Architecture And Security¶
This page explains FlowClaw's technical architecture and security controls.
Architecture Overview¶
Portals. FlowClaw has a Merchant Portal for route requests and an Admin / Operator Portal for review, proof, governance, and audit workflows.
Control API. The backend exposes auth, route session, runtime, artifact, route case, merchant, settlement-agent, readiness, and portal routes.
Platform layer. packages/platform handles auth, tenant membership, role checks, session access, provider accounts, storage, Supabase integration, and redaction.
Route intelligence. services/orchestrator/engine.py builds candidate routes using provider graph, corridor rules, liquidity/trust/risk scoring, and manual actor profiles.
Policy. policies/flowclaw.rego applies hard route allow/deny decisions.
Execution. The execution layer handles supported execution modes, manual pauses, proof confirmation, degraded states, and audit logs.
Database and artifacts. The data layer stores tenants, users, sessions, audit events, route cases, evidence, artifacts, and controlled review records.
Current Security Measures¶
| Measure | What it protects | Where it applies |
|---|---|---|
| Server-side actor context | Prevents protected endpoints acting without identity. | Protected API routes |
| Tenant membership checks | Keeps Operator Company workspaces separated. | Tenant-scoped APIs |
| Role boundaries | Separates Platform Admin, Desk Operator, Merchant Client, and Settlement Agent powers. | Role-guarded APIs |
| Session access checks | Prevents actors accessing sessions they should not see. | Session APIs |
| Merchant-safe response model | Keeps operator-only case details out of merchant views. | Merchant APIs |
| Settlement Agent denial routes | Keeps Settlement Agent power limited to assigned proof submission. | Settlement-agent APIs |
| OPA/Rego policy | Blocks excessive risk/cost/hops/unverified provider routes. | Route evaluation |
| Live-safe probe cap | Limits controlled live checks. | Execution layer |
| Proof-gated manual steps | Prevents manual steps being treated as complete without proof. | step confirmation endpoints |
| Audit event uniqueness | Prevents duplicate critical audit transition rows. | audit uniqueness migration |
| Sensitive data redaction | Redacts secrets, auth headers, cookies, JWT-like values, platform keys, and sensitive notes. | Logging and audit paths |
| Backend-mediated artifacts | Avoids directly exposing storage paths in normal API responses. | artifact download routes |
| Browser-safe config split | Separates browser-safe configuration from server-side keys. | Auth/config APIs |
Role Boundary Details¶
| Role | Allowed | Not allowed |
|---|---|---|
| Platform Admin | Governance decisions, readiness gates, operator oversight, all tenant-level control paths. | Evidence-backed decisions and tenant-scoped controls. |
| Desk Operator | Manage sessions, quotes, proof, manual routes, controlled review work, and operator queue items. | Proof-backed workflow actions and merchant-safe publishing. |
| Merchant Client | Request routes, accept route, view assigned merchant-visible cases. | Cannot see other merchants' cases, internal scoring, readiness governance, or policy bypass controls. |
| Settlement Agent | View assigned controlled-probe settlement legs and submit proof. | Cannot approve routes or bypass policy. |
Custody Model¶
FlowClaw is designed as route intelligence and operator workflow software.
Plain English meaning: FlowClaw can recommend, compare, record, and govern route decisions. Payment accounts and payment rails remain with the merchant, operator, or configured provider flow.
Controlled review forms can record rail ownership and proof references so route evidence stays traceable.
Route Intelligence Controls¶
FlowClaw's route intelligence is based on:
- provider graph
- allowed corridor pairs
- provider posture
- cost
- latency
- liquidity confidence
- slippage
- provider risk
- human execution penalty
- data freshness
- trust score
- proof requirements
- policy result
This is stronger than a static routing table because route choice is evidence and policy aware.
Security Roadmap¶
These are the main hardening areas to keep improving as FlowClaw moves into wider operational use.
| Priority | Measure | Why it matters |
|---|---|---|
| High | Fail closed when OPA policy evaluation is unavailable for non-simulation/live paths. | A policy outage should not accidentally allow a risky route. |
| High | Remove or tightly sandbox raw file_path artifact attachment. |
Client-supplied paths can be dangerous when download code reads local paths. |
| High | Encrypt provider account metadata with KMS or field-level encryption. | Provider account data can include sensitive operational metadata. |
| High | Add rate limiting and CSRF protection for cookie-auth mutating routes. | Browser-auth APIs need abuse protection beyond login lockout. |
| High | Fail closed on unknown provider connector IDs. | Unknown providers should not silently use MockConnector. |
| Medium | Add database-level RLS or equivalent tenant defense in depth. | Application checks exist, but DB-level boundaries reduce blast radius. |
| Medium | Add negative authorization tests for every endpoint group. | Prevents regressions across admin, operator, merchant, and settlement-agent access. |
| Medium | Add formal OpenAPI examples for important requests. | Future API users and agents need reliable examples. |
| Medium | Add provider and corridor compliance checklists. | Route intelligence should remain aligned with provider and corridor rules. |
| Medium | Add production secret rotation checklist. | Reduces risk from local/test keys or copied environment values. |
Operational Security Expectations¶
- Keep each Operator Company in its own tenant workspace.
- Use least-privilege roles for Platform Admins, Desk Operators, Merchant Clients, and Settlement Agents.
- Confirm manual steps only when proof is available.
- Publish merchant-visible case details only through merchant-safe summaries.
- Keep provider credentials and sensitive merchant documents out of public artifacts.
- Review audit entries for approval, resume, proof, and readiness changes.