@simple-auth-kit/cli 1.0.0

package/registry/core/crypto.ts

@@ -0,0 +1,43 @@
+import argon2 from "argon2";
+import { createHash, randomBytes, timingSafeEqual as nodeTimingSafeEqual } from "node:crypto";
+
+const ARGON2ID_DEFAULTS: argon2.HashOptions = {
+  type: argon2.argon2id,
+  memoryCost: 19456, // ~19 MiB, OWASP minimum recommendation
+  timeCost: 2,
+  parallelism: 1,
+};
+
+export async function hashPassword(password: string, opts: argon2.HashOptions = {}): Promise<string> {
+  return argon2.hash(password, { ...ARGON2ID_DEFAULTS, ...opts });
+}
+
+export async function verifyPassword(hash: string, password: string): Promise<boolean> {
+  try {
+    return await argon2.verify(hash, password);
+  } catch {
+    return false;
+  }
+}
+
+export function timingSafeEqualString(a: string, b: string): boolean {
+  const aBuf = Buffer.from(a);
+  const bBuf = Buffer.from(b);
+  if (aBuf.length !== bBuf.length) {
+    // still run a comparison of equal length to avoid a length-based timing signal
+    nodeTimingSafeEqual(aBuf, aBuf);
+    return false;
+  }
+  return nodeTimingSafeEqual(aBuf, bBuf);
+}
+
+/** High-entropy opaque token for password-reset links and 2FA backup codes. */
+export function randomToken(bytes = 32): string {
+  return randomBytes(bytes).toString("hex");
+}
+
+// sha256, not argon2id: random high-entropy tokens have no offline-guessing risk, so lookups
+// can stay a plain indexed equality match instead of a per-row argon2.verify call.
+export function hashToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}

package/registry/core/oauth.ts

@@ -0,0 +1,159 @@
+// Generic OIDC social-login, plus one isolated helper (`signAppleClientSecret`) for Apple's
+// deviation from the standard flow: its "client secret" is a short-lived signed JWT, not a
+// static string.
+import { createRemoteJWKSet, importPKCS8, jwtVerify, SignJWT } from "jose";
+import { AuditEvent, OAuthExchangeError, OAuthProfileInvalidError } from "./types.js";
+
+export interface OAuthProviderDescriptor {
+  id: string;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  jwksUri: string;
+  issuer: string;
+  defaultScope: string;
+}
+
+export const GOOGLE_OIDC_PROVIDER: OAuthProviderDescriptor = {
+  id: "google",
+  authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+  tokenEndpoint: "https://oauth2.googleapis.com/token",
+  jwksUri: "https://www.googleapis.com/oauth2/v3/certs",
+  issuer: "https://accounts.google.com",
+  defaultScope: "openid email profile",
+};
+
+export const APPLE_OIDC_PROVIDER: OAuthProviderDescriptor = {
+  id: "apple",
+  authorizationEndpoint: "https://appleid.apple.com/auth/authorize",
+  tokenEndpoint: "https://appleid.apple.com/auth/token",
+  jwksUri: "https://appleid.apple.com/auth/keys",
+  issuer: "https://appleid.apple.com",
+  defaultScope: "openid email name",
+};
+
+export function buildAuthorizationUrl(
+  provider: OAuthProviderDescriptor,
+  opts: { clientId: string; redirectUri: string; state: string; scope?: string },
+): string {
+  const params = new URLSearchParams({
+    client_id: opts.clientId,
+    redirect_uri: opts.redirectUri,
+    response_type: "code",
+    scope: opts.scope ?? provider.defaultScope,
+    state: opts.state,
+  });
+  // Apple requires form_post whenever the scope can return name/email (only sent on first consent)
+  if (provider.id === "apple") params.set("response_mode", "form_post");
+  return `${provider.authorizationEndpoint}?${params.toString()}`;
+}
+
+export async function exchangeCodeForTokens(
+  provider: OAuthProviderDescriptor,
+  opts: { clientId: string; clientSecret: string; redirectUri: string; code: string },
+): Promise<{ idToken: string; accessToken: string }> {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: opts.code,
+    redirect_uri: opts.redirectUri,
+    client_id: opts.clientId,
+    client_secret: opts.clientSecret,
+  });
+  const response = await fetch(provider.tokenEndpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body,
+  });
+  if (!response.ok) throw new OAuthExchangeError(`token exchange failed with status ${response.status}`);
+
+  const json = (await response.json()) as { id_token?: string; access_token?: string };
+  if (!json.id_token) throw new OAuthExchangeError("provider response missing id_token");
+  return { idToken: json.id_token, accessToken: json.access_token ?? "" };
+}
+
+// Apple requires `client_secret` to be a JWT signed with an Apple-issued private key, not a
+// static string — call this before `exchangeCodeForTokens` for the `apple` provider only.
+export async function signAppleClientSecret(opts: {
+  teamId: string;
+  clientId: string;
+  keyId: string;
+  privateKeyPem: string;
+  ttlSeconds?: number;
+}): Promise<string> {
+  const key = await importPKCS8(opts.privateKeyPem, "ES256");
+  const now = Math.floor(Date.now() / 1000);
+  return new SignJWT({})
+    .setProtectedHeader({ alg: "ES256", kid: opts.keyId })
+    .setIssuer(opts.teamId)
+    .setSubject(opts.clientId)
+    .setAudience(APPLE_OIDC_PROVIDER.issuer)
+    .setIssuedAt(now)
+    .setExpirationTime(now + (opts.ttlSeconds ?? 5 * 60))
+    .sign(key);
+}
+
+export interface OAuthProfile {
+  providerAccountId: string;
+  email?: string;
+  emailVerified: boolean;
+}
+
+const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+
+/** Verifies the id_token's signature against the provider's live JWKS (cached per-provider by `jose`). */
+export async function verifyIdTokenAndExtractProfile(
+  provider: OAuthProviderDescriptor,
+  opts: { clientId: string; idToken: string },
+): Promise<OAuthProfile> {
+  let jwks = jwksCache.get(provider.jwksUri);
+  if (!jwks) {
+    jwks = createRemoteJWKSet(new URL(provider.jwksUri));
+    jwksCache.set(provider.jwksUri, jwks);
+  }
+
+  let payload;
+  try {
+    ({ payload } = await jwtVerify(opts.idToken, jwks, { issuer: provider.issuer, audience: opts.clientId }));
+  } catch {
+    throw new OAuthProfileInvalidError();
+  }
+  if (typeof payload.sub !== "string") throw new OAuthProfileInvalidError("missing sub claim");
+
+  return {
+    providerAccountId: payload.sub,
+    email: typeof payload.email === "string" ? payload.email : undefined,
+    emailVerified: payload.email_verified === true || payload.email_verified === "true",
+  };
+}
+
+export interface OAuthStoreDeps {
+  findAccountByProvider: (provider: string, providerAccountId: string) => Promise<{ userId: string } | null>;
+  linkAccount: (input: { userId: string; provider: string; providerAccountId: string; email?: string }) => Promise<void>;
+  findUserByVerifiedEmail: (email: string) => Promise<{ id: string } | null>;
+  createUserFromOAuth: (input: { email?: string }) => Promise<{ id: string }>;
+  appendAuditEvent?: (event: AuditEvent) => Promise<void>;
+}
+
+// Find-linked-account → else link-by-verified-email → else create-new-user. Only links by
+// email when the provider asserts `email_verified` — an unverified email isn't proof of
+// ownership.
+export async function completeOAuthLogin(
+  deps: OAuthStoreDeps,
+  input: { provider: string; profile: OAuthProfile },
+): Promise<{ userId: string; isNewUser: boolean }> {
+  const existing = await deps.findAccountByProvider(input.provider, input.profile.providerAccountId);
+  if (existing) return { userId: existing.userId, isNewUser: false };
+
+  const matchedByEmail =
+    input.profile.email && input.profile.emailVerified
+      ? await deps.findUserByVerifiedEmail(input.profile.email)
+      : null;
+
+  const userId = matchedByEmail
+    ? matchedByEmail.id
+    : (await deps.createUserFromOAuth({ email: input.profile.email })).id;
+  const isNewUser = !matchedByEmail;
+
+  await deps.linkAccount({ userId, provider: input.provider, providerAccountId: input.profile.providerAccountId, email: input.profile.email });
+  await deps.appendAuditEvent?.({ type: "oauth_account_linked", userId, provider: input.provider });
+  return { userId, isNewUser };
+}

package/registry/core/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@simple-auth-kit/core",
+  "private": true,
+  "version": "0.0.0",
+  "description": "Framework/ORM-free auth core: token issuance, session policy, crypto, rate limiting. Copied verbatim into every combo by the CLI — never installed as a dependency by consumers.",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "argon2": "^0.45.1",
+    "jose": "^6.2.8"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}

package/registry/core/password-reset.ts

@@ -0,0 +1,42 @@
+import { hashPassword, hashToken, randomToken } from "./crypto.js";
+import { AuditEvent, PasswordResetTokenInvalidError } from "./types.js";
+
+const RESET_TOKEN_TTL_SECONDS_DEFAULT = 60 * 60; // 1 hour
+
+export interface PasswordResetStoreDeps {
+  saveResetToken: (input: { userId: string; tokenHash: string; expiresAt: string }) => Promise<void>;
+  findValidResetToken: (tokenHash: string) => Promise<{ userId: string; expiresAt: string; consumedAt: string | null } | null>;
+  consumeResetToken: (tokenHash: string) => Promise<void>;
+  setPasswordHash: (userId: string, passwordHash: string) => Promise<void>;
+  appendAuditEvent?: (event: AuditEvent) => Promise<void>;
+}
+
+// Persists only the token's hash, never the raw value; returns the raw token so the caller
+// can email it — this module owns no mailer.
+export async function requestPasswordReset(
+  deps: PasswordResetStoreDeps,
+  userId: string,
+  opts: { ttlSeconds?: number } = {},
+): Promise<{ token: string }> {
+  const token = randomToken();
+  const expiresAt = new Date(Date.now() + (opts.ttlSeconds ?? RESET_TOKEN_TTL_SECONDS_DEFAULT) * 1000).toISOString();
+  await deps.saveResetToken({ userId, tokenHash: hashToken(token), expiresAt });
+  await deps.appendAuditEvent?.({ type: "password_reset_requested", userId });
+  return { token };
+}
+
+// Does not revoke existing sessions — callers should follow up with
+// `revokeAllSessionsForUser` from session-policy.ts.
+export async function resetPassword(deps: PasswordResetStoreDeps, token: string, newPassword: string): Promise<{ userId: string }> {
+  const tokenHash = hashToken(token);
+  const record = await deps.findValidResetToken(tokenHash);
+  if (!record || record.consumedAt || new Date(record.expiresAt).getTime() < Date.now()) {
+    throw new PasswordResetTokenInvalidError();
+  }
+
+  const passwordHash = await hashPassword(newPassword);
+  await deps.setPasswordHash(record.userId, passwordHash);
+  await deps.consumeResetToken(tokenHash);
+  await deps.appendAuditEvent?.({ type: "password_reset_completed", userId: record.userId });
+  return { userId: record.userId };
+}

package/registry/core/rate-limit.ts

@@ -0,0 +1,33 @@
+export type RateLimitScope = "login" | "refresh" | "signup" | "password-reset";
+
+export interface RateLimitDeps {
+  /** Increments the counter for `key` within the current window and returns the new count. */
+  increment: (key: string, windowMs: number) => Promise<number>;
+}
+
+export interface RateLimitOptions {
+  windowMs: number;
+  max: number;
+}
+
+const DEFAULTS: Record<RateLimitScope, RateLimitOptions> = {
+  login: { windowMs: 60_000, max: 5 },
+  refresh: { windowMs: 60_000, max: 20 },
+  signup: { windowMs: 60 * 60_000, max: 10 },
+  "password-reset": { windowMs: 60 * 60_000, max: 5 },
+};
+
+export function rateLimitKey(scope: RateLimitScope, identifier: string): string {
+  return `authrl:${scope}:${identifier}`;
+}
+
+export async function checkRateLimit(
+  deps: RateLimitDeps,
+  scope: RateLimitScope,
+  identifier: string,
+  opts: Partial<RateLimitOptions> = {},
+): Promise<{ allowed: boolean; remaining: number }> {
+  const { windowMs, max } = { ...DEFAULTS[scope], ...opts };
+  const count = await deps.increment(rateLimitKey(scope, identifier), windowMs);
+  return { allowed: count <= max, remaining: Math.max(0, max - count) };
+}

package/registry/core/rbac.ts

@@ -0,0 +1,4 @@
+// Additive only, no deny/override semantics: role-derived permissions union with direct grants.
+export function resolvePermissions(rolePermissionKeys: string[], directPermissionKeys: string[]): string[] {
+  return [...new Set([...rolePermissionKeys, ...directPermissionKeys])].sort();
+}

package/registry/core/session-policy.ts

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+import { AuditEvent, RefreshInvalidError, RefreshReuseDetectedError, RefreshTokenClaims, Revoker, SessionRecord } from "./types.js";
+
+export interface SessionStoreDeps {
+  findSession: (sessionId: string) => Promise<SessionRecord | null>;
+  saveSession: (session: SessionRecord) => Promise<void>;
+  /**
+   * The store, not core, decides `expiresAt` — it is the half of the system that knows the
+   * deployment's configured session lifetime. Core only enforces whatever it is handed back.
+   */
+  createSession: (input: { userId: string; userAgent?: string; ip?: string; provider?: string }) => Promise<SessionRecord>;
+  revokeAllByUser: (userId: string, revoker?: Revoker) => Promise<void>;
+  revokeAllByUserExcept: (userId: string, keepSessionId: string, revoker?: Revoker) => Promise<void>;
+  denylistJti: (jti: string, ttlSeconds: number) => Promise<void>;
+  isDenylisted: (jti: string) => Promise<boolean>;
+  appendAuditEvent?: (event: AuditEvent) => Promise<void>;
+}
+
+export async function createSession(
+  deps: SessionStoreDeps,
+  input: { userId: string; userAgent?: string; ip?: string; provider?: string },
+): Promise<SessionRecord> {
+  const session = await deps.createSession(input);
+  await deps.appendAuditEvent?.({ type: "session_created", sessionId: session.id, userId: session.userId });
+  return session;
+}
+
+// A stale/revoked token (sv mismatch) just fails; a jti mismatch on a still-valid session means
+// the token was already rotated away and this one is a replay — kill the whole session family.
+export async function rotateRefreshToken(
+  deps: SessionStoreDeps,
+  presented: RefreshTokenClaims,
+): Promise<{ session: SessionRecord; nextJti: string }> {
+  const session = await deps.findSession(presented.sessionId);
+  if (!session || session.revokedAt) throw new RefreshInvalidError();
+  // The session's own absolute lifetime, independent of any token's. Rotation is the only place a
+  // session can be extended, so checking it here is what stops an endlessly-rotated refresh token
+  // from outliving the session it belongs to.
+  if (new Date(session.expiresAt).getTime() <= Date.now()) throw new RefreshInvalidError("session expired");
+  if (session.sessionVersion !== presented.sv) throw new RefreshInvalidError("session version stale");
+
+  if (session.currentRefreshJti !== presented.jti) {
+    // No revoker: this is the system reacting to a replayed token, not a person acting.
+    await deps.revokeAllByUser(session.userId);
+    await deps.appendAuditEvent?.({ type: "refresh_reuse_detected", sessionId: session.id, userId: session.userId });
+    throw new RefreshReuseDetectedError();
+  }
+
+  const nextJti = randomUUID();
+  const updated: SessionRecord = { ...session, currentRefreshJti: nextJti };
+  await deps.saveSession(updated);
+  return { session: updated, nextJti };
+}
+
+export async function revokeSession(deps: SessionStoreDeps, sessionId: string, revoker?: Revoker): Promise<void> {
+  const session = await deps.findSession(sessionId);
+  if (!session) return;
+  const updated: SessionRecord = {
+    ...session,
+    sessionVersion: session.sessionVersion + 1,
+    revokedAt: new Date().toISOString(),
+    revokedBy: revoker?.userId,
+    revokedByIp: revoker?.ip,
+  };
+  await deps.saveSession(updated);
+  await deps.appendAuditEvent?.({ type: "session_revoked", sessionId: session.id, userId: session.userId });
+}
+
+export async function revokeAllSessionsForUser(deps: SessionStoreDeps, userId: string, revoker?: Revoker): Promise<void> {
+  await deps.revokeAllByUser(userId, revoker);
+  await deps.appendAuditEvent?.({ type: "all_sessions_revoked", userId });
+}
+
+export async function revokeOtherSessionsForUser(deps: SessionStoreDeps, userId: string, keepSessionId: string, revoker?: Revoker): Promise<void> {
+  await deps.revokeAllByUserExcept(userId, keepSessionId, revoker);
+  await deps.appendAuditEvent?.({ type: "other_sessions_revoked", userId, keepSessionId });
+}
+
+export async function revokeAccessToken(deps: SessionStoreDeps, jti: string, remainingTtlSeconds: number): Promise<void> {
+  await deps.denylistJti(jti, remainingTtlSeconds);
+}
+
+// Block revokes every session immediately, not just future logins; `revoker` is the
+// administrator, so the row says who ended it, not merely that it ended.
+export async function blockUser(deps: SessionStoreDeps, userId: string, revoker?: Revoker): Promise<void> {
+  await deps.revokeAllByUser(userId, revoker);
+  await deps.appendAuditEvent?.({ type: "user_blocked", userId });
+}
+
+// Same shape as blockUser but a distinct audit trail — deactivation is a routine administrative
+// toggle, not a security action, and the two are tracked independently (see the `isActive` /
+// `blocked` split on `User`). Reactivating, like unblocking, revokes nothing.
+export async function deactivateUser(deps: SessionStoreDeps, userId: string, revoker?: Revoker): Promise<void> {
+  await deps.revokeAllByUser(userId, revoker);
+  await deps.appendAuditEvent?.({ type: "user_deactivated", userId });
+}

package/registry/core/test/crypto.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { hashPassword, timingSafeEqualString, verifyPassword } from "../crypto.js";
+
+describe("crypto", () => {
+  it("hashes and verifies a correct password", async () => {
+    const hash = await hashPassword("correct-horse-battery-staple");
+    expect(hash.startsWith("$argon2id$")).toBe(true);
+    expect(await verifyPassword(hash, "correct-horse-battery-staple")).toBe(true);
+  });
+
+  it("rejects an incorrect password", async () => {
+    const hash = await hashPassword("correct-horse-battery-staple");
+    expect(await verifyPassword(hash, "wrong-password")).toBe(false);
+  });
+
+  it("does not throw on a malformed hash", async () => {
+    await expect(verifyPassword("not-a-real-hash", "anything")).resolves.toBe(false);
+  });
+
+  it("timingSafeEqualString matches equal strings and rejects different ones", () => {
+    expect(timingSafeEqualString("abc123", "abc123")).toBe(true);
+    expect(timingSafeEqualString("abc123", "abc124")).toBe(false);
+    expect(timingSafeEqualString("short", "muchlonger")).toBe(false);
+  });
+});

package/registry/core/test/oauth.test.ts

@@ -0,0 +1,213 @@
+import { exportJWK, exportPKCS8, generateKeyPair, jwtVerify, SignJWT } from "jose";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  APPLE_OIDC_PROVIDER,
+  buildAuthorizationUrl,
+  completeOAuthLogin,
+  exchangeCodeForTokens,
+  GOOGLE_OIDC_PROVIDER,
+  OAuthProviderDescriptor,
+  OAuthStoreDeps,
+  signAppleClientSecret,
+  verifyIdTokenAndExtractProfile,
+} from "../oauth.js";
+import { AuditEvent, OAuthExchangeError, OAuthProfileInvalidError } from "../types.js";
+
+describe("oauth: buildAuthorizationUrl", () => {
+  it("builds a standard authorization URL for google", () => {
+    const url = new URL(
+      buildAuthorizationUrl(GOOGLE_OIDC_PROVIDER, { clientId: "client-1", redirectUri: "https://app/cb", state: "state-1" }),
+    );
+    expect(url.origin + url.pathname).toBe("https://accounts.google.com/o/oauth2/v2/auth");
+    expect(url.searchParams.get("client_id")).toBe("client-1");
+    expect(url.searchParams.get("state")).toBe("state-1");
+    expect(url.searchParams.get("response_mode")).toBeNull();
+  });
+
+  it("adds response_mode=form_post for apple", () => {
+    const url = new URL(
+      buildAuthorizationUrl(APPLE_OIDC_PROVIDER, { clientId: "client-1", redirectUri: "https://app/cb", state: "state-1" }),
+    );
+    expect(url.searchParams.get("response_mode")).toBe("form_post");
+  });
+});
+
+describe("oauth: exchangeCodeForTokens", () => {
+  const fetchMock = vi.fn();
+  beforeEach(() => vi.stubGlobal("fetch", fetchMock));
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("returns the id_token and access_token from a successful exchange", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ id_token: "the-id-token", access_token: "the-access-token" }), { status: 200 }));
+
+    const result = await exchangeCodeForTokens(GOOGLE_OIDC_PROVIDER, {
+      clientId: "c",
+      clientSecret: "s",
+      redirectUri: "https://app/cb",
+      code: "auth-code",
+    });
+    expect(result).toEqual({ idToken: "the-id-token", accessToken: "the-access-token" });
+  });
+
+  it("throws OAuthExchangeError on a non-2xx response", async () => {
+    fetchMock.mockResolvedValue(new Response("bad request", { status: 400 }));
+    await expect(
+      exchangeCodeForTokens(GOOGLE_OIDC_PROVIDER, { clientId: "c", clientSecret: "s", redirectUri: "https://app/cb", code: "bad" }),
+    ).rejects.toBeInstanceOf(OAuthExchangeError);
+  });
+
+  it("throws OAuthExchangeError when the response has no id_token", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ access_token: "only-access" }), { status: 200 }));
+    await expect(
+      exchangeCodeForTokens(GOOGLE_OIDC_PROVIDER, { clientId: "c", clientSecret: "s", redirectUri: "https://app/cb", code: "x" }),
+    ).rejects.toBeInstanceOf(OAuthExchangeError);
+  });
+});
+
+describe("oauth: signAppleClientSecret", () => {
+  it("produces a JWT signed with the given ES256 key, with the right issuer/subject/audience", async () => {
+    const { privateKey, publicKey } = await generateKeyPair("ES256", { extractable: true });
+    const privateKeyPem = await exportPKCS8(privateKey);
+
+    const secret = await signAppleClientSecret({ teamId: "TEAM123", clientId: "com.example.app", keyId: "KEY456", privateKeyPem });
+
+    const { payload } = await jwtVerify(secret, publicKey, { algorithms: ["ES256"] });
+    expect(payload.iss).toBe("TEAM123");
+    expect(payload.sub).toBe("com.example.app");
+    expect(payload.aud).toBe(APPLE_OIDC_PROVIDER.issuer);
+  });
+});
+
+describe("oauth: verifyIdTokenAndExtractProfile", () => {
+  const fetchMock = vi.fn();
+  beforeEach(() => vi.stubGlobal("fetch", fetchMock));
+  afterEach(() => vi.unstubAllGlobals());
+
+  async function fakeProvider(jwksUri: string): Promise<{ provider: OAuthProviderDescriptor; sign: (claims: Record<string, unknown>) => Promise<string> }> {
+    const { privateKey, publicKey } = await generateKeyPair("RS256", { extractable: true });
+    const jwk = await exportJWK(publicKey);
+    fetchMock.mockImplementation(async (input: string | URL) => {
+      if (String(input) === jwksUri) return new Response(JSON.stringify({ keys: [{ ...jwk, kid: "test-kid", alg: "RS256", use: "sig" }] }));
+      throw new Error(`unexpected fetch: ${input}`);
+    });
+
+    const provider: OAuthProviderDescriptor = { ...GOOGLE_OIDC_PROVIDER, jwksUri, issuer: "https://issuer.example" };
+    const sign = (claims: Record<string, unknown>) =>
+      new SignJWT(claims)
+        .setProtectedHeader({ alg: "RS256", kid: "test-kid" })
+        .setIssuer(provider.issuer)
+        .setAudience("client-1")
+        .setIssuedAt()
+        .setExpirationTime("5m")
+        .sign(privateKey);
+
+    return { provider, sign };
+  }
+
+  it("extracts a verified profile from a valid id_token", async () => {
+    const { provider, sign } = await fakeProvider("https://jwks.example/1");
+    const idToken = await sign({ sub: "provider-user-1", email: "alice@example.com", email_verified: true });
+
+    const profile = await verifyIdTokenAndExtractProfile(provider, { clientId: "client-1", idToken });
+    expect(profile).toEqual({ providerAccountId: "provider-user-1", email: "alice@example.com", emailVerified: true });
+  });
+
+  it("defaults emailVerified to false when the claim is absent", async () => {
+    const { provider, sign } = await fakeProvider("https://jwks.example/2");
+    const idToken = await sign({ sub: "provider-user-2" });
+
+    const profile = await verifyIdTokenAndExtractProfile(provider, { clientId: "client-1", idToken });
+    expect(profile.emailVerified).toBe(false);
+    expect(profile.email).toBeUndefined();
+  });
+
+  it("rejects an id_token signed for a different audience", async () => {
+    const { provider, sign } = await fakeProvider("https://jwks.example/3");
+    const idToken = await sign({ sub: "provider-user-3" });
+
+    await expect(verifyIdTokenAndExtractProfile(provider, { clientId: "some-other-client", idToken })).rejects.toBeInstanceOf(
+      OAuthProfileInvalidError,
+    );
+  });
+});
+
+describe("oauth: completeOAuthLogin", () => {
+  function fakeStore() {
+    const accounts = new Map<string, { userId: string }>();
+    const users = new Map<string, { id: string; email?: string; emailVerified: boolean }>();
+    const auditLog: AuditEvent[] = [];
+    let nextId = 1;
+
+    const deps: OAuthStoreDeps = {
+      findAccountByProvider: async (provider, providerAccountId) => accounts.get(`${provider}:${providerAccountId}`) ?? null,
+      linkAccount: async ({ userId, provider, providerAccountId }) => {
+        accounts.set(`${provider}:${providerAccountId}`, { userId });
+      },
+      findUserByVerifiedEmail: async (email) => {
+        for (const user of users.values()) if (user.email === email && user.emailVerified) return { id: user.id };
+        return null;
+      },
+      createUserFromOAuth: async ({ email }) => {
+        const id = `user-${nextId++}`;
+        users.set(id, { id, email, emailVerified: true });
+        return { id };
+      },
+      appendAuditEvent: async (event) => {
+        auditLog.push(event);
+      },
+    };
+    return { deps, accounts, users, auditLog };
+  }
+
+  it("creates a new user on first login and links the account", async () => {
+    const store = fakeStore();
+    const result = await completeOAuthLogin(store.deps, {
+      provider: "google",
+      profile: { providerAccountId: "g-1", email: "bob@example.com", emailVerified: true },
+    });
+
+    expect(result.isNewUser).toBe(true);
+    expect(store.accounts.get("google:g-1")?.userId).toBe(result.userId);
+    expect(store.auditLog).toContainEqual({ type: "oauth_account_linked", userId: result.userId, provider: "google" });
+  });
+
+  it("returns the same user on a repeat login without creating a duplicate", async () => {
+    const store = fakeStore();
+    const first = await completeOAuthLogin(store.deps, {
+      provider: "google",
+      profile: { providerAccountId: "g-1", email: "bob@example.com", emailVerified: true },
+    });
+    const second = await completeOAuthLogin(store.deps, {
+      provider: "google",
+      profile: { providerAccountId: "g-1", email: "bob@example.com", emailVerified: true },
+    });
+
+    expect(second.userId).toBe(first.userId);
+    expect(second.isNewUser).toBe(false);
+  });
+
+  it("links to an existing user by verified email instead of creating a new one", async () => {
+    const store = fakeStore();
+    const existing = await store.deps.createUserFromOAuth({ email: "carol@example.com" });
+
+    const result = await completeOAuthLogin(store.deps, {
+      provider: "apple",
+      profile: { providerAccountId: "a-1", email: "carol@example.com", emailVerified: true },
+    });
+
+    expect(result.userId).toBe(existing.id);
+    expect(result.isNewUser).toBe(false);
+  });
+
+  it("does not link by email when the provider has not verified it", async () => {
+    const store = fakeStore();
+    await store.deps.createUserFromOAuth({ email: "dave@example.com" });
+
+    const result = await completeOAuthLogin(store.deps, {
+      provider: "apple",
+      profile: { providerAccountId: "a-2", email: "dave@example.com", emailVerified: false },
+    });
+
+    expect(result.isNewUser).toBe(true);
+  });
+});