@_mustachio/openauth 0.9.1 → 0.10.0

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,83 @@
+/**
+ * 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
+  response_types_supported: string[]
+  grant_types_supported: string[]
+  subject_types_supported: string[]
+  id_token_signing_alg_values_supported: string[]
+  scopes_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
+  }>
+  /** Advertised scopes. Defaults to `["openid", "email", "profile"]`. */
+  scopes?: string[]
+}
+
+export function buildDiscoveryDocument(deps: DiscoveryDeps): DiscoveryDocument {
+  const base = deps.issuerUrl.replace(/\/+$/, "")
+  const p = deps.paths ?? {}
+  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"}`,
+    response_types_supported: ["code"],
+    grant_types_supported: [
+      "authorization_code",
+      "refresh_token",
+      "client_credentials",
+    ],
+    subject_types_supported: ["public"],
+    id_token_signing_alg_values_supported: ["ES256", "EdDSA"],
+    scopes_supported: deps.scopes ?? ["openid", "email", "profile"],
+    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))
+}

package/src/domain/introspect.ts

@@ -0,0 +1,145 @@
+/**
+ * `/introspect` endpoint logic (RFC 7662).
+ *
+ * RFC 7662 §2.1 REQUIRES authentication: "To prevent token scanning
+ * attacks, the endpoint MUST also require some form of authorization to
+ * access this endpoint." Confidential-client credentials are validated
+ * against the **presenter's** tenant — resolved by the HTTP layer from
+ * the request, exactly the same way `/token client_credentials` resolves
+ * tenant. Authenticating before touching the token's `tid` means:
+ *
+ *   - Unknown presenting client OR wrong secret → `invalid_client`
+ *     (uniform — the response says nothing about the token).
+ *   - Token belongs to a different tenant than the presenter, or names a
+ *     different client as audience, or fails verification → `{active: false}`.
+ *
+ * Pre-fix the order was "verify token → load token's tenant → look up
+ * presenter in *that* tenant", which let a client authenticated in
+ * tenant X probe whether its `client_id` existed in tenant Y by
+ * watching for `invalid_client` versus `{active: false}` responses.
+ *
+ * Audience check (RFC 7662 §2.2): an authenticated client may only
+ * inspect tokens that name it as the audience. Tokens belonging to a
+ * different client return `{ active: false }` — never a structured
+ * error — to avoid leaking which tokens exist.
+ *
+ * Refresh tokens are not introspectable here; RFC 7662 §2.1 only
+ * requires access-token introspection, and our refresh tokens are
+ * opaque and don't carry the standard introspection metadata.
+ */
+import type { ConfigStore } from "../ports/config-store"
+import type { KeyStore } from "../ports/key-store"
+import type { AuthError } from "../types/error"
+import { authError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { AccessTokenClaims } from "../types/token"
+import type { TenantId } from "../types/tenant"
+
+import { verifyClientCredentials } from "./client-auth"
+import { verifyAccessToken } from "./jwt"
+
+export type IntrospectResponse =
+  | { active: false }
+  | {
+      active: true
+      sub: string
+      aud: string
+      iss: string
+      exp: number
+      iat: number
+      scope?: string
+      client_id?: string
+      tid: string
+      mid?: string
+      mkind?: string
+    }
+
+export type IntrospectRequest = {
+  token: string
+  tokenTypeHint?: "access_token" | "refresh_token"
+  /** REQUIRED — RFC 7662 §2.1. */
+  clientId: string
+  clientSecret?: string
+  /**
+   * The tenant the presenting client belongs to. Resolved by the HTTP
+   * layer via `IdPOptions.resolveTenant`, just like for the m2m grant.
+   * Cross-tenant introspection collapses to `{active: false}` regardless
+   * of whether the presenter's client exists in the token's tenant.
+   */
+  presenterTenantId: TenantId
+}
+
+export type IntrospectDeps = {
+  keyStore: KeyStore
+  configStore: ConfigStore
+  /** Expected issuer for additional validation. */
+  issuerUrl?: string
+}
+
+export async function introspect(
+  req: IntrospectRequest,
+  deps: IntrospectDeps,
+): Promise<Result<IntrospectResponse, AuthError>> {
+  // 1. Authenticate the presenting client against its OWN tenant before
+  //    looking at the token. Failure here = `invalid_client` (RFC 7662
+  //    §2.1). The presenter's tenant is the only signal we trust until
+  //    auth succeeds.
+  const presenterTenantCfg = await deps.configStore.getTenantConfig(
+    req.presenterTenantId,
+  )
+  if (isErr(presenterTenantCfg)) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`))
+  }
+  const presenter = presenterTenantCfg.value.clients.find(
+    (c) => c.id === req.clientId,
+  )
+  if (!presenter) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`))
+  }
+  const authErr = await verifyClientCredentials(presenter, req.clientSecret)
+  if (authErr) return err(authErr)
+
+  // 2. Try to verify the token. Unverifiable / wrong issuer / expired →
+  //    `{active: false}` so a presenter cannot tell the difference
+  //    between a forged token and a valid one belonging to another
+  //    tenant or client.
+  const keysRes = await deps.keyStore.signingKeys()
+  if (isErr(keysRes)) return err(keysRes.error)
+  let claims: AccessTokenClaims | null
+  try {
+    claims = await verifyAccessToken(req.token, keysRes.value, {
+      ...(deps.issuerUrl ? { issuer: deps.issuerUrl } : {}),
+    })
+  } catch {
+    return ok({ active: false })
+  }
+
+  // 3. Token's tenant must match the presenter's tenant. RFC 7662 lets
+  //    us return `{active: false}` here — never a structured error —
+  //    so a presenter can't probe across tenants. (H6 of the
+  //    post-rebuild review.)
+  if ((claims.tid as TenantId) !== req.presenterTenantId) {
+    return ok({ active: false })
+  }
+
+  // 4. Audience check (RFC 7662 §2.2): only the client the token names
+  //    as audience may see its claims.
+  if (claims.aud !== req.clientId) {
+    return ok({ active: false })
+  }
+
+  return ok({
+    active: true,
+    sub: claims.sub,
+    aud: claims.aud,
+    iss: claims.iss,
+    exp: claims.exp,
+    iat: claims.iat,
+    scope: claims.scope,
+    client_id: claims.aud,
+    tid: claims.tid,
+    mid: claims.mid,
+    mkind: claims.mkind,
+  })
+}

package/src/domain/jwt.ts

@@ -0,0 +1,106 @@
+/**
+ * JWT signing + verification for access tokens, plus the JWKS document
+ * builder consumed by `/.well-known/jwks.json`.
+ *
+ * Per AD9 / AD11, access tokens are JWTs (ES256 default; Ed25519 supported).
+ * Refresh tokens are opaque server-side records — they do NOT pass through
+ * this module.
+ */
+import type { JWK, KeyLike } from "jose"
+import { importJWK, jwtVerify, SignJWT } from "jose"
+
+import type { AccessTokenClaims } from "../types/token"
+import type { SigningKey } from "../ports/key-store"
+
+/**
+ * Sign an access-token claim set under the supplied private key. `kid` is
+ * stamped into the JWT header so verifiers can look up the right public
+ * key from JWKS.
+ */
+export async function signAccessToken(
+  claims: AccessTokenClaims,
+  privateKey: KeyLike,
+  alg: string,
+  kid: string,
+): Promise<string> {
+  return new SignJWT(claims as unknown as Record<string, unknown>)
+    .setProtectedHeader({ alg, typ: "JWT", kid })
+    .sign(privateKey)
+}
+
+/** Allow-list of asymmetric `alg` values the IdP issues + accepts. */
+const ASYMMETRIC_ALGS: ReadonlySet<string> = new Set(["ES256", "EdDSA"])
+
+/**
+ * Verify a JWT access token using a list of trusted signing keys (from
+ * `KeyStore.signingKeys()`). Looks up by `kid` in the JWT header.
+ *
+ * Algorithm enforcement: the allow-list is derived from the loaded
+ * `SigningKey.alg` values, intersected with the asymmetric allow-list
+ * (`ES256`, `EdDSA`). Symmetric (`HS*`) and `none` are filtered out, so a
+ * symmetric key accidentally landing in the store does not open an
+ * alg-confusion path. The kid resolver also rejects `alg: "none"`
+ * explicitly as defense in depth — `jose` already refuses tokens whose
+ * header `alg` is outside `algorithms`, but a future call site that
+ * dropped the option would still be safe.
+ *
+ * Returns the typed claims on success. Throws (via `jose`) on any
+ * signature, expiry, or alg-mismatch failure — callers wrap in `try` and
+ * convert to `Result`.
+ */
+export async function verifyAccessToken(
+  token: string,
+  keys: ReadonlyArray<SigningKey>,
+  options: { issuer?: string; audience?: string } = {},
+): Promise<AccessTokenClaims> {
+  const algorithms = Array.from(
+    new Set(keys.map((k) => k.alg).filter((a) => ASYMMETRIC_ALGS.has(a))),
+  )
+  const { payload } = await jwtVerify<AccessTokenClaims>(
+    token,
+    async (header) => {
+      if (!header.alg || header.alg === "none") {
+        throw new Error(`verifyAccessToken: refusing alg "${header.alg ?? ""}"`)
+      }
+      const match = keys.find((k) => k.kid === header.kid)
+      if (!match) {
+        throw new Error(`verifyAccessToken: unknown kid "${header.kid}"`)
+      }
+      if (match.alg !== header.alg) {
+        throw new Error(
+          `verifyAccessToken: header.alg "${header.alg}" does not match key alg "${match.alg}"`,
+        )
+      }
+      const imported = await importJWK(
+        match.publicJwk as unknown as JWK,
+        match.alg,
+      )
+      return imported as KeyLike
+    },
+    {
+      algorithms,
+      ...(options.issuer ? { issuer: options.issuer } : {}),
+      ...(options.audience ? { audience: options.audience } : {}),
+    },
+  )
+  return payload
+}
+
+/**
+ * Build the JWKS document for `/.well-known/jwks.json`. Includes active +
+ * recently-rotated keys (the overlap window) so consumers caching JWKS
+ * continue to verify tokens signed under a just-retired key until they
+ * refresh.
+ */
+export function buildJwksDocument(keys: ReadonlyArray<SigningKey>): {
+  keys: JWK[]
+} {
+  return {
+    keys: keys.map((k) => ({
+      ...k.publicJwk,
+      kid: k.kid,
+      alg: k.alg,
+      use: "sig",
+    })) as JWK[],
+  }
+}