approval-md 0.3.0 → 0.4.1

package/dist/src/cli/channel-relay.js

@@ -0,0 +1,334 @@
+/**
+ * `approval channel relay` — gestures an operator's authenticated relay
+ * carries (SPEC.md §10.3, APRV-455).
+ *
+ * The third arrival of a human gesture, beside a Telegram tap and a terminal.
+ * An operator's control plane holds an EdgeOS session for the person, shows
+ * them a request or their policy, and posts what they did here: the gesture,
+ * the EdgeOS `/humans/me` id of the session that made it, the hash or the key
+ * it answers, and a nonce. `channels/relay-server.ts` authenticates the post
+ * and `channels/relay.ts` turns it into a log event through the one function a
+ * Telegram tap goes through. This file resolves configuration, refuses what it
+ * must refuse, binds a port and reports; it decides nothing.
+ *
+ * ## The refusals that are the point
+ *
+ * 1. **The secret comes from the launch environment, never from the tree.**
+ *    `APPROVAL_RELAY_SECRET`, refused when unset, when shorter than a value a
+ *    host would generate, and when it holds a character a header cannot carry
+ *    unambiguously (SPEC.md §11.1 invariant 7). It is a conventional name,
+ *    beside `APPROVAL_TG_WEBHOOK_SECRET`, for that variable's reason: the
+ *    policy decides WHETHER a channel exists, never the value that
+ *    authenticates it, and a second declaration would be a second place for
+ *    one fact to be wrong. Under the `APPROVAL_` prefix it is withheld from
+ *    every child `approval run` spawns (`core/child-env.ts`), and the hook
+ *    classifier holds this command line `policy.core`, so an agent session
+ *    cannot start a relay with a secret of its own.
+ * 2. **No human identity.** This verb takes no `--as` and reads no
+ *    `APPROVAL_HUMAN`. Every gesture is attributed to the account the attested
+ *    policy maps, or refused `sender-unmapped`.
+ * 3. **A post without the secret decides nothing and appends nothing.**
+ *
+ * ## Why there is no transport lease
+ *
+ * A Telegram bot admits one receiver, so its transports take a lease. A relay
+ * has no such constraint: two relays on one gate would each record through
+ * compare-and-append, the gate would answer a duplicate decision
+ * `already-decided`, and the nonce ledger is a directory of exclusively linked files that
+ * refuses a replay whichever relay it reaches. A second relay on the SAME port
+ * fails to bind and says so.
+ *
+ * ## Where TLS is
+ *
+ * Not here, exactly as for `approval serve` and the webhook. Loopback by
+ * default, behind whatever the operator puts in front of it; a routable bind
+ * takes two flags and prints a banner, because the secret travels in a header.
+ */
+import { isAbsolute, join, resolve as resolvePathSegments } from "node:path";
+import { RELAY_DEFAULT_HOST, RELAY_DEFAULT_PORT, RELAY_DEFAULT_PROPOSER, RELAY_PATH, RELAY_SECRET_HEADER, fileNonceLedger, } from "../channels/relay.js";
+import { serveRelay } from "../channels/relay-server.js";
+import { channelLeaseDirFor } from "../core/channel-lease.js";
+import { readGatePolicy } from "../core/gate.js";
+import { mapsSendersFor } from "../core/sender-identity.js";
+import { readVerifiedRecords } from "../core/state.js";
+import { boolFlag, parseFlags, stringFlag } from "./args.js";
+import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_TORN_TAIL, EXIT_USAGE } from "./exit-codes.js";
+import { CHANNEL_RELAY_HELP } from "./help.js";
+import { isLoopbackHost, parseListen } from "./mcp.js";
+import { DEFAULT_LOG_PATH, resolvePath } from "./paths.js";
+import { usageErrorText } from "./usage.js";
+/** The environment variable the shared secret is read from. */
+export const RELAY_SECRET_ENV = "APPROVAL_RELAY_SECRET";
+/** The shortest secret this verb starts with: `serve`'s floor, for its reason. */
+export const RELAY_MIN_SECRET_LENGTH = 24;
+/** What a header carries unambiguously, and what `openssl rand -hex` produces. */
+const SECRET_CHARSET = /^[A-Za-z0-9_-]{1,256}$/u;
+/**
+ * A proposer is an `agent:` id. The relay is a machine carrying a proposal the
+ * control plane rendered, and recording it under a `human:` id would say a
+ * person proposed something nobody typed (APRV-455 refuter L1).
+ */
+const PROPOSER_PATTERN = /^agent:[^\s]+$/u;
+const RELAY_FLAGS = {
+    "--listen": "string",
+    "--port": "string",
+    "--allow-non-loopback": "boolean",
+    "--log": "string",
+    "--policy": "string",
+    "--dir": "string",
+    "--proposer": "string",
+    "--json": "boolean",
+    "--help": "boolean",
+    "-h": "boolean",
+};
+/**
+ * Why the relay could not start. A closed union, distinct per repair (SPEC.md
+ * §11.1 invariant 6). Its per-request refusals are `RELAY_REFUSAL_CODES`.
+ */
+export const RELAY_START_REFUSAL_CODES = [
+    /** `APPROVAL_RELAY_SECRET` is unset or empty. */
+    "relay-secret-missing",
+    /** It is shorter than {@link RELAY_MIN_SECRET_LENGTH}. */
+    "relay-secret-weak",
+    /** It holds a character outside A-Z a-z 0-9 _ -, or is longer than 256. */
+    "relay-secret-charset",
+    /** `--proposer` is not an `agent:` id. */
+    "relay-proposer-invalid",
+    /** The bind flags do not name a usable loopback (or explicitly widened) address. */
+    "relay-bind-invalid",
+];
+/** Everything that can fail without binding a port. Prints nothing. */
+export function prepareRelay(request) {
+    const environment = request.env ?? process.env;
+    const raw = environment[RELAY_SECRET_ENV];
+    const secret = raw === undefined ? "" : raw.trim();
+    if (secret.length === 0) {
+        return {
+            ok: false,
+            code: "relay-secret-missing",
+            message: `no ${RELAY_SECRET_ENV} in the environment. The relay's only authentication is this shared secret, carried in ${RELAY_SECRET_HEADER}; without one, any post that looked like a gesture would be one. Generate it (\`openssl rand -hex 32\`), give the same value to the control plane, and set it in the environment this process is launched from, never in a file in the tree`,
+        };
+    }
+    if (!SECRET_CHARSET.test(secret)) {
+        return {
+            ok: false,
+            code: "relay-secret-charset",
+            message: `${RELAY_SECRET_ENV} holds a value outside 1 to 256 characters of A-Z, a-z, 0-9, underscore and hyphen, which a header cannot be relied on to carry byte for byte. Its value is not shown here and is in no message this process writes`,
+        };
+    }
+    if (secret.length < RELAY_MIN_SECRET_LENGTH) {
+        return {
+            ok: false,
+            code: "relay-secret-weak",
+            message: `${RELAY_SECRET_ENV} is shorter than ${String(RELAY_MIN_SECRET_LENGTH)} characters. Generate it (\`openssl rand -hex 32\`) rather than choosing it: it is the whole of what separates the operator's relay from anyone who can reach this port`,
+        };
+    }
+    const proposer = request.proposer ?? RELAY_DEFAULT_PROPOSER;
+    if (!PROPOSER_PATTERN.test(proposer)) {
+        return {
+            ok: false,
+            code: "relay-proposer-invalid",
+            message: `--proposer ${JSON.stringify(proposer)} is not an agent:<id> actor. A proposal is recorded under it, and the relay is a machine carrying what the control plane rendered: a human: id would say a person proposed something nobody typed`,
+        };
+    }
+    if (request.listen !== null && request.port !== null) {
+        return {
+            ok: false,
+            code: "relay-bind-invalid",
+            message: "--listen and --port name the same thing; pass one. --listen <[host:]port> is the only way to bind a non-loopback interface",
+        };
+    }
+    let host = RELAY_DEFAULT_HOST;
+    let port = RELAY_DEFAULT_PORT;
+    if (request.listen !== null) {
+        const bind = parseListen(request.listen);
+        if (!bind.ok)
+            return { ok: false, code: "relay-bind-invalid", message: bind.message };
+        host = bind.host;
+        port = bind.port;
+    }
+    else if (request.port !== null) {
+        if (!/^\d+$/u.test(request.port.trim())) {
+            return {
+                ok: false,
+                code: "relay-bind-invalid",
+                message: `--port expects a whole number, got ${JSON.stringify(request.port)}`,
+            };
+        }
+        port = Number(request.port.trim());
+    }
+    if (port < 1 || port > 65535) {
+        return {
+            ok: false,
+            code: "relay-bind-invalid",
+            message: `the bind port ${String(port)} is outside 1..65535. Port 0 is refused too: the control plane posts to a fixed address, and an ephemeral port is one nobody would find`,
+        };
+    }
+    if (!isLoopbackHost(host) && !request.allowNonLoopback) {
+        return {
+            ok: false,
+            code: "relay-bind-invalid",
+            message: `--listen ${JSON.stringify(host)} is not the loopback interface, and this process speaks plain HTTP: the relay secret arrives in a header and a cleartext hop hands it to whoever is on it. Add --allow-non-loopback if you meant it and TLS is terminated in front of this process`,
+        };
+    }
+    return {
+        ok: true,
+        setup: {
+            logPath: request.logPath,
+            policy: request.policy,
+            secret,
+            host,
+            port,
+            proposer,
+            json: request.json,
+        },
+    };
+}
+function usageError(streams, json, code, message) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code, message } })}\n`);
+    else
+        streams.err(usageErrorText(message, CHANNEL_RELAY_HELP));
+    return EXIT_USAGE;
+}
+function failure(streams, json, code, message, exit) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code, message } })}\n`);
+    else
+        streams.err(`approval: ${message}\n`);
+    return exit;
+}
+/** The banner a routable bind prints, every time, on stderr. */
+export function relayNonLoopbackBanner(host, port) {
+    return [
+        "",
+        "  !! the approval relay IS BOUND TO A NON-LOOPBACK INTERFACE !!",
+        `  ${host}:${String(port)} is reachable by anyone who can route to it, and this`,
+        "  process speaks PLAIN HTTP. The relay secret travels in a header, and a",
+        "  cleartext hop hands it to whoever is on it. Terminate TLS in front of this",
+        "  process, or give it a loopback bind.",
+        "",
+        "",
+    ].join("\n");
+}
+/** Run the relay until a signal stops it. */
+export async function runRelay(setup, streams) {
+    const json = setup.json;
+    // The log must be readable before anything binds: an operator who pointed
+    // at the wrong store learns it here, not from the first refused gesture.
+    const read = readVerifiedRecords(setup.logPath);
+    if (!read.ok) {
+        const exit = read.code === "log-torn-tail" ? EXIT_TORN_TAIL : read.code === "log-unreadable" ? EXIT_IO : EXIT_INTEGRITY;
+        return failure(streams, json, read.code, read.message, exit);
+    }
+    // Not a refusal: a policy that maps no EdgeOS account is a legitimate state
+    // (the operator has not mapped the resident yet), and the relay refuses
+    // every gesture `sender-unmapped` until it does. Said once, at start.
+    const load = readGatePolicy({ policy: setup.policy });
+    if (!load.ok || !mapsSendersFor(load.policy.approvers, "edgeos")) {
+        streams.err(`approval: relay: the policy ${load.ok ? "maps no edgeos sender" : `does not load (${load.code})`}, so every attest, decline, grant and reject will be refused sender-unmapped until an attested policy maps the person's EdgeOS id under approvers.<id>.senders.edgeos\n`);
+    }
+    const report = (line, text) => {
+        if (json)
+            streams.out(`${JSON.stringify(line)}\n`);
+        else
+            streams.out(`${text}\n`);
+    };
+    let handle;
+    try {
+        handle = await serveRelay({
+            logPath: setup.logPath,
+            secret: setup.secret,
+            ledger: fileNonceLedger(join(channelLeaseDirFor(setup.logPath), "relay-nonces")),
+            host: setup.host,
+            port: setup.port,
+            gateOptions: { policy: setup.policy },
+            proposer: setup.proposer,
+            log: (message) => streams.err(`${message}\n`),
+            // What reached the gate, by code: never the body, the sender id or the
+            // secret. The record in the log is where the attribution lives.
+            afterGesture: (response) => {
+                const body = response.body;
+                const gesture = String(body["gesture"] ?? "?");
+                if (body["ok"] === true) {
+                    report({
+                        event: "relay_gesture",
+                        gesture,
+                        ok: true,
+                        ...(body["seq"] === undefined ? {} : { seq: body["seq"] }),
+                        ...(body["event"] === undefined ? {} : { record: body["event"] }),
+                        ...(body["actor"] === undefined ? {} : { actor: body["actor"] }),
+                    }, `relay ${gesture}: recorded seq ${String(body["seq"])}${body["actor"] === undefined ? "" : ` by ${String(body["actor"])}`}`);
+                }
+                else {
+                    const refusal = body["refusal"];
+                    const code = String(refusal?.code ?? "?");
+                    report({ event: "relay_gesture", gesture, ok: false, code }, `relay ${gesture}: refused (${code})`);
+                }
+            },
+        });
+    }
+    catch (cause) {
+        return failure(streams, json, "io", `the relay could not bind ${setup.host}:${String(setup.port)}: ${cause instanceof Error ? cause.message : String(cause)}`, EXIT_IO);
+    }
+    if (!isLoopbackHost(handle.host))
+        streams.err(relayNonLoopbackBanner(handle.host, handle.port));
+    if (json) {
+        streams.out(`${JSON.stringify({ event: "relay_started", host: handle.host, port: handle.port, path: RELAY_PATH, proposer: setup.proposer })}\n`);
+    }
+    streams.err(`approval: relay bound http://${handle.host}:${String(handle.port)}${RELAY_PATH}. Every post must carry ${RELAY_SECRET_HEADER}; gestures are attributed to the EdgeOS account the attested policy maps, never to this process. TLS is your proxy's. Press Ctrl-C to stop.\n`);
+    return await new Promise((settle) => {
+        let stopping = false;
+        const stop = () => {
+            if (stopping)
+                return;
+            stopping = true;
+            void (async () => {
+                await handle.close();
+                if (json)
+                    streams.out(`${JSON.stringify({ event: "stopped", relay: handle.stats() })}\n`);
+                process.off("SIGINT", stop);
+                process.off("SIGTERM", stop);
+                settle(EXIT_OK);
+            })();
+        };
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+    });
+}
+function absolute(value, cwd) {
+    return isAbsolute(value) ? value : resolvePathSegments(cwd, value);
+}
+/** `approval channel relay [flags]`. */
+export async function commandChannelRelay(argv, streams, cwd) {
+    const json = argv.includes("--json");
+    const parsed = parseFlags(argv, RELAY_FLAGS);
+    if (!parsed.ok)
+        return usageError(streams, json, "usage", parsed.message);
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${CHANNEL_RELAY_HELP}\n`);
+        return EXIT_OK;
+    }
+    const extra = parsed.positionals[0];
+    if (extra !== undefined)
+        return usageError(streams, json, "usage", `unexpected argument ${JSON.stringify(extra)}`);
+    const flags = parsed.flags;
+    const policyFlag = stringFlag(flags, "--policy");
+    const dirFlag = stringFlag(flags, "--dir");
+    const policy = policyFlag !== null
+        ? { file: absolute(policyFlag, cwd) }
+        : { dir: dirFlag === null ? cwd : absolute(dirFlag, cwd) };
+    const prepared = prepareRelay({
+        logPath: resolvePath(stringFlag(flags, "--log"), DEFAULT_LOG_PATH, cwd),
+        policy,
+        listen: stringFlag(flags, "--listen"),
+        port: stringFlag(flags, "--port"),
+        allowNonLoopback: boolFlag(flags, "--allow-non-loopback"),
+        proposer: stringFlag(flags, "--proposer"),
+        json,
+    });
+    if (!prepared.ok)
+        return usageError(streams, json, prepared.code, prepared.message);
+    return await runRelay(prepared.setup, streams);
+}
+//# sourceMappingURL=channel-relay.js.map

package/dist/src/cli/channel-relay.js.map

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

package/dist/src/cli/channel-telegram-webhook.d.ts

@@ -0,0 +1,275 @@
+/**
+ * `approval channel telegram webhook` — the same channel, the other arrival
+ * (SPEC.md §10.3, APRV-424).
+ *
+ * `approval channel telegram listen` holds a socket open against `getUpdates`
+ * for as long as the gate exists. That works, and it costs one always-running
+ * process per bot and forbids a second poller on the same token. This verb
+ * registers a URL with `setWebhook` instead and serves the callback, which is
+ * what makes a sleep-when-idle host able to run a gate, and what lets an
+ * operator put the receiver behind a proxy they already own.
+ *
+ * **Everything below the arrival is unchanged, and deliberately not restated
+ * here.** The pending queue is still `dispatchPending`'s, re-derived from the
+ * verified log every cycle. The handlers are still {@link wireListener}'s, the
+ * same four function objects `listen` registers. A tap still becomes a
+ * decision through `channels/telegram.ts`'s `handleUpdate` and
+ * `channels/contract.ts`'s `recordChannelDecision`. This file resolves
+ * configuration, refuses what it must refuse, binds a port and keeps a cycle
+ * running; it decides nothing and it renders nothing.
+ *
+ * ## The three refusals that are the point of the task
+ *
+ * 1. **The secret comes from the launch environment, never from the tree.**
+ *    `APPROVAL_TG_WEBHOOK_SECRET` (`core/telegram-config.ts` says why the name
+ *    is conventional rather than policy-declared), refused when it is unset,
+ *    when it is shorter than a value a host would generate, and when it holds
+ *    a character Telegram will not accept. SPEC.md §11.1 invariant 7.
+ * 2. **A post without the matching header decides nothing.** That check is
+ *    `channels/telegram-webhook.ts`'s, before the path, the method or the
+ *    body, and its refusal is counted and complained about rather than
+ *    appended: an endpoint the internet can reach must not be able to grow the
+ *    tenant's log.
+ * 3. **One transport per bot.** The preflight asks the Bot API which webhook
+ *    holds this bot and refuses a foreign one; `listen` and `approval up` ask
+ *    the same question and refuse when any webhook holds it. Within one
+ *    process the channel refuses the second claim outright.
+ *
+ * ## Where TLS is, and why the bind is loopback
+ *
+ * Telegram will only deliver to an HTTPS URL, and this process terminates no
+ * TLS and holds no certificate — exactly as `approval serve` does not
+ * (APRV-421, `cli/serve.ts`). The supported deployment is a loopback bind
+ * behind a proxy or a tunnel the operator owns, which is what `--url` names
+ * and what `docs/cli-reference.md#channel-telegram-webhook` states. A
+ * non-loopback bind takes two flags and prints a banner, because the secret
+ * arrives in a header and a cleartext hop hands it to whoever is on it.
+ */
+import type { DaemonIdSource } from "../core/daemon-identity.js";
+import { type ListenRefusalCode, type ListenSetup } from "./channel-telegram.js";
+import type { GlossRunner } from "./gloss.js";
+import type { Streams } from "./main.js";
+/**
+ * The shortest `secret_token` this verb will start with.
+ *
+ * `serve/credentials.ts`'s floor, for its reason: not a password policy, a
+ * floor under the one mistake that makes the check meaningless, which is a
+ * memorable value somebody typed. The host generates this; the floor costs it
+ * nothing.
+ */
+export declare const WEBHOOK_MIN_SECRET_LENGTH = 24;
+/** How often the dispatch cycle runs when the operator names no period. */
+export declare const WEBHOOK_DEFAULT_CYCLE_MS = 30000;
+/**
+ * How long the stop path waits for `deleteWebhook` (APRV-424, second review,
+ * note 6).
+ *
+ * The channel's ordinary request timeout is thirty seconds, which is right for
+ * a delivery and wrong for a stop: on top of the receiver's drain it made a
+ * second Ctrl-C look swallowed for the better part of a minute. A removal that
+ * does not land in five seconds is reported, and the operator is told the
+ * webhook is still registered, which is a sentence they can act on.
+ */
+export declare const WEBHOOK_STOP_DELETE_TIMEOUT_MS = 5000;
+/**
+ * Why a webhook runner could not be built. A closed union, distinct per
+ * repair, per SPEC.md §11.1 invariant 6.
+ *
+ * It sits BESIDE `LISTEN_REFUSAL_CODES` rather than inside it: every reason a
+ * listener cannot start is a reason this cannot either (it needs the same
+ * token, chat, identity, log and policy), and these are the reasons peculiar
+ * to a transport that binds a port and registers a URL.
+ */
+export declare const WEBHOOK_REFUSAL_CODES: readonly [
+/** `APPROVAL_TG_WEBHOOK_SECRET` is unset or empty. */
+"webhook-secret-missing", 
+/** It is shorter than {@link WEBHOOK_MIN_SECRET_LENGTH}. */
+"webhook-secret-weak", 
+/** It holds a character Telegram will not accept in a `secret_token`. */
+"webhook-secret-charset", 
+/** No `--url`: nothing to register, so nothing would ever be delivered. */
+"webhook-url-missing", 
+/** `--url` is not a URL, or its scheme is not `https`. */
+"webhook-url-insecure", 
+/** `--url` names a port Telegram does not deliver to. */
+"webhook-url-port", 
+/**
+ * `--url` carries userinfo (`https://user:pw@host/hook`) (review finding 10).
+ *
+ * Refused rather than stripped. A credential in a url is a credential the
+ * operator put on a command line, and a runtime that quietly dropped it
+ * would register an endpoint that answers differently from the one they
+ * typed; a runtime that kept it would carry it into `setWebhook`, into the
+ * start-up banner and into every refusal that names the url.
+ */
+"webhook-url-userinfo", 
+/**
+ * `--path` is not a servable path: it does not start with `/`, or it holds a
+ * `..` segment (review finding 3).
+ */
+"webhook-path-invalid", 
+/**
+ * `--path` is a servable path, and not the one `--url` names (review finding
+ * 3).
+ *
+ * The pair used to be free to disagree, described as an override for a proxy
+ * that rewrites on the way. What it actually bought was a receiver that
+ * registered cleanly, verified the secret on every real delivery, and then
+ * answered all of them 404: `telegram/webhook` against a url path of
+ * `/telegram/webhook`, or `/hook/` against a url ending `/hook`, both start
+ * without a word. A path mismatch is now a startup refusal.
+ */
+"webhook-path-mismatch", 
+/** `--cycle` was not a duration. */
+"webhook-cycle", 
+/**
+ * `setWebhook` was refused by the Bot API.
+ *
+ * Emitted by {@link runWebhook} since the review of this task; before it the
+ * code was declared here and the failure was reported as a bare `io`, which
+ * made "Telegram will not take this registration" indistinguishable from
+ * "the log could not be read". The status and the Bot API's own description
+ * are carried, redacted of the token and the secret by the channel.
+ */
+"webhook-registration-failed"];
+export type WebhookRefusalCode = (typeof WEBHOOK_REFUSAL_CODES)[number];
+export interface WebhookSetup {
+    /** Everything a listener has: the channel, the log, the identity, the policy. */
+    listen: ListenSetup;
+    /** The `secret_token`, as a value. Never printed, never logged, never recorded. */
+    secret: string;
+    /** The public URL registered with `setWebhook`. */
+    url: string;
+    /** The path this process answers. Derived from `--url` unless `--path` says otherwise. */
+    path: string;
+    /** The interface to bind. Loopback unless the operator widened it. */
+    host: string;
+    /** The port to bind. Distinct from the URL's port, which is the proxy's. */
+    port: number;
+    /** How often the dispatch cycle runs. */
+    cycleMs: number;
+    /**
+     * `--reclaim`: register over a webhook that already holds this bot (review
+     * finding 6).
+     *
+     * Carried on the setup rather than consulted from the flags again, because
+     * the check it overrides is made by {@link claimListenerBot}, which this
+     * verb shares with the poller.
+     */
+    reclaim: boolean;
+    /**
+     * The daemon id every record this process appends carries (APRV-448),
+     * resolved by {@link prepareWebhook} from the launch environment and the log
+     * path with the function the daemon loop uses, and declared by
+     * {@link runWebhook} before anything can append. An unusable declared id never
+     * reaches a setup: it is refused `daemon-id-invalid` at preparation.
+     */
+    daemon: {
+        ok: true;
+        id: string;
+        source: DaemonIdSource;
+    };
+}
+export type WebhookPreparation = {
+    ok: true;
+    setup: WebhookSetup;
+} | {
+    ok: false;
+    /**
+     * This verb's own codes, the listener's, and `daemon-id-invalid`
+     * (APRV-448), which is the write boundary's own code for the same fault,
+     * reported here before anything binds rather than on the first append.
+     */
+    code: WebhookRefusalCode | ListenRefusalCode | "daemon-id-invalid";
+    message: string;
+};
+/** Everything {@link prepareWebhook} needs, already resolved. */
+export interface WebhookRequest {
+    logPath: string;
+    policy: {
+        dir?: string;
+        file?: string;
+    };
+    as: string | null;
+    payloads: string | null;
+    apiBase: string | null;
+    /** `--no-stale-copy` (APRV-456); see `staleCopyFor` in channel-telegram.ts. */
+    noStaleCopy?: boolean;
+    json: boolean;
+    allowCrossInstance?: boolean;
+    /** `--url` as typed, or `null`. */
+    url: string | null;
+    /** `--path`, or `null` to take the URL's own path. */
+    path: string | null;
+    /** The bind, already parsed by the verb. */
+    host: string;
+    port: number;
+    /** `--cycle` as typed, or `null` for {@link WEBHOOK_DEFAULT_CYCLE_MS}. */
+    cycle: string | null;
+    /** `--reclaim` as passed. Defaults to false, which is the refusing side. */
+    reclaim?: boolean;
+    /** The environment the secret is read from. Injectable for tests. */
+    env?: NodeJS.ProcessEnv;
+    log(message: string): void;
+    /** The gloss runner, if the caller wants one. See {@link ListenSetup.gloss}. */
+    gloss?: GlossRunner;
+}
+/**
+ * Everything that can fail without touching the network, in order.
+ *
+ * {@link prepareListen} first, because a webhook runner that has no bot token,
+ * no chat and no human identity is not a webhook problem: the two verbs refuse
+ * those the same way, in the same sentences, for the reason `prepareListen`
+ * exists at all. Then the three this transport adds.
+ *
+ * It PRINTS NOTHING and CHOOSES NO EXIT CODE, exactly as `prepareListen` does.
+ */
+export declare function prepareWebhook(request: WebhookRequest): WebhookPreparation;
+/**
+ * `--listen` / `--port` -> the interface and port this process binds (review
+ * finding 9).
+ *
+ * Its own function, and exported, because three refusals live in it and each
+ * one is a thing an operator can type:
+ *
+ * - **Port 0 is refused.** The kernel hands out an ephemeral port for it, and
+ *   an ephemeral port is the one thing this transport cannot use: the whole
+ *   deployment is a proxy forwarding a fixed public url to a fixed local
+ *   address, so a receiver that bound 51423 registered a url nothing would
+ *   ever reach and said nothing about it. Tests bind 0 by calling the receiver
+ *   directly, which is the level where an ephemeral port is the point.
+ * - **A port outside 1..65535 is refused**, on either flag. `parseListen`
+ *   accepts 0 for `approval serve`'s own reasons, so the floor is applied
+ *   here rather than assumed there.
+ * - **A routable interface needs `--allow-non-loopback`**, because this
+ *   process speaks plain HTTP and the secret arrives in a header.
+ */
+export type WebhookBind = {
+    ok: true;
+    host: string;
+    port: number;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function resolveWebhookBind(listenFlag: string | null, portFlag: string | null, allowNonLoopback: boolean): WebhookBind;
+/**
+ * The banner a non-loopback bind prints, every time, on stderr.
+ *
+ * `cli/serve.ts`'s, with the one credential this surface has in place of that
+ * one's two. Reached only when the operator passed both `--listen` naming a
+ * routable interface and `--allow-non-loopback`, so it is not a warning about
+ * something that happened by accident.
+ */
+export declare function webhookNonLoopbackBanner(host: string, port: number): string;
+/**
+ * Run the receiver until a signal stops it.
+ *
+ * The order is the one `cli/serve.ts` argues for, with one change that is this
+ * transport's own: everything that can refuse refuses first, and the LOCAL
+ * bind happens before `setWebhook`, so there is no window in which Telegram is
+ * posting to a port nothing is listening on.
+ */
+export declare function runWebhook(setup: WebhookSetup, streams: Streams): Promise<number>;
+/** `approval channel telegram webhook [flags]`. */
+export declare function commandTelegramWebhook(argv: string[], streams: Streams, cwd: string): Promise<number>;