From 825add64873ea3b4ac6aa34ca362fcbc794db33f Mon Sep 17 00:00:00 2001 From: Siavash Sameni Date: Sun, 24 May 2026 08:57:38 +0400 Subject: [PATCH] docs: add taskmaster prd task queue --- .taskmaster/README.md | 27 ++ .taskmaster/config.json | 40 +++ ...mermaid-diagram-rendering-stabilization.md | 118 +++++++ ...tform-audit-remediation-plan-2026-05-24.md | 232 ++++++++++++ ...-network-migration-and-funds-management.md | 333 ++++++++++++++++++ .taskmaster/state.json | 5 + .taskmaster/tasks/task-1.md | 9 + .taskmaster/tasks/task-2.md | 17 + .taskmaster/tasks/task-3.md | 18 + .taskmaster/tasks/tasks.json | 70 ++++ README.md | 1 + 11 files changed, 870 insertions(+) create mode 100644 .taskmaster/README.md create mode 100644 .taskmaster/config.json create mode 100644 .taskmaster/docs/prd-mermaid-diagram-rendering-stabilization.md create mode 100644 .taskmaster/docs/prd-platform-audit-remediation-plan-2026-05-24.md create mode 100644 .taskmaster/docs/prd-request-network-migration-and-funds-management.md create mode 100644 .taskmaster/state.json create mode 100644 .taskmaster/tasks/task-1.md create mode 100644 .taskmaster/tasks/task-2.md create mode 100644 .taskmaster/tasks/task-3.md create mode 100644 .taskmaster/tasks/tasks.json diff --git a/.taskmaster/README.md b/.taskmaster/README.md new file mode 100644 index 0000000..7919efc --- /dev/null +++ b/.taskmaster/README.md @@ -0,0 +1,27 @@ +# Taskmaster workspace for Amanat PRDs + +This docs-side Taskmaster setup tracks the product/security PRDs from the documentation vault. + +## Source PRDs + +- `prd-mermaid-diagram-rendering-stabilization.md` +- `prd-platform-audit-remediation-plan-2026-05-24.md` +- `prd-request-network-migration-and-funds-management.md` + +## Usage + +From `nick-doc`, developers can use Taskmaster-compatible tooling against `.taskmaster/tasks/tasks.json`. + +Common commands, once `task-master-ai` is installed/configured: + +```bash +task-master list +task-master show 2 +task-master show 3.4 +task-master next +task-master set-status --id=2.1 --status=in-progress +``` + +The Mermaid PRD is already marked `done` because its source PRD records the full parser sweep as passing. The security and migration PRDs are pending implementation. + +No API keys are committed here. Configure API keys locally or in MCP/editor config if AI-assisted Taskmaster commands are needed. diff --git a/.taskmaster/config.json b/.taskmaster/config.json new file mode 100644 index 0000000..ab2778f --- /dev/null +++ b/.taskmaster/config.json @@ -0,0 +1,40 @@ +{ + "models": { + "main": { + "provider": "anthropic", + "modelId": "claude-sonnet-4-20250514", + "maxTokens": 64000, + "temperature": 0.2 + }, + "research": { + "provider": "perplexity", + "modelId": "sonar", + "maxTokens": 8700, + "temperature": 0.1 + }, + "fallback": { + "provider": "anthropic", + "modelId": "claude-3-7-sonnet-20250219", + "maxTokens": 120000, + "temperature": 0.2 + } + }, + "global": { + "logLevel": "info", + "debug": false, + "defaultNumTasks": 10, + "defaultSubtasks": 5, + "defaultPriority": "medium", + "projectName": "Amanat Documentation PRDs", + "defaultTag": "master", + "ollamaBaseURL": "http://localhost:11434/api", + "bedrockBaseURL": "https://bedrock.us-east-1.amazonaws.com", + "responseLanguage": "English", + "enableCodebaseAnalysis": true, + "enableProxy": false, + "anonymousTelemetry": false + }, + "storage": { + "type": "local" + } +} diff --git a/.taskmaster/docs/prd-mermaid-diagram-rendering-stabilization.md b/.taskmaster/docs/prd-mermaid-diagram-rendering-stabilization.md new file mode 100644 index 0000000..49a9838 --- /dev/null +++ b/.taskmaster/docs/prd-mermaid-diagram-rendering-stabilization.md @@ -0,0 +1,118 @@ +# PRD: Mermaid Diagram Rendering Stabilization + +## Summary +- Scope: Documentation Mermaid diagrams in this vault. +- Discovery date: 2026-05-24. +- Total Mermaid blocks checked: `57`. +- Total failing blocks: `11`. +- Tooling used: `@mermaid-js/mermaid-cli` parse validation for each extracted block. + +## Goal +Create a pass-ready task queue of Mermaid syntax/render issues so each diagram can be corrected one-by-one without guessing. + +## Acceptance Criteria +- Every Mermaid block parses successfully with the same mmdc-based syntax validation. +- Diagrams render in Obsidian/markdown previews without parser errors. +- Each corrected block retains the same intent and participant names where possible. + +## Task 1 - Security Architecture: Email + password sequence +- **File:** `01 - Architecture/Security Architecture.md` +- **Diagram range:** `38-57` (Authentication layers / 2.1) +- **Error:** Parse error line 12: `...nAttempts; lock at N BE-->>FE: 4` +- **Likely issue:** Sequence parser is choking around a message containing inline punctuation and line continuation (`;` and `...`), likely interpreted as malformed sequence text. +- **Fix:** Keep the message text parser-safe (single simple `:` message per line; avoid special separators like unescaped semicolons) and rerun parser. + +## Task 2 - Authentication Flow: Login sequence +- **File:** `04 - Flows/Authentication Flow.md` +- **Diagram range:** `57-90` (`## Sequence diagram`) +- **Error:** Parse error line 48: `...Tokens.push(refresh) BE->>BE: ge` +- **Likely issue:** Line includes inline method-like token with parentheses-like/space patterns and tokenization ambiguity. +- **Fix:** Replace the problematic statement with plain text in message, e.g. `BE->>DB: User.refreshTokens.push(refreshToken)` as one line. + +## Task 3 - Authentication Flow: Refresh token flow +- **File:** `04 - Flows/Authentication Flow.md` +- **Diagram range:** `127-143` (`## Refresh flow`) +- **Error:** Parse error line 11: `... is in user.refreshTokens BE->>BE: Genera` +- **Likely issue:** Special math-style characters and expression-like message text interrupting parser tokenization. +- **Fix:** Replace special symbols in message text with plain ASCII and split to simple message line(s). + +## Task 4 - Chat Flow: typing/chat notification sequence +- **File:** `04 - Flows/Chat Flow.md` +- **Diagram range:** `91-125` (`## Sequence diagram`) +- **Error:** Parse error line 20: `...ata.lastActivity=now BE->>IO: emit c` +- **Likely issue:** Assignment-style text (`...=now`) in message and possible bare punctuation in one-line payload. +- **Fix:** Simplify message bodies around state updates to readable text only. + +## Task 5 - Delivery Confirmation Flow: code verification sequence +- **File:** `04 - Flows/Delivery Confirmation Flow.md` +- **Diagram range:** `45-71` (`## Sequence diagram`) +- **Error:** Parse error line 22: `...; status="delivered" BE->>IO: emit r` +- **Likely issue:** Double status expression in message (`deliveryCodeUsed=true; status="delivered"`). +- **Fix:** Split into two explicit sequence lines or rephrase with punctuation-safe text. + +## Task 6 - Dispute Flow: admin resolve sequence +- **File:** `04 - Flows/Dispute Flow.md` +- **Diagram range:** `90-134` (`## Sequence diagram`) +- **Error:** Parse error line 18: `... is dispute } FE-->>B,S: chat opens (real` +- **Likely issue:** Invalid multi-recipient send syntax `B,S` on one arrow line. +- **Fix:** Either split into two lines (`FE-->>B:` and `FE-->>S:`) or route via a shared frontend/chat intermediary. + +## Task 7 - Google OAuth Flow: completion sequence +- **File:** `04 - Flows/Google OAuth Flow.md` +- **Diagram range:** `56-96` (`## Sequence diagram`) +- **Error:** Parse error line 34: `...fill avatar if blank end BE->>BE` +- **Likely issue:** `end`/branch block combined with following arrow in parser context likely due missing separation in message-heavy block. +- **Fix:** Ensure `opt ... end` block boundaries and arrows are on clean, standalone lines. + +## Task 8 - Purchase Request Flow: publish sequence +- **File:** `04 - Flows/Purchase Request Flow.md` +- **Diagram range:** `94-129` (`## Sequence diagram`) +- **Error:** Parse error line 27: `...ds; compute isPublic BE->>DB: Purcha` +- **Likely issue:** Message text includes expressions (`compute isPublic`) and punctuation (`;`) that are breaking the sequence parser. +- **Fix:** Rephrase backend processing lines into simple text without `;`/embedded expressions. + +## Task 9 - Referral Flow: conversion and payout sequence +- **File:** `04 - Flows/Referral Flow.md` +- **Diagram range:** `70-99` (`## Sequence diagram`) +- **Error:** Parse error line 26: `...Transaction.create; update` +- **Likely issue:** Message text around chained commands (`updateUserLevel`) appears parser-conflicting. +- **Fix:** Break chained method-like messages into one action-per-line statements. + +## Task 10 - Registration Flow: email verification sequence +- **File:** `04 - Flows/Registration Flow.md` +- **Diagram range:** `87-127` (`## Sequence diagram`) +- **Error:** Parse error line 36: `...tokens.push(refresh) BE->>BE: 200` +- **Likely issue:** Message line includes token-manipulation call style in plain text causing parser confusion. +- **Fix:** Reword to plain textual action; keep method calls minimal. + +## Task 11 - Seller Offer Flow: submit offer sequence +- **File:** `04 - Flows/Seller Offer Flow.md` +- **Diagram range:** `97-134` (`## Sequence diagram`) +- **Error:** Parse error line 16: `...ETA, notes; submit FE_S->>BE: POST` +- **Likely issue:** Message with `; submit` and inline comma-separated action text. +- **Fix:** Split into cleaner action lines before POST step. + +## Execution Order +1. Address Task 6 first (obvious syntax violation) to quickly cut down parse noise. +2. Tackle Tasks 2, 3, 5, 8, 9, 10, 11 (message-format cleanup). +3. Validate with a full parser sweep after each batch. +4. Final sweep: re-run mmdc parse validation across all `57` Mermaid blocks and close this PRD once no errors remain. + +## Current Run Status +- Execution date: 2026-05-24 +- Parallel passes launched: 3 +- Result: All targeted task files pass `@mermaid-js/mermaid-cli` parsing. +- Full vault sweep (all markdown Mermaid blocks): **pass**. + +### Task Completion +- Task 1: Complete (Security Architecture sequence lines simplified) +- Task 2: Complete (Authentication login refresh token line split/rephrased) +- Task 3: Complete (Authentication refresh-flow syntax normalized) +- Task 4: Complete (Chat flow update-message line rewritten) +- Task 5: Complete (Delivery confirmation message split into safe lines) +- Task 6: Complete (Dispute flow multi-recipient send split into separate arrows) +- Task 7: Complete (Google OAuth flow statement ordering fixed) +- Task 8: Complete (Purchase Request preference/public logic split into separate action lines) +- Task 9: Complete (Referral flow user-points action split) +- Task 10: Complete (Registration token update line split) +- Task 11: Complete (Seller Offer flow rewritten into parser-safe sequence diagram) diff --git a/.taskmaster/docs/prd-platform-audit-remediation-plan-2026-05-24.md b/.taskmaster/docs/prd-platform-audit-remediation-plan-2026-05-24.md new file mode 100644 index 0000000..1adf12a --- /dev/null +++ b/.taskmaster/docs/prd-platform-audit-remediation-plan-2026-05-24.md @@ -0,0 +1,232 @@ +# PRD: Platform Audit Remediation Plan (2026-05-24) + +## Scope +- Source audit: `09 - Audits/Platform Logical Audit - 2026-05-24.md` +- Target: backend hardening and consistency fixes first, then doc/runtime alignment. +- Assessed date: 2026-05-24 + +## Audit validity check (code-backed vs docs-only) + +- **Code-confirmed valid findings**: + - Unauthenticated financial/auth-sensitive routes are exposed (`/api/payment/*`, `/api/ai/*`, legacy notification routes). + - Passkey flow uses stubbed credential handling and in-memory challenge storage. + - `PaymentCoordinator` does not currently enforce dispute holds. + - Web3 verifier relies primarily on `receipt.status`. + - Socket.IO user-room joins are client-controlled. + - Rate limiting is explicitly disabled in `backend/src/app.ts`. + +- **Partially validated / inconsistent findings**: + - Dispute module appears absent in the checked backend tree (`backend/src` does not contain `services/dispute`/`routes/disputeRoutes`/`controllers/disputeController`), so many dispute-specific audit checks cannot be confirmed against code but indicate a documentation-runtime mismatch. + - The REST/API/flow docs mention endpoints that differ from available implementation in some places; these should be normalized as part of a separate alignment pass. + +--- + +## PRD 1: Secure unauthenticated endpoints and data-owner enforcement (P0) + +### Problem +- `backend/src/services/payment/decentralizedPaymentRoutes.ts` exposes mutation endpoints (`/save`, `/update`, `/verify`, `/verify-all-pending`) without auth. +- `backend/src/services/ai/aiRoutes.ts` has public generation endpoints (`/generate`, `/analyze`, `/translate`, `/assist`) with no auth. +- `backend/src/services/notification/routes.ts` lets clients specify `userId` and mutate/read without ownership checks, and routes are mounted publicly via `app.use("/api", notificationRoutes)` in `backend/src/app.ts`. + +### Acceptance criteria +- Every endpoint in `decentralizedPaymentRoutes.ts`, `aiRoutes.ts`, and legacy `notificationRoutes.ts` requires: + - `authenticateToken` + - owner/admin role check where applicable +- Notification endpoints do not accept arbitrary `userId`; derive `userId` from authenticated principal. +- Payment history and mutation endpoints enforce requestor ownership or admin/authorized role. + +### Risk assessment +- **Threat**: Financial/private data tampering or privacy breach by unauthenticated callers. +- **Likelihood**: High. +- **Impact**: Critical (funding fraud, PII leakage, cost abuse). +- **Mitigation**: Introduce router-level middleware and standardized auth helper. +- **Residual risk**: Medium if any integration jobs call these endpoints (document required with service tokens or service role). + +### Delivery plan +1. Add route-level `authenticateToken` to all routes in files above. +2. Introduce ownership guard utilities for: + - `history/:userId` and payment listing/history filters + - notification queries/updates +3. Restrict AI calls to authenticated users with per-user rate budget. +4. Add audit logs for denied access and suspicious payloads. +5. Update API docs for auth requirements. + +### Owner / dependencies +- Owner: Backend security + payments teams. +- Depends on: token standards in `backend/src/shared/middleware/auth`. + +--- + +## PRD 2: Production-grade Passkey/WebAuthn flow (P0) + +### Problem +- `backend/src/services/auth/passkeyService.ts` stores passkey challenge data in an in-memory `Map` and inserts `'simulated-public-key'` during registration. +- Refresh token is generated on authentication but never persisted to `user.refreshTokens[]`, making token rotation behavior inconsistent with the rest of auth flows. + +### Acceptance criteria +- Replace stubbed registration/verification with real WebAuthn verification. +- Back challenges by shared storage (Redis or equivalent), not in-process memory. +- Persist verified refresh tokens and rotate according to normal auth policy. +- Reject reused/expired challenges and malformed assertions with deterministic errors. + +### Risk assessment +- **Threat**: Credential spoofing, replay attacks, and broken session continuity. +- **Likelihood**: High. +- **Impact**: Critical (account takeover / authentication bypass). +- **Mitigation**: Add `@simplewebauthn/server` (or equivalent) + Redis-backed nonce store + strict verification. +- **Residual risk**: Medium (device/browser compatibility edge-cases). + +### Delivery plan +1. Replace `verifyRegistration` and `verifyAuthentication` with attestation/assertion verification. +2. Swap `storedChallenges` map for distributed storage with TTL. +3. Add persistent refresh token append in passkey login flow. +4. Add regression tests for sign-in/sign-up and challenge expiry. + +### Owner / dependencies +- Owner: Auth team. +- Depends on: Redis infra, passkey frontend challenge handling. + +--- + +## PRD 3: Enforce dispute hold before payout/release operations (P1) + +### Problem +- No dispute implementation files are present in the checked backend for enforcement paths, yet escrow release can still proceed in payment logic without a blocking hold. +- `backend/src/services/marketplace/routes.ts` release endpoint (`/purchase-requests/:id/release-payment`) executes without a dispute gate. +- `backend/src/services/payment/paymentCoordinator.ts` applies sequencing and dedupe logic but has no dispute state guard. + +### Acceptance criteria +- Introduce explicit hold mechanism on `Payment` (or new `disputeStatus`/`holdReason` field). +- All release/refund flows check hold state before state mutation. +- Release endpoint returns clear 409/423 response when disputed. +- Backfill/reporting distinguishes dispute-blocked payments. + +### Risk assessment +- **Threat**: Funds released before dispute resolution. +- **Likelihood**: Medium (documented behavior gap). +- **Impact**: Critical (financial loss / trust erosion). +- **Mitigation**: Centralize payout/refund state checks in coordinator and services, not UI-only logic. +- **Residual risk**: Medium (existing open disputes may need manual reconciliation). + +### Delivery plan +1. Add `disputed`/`disputeHoldReason` fields (and migration plan) to `Payment`. +2. Add hold checks in: + - `backend/src/services/marketplace/routes.ts` admin release flow + - `backend/src/services/payment/shkeeper/shkeeperService.ts` and payout flows + - `backend/src/services/payment/paymentCoordinator.ts` before completion transitions. +3. Create an internal service contract for setting/releasing hold after dispute open/resolve. +4. Add guard tests for blocked release and allowed release post-override. + +### Owner / dependencies +- Owner: Escrow/payment platform team. +- Depends on: dispute subsystem availability / status source-of-truth. + +--- + +## PRD 4: Strengthen DePay/Web3 verification semantics (P1) + +### Problem +- `backend/src/services/payment/decentralizedPaymentService.ts` verifies only `receipt.status === '0x1'`, without validating destination token, recipient, and amount mapping. + +### Acceptance criteria +- Verification loads the transaction receipt + logs + token-decoding and validates: + - correct recipient address (`toAddress`) + - expected token contract (`token`) + - minimum amount with decimals. +- Reject/flag ambiguous payloads and store verifier evidence in `Payment.metadata`. +- Add idempotency/duplicate handling for repeated verification requests. + +### Risk assessment +- **Threat**: Fraudulent transaction proofing and false-positive confirmations. +- **Likelihood**: Medium. +- **Impact**: High (unauthorized balance movement/false completion). +- **Mitigation**: Strict recipient/token/amount checks + explicit failure reason mapping. +- **Residual risk**: Medium (chain/protocol variance). + +### Delivery plan +1. Extend verifier schema for expected transfer contract/address/decimals. +2. Decode ERC-20 `Transfer` event and compare against expected values. +3. Mark and persist `verificationFingerprint` to prevent replay/double-processing. +4. Return canonical failure reasons for observability. + +### Owner / dependencies +- Owner: Payments + blockchain service team. +- Depends on: RPC/provider reliability and token ABI metadata. + +--- + +## PRD 5: Lock Socket.IO user room joins to authenticated context (P2) + +### Problem +- `backend/src/app.ts` allows `join-user-room`, `join-buyer-room`, and `join-seller-room` events from arbitrary input IDs with no identity binding. + +### Acceptance criteria +- Server derives room membership from validated `socket` identity after token handshake. +- Reject mismatched room join attempts with server-side authorization checks. +- Preserve real-time event behavior for legitimate users. + +### Risk assessment +- **Threat**: Event channel interception and privacy leakage. +- **Likelihood**: Medium. +- **Impact**: High (notifications/messages for wrong user). +- **Mitigation**: Server-authorized socket-to-user mapping and middleware verification. +- **Residual risk**: Low (requires active socket auth and client migration). + +### Delivery plan +1. Add token validation middleware on socket connection. +2. Replace client-sent ID room joins with authenticated identity joins. +3. Add per-room join/emit checks in critical publishers. +4. Add monitoring for room-join failures and suspicious activity. + +### Owner / dependencies +- Owner: Real-time platform team. +- Depends on: frontend socket auth handshake updates. + +--- + +## PRD 6: Re-enable and scope rate limiting for public-sensitive paths (P2) + +### Problem +- `backend/src/app.ts` has comments and code indicating rate limiting is disabled globally. + +### Acceptance criteria +- Re-enable limiter at edge level with sensible defaults. +- Use stricter quotas for auth/financial/AI endpoints. +- Keep lightweight paths (public listings, static read APIs) at higher budgets. + +### Risk assessment +- **Threat**: Brute-force/log abuse, AI cost exhaustion, webhook abuse. +- **Likelihood**: High. +- **Impact**: Medium-High (operational availability and cost). +- **Mitigation**: Endpoint-tiered limiter with trusted network exceptions and observability. +- **Residual risk**: Medium (false positives on legitimate spikes). + +### Delivery plan +1. Restore global limiter with default relaxed values. +2. Add stricter route-level windows for `/api/auth/*`, `/api/payment/*`, `/api/ai/*`. +3. Add alerts on repeated 429s and limit misconfigurations. + +### Owner / dependencies +- Owner: Platform infrastructure/security team. + +--- + +## Documentation and API alignment follow-up (P2) + +- Where docs refer to `backend/src/services/dispute/*` and `backend/src/services/dispute/disputeRoutes.ts`, either implement that module or update architecture/API/docs to current repository reality. +- Normalize enum/action naming across: + - `02 - Data Models/*` + - `03 - API Reference/*` + - `04 - Flows/*` + +--- + +## Delivery sequencing suggestion +1. PRD 1 (security/auth) +2. PRD 6 (rate limiting) +3. PRD 2 (passkeys) +4. PRD 4 (verification trust) +5. PRD 5 (socket hardening) +6. PRD 3 (dispute hold controls) +7. Documentation/API alignment + diff --git a/.taskmaster/docs/prd-request-network-migration-and-funds-management.md b/.taskmaster/docs/prd-request-network-migration-and-funds-management.md new file mode 100644 index 0000000..508a612 --- /dev/null +++ b/.taskmaster/docs/prd-request-network-migration-and-funds-management.md @@ -0,0 +1,333 @@ +# PRD - Request Network Migration and Funds Management + +Date: 2026-05-24 +Status: Draft for architecture review +Owner: Platform / Payments +Codebase reviewed: `/Users/manwe/CascadeProjects/escrow` + +## Executive Summary + +Replacing SHKeeper with Request Network is not a provider swap. SHKeeper currently acts like a deposit-wallet and payout-task provider: the backend creates a payment intent, receives a generated wallet address, watches SHKeeper webhooks and BSC wallet balances, then optionally creates an outgoing payout task. + +Request Network is request/payment-reference based. The platform creates a Request Network payment request or secure payment page, the payer pays through Request Network contracts or hosted flow, and reconciliation happens through Request Network payment events. Payouts are API-created payment requests/calldata that still require wallet execution. This means Amanat needs a first-class funds ledger and a release/refund orchestration layer, not just renamed `/payment/shkeeper/*` endpoints. + +Primary recommendation: run a phased migration behind a provider adapter. Introduce Request Network for new pay-ins first using Secure Payment Pages, keep SHKeeper read-only for existing payments, then add funds ledger, release/refund gates, and Request Network payout flows. + +## Source Findings + +Current code: + +- Backend mounts SHKeeper at `/api/payment/shkeeper` through `backend/src/services/payment/shkeeper/shkeeperRoutes.ts` and `shkeeperPayoutRoutes.ts`. +- Frontend calls SHKeeper through `frontend/src/actions/payment.ts`, `frontend/src/web3/components/shkeeper-payment.tsx`, `shkeeper-widget.tsx`, and `shkeeper-payout.tsx`. +- `Payment.provider` only allows `shkeeper` or `other`; SHKeeper-specific fields live directly under `Payment.metadata`. +- Pay-in completion is accepted from SHKeeper webhook, manual confirmation, or wallet monitor, all coordinated through `PaymentCoordinator`. +- Current payout paths mix SHKeeper payout tasks, simulated marketplace release, and direct admin wallet payout. +- There is no durable internal funds ledger that tracks available, held, releasable, disputed, released, refunded, and fee amounts per purchase request. + +Request Network documentation checked: + +- API v2 supports programmatic request creation, secure payment pages, payouts, webhooks, payment search, platform fees, and payee destinations: +- Secure Payment Pages are hosted payment URLs returned by `POST /v2/secure-payments`, returning `requestIds`, `token`, and `securePaymentUrl`: +- Secure Payment Pages validate official Request Network contracts before payer signing: +- Webhooks are scoped by Client ID and include `x-request-network-signature`, delivery ID, retry count, and optional test header: +- Request Network webhooks retry failed deliveries up to 3 retries with short backoff windows: +- Payout endpoints return unsigned transaction data that the platform/wallet must execute: +- Batch payouts can return approval and batch payment transactions; the application sends those wallet transactions: +- Request Network protocol fee is 5 bps with stablecoin caps, and platform fees can be included through `feePercentage` and `feeAddress`: +- Payment networks use payment references for detection, rather than unique deposit wallets per invoice: + +## Target Architecture + +### Payment Provider Adapter + +Create a provider-neutral payment interface: + +- `createPayInIntent` +- `getPayInStatus` +- `handleProviderWebhook` +- `createHostedPaymentLink` +- `createReleaseInstruction` +- `createRefundInstruction` +- `getPayoutStatus` +- `searchProviderPayments` + +Implement: + +- `ShkeeperProvider` for legacy compatibility. +- `RequestNetworkProvider` for new flows. + +### Funds Ledger + +Add an internal ledger separate from provider metadata: + +- `fundsAccount`: one per purchase request or order. +- `ledgerEntry`: immutable entries for authorization, payment detected, platform fee, provider fee, hold, release, refund, chargeback/dispute hold, adjustment. +- `fundsBalance`: derived or cached view containing `expected`, `paid`, `held`, `releasable`, `released`, `refunded`, `disputed`, `fees`, and `available`. + +Ledger invariants: + +- Seller payout cannot exceed paid amount minus refunds, fees, and active dispute holds. +- Release requires payment status `completed`, escrow state `releasable`, no open dispute, and a verified seller destination. +- Refund requires available held balance and must mark the purchase request/payment state consistently. +- Provider webhooks never directly mark funds as released; they create/reconcile ledger entries. + +### Payment Flow + +Pay-in: + +1. Buyer accepts seller offer. +2. Backend creates internal payment + funds account. +3. Backend calls Request Network `POST /v2/secure-payments` or `POST /v2/request`. +4. Frontend redirects to `securePaymentUrl` or executes returned calldata in wallet. +5. Request Network webhook confirms payment. +6. Backend verifies signature, idempotency, amount, request ID, payment reference, currency, and merchant reference. +7. Ledger moves from `expected` to `held`. +8. Purchase request enters `payment` or `processing`. + +Release: + +1. Buyer delivery confirmation or admin release marks funds `releasable`. +2. Backend creates Request Network payout/release instruction, or admin wallet transaction instruction. +3. Admin/operator wallet signs and broadcasts transaction. +4. Backend records transaction hash as `release_pending`. +5. Webhook/search confirms settlement. +6. Ledger moves `held -> released`. + +Refund: + +1. Refund request validates available held balance. +2. Backend creates refund transaction instruction. +3. Admin/operator wallet executes. +4. Confirmation updates ledger `held -> refunded`. + +## PRD 1 - Provider-Neutral Payment Adapter + +Priority: P0 + +Goal: decouple checkout, webhook, and payout flows from SHKeeper-specific routes and metadata. + +Scope: + +- Add `paymentProvider` abstraction in backend. +- Add `provider: 'shkeeper' | 'request_network' | 'manual' | 'admin_wallet'` to payment model. +- Keep `/api/payment/shkeeper/*` operational for legacy records. +- Add `/api/payment/providers/request-network/*` or `/api/payment/request-network/*` for new Request Network flows. +- Add a feature flag: `PAYMENT_PROVIDER=request_network|shkeeper`. + +Acceptance Criteria: + +- New checkout can create a Request Network payment link without touching SHKeeper service code. +- Existing SHKeeper payments remain readable and can still process late webhooks. +- Frontend does not import provider-specific action names outside provider-specific components. +- Provider metadata is namespaced under `metadata.providers.requestNetwork` or a dedicated provider table. + +Risk Assessment: + +- Impact: High. Payment creation is core revenue flow. +- Likelihood: Medium. Existing code has many direct `shkeeper` references. +- Main risks: broken checkout, duplicate payment records, orphaned webhooks, mixed provider states. +- Mitigation: use provider feature flag, preserve SHKeeper routes, add idempotency keys, run Request Network only for new payments during rollout. +- Rollback: set `PAYMENT_PROVIDER=shkeeper`; keep Request Network records read-only. + +## PRD 2 - Request Network Pay-In Integration + +Priority: P0 + +Goal: replace generated SHKeeper wallet addresses with Request Network request/payment-reference based payment collection. + +Scope: + +- Store Request Network `requestId`, `paymentReference`, `securePaymentUrl`, `token`, `merchantReference`, `network`, `invoiceCurrency`, and `paymentCurrency`. +- Use Secure Payment Pages for first launch to reduce frontend wallet/calldata complexity. +- Include Amanat purchase request ID and payment ID as merchant reference or metadata. +- Validate supported networks/currencies before creating payment links. +- Remove frontend dependence on SHKeeper-generated `walletAddress` for new provider flow. + +Acceptance Criteria: + +- Buyer can start payment and receive a Request Network hosted payment URL. +- Backend records internal payment as `pending` with Request Network identifiers. +- Webhook `payment.confirmed` reconciles only the matching internal payment. +- Amount, currency, provider request ID, and merchant reference are verified before setting `escrowState='funded'`. +- Late or duplicate webhook deliveries are idempotent. + +Risk Assessment: + +- Impact: High. +- Likelihood: Medium. +- Main risks: currency/network mismatch, hosted redirect UX breakage, buyer pays wrong amount, missing webhook. +- Mitigation: backend-only creation, strict metadata correlation, periodic fallback reconciliation using Request Network payment search, idempotency by delivery ID and request ID. +- Rollback: disable Request Network provider for new payments; keep pending Request Network payments visible with manual support workflow. + +## PRD 3 - Funds Ledger and Escrow State Machine + +Priority: P0 + +Goal: introduce internal funds management so payment, hold, release, refund, dispute, and fee states are auditable and provider-independent. + +Scope: + +- Add `FundsAccount` model keyed by purchase request/payment. +- Add immutable `LedgerEntry` model with provider references and actor/source. +- Add derived `FundsBalance` query/service. +- Define state transitions: `expected -> held -> releasable -> releasing -> released`, plus `refunded`, `partially_refunded`, `disputed`, `failed`. +- Prevent release/refund from reading raw `Payment.status` alone. + +Acceptance Criteria: + +- Every successful pay-in creates a ledger entry for gross paid amount. +- Platform fee, Request Network protocol fee, and net seller amount are represented explicitly. +- Release API checks ledger invariants before creating payout/refund instructions. +- Dispute hold blocks payout until resolved. +- Admin UI/payment detail view can show gross paid, fees, held, releasable, released, refunded. + +Risk Assessment: + +- Impact: Very High. +- Likelihood: Medium. +- Main risks: double-release, incorrect fee accounting, drift between Payment and ledger state. +- Mitigation: immutable entries, unique idempotency keys, transaction/session writes where Mongo supports them, reconciliation job, read-only migration report before enforcing ledger. +- Rollback: keep old payment fields as source of truth until ledger backfill passes; feature flag release enforcement. + +## PRD 4 - Request Network Webhook and Reconciliation Service + +Priority: P1 + +Goal: replace SHKeeper webhook and wallet monitor semantics with signed Request Network event processing and periodic reconciliation. + +Scope: + +- Add `/api/payment/request-network/webhook`. +- Verify raw body using `x-request-network-signature`. +- Store delivery ID, retry count, event type, request ID, payment reference, payload hash, and processed status. +- Support test webhooks via `x-request-network-test`. +- Add scheduled reconciliation using Request Network payment search/status APIs. +- Retire SHKeeper wallet monitor for new Request Network payments. + +Acceptance Criteria: + +- Invalid signatures are rejected in all environments except explicit local test mode. +- Duplicate delivery IDs are acknowledged without duplicating ledger entries. +- `payment.confirmed` and partial/over/failed states map to internal status consistently. +- Reconciliation job can repair missed webhook state without relying on buyer/frontend callbacks. + +Risk Assessment: + +- Impact: High. +- Likelihood: Medium. +- Main risks: raw body parsing mismatch, webhook downtime, event mapping mistakes. +- Mitigation: raw-body middleware scoped to webhook route, event fixture tests, dead-letter queue/table, operator replay endpoint. +- Rollback: pause webhook processor and rely on manual/admin reconciliation for Request Network records. + +## PRD 5 - Release, Refund, and Payout Orchestration + +Priority: P1 + +Goal: replace SHKeeper payout tasks and simulated marketplace release with auditable transaction instruction and confirmation flows. + +Scope: + +- Define release/refund service that consumes ledger balances, not raw request status. +- Generate Request Network payout instructions or direct admin wallet transaction instructions. +- Store unsigned transaction payloads, signer, submitted tx hash, confirmation status, and provider status. +- Add batch payout support as a later optimization after single release is stable. +- Require admin/operator authorization and dispute checks before instruction creation. + +Acceptance Criteria: + +- Seller payout requires verified seller wallet/payee destination. +- Release cannot occur if funds are unpaid, already released, refunded, or disputed. +- Transaction hash confirmation updates ledger only once. +- Admin can see pending release instructions and retry/cancel safely. +- Existing `/purchase-requests/:id/release-payment` simulated path is removed or hidden behind dev-only mode. + +Risk Assessment: + +- Impact: Very High. +- Likelihood: High. +- Main risks: Request Network payouts are not custodial magic; operator wallet still signs transactions, so process failure can leave funds pending. +- Mitigation: explicit release queue, two-step admin approval, signer audit trail, reconciliation against tx hash/provider status. +- Rollback: keep direct admin wallet payout as emergency fallback with mandatory ledger entry and reason code. + +## PRD 6 - Frontend Checkout and Admin Migration + +Priority: P1 + +Goal: update buyer payment, admin release, seller payout, and payment details UI for Request Network flows. + +Scope: + +- Replace `ShkeeperPayment` with provider-neutral `CryptoPayment`. +- Add `RequestNetworkPayment` redirect flow for secure payment pages. +- Keep `ShkeeperPayment` available only for legacy/unpaid SHKeeper records if needed. +- Replace `ShkeeperPayout` with release queue/admin payout UI. +- Payment detail page shows provider, request ID, payment reference, hosted link, transaction hashes, ledger balances, webhook/reconciliation status. + +Acceptance Criteria: + +- Buyer checkout no longer expects provider-generated `walletAddress` for Request Network payments. +- Admin release UI displays available/releasable funds and blocks unsafe release states. +- Seller payout status comes from internal release instruction/ledger, not SHKeeper task polling. +- Legacy SHKeeper labels are not shown for Request Network payments. + +Risk Assessment: + +- Impact: Medium-High. +- Likelihood: Medium. +- Main risks: confusing redirect UX, old Persian labels referencing SHKeeper, admin accidentally using old payout button. +- Mitigation: provider-specific copy, feature flag UI sections, legacy badge, clear payment detail diagnostics. +- Rollback: route checkout back to SHKeeper component via provider flag. + +## PRD 7 - Data Migration and Legacy Decommission + +Priority: P2 + +Goal: safely migrate historical SHKeeper payment records and phase out provider-specific code. + +Scope: + +- Backfill provider metadata namespace for existing SHKeeper payments. +- Create ledger entries for completed SHKeeper payments from trusted records. +- Mark historical records as `legacyProvider='shkeeper'`. +- Keep SHKeeper webhook active during webhook tail period. +- Remove SHKeeper wallet monitor, simple auto webhook, test callback routes, and payout routes after cutoff. + +Acceptance Criteria: + +- Migration produces counts for total, migrated, skipped, ambiguous, and failed records. +- No historical completed payment loses transaction hash/provider invoice/task metadata. +- Legacy SHKeeper webhook can still reconcile existing pending records until cutoff date. +- Decommission checklist includes env vars, docs, frontend labels, backend routes, and runbooks. + +Risk Assessment: + +- Impact: Medium. +- Likelihood: Medium. +- Main risks: ambiguous historical records, template checkout string IDs, mixed status meanings. +- Mitigation: dry-run migration, manual review bucket, no destructive migration, keep original metadata. +- Rollback: ledger backfill is additive; old records remain intact. + +## Implementation Sequence + +1. Add provider adapter and Request Network config without changing default provider. +2. Add funds ledger models/services and dry-run backfill report. +3. Implement Request Network secure pay-in flow behind feature flag. +4. Implement signed webhook receiver and reconciliation job. +5. Enable Request Network for limited new checkout cohort. +6. Add release/refund orchestration using ledger gates. +7. Migrate admin/frontend views. +8. Backfill legacy records. +9. Decommission SHKeeper once no active records depend on it. + +## Open Decisions + +- Use Request Network Secure Payment Pages first, or execute Request Network calldata directly in the existing wallet modal? +- Keep funds in a platform-controlled escrow wallet, pay sellers via admin/operator release, or route pay-ins directly to seller with only platform fee collection? +- Which chains/currencies are required for launch: BSC USDT parity with today, or Request Network supported stablecoin routes first? +- Should platform fee be paid by buyer, seller, or absorbed by Amanat? +- Does Amanat need crypto-to-fiat/offramp later, which adds KYC/payment detail requirements? + +## Recommendation + +Start with Secure Payment Pages and a platform escrow/payee destination controlled by Amanat. This best matches the current escrow mental model while reducing frontend transaction-building risk. Do not route pay-ins directly to sellers until dispute handling, refund logic, and service fee economics are fully redesigned. + diff --git a/.taskmaster/state.json b/.taskmaster/state.json new file mode 100644 index 0000000..f1ae304 --- /dev/null +++ b/.taskmaster/state.json @@ -0,0 +1,5 @@ +{ + "currentTag": "master", + "lastSwitched": "2026-05-24T00:00:00.000Z", + "migrationNoticeShown": true +} diff --git a/.taskmaster/tasks/task-1.md b/.taskmaster/tasks/task-1.md new file mode 100644 index 0000000..8052088 --- /dev/null +++ b/.taskmaster/tasks/task-1.md @@ -0,0 +1,9 @@ +# Task 1: Stabilize Mermaid diagram rendering across documentation vault + +Status: done +Priority: medium +Source PRD: `.taskmaster/docs/prd-mermaid-diagram-rendering-stabilization.md` + +Correct Mermaid syntax/rendering issues across the documentation vault and validate all Mermaid blocks. + +The source PRD records that all targeted task files pass `@mermaid-js/mermaid-cli` parsing and the full vault sweep passes. diff --git a/.taskmaster/tasks/task-2.md b/.taskmaster/tasks/task-2.md new file mode 100644 index 0000000..c690b66 --- /dev/null +++ b/.taskmaster/tasks/task-2.md @@ -0,0 +1,17 @@ +# Task 2: Implement platform audit remediation plan + +Status: pending +Priority: high +Source PRD: `.taskmaster/docs/prd-platform-audit-remediation-plan-2026-05-24.md` + +Address the code-backed security and consistency issues identified in the 2026-05-24 platform audit remediation PRD. + +Subtasks: + +1. Secure unauthenticated endpoints and owner enforcement. +2. Re-enable and scope rate limiting. +3. Replace stubbed passkey/WebAuthn flow. +4. Strengthen DePay/Web3 payment verification. +5. Lock Socket.IO room joins to authenticated context. +6. Enforce dispute hold before payout and release operations. +7. Align documentation, API references, and runtime enums. diff --git a/.taskmaster/tasks/task-3.md b/.taskmaster/tasks/task-3.md new file mode 100644 index 0000000..8d6f09e --- /dev/null +++ b/.taskmaster/tasks/task-3.md @@ -0,0 +1,18 @@ +# Task 3: Migrate payment architecture toward Request Network and internal funds management + +Status: pending +Priority: high +Depends on: Task 2 +Source PRD: `.taskmaster/docs/prd-request-network-migration-and-funds-management.md` + +Plan and implement provider-neutral payment flows, Request Network pay-in support, funds ledger, webhook reconciliation, release/refund orchestration, UI migration, and SHKeeper decommissioning. + +Subtasks: + +1. Introduce provider-neutral payment adapter. +2. Implement Request Network pay-in integration. +3. Add funds ledger and escrow state machine. +4. Build Request Network webhook and reconciliation service. +5. Implement release, refund, and payout orchestration. +6. Migrate frontend checkout and admin payment UI. +7. Backfill legacy SHKeeper records and decommission provider-specific code. diff --git a/.taskmaster/tasks/tasks.json b/.taskmaster/tasks/tasks.json new file mode 100644 index 0000000..364be00 --- /dev/null +++ b/.taskmaster/tasks/tasks.json @@ -0,0 +1,70 @@ +{ + "master": { + "metadata": { + "projectName": "Amanat Documentation PRDs", + "created": "2026-05-24T00:00:00.000Z", + "updated": "2026-05-24T00:00:00.000Z", + "description": "Taskmaster task queue generated from docs-side PRDs for developer sharing.", + "sourcePrds": [ + ".taskmaster/docs/prd-mermaid-diagram-rendering-stabilization.md", + ".taskmaster/docs/prd-platform-audit-remediation-plan-2026-05-24.md", + ".taskmaster/docs/prd-request-network-migration-and-funds-management.md" + ] + }, + "tasks": [ + { + "id": 1, + "title": "Stabilize Mermaid diagram rendering across documentation vault", + "description": "Correct Mermaid syntax/rendering issues across the documentation vault and validate all Mermaid blocks.", + "details": "Source PRD: .taskmaster/docs/prd-mermaid-diagram-rendering-stabilization.md. Scope covered 57 Mermaid blocks and 11 failing blocks. The source PRD records that all targeted files now pass mmdc parse validation and the full vault sweep passes.", + "testStrategy": "Run the same mmdc-based syntax validation across all Markdown Mermaid blocks and confirm zero parser failures in Obsidian/markdown previews.", + "priority": "medium", + "status": "done", + "dependencies": [], + "subtasks": [ + { "id": 1, "title": "Fix Security Architecture email/password sequence", "description": "Normalize parser-sensitive sequence text in 01 - Architecture/Security Architecture.md.", "details": "Avoid semicolons and ambiguous inline punctuation in sequence messages.", "status": "done", "priority": "medium", "dependencies": [], "testStrategy": "mmdc parse for the specific block." }, + { "id": 2, "title": "Fix authentication login and refresh diagrams", "description": "Normalize parser-sensitive token and refresh-token sequence text in Authentication Flow.", "details": "Split method-like or expression-like message text into parser-safe plain text lines.", "status": "done", "priority": "medium", "dependencies": [], "testStrategy": "mmdc parse for both Authentication Flow blocks." }, + { "id": 3, "title": "Fix chat, delivery, dispute, OAuth, purchase request, referral, registration, and seller-offer diagrams", "description": "Clean the remaining Mermaid sequence diagrams with invalid or ambiguous syntax.", "details": "Split multi-recipient arrows, remove parser-conflicting semicolon/expression text, and keep intent unchanged.", "status": "done", "priority": "medium", "dependencies": [], "testStrategy": "Full vault mmdc parser sweep across all Mermaid blocks." } + ] + }, + { + "id": 2, + "title": "Implement platform audit remediation plan", + "description": "Address the code-backed security and consistency issues identified in the 2026-05-24 platform audit remediation PRD.", + "details": "Source PRD: .taskmaster/docs/prd-platform-audit-remediation-plan-2026-05-24.md. Target backend hardening first, then documentation/runtime alignment. Delivery order suggested by PRD: security/auth, rate limiting, passkeys, Web3 verification, socket hardening, dispute hold controls, docs/API alignment.", + "testStrategy": "Add focused regression tests for route auth/ownership, passkey challenge/verification, Web3 verification semantics, socket authorization, rate limiting tiers, and payout/release dispute holds. Update API docs after behavior is implemented.", + "priority": "high", + "status": "pending", + "dependencies": [], + "subtasks": [ + { "id": 1, "title": "Secure unauthenticated endpoints and owner enforcement", "description": "Require authenticateToken and owner/admin checks on exposed payment, AI, and legacy notification routes.", "details": "Derive notification userId from authenticated principal. Protect payment history and mutation endpoints. Restrict AI calls to authenticated users with per-user budgets. Add denied-access audit logs.", "status": "pending", "priority": "high", "dependencies": [], "testStrategy": "Unauthorized callers receive 401/403; users cannot access or mutate other users' payments/notifications; admins retain authorized access." }, + { "id": 2, "title": "Re-enable and scope rate limiting", "description": "Restore global and route-tiered rate limits for public-sensitive paths.", "details": "Use stricter limits for auth, financial, AI, file upload, and verification paths. Keep public reads at relaxed limits. Add observability for 429 spikes.", "status": "pending", "priority": "high", "dependencies": [1], "testStrategy": "Exercise configured limits per tier and confirm expected 429 responses without blocking ordinary reads." }, + { "id": 3, "title": "Replace stubbed passkey/WebAuthn flow", "description": "Implement production-grade WebAuthn registration/authentication and shared challenge storage.", "details": "Use real attestation/assertion verification, Redis-backed TTL challenges, refresh-token persistence/rotation, and deterministic malformed/reused/expired challenge errors.", "status": "pending", "priority": "high", "dependencies": [1], "testStrategy": "Registration, login, replay, expired challenge, and refresh-token continuity tests pass." }, + { "id": 4, "title": "Strengthen DePay/Web3 payment verification", "description": "Verify transaction recipient, token contract, and amount, not only receipt success.", "details": "Decode ERC-20 Transfer logs, compare recipient against escrow address, validate token contract and decimals-adjusted minimum amount, store verifier evidence and idempotency fingerprint.", "status": "pending", "priority": "high", "dependencies": [1], "testStrategy": "Reject successful but wrong-recipient/wrong-token/underpaid tx hashes; accept only matching transfers." }, + { "id": 5, "title": "Lock Socket.IO room joins to authenticated context", "description": "Remove trust in client-supplied user/buyer/seller room IDs.", "details": "Validate socket handshake token, derive server-side room membership, reject mismatched joins, and monitor suspicious join attempts.", "status": "pending", "priority": "medium", "dependencies": [1], "testStrategy": "A user cannot subscribe to another user's rooms; legitimate realtime notifications still arrive." }, + { "id": 6, "title": "Enforce dispute hold before payout and release operations", "description": "Add payment hold state and central release/refund guards that block disputed funds.", "details": "Introduce explicit dispute hold fields or state, enforce in PaymentCoordinator and payout/release services, return clear 409/423 responses, and backfill/report blocked payments.", "status": "pending", "priority": "medium", "dependencies": [1, 4], "testStrategy": "Open dispute blocks release/refund until resolved or explicitly overridden through authorized path." }, + { "id": 7, "title": "Align documentation, API references, and runtime enums", "description": "Normalize disputed/payment/request status docs and implementation references after security behavior changes.", "details": "Resolve mismatch around absent dispute module, endpoint names, status enums, and action names across Data Models, API Reference, and Flows.", "status": "pending", "priority": "medium", "dependencies": [1, 2, 3, 4, 5, 6], "testStrategy": "Docs match implemented routes, models, enum values, and state transitions." } + ] + }, + { + "id": 3, + "title": "Migrate payment architecture toward Request Network and internal funds management", + "description": "Plan and implement provider-neutral payment flows, Request Network pay-in support, funds ledger, webhook reconciliation, release/refund orchestration, UI migration, and SHKeeper decommissioning.", + "details": "Source PRD: .taskmaster/docs/prd-request-network-migration-and-funds-management.md. The PRD recommends phased migration behind a provider adapter, Secure Payment Pages first, platform-controlled escrow/payee destination, and a first-class internal funds ledger before release/refund enforcement.", + "testStrategy": "Use feature flags, provider fixture tests, webhook signature/idempotency tests, ledger invariant tests, migration dry-run reports, and limited cohort rollout before default provider switch.", + "priority": "high", + "status": "pending", + "dependencies": [2], + "subtasks": [ + { "id": 1, "title": "Introduce provider-neutral payment adapter", "description": "Decouple checkout, webhook, and payout flows from SHKeeper-specific routes and metadata.", "details": "Define createPayInIntent, getPayInStatus, handleProviderWebhook, createHostedPaymentLink, createReleaseInstruction, createRefundInstruction, getPayoutStatus, and searchProviderPayments. Add provider values shkeeper, request_network, manual, admin_wallet and PAYMENT_PROVIDER feature flag.", "status": "pending", "priority": "high", "dependencies": [], "testStrategy": "New provider can be selected by feature flag while existing SHKeeper payments remain readable and process late webhooks." }, + { "id": 2, "title": "Implement Request Network pay-in integration", "description": "Create Request Network payment requests or Secure Payment Pages for new checkout flows.", "details": "Store requestId, paymentReference, securePaymentUrl, token, merchantReference, network, invoiceCurrency, and paymentCurrency. Validate supported networks/currencies before creating links.", "status": "pending", "priority": "high", "dependencies": [1], "testStrategy": "Buyer receives hosted payment URL; webhook reconciles matching internal payment only after amount/currency/reference validation." }, + { "id": 3, "title": "Add funds ledger and escrow state machine", "description": "Introduce internal funds accounting independent from provider metadata.", "details": "Add FundsAccount, LedgerEntry, derived FundsBalance, expected/held/releasable/releasing/released/refunded/disputed/failed states, fee representation, and release/refund invariant checks.", "status": "pending", "priority": "high", "dependencies": [1], "testStrategy": "Every pay-in creates immutable ledger entries and payout/refund cannot exceed available held funds or bypass dispute holds." }, + { "id": 4, "title": "Build Request Network webhook and reconciliation service", "description": "Process signed Request Network events and repair missed webhook state through reconciliation.", "details": "Add /api/payment/request-network/webhook, verify raw-body x-request-network-signature, store delivery ID/retry/event/request/payment reference/payload hash, support test webhooks, and add scheduled payment search/status reconciliation.", "status": "pending", "priority": "high", "dependencies": [2, 3], "testStrategy": "Invalid signatures reject; duplicate delivery IDs acknowledge without duplicate ledger entries; reconciliation repairs missed state." }, + { "id": 5, "title": "Implement release, refund, and payout orchestration", "description": "Replace SHKeeper payout tasks and simulated release with auditable transaction instruction and confirmation flows.", "details": "Create release/refund service consuming ledger balances, generate Request Network payout or direct admin wallet instructions, store unsigned tx payloads, signer, submitted hash, confirmation status, provider status, and require admin/operator authorization plus dispute checks.", "status": "pending", "priority": "high", "dependencies": [3, 4], "testStrategy": "Release cannot occur if unpaid, already released, refunded, or disputed; tx hash confirmation updates ledger once; admin can retry/cancel safely." }, + { "id": 6, "title": "Migrate frontend checkout and admin payment UI", "description": "Update buyer checkout, admin release, seller payout, and payment details for provider-neutral Request Network flows.", "details": "Replace ShkeeperPayment with CryptoPayment/RequestNetworkPayment redirect flow, keep legacy SHKeeper only for legacy records, replace ShkeeperPayout with release queue/admin payout UI, and show provider IDs, payment references, hosted links, ledger balances, webhook/reconciliation status.", "status": "pending", "priority": "medium", "dependencies": [2, 3, 5], "testStrategy": "Request Network checkout does not expect walletAddress; admin UI blocks unsafe release; legacy labels are hidden for Request Network records." }, + { "id": 7, "title": "Backfill legacy SHKeeper records and decommission provider-specific code", "description": "Migrate historical SHKeeper payment metadata and safely remove legacy wallet monitor/webhook/payout paths after cutoff.", "details": "Backfill provider namespace, create ledger entries for trusted completed SHKeeper payments, mark legacyProvider, keep webhook tail period, and produce decommission checklist for env vars, docs, labels, routes, and runbooks.", "status": "pending", "priority": "medium", "dependencies": [3, 4, 5, 6], "testStrategy": "Dry-run report includes total, migrated, skipped, ambiguous, failed; no historical transaction hash/invoice/task metadata is lost." } + ] + } + ] + } +} diff --git a/README.md b/README.md index 838cd74..7e2d486 100644 --- a/README.md +++ b/README.md @@ -153,6 +153,7 @@ For engineers / SREs running the system in production. | **Payments** | [[Payment Flow - SHKeeper]] → [[Payment API]] → [[Payment]] → [[Payout Flow]] | | **Auth** | [[Authentication Flow]] → [[Authentication API]] → [[Security Architecture]] | | **Backend security / refactor** | [[Backend Stack Security and Refactor Assessment - 2026-05-24]] → [[Platform Logical Audit - 2026-05-24]] → [[PRD - Platform Audit Remediation Plan (2026-05-24)]] | +| **Developer task queue** | `.taskmaster/README.md` → `.taskmaster/tasks/tasks.json` → root `PRD - *.md` files | | **Real-time** | [[Real-time Layer]] → [[Socket Events]] → [[Chat Flow]] / [[Notification Flow]] | | **Disputes** | [[Dispute Flow]] → [[Dispute API]] → [[Dispute]] → [[Admin Guide]] §5 | | **Web3** | [[Payment Flow - DePay & Web3]] → [[Frontend Architecture]] §9 |