settld 0.1.0

package/src/core/url-safety.js

@@ -0,0 +1,263 @@
+import dns from "node:dns/promises";
+import net from "node:net";
+
+export const URL_SAFETY_CODE = Object.freeze({
+  INVALID_URL: "URL_INVALID",
+  SCHEME_FORBIDDEN: "URL_SCHEME_FORBIDDEN",
+  USERINFO_FORBIDDEN: "URL_USERINFO_FORBIDDEN",
+  HOST_FORBIDDEN: "URL_HOST_FORBIDDEN",
+  DNS_LOOKUP_FAILED: "URL_DNS_LOOKUP_FAILED",
+  DNS_FORBIDDEN: "URL_DNS_FORBIDDEN"
+});
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function defaultAllowHttp() {
+  if (typeof process !== "undefined" && process.env.PROXY_ALLOW_HTTP_URLS === "1") return true;
+  const env = typeof process !== "undefined" ? process.env.NODE_ENV : "";
+  return env === "development" || env === "test";
+}
+
+function stripTrailingDot(hostname) {
+  const h = String(hostname ?? "").trim().toLowerCase();
+  return h.endsWith(".") ? h.slice(0, -1) : h;
+}
+
+function isMetadataHostname(hostname) {
+  const h = stripTrailingDot(hostname);
+  if (!h) return false;
+  if (h === "metadata.google.internal") return true;
+  if (h === "metadata.azure.internal") return true;
+  return false;
+}
+
+function parseIpv4(ip) {
+  const parts = String(ip).trim().split(".");
+  if (parts.length !== 4) return null;
+  const bytes = [];
+  for (const p of parts) {
+    if (p.trim() === "" || !/^\d+$/.test(p)) return null;
+    const n = Number(p);
+    if (!Number.isInteger(n) || n < 0 || n > 255) return null;
+    bytes.push(n);
+  }
+  return bytes;
+}
+
+function isPublicIpv4(ip, { allowLoopback = false, allowPrivate = false } = {}) {
+  const b = parseIpv4(ip);
+  if (!b) return false;
+  const [a, c] = b;
+  const d = b[1];
+
+  // Unspecified / broadcast / multicast / reserved.
+  if (a === 0) return false;
+  if (a >= 224) return false;
+  if (a === 255) return false;
+
+  // Loopback.
+  if (!allowLoopback && a === 127) return false;
+
+  // Link-local.
+  if (!allowPrivate && a === 169 && d === 254) return false;
+
+  // RFC1918.
+  if (!allowPrivate && a === 10) return false;
+  if (!allowPrivate && a === 172 && d >= 16 && d <= 31) return false;
+  if (!allowPrivate && a === 192 && d === 168) return false;
+
+  // CGNAT.
+  if (!allowPrivate && a === 100 && d >= 64 && d <= 127) return false;
+
+  // Benchmarking.
+  if (!allowPrivate && a === 198 && (d === 18 || d === 19)) return false;
+
+  return true;
+}
+
+function parseIpv6ToHextets(ip) {
+  let value = String(ip).trim().toLowerCase();
+  const zoneIdx = value.indexOf("%");
+  if (zoneIdx !== -1) value = value.slice(0, zoneIdx);
+
+  if (value === "") return null;
+  const parts = value.split("::");
+  if (parts.length > 2) return null;
+
+  const head = parts[0] ? parts[0].split(":").filter(Boolean) : [];
+  const tail = parts.length === 2 && parts[1] ? parts[1].split(":").filter(Boolean) : [];
+
+  function expandIpv4InPlace(list) {
+    if (!list.length) return;
+    const last = list[list.length - 1];
+    if (!last.includes(".")) return;
+    const b = parseIpv4(last);
+    if (!b) return;
+    list.pop();
+    const hi = (b[0] << 8) | b[1];
+    const lo = (b[2] << 8) | b[3];
+    list.push(hi.toString(16));
+    list.push(lo.toString(16));
+  }
+
+  expandIpv4InPlace(head);
+  expandIpv4InPlace(tail);
+
+  const total = head.length + tail.length;
+  const hasCompression = parts.length === 2;
+  if (!hasCompression && total !== 8) return null;
+  if (hasCompression && total > 8) return null;
+
+  const missing = hasCompression ? 8 - total : 0;
+  const hextets = [];
+  for (const h of head) hextets.push(h);
+  for (let i = 0; i < missing; i += 1) hextets.push("0");
+  for (const t of tail) hextets.push(t);
+
+  if (hextets.length !== 8) return null;
+  const out = [];
+  for (const h of hextets) {
+    if (!/^[0-9a-f]{1,4}$/.test(h)) return null;
+    out.push(parseInt(h, 16));
+  }
+  return out;
+}
+
+function isPublicIpv6(ip, { allowLoopback = false, allowPrivate = false } = {}) {
+  const hextets = parseIpv6ToHextets(ip);
+  if (!hextets) return false;
+
+  const allZero = hextets.every((h) => h === 0);
+  const loopback = hextets.slice(0, 7).every((h) => h === 0) && hextets[7] === 1;
+  if (allZero) return false;
+  if (!allowLoopback && loopback) return false;
+
+  const first = hextets[0];
+  // Unique local: fc00::/7
+  if (!allowPrivate && first >= 0xfc00 && first <= 0xfdff) return false;
+  // Link-local: fe80::/10
+  if (!allowPrivate && first >= 0xfe80 && first <= 0xfebf) return false;
+  // Multicast: ff00::/8
+  if (first >= 0xff00 && first <= 0xffff) return false;
+
+  // IPv4-mapped IPv6: ::ffff:w.x.y.z
+  const v4Mapped = hextets.slice(0, 5).every((h) => h === 0) && hextets[5] === 0xffff;
+  if (v4Mapped) {
+    const v4 = `${hextets[6] >> 8}.${hextets[6] & 0xff}.${hextets[7] >> 8}.${hextets[7] & 0xff}`;
+    return isPublicIpv4(v4, { allowLoopback, allowPrivate });
+  }
+
+  return true;
+}
+
+function schemeFromUrlString(urlString) {
+  const idx = urlString.indexOf(":");
+  if (idx === -1) return null;
+  return urlString.slice(0, idx).trim().toLowerCase();
+}
+
+export function checkUrlSafetySync(
+  target,
+  {
+    allowHttp = defaultAllowHttp(),
+    allowPrivate = false,
+    allowLoopback = false,
+    allowedSchemes = ["https", "s3", "gcs", "gs", "minio", "obj"]
+  } = {}
+) {
+  assertNonEmptyString(target, "target");
+  const raw = String(target).trim();
+  if (raw.includes("\n") || raw.includes("\r")) {
+    return { ok: false, code: URL_SAFETY_CODE.INVALID_URL, message: "URL must not contain newlines" };
+  }
+
+  const scheme = schemeFromUrlString(raw);
+  if (!scheme) return { ok: false, code: URL_SAFETY_CODE.INVALID_URL, message: "URL is missing scheme" };
+  if (!allowedSchemes.includes(scheme) && !(allowHttp && scheme === "http")) {
+    return { ok: false, code: URL_SAFETY_CODE.SCHEME_FORBIDDEN, message: "URL scheme is not allowed", scheme };
+  }
+  if (scheme === "http" && !allowHttp) {
+    return { ok: false, code: URL_SAFETY_CODE.SCHEME_FORBIDDEN, message: "http:// is not allowed", scheme };
+  }
+
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, code: URL_SAFETY_CODE.INVALID_URL, message: "invalid URL" };
+  }
+
+  // Non-network schemes (opaque refs).
+  if (scheme === "obj" || scheme === "s3" || scheme === "gcs" || scheme === "gs" || scheme === "minio") {
+    return { ok: true, scheme, url, needsDns: false };
+  }
+
+  // Only http/https below.
+  if (url.username || url.password) {
+    return { ok: false, code: URL_SAFETY_CODE.USERINFO_FORBIDDEN, message: "URL userinfo is not allowed", scheme };
+  }
+
+  const hostname = stripTrailingDot(url.hostname);
+  if (!hostname) return { ok: false, code: URL_SAFETY_CODE.INVALID_URL, message: "URL hostname is required", scheme };
+
+  if (hostname === "localhost" || isMetadataHostname(hostname)) {
+    if (!allowLoopback && hostname === "localhost") {
+      return { ok: false, code: URL_SAFETY_CODE.HOST_FORBIDDEN, message: "URL hostname is not allowed", scheme, hostname };
+    }
+    if (isMetadataHostname(hostname)) {
+      return { ok: false, code: URL_SAFETY_CODE.HOST_FORBIDDEN, message: "URL hostname is not allowed", scheme, hostname };
+    }
+  }
+
+  const ipKind = net.isIP(hostname);
+  if (ipKind === 4) {
+    if (!isPublicIpv4(hostname, { allowLoopback, allowPrivate })) {
+      return { ok: false, code: URL_SAFETY_CODE.HOST_FORBIDDEN, message: "URL host is not allowed", scheme, hostname };
+    }
+    return { ok: true, scheme, url, hostname, needsDns: false };
+  }
+  if (ipKind === 6) {
+    if (!isPublicIpv6(hostname, { allowLoopback, allowPrivate })) {
+      return { ok: false, code: URL_SAFETY_CODE.HOST_FORBIDDEN, message: "URL host is not allowed", scheme, hostname };
+    }
+    return { ok: true, scheme, url, hostname, needsDns: false };
+  }
+
+  return { ok: true, scheme, url, hostname, needsDns: true };
+}
+
+export async function checkUrlSafety(target, options = {}) {
+  const base = checkUrlSafetySync(target, options);
+  if (!base.ok) return base;
+  if (!base.needsDns) return base;
+
+  const allowPrivate = Boolean(options.allowPrivate);
+  const allowLoopback = Boolean(options.allowLoopback);
+  const hostname = base.hostname;
+  if (!hostname) return base;
+
+  let addrs;
+  try {
+    addrs = await dns.lookup(hostname, { all: true, verbatim: true });
+  } catch (err) {
+    return { ok: false, code: URL_SAFETY_CODE.DNS_LOOKUP_FAILED, message: "DNS lookup failed", hostname, err: { message: err?.message } };
+  }
+
+  for (const a of addrs) {
+    const ip = a?.address ? String(a.address) : null;
+    const kind = ip ? net.isIP(ip) : 0;
+    if (kind === 4) {
+      if (!isPublicIpv4(ip, { allowLoopback, allowPrivate })) {
+        return { ok: false, code: URL_SAFETY_CODE.DNS_FORBIDDEN, message: "DNS resolved to a forbidden IP", hostname, ip };
+      }
+    } else if (kind === 6) {
+      if (!isPublicIpv6(ip, { allowLoopback, allowPrivate })) {
+        return { ok: false, code: URL_SAFETY_CODE.DNS_FORBIDDEN, message: "DNS resolved to a forbidden IP", hostname, ip };
+      }
+    }
+  }
+
+  return base;
+}

package/src/core/verification-warnings.js

@@ -0,0 +1,53 @@
+import { canonicalJsonStringify } from "./canonical-json.js";
+
+export const VERIFICATION_WARNING_CODE = Object.freeze({
+  LEGACY_KEYS_FORMAT_USED: "LEGACY_KEYS_FORMAT_USED",
+  NONSERVER_REVOCATION_NOT_ENFORCED: "NONSERVER_REVOCATION_NOT_ENFORCED",
+  TRUSTED_GOVERNANCE_ROOT_KEYS_MISSING_LENIENT: "TRUSTED_GOVERNANCE_ROOT_KEYS_MISSING_LENIENT",
+  GOVERNANCE_POLICY_MISSING_LENIENT: "GOVERNANCE_POLICY_MISSING_LENIENT",
+  GOVERNANCE_POLICY_V1_ACCEPTED_LENIENT: "GOVERNANCE_POLICY_V1_ACCEPTED_LENIENT",
+  BUNDLE_HEAD_ATTESTATION_MISSING_LENIENT: "BUNDLE_HEAD_ATTESTATION_MISSING_LENIENT",
+  MISSING_GOVERNANCE_SNAPSHOT_LENIENT: "MISSING_GOVERNANCE_SNAPSHOT_LENIENT",
+  UNSIGNED_REPORT_LENIENT: "UNSIGNED_REPORT_LENIENT",
+  VERIFICATION_REPORT_MISSING_LENIENT: "VERIFICATION_REPORT_MISSING_LENIENT",
+  PRICING_MATRIX_UNSIGNED_LENIENT: "PRICING_MATRIX_UNSIGNED_LENIENT",
+  WARN_PRICING_SIGNATURE_V1_BYTES_LEGACY: "WARN_PRICING_SIGNATURE_V1_BYTES_LEGACY",
+  CLOSE_PACK_SLA_SURFACES_MISSING_LENIENT: "CLOSE_PACK_SLA_SURFACES_MISSING_LENIENT",
+  CLOSE_PACK_ACCEPTANCE_SURFACES_MISSING_LENIENT: "CLOSE_PACK_ACCEPTANCE_SURFACES_MISSING_LENIENT",
+  TOOL_VERSION_UNKNOWN: "TOOL_VERSION_UNKNOWN",
+  TOOL_COMMIT_UNKNOWN: "TOOL_COMMIT_UNKNOWN"
+});
+
+const WARNING_CODE_SET = new Set(Object.values(VERIFICATION_WARNING_CODE));
+
+function isPlainObject(v) {
+  return Boolean(v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+}
+
+export function normalizeVerificationWarnings(warnings) {
+  if (warnings === null || warnings === undefined) return [];
+  if (!Array.isArray(warnings)) throw new TypeError("warnings must be an array");
+
+  const seen = new Set();
+  const out = [];
+  for (const w of warnings) {
+    if (!isPlainObject(w)) throw new TypeError("warning must be an object");
+    const code = typeof w.code === "string" ? w.code : null;
+    if (!code || !WARNING_CODE_SET.has(code)) throw new TypeError(`invalid warning code: ${String(code ?? "")}`);
+    const message = w.message === undefined ? undefined : w.message === null ? null : String(w.message);
+    const detail = w.detail === undefined ? undefined : w.detail;
+
+    const normalized = {};
+    normalized.code = code;
+    if (message !== undefined) normalized.message = message;
+    if (detail !== undefined) normalized.detail = detail;
+
+    const key = canonicalJsonStringify(normalized);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(normalized);
+  }
+
+  out.sort((a, b) => String(a.code).localeCompare(String(b.code)) || canonicalJsonStringify(a).localeCompare(canonicalJsonStringify(b)));
+  return out;
+}

package/src/core/zone-coverage.js

@@ -0,0 +1,59 @@
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  const t = Date.parse(value);
+  if (!Number.isFinite(t)) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+export const COVERAGE_SOURCE = Object.freeze({
+  ROBOT: "robot",
+  PLATFORM: "platform"
+});
+
+const COVERAGE_SOURCES = new Set(Object.values(COVERAGE_SOURCE));
+
+export function validateZoneCoverageReportedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "zoneId", "coveragePct", "window", "coverageMapHash", "source"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.zoneId, "payload.zoneId");
+
+  if (!Number.isSafeInteger(payload.coveragePct) || payload.coveragePct < 0 || payload.coveragePct > 100) {
+    throw new TypeError("payload.coveragePct must be an integer in range 0..100");
+  }
+
+  assertPlainObject(payload.window, "payload.window");
+  const winAllowed = new Set(["startAt", "endAt"]);
+  for (const key of Object.keys(payload.window)) {
+    if (!winAllowed.has(key)) throw new TypeError(`payload.window contains unknown field: ${key}`);
+  }
+  assertIsoDate(payload.window.startAt, "payload.window.startAt");
+  assertIsoDate(payload.window.endAt, "payload.window.endAt");
+  if (Date.parse(payload.window.startAt) > Date.parse(payload.window.endAt)) throw new TypeError("payload.window.startAt must be <= payload.window.endAt");
+
+  if (payload.coverageMapHash !== undefined && payload.coverageMapHash !== null) {
+    assertNonEmptyString(payload.coverageMapHash, "payload.coverageMapHash");
+    const hex = payload.coverageMapHash.trim();
+    if (!/^[a-f0-9]{64}$/i.test(hex)) throw new TypeError("payload.coverageMapHash must be 64-hex when provided");
+  }
+
+  assertNonEmptyString(payload.source, "payload.source");
+  if (!COVERAGE_SOURCES.has(payload.source)) throw new TypeError("payload.source is not supported");
+
+  return payload;
+}
+

package/src/core/zones.js

@@ -0,0 +1,8 @@
+export const DEFAULT_ZONE_ID = "zone_default";
+
+export function normalizeZoneId(zoneId) {
+  if (zoneId === undefined || zoneId === null) return DEFAULT_ZONE_ID;
+  if (typeof zoneId !== "string" || zoneId.trim() === "") return DEFAULT_ZONE_ID;
+  return zoneId.trim();
+}
+

package/src/core/zoneset.js

@@ -0,0 +1,67 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const ZONE_SET_SCHEMA_VERSION_V1 = "ZoneSet.v1";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+export function validateZoneSetV1(zoneSet) {
+  assertPlainObject(zoneSet, "zoneSet");
+  const allowed = new Set(["schemaVersion", "zoneSetId", "zones"]);
+  for (const k of Object.keys(zoneSet)) {
+    if (!allowed.has(k)) throw new TypeError(`zoneSet contains unknown field: ${k}`);
+  }
+
+  if (zoneSet.schemaVersion !== ZONE_SET_SCHEMA_VERSION_V1) throw new TypeError("zoneSet.schemaVersion is not supported");
+  assertNonEmptyString(zoneSet.zoneSetId, "zoneSet.zoneSetId");
+  if (!Array.isArray(zoneSet.zones) || zoneSet.zones.length === 0) throw new TypeError("zoneSet.zones must be a non-empty array");
+
+  const seen = new Set();
+  for (let i = 0; i < zoneSet.zones.length; i += 1) {
+    const z = zoneSet.zones[i];
+    assertPlainObject(z, `zoneSet.zones[${i}]`);
+    const allowedZone = new Set(["zoneId", "label", "areaSqFt"]);
+    for (const k of Object.keys(z)) {
+      if (!allowedZone.has(k)) throw new TypeError(`zoneSet.zones[${i}] contains unknown field: ${k}`);
+    }
+    assertNonEmptyString(z.zoneId, `zoneSet.zones[${i}].zoneId`);
+    if (z.label !== undefined && z.label !== null) assertNonEmptyString(z.label, `zoneSet.zones[${i}].label`);
+    if (z.areaSqFt !== undefined && z.areaSqFt !== null) {
+      if (!Number.isFinite(z.areaSqFt) || z.areaSqFt <= 0) throw new TypeError(`zoneSet.zones[${i}].areaSqFt must be a positive number`);
+    }
+    const zoneId = z.zoneId.trim();
+    if (seen.has(zoneId)) throw new TypeError("zoneSet.zones zoneId must be unique");
+    seen.add(zoneId);
+  }
+
+  return zoneSet;
+}
+
+export function normalizeZoneSetV1(zoneSet) {
+  const validated = validateZoneSetV1(zoneSet);
+  const normalized = normalizeForCanonicalJson(validated, { path: "$" });
+  // Enforce stable ordering by zoneId for determinism.
+  const zones = Array.isArray(normalized.zones) ? [...normalized.zones] : [];
+  zones.sort((a, b) => {
+    const az = String(a?.zoneId ?? "");
+    const bz = String(b?.zoneId ?? "");
+    if (az !== bz) return az < bz ? -1 : 1;
+    return 0;
+  });
+  return { ...normalized, zones };
+}
+
+export function computeZoneSetHash(zoneSet) {
+  const normalized = normalizeZoneSetV1(zoneSet);
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+

package/src/db/migrate.js

@@ -0,0 +1,61 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { MIGRATIONS_ADVISORY_LOCK_KEY } from "../core/maintenance-locks.js";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+export async function migratePg({ pool, migrationsDir }) {
+  if (!pool) throw new TypeError("pool is required");
+  assertNonEmptyString(migrationsDir, "migrationsDir");
+
+  const lockClient = await pool.connect();
+  try {
+    // Ensure only one process performs migrations at a time.
+    await lockClient.query("SELECT pg_advisory_lock(hashtext($1))", [MIGRATIONS_ADVISORY_LOCK_KEY]);
+
+    await lockClient.query(`
+      CREATE TABLE IF NOT EXISTS proxy_migrations (
+        id TEXT PRIMARY KEY,
+        applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      )
+    `);
+
+    const applied = new Set();
+    const existing = await lockClient.query("SELECT id FROM proxy_migrations ORDER BY id ASC");
+    for (const row of existing.rows) {
+      if (row?.id) applied.add(String(row.id));
+    }
+
+    const entries = await fs.readdir(migrationsDir, { withFileTypes: true });
+    const files = entries.filter((e) => e.isFile() && e.name.endsWith(".sql")).map((e) => e.name).sort();
+
+    for (const filename of files) {
+      if (applied.has(filename)) continue;
+      const full = path.join(migrationsDir, filename);
+      const sql = await fs.readFile(full, "utf8");
+
+      try {
+        await lockClient.query("BEGIN");
+        await lockClient.query(sql);
+        await lockClient.query("INSERT INTO proxy_migrations (id) VALUES ($1)", [filename]);
+        await lockClient.query("COMMIT");
+        applied.add(filename);
+      } catch (err) {
+        try {
+          await lockClient.query("ROLLBACK");
+        } catch {}
+        throw err;
+      }
+    }
+
+    return { applied: Array.from(applied.values()) };
+  } finally {
+    try {
+      await lockClient.query("SELECT pg_advisory_unlock(hashtext($1))", [MIGRATIONS_ADVISORY_LOCK_KEY]);
+    } catch {}
+    lockClient.release();
+  }
+}

package/src/db/migrations/001_init.sql

@@ -0,0 +1,92 @@
+-- v0.9: Postgres-backed event store + outbox + ledger.
+
+CREATE TABLE IF NOT EXISTS proxy_migrations (
+  id TEXT PRIMARY KEY,
+  applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public_keys (
+  key_id TEXT PRIMARY KEY,
+  public_key_pem TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS server_signer (
+  id INTEGER PRIMARY KEY,
+  public_key_pem TEXT NOT NULL,
+  private_key_pem TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS events (
+  aggregate_type TEXT NOT NULL,
+  aggregate_id TEXT NOT NULL,
+  seq BIGINT NOT NULL,
+  event_id TEXT NOT NULL,
+  chain_hash TEXT NOT NULL,
+  prev_chain_hash TEXT,
+  payload_hash TEXT NOT NULL,
+  type TEXT NOT NULL,
+  at TIMESTAMPTZ NOT NULL,
+  actor_json JSONB NOT NULL,
+  payload_json JSONB,
+  signature TEXT,
+  signer_key_id TEXT,
+  event_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (aggregate_type, aggregate_id, seq),
+  UNIQUE (event_id),
+  UNIQUE (aggregate_type, aggregate_id, chain_hash)
+);
+
+CREATE INDEX IF NOT EXISTS events_by_aggregate ON events (aggregate_type, aggregate_id, seq);
+CREATE INDEX IF NOT EXISTS events_by_type ON events (type);
+
+CREATE TABLE IF NOT EXISTS snapshots (
+  aggregate_type TEXT NOT NULL,
+  aggregate_id TEXT NOT NULL,
+  seq BIGINT NOT NULL,
+  at_chain_hash TEXT,
+  snapshot_json JSONB NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (aggregate_type, aggregate_id)
+);
+
+CREATE INDEX IF NOT EXISTS snapshots_by_type ON snapshots (aggregate_type, aggregate_id);
+
+CREATE TABLE IF NOT EXISTS outbox (
+  id BIGSERIAL PRIMARY KEY,
+  topic TEXT NOT NULL,
+  aggregate_type TEXT,
+  aggregate_id TEXT,
+  payload_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  claimed_at TIMESTAMPTZ,
+  processed_at TIMESTAMPTZ,
+  worker TEXT,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT
+);
+
+CREATE INDEX IF NOT EXISTS outbox_unprocessed ON outbox (processed_at, topic, id);
+
+CREATE TABLE IF NOT EXISTS idempotency (
+  key TEXT PRIMARY KEY,
+  request_hash TEXT NOT NULL,
+  status_code INTEGER NOT NULL,
+  response_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS ledger_entries (
+  entry_id TEXT PRIMARY KEY,
+  entry_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS ledger_balances (
+  account_id TEXT PRIMARY KEY,
+  balance_cents BIGINT NOT NULL
+);
+

package/src/db/migrations/002_robot_reservations.sql

@@ -0,0 +1,23 @@
+-- v1.0: robot reservations index + overlap prevention.
+
+-- Needed for exclusion constraints on TEXT columns.
+CREATE EXTENSION IF NOT EXISTS btree_gist WITH SCHEMA public;
+
+CREATE TABLE IF NOT EXISTS robot_reservations (
+  job_id TEXT PRIMARY KEY,
+  robot_id TEXT NOT NULL,
+  "window" TSTZRANGE NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'robot_reservations_no_overlap'
+  ) THEN
+    ALTER TABLE robot_reservations
+      ADD CONSTRAINT robot_reservations_no_overlap
+      EXCLUDE USING gist (robot_id WITH =, "window" WITH &&);
+  END IF;
+END $$;

package/src/db/migrations/003_idempotency_v2.sql

@@ -0,0 +1,32 @@
+-- v1.0: structured idempotency keys (principal, endpoint, key).
+
+ALTER TABLE idempotency RENAME TO idempotency_v0;
+
+CREATE TABLE idempotency (
+  principal_id TEXT NOT NULL,
+  endpoint TEXT NOT NULL,
+  idem_key TEXT NOT NULL,
+  request_hash TEXT NOT NULL,
+  status_code INTEGER NOT NULL,
+  response_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (principal_id, endpoint, idem_key)
+);
+
+-- Best-effort migration from v0 keys of the form METHOD:/path:idempotencyKey.
+INSERT INTO idempotency (principal_id, endpoint, idem_key, request_hash, status_code, response_json, created_at, updated_at)
+SELECT
+  'anon' AS principal_id,
+  split_part(key, ':', 1) || ' ' || split_part(key, ':', 2) AS endpoint,
+  split_part(key, ':', 3) AS idem_key,
+  request_hash,
+  status_code,
+  response_json,
+  created_at,
+  updated_at
+FROM idempotency_v0
+WHERE key LIKE '%:%:%';
+
+DROP TABLE idempotency_v0;
+

package/src/db/migrations/004_notifications.sql

@@ -0,0 +1,12 @@
+-- v1.0: notifications sink (outbox-driven).
+
+CREATE TABLE IF NOT EXISTS notifications (
+  id BIGSERIAL PRIMARY KEY,
+  outbox_id BIGINT UNIQUE,
+  topic TEXT NOT NULL,
+  payload_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS notifications_by_topic ON notifications (topic, id);
+