approval-md 0.1.0 → 0.2.0

package/dist/src/adapters/env-passphrase.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The vault passphrase, resolved from `.approval/env` inside a granted window
+ * (SPEC.md §10.4, §5.2; APRV-168).
+ *
+ * ## Why this narrows a load-bearing rule, and how far
+ *
+ * `core/env-file.ts` states the rule this module bends, and states it as the
+ * reason the file exists at all: **no verb in this runtime reads `.approval/env`
+ * into its own environment.** The argument there is `APPROVAL_HUMAN`. A
+ * working-tree file that could set human identity would move SPEC.md §11's trust
+ * boundary from "the local machine" to "anyone who can write a file in the
+ * repository", and every agent that can edit source can write a file in the
+ * repository. So the file is inert, one verb resolves it, and a human evaluates
+ * that verb's output in their own shell.
+ *
+ * The narrowing here keeps every part of that argument intact:
+ *
+ * 1. **One variable, named by the policy.** What this module resolves is the
+ *    `vault.passphrase_env` variable and nothing else. It cannot be asked for
+ *    `APPROVAL_HUMAN`, so it cannot be used to claim an identity, attest a
+ *    policy, or grant a request. The whole human-only gate is untouched.
+ * 2. **One caller, inside a token window.** Reaching this function requires an
+ *    {@link ExecutionGrant}, which `adapters/contract.ts` mints and no other
+ *    module can construct: its brand is a `unique symbol` that is never
+ *    exported, so a call site outside the contract's execution path does not
+ *    type-check. A generic vault verb, `approval doctor`, `approval setup` and
+ *    every other caller of `vaultCredentialProvider` have no way to produce one,
+ *    which is the "no verb reads `.approval/env`" rule holding everywhere except
+ *    the one path named here.
+ *
+ *    The contract mints a grant in two phases and both are honoured, for a
+ *    reason worth stating: the credential resolution APRV-169 moved AHEAD of the
+ *    token spend runs in the `presented` phase, so a fallback that insisted on
+ *    `consumed` would refuse the very execution it exists to enable. A
+ *    `presented` grant is minted only when the caller's token matches the digest
+ *    the log's `approval.granted` recorded for this action, so it is still proof
+ *    that a human approved this action and that the caller holds the token that
+ *    approval minted. What it does not prove is that the token may still be
+ *    spent (TTL, revocation, single use), and it does not have to: those are
+ *    checked in `startExecution` before anything is appended, and no side effect
+ *    happens on the strength of this phase.
+ * 3. **The authority is the token, not the file.** A human looked at the
+ *    payload on their phone, tapped Approve, and a token was minted, delivered,
+ *    verified and consumed for exactly this action key and exactly these bytes.
+ *    The question this module answers is narrower than "may this process act":
+ *    that was already answered, by a person. It is "the action a human approved
+ *    is about to run, and the credential it needs is described in the
+ *    instance's own configuration; may the runtime read that description".
+ * 4. **Nothing is loaded into an environment.** The value is returned to the
+ *    vault provider and used to derive one key. It is never written to
+ *    `process.env`, never placed in an argv (`core/env-file.ts`'s helper
+ *    lookups already pass a service NAME and take the secret on stdout), never
+ *    logged, and never put in a message, a refusal, or a thrown error.
+ *
+ * What the demo case looks like, since it is the one that produced this task:
+ * the web-agent runner scrubs the agent child's environment of everything
+ * matching `APPROVAL|VAULT|TELEGRAM`, deliberately, because the server itself
+ * must hold no vault passphrase. The child then holds a granted token for one
+ * approved email and no way to open the vault that token is the key to. Before
+ * this module the only answers were to weaken the scrub or to send the mail by
+ * hand.
+ *
+ * ## What it does not defend
+ *
+ * Exactly what SPEC.md §10.4 and §11 already say the vault does not defend: a
+ * compromised host, and an agent that can read the passphrase. An agent that can
+ * read `.approval/env` and run the same helper lookups needs no adapter and no
+ * token; it decrypts the file directly. This module does not widen that
+ * exposure, because it reads what such an agent could already read. What it
+ * changes is that a process which holds a HUMAN'S GRANT and no passphrase can
+ * complete the action the human approved.
+ *
+ * Total and synchronous, like everything on the credential path: nothing here
+ * throws, and every failure is `null`. A `null` carries no detail on purpose;
+ * the caller's own refusal names the variable and the vault, and a diagnostic
+ * that quoted a keychain error would be the one string in this system that
+ * describes where a passphrase lives.
+ */
+import { type SourceRunner } from "../core/env-file.js";
+import type { ExecutionGrant } from "./contract.js";
+/**
+ * Resolve `variable` from the source map at `envFilePath`, under `grant`.
+ *
+ * Returns the value, or `null` for every other outcome: no grant, a `consumed`
+ * grant from a path where no token was spent, no file, a file this runtime will
+ * not read (wrong mode, unparseable), no line for this variable, an `env:` line
+ * (which asserts the value comes from the shell and resolves to nothing on its
+ * own), a helper that is missing or declined, or an empty result.
+ *
+ * Not re-exported anywhere. `adapters/vault-provider.ts` is its only caller, and
+ * `tests/vault-provider.test.ts` pins that.
+ */
+export declare function passphraseUnderGrant(grant: ExecutionGrant | null, envFilePath: string, variable: string, runner?: SourceRunner): string | null;

package/dist/src/adapters/public.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The supported adapter-author API.
+ *
+ * Keep this barrel deliberately small. Every name exported here is a package
+ * compatibility commitment; the surrounding adapter and core modules remain
+ * implementation details.
+ */
+export { ADAPTER_REFUSAL_CODES, CREDENTIAL_REFUSAL_CODES, executeThroughAdapter, type ActInput, type ActOutcome, type Adapter, type AdapterExecuteOptions, type AdapterExecuteRequest, type AdapterExecuteResult, type AdapterExecuteSuccess, type AdapterRefusal, type AdapterRefusalCode, type CredentialProvider, type CredentialRefusalCode, type CredentialResult, type ExecutionGrant, type JsonValue, type PrecheckInput, type PrecheckOutcome, } from "./contract.js";
+export { runAdapterConformance, type AdapterConformanceCase, type AdapterConformanceHarness, type ConformanceContext, } from "./conformance.js";
+export { vaultCredentialProvider, type VaultLocation, type VaultProviderOptions, } from "./vault-provider.js";
+export type { CredentialKind, CredentialSpec } from "../core/credential-spec.js";

package/dist/src/adapters/public.js

@@ -0,0 +1,11 @@
+/**
+ * The supported adapter-author API.
+ *
+ * Keep this barrel deliberately small. Every name exported here is a package
+ * compatibility commitment; the surrounding adapter and core modules remain
+ * implementation details.
+ */
+export { ADAPTER_REFUSAL_CODES, CREDENTIAL_REFUSAL_CODES, executeThroughAdapter, } from "./contract.js";
+export { runAdapterConformance, } from "./conformance.js";
+export { vaultCredentialProvider, } from "./vault-provider.js";
+//# sourceMappingURL=public.js.map

package/dist/src/adapters/public.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.js","sourceRoot":"","sources":["../../../src/adapters/public.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,GAiBtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,GAItB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,uBAAuB,GAGxB,MAAM,qBAAqB,CAAC"}

package/dist/src/adapters/registry.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The built-in adapters, keyed by the classes they serve (APRV-205).
+ *
+ * One question is asked of this module and one only: **which credential names
+ * did the adapters for this class declare they cannot act without?** `approval
+ * run` asks it before it spawns, because those names are the ones the scrub in
+ * `core/child-env.ts` lets through into the child's environment; everything
+ * else under the credential-bearing prefixes is withheld.
+ *
+ * The declaration is the adapter's own, static, and reached through no flag.
+ * That is the point: a caller-supplied list of variables to keep would be a
+ * caller-supplied way to get the token back, which is the hole this task
+ * closes rather than a feature of the fix. {@link declaredCredentialsForClass}
+ * therefore takes a class and nothing else, and reads {@link builtInAdapters}
+ * and nothing else.
+ *
+ * The list is deliberately tiny and deliberately here rather than in
+ * `src/core/`: core does not know about adapters and must not learn, so the
+ * lookup lives beside the adapters and the CLI does the joining.
+ *
+ * This roster is the build's answer to "which adapters exist". The CLI's own
+ * adapter table (`cli/adapter.ts`) answers a different question, "which
+ * adapters have a verb", and the two are kept side by side on purpose: an
+ * adapter with no CLI face still declares credentials, and this module must
+ * not depend on the CLI to know that.
+ */
+import type { Adapter } from "./contract.js";
+/**
+ * Every adapter this build ships. Since APRV-223 that is two, and both serve
+ * `communicate.email.external`: the union of their declared names is what the
+ * scrub lets through, which is the honest superset {@link
+ * unionRequiredCredentials} was written for rather than a collision to resolve.
+ *
+ * Constructed with defaults: the question asked
+ * here is about DECLARED names, and no default answers it differently from a
+ * configured instance except by renaming vault entries, which is a deployment's
+ * own business and not a reason to open a socket at lookup time.
+ */
+export declare function builtInAdapters(): readonly Adapter[];
+/**
+ * The credential names declared by `adapters` serving `cls`, deduplicated and
+ * in roster order.
+ *
+ * Every adapter that serves the class contributes, because "which adapter would
+ * have run this" is a question with no answer at this point in the flow, and
+ * the union of two adapters' declarations is the honest superset. Two adapters
+ * may serve one class, and when they do the scrub lets both sets of names
+ * through rather than guessing between them.
+ *
+ * Pure, and separated from {@link declaredCredentialsForClass} so the union can
+ * be tested over more adapters than a build happens to ship. It is not a seam
+ * for enforcement: nothing outside a test passes it a roster.
+ */
+export declare function unionRequiredCredentials(adapters: readonly Adapter[], cls: string): readonly string[];
+/**
+ * The credential names declared by the built-in adapters serving `cls`, or an
+ * empty list when no adapter serves it.
+ */
+export declare function declaredCredentialsForClass(cls: string): readonly string[];

package/dist/src/adapters/registry.js

@@ -26,6 +26,7 @@
  */
 import { agentmailAdapter } from "./agentmail.js";
 import { emailAdapter } from "./email.js";
+import { zzzAdapter } from "./zzz.js";
 /**
  * Every adapter this build ships. Since APRV-223 that is two, and both serve
  * `communicate.email.external`: the union of their declared names is what the
@@ -38,7 +39,7 @@ import { emailAdapter } from "./email.js";
  * own business and not a reason to open a socket at lookup time.
  */
 export function builtInAdapters() {
-    return [emailAdapter(), agentmailAdapter()];
+    return [emailAdapter(), agentmailAdapter(), zzzAdapter()];
 }
 /**
  * The credential names declared by `adapters` serving `cls`, deduplicated and

package/dist/src/adapters/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/adapters/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,CAAC,YAAY,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAA4B,EAC5B,GAAW;IAEX,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,SAAS;QAC7C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,mBAAmB,IAAI,EAAE,EAAE,CAAC;YACrD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAAW;IACrD,OAAO,wBAAwB,CAAC,eAAe,EAAE,EAAE,GAAG,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/adapters/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,CAAC,YAAY,EAAE,EAAE,gBAAgB,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAA4B,EAC5B,GAAW;IAEX,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,SAAS;QAC7C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,mBAAmB,IAAI,EAAE,EAAE,CAAC;YACrD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAAW;IACrD,OAAO,wBAAwB,CAAC,eAAe,EAAE,EAAE,GAAG,CAAC,CAAC;AAC1D,CAAC"}

package/dist/src/adapters/smtp.d.ts

@@ -0,0 +1,213 @@
+/**
+ * A minimal SMTP client, for the email adapter and nothing else (APRV-69).
+ *
+ * ## Why this exists rather than a dependency
+ *
+ * `CLAUDE.md` and SPEC.md §14 both put minimal dependencies among this
+ * repository's invariants, and a mail library is a large surface to take on for
+ * one send: nodemailer pulls a templating layer, an attachment pipeline, a DKIM
+ * signer, OAuth2 token refresh, and a plugin system, all of it running inside
+ * the one call this project spends its whole design protecting. What is actually
+ * needed is RFC 5321's client half of a single transaction — greeting, EHLO,
+ * optionally STARTTLS, optionally AUTH, MAIL FROM, RCPT TO, DATA, QUIT — which
+ * is this file. `node:net` and `node:tls` and nothing else.
+ *
+ * ## What it deliberately does not do
+ *
+ * No connection pooling, no pipelining, no CHUNKING/BDAT, no SMTPUTF8, no DSN,
+ * no retry. One transaction per {@link sendMail} call, one message per
+ * transaction, and a failure is reported rather than retried: a retry inside an
+ * adapter would be a second side effect under one consumed token, and deciding
+ * to send again is a decision the gate exists to make.
+ *
+ * ## The probe, and the limit of what it proves
+ *
+ * {@link probeSmtp} runs the same session as {@link sendMail} up to and
+ * including AUTH, then says QUIT. It is the same code, one call away
+ * (`runSession` with no envelope), because a setup check that exercises a
+ * different client than the send does is a check that can pass while the send
+ * fails.
+ *
+ * A successful probe proves three things and no more: the host and port accept
+ * a connection, the requested transport security (implicit TLS, or the STARTTLS
+ * upgrade, with the same no-downgrade rule the send obeys) was actually
+ * established, and this server accepts this credential.
+ *
+ * It does **not** prove that a message would be accepted. MAIL FROM, RCPT TO
+ * and DATA are never issued, so nothing about the server's sender policy, its
+ * relaying rules, its recipient validation, its size limits or its content
+ * filtering is exercised. A probe that succeeds against a server which will
+ * later refuse `MAIL FROM:<…>` with a 550 is a probe behaving correctly. Any
+ * caller reporting the result to an operator (`setup adapter email` says
+ * "verified") owes them that distinction: the transport and the login are
+ * verified, the delivery is not.
+ *
+ * ## Failure vocabulary
+ *
+ * Everything is reported, nothing is thrown out of {@link sendMail}. Two
+ * families:
+ *
+ * - the transport codes in {@link SMTP_TRANSPORT_FAILURE_CODES}, which are a
+ *   frozen, additive union (SPEC.md §11.1(6)); and
+ * - a reply-code family, `smtp-<NNN>`, minted from the server's own three-digit
+ *   reply whenever the far side refuses a verb. It is a family rather than an
+ *   enumeration because RFC 5321 lets a server answer with codes this repository
+ *   cannot list in advance, and collapsing "mailbox unavailable" and
+ *   "authentication failed" into one local name would throw away the one piece
+ *   of information an operator needs. {@link SMTP_REPLY_CODE_PATTERN} pins the
+ *   shape.
+ *
+ * ## What may appear in a failure message
+ *
+ * The verb, the reply code, and **the first line of the server's reply text**.
+ * Not the whole reply: a multi-line refusal can run to a screen of banner text,
+ * and everything after the first line is the server explaining itself to a human
+ * rather than telling the client what happened. Not the command: an `AUTH PLAIN
+ * <base64>` echoed into a diagnostic would publish the credential in the one
+ * string the adapter's caller is most likely to print.
+ *
+ * And even the first line is passed through {@link SmtpTransportOptions.redact}
+ * before it is returned, because a server is entitled to quote back the username
+ * it just refused ("535 5.7.8 authentication failed for bot@example.com"), and a
+ * deployment whose username IS the credential would otherwise leak it through a
+ * channel the adapter contract's own guard also covers but which this module
+ * should not be relying on. Two independent scrubs, by design.
+ *
+ * Deterministic apart from the network and the clock it does not read: no
+ * randomness, no ambient configuration, no environment reads.
+ */
+/** How the connection is protected. */
+export type SmtpSecurity = 
+/** TLS from the first byte (the submissions port, 465). */
+"implicit"
+/** Plaintext, then a mandatory STARTTLS upgrade (the submission port, 587). */
+ | "starttls"
+/**
+ * Plaintext, and it stays that way. Only sane for a relay on the same host;
+ * the adapter refuses to AUTH over it, because a password on a cleartext
+ * socket is a password on the wire.
+ */
+ | "none";
+export declare function isSmtpSecurity(value: unknown): value is SmtpSecurity;
+/**
+ * Transport failures this client can report. Frozen union, additive only
+ * (SPEC.md §11.1(6)).
+ *
+ * They are distinguished because they call for four different responses: fix
+ * the address, fix the TLS configuration, look at why the far side is slow, and
+ * report a server that is not speaking SMTP.
+ */
+export declare const SMTP_TRANSPORT_FAILURE_CODES: readonly [
+/** The TCP connection could not be established at all. */
+"smtp-connect-failed", 
+/** TLS could not be established, or the server would not offer STARTTLS. */
+"smtp-tls-failed", 
+/** The session exceeded its whole-transaction budget. */
+"smtp-timeout", 
+/** The far side sent something that is not an SMTP reply, or hung up. */
+"smtp-protocol-error"];
+export type SmtpTransportFailureCode = (typeof SMTP_TRANSPORT_FAILURE_CODES)[number];
+/** The shape of a minted reply-code failure: `smtp-` and three digits. */
+export declare const SMTP_REPLY_CODE_PATTERN: RegExp;
+/** The default whole-session budget, in milliseconds. */
+export declare const DEFAULT_SMTP_TIMEOUT_MS = 30000;
+/** A parsed SMTP reply. `lines` holds the text of each line, code stripped. */
+export interface SmtpReply {
+    code: number;
+    lines: string[];
+    /** The first line's text, which is the only part any message may quote. */
+    first: string;
+}
+export interface SmtpTransportOptions {
+    host: string;
+    port: number;
+    security: SmtpSecurity;
+    /** Omitted (or empty) means the session does not authenticate. */
+    user?: string;
+    password?: string;
+    /** Whole-session budget. Exceeding it is `smtp-timeout`. */
+    timeoutMs?: number;
+    /** The name this client gives in EHLO. */
+    clientName?: string;
+    /**
+     * TLS certificate verification. **Defaults to `true`, and production must
+     * leave it there.** The only sanctioned `false` is a test against a mock on
+     * 127.0.0.1 holding a self-signed fixture certificate.
+     */
+    tlsRejectUnauthorized?: boolean;
+    /** Applied to every string this module returns. See the module header. */
+    redact?(text: string): string;
+}
+/** The SMTP envelope, which is not the message's headers. */
+export interface SmtpEnvelope {
+    /** MAIL FROM. The return path, not necessarily the From: header. */
+    from: string;
+    /** RCPT TO, once each: To, Cc, and **Bcc**, which appear in no header. */
+    recipients: readonly string[];
+}
+export type SmtpSendResult = {
+    ok: true;
+    /** The reply to the end-of-data terminator: the server accepting it. */
+    reply: {
+        code: number;
+        text: string;
+    };
+    /** `VERB code` for each step, in order. Never a command argument. */
+    transcript: string[];
+    /** Was the message handed over on an encrypted socket? */
+    secure: boolean;
+    /** Did the session authenticate, and with which mechanism? */
+    authenticated: "PLAIN" | "LOGIN" | null;
+} | {
+    ok: false;
+    code: SmtpTransportFailureCode | `smtp-${number}`;
+    message: string;
+    transcript: string[];
+    secure: boolean;
+};
+/**
+ * What {@link probeSmtp} reports: {@link SmtpSendResult} without `reply`, since
+ * a probe never issues a verb whose reply is anything but a step of the
+ * session. The failure codes are the same union, from the same code path.
+ */
+export type SmtpProbeResult = {
+    ok: true;
+    /** `VERB code` for each step, in order. Never a command argument. */
+    transcript: string[];
+    /** Was the session encrypted when it ended? */
+    secure: boolean;
+    /** Did the session authenticate, and with which mechanism? */
+    authenticated: "PLAIN" | "LOGIN" | null;
+} | {
+    ok: false;
+    code: SmtpTransportFailureCode | `smtp-${number}`;
+    message: string;
+    transcript: string[];
+    secure: boolean;
+};
+/**
+ * Run one SMTP transaction and report how it went. Never throws.
+ *
+ * The whole of it is {@link runSession}; this is the entry point that supplies
+ * an envelope and a message, and its result is unchanged from the day it was
+ * the whole function.
+ */
+export declare function sendMail(options: SmtpTransportOptions, envelope: SmtpEnvelope, message: string): Promise<SmtpSendResult>;
+/**
+ * Open a session, authenticate, send nothing, and report. Never throws.
+ *
+ * Exactly {@link sendMail}'s session up to AUTH — the same connection, the same
+ * STARTTLS rules including the no-downgrade refusal and the response-injection
+ * guard, the same refusal to put a password on a cleartext socket, the same
+ * one-session budget, the same redaction of every string it returns — and then
+ * QUIT. See this module's header for what a success does and does not prove:
+ * transport, TLS mode and credential, never that a message would be delivered.
+ */
+export declare function probeSmtp(options: SmtpTransportOptions): Promise<SmtpProbeResult>;
+/**
+ * RFC 5321 §4.5.2: a line of the message that begins with `.` gets a second
+ * one, so the terminator cannot be forged by the message's own content. The
+ * terminating `.` line is NOT added here; {@link sendMail} sends it as its own
+ * command so the transcript records the reply to it.
+ */
+export declare function dotStuff(message: string): string;

package/dist/src/adapters/vault-provider.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The vault as a {@link CredentialProvider} (SPEC.md §10.4; APRV-68).
+ *
+ * `adapters/contract.ts` left one seam open and named the task that would fill
+ * it: "No vault. {@link CredentialProvider} is the seam a real vault implements
+ * (APRV-68)." This module is that implementation, and it is deliberately thin.
+ * Everything about *when* a credential may be read belongs to the contract;
+ * everything about *how* the bytes are stored belongs to `core/vault.ts`. What
+ * is left here is the translation between the two vocabularies.
+ *
+ * ## The structural rule
+ *
+ * A provider built here is only ever handed to
+ * {@link executeThroughAdapter} through {@link AdapterExecuteOptions.credentials}.
+ * The contract wraps it in a window that closes the instant `act` returns, so
+ * every read during `act` is inside a verified execution. Manual and selected
+ * live paths consume a token; explicitly authorized supervised or autonomous
+ * paths do not. Three things hold that rule up, and none is a convention:
+ *
+ * 1. `core/vault.ts` exports exactly one function that returns a credential
+ *    value (`getCredential`), and this module is its only caller in the
+ *    repository. `tests/vault.test.ts` pins both halves.
+ * 2. There is no CLI verb that prints a value. `approval vault` can set, list
+ *    (names), and remove; it cannot show. See `src/cli/vault.ts`.
+ * 3. The contract scans everything an adapter returns for the values the
+ *    provider handed out and redacts them, so a leak by a careless adapter is
+ *    caught mechanically rather than reviewed for.
+ *
+ * ## What this defends, and what it does not
+ *
+ * Exactly what the vault module's own threat model says, restated because a
+ * reader arriving from the adapter side deserves it here too. **Defended:**
+ * credentials at rest, and casual reads by an agent that can read files in the
+ * working tree — the ciphertext hides the names as well as the values.
+ * **Not defended (SPEC.md §11, plainly):** a compromised host, and an agent that
+ * can read the passphrase environment variable. Such an agent does not need this
+ * provider; it can decrypt the file directly. The vault raises the cost of a
+ * leak from reading a file to owning the session, and claims nothing beyond
+ * that.
+ *
+ * Total and synchronous, as {@link CredentialProvider} requires: nothing here
+ * throws, nothing blocks on a human, and every failure is one of the three
+ * {@link CREDENTIAL_REFUSAL_CODES}.
+ */
+import { type SourceRunner } from "../core/env-file.js";
+import type { CredentialProvider } from "./contract.js";
+/**
+ * How to reach the vault. Either the vault file directly, or the log path the
+ * convention derives it from — never both, so there is one answer to "which
+ * file".
+ */
+export type VaultLocation = {
+    vaultPath: string;
+} | {
+    logPath: string;
+};
+export interface VaultProviderOptions {
+    /**
+     * The NAME of the environment variable holding the passphrase. Callers get
+     * this from `passphraseEnvFor(loadPolicy(...))`, so the policy's declaration
+     * is honoured and the default applies when it declares nothing.
+     */
+    passphraseEnv: string;
+    /** Injectable for tests. Defaults to this process's environment. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The instance's `.approval/env`, enabling the scoped passphrase fallback
+     * (APRV-168). Absent, and the provider behaves exactly as it always did:
+     * the passphrase comes from the environment or it comes from nowhere.
+     *
+     * Supplied by `approval adapter <name>`, which executes through the contract
+     * and therefore inside a consumed-token window. It is deliberately NOT
+     * supplied by `approval setup adapter <name>`, `approval vault`, or anything
+     * else: those hold no token, so the fallback would have no authority behind
+     * it. See `adapters/env-passphrase.ts` for the whole argument.
+     */
+    envFilePath?: string;
+    /** The keychain / secret-service seam, injectable exactly as it is there. */
+    sourceRunner?: SourceRunner;
+}
+/**
+ * A provider that answers from the encrypted vault.
+ *
+ * **Lazy, and cached for the life of the provider.** The vault is not opened
+ * until an adapter actually asks for something, so an execution that needs no
+ * credential pays no scrypt cost and touches no ciphertext. Once opened, the
+ * derived value for a name is remembered, because a provider's life *is* one
+ * `act` call: the contract closes it when `act` returns, so the cache cannot
+ * outlive the token window it was built for, and the alternative — a fresh
+ * ~100 ms key derivation per credential — would put a visible tax on an adapter
+ * that needs two.
+ *
+ * The passphrase is read from the environment on every open rather than
+ * captured at construction, so a provider built before the operator exported the
+ * variable is not permanently poisoned.
+ *
+ * **The scoped fallback (APRV-168).** When {@link VaultProviderOptions.envFilePath}
+ * is supplied AND the contract has told this provider it is inside a token
+ * window, a passphrase absent from the environment is resolved from the
+ * instance's `.approval/env` instead. That is the one narrowing of
+ * `core/env-file.ts`'s "no verb reads this file" rule, and the whole argument
+ * for it lives in `adapters/env-passphrase.ts`. The short form: the authority is
+ * the token, and a human tapped Approve for exactly this action. The value is
+ * used to derive one key and reaches no environment, no argv, no log, and no
+ * message; the cache is dropped when the window closes, so a passphrase resolved
+ * under one grant opens nothing under the next.
+ *
+ * Messages name the environment VARIABLE and the credential NAME, and never a
+ * value: an adapter's failure message is one of the strings the contract hands
+ * back to a caller, and a diagnostic that quoted the secret would defeat the
+ * redaction guard by putting the secret in the one place the guard cannot know
+ * to look for it.
+ */
+export declare function vaultCredentialProvider(location: VaultLocation, options: VaultProviderOptions): CredentialProvider;

package/dist/src/adapters/vault-provider.js

@@ -13,9 +13,9 @@
  * A provider built here is only ever handed to
  * {@link executeThroughAdapter} through {@link AdapterExecuteOptions.credentials}.
  * The contract wraps it in a window that closes the instant `act` returns, so
- * every read is inside a verified, consumed, single-use token — which is what
- * SPEC.md §10.4 means by "the credentials only answer to tokens". Three things
- * hold that rule up, and none of them is a convention:
+ * every read during `act` is inside a verified execution. Manual and selected
+ * live paths consume a token; explicitly authorized supervised or autonomous
+ * paths do not. Three things hold that rule up, and none is a convention:
  *
  * 1. `core/vault.ts` exports exactly one function that returns a credential
  *    value (`getCredential`), and this module is its only caller in the

package/dist/src/adapters/zzz.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Credential-custody transport for zzz.bot messages (APRV-320).
+ *
+ * The adapter sends only the JSON value a grant binds. Destination selection
+ * is a strict tagged union over two fixed service origins; neither the CLI nor
+ * the payload can supply an arbitrary URL. The Bearer credential comes only
+ * from the scoped provider opened by the shared adapter contract.
+ */
+import type { CredentialSpec } from "../core/credential-spec.js";
+import { type Adapter, type JsonValue } from "./contract.js";
+export declare const ZZZ_CLASS = "communicate.zzz.external";
+export declare const ZZZ_PRODUCTION_API_BASE = "https://zzz.bot";
+export declare const ZZZ_PREVIEW_API_BASE = "https://zzz-preview.soycarts.workers.dev";
+export declare const ZZZ_DEFAULT_TIMEOUT_MS = 15000;
+export declare const ZZZ_TOKEN_NAME = "zzz.agent_token";
+export declare const ZZZ_FAILURE_CODES: readonly ["zzz-payload-invalid", "zzz-config-invalid", "zzz-invalid-request", "zzz-unauthorized", "zzz-forbidden", "zzz-not-found", "zzz-idempotency-conflict", "zzz-payload-too-large", "zzz-rejected", "zzz-rate-limited", "zzz-unreachable", "zzz-cancelled", "credential-unavailable", "credential-refused", "credential-window-closed"];
+export declare const ZZZ_CREDENTIAL_SPECS: readonly CredentialSpec[];
+type Reference = {
+    kind: "external" | "post";
+    target: string;
+    label: string;
+    relationship: "source" | "context" | "supersedes";
+};
+type Message = {
+    body: string;
+    metadata?: JsonValue;
+    tags?: string[];
+    references?: Reference[];
+};
+export type ZzzPayload = ({
+    environment: "production" | "preview";
+    operation: "create_thread";
+    room_id: string;
+    title: string;
+} & Message) | ({
+    environment: "production" | "preview";
+    operation: "create_reply";
+    thread_id: string;
+} & Message);
+type Validation = {
+    ok: true;
+    payload: ZzzPayload;
+    path: string;
+    body: Record<string, JsonValue>;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function validateZzzPayload(value: JsonValue): Validation;
+export interface ZzzAdapterOptions {
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    /** Constructor-only test seam. The CLI never exposes these values. */
+    origins?: Partial<Record<"production" | "preview", string>>;
+}
+export declare function zzzAdapter(options?: ZzzAdapterOptions): Adapter;
+export type ZzzProbeResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/** Read-only authentication probe. It proves no write scope or room access. */
+export declare function probeZzz(token: string, options?: ZzzAdapterOptions): Promise<ZzzProbeResult>;
+export {};