approval-md 0.3.0 → 0.4.0

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

@@ -34,6 +34,24 @@
  * notify, long-poll, callbacks, failure modes — against a local mock Bot API
  * server and never touches the real network.
  *
+ * ## Two transports, one update path (APRV-424)
+ *
+ * An update reaches this channel either because it long-polled for it
+ * ({@link TelegramChannel.pollOnce}) or because Telegram posted it to a URL the
+ * runtime registered ({@link TelegramChannel.deliverUpdate}, fed by
+ * `channels/telegram-webhook.ts`). That is the WHOLE of the difference. Both
+ * entry points hand the update to the same {@link TelegramChannel.handleUpdate}
+ * and therefore to the same chat check, the same `senderOf`, the same
+ * resolution ladder, the same `onDecision` handler and the same
+ * annotate-after-decision edit; a decision does not know which door it came
+ * through, and there is no second copy of any of it to drift.
+ *
+ * The two are mutually exclusive per bot, and the Bot API says so first:
+ * `getUpdates` is refused outright while a webhook is set.
+ * {@link TelegramChannel.claimTransport} refuses the in-process form of the
+ * mistake, and the verbs above ask `getWebhookInfo` and the ownership registry
+ * about the cross-process one.
+ *
  * ## Config-declared identity — SPEC.md §11
  *
  * > Human identity in v0.1 is config-declared (an environment variable or
@@ -361,6 +379,13 @@ export declare function decidedLine(actor: string, ts: string, seq: number): str
 export declare const TELEGRAM_DEFAULT_RETENTION_MS: number;
 /** Least time between two sweeps. A sweep is O(map); once a minute is plenty. */
 export declare const TELEGRAM_SWEEP_INTERVAL_MS = 60000;
+/**
+ * How many refused cards' nonces a channel remembers as dead (APRV-442).
+ *
+ * A bound on memory and nothing else: a nonce that falls off the end reaches
+ * the action-reference fallback, and the gate judges that tap in full.
+ */
+export declare const TELEGRAM_REFUSED_NONCE_CAP = 1024;
 /**
  * The slice of `fetch` this module uses, structurally.
  *
@@ -831,6 +856,14 @@ export interface DigestState {
      * the request's own `ts` remains the only instant a TTL is measured from.
      */
     deliveredAtMs: number;
+    /**
+     * How long after {@link deliveredAtMs} the LAST of this digest's members can
+     * still be decided, or `null` when some member is bounded by nothing
+     * (APRV-423, second review pass). The widest of the members' own windows
+     * ({@link Delivery.windowMs}), because a digest is droppable only once every
+     * member is past deciding.
+     */
+    windowMs: number | null;
 }
 /**
  * The computed facts a digest's members share, as the digest states them.
@@ -1270,6 +1303,50 @@ export interface TelegramPollResult {
         ok: boolean;
     }[];
 }
+/**
+ * How updates reach this channel (APRV-424).
+ *
+ * `poll` is `getUpdates`, the transport every build before APRV-424 had.
+ * `webhook` is Telegram posting each update to a URL the runtime registered.
+ * They are alternatives and never a pair: the Bot API refuses `getUpdates`
+ * outright while a webhook is set, so a process that did both would spend its
+ * life in a 409 loop and the approver's tap would land on whichever half was
+ * lucky.
+ */
+export type TelegramTransport = "poll" | "webhook";
+/**
+ * Why a transport claim was refused. Frozen, per SPEC §11.1 invariant 6.
+ *
+ * One code, because there is one fact: this channel is already receiving
+ * updates by the other transport.
+ */
+export declare const TELEGRAM_TRANSPORT_REFUSAL_CODES: readonly ["transport-conflict"];
+export type TelegramTransportRefusalCode = (typeof TELEGRAM_TRANSPORT_REFUSAL_CODES)[number];
+export type TelegramTransportClaim = {
+    ok: true;
+    transport: TelegramTransport;
+} | {
+    ok: false;
+    code: TelegramTransportRefusalCode;
+    message: string;
+};
+/**
+ * The in-process half of "long-poll and webhook are mutually exclusive"
+ * (APRV-424).
+ *
+ * It is a belt on the braces and says so. The exclusion that matters is per
+ * BOT and lives above this class, where a process can ask the Bot API
+ * (`getWebhookInfo`) and the per-machine ownership registry who else is
+ * receiving this bot's updates; a channel object knows only about itself.
+ * What this rules out is the one failure a caller could cause here and
+ * nowhere else: feeding one channel instance from both a poll loop and an
+ * HTTP handler, where `handleUpdate`'s single ack slot and the delivery maps
+ * would be written by two arrivals nobody ordered.
+ */
+export declare class TelegramTransportError extends Error {
+    readonly code: TelegramTransportRefusalCode;
+    constructor(message: string);
+}
 export interface TelegramListenOptions {
     /** Process exactly one successful `getUpdates` batch, then return. */
     once?: boolean;
@@ -1393,11 +1470,60 @@ export declare class TelegramChannel implements TestableChannel {
     private readonly digests;
     /** "All" nonce -> the digest message it was issued for. */
     private readonly allNonces;
+    /**
+     * Action keys whose card this process disarmed on a tap the gate did NOT
+     * settle (APRV-442): a refusal (`sender-unmapped`, a budget, an unattested
+     * policy, anything `ok: false`) or a handler that threw. Drained by
+     * {@link takeReleased}.
+     *
+     * The disarm is right and stays, and {@link refusedNonces} keeps it final:
+     * the refused card's bytes resolve to nothing, not even through the
+     * action-reference fallback to the card that replaces it. What the disarm
+     * must not do is leave the listener believing the REQUEST is on the
+     * approver's phone, which is what `DispatchState.delivered` goes on saying
+     * until something tells it otherwise. This set is that something: it names
+     * a card, never an outcome, and the listener re-derives from the verified
+     * log whether the request is still pending before it offers a new card.
+     * Nothing here decides, and losing it to a restart costs nothing, because a
+     * restarted listener re-sends everything pending anyway.
+     */
+    private readonly released;
+    /**
+     * Nonces of cards a refused or failed tap disarmed (APRV-442), oldest first,
+     * capped at {@link TELEGRAM_REFUSED_NONCE_CAP}.
+     *
+     * Without this, a released request's fresh card would give the refused
+     * card's bytes somewhere to go: the nonce misses, the action reference
+     * resolves to the new live card, and a Telegram redelivery of the refused
+     * tap (a webhook retry) or a client replaying the removed buttons would be
+     * refused again, append again, disarm the new card and cause another
+     * re-send, once per replay. A nonce in this set never takes the fallback, so
+     * a refused card stays exactly as dead as it was before APRV-442 and only
+     * the REQUEST is offered again. Forgetting an entry past the cap degrades to
+     * the fallback, whose tap the gate still judges in full: volume, never a
+     * decision.
+     */
+    private readonly refusedNonces;
     private rendered;
     private offset;
     private counter;
     private stopped;
     private inFlight;
+    /**
+     * The transport this channel has started receiving updates by, or `null`
+     * before the first one (APRV-424). Sticky for the life of the object: a
+     * process that stopped polling has not stopped being a poller, and the
+     * question this answers is which arrival path owns the maps below.
+     */
+    private transport;
+    /**
+     * Everything {@link redact} scrubs out of anything that leaves this class.
+     *
+     * The bot token from construction, plus any secret a later call was handed:
+     * {@link registerWebhook} adds the `secret_token` before it sends it, so a
+     * Bot API error quoting the request cannot put it on an operator's terminal.
+     */
+    private readonly secrets;
     private readonly counters;
     constructor(config: TelegramConfig);
     onDecision(handler: (decision: ChannelDecision) => DecisionOutcome): void;
@@ -1553,6 +1679,28 @@ export declare class TelegramChannel implements TestableChannel {
      * a decided one is not that.
      */
     private disarm;
+    /**
+     * How long after delivery the request behind a prompt can still be decided,
+     * on this process's clock, or `null` when nothing bounds it (APRV-423, second
+     * review pass).
+     *
+     * The SHORTER of two bounds, each of which is at or past the gate's own
+     * lapse, so the sweep never forgets a button a decision could still reach:
+     *
+     * - the request's `ttl_remaining_ms`, computed by the listener from the
+     *   verified log against the window the gate judges by (the policy's TTL
+     *   narrowed by the harness cap the requesting hook declared). It was
+     *   measured at tagging time, and delivery is at or after tagging, so
+     *   counting it from delivery ends at or after the real lapse;
+     * - the policy's own TTL ({@link TelegramConfig.approvalTtlMs}), counted from
+     *   delivery, which is at or after the `approval.requested` it really runs
+     *   from. This was the only bound before APRV-423 and it stays as one.
+     *
+     * A request neither bounds is decidable forever, and its entry is dropped
+     * only on an observed settlement. This channel still reads no policy and no
+     * log: both numbers arrive computed, by the verb and by the tagger.
+     */
+    private retentionWindowMs;
     /**
      * Drop the delivery bookkeeping no callback can still be honoured against
      * (APRV-135).
@@ -1646,6 +1794,28 @@ export declare class TelegramChannel implements TestableChannel {
      * {@link Channel} interface names. Its wording is unchanged.
      */
     retract(deliveryId: DeliveryId, reason: string, actionKey?: string): Promise<void>;
+    /**
+     * The action keys whose card a refused or failed tap disarmed since the last
+     * call, and forget them (APRV-442).
+     *
+     * The listener's dispatch cycle calls this once per cycle and offers a fresh
+     * card for every key the verified log still calls pending. It is a statement
+     * about this process's cards and nothing else: it carries no decision, no
+     * sender and no outcome, and a key in it that the log has since settled is
+     * simply not offered.
+     */
+    takeReleased(): string[];
+    /**
+     * Mark `delivery`'s card dead and its request released, BEFORE the
+     * annotation that disarms it (APRV-442).
+     *
+     * Every nonce still armed for this request on this message is recorded in
+     * {@link refusedNonces}, together with the nonce the tap carried (which
+     * differs when the tap came from an earlier copy through the fallback), so
+     * none of those bytes can later resolve to the fresh card. On a digest only
+     * this member's nonce is taken: its siblings stay armed on the digest.
+     */
+    private release;
     /**
      * Send one plain message that carries no question (APRV-196).
      *
@@ -1700,6 +1870,99 @@ export declare class TelegramChannel implements TestableChannel {
      * what {@link listen} catches and retries.
      */
     pollOnce(): Promise<TelegramPollResult>;
+    /**
+     * Which update types this channel asks for, on either transport (APRV-424).
+     *
+     * APRV-216. `message` is asked for only while a command handler is
+     * registered: see {@link onCommand} for why a listener that reads messages
+     * nobody asked for would break `approval setup channel telegram`'s chat
+     * discovery. APRV-299 adds the second reason to read messages: a `loved` or
+     * `disliked` on a review card collects the human's words as a REPLY, because
+     * an inline keyboard has no text input.
+     *
+     * One function since APRV-424, because `setWebhook` takes the same list as
+     * `getUpdates` and two spellings of it would be two answers to "what does
+     * this listener read" — with the webhook's answer frozen at registration
+     * time, where nobody would look for it.
+     */
+    allowedUpdates(): string[];
+    /**
+     * One update, from whichever transport carried it (APRV-424).
+     *
+     * The whole of what the webhook adds is the ARRIVAL. Everything a tap then
+     * passes through — the chat check, `senderOf`, the checkpoint and review
+     * parsers, the resolution ladder, the early ack, `this.handler` and the
+     * annotation written from the record the gate appended — is
+     * {@link handleUpdate}, called from here and from {@link pollOnce}, and
+     * there is no second copy of any of it. `tests/telegram-webhook.test.ts`
+     * drives one callback through both entry points and compares the records the
+     * log ends up holding.
+     *
+     * The sweep is `pollOnce`'s, for `pollOnce`'s reason: this is the moment the
+     * process is about to be idle, and a channel that only ever wakes for taps
+     * would otherwise never run one.
+     */
+    deliverUpdate(update: unknown): Promise<TelegramPollResult>;
+    /** The per-update bookkeeping both transports do, before `handleUpdate`. */
+    private intake;
+    /**
+     * Bind this channel to one transport, or say which one already holds it
+     * (APRV-424).
+     *
+     * Idempotent for the transport already claimed, so a webhook server that
+     * claims at start-up and then delivers, or a driver calling `pollOnce` in a
+     * loop, pays nothing. Not released by {@link stop}: a process that stopped
+     * polling has not stopped being a poller, and re-pointing a live channel's
+     * delivery maps at a second arrival path is the state this exists to refuse.
+     */
+    claimTransport(transport: TelegramTransport): TelegramTransportClaim;
+    /** {@link claimTransport}, for the paths where a refusal is a caller's bug. */
+    private claimOrThrow;
+    /**
+     * Point this bot's updates at `url`, and require `secret` on every post.
+     *
+     * Three properties, and each is a refusal to be clever:
+     *
+     * - **The secret is Telegram's own mechanism**, `secret_token`, echoed back
+     *   on every delivery in the `X-Telegram-Bot-Api-Secret-Token` header. The
+     *   receiver compares it and refuses anything else, so a URL that leaks (a
+     *   proxy log, a referrer, a screenshot) is a URL that still decides
+     *   nothing.
+     * - **It is redacted from this moment on.** The value is added to the
+     *   channel's secret list BEFORE the call, so a Bot API error that quotes
+     *   the request cannot print it.
+     * - **Pending updates are kept.** `drop_pending_updates` is left false:
+     *   taps that arrived while the process was down are the approver's answers,
+     *   and the gate is what decides whether they are still honourable.
+     */
+    registerWebhook(url: string, secret: string): Promise<void>;
+    /**
+     * Take this bot's webhook away, so `getUpdates` works again.
+     *
+     * Called on a clean stop of the webhook runner. Pending updates are kept for
+     * {@link registerWebhook}'s reason: the next process to start — a poller or
+     * another webhook — is entitled to the taps that arrived in between.
+     *
+     * `timeoutMs` is what the stop path passes, and it is shorter than this
+     * channel's ordinary request timeout on purpose (APRV-424, second review,
+     * note 6). A stop already waits for the receiver to drain, and an operator
+     * pressing Ctrl-C a second time is asking for the process to end: half a
+     * minute of an unreachable Bot API on top of that reads as a hang, and the
+     * webhook it failed to remove is reported rather than silently retried.
+     */
+    deleteWebhook(timeoutMs?: number): Promise<void>;
+    /**
+     * What the Bot API says is receiving this bot's updates right now.
+     *
+     * The one authority on the question, and the reason it is asked at start-up
+     * by both transports: the ownership registry knows about processes on THIS
+     * machine, and a webhook registered from a laptop in another timezone is
+     * still a webhook swallowing every tap this poller is waiting for.
+     */
+    webhookInfo(): Promise<{
+        url: string;
+        pendingUpdateCount: number;
+    }>;
     /**
      * Exactly one `answerCallbackQuery` per callback query, on every path
      * (APRV-196).
@@ -1919,7 +2182,14 @@ export declare class TelegramChannel implements TestableChannel {
      * settled, so a member still in the map is one still armed on a live message.
      */
     private liveDeliveryFor;
-    /** Replace the token with a placeholder anywhere it appears in `text`. */
+    /**
+     * Replace every secret this channel holds with a placeholder in `text`.
+     *
+     * The bot token always, and since APRV-424 the webhook `secret_token` too,
+     * from the moment {@link registerWebhook} is handed it. Both are values that
+     * only ever travel TO the Bot API, so anything coming back that quotes one
+     * is a diagnostic about to print a credential.
+     */
     private redact;
     private describe;
     /**