gdc-sdk-node-ts 2.4.40 → 2.4.42

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

@@ -2,6 +2,11 @@ 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 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';
@@ -205,6 +210,69 @@ export type ResolvedServerProfileSession = Readonly<{
         }>): Promise<unknown>;
     }>;
 }>;
+/**
+ * Server-only authorization material used to reopen one registered controller.
+ *
+ * A product may let this manager open the PIN-protected seed directly, or may
+ * pass the same seed after its own passkey/session policy has authorized and
+ * unsealed it. `authorizedWalletSeed` must never cross a browser/API boundary.
+ */
+export type ServerOrganizationControllerOpenInput = Readonly<{
+    ownerId: string;
+    profileId: string;
+    /** Fresh signed OIDC id_token used as the HTTP bearer for this operation. */
+    idToken: string;
+    /** User-entered or product-managed profile PIN; mutually exclusive with authorizedWalletSeed. */
+    pin?: string;
+    /** Already-authorized server-only 32-byte base64url seed; mutually exclusive with pin. */
+    authorizedWalletSeed?: string;
+}>;
+/** High-level controller facade plus its immutable durable profile metadata. */
+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;
@@ -275,6 +343,25 @@ export declare class ServerProfileSessionManager {
      */
     refreshSession(ownerId: string, sessionId: string, idToken: string): Promise<ResolvedServerProfileSession>;
     resolveSession(ownerId: string, sessionId: string): Promise<ResolvedServerProfileSession>;
+    /**
+     * Opens the high-level organization-controller API without exposing wallet,
+     * DIDComm, DCR or HTTP-client plumbing to the integrating BFF.
+     *
+     * The durable profile remains authoritative for actor DID, provider DID,
+     * route and DCR client id. The reconstructed keys must match the public keys
+     * 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

@@ -6,6 +6,9 @@ import { addLegalRepresentativeCredential, addOrganizationCredential, addService
 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';
@@ -408,6 +411,159 @@ export class ServerProfileSessionManager {
             },
         };
     }
+    /**
+     * Opens the high-level organization-controller API without exposing wallet,
+     * DIDComm, DCR or HTTP-client plumbing to the integrating BFF.
+     *
+     * The durable profile remains authoritative for actor DID, provider DID,
+     * route and DCR client id. The reconstructed keys must match the public keys
+     * registered for that profile before any gateway request can be sent.
+     */
+    async openOrganizationController(input) {
+        const profile = await this.requireOwnedProfile(input.ownerId, input.profileId);
+        if (profile.actorKind !== ActorKinds.OrganizationController || profile.actorMode !== 'controller') {
+            throw new Error('Profile is not an organization controller.');
+        }
+        const idToken = String(input.idToken || '').trim();
+        if (!idToken)
+            throw new Error('Opening an organization controller requires a signed OIDC idToken.');
+        const hasPin = Boolean(String(input.pin || '').trim());
+        const hasAuthorizedSeed = Boolean(String(input.authorizedWalletSeed || '').trim());
+        if (hasPin === hasAuthorizedSeed) {
+            throw new Error('Opening an organization controller 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 client = new NodeHttpClient({
+            baseUrl: this.options.gatewayBaseUrl,
+            ctx: profile.routeContext,
+            bearerToken: idToken,
+            fetchImpl: this.options.fetchImpl,
+            appInfo: this.options.appInfo,
+            transportProfile: TransportProfiles.DidcommEncryptedForm,
+            secureTransportAdapter,
+        });
+        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)
@@ -489,6 +645,29 @@ export class ServerProfileSessionManager {
 function bindTransportActor(message, actorDid, clientId) {
     return { ...message, iss: actorDid, client_id: clientId };
 }
+/** Binds the encrypted request to the immutable controller registration. */
+function bindOrganizationControllerTransport(message, profile) {
+    return {
+        ...message,
+        iss: profile.actorDid,
+        aud: profile.providerDid,
+        client_id: profile.clientId,
+    };
+}
+/** Refuses a wrong or rotated seed before it can produce network traffic. */
+async function requireRegisteredProfileKeys(wallet, context, profile) {
+    const derived = await wallet.getPublicJwks(context, {});
+    const derivedKids = new Set(derived.map((entry) => String(entry.kid || '').trim()).filter(Boolean));
+    const registeredKids = profile.publicJwks
+        .map((jwk) => String(jwk.kid || '').trim())
+        .filter(Boolean);
+    if (!registeredKids.length || registeredKids.some((kid) => !derivedKids.has(kid))) {
+        throw new Error('Authorized wallet seed does not match registered profile keys.');
+    }
+    if (profile.clientInstanceId && !derivedKids.has(profile.clientInstanceId)) {
+        throw new Error('Authorized wallet seed does not match the registered client instance.');
+    }
+}
 /** Keeps the OpenID proof class aligned with the durable actor profile. */
 function profileSmartAcrValues(actorKind) {
     return actorKind === ActorKinds.IndividualController

package/package.json

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