dataspace-client-sdk-node 0.1.1 → 0.2.0

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

@@ -0,0 +1,343 @@
+# Portal Backend Integration Handover
+
+Target audience: team implementing a portal backend that integrates with GW via `dataspace-client-sdk-node`.
+
+## 1) What this SDK does vs does not do
+
+`dataspace-client-sdk-node` does:
+- build GW paths
+- submit/poll async DIDComm plain flows
+- provide high-level wrappers for common UC5 steps
+
+`dataspace-client-sdk-node` does not do:
+- ICA UX orchestration in browser
+- wallet UX/signing UX for end-users
+- generic OIDC4VP UI flow control
+
+`vp_token` source:
+- produced by your identity/wallet flow (usually ICA/OIDC4VP side)
+- then passed to backend and used in GW `_activate`
+
+## 2) Responsibility split
+
+1. Portal frontend:
+   - UX, contract signature flow, identity/wallet flow
+   - obtains `vpToken`
+   - sends onboarding payloads to portal backend
+2. Portal backend (this integration):
+   - uses this SDK to call GW
+   - executes end-to-end business order and polling
+3. GW backend:
+   - validates proofs, processes onboarding, authorization and data access contracts
+
+### Recommended SDK initialization
+
+Initialize once with default context to avoid repeating `tenantId/jurisdiction/sector`:
+
+```ts
+const client = new DataspaceNodeClient({
+  baseUrl,
+  bearerToken,
+  ctx: { tenantId, jurisdiction, sector },
+});
+```
+
+## 3) Legal organization onboarding (complete, numbered)
+
+Canonical order:
+`_verify -> _activate -> Offer -> Order -> DCR -> token`
+
+### Step 1. Frontend obtains `vpToken`
+
+Expected backend input:
+- `jurisdiction` (required)
+- `sector` (required)
+- `vpToken` (required)
+- `numberOfMembers` (optional, generic; default `2`)
+
+Notes:
+- `jurisdiction` is explicit route context. It is not inferred from VAT.
+- `sector` is explicit route context. It is not inferred from DID.
+
+Set once in client:
+
+```ts
+client.setContextOrg({ tenantId, jurisdiction, sector });
+client.setDefaultTimeoutSeconds(120);
+client.setDefaultIntervalSeconds(2);
+```
+
+### Step 2. Backend activates organization in GW
+
+Preferred SDK method (friendly):
+- `activateOrganizationInGatewaySimple(...)`
+
+```ts
+const activation = await client.activateOrganizationInGatewaySimple({
+  vpToken,
+  serviceProviderDidWeb, // or serviceProviderUrl (SDK maps URL -> did:web:<host>)
+  controllerEmail, // or controllerTelephone
+  controllerRole,  // e.g. ISCO-08|1112
+  numberOfMembers,     // optional, default 2
+});
+```
+
+Advanced equivalent (less friendly, same behavior):
+- `activateOrganizationInGatewayFromIcaProof(ctx, input, pollOptions)`
+
+```ts
+const activation = await client.activateOrganizationInGatewayFromIcaProof(
+  { jurisdiction, sector },
+  {
+    vpToken,
+    numberOfMembers,
+  },
+  { timeoutMs: 120000, intervalMs: 2000 },
+);
+```
+
+Default behavior:
+- if `numberOfMembers` is not provided, SDK defaults to `2`
+  (controller + one operational employee).
+
+### Step 3. Backend extracts `offerId` from `_activate` response
+
+Use SDK helper:
+- `client.getOfferIdFromResponse(activation)`
+
+Extract offer preview fields from the first DIDComm entry via:
+- `client.getFirstDidcommDataEntryFromResponse(activation)`
+- or directly as UI object: `client.getOfferPreviewFromResponse(activation)`
+
+Expected offer claims (GW examples/contracts):
+- `org.schema.Offer.identifier`
+- `org.schema.Offer.price`
+- `org.schema.Offer.priceCurrency`
+- `org.schema.Offer.eligibleQuantity.value`
+- `org.schema.Offer.itemOffered.name`
+- `org.schema.Offer.itemOffered.sku`
+- `org.schema.Offer.acceptedPaymentMethod`
+- `org.schema.Offer.checkoutPageURLTemplate`
+
+Recommended UI mapping helper:
+- `client.getOfferPreviewFromResponse(activation)` ->
+  `{ offerId, amount, currency, seats, planName, sku, paymentMethod, checkoutUrl }`
+
+### Step 4. Backend executes legal organization order (always)
+
+Even with `0` amount, Order is still required.
+
+Preferred SDK method (friendly):
+- `confirmLegalOrganizationOrderSimple(...)`
+
+```ts
+const legalOrgOrder = await client.confirmLegalOrganizationOrderSimple({
+  offerId,
+});
+```
+
+Advanced equivalent (less friendly):
+- `hostRegistryOrderBatchPath(...)`
+- `hostRegistryOrderPollPath(...)`
+- `submitAndPoll(...)`
+
+Example:
+
+```ts
+const offerId = client.getOfferIdFromResponse(activation);
+if (!offerId) throw new Error('Offer id missing in activation response.');
+
+const legalOrgOrder = await client.submitAndPoll(
+  client.hostRegistryOrderBatchPath({ jurisdiction, sector }),
+  client.hostRegistryOrderPollPath({ jurisdiction, sector }),
+  {
+    thid: `order-${Date.now()}`,
+    body: {
+      data: [{
+        type: 'Organization-order-request-v1.0',
+        meta: { claims: { 'Order.acceptedOffer.identifier': offerId } },
+      }],
+    },
+  },
+);
+```
+
+### Step 4.1 UX requirement: show offer summary before order
+
+Portal UX should present:
+1. Offer identifier
+2. Total amount and currency (if provided)
+3. Product/license summary
+4. Acceptance action (user confirms, then backend sends Order)
+
+Even if amount is `0`, user acceptance and Order submission still happen.
+
+### Step 5. Backend creates doctor employee
+
+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',
+      [ClaimsPersonSchemaorg.email]: 'doctor@example.com',
+      [ClaimsPersonSchemaorg.hasOccupation]: 'ISCO-08|2211',
+    },
+  },
+);
+```
+
+### Step 6. Backend activates doctor device (DCR path)
+
+SDK method:
+- `activateEmployeeDeviceWithActivationCodeSimple(...)` (recommended)
+- `activateEmployeeDeviceWithActivationCode(...)` (advanced)
+
+```ts
+const device = await client.activateEmployeeDeviceWithActivationCodeSimple({
+  activationCode,
+  idToken: doctorUserIdToken,
+  dcrPayload: {
+    application_type: 'web',
+    token_endpoint_auth_method: 'private_key_jwt',
+    jwks: { keys: [doctorPublicJwk] },
+  },
+});
+```
+
+### Step 7. Backend obtains SMART token for authorized access
+
+SDK method:
+- `requestSmartTokenSimple(...)` (recommended)
+- `requestSmartToken(...)` (advanced)
+
+```ts
+const smart = await client.requestSmartTokenSimple({
+  idToken: doctorUserIdToken,
+  targetEndpoint: client.getEndpointId({
+    section: 'organization',
+    format: 'org.hl7.fhir.r4',
+    resourceType: 'Composition',
+    action: '_search',
+  }, doctorDidWeb),
+  scopes: ['organization/Composition.rs'],
+});
+```
+
+## 4) Individual subject onboarding + access grant (doctor reads index)
+
+### Step 8. Register personal organization + family order
+
+SDK method:
+- `bootstrapSubjectOrganizationIndex(...)`
+
+```ts
+const subjectBootstrap = await client.bootstrapSubjectOrganizationIndex(
+  { tenantId, jurisdiction, sector },
+  {
+    registrationPayload,
+    confirmationPayload, // include accepted offer id
+  },
+);
+```
+
+### Step 9. Grant doctor consent to read subject index/data
+
+SDK method:
+- `grantProfessionalAccessSimple(...)`
+
+```ts
+await client.grantProfessionalAccessSimple(
+  { tenantId, jurisdiction, sector },
+  {
+    subjectDid: subjectDidWeb,
+    actor: { identifier: doctorDidWeb },
+    actorRole: 'Practitioner',
+    purpose: 'TREAT',
+    actions: ['organization/Composition.rs'],
+  },
+);
+```
+
+### Step 10. Doctor uses SMART token to read permitted resources
+
+Use bearer returned by step 7 in subsequent resource calls.
+
+## 5) Minimal backend request contracts from frontend
+
+Legal activate request:
+
+```json
+{
+  "jurisdiction": "ES",
+  "sector": "health-care",
+  "vpToken": "<vp_token>"
+}
+```
+
+Personal register request:
+
+```json
+{
+  "tenantId": "acme",
+  "jurisdiction": "ES",
+  "sector": "health-care",
+  "registrationPayload": {},
+  "confirmationPayload": {}
+}
+```
+
+## 6) Primary SDK methods checklist
+
+1. `activateOrganizationInGatewayFromIcaProof`
+2. extract `offerId` from activation response
+3. `submitAndPoll` + `hostRegistryOrderBatchPath` / `hostRegistryOrderPollPath`
+4. `createOrganizationEmployee`
+5. `activateEmployeeDeviceWithActivationCodeSimple`
+6. `requestSmartTokenSimple`
+7. `bootstrapSubjectOrganizationIndex`
+8. `grantProfessionalAccessSimple`
+
+## 7) Async/poll UX pattern (important)
+
+All onboarding operations are async (`submit` + `poll`).
+
+Recommended backend pattern per step:
+1. Emit status `submitted` after POST returns `202`.
+2. Poll until completion.
+3. Emit status `completed` or `failed` with diagnostics.
+
+Polling interval behavior:
+- if caller sets `intervalMs`, that value is forced.
+- if caller does not set `intervalMs`, SDK uses backend `Retry-After` when present.
+- fallback default is `2000ms`.
+
+Recommended portal UX states:
+1. `Verifying identity proof`
+2. `Activating organization`
+3. `Offer available` (show price/summary)
+4. `Waiting for acceptance`
+5. `Submitting order`
+6. `Creating employee`
+7. `Activating device`
+8. `Token ready`
+
+Implementation note:
+- If you need real-time UX updates, expose backend progress via SSE/WebSocket.
+- If not, frontend can poll your backend orchestration endpoint for step status.
+
+## 8) References
+
+- `docs/BACKEND_NODE_INTEGRATION.md`
+- `docs/REACT_WEB_INTEGRATION.md`
+- `docs/DEVELOPER_USE_CASES.md`
+- `docs/API.md`
+- `examples/e2e-bootstrap-tenant.mjs`
+- `tests/uc5-org-onboarding.flow.test.mjs`
+- `tests/uc5-subject-data.flow.test.mjs`

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/docs/REACT_WEB_INTEGRATION.md

@@ -0,0 +1,72 @@
+# React Web Integration
+
+This guide is frontend-only.  
+Backend SDK usage is documented in `docs/BACKEND_NODE_INTEGRATION.md`.
+
+## 1. What the React app does
+
+1. Run ICA UX flow and obtain `vpToken`.
+2. Send onboarding payloads to your backend.
+3. Show progress and status from backend responses.
+
+React does not call privileged GW onboarding routes directly.
+
+## 2. Legal onboarding payload sent by frontend
+
+Minimum payload to backend endpoint `/api/onboarding/legal/activate`:
+
+```json
+{
+  "jurisdiction": "ES",
+  "sector": "health-care",
+  "vpToken": "<vp_token>"
+}
+```
+
+Notes:
+- `jurisdiction` is explicit route context. Do not infer from VAT.
+- `sector` is explicit route context. Do not infer from DID.
+- `organizationVc` / `legalRepresentativeVc` can be sent only for legacy compatibility.
+
+## 3. Frontend code example
+
+```ts
+export async function activateLegalOrganization(input: {
+  jurisdiction: string;
+  sector: string;
+  vpToken: string;
+}) {
+  const response = await fetch('/api/onboarding/legal/activate', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(input),
+  });
+  if (!response.ok) throw new Error(`Activation failed: ${response.status}`);
+  return response.json();
+}
+```
+
+## 4. Personal/family onboarding from frontend
+
+```ts
+export async function registerPersonalOrganization(payload: {
+  tenantId: string;
+  jurisdiction: string;
+  sector: string;
+  registrationPayload: unknown;
+  confirmationPayload?: unknown;
+}) {
+  const response = await fetch('/api/onboarding/personal/register', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+  if (!response.ok) throw new Error(`Personal onboarding failed: ${response.status}`);
+  return response.json();
+}
+```
+
+## 5. Backend document
+
+For exact SDK methods and backend implementation steps, use:
+- `docs/BACKEND_NODE_INTEGRATION.md`

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,