gdc-sdk-node-ts 2.0.9 → 2.0.11

package/README.md

@@ -63,50 +63,42 @@ If you are integrating this package for the first time, open these in order:
 1. [gdc-sdk-core-ts/docs/101-SDK_PACKAGE_BOUNDARIES.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/101-SDK_PACKAGE_BOUNDARIES.md)
    Why `core`, `node`, and `front` are separate packages, what belongs in each
    one, and why actor-scoped facades must stay aligned across runtimes.
-1. [tests/101-live-full-cycle-bff-runtime.e2e.test.mjs](./tests/101-live-full-cycle-bff-runtime.e2e.test.mjs)
-   Canonical live backend/BFF walkthrough on a fresh local GW lifecycle:
-   host/tenant activation, employee provisioning, individual bootstrap,
-   consent grant, professional SMART token, clinical read, and final cleanup.
-1. [tests/101-backend-profile-runtime.test.mjs](./tests/101-backend-profile-runtime.test.mjs)
-   Minimal backend-generic walkthrough for loading one actor profile,
-   registering one trusted device/runtime context, connecting to one subject
-   index, reading one subject index composition, and then materializing the
-   `IndividualController` facade from the loaded backend session.
-   That walkthrough now uses the concrete direct backend runtime over the
-   injected `RuntimeClient`, not only one abstract adapter mock, and now also
-   demonstrates in-memory `JobManager` usage plus `closeProfile(...)`.
-1. [tests/101-individual-controller-backend-runtime.test.mjs](./tests/101-individual-controller-backend-runtime.test.mjs)
-   First pragmatic backend wrapper over the generic profile runtime for the
-   current individual-controller CORE baseline:
-   load profile, start registration, confirm order, and search the clinical
-   index.
-1. [docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md](./docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md)
-   Reconciles the old consumer flow with the current CORE registration baseline
-   and separates the stable registration base from later product extensions.
 1. [docs/101-SDK_END_TO_END.md](./docs/101-SDK_END_TO_END.md)
   Ordered onboarding guide with end-to-end journeys, copy/paste snippets, and
   the recommended reading path for new backend integrators.
 2. [docs/101-SDK_INTEGRATION.md](./docs/101-SDK_INTEGRATION.md)
-   Real backend setup, imports, `initializeCommunicationIdentity(...)`,
-   `new NodeHttpClient(...)`, route context, facade selection, and live method
-   usage.
-3. [docs/101-LIVE_GW_LOCAL.md](./docs/101-LIVE_GW_LOCAL.md)
+   Real backend setup plus the public runtime entrypoints:
+   `HostOnboardingSdk`, `OrganizationControllerSdk`,
+   `IndividualControllerSdk`, `ProfessionalSdk`, and route-context usage.
+3. [tests/101-live-full-cycle-bff-runtime.e2e.test.mjs](./tests/101-live-full-cycle-bff-runtime.e2e.test.mjs)
+   Canonical live backend/BFF walkthrough on a fresh local GW lifecycle:
+   host/tenant activation, employee provisioning, individual bootstrap,
+   consent grant, professional SMART token, clinical read, and final cleanup.
+4. [docs/101-LIVE_GW_LOCAL.md](./docs/101-LIVE_GW_LOCAL.md)
    Exact TTY/local/Docker commands for running the SDK against a real local GW
    CORE, including tenant bootstrap and employee-seat setup.
-4. [docs/101-DISCOVERY.md](./docs/101-DISCOVERY.md)
+5. [docs/101-DISCOVERY.md](./docs/101-DISCOVERY.md)
    Node/BFF dataspace discovery, hosting-operator resolution, provider
    resolution, and the correct integration boundary for fallback and cache.
-5. [gdc-sdk-core-ts/docs/101-SDK_FLOWS.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/101-SDK_FLOWS.md)
+6. [gdc-sdk-core-ts/docs/101-SDK_FLOWS.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/101-SDK_FLOWS.md)
    Actor split and business-flow map across organization, individual,
    permissions, invitation, import, and SMART flows.
-6. [gwtemplate-node-ts/docs/PORTAL_API_TO_GW_CORE.md](https://github.com/Global-DataCare/gwtemplate-node-ts/blob/main/docs/PORTAL_API_TO_GW_CORE.md)
+7. [gwtemplate-node-ts/docs/PORTAL_API_TO_GW_CORE.md](https://github.com/Global-DataCare/gwtemplate-node-ts/blob/main/docs/PORTAL_API_TO_GW_CORE.md)
    Canonical portal/BFF functional map over GW CORE, including the domain
    split between `employees`, `related persons`, `members`, and `consents`.
-7. [gdc-common-utils-ts/src/examples/](https://github.com/Global-DataCare/gdc-common-utils-ts/tree/main/src/examples)
+8. [gdc-common-utils-ts/src/examples/](https://github.com/Global-DataCare/gdc-common-utils-ts/tree/main/src/examples)
    Shared payload values used by the docs and tests.
-8. [gdc-common-utils-ts/docs/101-LIFECYCLE.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/101-LIFECYCLE.md)
+9. [gdc-common-utils-ts/docs/101-LIFECYCLE.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/101-LIFECYCLE.md)
    Canonical `enable/disable/delete` semantics and copy/paste placeholders.
-9. [docs/NEXT_STEPS.md](./docs/NEXT_STEPS.md)
+10. [tests/101-backend-profile-runtime.test.mjs](./tests/101-backend-profile-runtime.test.mjs)
+   Technical runtime slice for profile/device/session orchestration internals.
+   Read this after the public actor SDK guides, not before them.
+11. [tests/101-individual-controller-backend-runtime.test.mjs](./tests/101-individual-controller-backend-runtime.test.mjs)
+   Technical wrapper slice around the generic profile runtime. This is not the
+   main onboarding path for new integrators.
+12. [docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md](./docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md)
+   Historical reconciliation note for the current CORE registration baseline.
+13. [docs/NEXT_STEPS.md](./docs/NEXT_STEPS.md)
    Follow-up scope after GW CORE live validation, including the future user job
    manager boundary.
 
@@ -114,6 +106,9 @@ If you need the shortest path:
 
 - main onboarding guide:
   [docs/101-SDK_END_TO_END.md](./docs/101-SDK_END_TO_END.md)
+- first public actor surfaces:
+  `HostOnboardingSdk`, `OrganizationControllerSdk`,
+  `IndividualControllerSdk`, `ProfessionalSdk`
 - GW CORE app identity:
   `appId` mandatory, `appVersion` optional with default `v1.0`
 - backend technical identity:
@@ -130,7 +125,7 @@ Current live teaching target:
 
 - the main executable tutorial for integrators is now:
   [tests/101-live-full-cycle-bff-runtime.e2e.test.mjs](tests/101-live-full-cycle-bff-runtime.e2e.test.mjs)
-- the standalone actor-profile suites still exist as focused technical slices:
+- the standalone actor-profile suites still exist only as focused technical slices:
   - [tests/live-profile-runtime-individual.e2e.test.mjs](tests/live-profile-runtime-individual.e2e.test.mjs)
   - [tests/live-profile-runtime-professional.e2e.test.mjs](tests/live-profile-runtime-professional.e2e.test.mjs)
 - the larger runtime suite remains the regression-oriented environment proof:
@@ -208,7 +203,7 @@ Current live `101` flow covered by the test suite:
 Run the main live `101`:
 
 ```bash
-npm run test:e2e:101:live-full-cycle
+npm run test:e2e:live-full-cycle
 ```
 
 What is still not fully covered as one single root lifecycle:
@@ -694,6 +689,9 @@ Existing-tenant recovery/reverification:
   or directly `_exchange -> _dcr`
 - for a reproducible local/staging runtime check, use:
   `npm run test:e2e:live-gw:issue-recovery`
+- for the deterministic controller-lifecycle contract that also proves
+  post-registration seat preservation and final tenant teardown, use:
+  [docs/101-ORGANIZATION_CONTROLLER_LIFECYCLE.md](docs/101-ORGANIZATION_CONTROLLER_LIFECYCLE.md)
 
 Rules:
 

package/dist/UserProfileIndexStore.d.ts

@@ -0,0 +1,47 @@
+import type { IVaultRepository, UserProfileLookupKey } from 'gdc-sdk-core-ts';
+import type { UserProfileIndexRecord } from './UserProfileIndexStore.types.js';
+export type { UserProfileIndexRecord } from './UserProfileIndexStore.types.js';
+/**
+ * Node/server persistence adapter for hashed local user-profile indexes.
+ *
+ * Responsibilities:
+ * - store ordered local profile indexes
+ * - list stored index documents
+ * - resolve one index by hashed lookup key before PIN unlock
+ *
+ * Non-responsibilities:
+ * - hashing raw email/phone input
+ * - unlocking profiles with PIN
+ * - storing seeds or decrypted private key material
+ */
+export declare class UserProfileIndexStore {
+    private readonly vault;
+    constructor(vault: IVaultRepository);
+    /**
+     * Initializes the underlying storage adapter.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Creates or replaces one stored user-profile index record.
+     */
+    upsert(record: UserProfileIndexRecord): Promise<UserProfileIndexRecord>;
+    /**
+     * Returns every stored user-profile index record.
+     */
+    list(): Promise<UserProfileIndexRecord[]>;
+    /**
+     * Returns one stored index by storage id.
+     */
+    get(id: string): Promise<UserProfileIndexRecord | undefined>;
+    /**
+     * Resolves the first stored index that contains the given hashed lookup key.
+     *
+     * This intentionally compares hashed lookup tokens only. Raw phone/email
+     * values are outside this store contract.
+     */
+    findByLookup(lookup: UserProfileLookupKey): Promise<UserProfileIndexRecord | undefined>;
+    /**
+     * Deletes one stored index by storage id.
+     */
+    remove(id: string): Promise<boolean>;
+}

package/dist/UserProfileIndexStore.js

@@ -0,0 +1,66 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+const COLLECTION = 'user-profile-index';
+/**
+ * Node/server persistence adapter for hashed local user-profile indexes.
+ *
+ * Responsibilities:
+ * - store ordered local profile indexes
+ * - list stored index documents
+ * - resolve one index by hashed lookup key before PIN unlock
+ *
+ * Non-responsibilities:
+ * - hashing raw email/phone input
+ * - unlocking profiles with PIN
+ * - storing seeds or decrypted private key material
+ */
+export class UserProfileIndexStore {
+    constructor(vault) {
+        this.vault = vault;
+    }
+    /**
+     * Initializes the underlying storage adapter.
+     */
+    async initialize() {
+        await this.vault.initialize();
+    }
+    /**
+     * Creates or replaces one stored user-profile index record.
+     */
+    async upsert(record) {
+        await this.vault.put(COLLECTION, record);
+        return record;
+    }
+    /**
+     * Returns every stored user-profile index record.
+     */
+    async list() {
+        return this.vault.query(COLLECTION, {});
+    }
+    /**
+     * Returns one stored index by storage id.
+     */
+    async get(id) {
+        return this.vault.get(COLLECTION, id);
+    }
+    /**
+     * Resolves the first stored index that contains the given hashed lookup key.
+     *
+     * This intentionally compares hashed lookup tokens only. Raw phone/email
+     * values are outside this store contract.
+     */
+    async findByLookup(lookup) {
+        const records = await this.list();
+        return records.find((record) => record.lookup.some((item) => lookupEquals(item, lookup)));
+    }
+    /**
+     * Deletes one stored index by storage id.
+     */
+    async remove(id) {
+        return this.vault.delete(COLLECTION, id);
+    }
+}
+function lookupEquals(left, right) {
+    return left.kind === right.kind
+        && left.algorithm === right.algorithm
+        && left.value === right.value;
+}

package/dist/UserProfileIndexStore.types.d.ts

@@ -0,0 +1,16 @@
+import type { UserProfileIndex } from 'gdc-sdk-core-ts';
+/**
+ * Persisted local user-profile index document for node/server runtimes.
+ *
+ * The shared `UserProfileIndex` contract from `gdc-sdk-core-ts` is
+ * runtime-neutral and intentionally omits any storage identifier. Node
+ * runtimes need a stable document id so one logical index record can be
+ * replaced atomically in a concrete vault adapter such as Firestore, Redis,
+ * SQLite, or an in-memory test vault.
+ */
+export interface UserProfileIndexRecord extends UserProfileIndex {
+    /**
+     * Stable storage identifier for one local profile-index document.
+     */
+    id: string;
+}

package/dist/UserProfileIndexStore.types.js

@@ -0,0 +1,2 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+export {};

package/dist/index.d.ts

@@ -19,6 +19,10 @@ export * from './order-offer-summary.js';
 export * from './organization-license-order.js';
 export * from './resource-operations.js';
 export * from './profile-workspace.js';
+export * from './UserProfileIndexStore.js';
+export * from './wallet-backed-job-manager.js';
+export * from './node-crypto-helper.js';
+export * from './node-managed-wallet.js';
 export * from './constants/lifecycle.js';
 export * from './consent-claim-helpers.js';
 export * from './session.js';

package/dist/index.js

@@ -20,6 +20,10 @@ export * from './order-offer-summary.js';
 export * from './organization-license-order.js';
 export * from './resource-operations.js';
 export * from './profile-workspace.js';
+export * from './UserProfileIndexStore.js';
+export * from './wallet-backed-job-manager.js';
+export * from './node-crypto-helper.js';
+export * from './node-managed-wallet.js';
 export * from './constants/lifecycle.js';
 export * from './consent-claim-helpers.js';
 export * from './session.js';

package/dist/individual-onboarding.js

@@ -1,6 +1,13 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { resolvePollOptionsFromSeconds } from './poll-options.js';
 export async function confirmIndividualOrganizationOrderWithDeps(deps) {
+    /**
+     * Programming rule:
+     * - `offerId` here must come from the commercial individual/family bootstrap
+     *   response
+     * - this helper must not be used for embedded legacy individual registration
+     *   responses that do not mint an Offer
+     */
     const offerId = String(deps.input.offerId || '').trim();
     if (!offerId) {
         throw new Error('confirmIndividualOrganizationOrder requires offerId.');

package/dist/individual-start.js

@@ -64,6 +64,15 @@ export async function startIndividualOrganizationWithDeps(deps) {
     });
     const registration = await deps.submitAndPoll(deps.individualFamilyOrganizationBatchPath(deps.routeCtx), deps.individualFamilyOrganizationPollPath(deps.routeCtx), registrationPayload, pollOptions);
     deps.assertFirstDidcommEntrySuccess?.(registration, 'startIndividualOrganization.registration');
+    /**
+     * Commercial contract for this SDK path:
+     * - this helper targets the family/individual commercial bootstrap flow
+     * - the registration response must expose one Offer identifier
+     * - the caller must later confirm that Offer through `Order/_batch`
+     *
+     * This helper must therefore fail fast if the underlying GW route behaves
+     * like the embedded non-commercial individual registration flow instead.
+     */
     const offerId = deps.getOfferIdFromResponse(registration);
     if (!offerId) {
         throw new Error('startIndividualOrganization failed: missing offerId in registration response.');

package/dist/node-crypto-helper.d.ts

@@ -0,0 +1,19 @@
+import type { ICryptoHelper } from 'gdc-common-utils-ts/interfaces/ICryptoHelper';
+/**
+ * Node.js implementation of the low-level crypto helper contract used by
+ * `CryptographyService` and managed wallet adapters.
+ */
+export declare class NodeCryptoHelper implements ICryptoHelper {
+    /**
+     * Returns cryptographically secure random bytes from the Node runtime.
+     */
+    getRandomBytes(byteCount: number): Promise<Uint8Array>;
+    /**
+     * Computes a digest for the provided string using one Node-supported hash algorithm.
+     */
+    digestString(data: string, algorithm: string): Promise<string>;
+    /**
+     * Returns a cryptographically secure UUID v4 from the Node runtime.
+     */
+    randomUUID(): string;
+}

package/dist/node-crypto-helper.js

@@ -0,0 +1,27 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { createHash, randomBytes, randomUUID } from 'crypto';
+/**
+ * Node.js implementation of the low-level crypto helper contract used by
+ * `CryptographyService` and managed wallet adapters.
+ */
+export class NodeCryptoHelper {
+    /**
+     * Returns cryptographically secure random bytes from the Node runtime.
+     */
+    async getRandomBytes(byteCount) {
+        return randomBytes(byteCount);
+    }
+    /**
+     * Computes a digest for the provided string using one Node-supported hash algorithm.
+     */
+    async digestString(data, algorithm) {
+        const normalized = String(algorithm).replace(/-/g, '').toLowerCase();
+        return createHash(normalized).update(data, 'utf8').digest('hex');
+    }
+    /**
+     * Returns a cryptographically secure UUID v4 from the Node runtime.
+     */
+    randomUUID() {
+        return randomUUID();
+    }
+}

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

@@ -0,0 +1,154 @@
+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 { JWK, JwkSet } from 'gdc-common-utils-ts/models/jwk';
+export type NodeManagedWalletPolicy = {
+    defaults: Partial<Record<WalletKeyPurpose, WalletAlgorithm>>;
+};
+export type NodeManagedWalletOptions = {
+    cryptoHelper?: ICryptoHelper;
+    cryptography?: CryptographyService;
+    resolveRecipientJwk?: (recipientDid: string) => Promise<JWK>;
+    policy?: Partial<NodeManagedWalletPolicy>;
+};
+/**
+ * Node-focused managed wallet implementation for BFF, portal, and backend flows.
+ *
+ * This adapter keeps actor/profile keys separate from runtime/channel keys and
+ * exposes one shared `IWallet` contract suitable for:
+ * - user/domain signing
+ * - OpenID/JWT signing
+ * - DIDComm-style transport wrapping
+ * - confidential document protection
+ */
+export declare class NodeManagedWallet implements IWallet {
+    private readonly cryptoHelper;
+    private readonly cryptography;
+    private readonly resolveRecipientJwk?;
+    private readonly policy;
+    private readonly owners;
+    /**
+     * Creates one managed wallet backed by `CryptographyService` and Node crypto.
+     */
+    constructor(options?: NodeManagedWalletOptions);
+    /**
+     * Legacy provisioning shape kept for app compatibility.
+     *
+     * It provisions one profile-owned signing key, one runtime communication
+     * signing key, and one runtime communication encryption key while returning
+     * the signing/encryption public keys expected by older app-facing flows.
+     */
+    provisionKeys(entityId: string): Promise<JwkSet>;
+    /**
+     * Rich provisioning shape for actor/profile keys and runtime/channel keys.
+     */
+    provisionManagedKeys(context: WalletExecutionContext, request: WalletProvisionRequest): Promise<JwkSet>;
+    /**
+     * Returns the currently available public JWKs for the selected context and filter.
+     */
+    getPublicJwks(context?: WalletExecutionContext, filter?: WalletKeySelection): Promise<WalletKeyDescriptor[]>;
+    /**
+     * Computes a digest of a string using the configured runtime helper.
+     */
+    digest(data: string, algorithm: string): Promise<string>;
+    /**
+     * Protects one confidential document using one owner-specific symmetric storage key.
+     */
+    protectConfidentialData(doc: any, entityId: string): Promise<any>;
+    /**
+     * Protects one confidential document using the richer execution-context model.
+     */
+    protectManagedConfidentialData(doc: any, context: WalletExecutionContext, _options?: {
+        key?: WalletKeySelection;
+    }): Promise<any>;
+    /**
+     * Decrypts one confidential document using the legacy entity id shape.
+     */
+    unprotectConfidentialData(doc: any, entityId: string): Promise<any>;
+    /**
+     * Decrypts one confidential document using the richer execution-context model.
+     */
+    unprotectManagedConfidentialData(doc: any, context: WalletExecutionContext, _options?: {
+        key?: WalletKeySelection;
+    }): Promise<any>;
+    /**
+     * Signs arbitrary bytes or one UTF-8 string using the selected managed key.
+     */
+    sign(payload: Uint8Array | string, context: WalletExecutionContext, options: WalletKeySelection): Promise<string>;
+    /**
+     * Verifies one signature against the provided public JWK.
+     */
+    verify(payload: Uint8Array | string, signature: string, jwk: JWK, options?: {
+        alg?: WalletAlgorithm;
+    }): Promise<boolean>;
+    /**
+     * Encrypts one payload for the provided recipient public JWK.
+     */
+    encrypt(plaintext: Uint8Array | string, recipientJwk: JWK, options?: {
+        context?: WalletExecutionContext;
+        key?: WalletKeySelection;
+        contentType?: string;
+    }): Promise<string>;
+    /**
+     * Decrypts one ciphertext using one selected local encryption key.
+     */
+    decrypt(ciphertext: string, context: WalletExecutionContext, options?: {
+        key?: WalletKeySelection;
+    }): Promise<Uint8Array>;
+    /**
+     * Builds one compact JWS using one managed signing key.
+     */
+    signCompactJws(context: WalletExecutionContext, request: WalletCompactJwsRequest): Promise<string>;
+    /**
+     * Builds one detached compact JWS using one managed signing key.
+     */
+    signDetachedJws(context: WalletExecutionContext, request: WalletDetachedJwsRequest): Promise<string>;
+    /**
+     * Builds one compact JWE using one selected local ML-KEM key and one recipient public JWK.
+     */
+    buildCompactJwe(context: WalletExecutionContext, request: WalletCompactJweRequest): Promise<string>;
+    /**
+     * Decrypts one compact JWE using one selected local ML-KEM key.
+     */
+    decryptCompactJwe(jwe: string, context: WalletExecutionContext, options: {
+        key: WalletKeySelection;
+    }): Promise<Uint8Array>;
+    /**
+     * Legacy pack shape retained for app compatibility.
+     */
+    packForRecipient(content: any, recipientDid: string): Promise<string>;
+    /**
+     * Packs one payload into a transport envelope signed and encrypted by the runtime.
+     */
+    packForRecipientWithContext(content: any, recipientDidOrJwk: string | JWK, options: WalletPackOptions): Promise<string>;
+    /**
+     * Legacy unpack shape retained for app compatibility.
+     */
+    unpack(packedMessage: string): Promise<{
+        content: any;
+        meta: any;
+    }>;
+    /**
+     * Unpacks one transport envelope and returns the decoded business payload plus JOSE metadata.
+     */
+    unpackWithContext(packedMessage: string, options: WalletUnpackOptions): Promise<{
+        content: any;
+        meta: any;
+    }>;
+    private getOrCreateOwnerState;
+    private tryGetOwnerState;
+    private resolveOwnerId;
+    private resolveStorageOwnerId;
+    private createManagedKey;
+    private createStorageKey;
+    private requireStorageKey;
+    private requireManagedKey;
+    private inferRelevantScopes;
+    private matchesSelection;
+    private resolveAlgorithmForPurpose;
+    private deriveSignerSeed;
+    private deriveSeedBytes;
+    private deriveDeterministicBlock;
+    private resolveNodeDigestForAlgorithm;
+    private resolveRecipientPublicJwk;
+}