@facilis.dev/auth 0.0.0-stage → 0.1.1

package/src/sso/identity.ts

@@ -0,0 +1,220 @@
+import { and, eq, sql } from "drizzle-orm";
+
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+
+import type { IdentityClaims, SsoAudit, SystemRunner } from "./contracts.ts";
+import { SsoError } from "./errors.ts";
+import { authIdentities } from "./tables.ts";
+import { normalizeEmail } from "../email.ts";
+import { users, userRoles } from "../tables.ts";
+
+/**
+ * Account linking and JIT provisioning (D-120).
+ *
+ * The identity key is `(provider, subject)`: a changed email never breaks an existing link.
+ * Without a link, the asserted email must be verified before it can match a user, and a user is
+ * only created when the provider's `autoProvision` allows it. Every read/write happens inside the
+ * caller's audited `ctx.system` elevation — never on a raw client (D-099).
+ *
+ * Races are handled with the unique keys the schema already has: `(provider, subject)` for the
+ * identity and `users.email` for the user, both `ON CONFLICT DO NOTHING` followed by a re-read.
+ */
+
+export const IDENTITY_TABLES = ["auth_identities", "users", "user_roles"] as const;
+
+const IDENTITY_ELEVATION = {
+  actor: "system:auth:sso" as const,
+  operation: "auth:sso:identity:resolve",
+  reason: "Linking or provisioning the user happens before the SSO session exists.",
+  tables: IDENTITY_TABLES,
+};
+
+export interface IdentityProviderPolicy {
+  readonly id: string;
+  readonly autoProvision: boolean;
+  readonly defaultRole?: string;
+}
+
+export interface ResolveIdentityOptions {
+  /** `config.auth.defaultRole`, used when the provider has no `defaultRole`. */
+  readonly defaultRole: string;
+  /**
+   * `config.auth.verification.enabled` (D-156): with email verification on, a pending password
+   * account is claimed (the IdP just proved the mailbox). With it off, the account was never
+   * meant to be verified, so the link is refused instead of silently resetting its password.
+   */
+  readonly claimUnverifiedPasswordAccount: boolean;
+  readonly audit: SsoAudit;
+}
+
+export type IdentityOutcome = "existing" | "linked" | "provisioned";
+
+export interface IdentityResolution {
+  readonly userId: string;
+  readonly outcome: IdentityOutcome;
+}
+
+function roleFor(provider: IdentityProviderPolicy, options: ResolveIdentityOptions): string {
+  return provider.defaultRole ?? options.defaultRole;
+}
+
+async function findIdentityUserId(
+  db: PolicyScopedDatabase,
+  provider: string,
+  subject: string,
+): Promise<string | null> {
+  const rows = await db
+    .select({ userId: authIdentities.userId })
+    .from(authIdentities)
+    .where(and(eq(authIdentities.provider, provider), eq(authIdentities.subject, subject)))
+    .limit(1);
+  return rows[0]?.userId ?? null;
+}
+
+async function findUserByEmail(
+  db: PolicyScopedDatabase,
+  email: string,
+): Promise<{ id: string; passwordHash: string | null; emailVerifiedAt: Date | null } | null> {
+  const rows = await db
+    .select({
+      id: users.id,
+      passwordHash: users.passwordHash,
+      emailVerifiedAt: users.emailVerifiedAt,
+    })
+    .from(users)
+    .where(sql`lower(${users.email}) = ${normalizeEmail(email)}`)
+    .limit(1);
+  return rows[0] ?? null;
+}
+
+/**
+ * A service account exists only to back an API client: it must never complete an interactive
+ * login. The generic `sso_account_not_found` is deliberate — the flow must not become a probe
+ * for which addresses belong to a service identity.
+ */
+async function assertLoginable(db: PolicyScopedDatabase, userId: string): Promise<void> {
+  const rows = await db
+    .select({ isService: users.isService })
+    .from(users)
+    .where(eq(users.id, userId))
+    .limit(1);
+  if (rows[0]?.isService === true) throw new SsoError("sso_account_not_found");
+}
+
+async function touchIdentity(
+  db: PolicyScopedDatabase,
+  claims: IdentityClaims,
+  now: Date,
+): Promise<void> {
+  await db
+    .update(authIdentities)
+    .set({ email: normalizeEmail(claims.email), lastLoginAt: now })
+    .where(
+      and(eq(authIdentities.provider, claims.provider), eq(authIdentities.subject, claims.subject)),
+    );
+}
+
+/**
+ * Resolves the Facilis user for a verified identity.
+ *
+ * Throws `sso_email_unverified` for an unverified email that has no existing link and
+ * `sso_account_not_found` when provisioning is disabled; both are safe to redirect.
+ */
+export async function resolveIdentity(
+  system: SystemRunner,
+  claims: IdentityClaims,
+  provider: IdentityProviderPolicy,
+  options: ResolveIdentityOptions,
+  now: Date = new Date(),
+): Promise<IdentityResolution> {
+  return system(IDENTITY_ELEVATION, async (db) => {
+    const linked = await findIdentityUserId(db, claims.provider, claims.subject);
+    if (linked !== null) {
+      await assertLoginable(db, linked);
+      await touchIdentity(db, claims, now);
+      return { userId: linked, outcome: "existing" };
+    }
+
+    // An unverified email must never link to (or provision) an account: that is account takeover.
+    if (!claims.emailVerified) throw new SsoError("sso_email_unverified");
+
+    const existingUser = await findUserByEmail(db, claims.email);
+    if (existingUser !== null) {
+      await assertLoginable(db, existingUser.id);
+      // Account pre-hijacking (SEC-02): a pending password account was registered by someone
+      // who never proved they own the address, and with email verification enabled it cannot
+      // even log in. The verified IdP email IS that proof now, so the identity claims the
+      // account and the placeholder password is removed before linking (D-156): whoever
+      // registered the address first loses it, the mailbox owner keeps it. A verified password
+      // account belongs to the same proven mailbox and links without clearing anything.
+      const claimed = existingUser.passwordHash !== null && existingUser.emailVerifiedAt === null;
+      if (claimed) {
+        // With verification disabled the account was never meant to prove its mailbox: refuse
+        // rather than silently reset a password its owner may still use (D-156).
+        if (!options.claimUnverifiedPasswordAccount) throw new SsoError("sso_email_conflict");
+        await db
+          .update(users)
+          .set({ passwordHash: null, emailVerifiedAt: now })
+          .where(eq(users.id, existingUser.id));
+      }
+      const inserted = await db
+        .insert(authIdentities)
+        .values({
+          provider: claims.provider,
+          subject: claims.subject,
+          userId: existingUser.id,
+          email: normalizeEmail(claims.email),
+        })
+        .onConflictDoNothing()
+        .returning({ userId: authIdentities.userId });
+      const raced =
+        inserted[0]?.userId ?? (await findIdentityUserId(db, claims.provider, claims.subject));
+      if (raced === null) throw new SsoError("sso_internal_error", "identity link race");
+      await touchIdentity(db, claims, now);
+      options.audit({
+        operation: "auth:sso:link",
+        outcome: "succeeded",
+        tables: claimed ? ["auth_identities", "users"] : ["auth_identities"],
+        details: {
+          provider: claims.provider,
+          ...(claimed ? { claimed: "unverified_password" } : {}),
+        },
+      });
+      return { userId: raced, outcome: "linked" };
+    }
+
+    if (!provider.autoProvision) throw new SsoError("sso_account_not_found");
+
+    const role = roleFor(provider, options);
+    const created = await db
+      .insert(users)
+      .values({ email: normalizeEmail(claims.email), passwordHash: null })
+      .onConflictDoNothing()
+      .returning({ id: users.id });
+    const userId = created[0]?.id ?? (await findUserByEmail(db, claims.email))?.id ?? null;
+    if (userId === null) throw new SsoError("sso_internal_error", "user provision race");
+
+    await db.insert(userRoles).values({ userId, role }).onConflictDoNothing();
+    const identity = await db
+      .insert(authIdentities)
+      .values({
+        provider: claims.provider,
+        subject: claims.subject,
+        userId,
+        email: normalizeEmail(claims.email),
+      })
+      .onConflictDoNothing()
+      .returning({ userId: authIdentities.userId });
+    const resolved =
+      identity[0]?.userId ?? (await findIdentityUserId(db, claims.provider, claims.subject));
+    if (resolved === null) throw new SsoError("sso_internal_error", "identity provision race");
+
+    options.audit({
+      operation: "auth:sso:provision",
+      outcome: "succeeded",
+      tables: ["users", "user_roles", "auth_identities"],
+      details: { provider: claims.provider, role },
+    });
+    return { userId: resolved, outcome: "provisioned" };
+  });
+}

package/src/sso/index.ts

@@ -0,0 +1,105 @@
+/**
+ * SSO (D-120): OIDC, generic OAuth2 and SAML as framework auth.
+ *
+ * Root re-exports only; the implementation is split by concern under this directory.
+ */
+
+export { authIdentities, authSsoStates } from "./tables.ts";
+export type {
+  AuthIdentityRow,
+  AuthSsoStateRow,
+  NewAuthIdentityRow,
+  NewAuthSsoStateRow,
+} from "./tables.ts";
+export {
+  SSO_ERROR_CODES,
+  failureRedirectPath,
+  isSsoError,
+  SsoError,
+  ssoErrorCode,
+} from "./errors.ts";
+export type { SsoErrorCode } from "./errors.ts";
+export {
+  isProviderConfigured,
+  missingCredentialEnv,
+  publicProviderList,
+  resolveProvider,
+  SSO_NAMESPACE,
+} from "./providers.ts";
+export type {
+  Oauth2Mapping,
+  Oauth2ProviderConfig,
+  OidcProviderConfig,
+  PublicSsoProvider,
+  ResolvedSsoProvider,
+  SamlProviderConfig,
+  SsoConfigLike,
+  SsoProviderBase,
+  SsoProviderConfig,
+  SsoProviderKind,
+  SsoTokenAuth,
+} from "./providers.ts";
+export { consumeSsoState, createSsoState, MAX_REDIRECT_TO, normalizeRedirectTo } from "./state.ts";
+export type { CreateSsoStateInput } from "./state.ts";
+export {
+  buildOidcAuthorizeUrl,
+  clearOidcDiscoveryCache,
+  discoverOidc,
+  exchangeOidcCode,
+  OIDC_DISCOVERY_TTL_MS,
+  resolveOidcIdentity,
+  verifyOidcIdToken,
+} from "./oidc.ts";
+export { createPkcePair } from "./pkce.ts";
+export type {
+  OidcAuthorizeInput,
+  OidcClaims,
+  OidcDeps,
+  OidcDiscovery,
+  OidcTokenInput,
+} from "./oidc.ts";
+export type { PkcePair } from "./pkce.ts";
+export {
+  buildOauth2AuthorizeUrl,
+  exchangeOauth2Code,
+  readDottedPath,
+  readVerifiedClaim,
+  requestToken,
+  resolveOauth2Identity,
+  resolveOauth2IdentityFromCode,
+} from "./oauth2.ts";
+export type {
+  Oauth2Identity,
+  Oauth2TokenInput,
+  RequestTokenInput,
+  TokenClientConfig,
+  TokenPayload,
+} from "./oauth2.ts";
+export { buildAuthnRequestXml, buildSamlRedirect, validateSamlResponse } from "./saml.ts";
+export type {
+  BuiltSamlRequest,
+  SamlProfileLike,
+  SamlValidator,
+  SamlValidatorFactory,
+  ValidateSamlInput,
+} from "./saml.ts";
+export { IDENTITY_TABLES, resolveIdentity } from "./identity.ts";
+export type {
+  IdentityOutcome,
+  IdentityProviderPolicy,
+  IdentityResolution,
+  ResolveIdentityOptions,
+} from "./identity.ts";
+export { completeLogin, startLogin } from "./login.ts";
+export { DEFAULT_POST_LOGIN_PATH, postLoginPath, ssoCallbackUrl } from "./paths.ts";
+export type { CompleteLoginInput, CompleteLoginResult, SsoFlowDeps } from "./login.ts";
+export type {
+  FetchInit,
+  FetchLike,
+  FetchResponse,
+  IdentityClaims,
+  SsoAudit,
+  SsoAuditInput,
+  SystemElevationOptions,
+  SystemRunner,
+} from "./contracts.ts";

package/src/sso/login.ts

@@ -0,0 +1,296 @@
+import { randomToken } from "../crypto.ts";
+import type { FetchLike, IdentityClaims, SsoAudit, SystemRunner } from "./contracts.ts";
+import { isSsoError, SsoError, ssoErrorCode } from "./errors.ts";
+import { resolveIdentity, type IdentityResolution } from "./identity.ts";
+import {
+  buildOidcAuthorizeUrl,
+  discoverOidc,
+  exchangeOidcCode,
+  resolveOidcIdentity,
+  type OidcDeps,
+} from "./oidc.ts";
+import { buildOauth2AuthorizeUrl, resolveOauth2IdentityFromCode } from "./oauth2.ts";
+import { createPkcePair } from "./pkce.ts";
+import { postLoginPath, ssoCallbackUrl } from "./paths.ts";
+import {
+  identityPolicy,
+  missingCredentialEnv,
+  resolveProvider,
+  type ResolvedSsoProvider,
+  type SsoConfigLike,
+  type SsoProviderConfig,
+} from "./providers.ts";
+import { buildSamlRedirect, validateSamlResponse, type SamlValidatorFactory } from "./saml.ts";
+import { consumeSsoState, createSsoState, normalizeRedirectTo } from "./state.ts";
+import type { AuthSsoStateRow } from "./tables.ts";
+/**
+ * The two ends of an SSO login (D-120): start builds the IdP redirect and stores the single-use
+ * attempt; complete consumes that attempt, resolves the identity and returns the user.
+ *
+ * The route owns the HTTP envelope (302, cookie, failure redirect); this module owns the protocol
+ * and never exposes an internal message. Every failure is an {@link SsoError} whose code is safe
+ * to append to `failureRedirect`.
+ */
+export interface SsoFlowDeps {
+  /** `config.auth.sso` after defaults. */
+  readonly sso: SsoConfigLike;
+  /** `config.auth.defaultRole`: the role a provisioned user gets without a provider override. */
+  readonly defaultRole: string;
+  /** `config.auth.verification.enabled`: allows the SSO identity to claim a pending account. */
+  readonly verificationEnabled: boolean;
+  /** Deployment origin (`FACILIS_PUBLIC_ORIGIN` or the request origin), no trailing slash. */
+  readonly publicOrigin: string;
+  readonly system: SystemRunner;
+  readonly audit: SsoAudit;
+  readonly fetch?: FetchLike;
+  readonly now?: () => number;
+  readonly environment?: Readonly<Record<string, string | undefined>>;
+  /** Diagnostic line for an unusable provider; must never receive a secret value. */
+  readonly warn?: (message: string, data: Record<string, unknown>) => void;
+  /** Test seam for discovery/JWKS; defaults to the flow's fetch/now. */
+  readonly oidc?: OidcDeps;
+  /** Test seam for the lazily imported SAML validator. */
+  readonly samlValidatorFactory?: SamlValidatorFactory;
+}
+function oidcDeps(deps: SsoFlowDeps): OidcDeps {
+  if (deps.oidc !== undefined) return deps.oidc;
+  return {
+    ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+    ...(deps.now === undefined ? {} : { now: deps.now }),
+  };
+}
+function resolve(deps: SsoFlowDeps, providerId: string): ResolvedSsoProvider {
+  try {
+    return resolveProvider(deps.sso, providerId, deps.environment ?? process.env);
+  } catch (error) {
+    if (isSsoError(error) && error.code === "sso_provider_unavailable") {
+      const provider = deps.sso.providers.find((candidate) => candidate.id === providerId);
+      const envName = provider === undefined ? undefined : missingCredentialEnv(provider);
+      // The warning names the provider and the ENV VAR, never its value (D-120).
+      deps.warn?.("sso provider is not configured", {
+        provider: providerId,
+        ...(envName === undefined ? {} : { env: envName }),
+      });
+    }
+    throw error;
+  }
+}
+function nowOf(deps: SsoFlowDeps): number {
+  return deps.now?.() ?? Date.now();
+}
+function tokenClient(config: SsoProviderConfig, secret: string | undefined) {
+  if (config.kind === "saml") throw new SsoError("sso_state_invalid");
+  return {
+    clientId: config.clientId,
+    tokenAuth: config.tokenAuth,
+    ...(secret === undefined ? {} : { clientSecret: secret }),
+  };
+}
+async function startRedirect(
+  deps: SsoFlowDeps,
+  input: { readonly providerId: string; readonly redirectTo: string | null },
+  provider: ResolvedSsoProvider,
+): Promise<string> {
+  const config = provider.config;
+  const redirectTo = normalizeRedirectTo(input.redirectTo);
+  const now = nowOf(deps);
+  const redirectUri = ssoCallbackUrl(deps.publicOrigin, config.id);
+
+  if (config.kind === "saml") {
+    const state = randomToken(32);
+    const built = await buildSamlRedirect(config, redirectUri, state, now);
+    await createSsoState(
+      deps.system,
+      {
+        provider: config.id,
+        ttlMs: deps.sso.stateTtlMs,
+        redirectTo,
+        requestId: built.requestId,
+        state,
+      },
+      now,
+    );
+    return built.redirectUrl;
+  }
+
+  if (config.kind === "oidc") {
+    const discovery = await discoverOidc(config, oidcDeps(deps));
+    const pkce = await createPkcePair();
+    const nonce = randomToken(32);
+    const state = await createSsoState(
+      deps.system,
+      {
+        provider: config.id,
+        ttlMs: deps.sso.stateTtlMs,
+        redirectTo,
+        nonce,
+        codeVerifier: pkce.verifier,
+      },
+      now,
+    );
+    return buildOidcAuthorizeUrl(config, discovery, {
+      redirectUri,
+      state: state.state,
+      nonce,
+      codeChallenge: pkce.challenge,
+    });
+  }
+
+  const pkce = await createPkcePair();
+  const state = await createSsoState(
+    deps.system,
+    {
+      provider: config.id,
+      ttlMs: deps.sso.stateTtlMs,
+      redirectTo,
+      codeVerifier: pkce.verifier,
+    },
+    now,
+  );
+  return buildOauth2AuthorizeUrl(config, redirectUri, state.state, pkce.challenge);
+}
+/** Starts a login and returns the IdP URL; the attempt is stored as one single-use row. */
+export async function startLogin(
+  deps: SsoFlowDeps,
+  input: { readonly providerId: string; readonly redirectTo: string | null },
+): Promise<{ readonly redirectUrl: string }> {
+  try {
+    const provider = resolve(deps, input.providerId);
+    const redirectUrl = await startRedirect(deps, input, provider);
+    deps.audit({
+      operation: "auth:sso:start",
+      outcome: "succeeded",
+      details: { provider: input.providerId },
+    });
+    return { redirectUrl };
+  } catch (error) {
+    deps.audit({
+      operation: "auth:sso:start",
+      outcome: "failed",
+      errorCode: ssoErrorCode(error),
+      details: { provider: input.providerId },
+    });
+    throw error;
+  }
+}
+export type CompleteLoginInput =
+  | { readonly method: "GET"; readonly code: string; readonly state: string }
+  | { readonly method: "POST"; readonly samlResponse: string; readonly relayState: string };
+export interface CompleteLoginResult {
+  readonly userId: string;
+  readonly redirectTo: string;
+  readonly resolution: IdentityResolution;
+}
+async function claimsFromCode(
+  deps: SsoFlowDeps,
+  provider: ResolvedSsoProvider,
+  code: string,
+  state: AuthSsoStateRow,
+): Promise<IdentityClaims> {
+  const config = provider.config;
+  if (state.provider !== config.id) throw new SsoError("sso_state_invalid");
+  if (config.kind === "oidc") {
+    if (state.nonce === null || state.codeVerifier === null)
+      throw new SsoError("sso_state_invalid");
+    const discovery = await discoverOidc(config, oidcDeps(deps));
+    const token = await exchangeOidcCode(tokenClient(config, provider.clientSecret), discovery, {
+      code,
+      redirectUri: ssoCallbackUrl(deps.publicOrigin, config.id),
+      codeVerifier: state.codeVerifier,
+      ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+    });
+    return resolveOidcIdentity(config, discovery, token, state.nonce, oidcDeps(deps));
+  }
+  if (config.kind === "oauth2") {
+    if (state.codeVerifier === null) throw new SsoError("sso_state_invalid");
+    const identity = await resolveOauth2IdentityFromCode(
+      tokenClient(config, provider.clientSecret),
+      config,
+      {
+        code,
+        redirectUri: ssoCallbackUrl(deps.publicOrigin, config.id),
+        codeVerifier: state.codeVerifier,
+        ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+      },
+    );
+    return { provider: config.id, ...identity };
+  }
+  throw new SsoError("sso_state_invalid");
+}
+async function completeGet(
+  deps: SsoFlowDeps,
+  provider: ResolvedSsoProvider,
+  input: Extract<CompleteLoginInput, { method: "GET" }>,
+): Promise<CompleteLoginResult> {
+  const state = await consumeSsoState(deps.system, input.state, nowOf(deps));
+  const claims = await claimsFromCode(deps, provider, input.code, state);
+  const resolution = await resolveIdentity(deps.system, claims, identityPolicy(provider.config), {
+    defaultRole: deps.defaultRole,
+    claimUnverifiedPasswordAccount: deps.verificationEnabled,
+    audit: deps.audit,
+  });
+  return { userId: resolution.userId, redirectTo: postLoginPath(state), resolution };
+}
+async function completePost(
+  deps: SsoFlowDeps,
+  provider: ResolvedSsoProvider,
+  input: Extract<CompleteLoginInput, { method: "POST" }>,
+): Promise<CompleteLoginResult> {
+  const config = provider.config;
+  if (config.kind !== "saml") throw new SsoError("sso_state_invalid");
+  const state = await consumeSsoState(deps.system, input.relayState, nowOf(deps));
+  if (state.provider !== config.id) throw new SsoError("sso_state_invalid");
+  const claims = await validateSamlResponse({
+    provider: config,
+    certificate: provider.idpCertificate ?? "",
+    callbackUrl: ssoCallbackUrl(deps.publicOrigin, config.id),
+    samlResponse: input.samlResponse,
+    requestId: state.requestId,
+    ...(deps.samlValidatorFactory === undefined
+      ? {}
+      : { validatorFactory: deps.samlValidatorFactory }),
+  });
+  const resolution = await resolveIdentity(deps.system, claims, identityPolicy(config), {
+    defaultRole: deps.defaultRole,
+    claimUnverifiedPasswordAccount: deps.verificationEnabled,
+    audit: deps.audit,
+  });
+  return { userId: resolution.userId, redirectTo: postLoginPath(state), resolution };
+}
+/**
+ * Completes a login: consumes the single-use state, exchanges the code/assertion and resolves the
+ * identity. A failure is rethrown as the safe code the route turns into a redirect.
+ */
+export async function completeLogin(
+  deps: SsoFlowDeps,
+  providerId: string,
+  input: CompleteLoginInput,
+): Promise<CompleteLoginResult> {
+  try {
+    const provider = resolve(deps, providerId);
+    if (input.method === "POST" && provider.config.kind !== "saml") {
+      throw new SsoError("sso_state_invalid");
+    }
+    if (input.method === "GET" && provider.config.kind === "saml") {
+      throw new SsoError("sso_state_invalid");
+    }
+    const result =
+      input.method === "POST"
+        ? await completePost(deps, provider, input)
+        : await completeGet(deps, provider, input);
+    deps.audit({
+      operation: "auth:sso:login",
+      outcome: "succeeded",
+      details: { provider: providerId },
+    });
+    return result;
+  } catch (error) {
+    deps.audit({
+      operation: "auth:sso:login",
+      outcome: "failed",
+      errorCode: ssoErrorCode(error),
+      details: { provider: providerId },
+    });
+    throw error;
+  }
+}