gdc-sdk-node-ts 2.4.24 → 2.4.31

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
@@ -640,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(...)`
@@ -791,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,18 @@ 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';
+/**
+ * Creates the opaque FHIR identifier for the provider-level secondary-use
+ * Consent. Call this exactly once when the server creates the subject's index
+ * enrollment, persist the result there, and reuse it for every permit/deny.
+ * It is intentionally random and must not be derived from a subject or tenant
+ * identifier.
+ */
+export declare function createDigitalTwinSecondaryUseConsentIdentifier(): string;
+/** 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,27 @@
 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;
+/**
+ * Creates the opaque FHIR identifier for the provider-level secondary-use
+ * Consent. Call this exactly once when the server creates the subject's index
+ * enrollment, persist the result there, and reuse it for every permit/deny.
+ * It is intentionally random and must not be derived from a subject or tenant
+ * identifier.
+ */
+export function createDigitalTwinSecondaryUseConsentIdentifier() {
+    return `urn:uuid:${randomUUID()}`;
+}
+/** 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 +82,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 +97,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 +169,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.
      */

package/dist/node-runtime-client.d.ts

@@ -3,6 +3,7 @@ import type { AppInfo } from 'gdc-sdk-core-ts';
 import type { IndividualOrganizationLifecycleInput } from 'gdc-sdk-core-ts';
 import { type ResolvedAppInfo, type CommunicationClinicalFormatRenderers, type SecureDidcommTransportAdapter, type TransportProfile } from 'gdc-sdk-core-ts';
 import { type HostRouteContext, type HostedTenantLifecycleInput } from './host-onboarding.js';
+import type { HostedTenantDescendantKind } from './host-onboarding.js';
 import type { NodeLegalOrganizationVerificationTransactionInput, NodeOrganizationDidBindingInput, NodeOrganizationActivationInput } from './orchestration/client-port.js';
 import { type IndividualOrganizationConfirmOrderInput, type RouteContext } from './individual-onboarding.js';
 import { type EnsureFamilyOrganizationRegistrationInput } from './family-organization-registration.js';
@@ -11,7 +12,7 @@ import { type SmartTokenRequestInput } from './smart-token.js';
 import { type EmployeeDeviceActivationRequestInput, type EmployeeDeviceActivationResult, type EmployeeDeviceRevocationInput } from './device-activation.js';
 import { type OrganizationLicenseOrderConfirmInput } from './organization-license-order.js';
 import { type IndividualOrganizationBootstrapInput, type IndividualOrganizationStartResult } from './individual-start.js';
-import { type CommunicationIngestionInput, type BlockchainArtifactRegistrationInput, type VitalSignBatchCommunicationFromSearchResponseInput, type CommunicationParticipantRuntimeSearchInput, type ClinicalBundleSearchInput, type ClinicalSectionUpdateInput, type ClinicalSummaryReadResult, type ClinicalSummaryRequestInput, type ClinicalSummaryUpdateInput, type GrantProfessionalAccessInput, type GrantProfessionalAccessResult, type IndividualMemberLifecycleInput, type IndividualMemberLicenseAddInput, type IndividualMemberLicenseInvitationInput, type IndividualMemberLicenseTransitionInput, type LicenseListRuntimeSearchInput, type LicenseOfferRuntimeSearchInput, type LicenseOrderRuntimeSearchInput, type OrganizationEmployeeCreationInput, type OrganizationEmployeeLicenseAddInput, type OrganizationEmployeeLicenseOfferInput, type OrganizationEmployeeLicenseInvitationInput, type OrganizationEmployeeLifecycleInput, type OrganizationEmployeeSearchInput, type ProfessionalAccessRequestInput, type ProfessionalAccessRequestResult, type RevokeProfessionalAccessInput, type RevokeProfessionalAccessResult, type RelatedPersonUpsertInput } from './resource-operations.js';
+import { type CommunicationIngestionInput, type BlockchainArtifactRegistrationInput, type VitalSignBatchCommunicationFromSearchResponseInput, type CommunicationParticipantRuntimeSearchInput, type ClinicalBundleSearchInput, type ClinicalSectionUpdateInput, type ClinicalSummaryReadResult, type ClinicalSummaryRequestInput, type ClinicalSummaryUpdateInput, type GrantProfessionalAccessInput, type GrantProfessionalAccessResult, type DigitalTwinSecondaryUseConsentInput, type DigitalTwinSecondaryUseConsentResult, type DigitalTwinSubjectLinkPurgeInput, type DigitalTwinSubjectLinkPurgeResult, type IndividualMemberLifecycleInput, type IndividualMemberLicenseAddInput, type IndividualMemberLicenseInvitationInput, type IndividualMemberLicenseTransitionInput, type LicenseListRuntimeSearchInput, type LicenseOfferRuntimeSearchInput, type LicenseOrderRuntimeSearchInput, type OrganizationEmployeeCreationInput, type OrganizationEmployeeLicenseAddInput, type OrganizationEmployeeLicenseOfferInput, type OrganizationEmployeeLicenseInvitationInput, type OrganizationEmployeeLifecycleInput, type OrganizationEmployeeSearchInput, type ProfessionalAccessRequestInput, type ProfessionalAccessRequestResult, type RevokeProfessionalAccessInput, type RevokeProfessionalAccessResult, type RelatedPersonUpsertInput } from './resource-operations.js';
 import type { LegalOrganizationOrderInput } from './host-onboarding.js';
 import type { SmartTokenExchangeResult } from './smart-token.js';
 import { type OrganizationEmployeeProvisioningInput, type OrganizationEmployeeProvisioningResult } from './organization-employee-lifecycle.js';
@@ -254,10 +255,23 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * have already been disabled/purged.
      */
     disableTenant(hostCtx: HostRouteContext, input: HostedTenantLifecycleInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
+    /** Re-enables one suspended hosted tenant without changing its legal identity. */
+    enableTenant(hostCtx: HostRouteContext, input: HostedTenantLifecycleInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
     /**
      * Purges one already-disabled hosted tenant through the host registry.
      */
     purgeTenant(hostCtx: HostRouteContext, input: HostedTenantLifecycleInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
+    /** Reads authoritative tenant and descendant lifecycle state from the host registry. */
+    getTenantLifecycleStatus(hostCtx: HostRouteContext, input: HostedTenantLifecycleInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
+    /** Explicitly disables one descendant group; tenant disable itself never cascades. */
+    disableTenantDescendants(hostCtx: HostRouteContext, input: HostedTenantLifecycleInput & {
+        descendantKind: HostedTenantDescendantKind;
+    }, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
+    /** Explicitly purges one descendant group; tenant purge itself never cascades. */
+    purgeTenantDescendants(hostCtx: HostRouteContext, input: HostedTenantLifecycleInput & {
+        descendantKind: HostedTenantDescendantKind;
+    }, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
+    private submitTenantDescendantLifecycle;
     /**
      * Creates an employee or professional entry under an existing organization tenant.
      */
@@ -419,6 +433,13 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * Creates and submits a consent-oriented access grant for a professional actor.
      */
     grantProfessionalAccess(ctx: RouteContext, input: GrantProfessionalAccessInput): Promise<GrantProfessionalAccessResult>;
+    /**
+     * Applies the subject's reversible secondary-use decision and lets GW
+     * rebuild or pause the tenant-private digital-twin projection.
+     */
+    setDigitalTwinSecondaryUseConsent(ctx: RouteContext, input: DigitalTwinSecondaryUseConsentInput): Promise<DigitalTwinSecondaryUseConsentResult>;
+    /** Offboards the subject from this index provider without deleting the anonymous twin. */
+    purgeDigitalTwinSubjectLink(ctx: RouteContext, input: DigitalTwinSubjectLinkPurgeInput): Promise<DigitalTwinSubjectLinkPurgeResult>;
     /**
      * Closes an existing professional consent by setting its period end and
      * resubmitting the updated consent resource.
@@ -439,6 +460,11 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * actor-neutral and is used by portal and telephone profile runtimes.
      */
     activateProfileDeviceWithActivationRequest(input: EmployeeDeviceActivationRequestInput): Promise<EmployeeDeviceActivationResult>;
+    /**
+     * Actor-facade name retained for organization controllers and employees.
+     * The implementation is actor-neutral and shares the profile-device flow.
+     */
+    activateEmployeeDeviceWithActivationRequest(input: EmployeeDeviceActivationRequestInput): Promise<EmployeeDeviceActivationResult>;
     /**
      * Creates or updates a `RelatedPerson` for non-employee family/caregiver
      * roles such as a grandfather, guardian, or external caregiver.
@@ -616,6 +642,8 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
     individualRelatedPersonPurgePollPath(ctx?: RouteContext): string;
     individualConsentR4BatchPath(ctx: RouteContext): string;
     individualConsentR4PollPath(ctx: RouteContext): string;
+    individualResearchSubjectPurgePath(ctx: RouteContext): string;
+    individualResearchSubjectPurgePollPath(ctx: RouteContext): string;
     individualCommunicationBatchPath(ctx: RouteContext, format: string): string;
     individualCommunicationPollPath(ctx: RouteContext, format: string): string;
     individualCommunicationSearchPath(ctx: RouteContext): string;