feat(claim): hand over a managed profile through single sign-on

POST /api/auth/claim/sso checks the handover link and the username and seals
the link id, the username and a per-start binding into an hl_claim cookie.
GET /api/auth/oidc/login?intent=claim carries the binding into the encrypted
OIDC state, and the callback binds the provider subject to the profile in the
claim transaction, refusing a subject or verified email another account
holds, a link that is no longer usable, and a live session.

The handover status and the claim preview name the redemption methods; a
single-sign-on-only server hands over through the identity provider, and only
the password claim stays refused there.
This commit is contained in:
Marc-André Bombeck committed 2026-10-15 23:12:59 +02:00
1 parent 5dab12472f
commit 9eae352bb1
20 files changed
+1075 -208

No files matched your search

+174 -12
View File
@@ -5,7 +5,11 @@
* (`tests/integration/managed-profile-handover.test.ts`); here the order of
* the refusals is pinned, because each one is a security property:
*
* - single sign-on only refuses before anything else;
* - single sign-on only refuses the PASSWORD claim before anything else,
* while the preview answers there and names `sso` as the way in (v1.43);
* - the single-sign-on start needs a configured provider, refuses a live
* session before the rate limit, checks the link before the username,
* and seals the link's id (never the token) into `hl_claim`;
* - a live session is refused BEFORE the rate limit (a state, not an
* attempt), and before any token is read;
* - the rate limit runs before the body is parsed;
@@ -24,7 +28,18 @@ vi.mock("@/lib/auth/session", () => ({
createSession: vi.fn(),
getSession: vi.fn(),
}));
vi.mock("@/lib/auth/oidc", () => ({ isOidcOnly: vi.fn() }));
vi.mock("@/lib/auth/oidc", () => ({
isOidcOnly: vi.fn(),
isOidcConfigured: vi.fn(),
getOidcConfig: vi.fn(),
}));
vi.mock("@/lib/crypto", () => ({
encrypt: vi.fn((s: string) => `sealed(${s})`),
decrypt: vi.fn(),
}));
vi.mock("@/lib/auth/secure-cookie", () => ({
shouldEmitSecureCookie: () => true,
}));
vi.mock("@/lib/rate-limit", () => ({
checkRateLimit: vi.fn(),
checkAuthSurfaceRateLimit: vi.fn(),
@@ -49,6 +64,7 @@ vi.mock("@/lib/managed-profiles/handover", async () => {
return {
HandoverError: actual.HandoverError,
previewHandover: vi.fn(),
usableHandoverForToken: vi.fn(),
claimManagedProfile: vi.fn(),
};
});
@@ -67,9 +83,11 @@ vi.mock("next/headers", () => ({
import { POST as claim } from "../route";
import { POST as preview } from "../preview/route";
import { POST as claimSso } from "../sso/route";
import { prisma } from "@/lib/db";
import { createSession, getSession } from "@/lib/auth/session";
import { isOidcOnly } from "@/lib/auth/oidc";
import { getOidcConfig, isOidcConfigured, isOidcOnly } from "@/lib/auth/oidc";
import { auditLog } from "@/lib/auth/audit";
import { checkAuthSurfaceRateLimit } from "@/lib/rate-limit";
import { checkPasswordStrength, hashPassword } from "@/lib/auth/password";
import { checkPasswordBreachIfEnabled } from "@/lib/password-breach-check";
@@ -77,6 +95,7 @@ import {
claimManagedProfile,
HandoverError,
previewHandover,
usableHandoverForToken,
} from "@/lib/managed-profiles/handover";
import { notifyGuardiansOfHandover } from "@/lib/managed-profiles/handover-notify";
@@ -105,6 +124,12 @@ const PREVIEW = {
beforeEach(() => {
vi.resetAllMocks();
vi.mocked(isOidcOnly).mockReturnValue(false);
vi.mocked(isOidcConfigured).mockReturnValue(false);
vi.mocked(getOidcConfig).mockReturnValue(null);
vi.mocked(usableHandoverForToken).mockResolvedValue({
handoverId: "h1",
profileId: "p1",
});
vi.mocked(getSession).mockResolvedValue(null as never);
vi.mocked(checkAuthSurfaceRateLimit).mockResolvedValue({
allowed: true,
@@ -131,19 +156,62 @@ async function errorCode(res: Response): Promise<unknown> {
return body.meta?.errorCode;
}
const OIDC_CONFIG = {
issuerUrl: "https://idp.example.test",
clientId: "c",
clientSecret: "s",
scopes: "openid email",
buttonLabel: "Example ID",
};
function singleSignOnOnly(): void {
vi.mocked(isOidcOnly).mockReturnValue(true);
vi.mocked(isOidcConfigured).mockReturnValue(true);
vi.mocked(getOidcConfig).mockReturnValue(OIDC_CONFIG);
}
describe("on a single-sign-on-only instance", () => {
it("refuses the password claim before anything else", async () => {
singleSignOnOnly();
vi.mocked(getSession).mockResolvedValue({ user: { id: "u1" } } as never);
const res = await claim(post("/api/auth/claim", BODY));
expect(res.status).toBe(403);
expect(await errorCode(res)).toBe("profile_claim.oidc_only_unsupported");
expect(previewHandover).not.toHaveBeenCalled();
});
it("answers the preview and names single sign-on as the only way in", async () => {
singleSignOnOnly();
const res = await preview(
post("/api/auth/claim/preview", { token: TOKEN }),
);
expect(res.status).toBe(200);
const body = (await res.json()) as { data: Record<string, unknown> };
expect(body.data.methods).toEqual(["sso"]);
expect(body.data.ssoProviderName).toBe("Example ID");
});
});
describe.each([
["claim", claim, "/api/auth/claim", BODY],
["preview", preview, "/api/auth/claim/preview", { token: TOKEN }],
["sso", claimSso, "/api/auth/claim/sso", { token: TOKEN, username: "alex" }],
] as const)(
"POST %s — refusals that read no token",
(_n, route, path, body) => {
it("refuses on a single-sign-on-only instance before anything else", async () => {
vi.mocked(isOidcOnly).mockReturnValue(true);
vi.mocked(getSession).mockResolvedValue({ user: { id: "u1" } } as never);
const res = await route(post(path, body));
expect(res.status).toBe(403);
expect(await errorCode(res)).toBe("profile_claim.oidc_only_unsupported");
expect(previewHandover).not.toHaveBeenCalled();
(name, route, path, body) => {
beforeEach(() => {
if (name === "sso") {
vi.mocked(isOidcConfigured).mockReturnValue(true);
vi.mocked(getOidcConfig).mockReturnValue(OIDC_CONFIG);
}
if (name === "sso") {
vi.mocked(usableHandoverForToken).mockImplementation(async () => {
// Routes the sso start through the same "link" spy the other two
// use, so one set of assertions covers all three.
const found = await previewHandover(TOKEN);
return found ? { handoverId: "h1", profileId: "p1" } : null;
});
}
});
it("refuses over a live session before spending the rate limit", async () => {
@@ -234,7 +302,7 @@ describe("POST /api/auth/claim", () => {
expect(res.status).toBe(201);
expect(claimManagedProfile).toHaveBeenCalledWith(
expect.objectContaining({
rawToken: TOKEN,
link: { rawToken: TOKEN },
username: "alex",
email: "alex@example.test",
passwordHash: "argon2-hash",
@@ -260,7 +328,101 @@ describe("POST /api/auth/claim/preview", () => {
"displayName",
"expiresAt",
"guardians",
"methods",
"ssoProviderName",
]);
expect(body.data.methods).toEqual(["password"]);
expect(body.data.ssoProviderName).toBeNull();
expect(body.data.expiresAt).toBe("2030-01-01T00:00:00.000Z");
});
});
describe("POST /api/auth/claim/sso", () => {
const SSO_BODY = { token: TOKEN, username: "alex" };
beforeEach(() => {
vi.mocked(isOidcConfigured).mockReturnValue(true);
vi.mocked(getOidcConfig).mockReturnValue(OIDC_CONFIG);
});
it("answers 404 sso_unavailable without an identity provider, before anything else", async () => {
vi.mocked(isOidcConfigured).mockReturnValue(false);
vi.mocked(getSession).mockResolvedValue({ user: { id: "u1" } } as never);
const res = await claimSso(post("/api/auth/claim/sso", SSO_BODY));
expect(res.status).toBe(404);
expect(await errorCode(res)).toBe("profile_claim.sso_unavailable");
expect(checkAuthSurfaceRateLimit).not.toHaveBeenCalled();
expect(usableHandoverForToken).not.toHaveBeenCalled();
});
it("works on a single-sign-on-only instance", async () => {
singleSignOnOnly();
const res = await claimSso(post("/api/auth/claim/sso", SSO_BODY));
expect(res.status).toBe(200);
});
it("draws on the password claim's bucket", async () => {
await claimSso(post("/api/auth/claim/sso", SSO_BODY));
expect(checkAuthSurfaceRateLimit).toHaveBeenCalledWith(
expect.anything(),
"auth:claim",
5,
15 * 60 * 1000,
);
});
it("checks the link before the username probe", async () => {
vi.mocked(usableHandoverForToken).mockResolvedValue(null);
vi.mocked(prisma.user.findUnique).mockResolvedValue({ id: "x" } as never);
const res = await claimSso(post("/api/auth/claim/sso", SSO_BODY));
expect(res.status).toBe(404);
expect(await errorCode(res)).toBe("profile_claim.invalid");
expect(prisma.user.findUnique).not.toHaveBeenCalled();
expect(res.headers.get("set-cookie")).toBeNull();
});
it("answers 409 taken for a username in use, and sets no cookie", async () => {
vi.mocked(prisma.user.findUnique).mockResolvedValue({ id: "x" } as never);
const res = await claimSso(post("/api/auth/claim/sso", SSO_BODY));
expect(res.status).toBe(409);
expect(await errorCode(res)).toBe("profile_claim.taken");
expect(res.headers.get("set-cookie")).toBeNull();
});
it("refuses an unknown field and a managed- username (strict body)", async () => {
for (const body of [
{ ...SSO_BODY, email: "x@example.test" },
{ ...SSO_BODY, username: "managed-alex" },
]) {
const res = await claimSso(post("/api/auth/claim/sso", body));
expect(res.status).toBe(422);
}
expect(usableHandoverForToken).not.toHaveBeenCalled();
});
it("seals the link's id and the username, never the token, into hl_claim", async () => {
const res = await claimSso(post("/api/auth/claim/sso", SSO_BODY));
expect(res.status).toBe(200);
expect((await res.json()).data).toEqual({
redirectTo: "/api/auth/oidc/login?intent=claim",
});
const cookie = res.headers.get("set-cookie") ?? "";
expect(cookie).toMatch(/^hl_claim=/);
expect(cookie).toMatch(/Path=\/api\/auth\/oidc/);
expect(cookie).toMatch(/HttpOnly/i);
expect(cookie).toMatch(/Secure/i);
expect(cookie).toMatch(/SameSite=lax/i);
expect(cookie).toMatch(/Max-Age=600/);
const sealed = decodeURIComponent(cookie.split(";")[0]!.slice(9));
const payload = JSON.parse(sealed.replace(/^sealed\(/, "").slice(0, -1));
expect(payload.h).toBe("h1");
expect(payload.u).toBe("alex");
expect(typeof payload.b).toBe("string");
expect(cookie).not.toContain(TOKEN);
expect(JSON.stringify(vi.mocked(auditLog).mock.calls)).not.toContain(TOKEN);
expect(auditLog).toHaveBeenCalledWith(
"managed_profile.claim_sso.started",
expect.objectContaining({ userId: "p1", details: { handoverId: "h1" } }),
);
});
});
+12 -1
View File
@@ -4,6 +4,8 @@
* access (v1.42, #959). No health data.
*
* Anonymous by design: the person opening the link has no credentials yet.
* Answered on a single-sign-on-only server too (v1.43): `methods` then names
* only `sso`, and the page offers the identity provider.
* The one-time `hlp_` token travels in the BODY, never in this request's URL,
* so it never reaches an access log or a wide event's `http.path`. Every
* unusable link — malformed, unknown, expired, used, withdrawn, a profile no
@@ -15,7 +17,12 @@ import { apiHandler } from "@/lib/api-handler";
import { apiSuccess, returnAllZodIssues, safeJson } from "@/lib/api-response";
import { getSession } from "@/lib/auth/session";
import { annotate } from "@/lib/logging/context";
import { claimGate, claimInvalid } from "@/lib/managed-profiles/claim-gate";
import {
claimGate,
claimInvalid,
handoverMethods,
ssoProviderName,
} from "@/lib/managed-profiles/claim-gate";
import { previewHandover } from "@/lib/managed-profiles/handover";
import { claimPreviewSchema } from "@/lib/validations/managed-profile-handover";
@@ -46,5 +53,9 @@ export const POST = apiHandler(async (request: NextRequest) => {
displayName: preview.displayName,
expiresAt: preview.expiresAt.toISOString(),
guardians: preview.guardians,
// v1.43 (#959) — which ways in this server offers, so the page shows the
// password form, the provider button, or both.
methods: handoverMethods(),
ssoProviderName: ssoProviderName(),
});
});
+1 -1
View File
@@ -104,7 +104,7 @@ export const POST = apiHandler(async (request: NextRequest) => {
let claimed;
try {
claimed = await claimManagedProfile({
rawToken: token,
link: { rawToken: token },
username,
email,
passwordHash,
+69 -14
View File
@@ -1,29 +1,47 @@
/**
* `POST /api/auth/claim/sso` — start claiming a managed profile through
* single sign-on (#959).
* single sign-on (v1.43, #959).
*
* Anonymous, like the password claim beside it. `{ token, username }`: the
* link is checked and the username reserved for the round trip, a sealed
* `hl_claim` cookie (10 minutes, `httpOnly`, `Secure` through
* `shouldEmitSecureCookie()`) carries `{ handoverId, username, exp }`, and the
* answer names where to go: `{ redirectTo: "/api/auth/oidc/login?intent=claim" }`.
* The OIDC callback binds the identity provider's subject to the profile. The
* token never rides a URL. Works on a single-sign-on-only server; 404
* `profile_claim.sso_unavailable` when no identity provider is configured.
* Anonymous, like the password claim beside it, and ordered like it:
*
* 1. refusals that read no token (`claimGate`: no identity provider, a live
* session, the per-address bucket the password claim also draws on);
* 2. the body, strictly parsed, and the link checked;
* 3. the username probe, so the person learns a name is taken here rather
* than after the round trip to the provider.
*
* Nothing about the account changes here. The answer is a sealed `hl_claim`
* cookie (`claim-cookie.ts`) naming the link by its id and carrying the
* chosen username, and `{ redirectTo }` for the browser to navigate to. The
* OIDC callback binds the provider's subject to the profile, under the lock,
* with every check repeated. The token never rides a URL and never reaches the
* cookie.
*/
import { NextRequest } from "next/server";
import { apiHandler } from "@/lib/api-handler";
import { returnAllZodIssues, safeJson } from "@/lib/api-response";
import {
apiError,
apiSuccess,
returnAllZodIssues,
safeJson,
} from "@/lib/api-response";
import { auditLog } from "@/lib/auth/audit";
import { getSession } from "@/lib/auth/session";
import { notImplemented } from "@/lib/http/not-implemented";
import { claimGate } from "@/lib/managed-profiles/claim-gate";
import { prisma } from "@/lib/db";
import { annotate } from "@/lib/logging/context";
import {
CLAIM_SSO_REDIRECT,
setClaimCookie,
} from "@/lib/managed-profiles/claim-cookie";
import { claimGate, claimInvalid } from "@/lib/managed-profiles/claim-gate";
import { usableHandoverForToken } from "@/lib/managed-profiles/handover";
import { claimSsoSchema } from "@/lib/validations/claim-sso";
export const POST = apiHandler(async (request: NextRequest) => {
// Refuses a signed-in caller and rate-limits the address, as the password
// claim does.
const gate = await claimGate(request, "claim", (await getSession()) !== null);
const gate = await claimGate(request, "sso", (await getSession()) !== null);
if (gate.refusal) return gate.refusal;
const { data: body, error: jsonError } = await safeJson(request, {
@@ -32,6 +50,43 @@ export const POST = apiHandler(async (request: NextRequest) => {
if (jsonError) return jsonError;
const parsed = claimSsoSchema.safeParse(body);
if (!parsed.success) return returnAllZodIssues(parsed.error, 422);
const { token, username } = parsed.data;
return notImplemented("profile_claim.sso.start");
// The link first, so the username probe below is no oracle for anybody
// without a live link (the password claim's argument).
const link = await usableHandoverForToken(token);
if (!link) {
annotate({
action: { name: "profile_claim.sso.start" },
meta: { found: false },
});
return claimInvalid();
}
const existing = await prisma.user.findUnique({
where: { username },
select: { id: true },
});
if (existing) {
return apiError("Username already taken", 409, {
errorCode: "profile_claim.taken",
});
}
const response = apiSuccess({ redirectTo: CLAIM_SSO_REDIRECT });
setClaimCookie(response, { handoverId: link.handoverId, username });
// Filed under the record, with no actor: nobody is signed in yet. No token,
// no username — the username is not the person's until the claim lands.
await auditLog("managed_profile.claim_sso.started", {
userId: link.profileId,
actorUserId: null,
ipAddress: gate.ip,
details: { handoverId: link.handoverId },
});
annotate({
action: { name: "profile_claim.sso.start" },
meta: { found: true },
});
return response;
});