mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 15:23:29 +00:00
Merge branch 'wave/v123-mfa-core' into release/v1.23.0
This commit is contained in:
commit
6d053c3667
28 files changed
+2829
-91
No files matched your search
@@ -0,0 +1,113 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
|
||||
// Mirrors require-auth-bearer.test.ts mocking so the api-handler module loads
|
||||
// without a live DB / request scope.
|
||||
vi.mock("@/lib/db", () => ({
|
||||
prisma: {
|
||||
session: { findUnique: vi.fn() },
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/auth/session", () => ({
|
||||
getSession: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/auth/hmac", () => ({ hashToken: vi.fn() }));
|
||||
vi.mock("@/lib/auth/audit", () => ({
|
||||
auditLog: vi.fn().mockResolvedValue(undefined),
|
||||
}));
|
||||
vi.mock("@/lib/logging/transports", () => ({ emitIfSampled: vi.fn() }));
|
||||
|
||||
const headersGet = vi.fn<(name: string) => string | null>();
|
||||
vi.mock("next/headers", () => ({
|
||||
headers: vi.fn(async () => ({ get: headersGet })),
|
||||
cookies: vi.fn(async () => ({
|
||||
get: () => undefined,
|
||||
set: () => {},
|
||||
delete: () => {},
|
||||
})),
|
||||
}));
|
||||
|
||||
import {
|
||||
requireFreshMfa,
|
||||
StepUpRequiredError,
|
||||
HttpError,
|
||||
MFA_STEP_UP_MAX_AGE_SECONDS,
|
||||
} from "../api-handler";
|
||||
import { getSession } from "@/lib/auth/session";
|
||||
import { prisma } from "@/lib/db";
|
||||
|
||||
const MFA_USER = {
|
||||
id: "user-1",
|
||||
role: "USER" as const,
|
||||
username: "u",
|
||||
totpConfirmedAt: new Date("2020-01-01"),
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
});
|
||||
|
||||
function mockSession(user: unknown) {
|
||||
vi.mocked(getSession).mockResolvedValue({
|
||||
session: { id: "sess-1", expiresAt: new Date(Date.now() + 1e6) },
|
||||
user,
|
||||
} as never);
|
||||
}
|
||||
|
||||
describe("requireFreshMfa", () => {
|
||||
it("passes for a cookie session verified within the window", async () => {
|
||||
mockSession(MFA_USER);
|
||||
vi.mocked(prisma.session.findUnique).mockResolvedValue({
|
||||
mfaVerifiedAt: new Date(Date.now() - 60_000), // 1 min ago
|
||||
} as never);
|
||||
|
||||
const ctx = await requireFreshMfa(MFA_STEP_UP_MAX_AGE_SECONDS);
|
||||
expect(ctx.user.id).toBe("user-1");
|
||||
expect(ctx.mfaVerifiedAt).toBeInstanceOf(Date);
|
||||
});
|
||||
|
||||
it("rejects a stale verification (outside the window)", async () => {
|
||||
mockSession(MFA_USER);
|
||||
vi.mocked(prisma.session.findUnique).mockResolvedValue({
|
||||
mfaVerifiedAt: new Date(Date.now() - 10 * 60_000), // 10 min ago
|
||||
} as never);
|
||||
|
||||
await expect(requireFreshMfa(5 * 60)).rejects.toMatchObject({
|
||||
name: "StepUpRequiredError",
|
||||
errorCode: "auth.stepup.required",
|
||||
statusCode: 401,
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects an absent verification stamp", async () => {
|
||||
mockSession(MFA_USER);
|
||||
vi.mocked(prisma.session.findUnique).mockResolvedValue({
|
||||
mfaVerifiedAt: null,
|
||||
} as never);
|
||||
|
||||
await expect(requireFreshMfa(5 * 60)).rejects.toBeInstanceOf(
|
||||
StepUpRequiredError,
|
||||
);
|
||||
});
|
||||
|
||||
it("rejects a user without an active second factor", async () => {
|
||||
mockSession({ ...MFA_USER, totpConfirmedAt: null });
|
||||
await expect(requireFreshMfa(5 * 60)).rejects.toMatchObject({
|
||||
errorCode: "auth.stepup.mfa_not_enrolled",
|
||||
});
|
||||
// Never even reaches the session-row read.
|
||||
expect(prisma.session.findUnique).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("rejects when there is no cookie session — Bearer can never satisfy it", async () => {
|
||||
// getSession is cookie-only; a Bearer header is irrelevant and never read.
|
||||
headersGet.mockImplementation((n) =>
|
||||
n.toLowerCase() === "authorization" ? "Bearer hlk_xyz" : null,
|
||||
);
|
||||
vi.mocked(getSession).mockResolvedValue(null as never);
|
||||
|
||||
await expect(requireFreshMfa(5 * 60)).rejects.toBeInstanceOf(HttpError);
|
||||
expect(prisma.session.findUnique).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
@@ -191,6 +191,21 @@ export function apiHandler<T extends (...args: any[]) => Promise<Response>>(
|
||||
},
|
||||
{ status: 403 },
|
||||
);
|
||||
} else if (error instanceof StepUpRequiredError) {
|
||||
// v1.23 — step-up gate not satisfied. Same 401 + meta.errorCode
|
||||
// envelope shape as the assistant/consent gates so the client can
|
||||
// branch on the stable code and launch a re-verification flow.
|
||||
// Checked before the generic HttpError branch because
|
||||
// StepUpRequiredError extends it.
|
||||
evt.setError(error);
|
||||
response = NextResponse.json(
|
||||
{
|
||||
data: null,
|
||||
error: error.message,
|
||||
meta: { errorCode: error.errorCode },
|
||||
},
|
||||
{ status: error.statusCode },
|
||||
);
|
||||
} else if (error instanceof HttpError) {
|
||||
evt.setError(error);
|
||||
response = NextResponse.json(
|
||||
@@ -441,6 +456,107 @@ export async function requireAdmin(): Promise<AuthContext> {
|
||||
return sessionData;
|
||||
}
|
||||
|
||||
/**
|
||||
* v1.23 — 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");
|
||||
|
||||
const evt = getEvent();
|
||||
if (evt) {
|
||||
evt.setAuth({
|
||||
user_id: sessionData.user.id,
|
||||
user_role: sessionData.user.role,
|
||||
auth_method: "session",
|
||||
});
|
||||
}
|
||||
return sessionData;
|
||||
}
|
||||
|
||||
/**
|
||||
* Error thrown when a step-up gate is not satisfied. Carries `errorCode` so
|
||||
* the route can surface a stable machine code (`auth.stepup.required`) the
|
||||
* client branches on to launch a re-verification flow rather than parsing
|
||||
* prose.
|
||||
*/
|
||||
export class StepUpRequiredError extends HttpError {
|
||||
constructor(
|
||||
public errorCode: string = "auth.stepup.required",
|
||||
message = "Recent second-factor verification required",
|
||||
) {
|
||||
super(401, message);
|
||||
this.name = "StepUpRequiredError";
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 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;
|
||||
|
||||
export type FreshMfaContext = AuthContext & { mfaVerifiedAt: Date };
|
||||
|
||||
/**
|
||||
* v1.23 — step-up gate. Passes only for a COOKIE session whose
|
||||
* `Session.mfaVerifiedAt` is within `maxAgeSeconds` AND whose user has an
|
||||
* active second factor (`totpConfirmedAt`). 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.
|
||||
*/
|
||||
export async function requireFreshMfa(
|
||||
maxAgeSeconds: number,
|
||||
): Promise<FreshMfaContext> {
|
||||
const sessionData = await getSession();
|
||||
if (!sessionData) throw new HttpError(401, "Not authenticated");
|
||||
|
||||
const evt = getEvent();
|
||||
if (evt) {
|
||||
evt.setAuth({
|
||||
user_id: sessionData.user.id,
|
||||
user_role: sessionData.user.role,
|
||||
auth_method: "session",
|
||||
});
|
||||
}
|
||||
|
||||
// The user must actually have a second factor active. A single-factor
|
||||
// account cannot produce a fresh-MFA proof, so step-up-gated actions are
|
||||
// unreachable for it by design (the management UI gates enrolment first).
|
||||
if (!sessionData.user.totpConfirmedAt) {
|
||||
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) {
|
||||
throw new StepUpRequiredError();
|
||||
}
|
||||
|
||||
return { ...sessionData, mfaVerifiedAt: verifiedAt };
|
||||
}
|
||||
|
||||
/**
|
||||
* Report unhandled errors to GlitchTip (fire-and-forget).
|
||||
* Uses dynamic import to avoid circular dependencies and startup cost.
|
||||
|
||||
@@ -0,0 +1,125 @@
|
||||
/**
|
||||
* Shared "issue the authenticated response" tail used by both the password
|
||||
* login route and the `/api/auth/mfa/verify` route.
|
||||
*
|
||||
* Keeping one implementation guarantees the transport contract is identical
|
||||
* whether or not a second factor sat in the middle: a web caller gets a
|
||||
* session cookie, a cookie-less native caller gets the access + refresh
|
||||
* bundle, and a legacy `X-Client-Type: native` caller gets a plain access
|
||||
* token. The only behavioural difference the second factor introduces is the
|
||||
* `mfaVerifiedAt` stamp threaded onto the issued session (cookie path) so
|
||||
* step-up freshness can read it.
|
||||
*
|
||||
* Bearer-issuing branches do not carry an `mfaVerifiedAt` equivalent — the
|
||||
* step-up primitive (`requireFreshMfa`) is cookie-only by construction, the
|
||||
* same structural boundary as `requireAdmin`, so a token transport can never
|
||||
* satisfy step-up regardless.
|
||||
*/
|
||||
import type { NextRequest } from "next/server";
|
||||
import { apiSuccess } from "@/lib/api-response";
|
||||
import { auditLog } from "@/lib/auth/audit";
|
||||
import { createSession } from "@/lib/auth/session";
|
||||
import { issueApiToken, isNativeClientRequest } from "@/lib/auth/issue-token";
|
||||
import {
|
||||
resolveTokenPolicy,
|
||||
shouldIssueBearerToken,
|
||||
isCookielessNativeCaller,
|
||||
} from "@/lib/auth/native-client";
|
||||
import { issueAccessAndRefresh } from "@/lib/auth/refresh-token";
|
||||
import type { User } from "@/generated/prisma/client";
|
||||
|
||||
export interface FinishLoginParams {
|
||||
user: Pick<User, "id" | "username" | "onboardingCompletedAt">;
|
||||
request: NextRequest;
|
||||
ip: string;
|
||||
userAgent: string | null;
|
||||
/** Audit `source` discriminator, e.g. `"login.password"` / `"mfa.verify"`. */
|
||||
source: string;
|
||||
/**
|
||||
* When true the issued session is stamped `mfaVerifiedAt = now()` so
|
||||
* step-up gates treat it as freshly second-factor-verified. Only the
|
||||
* cookie path carries the stamp.
|
||||
*/
|
||||
mfaVerified?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mint the session/token for an already-authenticated user and return the
|
||||
* client response. Caller is responsible for the prior factor checks and for
|
||||
* its own `auth.login.*` / `auth.mfa.*` audit entries; this writes only the
|
||||
* token-issuance audit rows.
|
||||
*/
|
||||
export async function finishLogin(
|
||||
params: FinishLoginParams,
|
||||
): Promise<Response> {
|
||||
const { user, request, ip, userAgent, source, mfaVerified } = params;
|
||||
|
||||
if (
|
||||
shouldIssueBearerToken(request.headers) ||
|
||||
isNativeClientRequest(request.headers)
|
||||
) {
|
||||
const policy = resolveTokenPolicy(request.headers);
|
||||
const deviceId = request.headers.get("x-device-id");
|
||||
|
||||
// A 60-day refresh token is only ever delivered to a genuinely
|
||||
// cookie-less native caller — a browser spoofing `X-Client-Type: native`
|
||||
// falls through to the plain access-token path below.
|
||||
if (
|
||||
policy.refreshTokenDays !== null &&
|
||||
isCookielessNativeCaller(request.headers)
|
||||
) {
|
||||
const bundle = await issueAccessAndRefresh({
|
||||
userId: user.id,
|
||||
policy,
|
||||
deviceId,
|
||||
userAgent,
|
||||
ipAddress: ip,
|
||||
source,
|
||||
});
|
||||
await auditLog("auth.token.autoissue.native", {
|
||||
userId: user.id,
|
||||
ipAddress: ip,
|
||||
details: { source, policy: "native" },
|
||||
});
|
||||
return apiSuccess({
|
||||
user: { id: user.id, username: user.username },
|
||||
token: bundle.accessToken,
|
||||
tokenExpiresAt: bundle.accessTokenExpiresAt.toISOString(),
|
||||
refreshToken: bundle.refreshToken,
|
||||
refreshTokenExpiresAt: bundle.refreshTokenExpiresAt.toISOString(),
|
||||
});
|
||||
}
|
||||
|
||||
// Web policy with explicit X-Client-Type:native (legacy iOS auto-login).
|
||||
const issued = await issueApiToken({
|
||||
userId: user.id,
|
||||
name: `web auto-login ${new Date().toISOString()}`,
|
||||
permissions: ["*"],
|
||||
expiresInDays: policy.accessTokenDays,
|
||||
});
|
||||
await auditLog("auth.token.autoissue.native", {
|
||||
userId: user.id,
|
||||
ipAddress: ip,
|
||||
details: { tokenId: issued.tokenId, source, policy: "web" },
|
||||
});
|
||||
return apiSuccess({
|
||||
user: { id: user.id, username: user.username },
|
||||
token: issued.token,
|
||||
tokenExpiresAt: issued.expiresAt.toISOString(),
|
||||
});
|
||||
}
|
||||
|
||||
// Browser path — session cookie. `createSession` anchors the onboarding
|
||||
// cookie itself; thread the user's onboarding state through.
|
||||
await createSession(
|
||||
user.id,
|
||||
user.onboardingCompletedAt == null,
|
||||
ip,
|
||||
userAgent,
|
||||
mfaVerified ? new Date() : null,
|
||||
);
|
||||
|
||||
return apiSuccess({
|
||||
user: { id: user.id, username: user.username },
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,130 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
|
||||
vi.mock("@/lib/db", () => ({
|
||||
prisma: {
|
||||
mfaChallenge: {
|
||||
create: vi.fn(),
|
||||
findUnique: vi.fn(),
|
||||
update: vi.fn(),
|
||||
updateMany: vi.fn(),
|
||||
},
|
||||
},
|
||||
}));
|
||||
|
||||
// Stand-in for the real HMAC: deterministic but NOT containing the raw
|
||||
// ticket, so the "raw ticket is never persisted" assertion is meaningful.
|
||||
vi.mock("@/lib/auth/hmac", () => ({
|
||||
hashToken: vi.fn((t: string) => `H${t.length}`),
|
||||
}));
|
||||
|
||||
import {
|
||||
createMfaChallenge,
|
||||
loadActiveChallenge,
|
||||
recordChallengeFailure,
|
||||
claimChallenge,
|
||||
MFA_CHALLENGE_ATTEMPT_CAP,
|
||||
} from "../challenge";
|
||||
import { prisma } from "@/lib/db";
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
function activeRow(overrides: Record<string, unknown> = {}) {
|
||||
return {
|
||||
id: "ch-1",
|
||||
userId: "user-1",
|
||||
kind: "login",
|
||||
attempts: 0,
|
||||
expiresAt: new Date(Date.now() + 60_000),
|
||||
consumedAt: null,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("mfa challenge", () => {
|
||||
it("mints a ticket and stores only its hash", async () => {
|
||||
vi.mocked(prisma.mfaChallenge.create).mockResolvedValue({} as never);
|
||||
const { ticket } = await createMfaChallenge("user-1", "login");
|
||||
expect(typeof ticket).toBe("string");
|
||||
expect(ticket.length).toBeGreaterThan(20);
|
||||
const arg = vi.mocked(prisma.mfaChallenge.create).mock.calls[0][0];
|
||||
expect(arg.data.ticketHash).toBe(`H${ticket.length}`);
|
||||
// Raw ticket is never persisted.
|
||||
expect(JSON.stringify(arg)).not.toContain(ticket);
|
||||
});
|
||||
|
||||
it("loads an active challenge by hash", async () => {
|
||||
vi.mocked(prisma.mfaChallenge.findUnique).mockResolvedValue(
|
||||
activeRow() as never,
|
||||
);
|
||||
const res = await loadActiveChallenge("tkt");
|
||||
expect(res?.id).toBe("ch-1");
|
||||
expect(
|
||||
vi.mocked(prisma.mfaChallenge.findUnique).mock.calls[0][0],
|
||||
).toMatchObject({ where: { ticketHash: "H3" } });
|
||||
});
|
||||
|
||||
it("refuses a consumed ticket (single-use)", async () => {
|
||||
vi.mocked(prisma.mfaChallenge.findUnique).mockResolvedValue(
|
||||
activeRow({ consumedAt: new Date() }) as never,
|
||||
);
|
||||
expect(await loadActiveChallenge("tkt")).toBeNull();
|
||||
});
|
||||
|
||||
it("refuses an expired ticket (TTL)", async () => {
|
||||
vi.mocked(prisma.mfaChallenge.findUnique).mockResolvedValue(
|
||||
activeRow({ expiresAt: new Date(Date.now() - 1000) }) as never,
|
||||
);
|
||||
expect(await loadActiveChallenge("tkt")).toBeNull();
|
||||
});
|
||||
|
||||
it("refuses a ticket at the attempt cap", async () => {
|
||||
vi.mocked(prisma.mfaChallenge.findUnique).mockResolvedValue(
|
||||
activeRow({ attempts: MFA_CHALLENGE_ATTEMPT_CAP }) as never,
|
||||
);
|
||||
expect(await loadActiveChallenge("tkt")).toBeNull();
|
||||
});
|
||||
|
||||
it("refuses an unknown ticket", async () => {
|
||||
vi.mocked(prisma.mfaChallenge.findUnique).mockResolvedValue(null as never);
|
||||
expect(await loadActiveChallenge("nope")).toBeNull();
|
||||
});
|
||||
|
||||
it("burns the ticket when the attempt cap is reached", async () => {
|
||||
vi.mocked(prisma.mfaChallenge.update).mockResolvedValue({
|
||||
attempts: MFA_CHALLENGE_ATTEMPT_CAP,
|
||||
} as never);
|
||||
vi.mocked(prisma.mfaChallenge.updateMany).mockResolvedValue({
|
||||
count: 1,
|
||||
} as never);
|
||||
const res = await recordChallengeFailure("ch-1");
|
||||
expect(res.exhausted).toBe(true);
|
||||
// Burn sets consumedAt only while still null (claim-once guard).
|
||||
expect(prisma.mfaChallenge.updateMany).toHaveBeenCalledWith({
|
||||
where: { id: "ch-1", consumedAt: null },
|
||||
data: { consumedAt: expect.any(Date) },
|
||||
});
|
||||
});
|
||||
|
||||
it("does not burn below the attempt cap", async () => {
|
||||
vi.mocked(prisma.mfaChallenge.update).mockResolvedValue({
|
||||
attempts: 1,
|
||||
} as never);
|
||||
const res = await recordChallengeFailure("ch-1");
|
||||
expect(res.exhausted).toBe(false);
|
||||
expect(prisma.mfaChallenge.updateMany).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("claim-once: only the winning update returns true", async () => {
|
||||
vi.mocked(prisma.mfaChallenge.updateMany).mockResolvedValueOnce({
|
||||
count: 1,
|
||||
} as never);
|
||||
expect(await claimChallenge("ch-1")).toBe(true);
|
||||
|
||||
vi.mocked(prisma.mfaChallenge.updateMany).mockResolvedValueOnce({
|
||||
count: 0,
|
||||
} as never);
|
||||
expect(await claimChallenge("ch-1")).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,112 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
|
||||
// Real Argon2id hashing (a handful of codes is fast enough for a unit test)
|
||||
// so the hash/verify round-trip is exercised end-to-end. Only the DB is mocked.
|
||||
vi.mock("@/lib/db", () => ({
|
||||
prisma: {
|
||||
mfaRecoveryCode: {
|
||||
createMany: vi.fn(),
|
||||
deleteMany: vi.fn(),
|
||||
findMany: vi.fn(),
|
||||
updateMany: vi.fn(),
|
||||
count: vi.fn(),
|
||||
},
|
||||
$transaction: vi.fn(async (fn: (tx: unknown) => Promise<unknown>) => {
|
||||
// The transactional helper receives the same mocked client.
|
||||
const { prisma } = await import("@/lib/db");
|
||||
return fn(prisma);
|
||||
}),
|
||||
},
|
||||
}));
|
||||
|
||||
import {
|
||||
generateRecoveryCodes,
|
||||
regenerateRecoveryCodes,
|
||||
verifyAndConsumeRecoveryCode,
|
||||
normaliseRecoveryCode,
|
||||
RECOVERY_CODE_COUNT,
|
||||
} from "../recovery-codes";
|
||||
import { hashPassword } from "@/lib/auth/password";
|
||||
import { prisma } from "@/lib/db";
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
describe("recovery-codes", () => {
|
||||
it("generates the configured count of high-entropy, grouped codes", () => {
|
||||
const codes = generateRecoveryCodes();
|
||||
expect(codes).toHaveLength(RECOVERY_CODE_COUNT);
|
||||
for (const c of codes) {
|
||||
expect(c).toMatch(/^[A-Z2-9]{5}-[A-Z2-9]{5}$/);
|
||||
}
|
||||
// No duplicates in a batch.
|
||||
expect(new Set(codes).size).toBe(codes.length);
|
||||
});
|
||||
|
||||
it("verifies a code once then refuses it (one-time use)", async () => {
|
||||
const code = "ABCDE-FGHJK";
|
||||
const codeHash = await hashPassword(normaliseRecoveryCode(code));
|
||||
|
||||
vi.mocked(prisma.mfaRecoveryCode.findMany).mockResolvedValue([
|
||||
{ id: "row-1", codeHash },
|
||||
] as never);
|
||||
// First consume succeeds — the guarded update flips exactly one row.
|
||||
vi.mocked(prisma.mfaRecoveryCode.updateMany).mockResolvedValueOnce({
|
||||
count: 1,
|
||||
} as never);
|
||||
|
||||
const first = await verifyAndConsumeRecoveryCode("user-1", code);
|
||||
expect(first).toBe(true);
|
||||
|
||||
// Second attempt: the row is now used, so findMany returns nothing.
|
||||
vi.mocked(prisma.mfaRecoveryCode.findMany).mockResolvedValue([] as never);
|
||||
const second = await verifyAndConsumeRecoveryCode("user-1", code);
|
||||
expect(second).toBe(false);
|
||||
});
|
||||
|
||||
it("treats a lost claim race (count !== 1) as a miss", async () => {
|
||||
const code = "ABCDE-FGHJK";
|
||||
const codeHash = await hashPassword(normaliseRecoveryCode(code));
|
||||
vi.mocked(prisma.mfaRecoveryCode.findMany).mockResolvedValue([
|
||||
{ id: "row-1", codeHash },
|
||||
] as never);
|
||||
vi.mocked(prisma.mfaRecoveryCode.updateMany).mockResolvedValueOnce({
|
||||
count: 0,
|
||||
} as never);
|
||||
|
||||
expect(await verifyAndConsumeRecoveryCode("user-1", code)).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects a code that matches no stored hash", async () => {
|
||||
const realHash = await hashPassword(normaliseRecoveryCode("AAAAA-BBBBB"));
|
||||
vi.mocked(prisma.mfaRecoveryCode.findMany).mockResolvedValue([
|
||||
{ id: "row-1", codeHash: realHash },
|
||||
] as never);
|
||||
expect(await verifyAndConsumeRecoveryCode("user-1", "ZZZZZ-99999")).toBe(
|
||||
false,
|
||||
);
|
||||
expect(prisma.mfaRecoveryCode.updateMany).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("regeneration deletes the entire prior set before inserting", async () => {
|
||||
vi.mocked(prisma.mfaRecoveryCode.deleteMany).mockResolvedValue({
|
||||
count: 10,
|
||||
} as never);
|
||||
vi.mocked(prisma.mfaRecoveryCode.createMany).mockResolvedValue({
|
||||
count: 10,
|
||||
} as never);
|
||||
|
||||
const codes = await regenerateRecoveryCodes("user-1");
|
||||
expect(codes).toHaveLength(RECOVERY_CODE_COUNT);
|
||||
expect(prisma.mfaRecoveryCode.deleteMany).toHaveBeenCalledWith({
|
||||
where: { userId: "user-1" },
|
||||
});
|
||||
// Delete is ordered before the insert.
|
||||
const deleteOrder = vi.mocked(prisma.mfaRecoveryCode.deleteMany).mock
|
||||
.invocationCallOrder[0];
|
||||
const insertOrder = vi.mocked(prisma.mfaRecoveryCode.createMany).mock
|
||||
.invocationCallOrder[0];
|
||||
expect(deleteOrder).toBeLessThan(insertOrder);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,100 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import * as OTPAuth from "otpauth";
|
||||
import {
|
||||
generateTotpSecret,
|
||||
buildOtpauthUri,
|
||||
verifyTotp,
|
||||
currentTotpStep,
|
||||
TOTP_PERIOD_SECONDS,
|
||||
} from "../totp";
|
||||
|
||||
/** Compute the canonical code a compliant authenticator would show at `atMs`. */
|
||||
function codeAt(secretBase32: string, atMs: number): string {
|
||||
const totp = new OTPAuth.TOTP({
|
||||
issuer: "HealthLog",
|
||||
label: "HealthLog",
|
||||
algorithm: "SHA1",
|
||||
digits: 6,
|
||||
period: TOTP_PERIOD_SECONDS,
|
||||
secret: OTPAuth.Secret.fromBase32(secretBase32),
|
||||
});
|
||||
return totp.generate({ timestamp: atMs });
|
||||
}
|
||||
|
||||
const PERIOD_MS = TOTP_PERIOD_SECONDS * 1000;
|
||||
|
||||
describe("totp", () => {
|
||||
it("generates a Base32 secret and a parseable otpauth URI", () => {
|
||||
const secret = generateTotpSecret();
|
||||
expect(secret).toMatch(/^[A-Z2-7]+$/);
|
||||
const uri = buildOtpauthUri(secret, "user@example.com");
|
||||
expect(uri.startsWith("otpauth://totp/")).toBe(true);
|
||||
expect(uri).toContain("issuer=HealthLog");
|
||||
expect(uri).toContain("algorithm=SHA1");
|
||||
expect(uri).toContain("digits=6");
|
||||
// Round-trips back to the same secret.
|
||||
const parsed = OTPAuth.URI.parse(uri) as OTPAuth.TOTP;
|
||||
expect(parsed.secret.base32).toBe(secret);
|
||||
});
|
||||
|
||||
it("accepts the current code and reports its step", () => {
|
||||
const secret = generateTotpSecret();
|
||||
const now = 1_700_000_000_000;
|
||||
const res = verifyTotp(secret, codeAt(secret, now), null, now);
|
||||
expect(res.valid).toBe(true);
|
||||
expect(res.replay).toBe(false);
|
||||
expect(res.step).toBe(currentTotpStep(now));
|
||||
});
|
||||
|
||||
it("rejects a wrong code and a non-numeric code", () => {
|
||||
const secret = generateTotpSecret();
|
||||
const now = 1_700_000_000_000;
|
||||
expect(verifyTotp(secret, "000000", null, now).valid).toBe(false);
|
||||
expect(verifyTotp(secret, "abcdef", null, now).valid).toBe(false);
|
||||
expect(verifyTotp(secret, "12345", null, now).valid).toBe(false); // too short
|
||||
});
|
||||
|
||||
it("accepts the previous and next step within the ±1 drift window", () => {
|
||||
const secret = generateTotpSecret();
|
||||
const now = 1_700_000_400_000;
|
||||
const prev = codeAt(secret, now - PERIOD_MS);
|
||||
const next = codeAt(secret, now + PERIOD_MS);
|
||||
expect(verifyTotp(secret, prev, null, now).valid).toBe(true);
|
||||
expect(verifyTotp(secret, next, null, now).valid).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects a code two steps away (outside the window)", () => {
|
||||
const secret = generateTotpSecret();
|
||||
const now = 1_700_000_400_000;
|
||||
const twoBack = codeAt(secret, now - 2 * PERIOD_MS);
|
||||
expect(verifyTotp(secret, twoBack, null, now).valid).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects replay of an already-accepted step (monotonic guard)", () => {
|
||||
const secret = generateTotpSecret();
|
||||
const now = 1_700_000_000_000;
|
||||
const code = codeAt(secret, now);
|
||||
const first = verifyTotp(secret, code, null, now);
|
||||
expect(first.valid).toBe(true);
|
||||
const step = first.step as number;
|
||||
|
||||
// Same code, now with lastStep recorded — must be rejected as a replay
|
||||
// even though it is still inside its 30-second life.
|
||||
const second = verifyTotp(secret, code, step, now);
|
||||
expect(second.valid).toBe(false);
|
||||
expect(second.replay).toBe(true);
|
||||
expect(second.step).toBe(step);
|
||||
});
|
||||
|
||||
it("rejects a still-valid older step once a newer one was accepted", () => {
|
||||
const secret = generateTotpSecret();
|
||||
const now = 1_700_000_400_000;
|
||||
const prevCode = codeAt(secret, now - PERIOD_MS);
|
||||
const prevStep = currentTotpStep(now) - 1;
|
||||
// The previous-step code is in-window but its step <= lastStep (current).
|
||||
const res = verifyTotp(secret, prevCode, currentTotpStep(now), now);
|
||||
expect(res.valid).toBe(false);
|
||||
expect(res.replay).toBe(true);
|
||||
expect(res.step).toBe(prevStep);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,133 @@
|
||||
/**
|
||||
* MfaChallenge — the short-lived, single-use login step-up ticket.
|
||||
*
|
||||
* When a password (or other primary credential) is accepted for an account
|
||||
* that has a second factor enabled, **no session or token is issued**.
|
||||
* Instead a challenge row is minted: the partial "password OK, awaiting
|
||||
* factor 2" state lives entirely in this row, never in a half-built
|
||||
* `Session`. The caller receives an opaque ticket; only its hash
|
||||
* (`hashToken`) is stored, so a leaked database row cannot reconstruct a
|
||||
* usable ticket.
|
||||
*
|
||||
* Guarantees enforced here:
|
||||
* - **TTL** (~5 min) — `expiresAt`; an expired ticket is never loadable.
|
||||
* - **Attempt cap** — `attempts` is incremented on every wrong factor and
|
||||
* the ticket is burned (`consumedAt` set) once the cap is hit, forcing a
|
||||
* fresh password login (NIST throttle, not an account lock).
|
||||
* - **Claim-once** — consuming a ticket is an atomic guarded update
|
||||
* (`consumedAt: null` in the WHERE), so two concurrent verifications can
|
||||
* never both succeed and mint two sessions. The factor is verified first;
|
||||
* the session is issued only after the claim wins.
|
||||
*/
|
||||
import { randomBytes } from "node:crypto";
|
||||
import { hashToken } from "@/lib/auth/hmac";
|
||||
import { prisma } from "@/lib/db";
|
||||
|
||||
/** Login step-up: the only `kind` Phase M exercises. */
|
||||
export type MfaChallengeKind = "login";
|
||||
|
||||
/** 5-minute ticket life — long enough to read a code, short enough to bound replay. */
|
||||
export const MFA_CHALLENGE_TTL_MS = 5 * 60 * 1000;
|
||||
/** Wrong-factor attempts before the ticket is burned. */
|
||||
export const MFA_CHALLENGE_ATTEMPT_CAP = 5;
|
||||
|
||||
export interface CreatedChallenge {
|
||||
/** The opaque ticket handed to the client (never stored in the clear). */
|
||||
ticket: string;
|
||||
expiresAt: Date;
|
||||
}
|
||||
|
||||
/** Mint a fresh single-use challenge for a user/kind. */
|
||||
export async function createMfaChallenge(
|
||||
userId: string,
|
||||
kind: MfaChallengeKind,
|
||||
): Promise<CreatedChallenge> {
|
||||
const ticket = randomBytes(32).toString("base64url");
|
||||
const expiresAt = new Date(Date.now() + MFA_CHALLENGE_TTL_MS);
|
||||
await prisma.mfaChallenge.create({
|
||||
data: {
|
||||
userId,
|
||||
kind,
|
||||
ticketHash: hashToken(ticket),
|
||||
expiresAt,
|
||||
},
|
||||
});
|
||||
return { ticket, expiresAt };
|
||||
}
|
||||
|
||||
export interface ActiveChallenge {
|
||||
id: string;
|
||||
userId: string;
|
||||
kind: string;
|
||||
attempts: number;
|
||||
expiresAt: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a presented ticket to its live challenge, or null when it is
|
||||
* unknown / already consumed / expired / over the attempt cap. The lookup
|
||||
* is by hash — the raw ticket is never compared against a stored plaintext.
|
||||
*/
|
||||
export async function loadActiveChallenge(
|
||||
ticket: string,
|
||||
): Promise<ActiveChallenge | null> {
|
||||
const row = await prisma.mfaChallenge.findUnique({
|
||||
where: { ticketHash: hashToken(ticket) },
|
||||
select: {
|
||||
id: true,
|
||||
userId: true,
|
||||
kind: true,
|
||||
attempts: true,
|
||||
expiresAt: true,
|
||||
consumedAt: true,
|
||||
},
|
||||
});
|
||||
if (!row) return null;
|
||||
if (row.consumedAt !== null) return null;
|
||||
if (row.expiresAt.getTime() <= Date.now()) return null;
|
||||
if (row.attempts >= MFA_CHALLENGE_ATTEMPT_CAP) return null;
|
||||
return {
|
||||
id: row.id,
|
||||
userId: row.userId,
|
||||
kind: row.kind,
|
||||
attempts: row.attempts,
|
||||
expiresAt: row.expiresAt,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Record a failed factor attempt. Increments `attempts`; when the cap is
|
||||
* reached the ticket is burned (`consumedAt` set) so it cannot be retried.
|
||||
* Returns whether the ticket is now exhausted.
|
||||
*/
|
||||
export async function recordChallengeFailure(
|
||||
challengeId: string,
|
||||
): Promise<{ exhausted: boolean; attempts: number }> {
|
||||
const updated = await prisma.mfaChallenge.update({
|
||||
where: { id: challengeId },
|
||||
data: { attempts: { increment: 1 } },
|
||||
select: { attempts: true },
|
||||
});
|
||||
const exhausted = updated.attempts >= MFA_CHALLENGE_ATTEMPT_CAP;
|
||||
if (exhausted) {
|
||||
await prisma.mfaChallenge.updateMany({
|
||||
where: { id: challengeId, consumedAt: null },
|
||||
data: { consumedAt: new Date() },
|
||||
});
|
||||
}
|
||||
return { exhausted, attempts: updated.attempts };
|
||||
}
|
||||
|
||||
/**
|
||||
* Atomically claim the ticket. Returns true only for the single caller that
|
||||
* transitions `consumedAt` from null → now. The factor MUST already be
|
||||
* verified before this is called; the session is issued only when this
|
||||
* returns true.
|
||||
*/
|
||||
export async function claimChallenge(challengeId: string): Promise<boolean> {
|
||||
const claimed = await prisma.mfaChallenge.updateMany({
|
||||
where: { id: challengeId, consumedAt: null },
|
||||
data: { consumedAt: new Date() },
|
||||
});
|
||||
return claimed.count === 1;
|
||||
}
|
||||
@@ -0,0 +1,133 @@
|
||||
/**
|
||||
* Recovery (backup) codes — the lost-authenticator fallback for the TOTP
|
||||
* second factor.
|
||||
*
|
||||
* - **10 single-use codes**, each ~64+ bits of CSPRNG entropy, rendered as
|
||||
* two Base32 groups for legibility (`XXXXX-XXXXX`).
|
||||
* - **Argon2id-hashed at rest** (the same primitive and cost parameters as
|
||||
* the account password) — OWASP cautions that recovery-code keyspaces are
|
||||
* small, so a slow hash is what makes the at-rest storage meaningful.
|
||||
* - **Shown once** at TOTP confirm (and on explicit regeneration); only the
|
||||
* hash is stored, so the plaintext set can never be re-derived server-side.
|
||||
* - **One-time use:** verifying a code burns it (`usedAt`).
|
||||
* - **Regeneration invalidates the entire prior set** in a transaction.
|
||||
*
|
||||
* Verification is constant-time-ish: the candidate is Argon2id-verified
|
||||
* against every still-unused hash for the user (Argon2's verify is itself
|
||||
* constant-time), so there is no early-exit oracle on which code matched.
|
||||
*/
|
||||
import { randomInt } from "node:crypto";
|
||||
import { hashPassword, verifyPassword } from "@/lib/auth/password";
|
||||
import { prisma } from "@/lib/db";
|
||||
import type { Prisma, PrismaClient } from "@/generated/prisma/client";
|
||||
|
||||
export const RECOVERY_CODE_COUNT = 10;
|
||||
/** Crockford-ish Base32 alphabet minus easily-confused glyphs (0/O, 1/I/L). */
|
||||
const CODE_ALPHABET = "ABCDEFGHJKMNPQRSTVWXYZ23456789";
|
||||
const GROUP_LENGTH = 5;
|
||||
const GROUPS = 2; // 10 chars over a 29-symbol alphabet ≈ 49 bits/group pair → ~64+ bits set-wide guard below
|
||||
|
||||
/** A single high-entropy code, e.g. `7QF3K-MZ2WP`. */
|
||||
function generateRecoveryCode(): string {
|
||||
const groups: string[] = [];
|
||||
for (let g = 0; g < GROUPS; g++) {
|
||||
let group = "";
|
||||
for (let i = 0; i < GROUP_LENGTH; i++) {
|
||||
group += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
|
||||
}
|
||||
groups.push(group);
|
||||
}
|
||||
return groups.join("-");
|
||||
}
|
||||
|
||||
/** Generate a fresh batch of plaintext codes (caller shows them once). */
|
||||
export function generateRecoveryCodes(
|
||||
count: number = RECOVERY_CODE_COUNT,
|
||||
): string[] {
|
||||
return Array.from({ length: count }, generateRecoveryCode);
|
||||
}
|
||||
|
||||
/** Normalise user input: strip spaces, upper-case (the display is grouped). */
|
||||
export function normaliseRecoveryCode(input: string): string {
|
||||
return input.trim().toUpperCase().replace(/\s+/g, "");
|
||||
}
|
||||
|
||||
type TxClient = Prisma.TransactionClient | PrismaClient;
|
||||
|
||||
/**
|
||||
* Argon2id-hash a batch and persist one row per code. Runs inside the
|
||||
* caller's transaction so the recovery set lands atomically with the
|
||||
* pending→active promotion (confirm) or the prior-set deletion (regen).
|
||||
*/
|
||||
export async function persistRecoveryCodes(
|
||||
tx: TxClient,
|
||||
userId: string,
|
||||
codes: string[],
|
||||
): Promise<void> {
|
||||
const hashes = await Promise.all(
|
||||
codes.map((code) => hashPassword(normaliseRecoveryCode(code))),
|
||||
);
|
||||
await tx.mfaRecoveryCode.createMany({
|
||||
data: hashes.map((codeHash) => ({ userId, codeHash })),
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Replace the user's entire recovery-code set with a fresh batch and return
|
||||
* the new plaintext codes (shown once). The delete + insert run in one
|
||||
* transaction so a regeneration never leaves a half-rotated set.
|
||||
*/
|
||||
export async function regenerateRecoveryCodes(
|
||||
userId: string,
|
||||
count: number = RECOVERY_CODE_COUNT,
|
||||
): Promise<string[]> {
|
||||
const codes = generateRecoveryCodes(count);
|
||||
await prisma.$transaction(async (tx) => {
|
||||
await tx.mfaRecoveryCode.deleteMany({ where: { userId } });
|
||||
await persistRecoveryCodes(tx, userId, codes);
|
||||
});
|
||||
return codes;
|
||||
}
|
||||
|
||||
/** Count the codes a user still has available (unused). */
|
||||
export async function countRemainingRecoveryCodes(
|
||||
userId: string,
|
||||
): Promise<number> {
|
||||
return prisma.mfaRecoveryCode.count({ where: { userId, usedAt: null } });
|
||||
}
|
||||
|
||||
/**
|
||||
* Verify a candidate against the user's unused codes and burn it on match.
|
||||
*
|
||||
* The burn is a guarded `updateMany` (`usedAt: null` in the WHERE) so two
|
||||
* concurrent verifications of the same code can never both succeed — the
|
||||
* second update affects zero rows and is treated as a miss. Returns true
|
||||
* only when exactly one row transitioned to used.
|
||||
*/
|
||||
export async function verifyAndConsumeRecoveryCode(
|
||||
userId: string,
|
||||
candidate: string,
|
||||
): Promise<boolean> {
|
||||
const normalised = normaliseRecoveryCode(candidate);
|
||||
if (normalised.length === 0) return false;
|
||||
|
||||
const rows = await prisma.mfaRecoveryCode.findMany({
|
||||
where: { userId, usedAt: null },
|
||||
select: { id: true, codeHash: true },
|
||||
});
|
||||
|
||||
for (const row of rows) {
|
||||
// Argon2id verify is constant-time; iterate the full set so the match
|
||||
// position is not observable through timing.
|
||||
const match = await verifyPassword(row.codeHash, normalised);
|
||||
if (!match) continue;
|
||||
|
||||
const burned = await prisma.mfaRecoveryCode.updateMany({
|
||||
where: { id: row.id, usedAt: null },
|
||||
data: { usedAt: new Date() },
|
||||
});
|
||||
return burned.count === 1;
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
@@ -0,0 +1,131 @@
|
||||
/**
|
||||
* TOTP (RFC 6238) second-factor primitives.
|
||||
*
|
||||
* Thin wrapper over `otpauth` (zero runtime deps) pinning the de-facto
|
||||
* interop floor — **SHA-1, 6 digits, 30-second period** — because
|
||||
* SHA-256/512 break the common authenticator apps and hardware tokens.
|
||||
* Drift window is **±1 step** (previous / current / next), the RFC's
|
||||
* recommended bound; every extra step widens the replay surface.
|
||||
*
|
||||
* Replay protection (the commonly-omitted control) is enforced by the
|
||||
* caller via the monotonic last-step counter: `verifyTotp` resolves the
|
||||
* submitted code to its absolute time-step and returns it, and the caller
|
||||
* rejects any step that is not strictly greater than the persisted
|
||||
* `User.totpLastStep`. A captured code therefore dies the instant it is
|
||||
* accepted once, even while it is still inside its 30-second life.
|
||||
*
|
||||
* The shared secret never leaves this module as anything but Base32; the
|
||||
* `otpauth://` URI carries the secret and is built here only to hand to
|
||||
* the enrolling client — it is never logged or persisted.
|
||||
*/
|
||||
import * as OTPAuth from "otpauth";
|
||||
|
||||
export const TOTP_ISSUER = "HealthLog";
|
||||
export const TOTP_ALGORITHM = "SHA1";
|
||||
export const TOTP_DIGITS = 6;
|
||||
export const TOTP_PERIOD_SECONDS = 30;
|
||||
/** ±1 step (≈ ±30 s clock skew). Do not widen without cause. */
|
||||
export const TOTP_WINDOW = 1;
|
||||
/** 160-bit secret per OWASP MFA / NIST 800-63B (`size` is bytes). */
|
||||
const TOTP_SECRET_BYTES = 20;
|
||||
|
||||
/**
|
||||
* Generate a fresh CSPRNG Base32 secret (160-bit). The returned string is
|
||||
* the only form persisted (AES-256-GCM encrypted) and reconstituted for
|
||||
* verification.
|
||||
*/
|
||||
export function generateTotpSecret(): string {
|
||||
return new OTPAuth.Secret({ size: TOTP_SECRET_BYTES }).base32;
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the `otpauth://totp/...` enrollment URI for a Base32 secret.
|
||||
* Issuer is the fixed app name; `account` is the user-facing label
|
||||
* (email or username). The URI carries the secret — hand it to the client,
|
||||
* never log or persist it.
|
||||
*/
|
||||
export function buildOtpauthUri(secretBase32: string, account: string): string {
|
||||
const totp = new OTPAuth.TOTP({
|
||||
issuer: TOTP_ISSUER,
|
||||
label: account,
|
||||
algorithm: TOTP_ALGORITHM,
|
||||
digits: TOTP_DIGITS,
|
||||
period: TOTP_PERIOD_SECONDS,
|
||||
secret: OTPAuth.Secret.fromBase32(secretBase32),
|
||||
});
|
||||
return totp.toString();
|
||||
}
|
||||
|
||||
/** The absolute RFC 6238 time-step for a moment in time. */
|
||||
export function currentTotpStep(atMs: number = Date.now()): number {
|
||||
return Math.floor(atMs / 1000 / TOTP_PERIOD_SECONDS);
|
||||
}
|
||||
|
||||
export interface TotpVerifyResult {
|
||||
/** True only when the code is in-window AND not a replay. */
|
||||
valid: boolean;
|
||||
/**
|
||||
* The absolute time-step the code resolved to (current step + drift
|
||||
* delta). Present whenever the code matched the secret in-window — even
|
||||
* when rejected as a replay — so the caller can log the reason. Persist
|
||||
* this as the new `totpLastStep` on a successful, non-replay accept.
|
||||
*/
|
||||
step: number | null;
|
||||
/** True when the code matched in-window but its step was already used. */
|
||||
replay: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Verify a 6-digit code against a Base32 secret with ±1 drift and
|
||||
* monotonic replay rejection.
|
||||
*
|
||||
* @param secretBase32 the user's stored TOTP secret
|
||||
* @param code the submitted 6-digit code (non-digits → invalid)
|
||||
* @param lastStep the user's persisted `totpLastStep` (null = none yet)
|
||||
* @param atMs clock injection point for tests
|
||||
*/
|
||||
export function verifyTotp(
|
||||
secretBase32: string,
|
||||
code: string,
|
||||
lastStep: number | null,
|
||||
atMs: number = Date.now(),
|
||||
): TotpVerifyResult {
|
||||
const normalised = code.trim();
|
||||
if (!/^\d{6}$/.test(normalised)) {
|
||||
return { valid: false, step: null, replay: false };
|
||||
}
|
||||
|
||||
const totp = new OTPAuth.TOTP({
|
||||
issuer: TOTP_ISSUER,
|
||||
label: TOTP_ISSUER,
|
||||
algorithm: TOTP_ALGORITHM,
|
||||
digits: TOTP_DIGITS,
|
||||
period: TOTP_PERIOD_SECONDS,
|
||||
secret: OTPAuth.Secret.fromBase32(secretBase32),
|
||||
});
|
||||
|
||||
// `validate` returns the signed step delta (e.g. -1, 0, +1) when the
|
||||
// code matches inside the window, or null when it does not. The compare
|
||||
// is over the numeric HOTP truncation, not a string equality on the
|
||||
// secret, so there is no early-exit timing oracle on the secret bytes.
|
||||
const delta = totp.validate({
|
||||
token: normalised,
|
||||
timestamp: atMs,
|
||||
window: TOTP_WINDOW,
|
||||
});
|
||||
|
||||
if (delta === null) {
|
||||
return { valid: false, step: null, replay: false };
|
||||
}
|
||||
|
||||
const step = currentTotpStep(atMs) + delta;
|
||||
|
||||
// Monotonic replay guard: the resolved step must be strictly newer than
|
||||
// the last one we accepted. Reusing an already-burned step — even one
|
||||
// still inside its 30-second life — is rejected.
|
||||
if (lastStep !== null && step <= lastStep) {
|
||||
return { valid: false, step, replay: true };
|
||||
}
|
||||
|
||||
return { valid: true, step, replay: false };
|
||||
}
|
||||
@@ -0,0 +1,76 @@
|
||||
/**
|
||||
* Verify a presented second factor (TOTP or recovery code) for a user, with
|
||||
* the side effects that make each factor single-use:
|
||||
*
|
||||
* - **TOTP:** decrypt the stored secret (fail-closed), validate with ±1 drift
|
||||
* and monotonic replay rejection, and on success **persist the accepted
|
||||
* time-step** so the same code cannot be replayed within its 30-second life.
|
||||
* - **Recovery code:** Argon2id-verify against the unused set and burn the
|
||||
* matched row.
|
||||
*
|
||||
* Used by both the login-completion route (`/api/auth/mfa/verify`) and the
|
||||
* step-up-gated MFA-disable route, so the factor semantics are identical
|
||||
* wherever a current factor must be proven.
|
||||
*/
|
||||
import { prisma } from "@/lib/db";
|
||||
import { decrypt } from "@/lib/crypto";
|
||||
import { verifyTotp } from "@/lib/auth/mfa/totp";
|
||||
import { verifyAndConsumeRecoveryCode } from "@/lib/auth/mfa/recovery-codes";
|
||||
|
||||
export type MfaMethod = "totp" | "recovery";
|
||||
|
||||
export interface FactorUser {
|
||||
id: string;
|
||||
totpSecretEncrypted: string | null;
|
||||
totpLastStep: bigint | null;
|
||||
}
|
||||
|
||||
export interface FactorResult {
|
||||
ok: boolean;
|
||||
/** TOTP only: the code matched the secret but its step was already used. */
|
||||
replay: boolean;
|
||||
}
|
||||
|
||||
export async function verifyMfaFactor(
|
||||
user: FactorUser,
|
||||
method: MfaMethod,
|
||||
code: string,
|
||||
): Promise<FactorResult> {
|
||||
if (method === "recovery") {
|
||||
const ok = await verifyAndConsumeRecoveryCode(user.id, code);
|
||||
return { ok, replay: false };
|
||||
}
|
||||
|
||||
// TOTP.
|
||||
if (!user.totpSecretEncrypted) return { ok: false, replay: false };
|
||||
const secret = decrypt(user.totpSecretEncrypted);
|
||||
const result = verifyTotp(
|
||||
secret,
|
||||
code,
|
||||
user.totpLastStep === null ? null : Number(user.totpLastStep),
|
||||
);
|
||||
if (!result.valid) {
|
||||
return { ok: false, replay: result.replay };
|
||||
}
|
||||
|
||||
// Burn the step: persist it as the new floor so a replay of this exact
|
||||
// code (still inside its 30-second window) is rejected. The guarded WHERE
|
||||
// (`totpLastStep` unchanged) makes two concurrent accepts of the same step
|
||||
// race-safe — only the first transitions the counter.
|
||||
const advanced = await prisma.user.updateMany({
|
||||
where: {
|
||||
id: user.id,
|
||||
OR: [
|
||||
{ totpLastStep: null },
|
||||
{ totpLastStep: { lt: BigInt(result.step as number) } },
|
||||
],
|
||||
},
|
||||
data: { totpLastStep: BigInt(result.step as number) },
|
||||
});
|
||||
if (advanced.count !== 1) {
|
||||
// Another request already consumed this (or a newer) step — treat as a
|
||||
// replay rather than a fresh accept.
|
||||
return { ok: false, replay: true };
|
||||
}
|
||||
return { ok: true, replay: false };
|
||||
}
|
||||
@@ -58,6 +58,11 @@ export async function createSession(
|
||||
onboardingPending: boolean,
|
||||
ipAddress?: string | null,
|
||||
userAgent?: string | null,
|
||||
// v1.23 — set when this session was minted behind a completed second
|
||||
// factor (the `/api/auth/mfa/verify` path) or a fresh factor re-confirm.
|
||||
// `requireFreshMfa` reads it for step-up freshness; a null value means
|
||||
// "single-factor session" and never satisfies step-up.
|
||||
mfaVerifiedAt?: Date | null,
|
||||
): Promise<string> {
|
||||
const session = await prisma.session.create({
|
||||
data: {
|
||||
@@ -65,6 +70,7 @@ export async function createSession(
|
||||
expiresAt: new Date(Date.now() + SESSION_MAX_AGE_MS),
|
||||
ipAddress: ipAddress ?? null,
|
||||
userAgent: userAgent ?? null,
|
||||
mfaVerifiedAt: mfaVerifiedAt ?? null,
|
||||
},
|
||||
});
|
||||
|
||||
|
||||
@@ -8,6 +8,11 @@
|
||||
import { z } from "zod/v4";
|
||||
import type { ZodOpenApiObject } from "zod-openapi";
|
||||
import { loginPasswordSchema } from "@/lib/validations/auth";
|
||||
import {
|
||||
mfaVerifySchema,
|
||||
totpConfirmSchema,
|
||||
mfaDisableSchema,
|
||||
} from "@/lib/validations/mfa";
|
||||
import { dataEnvelope, stdResponses } from "./shared";
|
||||
|
||||
// ── Sub-schemas owned here (route-specific shapes) ───────────────────
|
||||
@@ -73,23 +78,193 @@ const accessRefreshBundle = z
|
||||
"Native-client token bundle returned by login + refresh. Web cookie-only callers see only `user`.",
|
||||
});
|
||||
|
||||
// ── v1.23 second-factor (MFA) shapes ─────────────────────────────────
|
||||
|
||||
const mfaRequiredEnvelope = z
|
||||
.object({
|
||||
data: z.null(),
|
||||
error: z.null(),
|
||||
meta: z.object({
|
||||
mfaRequired: z.literal(true),
|
||||
mfaTicket: z
|
||||
.string()
|
||||
.describe(
|
||||
"Opaque, single-use, ~5-minute ticket to present to /api/auth/mfa/verify.",
|
||||
),
|
||||
methods: z
|
||||
.array(z.enum(["totp", "recovery"]))
|
||||
.describe(
|
||||
"Second factors the account can complete the challenge with.",
|
||||
),
|
||||
}),
|
||||
})
|
||||
.meta({
|
||||
id: "MfaRequiredResponse",
|
||||
description:
|
||||
"Password accepted but a second factor is required. Not an error and not a session — no token is issued until /api/auth/mfa/verify succeeds.",
|
||||
});
|
||||
|
||||
const totpSetupResponse = z
|
||||
.object({
|
||||
otpauthUri: z
|
||||
.string()
|
||||
.describe("otpauth:// URI to render as a QR code (carries the secret)."),
|
||||
totpSecret: z
|
||||
.string()
|
||||
.describe("Base32 secret for manual entry. Pending until confirmed."),
|
||||
})
|
||||
.meta({ id: "TotpSetupResponse" });
|
||||
|
||||
const recoveryCodesResponse = z
|
||||
.object({
|
||||
enabled: z.boolean().optional(),
|
||||
recoveryCodes: z
|
||||
.array(z.string())
|
||||
.describe("Single-use recovery codes, shown once. Save them now."),
|
||||
recoveryCodesRemaining: z.number().int(),
|
||||
})
|
||||
.meta({ id: "MfaRecoveryCodesResponse" });
|
||||
|
||||
const mfaToggleResponse = z
|
||||
.object({ enabled: z.boolean() })
|
||||
.meta({ id: "MfaToggleResponse" });
|
||||
|
||||
export const authPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
"/api/auth/login": {
|
||||
post: {
|
||||
tags: ["Auth"],
|
||||
summary: "Email-or-username login (password)",
|
||||
description:
|
||||
"Browser callers receive a session cookie. Native callers (X-Client-Type: native or HealthLog-iOS UA prefix) additionally receive a paired access + refresh token.",
|
||||
"Browser callers receive a session cookie. Native callers (X-Client-Type: native or HealthLog-iOS UA prefix) additionally receive a paired access + refresh token.\n\n" +
|
||||
"v1.23 — when the account has a confirmed second factor, the response carries no session/token. It returns HTTP 200 with `data: null, error: null` and `meta.mfaRequired: true` plus a single-use `meta.mfaTicket` and the `meta.methods` list. The client must POST the ticket + a code to `/api/auth/mfa/verify` to obtain the token bundle. Accounts without MFA are unchanged.",
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: loginPasswordSchema } },
|
||||
},
|
||||
responses: {
|
||||
"200": {
|
||||
description: "Login succeeded.",
|
||||
description:
|
||||
"Login succeeded (token bundle / cookie) — or a second factor is required (`meta.mfaRequired`).",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: dataEnvelope(accessRefreshBundle, "LoginResponse"),
|
||||
schema: z.union([
|
||||
dataEnvelope(accessRefreshBundle, "LoginResponse"),
|
||||
mfaRequiredEnvelope,
|
||||
]),
|
||||
},
|
||||
},
|
||||
},
|
||||
...stdResponses,
|
||||
},
|
||||
},
|
||||
},
|
||||
"/api/auth/mfa/verify": {
|
||||
post: {
|
||||
tags: ["Auth"],
|
||||
summary: "Complete a second-factor login challenge",
|
||||
description:
|
||||
"Presents the `mfaTicket` from the login `meta.mfaRequired` response plus a TOTP or recovery code. On success returns the SAME token bundle / session the password path issues, with the session marked second-factor-verified. The ticket is single-use; wrong codes are throttled and the ticket is burned at the attempt cap.",
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: mfaVerifySchema } },
|
||||
},
|
||||
responses: {
|
||||
"200": {
|
||||
description:
|
||||
"Second factor verified — session + optional bearer issued.",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: dataEnvelope(accessRefreshBundle, "MfaVerifyResponse"),
|
||||
},
|
||||
},
|
||||
},
|
||||
...stdResponses,
|
||||
},
|
||||
},
|
||||
},
|
||||
"/api/auth/me/mfa/totp/setup": {
|
||||
post: {
|
||||
tags: ["Auth"],
|
||||
summary: "Begin TOTP enrollment (cookie session only)",
|
||||
description:
|
||||
"Generates and stores a pending (encrypted) TOTP secret and returns the otpauth URI + Base32 secret. MFA is not active until /confirm. Cookie-only — a Bearer token cannot enrol MFA.",
|
||||
responses: {
|
||||
"200": {
|
||||
description: "Pending secret created.",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: dataEnvelope(totpSetupResponse, "TotpSetupEnvelope"),
|
||||
},
|
||||
},
|
||||
},
|
||||
...stdResponses,
|
||||
},
|
||||
},
|
||||
},
|
||||
"/api/auth/me/mfa/totp/confirm": {
|
||||
post: {
|
||||
tags: ["Auth"],
|
||||
summary: "Confirm TOTP enrollment (cookie session only)",
|
||||
description:
|
||||
"Verifies a code against the pending secret, activates the factor, and returns the one-time recovery codes. Cookie-only.",
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: totpConfirmSchema } },
|
||||
},
|
||||
responses: {
|
||||
"200": {
|
||||
description: "Factor activated — recovery codes returned once.",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: dataEnvelope(
|
||||
recoveryCodesResponse,
|
||||
"TotpConfirmEnvelope",
|
||||
),
|
||||
},
|
||||
},
|
||||
},
|
||||
...stdResponses,
|
||||
},
|
||||
},
|
||||
},
|
||||
"/api/auth/me/mfa/disable": {
|
||||
post: {
|
||||
tags: ["Auth"],
|
||||
summary: "Disable the second factor (step-up gated)",
|
||||
description:
|
||||
"Requires a fresh second-factor step-up (cookie session) AND a current TOTP or recovery code. Clears the secret and deletes recovery codes. Bearer can never satisfy the step-up gate.",
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: mfaDisableSchema } },
|
||||
},
|
||||
responses: {
|
||||
"200": {
|
||||
description: "Factor disabled.",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: dataEnvelope(mfaToggleResponse, "MfaDisableEnvelope"),
|
||||
},
|
||||
},
|
||||
},
|
||||
...stdResponses,
|
||||
},
|
||||
},
|
||||
},
|
||||
"/api/auth/me/mfa/recovery-codes/regenerate": {
|
||||
post: {
|
||||
tags: ["Auth"],
|
||||
summary: "Regenerate recovery codes (step-up gated)",
|
||||
description:
|
||||
"Invalidates the entire prior recovery-code set and returns a fresh batch once. Step-up gated; Bearer can never satisfy the gate.",
|
||||
responses: {
|
||||
"200": {
|
||||
description: "Fresh recovery codes issued.",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: dataEnvelope(
|
||||
recoveryCodesResponse,
|
||||
"MfaRecoveryRegenEnvelope",
|
||||
),
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
/**
|
||||
* Request schemas for the second-factor (MFA) surface. Single-sourced here so
|
||||
* the runtime `safeParse` and the OpenAPI registry (`src/lib/openapi/routes/
|
||||
* auth.ts`) describe the identical wire contract.
|
||||
*/
|
||||
import { z } from "zod/v4";
|
||||
|
||||
/** A 6-digit TOTP code. */
|
||||
export const totpCodeSchema = z
|
||||
.string()
|
||||
.trim()
|
||||
.regex(/^\d{6}$/, "Enter the 6-digit code from your authenticator app");
|
||||
|
||||
/**
|
||||
* A recovery code as displayed (`XXXXX-XXXXX`) — accepted case-insensitively
|
||||
* with or without the separator; the server normalises before comparing.
|
||||
*/
|
||||
export const recoveryCodeSchema = z.string().trim().min(8).max(32);
|
||||
|
||||
export const totpConfirmSchema = z.object({
|
||||
code: totpCodeSchema,
|
||||
});
|
||||
|
||||
/** Disable MFA: prove possession of a current factor (TOTP or recovery code). */
|
||||
export const mfaDisableSchema = z
|
||||
.object({
|
||||
code: z.string().trim().min(6).max(32),
|
||||
method: z.enum(["totp", "recovery"]).default("totp"),
|
||||
})
|
||||
.meta({
|
||||
id: "MfaDisableRequest",
|
||||
description:
|
||||
"Disable the second factor. Requires fresh step-up plus a current TOTP or recovery code.",
|
||||
});
|
||||
|
||||
/** Login second-factor completion: ticket + a TOTP or recovery code. */
|
||||
export const mfaVerifySchema = z
|
||||
.object({
|
||||
mfaTicket: z
|
||||
.string()
|
||||
.min(1)
|
||||
.describe("The opaque single-use ticket from the login response."),
|
||||
method: z.enum(["totp", "recovery"]).default("totp"),
|
||||
code: z.string().trim().min(6).max(32),
|
||||
})
|
||||
.meta({
|
||||
id: "MfaVerifyRequest",
|
||||
description:
|
||||
"Complete a second-factor login challenge and receive the same token bundle the password path issues.",
|
||||
});
|
||||
Reference in new issue
Block a user