gdc-sdk-node-ts 2.0.9 → 2.0.10

package/dist/node-managed-wallet.js

@@ -0,0 +1,604 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { createHash, createPrivateKey, createPublicKey, sign as cryptoSign, verify as cryptoVerify } from 'crypto';
+import { CryptographyService } from 'gdc-common-utils-ts/CryptographyService';
+import { Content } from 'gdc-common-utils-ts/utils/content';
+import { createJwtSigner } from 'gdc-common-utils-ts/utils/jwt-signer';
+import { buildJwtCompact, prepareJwtForSignature } from 'gdc-common-utils-ts/utils/jwt';
+import { NodeCryptoHelper } from './node-crypto-helper.js';
+const DEFAULT_POLICY = {
+    defaults: {
+        'actor-signing': 'ES384',
+        'openid-id-token-signing': 'ES384',
+        'vp-token-signing': 'ES384',
+        'vc-signing': 'ES384',
+        'comm-signing': 'ML-DSA-44',
+        'comm-encryption': 'ML-KEM-768',
+    },
+};
+/**
+ * Node-focused managed wallet implementation for BFF, portal, and backend flows.
+ *
+ * This adapter keeps actor/profile keys separate from runtime/channel keys and
+ * exposes one shared `IWallet` contract suitable for:
+ * - user/domain signing
+ * - OpenID/JWT signing
+ * - DIDComm-style transport wrapping
+ * - confidential document protection
+ */
+export class NodeManagedWallet {
+    /**
+     * Creates one managed wallet backed by `CryptographyService` and Node crypto.
+     */
+    constructor(options = {}) {
+        this.owners = new Map();
+        this.cryptoHelper = options.cryptoHelper ?? new NodeCryptoHelper();
+        this.cryptography = options.cryptography ?? new CryptographyService(this.cryptoHelper);
+        this.resolveRecipientJwk = options.resolveRecipientJwk;
+        this.policy = {
+            defaults: {
+                ...DEFAULT_POLICY.defaults,
+                ...(options.policy?.defaults ?? {}),
+            },
+        };
+    }
+    /**
+     * Legacy provisioning shape kept for app compatibility.
+     *
+     * It provisions one profile-owned signing key, one runtime communication
+     * signing key, and one runtime communication encryption key while returning
+     * the signing/encryption public keys expected by older app-facing flows.
+     */
+    async provisionKeys(entityId) {
+        const profileContext = {
+            profile: {
+                profileId: entityId,
+            },
+            runtime: {
+                runtimeId: `${entityId}:runtime`,
+                runtimeType: 'web-app',
+            },
+        };
+        await this.provisionManagedKeys(profileContext, {
+            ownerScope: 'profile',
+            purposes: ['actor-signing'],
+            seedMaterial: entityId,
+            mode: 'deterministic',
+        });
+        const runtimeKeySet = await this.provisionManagedKeys(profileContext, {
+            ownerScope: 'runtime',
+            purposes: ['comm-signing', 'comm-encryption'],
+            seedMaterial: `${entityId}:runtime`,
+            mode: 'deterministic',
+        });
+        const signingKey = await this.getPublicJwks(profileContext, {
+            ownerScope: 'profile',
+            purpose: 'actor-signing',
+        });
+        const encryptionKey = runtimeKeySet.keys.find((key) => key.use === 'enc');
+        return {
+            keys: [
+                signingKey[0]?.publicJwk ?? runtimeKeySet.keys[0],
+                encryptionKey ?? runtimeKeySet.keys[0],
+            ],
+        };
+    }
+    /**
+     * Rich provisioning shape for actor/profile keys and runtime/channel keys.
+     */
+    async provisionManagedKeys(context, request) {
+        const ownerState = this.getOrCreateOwnerState(context, request.ownerScope);
+        const ownerId = this.resolveOwnerId(context, request.ownerScope);
+        const created = [];
+        for (const purpose of request.purposes) {
+            const existing = ownerState.keys.find((entry) => entry.descriptor.purpose === purpose);
+            if (existing) {
+                created.push(existing.descriptor.publicJwk);
+                continue;
+            }
+            const descriptor = await this.createManagedKey(context, request.ownerScope, purpose, request, ownerId);
+            ownerState.keys.push(descriptor);
+            created.push(descriptor.descriptor.publicJwk);
+        }
+        if (!ownerState.storageKey) {
+            ownerState.storageKey = await this.createStorageKey(request, ownerId);
+        }
+        return { keys: created };
+    }
+    /**
+     * Returns the currently available public JWKs for the selected context and filter.
+     */
+    async getPublicJwks(context, filter) {
+        if (!context && !filter?.keyId)
+            return [];
+        if (filter?.keyId) {
+            for (const ownerState of this.owners.values()) {
+                const match = ownerState.keys.find((entry) => entry.descriptor.kid === filter.keyId);
+                if (match && this.matchesSelection(match.descriptor, filter)) {
+                    return [match.descriptor];
+                }
+            }
+            return [];
+        }
+        const descriptors = [];
+        for (const scope of this.inferRelevantScopes(context, filter)) {
+            const ownerState = this.tryGetOwnerState(context, scope);
+            for (const entry of ownerState?.keys ?? []) {
+                if (this.matchesSelection(entry.descriptor, filter)) {
+                    descriptors.push(entry.descriptor);
+                }
+            }
+        }
+        return descriptors;
+    }
+    /**
+     * Computes a digest of a string using the configured runtime helper.
+     */
+    async digest(data, algorithm) {
+        return this.cryptoHelper.digestString(data, algorithm);
+    }
+    /**
+     * Protects one confidential document using one owner-specific symmetric storage key.
+     */
+    async protectConfidentialData(doc, entityId) {
+        return this.protectManagedConfidentialData(doc, {
+            profile: { profileId: entityId },
+            runtime: { runtimeId: `${entityId}:runtime`, runtimeType: 'web-app' },
+        });
+    }
+    /**
+     * Protects one confidential document using the richer execution-context model.
+     */
+    async protectManagedConfidentialData(doc, context, _options) {
+        if (!doc?.content)
+            return doc;
+        const storageKey = this.requireStorageKey(context);
+        const ownerId = this.resolveStorageOwnerId(context);
+        const contentString = JSON.stringify(doc.content);
+        const encrypted = await this.cryptography.encrypt(contentString, storageKey, ownerId);
+        const { content, ...docWithoutContent } = doc;
+        return {
+            ...docWithoutContent,
+            jwe: encrypted,
+        };
+    }
+    /**
+     * Decrypts one confidential document using the legacy entity id shape.
+     */
+    async unprotectConfidentialData(doc, entityId) {
+        return this.unprotectManagedConfidentialData(doc, {
+            profile: { profileId: entityId },
+            runtime: { runtimeId: `${entityId}:runtime`, runtimeType: 'web-app' },
+        });
+    }
+    /**
+     * Decrypts one confidential document using the richer execution-context model.
+     */
+    async unprotectManagedConfidentialData(doc, context, _options) {
+        if (!doc?.jwe)
+            return doc;
+        const storageKey = this.requireStorageKey(context);
+        const ownerId = this.resolveStorageOwnerId(context);
+        const decrypted = await this.cryptography.decrypt(doc.jwe, storageKey, ownerId);
+        const { jwe, ...docWithoutJwe } = doc;
+        return {
+            ...docWithoutJwe,
+            content: JSON.parse(decrypted),
+        };
+    }
+    /**
+     * Signs arbitrary bytes or one UTF-8 string using the selected managed key.
+     */
+    async sign(payload, context, options) {
+        const entry = this.requireManagedKey(context, options, 'sig');
+        const payloadBytes = typeof payload === 'string' ? Content.stringToBytesUTF8(payload) : payload;
+        const alg = entry.descriptor.alg;
+        if (alg.startsWith('ML-DSA')) {
+            const signature = await this.cryptography.signBytes(payloadBytes, entry.privateMaterial, alg);
+            return Content.bytesToRawBase64UrlSafe(signature);
+        }
+        const privateJwk = entry.privateMaterial;
+        const keyObject = createPrivateKey({ key: privateJwk, format: 'jwk' });
+        const signature = cryptoSign(this.resolveNodeDigestForAlgorithm(alg), Buffer.from(payloadBytes), keyObject);
+        return Buffer.from(signature).toString('base64url');
+    }
+    /**
+     * Verifies one signature against the provided public JWK.
+     */
+    async verify(payload, signature, jwk, options) {
+        const payloadBytes = typeof payload === 'string' ? Content.stringToBytesUTF8(payload) : payload;
+        const algorithm = (options?.alg ?? jwk.alg);
+        if (!algorithm) {
+            throw new Error('NodeManagedWallet.verify requires an algorithm on the key or in options.alg.');
+        }
+        if (algorithm.startsWith('ML-DSA')) {
+            return this.cryptography.verifyBytes(Content.base64ToBytes(signature), payloadBytes, jwk);
+        }
+        const publicKey = createPublicKey({ key: jwk, format: 'jwk' });
+        return cryptoVerify(this.resolveNodeDigestForAlgorithm(algorithm), Buffer.from(payloadBytes), publicKey, Buffer.from(signature, 'base64url'));
+    }
+    /**
+     * Encrypts one payload for the provided recipient public JWK.
+     */
+    async encrypt(plaintext, recipientJwk, options) {
+        if (!options?.context || !options?.key) {
+            throw new Error('NodeManagedWallet.encrypt requires options.context and options.key.');
+        }
+        return this.buildCompactJwe(options.context, {
+            plaintext,
+            recipientJwk,
+            contentType: options.contentType,
+            key: options.key,
+        });
+    }
+    /**
+     * Decrypts one ciphertext using one selected local encryption key.
+     */
+    async decrypt(ciphertext, context, options) {
+        return this.decryptCompactJwe(ciphertext, context, {
+            key: options?.key ?? {
+                ownerScope: 'runtime',
+                purpose: 'comm-encryption',
+            },
+        });
+    }
+    /**
+     * Builds one compact JWS using one managed signing key.
+     */
+    async signCompactJws(context, request) {
+        const entry = this.requireManagedKey(context, request.key, 'sig');
+        const header = {
+            ...request.header,
+            alg: entry.descriptor.alg,
+            kid: entry.descriptor.kid,
+        };
+        const prepared = prepareJwtForSignature(header, request.claims);
+        const signature = await this.sign(prepared.signingInput, context, request.key);
+        return buildJwtCompact(prepared.encodedHeader, prepared.encodedPayload, signature);
+    }
+    /**
+     * Builds one detached compact JWS using one managed signing key.
+     */
+    async signDetachedJws(context, request) {
+        const entry = this.requireManagedKey(context, request.key, 'sig');
+        const header = {
+            ...request.header,
+            alg: entry.descriptor.alg,
+            kid: entry.descriptor.kid,
+            b64: false,
+            crit: ['b64'],
+        };
+        const payloadBytes = typeof request.payload === 'string' ? Content.stringToBytesUTF8(request.payload) : request.payload;
+        const encodedHeader = Content.objectToRawBase64UrlSafe(header);
+        const signingBytes = Buffer.concat([Buffer.from(`${encodedHeader}.`, 'ascii'), Buffer.from(payloadBytes)]);
+        const signature = await this.sign(signingBytes, context, request.key);
+        return `${encodedHeader}..${signature}`;
+    }
+    /**
+     * Builds one compact JWE using one selected local ML-KEM key and one recipient public JWK.
+     */
+    async buildCompactJwe(context, request) {
+        const entry = this.requireManagedKey(context, request.key, 'enc');
+        const secretKeyJwk = {
+            ...entry.descriptor.publicJwk,
+            dBytes: entry.privateMaterial,
+        };
+        const protectedHeader = {
+            enc: 'A256GCM',
+            ...(request.contentType ? { cty: request.contentType } : {}),
+        };
+        const plaintext = typeof request.plaintext === 'string'
+            ? request.plaintext
+            : Content.bytesToStringUTF8(request.plaintext);
+        return this.cryptography.encryptJweToCompact(plaintext, protectedHeader, secretKeyJwk, request.recipientJwk);
+    }
+    /**
+     * Decrypts one compact JWE using one selected local ML-KEM key.
+     */
+    async decryptCompactJwe(jwe, context, options) {
+        const entry = this.requireManagedKey(context, options.key, 'enc');
+        const secretKeyJwk = {
+            ...entry.descriptor.publicJwk,
+            dBytes: entry.privateMaterial,
+        };
+        const result = await this.cryptography.decryptJwe(jwe, secretKeyJwk);
+        return result.decryptedBytes;
+    }
+    /**
+     * Legacy pack shape retained for app compatibility.
+     */
+    async packForRecipient(content, recipientDid) {
+        return this.packForRecipientWithContext(content, recipientDid, {
+            context: {
+                runtime: {
+                    runtimeId: 'default-runtime',
+                    runtimeType: 'web-app',
+                },
+            },
+        });
+    }
+    /**
+     * Packs one payload into a transport envelope signed and encrypted by the runtime.
+     */
+    async packForRecipientWithContext(content, recipientDidOrJwk, options) {
+        const recipientJwk = typeof recipientDidOrJwk === 'string'
+            ? await this.resolveRecipientPublicJwk(recipientDidOrJwk)
+            : recipientDidOrJwk;
+        const signingKey = options.signingKey ?? {
+            ownerScope: 'runtime',
+            purpose: 'comm-signing',
+        };
+        const encryptionKey = options.encryptionKey ?? {
+            ownerScope: 'runtime',
+            purpose: 'comm-encryption',
+        };
+        const compactJws = await this.signCompactJws(options.context, {
+            header: {
+                typ: 'JWS',
+            },
+            claims: {
+                payload: content,
+            },
+            key: signingKey,
+        });
+        return this.buildCompactJwe(options.context, {
+            plaintext: compactJws,
+            recipientJwk,
+            contentType: 'JWS',
+            key: encryptionKey,
+        });
+    }
+    /**
+     * Legacy unpack shape retained for app compatibility.
+     */
+    async unpack(packedMessage) {
+        return this.unpackWithContext(packedMessage, {
+            context: {
+                runtime: {
+                    runtimeId: 'default-runtime',
+                    runtimeType: 'web-app',
+                },
+            },
+        });
+    }
+    /**
+     * Unpacks one transport envelope and returns the decoded business payload plus JOSE metadata.
+     */
+    async unpackWithContext(packedMessage, options) {
+        const decryptedBytes = await this.decryptCompactJwe(packedMessage, options.context, {
+            key: options.decryptionKey ?? {
+                ownerScope: 'runtime',
+                purpose: 'comm-encryption',
+            },
+        });
+        const decryptedText = Content.bytesToStringUTF8(decryptedBytes);
+        const protectedHeader = this.cryptography.parseCompactJwe(packedMessage).protected;
+        if (protectedHeader) {
+            const decodedProtectedHeader = Content.base64UrlSafeToJSON(protectedHeader);
+            if (decodedProtectedHeader.cty === 'JWS') {
+                const compact = decryptedText;
+                const parts = compact.split('.');
+                if (parts.length !== 3) {
+                    throw new Error('NodeManagedWallet.unpackWithContext expected a compact JWS payload.');
+                }
+                const payload = Content.base64UrlSafeToJSON(parts[1]);
+                return {
+                    content: payload.payload,
+                    meta: {
+                        jwe: { protected: decodedProtectedHeader },
+                        jws: {
+                            compact,
+                        },
+                    },
+                };
+            }
+            return {
+                content: JSON.parse(decryptedText),
+                meta: {
+                    jwe: { protected: decodedProtectedHeader },
+                },
+            };
+        }
+        return {
+            content: JSON.parse(decryptedText),
+            meta: {},
+        };
+    }
+    getOrCreateOwnerState(context, ownerScope) {
+        const ownerId = this.resolveOwnerId(context, ownerScope);
+        const existing = this.owners.get(ownerId);
+        if (existing)
+            return existing;
+        const created = {
+            keys: [],
+        };
+        this.owners.set(ownerId, created);
+        return created;
+    }
+    tryGetOwnerState(context, ownerScope) {
+        const ownerId = this.resolveOwnerId(context, ownerScope);
+        return this.owners.get(ownerId);
+    }
+    resolveOwnerId(context, ownerScope) {
+        if (ownerScope === 'profile') {
+            const profileId = context.profile?.profileId;
+            if (!profileId) {
+                throw new Error('NodeManagedWallet requires context.profile.profileId when ownerScope="profile".');
+            }
+            return `profile:${profileId}:${context.walletId ?? 'default'}`;
+        }
+        const runtimeId = context.runtime?.runtimeId;
+        if (!runtimeId) {
+            throw new Error('NodeManagedWallet requires context.runtime.runtimeId when ownerScope="runtime".');
+        }
+        return `runtime:${runtimeId}:${context.walletId ?? 'default'}`;
+    }
+    resolveStorageOwnerId(context) {
+        if (context.profile?.profileId)
+            return `storage:profile:${context.profile.profileId}`;
+        if (context.runtime?.runtimeId)
+            return `storage:runtime:${context.runtime.runtimeId}`;
+        throw new Error('NodeManagedWallet requires either context.profile or context.runtime for storage operations.');
+    }
+    async createManagedKey(context, ownerScope, purpose, request, ownerId) {
+        const algorithm = this.resolveAlgorithmForPurpose(purpose);
+        if (algorithm === 'ML-KEM-768' || algorithm === 'ML-KEM-1024') {
+            const seedBytes = request.mode === 'deterministic' && request.seedMaterial !== undefined
+                ? this.deriveSeedBytes(request.seedMaterial, ownerId, purpose, 64)
+                : undefined;
+            const generated = await this.cryptography.generateKeyPairMlKem(seedBytes, algorithm);
+            return {
+                descriptor: {
+                    kid: generated.publicJWKey.kid,
+                    ownerScope,
+                    purpose,
+                    use: 'enc',
+                    alg: algorithm,
+                    publicJwk: generated.publicJWKey,
+                    defaultForPurpose: true,
+                },
+                privateMaterial: generated.secretKeyBytes,
+            };
+        }
+        const signer = await createJwtSigner({
+            alg: algorithm,
+            purpose: `${ownerId}:${purpose}`,
+            seed: request.mode === 'deterministic' && request.seedMaterial !== undefined
+                ? this.deriveSignerSeed(request.seedMaterial, ownerId, purpose)
+                : undefined,
+            cryptography: this.cryptography,
+        });
+        return {
+            descriptor: {
+                kid: signer.getKid(),
+                ownerScope,
+                purpose,
+                use: 'sig',
+                alg: algorithm,
+                publicJwk: signer.getPublicJwk(),
+                defaultForPurpose: true,
+            },
+            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()) {
+                const match = ownerState.keys.find((entry) => entry.descriptor.kid === selection.keyId);
+                if (match) {
+                    if (expectedUse && match.descriptor.use !== expectedUse) {
+                        throw new Error(`NodeManagedWallet key '${selection.keyId}' is not usable for '${expectedUse}'.`);
+                    }
+                    return match;
+                }
+            }
+        }
+        const scopes = this.inferRelevantScopes(context, selection);
+        for (const scope of scopes) {
+            const ownerState = this.tryGetOwnerState(context, scope);
+            const match = ownerState?.keys.find((entry) => this.matchesSelection(entry.descriptor, selection));
+            if (match) {
+                if (expectedUse && match.descriptor.use !== expectedUse) {
+                    throw new Error(`NodeManagedWallet key '${match.descriptor.kid}' is not usable for '${expectedUse}'.`);
+                }
+                return match;
+            }
+        }
+        throw new Error(`NodeManagedWallet found no managed key for selection ${JSON.stringify(selection)}.`);
+    }
+    inferRelevantScopes(context, selection) {
+        if (selection?.ownerScope)
+            return [selection.ownerScope];
+        const scopes = [];
+        if (context?.profile?.profileId)
+            scopes.push('profile');
+        if (context?.runtime?.runtimeId)
+            scopes.push('runtime');
+        return scopes.length > 0 ? scopes : ['runtime', 'profile'];
+    }
+    matchesSelection(descriptor, selection) {
+        if (!selection)
+            return true;
+        if (selection.keyId && descriptor.kid !== selection.keyId)
+            return false;
+        if (selection.ownerScope && descriptor.ownerScope !== selection.ownerScope)
+            return false;
+        if (selection.purpose && descriptor.purpose !== selection.purpose)
+            return false;
+        if (selection.alg && descriptor.alg !== selection.alg)
+            return false;
+        return true;
+    }
+    resolveAlgorithmForPurpose(purpose) {
+        const resolved = this.policy.defaults[purpose];
+        if (!resolved) {
+            throw new Error(`NodeManagedWallet has no default algorithm configured for purpose '${purpose}'.`);
+        }
+        return resolved;
+    }
+    deriveSignerSeed(seedMaterial, ownerId, purpose) {
+        const base = seedMaterial instanceof Uint8Array
+            ? Buffer.from(seedMaterial).toString('base64url')
+            : seedMaterial;
+        return `${base}:${ownerId}:${purpose}`;
+    }
+    deriveSeedBytes(seedMaterial, ownerId, purpose, size) {
+        const source = seedMaterial instanceof Uint8Array
+            ? Buffer.from(seedMaterial).toString('base64url')
+            : seedMaterial;
+        const blocks = [];
+        let counter = 0;
+        while (Buffer.concat(blocks).length < size) {
+            blocks.push(Buffer.from(this.deriveDeterministicBlock(source, ownerId, purpose, counter), 'hex'));
+            counter += 1;
+        }
+        return Buffer.concat(blocks).subarray(0, size);
+    }
+    deriveDeterministicBlock(seed, ownerId, purpose, counter) {
+        return createHash('sha512')
+            .update(seed, 'utf8')
+            .update(':', 'utf8')
+            .update(ownerId, 'utf8')
+            .update(':', 'utf8')
+            .update(purpose, 'utf8')
+            .update(':', 'utf8')
+            .update(String(counter), 'utf8')
+            .digest('hex');
+    }
+    resolveNodeDigestForAlgorithm(algorithm) {
+        switch (algorithm) {
+            case 'ES256K':
+                return 'sha256';
+            case 'ES384':
+                return 'sha384';
+            case 'RS256':
+                return 'sha256';
+            default:
+                throw new Error(`NodeManagedWallet does not support Node digest signing for algorithm '${algorithm}'.`);
+        }
+    }
+    async resolveRecipientPublicJwk(recipientDid) {
+        if (!this.resolveRecipientJwk) {
+            throw new Error(`NodeManagedWallet cannot resolve recipient DID '${recipientDid}' without options.resolveRecipientJwk.`);
+        }
+        return this.resolveRecipientJwk(recipientDid);
+    }
+}

package/dist/resource-operations.d.ts

@@ -37,13 +37,23 @@ export type OrganizationEmployeeCreationInput = {
  */
 export type OrganizationEmployeeLifecycleInput = {
     /**
-     * Canonical employee/person claims used by GW CORE to locate the employee.
+     * Canonical employee/person claims carried as the exportable employee identity.
+     *
+     * These claims should still include the business/external identifier
+     * (`org.schema.Person.identifier`) when available, but runtime lifecycle
+     * operations must prefer `resourceId` as the concrete GW profile locator.
+     * Treat `resource.id` as the current technical record anchor and
+     * `identifier` as the interoperable/exported identity value.
      */
     employeeClaims: Record<string, unknown>;
     /**
-     * Optional canonical resource id when already known by the caller.
+     * Preferred current GW employee profile id returned by create/search.
+     *
+     * Pass this for disable/purge whenever the caller already knows the active
+     * profile row. The SDK forwards it as `Bundle.entry.resource.id`, which GW
+     * now treats as the primary operational locator for lifecycle actions.
      */
-    resourceId?: string;
+    resourceId: string;
     dataType?: string;
 };
 export type OrganizationEmployeeSearchInput = {

package/dist/resource-operations.js

@@ -19,6 +19,7 @@ export async function disableOrganizationEmployeeWithDeps(routeCtx, input, optio
     // TODO(gw-core-lifecycle-target-patch-employee-disable): switch this
     // legacy DELETE-in-_batch flow to `_batch + PATCH` when GW CORE deploys it.
     void GwCoreLifecycleTodo.EmployeeDisablePatchMigration;
+    assertEmployeeLifecycleResourceId(input.resourceId, 'disableEmployee');
     const payload = buildEmployeeLifecyclePayload({
         routeCtx,
         requestType: input.dataType || GwCoreLifecycleRequestType.EmployeeDisable,
@@ -30,6 +31,7 @@ export async function disableOrganizationEmployeeWithDeps(routeCtx, input, optio
     return deps.submitAndPoll(deps.employeeBatchPath(routeCtx), deps.employeePollPath(routeCtx), payload, options);
 }
 export async function purgeOrganizationEmployeeWithDeps(routeCtx, input, options, deps) {
+    assertEmployeeLifecycleResourceId(input.resourceId, 'purgeEmployee');
     const payload = buildEmployeeLifecyclePayload({
         routeCtx,
         requestType: input.dataType || GwCoreLifecycleRequestType.EmployeePurge,
@@ -40,6 +42,12 @@ export async function purgeOrganizationEmployeeWithDeps(routeCtx, input, options
     });
     return deps.submitAndPoll(deps.employeePurgePath(routeCtx), deps.employeePurgePollPath(routeCtx), payload, options);
 }
+function assertEmployeeLifecycleResourceId(resourceId, operation) {
+    const normalized = String(resourceId || '').trim();
+    if (!normalized) {
+        throw new Error(`${operation}: resourceId is required and must be the current GW technical employee id (resource.id).`);
+    }
+}
 export async function searchOrganizationEmployeesWithDeps(routeCtx, input, deps) {
     return deps.submitAndPoll(deps.employeeSearchPath(routeCtx), deps.employeeSearchPollPath(routeCtx), {
         thid: input.requestThid || `employee-search-${createRuntimeUuid()}`,
@@ -422,6 +430,8 @@ function buildEmployeeLifecyclePayload(input) {
                     type: input.requestType,
                     method: input.requestMethod,
                     claims,
+                    // Keep the transport-local GW profile anchor separate from the
+                    // exportable employee identifier carried in claims.
                     resourceId: input.resourceId,
                 })],
         },

package/dist/wallet-backed-job-manager.d.ts

@@ -0,0 +1,19 @@
+import type { IJobManager } from 'gdc-sdk-core-ts';
+import type { WalletBackedJobManagerOptions } from './wallet-backed-job-manager.types.js';
+export type { WalletBackedJobManagerOptions, WalletBackedJobPollResult, WalletBackedJobSubmitResult, WalletBackedJobTransport, WalletExecutionContextLike, } from './wallet-backed-job-manager.types.js';
+/**
+ * Creates one backend/session job manager that stores protected job payloads in
+ * one local vault while reusing one shared wallet for protect/unprotect and
+ * transport packing.
+ *
+ * Intended for:
+ * - portal/BFF runtimes
+ * - short-lived service sessions
+ * - send-first or cache-first orchestration over one local in-memory vault
+ */
+export declare function createWalletBackedJobManager(options: WalletBackedJobManagerOptions): IJobManager;
+/**
+ * Convenience helper for the default transient backend/session mode where one
+ * in-memory vault is enough and durable cloud sync is optional.
+ */
+export declare function createWalletBackedJobManagerInMemory(options: WalletBackedJobManagerOptions): IJobManager;