gdc-common-utils-ts 2.9.5 → 2.9.6

package/README.md

@@ -240,6 +240,13 @@ The `utils` export exposes reusable helpers for DID and message handling, such a
 
 These helpers support DIDComm-style message construction and related transport/data-shaping workflows.
 
+The high-level [federated SMART authorization profile](docs/101-SMART_AUTHORIZATION_PROFILE.md)
+defines the two-step emergency flow: resolve the individual's index provider
+from an opaque subject-identifier ledger key, then ask any available trusted
+tenant to issue one token whose `aud` remains that resolved index provider.
+The ledger value is only `{ indexProviderDid: 'did:web:...' }`; the same opaque
+key is presented later to that provider to retrieve the protected card/index.
+
 Example:
 
 ```ts

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

@@ -1,27 +1,10 @@
-/** Public provider pointer stored for one opaque subject-identifier asset. */
-export type SubjectIdentifierProviderPointer = Readonly<{
-    identifier: Readonly<{
-        value: string;
-    }>;
-    /** Bare DNS domain: no URL scheme, path, DID or tenant identifier. */
-    url: string;
-}>;
-/** 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;
-}>;
 /**
- * @deprecated Parse canonical Person/Animal/Place Bundle entries with
- * `readSubjectIdentityBundleEntry` instead. Kept for 2.x compatibility only.
+ * Minimal public payload stored for one opaque subject-identifier lookup key.
+ *
+ * `indexProviderDid` is the resolvable `did:web` of the provider that owns the
+ * protected subject index. The ledger payload contains no card, subject,
+ * contact identifier, provider code, domain duplicate or authorization data.
  */
-export type SubjectIdentifierLedgerBundleEntry = Readonly<{
-    sameAs: string | readonly string[];
+export type SubjectIdentifierLedgerPayload = Readonly<{
+    indexProviderDid: string;
 }>;

package/dist/utils/index.d.ts

@@ -107,6 +107,7 @@ export * from './object-sanitize';
 export * from './unified-health-id';
 export * from './permission-templates';
 export * from './smart-scope';
+export * from './smart-authorization-profile';
 export * from './service-act-reasons';
 export * from './same-as';
 export * from './subject-identity';

package/dist/utils/index.js

@@ -107,6 +107,7 @@ export * from './object-sanitize.js';
 export * from './unified-health-id.js';
 export * from './permission-templates.js';
 export * from './smart-scope.js';
+export * from './smart-authorization-profile.js';
 export * from './service-act-reasons.js';
 export * from './same-as.js';
 export * from './subject-identity.js';

package/dist/utils/smart-authorization-profile.d.ts

@@ -0,0 +1,46 @@
+import { CommunicationTopicCodes } from '../constants/communication';
+/** Extension members carried inside an RFC 7662/9701 introspection result. */
+export declare const SmartIntrospectionExtensionFields: Readonly<{
+    /** OpenID4VP presentation transport member; its value retains its native format. */
+    readonly VpToken: "vp_token";
+}>;
+/** VC Data Model 2.0 media types for JOSE-secured presentations. */
+export declare const VerifiablePresentationMediaTypes: Readonly<{
+    readonly Jwt: "application/vp+jwt";
+}>;
+export type FhirEmergencyAuthorizationDetail = Readonly<{
+    type: string;
+    actions: readonly ['read'];
+    datatypes: readonly string[];
+    identifier: string;
+    privileges: readonly [typeof CommunicationTopicCodes.BreakTheGlass.attributeValue];
+}>;
+export type BuildFhirEmergencyAuthorizationDetailsInput = Readonly<{
+    /** Collision-resistant RFC 9396 type URI owned by the applicable domain profile. */
+    authorizationDetailType: string;
+    /** Stable subject identifier governed by the emergency decision. */
+    subject: string;
+    /** Granted read-only SMART scopes from which FHIR resource types are projected. */
+    scopes: readonly string[];
+}>;
+/**
+ * Builds the RFC 9396 representation of one read-only FHIR emergency grant.
+ *
+ * Only RFC 9396 common member names are emitted. Incident, Consent and audit
+ * identifiers remain server-side evidence correlated by the access-token
+ * `jti`; they are deliberately not copied into private flat JWT claims.
+ */
+export declare function buildFhirEmergencyAuthorizationDetails(input: BuildFhirEmergencyAuthorizationDetailsInput): readonly [FhirEmergencyAuthorizationDetail];
+export type VerifiablePresentationJwtPayloadResult = Readonly<{
+    presentation: Readonly<Record<string, unknown>>;
+    format: 'vc-data-model-2.0' | 'legacy-jwt-vp';
+}>;
+/**
+ * Reads a verified JOSE payload without confusing transport and data model.
+ *
+ * VC Data Model 2.0 `application/vp+jwt` encodes the presentation directly as
+ * the JWT Claims Set and forbids a wrapper claim named `vp`. The historical
+ * JWT-VP wrapper remains readable only as an explicitly reported compatibility
+ * format so callers can measure and eventually remove it.
+ */
+export declare function readVerifiablePresentationJwtPayload(payload: unknown): VerifiablePresentationJwtPayloadResult;

package/dist/utils/smart-authorization-profile.js

@@ -0,0 +1,88 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { CommunicationTopicCodes } from '../constants/communication.js';
+/** Extension members carried inside an RFC 7662/9701 introspection result. */
+export const SmartIntrospectionExtensionFields = Object.freeze({
+    /** OpenID4VP presentation transport member; its value retains its native format. */
+    VpToken: 'vp_token',
+});
+/** VC Data Model 2.0 media types for JOSE-secured presentations. */
+export const VerifiablePresentationMediaTypes = Object.freeze({
+    Jwt: 'application/vp+jwt',
+});
+function readScopeDatatype(scope) {
+    const head = String(scope || '').trim().split('?', 1)[0] || '';
+    const slash = head.indexOf('/');
+    const dot = head.lastIndexOf('.');
+    if (slash < 0 || dot <= slash + 1)
+        return undefined;
+    const permission = head.slice(dot + 1).toLowerCase();
+    if (permission !== 'r' && permission !== 'rs')
+        return undefined;
+    const datatype = head.slice(slash + 1, dot).trim();
+    return datatype || undefined;
+}
+/**
+ * Builds the RFC 9396 representation of one read-only FHIR emergency grant.
+ *
+ * Only RFC 9396 common member names are emitted. Incident, Consent and audit
+ * identifiers remain server-side evidence correlated by the access-token
+ * `jti`; they are deliberately not copied into private flat JWT claims.
+ */
+export function buildFhirEmergencyAuthorizationDetails(input) {
+    const authorizationDetailType = String(input.authorizationDetailType || '').trim();
+    try {
+        if (!authorizationDetailType || !new URL(authorizationDetailType).protocol)
+            throw new Error();
+    }
+    catch {
+        throw new Error('authorization_detail_type_uri_required');
+    }
+    const subject = String(input.subject || '').trim();
+    if (!subject)
+        throw new Error('emergency_subject_required');
+    const datatypes = Array.from(new Set(input.scopes.map(readScopeDatatype).filter((value) => Boolean(value))));
+    if (datatypes.length === 0 || datatypes.length !== input.scopes.length) {
+        throw new Error('read_only_smart_scope_required');
+    }
+    return [{
+            type: authorizationDetailType,
+            actions: ['read'],
+            datatypes,
+            identifier: subject,
+            privileges: [CommunicationTopicCodes.BreakTheGlass.attributeValue],
+        }];
+}
+function isPresentation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const type = value.type;
+    const types = Array.isArray(type) ? type : [type];
+    return types.some((entry) => String(entry || '') === 'VerifiablePresentation');
+}
+/**
+ * Reads a verified JOSE payload without confusing transport and data model.
+ *
+ * VC Data Model 2.0 `application/vp+jwt` encodes the presentation directly as
+ * the JWT Claims Set and forbids a wrapper claim named `vp`. The historical
+ * JWT-VP wrapper remains readable only as an explicitly reported compatibility
+ * format so callers can measure and eventually remove it.
+ */
+export function readVerifiablePresentationJwtPayload(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new Error('invalid_verifiable_presentation_payload');
+    }
+    const record = payload;
+    const legacyVp = record.vp;
+    const hasDirectPresentation = isPresentation(record);
+    const hasLegacyPresentation = isPresentation(legacyVp);
+    if (hasDirectPresentation && 'vp' in record) {
+        throw new Error('ambiguous_verifiable_presentation_payload');
+    }
+    if (hasDirectPresentation) {
+        return { presentation: record, format: 'vc-data-model-2.0' };
+    }
+    if (hasLegacyPresentation) {
+        return { presentation: legacyVp, format: 'legacy-jwt-vp' };
+    }
+    throw new Error('invalid_verifiable_presentation_payload');
+}

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

@@ -1,5 +1,6 @@
 import type { BundleEntry } from '../models/bundle';
 import type { SubjectIdentityAssociation, SubjectIdentityBundleEntry, SubjectIdentityInput } from '../models/subject-identity';
+import type { SubjectIdentifierLedgerPayload } from '../models/subject-identifier-ledger';
 /**
  * Builds the exact UTF-8 token used by the distributed Subject lookup.
  *
@@ -18,6 +19,16 @@ export declare function buildSubjectIdentifierToken(input: Pick<SubjectIdentityI
  * included in the Fabric payload.
  */
 export declare function buildSubjectIdentifierAssetId(input: Pick<SubjectIdentityInput, 'codingSystem' | 'jurisdiction' | 'codeValue'>): string;
+/**
+ * Builds the complete public value stored under an opaque subject identifier.
+ *
+ * The provider DID is deliberately the only payload field. DID resolution
+ * discovers its service endpoint; the protected provider lookup then uses the
+ * same opaque asset id to resolve the subject/card and authorized index.
+ */
+export declare function buildSubjectIdentifierLedgerPayload(indexProviderDid: string): SubjectIdentifierLedgerPayload;
+/** Reads the strict provider-only subject-identifier ledger payload. */
+export declare function readSubjectIdentifierLedgerPayload(payload: unknown): string;
 /**
  * Builds one semantic identity resource for the neutral Subject collection.
  *

package/dist/utils/subject-identity.js

@@ -1,6 +1,7 @@
 import { UrnPrefixes } from '../constants/urn.js';
 import { encodeMultibaseSha3 } from './multibasehash.js';
 import { normalizeIndividualIdentifierType } from './individual-identifier.js';
+import { normalizeDidWeb } from './did.js';
 const SUBJECT_RESOURCE_BY_KIND = {
     person: 'Person',
     animal: 'Animal',
@@ -13,6 +14,7 @@ const SUBJECT_KIND_BY_RESOURCE = {
 };
 const STABLE_CARD_ID_PATTERN = /^(?:did|urn|https):\S+$/i;
 const ISO_3166_JURISDICTION_PATTERN = /^[A-Z]{2}(?:-[A-Z0-9]{1,3})?$/;
+const DID_WEB_PATTERN = /^did:web:[^\s#?]+$/;
 /**
  * Builds the exact UTF-8 token used by the distributed Subject lookup.
  *
@@ -38,6 +40,31 @@ export function buildSubjectIdentifierToken(input) {
 export function buildSubjectIdentifierAssetId(input) {
     return `${UrnPrefixes.Multibase}${encodeMultibaseSha3(buildSubjectIdentifierToken(input), 384)}`;
 }
+/**
+ * Builds the complete public value stored under an opaque subject identifier.
+ *
+ * The provider DID is deliberately the only payload field. DID resolution
+ * discovers its service endpoint; the protected provider lookup then uses the
+ * same opaque asset id to resolve the subject/card and authorized index.
+ */
+export function buildSubjectIdentifierLedgerPayload(indexProviderDid) {
+    const normalized = normalizeDidWeb(String(indexProviderDid || '').trim());
+    if (!DID_WEB_PATTERN.test(normalized)) {
+        throw new TypeError('indexProviderDid must be a did:web identifier');
+    }
+    return { indexProviderDid: normalized };
+}
+/** Reads the strict provider-only subject-identifier ledger payload. */
+export function readSubjectIdentifierLedgerPayload(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new TypeError('subject_identifier_payload_must_contain_only_index_provider_did');
+    }
+    const record = payload;
+    if (Object.keys(record).length !== 1 || !Object.hasOwn(record, 'indexProviderDid')) {
+        throw new TypeError('subject_identifier_payload_must_contain_only_index_provider_did');
+    }
+    return buildSubjectIdentifierLedgerPayload(String(record.indexProviderDid || '')).indexProviderDid;
+}
 /**
  * Builds one semantic identity resource for the neutral Subject collection.
  *

package/package.json

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