gdc-sdk-node-ts 2.4.41 → 2.4.43

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './identity-bootstrap.js';
 export * from './async-polling.js';
 export * from './backend-profile-runtime.js';
 export * from './server-profile-session.js';
+export * from './profile-recovery-envelope.js';
 export * from './server-profile-protection.js';
 export * from './backend-profile-workspace.js';
 export * from './individual-controller-backend-runtime.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export * from './identity-bootstrap.js';
 export * from './async-polling.js';
 export * from './backend-profile-runtime.js';
 export * from './server-profile-session.js';
+export * from './profile-recovery-envelope.js';
 export * from './server-profile-protection.js';
 export * from './backend-profile-workspace.js';
 export * from './individual-controller-backend-runtime.js';

package/dist/profile-recovery-envelope.d.ts

@@ -0,0 +1,37 @@
+export type PortableProfileRecoveryEnvelope = Readonly<{
+    version: 'gdc-portable-profile-recovery-v1';
+    profileId: string;
+    walletKeyDerivationId: string;
+    kdf: Readonly<{
+        name: 'scrypt';
+        saltBase64Url: string;
+        cost: number;
+        blockSize: number;
+        parallelization: number;
+        keyLength: 32;
+    }>;
+    cipher: 'A256GCM';
+    ivBase64Url: string;
+    ciphertextBase64Url: string;
+    tagBase64Url: string;
+}>;
+export type PortableProfileRecoveryProtection = Readonly<{
+    cost?: number;
+    blockSize?: number;
+    parallelization?: number;
+}>;
+export declare function createPortableProfileRecoveryEnvelope(input: Readonly<{
+    profileId: string;
+    walletSeed: string;
+    walletKeyDerivationId: string;
+    recoverySecret: string;
+    protection?: PortableProfileRecoveryProtection;
+}>): PortableProfileRecoveryEnvelope;
+export declare function openPortableProfileRecoveryEnvelope(input: Readonly<{
+    envelope: PortableProfileRecoveryEnvelope;
+    recoverySecret: string;
+}>): Readonly<{
+    profileId: string;
+    walletSeed: string;
+    walletKeyDerivationId: string;
+}>;

package/dist/profile-recovery-envelope.js

@@ -0,0 +1,113 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
+export function createPortableProfileRecoveryEnvelope(input) {
+    const profileId = requiredText(input.profileId, 'profileId');
+    const walletKeyDerivationId = requiredText(input.walletKeyDerivationId, 'walletKeyDerivationId');
+    requireSeed(input.walletSeed);
+    requireRecoverySecret(input.recoverySecret);
+    const kdf = {
+        name: 'scrypt',
+        saltBase64Url: randomBytes(16).toString('base64url'),
+        cost: input.protection?.cost ?? 65536,
+        blockSize: input.protection?.blockSize ?? 8,
+        parallelization: input.protection?.parallelization ?? 1,
+        keyLength: 32,
+    };
+    const key = deriveKey(input.recoverySecret, kdf);
+    const iv = randomBytes(12);
+    const aad = envelopeAad(profileId, walletKeyDerivationId);
+    try {
+        const cipher = createCipheriv('aes-256-gcm', key, iv);
+        cipher.setAAD(aad);
+        const ciphertext = Buffer.concat([
+            cipher.update(JSON.stringify({ walletSeed: input.walletSeed }), 'utf8'),
+            cipher.final(),
+        ]);
+        return {
+            version: 'gdc-portable-profile-recovery-v1',
+            profileId,
+            walletKeyDerivationId,
+            kdf,
+            cipher: 'A256GCM',
+            ivBase64Url: iv.toString('base64url'),
+            ciphertextBase64Url: ciphertext.toString('base64url'),
+            tagBase64Url: cipher.getAuthTag().toString('base64url'),
+        };
+    }
+    finally {
+        key.fill(0);
+    }
+}
+export function openPortableProfileRecoveryEnvelope(input) {
+    const envelope = input.envelope;
+    try {
+        validateEnvelope(envelope);
+        requireRecoverySecret(input.recoverySecret);
+        const key = deriveKey(input.recoverySecret, envelope.kdf);
+        try {
+            const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(envelope.ivBase64Url, 'base64url'));
+            decipher.setAAD(envelopeAad(envelope.profileId, envelope.walletKeyDerivationId));
+            decipher.setAuthTag(Buffer.from(envelope.tagBase64Url, 'base64url'));
+            const cleartext = Buffer.concat([
+                decipher.update(Buffer.from(envelope.ciphertextBase64Url, 'base64url')),
+                decipher.final(),
+            ]).toString('utf8');
+            const payload = JSON.parse(cleartext);
+            const walletSeed = String(payload.walletSeed || '');
+            requireSeed(walletSeed);
+            return {
+                profileId: envelope.profileId,
+                walletSeed,
+                walletKeyDerivationId: envelope.walletKeyDerivationId,
+            };
+        }
+        finally {
+            key.fill(0);
+        }
+    }
+    catch {
+        throw new Error('Portable profile recovery envelope could not be opened.');
+    }
+}
+function deriveKey(secret, kdf) {
+    return scryptSync(secret, Buffer.from(kdf.saltBase64Url, 'base64url'), kdf.keyLength, {
+        N: kdf.cost,
+        r: kdf.blockSize,
+        p: kdf.parallelization,
+        maxmem: Math.max(128 * 1024 * 1024, 256 * kdf.cost * kdf.blockSize),
+    });
+}
+function envelopeAad(profileId, walletKeyDerivationId) {
+    return Buffer.from(JSON.stringify({
+        version: 'gdc-portable-profile-recovery-v1',
+        profileId,
+        walletKeyDerivationId,
+    }));
+}
+function requireRecoverySecret(value) {
+    const secret = String(value || '');
+    if (secret.length < 16 || /^\d+$/.test(secret)) {
+        throw new Error('Portable recovery requires a high-entropy recovery secret, not a short PIN.');
+    }
+}
+function requireSeed(value) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(value) || Buffer.from(value, 'base64url').byteLength !== 32) {
+        throw new Error('Portable recovery requires a 32-byte base64url wallet seed.');
+    }
+}
+function requiredText(value, name) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new Error(`Portable recovery requires ${name}.`);
+    return normalized;
+}
+function validateEnvelope(value) {
+    if (value?.version !== 'gdc-portable-profile-recovery-v1'
+        || value.cipher !== 'A256GCM'
+        || value.kdf?.name !== 'scrypt'
+        || value.kdf.keyLength !== 32
+        || !value.profileId
+        || !value.walletKeyDerivationId) {
+        throw new Error('Unsupported portable profile recovery envelope.');
+    }
+}

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

@@ -3,6 +3,10 @@ import type { ActorKind } from 'gdc-common-utils-ts/models/actor-session';
 import type { LegalOrganizationVerificationTransactionInput } from 'gdc-common-utils-ts/utils/legal-organization-verification-transaction';
 import { type AppInfo, type ConfidentialStorageProfile, type PollOptions, type SubmitAndPollResult } from 'gdc-sdk-core-ts';
 import { OrganizationControllerSdk } from './orchestration/organization-controller-sdk.js';
+import { ProfessionalSdk } from './orchestration/professional-sdk.js';
+import { DigitalTwinSdk } from './orchestration/digital-twin-sdk.js';
+import type { SmartTokenExchangeResult } from './smart-token.js';
+import type { DigitalTwinSearchInput, DigitalTwinSearchResult } from './digital-twin.js';
 import type { RouteContext } from './individual-onboarding.js';
 import type { HostRouteContext } from './host-onboarding.js';
 import type { SecureDidcommTransportAdapter } from 'gdc-sdk-core-ts';
@@ -70,6 +74,15 @@ export type ServerEmployeeProfileOtpRotationInput = Readonly<{
     clientName: string;
 }>;
 export type ServerEmployeeProfileOtpRotationResult = ServerProfileRecord;
+export type ServerProfilePinReplacementInput = Readonly<{
+    ownerId: string;
+    profileId: string;
+    /** Server-authorized seed obtained from a passkey, active wallet session or recovery envelope. */
+    authorizedWalletSeed: string;
+    /** Required when the durable profile still carries a separately protected legacy VP. */
+    authorizedVpToken?: string;
+    newPin: string;
+}>;
 export type ServerProfileEnrollmentInput = Readonly<{
     /** Stable confidential id of the authenticated portal account that owns and lists this profile. */
     ownerId: string;
@@ -228,6 +241,47 @@ export type OpenedServerOrganizationController = Readonly<{
     profile: ServerProfileRecord;
     sdk: OrganizationControllerSdk;
 }>;
+/** Server-owned role evidence used to sign a fresh professional VP. */
+export type ServerProfessionalProofInput = Readonly<{
+    role: string;
+    email?: string;
+    sameAs?: string | readonly string[];
+    telephone?: string;
+    credentialMaterial?: string;
+}>;
+/** Reopens one enrolled employee/professional profile behind the BFF boundary. */
+export type ServerProfessionalOpenInput = Readonly<{
+    ownerId: string;
+    profileId: string;
+    /** Fresh signed OIDC id_token proving the authenticated account/email. */
+    idToken: string;
+    /** Role evidence signed by the managed DCR wallet, independently of idToken. */
+    professionalProof: ServerProfessionalProofInput;
+    /** Manager-owned PIN path; mutually exclusive with authorizedWalletSeed. */
+    pin?: string;
+    /** Server-only seed already authorized by a product passkey/session policy. */
+    authorizedWalletSeed?: string;
+}>;
+/** Business authorization requested from SMART; OpenID/JWT fields stay SDK-owned. */
+export type ServerProfessionalSmartTokenInput = Readonly<{
+    subjectDid?: string;
+    purpose?: string;
+    scopes: string[];
+    acrValues?: string;
+    requestBodyClaims?: Record<string, unknown>;
+    tokenCacheKey?: string;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+}>;
+/** Role-scoped professional facades with managed SMART proof methods. */
+export type OpenedServerProfessional = Readonly<{
+    profile: ServerProfileRecord;
+    sdk: ProfessionalSdk;
+    digitalTwin: DigitalTwinSdk;
+    requestSmartToken(input: ServerProfessionalSmartTokenInput): Promise<SmartTokenExchangeResult>;
+    requestDigitalTwinSmartToken(input: ServerProfessionalSmartTokenInput): Promise<SmartTokenExchangeResult>;
+    searchDigitalTwins(input: Omit<DigitalTwinSearchInput, 'accessToken'>): Promise<DigitalTwinSearchResult>;
+}>;
 export type ServerProfileSessionManagerOptions = Readonly<{
     store: ServerProfileStore;
     sealer: ServerProfileSealer;
@@ -290,6 +344,12 @@ export declare class ServerProfileSessionManager {
     /** @deprecated Use `submitLegalOrganizationCredentialReissuanceWithBootstrapWallet`. */
     submitLegalOrganizationIssueWithBootstrapWallet(input: ServerProfileOrganizationIssueInput): Promise<SubmitAndPollResult>;
     listProfiles(ownerId: string): Promise<ServerProfileRecord[]>;
+    /**
+     * Rewraps the exact registered wallet under a new PIN after a separate
+     * server-authorized recovery factor has released its secrets. No GW call or
+     * DCR occurs because proof-of-possession and every public key remain intact.
+     */
+    replaceProfilePinFromAuthorizedSecrets(input: ServerProfilePinReplacementInput): Promise<ServerProfileRecord>;
     unlock(input: ServerProfileUnlockInput): Promise<ResolvedServerProfileSession>;
     /**
      * Renews the short SMART bearer while retaining the already-open server
@@ -307,6 +367,16 @@ export declare class ServerProfileSessionManager {
      * registered for that profile before any gateway request can be sent.
      */
     openOrganizationController(input: ServerOrganizationControllerOpenInput): Promise<OpenedServerOrganizationController>;
+    /**
+     * Opens one registered organization employee/professional without exposing
+     * wallet reconstruction, private_key_jwt, VP or transport plumbing.
+     *
+     * The product authorizes the PIN/passkey/session and supplies business role
+     * evidence. The SDK revalidates the registered key set, signs a fresh role
+     * VP independently from the OIDC account proof, derives the SMART endpoint
+     * from the durable profile route and owns the client assertion.
+     */
+    openProfessional(input: ServerProfessionalOpenInput): Promise<OpenedServerProfessional>;
     lock(ownerId: string, sessionId: string): Promise<void>;
     private createClient;
     private createWallet;

package/dist/server-profile-session.js

@@ -7,6 +7,8 @@ import { TransportProfiles, } from 'gdc-sdk-core-ts';
 import { NodeManagedWallet } from './node-managed-wallet.js';
 import { NodeHttpClient } from './node-runtime-client.js';
 import { OrganizationControllerSdk } from './orchestration/organization-controller-sdk.js';
+import { ProfessionalSdk } from './orchestration/professional-sdk.js';
+import { DigitalTwinSdk } from './orchestration/digital-twin-sdk.js';
 import { buildIdentityOpenIdSmartTokenPath } from './runtime-paths.js';
 import { createProfileDeviceActivationRequest } from './device-activation.js';
 import { ProfilePinRejectedError, openServerProfileSecret, protectServerProfileSecret, } from './server-profile-protection.js';
@@ -254,6 +256,38 @@ export class ServerProfileSessionManager {
     listProfiles(ownerId) {
         return this.options.store.listProfiles(ownerId);
     }
+    /**
+     * Rewraps the exact registered wallet under a new PIN after a separate
+     * server-authorized recovery factor has released its secrets. No GW call or
+     * DCR occurs because proof-of-possession and every public key remain intact.
+     */
+    async replaceProfilePinFromAuthorizedSecrets(input) {
+        const profile = await this.requireOwnedProfile(input.ownerId, input.profileId);
+        const seed = String(input.authorizedWalletSeed || '').trim();
+        requireBase64UrlSeed32(seed);
+        if (!this.options.store.deleteSessionsForProfile) {
+            throw new Error('Profile PIN replacement requires profile-session invalidation support.');
+        }
+        if (profile.protectedVpToken && !String(input.authorizedVpToken || '').trim()) {
+            throw new Error('Profile PIN replacement requires the authorized VP token.');
+        }
+        const walletKeyDerivationId = normalizedWalletKeyDerivationId(profile.walletKeyDerivationId, profile.profileId);
+        const wallet = await this.createWallet(walletKeyDerivationId, seed);
+        await requireRegisteredProfileKeys(wallet, walletContext(walletKeyDerivationId), profile);
+        const updated = {
+            ...profile,
+            protectedWalletSeed: await protectServerProfileSecret(seed, input.newPin, `${profile.profileId}:wallet-seed`, this.options.sealer, this.options.profileProtection),
+            ...(profile.protectedVpToken ? {
+                protectedVpToken: await protectServerProfileSecret(String(input.authorizedVpToken), input.newPin, `${profile.profileId}:vp-token`, this.options.sealer, this.options.profileProtection),
+            } : {}),
+            failedUnlocks: 0,
+            lockedUntil: undefined,
+            updatedAt: this.now().toISOString(),
+        };
+        await this.options.store.putProfile(updated);
+        await this.options.store.deleteSessionsForProfile(profile.profileId);
+        return updated;
+    }
     async unlock(input) {
         let profile = await this.requireOwnedProfile(input.ownerId, input.profileId);
         this.requireSubject(profile, input.subjectDid);
@@ -453,6 +487,115 @@ export class ServerProfileSessionManager {
         });
         return { profile, sdk: new OrganizationControllerSdk(client) };
     }
+    /**
+     * Opens one registered organization employee/professional without exposing
+     * wallet reconstruction, private_key_jwt, VP or transport plumbing.
+     *
+     * The product authorizes the PIN/passkey/session and supplies business role
+     * evidence. The SDK revalidates the registered key set, signs a fresh role
+     * VP independently from the OIDC account proof, derives the SMART endpoint
+     * from the durable profile route and owns the client assertion.
+     */
+    async openProfessional(input) {
+        const profile = await this.requireOwnedProfile(input.ownerId, input.profileId);
+        const isProfessional = profile.actorKind === ActorKinds.OrganizationEmployee
+            || profile.actorKind === ActorKinds.Professional;
+        if (!isProfessional || profile.actorMode !== 'member') {
+            throw new Error('Profile is not an organization employee or professional.');
+        }
+        const idToken = String(input.idToken || '').trim();
+        const role = String(input.professionalProof?.role || '').trim();
+        if (!idToken)
+            throw new Error('Opening a professional requires a signed OIDC idToken.');
+        if (!role)
+            throw new Error('Opening a professional requires role proof.');
+        const hasPin = Boolean(String(input.pin || '').trim());
+        const hasAuthorizedSeed = Boolean(String(input.authorizedWalletSeed || '').trim());
+        if (hasPin === hasAuthorizedSeed) {
+            throw new Error('Opening a professional requires exactly one of pin or authorizedWalletSeed.');
+        }
+        const seed = hasAuthorizedSeed
+            ? String(input.authorizedWalletSeed)
+            : await openServerProfileSecret(profile.protectedWalletSeed, String(input.pin), `${profile.profileId}:wallet-seed`, this.options.sealer);
+        requireBase64UrlSeed32(seed);
+        const walletKeyDerivationId = normalizedWalletKeyDerivationId(profile.walletKeyDerivationId, profile.profileId);
+        const wallet = await this.createWallet(walletKeyDerivationId, seed);
+        const context = walletContext(walletKeyDerivationId);
+        await requireRegisteredProfileKeys(wallet, context, profile);
+        const secureTransportAdapter = {
+            pack: (message) => wallet.packForRecipientWithContext(bindOrganizationControllerTransport(message, profile), profile.providerDid, { context }),
+            unpack: async (jwe) => (await wallet.unpackWithContext(jwe, { context })).content,
+        };
+        const operationalClient = new NodeHttpClient({
+            baseUrl: this.options.gatewayBaseUrl,
+            ctx: profile.routeContext,
+            bearerToken: idToken,
+            fetchImpl: this.options.fetchImpl,
+            appInfo: this.options.appInfo,
+            transportProfile: TransportProfiles.DidcommEncryptedForm,
+            secureTransportAdapter,
+        });
+        // SMART/OpenID uses its own JSON/form protocol and must not be wrapped in
+        // the encrypted resource transport selected for later business actions.
+        const sdk = new ProfessionalSdk(this.createClient(profile.routeContext, idToken));
+        const digitalTwin = new DigitalTwinSdk(operationalClient, profile.actorDid);
+        let digitalTwinAccessToken;
+        const request = async (smart) => {
+            if (!smart.scopes?.length)
+                throw new Error('Professional SMART request requires scopes.');
+            const now = this.now();
+            const audience = [
+                this.options.gatewayBaseUrl.replace(/\/+$/, ''),
+                buildIdentityOpenIdSmartTokenPath(profile.routeContext),
+            ].join('');
+            const clientAssertion = await buildWalletClientAssertion(wallet, profile, audience, now);
+            const vpToken = await buildManagedProfessionalVp(wallet, context, {
+                clientId: profile.clientId,
+                actorDid: profile.actorDid,
+                profileDid: profile.profileDid,
+                ...input.professionalProof,
+                role,
+            });
+            return sdk.requestSmartToken({
+                ...profile.routeContext,
+                actorDid: profile.actorDid,
+                subjectDid: String(smart.subjectDid || '').trim() || undefined,
+                clientId: profile.clientId,
+                issuer: profile.clientId,
+                audience,
+                idToken,
+                vpToken,
+                vpTokenFallback: 'omit',
+                clientAssertion,
+                clientAssertionType: 'private_key_jwt',
+                smartTokenKind: 'openid-smart',
+                acrValues: smart.acrValues || profileSmartAcrValues(profile.actorKind),
+                purpose: smart.purpose,
+                scopes: unique(smart.scopes),
+                requestBodyClaims: smart.requestBodyClaims,
+                tokenCacheKey: smart.tokenCacheKey,
+                timeoutSeconds: smart.timeoutSeconds,
+                intervalSeconds: smart.intervalSeconds,
+            });
+        };
+        return {
+            profile,
+            sdk,
+            digitalTwin,
+            requestSmartToken: request,
+            requestDigitalTwinSmartToken: async (smart) => {
+                const result = await request(smart);
+                if (result.accessToken)
+                    digitalTwinAccessToken = result.accessToken;
+                return result;
+            },
+            searchDigitalTwins: (search) => {
+                if (!digitalTwinAccessToken)
+                    throw new Error('Digital twin SMART token has not been granted.');
+                return digitalTwin.search(profile.routeContext, { ...search, accessToken: digitalTwinAccessToken });
+            },
+        };
+    }
     async lock(ownerId, sessionId) {
         const session = await this.options.store.getSession(sessionId);
         if (session?.ownerId === ownerId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-sdk-node-ts",
-  "version": "2.4.41",
+  "version": "2.4.43",
   "description": "Next-generation Node runtime package for the GDC SDK family",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",