@_mustachio/openauth 0.9.2 → 0.10.0

package/src/methods/code.ts

@@ -0,0 +1,359 @@
+/**
+ * `codeMethod` — magic-code (email / SMS) credential factory.
+ *
+ * Routes:
+ *   GET  /authorize → render destination form (email or phone input).
+ *   POST /send      → mint code, call `sendCode(destination, code)` hook,
+ *                      stash hashed code in `methodState`, render verify form.
+ *   POST /verify    → compare submitted code against stored hash; on match,
+ *                      return `success` with the destination as provider
+ *                      subject.
+ *
+ * The framework's flow record TTL (10 minutes) doubles as the code TTL —
+ * the methodState rolls off when the flow does.
+ *
+ * Anti-enumeration: the `/send` route always renders the verify form,
+ * whether or not the destination is valid. The user-supplied `sendCode`
+ * hook can silently no-op for unknown destinations.
+ */
+import { z } from "zod"
+
+import {
+  base64url,
+  randomBytes,
+  sha256,
+  timingSafeEqualStr,
+  utf8,
+} from "../domain/crypto"
+import type {
+  AuthMethod,
+  AuthMethodFactory,
+  MethodContext,
+  MethodResult,
+} from "../types/method"
+import { renderForm } from "../ui/forms"
+
+export type CodeProperties = {
+  destination: string
+}
+
+export type CodeState = {
+  destination: string
+  /** Base64url SHA-256 hash of the code; the plain code never persists. */
+  codeHash: string
+  /** Failed-verify counter. After 5 attempts the flow is denied. */
+  attempts: number
+  error?: string
+}
+
+export type CodeMethodOptions = {
+  /**
+   * Called when the user submits a destination. The hook receives the
+   * generated code and is responsible for delivering it (email, SMS,
+   * etc.). Returning normally means "delivery attempted"; the framework
+   * does not inspect the outcome.
+   */
+  sendCode: (input: {
+    destination: string
+    code: string
+    tenantId: string
+  }) => Promise<void>
+  /**
+   * Override code generation. Default: 6-digit numeric.
+   *
+   * Kept on the factory closure (not per-tenant) because the generation
+   * algorithm is part of the host's overall deliverability + UX
+   * decisions, not something that should be reconfigured per tenant.
+   */
+  generateCode?: () => string
+}
+
+/**
+ * Per-tenant config. Host supplies these via `MethodConfig.config` so
+ * each tenant can ship its own code length, attempt cap, channel kind,
+ * and copy without instantiating a new factory.
+ */
+const configSchema = z.object({
+  /** Default 6. Range 4–10. */
+  codeLength: z.number().int().min(4).max(10).optional(),
+  /** Default 5. After this many failed verifies the flow is denied. */
+  maxAttempts: z.number().int().min(1).max(20).optional(),
+  /** Default "email". */
+  destinationKind: z.enum(["email", "tel", "any"]).optional(),
+  /** Form copy overrides. */
+  titles: z
+    .object({
+      request: z.string().optional(),
+      verify: z.string().optional(),
+    })
+    .optional(),
+})
+type CodeConfig = z.infer<typeof configSchema>
+
+const sendBody = z.object({
+  destination: z.string().min(1),
+})
+const verifyBody = z.object({
+  code: z.string().min(1),
+})
+
+export function codeMethod(
+  opts: CodeMethodOptions,
+): AuthMethodFactory<CodeProperties, CodeState, CodeConfig> {
+  const customGenerator = opts.generateCode
+  return {
+    kind: "code",
+    configSchema,
+    build: async ({
+      id,
+      kind,
+      config,
+    }): Promise<AuthMethod<CodeProperties, CodeState>> => {
+      const titleRequest = config.titles?.request ?? "Sign in"
+      const titleVerify = config.titles?.verify ?? "Enter your code"
+      const maxAttempts = config.maxAttempts ?? 5
+      const destinationKind = config.destinationKind ?? "email"
+      const codeLength = config.codeLength ?? 6
+      const generateCode = customGenerator ?? (() => defaultCode(codeLength))
+      return {
+        id,
+        kind,
+        type: "code",
+        routes: {
+          "GET /authorize": async (_ctx) => ({
+            kind: "challenge",
+            response: htmlResponse(
+              renderForm({
+                title: titleRequest,
+                action: `/m/${id}/send`,
+                fields: destinationField(destinationKind),
+                submit: "Send code",
+              }),
+            ),
+          }),
+          "POST /send": async (ctx) =>
+            handleSend(
+              ctx,
+              id,
+              titleRequest,
+              titleVerify,
+              destinationKind,
+              generateCode,
+              opts.sendCode,
+            ),
+          "POST /verify": async (ctx) =>
+            handleVerify(ctx, id, titleVerify, maxAttempts),
+        },
+      }
+    },
+  }
+}
+
+async function handleSend(
+  ctx: MethodContext<CodeState>,
+  methodId: string,
+  titleRequest: string,
+  titleVerify: string,
+  destinationKind: "email" | "tel" | "any",
+  generateCode: () => string,
+  sendCode: CodeMethodOptions["sendCode"],
+): Promise<MethodResult<CodeProperties, CodeState>> {
+  const form = await safeForm(ctx.request)
+  const parsed = sendBody.safeParse(form)
+  if (
+    !parsed.success ||
+    !validateDestination(parsed.data?.destination, destinationKind)
+  ) {
+    return {
+      kind: "challenge",
+      response: htmlResponse(
+        renderForm({
+          title: titleRequest,
+          action: `/m/${methodId}/send`,
+          fields: destinationField(destinationKind),
+          submit: "Send code",
+          error: "Please enter a valid destination.",
+        }),
+        400,
+      ),
+    }
+  }
+  const destination = parsed.data.destination
+  const code = generateCode()
+  // Side effect best-effort: deliveries can fail but we still render the
+  // verify form so we never leak whether the destination exists.
+  try {
+    await sendCode({ destination, code, tenantId: ctx.tenant.id })
+  } catch {
+    /* swallow — the user retries via the resend control. */
+  }
+  const hash = base64url.encode(await sha256(utf8.encode(code)))
+  return {
+    kind: "challenge",
+    response: htmlResponse(
+      renderForm({
+        title: titleVerify,
+        action: `/m/${methodId}/verify`,
+        fields: [
+          {
+            name: "code",
+            label: "Code",
+            required: true,
+            inputmode: "numeric",
+            autocomplete: "one-time-code",
+          },
+        ],
+        submit: "Verify",
+        hidden: { destination },
+      }),
+    ),
+    saveMethodState: {
+      destination,
+      codeHash: hash,
+      attempts: 0,
+    },
+  }
+}
+
+async function handleVerify(
+  ctx: MethodContext<CodeState>,
+  methodId: string,
+  titleVerify: string,
+  maxAttempts: number,
+): Promise<MethodResult<CodeProperties, CodeState>> {
+  if (!ctx.methodState) {
+    return {
+      kind: "error",
+      error: {
+        code: "invalid_request",
+        description: "verify without prior /send",
+      },
+    }
+  }
+  const state = ctx.methodState
+  if (state.attempts >= maxAttempts) {
+    return { kind: "denied", reason: "too_many_attempts" }
+  }
+
+  const form = await safeForm(ctx.request)
+  const parsed = verifyBody.safeParse(form)
+  if (!parsed.success) {
+    return verifyError(methodId, state, titleVerify, "Please enter the code.")
+  }
+
+  const submittedHash = base64url.encode(
+    await sha256(utf8.encode(parsed.data.code)),
+  )
+  if (!timingSafeEqualStr(submittedHash, state.codeHash)) {
+    return verifyError(
+      methodId,
+      { ...state, attempts: state.attempts + 1 },
+      titleVerify,
+      "Incorrect code. Please try again.",
+    )
+  }
+
+  return {
+    kind: "success",
+    providerSubject: state.destination,
+    properties: { destination: state.destination },
+  }
+}
+
+function verifyError(
+  methodId: string,
+  next: CodeState,
+  titleVerify: string,
+  error: string,
+): MethodResult<CodeProperties, CodeState> {
+  return {
+    kind: "challenge",
+    response: htmlResponse(
+      renderForm({
+        title: titleVerify,
+        action: `/m/${methodId}/verify`,
+        fields: [
+          {
+            name: "code",
+            label: "Code",
+            required: true,
+            inputmode: "numeric",
+            autocomplete: "one-time-code",
+          },
+        ],
+        submit: "Verify",
+        error,
+      }),
+      400,
+    ),
+    saveMethodState: { ...next, error },
+  }
+}
+
+function destinationField(kind: "email" | "tel" | "any") {
+  if (kind === "email") {
+    return [
+      {
+        name: "destination",
+        label: "Email",
+        type: "email" as const,
+        required: true,
+        autocomplete: "email",
+      },
+    ]
+  }
+  if (kind === "tel") {
+    return [
+      {
+        name: "destination",
+        label: "Phone",
+        type: "tel" as const,
+        required: true,
+        autocomplete: "tel",
+      },
+    ]
+  }
+  return [
+    {
+      name: "destination",
+      label: "Destination",
+      type: "text" as const,
+      required: true,
+    },
+  ]
+}
+
+function validateDestination(
+  destination: string | undefined,
+  kind: "email" | "tel" | "any",
+): destination is string {
+  if (!destination) return false
+  if (kind === "email") return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(destination)
+  if (kind === "tel") return /^[+\d][\d\s\-()]{6,}$/.test(destination)
+  return destination.length > 0
+}
+
+function defaultCode(length: number): string {
+  // Modulo over a uniform 32-bit draw — small skew on the high end of the
+  // range, fine for codes gated by rate limiting + max-attempts.
+  const buf = randomBytes(4)
+  const view = new DataView(buf.buffer, buf.byteOffset, 4)
+  const max = 10 ** length
+  const n = view.getUint32(0) % max
+  return n.toString().padStart(length, "0")
+}
+
+async function safeForm(req: Request): Promise<Record<string, string>> {
+  const ct = req.headers.get("content-type") ?? ""
+  if (!ct.toLowerCase().startsWith("application/x-www-form-urlencoded")) {
+    return {}
+  }
+  return Object.fromEntries(new URLSearchParams(await req.text()).entries())
+}
+
+function htmlResponse(body: string, status = 200): Response {
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8" },
+  })
+}

package/src/methods/m2m.ts

@@ -0,0 +1,82 @@
+/**
+ * `m2mMethod` — machine-to-machine factory (RFC 6749 §4.4 client_credentials).
+ *
+ * No URL routes. The factory ships only a `client` fn the framework invokes
+ * from `/token` after standard client authentication has succeeded. The
+ * fn validates and returns the `P` properties the success callback will
+ * map into the issued subject claim.
+ *
+ * Typical use: a tenant configures one m2m method instance per tenant.
+ * The user-supplied `verify` hook decides whether the (already
+ * authenticated) client is allowed to use this method and what claims it
+ * carries (org id, service tier, etc.).
+ */
+import { z } from "zod"
+
+import { authError } from "../types/error"
+import { err, ok, type Result } from "../types/result"
+import type { AuthMethod, AuthMethodFactory, ClientFn } from "../types/method"
+
+export type M2MProperties = {
+  /** The client's stable id (echoed back from the request). */
+  clientId: string
+  /** Tenant-supplied extra claims. */
+  claims?: Record<string, unknown>
+}
+
+export type M2MMethodOptions = {
+  /**
+   * Look up the client's per-client metadata. Return `null` for unauthorized
+   * (the framework already authenticated the secret; this is for
+   * application-level authorization — e.g. "is this client allowed to use
+   * this method?", "what claims should we attach?").
+   */
+  verify: (input: {
+    clientID: string
+    params: Record<string, string>
+    tenantId: string
+  }) => Promise<{ claims?: Record<string, unknown> } | null>
+}
+
+const configSchema = z.object({}).strict()
+type M2MConfig = z.infer<typeof configSchema>
+
+export function m2mMethod(
+  opts: M2MMethodOptions,
+): AuthMethodFactory<M2MProperties, never, M2MConfig> {
+  return {
+    kind: "m2m",
+    configSchema,
+    build: async ({
+      id,
+      kind,
+      tenantId,
+    }): Promise<AuthMethod<M2MProperties, never>> => {
+      const clientFn: ClientFn<M2MProperties> = async (
+        input,
+      ): Promise<
+        Result<M2MProperties, ReturnType<typeof authError.invalidClient>>
+      > => {
+        const verified = await opts.verify({
+          clientID: input.clientID,
+          params: input.params,
+          tenantId,
+        })
+        if (!verified) {
+          return err(authError.invalidClient("client not authorized for m2m"))
+        }
+        return ok({
+          clientId: input.clientID,
+          ...(verified.claims ? { claims: verified.claims } : {}),
+        })
+      }
+      return {
+        id,
+        kind,
+        type: "m2m",
+        routes: {},
+        client: clientFn,
+      }
+    },
+  }
+}

package/src/methods/oauth2-factory.ts

@@ -0,0 +1,151 @@
+/**
+ * `oauth2Factory` and `oidcFactory` — generic multi-tenant factories.
+ *
+ * Use these when each tenant brings its own OAuth 2.0 / OIDC issuer,
+ * client credentials, scopes, and endpoint URLs. The factory's
+ * `configSchema` accepts a per-tenant blob and `build()` delegates to
+ * `buildOauth2Method` / `buildOidcMethod` to produce the actual
+ * `AuthMethod`.
+ *
+ * For built-in vendor wrappers (Google, GitHub, Apple, etc.) see
+ * `./providers/*` — those bake in the issuer URL and provider quirks.
+ *
+ * For single-tenant deployments where the issuer / endpoints are
+ * compile-time constants, you can still call `buildOauth2Method` /
+ * `buildOidcMethod` directly inside your own `AuthMethodFactory` —
+ * those entry points are the underlying "build a static AuthMethod"
+ * primitives; this file just wraps them in the multi-tenant factory
+ * shape.
+ */
+import { z } from "zod"
+
+import { buildOauth2Method } from "./oauth2-generic"
+import { buildOidcMethod } from "./oidc-generic"
+import type { Oauth2Properties, Oauth2State } from "./oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../types/method"
+
+const oauth2ConfigSchema = z.object({
+  clientId: z.string().min(1),
+  clientSecret: z.string().min(1).optional(),
+  scopes: z.array(z.string()).min(1),
+  authorizationUrl: z.string().url(),
+  tokenUrl: z.string().url(),
+  jwksUri: z.string().url().optional(),
+  expectedIssuer: z.string().optional(),
+  extraAuthorizeParams: z.record(z.string()).optional(),
+  pkce: z.enum(["S256", "none"]).optional(),
+  responseMode: z.enum(["query", "form_post"]).optional(),
+})
+
+export type Oauth2FactoryConfig = z.infer<typeof oauth2ConfigSchema>
+
+/**
+ * Generic OAuth 2.0 factory.
+ *
+ * `kind: "oauth2"`. Use a different `MethodConfig.id` per instance to
+ * register multiple OAuth 2.0 upstreams against a single tenant.
+ */
+export const oauth2Factory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  Oauth2FactoryConfig
+> = {
+  kind: "oauth2",
+  configSchema: oauth2ConfigSchema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOauth2Method({
+      id,
+      kind,
+      clientId: config.clientId,
+      ...(config.clientSecret !== undefined
+        ? { clientSecret: config.clientSecret }
+        : {}),
+      scopes: config.scopes,
+      authorizationUrl: config.authorizationUrl,
+      tokenUrl: config.tokenUrl,
+      ...(config.jwksUri ? { jwksUri: config.jwksUri } : {}),
+      ...(config.expectedIssuer
+        ? { expectedIssuer: config.expectedIssuer }
+        : {}),
+      ...(config.extraAuthorizeParams
+        ? { extraAuthorizeParams: config.extraAuthorizeParams }
+        : {}),
+      ...(config.pkce ? { pkce: config.pkce } : {}),
+      ...(config.responseMode ? { responseMode: config.responseMode } : {}),
+    }),
+}
+
+const oidcConfigSchema = z.object({
+  issuer: z.string().url(),
+  clientId: z.string().min(1),
+  clientSecret: z.string().min(1).optional(),
+  scopes: z.array(z.string()).optional(),
+  extraAuthorizeParams: z.record(z.string()).optional(),
+  pkce: z.enum(["S256", "none"]).optional(),
+  responseMode: z.enum(["query", "form_post"]).optional(),
+  /**
+   * Skip discovery and use these endpoints directly. Useful for
+   * providers with non-standard or fragmented discovery
+   * (Microsoft tenant-templated, legacy stacks).
+   */
+  endpoints: z
+    .object({
+      authorization_endpoint: z.string().url(),
+      token_endpoint: z.string().url(),
+      jwks_uri: z.string().url(),
+      issuer: z.string(),
+    })
+    .optional(),
+})
+
+export type OidcFactoryConfig = z.infer<typeof oidcConfigSchema>
+
+/**
+ * Generic OIDC factory. Auto-discovers `<issuer>/.well-known/openid-
+ * configuration` unless `endpoints` is supplied.
+ *
+ * `kind: "oidc"`. Use a different `MethodConfig.id` per instance to
+ * register multiple OIDC upstreams against a single tenant.
+ */
+export const oidcFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  OidcFactoryConfig
+> = {
+  kind: "oidc",
+  configSchema: oidcConfigSchema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOidcMethod({
+      id,
+      kind,
+      issuer: config.issuer,
+      clientId: config.clientId,
+      ...(config.clientSecret !== undefined
+        ? { clientSecret: config.clientSecret }
+        : {}),
+      scopes: config.scopes ?? ["openid", "email", "profile"],
+      ...(config.extraAuthorizeParams
+        ? { extraAuthorizeParams: config.extraAuthorizeParams }
+        : {}),
+      ...(config.pkce ? { pkce: config.pkce } : {}),
+      ...(config.responseMode ? { responseMode: config.responseMode } : {}),
+      ...(config.endpoints
+        ? {
+            endpoints: {
+              authorization_endpoint: config.endpoints.authorization_endpoint,
+              token_endpoint: config.endpoints.token_endpoint,
+              jwks_uri: config.endpoints.jwks_uri,
+              issuer: config.endpoints.issuer,
+            },
+          }
+        : {}),
+    }),
+}