sign-off-axi 0.3.3 → 0.3.4

package/README.md

@@ -137,8 +137,8 @@ sign-off-axi status                             is the board open started for th
 sign-off-axi stop                               stop that board
 sign-off-axi serve [--port 4410] [--bind <address>] [--evidence-root <dir>]   run the board in the foreground (--port 0 picks a free port)
 sign-off-axi answers [--key <key>]              the latest answer per decision, and how many still wait
-sign-off-axi wait [--filer <id>] [--key <key>] [--timeout 600]  block until the user answers, then print it like answers
-                                                (--filer: only that filer's items; without --key each answer once)
+sign-off-axi wait [--filer <id>] [--key <key>] [--timeout 600] [--events (needs --filer)]  block until the user answers, then print it like answers; --events prints one JSON event line per answer and round (docs/contract.md section 7)
+                                                (--filer: only that filer's items, each marked taken; without --key each answer once)
 sign-off-axi poll [--timeout 600]               block until the user comments or queues a prompt, then print each new one once
 sign-off-axi export [--out <file.html>]          write a frozen read-only copy of the board as one HTML file
 ```
@@ -159,8 +159,8 @@ sign-off-axi export [--out <file.html>]          write a frozen read-only copy o
 - Raising a question that is already on the board is a no-op that reports its status, so an agent can re-run it safely. `--key` defaults to a slug of the title.
 - Each raised or posted item records when it was filed (`filed`), so Triage shows `Waiting since 09:15` and the Waiting on you tile `Oldest 09:15`; `post --replace` keeps an item's first time.
 - `open` is a no-op when the same board is already open on the same address, and fails with `CONFLICT` when it runs on another one. `--evidence-root` is the folder holding `.done-done/`, for decisions that link run evidence.
-- `--filer <id>` on `post` and `raise` saves who filed the item (an agent session id or any 1-128 of `A-Z a-z 0-9 . _ -`; `SIGN_OFF_FILER` sets it for every command, and a post with neither saves `CLAUDE_CODE_SESSION_ID` when it is set). `wait --filer <id>` then returns only answers to that filer's items it has not taken yet, marks each taken (`decisions.seen.jsonl`) and the card shows **Seen by agent**; it fails with `NOT_FOUND` when none of that filer's items still needs an answer. The page never shows the filer id.
-- `on_answer: <command> [args]` in the `config.yaml` beside the board runs that command for every saved answer, read when the board starts. It runs with no shell, in the board's folder, and gets the answer as one JSON line on stdin (`{"key","answer","label","close","at","note"?,"title"?,"filer"?,"comments"?}`, where `comments`, present when the answer carried comments on mock elements, lists each as `id`, `mock`, `hash`, `ref`, `tag`, `words` and `text`); the answer is never put into its arguments, so a typed note cannot inject a command. A failure is logged and never blocks the answer. With no shell, `|`, `>` and `&&` are passed as plain arguments, so put a pipeline in a script and name the script; a relative path such as `./hook.sh` is found from the board's folder. `doctor` checks that the command can run.
+- `--filer <id>` on `post` and `raise` saves who filed the item (an agent session id or any 1-128 of `A-Z a-z 0-9 . _ -`; `SIGN_OFF_FILER` sets it for every command, and a post with neither saves `CLAUDE_CODE_SESSION_ID` when it is set). `wait --filer <id>` then returns only answers to that filer's items it has not taken yet (with `--key`, that key's answer even if taken), marks each taken (`decisions.seen.jsonl`) and the card shows **Seen by agent**; it fails with `NOT_FOUND` when none of that filer's items still needs an answer. The page never shows the filer id.
+- `on_answer: <command> [args]` in the `config.yaml` beside the board runs that command for every saved answer, read when the board starts. It runs with no shell, in the board's folder, and gets the answer as one JSON line on stdin (`{"event":"answer","contract":1,"kind","schema","key","answer","label","close","at","note"?,"title"?,"filer"?,"comments"?}`, where `kind` and `schema` are the item's contract kind, or `ask` and 1 for a board-format item, and `comments`, present when the answer carried comments on mock elements, lists each as `id`, `mock`, `hash`, `ref`, `tag`, `words` and `text`); the answer is never put into its arguments, so a typed note cannot inject a command. A failure is logged and never blocks the answer. With no shell, `|`, `>` and `&&` are passed as plain arguments, so put a pipeline in a script and name the script; a relative path such as `./hook.sh` is found from the board's folder. `doctor` checks that the command can run.
 - `post --from <file> --replace --filer <id>` lets several programs feed one board: it replaces only that filer's items (and items with no filer that the file names by key), keeps every other item, the board's other top-level fields and all answers, and an empty items list removes that filer's items.
 - `wait` replaces a polling loop. With `--key` it returns at once if that decision is already answered, and waits for a key that is not raised yet; without it, it waits for the next answer to any decision that still needs an answer and fails with `NOT_FOUND` when nothing needs one. It wakes on each save, gives up after `--timeout` seconds (600, ten minutes, by default) with code `TIMEOUT` and exit 1, and takes `--full` and `--json` like `answers`. Ctrl-C stops it without changing anything.
 - `open` records the board's pid, port and address next to the board file (`decisions.board.pid`). `status` and `stop` read it and only act on a pid that really serves that board, so no one has to guess a pid to kill. `open` on a board already served by `serve` records that server, so `stop` can close it too.

package/dist/cli.js

@@ -29,7 +29,7 @@ const TOP_HELP = `usage: sign-off-axi [command] [board.json] [flags]
 commands[15]:
   (none)=list, raise, post, answers, wait, poll, open, status, stop, serve, export, init, doctor, validate, help
 board: the nearest .sign-off/ board (the walk's bounds and SIGN_OFF_HOME: README, "Test runs never touch your board"), else ~/.sign-off/decisions.json; a board file given always wins
-flags: --full and --json on list, answers and wait, --json on status, --filer on post, raise and wait, --help on every command, -v/--version
+flags: --full and --json on list, answers and wait, --events on wait, --json on status, --filer on post, raise and wait, --help on every command, -v/--version
 examples:
   sign-off-axi
   sign-off-axi raise --title "Ship the new sign-in screen this week?" --recommend yes
@@ -106,7 +106,7 @@ examples:
   sign-off-axi answers --key keep-the-weekly-digest
   sign-off-axi answers ./decisions.json --json
 `,
-    wait: `usage: sign-off-axi wait [board.json] [--filer <id>] [--key <key>] [--timeout 600] [--full] [--json]
+    wait: `usage: sign-off-axi wait [board.json] [--filer <id>] [--key <key>] [--timeout 600] [--full] [--json | --events]
 Blocks until the user answers, then prints the answer the way answers does. Use it instead of a polling loop.
   --filer    only the items posted with this --filer (or SIGN_OFF_FILER): returns every answer to them this filer has not taken yet,
              even one saved before wait started, and marks it taken, so the board shows "Seen by agent" on that card;
@@ -117,11 +117,15 @@ Blocks until the user answers, then prints the answer the way answers does. Use
   --timeout  seconds to wait, 600 (10 minutes) by default; then exits 1 with code TIMEOUT
   --full     adds the button label, close and title
   --json     {"<key>":{"answer","label","close","at","note"?}} for the new answers; note only when the user wrote one
+  --events   needs --filer (or SIGN_OFF_FILER); one JSON line per new answer and per another-round ask, in the order they were saved (${CONTRACT}#7-answers):
+             {"event":"answer","contract":1,"kind","schema","key","title","answer","label","close","at","note"?,"filer"?,"comments"?}
+             {"event":"round","contract":1,"kind","schema","key","title","note","at","filer"?,"comments"?}; a board-format item reports as ask schema 1
 A note column appears when any shown answer has a note.
 Ctrl-C stops waiting; nothing is changed.
 examples:
   sign-off-axi wait --key keep-the-weekly-digest
   sign-off-axi wait ./decisions.json --timeout 60 --json
+  sign-off-axi wait --filer agent-41 --events
 `,
     open: `usage: sign-off-axi open [board.json] [--port 4410] [--bind <address>] [--evidence-root <dir>]
 Starts the board in the background on 127.0.0.1 and prints its URL and pid; a no-op when this board is already open.
@@ -442,11 +446,32 @@ function answers(args) {
     const waiting = rows.filter(waits).length, key = values.key === undefined ? '' : ` --key ${values.key}`;
     return printAnswers(file, rows, waiting, values, waiting ? [`Run \`sign-off-axi open${on}\` so the user can answer the ${waiting} waiting`, `Run \`sign-off-axi wait${on}${key}\` to block until they answer`] : []);
 }
+/** The contract fields an answer or round reports with: the item's kind and schema, or ask schema 1 for a board-format or dropped item (contract section 2). */
+function kindOf(file) {
+    const items = new Map((existsSync(file) ? readItems(file).items : []).map((i) => [i?.key, i]));
+    return (key) => {
+        const i = items.get(key), contract = typeof i?.kind === 'string';
+        return { contract: 1, kind: contract ? i.kind : 'ask', schema: contract ? i.schema : 1 };
+    };
+}
+/** One JSON line per answer and per round (contract section 7), oldest first. */
+function eventLines(file, rows, answers, rounds) {
+    const kind = kindOf(file), item = new Map(rows.map((d) => [d.key, d]));
+    const head = (event, key) => ({ event, ...kind(key), key, title: item.get(key)?.title });
+    const tail = (key, comments) => ({ ...(item.get(key)?.filer && { filer: item.get(key).filer }), ...(comments?.length && { comments }) });
+    return [...answers.map(({ key, answer, label, close, at, note, comments }) => ({ at, line: { ...head('answer', key), answer, label, close, at, ...(note && { note }), ...tail(key, comments) } })),
+        ...rounds.map(({ key, note, at, comments }) => ({ at, line: { ...head('round', key), note, at, ...tail(key, comments) } }))]
+        .sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0)).map(({ line }) => JSON.stringify(line)).join('\n');
+}
 async function wait(args) {
-    const { file, values, on: onBoard } = parse('wait', args, { ...TIERS, filer: { type: 'string' }, key: { type: 'string' }, timeout: { type: 'string', default: '600' }, into: { type: 'string' } });
+    const { file, values, on: onBoard } = parse('wait', args, { ...TIERS, events: { type: 'boolean' }, filer: { type: 'string' }, key: { type: 'string' }, timeout: { type: 'string', default: '600' }, into: { type: 'string' } });
     if (!/^\d{1,7}$/.test(values.timeout))
         throw fail('--timeout must be whole seconds, 0 or more', 'VALIDATION_ERROR', `Run \`sign-off-axi wait --help\``);
+    if (values.events && (values.json || values.full))
+        throw fail(`--events prints event lines, so it does not take --${values.json ? 'json' : 'full'}`, 'VALIDATION_ERROR', 'Run `sign-off-axi wait --filer <id> --events`');
     const filer = filerOf(values), on = onBoard + (filer ? ` --filer ${filer}` : '');
+    if (values.events && filer === undefined)
+        throw fail(`--events prints a filer's answer events, so it needs --filer`, 'VALIDATION_ERROR', 'Run `sign-off-axi wait --filer <id> --events`');
     // Vault Give delivery: its own loop, before any board read, so no ordinary wait changes. Undocumented while the vault is OFF.
     if (values.into !== undefined)
         return waitInto(file, values, onBoard);
@@ -471,22 +496,32 @@ async function wait(args) {
         for (let first = true;; first = false) {
             const rows = mine(board(file, first ? warn : () => { })), waiting = rows.filter(waits).length, taken = filer === undefined ? undefined : seenBy(file);
             const hit = rows.filter((d) => (values.key !== undefined ? d.key === values.key : d.answer && (taken ? !taken(d.answer) : !before.has(d.key))));
-            const counts = new Map();
-            for (const r of readRounds(file, first ? warn : () => { }))
+            const counts = new Map(), asked = [];
+            for (const r of readRounds(file, first ? warn : () => { })) {
                 counts.set(r.key, (counts.get(r.key) ?? 0) + 1);
+                if (counts.get(r.key) > (seenRounds.get(r.key) ?? 0))
+                    asked.push(r);
+            }
             const fresh = rows.filter((d) => (counts.get(d.key) ?? 0) > (seenRounds.get(d.key) ?? 0)
                 && (values.key === undefined || d.key === values.key));
             for (const [k, n] of counts)
                 seenRounds.set(k, n);
             let found = [...new Map([...hit.filter((d) => d.answer), ...fresh].map((d) => [d.key, d])).values()];
+            // The answers this wait hands over: a filer wait without --key gives only the ones it has not taken yet.
+            let given = hit.flatMap((d) => (d.answer ? [d.answer] : []));
             if (found.length && filer !== undefined) {
                 // Taken under a lock, so two waits for one filer never both hand over the same answer (another-round asks are not deduped here).
                 found = await locked(`${seenPath(file)}.lock`, () => {
                     const now = seenBy(file), left = found.filter((d) => values.key !== undefined || fresh.includes(d) || !now(d.answer));
-                    markSeen(file, left.flatMap((d) => (d.answer && !now(d.answer) ? [d.answer] : [])));
+                    const taking = left.flatMap((d) => (d.answer && !now(d.answer) ? [d.answer] : []));
+                    markSeen(file, taking);
+                    if (values.key === undefined)
+                        given = taking;
                     return left;
                 }, 'another wait is still taking answers');
             }
+            if (found.length && values.events)
+                return eventLines(file, found, given, asked.filter((r) => fresh.some((d) => d.key === r.key)));
             if (found.length) {
                 return printAnswers(file, found, waiting, values, [waiting ? `Run \`sign-off-axi wait${on}\` for the next of the ${waiting} waiting` : `Run \`sign-off-axi stop${onBoard}\` to close the board`]);
             }
@@ -1895,7 +1930,7 @@ function answered(a, d) {
     child.on('error', (e) => warn(`on_answer ${cmd} did not run: ${e.message}`));
     child.on('exit', (code, signal) => (code || signal) && warn(`on_answer ${cmd} exited with ${code ?? signal}`));
     child.stdin.on('error', () => { });
-    child.stdin.end(`${JSON.stringify({ ...a, ...(d && { title: d.title }), ...(d?.filer && { filer: d.filer }) })}\n`);
+    child.stdin.end(`${JSON.stringify({ event: 'answer', ...kindOf(file)(a.key), ...a, ...(d && { title: d.title }), ...(d?.filer && { filer: d.filer }) })}\n`);
 }
 const server = createServer(async (req, res) => {
     const { port: bound } = server.address();

package/dist/vault.js

@@ -2,6 +2,7 @@
 import { closeSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, parse, resolve } from 'node:path';
 import { homedir } from 'node:os';
+import { isIP } from 'node:net';
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
 import { isKey } from './store.js';
 export const errors = {
@@ -27,7 +28,7 @@ export class VaultError extends Error {
 }
 function bad(code) { throw new VaultError(code); }
 const digest = (board, key) => createHash('sha256').update(JSON.stringify([board, key])).digest('hex');
-const aad = (meta) => Buffer.from(JSON.stringify([1, meta.board, meta.key, meta.mode, meta.expires, meta.destination ?? null, meta.filer]));
+const aad = (meta) => Buffer.from(JSON.stringify([1, meta.board, meta.key, meta.mode, meta.expires, meta.destination ?? null, meta.filer, ...(meta.provider === undefined ? [] : [meta.provider])]));
 const VAULT_ID = /^[a-f0-9]{32}$/;
 function boardFile(board) {
     if (typeof board !== 'string' || !isAbsolute(board))
@@ -68,10 +69,10 @@ const plain = (p) => isAbsolute(p) && !p.split('/').some((s) => s === '.' || s =
 function metadata(m) {
     if (!m || typeof m.board !== 'string' || !VAULT_ID.test(m.board) || !isKey(m.key) || !isKey(m.filer) || !['give', 'receive'].includes(m.mode)
         || !Number.isSafeInteger(m.expires) || m.expires <= 0
-        || (m.mode === 'give' ? typeof m.destination !== 'string' || !plain(m.destination) : m.destination !== undefined))
+        || (m.mode === 'give' ? typeof m.destination !== 'string' || !plain(m.destination) || m.provider !== undefined : m.destination !== undefined || !isKey(m.provider)))
         bad('VALIDATION_ERROR');
     return { board: m.board, key: m.key, mode: m.mode, filer: m.filer, expires: m.expires,
-        ...(m.destination !== undefined && { destination: resolve(m.destination) }) };
+        ...(m.destination !== undefined && { destination: resolve(m.destination) }), ...(m.provider !== undefined && { provider: m.provider }) };
 }
 function privateFile(path) {
     const s = lstatSync(path);
@@ -138,6 +139,49 @@ function approvedDirs(file, dir) {
         return line;
     });
 }
+// Owner-only list of approved Receive sites: `<provider> <https-origin>` per line, `#` comments. Any bad line denies all.
+// Host rules live here; a link must then match one listed origin exactly, which carries them over.
+function approvedProviders() {
+    const list = join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'sign-off', 'vault-providers'), sites = new Map();
+    let text = '';
+    try {
+        if (isAbsolute(list)) {
+            privateFile(list);
+            text = readFileSync(list, 'utf8');
+        }
+    }
+    catch { /* denied below */ }
+    if (!text)
+        bad('VALIDATION_ERROR');
+    for (const line of text.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))) {
+        const [name, origin, extra] = line.split(/\s+/);
+        let host = '';
+        try {
+            const u = new URL(origin);
+            if (u.protocol === 'https:' && u.origin === origin && !u.port)
+                host = u.hostname;
+        }
+        catch { /* denied below */ }
+        if (extra !== undefined || !isKey(name) || sites.has(name) || !host.includes('.') || host.endsWith('.') || isIP(host))
+            bad('VALIDATION_ERROR');
+        sites.set(name, origin);
+    }
+    return sites;
+}
+/** A Receive link: one https URL whose exact origin the owner listed for its provider. Fails only with VALIDATION_ERROR, never echoing it. */
+export function checkReceiveUrl(value, provider) {
+    const origin = approvedProviders().get(provider);
+    let url;
+    try {
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(value).replace(/\r?\n$/, '');
+        // The URL parser silently drops tabs and newlines and trims spaces, so any space or control is refused before it.
+        if (!/[\x00-\x20\x7f-\x9f]/.test(text) && Buffer.byteLength(text) <= 8192)
+            url = new URL(text);
+    }
+    catch { /* refused below */ }
+    if (!origin || !url || url.username || url.password || url.origin !== origin)
+        bad('VALIDATION_ERROR');
+}
 function checkDestination(dest, file, dir) {
     if (!approvedDirs(file, dir).includes(dirname(dest)))
         bad('DESTINATION_DENIED');
@@ -489,6 +533,9 @@ export async function createVault(input, value) {
         bad('VALIDATION_ERROR');
     if ((fixed.mode === 'receive') !== (value !== undefined) || (value !== undefined && !sized(value)))
         bad('VALIDATION_ERROR');
+    // Before custody: a refused link leaves no folder, folder id, key or record.
+    if (fixed.mode === 'receive')
+        checkReceiveUrl(value, fixed.provider);
     return operate(input.board, fixed.key, true, (dir, path, old, id) => {
         const meta = { ...fixed, board: id };
         if (old)
@@ -554,17 +601,21 @@ export async function deliverVault(board, key, filer, into, afterClaim) {
         try {
             afterClaim?.();
             const value = unseal(secret, r.meta, r.sealed);
-            const fd = openSync(dest, 'wx', 0o600);
             try {
-                const st = fstatSync(fd);
-                made = { dev: st.dev, ino: st.ino };
-                writeFileSync(fd, value);
-                fsyncSync(fd);
+                const fd = openSync(dest, 'wx', 0o600);
+                try {
+                    const st = fstatSync(fd);
+                    made = { dev: st.dev, ino: st.ino };
+                    writeFileSync(fd, value);
+                    fsyncSync(fd);
+                }
+                finally {
+                    closeSync(fd);
+                }
             }
             finally {
-                closeSync(fd);
                 value.fill(0);
-            }
+            } // also when openSync or closeSync throws
             syncDir(dirname(dest));
             const done = { schema: 1, meta: r.meta, status: 'delivered', at: Date.now() };
             publish(path, JSON.stringify(done));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sign-off-axi",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "One review board for evidence, quick yes/no decisions and retro changes.",
   "type": "module",
   "bin": { "sign-off-axi": "dist/cli.js" },