approval-md 0.2.0 → 0.3.0

package/dist/src/channels/telegram.js

@@ -40,16 +40,35 @@
  * > flag); the trust boundary is the local machine, and anyone who can set that
  * > configuration and write to the log is inside it.
  *
- * This channel does **not** authenticate the person who tapped the button. It
- * checks that the callback arrived from the configured chat id, and the
- * decision is then recorded against the human actor the *runtime* was
- * configured with (`APPROVAL_HUMAN` / `--as`), not against anything the
- * callback carried. So the guarantee is "someone with access to the configured
- * chat, on a runtime configured by someone with local control, tapped Approve"
- * — not "alice tapped Approve". Anyone in that chat can approve as the
- * configured actor. Use a private chat with the bot, and treat the chat's
- * membership as part of the trust boundary. Cryptographic identity is future
- * work and is not a v0.1 claim.
+ * What this channel authenticates, exactly: that the callback arrived **from
+ * the configured chat id**, and which **Telegram account** the Bot API
+ * attributes the tap to (`callback_query.from.id`). It authenticates no
+ * person, because no transport can: an account id is evidence about an
+ * account.
+ *
+ * What is done with the second fact is the operator's to decide, and since
+ * APRV-324 there are two settings:
+ *
+ * - **No `senders` block in the policy.** Nothing changes from every build
+ *   before it. The decision is recorded against the human actor the *runtime*
+ *   was configured with (`APPROVAL_HUMAN` / `--as`), so the guarantee is
+ *   "someone with access to the configured chat, on a runtime configured by
+ *   someone with local control, tapped Approve" — not "alice tapped Approve".
+ *   Anyone in that chat can approve as the configured actor. Use a private chat
+ *   with the bot, and treat the chat's membership as part of the trust
+ *   boundary.
+ * - **A `senders` block mapping account ids to approvers.** The decision is
+ *   recorded against the person the operator attested that account to, and a
+ *   tap from an account the policy does not name is REFUSED rather than
+ *   recorded under the listener's identity. The guarantee becomes "the account
+ *   the operator attested to alice tapped Approve", which is a statement about
+ *   Telegram's session handling and the operator's assertion, and still not a
+ *   proof of personhood. Cryptographic identity is future work and is not a
+ *   v0.1 claim.
+ *
+ * The channel itself resolves nothing either way. It reports the account it
+ * saw; `channels/contract.ts` resolves it against the attested policy, and
+ * `core/gate.ts` decides. See `design/channel-sender-identity.md`.
  *
  * ## Formatting: HTML, not MarkdownV2 — a deliberate choice
  *
@@ -1206,6 +1225,42 @@ export function parseCheckpointCallback(data) {
         return null;
     return { sign: verb === "k", nonce };
 }
+/**
+ * The account the Bot API attributes a callback to (APRV-324, amended SPEC.md
+ * §10.3).
+ *
+ * `callback_query.from.id` and nothing else. Telegram assembles the `from`
+ * object itself, from the session the tap arrived on, which is why it is the
+ * one field on an update this channel treats as evidence about a person. Three
+ * neighbours are deliberately not read:
+ *
+ * - **`from.username`.** Mutable and reusable, so a mapping keyed on it would
+ *   hand an identity over with a handle. Never a key here and never recorded
+ *   (`core/sender-identity.ts` states the argument in full).
+ * - **`message.from`.** The author of the message the button sits on — this bot
+ *   — rather than the person who pressed it.
+ * - **`data`, and any text.** What the sender says about themselves, which
+ *   §11.1 invariant 4 says may raise scrutiny and never lower it. A callback
+ *   whose payload names a user id names it about itself; the id here comes from
+ *   the transport, and the two disagreeing changes nothing.
+ *
+ * `undefined` when the update carries no usable id: a sender this channel could
+ * not read is not a sender it may guess at, and the decision then travels with
+ * none, which the contract reads as today's configured attribution.
+ */
+export function senderOf(query, channel) {
+    const from = query["from"];
+    if (typeof from !== "object" || from === null)
+        return undefined;
+    const id = from["id"];
+    // Telegram sends a JSON number; a string is accepted for the same reason the
+    // chat check accepts one, and nothing else is: an object or an array here is
+    // a shape this channel does not understand rather than an id to stringify.
+    if (typeof id !== "number" && typeof id !== "string")
+        return undefined;
+    const text = String(id);
+    return text.length === 0 ? undefined : { channel, id: text };
+}
 const CALLBACK_VERBS = {
     g: { decision: "grant", scope: "one" },
     r: { decision: "reject", scope: "one" },
@@ -1494,6 +1549,29 @@ export function isMessageNotModified(cause) {
         cause.description !== null &&
         TELEGRAM_NOT_MODIFIED.test(cause.description));
 }
+/**
+ * Telegram's wording for "somebody else is already long-polling this bot".
+ *
+ * Matched on the description as well as the status, for the same reason
+ * {@link TELEGRAM_NOT_MODIFIED} is: 409 is a conflict, and the conflict this
+ * project cares about is specifically the terminated-by-other-getUpdates one.
+ */
+const TELEGRAM_POLL_CONFLICT = /terminated by other getupdates|make sure that only one bot/iu;
+/**
+ * Whether a failed poll is the Bot API saying another process holds this bot
+ * (APRV-390).
+ *
+ * It is the one poll failure that is not transient and not the network's
+ * fault: retrying it forever produces an identical line every few seconds and
+ * never recovers, because the other poller is not going to stop. {@link
+ * TelegramChannel.listen} reports it once, with whatever the caller knows
+ * about who the other process is, and then stops repeating itself.
+ */
+export function isPollConflict(cause) {
+    return (cause instanceof TelegramApiError &&
+        cause.method === "getUpdates" &&
+        (cause.status === 409 || (cause.description !== null && TELEGRAM_POLL_CONFLICT.test(cause.description))));
+}
 export class TelegramChannel {
     name = "telegram";
     token;
@@ -2255,6 +2333,32 @@ export class TelegramChannel {
         return String(result.message_id);
     }
     // -------------------------------------------------------------------------
+    // Identity
+    // -------------------------------------------------------------------------
+    /**
+     * Which bot this token is, from one `getMe` (APRV-390).
+     *
+     * `getMe` is the only Bot API call that answers it, and it is the call
+     * `approval doctor` and `approval setup channel telegram` already make for
+     * the same reason: it mutates nothing, sends nothing, and acknowledges
+     * nothing. In particular it is NOT `getUpdates`, so asking who this bot is
+     * consumes no update and steals no pending tap from a listener that is
+     * already running — which matters here above all, because the answer is
+     * what decides whether this process is allowed to poll at all.
+     *
+     * Throws {@link TelegramApiError} like every other call; the caller decides
+     * whether an unreachable Bot API is a refusal or a shrug.
+     */
+    async identify() {
+        const result = await this.call("getMe", {});
+        const id = result["id"];
+        const username = result["username"];
+        return {
+            id: typeof id === "number" || typeof id === "string" ? String(id) : "",
+            username: typeof username === "string" ? `@${username}` : "the bot",
+        };
+    }
+    // -------------------------------------------------------------------------
     // Long polling
     // -------------------------------------------------------------------------
     /**
@@ -2277,6 +2381,16 @@ export class TelegramChannel {
     async listen(options = {}) {
         this.stopped = false;
         let backoff = this.backoffMs;
+        /**
+         * APRV-390. The last failure reported, and how many identical ones have
+         * been swallowed since. A 409 does not recover: the other poller is not
+         * going to stop because this one asked again, so the pre-APRV-390 loop
+         * printed the same sentence every few seconds until somebody read the
+         * terminal. The retry itself stays — a listener that stops listening is
+         * the failure this loop rules out — and only the COMPLAINING is collapsed.
+         */
+        let lastComplaint = null;
+        let repeats = 0;
         while (!this.stopped) {
             try {
                 if (options.beforePoll !== undefined) {
@@ -2286,6 +2400,11 @@ export class TelegramChannel {
                 }
                 await this.pollOnce();
                 backoff = this.backoffMs;
+                if (repeats > 0) {
+                    this.complain(`approval: telegram getUpdates recovered after ${String(repeats)} further identical failure(s)`);
+                }
+                lastComplaint = null;
+                repeats = 0;
                 if (options.once === true)
                     return;
             }
@@ -2293,7 +2412,26 @@ export class TelegramChannel {
                 if (this.stopped)
                     return;
                 this.counters.pollErrors += 1;
-                this.complain(`approval: telegram getUpdates failed (${this.describe(cause)}); retrying in ${backoff}ms — the listener is still up`);
+                const conflict = isPollConflict(cause);
+                // The 409's own sentence, said once. It names the fact ("another
+                // process is polling this bot") rather than the HTTP status, because
+                // the status is what a reader was already staring at, and it carries
+                // whatever the caller knows about which two gates are involved.
+                const advice = conflict ? (options.conflictAdvice?.() ?? null) : null;
+                const message = conflict
+                    ? `approval: telegram getUpdates: another process is polling this bot${advice === null ? "" : ` — ${advice}`}; this listener keeps retrying and will not receive a tap until the other one stops`
+                    : `approval: telegram getUpdates failed (${this.describe(cause)}); retrying in ${backoff}ms — the listener is still up`;
+                if (message === lastComplaint) {
+                    repeats += 1;
+                }
+                else {
+                    if (repeats > 0) {
+                        this.complain(`approval: telegram getUpdates: the previous line repeated ${String(repeats)} more time(s)`);
+                    }
+                    this.complain(message);
+                    lastComplaint = message;
+                    repeats = 0;
+                }
                 await sleep(backoff);
                 backoff = Math.min(backoff * 2, this.maxBackoffMs);
             }
@@ -2478,17 +2616,37 @@ export class TelegramChannel {
         const chat = (message["chat"] ?? {});
         const chatId = chat["id"] === undefined ? "" : String(chat["id"]);
         // (a) Not our chat. Counted, answered, never decided, never logged.
+        //
+        // APRV-324 leaves this check exactly where it is, FIRST and ahead of the
+        // sender, on purpose: the mapping widens WHO may decide and never WHERE
+        // from. A callback carrying a perfectly mapped `from.id` but arriving in a
+        // chat this listener does not answer to is ignored here, before anything
+        // reads a sender, because a bot that accepted it would be one an operator
+        // could not scope by conversation.
         if (chatId !== this.chatId) {
             await this.ignore(result, callbackId, "foreign-chat", `callback from chat ${JSON.stringify(chatId)}, which is not the configured approver chat`, "This bot only accepts decisions from its configured approval chat.");
             return;
         }
+        // APRV-324. The one field on this update that identifies a PERSON rather
+        // than a conversation, read once, here, directly after the chat check and
+        // BEFORE every branch below. Its position is the fix for the follow-up
+        // review: read later, three callback families — checkpoint signatures,
+        // review cards and the decision ladder — would each have had their own
+        // chance to keep the pre-mapping behaviour, and two of them are privileged
+        // gestures. `callback_query.from` is the Bot API's own attribution of the
+        // tap to an account; nothing inside `message`, `data` or any text is
+        // consulted, because those are what the sender says about themselves. It is
+        // an observation and nothing more: this channel resolves no identity and
+        // chooses no actor, it reports what it saw and the runtime's handlers
+        // resolve it against the attested policy.
+        const sender = senderOf(query, this.name);
         // APRV-257, before the decision vocabulary and in a parser of its own. A
         // checkpoint button decides no request, so it must never reach the ladder
         // below — where an unresolved nonce falls back to an action reference, and
         // a signature gesture would start looking for something to approve.
         const checkpoint = parseCheckpointCallback(query["data"]);
         if (checkpoint !== null) {
-            await this.handleCheckpointTap(checkpoint, callbackId, result);
+            await this.handleCheckpointTap(checkpoint, callbackId, result, sender);
             return;
         }
         // APRV-299, before the decision vocabulary and in a parser of its own, for
@@ -2498,7 +2656,7 @@ export class TelegramChannel {
         // happened would start looking for something to approve.
         const review = parseReviewCallback(query["data"]);
         if (review !== null) {
-            await this.handleReviewTap(review, callbackId, result);
+            await this.handleReviewTap(review, callbackId, result, sender);
             return;
         }
         const parsed = parseCallbackData(query["data"]);
@@ -2510,7 +2668,7 @@ export class TelegramChannel {
         // decides is whatever is still open on that delivery right now, which this
         // process knows and the callback bytes deliberately do not say.
         if (parsed.scope === "all") {
-            await this.handleDigestAll(parsed.decision, parsed.nonce, callbackId, result);
+            await this.handleDigestAll(parsed.decision, parsed.nonce, callbackId, result, sender);
             return;
         }
         // The resolution ladder (APRV-196). A tap is answered by the nonce when
@@ -2552,6 +2710,7 @@ export class TelegramChannel {
             action_key: delivery.actionKey,
             decision: parsed.decision,
             deliveryId: delivery.deliveryId,
+            ...(sender === undefined ? {} : { sender }),
             ...(delivery.batchDeliveryId === undefined
                 ? {}
                 : { batchDeliveryId: delivery.batchDeliveryId }),
@@ -2643,7 +2802,11 @@ export class TelegramChannel {
      * the same message would show the approver their own decisions arriving one
      * at a time, and would spend N Bot API calls to end in the same place.
      */
-    async handleDigestAll(decision, nonce, callbackId, result) {
+    async handleDigestAll(decision, nonce, callbackId, result, 
+    // APRV-324: one gesture, one sender, on every member it decides. An "all"
+    // tap is N decisions by one person, so each of the N carries the account
+    // the one tap came from.
+    sender) {
         const deliveryId = this.allNonces.get(nonce);
         const digest = deliveryId === undefined ? undefined : this.digests.get(deliveryId);
         if (digest === undefined) {
@@ -2667,6 +2830,7 @@ export class TelegramChannel {
                 decision,
                 deliveryId: digest.deliveryId,
                 batchDeliveryId: digest.batchDeliveryId,
+                ...(sender === undefined ? {} : { sender }),
                 ...(decision === "reject"
                     ? { note: `${TELEGRAM_REJECT_NOTE} (callback ${callbackId}, all)` }
                     : {}),
@@ -2771,7 +2935,11 @@ export class TelegramChannel {
      * and appends to a log, and a spinner that lasted a decision long is what
      * that task removed.
      */
-    async handleCheckpointTap(tap, callbackId, result) {
+    async handleCheckpointTap(tap, callbackId, result, 
+    // APRV-324 follow-up. A checkpoint signature is a human-only act and says
+    // this log's head is what this person saw, so it carries the account the
+    // tap came from exactly as a decision does.
+    sender) {
         const held = this.checkpointNonces.get(tap.nonce);
         if (held === undefined) {
             await this.ignore(result, callbackId, "unknown-callback", `checkpoint nonce ${JSON.stringify(tap.nonce)} was not issued by this process`, "This checkpoint prompt is from an earlier run. A fresh one is offered when the next is due.");
@@ -2784,7 +2952,11 @@ export class TelegramChannel {
             return;
         }
         await this.safeAnswer(callbackId, tap.sign ? "Heard — signing. The message will say what the log recorded." : "Not now.");
-        const response = await handler({ sign: tap.sign, head: held.head });
+        const response = await handler({
+            sign: tap.sign,
+            head: held.head,
+            ...(sender === undefined ? {} : { sender }),
+        });
         // Edited here rather than through `annotate`, which renders an action key
         // under its headline. A checkpoint has none, and an empty `<code></code>`
         // where a request's key belongs would be this channel implying a request.
@@ -2817,7 +2989,7 @@ export class TelegramChannel {
      * re-implement the rule. The one thing this method owns is the ARMING, which
      * is process memory that appends nothing.
      */
-    async handleReviewTap(tap, callbackId, result) {
+    async handleReviewTap(tap, callbackId, result, sender) {
         const deliveryId = this.reviewNonces.get(tap.nonce);
         const state = deliveryId === undefined ? undefined : this.reviewCards.get(deliveryId);
         if (state === undefined || state.settled !== null) {
@@ -2845,7 +3017,11 @@ export class TelegramChannel {
             const chosen = tap.choice === "deny" ? "denied" : "ok";
             state.denyArmed = chosen === "denied";
             await this.safeAnswer(callbackId, TELEGRAM_REVIEW_ACK);
-            await this.recordReview(state, { sampleSeq: state.card.sampleSeq, verdict: chosen }, result);
+            await this.recordReview(state, {
+                sampleSeq: state.card.sampleSeq,
+                verdict: chosen,
+                ...(sender === undefined ? {} : { sender }),
+            }, result);
             return;
         }
         const reaction = tap.choice;
@@ -2858,11 +3034,16 @@ export class TelegramChannel {
         const conflicts = verdict === "denied" && (reaction === "liked" || reaction === "loved");
         if (!conflicts && (reaction === "loved" || reaction === "disliked")) {
             await this.safeAnswer(callbackId, TELEGRAM_REVIEW_NOTE_TOAST);
-            await this.askForNote(state, verdict, reaction);
+            await this.askForNote(state, verdict, reaction, sender);
             return;
         }
         await this.safeAnswer(callbackId, TELEGRAM_REVIEW_ACK);
-        await this.recordReview(state, { sampleSeq: state.card.sampleSeq, verdict, reaction }, result);
+        await this.recordReview(state, {
+            sampleSeq: state.card.sampleSeq,
+            verdict,
+            reaction,
+            ...(sender === undefined ? {} : { sender }),
+        }, result);
     }
     /**
      * Send the ForceReply prompt a `loved` or `disliked` needs, and remember what
@@ -2879,7 +3060,7 @@ export class TelegramChannel {
      * one card, and the older prompt stops resolving so a late reply to it lands
      * nowhere rather than recording a grade the human moved on from.
      */
-    async askForNote(state, verdict, reaction) {
+    async askForNote(state, verdict, reaction, sender) {
         if (state.awaitingNote !== null)
             this.reviewNotePrompts.delete(state.awaitingNote.promptId);
         const lines = reviewNotePromptLines(reaction, verdict, state.card.fields.action_key.value);
@@ -2893,7 +3074,7 @@ export class TelegramChannel {
             reply_markup: { force_reply: true },
         });
         const promptId = String(sent.message_id);
-        state.awaitingNote = { promptId, verdict, reaction };
+        state.awaitingNote = { promptId, verdict, reaction, ...(sender === undefined ? {} : { sender }) };
         this.reviewNotePrompts.set(promptId, state.deliveryId);
     }
     /**
@@ -2928,6 +3109,19 @@ export class TelegramChannel {
         }
         const state = this.reviewCards.get(deliveryId);
         const pending = state?.awaitingNote ?? null;
+        // APRV-324 follow-up, and checked BEFORE the prompt is forgotten, so a
+        // reply from the wrong account costs the right one nothing. A note prompt
+        // is a ForceReply addressed to the person who armed the grade, and its
+        // words are recorded as that person's; a different account replying to it
+        // is answering a question nobody asked them.
+        const sender = senderOf(message, this.name);
+        if (pending !== null &&
+            pending.promptId === promptId &&
+            pending.sender !== undefined &&
+            (sender === undefined || sender.id !== pending.sender.id)) {
+            this.complain("approval: telegram ignored a review note: it replied to a prompt issued for a different account, and the prompt is still open for the account that armed it");
+            return true;
+        }
         this.reviewNotePrompts.delete(promptId);
         if (state === undefined || pending === null || pending.promptId !== promptId)
             return true;
@@ -2937,6 +3131,7 @@ export class TelegramChannel {
             verdict: pending.verdict,
             reaction: pending.reaction,
             note: text,
+            ...(sender === undefined ? {} : { sender }),
         }, result);
         return true;
     }