gdc-sdk-node-ts 2.3.1 → 2.3.2

package/dist/did-web-recipient.d.ts

@@ -0,0 +1,18 @@
+import type { JWK } from 'gdc-common-utils-ts/models/jwk';
+export type ResolveDidWebKeyAgreementJwkOptions = Readonly<{
+    fetchImpl?: typeof fetch;
+    /**
+     * Transport override for a local/private route serving the same DID document.
+     * The returned document must still identify itself with the requested DID.
+     */
+    didDocumentUrl?: string;
+}>;
+/**
+ * Resolves the first public key-agreement JWK from a did:web document.
+ *
+ * The DID remains the recipient identity and the document remains the source
+ * of its public keys. `didDocumentUrl` changes only the HTTP route used to
+ * retrieve that same document, which is useful when a local GW publishes its
+ * external DID while being reached through localhost.
+ */
+export declare function resolveDidWebKeyAgreementJwk(recipientDid: string, options?: ResolveDidWebKeyAgreementJwkOptions): Promise<JWK>;

package/dist/did-web-recipient.js

@@ -0,0 +1,46 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { getBaseUrlFromDidWeb, normalizeDidWeb } from 'gdc-common-utils-ts/utils/did';
+/**
+ * Resolves the first public key-agreement JWK from a did:web document.
+ *
+ * The DID remains the recipient identity and the document remains the source
+ * of its public keys. `didDocumentUrl` changes only the HTTP route used to
+ * retrieve that same document, which is useful when a local GW publishes its
+ * external DID while being reached through localhost.
+ */
+export async function resolveDidWebKeyAgreementJwk(recipientDid, options = {}) {
+    const did = normalizeDidWeb(String(recipientDid || '').trim());
+    if (!did.startsWith('did:web:')) {
+        throw new Error('resolveDidWebKeyAgreementJwk requires a did:web recipient.');
+    }
+    const didDocumentUrl = String(options.didDocumentUrl || '').trim()
+        || `${getBaseUrlFromDidWeb(did)}.well-known/did.json`;
+    const response = await (options.fetchImpl || fetch)(didDocumentUrl, {
+        headers: { Accept: 'application/did+json, application/json' },
+    });
+    if (!response.ok) {
+        throw new Error(`Could not resolve DID document '${did}' (HTTP ${response.status}).`);
+    }
+    const document = await response.json();
+    if (normalizeDidWeb(String(document.id || '').trim()) !== did) {
+        throw new Error(`Resolved DID document does not belong to '${did}'.`);
+    }
+    const methods = new Map((document.verificationMethod || []).map((method) => [method.id, method]));
+    for (const agreement of document.keyAgreement || []) {
+        const method = typeof agreement === 'string' ? methods.get(agreement) : agreement;
+        const jwk = publicKeyAgreementJwk(method);
+        if (jwk)
+            return jwk;
+    }
+    throw new Error(`DID document '${did}' has no public keyAgreement JWK.`);
+}
+function publicKeyAgreementJwk(method) {
+    const publicKeyJwk = method?.publicKeyJwk;
+    if (!publicKeyJwk || typeof publicKeyJwk !== 'object')
+        return undefined;
+    if (publicKeyJwk.use && publicKeyJwk.use !== 'enc')
+        return undefined;
+    if (publicKeyJwk.kid || !method?.id.includes('#'))
+        return publicKeyJwk;
+    return { ...publicKeyJwk, kid: method.id.slice(method.id.lastIndexOf('#') + 1) };
+}

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export * from './UserProfileIndexStore.js';
 export * from './wallet-backed-job-manager.js';
 export * from './node-crypto-helper.js';
 export * from './node-managed-wallet.js';
+export * from './did-web-recipient.js';
 export * from './constants/lifecycle.js';
 export * from './consent-claim-helpers.js';
 export * from './session.js';

package/dist/index.js

@@ -27,6 +27,7 @@ export * from './UserProfileIndexStore.js';
 export * from './wallet-backed-job-manager.js';
 export * from './node-crypto-helper.js';
 export * from './node-managed-wallet.js';
+export * from './did-web-recipient.js';
 export * from './constants/lifecycle.js';
 export * from './consent-claim-helpers.js';
 export * from './session.js';

package/dist/node-managed-wallet.d.ts

@@ -51,9 +51,7 @@ export declare class NodeManagedWallet implements IWallet {
      * Computes a digest of a string using the configured runtime helper.
      */
     digest(data: string, algorithm: string): Promise<string>;
-    /**
-     * Protects one confidential document using one owner-specific symmetric storage key.
-     */
+    /** Protects one document with a random AES-256-GCM CEK wrapped to the owner's storage ML-KEM key. */
     protectConfidentialData(doc: any, entityId: string): Promise<any>;
     /**
      * Protects one confidential document using the richer execution-context model.
@@ -140,8 +138,6 @@ export declare class NodeManagedWallet implements IWallet {
     private resolveOwnerId;
     private resolveStorageOwnerId;
     private createManagedKey;
-    private createStorageKey;
-    private requireStorageKey;
     private requireManagedKey;
     private inferRelevantScopes;
     private matchesSelection;

package/dist/node-managed-wallet.js

@@ -13,6 +13,7 @@ const DEFAULT_POLICY = {
         'vc-signing': 'ES384',
         'comm-signing': 'ML-DSA-44',
         'comm-encryption': 'ML-KEM-768',
+        'document-at-rest': 'ML-KEM-768',
     },
 };
 /**
@@ -99,9 +100,6 @@ export class NodeManagedWallet {
             ownerState.keys.push(descriptor);
             created.push(descriptor.descriptor.publicJwk);
         }
-        if (!ownerState.storageKey) {
-            ownerState.storageKey = await this.createStorageKey(request, ownerId);
-        }
         return { keys: created };
     }
     /**
@@ -136,9 +134,7 @@ export class NodeManagedWallet {
     async digest(data, algorithm) {
         return this.cryptoHelper.digestString(data, algorithm);
     }
-    /**
-     * Protects one confidential document using one owner-specific symmetric storage key.
-     */
+    /** Protects one document with a random AES-256-GCM CEK wrapped to the owner's storage ML-KEM key. */
     async protectConfidentialData(doc, entityId) {
         return this.protectManagedConfidentialData(doc, {
             profile: { profileId: entityId },
@@ -151,10 +147,24 @@ export class NodeManagedWallet {
     async protectManagedConfidentialData(doc, context, _options) {
         if (!doc?.content)
             return doc;
-        const storageKey = this.requireStorageKey(context);
+        const storageKey = this.requireManagedKey(context, {
+            ownerScope: context.profile?.profileId ? 'profile' : 'runtime',
+            purpose: 'document-at-rest',
+        }, 'enc');
         const ownerId = this.resolveStorageOwnerId(context);
-        const contentString = JSON.stringify(doc.content);
-        const encrypted = await this.cryptography.encrypt(contentString, storageKey, ownerId);
+        const ownerBinding = createHash('sha256').update(ownerId).digest('base64url');
+        const privateJwk = {
+            ...storageKey.descriptor.publicJwk,
+            dBytes: storageKey.privateMaterial,
+        };
+        const encrypted = await this.cryptography.encryptJweToCompact(JSON.stringify(doc.content), {
+            typ: 'gdc-confidential-document+jwe',
+            cty: 'application/json',
+            enc: 'A256GCM',
+            gdc_pq_profile: 'confidential-pqc-v1',
+            gdc_key_purpose: 'document-at-rest',
+            gdc_owner_binding: ownerBinding,
+        }, privateJwk, storageKey.descriptor.publicJwk);
         const { content, ...docWithoutContent } = doc;
         return {
             ...docWithoutContent,
@@ -176,13 +186,26 @@ export class NodeManagedWallet {
     async unprotectManagedConfidentialData(doc, context, _options) {
         if (!doc?.jwe)
             return doc;
-        const storageKey = this.requireStorageKey(context);
+        const storageKey = this.requireManagedKey(context, {
+            ownerScope: context.profile?.profileId ? 'profile' : 'runtime',
+            purpose: 'document-at-rest',
+        }, 'enc');
         const ownerId = this.resolveStorageOwnerId(context);
-        const decrypted = await this.cryptography.decrypt(doc.jwe, storageKey, ownerId);
+        const privateJwk = {
+            ...storageKey.descriptor.publicJwk,
+            dBytes: storageKey.privateMaterial,
+        };
+        const decrypted = await this.cryptography.decryptJwe(doc.jwe, privateJwk);
+        const header = decrypted.protectedHeader;
+        if (header.gdc_pq_profile !== 'confidential-pqc-v1'
+            || header.gdc_key_purpose !== 'document-at-rest'
+            || header.gdc_owner_binding !== createHash('sha256').update(ownerId).digest('base64url')) {
+            throw new Error('Confidential document is not bound to this storage owner and policy.');
+        }
         const { jwe, ...docWithoutJwe } = doc;
         return {
             ...docWithoutJwe,
-            content: JSON.parse(decrypted),
+            content: JSON.parse(Content.bytesToStringUTF8(decrypted.decryptedBytes)),
         };
     }
     /**
@@ -480,25 +503,6 @@ export class NodeManagedWallet {
             privateMaterial: signer.getPrivateMaterial(),
         };
     }
-    async createStorageKey(request, ownerId) {
-        if (request.mode === 'deterministic' && request.seedMaterial !== undefined) {
-            return this.deriveSeedBytes(request.seedMaterial, ownerId, 'document-at-rest', 32);
-        }
-        return this.cryptoHelper.getRandomBytes(32);
-    }
-    requireStorageKey(context) {
-        if (context.profile?.profileId) {
-            const state = this.owners.get(`profile:${context.profile.profileId}:${context.walletId ?? 'default'}`);
-            if (state?.storageKey)
-                return state.storageKey;
-        }
-        if (context.runtime?.runtimeId) {
-            const state = this.owners.get(`runtime:${context.runtime.runtimeId}:${context.walletId ?? 'default'}`);
-            if (state?.storageKey)
-                return state.storageKey;
-        }
-        throw new Error('NodeManagedWallet has no storage key for the provided context. Provision keys first.');
-    }
     requireManagedKey(context, selection, expectedUse) {
         if (selection.keyId) {
             for (const ownerState of this.owners.values()) {

package/dist/orchestration/individual-controller-sdk.d.ts

@@ -79,7 +79,11 @@ export declare class IndividualControllerSdk {
      */
     importIpsOrFhirAndUpdateIndex(ctx: RouteContext, input: IpsOrFhirImportInput): Promise<SubmitAndPollResult>;
     /**
-     * Creates or updates a `RelatedPerson` for non-employee caregivers or family members.
+     * Compatibility adapter for the older direct `RelatedPerson` route.
+     *
+     * @deprecated Author one or more typed RelatedPerson entries in a Bundle,
+     * attach that completed Bundle to a Communication outbox job, and call
+     * `ingestCommunicationAndUpdateIndex(...)`.
      */
     upsertRelatedPersonAndPoll(ctx: RouteContext, input: RelatedPersonUpsertInput): Promise<SubmitAndPollResult>;
     /**

package/dist/orchestration/individual-controller-sdk.js

@@ -111,7 +111,11 @@ export class IndividualControllerSdk {
         return requireClientMethod(this.client, 'importIpsOrFhirAndUpdateIndex')(ctx, input);
     }
     /**
-     * Creates or updates a `RelatedPerson` for non-employee caregivers or family members.
+     * Compatibility adapter for the older direct `RelatedPerson` route.
+     *
+     * @deprecated Author one or more typed RelatedPerson entries in a Bundle,
+     * attach that completed Bundle to a Communication outbox job, and call
+     * `ingestCommunicationAndUpdateIndex(...)`.
      */
     upsertRelatedPersonAndPoll(ctx, input) {
         assertFacadeCapability(this.capabilities, ActorCapabilities.IndividualUpsertRelatedPerson, ActorKinds.IndividualController, 'upsertRelatedPersonAndPoll');

package/dist/orchestration/individual-member-sdk.d.ts

@@ -7,7 +7,10 @@ export declare class IndividualMemberSdk {
     private readonly client;
     constructor(client: NodeRuntimeClient);
     /**
-     * Creates or updates the member/caregiver `RelatedPerson` relationship to the subject.
+     * Compatibility adapter for the older direct `RelatedPerson` route.
+     *
+     * @deprecated Author a typed RelatedPerson Bundle, attach it to a
+     * Communication outbox job, and call `ingestCommunicationAndUpdateIndex(...)`.
      */
     upsertRelatedPersonAndPoll(ctx: RouteContext, input: RelatedPersonUpsertInput): Promise<import("gdc-sdk-core-ts/polling-model.js").SubmitAndPollResult>;
     /**

package/dist/orchestration/individual-member-sdk.js

@@ -6,7 +6,10 @@ export class IndividualMemberSdk {
         this.client = client;
     }
     /**
-     * Creates or updates the member/caregiver `RelatedPerson` relationship to the subject.
+     * Compatibility adapter for the older direct `RelatedPerson` route.
+     *
+     * @deprecated Author a typed RelatedPerson Bundle, attach it to a
+     * Communication outbox job, and call `ingestCommunicationAndUpdateIndex(...)`.
      */
     upsertRelatedPersonAndPoll(ctx, input) {
         return requireClientMethod(this.client, 'upsertRelatedPersonAndPoll')(ctx, input);

package/dist/server-profile-session.d.ts

@@ -1,5 +1,6 @@
 import type { JWK } from 'gdc-common-utils-ts/models/jwk';
 import type { ActorKind } from 'gdc-common-utils-ts/models/actor-session';
+import type { ConfidentialStorageProfile } from 'gdc-sdk-core-ts';
 import type { RouteContext } from './individual-onboarding.js';
 import type { SecureDidcommTransportAdapter } from 'gdc-sdk-core-ts';
 import { type PinProtectedProfileSecret, type ProfileProtectionOptions, type ServerProfileSealer } from './server-profile-protection.js';
@@ -19,6 +20,10 @@ export type ServerProfileRecord = Readonly<{
     clientId: string;
     deviceDid: string;
     publicJwks: Record<string, unknown>[];
+    /** Public recipient key for local confidential storage; not a DCR communication key. */
+    storagePublicJwk?: Record<string, unknown>;
+    /** Server-owned policy; browser input is never authoritative for this value. */
+    confidentialStorageProfile?: ConfidentialStorageProfile;
     protectedWalletSeed: PinProtectedProfileSecret;
     protectedVpToken: PinProtectedProfileSecret;
     failedUnlocks: number;
@@ -77,18 +82,30 @@ export type ResolvedServerProfileSession = Readonly<{
     scopes: string[];
     accessToken: string;
     secureTransportAdapter: SecureDidcommTransportAdapter;
+    /** Storage adapter available only while the PIN-unlocked session is alive. */
+    confidentialStorageAdapter: Readonly<{
+        protect(document: Readonly<{
+            id?: string;
+            content: unknown;
+        }>): Promise<unknown>;
+        unprotect(document: Readonly<{
+            id?: string;
+            jwe: string;
+        }>): Promise<unknown>;
+    }>;
 }>;
 export type ServerProfileSessionManagerOptions = Readonly<{
     store: ServerProfileStore;
     sealer: ServerProfileSealer;
     gatewayBaseUrl: string;
-    recipientDid: string;
     resolveRecipientJwk: (recipientDid: string) => Promise<JWK>;
     fetchImpl?: typeof fetch;
     sessionTtlSeconds?: number;
     maxFailedUnlocks?: number;
     lockSeconds?: number;
     profileProtection?: ProfileProtectionOptions;
+    /** Product/tenant policy applied to enrollment and upgraded on next PIN unlock. */
+    requiredConfidentialStorageProfile?: ConfidentialStorageProfile;
     now?: () => Date;
 }>;
 /**
@@ -109,6 +126,13 @@ export declare class ServerProfileSessionManager {
     lock(ownerId: string, sessionId: string): Promise<void>;
     private createClient;
     private createWallet;
+    /**
+     * Upgrade legacy profiles deterministically after successful PIN unlock.
+     * The protected seed already owns the storage pair, so migration neither
+     * exports a private key nor calls KMS/GW. Only its public JWK and policy label
+     * are added to the durable profile record.
+     */
+    private ensureRequiredStorageProfile;
     private requireOwnedProfile;
     private requireSubject;
     private now;

package/dist/server-profile-session.js

@@ -21,6 +21,9 @@ export class ServerProfileSessionManager {
         const wallet = await this.createWallet(input.profileId, seed);
         const context = walletContext(input.profileId);
         const publicKeys = await wallet.getPublicJwks(context, {});
+        const storagePublicJwk = publicKeys.find((entry) => entry.purpose === 'document-at-rest')?.publicJwk;
+        if (!storagePublicJwk)
+            throw new Error('Server profile enrollment requires a document-at-rest ML-KEM key.');
         const client = this.createClient(input.routeContext, input.idToken);
         const activation = await client.activateProfileDeviceWithActivationRequest({
             ...input.routeContext,
@@ -30,7 +33,7 @@ export class ServerProfileSessionManager {
                 application_type: 'web',
                 actor_did: input.actorDid,
                 profile_did: input.profileDid,
-                jwks: { keys: publicKeys.map((entry) => entry.publicJwk) },
+                jwks: { keys: publicKeys.filter((entry) => entry.purpose !== 'document-at-rest').map((entry) => entry.publicJwk) },
             },
         });
         const dcrBody = terminalBody(activation.dcr.poll.body);
@@ -51,7 +54,9 @@ export class ServerProfileSessionManager {
             allowedSubjectDids: unique(input.allowedSubjectDids),
             clientId,
             deviceDid,
-            publicJwks: publicKeys.map((entry) => entry.publicJwk),
+            publicJwks: publicKeys.filter((entry) => entry.purpose !== 'document-at-rest').map((entry) => entry.publicJwk),
+            storagePublicJwk: storagePublicJwk,
+            confidentialStorageProfile: this.options.requiredConfidentialStorageProfile ?? 'confidential-basic-v1',
             protectedWalletSeed: await protectServerProfileSecret(seed, input.pin, `${input.profileId}:wallet-seed`, this.options.sealer, this.options.profileProtection),
             protectedVpToken: await protectServerProfileSecret(input.vpToken, input.pin, `${input.profileId}:vp-token`, this.options.sealer, this.options.profileProtection),
             failedUnlocks: 0,
@@ -65,7 +70,7 @@ export class ServerProfileSessionManager {
         return this.options.store.listProfiles(ownerId);
     }
     async unlock(input) {
-        const profile = await this.requireOwnedProfile(input.ownerId, input.profileId);
+        let profile = await this.requireOwnedProfile(input.ownerId, input.profileId);
         this.requireSubject(profile, input.subjectDid);
         const now = this.now();
         if (profile.lockedUntil && new Date(profile.lockedUntil) > now) {
@@ -88,6 +93,7 @@ export class ServerProfileSessionManager {
             await this.options.store.putProfile({ ...profile, failedUnlocks: failures, lockedUntil, updatedAt: now.toISOString() });
             throw new Error('Profile PIN rejected.');
         }
+        profile = await this.ensureRequiredStorageProfile(profile, seed);
         const wallet = await this.createWallet(profile.profileId, seed);
         const assertion = await buildWalletClientAssertion(wallet, profile, this.options.gatewayBaseUrl, now);
         const token = await this.createClient(profile.routeContext, input.idToken).requestSmartToken({
@@ -141,9 +147,13 @@ export class ServerProfileSessionManager {
             scopes: session.scopes,
             accessToken: await this.options.sealer.unseal(session.sealedAccessToken, `${sessionId}:access-token`),
             secureTransportAdapter: {
-                pack: (message) => wallet.packForRecipientWithContext(message, this.options.recipientDid, { context }),
+                pack: (message) => wallet.packForRecipientWithContext(message, profile.providerDid, { context }),
                 unpack: async (jwe) => (await wallet.unpackWithContext(jwe, { context })).content,
             },
+            confidentialStorageAdapter: {
+                protect: (document) => wallet.protectManagedConfidentialData(document, context),
+                unprotect: (document) => wallet.unprotectManagedConfidentialData(document, context),
+            },
         };
     }
     async lock(ownerId, sessionId) {
@@ -164,7 +174,7 @@ export class ServerProfileSessionManager {
         const context = walletContext(profileId);
         await wallet.provisionManagedKeys(context, {
             ownerScope: 'profile',
-            purposes: ['actor-signing'],
+            purposes: ['actor-signing', 'document-at-rest'],
             mode: 'deterministic',
             seedMaterial: seed,
         });
@@ -176,6 +186,35 @@ export class ServerProfileSessionManager {
         });
         return wallet;
     }
+    /**
+     * Upgrade legacy profiles deterministically after successful PIN unlock.
+     * The protected seed already owns the storage pair, so migration neither
+     * exports a private key nor calls KMS/GW. Only its public JWK and policy label
+     * are added to the durable profile record.
+     */
+    async ensureRequiredStorageProfile(profile, seed) {
+        const required = this.options.requiredConfidentialStorageProfile ?? profile.confidentialStorageProfile ?? 'confidential-basic-v1';
+        if (required !== 'confidential-pqc-v1')
+            return profile;
+        const wallet = await this.createWallet(profile.profileId, seed);
+        const storageKeys = await wallet.getPublicJwks(walletContext(profile.profileId), {
+            ownerScope: 'profile', purpose: 'document-at-rest', alg: 'ML-KEM-768',
+        });
+        const storagePublicJwk = storageKeys[0]?.publicJwk;
+        if (!storagePublicJwk)
+            throw new Error('Required ML-KEM storage key could not be provisioned.');
+        const hasKey = profile.storagePublicJwk?.kid === storagePublicJwk.kid;
+        if (profile.confidentialStorageProfile === required && hasKey)
+            return profile;
+        const upgraded = {
+            ...profile,
+            confidentialStorageProfile: required,
+            storagePublicJwk,
+            updatedAt: this.now().toISOString(),
+        };
+        await this.options.store.putProfile(upgraded);
+        return upgraded;
+    }
     async requireOwnedProfile(ownerId, profileId) {
         const profile = await this.options.store.getProfile(profileId);
         if (!profile || profile.ownerId !== ownerId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-sdk-node-ts",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "description": "Next-generation Node runtime package for the GDC SDK family",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",
@@ -35,8 +35,8 @@
     "test:e2e:live-gw:clean": "bash ./scripts/run-live-gw-clean.sh"
   },
   "dependencies": {
-    "gdc-common-utils-ts": "^2.3.1",
-    "gdc-sdk-core-ts": "~2.3.1"
+    "gdc-common-utils-ts": "^2.3.2",
+    "gdc-sdk-core-ts": "~2.3.2"
   },
   "devDependencies": {
     "@types/node": "^20.14.10",