@visiion/dci-registry-core

Librería NestJS que implementa la DCI Registry Core API v1.0.0.

• Especificación oficial: https://api.spdci.org/release/html/registry_core_api_v1.0.0.html

Instalación

npm install @visiion/dci-registry-core

Uso en una app NestJS

1. Registrar el módulo

import { Module } from '@nestjs/common';
import { DciRegistryCoreModule } from '@visiion/dci-registry-core';
import { MySearchHandler } from './handlers/my-search.handler';

@Module({
  imports: [
    DciRegistryCoreModule.register({
      version: '1.0.0',
      strictHeaderValidation: true,
      strictMessageValidation: true,
      crypto: {
        enableSignatureVerification: true,
        algorithm: 'ed25519',
        clockSkewSeconds: 60,
        publicKeyResolver: async (senderId: string, kidId?: string) => {
          // Resolver la clave pública del sender (ej: desde BD, JWKS, etc.)
          return fetchPublicKey(senderId, kidId);
        },
      },
      encryption: {
        enableEncryptionSupport: false,
        decrypt: async () => ({}),
        encrypt: async (p) => p,
      },
      observability: {
        logger: console,
      },
      handlers: {
        search: MySearchHandler,
        onSearch: MyOnSearchHandler,
        syncSearch: MySyncSearchHandler,
        // ... resto de handlers
      },
    }),
  ],
})
export class AppModule {}

2. Implementar handlers

Cada API consumidora debe implementar los handlers que use:

// my-search.handler.ts
import { Injectable } from '@nestjs/common';
import type { SearchHandler } from '@visiion/dci-registry-core';
import type { SearchRequestDto } from '@visiion/dci-registry-core';

@Injectable()
export class MySearchHandler implements SearchHandler {
  async handleSearch(request, header, rawEnvelope) {
    // Lógica de negocio: validar, buscar en BD, etc.
    // Para async: devolver ACK (o void para ACK por defecto)
    return { status: 'ACK', message_id: header.message_id };
  }
}

3. Ejemplo de controller funcionando

Tras registrar el módulo, los endpoints quedan expuestos automáticamente:

• Async: POST /registry/search, POST /registry/on-search, POST /registry/subscribe, etc.
• Sync: POST /registry/sync/search, POST /registry/sync/txn/status

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

Checklist: qué debe implementar cada API

| Rol | Endpoints a implementar | Handlers requeridos | |-------|-------------------------|--------------------------| | SR | /registry/search, /registry/txn/status, /registry/sync/search, /registry/sync/txn/status | search, txnStatus, syncSearch, syncTxnStatus | | SPMIS | /registry/on-search, /registry/on-subscribe, /registry/on-unsubscribe, /registry/txn/on-status | onSearch, onSubscribe, onUnsubscribe, txnOnStatus | | Ambos | subscribe, unsubscribe, notify | subscribe, unsubscribe, notify |

Assumptions

1. Digest del body: Se asume que el digest se calcula sobre JSON.stringify({ header, message }). El spec no especifica orden de claves; se usa el orden nativo de JSON.stringify.
2. Signature en body: La firma viaja en envelope.signature, no en header HTTP Signature.
3. ACK por defecto: Si el handler devuelve void, se responde con { status: 'ACK', message_id }.
4. Namespace: Soporte configurable vía options.namespace; paths con namespace no están implementados en los controllers (TODO).
5. EncryptedMessage: Cuando is_msg_encrypted=true, message es un EncryptedMessage; el pipe de decrypt lo desencripta antes de pasar al handler.

Security Notes

• Verificación de firma: Activar enableSignatureVerification: true en producción.
• Public key resolver: Implementar resolución segura (JWKS, BD, etc.).
• Clock skew: Ajustar clockSkewSeconds según la precisión de relojes entre sistemas.
• Logging: No loguear PII ni payload completo; usar correlation_id y message_id para trazabilidad.

Estructura del paquete

src/
  module/          # DynamicModule, tipos, tokens
  controllers/     # registry-async.controller, registry-sync.controller
  dtos/            # envelope, header, signature, message DTOs
  crypto/          # signature parser, digest, ed25519, verifier
  interfaces/      # handlers, public-key-resolver, encryption
  pipes/           # validate-action, decrypt-message
  interceptors/    # correlation, logging
  errors/          # exception filter, error catalog

Scripts

npm run build   # Compila a dist/
npm test        # Ejecuta tests

Licencia

MIT