approval-md 0.3.0 → 0.4.0

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

@@ -0,0 +1,273 @@
+/**
+ * `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;
+    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>;