---
phase: 03-mini-app-shell-geolocation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - web/package.json
  - web/tsconfig.json
  - web/vite.config.ts
  - web/index.html
  - web/test/runner.mjs
  - web/test/harness.mjs
  - bot/src/kv/location-pin.ts
  - bot/src/bot/handlers/location-fallback.ts
  - bot/src/bot/bot.ts
  - bot/src/i18n/strings.ts
  - bot/src/webhook.ts
  - bot/test/location-pin.test.mjs
  - bot/test/privacy.test.mjs
  - package.json
autonomous: true
requirements: [GEO-02, GEO-03]
must_haves:
  decisions_implemented:
    - "D-01: TypeScript + Vite frontend, no UI framework, MapLibre GL JS v6 bundled — the workspace foundation Phases 4–6 build on"
    - "D-02: app source in a `web/` npm workspace; theme consumed as a build-time dependency, not CDN"
  truths:
    - "`web/` exists as an npm workspace with Vite + TypeScript configured and `npm test -w web` runs"
    - "A dev-signed initData string can be produced by a test helper (the keystone for every later web test)"
    - "`GET /api/location` validates a Bearer session token and returns only that token's own chat pin, or 401"
    - "`POST /api/location-fallback` validates the same token and asks the bot to send the location keyboard into THAT claim's chat, in the claim's language"
    - "The bot sends a ReplyKeyboardMarkup with request_location:true and records the shared pin in TTL-only KV"
    - "Every KV write in the new location-pin module carries an explicit expirationTtl on the same line"
  artifacts:
    - path: "web/package.json"
      provides: "@araharah/web workspace manifest with test/typecheck/dev/build scripts"
    - path: "web/tsconfig.json"
      provides: "DOM-targeted strict TS config mirroring bot/tsconfig.json flags (+ resolveJsonModule for the basemap style import)"
    - path: "web/test/runner.mjs"
      provides: "hand-rolled zero-dependency test runner (copied from bot/test/runner.mjs)"
    - path: "web/test/harness.mjs"
      provides: "zero-dependency test registry (copied from bot/test/harness.mjs)"
    - path: "bot/src/kv/location-pin.ts"
      provides: "TTL-only KV location-pin layer (put/get/delete by chat id)"
    - path: "bot/src/bot/handlers/location-fallback.ts"
      provides: "GEO-02 keyboard sender + message.location receiver"
    - path: "bot/src/webhook.ts"
      provides: "GET /api/location relay + POST /api/location-fallback keyboard trigger, both Bearer-gated"
  key_links:
    - from: "bot/src/webhook.ts"
      to: "bot/src/kv/sessions.ts"
      via: "getClaimByToken(env.chat_sessions, token) — derives chat_id from the CLAIM, never from a client-supplied id"
      pattern: "getClaimByToken"
    - from: "bot/src/webhook.ts"
      to: "bot/src/bot/handlers/location-fallback.ts"
      via: "handleLocationFallback calls requestLocationFallback(createBot(env), claim.chat_id, pickLocale(claim.language_code)) — the ONLY caller, so the export is never dead code"
      pattern: "requestLocationFallback"
    - from: "bot/src/bot/handlers/location-fallback.ts"
      to: "bot/src/kv/location-pin.ts"
      via: "writePin(kv, chatId, {latitude, longitude}) after message.location arrives"
      pattern: "writePin"
---

<objective>
Stand up the `web/` npm workspace shell (D-01, D-02) with the Wave-0 test runner, and build the
server half of GEO-02: the TTL-only location-pin KV module, the bot's chat-keyboard fallback handler,
and BOTH Worker routes that relay a chat-shared pin to the open Mini App — `GET /api/location`
(the poll) and `POST /api/location-fallback` (the app→bot keyboard trigger).

Purpose: GEO-02 is impossible without a chat→WebView relay — Telegram has no push channel from
chat to WebView, so the bot must write the pin to KV and the app must poll an authenticated endpoint
(RESEARCH §Pattern 3). The trigger direction matters just as much: the denied card's ASK VIA CHAT
CTA (plan 03-03) and the Desktop leg of the device matrix (plan 03-04) both need a route that makes
the bot send the keyboard. Both directions land here.

Output: `web/` workspace + test runner; `bot/src/kv/location-pin.ts`; `bot/src/bot/handlers/location-fallback.ts`;
`GET /api/location` + `POST /api/location-fallback` routes; `bot/test/location-pin.test.mjs`; extended `privacy.test.mjs`.
</objective>

<execution_context>
@$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
@$HOME/.config/opencode/get-shit-done/templates/summary.md

**Commit discipline:** commit after EACH task (one commit per task, atomic). If task 3 overruns
its context budget, split it rather than pushing through — this plan touches 14 files across 3 tasks,
which is above the 10-file warning line and is only safe because the code is pre-specified near-verbatim.
A task that needs more than ~7 files should be decomposed, not absorbed.
</execution_context>

<context>
@AGENTS.md
@.planning/phases/03-mini-app-shell-geolocation/03-CONTEXT.md
@.planning/phases/03-mini-app-shell-geolocation/03-RESEARCH.md
@.planning/phases/03-mini-app-shell-geolocation/03-PATTERNS.md
@bot/src/webhook.ts
@bot/src/kv/sessions.ts
@bot/src/bot/bot.ts
@bot/src/bot/commands/start.ts
@bot/src/i18n/strings.ts
@bot/src/config.ts
@bot/test/privacy.test.mjs
@bot/test/commands.test.mjs
@bot/test/webhook.test.mjs
@bot/test/runner.mjs
@bot/test/harness.mjs
@bot/package.json
@bot/tsconfig.json
@package.json
@theme/package.json

<interfaces>
From `bot/src/kv/sessions.ts` (the contract `location-pin.ts` mirrors):

```typescript
export const SESSION_TTL_SECONDS = 900;

export interface SessionClaim {
  user_id: number;
  chat_id: number;
  issued_at: number; // seconds-since-epoch
  language_code: string | null;
}

interface KvLike {
  get(key: string): Promise<string | null>;
  put(key: string, value: string, options: { expirationTtl: number }): Promise<void>;
  delete(key: string): Promise<void>;
}

export async function mintSession(kv: MintSessionKv, claim: SessionClaim): Promise<string>;
export async function getClaimByToken(kv: MintSessionKv, token: string): PromiseSessionClaim | null;
export async function getTokenForChat(kv: MintSessionKv, chatId: number): Promise<string | null>;
```

From `bot/src/config.ts`:
```typescript
export interface Env {
  BOT_TOKEN: string;
  WEBHOOK_SECRET: string;
  chat_sessions: KVNamespace;
}
```

From `bot/src/webhook.ts` — the dispatch shape to extend:
```typescript
export default {
  async fetch(req: Request, env: Env, _ctx: ExecutionContext): Promise<Response> {
    const url = new URL(req.url);
    if (url.pathname === "/telegram/webhook") { /* ... */ }
    if (url.pathname === "/api/session") { return handleSession(req, env); }
    return new Response("Not found", { status: 404 });
  },
} satisfies ExportedHandler<Env>;
```

From `bot/test/webhook.test.mjs` — the dev-signing helper shape (copy this, do NOT reimplement HMAC):
```javascript
function dataCheckString(fields) {
  return fields
    .filter(([key]) => key !== "hash" && key !== "signature")
    .slice()
    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
    .map(([key, value]) => `${key}=${value}`)
    .join("\n");
}
function telegramSecretKey(botToken) {
  return createHmac("sha256", "WebAppData").update(botToken, "utf8").digest();
}
function buildInitData(fields) {
  const hash = createHmac("sha256", telegramSecretKey(TEST_TOKEN))
    .update(dataCheckString(fields), "utf8")
    .digest("hex");
  const wire = fields.map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join("&");
  return `${wire}&hash=${hash}`;
}
```
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>task 1: `web/` workspace scaffold + Wave-0 test runner (D-01, D-02, D-11, D-14)</name>
  <files>web/package.json, web/tsconfig.json, web/vite.config.ts, web/index.html, web/test/runner.mjs, web/test/harness.mjs, package.json</files>
  <read_first>
    - `package.json` (root — see current workspaces array and bot:* delegate script block)
    - `bot/package.json` (the workspace manifest shape to mirror exactly)
    - `bot/tsconfig.json` (the strictness flags to preserve)
    - `bot/test/runner.mjs` and `bot/test/harness.mjs` (copy verbatim)
    - `.planning/phases/03-mini-app-shell-geolocation/03-RESEARCH.md` §Standard Stack (pinned versions)
  </read_first>
  <action>
**Step A — `web/package.json`.** Create `web/package.json` mirroring `bot/package.json` exactly in shape:

```json
{
  "name": "@araharah/web",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node test/runner.mjs",
    "typecheck": "tsc --noEmit",
    "dev": "vite",
    "build": "vite build",
    "capture": "node scripts/capture.mjs"
  },
  "dependencies": {
    "maplibre-gl": "^6.15.0",
    "@araharah/theme": "*"
  },
  "devDependencies": {
    "vite": "^8.3.5",
    "typescript": "^5.9.3",
    "playwright": "^1.50.0"
  }
}
```
Pinned versions come from RESEARCH §Standard Stack (maplibre-gl 6.15.0, vite 8.3.5, typescript 5.9.3 — do NOT bump to 7.x, playwright ^1.50.0).

**Do NOT add `@types/telegram-web-app`.** RESEARCH §Don't Hand-Roll recommends it for the *full* `WebApp` surface, but this phase consumes exactly 12 members behind one narrow hand-rolled interface (`TelegramWebAppLike` in `web/src/telegram/webapp.ts`, plan 03-02 task 3). A narrow interface is required here because every test fake and every harness mock is a plain object literal matching it — pulling in the 500-member official `WebApp` type would force each fake to satisfy ~50 unimplemented members. This retires RESEARCH assumption A2 by construction: there is no upstream typing to drift from. Do not add the dependency later "for completeness."

**Step B — `web/tsconfig.json`.** Copy `bot/tsconfig.json` verbatim and change exactly THREE keys (everything else stays byte-identical):
- `"lib": ["ES2023", "DOM", "DOM.Iterable"]` (was `["ES2023"]`)
- `"types": ["vite/client"]` (was `["@cloudflare/workers-types"]`)
- **`"resolveJsonModule": true` (ADDED — not present in `bot/tsconfig.json`)**. This third key is pre-authorized and REQUIRED: plan 03-03 task 2 imports `@araharah/theme/basemap/liberty-rams.json` as a module (`import ramsStyle from "@araharah/theme/basemap/liberty-rams.json"`), which is a TypeScript error without it. Do NOT add `esModuleInterop`/`allowSyntheticDefaultImports` — Vite's bundler resolution + `resolveJsonModule` covers the default import.

Keep every other flag byte-identical: `"target": "ES2023"`, `"module": "ESNext"`, `"moduleResolution": "bundler"`, `"strict": true`, `"noUncheckedIndexedAccess": true`, `"verbatimModuleSyntax": true`, `"allowImportingTsExtensions": true`, `"noEmit": true`, `"skipLibCheck": true`, `"forceConsistentCasingInFileNames": true`, `"include": ["src"]`. Do NOT add `"jsx"` (no framework, D-01).

**Step C — `web/vite.config.ts`.**
```typescript
import { defineConfig } from "vite";

export default defineConfig({
  base: "/",
  build: {
    outDir: "dist",
    emptyOutDir: true,
    target: "es2022",
  },
  server: {
    port: 5173,
    strictPort: true,
  },
});
```

**Step D — `web/index.html`.** Minimal shell entry. Exact viewport meta (viewport-fit=cover is the safe-area enabler, UI-SPEC §Safe-Area Handling):
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
  <title>araharah</title>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>
```
Do NOT add a `<script src=".../telegram-web-app.js">` tag — Telegram injects `window.Telegram.WebApp` automatically inside the WebView (RESEARCH §State of the Art). Do NOT copy the mockups' Tailwind Play CDN or Google Fonts links — D-02/D-14 replace them with build-time `@araharah/theme` imports (that wiring lands in plan 03).

**Step E — `web/test/runner.mjs` and `web/test/harness.mjs`.** Copy `bot/test/runner.mjs` and `bot/test/harness.mjs` **verbatim** — they are directory-relative and workspace-agnostic. Update only the header comment block of `runner.mjs` to name the precedent chain: "Same hand-rolled shape as theme/scripts/audit.test.mjs (Phase 1) and bot/test/ (Phase 2)."

**Step F — root `package.json`.** Add `"web"` to the `workspaces` array (after `"bot"`), and add these delegate scripts mirroring the existing `bot:*` block (D-02 ergonomics):
```json
"web:test": "npm test -w web",
"web:typecheck": "npm run typecheck -w web",
"web:dev": "npm run dev -w web",
"web:build": "npm run build -w web",
"web:capture": "npm run capture -w web"
```
Add the file header comment line to each new web/src file in later tasks: "`filename.ts` — one-line purpose (decision IDs)." then a dashed rule, then the contract in prose (PATTERNS §Shared Pattern 1).
  </action>
  <verify>
    <automated>cd /home/C-Fu/araharah && npm install 2>&1 | tail -5 && node -e "const p=require('./package.json'); if(!p.workspaces.includes('web')) throw new Error('web workspace missing'); ['web:test','web:typecheck','web:dev','web:build','web:capture'].forEach(k=>{if(!p.scripts[k]) throw new Error('missing script '+k)}); console.log('root OK')" && node web/test/runner.mjs</automated>
  </verify>
  <acceptance_criteria>
    - `node -e "require('./package.json').workspaces.includes('web')"` exits 0
    - `grep -c '"web:' package.json` returns 5 (test, typecheck, dev, build, capture)
    - `diff <(tail -n +11 bot/test/runner.mjs) <(tail -n +11 web/test/runner.mjs)` produces no output (bodies identical past the header)
    - `diff bot/test/harness.mjs web/test/harness.mjs` produces no output (verbatim copy)
    - `grep -c 'viewport-fit=cover' web/index.html` returns 1
    - `grep -q 'telegram-web-app.js' web/index.html` must FAIL (no script tag for the Telegram SDK)
    - `grep -q '"noUncheckedIndexedAccess": true' web/tsconfig.json` exits 0
    - `grep -q '"resolveJsonModule": true' web/tsconfig.json` exits 0 (pre-authorized third key — required by 03-03's style-JSON import)
    - `node -e "const t=require('./web/tsconfig.json'); const keys=Object.keys(t.compilerOptions); console.log(keys.length)"` — the file has exactly the three keys changed above plus the inherited set; nothing else was touched
    - `npm test -w web` exits 0 with `[runner] 0 passed, 0 failed` (empty suite is a pass)
  </acceptance_criteria>
  <done>web/ workspace is installed, typecheckable, testable, and wired into root delegates; test runner matches repo convention verbatim.</done>
</task>

<task type="auto">
  <name>task 2: TTL-only location-pin KV module + privacy gate extension (GEO-03, PRIV-02)</name>
  <files>bot/src/kv/location-pin.ts, bot/test/privacy.test.mjs</files>
  <read_first>
    - `bot/src/kv/sessions.ts` (the entire contract shape to mirror — KvLike, put-line discipline, defensive read)
    - `bot/test/privacy.test.mjs` (the PG1/PG2 gate and the storageModules list at line 25)
  </read_first>
  <action>
**Create `bot/src/kv/location-pin.ts`.** Copy `bot/src/kv/sessions.ts`'s header-comment style, `KvLike` interface, `KvLike` structural typing, named-TTL-constant discipline, and defensive read pattern verbatim. Concrete content:

Header comment (purpose + D-IDs + the storage contract prose — PATTERNS §Shared Pattern 1):
```
/*
 * location-pin.ts — TTL-only KV location-pin layer (GEO-02, GEO-03, PRIV-02).
 * ----------------------------------------------------------------------
 * Storage contract (privacy by construction — GEO-03, PRIV-02):
 *   - EVERY write to `chat_sessions` carries an explicit `expirationTtl`
 *     on its call line — no write path in this module can persist
 *     without a TTL. privacy.test.mjs's PG1 gate pins this.
 *   - The record is exactly Telegram's Location fields: latitude,
 *     longitude, horizontal_accuracy (optional). Nothing else is ever
 *     serialized. A 4th property means drift.
 *   - The pin is keyed by chat_id, derived from the SESSION CLAIM
 *     (never from a client-supplied id) — a token resolves to exactly
 *     one chat_id, and the KV key is `loc:<chat_id>`.
 *
 * Key scheme:
 *   loc:<chat_id>   → JSON LocationPin record
 *
 * GEO-03 note: this pin lives only in KV with a TTL. The client never
 * persists a coordinate anywhere (D-07) — this is the ONLY place a
 * coordinate ever exists server-side, and it expires.
 */
```

Exported constants and types:
```typescript
export const PIN_TTL_SECONDS = 300;

export interface LocationPin {
  latitude: number;
  longitude: number;
  horizontal_accuracy: number | null;
}

interface KvLike {
  get(key: string): Promise<string | null>;
  put(key: string, value: string, options: { expirationTtl: number }): Promise<void>;
  delete(key: string): Promise<void>;
}

export interface LocationPinKv extends KvLike {}
```

Functions (mirroring `sessions.ts` shapes):
```typescript
export async function writePin(kv: LocationPinKv, chatId: number, pin: LocationPin): Promise<void> {
  await kv.put(`loc:${chatId}`, JSON.stringify(pin), { expirationTtl: PIN_TTL_SECONDS });
}

export async function getPin(kv: LocationPinKv, chatId: number): Promise<LocationPin | null> {
  const raw = await kv.get(`loc:${chatId}`);
  if (raw === null) return null;
  try {
    const parsed: unknown = JSON.parse(raw);
    if (
      parsed &&
      typeof parsed === "object" &&
      "latitude" in parsed &&
      "longitude" in parsed &&
      typeof (parsed as LocationPin).latitude === "number" &&
      typeof (parsed as LocationPin).longitude === "number" &&
      Math.abs((parsed as LocationPin).latitude) <= 90 &&
      Math.abs((parsed as LocationPin).longitude) <= 180
    ) {
      return parsed as LocationPin;
    }
    return null;
  } catch {
    return null;
  }
}

export async function clearPin(kv: LocationPinKv, chatId: number): Promise<void> {
  await kv.delete(`loc:${chatId}`);
}
```
The `Math.abs(...) <= 90 / <= 180` range check is the V5 Input Validation mitigation from RESEARCH §Security Domain — reject absurd coordinates rather than flying the camera to null island.

**Extend `bot/test/privacy.test.mjs`.** At line 25, change:
```javascript
const storageModules = ["kv/sessions.ts"].map((rel) => path.join(SRC, ...rel.split("/")));
```
to:
```javascript
const storageModules = ["kv/sessions.ts", "kv/location-pin.ts"].map((rel) => path.join(SRC, ...rel.split("/")));
```
That single edit brings the new module under the existing PG1 (same-line `expirationTtl`, named constant) and PG2 (no persistence-shaped exports) gates automatically.

**Test-fake note for the later test file:** the KV fake in `bot/test/webhook.test.mjs` already logs `expirationTtl` per put — reuse that shape verbatim in `bot/test/location-pin.test.mjs` (task 3).
  </action>
  <verify>
    <automated>cd /home/C-Fu/araharah && npm test -w bot 2>&1 | tail -5 && grep -n 'kv/location-pin.ts' bot/test/privacy.test.mjs</automated>
  </verify>
  <acceptance_criteria>
    - `grep -v '^ \*\|^/\*\|^$' bot/src/kv/location-pin.ts | grep -c '\.put('` returns 1 and that line contains `expirationTtl: PIN_TTL_SECONDS`
    - `grep -n 'kv/location-pin.ts' bot/test/privacy.test.mjs` exits 0 (module is in the scanned list)
    - `grep -q 'export const PIN_TTL_SECONDS = 300;' bot/src/kv/location-pin.ts` exits 0
    - `npm test -w bot` exits 0 and reports `[runner] N passed, 0 failed` with N >= 15 (Phase 2's suite plus the extended gate)
    - `node -e "const s=require('fs').readFileSync('bot/src/kv/location-pin.ts','utf8'); if(!/location\s*:\s*\`loc:/.test(s)) throw new Error('key scheme wrong'); if(!/Math\.abs/.test(s)) throw new Error('range check missing')" ` exits 0
  </acceptance_criteria>
  <done>location-pin.ts is TTL-only by construction, range-validated on read, and covered by the existing privacy gate.</done>
</task>

<task type="auto">
  <name>task 3: GEO-02 bot half — chat keyboard fallback + `GET /api/location` route + tests</name>
  <files>bot/src/bot/handlers/location-fallback.ts, bot/src/bot/bot.ts, bot/src/i18n/strings.ts, bot/src/webhook.ts, bot/test/location-pin.test.mjs</files>
  <read_first>
    - `bot/src/bot/bot.ts` (the registration pattern)
    - `bot/src/bot/commands/start.ts` (handler + i18n import + register pattern)
    - `bot/src/i18n/strings.ts` (BotStrings interface + en/ms key-set parity)
    - `bot/src/webhook.ts` (dispatch pattern lines 39-63, method gate line 84, auth+service+response pattern lines 99-113)
    - `bot/src/kv/sessions.ts` (`getClaimByToken`)
    - `bot/src/kv/location-pin.ts` (written in task 2 — read your own output)
    - `bot/test/commands.test.mjs` (CS4 keyboard gate — you must decide whether to extend it)
    - `bot/test/webhook.test.mjs` (fake KV + makeEnv + handler import pattern)
  </read_first>
  <action>
**Step A — `bot/src/i18n/strings.ts`.** Add two keys to the `BotStrings` interface (after `helpMenu`), both with doc-comments:
```typescript
  /** 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;
```
Add to `strings.en`:
```typescript
    awaitingPin: "Send me a pin in this chat and I'll use it as your starting point.",
    shareLocationButton: "Share my location",
```
Add to `strings.ms`:
```typescript
    awaitingPin: "Hantar saya pin dalam chat ini dan saya akan gunakannya sebagai titik mula anda.",
    shareLocationButton: "Kongsi lokasi saya",
```
CS1 (en/ms key-set parity) will verify these stay in step.

**Step B — `bot/src/bot/handlers/location-fallback.ts`** (create the directory). Two exported functions plus one private handler.

```typescript
/*
 * 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
 * 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 recorded below.
 */
import type { Bot, Context } from "grammy";
import { pickLocale, strings } from "../../i18n/strings.ts";
import type { Locale } from "../../i18n/strings.ts";
import { writePin, type LocationPinKv } from "../../kv/location-pin.ts";

/** Send the awaiting-pin prompt + location keyboard (GEO-02). */
export async function requestLocationFallback(bot: Bot, chatId: number, locale: Locale): Promise<void> {
  await bot.chat.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. */
export function registerLocationFallback(bot: Bot, kv: LocationPinKv): void {
  bot.on("message", async (ctx: Context) => {
    const loc = ctx.message?.location;
    if (!loc) return;
    const chatId = ctx.chat?.id;
    if (chatId === undefined) return;
    await recordSharedPin(kv, chatId, loc);
    await ctx.reply("Got it — your starting point is set.", { link_preview_options: { is_disabled: true } });
  });
}
```
**CS4 decision (explicit, per PATTERNS §bot-strings note):** the new handler lives in `bot/src/bot/handlers/`, which is NOT in `commandSources` (that array is `["bot.ts", "commands/start.ts", "commands/help.ts", "commands/privacy.ts"]`). CS4 therefore keeps passing untouched — do NOT add handlers/ to that array, and do NOT delete the gate. Record the rationale in the handler's header comment (done above).

**Step C — `bot/src/bot/bot.ts`.** Update the import block and `createBot` to thread KV through. Use this exact shape (the optional `opts.baseFetch` seam exists so `bot/test/location-pin.test.mjs` LP12/LP13 can observe the outgoing `sendMessage`):
```typescript
import { registerLocationFallback } from "./handlers/location-fallback.ts";
// ...
export function createBot(env: Env, opts: { baseFetch?: typeof fetch } = {}): Bot {
  const bot = new Bot(env.BOT_TOKEN, opts.baseFetch ? { client: { baseFetch: opts.baseFetch } } : {});
  registerStart(bot); // /start + /mula (D-04)
  registerHelp(bot); // /help
  registerPrivacy(bot); // /privacy + /privasi (D-04)
  registerLocationFallback(bot, env.chat_sessions); // GEO-02 chat-keyboard fallback
  return bot;
}
```
Update the header comment to note the GEO-02 handler's keyboard is the one structural exception to the D-02 text-only rule, and that `requestLocationFallback` has exactly ONE caller — `handleLocationFallback` in `webhook.ts` (Step D). If a second caller appears later, that is a design change, not a refactor.

**Step D — `bot/src/webhook.ts`.** Add BOTH route branches and handlers. The second route is the app→bot keyboard trigger (GEO-02) — without it, `requestLocationFallback` in Step B is dead code with no caller, and the ASK VIA CHAT CTA in plan 03-03 and the Desktop leg in plan 03-04 have nothing to POST to.

Dispatch (insert after the `/api/session` branch, before the 404):
```typescript
    if (url.pathname === "/api/location") {
      return handleLocation(req, env);
    }
    if (url.pathname === "/api/location-fallback") {
      return handleLocationFallback(req, env);
    }
```

First handler — the relay (as previously specified):
```typescript
/** GEO-02 relay: 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-]+)$/);
  if (!match || !match[1]) {
    console.log("[location] rejected: unauthorized"); // category ONLY (D-14)
    return new Response(JSON.stringify({ error: "unauthorized" }), {
      status: 401,
      headers: { "content-type": "application/json" },
    });
  }
  const token = match[1];
  const claim = 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);
  if (pin === null) {
    return new Response(JSON.stringify({ pin: null }), {
      status: 200,
      headers: { "content-type": "application/json" },
    });
  }
  return new Response(JSON.stringify({ pin }), {
    status: 200,
    headers: { "content-type": "application/json" },
  });
}
```

Second handler — the keyboard trigger:
```typescript
/** GEO-02 trigger: the Mini App's denied card taps ASK VIA CHAT and POSTs
 *  here; the Worker asks the BOT to send the 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. */
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 && 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).
    console.log("[location-fallback] failed: telegram-send");
    return new Response(JSON.stringify({ error: "unavailable" }), {
      status: 502,
      headers: { "content-type": "application/json" },
    });
  }
}
```

Imports to add at the top of `bot/src/webhook.ts`: `getClaimByToken` joins the existing `sessions.ts` import; `getPin` comes from a new `import { getPin } from "./kv/location-pin.ts"`; `requestLocationFallback` and `createBot` come from the bot module (`createBot` from `./bot/bot.ts`, `requestLocationFallback` from `./bot/handlers/location-fallback.ts`); `pickLocale` joins the `i18n/strings.ts` import. **Check for a circular-import hazard:** `bot/src/bot/bot.ts` must not import from `webhook.ts` (it does not — `createBot` is the leaf dependency, so `webhook.ts` depends on it, not the reverse). Verify with `npm run typecheck -w bot`.

Update the file header comment's route list to document all four routes (`/telegram/webhook`, `/api/session`, `/api/location`, `/api/location-fallback`).

**Step E — `bot/test/location-pin.test.mjs`** (create). Copy `bot/test/runner.mjs`-style header, import `{ test }` from `./harness.mjs`, `strict as assert` from `node:assert`, and copy the `makeKV()` fake from `bot/test/webhook.test.mjs` verbatim. Cases:

```javascript
test("LP1 writePin writes exactly one TTL-carrying key loc:<chat_id>", async () => {
  const kv = makeKV();
  await writePin(kv, 777, { latitude: 3.1513, longitude: 101.6958, horizontal_accuracy: 12 });
  assert.equal(kv.ttlLog.length, 1);
  assert.equal(kv.ttlLog[0].key, "loc:777");
  assert.strictEqual(kv.ttlLog[0].expirationTtl, 300);
  assert.ok(!kv.ttlLog[0].key.includes("user"), "pin key is chat-scoped, not user-id scoped");
});

test("LP2 getPin round-trips a valid record and returns null for absent", async () => {
  const kv = makeKV();
  assert.equal(await getPin(kv, 777), null);
  await writePin(kv, 777, { latitude: 3.1513, longitude: 101.6958, horizontal_accuracy: 12 });
  const pin = await getPin(kv, 777);
  assert.equal(pin.latitude, 3.1513);
  assert.equal(pin.longitude, 101.6958);
  assert.strictEqual(pin.horizontal_accuracy, 12);
});

test("LP3 getPin rejects out-of-range coordinates (null island guard)", async () => {
  const kv = makeKV();
  await kv.put("loc:1", JSON.stringify({ latitude: 999, longitude: 101, horizontal_accuracy: null }), { expirationTtl: 300 });
  assert.equal(await getPin(kv, 1), null, "absurd latitude must be rejected on read");
  await kv.put("loc:2", JSON.stringify({ latitude: 3, longitude: -999, horizontal_accuracy: null }), { expirationTtl: 300 });
  assert.equal(await getPin(kv, 2), null, "absurd longitude must be rejected on read");
});

test("LP4 getPin returns null on malformed JSON (defensive read)", async () => {
  const kv = makeKV();
  await kv.put("loc:3", "{not json", { expirationTtl: 300 });
  assert.equal(await getPin(kv, 3), null);
});

test("LP5 GET /api/location rejects a missing bearer token with 401", async () => {
  const kv = makeKV();
  const req = new Request("https://host/api/location", { method: "GET" });
  const res = await handler(req, makeEnv(kv));
  assert.strictEqual(res.status, 401);
  const body = await res.json();
  assert.strictEqual(body.error, "unauthorized");
});

test("LP6 GET /api/location rejects an unknown token with 401", async () => {
  const kv = makeKV();
  const req = new Request("https://host/api/location", { method: "GET", headers: { authorization: "Bearer deadbeef-1234" } });
  const res = await handler(req, makeEnv(kv));
  assert.strictEqual(res.status, 401);
});

test("LP7 GET /api/location returns {pin:null} for a valid token with no pin yet", async () => {
  const kv = makeKV();
  await mintSession(kv, { user_id: 42, chat_id: 777, issued_at: 1700000000, language_code: "ms" });
  const token = await getTokenForChat(kv, 777);
  const req = new Request("https://host/api/location", { method: "GET", headers: { authorization: `Bearer ${token}` } });
  const res = await handler(req, makeEnv(kv));
  assert.strictEqual(res.status, 200);
  const body = await res.json();
  assert.strictEqual(body.pin, null);
});

test("LP8 GET /api/location returns the pin for the token's OWN chat only", async () => {
  const kv = makeKV();
  await mintSession(kv, { user_id: 42, chat_id: 777, issued_at: 1700000000, language_code: "en" });
  await mintSession(kv, { user_id: 99, chat_id: 888, issued_at: 1700000000, language_code: "en" });
  const token777 = await getTokenForChat(kv, 777);
  const token888 = await getTokenForChat(kv, 888);
  await writePin(kv, 888, { latitude: 3.1513, longitude: 101.6958, horizontal_accuracy: 8 });
  const reqA = new Request("https://host/api/location", { method: "GET", headers: { authorization: `Bearer ${token777}` } });
  const bodyA = await (await handler(reqA, makeEnv(kv))).json();
  assert.strictEqual(bodyA.pin, null, "user 42's token must NOT read user 99's pin (V4 access control)");
  const reqB = new Request("https://host/api/location", { method: "GET", headers: { authorization: `Bearer ${token888}` } });
  const bodyB = await (await handler(reqB, makeEnv(kv))).json();
  assert.strictEqual(bodyB.pin.latitude, 3.1513);
});

test("LP9 GET /api/location with a non-GET method returns 405", async () => {
  const res = await handler(new Request("https://host/api/location", { method: "POST" }), makeEnv(makeKV()));
  assert.strictEqual(res.status, 405);
});

test("LP10 POST /api/location-fallback with a missing bearer token returns 401", async () => {
  const res = await handler(new Request("https://host/api/location-fallback", { method: "POST" }), makeEnv(makeKV()));
  assert.strictEqual(res.status, 401);
  assert.strictEqual((await res.json()).error, "unauthorized");
});

test("LP11 POST /api/location-fallback with an unknown token returns 401", async () => {
  const req = new Request("https://host/api/location-fallback", { method: "POST", headers: { authorization: "Bearer deadbeef-1234" } });
  assert.strictEqual((await handler(req, makeEnv(makeKV()))).status, 401);
});

test("LP12 POST /api/location-fallback sends the location keyboard to the token's OWN chat", async () => {
  const kv = makeKV();
  await mintSession(kv, { user_id: 42, chat_id: 777, issued_at: 1700000000, language_code: "en" });
  const token = await getTokenForChat(kv, 777);
  const calls = [];
  const realFetch = globalThis.fetch;
  globalThis.fetch = async (_url, init) => {
    calls.push(JSON.parse(String(init.body)));
    return new Response(JSON.stringify({ ok: true, result: { message_id: 1 } }), { headers: { "content-type": "application/json" } });
  };
  try {
    const res = await handler(new Request("https://host/api/location-fallback", { method: "POST", headers: { authorization: `Bearer ${token}` } }), makeEnv(kv));
    assert.strictEqual(res.status, 200);
    assert.strictEqual(calls.length, 1);
    assert.strictEqual(calls[0].chat_id, 777, "keyboard must go to the CLAIM's chat, never a client-supplied id (V4)");
    assert.strictEqual(calls[0].reply_markup.keyboard[0][0].request_location, true);
  } finally { globalThis.fetch = realFetch; }
});

test("LP13 POST /api/location-fallback honours claim.language_code", async () => {
  const kv = makeKV();
  await mintSession(kv, { user_id: 42, chat_id: 777, issued_at: 1700000000, language_code: "ms" });
  await mintSession(kv, { user_id: 7, chat_id: 555, issued_at: 1700000000, language_code: "en" });
  const calls = [];
  const realFetch = globalThis.fetch;
  globalThis.fetch = async (_url, init) => { calls.push(JSON.parse(String(init.body))); return new Response(JSON.stringify({ ok: true, result: { message_id: 1 } }), { headers: { "content-type": "application/json" } }); };
  try {
    const tokMs = await getTokenForChat(kv, 777);
    await handler(new Request("https://host/api/location-fallback", { method: "POST", headers: { authorization: `Bearer ${tokMs}` } }), makeEnv(kv));
    const tokEn = await getTokenForChat(kv, 555);
    await handler(new Request("https://host/api/location-fallback", { method: "POST", headers: { authorization: `Bearer ${tokEn}` } }), makeEnv(kv));
  } finally { globalThis.fetch = realFetch; }
  assert.strictEqual(calls[0].text, strings.ms.awaitingPin, "ms claim must receive ms copy");
  assert.strictEqual(calls[1].text, strings.en.awaitingPin, "en claim must receive en copy");
});

test("LP14 POST /api/location-fallback with a non-POST method returns 405", async () => {
  assert.strictEqual((await handler(new Request("https://host/api/location-fallback", { method: "GET" }), makeEnv(makeKV()))).status, 405);
});
```
Imports needed at the top of the test file:
```javascript
const { writePin, getPin } = await import("../src/kv/location-pin.ts");
const { mintSession, getTokenForChat } = await import("../src/kv/sessions.ts");
const { strings } = await import("../src/i18n/strings.ts");
const handler = await import("../src/webhook.ts").then((m) => m.default.fetch);
```
Copy `makeEnv` from `bot/test/webhook.test.mjs` verbatim: `function makeEnv(kv) { return { BOT_TOKEN: TEST_TOKEN, WEBHOOK_SECRET: "wk-test-secret", chat_sessions: kv }; }` with `const TEST_TOKEN = "12345:TESTTOKEN";` at module top.

LP12/LP13 observe the outgoing Telegram call by stubbing `globalThis.fetch` (grammY's default client calls through it) for the duration of the case, returning `{ ok: true, result: { message_id: 1 } }`; restore it in a `finally`.  </action>
  <verify>
    <automated>cd /home/C-Fu/araharah && npm test -w bot 2>&1 | tail -20 && npm run typecheck -w bot</automated>
  </verify>
  <acceptance_criteria>
    - `npm test -w bot` exits 0 and reports `14 passed` for the `LP` prefix (LP1–LP14)
    - `npm run typecheck -w bot` exits 0
    - `grep -v '^ \*\|^/\*\|^$' bot/src/bot/handlers/location-fallback.ts | grep -c 'request_location: true'` returns 1
    - `grep -q 'registerLocationFallback(bot, env.chat_sessions)' bot/src/bot/bot.ts` exits 0
    - `grep -q 'url.pathname === "/api/location"' bot/src/webhook.ts` exits 0
    - `grep -q 'url.pathname === "/api/location-fallback"' bot/src/webhook.ts` exits 0 (the app→bot keyboard trigger exists — `requestLocationFallback` is NOT dead code)
    - `grep -v '^ \*\|^/\*\|^$' bot/src/webhook.ts | grep -c 'getClaimByToken(env.chat_sessions' | head -1` returns 2 (both routes resolve chat_id from the CLAIM, never client input)
    - `grep -v '^ \*\|^/\*\|^$' bot/src/webhook.ts | grep -c 'requestLocationFallback(createBot(env), claim.chat_id, pickLocale(claim.language_code))' | head -1` returns 1 (locale from the claim, never from the request body)
    - `grep -v '^ \*\|^/\*\|^$' bot/src/bot/bot.ts | grep -c 'opts.baseFetch' | head -1` returns >= 1 (the test transport seam exists; production calls `createBot(env)` with one arg)
    - `grep -q 'commandSources = \["bot.ts", "commands/start.ts", "commands/help.ts", "commands/privacy.ts"\]' bot/test/commands.test.mjs` exits 0 (CS4 scope unchanged — handlers/ not scanned)
    - `grep -c 'awaitingPin' bot/src/i18n/strings.ts` returns 3 (interface + en + ms)
  </acceptance_criteria>
  <done>The bot can request a shared pin and record it in TTL-only KV, and BOTH server routes the Mini App needs exist and are proven: `GET /api/location` (claim-scoped relay) and `POST /api/location-fallback` (claim-scoped keyboard trigger with locale from the claim). 14 LP tests cover the TTL contract, range guard, cross-user isolation on both routes, and the en/ms locale split.</done>
</task>

</tasks>

<threat_model>
## Trust Boundaries

| Boundary | Description |
|----------|-------------|
| Telegram client → Worker webhook | Untrusted update payloads arrive; the secret-token compare is the gate (Phase 2). |
| Mini App (browser) → `GET /api/location` | Bearer session token in a header; the KV key is derived from the resolved claim. |
| Mini App (browser) → `POST /api/location-fallback` | Bearer session token in a header; the target chat_id and locale are derived from the resolved claim, never from the request body. |
| Bot update → KV pin write | A message's `location` payload becomes a stored coordinate; range validation gates it. |

## STRIDE Threat Register

| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-03-01 | Information Disclosure | `GET /api/location` — another user's pin read | mitigate | Resolve `Authorization: Bearer <token>` through `getClaimByToken(env.chat_sessions, token)`; derive the KV key `loc:<chat_id>` from the **claim**, never from a request parameter. Missing/expired token → 401 `{error:"unauthorized"}`. Pinned by test LP8 (user 42's token cannot read user 99's pin). |
| T-03-02 | Information Disclosure | Coordinate persisted beyond TTL | mitigate | Every `.put(` in `location-pin.ts` carries `expirationTtl: PIN_TTL_SECONDS` (300) on the same line; `privacy.test.mjs` PG1 gate re-scans the module automatically after the storageModules edit. No profile/history/trip store exists (PG2). |
| T-03-03 | Tampering | Malicious webhook update injecting a fabricated pin | mitigate | Only Telegram-authenticated updates reach grammY — the `X-Telegram-Bot-Api-Secret-Token` constant-time compare runs BEFORE any bot processing (Phase 2, WR-02). The handler filters on `ctx.message?.location` only. |
| T-03-04 | Tampering / DoS | Out-of-range coordinates in a shared pin | mitigate | `getPin` rejects `\|latitude\| > 90` or `\|longitude\| > 180` and non-numeric values on read (V5 Input Validation), so a corrupt record can never fly the client camera to null island. Test LP3. |
| T-03-05 | Information Disclosure | Category-only logging violated | mitigate | The two 401 paths log the literal string `"[location] rejected: unauthorized"` — never the token, the chat id, or any coordinate. |
| T-03-06 | Repudiation | A chat pin served long after it was shared | mitigate | 300s TTL bounds exposure; `clearPin` exists for an explicit sweep and the Mini App deletes its copy from memory as soon as it consumes the pin. |
| T-03-26 | Elevation of Privilege | One user's session token pushing a location keyboard into ANOTHER user's chat via `POST /api/location-fallback` | mitigate | The handler resolves the token through `getClaimByToken` and passes `claim.chat_id` to `requestLocationFallback`; the request body is never read, so there is no client-supplied chat id to tamper with. Missing/expired token → 401. Pinned by test LP10/LP11 (401) and LP12 (the send goes to the claim's chat, asserting the `sendMessage` body's `chat_id`). |
| T-03-27 | Spoofing | Client-supplied language overriding the claim's locale | mitigate | `pickLocale(claim.language_code)` reads only the server-recorded claim value that `mintSession` captured from the HMAC-validated initData. The handler accepts no `lang`/locale field from the request. Pinned by test LP13 (ms claim → ms copy, en claim → en copy). |
| T-03-28 | Denial of Service | Unauthenticated flood of the keyboard trigger | mitigate | The route is POST-only (405 otherwise) and every request that reaches `requestLocationFallback` has already resolved a live, unexpired session claim via `getClaimByToken`, so an anonymous flood cannot reach Telegram's API at all. A Telegram-side failure (blocked bot, chat not found, rate limit) is caught and returned as a category-only 502 — the error text is never surfaced to the client or the log. |
</threat_model>

<verification>
- `npm test -w bot` green (all Phase-2 cases plus the 14 new LP cases)
- `npm run typecheck -w bot` clean — in particular, no circular import between `webhook.ts` and `bot/bot.ts`
- `npm test -w web` green (empty suite passes — later plans add cases)
- `npm install` resolves the `web` workspace with no peer conflicts
</verification>

<success_criteria>
- GEO-02 server half complete in BOTH directions: the bot requests a pin via reply keyboard and records it TTL-only, the app can trigger the keyboard via `POST /api/location-fallback`, and it can poll the result via `GET /api/location` — both routes claim-scoped
- GEO-03 server half complete: the only coordinate store is TTL-expiring KV, covered by an automated same-line TTL gate
- The `web/` workspace exists with the repo-convention hand-rolled test runner, so every later plan has a place to put tests
</success_criteria>

<output>
After completion, create `.planning/phases/03-mini-app-shell-geolocation/03-01-SUMMARY.md`
</output>