dataspace-client-sdk-node 0.1.2 → 0.2.1

package/docs/BACKEND_NODE_INTEGRATION.md

@@ -2,12 +2,43 @@
 
 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 |
+
 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,
+  wallet: backendWallet,
   ctx: { tenantId, jurisdiction, sector },
 });
 ```
@@ -15,23 +46,71 @@ const client = new DataspaceNodeClient({
 Alternative (mutable context):
 
 ```ts
-const client = new DataspaceNodeClient({ baseUrl, bearerToken });
+const client = new DataspaceNodeClient({ baseUrl, 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:
+1. Verify legal-organization PDF in ICA and obtain:
+   - `OrganizationCredential` VC
+   - `LegalRepresentativeCredential` VC
+2. Build VP payload with both VCs and prepare `header.payload` for signature.
+   - integrator signs with controller key (ES256K / ES384 / ML-DSA depending on environment policy)
+3. Receive from frontend/backend session context: `jurisdiction`, `sector`, `tenantId`, signed `vpToken`.
+4. 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.
+5. Complete legal organization order (always; amount may be `0`) using `offerId` returned by activation response.
    - `hostRegistryOrderBatchPath(...)`
    - `hostRegistryOrderPollPath(...)`
    - `submitAndPoll(...)`
-4. Run DCR/token bootstrap:
+6. Run controller DCR/token bootstrap first (`_exchange` then `_dcr`), then employee flows.
+7. Run employee DCR/token bootstrap when employee is invited/activated:
    - `activateEmployeeDeviceWithActivationCodeSimple(...)` (recommended)
    - `activateEmployeeDeviceWithActivationCode(...)` (advanced)
    - `requestSmartTokenSimple(...)` (recommended)
@@ -42,7 +121,7 @@ client.setDefaultIntervalSeconds(2);
 
 ```ts
 app.post('/api/onboarding/legal/activate', async (req, res) => {
-  const client = new DataspaceNodeClient({ baseUrl, bearerToken });
+  const client = new DataspaceNodeClient({ baseUrl });
   client.setContextOrg({
     tenantId: req.body.tenantId,
     jurisdiction: req.body.jurisdiction,
@@ -94,7 +173,7 @@ Async UX note:
 
 ```ts
 app.post('/api/onboarding/personal/register', async (req, res) => {
-  const client = new DataspaceNodeClient({ baseUrl, bearerToken });
+  const client = new DataspaceNodeClient({ baseUrl });
   const ctx = {
     tenantId: req.body.tenantId,
     jurisdiction: req.body.jurisdiction,
@@ -120,3 +199,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, {

package/docs/E2E_LOCAL_GW_UC5.md

@@ -0,0 +1,49 @@
+# E2E Local GW UC5 (Reproducible, No Mocks)
+
+This test runs a real UC5 chain against a locally running GW in demo mode:
+
+1. Legal entity controller activates tenant (`Organization/_activate`).
+2. Individual controller bootstraps personal/individual organization (`Organization/_batch` + `Order/_batch`).
+3. Consent is created (`Consent/_batch`) with `organization/Composition.rs`.
+4. Professional requests SMART token and receives scoped token.
+
+Test file:
+- [live-gw-uc5.e2e.test.mjs](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/live-gw-uc5.e2e.test.mjs)
+
+## Prerequisites
+
+1. Start GW local in demo mode:
+```bash
+npm -C /Users/fernando/GITS/gdc-workspace/gwtemplate-node-ts run api:local-demo
+```
+
+2. Provide ICA proof as either:
+- `VP_TOKEN` (preferred, real signed VP), or
+- `VP_TOKEN_FILE` pointing to a minimal fixture payload.
+
+Default fixture included:
+- [ica-vp-minimal.json](/Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node/tests/fixtures/ica-vp-minimal.json)
+- Built at runtime into unsigned compact JWT only for local demo reproducibility.
+
+3. Use a tenant id aligned with your activation proof (`TENANT_ID`).
+
+## Run
+
+```bash
+cd /Users/fernando/GITS/gdc-workspace/dataspace-client-sdk-node
+BASE_URL=http://127.0.0.1:3000 \
+VP_TOKEN_FILE=./tests/fixtures/ica-vp-minimal.json \
+TENANT_ID=VATES-B00000000 \
+JURISDICTION=ES \
+SECTOR=health-care \
+HOST_REGISTRY_SECTOR=test \
+PROFESSIONAL_ID_TOKEN='eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJzdWIiOiJwcm9mZXNzaW9uYWwifQ.demo' \
+npm run test:e2e:live-gw-uc5
+```
+
+## Notes
+
+- This is a real integration test (no `fetch` mocks).
+- `_activate` in this E2E uses `vp_token` in payload (no Bearer header required by the test).
+- If `TENANT_ID` does not match activation proof context, downstream tenant-scoped steps can return `404`.
+- The scripted scope assertion verifies `organization/Composition.rs` is granted in SMART token response.

package/docs/ENDPOINT_ID_CATALOG.md

@@ -0,0 +1,90 @@
+# ENDPOINT_ID_CATALOG
+
+Canonical endpoint-id construction for token cache/session reuse.
+
+Use `client.getEndpointId(selector, providerDid?)` and avoid ad-hoc strings.
+
+Selector shape:
+
+```ts
+type EndpointSelector = {
+  section: string;
+  format: string;
+  resourceType: string;
+  action: string;
+};
+```
+
+Generation rule:
+- With `providerDid`: `did:web:...#section:format:resourceType:action`
+- Without `providerDid`: `section:format:resourceType:action`
+
+## Recommended selectors
+
+```ts
+export const ENDPOINT_SELECTORS = {
+  ORG_COMPOSITION_SEARCH: {
+    section: 'organization',
+    format: 'org.hl7.fhir.r4',
+    resourceType: 'Composition',
+    action: '_search',
+  },
+  INDIVIDUAL_CONSENT_BATCH: {
+    section: 'individual',
+    format: 'org.hl7.fhir.r4',
+    resourceType: 'Consent',
+    action: '_batch',
+  },
+  INDIVIDUAL_COMMUNICATION_BATCH: {
+    section: 'individual',
+    format: 'org.hl7.fhir.r4',
+    resourceType: 'Communication',
+    action: '_batch',
+  },
+  INDIVIDUAL_DOCUMENTREFERENCE_BATCH: {
+    section: 'individual',
+    format: 'org.hl7.fhir.r4',
+    resourceType: 'DocumentReference',
+    action: '_batch',
+  },
+  IDENTITY_AUTH_TOKEN: {
+    section: 'identity',
+    format: 'auth',
+    resourceType: 'token',
+    action: '_token',
+  },
+  IDENTITY_AUTH_DCR: {
+    section: 'identity',
+    format: 'auth',
+    resourceType: 'device',
+    action: '_dcr',
+  },
+  IDENTITY_AUTH_EXCHANGE: {
+    section: 'identity',
+    format: 'auth',
+    resourceType: 'token',
+    action: '_exchange',
+  },
+} as const;
+```
+
+## Example
+
+```ts
+const targetEndpoint = client.getEndpointId(
+  ENDPOINT_SELECTORS.ORG_COMPOSITION_SEARCH,
+  ORG_CONTROLLER_DID_WEB,
+);
+
+const smart = await client.requestSmartTokenSimple({
+  idToken,
+  targetEndpoint,
+  scopes: ['organization/Composition.rs'],
+});
+```
+
+## Alignment policy
+
+- Prefer current namespaces and flows: `/host`, `/ica`, `/publisher`, and GW runtime `identity/auth`.
+- Do not introduce new integrations based on legacy aliases.
+- Keep endpoint-id selectors stable and explicit across Node + frontend SDKs.