gdc-common-utils-ts 2.4.1 → 2.5.1

package/dist/utils/index.d.ts

@@ -83,6 +83,7 @@ export * from './jwt-signer';
 export * from './jwk-thumbprint';
 export * from './legal-organization-onboarding';
 export * from './legal-organization-verification-transaction';
+export * from './organization-registration-authorization';
 export * from './local-terminology-provider';
 export * from './license';
 export * from './license-commercial-search';
@@ -102,6 +103,7 @@ 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';

package/dist/utils/index.js

@@ -83,6 +83,7 @@ export * from './jwt-signer.js';
 export * from './jwk-thumbprint.js';
 export * from './legal-organization-onboarding.js';
 export * from './legal-organization-verification-transaction.js';
+export * from './organization-registration-authorization.js';
 export * from './local-terminology-provider.js';
 export * from './license.js';
 export * from './license-commercial-search.js';
@@ -102,6 +103,7 @@ 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';

package/dist/utils/jwk-thumbprint.d.ts

@@ -38,3 +38,11 @@ export declare function computeRfc7638JwkThumbprint(jwk: ThumbprintableJwk): str
  * `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
  */
 export declare function toJwkThumbprintSha256Urn(jwk: ThumbprintableJwk): string;
+/**
+ * Returns a public JWK whose `kid` is derived exclusively from its public key
+ * material. Caller-provided aliases are deliberately replaced so DID methods,
+ * credentials and confidential-storage indexes share one RFC 9278 identifier.
+ */
+export declare function withJwkThumbprintSha256Kid<T extends ThumbprintableJwk>(jwk: T): T & {
+    kid: string;
+};

package/dist/utils/jwk-thumbprint.js

@@ -55,3 +55,14 @@ export function computeRfc7638JwkThumbprint(jwk) {
 export function toJwkThumbprintSha256Urn(jwk) {
     return `${UrnPrefixes.JwkThumbprintSha256KeyId}${computeRfc7638JwkThumbprint(jwk)}`;
 }
+/**
+ * Returns a public JWK whose `kid` is derived exclusively from its public key
+ * material. Caller-provided aliases are deliberately replaced so DID methods,
+ * credentials and confidential-storage indexes share one RFC 9278 identifier.
+ */
+export function withJwkThumbprintSha256Kid(jwk) {
+    return {
+        ...jwk,
+        kid: toJwkThumbprintSha256Urn(jwk),
+    };
+}

package/dist/utils/legal-organization-onboarding-editor.d.ts

@@ -106,6 +106,7 @@ export interface LegalOrganizationOnboardingFacade {
     buildVerificationTransactionInput(fields: LegalOrganizationFormTemplateFields, input: Readonly<{
         controller: LegalOrganizationVerificationTransactionController;
         organization?: LegalOrganizationVerificationTransactionOrganization;
+        /** @deprecated Legacy demo/OTP compatibility input. */
         legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
         verification?: LegalOrganizationVerificationRouting;
         attachments?: unknown[];
@@ -146,6 +147,7 @@ export interface LegalOrganizationOnboardingEditor {
     buildVerificationTransactionInput(input: Readonly<{
         controller: LegalOrganizationVerificationTransactionController;
         organization?: LegalOrganizationVerificationTransactionOrganization;
+        /** @deprecated Legacy demo/OTP compatibility input. */
         legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
         verification?: LegalOrganizationVerificationRouting;
         attachments?: unknown[];

package/dist/utils/legal-organization-onboarding-editor.js

@@ -304,9 +304,7 @@ export function createLegalOrganizationOnboardingFacade() {
                         ...(controllerEmail ? { email: controllerEmail } : {}),
                         ...(representativeSameAs ? { sameAs: representativeSameAs } : {}),
                     }
-                    : controllerEmail
-                        ? { email: controllerEmail }
-                        : undefined,
+                    : undefined,
                 verification: {
                     resourceType: normalizeOptionalText(input.verificationResourceType) || 'contract',
                 },

package/dist/utils/legal-organization-verification-result.d.ts

@@ -4,6 +4,27 @@ export type LegalOrganizationVerificationCredentialPair = Readonly<{
     organizationCredential: LegalOrganizationVerificationCredential;
     legalRepresentativeCredential: LegalOrganizationVerificationCredential;
 }>;
+/**
+ * Extracts the controller actor stored at
+ * `credentialSubject.owner` in an organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export declare function extractOrganizationControllerOwner(credential: unknown): Record<string, unknown> | undefined;
+/**
+ * Extracts the stable public actor identifier from an
+ * organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export declare function extractOrganizationControllerSameAs(credential: unknown): string | undefined;
+/**
+ * Extracts the RFC 9278 JWK-thumbprint binding from an
+ * organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export declare function extractOrganizationControllerBinding(credential: unknown): string | undefined;
 /**
  * Returns the ICA verification entries currently projected by GW host
  * legal-organization `_transaction`.
@@ -35,3 +56,27 @@ export declare function readLegalRepresentativeSameAsFromResponseBody(responseBo
  * legal-representative credential when present.
  */
 export declare function readLegalRepresentativeBindingFromResponseBody(responseBody: unknown): string | undefined;
+/**
+ * Returns all independently issued organization-controller service
+ * credentials in an ICA or projected GW verification response.
+ *
+ * The result is empty when the response contains only the legacy organization
+ * and legal-representative credential pair.
+ */
+export declare function readOrganizationControllerCredentialsFromResponseBody(responseBody: unknown): LegalOrganizationVerificationCredential[];
+/**
+ * Returns one organization-controller service credential in an ICA or
+ * projected GW verification response. Pass a stable actor `sameAs` to select
+ * one controller independently; otherwise the first controller is returned.
+ */
+export declare function readOrganizationControllerCredentialFromResponseBody(responseBody: unknown, controllerSameAs?: string): LegalOrganizationVerificationCredential | undefined;
+/**
+ * Reads `credentialSubject.owner.sameAs` from the first
+ * organization-controller service credential when present.
+ */
+export declare function readOrganizationControllerSameAsFromResponseBody(responseBody: unknown): string | undefined;
+/**
+ * Reads `credentialSubject.owner.hasCredential.material` from the first
+ * organization-controller service credential when present.
+ */
+export declare function readOrganizationControllerBindingFromResponseBody(responseBody: unknown): string | undefined;

package/dist/utils/legal-organization-verification-result.js

@@ -23,6 +23,45 @@ function findCredentialResource(entries, expectedTypeFragment, fallbackIndex) {
     }
     return resource;
 }
+function hasCredentialType(value, expectedType) {
+    const candidate = asObject(value);
+    const resource = asObject(candidate?.resource);
+    const typeValues = [candidate?.type, resource?.type];
+    return typeValues.some((typeValue) => {
+        const tokens = Array.isArray(typeValue)
+            ? typeValue.map((token) => String(token || ''))
+            : [String(typeValue || '')];
+        return tokens.some((token) => token.includes(expectedType));
+    });
+}
+/**
+ * Extracts the controller actor stored at
+ * `credentialSubject.owner` in an organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export function extractOrganizationControllerOwner(credential) {
+    return asObject(extractCredentialSubject(credential)?.owner);
+}
+/**
+ * Extracts the stable public actor identifier from an
+ * organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export function extractOrganizationControllerSameAs(credential) {
+    return String(extractOrganizationControllerOwner(credential)?.sameAs || '').trim() || undefined;
+}
+/**
+ * Extracts the RFC 9278 JWK-thumbprint binding from an
+ * organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export function extractOrganizationControllerBinding(credential) {
+    const owner = extractOrganizationControllerOwner(credential);
+    return owner ? extractRepresentativeCredentialBinding({ credentialSubject: owner }) : undefined;
+}
 /**
  * Returns the ICA verification entries currently projected by GW host
  * legal-organization `_transaction`.
@@ -104,3 +143,42 @@ export function readLegalRepresentativeBindingFromResponseBody(responseBody) {
     const pair = readLegalOrganizationVerificationCredentialPairFromResponseBody(responseBody);
     return extractRepresentativeCredentialBinding(pair.legalRepresentativeCredential);
 }
+/**
+ * Returns all independently issued organization-controller service
+ * credentials in an ICA or projected GW verification response.
+ *
+ * The result is empty when the response contains only the legacy organization
+ * and legal-representative credential pair.
+ */
+export function readOrganizationControllerCredentialsFromResponseBody(responseBody) {
+    return getLegalOrganizationVerificationEntriesFromResponseBody(responseBody)
+        .filter((entry) => hasCredentialType(entry, 'OrganizationControllerCredential'))
+        .map((entry) => asObject(asObject(entry)?.resource) || asObject(entry))
+        .filter((entry) => Boolean(entry));
+}
+/**
+ * Returns one organization-controller service credential in an ICA or
+ * projected GW verification response. Pass a stable actor `sameAs` to select
+ * one controller independently; otherwise the first controller is returned.
+ */
+export function readOrganizationControllerCredentialFromResponseBody(responseBody, controllerSameAs) {
+    const credentials = readOrganizationControllerCredentialsFromResponseBody(responseBody);
+    const expectedSameAs = String(controllerSameAs || '').trim();
+    return expectedSameAs
+        ? credentials.find((credential) => extractOrganizationControllerSameAs(credential) === expectedSameAs)
+        : credentials[0];
+}
+/**
+ * Reads `credentialSubject.owner.sameAs` from the first
+ * organization-controller service credential when present.
+ */
+export function readOrganizationControllerSameAsFromResponseBody(responseBody) {
+    return extractOrganizationControllerSameAs(readOrganizationControllerCredentialFromResponseBody(responseBody));
+}
+/**
+ * Reads `credentialSubject.owner.hasCredential.material` from the first
+ * organization-controller service credential when present.
+ */
+export function readOrganizationControllerBindingFromResponseBody(responseBody) {
+    return extractOrganizationControllerBinding(readOrganizationControllerCredentialFromResponseBody(responseBody));
+}

package/dist/utils/legal-organization-verification-transaction.d.ts

@@ -1,5 +1,6 @@
 import type { BundleJsonApi } from '../models/bundle';
 import type { ClaimsRecord } from '../models/resource-document';
+import type { VerifiableCredentialV2 } from '../models/verifiable-credential';
 /**
  * Canonical business entry type for the first host-side onboarding step that
  * asks GW CORE to forward a legal-organization verification request to ICA.
@@ -71,8 +72,14 @@ export type LegalOrganizationVerificationTransactionInput = Readonly<{
     claims: ClaimsRecord;
     controller: LegalOrganizationVerificationTransactionController;
     organization?: LegalOrganizationVerificationTransactionOrganization;
+    /**
+     * @deprecated Legacy demo/OTP compatibility only. Canonical signed-PDF and
+     * strict flows derive the representative from verified evidence.
+     */
     legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
     verification?: LegalOrganizationVerificationRouting;
+    /** Out-of-band host authorization used only by the Test Network path. */
+    authorizationCredential?: VerifiableCredentialV2;
     attachments?: unknown[];
 }>;
 export type LegalOrganizationVerificationTransactionEntry = Readonly<{
@@ -84,9 +91,12 @@ export type LegalOrganizationVerificationTransactionEntry = Readonly<{
     resource?: {
         controller?: LegalOrganizationVerificationTransactionController;
         organization?: LegalOrganizationVerificationTransactionOrganization;
+        /** @deprecated Legacy demo/OTP compatibility input. */
         legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
+        /** @deprecated Legacy ICA wire alias accepted only while migrating old callers. */
         legalRepresentative?: LegalOrganizationVerificationRepresentativePayload;
         verification?: LegalOrganizationVerificationRouting;
+        authorizationCredential?: VerifiableCredentialV2;
         [key: string]: unknown;
     };
     [key: string]: unknown;
@@ -122,6 +132,9 @@ export declare function getLegalOrganizationVerificationController(value: unknow
  * Returns the normalized legal representative contact payload from the first
  * legal-organization verification transaction entry when present.
  *
+ * @deprecated Read-only support for legacy demo/OTP payloads. Canonical
+ * signed-PDF and strict flows derive the representative from verified evidence.
+ *
  * Compatibility note:
  * - GW/SDK request builders use `resource.legalRepresentativePayload`
  * - the ICA forwarding payload currently uses `resource.legalRepresentative`

package/dist/utils/legal-organization-verification-transaction.js

@@ -61,6 +61,9 @@ export function buildLegalOrganizationVerificationTransactionBundle(input) {
                     verification: {
                         resourceType: normalizeText(input.verification?.resourceType) || 'contract',
                     },
+                    ...(input.authorizationCredential
+                        ? { authorizationCredential: input.authorizationCredential }
+                        : {}),
                 },
             }],
         ...(Array.isArray(input.attachments) && input.attachments.length > 0
@@ -98,6 +101,9 @@ export function getLegalOrganizationVerificationController(value) {
  * Returns the normalized legal representative contact payload from the first
  * legal-organization verification transaction entry when present.
  *
+ * @deprecated Read-only support for legacy demo/OTP payloads. Canonical
+ * signed-PDF and strict flows derive the representative from verified evidence.
+ *
  * Compatibility note:
  * - GW/SDK request builders use `resource.legalRepresentativePayload`
  * - the ICA forwarding payload currently uses `resource.legalRepresentative`

package/dist/utils/organization-registration-authorization.d.ts

@@ -0,0 +1,65 @@
+import type { VerifiableCredentialV2 } from '../models/verifiable-credential';
+/** Lifecycle of the one GW activation licence delivered to the legal postal address. */
+export declare const PostalActivationLicenseStatuses: Readonly<{
+    readonly Issued: "issued";
+    readonly Delivered: "delivered";
+    readonly Redeemed: "redeemed";
+    readonly Revoked: "revoked";
+    readonly Expired: "expired";
+}>;
+export type PostalActivationLicenseStatus = typeof PostalActivationLicenseStatuses[keyof typeof PostalActivationLicenseStatuses];
+/**
+ * Public binding recorded for the activation licence. The activation code is
+ * deliberately absent: storage implementations retain only its protected
+ * value/index and never place the secret inside a VC.
+ */
+export type PostalActivationLicenseBinding = Readonly<{
+    licenseId: string;
+    applicationId: string;
+    organizationIdentifier: string;
+    controllerEmail: string;
+    controllerKeyMaterial: string;
+    postalAddressHash: string;
+    hostDid: string;
+    network: 'test-network' | 'network';
+    status: PostalActivationLicenseStatus;
+    issuedAt: string;
+    expiresAt: string;
+    deliveredAt?: string;
+    redeemedAt?: string;
+}>;
+/** Input for the credential returned out-of-band to the applicant controller. */
+export type OrganizationRegistrationAuthorizationCredentialInput = Readonly<{
+    issuerDid: string;
+    subjectDid: string;
+    credentialId: string;
+    validFrom: string;
+    validUntil: string;
+    legalName: string;
+    organizationIdentifier: string;
+    controllerEmail: string;
+    controllerKeyMaterial: string;
+    applicationId: string;
+    accessPath: 'partner' | 'test-network';
+    targetNetwork: 'test-network' | 'network';
+    postalLicense: PostalActivationLicenseBinding;
+    proof?: VerifiableCredentialV2['proof'];
+}>;
+/**
+ * Builds the immutable VC that a controller receives out-of-band and attaches
+ * to `Organization/_transaction`. The postal code itself never appears in the
+ * credential; its confirmed, purpose-bound licence record is referenced.
+ */
+export declare function buildOrganizationRegistrationAuthorizationCredential(input: OrganizationRegistrationAuthorizationCredentialInput): VerifiableCredentialV2;
+/**
+ * Applies the only legal state transitions for the purpose-bound postal code.
+ * Confirmation proves delivery but deliberately does not consume the code;
+ * redemption occurs later during `_exchange`.
+ */
+export declare function transitionPostalActivationLicense(current: PostalActivationLicenseStatus, action: 'mark_delivered' | 'redeem' | 'revoke' | 'expire'): PostalActivationLicenseStatus;
+/**
+ * Produces deterministic UTF-8 JSON for detached proofs. Every proof signs the
+ * same credential payload with the complete `proof` property removed, so a
+ * later counter-proof cannot invalidate an earlier one.
+ */
+export declare function canonicalizeOrganizationRegistrationAuthorizationCredential(credential: VerifiableCredentialV2): string;

package/dist/utils/organization-registration-authorization.js

@@ -0,0 +1,112 @@
+import { ContractCredentialTypes, W3cCredentialContexts, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
+/** Lifecycle of the one GW activation licence delivered to the legal postal address. */
+export const PostalActivationLicenseStatuses = Object.freeze({
+    Issued: 'issued',
+    Delivered: 'delivered',
+    Redeemed: 'redeemed',
+    Revoked: 'revoked',
+    Expired: 'expired',
+});
+function required(value, name) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new Error(`Organization registration authorization requires ${name}.`);
+    return normalized;
+}
+/**
+ * Builds the immutable VC that a controller receives out-of-band and attaches
+ * to `Organization/_transaction`. The postal code itself never appears in the
+ * credential; its confirmed, purpose-bound licence record is referenced.
+ */
+export function buildOrganizationRegistrationAuthorizationCredential(input) {
+    const applicationId = required(input.applicationId, 'applicationId');
+    const organizationIdentifier = required(input.organizationIdentifier, 'organizationIdentifier');
+    const controllerEmail = required(input.controllerEmail, 'controllerEmail').toLowerCase();
+    if (input.postalLicense.status !== PostalActivationLicenseStatuses.Delivered) {
+        throw new Error('Organization registration authorization requires a delivered postal activation licence.');
+    }
+    if (input.postalLicense.applicationId !== applicationId
+        || input.postalLicense.organizationIdentifier !== organizationIdentifier
+        || input.postalLicense.controllerEmail.trim().toLowerCase() !== controllerEmail
+        || input.postalLicense.controllerKeyMaterial !== input.controllerKeyMaterial
+        || input.postalLicense.network !== input.targetNetwork) {
+        throw new Error('Postal activation licence does not match the organization registration application.');
+    }
+    return {
+        '@context': [W3cCredentialContexts.V2, 'https://schema.org'],
+        id: required(input.credentialId, 'credentialId'),
+        type: [
+            W3cCredentialTypes.VerifiableCredential,
+            ContractCredentialTypes.OrganizationRegistrationAuthorizationCredential,
+        ],
+        issuer: required(input.issuerDid, 'issuerDid'),
+        credentialSubject: {
+            id: required(input.subjectDid, 'subjectDid'),
+            applicationId,
+            accessPath: input.accessPath,
+            targetNetwork: input.targetNetwork,
+            organization: {
+                legalName: required(input.legalName, 'legalName'),
+                identifier: organizationIdentifier,
+            },
+            controller: {
+                email: controllerEmail,
+                hasCredential: { material: required(input.controllerKeyMaterial, 'controllerKeyMaterial') },
+            },
+            postalActivationLicense: {
+                id: required(input.postalLicense.licenseId, 'postalLicense.licenseId'),
+                status: input.postalLicense.status,
+                postalAddressHash: required(input.postalLicense.postalAddressHash, 'postalLicense.postalAddressHash'),
+                deliveredAt: required(input.postalLicense.deliveredAt, 'postalLicense.deliveredAt'),
+            },
+        },
+        validFrom: required(input.validFrom, 'validFrom'),
+        validUntil: required(input.validUntil, 'validUntil'),
+        ...(input.proof ? { proof: input.proof } : {}),
+    };
+}
+/**
+ * Applies the only legal state transitions for the purpose-bound postal code.
+ * Confirmation proves delivery but deliberately does not consume the code;
+ * redemption occurs later during `_exchange`.
+ */
+export function transitionPostalActivationLicense(current, action) {
+    if (action === 'mark_delivered' && current === PostalActivationLicenseStatuses.Issued) {
+        return PostalActivationLicenseStatuses.Delivered;
+    }
+    if (action === 'redeem' && current === PostalActivationLicenseStatuses.Delivered) {
+        return PostalActivationLicenseStatuses.Redeemed;
+    }
+    if (action === 'revoke'
+        && (current === PostalActivationLicenseStatuses.Issued
+            || current === PostalActivationLicenseStatuses.Delivered)) {
+        return PostalActivationLicenseStatuses.Revoked;
+    }
+    if (action === 'expire'
+        && (current === PostalActivationLicenseStatuses.Issued
+            || current === PostalActivationLicenseStatuses.Delivered)) {
+        return PostalActivationLicenseStatuses.Expired;
+    }
+    throw new Error(`Invalid postal activation licence transition: ${current} -> ${action}.`);
+}
+function canonicalizeValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeValue);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => key !== 'proof')
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => [key, canonicalizeValue(nested)]));
+}
+/**
+ * Produces deterministic UTF-8 JSON for detached proofs. Every proof signs the
+ * same credential payload with the complete `proof` property removed, so a
+ * later counter-proof cannot invalidate an earlier one.
+ */
+export function canonicalizeOrganizationRegistrationAuthorizationCredential(credential) {
+    if (!credential.type.includes(ContractCredentialTypes.OrganizationRegistrationAuthorizationCredential)) {
+        throw new Error('Credential is not an organization registration authorization.');
+    }
+    return JSON.stringify(canonicalizeValue(credential));
+}

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;
+}