arah2/.planning/phases/02-bot-skeleton-initdata-security/02-03-SUMMARY.md

---

phase: 02-bot-skeleton-initdata-security plan: 03 subsystem: bot-surface tags: [telegram, grammy, setmycommands, cloudflare-worker, webhook, session-gate, i18n, malay, deploy-gate]

Dependency graph

requires:

• plan 02-01: bot/ workspace scaffold — Env contract (BOT_TOKEN, WEBHOOK_SECRET, chat_sessions), wrangler.jsonc (KV_ID_PLACEHOLDER), delegate scripts
• plan 02-02: validateInitData (rejection classes malformed/tampered/stale) + mintSession (TTL-only, rotate-on-new) + SESSION_TTL_SECONDS provides:
• bot/src/i18n/strings.ts — single copy source of truth (en + ms identical key-sets), pickLocale fallback rule; clinical/honest start + privacy copy matching the code's actual KV writes (PRIV-01)
• bot/src/bot/bot.ts createBot(env) + command modules start/help/privacy — text-only handlers for /start /mula /help /privacy /privasi (aliases share handlers per D-04)
• bot/src/webhook.ts — Worker entry: POST /telegram/webhook (grammY cloudflare-mod, constant-time secret-token auth) + POST /api/session (validateInitData → 401 category-only → mintSession); only two routes, 404 otherwise
• bot/scripts/register-commands.mjs — one-time setMyCommands in default + ms scopes, descriptions derived from helpMenu (no inline copy, no stub entries)
• bot/scripts/set-webhook.mjs + chained npm run deploy — setWebhook with secret_token + allowed_updates:["message"]
• bot/test/commands.test.mjs — CS1–CS6 command-surface gates (locale parity, pickLocale matrix, PRIV-01 copy gate, D-02 structural grep, D-03 menu gap-freedom, D-04 alias completeness) affects: [phase 3 mini-app shell (same Worker, session endpoint already live), phase 4 Mini App caller of /api/session, phase 5 guidance envelope]

Tech tracking

tech-stack: added: [] # zero added deps — grammy webhookCallback + node builtins only patterns: [per-request Bot instantiation from env-bound token, webhookCallback(bot,"cloudflare-mod",undefined,undefined,secret) with constant-time header compare, descriptions derived from helpMenu lines (copy survives in one place), pure replyText builders + thin handlers, category-only rejection logging, KV namespace id placeholder until deploy checkpoint]

key-files: created: - bot/src/i18n/strings.ts - bot/src/bot/bot.ts - bot/src/bot/commands/start.ts - bot/src/bot/commands/help.ts - bot/src/bot/commands/privacy.ts - bot/scripts/register-commands.mjs - bot/scripts/set-webhook.mjs - bot/test/commands.test.mjs - bot/src/webhook.ts modified: - bot/package.json (deploy script now chains wrangler deploy + set-webhook) - bot/wrangler.jsonc (workers_dev: true marker; KV id still KV_ID_PLACEHOLDER)

key-decisions:

• "setMyCommands descriptions derive from strings.helpMenu's '/cmd — text' lines, so the registered menu and the /help reply cannot drift (D-03/D-05 in one mechanism)"
• "pickLocale uses exact 'ms' or 'ms-' prefix (not everything-starting-with-ms) so unrelated codes can never select Malay"
• "/api/session adds no extra branch beyond plan-02's mintSession — replay closing is purely D-07 rotate-on-new; endpoint has zero additional KV writes (T-02-06)"
• "Bot is instantiated per request inside the webhook branch only (env-bound token cannot resolve at module scope; /api/session path skips instantiation entirely)"

patterns-established:

• "Command-surface structural gates live in test/commands.test.mjs: any new keyboard/button surface or menu stub fails CS4/CS5"
• "D-14 discipline wide-scope: the only console statement in the Worker entry is '[initdata] rejected: '"

requirements-completed: [] # ONBD-01/PRIV-01 code paths shipped; req completion awaits the D-16 real-client deploy gate (plan task 3)

Metrics

duration: ~12min completed: 2026-10-22

Phase 2 Plan 3: Command Surface + Worker Wiring + Deploy Gate Summary

The full user-facing Telegram surface (en + ms, text-only, honest privacy copy) and the Worker entry (secret-token webhook + validateInitData→mintSession /api/session gate) are built, CI-verified (27/27), LIVE on workers.dev, and APPROVED by the user in a real Telegram client (checks a–e all green, 2026-10-22); four deployment-environment issues found during the walkthrough were remediated live — plan complete

Performance

• Duration: ~12 min (tasks 1–2) + deploy chain session
• Started: 2026-10-22T03:46Z
• Completed: 2026-10-22 (deploy chain through checkpoint)
• Tasks: 3 of 3 — task 3 deploy chain + real-client walkthrough complete, user approved (02-03-APPROVAL.md)
• Files created: 9; modified: 3 (+ KV namespace provisioned)

Accomplishments

• task 1 (b4393fb) — command surface with aliases:
  • src/i18n/strings.ts is the copy's tokens.css: en + ms with identical key-sets (CS1), clinical Rams-tone /start intro and /privacy stored/never-stored copy whose wording names exactly the D-08 claim fields (user id, chat id, language) and the 15-minute TTL (PRIV-01, matches src/kv/sessions.ts reads)
  • Handlers send plain text with link previews disabled and nothing else — D-02 is pinned as a source grep gate (CS4: zero keyboard-shaped tokens in bot.ts + commands)
  • pickLocale: ms/ms-… → ms; everything else (null, unknown, id) → en (CS2 matrix)
  • scripts/register-commands.mjs registers exactly two setMyCommands calls — default scope + language_code:"ms" scope — descriptions derived from helpMenu lines, no inline copy, no future-command stubs (D-03/D-05); gap-freedom asserted by CS5
  • Command stack registers exactly {start, mula, help, privacy, privasi} (CS6, D-04)
• task 2 (df3b7d6) — Worker entry + deploy plumbing:
  • src/webhook.ts routes exactly /telegram/webhook (grammY webhookCallback(bot, "cloudflare-mod", undefined, undefined, env.WEBHOOK_SECRET) — constant-time secret-token header compare rejects garbage before bot processing or any KV touch, T-02-03) and POST /api/session (validateInitData → 401 {error:<category>} / mintSession one-time opaque token; single mint path, no extra branch — T-02-01/02/06)
  • D-14: the only console statement in the Worker entry is the category-only [initdata] rejected: <reason> line
  • scripts/set-webhook.mjs posts setWebhook { url, secret_token, allowed_updates:["message"] }; secrets read from gitignored .dev.vars; token never echoed (T-02-04)
  • npm run deploy -w bot now chains wrangler deploy && node scripts/set-webhook.mjs; wrangler.jsonc marks workers_dev: true as the webhook URL target; KV id intentionally stays a placeholder for the checkpoint's wrangler kv namespace create
• Verification: npm test -w bot → [runner] 27 passed, 0 failed (all prior suites still green: initdata T1–T7, sessions, privacy PG1/PG2); npm run bot:typecheck exit 0; both scripts pass node --check; wrangler deploy --dry-run --outdir /tmp/opencode/worker-dryrun exit 0 bundling in 167.97 KiB with the chat_sessions binding

task Commits

1. task 1: strings module + command surface with aliases (D-01..D-05) — b4393fb (feat)
2. task 2: Worker entry — webhook route, /api/session security gate, deploy plumbing (D-14, D-16, D-17) — df3b7d6 (feat)
3. task 3: deploy gate (checkpoint:human-verify) — deploy chain executed after user provisioned credentials:
   • KV namespace created + id wired: 492a97b (fix)
   • Worker deployed live; secrets set; setWebhook + setMyCommands registered — no code commits required (see Deployment Record)
   • APPROVAL: real-client walkthrough a–e observed green by the user — "it works! Menu or / has /help and /privacy! approved!" — recorded in 02-03-APPROVAL.md
   • Hardening from walkthrough findings: d600d6e (set-webhook auto-appends /telegram/webhook)

Files Created/Modified

• Created: bot/src/i18n/strings.ts, bot/src/bot/bot.ts, bot/src/bot/commands/{start,help,privacy}.ts, bot/src/webhook.ts, bot/scripts/{register-commands,set-webhook}.mjs, bot/test/commands.test.mjs
• Modified: bot/package.json (deploy chain), bot/wrangler.jsonc (workers_dev + real KV namespace id, 492a97b), bot/scripts/set-webhook.mjs + bot/.dev.vars.example (walkthrough hardening, d600d6e)

Deployment Record (task 3, D-16)

• Worker URL (public, not a secret): https://araharah-bot.araharah-bot.workers.dev
  • araharah-bot workers.dev subdomain was already registered on the account; DNS went live within minutes of first deploy
  • Account: adri.mcmc@gmail.com, account id 7b4510d8…51e9
• KV namespace: chat_sessions → id 59f58a54bc44483e89872b20a005a5eb — created via wrangler kv namespace create, id committed in wrangler.jsonc (492a97b; the id is account-scoped config, not a secret)
• Runtime secrets: BOT_TOKEN + WEBHOOK_SECRET uploaded via wrangler secret put (set-once; .dev.vars is local-only for wrangler dev — values never printed, never committed)
• setWebhook: ok:true → delivered updates restricted to allowed_updates:["message"], secret-token header armed (T-02-03). Verified read-back via getWebhookInfo: url/secret-header/pending=0/no errors
• setMyCommands: default scope + language_code:"ms" scope both ok:true; read-back via getMyCommands shows exactly /help + /privacy with derived descriptions in both languages (D-03/D-05)
• Live security smokes (automated against the deployed Worker):
  • webhook without secret header → 401 "unauthorized"
  • webhook with wrong secret header → 401 "unauthorized"
  • POST /api/session garbage body → 401 {"error":"malformed"} (category-only, T-02-01/D-14)
  • GET /api/session → 405; unknown route → 404 "Not found"
  • KV key list pre-/start → [] (PRIV-02 baseline)

Real-Client Walkthrough Outcome (APPROVED — final gate for ONBD-01/PRIV-01/PRIV-02 + SC1–SC4)

User verified in the real Telegram client (2026-10-22) and said verbatim: "it works! Menu or / has /help and /privacy! approved!"

Check	Result
a. /start → one clinical sentence, no buttons	✓
b. menu + / autocomplete list exactly /help and /privacy	✓
c. /privacy stored/never-stored blocks as written	✓
d. /mula ≡ /start (reply language follows app language_code per D-05; user's app is English → English reply is correct behavior; no force-ms)	✓
e. gibberish /xyz → silent, no crash, no menu drift	✓

Four deployment-environment issues were found and remediated live during the walkthrough (see Deviations); the user approved after all four were resolved. Full record with verbatim response + evidence commands: 02-03-APPROVAL.md.

KV spot-check (PRIV-02, available any time): cd bot && npx wrangler kv key list --namespace-id 59f58a54bc44483e89872b20a005a5eb — only session:*/chat:*-shaped TTL keys, gone after ~15 min.

Decisions Made

• Menu descriptions derive from helpMenu: registration imports src/i18n/strings.ts and slices the /cmd — text lines, making the persisted menu and the /help reply one artifact (D-03 gap-freedom enforced by construction + test)
• pickLocale prefix semantics: exact ms / ms- prefix only — an unrelated code can never enter the ms surface
• /api/session is branch-free: replay closing is entirely plan-02's rotate-on-new invariant; the endpoint introduces zero extra KV writes so the PG1/PG2 privacy gates hold automatically
• Per-request Bot only on the webhook path: the token cannot resolve at module scope (Workers env), and /api/session has no need for a Bot instance

Deviations from Plan

Fix applied during task 3 deploy chain ([Rule 1 - Bug]: production secrets not deployed):

• Found during: task 3 live smoke test — first study: burning bright no-secret webhook probe returned 500 "Worker threw exception"; wrangler tail showed Error: Empty token! at new Bot — .dev.vars is local-only, so env.BOT_TOKEN/env.WEBHOOK_SECRET were undefined in production
• Fix: uploaded both runtime secrets via wrangler secret put (set-once, values from .dev.vars, never echoed); re-ran smokes → all green. Noted for future deploys: npm run bot:deploy deploys code + sets the webhook, but does NOT re-upload secrets — set-once is expected behavior; recreate only if the secret is rotated. Phase 3+ deploy docs should carry this note.
• Files modified: none (environment-only fix); Worker redeploy not needed
• Commit: n/a

Also: a first wrangler secret put attempt ran from the wrong working directory and uploaded empty values; corrected by re-uploading from bot/ with full values and verifying via wrangler secret list.

(One internal test-path fix in commands.test.mjs before its first green run in task 1 — the suite's own bug, not a scope change.) ExecutionContext parameter in webhook.ts is accepted-but-unused per the standard Workers fetch signature.

Live-debug remediations during the task 3 walkthrough (deployment-environment findings, all resolved before user approval):

• [Deployment misconfiguration] webhook registered without the route path — first setWebhook armed the bare workers.dev origin; Telegram answered ok but updates landed on / → 404, silent drop. Remedy: re-registered with /telegram/webhook appended; then hardened in-repo: set-webhook.mjs now auto-appends /telegram/webhook when the configured URL has no path (and fails fast on unparseable URLs, never echoing values — T-02-04). Commit d600d6e.
• [Stale runtime secret] production BOT_TOKEN was revoked — Worker-runtime secret held a dead token, so webhook updates 401'd inside the Worker; wrangler tail surfaced the failure. Remedy: npx wrangler secret put BOT_TOKEN re-run from bot/ with the value from .dev.vars; verified via wrangler secret list + live /start delivery.
• [Empty webhook + pending update queue] re-armed via scripts — after the URL/secret fixes, re-ran set-webhook.mjs and confirmed getWebhookInfo (url correct, pending_update_count → 0, last_error freed).
• [Menu cache] menu//-autocomplete initially empty — Telegram client-side caching of setMyCommands; resolved by explicitly calling setChatMenuButton (type commands) and registering the all_private_chats scope in addition to the default + ms scopes. User then confirmed both surfaces listed exactly /help and /privacy and approved.

Note for future deploys: command-menu registration and the menu button were found to need the all_private_chats scope + explicit setChatMenuButton in addition to the default scope; register-commands.mjs may be extended to include these one-time calls in a later plan (out of scope here).

Threat Model Dispositions Applied

• T-02-03 (webhook flooding/DoS): secret-token header constant-time compare happens in grammY's adapter before bot processing; no KV touched pre-check
• T-02-01 (spoofed identity → token): only the validateInitData→mintSession path mints; rejections return category-only 401s
• T-02-02 (stale-but-valid replay): 900 s freshness window + rotate-on-new deletion in mintSession
• T-02-04 (information disclosure): D-14 category-only logging; scripts print only ok/result/error_description — no token or secret values (grep-verified)
• T-02-06 (KV persistence drift): endpoint adds no storage writes; PG1/PG2 gates automatically cover src/webhook.ts (no .put( present)

Known Stubs

None. Every export is fully wired; no placeholder copy, no TODO/FIXME, no components without data sources. KV_ID_PLACEHOLDER in wrangler.jsonc is a deliberate deploy-checkpoint input (documented in plan task 3), not a code stub.

User Setup Required (deploy checkpoint — plan task 3)

RESOLVED — credentials were provisioned by the user (@BotFather token + WEBHOOK_SECRET in .dev.vars, wrangler login active). Deploy chain complete — see "Deployment Record". Real-client walkthrough a–e observed and approved — see "Real-Client Walkthrough Outcome". Nothing remains for the user on this plan.

Next Phase Readiness

• Phase 3's Worker inherits: mixed static-assets + existing routes are additive (/telegram/webhook and /api/session keep their paths); the chat_sessions binding and TTL conventions are already enforced by the green PG1/PG2 gates
• /api/session is live the moment the Worker deploys — the Phase 4 Mini App caller only needs to POST its verbatim Telegram.WebApp.initData
• Command-surface gates (CS1–CS6) guard all future copy/menu edits against drift from the strings module

Self-Check: PASSED

• All 9 created files verified present on disk
• Commits verified in history: b4393fb (task 1), df3b7d6 (task 2); no unintended file deletions in either commit
• npm test -w bot → [runner] 27 passed, 0 failed; npm run bot:typecheck exit 0
• wrangler deploy --dry-run exit 0; node --check clean on both scripts
• task 3: commits 492a97b (KV id) and d600d6e (set-webhook hardening) verified in history; deployed Worker URL reachable (404 fallback), secrets in wrangler secret list, getWebhookInfo ok (pending 0), getMyCommands read-back ok (both scopes), getChatMenuButton → commands, live 401/401/401/405/404 smokes green, KV list baseline [], user-approved walkthrough a–e (see 02-03-APPROVAL.md)
• STATE.md / ROADMAP.md untouched (orchestrator-owned)

---

Phase: 02-bot-skeleton-initdata-security Completed: 2026-10-22 (tasks 1–3 all complete; task 3 deploy + real-client walkthrough APPROVED by user)