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

# Security model

> Review identity, credential encryption, authorization, idempotency, uncertainty, and public-data boundaries.

# Review the security model

The wrapper assumes provider responses, browser input, network transport, and caller-supplied identifiers can be hostile or incomplete. It fails closed at identity, origin, amount, resource ownership, and state-transition boundaries.

## Separate caller authority

Customer routes require customer sessions. Operator routes can view operations and mandates and can suspend a mandate, but cannot move money. Agent execution requires both an OAuth scope and an active customer mandate bound to the same client identifier. Internal rules must match an approved rule revision.

Cookie-authenticated mutations require the exact application origin and the session cross-site request forgery token. Sensitive customer actions also consume a short-lived confirmation intent bound to the normalized payload.

## Encrypt provider authority

Vault Transit encrypts Perflo access and refresh credentials, beneficiary destinations and chains, browser approval sessions and URLs, and provider preparation context. Derived-key contexts bind connection ciphertext to the exact customer and provider-binding generation, and bind beneficiary and operation ciphertext to the exact customer and row ID. Moving ciphertext between rows or connection generations therefore fails decryption. Request and audit JSON contains only safe identifiers, fingerprints, normalized amounts, and policy values.

The public API never returns raw provider credentials, primary account numbers, card verification values, raw reveal tokens, token addresses, networks, or unmasked bank identifiers. Operators do not receive customer approval URLs.

## Prevent duplicate writes

The API stores the operation, idempotency record, and unique outbox event before provider submission. Equal replays return the same operation; another body with the same key returns a stable conflict.

Each idempotency key is honoured for twenty-four hours from first acceptance, and a replayed acceptance carries the response header `Idempotent-Replayed: true` — sent only on a replay, never as `false`. A key presented after its window is refused with `409` and code `idempotency_key_expired` and is never executed: once the window lapsed the API cannot promise "no duplicate", and executing would risk a second transfer. Between expiry and the thirty-day record retention that refusal is deterministic; pruning removes only the idempotency record and touches no operation row.

The worker commits `submitting` before a provider money or authority write. A timeout, reset, possible-acceptance server error, invalid accepted response, or restart while submitting becomes `indeterminate`. The worker never resubmits an indeterminate write.

## Reconcile with exact reads

Reconciliation can only use a stable transaction reference, exact card identifier and expected state, exact grant identifier, or other unique provider evidence. Each provider identifier is claimed once per provider-binding generation using a non-reversible fingerprint. A collision leaves the later operation indeterminate while retaining its exact correlation evidence. Missing or ambiguous evidence leaves the operation disabled and operator-visible.

Mandate execution re-reads the exact upstream grant before every payment and compares status, encrypted recipient destination, chain, United States dollar caps, payment count, and expiry. Local caller, rule, count, total, and rolling-window reservations are atomic.

## Pin provider and application origins

Live mode pins all five Perflo service origins. Hosted connection, approval, Know Your Customer, and reveal URLs must use the trusted app origin. Production also requires HTTPS application and Vault origins, Auth0, PostgreSQL, Redis, authenticated metrics, and disabled debug authentication.