diff --git a/packages/cli/README.md b/packages/cli/README.md index 8b5f30401..b8c2bf985 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1437,12 +1437,16 @@ The file is `/triage/route.json` (packages/webui/src/triage-route-store.mjs): a catalogue model key, a harness name and a daily cap leaf `{limit, since, reset, timeZone}`. It holds no env value and no key. The day resets at 00:00 in the zone given, which has no -default; an unknown zone refuses. The directory is 0700 and the file 0600, +default; an unknown zone refuses. The first cap counts from the time it is +set; a later change keeps that `since`, as an organization's token limits do, +so lowering the cap never drops tokens already spent. The directory is 0700 and the file 0600, owned by the running user; a link, a non-file, a wrong mode or owner, or an unknown field refuses (exit 3). A write is compare-and-set on `revision` (`--revision 0`: only when nothing is set), atomic, and appends one line with the old and new values to `route-receipts.jsonl`. A write that died leaves `route.lock`; the next write refuses and names it, and you remove it by hand. +If the route changed but its receipt line could not be written, the write +refuses with `triage-route-unrecorded` (exit 3) and names the new revision. `set` checks the harness against packages/plugins/harness/; it does not check the model key against a catalogue yet. diff --git a/packages/webui/src/triage-route-store.mjs b/packages/webui/src/triage-route-store.mjs index 801b8775f..b26015c65 100644 --- a/packages/webui/src/triage-route-store.mjs +++ b/packages/webui/src/triage-route-store.mjs @@ -11,12 +11,13 @@ // a link, a hard link, a non-file, a wrong mode or owner, an unknown field or an unknown time zone // refuses. A write is compare-and-set on `revision` under an exclusive lock file, atomic (a 0600 // temp file in the same directory, fsync, rename, fsync of the directory), and appends one line -// to route-receipts.jsonl. A writer that dies leaves its lock; the next write refuses and names +// to route-receipts.jsonl. Files and the directory the store makes get their modes set on the open +// descriptor, so the owner's umask cannot leave them unreadable. A writer that dies leaves its lock; the next write refuses and names // it, and the person removes it by hand, as with the organization lifecycle fence. // // Choices Jason may still reverse each live in one place: the file location (routePaths), the // field names (ROUTE_FIELDS, CAP_FIELDS) and the reset rule (capFor). -import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs"; +import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs"; import { randomBytes } from "node:crypto"; import { join } from "node:path"; import { isDailyModelQuota } from "../../plugins/src/model-quota.mjs"; @@ -53,20 +54,19 @@ export function routePaths(dataRoot) { } // The reset rule, in one place: the day resets at 00:00 in the owner's zone, which has no default. -// A cap whose limit, reset and zone are unchanged keeps its `since`; any other cap counts from now. +// A first cap counts from now; a changed cap keeps its stored `since`, as an organization's token +// limits do (packages/organization/src/launch-settings.mjs stamp), so lowering the cap never drops +// the tokens already spent today. Only a reset would move it, and this slice has no reset verb. export function capFor({ limit, timeZone, previous, now }) { - const reset = "00:00"; - const same = previous && previous.limit === limit && previous.reset === reset && previous.timeZone === timeZone; - return { limit, since: same ? previous.since : now, reset, timeZone }; + return { limit, since: previous ? previous.since : now, reset: "00:00", timeZone }; } const plain = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype; const exactKeys = (v, keys) => plain(v) && Object.keys(v).length === keys.length && keys.every((k) => Object.hasOwn(v, k)); const canonicalTime = (s) => typeof s === "string" && ISO.test(s) && !Number.isNaN(Date.parse(s)) && new Date(s).toISOString() === s; -const knownZone = (zone) => { - if (typeof zone !== "string" || zone === "") return false; - try { new Intl.DateTimeFormat("en-US", { timeZone: zone }); return true; } catch { return false; } -}; +// The same zone rule the stored cap is held to (isDailyModelQuota: its zone shape, then Intl). +const knownZone = (zone) => typeof zone === "string" + && isDailyModelQuota(LEAF_KEY, { limit: 0, since: "2000-01-01T00:00:00.000Z", reset: "00:00", timeZone: zone }); export function validRoute(doc) { return exactKeys(doc, ROUTE_FIELDS) @@ -81,6 +81,8 @@ export function validRoute(doc) { } const uidOf = (opts) => opts.uid ?? process.getuid(); +// The owner the files are held to: the same user, unless a test checks the file owner alone. +const fileUidOf = (opts) => opts.fileUid ?? uidOf(opts); // The triage directory: a real directory, the running user's, mode 0700. Returns false when it is // missing and `create` is off; with `create` it makes it (never the data root above it). @@ -91,6 +93,11 @@ function checkDir(dir, uid, { create }) { if (e.code !== "ENOENT") throw unreadable("the triage directory cannot be read"); if (!create) return false; try { mkdirSync(dir, { mode: 0o700 }); } catch { throw unreadable("the triage directory cannot be made"); } + // The umask may have narrowed the mode; set it on the directory just made, never through a link. + try { + const fd = openSync(dir, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW); + try { fchmodSync(fd, 0o700); } finally { closeSync(fd); } + } catch { throw unreadable("the triage directory cannot be made"); } st = lstatSync(dir); } if (st.isSymbolicLink()) throw unreadable("the triage directory is a link"); @@ -131,9 +138,8 @@ function readFile(file, uid) { // The stored route, or null when none is set. Throws triage-route-unreadable on anything unsafe. export function readRoute(dataRoot, opts = {}) { const { dir, file } = routePaths(dataRoot); - const uid = uidOf(opts); - if (!checkDir(dir, uid, { create: false })) return null; - return readFile(file, uid); + if (!checkDir(dir, uidOf(opts), { create: false })) return null; + return readFile(file, fileUidOf(opts)); } function checkInput(input) { @@ -186,13 +192,18 @@ function dropLock(lock, held) { closeSync(held.fd); } -// The receipts file, opened for append before the route changes, so a bad one refuses first. +// The receipts file, opened for append before the route changes, so a bad one refuses first. An +// existing file is held to its checks as it is; only a file made here gets its mode set. function openReceipts(receipts, uid) { + const flags = constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK; let fd; - try { fd = openSync(receipts, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600); } + try { fd = openSync(receipts, flags); } catch (e) { if (e.code === "ELOOP") throw unreadable("route-receipts.jsonl is a link"); - throw unreadable("route-receipts.jsonl cannot be opened"); + if (e.code !== "ENOENT") throw unreadable("route-receipts.jsonl cannot be opened"); + try { fd = openSync(receipts, flags | constants.O_CREAT | constants.O_EXCL, 0o600); } + catch { throw unreadable("route-receipts.jsonl cannot be made"); } + try { fchmodSync(fd, 0o600); } catch { closeSync(fd); throw unreadable("route-receipts.jsonl cannot be made"); } } try { checkFile(fd, uid, "route-receipts.jsonl"); } catch (e) { closeSync(fd); throw e; } return fd; @@ -203,18 +214,21 @@ const summary = (doc) => (doc ? { model: doc.model, harness: doc.harness, cap: d // Set the route. input: { model, harness, limit, timeZone, by, revision? }. With `revision` the // write happens only if the stored revision equals it (0: only when no route is set yet); without // it, the revision read under the lock. Returns the new route. -// opts.now and opts.uid are for tests; opts.hook(stage) is a test seam at "crash" (after the temp -// file is written) and "before-rename". +// opts.now, opts.uid and opts.fileUid are for tests; opts.hook(stage) is a test seam at "write" +// (inside the temp write), "crash" (after the temp file is written), "before-rename" and +// "after-rename" (before the receipt line). A failure after the rename refuses as +// triage-route-unrecorded: the route did change, and its receipt line is missing. export function writeRoute(dataRoot, input, opts = {}) { checkInput(input); const { dir, file, receipts, lock } = routePaths(dataRoot); const uid = uidOf(opts); + const fileUid = fileUidOf(opts); const now = (opts.now ?? (() => new Date()))().toISOString(); const hook = opts.hook ?? (() => {}); checkDir(dir, uid, { create: true }); const held = takeLock(lock); try { - const current = readFile(file, uid); + const current = readFile(file, fileUid); const stored = current?.revision ?? 0; if (input.revision !== undefined && input.revision !== stored) { throw new RouteStoreError("triage-route-stale", `the Triage route changed: the stored revision is ${stored}, not ${input.revision}`); @@ -225,21 +239,32 @@ export function writeRoute(dataRoot, input, opts = {}) { updatedAt: now, updatedBy: input.by, }; if (!validRoute(next)) throw invalid("the new route does not match the route shape"); - const receiptFd = openReceipts(receipts, uid); + const receiptFd = openReceipts(receipts, fileUid); try { const temp = join(dir, `.route.json.${process.pid}.${randomBytes(6).toString("hex")}.tmp`); - const tfd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + let tfd; + try { tfd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); } + catch { throw unreadable("route.json cannot be written"); } try { - writeSync(tfd, `${JSON.stringify(next, null, 2)}\n`); - fsyncSync(tfd); - } finally { closeSync(tfd); } + try { + fchmodSync(tfd, 0o600); + hook("write"); + writeSync(tfd, `${JSON.stringify(next, null, 2)}\n`); + fsyncSync(tfd); + } finally { closeSync(tfd); } + } catch { try { unlinkSync(temp); } catch {} throw unreadable("route.json cannot be written"); } hook("crash"); hook("before-rename"); try { renameSync(temp, file); } catch (e) { try { unlinkSync(temp); } catch {} throw unreadable("route.json cannot be replaced"); } - const dfd = openSync(dir, constants.O_RDONLY | constants.O_DIRECTORY); - try { fsyncSync(dfd); } finally { closeSync(dfd); } - writeSync(receiptFd, `${JSON.stringify({ at: now, by: input.by, revision: next.revision, from: summary(current), to: summary(next) })}\n`); - fsyncSync(receiptFd); + try { + hook("after-rename"); + const dfd = openSync(dir, constants.O_RDONLY | constants.O_DIRECTORY); + try { fsyncSync(dfd); } finally { closeSync(dfd); } + writeSync(receiptFd, `${JSON.stringify({ at: now, by: input.by, revision: next.revision, from: summary(current), to: summary(next) })}\n`); + fsyncSync(receiptFd); + } catch { + throw new RouteStoreError("triage-route-unrecorded", `the Triage route changed to revision ${next.revision}, but its receipt line was not written`); + } } finally { closeSync(receiptFd); } return next; } finally { dropLock(lock, held); } diff --git a/packages/webui/tests/triage-route-store.test.mjs b/packages/webui/tests/triage-route-store.test.mjs index 0732484f8..d8fb888be 100644 --- a/packages/webui/tests/triage-route-store.test.mjs +++ b/packages/webui/tests/triage-route-store.test.mjs @@ -48,11 +48,12 @@ test("paths, field names and the reset rule each live in one place", () => { assert.equal(ROUTE_VERSION, 1); // A new cap starts its count now and resets at 00:00 in the owner's zone. assert.deepEqual(capFor({ limit: 5, timeZone: "UTC", previous: null, now: NOW }), { limit: 5, since: NOW, reset: "00:00", timeZone: "UTC" }); - // The same cap keeps its since; a changed limit or zone starts again. + // A later cap keeps its since, changed or not, as an organization's token limits do: lowering + // the cap never drops the tokens already counted. const prev = { limit: 5, since: NOW, reset: "00:00", timeZone: "UTC" }; assert.equal(capFor({ limit: 5, timeZone: "UTC", previous: prev, now: LATER }).since, NOW); - assert.equal(capFor({ limit: 6, timeZone: "UTC", previous: prev, now: LATER }).since, LATER); - assert.equal(capFor({ limit: 5, timeZone: "Europe/Berlin", previous: prev, now: LATER }).since, LATER); + assert.equal(capFor({ limit: 2, timeZone: "UTC", previous: prev, now: LATER }).since, NOW); + assert.equal(capFor({ limit: 5, timeZone: "Europe/Berlin", previous: prev, now: LATER }).since, NOW); }); test("no file reads as not set; a write then reads back the same route", (t) => { @@ -88,7 +89,7 @@ test("each write appends one receipt line with the old and the new value", (t) = assert.equal(lines[1].revision, 2); assert.deepEqual(lines[1].from, { model: "glm-5", harness: "claude-code", cap: good().cap }); assert.equal(lines[1].to.cap.limit, 1000); - assert.equal(lines[1].to.cap.since, LATER); + assert.equal(lines[1].to.cap.since, NOW); assert.equal(lstatSync(routePaths(d).receipts).mode & 0o777, 0o600); // A refused write appends nothing. assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(LATER) }), code("triage-route-stale")); @@ -121,6 +122,7 @@ test("refused input shapes on a write", (t) => { [{ ...INPUT, limit: "100" }, /the cap must be/], [{ ...INPUT, limit: 2 ** 53 }, /the cap must be/], [{ ...INPUT, timeZone: undefined }, /a time zone is required/], [{ ...INPUT, timeZone: "" }, /time zone is unknown/], [{ ...INPUT, timeZone: "Mars/Olympus_Mons" }, /time zone is unknown/], [{ ...INPUT, timeZone: "../etc" }, /time zone is unknown/], + [{ ...INPUT, timeZone: "+05:00" }, /time zone is unknown/], [{ ...INPUT, by: "" }, /actor name/], [{ ...INPUT, by: "Owner Person" }, /actor name/], [{ ...INPUT, revision: -1 }, /revision must be/], [{ ...INPUT, revision: "1" }, /revision must be/], [{ ...INPUT, revision: 1.5 }, /revision must be/], [{ ...INPUT, env: { A: "b" } }, /unknown field env/], [{ ...INPUT, key: "mst-x" }, /unknown field key/], @@ -221,6 +223,14 @@ test("a wrong owner refuses on the directory and the file", (t) => { plant(d, good()); // Pretend to be another user: the store compares with the uid it is given. const other = process.getuid() + 1; + // The files alone owned by someone else: route.json on read and write, the receipts on write. + assert.throws(() => readRoute(d, { fileUid: other }), unreadableFor(/route\.json is not owned by this user/)); + assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(NOW), fileUid: other }), unreadableFor(/route\.json is not owned by this user/)); + const e = root(t); + writeRoute(e, INPUT, { now: at(NOW) }); + unlinkSync(routePaths(e).file); + assert.throws(() => writeRoute(e, INPUT, { now: at(NOW), fileUid: other }), unreadableFor(/route-receipts\.jsonl is not owned by this user/)); + assert.equal(existsSync(routePaths(e).file), false); assert.throws(() => readRoute(d, { uid: other }), unreadableFor(/the triage directory is not owned by this user/)); assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(NOW), uid: other }), unreadableFor(/the triage directory is not owned by this user/)); assert.equal(readRoute(d, { uid: process.getuid() }).revision, 1); @@ -277,6 +287,38 @@ test("a link at the file, the directory or the receipts refuses; so does a non-f assert.equal(existsSync(join(d, "nowhere")), false); }); +test("a write under a narrow umask still leaves 0700 and 0600, so the next read works", (t) => { + const d = root(t); + const old = process.umask(0o277); + let written; + try { written = writeRoute(d, INPUT, { now: at(NOW) }); } finally { process.umask(old); } + const { dir, file, receipts: r } = routePaths(d); + assert.equal(lstatSync(dir).mode & 0o777, 0o700); + assert.equal(lstatSync(file).mode & 0o777, 0o600); + assert.equal(lstatSync(r).mode & 0o777, 0o600); + assert.deepEqual(readRoute(d), written); + // An existing receipts file is never repaired: a wrong mode still refuses. + chmodSync(r, 0o644); + assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(LATER) }), unreadableFor(/route-receipts\.jsonl mode is not 0600/)); +}); + +test("a failed temp write refuses and leaves the route; a failed receipt after the rename says so", (t) => { + const d = root(t); + writeRoute(d, INPUT, { now: at(NOW) }); + const before = readFileSync(routePaths(d).file, "utf8"); + const fail = (stage) => (s) => { if (s === stage) throw Object.assign(new Error("no space"), { code: "ENOSPC" }); }; + assert.throws(() => writeRoute(d, { ...INPUT, limit: 1, revision: 1 }, { now: at(LATER), hook: fail("write") }), unreadableFor(/route\.json cannot be written/)); + assert.equal(readFileSync(routePaths(d).file, "utf8"), before); + assert.deepEqual(readdirSync(routePaths(d).dir).sort(), ["route-receipts.jsonl", "route.json"]); + assert.equal(receipts(d).length, 1); + // After the rename the route has changed; the refusal names the new revision and the missing line. + assert.throws(() => writeRoute(d, { ...INPUT, limit: 1, revision: 1 }, { now: at(LATER), hook: fail("after-rename") }), + (e) => code("triage-route-unrecorded")(e) && /changed to revision 2, but its receipt line was not written/.test(e.message)); + assert.equal(readRoute(d).revision, 2); + assert.equal(receipts(d).length, 1); + assert.deepEqual(readdirSync(routePaths(d).dir).sort(), ["route-receipts.jsonl", "route.json"]); +}); + test("the store makes its directory 0700 but never the data root", (t) => { const d = root(t); assert.throws(() => writeRoute(join(d, "missing"), INPUT, { now: at(NOW) }), code("triage-route-unreadable"));