gdc-sdk-node-ts 2.3.12 → 2.3.14

package/README.md

@@ -572,6 +572,29 @@ Reusable payload examples:
 - [gdc-common-utils-ts/src/examples/lifecycle.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/lifecycle.ts)
 - [gdc-common-utils-ts/src/examples/api-flow-examples.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/api-flow-examples.ts)
 
+## Local terminology route for Next.js
+
+`LocalTerminologyBffService` keeps complete JSON catalogs in the application
+BFF and returns only matching options:
+
+```ts
+const terminology = new LocalTerminologyBffService(catalogs);
+
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  return Response.json(terminology.search({
+    text: url.searchParams.get('text') || '',
+    language: url.searchParams.get('language') || 'en',
+    jurisdiction: url.searchParams.get('jurisdiction') || undefined,
+    systems: url.searchParams.getAll('system'),
+    limit: 20,
+  }));
+}
+```
+
+The application validates which systems are allowed for the specific coded
+form field. This MVP service performs no external terminology request.
+
 ## API Index
 
 ## Full Public Surface

package/dist/index.d.ts

@@ -41,3 +41,4 @@ export * from './orchestration/individual-member-sdk.js';
 export * from './orchestration/personal-sdk.js';
 export * from './orchestration/professional-sdk.js';
 export * from './legacy-compat.js';
+export * from './local-terminology-bff.js';

package/dist/index.js

@@ -42,3 +42,4 @@ export * from './orchestration/individual-member-sdk.js';
 export * from './orchestration/personal-sdk.js';
 export * from './orchestration/professional-sdk.js';
 export * from './legacy-compat.js';
+export * from './local-terminology-bff.js';

package/dist/local-terminology-bff.d.ts

@@ -0,0 +1,17 @@
+import { type TerminologyCatalogDocument, type TerminologySearchInput, type TerminologySearchResult } from 'gdc-sdk-core-ts';
+/** Small primary document returned by an application-owned terminology route. */
+export type TerminologySearchPrimaryDocument = Readonly<{
+    data: readonly TerminologySearchResult[];
+}>;
+/**
+ * Framework-neutral local terminology service for Node/BFF applications.
+ *
+ * A Next.js route validates its query, calls `search(...)`, and returns the
+ * resulting primary document. Complete catalogs remain server-side.
+ */
+export declare class LocalTerminologyBffService {
+    private readonly provider;
+    constructor(catalogs: readonly TerminologyCatalogDocument[]);
+    /** Searches the configured local fallback catalogs. */
+    search(input: TerminologySearchInput): TerminologySearchPrimaryDocument;
+}

package/dist/local-terminology-bff.js

@@ -0,0 +1,16 @@
+import { LocalTerminologyProvider, } from 'gdc-sdk-core-ts';
+/**
+ * Framework-neutral local terminology service for Node/BFF applications.
+ *
+ * A Next.js route validates its query, calls `search(...)`, and returns the
+ * resulting primary document. Complete catalogs remain server-side.
+ */
+export class LocalTerminologyBffService {
+    constructor(catalogs) {
+        this.provider = new LocalTerminologyProvider(catalogs);
+    }
+    /** Searches the configured local fallback catalogs. */
+    search(input) {
+        return { data: this.provider.search(input) };
+    }
+}

package/dist/node-managed-wallet.js

@@ -486,7 +486,9 @@ export class NodeManagedWallet {
             alg: algorithm,
             purpose: `${ownerId}:${purpose}`,
             seed: request.mode === 'deterministic' && request.seedMaterial !== undefined
-                ? this.deriveSignerSeed(request.seedMaterial, ownerId, purpose)
+                ? (algorithm.startsWith('ML-DSA')
+                    ? this.deriveSeedBytes(request.seedMaterial, ownerId, purpose, 32)
+                    : this.deriveSignerSeed(request.seedMaterial, ownerId, purpose))
                 : undefined,
             cryptography: this.cryptography,
         });

package/dist/organization-controller-recovery.d.ts

@@ -28,4 +28,6 @@ type RecoverOrganizationControllerWithIssueDeps = {
     } & Record<string, unknown>, pollOptions?: PollOptions) => Promise<SubmitAndPollResult>;
 };
 export declare function recoverOrganizationControllerWithIssueWithDeps(deps: RecoverOrganizationControllerWithIssueDeps): Promise<OrganizationControllerRecoveryResult>;
+/** Reads the opaque activation code from a successful Organization/_issue poll result. */
+export declare function readOrganizationIssueActivationCode(result: SubmitAndPollResult): string;
 export {};

package/dist/organization-controller-recovery.js

@@ -8,7 +8,7 @@ export async function recoverOrganizationControllerWithIssueWithDeps(deps) {
      * - this flow must not depend on a new commercial Offer or Order step
      */
     const issue = await deps.submitLegalOrganizationIssue(deps.hostCtx, deps.input.issueInput, deps.input.issuePollOptions);
-    const activationCode = readActivationCodeFromIssueResult(issue);
+    const activationCode = readOrganizationIssueActivationCode(issue);
     if (!activationCode) {
         throw new Error('recoverOrganizationControllerWithIssue: missing org.schema.IndividualProduct.serialNumber in Organization/_issue response.');
     }
@@ -32,7 +32,8 @@ export async function recoverOrganizationControllerWithIssueWithDeps(deps) {
         activation,
     };
 }
-function readActivationCodeFromIssueResult(result) {
+/** Reads the opaque activation code from a successful Organization/_issue poll result. */
+export function readOrganizationIssueActivationCode(result) {
     const pollBody = (result?.poll?.body || {});
     const body = (pollBody.body || pollBody);
     const data = Array.isArray(body.data) ? body.data : Array.isArray(pollBody.data) ? pollBody.data : [];

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

@@ -9,6 +9,8 @@ export type ServerActorMode = 'self' | 'controller' | 'member';
 /** Durable public metadata plus PIN-and-host protected private material. */
 export type ServerProfileRecord = Readonly<{
     profileId: string;
+    /** Stable key-derivation identity. Defaults to profileId for legacy records. */
+    walletKeyDerivationId?: string;
     ownerId: string;
     actorKind: ActorKind;
     actorMode: ServerActorMode;
@@ -64,6 +66,21 @@ export type ServerProfileEnrollmentInput = Readonly<{
     idToken: string;
     activationCode: string;
     vpToken: string;
+    /**
+     * Optional server-only recovery seed. It must be 32 bytes encoded as
+     * base64url and must never be accepted from an untrusted browser payload.
+     */
+    walletSeed?: string;
+    /** Stable identity used to reproduce the same keys independently of profile storage IDs. */
+    walletKeyDerivationId?: string;
+}>;
+export type ServerProfileEnrollmentPublicKey = Readonly<{
+    ownerScope: string;
+    purpose: string;
+    use: string;
+    alg: string;
+    kid: string;
+    publicJwk: Record<string, unknown>;
 }>;
 /** One explicit unlock request; scopes and subject remain session-bound. */
 export type ServerProfileUnlockInput = Readonly<{
@@ -120,6 +137,15 @@ export declare class ServerProfileSessionManager {
     private readonly options;
     constructor(options: ServerProfileSessionManagerOptions);
     enroll(input: ServerProfileEnrollmentInput): Promise<ServerProfileRecord>;
+    /**
+     * Derives only the public enrollment descriptors for a server-governed
+     * recovery seed. This is intended for pre-DCR controller binding requests;
+     * no private material or seed is returned.
+     */
+    prepareEnrollmentPublicKeys(input: Readonly<{
+        walletSeed: string;
+        walletKeyDerivationId: string;
+    }>): Promise<ServerProfileEnrollmentPublicKey[]>;
     listProfiles(ownerId: string): Promise<ServerProfileRecord[]>;
     unlock(input: ServerProfileUnlockInput): Promise<ResolvedServerProfileSession>;
     resolveSession(ownerId: string, sessionId: string): Promise<ResolvedServerProfileSession>;

package/dist/server-profile-session.js

@@ -18,9 +18,12 @@ export class ServerProfileSessionManager {
     }
     async enroll(input) {
         requireEnrollment(input);
-        const seed = randomBytes(32).toString('base64url');
-        const wallet = await this.createWallet(input.profileId, seed);
-        const context = walletContext(input.profileId);
+        const seed = input.walletSeed || randomBytes(32).toString('base64url');
+        if (input.walletSeed)
+            requireBase64UrlSeed32(input.walletSeed);
+        const walletKeyDerivationId = normalizedWalletKeyDerivationId(input.walletKeyDerivationId, input.profileId);
+        const wallet = await this.createWallet(walletKeyDerivationId, seed);
+        const context = walletContext(walletKeyDerivationId);
         const publicKeys = await wallet.getPublicJwks(context, {});
         const storagePublicJwk = publicKeys.find((entry) => entry.purpose === 'document-at-rest')?.publicJwk;
         if (!storagePublicJwk)
@@ -45,6 +48,7 @@ export class ServerProfileSessionManager {
         const now = this.now();
         const record = {
             profileId: input.profileId,
+            walletKeyDerivationId,
             ownerId: input.ownerId,
             actorKind: input.actorKind,
             actorMode: input.actorMode,
@@ -67,6 +71,27 @@ export class ServerProfileSessionManager {
         await this.options.store.putProfile(record);
         return record;
     }
+    /**
+     * Derives only the public enrollment descriptors for a server-governed
+     * recovery seed. This is intended for pre-DCR controller binding requests;
+     * no private material or seed is returned.
+     */
+    async prepareEnrollmentPublicKeys(input) {
+        requireBase64UrlSeed32(input.walletSeed);
+        const walletKeyDerivationId = normalizedWalletKeyDerivationId(input.walletKeyDerivationId, '');
+        if (!walletKeyDerivationId)
+            throw new Error('prepareEnrollmentPublicKeys requires walletKeyDerivationId.');
+        const wallet = await this.createWallet(walletKeyDerivationId, input.walletSeed);
+        const descriptors = await wallet.getPublicJwks(walletContext(walletKeyDerivationId), {});
+        return descriptors.map((entry) => ({
+            ownerScope: entry.ownerScope,
+            purpose: entry.purpose,
+            use: entry.use,
+            alg: entry.alg,
+            kid: entry.kid,
+            publicJwk: entry.publicJwk,
+        }));
+    }
     listProfiles(ownerId) {
         return this.options.store.listProfiles(ownerId);
     }
@@ -95,7 +120,8 @@ export class ServerProfileSessionManager {
             throw new Error('Profile PIN rejected.');
         }
         profile = await this.ensureRequiredStorageProfile(profile, seed);
-        const wallet = await this.createWallet(profile.profileId, seed);
+        const walletKeyDerivationId = profile.walletKeyDerivationId || profile.profileId;
+        const wallet = await this.createWallet(walletKeyDerivationId, seed);
         const smartTokenEndpoint = [
             this.options.gatewayBaseUrl.replace(/\/+$/, ''),
             buildIdentityOpenIdSmartTokenPath(profile.routeContext),
@@ -143,8 +169,9 @@ export class ServerProfileSessionManager {
         }
         const profile = await this.requireOwnedProfile(ownerId, session.profileId);
         const seed = await this.options.sealer.unseal(session.sealedUnlockedWalletSeed, `${sessionId}:unlocked-wallet-seed`);
-        const wallet = await this.createWallet(profile.profileId, seed);
-        const context = walletContext(profile.profileId);
+        const walletKeyDerivationId = profile.walletKeyDerivationId || profile.profileId;
+        const wallet = await this.createWallet(walletKeyDerivationId, seed);
+        const context = walletContext(walletKeyDerivationId);
         return {
             sessionId,
             profile,
@@ -174,9 +201,9 @@ export class ServerProfileSessionManager {
             fetchImpl: this.options.fetchImpl,
         });
     }
-    async createWallet(profileId, seed) {
+    async createWallet(walletKeyDerivationId, seed) {
         const wallet = new NodeManagedWallet({ resolveRecipientJwk: this.options.resolveRecipientJwk });
-        const context = walletContext(profileId);
+        const context = walletContext(walletKeyDerivationId);
         await wallet.provisionManagedKeys(context, {
             ownerScope: 'profile',
             purposes: ['actor-signing', 'document-at-rest'],
@@ -201,8 +228,9 @@ export class ServerProfileSessionManager {
         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), {
+        const walletKeyDerivationId = profile.walletKeyDerivationId || profile.profileId;
+        const wallet = await this.createWallet(walletKeyDerivationId, seed);
+        const storageKeys = await wallet.getPublicJwks(walletContext(walletKeyDerivationId), {
             ownerScope: 'profile', purpose: 'document-at-rest', alg: 'ML-KEM-768',
         });
         const storagePublicJwk = storageKeys[0]?.publicJwk;
@@ -234,7 +262,7 @@ export class ServerProfileSessionManager {
 }
 async function buildWalletClientAssertion(wallet, profile, audience, now) {
     const seconds = Math.floor(now.getTime() / 1000);
-    return wallet.signCompactJws(walletContext(profile.profileId), {
+    return wallet.signCompactJws(walletContext(profile.walletKeyDerivationId || profile.profileId), {
         header: { alg: 'ES384', typ: 'JWT' },
         claims: {
             iss: profile.clientId,
@@ -247,12 +275,20 @@ async function buildWalletClientAssertion(wallet, profile, audience, now) {
         key: { ownerScope: 'runtime', purpose: 'openid-id-token-signing' },
     });
 }
-function walletContext(profileId) {
+function walletContext(walletKeyDerivationId) {
     return {
-        profile: { profileId },
-        runtime: { runtimeId: `${profileId}:server-runtime`, runtimeType: 'backend-service' },
+        profile: { profileId: walletKeyDerivationId },
+        runtime: { runtimeId: `${walletKeyDerivationId}:server-runtime`, runtimeType: 'backend-service' },
     };
 }
+function normalizedWalletKeyDerivationId(value, profileId) {
+    return String(value || profileId).trim();
+}
+function requireBase64UrlSeed32(seed) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(seed) || Buffer.from(seed, 'base64url').byteLength !== 32) {
+        throw new Error('Profile enrollment walletSeed must be a 32-byte base64url value.');
+    }
+}
 function requireEnrollment(input) {
     for (const [name, value] of Object.entries({
         ownerId: input.ownerId,

package/package.json

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