dataspace-client-sdk-node 0.1.1

package/docs/DATA_MODEL_ALIGNMENT.md

@@ -0,0 +1,31 @@
+# Data Model Alignment (GW + Chat + SDK)
+
+Alignment reference for SDK consumers and backend integrators.
+
+## Business vs Infra Sector
+
+- Infra host onboarding uses network routing sector (`HOST_REGISTRY_SECTOR`).
+- Tenant runtime model uses business sector (`SECTOR`).
+- Canonical tenant vault ID:
+  - `<SECTOR>_<tenantId>`
+  - Example: `health-care_acme`
+
+## Individual Organization Model
+
+- Section: `<prefix>_individual`
+- Doc ID: `org.schema.Organization.identifier.value` (UUID)
+
+## Search Contract (`searchFamilyOrganization`)
+
+- Input mapping:
+  - `controllerPhone` -> `org.schema.Organization.owner.telephone`
+  - `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`
+

package/docs/DATA_PLANES_SCOPE_MATRIX.md

@@ -0,0 +1,51 @@
+# Data Planes And Scope Matrix (SDK Guide)
+
+Canonical reference for scope semantics and resource placement in the Node SDK.
+
+Primary backend source: `gdc-unid-node-ts/docs/02-API-AND-ENDPOINTS/02.F-DATA-PLANES-SCOPE-MATRIX.md`.
+
+## Quick rules
+
+1. Admin/legal plane
+- Scopes: `org.schema/Organization.<cruds>`, `org.schema/Person.<cruds>`.
+- Use for legal/admin governance and registry/discovery metadata.
+
+2. Subject data plane
+- Scopes: `organization/<ResourceType>.<cruds|rs|rus>`.
+- Use for private subject operations (`Person`, `RelatedPerson`, `Appointment`, `AppointmentResponse`, `Composition`, etc.).
+
+3. Catalog publication
+- Public/legal metadata: `org.schema` plane.
+- Private subject data: never publish raw records in catalog.
+
+## Resource matrix
+
+| Intent | Scope |
+|---|---|
+| Subject private person profile | `organization/Person.rus` |
+| Emergency contacts | `organization/RelatedPerson.cruds` |
+| Appointments | `organization/Appointment.cruds` |
+| Appointment responses | `organization/AppointmentResponse.cruds` |
+| Subject index composition read | `organization/Composition.rs` |
+
+## Notification phone policy
+
+1. Subject notification routing (caregiver/spouse/multi-contact) belongs to private data plane and should be stored in `organization/Organization`.
+2. Subject own phone belongs to `organization/Person`.
+3. Emergency contacts belong to `organization/RelatedPerson`.
+4. Do not model these private routing contacts as legal/public `org.schema` publication data.
+
+## Recommended default scope bundle for subject apps
+
+- `organization/Person.rus`
+- `organization/RelatedPerson.cruds`
+- `organization/Appointment.cruds`
+- `organization/AppointmentResponse.cruds`
+- `organization/Composition.rs`
+
+## Test checklist
+
+1. Token minted with only `org.schema/*` cannot operate on `organization/*` resources.
+2. Token minted with only `organization/*` cannot mutate legal/admin `org.schema/*` resources.
+3. Scope propagation in flow tests:
+- bootstrap -> consent -> request token -> subject operation.

package/docs/DEVELOPER_USE_CASES.md

@@ -0,0 +1,253 @@
+# Developer Use-Case Cookbook (Node SDK)
+
+This guide provides exact method calls for real integration flows.
+
+Normative scope/resource placement matrix:
+- [DATA_PLANES_SCOPE_MATRIX.md](DATA_PLANES_SCOPE_MATRIX.md)
+
+SDK: `dataspace-client-sdk-node` (`DataspaceNodeClient`)
+
+## Base Setup
+
+```ts
+import { DataspaceNodeClient } from 'dataspace-client-sdk-node';
+
+const client = new DataspaceNodeClient({
+  baseUrl: process.env.GW_BASE_URL!,
+  bearerToken: process.env.GW_BEARER_TOKEN, // controller/professional token depending on step
+});
+
+const ctx = {
+  tenantId: 'acme',
+  jurisdiction: 'ES',
+  sector: 'health-care',
+};
+```
+
+## UC5.1 Subject bootstrap (personal organization)
+
+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)`
+
+```ts
+const result = await client.bootstrapSubjectOrganizationIndex(ctx, {
+  registrationPayload: {
+    body: {
+      data: [{ type: 'Family-registration-form-v1.0', meta: { claims: { '@context': 'org.schema' } } }],
+    },
+  },
+  confirmationPayload: {
+    body: {
+      data: [{ type: 'Family-order-request-v1.0', meta: { claims: { 'Order.acceptedOffer.identifier': 'urn:offer:123' } } }],
+    },
+  },
+});
+```
+
+## UC5.2 Legal organization activation in GW (from ICA proof)
+
+Method: `activateOrganizationInGatewayFromIcaProof(hostCtx, input)`
+
+```ts
+const activation = await client.activateOrganizationInGatewayFromIcaProof(
+  { jurisdiction: 'ES', sector: 'health-care' },
+  {
+    vpToken: process.env.ICA_VP_TOKEN!,
+    organizationVc: process.env.ICA_ORG_VC_JWT,
+    legalRepresentativeVc: process.env.ICA_LEGAL_REP_VC_JWT,
+    regulatoryEvidence: { sanitaryRegister: 'REG-123' },
+  },
+);
+```
+
+## UC5.3 Create employee / professional license
+
+Method: `createOrganizationEmployee(ctx, input)`
+
+```ts
+await client.createOrganizationEmployee(ctx, {
+  employeeClaims: {
+    '@context': 'org.schema',
+    'org.schema.Person.email': 'doctor@example.com',
+    'org.schema.Person.hasOccupation': 'ISCO-08|2211',
+  },
+});
+```
+
+## UC5.4 Activate employee device
+
+Method: `activateEmployeeDeviceWithActivationCode(ctx, input)`
+
+```ts
+const device = await client.activateEmployeeDeviceWithActivationCode(ctx, {
+  activationCode: 'ACT-123456',
+  idToken: process.env.USER_ID_TOKEN!,
+  dcrPayload: {
+    application_type: 'web',
+    token_endpoint_auth_method: 'private_key_jwt',
+    jwks: { keys: [] },
+  },
+});
+```
+
+## UC5.5 Import IPS/FHIR and update index
+
+Method: `importIpsOrFhirAndUpdateIndex(ctx, input)`
+
+```ts
+await client.importIpsOrFhirAndUpdateIndex(ctx, {
+  format: 'r4',
+  compositionPayload: {
+    body: {
+      data: [{ type: 'Composition-import-request-v1.0', meta: { claims: { subject: 'did:web:subject.example.com' } } }],
+    },
+  },
+});
+```
+
+## UC5.6 Consent then SMART token (real decoupled flow)
+
+Step 1 method: `grantProfessionalAccessSimple(ctx, input)`  
+Step 2 method: `requestSmartToken(input)`
+
+Domain note: the protected context is modeled as organization (including personal organizations with controller + subject/person/patient members).
+
+Scope namespace note:
+- Organization administration (non-FHIR): `org.schema/Organization.<cruds>`, `org.schema/Person.<cruds>`
+- Subject/personal-organization data (FHIR): `organization/<ResourceType>.<cruds|rs>` with optional `?subject=<did:web:...>`
+
+```ts
+const consent = await client.grantProfessionalAccessSimple(ctx, {
+  subjectPhone: '+34600111222',
+  subjectGivenName: 'Ana',
+  actor: { identifier: 'did:web:hospital.example.com' },
+  actorRole: 'Practitioner',
+  purpose: 'TREAT',
+  actions: ['organization/Composition.rs'],
+});
+
+const token = await client.requestSmartToken({
+  endpointId: 'professional-app',
+  scopes: ['organization/Composition.rs'],
+  exchangePayload: { grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange' },
+  path: '/token',
+});
+```
+
+## UC5.7 Generate digital twin
+
+Method: `generateDigitalTwinFromSubjectData(ctx, input)`
+
+```ts
+await client.generateDigitalTwinFromSubjectData(ctx, {
+  format: 'r4',
+  compositionPayload: {
+    body: {
+      data: [{ type: 'DigitalTwin-composition-request-v1.0', meta: { claims: { source: 'subject-index' } } }],
+    },
+  },
+});
+```
+
+## Additional consent actor patterns
+
+Important: canonical claim key is `Consent.actor-identifier`.
+`grantProfessionalAccessSimple` accepts convenience aliases and resolves them into that canonical identifier.
+
+Action semantics note:
+- Avoid generic actions like `access` or `read`.
+- Use canonical operation strings aligned with protected resource contracts/scopes (for example `organization/Composition.rs`, `organization/Appointment.cruds`).
+
+### A) Actor by canonical `identifier` + role (recommended)
+
+```ts
+await client.grantProfessionalAccessSimple(ctx, {
+  subjectDid: 'did:web:subject.example.com',
+  actor: { identifier: 'did:web:org.example.com' },
+  actorRole: 'Practitioner',
+  purpose: 'TREAT',
+  actions: ['organization/Composition.rs'],
+});
+```
+
+### B) Actor by organization URL/domain or NIF + role
+
+```ts
+await client.grantProfessionalAccessSimple(ctx, {
+  subjectDid: 'did:web:subject.example.com',
+  actor: { url: 'org.example.com' }, // accepts bare domain or full URL; resolves to did:web:org.example.com
+  actorRole: 'Practitioner',
+  purpose: 'CARE',
+  actions: ['organization/Appointment.cruds'],
+});
+```
+
+```ts
+await client.grantProfessionalAccessSimple(ctx, {
+  subjectDid: 'did:web:subject.example.com',
+  actor: { organizationTaxId: 'B12345678' }, // maps to urn:taxid:B12345678
+  actorRole: 'Practitioner',
+  purpose: 'CARE',
+  actions: ['organization/RelatedPerson.cruds'],
+});
+```
+
+### C) Actor by email/phone + role
+
+```ts
+await client.grantProfessionalAccessSimple(ctx, {
+  subjectDid: 'did:web:subject.example.com',
+  actor: { email: 'doctor@example.com' },
+  actorRole: 'Practitioner',
+  purpose: 'TREAT',
+  actions: ['organization/Composition.rs'],
+});
+```
+
+```ts
+await client.grantProfessionalAccessSimple(ctx, {
+  subjectDid: 'did:web:subject.example.com',
+  actor: { phone: '+34600111222' }, // maps to urn:tel:+34600111222
+  actorRole: 'Practitioner',
+  purpose: 'TREAT',
+  actions: ['organization/AppointmentResponse.cruds'],
+});
+```
+
+### D) Jurisdiction + role (explicit claims)
+
+`grantProfessionalAccessSimple` does not currently expose a `jurisdiction` field.  
+For jurisdiction-based actor identifiers, submit explicit claims:
+
+```ts
+await client.submitAndPoll(
+  client.individualConsentR4BatchPath(ctx),
+  client.individualConsentR4PollPath(ctx),
+  {
+    thid: 'consent-jurisdiction-001',
+    body: {
+      data: [{
+        type: 'Consent-grant-request-v1.0',
+        meta: {
+          claims: {
+            '@context': 'org.hl7.fhir.api',
+            'Consent.decision': 'permit',
+            'Consent.subject': 'did:web:subject.example.com',
+            'Consent.actor-identifier': 'urn:jurisdiction:ES',
+            'Consent.actor-role': 'Practitioner',
+            'Consent.purpose': 'TREAT',
+            'Consent.action': 'LOINC|48765-2,LOINC|10160-0',
+          },
+        },
+      }],
+    },
+  },
+);
+```
+
+## Traceability contract (FHIR + claims)
+
+- FHIR resource identity: `resource.id` remains UUID.
+- FHIR version traceability: `resource.meta.versionId` stores CID of canonical FHIR resource version.
+- Claims traceability: `grantProfessionalAccessSimple(...)` now emits `resource.meta.claims["@id"]` as CID of canonical claims (excluding `@context`, `@type`, `@id`).

package/docs/E2E_BOOTSTRAP.md

@@ -0,0 +1,54 @@
+# E2E Bootstrap (Tenant + Controller)
+
+This flow prepares a tenant for frontend E2E tests (`apptemplate`) after ICA proof is available.
+
+## 1) What the script does
+
+Script: `examples/e2e-bootstrap-tenant.mjs`
+
+1. Authenticates to GW (`AUTH_MODE=demo|pkce`).
+2. Calls host activation endpoint (`Organization/_activate`) with `vp_token` and optional ICA JWT VCs.
+3. Optionally creates a controller employee in the tenant (`Employee/_batch`).
+
+## 2) Run command
+
+```bash
+npm run example:e2e-bootstrap-tenant
+```
+
+## 3) Required env
+
+- `BASE_URL` (default `http://localhost:3000`)
+- `VP_TOKEN` (required)
+
+Auth-specific:
+
+- Demo:
+  - `AUTH_MODE=demo` (default)
+  - `AUTH_BEARER` (optional, default `demo-token`)
+- PKCE:
+  - `AUTH_MODE=pkce`
+  - `GW_API_KEY`
+  - `GW_CONTROLLER_PUBLIC_JWK_SIGN` (JSON object)
+
+Routing:
+
+- `JURISDICTION` (default `ES`)
+- `HOST_REGISTRY_SECTOR` (default `test`)
+- `TENANT_ID` (default `acme`)
+- `SECTOR` (default `health-care`)
+
+Optional:
+
+- `ORGANIZATION_VC_JWT`
+- `LEGAL_REPRESENTATIVE_VC_JWT`
+- `CREATE_CONTROLLER_EMPLOYEE=true`
+- `CONTROLLER_EMAIL`
+- `CONTROLLER_ROLE`
+
+## 4) Typical sequence
+
+1. Start local stack (GW + ICA + dependencies).
+2. Obtain `vp_token` from ICA flow (frontend or node).
+3. Run this bootstrap script.
+4. Run `apptemplate` integration profile (`local-demo`, `local-docker`, or `cloud-staging`).

package/docs/TODO_SMART_EHR_COMPAT.md

@@ -0,0 +1,58 @@
+# TODO: SMART EHR Compatibility (patient scope alias)
+
+Status: pending
+Owner: TBD
+Priority: medium
+
+## Goal
+Support EHR integrations that request SMART scopes using `patient/*` without custom `?subject=...`, while preserving the current gateway profile based on subject-pinned scopes.
+
+## Current state (today)
+- Gateway profile expects subject pinning through scope query parameter (`?subject=...`).
+- Current token flow uses actor identity in `sub` and subject context extracted from scope.
+- This differs from SMART App Launch standard patient context behavior.
+
+## Target behavior
+1. Keep current gateway profile (`organization/*?subject=...`) for existing clients.
+2. Add compatibility profile for SMART EHR (`patient/*`) without requiring query `subject`.
+3. Resolve patient context via SMART launch context (authorize -> token `patient` context), not via custom query-only requirement.
+4. Keep single-subject enforcement per token request.
+
+## Proposed switch
+- Environment flag (default enabled compatibility):
+  - `DISABLE_PATIENT_SCOPE_ALIAS=false` (default)
+  - `DISABLE_PATIENT_SCOPE_ALIAS=true` disables alias compatibility
+
+## Implementation TODO
+1. Scope parser
+- Accept `patient/*` root scopes when alias compatibility is enabled.
+- Normalize internally to canonical authorization checks.
+
+2. Subject/patient context resolution
+- Priority order:
+  1) launch context patient id (SMART standard)
+  2) explicit `?subject=...` (gateway profile)
+- Reject when no resolvable subject context exists.
+
+3. Token payload contract
+- Include/propagate patient context field consistent with SMART expectations.
+- Preserve actor identity semantics already used by gateway.
+
+4. Policy checks
+- Ensure consent/rule lookup uses resolved subject context.
+- Enforce single-subject invariant.
+
+5. Documentation
+- Add compatibility matrix:
+  - SMART standard mode (launch/patient context)
+  - Gateway mode (scope subject pinning)
+- Clarify required fields per mode.
+
+6. Tests
+- Unit tests: scope parsing + subject resolution matrix.
+- Integration tests: EHR-style `patient/*` and gateway-style `organization/*?subject=...`.
+- Negative tests: missing subject context, mixed-subject scopes.
+
+## Out of scope (for this TODO)
+- Full redesign of authorization model.
+- Breaking changes in existing gateway clients.

package/examples/backend-pkce-auth.mjs

@@ -0,0 +1,119 @@
+/**
+ * Example: identity-exchange.v1 backend PKCE auth (Node SDK)
+ *
+ * Demonstrates authenticateBackendPkceAndExchange — the full B2B auth flow:
+ *   1. ICA DCR: bind API key to service public JWK
+ *   2. PKCE code: S256 challenge
+ *   3. PKCE token: code + verifier → id_token
+ *   4. Exchange: id_token → SMART bearer
+ *
+ * Node.js equivalent of Python connector_sdk `authenticate_backend_pkce_and_exchange`.
+ *
+ * Prerequisites:
+ *   - Tenant org activated in the GW (registry/org.schema/Organization/_activate with ICA VC)
+ *   - API key issued by ICA with required scopes
+ *   - Service key pair (EC P-384 recommended); only the public JWK is sent to the GW
+ *
+ * Environment variables:
+ *   BASE_URL        GW base URL (e.g. http://localhost:3000)
+ *   GW_API_KEY      API key issued by ICA for this service
+ *   GW_PUBLIC_JWK   JSON-serialised service public JWK (EC P-384)
+ *   TENANT_ID       Tenant org id (e.g. acme)
+ *   JURISDICTION    Jurisdiction code (e.g. ES)
+ *   SECTOR          Sector code (e.g. health-care)
+ *   GW_AUTH_BEARER  (optional) Static bearer for SECURITY_MODE=demo — skips the full flow
+ *
+ * Run (production flow):
+ *   BASE_URL="https://gw.example.com" \
+ *   GW_API_KEY="<api-key>" \
+ *   GW_PUBLIC_JWK='{"kty":"EC","crv":"P-384","x":"...","y":"..."}' \
+ *   TENANT_ID="acme" JURISDICTION="ES" SECTOR="health-care" \
+ *   node examples/backend-pkce-auth.mjs
+ *
+ * Run (demo/local bypass — SECURITY_MODE=demo):
+ *   BASE_URL="http://localhost:3000" GW_AUTH_BEARER="demo-token" \
+ *   node examples/backend-pkce-auth.mjs
+ */
+
+import { DataspaceNodeClient } from '../dist/index.js';
+
+// ---- Demo bypass --------------------------------------------------------
+// If GW_AUTH_BEARER is set (SECURITY_MODE=demo), skip the full PKCE flow.
+const staticBearer = process.env.GW_AUTH_BEARER;
+if (staticBearer) {
+  console.log('[demo] Using static GW_AUTH_BEARER — skipping identity-exchange.v1 flow.');
+  const client = new DataspaceNodeClient({
+    baseUrl: process.env.BASE_URL || 'http://localhost:3000',
+    bearerToken: staticBearer,
+  });
+  console.log('[demo] Client ready. bearerToken set from env.');
+  // eslint-disable-next-line no-process-exit
+  process.exit(0);
+}
+
+// ---- Production flow ----------------------------------------------------
+const baseUrl = process.env.BASE_URL;
+const apiKey = process.env.GW_API_KEY;
+const publicJwkRaw = process.env.GW_PUBLIC_JWK;
+
+if (!baseUrl || !apiKey || !publicJwkRaw) {
+  console.error('Required env vars: BASE_URL, GW_API_KEY, GW_PUBLIC_JWK');
+  console.error('Or set GW_AUTH_BEARER for demo/local bypass.');
+  process.exit(1);
+}
+
+const controllerPublicJwk = JSON.parse(publicJwkRaw);
+
+const ctx = {
+  tenantId: process.env.TENANT_ID || 'acme',
+  jurisdiction: process.env.JURISDICTION || 'ES',
+  sector: process.env.SECTOR || 'health-care',
+};
+
+// Client without bearer — auth flow will obtain it.
+const client = new DataspaceNodeClient({ baseUrl });
+
+console.log('[auth] Starting identity-exchange.v1 backend PKCE flow...');
+console.log('[auth] ctx:', ctx);
+console.log('[auth] apiKey prefix:', apiKey.slice(0, 8) + '...');
+
+const auth = await client.authenticateBackendPkceAndExchange({
+  ctx,
+  apiKey,
+  controllerPublicJwk,
+  scopes: ['onboarding', 'family-registration', 'license-order'],
+  endpointId: 'chatbot-main',
+  // codeVerifier: optional — auto-generated as randomUUID() if not provided
+  pollOptions: { timeoutMs: 60_000, intervalMs: 2_000 },
+});
+
+if (auth.status === 'failed') {
+  console.error(`[auth] FAILED at step: ${auth.step}`);
+  process.exit(1);
+}
+
+console.log(`[auth] Status: ${auth.status}`);  // 'fetched' or 'cached'
+console.log(`[auth] Token type: ${auth.tokenType}`);
+console.log(`[auth] Scopes granted: ${auth.scopes.join(' ')}`);
+console.log(`[auth] Bearer (truncated): ${auth.accessToken.slice(0, 20)}...`);
+
+// ---- Use the bearer for subsequent SDK calls ----------------------------
+const authedClient = new DataspaceNodeClient({
+  baseUrl,
+  bearerToken: auth.accessToken,
+});
+
+// Example: submit a family registration draft (DIDComm plain)
+// import { createDidcommPlainMessage } from '../dist/index.js';
+// const payload = createDidcommPlainMessage({ iss: ..., aud: ..., body: { data: [...] } });
+// const result = await authedClient.submitAndPoll(
+//   authedClient.individualFamilyOrganizationBatchPath(ctx),
+//   authedClient.individualFamilyOrganizationPollPath(ctx),
+//   payload,
+// );
+// console.log(result.poll.status, result.poll.body);
+
+// ---- Cache check --------------------------------------------------------
+// On subsequent calls, getCachedBearerToken avoids re-running the flow:
+const cached = client.getCachedBearerToken('chatbot-main');
+console.log(`[cache] Cached bearer available: ${cached !== undefined}`);

package/examples/conversion-upload.mjs

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { DataspaceNodeClient } from '../dist/index.js';
+
+const baseUrl = process.env.BASE_URL || 'http://localhost:3000';
+const bearerToken = process.env.AUTH_BEARER || 'demo-token';
+
+const tenantId = process.env.TENANT_ID || 'acme';
+const jurisdiction = process.env.JURISDICTION || 'ES';
+const sector = process.env.SECTOR || 'animal-care';
+const softwareId = process.env.SOFTWARE_ID || 'excel-adapter';
+const sourceFormat = process.env.SOURCE_FORMAT || 'xlsx';
+const filePath = process.env.SOURCE_FILE;
+
+if (!filePath) {
+  throw new Error('Missing SOURCE_FILE env var (path to excel/csv file).');
+}
+
+const client = new DataspaceNodeClient({ baseUrl, bearerToken });
+const ctx = { tenantId, jurisdiction, sector };
+
+const uploadPath = client.conversionUploadPath(ctx, softwareId, sourceFormat);
+const pollPath = client.conversionUploadPollPath(ctx, softwareId, sourceFormat);
+
+const fileName = basename(filePath);
+const bytes = await readFile(filePath);
+
+const submit = await client.uploadConversionFile({
+  path: uploadPath,
+  fileName,
+  fileContent: bytes,
+  fields: {
+    // Optional provider-specific fields. Keep/remove depending on DataConv API contract.
+    mode: process.env.CONVERSION_MODE || 'didcomm-plain',
+  },
+});
+
+console.log('Upload submit:', JSON.stringify(submit, null, 2));
+
+const thid =
+  process.env.THID ||
+  submit.body?.thid ||
+  submit.body?.body?.thid ||
+  submit.body?.data?.thid;
+
+if (!thid) {
+  console.log('No thid found in upload response. If your DataConv API is synchronous, stop here.');
+  process.exit(0);
+}
+
+const poll = await client.pollUntilComplete(pollPath, { thid }, { timeoutMs: 120000, intervalMs: 5000 });
+console.log('Upload poll:', JSON.stringify(poll, null, 2));