gdc-sdk-node-ts 2.4.34 → 2.4.35

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

@@ -11,6 +11,16 @@ export type NodeManagedWalletOptions = {
     resolveRecipientJwk?: (recipientDid: string) => Promise<JWK>;
     policy?: Partial<NodeManagedWalletPolicy>;
 };
+export type NodeProfessionalIdentityVpInput = Readonly<{
+    clientId: string;
+    actorDid: string;
+    profileDid?: string;
+    role: string;
+    email?: string;
+    sameAs?: string | readonly string[];
+    telephone?: string;
+    credentialMaterial?: string;
+}>;
 export type NodeCommunicationWalletInitialization = {
     /**
      * Stable secret used to reconstruct the same communication keys after a
@@ -67,26 +77,29 @@ export declare class NodeManagedWallet implements IWallet {
      */
     getPublicJwks(context?: WalletExecutionContext, filter?: WalletKeySelection): Promise<WalletKeyDescriptor[]>;
     /**
-     * Initializes the runtime communication wallet and returns exactly the
-     * public signing/encryption JWKS accepted as `controller.publicKeys` by the
-     * legacy organization activation builder.
+     * Initializes one user/profile device communication wallet and returns only
+     * its public signing/encryption JWKS. The wallet is actor-role neutral: the
+     * same custody contract can back a controller, employee/professional or
+     * individual-controller profile.
      *
-     * This does not replace the professional-role signing key supplied as
-     * `controller.publicSignKey`. The role key identifies the historical legal
-     * representative; these runtime keys protect DIDComm communications.
+     * These communication keys do not replace the actor's person/professional-
+     * role signing key. In the historical legal-representative flow, for example,
+     * this returned set is accepted as `controller.publicKeys`, while the
+     * independent role key is supplied as `controller.publicSignKey`.
      *
      * The caller owns durable wallet custody. When deterministic provisioning is
      * used, protect `seedMaterial` in the portal wallet store (for example with
      * its KMS/KEK and optionally a user PIN) and persist the same non-secret
      * `context.runtime.runtimeId`. A fresh `NodeManagedWallet` reconstructs the
      * same private keys from that seed and context after restart, so private JWKs
-     * do not need separate persistence. ICA and GW receive only this returned
-     * public JWKS.
+     * do not need separate persistence. Only the returned public JWKS may be
+     * submitted when the selected high-level onboarding flow requires it.
      */
     initializeCommunicationJsonWebKeySet(context: WalletExecutionContext, options?: NodeCommunicationWalletInitialization): Promise<JwkSet>;
     /**
      * Returns only the public DIDComm signing/encryption keys for a previously
-     * initialized runtime wallet. Private material never leaves the wallet.
+     * initialized user/profile device runtime wallet. Private material never
+     * leaves the wallet, and the returned keys do not convey an actor role.
      */
     getCommunicationJsonWebKeySet(context: WalletExecutionContext): Promise<JwkSet>;
     /**
@@ -139,6 +152,12 @@ export declare class NodeManagedWallet implements IWallet {
      * Builds one compact JWS using one managed signing key.
      */
     signCompactJws(context: WalletExecutionContext, request: WalletCompactJwsRequest): Promise<string>;
+    /**
+     * Builds and signs the canonical employee/professional VP with the managed
+     * `vp-token-signing` key. Callers provide identity facts only; they do not
+     * assemble JOSE headers, choose a JWK or handle private key material.
+     */
+    signProfessionalIdentityVp(context: WalletExecutionContext, input: NodeProfessionalIdentityVpInput): Promise<string>;
     /**
      * Builds one detached compact JWS using one managed signing key.
      */

package/dist/node-managed-wallet.js

@@ -4,6 +4,7 @@ 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 { buildProfessionalIdentityVpPayload } from 'gdc-common-utils-ts/utils/professional-smart';
 import { NodeCryptoHelper } from './node-crypto-helper.js';
 const DEFAULT_POLICY = {
     defaults: {
@@ -134,21 +135,23 @@ export class NodeManagedWallet {
         return descriptors;
     }
     /**
-     * Initializes the runtime communication wallet and returns exactly the
-     * public signing/encryption JWKS accepted as `controller.publicKeys` by the
-     * legacy organization activation builder.
+     * Initializes one user/profile device communication wallet and returns only
+     * its public signing/encryption JWKS. The wallet is actor-role neutral: the
+     * same custody contract can back a controller, employee/professional or
+     * individual-controller profile.
      *
-     * This does not replace the professional-role signing key supplied as
-     * `controller.publicSignKey`. The role key identifies the historical legal
-     * representative; these runtime keys protect DIDComm communications.
+     * These communication keys do not replace the actor's person/professional-
+     * role signing key. In the historical legal-representative flow, for example,
+     * this returned set is accepted as `controller.publicKeys`, while the
+     * independent role key is supplied as `controller.publicSignKey`.
      *
      * The caller owns durable wallet custody. When deterministic provisioning is
      * used, protect `seedMaterial` in the portal wallet store (for example with
      * its KMS/KEK and optionally a user PIN) and persist the same non-secret
      * `context.runtime.runtimeId`. A fresh `NodeManagedWallet` reconstructs the
      * same private keys from that seed and context after restart, so private JWKs
-     * do not need separate persistence. ICA and GW receive only this returned
-     * public JWKS.
+     * do not need separate persistence. Only the returned public JWKS may be
+     * submitted when the selected high-level onboarding flow requires it.
      */
     async initializeCommunicationJsonWebKeySet(context, options = {}) {
         if (!context.runtime?.runtimeId) {
@@ -164,7 +167,8 @@ export class NodeManagedWallet {
     }
     /**
      * Returns only the public DIDComm signing/encryption keys for a previously
-     * initialized runtime wallet. Private material never leaves the wallet.
+     * initialized user/profile device runtime wallet. Private material never
+     * leaves the wallet, and the returned keys do not convey an actor role.
      */
     async getCommunicationJsonWebKeySet(context) {
         if (!context.runtime?.runtimeId) {
@@ -335,6 +339,37 @@ export class NodeManagedWallet {
         const signature = await this.sign(prepared.signingInput, context, request.key);
         return buildJwtCompact(prepared.encodedHeader, prepared.encodedPayload, signature);
     }
+    /**
+     * Builds and signs the canonical employee/professional VP with the managed
+     * `vp-token-signing` key. Callers provide identity facts only; they do not
+     * assemble JOSE headers, choose a JWK or handle private key material.
+     */
+    async signProfessionalIdentityVp(context, input) {
+        const [vpSigningKey] = await this.getPublicJwks(context, {
+            ownerScope: 'runtime',
+            purpose: 'vp-token-signing',
+        });
+        if (!vpSigningKey)
+            throw new Error('Managed VP signing key is not available.');
+        const payload = buildProfessionalIdentityVpPayload({
+            clientId: input.clientId,
+            actorDid: input.actorDid,
+            role: input.role,
+            ...(input.email ? { email: input.email } : {}),
+            ...(input.sameAs ? { sameAs: input.sameAs } : {}),
+            ...(input.telephone ? { telephone: input.telephone } : {}),
+            ...(input.credentialMaterial ? { credentialMaterial: input.credentialMaterial } : {}),
+        });
+        return this.signCompactJws(context, {
+            header: { typ: 'JWT', jwk: vpSigningKey.publicJwk },
+            claims: {
+                iss: vpSigningKey.kid,
+                sub: input.profileDid || input.actorDid,
+                ...payload,
+            },
+            key: { ownerScope: 'runtime', purpose: 'vp-token-signing' },
+        });
+    }
     /**
      * Builds one detached compact JWS using one managed signing key.
      */

package/dist/organization-employee-lifecycle.js

@@ -218,6 +218,12 @@ export async function enrollInvitedOrganizationEmployeeWithDeps(input, deps) {
         clientInstanceId: input.clientInstanceId,
         dcrRedirectUris: input.dcrRedirectUris,
         dcrClientName: input.dcrClientName,
-        vpToken: input.idToken,
+        // The grant contains the server-verified stable actor alias and role. The
+        // profile runtime signs the VP with its managed DCR wallet after GW has
+        // returned the real client_id; idToken remains only the OIDC account proof.
+        professionalProof: {
+            role: input.grant.employeeRoleCode,
+            sameAs: input.grant.employeeActorIdentifier,
+        },
     });
 }

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

@@ -1,7 +1,7 @@
 import type { JWK } from 'gdc-common-utils-ts/models/jwk';
 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 ConfidentialStorageProfile, type PollOptions, type SubmitAndPollResult } from 'gdc-sdk-core-ts';
+import { type AppInfo, type ConfidentialStorageProfile, type PollOptions, type SubmitAndPollResult } from 'gdc-sdk-core-ts';
 import type { RouteContext } from './individual-onboarding.js';
 import type { HostRouteContext } from './host-onboarding.js';
 import type { SecureDidcommTransportAdapter } from 'gdc-sdk-core-ts';
@@ -31,7 +31,8 @@ export type ServerProfileRecord = Readonly<{
     /** Server-owned policy; browser input is never authoritative for this value. */
     confidentialStorageProfile?: ConfidentialStorageProfile;
     protectedWalletSeed: PinProtectedProfileSecret;
-    protectedVpToken: PinProtectedProfileSecret;
+    /** Present only when this actor kind requires an independent signed role/relationship VP. */
+    protectedVpToken?: PinProtectedProfileSecret;
     failedUnlocks: number;
     lockedUntil?: string;
     createdAt: string;
@@ -95,8 +96,25 @@ export type ServerProfileEnrollmentInput = Readonly<{
      * derives the identity from the wallet key it creates for this profile.
      */
     clientInstanceId?: string;
-    /** Signed actor/controller VP protected with the profile for later proof and session operations. */
-    vpToken: string;
+    /**
+     * Signed actor/controller VP protected for later SMART operations. Required
+     * for organization/professional/member actors. Individual-controller
+     * profiles omit it: their account `id_token`, DCR device binding and
+     * provider-side relationship policy are evaluated independently.
+     */
+    vpToken?: string;
+    /**
+     * High-level employee/professional proof source. When supplied, the SDK
+     * builds and signs the VP with the managed DCR wallet after registration;
+     * callers do not compose JWT/JWK material.
+     */
+    professionalProof?: Readonly<{
+        role: string;
+        email?: string;
+        sameAs?: string | readonly string[];
+        telephone?: string;
+        credentialMaterial?: string;
+    }>;
     /** Redirect URIs owned by this portal/app installation. */
     redirectUris?: string[];
     /** Human-readable portal/app name. */
@@ -132,6 +150,20 @@ export type ServerProfileOrganizationIssueInput = Readonly<{
     verificationInput: LegalOrganizationVerificationTransactionInput;
     pollOptions?: PollOptions;
 }>;
+export type ServerOrganizationControllerVpInput = Readonly<{
+    /** Same protected seed that committed the controller public key to ICA. */
+    walletSeed: string;
+    /** Stable application-owned derivation id reused after every restart. */
+    walletKeyDerivationId: string;
+    /** Terminal ICA/GW verification body containing the issued organization, representative and controller VCs. */
+    verificationResponseBody: unknown;
+    /** Exact organization tenant identifier represented by the controller proof. */
+    tenantId: string;
+    /** Exact audience required by the receiving GW/host policy. */
+    audience: string;
+    /** Optional stable sameAs selector when the response contains several controller credentials. */
+    controllerSameAs?: string;
+}>;
 /** One explicit unlock request; scopes and subject remain session-bound. */
 export type ServerProfileUnlockInput = Readonly<{
     ownerId: string;
@@ -166,6 +198,8 @@ export type ServerProfileSessionManagerOptions = Readonly<{
     sealer: ServerProfileSealer;
     gatewayBaseUrl: string;
     resolveRecipientJwk: (recipientDid: string) => Promise<JWK>;
+    /** Stable identity of the portal/application, shared by all of its user wallets. */
+    appInfo?: AppInfo;
     fetchImpl?: typeof fetch;
     sessionTtlSeconds?: number;
     maxFailedUnlocks?: number;
@@ -196,6 +230,15 @@ export declare class ServerProfileSessionManager {
         walletSeed: string;
         walletKeyDerivationId: string;
     }>): Promise<ServerProfileEnrollmentPublicKey[]>;
+    /**
+     * Builds and signs the canonical controller VP directly from ICA-issued
+     * credentials. The caller never assembles a VP/JWS or exports a private key.
+     *
+     * This proof is independent from the signed OIDC id_token: the VP proves
+     * organization/controller authority, while id_token proves control of the
+     * verified login identifier used by Token/_exchange and DCR.
+     */
+    buildOrganizationControllerVpFromIcaProof(input: ServerOrganizationControllerVpInput): Promise<string>;
     /**
      * Reissues an existing organization controller activation through protected
      * DIDComm transport before a durable profile exists. The deterministic seed

package/dist/server-profile-session.js

@@ -1,6 +1,8 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { randomBytes } from 'node:crypto';
 import { ActorKinds } from 'gdc-common-utils-ts/constants/actor-session';
+import { readLegalOrganizationVerificationCredentialPairFromResponseBody, readServiceControllerCredentialFromResponseBody, } from 'gdc-common-utils-ts/utils/legal-organization-verification-result';
+import { addLegalRepresentativeCredential, addOrganizationCredential, addServiceControllerCredential, createVP, } from 'gdc-common-utils-ts/utils/vp-token';
 import { TransportProfiles, } from 'gdc-sdk-core-ts';
 import { NodeManagedWallet } from './node-managed-wallet.js';
 import { NodeHttpClient } from './node-runtime-client.js';
@@ -62,6 +64,14 @@ export class ServerProfileSessionManager {
             throw new Error('GW DCR did not return client_id.');
         const deviceDid = findText(dcrBody, ['device_did', 'deviceDid', 'did']) || clientId;
         const now = this.now();
+        const managedVpToken = input.vpToken || (input.professionalProof
+            ? await buildManagedProfessionalVp(wallet, context, {
+                clientId,
+                actorDid: input.actorDid,
+                profileDid: input.profileDid,
+                ...input.professionalProof,
+            })
+            : undefined);
         const record = {
             profileId: input.profileId,
             walletKeyDerivationId,
@@ -80,7 +90,9 @@ export class ServerProfileSessionManager {
             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),
+            ...(managedVpToken ? {
+                protectedVpToken: await protectServerProfileSecret(managedVpToken, input.pin, `${input.profileId}:vp-token`, this.options.sealer, this.options.profileProtection),
+            } : {}),
             failedUnlocks: 0,
             createdAt: now.toISOString(),
             updatedAt: now.toISOString(),
@@ -109,6 +121,57 @@ export class ServerProfileSessionManager {
             publicJwk: entry.publicJwk,
         }));
     }
+    /**
+     * Builds and signs the canonical controller VP directly from ICA-issued
+     * credentials. The caller never assembles a VP/JWS or exports a private key.
+     *
+     * This proof is independent from the signed OIDC id_token: the VP proves
+     * organization/controller authority, while id_token proves control of the
+     * verified login identifier used by Token/_exchange and DCR.
+     */
+    async buildOrganizationControllerVpFromIcaProof(input) {
+        requireBase64UrlSeed32(input.walletSeed);
+        const walletKeyDerivationId = normalizedWalletKeyDerivationId(input.walletKeyDerivationId, '');
+        if (!walletKeyDerivationId) {
+            throw new Error('buildOrganizationControllerVpFromIcaProof requires walletKeyDerivationId.');
+        }
+        const tenantId = String(input.tenantId || '').trim();
+        const audience = String(input.audience || '').trim();
+        if (!tenantId)
+            throw new Error('buildOrganizationControllerVpFromIcaProof requires tenantId.');
+        if (!audience)
+            throw new Error('buildOrganizationControllerVpFromIcaProof requires audience.');
+        const { organizationCredential, legalRepresentativeCredential } = readLegalOrganizationVerificationCredentialPairFromResponseBody(input.verificationResponseBody);
+        const controllerCredential = readServiceControllerCredentialFromResponseBody(input.verificationResponseBody, input.controllerSameAs);
+        if (!controllerCredential) {
+            throw new Error('ICA verification response does not contain a ServiceControllerCredential.');
+        }
+        const wallet = await this.createWallet(walletKeyDerivationId, input.walletSeed);
+        const context = walletContext(walletKeyDerivationId);
+        const [actorSigningKey] = await wallet.getPublicJwks(context, {
+            ownerScope: 'profile',
+            purpose: 'actor-signing',
+        });
+        if (!actorSigningKey)
+            throw new Error('Controller actor-signing key is not available.');
+        const vp = createVP({
+            iss: actorSigningKey.kid,
+            sub: tenantId,
+            aud: audience,
+            vp: { holder: actorSigningKey.kid, verifiableCredential: [] },
+        });
+        addOrganizationCredential(vp, organizationCredential);
+        addLegalRepresentativeCredential(vp, legalRepresentativeCredential);
+        addServiceControllerCredential(vp, controllerCredential);
+        return wallet.signCompactJws(context, {
+            header: {
+                typ: 'JWT',
+                jwk: actorSigningKey.publicJwk,
+            },
+            claims: vp,
+            key: { ownerScope: 'profile', purpose: 'actor-signing' },
+        });
+    }
     /**
      * Reissues an existing organization controller activation through protected
      * DIDComm transport before a durable profile exists. The deterministic seed
@@ -126,6 +189,7 @@ export class ServerProfileSessionManager {
             baseUrl: this.options.gatewayBaseUrl,
             ctx: input.routeContext,
             bearerToken: input.bearerToken,
+            appInfo: this.options.appInfo,
             fetchImpl: this.options.fetchImpl,
             transportProfile: TransportProfiles.DidcommEncryptedForm,
             secureTransportAdapter: {
@@ -153,7 +217,9 @@ export class ServerProfileSessionManager {
         let vpToken;
         try {
             seed = await openServerProfileSecret(profile.protectedWalletSeed, input.pin, `${profile.profileId}:wallet-seed`, this.options.sealer);
-            vpToken = await openServerProfileSecret(profile.protectedVpToken, input.pin, `${profile.profileId}:vp-token`, this.options.sealer);
+            vpToken = profile.protectedVpToken
+                ? await openServerProfileSecret(profile.protectedVpToken, input.pin, `${profile.profileId}:vp-token`, this.options.sealer)
+                : undefined;
         }
         catch (reason) {
             if (!(reason instanceof ProfilePinRejectedError))
@@ -183,6 +249,7 @@ export class ServerProfileSessionManager {
             audience: smartTokenEndpoint,
             idToken: input.idToken,
             vpToken,
+            vpTokenFallback: vpToken ? undefined : 'omit',
             clientAssertion: assertion,
             clientAssertionType: 'private_key_jwt',
             smartTokenKind: 'openid-smart',
@@ -247,6 +314,7 @@ export class ServerProfileSessionManager {
             ctx,
             bearerToken,
             fetchImpl: this.options.fetchImpl,
+            appInfo: this.options.appInfo,
         });
     }
     async createWallet(walletKeyDerivationId, seed) {
@@ -323,6 +391,10 @@ function profileSmartAcrValues(actorKind) {
         ? 'urn:antifraud:acr:openid4vp:individual'
         : 'urn:antifraud:acr:openid4vp:employee';
 }
+/** Creates the role VP after DCR has returned the wallet's actual client_id. */
+async function buildManagedProfessionalVp(wallet, context, input) {
+    return wallet.signProfessionalIdentityVp(context, input);
+}
 async function buildWalletClientAssertion(wallet, profile, audience, now) {
     const seconds = Math.floor(now.getTime() / 1000);
     return wallet.signCompactJws(walletContext(profile.walletKeyDerivationId || profile.profileId), {
@@ -361,10 +433,17 @@ function requireEnrollment(input) {
         providerDid: input.providerDid,
         activationCode: input.activationCode,
         idToken: input.idToken,
-        vpToken: input.vpToken,
     }))
         if (!String(value || '').trim())
             throw new Error(`Profile enrollment requires ${name}.`);
+    if (input.actorKind !== ActorKinds.IndividualController
+        && !String(input.vpToken || '').trim()
+        && !input.professionalProof) {
+        throw new Error('Profile enrollment requires vpToken for this actor kind.');
+    }
+    if (input.professionalProof && !String(input.professionalProof.role || '').trim()) {
+        throw new Error('Profile enrollment professionalProof requires role.');
+    }
     if (!input.allowedSubjectDids.length)
         throw new Error('Profile enrollment requires an allowed subject.');
 }

package/package.json

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