Sign your first event

This tutorial walks you through producing your first cryptographically signed CDS event. You will install the SDK, generate an RSA-4096 keypair, build an event in code, and sign it. The whole exercise takes under five minutes.

Prerequisites

• Python 3.12+ or Node.js 20+
• An empty working directory

1. Install the SDK

   Python

   pip install signeddata-cds

   TypeScript

   npm install @signeddata/cds-sdk

2. Generate an RSA-4096 keypair

   The producer holds the private key. Consumers only ever need the public key.

   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");

   Protect your private key

   Add keys/ to .gitignore immediately. In production, store the private key in AWS Secrets Manager, Azure Key Vault, or an HSM. Never commit it.

3. Build a CDS event

   This example builds a weather event for London using the canonical WEATHER_CURRENT content type.

   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. Sign the event

   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. Inspect the signed JSON-LD

   Python

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

   TypeScript

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

   You should see a JSON document with @context, @type, @id, and an integrity block containing the SHA-256 hash and base64-encoded RSA-PSS signature. This is a complete, verifiable CDS v0.2.0 event.

Next steps

• Verify a CDS event — verify the signature with the public key
• Connect Claude to an MCP server — give Claude access to signed data
• Self-host an issuer — run your own production setup
• Signing — the cryptographic details