@www.hyperlinks.space/program-kit 1.2.3

package/docs/security_plan_raw.md

@@ -0,0 +1,244 @@
+# Security Implementation Plan (Telegram-First Wallet)
+
+This file describes a practical implementation plan for the security model defined in `security.md`, focused on the `./app` (Expo / Vercel) codebase and a serverless backend.
+
+---
+
+## Phase 0 – Prerequisites & Plumbing
+
+- **0.1. Bot & Mini App configuration**
+  - Ensure main Mini App is configured in @BotFather with:
+    - `https://hsbexpo.vercel.app` (or new URL) as base.
+    - `startapp` support enabled.
+  - Confirm `telegram-web-app.js` is loaded in the Mini App shell.
+
+- **0.2. Serverless backend basics**
+  - Use existing Vercel project (`./app`) API routes:
+    - Create a shared util for **Telegram initData validation** (WebApp) in `api/_lib/telegram.ts`:
+      - `validateInitData(initData: string): { username: string }`.
+    - Create a shared util for **Telegram Login widget validation** (web/native) in `api/_lib/telegram_login.ts`:
+      - `validateLoginPayload(payload): { username: string }`.
+
+- **0.3. Database**
+  - Choose a serverless DB (e.g. Neon, Supabase, PlanetScale, Vercel Postgres).
+  - Define tables (supporting **multiple wallets per user**, including app-created and TonConnect-linked):
+    - `users`:
+      - `telegram_username` (PK or unique, text).
+      - `created_at`, `updated_at`.
+      - `last_login_at` – last successful Telegram login (any platform).
+      - `last_tma_seen_at` – last time user opened the Mini App.
+      - `locale` – preferred language (derived from Telegram).
+      - `time_zone` (optional, from app settings).
+      - `number_of_wallets` – cached count for quick UI/query.
+      - `default_wallet` – optional reference/key to the user’s default wallet (e.g. `wallet_address` + `wallet_blockchain` + `wallet_net` tuple or UI identifier).
+      - `security_flags` (JSON) – e.g. `{ "high_value_user": true, "require_extra_confirm": false }`.
+      - `marketing_opt_in` (bool) – whether user agreed to non-transactional notifications.
+    - `wallets`:
+      - `telegram_username` (FK to `users`).
+      - `address` (text).
+      - `blockchain` (text, e.g. `'ton'`).
+      - `net` (text, e.g. `'mainnet'`, `'testnet'`).
+      - `type` (`'internal' | 'tonconnect' | 'other'`) – app-created vs external/connected.
+      - `label` (optional user-friendly name, e.g. “Main wallet”, “Tonkeeper”).
+      - `is_default` (bool) – which wallet to show first in UI.
+      - Composite PK/unique: (`telegram_username`, `wallet_address`, `wallet_blockchain`, `wallet_net`).
+      - `created_at` – when this wallet record was created (first seen / added).
+      - `updated_at` – when this wallet record was created (first seen / added).
+      - `last_used_at` – last time a transaction was initiated or confirmed with this wallet.
+      - `last_seen_balance_at` – last time we refreshed its on-chain balance
+      - `source` – 'miniapp', 'tonconnect', 'imported' (how it was added)
+      - `notes` – (optional text): free-form user note about this wallet.
+      - Timestamps / metadata (last_used_at, etc.).
+    - `pending_transactions`:
+      - `id` (UUID / text, PK).
+      - `telegram_username` (FK to `users`).
+      - `wallet_address` (text).
+      - `wallet_blockchain` (text).
+      - `wallet_net` (text).
+      - `payload` (JSONB / text).
+      - `status` (`pending | confirmed | rejected | failed`).
+      - `created_at`, `updated_at`.
+  - Add minimal DB client in `api/_lib/db.ts`.
+
+---
+
+## Phase 1 – Telegram Mini App: Wallet Creation & Device Auth
+
+- **1.1. Mini App bootstrap**
+  - Create a dedicated Mini App entry screen in Expo web (`app/app/index.tsx` or a nested route) that:
+    - Accesses `window.Telegram.WebApp.initData`.
+    - Calls a backend endpoint `POST /api/tg/init` to:
+      - Validate `initData`.
+      - Upsert a bare `users` row if needed (without wallet).
+
+- **1.2. Wallet creation flow (TMA)**
+  - Implement a React flow in the Mini App:
+    - Step 1: Intro + explanation (self-custody, seed phrase).
+    - Step 2: Generate mnemonic (client-side) with a TON/crypto library.
+    - Step 3: Show mnemonic & confirmation quiz.
+    - Step 4:
+      - Derive wallet master key from mnemonic.
+      - Store it via `Telegram.WebApp.SecureStorage.setItem('wallet_master_key', <key>)`.
+      - Derive/encode wallet seed or root key, encrypt with master key → `seed_cipher`.
+      - Store `seed_cipher` via `Telegram.WebApp.CloudStorage.setItem('wallet_seed_cipher', <cipher>)`.
+      - Derive `wallet_address` from mnemonic/root key.
+      - Call `POST /api/wallet/register` with `{ telegram_username, wallet_address }` (initData-validated).
+    - Step 5: Success screen explaining:
+      - “Wallet created in Telegram; keep your mnemonic safe.”
+      - “Use Android/iOS/web to view wallet after logging in with Telegram.”
+
+- **1.3. New Telegram device authorization**
+  - At Mini App start:
+    - Check `SecureStorage.getItem('wallet_master_key')`.
+      - If present → user can operate without extra input.
+      - If absent but `CloudStorage.getItem('wallet_seed_cipher')` exists:
+        - Show “Authorize this device” screen:
+          - Prompt for mnemonic once.
+          - Derive new master key, store in `SecureStorage`.
+          - Optionally re-encrypt `seed_cipher` (or just reuse old one).
+
+---
+
+## Phase 2 – iOS/Android App Flow (Single App)
+
+(All implemented inside `./app` using Expo Router / React Native.)
+
+- **2.1. Local state**
+  - Add a simple secure storage wrapper (e.g. `expo-secure-store`):
+    - Keys:
+      - `telegram_username`
+      - `wallet_address`
+  - Add a React context or hook `useCurrentUser()` that:
+    - On app start, reads these keys.
+    - Exposes `state: 'anonymous' | 'linked'`, `telegram_username`, `wallet_address`.
+
+- **2.2. “Log in with Telegram” screen**
+  - Create a route (e.g. `app/app/login/telegram.tsx`) used on mobile startup when `state === 'anonymous'`:
+    - Copy text from `security.md`:
+      - Explain benefits of Telegram-based wallet creation and storage.
+    - Buttons:
+      - **Open Telegram to create wallet**:
+        - Use `Linking.openURL('https://t.me/<bot_username>?startapp=wallet_onboarding')`.
+      - **I already created my wallet in Telegram / Log in with Telegram**:
+        - Opens a WebView or browser to hosted login page (e.g. `/login/telegram`).
+
+- **2.3. Telegram Login for Websites (web page + API)**
+  - Create a web page (static route in `./app` or separate) that:
+    - Embeds the Telegram Login widget configured for your bot & domain.
+    - On success, posts the payload (via `data-onauth` callback) to `POST /api/login/telegram`.
+  - `POST /api/login/telegram`:
+    - Validates login payload (`hash` + `auth_date`) per [Telegram widget docs](https://core.telegram.org/widgets/login).
+    - Extracts `username`.
+    - Looks up `users` by `telegram_username`.
+    - Responds with:
+      - On success: `{ telegram_username, wallet_address }`.
+      - On missing wallet: `{ error: 'NO_WALLET' }`.
+  - In the mobile WebView:
+    - When login completes, post a message back to the React Native layer with the above payload.
+    - Native side saves `telegram_username` + `wallet_address` via secure storage and updates `useCurrentUser()` state.
+
+- **2.4. Main wallet UI on mobile**
+  - When `useCurrentUser()` reports `state === 'linked'`:
+    - Show wallet balances / positions (read-only) via:
+      - Direct chain APIs or your own serverless `GET /api/wallet/state?address=...`.
+    - For any **sensitive action** (swap, send, etc.) use the serverless + bot confirmation flow (Phase 3).
+
+---
+
+## Phase 3 – Serverless Transaction Flow & Bot Confirmation
+
+- **3.1. Create transaction (serverless route)**
+  - Add `POST /api/tx/create`:
+    - Auth:
+      - From Mini App: validate `initData`, resolve `telegram_username`.
+      - From web/mobile: require a session or signed JWT containing `telegram_username` from Telegram login.
+    - Validate payload (action, amount, destination).
+    - Insert into `pending_transactions` with status `pending`.
+    - Use bot token to call `sendMessage` with:
+      - Text summary.
+      - Inline `web_app` button pointing to `https://t.me/<bot_username>?startapp=tx_<id>`.
+    - Return `{ id }` to caller for polling.
+
+- **3.2. Confirmation page in Mini App**
+  - Implement a `tx/[id]`-like route in the Mini App (or use `start_param` parsing on the main screen) that:
+    - Reads `start_param` → extracts `<id>`.
+    - Calls `GET /api/tx/<id>`:
+      - Validates `initData`, ensures tx belongs to `telegram_username`.
+      - Returns tx summary (read-only).
+    - UI:
+      - Shows:
+        - Asset, amount, from / to addresses, network, estimated fee.
+        - A big, unambiguous **“Confirm”** button and a **“Reject”** button.
+
+- **3.3. Local signing & completion**
+  - On **Confirm**:
+    - Mini App:
+      - Reconstructs the on-chain transaction from the payload and `wallet_address`.
+      - Signs it with the wallet key derived from mnemonic / master key in `SecureStorage`.
+      - Sends `POST /api/tx/<id>/complete` with:
+        - `id`
+        - `signedTx` (or `txHash` if client broadcasts).
+        - `decision: 'confirmed'`.
+  - `POST /api/tx/<id>/complete`:
+    - Validates `initData` and ownership.
+    - Verifies tx is still `pending`.
+    - Option A (backend broadcasting):
+      - Broadcast `signedTx` to RPC endpoint.
+      - On success/failure, update `status` accordingly and store `tx_hash`.
+    - Option B (client broadcasting):
+      - Trust `txHash` and mark as `confirmed`, or perform lightweight verification.
+    - Returns final status to Mini App.
+
+- **3.4. Rejection path**
+  - On **Reject**:
+    - Mini App calls `POST /api/tx/<id>/complete` with `decision: 'rejected'`.
+    - Backend sets status `rejected`.
+
+- **3.5. Client status updating**
+  - Any client that initiated the tx (Mini App, web, mobile app):
+    - Polls `GET /api/tx/<id>` until `status !== 'pending'`.
+    - Or uses lightweight WebSocket/SSE if desired.
+
+---
+
+## Phase 4 – Hardening & Observability
+
+- **4.1. Logging & audit**
+  - Add structured logging in all API routes:
+    - User identity (`telegram_username`), tx id, IP, user agent.
+  - Consider a `tx_history` view for user self-audits.
+
+- **4.2. Rate limiting & abuse protection**
+  - Add rate limiting (IP + username) on:
+    - `/api/tx/create`
+    - `/api/login/telegram`
+  - Consider CAPTCHA or additional friction on spammy accounts.
+
+- **4.3. Secrets & config**
+  - Store:
+    - Bot token, DB URL, RPC URLs, etc. in Vercel environment variables.
+  - Never log full mnemonics or keys; ensure any debug logging never prints sensitive values.
+
+- **4.4. UX safety rails**
+  - On confirmation pages (Mini App & web):
+    - Highlight destination address and allow user to copy it.
+    - Show human-readable asset names & verify network.
+    - For large amounts, add extra confirmation step or warning.
+
+---
+
+## Phase 5 – Optional Enhancements
+
+- **5.1. Advanced local wallets (non-default)**
+  - In the mobile app and/or web app, optionally add:
+    - “Import mnemonic to this device” flow (explicit, with big warnings).
+  - Keep Telegram-first as the recommended path in docs and UI.
+
+- **5.2. Multi-device / guardian support (future)**
+  - Extend smart contract / wallet to support multiple keys or social recovery.
+  - Use Telegram as one guardian channel among others.
+
+---
+
+This plan should be implemented iteratively: Phase 1 (Mini App wallet), Phase 2 (mobile login shell), Phase 3 (serverless tx + confirmations), then hardening and enhancements. Each step can be validated independently (unit tests on API routes, manual testing in TMA, Expo mobile, and web). 
+

package/docs/security_raw.md

@@ -0,0 +1,345 @@
+# Security Model: Telegram-First Wallet
+
+## Goals
+
+- Create wallets inside the Telegram Mini App.
+- Let users access the **same wallet** from:
+  - Telegram on any device.
+  - Other platforms (web / desktop / native) via **Login with Telegram**.
+- Keep custody with the **user** (mnemonic as ultimate root of trust), while using Telegram features to improve UX.
+
+This document describes the current high-level design; it is not a formal audit.
+
+---
+
+## Key Concepts & Storage
+
+**Key terms**
+
+- **Mnemonic (seed phrase)**: Ultimate secret that controls the wallet. If lost, funds are lost; if leaked, funds are at risk.
+- **Wallet master key**: Device-specific key derived from the mnemonic and stored only on that device.
+- **Wallet seed cipher**: Encrypted blob that contains the wallet seed (or a seed-derived secret), usable only together with the wallet master key.
+- **Telegram CloudStorage**: Per-user, per-bot key–value store synced via Telegram servers. Suitable for non-secret data or ciphertext.
+- **Telegram SecureStorage**: Per-device secure storage, backed by iOS Keychain / Android Keystore, intended for small sensitive values like tokens and keys (see [Mini Apps docs](https://core.telegram.org/bots/webapps#securestorage)).
+
+We **never store raw mnemonics** on our backend or in Telegram CloudStorage.
+
+---
+
+## I. Wallet Creation in Telegram
+
+Flow when a user creates a wallet for the first time in the Telegram Mini App on a device:
+
+1. **Generate mnemonic on the device**
+   - The Mini App generates a new mnemonic locally (client-side).
+   - The user is shown the mnemonic once and asked to write it down for lifelong backup.
+
+2. **Derive wallet master key (device-local)**
+   - From the mnemonic, the app derives a **wallet master key** (e.g. via a BIP-style KDF / HKDF).
+   - This master key is stored **only** in Telegram `SecureStorage` on that device.
+   - Because `SecureStorage` is backed by **Keychain / Keystore**, the key is:
+     - Encrypted at rest.
+     - Bound to this device + Telegram app.
+
+3. **Create and store wallet seed cipher (cloud)**
+   - The app creates a **wallet seed cipher**:
+     - `seed_cipher = Encrypt(wallet_seed_or_root, wallet_master_key)`.
+   - `seed_cipher` is stored in Telegram `CloudStorage` under this bot for this user.
+   - CloudStorage contains **only ciphertext**, never raw seed or keys.
+
+4. **Persist wallet mapping in our backend**
+   - Our backend stores a record like:
+     - `telegram_username` (Telegram username, treated as unique in our system),
+     - `wallet_address` (public address),
+     - metadata (creation time, network, etc.).
+   - No mnemonics or master keys are saved server-side.
+
+**Properties**
+
+- The **first Telegram device** has everything needed to use the wallet:
+  - Master key in `SecureStorage`.
+  - Seed cipher in `CloudStorage`.
+- If the app is reinstalled on the **same device**, we can:
+  - Recover the master key from `SecureStorage` (if Telegram restores it).
+  - Decrypt the seed cipher for a smooth UX without re-entering the mnemonic.
+- If `SecureStorage` is wiped, the user must re-enter the mnemonic.
+
+---
+
+## II. New Telegram Device Authorization
+
+When the same user opens the Mini App on **another Telegram client** (new phone/tablet):
+
+1. **Detect existing wallet**
+   - Using `initData` / backend lookup, we see that this `telegram_username` already owns at least one `wallet_address`.
+
+2. **Check device SecureStorage**
+   - On this **new device**, `SecureStorage` is empty for our bot (no wallet master key yet).
+   - We may still see the `seed_cipher` in `CloudStorage` (it is synced across user devices), but without a master key it is useless.
+
+3. **Ask user for mnemonic to authorize this device**
+   - The Mini App prompts the user to enter their mnemonic.
+   - From the mnemonic we derive a **new device-specific wallet master key** and store it in this device’s `SecureStorage`.
+   - Optionally, we re-encrypt and update the `seed_cipher` for this device; but the canonical root of trust remains the mnemonic.
+
+**Result**
+
+- Each Telegram device gains access only after the user proves knowledge of the mnemonic once.
+- Loss of a device does **not** affect other devices, as long as the mnemonic is safe.
+
+---
+
+## III. Other Platforms (Outside Telegram)
+
+For platforms outside Telegram (web, desktop app, native mobile app not running inside Telegram), we:
+
+1. **Authenticate via Telegram**
+   - Use **Telegram Login for Websites** (see [login widget docs](https://core.telegram.org/widgets/login)) in a browser or embedded WebView.
+   - The login widget:
+     - Shows a Telegram-branded authorization UI where the user confirms sharing their Telegram identity with our site.
+     - After success, returns a signed payload containing `id`, `first_name`, `last_name`, `username`, `photo_url`, `auth_date`, and `hash`.
+   - On our backend we verify the `hash` using HMAC-SHA-256 with the SHA-256 of the bot’s token as a key, as described in the official docs.
+   - This works on:
+     - **Desktop browsers** (Chrome, Firefox, Safari, Edge, …),
+     - **Mobile browsers** on **iOS and Android**,
+     - In-app WebViews (e.g. inside a native app’s web login screen).
+
+   > For pure native iOS/Android apps, we typically embed a small web login page (with the widget) or open the system browser, then pass the verified Telegram identity back into the app.
+
+2. **Lookup existing wallet**
+   - Once Telegram login succeeds, we resolve `telegram_username` in our DB.
+   - If there is an associated `wallet_address`, we know this user already owns a wallet.
+
+3. **Authorize the device with the mnemonic**
+   - Because we are **outside Telegram**, we do not have Telegram’s `SecureStorage`.
+   - We therefore ask the user to **enter the mnemonic** to authorize this new platform.
+   - The app derives a **local wallet master key** from the mnemonic and stores it using the platform’s secure storage:
+     - iOS: Keychain
+     - Android: Keystore
+     - Desktop: DPAPI / Keychain / Keyring, depending on OS
+     - Web: WebCrypto + IndexedDB (with the usual caveats around user clearing storage).
+
+**Result**
+
+- Telegram login is used purely as an **identity layer** (“who is this user?”).
+- The **mnemonic** is still required to authorize a completely new platform.
+- Our backend never receives the raw mnemonic; only derived public keys / addresses.
+
+---
+
+## IV. Android / iOS (Single App, Telegram‑Centric Flow)
+
+We ship **one app** (the current `./app` Expo app) to iOS/Android stores. On mobile, the app acts as a shell that:
+
+- Explains why wallet creation happens in Telegram.
+- Sends the user into the Telegram Mini App to actually create the wallet.
+- Then uses **Telegram Login for Websites** + our backend to recognize the user and their wallet.
+
+### Database: user identification (Telegram username–centric)
+
+In the backend we maintain a `users` table (or equivalent) with at least:
+
+- `telegram_username` – Telegram username, treated as unique in our system.
+- `wallet_address` – current wallet address owned by this username.
+
+The mobile app never needs to store the mnemonic or keys; it only needs the `telegram_username` and `wallet_address` retrieved from the backend after Telegram login.
+
+### A. New user on iOS/Android (no wallet yet)
+
+1. **App start → “Log in with Telegram” screen**
+   - Shown when there is no linked `telegram_username` in local app storage.
+   - Content:
+     - Title: “Create your wallet in Telegram”.
+     - Short text summarizing benefits:
+       - “Wallets are created **inside Telegram**, we never see your seed phrase.”
+       - “Your keys are stored using Telegram **SecureStorage + CloudStorage** on your devices.”
+       - “You can access the same wallet from Telegram, web, and this app.”
+     - UI:
+       - Primary button: **“Open Telegram to create wallet”**.
+       - Secondary button (dimmed / smaller): **“I already created my wallet in Telegram”** (goes to login widget, see flow B).
+   - Action on primary:
+     - Deep link to Mini App, e.g. `https://t.me/<bot_username>?startapp=wallet_onboarding`.
+
+2. **Telegram Mini App: wallet creation (same as section I)**
+   - Generate mnemonic, show/confirm it.
+   - Derive wallet master key → store in `SecureStorage`.
+   - Encrypt wallet seed → store cipher in `CloudStorage`.
+   - Call backend `register_wallet(telegram_username, wallet_address)` which:
+     - Creates a new `users` row.
+     - Stores `telegram_username`, `wallet_address`.
+   - Show a completion screen:
+     - “Your wallet is ready in Telegram.”
+     - Instruction: “Return to the app and tap ‘I already created my wallet’ to connect.”
+
+3. **Back in iOS/Android app → “Log in with Telegram” (Telegram login widget)**
+   - User returns to the app and taps **“I already created my wallet in Telegram”** (or simply “Log in with Telegram”).
+   - App opens an embedded WebView or browser page with **Telegram Login for Websites**:
+     - Widget asks the user to confirm sharing their Telegram identity.
+     - After success, backend receives a signed payload and validates it as in section III.
+     - Backend extracts `username` from the payload and looks up `telegram_username` in `users`:
+       - If found, returns `{ telegram_username, wallet_address, ... }` to the app.
+       - If not found (edge case: user logged in before creating wallet), the app can:
+         - Show “No wallet yet, please create it in Telegram first” and show the **Open Telegram** button again.
+
+4. **App state after linking**
+   - The app stores `telegram_username` and `wallet_address` in its local storage.
+   - It can now:
+     - Display balances / history via backend or blockchain APIs.
+     - For signing, either:
+       - Redirect back to Telegram Mini App on an action (“Sign in Telegram”), or
+       - In a future advanced flow, allow the user to import mnemonic locally (explicit, non‑default).
+
+### B. Existing Telegram wallet user installing iOS/Android app
+
+For a user who already has a Telegram wallet (created earlier in the Mini App):
+
+1. **App start → same “Log in with Telegram” screen**
+   - The screen is identical, but the text emphasizes:
+     - “If you already created your wallet in Telegram, just log in below.”
+   - Action:
+     - User taps **“I already created my wallet in Telegram”** / **“Log in with Telegram”**.
+
+2. **Telegram Login for Websites**
+   - Same widget flow as in A.3.
+   - Backend verifies the payload and looks up `telegram_username` in `users`:
+     - If a row exists → return `{ telegram_username, wallet_address }` to the app.
+     - If no row exists → the app suggests:
+       - “We don’t see a wallet yet. Please open Telegram to create one.” and shows the **Open Telegram to create wallet** button.
+
+3. **After login**
+   - The app saves `telegram_username` + `wallet_address` locally and shows the wallet UI.
+   - No mnemonic is ever handled by the app in this default flow.
+
+**Key points of this model**
+
+- There is **one app** (`./app`), not a separate companion; mobile just has a Telegram‑centric onboarding path.
+- All wallet creation and key material remain in the Telegram Mini App and its SecureStorage/CloudStorage environment.
+- The iOS/Android app uses:
+  - **Telegram Login for Websites** to learn “who is this user?” (via `username`),
+  - The backend’s `users` table (`telegram_username`, `wallet_address`) to link that identity to a wallet.
+- Users who don’t want to connect Telegram can only use future “local‑only” features if we add them explicitly; the default path is Telegram‑first. 
+
+---
+
+## V. Serverless Transaction Flow & Bot‑Based Confirmation
+
+We assume a **serverless backend** (e.g. Vercel / Cloudflare / Lambda functions) with:
+
+- Stateless HTTP handlers (API routes).
+- A persistent datastore (serverless Postgres / KV / Dynamo, etc.) for:
+  - `users` (`telegram_username`, `wallet_address`, …).
+  - `pending_transactions` (id, telegram_username, payload, status, timestamps).
+
+All **signing** happens on the client side (Telegram Mini App or other wallet environment); serverless functions never hold private keys.
+
+### 1. Initiating a transaction (any client)
+
+From any frontend (Telegram Mini App, web, iOS/Android app):
+
+1. Client sends a request to a serverless endpoint, e.g. `POST /api/tx/create`:
+   - Body includes:
+     - `telegram_username` (or derived from Telegram auth),
+     - transaction intent (action type, amount, asset, destination, etc.).
+2. Serverless handler:
+   - Validates the request and user identity.
+   - Creates a `pending_transactions` row with:
+     - `id` (e.g. UUID or short code),
+     - `telegram_username`,
+     - serialized transaction payload (what needs to be signed),
+     - status = `pending`.
+   - Uses the **Telegram Bot API** to send a push message to the user:
+     - “New action requires confirmation: <summary>”.
+     - Inline button: **“Review & confirm”** linking to:
+       - Recommended: Mini App deep link, e.g.\
+         `https://t.me/<bot_username>?startapp=tx_<id>`
+       - Optionally, a web URL, e.g.\
+         `https://app.hyperlinks.space/tx/<id>`.
+
+### 2. Confirmation page (Telegram Mini App)
+
+When the user taps the button in the bot message and opens the Mini App:
+
+1. The Mini App receives `start_param = tx_<id>` via `initData`.
+2. It calls a serverless endpoint, e.g. `GET /api/tx/<id>`:
+   - Backend verifies the request using `initData`/`hash` and checks that:
+     - `pending_transactions.id` exists,
+     - `telegram_username` from DB matches the Mini App user,
+     - status is `pending`.
+   - Backend returns the transaction details (read‑only).
+3. Mini App shows a **confirmation UI**:
+   - Clear summary: amounts, assets, destination, fees, network.
+   - Buttons: **Confirm** / **Reject**.
+
+### 3. Signing & broadcasting (inside Telegram)
+
+On **Confirm** from the Mini App:
+
+1. Mini App reconstructs/derives the transaction to be signed using:
+   - The locally available wallet (seed/master key in `SecureStorage`).
+   - The payload from `pending_transactions`.
+2. Mini App signs the transaction **locally** using the wallet key.
+3. Mini App sends a request to a serverless endpoint, e.g. `POST /api/tx/<id>/complete` with:
+   - `id`,
+   - signed transaction payload (or only the resulting transaction hash if the client broadcasts itself),
+   - confirmation that user accepted.
+4. Serverless handler:
+   - Verifies that the caller is the right `telegram_username` and that tx is still `pending`.
+   - Either:
+     - Broadcasts the signed transaction to the chain (if backend has RPC access and broadcasting doesn’t leak secrets), **or**
+     - Simply records the fact that this transaction was confirmed and uses a separate service / worker to broadcast.
+   - Updates `pending_transactions.status` to `confirmed` (or `failed` with reason).
+
+The originating client (web / mobile app) can poll or subscribe for status changes on `pending_transactions` to reflect completion.
+
+### 4. Optional: web‑only confirmation page
+
+For users who click a **web URL** from the bot instead of the Mini App:
+
+- The confirmation page:
+  - Uses **Telegram Login for Websites** to authenticate the user (retrieve `username`).
+  - Loads the `pending_transactions` row by `id` + `telegram_username`.
+  - Shows the same confirmation UI.
+- For signing, we recommend **redirecting back to Telegram** for actual key usage:
+  - On **Confirm**, the web page can:
+    - Either deep‑link into the Mini App with the same `tx_<id>`, or
+    - Ask the user to enter the mnemonic or connect an external wallet (advanced, non‑default).
+- This keeps the **self‑custodial key** anchored in the Mini App by default, while still allowing purely web‑based flows where the user explicitly opts into entering their mnemonic or linking another wallet.
+
+### Serverless guarantees
+
+- All backend logic is stateless across requests; long‑lived data lives in `users` and `pending_transactions`.
+- No private keys or mnemonics are ever stored or derived in serverless functions.
+- Bot pushes and confirmation flows are coordinated exclusively via:
+  - Telegram Bot API (for notifications),
+  - Telegram Mini App (for secure signing with SecureStorage),
+  - Telegram Login (for identity on web / mobile).
+
+This model keeps transaction approvals **user‑driven and key‑local** (inside Telegram or another explicit wallet) while still fitting neatly into a serverless architecture. 
+
+---
+
+## Security Properties
+
+- **Self-custody:**
+  - The mnemonic is the **only ultimate key**; if the user keeps it offline and safe, they retain full control over funds.
+  - Neither our backend nor Telegram can unilaterally move funds without the mnemonic / keys.
+
+- **Device-local keys:**
+  - Each device has its own **wallet master key** stored in that device’s secure storage (Telegram SecureStorage or OS keystore).
+  - Compromise of one device does **not** automatically compromise others.
+
+- **Cloud data is ciphertext only:**
+  - `Wallet Seed Cipher` in CloudStorage is encrypted with a master key that lives only in secure storage on a device.
+  - An attacker with only CloudStorage access cannot derive the mnemonic.
+
+- **Cross-platform restore requires mnemonic:**
+  - Any **new environment** (new Telegram device with empty SecureStorage or any non-Telegram platform) requires the mnemonic once.
+
+---
+
+## Limitations & Notes
+
+- If the **mnemonic is lost**, there is no recovery (by design) – it is the self-custodial root.
+- If a device with a master key is compromised, an attacker can act as the owner from that device until the user moves funds to a new wallet.
+- Telegram `SecureStorage` is documented for **iOS and Android**; behavior on other Telegram clients may differ.
+- Telegram Login for Websites is an **authentication mechanism only** – it does not give access to keys or the mnemonic itself, and cannot replace the mnemonic for wallet authorization.

package/docs/timing_raw.md

@@ -0,0 +1,63 @@
+# Raw timing estimate
+
+**Purpose:** Rough “time till app finish” and **MVP launch** based on commit history, plans, and the front app.
+
+**Important:** The app will not be sent to platforms (store/listing) before it is fully finished. So **MVP launch = full product launch**, and the realistic estimate is **3 months**.
+
+## Transfer layout to `./app` (TypeScript) — build on new architecture
+
+The goal is **not** to finish the Flutter app in `front/`. The **Flutter** app in `front/` is the **reference layout** (web pages, flows, structure). The work is to **transfer that layout and flows into `./app` in TypeScript** and make everything work there, with **security plan compliance** (see `docs/security_plan.md`). The production Mini App is the TS app in `./app` (Expo/React), backed by the same repo’s API and DB.
+
+### Pages to implement in `./app` (TS) — from `front/` reference
+
+- **Bootstrap** – initData auth, config from API, wallet warm-up.
+- **Main** – home / hub after bootstrap.
+- **Send** – send flow (security plan: pending tx, confirmations).
+- **Swap** – swap flow (rate state, rotation, etc. from root plan).
+- **Wallets** – list/create/manage; wallet creation and nickname (security plan: mnemonic flow, device auth, wallet registration).
+- **Apps** – apps design, brand book alignment.
+- **AI** – AI & search bar; response formatting; scrolling fix; wired to `app` AI routes.
+- **Get** – get flow.
+- **Trade** – trade page.
+- **Creators** – creators content.
+- **Mnemonics** – mnemonic display/backup (security plan).
+- **Wallet panel** – wallet panel page.
+
+### Services / wiring in `./app` (TS)
+
+| Concern | Role | Backend / compliance |
+|--------|------|-----------------------|
+| **Auth** | Telegram initData auth (e.g. app’s telegram/init endpoint). | initData validation and user upsert (Phase 0–1). |
+| **AI** | Chat with AI via same-origin `/api/ai` (or app’s AI route). | Already in `app`; ensure config, keys, and error handling in prod. |
+| **Wallet** | Mnemonic generation, storage, key derivation (client-side). | Security plan: SecureStorage/CloudStorage, wallet registration (`POST /api/wallet/register`), device auth flow; optional TonConnect later. |
+
+### API surface (in `./app`)
+
+- **`/api/telegram`** (or init) – initData validation, user upsert.
+- **`/api/ai`** – AI proxy; used by the TS app.
+
+All of the above must work end-to-end in the TS app and stay within the security model (initData-only auth, no raw secrets to server, wallet registration and pending tx where applicable).
+
+---
+
+## Short and Medium term backlogs
+
+- **`app/short_term_backlog.md`** (3 items): Response formatting, app theme, AI & search bar.
+- **Root `medium_term_backlog.md`** (backlog): Header indent bug, rotation on swap, edit-interval healthcheck, ticker link, scrolling in AI widget, bot parts isolation, ld timeout, “AI bd”, hovers, languages, favicon, wallet creation & nickname, jetton lockup, theme in Chrome, “Bd”, wallet creation, apps design, plan users BD for search, brand book, fixes, starting rewards, feed item types, PAY BY QR, swap long rate state, swaps, tokens.
+
+**Security:** All features above are delivered **with security plan compliance** (Phase 0–2: initData validation, wallet creation and registration, device auth, pending transactions, TonConnect if in scope, etc.). No “MVP without security”; the launch build is compliant.
+
+---
+
+## Time estimate
+
+Completion order and stages:
+
+| Stage | Scope | Estimate | Notes |
+|-------|--------|----------|--------|
+| **1** | **Security plan implementation** | **~3 weeks** | Phase 0 (validation, DB), Phase 1 (wallet creation, device auth, register), Phase 2 (pending tx, confirmations). |
+| **2** | **App (TS) – pages & UX** | **~3 weeks** | Transfer layout from `front/` and implement all pages in `./app` (send, swap, wallets, apps, AI, get, trade, creators, mnemonics, wallet panel); layout and navigation solid. |
+| **3** | **App (TS) – services & wiring** | **~3 weeks** | Auth, AI, and wallet flows in `./app`; backend alignment; errors and edge cases. |
+| **4** | **Integration, testing, finishing** | **~3 weeks** | E2E, platform checks, store/listing readiness, app/plan and root plan items (formatting, theme, bugs, features). |
+
+**MVP launch (full finish, platform-ready):** **~3 months** (12 weeks).