Skip to main content

​
ADR 0010: Use a neobank-owned Perflo login for the live demo

This record defines how the local product demo connects a real Perflo account.

​
Context

The account already authenticated in the Perflo CLI is useful for identifying the intended demo user. Reusing that CLI credential would make the neobank a probe attached to another application’s session instead of a complete system with its own API login state. It would also couple the demo to a local credential file and make logout, refresh, and revocation ownership ambiguous. The current Perflo device login returns a broad access and refresh credential. It is adequate for a local capability demo but does not meet the production least-privilege boundary recorded in ADR 0004.

​
Decision

Use the CLI only to display the account the operator intends to link. The neobank never reads or imports CLI credentials. The FastAPI API starts a new Perflo device session, returns only the approval URL and polling metadata to the authenticated customer, and polls Perflo from the backend. After approval, it stores the new access and refresh credentials in PostgreSQL encrypted with a derived Vault Transit key. It refreshes that session independently and shows only a masked Perflo account hint. Disconnect revokes the Perflo device before deleting local state. Add an explicit demo adapter mode for this workflow. It is limited to the development environment, requires PostgreSQL, Redis, Vault, and the reviewed live Perflo origins. A loopback demo requires explicit debug authentication. The dedicated neobank.proofof.tech demo forbids debug authentication and uses Auth0 customer sessions. Keep pilot for the partner-read Auth0 runtime and partner as the only production mode. Use the deterministic fake adapter for financial mutations and features that lack partner-safe Perflo contracts. The live demo performs account linking and reviewed non-financial reads only.

​
Consequences

The frontend and API demonstrate their own login lifecycle against the same real account without depending on the CLI session. The customer can see which account was linked and can revoke the neobank device. The local demo still holds a broad credential. Vault encryption, route pinning, and non-production startup checks reduce exposure but do not provide least privilege. Production remains blocked on the Perflo capability requests. The local live-demo Vault instance is ephemeral. The dedicated server persists Vault data and bootstrap material, but the operator must still disconnect every provider device before deleting its volumes so the API can decrypt the access credential and revoke it.

​
Rejected alternatives

  • Reuse the CLI access or refresh token: session ownership remains with the CLI and the neobank is not independently authenticated.
  • Store the credential in the browser: a browser compromise could expose the broad upstream token.
  • Exercise live financial mutations: current contracts lack the required partner scope, idempotency, confirmation, and reconciliation guarantees.