gdc-sdk-node-ts 2.4.23 → 2.4.30

package/README.md

@@ -238,6 +238,11 @@ Current runtime boundary:
 - `OrganizationControllerSdk.confirmOrganizationLicenseOrder(...)` now uses the
   public host `Order/_batch` route used by GW CORE for portal-managed
   post-payment seat activation
+- that route is commercial routing only: `iss` remains the exact controller DID
+  registered by tenant DCR, `aud` remains the tenant id, and GW resolves its
+  JWS/JWE key identifiers from the tenant rather than the host
+- applications use the high-level SDK method and configured transport profile;
+  they do not populate `meta.jws`, move public keys, or construct DIDComm by hand
 - the long root lifecycle is still not fully closed because the suite does not
   yet orchestrate the whole `license list -> pay -> confirm -> relist -> two
   employees -> selective purge -> cleanup` dialogue as one single test
@@ -288,9 +293,11 @@ npm run test:e2e:live-gw:all
 
 Profile note:
 
-- `didcomm-plain` is the current live baseline implemented by the Node runtime client
+- `didcomm-plain` is the explicit demo-only live profile
 - `legacy-fhir` exercises raw `application/fhir+json` async batch submission for `org.hl7.fhir.*`
 - `all` runs every implemented profile from the same suite file
+- each `NodeHttpClient` selects one profile at construction; every facade
+  operation and poll uses it and cannot override or downgrade it
 
 Run the IPS ingestion/search branch as well:
 
@@ -638,8 +645,8 @@ modules below.
   - types: `SmartTokenRequestInput`, `SmartTokenExchangeResult`
   - function: `requestSmartTokenWithDeps(...)`
 - [`src/resource-operations.ts`](src/resource-operations.ts)
-  - types: `OrganizationEmployeeCreationInput`, `IpsOrFhirImportInput`, `RelatedPersonUpsertInput`, `CommunicationIngestionInput`, `ClinicalDateRange`, `ClinicalBundleSearchInput`, `ConsentActorTargetInput`, `GrantProfessionalAccessInput`, `GrantProfessionalAccessResult`, `DigitalTwinGenerationInput`
-  - functions: `createOrganizationEmployeeWithDeps(...)`, `importIpsOrFhirAndUpdateIndexWithDeps(...)`, `upsertRelatedPersonAndPollWithDeps(...)`, `ingestCommunicationAndUpdateIndexWithDeps(...)`, `searchClinicalBundleWithDeps(...)`, `searchLatestIpsWithDeps(...)`, `grantProfessionalAccessWithDeps(...)`, `generateDigitalTwinFromSubjectDataWithDeps(...)`
+  - types: `OrganizationEmployeeCreationInput`, `IpsOrFhirImportInput`, `RelatedPersonUpsertInput`, `CommunicationIngestionInput`, `ClinicalDateRange`, `ClinicalBundleSearchInput`, `ConsentActorTargetInput`, `GrantProfessionalAccessInput`, `GrantProfessionalAccessResult`, `DigitalTwinSecondaryUseConsentInput`, `DigitalTwinSubjectLinkPurgeInput`
+  - functions: `createOrganizationEmployeeWithDeps(...)`, `importIpsOrFhirAndUpdateIndexWithDeps(...)`, `upsertRelatedPersonAndPollWithDeps(...)`, `ingestCommunicationAndUpdateIndexWithDeps(...)`, `searchClinicalBundleWithDeps(...)`, `searchLatestIpsWithDeps(...)`, `grantProfessionalAccessWithDeps(...)`, `setDigitalTwinSecondaryUseConsentWithDeps(...)`, `purgeDigitalTwinSubjectLinkWithDeps(...)`
 - [`src/digital-twin.ts`](src/digital-twin.ts)
   - types: `DigitalTwinSearchInput`, `DigitalTwinSelectionInput`, `DigitalTwinResearchTag`, `DigitalTwinMaterializationInput`
   - functions: `searchDigitalTwinsWithDeps(...)`, `saveDigitalTwinSelectionWithDeps(...)`, `materializeDigitalTwinWithDeps(...)`
@@ -789,10 +796,14 @@ Live E2E legal PDF source:
 Recovery-specific live rule:
 
 - `Organization/_issue` can succeed and still be followed by `_exchange` failure
-  if the controller `id_token` is not production-shaped enough
-- the current GW `_exchange` path expects at least:
-  - syntactically valid JWT format
-  - `tenant_id` claim matching the target tenant
+  if the controller `id_token` is invalid, expired or does not prove the
+  expected actor/contact
+- the current GW `_exchange` path expects a valid IdP token but takes tenant
+  authority from the already validated request route
+- a custom `tenant_id` claim is optional; when present it must match the route
+  and cannot select another tenant
+- a failed poll `OperationOutcome` is surfaced before the helper checks for
+  `initial_access_token`, preserving the real GW diagnostic
 - the bundled recovery runner generates a syntactically valid demo JWT if
   `CONTROLLER_ID_TOKEN` is not provided, but production/staging should use a
   real IdP-issued token

package/dist/constants/lifecycle.d.ts

@@ -16,7 +16,11 @@ export declare const GwCoreLifecycleAction: Readonly<{
     readonly Transaction: "_transaction";
     readonly TransactionResponse: "_transaction-response";
     readonly Disable: "_disable";
+    readonly Enable: "_enable";
     readonly Purge: "_purge";
+    readonly Status: "_status";
+    readonly DisableDescendants: "_disable-descendants";
+    readonly PurgeDescendants: "_purge-descendants";
 }>;
 /**
  * Entry request methods currently used by GW CORE lifecycle handlers.
@@ -36,6 +40,10 @@ export declare const GwCoreLifecycleRequestType: Readonly<{
     readonly IndividualOrganizationDisable: "Family-disable-request-v1.0";
     readonly IndividualOrganizationPurge: "Family-purge-request-v1.0";
     readonly IndividualMemberPurge: "RelatedPerson-purge-request-v1.0";
+    readonly TenantStatus: "Organization-lifecycle-status-request-v1.0";
+    readonly TenantEnable: "Organization-enable-request-v1.0";
+    readonly TenantDisableDescendants: "Organization-disable-descendants-request-v1.0";
+    readonly TenantPurgeDescendants: "Organization-purge-descendants-request-v1.0";
 }>;
 /**
  * Named TODO ids kept close to the current lifecycle implementation so the

package/dist/constants/lifecycle.js

@@ -18,7 +18,11 @@ export const GwCoreLifecycleAction = Object.freeze({
     Transaction: '_transaction',
     TransactionResponse: '_transaction-response',
     Disable: '_disable',
+    Enable: '_enable',
     Purge: '_purge',
+    Status: '_status',
+    DisableDescendants: '_disable-descendants',
+    PurgeDescendants: '_purge-descendants',
 });
 /**
  * Entry request methods currently used by GW CORE lifecycle handlers.
@@ -38,6 +42,10 @@ export const GwCoreLifecycleRequestType = Object.freeze({
     IndividualOrganizationDisable: 'Family-disable-request-v1.0',
     IndividualOrganizationPurge: 'Family-purge-request-v1.0',
     IndividualMemberPurge: LifecycleRequestType.RelatedPersonPurge,
+    TenantStatus: 'Organization-lifecycle-status-request-v1.0',
+    TenantEnable: 'Organization-enable-request-v1.0',
+    TenantDisableDescendants: 'Organization-disable-descendants-request-v1.0',
+    TenantPurgeDescendants: 'Organization-purge-descendants-request-v1.0',
 });
 /**
  * Named TODO ids kept close to the current lifecycle implementation so the

package/dist/device-activation.d.ts

@@ -12,10 +12,57 @@ export type EmployeeDeviceActivationRequestInput = {
     sector?: string;
     activationCode: string;
     idToken: string;
-    dcrPayload: Record<string, unknown>;
+    /** Canonical high-level description converted to OpenID DCR metadata by the SDK. */
+    deviceRegistration?: ProfileDeviceRegistrationInput;
+    /**
+     * @deprecated Low-level OpenID escape hatch. Use
+     * `createProfileDeviceActivationRequest(...).set...build()` instead.
+     */
+    dcrPayload?: Record<string, unknown>;
     timeoutSeconds?: number;
     intervalSeconds?: number;
 };
+/** Application concepts required to bind one portal/app installation. */
+export type ProfileDeviceRegistrationInput = Readonly<{
+    clientInstanceId: string;
+    clientName: string;
+    applicationType: 'native' | 'web';
+    redirectUris: readonly string[];
+    publicJwks: readonly Record<string, unknown>[];
+    deviceName?: string;
+    actorDid?: string;
+    profileDid?: string;
+}>;
+/** Advanced typed editor used by SDK runtimes that already own profile keys. */
+export interface ProfileDeviceActivationDraft {
+    setClientInstanceId(value: string): ProfileDeviceActivationDraft;
+    setClientName(value: string): ProfileDeviceActivationDraft;
+    setApplicationType(value: 'native' | 'web'): ProfileDeviceActivationDraft;
+    setRedirectUris(values: readonly string[]): ProfileDeviceActivationDraft;
+    setPublicJwks(values: readonly Record<string, unknown>[]): ProfileDeviceActivationDraft;
+    setDeviceName(value: string): ProfileDeviceActivationDraft;
+    setActorDid(value: string): ProfileDeviceActivationDraft;
+    setProfileDid(value: string): ProfileDeviceActivationDraft;
+    setTimeoutSeconds(value: number): ProfileDeviceActivationDraft;
+    setIntervalSeconds(value: number): ProfileDeviceActivationDraft;
+    build(): EmployeeDeviceActivationRequestInput & {
+        deviceRegistration: ProfileDeviceRegistrationInput;
+    };
+}
+/**
+ * Starts an advanced profile-device activation request.
+ *
+ * Product portals should normally use `ServerProfileSessionManager.enroll`,
+ * which provisions the wallet and calls this editor internally. This surface
+ * exists for runtimes that already own and select the profile public keys.
+ */
+export declare function createProfileDeviceActivationRequest(input: Readonly<{
+    activationCode: string;
+    idToken: string;
+    tenantId?: string;
+    jurisdiction?: string;
+    sector?: string;
+}>): ProfileDeviceActivationDraft;
 export type EmployeeDeviceActivationResult = {
     initialAccessToken: string;
     exchange: SubmitAndPollResult;

package/dist/device-activation.js

@@ -2,6 +2,60 @@
 import { resolvePollOptionsFromSeconds } from './poll-options.js';
 import { IdentityAuthRequestFields, IdentityAuthResponseFields, IdentityDcrMetadataFields, IdentityDeviceInfoFields, } from 'gdc-common-utils-ts/constants/identity-auth';
 import { buildEmployeeDeviceRevocationBody } from 'gdc-common-utils-ts/utils/organization-employee-lifecycle';
+/**
+ * Starts an advanced profile-device activation request.
+ *
+ * Product portals should normally use `ServerProfileSessionManager.enroll`,
+ * which provisions the wallet and calls this editor internally. This surface
+ * exists for runtimes that already own and select the profile public keys.
+ */
+export function createProfileDeviceActivationRequest(input) {
+    const activationCode = requiredText(input.activationCode, 'activation code');
+    const idToken = requiredText(input.idToken, 'signed identity token');
+    let clientInstanceId = '';
+    let clientName = '';
+    let applicationType;
+    let redirectUris = [];
+    let publicJwks = [];
+    let deviceName = '';
+    let actorDid = '';
+    let profileDid = '';
+    let timeoutSeconds;
+    let intervalSeconds;
+    const draft = {
+        setClientInstanceId(value) { clientInstanceId = normalizedText(value); return draft; },
+        setClientName(value) { clientName = normalizedText(value); return draft; },
+        setApplicationType(value) { applicationType = value; return draft; },
+        setRedirectUris(values) { redirectUris = uniqueText(values); return draft; },
+        setPublicJwks(values) { publicJwks = values.map((value) => ({ ...value })); return draft; },
+        setDeviceName(value) { deviceName = normalizedText(value); return draft; },
+        setActorDid(value) { actorDid = normalizedText(value); return draft; },
+        setProfileDid(value) { profileDid = normalizedText(value); return draft; },
+        setTimeoutSeconds(value) { timeoutSeconds = positiveNumber(value, 'timeout seconds'); return draft; },
+        setIntervalSeconds(value) { intervalSeconds = positiveNumber(value, 'interval seconds'); return draft; },
+        build() {
+            const registration = {
+                clientInstanceId: requiredText(clientInstanceId, 'client instance id'),
+                clientName: requiredText(clientName, 'client name'),
+                applicationType: applicationType || failRequired('application type'),
+                redirectUris: requiredList(redirectUris, 'redirect URI'),
+                publicJwks: requiredList(publicJwks, 'public JWK'),
+                ...(deviceName ? { deviceName } : {}),
+                ...(actorDid ? { actorDid } : {}),
+                ...(profileDid ? { profileDid } : {}),
+            };
+            return {
+                ...input,
+                activationCode,
+                idToken,
+                deviceRegistration: registration,
+                ...(timeoutSeconds !== undefined ? { timeoutSeconds } : {}),
+                ...(intervalSeconds !== undefined ? { intervalSeconds } : {}),
+            };
+        },
+    };
+    return draft;
+}
 export async function revokeEmployeeDeviceWithDeps(deps) {
     const licenseId = String(deps.input.licenseId || '').trim();
     const clientId = String(deps.input.clientId || '').trim();
@@ -28,6 +82,16 @@ export async function activateEmployeeDeviceWithActivationCodeWithDeps(deps) {
         [IdentityAuthRequestFields.ClientInstanceId]: clientInstanceId,
     };
     const exchange = await deps.submitAndPollWithBearerToken(deps.input.idToken, deps.identityTokenExchangePath(deps.routeCtx), deps.identityTokenExchangePollPath(deps.routeCtx), exchangePayload, deps.input.pollOptions);
+    const exchangeDiagnostics = firstFailedOperationOutcomeDiagnostic(exchange.poll.body)
+        || firstFailedOperationOutcomeDiagnostic(exchange.submit.body);
+    if (exchangeDiagnostics) {
+        throw new Error(`activateEmployeeDeviceWithActivationCode: exchange failed: ${exchangeDiagnostics}`);
+    }
+    const failedExchangeStatus = [exchange.submit.status, exchange.poll.status]
+        .find((status) => status < 200 || status >= 300);
+    if (failedExchangeStatus !== undefined) {
+        throw new Error(`activateEmployeeDeviceWithActivationCode: exchange failed (HTTP ${failedExchangeStatus}).`);
+    }
     const pollBody = exchange.poll.body || {};
     const exchangeBody = (pollBody.body || pollBody);
     const initialAccessToken = String(exchangeBody[IdentityAuthResponseFields.InitialAccessToken]
@@ -56,10 +120,58 @@ export async function activateEmployeeDeviceWithActivationRequestWithDeps(deps)
     return deps.activateEmployeeDeviceWithActivationCode(deps.routeCtx, {
         activationCode: deps.input.activationCode,
         idToken: deps.input.idToken,
-        dcrPayload: deps.input.dcrPayload,
+        dcrPayload: resolveDcrPayload(deps.input),
         pollOptions,
     });
 }
+function resolveDcrPayload(input) {
+    if (input.deviceRegistration && input.dcrPayload) {
+        throw new Error('Device activation accepts either deviceRegistration or the deprecated dcrPayload, not both.');
+    }
+    if (input.deviceRegistration) {
+        const registration = input.deviceRegistration;
+        return {
+            [IdentityDcrMetadataFields.ApplicationType]: registration.applicationType,
+            [IdentityDcrMetadataFields.ClientName]: registration.clientName,
+            [IdentityDcrMetadataFields.RedirectUris]: [...registration.redirectUris],
+            [IdentityDcrMetadataFields.Jwks]: { keys: registration.publicJwks.map((value) => ({ ...value })) },
+            [IdentityDcrMetadataFields.ExtendedDeviceInfo]: {
+                [IdentityDeviceInfoFields.DeviceId]: registration.clientInstanceId,
+                device_name: registration.deviceName || registration.clientName,
+            },
+            ...(registration.actorDid ? { [IdentityDcrMetadataFields.ActorDid]: registration.actorDid } : {}),
+            ...(registration.profileDid ? { [IdentityDcrMetadataFields.ProfileDid]: registration.profileDid } : {}),
+        };
+    }
+    if (input.dcrPayload)
+        return { ...input.dcrPayload };
+    throw new Error('Device activation requires a device registration built by createProfileDeviceActivationRequest.');
+}
+function normalizedText(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function requiredText(value, label) {
+    const normalized = normalizedText(value);
+    if (!normalized)
+        throw new Error(`Profile device activation requires ${label}.`);
+    return normalized;
+}
+function uniqueText(values) {
+    return [...new Set((values || []).map((value) => normalizedText(value)).filter(Boolean))];
+}
+function requiredList(values, label) {
+    if (!values.length)
+        throw new Error(`Profile device activation requires at least one ${label}.`);
+    return [...values];
+}
+function positiveNumber(value, label) {
+    if (!Number.isFinite(value) || value <= 0)
+        throw new Error(`Profile device activation ${label} must be positive.`);
+    return value;
+}
+function failRequired(label) {
+    throw new Error(`Profile device activation requires ${label}.`);
+}
 function createRuntimeUuid() {
     const fromCrypto = globalThis.crypto?.randomUUID?.();
     if (fromCrypto) {
@@ -67,3 +179,47 @@ function createRuntimeUuid() {
     }
     return `fallback-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 }
+/** Preserves a terminal async GW diagnostic before checking success fields. */
+function firstFailedOperationOutcomeDiagnostic(value) {
+    if (typeof value === 'string') {
+        const candidate = value.trim();
+        if (!candidate || (candidate[0] !== '{' && candidate[0] !== '['))
+            return undefined;
+        try {
+            return firstFailedOperationOutcomeDiagnostic(JSON.parse(candidate));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!value || typeof value !== 'object')
+        return undefined;
+    if (Array.isArray(value)) {
+        for (const child of value) {
+            const diagnostic = firstFailedOperationOutcomeDiagnostic(child);
+            if (diagnostic)
+                return diagnostic;
+        }
+        return undefined;
+    }
+    const record = value;
+    if (record.resourceType === 'OperationOutcome' && Array.isArray(record.issue)) {
+        for (const rawIssue of record.issue) {
+            if (!rawIssue || typeof rawIssue !== 'object')
+                continue;
+            const issue = rawIssue;
+            const severity = String(issue.severity || '').trim().toLowerCase();
+            if (severity !== 'error' && severity !== 'fatal')
+                continue;
+            const diagnostic = String(issue.diagnostics || '').trim();
+            if (diagnostic)
+                return diagnostic;
+        }
+    }
+    for (const child of Object.values(record)) {
+        const diagnostic = firstFailedOperationOutcomeDiagnostic(child);
+        if (diagnostic)
+            return diagnostic;
+    }
+    return undefined;
+}

package/dist/digital-twin.d.ts

@@ -3,6 +3,10 @@ import type { MetaTagCoding } from 'gdc-common-utils-ts/models/confidential-stor
 import type { RouteContext } from './individual-onboarding.js';
 import type { PollOptions, SubmitAndPollResult } from './orchestration/client-port.js';
 export type DigitalTwinFhirFormat = 'org.hl7.fhir.r4' | 'org.hl7.fhir.api';
+/** Returns whether a value can be used as a pseudonymous digital-twin subject. */
+export declare function isDigitalTwinSubjectId(value: unknown): value is string;
+/** Rejects operational DIDs and malformed or caller-invented subject shapes. */
+export declare function assertDigitalTwinSubjectId(value: unknown): asserts value is string;
 /** Search parameters added by the digital-twin Composition profile. */
 export declare const DigitalTwinSearchParameter: Readonly<{
     Section: "section";

package/dist/digital-twin.js

@@ -2,6 +2,17 @@
 import { randomUUID } from 'node:crypto';
 import { HealthcareDocumentTypes } from 'gdc-common-utils-ts/constants';
 import { CompositionClaim } from 'gdc-common-utils-ts/models';
+const DIGITAL_TWIN_SUBJECT_URN_UUID = /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Returns whether a value can be used as a pseudonymous digital-twin subject. */
+export function isDigitalTwinSubjectId(value) {
+    return DIGITAL_TWIN_SUBJECT_URN_UUID.test(String(value || '').trim());
+}
+/** Rejects operational DIDs and malformed or caller-invented subject shapes. */
+export function assertDigitalTwinSubjectId(value) {
+    if (!isDigitalTwinSubjectId(value)) {
+        throw new Error('Digital twin subject must be a valid urn:uuid identifier.');
+    }
+}
 /** Search parameters added by the digital-twin Composition profile. */
 export const DigitalTwinSearchParameter = Object.freeze({
     Section: 'section',
@@ -61,6 +72,9 @@ export function readDigitalTwinSearchResult(operation) {
         throw new Error('Digital twin search did not return a Composition result set.');
     }
     const matches = responseEntry.resource.data;
+    for (const match of matches) {
+        assertDigitalTwinSubjectId(match?.[CompositionClaim.Subject]);
+    }
     const parsedTotal = Number(responseEntry.resource.total);
     return {
         total: Number.isFinite(parsedTotal) ? parsedTotal : matches.length,
@@ -73,8 +87,7 @@ export async function saveDigitalTwinSelectionWithDeps(ctx, input, deps) {
     const twinSubjectId = String(input.twinSubjectId || '').trim();
     const section = String(input.section || '').trim();
     const authorDid = String(input.authorDid || '').trim();
-    if (!twinSubjectId)
-        throw new Error('twinSubjectId is required.');
+    assertDigitalTwinSubjectId(twinSubjectId);
     if (!section)
         throw new Error('Digital twin selection section is required.');
     if (!authorDid)
@@ -146,8 +159,7 @@ export async function searchDigitalTwinsWithDeps(ctx, input, deps) {
 /** Materializes one selected pseudonymous twin as a research summary Bundle. */
 export async function materializeDigitalTwinWithDeps(ctx, input, deps) {
     const twinSubjectId = String(input.twinSubjectId || '').trim();
-    if (!twinSubjectId)
-        throw new Error('twinSubjectId is required.');
+    assertDigitalTwinSubjectId(twinSubjectId);
     const format = input.format || 'org.hl7.fhir.r4';
     const thid = String(input.thid || randomUUID());
     const parameters = [

package/dist/host-onboarding.d.ts

@@ -7,3 +7,10 @@
  */
 export { confirmLegalOrganizationOrderWithDeps, HostLifecycleRequestType, HostedTenantLifecycleRequestType, submitHostedTenantLifecycleWithDeps, } from 'gdc-sdk-core-ts';
 export type { HostingControllerFacade, HostLifecycleInput, HostRouteContext, HostedTenantLifecycleInput, LegalOrganizationOrderInput, } from 'gdc-sdk-core-ts';
+/** Descendant groups that a controller can clean explicitly before tenant shutdown. */
+/**
+ * Tenant-owned subject group supported by the generic cleanup endpoint.
+ * Employees use their dedicated encrypted lifecycle so license release and
+ * audit metadata cannot be bypassed.
+ */
+export type HostedTenantDescendantKind = 'individuals';

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

@@ -1,6 +1,6 @@
 import { CryptographyService } from 'gdc-common-utils-ts/CryptographyService';
 import type { ICryptoHelper } from 'gdc-common-utils-ts/interfaces/ICryptoHelper';
-import type { IWallet, WalletAlgorithm, WalletCompactJweRequest, WalletCompactJwsRequest, WalletDetachedJwsRequest, WalletExecutionContext, WalletKeyDescriptor, WalletKeyPurpose, WalletKeySelection, WalletPackOptions, WalletProvisionRequest, WalletUnpackOptions } from 'gdc-sdk-core-ts';
+import type { IWallet, WalletAlgorithm, WalletCompactJweRequest, WalletCompactJwsRequest, WalletDetachedJwsRequest, WalletExecutionContext, WalletKeyDescriptor, WalletKeyPurpose, WalletKeySelection, WalletPackOptions, WalletProvisionMode, WalletProvisionRequest, WalletUnpackOptions } from 'gdc-sdk-core-ts';
 import type { JWK, JwkSet } from 'gdc-common-utils-ts/models/jwk';
 export type NodeManagedWalletPolicy = {
     defaults: Partial<Record<WalletKeyPurpose, WalletAlgorithm>>;
@@ -11,6 +11,20 @@ export type NodeManagedWalletOptions = {
     resolveRecipientJwk?: (recipientDid: string) => Promise<JWK>;
     policy?: Partial<NodeManagedWalletPolicy>;
 };
+export type NodeCommunicationWalletInitialization = {
+    /**
+     * Stable secret used to reconstruct the same communication keys after a
+     * process restart. Persist it only through the portal's protected wallet
+     * store; never send it to ICA or GW.
+     */
+    seedMaterial?: string | Uint8Array;
+    /**
+     * Defaults to deterministic when seedMaterial is present, otherwise random.
+     * Random keys are suitable only when the wallet implementation itself is
+     * durably persisted.
+     */
+    mode?: WalletProvisionMode;
+};
 /**
  * Node-focused managed wallet implementation for BFF, portal, and backend flows.
  *
@@ -20,6 +34,11 @@ export type NodeManagedWalletOptions = {
  * - OpenID/JWT signing
  * - DIDComm-style transport wrapping
  * - confidential document protection
+ *
+ * OpenID boundary: managing an `openid-id-token-signing` key and producing a
+ * compact JWT does not turn this wallet into an OpenID Provider. The hosting
+ * portal/BFF must authenticate the account, verify any asserted email, publish
+ * provider metadata and JWKS, and be explicitly trusted by the receiving GW.
  */
 export declare class NodeManagedWallet implements IWallet {
     private readonly cryptoHelper;
@@ -47,6 +66,27 @@ export declare class NodeManagedWallet implements IWallet {
      * Returns the currently available public JWKs for the selected context and filter.
      */
     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.
+     *
+     * 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.
+     *
+     * The caller owns durable wallet custody. When deterministic provisioning is
+     * used, protect `seedMaterial` in the portal wallet store (for example behind
+     * the user's PIN and a server-held KEK) so the same private keys can be
+     * reconstructed after restart. ICA and GW receive only this returned public
+     * JWKS.
+     */
+    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.
+     */
+    getCommunicationJsonWebKeySet(context: WalletExecutionContext): Promise<JwkSet>;
     /**
      * Computes a digest of a string using the configured runtime helper.
      */

package/dist/node-managed-wallet.js

@@ -25,6 +25,11 @@ const DEFAULT_POLICY = {
  * - OpenID/JWT signing
  * - DIDComm-style transport wrapping
  * - confidential document protection
+ *
+ * OpenID boundary: managing an `openid-id-token-signing` key and producing a
+ * compact JWT does not turn this wallet into an OpenID Provider. The hosting
+ * portal/BFF must authenticate the account, verify any asserted email, publish
+ * provider metadata and JWKS, and be explicitly trusted by the receiving GW.
  */
 export class NodeManagedWallet {
     /**
@@ -128,6 +133,53 @@ 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.
+     *
+     * 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.
+     *
+     * The caller owns durable wallet custody. When deterministic provisioning is
+     * used, protect `seedMaterial` in the portal wallet store (for example behind
+     * the user's PIN and a server-held KEK) so the same private keys can be
+     * reconstructed after restart. ICA and GW receive only this returned public
+     * JWKS.
+     */
+    async initializeCommunicationJsonWebKeySet(context, options = {}) {
+        if (!context.runtime?.runtimeId) {
+            throw new Error('Communication wallet initialization requires context.runtime.runtimeId.');
+        }
+        await this.provisionManagedKeys(context, {
+            ownerScope: 'runtime',
+            purposes: ['comm-signing', 'comm-encryption'],
+            ...(options.seedMaterial !== undefined ? { seedMaterial: options.seedMaterial } : {}),
+            mode: options.mode ?? (options.seedMaterial !== undefined ? 'deterministic' : 'random'),
+        });
+        return this.getCommunicationJsonWebKeySet(context);
+    }
+    /**
+     * Returns only the public DIDComm signing/encryption keys for a previously
+     * initialized runtime wallet. Private material never leaves the wallet.
+     */
+    async getCommunicationJsonWebKeySet(context) {
+        if (!context.runtime?.runtimeId) {
+            throw new Error('Communication JWKS lookup requires context.runtime.runtimeId.');
+        }
+        const descriptors = await this.getPublicJwks(context, { ownerScope: 'runtime' });
+        return {
+            keys: descriptors
+                .filter((entry) => entry.purpose === 'comm-signing' || entry.purpose === 'comm-encryption')
+                .map((entry) => ({
+                ...entry.publicJwk,
+                kid: entry.publicJwk.kid ?? entry.kid,
+                use: entry.use,
+                alg: entry.publicJwk.alg ?? entry.alg,
+            })),
+        };
+    }
     /**
      * Computes a digest of a string using the configured runtime helper.
      */