Merge branch 'staging' into feature/508-approve-recovery-admin-action

Author: Jambox11

.env.example

@@ -31,6 +31,12 @@ WALLET_ENCRYPTION_KEY=your-secret-encryption-key-min-32-chars
 # Mainnet:  https://horizon.stellar.org
 # ------------------------------------------------------------
 STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
+STELLAR_NETWORK=TESTNET
+STELLAR_HORIZON_MAX_RETRIES=3
+STELLAR_HORIZON_RETRY_BACKOFF_MS=500
+STELLAR_HORIZON_RETRY_JITTER_MS=250
+BALANCE_STALE_THRESHOLD_MS=300000  # 5 minutes
+# Webhook Configuration
 
 # ------------------------------------------------------------
 # Balance Indexer

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - staging
+  pull_request:
+    branches:
+      - main
+      - staging
+
+jobs:
+  test:
+    name: Build and test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js (enable pnpm cache)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate Prisma client
+        run: pnpm prisma:generate
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Test
+        run: pnpm test

.github/workflows/migrate.yml

@@ -8,10 +8,12 @@ on:
     paths:
       - 'prisma/migrations/**'
       - 'prisma/schema.prisma'
+      - '.github/workflows/migrate.yml'
   pull_request:
     paths:
       - 'prisma/migrations/**'
       - 'prisma/schema.prisma'
+      - '.github/workflows/migrate.yml'
 
 jobs:
   migrate:
@@ -40,12 +42,17 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: latest
+          version: 9
 
-      - name: Setup Node.js
+      - name: Setup Node.js (enable pnpm cache)
         uses: actions/setup-node@v4
         with:
           node-version: '22'

README.md

@@ -33,6 +33,8 @@ It handles wallet creation, transaction orchestration, fee sponsorship, and on-c
 
 ## API Endpoints
 
+All routes below are served under the `/v1` prefix (e.g. `GET /v1/health`). See [docs/API-VERSIONING.md](docs/API-VERSIONING.md) for the versioning strategy.
+
 ### Health & Monitoring
 
 #### `GET /health`
@@ -391,8 +393,93 @@ The middleware is registered in `src/main.ts` and runs for all incoming requests
 
 ---
 
+## Balance Indexer
+
+The balance indexer provides fast, cached balance reads without hitting Stellar Horizon on every request.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  BalanceIndexerService                  │
+│                                                         │
+│  getBalance()          → cached read from DB            │
+│  getAllBalances()       → cached reads from DB           │
+│  syncWalletBalances()  → fetch Horizon → upsert DB      │
+│  reconcileBalance()    → compare DB vs Horizon          │
+│  reconcileAllBalances()→ full sweep across active wallets│
+│  syncAllWallets()      → manual full sync trigger       │
+└──────────┬──────────────────────┬───────────────────────┘
+           │                      │
+  ┌────────▼────────┐   ┌────────▼──────────────┐
+  │  PrismaService  │   │  StellarHorizonService │
+  │  (PostgreSQL)   │   │  (Horizon REST API)    │
+  └─────────────────┘   └────────────────────────┘
+```
+
+### Stale Detection
+
+Balances older than `BALANCE_STALE_THRESHOLD_MS` (default 5 minutes) trigger an async background refresh on the next read. The stale value is still returned immediately so callers are never blocked.
+
+### Mismatch Handling
+
+On reconciliation, if the indexed balance differs from the on-chain balance, the indexed value is corrected and `mismatchDetectedAt` / `reconciliationAttempts` are updated for observability.
+
+### Sync Job Tracking
+
+All sync and reconciliation operations create a `BalanceSyncJob` record for audit and observability.
+
+### API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/balances/wallet/:walletId` | Get cached balances (add `?assetType=NATIVE` for single asset) |
+| `POST` | `/balances/wallet/:walletId/sync` | Manually trigger sync for a single wallet |
+| `POST` | `/balances/sync-all` | Manually trigger full sync for all active wallets (admin) |
+| `POST` | `/balances/wallet/:walletId/reconcile` | Reconcile wallet balance with on-chain state |
+| `POST` | `/balances/reconcile-all` | Reconcile all balances (admin) |
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BALANCE_STALE_THRESHOLD_MS` | `300000` | Age (ms) after which a balance is considered stale |
+| `STELLAR_HORIZON_URL` | `https://horizon-testnet.stellar.org` | Stellar Horizon API URL |
+
+---
+
+## Webhooks
+
+Webhooks allow your application to receive real-time notifications when events occur in Mux Protocol.
+
+### Endpoint CRUD
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/webhooks/endpoints` | Register a new webhook endpoint |
+| `GET` | `/webhooks/endpoints/project/:projectId` | List endpoints for a project |
+| `GET` | `/webhooks/endpoints/:id` | Get a specific endpoint |
+| `PUT` | `/webhooks/endpoints/:id` | Update an endpoint |
+| `DELETE` | `/webhooks/endpoints/:id` | Delete an endpoint |
+| `POST` | `/webhooks/endpoints/:id/rotate-secret` | Rotate signing secret |
+| `GET` | `/webhooks/endpoints/:id/deliveries` | Get delivery history |
+| `POST` | `/webhooks/process-deliveries` | Manually process pending deliveries (admin) |
+
+### Payload Signing
+
+All webhook payloads are signed with HMAC-SHA256. The `X-Webhook-Signature` header has format `t=<timestamp>,v1=<signature>`. Verify with the secret returned at endpoint creation.
+
+### Supported Events
+
+`wallet.created`, `wallet.activated`, `wallet.suspended`, `wallet.rotated`, `transaction.created`, `transaction.pending`, `transaction.confirmed`, `transaction.failed`, `balance.updated`, `balance.low`, `user.created`, `user.updated`
+
+---
+
 ## Wallets API
 
+Endpoint semantics, idempotency, lifecycle events, dependency retries, and
+metrics are documented in [docs/WALLET-API.md](docs/WALLET-API.md).
+
 - `POST /wallets` - create wallet
 - `GET /wallets` - list all wallets
 - `GET /wallets/user/:userId` - list wallets by userId (#189)
@@ -433,4 +520,3 @@ Testing
 
 - Unit tests are under `src/**/*spec.ts`.
 - E2E tests are under `test/` and use Jest + Supertest.
-

TEST_VERIFICATION_GUIDE.md

@@ -33,6 +33,8 @@ These test files were updated to use the new `/v1` prefix:
 
 4. **test/wallets.e2e-spec.ts**
    - Tests wallet endpoint: `GET /v1/wallets/protected`
+   - Tests wallet creation and wallet status paths
+   - Verifies `x-request-id` propagation in headers
    - Verifies API key authentication with prefix
 
 ### New Test File

docs/API-VERSIONING.md

@@ -0,0 +1,50 @@
+# API Versioning Strategy
+
+This document describes how the Mux backend versions its public HTTP API.
+
+## Current approach: URI path versioning
+
+All routes are served under a global `/v1` prefix, applied once in `src/main.ts`:
+
+```ts
+app.setGlobalPrefix('v1');
+```
+
+Individual controllers (e.g. `@Controller('auth')`, `@Controller('wallets')`)
+declare their resource path only; the version prefix is applied globally so
+every route is automatically namespaced (`/v1/auth/authenticate`,
+`/v1/wallets`, etc.). Requests made without the `/v1` prefix return `404 Not
+Found` — there is no unversioned fallback.
+
+## Why URI versioning
+
+- **Explicit and cache-friendly**: the version is visible in the URL, in logs,
+  and in reverse-proxy/CDN routing rules, without relying on a header that
+  intermediaries may strip.
+- **Simple for consumers**: partners and the frontend hard-code a base URL
+  (e.g. `https://api.mux.dev/v1`) rather than needing to set a custom header
+  on every request.
+- **Matches existing NestJS conventions** in this repo — a single
+  `setGlobalPrefix` call versions every controller without per-route
+  decorators.
+
+## Introducing a breaking change (`/v2`)
+
+When a change is not backwards compatible:
+
+1. Add the new/changed controllers under a `v2` path (NestJS's built-in
+   [URI versioning](https://docs.nestjs.com/techniques/versioning) via
+   `app.enableVersioning({ type: VersioningType.URI })` can be adopted at that
+   point to run `v1` and `v2` controllers side by side).
+2. Keep `/v1` serving the previous behavior until consumers have migrated.
+3. Announce the deprecation window for `/v1` in release notes before removal.
+
+## Non-breaking changes
+
+Additive changes (new endpoints, new optional request/response fields) ship
+directly under the current `/v1` prefix — no new version is required.
+
+## Health and monitoring endpoints
+
+`/v1/health` and `/v1/ready` follow the same prefix as every other route, so
+uptime checks and readiness probes must be configured with the `/v1` path.

docs/AUTH-FEATURE-FLAGS.md

@@ -0,0 +1,16 @@
+# Auth Feature Flags
+
+This document summarizes feature flags added for the auth and session endpoints.
+
+- `FEATURE_AUTH_API` (boolean, default: false)
+  - When `true`, the auth endpoints (`POST /auth/authenticate`, `GET /auth/sessions`, `GET /auth/validate/:authId`) are enabled.
+  - When `false` or unset, the endpoints return HTTP 403 (Forbidden) with message: "Feature is not available at this time. (Flag: auth_api)".
+
+Notes:
+- The flag is implemented via the existing `FeatureFlagGuard` and the `@FeatureFlag('auth_api')` decorator on the `AuthOrchestratorController`.
+- The guard reads environment variables using the existing pattern: `FEATURE_<FLAG_NAME>=true|false` (e.g. `FEATURE_AUTH_API=true`).
+- Existing unit tests for `FeatureFlagGuard` cover enabled/disabled behavior. The auth controller tests were adjusted to override the guard for isolation.
+
+Operational guidance:
+- To enable auth in runtime, set `FEATURE_AUTH_API=true` in the configuration used by the service (env, k8s secret, etc.).
+- Ensure any API gateway or routing changes are coordinated when toggling this flag in production to avoid unexpected client errors.

docs/WALLET-API.md

@@ -0,0 +1,62 @@
+# Wallet API behavior
+
+All Wallet API routes require a valid API key and are rate-limited. The API
+never returns encrypted key material on read endpoints. The only operation
+that returns a `privateKey` is a successful first wallet-creation response;
+clients must consume it immediately and must not expect it to be replayed.
+
+## Endpoints
+
+| Method | Route | Behavior |
+| --- | --- | --- |
+| `POST` | `/wallets` | Creates one active wallet per user/network pair. Duplicate user/network requests return `409`. |
+| `GET` | `/wallets` | Lists wallets. Supports `userId`, `network`, `status` filters and `limit`/`offset` pagination (default `limit=20`, max `100`). Returns `{ data, total, limit, offset, hasMore }`. |
+| `GET` | `/wallets/:id` | Returns a wallet or `404`. |
+| `GET` | `/wallets/:id/status` | Returns lifecycle status without decrypting the private key. |
+| `PATCH` | `/wallets/:id` | Updates wallet lifecycle status. |
+| `PATCH` | `/wallets/:id/activate` | Activates a `PROVISIONING` wallet. Any other current state is rejected. |
+| `DELETE` | `/wallets/:id` | Removes a wallet record. |
+| `POST` | `/wallets/orchestration/create` | Runs the provisioning flow and accepts an optional `idempotencyKey`. |
+| `GET` | `/wallets/orchestration/user/:userId/:network` | Returns the wallet for a user/network pair or `404`. |
+| `GET` | `/wallets/orchestration/validate/:userId/:network` | Reports whether a new wallet may be created. |
+
+`network` is `TESTNET` or `MAINNET`. `POST /wallets/orchestration/create`
+creates a wallet as `PROVISIONING`, then promotes it to `ACTIVE` in the same
+database transaction. Testnet funding is best effort: a disconnected or
+failed Friendbot call is logged and does not undo a committed wallet.
+
+## Idempotency
+
+For orchestration creation, an `idempotencyKey` is scoped to one
+`userId`/`network` operation for 24 hours.
+
+- Repeating the same operation returns the cached wallet result with
+  `privateKey: ""`.
+- Reusing the key for another user or network returns `409`.
+- Expired keys are treated as new requests.
+
+## Lifecycle events
+
+The API emits webhook domain events after state has been durably persisted:
+`wallet.created`, `wallet.activated`, `wallet.suspended`, and
+`wallet.rotated`. Event dispatch is asynchronous; a webhook outage is logged
+but never changes the response or rolls back wallet state. Creation events
+from the orchestration endpoint are emitted only after its database
+transaction commits, and are not repeated for idempotency replays.
+
+## Dependency retries and metrics
+
+Before any wallet write, transient key-management and testnet-funding failures
+are retried with capped exponential backoff. Invalid requests and non-transient
+4xx responses are not retried. Configure this behavior with:
+
+| Variable | Default |
+| --- | --- |
+| `WALLET_API_RETRY_MAX_ATTEMPTS` | `3` |
+| `WALLET_API_RETRY_BASE_DELAY_MS` | `100` |
+| `WALLET_API_RETRY_MAX_DELAY_MS` | `2000` |
+
+Wallet operations write structured `[wallet-api-metrics]` log records with
+operation, outcome, duration, and network. Metrics intentionally exclude user
+and wallet identifiers so they are safe to aggregate as low-cardinality
+telemetry.