dataspace-client-sdk-node 0.1.2 → 0.2.0

package/tests/fixtures/ica-vp-minimal.json

@@ -0,0 +1,67 @@
+{
+  "iss": "did:web:controller.example.org",
+  "sub": "did:web:controller.example.org",
+  "aud": "did:web:host.example.com",
+  "vp": {
+    "@context": [
+      "https://www.w3.org/ns/credentials/v2"
+    ],
+    "type": [
+      "VerifiablePresentation"
+    ],
+    "holder": "did:web:controller.example.org",
+    "verifiableCredential": [
+      {
+        "@context": [
+          "https://www.w3.org/ns/credentials/v2",
+          "https://schema.org"
+        ],
+        "type": [
+          "VerifiableCredential",
+          "OrganizationCredential"
+        ],
+        "issuer": "did:web:localhost%3A3310",
+        "credentialSubject": {
+          "id": "did:web:globaldatacare.es:onehealth:organization:taxid:VATES-B00000000",
+          "@type": "Organization",
+          "legalName": "Example Data Provider SL",
+          "taxID": "VATES-B00000000",
+          "sameAs": "did:web:provider.example.org",
+          "url": "provider.example.org",
+          "alternateName": "example-provider",
+          "identifier": "did:web:globaldatacare.es:onehealth:organization:taxid:VATES-B00000000",
+          "identifierType": "TAX",
+          "identifierValue": "VATES-B00000000",
+          "address": {
+            "@type": "PostalAddress",
+            "addressCountry": "ES"
+          }
+        }
+      },
+      {
+        "@context": [
+          "https://www.w3.org/ns/credentials/v2",
+          "https://schema.org"
+        ],
+        "type": [
+          "VerifiableCredential",
+          "PersonCredential",
+          "LegalRepresentativeCredential"
+        ],
+        "issuer": "did:web:localhost%3A3310",
+        "credentialSubject": {
+          "id": "urn:person:identifier:IDCES-99999999R",
+          "@type": "Person",
+          "name": "Alex Example",
+          "identifier": "IDCES-99999999R",
+          "sameAs": "did:web:controller.example.org",
+          "memberOf": {
+            "@type": "Organization",
+            "taxID": "VATES-B00000000"
+          }
+        }
+      }
+    ]
+  }
+}
+

package/tests/helpers/vp-token-fixture.mjs

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+
+function b64url(input) {
+  return Buffer.from(input).toString('base64url');
+}
+
+export function buildUnsignedVpJwt(payload) {
+  const now = Math.floor(Date.now() / 1000);
+  const header = { alg: 'none', typ: 'JWT' };
+  const claims = {
+    iat: now,
+    exp: now + 600,
+    nonce: `nonce-${now}`,
+    ...payload,
+  };
+  return `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(claims))}.`;
+}
+
+export function loadVpPayloadFixture(path) {
+  const raw = fs.readFileSync(path, 'utf8');
+  return JSON.parse(raw);
+}
+

package/tests/live-gw-uc5.e2e.test.mjs

@@ -0,0 +1,108 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DataspaceNodeClient } from '../dist/index.js';
+import { buildUnsignedVpJwt, loadVpPayloadFixture } from './helpers/vp-token-fixture.mjs';
+
+function env(name, fallback = '') {
+  const value = String(process.env[name] ?? fallback).trim();
+  return value;
+}
+
+const RUN = env('RUN_LIVE_GW_E2E', '0') === '1';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+test('LIVE UC5 chain on local GW (legal -> individual -> consent -> professional token)', { skip: !RUN }, async () => {
+  const baseUrl = env('BASE_URL', 'http://127.0.0.1:3000');
+  const vpTokenEnv = env('VP_TOKEN');
+  const vpTokenFile = env('VP_TOKEN_FILE', path.join(__dirname, 'fixtures', 'ica-vp-minimal.json'));
+  const tenantId = env('TENANT_ID', 'VATES-B00000000');
+  const jurisdiction = env('JURISDICTION', 'ES');
+  const sector = env('SECTOR', 'health-care');
+  const hostSector = env('HOST_REGISTRY_SECTOR', 'test');
+  const professionalIdToken = env(
+    'PROFESSIONAL_ID_TOKEN',
+    'eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJzdWIiOiJwcm9mZXNzaW9uYWwifQ.demo',
+  );
+
+  const vpToken = vpTokenEnv || buildUnsignedVpJwt(loadVpPayloadFixture(vpTokenFile));
+  assert.ok(vpToken, 'VP_TOKEN or VP_TOKEN_FILE fixture is required for live activation test.');
+
+  const hostCtx = { jurisdiction, sector: hostSector };
+  const ctx = { tenantId, jurisdiction, sector };
+  const pollOptions = { timeoutMs: 120000, intervalMs: 1500 };
+
+  const ping = await fetch(`${baseUrl}/host/.well-known/ping`);
+  assert.equal(ping.status, 200, 'GW ping must be healthy before running live UC5 chain.');
+
+  const legalClient = new DataspaceNodeClient({ baseUrl, ctx });
+
+  const activation = await legalClient.activateOrganizationInGatewayFromIcaProof(
+    hostCtx,
+    { vpToken },
+    pollOptions,
+  );
+  assert.equal(activation.poll.status, 200, 'Legal organization activation must complete (200).');
+
+  const individual = await legalClient.bootstrapSubjectOrganizationIndex(ctx, {
+    registrationPayload: {
+      body: {
+        data: [
+          {
+            type: 'Family-registration-form-v1.0',
+            meta: {
+              claims: {
+                '@context': 'org.schema',
+                'org.schema.Organization.alternateName': env('INDIVIDUAL_ALTERNATE_NAME', `family-${Date.now()}`),
+                'org.schema.Person.telephone': env('INDIVIDUAL_CONTROLLER_PHONE', 'tel:+34600111222'),
+              },
+            },
+          },
+        ],
+      },
+    },
+    pollOptions,
+  });
+  assert.equal(
+    individual.registration.poll.status,
+    200,
+    `Individual organization registration must complete (tenantId='${tenantId}' must exist and be resolvable in GW).`,
+  );
+
+  const consent = await legalClient.grantProfessionalAccessSimple(ctx, {
+    subjectPhone: env('SUBJECT_PHONE', '+34600111222'),
+    subjectGivenName: env('SUBJECT_GIVEN_NAME', 'Ana'),
+    actor: { identifier: env('PROFESSIONAL_DID', 'did:web:professional.example.com') },
+    actorRole: env('PROFESSIONAL_ROLE', 'Practitioner'),
+    purpose: env('CONSENT_PURPOSE', 'TREAT'),
+    actions: ['organization/Composition.rs'],
+    pollOptions,
+  });
+  assert.equal(consent.poll.status, 200, 'Consent grant must complete.');
+
+  const smart = await legalClient.requestSmartTokenSimple({
+    tenantId,
+    jurisdiction,
+    sector,
+    idToken: professionalIdToken,
+    targetEndpoint: legalClient.getEndpointId(
+      {
+        section: 'organization',
+        format: 'org.hl7.fhir.r4',
+        resourceType: 'Composition',
+        action: '_search',
+      },
+      env('PROFESSIONAL_DID', 'did:web:professional.example.com'),
+    ),
+    scopes: ['organization/Composition.rs'],
+    timeoutSeconds: 60,
+    intervalSeconds: 2,
+  });
+
+  assert.ok(smart.accessToken, 'Professional SMART token must be issued.');
+  assert.ok(
+    Array.isArray(smart.scopes) && smart.scopes.includes('organization/Composition.rs'),
+    'SMART token must include organization/Composition.rs scope.',
+  );
+});

package/TODO_PROMPT_NEXT_STEPS.md

@@ -1,185 +0,0 @@
-# TODO / Prompt - Next Steps (dataspace-client-sdk-node)
-
-Objetivo de este backlog:
-- Mantener `dataspace-client-sdk-node` como SDK backend oficial para Node.
-- Añadir una capa wallet/KMS reutilizable para clientes backend Node (paridad conceptual con Python).
-- Evitar que servicios consumidores implementen crypto/auth ad-hoc fuera del SDK.
-
-Importante (decisión de arquitectura actual):
-- El wallet/KMS se implementa temporalmente dentro de este repo en:
-  - `src/sdk/dataspace-wallet-sdk-node/`
-- Más adelante se extraerá a repo/npm independiente (`dataspace-wallet-sdk-node`) sin romper API.
-
-## Repositorio fuente y referencias obligatorias
-
-Estas son las fuentes que el agente debe tomar como referencia técnica antes de implementar:
-
-1. Frontend / cliente app:
-- `gdc-sdk-client-ts`
-- Papel: SDK frontend/wallet UX-side (no backend custodial KMS).
-
-2. Backend gateway template:
-- `gwtemplate-node-ts`
-- Ruta clave: `src/gdc-backend-utils-node`
-- Papel: utilidades backend de crypto/KMS y contratos base.
-
-3. Backend UNID (fork operativo):
-- `gdc-unid-node-ts`
-- Papel: integración real de GW + managers + KMS runtime + flujos de negocio.
-
-4. SDK Python de referencia de paridad:
-- `connector-sdk-py`
-- Papel: referencia 1:1 de casos de uso backend.
-
-5. Orquestador de canal (consumidor actual):
-- `uhc-unid-chat-node`
-- Papel: usa SDK de alto nivel; no debe contener crypto/KMS de backend.
-
-Regla: si hay contradicción entre implementación Node actual y Python, documentar la divergencia y dejar TODO de convergencia.
-
-## Contexto que el agente debe respetar
-
-1. `uhc-unid-chat-node` y otros consumidores deben seguir usando métodos de alto nivel del SDK.
-2. Los cambios internos de path builders de identidad son breaking solo para consumidores que montan rutas a mano.
-3. Si el consumidor usa `authenticateBackendPkceAndExchange(...)`, no debe cambiar nada en su código por la migración de rutas identity.
-
-## Funcionamiento actual de backend tools + KMS (baseline)
-
-Resumen operativo esperado por el ecosistema backend:
-
-1. Capa SDK cliente (`dataspace-client-sdk-node`):
-- construye paths canónicos,
-- hace submit/poll,
-- orquesta auth backend (`_dcr -> _code -> _token -> _exchange`).
-
-2. Capa backend utils / KMS (hoy en GW/template repos):
-- `KmsService` / `DemoKmsService`,
-- interfaces de crypto (`IKmsService`, tipos JWK/JWS/JWE),
-- utilidades KEK/envelope para protección de claves y datos.
-
-3. Capa GW backend (`gdc-unid-node-ts` / `gwtemplate-node-ts`):
-- runtime multitenant,
-- provisión y resolución de claves por tenant,
-- operaciones de firma/verificación/cifrado en contexto servidor.
-
-Límite de responsabilidad:
-- `dataspace-client-sdk-node` no debe replicar managers de GW.
-- Sí debe poder exponer wallet/KMS cliente reutilizable para backends no-GW.
-
-## Definición de Hecho (DoD)
-
-1. Existe módulo wallet interno funcional con interfaz pública estable.
-2. El flujo `identity-exchange.v1` está soportado por métodos de alto nivel en Node (sin construir rutas manuales fuera del SDK).
-3. Se documenta paridad Node/Python por capability (no solo por endpoint).
-4. Hay tests que fallen si se rompe la paridad mínima acordada.
-5. README y ejemplos permiten a otro equipo integrar sin leer código interno.
-
-## Alcance técnico a implementar
-
-### A) Wallet/KMS interno (nuevo)
-
-Crear módulo en `src/sdk/dataspace-wallet-sdk-node/`:
-
-- `types.ts`
-  - `WalletContext` (`tenantId`, `jurisdiction`, `sector`, opcional `walletId`)
-  - `PublicJwk`, `PrivateKeyRef`, `SignOptions`, `EncryptOptions`, `DecryptOptions`
-  - `WalletProviderKind = 'mem' | 'seed' | 'external'`
-
-- `provider.ts`
-  - `WalletProvider` interface:
-    - `init(...)`
-    - `getPublicJwks(context)`
-    - `sign(payload, context, options)`
-    - `verify(payload, signature, jwk)`
-    - `encrypt(plaintext, recipientJwk, options)`
-    - `decrypt(ciphertext, context, options)`
-
-- `providers/memory-provider.ts`
-  - provider mínimo productivo para pruebas.
-
-- `providers/seed-provider.ts`
-  - solo para `demo/dev` (determinístico).
-  - prohibido recomendarlo para staging/prod.
-
-- `WalletClient.ts`
-  - fachada single-tenant.
-
-- `MultiWalletClient.ts`
-  - resolución por `tenantId/jurisdiction/sector`.
-
-### B) Integración en `DataspaceNodeClient`
-
-- Aceptar opcionalmente `wallet` en constructor/options.
-- Mantener compatibilidad de los métodos actuales de negocio/auth.
-- No mover lógica de dominios al wallet: wallet solo crypto/key operations.
-
-### C) Auth de alto nivel (paridad Python)
-
-Asegurar métodos de alto nivel para:
-- `authenticateBackendPkceAndExchange(...)`
-- base para `authenticateBackendSmartStandard(...)` (si el contrato backend ya está listo)
-
-Notas:
-- Internamente usar path builders canónicos nuevos.
-- Evitar exponer helpers de rutas como API pública “recomendada” para auth.
-
-## Plan de ejecución (orden obligatorio)
-
-1. Fase 1 - Contratos y estructura
-- Crear árbol `src/sdk/dataspace-wallet-sdk-node/*`.
-- Definir interfaces y tipos.
-- Añadir tests unitarios de contrato (sin integración GW todavía).
-
-2. Fase 2 - Provider mem/seed
-- Implementar `memory-provider` y `seed-provider`.
-- Añadir tests de firma/verificación y cifrado/descifrado.
-
-3. Fase 3 - Integración client
-- Conectar wallet opcional en `src/client.ts`.
-- Mantener sin breaking en usos actuales.
-
-4. Fase 4 - Paridad y documentación
-- Actualizar `SDK_PARITY_MAP.md` con estado real.
-- Actualizar `README.md` con sección “Wallet/KMS for backend clients”.
-- Añadir ejemplo runnable en `examples/`.
-
-5. Fase 5 - Puerta de extracción futura
-- Definir imports internos de forma que luego sea fácil reemplazar:
-  - `src/sdk/dataspace-wallet-sdk-node/*` -> paquete npm externo.
-
-## Tests mínimos obligatorios
-
-1. Unit tests wallet:
-- sign/verify roundtrip
-- encrypt/decrypt roundtrip
-- error handling de context faltante
-
-2. Unit tests auth orchestration:
-- secuencia `_dcr -> _code -> _token -> _exchange`
-- gestión de token cacheado vs refresh
-
-3. Regression tests identity routes:
-- verificar que internamente se usa patrón canónico
-  - `/{prefix}/cds-{j}/v1/{sector}/{tenantId}/identity/auth/{action}`
-
-4. Public API smoke:
-- import del SDK no rompe para consumidores actuales.
-
-## Criterios de seguridad
-
-- Ninguna private key en logs.
-- `seed-provider` marcado explícitamente como no apto para staging/prod.
-- Errores crypto sin volcar material sensible.
-
-## Entregables esperados del agente
-
-1. PR con código + tests + docs.
-2. Resumen de decisiones (tradeoffs) en la descripción.
-3. Tabla de estado actualizada en `SDK_PARITY_MAP.md`.
-4. Lista de pendientes para extracción a repo independiente.
-
-## Plantilla de commit sugerida
-
-- `feat(wallet): add internal dataspace-wallet-sdk-node module (mem/seed providers)`
-- `feat(auth): keep pkce high-level orchestration aligned with canonical identity routes`
-- `docs(parity): update SDK parity map and wallet roadmap`