governance.EntityIdtypeno test imports ittype EntityId = Brand<string, "EntityId">;The identifier of an entity of a group: opaque, a stable id.
A group of entities (0009-grc-groups): its controls are defined once and scoped to each entity. An entity is an opaque branded identifier; its ledger, evidence store, signing keys and secrets are references the host resolves for that entity alone, never values. An entity may have one parent (0012-grc-subtenants), so that the entities form a tree, held by EntityTree. The scope is a document that says which controls apply to which entity, and applicability is the pure function that answers it.
The model assumes nothing of how an entity's data is stored or kept apart from another's: a reference is an opaque name. A control scoped to an entity reaches its subtenants unless the nearest rule of an entity on the way up says otherwise.
import { entityId } from "./group.ts";
entityId("unit-a"); // { kind: "ok", value: "unit-a" }
entityId("Unit A"); // { kind: "err", error: "Unit A is not an entity id (lower-case words joined by - or .)" }governance.EntityIdtypeno test imports ittype EntityId = Brand<string, "EntityId">;The identifier of an entity of a group: opaque, a stable id.
governance.PortReftypeno test imports ittype PortRef = Brand<string, "PortRef">;A reference to a port of one entity (its ledger, its store, a key): a stable id the host resolves for that entity alone.
governance.SecretReftypeno test imports ittype SecretRef = Brand<string, "SecretRef">;A reference to a secret of one entity, never its value: secret: and a path of stable words.
governance.entityIdDecoderconstno test imports itconst entityIdDecoder: Decoder<EntityId>The decoder of an entity identifier.
entityIdDecoder("unit-a").kind; // "ok"governance.portRefDecoderconstno test imports itconst portRefDecoder: Decoder<PortRef>The decoder of a port reference.
portRefDecoder("ledger-a").kind; // "ok"governance.secretRefDecoderconstno test imports itconst secretRefDecoder: Decoder<SecretRef>The decoder of a secret reference: a value in its place is a decode error.
secretRefDecoder("a value").kind; // "err"governance.entityIdfunctionno test imports itfunction entityId(text: string): Result<EntityId, string>The entity identifier of text, or why it is not one.
governance.portReffunctionno test imports itfunction portRef(text: string): Result<PortRef, string>The port reference of text, or why it is not one.
portRef("ledger-unit-a"); // { kind: "ok", value: "ledger-unit-a" }governance.secretReffunctionno test imports itfunction secretRef(text: string): Result<SecretRef, string>The secret reference of text, or why it is not one (secret: and a path such as secret:unit-a/signing).
secretRef("secret:unit-a/signing"); // { kind: "ok", ... }
secretRef("hunter2"); // { kind: "err", ... }governance.entityDecoderconstno test imports itconst entityDecoder: Decoder<ObjectOf<{ id: Decoder<EntityId>; title: Decoder<string>; ledger: Decoder<PortRef>; store: Decoder<PortRef>; keys: Decoder<readonly PortRef[]>; secrets: Decoder<readonly SecretRef[]>; }, { parent: Decoder<EntityId>; }>>One entity of a group: its identifier, the references to its own ports and, optionally, its parent.
// entityDecoder({ id: "unit-a", title: "A", ledger: "l", store: "s", keys: [], secrets: [], parent: "unit" }).kind;governance.Entitytypeno test imports ittype Entity = Decoded<typeof entityDecoder>;An entity of a group.
governance.TreeFaulttypeno test imports ittype TreeFault =
| { readonly kind: "duplicate-entity"; readonly entity: EntityId }
| { readonly kind: "unknown-parent"; readonly entity: EntityId; readonly parent: EntityId }
| { readonly kind: "cycle"; readonly entities: readonly EntityId[] };Why the entities of a group are not a tree.
governance.treeFaultMessagefunctionno test imports itfunction treeFaultMessage(f: TreeFault): stringThe sentence of a tree fault.
// treeFaultMessage({ kind: "cycle", entities: [a, b] }); // "unit-a, unit-b are each other's ancestors"governance.entityGroupconstno test imports itconst entityGroup: DocumentKind<Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<EntityId>; title: Decoder<string>; ledger: Decoder<PortRef>; store: Decoder<PortRef>; keys: Decoder<readonly PortRef[]>; secrets: Decoder<readonly SecretRef[]>; }, { parent: Decoder<EntityId>; }>[]; } & { readonly [x: string]: unknown; }>A group of entities. The id of the document is the group's slug; the decoder refuses a parent the group does not hold and a cycle of parents.
// entityGroup.decode(document).kind; // "ok" for a group of entities with references as portsgovernance.EntityGrouptypeno test imports ittype EntityGroup = Decoded<typeof entityGroup.decode>;A group of entities.
governance.EntityTreeclassno test imports itclass EntityTreeThe entities of a group as a tree (0012-grc-subtenants): each entity has at most one parent and none is its own ancestor. Made only by entityTree.
| Member | Type | What it is |
|---|---|---|
group | Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<EntityId>; title: Decoder<string>; ledger: Decoder<PortRef>; store: Decoder<PortRef>; keys: Decoder<readonly PortRef[]>; secrets: Decoder<readonly SecretRef[]>; }, { parent: Decoder<EntityId>; }>[]; } & { readonly [x: string]: unknown; } | The group the tree is of. |
entities | readonly EntityId[] | Every entity, in the order of the identifiers. |
roots | readonly EntityId[] | The entities with no parent, in the order of the identifiers. |
parentOf | (entity: EntityId) => EntityId | undefined | The parent of entity, if it has one. |
childrenOf | (entity: EntityId) => readonly EntityId[] | The children of entity, in the order of the identifiers. |
ancestorsOf | (entity: EntityId) => readonly EntityId[] | The ancestors of entity from the nearest: its parent, then the parent's parent. |
descendantsOf | (entity: EntityId) => readonly EntityId[] | The descendants of entity, depth first, each level in the order of the identifiers. |
depthOf | (entity: EntityId) => number | The number of ancestors of entity. |
// const tree = entityTree(group); if (tree.kind === "ok") tree.value.ancestorsOf(subtenant); // [parent, grandparent]governance.entityTreefunctionno test imports itfunction entityTree(group: Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<EntityId>; title: Decoder<string>; ledger: Decoder<PortRef>; store: Decoder<PortRef>; keys: Decoder<readonly PortRef[]>; secrets: Decoder<readonly SecretRef[]>; }, { parent: Decoder<EntityId>; }>[]; } & { readonly [x: string]: unknown; }): Result<EntityTree, TreeFault>The tree of a group, or why its entities are not one: an entity held twice, a parent the group does not hold, a cycle.
// entityTree(group); // { kind: "ok", value: EntityTree } or { kind: "err", error: { kind: "cycle", entities: [...] } }governance.Selectortypeno test imports ittype Selector =
| { readonly kind: "all" }
| { readonly kind: "only"; readonly entities: readonly EntityId[] }
| { readonly kind: "except"; readonly entities: readonly EntityId[] };Which entities a rule of the scope reaches: all, only those listed, or all but those listed.
governance.selectorconstno test imports itconst selector: Decoder<Selector>The decoder of a selector.
selector({ kind: "only", entities: ["unit-a"] }).kind; // "ok"governance.controlScopeconstno test imports itconst controlScope: DocumentKind<Document & { readonly group: string; readonly rules: readonly ObjectOf<{ control: Decoder<string>; entities: Decoder<Selector>; }, { for: Decoder<EntityId>; inherit: Decoder<boolean>; note: Decoder<string>; }>[]; } & {}>The scoping of a group's controls: a rule names a control and the entities it applies to; a control no rule names applies to every entity. A rule may be the word of one entity on the control (for: it ranges over that entity and its descendants), and its selector stands for the descendants of the entities it names unless inherit is false (0012-grc-subtenants).
// controlScope.decode(document).kind;governance.ControlScopetypeno test imports ittype ControlScope = Decoded<typeof controlScope.decode>;A control scope.
governance.ScopeRuletypeno test imports ittype ScopeRule = ControlScope["rules"][number];A rule of a control scope.
governance.Applicabilitytypeno test imports ittype Applicability = "applies" | "not-applicable";Whether a control applies to an entity.
governance.ApplicabilityCelltypeno test imports ittype ApplicabilityCell = { readonly control: string; readonly entity: EntityId; readonly applicability: Applicability };One cell of the matrix: a control and an entity.
governance.appliesTofunctionno test imports itfunction appliesTo(scope: Document & { readonly group: string; readonly rules: readonly ObjectOf<{ control: Decoder<string>; entities: Decoder<Selector>; }, { for: Decoder<EntityId>; inherit: Decoder<boolean>; note: Decoder<string>; }>[]; } & {}, tree: EntityTree, control: string, entity: EntityId): ApplicabilityWhether control applies to entity by the scope: the nearest explicit rule decides. The rules that name the control are looked at on the way up from the entity (a rule for an ancestor counts where it inherits), then the rule of the group; a control no rule on the way names applies.
// appliesTo(scope, tree, "urn:grc:ex:1:A-1", unitA); // "applies" where no rule names the controlgovernance.applicabilityfunctionno test imports itfunction applicability(tree: EntityTree, scope: Document & { readonly group: string; readonly rules: readonly ObjectOf<{ control: Decoder<string>; entities: Decoder<Selector>; }, { for: Decoder<EntityId>; inherit: Decoder<boolean>; note: Decoder<string>; }>[]; } & {}, controls: readonly string[]): readonly ApplicabilityCell[]The applicability of every control to every entity of the tree, controls first, in the order given and the order of the identifiers.
// applicability(tree, scope, ["urn:grc:ex:1:A-1"]).map((c) => c.applicability);governance.exceptionCoversfunctionno test imports itfunction exceptionCovers(e: Document & { readonly excuses: ObjectOf<{ type: Decoder<"check" | "control" | "policy">; ref… (618 characters)function exceptionCovers(e: Document & { readonly excuses: ObjectOf<{ type: Decoder<"check" | "control" | "policy">; ref: Decoder<string>; }, Record<never, never>>; readonly subjects: readonly string[]; readonly reason: string; readonly approvedBy: string; readonly grantedAt: string; readonly expiresAt: string; } & { readonly acceptedRisk?: ObjectOf<{ owner: Decoder<string>; level: Decoder<"high" | "low" | "moderate" | "very-high" | "very-low">; reviewBy: Decoder<string>; }, Record<never, never>> | undefined; readonly inheritable?: boolean | undefined; }, tree: EntityTree, entity: EntityId, at: string): booleanWhether an exception excuses entity at at: it applies to the entity, or, only where it is inheritable, to an ancestor of it.
// exceptionCovers(exceptionOfParent, tree, subtenant, at); // false unless the exception says inheritable: truegovernance.ProblemRuletypeno test imports ittype ProblemRule =
| "entity/duplicate"
| "entity/unknown-parent"
| "entity/parent-cycle"
| "scope/unknown-entity"
| "scope/unknown-control"
| "scope/duplicate-control"
| "scope/duplicate-entity"
| "scope/outside-anchor";The rules of scopeProblems.
governance.ScopeProblemtypeno test imports ittype ScopeProblem = { readonly rule: ProblemRule; readonly id: string; readonly message: string };A problem of a group and its scope.
governance.scopeProblemsfunctionno test imports itfunction scopeProblems(group: Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<En… (638 characters)function scopeProblems(group: Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<EntityId>; title: Decoder<string>; ledger: Decoder<PortRef>; store: Decoder<PortRef>; keys: Decoder<readonly PortRef[]>; secrets: Decoder<readonly SecretRef[]>; }, { parent: Decoder<EntityId>; }>[]; } & { readonly [x: string]: unknown; }, scope: Document & { readonly group: string; readonly rules: readonly ObjectOf<{ control: Decoder<string>; entities: Decoder<Selector>; }, { for: Decoder<EntityId>; inherit: Decoder<boolean>; note: Decoder<string>; }>[]; } & {}, controls: readonly string[]): readonly ScopeProblem[]Every problem of a group and its scope, as data.
// scopeProblems(group, scope, controls).map((p) => p.rule); // [] for a sound scopeEntityIdtypetype EntityId = Brand<string, "EntityId">;The identifier of an entity of a group: opaque, a stable id.
PortReftypeno test imports ittype PortRef = Brand<string, "PortRef">;A reference to a port of one entity (its ledger, its store, a key): a stable id the host resolves for that entity alone.
SecretReftypeno test imports ittype SecretRef = Brand<string, "SecretRef">;A reference to a secret of one entity, never its value: secret: and a path of stable words.
entityIdDecoderconstno test imports itconst entityIdDecoder: Decoder<EntityId>The decoder of an entity identifier.
entityIdDecoder("unit-a").kind; // "ok"portRefDecoderconstno test imports itconst portRefDecoder: Decoder<PortRef>The decoder of a port reference.
portRefDecoder("ledger-a").kind; // "ok"secretRefDecoderconstno test imports itconst secretRefDecoder: Decoder<SecretRef>The decoder of a secret reference: a value in its place is a decode error.
secretRefDecoder("a value").kind; // "err"entityIdfunctionfunction entityId(text: string): Result<EntityId, string>The entity identifier of text, or why it is not one.
portReffunctionfunction portRef(text: string): Result<PortRef, string>The port reference of text, or why it is not one.
portRef("ledger-unit-a"); // { kind: "ok", value: "ledger-unit-a" }secretReffunctionfunction secretRef(text: string): Result<SecretRef, string>The secret reference of text, or why it is not one (secret: and a path such as secret:unit-a/signing).
secretRef("secret:unit-a/signing"); // { kind: "ok", ... }
secretRef("hunter2"); // { kind: "err", ... }entityDecoderconstconst entityDecoder: Decoder<ObjectOf<{ id: Decoder<EntityId>; title: Decoder<string>; ledger: Decoder<PortRef>; store: Decoder<PortRef>; keys: Decoder<readonly PortRef[]>; secrets: Decoder<readonly SecretRef[]>; }, { parent: Decoder<EntityId>; }>>One entity of a group: its identifier, the references to its own ports and, optionally, its parent.
// entityDecoder({ id: "unit-a", title: "A", ledger: "l", store: "s", keys: [], secrets: [], parent: "unit" }).kind;Entitytypetype Entity = Decoded<typeof entityDecoder>;An entity of a group.
TreeFaulttypetype TreeFault =
| { readonly kind: "duplicate-entity"; readonly entity: EntityId }
| { readonly kind: "unknown-parent"; readonly entity: EntityId; readonly parent: EntityId }
| { readonly kind: "cycle"; readonly entities: readonly EntityId[] };Why the entities of a group are not a tree.
treeFaultMessagefunctionno test imports itfunction treeFaultMessage(f: TreeFault): stringThe sentence of a tree fault.
// treeFaultMessage({ kind: "cycle", entities: [a, b] }); // "unit-a, unit-b are each other's ancestors"entityGroupconstconst entityGroup: DocumentKind<Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<EntityId>; title: Decoder<string>; ledger: Decoder<PortRef>; store: Decoder<PortRef>; keys: Decoder<readonly PortRef[]>; secrets: Decoder<readonly SecretRef[]>; }, { parent: Decoder<EntityId>; }>[]; } & { readonly [x: string]: unknown; }>A group of entities. The id of the document is the group's slug; the decoder refuses a parent the group does not hold and a cycle of parents.
// entityGroup.decode(document).kind; // "ok" for a group of entities with references as portsEntityGrouptypetype EntityGroup = Decoded<typeof entityGroup.decode>;A group of entities.
EntityTreeclassclass EntityTreeThe entities of a group as a tree (0012-grc-subtenants): each entity has at most one parent and none is its own ancestor. Made only by entityTree.
| Member | Type | What it is |
|---|---|---|
group | Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<EntityId>; title: Decoder<string>; ledger: Decoder<PortRef>; store: Decoder<PortRef>; keys: Decoder<readonly PortRef[]>; secrets: Decoder<readonly SecretRef[]>; }, { parent: Decoder<EntityId>; }>[]; } & { readonly [x: string]: unknown; } | The group the tree is of. |
entities | readonly EntityId[] | Every entity, in the order of the identifiers. |
roots | readonly EntityId[] | The entities with no parent, in the order of the identifiers. |
parentOf | (entity: EntityId) => EntityId | undefined | The parent of entity, if it has one. |
childrenOf | (entity: EntityId) => readonly EntityId[] | The children of entity, in the order of the identifiers. |
ancestorsOf | (entity: EntityId) => readonly EntityId[] | The ancestors of entity from the nearest: its parent, then the parent's parent. |
descendantsOf | (entity: EntityId) => readonly EntityId[] | The descendants of entity, depth first, each level in the order of the identifiers. |
depthOf | (entity: EntityId) => number | The number of ancestors of entity. |
// const tree = entityTree(group); if (tree.kind === "ok") tree.value.ancestorsOf(subtenant); // [parent, grandparent]entityTreefunctionfunction entityTree(group: Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<EntityId>; title: Decoder<string>; ledger: Decoder<PortRef>; store: Decoder<PortRef>; keys: Decoder<readonly PortRef[]>; secrets: Decoder<readonly SecretRef[]>; }, { parent: Decoder<EntityId>; }>[]; } & { readonly [x: string]: unknown; }): Result<EntityTree, TreeFault>The tree of a group, or why its entities are not one: an entity held twice, a parent the group does not hold, a cycle.
// entityTree(group); // { kind: "ok", value: EntityTree } or { kind: "err", error: { kind: "cycle", entities: [...] } }Selectortypeno test imports ittype Selector =
| { readonly kind: "all" }
| { readonly kind: "only"; readonly entities: readonly EntityId[] }
| { readonly kind: "except"; readonly entities: readonly EntityId[] };Which entities a rule of the scope reaches: all, only those listed, or all but those listed.
selectorconstno test imports itconst selector: Decoder<Selector>The decoder of a selector.
selector({ kind: "only", entities: ["unit-a"] }).kind; // "ok"controlScopeconstconst controlScope: DocumentKind<Document & { readonly group: string; readonly rules: readonly ObjectOf<{ control: Decoder<string>; entities: Decoder<Selector>; }, { for: Decoder<EntityId>; inherit: Decoder<boolean>; note: Decoder<string>; }>[]; } & {}>The scoping of a group's controls: a rule names a control and the entities it applies to; a control no rule names applies to every entity. A rule may be the word of one entity on the control (for: it ranges over that entity and its descendants), and its selector stands for the descendants of the entities it names unless inherit is false (0012-grc-subtenants).
// controlScope.decode(document).kind;ControlScopetypetype ControlScope = Decoded<typeof controlScope.decode>;A control scope.
ScopeRuletypeno test imports ittype ScopeRule = ControlScope["rules"][number];A rule of a control scope.
Applicabilitytypeno test imports ittype Applicability = "applies" | "not-applicable";Whether a control applies to an entity.
ApplicabilityCelltypeno test imports ittype ApplicabilityCell = { readonly control: string; readonly entity: EntityId; readonly applicability: Applicability };One cell of the matrix: a control and an entity.
appliesTofunctionfunction appliesTo(scope: Document & { readonly group: string; readonly rules: readonly ObjectOf<{ control: Decoder<string>; entities: Decoder<Selector>; }, { for: Decoder<EntityId>; inherit: Decoder<boolean>; note: Decoder<string>; }>[]; } & {}, tree: EntityTree, control: string, entity: EntityId): ApplicabilityWhether control applies to entity by the scope: the nearest explicit rule decides. The rules that name the control are looked at on the way up from the entity (a rule for an ancestor counts where it inherits), then the rule of the group; a control no rule on the way names applies.
// appliesTo(scope, tree, "urn:grc:ex:1:A-1", unitA); // "applies" where no rule names the controlapplicabilityfunctionfunction applicability(tree: EntityTree, scope: Document & { readonly group: string; readonly rules: readonly ObjectOf<{ control: Decoder<string>; entities: Decoder<Selector>; }, { for: Decoder<EntityId>; inherit: Decoder<boolean>; note: Decoder<string>; }>[]; } & {}, controls: readonly string[]): readonly ApplicabilityCell[]The applicability of every control to every entity of the tree, controls first, in the order given and the order of the identifiers.
// applicability(tree, scope, ["urn:grc:ex:1:A-1"]).map((c) => c.applicability);exceptionCoversfunctionfunction exceptionCovers(e: Document & { readonly excuses: ObjectOf<{ type: Decoder<"check" | "control" | "policy">; ref… (618 characters)function exceptionCovers(e: Document & { readonly excuses: ObjectOf<{ type: Decoder<"check" | "control" | "policy">; ref: Decoder<string>; }, Record<never, never>>; readonly subjects: readonly string[]; readonly reason: string; readonly approvedBy: string; readonly grantedAt: string; readonly expiresAt: string; } & { readonly acceptedRisk?: ObjectOf<{ owner: Decoder<string>; level: Decoder<"high" | "low" | "moderate" | "very-high" | "very-low">; reviewBy: Decoder<string>; }, Record<never, never>> | undefined; readonly inheritable?: boolean | undefined; }, tree: EntityTree, entity: EntityId, at: string): booleanWhether an exception excuses entity at at: it applies to the entity, or, only where it is inheritable, to an ancestor of it.
// exceptionCovers(exceptionOfParent, tree, subtenant, at); // false unless the exception says inheritable: trueProblemRuletypeno test imports ittype ProblemRule =
| "entity/duplicate"
| "entity/unknown-parent"
| "entity/parent-cycle"
| "scope/unknown-entity"
| "scope/unknown-control"
| "scope/duplicate-control"
| "scope/duplicate-entity"
| "scope/outside-anchor";The rules of scopeProblems.
ScopeProblemtypeno test imports ittype ScopeProblem = { readonly rule: ProblemRule; readonly id: string; readonly message: string };A problem of a group and its scope.
scopeProblemsfunctionfunction scopeProblems(group: Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<En… (638 characters)function scopeProblems(group: Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<EntityId>; title: Decoder<string>; ledger: Decoder<PortRef>; store: Decoder<PortRef>; keys: Decoder<readonly PortRef[]>; secrets: Decoder<readonly SecretRef[]>; }, { parent: Decoder<EntityId>; }>[]; } & { readonly [x: string]: unknown; }, scope: Document & { readonly group: string; readonly rules: readonly ObjectOf<{ control: Decoder<string>; entities: Decoder<Selector>; }, { for: Decoder<EntityId>; inherit: Decoder<boolean>; note: Decoder<string>; }>[]; } & {}, controls: readonly string[]): readonly ScopeProblem[]Every problem of a group and its scope, as data.
// scopeProblems(group, scope, controls).map((p) => p.rule); // [] for a sound scope