gdc-common-utils-ts 2.3.1 → 2.3.2

package/dist/utils/bundle-entry-editor.js

@@ -27,6 +27,10 @@ export class BundleEntryEditor {
         switch (normalized) {
             case BundleEditableResourceTypes.employee:
                 return this.asEmployee();
+            case BundleEditableResourceTypes.consent:
+                return this.asConsent();
+            case BundleEditableResourceTypes.relatedPerson:
+                return this.asRelatedPerson();
             case BundleEditableResourceTypes.vitalSign:
                 return this.asVitalSign();
             case BundleEditableResourceTypes.observation:
@@ -71,6 +75,22 @@ export class BundleEntryEditor {
         }
         return createRegisteredBundleEntryEditor(BundleEditableResourceTypes.employee, this.bundleEditor, this.entryIndex);
     }
+    /** Opens the current entry as one Consent permission editor. */
+    asConsent() {
+        const entry = this.getMutableEntry();
+        if (entry.resource?.resourceType !== ResourceTypesFhirR4.Consent) {
+            throw new Error(`BundleEntryEditor cannot open this entry as Consent: ${String(entry.resource?.resourceType || '')}`);
+        }
+        return createRegisteredBundleEntryEditor(BundleEditableResourceTypes.consent, this.bundleEditor, this.entryIndex);
+    }
+    /** Opens the current entry as one RelatedPerson/contact editor. */
+    asRelatedPerson() {
+        const entry = this.getMutableEntry();
+        if (entry.resource?.resourceType !== ResourceTypesFhirR4.RelatedPerson) {
+            throw new Error(`BundleEntryEditor cannot open this entry as RelatedPerson: ${String(entry.resource?.resourceType || '')}`);
+        }
+        return createRegisteredBundleEntryEditor(BundleEditableResourceTypes.relatedPerson, this.bundleEditor, this.entryIndex);
+    }
     /** Opens the current entry as one vital-sign-specific Observation editor. */
     asVitalSign() {
         const entry = this.getMutableEntry();

package/dist/utils/communication-consent-access-editor.d.ts

@@ -1,6 +1,6 @@
 import { type HealthcareActorRoleDescriptor, type HealthcareSectionDescriptor } from '../constants/healthcare';
 import type { DataspaceSector } from '../constants/sectors';
-import type { CommunicationAttachedBundleSessionOptions, ConsentEditorClassifiedActors, ConsentEditorClassifiedPurpose, ConsentEditorClassifiedRoles, ConsentEditorClassifiedTarget, ConsentViewModel } from '../models/communication-attached-bundle-session';
+import type { ActiveEntrySelection, CommunicationAttachedBundleSessionOptions, ConsentEditorClassifiedActors, ConsentEditorClassifiedPurpose, ConsentEditorClassifiedRoles, ConsentEditorClassifiedTarget, ConsentViewModel, UpsertClaimsResourceEntryInput } from '../models/communication-attached-bundle-session';
 import type { ConsentDuplicateRuleConflict } from './consent-duplicate-rules';
 import { CommunicationAttachedBundleSession } from './communication-attached-bundle-session';
 /**
@@ -15,6 +15,19 @@ import { CommunicationAttachedBundleSession } from './communication-attached-bun
  * by the existing access-rule contract.
  */
 export declare class ConsentAccessEditor extends CommunicationAttachedBundleSession {
+    /**
+     * Adds one authored Consent to the in-memory permission Bundle and selects it.
+     *
+     * Prefer this semantic name in app code and tutorials. Saving, attaching the
+     * completed Bundle to a Communication and transporting it are later steps.
+     */
+    addConsent(input: UpsertClaimsResourceEntryInput<Record<string, unknown>>): this;
+    /** Reopens one Consent already present in the in-memory permission Bundle. */
+    openConsent(selection: ActiveEntrySelection): this;
+    /** Saves the active Consent and closes its editing selection. */
+    saveConsent(): this;
+    /** @deprecated Internal compatibility plumbing. Use `addConsent(...)`. */
+    upsertActiveConsentEntry(input: UpsertClaimsResourceEntryInput<Record<string, unknown>>): this;
     /** Returns duplicate atomic consent-rule conflicts across the current bundle. */
     getConsentRuleDuplicateConflicts(): ConsentDuplicateRuleConflict[];
     /** Returns duplicate atomic consent-rule conflicts affecting the active Consent entry. */

package/dist/utils/communication-consent-access-editor.js

@@ -18,6 +18,33 @@ import { asTrimmedString, buildClassifiedConsentTarget, buildConsentViewModel, b
  * by the existing access-rule contract.
  */
 export class ConsentAccessEditor extends CommunicationAttachedBundleSession {
+    /**
+     * Adds one authored Consent to the in-memory permission Bundle and selects it.
+     *
+     * Prefer this semantic name in app code and tutorials. Saving, attaching the
+     * completed Bundle to a Communication and transporting it are later steps.
+     */
+    addConsent(input) {
+        return super.upsertActiveConsentEntry(input);
+    }
+    /** Reopens one Consent already present in the in-memory permission Bundle. */
+    openConsent(selection) {
+        this.selectActiveEntry(selection);
+        const resourceType = this.getActiveEntry()?.resource?.resourceType;
+        if (resourceType !== ResourceTypesFhirR4.Consent) {
+            this.clearActiveEntry();
+            throw new Error(`ConsentAccessEditor cannot open resource type: ${String(resourceType || '')}`);
+        }
+        return this;
+    }
+    /** Saves the active Consent and closes its editing selection. */
+    saveConsent() {
+        return this.saveAndReleaseActiveEntry();
+    }
+    /** @deprecated Internal compatibility plumbing. Use `addConsent(...)`. */
+    upsertActiveConsentEntry(input) {
+        return this.addConsent(input);
+    }
     /** Returns duplicate atomic consent-rule conflicts across the current bundle. */
     getConsentRuleDuplicateConflicts() {
         return detectDuplicateConsentRuleConflicts(this.getBundleInMemory().data);

package/dist/utils/consent-entry-editor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * File discipline note:
+ * - Read `ARCHITECTURE.md` and `CONTRIBUTING.md` before changing this module.
+ * - This file owns only the typed editor for one staged Consent entry.
+ */
+import { type ConsentDecision } from '../models/consent-rule';
+import { BundleEntryEditor } from './bundle-entry-editor';
+/**
+ * Typed editor for one Consent permission staged inside a Bundle.
+ *
+ * It edits semantic permission data only. It does not create a Communication,
+ * choose a clinical projection, pack DIDComm, authorize, submit or poll.
+ */
+export declare class ConsentEntryEditor extends BundleEntryEditor {
+    setIdentifier(value?: string | null): this;
+    getIdentifier(): string | undefined;
+    ensureIdentifier(): string;
+    setSubject(value?: string | null): this;
+    getSubject(): string | undefined;
+    setDecision(value?: ConsentDecision | null): this;
+    getDecision(): string | undefined;
+    setActorIdentifierList(values: readonly string[]): this;
+    getActorIdentifierList(): string[];
+    setActorRoleList(values: readonly string[]): this;
+    getActorRoleList(): string[];
+    setPurposeList(values: readonly string[]): this;
+    getPurposeList(): string[];
+    setSectionList(values: readonly string[]): this;
+    getSectionList(): string[];
+    setResourceTypeList(values: readonly string[]): this;
+    getResourceTypeList(): string[];
+    setDate(value?: string | null): this;
+    getDate(): string | undefined;
+    setPeriodStart(value?: string | null): this;
+    getPeriodStart(): string | undefined;
+    setPeriodEnd(value?: string | null): this;
+    getPeriodEnd(): string | undefined;
+    private setOptionalText;
+    private getOptionalText;
+    private setList;
+    private getList;
+}

package/dist/utils/consent-entry-editor.js

@@ -0,0 +1,80 @@
+/**
+ * File discipline note:
+ * - Read `ARCHITECTURE.md` and `CONTRIBUTING.md` before changing this module.
+ * - This file owns only the typed editor for one staged Consent entry.
+ */
+import { ClaimConsent } from '../models/consent-rule.js';
+import { BundleEditableResourceTypes } from '../models/bundle-editor-types.js';
+import { BundleEntryEditor } from './bundle-entry-editor.js';
+import { registerBundleEntryEditor } from './bundle-editor-registry.js';
+function normalizeText(value) {
+    const normalized = String(value || '').trim();
+    return normalized || undefined;
+}
+function normalizeList(values) {
+    return [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))];
+}
+/**
+ * Typed editor for one Consent permission staged inside a Bundle.
+ *
+ * It edits semantic permission data only. It does not create a Communication,
+ * choose a clinical projection, pack DIDComm, authorize, submit or poll.
+ */
+export class ConsentEntryEditor extends BundleEntryEditor {
+    setIdentifier(value) {
+        const normalized = normalizeText(value);
+        if (!normalized) {
+            this.removeClaim(ClaimConsent.identifier).setResourceId().setFullUrl();
+            return this;
+        }
+        return this.setClaim(ClaimConsent.identifier, normalized)
+            .setResourceId(normalized)
+            .setFullUrl(normalized);
+    }
+    getIdentifier() {
+        return normalizeText(String(this.getClaim(ClaimConsent.identifier) || this.getResourceId() || this.getFullUrl() || ''));
+    }
+    ensureIdentifier() {
+        const identifier = this.getIdentifier();
+        if (!identifier)
+            throw new Error('Consent entry requires a generated resource id or explicit identifier.');
+        this.setIdentifier(identifier);
+        return identifier;
+    }
+    setSubject(value) { return this.setOptionalText(ClaimConsent.subject, value); }
+    getSubject() { return this.getOptionalText(ClaimConsent.subject); }
+    setDecision(value) { return this.setOptionalText(ClaimConsent.decision, value); }
+    getDecision() { return this.getOptionalText(ClaimConsent.decision); }
+    setActorIdentifierList(values) { return this.setList(ClaimConsent.actorIdentifier, values); }
+    getActorIdentifierList() { return this.getList(ClaimConsent.actorIdentifier); }
+    setActorRoleList(values) { return this.setList(ClaimConsent.actorRole, values); }
+    getActorRoleList() { return this.getList(ClaimConsent.actorRole); }
+    setPurposeList(values) { return this.setList(ClaimConsent.purpose, values); }
+    getPurposeList() { return this.getList(ClaimConsent.purpose); }
+    setSectionList(values) { return this.setList(ClaimConsent.action, values); }
+    getSectionList() { return this.getList(ClaimConsent.action); }
+    setResourceTypeList(values) { return this.setList(ClaimConsent.resourceType, values); }
+    getResourceTypeList() { return this.getList(ClaimConsent.resourceType); }
+    setDate(value) { return this.setOptionalText(ClaimConsent.date, value); }
+    getDate() { return this.getOptionalText(ClaimConsent.date); }
+    setPeriodStart(value) { return this.setOptionalText(ClaimConsent.periodStart, value); }
+    getPeriodStart() { return this.getOptionalText(ClaimConsent.periodStart); }
+    setPeriodEnd(value) { return this.setOptionalText(ClaimConsent.periodEnd, value); }
+    getPeriodEnd() { return this.getOptionalText(ClaimConsent.periodEnd); }
+    setOptionalText(key, value) {
+        const normalized = normalizeText(value);
+        return normalized ? this.setClaim(key, normalized) : this.removeClaim(key);
+    }
+    getOptionalText(key) {
+        return normalizeText(String(this.getClaim(key) || ''));
+    }
+    setList(key, values) {
+        const normalized = normalizeList(values);
+        return normalized.length ? this.setClaim(key, normalized.join(',')) : this.removeClaim(key);
+    }
+    getList(key) {
+        const value = this.getClaim(key);
+        return normalizeList(Array.isArray(value) ? value.map(String) : String(value || '').split(','));
+    }
+}
+registerBundleEntryEditor(BundleEditableResourceTypes.consent, ConsentEntryEditor);

package/dist/utils/index.d.ts

@@ -59,6 +59,7 @@ export * from './clinical-resource-view';
 export * from './fhir-validator';
 export * from './family-registration-test-data';
 export * from './individual-form-pdf';
+export * from './individual-identifier';
 export * from './individual-smart';
 export * from './individual-organization-claims';
 export * from './inter-tenant-access-contract';

package/dist/utils/index.js

@@ -59,6 +59,7 @@ export * from './clinical-resource-view.js';
 export * from './fhir-validator.js';
 export * from './family-registration-test-data.js';
 export * from './individual-form-pdf.js';
+export * from './individual-identifier.js';
 export * from './individual-smart.js';
 export * from './individual-organization-claims.js';
 export * from './inter-tenant-access-contract.js';

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

@@ -0,0 +1,14 @@
+import { type Hl7V20203IdentifierCode, type IdKindValue } from '../constants/identity-identifiers.js';
+export type IndividualIdentifierInput = Readonly<{
+    type: Hl7V20203IdentifierCode | IdKindValue | string;
+    jurisdiction: string;
+    value: string;
+}>;
+/** Resolves a supported short or reverse-DNS HL7 identifier type to one canonical type. */
+export declare function normalizeIndividualIdentifierType(type: IndividualIdentifierInput['type']): IdKindValue;
+/** Builds the sole canonical input hashed for an external individual identifier alias. */
+export declare function buildIndividualIdentifierToken(input: IndividualIdentifierInput): string;
+/** Returns the deterministic CIDv1/SHA3-384 alias stored in `Organization.sameAs`. */
+export declare function buildIndividualIdentifierCid(input: IndividualIdentifierInput): string;
+/** Returns the SHA3-384 multihash URN used as a ledger lookup asset id. */
+export declare function buildIndividualIdentifierLedgerAssetId(input: IndividualIdentifierInput): string;

package/dist/utils/individual-identifier.js

@@ -0,0 +1,39 @@
+import { HL7_V2_0203_REVERSE_DNS_PREFIX, HL7_V2_0203_REVERSE_DNS_TYPES, } from '../constants/identity-identifiers.js';
+import { buildRawCidV1FromUtf8String } from './multiformat-profile.js';
+import { encodeMultibaseSha3 } from './multibasehash.js';
+import { UrnPrefixes } from '../constants/urn.js';
+const LEGACY_HL7_V2_0203_REVERSE_DNS_PREFIX = 'org.hl7.terminology.codesystem.v2-0203';
+const ISO_3166_JURISDICTION_PATTERN = /^[A-Z]{2}(?:-[A-Z0-9]{1,3})?$/;
+/** Resolves a supported short or reverse-DNS HL7 identifier type to one canonical type. */
+export function normalizeIndividualIdentifierType(type) {
+    const candidate = String(type).trim();
+    const shortCode = candidate.startsWith(`${HL7_V2_0203_REVERSE_DNS_PREFIX}.`)
+        ? candidate.slice(HL7_V2_0203_REVERSE_DNS_PREFIX.length + 1)
+        : candidate.startsWith(`${LEGACY_HL7_V2_0203_REVERSE_DNS_PREFIX}.`)
+            ? candidate.slice(LEGACY_HL7_V2_0203_REVERSE_DNS_PREFIX.length + 1)
+            : candidate;
+    const canonical = HL7_V2_0203_REVERSE_DNS_TYPES[shortCode];
+    if (!canonical)
+        throw new Error(`Unsupported individual identifier type: ${candidate}`);
+    return canonical;
+}
+/** Builds the sole canonical input hashed for an external individual identifier alias. */
+export function buildIndividualIdentifierToken(input) {
+    const type = normalizeIndividualIdentifierType(input.type);
+    const jurisdiction = input.jurisdiction.trim().toUpperCase();
+    const value = input.value.trim().normalize('NFKC').toUpperCase();
+    if (!ISO_3166_JURISDICTION_PATTERN.test(jurisdiction)) {
+        throw new Error(`Invalid ISO 3166 jurisdiction: ${input.jurisdiction}`);
+    }
+    if (!value)
+        throw new Error('Individual identifier value is required');
+    return `${type}|${jurisdiction}|${value}`;
+}
+/** Returns the deterministic CIDv1/SHA3-384 alias stored in `Organization.sameAs`. */
+export function buildIndividualIdentifierCid(input) {
+    return buildRawCidV1FromUtf8String(buildIndividualIdentifierToken(input));
+}
+/** Returns the SHA3-384 multihash URN used as a ledger lookup asset id. */
+export function buildIndividualIdentifierLedgerAssetId(input) {
+    return `${UrnPrefixes.Multibase}${encodeMultibaseSha3(buildIndividualIdentifierToken(input))}`;
+}

package/dist/utils/multibasehash.d.ts

@@ -1,8 +1,22 @@
+export type Sha3DigestBits = 224 | 256 | 384 | 512;
 /**
- * Encodes input into multibase(base58btc(multihash(sha384))).
- * - Multihash prefix: 0x15 0x30
- *   - 0x15: code for SHA-384
- *   - 0x30: length of SHA-384 = 48 bytes
- * - Multibase prefix: 'z'
+ * Encodes bytes as `multibase(base58btc(multihash(SHA3-n)))`.
+ *
+ * Contract:
+ * - input strings are hashed as their exact UTF-8 bytes; callers own any
+ *   higher-level identifier or JSON canonicalization
+ * - SHA3-384 is the default profile
+ * - the multihash stores the canonical SHA3 multicodec code and digest length
+ * - the returned `z...` value is a multibase string, not a CID
+ *
+ * Use a CID builder when identifying a content-addressed record. Use this
+ * helper when the multihash itself is the stable identifier or index key.
+ */
+export declare function encodeMultibaseSha3(input: string | Uint8Array, digestBits?: Sha3DigestBits): string;
+/**
+ * @deprecated Use `encodeMultibaseSha3(input)` or pass `384` explicitly.
+ *
+ * This compatibility name now follows its historically intended multihash
+ * profile: SHA3-384, not SHA-2 SHA-384 with a mismatched SHA3 prefix.
  */
 export declare function encodeMultibaseSha384(input: string | Uint8Array): string;

package/dist/utils/multibasehash.js

@@ -1,23 +1,48 @@
 // Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
 // Use explicit .js subpaths to satisfy package exports in Metro/Node ESM.
-import { sha384 } from '@noble/hashes/sha2.js';
+import { sha3_224, sha3_256, sha3_384, sha3_512 } from '@noble/hashes/sha3.js';
 import { utf8ToBytes } from '@noble/hashes/utils.js';
 import baseX from 'base-x';
 const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
 const base58btc = baseX(BASE58_ALPHABET);
+const SHA3_PROFILES = Object.freeze({
+    224: Object.freeze({ code: 0x17, digestLengthBytes: 28, digest: sha3_224 }),
+    256: Object.freeze({ code: 0x16, digestLengthBytes: 32, digest: sha3_256 }),
+    384: Object.freeze({ code: 0x15, digestLengthBytes: 48, digest: sha3_384 }),
+    512: Object.freeze({ code: 0x14, digestLengthBytes: 64, digest: sha3_512 }),
+});
 /**
- * Encodes input into multibase(base58btc(multihash(sha384))).
- * - Multihash prefix: 0x15 0x30
- *   - 0x15: code for SHA-384
- *   - 0x30: length of SHA-384 = 48 bytes
- * - Multibase prefix: 'z'
+ * Encodes bytes as `multibase(base58btc(multihash(SHA3-n)))`.
+ *
+ * Contract:
+ * - input strings are hashed as their exact UTF-8 bytes; callers own any
+ *   higher-level identifier or JSON canonicalization
+ * - SHA3-384 is the default profile
+ * - the multihash stores the canonical SHA3 multicodec code and digest length
+ * - the returned `z...` value is a multibase string, not a CID
+ *
+ * Use a CID builder when identifying a content-addressed record. Use this
+ * helper when the multihash itself is the stable identifier or index key.
  */
-export function encodeMultibaseSha384(input) {
+export function encodeMultibaseSha3(input, digestBits = 384) {
+    const profile = SHA3_PROFILES[digestBits];
+    if (!profile) {
+        throw new Error(`Unsupported SHA3 digest size: ${String(digestBits)}`);
+    }
     const bytes = typeof input === 'string' ? utf8ToBytes(input) : input;
-    const hashBytes = sha384(bytes);
+    const hashBytes = profile.digest(bytes);
     const multihashBytes = new Uint8Array(2 + hashBytes.length);
-    multihashBytes[0] = 0x15; // SHA-384 code
-    multihashBytes[1] = 0x30; // length = 48
+    multihashBytes[0] = profile.code;
+    multihashBytes[1] = profile.digestLengthBytes;
     multihashBytes.set(hashBytes, 2);
     return 'z' + base58btc.encode(multihashBytes);
 }
+/**
+ * @deprecated Use `encodeMultibaseSha3(input)` or pass `384` explicitly.
+ *
+ * This compatibility name now follows its historically intended multihash
+ * profile: SHA3-384, not SHA-2 SHA-384 with a mismatched SHA3 prefix.
+ */
+export function encodeMultibaseSha384(input) {
+    return encodeMultibaseSha3(input, 384);
+}

package/dist/utils/multiformat-profile.d.ts

@@ -38,9 +38,11 @@ export declare const SHA3_256_MULTIHASH_PROFILE: MultihashProfile;
  */
 export declare const SHA3_384_MULTIHASH_PROFILE: MultihashProfile;
 /**
- * Builds a `CIDv1` over a UTF-8 string using the provided multihash profile.
+ * Builds a `CIDv1` over a UTF-8 string using SHA3-384 by default.
  *
  * This helper intentionally does not canonicalize the input string for you.
  * Callers must pass the final canonical logical identifier they want to anchor.
+ * A caller may supply another explicit multihash profile when an established
+ * external contract requires it.
  */
-export declare function buildRawCidV1FromUtf8String(value: string, profile: MultihashProfile): string;
+export declare function buildRawCidV1FromUtf8String(value: string, profile?: MultihashProfile): string;

package/dist/utils/multiformat-profile.js

@@ -19,7 +19,7 @@ export const MULTICODEC_RAW_CODE = 0x55;
  */
 export const SHA3_256_MULTIHASH_PROFILE = Object.freeze({
     algorithm: 'sha3-256',
-    code: 0x14,
+    code: 0x16,
     digestLengthBytes: 32,
     digest: sha3_256,
 });
@@ -36,12 +36,14 @@ export const SHA3_384_MULTIHASH_PROFILE = Object.freeze({
     digest: sha3_384,
 });
 /**
- * Builds a `CIDv1` over a UTF-8 string using the provided multihash profile.
+ * Builds a `CIDv1` over a UTF-8 string using SHA3-384 by default.
  *
  * This helper intentionally does not canonicalize the input string for you.
  * Callers must pass the final canonical logical identifier they want to anchor.
+ * A caller may supply another explicit multihash profile when an established
+ * external contract requires it.
  */
-export function buildRawCidV1FromUtf8String(value, profile) {
+export function buildRawCidV1FromUtf8String(value, profile = SHA3_384_MULTIHASH_PROFILE) {
     const digest = profile.digest(utf8ToBytes(String(value || '')));
     const multihash = concatBytes(Uint8Array.from([profile.code, profile.digestLengthBytes]), digest);
     const cidBytes = concatBytes(encodeVarint(MULTIFORMAT_CID_V1_CODE), encodeVarint(MULTICODEC_RAW_CODE), multihash);

package/dist/utils/related-person-entry-editor.d.ts

@@ -0,0 +1,32 @@
+import { BundleEntryEditor } from './bundle-entry-editor';
+/**
+ * Typed editor for one RelatedPerson/contact staged inside a Bundle.
+ *
+ * Relationship authoring is separate from access authorization. This editor
+ * does not grant Consent, build a Communication, submit or poll.
+ */
+export declare class RelatedPersonEntryEditor extends BundleEntryEditor {
+    setIdentifier(value?: string | null): this;
+    getIdentifier(): string | undefined;
+    ensureIdentifier(): string;
+    setActive(value?: boolean | null): this;
+    getActive(): boolean | undefined;
+    setSubject(value?: string | null): this;
+    getSubject(): string | undefined;
+    setRelationship(value?: string | null): this;
+    getRelationship(): string | undefined;
+    setRoleList(values: readonly string[]): this;
+    getRoleList(): string[];
+    setName(value?: string | null): this;
+    getName(): string | undefined;
+    setTelecom(value?: string | null): this;
+    getTelecom(): string | undefined;
+    setRelatedEntityType(value?: string | null): this;
+    getRelatedEntityType(): string | undefined;
+    setActorIdentifierList(values: readonly string[]): this;
+    getActorIdentifierList(): string[];
+    private setOptionalText;
+    private getOptionalText;
+    private setList;
+    private getList;
+}

package/dist/utils/related-person-entry-editor.js

@@ -0,0 +1,97 @@
+/**
+ * File discipline note:
+ * - Read `ARCHITECTURE.md` and `CONTRIBUTING.md` before changing this module.
+ * - This file owns only the typed editor for one staged RelatedPerson entry.
+ */
+import { RelatedPersonClaim } from '../models/interoperable-claims/related-person-claims.js';
+import { BundleEditableResourceTypes } from '../models/bundle-editor-types.js';
+import { BundleEntryEditor } from './bundle-entry-editor.js';
+import { registerBundleEntryEditor } from './bundle-editor-registry.js';
+function normalizeText(value) {
+    const normalized = String(value || '').trim();
+    return normalized || undefined;
+}
+function normalizeList(values) {
+    return [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))];
+}
+/**
+ * Typed editor for one RelatedPerson/contact staged inside a Bundle.
+ *
+ * Relationship authoring is separate from access authorization. This editor
+ * does not grant Consent, build a Communication, submit or poll.
+ */
+export class RelatedPersonEntryEditor extends BundleEntryEditor {
+    setIdentifier(value) {
+        const normalized = normalizeText(value);
+        if (!normalized) {
+            this.removeClaim(RelatedPersonClaim.IdentifierValue)
+                .removeClaim(RelatedPersonClaim.Identifier)
+                .setResourceId()
+                .setFullUrl();
+            return this;
+        }
+        return this.setClaim(RelatedPersonClaim.IdentifierValue, normalized)
+            .setClaim(RelatedPersonClaim.Identifier, normalized)
+            .setResourceId(normalized)
+            .setFullUrl(normalized);
+    }
+    getIdentifier() {
+        return normalizeText(String(this.getClaim(RelatedPersonClaim.IdentifierValue)
+            || this.getClaim(RelatedPersonClaim.Identifier)
+            || this.getResourceId()
+            || this.getFullUrl()
+            || ''));
+    }
+    ensureIdentifier() {
+        const identifier = this.getIdentifier();
+        if (!identifier)
+            throw new Error('RelatedPerson entry requires a generated resource id or explicit identifier.');
+        this.setIdentifier(identifier);
+        return identifier;
+    }
+    setActive(value) {
+        return value === undefined || value === null
+            ? this.removeClaim(RelatedPersonClaim.Active)
+            : this.setClaim(RelatedPersonClaim.Active, value);
+    }
+    getActive() {
+        const value = this.getClaim(RelatedPersonClaim.Active);
+        if (typeof value === 'boolean')
+            return value;
+        if (String(value).toLowerCase() === 'true')
+            return true;
+        if (String(value).toLowerCase() === 'false')
+            return false;
+        return undefined;
+    }
+    setSubject(value) { return this.setOptionalText(RelatedPersonClaim.Patient, value); }
+    getSubject() { return this.getOptionalText(RelatedPersonClaim.Patient); }
+    setRelationship(value) { return this.setOptionalText(RelatedPersonClaim.Relationship, value); }
+    getRelationship() { return this.getOptionalText(RelatedPersonClaim.Relationship); }
+    setRoleList(values) { return this.setList(RelatedPersonClaim.Role, values); }
+    getRoleList() { return this.getList(RelatedPersonClaim.Role); }
+    setName(value) { return this.setOptionalText(RelatedPersonClaim.Name, value); }
+    getName() { return this.getOptionalText(RelatedPersonClaim.Name); }
+    setTelecom(value) { return this.setOptionalText(RelatedPersonClaim.Telecom, value); }
+    getTelecom() { return this.getOptionalText(RelatedPersonClaim.Telecom); }
+    setRelatedEntityType(value) { return this.setOptionalText(RelatedPersonClaim.RelatedEntityType, value); }
+    getRelatedEntityType() { return this.getOptionalText(RelatedPersonClaim.RelatedEntityType); }
+    setActorIdentifierList(values) { return this.setList(RelatedPersonClaim.ActorIdentifier, values); }
+    getActorIdentifierList() { return this.getList(RelatedPersonClaim.ActorIdentifier); }
+    setOptionalText(key, value) {
+        const normalized = normalizeText(value);
+        return normalized ? this.setClaim(key, normalized) : this.removeClaim(key);
+    }
+    getOptionalText(key) {
+        return normalizeText(String(this.getClaim(key) || ''));
+    }
+    setList(key, values) {
+        const normalized = normalizeList(values);
+        return normalized.length ? this.setClaim(key, normalized.join(',')) : this.removeClaim(key);
+    }
+    getList(key) {
+        const value = this.getClaim(key);
+        return normalizeList(Array.isArray(value) ? value.map(String) : String(value || '').split(','));
+    }
+}
+registerBundleEntryEditor(BundleEditableResourceTypes.relatedPerson, RelatedPersonEntryEditor);

package/dist/utils/same-as.d.ts

@@ -49,6 +49,16 @@ export declare function normalizeSameAsHash(value: string): string;
  * @param value Canonical sameAs source value(s).
  */
 export declare function normalizeSameAsHashList(value: string | readonly string[] | undefined): string[];
+/**
+ * Splits a public alias CSV without changing the aliases themselves.
+ *
+ * Use this for mixed DID/CID `sameAs` indexes. Unlike
+ * `normalizeSameAsHashList`, it deliberately does not interpret a CIDv1
+ * beginning with `z` as a bare `urn:multibase` value.
+ */
+export declare function normalizePublicAliasList(value: string | readonly string[] | undefined): string[];
+/** Derives an opaque SHA3-384 multihash URN for a global-ledger alias key. */
+export declare function buildPublicAliasLedgerAssetId(alias: string): string;
 /**
  * Joins one or more normalized `sameAs` aliases into the current flat CSV
  * storage form used by some shared VC/profile helpers.

package/dist/utils/same-as.js

@@ -1,6 +1,9 @@
-import { createHash } from 'crypto';
+import { sha3_256 } from '@noble/hashes/sha3.js';
+import { utf8ToBytes } from '@noble/hashes/utils.js';
 import { normalizePhone } from './consent.js';
 import { encodeMultibase58btc } from './multibase58.js';
+import { encodeMultibaseSha3 } from './multibasehash.js';
+import { UrnPrefixes } from '../constants/urn.js';
 /**
  * Builds the ICA-compatible multibase58(multihash(sha3-256)) payload for a
  * public controller alias.
@@ -18,8 +21,8 @@ export function multibase58MultihashSha3_256(value) {
     if (!normalized) {
         throw new Error('Cannot create multihash from empty value.');
     }
-    const digest = createHash('sha3-256').update(normalized, 'utf8').digest();
-    const multihash = Buffer.concat([Buffer.from([0x16, 0x20]), digest]);
+    const digest = sha3_256(utf8ToBytes(normalized));
+    const multihash = Uint8Array.from([0x16, 0x20, ...digest]);
     return encodeMultibase58btc(multihash);
 }
 function looksLikeBase58Multibase(value) {
@@ -96,6 +99,28 @@ export function normalizeSameAsHashList(value) {
         .filter(Boolean);
     return [...new Set(normalized)];
 }
+/**
+ * Splits a public alias CSV without changing the aliases themselves.
+ *
+ * Use this for mixed DID/CID `sameAs` indexes. Unlike
+ * `normalizeSameAsHashList`, it deliberately does not interpret a CIDv1
+ * beginning with `z` as a bare `urn:multibase` value.
+ */
+export function normalizePublicAliasList(value) {
+    const candidates = Array.isArray(value)
+        ? value.flatMap((entry) => splitCommaSeparatedValues(entry))
+        : splitCommaSeparatedValues(String(value || ''));
+    return [...new Set(candidates.map((candidate) => candidate.trim()).filter(Boolean))];
+}
+/** Derives an opaque SHA3-384 multihash URN for a global-ledger alias key. */
+export function buildPublicAliasLedgerAssetId(alias) {
+    const normalized = String(alias || '').trim().normalize('NFKC');
+    if (!normalized)
+        throw new Error('Public alias is required');
+    if (normalized.startsWith(UrnPrefixes.Multibase))
+        return normalized;
+    return `${UrnPrefixes.Multibase}${encodeMultibaseSha3(normalized)}`;
+}
 /**
  * Joins one or more normalized `sameAs` aliases into the current flat CSV
  * storage form used by some shared VC/profile helpers.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
   "dependencies": {
+    "@noble/hashes": "^2.0.1",
     "@noble/post-quantum": "^0.5.4",
     "@stablelib/base64": "^1.0.1",
     "@stablelib/utf8": "^1.0.2",