approval-md 0.0.1 → 0.2.0

package/dist/src/cli/scaffold.js

@@ -0,0 +1,137 @@
+/**
+ * The bytes `approval init` scaffolds, and the one-line rationale for each.
+ *
+ * These constants live apart from both `init.ts` and `help.ts` because both
+ * need them: the verb writes them and the help text quotes them, and a help text
+ * that quoted a stale copy would be the second-worst kind of documentation — the
+ * confident kind. One definition, two readers, no cycle.
+ */
+/**
+ * SPEC.md §5.1's canonical example, byte for byte.
+ *
+ * This constant and `schema/fixtures/policy-md/valid/canonical.md` are the same
+ * bytes, and `tests/cli-init.test.ts` asserts it: the fixture is frozen (every
+ * policy-loading test descends from it) and the spec section it transcribes is
+ * what a reader compares the scaffolded file against. A copy that drifted from
+ * either would hand a new user a policy the documentation does not describe.
+ *
+ * It is embedded here rather than read from `schema/` because the published
+ * package ships the CLI and the spec, not the test fixtures, and a scaffolding
+ * verb that fails on an installed copy is a verb that only ever worked in this
+ * checkout.
+ *
+ * The closing sentence is not in SPEC.md §5.1's fence — it is the fixture's own
+ * trailing prose, kept because it says the one thing a first-time reader of this
+ * file needs to know: the prose is not the policy.
+ */
+export const CANONICAL_POLICY = `# Approval Policy
+
+Agents working in this project handle my life admin. Anything that leaves
+the machine gets declared, and the classes below say what I sign off on.
+
+\`\`\`yaml approval-policy
+version: "0.1"
+
+defaults:
+  autonomy: manual          # unknown/undeclared classes require sign-off
+  channel: telegram
+  approval_ttl: 24h         # pending requests expire
+  on_expiry: reject
+
+approvers:
+  alice:
+    channels: [telegram, cli]
+
+classes:
+  read.*:                       { autonomy: autonomous }
+  files.write.workspace:        { autonomy: autonomous }
+  calendar.write.own:           { autonomy: supervised }
+  communicate.email.draft:      { autonomy: autonomous }
+  communicate.email.external:
+    autonomy: manual
+    approvers: [alice]
+  financial.spend:
+    autonomy: manual
+    approvers: [alice]
+    limits: { per_action_usd: 25, daily_usd: 100 }
+  public.post:                  { autonomy: manual }
+  data.delete:                  { autonomy: manual }
+  account.auth:                 { autonomy: manual }
+
+budgets:
+  global: { daily_usd: 100, daily_actions: 200 }
+
+audit:
+  supervised_sample_rate: 0.10   # fraction of supervised actions escalated
+                                 # for retrospective human review
+
+channels:
+  telegram:
+    chat_id_env: APPROVAL_TG_CHAT
+    token_env: APPROVAL_TG_TOKEN
+  web:
+    port: 4680
+\`\`\`
+
+Everything after the block is prose again and is ignored by the parser.
+`;
+/**
+ * The comment the merged `.gitignore` lines live under.
+ *
+ * A marker rather than a bare append, so a second `init` can tell its own lines
+ * from the operator's and add only what is missing, and so a human reading the
+ * file knows which lines they are allowed to delete.
+ */
+export const GITIGNORE_MARKER = "# approval.md";
+/**
+ * The ignore lines, and why each one is there.
+ *
+ * - `.approval/*.sqlite` — the index is a projection (SPEC.md §9.2). It rebuilds
+ *   from the log with `approval reindex`; committing it would put a cache in the
+ *   history of the thing it caches.
+ * - `.approval/vault.enc` — the encrypted credential store (M7). Encrypted or
+ *   not, the vault is the one file in the layout whose contents are secrets, and
+ *   secrets do not go in a repository.
+ * - `.approval/env` — the environment source map (APRV-73). Usually it holds
+ *   only keychain service names, and it is ignored anyway: the format permits a
+ *   plaintext literal, an operator will eventually paste one in, and the day
+ *   they do must not be the day a bot token lands in a commit. Ignoring it also
+ *   states the intent — the environment is per-machine, not per-repository.
+ * - `.approval/keys/` — the per-request X25519 private keys of sealed token
+ *   delivery (APRV-105). Per-machine by construction: the whole design is that
+ *   the log, which IS shared, carries only ciphertext, and a key committed to a
+ *   shared history would hand every reader of that history the ability to open
+ *   an unspent token inside its TTL. Written whether or not a policy has opted
+ *   into `token_delivery: sealed`, because the line an operator needs is the one
+ *   that is already there on the day they turn the knob.
+ * - `.approval/**\/*.tmp-*` — the atomic-write temp files. Both writers that
+ *   rename into place (`channels/render-queue.ts`, `core/payload-store.ts`) name
+ *   their temp `.<basename>.tmp-<pid>-<counter>`, so this pattern is written to
+ *   match what those two actually produce, at both levels of the tree. A crashed
+ *   write leaves one behind; nobody should be asked to review it.
+ *
+ * - `.approval-journal/` — the ungated free-text channel of `approval journal`
+ *   (APRV-195). Ignored rather than tracked because it is not truth and not
+ *   evidence: the log is the record of what happened and it is committed, while
+ *   the journal is what an agent said about working here, which the operator
+ *   reads locally. Committing it would also turn an outlet into a publication,
+ *   and an agent writing for a public repository is an agent writing for an
+ *   audience — the pressure this channel exists to be free of. An operator who
+ *   wants the history keeps it by deleting the line.
+ *
+ * `.approval/log/` is deliberately absent: the log is the truth and belongs in
+ * the history. So is `.approval/payloads/`, which holds the bytes each approval
+ * bound to — evidence defaults to tracked, and the next steps `init` prints say
+ * so, along with the one line that reverses the choice.
+ */
+export const GITIGNORE_ENTRIES = [
+    ".approval/*.sqlite",
+    ".approval/vault.enc",
+    ".approval/env",
+    ".approval/keys/",
+    ".approval/**/*.tmp-*",
+    ".approval-journal/",
+];
+/** The same entries, indented for the help text so the two cannot disagree. */
+export const GITIGNORE_ENTRY_LINES = GITIGNORE_ENTRIES.join("\n                      ");
+//# sourceMappingURL=scaffold.js.map

package/dist/src/cli/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/cli/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkD/B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,eAAe,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAsB;IAClD,oBAAoB;IACpB,qBAAqB;IACrB,eAAe;IACf,iBAAiB;IACjB,sBAAsB;IACtB,oBAAoB;CACrB,CAAC;AAEF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC"}

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

@@ -0,0 +1,137 @@
+/**
+ * `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 type { CredentialSpec } from "../core/credential-spec.js";
+import type { CredentialProvider } from "../adapters/contract.js";
+import { probeSmtp } from "../adapters/smtp.js";
+import type { Streams } from "./main.js";
+import { type Prompter } from "./prompt.js";
+import { type HintContext, type SetupDeps } from "./setup-common.js";
+import { type VerifyOutcome } from "./setup-flow.js";
+/** What a verify hook is handed beyond the values: what the run actually did. */
+export interface VerifyContext {
+    written: readonly string[];
+    skipped: readonly string[];
+    streams: Streams;
+    prompter: Prompter;
+    probe: typeof probeSmtp;
+    /**
+     * The API root the AgentMail probe reads (APRV-223), or `undefined` for the
+     * public one. Threaded from `SetupDeps.apiBase`, which is how every other
+     * setup verb points a probe at a loopback fixture; there is no relaxation
+     * here to keep inside a test, because the probe is one HTTPS GET.
+     */
+    apiBase?: string | undefined;
+    /**
+     * The adapter's own credential provider, over the vault this run just wrote
+     * to (APRV-99). Lazy: a first run never opens it, because a first run holds
+     * everything already. A partial re-run opens it to probe the MERGED set, and
+     * that read is the one the adapter performs at send time, in this process,
+     * printed by nothing.
+     */
+    credentials: CredentialProvider;
+}
+/** One adapter, as this verb needs to see it. */
+export interface AdapterSetupEntry {
+    /** The manifest, declared by the adapter itself. */
+    specs: readonly CredentialSpec[];
+    /**
+     * The adapter's cross-field rule, or `undefined` when it has none. `kept`
+     * names the values already in the store that this run left alone (APRV-98):
+     * the flow never reads a value back, but presence is a fact it does know.
+     */
+    check?(values: Record<string, string>, kept: readonly string[]): string | null;
+    /** One line of what this adapter is, for the title. */
+    summary: string;
+    /**
+     * This adapter's own help, printed for `--help` and beside every usage error
+     * from here down (APRV-221). On the entry rather than in a `name === "email"`
+     * branch: an adapter's help is the adapter's, and a branch is a place for the
+     * next adapter's help to be forgotten.
+     */
+    help: string;
+    /** The non-interactive path: the exact `vault set` calls, generated. */
+    hint(context: HintContext): string;
+    /** Prove the stored configuration against the far end, sending nothing. */
+    verify(values: Record<string, string>, context: VerifyContext): Promise<VerifyOutcome>;
+    /** What to tell the operator to do next. */
+    nextSteps: readonly string[];
+}
+/** Every adapter this verb can configure. Keyed by the `adapter <name>` name. */
+export declare const ADAPTER_SETUPS: Record<string, AdapterSetupEntry>;
+/** The known names, sorted, for a usage error and for the help text. */
+export declare function knownAdapterNames(): string[];
+/**
+ * `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 declare function commandSetupAdapter(argv: string[], streams: Streams, cwd: string, deps?: SetupDeps): Promise<number>;