docs: add latest audit to taskmaster

This commit is contained in:
Siavash Sameni
2026-05-24 09:09:55 +04:00
parent a37b1b1446
commit 393bb17c2e
3 changed files with 916 additions and 19 deletions

View File

@@ -8,7 +8,8 @@
"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"
".taskmaster/docs/prd-request-network-migration-and-funds-management.md",
".taskmaster/docs/audit-backend-stack-security-and-refactor-assessment-2026-05-24.md"
]
},
"tasks": [
@@ -22,9 +23,36 @@
"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": 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."
}
]
},
{
@@ -37,13 +65,94 @@
"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": 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."
}
]
},
{
@@ -54,15 +163,222 @@
"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],
"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." }
{
"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."
}
]
},
{
"id": 4,
"title": "Define backend security and refactor strategy from latest audit",
"description": "Convert the backend stack security/refactor assessment into concrete architecture decisions, documentation deliverables, and developer handoff criteria.",
"details": "Source audit: .taskmaster/docs/audit-backend-stack-security-and-refactor-assessment-2026-05-24.md. This task is advisory/architecture-focused and should run in parallel with immediate hardening. It should produce the decision artifacts needed before any backend-core rewrite or provider migration is started.",
"testStrategy": "Review and sign off each architecture document with backend, payments, frontend, and operations stakeholders. Confirm every open question has an owner or explicit deferred decision before implementation work begins.",
"priority": "high",
"status": "pending",
"dependencies": [],
"subtasks": [
{
"id": 1,
"title": "Assign security ownership and launch decision criteria",
"description": "Define who owns security decisions and what must be true before public launch or migration work proceeds.",
"details": "Answer ownership questions from the audit: security owner, launch safety bar, whether launch prioritizes hardening or redesign, and whether external penetration testing is required.",
"status": "pending",
"priority": "high",
"dependencies": [],
"testStrategy": "Written owner/RACI and launch gate checklist are accepted by leadership and engineering."
},
{
"id": 2,
"title": "Produce threat model for escrow platform",
"description": "Document protected assets, actors, trust boundaries, and abuse cases for the financial marketplace.",
"details": "Include buyer, seller, admin, support, unauthenticated attacker, compromised user/admin, provider, malicious webhook sender, browser/backend/database/Redis/provider/wallet/Socket.IO trust boundaries, and abuse cases such as fake payment proof, replayed webhook, arbitrary room join, stolen token, double payout, dispute bypass, email abuse, and AI abuse.",
"status": "pending",
"priority": "high",
"dependencies": [
1
],
"testStrategy": "Threat model maps each high-risk finding to at least one mitigation task or accepted risk."
},
{
"id": 3,
"title": "Specify funds ledger and escrow state machine",
"description": "Define canonical money movement and legal state transitions before refactor or provider migration.",
"details": "Create specs for FundsAccount, LedgerEntry, FundsBalance, gross paid, provider fees, platform fees, held, disputed, releasable, released, refunded, idempotency keys, reconciliation behavior, purchase request states, payment states, escrow/funds states, dispute states, valid transitions, forbidden transitions, and release/refund/admin override preconditions.",
"status": "pending",
"priority": "high",
"dependencies": [
2
],
"testStrategy": "Spec can be used to reject double-release, release-during-dispute, underfunded payout, and ambiguous provider-event scenarios."
},
{
"id": 4,
"title": "Create authorization matrix for REST and Socket.IO",
"description": "Map every endpoint and realtime event to access level, ownership checks, state preconditions, rate-limit tier, and audit-log requirement.",
"details": "Include public/authenticated/owner/buyer/seller/admin/support/service-role classifications. Socket.IO rooms must be server-derived from authenticated identity, not client-supplied user IDs.",
"status": "pending",
"priority": "high",
"dependencies": [
2
],
"testStrategy": "No route or socket event remains unmapped; implementation tasks can reference matrix rows directly."
},
{
"id": 5,
"title": "Decide session, passkey, and admin step-up architecture",
"description": "Choose browser session model and high-risk admin authentication requirements.",
"details": "Decide localStorage versus httpOnly cookies, access/refresh token lifetimes, CSRF strategy, refresh rotation, WebAuthn requirements, OAuth requirements, device/session revocation, and whether payouts/role changes require step-up authentication or two-person approval.",
"status": "pending",
"priority": "high",
"dependencies": [
2
],
"testStrategy": "Decision record lists chosen model, rejected alternatives, migration cost, and required implementation tasks."
},
{
"id": 6,
"title": "Specify webhook security and provider adapter contracts",
"description": "Define provider-neutral payment interface and signed webhook processing rules.",
"details": "Document createPayInIntent, getPayInStatus, handleProviderWebhook, createHostedPaymentLink, createReleaseInstruction, createRefundInstruction, getPayoutStatus, searchProviderPayments, raw-body signature verification, replay prevention, delivery ID idempotency, duplicate/unknown event behavior, retry semantics, dead-letter/replay storage, and alert thresholds.",
"status": "pending",
"priority": "high",
"dependencies": [
3
],
"testStrategy": "Contracts cover SHKeeper legacy, Request Network, manual/admin wallet, invalid signatures, duplicate deliveries, and missed webhook reconciliation."
},
{
"id": 7,
"title": "Define secure build and supply-chain policy",
"description": "Reduce npm/dependency compromise risk across frontend and any remaining Node services.",
"details": "Specify package manager and lockfile policy, CI install mode, dependency update cadence, advisory monitoring, npm provenance/signature policy where available, secrets handling, reproducible production builds, and separation between frontend npm risk and backend-core risk.",
"status": "pending",
"priority": "medium",
"dependencies": [
1
],
"testStrategy": "Policy is actionable in CI and includes response steps for compromised package, leaked token, and vulnerable dependency alerts."
},
{
"id": 8,
"title": "Make backend-core stack decision",
"description": "Choose whether the security-critical backend core remains TypeScript or moves to Go/Kotlin/Rust/Python.",
"details": "Evaluate team capability, two-year maintainability, operational footprint, rewrite cost, dual-stack complexity, auditability, supply-chain exposure, and which modules belong in a payment/auth/escrow core versus the existing marketplace/chat API.",
"status": "pending",
"priority": "medium",
"dependencies": [
2,
3,
4,
5,
6,
7
],
"testStrategy": "Architecture decision record states chosen stack, scope of extraction, non-goals, migration phases, rollback criteria, and owners."
},
{
"id": 9,
"title": "Create migration and operational runbooks",
"description": "Document rollout, rollback, and incident response for the selected backend/funds architecture.",
"details": "Include SHKeeper legacy read path, provider feature flag, ledger backfill, validation report before enforcement, rollback criteria, webhook cutoff, manual reconciliation, failed webhook, duplicate/missing payment, stuck release, disputed release attempt, compromised admin, leaked API key, provider outage, chain/RPC outage, suspicious payment proof, and npm/package compromise.",
"status": "pending",
"priority": "medium",
"dependencies": [
8
],
"testStrategy": "Runbooks identify owner, trigger, detection signal, immediate action, recovery action, and post-incident documentation for each scenario."
}
]
}
]