cratefield-module-telegram

Telegram in a Cratefield venture: the secret-token webhook, account linking, and consent buttons with a rule this module does not bend — a tap in Telegram can deny anything, approve anything harmless, and only arm — never finish — anything that moves value.

The module mounts at /v1/telegram and owns four tables (telegram_inbox, telegram_link_codes, telegram_links, telegram_actions), shipped as one migration.

Routes

Configuration

Every key is optional at boot — the module fails closed per request instead — but set-and-blank fails validate_config:

Linking

The signed-in app calls /link-codes and shows the deep link. The code is stored only as a SHA-256 hash, works for ten minutes, and works once. /start <code> in a private chat consumes it (a conditional update, so a code pasted twice links once), refuses a Telegram user already linked to a different account — out loud, in the chat — and answers linked. on_linked fires with the subject, the Telegram user id and the chat id.

Action buttons

send_action_prompt sends a subject's linked chat a text with Approve and Deny buttons. Each button carries its own compact token in callback_data (Telegram caps it at 64 bytes):

a1.<base64url(action_id[16] ‖ decision[1] ‖ exp_unix[4 BE] ‖ tag[12])>

The tag is HMAC-SHA256 over the action id, the decision, the expiry and the intended Telegram user, verified in constant time — so a button forwarded to a group is dead paper, and so is a replayed one: the decision is a conditional update out of pending, judged by rows affected.

What a tap does:

• Deny — the action is denied, on_action fires, done.
• Approve, not value-moving — the action is approved, on_action fires with passkey_confirmed: false, done.
• Approve, value-moving — the action only moves to awaiting_passkey, no hook fires, and the bot replies with a URL button to TELEGRAM_APPROVAL_URL?action=<action_id>.

The passkey rule

awaiting_passkey has exactly one exit: POST /actions/{action_id}/confirm, from the web app, by the subject who owns the action, while the action is unexpired, with a configured StepUp willing to swear the request carries a fresh passkey ceremony. No StepUp injected — 403, always. Only then does the confirmation commit (single-use) and on_action fire with passkey_confirmed: true.

There is deliberately no stock StepUp implementation here. One that reads the bearer token's amr and iat claims would be unsound: the auth service stores the login's methods in the session and copies them into every token it mints, stamping each mint with a fresh iat — the refresh grant included. A token refreshed hours after a passkey login carries passkey and a seconds-old iat while proving nothing about the last minutes, and no access-token claim (there is no auth_time) tells the two apart.

An implementation must therefore prove what the trait's documentation says: a passkey assertion completed for this subject within this request, or within a freshness window it names — a WebAuthn ceremony it observed, not a passkey-born session. Being signed in is not being present; a consent button that moves value requires the second one.

If the hook behind a finished confirmation fails, the route rolls the action back to awaiting_passkey — only while it still carries approved — and answers 5xx, so the caller's retry can run the confirmation again; the same is true of a Telegram tap whose on_action hook fails, and of a /start <code> whose on_linked hook fails (the code is put back; the redelivery re-runs the linking).

Composition

use std::sync::Arc;
use cratefield_module_telegram::{Telegram, TelegramEvents, StepUp};

let module = Telegram::new(
    TelegramEvents::new()
        .on_message(|message| Box::pin(async move { Ok(()) }))
        .on_linked(|linked| Box::pin(async move {
            println!("{} linked telegram user {}", linked.subject, linked.telegram_user_id);
            Ok(())
        }))
        .on_action(|decision| Box::pin(async move { Ok(()) })),
)
// .bot(Arc::new(HttpTelegramBot::new(http, clock, token)))  // or TELEGRAM_BOT_TOKEN
//     .random(rng)                                            // required: codes and ids
//     .step_up(Arc::new(MyStepUp::new(...)));                 // see `StepUp`: a fresh passkey assertion, per request

.random(..) should always be there — self_check names its absence; without it no link code or action id can be drawn.