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

package/src/relay/seed.mjs

@@ -0,0 +1,89 @@
+// Cloud Commons relay: the seed bundle (spec v3.4.5 section 8, B5-B7, R5; N22 custody).
+//
+// The seed bundle is the public bootstrap document a member reads with a signed GET /v1/seed. It
+// holds no secret: never a key seed, private key, invite secret, passphrase, provider key, operator
+// token or another member's id. It is signed by the relay key (Ed25519 over JCS of every field but
+// `sig`) and expires within 30 days; status is still checked on every request, so expiry is a hygiene
+// bound, not the revocation mechanism. Only these four values cross a reset: the key seed, `agent`,
+// `relay.origin` and `relay.public_key`; everything else comes back from GET /v1/seed.
+//
+// `rules` and `reconnect` name the two documents in ./docs by sha256. The agent acts only on a
+// rules document whose hash matches the bundle (the reference client ships the same files).
+
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { jcs } from "../pillar.mjs";
+import { RelayError } from "./records.mjs";
+import { ROUTES } from "./routes.mjs";
+import { verifyBytesStrict } from "./auth.mjs";
+
+export const SEED_BUNDLE_V = "commons-relay-seed-bundle/1";
+export const RELAY_PROTOCOL = "commons-relay/1";
+export const SEED_BUNDLE_TTL_MS = 30 * 86400000;
+const doc = (name) => readFileSync(new URL(`./docs/${name}`, import.meta.url));
+const sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** The working-rules document (R2 and R4 restated, the authority invariant, the dedicated-key rule). */
+export const RULES = Object.freeze({ ref: "commons-relay/working-rules/1", version: 1, file: "working-rules-v1.md", sha256: sha(doc("working-rules-v1.md")) });
+/** The reconnect procedure (11.5). */
+export const RECONNECT = Object.freeze({ ref: "commons-relay/reconnect/1", file: "reconnect-v1.md", sha256: sha(doc("reconnect-v1.md")) });
+/** The member endpoints (6.5): every signed route outside /v1/fleet/. */
+export const MEMBER_ENDPOINTS = Object.freeze(ROUTES.filter(r => r.auth === "signed" && r.principal === "member").map(r => `${r.method} ${r.path}`));
+/** Every field a seed bundle may hold (N22: a custody test covers each). */
+export const SEED_BUNDLE_FIELDS = Object.freeze(["v", "relay", "namespace", "member", "rules", "board", "reconnect", "issued_at", "expires_at", "sig"]);
+
+/** The unsigned bundle for an active member, read from the relay's own tables. */
+export function seedBundleBody(db, memberId, { aud, relayPublicKey, now }) {
+  const m = db.prepare(`SELECT m.member_id, m.status, m.role, p.lane FROM members m JOIN member_profiles p USING(member_id) WHERE m.member_id = ?`).get(memberId);
+  if (!m || m.status !== "active") throw new RelayError("unauthorized", 401);
+  const keys = db.prepare("SELECT agent FROM keys WHERE principal_kind = 'member' AND principal_id = ? AND status = 'active'").all(memberId);
+  if (keys.length !== 1) throw new RelayError("unauthorized", 401);
+  return {
+    v: SEED_BUNDLE_V,
+    relay: { origin: aud, public_key: relayPublicKey, protocol: RELAY_PROTOCOL },
+    namespace: "agentnet",
+    member: { member_id: m.member_id, agent: keys[0].agent, role: m.role },
+    rules: { sha256: RULES.sha256, ref: RULES.ref, version: RULES.version },
+    board: { lane: m.lane, endpoints: [...MEMBER_ENDPOINTS] },
+    reconnect: { sha256: RECONNECT.sha256, ref: RECONNECT.ref },
+    issued_at: now,
+    expires_at: now + SEED_BUNDLE_TTL_MS,
+  };
+}
+
+/** Sign a bundle body with the relay key seed (held by the relay only). */
+export function signSeedBundle(body, relaySeedHex) {
+  const sig = Buffer.from(ed25519.sign(Buffer.from(jcs(body), "utf8"), Buffer.from(relaySeedHex, "hex"))).toString("hex");
+  return { ...body, sig };
+}
+
+/**
+ * The client's check (8, B7): the relay key pinned in the invite or carried across a reset, byte for
+ * byte; strict Ed25519 over JCS(bundle minus sig); the version, protocol and namespace; the origin; not
+ * expired; the expiry within 30 days of issue; and, when given, the expected member and agent.
+ */
+export function verifySeedBundle(bundle, relayPublicKey, { aud, now, member_id, agent } = {}) {
+  const problems = [];
+  if (!bundle || typeof bundle !== "object") return { ok: false, problems: ["not-an-object"] };
+  for (const k of Object.keys(bundle)) if (!SEED_BUNDLE_FIELDS.includes(k)) problems.push(`unknown-field:${k}`);
+  const { sig, ...body } = bundle;
+  let bytes = null;
+  try { bytes = Buffer.from(jcs(body), "utf8"); } catch { problems.push("not-jcs"); }
+  if (!bytes || !verifyBytesStrict(relayPublicKey, bytes, sig)) problems.push("bad-signature");
+  if (bundle.relay?.public_key !== relayPublicKey) problems.push("relay-key-mismatch");
+  if (bundle.v !== SEED_BUNDLE_V || bundle.relay?.protocol !== RELAY_PROTOCOL || bundle.namespace !== "agentnet") problems.push("version");
+  if (aud !== undefined && bundle.relay?.origin !== aud) problems.push("origin-mismatch");
+  if (!Number.isSafeInteger(bundle.issued_at) || !Number.isSafeInteger(bundle.expires_at) || bundle.expires_at <= bundle.issued_at
+      || bundle.expires_at - bundle.issued_at > SEED_BUNDLE_TTL_MS) problems.push("validity");
+  if (now !== undefined && !(now < bundle.expires_at)) problems.push("expired");
+  if (member_id !== undefined && bundle.member?.member_id !== member_id) problems.push("member-mismatch");
+  if (agent !== undefined && bundle.member?.agent !== agent) problems.push("agent-mismatch");
+  return { ok: problems.length === 0, problems };
+}
+
+/** The local copy of a document the bundle names, accepted only if its sha256 matches (the agent acts on nothing else). */
+export function trustedDocument(bundleEntry, which = RULES) {
+  const bytes = doc(which.file);
+  if (!bundleEntry || bundleEntry.sha256 !== sha(bytes) || bundleEntry.ref !== which.ref) throw new RelayError("document-mismatch", 400, which.ref);
+  return bytes.toString("utf8");
+}

package/src/relay/serve.mjs

@@ -0,0 +1,116 @@
+// Cloud Commons relay: the PRODUCTION entrypoint (security invariant: it has no test flag). It is what
+// `agent-commons relay serve` runs. It is a separate module from the test entrypoint
+// (server.mjs's command line) and it has no test flag: --test-mode, --test-dir and --test-interface are
+// unknown arguments here, and the test audience (or any non-https, non-canonical or `.test`
+// audience) is refused. Every refusal exits with status 2 before anything listens, and the aud and
+// bind are checked before any file is read.
+//
+//   agent-commons relay serve --aud https://<host>[:port] --bind <loopback ip> [--port <n>]
+//     --db <dir>/relay*.db --roster <signed roster file> --policy <signed policy file>
+//     --owner-public-key <64 hex> --relay-key-file <key seed file> [--access-log <file>]
+//
+// Files the owner custodies (formats only; this module mints no key):
+//   --relay-key-file  one 64-hex Ed25519 key seed (RFC 8032), optionally newline-terminated;
+//   --roster          the owner-signed roster  {body: {v: "commons-relay-roster/1", ...}, sig};
+//   --policy          the owner-signed policy  {body: {v: "commons-relay-policy/1", ...}, sig}.
+// Each must be a regular file (never a symlink) owned by this user with no group or other access
+// (mode 0600 or stricter); anything else is refused. The access log, if named, must not exist yet or
+// be such a file too. The process umask is 077, so relay.db, its WAL and the access log are private.
+//
+// The relay listens on plain HTTP on loopback only; the host's reverse proxy terminates TLS for the
+// configured origin and sets X-Real-IP (server.mjs, production mode).
+
+import { lstatSync, readFileSync, appendFileSync, realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { StartRefused, checkStart, startRelay } from "./server.mjs";
+import { openRelay } from "./roster.mjs";
+
+/** The production flags. Security invariant: no test flag exists here. */
+export const SERVE_FLAGS = Object.freeze(["--aud", "--bind", "--port", "--db", "--roster", "--policy", "--owner-public-key", "--relay-key-file", "--access-log"]);
+const REQUIRED = Object.freeze(["aud", "bind", "db", "roster", "policy", "owner-public-key", "relay-key-file"]);
+
+export function parseServeArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!SERVE_FLAGS.includes(flag)) throw new StartRefused([`unknown argument ${JSON.stringify(String(flag).slice(0, 40))}`]);
+    const key = flag.slice(2);
+    if (Object.hasOwn(out, key)) throw new StartRefused([`${flag} given twice`]);
+    if (i + 1 >= argv.length || argv[i + 1].startsWith("--")) throw new StartRefused([`${flag} needs a value`]);
+    out[key] = argv[++i];
+  }
+  for (const k of REQUIRED) if (typeof out[k] !== "string") throw new StartRefused([`--${k} is required`]);
+  return out;
+}
+
+/** An owner-custodied file: a regular file of this user, never a symlink, no group or other access. */
+export function readOwnerFile(path, what) {
+  let st;
+  try { st = lstatSync(path); } catch { throw new StartRefused([`${what} missing`]); }
+  if (st.isSymbolicLink() || !st.isFile()) throw new StartRefused([`${what} must be a regular file, not a symlink`]);
+  if ((st.mode & 0o077) !== 0) throw new StartRefused([`${what} must have no group or other access (mode 0600)`]);
+  if (typeof process.getuid === "function" && st.uid !== process.getuid()) throw new StartRefused([`${what} must be owned by this user`]);
+  return readFileSync(path, "utf8");
+}
+
+/** The relay key seed file: exactly one 64-hex seed. */
+export function loadRelayKeySeed(path) {
+  const seed = readOwnerFile(path, "--relay-key-file").replace(/\n$/, "");
+  if (!/^[0-9a-f]{64}$/.test(seed)) throw new StartRefused(["--relay-key-file must hold exactly one 64-hex key seed"]);
+  return seed;
+}
+
+/** A signed roster or policy file: JSON {body, sig}; its signature and contents are checked by openRelay. */
+export function loadSignedFile(path, what) {
+  let parsed;
+  try { parsed = JSON.parse(readOwnerFile(path, what)); } catch (error) { if (error instanceof StartRefused) throw error; throw new StartRefused([`${what} is not JSON`]); }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || Object.keys(parsed).sort().join(",") !== "body,sig")
+    throw new StartRefused([`${what} must be a signed file {body, sig}`]);
+  return parsed;
+}
+
+/** An access log path: absent, or an owner-only regular file. */
+function checkLogPath(path) {
+  let st;
+  try { st = lstatSync(path); } catch { return; }
+  if (st.isSymbolicLink() || !st.isFile() || (st.mode & 0o077) !== 0 || (typeof process.getuid === "function" && st.uid !== process.getuid()))
+    throw new StartRefused(["--access-log must be absent or a private regular file of this user"]);
+}
+
+/** The production command line. Exit status 2 on any refusal, before anything listens. */
+export async function serveMain(argv = process.argv.slice(2), { stdout = process.stdout, stderr = process.stderr } = {}) {
+  let relay, db;
+  try {
+    const o = parseServeArgs(argv);
+    // The aud and the bind first: nothing is read before they pass.
+    checkStart({ aud: o.aud, host: o.bind, mode: "production" });
+    const port = o.port === undefined ? 0 : /^(0|[1-9][0-9]{0,4})$/.test(o.port) && Number(o.port) <= 65535 ? Number(o.port) : NaN;
+    if (Number.isNaN(port)) throw new StartRefused(["--port must be 0-65535"]);
+    if (!/^[0-9a-f]{64}$/.test(o["owner-public-key"])) throw new StartRefused(["--owner-public-key must be 64 lower-case hex"]);
+    process.umask(0o077);
+    const seed = loadRelayKeySeed(o["relay-key-file"]);
+    const roster = loadSignedFile(o.roster, "--roster"), policy = loadSignedFile(o.policy, "--policy");
+    if (o["access-log"] !== undefined) checkLogPath(o["access-log"]);
+    db = openRelay({ path: o.db, roster, policy, ownerPublicKey: o["owner-public-key"], now: Date.now() });
+    const log = o["access-log"];
+    const accessLog = (entry) => {
+      const line = `${JSON.stringify(entry)}\n`;
+      if (log) appendFileSync(log, line, { mode: 0o600 }); else stderr.write(`access ${line}`);
+    };
+    relay = await startRelay({ db, aud: o.aud, host: o.bind, port, relayKeySeedHex: seed, accessLog, mode: "production",
+      onError: (error) => stderr.write(`relay error: ${String(error?.stack ?? error).slice(0, 2000)}\n`) });
+  } catch (error) {
+    stderr.write(`${error instanceof StartRefused ? error.message : `relay start refused: ${String(error?.message ?? error).slice(0, 500)}`}\n`);
+    try { db?.close(); } catch { /* already closed */ }
+    process.exitCode = 2;
+    return null;
+  }
+  stdout.write(`${JSON.stringify({ listening: relay.url, relay_public_key: relay.publicKey, mode: relay.mode, aud: argv[argv.indexOf("--aud") + 1] })}\n`);
+  const shutdown = async () => { await relay.close(); db.close(); process.exit(0); };
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+  return relay;
+}
+
+const invoked = (() => { try { return process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href; } catch { return false; } })();
+if (invoked) await serveMain();