dataspace-client-sdk-node 0.1.2 → 0.2.1

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`

package/docs/PERSONAL_FLOW_STEP_BY_STEP.md

@@ -0,0 +1,70 @@
+# PERSONAL_FLOW_STEP_BY_STEP
+
+Canonical flow for personal/family onboarding and consented access.
+
+Security note:
+- User authentication/authorization (id-token + scopes + consent) is independent from transport/message protection.
+- Backend may enforce DIDComm message security (JWS/JWE) per deployment policy: `plain` / `strict` / `auto-detect`.
+
+## 1) Start individual/family organization onboarding
+
+```ts
+const started = await client.startIndividualOrganizationSimple({
+  alternateName,
+  controllerEmail,        // or controllerTelephone
+  controllerRole: 'org.hl7.v3.RoleCode|RESPRSN',
+});
+```
+
+## 2) Show offer in UI and accept
+
+```ts
+const offerId = started.offerId;
+const offerPreview = started.offerPreview;
+```
+
+## 3) Confirm order (always)
+
+```ts
+const order = await client.confirmIndividualOrganizationOrderSimple({ offerId: offerId! });
+```
+
+## 4) Configure consent/preauthorization
+
+```ts
+const consent = await client.grantProfessionalAccessSimple(
+  { tenantId, jurisdiction, sector },
+  {
+    subjectDid,
+    actor: { identifier: practitionerDid },
+    actorRole: 'Practitioner',
+    purpose: 'TREAT',
+    actions: ['organization/Composition.rs'],
+  },
+);
+```
+
+## 5) Optional: import/update index data
+
+Use your ingestion path (`/publisher/...`) and then subject-side runtime operations.
+
+## 6) Professional requests token and reads allowed resources
+
+```ts
+const smart = await client.requestSmartTokenSimple({
+  idToken: practitionerIdToken,
+  targetEndpoint: client.getEndpointId({
+    section: 'organization',
+    format: 'org.hl7.fhir.r4',
+    resourceType: 'Composition',
+    action: '_search',
+  }, practitionerDid),
+  scopes: ['organization/Composition.rs'],
+});
+```
+
+## Notes
+
+- For personal onboarding in GW, verification is integrated in the onboarding flow (`individual/org.schema/Organization/_batch` + `Order/_batch`).
+- Keep Offer/Order UX explicit even when amount is `0`.
+- Use endpoint-id selectors from `docs/ENDPOINT_ID_CATALOG.md`.

package/docs/PORTAL_BACKEND_INTEGRATION_HANDOVER.md

@@ -177,14 +177,17 @@ Even if amount is `0`, user acceptance and Order submission still happen.
 SDK method:
 - `createOrganizationEmployee(...)`
 
+Use claim constants:
+- `ClaimsPersonSchemaorg` from `gdc-common-utils-ts/constants/schemaorg`
+
 ```ts
 const employee = await client.createOrganizationEmployee(
   { tenantId, jurisdiction, sector },
   {
     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',
     },
   },
 );
@@ -217,7 +220,12 @@ SDK method:
 ```ts
 const smart = await client.requestSmartTokenSimple({
   idToken: doctorUserIdToken,
-  endpointId: 'doctor-portal',
+  targetEndpoint: client.getEndpointId({
+    section: 'organization',
+    format: 'org.hl7.fhir.r4',
+    resourceType: 'Composition',
+    action: '_search',
+  }, doctorDidWeb),
   scopes: ['organization/Composition.rs'],
 });
 ```

package/docs/PRACTITIONER_FLOW_STEP_BY_STEP.md

@@ -0,0 +1,182 @@
+# PRACTITIONER_FLOW_STEP_BY_STEP
+
+Flow for physician/practitioner employee after controller has issued `activationCode`.
+
+## Rules first
+
+- `jurisdiction` is mandatory (country context for tenant routing and authorization).
+- `activationCode` is single-use bootstrap material for identity activation.
+- Identity token endpoints and entity/business endpoints are different concerns:
+  - identity token flow path: `/host/cds-{jurisdiction}/v1/{sector}/{tenantId}/identity/auth/...`
+  - entity/business paths: `/{tenantId}/cds-{jurisdiction}/v1/{sector}/...`
+- Practitioner signs `client_assertion` with their private signing key when required by the token endpoint.
+- Message transport may also use backend wallet JWS/JWE protection (deployment policy: `plain` / `strict` / `auto-detect`).
+
+## 1) Receive activation code
+
+Input from controller flow:
+- `activationCode`
+
+Runtime context:
+
+```ts
+const profileContext = {
+  baseUrl: process.env.BASE_URL!,
+  jurisdiction: process.env.JURISDICTION!, // REQUIRED
+  sector: process.env.SECTOR || 'health-care',
+};
+
+const sessionContext = {
+  tenantId: currentSession.tenantId,
+  practitionerDidWeb: currentSession.practitioner.didWeb,
+  practitionerIdToken: currentSession.idToken,
+  practitionerPublicJwk: currentSession.practitioner.publicJwk,
+};
+```
+
+## 2) Activate device identity (DCR bootstrap)
+
+```ts
+const client = new DataspaceNodeClient({
+  baseUrl: profileContext.baseUrl,
+  ctx: {
+    tenantId: sessionContext.tenantId,
+    jurisdiction: profileContext.jurisdiction,
+    sector: profileContext.sector,
+  },
+});
+
+const device = await client.activateEmployeeDeviceWithActivationCodeSimple({
+  tenantId: sessionContext.tenantId,
+  jurisdiction: profileContext.jurisdiction,
+  sector: profileContext.sector,
+  activationCode,
+  idToken: sessionContext.practitionerIdToken,
+  dcrPayload: {
+    application_type: 'web',
+    token_endpoint_auth_method: 'private_key_jwt',
+    jwks: { keys: [sessionContext.practitionerPublicJwk] },
+  },
+});
+```
+
+## 3) Request SMART token for protected operations
+
+`targetEndpoint` is only a local token-target identifier. Authorization is defined by `scopes`.
+
+```ts
+const smart = await client.requestSmartTokenSimple({
+  tenantId: sessionContext.tenantId,
+  jurisdiction: profileContext.jurisdiction,
+  sector: profileContext.sector,
+  idToken: sessionContext.practitionerIdToken,
+  targetEndpoint: `smart:practitioner:${sessionContext.practitionerDidWeb}:ips-read`,
+  scopes: [
+    'organization/Composition.rs',
+    'organization/Consent.cruds',
+    'organization/Communication.cruds',
+  ],
+});
+```
+
+IPS note:
+- Access to IPS sections is authorized via scopes (for example `organization/Composition.rs`) and consent/policy checks.
+- Do not derive authorization from `targetEndpoint` or from a single endpoint selector.
+
+## 3.1) Where JWT signing happens (`private_key_jwt`)
+
+If your token endpoint requires `client_assertion` (`private_key_jwt`), the JWT must be signed with the practitioner's/controller's private key.
+
+Option A (recommended): SDK signs and sends `client_assertion` for you.
+
+```ts
+const token = await client.authenticateBackendSmartStandard({
+  clientId: sessionContext.practitionerDidWeb,
+  scopes: ['organization/Composition.rs'],
+  targetEndpoint: `smart:practitioner:${sessionContext.practitionerDidWeb}:ips-read`,
+  tokenUrl: `${profileContext.baseUrl}/token`,
+  audience: `${profileContext.baseUrl}/token`,
+  walletContext: {
+    tenantId: sessionContext.tenantId,
+    jurisdiction: profileContext.jurisdiction,
+    sector: profileContext.sector,
+  },
+  publicJwk: sessionContext.practitionerPublicJwk,
+});
+```
+
+Option B (manual): build/sign JWT yourself, then attach it in token request.
+
+```ts
+const now = Math.floor(Date.now() / 1000);
+const encodedHeader = base64url(JSON.stringify({
+  alg: 'ES384',
+  typ: 'JWT',
+  kid: sessionContext.practitionerPublicJwk.kid,
+}));
+const encodedPayload = base64url(JSON.stringify({
+  iss: sessionContext.practitionerDidWeb,
+  sub: sessionContext.practitionerDidWeb,
+  aud: `${profileContext.baseUrl}/token`,
+  iat: now,
+  exp: now + 300,
+  jti: crypto.randomUUID(),
+}));
+const signingInput = `${encodedHeader}.${encodedPayload}`; // what must be signed
+
+const signatureBase64Url = await externalSigner(signingInput); // integrator-managed signer
+const clientAssertion = `${encodedHeader}.${encodedPayload}.${signatureBase64Url}`;
+
+// Equivalent high-level helper style:
+// const clientAssertion = await wallet.signCompactJws({ header, claims });
+```
+
+```ts
+const tokenRequestBody = {
+  grant_type: 'client_credentials',
+  client_id: sessionContext.practitionerDidWeb,
+  scope: 'organization/Composition.rs organization/Consent.cruds organization/Communication.cruds',
+  client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+  client_assertion, // signed JWT is attached here
+};
+```
+
+Integrator note:
+- SDK can help generate/sign compact JWTs, but key custody/signature execution belongs to the integrator.
+- The signer may be wallet SDK, secure enclave, KMS, HSM, or remote signature service.
+
+```ts
+// Alternative helper form if your signer abstraction already returns compact JWS:
+const clientAssertion = await wallet.signCompactJws({
+  header: {
+    alg: 'ES384',
+    typ: 'JWT',
+    kid: sessionContext.practitionerPublicJwk.kid,
+  },
+  claims: {
+    iss: sessionContext.practitionerDidWeb,
+    sub: sessionContext.practitionerDidWeb,
+    aud: `${profileContext.baseUrl}/token`,
+    iat: now,
+    exp: now + 300,
+    jti: crypto.randomUUID(),
+  },
+});
+```
+
+For the current GW `identity/auth/_token` flow documented in this SDK, `requestSmartTokenSimple(...)` is id-token based.  
+Use `private_key_jwt` flow when your deployment exposes a standards token endpoint that requires `client_assertion`.
+
+## 4) Call protected APIs with returned bearer
+
+Use `smart.accessToken` in subsequent requests.
+
+Complete path examples:
+- exchange activation code:
+  `/host/cds-ES/v1/health-care/{tenantId}/identity/auth/_exchange`
+- DCR:
+  `/host/cds-ES/v1/health-care/{tenantId}/identity/auth/_dcr`
+- SMART token:
+  `/host/cds-ES/v1/health-care/{tenantId}/identity/auth/_token`
+- example protected entity route (if practitioner is allowed):
+  `/{tenantId}/cds-ES/v1/health-care/entity/org.schema/Employee/_search`

package/examples/e2e-bootstrap-tenant.mjs

@@ -1,4 +1,5 @@
 import { DataspaceNodeClient } from '../dist/index.js';
+import { ClaimsPersonSchemaorg } from 'gdc-common-utils-ts/constants/schemaorg';
 
 function parseCsv(value, fallback = []) {
   const items = String(value || '')
@@ -106,8 +107,8 @@ async function main() {
     {
       employeeClaims: {
         '@context': 'org.schema',
-        'org.schema.Person.email': process.env.CONTROLLER_EMAIL || 'controller@example.com',
-        'org.schema.Person.hasOccupation': process.env.CONTROLLER_ROLE || 'ISCO-08|1342',
+        [ClaimsPersonSchemaorg.email]: process.env.CONTROLLER_EMAIL || 'controller@example.com',
+        [ClaimsPersonSchemaorg.hasOccupation]: process.env.CONTROLLER_ROLE || 'ISCO-08|1342',
       },
     },
     pollOptions,

package/examples/e2e-individual-flow.mjs

@@ -1,4 +1,9 @@
 import { DataspaceNodeClient, createDidcommPlainMessage } from '../dist/index.js';
+import {
+  ClaimsOrganizationSchemaorg,
+  ClaimsPersonSchemaorg,
+  ClaimsServiceSchemaorg,
+} from 'gdc-common-utils-ts/constants/schemaorg';
 
 const baseUrl = process.env.BASE_URL || 'http://localhost:3000';
 const bearerToken = process.env.AUTH_BEARER || 'demo-token';
@@ -21,14 +26,14 @@ const payload = createDidcommPlainMessage({
           claims: {
             '@context': 'org.schema',
             '@type': 'template',
-            'org.schema.Organization.address.addressCountry': 'ES',
-            'org.schema.Organization.identifier.additionalType': 'UUID',
-            'org.schema.Organization.identifier.value': `family-${Date.now()}`,
-            'org.schema.Person.email': 'adult1@example.com',
-            'org.schema.Service.category': ctx.sector,
-            'org.schema.Service.identifier': 'did:web:api-provider.example.com',
-            'org.schema.Service.serviceType': 'http://terminology.hl7.org/CodeSystem/v3-ActReason|SRVC',
-            'org.schema.Service.termsOfService': 'https://provider.example.com/terms',
+            [ClaimsOrganizationSchemaorg.addressCountry]: 'ES',
+            [ClaimsOrganizationSchemaorg.identifierType]: 'UUID',
+            [ClaimsOrganizationSchemaorg.identifierValue]: `family-${Date.now()}`,
+            [ClaimsPersonSchemaorg.email]: 'adult1@example.com',
+            [ClaimsServiceSchemaorg.category]: ctx.sector,
+            [ClaimsServiceSchemaorg.identifier]: 'did:web:api-provider.example.com',
+            [ClaimsServiceSchemaorg.serviceType]: 'http://terminology.hl7.org/CodeSystem/v3-ActReason|SRVC',
+            [ClaimsServiceSchemaorg.termsOfService]: 'https://provider.example.com/terms',
           },
         },
       },

package/examples/host-activate-and-employee.mjs

@@ -1,4 +1,5 @@
 import { DataspaceNodeClient, createDidcommPlainMessage } from '../dist/index.js';
+import { ClaimsPersonSchemaorg } from 'gdc-common-utils-ts/constants/schemaorg';
 
 const baseUrl = process.env.BASE_URL || 'http://localhost:3000';
 const bearerToken = process.env.AUTH_BEARER || 'demo-token';
@@ -56,8 +57,8 @@ const employeePayload = createDidcommPlainMessage({
         meta: {
           claims: {
             '@context': 'org.schema',
-            'org.schema.Person.email': process.env.EMPLOYEE_EMAIL || 'doctor1@acme.org',
-            'org.schema.Person.hasOccupation': process.env.EMPLOYEE_ROLE || 'ISCO-08|2211',
+            [ClaimsPersonSchemaorg.email]: process.env.EMPLOYEE_EMAIL || 'doctor1@acme.org',
+            [ClaimsPersonSchemaorg.hasOccupation]: process.env.EMPLOYEE_ROLE || 'ISCO-08|2211',
           },
         },
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataspace-client-sdk-node",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Node.js SDK skeleton for GW/UNID DIDComm plain batch + async polling flows",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
     "build": "tsc -p tsconfig.json",
     "type-check": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test tests/*.test.mjs",
-    "example:e2e-bootstrap-tenant": "npm run build && node examples/e2e-bootstrap-tenant.mjs"
+    "example:e2e-bootstrap-tenant": "npm run build && node examples/e2e-bootstrap-tenant.mjs",
+    "test:e2e:live-gw-uc5": "npm run build && RUN_LIVE_GW_E2E=1 node --test tests/live-gw-uc5.e2e.test.mjs"
   },
   "engines": {
     "node": ">=22"
@@ -20,7 +21,7 @@
   },
   "dependencies": {
     "@noble/post-quantum": "^0.6.1",
-    "gdc-common-utils-ts": "^1.4.8",
+    "gdc-common-utils-ts": "^1.4.12",
     "node-fetch": "^3.3.2"
   }
 }