@facilis.dev/auth 0.0.0-stage → 0.1.0

package/src/sso/oauth2.ts

@@ -0,0 +1,235 @@
+import { runtimeFetch, type FetchLike, type FetchResponse } from "./contracts.ts";
+import { SsoError } from "./errors.ts";
+import type { Oauth2ProviderConfig, SsoTokenAuth } from "./providers.ts";
+
+/**
+ * Generic OAuth2 authorization-code provider (D-120).
+ *
+ * Unlike OIDC there is no discovery or ID token, so the identity comes from the userinfo endpoint
+ * plus a dotted-path mapping declared in facilis.config.ts. Email verification is claim-driven:
+ * a provider that never reports the claim must opt in with `assumeEmailVerified`.
+ */
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+$/;
+
+export interface TokenPayload {
+  readonly accessToken: string;
+  readonly idToken?: string;
+}
+
+/** The subset of a provider the token endpoint needs; OIDC and OAuth2 share it. */
+export interface TokenClientConfig {
+  readonly clientId: string;
+  readonly clientSecret?: string;
+  readonly tokenAuth: SsoTokenAuth;
+}
+
+export interface RequestTokenInput {
+  readonly endpoint: string;
+  readonly client: TokenClientConfig;
+  readonly form: Readonly<Record<string, string>>;
+  readonly fetch?: FetchLike;
+}
+
+function requireFetch(fetch: FetchLike | undefined): FetchLike {
+  return fetch ?? runtimeFetch();
+}
+
+function basicAuthorization(clientId: string, clientSecret: string): string {
+  const bytes = new TextEncoder().encode(`${clientId}:${clientSecret}`);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return `Basic ${btoa(binary)}`;
+}
+
+/**
+ * POSTs an authorization-code grant to the token endpoint with the configured client auth mode.
+ *
+ * The response is parsed for `access_token`/`id_token` only; a provider error body is never
+ * surfaced (it can echo the code), just the safe `sso_exchange_failed` code.
+ */
+export async function requestToken(input: RequestTokenInput): Promise<TokenPayload> {
+  const form = new URLSearchParams(input.form);
+  form.set("client_id", input.client.clientId);
+  const headers: Record<string, string> = {
+    "content-type": "application/x-www-form-urlencoded",
+    accept: "application/json",
+  };
+  if (input.client.tokenAuth === "client_secret_basic") {
+    if (input.client.clientSecret === undefined) throw new SsoError("sso_provider_unavailable");
+    headers["authorization"] = basicAuthorization(input.client.clientId, input.client.clientSecret);
+  } else if (input.client.tokenAuth === "client_secret_post") {
+    if (input.client.clientSecret === undefined) throw new SsoError("sso_provider_unavailable");
+    form.set("client_secret", input.client.clientSecret);
+  }
+
+  let response: FetchResponse;
+  try {
+    response = await requireFetch(input.fetch)(input.endpoint, {
+      method: "POST",
+      headers,
+      body: form.toString(),
+    });
+  } catch (error) {
+    throw new SsoError("sso_exchange_failed", "token request failed", { cause: error });
+  }
+  if (!response.ok) throw new SsoError("sso_exchange_failed", `token endpoint ${response.status}`);
+
+  let payload: unknown;
+  try {
+    payload = await response.json();
+  } catch (error) {
+    throw new SsoError("sso_exchange_failed", "token response is not JSON", { cause: error });
+  }
+  if (typeof payload !== "object" || payload === null) {
+    throw new SsoError("sso_exchange_failed", "token response shape");
+  }
+  const record = payload as Record<string, unknown>;
+  const accessToken = readString(record, "access_token");
+  if (accessToken === undefined) throw new SsoError("sso_exchange_failed", "no access_token");
+  const idToken = readString(record, "id_token");
+  return idToken === undefined ? { accessToken } : { accessToken, idToken };
+}
+
+/** Reads a dotted path (`data.user.email`) out of parsed userinfo JSON. */
+export function readDottedPath(value: unknown, path: string): unknown {
+  let current: unknown = value;
+  for (const segment of path.split(".")) {
+    if (typeof current !== "object" || current === null) return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+function readString(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Truthiness of a verification claim: boolean true or the string "true" only. */
+export function readVerifiedClaim(value: unknown): boolean | undefined {
+  if (value === true || value === "true") return true;
+  if (value === false || value === "false") return false;
+  return undefined;
+}
+
+function requireString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+/** Subjects are often numeric in OAuth2 userinfo (e.g. a GitHub `id`). */
+function requireScalar(value: unknown): string | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return requireString(value);
+}
+
+/**
+ * The authorization URL: response_type=code, the configured scopes, state, PKCE S256 and the
+ * redirect URI. PKCE is sent unconditionally (RFC 6749 lets a provider ignore it) so a public
+ * `tokenAuth: "none"` client is protected exactly like the OIDC flow (D-120).
+ */
+export function buildOauth2AuthorizeUrl(
+  provider: Oauth2ProviderConfig,
+  redirectUri: string,
+  state: string,
+  codeChallenge: string,
+): string {
+  const url = new URL(provider.authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", provider.clientId);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  if (provider.scopes.length > 0) url.searchParams.set("scope", provider.scopes.join(" "));
+  return url.toString();
+}
+
+export interface Oauth2TokenInput {
+  readonly code: string;
+  readonly redirectUri: string;
+  /** PKCE verifier stored in the single-use state row; required, like the OIDC flow. */
+  readonly codeVerifier: string;
+  readonly fetch?: FetchLike;
+}
+
+export function exchangeOauth2Code(
+  client: TokenClientConfig,
+  provider: Oauth2ProviderConfig,
+  input: Oauth2TokenInput,
+): Promise<TokenPayload> {
+  return requestToken({
+    endpoint: provider.tokenEndpoint,
+    client,
+    form: {
+      grant_type: "authorization_code",
+      code: input.code,
+      redirect_uri: input.redirectUri,
+      code_verifier: input.codeVerifier,
+    },
+    ...(input.fetch === undefined ? {} : { fetch: input.fetch }),
+  });
+}
+
+async function fetchUserinfo(
+  provider: Oauth2ProviderConfig,
+  accessToken: string,
+  fetch: FetchLike,
+): Promise<Record<string, unknown>> {
+  let response: FetchResponse;
+  try {
+    response = await fetch(provider.userinfoEndpoint, {
+      method: "GET",
+      headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" },
+    });
+  } catch (error) {
+    throw new SsoError("sso_exchange_failed", "userinfo request failed", { cause: error });
+  }
+  if (!response.ok) throw new SsoError("sso_exchange_failed", `userinfo ${response.status}`);
+  let payload: unknown;
+  try {
+    payload = await response.json();
+  } catch (error) {
+    throw new SsoError("sso_exchange_failed", "userinfo is not JSON", { cause: error });
+  }
+  if (typeof payload !== "object" || payload === null) {
+    throw new SsoError("sso_exchange_failed", "userinfo shape");
+  }
+  return payload as Record<string, unknown>;
+}
+
+export interface Oauth2Identity {
+  readonly subject: string;
+  readonly email: string;
+  readonly emailVerified: boolean;
+}
+
+/** Maps the userinfo JSON onto the identity key via the configured dotted paths. */
+export function resolveOauth2Identity(
+  provider: Oauth2ProviderConfig,
+  userinfo: Record<string, unknown>,
+): Oauth2Identity {
+  const subject = requireScalar(readDottedPath(userinfo, provider.mapping.subject));
+  if (subject === undefined) throw new SsoError("sso_identity_invalid", "no subject mapping");
+  const rawEmail = requireString(readDottedPath(userinfo, provider.mapping.email));
+  if (rawEmail === undefined || !EMAIL_PATTERN.test(rawEmail)) {
+    throw new SsoError("sso_identity_invalid", "no email mapping");
+  }
+  const claim =
+    provider.mapping.emailVerified === undefined
+      ? undefined
+      : readVerifiedClaim(readDottedPath(userinfo, provider.mapping.emailVerified));
+  const emailVerified = claim ?? provider.assumeEmailVerified;
+  return { subject, email: rawEmail, emailVerified };
+}
+
+/** Token exchange + userinfo + mapping, the complete generic-OAuth2 identity resolution. */
+export async function resolveOauth2IdentityFromCode(
+  client: TokenClientConfig,
+  provider: Oauth2ProviderConfig,
+  input: Oauth2TokenInput,
+): Promise<Oauth2Identity> {
+  const token = await exchangeOauth2Code(client, provider, input);
+  const userinfo = await fetchUserinfo(provider, token.accessToken, input.fetch ?? runtimeFetch());
+  return resolveOauth2Identity(provider, userinfo);
+}

package/src/sso/oidc.ts

@@ -0,0 +1,285 @@
+import { createRemoteJWKSet, jwtVerify, type JWTVerifyGetKey } from "jose";
+
+import {
+  runtimeFetch,
+  type FetchLike,
+  type FetchResponse,
+  type IdentityClaims,
+} from "./contracts.ts";
+import { SsoError } from "./errors.ts";
+import { requestToken, readVerifiedClaim, type TokenPayload } from "./oauth2.ts";
+import type { OidcProviderConfig } from "./providers.ts";
+
+/**
+ * OpenID Connect authorization code flow with PKCE and nonce (D-120).
+ *
+ * Discovery is fetched once per provider and cached with a TTL; the ID token is verified with
+ * `jose` against the provider JWKS, the issuer, the client id and the nonce. Tests inject the
+ * fetch (discovery) and the JWKS resolver (`createLocalJWKSet`), so the suite needs no network.
+ */
+
+export const OIDC_DISCOVERY_TTL_MS = 5 * 60 * 1000;
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+$/;
+
+export interface OidcDiscovery {
+  readonly issuer: string;
+  readonly authorizationEndpoint: string;
+  readonly tokenEndpoint: string;
+  readonly userinfoEndpoint?: string;
+  readonly jwksUri: string;
+}
+
+export interface OidcDeps {
+  readonly fetch?: FetchLike;
+  readonly now?: () => number;
+  readonly jwksResolver?: (jwksUri: string) => JWTVerifyGetKey;
+  readonly discoveryTtlMs?: number;
+}
+
+interface CachedDiscovery {
+  readonly value: OidcDiscovery;
+  readonly fetchedAt: number;
+}
+
+const discoveryCache = new Map<string, CachedDiscovery>();
+
+/** Clears the per-provider discovery cache (tests, and a deliberate provider reconfiguration). */
+export function clearOidcDiscoveryCache(): void {
+  discoveryCache.clear();
+}
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+function readUrl(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  if (typeof value !== "string") return undefined;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function discoveryUrl(issuer: string): string {
+  return `${issuer.replace(/\/+$/, "")}/.well-known/openid-configuration`;
+}
+
+function parseDiscovery(value: unknown): OidcDiscovery {
+  const record = readRecord(value);
+  if (record === null) throw new SsoError("sso_provider_unavailable", "discovery shape");
+  const authorizationEndpoint = readUrl(record, "authorization_endpoint");
+  const tokenEndpoint = readUrl(record, "token_endpoint");
+  const jwksUri = readUrl(record, "jwks_uri");
+  const issuer = typeof record["issuer"] === "string" ? record["issuer"] : "";
+  if (authorizationEndpoint === undefined || tokenEndpoint === undefined || jwksUri === undefined) {
+    throw new SsoError("sso_provider_unavailable", "discovery is missing an endpoint");
+  }
+  const userinfoEndpoint = readUrl(record, "userinfo_endpoint");
+  return {
+    issuer,
+    authorizationEndpoint,
+    tokenEndpoint,
+    jwksUri,
+    ...(userinfoEndpoint === undefined ? {} : { userinfoEndpoint }),
+  };
+}
+
+/** Fetches and caches `<issuer>/.well-known/openid-configuration` for one provider. */
+export async function discoverOidc(
+  provider: OidcProviderConfig,
+  deps: OidcDeps = {},
+): Promise<OidcDiscovery> {
+  const now = deps.now?.() ?? Date.now();
+  const ttl = deps.discoveryTtlMs ?? OIDC_DISCOVERY_TTL_MS;
+  const key = `${provider.id}\u0000${provider.issuer}`;
+  const cached = discoveryCache.get(key);
+  if (cached !== undefined && now - cached.fetchedAt < ttl) return cached.value;
+
+  const fetch = deps.fetch ?? runtimeFetch();
+  let response: FetchResponse;
+  try {
+    response = await fetch(discoveryUrl(provider.issuer), {
+      method: "GET",
+      headers: { accept: "application/json" },
+    });
+  } catch (error) {
+    throw new SsoError("sso_provider_unavailable", "discovery request failed", { cause: error });
+  }
+  if (!response.ok) {
+    throw new SsoError("sso_provider_unavailable", `discovery ${response.status}`);
+  }
+  let payload: unknown;
+  try {
+    payload = await response.json();
+  } catch (error) {
+    throw new SsoError("sso_provider_unavailable", "discovery is not JSON", { cause: error });
+  }
+  const discovery = parseDiscovery(payload);
+  discoveryCache.set(key, { value: discovery, fetchedAt: now });
+  return discovery;
+}
+
+export interface OidcAuthorizeInput {
+  readonly redirectUri: string;
+  readonly state: string;
+  readonly nonce: string;
+  readonly codeChallenge: string;
+}
+
+/** The authorization URL: response_type=code, scopes, state, nonce and PKCE S256. */
+export function buildOidcAuthorizeUrl(
+  provider: OidcProviderConfig,
+  discovery: OidcDiscovery,
+  input: OidcAuthorizeInput,
+): string {
+  const url = new URL(discovery.authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", provider.clientId);
+  url.searchParams.set("redirect_uri", input.redirectUri);
+  url.searchParams.set("scope", provider.scopes.join(" "));
+  url.searchParams.set("state", input.state);
+  url.searchParams.set("nonce", input.nonce);
+  url.searchParams.set("code_challenge", input.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  return url.toString();
+}
+
+export interface OidcTokenInput {
+  readonly code: string;
+  readonly redirectUri: string;
+  readonly codeVerifier: string;
+  readonly fetch?: FetchLike;
+}
+
+export function exchangeOidcCode(
+  client: { clientId: string; clientSecret?: string; tokenAuth: OidcProviderConfig["tokenAuth"] },
+  discovery: OidcDiscovery,
+  input: OidcTokenInput,
+): Promise<TokenPayload> {
+  return requestToken({
+    endpoint: discovery.tokenEndpoint,
+    client,
+    form: {
+      grant_type: "authorization_code",
+      code: input.code,
+      redirect_uri: input.redirectUri,
+      code_verifier: input.codeVerifier,
+    },
+    ...(input.fetch === undefined ? {} : { fetch: input.fetch }),
+  });
+}
+
+export interface OidcClaims {
+  readonly subject: string;
+  readonly email?: string;
+  readonly emailVerified: boolean;
+}
+
+function readString(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Verifies an ID token: signature (JWKS), issuer, audience, expiry (jose) and the nonce. */
+export async function verifyOidcIdToken(
+  provider: OidcProviderConfig,
+  discovery: OidcDiscovery,
+  idToken: string,
+  nonce: string,
+  deps: OidcDeps = {},
+): Promise<OidcClaims> {
+  try {
+    const resolver =
+      deps.jwksResolver?.(discovery.jwksUri) ?? createRemoteJWKSet(new URL(discovery.jwksUri));
+    const { payload } = await jwtVerify(idToken, resolver, {
+      issuer: provider.issuer,
+      audience: provider.clientId,
+    });
+    const tokenNonce = payload["nonce"];
+    if (typeof tokenNonce !== "string" || tokenNonce !== nonce) {
+      throw new SsoError("sso_identity_invalid", "id_token nonce mismatch");
+    }
+    const subject = payload.sub;
+    if (typeof subject !== "string" || subject.length === 0) {
+      throw new SsoError("sso_identity_invalid", "id_token has no subject");
+    }
+    const email = typeof payload["email"] === "string" ? payload["email"] : undefined;
+    const claim = readVerifiedClaim(payload["email_verified"]);
+    return {
+      subject,
+      ...(email === undefined ? {} : { email }),
+      emailVerified: claim ?? provider.assumeEmailVerified,
+    };
+  } catch (error) {
+    if (error instanceof SsoError) throw error;
+    throw new SsoError("sso_identity_invalid", "id_token verification failed", { cause: error });
+  }
+}
+
+async function fetchUserinfo(
+  discovery: OidcDiscovery,
+  accessToken: string,
+  fetch: FetchLike,
+): Promise<Record<string, unknown>> {
+  if (discovery.userinfoEndpoint === undefined) {
+    throw new SsoError("sso_identity_invalid", "no userinfo endpoint");
+  }
+  let response: FetchResponse;
+  try {
+    response = await fetch(discovery.userinfoEndpoint, {
+      method: "GET",
+      headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" },
+    });
+  } catch (error) {
+    throw new SsoError("sso_exchange_failed", "userinfo request failed", { cause: error });
+  }
+  if (!response.ok) throw new SsoError("sso_exchange_failed", `userinfo ${response.status}`);
+  let payload: unknown;
+  try {
+    payload = await response.json();
+  } catch (error) {
+    throw new SsoError("sso_exchange_failed", "userinfo is not JSON", { cause: error });
+  }
+  const record = readRecord(payload);
+  if (record === null) throw new SsoError("sso_exchange_failed", "userinfo shape");
+  return record;
+}
+
+/**
+ * Resolves the OIDC identity: ID-token claims, with a userinfo fallback only when the email
+ * claim is absent. The userinfo `sub` must agree with the verified ID-token subject.
+ */
+export async function resolveOidcIdentity(
+  provider: OidcProviderConfig,
+  discovery: OidcDiscovery,
+  token: TokenPayload,
+  nonce: string,
+  deps: OidcDeps = {},
+): Promise<IdentityClaims> {
+  if (token.idToken === undefined) throw new SsoError("sso_identity_invalid", "no id_token");
+  const claims = await verifyOidcIdToken(provider, discovery, token.idToken, nonce, deps);
+  let email = claims.email;
+  let emailVerified = claims.emailVerified;
+
+  if (email === undefined) {
+    const userinfo = await fetchUserinfo(
+      discovery,
+      token.accessToken,
+      deps.fetch ?? runtimeFetch(),
+    );
+    const userinfoSubject = readString(userinfo, "sub");
+    if (userinfoSubject !== undefined && userinfoSubject !== claims.subject) {
+      throw new SsoError("sso_identity_invalid", "userinfo subject mismatch");
+    }
+    email = readString(userinfo, "email");
+    emailVerified = readVerifiedClaim(userinfo["email_verified"]) ?? provider.assumeEmailVerified;
+  }
+
+  if (email === undefined || !EMAIL_PATTERN.test(email)) {
+    throw new SsoError("sso_identity_invalid", "no email claim");
+  }
+  return { provider: provider.id, subject: claims.subject, email, emailVerified };
+}

package/src/sso/paths.ts

@@ -0,0 +1,21 @@
+import { normalizeRedirectTo } from "./state.ts";
+
+/**
+ * URL helpers for the SSO flow (D-120), shared by the login orchestration and its tests.
+ *
+ * Kept out of login.ts so the orchestration stays under the 300-line limit; nothing here needs
+ * the flow dependencies, only the public origin and the single-use state row.
+ */
+
+/** Fallback after a login when the attempt carried no valid same-origin path. */
+export const DEFAULT_POST_LOGIN_PATH = "/";
+
+/** The callback URL registered at the IdP for one provider. */
+export function ssoCallbackUrl(publicOrigin: string, providerId: string): string {
+  return `${publicOrigin.replace(/\/+$/, "")}/api/auth/sso/${encodeURIComponent(providerId)}/callback`;
+}
+
+/** The post-login path for a state row; an absent or invalid value falls back to the app root. */
+export function postLoginPath(state: { readonly redirectTo: string | null }): string {
+  return normalizeRedirectTo(state.redirectTo) ?? DEFAULT_POST_LOGIN_PATH;
+}

package/src/sso/pkce.ts

@@ -0,0 +1,30 @@
+import { encodeBase64, randomToken, webcrypto } from "../crypto.ts";
+
+/**
+ * PKCE (RFC 7636) for the authorization-code flows (D-120).
+ *
+ * Both OIDC and generic OAuth2 use S256 unconditionally: a provider that does not implement PKCE
+ * ignores the unknown parameters (RFC 6749), while a public `tokenAuth: "none"` client is
+ * protected against authorization-code interception. Kept in its own module so the OIDC flow
+ * and the login orchestration stay under the 300-line limit.
+ */
+
+function toBase64Url(bytes: Uint8Array): string {
+  return encodeBase64(bytes).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+
+async function s256(verifier: string): Promise<string> {
+  const digest = await webcrypto().subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return toBase64Url(new Uint8Array(digest));
+}
+
+export interface PkcePair {
+  readonly verifier: string;
+  readonly challenge: string;
+}
+
+/** PKCE S256 pair: a 43-character base64url verifier and its SHA-256 challenge. */
+export async function createPkcePair(): Promise<PkcePair> {
+  const verifier = randomToken(32);
+  return { verifier, challenge: await s256(verifier) };
+}