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

package/src/relay/mailbox.mjs

@@ -0,0 +1,103 @@
+// Cloud Commons relay: store-and-forward mailbox core (spec v3.2 sections
+// 11.5 and 7.6). Each record for a member gets a per-member seq that is never
+// reused. A read without a cursor resumes after the member's last ack, so a
+// client that lost its state gets exactly what it had not acknowledged.
+
+import { tx, getMeta } from "./schema.mjs";
+import { RelayError, isRecordId } from "./records.mjs";
+import { sha256Hex, canonicalBytes, appendLog } from "./signing.mjs";
+import { jcs } from "../pillar.mjs";
+
+export const MAILBOX_LIMITS = Object.freeze({
+  maxUndelivered: 500,
+  maxUndeliveredBytes: 2 * 1024 * 1024,
+  pageSize: 100,
+  ackedRetentionMs: 7 * 86400000,
+  unackedRetentionMs: 14 * 86400000,
+});
+
+export const relayEpoch = (db) => getMeta(db, "epoch");
+
+function mailboxState(db, memberId) {
+  db.prepare("INSERT OR IGNORE INTO mailbox_state(member_id) VALUES (?)").run(memberId);
+  return db.prepare("SELECT next_seq, acked_through FROM mailbox_state WHERE member_id = ?").get(memberId);
+}
+
+function readableMember(db, memberId) {
+  const m = db.prepare("SELECT status FROM members WHERE member_id = ?").get(memberId);
+  if (!m || m.status !== "active") throw new RelayError("unauthorized", 401);
+}
+
+/** Deliver one record to a member's mailbox. Call inside the caller's transaction. Idempotent on record_id. */
+export function deliverInTx(db, memberId, { record_id, sender, type, body }, now) {
+  if (!isRecordId(record_id)) throw new RelayError("invalid-field", 400, "record_id");
+  const member = db.prepare("SELECT status FROM members WHERE member_id = ?").get(memberId);
+  if (!member || member.status === "revoked") throw new RelayError("unknown-recipient", 404);
+  const text = jcs(body);
+  const sha = sha256Hex(canonicalBytes({ sender, type, body }));
+  const prior = db.prepare("SELECT seq, body_sha256 FROM mailbox WHERE member_id = ? AND record_id = ?").get(memberId, record_id);
+  if (prior) {
+    if (prior.body_sha256 !== sha) throw new RelayError("record-conflict", 409);
+    return { seq: prior.seq, duplicate: true };
+  }
+  const bytes = Buffer.byteLength(text, "utf8");
+  const load = db.prepare("SELECT count(*) n, coalesce(sum(bytes), 0) b FROM mailbox WHERE member_id = ? AND acked_at IS NULL AND expired_at IS NULL").get(memberId);
+  if (load.n >= MAILBOX_LIMITS.maxUndelivered || load.b + bytes > MAILBOX_LIMITS.maxUndeliveredBytes) throw new RelayError("mailbox-full", 507);
+  const state = mailboxState(db, memberId);
+  db.prepare(`INSERT INTO mailbox(member_id, seq, record_id, sender, type, body, body_sha256, bytes, created_at)
+              VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(memberId, state.next_seq, record_id, sender, type, text, sha, bytes, now);
+  db.prepare("UPDATE mailbox_state SET next_seq = ? WHERE member_id = ?").run(state.next_seq + 1, memberId);
+  appendLog(db, "mailbox", { kind: "delivered", member_id: memberId, seq: state.next_seq, record_id, sender, type, sha256: sha }, now);
+  return { seq: state.next_seq, duplicate: false };
+}
+
+/**
+ * Read up to one page. `after` omitted resumes after the member's last ack (B8).
+ * Expired records are skipped; the page says where the next read starts.
+ */
+export function readInbox(db, memberId, { after } = {}, now) {
+  return tx(db, () => {
+    readableMember(db, memberId);
+    const state = mailboxState(db, memberId);
+    const from = after === undefined ? state.acked_through : after;
+    if (!Number.isSafeInteger(from) || from < 0) throw new RelayError("invalid-field", 400, "after");
+    const rows = db.prepare(`SELECT seq, record_id, sender, type, body, created_at FROM mailbox
+                              WHERE member_id = ? AND seq > ? AND expired_at IS NULL ORDER BY seq LIMIT ?`)
+      .all(memberId, from, MAILBOX_LIMITS.pageSize);
+    return {
+      epoch: relayEpoch(db),
+      acked_through: state.acked_through,
+      records: rows.map(r => ({ seq: r.seq, record_id: r.record_id, sender: r.sender, type: r.type, body: JSON.parse(r.body), created_at: r.created_at })),
+      next_after: rows.length ? rows.at(-1).seq : from,
+    };
+  });
+}
+
+/** Acknowledge through seq. Lower or equal acks are no-ops; acks beyond what was delivered are refused. */
+export function ackInbox(db, memberId, through, now) {
+  return tx(db, () => {
+    readableMember(db, memberId);
+    const state = mailboxState(db, memberId);
+    if (!Number.isSafeInteger(through) || through < 0) throw new RelayError("invalid-field", 400, "through");
+    if (through >= state.next_seq) throw new RelayError("ack-beyond-delivered", 400);
+    if (through <= state.acked_through) return { acked_through: state.acked_through };
+    db.prepare("UPDATE mailbox SET acked_at = ? WHERE member_id = ? AND seq > ? AND seq <= ? AND acked_at IS NULL AND expired_at IS NULL")
+      .run(now, memberId, state.acked_through, through);
+    db.prepare("UPDATE mailbox_state SET acked_through = ? WHERE member_id = ?").run(through, memberId);
+    appendLog(db, "mailbox", { kind: "acked", member_id: memberId, through }, now);
+    return { acked_through: through };
+  });
+}
+
+/** Retention (7.6): acked records go after 7 days; unacked ones expire after 14 days with a logged event. */
+export function pruneMailbox(db, now) {
+  return tx(db, () => {
+    const removed = db.prepare("DELETE FROM mailbox WHERE acked_at IS NOT NULL AND acked_at <= ?").run(now - MAILBOX_LIMITS.ackedRetentionMs).changes;
+    const stale = db.prepare("SELECT member_id, seq, record_id FROM mailbox WHERE acked_at IS NULL AND expired_at IS NULL AND created_at <= ?").all(now - MAILBOX_LIMITS.unackedRetentionMs);
+    for (const r of stale) {
+      db.prepare("UPDATE mailbox SET expired_at = ? WHERE member_id = ? AND seq = ?").run(now, r.member_id, r.seq);
+      appendLog(db, "mailbox", { kind: "expired", member_id: r.member_id, seq: r.seq, record_id: r.record_id }, now);
+    }
+    return { removed: Number(removed), expired: stale.length };
+  });
+}

package/src/relay/records.mjs

@@ -0,0 +1,146 @@
+// Cloud Commons relay: record types, field allowlists, size caps and the
+// text sanitizer (spec v3.2 sections 7.1-7.3, 11.4). Pure; no I/O.
+
+export class RelayError extends Error {
+  constructor(code, status = 400, detail) {
+    super(detail ? `${code}: ${detail}` : code);
+    this.name = "RelayError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export const RECORD_CAPS = Object.freeze({ record: 65536, patch: 262144, enrollment: 4096 });
+export const PATCH_MAX_FILES = 20;
+export const ROLES = Object.freeze(["C0", "C1", "C2", "C3"]);
+
+// Signed fleet record formats (version tags). Kept here so the reducer and the
+// offline export verifier share them without importing each other.
+export const DECISION_V = "commons-relay-decision/1";
+// /2 binds the verdict's position: seq is the signer's next verdict number on
+// the decision, prev the sha256 of the signer's previous signed verdict body there.
+export const APPROVAL_V = "commons-relay-approval/2";
+export const VERIFY_V = "commons-relay-verify/1";
+export const SECURITY_V = "commons-relay-security/1";
+export const OWNER_CONFIRM_V = "commons-relay-owner-confirm/1";
+export const COAUTHOR_V = "commons-relay-coauthor/1";
+export const SEAT_MESSAGE_V = "commons-relay-seat-message/1";
+export const FINDING_OPEN_V = "commons-relay-finding-open/1";
+export const FINDING_CLOSE_V = "commons-relay-finding-close/1";
+// The family a seat ASSERTS in its served_by, "measured:<family>[:<model>]". Under spec
+// 9.8 an assertion alone earns no family credit: credit needs a measurer's
+// attestation of that verdict whose family equals this assertion.
+const MEASURED = /^measured:([a-z][a-z0-9-]{0,31})(?::[A-Za-z0-9._/@+-]{1,80})?$/;
+export const measuredFamily = (servedBy) => MEASURED.exec(typeof servedBy === "string" ? servedBy : "")?.[1] ?? null;
+
+// C5 (9.8): a measurer's evidence of which model really served a verdict's turn.
+export const ATTEST_V = "commons-relay-attest/1";
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+
+/** JCS refuses fractions; the relay also refuses integers outside +/-(2^53-1) (B4). */
+export function assertIntegerOnly(value, path = "body") {
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value)) throw new RelayError("non-integer-number", 400, path);
+    return;
+  }
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (Array.isArray(value)) { value.forEach((v, i) => assertIntegerOnly(v, `${path}[${i}]`)); return; }
+  if (typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+    for (const [k, v] of Object.entries(value)) assertIntegerOnly(v, `${path}.${k}`);
+    return;
+  }
+  throw new RelayError("unsupported-value", 400, path);
+}
+
+// Refused, never stripped (7.3): C0 controls except tab and newline (CR included),
+// DEL, C1 controls, every format character (Cf, which covers bidi controls,
+// zero-width characters, BOM, soft hyphen, U+061C), and U+2028/U+2029.
+const FORBIDDEN = new RegExp("[\\u0000-\\u0008\\u000B-\\u001F\\u007F-\\u009F\\u2028\\u2029\\p{Cf}]", "u");
+
+export function sanitizeText(value, { field = "text", max, patch = false } = {}) {
+  if (typeof value !== "string") throw new RelayError("invalid-field", 400, `${field} must be text`);
+  if (!value.isWellFormed()) throw new RelayError("invalid-utf8", 400, field);
+  let text = value.normalize("NFC");
+  if (patch) text = text.replace(/\r\n/g, "\n");
+  if (FORBIDDEN.test(text)) throw new RelayError("hidden-character", 422, field);
+  if (max !== undefined && Buffer.byteLength(text, "utf8") > max) throw new RelayError("field-too-long", 400, field);
+  return text;
+}
+
+const id = (v, f) => { if (typeof v !== "string" || !ID.test(v)) throw new RelayError("invalid-field", 400, f); return v; };
+const int = (v, f, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) => {
+  if (!Number.isSafeInteger(v) || v < min || v > max) throw new RelayError("invalid-field", 400, f);
+  return v;
+};
+const oneOf = (values) => (v, f) => { if (!values.includes(v)) throw new RelayError("invalid-field", 400, f); return v; };
+const text = (max) => (v, f) => sanitizeText(v, { field: f, max });
+
+// Member record types (7.2). minRole is enforced by the permission table in
+// governance.mjs; it is repeated here only so the two tables can be compared.
+export const MEMBER_RECORD_TYPES = Object.freeze({
+  heartbeat: { minRole: "C0", fields: { claim_id: [id, false], epoch: [(v, f) => int(v, f, { min: 1 }), false] } },
+  message: { minRole: "C0", fields: { lane: [id, true], text: [text(8192), true], reply_to: [id, false] } },
+  note: { minRole: "C0", fields: { text: [text(4096), true] } },
+  claim: { minRole: "C1", fields: { task_id: [id, true], lease_ms: [(v, f) => int(v, f, { min: 60000, max: 86400000 }), false] } },
+  release: { minRole: "C1", fields: { claim_id: [id, true], epoch: [(v, f) => int(v, f, { min: 1 }), true] } },
+  progress: { minRole: "C1", fields: { claim_id: [id, true], epoch: [(v, f) => int(v, f, { min: 1 }), true], text: [text(2048), true] } },
+  result: { minRole: "C1", fields: { claim_id: [id, true], epoch: [(v, f) => int(v, f, { min: 1 }), true], kind: [oneOf(["patch", "report"]), true], body: [null, true] } },
+  evidence: { minRole: "C1", fields: { submission_id: [id, true], kind: [id, true], text: [text(16384), true] } },
+  "review-request": { minRole: "C1", fields: { submission_id: [id, true] } },
+  propose: { minRole: "C2", fields: { title: [text(120), true], description: [text(4096), true], lane: [id, true], acceptance: [text(4096), true] } },
+  "advisory-review": { minRole: "C2", fields: { target: [id, true], verdict: [oneOf(["looks-good", "concern"]), true], text: [text(4096), true] } },
+});
+
+/**
+ * Validate one member record {type, record_id, body}. Order (7.1): size cap,
+ * known type, integer-only, strict field allowlist, per-field checks and
+ * sanitizing. Returns a normalized copy; never mutates the input.
+ */
+export function validateMemberRecord(record) {
+  if (!record || typeof record !== "object" || Array.isArray(record)) throw new RelayError("invalid-record", 400);
+  const type = record.type;
+  const cap = type === "result" ? RECORD_CAPS.patch : RECORD_CAPS.record;
+  let bytes;
+  try { bytes = Buffer.byteLength(JSON.stringify(record), "utf8"); } catch { throw new RelayError("invalid-record", 400); }
+  if (bytes > cap) throw new RelayError("record-too-large", 413);
+  const spec = Object.hasOwn(MEMBER_RECORD_TYPES, type) ? MEMBER_RECORD_TYPES[type] : null;
+  if (!spec) throw new RelayError("unknown-record-type", 400, String(type).slice(0, 40));
+  for (const key of Object.keys(record)) if (!["type", "record_id", "body"].includes(key)) throw new RelayError("unknown-field", 400, key);
+  assertIntegerOnly(record);
+  const recordId = id(record.record_id, "record_id");
+  const body = record.body;
+  if (!body || typeof body !== "object" || Array.isArray(body)) throw new RelayError("invalid-record", 400, "body");
+  for (const key of Object.keys(body)) if (!Object.hasOwn(spec.fields, key)) throw new RelayError("unknown-field", 400, key);
+  const out = {};
+  for (const [field, [check, required]] of Object.entries(spec.fields)) {
+    if (!Object.hasOwn(body, field) || body[field] === null) {
+      if (required) throw new RelayError("missing-field", 400, field);
+      continue;
+    }
+    out[field] = check ? check(body[field], field) : body[field];
+  }
+  if (type === "heartbeat" && (out.claim_id === undefined) !== (out.epoch === undefined)) throw new RelayError("invalid-field", 400, "claim_id and epoch go together");
+  if (type === "result") out.body = validateResultBody(out.kind, body.body);
+  return { type, record_id: recordId, body: out };
+}
+
+/** A patch result is a list of {path, diff}, one diff per file, at most 20 files (12.1). A report is text. */
+function validateResultBody(kind, value) {
+  if (kind === "report") return sanitizeText(value, { field: "body", max: RECORD_CAPS.record });
+  if (!Array.isArray(value) || value.length === 0) throw new RelayError("invalid-field", 400, "body must list patch files");
+  if (value.length > PATCH_MAX_FILES) throw new RelayError("too-many-files", 400);
+  const seen = new Set();
+  return value.map((file, i) => {
+    if (!file || typeof file !== "object" || Array.isArray(file)) throw new RelayError("invalid-field", 400, `body[${i}]`);
+    for (const key of Object.keys(file)) if (!["path", "diff"].includes(key)) throw new RelayError("unknown-field", 400, `body[${i}].${key}`);
+    const path = sanitizeText(file.path, { field: `body[${i}].path`, max: 512 });
+    if (seen.has(path)) throw new RelayError("invalid-field", 400, `duplicate path ${path}`);
+    seen.add(path);
+    return { path, diff: sanitizeText(file.diff, { field: `body[${i}].diff`, max: RECORD_CAPS.patch, patch: true }) };
+  });
+}
+
+export const isHex64 = (v) => typeof v === "string" && HEX64.test(v);
+export const isRecordId = (v) => typeof v === "string" && ID.test(v);

package/src/relay/render.mjs

@@ -0,0 +1,38 @@
+// Cloud Commons relay: seat-side renderer (spec v3.2 section 7.4).
+// The header is built from relay metadata, never from record text. Content is
+// inert text in a fence longer than any backtick run inside it: no HTML, no
+// markdown rendering, no links or images. Record content never carries an
+// order, a grant, an approval or a credential request, even when it reads as one.
+
+const DOT = " \u00B7 ";
+
+function fence(text) {
+  const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map(m => m[0].length));
+  return "`".repeat(Math.max(3, longest + 1));
+}
+
+/** meta: relay-owned fields {type, member_id, agent, display_name, role, at}. content: the record's text. */
+export function renderMemberRecord(meta, content) {
+  const text = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+  const header = [
+    "EXTERNAL (untrusted)",
+    String(meta.type),
+    `member ${meta.member_id} (current ${meta.agent ?? "unknown"})`,
+    JSON.stringify(String(meta.display_name ?? "")),
+    `role ${meta.role ?? "none"}`,
+    new Date(meta.at).toISOString(),
+  ].join(DOT);
+  const f = fence(text);
+  return `${header}\n${f}text\n${text}\n${f}`;
+}
+
+/** Render the pending seat feed for a lane, oldest first, using relay metadata only. */
+export function renderSeatFeed(db, lane) {
+  const rows = db.prepare(`SELECT f.*, p.display_name, m.role,
+                                  (SELECT agent FROM keys k WHERE k.principal_kind = 'member' AND k.principal_id = f.member_id AND k.status = 'active') AS agent
+                             FROM seat_feed f JOIN members m USING(member_id) JOIN member_profiles p USING(member_id)
+                            WHERE f.lane = ? AND f.state = 'pending' ORDER BY f.feed_id`).all(lane);
+  return rows.map(r => renderMemberRecord(
+    { type: r.type, member_id: r.member_id, agent: r.agent, display_name: r.display_name, role: r.role, at: r.at },
+    JSON.parse(r.body)));
+}

package/src/relay/roster.mjs

@@ -0,0 +1,134 @@
+// Cloud Commons relay: owner-signed roster and policy files (spec v3.2
+// sections 9.1, 9.2 D3, 12.3). The relay loads both at start and refuses to start
+// on a bad signature. No API changes either one. The owner key is pinned by the
+// operator, outside the files, so a file cannot vouch for itself.
+
+import { tx, getMeta, setMeta, openRelayDb } from "./schema.mjs";
+import { RelayError, isRecordId, sanitizeText } from "./records.mjs";
+import { verifyBody, canonicalBytes, sha256Hex, appendLog } from "./signing.mjs";
+import { keyBindsAgentUuaid } from "../uuaid-namespace.mjs";
+import { jcs } from "../pillar.mjs";
+
+export const ROSTER_V = "commons-relay-roster/1";
+export const POLICY_V = "commons-relay-policy/1";
+const KINDS = ["ac-seat", "verifier", "security", "scope", "owner", "measurer"];
+const HEX64 = /^[0-9a-f]{64}$/;
+
+function verifyOwnerSigned(signed, version, ownerPublicKey, what) {
+  if (typeof ownerPublicKey !== "string" || !HEX64.test(ownerPublicKey)) throw new RelayError(`${what}-owner-key-unpinned`, 500);
+  const body = signed?.body;
+  if (!body || typeof body !== "object" || body.v !== version) throw new RelayError(`${what}-invalid`, 500, "version");
+  if (!Number.isSafeInteger(body.version) || body.version < 1 || !Number.isSafeInteger(body.issued_at)) throw new RelayError(`${what}-invalid`, 500, "version/issued_at");
+  if (!verifyBody(ownerPublicKey, body, signed.sig)) throw new RelayError(`${what}-signature`, 500);
+  return { body, sha: sha256Hex(canonicalBytes({ body, sig: signed.sig })) };
+}
+
+/** Version rule shared by both files: same version must be the same bytes; never go back. */
+function versionCheck(db, what, version, sha) {
+  const current = Number(getMeta(db, `${what}_version`) ?? 0);
+  if (version < current) throw new RelayError(`${what}-version-rollback`, 500);
+  if (version === current) {
+    if (getMeta(db, `${what}_sha256`) !== sha) throw new RelayError(`${what}-version-reused`, 500);
+    return false;   // already loaded
+  }
+  return true;
+}
+
+/**
+ * Load the owner-signed roster. New principals are added with their keys; an
+ * existing principal's kind, family and key never change; a principal absent
+ * from a newer roster is retired and its key revoked. A retired principal cannot
+ * return (one key ever).
+ */
+export function loadRoster(db, signed, { ownerPublicKey, now }) {
+  const { body, sha } = verifyOwnerSigned(signed, ROSTER_V, ownerPublicKey, "roster");
+  for (const key of Object.keys(body)) if (!["v", "version", "issued_at", "principals"].includes(key)) throw new RelayError("roster-invalid", 500, key);
+  const list = body.principals;
+  if (!Array.isArray(list) || !list.length) throw new RelayError("roster-invalid", 500, "principals");
+  const ids = new Set(), keys = new Set();
+  for (const p of list) {
+    for (const key of Object.keys(p)) if (!["principal_id", "kind", "runtime_family", "public_key", "agent"].includes(key)) throw new RelayError("roster-invalid", 500, key);
+    if (!isRecordId(p.principal_id) || ids.has(p.principal_id)) throw new RelayError("roster-invalid", 500, "principal_id");
+    if (!KINDS.includes(p.kind)) throw new RelayError("roster-invalid", 500, "kind");
+    if (p.runtime_family !== null && !(typeof p.runtime_family === "string" && /^[a-z][a-z0-9-]{0,31}$/.test(p.runtime_family))) throw new RelayError("roster-invalid", 500, "runtime_family");
+    if (!HEX64.test(p.public_key ?? "") || keys.has(p.public_key)) throw new RelayError("roster-invalid", 500, "public_key");
+    if (!keyBindsAgentUuaid(p.agent, p.public_key) || !p.agent.startsWith("uuaid:agentnet:")) throw new RelayError("roster-invalid", 500, "agent");
+    ids.add(p.principal_id); keys.add(p.public_key);
+  }
+  const owners = list.filter(p => p.kind === "owner");
+  if (owners.length !== 1 || owners[0].public_key !== ownerPublicKey) throw new RelayError("roster-owner-mismatch", 500);
+  return tx(db, () => {
+    if (!versionCheck(db, "roster", body.version, sha)) return { loaded: false, version: body.version };
+    for (const p of list) {
+      const existing = db.prepare(`SELECT f.kind, f.runtime_family, f.status, k.public_key FROM fleet_principals f
+                                     LEFT JOIN keys k ON k.principal_kind = 'fleet' AND k.principal_id = f.principal_id WHERE f.principal_id = ?`).get(p.principal_id);
+      if (!existing) {
+        db.prepare("INSERT INTO fleet_principals(principal_id, kind, runtime_family, status) VALUES (?, ?, ?, 'active')").run(p.principal_id, p.kind, p.runtime_family);
+        db.prepare("INSERT INTO keys(public_key, agent, principal_kind, principal_id, status, added_at, revoked_at) VALUES (?, ?, 'fleet', ?, 'active', ?, NULL)")
+          .run(p.public_key, p.agent, p.principal_id, now);
+      } else {
+        if (existing.status === "retired") throw new RelayError("roster-retired-principal", 500, p.principal_id);
+        if (existing.kind !== p.kind || existing.runtime_family !== p.runtime_family || existing.public_key !== p.public_key)
+          throw new RelayError("roster-binding-changed", 500, p.principal_id);
+      }
+    }
+    for (const { principal_id } of db.prepare("SELECT principal_id FROM fleet_principals WHERE status = 'active'").all()) {
+      if (ids.has(principal_id)) continue;
+      db.prepare("UPDATE fleet_principals SET status = 'retired' WHERE principal_id = ?").run(principal_id);
+      db.prepare("UPDATE keys SET status = 'revoked', revoked_at = ? WHERE principal_kind = 'fleet' AND principal_id = ? AND status <> 'revoked'").run(now, principal_id);
+    }
+    db.prepare("INSERT INTO signed_files(kind, version, body, sig, loaded_at) VALUES ('roster', ?, ?, ?, ?)").run(body.version, jcs(body), signed.sig, now);
+    setMeta(db, "roster_version", body.version);
+    setMeta(db, "roster_sha256", sha);
+    appendLog(db, "security", { kind: "roster.loaded", version: body.version, sha256: sha, principals: list.length }, now);
+    return { loaded: true, version: body.version };
+  });
+}
+
+/** Load the owner-signed policy: lane owners, the 12.3 security path list and the C5 model -> family map. */
+export function loadPolicy(db, signed, { ownerPublicKey, now }) {
+  const { body, sha } = verifyOwnerSigned(signed, POLICY_V, ownerPublicKey, "policy");
+  for (const key of Object.keys(body)) if (!["v", "version", "issued_at", "lanes", "security_paths", "family_map"].includes(key)) throw new RelayError("policy-invalid", 500, key);
+  // C5 (9.8): the fixed map of a served model name to its family. Exactly one pattern must
+  // match a model for it to earn credit; unknown names earn nothing.
+  const map = body.family_map;
+  if (!Array.isArray(map) || !map.length || map.some(e => !e || typeof e !== "object" || Object.keys(e).some(k => !["pattern", "family"].includes(k))
+    || typeof e.pattern !== "string" || !/^[A-Za-z][A-Za-z0-9.*?_-]{0,63}$/.test(e.pattern)
+    || typeof e.family !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(e.family))) throw new RelayError("policy-invalid", 500, "family_map");
+  if (new Set(map.map(e => e.pattern)).size !== map.length) throw new RelayError("policy-invalid", 500, "family_map duplicate pattern");
+  if (!Array.isArray(body.lanes) || !body.lanes.length) throw new RelayError("policy-invalid", 500, "lanes");
+  if (!Array.isArray(body.security_paths) || !body.security_paths.length) throw new RelayError("policy-invalid", 500, "security_paths");
+  const paths = body.security_paths.map((p, i) => sanitizeText(p, { field: `security_paths[${i}]`, max: 512 }));
+  if (paths.some(p => !p.length)) throw new RelayError("policy-invalid", 500, "security_paths");
+  return tx(db, () => {
+    if (!versionCheck(db, "policy", body.version, sha)) return { loaded: false, version: body.version };
+    for (const l of body.lanes) {
+      if (!l || !isRecordId(l.lane) || Object.keys(l).some(k => !["lane", "owner_seat"].includes(k))) throw new RelayError("policy-invalid", 500, "lane");
+      const seat = db.prepare("SELECT kind, status FROM fleet_principals WHERE principal_id = ?").get(l.owner_seat ?? "");
+      if (!seat || seat.kind !== "ac-seat" || seat.status !== "active") throw new RelayError("policy-invalid", 500, `lane owner ${l.owner_seat}`);
+      db.prepare("INSERT INTO lanes(lane, owner_seat) VALUES (?, ?) ON CONFLICT(lane) DO UPDATE SET owner_seat = excluded.owner_seat").run(l.lane, l.owner_seat);
+    }
+    const row = db.prepare("INSERT INTO policy_family_map(policy_version, pattern, family) VALUES (?, ?, ?)");
+    for (const e of map) row.run(body.version, e.pattern, e.family);
+    setMeta(db, "security_paths", JSON.stringify(paths));
+    db.prepare("INSERT INTO signed_files(kind, version, body, sig, loaded_at) VALUES ('policy', ?, ?, ?, ?)").run(body.version, jcs(body), signed.sig, now);
+    setMeta(db, "policy_version", body.version);
+    setMeta(db, "policy_sha256", sha);
+    appendLog(db, "security", { kind: "policy.loaded", version: body.version, sha256: sha }, now);
+    return { loaded: true, version: body.version };
+  });
+}
+
+/** Start a relay: open relay.db, then load the signed roster and policy. Any failure closes it and refuses. */
+export function openRelay({ path = ":memory:", roster, policy, ownerPublicKey, now }) {
+  if (!roster || !policy) throw new RelayError("relay-needs-roster-and-policy", 500);
+  const db = openRelayDb(path);
+  try {
+    loadRoster(db, roster, { ownerPublicKey, now });
+    loadPolicy(db, policy, { ownerPublicKey, now });
+    return db;
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+}

package/src/relay/routes.mjs

@@ -0,0 +1,87 @@
+// Cloud Commons relay: the request front door (spec v3.4.5 6.5 endpoint inventory, 6.1
+// browser-origin refusal (A8), 7.1 ingress order and size caps, pending members).
+// Pure: no listener and no I/O. The server reads the method, path, headers and Content-Length, asks
+// classifyRequest before reading any body byte, then authenticates with admitRequest.
+//
+// Order, before any authentication work:
+//   1. the closed route inventory (routes.json): any other method or path -> 404 not-found;
+//   2. on every path outside /v1/fleet/: an Origin, Sec-Fetch-Site or Sec-Fetch-Mode header that is
+//      PRESENT, even empty -> 403 browser-origin-refused (before any signature, nonce or invite work;
+//      principal-independent, so not an oracle);
+//   3. the size cap chosen from the path (7.1): one byte over -> 413.
+// Then admitRequest: the 6.1 signature (auth.mjs); a pending member only on GET /v1/status;
+// a member on a fleet path, or a fleet principal on a member path -> the uniform 401; on a fleet
+// record (sent as the signed record { body, sig }) the signer must equal body.by (6.5, C1) ->
+// otherwise the uniform 401; a member record path's <type> must equal the record's type.
+
+import { RelayError } from "./records.mjs";
+import { MEMBER_RECORD_TYPES } from "./records.mjs";
+import { authenticateRequest, signerMatchesBy, UNAUTHORIZED } from "./auth.mjs";
+
+export const KB = 1024;
+/** 6.5 fleet record types, closed (the fleet record table; v3.4.4 adds review.changes and review.reject). */
+export const FLEET_RECORD_TYPES = Object.freeze([
+  "invite.create", "rebind.cancel", "enroll.confirm", "rekey.confirm",
+  "task.open", "task.close", "task.assign", "claim.release", "progress.accept", "role.c1", "clock.resume",
+  "review.changes", "review.reject",
+  "decision.propose", "verdict", "served_by.attest", "finding.open", "finding.close", "coauthor.declare",
+  "verify.result", "security.approve", "suspend", "message", "owner-record.confirm", "freeze", "veto", "unfreeze",
+]);
+/** 6.5 fleet views, closed. */
+export const FLEET_VIEWS = Object.freeze(["alerts", "queue", "decisions", "members", "quarantine", "owner-outbox"]);
+export const BROWSER_HEADERS = Object.freeze(["origin", "sec-fetch-site", "sec-fetch-mode"]);
+
+/**
+ * The closed route inventory (6.5). `auth`: "invite" (5.2 enrollment flow) or "signed" (6.1).
+ * `principal`: who may call it. `cap`: body bytes (0 = no body). Exported for routes.json.
+ */
+export const ROUTES = Object.freeze([
+  ...["enroll", "rekey", "rebind"].map(kind => ({ method: "POST", path: `/v1/${kind}`, auth: "invite", principal: null, cap: 4 * KB, flow: kind })),
+  { method: "GET", path: "/v1/status", auth: "signed", principal: "member", cap: 0, allowPending: true },
+  { method: "GET", path: "/v1/seed", auth: "signed", principal: "member", cap: 0 },
+  { method: "GET", path: "/v1/inbox", auth: "signed", principal: "member", cap: 0 },
+  { method: "POST", path: "/v1/inbox/ack", auth: "signed", principal: "member", cap: 1 * KB },
+  { method: "GET", path: "/v1/claims", auth: "signed", principal: "member", cap: 0 },
+  { method: "GET", path: "/v1/board", auth: "signed", principal: "member", cap: 0 },
+  ...Object.keys(MEMBER_RECORD_TYPES).map(type => ({ method: "POST", path: `/v1/records/${type}`, auth: "signed", principal: "member", cap: type === "result" ? 256 * KB : 64 * KB, recordType: type })),
+  ...FLEET_RECORD_TYPES.map(type => ({ method: "POST", path: `/v1/fleet/records/${type}`, auth: "signed", principal: "fleet", cap: 64 * KB, recordType: type })),
+  ...FLEET_VIEWS.map(view => ({ method: "GET", path: `/v1/fleet/${view}`, auth: "signed", principal: "fleet", cap: 0, view })),
+].map(r => Object.freeze(r)));
+const BY_KEY = new Map(ROUTES.map(r => [`${r.method} ${r.path}`, r]));
+
+const isFleetPath = (path) => typeof path === "string" && path.startsWith("/v1/fleet/");
+const refusal = (status, error) => ({ ok: false, status, body: { error } });
+
+/**
+ * Classify a request before any body byte is read and before any authentication work.
+ * `headers` uses lower-case names (as node:http gives them). `contentLength` is the declared body
+ * size in bytes (0 or undefined when there is none); the server must also stop reading at the cap.
+ * Returns { ok: true, route } or a refusal { ok: false, status, body }.
+ */
+export function classifyRequest({ method, path, headers = {}, contentLength = 0 }) {
+  const route = BY_KEY.get(`${method} ${path}`);
+  if (!route) return refusal(404, "not-found");
+  // A8: refuse on the header's PRESENCE (an empty value included), on every non-fleet path.
+  if (!isFleetPath(path) && BROWSER_HEADERS.some(h => Object.hasOwn(headers, h))) return refusal(403, "browser-origin-refused");
+  if (!Number.isSafeInteger(contentLength) || contentLength < 0) return refusal(400, "bad-content-length");
+  if (contentLength > route.cap) return refusal(413, "too-large");
+  return { ok: true, route };
+}
+
+/**
+ * Admit a classified, signed request (6.1 auth + 6.5 principal rules). `req` = { method, path,
+ * query, headers, body } with `body` the parsed JSON. Returns { ok: true, route, principal } or a
+ * refusal. The enrollment-flow routes (auth "invite") are not handled here (5.2).
+ */
+export function admitRequest(db, route, req, { aud, now }) {
+  if (route.auth !== "signed") throw new RelayError("route-not-signed", 500, route.path);
+  const a = authenticateRequest(db, req, { aud, now, allowPending: route.allowPending === true });
+  if (!a.ok) return a;
+  const p = a.principal;
+  // Only GET /v1/status admits a pending member (authenticateRequest enforces allowPending).
+  if (p.kind !== route.principal) return { ok: false, ...UNAUTHORIZED };
+  // A fleet record travels as the signed record { body, sig } (9.2); its body's `by` must be the signer.
+  if (route.principal === "fleet" && route.recordType && !signerMatchesBy(p, req.body?.body)) return { ok: false, ...UNAUTHORIZED };
+  if (route.recordType && route.principal === "member" && req.body?.type !== route.recordType) return refusal(400, "type-mismatch");
+  return { ok: true, route, principal: p };
+}