agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/oss-env.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+// The environment every OSS script inherits from this CLI.
+//
+// One place, because the thing it says is a property of "this process runs
+// agmsg as a step of something bigger", not of any particular command. Setting
+// it at each spawn site would mean three copies of one decision, and the one
+// that got missed would be the one printing the wrong route to an operator.
+//
+// `AGMSG_OPERATOR_GUIDANCE=caller` tells the OSS scripts that whoever invoked
+// them owns the "what to do next" lines. It does not silence errors, warnings,
+// progress or prompts, and it does not silence facts — only the closing
+// guidance, which for a plain install names routes this product does not have:
+// no server-side recovery (there is one here), `key.sh show --reveal-secret`
+// (people using this never meet key.sh), and carrying a snapshot out of band
+// (there is a ceremony here that exists so nobody has to).
+//
+// Taking that on is an obligation, not a mute button: OSS no longer says those
+// things, so this side has to.
+export const OSS_GUIDANCE_ENV = 'AGMSG_OPERATOR_GUIDANCE';
+export function ossChildEnv(env = process.env) {
+    return { ...env, [OSS_GUIDANCE_ENV]: 'caller' };
+}
+/**
+ * Start an OSS script. The only way this CLI does.
+ *
+ * A wrapper rather than a rule to remember, because "every spawn site must
+ * also pass the environment" is the kind of rule that holds until someone adds
+ * a fourth site. There is nowhere here to forget it: the environment is not a
+ * parameter, and a caller that wanted to skip it would have to stop using this
+ * function, which is visible in a way a missing option is not.
+ *
+ * stdio stays the caller's choice — `connect` and `pull` inherit it so the
+ * operator sees progress and can answer prompts; the wrappers in oss.ts pipe
+ * it because they parse what comes back.
+ */
+/**
+ * Start an OSS script whose output the operator watches, and may answer.
+ *
+ * Two functions rather than one with a mode, because the pipe variant's
+ * streams are non-null and the inherited one's are not — a single signature
+ * loses that and hands every caller a null check it does not need.
+ */
+export function spawnOssInherit(command, args) {
+    return spawn(command, [...args], { stdio: 'inherit', env: ossChildEnv() });
+}
+/** Start an OSS script whose output this CLI reads. */
+export function spawnOssPiped(command, args) {
+    return spawn(command, [...args], { stdio: ['pipe', 'pipe', 'pipe'], env: ossChildEnv() });
+}

package/dist/src/oss.js

@@ -0,0 +1,289 @@
+import { createHash } from 'node:crypto';
+import { closeSync, constants, openSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnOssPiped } from './oss-env.js';
+// Thin wrappers over the OSS tooling. The proprietary courier never touches key
+// material: sealing/opening the bundle and the handoff/unlock steps all run
+// through `age` and the OSS `key.sh` / `remote.sh` on the operator's machine.
+// This module only shells out to them.
+// Run a command, piping `input` to stdin and collecting stdout as a Buffer.
+// Rejects with the exit code and captured stderr (never the input) on failure.
+function run(cmd, args, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawnOssPiped(cmd, args);
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (d) => out.push(d));
+        child.stderr.on('data', (d) => err.push(d));
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve(Buffer.concat(out));
+            else
+                reject(new Error(`${cmd} exited ${code}: ${Buffer.concat(err).toString().trim()}`));
+        });
+        if (input !== undefined)
+            child.stdin.end(input);
+        else
+            child.stdin.end();
+    });
+}
+/** A finished run, whatever its exit code. For callers where non-zero is an ANSWER. */
+function runAllowingFailure(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawnOssPiped(cmd, args);
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (d) => out.push(d));
+        child.stderr.on('data', (d) => err.push(d));
+        child.on('error', reject);
+        child.on('close', (code) => resolve({
+            code: code ?? -1,
+            stdout: Buffer.concat(out).toString(),
+            stderr: Buffer.concat(err).toString().trim(),
+        }));
+        child.stdin.end();
+    });
+}
+/**
+ * Whether this machine has a team by this name — the question `unlock` asks.
+ *
+ * NOT `remoteBinding`, and the difference was measured rather than assumed.
+ * `remoteBinding` additionally requires the binding to be ACTIVE, and against
+ * the real scripts:
+ *
+ *   team              status <team> --json     unlock <team>
+ *   connected         exit 0, state active     past the team check
+ *   DISCONNECTED      exit 0, state disconnected   past the team check
+ *   never existed     exit 1                   "agmsg: team not found"
+ *
+ * So a disconnected team is one `unlock` accepts and `remoteBinding` refuses.
+ * A caller that used the stricter check to decide whether a name is known would
+ * turn a working command into a refusal — which is the shape of defect this arc
+ * has already paid for twice. The exit code is the answer; the state is not.
+ *
+ * A non-zero exit is reported WITH what the store said, so a broken script does
+ * not get presented to the operator as a mistyped name.
+ */
+export async function localTeamLookup(scriptsDir, team) {
+    const r = await runAllowingFailure('bash', [
+        join(scriptsDir, 'remote.sh'),
+        'status',
+        team,
+        '--json',
+    ]);
+    return r.code === 0 ? { known: true, said: '' } : { known: false, said: r.stderr };
+}
+// Generate a device age identity at `identityPath`; returns its public recipient.
+export async function generateDeviceIdentity(identityPath) {
+    await run('age-keygen', ['-o', identityPath]);
+    const pub = (await run('age-keygen', ['-y', identityPath])).toString().trim();
+    return pub;
+}
+// The public recipient of an existing device identity file.
+export async function publicKeyOf(identityPath) {
+    return (await run('age-keygen', ['-y', identityPath])).toString().trim();
+}
+// Seal plaintext to a device's public recipient (binary age ciphertext).
+export function sealToRecipient(recipient, plaintext) {
+    return run('age', ['-r', recipient, '-e'], plaintext);
+}
+// Open a sealed blob with the local device identity.
+export function decryptWithIdentity(identityPath, ciphertext) {
+    return run('age', ['-d', '-i', identityPath], ciphertext);
+}
+// OSS `key.sh handoff <team> --out <file>` — export the one secret handoff bundle
+// (confirmed snapshot chain + every epoch identity) for `team`.
+export async function keyHandoff(scriptsDir, team, outFile) {
+    await run('bash', [join(scriptsDir, 'key.sh'), 'handoff', team, '--out', outFile]);
+}
+// OSS `remote-sync.sh verify-age-handoff` — the digest the joiner's `unlock`
+// will compare the human-carried value against.
+//
+// It is NOT recomputed here. `unlock` compares `snapshot_sha256`, which is
+// SHA-256 over the RFC 8785 canonical JSON of the bundle's latest snapshot — not
+// over the bundle file. A second implementation of that in TypeScript would
+// agree until the day it did not, and the disagreement would surface as two
+// people reading the same digits aloud while the gate refuses them. So the
+// approver asks the same code the joiner will ask.
+//
+// The verification writes the bundle's epoch identities into `outDir`. That is
+// not new exposure: the bundle handed to it already contains those identities
+// and is already on disk beside it — but the directory holds private key
+// material and must be treated exactly like the bundle.
+export async function verifyHandoffDigest(scriptsDir, team, bundleFile, outDir) {
+    const out = await run('bash', [
+        join(scriptsDir, 'remote-sync.sh'),
+        'verify-age-handoff',
+        '--team',
+        team,
+        '--bundle',
+        bundleFile,
+        '--out-dir',
+        outDir,
+    ]);
+    const text = out.toString().trim();
+    const lines = text.split('\n').filter((l) => l.trim() !== '');
+    // The contract is ONE line of JSON on stdout (the shell wrapper writes nothing
+    // there; every human-facing line goes to stderr). Taking the last line would
+    // quietly absorb anything that started appearing before it, which is how an
+    // ABI change becomes a silent behaviour change instead of a loud failure.
+    if (lines.length !== 1) {
+        throw new Error(`verify-age-handoff wrote ${lines.length} lines to stdout; the contract is exactly one JSON result`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(lines[0]);
+    }
+    catch {
+        throw new Error('verify-age-handoff did not produce a JSON result');
+    }
+    const result = parsed;
+    // Shape-checked rather than trusted: a digest read out of an unexpected
+    // response would be confirmed by a human and then never match.
+    if (result.type !== 'age_handoff_verified' || typeof result.snapshot_sha256 !== 'string') {
+        throw new Error('verify-age-handoff returned an unrecognised result');
+    }
+    if (!/^[a-f0-9]{64}$/.test(result.snapshot_sha256)) {
+        throw new Error('verify-age-handoff returned a digest that is not a SHA-256 hex string');
+    }
+    return result.snapshot_sha256;
+}
+// The full binding, for callers that have to record WHICH remote a team's
+// material came from. `remoteTeamId` stays for callers that only address the
+// team, so neither has to know about the other's fields.
+export async function remoteBinding(scriptsDir, team) {
+    const out = await run('bash', [join(scriptsDir, 'remote.sh'), 'status', team, '--json']);
+    const text = out.toString().trim();
+    if (!text)
+        throw new Error(`team '${team}' has never been connected to a remote`);
+    const status = JSON.parse(text);
+    if (status.state !== 'active') {
+        throw new Error(`team '${team}' is not connected (state: ${String(status.state)})`);
+    }
+    if (typeof status.remote_team_id !== 'string' || !status.remote_team_id) {
+        throw new Error(`team '${team}' has no remote team id recorded`);
+    }
+    if (typeof status.server_instance_id !== 'string' || !status.server_instance_id) {
+        // Refuse rather than file the entry under an empty instance: the binding is
+        // what tells a restore that this bundle belongs to the remote this machine
+        // is talking to.
+        throw new Error(`team '${team}' has no server instance id recorded`);
+    }
+    return { teamId: status.remote_team_id, serverInstanceId: status.server_instance_id };
+}
+export async function connectedTeams(scriptsDir) {
+    const out = await run('bash', [join(scriptsDir, 'remote.sh'), 'status', '--json']);
+    const teams = [];
+    for (const line of out.toString().split('\n')) {
+        const text = line.trim();
+        if (text === '')
+            continue;
+        let status;
+        try {
+            status = JSON.parse(text);
+        }
+        catch {
+            // One unreadable line must not decide the whole answer either way:
+            // skipping it silently would file a backup that quietly omits a team, so
+            // it is refused instead. A status output this client cannot parse is not
+            // a shorter list of teams.
+            // Worded so it does not read as a command to paste: it quotes DATA, and
+            // the checker is right that an interpolation inside something
+            // command-shaped is worth refusing on sight.
+            throw new Error(`the team status this machine printed contains a line this version cannot read: ${JSON.stringify(text.slice(0, 80))}`);
+        }
+        // A state this version does not know is not quietly dropped and not quietly
+        // treated as filable: an unknown word here is the same shape as a line that
+        // did not parse, and it gets the same refusal.
+        if (status.state !== 'active' && status.state !== 'disconnected') {
+            throw new Error(`the team status this machine printed describes a state this version cannot read: ${JSON.stringify(String(status.state).slice(0, 40))}`);
+        }
+        if (typeof status.local_team !== 'string' ||
+            typeof status.remote_team_id !== 'string' ||
+            !status.remote_team_id ||
+            typeof status.server_instance_id !== 'string' ||
+            !status.server_instance_id) {
+            throw new Error(`remote.sh status --json described a team without the ids a vault entry needs`);
+        }
+        teams.push({
+            team: status.local_team,
+            teamId: status.remote_team_id,
+            serverInstanceId: status.server_instance_id,
+            state: status.state,
+        });
+    }
+    return teams;
+}
+export async function remoteTeamId(scriptsDir, team) {
+    const out = await run('bash', [join(scriptsDir, 'remote.sh'), 'status', team, '--json']);
+    const text = out.toString().trim();
+    if (!text)
+        throw new Error(`team '${team}' has never been connected to a remote`);
+    const status = JSON.parse(text);
+    if (status.state !== 'active') {
+        // A disconnected binding's remote_team_id is a leftover. Writing a vault
+        // version under it would file the backup against a team this machine is no
+        // longer bound to.
+        throw new Error(`team '${team}' is not connected (state: ${String(status.state)})`);
+    }
+    if (typeof status.remote_team_id !== 'string' || !status.remote_team_id) {
+        throw new Error(`team '${team}' has no remote team id recorded`);
+    }
+    return status.remote_team_id;
+}
+// OSS `remote.sh unlock <team> --authenticated-bundle-stdin`.
+//
+// The disaster-restore ingress. We pass the exact Buffer the AEAD produced,
+// straight down the pipe — no temporary file, no path. A path would reopen the
+// window this mode exists to close: what we authenticated and what gets imported
+// must be the same bytes, not the same filename. It also means the decrypted
+// bundle never lands on disk in the clear.
+//
+// remote.sh performs no authentication here; it trusts that the caller did. That
+// obligation is ours: only call this with a buffer that came out of
+// unwrapWithVdk, whose AAD bound the vault, team, and profile we expected. The
+// courier path must keep using unlockBundle with an out-of-band digest, because
+// age's recipient encryption does not authenticate the sender.
+export async function unlockAuthenticatedBundle(scriptsDir, team, bundle) {
+    await run('bash', [join(scriptsDir, 'remote.sh'), 'unlock', team, '--authenticated-bundle-stdin'], bundle);
+}
+// OSS `remote.sh unlock <team> --bundle <file> [--confirm-digest <digest>]`.
+export async function unlockBundle(scriptsDir, team, bundleFile, confirmDigest) {
+    const args = [join(scriptsDir, 'remote.sh'), 'unlock', team, '--bundle', bundleFile];
+    if (confirmDigest)
+        args.push('--confirm-digest', confirmDigest);
+    await run('bash', args);
+}
+// The canonical age snapshot, exported locally, and its digest (§3.2, §3.2.1).
+//
+// This is what A commits to BEFORE either side opens. It is the public
+// key-state description — no identity material — so what it leaves behind if
+// this process is killed is a snapshot in a file the user owns, not a secret.
+// The bundle that does carry identities is generated after the human answers.
+//
+// The digest is taken from the FILE, not from the script's stderr line. The
+// spec defines it as the SHA-256 of the canonical JSON, and the file is that
+// JSON; the stderr line is a human-facing surface whose wording can change
+// without anything failing. Reading the definition rather than the message
+// also means A and B compute the same value from the same rule.
+export async function exportSnapshotDigest(scriptsDir, team, outPath) {
+    await run('bash', [
+        join(scriptsDir, 'remote-sync.sh'),
+        'export-age-snapshot',
+        '--team',
+        team,
+        '--out',
+        outPath,
+    ]);
+    // O_NOFOLLOW: the path is one we just asked another program to create, and
+    // reading a snapshot through a symlink someone else planted would hash a
+    // file this machine never wrote.
+    const fd = openSync(outPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        return createHash('sha256').update(readFileSync(fd)).digest('hex');
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/src/paths.js

@@ -0,0 +1,8 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// Where this machine keeps its device identity (the age private key that blobs
+// are sealed to). It never leaves the machine; 0600, outside any repo.
+export function deviceIdentityPath(env = process.env) {
+    const base = env.AGMSG_CLOUD_HOME ?? join(homedir(), '.agmsg-cloud');
+    return join(base, 'device.key');
+}

package/dist/src/pending.js

@@ -0,0 +1,330 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { deriveApproverCommitment, isCanonicalAgeRecipient } from '@agmsg-cloud/sas-core';
+import { readIfPresent, uniqueTempPath, withFileLock } from './filelock.js';
+// Same scope as the §4.1 ledger: the canonical server origin. A record from one
+// deployment must never satisfy another, so the origin is part of the key rather
+// than a field a reader could forget to check.
+function originTag(serverOrigin) {
+    return createHash('sha256').update(serverOrigin).digest('hex').slice(0, 16);
+}
+export function pendingDir(env = process.env) {
+    const base = env['AGMSG_CLOUD_HOME'] ?? join(homedir(), '.agmsg-cloud');
+    return join(base, 'pending');
+}
+function recordPath(dir, role, origin, key) {
+    return join(dir, `${role}-${originTag(origin)}-${key}.json`);
+}
+// 0700 on the directory as well as 0600 on the file: a world-readable directory
+// leaks which ceremonies are in flight and when, even if the nonces themselves
+// stay unreadable.
+function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+}
+// Written to a temporary name and renamed, so a reader never sees a half-written
+// record, and created 0600 from the start rather than chmod'ed afterwards — a
+// window where the nonce is world-readable is still a window.
+function writeRecord(path, record) {
+    // Per-process temp name: a shared one is renamed over by every writer, so two
+    // processes reserving at once lose one of the two records — and a lost record
+    // is a nonce nobody can open with.
+    const tmp = uniqueTempPath(path);
+    writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+}
+const HEX64 = /^[0-9a-f]{64}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function validTimestamp(value) {
+    if (typeof value !== 'string')
+        return false;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) && new Date(ms).toISOString() === value;
+}
+/**
+ * Read a record, checking every field rather than only that the file is JSON.
+ *
+ * An earlier version accepted anything that parsed, so `{}` came back as an
+ * existing record: minting was suppressed and undefined values went on to be
+ * used as a nonce. "Corrupt" has to mean "does not satisfy the shape", or the
+ * refusal protects only against a truncated write.
+ *
+ * The expected role, origin and key are passed in and compared against the
+ * contents, so a record cannot be moved or renamed into another ceremony's slot.
+ */
+function readRecord(path, expected) {
+    const raw = readIfPresent(path);
+    if (raw === null)
+        return null;
+    const fail = () => {
+        throw new Error(`pending record is unreadable: ${path}`);
+    };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return fail();
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return fail();
+    const r = parsed;
+    if (r['role'] !== expected.role)
+        return fail();
+    if (r['serverOrigin'] !== expected.serverOrigin)
+        return fail();
+    if (typeof r['commitmentHex'] !== 'string' || !HEX64.test(r['commitmentHex']))
+        return fail();
+    if (typeof r['nonceHex'] !== 'string' || !HEX64.test(r['nonceHex']))
+        return fail();
+    if (!validTimestamp(r['createdAt']))
+        return fail();
+    if (expected.role === 'requester') {
+        // The commitment IS the file key for a requester, so a mismatch means this
+        // record belongs to a different ceremony.
+        if (r['commitmentHex'] !== expected.key)
+            return fail();
+        if (typeof r['devicePubkey'] !== 'string' || !isCanonicalAgeRecipient(r['devicePubkey'])) {
+            return fail();
+        }
+        if (r['requestId'] !== undefined && (typeof r['requestId'] !== 'string' || !UUID.test(r['requestId']))) {
+            return fail();
+        }
+    }
+    else {
+        if (typeof r['requestId'] !== 'string' || r['requestId'] !== expected.key)
+            return fail();
+        if (r['devicePubkey'] !== undefined)
+            return fail();
+        // Required, and required STRICTLY. A record written before the digest was
+        // part of the commitment cannot be repaired by attaching today's snapshot:
+        // the stored commitment was computed without one, so the pair would not
+        // reproduce it, and the server would refuse the opening after the human
+        // had already compared digits. Fail here and let a fresh attempt start
+        // (raised in review).
+        if (typeof r['handoffDigestHex'] !== 'string' || !HEX64.test(r['handoffDigestHex'])) {
+            return fail();
+        }
+    }
+    // A requester never has one. Allowing it would let a file written for one
+    // role be read as the other's.
+    if (expected.role === 'requester' && r['handoffDigestHex'] !== undefined)
+        return fail();
+    return r;
+}
+export function fileMode(path) {
+    return statSync(path).mode & 0o777;
+}
+/**
+ * Reserve the requester's opening nonce for a commitment.
+ *
+ * Called BEFORE the commitment is posted. If a record already exists for this
+ * commitment, it is returned unchanged — the same commitment must always open to
+ * the same nonce.
+ */
+export function reserveRequesterNonce(input, env = process.env) {
+    const dir = pendingDir(env);
+    ensureDir(dir);
+    const path = recordPath(dir, 'requester', input.serverOrigin, input.commitmentHex);
+    const expected = { role: 'requester', serverOrigin: input.serverOrigin, key: input.commitmentHex };
+    // Read and write under one lock. Split apart, two processes both see nothing
+    // and both write — and the loser's nonce is the one the server is holding a
+    // commitment for.
+    return withFileLock(path, () => {
+        const existing = readRecord(path, expected);
+        if (existing)
+            return existing;
+        const record = {
+            role: 'requester',
+            commitmentHex: input.commitmentHex,
+            nonceHex: input.nonceHex,
+            devicePubkey: input.devicePubkey,
+            serverOrigin: input.serverOrigin,
+            createdAt: new Date().toISOString(),
+        };
+        writeRecord(path, record);
+        return record;
+    });
+}
+/**
+ * Reserve the approver's nonce for one enrollment request.
+ *
+ * The mint callback runs ONLY when no record exists. After a crash this returns
+ * the nonce already committed to, because replacing a fixed commitment is
+ * indistinguishable from a substitution attack.
+ */
+/**
+ * Reserve the approver's (nonce, digest, commitment) — as one thing.
+ *
+ * `handoffDigestHex` is exported OUTSIDE this lock, because exporting a
+ * snapshot spawns a child process and the lock is synchronous. That is safe
+ * for one reason, and it is worth stating: a caller that loses the race
+ * DISCARDS its own digest. It returns the stored record whole, so the value
+ * that ends up committed to, opened with, and compared by a human is the one
+ * on disk — never a second snapshot taken concurrently (raised in review).
+ *
+ * The trio is written in a single record, and read back through the validator
+ * that requires all three, so a partially written or pre-digest record fails
+ * rather than being completed from the current state.
+ */
+/**
+ * Does this approver record reproduce its own commitment from its own nonce and
+ * digest?
+ *
+ * The three values are only meaningful together, and a record that fails this
+ * cannot be used for anything: it would post a commitment the server never saw,
+ * or open one it cannot satisfy. Which of the three is wrong is unknowable from
+ * here, so there is nothing to repair.
+ *
+ * Shared, because two callers now ask it for different reasons and they must
+ * not drift: reserving refuses to continue from a record like this, and the
+ * budget refuses to treat one as evidence that a run is re-sending a commitment
+ * it has already been charged for (raised in review).
+ */
+export function approverRecordAgreesWithItself(record) {
+    if (record.role !== 'approver')
+        return false;
+    if (typeof record.handoffDigestHex !== 'string')
+        return false;
+    return (deriveApproverCommitment(new Uint8Array(Buffer.from(record.nonceHex, 'hex')), record.handoffDigestHex) === record.commitmentHex);
+}
+export function reserveApproverNonce(input, mint, env = process.env) {
+    if (!HEX64.test(input.handoffDigestHex)) {
+        throw new Error('handoff digest must be 64 lowercase hexadecimal characters');
+    }
+    const dir = pendingDir(env);
+    ensureDir(dir);
+    const path = recordPath(dir, 'approver', input.serverOrigin, input.requestId);
+    const expected = { role: 'approver', serverOrigin: input.serverOrigin, key: input.requestId };
+    // The mint callback runs INSIDE the lock, so two processes cannot each mint a
+    // nonce for one request. Two different nonces for one fixed commitment is,
+    // from the requester's side, indistinguishable from a substitution.
+    return withFileLock(path, () => {
+        const existing = readRecord(path, expected);
+        if (existing) {
+            // The three values are only meaningful together. A record whose stored
+            // commitment does not reproduce from its own nonce and digest is one
+            // this cannot use — it would post a commitment the server never saw, or
+            // open one it cannot satisfy — and there is nothing to repair, because
+            // which of the three is wrong is unknowable from here.
+            if (!approverRecordAgreesWithItself(existing)) {
+                throw new Error(`pending approver record does not agree with itself: ${path}\n\n` +
+                    'Remove it and start a fresh approval; its commitment cannot be reproduced from the nonce and digest stored beside it.');
+            }
+            return existing;
+        }
+        const minted = mint(input.handoffDigestHex);
+        const record = {
+            role: 'approver',
+            commitmentHex: minted.commitmentHex,
+            nonceHex: minted.nonceHex,
+            handoffDigestHex: input.handoffDigestHex,
+            requestId: input.requestId,
+            serverOrigin: input.serverOrigin,
+            createdAt: new Date().toISOString(),
+        };
+        writeRecord(path, record);
+        return record;
+    });
+}
+// Record the id the server assigned, once the commitment is accepted. Only ever
+// adds the id; the nonce and commitment are never touched.
+export function attachRequestId(input, env = process.env) {
+    const path = recordPath(pendingDir(env), 'requester', input.serverOrigin, input.commitmentHex);
+    const expected = { role: 'requester', serverOrigin: input.serverOrigin, key: input.commitmentHex };
+    withFileLock(path, () => {
+        const existing = readRecord(path, expected);
+        if (!existing)
+            return;
+        writeRecord(path, { ...existing, requestId: input.requestId });
+    });
+}
+export function loadRequesterRecord(input, env = process.env) {
+    return readRecord(recordPath(pendingDir(env), 'requester', input.serverOrigin, input.commitmentHex), { role: 'requester', serverOrigin: input.serverOrigin, key: input.commitmentHex });
+}
+export function loadApproverRecord(input, env = process.env) {
+    return readRecord(recordPath(pendingDir(env), 'approver', input.serverOrigin, input.requestId), {
+        role: 'approver',
+        serverOrigin: input.serverOrigin,
+        key: input.requestId,
+    });
+}
+/**
+ * The requester's unfinished ceremonies against one server, oldest first.
+ *
+ * Resuming matters for more than convenience. §4.1 charges an attempt when the
+ * commitment is posted, so starting over instead of finishing an existing
+ * request spends a second attempt for one enrollment — five crashes would
+ * exhaust the day's budget without a single completed comparison.
+ */
+export function listResumableRequesterRecords(serverOrigin, env = process.env) {
+    const dir = pendingDir(env);
+    const prefix = `requester-${originTag(serverOrigin)}-`;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        if (!name.startsWith(prefix) || !name.endsWith('.json'))
+            continue;
+        const key = name.slice(prefix.length, -'.json'.length);
+        const record = readRecord(join(dir, name), {
+            role: 'requester',
+            serverOrigin,
+            key,
+        });
+        // Records WITHOUT an id are returned too. One of them may still have landed
+        // on the server — the response can be lost after the row exists — and
+        // dropping it here left the caller starting over while the ledger's open
+        // attempt refused every retry. Deciding which case it is needs the server,
+        // so that decision belongs to the caller.
+        if (record)
+            out.push(record);
+    }
+    return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+// Called once a ceremony reaches a terminal state. Not called on a mere failure
+// to reach the server: a record whose commitment may have landed must survive,
+// or the next run would mint a replacement for a commitment the server holds.
+export function clearRecord(input, env = process.env) {
+    rmSync(recordPath(pendingDir(env), input.role, input.serverOrigin, input.key), { force: true });
+}
+/**
+ * Drop every pending record for one server, and say how many.
+ *
+ * For sign-out: a ceremony half-started against a service this machine is
+ * leaving has nothing left to complete, and its nonce is the opening of a
+ * commitment nobody will ever ask about again.
+ *
+ * Selected by the origin TAG that is already part of every filename, so this
+ * cannot drift from the naming above the way a second list of origins would.
+ * Records for other servers are untouched: signing out of one deployment is
+ * not signing out of the others.
+ */
+export function clearRecordsForOrigin(serverOrigin, env = process.env) {
+    const dir = pendingDir(env);
+    if (!existsSync(dir))
+        return 0;
+    const tag = originTag(serverOrigin);
+    let removed = 0;
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith('.json'))
+            continue;
+        // `<role>-<tag>-<key>.json`. Matching the tag as its own dash-delimited
+        // field, not as a substring: a key that happened to contain the tag would
+        // otherwise take another server's record with it.
+        const parts = name.slice(0, -'.json'.length).split('-');
+        if (parts[1] !== tag)
+            continue;
+        rmSync(join(dir, name), { force: true });
+        removed += 1;
+    }
+    return removed;
+}