@_mustachio/openauth 0.9.2 → 0.10.0

package/src/types/tenant.ts

@@ -0,0 +1,248 @@
+/**
+ * Tenant model + tenant-resolution / callback-recovery types.
+ *
+ * Per AD1, tenancy is **not** a URL concept. A tenant is whatever the
+ * user-supplied `resolveTenant(req)` says it is for an incoming request, plus
+ * a deterministic callback-recovery chain (MAC-bound state, partitioned host,
+ * or `flowId`-in-URI) for the post-redirect leg where the original tenant
+ * signal may no longer be available.
+ *
+ * The minimal state envelope MACed and round-tripped through upstream
+ * providers carries only `{ tenantId, flowId, nonce, kid }`. Everything else
+ * lives in the server-side `FlowRecord` (see `./flow.ts`).
+ */
+
+/**
+ * Branded tenant id — **opaque to the framework**.
+ *
+ * The framework treats `TenantId` as a comparable string and nothing more.
+ * It never parses it, never assumes a hierarchy or naming convention, never
+ * imposes uniqueness rules, never knows the lifecycle of a tenant. The
+ * embedding application decides what a tenant *is* (an organization, a
+ * workspace, an App-Tenant tuple, a customer, …) and supplies a
+ * `resolveTenant(req)` that maps incoming requests to the right key.
+ *
+ * Common embedding pattern when the host application has two levels of
+ * scoping (e.g. `App` ⇒ `App-Tenant`): encode the tuple into the key.
+ *
+ * ```ts
+ * // Inside the host application's resolveTenant:
+ * return ok(`${app.id}:${appTenant?.id ?? "__default__"}` as TenantId)
+ *
+ * // Inside the host application's ConfigStore.getTenantConfig:
+ * const [appId, subId] = (id as string).split(":")
+ * // merge App defaults + App-Tenant overrides from your own DB ...
+ * ```
+ *
+ * The brand exists to keep arbitrary `string` values from being passed
+ * where a `TenantId` is expected; the *meaning* of the string is the host
+ * application's concern.
+ */
+export type TenantId = string & { readonly __brand: "TenantId" }
+
+/**
+ * Cast helper for code that mints `TenantId` from a validated string. The
+ * framework imposes no validation on the value — callers ensure their key
+ * is non-empty and stable per partition.
+ */
+export const asTenantId = (value: string): TenantId => value as TenantId
+
+/** OAuth 2.1 grant types in scope for this IdP. Implicit is intentionally absent. */
+export type GrantType =
+  | "authorization_code"
+  | "refresh_token"
+  | "client_credentials"
+
+/**
+ * `MethodType` is the canonical discriminator for an `AuthMethod`. It mirrors
+ * the existing provider taxonomy. The UI uses it to decide which selection /
+ * form to render; the framework uses it as a routing / dispatch hint.
+ */
+export type MethodType =
+  | "oauth2"
+  | "oidc"
+  | "password"
+  | "code"
+  | "m2m"
+  | "passkey"
+  | "custom"
+
+/**
+ * Per-tenant configuration for a single auth method **instance**.
+ *
+ * `id` is the **tenant-local instance id** — the value that ends up in URLs
+ * (`/<id>/*`) and that the framework dispatches by.
+ *
+ * `kind` is the **factory id** — the value that selects which
+ * `AuthMethodFactory` builds this instance. A tenant may register multiple
+ * instances of the same factory (e.g. one Google Workspace SSO and one
+ * consumer Google Sign-In) by giving each instance a unique `id` while
+ * sharing a `kind`.
+ *
+ * `type` is the `MethodType` discriminator the UI uses. The framework
+ * verifies it agrees with the factory's declared type at load time.
+ *
+ * `config` is the tenant-supplied configuration blob. The framework validates
+ * it against the factory's Zod `configSchema` before any handler runs.
+ */
+export type MethodConfig = {
+  id: string
+  kind: string
+  type: MethodType
+  enabled: boolean
+  config: Record<string, unknown>
+}
+
+/** Optional theme metadata. Schema expanded in later phases. */
+export type ThemeConfig = {
+  primary?: string
+  logo?: string
+  favicon?: string
+  background?: string
+  font?: string
+}
+
+/**
+ * Registered OAuth client of this IdP (an app, SPA, mobile, M2M).
+ *
+ * Phase 8: split into a discriminated union so misconfiguration is a type
+ * error, not a runtime check. The runtime in `domain/authorize.ts` still
+ * enforces PKCE for public clients defensively, but hosts will see the
+ * problem at compile time.
+ *
+ * - **Public clients** (SPAs, mobile apps, native apps): no client secret;
+ *   `pkceRequired` is the literal `true`. PKCE is non-negotiable per
+ *   OAuth 2.1 BCP §2.1.1.
+ * - **Confidential clients** (server-side apps, M2M): `secretHash` is
+ *   required (this used to be optional, in practice always set). PKCE
+ *   recommended but may be disabled by the host.
+ */
+export type ClientConfig = PublicClientConfig | ConfidentialClientConfig
+
+export type PublicClientConfig = {
+  id: string
+  name: string
+  type: "public"
+  redirectUris: string[]
+  grantTypes: GrantType[]
+  scopes: string[]
+  /** Must be `true` for public clients per OAuth 2.1 §2.1.1. */
+  pkceRequired: true
+  /** Phase 8. */
+  dpopRequired?: boolean
+}
+
+export type ConfidentialClientConfig = {
+  id: string
+  name: string
+  type: "confidential"
+  /** Hash of the client secret. Required for confidential clients. */
+  secretHash: string
+  redirectUris: string[]
+  grantTypes: GrantType[]
+  scopes: string[]
+  /**
+   * Default true. Disabling it is permitted for confidential clients but
+   * strongly discouraged; OAuth 2.1 §2.1.1 recommends PKCE for every client.
+   */
+  pkceRequired: boolean
+  /** Phase 8. */
+  dpopRequired?: boolean
+}
+
+export type TenantConfig = {
+  id: TenantId
+  displayName: string
+  clients: ClientConfig[]
+  methods: MethodConfig[]
+  theme?: ThemeConfig
+  /** Set when the tenant needs cross-subdomain SSO. */
+  cookieDomain?: string
+  /** Override default refresh-token TTL (seconds). */
+  refreshTtl?: number
+  /** Override default access-token TTL (seconds). */
+  accessTtl?: number
+}
+
+/**
+ * Per-request tenant context handed to methods and the user-supplied
+ * `success` callback. `request.raw` is the Web Fetch `Request` the framework
+ * received; `request.custom` is whatever the host returned from the
+ * `IdPOptions.buildCustomContext` hook (request id, decoded JWT claims, mTLS
+ * cert info, geo hints — anything per-request that methods or `success`
+ * should see). Without the hook the blob is `{}`. The same blob is also
+ * persisted on the `FlowRecord` at `/authorize` time so it survives the
+ * upstream redirect and re-presents on the callback side.
+ */
+export type TenantContext = {
+  id: TenantId
+  config: TenantConfig
+  request: {
+    raw: Request
+    custom: Record<string, unknown>
+  }
+}
+
+/**
+ * Outcome of the framework's tenant-recovery chain, evaluated **before**
+ * `resolveTenant` runs on the incoming request. Each non-`fresh-request`
+ * variant carries a `flowId`; the framework consumes the matching
+ * `FlowRecord` and dispatches without consulting `resolveTenant`.
+ *
+ * Order of evaluation (see plan §"Tenant Recovery Across Redirects"):
+ *   1. If `callbackHostFor` configured AND host matches a known tenant:
+ *        a. `state` MAC-verifies → host-plus-mac
+ *        b. `flowId` in URI       → host-plus-uri
+ *        c. otherwise              → invalid_request, audit unrecoverable_flow
+ *   2. Else if `state` MAC-verifies → mac-state
+ *   3. Else if `flowId` in registered URI path/query → flow-id-in-uri
+ *   4. Else → fresh-request → call user's `resolveTenant(req)`
+ */
+export type TenantRecovery =
+  | { kind: "mac-state"; tenantId: TenantId; flowId: string }
+  | { kind: "host-plus-uri"; tenantId: TenantId; flowId: string }
+  | { kind: "host-plus-mac"; tenantId: TenantId; flowId: string }
+  | { kind: "flow-id-in-uri"; tenantId: TenantId; flowId: string }
+  | { kind: "fresh-request" }
+
+/**
+ * Minimal envelope MACed into the `state` query parameter. Intentionally
+ * tiny — under 256 base64url bytes — so it stays clear of provider URL
+ * limits. **No sensitive data must ever be added here.** Everything else
+ * lives in the server-side `FlowRecord`.
+ */
+export type StateEnvelope = {
+  tenantId: TenantId
+  flowId: string
+  /** Per-flow nonce. Distinct from the relying party's `state` param. */
+  nonce: string
+  /** Key id of the HMAC key used to mint this envelope (`StateKeyRing` lookup). */
+  kid: string
+}
+
+/**
+ * HMAC-SHA-256 key entry used to mint / verify the `state` envelope MAC.
+ * The 32-byte key is global (shared across IdP instances) — recovery has to
+ * work before tenant config is loaded, so per-tenant keys would create a
+ * bootstrap problem.
+ */
+export type StateKey = {
+  kid: string
+  /** 32 raw bytes. */
+  key: Uint8Array
+}
+
+/**
+ * State-MAC key ring with overlap-based rotation. `active` mints new state;
+ * any key in `verify` accepts existing state during its overlap window.
+ *
+ * Rotation cadence: monthly. The overlap window must be at least as long as
+ * the flow-record TTL (default 10 minutes); a 1-hour overlap is the
+ * recommended default. New keys are added to `verify` first, promoted to
+ * `active` on the next rotation, then dropped from `verify` after overlap.
+ */
+export type StateKeyRing = {
+  active: StateKey
+  /** Includes `active` plus any previous keys still inside their overlap window. */
+  verify: ReadonlyArray<StateKey>
+}

package/src/types/token.ts

@@ -0,0 +1,101 @@
+/**
+ * Token-domain shapes — auth code payload (snapshot of `FlowRecord` at
+ * handoff), access-token claims, refresh-token payload, and the small
+ * envelopes the `TokenStore` persists.
+ *
+ * Per AD9, access tokens are JWTs (ES256 by default, Ed25519 optional per
+ * AD11) and refresh tokens are opaque server-side records.
+ */
+import type { SubjectClaim } from "./subject"
+import type { TenantId } from "./tenant"
+
+/**
+ * Payload stored under an auth code. Built at callback time from the consumed
+ * `FlowRecord` plus the method's `success` result. Encrypted at rest by
+ * `TokenStore.saveCode` (see `ports/CONSISTENCY.md`).
+ *
+ * `methodState` is intentionally **not** snapshotted: it served its
+ * upstream-callback purpose and is dropped with the flow record.
+ */
+export type CodePayload = {
+  tenantId: TenantId
+  clientId: string
+  appRedirectUri: string
+  /** Relying party's `state` param, echoed back at success. */
+  appState: string | null
+  scopes: string[]
+  audience?: string
+  /** Relying-party → IdP PKCE; verified at `/token` against the RP's verifier. */
+  clientPkce?: { challenge: string; method: "S256" }
+  /** Tenant-local method instance id (`MethodConfig.id`). */
+  methodId: string
+  /** Factory kind (`MethodConfig.kind`). */
+  methodKind: string
+  /** User's `requestContext` snapshot, if any. */
+  context?: Record<string, unknown> | null
+  /** Upstream system's stable identifier (from `MethodResult.success`). */
+  providerSubject: string
+  /** Typed-per-method properties from `MethodResult.success`. */
+  properties: unknown
+  /** Auth-code TTL is 60 s — framework refuses anything longer. */
+  expiresAt: number
+}
+
+/** Access-token JWT claims this IdP issues. */
+export type AccessTokenClaims = {
+  iss: string
+  sub: string
+  aud: string
+  exp: number
+  iat: number
+  /** Tenant id. */
+  tid: TenantId
+  /** Tenant-local method instance id that originated this token. */
+  mid?: string
+  /** Factory kind that originated this token. */
+  mkind?: string
+  scope?: string
+  /** DPoP confirmation claim (Phase 8). */
+  cnf?: { jkt: string }
+  /** The structured subject (matches `SubjectClaim`). Inlined for resource servers. */
+  claim: SubjectClaim
+}
+
+/**
+ * Opaque refresh-token payload — persisted in `TokenStore` with strong CAS
+ * semantics (see `ports/CONSISTENCY.md`). The token itself is a random
+ * string; the payload is what the store returns on consume.
+ */
+export type RefreshTokenPayload = {
+  tenantId: TenantId
+  clientId: string
+  /** Stable subject id derived from the issued `SubjectClaim`. */
+  subjectId: string
+  claim: SubjectClaim
+  scopes: string[]
+  audience?: string
+  /** Reuse-detection chain id. Rotation issues a new token with the same family. */
+  family: string
+  /**
+   * Tenant-local method instance id (`MethodConfig.id`) that originated the
+   * chain. Preserved across `refresh_token` rotations so descendant access
+   * tokens carry the original `mid` / `mkind` claims instead of the
+   * grant-type literal "refresh".
+   */
+  methodId: string
+  /** Factory kind (`MethodConfig.kind`) that originated the chain. */
+  methodKind: string
+  /** Wall-clock issuance and absolute-expiry timestamps. */
+  issuedAt: number
+  expiresAt: number
+}
+
+/** Response body of `/token` (RFC 6749 §5.1). */
+export type TokenResponse = {
+  access_token: string
+  token_type: "Bearer" | "DPoP"
+  expires_in: number
+  refresh_token?: string
+  scope?: string
+  id_token?: string
+}

package/src/ui/forms.ts

@@ -0,0 +1,289 @@
+/**
+ * Server-rendered HTML helpers for the bundled credential methods and the
+ * default authorization picker.
+ *
+ * Intentionally minimal — zero JS, no client framework. Hosts that want a
+ * richer UI override `IdPOptions.renderPicker` (for method selection) or
+ * supply their own `success-response` from method handlers (for credential
+ * forms). The helpers escape user-provided strings so callers can drop
+ * arbitrary labels or error messages without thinking about XSS.
+ */
+
+export function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => {
+    switch (c) {
+      case "&":
+        return "&amp;"
+      case "<":
+        return "&lt;"
+      case ">":
+        return "&gt;"
+      case '"':
+        return "&quot;"
+      case "'":
+        return "&#39;"
+      default:
+        return c
+    }
+  })
+}
+
+export const BASE_STYLES = `
+:root {
+  color-scheme: light dark;
+
+  --bg-page: #eef0f4;
+  --bg-card: #ffffff;
+  --bg-input: #ffffff;
+  --bg-row: #f5f6f8;
+  --bg-row-hover: #eaecf1;
+  --fg-high: #0e1116;
+  --fg-mid: #4a5160;
+  --fg-low: #8b93a3;
+  --border: #d8dce3;
+  --border-strong: #9aa3b2;
+  --primary: #2f3137;
+  --primary-fg: #ffffff;
+  --primary-hover: #1b1d22;
+  --focus-ring: rgba(47, 49, 55, 0.18);
+  --error-bg: #fdecec;
+  --error-fg: #8a1a1a;
+  --radius: 8px;
+  --shadow-card: 0 1px 2px rgba(15, 18, 25, 0.04), 0 12px 28px rgba(15, 18, 25, 0.08);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg-page: #0e0f12;
+    --bg-card: #16181d;
+    --bg-input: #1c1f25;
+    --bg-row: #20242c;
+    --bg-row-hover: #2a2f38;
+    --fg-high: #f3f4f6;
+    --fg-mid: #b6bcc7;
+    --fg-low: #7a8190;
+    --border: #2a2e36;
+    --border-strong: #3a4049;
+    --primary: #f3f4f6;
+    --primary-fg: #0e1116;
+    --primary-hover: #ffffff;
+    --focus-ring: rgba(243, 244, 246, 0.22);
+    --error-bg: #2a1414;
+    --error-fg: #f5b4b4;
+    --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.5), 0 18px 40px rgba(0, 0, 0, 0.5);
+  }
+}
+
+* { box-sizing: border-box; }
+
+html, body { margin: 0; padding: 0; }
+
+body {
+  min-height: 100vh;
+  background: var(--bg-page);
+  color: var(--fg-high);
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", "Inter", "Helvetica Neue", sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
+  font-size: 15px;
+  line-height: 1.45;
+  display: grid;
+  place-items: center;
+  padding: 1.5rem;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+main {
+  max-width: 380px;
+  width: 100%;
+  padding: 2rem 1.75rem;
+  background: var(--bg-card);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow-card);
+}
+
+h1 {
+  font-size: 1.125rem;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  margin: 0 0 1.25rem;
+  color: var(--fg-high);
+}
+
+form {
+  display: grid;
+  gap: 0.85rem;
+  margin: 0;
+}
+
+label {
+  display: grid;
+  gap: 0.4rem;
+  font-size: 0.78rem;
+  font-weight: 500;
+  color: var(--fg-mid);
+  text-transform: none;
+}
+
+input {
+  width: 100%;
+  height: 2.5rem;
+  padding: 0 0.85rem;
+  background: var(--bg-input);
+  color: var(--fg-high);
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius) - 2px);
+  font-size: 0.95rem;
+  font-family: inherit;
+  outline: none;
+  transition: border-color 120ms ease, box-shadow 120ms ease;
+}
+input::placeholder { color: var(--fg-low); }
+input:hover { border-color: var(--border-strong); }
+input:focus {
+  border-color: var(--primary);
+  box-shadow: 0 0 0 3px var(--focus-ring);
+}
+input:user-invalid:not(:focus) {
+  border-color: var(--error-fg);
+}
+
+button {
+  height: 2.5rem;
+  padding: 0 1rem;
+  border: 0;
+  border-radius: calc(var(--radius) - 2px);
+  background: var(--primary);
+  color: var(--primary-fg);
+  font-family: inherit;
+  font-size: 0.9rem;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  transition: background 120ms ease, transform 80ms ease;
+}
+button:hover { background: var(--primary-hover); }
+button:active { transform: translateY(1px); }
+button:focus-visible { box-shadow: 0 0 0 3px var(--focus-ring); outline: none; }
+
+.error {
+  display: flex;
+  align-items: center;
+  min-height: 2.25rem;
+  padding: 0.5rem 0.85rem;
+  margin: 0 0 0.25rem;
+  background: var(--error-bg);
+  color: var(--error-fg);
+  font-size: 0.82rem;
+  border-radius: calc(var(--radius) - 2px);
+}
+
+.methods {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: grid;
+  gap: 0.5rem;
+}
+.methods a {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 2.75rem;
+  padding: 0 1rem;
+  background: var(--bg-row);
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius) - 2px);
+  color: var(--fg-high);
+  font-size: 0.92rem;
+  font-weight: 500;
+  text-decoration: none;
+  transition: background 120ms ease, border-color 120ms ease, transform 80ms ease;
+}
+.methods a::after {
+  content: "›";
+  color: var(--fg-mid);
+  font-size: 1.15rem;
+  font-weight: 500;
+  line-height: 1;
+}
+.methods a:hover {
+  background: var(--bg-row-hover);
+  border-color: var(--border-strong);
+  color: var(--fg-high);
+}
+.methods a:hover::after {
+  color: var(--fg-high);
+}
+.methods a:active { transform: translateY(1px); }
+.methods a:focus-visible {
+  outline: none;
+  border-color: var(--primary);
+  box-shadow: 0 0 0 3px var(--focus-ring);
+}
+`
+
+export function htmlPage(opts: { title: string; body: string }): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(opts.title)}</title>
+  <style>${BASE_STYLES}</style>
+</head>
+<body>
+  <main>${opts.body}</main>
+</body>
+</html>`
+}
+
+export type FormField = {
+  name: string
+  label: string
+  type?: "text" | "password" | "email" | "tel"
+  value?: string
+  required?: boolean
+  autocomplete?: string
+  inputmode?: string
+}
+
+/** Build a `<form>` POSTing to `action`. */
+export function renderForm(opts: {
+  title: string
+  action: string
+  fields: FormField[]
+  submit: string
+  error?: string
+  hidden?: Record<string, string>
+}): string {
+  const errorHtml = opts.error
+    ? `<p class="error">${escapeHtml(opts.error)}</p>`
+    : ""
+  const hidden = Object.entries(opts.hidden ?? {})
+    .map(
+      ([k, v]) =>
+        `<input type="hidden" name="${escapeHtml(k)}" value="${escapeHtml(v)}">`,
+    )
+    .join("")
+  const fields = opts.fields
+    .map(
+      (f) => `<label>${escapeHtml(f.label)}
+<input
+  name="${escapeHtml(f.name)}"
+  type="${f.type ?? "text"}"
+  value="${escapeHtml(f.value ?? "")}"
+  ${f.required ? "required" : ""}
+  ${f.autocomplete ? `autocomplete="${escapeHtml(f.autocomplete)}"` : ""}
+  ${f.inputmode ? `inputmode="${escapeHtml(f.inputmode)}"` : ""}
+></label>`,
+    )
+    .join("")
+  return htmlPage({
+    title: opts.title,
+    body: `<h1>${escapeHtml(opts.title)}</h1>${errorHtml}<form method="POST" action="${escapeHtml(opts.action)}">${hidden}${fields}<button type="submit">${escapeHtml(opts.submit)}</button></form>`,
+  })
+}

package/src/ui/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Public surface for the built-in server-rendered UI helpers.
+ *
+ * Hosts who want their own UI typically don't import from here at all —
+ * they intercept at the host application layer. Hosts that want to keep
+ * the defaults but tweak around the edges (e.g. supply a custom picker
+ * while keeping the default credential forms) can pull renderForm /
+ * renderPicker from here.
+ */
+export { renderForm, escapeHtml, htmlPage, BASE_STYLES } from "./forms"
+export type { FormField } from "./forms"
+
+export { renderPicker, buildMethodLink } from "./picker"
+export type { PickerMethod, PickerContext } from "./picker"