agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/recovery-key.js

@@ -0,0 +1,386 @@
+import { randomInt } from 'node:crypto';
+import { shellArg } from './shell-arg.js';
+// The recovery key (K7) is the only thing that opens the vault. It is generated
+// here, shown once, and never stored — not by us and not by the server. Losing it
+// means the vault is unopenable, which is the property that makes the vault worth
+// having; the cost is that the display and the read-back below are the entire
+// safety net for the user.
+// Crockford-ish: no I/L/O/U, so a transcribed key cannot be ruined by 1-vs-l or
+// 0-vs-O. 32 symbols = 5 bits each.
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+// The shape the design pins (recovery-vault-v1.md, recovery-key-v1): 24 symbols
+// of secret — 120 bits — plus one check symbol, shown as five groups of five
+// behind an AGMSG- prefix.
+//
+// The prefix is not decoration. It is how someone finds this string again on a
+// piece of paper months later and knows what it opens; a bare block of base32
+// is indistinguishable from every other token they have written down.
+const PREFIX = 'AGMSG-';
+const PREFIX_SYMBOLS = 'AGMSG'.length;
+const SECRET_SYMBOLS = 24;
+const TOTAL_SYMBOLS = SECRET_SYMBOLS + 1;
+const GROUP = 5;
+// The check symbol, 5 bits, over the 24 secret symbols.
+//
+// The design delegates "check-digit bit selection and domain" to an OSS pin
+// that does not exist yet (searched: no recovery-key spec in the vendored
+// tree). So this is the cloud side choosing first, and the choice is written
+// down here rather than left in the arithmetic:
+//
+//   sum of (value * (position + 1)) over the 24 symbols, mod 32
+//
+// The weights are ODD, which is the whole reason the scheme works mod 32.
+// An even weight shares a factor with 32, so a substitution can move the sum
+// by a multiple of 32 and leave the check symbol unchanged: with weight 2, a
+// value difference of 16 is invisible. Odd weights are invertible mod 32, so
+// weight*delta is zero only when delta is, and EVERY single-symbol
+// substitution changes the result.
+//
+// Adjacent transposition is the weaker case, not the stronger one: swapping
+// neighbours moves the sum by 2*(a-b) mod 32, which vanishes when the two
+// symbols differ by exactly 16. So: all single substitutions, and all
+// transpositions except that one class.
+//
+// A prime modulus (Crockford's own check uses 37) would catch both outright,
+// and is what a future pin should probably use. It cannot be spelled in five
+// bits, which is what the design asked for. Changing this later invalidates
+// keys people have already written down.
+function checkSymbol(secret) {
+    let sum = 0;
+    for (let i = 0; i < secret.length; i++) {
+        sum += ALPHABET.indexOf(secret[i]) * (2 * i + 1);
+    }
+    return ALPHABET[sum % ALPHABET.length];
+}
+/** The canonical display form: AGMSG-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX. */
+export function formatRecoveryKey(symbols) {
+    return PREFIX + (symbols.match(new RegExp(`.{1,${GROUP}}`, 'g')) ?? []).join('-');
+}
+export function generateRecoveryKey() {
+    let secret = '';
+    for (let i = 0; i < SECRET_SYMBOLS; i++) {
+        // randomInt is rejection-sampled: `randomBytes[i] % 32` would be unbiased at
+        // 32 but silently biased the moment someone edits the alphabet's length.
+        secret += ALPHABET[randomInt(ALPHABET.length)];
+    }
+    return formatRecoveryKey(secret + checkSymbol(secret));
+}
+// Accept what a human retypes: any case, any grouping, and the four excluded
+// letters mapped to the digits they get mistaken for. Everything else is an
+// error rather than a silent drop, so a wrong key fails as a wrong key and not
+// as a mangled one.
+export function normalizeRecoveryKey(input) {
+    let cleaned = input
+        .trim()
+        .toUpperCase()
+        .replace(/[\s-]/g, '');
+    // The prefix is a label, not key material, and it is stripped by LENGTH
+    // rather than by the letters. Every character of AGMSG is also a legal
+    // symbol, so a perfectly good key can begin with those five: stripping on
+    // sight turns that person's 25 symbols into 20 and rejects the key they
+    // hold. One in 32^5 keys starts that way — rare enough never to be noticed
+    // in testing, and permanent for whoever draws it.
+    //
+    // So: PREFIX + body is 30 and gets the prefix removed; a bare body is 25 and
+    // is kept whole. Anything else falls through to the length check below,
+    // which says what was wrong.
+    if (cleaned.length === PREFIX_SYMBOLS + TOTAL_SYMBOLS && cleaned.startsWith('AGMSG')) {
+        cleaned = cleaned.slice(PREFIX_SYMBOLS);
+    }
+    cleaned = cleaned
+        .replace(/[IL]/g, '1')
+        .replace(/O/g, '0')
+        .replace(/U/g, 'V');
+    for (const ch of cleaned) {
+        if (!ALPHABET.includes(ch))
+            throw new Error(`recovery key contains an unusable character: ${ch}`);
+    }
+    if (cleaned.length !== TOTAL_SYMBOLS) {
+        throw new Error(`recovery key must be ${TOTAL_SYMBOLS} symbols, got ${cleaned.length}`);
+    }
+    // The check symbol, verified here rather than at the vault. Without it, a
+    // mistyped key is indistinguishable from a wrong one until the AEAD refuses
+    // it — which is at restore time, the moment there is no way back. Naming the
+    // typo at the prompt is the whole reason the design could withdraw the
+    // type-it-back-to-confirm step.
+    const secret = cleaned.slice(0, SECRET_SYMBOLS);
+    if (cleaned[SECRET_SYMBOLS] !== checkSymbol(secret)) {
+        throw new Error('that recovery key has a typo in it: the check symbol does not match. ' +
+            'Nothing was sent. Compare it with what you wrote down and try again.');
+    }
+    return cleaned;
+}
+// Read a secret from the terminal without ever writing it to an output stream.
+//
+// The obvious implementation — let readline echo, then erase the line — does not
+// work, and looked like it did. readline writes the character to stdout first;
+// the erase only repaints the screen. Anything recording that stream (a PTY
+// transcript, `script`, a terminal logger, CI capture) already has the key bytes.
+// "It disappears from the display" is not "it was never emitted".
+//
+// So: raw mode, read the key events ourselves, and echo nothing. Deliberately
+// narrow otherwise — there is no argv flag and no environment variable for the
+// recovery key, because both would put it in shell history and in every process
+// listing on the machine.
+//
+// Raw mode is process-EXTERNAL state: it belongs to the terminal and outlives us.
+// So the restore is bound to every way out, not to the successful one. A `finally`
+// covers returning and throwing; it does not cover being killed, and it does not
+// cover a stream that ends while we wait. Leaving a shell with no echo and no line
+// editing is its own kind of damage — and having written restore code is not
+// evidence that it runs.
+const PROMPT_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+const CTRL_C = '\x03';
+const DEL = '\x7f';
+// What stands in for a typed symbol. A fixed character, so the width of the
+// row is the number of symbols entered and nothing about their values.
+//
+// ASCII on purpose. A bullet renders as two bytes that `cat -v` shows as
+// M-^@M-^" and that a non-UTF-8 terminal shows as mojibake — and this row is
+// the only feedback someone gets while typing a key they cannot see.
+const MASK = '*';
+// One raw-mode session at the terminal, with every way out restored.
+//
+// Extracted because a second input path (the save acknowledgement) reimplemented
+// it and lost half: no signal handling, no end/close/error, and on those paths
+// the promise never settled and the shell was left in raw mode. A third input
+// path would have lost a different half. There is one of these now, and both
+// callers get whatever it knows.
+//
+// `onChunk` decides when the session is over: call `done()` to finish, or
+// `stop(err)` to fail. Everything else — listeners, signal handlers, raw mode,
+// pause — is unwound exactly once, on every exit including the ones nobody
+// writes tests for.
+function withRawStdin(prompt, onChunk) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
+        return Promise.reject(new Error('this can only be answered at a terminal (stdin is not a TTY)'));
+    }
+    const wasRaw = stdin.isRaw === true;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        // Idempotent, and the only place that undoes anything. The signal handlers
+        // go too: registered per session, they would otherwise accumulate on the
+        // process across successive prompts.
+        const restore = () => {
+            if (settled)
+                return;
+            settled = true;
+            stdin.off('data', onData);
+            stdin.off('end', onEnd);
+            stdin.off('close', onEnd);
+            stdin.off('error', onError);
+            for (const [sig, handler] of signalHandlers)
+                process.off(sig, handler);
+            try {
+                stdin.setRawMode(wasRaw);
+            }
+            catch {
+                // The stream can already be gone on close/error; nothing left to restore.
+            }
+            stdin.pause();
+        };
+        const done = (value) => {
+            restore();
+            resolve(value);
+        };
+        const stop = (err) => {
+            restore();
+            reject(err);
+        };
+        const onData = (chunk) => onChunk(chunk, done, stop);
+        const onEnd = () => stop(new Error('input ended before the terminal answered'));
+        const onError = (err) => stop(err instanceof Error ? err : new Error(`stdin failed: ${String(err)}`));
+        // Restore first, then let the signal do what it was sent to do. Swallowing
+        // it would turn "stop this process" into "this process ignores you".
+        const signalHandlers = PROMPT_SIGNALS.map((sig) => [
+            sig,
+            () => {
+                stop(new Error(`interrupted by ${sig}`));
+                process.kill(process.pid, sig);
+            },
+        ]);
+        try {
+            stdin.setRawMode(true);
+            stdin.resume();
+            stdin.setEncoding('utf8');
+            stdin.on('data', onData);
+            stdin.on('end', onEnd);
+            stdin.on('close', onEnd);
+            stdin.on('error', onError);
+            for (const [sig, handler] of signalHandlers)
+                process.on(sig, handler);
+            process.stdout.write(prompt);
+        }
+        catch (err) {
+            // setRawMode/resume/setEncoding can throw. They sit inside the guarded
+            // region precisely so that failing halfway still unwinds what was done.
+            stop(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+}
+export function promptRecoveryKey(prompt) {
+    let entered = '';
+    return withRawStdin(prompt, (chunk, done, stop) => {
+        for (const ch of chunk) {
+            switch (ch) {
+                case '\r':
+                case '\n':
+                    process.stdout.write('\n');
+                    done(entered);
+                    return;
+                case CTRL_C: // In raw mode this arrives as a byte, not as a signal.
+                    process.stdout.write('\n');
+                    stop(new Error('cancelled'));
+                    return;
+                case DEL: // Backspace.
+                case '\b':
+                    // Erase one mask character too, or the row stops matching what is in
+                    // the buffer: someone correcting a typo would watch the line keep
+                    // growing and have no idea how far back they had reached.
+                    if (entered.length > 0)
+                        process.stdout.write('\b \b');
+                    entered = entered.slice(0, -1);
+                    break;
+                default:
+                    // Ignore other control characters rather than storing them: they are
+                    // never part of a recovery key and would fail normalization later
+                    // with a confusing message.
+                    if (ch >= ' ') {
+                        entered += ch;
+                        // One mask character per accepted symbol — not the symbol itself,
+                        // which is the property this prompt exists for. Typing 25
+                        // characters into a line that never moves is indistinguishable
+                        // from a hung terminal, and the reflex it teaches is to paste.
+                        process.stdout.write(MASK);
+                    }
+            }
+        }
+    });
+}
+// Show the key once, before anything is stored.
+//
+// There is no type-it-back step: the design withdrew it (recovery-vault-v1.md,
+// recovery-key-v1, "no re-entry confirmation") once the key carried a check
+// symbol. Retyping 25 characters with no error detection is what taught people
+// to paste, and paste is the one thing this key must never touch. The check
+// symbol names a typo at the prompt instead.
+//
+// There IS an acknowledgement keypress, and the ordering is what makes it
+// mean something: display -> save ack -> vault create. Cancelling at the ack
+// leaves no vault, because nothing has been created yet.
+//
+// Showing after the upload instead would break both halves. It creates a
+// failure this order does not have — a crash between storing the vault and
+// reaching the screen leaves a vault encrypted under a key nobody has ever
+// seen — and it makes the ack a lie, since the thing it offers to cancel
+// already exists. A key on paper for a vault that was never created is fixed
+// by discarding the paper; neither of those is.
+//
+// Showing last becomes safe when the device-local slot exists, because the key
+// can then be re-derived from material this machine holds. It does not exist
+// yet, so the caller shows first and says so if the backup then fails.
+//
+// The command it prints is the REAL one, built from the team this run was
+// given and quoted through `shellArg` (raised in review). It used to read
+// `agmsg-cloud recovery setup` with no argument, which the dispatch refuses —
+// so the one line telling someone what to do next was a line that could only
+// produce a usage error. A `<team>` placeholder would have the same defect in
+// a politer form: what is printed here is meant to be pasted, so it has to be
+// the command that runs, for the team this failure happened on, including
+// when that name is not one shell word.
+// The command to re-run. The quoting sits ON the interpolating line, which is
+// what the printed-command checker reads — a ternary hid it, and so did binding
+// the result to a variable first. Both were still quoted; neither was visible.
+// The checker is right to demand the stricter form: what it can see is what
+// survives the next edit.
+function setupCommand(team) {
+    if (team === undefined)
+        return 'agmsg-cloud recovery setup';
+    return `agmsg-cloud recovery setup ${shellArg(team)}`;
+}
+export class NeedsTerminalError extends Error {
+    constructor(team) {
+        super('this needs a terminal, and stdin is not one.\n\n' +
+            'Nothing was created and no recovery key exists yet. Run this yourself,\n' +
+            'in your own terminal:\n\n' +
+            `    ${setupCommand(team)}\n\n` +
+            'It is refused here on purpose: the recovery key is shown once and stored\n' +
+            'nowhere, so writing it into a redirected or captured stream would be this\n' +
+            'tool breaking that promise itself.');
+        this.name = 'NeedsTerminalError';
+    }
+}
+/**
+ * The words shown with the key, as a value rather than as a side effect.
+ *
+ * Split out because the words ARE the artifact here, and they could not be
+ * checked: this screen claimed the machine would be asked for the key again on
+ * the next backup, the closing line of the same command claimed it would not,
+ * and nothing failed. The most important screen in the product contradicted
+ * itself and no test could see it.
+ */
+export function recoveryKeyNotice(key) {
+    return ('\n' +
+        'RECOVERY KEY - save this now. This is the only time it is shown.\n' +
+        'Your vault is created right after this, using this key.\n' +
+        '\n' +
+        `    ${key}\n` +
+        '\n' +
+        // Says nothing about whether this machine will ask again, deliberately.
+        //
+        // It cannot: this runs BEFORE the vault exists and before a device key
+        // slot is attempted, and whether one can be kept depends on the machine —
+        // there is no secure store on Windows or Linux, and a locked keychain
+        // refuses on macOS. The command reports what actually happened once it
+        // knows, in one place (`keepSlot`). A screen that has to be read once and
+        // acted on immediately is the last place to put a guess about the future.
+        'Put it in your password manager, or print it and keep it where you keep\n' +
+        'a passport. It is the only thing that opens your personal recovery\n' +
+        'vault, from this machine or any other. Nobody can reissue it: not this\n' +
+        'machine, not the server, not support.\n' +
+        '\n');
+}
+export async function showRecoveryKey(key, team) {
+    // Checked BEFORE the key reaches stdout, which is the whole point. Showing
+    // first and then discovering there is nobody to acknowledge means the only
+    // copy of the key is already in whatever the output was redirected to —
+    // `recovery setup <team> > log.txt` would write it to a file and report
+    // success, which is the opposite of "shown once, stored nowhere".
+    //
+    // Nothing has been created at this point, so refusing here leaves no vault
+    // and no key in use. The message says what to run instead.
+    if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function') {
+        throw new NeedsTerminalError(team);
+    }
+    process.stdout.write(recoveryKeyNotice(key));
+    await confirmSaved();
+}
+// The one thing left of the withdrawn confirmation step: a keypress, not a
+// transcription.
+//
+// It is load-bearing only because it happens BEFORE the vault is created.
+// Cancelling here leaves no vault, so a person who is not ready to save the
+// key can stop and nothing exists that needs it. Move the display after the
+// upload and this button stops meaning anything — the vault is already there,
+// and "cancel" would be a lie.
+//
+// Ctrl-C is the cancel. It throws rather than returning a flag, because every
+// caller's correct response is to stop, and a flag invites one of them to
+// carry on.
+async function confirmSaved() {
+    // No non-TTY branch here: showRecoveryKey refuses before the key is printed,
+    // so by the time this runs there is a terminal. A second escape hatch would
+    // be a way to reach the vault-create without an acknowledgement.
+    await withRawStdin('Press Enter once you have saved it, or Ctrl-C to stop. ', (chunk, done, stop) => {
+        if (chunk.includes(CTRL_C)) {
+            process.stdout.write('\n\n');
+            stop(new Error('stopped before anything was created; no vault exists and no key is in use'));
+            return;
+        }
+        if (chunk.includes('\r') || chunk.includes('\n')) {
+            process.stdout.write('\n\n');
+            done(undefined);
+        }
+    });
+}

package/dist/src/sas.js

@@ -0,0 +1,18 @@
+// Whether the SAS ceremony is pinned.
+//
+// It is. The derivations live in @agmsg-cloud/sas-core, fixed to the three test
+// vectors of docs/spec/sas-pin-v1.md §6 and driven through the server as well as
+// the clients, so both sides agree with the SPECIFICATION rather than merely
+// with each other. The provisional derivation that used to live here — a short
+// digest a malicious server could grind a match for — is gone.
+//
+// What this flag gates is approval, which seals real key history to a machine on
+// the strength of eight digits a human compared. It stayed false while any part
+// of that comparison was unfinished, and the order it was turned on in matters:
+// the state machine and the client were each reviewed, an end-to-end run proved
+// the two halves actually work together over real HTTP with real age keys, and
+// only then did this become true.
+//
+// Turning it back to false is a real thing to do if the ceremony is ever in
+// doubt: everything downstream of it is fail-closed by construction.
+export const SAS_PINNED = true;

package/dist/src/secure-store.js

@@ -0,0 +1,176 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+const SERVICE = 'agmsg-cloud';
+// macOS ships `security`. Linux would use libsecret's `secret-tool` and Windows
+// the credential manager; neither is implemented here, and each reports
+// unsupported rather than pretending. Callers must treat unsupported as "this
+// machine keeps using the recovery key", never as "write it somewhere else".
+function platformTool() {
+    return process.platform === 'darwin' ? { tool: 'security' } : null;
+}
+export async function secureStoreStatus() {
+    const platform = platformTool();
+    if (!platform) {
+        return {
+            kind: 'unsupported',
+            reason: `no supported secure store on ${process.platform} (this build knows macOS only)`,
+        };
+    }
+    try {
+        // Cheapest call that proves the tool exists AND answers: listing the
+        // default keychain touches the store without writing to it.
+        await run('security', ['default-keychain']);
+        return { kind: 'available' };
+    }
+    catch (err) {
+        return { kind: 'locked', reason: messageOf(err) };
+    }
+}
+/**
+ * How the store command is built, as a pure value.
+ *
+ * Separate from running it because the two have different requirements: the
+ * command can be checked anywhere, and only executing it needs macOS. Folding
+ * them together is what let a platform guard hide the check — on Linux CI the
+ * refusal came first and the argv assertions never ran, so reverting to the
+ * old `-w <secret>` shape would have stayed green.
+ *
+ * argv carries `-i` and nothing else. The command, with the value as hex,
+ * travels on stdin — anything in argv is readable by every process of the same
+ * user, and the blob is the KEK and the wrapped VDK together.
+ */
+export function buildStoreCommand(account, value) {
+    assertAddressable(account);
+    const line = [
+        'add-generic-password',
+        '-a',
+        hexArg(account),
+        '-s',
+        hexArg(SERVICE),
+        '-X',
+        Buffer.from(value, 'utf8').toString('hex'),
+        '-U',
+    ].join(' ');
+    return { argv: ['-i'], stdin: `${line}\n` };
+}
+export async function storeSecret(account, value) {
+    // Built first, so a malformed account is refused the same way everywhere.
+    const command = buildStoreCommand(account, value);
+    requireDarwin();
+    // Not a temp file, deliberately. Writing the wrapped VDK to disk — even
+    // 0600, even briefly — breaks the property this whole feature rests on: the
+    // key material exists in memory for one command and nowhere else.
+    await runner(command);
+}
+// Names go through hex as well, on every operation.
+//
+// Measured, and the reason is not theoretical: `security -i` reads one command
+// per LINE. An account containing a newline runs a second command — I stored an
+// item, then wrote an address whose newline carried a `delete-generic-password`
+// for it, and the item was gone. Whitespace and quotes reshape the token more
+// quietly.
+//
+// A 0x-prefixed name is a distinct item from the decoded name (measured: a
+// plain-text lookup does not find it), so this only works if EVERY operation
+// uses the same form. Write, read and delete all call hexArg — that consistency
+// is what makes it safe, and splitting it would lose slots rather than expose
+// them.
+function hexArg(value) {
+    return `0x${Buffer.from(value, 'utf8').toString('hex')}`;
+}
+const spawnRunner = ({ argv, stdin }) => new Promise((resolve, reject) => {
+    const child = spawn('security', argv, { stdio: ['pipe', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', (chunk) => (stderr += String(chunk)));
+    child.on('error', (err) => reject(new SecureStoreUnavailable(err.message)));
+    child.stdin.on('error', (err) => reject(new SecureStoreUnavailable(`could not write the command: ${err.message}`)));
+    child.on('close', (code) => {
+        // `security -i` reports an unknown command as 1 and a failing one as 44
+        // (measured), so a non-zero exit is the inner command failing and must
+        // not be reported as a save.
+        if (code === 0)
+            resolve();
+        else
+            reject(new SecureStoreUnavailable(stderr.trim() || `security exited ${code}`));
+    });
+    child.stdin.end(stdin);
+});
+let runner = spawnRunner;
+/** Test seam. Returns the previous runner so a caller can put it back. */
+export function setSecurityRunner(next) {
+    const previous = runner;
+    runner = next;
+    return previous;
+}
+export async function readSecret(account) {
+    requireDarwin();
+    assertAddressable(account);
+    try {
+        const { stdout } = await run('security', [
+            'find-generic-password',
+            '-a',
+            hexArg(account),
+            '-s',
+            hexArg(SERVICE),
+            '-w',
+        ]);
+        return stdout.trim();
+    }
+    catch (err) {
+        // `security` exits non-zero both for "no such item" and for a locked
+        // keychain. They are different answers — one means "make a slot", the
+        // other means "do not touch anything" — so the distinction is preserved
+        // rather than collapsed into null.
+        if (/could not be found/i.test(messageOf(err)))
+            return null;
+        throw new SecureStoreUnavailable(messageOf(err));
+    }
+}
+export async function deleteSecret(account) {
+    requireDarwin();
+    assertAddressable(account);
+    try {
+        await run('security', ['delete-generic-password', '-a', hexArg(account), '-s', hexArg(SERVICE)]);
+    }
+    catch (err) {
+        if (/could not be found/i.test(messageOf(err)))
+            return;
+        throw new SecureStoreUnavailable(messageOf(err));
+    }
+}
+export class SecureStoreUnavailable extends Error {
+    constructor(reason) {
+        super(`the OS secure store did not answer: ${reason}`);
+        this.name = 'SecureStoreUnavailable';
+    }
+}
+// A second line of defence, at the boundary rather than in the encoding.
+//
+// Hex already stops a newline from becoming another command — measured, and
+// the regression holds it. This refuses the shape outright, so a future change
+// that alters how names are encoded cannot quietly re-open the door, and so a
+// caller passing a control character learns it here rather than storing a slot
+// under a name nobody will reconstruct.
+function assertAddressable(account) {
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f]/.test(account)) {
+        throw new SecureStoreUnavailable('a secure-store account name cannot contain control characters');
+    }
+    if (account.length === 0) {
+        throw new SecureStoreUnavailable('a secure-store account name cannot be empty');
+    }
+}
+function requireDarwin() {
+    if (!platformTool()) {
+        throw new SecureStoreUnavailable(`no supported secure store on ${process.platform} (this build knows macOS only)`);
+    }
+}
+function messageOf(err) {
+    if (err && typeof err === 'object' && 'stderr' in err) {
+        const stderr = String(err.stderr ?? '').trim();
+        if (stderr)
+            return stderr;
+    }
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/src/shell-arg.js

@@ -0,0 +1,18 @@
+// Quote a value so a command we PRINT can be pasted and run as-is.
+//
+// Every place that shows someone a command is showing them something they will
+// select and paste. A team name is a string, not a shell token: it may contain
+// spaces, quotes, or metacharacters, and interpolating it raw turns a helpful
+// line into a different command than the one it appears to be. A display that
+// breaks on a space is worse than a placeholder, because it looks like it works.
+//
+// Lives here rather than beside one command because it was written twice — the
+// second copy was written by pasting the first, and a third would have been too.
+const BARE_ARG = /^[A-Za-z0-9._-]+$/u;
+export function shellArg(value) {
+    if (BARE_ARG.test(value))
+        return value;
+    // Single quotes stop every expansion; the only thing they cannot contain is a
+    // single quote, which is closed, escaped, and reopened.
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}

package/dist/src/slot-advice.js

@@ -0,0 +1,74 @@
+import { shellArg } from './shell-arg.js';
+/**
+ * Explain a slot that did not open, given the command that will now ask for the
+ * recovery key anyway.
+ *
+ * Every branch below ends the same way in practice — the run continues and the
+ * recovery key is typed. None of them is a dead end, which is the point: a
+ * machine with no secure store is not a machine that cannot back up.
+ */
+export function adviseOnSlot(result, ctx) {
+    if (result.ok)
+        return { tone: 'silent', lines: [] };
+    switch (result.reason) {
+        case 'no-slot':
+            // The first backup on this machine, or the first after a re-issuance.
+            // Worth one line, because the next sentence asks for the recovery key and
+            // the person deserves to know why this time and not next time.
+            return {
+                tone: 'note',
+                lines: [
+                    'this machine has no key slot for this vault yet, so the recovery key is needed once.',
+                ],
+            };
+        case 'no-store':
+            // Windows and Linux, every run. Stated as a property of the machine, not
+            // as a fault, and without advice — there is nothing to do about it.
+            return {
+                tone: 'note',
+                lines: [
+                    'this machine has no secure store, so the recovery key is needed for each backup.',
+                ],
+            };
+        case 'store-locked':
+            // The one the person can act on. The action is about later runs, not this
+            // one: this run proceeds with the recovery key either way, and saying
+            // "unlock and retry" as though it were required would be false.
+            return {
+                tone: 'note',
+                lines: [
+                    'this machine has a secure store but it refused: ' + result.detail,
+                    `unlock it and run \`agmsg-cloud recovery setup ${shellArg(ctx.team)}\` again to keep a key`,
+                    'slot, so later backups do not ask for the recovery key. This run continues without one.',
+                ],
+            };
+        case 'unusable':
+            // The only warning, and it is narrower than it first looks.
+            //
+            // A re-issued vault or another account does NOT arrive here: the store
+            // account name is built from (service, account, vault, generation), so
+            // those look up a different address and come back as `no-slot`. What
+            // reaches this branch is a slot at THIS address whose contents did not
+            // hold up — a shape this version does not wrap, or bytes whose tag failed.
+            // Naming re-issuance here would put another branch's cause on this one's
+            // warning, which is the blurring the four reasons exist to end
+            // (raised in review).
+            return {
+                tone: 'warning',
+                lines: [
+                    'this machine has a key slot for this vault and its contents did not hold up: ' +
+                        result.detail,
+                    'the stored slot was written by a different version of this tool, or it has been',
+                    'altered. It is not used. The recovery key is needed for this backup, and a fresh',
+                    'slot is kept once that succeeds.',
+                ],
+            };
+    }
+}
+/** Render advice for a terminal. Empty string when there is nothing to say. */
+export function renderSlotAdvice(advice) {
+    if (advice.lines.length === 0)
+        return '';
+    const prefix = advice.tone === 'warning' ? 'warning: ' : 'note: ';
+    return `${prefix}${advice.lines.join('\n  ')}\n`;
+}