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

package/dist/approval-phase.d.ts

@@ -0,0 +1,125 @@
+import type { LinkRecord, OpenKeyApprovalRequestV1 } from '@tinycloud/share-envelope/links';
+/**
+ * The one module that reads, writes and classifies the saved OpenKey approval request, `approval-pending.json`.
+ *
+ * `readApprovalEntry` is the only reader. `approvalPhase` is the only classifier: every other module asks it (or `stageOf`, the same rule
+ * on one record) what the request is, and never looks at the optional fields itself. The record's schema is unchanged and so is the
+ * meaning of every phase: this names what the code already did.
+ *
+ * Phases: `none` (no file), `open` (a request nobody has answered; `lapsed` is the request's own expiry having passed), `held` (the
+ * owner approved: stage `ref` = OpenKey holds a result we have only a reference to, `result` = the encrypted result is saved here,
+ * `committed` = the grant is installed and only the acknowledgement may remain), `unreadable` (the file or its directory has the wrong
+ * mode, or cannot be read: the approval in it may be intact), `corrupt` (readable, not a request) and `orphaned` (a live request whose
+ * profile or agent key is missing: it is never dropped on its own).
+ */
+export declare const APPROVAL_FILE = "approval-pending.json";
+/** 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 ApprovalEntry = {
+    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 type HeldStage = 'ref' | 'result' | 'committed';
+export type LivePhase = {
+    phase: 'open';
+    lapsed: boolean;
+} | {
+    phase: 'held';
+    stage: HeldStage;
+} | {
+    phase: 'unreadable';
+    reason: string;
+    fix: string;
+};
+export type ApprovalPhase = {
+    phase: 'none';
+} | {
+    phase: 'corrupt';
+    reason: string;
+} | LivePhase | {
+    phase: 'orphaned';
+    was: LivePhase;
+};
+/** The reader. Reads only: it never removes, repairs or rewrites the file. */
+export declare function readApprovalEntry(): ApprovalEntry;
+/** How far a held request has got: committed outranks a collected result, which outranks a reference. Undefined: nothing held. */
+export declare function stageOf(pending: PendingGrantRequest): HeldStage | undefined;
+/** The request already holds something that cannot be made again: a result reference, the result itself, or an installed grant. */
+export declare const holdsApproval: (pending: PendingGrantRequest) => boolean;
+/** A saved request has no owner to belong to when the profile or the agent key is missing. */
+export declare const lacksOwner: (presence: {
+    profile: boolean;
+    key: boolean;
+}) => boolean;
+/**
+ * The classifier. `presence` says whether the profile and the agent key exist (default: both do). The request's own expiry only matters
+ * while nothing is held, and is judged against `now`, exactly as before.
+ */
+export declare function approvalPhase(entry: ApprovalEntry, presence?: {
+    profile: boolean;
+    key: boolean;
+}, now?: number): ApprovalPhase;
+/** The saved request when it can be read, else undefined (with a warning when a file is there but unusable). For read-only and cleanup callers. */
+export declare function loadPending(): PendingGrantRequest | undefined;
+/**
+ * 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;
+/**
+ * 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.
+ */
+export declare function loadPendingForWrite(): PendingGrantRequest | undefined;
+export declare function savePending(pending: PendingGrantRequest): void;
+export declare function clearPending(): void;
+/** OpenKey holds a result for this request: remember where, and until when. */
+export declare function recordResultRef(pending: PendingGrantRequest, resultRef: string, expiresAt: string): void;
+/** The encrypted result was collected and is about to be saved. */
+export declare function recordResultEnvelope(pending: PendingGrantRequest, relay: unknown): void;
+/** The grant and profile are saved; only the acknowledgement may remain. */
+export declare function markCommitted(pending: PendingGrantRequest): void;
+/** The reference and expiry of a result already discovered, for a collection that should not ask again. */
+export declare function knownResult(pending: PendingGrantRequest): {
+    resultRef: string;
+    expiresAt: string;
+} | undefined;
+/** The reference an acknowledgement is sent for; undefined when there is none to acknowledge. */
+export declare function ackRef(pending: PendingGrantRequest): string | undefined;
+/** The collected, still encrypted result. */
+export declare function resultEnvelopeOf(pending: PendingGrantRequest): unknown;
+/** Whether a failing collection already had its result reference saved (so the failing call was the fetch). */
+export declare function resultSeen(pending: PendingGrantRequest): boolean;

package/dist/approval-phase.js

@@ -0,0 +1,175 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { cmd } from './program.js';
+import { CourierError } from './errors.js';
+import { profileDir, writeSecure } from './profile.js';
+/**
+ * The one module that reads, writes and classifies the saved OpenKey approval request, `approval-pending.json`.
+ *
+ * `readApprovalEntry` is the only reader. `approvalPhase` is the only classifier: every other module asks it (or `stageOf`, the same rule
+ * on one record) what the request is, and never looks at the optional fields itself. The record's schema is unchanged and so is the
+ * meaning of every phase: this names what the code already did.
+ *
+ * Phases: `none` (no file), `open` (a request nobody has answered; `lapsed` is the request's own expiry having passed), `held` (the
+ * owner approved: stage `ref` = OpenKey holds a result we have only a reference to, `result` = the encrypted result is saved here,
+ * `committed` = the grant is installed and only the acknowledgement may remain), `unreadable` (the file or its directory has the wrong
+ * mode, or cannot be read: the approval in it may be intact), `corrupt` (readable, not a request) and `orphaned` (a live request whose
+ * profile or agent key is missing: it is never dropped on its own).
+ */
+export const APPROVAL_FILE = 'approval-pending.json';
+/** The reader. Reads only: it never removes, repairs or rewrites the file. */
+export function readApprovalEntry() {
+    const file = path.join(profileDir(), APPROVAL_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.code ?? 'read error'})`, fix: `chmod 600 ${file}` };
+    }
+    let pending;
+    // The parser's message quotes the text around the failure, and this file holds `relayPrivateKey`: the reason is fixed, never the message.
+    try {
+        pending = JSON.parse(text);
+    }
+    catch {
+        return { kind: 'corrupt', reason: 'the file is not valid JSON' };
+    }
+    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 };
+}
+/** How far a held request has got: committed outranks a collected result, which outranks a reference. Undefined: nothing held. */
+export function stageOf(pending) {
+    if (pending.committed === true)
+        return 'committed';
+    if (pending.resultEnvelope !== undefined)
+        return 'result';
+    if (pending.resultRef !== undefined)
+        return 'ref';
+    return undefined;
+}
+/** The request already holds something that cannot be made again: a result reference, the result itself, or an installed grant. */
+export const holdsApproval = (pending) => stageOf(pending) !== undefined;
+/** A saved request has no owner to belong to when the profile or the agent key is missing. */
+export const lacksOwner = (presence) => !presence.profile || !presence.key;
+/**
+ * The classifier. `presence` says whether the profile and the agent key exist (default: both do). The request's own expiry only matters
+ * while nothing is held, and is judged against `now`, exactly as before.
+ */
+export function approvalPhase(entry, presence = { profile: true, key: true }, now = Date.now()) {
+    if (entry.kind === 'none')
+        return { phase: 'none' };
+    if (entry.kind === 'corrupt')
+        return { phase: 'corrupt', reason: entry.reason };
+    let live;
+    if (entry.kind === 'unreadable') {
+        live = { phase: 'unreadable', reason: entry.reason, fix: entry.fix };
+    }
+    else {
+        const stage = stageOf(entry.pending);
+        live = stage ? { phase: 'held', stage } : { phase: 'open', lapsed: Date.parse(entry.pending.requestExpiresAt) <= now };
+    }
+    return lacksOwner(presence) ? { phase: 'orphaned', was: live } : live;
+}
+/** The saved request when it can be read, else undefined (with a warning when a file is there but unusable). For read-only and cleanup callers. */
+export function loadPending() {
+    const entry = readApprovalEntry();
+    if (entry.kind === 'ok')
+        return entry.pending;
+    if (entry.kind !== 'none') {
+        console.error(`warning: ignoring the saved approval request ${APPROVAL_FILE} in ${profileDir()} (${entry.reason}).`);
+    }
+    return undefined;
+}
+function unreadableError(entry) {
+    return new CourierError('approval-unreadable', `The saved approval request cannot be used: ${entry.reason}. It may hold an approval the owner already gave, so it was not touched and nothing else was changed. Fix it with \`${entry.fix}\`, then run \`${cmd('init --wait')}\` again.`);
+}
+/**
+ * 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 entry = readApprovalEntry();
+    if (entry.kind === 'unreadable')
+        throw unreadableError(entry);
+}
+/**
+ * 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.
+ */
+export function loadPendingForWrite() {
+    const entry = readApprovalEntry();
+    if (entry.kind === 'ok')
+        return entry.pending;
+    if (entry.kind === 'unreadable') {
+        throw unreadableError(entry);
+    }
+    if (entry.kind === 'corrupt') {
+        const file = path.join(profileDir(), APPROVAL_FILE);
+        const aside = `${file}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+        fs.renameSync(file, aside);
+        fs.chmodSync(aside, 0o600);
+        console.error(`warning: ${APPROVAL_FILE} is corrupt (${entry.reason}); it was moved to ${aside} and will be replaced by a new request.`);
+    }
+    return undefined;
+}
+export function savePending(pending) {
+    writeSecure(path.join(profileDir(), APPROVAL_FILE), pending);
+}
+export function clearPending() {
+    try {
+        fs.unlinkSync(path.join(profileDir(), APPROVAL_FILE));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+// ---- the record's optional fields: only this module reads or sets them ----
+/** OpenKey holds a result for this request: remember where, and until when. */
+export function recordResultRef(pending, resultRef, expiresAt) {
+    pending.resultRef = resultRef;
+    pending.resultExpiresAt = expiresAt;
+}
+/** The encrypted result was collected and is about to be saved. */
+export function recordResultEnvelope(pending, relay) {
+    pending.resultEnvelope = relay;
+}
+/** The grant and profile are saved; only the acknowledgement may remain. */
+export function markCommitted(pending) {
+    pending.committed = true;
+}
+/** The reference and expiry of a result already discovered, for a collection that should not ask again. */
+export function knownResult(pending) {
+    return pending.resultRef && pending.resultExpiresAt ? { resultRef: pending.resultRef, expiresAt: pending.resultExpiresAt } : undefined;
+}
+/** The reference an acknowledgement is sent for; undefined when there is none to acknowledge. */
+export function ackRef(pending) {
+    return pending.resultRef || undefined;
+}
+/** The collected, still encrypted result. */
+export function resultEnvelopeOf(pending) {
+    return pending.resultEnvelope;
+}
+/** Whether a failing collection already had its result reference saved (so the failing call was the fetch). */
+export function resultSeen(pending) {
+    return pending.resultRef !== undefined;
+}
+//# sourceMappingURL=approval-phase.js.map

package/dist/approval-phase.js.map

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

package/dist/commands.js

@@ -1,3 +1,4 @@
+import { adviceFor, deriveState, heldApproval, recoverInterrupted, rotateKey } from './state.js';
 import { recentNotices } from './notify.js';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -7,10 +8,12 @@ import { NodeWasmBindings, activateValidatedRuntimeDelegation, deserializeDelega
 import { cmd } from './program.js';
 import { CourierError, CourierPending, errInfo } from './errors.js';
 import { AGENT_GRANT, AGENT_GRANT_EXPIRY, COURIER_SPACE, DEFAULT_HOST, EXT, k, peerReadPermissions, PREFIX } from './keys.js';
-import { loadProfile, saveProfile, getPeer, profileDir, profileExists, loadKey, saveKey, } from './profile.js';
+import { loadProfile, saveProfile, assertNotPaired, getPeer, profileDir, profileExists, loadKey, saveKey, } from './profile.js';
 import { courierNode, peerKv } from './node.js';
+import { REVOKE_URL } from './grant-refusal.js';
 import { courierGrantRequest, grantFromInput, installRefusing, isShortCode, noSpaceError, pendingSpaceError, receiveGrant, resumeAwaitingGrant, resumeGrant } from './grant.js';
-import { assertPendingReadable, clearPending, completeApproval, DEFAULT_WAIT_MS, holdsApproval, loadPending, MAX_WAIT_MS, readPending, requestApproval, waitApproval } from './grant-request.js';
+import { completeApproval, DEFAULT_WAIT_MS, MAX_WAIT_MS, requestApproval, waitApproval } from './grant-request.js';
+import { approvalPhase, assertPendingReadable, clearPending, holdsApproval, loadPending, readApprovalEntry, stageOf } from './approval-phase.js';
 import { artifactA, artifactWithDelegation, parseArtifact, peerRecordBody, PEER_DELEGATION_EXPIRY, validateArtifactIdentity, } from './pairing.js';
 import { authRequiredTask, buildMessage, buildTask, COUNTERPARTY_NOTICE, isRecord, messageView, oneLine, safeText, messageRole, parseTaskState, taskView, INTENTS, } from './a2a.js';
 import { commitReceipts, collectInbound, renderInboxText, writeOut } from './inbox.js';
@@ -96,12 +99,41 @@ export async function cmdInit(args) {
     const grantRaw = grantFile === undefined || args.has('request')
         ? undefined
         : grantFile === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(grantFile, 'utf8');
+    // Explicit recovery before any mode acts: finish an interrupted rotation, remove stray key-bearing temp files; then derive once.
+    recoverInterrupted();
+    const state = deriveState();
+    for (const note of state.notes)
+        console.error(`warning: ${note}`);
+    // A profile.json that exists and cannot be read is never treated as absent: `loadProfile` refuses with its own message (an unreadable
+    // profile is replaced only by an explicit `--rotate-key`).
+    if (state.action === 'fix-profile' && !args.has('rotate-key')) {
+        loadProfile();
+        fail('bad-profile', adviceFor(state));
+    }
+    // A saved approval without its profile or key is left as it is; `--rotate-key` starts over with a new key.
+    if (state.action === 'refuse' && !args.has('rotate-key'))
+        fail('approval-orphaned', adviceFor(state));
+    // A grant.json that is not owner-only is a saved grant that cannot be used yet: it is neither replaced nor counted as missing. A rotation
+    // discards the grant by design, so it goes on.
+    if (state.grantMode && !args.has('rotate-key')) {
+        const file = path.join(profileDir(), 'grant.json');
+        fail('profile-permissions', `${file} must be owner-only (mode 0600); found mode ${state.grantMode}. It holds a saved grant, so nothing was changed. Run \`chmod 600 ${file}\`, then run the command again.`);
+    }
+    const HELD_APPROVAL_KEPT = `The saved approval request holds an approval from the owner and was kept: run \`${cmd('init --wait')}\` to collect or acknowledge it.`;
     if (args.has('resume')) {
         if (!profileExists())
             fail('no-grant', `No Courier profile to resume. Run \`${cmd('init')}\` and approve a grant first.`);
         const profile = loadProfile();
+        // An approval the owner gave, with no grant saved to install first, is collected by `--wait`, never discarded or shadowed by a cleanup.
+        if (state.action === 'wait' && heldApproval(state.inputs.approval) && profile.status !== 'ready') {
+            console.error(`${adviceFor(state)} Continuing as \`${cmd('init --wait')}\`.`);
+            await collectApproval(profile, loadKey(), { expiry: args.get('expiry'), openkeyApiHost: apiHostFlag, waitMs });
+            return;
+        }
         if (profile.status === 'awaiting-grant' && await resumeAwaitingGrant(profile)) {
             dropOpenRequest();
+            if (heldApproval(state.inputs.approval))
+                console.error(HELD_APPROVAL_KEPT);
             await finishInit(profile, profile.host);
             return;
         }
@@ -109,22 +141,20 @@ export async function cmdInit(args) {
             fail('usage', `\`${cmd('init --resume')}\` requires a profile in awaiting-space state.`);
         await resumeGrant(profile, loadKey());
         dropOpenRequest();
+        if (heldApproval(state.inputs.approval))
+            console.error(HELD_APPROVAL_KEPT);
         await finishInit(profile, profile.host);
         return;
     }
     const rotate = args.has('rotate-key');
     // A writer must learn that the saved approval is unreadable BEFORE the key, grant or profile is changed.
-    if (args.has('request') || args.has('wait'))
+    // Also for a plain `--rotate-key`: an approval that cannot be read may be bound to the old key, and a rotation would leave it there.
+    if (args.has('request') || args.has('wait') || rotate)
         assertPendingReadable();
-    // Read before the key is replaced: an approval the owner already gave is bound to the old key and is lost by a rotation.
-    const heldApproval = rotate && (() => { const saved = loadPending(); return saved !== undefined && holdsApproval(saved); })();
     const prior = profileExists() && !rotate ? loadProfile() : undefined;
-    // A renewal is asked for with `--request`; `--wait` only collects. Starting a request here would hide its link on stderr.
-    if (args.has('wait') && prior && prior.status !== 'awaiting-grant' && !loadPending()) {
-        fail('usage', prior.status === 'awaiting-space'
-            ? `The grant is saved and the "${COURIER_SPACE}" space is still being set up: run \`${cmd('init --resume')}\`. \`${cmd('init --wait')}\` collects an approval that \`${cmd('init --request')}\` asked for.`
-            : `This profile already has a grant and no approval request is pending. To renew it, run \`${cmd('init --request')}\`, send the printed openkeyUrl to the owner, then run \`${cmd('init --wait')}\`.`);
-    }
+    // A renewal is asked for with `--request`; `--wait` only collects. The derived state says when `--wait` goes on.
+    if (args.has('wait') && !rotate && !state.wait)
+        fail('usage', adviceFor(state));
     const key = prior ? loadKey() : newAgentKey();
     const host = hostFlag ?? prior?.host ?? process.env.COURIER_HOST ?? DEFAULT_HOST;
     const openkeyHost = openkeyHostFlag ?? prior?.openkeyHost ?? process.env.COURIER_OPENKEY_HOST ?? 'https://openkey.so';
@@ -143,25 +173,23 @@ export async function cmdInit(args) {
     profile.label = labelFlag ?? profile.label;
     if (handleFlag)
         profile.selfHandle = handleFlag;
+    profile.courierDid = bareDid(key.did);
     if (rotate) {
         profile.peers = {};
         profile.ownerDid = undefined;
         profile.spaceId = undefined;
         profile.grantExpiresAt = undefined;
         profile.status = 'awaiting-grant';
-        try {
-            fs.unlinkSync(path.join(profileDir(), 'grant.json'));
-        }
-        catch { /* no prior grant */ }
+        // One journaled step: key, profile, grant and a discarded approval change together, and an interruption is finished by the next init.
+        await rotateKey(key, profile);
+    }
+    else {
+        saveKey(key);
+        saveProfile(profile);
     }
-    profile.courierDid = bareDid(key.did);
-    saveKey(key);
-    saveProfile(profile);
     const request = courierGrantRequest(profile, key, expiry, { openkeyApiHost: apiHostFlag });
     if (rotate)
         console.error('Agent key rotated. Existing peer pairings must be re-established; the old grant remains valid until expiry.');
-    if (heldApproval)
-        console.error('The saved approval request already held an approval from the owner. It is bound to the old agent key, so this key rotation discards that approval: the owner must approve a new request.');
     if (args.has('request')) {
         const pending = await requestApproval(profile, key, args.get('expiry'), { openkeyApiHost: apiHostFlag });
         console.error(`Send the owner this link to approve (it expires ${pending.requestExpiresAt}). Copy it exactly, never retype it:\n${pending.approvalUrl}\nThen run \`${cmd('init --wait --timeout 60s')}\` to collect the approval.`);
@@ -171,18 +199,7 @@ export async function cmdInit(args) {
         return;
     }
     if (args.has('wait')) {
-        const deadline = Date.now() + waitMs;
-        const { pending, resumed } = await waitApproval(profile, key, args.get('expiry'), { openkeyApiHost: apiHostFlag });
-        if (!pending.committed) {
-            console.error(`${resumed ? 'Resuming the saved approval request.' : 'Created an approval request.'} Owner: approve it in OpenKey (copy the link exactly, never retype it):\n${pending.approvalUrl}\nWaiting for approval (up to ${Math.round(waitMs / 1000)} s). Run \`${cmd('init --wait')}\` again after an interruption; no new approval is needed.`);
-        }
-        if (await completeApproval(profile, key, pending, { deadline }) === 'deadline') {
-            throw new CourierPending({ step: 1, of: 1, approvalUrl: pending.approvalUrl, expiresAt: pending.requestExpiresAt });
-        }
-        const active = loadProfile();
-        if (active.status !== 'ready')
-            throw active.spacePending ? pendingSpaceError(active) : noSpaceError(active);
-        await finishInit(active, active.host);
+        await collectApproval(profile, key, { expiry: args.get('expiry'), openkeyApiHost: apiHostFlag, waitMs });
         return;
     }
     let payload;
@@ -211,14 +228,14 @@ export async function cmdInit(args) {
  */
 function clearPendingQuietly() {
     try {
-        const read = readPending();
-        if (read.kind === 'ok' && read.pending.committed) {
+        const phase = approvalPhase(readApprovalEntry());
+        if (phase.phase === 'held' && phase.stage === 'committed') {
             console.error('This grant replaces a saved short-link approval that was already installed: its acknowledgement to OpenKey is never sent (harmless; OpenKey discards the result).');
         }
-        else if (read.kind === 'ok' && holdsApproval(read.pending)) {
+        else if (phase.phase === 'held') {
             console.error('This grant replaces the saved short-link approval: discarded a saved approval that was not installed.');
         }
-        else if (read.kind === 'unreadable' || read.kind === 'corrupt') {
+        else if (phase.phase === 'unreadable' || phase.phase === 'corrupt') {
             console.error('This grant replaces the saved short-link request: discarded an unreadable saved approval request (it may have held an approval that was not installed).');
         }
         clearPending();
@@ -237,6 +254,21 @@ function dropOpenRequest() {
     if (saved && !holdsApproval(saved))
         clearPendingQuietly();
 }
+/** `init --wait`: create or resume the approval request, wait for the owner, install the result and acknowledge it. `--resume` hands off here while an approval is saved. */
+async function collectApproval(profile, key, options) {
+    const deadline = Date.now() + options.waitMs;
+    const { pending, resumed } = await waitApproval(profile, key, options.expiry, { openkeyApiHost: options.openkeyApiHost });
+    if (stageOf(pending) !== 'committed') {
+        console.error(`${resumed ? 'Resuming the saved approval request.' : 'Created an approval request.'} Owner: approve it in OpenKey (copy the link exactly, never retype it):\n${pending.approvalUrl}\nWaiting for approval (up to ${Math.round(options.waitMs / 1000)} s). Run \`${cmd('init --wait')}\` again after an interruption; no new approval is needed.`);
+    }
+    if (await completeApproval(profile, key, pending, { deadline }) === 'deadline') {
+        throw new CourierPending({ step: 1, of: 1, approvalUrl: pending.approvalUrl, expiresAt: pending.requestExpiresAt });
+    }
+    const active = loadProfile();
+    if (active.status !== 'ready')
+        throw active.spacePending ? pendingSpaceError(active) : noSpaceError(active);
+    await finishInit(active, active.host);
+}
 async function finishInit(profile, host) {
     const active = await ctx();
     for (const peer of Object.values(active.profile.peers)) {
@@ -326,6 +358,7 @@ async function pairAccept(args) {
         fail('bad-artifact', 'Refusing to pair with this agent identity.');
     if (art.step === 'A') {
         const handle = art.callMe;
+        assertNotPaired(profile, handle); // before delegateTo: a refusal after it would leave a live delegation nothing records
         const outbound = await node.delegateTo(art.from.courier, peerReadPermissions(handle, profile.spaceId), { expiry: PEER_DELEGATION_EXPIRY });
         const peer = {
             handle, ownerDid: art.from.owner, courierDid: art.from.courier, label: art.from.label,
@@ -333,7 +366,7 @@ async function pairAccept(args) {
         };
         recordOutbound(peer, outbound.delegation);
         profile.peers[handle] = peer;
-        saveProfile(profile);
+        saveAfterDelegation(profile, outbound.delegation);
         await writePeerRecord(node, peer);
         printJson(artifactWithDelegation('B', profile, outbound.delegation, handle, art.peer));
         return;
@@ -355,7 +388,7 @@ async function pairAccept(args) {
         const outgoing = await node.delegateTo(peer.courierDid, peerReadPermissions(peer.handle, profile.spaceId), { expiry: PEER_DELEGATION_EXPIRY });
         recordOutbound(peer, outgoing.delegation);
         peer.status = 'paired';
-        saveProfile(profile);
+        saveAfterDelegation(profile, outgoing.delegation);
         await writePeerRecord(node, peer);
         printJson(artifactWithDelegation('C', profile, outgoing.delegation, peer.handle, art.peer));
         return;
@@ -388,6 +421,19 @@ async function pairAccept(args) {
     await writePeerRecord(node, peer);
     printJson({ ok: true, paired: peer.handle, peerDid: peer.courierDid, peerSpace: peer.spaceId, delegationExpiresAt: peer.inbound.expiresAt });
 }
+/**
+ * Saves after `delegateTo` made a delegation that is live from that moment. A save that refuses (the pairing completed, or the peer was
+ * revoked, meanwhile) leaves a delegation no profile records: say so, with its CID and where the owner can revoke it, and never publish it.
+ */
+function saveAfterDelegation(profile, delegation) {
+    try {
+        saveProfile(profile);
+    }
+    catch (error) {
+        console.error(`warning: the delegation ${delegationCid(delegation)} created for this pairing is live and was not saved. Nothing was published. The owner can revoke it at ${REVOKE_URL}.`);
+        throw error;
+    }
+}
 function recordOutbound(peer, delegation) {
     const expiresAt = delegation.expiry instanceof Date ? delegation.expiry.toISOString() : new Date(delegation.expiry).toISOString();
     peer.outbound.push({ cid: delegationCid(delegation), issuedAt: new Date().toISOString(), expiresAt });