@heyquilt/seam 0.27.0 → 0.130.0

package/lib/quilts/attest.js

@@ -0,0 +1,212 @@
+// Server attestation (plans/quilt-source-control/11.7): every log row is signed by the server
+// after it commits, outside the quilt row lock, with an Ed25519 key only Seam's server holds. An
+// attestation names the row's quilt, its dense seq, the hash of its canonical encoding, who wrote
+// it (and for whom, and with which quilt token), and when. So a row edited in the database fails
+// its signature, an inserted one collides with a signed seq or arrives unsigned, and a removed
+// one leaves a gap: anyone with the published keys can check a quilt's log offline.
+//
+// The API process that wrote a row signs it as soon as its write returns. A row found unsigned
+// later than LATE_MS after it was written (its server died first) is signed by whoever finds it
+// and marked `late`: that proves only that the row was in the database when it was read.
+//
+// Member signatures (signing.js) stay alongside as the co-signature: a person's own key over a
+// commit id, which the server can never forge (ruling in 11.7).
+import crypto from 'node:crypto'
+import { blake3 } from '@noble/hashes/blake3.js'
+import { QuiltError } from './errors.js'
+
+export const LATE_MS = 60 * 1000
+export const SWEEP_MS = 30 * 1000
+const BATCH = 500
+const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex')
+
+/**
+ * Canonical JSON: keys sorted at every level, and a key whose value is null or undefined left out
+ * (as Postgres' jsonb_strip_nulls does), so a row reads the same from either store.
+ */
+export function canonical (v) {
+  if (Array.isArray(v)) return '[' + v.map((x) => x === undefined ? 'null' : canonical(x)).join(',') + ']'
+  if (v && typeof v === 'object') return '{' + Object.keys(v).filter((k) => v[k] != null).sort().map((k) => JSON.stringify(k) + ':' + canonical(v[k])).join(',') + '}'
+  return JSON.stringify(v ?? null)
+}
+
+// The fields of a log row that it is (03); `checks`, the one mutable column, is left out.
+const ROW_FIELDS = ['quilt_id', 'seq', 'kind', 'commit', 'square', 'line', 'patch_no', 'from', 'to', 'actor', 'at', 'snapshot_root', 'payload']
+
+/** A log row's canonical bytes: the same from the memory store and Postgres. */
+export function rowBytes (row) {
+  const out = {}
+  for (const k of ROW_FIELDS) if (row[k] != null) out[k] = row[k]
+  if (!out.payload) out.payload = {}
+  return Buffer.from(canonical(out))
+}
+export const rowHash = (row) => Buffer.from(blake3(rowBytes(row), { context: Buffer.from('seam log row v1') })).toString('hex')
+
+const SIGNED = ['quilt_id', 'seq', 'kind', 'row_hash', 'commit', 'author', 'on_behalf_of', 'token_id', 'at', 'late', 'key_id']
+/** What a signature covers: the attestation's fields, canonical, after a context line. */
+export const attestationText = (a) => 'seam-attestation-v1\n' + canonical(Object.fromEntries(SIGNED.map((k) => [k, a[k] ?? null])))
+
+/** A key's id: `ed25519:` and the first 16 hex of the sha256 of its raw public bytes. */
+const keyIdOf = (raw) => 'ed25519:' + crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16)
+
+/**
+ * The server's attestation key from SEAM_ATTESTATION_KEY (an Ed25519 private key: PKCS8 PEM, or
+ * base64 of its PKCS8 DER), or a new one for this process when none is given.
+ */
+export function attestationKey (secret) {
+  let key
+  if (secret) {
+    const s = String(secret).trim()
+    key = s.includes('BEGIN') ? crypto.createPrivateKey(s) : crypto.createPrivateKey({ key: Buffer.from(s, 'base64'), format: 'der', type: 'pkcs8' })
+    if (key.asymmetricKeyType !== 'ed25519') throw new Error('SEAM_ATTESTATION_KEY is not an Ed25519 private key')
+  } else key = crypto.generateKeyPairSync('ed25519').privateKey
+  const raw = crypto.createPublicKey(key).export({ format: 'der', type: 'spki' }).subarray(SPKI_PREFIX.length)
+  return { id: keyIdOf(raw), public_key: raw.toString('base64'), ephemeral: !secret, sign: (text) => crypto.sign(null, Buffer.from(text), key).toString('base64') }
+}
+
+/** Whether `a` is a good attestation of `row` under one of `keys` ([{ id, public_key }]). */
+export function verifyAttestation (a, row, keys) {
+  if (!a) return 'unsigned'
+  if (a.seq !== row.seq || a.kind !== row.kind || a.row_hash !== rowHash(row)) return 'mismatch'
+  const k = keys.find((x) => x.id === a.key_id)
+  if (!k) return 'unknown_key'
+  try {
+    const pub = crypto.createPublicKey({ key: Buffer.concat([SPKI_PREFIX, Buffer.from(k.public_key, 'base64')]), format: 'der', type: 'spki' })
+    if (!crypto.verify(null, Buffer.from(attestationText(a)), pub, Buffer.from(String(a.sig), 'base64'))) return 'bad_signature'
+  } catch { return 'bad_signature' }
+  return a.late ? 'late' : 'ok'
+}
+
+/**
+ * Checks a run of log rows against their attestations: { checked, ok, late, unsigned, bad, gaps }
+ * (each a list of seqs, gaps as [from, to] where seqs are missing between rows).
+ */
+export function verifyLog (rows, attestations, keys) {
+  const bySeq = new Map(attestations.map((a) => [a.seq, a]))
+  const out = { checked: rows.length, ok: 0, late: [], unsigned: [], bad: [], gaps: [] }
+  let prev = null
+  for (const row of rows) {
+    if (prev != null && row.seq !== prev + 1) out.gaps.push([prev + 1, row.seq - 1])
+    prev = row.seq
+    const v = verifyAttestation(bySeq.get(row.seq), row, keys)
+    if (v === 'ok') out.ok++
+    else if (v === 'late') { out.ok++; out.late.push(row.seq) } else if (v === 'unsigned') out.unsigned.push(row.seq)
+    else out.bad.push({ seq: row.seq, why: v })
+  }
+  // A signed seq with no row: the row was removed after it was signed.
+  const seen = new Set(rows.map((r) => r.seq))
+  const lo = rows.length ? rows[0].seq : 0
+  const hi = rows.length ? rows[rows.length - 1].seq : 0
+  for (const a of attestations) if (a.seq >= lo && a.seq <= hi && !seen.has(a.seq)) out.bad.push({ seq: a.seq, why: 'row_missing' })
+  return out
+}
+
+/**
+ * The signer: attest(qid) signs every row of the quilt still unsigned (from the lowest one this
+ * process has not yet seen signed), sweep() does it for each quilt this process has written.
+ */
+export function createAttester ({ store, now = Date.now, key, log = () => {} }) {
+  const floor = new Map() // quilt → seq below which every row is known signed
+  const running = new Map()
+  async function attestOnce (qid) {
+    for (;;) {
+      const rows = await store.unattested(qid, { after: floor.get(qid) || 0, limit: BATCH })
+      if (!rows.length) return
+      const at = now()
+      const out = []
+      for (const row of rows) {
+        const c = row.kind === 'commit' || row.kind === 'merge' ? (row.commit ? await store.getCommit(qid, row.commit) : null) : null
+        const a = {
+          quilt_id: qid, seq: row.seq, kind: row.kind, row_hash: rowHash(row), commit: row.commit || null,
+          author: row.actor, on_behalf_of: c?.on_behalf_of || null,
+          token_id: String(row.actor || '').startsWith('token:') ? row.actor.slice(6) : null,
+          at: row.at, late: at - row.at > LATE_MS, key_id: key.id
+        }
+        out.push({ ...a, sig: key.sign(attestationText(a)), signed_at: at })
+      }
+      await store.addAttestations({ quilt_id: qid, rows: out })
+      const late = out.filter((a) => a.late).length
+      if (late) log(`seam attestation: signed ${late} late row${late === 1 ? '' : 's'} of quilt ${qid}`)
+      floor.set(qid, rows[rows.length - 1].seq)
+      if (rows.length < BATCH) return
+    }
+  }
+  /** Signs the quilt's unsigned rows; one pass at a time per quilt, a second call waits for it. */
+  function attest (qid) {
+    const prev = running.get(qid) || Promise.resolve()
+    const next = prev.then(() => attestOnce(qid)).catch((err) => log(`seam attestation: ${qid}: ${err.message}`))
+    running.set(qid, next)
+    next.finally(() => { if (running.get(qid) === next) running.delete(qid) })
+    return next
+  }
+  async function sweep () { for (const qid of floor.keys()) await attest(qid) }
+  let timer = null
+  return {
+    key,
+    attest,
+    sweep,
+    start () { if (!timer) { timer = setInterval(() => sweep().catch(() => {}), SWEEP_MS); timer.unref?.() } },
+    stop () { if (timer) clearInterval(timer); timer = null }
+  }
+}
+
+/** GET /attestations, GET /verify and the published keys. */
+export function attestationOps (svc, attester) {
+  const { store, quiltFor } = svc.internals
+  const keys = () => attester ? [{ id: attester.key.id, public_key: attester.key.public_key, use: 'attestation' }] : []
+
+  async function readable (me, ref) {
+    const q = await quiltFor(me, ref, 'read')
+    // Log rows name paths and squares: only a caller who may read the whole quilt gets them raw.
+    if (q.access.restricted) throw new QuiltError(403, 'protections', 'your reads in this quilt are limited by path, so its raw log is not yours to read', { need: 'read' })
+    if (!attester) throw new QuiltError(409, 'attestation_off', 'this Seam server does not sign its log (start it with SEAM_ATTESTATION=1)')
+    return q
+  }
+
+  /** GET /attestations?after=&limit=: each log row with its attestation (null while unsigned). */
+  async function attestations (me, ref, { after = 0, limit = 200 } = {}) {
+    const q = await readable(me, ref)
+    await attester.attest(q.id)
+    const max = Math.min(Math.max(Number(limit) || 200, 1), 1000)
+    const rows = await store.logRows(q.id, { after: Number(after) || 0, limit: max })
+    const signed = rows.length ? await store.attestationsOf(q.id, { from: rows[0].seq, to: rows[rows.length - 1].seq }) : []
+    const bySeq = new Map(signed.map((a) => [a.seq, a]))
+    return { quilt: q.slug, quilt_id: q.id, keys: keys(), rows: rows.map((row) => ({ row, attestation: bySeq.get(row.seq) || null })), more: rows.length === max }
+  }
+
+  /** GET /verify?after=&limit=: the server's own check of its log against the published keys. */
+  async function verify (me, ref, opts = {}) {
+    const r = await attestations(me, ref, opts)
+    return { quilt: r.quilt, ...verifyLog(r.rows.map((x) => x.row), r.rows.map((x) => x.attestation).filter(Boolean), r.keys), more: r.more }
+  }
+
+  return { attestations, verify, attestationKeys: async () => ({ keys: keys() }) }
+}
+
+/**
+ * `seam verify`: reads a quilt's log and attestations through `client` and checks them here,
+ * against `keys` (pinned by the caller) or the server's published keys.
+ */
+export async function verifyQuilt (client, quilt, { after = 0, keys = null } = {}) {
+  const pinned = keys || (await client.attestationKeys()).keys
+  const rows = []; const atts = []
+  let from = Number(after) || 0
+  for (;;) {
+    const r = await client.attestations(quilt, { after: from, limit: 1000 })
+    for (const x of r.rows) { rows.push(x.row); if (x.attestation) atts.push(x.attestation) }
+    if (!r.more || !r.rows.length) break
+    from = r.rows[r.rows.length - 1].row.seq
+  }
+  return { quilt, keys: pinned.map((k) => k.id), ...verifyLog(rows, atts, pinned) }
+}
+
+/** A verification in a few lines. */
+export function describeVerify (v) {
+  const head = `Checked ${v.checked} log row${v.checked === 1 ? '' : 's'} of ${v.quilt} against ${v.keys.join(', ') || 'no keys'}: ${v.ok} signed`
+  const lines = [head + (v.late.length ? ` (${v.late.length} late: ${v.late.slice(0, 10).join(', ')}${v.late.length > 10 ? ', …' : ''})` : '') + '.']
+  if (v.unsigned.length) lines.push(`Not signed yet: ${v.unsigned.slice(0, 20).join(', ')}${v.unsigned.length > 20 ? ', …' : ''}.`)
+  for (const b of v.bad.slice(0, 20)) lines.push(`Row ${b.seq}: ${{ mismatch: 'its row is not the row that was signed (changed after it was written)', bad_signature: 'its signature does not check out', unknown_key: 'signed with a key not in the list', row_missing: 'signed, but the row is gone' }[b.why] || b.why}.`)
+  for (const [a, b] of v.gaps.slice(0, 20)) lines.push(`Rows ${a === b ? a : `${a} to ${b}`} are missing.`)
+  if (!v.unsigned.length && !v.bad.length && !v.gaps.length) lines.push('Every row is the row the server signed, and none is missing.')
+  return lines.join('\n')
+}

package/lib/quilts/bisect-run.js

@@ -1,6 +1,7 @@
 // The check side of bisect (the server narrows, history.js): each commit the server names is
 // checked out into a fresh folder and the check command runs there. Exit 0 is good, 125 is skip,
 // 1 to 127 is bad, anything else (a signal, 128 and up) stops, as git bisect run does.
+// `paths` are checked out; `only` narrows the commits tested to those that touched them.
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
@@ -13,10 +14,10 @@ const runIn = (cmd, cwd) => new Promise((resolve, reject) => {
   child.on('exit', (code, signal) => resolve(signal ? null : code))
 })
 
-export async function bisectRun (client, { quilt, bad, good, run, marks = {}, paths = [''], api, log = () => {} }) {
+export async function bisectRun (client, { quilt, bad, good, run, marks = {}, paths = [''], only, api, log = () => {} }) {
   const m = { ...marks }
   for (let i = 0; i < 200; i++) {
-    const r = await client.bisect(quilt, { bad, good, marks: m })
+    const r = await client.bisect(quilt, { bad, good, marks: m, ...(only && only.length ? { paths: only } : {}) })
     if (r.done) return { ...r, marks: m }
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'seam-bisect-'))
     try {