dataspace-client-sdk-node 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.js';
 export * from './builders.js';
+export * from './vp-token.js';
 export * from './client.js';
 export * from './sdk/dataspace-wallet-sdk-node/index.js';

package/dist/index.js

@@ -4,5 +4,6 @@
 // See subjectVaultPhoneResolution.test.ts for context and migration plan.
 export * from './types.js';
 export * from './builders.js';
+export * from './vp-token.js';
 export * from './client.js';
 export * from './sdk/dataspace-wallet-sdk-node/index.js';

package/dist/types.d.ts

@@ -158,6 +158,23 @@ export type FamilyOrganizationSummary = {
     missingFields?: string[];
     updatedAt?: string;
 };
+export type OfferPreview = {
+    offerId?: string;
+    amount?: string;
+    currency?: string;
+    seats?: number;
+    planName?: string;
+    sku?: string;
+    paymentMethod?: string;
+    checkoutUrl?: string;
+};
+export type OfferInfo = OfferPreview;
+export type EndpointSelector = {
+    section: string;
+    format: string;
+    resourceType: string;
+    action: string;
+};
 /**
  * Input for organization activation in GW using ICA-derived proof material.
  *
@@ -166,11 +183,40 @@ export type FamilyOrganizationSummary = {
  */
 export type GatewayOrganizationActivationInput = {
     vpToken: string;
+    /** Generic requested seats/members for initial offer sizing. Defaults to 2. */
+    numberOfMembers?: number;
+    organizationVc?: string;
+    legalRepresentativeVc?: string;
+    regulatoryEvidence?: Record<string, unknown>;
+    /** @deprecated Prefer `numberOfMembers` and explicit input fields. */
+    additionalClaims?: Record<string, unknown>;
+};
+export type GatewayOrganizationActivationSimpleInput = {
+    jurisdiction?: string;
+    sector?: string;
+    vpToken: string;
+    serviceProviderDidWeb?: string;
+    serviceProviderUrl?: string;
+    controllerEmail?: string;
+    controllerTelephone?: string;
+    controllerRole: string;
+    numberOfMembers?: number;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
     organizationVc?: string;
     legalRepresentativeVc?: string;
     regulatoryEvidence?: Record<string, unknown>;
     additionalClaims?: Record<string, unknown>;
 };
+export type LegalOrganizationOrderSimpleInput = {
+    jurisdiction?: string;
+    sector?: string;
+    offerId: string;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+    dataType?: string;
+    additionalClaims?: Record<string, unknown>;
+};
 /**
  * Input for device activation based on activation code exchange + DCR.
  */
@@ -180,6 +226,16 @@ export type EmployeeDeviceActivationInput = {
     dcrPayload: Record<string, unknown>;
     pollOptions?: PollOptions;
 };
+export type EmployeeDeviceActivationSimpleInput = {
+    tenantId?: string;
+    jurisdiction?: string;
+    sector?: string;
+    activationCode: string;
+    idToken: string;
+    dcrPayload: Record<string, unknown>;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+};
 /**
  * Result of device activation flow.
  *
@@ -217,6 +273,36 @@ export type SubjectOrganizationBootstrapResult = {
     registration: SubmitAndPollResult;
     confirmation?: SubmitAndPollResult;
 };
+export type IndividualOrganizationBootstrapSimpleInput = {
+    tenantId?: string;
+    jurisdiction?: string;
+    sector?: string;
+    alternateName: string;
+    controllerEmail?: string;
+    controllerTelephone?: string;
+    controllerRole?: string;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+    additionalClaims?: Record<string, unknown>;
+};
+export type IndividualOrganizationBootstrapSimpleResult = {
+    registration: SubmitAndPollResult;
+    offerId: string;
+    confirmation: SubmitAndPollResult;
+};
+export type IndividualOrganizationStartSimpleResult = {
+    registration: SubmitAndPollResult;
+    offerId: string;
+    offerPreview: OfferPreview;
+};
+export type IndividualOrganizationConfirmOrderSimpleInput = {
+    tenantId?: string;
+    jurisdiction?: string;
+    sector?: string;
+    offerId: string;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+};
 /**
  * Input for UC 5.5 IPS/FHIR import and index update.
  */
@@ -367,6 +453,8 @@ export type ClientOptions = {
     bearerToken?: string;
     defaultHeaders?: Record<string, string>;
     wallet?: WalletProvider;
+    /** Optional default tenant context so calls can omit ctx repeatedly. */
+    ctx?: RouteContext;
 };
 /**
  * Options for identity-exchange.v1 backend PKCE + token exchange flow.
@@ -390,6 +478,8 @@ export type BackendPkceAuthOptions = {
     /** Requested scopes for the SMART bearer token. */
     scopes: string[];
     /** Cache key for the resulting bearer token. Defaults to `pkce:<apiKey prefix>`. */
+    tokenCacheKey?: string;
+    /** @deprecated Use `tokenCacheKey`. */
     endpointId?: string;
     /** PKCE code verifier. Auto-generated with randomUUID if not provided. */
     codeVerifier?: string;
@@ -399,6 +489,8 @@ export type BackendPkceAuthOptions = {
 export type BackendPkceAuthResult = {
     /** `fetched`: new token obtained. `cached`: valid token already in cache. `failed`: flow error. */
     status: 'fetched' | 'cached' | 'failed';
+    tokenCacheKey: string;
+    /** @deprecated Use `tokenCacheKey`. */
     endpointId: string;
     accessToken: string;
     tokenType: string;
@@ -409,6 +501,8 @@ export type BackendPkceAuthResult = {
 export type BackendSmartAuthOptions = {
     clientId: string;
     scopes: string[];
+    tokenCacheKey?: string;
+    /** @deprecated Use `tokenCacheKey`. */
     endpointId?: string;
     tokenUrl?: string;
     tokenPath?: string;
@@ -421,6 +515,8 @@ export type BackendSmartAuthOptions = {
 export type BackendSmartAuthResult = {
     status: 'fetched' | 'cached' | 'failed';
     profile: 'smart-backend.v1';
+    tokenCacheKey: string;
+    /** @deprecated Use `tokenCacheKey`. */
     endpointId: string;
     accessToken?: string;
     tokenType?: string;
@@ -430,11 +526,26 @@ export type BackendSmartAuthResult = {
     response?: unknown;
 };
 export type SmartTokenExchangeInput = {
-    endpointId: string;
+    tokenCacheKey: string;
+    /** @deprecated Use `tokenCacheKey`. */
+    endpointId?: string;
     scopes: string[];
     exchangePayload: Record<string, unknown>;
     path?: string;
 };
+export type SmartTokenRequestSimpleInput = {
+    tenantId?: string;
+    jurisdiction?: string;
+    sector?: string;
+    idToken: string;
+    scopes: string[];
+    tokenCacheKey?: string;
+    /** @deprecated Use `tokenCacheKey`. */
+    endpointId?: string;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+    additionalClaims?: Record<string, unknown>;
+};
 export type SmartTokenExchangeResult = {
     status: 'fetched' | 'cached' | 'failed';
     accessToken?: string;

package/dist/vp-token.d.ts

@@ -0,0 +1,37 @@
+export type VpTokenHeader = {
+    alg: string;
+    typ?: string;
+    kid?: string;
+    [key: string]: unknown;
+};
+export type VpTokenPayload = {
+    iss: string;
+    sub?: string;
+    aud?: string;
+    jti?: string;
+    iat?: number;
+    exp?: number;
+    nonce?: string;
+    vp: {
+        '@context'?: unknown;
+        type?: unknown;
+        holder?: string;
+        verifiableCredential: string[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+};
+export declare function generateUuidLike(): string;
+export declare function buildEpochWindow(ttlSeconds?: number): {
+    iat: number;
+    exp: number;
+};
+export declare function createVP(input?: Partial<VpTokenPayload>): VpTokenPayload;
+export declare function addVC(vpPayload: VpTokenPayload, vcJwt: string): VpTokenPayload;
+export declare function prepareForSignature(header: VpTokenHeader, payload: VpTokenPayload): {
+    encodedHeader: string;
+    encodedPayload: string;
+    signingInput: string;
+};
+export declare function prepareBytesForSignature(header: VpTokenHeader, payload: VpTokenPayload): Uint8Array;
+export declare function buildVpTokenCompact(encodedHeader: string, encodedPayload: string, signatureBase64Url: string): string;

package/dist/vp-token.js

@@ -0,0 +1,56 @@
+function toB64UrlJson(input) {
+    return Buffer.from(JSON.stringify(input), 'utf-8').toString('base64url');
+}
+function fallbackId() {
+    const rand = Math.random().toString(36).slice(2, 10);
+    return `id-${Date.now()}-${rand}`;
+}
+export function generateUuidLike() {
+    const fn = globalThis?.crypto?.randomUUID;
+    if (typeof fn === 'function')
+        return fn.call(globalThis.crypto);
+    return fallbackId();
+}
+export function buildEpochWindow(ttlSeconds = 300) {
+    const iat = Math.floor(Date.now() / 1000);
+    return { iat, exp: iat + Math.max(1, Math.floor(ttlSeconds)) };
+}
+export function createVP(input) {
+    const ttl = input?.exp && input?.iat ? undefined : buildEpochWindow(300);
+    const jti = input?.jti || generateUuidLike();
+    const nonce = input?.nonce || generateUuidLike();
+    return {
+        iss: String(input?.iss || ''),
+        sub: input?.sub,
+        aud: input?.aud,
+        jti,
+        iat: input?.iat ?? ttl?.iat,
+        exp: input?.exp ?? ttl?.exp,
+        nonce,
+        vp: {
+            '@context': ['https://www.w3.org/2018/credentials/v1'],
+            type: ['VerifiablePresentation'],
+            holder: input?.vp?.holder || input?.iss || '',
+            verifiableCredential: [],
+            ...(input?.vp || {}),
+        },
+    };
+}
+export function addVC(vpPayload, vcJwt) {
+    const v = String(vcJwt || '').trim();
+    if (v)
+        vpPayload.vp.verifiableCredential.push(v);
+    return vpPayload;
+}
+export function prepareForSignature(header, payload) {
+    const encodedHeader = toB64UrlJson(header);
+    const encodedPayload = toB64UrlJson(payload);
+    return { encodedHeader, encodedPayload, signingInput: `${encodedHeader}.${encodedPayload}` };
+}
+export function prepareBytesForSignature(header, payload) {
+    const { signingInput } = prepareForSignature(header, payload);
+    return new TextEncoder().encode(signingInput);
+}
+export function buildVpTokenCompact(encodedHeader, encodedPayload, signatureBase64Url) {
+    return `${encodedHeader}.${encodedPayload}.${String(signatureBase64Url || '').trim()}`;
+}

package/docs/API.md

@@ -478,22 +478,33 @@ const token = client.getCachedBearerToken('pkce:my-api-key');
 
 ## Transport methods
 
-### `submitBatch`
+### `submitBundle`
 
-POST a DIDComm plaintext payload (`application/didcomm-plaintext+json`).
+POST a DIDComm bundle payload. Preferred API for FHIR/API bundle operations.
 
 ```ts
-submitBatch(path: string, payload: unknown): Promise<SubmitResponse>
+submitBundle(
+  path: string,
+  payload: { thid?: string } & Record<string, unknown>,
+  options?: {
+    mode?: 'plain' | 'strict';
+    recipientEncryptionJwk?: PublicJwk;
+    walletContext?: WalletContext;
+  },
+): Promise<SubmitResponse>
 ```
 
 ```ts
-const { status, location } = await client.submitBatch(
+const { status, location } = await client.submitBundle(
   client.individualTaskBatchPath(ctx),
   payload,
+  { mode: 'plain' },
 );
 // location header contains the poll URL
 ```
 
+`submitBatch(...)` remains available as a legacy alias for compatibility.
+
 ---
 
 ### `submitBatchEncrypted`
@@ -531,6 +542,10 @@ POST a plain JSON body (`application/json`). Use for token endpoints and API key
 postJson(path: string, payload: unknown): Promise<SubmitResponse>
 ```
 
+### `submitLegacyJson`
+
+Alias of `postJson(...)` for explicit non-bundle JSON submits (openid/token/resource payloads).
+
 ```ts
 const response = await client.postJson('/host/admin/api-keys', {
   agent: { email: 'service@example.com' },

package/docs/BACKEND_NODE_INTEGRATION.md

@@ -0,0 +1,249 @@
+# Backend Node Integration
+
+This guide is backend-only and uses `dataspace-client-sdk-node`.
+
+## Secure communications intent
+
+- `backendWallet` is used for secure API communications in the dataspace.
+- User authentication and authorization still apply (for example `client_assertion` for SMART token issuance, scopes, consent).
+- Message protection can run in addition to HTTPS:
+  - signature (embedded JWS)
+  - encryption (JWE with nested JWS)
+- Apply by environment policy (`plain` / `strict` / `auto-detect`).
+- This is layered security (transport + message), not a literal VPN.
+
+## Credential map (do not mix)
+
+| Credential | Plane | Purpose | Not used for |
+|---|---|---|---|
+| transport bearer / mTLS / API-gateway credential | Transport | Allow backend HTTP access to GW deployment | User identity, `_exchange`, SMART scopes |
+| `vp_token` | Identity/business | Onboarding proof for activation | Catalog discovery auth |
+| `idToken` (user session) | Identity/business | User session proof | Transport gateway access policy |
+| `_exchange` token flow | Identity/business | Activation code exchange for initial access | Multi-ICA/operator catalog traversal |
+| SMART access token | Identity/business | Authorized protected operations via scopes | Infrastructure/operator-plane control |
+
+If your deployment does not require a transport credential, omit `bearerToken` entirely.
+
+Recommended initialization:
+
+```ts
+import { randomBytes } from 'node:crypto';
+import { DataspaceNodeClient, SeedWalletProvider } from 'dataspace-client-sdk-node';
+
+const backendWalletSeedBytes = process.env.WALLET_SEED_BASE64URL
+  ? Buffer.from(process.env.WALLET_SEED_BASE64URL, 'base64url')
+  : randomBytes(32); // if not provided, generate random 32 bytes for this runtime
+
+const backendWallet = new SeedWalletProvider(
+  Buffer.from(backendWalletSeedBytes).toString('base64url'),
+);
+
+const client = new DataspaceNodeClient({
+  baseUrl,
+  bearerToken, // optional transport-plane credential if deployment requires it
+  wallet: backendWallet,
+  ctx: { tenantId, jurisdiction, sector },
+});
+```
+
+Alternative (mutable context):
+
+```ts
+const client = new DataspaceNodeClient({ baseUrl, bearerToken, wallet: backendWallet });
+client.setContextOrg({ tenantId, jurisdiction, sector });
+client.setDefaultTimeoutSeconds(12);
+client.setDefaultIntervalSeconds(2);
+```
+
+### Communication mode (integration-level policy)
+
+SDK does not currently expose a single constructor flag for communication mode.
+Use an integration policy variable and choose the submit method explicitly:
+
+- `plain`: always `submitBundle(..., { mode: 'plain' })` (or `submitBatch(...)` for legacy compatibility)
+- `strict`: always `submitBatchEncrypted(...)`
+- `auto-detect` (default): use encrypted when backend wallet + recipient encryption JWK are available, otherwise plaintext
+
+GW compatibility (current):
+- supported request envelopes:
+  - `application/didcomm-plaintext+json` (demo/compat only)
+  - `application/json` (legacy/demo paths only)
+  - `application/x-www-form-urlencoded` with `request=<jwe>` (secure/FAPI style)
+- no standalone `didcomm-signed+json` HTTP submit mode is currently exposed as a first-class request content type.
+  - signed-only JWS exists as an internal layer pattern, but secure mode entrypoint is form-encoded JWE.
+
+```ts
+type CommunicationMode = 'plain' | 'strict' | 'auto-detect';
+const communicationMode: CommunicationMode = (process.env.GW_COMMUNICATION_MODE as CommunicationMode) || 'auto-detect';
+
+async function submitDidcomm(
+  client: DataspaceNodeClient,
+  path: string,
+  payload: Record<string, unknown>,
+  opts: {
+    mode: CommunicationMode;
+    walletContext: { tenantId: string; jurisdiction: string; sector: string; walletId?: string };
+    recipientEncryptionJwk?: any;
+  },
+) {
+  const canEncrypt = !!opts.recipientEncryptionJwk;
+  if (opts.mode === 'strict' && !canEncrypt) {
+    throw new Error('strict mode requires recipientEncryptionJwk');
+  }
+  if (opts.mode === 'strict' || (opts.mode === 'auto-detect' && canEncrypt)) {
+    return client.submitBatchEncrypted(path, payload as any, opts.recipientEncryptionJwk, opts.walletContext as any);
+  }
+  return client.submitBundle(path, payload, { mode: 'plain' });
+}
+```
+
+## Flow A. Legal Organization Onboarding (B2B)
+
+1. Receive from frontend: `jurisdiction`, `sector`, `vpToken`.
+2. Activate in GW:
+   - SDK method: `activateOrganizationInGatewaySimple(...)` (recommended)
+   - SDK method: `activateOrganizationInGatewayFromIcaProof(...)` (advanced)
+3. Complete legal organization order (always; amount may be `0`) using `offerId` returned by activation response.
+   - `hostRegistryOrderBatchPath(...)`
+   - `hostRegistryOrderPollPath(...)`
+   - `submitAndPoll(...)`
+4. Run DCR/token bootstrap:
+   - `activateEmployeeDeviceWithActivationCodeSimple(...)` (recommended)
+   - `activateEmployeeDeviceWithActivationCode(...)` (advanced)
+   - `requestSmartTokenSimple(...)` (recommended)
+   - `requestSmartToken(...)` (advanced)
+   - `authenticateBackendPkceAndExchange(...)` or `authenticateBackendSmartStandard(...)`
+
+### Custom backend code example: activate endpoint
+
+```ts
+app.post('/api/onboarding/legal/activate', async (req, res) => {
+  const client = new DataspaceNodeClient({ baseUrl, bearerToken });
+  client.setContextOrg({
+    tenantId: req.body.tenantId,
+    jurisdiction: req.body.jurisdiction,
+    sector: req.body.sector,
+  });
+  const activation = await client.activateOrganizationInGatewaySimple({
+    vpToken: req.body.vpToken,
+    serviceProviderDidWeb: req.body.serviceProviderDidWeb, // or serviceProviderUrl
+    serviceProviderUrl: req.body.serviceProviderUrl,
+    controllerEmail: req.body.controllerEmail,
+    controllerTelephone: req.body.controllerTelephone, // optional alternative to email
+    controllerRole: req.body.controllerRole,
+    numberOfMembers: req.body.numberOfMembers ?? 2,
+  });
+  const offerId = client.getOfferIdFromResponse(activation);
+  if (!offerId) throw new Error('Offer id missing in activation response');
+  const offer = client.getOfferPreviewFromResponse(activation);
+  // Use `offer` to render amount/currency/description to user before acceptance.
+  const order = await client.confirmLegalOrganizationOrderSimple({
+    offerId,
+  });
+  res.json({ activation, offerId, order });
+});
+```
+
+Async UX note:
+- `submitAndPoll` is convenient but returns final state.
+- If you need progress updates, call lower-level `submitBatch` + `pollUntilComplete`
+  and stream step transitions to frontend.
+
+## Flow B. Personal Organization Onboarding (individual/family)
+
+1. Receive registration payload from frontend.
+2. Start registration and extract offer:
+   - SDK method: `startIndividualOrganizationSimple(...)` (recommended)
+3. Frontend shows offer and user accepts.
+4. Confirm order:
+   - SDK method: `confirmIndividualOrganizationOrderSimple(...)` (recommended)
+5. Provisional one-shot helper (auto-order, for legacy/fork scenarios):
+   - SDK method: `bootstrapIndividualOrganizationSimple(...)` (provisional)
+3. Continue consent/clinical lifecycle as needed:
+   - `grantProfessionalAccessSimple(...)`
+   - `importIpsOrFhirAndUpdateIndex(...)`
+   - `requestSmartTokenSimple(...)` (recommended)
+   - `requestSmartToken(...)` (advanced)
+   - `generateDigitalTwinFromSubjectData(...)`
+
+### Custom backend code example: personal register endpoint
+
+```ts
+app.post('/api/onboarding/personal/register', async (req, res) => {
+  const client = new DataspaceNodeClient({ baseUrl, bearerToken });
+  const ctx = {
+    tenantId: req.body.tenantId,
+    jurisdiction: req.body.jurisdiction,
+    sector: req.body.sector,
+  };
+
+  const started = await client.startIndividualOrganizationSimple({
+    alternateName: req.body.alternateName,
+    controllerEmail: req.body.controllerEmail,
+    controllerTelephone: req.body.controllerTelephone,
+    controllerRole: req.body.controllerRole || 'org.hl7.v3.RoleCode|RESPRSN',
+  });
+  // Return offer to frontend for explicit acceptance UX.
+  // Later, call confirmIndividualOrganizationOrderSimple({ offerId: started.offerId }).
+  res.json(started);
+});
+```
+
+## References
+
+- `examples/e2e-bootstrap-tenant.mjs`
+- `examples/host-activate-and-employee.mjs`
+- `examples/e2e-individual-flow.mjs`
+- `tests/uc5-org-onboarding.flow.test.mjs`
+- `tests/uc5-subject-data.flow.test.mjs`
+
+## Deterministic Wallet Profile (seed-based, integrator-managed)
+
+Use this section for all flows (controller/professional/personal) when the backend signs/encrypts DIDComm messages without external per-operation KMS signing.
+
+Core rule:
+- key custody and seed storage are integrator responsibility
+- SDK requires signing/encryption capability, not local private-key assumptions
+
+Recommended derivation contract:
+
+```ts
+type DeriveKeyMaterialInput = {
+  seed: Uint8Array;               // decrypted by integrator runtime
+  tenantId: string;
+  jurisdiction: string;
+  sector: string;
+  walletId?: string;
+  purpose: 'signing' | 'encryption';
+  algorithm: 'ES384' | 'ES256K' | 'ML-DSA-65' | 'ML-KEM-768';
+  kdfVersion: 'v1';
+};
+```
+
+Domain separation (mandatory):
+- derive per `purpose` and `algorithm`
+- never reuse derived bytes across different purposes or algorithms
+
+Canonical context string:
+- `tenantId|jurisdiction|sector|walletId|purpose|algorithm|kdfVersion`
+
+KDF profile (example):
+- `scrypt(seed, salt=context, N=2^15, r=8, p=1, dkLen=64)`
+- split derived bytes by algorithm requirements
+- keep parameters versioned and immutable per `kdfVersion`
+
+Why:
+- deterministic reproducibility across runs/devices
+- safe algorithm migration (ES384 now, ML-DSA later) without collisions
+- portable across Node backend and mobile/web SDK profiles
+
+Strict DIDComm mode:
+- sign payload as embedded JWS
+- encrypt as JWE for recipient
+- use the derived keypair for the active `purpose+algorithm`
+
+Flow links:
+- `CONTROLLER_FLOW_STEP_BY_STEP.md`
+- `LEGAL_ORGANIZATION_FLOW_STEP_BY_STEP.md`
+- `PRACTITIONER_FLOW_STEP_BY_STEP.md`
+- `PERSONAL_FLOW_STEP_BY_STEP.md`