Signing

Detached Ed25519 signatures for UKS packets. A signature binds a packet to a publisher identity without ever modifying the packet itself — a registry or downstream consumer can verify both that the packet wasn't altered in transit and that it came from a known publisher.

Status: the reference implementation ships in @uks/cli; normative integration into the spec body is pending, tracked alongside the IANA/W3C submission (on hold for the public comment period).

Why detached

The signature lives in a sidecar object (<packet>.sig.json), never inside the packet:

• The packet is never mutated — it still validates against UKS.v3.schema.json unchanged, with no _signature field to allow-list.
• Verification is asymmetric (Ed25519) — anyone holding the public key can verify; only the holder of the private key can sign.

Canonicalization (uks-jcs-1)

The signature is computed over the packet's canonical form, not its literal bytes, so re-serialization (different key order, whitespace, encoder) doesn't invalidate it. uks-jcs-1 = recursively key-sorted, minimal-whitespace JSON — approximating RFC 8785 / JCS over the subset of JSON UKS uses (no NaN/Infinity).

Signature object

{
  "alg": "ed25519",
  "canon": "uks-jcs-1",
  "public_key": "<base64 SPKI DER>",
  "signature": "<base64 Ed25519 signature>",
  "signed_at": "2026-06-18T12:00:00Z"
}

signed_at is informational only and is not covered by the signature itself — the signature attests to the packet content, not the timestamp. The public key is embedded so a verifier needs nothing but the sidecar; publishers should also distribute their public key out-of-band so consumers can pin a trusted identity.

CLI usage

uks sign  path/to/packet.uks.json            # generates a keypair if --key is absent
uks sign  --key publisher.pem --out p.sig.json packet.uks.json
uks verify path/to/packet.uks.json           # reads <packet>.sig.json by default
uks verify --sig p.sig.json packet.uks.json  # exit 0 = valid, 1 = invalid

Signing and publishing together:

uks publish --sign --sign-key ./my-key.pem my-packet.uks.json

A signed packet records a W3C did:key publisher identity on the registry, verified server-side. See Publish & sign for the registry-side behavior (valid signature → verified tier; no signature → still publishes as unsigned/raw; invalid signature or a signer switch on re-publish → rejected).

Threat model — what a valid signature does and does not prove

• Does prove: the packet content is byte-for-byte (canonically) what the holder of the private key signed; any tampering with sources, scores, targets, or directives invalidates it.
• Does not prove: that the public key belongs to who you think it does — binding the key to a publisher identity happens out-of-band (the registry's revocable API-key author identity, a .well-known key, or a key-transparency log). Key distribution and trust roots are out of scope for this mechanism.

→ Related: Publish & sign · CLI · Trust & safety