IF Commons GitHub

governance/ids

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-integrations-governance FR-001, 0002-integrations-governance FR-002, 0002-integrations-governance FR-003

The identities of Integrations (commons integrations 0002-integrations-governance): each an opaque (branded) string that only a smart constructor makes, so that a value that is not a connector id, a standard urn, a credential reference, a digest or an instant cannot reach a function that wants one (parse, do not validate).

brand is the one cast of the library. A refusal says what was expected and never repeats the input of a credential reference, because a mistaken reference may be the value itself.

Source: commons/integrations/src/governance/ids.ts

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

IdErrortypeno test imports it
type IdError = { readonly kind: "id"; readonly what: string; readonly expected: string; readonly input?: string };

Why a text is not an identity: what it was to be, and the input where the input is an identity and not a secret.

brandfunctionno test imports it
function brand<B extends string, T extends string | number = string>(value: T): Brand<T, B>

The one cast of the library: a text that a smart constructor has checked.

ConnectorIdtype
type ConnectorId = Brand<string, "ConnectorId">;

The id of a connector: ^[a-z][a-z0-9-]{1,39}$.

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

parseConnectorIdconst
const parseConnectorId: (text: string) => Result<ConnectorId, IdError>

Reads the id of a connector: a lower-case name of 2 to 40 characters.

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

PartnerIdtypeno test imports it
type PartnerId = Brand<string, "PartnerId">;

The id of a trading partner.

parsePartnerIdconst
const parsePartnerId: (text: string) => Result<PartnerId, IdError>

Reads the id of a partner: a lower-case name of 2 to 64 characters.

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

AgreementIdtype
type AgreementId = Brand<string, "AgreementId">;

The id of an exchange agreement.

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

parseAgreementIdconst
const parseAgreementId: (text: string) => Result<AgreementId, IdError>

Reads the id of an agreement: a lower-case name of 2 to 80 characters.

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

StandardUrntypeno test imports it
type StandardUrn = Brand<string, "StandardUrn">;

The urn of a standard: urn:standard:<issuer>:<name>:<version> (commons 0018-standards-first FR-006).

parseStandardUrnconst
const parseStandardUrn: (text: string) => Result<StandardUrn, IdError>

Reads the URN of a standard that a message is written to.

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

StandardPartstypeno test imports it
type StandardParts = { readonly issuer: string; readonly name: string; readonly version: string };

The parts of a standard's urn.

partsOfUrnfunction
function partsOfUrn(urn: StandardUrn): StandardParts

The issuer, name and version a urn names.

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

standardUrnconst
const standardUrn: (p: StandardParts) => Result<StandardUrn, IdError>

A urn built from its parts.

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

CredentialReftypeno test imports it
type CredentialRef = Brand<string, "CredentialRef">;

A reference to a secret in a vault: vault://<store>/<name>. Never the secret; a refusal never repeats its input.

parseCredentialRefconst
const parseCredentialRef: (text: string) => Result<CredentialRef, IdError>

Reads a reference to a credential, never the credential itself.

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

Sha256typeno test imports it
type Sha256 = Brand<string, "Sha256">;

A SHA-256 digest as 64 lower-case hexadecimal digits.

parseSha256const
const parseSha256: (text: string) => Result<Sha256, IdError>

Reads a SHA-256 digest: 64 lower-case hexadecimal digits.

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

Instanttype
type Instant = Brand<string, "Instant">;

A moment in UTC as an ISO 8601 text with a Z: 2026-11-20T10:00:00.000Z.

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

parseInstantfunction
function parseInstant(text: string): Result<Instant, IdError>

Reads an instant as an ISO 8601 timestamp in UTC.

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

instantOfconst
const instantOf: (ms: number) => Instant

The instant of a number of milliseconds since the epoch.

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

msOfconst
const msOf: (at: Instant) => number

The milliseconds since the epoch of an instant.

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

Durationtypeno test imports it
type Duration = Brand<number, "Duration">;

A length of time in whole milliseconds, positive.

parseDurationfunction
function parseDuration(text: string): Result<Duration, IdError>

A duration from 15m, 6h, 1d or 30s: a whole number and one unit.

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

durationMsconst
const durationMs: (d: Duration) => number

The milliseconds of a duration, as a duration (for arithmetic that stays positive).

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

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