Document telegram-native task 5 foundation

09 - Audits/Task 5 Telegram-Native Verification Report.md

@@ -0,0 +1,110 @@
+---
+title: Task 5 Telegram-Native Verification Report
+tags: [taskmaster, verification, telegram]
+created: 2026-05-24
+status: draft
+---
+
+# Task 5 Telegram-Native Verification Report
+
+## 1) Deliverable map
+
+| Subtask | Artifact | Location |
+|---|---|---|
+| 5.1 | Product surface map | `09 - Audits/Task 5.1 Telegram Product Surface and Flow Map.md` |
+| 5.2 | Identity linking and session model | `09 - Audits/Task 5.2 Telegram Identity Linking and Session Model.md`, backend Telegram service/model/routes |
+| 5.3 | Bot command and notification foundation | `09 - Audits/Task 5.3 Telegram Bot Command and Notification Foundation.md`, backend Telegram webhook skeleton |
+| 5.4 | Mini App shell | `09 - Audits/Task 5.4 Telegram Mini App Shell Implementation.md`, frontend `/telegram` route |
+| 5.5 | Payment/wallet strategy | `09 - Audits/Task 5.5 Telegram Payment and Wallet Strategy.md` |
+| 5.6 | Escrow/delivery/dispute/release action plan | `09 - Audits/Task 5.6 Telegram Escrow Delivery Dispute Release Actions.md` |
+| 5.7 | Admin/support operating surface plan | `09 - Audits/Task 5.7 Telegram Admin Support Surface.md` |
+| 5.8 | Security/compliance controls | `09 - Audits/Task 5.8 Telegram Security, Compliance, and Abuse Controls.md` |
+| 5.9 | QA/rollout/analytics/runbooks | `09 - Audits/Task 5.9 QA Rollout Analytics and Launch Runbooks.md` |
+
+## 2) Documentation verification executed
+
+Commands run while producing this report:
+
+```bash
+cd nick-doc && task-master next
+cd nick-doc && task-master show 5.1
+cd nick-doc && task-master show 5.5
+cd nick-doc && task-master show 5.8
+cd nick-doc && task-master show 5.9
+rg --files nick-doc/.taskmaster/docs
+npm run typecheck --silent
+npx jest __tests__/telegram-service.test.ts __tests__/telegram-routes.test.ts --runInBand --silent
+npx eslint src/services/telegram/telegramService.ts src/services/telegram/telegramRoutes.ts src/models/TelegramLink.ts src/models/TelegramSession.ts __tests__/telegram-service.test.ts __tests__/telegram-routes.test.ts
+npx jest __tests__/utils-test/telegram-webapp.test.ts __tests__/sections/telegram/telegram-mini-app-shell.test.tsx --runInBand
+npx eslint src/utils/telegram-webapp.ts src/sections/telegram/telegram-mini-app-shell.tsx src/app/telegram/page.tsx
+npx tsc --noEmit
+```
+
+## 2.1 Code artifacts added
+
+Backend:
+
+- `src/models/TelegramLink.ts`
+- `src/models/TelegramSession.ts`
+- `src/services/telegram/telegramService.ts`
+- `src/services/telegram/telegramRoutes.ts`
+- `src/services/telegram/index.ts`
+- `/api/telegram` route mount behind feature flag
+- `__tests__/telegram-service.test.ts`
+- `__tests__/telegram-routes.test.ts`
+
+Frontend:
+
+- `src/app/telegram/page.tsx`
+- `src/sections/telegram/telegram-mini-app-shell.tsx`
+- `src/sections/telegram/index.ts`
+- `src/utils/telegram-webapp.ts`
+- `paths.telegram.root`
+- `__tests__/utils-test/telegram-webapp.test.ts`
+- `__tests__/sections/telegram/telegram-mini-app-shell.test.tsx`
+
+## 3) Constraint checks against Task 4 docs
+
+- Canonical ledger and escrow states as authority: verified and referenced in all 4 Task 5 documents.
+- Provider adapters kept optional in the first phase: explicitly stated in Task 5.5.
+- Dispute hold and authorization gates preserved for Telegram-initiated financial transitions: repeated across all documents with links to:
+  - `Funds Ledger and Escrow State Machine Specification`
+  - `Payment Provider Adapter Spec`
+  - `Webhook Security Spec`
+  - `Security Ownership and Launch Decision Criteria`
+
+## 3.1 Test results
+
+Backend:
+
+- `npm run typecheck --silent` passed.
+- `npx jest __tests__/telegram-service.test.ts __tests__/telegram-routes.test.ts --runInBand --silent` passed: 2 suites, 12 tests.
+- Scoped backend ESLint passed on Telegram service/model/route/test files.
+
+Frontend:
+
+- `npx jest __tests__/utils-test/telegram-webapp.test.ts __tests__/sections/telegram/telegram-mini-app-shell.test.tsx --runInBand` passed: 2 suites, 6 tests.
+- Scoped frontend ESLint passed on Telegram utility/route/component files.
+- `npx tsc --noEmit` is blocked by two pre-existing non-Telegram errors:
+  - `src/components/payment/shkeeper-payment-widget.tsx` missing `sellerId` in an `IPaymentIntentPayload`.
+  - `src/web3/components/provider-payment.tsx` uses unregistered `solar:wallet-money-bold` icon.
+
+## 4) Remaining gaps and open questions
+
+1. Bot command actions are still a skeleton: updates are classified and deduped,
+   but commands/callbacks do not yet execute product workflows.
+2. Outbound Telegram notifications, preferences, blocked-bot handling, retry
+   metrics, and quiet mode are not implemented.
+3. Mini App shell is present, but request/offer/payment/dispute data loading and
+   action execution are still pending.
+4. Deep-link token schema still needs final claim set and signing key rotation schedule.
+5. Analytics schema and dashboard ownership for Telegram events remains to be implemented in code and monitoring tooling.
+6. Runbook automation checks for replay checks and payment mismatch drilldown are not yet scripted in operations tooling.
+
+## 5) Recommendation
+
+This pass completes the Task 5 foundation for product mapping, Telegram identity
+linking/session verification, Mini App shell, payment/wallet strategy, security
+controls, and launch QA documentation. Keep Task 5 open until bot actions,
+notifications, real Mini App marketplace workflows, Telegram escrow actions, and
+admin/support surfaces are implemented and verified.

09 - Audits/Task 5.1 Telegram Product Surface and Flow Map.md

@@ -0,0 +1,122 @@
+---
+title: Task 5.1 Telegram Product Surface and Flow Map
+tags: [taskmaster, telegram, product, flow-map, canonical-state]
+created: 2026-05-24
+status: draft
+---
+
+# Task 5.1 Telegram Product Surface and Flow Map
+
+Source: `/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md`
+
+This map defines the first-release Telegram-native surface for Task 5.1 and keeps the financial core bound to the canonical
+[`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md) and
+Task 4 authorization/risk controls.
+
+## 1) Channel split (first release)
+
+| Area | Bot messages | Mini App | Web/Admin-only (first release) |
+|---|---|---|---|
+| Discovery & onboarding | `/start`, `/help`, `/link`, `/settings` | Onboarding cards, link prompts, fallback CTA | Full self-serve onboarding docs |
+| Request browse/create | summary list + quick actions only | Full in-app list, create/edit request form | Full advanced catalog/search UI |
+| Offers | receive offer summary, accept/reject shortcuts | full offer list and detail, offer accept/reject | Seller negotiation detail with admin context |
+| Payment start | payment shortcut button + deep link payload | payment state UI + provider launch from in-app | Payment method setup, advanced failure handling |
+| Delivery evidence | status update nudges + evidence deep link | upload evidence from in-app flow | Full media manager + admin-side attachments |
+| Dispute | dispute open/summary + status check | open/respond/track dispute in app | Admin moderation, manual evidence review |
+| Release/Refund | only status blockers and support handoff | confirmation request + release/refund request | Execute actions through canonical payment API |
+| Notification settings | toggle on/off, blocked-state view | mirror of notification status and quiet mode | Full support/notification audit UI |
+| Support | support contact + report IDs | support request and context handoff | Admin/operator console and action audit |
+
+## 2) Canonical state mapping (all actions)
+
+All Telegram actions must map to existing canonical states and API-side checks:
+
+- `PurchaseRequest.status`: `pending` → `received_offers` → `in_negotiation` → `payment` → `processing` → `delivery` → `delivered` → `confirming` → `completed` / `cancelled`
+- `Payment.escrowState`: `FUNDED` / `PARTIALLY_FUNDED` / `RELEASABLE` / `DISPUTED` / `RELEASING` / `RELEASED` / `REFUNDING` / `REFUNDED` / `FAILED` / `CANCELLED`
+- `Dispute.status`: `OPEN` / `UNDER_REVIEW` / `RESOLVED_*` / `CLOSED` as appropriate
+
+The only transitions that may modify funds, release eligibility, or dispute holds are those enforced by the canonical service
+layer from the
+[`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md).
+
+## 3) Journey mapping by persona
+
+### 3.1 Unauthenticated user
+
+- See bot start/help and public support command.
+- Any authenticated action routes to account-link flow.
+- No request write actions without auth link.
+
+### 3.2 Unlinked Telegram user
+
+1. Start in bot or Mini App.
+2. Prompt account linking (`/link` equivalent) using signed callback token.
+3. Complete account link or return to web flow.
+4. After link success, deep link returns user to prior action context (request, offer, payment, or dispute).
+
+### 3.3 Linked buyer
+
+- Browse/create requests, send offer review decision, start payment, upload delivery evidence, open disputes, monitor request state, request release/refund.
+- No direct fund release path: Telegram actions read state and submit intent only.
+
+### 3.4 Linked seller
+
+- Receive offer and request notifications, update offer availability, review buyer disputes, upload shipping/proof artifacts.
+- No direct payout mutation from Telegram; actions remain canonical requests to existing payment/dispute endpoints.
+
+### 3.5 Admin/support
+
+- Dedicated support context in admin view only (first release).
+- Telegram-origin IDs and linked wallet/payment provenance shown in existing admin interfaces.
+- Any manual override for Telegram-originated cases follows the same step-up/two-person policy as web flows when configured in
+[`Security Ownership and Launch Decision Criteria`](Security%20Ownership%20and%20Launch%20Decision%20Criteria.md).
+
+## 4) Deep-link and context contract
+
+Deep-link entry points in order of priority:
+
+1. `request` detail
+2. `offer-review` (accept/reject)
+3. `payment-start`
+4. `dispute-open` / `dispute-track`
+5. `delivery-evidence`
+6. `account-link`
+
+Rules:
+
+- No raw IDs in clear URLs when not needed.
+- Use short opaque or signed context IDs.
+- Expire context tokens and bind to Telegram user + wallet/session.
+- Every context hit verifies canonical ownership/state before rendering any action.
+
+### Example startapp routes (illustrative)
+
+- `.../startapp=request&rid=<opaque>`
+- `.../startapp=offer&oid=<opaque>`
+- `.../startapp=payment&pid=<opaque>`
+- `.../startapp=dispute&did=<opaque>`
+- `.../startapp=verify`
+
+## 5) Release phasing
+
+| Phase | Telegram surface | Backend dependency |
+|---|---|---|
+| Phase 0 (MVP) | bot + limited Mini App for state-safe buyer/seller actions; no Telegram-only financial mutations | Payment and ledger gates already enforced |
+| Phase 1 | richer navigation, richer filters, deeper support surfaces | Identity linking + event fanout |
+| Phase 2 | admin operator actions in Telegram | Additional ops hardening and audit scope |
+
+## 6) Acceptance traceability
+
+Directly mapped to PRD section "Task 1":
+
+- Buyer/seller/admin/support journeys and entry contexts documented: **yes**
+- Deep links and entry points defined with phase split: **yes**
+- Canonical API/state mapping in table + journey sections: **yes**
+- Non-native and admin surfaces identified: **yes**
+- Backward compatibility with existing web flows retained: **yes**
+
+## 7) Open items for implementation
+
+1. Finalize concrete deep-link payload schema (opaque token claim set).
+2. Finalize Mini App navigation IDs and route-to-state matrix in frontend routing.
+3. Confirm unsupported actions for `DISPUTED`/`FAILED` states at Telegram action layer.

09 - Audits/Task 5.2 Telegram Identity Linking and Session Model.md

@@ -0,0 +1,62 @@
+---
+title: Task 5.2 Telegram Identity Linking and Session Model
+tags: [taskmaster, telegram, identity, session]
+created: 2026-05-24
+status: implemented-foundation
+---
+
+# Task 5.2 Telegram Identity Linking and Session Model
+
+This document captures the first backend implementation pass for Task 5.2.
+
+## Implemented foundation
+
+- `TelegramLink` model maps one active Telegram user ID to one Amanat user.
+- `TelegramSession` model stores Mini App session tokens, Telegram user ID,
+  optional Amanat user ID, initData fingerprint, auth date, source, expiry, and
+  active state.
+- `/api/telegram/miniapp/verify` validates Telegram Mini App `initData` without
+  creating an Amanat session.
+- `/api/telegram/miniapp/session` creates a Telegram session after verified
+  `initData`.
+- `/api/telegram/link` lets an authenticated Amanat user link, read, or unlink a
+  Telegram account.
+
+## Security model
+
+- Backend verifies Mini App `initData` with Telegram's server-side signature
+  scheme before trusting Telegram identity.
+- `initDataUnsafe` remains client-only display context and is not trusted for
+  backend authorization.
+- Bot accounts are rejected.
+- Stale `auth_date` values are rejected by configured TTL.
+- Replayed Mini App payloads are rejected inside the configured replay window.
+- Duplicate active Telegram-to-Amanat links are rejected.
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `TELEGRAM_FEATURE_ENABLED` | Master feature flag |
+| `TELEGRAM_MINIAPP_ENABLED` | Mini App session/linking flag |
+| `TELEGRAM_BOT_TOKEN` | Server-side token used to verify Mini App signatures |
+| `TELEGRAM_INITDATA_MAX_AGE_SEC` | Maximum accepted `auth_date` age |
+| `TELEGRAM_INITDATA_REPLAY_WINDOW_MS` | Replay window for duplicate Mini App submissions |
+| `TELEGRAM_SESSION_TTL_SEC` | Telegram session lifetime |
+
+## Tests
+
+- `backend/__tests__/telegram-service.test.ts`
+- `backend/__tests__/telegram-routes.test.ts`
+
+Coverage includes valid/invalid signature, expired initData, replay detection,
+session persistence, link/unlink behavior, duplicate link rejection, route-level
+Mini App validation, and secret non-leakage.
+
+## Remaining work
+
+- Move replay protection from in-memory maps to Redis or another shared store for
+  multi-instance deployments.
+- Bind Telegram session tokens to first-party web session controls once the
+  final session architecture is implemented.
+- Add admin/support controls for revoking or blocking Telegram links.

09 - Audits/Task 5.3 Telegram Bot Command and Notification Foundation.md

@@ -0,0 +1,48 @@
+---
+title: Task 5.3 Telegram Bot Command and Notification Foundation
+tags: [taskmaster, telegram, bot, notifications]
+created: 2026-05-24
+status: partial-foundation
+---
+
+# Task 5.3 Telegram Bot Command and Notification Foundation
+
+This document captures the first backend bot foundation pass.
+
+## Implemented foundation
+
+- `/api/telegram/status` reports feature and webhook readiness without leaking
+  bot or webhook secrets.
+- `/api/telegram/webhook` is mounted only when Telegram features are enabled.
+- Webhook requests require `x-telegram-bot-api-secret-token` to match
+  `TELEGRAM_WEBHOOK_SECRET_TOKEN`.
+- Webhook update handling dedupes by `update_id` or callback ID.
+- Webhook handler classifies updates as:
+  - `command`
+  - `callback`
+  - `noop`
+  - `duplicate`
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `TELEGRAM_WEBHOOK_ENABLED` | Enables webhook route |
+| `TELEGRAM_WEBHOOK_SECRET_TOKEN` | Telegram webhook secret token |
+| `TELEGRAM_WEBHOOK_REPLAY_WINDOW_MS` | Duplicate update replay window |
+
+## Tests
+
+- Service-level tests cover command/callback/noop classification and duplicate
+  handling.
+- Route-level tests cover secret-token rejection and accepted command webhook
+  processing.
+
+## Remaining work
+
+- Implement actual command actions for `/start`, `/help`, `/link`, `/status`,
+  `/request`, `/offer`, `/payment`, `/dispute`, and `/settings`.
+- Add signed opaque callback payload issuance and resolution.
+- Add outbound notification delivery, blocked-bot detection, retry metrics, and
+  notification preferences.
+- Persist webhook dedupe keys in shared storage instead of process memory.

09 - Audits/Task 5.4 Telegram Mini App Shell Implementation.md

@@ -0,0 +1,42 @@
+---
+title: Task 5.4 Telegram Mini App Shell Implementation
+tags: [taskmaster, telegram, mini-app, frontend]
+created: 2026-05-24
+status: partial-foundation
+---
+
+# Task 5.4 Telegram Mini App Shell Implementation
+
+This document captures the first frontend implementation pass for the Telegram
+Mini App surface.
+
+## Implemented foundation
+
+- Added `/telegram` route.
+- Added `src/utils/telegram-webapp.ts` for safe Telegram WebApp context parsing.
+- Added `TelegramMiniAppShell` with three first-pass states:
+  - unsupported browser context,
+  - Telegram detected but unlinked,
+  - Telegram detected and authenticated web user present.
+- Added basic marketplace/escrow action cards for requests, request creation,
+  payment/escrow, chat, and account.
+- Added Telegram chrome attachment helper for MainButton, BackButton, and haptic
+  feedback when available.
+- Added safe-area and Telegram theme helpers.
+
+## Tests
+
+- `frontend/__tests__/utils-test/telegram-webapp.test.ts`
+- `frontend/__tests__/sections/telegram/telegram-mini-app-shell.test.tsx`
+
+Coverage includes standard browser fallback, Telegram context parsing,
+safe-area/theme fallback, start parameter parsing, unsupported state, unlinked
+state, and linked state rendering.
+
+## Remaining work
+
+- Wire Mini App shell to backend Telegram session endpoints.
+- Add request/offer/payment/dispute data loading inside the Mini App route.
+- Add upload and dispute action surfaces that call canonical backend APIs.
+- Add Telegram BackButton routing behavior once final navigation stack is known.
+- Add client matrix QA across iOS, Android, Desktop, and Web Telegram clients.

09 - Audits/Task 5.5 Telegram Payment and Wallet Strategy.md

@@ -0,0 +1,105 @@
+---
+title: Task 5.5 Telegram Payment and Wallet Strategy
+tags: [taskmaster, telegram, payment, wallet, provider-adapter]
+created: 2026-05-24
+status: draft
+---
+
+# Task 5.5 Telegram Payment and Wallet Strategy
+
+Source: `/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md`
+
+## 1) Strategy principle for this track
+
+For first release, Telegram-native payment initiation must feed the existing canonical payment system and must **not** bypass
+ledger-led state transitions. This means:
+
+- payment proof and funds movement remain authorized by
+  [`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md),
+- release/refund actions remain governed by service-layer guards and dispute holds,
+- Telegram provider adapters are optional extensions, not a hard dependency.
+
+In practice: Telegram can open payment flows through one canonical path first, and optional providers are layered later.
+
+## 2) Option comparison
+
+| Option | Fit for Telegram UX | Funds correctness risk | Regulatory / abuse risk | Complexity | Decision |
+|---|---|---|---|---|---|
+| Bot API Payments / Telegram Stars | Moderate | High (revenue and settlement mapping differs from existing ledger assumptions) | Medium | Medium | Deferred |
+| Wallet Pay | Moderate | Medium-High (token-specific proof path) | High | High | Deferred |
+| TON Pay | Medium | Medium-High (provider proof consistency + chain mapping) | High | High | Deferred |
+| TON Connect + direct wallet pay | Medium | Medium if proven; requires strict recipient+amount+memo checks | High | High | Deferred |
+| Request Network links | High (already introduced) | Low-Medium (existing adapter/service contract) | Medium | Low | **Primary for phase 1** |
+| Existing Web3/crypto checkout path | High | Medium (requires recipient/amount/network proof hardening) | High | Medium | Keep as fallback only |
+
+## 3) Selected phase-1 path
+
+### Primary phase-1 strategy
+
+- Telegram bot/Mini App starts the payment by invoking the same canonical payment intent creation API used for web flows.
+- Payment provider is written as metadata; provider-neutral adapter remains optional and feature-flagged.
+- Telegram identity metadata is persisted with the intent:
+  - `provider` (e.g., `request_network` or `shkeeper`)
+  - `telegramUserId`
+  - `telegramChatId` (if available)
+  - `launchSource` (`bot`, `mini_app`, `web_fallback`)
+  - `paymentReference`
+  - `invoiceId` / `orderId` / `requestId`
+  - `currency`, `amount`, `expiresAt`
+  - idempotency key (request-scoped)
+
+### Optional providers
+
+- Wallet Pay / TON Pay / TON Connect paths are documented as optional and must be implemented behind explicit
+  feature flags and dedicated adapter configuration only when:
+  - replay-safe proofs are standardized,
+  - canonical refund/release reconciliation supports provider-native evidence,
+  - monitoring/reporting has parity with existing paths.
+- Until that date, these options are not required to merge for Task 5.1-5.9 handoff.
+
+## 4) Data integrity requirements for any Telegram payment/Wallet path
+
+Before any pay-in is accepted into escrow, enforce:
+
+1. recipient validation (exact canonical recipient for the active escrow policy),
+2. asset validation (supported chain + token),
+3. amount validation against payment intent and currency precision,
+4. memo/reference validation (idempotent and tamper-evident),
+5. confirmation proof validation (`confirmed`, `on-chain`, or provider webhook),
+6. canonical reconciliation step before mark-complete,
+7. invariant re-check with ledger balances before release/refund operations.
+
+These map directly to:
+
+- [`Webhook Security Spec`](Webhook%20Security%20Spec.md)
+- [`Payment Provider Adapter Spec`](Payment%20Provider%20Adapter%20Spec.md) (if optional provider is enabled)
+- [`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md) (all financial state transitions).
+
+## 5) Anti-divergence record model
+
+Every Telegram payment intent should write a small canonical trace record with:
+
+- canonical `paymentId`
+- `canonicalSourceChannel = telegram`
+- `telegramContext` payload hash
+- `provider` and `providerReference`
+- `idempotencyKey`
+- `createdFrom` deep-link/command/callback identifier
+- reconciliation status (`created`, `started`, `confirmed`, `failed`, `reconciled`)
+
+This avoids duplicate checkout creation and makes Telegram callback replay and callback mismatch explainable in operations.
+
+## 6) Refund/release compatibility
+
+Refund/release logic remains unchanged from the canonical engine:
+
+- cannot release funds not in releasable state,
+- no release/release-amount mutation from Telegram without canonical precondition checks,
+- disputed states block direct payout operations,
+- release/refund events are only reflected after ledger updates succeed.
+
+## 7) Open follow-up decisions
+
+1. Decide whether to onboard `Wallet Pay` as phase-2 provider once adapter-level proof validation and reconciliation parity are met.
+2. Decide whether to expose optional "wallet direct top-up" button in Mini App from day one or keep explicit link-first flow.
+3. Finalize provider timeout and retry policy for Telegram-triggered intents under slow-network conditions.

09 - Audits/Task 5.6 Telegram Escrow Delivery Dispute Release Actions.md

@@ -0,0 +1,38 @@
+---
+title: Task 5.6 Telegram Escrow Delivery Dispute Release Actions
+tags: [taskmaster, telegram, escrow, disputes, release]
+created: 2026-05-24
+status: planned
+---
+
+# Task 5.6 Telegram Escrow Delivery Dispute Release Actions
+
+Task 5.6 is not complete in this first Task 5 pass. This document defines the
+implementation boundary required before Telegram shortcuts can affect escrow
+state.
+
+## Required behavior
+
+- Telegram users can view current escrow state and next allowed actions.
+- Delivery confirmation, evidence upload, refund request, dispute open/respond,
+  and release approval route through existing backend precondition checks.
+- High-risk actions require fresh confirmation and audit logging with Telegram
+  context.
+- Disputed or held funds cannot be released through Telegram shortcuts.
+
+## Required backend constraints
+
+- Use canonical purchase request, payment, dispute, and ledger state.
+- Reject release/refund actions unless the funds state machine says the action is
+  allowed.
+- Apply the same step-up and two-person policy as web/admin flows.
+- Record Telegram user ID, chat/update ID, deep-link source, and callback token
+  ID in audit metadata.
+
+## Required tests
+
+- Buyer cannot confirm delivery before delivery state.
+- Disputed funds cannot be released.
+- Replayed Telegram callback cannot create a second action.
+- Stale callback token is rejected.
+- Telegram release/refund action emits the same audit fields as web release.

09 - Audits/Task 5.7 Telegram Admin Support Surface.md

@@ -0,0 +1,40 @@
+---
+title: Task 5.7 Telegram Admin Support Surface
+tags: [taskmaster, telegram, admin, support]
+created: 2026-05-24
+status: planned
+---
+
+# Task 5.7 Telegram Admin Support Surface
+
+Task 5.7 is not complete in this first Task 5 pass. This document defines the
+admin/support scope required for Telegram-originated cases.
+
+## Required admin/support visibility
+
+- Telegram linked identity on user profile.
+- Bot notification status and blocked-bot state.
+- Mini App launch source and latest Telegram session metadata.
+- Payment provider and wallet/payment references for Telegram-originated intents.
+- Telegram webhook/callback event history for support investigation.
+
+## Required admin/support actions
+
+- Resend link prompt.
+- Revoke Telegram link.
+- Block Telegram bot access for a user.
+- Inspect Telegram-originated event history.
+- Escalate payment/dispute issues to canonical admin workflows.
+
+## Security requirements
+
+- Admin overrides remain gated by Task 4 step-up/two-person controls.
+- Support can inspect Telegram context but cannot mutate funds state.
+- Every support/admin action writes structured audit metadata.
+
+## Required tests
+
+- Support can read Telegram link metadata but cannot release/refund funds.
+- Admin link revocation invalidates active Telegram link.
+- Blocked Telegram user cannot create a new Mini App session.
+- Admin override paths still require step-up when configured.

09 - Audits/Task 5.8 Telegram Security, Compliance, and Abuse Controls.md

@@ -0,0 +1,138 @@
+---
+title: Task 5.8 Telegram Security, Compliance, and Abuse Controls
+tags: [taskmaster, telegram, security, compliance, abuse]
+created: 2026-05-24
+status: draft
+---
+
+# Task 5.8 Telegram Security, Compliance, and Abuse Controls
+
+Source: `/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md`
+
+## 1) Threat model alignment
+
+Threats are prioritized by impact to funds and identity:
+
+- forged `initData`
+- callback/replay abuse
+- deep-link tampering
+- phishing / link substitution
+- bot token leakage
+- spam / command flood
+- account takeover
+- wallet spoofing
+- fake payment proof
+- support impersonation
+
+These correspond to existing concerns in
+[`Threat Model - Amanat Escrow Platform`](Threat%20Model%20-%20Amanat%20Escrow%20Platform.md), especially **T16** (Telegram deep-link tampering).
+
+## 2) Channel-specific controls
+
+### 2.1 Telegram Web App identity
+
+- Validate every Mini App session using Telegram `initData` with server-side signature verification.
+- Never trust raw Telegram identifiers from client payload.
+- Reject `initData` outside active bot context.
+- Enforce short TTL and replay window for session and deep-link context tokens.
+
+### 2.2 Bot callback and command surface
+
+- Signed opaque callback payloads only; no mutable business state in query strings.
+- Update callback handling is idempotent with dedupe key `(callbackId, telegramUpdateId, telegramUserId)`.
+- Unknown callback payloads are rejected with audit logging and zero state mutation.
+- Hard rate limits on `/api/telegram/webhook` per IP and per Telegram user.
+
+### 2.3 Deep-link and redirect controls
+
+- Signed link payloads with short expiry and bound context.
+- Reject tampered/deprecated deep links by schema/nonce/version checks.
+- No direct redirect to non-whitelisted hosts.
+- Re-validate request ownership after deep-link state resolution.
+
+### 2.4 Wallet and payment evidence controls
+
+- Recipient, token, amount, and network checks must run before trust decisions.
+- Payment proof replay rejected when payload hash differs from signed first-seen proof.
+- Require provider-normalized reconciliation confirmation before marking funds complete.
+
+### 2.5 Bot token and secrets
+
+Secrets must never be in client-side code and must not be logged:
+
+- `TELEGRAM_BOT_TOKEN`
+- `TELEGRAM_WEBHOOK_SECRET`
+- `TELEGRAM_WALLET_PAY_TOKEN` (if Wallet Pay enabled)
+- `TON_CONNECT_MANIFEST_URL` / TON secret artifacts
+- provider API secrets and webhook keys for request-network/SHKeeper paths
+
+Apply Task 4 secret principles:
+
+- separate sandbox and production tokens/environments,
+- short rotation cadence,
+- strict allowlist for secret-bearing hosts.
+
+## 3) Compliance and secure configuration
+
+### 3.1 CORS / CSP / framing
+
+- Restrict Telegram endpoints to required app origins only.
+- CSP in Telegram surfaces should avoid wildcard connect/script allowances.
+- Add explicit `frame-ancestors` constraints for web entry surfaces that can be embedded.
+
+### 3.2 Access and authorization
+
+- Apply existing ownership rules from
+  [`Authorization Matrix - REST and Socket.IO`](Authorization%20Matrix%20-%20REST%20and%20Socket.IO.md).
+- Telegram-originated actions use the same actor checks as web actions, including admin step-up and two-person control for high-value override actions.
+- Dispute hold checks remain blocking for release/refund.
+
+## 4) Abuse controls
+
+1. **Spam / abuse**
+   - per-user command/chat throttle,
+   - per-IP flood detection on webhook.
+2. **Account takeover**
+   - suspicious Telegram session behavior triggers notification disable and forced re-link.
+3. **Wallet spoofing**
+   - signed wallet ownership checks + reconciliation proof checks.
+4. **Fake proof**
+   - malformed proofs logged; never auto-complete payment with unverifiable proof.
+5. **Support impersonation**
+   - support tools require signed admin context, with explicit role and actor logs.
+
+## 5) Monitoring and alerting
+
+Signals (and baseline targets):
+
+- `telegram_update_failures_total` (high if sustained >0.5%)
+- `telegram_initdata_invalid_total`
+- `telegram_callback_replay_total`
+- `telegram_payment_proof_mismatch_total`
+- `telegram_notification_blocked_total`
+- `telegram_payment_abnormal_status_jump_total`
+
+Alert rules (initial):
+
+- warning after 10 minutes, critical after 30 minutes or sustained spike above baseline.
+- any sudden increase in payment mismatch ratio requires incident triage.
+
+Where to emit:
+
+- Sentry for exception/error trending,
+- backend logs for structured events,
+- existing dashboard metrics hooks and runbook scripts where available.
+
+## 6) Operational controls required before launch
+
+- Secrets rotation checklist completed (bot token and payment/provider keys).
+- CORS/CSP reviewed and restricted to Telegram and known frontend origin.
+- webhook secrets configured separately for sandbox and production.
+- callback replay suppression validated in QA scenarios.
+- support impersonation checks and audit trails validated.
+
+## 7) Outstanding controls not yet implemented in this task layer
+
+- Two-way admin alerting channel for Telegram-specific abuse currently depends on operations integration.
+- Formal cryptographic replay store for deep-link one-time tokens (recommended before general rollout).
+- Telegram payment-specific policy page and end-user risk consent copy.

09 - Audits/Task 5.9 QA Rollout Analytics and Launch Runbooks.md

@@ -0,0 +1,156 @@
+---
+title: Task 5.9 QA, Rollout, Analytics, and Launch Runbooks
+tags: [taskmaster, telegram, qa, rollout, analytics, runbook]
+created: 2026-05-24
+status: draft
+---
+
+# Task 5.9 QA, Rollout, Analytics, and Launch Runbooks
+
+Source: `/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md`
+
+## 1) QA scope for launch readiness
+
+### 1.1 Client matrix (required)
+
+- Telegram iOS
+- Telegram Android
+- Telegram Desktop
+- Telegram Web
+- Light / dark themes
+- Compact / fullscreen modes
+- Normal and slow network
+- Blocked bot scenario
+- Expired / stale session scenario
+- Payment cancellation and abort
+- Unlinked user and re-link path
+
+### 1.2 Functional QA checklist
+
+1. Identity and linking
+2. Request listing/detail in both bot and Mini App
+3. Offer review flow
+4. Payment initiation and cancel path
+5. Delivery evidence upload
+6. Dispute open/respond and status progression
+7. Notification quiet/error state
+8. Error and blocked-bot behavior
+9. Support escalation handoff
+
+### 1.3 Security/abuse QA
+
+- forged/invalid `initData` rejection
+- callback replay replayed twice: one success one no-op
+- deep-link tampering
+- wallet proof mismatch
+- callback processing under invalid provider secrets
+- admin override behavior and audit event capture
+
+## 2) Environments and rollout
+
+### 2.1 Environment separation
+
+- `telegram-dev-bot` and `telegram-prod-bot` tokens and webhook endpoints must be distinct.
+- No shared webhook secret between environments.
+- QA and production payment fixtures remain isolated.
+
+### 2.2 Feature flag sequence
+
+1. **Development flag off**: no surface exposed
+2. **Internal allowlist**: selected users only (buyer/seller/admin)
+3. **Beta cohort**: controlled percentage and fixed org list
+4. **Production enablement**: after runbook and KPI thresholds pass
+
+### 2.3 Deployment safety
+
+- If new surface increases payment mismatch or callback failure, immediately pause `TELEGRAM_SURFACE_ENABLED` and keep providers in read-only mode.
+- Use existing rollback flow from incident operations and deployment runbooks.
+
+## 3) Analytics and launch KPIs
+
+Track these metrics daily for 14 days after stage advancement:
+
+- activation rate (`activatedTelegramUsers / startedTelegramUsers`)
+- link completion rate (`linkedUsers / startedLink`)
+- request creation from Telegram (`telegramRequestsCreated`)
+- offer response completion (`offerResponses / offersOpened`)
+- payment started / payment completed (`telegramPaymentStart`, `telegramPaymentComplete`, `telegramPaymentFail`)
+- dispute activity (`disputesOpened`, `disputesResolvedInTelegram`)
+- release approvals from Telegram context (`telegramReleaseApprovals`)
+- notification opt-outs (`notificationsOptOutRate`)
+- callback duplicate ratio (`callbackReplay / callbackTotal`)
+- average context resume latency (min and p95)
+
+### Reporting destinations
+
+- Sentry for exception and failure spikes
+- application logs for workflow events
+- existing monitoring dashboards for rate/latency anomalies
+
+## 4) Launch runbooks
+
+All runbooks are mandatory for Stage-1 rollout and post-launch incidents.
+
+### 4.1 Bot outage
+
+1. Validate webhook endpoint response health.
+2. Switch status to notification-only mode where possible.
+3. Confirm bot token and webhook URL.
+4. Re-route urgent flows to web fallback.
+5. Restore Telegram webhook + replay backlog after recovery.
+
+### 4.2 Telegram API outage
+
+1. Confirm external Telegram API status.
+2. Temporarily disable deep-link / in-app actions that require Telegram callbacks.
+3. Notify users of delayed updates.
+4. Keep pending payment states in read-only mode until callback channel is restored.
+
+### 4.3 Payment provider outage
+
+1. Identify affected provider via provider mode and provider health flags.
+2. Switch to read-only or alternative provider mode where configured.
+3. Run reconciliation before re-enabling full writes.
+4. Track stale pending payment age and contact support workflow.
+
+### 4.4 Stuck payment
+
+1. Check payment reconciliation queue and provider status.
+2. Verify callback proof and on-chain confirmation.
+3. Manually reconcile if allowed by protocol and policy.
+4. Escalate if stale > 24h in funded or processing state.
+
+### 4.5 Duplicate callback
+
+1. Validate idempotency path executed correctly.
+2. Confirm callback dedupe key retention window.
+3. Compare event fingerprint for payload divergence.
+4. Mark one path as duplicate no-op and keep audit trail.
+
+### 4.6 Suspicious wallet proof
+
+1. Block automated release/refund for the request.
+2. Flag payment and mark for manual ops review.
+3. Verify recipient, amount, and tx hash against chain/provider data.
+4. Resume only after explicit approval.
+
+### 4.7 Compromised bot token
+
+1. Rotate bot token immediately.
+2. Disable bot endpoints and clear webhook secret for 1 hour.
+3. Validate callback signatures with new secret.
+4. Resume in staged rollout mode with monitoring for 24h.
+
+## 5) Stage exit criteria
+
+- All required QA scenarios pass on iOS/Android/desktop/web.
+- No critical webhook/payload mismatch regressions in 24h observation window.
+- No unresolved payment stuck items > 24h after manual triage.
+- Incident owners can execute all seven runbooks.
+- Rollout metrics show non-degrading trend for the first two days.
+
+## 6) Known rollout gaps
+
+1. Fine-grained feature toggles for Telegram in existing observability dashboards are pending.
+2. Admin analytics for Telegram-originated releases are schema-dependent and need implementation wiring.
+3. Deep-link recovery behavior after prolonged Telegram link expiry still needs UX polishing.