@www.hyperlinks.space/program-kit 1.2.181818 → 7.8.3

package/research & docs/keys-retrieval-console-scripts.js

@@ -0,0 +1,131 @@
+/**
+ * Telegram Mini App key retrieval checker (paste into DevTools console).
+ *
+ * Purpose:
+ * - Inspect where wallet keys are currently stored after app flow runs.
+ * - Check these keys across available storages:
+ *   1) SecureStorage: wallet_master_key
+ *   2) DeviceStorage: wallet_master_key
+ *   3) CloudStorage:  wallet_seed_cipher
+ *
+ * What it prints:
+ * - Per-storage availability (API object + method presence).
+ * - Read result for each key (err/value present/length).
+ * - Final quick verdict about expected Desktop fallback model:
+ *   - secureOnly: master key in SecureStorage
+ *   - deviceFallback: master key in DeviceStorage
+ *   - none: master key not found in either local store
+ *
+ * Notes:
+ * - This script does not print full secret values; it shows only existence/length.
+ * - In some Telegram Desktop builds, SecureStorage methods exist but return UNSUPPORTED.
+ */
+(async () => {
+  const wa = window.Telegram?.WebApp;
+  if (!wa) {
+    const out = { ok: false, error: "Telegram.WebApp not found" };
+    console.log("[keys-retrieval]", out);
+    return out;
+  }
+
+  const readSecure = (key) =>
+    new Promise((resolve) => {
+      const storage = wa.SecureStorage;
+      if (!storage || typeof storage.getItem !== "function") {
+        resolve({ present: false, err: "NO_API", value: null, canRestore: null });
+        return;
+      }
+      storage.getItem(key, (err, value, canRestore) => {
+        resolve({
+          present: true,
+          err: err ?? null,
+          value: value ?? null,
+          canRestore: canRestore ?? null,
+        });
+      });
+    });
+
+  const readDevice = (key) =>
+    new Promise((resolve) => {
+      const storage = wa.DeviceStorage;
+      if (!storage || typeof storage.getItem !== "function") {
+        resolve({ present: false, err: "NO_API", value: null });
+        return;
+      }
+      storage.getItem(key, (err, value) => {
+        resolve({
+          present: true,
+          err: err ?? null,
+          value: value ?? null,
+        });
+      });
+    });
+
+  const readCloud = (key) =>
+    new Promise((resolve) => {
+      const storage = wa.CloudStorage;
+      if (!storage || typeof storage.getItem !== "function") {
+        resolve({ present: false, err: "NO_API", value: null });
+        return;
+      }
+      storage.getItem(key, (err, value) => {
+        resolve({
+          present: true,
+          err: err ?? null,
+          value: value ?? null,
+        });
+      });
+    });
+
+  const [secureMaster, deviceMaster, cloudSeedCipher] = await Promise.all([
+    readSecure("wallet_master_key"),
+    readDevice("wallet_master_key"),
+    readCloud("wallet_seed_cipher"),
+  ]);
+
+  const hasSecureMaster = secureMaster.value != null && secureMaster.err == null;
+  const hasDeviceMaster = deviceMaster.value != null && deviceMaster.err == null;
+  const hasCloudSeedCipher = cloudSeedCipher.value != null && cloudSeedCipher.err == null;
+
+  const localTier = hasSecureMaster ? "secureOnly" : hasDeviceMaster ? "deviceFallback" : "none";
+
+  const result = {
+    ok: true,
+    webApp: {
+      platform: wa.platform ?? null,
+      version: wa.version ?? null,
+    },
+    keys: {
+      wallet_master_key: {
+        secureStorage: {
+          available: secureMaster.present,
+          err: secureMaster.err,
+          exists: hasSecureMaster,
+          valueLength: typeof secureMaster.value === "string" ? secureMaster.value.length : 0,
+          canRestore: secureMaster.canRestore ?? null,
+        },
+        deviceStorage: {
+          available: deviceMaster.present,
+          err: deviceMaster.err,
+          exists: hasDeviceMaster,
+          valueLength: typeof deviceMaster.value === "string" ? deviceMaster.value.length : 0,
+        },
+      },
+      wallet_seed_cipher: {
+        cloudStorage: {
+          available: cloudSeedCipher.present,
+          err: cloudSeedCipher.err,
+          exists: hasCloudSeedCipher,
+          valueLength: typeof cloudSeedCipher.value === "string" ? cloudSeedCipher.value.length : 0,
+        },
+      },
+    },
+    verdict: {
+      localTier,
+      modelOkForDesktopFallback: localTier === "deviceFallback" && hasCloudSeedCipher,
+    },
+  };
+
+  console.log("[keys-retrieval]", result);
+  return result;
+})();

package/{docs/security_plan_raw.md → research & docs/security_plan_raw.md }

@@ -78,7 +78,7 @@ This file describes a practical implementation plan for the security model defin
     - 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>)`.
+      - Store it via `SecureStorage.setItem('wallet_master_key', …)` when supported; if that fails (e.g. Desktop `UNSUPPORTED`), fall back to `DeviceStorage` and warn the user (see `docs/security_raw.md`).
       - 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.

package/{docs/security_raw.md → research & docs/security_raw.md }

@@ -21,9 +21,20 @@ This document describes the current high-level design; it is not a formal audit.
 - **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)).
+- **Telegram DeviceStorage**: Persistent **local** key–value storage inside the Telegram client for the bot (up to 5 MB per user). Telegram documents it as conceptually similar to browser `localStorage`, **not** as Keychain/Keystore-backed secure storage (see [DeviceStorage](https://core.telegram.org/bots/webapps#devicestorage)).
 
 We **never store raw mnemonics** on our backend or in Telegram CloudStorage.
 
+### SecureStorage vs DeviceStorage (product stance)
+
+- **SecureStorage** is the preferred place for the wallet master key: encrypted at rest and isolated using OS secure hardware where Telegram implements it.
+- Some clients (notably **Telegram Desktop** in common builds) report `secure_storage_failed` with errors such as **`UNSUPPORTED`**, meaning there is no SecureStorage bridge for that Mini App session.
+- **DeviceStorage fallback** (used only when SecureStorage fails) keeps the same split as the design (master key local, seed as ciphertext in CloudStorage), but the master key is **not** under the same hardware-backed guarantees. It is **stricter than random website `localStorage`** (scoped to the Telegram client and bot), yet **strictly weaker than SecureStorage** against threats that can read Mini App storage (e.g. XSS, compromised WebView, malware with access to Telegram’s local storage).
+
+**Alternative architectures** (not the default in this repo) include: **require** SecureStorage and **block** signing until the user opens the Mini App on a supported client, or a **Tonkeeper-style** model (password-encrypted secrets with persistence via CloudStorage only, with security bounded by password strength and KDF choice).
+
+The Mini App implementation tries **SecureStorage first**, then **DeviceStorage** for `wallet_master_key`, and surfaces a short in-app notice when the weaker path is used.
+
 ---
 
 ## I. Wallet Creation in Telegram
@@ -36,10 +47,8 @@ Flow when a user creates a wallet for the first time in the Telegram Mini App on
 
 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.
+   - This master key is stored in Telegram **`SecureStorage` when available** (Keychain / Keystore on mobile).
+   - If SecureStorage is unavailable (`UNSUPPORTED` or failure), the app **falls back to `DeviceStorage`** and explains the weaker guarantee in the UI (see “SecureStorage vs DeviceStorage” above).
 
 3. **Create and store wallet seed cipher (cloud)**
    - The app creates a **wallet seed cipher**:
@@ -57,12 +66,12 @@ Flow when a user creates a wallet for the first time in the Telegram Mini App on
 **Properties**
 
 - The **first Telegram device** has everything needed to use the wallet:
-  - Master key in `SecureStorage`.
+  - Master key in `SecureStorage` or, on some clients, `DeviceStorage`.
   - 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).
+  - Recover the master key from the same Telegram local store (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.
+- If local storage is wiped, the user must re-enter the mnemonic.
 
 ---
 
@@ -275,7 +284,7 @@ When the user taps the button in the bot message and opens the Mini App:
 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 locally available wallet (seed/master key in Telegram `SecureStorage` or `DeviceStorage` fallback).
    - 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:
@@ -311,7 +320,7 @@ For users who click a **web URL** from the bot instead of the Mini App:
 - 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 Mini App (for signing with local master key in SecureStorage or DeviceStorage fallback),
   - 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. 
@@ -325,12 +334,12 @@ This model keeps transaction approvals **user‑driven and key‑local** (inside
   - 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).
+  - Each device has its own **wallet master key** stored in Telegram **SecureStorage** when supported, else **DeviceStorage** (weaker).
   - 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.
+  - `Wallet Seed Cipher` in CloudStorage is encrypted with the wallet master key, which should exist only on the user’s Telegram client for that device.
+  - An attacker with only CloudStorage access cannot derive the mnemonic without the master key.
 
 - **Cross-platform restore requires mnemonic:**
   - Any **new environment** (new Telegram device with empty SecureStorage or any non-Telegram platform) requires the mnemonic once.
@@ -341,5 +350,5 @@ This model keeps transaction approvals **user‑driven and key‑local** (inside
 
 - 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 `SecureStorage` is documented for **iOS and Android**; **Desktop and some builds may not support it**, triggering fallback to `DeviceStorage` or leaving the key unsaved until the user uses a supported client or restores with the mnemonic.
 - 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/research & docs/storage-availability-console-script.js

@@ -0,0 +1,152 @@
+/**
+ * Telegram Mini App storage availability probe (paste into DevTools console).
+ *
+ * What this script does:
+ * 1) Checks whether Telegram WebApp bridge exists.
+ * 2) Probes SecureStorage by real write+read+remove roundtrip.
+ * 3) Probes DeviceStorage by real write+read+remove roundtrip.
+ * 4) Probes CloudStorage by real write+read+remove roundtrip.
+ * 5) Prints a single QA verdict:
+ *    - "secure" => SecureStorage works.
+ *    - "device" => SecureStorage fails, but DeviceStorage works.
+ *    - "none"   => neither SecureStorage nor DeviceStorage works.
+ *
+ * Notes:
+ * - "API object exists" does NOT mean storage is supported. Telegram Desktop may expose methods
+ *   but return UNSUPPORTED at runtime. This script verifies runtime behavior.
+ * - Probe keys are deleted at the end.
+ */
+(async () => {
+  const wa = window.Telegram?.WebApp;
+  if (!wa) {
+    const result = {
+      verdict: "none",
+      webApp: null,
+      error: "Telegram.WebApp not found (not running in TMA context).",
+    };
+    console.log("[storage-probe]", result);
+    return result;
+  }
+
+  const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  const probeSecureOrDevice = async (storage, eventPrefix, includeCanRestore) => {
+    const key = `probe_${eventPrefix}_${Date.now()}`;
+    const value = "ok";
+    let eventFailed = null;
+
+    const failedEventName = `${eventPrefix}_failed`;
+    const savedEventName = `${eventPrefix}_key_saved`;
+
+    const onFailed = (payload) => { eventFailed = payload; };
+    const onSaved = () => {};
+
+    try {
+      wa.onEvent?.(failedEventName, onFailed);
+      wa.onEvent?.(savedEventName, onSaved);
+    } catch {}
+
+    const cleanup = () => {
+      try { wa.offEvent?.(failedEventName, onFailed); } catch {}
+      try { wa.offEvent?.(savedEventName, onSaved); } catch {}
+    };
+
+    if (!storage || typeof storage.setItem !== "function" || typeof storage.getItem !== "function") {
+      cleanup();
+      return {
+        present: false,
+        supported: false,
+        set: null,
+        get: null,
+        remove: null,
+        eventFailed: null,
+      };
+    }
+
+    return new Promise((resolve) => {
+      storage.setItem(key, value, (setErr, stored) => {
+        storage.getItem(key, async (getErr, gotValue, canRestore) => {
+          await wait(50);
+
+          const base = {
+            present: true,
+            supported: setErr == null && getErr == null && gotValue === value,
+            set: { err: setErr ?? null, stored: stored ?? null },
+            get: includeCanRestore
+              ? { err: getErr ?? null, value: gotValue ?? null, canRestore: canRestore ?? null }
+              : { err: getErr ?? null, value: gotValue ?? null },
+            remove: null,
+            eventFailed,
+          };
+
+          if (typeof storage.removeItem === "function") {
+            storage.removeItem(key, (rmErr, removed) => {
+              base.remove = { err: rmErr ?? null, removed: removed ?? null };
+              cleanup();
+              resolve(base);
+            });
+          } else {
+            cleanup();
+            resolve(base);
+          }
+        });
+      });
+    });
+  };
+
+  const probeCloudStorage = async () => {
+    const cs = wa.CloudStorage;
+    const key = `probe_cloud_${Date.now()}`;
+    const value = "ok";
+
+    if (!cs || typeof cs.setItem !== "function" || typeof cs.getItem !== "function") {
+      return {
+        present: false,
+        supported: false,
+        set: null,
+        get: null,
+        remove: null,
+      };
+    }
+
+    return new Promise((resolve) => {
+      cs.setItem(key, value, (setErr, stored) => {
+        cs.getItem(key, (getErr, gotValue) => {
+          const out = {
+            present: true,
+            supported: setErr == null && getErr == null && gotValue === value,
+            set: { err: setErr ?? null, stored: stored ?? null },
+            get: { err: getErr ?? null, value: gotValue ?? null },
+            remove: null,
+          };
+
+          if (typeof cs.removeItem === "function") {
+            cs.removeItem(key, (rmErr, removed) => {
+              out.remove = { err: rmErr ?? null, removed: removed ?? null };
+              resolve(out);
+            });
+          } else {
+            resolve(out);
+          }
+        });
+      });
+    });
+  };
+
+  const secureStorage = await probeSecureOrDevice(wa.SecureStorage, "secure_storage", true);
+  const deviceStorage = await probeSecureOrDevice(wa.DeviceStorage, "device_storage", false);
+  const cloudStorage = await probeCloudStorage();
+
+  const verdict = secureStorage.supported ? "secure" : deviceStorage.supported ? "device" : "none";
+
+  const result = {
+    verdict,
+    webApp: { platform: wa.platform ?? null, version: wa.version ?? null },
+    secureStorage,
+    deviceStorage,
+    cloudStorage,
+  };
+
+  console.log(`[storage-probe] verdict=${verdict}`, result);
+  return result;
+})();

package/research & docs/storage-lifetime.md

@@ -0,0 +1,33 @@
+# Storage Lifetime for Wallet Keys
+
+This document summarizes practical storage lifetime expectations for wallet-related secrets.
+
+Important: "lifetime" is never absolute. Every layer can be lost due to account loss, uninstall, reset, policy changes, corruption, or compromise.
+
+## Quick Matrix
+
+| Storage type | Typical lifetime | Main limiting factor | Cross-device | Notes for wallet keys |
+|---|---|---|---|---|
+| Telegram CloudStorage | Potentially long-lived | Telegram account/app availability and platform behavior | Yes (inside Telegram ecosystem) | Use for ciphertext/public metadata, not raw mnemonic |
+| Telegram SecureStorage | Device-scoped durable | Device/app reinstall/reset and client support | No | Best TMA local tier when supported |
+| Telegram DeviceStorage | Device-scoped durable | Device/app reinstall/reset | No | Weaker than SecureStorage; fallback tier |
+| Session Storage (`sessionStorage`) | Current tab/session only | Tab/window/browser session end | No | Not suitable for persistent keys |
+| Browser Local Storage (`localStorage`) | Potentially long-lived on same browser profile | User clearing data, browser profile loss | No | Use only encrypted blobs if needed |
+| IndexedDB (web) | Potentially long-lived on same browser profile | User/browser data clearing, profile loss | No | Better than localStorage for larger encrypted blobs |
+| Expo Secure Store (iOS/Android) | Durable on device | Uninstall/reset/device change | No | Good native local secret store; still not "forever" |
+| Electron OS secure storage (Windows/macOS) | Durable on device profile | OS profile/device lifetime, reinstall/migration | No | Suitable desktop local secret store |
+| In-memory runtime only | Process/session only | App restart/crash/background termination | No | Best for temporary decrypted material |
+
+## Lifetime Statements (practical wording)
+
+- **Telegram CloudStorage:** theoretically long-lived, practically bounded by **Telegram account lifetime and platform behavior**.
+- **Device-local storage (SecureStorage/DeviceStorage/Secure Store/OS keychain):** bounded by **device/app/profile lifetime**.
+- **Session storage:** bounded by **session lifetime** (tab/window/app session).
+
+## Recommended usage pattern
+
+1. Keep **mnemonic as offline backup** (user-controlled, not in backend/cloud plaintext).
+2. Store day-to-day local unlock material in the strongest available **device-local secure store**.
+3. Store only **ciphertext** in cloud/sync layers.
+4. Treat all lifetimes as "best effort durability", not guaranteed permanence.
+

package/research & docs/telegram-raw-keys-cloud-storage-risks.md

@@ -0,0 +1,31 @@
+# Telegram CloudStorage Raw Keys Risks
+
+This note clarifies a common misunderstanding:
+
+- It is true that Telegram Mini App `CloudStorage` is scoped per bot/per user.
+- It is true that each Telegram user session is strongly protected by Telegram account security controls (session management, device authorization, transport security, etc.).
+- It is also true that endpoint compromise exists in both models (Bitcoin Core local storage and TMA/web clients).
+
+The key security difference is not "cross-user direct reads". The key difference is how compromise can scale through the app runtime.
+
+In other words: Telegram session protection is a strong baseline and should be acknowledged. The residual risk discussed here is about compromised Mini App code/runtime on an already authenticated user session, not about bypassing Telegram account/session controls.
+
+## Corrected comparison
+
+Exactly: a PC can be hacked in both cases.
+
+- **Bitcoin Core local storage:** an attacker usually needs to compromise that specific machine (or steal wallet backups) to get that user's keys.
+- **Raw mnemonic in Telegram CloudStorage:** per-user storage still applies, but if the Mini App runtime/supply chain is compromised, malicious code can read each currently logged-in user's own CloudStorage during their session and exfiltrate it. This can impact many users over time without a "read all users" API.
+
+So both models are vulnerable to endpoint compromise, but web/TMA delivery can add centralized distribution/supply-chain risk that increases aggregate exposure.
+
+## Practical differences vs local desktop wallet model
+
+- **Runtime surface:**
+  - Local desktop wallet (Bitcoin Core style): narrower app distribution/runtime model.
+  - Web/TMA app: JavaScript/runtime/supply-chain surface is broader.
+
+- **Secret impact on read:**
+  - **Raw mnemonic in cloud:** one successful read is immediate takeover.
+  - **Encrypted cloud blob:** attacker still needs decrypt capability (password/device key), which adds a barrier.
+

package/{docs/wallets_hosting_architecture.md → research & docs/wallets_hosting_architecture.md }

@@ -1,7 +1,7 @@
 # HyperlinksSpace — Wallet Architecture Doc
 
 > High-level system design, UI flow principles, and implementation thoughts.  
-> Target: non-custodial TON wallet built into the HyperlinksSpace app (Flutter/TMA/Web).
+> Target: TON wallet architecture options for HyperlinksSpace app (Flutter/TMA/Web), including non-custodial and custodial modes.
 
 ---
 
@@ -254,4 +254,150 @@ Swap between implementations via a flag (`kUseMockWalletState` for dev, env-driv
 
 ---
 
+## 13. Custodial Model Extension
+
+This section adds a custodial architecture option alongside the existing non-custodial design.
+
+### 13.1 What "custodial" means in this doc
+
+- Wallet secrets are stored centrally as encrypted data in backend storage.
+- Backend trust boundary can participate in decrypt/sign authorization.
+- User identity (Google/Telegram/GitHub/email OTP) becomes a stronger operational gate.
+
+This is a product/trust choice, not just an implementation detail.
+
+---
+
+### 13.2 Custodial key architecture (envelope encryption)
+
+Store per-wallet:
+
+- `ciphertext` (wallet secret encrypted by a DEK)
+- `wrapped_dek` (DEK encrypted by KEK)
+- metadata (`key_version`, `algo`, `created_at`, `status`)
+
+Keep KEK in KMS/HSM, not in DB/app code.
+
+Result:
+- DB theft alone is insufficient.
+- Attacker also needs KMS/HSM access path and permissions.
+
+---
+
+### 13.3 Identity and auth in custodial mode
+
+Identity providers:
+- Google OAuth
+- GitHub OAuth
+- Telegram login bridge
+- Email + OTP (protection code)
+
+Account linking maps all providers to one internal `user_id`.
+
+Auth session is used to authorize protected operations:
+- key unwrap requests
+- signing requests
+- provider linking/unlinking
+
+---
+
+### 13.4 Custodial state machine
+
+```
+[ No Wallet Record ]
+     │
+     ├── Create wallet ─► [ Custodial Encrypted ]
+     │                         │
+     │                         ├── Unlock request (auth + policy) ─► [ Session Unlocked ]
+     │                         │                                         │
+     │                         │                                         └── Sign tx ─► [ Ready ]
+     │                         │
+     └── Restore/import ─────► [ Custodial Encrypted ]
+```
+
+`Session Unlocked` should be short-lived and policy-limited (risk checks, cooldowns, limits).
+
+---
+
+### 13.5 Signing variants
+
+## Variant A: Backend signing (fully custodial)
+- Backend unwraps DEK and signs transactions server-side.
+- Client receives signed transaction/hash.
+- Simplest UX, highest custodial responsibility.
+
+## Variant B: Backend-assisted client resolve (hybrid custodial)
+- Backend authorizes access and returns short-lived decrypt context.
+- Client resolves and signs locally.
+- Better client-side control, still centralized key lifecycle.
+
+Choose one variant explicitly in product docs and legal language.
+
+---
+
+### 13.6 API extension for custodial mode
+
+```
+POST /wallet/custodial/create
+  Body: { user_id, wallet_label, encrypted_payload, wrapped_dek, key_version }
+  Response: { ok: true, wallet_id }
+
+POST /wallet/custodial/unlock
+  Body: { wallet_id, auth_context }
+  Response: { unlock_token, expires_at }   // or server-side unlock only
+
+POST /wallet/custodial/sign
+  Body: { wallet_id, unlock_token, tx_payload }
+  Response: { signed_tx | tx_hash }
+
+POST /wallet/custodial/rotate-kek
+  Body: { wallet_id? | batch_selector, new_key_version }
+  Response: { rewrapped_count }
+```
+
+All endpoints must be audited and rate-limited.
+
+---
+
+### 13.7 Security controls required in custodial mode
+
+- KMS/HSM-backed KEK, non-exportable where possible
+- Strict IAM separation (runtime vs admin)
+- Row-level access control by `user_id`
+- Risk checks before unlock/sign (IP/device anomaly, velocity limits)
+- Immutable security event log
+- Emergency freeze and key-rotation runbook
+- Signed release pipeline + dependency controls
+
+---
+
+### 13.8 UX implications vs non-custodial
+
+Benefits:
+- Easier cross-device recovery
+- Less mnemonic friction for mainstream users
+
+Tradeoffs:
+- Backend/service compromise has larger blast radius
+- Stronger legal/compliance burden
+- Must clearly disclose custodial trust model
+
+Recommended product stance:
+- Keep non-custodial as default for advanced users.
+- Offer custodial mode as explicit opt-in with clear warnings and recovery terms.
+
+---
+
+### 13.9 Updated roadmap including custodial track
+
+| Phase | Non-custodial track | Custodial track |
+|---|---|---|
+| **Phase 1** | Create/restore local wallet, deploy flow | Auth foundation (Google/GitHub/Telegram/email OTP), user linking |
+| **Phase 2** | Device/local storage hardening | Envelope storage (`ciphertext` + `wrapped_dek`) + KMS/HSM integration |
+| **Phase 3** | TMA/Desktop fallback tiers | Unlock/sign endpoints + policy/rate limits |
+| **Phase 4** | Send/receive/history | Custodial signing UX + anomaly protections |
+| **Phase 5** | Backup/export UX hardening | Key rotation, incident runbooks, compliance hardening |
+
+---
+
 *Last updated: April 2026. Maintained in repo at `docs/wallets_hosting_architecture.md`.*

package/scripts/test-api-base.ts

@@ -1,8 +1,8 @@
 /**
- * Quick check that api/base.ts works. Run: npx tsx scripts/test-api-base.ts
+ * Quick check that api/_base.ts works. Run: npx tsx scripts/test-api-base.ts
  * In Node (no window), getApiBaseUrl() uses Vercel env or falls back to http://localhost:3000.
  */
-import { getApiBaseUrl, buildApiUrl } from "../api/base.js";
+import { getApiBaseUrl, buildApiUrl } from "../api/_base.js";
 
 const base = getApiBaseUrl();
 const full = buildApiUrl("/api/telegram");