@uuaid/agent-commons 0.2.0-alpha.2 → 0.2.0-alpha.4

package/src/relay/auth.mjs

@@ -0,0 +1,294 @@
+// Cloud Commons relay: request authentication and response signing (spec v3.4.5 sections 6.1,
+// 6.2, 6.3 and 6.5 "Signer = by").
+//
+// Port source (B1): the identity repo at commit cf48f0e, ported verbatim:
+//   packages/pillar-client/src/identity-request.ts - the header name and grammar, the strict
+//     parser (:95-114), the descriptor (:54-66), the body hash (:71-74), the signing bytes
+//     (:77-79) and verifyIdentityRequest;
+//   packages/pillar-client/src/identity.ts - isStrictEd25519PublicKey and verifyBytesStrict
+//     (RFC 8032 strict: canonical A and R, never a small-order or mixed-order key);
+//   apps/api/src/self-auth.ts:41-77 - the verifier order: a stale request is refused unverified;
+//     a future-dated one is verified and refused only after its nonce is spent.
+// The port passes the vector docs/standards/agent-vault-wallet/vectors/identity-auth.json at that
+// commit, with the vector's own audience and namespace (test/relay-auth.test.mjs), before it is
+// used with the relay's.
+//
+// The relay's differences (6.1, 6.3): the audience is one configured string compared byte for byte
+// (never the Host header); the principal header `commons-principal` names the agent and must be an
+// agentnet id (B3); the key comes from the relay's own keys table (D-i); every principal failure is
+// the same 401 {"error":"unauthorized"} after a check against a fixed dummy key; the nonce is spent
+// (UNIQUE(principal, nonce)) before the future check; a replay is 409. On every fleet record
+// the authenticated signer must equal the body's `by` (6.5).
+//
+// 6.2: every relay response carries `commons-relay-sig`, Ed25519 by the relay key over
+// JCS({aud, request_nonce, status, body_sha256}); signRelayResponse takes the relay key seed from
+// its caller (the server) and verifyRelayResponse is the client's check against the pinned key.
+//
+// This module performs no network I/O and stores no private key. The server applies the size
+// cap, the route inventory and the browser-origin refusal before calling authenticateRequest.
+
+import { createHash, randomBytes } from "node:crypto";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { jcs } from "../pillar.mjs";
+import { localIdFromKey } from "../vendor/pillar/identity/keychain.mjs";
+import { keyBindsAgentUuaid } from "../uuaid-namespace.mjs";
+import { RelayError, assertIntegerOnly } from "./records.mjs";
+import { tx } from "./schema.mjs";
+
+// --- verbatim port: identity-request.ts (cf48f0e) ----------------------------------------
+
+export const IDENTITY_AUTH_HEADER = "uuaid-identity-auth";
+export const IDENTITY_REQUEST_TYPE = "uuaid.identity.request.v1";
+/** The methods an identity key may sign. */
+export const IDENTITY_REQUEST_METHODS = Object.freeze(["GET", "PUT", "POST", "DELETE", "PATCH"]);
+
+/** The object the identity key signs. Never transmitted: the verifier rebuilds it. */
+export function identityRequestDescriptor(i) {
+  return {
+    type: IDENTITY_REQUEST_TYPE,
+    aud: i.audience,
+    agent: i.agent,
+    method: i.method.toUpperCase(),
+    path: i.path,
+    query: i.query ?? "",
+    body_sha256: i.bodySha256,
+    created: i.created,
+    nonce: i.nonce,
+  };
+}
+
+/** sha256 hex of JCS(body); null when there is no body. */
+export function identityRequestBodyHash(body) {
+  if (body === undefined || body === null) return null;
+  return createHash("sha256").update(Buffer.from(jcs(body), "utf8")).digest("hex");
+}
+
+/** The exact bytes the identity key signs. */
+export function identityRequestSigningBytes(d) {
+  return Buffer.from(`${IDENTITY_REQUEST_TYPE}\n${jcs(d)}`, "utf8");
+}
+
+export function formatIdentityAuthHeader(h) {
+  return `v=${h.v}; created=${h.created}; nonce=${h.nonce}; ed25519=${h.ed25519}`;
+}
+
+const CREATED_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+
+/** Parse the header strictly: every field once, nothing else. Null on any defect. */
+export function parseIdentityAuthHeader(value) {
+  if (typeof value !== "string" || value.length > 512) return null;
+  const fields = new Map();
+  for (const part of value.split(";")) {
+    const t = part.trim();
+    const eq = t.indexOf("=");
+    if (eq <= 0) return null;
+    const k = t.slice(0, eq);
+    if (fields.has(k)) return null;
+    fields.set(k, t.slice(eq + 1));
+  }
+  const keys = ["v", "created", "nonce", "ed25519"];
+  if (fields.size !== keys.length || !keys.every((k) => fields.has(k))) return null;
+  const created = fields.get("created");
+  if (fields.get("v") !== "1") return null;
+  if (!CREATED_RE.test(created) || Number.isNaN(Date.parse(created))) return null;
+  if (!/^[0-9a-f]{32,64}$/.test(fields.get("nonce"))) return null;
+  if (!/^[0-9a-f]{128}$/.test(fields.get("ed25519"))) return null;
+  return { v: "1", created, nonce: fields.get("nonce"), ed25519: fields.get("ed25519") };
+}
+
+// --- verbatim port: identity.ts (cf48f0e) -------------------------------------------------
+
+export function isStrictEd25519PublicKey(pubKeyHex) {
+  if (typeof pubKeyHex !== "string" || !/^[0-9a-f]{64}$/i.test(pubKeyHex)) return false;
+  const hex = pubKeyHex.toLowerCase();
+  try {
+    const point = ed25519.Point.fromHex(hex, false);
+    return point.toHex() === hex && !point.isSmallOrder() && point.isTorsionFree();
+  } catch {
+    return false;
+  }
+}
+
+export function verifyBytesStrict(pubKeyHex, msg, sigHex) {
+  if (!isStrictEd25519PublicKey(pubKeyHex)) return false;
+  if (typeof sigHex !== "string" || !/^[0-9a-f]{128}$/i.test(sigHex)) return false;
+  try {
+    return ed25519.verify(Buffer.from(sigHex.toLowerCase(), "hex"), msg, Buffer.from(pubKeyHex.toLowerCase(), "hex"), { zip215: false });
+  } catch {
+    return false;
+  }
+}
+
+/** Verify a parsed header against a rebuilt descriptor and the agent's identity key (RFC 8032, prime-order key). */
+export function verifyIdentityRequest(d, h, publicKeyHex) {
+  if (d.created !== h.created || d.nonce !== h.nonce) return false;
+  return verifyBytesStrict(publicKeyHex, identityRequestSigningBytes(d), h.ed25519);
+}
+
+/**
+ * Sign a request with an identity key seed (the reference client's signer; tests). Returns the
+ * header value. The seed never leaves the caller. `created` and `nonce` overrides are for fixed
+ * test vectors only.
+ */
+export function signIdentityRequest({ seedHex, namespace = "agentnet", method, path, query, body, audience, created, nonce }) {
+  const seed = Buffer.from(seedHex, "hex");
+  const pub = Buffer.from(ed25519.getPublicKey(seed));
+  const agent = `uuaid:${namespace}:agent:${localIdFromKey(pub)}`;
+  const c = created ?? new Date().toISOString();
+  const n = nonce ?? randomBytes(16).toString("hex");
+  const d = identityRequestDescriptor({ audience, agent, method, path, query, bodySha256: identityRequestBodyHash(body), created: c, nonce: n });
+  const sig = Buffer.from(ed25519.sign(identityRequestSigningBytes(d), seed)).toString("hex");
+  return { agent, publicKey: pub.toString("hex"), header: formatIdentityAuthHeader({ v: "1", created: c, nonce: n, ed25519: sig }) };
+}
+
+// --- the relay verifier (6.1, 6.3) ----------------------------------------------------------
+
+export const PRINCIPAL_HEADER = "commons-principal";
+/** The test audience (6.1, B5): `.test` is reserved (RFC 6761); a deployed relay is configured with its own origin. */
+export const RELAY_TEST_AUD = "http://commons-relay.test:8080";
+export const AUTH_MAX_AGE_MS = 5 * 60 * 1000;
+export const AUTH_MAX_FUTURE_MS = 60 * 1000;
+export const NONCE_KEEP_MS = 10 * 60 * 1000;   // covers the 6-minute acceptance span (6.1)
+
+/** The uniform refusal (6.3): the same status and body for every principal or signature failure. */
+export const UNAUTHORIZED = Object.freeze({ status: 401, body: Object.freeze({ error: "unauthorized" }) });
+const STALE = Object.freeze({ status: 401, body: Object.freeze({ error: "stale" }) });   // principal-independent (6.3)
+const REPLAY = Object.freeze({ status: 409, body: Object.freeze({ error: "replay" }) });   // reachable only with a valid signature
+
+// A fixed, valid, strict key with no known seed holder: the refusal path for an unknown or
+// ineligible principal still runs one signature check, so it takes similar time (6.3).
+const DUMMY_PUBLIC_KEY = Buffer.from(ed25519.getPublicKey(createHash("sha256").update("commons-relay.dummy-key.v1").digest())).toString("hex");
+
+const AGENTNET_AGENT = /^uuaid:agentnet:agent:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** B3: an agentnet agent id (the only namespace the relay accepts). */
+export const isAgentnetAgent = (value) => typeof value === "string" && AGENTNET_AGENT.test(value);
+const header = (headers, name) => {
+  const v = headers?.[name] ?? headers?.[name.toLowerCase()];
+  return Array.isArray(v) ? null : v;   // a repeated header is a malformed request
+};
+
+/**
+ * The principal a key row names, with the facts the verifier needs, read from the relay's tables
+ * on every request with no cache (M3). Null when the agent has no key row.
+ */
+function principalOf(db, agent) {
+  const k = db.prepare("SELECT public_key, agent, principal_kind, principal_id, status FROM keys WHERE agent = ?").get(agent);
+  if (!k) return null;
+  if (k.principal_kind === "fleet") {
+    const f = db.prepare("SELECT kind, status FROM fleet_principals WHERE principal_id = ?").get(k.principal_id);
+    return { kind: "fleet", id: k.principal_id, agent, publicKey: k.public_key, keyStatus: k.status, fleetKind: f?.kind ?? null, status: f?.status ?? null };
+  }
+  const m = db.prepare("SELECT status, role FROM members WHERE member_id = ?").get(k.principal_id);
+  return { kind: "member", id: k.principal_id, agent, publicKey: k.public_key, keyStatus: k.status, status: m?.status ?? null, role: m?.role ?? null };
+}
+
+/**
+ * Whether this principal may be authenticated on this request (6.1 step 3):
+ * - a fleet principal: an active key of an active roster principal;
+ * - a member: an active key and status active; or, only where `allowPending` (GET /v1/status
+ *   only), a pending member on its pending enrollment key.
+ * Suspended, revoked, unknown, retired and revoked-key principals are ineligible: uniform 401.
+ */
+function eligible(p, allowPending) {
+  if (!p) return false;
+  if (p.kind === "fleet") return p.keyStatus === "active" && p.status === "active";
+  if (p.keyStatus === "active" && p.status === "active") return true;
+  return allowPending && p.keyStatus === "pending" && p.status === "pending";
+}
+
+/**
+ * Authenticate one request (6.1 steps 2-6; 3 and 8 read the tables on every request).
+ * `req` = { method, path, query, headers, body } with `body` the parsed JSON body (undefined when
+ * there is none); `aud` the relay's configured audience; `now` the relay clock in ms.
+ * Returns { ok: true, principal } or { ok: false, status, body }. Throws RelayError
+ * non-integer-number (400) for a body JCS cannot hash, before any signature or nonce work (B4).
+ */
+/** 6.1 `created`: the header grammar's RFC 3339 UTC form (shared with the enrollment flow). */
+export const isCreated = (value) => typeof value === "string" && CREATED_RE.test(value) && !Number.isNaN(Date.parse(value));
+/** 6.1 `nonce`: 32-64 lower-case hex (shared with the enrollment flow). */
+export const isNonce = (value) => typeof value === "string" && /^[0-9a-f]{32,64}$/.test(value);
+
+/**
+ * 6.1 step 5 / 5.2 step 6 (B9): spend (principal, nonce) in the one request-nonce table, pruning
+ * expired rows. Returns false on a replay. The row is kept NONCE_KEEP_MS past max(created, now).
+ */
+export function spendNonce(db, principal, nonce, createdMs, now) {
+  return tx(db, () => {
+    db.prepare("DELETE FROM request_nonces WHERE expires_at <= ?").run(now);
+    const r = db.prepare("INSERT INTO request_nonces(principal, nonce, expires_at) VALUES (?, ?, ?) ON CONFLICT DO NOTHING")
+      .run(principal, nonce, Math.max(createdMs, now) + NONCE_KEEP_MS);
+    return r.changes === 1;
+  });
+}
+
+export function authenticateRequest(db, req, { aud, now, allowPending = false }) {
+  if (typeof aud !== "string" || !aud) throw new RelayError("relay-aud-unset", 500);
+  if (!Number.isSafeInteger(now)) throw new RelayError("invalid-time", 500);
+  // Step 2: parse; a stale request is refused before any principal or signature work.
+  const h = parseIdentityAuthHeader(header(req.headers, IDENTITY_AUTH_HEADER));
+  const agent = header(req.headers, PRINCIPAL_HEADER);
+  if (!h || typeof agent !== "string") return { ok: false, ...UNAUTHORIZED };
+  const created = Date.parse(h.created);
+  if (created < now - AUTH_MAX_AGE_MS) return { ok: false, ...STALE };
+  // B4: integer-only bodies; hashing fails before any signature work, so no nonce is spent.
+  if (req.body !== undefined && req.body !== null) assertIntegerOnly(req.body);
+  const bodySha256 = identityRequestBodyHash(req.body);
+  // Step 3: the principal's current key, from the relay's own tables (D-i); never from the request.
+  const p = AGENTNET_AGENT.test(agent) ? principalOf(db, agent) : null;
+  const ok = eligible(p, allowPending);
+  const key = ok ? p.publicKey : DUMMY_PUBLIC_KEY;
+  // Step 4: strict Ed25519; the key derives the agent in agentnet (B3); the signature over the
+  // descriptor the relay rebuilds from the request it received, with its own audience (B5).
+  const d = identityRequestDescriptor({ audience: aud, agent, method: req.method, path: req.path, query: req.query ?? "", bodySha256, created: h.created, nonce: h.nonce });
+  const verified = verifyIdentityRequest(d, h, key) && isStrictEd25519PublicKey(key) && keyBindsAgentUuaid(agent, key);
+  if (!ok || !verified) return { ok: false, ...UNAUTHORIZED };
+  // Step 5: spend the nonce before the future check. It stays spent even if a later step fails.
+  if (!spendNonce(db, agent, h.nonce, created, now)) return { ok: false, ...REPLAY };
+  // Step 6: more than 60 s ahead is refused, after the nonce is spent.
+  if (created > now + AUTH_MAX_FUTURE_MS) return { ok: false, ...STALE };
+  return { ok: true, principal: { kind: p.kind, id: p.id, agent, status: p.status, ...(p.kind === "fleet" ? { fleetKind: p.fleetKind } : { role: p.role }) } };
+}
+
+/**
+ * 6.5 "Signer = by": a fleet record is accepted only from the fleet principal its
+ * body names. A member principal, or any other fleet principal, gets the uniform 401, so a captured
+ * signed body cannot be re-submitted by another principal.
+ */
+export function signerMatchesBy(principal, body) {
+  return !!principal && principal.kind === "fleet" && !!body && typeof body === "object" && body.by === principal.id;
+}
+
+// --- relay authenticity (6.2) ----------------------------------------------------------------
+
+/** 6.2: the header that carries the relay's signature on every response. */
+export const RELAY_SIG_HEADER = "commons-relay-sig";
+
+/**
+ * 6.2: the bytes the relay signs for one response: JCS({aud, request_nonce, status, body_sha256}),
+ * with body_sha256 defined as in 6.1 (sha256 hex of JCS(body), or null when there is no body).
+ * `requestNonce` is the request's own 6.1 nonce, or null when the request carried no header that parses.
+ */
+export function relayResponseSigningBytes({ aud, requestNonce, status, body }) {
+  if (typeof aud !== "string" || !aud) throw new RelayError("relay-aud-unset", 500);
+  if (!Number.isSafeInteger(status) || status < 100 || status > 599) throw new RelayError("invalid-status", 500);
+  if (requestNonce !== null && !(typeof requestNonce === "string" && /^[0-9a-f]{32,64}$/.test(requestNonce))) throw new RelayError("invalid-nonce", 500);
+  return Buffer.from(jcs({ aud, request_nonce: requestNonce, status, body_sha256: identityRequestBodyHash(body) }), "utf8");
+}
+
+/** Sign a response with the relay key seed (32-byte hex, held by the server only). Returns 128 hex. */
+export function signRelayResponse(relaySeedHex, response) {
+  return Buffer.from(ed25519.sign(relayResponseSigningBytes(response), Buffer.from(relaySeedHex, "hex"))).toString("hex");
+}
+
+/** A client's check (6.2): strict Ed25519 against the pinned 64-hex relay key, byte for byte. */
+export function verifyRelayResponse(relayPublicKeyHex, response, sigHex) {
+  if (typeof relayPublicKeyHex !== "string" || !/^[0-9a-f]{64}$/.test(relayPublicKeyHex)) return false;
+  let bytes;
+  try { bytes = relayResponseSigningBytes(response); } catch { return false; }
+  return isStrictEd25519PublicKey(relayPublicKeyHex) && verifyBytesStrict(relayPublicKeyHex, bytes, sigHex);
+}
+
+/** The request's 6.1 nonce for the response signature: the strict header parse, or null. */
+export function requestNonceOf(headers) {
+  return parseIdentityAuthHeader(header(headers, IDENTITY_AUTH_HEADER))?.nonce ?? null;
+}

package/src/relay/board.mjs

@@ -0,0 +1,223 @@
+// Cloud Commons relay: work board reducer (spec v3.2 sections 11 and 12.1).
+// Every member record runs in one transaction: freeze and status check,
+// idempotency, sweep, permission check, handler, receipt. Only the relay clock
+// decides lease expiry; nothing is replayed after expiry or suspension.
+
+import { randomUUID } from "node:crypto";
+import { tx, getMeta, setMeta } from "./schema.mjs";
+import { openClaim, LEASE_MAX_MS, CLAIM_CAPS } from "./claims.mjs";
+import { RelayError, validateMemberRecord } from "./records.mjs";
+import { appendLog, sha256Hex, canonicalBytes } from "./signing.mjs";
+import { roleOf, permits, isFrozen, expireInTx } from "./governance.mjs";
+import { validatePatchPath, validateUnifiedDiff } from "../collaboration.mjs";
+import { jcs } from "../pillar.mjs";
+
+export { LEASE_MAX_MS, CLAIM_CAPS };
+export const HEARTBEAT_FLOOR_MS = 60000;
+export const CLOCK_ROLLBACK_MS = 5000;
+export const SWEEP_INTERVAL_MS = 15000;
+export const TRIAGE_ATTEMPTS = 3;
+
+/**
+ * Expire live claims whose lease has passed. If the relay clock went back by
+ * more than 5 s, expiries freeze and stay frozen until an AC seat clears the
+ * latch (fail closed). Call inside the caller's transaction.
+ */
+export function sweep(db, now) {
+  // While frozen no lease expires (9.2 Freeze); unfreeze extends live leases by the frozen interval.
+  if (isFrozen(db)) return { frozen: true, expired: [] };
+  const highWater = Number(getMeta(db, "clock_high_water") ?? 0);
+  if (getMeta(db, "clock_suspect") === "1") return { frozen: true, expired: [] };
+  if (now < highWater - CLOCK_ROLLBACK_MS) {
+    setMeta(db, "clock_suspect", "1");
+    appendLog(db, "security", { kind: "clock.suspect", now, high_water: highWater }, highWater);
+    db.prepare("INSERT INTO alerts(at, kind, subject, detail) VALUES (?, 'clock.suspect', NULL, ?)").run(highWater, jcs({ now, high_water: highWater }));
+    return { frozen: true, expired: [] };
+  }
+  if (now > highWater) setMeta(db, "clock_high_water", String(now));
+  // 5.3 and the D items (5.4): unconfirmed enrollments of all three kinds expire after 72 h (the
+  // pending key is revoked for ever), and dead re-bind attempts are recorded. Never while frozen
+  // or clock-suspect: the sweep has returned above.
+  expireInTx(db, now);
+  const expired = db.prepare("SELECT claim_id, task_id, member_id, epoch FROM claims WHERE state = 'live' AND lease_until <= ?").all(now);
+  for (const c of expired) {
+    db.prepare("UPDATE claims SET state = 'expired', released_at = ?, released_reason = 'lease' WHERE claim_id = ?").run(now, c.claim_id);
+    const attempts = db.prepare("SELECT attempts FROM tasks WHERE task_id = ?").get(c.task_id).attempts + 1;
+    db.prepare("UPDATE tasks SET attempts = ?, status = ?, updated_at = ? WHERE task_id = ?")
+      .run(attempts, attempts >= TRIAGE_ATTEMPTS ? "needs-triage" : "open", now, c.task_id);
+    appendLog(db, "board", { kind: "claim.expired", claim_id: c.claim_id, task_id: c.task_id, member_id: c.member_id, epoch: c.epoch, attempts }, now);
+  }
+  return { frozen: false, expired: expired.map(c => ({ ...c })) };
+}
+
+export const runSweep = (db, now) => tx(db, () => sweep(db, now));
+
+/** Fencing (11.3): the named claim must be this member's live claim at this epoch. */
+function liveClaim(db, member, claimId, epoch) {
+  const c = db.prepare("SELECT c.*, d.lease_ms FROM claims c JOIN claim_details d USING(claim_id) WHERE c.claim_id = ?").get(claimId);
+  // Another member's claim is indistinguishable from no claim.
+  if (!c || c.member_id !== member.member_id) throw new RelayError("unknown-claim", 404);
+  if (c.state === "live" && c.epoch === epoch) return c;
+  // R7: a result closes its claim; nothing more may be written against it.
+  if (c.state === "submitted") throw new RelayError("CLAIM_CLOSED", 409);
+  const newest = db.prepare("SELECT max(epoch) e FROM claims WHERE task_id = ?").get(c.task_id).e;
+  if (c.epoch !== epoch || newest > c.epoch) throw new RelayError("STALE_EPOCH", 409);
+  throw new RelayError("CLAIM_EXPIRED", 409);
+}
+
+const HANDLERS = {
+  heartbeat(db, m, role, rec, now) {
+    if (m.last_heartbeat_at !== null && now - m.last_heartbeat_at < HEARTBEAT_FLOOR_MS) throw new RelayError("heartbeat-too-fast", 429);
+    db.prepare("UPDATE member_profiles SET last_heartbeat_at = ?, first_heartbeat_at = coalesce(first_heartbeat_at, ?) WHERE member_id = ?").run(now, now, m.member_id);
+    if (rec.body.claim_id === undefined) return { kind: "heartbeat", at: now };
+    const c = liveClaim(db, m, rec.body.claim_id, rec.body.epoch);
+    const leaseUntil = Math.max(c.lease_until, now + c.lease_ms);
+    db.prepare("UPDATE claims SET lease_until = ? WHERE claim_id = ?").run(leaseUntil, c.claim_id);
+    return { kind: "heartbeat", at: now, claim_id: c.claim_id, epoch: c.epoch, lease_until: leaseUntil };
+  },
+
+  message(db, m, role, rec, now) {
+    if (rec.body.lane !== m.lane) throw new RelayError("forbidden", 403, "lane");
+    const { lastInsertRowid } = db.prepare("INSERT INTO seat_feed(lane, member_id, record_id, type, body, at, state) VALUES (?, ?, ?, 'message', ?, ?, 'pending')")
+      .run(m.lane, m.member_id, rec.record_id, jcs(rec.body), now);
+    return { kind: "message", feed_id: Number(lastInsertRowid) };
+  },
+
+  note(db, m, role, rec, now) {
+    db.prepare("INSERT INTO ext_quarantine(member_id, record_id, body, at) VALUES (?, ?, ?, ?)").run(m.member_id, rec.record_id, jcs(rec.body), now);
+    return { kind: "note", quarantined: true };
+  },
+
+  claim(db, m, role, rec, now) {
+    const task = db.prepare("SELECT * FROM tasks WHERE task_id = ?").get(rec.body.task_id);
+    if (!task) throw new RelayError("unknown-task", 404);
+    if (task.status === "claimed") throw new RelayError("CLAIM_HELD", 409);
+    if (task.status !== "open") throw new RelayError("task-not-open", 409);
+    return { kind: "claim", ...openClaim(db, { taskId: task.task_id, memberId: m.member_id, role, leaseMs: rec.body.lease_ms, now }) };
+  },
+
+  release(db, m, role, rec, now) {
+    const c = liveClaim(db, m, rec.body.claim_id, rec.body.epoch);
+    db.prepare("UPDATE claims SET state = 'released', released_at = ?, released_reason = 'member' WHERE claim_id = ?").run(now, c.claim_id);
+    db.prepare("UPDATE tasks SET status = 'open', updated_at = ? WHERE task_id = ?").run(now, c.task_id);
+    return { kind: "release", claim_id: c.claim_id, task_id: c.task_id };
+  },
+
+  progress(db, m, role, rec, now) {
+    const c = liveClaim(db, m, rec.body.claim_id, rec.body.epoch);
+    db.prepare("INSERT INTO progress(member_id, record_id, claim_id, text, at) VALUES (?, ?, ?, ?, ?)").run(m.member_id, rec.record_id, c.claim_id, rec.body.text, now);
+    return { kind: "progress", claim_id: c.claim_id, epoch: c.epoch };
+  },
+
+  result(db, m, role, rec, now) {
+    const c = liveClaim(db, m, rec.body.claim_id, rec.body.epoch);
+    const task = db.prepare("SELECT * FROM tasks WHERE task_id = ?").get(c.task_id);
+    let stored;
+    if (rec.body.kind === "patch") {
+      const allowed = JSON.parse(task.paths);
+      for (const file of rec.body.body) {
+        try {
+          const path = validatePatchPath(file.path, allowed);
+          if (path !== file.path) throw new Error("path is not in normal form");
+          validateUnifiedDiff(file.path, file.diff);
+        } catch (error) {
+          throw new RelayError("invalid-patch", 422, String(error?.message ?? error).slice(0, 200));
+        }
+      }
+      stored = jcs(rec.body.body);
+    } else stored = rec.body.body;
+    const submissionId = randomUUID(), sha = sha256Hex(stored);
+    db.prepare("INSERT INTO submissions(submission_id, member_id, state) VALUES (?, ?, 'in-review')").run(submissionId, m.member_id);
+    db.prepare(`INSERT INTO submission_details(submission_id, task_id, claim_id, epoch, kind, body, body_sha256, created_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(submissionId, c.task_id, c.claim_id, c.epoch, rec.body.kind, stored, sha, now);
+    db.prepare("UPDATE claims SET state = 'submitted', released_at = ?, released_reason = 'submitted' WHERE claim_id = ?").run(now, c.claim_id);
+    db.prepare("UPDATE tasks SET status = 'in-review', updated_at = ? WHERE task_id = ?").run(now, c.task_id);
+    return { kind: "result", submission_id: submissionId, task_id: c.task_id, body_sha256: sha };
+  },
+
+  evidence(db, m, role, rec, now) {
+    const s = db.prepare("SELECT member_id, state FROM submissions WHERE submission_id = ?").get(rec.body.submission_id);
+    if (!s || s.member_id !== m.member_id) throw new RelayError("unknown-submission", 404);
+    db.prepare("INSERT INTO evidence(member_id, record_id, submission_id, kind, text, at) VALUES (?, ?, ?, ?, ?, ?)")
+      .run(m.member_id, rec.record_id, rec.body.submission_id, rec.body.kind, rec.body.text, now);
+    // Advisory only: evidence is context for reviewers and never counts toward D1.
+    return { kind: "evidence", submission_id: rec.body.submission_id, advisory: true };
+  },
+
+  "review-request"(db, m, role, rec, now) {
+    const s = db.prepare("SELECT member_id FROM submissions WHERE submission_id = ?").get(rec.body.submission_id);
+    if (!s || s.member_id !== m.member_id) throw new RelayError("unknown-submission", 404);
+    db.prepare("INSERT INTO seat_feed(lane, member_id, record_id, type, body, at, state) VALUES (?, ?, ?, 'review-request', ?, ?, 'pending')")
+      .run(m.lane, m.member_id, rec.record_id, jcs(rec.body), now);
+    return { kind: "review-request", submission_id: rec.body.submission_id };
+  },
+
+  propose(db, m, role, rec, now) {
+    // A proposal is a request to seats. A D0 task.open by the lane owner opens it as a task (R4).
+    db.prepare("INSERT INTO seat_feed(lane, member_id, record_id, type, body, at, state) VALUES (?, ?, ?, 'propose', ?, ?, 'pending')")
+      .run(rec.body.lane, m.member_id, rec.record_id, jcs(rec.body), now);
+    return { kind: "propose", queued: true };
+  },
+
+  "advisory-review"(db, m, role, rec, now) {
+    db.prepare("INSERT INTO seat_feed(lane, member_id, record_id, type, body, at, state) VALUES (?, ?, ?, 'advisory-review', ?, ?, 'pending')")
+      .run(m.lane, m.member_id, rec.record_id, jcs(rec.body), now);
+    return { kind: "advisory-review", counts: false };
+  },
+};
+
+function activeMember(db, memberId) {
+  const m = db.prepare(`SELECT m.member_id, m.status, m.role, p.display_name, p.platform, p.lane, p.first_heartbeat_at, p.last_heartbeat_at
+                          FROM members m JOIN member_profiles p USING(member_id) WHERE m.member_id = ?`).get(memberId);
+  // Status is read from the table inside the write transaction, every time (M3).
+  if (!m || m.status !== "active") throw new RelayError("unauthorized", 401);
+  return m;
+}
+
+/**
+ * Apply one member record. `memberId` is the authenticated member: request
+ * verification supplies it in the server, and a test supplies it directly.
+ */
+export function handleMemberRecord(db, memberId, record, now) {
+  const rec = validateMemberRecord(record);
+  const sha = sha256Hex(canonicalBytes(rec));
+  return tx(db, () => {
+    if (isFrozen(db)) throw new RelayError("frozen", 503);
+    const m = activeMember(db, memberId);
+    const prior = db.prepare("SELECT record_sha256, receipt FROM member_records WHERE member_id = ? AND record_id = ?").get(memberId, rec.record_id);
+    if (prior) {
+      if (prior.record_sha256 !== sha) throw new RelayError("record-conflict", 409);
+      return { ...JSON.parse(prior.receipt), replay: true };
+    }
+    sweep(db, now);
+    const role = roleOf(db, memberId);
+    if (!permits("member", role, rec.type)) throw new RelayError("forbidden", 403, rec.type);
+    const receipt = HANDLERS[rec.type](db, m, role, rec, now);
+    db.prepare("INSERT INTO member_records(member_id, record_id, type, record_sha256, receipt, at) VALUES (?, ?, ?, ?, ?, ?)")
+      .run(memberId, rec.record_id, rec.type, sha, jcs(receipt), now);
+    appendLog(db, "board", { kind: `member.${rec.type}`, member_id: memberId, record_id: rec.record_id, record_sha256: sha }, now);
+    return receipt;
+  });
+}
+
+/** The member's own live claims (B8): task, claim id, epoch, lease. */
+export function ownClaims(db, memberId, now) {
+  return tx(db, () => {
+    activeMember(db, memberId);
+    sweep(db, now);
+    return db.prepare(`SELECT c.task_id, c.claim_id, c.epoch, c.lease_until FROM claims c JOIN claim_details d USING(claim_id)
+                        WHERE c.member_id = ? AND c.state = 'live' ORDER BY d.created_at, c.claim_id`).all(memberId).map(r => ({ ...r }));
+  });
+}
+
+/** Member board view (7.5): status only; a claimant is shown only to itself. */
+export function boardView(db, memberId, now) {
+  return tx(db, () => {
+    activeMember(db, memberId);
+    sweep(db, now);
+    return db.prepare(`SELECT t.task_id, t.title, t.lane, t.kind, t.status, t.base_commit,
+                              EXISTS (SELECT 1 FROM claims c WHERE c.task_id = t.task_id AND c.state = 'live' AND c.member_id = ?) AS mine
+                         FROM tasks t WHERE t.status IN ('open','claimed','in-review','held') ORDER BY t.created_at`)
+      .all(memberId).map(r => ({ ...r, mine: r.mine === 1 }));
+  });
+}

package/src/relay/claims.mjs

@@ -0,0 +1,25 @@
+// Cloud Commons relay: opening a claim (spec v3.2 section 11.3). One path
+// for a member's own claim, a lane owner's task.assign and the new claim a seat's
+// "changes" issues, so epochs, leases and caps cannot drift between them.
+// Call inside the caller's transaction.
+
+import { randomUUID } from "node:crypto";
+import { RelayError } from "./records.mjs";
+
+export const LEASE_MAX_MS = 86400000;
+export const CLAIM_CAPS = Object.freeze({ C0: 0, C1: 1, C2: 3, C3: 5 });
+
+/** decisionId: the seat decision that opened the claim (task.assign, review.changes), recorded for its reversal (C3). */
+export function openClaim(db, { taskId, memberId, role, leaseMs, now, decisionId = null }) {
+  const live = db.prepare("SELECT count(*) n FROM claims WHERE member_id = ? AND state = 'live'").get(memberId).n;
+  if (live >= (CLAIM_CAPS[role] ?? 0)) throw new RelayError("claim-cap", 409);
+  const lease = Math.min(leaseMs ?? LEASE_MAX_MS, LEASE_MAX_MS);
+  const epoch = (db.prepare("SELECT max(epoch) e FROM claims WHERE task_id = ?").get(taskId).e ?? 0) + 1;
+  const claimId = randomUUID();
+  db.prepare(`INSERT INTO claims(claim_id, task_id, member_id, epoch, state, lease_until, released_reason, released_at)
+              VALUES (?, ?, ?, ?, 'live', ?, NULL, NULL)`).run(claimId, taskId, memberId, epoch, now + lease);
+  db.prepare("INSERT INTO claim_details(claim_id, lease_ms, created_at) VALUES (?, ?, ?)").run(claimId, lease, now);
+  if (decisionId) db.prepare("INSERT INTO claim_origins(claim_id, decision_id) VALUES (?, ?)").run(claimId, decisionId);
+  db.prepare("UPDATE tasks SET status = 'claimed', updated_at = ? WHERE task_id = ?").run(now, taskId);
+  return { task_id: taskId, claim_id: claimId, epoch, lease_until: now + lease };
+}

package/src/relay/cli.mjs

@@ -0,0 +1,49 @@
+// Cloud Commons relay: the `agent-commons relay ...` command.
+//
+//   agent-commons relay serve ...              the production relay (serve.mjs; no test flag)
+//   agent-commons relay <client command> ...   the reference client (client.mjs runClientCommand):
+//     mint | enroll --invite-file <f> [--display-name <s> --platform <s>] | adopt-next-key | status |
+//     seed | claims | board | send --type <t> --record-id <id> --body-json <json> | drain |
+//     run-once [--wait <s>] | handled | outbox
+//   every client command takes --state <absolute private directory> and optionally --relay-url <url>
+//   (default: the relay origin pinned from the invite).
+//
+// Security invariant: neither path accepts --test-mode, --test-dir or --test-interface; they are unknown arguments
+// here and exit 2. The test entrypoints are src/relay/server.mjs and src/relay/client.mjs, run directly.
+// Seat (fleet) commands are not here: they sign with seat keys whose custody is an owner decision.
+
+import { serveMain } from "./serve.mjs";
+import { CLIENT_COMMANDS, CLIENT_VALUE_FLAGS, runClientCommand } from "./client.mjs";
+
+export const RELAY_USAGE = `agent-commons relay serve --aud https://<host> --bind <loopback ip> [--port <n>] --db <relay*.db>
+    --roster <signed roster> --policy <signed policy> --owner-public-key <64 hex> --relay-key-file <key seed file> [--access-log <file>]
+agent-commons relay ${CLIENT_COMMANDS.join("|")} --state <private dir> [--relay-url <url>]
+    enroll --invite-file <f> [--display-name <s> --platform <s>]; send --type <t> --record-id <id> --body-json <json>; run-once [--wait <s>]`;
+
+/** Run the relay command. Returns the exit status it set (the server keeps the process alive). */
+export async function relayCli(argv, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const [command, ...rest] = argv;
+  if (command === "serve") { await serveMain(rest, { stdout, stderr }); return process.exitCode ?? 0; }
+  if (command === undefined || command === "help" || command === "--help") { stdout.write(`${RELAY_USAGE}\n`); return 0; }
+  const o = {};
+  let usage = !CLIENT_COMMANDS.includes(command);
+  for (let i = 0; !usage && i < rest.length; i++) {
+    if (!CLIENT_VALUE_FLAGS.includes(rest[i]) || i + 1 >= rest.length || Object.hasOwn(o, rest[i].slice(2))) { usage = true; break; }
+    o[rest[i].slice(2)] = rest[++i];
+  }
+  if (usage) {
+    stdout.write(`${JSON.stringify({ ok: false, error: "usage" })}\n`);
+    stderr.write(`${RELAY_USAGE}\n`);
+    process.exitCode = 2;
+    return 2;
+  }
+  try {
+    const result = await runClientCommand(command, o);
+    stdout.write(`${JSON.stringify({ ok: true, result })}\n`);
+    return 0;
+  } catch (error) {
+    stdout.write(`${JSON.stringify({ ok: false, error: error?.code ?? "error", status: error?.status ?? null, detail: String(error?.message ?? error).slice(0, 300) })}\n`);
+    process.exitCode = 1;
+    return 1;
+  }
+}