gdc-sdk-node-ts 2.4.42 → 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

@@ -74,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;
@@ -335,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

package/dist/server-profile-session.js

@@ -256,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);

package/package.json

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