gdc-sdk-node-ts 2.4.32 → 2.4.34

package/README.md

@@ -113,6 +113,8 @@ If you need the shortest path:
 
 - main onboarding guide:
   [docs/101-SDK_END_TO_END.md](./docs/101-SDK_END_TO_END.md)
+- wallet `context`, stable `runtimeId` and KMS-encrypted seed custody:
+  [docs/101-WALLET_CONTEXT_AND_KEY_CUSTODY.md](./docs/101-WALLET_CONTEXT_AND_KEY_CUSTODY.md)
 - first public actor surfaces:
   `HostOnboardingSdk`, `OrganizationControllerSdk`,
   `IndividualControllerSdk`, `ProfessionalSdk`
@@ -649,7 +651,7 @@ modules below.
   - functions: `createOrganizationEmployeeWithDeps(...)`, `importIpsOrFhirAndUpdateIndexWithDeps(...)`, `upsertRelatedPersonAndPollWithDeps(...)`, `ingestCommunicationAndUpdateIndexWithDeps(...)`, `searchClinicalBundleWithDeps(...)`, `searchLatestIpsWithDeps(...)`, `grantProfessionalAccessWithDeps(...)`, `setDigitalTwinSecondaryUseConsentWithDeps(...)`, `purgeDigitalTwinSubjectLinkWithDeps(...)`
 - [`src/digital-twin.ts`](src/digital-twin.ts)
   - types: `DigitalTwinSearchInput`, `DigitalTwinSelectionInput`, `DigitalTwinResearchTag`, `DigitalTwinMaterializationInput`
-  - functions: `createDigitalTwinSecondaryUseConsentIdentifier()`, `searchDigitalTwinsWithDeps(...)`, `saveDigitalTwinSelectionWithDeps(...)`, `materializeDigitalTwinWithDeps(...)`
+  - functions: `searchDigitalTwinsWithDeps(...)`, `saveDigitalTwinSelectionWithDeps(...)`, `materializeDigitalTwinWithDeps(...)`
 - [`src/orchestration/digital-twin-sdk.ts`](src/orchestration/digital-twin-sdk.ts)
   - class: `DigitalTwinSdk` (`requestSmartToken`, `search`, `saveSelection`, `materialize`)
 - [`src/session.ts`](src/session.ts)

package/dist/digital-twin.d.ts

@@ -3,14 +3,6 @@ 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. */

package/dist/digital-twin.js

@@ -3,16 +3,6 @@ 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());

package/dist/gateway-active-consent-provider.js

@@ -48,9 +48,11 @@ export function extractConsentRules(value) {
             ? record.claims
             : undefined;
         for (const candidate of [record, claims]) {
-            if (!candidate || !looksLikeConsentRule(candidate))
+            if (!candidate)
+                continue;
+            const rule = normalizeConsentRule(candidate);
+            if (!looksLikeConsentRule(rule))
                 continue;
-            const rule = candidate;
             const key = String(rule[ClaimConsent.identifier] || JSON.stringify(rule));
             if (!seenRules.has(key)) {
                 seenRules.add(key);
@@ -62,6 +64,18 @@ export function extractConsentRules(value) {
     visit(value);
     return candidates;
 }
+function normalizeConsentRule(value) {
+    const normalized = { ...value };
+    const context = String(value['@context'] || '').trim();
+    if (context) {
+        const prefix = context.endsWith('.') ? context : `${context}.`;
+        for (const [key, claimValue] of Object.entries(value)) {
+            if (key.startsWith(prefix))
+                normalized[key.slice(prefix.length)] = claimValue;
+        }
+    }
+    return normalized;
+}
 function looksLikeConsentRule(value) {
     return Boolean(String(value[ClaimConsent.subject] || '').trim()
         && String(value[ClaimConsent.actorIdentifier] || '').trim()

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

@@ -76,10 +76,12 @@ export declare class NodeManagedWallet implements IWallet {
      * 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.
+     * 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.
      */
     initializeCommunicationJsonWebKeySet(context: WalletExecutionContext, options?: NodeCommunicationWalletInitialization): Promise<JwkSet>;
     /**

package/dist/node-managed-wallet.js

@@ -143,10 +143,12 @@ export class NodeManagedWallet {
      * 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.
+     * 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.
      */
     async initializeCommunicationJsonWebKeySet(context, options = {}) {
         if (!context.runtime?.runtimeId) {

package/dist/orchestration/individual-controller-sdk.d.ts

@@ -1,4 +1,3 @@
-import { type ConsentRule } from 'gdc-common-utils-ts/models/consent-rule';
 import { type IndividualControllerCredentialInput, type IndividualControllerVpPayloadInput, type IndividualSubjectCredentialInput } from 'gdc-common-utils-ts';
 import { type NodeRuntimeClient, type PollOptions, type SubmitAndPollResult, type SubmitPayload } from './client-port.js';
 import type { FamilyOrganizationSummary } from 'gdc-common-utils-ts/utils/family-organization-summary';
@@ -129,8 +128,8 @@ export declare class IndividualControllerSdk {
      * Enables or disables the subject's secondary-use digital-twin projection.
      * This is the canonical patient-side operation; application code must not
      * publish a canonical Composition directly into the research index. The
-     * caller reuses the server-owned identifier created once with
-     * `createDigitalTwinSecondaryUseConsentIdentifier()` during index enrollment.
+     * caller supplies only the portal/software/study reference. GW owns and
+     * reuses the underlying FHIR Consent identifier.
      */
     setDigitalTwinSecondaryUseConsent(ctx: RouteContext, input: DigitalTwinSecondaryUseConsentInput): Promise<DigitalTwinSecondaryUseConsentResult>;
     /**
@@ -139,15 +138,14 @@ export declare class IndividualControllerSdk {
      * data already shared for research.
      */
     purgeDigitalTwinSubjectLink(ctx: RouteContext, input: DigitalTwinSubjectLinkPurgeInput): Promise<DigitalTwinSubjectLinkPurgeResult>;
-    /** Returns whether the subject currently permits projection by its index provider. */
+    /** Returns the current decision for one portal, software or research study. */
     getDigitalTwinSecondaryUseConsentStatus(ctx: RouteContext, input: Readonly<{
         subjectDid: string;
         indexProviderOrganizationDid: string;
-        consentIdentifier: string;
+        researchUseReference: string;
     }>): Promise<Readonly<{
         exists: boolean;
         enabled: boolean;
-        consent?: ConsentRule;
     }>>;
     /**
      * Searches indexed clinical bundles for the current subject/controller context.

package/dist/orchestration/individual-controller-sdk.js

@@ -192,8 +192,8 @@ export class IndividualControllerSdk {
      * Enables or disables the subject's secondary-use digital-twin projection.
      * This is the canonical patient-side operation; application code must not
      * publish a canonical Composition directly into the research index. The
-     * caller reuses the server-owned identifier created once with
-     * `createDigitalTwinSecondaryUseConsentIdentifier()` during index enrollment.
+     * caller supplies only the portal/software/study reference. GW owns and
+     * reuses the underlying FHIR Consent identifier.
      */
     setDigitalTwinSecondaryUseConsent(ctx, input) {
         assertFacadeCapability(this.capabilities, ActorCapabilities.IndividualGenerateDigitalTwin, ActorKinds.IndividualController, 'setDigitalTwinSecondaryUseConsent');
@@ -208,26 +208,27 @@ export class IndividualControllerSdk {
         assertFacadeCapability(this.capabilities, ActorCapabilities.IndividualGenerateDigitalTwin, ActorKinds.IndividualController, 'purgeDigitalTwinSubjectLink');
         return requireClientMethod(this.client, 'purgeDigitalTwinSubjectLink')(ctx, input);
     }
-    /** Returns whether the subject currently permits projection by its index provider. */
+    /** Returns the current decision for one portal, software or research study. */
     async getDigitalTwinSecondaryUseConsentStatus(ctx, input) {
         assertFacadeCapability(this.capabilities, ActorCapabilities.IndividualGenerateDigitalTwin, ActorKinds.IndividualController, 'getDigitalTwinSecondaryUseConsentStatus');
-        const activeConsents = await new GatewayActiveConsentProvider(this.client, ctx)
+        const consents = await new GatewayActiveConsentProvider(this.client, ctx)
             .getActiveConsentsForSubject(input.subjectDid);
-        const consentIdentifier = String(input.consentIdentifier || '').trim();
-        if (!consentIdentifier)
-            throw new Error('consentIdentifier is required to distinguish the portal rule from study consents.');
+        const researchUseReference = String(input.researchUseReference || '').trim();
+        if (!researchUseReference)
+            throw new Error('researchUseReference is required to identify the portal, software or study consent.');
         const indexProviderOrganizationDid = String(input.indexProviderOrganizationDid || '').trim();
         if (!indexProviderOrganizationDid)
             throw new Error('indexProviderOrganizationDid is required.');
-        const consent = activeConsents.find((rule) => {
+        const consent = consents.find((rule) => {
+            const claims = rule;
             const actions = String(rule[ClaimConsent.action] || '').split(',').map((value) => value.trim());
-            return String(rule[ClaimConsent.identifier] || '').trim() === consentIdentifier
+            return String(claims[ClaimConsent.sourceReference] || '').trim() === researchUseReference
                 && String(rule[ClaimConsent.actorIdentifier] || '').trim() === indexProviderOrganizationDid
                 && String(rule[ClaimConsent.purpose] || '').trim().toUpperCase() === String(HealthcareConsentPurposes.Research).toUpperCase()
                 && actions.includes(ServiceCapability.DigitalTwinReader);
         });
         return consent
-            ? { exists: true, enabled: String(consent[ClaimConsent.decision] || '').trim().toLowerCase() === 'permit', consent }
+            ? { exists: true, enabled: String(consent[ClaimConsent.decision] || '').trim().toLowerCase() === 'permit' }
             : { exists: false, enabled: false };
     }
     /**

package/dist/resource-operations.d.ts

@@ -508,11 +508,11 @@ export type DigitalTwinSecondaryUseConsentInput = {
     indexProviderOrganizationDid: string;
     decision: 'permit' | 'deny';
     /**
-     * Server-owned FHIR Consent identifier. Create it once with
-     * `createDigitalTwinSecondaryUseConsentIdentifier()` in the index-enrollment
-     * transaction, persist it there and never accept it from the browser.
+     * Stable URL or URI identifying the portal, software or research study whose
+     * permission is being changed. GW uses it as `Consent.source-reference` to
+     * find or create the rule; callers never manage `Consent.identifier`.
      */
-    consentIdentifier: string;
+    researchUseReference: string;
     consentDate?: string;
     dataType?: string;
     pollOptions?: {

package/dist/resource-operations.js

@@ -811,8 +811,9 @@ export async function grantProfessionalAccessWithDeps(routeCtx, input, deps) {
  * tenant-private subject alias.
  */
 export async function setDigitalTwinSecondaryUseConsentWithDeps(routeCtx, input, deps) {
-    if (!String(input.consentIdentifier || '').trim()) {
-        throw new Error('consentIdentifier is required for idempotent digital-twin consent updates.');
+    const researchUseReference = String(input.researchUseReference || '').trim();
+    if (!researchUseReference) {
+        throw new Error('researchUseReference is required to identify the portal, software or study consent.');
     }
     const indexProviderOrganizationDid = String(input.indexProviderOrganizationDid || '').trim();
     if (!indexProviderOrganizationDid) {
@@ -827,7 +828,9 @@ export async function setDigitalTwinSecondaryUseConsentWithDeps(routeCtx, input,
         if (context) {
             delete claims[`${context}.${ClaimConsent.attachmentContentType}`];
             delete claims[`${context}.${ClaimConsent.attachmentData}`];
+            delete claims[`${context}.${ClaimConsent.identifier}`];
         }
+        delete claims[ClaimConsent.identifier];
         const assigned = assignCidToClaimsId(claims);
         return { ...built, consentClaims: assigned.claims, claimsCid: assigned.cid };
     };
@@ -838,7 +841,7 @@ export async function setDigitalTwinSecondaryUseConsentWithDeps(routeCtx, input,
         purpose: HealthcareConsentPurposes.Research,
         actions: [ServiceCapability.DigitalTwinReader],
         decision: input.decision,
-        consentIdentifier: input.consentIdentifier,
+        sourceReference: researchUseReference,
         consentDate: input.consentDate,
         dataType: input.dataType,
         pollOptions: input.pollOptions,

package/package.json

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