@tinycloud/courier 0.5.1-beta.2 → 0.5.1-beta.4

package/dist/file-lock.js

@@ -0,0 +1,331 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { CourierError } from './errors.js';
+/** Makes a link or rename in `dir` durable: the directory entry is fsynced, not only the file contents. */
+export function fsyncDir(dir) {
+    const fd = fs.openSync(dir, 'r');
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Writes the full body to a same-directory temp file with the given mode, fsynced, and returns its path. */
+export function writeTemp(dir, name, body, mode) {
+    const temp = path.join(dir, `.${name}.${randomBytes(6).toString('hex')}.tmp`);
+    const fd = fs.openSync(temp, 'wx', mode);
+    try {
+        fs.writeFileSync(fd, body);
+        fs.fchmodSync(fd, mode);
+        fs.fsyncSync(fd);
+    }
+    catch (error) {
+        fs.closeSync(fd);
+        fs.rmSync(temp, { force: true });
+        throw error;
+    }
+    fs.closeSync(fd);
+    return temp;
+}
+/**
+ * Creates `dir/name` only if nothing is there yet (hard link of the temp file, which fails if the target exists, symlinks
+ * included). Returns false when the target already exists, so a queued message is never overwritten.
+ */
+export function writeNew(dir, name, body, mode) {
+    const temp = writeTemp(dir, name, body, mode);
+    try {
+        fs.linkSync(temp, path.join(dir, name));
+        fsyncDir(dir);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        fs.rmSync(temp, { force: true });
+    }
+}
+const MAX_FIELD = 128;
+const OPTIONAL_FIELDS = ['host', 'pidns', 'machine', 'boot'];
+/** Parses `{"pid":N,"nonce":"..."}` (plus the optional identity fields). A legacy `pid\n` lock parses with its own text as the nonce. */
+function parseRecord(text) {
+    if (/^\d+\n?$/.test(text)) {
+        const pid = Number(text);
+        return Number.isInteger(pid) && pid > 0 ? { pid, nonce: text } : undefined;
+    }
+    try {
+        const value = JSON.parse(text);
+        if (typeof value !== 'object' || value === null)
+            return undefined;
+        const fields = value;
+        const { pid, nonce } = fields;
+        if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0)
+            return undefined;
+        if (typeof nonce !== 'string' || nonce.length === 0 || nonce.length > MAX_FIELD)
+            return undefined;
+        const record = { pid, nonce };
+        for (const key of OPTIONAL_FIELDS) {
+            const field = fields[key];
+            if (field === undefined)
+                continue;
+            if (typeof field !== 'string' || field.length > MAX_FIELD)
+                return undefined; // an oversized or mistyped field is a corrupt record
+            record[key] = field;
+        }
+        return record;
+    }
+    catch {
+        return undefined;
+    }
+}
+function recordBody(record) {
+    return `${JSON.stringify(record)}\n`;
+}
+/** Reads the lock. An unparseable lock is never broken: it refuses, as a live one would. */
+function readLock(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { kind: 'missing' };
+        throw error;
+    }
+    const record = parseRecord(text);
+    return record ? { kind: 'held', record } : { kind: 'corrupt' };
+}
+function pidNamespace() {
+    try {
+        return fs.readlinkSync('/proc/self/ns/pid');
+    }
+    catch {
+        return undefined;
+    }
+}
+const realIo = {
+    platform: process.platform,
+    ...(process.env.SystemRoot === undefined ? {} : { systemRoot: process.env.SystemRoot }),
+    readFile: (file) => { try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    } },
+    exec: (command, args) => { try {
+        return execFileSync(command, args, { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+    }
+    catch {
+        return undefined;
+    } },
+};
+const firstLine = (text) => text?.trim().split(/\r?\n/)[0]?.trim() || undefined;
+/**
+ * The machine and the boot this process runs on. `boot` is a true per-boot identifier or absent, and is prefixed with the platform that
+ * produced it so two kinds are never compared. Linux: /etc/machine-id and the kernel boot id. macOS: IOPlatformUUID (`/usr/sbin/ioreg`) and
+ * kern.bootsessionuuid (`/usr/sbin/sysctl`). Windows: MachineGuid (`%SystemRoot%\\System32\\reg.exe`); Windows has no per-boot identifier
+ * verified to be stable, so it has none. Wall-clock values (`kern.boottime`, LastBootUpTime, uptime) are never used: they jitter and shift
+ * with the clock, and a lock must not be called dead on a clock difference. An identity that cannot be read stays absent: records are then not judged.
+ */
+export function machineIdentity(io = realIo) {
+    let machine;
+    let boot;
+    if (io.platform === 'linux') {
+        machine = firstLine(io.readFile('/etc/machine-id')) ?? firstLine(io.readFile('/var/lib/dbus/machine-id'));
+        const id = firstLine(io.readFile('/proc/sys/kernel/random/boot_id'));
+        if (id)
+            boot = `linux:${id}`;
+    }
+    else if (io.platform === 'darwin') {
+        machine = /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(io.exec('/usr/sbin/ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice']) ?? '')?.[1];
+        const id = firstLine(io.exec('/usr/sbin/sysctl', ['-n', 'kern.bootsessionuuid']));
+        if (id)
+            boot = `macos:${id}`;
+    }
+    else if (io.platform === 'win32') {
+        const reg = `${io.systemRoot ?? 'C:\\Windows'}\\System32\\reg.exe`;
+        machine = /MachineGuid\s+REG_SZ\s+(\S+)/.exec(io.exec(reg, ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid']) ?? '')?.[1];
+    }
+    return { ...(machine === undefined ? {} : { machine }), ...(boot === undefined ? {} : { boot }) };
+}
+let cachedIdentity;
+const currentIdentity = () => (cachedIdentity ??= machineIdentity());
+/** What this process records about itself: enough to tell another machine's, boot's or pid namespace's records apart. */
+function identity(here) {
+    const out = { host: os.hostname(), ...here };
+    const ns = pidNamespace();
+    if (ns !== undefined)
+        out.pidns = ns;
+    return out;
+}
+/**
+ * Whether the process that wrote `record` still runs. A holder is `dead` in exactly two cases, and `unknown` (the lock is kept) in every other:
+ *   (a) a different true boot id of the same kind on the same machine and host: no process survives a reboot; or
+ *   (b) its pid is absent (`ESRCH`).
+ * Before either, the record must name this machine (machine-id) and this host (another machine, a cloned machine-id, a renamed host, an old
+ * pid-only record, or an identity this process cannot read is never judged), and on Linux the same pid namespace as this process: a reader in
+ * another pid namespace sees a live holder's pid as absent. A pid that exists is never `dead`, whatever its start time, state or owner: a
+ * crashed holder whose pid was reused needs the manual recovery line.
+ */
+export function recordLiveness(record, here = currentIdentity()) {
+    if (record.machine === undefined || here.machine === undefined || record.machine !== here.machine)
+        return 'unknown';
+    if (record.host === undefined || record.host !== os.hostname())
+        return 'unknown';
+    if (record.boot !== undefined && here.boot !== undefined) {
+        const [kindA, kindB] = [record.boot.split(':', 1)[0], here.boot.split(':', 1)[0]];
+        if ((kindA === 'linux' || kindA === 'macos') && kindA === kindB && record.boot !== here.boot)
+            return 'dead';
+    }
+    const ns = pidNamespace();
+    if (process.platform === 'linux' ? record.pidns === undefined || ns === undefined || record.pidns !== ns : record.pidns !== undefined && record.pidns !== ns)
+        return 'unknown';
+    try {
+        process.kill(record.pid, 0);
+    }
+    catch (error) {
+        return error.code === 'ESRCH' ? 'dead' : 'unknown';
+    }
+    return 'unknown';
+}
+/** Guard slots per dead lock. The bound stops a corrupt directory from looping forever. */
+const MAX_BREAK_GUARDS = 8;
+/** The one line a refused lock prints: what holds it, and the only safe way out. The lock itself is never removed on doubt. */
+export function lockRefusal({ file, reason, pid, host, record }, platform = process.platform) {
+    // Text from a lock record is data, not words: JSON-quoted so a hostile host name cannot add lines or terminal escapes.
+    const holder = pid === undefined ? 'a holder that cannot be read' : `pid ${pid}${host === undefined ? '' : ` on host ${JSON.stringify(host)}`}`;
+    const why = reason === 'alive' ? `is held by a running Courier command (${holder})`
+        : reason === 'corrupt' ? 'has a record Courier cannot read'
+            : reason === 'unknown' ? `is held by ${holder}, and Courier cannot tell whether that process is still running`
+                : `is held by ${holder}, and another Courier command is already working on clearing it`;
+    const remove = platform === 'win32'
+        ? `Remove-Item -LiteralPath '${file.replace(/['\u2018-\u201B]/g, (quote) => quote + quote)}' -Force` // PowerShell: single quotes are literal; ' and its typographic forms U+2018 to U+201B each end the string unless doubled
+        : `rm -f -- '${file.replace(/'/g, `'\\''`)}'`;
+    return `${file} ${why}${record === undefined ? '' : ` (record ${record})`}; the lock was left in place. Try again; only after confirming no Courier command is running anywhere that uses this lock, clear it with: ${remove}`;
+}
+/**
+ * Takes the lock `file`. A live or unknowable holder always refuses, however old its file is; only a holder that is established dead
+ * is broken. The lock is created whole (never empty) and carries a nonce, so a release or a break removes only the lock it actually observed.
+ */
+export function acquireLock(file, opts = {}) {
+    const dir = path.dirname(file);
+    const name = path.basename(file);
+    const pid = opts.pid ?? process.pid;
+    const here = (opts.identity ?? currentIdentity)();
+    const self = { pid, nonce: randomBytes(6).toString('hex'), ...identity(here) };
+    const state = (record) => (opts.alive ? (opts.alive(record.pid) ? 'alive' : 'dead') : recordLiveness(record, here));
+    const refuse = (info) => {
+        throw new CourierError('locked', (opts.refusal ?? lockRefusal)({ file, ...info }));
+    };
+    for (let attempt = 0; attempt < 3; attempt++) {
+        let seen = readLock(file);
+        if (seen.kind === 'missing') {
+            // Only a missing lock costs a temp file and two fsyncs: a held one is judged from a read, so a waiter polling every 10 ms writes nothing.
+            let created;
+            try {
+                created = writeNew(dir, name, recordBody(self), 0o600);
+            }
+            catch (error) {
+                const now = readLock(file); // linked, then a later step (the directory fsync) failed: do not leave a live-looking lock nobody holds
+                if (now.kind === 'held' && now.record.nonce === self.nonce)
+                    fs.rmSync(file, { force: true });
+                throw error;
+            }
+            if (created) {
+                return () => {
+                    const current = readLock(file);
+                    if (current.kind === 'held' && current.record.nonce === self.nonce)
+                        fs.rmSync(file, { force: true });
+                };
+            }
+            seen = readLock(file);
+            if (seen.kind === 'missing')
+                continue;
+        }
+        if (seen.kind === 'corrupt')
+            return refuse({ reason: 'corrupt' });
+        if (seen.kind !== 'held')
+            continue;
+        const holder = { pid: seen.record.pid, record: JSON.stringify({ pid: seen.record.pid, nonce: seen.record.nonce, ...(seen.record.host === undefined ? {} : { host: seen.record.host }) }), ...(seen.record.host === undefined ? {} : { host: seen.record.host }) };
+        const live = state(seen.record);
+        if (live !== 'dead')
+            return refuse({ reason: live, ...holder });
+        opts.afterObserve?.();
+        if (!breakDead(file, seen.record, self, state))
+            return refuse({ reason: 'contended', ...holder });
+    }
+    return refuse({ reason: 'contended' });
+}
+/**
+ * Breaks the dead lock `stale`. Breakers serialize on numbered guard files `<lock>.break.<nonce>.<k>`: guard k is
+ * claimed exclusively; a guard whose holder is not dead refuses the break, and one whose holder is dead is passed over.
+ * Under the guard the lock is re-read and unlinked only if it is still exactly `stale`. Returns false when a live
+ * contender holds the break, and true when the caller should retry creating its own lock.
+ */
+function breakDead(file, stale, self, state) {
+    const dir = path.dirname(file);
+    const tag = `${path.basename(file)}.break.${stale.nonce.trim().replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64)}.`;
+    const body = recordBody(self);
+    /** Guards whose breaker was read and judged dead: removed only while they still hold exactly that record, never one claimed meanwhile. */
+    const dead = new Map();
+    const clearDead = () => {
+        for (const [guard, text] of dead) {
+            try {
+                if (fs.readFileSync(guard, 'utf8') === text)
+                    fs.rmSync(guard, { force: true });
+            }
+            catch { /* already gone */ }
+        }
+    };
+    let own;
+    let retries = 0;
+    for (let k = 1; k <= MAX_BREAK_GUARDS && own === undefined; k++) {
+        const candidate = path.join(dir, `${tag}${k}`);
+        if (writeNew(dir, `${tag}${k}`, body, 0o600)) {
+            own = candidate;
+            break;
+        }
+        let text;
+        try {
+            text = fs.readFileSync(candidate, 'utf8');
+        }
+        catch (error) {
+            // The breaker that held this guard finished and removed it between our failed create and this read: take the slot again.
+            if (error.code === 'ENOENT' && retries++ < MAX_BREAK_GUARDS) {
+                k -= 1;
+                continue;
+            }
+            return false;
+        }
+        const holder = parseRecord(text);
+        if (!holder || state(holder) !== 'dead')
+            return false;
+        dead.set(candidate, text);
+    }
+    if (own === undefined) {
+        // Every slot holds a guard whose breaker is dead: clear exactly those, or the break could never run again. The lock itself is still removed only by exact nonce.
+        clearDead();
+        return true;
+    }
+    try {
+        const now = readLock(file);
+        if (now.kind === 'held' && now.record.nonce === stale.nonce)
+            fs.rmSync(file, { force: true });
+        return true;
+    }
+    finally {
+        clearDead();
+        try {
+            if (fs.readFileSync(own, 'utf8') === body)
+                fs.rmSync(own, { force: true });
+        }
+        catch { /* already gone */ }
+    }
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/file-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.js","sourceRoot":"","sources":["../src/file-lock.ts"],"names":[],"mappings":"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"}

package/dist/grant-request.d.ts

@@ -1,60 +1,12 @@
-import { type LinkRecord, type OpenKeyApprovalRequestV1 } from '@tinycloud/share-envelope/links';
 import { type AgentKey, type Profile } from './profile.js';
-export declare const DEFAULT_WAIT_MS = 60000;
-export declare const MAX_WAIT_MS: number;
-/** The durable record of one approval request. The result stays encrypted at rest under `relayPrivateKey`. */
-export interface PendingGrantRequest {
-    version: 1;
-    request: OpenKeyApprovalRequestV1;
-    requestId: string;
-    bodyCid: string;
-    approvalUrl: string;
-    requestExpiresAt: string;
-    record: LinkRecord;
-    apiOrigin: string;
-    linkApiOrigin: string;
-    openkeyOrigin: string;
-    relayPrivateKey: string;
-    /** Sent with the acknowledgement; stable across retries so OpenKey can recognise the same ack. */
-    ackId: string;
-    resultRef?: string;
-    resultExpiresAt?: string;
-    resultEnvelope?: unknown;
-    /** The grant and profile are saved; only the acknowledgement may remain. */
-    committed?: true;
-}
-export type PendingRead = {
-    kind: 'none';
-} | {
-    kind: 'ok';
-    pending: PendingGrantRequest;
-}
-/** The file or its directory has the wrong mode, or the file cannot be read (EACCES, EIO): the record may well be intact. */
- | {
-    kind: 'unreadable';
-    reason: string;
-    fix: string;
-}
-/** The file is readable and is not a saved request. */
- | {
-    kind: 'corrupt';
-    reason: string;
-};
-export declare function readPending(): PendingRead;
-/**
- * Stops (without changing anything) when a saved approval request exists but cannot be read. Call it before a writer changes any
- * other state, so a key, grant or profile is never replaced while the approval it belongs to is unreachable.
- */
-export declare function assertPendingReadable(): void;
+import { type PendingGrantRequest } from './approval-phase.js';
 /**
- * The saved request for READ-ONLY and cleanup callers. A record that cannot be read is reported on stderr and treated as no record, so
- * it never fails a command that already installed a grant or blocks `--rotate-key`. Callers that WRITE the record use
- * `loadPendingForWrite`, which never lets an unreadable record be overwritten.
+ * The OpenKey short-link approval flow (the same one `tc onboard` uses): `init --request` creates a sealed approval
+ * request at the links API and saves it here; `init --wait` polls OpenKey for the result with the agent key's signed
+ * proof, installs the grant, and only then acknowledges it. Every step is resumable from `approval-pending.json`.
  */
-export declare function loadPending(): PendingGrantRequest | undefined;
-export declare function clearPending(): void;
-/** The saved request already holds something that cannot be made again: a reference to an approved result, the result itself, or an installed grant. */
-export declare const holdsApproval: (pending: PendingGrantRequest) => boolean;
+export declare const DEFAULT_WAIT_MS = 60000;
+export declare const MAX_WAIT_MS: number;
 /**
  * `init --request`: the saved request when it is still the same and open, else a new one. A saved request that already holds an
  * approval (a result reference, the encrypted result, or an installed grant awaiting its acknowledgement) is NEVER replaced:

package/dist/grant-request.js

@@ -1,12 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
 import { ackApprovalResult, checkApprovalResultBinding, collectApprovalResult, createApprovalRequest, DEFAULT_LINKS_API_ORIGIN, discoverApprovalResult, generateRelayKey, isApprovalClientError, isLinkError, openRelayResult, signerFromJwk, } from '@tinycloud/share-envelope/links';
 import { canonicalJson } from './canonical.js';
 import { cmd } from './program.js';
 import { CourierError } from './errors.js';
 import { AGENT_GRANT, AGENT_GRANT_EXPIRY } from './keys.js';
-import { profileDir, writeSecure } from './profile.js';
+import { profileDir } from './profile.js';
+import { ackRef, clearPending, holdsApproval, knownResult, loadPendingForWrite, markCommitted, recordResultEnvelope, recordResultRef, resultEnvelopeOf, resultSeen, savePending, stageOf, approvalPhase, } from './approval-phase.js';
 import { assertBoundToKey, installGrant, isClockRefusal, isPermanentRefusal, parseGrantPayload, resolveOpenKeyApiHost } from './grant.js';
 import { withRefusalNotice } from './grant-refusal.js';
 import { bareDid, CLOCK_SKEW_MS, durationMs, siweTimes } from './authority.js';
@@ -15,7 +14,7 @@ import { bareDid, CLOCK_SKEW_MS, durationMs, siweTimes } from './authority.js';
  * request at the links API and saves it here; `init --wait` polls OpenKey for the result with the agent key's signed
  * proof, installs the grant, and only then acknowledges it. Every step is resumable from `approval-pending.json`.
  */
-const PENDING_FILE = 'approval-pending.json';
+// The saved request file, its reader, writers and phase live in approval-phase.ts; this module only calls them.
 export const DEFAULT_WAIT_MS = 60_000;
 export const MAX_WAIT_MS = 9 * 60_000;
 /**
@@ -31,100 +30,6 @@ const MAX_SPACE_WAIT_MS = 150_000;
 const ACK_TIMEOUT_MS = 5_000;
 /** installGrant failures that no retry can fix: the approved result itself is wrong, so the request is dropped. */
 const REFUSED_CODES = { 'bad-grant': true, 'grant-too-broad': true, 'grant-incomplete': true, 'grant-expired': true, 'grant-too-long': true };
-export function readPending() {
-    const file = path.join(profileDir(), PENDING_FILE);
-    if (!fs.existsSync(file))
-        return { kind: 'none' };
-    const dirMode = fs.statSync(profileDir()).mode & 0o777;
-    if ((dirMode & 0o077) !== 0) {
-        return { kind: 'unreadable', reason: `${profileDir()} has mode ${dirMode.toString(8)}`, fix: `chmod 700 ${profileDir()}` };
-    }
-    const mode = fs.statSync(file).mode & 0o777;
-    if ((mode & 0o077) !== 0)
-        return { kind: 'unreadable', reason: `${file} has mode ${mode.toString(8)}, not 600`, fix: `chmod 600 ${file}` };
-    let text;
-    try {
-        text = fs.readFileSync(file, 'utf8');
-    }
-    catch (error) {
-        return { kind: 'unreadable', reason: `${file} cannot be read (${error.message})`, fix: `chmod 600 ${file}` };
-    }
-    let pending;
-    try {
-        pending = JSON.parse(text);
-    }
-    catch (error) {
-        return { kind: 'corrupt', reason: error.message };
-    }
-    if (pending && typeof pending.version === 'number' && pending.version > 1) {
-        // Written by a newer Courier: not corrupt, and not ours to set aside. Use that Courier, or move the file away by hand.
-        return { kind: 'unreadable', reason: `${file} was written by a newer Courier (record version ${pending.version})`, fix: `mv ${file} ${file}.newer` };
-    }
-    if (!pending || pending.version !== 1 || !pending.request || typeof pending.requestId !== 'string' || typeof pending.bodyCid !== 'string'
-        || typeof pending.approvalUrl !== 'string' || typeof pending.relayPrivateKey !== 'string' || typeof pending.ackId !== 'string') {
-        return { kind: 'corrupt', reason: 'unexpected contents' };
-    }
-    return { kind: 'ok', pending };
-}
-/**
- * Stops (without changing anything) when a saved approval request exists but cannot be read. Call it before a writer changes any
- * other state, so a key, grant or profile is never replaced while the approval it belongs to is unreachable.
- */
-export function assertPendingReadable() {
-    const read = readPending();
-    if (read.kind === 'unreadable')
-        throw unreadableError(read);
-}
-function unreadableError(read) {
-    return new CourierError('approval-unreadable', `The saved approval request cannot be used: ${read.reason}. It may hold an approval the owner already gave, so it was not touched and nothing else was changed. Fix it with \`${read.fix}\`, then run \`${cmd('init --wait')}\` again.`);
-}
-/**
- * The saved request for READ-ONLY and cleanup callers. A record that cannot be read is reported on stderr and treated as no record, so
- * it never fails a command that already installed a grant or blocks `--rotate-key`. Callers that WRITE the record use
- * `loadPendingForWrite`, which never lets an unreadable record be overwritten.
- */
-export function loadPending() {
-    const read = readPending();
-    if (read.kind === 'ok')
-        return read.pending;
-    if (read.kind !== 'none') {
-        console.error(`warning: ignoring the saved approval request ${PENDING_FILE} in ${profileDir()} (${read.reason}).`);
-    }
-    return undefined;
-}
-/**
- * The saved request for a caller that is about to write one. A record that exists but cannot be read stops the command with the file
- * named and how to fix it: the approval in it may be intact (it comes back after the fix). Only a record that is readable and corrupt
- * is set aside, as `approval-pending.json.corrupt-<time>` (0600), and the command goes on without it.
- */
-function loadPendingForWrite() {
-    const read = readPending();
-    if (read.kind === 'ok')
-        return read.pending;
-    if (read.kind === 'unreadable') {
-        throw unreadableError(read);
-    }
-    if (read.kind === 'corrupt') {
-        const file = path.join(profileDir(), PENDING_FILE);
-        const aside = `${file}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}`;
-        fs.renameSync(file, aside);
-        fs.chmodSync(aside, 0o600);
-        console.error(`warning: ${PENDING_FILE} is corrupt (${read.reason}); it was moved to ${aside} and will be replaced by a new request.`);
-    }
-    return undefined;
-}
-function savePending(pending) {
-    writeSecure(path.join(profileDir(), PENDING_FILE), pending);
-}
-export function clearPending() {
-    try {
-        fs.unlinkSync(path.join(profileDir(), PENDING_FILE));
-    }
-    catch (error) {
-        if (error.code !== 'ENOENT')
-            throw error;
-    }
-}
 function configuredOrigin(value, label) {
     let url;
     try {
@@ -178,8 +83,6 @@ function matches(pending, profile, want) {
         && (!want.explicitLifetime || grantLifetimeSeconds === want.lifetime)
         && pending.openkeyOrigin === want.openkeyOrigin && pending.apiOrigin === want.apiOrigin && pending.linkApiOrigin === want.linkApiOrigin;
 }
-/** The saved request already holds something that cannot be made again: a reference to an approved result, the result itself, or an installed grant. */
-export const holdsApproval = (pending) => pending.resultRef !== undefined || pending.resultEnvelope !== undefined || pending.committed === true;
 /**
  * OpenKey keeps an approved result for this long after the approval: production APPROVAL_RESULT_RETENTION_SECONDS=600,
  * docker-compose.prod.yml:28 (OpenKey repo). The constant follows the DEPLOYED value.
@@ -188,7 +91,10 @@ const RESULT_RETENTION_MS = 600_000;
 /** Clock difference tolerated between this machine and OpenKey when judging the end of that window. */
 const EXPIRY_SKEW_MS = 60_000;
 /** The request's own expiry has passed and nothing was ever collected for it. */
-const requestLapsed = (pending) => !holdsApproval(pending) && Date.parse(pending.requestExpiresAt) <= Date.now();
+const requestLapsed = (pending) => {
+    const phase = approvalPhase({ kind: 'ok', pending });
+    return phase.phase === 'open' && phase.lapsed;
+};
 /**
  * A lapsed, unapproved request may still have been approved just before it expired: OpenKey serves the result for
  * RESULT_RETENTION_MS after the approval. So it is asked ONCE (the normal discover) before the record is dropped:
@@ -203,8 +109,7 @@ async function settleLapsed(pending, key) {
         const found = await discoverApprovalResult(requesterState(pending, key));
         if (found.status === 'pending')
             return 'open';
-        pending.resultRef = found.resultRef;
-        pending.resultExpiresAt = found.expiresAt;
+        recordResultRef(pending, found.resultRef, found.expiresAt);
         savePending(pending);
         return 'approved';
     }
@@ -324,7 +229,7 @@ function requesterState(pending, key) {
 async function verifiedPayload(profile, pending, key) {
     let delegationCid;
     try {
-        const opened = await openRelayResult(pending.resultEnvelope, pending.requestId, pending.relayPrivateKey);
+        const opened = await openRelayResult(resultEnvelopeOf(pending), pending.requestId, pending.relayPrivateKey);
         const claimedCid = opened.delegation?.delegationCid;
         delegationCid = typeof claimedCid === 'string' && claimedCid !== '' ? claimedCid : undefined;
         const checked = checkApprovalResultBinding(opened, { requestId: pending.requestId, bodyCid: pending.bodyCid, request: pending.request });
@@ -354,12 +259,13 @@ async function verifiedPayload(profile, pending, key) {
 }
 /** Acknowledge a saved grant. A failure is reported, never fatal: the grant is installed and the saved request keeps the ack to retry. */
 async function acknowledge(pending, key) {
-    if (!pending.resultRef) {
+    const ref = ackRef(pending);
+    if (!ref) {
         clearPending();
         return;
     }
     try {
-        await ackApprovalResult(requesterState(pending, key), pending.resultRef, pending.ackId, { timeoutMs: ACK_TIMEOUT_MS });
+        await ackApprovalResult(requesterState(pending, key), ref, pending.ackId, { timeoutMs: ACK_TIMEOUT_MS });
         clearPending();
     }
     catch (error) {
@@ -380,16 +286,17 @@ async function acknowledge(pending, key) {
  * are durably saved; every earlier step is resumable from the saved request alone.
  */
 export async function completeApproval(profile, key, pending, options) {
-    if (!pending.committed) {
-        if (pending.resultEnvelope === undefined) {
+    const stage = stageOf(pending);
+    if (stage !== 'committed') {
+        if (stage !== 'result') {
+            const known = knownResult(pending);
             let collected;
             try {
                 collected = await collectApprovalResult(requesterState(pending, key), {
                     deadline: options.deadline,
-                    ...(pending.resultRef && pending.resultExpiresAt ? { known: { resultRef: pending.resultRef, expiresAt: pending.resultExpiresAt } } : {}),
+                    ...(known ? { known } : {}),
                     onDiscovered: (found) => {
-                        pending.resultRef = found.resultRef;
-                        pending.resultExpiresAt = found.expiresAt;
+                        recordResultRef(pending, found.resultRef, found.expiresAt);
                         savePending(pending);
                     },
                 });
@@ -397,11 +304,11 @@ export async function completeApproval(profile, key, pending, options) {
             catch (error) {
                 if (!isApprovalClientError(error))
                     throw error;
-                throw collectFailure(error, pending.resultRef !== undefined);
+                throw collectFailure(error, resultSeen(pending));
             }
             if (collected.status === 'deadline')
                 return 'deadline';
-            pending.resultEnvelope = collected.relay;
+            recordResultEnvelope(pending, collected.relay);
             savePending(pending); // the encrypted result is on disk before any install work
         }
         const payload = await verifiedPayload(profile, pending, key);
@@ -423,7 +330,7 @@ export async function completeApproval(profile, key, pending, options) {
                 throw withRefusalNotice(error, payload.delegationCid);
             }
         }
-        pending.committed = true;
+        markCommitted(pending);
         savePending(pending);
         await acknowledge(pending, key);
         if (spaceError)