approval-md 0.0.1 → 0.2.0

package/dist/src/cli/setup-adapter.js

@@ -0,0 +1,509 @@
+/**
+ * `approval setup adapter <name>` — fill the vault for one adapter (APRV-78).
+ *
+ * SPEC.md §10.4 gives adapters an encrypted vault and `approval vault set` as
+ * the way in, and that verb is deliberately austere: one credential, one call,
+ * no prompt, the value from stdin or a named variable. It is the right shape
+ * for a script and the wrong shape for a person, who has to know that the email
+ * adapter wants five values, what each of them is called, which of them are
+ * secrets, that the port must be a port and the security setting one of three
+ * words, and that the user and the password are both-or-neither. All of that
+ * was written down only inside `adapters/email.ts`'s `act`, where nobody
+ * setting a machine up can read it.
+ *
+ * This verb reads the adapter's own manifest instead. The conversation is
+ * `cli/setup-flow.ts` and knows nothing about SMTP; the manifest is
+ * `EMAIL_CREDENTIAL_SPECS` and knows nothing about vaults or terminals; this
+ * file is the ten lines that join them, plus the two things that are genuinely
+ * about the pairing: what to do with the passphrase, and how to prove the
+ * result without sending anything.
+ *
+ * ## Where the values go, and where they do NOT
+ *
+ * **Into the vault, always.** Not the OS keystore, which is where `setup
+ * vault|sampling|channel <name>` put their secrets, and not `.approval/env`. The
+ * distinction is the one §10.4 draws: `.approval/env` holds what unlocks the
+ * machine (the human identity, the passphrase's source, the channel's token),
+ * and the vault holds what a gated adapter SPENDS inside a verified-token
+ * window. An SMTP password in `.approval/env` would be readable by
+ * `approval env` on demand, which is exactly the journey the vault exists to
+ * forbid.
+ *
+ * ## The passphrase is read, never established
+ *
+ * From the shell environment, under the name the policy declares, through
+ * {@link passphraseFrom} — and from nowhere else. **This verb never resolves
+ * `.approval/env` itself** (SPEC.md §11.1 invariant 7: no command loads that
+ * file implicitly, because a working-tree file any process read on its own
+ * would let anything able to write it act as you). It does READ the file, for
+ * one thing only: whether a line for the passphrase variable exists, which
+ * decides whether the refusal tells you to run `approval setup vault` or just
+ * to `eval "$(approval env)"`. A key's PRESENCE is not its value, and
+ * `planReplacements` has always read the file for exactly that.
+ *
+ * ## Verification sends nothing
+ *
+ * The proof is {@link probeSmtp}: the same session `sendMail` runs, up to and
+ * including AUTH, and then QUIT. It proves the host resolves, the port answers,
+ * the TLS mode is the one the server offers, and the credential is accepted. It
+ * does not prove a message would be delivered, and it puts no message on the
+ * wire — a setup verb that emailed somebody to prove itself would be a verb
+ * people run once and then avoid, which is `approval doctor`'s argument for
+ * calling `getMe` and nothing else.
+ *
+ * It is OFFERED, defaulting to YES, and a failure does not delete anything: the
+ * values stay, the refusal names the SMTP code and the server's first line
+ * (redacted), and the undo is printed as `approval vault remove <name>`. Values
+ * discarded by a wizard because a laptop was on a captive portal would be five
+ * more things to type.
+ *
+ * A PARTIAL RE-RUN is offered the same proof over the STORED set (APRV-99). It
+ * holds only what it just collected, so it reads the rest through
+ * {@link readEmailSmtpConfig} over a {@link vaultCredentialProvider}: the exact
+ * path `approval adapter email` takes at send time, in this process, printed by
+ * nothing. That is not a hole in "there is no verb that reads a credential
+ * out" — that rule is about what reaches a terminal, and nothing here does.
+ * Rotating an app password is the common case for this verb, and a probe no
+ * wider than the send it proves is the difference between a rotation you have
+ * checked and one you find out about from a bounce.
+ */
+import { envFilePathFor, readEnvFile } from "../core/env-file.js";
+import { passphraseEnvFor, passphraseFrom, vaultExists, vaultPathFor } from "../core/vault.js";
+import { DEFAULT_CREDENTIAL_NAMES, EMAIL_CREDENTIAL_SPECS, checkEmailCredentialSet, readEmailSmtpConfig, } from "../adapters/email.js";
+import { AGENTMAIL_CREDENTIAL_SPECS, AGENTMAIL_SEND_PERMISSIONS, DEFAULT_AGENTMAIL_CREDENTIAL_NAMES, probeAgentmail, readAgentmailConfig, } from "../adapters/agentmail.js";
+import { probeZzz, ZZZ_CREDENTIAL_SPECS, ZZZ_TOKEN_NAME, } from "../adapters/zzz.js";
+import { vaultCredentialProvider } from "../adapters/vault-provider.js";
+import { isSmtpSecurity, probeSmtp } from "../adapters/smtp.js";
+import { EXIT_OK } from "./exit-codes.js";
+import { SETUP_ADAPTER_AGENTMAIL_HELP, SETUP_ADAPTER_EMAIL_HELP, SETUP_ADAPTER_HELP, SETUP_ADAPTER_ZZZ_HELP, } from "./help.js";
+import { refusal as renderRefusal, style } from "./style.js";
+import { confirmUntil } from "./prompt.js";
+import { front, requireHuman, usageError, } from "./setup-common.js";
+import { runCredentialFlow, vaultDestination, } from "./setup-flow.js";
+/** The keystore read form for this machine, defaulting to the macOS one. */
+function readBackCommand(kind, item) {
+    return kind === "secret-service"
+        ? `secret-tool lookup approval ${item}`
+        : `security find-generic-password -a "$USER" -s ${item} -w`;
+}
+/**
+ * The scripted path, GENERATED FROM THE MANIFEST rather than written out.
+ *
+ * A hand-written hint is a list of five commands that has to be edited every
+ * time the manifest changes and will not be. Generating it means the refusal an
+ * operator copies is, by construction, the set of names the adapter actually
+ * reads.
+ *
+ * The secret's line takes its value from the keystore's own reader, so the
+ * password is never an argument on any line printed here — the rule the rest of
+ * `setup` follows, applied to a verb whose whole subject is credentials.
+ */
+function manifestHint(specs, context) {
+    const lines = [
+        `  # 1. establish the vault passphrase in ${context.passphraseEnv} and put it in this`,
+        `  #    shell. Every line below reads it from the environment and nowhere else:`,
+        `  approval setup vault --as human:<id>`,
+        `  eval "$(approval env)"`,
+        ``,
+        `  # 2. store each credential. The VALUE is never a command-line argument:`,
+        `  #    --value-env names a variable, and the variable is set for that one call.`,
+    ];
+    for (const spec of specs) {
+        const call = `approval vault set ${spec.name} --value-env V --as human:<id>`;
+        if (spec.kind === "secret") {
+            lines.push(`  V="$(${readBackCommand(context.kind, "<your-item>")})" \\`, `    ${call}`);
+        }
+        else {
+            const placeholder = spec.default ?? `<${spec.label.replace(/\s+/gu, "-")}>`;
+            lines.push(`  V='${placeholder}' ${call}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Replace every occurrence of each secret. Nothing leaves this file with one. */
+function redactor(secrets) {
+    const present = secrets.filter((secret) => secret.length > 0);
+    return (text) => {
+        let out = text;
+        for (const secret of present)
+            out = out.split(secret).join("<redacted>");
+        return out;
+    };
+}
+/** Today's refusal for a partial run, kept verbatim as the fallback (APRV-99). */
+function partialRefusal(skipped) {
+    return `\nnot verified: ${skipped.join(", ")} ${skipped.length === 1 ? "was" : "were"} left alone this run, so this verb does not hold the whole\nconfiguration, and it will not read the missing values back — there is no verb in\nthis CLI that reads a credential out of the vault. Re-run and replace all of them\nto probe the server.\n`;
+}
+/**
+ * The session itself, and the two sentences it can end with.
+ *
+ * Shared by the first-run path and the stored-configuration path (APRV-99) so
+ * that a probe reports the same way whichever set it ran over: an operator
+ * rotating an app password is owed the proof they get on day one, in the words
+ * they got it in. `undo` is the list of names this run stored, because the undo
+ * for a failed probe is removing what was just written and nothing else.
+ */
+async function probeAndReport(config, scrub, probe, undo) {
+    const result = await probe({
+        host: config.host,
+        port: config.port,
+        security: config.security,
+        ...(config.user === undefined ? {} : { user: config.user }),
+        ...(config.password === undefined ? {} : { password: config.password }),
+        tlsRejectUnauthorized: true,
+        redact: scrub,
+    });
+    if (result.ok) {
+        return {
+            ok: true,
+            detail: `\nverified: ${config.host}:${String(config.port)} answered over ${config.security}, ${result.authenticated === null
+                ? "with no login (neither a user nor a password is stored)"
+                : `and accepted the credential over AUTH ${result.authenticated}`}.\nNo message was sent: the session ran to AUTH and then QUIT.\n`,
+        };
+    }
+    const lines = undo.map((name) => `  approval vault remove ${name} --as human:<id>`).join("\n");
+    return {
+        ok: false,
+        // APRV-102: the one refusal shape, here too. A probe failure is the last
+        // thing this verb prints before the operator decides what to fix.
+        detail: `${renderRefusal(style(), result.code, scrub(result.message))}\n\nThe values ARE stored — a probe that failed because a laptop is behind a captive\nportal is not a reason to make you type five things again. Fix the server or the\nsetting and re-run this verb, or undo it by hand:\n\n${lines}\n`,
+    };
+}
+/**
+ * The partial re-run: offer to probe the configuration IN THE VAULT (APRV-99).
+ *
+ * This verb used to stop here, on the argument that it did not hold the whole
+ * configuration and that reading the rest back is the thing there is no verb
+ * for. The first half is true and the second half was the wrong inference.
+ * There is no verb that PRINTS a credential, and there still is not; but the
+ * email adapter reads all five out of the vault on every send, through
+ * {@link readEmailSmtpConfig} over a {@link vaultCredentialProvider}, and this
+ * function does exactly that and nothing more. The values are read into this
+ * process, handed to the same SMTP session `sendMail` opens, and dropped. No
+ * count, no prefix, no length, no value reaches a stream — the suite sweeps
+ * every captured byte for the fixture secrets on this path too. A probe that is
+ * no wider than the send it is proving does not widen the exposure; rotating an
+ * app password is the common case for this verb and it deserves the proof.
+ *
+ * When the vault will not open, or what it holds is not usable configuration,
+ * the answer is today's refusal verbatim plus one line naming why the probe
+ * could not run. The provider's sentences name the variable, the path and the
+ * credential NAME, never a value, and they are scrubbed with this run's own
+ * values before they are printed anyway.
+ */
+async function verifyStored(values, context) {
+    const refusal = partialRefusal(context.skipped);
+    const scrub = redactor(Object.values(values));
+    if (!confirmUntil(context.streams, context.prompter, `open an SMTP session using the stored configuration to check it?`, true)) {
+        return { ok: true, declined: true, detail: refusal };
+    }
+    const configured = readEmailSmtpConfig(context.credentials, DEFAULT_CREDENTIAL_NAMES);
+    if (!configured.ok) {
+        return {
+            ok: true,
+            declined: true,
+            detail: `${refusal}\nthe probe could not run: ${scrub(configured.message)}\n`,
+        };
+    }
+    return probeAndReport(configured.config, redactor([...Object.values(values), ...configured.secrets]), context.probe, context.written);
+}
+/**
+ * The email adapter's verification: one SMTP session that sends nothing.
+ *
+ * A run that collected the whole picture probes what it collected. A partial
+ * re-run hands off to {@link verifyStored}, which offers to probe what is in
+ * the vault, read the way the adapter reads it.
+ */
+async function verifyEmail(values, context) {
+    const names = DEFAULT_CREDENTIAL_NAMES;
+    if (context.skipped.length > 0)
+        return verifyStored(values, context);
+    const host = values[names.host];
+    const port = Number(values[names.port]);
+    const security = values[names.security];
+    if (host === undefined || !Number.isInteger(port) || !isSmtpSecurity(security)) {
+        return {
+            ok: true,
+            declined: true,
+            detail: `\nnot verified: the run did not collect ${names.host}, ${names.port} and ${names.security}\n`,
+        };
+    }
+    const user = values[names.user];
+    const password = values[names.password];
+    const scrub = redactor([user ?? "", password ?? ""]);
+    if (!context.prompter.confirm(`open an SMTP session to ${host}:${String(port)} to check it? Nothing is sent`, false)) {
+        return {
+            ok: true,
+            declined: true,
+            detail: `\nstored and unverified: no connection was made. \`approval doctor\` does not probe SMTP\neither; the first proof will be the first \`approval adapter email\` send.\n`,
+        };
+    }
+    return probeAndReport({
+        host,
+        port,
+        security: security,
+        ...(user === undefined ? {} : { user }),
+        ...(password === undefined ? {} : { password }),
+    }, scrub, context.probe, [names.host, names.port, names.security, names.user, names.password].filter((name) => values[name] !== undefined));
+}
+// ---------------------------------------------------------------------------
+// agentmail (APRV-223)
+// ---------------------------------------------------------------------------
+/**
+ * What the probe can say about the stored key's own permissions.
+ *
+ * Three answers and not two, because "not disclosed" is not "none". AgentMail
+ * keys carry `draft_send` and `message_send` as separate booleans and the whole
+ * deployment this adapter assumes rests on the vault's key holding both while
+ * the agent's key holds neither. The inbox read this probe already makes is the
+ * only call it will make: probing a second endpoint nobody has confirmed exists
+ * would turn its 404 into a permissions verdict, which is a worse answer than
+ * saying plainly that the check could not be made. So a run that learns nothing
+ * prints the reminder, and only a disclosure names a missing permission.
+ */
+function permissionsLine(disclosed) {
+    if (disclosed === null) {
+        return `AgentMail disclosed no permissions for this key here, so nothing was checked: the key you\njust stored must carry ${AGENTMAIL_SEND_PERMISSIONS.join(" and ")}, and the key your AGENT holds must not.`;
+    }
+    const missing = AGENTMAIL_SEND_PERMISSIONS.filter((name) => !disclosed.includes(name));
+    if (missing.length === 0) {
+        return `The key carries ${AGENTMAIL_SEND_PERMISSIONS.join(" and ")}, which is what a granted send spends.`;
+    }
+    return `WARNING: this key does not carry ${missing.join(" and ")}. \`approval adapter agentmail\`\nwill be refused agentmail-unauthorized at send time, AFTER a human has granted it.\nStore a key that can send, and leave the one without those permissions to the agent.`;
+}
+/**
+ * The AgentMail proof: `GET /v0/inboxes/{inbox_id}`, and nothing else.
+ *
+ * The same read `act` makes before every direct send, for the same two reasons:
+ * it establishes that the key opens this inbox, and it reports the address the
+ * inbox sends as, which is the address every approved message will actually
+ * come from. It puts no message anywhere.
+ */
+async function probeAgentmailAndReport(config, scrub, probe, apiBase, undo) {
+    const result = await probe(config, apiBase === undefined ? {} : { apiBase });
+    if (result.ok) {
+        return {
+            ok: true,
+            detail: `\nverified: the key opened the inbox ${config.inboxId}, which sends as ${result.address}.\nNo message was sent: the probe is one GET of the inbox.\n${permissionsLine(result.permissions)}\n`,
+        };
+    }
+    const lines = undo.map((name) => `  approval vault remove ${name} --as human:<id>`).join("\n");
+    return {
+        ok: false,
+        detail: `${renderRefusal(style(), result.code, scrub(result.message))}\n\nThe values ARE stored — a probe that failed because a laptop is behind a captive\nportal is not a reason to make you type them again. Fix the key or the inbox id\nand re-run this verb, or undo it by hand:\n\n${lines}\n`,
+    };
+}
+/**
+ * `setup adapter agentmail`'s verification.
+ *
+ * One shape for both runs, unlike the email adapter's: this manifest is two
+ * values, so a partial re-run is a rotation of the key with the inbox left
+ * alone, and the read that proves it is the same one either way. It goes
+ * through {@link readAgentmailConfig} over the vault whenever the run does not
+ * hold both values, which is the exact path `approval adapter agentmail` takes
+ * at send time and prints nothing.
+ */
+async function verifyAgentmail(values, context) {
+    const names = DEFAULT_AGENTMAIL_CREDENTIAL_NAMES;
+    const probe = probeAgentmail;
+    const scrub = redactor(Object.values(values));
+    if (!confirmUntil(context.streams, context.prompter, `read the inbox from AgentMail to check the key? Nothing is sent`, true)) {
+        return {
+            ok: true,
+            declined: true,
+            detail: `\nstored and unverified: no request was made. The first proof will be the first\n\`approval adapter agentmail\` send, which is a proof a human has already granted.\n`,
+        };
+    }
+    const inboxId = values[names.inboxId];
+    const apiKey = values[names.apiKey];
+    if (inboxId !== undefined && apiKey !== undefined) {
+        return probeAgentmailAndReport({ inboxId, apiKey }, scrub, probe, context.apiBase, context.written);
+    }
+    // A partial re-run: read what the vault holds, the way the adapter reads it.
+    const configured = readAgentmailConfig(context.credentials, names);
+    if (!configured.ok) {
+        return {
+            ok: true,
+            declined: true,
+            detail: `${partialRefusal(context.skipped)}\nthe probe could not run: ${scrub(configured.message)}\n`,
+        };
+    }
+    return probeAgentmailAndReport(configured.config, redactor([...Object.values(values), ...configured.secrets]), probe, context.apiBase, context.written);
+}
+async function verifyZzz(values, context) {
+    if (!confirmUntil(context.streams, context.prompter, "ask zzz.bot to authenticate the stored token with one read-only room-list request? Nothing is posted", true)) {
+        return { ok: true, declined: true, detail: "\nstored and unverified: no request was made.\n" };
+    }
+    const current = values[ZZZ_TOKEN_NAME] === undefined
+        ? context.credentials.get(ZZZ_TOKEN_NAME)
+        : { ok: true, value: values[ZZZ_TOKEN_NAME] };
+    if (!current.ok)
+        return { ok: false, detail: `${renderRefusal(style(), current.code, current.message)}\n` };
+    const result = await probeZzz(current.value, context.apiBase === undefined ? {} : { origins: { production: context.apiBase } });
+    if (result.ok) {
+        return {
+            ok: true,
+            detail: "\nverified: zzz.bot accepted the token on one read-only room-list request. No message was posted. This does not prove write scope, room membership, or private-room workflow evidence; those are checked by zzz.bot when the approved message is sent.\n",
+        };
+    }
+    return { ok: false, detail: `${renderRefusal(style(), result.code, result.message)}\nThe value remains stored; replace it or retry the probe after connectivity is restored.\n` };
+}
+/** Every adapter this verb can configure. Keyed by the `adapter <name>` name. */
+export const ADAPTER_SETUPS = {
+    email: {
+        specs: EMAIL_CREDENTIAL_SPECS,
+        check: (values, kept) => checkEmailCredentialSet(values, DEFAULT_CREDENTIAL_NAMES, kept),
+        summary: "the SMTP settings `approval adapter email` reads inside the verified execution window",
+        help: SETUP_ADAPTER_EMAIL_HELP,
+        hint: (context) => manifestHint(EMAIL_CREDENTIAL_SPECS, context),
+        verify: verifyEmail,
+        nextSteps: [
+            `Check the names (never the values) with:`,
+            ``,
+            `  approval vault list --as human:<id>`,
+            ``,
+            `The adapter reads them itself, inside the verified execution window; nothing else does.`,
+        ],
+    },
+    agentmail: {
+        specs: AGENTMAIL_CREDENTIAL_SPECS,
+        summary: "the AgentMail inbox and sending key `approval adapter agentmail` reads inside the verified execution window",
+        help: SETUP_ADAPTER_AGENTMAIL_HELP,
+        hint: (context) => manifestHint(AGENTMAIL_CREDENTIAL_SPECS, context),
+        verify: verifyAgentmail,
+        nextSteps: [
+            `Check the names (never the values) with:`,
+            ``,
+            `  approval vault list --as human:<id>`,
+            ``,
+            `The key stored here is the one that CAN send. Give the agent a different key,`,
+            `without ${AGENTMAIL_SEND_PERMISSIONS.join(" or ")}, in AGENTMAIL_API_KEY: that key composes`,
+            `drafts, and \`approval payload agentmail-draft\` snapshots one for a human to read.`,
+        ],
+    },
+    zzz: {
+        specs: ZZZ_CREDENTIAL_SPECS,
+        summary: "the invited zzz.bot agent token `approval adapter zzz` reads inside the verified execution window",
+        help: SETUP_ADAPTER_ZZZ_HELP,
+        hint: (context) => manifestHint(ZZZ_CREDENTIAL_SPECS, context),
+        verify: verifyZzz,
+        nextSteps: [
+            `Check the credential name (never its value) with:`,
+            ``,
+            `  approval vault list --as human:<id>`,
+            ``,
+            `Keep this write-capable token out of the agent environment. For a private room,`,
+            `zzz.bot also requires active membership and accepted approval.md workflow evidence.`,
+        ],
+    },
+};
+/** The known names, sorted, for a usage error and for the help text. */
+export function knownAdapterNames() {
+    return Object.keys(ADAPTER_SETUPS).sort();
+}
+// ---------------------------------------------------------------------------
+// The verb
+// ---------------------------------------------------------------------------
+/**
+ * The refusal for an unset passphrase.
+ *
+ * Two shapes, and the difference is a diagnosis: no vault file AND no line for
+ * the variable means nobody has ever established one, so the repair starts with
+ * `approval setup vault`. Anything else means the passphrase exists and this
+ * shell has not evaluated it, so the repair is one line. A verb that printed
+ * both every time would train the operator to skim past the one that mattered.
+ */
+function passphraseHint(variable, logPath, envPath) {
+    const file = readEnvFile(envPath);
+    // Reading the file for a KEY'S PRESENCE, never for a value, and never
+    // resolving it: SPEC.md §11.1 invariant 7 forbids the resolution, not the
+    // stat. An unreadable file is treated as "no line", which is the fail-closed
+    // reading: it produces the longer hint, never the shorter one.
+    const hasLine = file.ok && file.entries.some((entry) => entry.key === variable);
+    const established = hasLine || vaultExists(vaultPathFor(logPath));
+    return established
+        ? `The passphrase is recorded but not in this shell. Establish it with:\n\n  eval "$(approval env)"`
+        : `Nobody has established a vault passphrase here. Do that first, then evaluate it:\n\n  approval setup vault --as human:<id>\n  eval "$(approval env)"`;
+}
+/**
+ * `approval setup adapter <name>` — the interactive writer for one adapter's
+ * credentials. HUMAN-ONLY.
+ *
+ * `argv` starts at the adapter's name: `commandSetup` has already eaten
+ * `adapter`.
+ */
+export async function commandSetupAdapter(argv, streams, cwd, deps = {}) {
+    const json = argv.includes("--json");
+    const name = argv[0];
+    // The name is resolved BEFORE the terminal check, so that a typo is answered
+    // with "here are the adapters" rather than with a lecture about pipes.
+    if (name === "--help" || name === "-h" || name === "help") {
+        streams.out(`${SETUP_ADAPTER_HELP}\n`);
+        return EXIT_OK;
+    }
+    if (name === undefined || name.startsWith("-")) {
+        return usageError(streams, json, `missing <name> for \`approval setup adapter\`; known adapters: ${knownAdapterNames().join(", ")}`, SETUP_ADAPTER_HELP);
+    }
+    // Own keys only, for the reason `cli/adapter.ts` gives (APRV-223): every
+    // string names something on `Object.prototype` before it names an adapter.
+    const entry = Object.hasOwn(ADAPTER_SETUPS, name) ? ADAPTER_SETUPS[name] : undefined;
+    if (entry === undefined) {
+        return usageError(streams, json, `unknown adapter ${JSON.stringify(name)}; known adapters: ${knownAdapterNames().join(", ")}`, SETUP_ADAPTER_HELP);
+    }
+    // The adapter's own help, from the table entry the name resolved to: the
+    // generic SETUP_ADAPTER_HELP is for the errors that happen BEFORE a name
+    // resolves, and for nothing after this line.
+    const helpText = entry.help;
+    const outcome = front(`adapter ${name}`, argv.slice(1), streams, cwd, deps, helpText, (context) => entry.hint(context));
+    if (outcome.kind === "handled")
+        return outcome.code;
+    const context = outcome;
+    const extra = context.positionals[0];
+    if (extra !== undefined) {
+        return usageError(streams, false, `unexpected argument ${JSON.stringify(extra)}`, helpText);
+    }
+    const human = requireHuman(context.flags, streams, helpText, `adapter ${name}`);
+    if (!human.ok)
+        return human.code;
+    // The passphrase, from the SHELL environment under the policy's name. Never
+    // from `.approval/env` directly: §11.1 invariant 7.
+    const variable = passphraseEnvFor(context.load);
+    const passphrase = passphraseFrom(variable, deps.env ?? process.env);
+    if (passphrase === null) {
+        return usageError(streams, false, `${variable} is unset or empty: the vault passphrase is read from that environment variable and from nowhere else, and this verb creates nothing without it. Nothing was stored and no vault was created.\n\n${passphraseHint(variable, context.logPath, envFilePathFor(context.logPath))}`, helpText);
+    }
+    const vaultPath = vaultPathFor(context.logPath);
+    const probe = deps.probe ?? probeSmtp;
+    // The adapter's own reader over the same vault, for the partial-re-run probe
+    // (APRV-99). Built here and not in the hook so that this file keeps the one
+    // fact the hook has no business knowing: which file, and under which
+    // variable. Lazy, so a first run never opens it.
+    const credentials = deps.credentials ??
+        vaultCredentialProvider({ vaultPath }, { passphraseEnv: variable, env: deps.env ?? process.env });
+    const result = await runCredentialFlow({
+        streams,
+        prompter: context.prompter,
+        specs: entry.specs,
+        destination: vaultDestination(vaultPath, passphrase),
+        labels: {
+            title: `approval setup adapter ${name} — ${entry.summary}.`,
+            prereq: `The values go into the VAULT, not into the OS keystore and not into\n.approval/env: what this verb stores is what a gated adapter spends inside a\nverified-token window. Nothing here appends to the log or attests anything.`,
+            nextSteps: entry.nextSteps,
+        },
+        hooks: {
+            ...(entry.check === undefined ? {} : { check: entry.check }),
+            verify: (values, progress) => entry.verify(values, {
+                written: progress.written,
+                skipped: progress.skipped,
+                streams,
+                prompter: context.prompter,
+                probe,
+                ...(deps.apiBase === undefined ? {} : { apiBase: deps.apiBase }),
+                credentials,
+            }),
+        },
+    });
+    // The flow decided the code; this verb adds nothing to it.
+    return result.code;
+}
+//# sourceMappingURL=setup-adapter.js.map

package/dist/src/cli/setup-adapter.js.map

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

package/dist/src/cli/setup-channel.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `approval setup channel <name>` — configure one channel (APRV-79).
+ *
+ * SPEC.md §4 draws a line this verb's NAME now carries: a **channel** surfaces
+ * requests and collects decisions and holds no state; an **adapter** executes
+ * side effects and holds credentials. `approval setup adapter <name>` (APRV-78)
+ * fills the VAULT from an adapter's manifest. This verb fills the OS keystore
+ * and `.approval/env` from a channel's, because what a channel needs is not a
+ * credential an action spends inside a token window: it is the transport
+ * credential that lets the runtime ask a human anything at all.
+ *
+ * An older build spelled the Telegram one without the `channel` noun. That form
+ * is gone rather than aliased — the dispatch in `cli/setup.ts` answers it at
+ * exit 2 with the new one, in {@link RENAMED_NOTICE} — because two spellings of
+ * a distinction the SPEC draws on purpose is exactly how the distinction stops
+ * being drawn.
+ *
+ * ## What Telegram's flow keeps, unchanged
+ *
+ * The conversation is now `cli/setup-flow.ts`'s, the same one `setup adapter`
+ * runs, over the manifest `core/telegram-config.ts` declares. Everything that
+ * was a decision rather than a phrasing survives it, and each of these is
+ * asserted in `tests/cli-setup.test.ts`:
+ *
+ * - **`getMe` happens before anything is written.** It runs at the END of the
+ *   token's collection (step five of the flow), not after the write (step
+ *   seven), so a token the Bot API refuses costs the operator one line of
+ *   output and leaves `.approval/env` untouched. The chat discovery below it
+ *   also needs the bot's username, and asking `getMe` for it is the same call.
+ * - **No `getUpdates` from this verb carries an offset, ever.** An offset is an
+ *   ACKNOWLEDGEMENT: it tells the Bot API that everything below it may be
+ *   discarded, and a decision tap consumed here would never reach the listener
+ *   that was waiting for it. `allowed_updates` is `["message"]`, so a pending
+ *   `callback_query` is not even delivered to this process.
+ * - **The token is never typed into this process** on a machine with a
+ *   keystore: the helper's own no-echo prompt collects it and this runtime
+ *   learns it by reading the item back on stdout.
+ * - **The chat id is a literal.** A chat id is not a secret; the token is.
+ * - "send the bot a message", the 409 hint, the manual-curl refusal when nothing
+ *   arrives, and the optional send-a-test-message proof that defaults to NO.
+ *   What changed in APRV-96 is only WHEN the read happens: the verb long-polls
+ *   continuously until a message arrives or {@link DISCOVERY_DEADLINE_MS}
+ *   passes, instead of asking the operator to press Enter between reads.
+ *
+ * ## Where the two hooks sit, and why
+ *
+ * The flow asks its questions in one fixed order, and Telegram's shape falls
+ * out of it: the token is `collect`, because a human supplies it; the chat id is
+ * `discover`, because the SERVICE supplies it and the human's only part is
+ * sending a message and picking from what arrived. That is the hook APRV-78
+ * reserved and did not call. The proof is `verify`, which runs after the write —
+ * later than the old hand-rolled flow ran it, and correct in the same way the
+ * adapter's SMTP probe is: what is being proved is the stored configuration.
+ */
+import type { CredentialSpec } from "../core/credential-spec.js";
+import type { PolicyLoadResult } from "../core/policy-load.js";
+import type { Streams } from "./main.js";
+import { type Context, type HintContext, type SetupDeps } from "./setup-common.js";
+import { type FlowHooks } from "./setup-flow.js";
+/**
+ * The Telegram-only dependency, kept local to this file ON PURPOSE.
+ *
+ * `SetupDeps` is `setup-common.ts`'s, shared by every subcommand, and a
+ * discovery deadline is not something `setup vault` or `setup adapter email`
+ * has any meaning for. Tests inject a short one so the deadline path costs the
+ * suite milliseconds rather than a minute and a half; no operator has a reason
+ * to change it, so it is not a flag either.
+ */
+export interface ChannelSetupDeps extends SetupDeps {
+    /** The chat-discovery deadline in ms. {@link DISCOVERY_DEADLINE_MS} default. */
+    discoveryDeadlineMs?: number;
+}
+/**
+ * The refusal for the OLD spelling, as one constant on one line.
+ *
+ * One line and one identifier, because `tests/setup-rename.test.ts` sweeps
+ * `src/`, `docs/`, `examples/`, `README.md` and `SPEC.md` for the bare phrase
+ * and exempts exactly the lines that also name `RENAMED_NOTICE`. That is the
+ * whole exemption mechanism: a future line that reintroduces the old spelling
+ * cannot claim the exemption without saying this constant's name out loud.
+ */
+export declare const RENAMED_NOTICE = "`approval setup telegram` is now `approval setup channel telegram`, and there is no alias. A channel surfaces requests and collects decisions and holds no state; an adapter executes side effects and holds credentials. The two setup verbs fill different stores, so a channel's name belongs under `channel` (the OS keystore and .approval/env) and an adapter's under `adapter` (the vault)";
+/** One channel, as this verb needs to see it. Symmetric with ADAPTER_SETUPS. */
+export interface ChannelSetupEntry {
+    /** The manifest, declared by the channel itself, resolved against the policy. */
+    specs(load: PolicyLoadResult): readonly CredentialSpec[];
+    /** One line of what this channel is, for the title. */
+    summary: string;
+    /** The prerequisite paragraph, printed under the title. */
+    prereq: string;
+    /** The non-interactive path: the exact commands, generated. */
+    hint(context: HintContext): string;
+    /** The channel-specific conversation, as the flow's hooks. */
+    hooks(context: Context, deps: SetupDeps, streams: Streams, helpText: string): FlowHooks;
+    /** What to tell the operator to do next. */
+    nextSteps: readonly string[];
+    /** The per-channel help, for `--help` and for every refusal. */
+    help: string;
+}
+/** Every channel this verb can configure. Keyed by the `channel <name>` name. */
+export declare const CHANNEL_SETUPS: Record<string, ChannelSetupEntry>;
+/** The known names, sorted, for a usage error and for the help text. */
+export declare function knownChannelNames(): string[];
+/**
+ * `approval setup channel <name>` — the interactive writer for one channel's
+ * transport credentials. HUMAN-ONLY.
+ *
+ * The human-only gate is NEW in APRV-79. The Telegram help text had said
+ * HUMAN-ONLY since APRV-74 and nothing enforced it: the verb stores a bot
+ * credential and writes `.approval/env`, which is exactly what `vault` and
+ * `sampling` are gated for, and a help text that claims a control the code does
+ * not apply is worse than no claim at all.
+ *
+ * `argv` starts at the channel's name: `commandSetup` has already eaten
+ * `channel`.
+ */
+export declare function commandSetupChannel(argv: string[], streams: Streams, cwd: string, deps?: SetupDeps): Promise<number>;