refactor(auth): move the SSO callback's account resolution and sign-in endings out of its route

This commit is contained in:
Marc-André Bombeck committed 2026-10-23 15:17:27 +02:00
1 parent d76497ec13
commit af5cf1ace2
7 files changed
+475 -334

No files matched your search

@@ -0,0 +1,116 @@
/**
* The three ways an SSO sign-in ends once its account is known
* (`GET /api/auth/oidc/callback`): this app's own second factor, a native
* handoff code, or a web session. The callback turns each into its
* redirect.
*/
import { prisma } from "@/lib/db";
import type { User } from "@/generated/prisma/client";
import { annotate } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import { createSession } from "@/lib/auth/session";
import { recordSignInDevice } from "@/lib/auth/login-alert";
import { createMfaChallenge } from "@/lib/auth/mfa/challenge";
import { syncMfaEnrollCookie } from "@/lib/auth/mfa-enrollment";
import { mintNativeHandoff } from "@/lib/auth/oidc-native-handoff";
export type MfaMethod = "totp" | "recovery" | "webauthn";
/**
* OIDC is a DELEGATED factor: it proves the IdP authenticated someone, but it
* never substitutes for this app's own second factor. An account with a
* confirmed TOTP secret or a registered security key gets the same MFA
* challenge step password login gets: no session is minted, and the
* single-use ticket goes to the login page (web) or the custom scheme
* (native), which render the same challenge UI and complete at
* `/api/auth/mfa/verify`. (The trusted-device skip cannot apply on this
* path: its cookie is SameSite=Strict, which the browser withholds on an
* IdP-initiated redirect chain.)
*
* Answers the challenge, or null when the account has no second factor.
*/
export async function startOidcSecondFactor(
user: User,
ip: string,
native: boolean,
): Promise<{ ticket: string; methods: MfaMethod[] } | null> {
const hasTotp = Boolean(user.totpConfirmedAt);
const webauthnKeyCount = await prisma.webauthnMfaCredential.count({
where: { userId: user.id },
});
const hasWebauthn = webauthnKeyCount > 0;
if (!hasTotp && !hasWebauthn) return null;
const challenge = await createMfaChallenge(user.id, "login");
const methods: MfaMethod[] = [];
if (hasTotp) methods.push("totp", "recovery");
if (hasWebauthn) methods.push("webauthn");
await auditLog("auth.mfa.challenge", {
userId: user.id,
ipAddress: ip,
details: { source: native ? "login.oidc.native" : "login.oidc" },
});
annotate({
action: { name: "auth.mfa.challenge" },
meta: { mfa_required: true },
});
return { ticket: challenge.ticket, methods };
}
/**
* Native, no MFA: a one-time handoff code for the app. NO session and NO
* cookie are minted here: the app exchanges the code at
* `POST /api/auth/oidc/native/token` for the native bundle. The app's S256
* challenge (bound at login, tamper-authenticated in the state blob) locks
* the code to the app instance that started the flow. The session and
* device are recorded at the exchange via `finishLogin`, not here.
*/
export async function mintOidcNativeHandoff(input: {
userId: string;
appCodeChallenge: string;
ip: string;
userAgent: string | null;
}): Promise<string> {
const { code } = await mintNativeHandoff({
userId: input.userId,
appCodeChallenge: input.appCodeChallenge,
ipAddress: input.ip,
userAgent: input.userAgent,
});
await auditLog("auth.oidc.native.handoff_minted", {
userId: input.userId,
ipAddress: input.ip,
});
annotate({ action: { name: "auth.oidc.native.handoff_minted" } });
return code;
}
/** A web sign-in without a second factor: the session and its ledger row. */
export async function openOidcSession(
user: User,
ip: string,
userAgent: string | null,
): Promise<void> {
// Parity with password login: the admin-enforced-MFA hint cookie sends a
// single-factor account into forced enrollment after sign-in.
await syncMfaEnrollCookie(user.id, {
totpConfirmedAt: user.totpConfirmedAt,
mfaEnforced: user.mfaEnforced,
});
// The 5th argument stays null: OIDC is a delegated factor, so an SSO
// session must never satisfy `requireFreshMfa` step-up (MFA disable,
// encryption-key rotation, encrypted export, account deletion), the same
// treatment a trusted-device login gets.
await createSession(
user.id,
user.onboardingCompletedAt === null,
ip,
userAgent,
null,
);
void recordSignInDevice({ userId: user.id, ip, userAgent });
await auditLog("auth.oidc.login", { userId: user.id, ipAddress: ip });
}
@@ -0,0 +1,202 @@
/**
* Which account an SSO sign-in belongs to (`GET /api/auth/oidc/callback`),
* once the provider has authenticated a subject.
*
* 1. The durable identity match: the (issuer, sub) pair stamped on a
* previous login, link or provision.
* 2. An account that already holds the verified email: never linked on the
* email alone. Pinned to another identity it is a conflict; otherwise
* the link waits for the account's own credential.
* 3. Nobody: provision, while registration is open.
*
* A refusal names the reason the callback redirects with.
*/
import { prisma } from "@/lib/db";
import type { User } from "@/generated/prisma/client";
import { annotate } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import { deriveUniqueUsername } from "@/lib/auth/oidc";
import { resolveServerDefaultTimezone } from "@/lib/tz/resolver";
export type OidcAccountResolution =
| { kind: "user"; user: User }
| { kind: "refused"; reason: string }
| { kind: "linkPending"; userId: string };
/** A refusal; the reason is the `?error=` the callback redirects with. */
function refuse(reason: string): OidcAccountResolution {
return { kind: "refused", reason };
}
interface OidcSubject {
issuer: string;
sub: string;
email: string | null;
emailVerified: boolean | undefined;
ip: string;
}
/**
* Refresh the display email only, and only from a claim the IdP explicitly
* marks verified. Skipped when another account already holds the address
* (`email` is unique); the login itself proceeds either way, keyed by
* (issuer, sub). Email is deliberately NOT consulted for the match: after
* the stamp it is a display field, so an IdP-side email change can refresh
* it but can never re-point the login at a different account.
*/
async function refreshDisplayEmail(
user: User,
subject: OidcSubject,
): Promise<User> {
const displayEmail = subject.email ? subject.email.toLowerCase() : null;
if (
!displayEmail ||
subject.emailVerified !== true ||
user.email?.toLowerCase() === displayEmail
) {
return user;
}
const emailTaken = await prisma.user.findFirst({
where: {
email: { equals: displayEmail, mode: "insensitive" },
NOT: { id: user.id },
},
select: { id: true },
});
if (emailTaken) return user;
return prisma.user.update({
where: { id: user.id },
data: { email: displayEmail },
});
}
async function registrationOpen(): Promise<boolean> {
const userCount = await prisma.user.count();
try {
const settings = await prisma.appSettings.findUnique({
where: { id: "singleton" },
});
if (settings && !settings.registrationEnabled && userCount > 0) {
return false;
}
} catch {
// Table may not exist yet; allow provisioning (matches register/route.ts).
}
return true;
}
/**
* The first provisioned user becomes ADMIN. Deriving that role from an early
* count and then creating without coordination is the check-then-act race
* the password-register route closed: two concurrent first logins racing the
* empty-DB window would both observe `0` and both be minted ADMIN. The
* count+insert is serialised behind a transaction-scoped advisory lock
* (released on commit/rollback) and re-counted *inside* the lock, so the
* second provision observes the first's committed row and is minted USER.
* The lock key STRING matches the register route's: an OIDC first login
* racing a password first registration is serialised against the same lock,
* so only one ADMIN can ever be minted.
*/
async function provision(
subject: OidcSubject & { email: string },
): Promise<User> {
const username = await deriveUniqueUsername(subject.email, (candidate) =>
prisma.user
.findUnique({ where: { username: candidate } })
.then((u: unknown) => u !== null),
);
// Same server-default resolution the register route uses: an
// SSO-provisioned account has no registration form to carry the
// browser-detected timezone.
const timezone = await resolveServerDefaultTimezone();
const user = await prisma.$transaction(async (tx) => {
// `pg_advisory_xact_lock` returns void, which the client cannot
// deserialize as a column; selecting FROM it yields a plain int row.
await tx.$queryRaw`
SELECT 1 AS locked
FROM pg_advisory_xact_lock(hashtextextended('register:first-admin', 0))
`;
const priorUsers = await tx.user.count();
const role = priorUsers === 0 ? "ADMIN" : "USER";
return tx.user.create({
data: {
email: subject.email.toLowerCase(),
username,
passwordHash: null,
role,
timezone,
oidcIssuer: subject.issuer,
oidcSub: subject.sub,
},
});
});
await auditLog("auth.oidc.provisioned", {
userId: user.id,
ipAddress: subject.ip,
});
return user;
}
export async function resolveOidcAccount(
subject: OidcSubject,
): Promise<OidcAccountResolution> {
// (1) Durable identity match.
const stamped = await prisma.user.findFirst({
where: { oidcIssuer: subject.issuer, oidcSub: subject.sub },
});
if (stamped) {
return { kind: "user", user: await refreshDisplayEmail(stamped, subject) };
}
// No stamped identity yet: both remaining paths (link-once, provision)
// bind this (issuer, sub) to an account keyed by email, so the claim must
// be explicitly `email_verified: true`. An ABSENT claim is a reject, not a
// benefit of the doubt: an IdP that does not assert verification cannot
// anchor a link that later gates a health record.
const email = subject.email;
if (!email) {
annotate({ meta: { reason: "no_email" } });
return refuse("oidc_no_email");
}
if (subject.emailVerified !== true) {
annotate({ meta: { reason: "email_unverified" } });
return refuse("oidc_email_unverified");
}
const byEmail = await prisma.user.findFirst({
where: { email: { equals: email, mode: "insensitive" } },
});
if (byEmail) {
// (2) Link ONCE. An account already pinned to a different IdP identity
// is never silently re-bound: a rebind would let a second IdP identity
// that acquires the same email capture the account. Audited so the
// operator can see the collision.
if (byEmail.oidcIssuer !== null || byEmail.oidcSub !== null) {
await auditLog("auth.oidc.link_conflict", {
userId: byEmail.id,
ipAddress: subject.ip,
});
annotate({ meta: { reason: "identity_conflict" } });
return refuse("oidc_identity_conflict");
}
// (2b) Never link on the email alone. The local address was never
// verified (anyone can register with it or type it into a profile), so
// matching it proves nothing about who owns the account. Record the link
// this login would make; the callback sends the browser to sign in to
// the account with its own credential, and the link is made there
// (`completePendingOidcLink`), and only for this account.
await auditLog("auth.oidc.link_pending", {
userId: byEmail.id,
ipAddress: subject.ip,
});
annotate({ meta: { reason: "link_confirmation_required" } });
return { kind: "linkPending", userId: byEmail.id };
}
// (3) Provision.
if (!(await registrationOpen())) {
annotate({ meta: { reason: "registration_disabled" } });
return refuse("oidc_registration_disabled");
}
return { kind: "user", user: await provision({ ...subject, email }) };
}
+102
View File
@@ -0,0 +1,102 @@
/**
* The single-use state blob of an SSO sign-in, as the callback reads it back
* (`GET /api/auth/oidc/callback`), and the provider error codes it may name
* in its wide event.
*/
import { decrypt } from "@/lib/crypto";
export interface StoredOidcState {
state: string;
nonce: string;
codeVerifier: string;
next: string;
/**
* Set only when the login GET carried `client=native`. When true the
* callback mints a handoff code (or MFA ticket) and redirects to the custom
* scheme instead of minting a session. Both fields live ONLY inside the
* AES-256-GCM blob, so they are tamper-authenticated: a network attacker or
* the IdP cannot flip a web login into a native one or swap the app
* challenge.
*/
native?: boolean;
/** The app's S256 PKCE challenge, bound at login; verified at the exchange. */
appCodeChallenge?: string;
/**
* Set only when the login carried `intent=claim` and a valid `hl_claim`
* cookie (#959). The callback then claims the managed profile the cookie
* names instead of signing in, and only when the cookie still carries this
* exact binding. Web only: never together with `native`.
*/
intent?: "claim";
claimBinding?: string;
}
function isStoredOidcState(value: unknown): value is StoredOidcState {
const v = value as Record<string, unknown>;
if (
typeof value !== "object" ||
value === null ||
typeof v.state !== "string" ||
typeof v.nonce !== "string" ||
typeof v.codeVerifier !== "string" ||
typeof v.next !== "string"
) {
return false;
}
// Optional native fields: when present they must be the right shape, and a
// native start MUST carry the challenge the exchange verifies against.
if (v.native !== undefined) {
if (v.native !== true) return false;
if (typeof v.appCodeChallenge !== "string") return false;
}
if (v.intent !== undefined) {
if (v.intent !== "claim") return false;
if (typeof v.claimBinding !== "string" || v.claimBinding.length === 0) {
return false;
}
if (v.native !== undefined) return false;
}
return true;
}
/** The decrypted blob, or null when it is missing, unreadable or malformed. */
export function readStoredOidcState(
rawCookie: string | undefined,
): StoredOidcState | null {
if (!rawCookie) return null;
try {
const parsed: unknown = JSON.parse(decrypt(rawCookie));
return isStoredOidcState(parsed) ? parsed : null;
} catch {
return null;
}
}
/**
* Closed set of RFC 6749 §4.1.2.1 / OIDC Core §3.1.2.6 authorization error
* codes. The wide-event meta only ever carries a member of this set (or
* "other"), never the raw, attacker-influenceable query value.
*/
const KNOWN_IDP_ERROR_CODES = new Set([
"access_denied",
"invalid_request",
"unauthorized_client",
"unsupported_response_type",
"invalid_scope",
"server_error",
"temporarily_unavailable",
"interaction_required",
"login_required",
"account_selection_required",
"consent_required",
"invalid_request_uri",
"invalid_request_object",
"request_not_supported",
"request_uri_not_supported",
"registration_not_supported",
]);
/** The provider's error code as the wide event may carry it. */
export function idpErrorCode(raw: string): string {
return KNOWN_IDP_ERROR_CODES.has(raw) ? raw : "other";
}