gdc-common-utils-ts 2.3.3 → 2.3.4

package/dist/constants/verifiable-credentials.d.ts

@@ -44,6 +44,14 @@ export declare const IndividualCredentialTypes: Readonly<{
     IndividualControllerCredential: "IndividualControllerCredential";
     IndividualMemberCredential: "IndividualMemberCredential";
     IndividualSubjectCredential: "IndividualSubjectCredential";
+    /**
+     * Credential issued by a trusted portal/identity authority to bind two or
+     * more DIDs that identify the same individual.
+     *
+     * A physical card/support DID is not an individual alias: clients resolve
+     * the support document's `subject` first and bind that subject DID instead.
+     */
+    SubjectIdentityBindingCredential: "SubjectIdentityBindingCredential";
 }>;
 /**
  * Canonical credential subtype names used by inter-tenant authorization

package/dist/constants/verifiable-credentials.js

@@ -46,6 +46,14 @@ export const IndividualCredentialTypes = Object.freeze({
     IndividualControllerCredential: 'IndividualControllerCredential',
     IndividualMemberCredential: 'IndividualMemberCredential',
     IndividualSubjectCredential: 'IndividualSubjectCredential',
+    /**
+     * Credential issued by a trusted portal/identity authority to bind two or
+     * more DIDs that identify the same individual.
+     *
+     * A physical card/support DID is not an individual alias: clients resolve
+     * the support document's `subject` first and bind that subject DID instead.
+     */
+    SubjectIdentityBindingCredential: 'SubjectIdentityBindingCredential',
 });
 /**
  * Canonical credential subtype names used by inter-tenant authorization

package/dist/examples/index.d.ts

@@ -11,6 +11,7 @@ export * from './employee';
 export * from './license';
 export * from './invoice';
 export * from './inter-tenant-access-contract';
+export * from './subject-identity-binding';
 export * from './related-person';
 export * from './consent-access';
 export * from './relationship-access';

package/dist/examples/index.js

@@ -11,6 +11,7 @@ export * from './employee.js';
 export * from './license.js';
 export * from './invoice.js';
 export * from './inter-tenant-access-contract.js';
+export * from './subject-identity-binding.js';
 export * from './related-person.js';
 export * from './consent-access.js';
 export * from './relationship-access.js';

package/dist/examples/shared.d.ts

@@ -117,6 +117,8 @@ export declare const EXAMPLE_GATEWAY_PUBLIC_ORIGIN: "https://gateway.example.com
 export declare const EXAMPLE_HOST_PUBLIC_HOSTNAME: "host.example.com";
 export declare const EXAMPLE_PROVIDER_TAX_ID: "VATES-B00112233";
 export declare const EXAMPLE_PROVIDER_DOMAIN: "health-care.provider.example.org";
+/** Synthetic public portal domain used to derive organization path DIDs. */
+export declare const EXAMPLE_PUBLIC_PORTAL_DOMAIN: "portal.example.org";
 export declare const EXAMPLE_INDIVIDUAL_MULTIBASE_ID: string;
 export declare const EXAMPLE_INDIVIDUAL_MULTIBASE_ID_SECONDARY: string;
 export declare const EXAMPLE_INDIVIDUAL_MULTIBASE_ID_TERTIARY: string;

package/dist/examples/shared.js

@@ -136,6 +136,8 @@ export const EXAMPLE_GATEWAY_PUBLIC_ORIGIN = 'https://gateway.example.com';
 export const EXAMPLE_HOST_PUBLIC_HOSTNAME = 'host.example.com';
 export const EXAMPLE_PROVIDER_TAX_ID = 'VATES-B00112233';
 export const EXAMPLE_PROVIDER_DOMAIN = 'health-care.provider.example.org';
+/** Synthetic public portal domain used to derive organization path DIDs. */
+export const EXAMPLE_PUBLIC_PORTAL_DOMAIN = 'portal.example.org';
 export const EXAMPLE_INDIVIDUAL_MULTIBASE_ID = encodeHexToMultibase58btc('a87e5b15aea444759c7c40aa88354b6f');
 export const EXAMPLE_INDIVIDUAL_MULTIBASE_ID_SECONDARY = encodeHexToMultibase58btc('b98f6c24bfb545849d8d51bb99465c7e');
 export const EXAMPLE_INDIVIDUAL_MULTIBASE_ID_TERTIARY = encodeHexToMultibase58btc('c39f7d35c0c65695ae9e62cca0576d8f');

package/dist/examples/subject-identity-binding.d.ts

@@ -0,0 +1,9 @@
+/** Synthetic trusted portal DID used by binding examples and tests. */
+export declare const EXAMPLE_TRUSTED_HEALTH_PORTAL_DID: "did:web:portal.example.org";
+/** Synthetic individual DID exposed by one health portal. */
+export declare const EXAMPLE_PORTAL_INDIVIDUAL_DID: "did:web:portal.example.org:health-care:individual:multibase:zSubjectExample";
+/** Synthetic individual DID exposed by a second, independent portal. */
+export declare const EXAMPLE_ALTERNATE_PORTAL_INDIVIDUAL_DID: "did:web:cards.example.org:individual:multibase:zSubjectExample";
+/** Physical support/card DID used only to demonstrate that it is not an auth alias. */
+export declare const EXAMPLE_PHYSICAL_SUPPORT_DID: "did:web:cards.example.org:card:personal:000-000-000-001";
+export declare const EXAMPLE_SUBJECT_IDENTITY_BINDING_CREDENTIAL: Readonly<import("..").VerifiableCredentialV2>;

package/dist/examples/subject-identity-binding.js

@@ -0,0 +1,20 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { DataspaceSectors } from '../constants/sectors.js';
+import { buildSubjectIdentityBindingCredential } from '../utils/subject-identity-binding.js';
+/** Synthetic trusted portal DID used by binding examples and tests. */
+export const EXAMPLE_TRUSTED_HEALTH_PORTAL_DID = 'did:web:portal.example.org';
+/** Synthetic individual DID exposed by one health portal. */
+export const EXAMPLE_PORTAL_INDIVIDUAL_DID = 'did:web:portal.example.org:health-care:individual:multibase:zSubjectExample';
+/** Synthetic individual DID exposed by a second, independent portal. */
+export const EXAMPLE_ALTERNATE_PORTAL_INDIVIDUAL_DID = 'did:web:cards.example.org:individual:multibase:zSubjectExample';
+/** Physical support/card DID used only to demonstrate that it is not an auth alias. */
+export const EXAMPLE_PHYSICAL_SUPPORT_DID = 'did:web:cards.example.org:card:personal:000-000-000-001';
+export const EXAMPLE_SUBJECT_IDENTITY_BINDING_CREDENTIAL = Object.freeze(buildSubjectIdentityBindingCredential({
+    id: 'urn:uuid:subject-identity-binding-001',
+    issuerDid: EXAMPLE_TRUSTED_HEALTH_PORTAL_DID,
+    subjectDid: EXAMPLE_PORTAL_INDIVIDUAL_DID,
+    aliasDids: [EXAMPLE_ALTERNATE_PORTAL_INDIVIDUAL_DID],
+    sectors: [DataspaceSectors.HealthCare],
+    validFrom: '2026-01-01T00:00:00.000Z',
+    validUntil: '2027-01-01T00:00:00.000Z',
+}));

package/dist/models/index.d.ts

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

package/dist/models/index.js

@@ -48,6 +48,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-binding.js';
 export * from './urlPath.js';
 export * from './verifiable-credential.js';
 export * from './wallet.js';

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

@@ -0,0 +1,22 @@
+/** Canonical JSON members of a subject identity binding credential. */
+export declare const SubjectIdentityBindingClaims: Readonly<{
+    SubjectId: "id";
+    SameAs: "sameAs";
+    Sector: "sector";
+}>;
+/** Normalized, security-relevant projection of a subject identity binding VC. */
+export type SubjectIdentityBindingSummary = Readonly<{
+    issuerDid: string;
+    subjectDid: string;
+    aliasDids: readonly string[];
+    sectors: readonly string[];
+    validFrom?: string;
+    validUntil?: string;
+}>;
+/** Criteria used by a verifier after the enclosing VP has been verified. */
+export type SubjectIdentityBindingMatchCriteria = Readonly<{
+    trustedIssuerDids: readonly string[];
+    requiredSubjectDids: readonly string[];
+    sector?: string;
+    now?: string | Date;
+}>;

package/dist/models/subject-identity-binding.js

@@ -0,0 +1,7 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/** Canonical JSON members of a subject identity binding credential. */
+export const SubjectIdentityBindingClaims = Object.freeze({
+    SubjectId: 'id',
+    SameAs: 'sameAs',
+    Sector: 'sector',
+});

package/dist/utils/index.d.ts

@@ -99,6 +99,7 @@ export * from './permission-templates';
 export * from './smart-scope';
 export * from './service-act-reasons';
 export * from './same-as';
+export * from './subject-identity-binding';
 export * from './activation-request';
 export * from './vp-token';
 export * from './vital-sign-day-batch';

package/dist/utils/index.js

@@ -99,6 +99,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-binding.js';
 export * from './activation-request.js';
 export * from './vp-token.js';
 export * from './vital-sign-day-batch.js';

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

@@ -33,6 +33,19 @@ export type LegalOrganizationOnboardingDraftResult = Readonly<{
 export type LegalOrganizationGatewayVerificationSignatureFlow = 'certificate' | 'otp';
 export type LegalOrganizationGatewayVerificationRequestInput = Readonly<{
     controller: LegalOrganizationVerificationTransactionController;
+    /**
+     * Explicit public organization DID controlled by the registering portal.
+     * This is independent from the GW/service DID and from its network address.
+     */
+    publicOrganizationDid?: string;
+    /**
+     * Public portal domain used to derive the canonical path DID when
+     * `publicOrganizationDid` is omitted.
+     *
+     * Result:
+     * `did:web:<domain>:<sector>:organization:taxid:<tax-id>`
+     */
+    publicOrganizationDomain?: string;
     signatureFlow?: LegalOrganizationGatewayVerificationSignatureFlow;
     representativeSameAs?: string;
     verificationResourceType?: string;

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

@@ -1,5 +1,6 @@
 import { ClaimsOrganizationSchemaorg, ClaimsPersonSchemaorg, ClaimsServiceSchemaorg, } from '../constants/schemaorg.js';
 import { validateLegalOrganizationOnboardingClaims, } from './legal-organization-onboarding.js';
+import { buildHostedProviderDidWeb } from './did.js';
 function normalizeText(value) {
     return typeof value === 'string' ? value.trim() : '';
 }
@@ -275,16 +276,26 @@ export function createLegalOrganizationOnboardingFacade() {
         },
         buildGatewayVerificationRequest(fields, input) {
             const controllerEmail = facade.getControllerEmail(fields);
-            const serviceIdentifier = facade.getServiceIdentifier(fields);
             const serviceUrl = facade.getServiceUrl(fields);
+            const publicOrganizationDid = normalizeOptionalText(input.publicOrganizationDid);
+            const publicOrganizationDomain = normalizeOptionalText(input.publicOrganizationDomain);
+            const organizationDid = publicOrganizationDid || (publicOrganizationDomain
+                && facade.getServiceCategory(fields)
+                && facade.getTaxId(fields)
+                ? buildHostedProviderDidWeb({
+                    hostDomain: publicOrganizationDomain,
+                    sector: facade.getServiceCategory(fields),
+                    providerTaxId: facade.getTaxId(fields),
+                })
+                : undefined);
             const signatureFlow = normalizeText(input.signatureFlow || 'certificate').toLowerCase();
             const representativeSameAs = normalizeOptionalText(input.representativeSameAs || controllerEmail);
             const signedTermsPdfUrl = normalizeOptionalText(input.signedTermsPdfUrl);
             return facade.buildVerificationTransactionInput(fields, {
                 controller: input.controller,
-                organization: serviceIdentifier || serviceUrl
+                organization: organizationDid || serviceUrl
                     ? {
-                        ...(serviceIdentifier ? { did: serviceIdentifier } : {}),
+                        ...(organizationDid ? { did: organizationDid } : {}),
                         ...(serviceUrl ? { url: serviceUrl } : {}),
                     }
                     : undefined,

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

@@ -0,0 +1,28 @@
+import { type SubjectIdentityBindingMatchCriteria, type SubjectIdentityBindingSummary } from '../models/subject-identity-binding';
+import type { VerifiableCredentialV2 } from '../models/verifiable-credential';
+/**
+ * Builds the unsigned JSON form of a subject identity binding VC.
+ *
+ * This helper only builds the canonical payload. The issuer must sign it using
+ * the normal VC/VP signing flow before a verifier treats it as evidence.
+ */
+export declare function buildSubjectIdentityBindingCredential(input: Readonly<{
+    issuerDid: string;
+    subjectDid: string;
+    aliasDids: readonly string[];
+    sectors: readonly string[];
+    validFrom: string;
+    validUntil?: string;
+    id?: string;
+}>): VerifiableCredentialV2;
+/** Returns the normalized identity set asserted by one binding VC. */
+export declare function summarizeSubjectIdentityBinding(credential: unknown): SubjectIdentityBindingSummary | undefined;
+/** Checks issuer trust, validity, sector and exact DID membership. */
+export declare function matchesSubjectIdentityBinding(summary: SubjectIdentityBindingSummary | undefined, criteria: SubjectIdentityBindingMatchCriteria): boolean;
+/**
+ * Finds a matching binding credential in an already-verified VP token.
+ *
+ * This function decodes and matches claims; it does not verify signatures.
+ * Callers must first verify the enclosing VP/VC proof chain.
+ */
+export declare function getMatchingSubjectIdentityBindingFromVpToken(vpToken: string, criteria: SubjectIdentityBindingMatchCriteria): SubjectIdentityBindingSummary | undefined;

package/dist/utils/subject-identity-binding.js

@@ -0,0 +1,136 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { IndividualCredentialTypes, W3cCredentialContexts, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
+import { SubjectIdentityBindingClaims, } from '../models/subject-identity-binding.js';
+import { getVpCredentials } from './vp-token.js';
+function uniqueStrings(value) {
+    const values = Array.isArray(value) ? value : value ? [value] : [];
+    return Array.from(new Set(values.map((item) => String(item || '').trim()).filter(Boolean)));
+}
+function isDidWeb(value) {
+    return /^did:web:[^:\s]+(?::[^:\s]+)*$/.test(value);
+}
+function isPhysicalSupportDid(value) {
+    const segments = value.toLowerCase().split(':');
+    return segments.includes('card') || segments.includes('petd');
+}
+function isIndividualIdentityDid(value) {
+    return isDidWeb(value) && !isPhysicalSupportDid(value);
+}
+function includesCredentialType(credential) {
+    const types = uniqueStrings(credential?.type);
+    return types.includes(IndividualCredentialTypes.SubjectIdentityBindingCredential);
+}
+function normalizeNow(input) {
+    if (input instanceof Date)
+        return input.getTime();
+    if (input)
+        return new Date(input).getTime();
+    return Date.now();
+}
+/**
+ * Builds the unsigned JSON form of a subject identity binding VC.
+ *
+ * This helper only builds the canonical payload. The issuer must sign it using
+ * the normal VC/VP signing flow before a verifier treats it as evidence.
+ */
+export function buildSubjectIdentityBindingCredential(input) {
+    const issuerDid = String(input.issuerDid || '').trim();
+    const subjectDid = String(input.subjectDid || '').trim();
+    const aliasDids = uniqueStrings(input.aliasDids).filter((did) => did !== subjectDid);
+    const sectors = uniqueStrings(input.sectors);
+    if (!isDidWeb(issuerDid))
+        throw new Error('issuerDid must be a did:web identifier.');
+    if (!isIndividualIdentityDid(subjectDid)) {
+        throw new Error('subjectDid must be a did:web individual identifier, not a physical support DID.');
+    }
+    if (aliasDids.length === 0 || aliasDids.some((did) => !isIndividualIdentityDid(did))) {
+        throw new Error('aliasDids must contain at least one distinct did:web individual identifier and no physical support DID.');
+    }
+    if (sectors.length === 0)
+        throw new Error('sectors must contain at least one sector.');
+    if (!String(input.validFrom || '').trim() || Number.isNaN(Date.parse(input.validFrom))) {
+        throw new Error('validFrom must be an ISO date-time.');
+    }
+    if (input.validUntil && Number.isNaN(Date.parse(input.validUntil))) {
+        throw new Error('validUntil must be an ISO date-time.');
+    }
+    return {
+        '@context': [W3cCredentialContexts.V2],
+        ...(input.id ? { id: String(input.id).trim() } : {}),
+        type: [
+            W3cCredentialTypes.VerifiableCredential,
+            IndividualCredentialTypes.SubjectIdentityBindingCredential,
+        ],
+        issuer: issuerDid,
+        validFrom: String(input.validFrom).trim(),
+        ...(input.validUntil ? { validUntil: String(input.validUntil).trim() } : {}),
+        credentialSubject: {
+            [SubjectIdentityBindingClaims.SubjectId]: subjectDid,
+            [SubjectIdentityBindingClaims.SameAs]: aliasDids,
+            [SubjectIdentityBindingClaims.Sector]: sectors,
+        },
+    };
+}
+/** Returns the normalized identity set asserted by one binding VC. */
+export function summarizeSubjectIdentityBinding(credential) {
+    if (!credential || typeof credential !== 'object' || !includesCredentialType(credential))
+        return undefined;
+    const source = credential;
+    const issuerDid = String(source.issuer?.id || source.issuer || '').trim();
+    const subject = source.credentialSubject || {};
+    const subjectDid = String(subject[SubjectIdentityBindingClaims.SubjectId] || '').trim();
+    const aliasDids = uniqueStrings(subject[SubjectIdentityBindingClaims.SameAs])
+        .filter((did) => did !== subjectDid);
+    const sectors = uniqueStrings(subject[SubjectIdentityBindingClaims.Sector]);
+    if (!isDidWeb(issuerDid) || !isIndividualIdentityDid(subjectDid) || aliasDids.length === 0)
+        return undefined;
+    if (aliasDids.some((did) => !isIndividualIdentityDid(did)) || sectors.length === 0)
+        return undefined;
+    return {
+        issuerDid,
+        subjectDid,
+        aliasDids,
+        sectors,
+        validFrom: String(source.validFrom || '').trim() || undefined,
+        validUntil: String(source.validUntil || '').trim() || undefined,
+    };
+}
+/** Checks issuer trust, validity, sector and exact DID membership. */
+export function matchesSubjectIdentityBinding(summary, criteria) {
+    if (!summary)
+        return false;
+    if (!criteria.trustedIssuerDids.includes(summary.issuerDid))
+        return false;
+    const now = normalizeNow(criteria.now);
+    if (Number.isNaN(now))
+        return false;
+    if (summary.validFrom) {
+        const start = Date.parse(summary.validFrom);
+        if (Number.isNaN(start) || start > now)
+            return false;
+    }
+    if (summary.validUntil) {
+        const end = Date.parse(summary.validUntil);
+        if (Number.isNaN(end) || end < now)
+            return false;
+    }
+    if (criteria.sector && !summary.sectors.includes(criteria.sector))
+        return false;
+    const identities = new Set([summary.subjectDid, ...summary.aliasDids]);
+    const required = uniqueStrings(criteria.requiredSubjectDids);
+    return required.length > 0 && required.every((did) => identities.has(did));
+}
+/**
+ * Finds a matching binding credential in an already-verified VP token.
+ *
+ * This function decodes and matches claims; it does not verify signatures.
+ * Callers must first verify the enclosing VP/VC proof chain.
+ */
+export function getMatchingSubjectIdentityBindingFromVpToken(vpToken, criteria) {
+    for (const credential of getVpCredentials(vpToken)) {
+        const summary = summarizeSubjectIdentityBinding(credential);
+        if (matchesSubjectIdentityBinding(summary, criteria))
+            return summary;
+    }
+    return undefined;
+}

package/package.json

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