diff --git a/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md b/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md new file mode 100644 index 0000000..733f518 --- /dev/null +++ b/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md @@ -0,0 +1,163 @@ +# PRD: Telegram-Native App, Bot, and Wallet Experience + +## Scope + +Create a separate delivery track for making Amanat usable from inside Telegram through a bot plus Telegram Mini App. The goal is not only notifications, but a native-feeling Telegram surface that can cover buyer, seller, escrow, chat, dispute, payment, release/refund, and support workflows. + +This track should remain separate from the current security remediation and Request Network migration backlog, but it depends on those foundations for any money movement or high-risk actions. + +## Platform assumptions checked May 24, 2026 + +- Telegram Mini Apps provide a full JavaScript web interface inside Telegram and can be launched from bot profile, menu button, inline buttons, direct links, inline mode, and selected attachment-menu contexts. +- Mini Apps must validate `Telegram.WebApp.initData` on the backend before trusting Telegram user identity. `initDataUnsafe` is not trusted. +- Bot API payments support invoices, invoice links, pre-checkout handling, successful payment events, Telegram Stars, and refund/subscription management for Stars. +- TON Connect is the standard wallet connection protocol for TON dApps and Telegram Mini Apps. It lets apps request wallet connection, signatures, and transactions without controlling user keys. +- TON Pay SDK and Wallet Pay are possible payment paths for TON/jetton/Telegram-wallet-style crypto payments, but they must be evaluated against escrow ledger, webhook, jurisdiction, KYC, fee, refund, and reconciliation requirements before production use. + +Reference docs: + +- Telegram Mini Apps: https://core.telegram.org/bots/webapps +- Telegram Bot API payments: https://core.telegram.org/bots/api#payments +- TON Connect: https://docs.ton.org/applications/ton-connect/overview +- TON Pay SDK: https://docs.ton.org/applications/ton-pay/overview +- Wallet Pay API: https://docs.wallet.tg/pay/ + +## Product goal + +Users should be able to complete the practical Amanat journey without leaving Telegram: + +- Register or link an Amanat account from Telegram. +- Browse and create purchase requests. +- Receive seller offers and buyer decisions. +- Chat around a request with structured context. +- Start escrow payment from Telegram. +- See payment, delivery, dispute, and release state. +- Submit evidence for delivery or dispute. +- Confirm delivery, request refund, or approve release when eligible. +- Receive actionable notifications and reminders. +- Use wallet/payments options that are safe for escrow accounting. + +## Non-goals + +- Do not bypass the canonical backend authorization, funds ledger, or escrow state machine. +- Do not treat Telegram chat messages as the source of truth for financial state. +- Do not release funds based only on bot callback data or client-side Mini App state. +- Do not store Telegram bot tokens, Wallet Pay keys, or TON private keys in frontend code. +- Do not make Telegram the only supported channel unless a later product decision explicitly says so. + +## Architecture principles + +- The Mini App is a client surface. The backend remains the authority for identity, authorization, payment state, escrow state, disputes, and audit logs. +- Telegram identity maps to an Amanat user through a verified link table keyed by Telegram user ID and Amanat user ID. +- Every Telegram-originated command, callback, webhook, and Mini App request is authenticated and rate-limited. +- Telegram callbacks must be idempotent and replay-safe. +- Payment events flow into the same provider-neutral payment adapter, ledger, and reconciliation pipeline as web checkout. +- High-risk actions such as release, refund, payout address change, dispute resolution, and admin override require step-up confirmation or explicit backend policy. + +## Task set + +### Task 1: Define Telegram product surface and flow map + +Document which Amanat workflows live in bot messages, which live in the Mini App, and which remain web/admin-only for the first release. + +Acceptance criteria: + +- Buyer, seller, admin/support, unauthenticated, linked-user, and unlinked-user journeys are mapped. +- Deep-link entry points are specified for request details, offer review, payment, dispute, delivery evidence, and account linking. +- First-release scope separates must-have flows from later enhancements. +- Every Telegram action maps to an existing or planned backend API/state transition. + +### Task 2: Build Telegram identity linking and session model + +Implement secure account linking between Telegram users and Amanat accounts. + +Acceptance criteria: + +- Backend verifies Mini App `initData` before creating a Telegram session. +- Telegram user IDs are linked to Amanat users through an auditable association table. +- Account linking supports existing users, new users, unlinking, blocked accounts, and duplicate Telegram-account attempts. +- Session expiry, replay protection, rate limits, and audit logging are defined. + +### Task 3: Implement bot command and notification foundation + +Create the Telegram bot backend for commands, inline keyboards, callback queries, deep links, and outbound notifications. + +Acceptance criteria: + +- Bot supports start/help/link/status/request/offer/payment/dispute/settings basics. +- Callback payloads use short opaque IDs or signed tokens, not raw financial state. +- All incoming updates are idempotently processed and rate-limited. +- Notification preferences and quiet/error states are respected. +- Failed delivery, blocked bot, and retry behavior are observable. + +### Task 4: Build Telegram Mini App shell for core marketplace workflows + +Deliver the mobile-first Mini App that gives users the full Amanat workflow surface inside Telegram. + +Acceptance criteria: + +- Mini App uses Telegram theme, safe-area, viewport, back button, haptics, and main/bottom button patterns. +- Users can browse requests, create/edit requests, review offers, view escrow/payment state, upload evidence, and manage dispute/delivery actions. +- The Mini App can be launched from bot profile, menu button, inline buttons, and direct links with `startapp` context. +- UX handles unlinked accounts, expired sessions, unsupported Telegram clients, and fallback web links. + +### Task 5: Add Telegram payment and wallet strategy + +Evaluate and implement safe payment entry points for Telegram-native users without weakening escrow accounting. + +Acceptance criteria: + +- Compare Bot API payments/Stars, Wallet Pay, TON Pay, TON Connect, Request Network links, and existing crypto checkout for supported use cases. +- Select a first payment path and document rejected options. +- Payment creation stores provider, Telegram user ID, deep-link source, payment reference, invoice/order/request ID, currency, amount, expiration, and idempotency key. +- Wallet/TON flows validate recipient, asset, amount, memo/reference, confirmation status, and reconciliation evidence before crediting escrow. +- Refund/release behavior is explicitly compatible with the canonical ledger and dispute holds. + +### Task 6: Expose escrow, delivery, dispute, and release actions safely + +Make Telegram actions useful for real escrow work while preserving backend state authority. + +Acceptance criteria: + +- Telegram users can see current escrow state, next allowed actions, and blockers. +- Delivery confirmation, evidence upload, refund request, dispute open/respond, and release approval route through backend precondition checks. +- High-risk actions require fresh confirmation and are audit logged with Telegram context. +- Disputed or held funds cannot be released through Telegram shortcuts. + +### Task 7: Add admin/support operating surface for Telegram-originated cases + +Give support/admin users enough visibility to handle Telegram-originated users and payments. + +Acceptance criteria: + +- Admin UI/API shows Telegram linked identity, bot notification status, launch source, payment provider, and wallet/payment references. +- Support can resend links, revoke Telegram link, block bot access, and inspect Telegram-originated events. +- Admin overrides require the same step-up/two-person policy as web flows if configured. + +### Task 8: Security, compliance, and abuse controls for Telegram + +Threat-model the Telegram surface and add controls before launch. + +Acceptance criteria: + +- Threat model covers forged init data, callback replay, deep-link parameter tampering, phishing links, bot token leakage, spam, account takeover, wallet spoofing, fake payment proof, and support impersonation. +- Secrets, bot webhook endpoints, Wallet Pay keys, TON Connect manifest, CORS, CSP, allowed origins, and rate limits are documented. +- Monitoring covers update processing failures, abnormal callbacks, payment mismatches, blocked notifications, and suspicious wallet activity. + +### Task 9: QA, rollout, analytics, and launch operations + +Prepare the Telegram app/bot for controlled release. + +Acceptance criteria: + +- Test matrix covers Telegram iOS, Android, Desktop, Web, light/dark themes, compact/fullscreen modes, slow network, blocked bot, expired sessions, and payment cancellation. +- Sandbox/test bot and production bot environments are separated. +- Rollout uses feature flags, internal allowlist, beta cohort, and production enablement. +- Analytics measure activation, linked accounts, request creation, offer response, payment start/completion, dispute activity, release approval, and notification opt-outs. +- Runbooks exist for bot outage, Telegram API outage, payment provider outage, stuck payment, duplicate callback, suspicious wallet proof, and compromised bot token. + +## Dependency guidance + +- Tasks involving release/refund/payment crediting should depend on the platform hardening and ledger/payment-provider work. +- Identity, bot navigation, Mini App shell, and notification preferences can start earlier behind feature flags. +- Wallet/TON payment work must not precede the provider-neutral adapter, ledger invariants, and webhook/idempotency contracts. diff --git a/taskmaster-share/index.html b/taskmaster-share/index.html index 922bbc0..10ff91e 100644 --- a/taskmaster-share/index.html +++ b/taskmaster-share/index.html @@ -6,170 +6,385 @@ Amanat Taskmaster Queue
+

Amanat docs ยท Taskmaster

-

Developer task queue

-

A shareable static view of the docs-side Taskmaster queue generated from the PRDs and latest backend security/refactor audit. Use this page for planning; use Taskmaster CLI for status updates.

+

Roadmap

+

A public planning view generated from the docs-side Taskmaster queue. Track security remediation, payment architecture, refactor decisions, and completed documentation work from one place.