CASHFLOWARC MFA IMPLEMENTATION OUTLINE ====================================== Purpose ------- CashFlowArc protects its CollectArc and BudgetArc application accounts with authenticator-app multi-factor authentication (MFA). The implementation uses time-based one-time passwords (TOTP) after password verification. Financial institution MFA is intentionally kept separate: it is performed by the bank inside the account-linking provider's secure flow, never by CashFlowArc. 1. MFA METHODS AND SCOPE ------------------------ Application sign-in MFA * Supports standards-compatible authenticator apps through a TOTP setup URI and QR code. * Uses a Base32 secret generated from 20 random bytes, six-digit codes, and 30-second time steps. * Accepts the current time step plus one immediately preceding and following step to accommodate normal device clock drift. * Applies to email-based user accounts and to the separately configured global administrator account. Institution MFA * Teller Connect presents bank credentials and any bank MFA prompt directly to the account holder. * CashFlowArc does not receive or store the bank username, password, or bank MFA secret. After a successful provider flow, it verifies the signed enrollment and stores only the provider access token, encrypted at the application layer. 2. USER ENROLLMENT FLOW ----------------------- 1. An authenticated user opens Preferences > Multi-Factor Authentication. 2. CashFlowArc generates a unique TOTP secret if one has not already been staged for that user. 3. The secret is encrypted with the application master key using the Fernet authenticated-encryption wrapper, then stored in Oracle. At this point MFA remains disabled and unconfirmed. 4. The setup screen provides a QR code, manual setup key, and otpauth URI labelled with the issuer "CashFlowArc" and the user's email address. 5. The user scans the QR code in an authenticator app and submits a current six-digit code. 6. CashFlowArc verifies the code and atomically marks MFA enabled, records the confirmation timestamp, and marks the current session MFA-verified. 3. SIGN-IN AND ACCESS ENFORCEMENT --------------------------------- * Password verification always occurs before the MFA challenge. * If a user has enabled MFA, successful password verification creates a short-lived pending-MFA session rather than a full application session. That pending state expires after 10 minutes. * The /mfa challenge validates the submitted code against the encrypted secret. A successful result starts the normal user session and records the login time. * A completed application session has a fixed 24-hour maximum age. * BUDGET_REQUIRE_MFA controls user-MFA policy. When true, authenticated user requests are redirected to enrollment until MFA is enabled. It also blocks users from disabling MFA. When false, MFA is opt-in and may be disabled. * The global admin account uses BUDGET_ADMIN_TOTP_SECRET. When this setting is present, the administrator must complete the same post-password TOTP challenge. When absent, the admin account remains password-only. 4. DATA MODEL ------------- Oracle table: BUDGET_USERS MFA_TOTP_SECRET_CIPHER Encrypted per-user TOTP secret (CLOB) MFA_ENABLED Required, defaults to 0; set to 1 after confirmation MFA_CONFIRMED_AT Timestamp of successful enrollment confirmation MFA_UPDATED_AT Timestamp of the most recent MFA state change The schema migration adds these columns to existing deployments, backfills a missing MFA_ENABLED value to 0, and makes the column non-null. Disabling MFA securely clears the stored encrypted secret, disabled flag, and confirmation timestamp. The disable action requires both the current password and a valid current TOTP code, as well as CSRF validation. It is unavailable when BUDGET_REQUIRE_MFA is enabled. 5. SECURITY CONTROLS -------------------- * Secrets are encrypted before database storage and decrypted only during enrollment confirmation, login challenge, or a verified disable request. * The admin TOTP secret is configuration-managed rather than stored in the user table; protect BUDGET_ADMIN_TOTP_SECRET as a deployment secret. * TOTP codes are normalized to digits and compared with a constant-time comparison after the expected code is generated. * Login and MFA attempts are rate limited by both client IP and a hashed identity. Login limits are 30/IP and 10/identity per 10 minutes; MFA limits are 10/IP and 3/identity per hour. * Login, MFA setup, and MFA-disable forms use CSRF tokens. Redirect targets are constrained to safe local destinations. * Session cookies are HttpOnly and SameSite=Lax; the Secure flag is enabled through BUDGET_COOKIE_SECURE for HTTPS deployments. Authenticated HTML and JSON responses are marked no-store. * Expired or invalid full and pending MFA sessions are cleared before a new sign-in can proceed. 6. FINANCIAL-INSTITUTION MFA OPERATIONS --------------------------------------- * The provider-hosted enrollment/repair screen is the only place a user enters bank credentials or responds to a bank MFA prompt. * For American Express, scheduled background syncs use a quieter default cadence of seven days (versus 24 hours generally). An MFA-required result during background sync is recorded as a deferred reconnect instead of immediately declaring the connection broken. * A manual sync or an enrollment-disconnected webhook still requires the user to repair the connection through the provider flow. 7. CONFIGURATION AND DEPLOYMENT CHECKLIST ----------------------------------------- * Set BUDGET_REQUIRE_AUTH=true in production. * Set BUDGET_COOKIE_SECURE=true and serve the application behind HTTPS. * Set BUDGET_REQUIRE_MFA=true to require user MFA before financial-data use. * Set BUDGET_ADMIN_TOTP_SECRET to require MFA for the global admin account. * Keep the application master key and all environment secrets out of source control; restrict them to the runtime identity or a secret manager. * Confirm that server time is synchronized, since TOTP verification depends on accurate time. * Test enrollment, normal MFA login, expired pending challenge, required-MFA redirect, disable flow (when policy permits), and provider-bank MFA repair. 8. CURRENT DESIGN BOUNDARIES / FUTURE HARDENING OPTIONS -------------------------------------------------------- The current implementation is authenticator-app TOTP only. It does not show recovery codes, WebAuthn/passkeys, SMS/email MFA, device trust, or a persistent distributed rate-limit store. If CashFlowArc expands beyond its current deployment topology, consider adding recovery-code management, an audited administrator-assisted recovery procedure, replay-resistant TOTP tracking, centralized rate limiting, MFA/security-event audit logs, and phishing- resistant WebAuthn support. Implementation sources reviewed ------------------------------- * budget_teller_oracle/web.py: TOTP generation/verification, login, pending MFA session, enrollment, enforcement, disabling, rate limits, and cookies. * budget_teller_oracle/db.py: Oracle schema and MFA persistence methods. * budget_teller_oracle/crypto.py: Fernet encryption wrapper. * budget_teller_oracle/templates/mfa_setup.html and mfa_challenge.html: enrollment and challenge user experience. * docs/COLLECTARC_OPERATIONS.md and docs/SECURE_SERVER_SETUP.md: provider MFA and American Express operational behavior.