can2cup 0.10.3 → 0.10.4

package/src/protocol/principal.ts

@@ -0,0 +1,90 @@
+/**
+ * Principal-signed messages — the principal → agent channel, end to end.
+ *
+ * v0.2 and earlier: whatever the bridge put in an agent's inbox was shown to the model as
+ * "principal instructions", and the only thing standing between an attacker and that label
+ * was the bot's shared BRIDGE_KEY (2026-08-19 review, F1/F7). v0.3 gives the principal an
+ * ed25519 keypair of their own (`~/.parley/principal.json`). An instruction or a pause that
+ * carries a valid signature by THAT key — addressed to THIS agent, with a fresh nonce — is
+ * the only thing the MCP server will ever label as verified. The relay and the bot can still
+ * write unsigned items; those stay explicitly unverified.
+ *
+ * The signature covers `agent`, so a message signed for one agent cannot be replayed to
+ * another; `nonce` lets the receiver refuse the same message twice; `at` orders pauses.
+ * `approve` binds an approval to a concrete envelope (room, seq, hash), so an approval can
+ * never be re-aimed at a different decision than the one the principal looked at (F6).
+ */
+import { canon } from "./canon.js";
+import { randomHex, signHex, verifyHex } from "./crypto.js";
+
+export interface ApproveRef { room: string; seq: number; hash: string; ok: boolean }
+
+export interface PrincipalMsg {
+  kind: "say" | "pause";
+  agent: string;   // the agent's pubkey this is addressed to
+  at: string;      // ISO-8601
+  nonce: string;   // random hex; receivers keep a seen-set
+  text?: string;   // say
+  paused?: boolean; // pause
+  approve?: ApproveRef; // say: this text is a decision on one specific envelope
+}
+export interface SignedPrincipalMsg extends PrincipalMsg { pub: string; sig: string }
+
+export function principalSigningBytes(m: PrincipalMsg): string {
+  const { kind, agent, at, nonce, text, paused, approve } = m;
+  return canon({ kind, agent, at, nonce, text, paused, approve });
+}
+
+export function signPrincipal(m: Omit<PrincipalMsg, "at" | "nonce"> & Partial<Pick<PrincipalMsg, "at" | "nonce">>, priv: string, pub: string): SignedPrincipalMsg {
+  const full: PrincipalMsg = { ...m, at: m.at ?? new Date().toISOString(), nonce: m.nonce ?? randomHex(16) };
+  return { ...full, pub, sig: signHex(principalSigningBytes(full), priv) };
+}
+
+/** Structural + cryptographic check. `expectedPub` = the principal key the verifier trusts
+ *  (the agent pins its own principal.json pubkey; the bridge pins what the agent registered);
+ *  `expectedAgent` = the verifier's own agent pubkey. */
+export function verifyPrincipal(s: SignedPrincipalMsg, expectedPub: string, expectedAgent: string): { ok: boolean; error?: string } {
+  if (!s || typeof s !== "object") return { ok: false, error: "not a message" };
+  if (s.kind !== "say" && s.kind !== "pause") return { ok: false, error: "bad kind" };
+  if (!/^[0-9a-f]{64}$/.test(s.pub ?? "")) return { ok: false, error: "bad pub" };
+  if (s.pub !== expectedPub) return { ok: false, error: "signed by a key that is not your principal's" };
+  if (s.agent !== expectedAgent) return { ok: false, error: "addressed to a different agent" };
+  if (typeof s.nonce !== "string" || s.nonce.length < 16) return { ok: false, error: "bad nonce" };
+  if (!Number.isFinite(Date.parse(s.at ?? ""))) return { ok: false, error: "bad timestamp" };
+  if (s.kind === "say" && typeof s.text !== "string") return { ok: false, error: "say without text" };
+  if (s.kind === "pause" && typeof s.paused !== "boolean") return { ok: false, error: "pause without paused flag" };
+  if (!verifyHex(s.sig, principalSigningBytes(s), s.pub)) return { ok: false, error: "bad principal signature" };
+  return { ok: true };
+}
+
+// ------------------------------------------------ signed HTTP requests ---
+
+/** Requests that must prove possession of a key (agent → bridge, agent → room admin ops,
+ *  principal → bridge) carry three headers and sign "METHOD\nPATH\nTS\nBODY". The relay
+ *  checks the timestamp is within ±5 minutes. Same scheme for every key role, so one helper. */
+export const REQ_SIG_SKEW_MS = 5 * 60 * 1000;
+
+export function requestSigningBytes(method: string, path: string, ts: string, body: string): string {
+  return `${method}\n${path}\n${ts}\n${body}`;
+}
+
+export function signRequestHeaders(method: string, path: string, body: string, key: { pub: string; priv: string }, prefix = "x-parley"): Record<string, string> {
+  const ts = new Date().toISOString();
+  return {
+    [`${prefix}-pub`]: key.pub,
+    [`${prefix}-ts`]: ts,
+    [`${prefix}-sig`]: signHex(requestSigningBytes(method, path, ts, body), key.priv),
+  };
+}
+
+export function verifyRequestHeaders(
+  h: (name: string) => string | undefined, method: string, path: string, body: string, prefix = "x-parley", now = Date.now(),
+): { ok: true; pub: string } | { ok: false; error: string } {
+  const pub = h(`${prefix}-pub`) ?? "";
+  const ts = h(`${prefix}-ts`) ?? "";
+  const sig = h(`${prefix}-sig`) ?? "";
+  if (!/^[0-9a-f]{64}$/.test(pub) || !ts || !sig) return { ok: false, error: "missing signature headers" };
+  if (Math.abs(now - Date.parse(ts)) > REQ_SIG_SKEW_MS) return { ok: false, error: "signature timestamp too old" };
+  if (!verifyHex(sig, requestSigningBytes(method, path, ts, body), pub)) return { ok: false, error: "bad signature" };
+  return { ok: true, pub };
+}

package/src/protocol/release.ts

@@ -0,0 +1,35 @@
+// v0.10.0 (security G-3, P2): release signing.
+//
+// The relay serves the install tarball; the maintainer SIGNS it. These are different people in the threat model
+// (or the same person on different days), so the key that vouches for a release must not live on the relay.
+// The private half stays offline on the maintainer's machine (scripts/release-key.mjs); this file carries the
+// public half, compiled into every client. A client trusts a release only if manifest.sig verifies against one
+// of these keys. Rotation: add the new key here, ship, drop the old one in the following release.
+import { canon } from "./canon.js";
+import { verifyHex } from "./crypto.js";
+
+export const RELEASE_PUBS: string[] = [
+  "7a025a45418ea95d0aaf6738749cf72d40207965610d1a31cb3db6233f50d571", // 2026-09-05, the maintainer's home machine
+];
+
+export interface ReleaseManifest {
+  v: number;
+  version: string;
+  date: string;
+  /** file name → sha256 hex; every alias the relay serves maps to the same hash */
+  files: Record<string, string>;
+  changelogSha256?: string;
+  permissionChange?: boolean;
+  dataFlowChange?: boolean;
+  minClient?: string;
+}
+
+/** Signature over canon(manifest) — the same canonical JSON every envelope uses; no new format. */
+export function verifyManifest(m: unknown, sigHex: string, pubs: string[]): { ok: true; pub: string } | { ok: false; reason: string } {
+  const x = m as Partial<ReleaseManifest> | null;
+  if (!x || typeof x !== "object" || x.v !== 1 || typeof x.version !== "string" || !x.files || typeof x.files !== "object") return { ok: false, reason: "release manifest is malformed" };
+  if (!/^[0-9a-f]{128}$/.test(sigHex)) return { ok: false, reason: "release manifest signature is malformed" };
+  const msg = canon(x);
+  for (const pub of pubs) if (verifyHex(sigHex, msg, pub)) return { ok: true, pub };
+  return { ok: false, reason: `release manifest signature does not verify against any release key this client trusts (${pubs.map((p) => p.slice(0, 8) + "…").join(", ")}) — release key not trusted by this client, or the manifest was altered` };
+}

package/src/protocol/room.ts

@@ -0,0 +1,115 @@
+/** Shared room shapes and the invite encodings. */
+export interface RoomPolicy {
+  maxMessages: number; // hard cap per room; hitting it forces a close
+  ttlSec: number;      // relay refuses appends after createdAt + ttl
+}
+export const DEFAULT_POLICY: RoomPolicy = { maxMessages: 200, ttlSec: 6 * 3600 };
+
+export interface Participant { name: string; joinedAt: string; removed?: string /* ISO, set by eject */ }
+
+export interface RoomInfo {
+  id: string;
+  name: string;
+  policy: RoomPolicy;
+  participants: Record<string, Participant>; // pubkey -> participant (ejected ones stay listed, with `removed`)
+  createdAt: string;
+  createdBy: string;
+  state: "open" | "closed";
+  lastSeq: number;
+  lastHash: string;
+  relayPub?: string; // the relay's signing pubkey (v0.3+); clients pin it per room
+  secret?: string;   // the CURRENT invite secret — only returned to a caller authenticated by their own cap
+  e2e?: boolean;     // v0.5.0: bodies are ciphertext; the key lives in the invite fragment, never here
+  // Portable rooms / mirrors (v0.4.15+):
+  pastRelayPubs?: string[];    // relay keys this room lived under before it was imported here
+  role?: "mirror";             // absent = primary (writable); "mirror" = read-only replica fed by /replicate
+  origin?: string;             // mirror only: the primary relay this replica follows
+  mirrors?: string[];          // primary only: relays every append is replicated to
+}
+
+/** What GET /rooms/:id/export returns and POST /rooms/:id/import accepts. The chain is
+ *  re-verified on import — an export is claimed evidence, never trusted evidence. */
+export interface RoomExport {
+  format: "parley-export-1";
+  exportedAt: string;
+  room: {
+    id: string; name: string; policy: RoomPolicy; participants: Record<string, Participant>;
+    createdAt: string; createdBy: string; state: "open" | "closed"; e2e?: boolean;
+  };
+  secret?: string;    // only present for a cap-authenticated exporter (same rule as info)
+  messages: unknown[]; // Envelope[]; typed loosely so the importer must verify, not assume
+  relayPub?: string;  // the exporting relay's signing key — system events verify against it
+  head?: unknown;     // the exporting relay's signed head over the tail
+}
+
+/**
+ * Invite = everything the other side needs: relay (u), room id (r), room secret (s), name (n).
+ *
+ * Two encodings of the same thing:
+ *   URL     https://<relay>/j/<room>?n=<name>#<secret>   ← the one to hand to humans
+ *   token   parley1.<base64url json>                     ← compact, for logs / agent-only paths
+ *
+ * The URL is the primary form: a human can click it (the relay serves a landing page
+ * that explains what to paste to their agent), a phone can scan it as a QR code, and
+ * an agent can paste it straight into can2cup_join. The secret rides in the fragment,
+ * so it never appears in the relay's request logs. Whoever holds either form can read
+ * and post in the room — treat an invite like a Telegram join link, not like a URL.
+ */
+/** k (v0.5.0): the E2E room key. It rides in the URL fragment after the secret
+ *  (`#<secret>.<key>`), so like the secret it never reaches any server. */
+export interface Invite { u: string; r: string; s: string; n?: string; p?: string /* relay signing pubkey, vouched by the inviter */; k?: string }
+
+const PREFIX = "parley1.";
+const TOKEN_RE = /parley1.[A-Za-z0-9_-]{16,}/;
+const URL_RE = /https?:\/\/[^\s"'<>]+\/j\/[0-9a-f]{12}[^\s"'<>]*/;
+
+export function encodeInvite(i: Invite): string {
+  return PREFIX + b64url(JSON.stringify(i));
+}
+
+export function encodeInviteUrl(i: Invite): string {
+  const base = i.u.replace(/\/+$/, "");
+  const qs = new URLSearchParams();
+  if (i.n) qs.set("n", i.n);
+  if (i.p) qs.set("p", i.p);
+  const qstr = qs.toString();
+  const q = qstr ? `?${qstr}` : "";
+  return `${base}/j/${i.r}${q}#${i.s}${i.k ? "." + i.k : ""}`;
+}
+
+/** Accepts a token, a URL, or any text that contains one of them (agents paste whole chat lines). */
+export function decodeInvite(s: string): Invite {
+  const t = s.trim();
+  const url = URL_RE.exec(t)?.[0];
+  if (url) return decodeInviteUrl(url);
+  const tok = TOKEN_RE.exec(t)?.[0] ?? (t.startsWith(PREFIX) ? t : undefined);
+  if (!tok) throw new Error("not a can2cup invite (expected a https://…/j/<room>#<secret> link or a parley1.… token)");
+  const i = JSON.parse(unb64url(tok.slice(PREFIX.length))) as Invite;
+  if (!i.u || !i.r || !i.s) throw new Error("malformed invite");
+  return i;
+}
+
+export function decodeInviteUrl(url: string): Invite {
+  const u = new URL(url);
+  const m = /^(.*)\/j\/([0-9a-f]{12})$/.exec(u.pathname);
+  if (!m) throw new Error("malformed invite link (expected /j/<room>)");
+  const [s, k] = u.hash.replace(/^#/, "").split(".");
+  if (!/^[0-9a-f]{16,}$/.test(s)) throw new Error("invite link is missing its secret (the part after #) — copy the whole link");
+  const n = u.searchParams.get("n") ?? undefined;
+  const p = u.searchParams.get("p") ?? undefined;
+  return { u: u.origin + m[1], r: m[2], s, ...(n ? { n } : {}), ...(p && /^[0-9a-f]{64}$/.test(p) ? { p } : {}), ...(k && /^[0-9a-f]{64}$/.test(k) ? { k } : {}) };
+}
+
+function b64url(s: string): string {
+  const bytes = new TextEncoder().encode(s);
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unb64url(s: string): string {
+  const b = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4);
+  const bin = atob(b);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return new TextDecoder().decode(bytes);
+}

package/src/protocol/semver.ts

@@ -0,0 +1,14 @@
+/** v0.9.0 upgrade protocol: the only comparison both relay and client need. "1.2.3" style; unknown → 0.0.0. */
+export function parseSemver(v: string | null | undefined): [number, number, number] {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec((v ?? "").trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : [0, 0, 0];
+}
+
+/** negative when a < b, 0 when equal, positive when a > b. */
+export function cmpSemver(a: string | null | undefined, b: string | null | undefined): number {
+  const x = parseSemver(a), y = parseSemver(b);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
+  return 0;
+}
+
+export const NO_VERSION = "0.0.0";

package/src/relay/a2a.ts

@@ -0,0 +1,212 @@
+/**
+ * A2A (Agent2Agent, Linux Foundation) conformance layer — v1.0.0 of the spec.
+ *
+ * Why this exists: A2A assumes an agent is an HTTP server at a domain. A can2cup
+ * agent is a Claude Code process on somebody's laptop — no domain, no inbound
+ * port, not always awake. The relay already stands in for that laptop, so it is
+ * also the natural place to host the agent's A2A surface.
+ *
+ * What is conformant here and what deliberately is not:
+ *   - The Agent Card, the JSON-RPC envelope, the error codes and the security
+ *     scheme follow the spec exactly. Do not invent fields.
+ *   - can2cup's own semantics (the principal's outbound mandate, and the ed25519
+ *     per-message signature over a hash-chained transcript) have no home in the
+ *     spec — A2A does per-agent-card JWS but explicitly no per-message signing,
+ *     and expresses no principal->agent authority at all. They are therefore
+ *     declared as A2A extensions, which is the sanctioned way to add meaning
+ *     without forking. Both are `required: false`, so an agent that has never
+ *     heard of can2cup can still talk to us.
+ *   - The room stays can2cup's model. A2A's Task is a delegated unit of work with
+ *     a terminal state; a room is an ongoing multi-party ordered log. We map
+ *     `contextId` to the room id at the boundary and keep RoomDO unchanged.
+ *
+ * INGEST IS CLOSED BY DEFAULT. An inbound A2A message cannot be signed by the
+ * sender's can2cup key (the relay holds no private key, and an external agent has
+ * no can2cup identity), so admitting one means writing a relay-attested envelope
+ * into a transcript whose whole value is that every entry is participant-signed.
+ * That is the same trust downgrade as the LINE `/a` path, which is why it is
+ * marked UNVERIFIED there. Until a room opts in, message/send answers with the
+ * spec's UnsupportedOperation — which is also exactly what a non-opted-in room
+ * will answer once ingest ships, so this endpoint does not lie about itself.
+ */
+import { PROTOCOL_VERSION } from "../protocol/index.js";
+
+export const A2A_PROTOCOL_VERSION = "1.0.0";
+export const A2A_AGENT_VERSION = "0.6.0";
+
+/** JSON-RPC 2.0 plus the A2A-specific range. */
+export const RPC = {
+  parseError: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internalError: -32603,
+  taskNotFound: -32001,
+  taskNotCancelable: -32002,
+  pushNotificationNotSupported: -32003,
+  unsupportedOperation: -32004,
+  contentTypeNotSupported: -32005,
+} as const;
+
+/** Extension identifiers are namespaced under the relay's own origin, so they
+ *  are dereferenceable by whoever is actually running this deployment. */
+export const extUri = (origin: string, name: string): string => `${origin}/ext/${name}/v1`;
+
+export interface CardOptions {
+  origin: string;
+  relayPub?: string;
+}
+
+export function agentCard(o: CardOptions): unknown {
+  return {
+    protocolVersion: A2A_PROTOCOL_VERSION,
+    name: "can2cup relay",
+    description:
+      "Hosts the A2A surface for personal agents that have no server of their own. " +
+      "Each can2cup room is an ordered, hash-chained transcript between agents that each answer " +
+      "to a different human principal; this gateway lets an A2A caller reach one.",
+    version: A2A_AGENT_VERSION,
+    url: `${o.origin}/a2a`,
+    preferredTransport: "JSONRPC",
+    provider: { organization: "can2cup", url: o.origin },
+    documentationUrl: `${o.origin}/`,
+
+    defaultInputModes: ["text/plain", "application/json"],
+    defaultOutputModes: ["text/plain", "application/json"],
+
+    capabilities: {
+      // Truthful, not aspirational. Flip these in the same commit that implements them.
+      streaming: false,
+      pushNotifications: false,
+      stateTransitionHistory: false,
+      extensions: [
+        {
+          uri: extUri(o.origin, "principal-mandate"),
+          description:
+            "Outbound messages are gated on the sending agent's machine by a mandate its human principal " +
+            "wrote: disclosure limits, a commitment ceiling, and what authority it may delegate. A blocked " +
+            "message is never sent, and the agent reports task state input-required rather than failed. " +
+            "A2A expresses no principal-to-agent authority, so this is carried out of band and declared here.",
+          required: false,
+        },
+        {
+          uri: extUri(o.origin, "signed-transcript"),
+          description:
+            "Every participant message carries an ed25519 signature over a canonical envelope whose prev field " +
+            "is the hash of the previous entry, so the room is a hash chain. The relay additionally signs a " +
+            "transcript head (seq, hash, time) on every read, which lets a client that pinned the relay key " +
+            "prove a fork or a truncated tail after the fact. A2A signs the agent card (JWS) but specifies " +
+            "no per-message signing; callers that do not implement this extension are stored relay-attested " +
+            "and shown to participants as UNVERIFIED.",
+          required: false,
+        },
+      ],
+    },
+
+    securitySchemes: {
+      participantCap: {
+        type: "http",
+        scheme: "bearer",
+        description:
+          "A participant capability for one room, issued by POST /rooms/:id/join to the key that signed the " +
+          "join. The invite secret is a join-and-read key and is not accepted here.",
+      },
+    },
+    security: [{ participantCap: [] }],
+
+    skills: [
+      {
+        id: "room-message",
+        name: "Send a message into a can2cup room",
+        description:
+          "Deliver a message to the participants of one room. contextId must be the room's 12-hex id and the " +
+          "bearer token must be a participant capability for that room. Ingest is opt-in per room: a room that " +
+          "has not enabled it answers -32004 UnsupportedOperation.",
+        tags: ["messaging", "relay", "room", "agent-to-agent"],
+        examples: ["Send a review request into room 77ff7ca1be69"],
+        inputModes: ["text/plain"],
+        outputModes: ["text/plain"],
+      },
+      {
+        id: "room-transcript",
+        name: "Read a room transcript",
+        description:
+          "Return a room's ordered, hash-chained transcript from a given sequence number, together with the " +
+          "relay-signed head. Available today over the native REST surface at GET /rooms/:id/messages.",
+        tags: ["history", "audit", "hash-chain"],
+        inputModes: ["application/json"],
+        outputModes: ["application/json"],
+      },
+    ],
+
+    // Informational: how to reach the native surface this gateway fronts.
+    additionalInterfaces: [{ transport: "HTTP+JSON", url: `${o.origin}/rooms` }],
+  };
+}
+
+interface RpcReq { jsonrpc?: string; id?: unknown; method?: unknown; params?: unknown }
+
+const err = (id: unknown, code: number, message: string, data?: unknown): Response =>
+  Response.json({ jsonrpc: "2.0", id: id ?? null, error: { code, message, ...(data ? { data } : {}) } });
+
+/**
+ * JSON-RPC entry point. Every method the card claims is routed here; the ones we
+ * have not built answer with the spec's own codes rather than a 404, so a caller
+ * gets a machine-readable reason instead of a broken endpoint.
+ */
+export async function handleA2A(req: Request, origin: string): Promise<Response> {
+  if (req.method !== "POST") return err(null, RPC.invalidRequest, "A2A JSON-RPC requires POST");
+
+  let body: RpcReq;
+  try {
+    body = (await req.json()) as RpcReq;
+  } catch {
+    return err(null, RPC.parseError, "invalid JSON");
+  }
+
+  const id = body.id ?? null;
+  if (body.jsonrpc !== "2.0" || typeof body.method !== "string") {
+    return err(id, RPC.invalidRequest, 'jsonrpc must be "2.0" and method must be a string');
+  }
+
+  const auth = req.headers.get("authorization") ?? "";
+  const token = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+
+  switch (body.method) {
+    case "message/send":
+    case "message/stream": {
+      if (!token) {
+        return err(id, RPC.invalidRequest, "a participant capability is required (Authorization: Bearer <cap>)");
+      }
+      const p = body.params as { message?: { contextId?: string } } | undefined;
+      const room = p?.message?.contextId ?? "";
+      if (!/^[0-9a-f]{12}$/.test(room)) {
+        return err(id, RPC.invalidParams, "message.contextId must be a 12-hex can2cup room id");
+      }
+      return err(id, RPC.unsupportedOperation, `room ${room} has not enabled A2A ingest`, {
+        reason: "ingest-not-enabled",
+        detail:
+          "A can2cup transcript is participant-signed end to end. An inbound A2A message cannot carry that " +
+          "signature, so admitting it writes a relay-attested entry that participants see as UNVERIFIED. " +
+          "The room's creator must opt in before this is allowed.",
+        extension: extUri(origin, "signed-transcript"),
+      });
+    }
+
+    case "tasks/get":
+      return err(id, RPC.taskNotFound, "no tasks exist: this gateway does not yet create A2A tasks");
+
+    case "tasks/pushNotificationConfig/set":
+    case "tasks/pushNotificationConfig/get":
+      return err(id, RPC.pushNotificationNotSupported, "push notifications are not implemented on this gateway");
+
+    case "agent/getAuthenticatedExtendedCard":
+      return Response.json({ jsonrpc: "2.0", id, result: agentCard({ origin }) });
+
+    default:
+      return err(id, RPC.methodNotFound, `unknown method: ${body.method}`);
+  }
+}
+
+/** Compile-time tie to the can2cup protocol version this gateway fronts. */
+export const PARLEY_PROTOCOL = PROTOCOL_VERSION;

package/src/relay/anchor.ts

@@ -0,0 +1,159 @@
+/**
+ * RFC 3161 trusted timestamps over the transcript head.
+ *
+ * The problem this closes: the relay signs the head, so a client that pinned the
+ * relay key can prove a fork after the fact — but only against a relay that keeps
+ * its key honest. The operator holds that key. For a transcript meant to be cited
+ * later, "trust the operator's clock" is exactly the objection the reader will
+ * raise. A Time Stamping Authority is a neutral third party that signs
+ * "this digest existed at this time", and it is the primitive eIDAS/PAdES/CAdES
+ * already build on, so the attestation is one a lawyer recognises.
+ *
+ * Scope, deliberately: we BUILD the TimeStampReq and STORE the TimeStampResp as
+ * an opaque DER blob. We do not verify the CMS SignedData or walk the TSA's X.509
+ * chain here — doing that properly needs a real PKI stack, and a half-verified
+ * token is worse than an unverified one. Verification belongs where the tooling
+ * exists: `openssl ts -verify`. The relay only checks PKIStatus so it never
+ * stores a rejection as if it were evidence.
+ *
+ * Disabled unless TSA_URL is set. An unset relay answers "not configured" rather
+ * than silently skipping, so nobody believes they have an anchor they do not have.
+ */
+
+// ------------------------------------------------------------------ DER ---
+
+const tag = (t: number, body: Uint8Array): Uint8Array => {
+  const len = body.length;
+  let header: number[];
+  if (len < 0x80) header = [t, len];
+  else {
+    const bytes: number[] = [];
+    for (let n = len; n > 0; n = Math.floor(n / 256)) bytes.unshift(n % 256);
+    header = [t, 0x80 | bytes.length, ...bytes];
+  }
+  const out = new Uint8Array(header.length + len);
+  out.set(header, 0);
+  out.set(body, header.length);
+  return out;
+};
+
+const concat = (...parts: Uint8Array[]): Uint8Array => {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+};
+
+const SEQUENCE = 0x30, INTEGER = 0x02, OCTET_STRING = 0x04, NULL = 0x05, BOOLEAN = 0x01, OID = 0x06;
+
+/** 2.16.840.1.101.3.4.2.1 — id-sha256 */
+const OID_SHA256 = new Uint8Array([0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01]);
+
+export function hexToBytes(hex: string): Uint8Array {
+  if (!/^[0-9a-f]*$/i.test(hex) || hex.length % 2) throw new Error("not hex");
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+export const bytesToB64 = (b: Uint8Array): string => {
+  let s = "";
+  for (const x of b) s += String.fromCharCode(x);
+  return btoa(s);
+};
+
+/**
+ * TimeStampReq ::= SEQUENCE {
+ *   version INTEGER {v1(1)}, messageImprint MessageImprint,
+ *   reqPolicy TSAPolicyId OPTIONAL, nonce INTEGER OPTIONAL,
+ *   certReq BOOLEAN DEFAULT FALSE, extensions [0] IMPLICIT Extensions OPTIONAL }
+ *
+ * `digest` is the sha256 the TSA will attest to — for us, the chain head hash,
+ * which is already a sha256 over the canonical envelope.
+ */
+export function buildTimeStampReq(digest: Uint8Array, nonce: Uint8Array): Uint8Array {
+  if (digest.length !== 32) throw new Error("sha256 digest must be 32 bytes");
+  const algId = tag(SEQUENCE, concat(tag(OID, OID_SHA256), tag(NULL, new Uint8Array(0))));
+  const messageImprint = tag(SEQUENCE, concat(algId, tag(OCTET_STRING, digest)));
+  // DER INTEGER is signed: a leading bit of 1 would read as negative.
+  const n = nonce[0] & 0x80 ? concat(new Uint8Array([0]), nonce) : nonce;
+  return tag(SEQUENCE, concat(
+    tag(INTEGER, new Uint8Array([1])),
+    messageImprint,
+    tag(INTEGER, n),
+    tag(BOOLEAN, new Uint8Array([0xff])), // certReq: ask the TSA to include its cert
+  ));
+}
+
+/**
+ * Read PKIStatus out of a TimeStampResp. Structure:
+ *   TimeStampResp ::= SEQUENCE { status PKIStatusInfo, timeStampToken TST OPTIONAL }
+ *   PKIStatusInfo ::= SEQUENCE { status INTEGER, ... }
+ * 0 = granted, 1 = grantedWithMods; anything else is a rejection.
+ */
+export function readPkiStatus(resp: Uint8Array): number | undefined {
+  let i = 0;
+  const readLen = (): number => {
+    let len = resp[i++];
+    if (len & 0x80) {
+      const n = len & 0x7f;
+      len = 0;
+      for (let k = 0; k < n; k++) len = len * 256 + resp[i++];
+    }
+    return len;
+  };
+  if (resp[i++] !== SEQUENCE) return undefined; // TimeStampResp
+  readLen();
+  if (resp[i++] !== SEQUENCE) return undefined; // PKIStatusInfo
+  readLen();
+  if (resp[i++] !== INTEGER) return undefined;
+  const len = readLen();
+  let v = 0;
+  for (let k = 0; k < len; k++) v = v * 256 + resp[i++];
+  return v;
+}
+
+// ------------------------------------------------------------- request ---
+
+export interface Anchor {
+  seq: number;
+  hash: string;        // the transcript head this attests to
+  requestedAt: string; // relay clock — informational only; the TSA's clock is inside the token
+  tsa: string;
+  status: number;      // PKIStatus: 0 granted, 1 grantedWithMods
+  token: string;       // base64 DER TimeStampResp — verify with `openssl ts -verify`
+}
+
+export class AnchorError extends Error {}
+
+/** POST an RFC 3161 query and return the stored anchor. Throws AnchorError on any
+ *  outcome that is not a granted token, so a failure is never stored as evidence. */
+export async function requestTimestamp(
+  tsaUrl: string, seq: number, headHash: string, nonceHex: string,
+): Promise<Anchor> {
+  const req = buildTimeStampReq(hexToBytes(headHash), hexToBytes(nonceHex));
+  let res: Response;
+  try {
+    res = await fetch(tsaUrl, {
+      method: "POST",
+      headers: { "content-type": "application/timestamp-query" },
+      // workers-types' BodyInit predates TS's generic Uint8Array<ArrayBufferLike>; the
+      // runtime accepts a typed array here. Narrow cast rather than copying the buffer.
+      body: req as unknown as BodyInit,
+    });
+  } catch (e) {
+    throw new AnchorError(`TSA unreachable: ${(e as Error).message}`);
+  }
+  if (!res.ok) throw new AnchorError(`TSA returned HTTP ${res.status}`);
+
+  const body = new Uint8Array(await res.arrayBuffer());
+  if (body.length === 0) throw new AnchorError("TSA returned an empty body");
+  const status = readPkiStatus(body);
+  if (status === undefined) throw new AnchorError("TSA response is not a TimeStampResp");
+  if (status !== 0 && status !== 1) throw new AnchorError(`TSA rejected the request (PKIStatus ${status})`);
+
+  return {
+    seq, hash: headHash, requestedAt: new Date().toISOString(),
+    tsa: tsaUrl, status, token: bytesToB64(body),
+  };
+}