verification/api/tests/api_verification_inventory.md

# Scientific Verification Inventory — API Subsystem

This document provides a comprehensive scientific audit inventory of the API implementation for the Privacy-Preserving Cross-Bank Fraud Detection platform. It systematically analyzes every component, endpoint specification, request/response contract, invariant, risk, edge case, engineering claim, and appropriate verification methodology.

---

1. Middleware & System Infrastructure Inventory

1.1 Global Exception Handler (RFC 7807)

• Component: app.main.global_exception_handler
• Purpose: Ensures all unhandled runtime exceptions return structured JSON formatted per RFC 7807 (application/problem+json) when requested or as standard JSON error responses.
• Endpoint Specification: Global error interceptor across all HTTP endpoints.
• Request/Response Contract:
  • Request: Any failing HTTP request.
  • Response: HTTP 500 Internal Server Error, Content-Type: application/problem+json or application/json.
  • Body: {"type": "https://cfi-platform.org/errors/<ExcName>", "title": "Internal Server Error", "status": 500, "detail": "<msg>", "instance": "<path>"}.
• Expected Invariant: Unhandled exceptions NEVER leak plain-text stack traces or non-JSON responses.
• Possible Implementation Risks: Exception string details might inadvertently leak internal variable names if not sanitized.
• Edge Cases: Exceptions raised during streaming responses or WebSocket handshakes after headers are sent.
• Engineering Claim Being Made: "All unhandled runtime errors conform to RFC 7807 problem details contracts without exception."
• Appropriate Verification Methodology: Adversarial property testing injecting unexpected runtime exceptions across routes.

---

1.2 Content-Type Enforcement Middleware

• Component: app.main.ContentTypeMiddleware
• Purpose: Protects mutating endpoints (POST, PUT, PATCH) by enforcing Content-Type: application/json.
• Endpoint Specification: Global middleware targeting mutating routes (excluding exempt paths like /docs, /openapi.json, /ws/).
• Request/Response Contract:
  • Request: Mutating request with non-JSON or missing Content-Type.
  • Response: HTTP 415 Unsupported Media Type, Content-Type: application/problem+json.
  • Body: {"type": ".../UnsupportedMediaType", "title": "Unsupported Media Type", "status": 415, "detail": "...", "received": "<ct>", "instance": "<path>"}.
• Expected Invariant: Non-JSON bodies sent to mutating endpoints are rejected at the edge before route handlers execute.
• Possible Implementation Risks: Overly strict matching breaking multipart form-data file uploads if paths are not exempted.
• Edge Cases: Binary payloads (application/octet-stream), empty bodies, text/xml, application/x-www-form-urlencoded.
• Engineering Claim Being Made: "Mutating endpoints strictly reject unsupported media types with HTTP 415 before payload parsing."
• Appropriate Verification Methodology: Fuzz testing with arbitrary binary and non-JSON content-type headers.

---

1.3 Distributed W3C Trace Context Middleware

• Component: app.main.W3CTraceContextMiddleware
• Purpose: Implements OpenTelemetry W3C traceparent specification for cross-service distributed tracing.
• Endpoint Specification: Applied to all incoming HTTP requests.
• Request/Response Contract:
  • Request Header: traceparent: 00-{trace_id}-{span_id}-{flags} (optional).
  • Response Header: traceparent: 00-{trace_id}-{span_id}-01.
• Expected Invariant: Every HTTP response carries a valid, deterministic W3C traceparent header.
• Possible Implementation Risks: Malformed incoming traceparent headers causing regex/split indexing errors.
• Edge Cases: Headers with invalid version digits, incorrect hex lengths, or empty strings.
• Engineering Claim Being Made: "All API responses carry W3C-compliant distributed trace context headers."
• Appropriate Verification Methodology: Header injection testing with valid and malformed traceparent strings.

---

1.4 API Version Lifecycle Middleware

• Component: app.main.APIVersionLifecycleMiddleware
• Purpose: Attaches RFC 8594 Deprecation and Sunset headers along with X-API-Version to support version governance.
• Endpoint Specification: Global HTTP response modifier.
• Request/Response Contract:
  • Response Headers: X-API-Version: v1, Deprecation: <HTTP-date> (optional), Sunset: <HTTP-date> (optional).
• Expected Invariant: Every response header contains explicit API version identification.
• Possible Implementation Risks: Unset deprecation date configurations omitting RFC headers.
• Edge Cases: CORS preflight OPTIONS requests needing header exposure in Access-Control-Expose-Headers.
• Engineering Claim Being Made: "All API endpoints explicitly declare their version lifecycle metadata via RFC 8594 headers."
• Appropriate Verification Methodology: HTTP response header assertion across GET/POST/OPTIONS calls.

---

1.5 In-App mTLS Peer Verification Middleware

• Component: app.main.MTLSVerificationMiddleware
• Purpose: Validates X.509 client certificate fingerprints and CRL revocation status at the application layer.
• Endpoint Specification: Applied to sensitive banking routes (/api/v1/predict, /api/v1/training, /api/v1/banks).
• Request/Response Contract:
  • Request Headers: X-SSL-Client-Verify: SUCCESS, X-Client-Cert-SHA256: <fingerprint>.
  • Response: HTTP 403 Forbidden if verification fails or certificate fingerprint is revoked in CRL.
• Expected Invariant: Requests with invalid or revoked client certificate fingerprints are denied access.
• Possible Implementation Risks: Mismatch between proxy header naming and application middleware extraction keys.
• Edge Cases: Revoked serial numbers present in CRL, header spoofing when proxy is bypassed.
• Engineering Claim Being Made: "Sensitive banking routes enforce in-app mTLS peer validation against active CRLs."
• Appropriate Verification Methodology: Security audit tests sending revoked and unverified certificate headers.

---

1.6 L7 Application-Layer DDoS Protection Middleware

• Component: app.main.DDoSProtectionMiddleware
• Purpose: Implements sliding-window token bucket IP rate limiting for burst attack detection and flood prevention.
• Endpoint Specification: Applied to all incoming HTTP routes per client IP address.
• Request/Response Contract:
  • Response (when throttled): HTTP 429 Too Many Requests, Headers: Retry-After: 10, X-DDoS-Throttled: true.
  • Body: {"type": ".../DDoSThrottled", "title": "Volumetric Flood Throttling Triggered", "status": 429, ...}.
• Expected Invariant: Client IPs exceeding 100 requests within a 10-second window are throttled immediately.
• Possible Implementation Risks: Shared NAT IP addresses throttling multiple legitimate users simultaneously.
• Edge Cases: Rapid burst of 150 requests in 1 second, spoofed X-Forwarded-For headers.
• Engineering Claim Being Made: "The application layer protects against L7 volumetric floods using sliding-window rate limiting."
• Appropriate Verification Methodology: High-throughput concurrent burst testing to verify HTTP 429 enforcement.

---

1.7 Prometheus Telemetry Instrumentator

• Component: app.infrastructure.telemetry.setup_telemetry
• Purpose: Instruments FastAPI application using prometheus-fastapi-instrumentator for per-endpoint HTTP metrics.
• Endpoint Specification: GET /metrics (untracked, excluded from schema).
• Request/Response Contract:
  • Response: HTTP 200 OK, Content-Type: text/plain; version=0.0.4; charset=utf-8.
  • Body: OpenMetrics text format containing http_request_duration_seconds histograms and http_requests_in_flight.
• Expected Invariant: Endpoint latency histograms and request counters are automatically updated on every HTTP call.
• Possible Implementation Risks: High cardinality metric explosion if path parameters are untemplated.
• Edge Cases: Unregistered paths causing unbounded metric label generation (should_ignore_untemplated=True configured).
• Engineering Claim Being Made: "Per-endpoint request durations and in-flight counters are automatically tracked in OpenMetrics format."
• Appropriate Verification Methodology: Scraping /metrics after benchmark execution to assert metric existence.

---

2. Router & Endpoint Inventory

2.1 Health & Readiness Probes (health.py)

• Component: app.presentation.routers.health
• Purpose: Exposes Kubernetes liveness and readiness probe endpoints.
• Endpoint Specification:
  • GET /health (Liveness)
  • GET /health/ready (Readiness)
• Request/Response Contract:
  • GET /health → HTTP 200 OK, {"status": "healthy", "version": "0.2.0"}.
  • GET /health/ready → HTTP 200 OK (when Redis & DB are healthy) OR HTTP 503 Service Unavailable ({"status": "degraded", "checks": {...}}).
• Expected Invariant: /health/ready returns HTTP 503 whenever Redis or Database dependencies fail.
• Possible Implementation Risks: Slow health check queries causing probe timeouts under heavy load.
• Edge Cases: Redis connection timeout, PostgreSQL pool exhaustion.
• Engineering Claim Being Made: "The readiness probe returns HTTP 503 on dependency failure for Kubernetes orchestration."
• Appropriate Verification Methodology: Fault injection disabling Redis/DB and asserting HTTP 503 response.

---

2.2 Machine Learning Inference & Scoring (predict.py)

• Component: app.presentation.routers.predict
• Purpose: Real-time transaction fraud score evaluation, shadow challenger model execution, and feature store ingestion.
• Endpoint Specification:
  • POST /api/v1/predict
  • POST /api/v1/score-transaction
• Request/Response Contract:
  • Request: TransactionPredictRequest (transaction_amount >= 0.0, merchant_category: max_length=256, hour_of_day: [0, 23], country_code: max_length=256).
  • Response: TransactionPredictResponse (fraud_probability ∈ [0.0, 1.0], risk_score ∈ [0, 1000], policy_action, breakdown).
• Expected Invariant:
  • fraud_probability is bounded in [0, 1].
  • PyTorch inference and risk scoring are offloaded via asyncio.to_thread to prevent event loop blocking.
  • Feature Store ingestion (ingest_transaction) is executed via BackgroundTasks after response dispatch, ensuring score idempotency.
• Possible Implementation Risks: Out-of-memory errors during concurrent PyTorch forward passes on large tensors.
• Edge Cases: Extremely large transaction amounts (1e308), invalid categorical values, missing optional fields.
• Engineering Claim Being Made: "ML inference is non-blocking, idempotent, and guaranteed to produce bounded risk scores."
• Appropriate Verification Methodology: Property-based testing with Hypothesis and threadpool concurrency benchmarks.

---

2.3 Alert Management & Intelligence (alerts.py)

• Component: app.presentation.routers.alerts
• Purpose: Fraud alert retrieval, filtering, explainability report extraction, and cross-bank shared threat intelligence.
• Endpoint Specification:
  • GET /api/v1/alerts
  • POST /api/v1/alerts
  • GET /api/v1/alerts/{alert_id}
  • GET /api/v1/alerts/{alert_id}/explainability
  • GET /api/v1/alerts/intelligence
• Request/Response Contract:
  • Query Params: limit (ge=1, le=200), severity (AlertSeverity enum), status (AlertStatus enum).
  • Response: Paginated alert list, SHAP/LIME feature contributions, or HTTP 422 on invalid enum query parameters.
• Expected Invariant: Invalid query enum parameters return HTTP 422 Unprocessable Entity rather than unhandled HTTP 500.
• Possible Implementation Risks: Missing index on bank_id / created_at causing slow query pagination.
• Edge Cases: severity=INVALID_STRING, limit=0, limit=1000, non-existent alert_id.
• Engineering Claim Being Made: "Alert query parameters are guarded against invalid Enum values, returning HTTP 422."
• Appropriate Verification Methodology: Invalid enum query parameter injection testing.

---

2.4 Case Investigation & Idempotency (cases.py)

• Component: app.presentation.routers.cases
• Purpose: Case lifecycle management, status transitions, note attachments, and idempotent case creation.
• Endpoint Specification:
  • GET /api/v1/cases
  • POST /api/v1/cases
  • PUT /api/v1/cases/{case_id}/status
  • POST /api/v1/cases/{case_id}/notes
  • POST /api/v1/cases/{case_id}/link-alert
• Request/Response Contract:
  • Header: Idempotency-Key (optional string, max_length=256).
  • Request Body: CaseCreateRequest (title: max_length=256, priority: max_length=64).
  • Response: CaseResponse, HTTP 422 on invalid status transition or invalid enum parameter.
• Expected Invariant: Replaying POST /api/v1/cases with the same Idempotency-Key returns the cached response without creating duplicate cases.
• Possible Implementation Risks: In-memory idempotency cache fallback leaking memory if TTL expiration fails.
• Edge Cases: Duplicate Idempotency-Key sent concurrently across two parallel threads.
• Engineering Claim Being Made: "Case creation processes Idempotency-Key headers with Redis-backed 24h TTL deduplication."
• Appropriate Verification Methodology: Concurrent replay testing using identical Idempotency-Key values.

---

2.5 Security, ABAC, & Audit Chain (security.py)

• Component: app.presentation.routers.security
• Purpose: Dynamic ABAC policy evaluation, SHA-256 audit chain verification, and subsystem security status reporting.
• Endpoint Specification:
  • POST /security/abac/evaluate
  • POST /security/audit-chain/verify
  • GET /security/status
• Request/Response Contract:
  • Evaluate Request: UserClaims, ABACResource, action.
  • Evaluate Response: {"allowed": bool, "reason": str, "policy_name": str}.
  • Verify Response: {"is_valid": bool, "length": int, "latest_hash": str}.
• Expected Invariant:
  • Cross-tenant bank access is strictly denied by ABAC.
  • The SHA-256 audit chain remains cryptographically valid (is_valid = True) across sequential appends.
• Possible Implementation Risks: Audit chain lock contention under high concurrent logging throughput.
• Edge Cases: Mis-matched bank clearance levels, corrupted audit chain block hashes.
• Engineering Claim Being Made: "ABAC tenant isolation is mathematically enforced and audit chains are tamper-evident."
• Appropriate Verification Methodology: Property-based invariant verification and multi-thread concurrency testing.

---

2.6 Gateway Proxy Router (gateway.py)

• Component: app.presentation.routers.gateway
• Purpose: Reverse proxying, OIDC JWT bearer authentication, API key verification, and RFC rate limit header injection.
• Endpoint Specification:
  • ANY /{path:path} (Passthrough reverse proxy)
• Request/Response Contract:
  • Headers: Authorization: Bearer <token> or X-API-Key: <key>.
  • Response Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
  • Response (on auth fail): HTTP 401 Unauthorized or HTTP 403 Forbidden.
  • Response (on rate limit): HTTP 429 Too Many Requests, Retry-After.
• Expected Invariant: Every gateway proxy response carries explicit RFC rate limit headers.
• Possible Implementation Risks: Downstream service unavailability causing HTTP 502 Bad Gateway timeouts.
• Edge Cases: Expired JWT tokens, malformed API keys, downstream socket connection refused.
• Engineering Claim Being Made: "The gateway enforces OIDC/API-key auth, ABAC authorization, and returns RFC rate limit headers."
• Appropriate Verification Methodology: Adversarial JWT/API-key testing and rate limit bucket verification.

---

2.7 Federated Learning Simulation & Training (simulation.py, training.py)

• Component: app.presentation.routers.simulation, app.presentation.routers.training
• Purpose: Federated Learning simulation management, round execution, participant configuration, and model aggregation.
• Endpoint Specification:
  • GET /api/v1/simulations, POST /api/v1/simulations
  • POST /api/v1/training/round
• Request/Response Contract:
  • Request: Simulation parameters (num_rounds, privacy_budget_epsilon, participant_banks).
  • Response: SimulationResponse or training round execution metrics.
• Expected Invariant: FL training rounds preserve client differential privacy bounds (epsilon <= max_epsilon).
• Possible Implementation Risks: Long-running simulation rounds blocking HTTP worker threads if executed synchronously.
• Edge Cases: num_rounds = 0, epsilon <= 0.0, missing participant banks.
• Engineering Claim Being Made: "FL simulation endpoints enforce differential privacy budget constraints."
• Appropriate Verification Methodology: Differential privacy parameter boundary testing.

---

2.8 Entity Resolution & Risk Graph (entities.py, graph.py)

• Component: app.presentation.routers.entities, app.presentation.routers.graph
• Purpose: Cross-bank privacy-preserving entity resolution and GraphSAGE relationship network graph visualization.
• Endpoint Specification:
  • GET /api/v1/entities, POST /api/v1/entities
  • GET /api/v1/graph
• Request/Response Contract:
  • Request: Entity identifiers or graph node depth parameters.
  • Response: Entity matching confidence scores or graph nodes/edges JSON structure.
• Expected Invariant: Entity resolution raw PII is never exposed; matching operates on cryptographic hashes.
• Possible Implementation Risks: Deep graph traversal (depth > 5) causing memory allocation spikes.
• Edge Cases: Cyclic graph relationships, isolated orphan nodes.
• Engineering Claim Being Made: "Entity resolution uses privacy-preserving hashes and graph traversal is strictly bounded."
• Appropriate Verification Methodology: Graph structural invariant testing and memory allocation tracing.

---

2.9 Compliance, PSD2, & Real-Time Inference (compliance.py, psd2.py, realtime_inference.py)

• Component: app.presentation.routers.compliance, app.presentation.routers.psd2, app.presentation.routers.realtime_inference
• Purpose: Regulatory compliance reporting, PSD2 Strong Customer Authentication (SCA) evaluation, and streaming scoring.
• Endpoint Specification:
  • GET /api/v1/compliance
  • GET /api/v1/psd2/sca
  • POST /api/v1/realtime/stream-score
• Request/Response Contract:
  • Response: Compliance audit summaries, SCA exemption flags (EXEMPT_TRA, MANDATE_SCA), or streaming risk scores.
• Expected Invariant: PSD2 SCA evaluations deterministically assign exemption status based on transaction risk thresholds.
• Possible Implementation Risks: Inconsistent risk scoring between batch /predict and streaming /realtime/stream-score.
• Edge Cases: Amount exactly equal to TRA exemption boundary (€100, €250, €500).
• Engineering Claim Being Made: "PSD2 SCA exemption logic adheres strictly to RTS EBA risk threshold tables."
• Appropriate Verification Methodology: Boundary testing against EBA Regulatory Technical Standards (RTS) thresholds.

---

2.10 Real-Time WebSockets (streaming_ws.py, training_ws.py)

• Component: app.presentation.websockets.streaming_ws, app.presentation.websockets.training_ws
• Purpose: Bi-directional real-time event streaming and FL training progress push notifications.
• Endpoint Specification:
  • GET /ws/stream
  • GET /ws/training
• Request/Response Contract:
  • Handshake: WebSocket upgrade request with token authentication.
  • Frames: JSON event frames (ALERT_GENERATED, FL_ROUND_COMPLETE).
• Expected Invariant: Unauthorized WebSocket connections are closed immediately during handshake with code 1008.
• Possible Implementation Risks: Unhandled client disconnects leading to dangling WebSocket connection references.
• Edge Cases: Client disconnection mid-frame broadcast, missing auth token in query string.
• Engineering Claim Being Made: "WebSocket connections enforce query-string token auth and handle abrupt disconnections gracefully."
• Appropriate Verification Methodology: WebSocket handshake auth testing and abrupt disconnect handling verification.

---

3. Comprehensive Verification Matrix

Component	Target File	Verification Focus	Primary Methodology
Global Error Handling	main.py	RFC 7807 problem+json response format	Adversarial Exception Injection
Content-Type Filter	main.py	HTTP 415 rejection on non-JSON bodies	Media Type Fuzzing
Trace Context	main.py	W3C traceparent header injection	Header Assertion
mTLS Verification	main.py	Certificate fingerprint & CRL validation	Security Certificate Audit
DDoS Throttling	main.py	L7 sliding-window rate limiting	High-Throughput Burst Test
Readiness Probe	health.py	HTTP 503 on Redis/DB failure	Dependency Fault Injection
ML Inference	predict.py	Non-blocking asyncio.to_thread execution	Async Event Loop Concurrency
Alert Enums	alerts.py	HTTP 422 on invalid Enum params	Invalid Query Injection
Case Idempotency	cases.py	Idempotency-Key 24h deduplication	Concurrent Replay Testing
ABAC & Audit	security.py	Cross-tenant isolation & SHA-256 chain	Property-Based Invariant Test
Gateway Rate Limit	gateway.py	RFC X-RateLimit-* headers	Rate Limit Bucket Verification
PSD2 SCA	psd2.py	EBA RTS threshold compliance	Boundary Value Analysis
WebSockets	streaming_ws.py	Token handshake & abrupt disconnect	WS Handshake Security Audit

---

This inventory serves as the foundational specification reference for all subsequent empirical testing and verification suites.