IF Commons GitHub

governance/group

Written to: 5 requirements: 5 proved, 0 partly, 0 failing, 0 with no test recorded. 0009-grc-groups FR-001, 0009-grc-groups FR-002, 0009-grc-groups FR-003, 0009-grc-groups FR-004, 0009-grc-groups FR-005

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 .)" }

Source: commons/grc/src/governance/group.ts

17 of 60 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

governance.EntityIdtypeno test imports it
type EntityId = Brand<string, "EntityId">;

The identifier of an entity of a group: opaque, a stable id.

governance.PortReftypeno test imports it
type 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 it
type 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 it
const entityIdDecoder: Decoder<EntityId>

The decoder of an entity identifier.

entityIdDecoder("unit-a").kind; // "ok"
governance.portRefDecoderconstno test imports it
const portRefDecoder: Decoder<PortRef>

The decoder of a port reference.

portRefDecoder("ledger-a").kind; // "ok"
governance.secretRefDecoderconstno test imports it
const 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 it
function entityId(text: string): Result<EntityId, string>

The entity identifier of text, or why it is not one.

governance.portReffunctionno test imports it
function 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 it
function 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 it
const 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 it
type Entity = Decoded<typeof entityDecoder>;

An entity of a group.

governance.TreeFaulttypeno test imports it
type 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 it
function treeFaultMessage(f: TreeFault): string

The sentence of a tree fault.

// treeFaultMessage({ kind: "cycle", entities: [a, b] }); // "unit-a, unit-b are each other's ancestors"
governance.entityGroupconstno test imports it
const 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 ports
governance.EntityGrouptypeno test imports it
type EntityGroup = Decoded<typeof entityGroup.decode>;

A group of entities.

governance.EntityTreeclassno test imports it
class EntityTree

The 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.

MemberTypeWhat it is
groupDocument & { 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.
entitiesreadonly EntityId[]Every entity, in the order of the identifiers.
rootsreadonly EntityId[]The entities with no parent, in the order of the identifiers.
parentOf(entity: EntityId) => EntityId | undefinedThe 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) => numberThe number of ancestors of entity.
// const tree = entityTree(group); if (tree.kind === "ok") tree.value.ancestorsOf(subtenant); // [parent, grandparent]
governance.entityTreefunctionno test imports it
function 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 it
type 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 it
const selector: Decoder<Selector>

The decoder of a selector.

selector({ kind: "only", entities: ["unit-a"] }).kind; // "ok"
governance.controlScopeconstno test imports it
const 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 it
type ControlScope = Decoded<typeof controlScope.decode>;

A control scope.

governance.ScopeRuletypeno test imports it
type ScopeRule = ControlScope["rules"][number];

A rule of a control scope.

governance.Applicabilitytypeno test imports it
type Applicability = "applies" | "not-applicable";

Whether a control applies to an entity.

governance.ApplicabilityCelltypeno test imports it
type ApplicabilityCell = { readonly control: string; readonly entity: EntityId; readonly applicability: Applicability };

One cell of the matrix: a control and an entity.

governance.appliesTofunctionno test imports it
function 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): Applicability

Whether 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 control
governance.applicabilityfunctionno test imports it
function 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 it
function 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): boolean

Whether 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: true
governance.ProblemRuletypeno test imports it
type 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 it
type ScopeProblem = { readonly rule: ProblemRule; readonly id: string; readonly message: string };

A problem of a group and its scope.

governance.scopeProblemsfunctionno test imports it
function 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
EntityIdtype
type EntityId = Brand<string, "EntityId">;

The identifier of an entity of a group: opaque, a stable id.

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

PortReftypeno test imports it
type 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 it
type 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 it
const entityIdDecoder: Decoder<EntityId>

The decoder of an entity identifier.

entityIdDecoder("unit-a").kind; // "ok"
portRefDecoderconstno test imports it
const portRefDecoder: Decoder<PortRef>

The decoder of a port reference.

portRefDecoder("ledger-a").kind; // "ok"
secretRefDecoderconstno test imports it
const secretRefDecoder: Decoder<SecretRef>

The decoder of a secret reference: a value in its place is a decode error.

secretRefDecoder("a value").kind; // "err"
entityIdfunction
function entityId(text: string): Result<EntityId, string>

The entity identifier of text, or why it is not one.

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

portReffunction
function 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" }

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

secretReffunction
function 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", ... }

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

entityDecoderconst
const 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;

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

Entitytype
type Entity = Decoded<typeof entityDecoder>;

An entity of a group.

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

TreeFaulttype
type 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.

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

treeFaultMessagefunctionno test imports it
function treeFaultMessage(f: TreeFault): string

The sentence of a tree fault.

// treeFaultMessage({ kind: "cycle", entities: [a, b] }); // "unit-a, unit-b are each other's ancestors"
entityGroupconst
const 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 ports

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

EntityGrouptype
type EntityGroup = Decoded<typeof entityGroup.decode>;

A group of entities.

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

EntityTreeclass
class EntityTree

The 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.

MemberTypeWhat it is
groupDocument & { 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.
entitiesreadonly EntityId[]Every entity, in the order of the identifiers.
rootsreadonly EntityId[]The entities with no parent, in the order of the identifiers.
parentOf(entity: EntityId) => EntityId | undefinedThe 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) => numberThe number of ancestors of entity.
// const tree = entityTree(group); if (tree.kind === "ok") tree.value.ancestorsOf(subtenant); // [parent, grandparent]

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

entityTreefunction
function 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: [...] } }

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

Selectortypeno test imports it
type 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 it
const selector: Decoder<Selector>

The decoder of a selector.

selector({ kind: "only", entities: ["unit-a"] }).kind; // "ok"
controlScopeconst
const 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;

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

ControlScopetype
type ControlScope = Decoded<typeof controlScope.decode>;

A control scope.

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

ScopeRuletypeno test imports it
type ScopeRule = ControlScope["rules"][number];

A rule of a control scope.

Applicabilitytypeno test imports it
type Applicability = "applies" | "not-applicable";

Whether a control applies to an entity.

ApplicabilityCelltypeno test imports it
type ApplicabilityCell = { readonly control: string; readonly entity: EntityId; readonly applicability: Applicability };

One cell of the matrix: a control and an entity.

appliesTofunction
function 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): Applicability

Whether 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 control

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

applicabilityfunction
function 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);

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

exceptionCoversfunction
function 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): boolean

Whether 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: true

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

ProblemRuletypeno test imports it
type 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 it
type ScopeProblem = { readonly rule: ProblemRule; readonly id: string; readonly message: string };

A problem of a group and its scope.

scopeProblemsfunction
function 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

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.