> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coverfi.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Backend operations

> API hardening, health checks, privacy boundaries, and deployment notes

The `server` workspace runs the Express API for market data, CoverFi AI, health checks, legal/privacy notices, status endpoints, partner APIs, protected invoices, webhooks, optional KYC/KYB hooks, and compatibility routes. Username ownership, username payment execution, protection creation, settlement, payout claims, principal withdrawal, payment resolution, and receipt anchoring are contract/client flows.

The backend is not an authoritative product database. Private profile, payment, receipt, draft, and AI records live in wallet-unlocked encrypted browser storage. Protocol state lives on Stellar/Soroban.

## Security controls

Current controls:

* JSON body size limit of `32kb`.
* Structured request logs with request IDs.
* Wallet addresses and transaction hashes redacted from standard request paths.
* Wallet identifiers in logs and rate limits are HMAC pseudonyms.
* Route-specific rate limits.
* Schema validation for wallets, receipts, legal notices, account compatibility routes, and AI prompts.
* Wallet-signed challenge/session authentication for private wallet resources.
* Session issuer, audience, terms version, token ID, expiry, timing-safe HMAC validation, and in-memory revocation.
* Local CORS support for the main app, preview app, and protocol monitor.

Production should use a stable `AUTH_SESSION_SECRET`, a stable `PRIVACY_HMAC_SECRET`, shared session revocation storage, and distributed rate limits. Local development may use process-local fallback secrets, but that invalidates sessions on restart.

## Private route authentication

Private routes require:

```txt theme={null}
X-CoverFi-Wallet-Address: <stellar-public-key>
Authorization: Bearer <signed-session-token>
```

Clients obtain a token with:

1. `POST /api/auth/challenge`
2. Wallet signs the returned challenge message.
3. `POST /api/auth/session`

Clients may revoke the current token with:

```txt theme={null}
POST /api/auth/session/revoke
```

## Storage boundary

The following compatibility endpoints do not persist product records server-side:

* `POST /api/legal/accept`
* `GET /api/account/:walletAddress`
* `PUT /api/account/:walletAddress`
* `POST /api/payments/save`
* `GET /api/payments/:username`
* `POST /api/receipts/save`
* `GET /api/privacy/export/:walletAddress`
* `DELETE /api/privacy/:walletAddress`
* `GET /api/ai/chat/:walletAddress`

They return explicit local-storage or on-chain boundaries so old clients fail safely instead of writing linked wallet records to a backend database.

## Health checks

`GET /api/health` returns:

* `ok`
* `aiConfigured`
* `accountStorage`
* `receiptStorage`
* `analyticsWalletStorage`
* `backendProductDatabase`
* `termsVersion`

Deployment platforms should use this route as the readiness probe.

## Protocol status endpoints

The backend exposes read-only status routes for public monitoring:

* `GET /api/status/contracts`
* `GET /api/status/oracle`
* `GET /api/status/reserve`
* `GET /api/status/atlassian`
* `GET /api/status/proof-of-reserve`

The reserve endpoint reads V2 pool state, collateral, locked liabilities, available liquidity, utilization, and provider NAV. The oracle endpoint reads latest/fresh observations, reports age, and includes a volatile 24-hour runtime observation buffer. The Atlassian route includes public incident and scheduled-maintenance history when the configured Statuspage exposes it.

`/api/status/proof-of-reserve` is intentionally testnet-only. It returns `not_configured` until a separate deployment-held Ed25519 signer is set through `TESTNET_RESERVE_ATTESTATION_SECRET` (and optionally its matching public key through `TESTNET_RESERVE_ATTESTATION_PUBLIC_KEY`). The secret is never returned; a configured endpoint returns a canonical payload, signer public key, and signature. This is an operational testnet attestation, not an audit or a guarantee of payout.

## Protocol monitor

The `coverfi-monitor` workspace is a read-only Vite app for local operations. It reads:

* `GET /api/health`
* `GET /api/legal/status`
* `GET /api/prices`
* `GET /api/portfolio/markets`
* Backend oracle and reserve status endpoints.
* Soroban contract getters for engine config, reserve pool state, oracle observations, and V2 quote checks.

Default local URL:

```txt theme={null}
http://localhost:5175
```

## Environment variables

Keep these server-side only:

* `AUTH_SESSION_SECRET`
* `PRIVACY_HMAC_SECRET`
* `AZURE_OPENAI_API_KEY`
* `AZURE_OPENAI_ENDPOINT`
* `UPSTASH_REDIS_REST_TOKEN`
* `STATUSPAGE_API_KEY`
* `DATABASE_URL`
* `DIDIT_API_KEY`
* `DIDIT_WEBHOOK_SECRET`
* `PARTNER_API_KEY_PEPPER`

Frontend-safe values:

* `VITE_API_BASE_URL`
* Stellar public contract IDs.
* Public asset contract IDs and issuer IDs.
* Public status/monitor URLs.

## Deployment checklist

1. Set stable auth and privacy HMAC secrets.
2. Configure trusted proxy hops for the deployment platform.
3. Configure contract IDs and public source account for read-only status calls.
4. Configure Azure OpenAI only if AI support should be enabled.
5. Configure Upstash or another distributed rate-limit backend for production scale.
6. Run `npm run check`, `npm test`, and frontend builds.
7. Verify `/api/health`, `/api/status/oracle`, and `/api/status/reserve`.
8. Verify the monitor can read contract and backend state.

## Partner API versions

The backend currently contains two partner API surfaces.

| API surface         | Status                                                                                                                                 | SDK                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `/api/partner/v1/*` | Modern partner API for quotes, positions, assets, pricing, usage, claims, payouts, receipts, webhooks, sessions, and signing payloads. | `packages/coverfi-sdk` |
| `/api/partners/*`   | Legacy/simple partner API retained for compatibility and early sandbox flows.                                                          | `partner-sdk`          |

New technical reviewers should evaluate the modern `/api/partner/v1/*` API first. Production work should align scopes, idempotency, webhook validation, and rate limits across the surviving API surface before mainnet scale.