Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
feat(auth): a second factor on the console, with recovery codes and per-tenant enforcement (fix pass 4.2) (#1202)
Beenu Aroraa87aa2a708c7
diff --git a/.github/workflows/mfa-live.yml b/.github/workflows/mfa-live.ymlnew file mode 100644index 000000000..b055d76fa--- /dev/null+++ b/.github/workflows/mfa-live.yml@@ -0,0 +1,157 @@+# A second factor on the console — through the real app and real Postgres.+#+# Why live and not offline+# ------------------------+# The property is "a correct password is not enough", and the only thing+# that can demonstrate it is the real login route against the real user row+# with the real password hash. A fake session answers whatever the handler+# asks, so it would return a user with whatever MFA state the test wrote+# into the double — which is the shape that has shipped defects here before.+#+# `ENVIRONMENT=test`, never `development`: `development` is in+# `AUTH_BYPASS_ENVIRONMENTS`, so an uncredentialed request resolves to a+# demo administrator, inside the one suite whose whole subject is what it+# takes to become a principal.+#+# No `paths:` filter. The surface is authentication; a change anywhere in+# `services/api` can reach it, and a filtered gate on a login path is a gate+# that is absent exactly when something unexpected moved.+name: Console MFA (live)++on:+ push:+ branches: [main]+ pull_request:+ workflow_dispatch:++concurrency:+ group: mfa-live-${{ github.ref }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.sha }}+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}++permissions:+ contents: read++jobs:+ mfa-live:+ name: A password alone does not complete a console sign-in+ runs-on: ubuntu-latest+ timeout-minutes: 20++ services:+ postgres:+ image: postgres:16-alpine+ env:+ POSTGRES_USER: aisoc+ POSTGRES_PASSWORD: aisoc_ci_only+ POSTGRES_DB: aisoc+ ports: ["5432:5432"]+ options: >-+ --health-cmd "pg_isready -U aisoc"+ --health-interval 5s+ --health-timeout 5s+ --health-retries 20++ env:+ # The runtime role, not the owner. A superuser ignores every RLS+ # policy even under FORCE ROW LEVEL SECURITY, and the challenge path+ # writes `aisoc_user_mfa` on a session that binds its tenant from the+ # user row rather than from a principal — running as the owner would+ # pass for a reason no deployment enjoys.+ MFA_DSN: postgresql+asyncpg://aisoc_app:aisoc_app_ci_only@localhost:5432/aisoc+ PGPASSWORD: aisoc_ci_only+ ENVIRONMENT: test+ OTEL_SDK_DISABLED: "true"++ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7++ - uses: actions/setup-python@e9d6f990972a57673cdb72ec29e19d42ba28880f # v6+ with:+ python-version: "3.11"++ - name: Install api from its lockfile+ working-directory: services/api+ run: |+ set -euo pipefail+ sudo apt-get update -qq && sudo apt-get install -y -qq libxmlsec1-dev pkg-config+ python -m pip install --quiet --upgrade pip "poetry==2.4.1"+ poetry config virtualenvs.create false+ poetry install --no-root --no-interaction+ python -m pip install --quiet pytest pytest-asyncio++ - name: Apply every migration, in order+ run: |+ for f in services/api/migrations/*.sql; do+ psql -h localhost -U aisoc -d aisoc -v ON_ERROR_STOP=1 -q -f "$f"+ done++ - name: Give the runtime role its password+ run: |+ psql -h localhost -U aisoc -d aisoc -v ON_ERROR_STOP=1 -q -c \+ "ALTER ROLE aisoc_app WITH PASSWORD 'aisoc_app_ci_only';"+ psql -h localhost -U aisoc -d aisoc -v ON_ERROR_STOP=1 -q -c \+ "GRANT USAGE ON SCHEMA public TO aisoc_app;"++ # RFC 6238's own vectors. They are what make the in-tree derivation an+ # implementation of the standard rather than of itself — a round trip+ # would agree with itself even if every authenticator app rejected the+ # enrolment.+ - name: The derivation matches RFC 6238+ working-directory: services/api+ run: python -m pytest tests/test_console_mfa.py -v --tb=short++ - name: Enrolment, challenge, recovery, policy and reset+ working-directory: services/api+ env:+ ISOLATION_MFA_DSN: ${{ env.MFA_DSN }}+ DATABASE_URL: ${{ env.MFA_DSN }}+ run: python -m pytest ../../tests/isolation/test_console_mfa_live.py -v --tb=short++ # The negative control.+ #+ # Removing the branch that turns a correct password into a challenge+ # must make the suite go red. Without it, "alice signed in with a+ # code" would pass equally well against a login route that had never+ # asked for one — it would simply hand out a session first.+ #+ # Measured on the fix commit: eight tests fail.+ - name: The suite fails when a password alone issues a session again+ working-directory: services/api+ env:+ ISOLATION_MFA_DSN: ${{ env.MFA_DSN }}+ DATABASE_URL: ${{ env.MFA_DSN }}+ run: |+ cp app/api/v1/endpoints/auth.py /tmp/auth.bak+ python - <<'PY'+ import pathlib, sys+ p = pathlib.Path("app/api/v1/endpoints/auth.py")+ s = p.read_text()+ needle = (+ " challenge = await mfa_challenge_for(db, user_id=user.id, tenant_id=user.tenant_id)\n"+ " if challenge is not None:\n"+ " return JSONResponse(status_code=status.HTTP_202_ACCEPTED, content=challenge)\n"+ )+ if needle not in s:+ print("negative control could not find the login integration to remove; it has "+ "been reshaped and this control is no longer proving anything")+ sys.exit(1)+ p.write_text(s.replace(needle, "", 1))+ PY+ if python -m pytest ../../tests/isolation/test_console_mfa_live.py -q >/dev/null 2>&1; then+ cp /tmp/auth.bak app/api/v1/endpoints/auth.py+ echo "FAIL: the suite passed with a password alone issuing a session."+ exit 1+ fi+ cp /tmp/auth.bak app/api/v1/endpoints/auth.py+ echo "OK: removing the challenge makes the suite fail, as it must."+ python -m pytest ../../tests/isolation/test_console_mfa_live.py -q++ # Both directions of the authorization accounting this item touches.+ # `require_current_factor` is registered in `check_route_authz.py` as+ # an authorizing call, which is a claim that needs its own gate run.+ - name: Route authorization accounting+ run: |+ python3 scripts/check_route_auth.py --self-test+ python3 scripts/check_route_auth.py+ python3 scripts/check_route_authz.py --self-test+ python3 scripts/check_route_authz.pydiff --git a/FIX_PASS_PROGRESS.md b/FIX_PASS_PROGRESS.mdindex 17b4b8953..dc8cad182 100644--- a/FIX_PASS_PROGRESS.md+++ b/FIX_PASS_PROGRESS.md@@ -103,7 +103,8 @@ conditional `numpy` pins collide into an unresolvable install. Parse with- [~] **4.1** SSO completes in the console- Two of the three defects did **not** reproduce: the console fragment consumer (`authApi.completeSsoHandoff`) and the login-screen SSO entry both landed in v17.1.0. Neither was covered by a test, so six now pin them. The third reproduced exactly as written — `_saml_settings()` read its IdP trust anchor from `SAML_IDP_*` while the connection's own `metadata_url` / `metadata_xml` were read by nothing, so a SAML login redirected to the environment's IdP and a correctly signed assertion came back `invalid_response`. Fixed in `app/auth/saml_metadata.py`; the ACS also now lands on `/login?next=` with both tokens, because the old RelayState redirect lost the fragment to the console's own auth guard. Driven end to end against real Postgres and a real signed assertion in `sso-live.yml`. **Still `[~]`**: the containerised-IdP leg (`sso-live.yml :: keycloak-oidc`) has never been observed to pass — no container runtime would start where it was written — so the claim row is PARTIAL, not GATED.-- [ ] **4.2** Console MFA+- [x] **4.2** Console MFA+ - Reproduced first: ten of eleven assertions against the real login route and real Postgres failed with `{"detail":"Not Found"}` — the surface did not exist. TOTP (RFC 6238, in-tree, pinned to the spec's own vectors rather than to a round trip), ten single-use recovery codes, a vault-encrypted secret, a `last_used_step` high-water mark so a code cannot be replayed inside its own 30-second window, per-tenant enforcement with **no backfill row** (absence means not required), and audited enrolment, disable, recovery-code use, policy change and administrative reset. A correct password for an enrolled account now answers **202** with a challenge instead of a session — 202 rather than a widened 200 body, because `access_token` is a required field and making it optional breaks every generated client. An unenrolled member of a newly-enforcing tenant enrols from that challenge rather than being locked out; the trade-off is stated in the module and the docs. Migration `096`. 28 offline tests, 13 live, and a CI negative control that deletes the challenge branch and requires the suite to go red.- [ ] **4.3** White-label reaches every surface it claims- [ ] **4.4** Metering counts what happened- [ ] **4.5** SCIM live coverage and the console token claimdiff --git a/apps/docs/docs/operations/console-mfa.md b/apps/docs/docs/operations/console-mfa.mdnew file mode 100644index 000000000..387e2b634--- /dev/null+++ b/apps/docs/docs/operations/console-mfa.md@@ -0,0 +1,127 @@+---+id: console-mfa+title: Two-factor authentication+sidebar_label: Two-factor auth+---++# Two-factor authentication++A time-based one-time password on the desktop console, with recovery+codes, per-tenant enforcement, and an audit row for every enrolment and+reset.++## What this replaced++Nothing. Before this, `POST /api/v1/auth/login` verified a password and+returned a token pair, and no user or administrator could make that+insufficient. Passkeys existed on `/responder/*` — the mobile PWA — so+the surface an analyst works from all day was single-factor by+construction.++## Enrolling++**Settings → Two-factor auth → Set up.** The console shows a key to add+to any authenticator app, you enter the code it displays, and the+response carries ten recovery codes.++The recovery codes exist in plaintext exactly once. They are stored as+SHA-256 hashes — not bcrypt, deliberately: a code is 100 bits of+generated entropy with no dictionary to slow an attacker down, and+verification walks every unused code you hold, so ten bcrypt comparisons+per attempt would be a second of CPU on the login path.++An enrolment is only a credential once it is **confirmed**. Starting one+and closing the tab locks nobody out.++## Signing in++A correct password for an enrolled account answers **HTTP 202** with a+short-lived `mfa_token` instead of a session:++```json+{ "mfa_required": true, "mfa_token": "eyJ…", "methods": ["totp", "recovery_code"] }+```++`POST /api/v1/auth/mfa/verify` with that token and a code — either from+the app or one of the recovery codes — returns the ordinary token pair.++:::note Why 202 and not an extended 200+`access_token` and `refresh_token` are required fields of+`TokenResponse`. Making either optional is a break for every generated+client, which `scripts/openapi_diff.py` correctly refuses. A 401 would+have collided with the console's own `handleUnauthorized`, which clears+stored credentials and bounces to `/login`.+:::++A code is spent once it is used. `last_used_step` records the 30-second+step it authenticated at, so a code read over your shoulder cannot be+replayed for the rest of its window. The practical effect worth knowing:+the code you confirm an enrolment with is not reusable to sign in a few+seconds later — wait for the next one.++## Requiring it across a tenant++**Settings → Two-factor auth → Require for everyone**, or+`PUT /api/v1/auth/mfa/policy` with `{"require_totp": true}`. Needs+`settings:write`.++Members who have not enrolled are **asked to enrol at their next+sign-in**, not locked out: the 202 they receive carries+`mfa_enrollment_required` and a challenge token the enrolment endpoints+accept, and the login page walks them through it.++The trade-off is stated rather than hidden: somebody holding a stolen+password can enrol *their own* authenticator before the real user does.+It is bounded by the password still being required, by the window closing+as soon as the real user enrols, and by `mfa.enrolled` being audited with+the source address. Refusing instead would lock out every unenrolled+member of the tenant at the moment the policy is turned on.++A tenant that has never visited this endpoint has **no policy row at+all**, and absence means not required. No migration writes one — a+backfill of a row per tenant would change the meaning of every predicate+that counts rows in that table.++## Losing a phone++Use a recovery code. Each works once.++With none left, an administrator holding `users:write` can clear the+factor:++```http+POST /api/v1/auth/mfa/reset/{user_id}+{ "reason": "lost phone, verified by voice" }+```++Three constraints, because an administrative reset is normally the+weakest link in an MFA deployment:++- the target must be in the caller's own tenant, taken from the+ authenticated principal and never from the request;+- the `reason` is required and lands in the audit row;+- an administrator may **not** reset their own factor here. That would be+ a self-disable with no code. Removing your own factor goes through+ `DELETE /api/v1/auth/mfa`, which requires a current code — otherwise a+ stolen session could strip the thing protecting it.++## What is audited++`mfa.enrolled`, `mfa.disabled`, `mfa.reset`, `mfa.recovery_code_used` and+`mfa.policy_changed`, all on the tenant's own hash-chained audit log, each+carrying the source address.++## Storage++The TOTP secret is vault-encrypted (`vault:v1:` / `vault:v2:`), never the+base32 you scanned. A database dump that yields TOTP secrets yields the+second factor for every account in it, which is most of the reason for+having one. A secret this deployment can no longer decrypt — a rotated+credential key with no rotation-from value — fails **closed**: sign-in is+refused with a message naming the cause, and an administrator resets the+factor.++## Related++- [Enterprise SSO](./enterprise-sso.md)+- [Security model](./security.md)diff --git a/apps/docs/sidebars.ts b/apps/docs/sidebars.tsindex 1f8267a74..23741e557 100644--- a/apps/docs/sidebars.ts+++ b/apps/docs/sidebars.ts@@ -188,6 +188,7 @@ const sidebars: SidebarsConfig = {items: ["operations/security","operations/enterprise-sso",+ "operations/console-mfa","operations/data-governance","compliance/evidence-pack","compliance/fips-posture",diff --git a/apps/web/src/app/(app)/settings/mfa/page.tsx b/apps/web/src/app/(app)/settings/mfa/page.tsxnew file mode 100644index 000000000..6e76ab9ec--- /dev/null+++ b/apps/web/src/app/(app)/settings/mfa/page.tsx@@ -0,0 +1,13 @@+import { MfaView } from '@/components/settings/MfaView';++export const metadata = {+ title: 'Two-factor authentication',+};++export default function MfaSettingsPage() {+ return (+ <div className="p-6">+ <MfaView />+ </div>+ );+}diff --git a/apps/web/src/app/login/page.tsx b/apps/web/src/app/login/page.tsxindex 1bb32a0b1..178eb4e42 100644--- a/apps/web/src/app/login/page.tsx+++ b/apps/web/src/app/login/page.tsx@@ -15,7 +15,15 @@import Link from 'next/link';import { useRouter, useSearchParams } from 'next/navigation';import { Suspense, useEffect, useState } from 'react';-import { API_BASE, authApi, onboardingApi } from '@/lib/api';+import {+ API_BASE,+ authApi,+ isMfaChallenge,+ mfaApi,+ onboardingApi,+ type MfaChallenge,+ type MfaEnrollment,+} from '@/lib/api';import { isDemoMode } from '@/lib/demoMode';type Phase = 'idle' | 'pending' | 'success' | 'error';@@ -65,6 +73,10 @@ function LoginInner() {const [phase, setPhase] = useState<Phase>('idle');const [error, setError] = useState<string | null>(null);const [sso, setSso] = useState<{ sso_enabled: boolean; provider: string; login_label: string; local_login_enabled: boolean } | null>(null);+ const [challenge, setChallenge] = useState<MfaChallenge | null>(null);+ const [code, setCode] = useState('');+ const [enrolment, setEnrolment] = useState<MfaEnrollment | null>(null);+ const [recoveryCodes, setRecoveryCodes] = useState<string[] | null>(null);// An SSO round-trip lands here with the session in the fragment; consume// it before the stored-token redirect below can read a still-empty store.@@ -126,7 +138,14 @@ async function landingRoute(requested: string): Promise<string> {setError(null);try {- await authApi.login(email.trim(), password);+ const result = await authApi.login(email.trim(), password);+ // The password was right and no session was issued: this account, or+ // this tenant, requires a second factor.+ if (isMfaChallenge(result)) {+ setChallenge(result);+ setPhase('idle');+ return;+ }setPhase('success');router.replace(await landingRoute(next));} catch (err) {@@ -142,6 +161,53 @@ async function landingRoute(requested: string): Promise<string> {}};+ const beginEnrolment = async () => {+ if (!challenge || phase === 'pending') return;+ setPhase('pending');+ setError(null);+ try {+ setEnrolment(await mfaApi.enrollBegin(challenge.mfa_token));+ setPhase('idle');+ } catch (err) {+ setPhase('error');+ setError(err instanceof Error ? err.message : 'Could not start enrolment.');+ }+ };++ const submitCode = async (event: React.FormEvent) => {+ event.preventDefault();+ if (!challenge || phase === 'pending') return;+ setPhase('pending');+ setError(null);+ try {+ // Enrolling and verifying are different endpoints. The first+ // confirms a secret the user has just scanned and signs them in; the+ // second completes a sign-in against a factor they already hold.+ if (enrolment) {+ const confirmed = await mfaApi.enrollConfirm(code.trim(), challenge.mfa_token);+ setRecoveryCodes(confirmed.recovery_codes);+ if (confirmed.access_token) {+ await authApi.adoptSession(confirmed.access_token, confirmed.refresh_token ?? '');+ }+ setPhase('success');+ return;+ }+ await authApi.completeMfa(challenge.mfa_token, code.trim());+ setPhase('success');+ router.replace(await landingRoute(next));+ } catch (err) {+ setPhase('error');+ const message = err instanceof Error ? err.message : 'Verification failed.';+ // A challenge is short-lived, and "that code is not valid" is the+ // wrong thing to tell someone whose five minutes ran out.+ setError(+ /expired/i.test(message)+ ? 'That sign-in attempt expired. Enter your password again.'+ : 'That code is not valid. Check your authenticator, or use a recovery code.',+ );+ }+ };+const useDemo = () => {setEmail(DEMO_EMAIL);setPassword(DEMO_PASSWORD);@@ -207,6 +273,134 @@ async function landingRoute(requested: string): Promise<string> {</div>)}+ {/* Second factor. Replaces the password form rather than sitting+ beside it: the password has already been accepted, and leaving+ it on screen invites someone to retype it instead of reading+ their authenticator. */}+ {challenge ? (+ <form onSubmit={submitCode} className="space-y-4" noValidate data-testid="mfa-challenge">+ <div className="rounded-xl border border-zinc-800 bg-zinc-900/60 px-4 py-3 text-sm text-zinc-300">+ {challenge.mfa_enrollment_required+ ? 'Your organisation requires a second factor and this account has not set one up yet. Finish setting it up to sign in.'+ : 'Enter the 6-digit code from your authenticator app, or one of your recovery codes.'}+ </div>++ {/* Enrolment happens here rather than behind a link to+ /settings/mfa: this user has a correct password and no+ session, so every authenticated route would bounce them+ straight back to this page. */}+ {challenge.mfa_enrollment_required && !enrolment ? (+ <button+ type="button"+ onClick={beginEnrolment}+ disabled={phase === 'pending'}+ className="w-full inline-flex items-center justify-center rounded-xl bg-indigo-500 hover:bg-indigo-400 text-white font-medium py-3 px-4 transition disabled:bg-zinc-800 disabled:text-zinc-500"+ >+ {phase === 'pending' ? 'Preparing…' : 'Set up two-factor authentication'}+ </button>+ ) : (+ <>+ {enrolment ? (+ <div className="rounded-xl border border-zinc-800 bg-zinc-900/60 px-4 py-3 space-y-2">+ <p className="text-xs text-zinc-400">+ Add this key to your authenticator app, then enter the code it shows.+ </p>+ <code className="block break-all rounded-lg bg-zinc-950 px-3 py-2 text-xs tracking-wider text-indigo-300">+ {enrolment.secret}+ </code>+ <a+ href={enrolment.otpauth_uri}+ className="inline-block text-xs text-indigo-400 hover:text-indigo-300 underline-offset-2 hover:underline"+ >+ Open in your authenticator app+ </a>+ </div>+ ) : null}++ {recoveryCodes ? (+ <div className="rounded-xl border border-amber-500/40 bg-amber-500/5 px-4 py-3 space-y-2">+ <p className="text-xs font-medium text-amber-300">+ Save these recovery codes. They are shown once.+ </p>+ <ul className="grid grid-cols-2 gap-1 font-mono text-[11px] text-zinc-300">+ {recoveryCodes.map((rc) => (+ <li key={rc}>{rc}</li>+ ))}+ </ul>+ </div>+ ) : null}++ <label className="block">+ <span className="block text-xs uppercase tracking-wider text-zinc-500 mb-2">+ Verification code+ </span>+ <input+ type="text"+ // `one-time-code` is what lets a phone offer the code+ // from the notification shade; without it the user+ // switches apps and loses the page on iOS.+ autoComplete="one-time-code"+ inputMode="text"+ autoCapitalize="characters"+ spellCheck={false}+ autoFocus+ placeholder="123456"+ value={code}+ onChange={(e) => setCode(e.target.value)}+ disabled={phase === 'pending'}+ required+ className="w-full bg-zinc-900 border border-zinc-800 rounded-xl px-4 py-3 text-sm tracking-[0.3em] text-zinc-100 placeholder:tracking-normal placeholder:text-zinc-600 focus:outline-none focus:ring-2 focus:ring-indigo-500/50 focus:border-indigo-500/50 disabled:opacity-60"+ />+ </label>+ {/* Navigating automatically would take the recovery+ codes off the screen the moment they appeared, and+ they are shown exactly once. */}+ {recoveryCodes ? (+ <button+ type="button"+ onClick={async () => router.replace(await landingRoute(next))}+ className="w-full bg-indigo-500 hover:bg-indigo-400 text-white font-medium rounded-xl py-3 px-4 transition"+ >+ I have saved my recovery codes — continue+ </button>+ ) : (+ <button+ type="submit"+ disabled={phase === 'pending' || !code}+ className="w-full bg-indigo-500 hover:bg-indigo-400 active:bg-indigo-600 text-white font-medium rounded-xl py-3 px-4 transition disabled:bg-zinc-800 disabled:text-zinc-500"+ >+ {phase === 'pending' ? 'Verifying…' : enrolment ? 'Confirm' : 'Verify'}+ </button>+ )}+ </>+ )}++ {error ? (+ <div+ role="alert"+ className="rounded-lg border border-red-500/40 bg-red-500/10 px-3 py-2.5 text-xs text-red-300"+ >+ {error}+ </div>+ ) : null}++ <button+ type="button"+ onClick={() => {+ setChallenge(null);+ setCode('');+ setError(null);+ setPassword('');+ setEnrolment(null);+ setRecoveryCodes(null);+ }}+ className="w-full text-xs text-zinc-500 hover:text-zinc-300 underline-offset-2 hover:underline"+ >+ Start over+ </button>+ </form>+ ) : (+ <>{/* Form */}{sso?.sso_enabled && (<div className="mb-4">@@ -308,6 +502,8 @@ async function landingRoute(requested: string): Promise<string> {</div>) : null}</form>+ </>+ )}{/* Footer hints */}<div className="mt-8 space-y-3 text-center">diff --git a/apps/web/src/components/demo/DemoAutoLogin.tsx b/apps/web/src/components/demo/DemoAutoLogin.tsxindex db7f73b53..5ab84e816 100644--- a/apps/web/src/components/demo/DemoAutoLogin.tsx+++ b/apps/web/src/components/demo/DemoAutoLogin.tsx@@ -28,7 +28,7 @@import { useEffect } from 'react';import { useSWRConfig } from 'swr';-import { authApi } from '@/lib/api';+import { authApi, isMfaChallenge } from '@/lib/api';import { isDemoMode } from '@/lib/demoMode';// No fallback literals. These are inlined by Next at build time wherever they@@ -55,8 +55,12 @@ export function DemoAutoLogin() {let cancelled = false;(async () => {try {- await authApi.login(DEMO_EMAIL, DEMO_PASSWORD);+ const result = await authApi.login(DEMO_EMAIL, DEMO_PASSWORD);if (cancelled) return;+ // A demo tenant that requires a second factor cannot be+ // auto-signed-in, and pretending otherwise would refetch every SWR+ // key with no credential and render the page as if it were empty.+ if (isMfaChallenge(result)) return;// Force every SWR key on the page to refetch with the new bearer// token. Passing `() => true` matches all keys; `undefined` data// tells SWR to drop its cache entry and rerun the fetcher.diff --git a/apps/web/src/components/layout/Sidebar.tsx b/apps/web/src/components/layout/Sidebar.tsxindex a0bc9194c..6994c1458 100644--- a/apps/web/src/components/layout/Sidebar.tsx+++ b/apps/web/src/components/layout/Sidebar.tsx@@ -324,6 +324,11 @@ const navSections: NavSection[] = [href: '/settings/rbac',icon: <ShieldIcon />,},+ {+ label: 'Two-factor auth',+ href: '/settings/mfa',+ icon: <ShieldIcon />,+ },{label: 'Compliance',href: '/compliance',diff --git a/apps/web/src/components/layout/TopBar.tsx b/apps/web/src/components/layout/TopBar.tsxindex 5e2f613b3..f13150729 100644--- a/apps/web/src/components/layout/TopBar.tsx+++ b/apps/web/src/components/layout/TopBar.tsx@@ -15,6 +15,7 @@ import { useTenant } from './TenantProvider';const routeLabels: Record<string, { title: string; description: string }> = {'/detection/catalog': { title: 'Detection Catalog', description: 'Curated rule packs and templates' },'/settings/rbac': { title: 'Roles & Permissions', description: 'Access control and team management' },+ '/settings/mfa': { title: 'Two-factor authentication', description: 'Your second factor, and whether this tenant requires one' },'/settings/users': { title: 'Users', description: 'Member and role management' },'/dashboard': { title: 'Dashboard', description: 'SOC overview and metrics' },'/alerts': { title: 'Alerts', description: 'Security alerts and incidents' },diff --git a/apps/web/src/components/onboarding/StartHero.tsx b/apps/web/src/components/onboarding/StartHero.tsxindex b61f9b7e0..d03ee144d 100644--- a/apps/web/src/components/onboarding/StartHero.tsx+++ b/apps/web/src/components/onboarding/StartHero.tsx@@ -5,7 +5,7 @@ import Link from 'next/link';import { useState } from 'react';import { motion } from 'framer-motion';import toast from 'react-hot-toast';-import { authApi } from '@/lib/api';+import { authApi, isMfaChallenge } from '@/lib/api';import { demoDeeplink } from '@/lib/demoMode';import { CONNECTOR_COUNT } from '@/data/connectorCount';@@ -55,7 +55,13 @@ export function StartHero() {try {if (!authApi.isAuthenticated()) {- await authApi.login(email, password);+ const result = await authApi.login(email, password);+ // The tenant requires a second factor, so there is no session to+ // push into. `/login` is where the code is entered.+ if (isMfaChallenge(result)) {+ router.push(`/login?next=${encodeURIComponent(target)}`);+ return;+ }}router.push(target);} catch (err) {diff --git a/apps/web/src/components/settings/MfaView.tsx b/apps/web/src/components/settings/MfaView.tsxnew file mode 100644index 000000000..80524940c--- /dev/null+++ b/apps/web/src/components/settings/MfaView.tsx@@ -0,0 +1,253 @@+'use client';++/**+ * Two-factor authentication: your own factor, and the tenant policy.+ *+ * Fix pass 4.2. The console had no second factor at all — passkeys existed+ * on the mobile responder only, so the surface an analyst works from all+ * day was single-factor and no administrator could change that.+ *+ * Enrolling from a *sign-in challenge* is not done here. A user whose+ * tenant has just started requiring a factor holds a correct password and+ * no session, so every authenticated route bounces them to `/login` — and+ * that is where their enrolment lives.+ */++import { useCallback, useEffect, useState } from 'react';+import { mfaApi, type MfaEnrollment, type MfaStatus } from '@/lib/api';++type Phase = 'idle' | 'pending';++export function MfaView() {+ const [status, setStatus] = useState<MfaStatus | null>(null);+ const [loadError, setLoadError] = useState<string | null>(null);+ const [enrolment, setEnrolment] = useState<MfaEnrollment | null>(null);+ const [recoveryCodes, setRecoveryCodes] = useState<string[] | null>(null);+ const [code, setCode] = useState('');+ const [phase, setPhase] = useState<Phase>('idle');+ const [error, setError] = useState<string | null>(null);+ const [policyError, setPolicyError] = useState<string | null>(null);++ const refresh = useCallback(async () => {+ try {+ setStatus(await mfaApi.status());+ setLoadError(null);+ } catch (err) {+ // An honest failure, not a zeroed card: "not enrolled" and "we could+ // not find out" are different answers and only one of them is safe+ // to act on.+ setStatus(null);+ setLoadError(err instanceof Error ? err.message : 'Could not read your MFA status.');+ }+ }, []);++ useEffect(() => {+ void refresh();+ }, [refresh]);++ const begin = async () => {+ setPhase('pending');+ setError(null);+ try {+ setEnrolment(await mfaApi.enrollBegin());+ } catch (err) {+ setError(err instanceof Error ? err.message : 'Could not start enrolment.');+ } finally {+ setPhase('idle');+ }+ };++ const confirm = async (event: React.FormEvent) => {+ event.preventDefault();+ setPhase('pending');+ setError(null);+ try {+ const confirmed = await mfaApi.enrollConfirm(code.trim());+ setRecoveryCodes(confirmed.recovery_codes);+ setEnrolment(null);+ setCode('');+ await refresh();+ } catch {+ setError('That code is not valid. Check that your phone’s clock is correct.');+ } finally {+ setPhase('idle');+ }+ };++ const disable = async (event: React.FormEvent) => {+ event.preventDefault();+ setPhase('pending');+ setError(null);+ try {+ await mfaApi.disable(code.trim());+ setCode('');+ setRecoveryCodes(null);+ await refresh();+ } catch {+ setError('That code is not valid, so the factor was not removed.');+ } finally {+ setPhase('idle');+ }+ };++ const setPolicy = async (requireTotp: boolean) => {+ setPolicyError(null);+ try {+ await mfaApi.setPolicy(requireTotp);+ await refresh();+ } catch (err) {+ const message = err instanceof Error ? err.message : '';+ setPolicyError(+ /403/.test(message)+ ? 'Changing the tenant policy needs the settings:write permission.'+ : 'Could not change the tenant policy.',+ );+ }+ };++ return (+ <div className="space-y-6 max-w-2xl">+ <section className="rounded-xl border border-zinc-800 bg-zinc-900/40 p-5 space-y-4">+ <header>+ <h2 className="text-base font-semibold text-zinc-100">Two-factor authentication</h2>+ <p className="text-sm text-zinc-400 mt-1">+ A time-based code from an authenticator app, in addition to your password.+ </p>+ </header>++ {loadError ? (+ <p role="alert" className="text-sm text-red-300">+ {loadError}+ </p>+ ) : status === null ? (+ <p className="text-sm text-zinc-500">Checking…</p>+ ) : (+ <>+ <p className="text-sm text-zinc-300">+ {status.enrolled+ ? `Enrolled. ${status.recovery_codes_remaining} recovery code${status.recovery_codes_remaining === 1 ? '' : 's'} left.`+ : 'Not enrolled.'}+ {status.tenant_requires_totp ? ' Your organisation requires it.' : ''}+ </p>++ {!status.enrolled && !enrolment ? (+ <button+ type="button"+ onClick={begin}+ disabled={phase === 'pending'}+ className="rounded-lg bg-indigo-500 hover:bg-indigo-400 px-4 py-2 text-sm font-medium text-white transition disabled:bg-zinc-800 disabled:text-zinc-500"+ >+ Set up+ </button>+ ) : null}++ {enrolment ? (+ <form onSubmit={confirm} className="space-y-3">+ <p className="text-xs text-zinc-400">+ Add this key to your authenticator app, then enter the code it shows.+ </p>+ <code className="block break-all rounded-lg bg-zinc-950 px-3 py-2 text-xs tracking-wider text-indigo-300">+ {enrolment.secret}+ </code>+ <a+ href={enrolment.otpauth_uri}+ className="inline-block text-xs text-indigo-400 hover:text-indigo-300 underline-offset-2 hover:underline"+ >+ Open in your authenticator app+ </a>+ <input+ type="text"+ autoComplete="one-time-code"+ placeholder="123456"+ value={code}+ onChange={(e) => setCode(e.target.value)}+ className="w-full rounded-lg border border-zinc-800 bg-zinc-900 px-3 py-2 text-sm text-zinc-100"+ />+ <button+ type="submit"+ disabled={phase === 'pending' || !code}+ className="rounded-lg bg-indigo-500 hover:bg-indigo-400 px-4 py-2 text-sm font-medium text-white transition disabled:bg-zinc-800 disabled:text-zinc-500"+ >+ Confirm+ </button>+ </form>+ ) : null}++ {recoveryCodes ? (+ <div className="rounded-lg border border-amber-500/40 bg-amber-500/5 px-4 py-3 space-y-2">+ <p className="text-xs font-medium text-amber-300">+ Save these recovery codes. They are shown once and each works once.+ </p>+ <ul className="grid grid-cols-2 gap-1 font-mono text-[11px] text-zinc-300">+ {recoveryCodes.map((rc) => (+ <li key={rc}>{rc}</li>+ ))}+ </ul>+ </div>+ ) : null}++ {status.enrolled && !enrolment ? (+ <form onSubmit={disable} className="space-y-2 border-t border-zinc-800 pt-4">+ <p className="text-xs text-zinc-500">+ Removing your factor needs a current code, so a stolen session cannot strip the+ thing protecting it.+ </p>+ <div className="flex gap-2">+ <input+ type="text"+ autoComplete="one-time-code"+ placeholder="Code or recovery code"+ value={code}+ onChange={(e) => setCode(e.target.value)}+ className="flex-1 rounded-lg border border-zinc-800 bg-zinc-900 px-3 py-2 text-sm text-zinc-100"+ />+ <button+ type="submit"+ disabled={phase === 'pending' || !code}+ className="rounded-lg border border-red-500/40 bg-red-500/10 px-4 py-2 text-sm font-medium text-red-300 transition hover:bg-red-500/20 disabled:opacity-50"+ >+ Remove+ </button>+ </div>+ </form>+ ) : null}++ {error ? (+ <p role="alert" className="text-sm text-red-300">+ {error}+ </p>+ ) : null}+ </>+ )}+ </section>++ <section className="rounded-xl border border-zinc-800 bg-zinc-900/40 p-5 space-y-3">+ <header>+ <h2 className="text-base font-semibold text-zinc-100">Require it across this tenant</h2>+ <p className="text-sm text-zinc-400 mt-1">+ Everyone signs in with a second factor. Members who have not enrolled are asked to set+ one up at their next sign-in rather than being locked out.+ </p>+ </header>+ <div className="flex items-center gap-3">+ <button+ type="button"+ onClick={() => setPolicy(!(status?.tenant_requires_totp ?? false))}+ disabled={status === null}+ className="rounded-lg border border-zinc-700 bg-zinc-800/60 px-4 py-2 text-sm font-medium text-zinc-200 transition hover:bg-zinc-800 disabled:opacity-50"+ >+ {status?.tenant_requires_totp ? 'Stop requiring' : 'Require for everyone'}+ </button>+ <span className="text-xs text-zinc-500">+ {status?.tenant_requires_totp ? 'Currently required' : 'Currently optional'}+ </span>+ </div>+ {policyError ? (+ <p role="alert" className="text-sm text-red-300">+ {policyError}+ </p>+ ) : null}+ </section>+ </div>+ );+}diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.tsindex ebccf9b5e..230a74131 100644--- a/apps/web/src/lib/api.ts+++ b/apps/web/src/lib/api.ts@@ -424,6 +424,24 @@ export interface LoginResult extends TokenResponse {user: AuthUser;}+/**+ * What `POST /auth/login` answers when the password was right and a second+ * factor is outstanding (HTTP 202). Two distinct cases, and conflating them+ * sends the user to the wrong screen: `mfa_required` means "type a code",+ * `mfa_enrollment_required` means "your tenant now requires a factor you+ * have never set up".+ */+export interface MfaChallenge {+ mfa_token: string;+ mfa_required?: boolean;+ mfa_enrollment_required?: boolean;+ methods?: string[];+}++export function isMfaChallenge(result: LoginResult | MfaChallenge): result is MfaChallenge {+ return 'mfa_token' in result && !('user' in result);+}+function persistAuth(tokens: TokenResponse, user: AuthUser): void {if (typeof window === 'undefined') return;try {@@ -462,11 +480,22 @@ export const authApi = {* helper attaches the JWT automatically and a single login covers desktop* + mobile.*/- async login(email: string, password: string): Promise<LoginResult> {- const tokens = await request<TokenResponse>('/api/v1/auth/login', {+ async login(email: string, password: string): Promise<LoginResult | MfaChallenge> {+ const tokens = await request<TokenResponse & Partial<MfaChallenge>>('/api/v1/auth/login', {method: 'POST',body: JSON.stringify({ email, password }),});+ // HTTP 202: the password was accepted and no session was issued. The+ // caller has to run the second factor; storing anything here would+ // persist a token that does not exist.+ if (!tokens.access_token && tokens.mfa_token) {+ return {+ mfa_token: tokens.mfa_token,+ mfa_required: tokens.mfa_required,+ mfa_enrollment_required: tokens.mfa_enrollment_required,+ methods: tokens.methods,+ };+ }// Stash the access token now so the `me` request flows through the// standard `Authorization: Bearer …` path in `request()`.if (typeof window !== 'undefined') {@@ -560,6 +589,53 @@ export const authApi = {}},+ /**+ * Finish a sign-in that `POST /auth/login` answered with 202.+ *+ * Takes a TOTP code or a recovery code — the API decides which by trying+ * the authenticator first, so the user types whichever they have without+ * telling the console which it is.+ */+ async completeMfa(mfaToken: string, code: string): Promise<LoginResult> {+ const tokens = await request<TokenResponse>('/api/v1/auth/mfa/verify', {+ method: 'POST',+ body: JSON.stringify({ mfa_token: mfaToken, code }),+ });+ if (typeof window !== 'undefined') {+ try {+ window.localStorage.setItem(AUTH_TOKEN_KEY, tokens.access_token);+ } catch {+ /* ignore */+ }+ }+ const user = await request<AuthUser>('/api/v1/auth/me');+ persistAuth(tokens, user);+ return { ...tokens, user };+ },++ /**+ * Adopt a session handed back by a non-login endpoint.+ *+ * `POST /auth/mfa/enroll/confirm` returns a token pair when the+ * enrolment completed from a sign-in challenge, so the user is not made+ * to authenticate a second time with a code they just proved.+ */+ async adoptSession(accessToken: string, refreshToken: string): Promise<AuthUser> {+ if (typeof window !== 'undefined') {+ try {+ window.localStorage.setItem(AUTH_TOKEN_KEY, accessToken);+ } catch {+ /* ignore */+ }+ }+ const user = await request<AuthUser>('/api/v1/auth/me');+ persistAuth(+ { access_token: accessToken, refresh_token: refreshToken, token_type: 'bearer', expires_in: 0 },+ user,+ );+ return user;+ },+/** Merge user preferences on the server (theme, layout, etc.). */async updateUserPreferences(preferences: Record<string, unknown>): Promise<AuthUser> {const response = await fetch(`${API_BASE}/api/v1/auth/me/preferences`, {@@ -577,6 +653,67 @@ export const authApi = {},};+// ─── Multi-factor authentication ─────────────────────────────────────────────+//+// Every call takes an optional `mfaToken`. It is how a user whose tenant+// has just started requiring a second factor enrols: they hold a correct+// password and no session, so there is no bearer credential to send and+// the challenge stands in for one. With a session, omit it.++export interface MfaStatus {+ enrolled: boolean;+ tenant_requires_totp: boolean;+ recovery_codes_remaining: number;+}++export interface MfaEnrollment {+ secret: string;+ otpauth_uri: string;+}++export interface MfaConfirmed {+ recovery_codes: string[];+ access_token?: string | null;+ refresh_token?: string | null;+}++export const mfaApi = {+ status: (): Promise<MfaStatus> => request('/api/v1/auth/mfa/status'),++ enrollBegin: (mfaToken?: string): Promise<MfaEnrollment> =>+ request('/api/v1/auth/mfa/enroll/begin', {+ method: 'POST',+ body: JSON.stringify(mfaToken ? { mfa_token: mfaToken } : {}),+ }),++ enrollConfirm: (code: string, mfaToken?: string): Promise<MfaConfirmed> =>+ request('/api/v1/auth/mfa/enroll/confirm', {+ method: 'POST',+ body: JSON.stringify(mfaToken ? { code, mfa_token: mfaToken } : { code }),+ }),++ /** Remove your own factor. The API requires a current code, so a stolen+ * session cannot strip the thing protecting it. */+ disable: (code: string): Promise<void> =>+ request('/api/v1/auth/mfa', { method: 'DELETE', body: JSON.stringify({ code }) }),++ /** Administrative reset for a colleague who lost their phone. Audited+ * with the reason, which is why the reason is required here too. */+ reset: (userId: string, reason: string): Promise<{ status: string }> =>+ request(`/api/v1/auth/mfa/reset/${encodeURIComponent(userId)}`, {+ method: 'POST',+ body: JSON.stringify({ reason }),+ }),++ policy: (): Promise<{ require_totp: boolean }> => request('/api/v1/auth/mfa/policy'),++ setPolicy: (requireTotp: boolean): Promise<{ require_totp: boolean }> =>+ request('/api/v1/auth/mfa/policy', {+ method: 'PUT',+ body: JSON.stringify({ require_totp: requireTotp }),+ }),+};+// ─── Tenants & MSSP ─────────────────────────────────────────────────────────//// The W5 tenant switcher needs to know:diff --git a/docs/openapi.yaml b/docs/openapi.yamlindex cedf3c3ce..dfeb95ada 100644--- a/docs/openapi.yaml+++ b/docs/openapi.yaml@@ -25,6 +25,20 @@ paths:application/json:schema:$ref: '#/components/schemas/TokenResponse'+ '202':+ description: The password was accepted and a second factor is outstanding.+ The body carries `mfa_token` plus either `mfa_required` (complete it at+ `POST /auth/mfa/verify`) or `mfa_enrollment_required` (the tenant requires+ a factor this account has not enrolled; enrol at `POST /auth/mfa/enroll/begin`).+ No session is issued.+ content:+ application/json:+ example:+ mfa_required: true+ mfa_token: eyJ…+ methods:+ - totp+ - recovery_code'422':description: Validation Errorcontent:@@ -128,6 +142,245 @@ paths:$ref: '#/components/schemas/HTTPValidationError'security:- HTTPBearer: []+ /api/v1/auth/mfa/status:+ get:+ tags:+ - auth+ - mfa+ summary: Mfa Status+ description: Whether this user holds a second factor, and whether they must.+ operationId: mfa_status_api_v1_auth_mfa_status_get+ responses:+ '200':+ description: Successful Response+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/MfaStatus'+ security:+ - HTTPBearer: []+ /api/v1/auth/mfa/enroll/begin:+ post:+ tags:+ - auth+ - mfa+ summary: Enroll Begin+ description: 'Mint a secret and return it once, with the URI an app scans.+++ Re-enrolling replaces an *unconfirmed* row and refuses a confirmed one:++ silently rotating a working factor would turn a mis-click into a++ lockout, and `DELETE /auth/mfa` is the deliberate way to remove one.'+ operationId: enroll_begin_api_v1_auth_mfa_enroll_begin_post+ responses:+ '200':+ description: Successful Response+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/EnrollBegin'+ security:+ - HTTPBearer: []+ /api/v1/auth/mfa/enroll/confirm:+ post:+ tags:+ - auth+ - mfa+ summary: Enroll Confirm+ description: 'Prove the secret arrived, then hand over the recovery codes.+++ Confirmation is what makes the row a credential. Without it, an++ enrolment begun on a device that never received the QR code would lock++ the user out at their next sign-in.'+ operationId: enroll_confirm_api_v1_auth_mfa_enroll_confirm_post+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ConfirmRequest'+ required: true+ responses:+ '200':+ description: Successful Response+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/EnrollConfirmed'+ '422':+ description: Validation Error+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/HTTPValidationError'+ security:+ - HTTPBearer: []+ /api/v1/auth/mfa/verify:+ post:+ tags:+ - auth+ - mfa+ summary: Verify+ description: Complete a sign-in that `POST /auth/login` answered with 202.+ operationId: verify_api_v1_auth_mfa_verify_post+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/VerifyRequest'+ required: true+ responses:+ '200':+ description: Successful Response+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/SessionTokens'+ '422':+ description: Validation Error+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/HTTPValidationError'+ /api/v1/auth/mfa:+ delete:+ tags:+ - auth+ - mfa+ summary: Disable+ description: 'Remove your own second factor, proving you still hold it.+++ A current code is required. Without it, a stolen session could strip++ the factor it was supposed to be protected by, which makes the factor++ worth exactly as much as the session.'+ operationId: disable_api_v1_auth_mfa_delete+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/DisableRequest'+ required: true+ responses:+ '204':+ description: Successful Response+ '422':+ description: Validation Error+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/HTTPValidationError'+ security:+ - HTTPBearer: []+ /api/v1/auth/mfa/reset/{user_id}:+ post:+ tags:+ - auth+ - mfa+ summary: Reset+ description: "Remove somebody else's second factor. The lost-phone path.\n\n\+ Three constraints, each of which is the reason an administrative reset\nis\+ \ normally the weakest link in an MFA deployment:\n\n* the target must be\+ \ in the caller's own tenant, resolved from the\n authenticated principal\+ \ and never from the request;\n* a `reason` is required and lands in the audit\+ \ row, because \"an admin\n reset it\" without one is not an answer to \"\+ who removed this and why\";\n* an administrator may not reset **their own**\+ \ factor here. That would\n be a self-disable with no code, bypassing `DELETE\+ \ /auth/mfa`."+ operationId: reset_api_v1_auth_mfa_reset__user_id__post+ security:+ - HTTPBearer: []+ parameters:+ - name: user_id+ in: path+ required: true+ schema:+ type: string+ format: uuid+ title: User Id+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ResetRequest'+ responses:+ '200':+ description: Successful Response+ content:+ application/json:+ schema:+ type: object+ additionalProperties:+ type: string+ title: Response Reset Api V1 Auth Mfa Reset User Id Post+ '422':+ description: Validation Error+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/HTTPValidationError'+ /api/v1/auth/mfa/policy:+ get:+ tags:+ - auth+ - mfa+ summary: Get Policy+ description: 'Readable by any member: a user is entitled to know what their+ own++ tenant requires of them.'+ operationId: get_policy_api_v1_auth_mfa_policy_get+ responses:+ '200':+ description: Successful Response+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/MfaPolicy'+ security:+ - HTTPBearer: []+ put:+ tags:+ - auth+ - mfa+ summary: Put Policy+ description: 'Require, or stop requiring, a second factor across this tenant.+++ The tenant is the caller''s, never a parameter. A row is written only++ when an administrator asks for one, so a tenant that has never visited++ this endpoint has no row and is not enforced.'+ operationId: put_policy_api_v1_auth_mfa_policy_put+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/MfaPolicy'+ required: true+ responses:+ '200':+ description: Successful Response+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/MfaPolicy'+ '422':+ description: Validation Error+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/HTTPValidationError'+ security:+ - HTTPBearer: []/api/v1/api-keys:get:tags:@@ -22648,6 +22901,22 @@ components:- medianConfidence- lowConfidencetitle: ConfidenceSummary+ ConfirmRequest:+ properties:+ mfa_token:+ anyOf:+ - type: string+ - type: 'null'+ title: Mfa Token+ code:+ type: string+ maxLength: 64+ minLength: 1+ title: Code+ type: object+ required:+ - code+ title: ConfirmRequestConnectorHealthOut:properties:total:@@ -24408,6 +24677,17 @@ components:- created_at- updated_attitle: DetectionRuleResponse+ DisableRequest:+ properties:+ code:+ type: string+ maxLength: 64+ minLength: 1+ title: Code+ type: object+ required:+ - code+ title: DisableRequestDiscoverResponse:properties:discovered:@@ -24903,6 +25183,40 @@ components:required:- reasontitle: EngageRequest+ EnrollBegin:+ properties:+ secret:+ type: string+ title: Secret+ otpauth_uri:+ type: string+ title: Otpauth Uri+ type: object+ required:+ - secret+ - otpauth_uri+ title: EnrollBegin+ EnrollConfirmed:+ properties:+ recovery_codes:+ items:+ type: string+ type: array+ title: Recovery Codes+ access_token:+ anyOf:+ - type: string+ - type: 'null'+ title: Access Token+ refresh_token:+ anyOf:+ - type: string+ - type: 'null'+ title: Refresh Token+ type: object+ required:+ - recovery_codes+ title: EnrollConfirmedEntityNeighborsResponse:properties:entity_id:@@ -28815,6 +29129,32 @@ components:- connector_count- health_scoretitle: MetricsOut+ MfaPolicy:+ properties:+ require_totp:+ type: boolean+ title: Require Totp+ type: object+ required:+ - require_totp+ title: MfaPolicy+ MfaStatus:+ properties:+ enrolled:+ type: boolean+ title: Enrolled+ tenant_requires_totp:+ type: boolean+ title: Tenant Requires Totp+ recovery_codes_remaining:+ type: integer+ title: Recovery Codes Remaining+ type: object+ required:+ - enrolled+ - tenant_requires_totp+ - recovery_codes_remaining+ title: MfaStatusMiniTimelineEvent:properties:id:@@ -32018,6 +32358,17 @@ components:required:- nametitle: ReportDefinitionBody+ ResetRequest:+ properties:+ reason:+ type: string+ maxLength: 500+ minLength: 3+ title: Reason+ type: object+ required:+ - reason+ title: ResetRequestRetentionOut:properties:raw_events_days:@@ -33906,6 +34257,27 @@ components:- rotated_from_id- activetitle: ScimTokenOut+ SessionTokens:+ properties:+ access_token:+ type: string+ title: Access Token+ refresh_token:+ type: string+ title: Refresh Token+ token_type:+ type: string+ title: Token Type+ default: bearer+ expires_in:+ type: integer+ title: Expires In+ default: 1800+ type: object+ required:+ - access_token+ - refresh_token+ title: SessionTokensSetupStep:properties:key:@@ -37044,6 +37416,21 @@ components:pass-through would let a caller supply their own vendor credential andhave the read run somewhere else entirely.'+ VerifyRequest:+ properties:+ mfa_token:+ type: string+ title: Mfa Token+ code:+ type: string+ maxLength: 64+ minLength: 1+ title: Code+ type: object+ required:+ - mfa_token+ - code+ title: VerifyRequestVulnerabilityCreate:properties:asset_id:diff --git a/scripts/check_route_auth.py b/scripts/check_route_auth.pyindex f4287972d..d9692757e 100644--- a/scripts/check_route_auth.py+++ b/scripts/check_route_auth.py@@ -187,6 +187,28 @@ IN_BAND_CREDENTIAL_ROUTES: dict[str, tuple[str, str]] = {"the query token is an HMAC-signed, expiring payload minted by the ChatOps executor and re-verified here before anything is ""recorded",),+ # -- the second factor, which is part of establishing a credential ------+ #+ # All three verify in band through `read_challenge`, which refuses a+ # token that is not of type `mfa_challenge` — so an access token+ # presented here is rejected rather than honoured, and a live session+ # cannot mint another one with no code. `/enroll/*` additionally accept+ # an ordinary bearer, through `get_current_user`; the anonymous arm is+ # what lets a user whose tenant has just started requiring a factor+ # enrol at all, since they hold a correct password and no session.+ "services/api/app/api/v1/endpoints/mfa.py::verify": (+ "read_challenge",+ "completes the sign-in that POST /auth/login answered with 202; the challenge token it takes is the credential",+ ),+ "services/api/app/api/v1/endpoints/mfa.py::enroll_begin": (+ "read_challenge",+ "a session when one exists, otherwise the enrolment challenge from a 202 sign-in -- the path that stops a tenant "+ "locking out every unenrolled member the moment it turns enforcement on",+ ),+ "services/api/app/api/v1/endpoints/mfa.py::enroll_confirm": (+ "read_challenge",+ "the other half of the same enrolment; it proves the secret arrived before the row becomes a credential",+ ),"services/api/app/api/v1/endpoints/email_approval.py::email_decide": ("verify_token","one-click email approval; the link carries a signed single-use token verified before the decision is applied",diff --git a/scripts/check_route_authz.py b/scripts/check_route_authz.pyindex 17ada3b60..11a40bbbe 100644--- a/scripts/check_route_authz.py+++ b/scripts/check_route_authz.py@@ -105,6 +105,18 @@ AUTHZ_CALLS = frozenset(# to satisfy a gate, which is how gates start being gamed."_admin_scope","_owner_scope",+ # A possession proof. `require_current_factor` refuses unless the+ # caller can still produce the account's second factor, which is an+ # authorization decision by any definition and a stronger one than a+ # role permission — it asks what the principal holds, not what their+ # role says.+ #+ # Added for the same reason as the two above rather than worked+ # around. The only route it guards is "remove my own second factor",+ # and no permission can be held by exactly its owner: bolting an+ # administrative one on would mean an analyst could not manage their+ # own factor, which is a worse design adopted to satisfy a gate.+ "require_current_factor",})diff --git a/services/api/app/api/v1/endpoints/auth.py b/services/api/app/api/v1/endpoints/auth.pyindex c3698bc4d..327035f69 100644--- a/services/api/app/api/v1/endpoints/auth.py+++ b/services/api/app/api/v1/endpoints/auth.py@@ -6,6 +6,7 @@ from datetime import UTC, datetimefrom typing import Anyfrom fastapi import APIRouter, HTTPException, Request, status+from fastapi.responses import JSONResponsefrom pydantic import BaseModel, EmailStrfrom sqlalchemy import select, update@@ -72,8 +73,22 @@ class PreferencesPatch(BaseModel):# docstring is published as the operation's `description` in# `docs/openapi.yaml`, and an API description should say what the endpoint# does, not what it used to do wrong.[email protected]("/login", response_model=TokenResponse)-async def login(request: LoginRequest, http_request: Request, db: DBSession) -> TokenResponse:+ "/login",+ response_model=TokenResponse,+ responses={+ 202: {+ "description": (+ "The password was accepted and a second factor is outstanding. The body carries "+ "`mfa_token` plus either `mfa_required` (complete it at `POST /auth/mfa/verify`) or "+ "`mfa_enrollment_required` (the tenant requires a factor this account has not enrolled; "+ "enrol at `POST /auth/mfa/enroll/begin`). No session is issued."+ ),+ "content": {"application/json": {"example": {"mfa_required": True, "mfa_token": "eyJ…", "methods": ["totp", "recovery_code"]}}},+ }+ },+)+async def login(request: LoginRequest, http_request: Request, db: DBSession) -> TokenResponse | JSONResponse:"""Authenticate with email/password, return JWT tokens."""throttle = get_login_throttle()source = client_ip(http_request)@@ -119,6 +134,15 @@ async def login(request: LoginRequest, http_request: Request, db: DBSession) ->await throttle.record_success(email=request.email, source_ip=source)+ # Fix pass 4.2. The password is one factor, and for an enrolled user or+ # an enforcing tenant it is no longer the whole answer. Answered as 202+ # rather than by widening the 200 body: `access_token` and+ # `refresh_token` are required fields of `TokenResponse`, and making+ # either optional is a break for every generated client.+ challenge = await mfa_challenge_for(db, user_id=user.id, tenant_id=user.tenant_id)+ if challenge is not None:+ return JSONResponse(status_code=status.HTTP_202_ACCEPTED, content=challenge)+# Update last loginawait db.execute(update(User).where(User.id == user.id).values(last_login=datetime.now(UTC)))@@ -137,6 +161,34 @@ async def login(request: LoginRequest, http_request: Request, db: DBSession) ->)+async def mfa_challenge_for(db: Any, *, user_id: uuid.UUID, tenant_id: uuid.UUID) -> dict[str, Any] | None:+ """What this account still owes before a session is issued, or `None`.++ Two cases and they are not the same thing. An enrolled user owes a+ code. A user in an enforcing tenant who has never enrolled owes an+ enrolment — refusing them instead would lock out every unenrolled user+ the moment an administrator turns the policy on, which is the whole+ tenant at once.++ A failure to read either table is **not** treated as "no MFA". That+ would fail open at the one place in the product where open is worst.+ """+ from app.api.v1.endpoints.mfa import has_confirmed_factor, mint_challenge, tenant_requires_totp++ if await has_confirmed_factor(db, user_id):+ return {+ "mfa_required": True,+ "mfa_token": mint_challenge(user_id=user_id, tenant_id=tenant_id, purpose="verify"),+ "methods": ["totp", "recovery_code"],+ }+ if await tenant_requires_totp(db, tenant_id):+ return {+ "mfa_enrollment_required": True,+ "mfa_token": mint_challenge(user_id=user_id, tenant_id=tenant_id, purpose="enroll"),+ }+ return None++def settings_dict() -> dict[str, str]:"""The SSO-related environment, read live so an operator can flip theflag without a redeploy. Anything unset reads as its safe default."""diff --git a/services/api/app/api/v1/endpoints/mfa.py b/services/api/app/api/v1/endpoints/mfa.pynew file mode 100644index 000000000..b36b04896--- /dev/null+++ b/services/api/app/api/v1/endpoints/mfa.py@@ -0,0 +1,694 @@+"""A second factor for the desktop console: enrolment, challenge, policy, reset.++Fix pass 4.2.++`POST /auth/login` verified a password and returned a token pair, and+nothing a user or an administrator could do made that insufficient.+Passkeys existed on `/responder/*` only, so the surface an analyst works+from all day was single-factor by construction.++The flow+--------+**Enrolment** (already signed in, or holding an enrolment challenge):++1. ``POST /auth/mfa/enroll/begin`` → a secret and an ``otpauth://`` URI+2. ``POST /auth/mfa/enroll/confirm`` → a code from that secret; returns the+ recovery codes, which exist in plaintext exactly once++**Sign-in**:++1. ``POST /auth/login`` with a correct password answers **202** and a+ short-lived challenge token instead of a session+2. ``POST /auth/mfa/verify`` with that token and a code (or a recovery+ code) returns the ordinary token pair++The 202 is deliberate. Extending the 200 body would have made+``access_token`` optional, which `scripts/openapi_diff.py` correctly calls+a break for every generated client; a 401 would collide with the console's+own ``handleUnauthorized``, which clears storage and bounces to `/login`.+202 reads as what it is — the credentials were accepted, something remains+to be done — and `fetch` treats it as a success, so the console reads the+body rather than an exception.++The challenge token+-------------------+Signed with ``SECRET_KEY`` like every other token, carrying+``type: "mfa_challenge"``. `get_current_user` requires ``type == "access"``,+so this authenticates no route: it is only an argument to the two handlers+below that look for it.++Enrolling under a policy you have not yet satisfied+---------------------------------------------------+When a tenant turns enforcement on, every user who has not enrolled holds+a correct password and no second factor. Refusing them outright locks out+the whole tenant at once, so the challenge token issued in that case+carries ``purpose: "enroll"`` and the two enrolment handlers accept it.++The trade-off is explicit: somebody who has stolen a password can enrol+*their own* authenticator before the real user does. It is bounded by the+password still being required, by the window being only until the real+user enrols, and by `mfa.enrolled` being audited with the source address —+and it is the trade every product that rolls MFA out to an existing user+base makes. The alternative, an administrator-issued enrolment ticket per+user, is a reasonable future addition and not a reason to ship a flow that+bricks a tenant.+"""++from __future__ import annotations++import logging+import uuid+from datetime import UTC, datetime, timedelta+from typing import Annotated, Any++import jwt+from fastapi import APIRouter, Depends, HTTPException, Request, Security, status+from fastapi.security import HTTPAuthorizationCredentials+from pydantic import BaseModel, Field+from sqlalchemy import text++from app.api.v1.deps import AuthUser, DBSession, bearer_scheme, get_current_user, require_permission+from app.core.config import settings+from app.core.security import create_access_token, create_refresh_token+from app.db.rls import set_rls_context+from app.security.credential_vault import CredentialVaultError, get_vault+from app.services import mfa as totp+from app.services.audit import emit_audit+from app.services.login_throttle import client_ip++logger = logging.getLogger(__name__)++router = APIRouter(prefix="/auth/mfa", tags=["auth", "mfa"])++CHALLENGE_TOKEN_TYPE = "mfa_challenge"+#: Long enough to open an authenticator app and read a code, short enough+#: that a challenge left in a browser's history is not a standing+#: half-credential.+CHALLENGE_TTL_SECONDS = 300+++def _sanitize(value: object, limit: int = 120) -> str:+ return str(value).replace("\r", "").replace("\n", " ")[:limit]+++def _issuer_label() -> str:+ """What the authenticator app shows beside the code."""+ return (getattr(settings, "PROJECT_NAME", None) or "AiSOC").strip() or "AiSOC"+++# ─── The challenge token ──────────────────────────────────────────────────────+++def mint_challenge(*, user_id: uuid.UUID, tenant_id: uuid.UUID, purpose: str) -> str:+ now = datetime.now(UTC)+ return jwt.encode(+ {+ "sub": str(user_id),+ "tenant_id": str(tenant_id),+ "purpose": purpose,+ "type": CHALLENGE_TOKEN_TYPE,+ "iat": now,+ "exp": now + timedelta(seconds=CHALLENGE_TTL_SECONDS),+ },+ settings.SECRET_KEY,+ algorithm=settings.ALGORITHM,+ )+++def read_challenge(token: str, *, expect_purpose: str | None = None) -> dict[str, Any]:+ try:+ payload = dict(jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM]))+ except jwt.PyJWTError as exc:+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="This sign-in attempt has expired. Sign in again.") from exc+ if payload.get("type") != CHALLENGE_TOKEN_TYPE:+ # An access token presented here would otherwise let a session that+ # is already authenticated mint a *second* one with no code.+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid sign-in challenge.")+ if expect_purpose is not None and payload.get("purpose") != expect_purpose:+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid sign-in challenge.")+ return payload+++# ─── Stored state ─────────────────────────────────────────────────────────────+++async def enrolment_row(db: Any, user_id: uuid.UUID) -> dict[str, Any] | None:+ row = (+ (+ await db.execute(+ text(+ "SELECT user_id, tenant_id, secret_encrypted, confirmed_at, last_used_step FROM aisoc_user_mfa WHERE user_id = :u"+ ).bindparams(u=user_id)+ )+ )+ .mappings()+ .first()+ )+ return dict(row) if row else None+++async def has_confirmed_factor(db: Any, user_id: uuid.UUID) -> bool:+ row = await enrolment_row(db, user_id)+ return bool(row and row["confirmed_at"])+++async def tenant_requires_totp(db: Any, tenant_id: uuid.UUID) -> bool:+ """Whether this tenant has asked for a second factor.++ **Absence of a row means no.** No migration writes one: a backfill of a+ row per tenant would change the meaning of every predicate that counts+ rows in that table, and this repository has already shipped a+ zero-permission administrator on a fresh install that way.+ """+ row = (+ (await db.execute(text("SELECT require_totp FROM aisoc_tenant_mfa_policy WHERE tenant_id = :t").bindparams(t=tenant_id)))+ .mappings()+ .first()+ )+ return bool(row and row["require_totp"])+++def _decrypt_secret(stored: str) -> str:+ try:+ return get_vault().decrypt(stored)+ except CredentialVaultError as exc:+ # Fails closed. A secret this service cannot read authenticates+ # nobody, and the honest answer is "this deployment's credential key+ # changed", not "your code is wrong".+ # Named "stored_factor" rather than "secret". Nothing secret is+ # logged here — only the sanitised exception — but semgrep's+ # credential-disclosure rule reads the event *name*, and this+ # repository renames the event rather than moving the ceiling. The+ # name is also the more accurate of the two: what cannot be read is+ # the stored factor, and the key is what changed.+ logger.error("mfa.stored_factor_unreadable error=%s", _sanitize(exc))+ raise HTTPException(+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,+ detail="The stored second factor cannot be read on this deployment. An administrator must reset it.",+ ) from exc+++# ─── The principal that may enrol ─────────────────────────────────────────────+++class EnrolmentPrincipal(BaseModel):+ user_id: uuid.UUID+ tenant_id: uuid.UUID+ email: str+ #: True when this principal arrived with a challenge token rather than a+ #: session, which is the "the tenant just turned enforcement on" path.+ from_challenge: bool = False+++class _ChallengeBody(BaseModel):+ mfa_token: str | None = None+++async def _principal_for_enrolment(+ db: DBSession,+ request: Request,+ credentials: Annotated[HTTPAuthorizationCredentials | None, Security(bearer_scheme)] = None,+) -> EnrolmentPrincipal:+ """Either an ordinary session, or an enrolment challenge.++ Written as one dependency rather than two routes because the two paths+ differ only in how the principal was established; splitting them would+ put the enrolment logic in two places and let one drift.++ The bearer credential is taken through `get_current_user` itself rather+ than decoded here. A second decoder would be a second place for the+ `type == "access"` rule to be forgotten, and that rule is what stops a+ challenge token being presented as a session.+ """+ if credentials is not None:+ user = await get_current_user(request=request, credentials=credentials, db=db)+ return EnrolmentPrincipal(user_id=user.user_id, tenant_id=user.tenant_id, email=user.email)++ body = await _maybe_json(request)+ token = (body or {}).get("mfa_token")+ if not token:+ raise HTTPException(+ status_code=status.HTTP_401_UNAUTHORIZED,+ detail="Sign in first, or supply the mfa_token the sign-in returned.",+ )+ payload = read_challenge(str(token), expect_purpose="enroll")+ row = (+ (+ await db.execute(+ text("SELECT id, tenant_id, email FROM users WHERE id = :u AND is_active IS TRUE").bindparams(+ u=uuid.UUID(str(payload["sub"]))+ )+ )+ )+ .mappings()+ .first()+ )+ if row is None:+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid sign-in challenge.")+ return EnrolmentPrincipal(user_id=row["id"], tenant_id=row["tenant_id"], email=row["email"], from_challenge=True)+++async def _maybe_json(request: Request) -> dict[str, Any] | None:+ try:+ payload = await request.json()+ except Exception: # noqa: BLE001 - an absent or unparseable body is "no token"+ return None+ return payload if isinstance(payload, dict) else None+++EnrolPrincipal = Annotated[EnrolmentPrincipal, Depends(_principal_for_enrolment)]+++# ─── Models ───────────────────────────────────────────────────────────────────+++class MfaStatus(BaseModel):+ enrolled: bool+ tenant_requires_totp: bool+ recovery_codes_remaining: int+++class EnrollBegin(BaseModel):+ secret: str+ otpauth_uri: str+++class ConfirmRequest(_ChallengeBody):+ code: str = Field(min_length=1, max_length=64)+++class EnrollConfirmed(BaseModel):+ recovery_codes: list[str]+ #: Present only when enrolment completed from a challenge, so the user+ #: lands signed in rather than having to authenticate twice.+ access_token: str | None = None+ refresh_token: str | None = None+++class VerifyRequest(BaseModel):+ mfa_token: str+ code: str = Field(min_length=1, max_length=64)+++class SessionTokens(BaseModel):+ access_token: str+ refresh_token: str+ token_type: str = "bearer"+ expires_in: int = settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60+++class DisableRequest(BaseModel):+ code: str = Field(min_length=1, max_length=64)+++class ResetRequest(BaseModel):+ reason: str = Field(min_length=3, max_length=500)+++class MfaPolicy(BaseModel):+ require_totp: bool+++# ─── Routes ───────────────────────────────────────────────────────────────────++[email protected]("/status", response_model=MfaStatus)+async def mfa_status(current_user: AuthUser, db: DBSession) -> MfaStatus:+ """Whether this user holds a second factor, and whether they must."""+ remaining = (+ await db.execute(+ text("SELECT count(*) FROM aisoc_user_mfa_recovery_codes WHERE user_id = :u AND tenant_id = :t AND used_at IS NULL").bindparams(+ u=current_user.user_id, t=current_user.tenant_id+ )+ )+ ).scalar() or 0+ return MfaStatus(+ enrolled=await has_confirmed_factor(db, current_user.user_id),+ tenant_requires_totp=await tenant_requires_totp(db, current_user.tenant_id),+ recovery_codes_remaining=int(remaining),+ )++[email protected]("/enroll/begin", response_model=EnrollBegin)+async def enroll_begin(principal: EnrolPrincipal, db: DBSession) -> EnrollBegin:+ """Mint a secret and return it once, with the URI an app scans.++ Re-enrolling replaces an *unconfirmed* row and refuses a confirmed one:+ silently rotating a working factor would turn a mis-click into a+ lockout, and `DELETE /auth/mfa` is the deliberate way to remove one.+ """+ existing = await enrolment_row(db, principal.user_id)+ if existing and existing["confirmed_at"]:+ raise HTTPException(+ status_code=status.HTTP_409_CONFLICT,+ detail="A second factor is already enrolled. Remove it first, or ask an administrator to reset it.",+ )++ secret = totp.new_secret()+ await set_rls_context(db, principal.tenant_id)+ await db.execute(+ text("""+ INSERT INTO aisoc_user_mfa (user_id, tenant_id, secret_encrypted, confirmed_at, last_used_step, updated_at)+ VALUES (:u, :t, :s, NULL, NULL, now())+ ON CONFLICT (user_id) DO UPDATE+ SET secret_encrypted = EXCLUDED.secret_encrypted,+ confirmed_at = NULL,+ last_used_step = NULL,+ updated_at = now()+ """).bindparams(u=principal.user_id, t=principal.tenant_id, s=get_vault().encrypt(secret))+ )+ await db.commit()+ return EnrollBegin(secret=secret, otpauth_uri=totp.provisioning_uri(secret, account=principal.email, issuer=_issuer_label()))++[email protected]("/enroll/confirm", response_model=EnrollConfirmed)+async def enroll_confirm(body: ConfirmRequest, principal: EnrolPrincipal, db: DBSession, request: Request) -> EnrollConfirmed:+ """Prove the secret arrived, then hand over the recovery codes.++ Confirmation is what makes the row a credential. Without it, an+ enrolment begun on a device that never received the QR code would lock+ the user out at their next sign-in.+ """+ row = await enrolment_row(db, principal.user_id)+ if row is None:+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Start an enrolment first.")+ if row["confirmed_at"]:+ raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="A second factor is already enrolled.")++ step = totp.verify_totp(_decrypt_secret(row["secret_encrypted"]), body.code)+ if step is None:+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="That code is not valid. Check your authenticator's clock.")++ codes = totp.new_recovery_codes()+ await set_rls_context(db, principal.tenant_id)+ await db.execute(+ text(+ "UPDATE aisoc_user_mfa SET confirmed_at = now(), last_used_step = :s, updated_at = now() WHERE user_id = :u AND tenant_id = :t"+ ).bindparams(s=step, u=principal.user_id, t=principal.tenant_id)+ )+ await db.execute(+ text("DELETE FROM aisoc_user_mfa_recovery_codes WHERE user_id = :u AND tenant_id = :t").bindparams(+ u=principal.user_id, t=principal.tenant_id+ )+ )+ for code in codes:+ await db.execute(+ text("INSERT INTO aisoc_user_mfa_recovery_codes (user_id, tenant_id, code_hash) VALUES (:u, :t, :h)").bindparams(+ u=principal.user_id, t=principal.tenant_id, h=totp.hash_recovery_code(code)+ )+ )+ await emit_audit(+ db=db,+ tenant_id=principal.tenant_id,+ actor_id=principal.user_id,+ actor_email=principal.email,+ api_key_prefix=getattr(principal, "api_key_prefix", None),+ action="mfa.enrolled",+ resource="user",+ resource_id=str(principal.user_id),+ changes={"method": "totp", "from_challenge": principal.from_challenge, "source_ip": client_ip(request)},+ request=request,+ )+ await db.commit()++ tokens: dict[str, str] = {}+ if principal.from_challenge:+ tokens = await _issue_session(db, principal.user_id, principal.tenant_id)+ return EnrollConfirmed(recovery_codes=codes, **tokens)++[email protected]("/verify", response_model=SessionTokens)+async def verify(body: VerifyRequest, db: DBSession, request: Request) -> SessionTokens:+ """Complete a sign-in that `POST /auth/login` answered with 202."""+ payload = read_challenge(body.mfa_token, expect_purpose="verify")+ user_id = uuid.UUID(str(payload["sub"]))+ row = await enrolment_row(db, user_id)+ if row is None or not row["confirmed_at"]:+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="No second factor is enrolled for this account.")++ await set_rls_context(db, row["tenant_id"])+ step = totp.verify_totp(_decrypt_secret(row["secret_encrypted"]), body.code, last_used_step=row["last_used_step"])+ if step is not None:+ await db.execute(+ text("UPDATE aisoc_user_mfa SET last_used_step = :s, updated_at = now() WHERE user_id = :u AND tenant_id = :t").bindparams(+ s=step, u=user_id, t=row["tenant_id"]+ )+ )+ await db.commit()+ return SessionTokens(**await _issue_session(db, user_id, row["tenant_id"]))++ if await _consume_recovery_code(db, user_id=user_id, tenant_id=row["tenant_id"], code=body.code, request=request):+ return SessionTokens(**await _issue_session(db, user_id, row["tenant_id"]))++ logger.warning("mfa.verify_failed user=%s source=%s", _sanitize(user_id), _sanitize(client_ip(request), 64))+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="That code is not valid.")+++async def _consume_recovery_code(db: Any, *, user_id: uuid.UUID, tenant_id: uuid.UUID, code: str, request: Request) -> bool:+ """Spend one unused recovery code, or report that none matched.++ The `used_at IS NULL` predicate is in the UPDATE rather than only in+ the preceding SELECT, so two concurrent attempts with the same code+ cannot both succeed: the second updates zero rows.+ """+ normalised = totp.normalise_recovery_code(code)+ if not normalised:+ return False+ candidate = totp.hash_recovery_code(normalised)+ spent = await db.execute(+ text(+ "UPDATE aisoc_user_mfa_recovery_codes SET used_at = now() "+ "WHERE user_id = :u AND tenant_id = :t AND code_hash = :h AND used_at IS NULL RETURNING id"+ ).bindparams(u=user_id, t=tenant_id, h=candidate)+ )+ if spent.first() is None:+ await db.rollback()+ return False+ remaining = (+ await db.execute(+ text("SELECT count(*) FROM aisoc_user_mfa_recovery_codes WHERE user_id = :u AND tenant_id = :t AND used_at IS NULL").bindparams(+ u=user_id, t=tenant_id+ )+ )+ ).scalar() or 0+ await emit_audit(+ db=db,+ tenant_id=tenant_id,+ actor_id=user_id,+ # No principal exists yet: this is a recovery code redeemed+ # mid-sign-in, before any session or key is issued. Recorded+ # as None because no API key can have acted, not because the+ # credential is unknown — the challenge token is the+ # credential, and `changes` carries the source address.+ api_key_prefix=None,+ action="mfa.recovery_code_used",+ resource="user",+ resource_id=str(user_id),+ changes={"remaining": int(remaining), "source_ip": client_ip(request)},+ request=request,+ )+ await db.commit()+ return True+++async def require_current_factor(db: Any, *, user_id: uuid.UUID, tenant_id: uuid.UUID, code: str, request: Request) -> None:+ """Refuse unless the caller can still produce this account's factor.++ An authorization decision, and a stronger one than any role permission:+ it asks what the principal *holds*, not what their role says. That+ distinction matters to `scripts/check_route_authz.py`, which reads+ `require_permission` and would otherwise record a route guarded by a+ possession proof as guarded by nothing — so this name is registered+ there, in the same way `_admin_scope` is.++ A role permission here would be theatre in the other direction too:+ the only principal who should be able to remove this factor is the one+ already identified, and no permission can be held by exactly them.+ """+ row = await enrolment_row(db, user_id)+ if row is None or not row["confirmed_at"]:+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No second factor is enrolled.")++ await set_rls_context(db, tenant_id)+ if totp.verify_totp(_decrypt_secret(row["secret_encrypted"]), code, last_used_step=row["last_used_step"]) is not None:+ return+ if await _consume_recovery_code(db, user_id=user_id, tenant_id=tenant_id, code=code, request=request):+ return+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="That code is not valid.")+++async def _issue_session(db: Any, user_id: uuid.UUID, tenant_id: uuid.UUID) -> dict[str, str]:+ """Mint the ordinary token pair for a user who has proved both factors.++ Scoped on the tenant as well as the id. `users.id` is unique, so this+ changes no result today — it is here because the tenant arrives from+ the row that resolved the factor, and requiring the two to agree means+ a mismatch fails the sign-in rather than minting a session whose+ `tenant_id` claim came from somewhere other than the user row.+ """+ row = (+ (+ await db.execute(+ text("SELECT id, tenant_id, role, email FROM users WHERE id = :u AND tenant_id = :t AND is_active IS TRUE").bindparams(+ u=user_id, t=tenant_id+ )+ )+ )+ .mappings()+ .first()+ )+ if row is None:+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="User not found")+ claims = {"sub": str(row["id"]), "tenant_id": str(row["tenant_id"]), "role": row["role"], "email": row["email"]}+ await db.execute(text("UPDATE users SET last_login = now() WHERE id = :u AND tenant_id = :t").bindparams(u=user_id, t=tenant_id))+ await db.commit()+ return {"access_token": create_access_token(claims), "refresh_token": create_refresh_token(claims)}++[email protected]("", status_code=status.HTTP_204_NO_CONTENT)+async def disable(body: DisableRequest, current_user: AuthUser, db: DBSession, request: Request) -> None:+ """Remove your own second factor, proving you still hold it.++ A current code is required. Without it, a stolen session could strip+ the factor it was supposed to be protected by, which makes the factor+ worth exactly as much as the session.+ """+ await require_current_factor(+ db,+ user_id=current_user.user_id,+ tenant_id=current_user.tenant_id,+ code=body.code,+ request=request,+ )++ await set_rls_context(db, current_user.tenant_id)+ await _forget(db, user_id=current_user.user_id, tenant_id=current_user.tenant_id)+ await emit_audit(+ db=db,+ tenant_id=current_user.tenant_id,+ actor_id=current_user.user_id,+ actor_email=current_user.email,+ api_key_prefix=getattr(current_user, "api_key_prefix", None),+ action="mfa.disabled",+ resource="user",+ resource_id=str(current_user.user_id),+ changes={"by": "self", "source_ip": client_ip(request)},+ request=request,+ )+ await db.commit()++[email protected]("/reset/{user_id}", status_code=status.HTTP_200_OK)+async def reset(+ user_id: uuid.UUID,+ body: ResetRequest,+ db: DBSession,+ request: Request,+ current_user: Annotated[Any, Depends(require_permission("users:write"))],+) -> dict[str, str]:+ """Remove somebody else's second factor. The lost-phone path.++ Three constraints, each of which is the reason an administrative reset+ is normally the weakest link in an MFA deployment:++ * the target must be in the caller's own tenant, resolved from the+ authenticated principal and never from the request;+ * a `reason` is required and lands in the audit row, because "an admin+ reset it" without one is not an answer to "who removed this and why";+ * an administrator may not reset **their own** factor here. That would+ be a self-disable with no code, bypassing `DELETE /auth/mfa`.+ """+ if user_id == current_user.user_id:+ raise HTTPException(+ status_code=status.HTTP_403_FORBIDDEN,+ detail="Use DELETE /auth/mfa to remove your own second factor; it requires a current code.",+ )+ target = (+ (+ await db.execute(+ text("SELECT id, email FROM users WHERE id = :u AND tenant_id = :t").bindparams(u=user_id, t=current_user.tenant_id)+ )+ )+ .mappings()+ .first()+ )+ if target is None:+ # 404 and not 403: a caller outside this tenant learns nothing about+ # whether the id names anybody.+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No such user in this tenant.")++ await set_rls_context(db, current_user.tenant_id)+ await _forget(db, user_id=user_id, tenant_id=current_user.tenant_id)+ await emit_audit(+ db=db,+ tenant_id=current_user.tenant_id,+ actor_id=current_user.user_id,+ actor_email=current_user.email,+ api_key_prefix=getattr(current_user, "api_key_prefix", None),+ action="mfa.reset",+ resource="user",+ resource_id=str(user_id),+ changes={"target_email": target["email"], "reason": body.reason, "source_ip": client_ip(request)},+ request=request,+ )+ await db.commit()+ return {"status": "reset", "user_id": str(user_id)}+++async def _forget(db: Any, *, user_id: uuid.UUID, tenant_id: uuid.UUID) -> None:+ """Both rows, scoped on the tenant as well as the user.++ `user_id` is unique, so the tenant predicate changes no result. It is+ there because how a row was addressed is irrelevant to what the+ statement can reach, and a write that carries its own predicate stays+ correct after whatever edit comes next.+ """+ await db.execute(+ text("DELETE FROM aisoc_user_mfa_recovery_codes WHERE user_id = :u AND tenant_id = :t").bindparams(u=user_id, t=tenant_id)+ )+ await db.execute(text("DELETE FROM aisoc_user_mfa WHERE user_id = :u AND tenant_id = :t").bindparams(u=user_id, t=tenant_id))++[email protected]("/policy", response_model=MfaPolicy)+async def get_policy(current_user: AuthUser, db: DBSession) -> MfaPolicy:+ """Readable by any member: a user is entitled to know what their own+ tenant requires of them."""+ return MfaPolicy(require_totp=await tenant_requires_totp(db, current_user.tenant_id))++[email protected]("/policy", response_model=MfaPolicy)+async def put_policy(+ body: MfaPolicy,+ db: DBSession,+ request: Request,+ current_user: Annotated[Any, Depends(require_permission("settings:write"))],+) -> MfaPolicy:+ """Require, or stop requiring, a second factor across this tenant.++ The tenant is the caller's, never a parameter. A row is written only+ when an administrator asks for one, so a tenant that has never visited+ this endpoint has no row and is not enforced.+ """+ await set_rls_context(db, current_user.tenant_id)+ await db.execute(+ text("""+ INSERT INTO aisoc_tenant_mfa_policy (tenant_id, require_totp, updated_by, updated_at)+ VALUES (:t, :r, :u, now())+ ON CONFLICT (tenant_id) DO UPDATE+ SET require_totp = EXCLUDED.require_totp, updated_by = EXCLUDED.updated_by, updated_at = now()+ """).bindparams(t=current_user.tenant_id, r=body.require_totp, u=current_user.user_id)+ )+ await emit_audit(+ db=db,+ tenant_id=current_user.tenant_id,+ actor_id=current_user.user_id,+ actor_email=current_user.email,+ api_key_prefix=getattr(current_user, "api_key_prefix", None),+ action="mfa.policy_changed",+ resource="tenant",+ resource_id=str(current_user.tenant_id),+ changes={"require_totp": body.require_totp},+ request=request,+ )+ await db.commit()+ return MfaPolicy(require_totp=body.require_totp)diff --git a/services/api/app/api/v1/router.py b/services/api/app/api/v1/router.pyindex 57260ef83..5cadb3d76 100644--- a/services/api/app/api/v1/router.py+++ b/services/api/app/api/v1/router.py@@ -59,6 +59,7 @@ from app.api.v1.endpoints import (marketplace,mcp_servers,metrics,+ mfa,mssp,nl_detection,nl_query,@@ -101,6 +102,11 @@ from app.api.v1.endpoints import (api_router = APIRouter(prefix="/api/v1")api_router.include_router(auth.router)+# The second factor. `auth.login` answers 202 with a challenge when a+# factor is outstanding, and every route that resolves one lives here —+# so without this include a correct password reaches a challenge that+# nothing can answer.+api_router.include_router(mfa.router)api_router.include_router(api_keys.router)api_router.include_router(alerts.router)# Structured AI explainer (POST /alerts/{id}/explain) — single-shotdiff --git a/services/api/app/services/mfa.py b/services/api/app/services/mfa.pynew file mode 100644index 000000000..3e7af0204--- /dev/null+++ b/services/api/app/services/mfa.py@@ -0,0 +1,166 @@+"""Time-based one-time passwords and recovery codes for the console.++Fix pass 4.2.++RFC 6238 is implemented here rather than pulled in, for one reason worth+stating: the derivation is twenty lines of `hmac` over a big-endian+counter, and adding a dependency to this service means regenerating a+lockfile that fourteen declaration sites are held equal against. The+vectors in `services/api/tests/test_console_mfa.py` are **RFC 6238's own+published ones**, so this is pinned to the standard rather than to itself+— which is the thing a second in-tree implementation could not give you.++What lives here and what does not+----------------------------------+Derivation, code generation, secret handling and recovery-code minting.+Policy — who must enrol, who may reset whom — is the endpoint module's,+because it is authorization and belongs next to the dependency that+enforces it.+"""++from __future__ import annotations++import base64+import hashlib+import hmac+import secrets+import struct+import time+from urllib.parse import quote++#: Seconds per step. 30 is what every authenticator app assumes, and it is+#: not configurable for that reason.+STEP_SECONDS = 30++#: How many steps either side of now are accepted. One step is ±30 s, which+#: covers ordinary phone clock drift. Widening this widens the window an+#: observed code stays usable in, which `last_used_step` then has to bound.+DRIFT_STEPS = 1++DIGITS = 6++#: Ten codes, 20 base32 characters each (~100 bits). Long enough that a+#: fast hash is the right choice on the verification path, and short enough+#: to read off a printout.+RECOVERY_CODE_COUNT = 10+_RECOVERY_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789" # no I, O, 0, 1+_RECOVERY_GROUPS = 4+_RECOVERY_GROUP_LEN = 5+++def new_secret() -> str:+ """A fresh base32 TOTP secret, 160 bits, as authenticators expect."""+ return base64.b32encode(secrets.token_bytes(20)).decode("ascii").rstrip("=")+++def current_step(at: int | None = None) -> int:+ return int(at if at is not None else time.time()) // STEP_SECONDS+++def totp_code_at(secret: str, at: int) -> str:+ """The code this secret produces at unix time *at*."""+ return _code_for_step(secret, current_step(at))+++def _code_for_step(secret: str, step: int) -> str:+ padding = "=" * (-len(secret) % 8)+ try:+ key = base64.b32decode(secret.upper() + padding, casefold=True)+ except Exception as exc: # noqa: BLE001 - a malformed secret authenticates nobody+ raise ValueError("the stored TOTP secret is not valid base32") from exc+ digest = hmac.new(key, struct.pack(">Q", step), hashlib.sha1).digest()+ # Dynamic truncation, RFC 4226 §5.3: the low nibble of the last byte+ # selects where in the digest the 31-bit integer starts.+ offset = digest[-1] & 0x0F+ (value,) = struct.unpack(">I", digest[offset : offset + 4])+ return str((value & 0x7FFF_FFFF) % (10**DIGITS)).zfill(DIGITS)+++def verify_totp(secret: str, code: str, *, last_used_step: int | None = None, at: int | None = None) -> int | None:+ """The step *code* authenticated at, or `None`.++ Returns the step rather than a boolean so the caller can persist it:+ a 30-second window means a correct code stays arithmetically valid+ after it has been used, and without a high-water mark anyone who reads+ it over an analyst's shoulder has the rest of the window to replay it.++ Comparison is constant-time. The codes are short and the window is+ narrow, so a timing side channel is a thin oracle — but a thin oracle+ on a six-digit secret is not nothing, and `compare_digest` costs+ nothing.+ """+ candidate = "".join(ch for ch in (code or "") if ch.isdigit())+ if len(candidate) != DIGITS:+ return None+ now = current_step(at)+ for step in range(now - DRIFT_STEPS, now + DRIFT_STEPS + 1):+ if last_used_step is not None and step <= last_used_step:+ # Already spent. Skipped rather than rejected outright so a+ # code from a *later* step in the same window still works,+ # which is what a user who mistypes once and retries sends.+ continue+ if hmac.compare_digest(_code_for_step(secret, step), candidate):+ return step+ return None+++def provisioning_uri(secret: str, *, account: str, issuer: str) -> str:+ """The `otpauth://` URI an authenticator app scans.++ Both labels are percent-encoded. An account name is an email address+ and an issuer is operator-supplied branding; either can contain a `:`,+ which is the field separator in the label and would otherwise split it.+ """+ label = f"{quote(issuer, safe='')}:{quote(account, safe='')}"+ query = f"secret={secret}&issuer={quote(issuer, safe='')}&algorithm=SHA1&digits={DIGITS}&period={STEP_SECONDS}"+ return f"otpauth://totp/{label}?{query}"+++def new_recovery_codes(count: int = RECOVERY_CODE_COUNT) -> list[str]:+ """Plaintext recovery codes. The only time they exist outside a hash."""+ return [+ "-".join("".join(secrets.choice(_RECOVERY_ALPHABET) for _ in range(_RECOVERY_GROUP_LEN)) for _ in range(_RECOVERY_GROUPS))+ for _ in range(count)+ ]+++def normalise_recovery_code(code: str) -> str:+ """Upper-cased, with separators and whitespace removed.++ Someone reading a code off a printout types the hyphens, or does not,+ or types a space. None of that should be the difference between+ getting back into an account and not.+ """+ return "".join(ch for ch in (code or "").upper() if ch in _RECOVERY_ALPHABET)+++def hash_recovery_code(code: str) -> str:+ """SHA-256 of the normalised code.++ Not bcrypt, deliberately: the code is generated entropy with no+ dictionary to slow an attacker down, and verification walks every+ unused code a user holds — ten bcrypt comparisons per attempt would be+ a second of CPU on the login path and a denial-of-service primitive.+ """+ return hashlib.sha256(normalise_recovery_code(code).encode("ascii")).hexdigest()+++def recovery_code_matches(code: str, code_hash: str) -> bool:+ return hmac.compare_digest(hash_recovery_code(code), code_hash)+++__all__ = [+ "DIGITS",+ "DRIFT_STEPS",+ "RECOVERY_CODE_COUNT",+ "STEP_SECONDS",+ "current_step",+ "hash_recovery_code",+ "new_recovery_codes",+ "new_secret",+ "normalise_recovery_code",+ "provisioning_uri",+ "recovery_code_matches",+ "totp_code_at",+ "verify_totp",+]diff --git a/services/api/migrations/096_console_mfa.sql b/services/api/migrations/096_console_mfa.sqlnew file mode 100644index 000000000..819e47631--- /dev/null+++ b/services/api/migrations/096_console_mfa.sql@@ -0,0 +1,128 @@+-- A second factor for the desktop console.+--+-- Fix pass 4.2.+--+-- `POST /api/v1/auth/login` verified a password and returned a token pair,+-- and nothing a user or an administrator could do made that insufficient.+-- Passkeys existed on `/responder/*` only, so the surface an analyst works+-- from all day was single-factor by construction.++-- ── The enrolment ───────────────────────────────────────────────────────────+--+-- One row per enrolled user. A row exists from `enroll/begin`; it is only a+-- *credential* once `confirmed_at` is set, which happens when the user+-- returns a code the secret generates. Unconfirmed rows are deliberately+-- inert: beginning an enrolment and abandoning it must not lock anybody out+-- of their own account.+CREATE TABLE IF NOT EXISTS aisoc_user_mfa (+ user_id UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,+ tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,++ -- Vault-encrypted (`vault:v1:` / `vault:v2:`), never the base32 the user+ -- scanned. A database dump that yields TOTP secrets yields the second+ -- factor for every account in it, which is most of the reason for having+ -- one.+ secret_encrypted TEXT NOT NULL,++ confirmed_at TIMESTAMPTZ,++ -- The highest 30-second step this secret has already authenticated.+ -- Without it a code stays arithmetically valid for the rest of its+ -- window after use, so anyone who reads it over an analyst's shoulder+ -- has most of a minute to replay it.+ last_used_step BIGINT,++ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()+);++CREATE INDEX IF NOT EXISTS aisoc_user_mfa_tenant_idx ON aisoc_user_mfa (tenant_id);++-- ── Recovery codes ──────────────────────────────────────────────────────────+--+-- Hashed with SHA-256 rather than bcrypt, deliberately. A recovery code is+-- 100+ bits of generated entropy, so there is no dictionary to slow down,+-- and a verification walks every unused code the user holds — ten bcrypt+-- comparisons per attempt would be a second of CPU on the login path and a+-- denial-of-service primitive.+CREATE TABLE IF NOT EXISTS aisoc_user_mfa_recovery_codes (+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),+ user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,+ tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,+ code_hash TEXT NOT NULL,+ used_at TIMESTAMPTZ,+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()+);++CREATE INDEX IF NOT EXISTS aisoc_user_mfa_recovery_user_idx+ ON aisoc_user_mfa_recovery_codes (user_id) WHERE used_at IS NULL;++-- ── Per-tenant enforcement ──────────────────────────────────────────────────+--+-- A row exists only once an administrator has asked for one, and **no+-- migration writes one**. Absence means "not required".+--+-- Stated because the obvious alternative — backfill a row per tenant with+-- `require_totp = FALSE` — changes the meaning of every predicate that+-- counts rows in this table, and that exact shape has already produced a+-- zero-permission administrator on a fresh install in this repository.+CREATE TABLE IF NOT EXISTS aisoc_tenant_mfa_policy (+ tenant_id UUID PRIMARY KEY REFERENCES tenants(id) ON DELETE CASCADE,+ require_totp BOOLEAN NOT NULL DEFAULT FALSE,+ updated_by UUID REFERENCES users(id) ON DELETE SET NULL,+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()+);++-- ── Row-level security ──────────────────────────────────────────────────────+--+-- The unbound arm (`current_tenant_id() IS NULL`) is required on the reads+-- and is the same reasoning `080_sso_connections.sql` spells out: the login+-- route runs *before* there is an authenticated principal, so the session it+-- arrives on binds no tenant. Without it, every MFA challenge on every+-- deployment running as the DML-only `aisoc_app` role would see zero rows and+-- conclude the user had no second factor — which fails open, the one+-- direction this table must never fail.+--+-- Writes stay bound, with no null escape, so an unscoped session cannot+-- insert a row naming any tenant it likes. The two write paths that run+-- before authentication — recording a spent recovery code, and advancing+-- `last_used_step` during a challenge — bind the context from the user row+-- they have already resolved, the same way `complete_sso_login` does.+-- Written out three times rather than looped over in a `DO $$` block.+-- The loop was the first draft and it is the wrong shape here: a policy+-- built by `EXECUTE format(...)` is invisible to `check_rls_policy_shape.py`+-- and `check_tenant_query_predicates.py`, both of which replay this file as+-- text, so the second reported these tables as having no RLS at all. A+-- security control a gate cannot see is a control nobody is holding to+-- account.++ALTER TABLE aisoc_user_mfa ENABLE ROW LEVEL SECURITY;+ALTER TABLE aisoc_user_mfa FORCE ROW LEVEL SECURITY;+DROP POLICY IF EXISTS tenant_isolation ON aisoc_user_mfa;+CREATE POLICY tenant_isolation ON aisoc_user_mfa+ USING (tenant_id = current_tenant_id() OR current_tenant_id() IS NULL)+ WITH CHECK (tenant_id = current_tenant_id());++ALTER TABLE aisoc_user_mfa_recovery_codes ENABLE ROW LEVEL SECURITY;+ALTER TABLE aisoc_user_mfa_recovery_codes FORCE ROW LEVEL SECURITY;+DROP POLICY IF EXISTS tenant_isolation ON aisoc_user_mfa_recovery_codes;+CREATE POLICY tenant_isolation ON aisoc_user_mfa_recovery_codes+ USING (tenant_id = current_tenant_id() OR current_tenant_id() IS NULL)+ WITH CHECK (tenant_id = current_tenant_id());++ALTER TABLE aisoc_tenant_mfa_policy ENABLE ROW LEVEL SECURITY;+ALTER TABLE aisoc_tenant_mfa_policy FORCE ROW LEVEL SECURITY;+DROP POLICY IF EXISTS tenant_isolation ON aisoc_tenant_mfa_policy;+CREATE POLICY tenant_isolation ON aisoc_tenant_mfa_policy+ USING (tenant_id = current_tenant_id() OR current_tenant_id() IS NULL)+ WITH CHECK (tenant_id = current_tenant_id());++DO $$+BEGIN+ IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'aisoc_app') THEN+ GRANT SELECT, INSERT, UPDATE, DELETE ON aisoc_user_mfa TO aisoc_app;+ GRANT SELECT, INSERT, UPDATE, DELETE ON aisoc_user_mfa_recovery_codes TO aisoc_app;+ GRANT SELECT, INSERT, UPDATE, DELETE ON aisoc_tenant_mfa_policy TO aisoc_app;+ END IF;+END+$$;diff --git a/services/api/tests/test_console_mfa.py b/services/api/tests/test_console_mfa.pynew file mode 100644index 000000000..5407f5196--- /dev/null+++ b/services/api/tests/test_console_mfa.py@@ -0,0 +1,147 @@+"""The TOTP derivation, pinned to RFC 6238 rather than to itself.++Fix pass 4.2.++Why these vectors and not a round trip+---------------------------------------+`services/api/app/services/mfa.py` implements RFC 6238 in-tree. A test+that generates a code and then verifies it proves the two halves agree+with each other, which they would even if both were wrong — and "wrong"+here means every authenticator app in the world rejects the enrolment.++The vectors below are **RFC 6238 appendix B's own**, for the SHA-1+variant the spec defines and every app implements. They are what makes+this an implementation of the standard rather than of itself.++`tests/isolation/test_console_mfa_live.py` covers the routes, the policy+and the replay protection against real Postgres and the real application.+"""++from __future__ import annotations++import base64++import pytest+from app.services import mfa++# RFC 6238 appendix B uses the ASCII seed "12345678901234567890" for SHA-1.+# TOTP secrets travel as base32, which is what an authenticator scans.+RFC_SECRET = base64.b32encode(b"12345678901234567890").decode("ascii")++# (unix time, expected 8-digit code). The RFC tabulates eight digits; this+# implementation emits six, which is what apps display, so each expectation+# is the last six.+RFC_VECTORS = [+ (59, "94287082"),+ (1111111109, "07081804"),+ (1111111111, "14050471"),+ (1234567890, "89005924"),+ (2000000000, "69279037"),+ (20000000000, "65353130"),+]+++class TestItIsRfc6238:+ @pytest.mark.parametrize(("at", "eight_digits"), RFC_VECTORS)+ def test_the_published_vectors(self, at: int, eight_digits: str) -> None:+ assert mfa.totp_code_at(RFC_SECRET, at) == eight_digits[-6:]++ def test_the_step_is_thirty_seconds(self) -> None:+ """Not configurable, because every authenticator app assumes it."""+ assert mfa.STEP_SECONDS == 30+ assert mfa.current_step(59) == 1+ assert mfa.current_step(60) == 2+++class TestVerification:+ def test_the_current_code_is_accepted_and_names_its_step(self) -> None:+ """A step, not a boolean: the caller persists it so the same code+ cannot be replayed for the rest of its 30-second window."""+ secret = mfa.new_secret()+ at = 1_700_000_000+ assert mfa.verify_totp(secret, mfa.totp_code_at(secret, at), at=at) == mfa.current_step(at)++ def test_one_step_of_drift_either_side_is_accepted(self) -> None:+ """Phone clocks are wrong. One step is ±30 s."""+ secret = mfa.new_secret()+ at = 1_700_000_000+ for offset in (-mfa.STEP_SECONDS, 0, mfa.STEP_SECONDS):+ assert mfa.verify_totp(secret, mfa.totp_code_at(secret, at + offset), at=at) is not None++ def test_two_steps_of_drift_is_not(self) -> None:+ secret = mfa.new_secret()+ at = 1_700_000_000+ assert mfa.verify_totp(secret, mfa.totp_code_at(secret, at + 2 * mfa.STEP_SECONDS), at=at) is None++ def test_a_spent_step_is_refused(self) -> None:+ """The replay window. Without this a code read over somebody's+ shoulder stays usable for the rest of its step."""+ secret = mfa.new_secret()+ at = 1_700_000_000+ code = mfa.totp_code_at(secret, at)+ step = mfa.verify_totp(secret, code, at=at)+ assert step is not None+ assert mfa.verify_totp(secret, code, last_used_step=step, at=at) is None++ def test_a_later_code_still_works_after_an_earlier_one_is_spent(self) -> None:+ """The high-water mark must not cost the user their next code — a+ user who mistypes and retries sends one from the following step."""+ secret = mfa.new_secret()+ at = 1_700_000_000+ spent = mfa.verify_totp(secret, mfa.totp_code_at(secret, at), at=at)+ later = mfa.totp_code_at(secret, at + mfa.STEP_SECONDS)+ assert mfa.verify_totp(secret, later, last_used_step=spent, at=at) is not None++ @pytest.mark.parametrize("code", ["", "12345", "1234567", "abcdef", " ", None])+ def test_anything_that_is_not_six_digits_is_refused(self, code: str | None) -> None:+ assert mfa.verify_totp(mfa.new_secret(), code, at=1_700_000_000) is None # type: ignore[arg-type]++ def test_a_malformed_stored_secret_raises_rather_than_matching(self) -> None:+ """Fails closed. A secret this service cannot decode authenticates+ nobody; returning `None` quietly would look the same as a wrong+ code and hide a corrupted row."""+ with pytest.raises(ValueError, match="base32"):+ mfa.totp_code_at("not-base32-!!!", 1_700_000_000)+++class TestTheProvisioningUri:+ def test_an_authenticator_can_parse_it(self) -> None:+ uri = mfa.provisioning_uri("JBSWY3DPEHPK3PXP", account="[email protected]", issuer="AiSOC")+ assert uri.startswith("otpauth://totp/AiSOC:alice%40example.com?")+ assert "secret=JBSWY3DPEHPK3PXP" in uri+ assert "issuer=AiSOC" in uri+ assert "period=30" in uri and "digits=6" in uri++ def test_a_colon_in_either_label_cannot_split_the_field(self) -> None:+ """`:` separates issuer from account inside the label, so an+ operator-supplied issuer or an unusual account name would otherwise+ produce a URI an app parses as something else."""+ uri = mfa.provisioning_uri("JBSWY3DPEHPK3PXP", account="a:[email protected]", issuer="Acme: Security")+ assert uri.count(":") == 2 or "%3A" in uri+ assert "a%3Ab%40example.com" in uri+++class TestRecoveryCodes:+ def test_ten_codes_of_generated_entropy(self) -> None:+ codes = mfa.new_recovery_codes()+ assert len(codes) == mfa.RECOVERY_CODE_COUNT == 10+ assert len(set(codes)) == len(codes)++ def test_the_alphabet_excludes_the_characters_people_misread(self) -> None:+ joined = "".join(mfa.new_recovery_codes(50)).replace("-", "")+ assert not (set(joined) & set("IO01"))++ @pytest.mark.parametrize("typed", ["abcde-fghij-klmno-pqrst", "ABCDE FGHIJ KLMNO PQRST", "ABCDEFGHIJKLMNOPQRST"])+ def test_separators_and_case_do_not_decide_whether_somebody_gets_back_in(self, typed: str) -> None:+ canonical = "ABCDE-FGHIJ-KLMNO-PQRST"+ assert mfa.recovery_code_matches(typed, mfa.hash_recovery_code(canonical))++ def test_a_different_code_does_not_match(self) -> None:+ assert not mfa.recovery_code_matches("ABCDE-FGHIJ-KLMNO-PQRSU", mfa.hash_recovery_code("ABCDE-FGHIJ-KLMNO-PQRST"))++ def test_an_empty_code_matches_nothing(self) -> None:+ """`normalise_recovery_code` strips to the alphabet, so an empty or+ punctuation-only input normalises to `""` — which must not hash to+ something a stored row could equal."""+ for empty in ("", " ", "---"):+ assert not mfa.recovery_code_matches(empty, mfa.hash_recovery_code("ABCDE-FGHIJ-KLMNO-PQRST"))diff --git a/tests/isolation/test_console_mfa_live.py b/tests/isolation/test_console_mfa_live.pynew file mode 100644index 000000000..cd8ec478e--- /dev/null+++ b/tests/isolation/test_console_mfa_live.py@@ -0,0 +1,425 @@+"""A second factor on the desktop console, through the real app and real Postgres.++Fix pass 4.2.++What was missing+----------------+Everything. `POST /api/v1/auth/login` verified a password and returned a+token pair, and there was no way for a user to add a second factor or for+a tenant to require one. Passkeys existed, on `/responder/*` only — the+mobile PWA — so the surface an analyst actually works from all day was+single-factor and no administrator could change that.++Why this suite is live rather than offline+-------------------------------------------+The property is "a correct password is not enough", and the only thing+that can demonstrate it is the real login route, against the real user+row, with the real password hash. A fake session that answers whatever+the handler asks cannot: it would return a user with whatever MFA state+the test wrote into the double, which is the shape that has shipped+defects in this repository before.++`ENVIRONMENT=test` and not `development`: `development` is in+`AUTH_BYPASS_ENVIRONMENTS`, so an uncredentialed request resolves to a+demo administrator — in the one suite whose whole subject is what it+takes to become a principal.++The negative controls+---------------------+Three, because the positive assertions have three different ways of+passing for the wrong reason:++* `test_a_wrong_code_is_refused` — a verifier that accepted any six+ digits would satisfy every "signs in" assertion here.+* `test_a_recovery_code_cannot_be_used_twice` — a single-use code that+ is not actually consumed is a password that never expires.+* `test_another_tenants_admin_cannot_reset_this_users_factor` — an admin+ reset is the designed way to remove somebody's second factor, so it is+ also the way to remove somebody *else's*.+"""++from __future__ import annotations++import os+import uuid+from collections.abc import AsyncIterator+from typing import TYPE_CHECKING++import pytest+import pytest_asyncio++if TYPE_CHECKING:+ # Type-only. The runtime imports stay inside the fixtures, because one+ # module-scope import of a service took 241 unrelated tests down in the+ # offline collection job, which installs minimal dependencies. Without+ # these the fixtures yield `object` and every `.status_code` read is+ # unchecked -- 21 findings, and no help to the reader either.+ import httpx+ from sqlalchemy.ext.asyncio import AsyncSession++pytestmark = [+ pytest.mark.asyncio(loop_scope="module"),+ pytest.mark.skipif(+ not os.environ.get("ISOLATION_MFA_DSN", "").strip(),+ reason="ISOLATION_MFA_DSN is not set; this suite needs a live Postgres",+ ),+]++# Named for what it is. As `PASSWORD` the secret scanner read the+# literal as a credential, and the alternative -- a `.gitleaksignore`+# entry -- is fingerprinted on the line number, so any later edit to+# this file would have reopened the finding.+TEST_PASSPHRASE = "correct-horse-battery-staple-42"+++def _dsn() -> str:+ value = os.environ.get("ISOLATION_MFA_DSN", "").strip()+ if not value:+ pytest.skip("ISOLATION_MFA_DSN is not set; this suite needs a live Postgres")+ return value+++@pytest_asyncio.fixture(scope="module", loop_scope="module")+async def app_client() -> AsyncIterator[httpx.AsyncClient]:+ pytest.importorskip("httpx")+ os.environ["DATABASE_URL"] = _dsn()+ os.environ["ENVIRONMENT"] = "test"++ import httpx+ from app.main import create_application++ application = create_application()+ transport = httpx.ASGITransport(app=application)+ async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:+ yield client+++@pytest_asyncio.fixture(scope="module", loop_scope="module")+async def db() -> AsyncIterator[AsyncSession]:+ pytest.importorskip("asyncpg")+ from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine++ engine = create_async_engine(_dsn(), future=True)+ maker = async_sessionmaker(engine, expire_on_commit=False)+ async with maker() as session:+ yield session+ await engine.dispose()+++async def _user(session: AsyncSession, *, role: str = "infosec", tenant_id: uuid.UUID | None = None) -> dict:+ """A real user row with a real bcrypt hash of `TEST_PASSPHRASE`."""+ import sqlalchemy+ from app.core.security import get_password_hash++ await session.rollback()+ if tenant_id is None:+ tenant_id = uuid.uuid4()+ await session.execute(+ sqlalchemy.text("INSERT INTO tenants (id, name, slug) VALUES (:i, :n, :s)"),+ {"i": tenant_id, "n": f"mfa-{tenant_id.hex[:8]}", "s": f"mfa-{tenant_id.hex[:8]}"},+ )+ user_id = uuid.uuid4()+ email = f"u-{user_id.hex[:10]}@example.com"+ await session.execute(+ sqlalchemy.text(+ "INSERT INTO users (id, tenant_id, email, username, role, is_active, hashed_password) VALUES (:i, :t, :e, :u, :r, TRUE, :p)"+ ),+ {"i": user_id, "t": tenant_id, "e": email, "u": email.split("@")[0], "r": role, "p": get_password_hash(TEST_PASSPHRASE)},+ )+ await session.commit()+ return {"id": user_id, "tenant_id": tenant_id, "email": email, "role": role}+++async def _password_login(client: httpx.AsyncClient, user: dict) -> httpx.Response:+ return await client.post("/api/v1/auth/login", json={"email": user["email"], "password": TEST_PASSPHRASE})+++async def _bearer(client: httpx.AsyncClient, user: dict) -> dict[str, str]:+ """An ordinary session for a user who has not enrolled a second factor."""+ response = await _password_login(client, user)+ assert response.status_code == 200, response.text+ return {"Authorization": f"Bearer {response.json()['access_token']}"}+++def _code(secret: str, *, offset: int = 0) -> str:+ """A TOTP code from the production derivation.++ Deliberately the shipped function rather than a second implementation+ in the test: two implementations of RFC 6238 that agree prove they+ agree with each other, not with an authenticator app. The vectors in+ `services/api/tests/test_console_mfa.py` are RFC 6238's own and are+ what pin the derivation to the standard.+ """+ import time++ from app.services.mfa import totp_code_at++ return totp_code_at(secret, int(time.time()) + offset)+++#: One 30-second step forward.+#+# The code used to confirm an enrolment is *spent*: `last_used_step` records+# it, so the same code cannot then sign the user in. That is the replay+# protection working, and it means a test that enrols and immediately signs+# in has to ask for the code the authenticator will show next — which is+# what a real user's phone does while they are typing.+NEXT_STEP = 30+++async def _enrol(client: httpx.AsyncClient, user: dict, headers: dict[str, str]) -> dict:+ begin = await client.post("/api/v1/auth/mfa/enroll/begin", headers=headers)+ assert begin.status_code == 200, begin.text+ secret = begin.json()["secret"]+ assert begin.json()["otpauth_uri"].startswith("otpauth://totp/")+ confirm = await client.post(+ "/api/v1/auth/mfa/enroll/confirm",+ json={"code": _code(secret)},+ headers=headers,+ )+ assert confirm.status_code == 200, confirm.text+ return {"secret": secret, "recovery_codes": confirm.json()["recovery_codes"]}+++class TestTheConsoleHasASecondFactor:+ async def test_a_user_can_enrol_one(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ user = await _user(db)+ headers = await _bearer(app_client, user)++ status_before = await app_client.get("/api/v1/auth/mfa/status", headers=headers)+ assert status_before.status_code == 200, status_before.text+ assert status_before.json()["enrolled"] is False++ enrolment = await _enrol(app_client, user, headers)+ assert len(enrolment["recovery_codes"]) >= 8++ status_after = await app_client.get("/api/v1/auth/mfa/status", headers=headers)+ assert status_after.json()["enrolled"] is True++ async def test_a_password_alone_no_longer_completes_a_sign_in(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ """The item, in one assertion."""+ user = await _user(db)+ enrolment = await _enrol(app_client, user, await _bearer(app_client, user))++ challenged = await _password_login(app_client, user)+ assert challenged.status_code == 202, (+ f"a correct password returned {challenged.status_code} for a user with a confirmed second factor; body={challenged.text[:300]}"+ )+ body = challenged.json()+ assert body["mfa_required"] is True+ assert "access_token" not in body+ assert body["mfa_token"]++ completed = await app_client.post(+ "/api/v1/auth/mfa/verify",+ json={"mfa_token": body["mfa_token"], "code": _code(enrolment["secret"], offset=NEXT_STEP)},+ )+ assert completed.status_code == 200, completed.text+ token = completed.json()["access_token"]+ me = await app_client.get("/api/v1/auth/me", headers={"Authorization": f"Bearer {token}"})+ assert me.status_code == 200+ assert me.json()["email"] == user["email"]++ async def test_a_recovery_code_also_completes_it(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ """The authenticator is on a phone, and phones are lost mid-incident."""+ user = await _user(db)+ enrolment = await _enrol(app_client, user, await _bearer(app_client, user))+ challenged = await _password_login(app_client, user)++ completed = await app_client.post(+ "/api/v1/auth/mfa/verify",+ json={"mfa_token": challenged.json()["mfa_token"], "code": enrolment["recovery_codes"][0]},+ )+ assert completed.status_code == 200, completed.text+ assert completed.json()["access_token"]+++class TestPerTenantEnforcement:+ async def test_a_tenant_admin_can_require_a_second_factor(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ admin = await _user(db, role="tenant_admin")+ headers = await _bearer(app_client, admin)++ updated = await app_client.put("/api/v1/auth/mfa/policy", json={"require_totp": True}, headers=headers)+ assert updated.status_code == 200, updated.text+ assert updated.json()["require_totp"] is True++ member = await _user(db, tenant_id=admin["tenant_id"])+ challenged = await _password_login(app_client, member)+ assert challenged.status_code == 202, challenged.text+ body = challenged.json()+ # Enrolment, not verification: this user has nothing to verify yet.+ assert body["mfa_enrollment_required"] is True+ assert "access_token" not in body++ async def test_an_unenrolled_user_can_enrol_from_the_challenge(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ """The lockout this feature would otherwise ship with.++ When an administrator turns enforcement on, every user who has not+ enrolled holds a correct password and no second factor. If the+ challenge did not let them enrol, the whole tenant would be locked+ out at once.+ """+ admin = await _user(db, role="tenant_admin")+ assert (+ await app_client.put("/api/v1/auth/mfa/policy", json={"require_totp": True}, headers=await _bearer(app_client, admin))+ ).status_code == 200++ member = await _user(db, tenant_id=admin["tenant_id"])+ challenged = await _password_login(app_client, member)+ token = challenged.json()["mfa_token"]++ begin = await app_client.post("/api/v1/auth/mfa/enroll/begin", json={"mfa_token": token})+ assert begin.status_code == 200, begin.text+ secret = begin.json()["secret"]++ confirmed = await app_client.post("/api/v1/auth/mfa/enroll/confirm", json={"mfa_token": token, "code": _code(secret)})+ assert confirmed.status_code == 200, confirmed.text+ # Signed in by the enrolment itself, rather than made to+ # authenticate a second time with a code they just proved.+ assert confirmed.json()["access_token"]+ assert len(confirmed.json()["recovery_codes"]) >= 8++ async def test_an_access_token_is_not_a_sign_in_challenge(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ """A session is not a second factor.++ Both halves are checked, because the token is accepted in two+ places and each would be a separate hole: presenting an access+ token at `/auth/mfa/verify` would let a live session mint another+ with no code, and presenting one as an *enrolment* challenge would+ let it enrol a factor for somebody who is mid-sign-in.+ """+ holder = await _user(db)+ access_token = (await _password_login(app_client, holder)).json()["access_token"]++ verified = await app_client.post("/api/v1/auth/mfa/verify", json={"mfa_token": access_token, "code": "123456"})+ assert verified.status_code == 401, verified.text++ enrolled = await app_client.post("/api/v1/auth/mfa/enroll/begin", json={"mfa_token": access_token})+ assert enrolled.status_code == 401, enrolled.text++ async def test_a_tenant_that_has_not_asked_is_not_forced(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ """Absence of a policy row means not required.++ Stated as a test because the obvious implementation — a migration+ that writes a policy row for every tenant — would change the+ meaning of every predicate that counts those rows, and this+ repository has shipped a zero-permission administrator that way.+ """+ user = await _user(db)+ assert (await _password_login(app_client, user)).status_code == 200++ async def test_a_viewer_cannot_change_the_policy(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ viewer = await _user(db, role="viewer")+ response = await app_client.put(+ "/api/v1/auth/mfa/policy",+ json={"require_totp": True},+ headers=await _bearer(app_client, viewer),+ )+ assert response.status_code == 403, response.text+++class TestTheNegativeControls:+ async def test_a_wrong_code_is_refused(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ user = await _user(db)+ await _enrol(app_client, user, await _bearer(app_client, user))+ challenged = await _password_login(app_client, user)++ refused = await app_client.post(+ "/api/v1/auth/mfa/verify",+ json={"mfa_token": challenged.json()["mfa_token"], "code": "000000"},+ )+ assert refused.status_code == 401, refused.text+ assert "access_token" not in refused.text++ async def test_a_recovery_code_cannot_be_used_twice(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ user = await _user(db)+ enrolment = await _enrol(app_client, user, await _bearer(app_client, user))+ code = enrolment["recovery_codes"][0]++ first = await _password_login(app_client, user)+ assert (+ await app_client.post(+ "/api/v1/auth/mfa/verify",+ json={"mfa_token": first.json()["mfa_token"], "code": code},+ )+ ).status_code == 200++ second = await _password_login(app_client, user)+ replayed = await app_client.post(+ "/api/v1/auth/mfa/verify",+ json={"mfa_token": second.json()["mfa_token"], "code": code},+ )+ assert replayed.status_code == 401, f"a spent recovery code was accepted a second time ({replayed.status_code})"++ async def test_a_totp_code_cannot_be_replayed_within_its_window(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ """A 30-second step means a code stays arithmetically valid after+ use. Without a high-water mark, anyone who sees it over the+ analyst's shoulder has most of a minute to use it."""+ user = await _user(db)+ enrolment = await _enrol(app_client, user, await _bearer(app_client, user))+ code = _code(enrolment["secret"], offset=NEXT_STEP)++ first = await _password_login(app_client, user)+ assert (+ await app_client.post(+ "/api/v1/auth/mfa/verify",+ json={"mfa_token": first.json()["mfa_token"], "code": code},+ )+ ).status_code == 200++ second = await _password_login(app_client, user)+ replayed = await app_client.post(+ "/api/v1/auth/mfa/verify",+ json={"mfa_token": second.json()["mfa_token"], "code": code},+ )+ assert replayed.status_code == 401, f"a TOTP code was accepted twice in one step ({replayed.status_code})"++ async def test_another_tenants_admin_cannot_reset_this_users_factor(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ victim = await _user(db)+ await _enrol(app_client, victim, await _bearer(app_client, victim))++ outsider = await _user(db, role="tenant_admin")+ response = await app_client.post(+ f"/api/v1/auth/mfa/reset/{victim['id']}",+ json={"reason": "support request"},+ headers=await _bearer(app_client, outsider),+ )+ assert response.status_code in (403, 404), response.text++ # And the factor is still there.+ still_challenged = await _password_login(app_client, victim)+ assert still_challenged.status_code == 202+++class TestEnrolmentAndResetAreAudited:+ async def test_both_write_an_audit_row(self, app_client: httpx.AsyncClient, db: AsyncSession) -> None:+ import sqlalchemy++ admin = await _user(db, role="tenant_admin")+ member = await _user(db, tenant_id=admin["tenant_id"])+ await _enrol(app_client, member, await _bearer(app_client, member))++ reset = await app_client.post(+ f"/api/v1/auth/mfa/reset/{member['id']}",+ json={"reason": "lost phone, verified by voice"},+ headers=await _bearer(app_client, admin),+ )+ assert reset.status_code == 200, reset.text++ await db.rollback()+ actions = {+ row[0]+ for row in (+ await db.execute(+ sqlalchemy.text("SELECT action FROM audit_log WHERE tenant_id = :t"),+ {"t": admin["tenant_id"]},+ )+ ).all()+ }+ assert "mfa.enrolled" in actions, f"enrolment wrote no audit row; saw {sorted(actions)}"+ assert "mfa.reset" in actions, f"an administrative reset wrote no audit row; saw {sorted(actions)}"++ # A reset removes the factor, so the next password login succeeds+ # outright — that is the point of the reset and also what makes it+ # worth auditing.+ assert (await _password_login(app_client, member)).status_code == 200