@_mustachio/openauth 0.9.2 → 0.11.0

package/src/types/token.ts

@@ -0,0 +1,236 @@
+/**
+ * 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 { ClaimsRequest } from "./authorization"
+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
+  /**
+   * Relying party's OIDC `nonce` (OIDC Core §3.1.2.1). Snapshotted from
+   * `FlowRecord.appNonce`. Echoed into the issued `id_token` when present.
+   */
+  appNonce?: string
+  /**
+   * Seconds-since-epoch when end-user authentication completed
+   * (OIDC Core §2 `auth_time`). Stamped at the moment the method's
+   * `MethodResult.success` fires. Carried into the `id_token` and forward
+   * across refresh-token rotations.
+   */
+  authTime: number
+  /** OIDC Core §5.5 — RP-requested claims; honored at id_token + /userinfo. */
+  claimsRequest?: ClaimsRequest
+  /** Auth-code TTL is 60 s — framework refuses anything longer. */
+  expiresAt: number
+}
+
+/**
+ * OIDC Core §5.1 `address` claim. Structured object value rather than a
+ * scalar — distinct from the rest of the profile fields.
+ */
+export type AddressClaim = {
+  formatted?: string
+  street_address?: string
+  locality?: string
+  region?: string
+  postal_code?: string
+  country?: string
+}
+
+/**
+ * OIDC Core §5.1 profile / email / phone / address claims, gated by the
+ * `profile` / `email` / `phone` / `address` scopes via §5.4. Reused by
+ * `IdTokenClaims` and the `/userinfo` response so the two surfaces share
+ * exactly one source of truth for scope→claim mapping.
+ *
+ * Every field is optional: presence depends on (a) which scopes were
+ * granted and (b) whether the host populated the matching key in
+ * `SubjectClaim.properties`.
+ */
+export type ScopedProfileClaims = {
+  // `profile` scope
+  name?: string
+  given_name?: string
+  family_name?: string
+  middle_name?: string
+  nickname?: string
+  preferred_username?: string
+  profile?: string
+  picture?: string
+  website?: string
+  gender?: string
+  birthdate?: string
+  zoneinfo?: string
+  locale?: string
+  updated_at?: number
+  // `email` scope
+  email?: string
+  email_verified?: boolean
+  // `phone` scope
+  phone_number?: string
+  phone_number_verified?: boolean
+  // `address` scope
+  address?: AddressClaim
+}
+
+/**
+ * OIDC `id_token` JWT claims this IdP issues at `/token` when `openid`
+ * scope is granted (OIDC Core §2). Distinct from access-token claims:
+ *
+ *  - `aud` is the relying-party `client_id` (not the API audience).
+ *  - `nonce` echoes the RP's `/authorize` `nonce` parameter when present.
+ *  - `auth_time` is stable across refresh-token rotations (OIDC Core §12).
+ *  - `at_hash` is recommended whenever an id_token and access_token are
+ *    returned in the same response (§3.1.3.6).
+ *
+ * Standard OIDC claim names use snake_case on the wire; TypeScript field
+ * names match to keep the marshalling 1:1.
+ */
+export type IdTokenClaims = ScopedProfileClaims & {
+  iss: string
+  sub: string
+  aud: string
+  exp: number
+  iat: number
+  /** Seconds-since-epoch when end-user auth completed. */
+  auth_time?: number
+  /** RP-supplied OIDC nonce, when present. MUST equal the `/authorize` value. */
+  nonce?: string
+  /** Authentication Methods References (RFC 8176). */
+  amr?: string[]
+  /** Authentication Context Class Reference. */
+  acr?: string
+  /** Authorized party — the client_id of the party the id_token is for. */
+  azp?: string
+  /** Access-token hash (OIDC Core §3.1.3.6). */
+  at_hash?: string
+}
+
+/** 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
+  /**
+   * Seconds-since-epoch when the end-user originally authenticated
+   * (OIDC Core §2). Stable across refresh-token rotation and across
+   * RFC 8693 token-exchange (§12 — exchanging an audience does NOT
+   * re-authenticate the user). Absent on `client_credentials` grants
+   * where there is no end-user.
+   *
+   * Carried on the access token so RFC 8693 `subject_token` consumers
+   * can propagate it without needing the original id_token. Resource
+   * servers typically ignore it; it's there for the IdP's own
+   * downstream issuance.
+   */
+  auth_time?: number
+  /** DPoP confirmation claim (Phase 8). */
+  cnf?: { jkt: string }
+  /**
+   * OIDC Core §5.5 — list of claim names the RP requested for the
+   * `/userinfo` response via the `claims` parameter. The resource server
+   * surface uses this to bypass scope-gating per §5.5; it is empty /
+   * absent when the RP did not use the `claims` parameter.
+   */
+  uic?: 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
+  /**
+   * Seconds-since-epoch when end-user authentication originally completed
+   * (OIDC Core §2 `auth_time`). Stable across refresh-token rotations —
+   * `auth_time` does **not** advance on refresh, only on re-authentication.
+   */
+  authTime: number
+  /**
+   * RFC 7638 JWK thumbprint of the client's DPoP key (RFC 9449 §6.1).
+   * Present when the original token grant was DPoP-bound. Refresh-grant
+   * rotation REQUIRES a fresh DPoP proof whose thumbprint matches; absent
+   * = the token is plain Bearer and Bearer is acceptable on refresh.
+   */
+  dpopJkt?: string
+  /**
+   * OIDC Core §12 — the original RP-requested claims, preserved so
+   * refresh-grant id_token + /userinfo responses keep returning them.
+   */
+  claimsRequest?: ClaimsRequest
+  /** 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"

package/src/ui/picker.ts

@@ -0,0 +1,63 @@
+/**
+ * Default provider picker — rendered when an `/authorize` request matches
+ * more than one enabled method and no `method_id` was specified.
+ *
+ * Hosts that want a fully custom UI override `IdPOptions.renderPicker`.
+ * Both the default and any override return a `Response`; the framework
+ * applies caching headers afterward.
+ */
+import type { PickerContext, PickerMethod } from "../types/picker"
+import { escapeHtml, htmlPage } from "./forms"
+
+export type { PickerContext, PickerMethod }
+
+/**
+ * Build an `/authorize` URL that pre-selects a specific `method_id` while
+ * carrying every other OAuth param through unchanged.
+ */
+export function buildMethodLink(methodId: string, ctx: PickerContext): string {
+  const params = new URLSearchParams()
+  params.set("client_id", ctx.clientId)
+  params.set("redirect_uri", ctx.redirectUri)
+  params.set("response_type", "code")
+  params.set("method_id", methodId)
+  if (ctx.state) params.set("state", ctx.state)
+  if (ctx.scope) params.set("scope", ctx.scope)
+  if (ctx.nonce) params.set("nonce", ctx.nonce)
+  if (ctx.codeChallenge) params.set("code_challenge", ctx.codeChallenge)
+  if (ctx.codeChallengeMethod)
+    params.set("code_challenge_method", ctx.codeChallengeMethod)
+  if (ctx.audience) params.set("audience", ctx.audience)
+  if (ctx.prompt) params.set("prompt", ctx.prompt)
+  if (ctx.uiLocales) params.set("ui_locales", ctx.uiLocales)
+  return `?${params.toString()}`
+}
+
+/** Default styled HTML picker. */
+export function renderPicker(
+  methods: PickerMethod[],
+  ctx: PickerContext,
+): Response {
+  const items = methods
+    .map((m) => {
+      const label = m.displayName ?? prettyKind(m.kind)
+      return `<li><a href="${escapeHtml(buildMethodLink(m.id, ctx))}">${escapeHtml(label)}</a></li>`
+    })
+    .join("")
+  const body = `<h1>Sign in</h1><ul class="methods">${items}</ul>`
+  return new Response(htmlPage({ title: "Sign in", body }), {
+    status: 200,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+    },
+  })
+}
+
+function prettyKind(kind: string): string {
+  if (!kind) return "Continue"
+  return kind
+    .split(/[-_]/)
+    .map((p) => (p.length === 0 ? p : p[0]!.toUpperCase() + p.slice(1)))
+    .join(" ")
+}