dataspace-client-sdk-node 0.1.1

package/README.md

@@ -0,0 +1,310 @@
+# dataspace-client-sdk-node
+
+Node.js SDK to consume GW/UNID async DIDComm plain endpoints.
+
+**[→ Full API Reference](docs/API.md)**
+**[→ Data Model Alignment (GW + Chat + SDK)](docs/DATA_MODEL_ALIGNMENT.md)**
+**[→ Frontend/Backend SDK Ownership Matrix](../docs/SDK_AUTH_OWNERSHIP.md)**
+**[→ Developer Use-Case Cookbook (UC5 + additional patterns)](docs/DEVELOPER_USE_CASES.md)**
+
+## Scope
+- Generic async batch client (`_batch` + `_batch-response`) and JSON POST helper.
+- Route builders that cover Swagger v1 route families:
+  - `host/registry`: `Organization _batch/_activate`, `Order`,
+  - `entity`: `Employee`,
+  - `identity`: `Device/_dcr`, `Token/_exchange`, `License/_issue`, SMART token, Firebase custom token,
+  - `individual`: `Organization`, `Order`, `Person (legacy)`, `Consent`, `Composition`, `Communication`, `RelatedPerson`, `Observation`, `Task`,
+  - `digitaltwin`: `Composition` (`org.hl7.fhir.api` and `org.hl7.fhir.r4`),
+  - debug UHC task endpoints: `_call-start`, `_logs`.
+
+## Claims Placement Contract
+- Canonical batch-entry claims location: `entry.resource.meta.claims`.
+- Legacy compatibility location: `entry.meta.claims`.
+- This SDK now emits both during migration; new consumers should read/write `resource.meta.claims`.
+
+## Install (local workspace)
+
+```bash
+cd tools/dataspace-client-sdk-node
+npm install
+npm run type-check
+npm run build
+```
+
+## Tests (mocked, no network)
+
+The SDK includes mocked tests (Python-SDK style) for:
+- route/path building,
+- async `submit + poll`,
+- multipart conversion upload.
+
+Run:
+```bash
+cd sdk/dataspace-client-sdk-node
+
+npm test
+
+```
+
+
+```ts
+import { DataspaceNodeClient, createDidcommPlainMessage } from './dist/index.js';
+const client = new DataspaceNodeClient({
+  baseUrl: 'http://localhost:3000',
+  bearerToken: 'demo-token',
+});
+
+const ctx = { tenantId: 'acme', jurisdiction: 'ES', sector: 'health-care' };
+  iss: 'adult1@example.com',
+  aud: 'did:web:api.acme.org',
+  body: {
+    data: [
+      {
+        type: 'Family-registration-form-v1.0',
+        meta: {
+          claims: {
+            '@context': 'org.schema',
+            '@type': 'template',
+            'org.schema.Organization.address.addressCountry': 'ES',
+            'org.schema.Organization.identifier.additionalType': 'UUID',
+            'org.schema.Organization.identifier.value': 'f0d4b66d-7e28-4fa2-91b7-7041e57f4f90',
+            'org.schema.Person.email': 'adult1@example.com',
+            'org.schema.Service.category': 'health-care',
+            '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',
+          },
+        },
+      },
+    ],
+  },
+});
+
+const submitPath = client.individualFamilyOrganizationBatchPath(ctx);
+const pollPath = client.individualFamilyOrganizationPollPath(ctx);
+const result = await client.submitAndPoll(submitPath, pollPath, payload);
+console.log(result.poll.status, result.poll.body);
+```
+
+## Backend auth: identity-exchange.v1 (B2B PKCE flow)
+
+For server-to-server integration (e.g. `uhc-unid-chat-node` calling the GW), the SDK implements the
+full `identity-exchange.v1` flow: DCR binding → PKCE code → token → SMART bearer exchange.
+
+This is the Node equivalent of Python's `authenticate_backend_pkce_and_exchange` in `connector-sdk-py`.
+
+**Prerequisites:**
+1. Your tenant org is activated in the GW (`registry/org.schema/Organization/_activate` with ICA VC).
+2. An API key with the required scopes has been issued by ICA (`identity/api-key/_create`).
+3. You have your service's public JWK (EC P-384 recommended).
+
+**Usage:**
+
+```ts
+import { DataspaceNodeClient } from './dist/index.js';
+
+const client = new DataspaceNodeClient({ baseUrl: 'https://gw.example.com' });
+
+const ctx = { tenantId: 'acme', jurisdiction: 'ES', sector: 'health-care' };
+
+// Run once per key pair; result is cached automatically.
+const auth = await client.authenticateBackendPkceAndExchange({
+  ctx,
+  apiKey: process.env.GW_API_KEY!,
+  controllerPublicJwk: JSON.parse(process.env.GW_PUBLIC_JWK!),
+  scopes: ['onboarding', 'family-registration', 'license-order'],
+  endpointId: 'chatbot-main', // cache key; re-auth on expiry is automatic
+});
+
+if (auth.status === 'failed') {
+  throw new Error(`Backend auth failed at step: ${auth.step}`);
+}
+
+// Use the bearer for subsequent requests:
+const authedClient = new DataspaceNodeClient({
+  baseUrl: 'https://gw.example.com',
+  bearerToken: auth.accessToken,
+});
+```
+
+**Demo / local bypass (never for production):**
+
+```ts
+// .env: SECURITY_MODE=demo  GW_AUTH_BEARER=static-demo-token
+const client = new DataspaceNodeClient({
+  baseUrl: process.env.BASE_URL!,
+  bearerToken: process.env.GW_AUTH_BEARER, // skip identity-exchange.v1 entirely
+});
+```
+
+## Backend auth: smart-backend.v1 (client_credentials + private_key_jwt)
+
+For direct OAuth2 machine-to-machine flows (bypassing the PKCE device flow), use the
+`smart-backend.v1` profile. The SDK signs the `client_assertion` JWT locally using an
+in-memory ES384 wallet.
+
+This is the Node equivalent of Python's `authenticate_backend_smart_standard` in
+`connector-sdk-py`.
+
+**Usage:**
+
+```ts
+import { DataspaceNodeClient, MemoryWalletProvider } from './dist/index.js';
+
+const wallet = new MemoryWalletProvider();
+
+// walletContext scopes the key pair. Use the service's logical identity.
+const walletContext = { tenantId: 'service-a', jurisdiction: 'ES', sector: 'health-care' };
+
+const client = new DataspaceNodeClient({
+  baseUrl: 'https://gw.example.com',
+  wallet,
+});
+
+// On first call, authenticates. On subsequent calls within token TTL, returns cached.
+const result = await client.authenticateBackendSmartStandard({
+  clientId: 'service-a',
+  scopes: ['system/*.read', 'system/*.write'],
+  walletContext,
+  // tokenUrl: optional absolute URL; defaults to `${baseUrl}/token`
+  // audience: optional; defaults to the resolved tokenUrl
+  // assertionTtlSeconds: optional; defaults to 300
+});
+
+if (result.status === 'failed') {
+  throw new Error(`smart-backend.v1 auth failed: HTTP ${result.statusCode}`);
+}
+
+const authedClient = new DataspaceNodeClient({
+  baseUrl: 'https://gw.example.com',
+  bearerToken: result.accessToken,
+});
+```
+
+**How it works internally:**
+1. `MemoryWalletProvider` generates a dedicated EC P-384 key (`use: sig`, `alg: ES384`).
+2. `signCompactJws(...)` produces the `client_assertion` JWT signed with that key.
+3. A single `client_credentials` POST to the token endpoint returns the bearer.
+4. The token is cached until 30s before expiry; subsequent calls return `status: 'cached'`.
+
+## DIDComm encrypted (nested JWS-in-JWE)
+
+For GW endpoints that require `application/didcomm-encrypted+json`, use `submitBatchEncrypted`.
+This implements the nested JOSE pattern expected by the backend: sign first (ES384 compact JWS),
+then encrypt (ML-KEM-768 + A256GCM compact JWE with `cty: JWS`).
+
+Requires a wallet provider and the recipient's ML-KEM-768 encryption JWK (from GW
+`.well-known/jwks.json`, `use: enc`). The `MemoryWalletProvider` generates ML-KEM-768 keys
+automatically — no RSA setup required.
+
+### ML-KEM-768 JWK format
+
+Encryption keys use the OKP JWK type with `crv: "ML-KEM-768"`:
+
+```json
+{
+  "kty": "OKP",
+  "crv": "ML-KEM-768",
+  "use": "enc",
+  "alg": "ML-KEM-768",
+  "x": "<base64url-encoded 1184-byte public key>",
+  "kid": "wallet:acme:ES:health-care:abc123"
+}
+```
+
+The `encrypted_key` slot in the compact JWE is the 1088-byte ML-KEM ciphertext (base64url).
+The 32-byte shared secret derived by KEM encapsulation is used directly as the AES-256-GCM CEK.
+
+```ts
+import { DataspaceNodeClient, MemoryWalletProvider } from './dist/index.js';
+
+const wallet = new MemoryWalletProvider();
+const walletContext = { tenantId: 'acme', jurisdiction: 'ES', sector: 'health-care' };
+const client = new DataspaceNodeClient({ baseUrl: 'https://gw.example.com', wallet });
+
+// Wallet's own ML-KEM enc JWK (share with backend so it can encrypt to you):
+const [, encJwk] = await wallet.getPublicJwks(walletContext);
+
+// Fetch GW encryption JWK from well-known endpoint for outbound encryption:
+// const { keys } = await (await fetch('https://gw.example.com/.well-known/jwks.json')).json();
+// const recipientEncJwk = keys.find(k => k.use === 'enc' && k.crv === 'ML-KEM-768');
+
+// For local roundtrip test, use wallet's own enc key as recipient:
+const recipientEncJwk = encJwk;
+
+const payload = { thid: 'my-thid', body: { data: [] } };
+const result = await client.submitBatchEncrypted(
+  client.individualFamilyOrganizationBatchPath(ctx),
+  payload,
+  recipientEncJwk,
+  walletContext,
+);
+```
+
+**Cache helper** — if you need the current bearer without re-running the flow:
+
+```ts
+const bearer = client.getCachedBearerToken('chatbot-main');
+// Returns undefined if not cached or expired (>30s remaining).
+```
+
+Full runnable example: `examples/backend-pkce-auth.mjs`
+
+## Swagger parity strategy
+- For any v1 route exposed in Swagger, use:
+  - `client.v1Path(ctx, section, format, resourceType, action)` for tenant routes.
+  - `client.hostRegistryPath(ctx, resourceType, action)` for host registry routes.
+- Then call one of:
+  - `submitBatch(path, didcommPayload)` for DIDComm plain submit routes,
+  - `pollBatchResponse(path, { thid })` / `pollUntilComplete(...)`,
+  - `postJson(path, payload)` for non-batch JSON routes.
+
+This avoids hardcoding curl scripts per endpoint.
+
+## Notes for telephony tests
+- Keep GW/UHC unit/integration tests direct (service/router level).
+- Use this SDK for consumer-style E2E tests and external Node.js service integrations.
+- If individual onboarding moves to a separate service, telephony tests should consume that service and only use GW/UHC for reminders/calls.
+
+## DataConversion / Excel
+
+This SDK now includes conversion helpers:
+- `conversionUploadPath(ctx, softwareId, sourceFormat)`
+- `conversionUploadPollPath(ctx, softwareId, sourceFormat)`
+- `uploadConversionFile({ path, fileName, fileContent, fields })`
+
+Example:
+- `examples/conversion-upload.mjs`
+
+Run:
+```bash
+cd sdk/dataspace-client-sdk-node
+npm run build
+BASE_URL="http://localhost:3000" \
+AUTH_BEARER="demo-token" \
+TENANT_ID="acme" \
+JURISDICTION="ES" \
+SECTOR="animal-care" \
+SOFTWARE_ID="excel-adapter" \
+SOURCE_FORMAT="xlsx" \
+SOURCE_FILE="/absolute/path/to/input.xlsx" \
+node examples/conversion-upload.mjs
+```
+
+Notes:
+- Exact multipart field names may vary by DataConversion deployment.
+- If your conversion API is synchronous, polling is optional.
+- If it is async, provide/resolve `thid` and poll `.../_upload-response`.
+
+## Next planned additions
+- Typed payload builders per flow (`family`, `relatedPerson`, `observation`, `task`).
+- Claims mappers (`ClaimName` <-> SQL internal name with `_`).
+- Retry/backoff + richer error mapping.
+
+## Planning and Parity Docs
+
+- TODO / execution prompt: `TODO_PROMPT_NEXT_STEPS.md`
+- Node/Python API parity map: `SDK_PARITY_MAP.md`
+
+## Pending Compatibility TODO
+- See [SMART EHR compatibility TODO](docs/TODO_SMART_EHR_COMPAT.md).

package/SDK_PARITY_MAP.md

@@ -0,0 +1,120 @@
+# SDK Parity Map (Node vs Python)
+
+Estado: guía de referencia para alinear `dataspace-client-sdk-node` con `connector-sdk-py`.
+
+Convención:
+- Node SDK: `dataspace-client-sdk-node`
+- Python SDK: `connector-sdk-py`
+- Wallet interno temporal en Node: `src/sdk/dataspace-wallet-sdk-node/`
+
+## 0) Repos fuente del ecosistema (contexto obligatorio)
+
+| Repo | Rol |
+|---|---|
+| `dataspace-client-sdk-node` | SDK backend Node (este repo) |
+| `connector-sdk-py` | referencia de paridad backend Python |
+| `gdc-sdk-client-ts` | SDK/frontend wallet UX-side |
+| `gwtemplate-node-ts` | base backend GW + `gdc-backend-utils-node` |
+| `gdc-unid-node-ts` | fork operativo de GW para UNID |
+| `uhc-unid-chat-node` | consumidor de alto nivel (voice/chat orchestration) |
+
+## 1) Perímetro de paridad
+
+La paridad se mide por capacidades, no por nombres internos exactos:
+
+1. Auth backend (PKCE + exchange / SMART backend)
+2. Submit + poll de operaciones de dominio
+3. Lifecycle de API keys
+4. Wallet/KMS cliente (firma, verificación, cifrado, descifrado)
+
+## 2) Identity Routes (canónicas)
+
+Patrón objetivo para rutas de identidad:
+
+`/{prefix}/cds-{jurisdiction}/v1/{sector}/{tenantId}/identity/auth/{action}`
+
+Donde `prefix` depende del servicio:
+- `host` (GW)
+- `publisher` (DataConv)
+- `ica` (ICA)
+
+Nota de compatibilidad:
+- Consumidores que usan métodos de alto nivel (`authenticateBackendPkceAndExchange`) no deberían depender de este detalle.
+- Consumidores que montaban rutas manuales sí deben migrar.
+
+## 3) Paridad de Auth
+
+| Capability | Node SDK | Python SDK | Estado objetivo |
+|---|---|---|---|
+| Identity DCR submit/poll | path builder + submit/poll | operación equivalente | ✅ |
+| Identity code submit/poll | path builder + submit/poll | operación equivalente | ✅ |
+| Identity token submit/poll | path builder + submit/poll | operación equivalente | ✅ |
+| Identity exchange submit/poll | path builder + submit/poll | operación equivalente | ✅ |
+| PKCE orchestration | `authenticateBackendPkceAndExchange(...)` | `authenticate_backend_pkce_and_exchange(...)` | ✅ |
+| SMART backend orchestration | método Node equivalente (pendiente según contrato) | `authenticate_backend_smart_standard(...)` | ⏳ |
+
+## 4) Paridad de Wallet/KMS cliente
+
+Arquitectura temporal Node:
+- módulo interno `src/sdk/dataspace-wallet-sdk-node/`
+- evolución futura: extraer a paquete/repo independiente
+
+Baseline funcional backend/KMS que debe respetarse:
+- en GW (`gdc-unid-node-ts`/`gwtemplate-node-ts`) existen servicios KMS runtime (`KmsService`, `DemoKmsService`) y utilidades KEK en backend utils,
+- el SDK cliente no replica managers de GW,
+- pero sí debe exponer wallet/KMS reutilizable para servicios backend cliente.
+
+| Capability | Node target (`dataspace-wallet-sdk-node` interno) | Python target | Estado |
+|---|---|---|---|
+| Key material provider abstraction | `WalletProvider` | provider equivalente | ⏳ |
+| In-memory provider | `memory-provider` | provider equivalente | ⏳ |
+| Deterministic seed provider (demo/dev) | `seed-provider` | provider equivalente | ⏳ |
+| Public JWK export | `getPublicJwks(...)` | equivalente | ⏳ |
+| Sign/verify | `sign(...)`, `verify(...)` | equivalente | ⏳ |
+| Encrypt/decrypt | `encrypt(...)`, `decrypt(...)` | equivalente | ⏳ |
+| Single-tenant facade | `WalletClient` | equivalente | ⏳ |
+| Multi-tenant facade | `MultiWalletClient` | equivalente | ⏳ |
+
+## 5) Paridad de dominios (baseline)
+
+| Domain capability | Node SDK | Python SDK | Estado |
+|---|---|---|---|
+| Family/Organization onboarding | métodos batch + poll | equivalente | ✅/⏳ según endpoint |
+| RelatedPerson | métodos batch + poll | equivalente | ✅ |
+| Observation | métodos batch + poll | equivalente | ✅ |
+| Communication | métodos batch + poll | equivalente | ✅ |
+| Composition | métodos batch + poll | equivalente | ✅ |
+| Task | métodos batch + poll | equivalente | ✅ |
+| Conversion upload | upload + poll | equivalente | ✅ |
+
+## 6) Surface nuevo (onboarding/licensing/payment)
+
+| Capability | Node SDK | Python SDK | Contract endpoint | Estado |
+|---|---|---|---|---|
+| Family Organization search | pendiente | pendiente | `individual/org.schema/Organization/_search` (+ `_batch-response`) | ⏳ |
+| Family Organization create/resume | pendiente | pendiente | `individual/org.schema/Organization/_batch` (+ `_batch-response`) | ⏳ |
+| Family Order create | pendiente | pendiente | `individual/org.schema/Order/_batch` (+ `_batch-response`) | ⏳ |
+| Host registry order (host flow) | pendiente | pendiente | `host/.../registry/org.schema/Order/_batch` (+ `_batch-response`) | ⏳ |
+| Offer consumption for family flow | pendiente | pendiente | offer returned by Organization `_batch-response` | ⏳ |
+| Stripe intent | pendiente | pendiente | `payment/stripe/_intent` | ⏳ |
+| Stripe status | pendiente | pendiente | `payment/stripe/_status` | ⏳ |
+| API key create | pendiente | disponible en Python | `identity/api-key/_create` | ⏳ |
+| API key disable | pendiente | disponible en Python | `identity/api-key/_disable` | ⏳ |
+| API key search | pendiente | disponible en Python | `identity/api-key/_search` | ⏳ |
+
+## 7) Reglas de cambio
+
+Cada PR que cambie superficie pública en Node o Python debe incluir:
+
+1. actualización de esta tabla,
+2. tests de paridad/compatibilidad,
+3. nota de migración si hay breaking changes.
+
+## 8) Check de salida para release
+
+Antes de publicar nueva versión Node:
+
+1. `README` actualizado con auth + wallet.
+2. ejemplos funcionales en `examples/`.
+3. tests de paridad en verde.
+4. changelog con sección de migración (si aplica).

package/TODO_PROMPT_NEXT_STEPS.md

@@ -0,0 +1,185 @@
+# 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`