gdc-sdk-node-ts 2.0.8 → 2.0.10

package/README.md

@@ -208,7 +208,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 +694,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/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;
+}