Firma tu primer evento

Este tutorial te guía a través de la producción de tu primer evento CDS firmado criptográficamente. Instalarás el SDK, generarás un par de claves RSA-4096, construirás un evento en código y lo firmarás. Todo el ejercicio toma menos de cinco minutos.

Prerrequisitos

• Python 3.12+ o Node.js 20+
• Un directorio de trabajo vacío

1. Instala el SDK

   Python

   pip install signeddata-cds

   TypeScript

   npm install @signeddata/cds-sdk

2. Genera un par de claves RSA-4096

   El productor posee la clave privada. Los consumidores solo necesitan la clave pública.

   Python

   from cds import generate_keypair
   import os
   
   os.makedirs("keys", exist_ok=True)
   generate_keypair("keys/private.pem", "keys/public.pem")

   TypeScript

   import { generateKeypair } from "@signeddata/cds-sdk";
   import { mkdirSync } from "node:fs";
   
   mkdirSync("keys", { recursive: true });
   generateKeypair("keys/private.pem", "keys/public.pem");

   Protege tu clave privada

   Añade keys/ a .gitignore inmediatamente. En producción, almacena la clave privada en AWS Secrets Manager, Azure Key Vault o un HSM. Nunca la subas al repositorio.

3. Construye un evento CDS

   Este ejemplo construye un evento meteorológico para Londres usando el tipo de contenido canónico WEATHER_CURRENT.

   Python

   from cds import CDSEvent, SourceMeta, ContextMeta, CDSVocab, CDSSources
   from datetime import datetime, timezone
   
   event = CDSEvent(
       content_type  = CDSVocab.WEATHER_CURRENT,
       source        = SourceMeta(id=CDSSources.OPEN_METEO),
       occurred_at   = datetime.now(timezone.utc),
       lang          = "en",
       payload       = {
           "location":    {"city": "London", "lat": 51.51, "lon": -0.13},
           "temperature": {"current": 14.0, "feels_like": 12.0},
           "condition":   "overcast",
       },
       event_context = ContextMeta(
           summary = "London: overcast, 14C (feels 12C).",
           model   = "rule-based-v1",
       ),
   )

   TypeScript

   import { CDSEvent, CDSVocab, CDSSources } from "@signeddata/cds-sdk";
   
   const event = new CDSEvent({
     content_type: CDSVocab.WEATHER_CURRENT,
     source:       { "@id": CDSSources.OPEN_METEO },
     occurred_at:  new Date(),
     lang:         "en",
     payload:      {
       location:    { city: "London", lat: 51.51, lon: -0.13 },
       temperature: { current: 14.0, feels_like: 12.0 },
       condition:   "overcast",
     },
     context: {
       summary:      "London: overcast, 14C (feels 12C).",
       model:        "rule-based-v1",
       generated_at: new Date().toISOString(),
     },
   });

4. Firma el evento

   Python

   from cds import CDSSigner
   
   signer = CDSSigner("keys/private.pem", issuer="https://myorg.example.com")
   signer.sign(event)
   
   print(event.integrity.hash)       # sha256:...
   print(event.integrity.signed_by)  # https://myorg.example.com

   TypeScript

   import { CDSSigner } from "@signeddata/cds-sdk";
   
   const signer = new CDSSigner("keys/private.pem", "https://myorg.example.com");
   signer.sign(event);
   
   console.log(event.integrity?.hash);       // sha256:...
   console.log(event.integrity?.signed_by);  // https://myorg.example.com

5. Inspecciona el JSON-LD firmado

   Python

   import json
   print(json.dumps(event.to_jsonld(), indent=2))

   TypeScript

   console.log(JSON.stringify(event.toJSON(), null, 2));

   Deberías ver un documento JSON con @context, @type, @id y un bloque integrity que contiene el hash SHA-256 y la firma RSA-PSS codificada en base64. Este es un evento CDS v0.2.0 completo y verificable.

Próximos pasos

• Verifica un evento CDS — verifica la firma con la clave pública
• Conecta Claude a un servidor MCP — da a Claude acceso a datos firmados
• Auto-aloja un emisor — ejecuta tu propia configuración de producción
• Firma — los detalles criptográficos