feat(03-01): GEO-02 server half both directions — chat-keyboard fallback + GET /api/location + POST /api/location-fallback (claim-scoped)

- handlers/location-fallback.ts: requestLocationFallback (ReplyKeyboardMarkup request_location:true copy from strings.ts), recordSharedPin, registerLocationFallback (filters message.location, T-03-03)
- strings.ts: awaitingPin/shareLocationButton/pinReceived in en+ms (CS1 parity) — all bot copy stays in strings.ts
- bot.ts: createBot threads env.chat_sessions into the fallback handler; optional client fetch seam for tests; one-caller rule documented
- webhook.ts: GET /api/location relay + POST /api/location-fallback trigger, both resolve chat_id & locale from getClaimByToken CLAIM, never client input (T-03-01/26/27); telegram-send failure is category-only 502 (T-03-28)
- location-pin.test.mjs: LP1–LP14 (TTL contract, range guard, cross-user isolation both routes, locale split); LP12/LP13 patch node-fetch's cached default (grammy's node shim transport), then restore
- CS4 scope untouched (handlers/ not scanned); CS1 parity automatic

bot/src/bot/bot.ts

@@ -10,17 +10,28 @@
  * text replies only — no reply menus, no inline button payloads, no
  * callback routes, no menu augmentation per request. The persistent menu
  * is registered once by scripts/register-commands.mjs (D-03).
+ *
+ * GEO-02 (structural): createBot threads env.chat_sessions into the
+ * location-fallback handler (handlers/location-fallback.ts) — the ONE
+ * deliberate exception to the D-02 text-only rule (its Telegram send
+ * attaches a reply-markup location request). Also: requestLocationFallback
+ * has exactly ONE caller — handleLocationFallback in src/webhook.ts. If a
+ * second caller ever appears, that is a design change, not a refactor.
  */
 import { Bot } from "grammy";
 import type { Env } from "../config.ts";
+import { registerLocationFallback } from "./handlers/location-fallback.ts";
 import { registerHelp } from "./commands/help.ts";
 import { registerPrivacy } from "./commands/privacy.ts";
 import { registerStart } from "./commands/start.ts";
 
-export function createBot(env: Env): Bot {
-  const bot = new Bot(env.BOT_TOKEN);
+export function createBot(env: Env, opts: { baseFetch?: typeof fetch } = {}): Bot {
+  const bot = opts.baseFetch
+    ? new Bot(env.BOT_TOKEN, { client: { fetch: opts.baseFetch } })
+    : new Bot(env.BOT_TOKEN);
   registerStart(bot); // /start + /mula (D-04)
   registerHelp(bot); // /help
   registerPrivacy(bot); // /privacy + /privasi (D-04)
+  registerLocationFallback(bot, env.chat_sessions); // GEO-02 location reply fallback
   return bot;
 }

bot/src/bot/handlers/location-fallback.ts

@@ -0,0 +1,72 @@
+/*
+ * location-fallback.ts — GEO-02 chat-keyboard location fallback.
+ * -------------------------------------------------------------------
+ * When in-app location fails (denied permission, or Desktop Telegram
+ * which has NO geolocation at all — Telegram-Mini-Apps issue #77), the
+ * bot sends a ReplyKeyboardMarkup with request_location: true. The
+ * user taps it, Telegram's native location picker opens, and the bot
+ * receives the shared pin as a normal Message with a `location` field.
+ *
+ * That pin is written to TTL-only KV (kv/location-pin.ts) keyed by
+ * chat_id. The open Mini App polls GET /api/location (webhook.ts) to
+ * pick it up — Telegram has NO push channel from chat to WebView, so
+ * the relay is server-mediated by necessity.
+ *
+ * D-02 structural note: this handler is the ONE deliberate exception
+ * to the Phase-2 "plain text only" command-surface rule. The GEO-02
+ * reply keyboard is required by the platform; it lives in handlers/
+ * and is NOT part of commandSources in commands.test.mjs's CS4 gate
+ * (which scans only bot.ts + commands/*). See the CS4 decision in the
+ * plan.
+ *
+ * All copy comes from src/i18n/strings.ts — nothing inline here.
+ */
+import type { Bot, Context } from "grammy";
+import { pickLocale, strings } from "../../i18n/strings.ts";
+import type { Locale } from "../../i18n/strings.ts";
+import { writePin } from "../../kv/location-pin.ts";
+import type { LocationPinKv } from "../../kv/location-pin.ts";
+
+/** Send the awaiting-pin prompt + location keyboard (GEO-02).
+ *
+ *  grammY note: the plan's original shape called `bot.chat.sendMessage`,
+ *  but grammY 1.46 exposes no `bot.chat` proxy — `bot.api.sendMessage` is
+ *  the same request over the same API surface. The Mini App's
+ *  POST /api/location-fallback route (webhook.ts) is the ONLY caller. */
+export async function requestLocationFallback(bot: Bot, chatId: number, locale: Locale): Promise<void> {
+  await bot.api.sendMessage(chatId, strings[locale].awaitingPin, {
+    reply_markup: {
+      keyboard: [[{ text: strings[locale].shareLocationButton, request_location: true }]],
+      resize_keyboard: true,
+      one_time_keyboard: true,
+    },
+  });
+}
+
+/** Persist a user-shared pin to TTL-only KV (GEO-03, PRIV-02). */
+export async function recordSharedPin(
+  kv: LocationPinKv,
+  chatId: number,
+  loc: { latitude: number; longitude: number; horizontal_accuracy?: number },
+): Promise<void> {
+  await writePin(kv, chatId, {
+    latitude: loc.latitude,
+    longitude: loc.longitude,
+    horizontal_accuracy: loc.horizontal_accuracy ?? null,
+  });
+}
+
+/** Register the GEO-02 message handler. Filters on ctx.message?.location
+ *  — Telegram-authenticated updates only (T-03-03), so a fabricated pin
+ *  can never enter KV. */
+export function registerLocationFallback(bot: Bot, kv: LocationPinKv): void {
+  bot.on("message", async (ctx: Context) => {
+    const location = ctx.message?.location;
+    if (!location) return;
+    const chatId = ctx.chat?.id;
+    if (chatId === undefined) return;
+    await recordSharedPin(kv, chatId, location);
+    const locale = pickLocale(ctx.from?.language_code);
+    await ctx.reply(strings[locale].pinReceived, { link_preview_options: { is_disabled: true } });
+  });
+}

bot/src/i18n/strings.ts

@@ -28,6 +28,13 @@ export interface BotStrings {
   /** D-03: lists only commands that exist in this phase — derived lines
    *  ("cmd — description") feed the setMyCommands registration script. */
   helpMenu: string;
+  /** GEO-02: chat-keyboard fallback prompt — bot tells the user to share a pin. */
+  awaitingPin: string;
+  /** GEO-02: the reply-keyboard button label (request_location: true). */
+  shareLocationButton: string;
+  /** GEO-02: confirmation after the user's shared pin has been recorded
+   *  in the TTL-only location-pin KV (GEO-03). */
+  pinReceived: string;
 }
 
 export type Locale = "en" | "ms";
@@ -42,6 +49,9 @@ export const strings: Record<Locale, BotStrings> = {
       "What araharah never keeps: your location, your routes, your trip history, any profile about you.",
     helpMenu:
       "Commands:\n/help — How araharah works and what it keeps\n/privacy — What araharah stores and never stores",
+    awaitingPin: "Send me a pin in this chat and I'll use it as your starting point.",
+    shareLocationButton: "Share my location",
+    pinReceived: "Got it — your starting point is set.",
   },
   ms: {
     startIntro:
@@ -52,6 +62,9 @@ export const strings: Record<Locale, BotStrings> = {
       "Yang araharah tidak pernah simpan: lokasi anda, laluan anda, sejarah perjalanan anda, apa-apa profil tentang anda.",
     helpMenu:
       "Arahan:\n/help — Cara araharah berfungsi dan apa yang ia simpan\n/privacy — Apa yang araharah simpan dan tidak pernah simpan",
+    awaitingPin: "Hantar saya pin dalam chat ini dan saya akan gunakannya sebagai titik mula anda.",
+    shareLocationButton: "Kongsi lokasi saya",
+    pinReceived: "Baik — titik mula anda sudah ditetapkan.",
   },
 };
 

bot/src/webhook.ts

@@ -21,6 +21,18 @@
  *     own invariant (D-07 — best-effort under KV eventual consistency, see
  *     sessions.ts) — this endpoint adds no extra branch and no extra write
  *     path (T-02-06).
+ *   GET  /api/location      → GEO-02 relay (T-03-01): the Mini App polls
+ *     here with its memory-held Bearer token; the token resolves through
+ *     getClaimByToken and the KV key loc:<chat_id> derives from the
+ *     CLAIM — never from a client-supplied id — so one user's token can
+ *     never read another user's pin. No pin or expired token → honest
+ *     nulls / 401, nothing fabricated.
+ *   POST /api/location-fallback → GEO-02 keyboard trigger (T-03-26): the
+ *     app's denied card asks the BOT to send the request_location reply
+ *     keyboard into the user's own chat. The target chat_id AND the
+ *     locale come from the resolved claim (T-03-27) — the request body
+ *     is never read, and no chat id or language is accepted from the
+ *     client. A rejected Telegram send is a category-only 502 (T-03-28).
  * Anything else → 404.
  *
  * D-14: the ONLY log statements are category-only — malformed/tampered/stale
@@ -33,8 +45,11 @@
 import { webhookCallback } from "grammy";
 import type { Env } from "./config.ts";
 import { createBot } from "./bot/bot.ts";
-import { mintSession } from "./kv/sessions.ts";
+import { requestLocationFallback } from "./bot/handlers/location-fallback.ts";
+import { mintSession, getClaimByToken } from "./kv/sessions.ts";
+import { getPin } from "./kv/location-pin.ts";
 import { validateInitData } from "./security/initdata.ts";
+import { pickLocale } from "./i18n/strings.ts";
 
 export default {
   async fetch(req: Request, env: Env, _ctx: ExecutionContext): Promise<Response> {
@@ -58,6 +73,12 @@ export default {
     if (url.pathname === "/api/session") {
       return handleSession(req, env);
     }
+    if (url.pathname === "/api/location") {
+      return handleLocation(req, env);
+    }
+    if (url.pathname === "/api/location-fallback") {
+      return handleLocationFallback(req, env);
+    }
     return new Response("Not found", { status: 404 });
   },
 } satisfies ExportedHandler<Env>;
@@ -112,3 +133,70 @@ async function handleSession(req: Request, env: Env): Promise<Response> {
   });
   return new Response(JSON.stringify({ token }), { status: 200, headers: { "content-type": "application/json" } });
 }
+
+/** GEO-02 relay (T-03-01): the Mini App polls here with its memory-held
+ *  Bearer token to pick up a pin the user shared in chat. V4 Access
+ *  Control (RESEARCH §Security Domain): the bearer token is resolved via
+ *  getClaimByToken; a missing/expired token is a 401. The KV key is
+ *  derived from the CLAIM's chat_id — NEVER from a client-supplied chat
+ *  id, so one user's token can never read another user's pin. */
+async function handleLocation(req: Request, env: Env): Promise<Response> {
+  if (req.method !== "GET") return new Response("Method not allowed", { status: 405 });
+  const header = req.headers.get("authorization") ?? "";
+  const match = header.match(/^Bearer ([A-Za-z0-9-]+)$/);
+  const token = match !== null && match[1] ? match[1] : null;
+  const claim = token === null ? null : await getClaimByToken(env.chat_sessions, token);
+  if (claim === null) {
+    console.log("[location] rejected: unauthorized"); // category ONLY (D-14)
+    return new Response(JSON.stringify({ error: "unauthorized" }), {
+      status: 401,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  const pin = await getPin(env.chat_sessions, claim.chat_id);
+  return new Response(JSON.stringify({ pin }), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** GEO-02 trigger (T-03-26): the Mini App's denied card taps ASK VIA CHAT
+ *  and POSTs here; the Worker asks the BOT to send the request_location
+ *  reply keyboard in the user's own chat. Same V4 access control as
+ *  handleLocation — the target chat_id comes from the resolved CLAIM,
+ *  never from the request body, so one user's token can never push a
+ *  keyboard into another user's chat.
+ *
+ *  The locale comes from `claim.language_code`, which mintSession already
+ *  recorded from the validated initData — the Worker does NOT re-derive it
+ *  from client input, and no language is accepted from the request body
+ *  (T-03-27). */
+async function handleLocationFallback(req: Request, env: Env): Promise<Response> {
+  if (req.method !== "POST") return new Response("Method not allowed", { status: 405 });
+  const header = req.headers.get("authorization") ?? "";
+  const match = header.match(/^Bearer ([A-Za-z0-9-]+)$/);
+  const token = match !== null && match[1] ? match[1] : null;
+  const claim = token === null ? null : await getClaimByToken(env.chat_sessions, token);
+  if (claim === null) {
+    console.log("[location-fallback] rejected: unauthorized"); // category ONLY (D-14)
+    return new Response(JSON.stringify({ error: "unauthorized" }), {
+      status: 401,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  try {
+    await requestLocationFallback(createBot(env), claim.chat_id, pickLocale(claim.language_code));
+    return new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  } catch {
+    // Telegram rejected the send (user blocked the bot, chat not found, rate
+    // limit). Category only — never the chat id, never the error text (D-14, T-03-28).
+    console.log("[location-fallback] failed: telegram-send");
+    return new Response(JSON.stringify({ error: "unavailable" }), {
+      status: 502,
+      headers: { "content-type": "application/json" },
+    });
+  }
+}