@facilis.dev/auth 0.0.0-stage → 0.1.0

package/src/sso/providers.ts

@@ -0,0 +1,176 @@
+import { SsoError } from "./errors.ts";
+
+/**
+ * Provider resolution against the environment (D-120).
+ *
+ * The config commits the ENV VAR NAMES that hold secrets; the values never appear in the project.
+ * A provider whose secret (or SAML certificate) is missing is unusable: it is hidden from the
+ * public list and a start attempt answers `sso_provider_unavailable`. The value itself is never
+ * read for logging, compared or echoed.
+ *
+ * The types here mirror the `auth.sso` section of facilis.config.ts structurally. @facilis.dev/core
+ * already validates that config and depends on @facilis.dev/auth, so auth cannot import the core
+ * types without a package cycle; a parsed core provider is assignable to these shapes.
+ */
+
+export type SsoProviderKind = "oidc" | "oauth2" | "saml";
+export type SsoTokenAuth = "client_secret_post" | "client_secret_basic" | "none";
+
+export interface SsoProviderBase {
+  readonly id: string;
+  readonly label?: string;
+  readonly autoProvision: boolean;
+  readonly defaultRole?: string;
+}
+
+export interface OidcProviderConfig extends SsoProviderBase {
+  readonly kind: "oidc";
+  readonly issuer: string;
+  readonly clientId: string;
+  readonly clientSecretEnv?: string;
+  readonly scopes: readonly string[];
+  readonly tokenAuth: SsoTokenAuth;
+  readonly assumeEmailVerified: boolean;
+}
+
+export interface Oauth2Mapping {
+  readonly subject: string;
+  readonly email: string;
+  readonly emailVerified?: string;
+}
+
+export interface Oauth2ProviderConfig extends SsoProviderBase {
+  readonly kind: "oauth2";
+  readonly authorizationEndpoint: string;
+  readonly tokenEndpoint: string;
+  readonly userinfoEndpoint: string;
+  readonly clientId: string;
+  readonly clientSecretEnv?: string;
+  readonly scopes: readonly string[];
+  readonly tokenAuth: SsoTokenAuth;
+  readonly mapping: Oauth2Mapping;
+  readonly assumeEmailVerified: boolean;
+}
+
+export interface SamlProviderConfig extends SsoProviderBase {
+  readonly kind: "saml";
+  readonly entryPoint: string;
+  /** SP entity id declared to the IdP, and the expected assertion audience. */
+  readonly issuer: string;
+  readonly certificateEnv: string;
+  readonly emailAttribute: string;
+  readonly wantAssertionsSigned: boolean;
+  readonly wantResponseSigned: boolean;
+}
+
+export type SsoProviderConfig = OidcProviderConfig | Oauth2ProviderConfig | SamlProviderConfig;
+
+/**
+ * The identity-policy projection of a provider: exactly the fields identity resolution needs,
+ * so the flow never hands the whole config (and its secrets) to the linking code.
+ */
+export function identityPolicy(config: SsoProviderConfig): {
+  readonly id: string;
+  readonly autoProvision: boolean;
+  readonly defaultRole?: string;
+} {
+  return {
+    id: config.id,
+    autoProvision: config.autoProvision,
+    ...(config.defaultRole === undefined ? {} : { defaultRole: config.defaultRole }),
+  };
+}
+
+/** Structural shape of `config.auth.sso` after defineConfig applied its defaults. */
+export interface SsoConfigLike {
+  readonly providers: readonly SsoProviderConfig[];
+  readonly failureRedirect: string;
+  readonly stateTtlMs: number;
+}
+
+/** What the login page may see: no secret, no endpoint beyond the framework start URL. */
+export interface PublicSsoProvider {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: SsoProviderKind;
+  /** Framework-owned start URL, always relative to the application origin. */
+  readonly startUrl: string;
+}
+
+/** A provider plus the environment values the flow needs; never serialised. */
+export interface ResolvedSsoProvider {
+  readonly config: SsoProviderConfig;
+  readonly clientSecret?: string;
+  readonly idpCertificate?: string;
+}
+
+export const SSO_NAMESPACE = "/api/auth/sso";
+
+/** The environment variable whose absence makes a provider unusable, if any. */
+export function missingCredentialEnv(provider: SsoProviderConfig): string | undefined {
+  if (provider.kind === "saml") return provider.certificateEnv;
+  if (provider.tokenAuth === "none") return undefined;
+  return provider.clientSecretEnv;
+}
+
+function readEnv(
+  name: string | undefined,
+  environment: Readonly<Record<string, string | undefined>>,
+): string | undefined {
+  if (name === undefined) return undefined;
+  const value = environment[name];
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+/** True when every environment value this provider needs is present. */
+export function isProviderConfigured(
+  provider: SsoProviderConfig,
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  if (provider.kind === "saml") {
+    return readEnv(provider.certificateEnv, environment) !== undefined;
+  }
+  if (provider.tokenAuth === "none") return true;
+  return readEnv(provider.clientSecretEnv, environment) !== undefined;
+}
+
+/** The public list rendered by the login page; unconfigured providers are omitted. */
+export function publicProviderList(
+  config: SsoConfigLike,
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+): PublicSsoProvider[] {
+  return config.providers
+    .filter((provider) => isProviderConfigured(provider, environment))
+    .map((provider) => ({
+      id: provider.id,
+      label: provider.label ?? provider.id,
+      kind: provider.kind,
+      startUrl: `${SSO_NAMESPACE}/${encodeURIComponent(provider.id)}/start`,
+    }));
+}
+
+/**
+ * Finds a configured provider and reads its environment secret(s).
+ *
+ * Unknown provider => `sso_provider_unknown`; a known provider missing its env value =>
+ * `sso_provider_unavailable` (the caller logs a warning with the ENV VAR NAME only).
+ */
+export function resolveProvider(
+  config: SsoConfigLike,
+  id: string,
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+): ResolvedSsoProvider {
+  const provider = config.providers.find((candidate) => candidate.id === id);
+  if (provider === undefined) throw new SsoError("sso_provider_unknown");
+
+  if (provider.kind === "saml") {
+    const idpCertificate = readEnv(provider.certificateEnv, environment);
+    if (idpCertificate === undefined) throw new SsoError("sso_provider_unavailable");
+    return { config: provider, idpCertificate };
+  }
+
+  if (provider.tokenAuth === "none") return { config: provider };
+  const clientSecret = readEnv(provider.clientSecretEnv, environment);
+  if (clientSecret === undefined) throw new SsoError("sso_provider_unavailable");
+  return { config: provider, clientSecret };
+}

package/src/sso/saml.ts

@@ -0,0 +1,222 @@
+import type { CacheItem, CacheProvider, SamlConfig } from "@node-saml/node-saml";
+
+import { encodeBase64 } from "../crypto.ts";
+import type { IdentityClaims } from "./contracts.ts";
+import { SsoError } from "./errors.ts";
+import type { SamlProviderConfig } from "./providers.ts";
+
+/**
+ * SAML 2.0 SP-initiated Web Browser SSO (D-120).
+ *
+ * The AuthnRequest is built here (HTTP-Redirect, DEFLATE+base64) so the framework owns the
+ * request id, the ACS URL and the RelayState. ACS validation is delegated to
+ * `@node-saml/node-saml`, imported LAZILY inside this path: a project without SAML never loads
+ * (or bundles) its CJS crypto tree. IdP-initiated assertions are not accepted: there is no
+ * unsolicited-response surface, and the single-use RelayState is mandatory.
+ */
+
+const CLOCK_SKEW_MS = 5000;
+const NAME_ID_FORMAT = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress";
+const PROTOCOL_BINDING_POST = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST";
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+$/;
+
+export interface BuiltSamlRequest {
+  readonly requestId: string;
+  readonly redirectUrl: string;
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+/** The AuthnRequest XML (exported for tests; the IdP only ever sees the DEFLATE+base64 form). */
+export function buildAuthnRequestXml(
+  provider: SamlProviderConfig,
+  requestId: string,
+  acsUrl: string,
+  issueInstant: string,
+): string {
+  return (
+    `<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ` +
+    `xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="${escapeXml(requestId)}" ` +
+    `Version="2.0" IssueInstant="${issueInstant}" Destination="${escapeXml(provider.entryPoint)}" ` +
+    `AssertionConsumerServiceURL="${escapeXml(acsUrl)}" ProtocolBinding="${PROTOCOL_BINDING_POST}">` +
+    `<saml:Issuer>${escapeXml(provider.issuer)}</saml:Issuer>` +
+    `<samlp:NameIDPolicy AllowCreate="true" Format="${NAME_ID_FORMAT}"/>` +
+    `</samlp:AuthnRequest>`
+  );
+}
+
+async function deflateRaw(bytes: Uint8Array): Promise<Uint8Array> {
+  // node:zlib is a server-only builtin and is loaded with the SAML path, never at module load.
+  const { deflateRawSync } = await import("node:zlib");
+  return new Uint8Array(deflateRawSync(bytes));
+}
+
+/** Builds the HTTP-Redirect URL carrying the deflated AuthnRequest and the RelayState. */
+export async function buildSamlRedirect(
+  provider: SamlProviderConfig,
+  acsUrl: string,
+  relayState: string,
+  now: number = Date.now(),
+): Promise<BuiltSamlRequest> {
+  const requestId = `_${globalThis.crypto.randomUUID()}`;
+  const xml = buildAuthnRequestXml(provider, requestId, acsUrl, new Date(now).toISOString());
+  const compressed = await deflateRaw(new TextEncoder().encode(xml));
+  const url = new URL(provider.entryPoint);
+  url.searchParams.set("SAMLRequest", encodeBase64(compressed));
+  url.searchParams.set("RelayState", relayState);
+  return { requestId, redirectUrl: url.toString() };
+}
+
+export interface SamlProfileLike {
+  readonly nameID?: unknown;
+  readonly issuer?: unknown;
+  [attribute: string]: unknown;
+}
+
+export interface SamlValidator {
+  validatePostResponseAsync(
+    container: Record<string, string>,
+  ): Promise<{ profile: SamlProfileLike | null; loggedOut: boolean }>;
+}
+
+export type SamlValidatorFactory = (config: SamlConfig) => SamlValidator | Promise<SamlValidator>;
+
+/**
+ * A cache provider whose only entry is the request id of THIS attempt.
+ *
+ * `validateInResponseTo: "always"` (D-147) requires the response to carry the InResponseTo of the
+ * AuthnRequest this framework issued and to match the single-use state row; a response without
+ * it (IdP-initiated / unsolicited, or a replayed assertion) is rejected by node-saml.
+ */
+function singleUseRequestCache(requestId: string | null): CacheProvider {
+  let remaining = requestId;
+  const take = async (key: string | null): Promise<string | null> => {
+    if (key === null || remaining === null || key !== remaining) return null;
+    const value = remaining;
+    remaining = null;
+    return value;
+  };
+  return {
+    async saveAsync(): Promise<CacheItem | null> {
+      return null;
+    },
+    async getAsync(key: string): Promise<string | null> {
+      return key === remaining ? remaining : null;
+    },
+    async removeAsync(key: string | null): Promise<string | null> {
+      return take(key);
+    },
+    async consumeAsync(key: string): Promise<string | null> {
+      return take(key);
+    },
+    async saveIfAbsentAsync(): Promise<boolean> {
+      return false;
+    },
+  };
+}
+
+function toSamlConfig(
+  provider: SamlProviderConfig,
+  certificate: string,
+  callbackUrl: string,
+  requestId: string | null,
+): SamlConfig {
+  return {
+    callbackUrl,
+    entryPoint: provider.entryPoint,
+    issuer: provider.issuer,
+    audience: provider.issuer,
+    idpCert: certificate,
+    wantAssertionsSigned: provider.wantAssertionsSigned,
+    wantAuthnResponseSigned: provider.wantResponseSigned,
+    acceptedClockSkewMs: CLOCK_SKEW_MS,
+    // The library's enum is a runtime value; the string literal is the same member.
+    validateInResponseTo: "always" as SamlConfig["validateInResponseTo"],
+    cacheProvider: singleUseRequestCache(requestId),
+  };
+}
+
+async function defaultSamlFactory(config: SamlConfig): Promise<SamlValidator> {
+  const { SAML } = await import("@node-saml/node-saml");
+  return new SAML(config) as unknown as SamlValidator;
+}
+
+function asString(value: unknown): string | undefined {
+  if (typeof value === "string" && value.trim().length > 0) return value;
+  if (Array.isArray(value)) {
+    const first = value.find((entry) => typeof entry === "string" && entry.length > 0);
+    return typeof first === "string" ? first : undefined;
+  }
+  return undefined;
+}
+
+/** Case-insensitive attribute lookup; `nameid` means the NameID itself. */
+function readAttribute(profile: SamlProfileLike, attribute: string): string | undefined {
+  const wanted = attribute.toLowerCase();
+  if (wanted === "nameid") return asString(profile.nameID);
+  for (const [key, value] of Object.entries(profile)) {
+    if (key.toLowerCase() !== wanted) continue;
+    const found = asString(value);
+    if (found !== undefined) return found;
+  }
+  for (const fallback of ["email", "mail", "emailaddress"]) {
+    const found = asString(profile[fallback]);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+export interface ValidateSamlInput {
+  readonly provider: SamlProviderConfig;
+  /** The IdP signing certificate (PEM or base64 DER). Never logged. */
+  readonly certificate: string;
+  readonly callbackUrl: string;
+  /** The base64 `SAMLResponse` form field. */
+  readonly samlResponse: string;
+  /** The AuthnRequest id stored in the consumed state row. */
+  readonly requestId: string | null;
+  /** Test seam: replace the lazily imported validator. */
+  readonly validatorFactory?: SamlValidatorFactory;
+}
+
+/**
+ * Validates an ACS POST and returns the asserted identity.
+ *
+ * Signature, recipient, audience and time-window checks are node-saml's; a rejected response
+ * (unsigned, tampered, wrong recipient/audience, expired) becomes `sso_exchange_failed`, never
+ * a library message. A signed assertion is the IdP asserting the email, so SAML has no separate
+ * `email_verified` flag and treats the address as verified.
+ */
+export async function validateSamlResponse(input: ValidateSamlInput): Promise<IdentityClaims> {
+  const config = toSamlConfig(
+    input.provider,
+    input.certificate,
+    input.callbackUrl,
+    input.requestId,
+  );
+  const factory = input.validatorFactory ?? defaultSamlFactory;
+  let result: Awaited<ReturnType<SamlValidator["validatePostResponseAsync"]>>;
+  try {
+    const validator = await factory(config);
+    result = await validator.validatePostResponseAsync({ SAMLResponse: input.samlResponse });
+  } catch (error) {
+    throw new SsoError("sso_exchange_failed", "SAML response rejected", { cause: error });
+  }
+  if (result.profile === null || result.loggedOut) {
+    throw new SsoError("sso_exchange_failed", "SAML response has no assertion");
+  }
+  const profile = result.profile;
+  const email = readAttribute(profile, input.provider.emailAttribute);
+  if (email === undefined || !EMAIL_PATTERN.test(email)) {
+    throw new SsoError("sso_identity_invalid", "SAML assertion has no email");
+  }
+  const subject = asString(profile.nameID) ?? email;
+  return { provider: input.provider.id, subject, email, emailVerified: true };
+}

package/src/sso/state.ts

@@ -0,0 +1,114 @@
+import { eq, lt } from "drizzle-orm";
+
+import { randomToken } from "../crypto.ts";
+import type { SystemRunner } from "./contracts.ts";
+import { SsoError } from "./errors.ts";
+import { authSsoStates, type AuthSsoStateRow } from "./tables.ts";
+
+/** Contract cap on the post-login path (same-origin only; D-120). */
+export const MAX_REDIRECT_TO = 2048;
+const STATE_TOKEN_PATTERN = /^[A-Za-z0-9_-]{20,256}$/;
+const STATE_TABLES = ["auth_sso_states"] as const;
+
+/**
+ * Validates a post-login redirect: a same-origin absolute path only.
+ *
+ * Rejecting `//host`, a backslash and control characters closes the open-redirect hole: the value
+ * becomes the `Location` of a 302 and the user must never leave the application origin.
+ */
+export function normalizeRedirectTo(value: unknown): string | null {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_REDIRECT_TO)
+    return null;
+  if (!value.startsWith("/") || value.startsWith("//")) return null;
+  if (value.includes("\\")) return null;
+  // Whitespace and control characters have no business in an origin-relative path; browsers
+  // trim some of them, so refuse instead of relying on normalisation.
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code <= 0x20 || code === 0x7f) return null;
+  }
+  return value;
+}
+
+export interface CreateSsoStateInput {
+  /** Explicit token (SAML builds the AuthnRequest, whose RelayState is the state, before insert). */
+  readonly state?: string;
+  readonly provider: string;
+  /** `auth.sso.stateTtlMs`. */
+  readonly ttlMs: number;
+  readonly redirectTo: string | null;
+  readonly nonce?: string;
+  readonly codeVerifier?: string;
+  readonly requestId?: string;
+}
+
+function stateElevation(operation: string) {
+  return {
+    actor: "system:auth:sso" as const,
+    operation,
+    reason: "The SSO login attempt is framework-owned state written before a session exists.",
+    tables: STATE_TABLES,
+  };
+}
+
+/**
+ * Creates one single-use state row (32 random bytes, base64url) inside the audited system
+ * elevation. Expired rows are pruned on the same write, so a start request also cleans up.
+ */
+export async function createSsoState(
+  system: SystemRunner,
+  input: CreateSsoStateInput,
+  now: number = Date.now(),
+): Promise<AuthSsoStateRow> {
+  const state = input.state ?? randomToken(32);
+  if (!STATE_TOKEN_PATTERN.test(state)) throw new SsoError("sso_internal_error", "bad state token");
+  const createdAt = new Date(now);
+  const expiresAt = new Date(now + input.ttlMs);
+
+  const row = await system(stateElevation("auth:sso:state:create"), async (db) => {
+    await db.delete(authSsoStates).where(lt(authSsoStates.expiresAt, createdAt));
+    const inserted = await db
+      .insert(authSsoStates)
+      .values({
+        state,
+        provider: input.provider,
+        nonce: input.nonce ?? null,
+        codeVerifier: input.codeVerifier ?? null,
+        requestId: input.requestId ?? null,
+        redirectTo: input.redirectTo,
+        createdAt,
+        expiresAt,
+      })
+      .returning();
+    return inserted[0] ?? null;
+  });
+
+  if (row === null) throw new SsoError("sso_internal_error");
+  return row;
+}
+
+/**
+ * Consumes a state row atomically (`DELETE ... RETURNING`) and returns it once.
+ *
+ * A missing row (already used, unknown, or never issued) and an expired row are both
+ * `sso_state_invalid`: the caller only learns "this attempt is not valid".
+ */
+export async function consumeSsoState(
+  system: SystemRunner,
+  state: string,
+  now: number = Date.now(),
+): Promise<AuthSsoStateRow> {
+  if (!STATE_TOKEN_PATTERN.test(state)) throw new SsoError("sso_state_invalid");
+
+  const row = await system(stateElevation("auth:sso:state:consume"), async (db) => {
+    const deleted = await db
+      .delete(authSsoStates)
+      .where(eq(authSsoStates.state, state))
+      .returning();
+    return deleted[0] ?? null;
+  });
+
+  if (row === null) throw new SsoError("sso_state_invalid");
+  if (row.expiresAt.getTime() <= now) throw new SsoError("sso_state_invalid");
+  return row;
+}

package/src/sso/tables.ts

@@ -0,0 +1,77 @@
+import { sql } from "drizzle-orm";
+import { pgPolicy, pgTable, primaryKey, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+import { rlsForTable, tenantColumn } from "@facilis.dev/db";
+
+import { users } from "../tables.ts";
+
+const identitiesRls = rlsForTable({ tenantColumn: "tenant_id" });
+const statesRls = rlsForTable({ tenantColumn: "tenant_id" });
+
+/**
+ * SSO identity links (D-120, SPEC §5.3): one row per `(provider, subject)` pair.
+ *
+ * The identity key is the IdP's stable subject, never the email: a user who changes their email
+ * at the IdP keeps the link. `email` is the address reported at the last sign-in, for operators.
+ *
+ * RLS matches `users`: restrictive tenant isolation AND-ed with a permissive "tenant scope
+ * present" policy, because Postgres denies by default when no permissive policy applies.
+ */
+export const authIdentities = pgTable(
+  "auth_identities",
+  {
+    provider: text("provider").notNull(),
+    subject: text("subject").notNull(),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    email: text("email").notNull(),
+    tenantId: tenantColumn(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    lastLoginAt: timestamp("last_login_at").notNull().defaultNow(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.provider, table.subject] }),
+    ...identitiesRls.policies,
+    pgPolicy("auth_identities_tenant_access", {
+      for: "all",
+      using: sql`nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+      withCheck: sql`nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+  ],
+).enableRLS();
+
+/**
+ * One SSO login attempt (D-120): single-use state plus whatever the protocol needs to finish
+ * (`nonce`/`code_verifier` for OIDC, `request_id` for SAML, `redirect_to` for the browser).
+ *
+ * The row is written and consumed inside the audited `ctx.system` elevation, so RLS is not the
+ * load-bearing check here, but every scoped table ships the standard policies (SPEC §8.3).
+ */
+export const authSsoStates = pgTable(
+  "auth_sso_states",
+  {
+    state: text("state").primaryKey(),
+    provider: text("provider").notNull(),
+    nonce: text("nonce"),
+    codeVerifier: text("code_verifier"),
+    requestId: text("request_id"),
+    redirectTo: text("redirect_to"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    expiresAt: timestamp("expires_at").notNull(),
+    tenantId: tenantColumn(),
+  },
+  () => [
+    ...statesRls.policies,
+    pgPolicy("auth_sso_states_tenant_access", {
+      for: "all",
+      using: sql`nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+      withCheck: sql`nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+  ],
+).enableRLS();
+
+export type AuthIdentityRow = typeof authIdentities.$inferSelect;
+export type NewAuthIdentityRow = typeof authIdentities.$inferInsert;
+export type AuthSsoStateRow = typeof authSsoStates.$inferSelect;
+export type NewAuthSsoStateRow = typeof authSsoStates.$inferInsert;