gdc-common-utils-ts 2.4.0 → 2.5.0

package/README.md

@@ -243,11 +243,18 @@ const lookupMultihash = encodeMultibaseSha3('DL|US-CA|D1234567');
 const blockchainAssetId = buildRawCidV1FromUtf8String('DL|US-CA|D1234567');
 ```
 
-Individual lookup tokens keep the identifier type and jurisdiction separate:
-`org.hl7.terminology.CodeSystem.v2-0203.NN|ES|12345678Z`. Import
-`buildIndividualIdentifierLedgerAssetId(...)` when a GW must derive the opaque
-SHA3-384 `urn:multibase` key used by the subject-identifier ledger. The raw
-identifier must never be written to that ledger.
+Canonical Subject-collection lookup tokens use `codingSystem|codeValue`, for
+example `org.hl7.terminology.CodeSystem.v2-0203.NN.ES|12345678Z` or
+`urn:iso:std:iso:11784-11785|981020000123456`. Import
+`buildSubjectIdentifierAssetId(...)` when a GW must derive the opaque SHA3-384
+`urn:multibase` key used by the distributed subject index. The semantic
+`Person`/`Animal` entry keeps the private claims and its `sameAs` points to the
+stable public unified card; the raw identifier must never be written to the
+ledger.
+
+`buildIndividualIdentifierLedgerAssetId(...)` remains the older
+type/jurisdiction/value compatibility helper. Do not use its former
+`Organization.sameAs` convention for new Subject collection writes.
 
 Both helpers hash the exact UTF-8 bytes supplied by the caller. Identifier,
 FHIR-token or JSON canonicalization belongs to the contract that owns the

package/dist/constants/schemaorg.d.ts

@@ -175,6 +175,8 @@ export declare enum ClaimsPersonSchemaorg {
     identifier = "org.schema.Person.identifier",// the URN (composed by the provider)
     identifierType = "org.schema.Person.identifier.additionalType",// retrieved from a form
     identifierValue = "org.schema.Person.identifier.value",// retrieved from a form
+    /** Stable public unified-card URI shared by private identity representations. */
+    sameAs = "org.schema.Person.sameAs",
     /** ICAO transliteration of official given name (including middlenames), family name and addtional surname */
     name = "org.schema.Person.name",
     memberOf = "org.schema.Person.memberOf",// for employees

package/dist/constants/schemaorg.js

@@ -183,6 +183,8 @@ export var ClaimsPersonSchemaorg;
     ClaimsPersonSchemaorg["identifier"] = "org.schema.Person.identifier";
     ClaimsPersonSchemaorg["identifierType"] = "org.schema.Person.identifier.additionalType";
     ClaimsPersonSchemaorg["identifierValue"] = "org.schema.Person.identifier.value";
+    /** Stable public unified-card URI shared by private identity representations. */
+    ClaimsPersonSchemaorg["sameAs"] = "org.schema.Person.sameAs";
     /** ICAO transliteration of official given name (including middlenames), family name and addtional surname */
     ClaimsPersonSchemaorg["name"] = "org.schema.Person.name";
     ClaimsPersonSchemaorg["memberOf"] = "org.schema.Person.memberOf";

package/dist/models/device-license.d.ts

@@ -161,7 +161,11 @@ export interface DeviceLicense {
     maxDevices?: number;
     /** All DCR installations bound to this user/member seat. */
     deviceBindings?: DeviceBinding[];
-    /** Identity-provider subject that first activated this seat. */
+    /**
+     * Stable private actor identifier:
+     * `urn:multibase:<hash(normalized email or phone)>:<professional|personal>`.
+     * Portal DIDs, IdP subjects, wallets and DCR clients bind to this value but do not define it.
+     */
     activatedBy?: string;
     /**
      * Optional, pre-defined restrictions on which devices are allowed to activate this license.

package/dist/models/index.d.ts

@@ -51,6 +51,7 @@ export * from './resource-document';
 export * from './relationship-access';
 export * from './response';
 export * from './subject-identifier-ledger';
+export * from './subject-identity';
 export * from './subject-identity-binding';
 export * from './terminology';
 export * from './urlPath';

package/dist/models/index.js

@@ -51,6 +51,7 @@ export * from './resource-document.js';
 export * from './relationship-access.js';
 export * from './response.js';
 export * from './subject-identifier-ledger.js';
+export * from './subject-identity.js';
 export * from './subject-identity-binding.js';
 export * from './terminology.js';
 export * from './urlPath.js';

package/dist/models/subject-identifier-ledger.d.ts

@@ -6,11 +6,22 @@ export type SubjectIdentifierProviderPointer = Readonly<{
     /** Bare DNS domain: no URL scheme, path, DID or tenant identifier. */
     url: string;
 }>;
-/** Ledger payload. It deliberately contains no subject DID or raw identifier. */
+/** Public unified-card pointer resolved from an exact known identifier. */
+export type SubjectIdentifierCardPointer = Readonly<{
+    identifier: Readonly<{
+        value: string;
+    }>;
+    subjectKind: 'person' | 'animal' | 'property';
+}>;
+/** Ledger payload. It deliberately contains no raw private identifier. */
 export type SubjectIdentifierLedgerPayload = Readonly<{
+    card: SubjectIdentifierCardPointer;
     provider: SubjectIdentifierProviderPointer;
 }>;
-/** One individual/animal bundle entry expanded into one write per `sameAs` alias. */
+/**
+ * @deprecated Parse canonical Person/Animal/Place Bundle entries with
+ * `readSubjectIdentityBundleEntry` instead. Kept for 2.x compatibility only.
+ */
 export type SubjectIdentifierLedgerBundleEntry = Readonly<{
     sameAs: string | readonly string[];
 }>;

package/dist/models/subject-identity.d.ts

@@ -0,0 +1,36 @@
+import type { BundleEntry } from './bundle';
+/** Subject categories supported by the neutral identity collection. */
+export type SubjectKind = 'person' | 'animal' | 'property';
+/** Semantic resource types stored inside the neutral Subject collection. */
+export type SubjectIdentityResourceType = 'Person' | 'Animal' | 'Place';
+/** Exact private identifier input linked to one public unified card. */
+export type SubjectIdentityInput = Readonly<{
+    subjectKind: SubjectKind;
+    cardId: string;
+    /** Canonical identifier type/coding system. */
+    codingSystem: string;
+    /** ISO jurisdiction for scoped identifiers; empty for a global identifier. */
+    jurisdiction: string;
+    codeValue: string;
+    /** Additional encrypted claims; canonical identifier and sameAs keys cannot be overridden. */
+    additionalClaims?: Readonly<Record<string, unknown>>;
+}>;
+/** Normalized association recovered from one Subject collection entry. */
+export type SubjectIdentityAssociation = SubjectIdentityInput & Readonly<{
+    resourceType: SubjectIdentityResourceType;
+    assetId: string;
+}>;
+/** Bundle entry used to write one semantic identity into the Subject collection. */
+export type SubjectIdentityBundleEntry = BundleEntry & Readonly<{
+    type: 'Subject-identity-link-v1.0';
+    resource: NonNullable<BundleEntry['resource']> & Readonly<{
+        resourceType: SubjectIdentityResourceType;
+        meta: {
+            claims: Record<string, unknown>;
+        };
+    }>;
+    request: {
+        method: 'POST';
+        url: 'Subject';
+    };
+}>;

package/dist/models/subject-identity.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/actor-identifier.d.ts

@@ -0,0 +1,36 @@
+/** Cross-portal actor classes. These are intentionally broader than job roles. */
+export declare const StableActorRoles: Readonly<{
+    readonly Professional: "professional";
+    readonly Personal: "personal";
+}>;
+export type StableActorRole = typeof StableActorRoles[keyof typeof StableActorRoles];
+export type StableActorContactKind = 'email' | 'phone';
+/**
+ * Builds the private, stable actor identifier shared by independent portals.
+ *
+ * Wire format: `urn:multibase:<multibase(multihash(SHA3-256, normalized-contact))>:<role>`.
+ * Examples end in `:professional` or `:personal`; the clear email/phone is
+ * never embedded. A portal-specific `did:web`, IdP `sub`, wallet and DCR
+ * `client_id` are bindings to this identifier, not replacements for it.
+ *
+ * Email is trimmed, stripped of `mailto:` and lower-cased. Phone is stripped
+ * of `tel:` and formatting while preserving an E.164 leading `+`.
+ */
+export declare function buildStableActorIdentifier(input: {
+    contactKind: StableActorContactKind;
+    contact: string;
+    role: StableActorRole;
+}): string;
+/**
+ * Builds a portal-specific DID binding that carries the stable actor payload.
+ * The portal root can change while the final actor payload remains identical.
+ */
+export declare function buildPortalActorDidWeb(input: {
+    portalDidWeb: string;
+    actorIdentifier: string;
+}): string;
+/**
+ * Extracts the stable actor URN from a canonical GDC portal actor DID.
+ * This is extraction, not reversal of the contact hash.
+ */
+export declare function stableActorIdentifierFromDidWeb(didWeb: string): string;

package/dist/utils/actor-identifier.js

@@ -0,0 +1,58 @@
+import { normalizePhone } from './consent.js';
+import { multibase58MultihashSha3_256 } from './same-as.js';
+/** Cross-portal actor classes. These are intentionally broader than job roles. */
+export const StableActorRoles = Object.freeze({
+    Professional: 'professional',
+    Personal: 'personal',
+});
+/**
+ * Builds the private, stable actor identifier shared by independent portals.
+ *
+ * Wire format: `urn:multibase:<multibase(multihash(SHA3-256, normalized-contact))>:<role>`.
+ * Examples end in `:professional` or `:personal`; the clear email/phone is
+ * never embedded. A portal-specific `did:web`, IdP `sub`, wallet and DCR
+ * `client_id` are bindings to this identifier, not replacements for it.
+ *
+ * Email is trimmed, stripped of `mailto:` and lower-cased. Phone is stripped
+ * of `tel:` and formatting while preserving an E.164 leading `+`.
+ */
+export function buildStableActorIdentifier(input) {
+    const role = String(input.role || '').trim();
+    if (!Object.values(StableActorRoles).includes(role)) {
+        throw new Error('Stable actor role must be professional or personal.');
+    }
+    const rawContact = String(input.contact || '').trim();
+    const normalizedContact = input.contactKind === 'email'
+        ? rawContact.replace(/^mailto:/i, '').replace(/\s+/g, '').toLowerCase()
+        : normalizePhone(rawContact.replace(/^tel:/i, ''));
+    if (!normalizedContact) {
+        throw new Error(`Stable actor ${input.contactKind} is required.`);
+    }
+    return `urn:multibase:${multibase58MultihashSha3_256(normalizedContact)}:${role}`;
+}
+/**
+ * Builds a portal-specific DID binding that carries the stable actor payload.
+ * The portal root can change while the final actor payload remains identical.
+ */
+export function buildPortalActorDidWeb(input) {
+    const portalDidWeb = String(input.portalDidWeb || '').trim();
+    const match = /^urn:multibase:(z[^:]+):(professional|personal)$/.exec(String(input.actorIdentifier || '').trim());
+    if (!portalDidWeb.startsWith('did:web:')) {
+        throw new Error('Portal actor binding requires a did:web root.');
+    }
+    if (!match) {
+        throw new Error('Portal actor binding requires a stable actor URN.');
+    }
+    return `${portalDidWeb}:actor:multibase:${match[1]}:${match[2]}`;
+}
+/**
+ * Extracts the stable actor URN from a canonical GDC portal actor DID.
+ * This is extraction, not reversal of the contact hash.
+ */
+export function stableActorIdentifierFromDidWeb(didWeb) {
+    const match = /:actor:multibase:(z[^:]+):(professional|personal)(?::|$)/.exec(String(didWeb || '').trim());
+    if (!match) {
+        throw new Error('DID does not contain a canonical GDC actor binding.');
+    }
+    return `urn:multibase:${match[1]}:${match[2]}`;
+}

package/dist/utils/index.d.ts

@@ -102,8 +102,10 @@ export * from './permission-templates';
 export * from './smart-scope';
 export * from './service-act-reasons';
 export * from './same-as';
+export * from './subject-identity';
 export * from './subject-identity-binding';
 export * from './activation-request';
+export * from './actor-identifier';
 export * from './vp-token';
 export * from './vital-sign-day-batch';
 export * from './wallet-mem';

package/dist/utils/index.js

@@ -102,8 +102,10 @@ export * from './permission-templates.js';
 export * from './smart-scope.js';
 export * from './service-act-reasons.js';
 export * from './same-as.js';
+export * from './subject-identity.js';
 export * from './subject-identity-binding.js';
 export * from './activation-request.js';
+export * from './actor-identifier.js';
 export * from './vp-token.js';
 export * from './vital-sign-day-batch.js';
 export * from './wallet-mem.js';

package/dist/utils/subject-identity.d.ts

@@ -0,0 +1,30 @@
+import type { BundleEntry } from '../models/bundle';
+import type { SubjectIdentityAssociation, SubjectIdentityBundleEntry, SubjectIdentityInput } from '../models/subject-identity';
+/**
+ * Builds the exact UTF-8 token used by the distributed Subject lookup.
+ *
+ * Contract:
+ * - canonical input is `codingSystem|jurisdiction-or-empty|codeValue`;
+ * - an empty jurisdiction is explicit, producing `||` for global identifiers;
+ * - values use the existing individual-identifier uppercase normalization;
+ * - `|` is forbidden in every component to keep the encoding unambiguous.
+ */
+export declare function buildSubjectIdentifierToken(input: Pick<SubjectIdentityInput, 'codingSystem' | 'jurisdiction' | 'codeValue'>): string;
+/**
+ * Returns `urn:multibase:<base58btc multihash>` using SHA3-384.
+ *
+ * The value is a deterministic public lookup key, not an authorization proof.
+ * The raw identifier remains in the encrypted Subject collection and is never
+ * included in the Fabric payload.
+ */
+export declare function buildSubjectIdentifierAssetId(input: Pick<SubjectIdentityInput, 'codingSystem' | 'jurisdiction' | 'codeValue'>): string;
+/**
+ * Builds one semantic identity resource for the neutral Subject collection.
+ *
+ * `sameAs` always identifies the stable public unified card. The private
+ * coding system and code value remain claims of Person, Animal or Place; the
+ * collection name never replaces that semantic resource type.
+ */
+export declare function buildSubjectIdentityBundleEntry(input: SubjectIdentityInput): SubjectIdentityBundleEntry;
+/** Reads and validates one Person/Animal/Place entry from the Subject collection. */
+export declare function readSubjectIdentityBundleEntry(entry: BundleEntry): SubjectIdentityAssociation;

package/dist/utils/subject-identity.js

@@ -0,0 +1,127 @@
+import { UrnPrefixes } from '../constants/urn.js';
+import { encodeMultibaseSha3 } from './multibasehash.js';
+import { normalizeIndividualIdentifierType } from './individual-identifier.js';
+const SUBJECT_RESOURCE_BY_KIND = {
+    person: 'Person',
+    animal: 'Animal',
+    property: 'Place',
+};
+const SUBJECT_KIND_BY_RESOURCE = {
+    Person: 'person',
+    Animal: 'animal',
+    Place: 'property',
+};
+const STABLE_CARD_ID_PATTERN = /^(?:did|urn|https):\S+$/i;
+const ISO_3166_JURISDICTION_PATTERN = /^[A-Z]{2}(?:-[A-Z0-9]{1,3})?$/;
+/**
+ * Builds the exact UTF-8 token used by the distributed Subject lookup.
+ *
+ * Contract:
+ * - canonical input is `codingSystem|jurisdiction-or-empty|codeValue`;
+ * - an empty jurisdiction is explicit, producing `||` for global identifiers;
+ * - values use the existing individual-identifier uppercase normalization;
+ * - `|` is forbidden in every component to keep the encoding unambiguous.
+ */
+export function buildSubjectIdentifierToken(input) {
+    const codingSystem = normalizeTokenPart(input.codingSystem, 'codingSystem');
+    const jurisdiction = normalizeJurisdiction(input.jurisdiction);
+    const codeValue = normalizeTokenPart(input.codeValue, 'codeValue').toUpperCase();
+    return `${codingSystem}|${jurisdiction}|${codeValue}`;
+}
+/**
+ * Returns `urn:multibase:<base58btc multihash>` using SHA3-384.
+ *
+ * The value is a deterministic public lookup key, not an authorization proof.
+ * The raw identifier remains in the encrypted Subject collection and is never
+ * included in the Fabric payload.
+ */
+export function buildSubjectIdentifierAssetId(input) {
+    return `${UrnPrefixes.Multibase}${encodeMultibaseSha3(buildSubjectIdentifierToken(input), 384)}`;
+}
+/**
+ * Builds one semantic identity resource for the neutral Subject collection.
+ *
+ * `sameAs` always identifies the stable public unified card. The private
+ * coding system and code value remain claims of Person, Animal or Place; the
+ * collection name never replaces that semantic resource type.
+ */
+export function buildSubjectIdentityBundleEntry(input) {
+    const resourceType = SUBJECT_RESOURCE_BY_KIND[input.subjectKind];
+    if (!resourceType)
+        throw new TypeError(`Unsupported subject kind: ${input.subjectKind}`);
+    const cardId = input.cardId.trim();
+    if (!STABLE_CARD_ID_PATTERN.test(cardId)) {
+        throw new TypeError('Subject identity cardId must be a stable URI (did:, urn: or https:).');
+    }
+    const codingSystem = input.subjectKind === 'person'
+        ? normalizeIndividualIdentifierType(input.codingSystem)
+        : normalizeTokenPart(input.codingSystem, 'codingSystem');
+    const jurisdiction = normalizeJurisdiction(input.jurisdiction);
+    if (input.subjectKind === 'person' && !jurisdiction) {
+        throw new TypeError('Person identity jurisdiction is required.');
+    }
+    const codeValue = normalizeTokenPart(input.codeValue, 'codeValue').toUpperCase();
+    const assetId = buildSubjectIdentifierAssetId({ codingSystem, jurisdiction, codeValue });
+    const claimPrefix = `org.schema.${resourceType}`;
+    return {
+        id: assetId,
+        fullUrl: assetId,
+        type: 'Subject-identity-link-v1.0',
+        resource: {
+            resourceType,
+            id: assetId,
+            meta: {
+                claims: {
+                    ...(input.additionalClaims || {}),
+                    [`${claimPrefix}.identifier`]: assetId,
+                    [`${claimPrefix}.identifier.additionalType`]: codingSystem,
+                    [`${claimPrefix}.identifier.jurisdiction`]: jurisdiction,
+                    [`${claimPrefix}.identifier.value`]: codeValue,
+                    [`${claimPrefix}.sameAs`]: cardId,
+                },
+            },
+        },
+        request: { method: 'POST', url: 'Subject' },
+    };
+}
+/** Reads and validates one Person/Animal/Place entry from the Subject collection. */
+export function readSubjectIdentityBundleEntry(entry) {
+    const resourceType = String(entry.resource?.resourceType || '');
+    const subjectKind = SUBJECT_KIND_BY_RESOURCE[resourceType];
+    if (!subjectKind) {
+        throw new TypeError(`Unsupported Subject identity resourceType: ${resourceType || '(missing)'}; expected Person, Animal or Place.`);
+    }
+    const claims = entry.resource?.meta?.claims || {};
+    const prefix = `org.schema.${resourceType}`;
+    const cardId = String(claims[`${prefix}.sameAs`] || '').trim();
+    const codingSystem = String(claims[`${prefix}.identifier.additionalType`] || '').trim();
+    const jurisdiction = normalizeJurisdiction(String(claims[`${prefix}.identifier.jurisdiction`] || ''));
+    const codeValue = String(claims[`${prefix}.identifier.value`] || '').trim();
+    if (!STABLE_CARD_ID_PATTERN.test(cardId))
+        throw new TypeError('Subject identity sameAs must contain one stable card URI.');
+    if (subjectKind === 'person' && !jurisdiction)
+        throw new TypeError('Person identity jurisdiction is required.');
+    const assetId = buildSubjectIdentifierAssetId({ codingSystem, jurisdiction, codeValue });
+    const claimedAssetId = String(claims[`${prefix}.identifier`] || entry.resource?.id || entry.id || '').trim();
+    if (claimedAssetId && claimedAssetId !== assetId) {
+        throw new TypeError('Subject identity identifier does not match codingSystem|jurisdiction|codeValue.');
+    }
+    return { subjectKind, resourceType, cardId, codingSystem, jurisdiction, codeValue, assetId };
+}
+function normalizeTokenPart(value, field) {
+    const normalized = String(value || '').trim().normalize('NFKC');
+    if (!normalized)
+        throw new TypeError(`${field} is required`);
+    if (normalized.includes('|'))
+        throw new TypeError(`${field} must not contain the '|' delimiter`);
+    return normalized;
+}
+function normalizeJurisdiction(value) {
+    const normalized = String(value || '').trim().normalize('NFKC').toUpperCase();
+    if (normalized.includes('|'))
+        throw new TypeError("jurisdiction must not contain the '|' delimiter");
+    if (normalized && !ISO_3166_JURISDICTION_PATTERN.test(normalized)) {
+        throw new TypeError(`Invalid ISO 3166 jurisdiction: ${value}`);
+    }
+    return normalized;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "publishConfig": {
     "access": "public"
   },