Skip to main content
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:
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:

​
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:

​
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. 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.