refactor(auth): move the request guards out of api-handler into lib/auth/guards

api-handler.ts held two modules: the route wrapper and thirteen guards. The
guards now live in lib/auth/guards/, one module per family (the caller,
the acting-account carrier, the record modes, the cookie-only helpers, the
fresh-factor and recent-proof gates, the Bearer elevation, MFA management).
api-handler.ts keeps the wrapper and re-exports every guard, so it stays the
one public entry and no route changes its import.

The bodies move verbatim; only the version prefixes of moved comments are
dropped. The structural guards that read the auth layer now find the module
that declares a guard by name (helpers/auth-guards.ts) instead of a fixed
path, and a new guard holds the entry: nothing outside the folder but
api-handler.ts imports a guard module.
This commit is contained in:
Marc-André Bombeck committed 2026-10-23 10:54:23 +02:00
1 parent 9de64cae3e
commit ee1561496b
40 files changed
+2153 -1668

No files matched your search

+1 -1
View File
@@ -4,7 +4,7 @@ The server and runtime toolkit. Everything that is not a page, component, or rou
## Core request kit
- **`api-handler.ts`** — the `apiHandler` wrapper every route uses. Auth resolver (cookie OR Bearer), `requireAuth` / `requireAdmin` (admin is cookie-only by construction), idempotency plumbing, Wide-Event builder, GlitchTip forwarder.
- **`api-handler.ts`** — the `apiHandler` wrapper every route uses (Wide-Event builder, error envelope, GlitchTip forwarder) and the one public entry for the request guards in `auth/guards/`: the auth resolver (cookie OR Bearer), `requireAuth` / `requireRecordAuth` / `requireAdmin` (admin is cookie-only by construction), the step-up gates.
- **`api-response.ts`** — the `{ data, error, meta? }` envelope: `apiSuccess` / `apiError`, `safeJson`, trusted-proxy IP resolver, `returnAllZodIssues` + `sanitiseZodIssues`.
- **`rate-limit.ts`** — Postgres-backed sliding-window limiter (single atomic upsert); multi-instance correct.
- **`idempotency.ts`** — user-scoped idempotency keys that refuse to cache secret-shaped responses.
@@ -312,7 +312,7 @@ describe("requireAuth — MCP-audience tokens have no REST reach", () => {
// method — reads included. Its audience narrows from "/mcp + REST reads" to
// "/mcp only", which is what RFC 8707 audience binding asked for.
//
// The `isMcpAudienceToken` guard is retained in `api-handler.ts` as defence
// The `isMcpAudienceToken` guard is retained in `lib/auth/guards/caller.ts` as defence
// in depth; it is unreachable on this path, which is exactly why these tests
// assert `undeclared_scope` rather than `mcp_audience_write_blocked`.
const route = apiHandler(async (req) => {
+57 -1538
View File
File diff suppressed because it is too large. Load diff
+1 -1
View File
@@ -4,7 +4,7 @@
* Two things in the app have to answer that question, and they have to answer
* it the same way:
*
* * `requireRecordAuth` (`src/lib/api-handler.ts`), which turns the claim
* * `requireRecordAuth` (`src/lib/auth/guards/record.ts`), which turns the claim
* into a data scope after checking a live grant.
* * `withIdempotency` (`src/lib/idempotency.ts`), which files the replay cell
* under the record the request claims — before any handler runs, so it
+122
View File
@@ -0,0 +1,122 @@
import { annotate, getEvent } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import {
carrierTarget,
decideActingCarrier,
readSelectorHeader,
type ActingCarrier,
} from "@/lib/auth/acting-carrier";
import { SharingNotPermittedError } from "@/lib/api-errors";
import type { AuthContext } from "./context";
// ── The acting-account resolver ─────────────────────────────────────────────
//
// One function decides, for every transport, whether this request acts on
// somebody else's record — the same argument that put `resolveBearerToken` in
// one file for two wires. Two carriers converge on one decision because they
// are two answers to one question, and two answers that live apart drift.
//
// That decision lives in `@/lib/auth/acting-carrier`, because a second caller
// needs it: the idempotency wrapper files its replay cell under the record a
// request claims, and it runs before any auth context exists. What stays in
// the guards is what only they may do: turning a claim into a data scope after
// a live grant says so (`./record.ts`), and refusing one (below).
/**
* The acting-account carrier for this request.
*
* The session value rides out of `getSession()` on the row that call already
* loaded — a second query for a column we have just read would be waste on
* every cookie request in the app. What does NOT ride out of `getSession()` is
* a substituted user: it keeps answering "who is calling" and nothing else,
* which is exactly why `requireAdmin`, `requireCookieAuth` and
* `requireFreshMfa` are unreachable by a switch. The carrier is an id to be
* checked, not a decision that has been made.
*
* Fresh on every request, by construction: `getSession()` reads the row from
* Postgres each time, so a switch cleared by a revocation is gone from the very
* next request rather than from the next login.
*/
export async function readActingCarrier(
auth: AuthContext,
): Promise<ActingCarrier> {
return decideActingCarrier({
transport: auth.authMethod === "bearer" ? "bearer" : "cookie",
stamped: auth.session.actingAsUserId ?? null,
header: await readSelectorHeader(),
});
}
/**
* Record a refused delegation.
*
* The row is filed under the CALLER, with no actor, and it is the operator's
* trail rather than the owner's. It names who called, the account they claimed,
* and why the claim was refused — none of which reaches the response.
*
* It is deliberately not filed under the claimed account, and that decision is
* worth stating because the opposite reads as the obvious one. A row is only
* written for a HEADER refusal, and a header is an unverified per-request
* assertion: the value is whatever the caller typed. Filing under it would let
* any authenticated caller write rows into any account's activity feed by
* naming it, which is a spam vector aimed at exactly the panel that exists to
* be trustworthy. Verifying the claim first would mean a grant lookup on a path
* whose whole job is to refuse without touching the record.
*
* What the owner does see is the other half: `recordDelegatedAccess` files a
* per-day row under the OWNER, naming the actor, for every delegated read that
* succeeded. "Who reached my record" is answered there. "Whose client sent a
* malformed claim" is an operator question and stays here.
*
* Fire-and-forget: an audit write that fails must not convert a 403 into a 500,
* because the 403 is the part that protects the record.
*/
export function auditRefusal(
auth: AuthContext,
carrier: ActingCarrier,
reason: string,
): void {
auditLog("sharing.access.denied", {
userId: auth.user.id,
details: {
reason,
carrier: carrier.kind,
target: carrierTarget(carrier),
method: getEvent()?.getHttpMethod() ?? null,
},
}).catch(() => {});
}
/**
* This request says it is acting on another account and this route will not.
*
* Three ways to arrive: a route that never declared a mode (`undeclared_mode`),
* a selector sent over the transport that does not carry one
* (`misplaced_selector`), and a narrow single-purpose Bearer naming a record
* that is not its owner's (`narrow_scope_selector`). One response every way —
* the caller learns that the request will not be served, and nothing about
* grants.
*
* The audit rule, stated once because it is a judgement call: a HEADER refusal
* always writes a row, a SESSION refusal never does. The header is a per-request
* assertion by a client — a bug or a probe, and both are worth a durable record.
* The session field is ambient browser state: while a switch is on, every
* navigation, prefetch and poll that touches a non-delegable route lands here,
* and a row per such request would bury the header rows that matter under noise
* from the feature working as designed. Both are on the wide event either way.
*/
export function refuseUndeclaredMode(
auth: AuthContext,
carrier: ActingCarrier,
reason:
| "undeclared_mode"
| "misplaced_selector"
| "narrow_scope_selector" = "undeclared_mode",
): SharingNotPermittedError {
annotate({ meta: { sharing_refusal: reason } });
if (carrier.kind !== "session") {
auditRefusal(auth, carrier, reason);
}
return new SharingNotPermittedError();
}
+297
View File
@@ -0,0 +1,297 @@
import { headers } from "next/headers";
import { getEvent } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import {
resolveBearerToken,
BearerAuthError,
type ScopeRequirement,
} from "@/lib/auth/bearer";
import { hashToken } from "@/lib/auth/hmac";
import {
meterAccountWrite,
type WriteMeterOptions,
} from "@/lib/auth/write-meter";
import { getSession } from "@/lib/auth/session";
import { AUTH_ERROR_CODES, HttpError } from "@/lib/api-errors";
import { readActingCarrier, refuseUndeclaredMode } from "./acting";
import {
READ_HTTP_METHODS,
isMcpAudienceToken,
type AuthContext,
} from "./context";
/**
* Require an authenticated request. Throws HttpError(401) / HttpError(403) on failure.
*
* Auth precedence (cookie-first, never both):
* 1. Valid session cookie → cookie path (existing behaviour, requiredPermission ignored).
* 2. No cookie + `Authorization: Bearer hlk_<...>` → API token path.
* 3. Neither → 401.
*
* And it REFUSES to run while the request is acting on another
* account. A bare `requireAuth()` is an undeclared route: nobody has decided
* whether it is safe under a switch, and the routes that call it include the
* password change, the MFA management surface, the token mint, and the
* integration connect. So a request carrying an acting-account carrier gets a
* 403 `sharing.not_permitted` here, and never a silent fall-back to the
* caller's own record.
*
* The fall-back is the tempting wrong answer and is worth naming: it looks
* harmless, it keeps every un-migrated route working, and it is the reverse
* data-mixing failure. A delegate reading what they believe is the owner's
* record would be shown their own; a delegate writing what they believe is the
* owner's measurement would write it into theirs. An inaccessible route is an
* inconvenience. A route that answers with the wrong person's health record is
* the product being wrong about the only thing it does.
*
* @param requiredPermission Optional permission scope. Only enforced for Bearer
* auth — cookie sessions always pass (full user access). Omitting it is a
* positive declaration: the route accepts cookie sessions and cookie-
* equivalent (`["*"]`) tokens ONLY, and refuses a narrow-scope token with
* HttpError(403). Naming a scope additionally admits narrow tokens that list
* it. A token that lists neither `*` nor the named scope throws
* HttpError(403).
*/
export async function requireAuth(
requiredPermission?: string,
options?: WriteMeterOptions,
): Promise<AuthContext> {
const auth = await authenticateCaller(requiredPermission);
const carrier = await readActingCarrier(auth);
if (carrier.kind !== "none") {
throw refuseUndeclaredMode(auth, carrier);
}
// The shared write ceiling, for every write this resolver admits — see
// `meterAccountWrite`.
await meterAccountWrite(auth.user.id, options);
return auth;
}
/**
* Resolve the caller as themselves. The pre-v1.36.0 `requireAuth` body,
* unchanged, split out so the three declared modes above it can share it.
*
* This function knows nothing about acting accounts and must not learn: it is
* the thing every mode agrees on before they disagree about what the request
* is allowed to reach.
*/
export async function authenticateCaller(
requiredPermission?: string,
): Promise<AuthContext> {
// 1. Session cookie path — unchanged.
const sessionData = await getSession();
if (sessionData) {
const evt = getEvent();
if (evt) {
evt.setAuth({
user_id: sessionData.user.id,
user_role: sessionData.user.role,
auth_method: "session",
});
}
return { ...sessionData, authMethod: "cookie" };
}
// 2. Bearer-token path.
// `headers()` is only valid inside a Next.js request scope. Outside one
// (e.g. during direct unit tests of legacy routes that pre-date Bearer auth)
// we treat the absence of a header context as "no Bearer present" and fall
// through to the unauthenticated case below.
let authHeader: string | null = null;
try {
const headerList = await headers();
authHeader = headerList.get("authorization");
} catch {
authHeader = null;
}
if (authHeader?.startsWith("Bearer ")) {
return await authenticateBearer(authHeader.slice(7), requiredPermission);
}
// 3. No credentials.
throw new HttpError(401, "Not authenticated", AUTH_ERROR_CODES.missing);
}
/**
* Authenticate a raw Bearer token against `ApiToken`.
*
* The validation itself lives in the transport-agnostic `resolveBearerToken`
* (`./auth/bearer`) — the single source of truth shared with the MCP wire. This
* wrapper adds the HTTP-edge concerns: the `auth.bearer.failure` audit trail
* (only the failure path writes a durable audit row — the success row was
* intentionally dropped for perf) and the Wide-Event `auth_method: "bearer"`
* annotation, then maps the result onto the `AuthContext` contract
* (`session.id` carries the token id).
*
* Authorisation contract (fail-closed): a route that declares no
* `requiredPermission` accepts cookie sessions and cookie-equivalent (`["*"]`)
* tokens only — a narrow-scope token is refused 403 with an `undeclared_scope`
* audit row. A route that declares a scope additionally accepts narrow tokens
* that list it. The absence of an argument is a positive statement, not an
* omission, which is what makes the default safe for routes nobody has thought
* about yet.
*/
export async function authenticateBearer(
rawToken: string,
requiredPermission: string | undefined,
): Promise<AuthContext> {
const requirement: ScopeRequirement = requiredPermission
? { kind: "scope", scope: requiredPermission }
: { kind: "wildcard-only" };
let resolution;
try {
resolution = await resolveBearerToken(rawToken, requirement);
} catch (err) {
if (err instanceof BearerAuthError) {
auditLog("auth.bearer.failure", {
userId: err.userId ?? null,
details: {
reason: err.reason,
...(err.tokenId ? { tokenId: err.tokenId } : {}),
...(err.reason === "insufficient_permissions"
? { required: requiredPermission }
: {}),
},
}).catch(() => {});
// Sentence and code are decided together, so a future rewording of the
// prose cannot silently change what a client does with the refusal.
const [message, errorCode] =
err.statusCode === 403
? (["Insufficient permissions", AUTH_ERROR_CODES.scope] as const)
: err.reason === "expired"
? (["Token expired", AUTH_ERROR_CODES.expired] as const)
: (["Invalid token", AUTH_ERROR_CODES.invalid] as const);
throw new HttpError(err.statusCode, message, errorCode);
}
throw err;
}
const { user, tokenId, expiresAt, permissions } = resolution;
// H1 — audience binding at the resource server. An MCP-audience token
// (`health:read`, or `health:read health:write`) is bound to the `/mcp`
// surface; it may reach `/mcp` (a separate resolver that never runs this
// edge) and safe REST reads, but a write/delete over REST is outside its
// audience and is refused — INCLUDING a write-scoped token, whose writes are
// confined to the in-process `/mcp` tools and never granted over REST. Fail
// closed when the method is unknown
// (no event context) since every real REST request runs inside apiHandler,
// which always sets the method — an unknown method means we cannot prove a
// read, so we deny. This is RFC 8707 audience binding on the credential the
// client actually holds, not only during the OAuth exchange.
//
// Since the fail-closed scope default landed, this guard is unreachable on
// the deny path: an MCP-audience token carries no `*`, so `wildcard-only`
// already refused it in `resolveBearerToken` before we get here (an MCP
// token's REST reach is now nil, not "safe methods"). It is kept as defence
// in depth — it still holds the line if a future REST route ever declares
// `health:read` and so admits the token past the resolver.
if (isMcpAudienceToken(permissions)) {
const method = (getEvent()?.getHttpMethod() ?? "").toUpperCase();
if (!READ_HTTP_METHODS.has(method)) {
auditLog("auth.bearer.failure", {
userId: user.id,
details: {
reason: "mcp_audience_write_blocked",
tokenId,
method: method || "unknown",
},
}).catch(() => {});
throw new HttpError(
403,
"Insufficient permissions",
AUTH_ERROR_CODES.scope,
);
}
}
// No per-request success audit row. The polling iOS client drove a
// constant INSERT + pool checkout on every authenticated Bearer request; the
// wide event below already records `auth_method: "bearer"` + `user_id`, so the
// success path stays fully observable without the write churn. The failure
// path keeps its audit row.
const evt = getEvent();
if (evt) {
evt.setAuth({
user_id: user.id,
user_role: user.role,
auth_method: "bearer",
});
}
return {
session: { id: tokenId, expiresAt },
user,
authMethod: "bearer",
// Non-null exactly when a NAMED scope admitted a narrow token. A `["*"]`
// token is cookie-equivalent and reads null however the route was declared;
// a narrow token on a route that named no scope never reaches this line,
// because `wildcard-only` already refused it in `resolveBearerToken`.
//
// Derived here rather than in the resolver so `bearer.ts` keeps its single
// authorisation arm: this is a report of the decision that already ran, not
// a second one.
bearerScope: permissions.includes("*")
? null
: (requiredPermission ?? null),
};
}
/**
* A Bearer-resolved caller.
*
* `apiTokenId` and `accessTokenHash` are named rather than smuggled through
* `AuthContext.session.id`. That field means "the session row id" on the cookie
* path and "the ApiToken row id" on the Bearer path, and code that forgot which
* one it held passed a token id to a session-scoped query — deleting every one
* of the user's browser sessions and revoking the caller's own refresh token.
* Naming the fields is what stops that recurring.
*/
export interface BearerAuthContext extends AuthContext {
/** The `ApiToken` row id — the binding a step-up elevation is tied to. */
apiTokenId: string;
/**
* HMAC of the presented access token, which is what `RefreshToken`
* cross-references in `accessTokenHash`. Lets a route identify the CALLER's
* own device login and spare it when revoking every other one.
*/
accessTokenHash: string;
}
/**
* Resolve a caller by Bearer token ONLY, refusing a cookie session.
*
* The mirror image of `requireCookieAuth`, and it exists for one surface: the
* step-up mint endpoints, which are the Bearer transport's own re-authentication
* flow and have no meaning for a browser (a browser re-proves a factor at login
* and carries the result on its session row). Refusing the cookie keeps the mint
* surface entirely outside the cookie's blast radius — no ambient credential can
* reach it, so the class of attack where a browser is induced to fire a request
* on the user's behalf simply does not apply.
*
* Scope handling is the standard fail-closed default: no declared scope, so only
* a cookie-equivalent (`["*"]`) token is admitted. A narrow token — an MCP grant,
* a medication-ingest grant — is refused 403 by the resolver.
*/
export async function requireBearerAuth(): Promise<BearerAuthContext> {
let authHeader: string | null = null;
try {
const headerList = await headers();
authHeader = headerList.get("authorization");
} catch {
authHeader = null;
}
if (!authHeader?.startsWith("Bearer ")) {
throw new HttpError(401, "Not authenticated", AUTH_ERROR_CODES.missing);
}
const raw = authHeader.slice(7);
const auth = await authenticateBearer(raw, undefined);
await meterAccountWrite(auth.user.id);
return {
...auth,
apiTokenId: auth.session.id,
accessTokenHash: hashToken(raw),
};
}
+111
View File
@@ -0,0 +1,111 @@
/**
* The authenticated request context every guard returns, and the two
* predicates over a credential that more than one guard needs.
*
* The guards themselves are in the sibling modules; route handlers import
* all of them through `@/lib/api-handler`.
*/
import type { SessionUser } from "@/lib/auth/session-user";
import { SCOPE_HEALTH_READ, SCOPE_HEALTH_WRITE } from "@/lib/mcp/oauth/config";
/**
* HTTP methods a read-only credential may use on the REST surface. A request
* with any other method (POST / PUT / PATCH / DELETE) is a write.
*
* The MCP-audience guard below assumes these methods are side-effect-free:
* an MCP-bound token is admitted on them. A future side-effecting GET (or HEAD)
* would silently widen that token's reach over REST — do NOT add one without
* revisiting the MCP audience binding here.
*/
export const READ_HTTP_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
/**
* Whether a token is MCP-audience-bound (H1). The MCP OAuth bridge and the
* connector settings card mint tokens whose ONLY grants are `health:read` —
* and, when the user consents to logging, `health:read health:write`. Either
* shape is bound to the MCP surface: the `/mcp` resolver accepts it and so do
* safe (read) REST methods, but it must NEVER reach a REST write/delete. The
* `health:write` grant admits writes ONLY in-process over `/mcp` (the confirmed
* write tools), never over REST — so a write-scoped MCP token is exactly as
* audience-bound on this edge as a read-only one. A token carrying any broader
* or legacy grant (`*`, `medication:ingest`, …) is NOT MCP-audience-bound and
* keeps its existing reach.
*/
export function isMcpAudienceToken(permissions: readonly string[]): boolean {
if (permissions.length === 0) return false;
return permissions.every(
(p) => p === SCOPE_HEALTH_READ || p === SCOPE_HEALTH_WRITE,
);
}
/**
* Authenticated request context. Returned by both session-cookie and Bearer-token
* authentication paths. The `session.id` is the session-record id for cookie auth
* and the `ApiToken` id for bearer auth — callers must not assume the id refers
* to a Session row.
*/
export type AuthContext = {
session: {
id: string;
expiresAt: Date;
/**
* The cookie transport's acting-account carrier, straight off
* the session row. Absent on the Bearer path, which has no session row and
* carries its selector in a per-request header instead.
*
* Optional so that the ~180 test files which hand `requireAuth` a
* hand-built session context keep compiling; an absent field means the
* same thing as a null one — no switch. Only the acting-account resolver
* below reads it.
*/
readonly actingAsUserId?: string | null;
/**
* How many times this session's record selector has moved. The
* record-session fence compares it against what the request asserted.
*
* Optional for the same reason as `actingAsUserId` above, and `undefined`
* reads as `0` — which is the fence's exemption, so a hand-built test
* context keeps meaning "a session that never switched". Read only by the
* fence.
*/
readonly recordEpoch?: number;
};
user: SessionUser;
/**
* Transport the caller authenticated with, derived from the SAME branch that
* sets the wide event's `auth_method`: the cookie-session path resolves
* `"cookie"`, the Bearer-token path resolves `"bearer"`. Read-only and never
* client-asserted — it is the transport fact, not a request field. A route
* that must record write provenance (e.g. the medication-intake `source`)
* maps it server-side, the same posture as `userId` being narrowed from auth.
*/
readonly authMethod: "cookie" | "bearer";
/**
* The named scope that admitted this Bearer, or null when the credential is
* cookie-equivalent — a session, or a `["*"]` token. A non-null value marks a
* NARROW, single-purpose credential: one minted for one job, by its own
* holder, from their own settings page.
*
* A single nullable string rather than the token's permission array, and that
* is the point: nothing downstream can re-derive an authorisation decision
* from it. The decision was made once, in `resolveBearerToken`; this only
* reports which arm ran, so a route can refuse a narrow credential something
* a cookie session may still do.
*
* Optional for the reason `actingAsUserId` and `recordEpoch` above are: the
* test files that hand-build this object keep compiling, and an absent field
* reads as null — "cookie-equivalent", which is what a hand-built context has
* always meant.
*/
readonly bearerScope?: string | null;
};
/**
* Was this request authenticated by a narrow, single-purpose Bearer scope?
*
* The one reader of `bearerScope`, exported so no handler re-derives the test
* and they cannot drift on what "narrow" means.
*/
export function isScopedCredential(auth: AuthContext): boolean {
return (auth.bearerScope ?? null) !== null;
}
+65
View File
@@ -0,0 +1,65 @@
import { getEvent } from "@/lib/logging/context";
import { getSession } from "@/lib/auth/session";
import { meterAccountWrite } from "@/lib/auth/write-meter";
import { AUTH_ERROR_CODES, HttpError } from "@/lib/api-errors";
import type { AuthContext } from "./context";
/**
* Require an authenticated admin user. Throws HttpError(401) or HttpError(403).
* Cookie-only — Bearer tokens never elevate to admin (security boundary).
* Automatically annotates the Wide Event with auth context.
*
* Unreachable by a switch, structurally: it resolves through
* `getSession()`, which knows only who is calling, and the role is read off
* that row. Switching into an ADMIN's record therefore confers nothing, and
* making it confer something would take a deliberate edit here rather than an
* oversight elsewhere.
*/
export async function requireAdmin(): Promise<AuthContext> {
const sessionData = await getSession();
if (!sessionData)
throw new HttpError(401, "Not authenticated", AUTH_ERROR_CODES.missing);
const evt = getEvent();
if (evt) {
evt.setAuth({
user_id: sessionData.user.id,
user_role: sessionData.user.role,
auth_method: "session",
});
}
if (sessionData.user.role !== "ADMIN") {
throw new HttpError(403, "Admin access required", AUTH_ERROR_CODES.admin);
}
await meterAccountWrite(sessionData.user.id);
return { ...sessionData, authMethod: "cookie" };
}
/**
* Require a cookie-backed session, refusing Bearer tokens.
*
* Cookie-only by the same structural argument as `requireAdmin`: it resolves
* the session via `getSession()` (which reads only the session cookie) and
* never falls through to the Bearer branch. The second-factor management
* surfaces (TOTP enroll / confirm / disable / recovery-code regenerate) use
* this so an API token — even a wildcard one — can never enrol or tear down
* MFA on the account it belongs to. MFA management is a browser-only action.
*/
export async function requireCookieAuth(): Promise<AuthContext> {
const sessionData = await getSession();
if (!sessionData)
throw new HttpError(401, "Not authenticated", AUTH_ERROR_CODES.missing);
const evt = getEvent();
if (evt) {
evt.setAuth({
user_id: sessionData.user.id,
user_role: sessionData.user.role,
auth_method: "session",
});
}
await meterAccountWrite(sessionData.user.id);
return { ...sessionData, authMethod: "cookie" };
}
+110
View File
@@ -0,0 +1,110 @@
import { headers } from "next/headers";
import type { SessionUser } from "@/lib/auth/session-user";
import { annotate } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import {
claimStepUpElevation,
validateStepUpElevation,
STEP_UP_ELEVATION_TTL_SECONDS,
} from "@/lib/auth/step-up";
import { StepUpRequiredError } from "@/lib/api-errors";
import {
canProveFreshFactor,
type FreshFactorProofSource,
} from "./fresh-factor";
/**
* Header carrying a step-up elevation on the Bearer path. Never logged — the
* wide event captures no request headers at all, and `redactSecrets` carries an
* `hle_` rule as a second line of defence.
*/
export const STEP_UP_ELEVATION_HEADER = "x-step-up";
/**
* The Bearer elevation arm, shared by `requireMfaManagementAuth` and
* `requireFreshMfaOrElevationIfEnrolled` so there is exactly one place that
* reads the header, validates, refuses, and claims.
*
* Takes an ALREADY-RESOLVED Bearer caller: the token's own validity and scope
* were decided before this runs, and nothing here can widen that decision. It
* returns the commit closure — the atomic single-use claim — and throws
* `StepUpRequiredError` for a missing, unknown, foreign, spent, expired, or
* too-weak elevation, with the real reason in the audit row and none of it on
* the wire.
*/
export async function resolveBearerElevation(
auth: { user: SessionUser; apiTokenId: string },
options: { freshFactor: boolean; proofSource: FreshFactorProofSource },
): Promise<() => Promise<void>> {
const { freshFactor, proofSource } = options;
let raw: string | null = null;
try {
const headerList = await headers();
raw = headerList.get(STEP_UP_ELEVATION_HEADER);
} catch {
raw = null;
}
if (!raw) {
annotate({
action: { name: "auth.stepup.elevation.missing" },
meta: { maxAgeSeconds: STEP_UP_ELEVATION_TTL_SECONDS, freshFactor },
});
throw new StepUpRequiredError();
}
const rawToken = raw;
const refusal = (reason: string): StepUpRequiredError => {
// One audit row with the machine reason, one generic refusal on the wire.
// A prober learns only "not accepted" — never whether the elevation was
// unknown, already spent, expired, minted for a different token, or minted
// from a factor too weak for this route.
auditLog("auth.stepup.elevation.rejected", {
userId: auth.user.id,
details: { reason, freshFactor },
}).catch(() => {});
annotate({
action: { name: "auth.stepup.elevation.rejected" },
meta: { reason, freshFactor },
});
// Returned rather than thrown so every call site reads `throw refusal(...)`
// and the compiler narrows the result union afterwards.
return new StepUpRequiredError();
};
// Validate WITHOUT consuming. The route runs its own cheap checks next and
// spends the elevation only when it is about to act.
const validated = await validateStepUpElevation({
rawToken,
userId: auth.user.id,
apiTokenId: auth.apiTokenId,
requireFreshFactor: freshFactor,
});
if (!validated.ok) throw refusal(validated.reason);
// Parity with the cookie path: `requireFreshMfa` refuses an account that holds
// no credential able to produce the proof, because a step-up-gated action is
// unreachable rather than merely refused there. The Bearer path asks the same
// question, with the same `proofSource`, rather than becoming the softer or
// the stricter route.
if (freshFactor && !(await canProveFreshFactor(auth.user, proofSource))) {
throw new StepUpRequiredError("auth.stepup.mfa_not_enrolled");
}
return async () => {
const claimed = await claimStepUpElevation({
rawToken,
userId: auth.user.id,
apiTokenId: auth.apiTokenId,
requireFreshFactor: freshFactor,
});
if (!claimed.ok) throw refusal(claimed.reason);
annotate({
action: { name: "auth.stepup.elevation.accepted" },
meta: { method: claimed.method, freshFactor },
});
};
}
+92
View File
@@ -0,0 +1,92 @@
import { prisma } from "@/lib/db";
import { hasSecondFactorEnrolled } from "@/lib/auth/second-factor";
/**
* Default step-up freshness window (5 minutes) for sensitive mutations.
* Within the 5–15 min band OWASP recommends; tight end because the gated
* actions (disable MFA, regenerate codes, and later key rotation / export)
* are destructive.
*/
export const MFA_STEP_UP_MAX_AGE_SECONDS = 5 * 60;
/**
* Which credentials count when asking "can this account produce a fresh-factor
* proof at all".
*
* The gate is the same either way — a `Session.mfaVerifiedAt` inside the window
* on the cookie path, an elevation minted from a `FRESH_FACTOR_METHODS` proof on
* the Bearer path. What differs is the pre-check that decides whether refusing
* would be a gate or a dead end, and the honest answer to that depends on what
* the route is protecting.
*
* `second-factor` — a confirmed TOTP secret or a registered second-factor
* security key. The default of `requireMfaManagementAuth`, and the right
* question for the routes that MANAGE a second factor: there is nothing there
* to protect if nothing is enrolled.
*
* `any-possession` — the above, OR a registered PRIMARY passkey. The default
* of `requireFreshMfa` since v1.43.3, and the right question for a route
* protecting the passkey itself, because a passkey is a
* possession factor in its own right and this codebase already treats it as
* one in three places: `/api/auth/passkey/login-verify` stamps `mfaVerifiedAt`
* on a passkey login (v1.23, M-review M1), `passkey` is in
* `FRESH_FACTOR_METHODS` so a passkey-proved elevation reaches the fresh-factor
* routes, and `resolveMfaEnrollmentRequired` counts a primary passkey as
* satisfying the enforcement policy outright. A passkey-only account can
* therefore clear the gate on both transports, and asking the narrower
* question would have thrown `mfa_not_enrolled` at an account that was holding
* the proof all along.
*/
export type FreshFactorProofSource = "second-factor" | "any-possession";
/*
* A PASSKEY COUNTS AS A SECOND FACTOR FOR THE UNCONDITIONAL STEP-UP GATE.
*
* Maintainer decision, v1.43.3. `requireFreshMfa` defaults to
* `any-possession`, so an account whose only strong credential is a passkey
* is no longer refused `mfa_not_enrolled` on the routes that call it directly
* (creating, editing, deleting and handing over a managed profile, inviting
* and removing a guardian, the admin key rotation). It clears the gate the
* way every other account does: a passkey sign-in or a passkey re-proof at
* `POST /api/auth/reproof` stamps `Session.mfaVerifiedAt`, and the gate reads
* that stamp inside the same five minutes.
*
* The limits, each deliberate:
*
* - `hasSecondFactorEnrolled` keeps its narrow meaning. It decides whether
* the CONDITIONAL gates (`requireFreshMfaIfEnrolled`,
* `requireFreshMfaOrElevationIfEnrolled`, `requireRecentProof`'s branches,
* the enrollment proofs) apply at all. Widening it would newly gate
* account deletion, the data reset, the password change and the export
* for every passkey holder, take the password re-proof away from them, and
* change what the native app's Bearer requests need. None of that is part
* of the decision.
* - Password login is untouched. It asks for a second factor from
* `totpConfirmedAt` and the security-key count only; a passkey-only
* account signing in with its password is not challenged, as before.
* - The MFA-management routes (`requireMfaManagementAuth`) still default to
* `second-factor`: disabling TOTP or rotating recovery codes on an account
* with no second factor has nothing to protect.
* - Cookie only, as ever. The Bearer path is not reached from here.
*/
/**
* Can this account produce a fresh-factor proof at all?
*
* The wider question, asked by the routes that gate on possession rather than
* on second-factor management. See {@link FreshFactorProofSource} for why a
* primary passkey answers yes and where the codebase already says so; see
* {@link hasSecondFactorEnrolled} for why the narrower predicate must not be
* widened into this one.
*/
export async function canProveFreshFactor(
user: { id: string; totpConfirmedAt: Date | null },
proofSource: FreshFactorProofSource,
): Promise<boolean> {
if (await hasSecondFactorEnrolled(user)) return true;
if (proofSource === "second-factor") return false;
const passkeyCount = await prisma.passkey.count({
where: { userId: user.id },
});
return passkeyCount > 0;
}
+196
View File
@@ -0,0 +1,196 @@
import { prisma } from "@/lib/db";
import { annotate, getEvent } from "@/lib/logging/context";
import { getSession } from "@/lib/auth/session";
import {
hasSecondFactorEnrolled,
recentProofMethods,
} from "@/lib/auth/second-factor";
import { meterAccountWrite } from "@/lib/auth/write-meter";
import {
AUTH_ERROR_CODES,
HttpError,
StepUpRequiredError,
} from "@/lib/api-errors";
import { requireAuth } from "./caller";
import type { AuthContext } from "./context";
import { resolveBearerElevation } from "./elevation";
import {
canProveFreshFactor,
type FreshFactorProofSource,
} from "./fresh-factor";
export type FreshMfaContext = AuthContext & { mfaVerifiedAt: Date };
/**
* Step-up gate. Passes only for a COOKIE session whose
* `Session.mfaVerifiedAt` is within `maxAgeSeconds` AND whose user holds a
* credential that can produce such a stamp. Throws `StepUpRequiredError`
* (401, `errorCode: "auth.stepup.required"`) otherwise.
*
* Bearer tokens can NEVER satisfy this — exactly like `requireAdmin`, the
* resolution path is `getSession()` (cookie-only) and there is no Bearer
* fall-through. A token transport carries no `mfaVerifiedAt` and cannot
* acquire one, so the boundary is structural, not a softenable runtime check.
*
* Consumed in Phase M by MFA disable + recovery-code regeneration; later
* waves gate account deletion, key rotation, and passphrase export on it.
*
* @param proofSource which credentials count as "can prove a factor". Defaults
* to `any-possession`, so a primary passkey counts (see the decision note
* below {@link FreshFactorProofSource}); `requireMfaManagementAuth` passes
* `second-factor` explicitly.
*/
export async function requireFreshMfa(
maxAgeSeconds: number,
proofSource: FreshFactorProofSource = "any-possession",
): Promise<FreshMfaContext> {
const sessionData = await getSession();
if (!sessionData)
throw new HttpError(401, "Not authenticated", AUTH_ERROR_CODES.missing);
const evt = getEvent();
if (evt) {
evt.setAuth({
user_id: sessionData.user.id,
user_role: sessionData.user.role,
auth_method: "session",
});
}
await meterAccountWrite(sessionData.user.id);
// The account must hold a credential that can stamp `mfaVerifiedAt` in the
// first place. Without one a step-up-gated action is unreachable by design
// rather than merely refused, so the refusal is named differently
// (`mfa_not_enrolled`) and the management UI gates enrolment ahead of it.
if (!(await canProveFreshFactor(sessionData.user, proofSource))) {
throw new StepUpRequiredError("auth.stepup.mfa_not_enrolled");
}
// Read the freshness stamp off the live session row — `getSession`'s
// projection intentionally omits it.
const row = await prisma.session.findUnique({
where: { id: sessionData.session.id },
select: { mfaVerifiedAt: true },
});
const verifiedAt = row?.mfaVerifiedAt ?? null;
if (!verifiedAt || verifiedAt.getTime() < Date.now() - maxAgeSeconds * 1000) {
// Name the proofs that clear this gate, the way the recent-proof gate
// does, so the browser can open the re-proof dialog instead of printing a
// sentence with nowhere to act on it. Only the possession proofs: a
// `POST /api/auth/reproof` with one of them stamps `mfaVerifiedAt`, a
// password stamps `reproofAt` only and would leave this gate shut.
const methods = (await recentProofMethods(sessionData.user)).filter(
(method) => method !== "password",
);
annotate({ meta: { step_up_methods: methods.join(",") } });
throw new StepUpRequiredError(
"auth.stepup.required",
"Recent second-factor verification required",
{ methods },
);
}
return { ...sessionData, authMethod: "cookie", mfaVerifiedAt: verifiedAt };
}
/**
* Conditional step-up for destructive account actions.
*
* Resolves the caller with the standard `requireAuth()` (cookie OR Bearer).
* For an account WITHOUT a confirmed second factor the caller passes straight
* through — a single-factor user is intentionally unaffected, so account
* deletion / data reset keeps its existing typed-confirmation-only contract.
* For an account WITH MFA active (`totpConfirmedAt` set) it additionally runs
* `requireFreshMfa`, which is cookie-only by construction: an MFA-enrolled
* account's Bearer transport carries no `mfaVerifiedAt` and therefore cannot
* satisfy step-up, surfacing `StepUpRequiredError` (401,
* `errorCode: "auth.stepup.required"`) so the UI launches a re-verification.
*
* Gating only the MFA-enrolled cohort keeps the boundary structural: a
* hijacked live cookie session for an MFA user cannot nuke the record without
* a fresh factor, while users who never opted into MFA are not forced through
* a flow they have no way to complete.
*/
export async function requireFreshMfaIfEnrolled(
maxAgeSeconds: number,
): Promise<AuthContext> {
const auth = await requireAuth();
if (await hasSecondFactorEnrolled(auth.user)) {
await requireFreshMfa(maxAgeSeconds);
}
return auth;
}
/**
* What an erasure route received: the caller, plus the hook that spends a
* Bearer elevation. See `MfaManagementContext.commitElevation` for the
* contract — call it immediately before the mutation, after every cheap
* refusal (a bad confirmation, the last-admin check) has passed, so a 422
* does not burn a proof the user then has to mint again.
*/
export type ErasureAuthContext = AuthContext & {
commitElevation: () => Promise<void>;
};
/**
* The sibling of `requireFreshMfaIfEnrolled` for the two erasure routes —
* account deletion and the record wipe — and only those.
*
* WHY IT EXISTS. App Store guideline 5.1.1(v) requires that an account created
* in the app can be deleted from the app. `requireFreshMfaIfEnrolled` gates an
* MFA-enrolled account on `requireFreshMfa`, which is cookie-only by
* construction, so a native-app user with a second factor could not delete
* their account from the app at all: the Bearer transport had no way to
* present a fresh factor and the route answered 401 "Not authenticated" to a
* perfectly valid token. This helper adds the Bearer arm without touching
* `requireFreshMfa`, which stays cookie-only.
*
* THE THREE ARMS.
*
* No second factor enrolled — pass through on either transport, exactly as
* the sibling does. A user who never enrolled has no ceremony to complete.
*
* Cookie + enrolled — `requireFreshMfa`, unchanged: `Session.mfaVerifiedAt`
* within the window. A browser session cannot tell the two helpers apart.
*
* Bearer + enrolled — a step-up elevation in the `X-Step-Up` header, minted
* by `POST /api/auth/step-up` against a re-proved factor, validated by the
* same code the MFA-management routes use and with `freshFactor` pinned ON:
* a `totp`, `webauthn`, or `passkey` proof passes; a password proof is
* refused with the same generic 401, because a password login has never
* satisfied step-up on the web and must not start here. The elevation is
* token-bound, single-use, and five minutes wide — the cookie window.
*
* WHAT IT DOES NOT DO. Scope is `requireAuth()`'s fail-closed default, so a
* narrow token is refused 403 before the header is read. A recovery code is
* not accepted on Bearer — the mint does not take one, and `FRESH_FACTOR_METHODS`
* says why; an account that has lost its authenticator erases itself on the
* web, where `/api/auth/mfa/verify` accepts the code and stamps the session.
* And the gate takes no factor in the BODY: there is one mint surface and one
* redemption path, which is what `step-up-elevation-guard.test.ts` freezes.
*/
export async function requireFreshMfaOrElevationIfEnrolled(
maxAgeSeconds: number,
): Promise<ErasureAuthContext> {
const auth = await requireAuth();
const noop = async () => {};
if (!(await hasSecondFactorEnrolled(auth.user))) {
return { ...auth, commitElevation: noop };
}
if (auth.authMethod === "cookie") {
await requireFreshMfa(maxAgeSeconds);
return { ...auth, commitElevation: noop };
}
// On the Bearer path `requireAuth` puts the resolved `ApiToken` row id in
// `session.id` — the binding the elevation was minted against.
const commitElevation = await resolveBearerElevation(
{ user: auth.user, apiTokenId: auth.session.id },
{ freshFactor: true, proofSource: "second-factor" },
);
return { ...auth, commitElevation };
}
+135
View File
@@ -0,0 +1,135 @@
import type { SessionUser } from "@/lib/auth/session-user";
import { getSession } from "@/lib/auth/session";
import { hasSecondFactorEnrolled } from "@/lib/auth/second-factor";
import { requireBearerAuth } from "./caller";
import { requireCookieAuth } from "./cookie";
import { resolveBearerElevation } from "./elevation";
import {
MFA_STEP_UP_MAX_AGE_SECONDS,
type FreshFactorProofSource,
} from "./fresh-factor";
import { requireFreshMfa } from "./fresh-mfa";
/**
* What an MFA-management route received, with the transport made explicit.
*
* The two arms carry DIFFERENT fields on purpose. A cookie caller has a session
* row and a Bearer caller does not, so `session` exists only on the cookie arm
* and the compiler refuses to read it on the other. This is the fix for a real
* defect: the MFA-disable route passed `session.id` to `destroyOtherSessions`,
* which on the Bearer path was an ApiToken id — matching no session row, so the
* "keep the current one" exclusion excluded nothing and the caller revoked its
* own device login. A comment would not have caught that; a type does.
*/
export type MfaManagementContext = {
user: SessionUser;
/**
* Spend the elevation. Call it immediately BEFORE the mutation, once every
* cheap validation has passed — a 429, a 422, or a wrong factor code must not
* burn a proof the user then has to mint again against a 5-per-15-minute
* ceiling.
*
* A no-op on the cookie arm (the session stamp is not consumable). On the
* Bearer arm it is the atomic single-use claim, and it THROWS
* `StepUpRequiredError` if the claim is lost — so a concurrent redemption
* still yields exactly one winner even though validation happened earlier.
*/
commitElevation: () => Promise<void>;
} & (
| { transport: "cookie"; session: { id: string; expiresAt: Date } }
| { transport: "bearer"; apiTokenId: string; accessTokenHash: string }
);
/**
* The single gate for second-factor management.
*
* Every MFA-management MUTATION goes through here and nothing else does. The set
* is frozen by `src/__tests__/step-up-elevation-guard.test.ts`, so a future
* route cannot quietly join it: widening the reach of an elevation has to be a
* visible edit to that allowlist.
*
* Two accepted proofs, and they are equals rather than a primary and a fallback:
*
* COOKIE — unchanged, byte for byte. A cookie session delegates to
* `requireCookieAuth` / `requireFreshMfa` exactly as before this function
* existed. The web flow cannot regress here because there is no new code on
* its path; the elevation branch is only reached when there is no session at
* all.
*
* BEARER + ELEVATION — a token that resolves cleanly AND presents a valid,
* unconsumed elevation minted for that same token against a re-proved factor
* of sufficient strength. The token alone is never enough.
*
* FRESH FACTOR IS ABOUT WHICH FACTOR, NOT JUST HOW RECENT. On the cookie path
* `requireFreshMfa` reads `Session.mfaVerifiedAt`, and only a completed second
* factor or a primary passkey login ever writes it — a password login does not.
* The Bearer arm holds the identical line through `FRESH_FACTOR_METHODS`: a
* password-proved elevation reaches what a plain cookie session reaches and
* stops there. Without that rule, a stolen token plus the account password could
* rotate the recovery codes and spend one to disable the second factor.
*
* `requireAdmin` is untouched and stays cookie-only. An elevation cannot reach
* it — not because a check refuses one, but because `requireAdmin` resolves
* through `getSession()` and never consults this function or the header.
*
* @param options.freshFactor mirrors the cookie path's `requireFreshMfa`. Set by
* the destructive routes (disable, recovery-code rotation, security-key
* removal, passkey removal).
* @param options.proofSource which credentials count as "can prove a factor"
* when deciding whether the gate is reachable. Defaults to the second-factor
* set. Passkey removal passes `"any-possession"` because a primary passkey IS
* the proof there — see {@link FreshFactorProofSource}. It changes only the
* reachability pre-check; the gate itself is identical either way.
* @param options.freshFactorIfEnrolled the Bearer arm of ADDING a factor
* (TOTP setup, security-key registration). On an account that already has a
* second factor, the elevation must come from a second-factor or passkey
* proof, the rule `checkCookieEnrollmentProof` holds on the cookie arm; on
* one without, a password-proved elevation is still enough. The cookie arm
* is not changed by it: those routes run their own enrollment proof there.
*/
export async function requireMfaManagementAuth(
options: {
freshFactor?: boolean;
freshFactorIfEnrolled?: boolean;
proofSource?: FreshFactorProofSource;
} = {},
): Promise<MfaManagementContext> {
const freshFactor = options.freshFactor === true;
const proofSource = options.proofSource ?? "second-factor";
// Cookie first, and via the original helpers — the web path runs the same
// code it always did.
const sessionData = await getSession();
if (sessionData) {
const resolved = freshFactor
? await requireFreshMfa(MFA_STEP_UP_MAX_AGE_SECONDS, proofSource)
: await requireCookieAuth();
return {
transport: "cookie",
user: resolved.user,
session: resolved.session,
commitElevation: async () => {},
};
}
// Bearer path. Resolution first: an unknown, revoked, expired, or narrow-scope
// token is refused here and never gets as far as presenting an elevation.
const auth = await requireBearerAuth();
const bearerFreshFactor =
freshFactor ||
(options.freshFactorIfEnrolled === true &&
(await hasSecondFactorEnrolled(auth.user)));
const commitElevation = await resolveBearerElevation(
{ user: auth.user, apiTokenId: auth.apiTokenId },
{ freshFactor: bearerFreshFactor, proofSource },
);
return {
transport: "bearer",
user: auth.user,
apiTokenId: auth.apiTokenId,
accessTokenHash: auth.accessTokenHash,
commitElevation,
};
}
+126
View File
@@ -0,0 +1,126 @@
import { prisma } from "@/lib/db";
import type { SessionUser } from "@/lib/auth/session-user";
import { annotate } from "@/lib/logging/context";
import {
hasSecondFactorEnrolled,
recentProofMethods,
} from "@/lib/auth/second-factor";
import { REPROOF_REQUIRED_CODE, StepUpRequiredError } from "@/lib/api-errors";
import { requireAuth } from "./caller";
import { resolveBearerElevation } from "./elevation";
import { MFA_STEP_UP_MAX_AGE_SECONDS } from "./fresh-factor";
import type { ErasureAuthContext } from "./fresh-mfa";
/**
* How the recent-proof gate treats a Bearer caller.
*
* `elevation` — the Bearer twin of the cookie rule: an `X-Step-Up` elevation
* minted by `POST /api/auth/step-up`. On an account with a second factor it
* must come from a second-factor proof; without one, a password-proved
* elevation is enough. For routes no shipped client calls on Bearer.
*
* `elevation-if-enrolled` — the erasure routes' rule
* (`requireFreshMfaOrElevationIfEnrolled`): an account with a second factor
* presents a second-factor elevation, one without passes on the token. For a
* route the shipped app calls, where the second-factor arm was already
* refused before and the other arm must keep working.
*
* `token` — the token is the proof, as before. Only for routes the shipped
* app calls without an elevation, where a refusal would sign the app out (it
* reads a 401 outside its known paths as a dead session). Each one is named
* in the iOS note and in `recent-proof-surface-guard.test.ts`, so tightening
* it later is a visible edit.
*/
export type RecentProofBearerRule =
"elevation" | "elevation-if-enrolled" | "token";
/**
* The fresh-proof gate in front of the actions that hand the record, or a
* standing credential to it, to somebody: exporting the whole record, making a
* clinician share link, minting a token, and the admin backup, restore, wipe
* and reset actions. A live session is not enough for those, because whoever
* holds a stolen session would otherwise walk off with the record or leave a
* credential behind that outlives the session.
*
* Cookie session, account WITH a second factor: `Session.mfaVerifiedAt`
* within five minutes — exactly `requireFreshMfa`. Signing in completes the
* factor; later, `POST /api/auth/reproof` with a TOTP code, security key or
* passkey stamps it again.
*
* Cookie session, account WITHOUT a second factor: any of the session's
* creation (a sign-in), `mfaVerifiedAt` (a passkey sign-in or re-proof) or
* `reproofAt` (a password re-proof) within five minutes. Such an account
* re-enters its password, or uses a passkey.
*
* The refusal is 401 `auth.reproof.required` with `meta.methods`, the proofs
* this account can give; the web opens the re-proof dialog on it and retries.
* An empty list means the account holds nothing to re-prove in place (an
* SSO-only account), and signing in again is the way through.
*
* Returns the caller plus `commitElevation`, which spends a Bearer elevation
* and is a no-op otherwise. Call it right before acting.
*/
export async function requireRecentProof(options: {
bearer: RecentProofBearerRule;
}): Promise<ErasureAuthContext> {
const auth = await requireAuth();
const noop = async () => {};
if (auth.authMethod === "cookie") {
await assertRecentCookieProof(auth.user, auth.session.id);
return { ...auth, commitElevation: noop };
}
const enrolled = await hasSecondFactorEnrolled(auth.user);
if (options.bearer === "token") {
annotate({ meta: { recent_proof: "bearer_token" } });
return { ...auth, commitElevation: noop };
}
if (options.bearer === "elevation-if-enrolled" && !enrolled) {
annotate({ meta: { recent_proof: "bearer_token" } });
return { ...auth, commitElevation: noop };
}
const commitElevation = await resolveBearerElevation(
{ user: auth.user, apiTokenId: auth.session.id },
{ freshFactor: enrolled, proofSource: "second-factor" },
);
return { ...auth, commitElevation };
}
/**
* The cookie arm of {@link requireRecentProof}, for routes that resolve the
* caller themselves (the admin routes, which must stay on `requireAdmin`).
*/
export async function assertRecentCookieProof(
user: SessionUser,
sessionId: string,
): Promise<void> {
const enrolled = await hasSecondFactorEnrolled(user);
const row = await prisma.session.findUnique({
where: { id: sessionId },
select: { mfaVerifiedAt: true, createdAt: true, reproofAt: true },
});
const now = Date.now();
const fresh = (d: Date | null | undefined) =>
d != null && now - d.getTime() <= MFA_STEP_UP_MAX_AGE_SECONDS * 1000;
const satisfied = enrolled
? fresh(row?.mfaVerifiedAt)
: fresh(row?.mfaVerifiedAt) ||
fresh(row?.createdAt) ||
fresh(row?.reproofAt);
if (satisfied) {
annotate({ meta: { recent_proof: "session" } });
return;
}
const methods = await recentProofMethods(user, enrolled);
annotate({
action: { name: "auth.reproof.required" },
meta: { second_factor: enrolled, methods: methods.join(",") },
});
throw new StepUpRequiredError(
REPROOF_REQUIRED_CODE,
"Confirm it is you to continue",
{ methods },
);
}
+390
View File
@@ -0,0 +1,390 @@
import type { AccountGrant } from "@/generated/prisma/client";
import { prisma } from "@/lib/db";
import { SESSION_USER_SELECT, type SessionUser } from "@/lib/auth/session-user";
import { annotate, getEvent } from "@/lib/logging/context";
import { recordDelegatedAccess } from "@/lib/auth/audit";
import {
readSelectorHeader,
selectorNamesAnAccount,
type ActingCarrier,
} from "@/lib/auth/acting-carrier";
import { meterAccountWrite } from "@/lib/auth/write-meter";
import {
findActiveGrant,
grantAllows,
grantCoversDomain,
touchGrantUsage,
type GrantNeed,
} from "@/lib/sharing/grants";
import type { ShareScope } from "@/lib/sharing/scope";
import { assertRecordSessionFence } from "@/lib/sharing/record-session-fence";
import {
SharingAccessDeniedError,
SharingNotPermittedError,
} from "@/lib/api-errors";
import {
auditRefusal,
readActingCarrier,
refuseUndeclaredMode,
} from "./acting";
import { authenticateCaller } from "./caller";
import {
READ_HTTP_METHODS,
isScopedCredential,
type AuthContext,
} from "./context";
/**
* An actor surface: this route always serves the CALLER's own rows.
*
* It works under a switch. That is the whole reason the mode exists: the
* switcher itself, the banner, and the "which records may I open" list all have
* to keep answering while the browser is acting as someone else, and every one
* of them is about the delegate. So the session carrier is read and
* deliberately ignored — no query, because there is nothing the answer could
* change.
*
* A selector HEADER is refused, loudly. An actor surface is DEFINED as serving
* the caller's own rows, so a client that attaches a selector to one has a bug,
* and the bug is invisible until somebody files a support ticket about data
* that looks wrong. Ignoring the header would serve exactly the right response
* to exactly the wrong expectation.
*/
export async function requireActorAuth(): Promise<AuthContext> {
const auth = await authenticateCaller();
const header = await readSelectorHeader();
if (header !== null) {
annotate({ meta: { sharing_refusal: "actor_surface" } });
auditRefusal(auth, { kind: "header", accountId: header }, "actor_surface");
throw new SharingNotPermittedError();
}
await meterAccountWrite(auth.user.id);
return auth;
}
/**
* A request resolved against a record that may not be the caller's own.
*
* `user` is the account whose rows the handler must read and write — so an
* existing `where: { userId: user.id }` is correct without being touched, which
* is what keeps a route migration a one-line change instead of an audit.
* `actor` is who is actually here. They are the same object when no switch is
* active.
*/
export interface RecordAuthContext extends AuthContext {
/** The authenticated caller. Equals `user` when the caller acts as themselves. */
readonly actor: SessionUser;
/** The grant being exercised, or null when the caller acts as themselves. */
readonly grantId: string | null;
}
/** What a delegable route may additionally declare about the credentials it takes. */
export interface RecordAuthOptions {
/**
* A Bearer scope this route accepts in place of the cookie-equivalent
* default. Naming one is a WIDENING — it admits a credential class the route
* refused before — and is frozen by `bearer-scope-enforcement-guard.test.ts`
* exactly like a `requireAuth` scope, so it lands in a reviewed diff.
*
* What the option does NOT do is relax anything below it. A credential
* admitted this way is single-purpose: it reaches this route on its OWN
* record and is refused the moment the request names another, before any
* grant is read. The `need` and `domain` checks run unchanged for everyone
* else.
*/
readonly scope?: string;
/**
* This route answers a POST without changing anything: the body
* carries a query that must not stand in a URL (the record search, whose
* text is health data a proxy's access log would otherwise keep). Under a
* route declaring `"read"`, a POST is then read at the grant's read level
* instead of being escalated to a write.
*
* Like `scope`, naming it is a WIDENING and is frozen by
* `read-over-post-guard.test.ts`, so it lands in a reviewed diff. It does
* nothing for any other method, and nothing for a route declaring a need
* above `"read"`.
*/
readonly readOverPost?: true;
/**
* This route meters its writes with a dedicated bucket instead of the shared
* per-account one (`meterAccountWrite`). Frozen per route, with the reason,
* by `write-rate-limit-guard.test.ts`, which also requires the route to call
* its own limiter.
*/
readonly writeBucket?: "own";
}
/**
* A delegable surface: this route may act on a shared record.
*
* Calling it is a DECLARATION, reviewed and frozen by a structural guard, that
* the route reads or writes health data and nothing else — no credential, no
* integration, no notification channel, no grant management, nothing that would
* let a delegate extend their own reach. The declaration is the security
* property; this function only enforces what was declared.
*
* @param need what the route does to the record. `"read"` still refuses a
* non-safe HTTP method under a read-only grant: the declaration and the
* method must BOTH be satisfiable, so a delegable GET handler that grows a
* POST export cannot quietly inherit the read grant's permission. An unknown
* method (no event context) counts as a write and is refused, the same
* fail-closed posture as the MCP audience guard in `caller.ts`. A route declaring
* `"manage"` refuses everything below it regardless of method: the method
* can only escalate what the declaration asked for, never satisfy it.
* @param domain v1.37.0 — which section of the record the route touches, or
* `"record"` when it reads across sections. Required, and the requirement is
* the fail-closed lever: a delegable route without a classification does not
* typecheck, so the set of routes carrying one cannot fall behind the set of
* routes that are delegable. The value is frozen per module by
* `src/__tests__/sharing-surface-guard.test.ts` and reviewed against the
* design's clustering table; this function only enforces what was declared.
* @param options v1.38.x — optional extra declarations. Today that is `scope`,
* naming a narrow Bearer this route admits alongside cookie sessions and
* cookie-equivalent tokens. A route that passes none keeps the fail-closed
* default and refuses every narrow token, which is what makes adding one a
* visible decision rather than an omission.
*/
export async function requireRecordAuth(
need: GrantNeed,
domain: ShareScope,
options?: RecordAuthOptions,
): Promise<RecordAuthContext> {
const auth = await authenticateCaller(options?.scope);
// Before any carrier is read, any grant is looked up, or any record
// row is touched: does this request still believe what its session believes?
//
// The atomicity that makes this a tautology rather than a race: the epoch the
// fence compares and the `actingAsUserId` the carrier below is built from are
// BOTH projected off the one session row `authenticateCaller()` already
// loaded. The scope this handler serves under and the epoch it validated are
// therefore the same fact read at the same instant, not two reads a commit
// can land between. Do not add a second session read here to "refresh" it —
// that would reintroduce exactly the window this ordering removes.
//
// `authenticateCaller` necessarily runs first because it supplies the row the
// fence reads, so the invariant is "before the carrier", not "before the
// first database await".
await assertRecordSessionFence(auth);
// The shared write ceiling, charged to the ACTING account before any grant
// is read, so a refused write counts like an admitted one — see
// `meterAccountWrite`.
await meterAccountWrite(auth.user.id, {
readOverPost: options?.readOverPost,
writeBucket: options?.writeBucket,
});
const carrier = await readActingCarrier(auth);
// A narrow, single-purpose Bearer never acts on another record.
//
// Its holder mints it themselves, for one job, and pastes it into something
// that is not this app — a scale bridge, a home-automation rule. Admitting it
// under a selector would exercise somebody else's grant through a credential
// nobody reviewed for that purpose, and the blast radius of the paste would
// stop being "my own record" without anyone deciding it should.
//
// Placed above the `none` arm and below the carrier read, which is the only
// position that is both correct and cheap: no grant is looked up on the way
// to the refusal, and a scoped credential on its own record still falls
// through to the untouched `none` path below. A `["*"]` token and a cookie
// session read `bearerScope: null` here and keep exactly the delegation
// behaviour they had.
if (carrier.kind !== "none" && isScopedCredential(auth)) {
throw refuseUndeclaredMode(auth, carrier, "narrow_scope_selector");
}
if (carrier.kind === "none") {
// Do no harm: without a carrier this is byte-for-byte the pre-v1.36.0
// request, resolved by the same `authenticateCaller` every other mode uses.
getEvent()?.setProviderWorkAuthority({
origin: "owner",
recordUserId: auth.user.id,
actorUserId: auth.user.id,
grantId: null,
});
return { ...auth, actor: auth.user, grantId: null };
}
if (carrier.kind === "misplaced-header") {
// The route DID declare a mode; the client sent the selector over the
// cookie transport, where the carrier is the session row.
throw refuseUndeclaredMode(auth, carrier, "misplaced_selector");
}
const method = (getEvent()?.getHttpMethod() ?? "").toUpperCase();
const readsOnly =
READ_HTTP_METHODS.has(method) ||
(options?.readOverPost === true && method === "POST");
const effectiveNeed: GrantNeed =
need !== "read" || !readsOnly ? escalate(need) : "read";
return resolveSwitchedRecord(auth, carrier, (grant) => {
if (!grantAllows(grant, effectiveNeed)) return "insufficient_access";
// Level first, then scope, and the order is visible on the wire in exactly
// one way: not at all. Both refusals are the same error with the same
// bytes, and only the audit reason differs — so the ordering is a choice
// about what the operator's trail says happened, not about what the caller
// learns. It says the bigger thing: a delegate who was never given this
// level is a different story from one whose sections do not reach here.
if (!grantCoversDomain(grant, domain)) return "out_of_scope";
return null;
});
}
/**
* The need a non-safe method implies, for a route that declared `need`.
*
* A PUT on a route declaring `"read"` needs a write grant, which is what this
* has always done. A PUT on a route declaring `"manage"` needs a MANAGE grant
* and must not be reduced to a write — so the escalation raises the floor to
* `"write"` and never lowers a declaration that already sits above it.
*/
function escalate(need: GrantNeed): GrantNeed {
return need === "manage" ? "manage" : "write";
}
/**
* A guardian surface: this route administers a managed profile.
*
* The other declaration, and a separate function rather than a flag on the one
* above, for the reason `requireActorAuth` is also separate: the guard freezes
* each declaration as its own list, so a route moving between them is a diff a
* human reviews rather than an argument about a parameter.
*
* What it admits is narrower than it looks. An active MANAGE grant is
* necessary and NOT sufficient — the record must also carry the managed-profile
* marker. That second condition is the identity fence, and it is the line
* between "manage my data" and "own my account": an adult who granted
* management of their own record reaches none of this, at any level, by any
* argument, because their record has no marker and never will while they hold
* it. A managed profile has no self to reserve these surfaces for, so its
* guardian holds them.
*
* The fence is gated on the marker rather than on the grant precisely so that
* no future change to what MANAGE means can reach through it. Widening MANAGE
* would widen `requireRecordAuth`; it would not touch this function.
*/
export async function requireGuardianAuth(): Promise<RecordAuthContext> {
const auth = await authenticateCaller();
// Same placement and the same reason as `requireRecordAuth` above: the
// guardian surfaces administer a managed profile, so a request arriving under
// a context that has since moved must be refused before the marker is read,
// not after.
await assertRecordSessionFence(auth);
await meterAccountWrite(auth.user.id);
const carrier = await readActingCarrier(auth);
if (carrier.kind === "none") {
// The owner of an ordinary record, reaching their own settings. Same
// do-no-harm posture as the record resolver: without a carrier this is the
// request it always was.
return { ...auth, actor: auth.user, grantId: null };
}
if (carrier.kind === "misplaced-header") {
throw refuseUndeclaredMode(auth, carrier, "misplaced_selector");
}
return resolveSwitchedRecord(auth, carrier, (grant, owner) => {
if (!grantAllows(grant, "manage")) return "insufficient_access";
if (owner.managedProfileAt === null) return "guardian_only";
return null;
});
}
/**
* The shared body of both record resolvers: turn a selector into an owner, or
* refuse.
*
* Everything either resolver does with a carrier lives here except the
* admission rule itself, which arrives as `admit` — a function of the grant
* and the owner returning an audit reason to refuse with, or null to proceed.
* The split is where it is because the two resolvers differ in exactly that
* one decision and in nothing else, and two copies of the grant lookup, the
* refusal shape, the usage stamp and the owner's access row would be two
* copies to keep in step.
*
* The owner row is loaded BEFORE the admission runs, which is a change from
* the first resolver's ordering and a deliberate one: the guardian rule is a fact about
* the owner, so it cannot be decided before the owner is known. Nothing about
* the refusal moved — every arm below is the same error with the same bytes,
* and an admission that refuses after the load costs one query it does not use
* and tells the caller nothing extra.
*/
async function resolveSwitchedRecord(
auth: AuthContext,
carrier: Extract<ActingCarrier, { accountId: string }>,
admit: (grant: AccountGrant, owner: SessionUser) => string | null,
): Promise<RecordAuthContext> {
/** Every refusal below is this one error, with the reason kept off the wire. */
const denied = (reason: string): SharingAccessDeniedError => {
annotate({ meta: { sharing_refusal: reason } });
auditRefusal(auth, carrier, reason);
return new SharingAccessDeniedError();
};
if (!selectorNamesAnAccount(carrier.accountId)) {
throw denied("malformed_selector");
}
// Loaded here, on this request, every request. Not memoised on the session,
// not cached in the process, not carried on the token: a revocation has to
// land on the delegate's NEXT request, not on their next login. That is the
// one property the owner is actually promised when they press revoke.
//
// Note what is NOT looked up: the account named by the carrier. An account
// that does not exist and an account that granted nothing produce the same
// empty row from the same query, which is what makes the two refusals
// identical in bytes and in timing rather than identical by careful wording.
const grant = await findActiveGrant({
grantorId: carrier.accountId,
granteeId: auth.user.id,
});
if (!grant) throw denied("no_active_grant");
const owner = await prisma.user.findUnique({
where: { id: grant.grantorId },
select: SESSION_USER_SELECT,
});
// Unreachable while the FK cascade holds — a grant naming a deleted account
// is deleted with it. Fail closed anyway: an authorization we cannot resolve
// to a person is not one to act on.
if (!owner) throw denied("owner_missing");
const refusal = admit(grant, owner);
if (refusal !== null) throw denied(refusal);
getEvent()?.setActingAs(owner.id);
// And whether this request may spend the owner's provider budget.
// MANAGE opens the generated reads; it does not open the generation behind
// them, because the owner would pay for and consent to an egress they did
// not cause. A managed profile is the exception and the reason the marker is
// read here rather than the grant: it has no self to protect from its own
// guardian. Stamped where the owner row is already loaded, so no generator
// has to be told; see `src/lib/sharing/delegated-generation.ts`.
if (owner.id !== auth.user.id && owner.managedProfileAt === null) {
getEvent()?.setDelegatedGenerationSuppressed();
}
getEvent()?.setProviderWorkAuthority({
origin: owner.managedProfileAt === null ? "delegate" : "guardian",
recordUserId: owner.id,
actorUserId: auth.user.id,
grantId: grant.id,
});
// Fire-and-forget, the `ApiToken.lastUsedAt` posture: the read must not wait
// on the bookkeeping, and the bookkeeping failing must not fail the read.
void touchGrantUsage(grant.id);
// The owner's copy of the same fact, and the one they can read: a day-
// coalesced row on their own record saying who opened it. It lands here
// rather than in the handlers because a route cannot forget what it never
// had to remember — every delegated request in the product passes through
// this line, and only requests that got past the grant check reach it.
void recordDelegatedAccess(owner.id, auth.user.id);
return {
session: auth.session,
user: owner,
authMethod: auth.authMethod,
actor: auth.user,
grantId: grant.id,
};
}
+1 -1
View File
@@ -18,7 +18,7 @@ import { prisma } from "@/lib/db";
* a step-up at all. Counting a passkey here would silently pull every
* passkey-holding account into a gate those routes have never applied to them —
* a behaviour change to five destructive actions, made in passing, for the
* benefit of a sixth. `canProveFreshFactor` in `api-handler.ts` is where the wider question
* benefit of a sixth. `canProveFreshFactor` in `auth/guards/fresh-factor.ts` is where the wider question
* lives.
*
* Since v1.43.3 a passkey DOES count as a second factor where the gate is
+1 -1
View File
@@ -446,7 +446,7 @@ export async function getSession(): Promise<{
// already in hand and re-reading it per request would be waste.
//
// Read this in exactly one place: the acting-account resolver in
// `src/lib/api-handler.ts`. It is a selector and not a decision — the
// `src/lib/auth/guards/`. It is a selector and not a decision — the
// resolver still has to find a live grant for the pair before anything
// is substituted, and a value stranded here by a grant that has since
// ended confers nothing.
+1 -1
View File
@@ -7,7 +7,7 @@
* PATCH and DELETE on an `[id]` among them. A positive list of routes that
* remember to call it can only fall behind the routes that exist, so the
* ceiling now sits on the path every authenticated write already takes: the
* identity resolvers in `src/lib/api-handler.ts` call {@link meterAccountWrite}
* identity resolvers in `src/lib/auth/guards/` call {@link meterAccountWrite}
* once the caller is known, and it charges the bucket for any request whose
* method writes.
*
+1 -1
View File
@@ -8,7 +8,7 @@
* That is the whole design of this file and it is worth stating plainly,
* because the tempting alternative is one line shorter: publish the grant rows
* and let the client work out what they mean. Then two programs decide one
* person's access — the resolver in `src/lib/api-handler.ts`, and whichever
* person's access — the resolver in `src/lib/auth/guards/record.ts`, and whichever
* client is being read today — and they answer differently the first time an
* expiry, a revocation or a second access level appears. The client renders
* `canSwitch` and `canWrite`; it never computes them, and there is nothing in
+1 -1
View File
@@ -6,7 +6,7 @@
* session at a record, and the end of a grant points every affected session
* back at its own. Both live here rather than at their call sites so the
* carrier has one writer, the same way it has one reader (the resolver in
* `src/lib/api-handler.ts`). The structural guard in
* `src/lib/auth/guards/acting.ts`). The structural guard in
* `src/__tests__/acting-account-boundary-guard.test.ts` holds that shape: any
* other file that so much as names the column fails it.
*
+1 -1
View File
@@ -198,7 +198,7 @@ export async function assertRecordSessionFence(
// two-refusals note in the contract module.
//
// No audit row, and that follows the rule already written for the session
// carrier in `api-handler.ts`: a HEADER refusal is a per-request assertion by
// carrier in `auth/guards/acting.ts`: a HEADER refusal is a per-request assertion by
// a client and earns a durable record, a SESSION-state refusal is ambient
// browser state and would bury the rows that matter under noise from the
// feature working as designed. This arm is the second kind — every