dataspace-client-sdk-node 0.1.1 → 0.2.0

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/DATA_MODEL_ALIGNMENT.md

@@ -1,31 +1,55 @@
-# Data Model Alignment (GW + Chat + SDK)
+# Data Model Alignment (GW + ICA + DataConv + SDK)
 
-Alignment reference for SDK consumers and backend integrators.
+Reference alignment for SDK consumers and backend integrators.
 
-## Business vs Infra Sector
+## API Namespace Alignment
 
-- Infra host onboarding uses network routing sector (`HOST_REGISTRY_SECTOR`).
+- Gateway onboarding and operational flows use `/host/...` with `auth`-based security (OIDC + smart token post-DCR).
+- ICA flows use `/ica/...` namespace.
+- DataConv flows use `/publisher/...` namespace.
+- SDK helpers should abstract these prefixes so integrators do not rebuild paths manually.
+
+## Business Sector vs Host Registry Sector
+
+- Host onboarding/routing can use infrastructure/network sector (`HOST_REGISTRY_SECTOR`).
 - Tenant runtime model uses business sector (`SECTOR`).
-- Canonical tenant vault ID:
+- Canonical tenant vault ID format:
   - `<SECTOR>_<tenantId>`
   - Example: `health-care_acme`
 
+## Legal Organization Activation Inputs
+
+- `vp_token` is the primary proof artifact.
+- Organization VC can be extracted from the VP (`LegalOrganizationCredential` / `OrganizationCredential`).
+- Representative VC is optional depending on policy, but contact/role claims are still required for controller bootstrap.
+- Controller contact supports both:
+  - `org.schema.Person.email`
+  - `org.schema.Person.telephone`
+- Do not document phone-only assumptions as general contract.
+
+## Offer/Order Commercial Contract
+
+- Offer/Order remains part of the onboarding business flow even when amount is `0`.
+- SDK should expose helpers to:
+  - extract offer identifier from activation/orderable claims
+  - expose offer preview fields (amount, currency, description) for UI confirmation
+- Backend should send Order acceptance explicitly using `Order.acceptedOffer.identifier`.
+
 ## Individual Organization Model
 
-- Section: `<prefix>_individual`
-- Doc ID: `org.schema.Organization.identifier.value` (UUID)
+- Section naming: `<prefix>_individual`.
+- Canonical individual org identifier: `org.schema.Organization.identifier.value` (UUID).
+- Contact model is the same as legal org onboarding: email or telephone.
 
 ## Search Contract (`searchFamilyOrganization`)
 
 - Input mapping:
   - `controllerPhone` -> `org.schema.Organization.owner.telephone`
+  - `controllerEmail` -> `org.schema.Organization.owner.email`
   - `usualname` -> `org.schema.Organization.alternateName`
   - `birthDate` -> `org.schema.Organization.foundingDate` (optional)
 
-## Voice Phone Contract
-
-- Preferred claim for subject call target:
-  - `org.schema.Organization.telephone`
-- Fallback claim:
-  - `org.schema.Organization.owner.telephone`
+## Voice/Phone Use Case Notes
 
+- Voice agents may prioritize `telephone` for call target resolution.
+- Generic portal/web integrations must support both email and telephone identity channels.

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.

package/docs/LEGAL_ORGANIZATION_FLOW_STEP_BY_STEP.md

@@ -0,0 +1,84 @@
+# LEGAL_ORGANIZATION_FLOW_STEP_BY_STEP
+
+Canonical legal-organization flow index.
+This file avoids duplicating controller/practitioner details and points to the source guides.
+
+## Mandatory rules for integrators
+
+Security planes:
+- Transport plane: backend ↔ gateway channel protection (deployment-specific).
+- Identity/business plane: user/controller/member authentication and authorization.
+- Operator/hosting plane: infrastructure/operator lifecycle.
+
+Keep these planes separated; do not treat transport credentials as user identity tokens.
+
+Secure messaging note:
+- Authentication for controller/member actions is identity-plane (`vp_token`, `idToken`, SMART/client_assertion).
+- Backend-to-service P2P messages can additionally be signed/encrypted (embedded JWS/JWE) according to deployment communication mode.
+
+Wallet profile:
+- deterministic key derivation/profile rules are centralized in `BACKEND_NODE_INTEGRATION.md` ("Deterministic Wallet Profile").
+- communication mode (`plain` / `strict` / `auto-detect`) is centralized in `BACKEND_NODE_INTEGRATION.md`.
+
+- `jurisdiction` (country) is required in every step.
+- Professional tenants are registered in one jurisdiction and all routes resolve against it.
+- Identity auth routes and business/entity routes are different:
+  - identity: `/host/cds-{jurisdiction}/v1/{sector}/{tenantId}/identity/auth/...`
+  - business: `/{tenantId}/cds-{jurisdiction}/v1/{sector}/...`
+- `vp_token` is for onboarding proof (`_activate`), not for runtime calls.
+- Controller DCR/token and practitioner DCR/token are distinct flows.
+
+## Runtime context pattern (high-level)
+
+```ts
+const profileContext = {
+  baseUrl: process.env.BASE_URL!,
+  jurisdiction: process.env.JURISDICTION!, // REQUIRED
+  sector: process.env.SECTOR || 'health-care',
+};
+
+const sessionContext = {
+  tenantId: currentSession.tenantId,
+  controller: currentSession.controller,
+  practitioner: currentSession.practitioner,
+};
+```
+
+Use `profileContext` for role/organization runtime context and `sessionContext` for logged-in user/session data.
+
+## Phase A: controller flow (authoritative)
+
+1. Build/sign VP token (`nonce`, no `jti` in VP for this flow).
+2. `_activate` organization in host registry.
+3. Read offer and explicit user acceptance.
+4. Submit `initialOrder`.
+5. Controller DCR bootstrap (`_exchange` then `_dcr`).
+6. Request controller runtime token (`_token`).
+7. Create employee/member in entity route.
+8. Extract activation code for practitioner.
+9. If license seats are exhausted: receive `Employee-license-offer-v1.0`, accept, submit `licenseOrder`, retry employee create.
+
+Detailed guide (single source of truth):
+- `CONTROLLER_FLOW_STEP_BY_STEP.md`
+
+## Phase B: practitioner flow (authoritative)
+
+1. Receive practitioner activation code from controller flow.
+2. Practitioner DCR bootstrap (`_exchange` then `_dcr`).
+3. Request practitioner SMART/runtime token (`_token`) with required scopes.
+4. Call protected organization/business endpoints.
+
+Detailed guide (single source of truth):
+- `PRACTITIONER_FLOW_STEP_BY_STEP.md`
+
+## Scope of this file
+
+- Keep this file as top-level legal organization map.
+- Put implementation details in:
+  - `CONTROLLER_FLOW_STEP_BY_STEP.md`
+  - `PRACTITIONER_FLOW_STEP_BY_STEP.md`
+  - `BACKEND_NODE_INTEGRATION.md`
+
+Related references:
+- `ENDPOINT_ID_CATALOG.md`
+- `DATA_MODEL_ALIGNMENT.md`