# Platform Logical Audit

**Date:** 2026-05-24  
**Scope:** Data Models, API Reference, Architecture, Flows, Security  
**Method:** Cross-document consistency check, state-machine validation, authorization gap analysis, dependency verification

---

## Executive Summary

This audit identifies critical logical contradictions, security holes, and cross-document inconsistencies across the Amn platform documentation. The most severe findings are:

1. **Dispute/escrow race condition** allowing fund release while a dispute is active.
2. **Three mutually incompatible `Dispute` status/action enums** across the Data Model, API Reference, and Flow documents — the documented API cannot be implemented against the documented schema.
3. **Passkey (WebAuthn) implementation is cryptographically broken** and unusable in production.
4. **Multiple financial endpoints require no authentication**, allowing unauthenticated payment record injection and private data exfiltration.
5. **Web3 payment verification only checks `receipt.status`**, not recipient address or amount, making payment fraud trivial.

---

## 🔴 Critical Issues

### 1. Dispute Does Not Auto-Pause Escrow (Funds-at-Risk)

**Files:** `04 - Flows/Dispute Flow.md`, `03 - API Reference/Dispute API.md`

**Finding:** The Dispute Flow explicitly states: *"Today, opening a dispute does **not** flip `Payment.escrowState` away from `funded`. An admin could theoretically still release the escrow before resolving the dispute."*

At the same time, the Dispute API claims dispute creation *"Pauses any in-flight payout (sets a hold flag)."*

**Impact:** A buyer opens a dispute; an admin (or malicious/compromised admin) releases the escrow before resolution. The seller receives funds while the dispute is still open.

**Required Fix:** Introduce a `disputed` escrow state (or `disputeHold` flag) that blocks all release/refund operations until the dispute is resolved. The hold must be enforced in `PaymentCoordinator`, not just in controller logic.

---

### 2. Passkey Authentication Is Completely Broken

**Files:** `04 - Flows/Passkey (WebAuthn) Flow.md`, `02 - Data Models/User.md`

**Findings:**
- **Attestation is stubbed:** The `publicKey` field is stored as the literal string `'simulated-public-key'`. A malicious client can register any credential ID under any user account.
- **Refresh tokens are not persisted:** Passkey-issued refresh tokens are never appended to `user.refreshTokens[]`. Standard `/api/auth/refresh-token` will reject them, breaking session continuity.
- **In-memory challenge store:** `storedChallenges` is a `Map` in process memory. In a horizontally scaled deployment, the challenge created on instance A can only be verified on instance A. Load-balancer round-robin breaks authentication entirely.

**Impact:** Passkey auth is trivially bypassable and non-functional at scale.

**Required Fix:** Replace stub with `@simplewebauthn/server` (or equivalent), persist real public keys, store refresh tokens in the user record, and move challenges to Redis with TTL.

---

### 3. Unauthenticated State-Mutation Endpoints

**Files:** `03 - API Reference/Payment API.md`, `03 - API Reference/AI API.md`, `03 - API Reference/Notification API.md`

**Findings:**

| Endpoint | Risk |
|----------|------|
| `POST /api/payment/decentralized/save` | Anyone can persist a Web3 payment record |
| `POST /api/payment/decentralized/update` | Anyone can update decentralized payment status/confirmations |
| `GET /api/payment/decentralized/history/:userId` | Anyone can read any user's payment history (privacy breach) |
| `POST /api/payment/shkeeper/create-test-payment` | Anyone can inject test payment records into production data |
| `POST /api/payment/decentralized/verify/:paymentId` | Anyone can trigger chain re-verification |
| `POST /api/payment/decentralized/verify-all-pending` | Anyone can trigger a global batch verification job |
| All AI endpoints (`/generate`, `/analyze`, `/translate`, `/assist`) | No caller identity; unlimited OpenAI cost abuse |
| Legacy notification router (`notification/routes.ts`) | Mounted without auth; accepts `?userId=` query parameter allowing notification read/modify for any user |

**Impact:** Data poisoning, privacy violations, and unbounded cost exposure.

**Required Fix:** Add Bearer JWT middleware to all endpoints above. Enforce ownership or admin-role checks on `:userId` parameterized endpoints.

---

### 4. Web3 Payment Verification Trusts the Wrong Data

**Files:** `04 - Flows/Payment Flow - DePay & Web3.md`

**Finding:** The verifier checks only `receipt.status === '0x1'`. It **does not** decode the `Transfer` event to verify:
- `to` address == `ESCROW_WALLET_ADDRESS`
- `value` >= expectedAmount (accounting for decimals)

**Impact:** A malicious actor can submit the hash of any successful transaction (e.g., a 0.01 USDT transfer to their own wallet) and the system will mark the payment as completed.

**Required Fix:** Decode the event logs; verify recipient, token contract address, and amount match the intent.

---

### 5. Three Mutually Incompatible Dispute Enum Sets

**Files:** `02 - Data Models/Dispute.md`, `03 - API Reference/Dispute API.md`, `04 - Flows/Dispute Flow.md`

**Finding:** The three documents describe three different `Dispute` systems:

| Source | Status Enum | Resolution Action Enum |
|--------|-------------|------------------------|
| **Data Model** | `pending`, `in_progress`, `waiting_response`, `resolved`, `rejected`, `closed` | `refund`, `replacement`, `compensation`, `warning_seller`, `ban_seller`, `no_action` |
| **API Reference** | `open`, `under_review`, `resolved_buyer`, `resolved_seller`, `closed` | `buyer`, `seller`, `split` |
| **Flow** | `pending`, `in_progress`, `resolved`, `closed` | `refund`, `partial`, `release`, `reject` |

**Impact:** The API cannot be implemented as documented against the data model. The request/response schemas for `POST /api/disputes/:id/resolve` are completely different between API (uses `decision`) and Flow (uses `action`).

**Required Fix:** Create a single source-of-truth enum set. Align all three documents (or generate API docs from the model). `ban_seller` also has no corresponding `User.status` value (`User.status` is `active | suspended | deleted`).

---

## 🟠 High Severity Issues

### 6. Payment Model Uses `Mixed` for Core Foreign Keys

**File:** `02 - Data Models/Payment.md`

`purchaseRequestId`, `sellerOfferId`, and `sellerId` are `Schema.Types.Mixed` (ObjectId *or* String) to support the template flow. This sacrifices all type safety, referential integrity, and indexing efficiency for the normal (non-template) payment path, which is the vast majority of transactions.

**Fix:** Use strict `ObjectId` refs for the standard path; store template linkage in a separate `metadata` field.

---

### 7. Broken Foreign Key References

**Files:** `02 - Data Models/PointTransaction.md`, `02 - Data Models/Chat.md`

- `PointTransaction.order` references an **`Order` model that does not exist** in any documented schema.
- `Chat.relatedTo.type` includes `Transaction`, but no `Transaction` model exists.

**Fix:** Remove or rename orphaned references. If `Order` is an internal alias, document it.

---

### 8. Delivery Confirmation Code Is Brute-Forceable

**Files:** `04 - Flows/Delivery Confirmation Flow.md`

The 6-digit code (`Math.floor(100000 + Math.random()*900000)`) has only 900,000 combinations. There is **no rate limiting** documented on verification attempts.

**Fix:** Add Redis-backed rate limiting (e.g., 5 attempts per 15 minutes per request). Consider increasing entropy or adding time-based invalidation.

---

### 9. Purchase Request Status Machine Is Inconsistent

**Files:** `02 - Data Models/PurchaseRequest.md`, `03 - API Reference/Marketplace API.md`, `04 - Flows/Purchase Request Flow.md`

Three different status enums:

| Source | Unique Values |
|--------|---------------|
| **Data Model** | `pending_payment`, `active`, `seller_paid` |
| **API** | `draft` |
| **Flow** | `finalized`, `archived` |

The flow also claims a backward transition `in_negotiation → received_offers` is valid, but states elsewhere that "progression is forward-only except into terminal status."

**Fix:** One canonical enum. Remove ghost states (`draft`, `finalized`, `archived`, `pending_payment`, `active`) or implement them consistently.

---

### 10. JWTs in `localStorage` with 7-Day Expiry

**Files:** `01 - Architecture/Security Architecture.md`

Access tokens are stored in `localStorage` (XSS theft vector) and expire in **7 days**. For a financial escrow platform, this is far too long. The docs admit the risk but only list secondary mitigations (CSP, audits).

**Fix:** Move tokens to `httpOnly` cookies with 15–60 minute expiry and implement a secure refresh-token rotation mechanism.

---

### 11. SHKeeper Webhook Swallows All Errors

**File:** `04 - Flows/Payment Flow - SHKeeper.md`

The webhook returns `202 Accepted` even on signature failures, DB errors, and unknown payments. Failures are silently swallowed with no dead-letter queue, retry mechanism, or alerting.

**Fix:** Differentiate `400` (client error, do not retry) from `500` (server error, retry). Log structured webhook failures to a DLQ or alerting channel.

---

### 12. Socket.IO Room Joining Is Client-Controlled

**Files:** `01 - Architecture/Real-time Layer.md`

Clients explicitly emit `join-user-room {userId}` with their own ID. The docs include a warning that `userId` arguments "are NOT trusted blindly" and add "(cite: needs verification in `socketService.ts`)." This is an explicit admission the authorization check may not be implemented. If missing, any authenticated user can subscribe to another user's private notifications.

**Fix:** Remove client-driven `join-user-room` events. The server should automatically join the socket to `user-{decoded.id}` immediately after handshake auth.

---

### 13. Rate Limiting Is Effectively Disabled

**Files:** `01 - Architecture/Backend Architecture.md`, `03 - API Reference/API Overview.md`

`express-rate-limit` is disabled by default. Protected paths are limited to auth OTP/resend and AI endpoints. Marketplace, payment, chat, file upload, and notification endpoints have **no documented rate limiting**.

**Fix:** Enable global rate limiting with tiered limits (stricter for auth/financial, moderate for chat/marketplace).

---

## 🟡 Medium Severity Issues

### 14. Architecture Claims Stateless, But Isn't

**Files:** `01 - Architecture/System Architecture.md`, `01 - Architecture/Backend Architecture.md`, `01 - Architecture/Real-time Layer.md`

- Claims backend is **stateless** (JWT-only, no sessions).
- Admits Redis stores **login-attempt lockout counters** (session state).
- Socket.IO requires **sticky sessions** for multi-node, but current infra is a single Docker host. Running `N=2` backend replicas would break real-time events.

**Fix:** Remove the "stateless" claim until auth state and Socket.IO are node-agnostic (Redis adapter + cookie-based sticky sessions).

---

### 15. Fictitious Dependencies

**Files:** `01 - Architecture/Frontend Architecture.md`, `01 - Architecture/Infrastructure.md`

- **Next.js 16** does not exist (latest stable is 15). Using an unverified framework version for a financial platform is high-risk.
- **Redis 8** (`redis:8-alpine`) does not exist (latest stable is 7.x).

**Fix:** Update docs to reflect actual tested versions.

---

### 16. Blog Post `viewsCount` Incremented on GET

**File:** `03 - API Reference/Blog API.md`

`GET /api/blog/posts/:slug` atomically increments `viewsCount`. GET requests should be idempotent and safe.

**Fix:** Move view counting to a `POST /api/blog/posts/:slug/view` beacon endpoint, or use an async analytics pipeline.

---

### 17. API Request/Response Fields Do Not Match Data Models

**File:** `03 - API Reference/*`

| API | Uses | Model Has |
|-----|------|-----------|
| Address (`POST /api/addresses`) | `fullName`, `street`, `postalCode`, `isPrimary` | `name`, `fullAddress`, `zipCode`, `primary` |
| Blog (`POST /api/blog/posts`) | `excerpt`, `isFeatured`, `videoUrl`, `metadata` | `description`, `featured`, `videos[]`, no `metadata` |
| Chat (`POST /api/chat`) | `title` | `name` |
| Chat message (`POST /api/chat/:id/messages`) | `type`, `replyToMessageId` | `messageType`, `replyTo` |
| Payment (multiple) | flat `amount: number` | nested `amount: { amount, currency }` |
| Notification (`POST /api/notifications`) | `body`, `type` (domain) | `message`, `type` (severity), `category` (domain) |
| User profile (`PUT /api/user/profile`) | `name` (alias for `profile.name`) | No `profile.name` field exists |
| Points (`POST /api/points/admin/add`) | `reason` | `description` (required) |

**Fix:** Align API specs to the data models, or vice versa, with a single source of truth.

---

### 18. Seller Can Update Price After Offer Acceptance

**File:** `04 - Flows/Negotiation Flow.md`

The flow admits: *"`updateOffer` does not enforce status... Current code allows the price change, which is dangerous post-payment."*

**Fix:** Reject `updateOffer` if `status !== 'pending'`.

---

### 19. Buyer Can Confirm Delivery Before Seller Ships

**File:** `04 - Flows/Delivery Confirmation Flow.md`

Preconditions list `payment`, `processing`, or `delivery`. The "manual fast-track" lets the buyer skip the code and confirm receipt at any time — including immediately after payment, before the seller acknowledges.

**Fix:** Restrict fast-track confirmation to status `delivery` only, or require admin override.

---

### 20. Payment `confirmed` Status Is a Ghost State

**Files:** `02 - Data Models/Payment.md`, `04 - Flows/Payment Flow - SHKeeper.md`

The model includes `confirmed` in `status`. The SHKeeper webhook maps `PAID` directly to `completed`, skipping `confirmed`. No automated flow appears to set it.

**Fix:** Remove `confirmed` from the enum, or document the transition that sets it.

---

### 21. `partial` Escrow State Does Not Exist in Model

**Files:** `04 - Flows/Escrow Flow.md`, `04 - Flows/Payment Flow - SHKeeper.md`, `02 - Data Models/Payment.md`

Both flows use `escrowState: "partial"` for overpayments. The `Payment` model enum is `funded | releasable | released | refunded | releasing | failed` — `partial` is absent.

**Fix:** Add `partial` to the model enum, or map overpayments to `funded` with a `overpaidAmount` metadata field.

---

### 22. `BlogPost.comments` Is Just a Number

**File:** `02 - Data Models/BlogPost.md`

There is no `Comment` model. The system counts comments but cannot store or retrieve actual comment content.

**Fix:** Implement a `Comment` collection, or remove the `comments` counter.

---

### 23. No Pagination on List-Oriented Endpoints

**File:** `03 - API Reference/*`

- `GET /api/marketplace/sellers`
- `GET /api/marketplace/purchase-requests/my`
- `GET /api/marketplace/purchase-requests/:id/offers`
- `GET /api/blog/posts/featured`
- `GET /api/points/leaderboard`
- `GET /api/users/contacts`

**Fix:** Add cursor- or offset-based pagination to all unbounded list endpoints.

---

### 24. Missing Array Defaults

**Files:** `02 - Data Models/*`

Across 5+ models, array fields (`offers[]`, `tags[]`, `attachments[]`, `evidence[]`, `timeline[]`, `participants[]`, etc.) have no default value. In Mongoose they default to `undefined`, causing runtime errors on `.push()` or `.length`.

**Fix:** Add `default: []` to all array fields.

---

### 25. Inconsistent Soft-Delete Patterns

**Files:** `02 - Data Models/*`

| Model | Pattern |
|-------|---------|
| User | `status: active / suspended / deleted` |
| BlogPost | `status: draft / published / archived` |
| RequestTemplate, Category, LevelConfig | `isActive` boolean |
| Dispute | `status` enum (no deleted state) |
| SellerOffer | `status` enum |

**Fix:** Standardize on one pattern (e.g., `status` enum with `deleted` or `archived`, plus `deletedAt` timestamp).

---

### 26. Frontend Docker Image Cannot Be Promoted Across Environments

**File:** `01 - Architecture/Frontend Architecture.md`

The frontend uses `process.env.NEXT_PUBLIC_API_URL`, which is baked at **build time**. The same Docker image cannot be promoted from dev → staging → prod without rebuilding.

**Fix:** Inject the API URL at runtime via a server-side config endpoint or an env-replacement script in the container entrypoint.

---

### 27. Watchtower Auto-Deploys with Zero Staging Gate

**File:** `01 - Architecture/Infrastructure.md`

Production auto-updates every 5 minutes on `latest` tag change with no health-check gate, blue/green rollout, or smoke test.

**Fix:** Implement a staging promotion pipeline: build → deploy to staging → smoke test → tag promote to `stable` → Watchtower watches `stable`, not `latest`.

---

## 🟢 Lower Severity / Polish Issues

### 28. Naming Inconsistencies

**Files:** `02 - Data Models/*`

- `PointTransaction.user` vs `*Id` suffix convention used everywhere else
- `User.referredBy` vs `referredById`
- `User.profile.phone` vs `phoneNumber` used in `Address` and `PurchaseRequest`
- `Chat.messages[].senderType` defaults to `User` (PascalCase) while 95% of enums use lowercase
- `Address.addressType` uses `Home` / `Office` / `Other` (PascalCase)
- `Chat.metadata.createdBy` lacks `Id` suffix
- `Dispute.resolution.resolvedBy` lacks `Id` suffix

### 29. Redundant / Derived Fields

**Files:** `02 - Data Models/PurchaseRequest.md`, `02 - Data Models/User.md`

- `PurchaseRequest.deliveryConfirmed` boolean + `deliveryConfirmedAt` — boolean is derivable
- `PurchaseRequest.deliveryInfo.deliveryCodeUsed` boolean — derivable from `deliveryCodeUsedAt`
- `User.points.total` — derivable from `available + used`; risks arithmetic drift
- `PurchaseRequest.rating` + `feedback` — duplicate the dedicated `Review` model (two sources of truth)

### 30. ER Diagram Errors

**File:** `02 - Data Models/Data Model Overview.md`

- `PURCHASE_REQUEST ||--o| REVIEW` implies max one review; the model allows many
- `CHAT ||--o{ DISPUTE` direction is reversed; a chat belongs to at most one dispute

### 31. Missing Audit Timestamps

**Files:** `02 - Data Models/*`

- `User` has `status: deleted` but no `deletedAt`
- `PurchaseRequest` has terminal states (`completed`, `seller_paid`, `cancelled`) but no `completedAt` / `cancelledAt`
- `Review` has `pending → published → rejected` workflow but no transition timestamps
- `Dispute` has `adminId` assignment but no `assignedAt`

### 32. Missing Constraints

**Files:** `02 - Data Models/*`

- `Dispute.purchaseRequestId` has no unique constraint (allows duplicate active disputes per request)
- `PurchaseRequest.deliveryInfo.deliveryCode` is not unique or sparse-unique across requests
- `Category.parentId` has no circular-reference guard
- `User.referredBy` can self-reference with no prevention
- `LevelConfig.discountPercent` has no upper bound (`max: 100`)
- `RequestTemplate.expiresAt` can be created in the past

---

## Cross-Cutting Themes

1. **Documentation Drift:** The four primary document layers (Models, API, Flows, Architecture) describe different versions of the same system. The most egregious example is the `Dispute` entity, which has three incompatible definitions.
2. **Security Theater:** Several sections describe security measures (CSP, audits, future ClamAV) while fundamental flaws (localStorage tokens, unauthenticated endpoints, stubbed crypto) remain unaddressed.
3. **Ghost States:** Multiple status enums contain values that no automated flow sets (`confirmed`, `partial`, `finalized`, `archived`, `active` for SellerOffer).
4. **Operational Fragility:** The production topology is a single Docker host with automatic `latest` deployment. There is no HA, no staging gate, and no upload storage that can survive horizontal scaling (uploads are host bind-mounts).

---

## Recommendations (Priority Order)

1. **Fix the Dispute ↔ Escrow race condition** immediately. A `disputed` state must block all releases.
2. **Align all status enums** across Models, API, and Flows. Create a single source-of-truth document.
3. **Harden Passkey authentication** before any production use.
4. **Add authentication and ownership checks** to all financial endpoints.
5. **Fix Web3 verification** to decode and validate `Transfer` event parameters.
6. **Enable rate limiting globally**, with stricter tiers for auth and financial paths.
7. **Implement idempotency keys** for dispute creation, payment verify, and payout creation.
8. **Protect `/uploads`** with signed URLs or session-based auth for sensitive attachments.
9. **Fix SHKeeper webhook error handling** — return proper status codes and log to a DLQ.
10. **Sanitize logs** to remove plaintext verification/reset codes.