Defense-in-Depth to Production

Status: Design — pre-launch hardening baseline
Owner: software-architect
Date: 2026-07-11 UTC
Pair review: security-agent (adversarial review follows this doc)
Related: docs/plan-to-production.md (parallel PM doc); ADR-0138 (idempotency); ADR-0137 (wp-config-svc); ADR-0130/0131 (agent identity); docs/architecture/customer-audit-unified/design.md
Hardening epic: #94 (Production Release v1.0)

1. Preamble — design invariants this doc enforces

Every control described here is subordinate to these non-negotiable platform invariants. A design that requires violating any of them is not a design; it is a conflict that must be escalated.

• I-1 No stored credentials. No auth token, passkey secret, OAuth credential, or broker API key is ever persisted in a form that can be replayed.
• I-2 Passkeys / WebAuthn only. No password column exists or ever will. No SMS OTP. No email OTP as a primary factor.
• I-3 Paper-first gate. Live-trading code paths require the graduation gate or explicit per-flow override. The gate cannot be short-circuited by an idempotency replay, a support token, or a feature flag misconfiguration.
• I-4 Audit trail. Every state change affecting money, permissions, or data access is written to the append-only audit chain with HMAC-KMS integrity, before the response is returned.
• I-5 Credentials in infra. API keys live in Infisical vault or AWS SSM. Never in application code, logs, or Heroku config set without masking.
• I-6 GDPR by default. Retention limits, DSR (access / portability / erasure / rectification), DPA-ready logging, 72-hour breach notification clock.
• I-7 Defense-in-depth. No single control failure is fatal. Every surface must have at least two independent controls; where only one layer currently exists, that is a hardening card.

2. Per-surface threat model

2.1 Order-firing / trading path

Assets: paper positions, paper cash balance, audit chain, live broker credentials (future).

Trust boundary: Authenticated Raptor session (raxx_session cookie) → session_auth → require_session → optional idempotency_key decorator → handler → MbtFillEngine → paper_orders table → audit write.

Order-firing path deepest treatment — see Section 3.

2.2 AuthN / AuthZ surface

Assets: WebAuthn credential bindings, session tokens, recovery flow, RBAC role grants.

Trust boundary: Browser → Cloudflare WAF → Raptor /api/auth/* → py-webauthn → webauthn_credentials + sessions tables.

Internal machine-auth paths (/api/internal/*):
Multiple auth patterns co-exist: HMAC token (FreeScout webhook), Bearer token (WAF events), X-Admin-Service-Token (jobs, merges). The X-Admin-Service-Token is a single shared secret. If it leaks, all /api/internal/jobs/* and /api/internal/merges* routes are compromised. No per-route isolation or per-caller identity today. See HC-AUTH-3.

2.3 Billing / payments

Assets: Stripe checkout sessions, Apple IAP receipts, subscription state, billing action log.

2.4 Edge / perimeter

Assets: Heroku origin URL, vault.raxx.app, ci.moosequest.net, CI pipeline config.

2.5 Secrets — Infisical vault + SSM + agent identity

Assets: All service credentials (Stripe, Postmark, Heroku, Apple IAP, broker OAuth), GitHub App private keys, agent machine identities.

2.6 Data — audit log, idempotency_keys, GDPR

Assets: customer_audit_events, audit_log, idempotency_keys, PII in users, shadow tables, GDPR DSR machinery.

3. Order-firing path — deep threat model

The idempotency mechanism is the primary correctness control on the path that moves paper money. The following findings represent the highest-confidence attack or failure vectors.

3.1 In-flight race: business logic success + UPDATE failure (double-fire)

Threat: Handler executes successfully — paper_orders row created, audit written — but the UPDATE SET status='completed' fails before commit (DB connection lost, gunicorn worker killed at exactly the wrong moment).

Effect: Row stays in_flight. After 30 seconds, a retry sees stale_in_flight → 409 with no stored response. User retries with a new idempotency key → second order placed. This is a double-fire on the paper portfolio.

Why the 30s stale detection doesn't fully protect here: The stale detection prevents re-execution via the same key. It does not prevent the user from issuing a new key after seeing the 409. There is no "check your orders before retrying" signal in the current 409 response body.

Hardening (HC-ORD-2): 1. The handler's side effects (paper_orders INSERT, audit write) and the idempotency UPDATE must be wrapped in the same DB transaction. If the UPDATE fails, the handler's side effects roll back. At-most-once is then guaranteed by the DB commit boundary. 2. If transaction wrapping is not possible for a specific handler (e.g., it calls an external broker), add a pre-commit idempotency check: before executing the external call, mark status='executing' (new intermediate state) with a savepoint; on external call success, complete the UPDATE in the same transaction block. 3. The stale_in_flight 409 response body must include "check_order_status": true to prompt the client to inspect GET /api/trading/orders before retrying with a new key. 4. Document as a v1 known limitation in the trading panel UI.

3.2 Request-hash normalization undefined for edge inputs

Threat: get_json(silent=True) returns None on malformed body or wrong Content-Type. The current spec calls for SHA256(sorted_json_body) but does not define behavior when the body is None.

Effect A (real risk): None body hashes to a constant string (e.g., SHA256("null")). A legitimate retry after a timeout that produced no body will hash to that constant and trigger a 422 body-mismatch against the original non-null hash. Client retries with a new key → double-fire.

Effect B (security): Two requests with empty bodies produce the same hash regardless of intent, collapsing them to one idempotent operation. Harmless for order endpoints (an order with no body should be rejected by the handler before idempotency anyway), but worth documenting.

Hardening (HC-ORD-1): Before computing the hash, validate body = request.get_json(silent=True) is a non-None dict. If not, return 400 before the idempotency check runs. Define canonical serialization as json.dumps(body, sort_keys=True, separators=(',', ':'), ensure_ascii=True). Add an integration test that submits the same body with different whitespace and confirms 200+replay on retry.

3.3 Live-mode gate: FLAG_LIVE_MODE_RBAC_GATE off by default

Threat: The @require_live_mode_role decorator is a transparent passthrough when FLAG_LIVE_MODE_RBAC_GATE=0. The flag is off in the current default configuration. If a live broker credential were accidentally activated, any authenticated user could reach the live order path with no RBAC gate.

Assessment: The paper-first graduation gate (paper_profitable_gate_met) is a separate mechanism checked inside the handler. However, it is distinct from the RBAC gate and may have its own failure modes. Two independent gates are stronger than one.

Hardening (HC-ORD-4): FLAG_LIVE_MODE_RBAC_GATE=1 must be set on both staging and prod before any live broker credential is activated. This is a pre-launch configuration requirement, not a code change.

3.4 Replay after live-mode access revocation

Threat: User is granted live-mode access, places a live order (key K), access is revoked. User retries with key K within the 24h TTL — the stored replay response is returned. The live order confirmation is replayed without re-checking current access.

Assessment: This is correct behavior within the design. The replay returns a stored response from an execution that was authorized at the time. The 24h window is the exposure period after revocation.

Hardening (HC-ORD-5): On live_mode_grants revocation, proactively set expires_at = now() on all idempotency_keys rows for that user on POST /api/trading/orders and POST /api/trading/orders/ic. This collapses the replay window to zero on revocation rather than waiting for TTL expiry.

3.5 Decorator stack ordering: missing runtime assertion

Threat: If @idempotency_key is applied before @require_session, g.current_user_id is not set. The middleware falls back to scope_user_id = NULL, collapsing all service-call keys into the same namespace. Two users with key "abc" on the same endpoint would conflict.

Hardening (HC-ORD-6): Add a runtime assertion in the decorator: if g.current_user_id is not set when fail_closed=True, raise RuntimeError("idempotency_key applied before require_session"). This surfaces misconfiguration at development time (Sentry alert, test failure) rather than silently in production.

4. Residual-risk register

Must close before launch (7 items)

Accept for v1 (9 items)

5. Security considerations — GDPR checklist

• PII in this design: This is an architecture doc only. Per-surface PII handling is in source designs (auth.md §8, customer-audit-unified/design.md §I-3, [ADR-0138](https://internal-docs.raxx.app/architecture/adr/0138-idempotency-key-mechanism.html) §Security).
• Breach notification: The 72-hour Art. 33 automation is triggered by audit_log writes with action='breach.*'; documented in docs/agents/security_response.md. This doc does not change that path.
• Kill-switches per surface: MBT_NEW_ORDERS_DISABLED (order path) · AUTH_DISABLED=1 (auth) · FLAG_BILLING_SUMMARY_API=0 (billing) · FLAG_ENFORCE_CF_ORIGIN=0 (edge) · per-identity Infisical revocation < 60s (secrets).
• No new secrets introduced by this design document.

6. Open questions (operator decisions required before sub-cards are claimed)

1. HC-AUTH-1 timing: Raptor is currently on 1 dyno. At what user volume does scaling trigger? This determines whether the Postgres challenge store migration is pre-launch or post-launch.
2. HC-EDGE-2 Woodpecker PR secret scope: Does the current Woodpecker configuration inject production secrets into PR-context pipeline runs? sre-agent to verify before launch.
3. HC-DATA-1 role confirmation: Is the Heroku DATABASE_URL credential used by the running Raptor dyno the raptor_app role or the owner role? sre-agent to run SELECT current_user; on prod DB.
4. response_body encryption (ADR-0138 OQ2): Encrypt idempotency_keys.response_body at column level (pgcrypto), or accept DB-level readers see order details? Operator decision required before Wave 3 rollout.