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

package/docs/auth-and-centralized-encrypted-keys-plan.md

@@ -0,0 +1,440 @@
+# Auth + Centralized Encrypted Keys Plan (Supabase)
+
+This document defines a practical implementation plan for:
+
+- Multi-provider login: **Google**, **Telegram**, **GitHub**, and **email + protection code (OTP)**
+- Centralized storage in **Supabase**
+- Wallet secrets stored as **encrypted blobs only** (no plaintext mnemonic/private keys server-side)
+
+---
+
+## 1) Product Goal
+
+Enable users to sign in from multiple platforms and recover wallet access from Supabase by using account credentials plus a user-held decryption secret model.
+
+## 2) Security Goal
+
+- Supabase/backend stores only ciphertext envelopes and metadata.
+- Decryption happens client-side.
+- Server does not receive plaintext mnemonic/private keys.
+
+---
+
+## 3) Trust Model Decision
+
+To avoid custodial key handling by backend, choose one of these decryption models:
+
+1. **Password-derived key model (recommended for centralized sync)**
+   - User sets a wallet passphrase.
+   - Client derives key with Argon2id.
+   - Ciphertext stored in Supabase.
+2. **Device-key model only**
+   - Better local UX, weaker cross-device recovery unless mnemonic re-entry is required.
+
+For this plan, use model (1) as canonical centralized recovery path.
+
+---
+
+## 3.1) What "wrapped decrypt key" means (plain language)
+
+This phrase means we do not store the real decryption key directly in the database.
+
+- **DEK (Data Encryption Key):** key that encrypts wallet secret/mnemonic.
+- **KEK (Key Encryption Key):** key that encrypts ("wraps") the DEK.
+
+So database stores:
+- wallet ciphertext (encrypted by DEK)
+- wrapped DEK (encrypted by KEK)
+
+Database does **not** store:
+- plaintext mnemonic
+- plaintext DEK
+- plaintext KEK
+
+### Why KMS/HSM is mentioned
+
+`KEK` should live in a managed key system (AWS KMS, GCP KMS, Azure Key Vault HSM, etc.), not in app code or DB columns.
+
+When app needs decrypt flow:
+1. User authenticates (Google/Telegram/GitHub/email OTP).
+2. Backend loads `wrapped_dek` + wallet `ciphertext` from DB.
+3. Backend asks KMS/HSM to unwrap DEK (or returns a short-lived tokenized decrypt result, depending on policy).
+4. Decrypt happens in the chosen boundary (client-side or controlled backend flow).
+
+### Tiny analogy
+
+- Wallet data = document in locked box (ciphertext).
+- DEK = key to that box.
+- KEK = key to a safe that contains the DEK.
+- KMS/HSM = guarded safe room.
+
+This way, stealing only DB rows is not enough to decrypt user wallets.
+
+---
+
+## 3.2) Newbie note: "But ciphertext and wrapped key are in the same DB"
+
+This is a common concern and the short answer is:
+
+- Yes, they can be stored in the same row.
+- No, that does not automatically break security.
+
+### Why this can still be safe
+
+Think of three pieces:
+
+1. `ciphertext` (locked wallet data)
+2. `wrapped_dek` (the key to the lock, but itself locked)
+3. `kek` in KMS/HSM (the key that unlocks `wrapped_dek`)
+
+If attacker steals DB only, they get (1) and (2), but not (3).
+Without (3), they cannot recover plaintext keys.
+
+### What actually protects the system
+
+The real protection is **access control to KMS/HSM**, not hiding DB relations.
+
+- Keep KEK outside DB.
+- Restrict KMS permissions to minimum required service path.
+- Audit and rate-limit unwrap operations.
+
+### Optional extra hardening
+
+You can split storage across two databases (ciphertext in one, wrapped key in another), but this is additional defense-in-depth. It does not replace KMS/HSM boundary.
+
+Rule of thumb for beginners:
+**Do not rely on "they cannot match rows"; rely on "they cannot access KEK".**
+
+---
+
+## 3.3) How user session works with KEK (Google/Telegram/GitHub/email OTP)
+
+Important: user login session is an **authorization signal**, not the KEK itself.
+
+- Google/Telegram/GitHub/email OTP proves "this user is authenticated".
+- Backend then decides whether to allow key unwrap path.
+- KEK remains in KMS/HSM and is never replaced by OAuth/session token.
+
+Typical flow:
+
+1. User logs in and gets a valid app session.
+2. App requests wallet unlock/decrypt operation.
+3. Backend verifies session + policy checks (device/risk/rate limits).
+4. Backend reads `wrapped_dek + ciphertext` from DB.
+5. Backend calls KMS/HSM to unwrap DEK.
+6. Decrypt/sign path continues under selected trust boundary.
+
+This is why people say "session gates KEK usage", not "session is KEK".
+
+### Two deployment variants
+
+- **Variant A (more custodial):**
+  - Backend unwraps DEK and performs decrypt/sign server-side.
+  - User gets signed result/tx hash.
+- **Variant B (hybrid):**
+  - Backend authorizes and returns short-lived decrypt material/session token.
+  - Client resolves/decrypts locally for signing.
+
+Choose Variant A only if you explicitly accept custodial responsibility.
+
+---
+
+## 3.4) Why keep both `wrapped_dek` and `ciphertext` in DB (not one encrypted entity)
+
+You can think "why not one giant blob encrypted by KEK directly?".
+Short answer: envelope encryption with separate DEK is safer and more operationally practical.
+
+Reasons:
+
+1. **KMS/HSM usage limits and performance**
+   - KMS is best for wrapping small keys, not encrypting large/high-volume payloads repeatedly.
+   - DEK handles data encryption efficiently.
+
+2. **Key rotation without re-encrypting all wallet data**
+   - Rotate KEK by re-wrapping DEKs.
+   - No need to decrypt/re-encrypt every wallet ciphertext each time KEK rotates.
+
+3. **Cryptographic separation of duties**
+   - DEK protects wallet payload.
+   - KEK protects DEK.
+   - Cleaner blast-radius control and auditing.
+
+4. **Metadata and versioning flexibility**
+   - You can evolve ciphertext formats (AEAD params/version) independently from KEK lifecycle.
+
+5. **Standard industry pattern**
+   - This is standard "envelope encryption" used by major cloud security systems.
+
+So storing both `ciphertext` and `wrapped_dek` is expected architecture, not duplication.
+
+---
+
+## 3.5) KMS/HSM section: what it is and how to operate it
+
+## What is KMS?
+
+**KMS (Key Management Service)** is a managed service that stores and uses cryptographic master keys with strict access controls, logging, and rotation features.
+
+Examples:
+- AWS KMS
+- Google Cloud KMS
+- Azure Key Vault (with HSM-backed options)
+
+## What is HSM?
+
+**HSM (Hardware Security Module)** is specialized hardware designed to keep key material protected and perform crypto operations with strong tamper resistance.
+
+In practice:
+- Many cloud KMS offerings can use HSM-backed keys.
+- Teams usually start with managed KMS and move to stricter HSM policies if required by risk/compliance.
+
+## Why use KMS/HSM here
+
+- Keep `KEK` out of application DB and source code.
+- Centralize key policy and access control.
+- Get immutable audit logs for unwrap/encrypt/decrypt operations.
+- Support controlled key rotation and key disable/emergency revoke.
+
+## How to deal with it (practical checklist)
+
+1. **Create KEK in KMS/HSM**
+   - Mark as non-exportable when available.
+   - Separate key per environment (`dev/stage/prod`).
+
+2. **Restrict IAM permissions**
+   - App service can only call required operations (typically `Decrypt/Unwrap`, maybe `Encrypt/Wrap`).
+   - No broad admin access from runtime services.
+
+3. **Use envelope encryption pattern**
+   - Generate DEK for wallet payload encryption.
+   - Store `ciphertext + wrapped_dek` in DB.
+   - Never store plaintext KEK/DEK at rest.
+
+4. **Add policy checks before unwrap**
+   - Require valid session and account state.
+   - Apply risk checks (IP/device anomalies, rate limits, cooldowns).
+   - Log every sensitive operation.
+
+5. **Implement rotation**
+   - Rotate KEK on schedule.
+   - Re-wrap DEKs in background jobs.
+   - Keep key version metadata in DB.
+
+6. **Prepare incident controls**
+   - Ability to disable key version quickly.
+   - Emergency freeze for high-risk accounts.
+   - Recovery runbook for key compromise scenarios.
+
+## Common mistakes to avoid
+
+- Putting KEK plaintext in `.env` and calling it "KMS-ready".
+- Giving app runtime full KMS admin permissions.
+- Missing unwrap rate limits and anomaly detection.
+- No audit review pipeline for key operations.
+- Designing without key-rotation path from day one.
+
+## Newbie rule
+
+If DB is stolen, attacker should still need **separate KMS/HSM access** to decrypt anything.
+If DB theft alone can decrypt wallets, architecture is wrong.
+
+---
+
+## 4) Authentication Architecture
+
+Use **Supabase Auth** as identity layer:
+
+- Google OAuth
+- GitHub OAuth
+- Email + protection code (OTP / magic code)
+- Telegram login bridge (custom verifier service; link to Supabase user)
+
+### Identity Linking
+
+A single user can link multiple auth methods to one account.
+
+- Primary identity key: `user_id` (Supabase Auth UUID)
+- Linked providers table stores provider identifiers (`google_sub`, `github_id`, `telegram_id`, etc.)
+
+---
+
+## 5) Wallet Encryption Envelope
+
+Store one or more encrypted wallet envelopes per user.
+
+### Envelope format (server-stored)
+
+- `ciphertext` (base64)
+- `nonce/iv`
+- `kdf` params:
+  - `algorithm = argon2id`
+  - `salt`
+  - `memory_kib`
+  - `iterations`
+  - `parallelism`
+  - `dk_len`
+- `aead`:
+  - `algorithm = aes-256-gcm` (or xchacha20-poly1305)
+  - optional `aad`
+- `version`
+- `created_at`, `updated_at`
+
+### Crypto rules
+
+- KDF and encryption run **client-side only**.
+- Never send passphrase to server.
+- Never log secrets/ciphertext in verbose logs.
+
+---
+
+## 6) Supabase Data Model
+
+## `profiles`
+- `id` (uuid, fk -> auth.users.id)
+- `username` (nullable unique)
+- `display_name`
+- `created_at`
+
+## `auth_identities`
+- `id` (uuid)
+- `user_id` (uuid)
+- `provider` (`google|github|telegram|email_otp`)
+- `provider_subject` (string)
+- unique (`provider`, `provider_subject`)
+
+## `wallet_envelopes`
+- `id` (uuid)
+- `user_id` (uuid)
+- `wallet_label`
+- `ciphertext`
+- `kdf_json`
+- `aead_json`
+- `envelope_version`
+- `is_active`
+- timestamps
+
+## `security_events`
+- `id`, `user_id`
+- `event_type`
+- `ip_hash`, `ua_hash`
+- timestamps
+
+---
+
+## 7) Authorization and RLS
+
+Enable Row Level Security:
+
+- user can read/write only rows where `user_id = auth.uid()`.
+- admin/service role separated for backend-only tasks.
+- strict policies for envelope update/delete.
+
+Add rate limits and abuse controls at API edge:
+
+- login attempt throttling
+- envelope fetch/update throttling
+- device/IP anomaly checks
+
+---
+
+## 8) Provider-Specific Notes
+
+## Google / GitHub
+- Use Supabase OAuth providers.
+- Standard callback + session issuance.
+
+## Email + Protection Code (OTP)
+- Use Supabase OTP flow (`signInWithOtp`) with short code expiry.
+- Rate-limit OTP requests and verify attempts.
+- Add anti-abuse checks (per-IP/per-email cooldown).
+- Optional: require email verification before provider linking actions.
+
+## Telegram
+- Verify Telegram login payload (`id_token`/signed data) in backend function.
+- On success, link Telegram identity to existing `user_id` or create new profile.
+- Telegram auth is identity only, not decryption secret.
+
+---
+
+## 9) Client Flows
+
+## Registration
+1. User signs up via any provider.
+2. App prompts wallet passphrase setup (if no envelope exists).
+3. Client generates/imports mnemonic.
+4. Client encrypts mnemonic -> envelope.
+5. Upload envelope to Supabase.
+
+## Login on new device
+1. User authenticates via provider.
+2. App fetches envelope from Supabase.
+3. User enters wallet passphrase.
+4. Client decrypts locally and unlocks wallet.
+
+## Passphrase change
+1. Unlock with current passphrase.
+2. Re-encrypt with new Argon2id salt/params.
+3. Replace envelope atomically.
+
+## Email protection-code recovery
+1. User requests login code by email.
+2. Enters code and gets authenticated session.
+3. If wallet envelope exists, user enters wallet passphrase to decrypt.
+4. If passphrase is forgotten, user must recover with mnemonic and set a new passphrase.
+
+---
+
+## 10) Operational Security Requirements
+
+- CSP hardening and dependency pinning for web/TMA.
+- Secrets scanning and signed CI artifacts.
+- Audit trail for sensitive actions.
+- Incident playbook for account takeover and suspicious activity.
+- User alerts (new login, passphrase changed, provider linked/unlinked).
+- User alerts (new OTP login, passphrase changed, provider linked/unlinked).
+
+---
+
+## 11) Migration Plan (from current model)
+
+1. Keep existing TMA SecureStorage/DeviceStorage path active.
+2. Add optional centralized envelope creation for users.
+3. Backfill on next successful unlock/sign event.
+4. After adoption, use centralized envelope as cross-device recovery path.
+5. Maintain mnemonic-first emergency recovery.
+
+---
+
+## 12) Scope, Non-goals, and Warnings
+
+Non-goals:
+- Backend plaintext key custody
+- Signing in backend with user mnemonic/private key
+
+Warnings:
+- If user forgets both mnemonic and passphrase, recovery is impossible by design.
+- Centralized ciphertext still increases account-takeover pressure; defense must focus on OTP hardening, rate limits, and alerts.
+
+---
+
+## 13) Phase Breakdown
+
+## Phase A: Identity foundation
+- Configure Supabase Auth providers.
+- Add account linking UX.
+- Add RLS and identity tables.
+
+## Phase B: Envelope crypto
+- Implement client Argon2id + AEAD module.
+- Add `wallet_envelopes` APIs and tests.
+
+## Phase C: Recovery UX
+- New device unlock flow.
+- Passphrase reset/re-encrypt flow.
+
+## Phase D: Hardening
+- Abuse controls, telemetry, alerts, and audits.
+
+## Phase E: Rollout
+- Feature flags, gradual rollout, and migration metrics.
+

package/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

@@ -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

@@ -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.