fix(auth): let every fresh-factor refusal open the re-proof dialog

A Guardian signed in through single sign-on with a second factor enrolled
could not hand a managed profile over once five minutes had passed since
sign-in: the handover answered 401 auth.stepup.required, and the panel
printed "Confirm your second factor, then try again" with no way to do so.

The same held for every action behind requireFreshMfa: creating, editing
and ending a managed profile, adding and removing a Guardian, disabling
the second factor, rotating recovery codes, removing a security key or a
passkey, changing the password, the data wipe, account deletion and the
key rotation. The recent-proof routes had the dialog; these had text.

- requireFreshMfa names the proofs that clear a stale stamp in
  meta.methods (the possession proofs the account holds, never a
  password, which stamps reproofAt only).
- The re-proof flow treats that refusal like auth.reproof.required:
  open the dialog, post the proof to /api/auth/reproof, send the request
  once more. The flow moves into a React-free module so it can be driven
  in tests; the hook binds it to the dialog.
- The managed-profile mutation hooks take a required proof guard, and
  every caller passes recentProof.run. The other surfaces wrap their
  requests in recentProof.run; disabling the second factor asks before
  its confirmation opens, so the code typed there is not spent twice.
- An account with nothing to re-prove in place (single sign-on only, no
  factor) is told to sign in again when adding a factor, instead of being
  offered a password it does not have.
- step-up-web-caller-guard freezes the gated route methods and fails when
  a web request to one of them runs outside the flow.

An account whose only second factor is the identity provider's is still
asked for an app factor on the managed-profile acts: the app cannot see
the provider's factor. Enrolling right after a sign-in needs no further
proof, and the confirmation stamps the session, so the act follows.

Refs #959
This commit is contained in:
Marc-André Bombeck committed 2026-10-17 09:17:03 +02:00
1 parent 59f910df5e
commit 99f0607a69
36 files changed
+2122 -466

No files matched your search

@@ -0,0 +1,383 @@
/**
* Every web action behind a fresh-proof gate goes through the re-proof dialog.
*
* Two server gates hold an action back until the session has proved something
* recently: the recent-proof gate (`requireRecentProof`,
* `assertRecentCookieProof`, 401 `auth.reproof.required`) and the fresh-factor
* gate (`requireFreshMfa` and the helpers that escalate to it, 401
* `auth.stepup.required`). Both name the proofs that clear them in
* `meta.methods`, and `useRecentProof` opens the dialog on either, posts the
* proof to `/api/auth/reproof` and runs the action once more.
*
* The defect this exists for: the managed-profile acts (handing a profile
* over, adding and removing a Guardian, creating, editing and ending a
* record) answered the fresh-factor refusal with a sentence telling the
* person to confirm their second factor, and offered nowhere to do it. The
* same was true of disabling the second factor, rotating recovery codes,
* removing a security key or passkey, changing the password, the data wipe,
* account deletion and the key rotation. The recent-proof surfaces had the
* dialog; the fresh-factor ones had text.
*
* What it pins:
*
* 1. The set of gated route methods, discovered from the route files and
* frozen below. A new gated route has to be entered here, with either
* its web callers checked by the sweep or the reason it has none.
* 2. Every request a web file makes to one of them runs inside the shared
* flow: `recentProof.run(…)` in a component, or `guard(…)` inside a
* query hook whose `guard` parameter every caller fills with
* `recentProof.run`. A gated request outside it is the defect again.
*
* Every sweep asserts a floor, because a matcher that finds nothing agrees
* with every list.
*/
import { describe, expect, it } from "vitest";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { walkSourceFiles } from "./helpers/source-files";
const SRC = join(process.cwd(), "src");
function read(rel: string): string {
return readFileSync(join(SRC, rel), "utf8");
}
/**
* Source with comments removed, so a route that only DESCRIBES a gate in its
* doc comment is not counted, and a path quoted in a comment is not a call.
*/
function code(rel: string): string {
return read(rel)
.replace(/\/\*[\s\S]*?\*\//g, "")
.split("\n")
.map((line) => line.replace(/(^|[^:"'`\\])\/\/.*$/, "$1"))
.join("\n");
}
const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
const GATE =
/\b(?:requireFreshMfa|requireFreshMfaIfEnrolled|requireFreshMfaOrElevationIfEnrolled|requireRecentProof|assertRecentCookieProof)\s*\(|\bfreshFactor\s*:\s*true\b/;
/** `src/app/api/a/[id]/route.ts` -> `/api/a/[id]`. */
function routePath(rel: string): string {
return "/" + rel.replace(/^app\//, "").replace(/\/route\.ts$/, "");
}
/** The gated `METHOD /api/path` pairs, read off the route files. */
function discoverGatedRoutes(): string[] {
const routes = walkSourceFiles(join(SRC, "app", "api"), { floor: 300 })
.filter((p) => p.endsWith("/route.ts") && !p.includes("__tests__"))
.map((p) => `app/api/${p}`);
expect(routes.length).toBeGreaterThan(300);
const found = new Set<string>();
for (const rel of routes) {
const src = code(rel);
if (!GATE.test(src)) continue;
const exportRe = new RegExp(
`export\\s+(?:const\\s+(${METHODS.join("|")})\\s*=|async\\s+function\\s+(${METHODS.join("|")})\\s*\\()`,
"g",
);
const exports = [...src.matchAll(exportRe)].map((m) => ({
method: m[1] ?? m[2],
index: m.index ?? 0,
}));
const path = routePath(rel);
// A gate before the first exported method lives in a helper or a
// `handler` constant the exports wrap, and binds every method.
const preamble = src.slice(0, exports[0]?.index ?? src.length);
if (GATE.test(preamble)) {
for (const e of exports) found.add(`${e.method} ${path}`);
}
exports.forEach((e, i) => {
const block = src.slice(e.index, exports[i + 1]?.index ?? src.length);
if (GATE.test(block)) found.add(`${e.method} ${path}`);
});
}
return [...found].sort();
}
/**
* Every gated route method, and how the web reaches it. `"web"` means the
* sweep below finds its callers and checks them; anything else is the reason
* no web file calls it.
*/
const GATED_ROUTES: Record<string, string> = {
"DELETE /api/admin/data": "web",
"DELETE /api/auth/me/mfa/webauthn/[id]": "web",
"DELETE /api/auth/passkeys/[id]": "web",
"DELETE /api/managed-profiles/[id]": "web",
"DELETE /api/managed-profiles/[id]/guardians/[grantId]": "web",
"DELETE /api/settings/account": "web",
"DELETE /api/settings/data": "web",
"GET /api/admin/backups/[id]/download": "web",
"GET /api/auth/reproof":
"the flow's own question: the web asks it inside recentProof.run before an upload or a typed confirmation",
"GET /api/export":
"the plaintext whole-record download (`type=all`); the web's whole-record export is the full backup, and its single-type exports have their own routes",
"GET /api/export/full-backup": "web",
"GET /api/fhir/Patient/$everything":
"a FHIR client endpoint, reached with a fhir:read token; no web file calls it",
"GET /api/mcp/oauth/authorize":
"a browser navigation from an assistant, answered with a page that links to /confirm-access, which runs the dialog",
"PATCH /api/managed-profiles/[id]": "web",
"POST /api/account/grants": "web",
"POST /api/admin/backups/[id]/restore": "web",
"POST /api/admin/backups/upload": "web",
"POST /api/admin/encryption/rotate": "web",
"POST /api/admin/users/[id]/reset-password": "web",
"POST /api/auth/me/mfa/disable": "web",
"POST /api/auth/me/mfa/recovery-codes/regenerate": "web",
"POST /api/auth/password": "web",
"POST /api/export/encrypted": "web",
"POST /api/export/health-record": "web",
"POST /api/managed-profiles": "web",
"POST /api/managed-profiles/[id]/guardians": "web",
"POST /api/managed-profiles/[id]/handover": "web",
"POST /api/mcp/oauth/authorize":
"the consent form's own submission, refused into the same /confirm-access page as the GET",
"POST /api/mcp/tokens": "web",
"POST /api/share-links": "web",
"POST /api/tokens/documents": "web",
"POST /api/tokens/measurements": "web",
"POST /api/tokens/workouts": "web",
};
/** The web side: everything under src that is not a route, a test or docs. */
function webFiles(): string[] {
return walkSourceFiles(SRC, { floor: 3000 })
.filter((p) => !p.startsWith("generated/"))
.filter((p) => !p.startsWith("app/api/"))
.filter((p) => !p.startsWith("lib/openapi/"))
.filter((p) => !p.includes("__tests__"))
.filter((p) => !p.endsWith(".test.ts") && !p.endsWith(".test.tsx"))
.sort();
}
/** A string or template literal naming exactly this path. */
function pathPattern(path: string): RegExp {
const body = path
.split("/")
.map((seg) =>
/^\[.+\]$/.test(seg)
? "\\$\\{[^}]+\\}"
: seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
)
.join("/");
return new RegExp(`["'\`]${body}(?=["'\`?])`, "g");
}
/** Which method a call naming the path at `index` sends. */
function methodAt(src: string, index: number, matchLength: number): string {
const before = src.slice(Math.max(0, index - 160), index);
const helper = [
...before.matchAll(/\bapi(Get|Post|Put|Patch|Delete)\b(?:<[^()]*>)?\s*\(/g),
].pop();
// The helper must be the call this literal is the first argument of.
if (
helper &&
/^\s*$/.test(before.slice((helper.index ?? 0) + helper[0].length))
) {
return helper[1].toUpperCase();
}
const after = src.slice(index + matchLength, index + matchLength + 240);
const explicit = after.match(/method\s*:\s*["'](\w+)["']/);
return explicit ? explicit[1].toUpperCase() : "GET";
}
/** The name of the function the code at `index` sits in, if it has one. */
function enclosingFunction(src: string, index: number): string | null {
const head = src.slice(0, index);
const decls = [
...head.matchAll(
/(?:\bfunction\s+(\w+)\s*\(|\b(?:const|let)\s+(\w+)\s*=\s*(?:async\s+)?(?:\([^)]*\)|\w+)\s*=>)/g,
),
].pop();
return decls ? (decls[1] ?? decls[2] ?? null) : null;
}
/**
* The request at `index` runs inside the shared flow: directly inside a
* `recentProof.run(…)` or a hook's `guard(…)`, or in a named function that is
* itself handed to, or called from, `recentProof.run`.
*/
function guardedAt(src: string, index: number): boolean {
const before = src.slice(Math.max(0, index - 400), index);
if (/(?:\.run|\bguard)\s*\(/.test(before)) return true;
const name = enclosingFunction(src, index);
if (!name) return false;
return new RegExp(
`\\.run\\(\\s*(?:async\\s*)?(?:\\(\\)\\s*=>\\s*)?${name}\\b`,
).test(src);
}
interface GatedCall {
file: string;
route: string;
guarded: boolean;
}
/**
* A query hook whose request is not guarded inside the hook is still guarded
* when every component that mounts it sends the mutation through the flow:
* `recentProof.run(() => mutation.mutateAsync(…))`. At least one such
* component must exist, or nothing is guarded.
*/
function hookCallersWrap(
files: string[],
hookFile: string,
src: string,
index: number,
): boolean {
const hook = [
...src.slice(0, index).matchAll(/export function (use\w+)/g),
].pop()?.[1];
if (!hook) return false;
let callers = 0;
for (const file of files) {
if (file === hookFile) continue;
const other = code(file);
for (const m of other.matchAll(
new RegExp(`\\b(?:const|let)\\s+(\\w+)\\s*=\\s*${hook}\\s*\\(`, "g"),
)) {
callers++;
const wraps = new RegExp(
`\\.run\\(\\s*(?:async\\s*)?\\(\\)\\s*=>\\s*${m[1]}\\.mutateAsync\\b`,
);
if (!wraps.test(other)) return false;
}
}
return callers > 0;
}
function gatedWebCalls(): GatedCall[] {
const calls: GatedCall[] = [];
const files = webFiles();
const sources = new Map(files.map((f) => [f, code(f)]));
for (const route of Object.keys(GATED_ROUTES)) {
if (GATED_ROUTES[route] !== "web") continue;
const [method, path] = route.split(" ");
const re = pathPattern(path);
for (const file of files) {
const src = sources.get(file) ?? "";
for (const m of src.matchAll(re)) {
const index = m.index ?? 0;
// The path handed to a component as a prop (`endpoint="/api/…"`):
// the request is wherever that component sends the prop.
const prop = src.slice(Math.max(0, index - 40), index).match(/(\w+)=$/);
if (prop) {
const sends = [
...src.matchAll(
new RegExp(`\\bapiFetchRaw\\(\\s*${prop[1]}\\s*,`, "g"),
),
];
for (const send of sends) {
const at = send.index ?? 0;
if (methodAt(src, at, send[0].length) !== method) continue;
calls.push({ file, route, guarded: guardedAt(src, at) });
}
continue;
}
if (methodAt(src, index, m[0].length) !== method) continue;
const guarded =
guardedAt(src, index) ||
(file.startsWith("lib/queries/") &&
hookCallersWrap(files, file, src, index));
calls.push({ file, route, guarded });
}
}
}
return calls;
}
/**
* Calls the sweep cannot read as guarded, each checked by hand and pinned.
* The request runs after a `recentProof.run(() => apiGet("/api/auth/reproof"))`
* a few lines earlier, so the proof is in place before a file is sent or a
* typed confirmation is spent.
*/
const PRECHECKED = new Set<string>([
// `upload.mutationFn` asks first, then calls `uploadOnce`, so a large file
// is not sent once only to be refused.
"components/admin/backups-section.tsx -> POST /api/admin/backups/upload",
]);
describe("fresh-proof gates on the web", () => {
it("freezes the set of gated route methods", () => {
const discovered = discoverGatedRoutes();
expect(discovered.length).toBeGreaterThanOrEqual(30);
expect(discovered).toEqual(Object.keys(GATED_ROUTES).sort());
});
it("finds a web caller for every route marked as called from the web", () => {
const calls = gatedWebCalls();
expect(calls.length).toBeGreaterThanOrEqual(25);
const reached = new Set(calls.map((c) => c.route));
const unreached = Object.keys(GATED_ROUTES).filter(
(r) => GATED_ROUTES[r] === "web" && !reached.has(r),
);
expect(unreached).toEqual([]);
});
it("sends every gated request through the re-proof flow", () => {
const unguarded = gatedWebCalls()
.filter((c) => !c.guarded)
.map((c) => `${c.file} -> ${c.route}`)
.filter((key) => !PRECHECKED.has(key));
expect(unguarded).toEqual([]);
});
it("renders the dialog wherever a component runs the flow", () => {
const files = [...new Set(gatedWebCalls().map((c) => c.file))].filter((f) =>
f.endsWith(".tsx"),
);
expect(files.length).toBeGreaterThanOrEqual(10);
const missing = files.filter((f) => {
const src = code(f);
return !/useRecentProof\s*\(/.test(src) || !/\.dialog\b/.test(src);
});
expect(missing).toEqual([]);
});
it("makes every caller of a guarded query hook pass recentProof.run", () => {
// Hooks whose gated request runs inside `guard(…)`.
const hookFiles = [
...new Set(
gatedWebCalls()
.filter((c) => c.file.startsWith("lib/queries/"))
.map((c) => c.file),
),
];
expect(hookFiles.length).toBeGreaterThanOrEqual(1);
const hooks: string[] = [];
for (const file of hookFiles) {
for (const m of code(file).matchAll(
/export function (use\w+)\(\s*guard\s*:\s*ProofGuard\s*\)/g,
)) {
hooks.push(m[1]);
}
}
expect(hooks.length).toBeGreaterThanOrEqual(6);
const offenders: string[] = [];
let callSites = 0;
for (const file of webFiles()) {
if (hookFiles.includes(file)) continue;
const src = code(file);
for (const hook of hooks) {
for (const m of src.matchAll(
new RegExp(`\\b${hook}\\s*\\(([^)]*)\\)`, "g"),
)) {
callSites++;
if (!/^\s*\w+\.run\s*$/.test(m[1])) {
offenders.push(`${file}: ${hook}(${m[1].trim()})`);
}
}
}
}
expect(callSites).toBeGreaterThanOrEqual(6);
expect(offenders).toEqual([]);
});
});