approval-md 0.3.0 → 0.4.1

package/dist/src/channels/telegram-webhook.d.ts

@@ -0,0 +1,273 @@
+/**
+ * The Telegram webhook receiver (SPEC.md §10.3, APRV-424).
+ *
+ * §10.3 has always written the channel interface as `notify(request) ->
+ * delivery_id`, `poll()/webhook() -> decision`. Until this task only the first
+ * half of the second clause existed: the Telegram channel long-polled
+ * `getUpdates`, which needs one always-running process per bot and forbids a
+ * second poller on the same token. This is the other half. Telegram posts each
+ * update to a URL the runtime registered, and a host that sleeps between
+ * requests can therefore serve a gate.
+ *
+ * ## It decides nothing, and it barely reads
+ *
+ * This file checks one header, one path, one method and one body size, parses
+ * JSON, and hands the object to {@link TelegramChannel.deliverUpdate}. Which
+ * account the Bot API attributed the tap to, which approver the attested
+ * policy maps that account to, whether the gate will take the answer, and what
+ * the message is edited to say afterwards are all decided exactly where they
+ * were decided before this task existed — in `channels/telegram.ts`'s
+ * `handleUpdate` and in `channels/contract.ts`'s `recordChannelDecision`,
+ * reached by the same call the poll loop makes. An update that arrives here is
+ * an update; it is not evidence about itself.
+ *
+ * ## The secret is the whole of the authentication
+ *
+ * A webhook URL is a public endpoint. Anyone who can route to it can POST a
+ * JSON object that LOOKS like a tap from the approver's chat, and nothing in
+ * the body could tell the difference: SPEC.md §11.1 invariant 4 — a
+ * self-reported field never reduces scrutiny — is exactly the rule that makes
+ * a body-only check worthless here. So Telegram's own `secret_token` is
+ * REQUIRED rather than optional. It is set on `setWebhook`, echoed on every
+ * delivery in `X-Telegram-Bot-Api-Secret-Token`, compared here in constant
+ * time, and a post without the matching value is refused before its path, its
+ * method or its body is looked at.
+ *
+ * Three consequences, each deliberate:
+ *
+ * - **The comparison is over SHA-256 digests under `timingSafeEqual`**, which
+ *   is constant-time AND length-independent (`timingSafeEqual` throws on a
+ *   length mismatch, which would itself be an oracle for the secret's length).
+ *   `serve/credentials.ts` states the same argument for the same reason.
+ * - **Duplicate headers are refused rather than resolved.** Node joins
+ *   repeated headers, so two of them would make the value this server compares
+ *   differ from the one a reader of the request would name. There is no
+ *   correct choice; the request is malformed.
+ * - **A refusal appends NOTHING to the log.** It is counted, complained about
+ *   on the runner's stderr and answered with its own machine-readable code,
+ *   and it never reaches the decision path. This is `TELEGRAM_ANOMALY_KINDS`'s
+ *   rule, and it matters more here than it does there: writing "somebody
+ *   posted a forgery" into an append-only approval log would let anyone who
+ *   can reach this URL grow the record a human is asked to trust. A refusal is
+ *   a fact about this transport, and this transport reports it where facts
+ *   about transports belong.
+ *
+ * ## What is reused from `approval serve`, and what could not be
+ *
+ * The shape is APRV-421's, deliberately: loopback bind by default with the
+ * operator's proxy terminating TLS, the credential checked before the URL is
+ * parsed, a refusal carried as a body with a frozen code rather than as a bare
+ * status, an oversized body drained before the refusal is written (a response
+ * written while the client is still uploading closes the socket under it), and
+ * no state a restart loses.
+ *
+ * Its CODE could not be reused, and the reason is structural rather than
+ * stylistic. `src/serve/` imports `src/cli/`, which imports `src/channels/`;
+ * an import from here back into `src/serve/` would close an ESM cycle, which
+ * is not a compile error but a binding that is `undefined` in one direction on
+ * the day module initialisation order changes. `tests/layering.test.ts` pins
+ * that direction. The two servers are also different surfaces: that one
+ * answers two bearer credentials for two parties across six routes, this one
+ * answers Telegram's echoed secret on one.
+ *
+ * ## One update at a time
+ *
+ * Deliveries are serialized through a promise chain. `handleUpdate` keeps a
+ * single callback-query ack slot and the delivery maps are plain `Map`s, so
+ * two updates handled concurrently would interleave in ways nobody ordered.
+ * The poll loop gets this for free by awaiting each update in turn; an HTTP
+ * server has to say it.
+ *
+ * ## Stopping waits for the update it is holding
+ *
+ * A stop closes the listener, drains what is in flight, and only then drops
+ * the sockets. The first version of this file did the opposite — it destroyed
+ * every socket synchronously and resolved in about a millisecond — so
+ * `deleteWebhook`, the "stopped" line and the process's exit all ran while an
+ * update was still being handled: an append in progress, a dispatch cycle
+ * halfway through a send, and a caller whose response never arrived. The order
+ * is now stop accepting, drain, drop, and the verb's own stop path does its
+ * `deleteWebhook` after this resolves rather than beside it.
+ *
+ * ## Redelivery is safe because the gate is
+ *
+ * Telegram retries a delivery it did not get a 2xx for, so the same tap can
+ * arrive twice. Nothing here deduplicates, and nothing needs to: the second
+ * one reaches `decide()` through the same path as the first and is refused
+ * `already-decided` with the first human answer standing. That is the same
+ * property a button pressed twice has had since APRV-26.
+ */
+import type { TelegramChannel, TelegramPollResult } from "./telegram.js";
+/**
+ * The header Telegram echoes the `secret_token` in, lowercased as Node
+ * presents it.
+ */
+export declare const TELEGRAM_SECRET_HEADER = "x-telegram-bot-api-secret-token";
+/** The path this server answers when the operator names none. */
+export declare const TELEGRAM_WEBHOOK_DEFAULT_PATH = "/telegram/webhook";
+/** The interface it binds when the operator names none. Loopback, always. */
+export declare const TELEGRAM_WEBHOOK_DEFAULT_HOST = "127.0.0.1";
+/** The port it binds when the operator names none. */
+export declare const TELEGRAM_WEBHOOK_DEFAULT_PORT = 4683;
+/**
+ * Largest body accepted. A Telegram update is a small JSON object; the
+ * largest thing one can carry is a message's 4096-character text.
+ */
+export declare const TELEGRAM_WEBHOOK_MAX_BODY_BYTES: number;
+/**
+ * How much of an oversized body is read and thrown away before the socket is
+ * dropped. `serve/server.ts` carries the argument: the refusal cannot be
+ * written until the client stops writing, or the response closes the socket
+ * under it and the caller sees a transport error instead of a refusal.
+ */
+export declare const TELEGRAM_WEBHOOK_DRAIN_LIMIT_BYTES: number;
+/**
+ * How long {@link TelegramWebhookHandle.close} waits for requests already in
+ * flight before it destroys their sockets (APRV-424, review finding 2).
+ *
+ * A stop has to end. What this bounds is the pathological case — a client that
+ * opened a request and stopped writing, a handler that will never return — and
+ * not the ordinary one, which is an update whose decision is being appended
+ * and takes milliseconds. The ordinary one is what the drain exists for: the
+ * first version of this file destroyed every socket synchronously and
+ * resolved in about a millisecond, so `deleteWebhook`, the "stopped" line and
+ * the process's exit all happened while an append and a dispatch were still
+ * running.
+ */
+export declare const TELEGRAM_WEBHOOK_CLOSE_TIMEOUT_MS = 10000;
+/** How long the close drain waits between checks of the in-flight count. */
+export declare const TELEGRAM_WEBHOOK_DRAIN_POLL_MS = 5;
+/**
+ * Everything this receiver refuses, and nothing else. Frozen, per SPEC.md
+ * §11.1 invariant 6: a refusal is machine-readable and distinct.
+ *
+ * Distinct because the repairs are distinct. A secret mismatch is a forgery or
+ * a rotation the registration did not follow; an unknown path is a URL that
+ * does not match the one registered; a body too large is a caller that is not
+ * Telegram. None of them is a decision, and none of them is the same fact.
+ */
+export declare const TELEGRAM_WEBHOOK_REFUSAL_CODES: readonly [
+/** No `X-Telegram-Bot-Api-Secret-Token`, or one that is not the registered value. */
+"webhook-secret-mismatch", 
+/** More than one secret header. Malformed, and not resolvable by choosing. */
+"webhook-duplicate-secret-header", 
+/**
+ * The request line and the `Host` header do not form a URL (400).
+ *
+ * Split from `webhook-unknown-path` in the review of this task: one code for
+ * both collapsed "what arrived is not a request this server can parse" into
+ * "you are posting to a path this server does not serve", and those two
+ * share nothing but a status family — the first is a broken proxy or a
+ * hand-written client, the second is a registration that does not match the
+ * bind. `src/serve/server.ts` makes the same split, between
+ * `serve-malformed-url` and `serve-unknown-path`.
+ */
+"webhook-malformed-request", 
+/** A path this server does not serve (404). */
+"webhook-unknown-path", 
+/** The right path, the wrong method. Telegram POSTs. */
+"webhook-method-not-allowed", 
+/** Larger than {@link TELEGRAM_WEBHOOK_MAX_BODY_BYTES}. */
+"webhook-body-too-large", 
+/** The body could not be read off the socket, or is not JSON. */
+"webhook-body-unreadable", 
+/** JSON that is not an Update object. */
+"webhook-not-an-update", 
+/** The channel is already receiving updates by the other transport. */
+"webhook-transport-conflict", 
+/** The channel threw while handling the update. Nothing is claimed about the log. */
+"webhook-handler-failed"];
+export type TelegramWebhookRefusalCode = (typeof TELEGRAM_WEBHOOK_REFUSAL_CODES)[number];
+/** What this receiver has done since it bound. Counters, never decisions. */
+export interface TelegramWebhookStats {
+    /** Requests answered, of any kind. */
+    requests: number;
+    /** Updates handed to the channel. */
+    updates: number;
+    /** Refusals, by code. Never a decision, never a log event. */
+    refusals: Record<TelegramWebhookRefusalCode, number>;
+}
+export interface TelegramWebhookOptions {
+    /** The channel every accepted update is handed to. */
+    channel: TelegramChannel;
+    /**
+     * The registered `secret_token`, as a value.
+     *
+     * Resolved by the VERB from the launch environment (SPEC.md §11.1 invariant
+     * 7: configuration is never loaded implicitly from the working tree).
+     * Nothing under `src/channels/` reads `process.env`, here as everywhere.
+     */
+    secret: string;
+    /** The path to answer. Defaults to {@link TELEGRAM_WEBHOOK_DEFAULT_PATH}. */
+    path?: string;
+    /** Interface to bind. Defaults to loopback; the CLI owns any widening. */
+    host?: string;
+    /** TCP port. `0` asks the kernel for an ephemeral one, which is what tests use. */
+    port?: number;
+    /** Where operational complaints go. Defaults to stderr. */
+    log?: (message: string) => void;
+    /**
+     * How long {@link TelegramWebhookHandle.close} drains before it drops what
+     * is left. Defaults to {@link TELEGRAM_WEBHOOK_CLOSE_TIMEOUT_MS}; a test
+     * that deliberately holds a handler open shortens it.
+     */
+    closeTimeoutMs?: number;
+    /**
+     * Run after each update the channel accepted (APRV-424).
+     *
+     * This is where the runtime's dispatch cycle goes, and it is the webhook's
+     * equivalent of the listener's `beforePoll`: the channel holds
+     * no queue and reads no log, so putting the next pending request on the
+     * phone after a tap is the caller's job. It MUST NOT throw; a rejection is
+     * complained about and swallowed, because a dispatch that failed must not
+     * turn an answered tap into an unanswered request.
+     */
+    afterUpdate?: (result: TelegramPollResult) => Promise<void> | void;
+}
+export interface TelegramWebhookHandle {
+    readonly host: string;
+    readonly port: number;
+    readonly path: string;
+    stats(): TelegramWebhookStats;
+    /** Run `work` behind the same queue update delivery uses. */
+    serialize<T>(work: () => Promise<T>): Promise<T>;
+    /** Requests this receiver has accepted and not yet answered. */
+    inFlight(): number;
+    /**
+     * Stop accepting, let what is in flight finish, then drop the sockets.
+     *
+     * In that order, and the order is the fix for review finding 2: a close that
+     * destroyed sockets first would tear the response off an update whose
+     * decision was mid-append, and would hand its caller back control in time
+     * to call `deleteWebhook` and print "stopped" over the top of it. Idempotent
+     * and safe to await twice; a second call awaits the first.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Is `offered` the registered secret?
+ *
+ * Both sides are hashed first, so the comparison is over two equal-length
+ * buffers and `timingSafeEqual` can never throw — which is what keeps the
+ * length of the real secret out of the answer.
+ */
+export declare function secretMatches(expected: string, offered: string | null): boolean;
+/**
+ * The one secret header a request offered, `null` for none, and `"duplicate"`
+ * for more than one.
+ *
+ * Read off `rawHeaders` rather than `headers`, because Node joins repeats of a
+ * non-special header into one comma-separated value and the join is exactly
+ * what hides the second one.
+ */
+export declare function secretHeaderOf(rawHeaders: readonly string[]): string | null | "duplicate";
+/**
+ * Start the receiver. Resolves once it is bound and its real port is known;
+ * rejects when the bind fails, so the verb can report it and exit.
+ *
+ * The channel's transport is claimed BEFORE the listener exists, for the
+ * reason `approval serve` settles its credentials first: a server that bound
+ * and then discovered it could not receive would be a server Telegram had
+ * already posted to.
+ */
+export declare function serveTelegramWebhook(options: TelegramWebhookOptions): Promise<TelegramWebhookHandle>;