dataspace-client-sdk-node 0.1.2 → 0.2.0

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

@@ -2,12 +2,46 @@
 
 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,
+  bearerToken, // optional transport-plane credential if deployment requires it
+  wallet: backendWallet,
   ctx: { tenantId, jurisdiction, sector },
 });
 ```
@@ -15,12 +49,54 @@ const client = new DataspaceNodeClient({
 Alternative (mutable context):
 
 ```ts
-const client = new DataspaceNodeClient({ baseUrl, bearerToken });
+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`.
@@ -120,3 +196,54 @@ app.post('/api/onboarding/personal/register', async (req, res) => {
 - `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`

package/docs/CONTROLLER_FLOW_STEP_BY_STEP.md

@@ -0,0 +1,283 @@
+# CONTROLLER_FLOW_STEP_BY_STEP
+
+Strict step-by-step flow for organization onboarding by controller, then controller runtime activation, then employee provisioning.
+
+## Security model (read first)
+
+Security planes:
+- Transport plane (deployment-specific): backend ↔ gateway channel protection (optional bearer, mTLS, API gateway policy).
+- Identity/business plane (functional flow): controller/member credentials and tokens (`vp_token`, `idToken`, DCR, SMART).
+- Operator/hosting plane: infrastructure tenancy and node-operator lifecycle.
+
+Do not mix these planes in implementation or documentation.
+
+Secure communication intent:
+- controller/member auth tokens are identity-plane credentials
+- in addition, backend P2P messages can be protected with embedded JWS/JWE via backend wallet
+- use `plain` / `strict` / `auto-detect` communication policy per deployment
+
+- `initialOrder` = first order linked to onboarding `offerId` from `_activate`.
+- `licenseOrder` = later order(s) for additional employee licenses.
+- `initialOrder` is authorized by onboarding proof (`vp_token`) + gateway onboarding policy.
+- `licenseOrder` is a runtime business operation and must use controller runtime auth (DCR + SMART token).
+- DCR for controller and DCR for employee are different operations and different identities.
+
+Current GW behavior for `Employee/_batch` (important):
+- if employee license pool exists and has `available` seats: employee is created (`201`) and one seat is consumed
+- if employee license pool exists but has no `available` seats: response is `Employee-license-offer-v1.0` (no employee created)
+- if employee license pool does not exist: employee is created without license gating (legacy/non-strict mode)
+
+## 0) Runtime context (not all from `.env`)
+
+```ts
+// optional transport security context (deployment-specific, not user identity)
+const transportSecurity = {
+  gwBearerToken: process.env.GW_BEARER_TOKEN, // optional
+};
+```
+
+```ts
+// profile-level runtime context for this authenticated role in this organization
+const profileContext = {
+  baseUrl: process.env.BASE_URL!,
+  jurisdiction: process.env.JURISDICTION!, // REQUIRED
+  sector: process.env.SECTOR || 'health-care',
+  hostRegistrySector: process.env.HOST_REGISTRY_SECTOR || 'test-network',
+  gwDidWeb: process.env.GW_DID_WEB!,
+  credentialExpSeconds: Number(process.env.CREDENTIAL_EXP_SECONDS || 300),
+};
+
+// user/session context (from authenticated portal user + selected tenant/org)
+const sessionContext = {
+  tenantId: currentSession.tenantId,
+  controllerDidWeb: currentSession.controller.didWeb,
+  controllerSignKid: currentSession.controller.signKid, // RFC7638 thumbprint / key id
+  controllerIdToken: currentSession.idToken,
+  controllerPublicJwk: currentSession.controller.publicJwk,
+  controllerEmail: currentSession.controller.email,
+  newMemberEmailToInvite: uiFormNewMember.email,
+  newMemberRoleCode: uiFormNewMember.hasOccupation || 'ISCO-08|2211',
+};
+
+// credentials issued previously by ICA
+const onboardingProof = {
+  organizationVcJwt: currentSession.ica.organizationVcJwt,
+  legalRepresentativeVcJwt: currentSession.ica.legalRepresentativeVcJwt, // optional by policy
+};
+```
+
+## 1) Build and externally sign `vp_token` (controller identity proof)
+
+```ts
+import {
+  DataspaceNodeClient,
+  createVP, addVC, prepareForSignature, prepareBytesForSignature, buildVpTokenCompact,
+  buildEpochWindow, generateUuidLike,
+} from 'dataspace-client-sdk-node';
+import { ClaimsPersonSchemaorg } from 'gdc-common-utils-ts/constants/schemaorg';
+
+const { iat, exp } = buildEpochWindow(profileContext.credentialExpSeconds);
+const header = {
+  alg: 'ES256',
+  typ: 'JWT',
+  kid: `${sessionContext.controllerDidWeb}#${sessionContext.controllerSignKid}`,
+};
+const uniquePresentationNonce = generateUuidLike();
+const vp = createVP({
+  iss: sessionContext.controllerDidWeb,
+  sub: sessionContext.controllerDidWeb,
+  aud: profileContext.gwDidWeb,
+  iat,
+  exp,
+  nonce: uniquePresentationNonce,
+});
+
+addVC(vp, onboardingProof.organizationVcJwt);
+if (onboardingProof.legalRepresentativeVcJwt) addVC(vp, onboardingProof.legalRepresentativeVcJwt);
+
+const { encodedHeader, encodedPayload } = prepareForSignature(header, vp);
+const bytesToSign = prepareBytesForSignature(header, vp);
+const signatureBase64Url = await externalSigner(bytesToSign); // wallet/HSM
+const vpToken = buildVpTokenCompact(encodedHeader, encodedPayload, signatureBase64Url);
+```
+
+Signing responsibility (integrator):
+- SDK provides `prepareForSignature(...)` and `prepareBytesForSignature(...)` to produce the JWT signing input.
+- Signing input is exactly: `base64url(header) + "." + base64url(payload)`.
+- The integrator signs that input with the current user's key material (wallet, secure storage, KMS, HSM, etc.).
+- SDK does not require local custody of private keys.
+
+## 2) Activate organization in GW (`_activate`)
+
+```ts
+const client = new DataspaceNodeClient({
+  baseUrl: profileContext.baseUrl,
+  ...(transportSecurity.gwBearerToken ? { bearerToken: transportSecurity.gwBearerToken } : {}),
+  ctx: { tenantId: sessionContext.tenantId, jurisdiction: profileContext.jurisdiction, sector: profileContext.sector },
+});
+
+const activation = await client.activateOrganizationInGatewayFromIcaProof(
+  { jurisdiction: profileContext.jurisdiction, sector: profileContext.hostRegistrySector },
+  {
+    vpToken,
+    organizationVc: onboardingProof.organizationVcJwt,
+    legalRepresentativeVc: onboardingProof.legalRepresentativeVcJwt,
+    numberOfMembers: 2,
+  },
+);
+```
+
+Jurisdiction is mandatory in all flows:
+- Professional: the organization/tenant is registered in one jurisdiction (country) and routes/scopes resolve against it.
+- Personal: user selects jurisdiction first, then service providers are filtered for that jurisdiction.
+- Integrator rule: reject onboarding/session setup when `jurisdiction` is missing.
+
+Auth model note:
+- user auth tokens (`idToken`, SMART access token) belong to the identity/business plane (authenticated user session).
+- `transportSecurity.gwBearerToken` belongs to the transport plane only and is optional by deployment.
+- `transportSecurity.gwBearerToken` is not an ICA exchange token and not a controller API key.
+
+## 3) Read Offer and show explicit acceptance UI
+
+```ts
+const offerId = client.getOfferIdFromResponse(activation);
+const offer = client.getOfferInfoFromResponse(activation);
+if (!offerId) throw new Error('Offer id missing in activation response');
+// show offer in UI and wait for user acceptance
+```
+
+## 4) Send Order (always, even if amount is 0)
+
+```ts
+// This is the INITIAL ORDER (onboarding order).
+const initialOrder = await client.confirmLegalOrganizationOrderSimple({ offerId });
+```
+
+## 5) Controller runtime activation (DCR) to operate organization's APIs
+
+This is separate from onboarding proof. It creates controller device runtime identity.
+
+```ts
+const controllerActivationCode =
+  client.getActivationCodeFromResponse(initialOrder) ||
+  client.getActivationCodeFromResponse(activation);
+if (!controllerActivationCode) throw new Error('Controller activation code not found');
+
+const controllerDevice = await client.activateEmployeeDeviceWithActivationCodeSimple({
+  tenantId: sessionContext.tenantId,
+  jurisdiction: profileContext.jurisdiction,
+  sector: profileContext.sector,
+  activationCode: controllerActivationCode,
+  idToken: sessionContext.controllerIdToken,
+  dcrPayload: {
+    application_type: 'web',
+    token_endpoint_auth_method: 'private_key_jwt',
+    jwks: { keys: [sessionContext.controllerPublicJwk] },
+  },
+});
+```
+
+## 6) Controller identity token vs entity token (separate concerns)
+
+- Identity token request endpoint is tenant-scoped auth route:
+  `/host/cds-{jurisdiction}/v1/{sector}/{tenantId}/identity/auth/_token`
+- The returned access token is then used to call entity/business endpoints like:
+  `/{tenantId}/cds-{jurisdiction}/v1/{sector}/entity/org.schema/Employee/_batch`
+
+Use explicit cache keys by intent to avoid confusion:
+- `controller_identity_token:*` for auth/token operations
+- `controller_entity_token:*` for entity/business operations
+
+```ts
+const controllerSmart = await client.requestSmartTokenSimple({
+  tenantId: sessionContext.tenantId,
+  jurisdiction: profileContext.jurisdiction,
+  sector: profileContext.sector,
+  idToken: sessionContext.controllerIdToken,
+  targetEndpoint: client.getEndpointId(
+    { section: 'organization', format: 'org.hl7.fhir.r4', resourceType: 'Person', action: '_batch' },
+    sessionContext.controllerDidWeb,
+  ),
+  scopes: [
+    'organization/Person.cruds',
+    'organization/Organization.cruds',
+    'organization/Consent.cruds',
+  ],
+});
+```
+
+## 7) Create newMember/practitioner employee (runtime, uses controller token)
+
+```ts
+const employee = await client.createOrganizationEmployee(
+  { tenantId: sessionContext.tenantId, jurisdiction: profileContext.jurisdiction, sector: profileContext.sector },
+  {
+    employeeClaims: {
+      '@context': 'org.schema',
+      [ClaimsPersonSchemaorg.email]: sessionContext.newMemberEmailToInvite,
+      [ClaimsPersonSchemaorg.hasOccupation]: sessionContext.newMemberRoleCode,
+    },
+  },
+);
+```
+
+## 8) Extract newMember activation code and hand off to practitioner flow
+
+```ts
+const newMemberActivationCode = client.getActivationCodeFromResponse(employee);
+if (!newMemberActivationCode) throw new Error('newMember activation code not found');
+```
+
+## 9) If no license is available: create `licenseOrder` (separate from `initialOrder`)
+
+When employee creation returns license-offer/gating instead of activation code:
+
+1. Extract `licenseOfferId` from employee response (same `getOfferIdFromResponse(...)` helper).
+2. Show offer in UI and request explicit user acceptance.
+3. Submit a new order as `licenseOrder`.
+4. Retry employee creation after successful `licenseOrder`.
+
+```ts
+const licenseOfferId = client.getOfferIdFromResponse(employee);
+if (!licenseOfferId) throw new Error('License offer id missing');
+
+// This is a LICENSE ORDER (runtime order), not the onboarding order.
+const licenseOrder = await client.confirmLegalOrganizationOrderSimple({
+  offerId: licenseOfferId,
+});
+```
+
+Authentication rules for this step:
+- never reuse onboarding `vp_token` for runtime ordering
+- use controller runtime identity (DCR already completed)
+- use controller SMART token for protected runtime routes
+
+Route intent:
+- controller's onboarding activation and onboarding order for the legal organization: `/host/.../registry/...`
+- controller's identity DCR/token flows are tenant-scoped for the legal organization but exposed as `/host/.../{tenantId}/identity/auth/...`
+- employee business operations use tenant-scoped data routes: `/{tenantId}/.../entity/...` (or corresponding section)
+
+Complete path examples:
+(using `test-network` but `test` can be used for local development)
+- activate organization:
+  `/host/cds-ES/v1/test-network/registry/org.schema/Organization/_activate`
+- poll activate:
+  `/host/cds-ES/v1/test-network/registry/org.schema/Organization/_activate-response`
+- initial onboarding order:
+  `/host/cds-ES/v1/test-network/registry/org.schema/Order/_batch`
+- poll onboarding order:
+  `/host/cds-ES/v1/test-network/registry/org.schema/Order/_batch-response`
+- controller/employee identity exchange (activation code -> initial token):
+  `/host/cds-ES/v1/health-care/{tenantId}/identity/auth/_exchange`
+- controller's DCR (consumes the initial access token with scope 'dcr' as per OpenID DCR):
+  `/host/cds-ES/v1/health-care/{tenantId}/identity/auth/_dcr`
+- controller's smart token for entity management:
+  `/host/cds-ES/v1/health-care/{tenantId}/identity/auth/_token`
+- employee creation:
+  `/{tenantId}/cds-ES/v1/health-care/entity/org.schema/Employee/_batch`
+
+Continue with:
+- `PRACTITIONER_FLOW_STEP_BY_STEP.md`
+
+Shared wallet derivation profile:
+- `BACKEND_NODE_INTEGRATION.md` ("Deterministic Wallet Profile")

package/docs/DEVELOPER_USE_CASES.md

@@ -11,6 +11,7 @@ SDK: `dataspace-client-sdk-node` (`DataspaceNodeClient`)
 
 ```ts
 import { DataspaceNodeClient } from 'dataspace-client-sdk-node';
+import { ClaimsPersonSchemaorg } from 'gdc-common-utils-ts/constants/schemaorg';
 
 const client = new DataspaceNodeClient({
   baseUrl: process.env.GW_BASE_URL!,
@@ -29,6 +30,7 @@ const ctx = {
 Terminology note: `subject` names in methods/claims refer to the member (person/patient) orchestrated by a personal organization with controller/manager and associated members.
 
 Method: `bootstrapSubjectOrganizationIndex(ctx, input)`
+Test: [tests/client.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/client.test.mjs), [tests/uc5-subject-data.flow.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/uc5-subject-data.flow.test.mjs)
 
 ```ts
 const result = await client.bootstrapSubjectOrganizationIndex(ctx, {
@@ -48,6 +50,7 @@ const result = await client.bootstrapSubjectOrganizationIndex(ctx, {
 ## UC5.2 Legal organization activation in GW (from ICA proof)
 
 Method: `activateOrganizationInGatewayFromIcaProof(hostCtx, input)`
+Test: [tests/client.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/client.test.mjs), [tests/uc5-org-onboarding.flow.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/uc5-org-onboarding.flow.test.mjs)
 
 ```ts
 const activation = await client.activateOrganizationInGatewayFromIcaProof(
@@ -64,13 +67,14 @@ const activation = await client.activateOrganizationInGatewayFromIcaProof(
 ## UC5.3 Create employee / professional license
 
 Method: `createOrganizationEmployee(ctx, input)`
+Test: [tests/client.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/client.test.mjs), [tests/uc5-org-onboarding.flow.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/uc5-org-onboarding.flow.test.mjs)
 
 ```ts
 await client.createOrganizationEmployee(ctx, {
   employeeClaims: {
     '@context': 'org.schema',
-    'org.schema.Person.email': 'doctor@example.com',
-    'org.schema.Person.hasOccupation': 'ISCO-08|2211',
+    [ClaimsPersonSchemaorg.email]: 'doctor@example.com',
+    [ClaimsPersonSchemaorg.hasOccupation]: 'ISCO-08|2211',
   },
 });
 ```
@@ -78,6 +82,7 @@ await client.createOrganizationEmployee(ctx, {
 ## UC5.4 Activate employee device
 
 Method: `activateEmployeeDeviceWithActivationCode(ctx, input)`
+Test: [tests/client.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/client.test.mjs), [tests/uc5-org-onboarding.flow.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/uc5-org-onboarding.flow.test.mjs)
 
 ```ts
 const device = await client.activateEmployeeDeviceWithActivationCode(ctx, {
@@ -94,6 +99,7 @@ const device = await client.activateEmployeeDeviceWithActivationCode(ctx, {
 ## UC5.5 Import IPS/FHIR and update index
 
 Method: `importIpsOrFhirAndUpdateIndex(ctx, input)`
+Test: [tests/client.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/client.test.mjs), [tests/uc5-subject-data.flow.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/uc5-subject-data.flow.test.mjs)
 
 ```ts
 await client.importIpsOrFhirAndUpdateIndex(ctx, {
@@ -110,6 +116,7 @@ await client.importIpsOrFhirAndUpdateIndex(ctx, {
 
 Step 1 method: `grantProfessionalAccessSimple(ctx, input)`  
 Step 2 method: `requestSmartToken(input)`
+Test: [tests/client.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/client.test.mjs), [tests/uc5-subject-data.flow.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/uc5-subject-data.flow.test.mjs)
 
 Domain note: the protected context is modeled as organization (including personal organizations with controller + subject/person/patient members).
 
@@ -138,6 +145,7 @@ const token = await client.requestSmartToken({
 ## UC5.7 Generate digital twin
 
 Method: `generateDigitalTwinFromSubjectData(ctx, input)`
+Test: [tests/client.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/client.test.mjs), [tests/uc5-subject-data.flow.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/uc5-subject-data.flow.test.mjs)
 
 ```ts
 await client.generateDigitalTwinFromSubjectData(ctx, {