@_mustachio/openauth 0.9.2 → 0.11.0

package/src/domain/client-auth.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared client-authentication helpers.
+ *
+ * `/token`, `/revoke`, `/introspect`, and refresh-token rotation all need
+ * to validate presented credentials against a `ClientConfig`. The logic is
+ * the same in every case:
+ *
+ *  - **Public clients** MUST NOT present a `client_secret` (RFC 6749 §2.3).
+ *  - **Confidential clients** MUST present a `client_secret`, hashed and
+ *    compared in constant time against `ClientConfig.secretHash`.
+ *
+ * Credentials may ride either in the form body (`client_id`,
+ * `client_secret`) or in an `Authorization: Basic` header
+ * (RFC 6749 §2.3.1). Both encodings are accepted; the header takes
+ * precedence when both are present.
+ *
+ * The hashing function lives in `./token.ts` (`hashClientSecret`) to keep
+ * the legacy phase-2 SHA-256 / base64url format in one place; production
+ * deployments migrate to argon2id later in the rebuild.
+ */
+import { authError, type AuthError } from "../types/error"
+import type { ClientConfig } from "../types/tenant"
+
+import { timingSafeEqualStr } from "./crypto"
+import { hashClientSecret } from "./token"
+
+export type ClientCredentials = {
+  /** Client identifier (always present when credentials are presented). */
+  clientId: string
+  /** Confidential clients only. */
+  clientSecret?: string
+}
+
+/**
+ * Validate presented credentials against `client`. Returns `null` on
+ * success, `AuthError` on rejection.
+ *
+ * Public clients pass when no secret is presented. Confidential clients
+ * require both a secret and a matching `secretHash`.
+ */
+export async function verifyClientCredentials(
+  client: ClientConfig,
+  presentedSecret: string | undefined,
+): Promise<AuthError | null> {
+  if (client.type === "public") {
+    if (presentedSecret) {
+      return authError.invalidClient(
+        "public clients must not present a client_secret",
+      )
+    }
+    return null
+  }
+  if (!presentedSecret) {
+    return authError.invalidClient("confidential client requires client_secret")
+  }
+  const supplied = await hashClientSecret(presentedSecret)
+  if (!timingSafeEqualStr(supplied, client.secretHash)) {
+    return authError.invalidClient("client_secret mismatch")
+  }
+  return null
+}
+
+/**
+ * Parse an `Authorization: Basic <base64>` header.
+ *
+ * Returns `null` for missing / non-Basic headers and for any decoding
+ * failure; callers fall back to form-body credentials.
+ */
+export function parseBasicAuth(
+  header: string | null,
+): ClientCredentials | null {
+  if (!header) return null
+  const match = /^Basic\s+(.+)$/i.exec(header)
+  if (!match || !match[1]) return null
+  let decoded: string
+  try {
+    decoded = atob(match[1])
+  } catch {
+    return null
+  }
+  const colon = decoded.indexOf(":")
+  if (colon === -1) return null
+  let clientId: string
+  let clientSecret: string
+  try {
+    clientId = decodeURIComponent(decoded.slice(0, colon))
+    clientSecret = decodeURIComponent(decoded.slice(colon + 1))
+  } catch {
+    return null
+  }
+  return { clientId, clientSecret }
+}
+
+/**
+ * Merge form-body credentials with an optional `Authorization: Basic`
+ * header. The header wins per RFC 6749 §2.3 when both are present.
+ *
+ * Returns `null` when neither source supplies a `client_id` — callers
+ * then decide whether that's permissible (anonymous revoke is OK; the
+ * token endpoint isn't).
+ */
+export function resolveClientCredentials(input: {
+  authorizationHeader: string | null
+  bodyClientId: string | undefined
+  bodyClientSecret: string | undefined
+}): ClientCredentials | null {
+  const basic = parseBasicAuth(input.authorizationHeader)
+  if (basic) return basic
+  if (!input.bodyClientId) return null
+  return {
+    clientId: input.bodyClientId,
+    ...(input.bodyClientSecret !== undefined
+      ? { clientSecret: input.bodyClientSecret }
+      : {}),
+  }
+}

package/src/domain/client-credentials.ts

@@ -0,0 +1,180 @@
+/**
+ * `/token` endpoint logic for `grant_type=client_credentials` (RFC 6749 §4.4).
+ *
+ * Steps:
+ *   1. Authenticate the client. Must be confidential and must declare
+ *      `client_credentials` in `grantTypes`.
+ *   2. Resolve the tenant's m2m method. The plan models m2m as a method
+ *      with a `client` fn and no routes; we look for the unique
+ *      `type === "m2m"` instance on the tenant. Zero or multiple → error.
+ *   3. Call `method.client({ clientID, clientSecret, params })`. On
+ *      success the method returns the `P` properties it would have
+ *      emitted on a `success` MethodResult.
+ *   4. Invoke the user's `success` callback to mint the subject claim
+ *      with `methodKind = method.kind`, `methodId = method.id`.
+ *   5. `mintTokens` — access token only (no refresh per §4.4.3).
+ *
+ * The framework rejects requests presenting `scope` beyond what
+ * `ClientConfig.scopes` allows.
+ */
+import type { AuditLog } from "../ports/audit-log"
+import type { ConfigStore } from "../ports/config-store"
+import type { KeyStore } from "../ports/key-store"
+import type { TokenStore } from "../ports/token-store"
+import { authError, type AuthError } from "../types/error"
+import type { PersistUpstreamTokens, SuccessMapInput } from "../types/idp"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { SubjectClaim } from "../types/subject"
+import type { TenantContext, TenantId } from "../types/tenant"
+import type { TokenResponse } from "../types/token"
+
+import { verifyClientCredentials } from "./client-auth"
+import { randomId } from "./crypto"
+import { mintTokens } from "./token"
+import { MethodCache } from "./method-cache"
+
+export type ClientCredentialsRequest = {
+  grantType: "client_credentials"
+  clientId: string
+  clientSecret: string
+  scope?: string
+  /** Extra params (audience, resource, etc.). Forwarded to `method.client`. */
+  params?: Record<string, string>
+}
+
+export type ClientCredentialsDeps = {
+  configStore: ConfigStore
+  tokenStore: TokenStore
+  keyStore: KeyStore
+  auditLog?: AuditLog
+  methodCache: MethodCache
+  success: (input: SuccessMapInput) => Promise<SubjectClaim>
+  persistUpstreamTokens?: PersistUpstreamTokens
+  issuerUrl: string
+  clock: () => number
+  newRefreshFamily?: () => string
+  /** See `IdPOptions.customScopeClaims`. Forwarded to `mintTokens`. */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
+}
+
+export async function clientCredentialsGrant(
+  req: ClientCredentialsRequest,
+  deps: ClientCredentialsDeps,
+  tenantId: TenantId,
+): Promise<Result<TokenResponse, AuthError>> {
+  // 1. Tenant + client lookup.
+  const tenantCfg = await deps.configStore.getTenantConfig(tenantId)
+  if (isErr(tenantCfg)) return err(tenantCfg.error)
+  const client = tenantCfg.value.clients.find((c) => c.id === req.clientId)
+  if (!client) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`))
+  }
+  if (client.type !== "confidential") {
+    return err(
+      authError.invalidClient(
+        "client_credentials requires confidential client",
+      ),
+    )
+  }
+  if (!client.grantTypes.includes("client_credentials")) {
+    return err(
+      authError.unauthorizedClient(
+        `client "${client.id}" is not authorized for client_credentials`,
+      ),
+    )
+  }
+  const authErr = await verifyClientCredentials(client, req.clientSecret)
+  if (authErr) return err(authErr)
+
+  // 2. Scope validation.
+  const requestedScopes = req.scope
+    ? req.scope.split(" ").filter(Boolean)
+    : client.scopes
+  for (const s of requestedScopes) {
+    if (!client.scopes.includes(s)) {
+      return err(authError.invalidScope(`scope "${s}" not allowed for client`))
+    }
+  }
+
+  // 3. Resolve m2m method instance.
+  const m2mCfgs = tenantCfg.value.methods.filter(
+    (m) => m.type === "m2m" && m.enabled,
+  )
+  if (m2mCfgs.length === 0) {
+    return err(authError.methodNotFound("no enabled m2m method on tenant", {}))
+  }
+  if (m2mCfgs.length > 1) {
+    return err(
+      authError.methodNotFound(
+        "multiple m2m methods configured — only one supported",
+        {},
+      ),
+    )
+  }
+  const methodCfg = m2mCfgs[0]!
+  const methodRes = await deps.methodCache.resolve(
+    tenantCfg.value,
+    methodCfg.id,
+  )
+  if (isErr(methodRes)) return err(methodRes.error)
+  const method = methodRes.value
+  if (!method.client) {
+    return err(
+      authError.methodNotFound(
+        `m2m method "${methodCfg.id}" did not register a client fn`,
+        { methodId: methodCfg.id, methodKind: method.kind },
+      ),
+    )
+  }
+
+  // 4. Dispatch the method's client fn.
+  const clientResult = await method.client({
+    clientID: req.clientId,
+    clientSecret: req.clientSecret,
+    params: req.params ?? {},
+  })
+  if (isErr(clientResult)) return err(clientResult.error)
+
+  // 5. Build subject claim via user's success callback.
+  const tenant: TenantContext = {
+    id: tenantCfg.value.id,
+    config: tenantCfg.value,
+    request: { raw: new Request("about:blank"), custom: {} },
+  }
+  let claim: SubjectClaim
+  try {
+    claim = await deps.success({
+      tenant,
+      methodId: method.id,
+      methodKind: method.kind,
+      providerSubject: req.clientId,
+      properties: clientResult.value,
+      context: null,
+    })
+  } catch (e) {
+    return err(authError.serverError("success callback threw", e))
+  }
+
+  // 6. Mint access only — RFC 6749 §4.4.3 says client_credentials SHOULD
+  //    NOT issue a refresh token. `skipRefresh: true` keeps the token-
+  //    store from accumulating orphaned rows that the response would
+  //    otherwise strip.
+  const minted = await mintTokens({
+    tenant,
+    claim,
+    payload: {
+      tenantId: tenant.id,
+      clientId: client.id,
+      methodId: method.id,
+      methodKind: method.kind,
+      scopes: requestedScopes,
+      ...(client.scopes.includes("audience") ? {} : {}),
+    },
+    family: (deps.newRefreshFamily ?? randomId)(),
+    skipRefresh: true,
+    deps,
+  })
+  if (isErr(minted)) return err(minted.error)
+  return ok(minted.value)
+}

package/src/domain/crypto.ts

@@ -0,0 +1,168 @@
+/**
+ * Low-level crypto + encoding helpers used across the domain.
+ *
+ * Web Crypto only. No `node:*` imports — domain code runs on every runtime
+ * we target (Node 18+, Bun, Workers, Lambda).
+ */
+import { base64url as joseB64u, CompactEncrypt, compactDecrypt } from "jose"
+
+/** 256-bit random token, base64url-encoded. ~43 chars. */
+export function randomToken(): string {
+  const buf = new Uint8Array(32)
+  crypto.getRandomValues(buf)
+  return joseB64u.encode(buf)
+}
+
+/** 128-bit random id, base64url-encoded. ~22 chars. */
+export function randomId(): string {
+  const buf = new Uint8Array(16)
+  crypto.getRandomValues(buf)
+  return joseB64u.encode(buf)
+}
+
+/** Cryptographic random hex string of `bytes` length. */
+export function randomHex(bytes: number): string {
+  const buf = new Uint8Array(bytes)
+  crypto.getRandomValues(buf)
+  return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("")
+}
+
+/** Cryptographic random `Uint8Array` of `bytes` length. */
+export function randomBytes(bytes: number): Uint8Array {
+  const buf = new Uint8Array(bytes)
+  crypto.getRandomValues(buf)
+  return buf
+}
+
+/** Base64url encode raw bytes (jose alias for downstream consistency). */
+export const base64url = {
+  encode: (data: Uint8Array | string): string => joseB64u.encode(data),
+  decode: (s: string): Uint8Array => joseB64u.decode(s),
+}
+
+/** UTF-8 helpers. */
+export const utf8 = {
+  encode: (s: string): Uint8Array => new TextEncoder().encode(s),
+  decode: (b: Uint8Array): string => new TextDecoder().decode(b),
+}
+
+/**
+ * Constant-time byte-array compare. Returns false fast on length mismatch
+ * (length itself is not secret), then XORs every byte to avoid early exit.
+ */
+export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a[i]! ^ b[i]!
+  return diff === 0
+}
+
+/** Constant-time string compare (UTF-8 bytes). */
+export function timingSafeEqualStr(a: string, b: string): boolean {
+  return timingSafeEqual(utf8.encode(a), utf8.encode(b))
+}
+
+/** SHA-256 digest. */
+export async function sha256(data: Uint8Array | string): Promise<Uint8Array> {
+  const bytes = typeof data === "string" ? utf8.encode(data) : data
+  const digest = await crypto.subtle.digest("SHA-256", bytes)
+  return new Uint8Array(digest)
+}
+
+/** Import a 32-byte HMAC-SHA-256 key for sign/verify use. */
+export async function importHmacKey(
+  raw: Uint8Array,
+  usage: ReadonlyArray<"sign" | "verify"> = ["sign", "verify"],
+): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    "raw",
+    raw,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    [...usage],
+  )
+}
+
+/** HMAC-SHA-256 sign. */
+export async function hmacSign(
+  key: CryptoKey,
+  message: Uint8Array,
+): Promise<Uint8Array> {
+  const sig = await crypto.subtle.sign("HMAC", key, message)
+  return new Uint8Array(sig)
+}
+
+/**
+ * HMAC-SHA-256 verify. `crypto.subtle.verify` is timing-safe by spec, which
+ * is why we use it instead of recomputing + comparing manually.
+ */
+export async function hmacVerify(
+  key: CryptoKey,
+  signature: Uint8Array,
+  message: Uint8Array,
+): Promise<boolean> {
+  return crypto.subtle.verify("HMAC", key, signature, message)
+}
+
+/**
+ * Encrypt a JSON-serializable payload with AES-256-GCM under the supplied
+ * 256-bit key. Output is a compact JWE string (`{header}.{enc-key}.{iv}.{ct}.{tag}`).
+ *
+ * Used for `TokenStore.saveCode` — the auth-code payload is encrypted at
+ * rest. The compact-JWE format embeds the `kid` so `consumeCode` can pick
+ * the right key during overlap rotation.
+ *
+ * For symmetric direct encryption we use `dir` with `A256GCM`, so the
+ * supplied `keyBytes` is the content-encryption key itself.
+ */
+export async function encryptPayload(
+  payload: unknown,
+  kid: string,
+  keyBytes: Uint8Array,
+): Promise<string> {
+  if (keyBytes.byteLength !== 32) {
+    throw new Error(
+      `encryptPayload: keyBytes must be 32 bytes (A256GCM); got ${keyBytes.byteLength}`,
+    )
+  }
+  const cek = await crypto.subtle.importKey(
+    "raw",
+    keyBytes,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt"],
+  )
+  const json = utf8.encode(JSON.stringify(payload))
+  return new CompactEncrypt(json)
+    .setProtectedHeader({ alg: "dir", enc: "A256GCM", kid })
+    .encrypt(cek)
+}
+
+/** Inverse of {@link encryptPayload}. Returns the parsed JSON payload. */
+export async function decryptPayload<T = unknown>(
+  jwe: string,
+  resolveKey: (kid: string) => Promise<Uint8Array>,
+): Promise<T> {
+  const { plaintext } = await compactDecrypt(jwe, async (header) => {
+    const kid = header.kid
+    if (typeof kid !== "string") {
+      throw new Error("decryptPayload: missing kid in JWE header")
+    }
+    const raw = await resolveKey(kid)
+    return crypto.subtle.importKey(
+      "raw",
+      raw,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["decrypt"],
+    )
+  })
+  return JSON.parse(utf8.decode(plaintext)) as T
+}
+
+/** Generate a fresh 32-byte AES-256 / HMAC-SHA-256 key. */
+export function generateSymmetricKey(): Uint8Array {
+  const buf = new Uint8Array(32)
+  crypto.getRandomValues(buf)
+  return buf
+}

package/src/domain/discovery.ts

@@ -0,0 +1,161 @@
+/**
+ * Metadata-document builders for `/.well-known/openid-configuration` and
+ * `/.well-known/jwks.json`.
+ *
+ * Pure functions over typed ports + a small options record.
+ */
+import type { KeyStore } from "../ports/key-store"
+import type { AuthError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+
+import { buildJwksDocument } from "./jwt"
+
+export type DiscoveryDocument = {
+  issuer: string
+  authorization_endpoint: string
+  token_endpoint: string
+  userinfo_endpoint: string
+  jwks_uri: string
+  revocation_endpoint: string
+  introspection_endpoint: string
+  /** OIDC RP-Initiated Logout 1.0 §2. */
+  end_session_endpoint: string
+  /** RFC 7591 §3.1. */
+  registration_endpoint: string
+  /** RFC 9126 §5. */
+  pushed_authorization_request_endpoint: string
+  /**
+   * RFC 9126 §5. True iff every client on this tenant is required to use
+   * PAR. We advertise `false` at the tenant level — the per-client toggle
+   * is read at request time.
+   */
+  require_pushed_authorization_requests: boolean
+  /** RFC 9449 §5.1 — DPoP algorithms accepted on proof JWTs. */
+  dpop_signing_alg_values_supported: string[]
+  response_types_supported: string[]
+  grant_types_supported: string[]
+  subject_types_supported: string[]
+  id_token_signing_alg_values_supported: string[]
+  scopes_supported: string[]
+  /** OIDC Core §3 — registered claim names the IdP can return. */
+  claims_supported: string[]
+  /** OIDC Core §5.5 — `claims` request parameter is honored. */
+  claims_parameter_supported: boolean
+  /** OIDC Core §6.1 — JAR (`request` parameter). Not implemented. */
+  request_parameter_supported: boolean
+  /** OIDC Core §6.2 — JAR (`request_uri` parameter). Not implemented. */
+  request_uri_parameter_supported: boolean
+  /** OIDC Core §6.2 — whether `request_uri` values must be pre-registered. */
+  require_request_uri_registration: boolean
+  /** OIDC Core §3.1.2.1 — UI locales the OP can render. */
+  ui_locales_supported?: string[]
+  token_endpoint_auth_methods_supported: string[]
+  code_challenge_methods_supported: string[]
+}
+
+export type DiscoveryDeps = {
+  issuerUrl: string
+  /** Override path defaults if mounted under a non-root prefix. */
+  paths?: Partial<{
+    authorize: string
+    token: string
+    userinfo: string
+    jwks: string
+    revoke: string
+    introspect: string
+    endSession: string
+    par: string
+    register: string
+  }>
+  /** Advertised scopes. Defaults to `["openid", "email", "profile"]`. */
+  scopes?: string[]
+  /** Advertised UI locales. Defaults to `["en"]`. */
+  uiLocales?: string[]
+  /**
+   * Host-supplied scope → claim-names map. Each key adds a scope to
+   * `scopes_supported`; the union of values augments `claims_supported`.
+   * Mirrors `IdPOptions.customScopeClaims`.
+   */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
+}
+
+export function buildDiscoveryDocument(deps: DiscoveryDeps): DiscoveryDocument {
+  const base = deps.issuerUrl.replace(/\/+$/, "")
+  const p = deps.paths ?? {}
+  const customScopeKeys = Object.keys(deps.customScopeClaims ?? {})
+  const customClaimNames = new Set<string>()
+  for (const list of Object.values(deps.customScopeClaims ?? {})) {
+    for (const name of list) customClaimNames.add(name)
+  }
+  return {
+    issuer: deps.issuerUrl,
+    authorization_endpoint: `${base}${p.authorize ?? "/authorize"}`,
+    token_endpoint: `${base}${p.token ?? "/token"}`,
+    userinfo_endpoint: `${base}${p.userinfo ?? "/userinfo"}`,
+    jwks_uri: `${base}${p.jwks ?? "/.well-known/jwks.json"}`,
+    revocation_endpoint: `${base}${p.revoke ?? "/revoke"}`,
+    introspection_endpoint: `${base}${p.introspect ?? "/introspect"}`,
+    end_session_endpoint: `${base}${p.endSession ?? "/end_session"}`,
+    registration_endpoint: `${base}${p.register ?? "/register"}`,
+    pushed_authorization_request_endpoint: `${base}${p.par ?? "/par"}`,
+    require_pushed_authorization_requests: false,
+    dpop_signing_alg_values_supported: ["ES256", "EdDSA"],
+    response_types_supported: ["code"],
+    grant_types_supported: [
+      "authorization_code",
+      "refresh_token",
+      "client_credentials",
+    ],
+    subject_types_supported: ["public", "pairwise"],
+    id_token_signing_alg_values_supported: ["ES256", "EdDSA"],
+    scopes_supported: [
+      ...(deps.scopes ?? ["openid", "email", "profile"]),
+      ...customScopeKeys,
+    ],
+    claims_supported: [
+      "sub",
+      "iss",
+      "aud",
+      "exp",
+      "iat",
+      "auth_time",
+      "nonce",
+      "amr",
+      "at_hash",
+      "email",
+      "email_verified",
+      "name",
+      "given_name",
+      "family_name",
+      "preferred_username",
+      "picture",
+      "locale",
+      "phone_number",
+      "phone_number_verified",
+      "address",
+      ...customClaimNames,
+    ],
+    claims_parameter_supported: true,
+    request_parameter_supported: false,
+    request_uri_parameter_supported: false,
+    require_request_uri_registration: false,
+    ui_locales_supported: deps.uiLocales ?? ["en"],
+    token_endpoint_auth_methods_supported: [
+      "client_secret_basic",
+      "client_secret_post",
+      "none",
+    ],
+    code_challenge_methods_supported: ["S256"],
+  }
+}
+
+export type JwksDoc = ReturnType<typeof buildJwksDocument>
+
+export async function buildJwks(
+  keyStore: KeyStore,
+): Promise<Result<JwksDoc, AuthError>> {
+  const res = await keyStore.signingKeys()
+  if (isErr(res)) return err(res.error)
+  return ok(buildJwksDocument(res.value))
+}