@_mustachio/openauth 0.9.2 → 0.11.0

package/src/methods/password.ts

@@ -0,0 +1,298 @@
+/**
+ * `passwordMethod` — username + password credential factory.
+ *
+ * Routes:
+ *   GET  /authorize   → render login form
+ *   POST /login       → verify credentials
+ *   POST /register    → create user + sign in
+ *
+ * Forgot / reset flows land in Phase 5 alongside email-sender infra (they
+ * share the same `sendEmail`-style hook the magic-code method uses).
+ *
+ * Storage: the framework does NOT own the user record. Users supply a
+ * `users` interface (lookup / create / setPassword); the method calls into
+ * it. Hashes are stored via the supplied `users.setPassword` hook so apps
+ * can keep them in the same row as the rest of their user data.
+ *
+ * Hashing: argon2id by default (`@noble/hashes/argon2`). Pluggable via
+ * `passwordMethod({ hasher: customHasher })` for migrations.
+ */
+import { z } from "zod"
+
+import { argon2idHasher, type PasswordHasher } from "./password-hash"
+import type {
+  AuthMethod,
+  AuthMethodFactory,
+  MethodContext,
+  MethodResult,
+} from "../types/method"
+import { renderForm } from "../ui/forms"
+
+export type PasswordProperties = {
+  /** The user's lookup key (typically their email). */
+  email: string
+  /** Optional extra claims the user store returned alongside the record. */
+  claims?: Record<string, unknown>
+}
+
+export type PasswordState = {
+  /** Most-recent error message to surface on re-render. */
+  error?: string
+}
+
+export type PasswordUser = {
+  /** Stable internal id (provider subject). */
+  id: string
+  /** Argon2id-format hash. Compared via the configured hasher. */
+  passwordHash: string
+  /** Optional extra claims that ride along to the IdP's success callback. */
+  claims?: Record<string, unknown>
+}
+
+export type PasswordUserStore = {
+  /** Look up a user by email; `null` if unknown. */
+  findByEmail(email: string, tenantId: string): Promise<PasswordUser | null>
+  /**
+   * Optional — only required if `enableRegistration: true`. Should create
+   * the row and return the persisted user. Implementations decide how to
+   * race with concurrent registrations.
+   */
+  create?(input: {
+    email: string
+    passwordHash: string
+    tenantId: string
+  }): Promise<PasswordUser>
+}
+
+export type PasswordMethodOptions = {
+  /** The tenant-supplied user store. */
+  users: PasswordUserStore
+  /** Override the default argon2id hasher. */
+  hasher?: PasswordHasher
+  /** Allow `POST /register` to create new users. Default: false. */
+  enableRegistration?: boolean
+  /** Display title for the form. */
+  title?: string
+}
+
+/** Tenant-supplied config is empty for password — users + hasher live on the factory closure. */
+const configSchema = z.object({}).strict()
+type PasswordConfig = z.infer<typeof configSchema>
+
+const loginBodySchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(1),
+})
+
+const registerBodySchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+})
+
+export function passwordMethod(
+  opts: PasswordMethodOptions,
+): AuthMethodFactory<PasswordProperties, PasswordState, PasswordConfig> {
+  const hasher = opts.hasher ?? argon2idHasher()
+  const title = opts.title ?? "Sign in"
+
+  return {
+    kind: "password",
+    configSchema,
+    build: async ({
+      id,
+      kind,
+    }): Promise<AuthMethod<PasswordProperties, PasswordState>> => ({
+      id,
+      kind,
+      type: "password",
+      routes: {
+        "GET /authorize": async (ctx) => renderLogin(ctx, id, title),
+        "POST /login": async (ctx) =>
+          handleLogin(ctx, id, title, opts.users, hasher),
+        "POST /register": async (ctx) => {
+          if (!opts.enableRegistration || !opts.users.create) {
+            return {
+              kind: "error",
+              error: {
+                code: "invalid_request",
+                description: "registration disabled",
+              },
+            }
+          }
+          return handleRegister(
+            ctx,
+            id,
+            title,
+            opts.users.create,
+            opts.users,
+            hasher,
+          )
+        },
+      },
+    }),
+  }
+}
+
+async function renderLogin(
+  ctx: MethodContext<PasswordState>,
+  methodId: string,
+  title: string,
+): Promise<MethodResult<PasswordProperties, PasswordState>> {
+  const body = renderForm({
+    title,
+    action: `/m/${methodId}/login`,
+    fields: [
+      {
+        name: "email",
+        label: "Email",
+        type: "email",
+        required: true,
+        autocomplete: "username",
+      },
+      {
+        name: "password",
+        label: "Password",
+        type: "password",
+        required: true,
+        autocomplete: "current-password",
+      },
+    ],
+    submit: "Sign in",
+    ...(ctx.methodState?.error ? { error: ctx.methodState.error } : {}),
+  })
+  return {
+    kind: "challenge",
+    response: new Response(body, {
+      status: 200,
+      headers: { "content-type": "text/html; charset=utf-8" },
+    }),
+  }
+}
+
+async function handleLogin(
+  ctx: MethodContext<PasswordState>,
+  methodId: string,
+  title: string,
+  users: PasswordUserStore,
+  hasher: PasswordHasher,
+): Promise<MethodResult<PasswordProperties, PasswordState>> {
+  const form = await safeForm(ctx.request)
+  const parsed = loginBodySchema.safeParse(form)
+  if (!parsed.success) {
+    return reLoginWithError(
+      methodId,
+      title,
+      "Please enter your email and password.",
+    )
+  }
+
+  const user = await users.findByEmail(parsed.data.email, ctx.tenant.id)
+  if (!user) {
+    return reLoginWithError(methodId, title, "Invalid email or password.")
+  }
+
+  const verified = await hasher.verify(parsed.data.password, user.passwordHash)
+  if (!verified) {
+    return reLoginWithError(methodId, title, "Invalid email or password.")
+  }
+
+  return {
+    kind: "success",
+    providerSubject: user.id,
+    properties: {
+      email: parsed.data.email,
+      ...(user.claims ? { claims: user.claims } : {}),
+    },
+  }
+}
+
+async function handleRegister(
+  ctx: MethodContext<PasswordState>,
+  methodId: string,
+  title: string,
+  create: NonNullable<PasswordUserStore["create"]>,
+  users: PasswordUserStore,
+  hasher: PasswordHasher,
+): Promise<MethodResult<PasswordProperties, PasswordState>> {
+  const form = await safeForm(ctx.request)
+  const parsed = registerBodySchema.safeParse(form)
+  if (!parsed.success) {
+    return reLoginWithError(
+      methodId,
+      title,
+      "Password must be at least 8 characters and email must be valid.",
+    )
+  }
+
+  const existing = await users.findByEmail(parsed.data.email, ctx.tenant.id)
+  if (existing) {
+    return reLoginWithError(
+      methodId,
+      title,
+      "An account with that email already exists.",
+    )
+  }
+
+  const passwordHash = await hasher.hash(parsed.data.password)
+  const user = await create({
+    email: parsed.data.email,
+    passwordHash,
+    tenantId: ctx.tenant.id,
+  })
+  return {
+    kind: "success",
+    providerSubject: user.id,
+    properties: {
+      email: parsed.data.email,
+      ...(user.claims ? { claims: user.claims } : {}),
+    },
+  }
+}
+
+function reLoginWithError(
+  methodId: string,
+  title: string,
+  error: string,
+): MethodResult<PasswordProperties, PasswordState> {
+  return {
+    kind: "challenge",
+    response: new Response(
+      renderForm({
+        title,
+        action: `/m/${methodId}/login`,
+        fields: [
+          {
+            name: "email",
+            label: "Email",
+            type: "email",
+            required: true,
+            autocomplete: "username",
+          },
+          {
+            name: "password",
+            label: "Password",
+            type: "password",
+            required: true,
+            autocomplete: "current-password",
+          },
+        ],
+        submit: "Sign in",
+        error,
+      }),
+      {
+        status: 400,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      },
+    ),
+    saveMethodState: { error },
+  }
+}
+
+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 {}
+  }
+  const params = new URLSearchParams(await req.text())
+  return Object.fromEntries(params.entries())
+}

package/src/methods/providers/apple.ts

@@ -0,0 +1,42 @@
+/**
+ * Apple — OIDC. Auto-discovers from `https://appleid.apple.com`.
+ *
+ * Apple requires `response_mode=form_post` when `name` / `email` scopes
+ * are requested. Pass `responseMode: "form_post"` when those scopes are
+ * in play; default is `query`.
+ */
+import { z } from "zod"
+
+import { buildOidcMethod } from "../oidc-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+  responseMode: z.enum(["query", "form_post"]).optional(),
+})
+
+export const appleFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "apple",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOidcMethod({
+      id,
+      kind,
+      issuer: "https://appleid.apple.com",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["openid", "name", "email"],
+      ...(config.responseMode ? { responseMode: config.responseMode } : {}),
+    }),
+}

package/src/methods/providers/cognito.ts

@@ -0,0 +1,55 @@
+/**
+ * AWS Cognito — OIDC. The `domain` is the Cognito user-pool domain
+ * (without protocol), e.g. `"my-pool.auth.us-east-1.amazoncognito.com"`.
+ *
+ * Cognito's OIDC discovery is at
+ * `https://cognito-idp.<region>.amazonaws.com/<userPoolId>/.well-known/openid-configuration`
+ * (NOT the user-pool domain). Callers supply the user-pool domain for the
+ * OAuth endpoints AND the issuer URL for discovery / id_token validation.
+ */
+import { z } from "zod"
+
+import { buildOidcMethod } from "../oidc-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string().optional(),
+  /** Cognito user-pool hosted UI domain (no protocol). */
+  domain: z.string(),
+  /** Issuer URL, e.g. `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xyz`. */
+  issuer: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const cognitoFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "cognito",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> => {
+    return buildOidcMethod({
+      id,
+      kind,
+      issuer: config.issuer,
+      // Cognito's hosted UI endpoints are separate from its discovery doc.
+      // Pin them explicitly so we don't double-fetch.
+      endpoints: {
+        authorization_endpoint: `https://${config.domain}/oauth2/authorize`,
+        token_endpoint: `https://${config.domain}/oauth2/token`,
+        jwks_uri: `${config.issuer.replace(/\/+$/, "")}/.well-known/jwks.json`,
+        issuer: config.issuer,
+      },
+      clientId: config.clientId,
+      ...(config.clientSecret ? { clientSecret: config.clientSecret } : {}),
+      scopes: config.scopes ?? ["openid", "email", "profile"],
+    })
+  },
+}

package/src/methods/providers/discord.ts

@@ -0,0 +1,37 @@
+/**
+ * Discord — OAuth 2.0. Default scopes: `identify email`.
+ */
+import { z } from "zod"
+
+import { buildOauth2Method } from "../oauth2-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const discordFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "discord",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOauth2Method({
+      id,
+      kind,
+      authorizationUrl: "https://discord.com/oauth2/authorize",
+      tokenUrl: "https://discord.com/api/oauth2/token",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["identify", "email"],
+    }),
+}

package/src/methods/providers/facebook.ts

@@ -0,0 +1,54 @@
+/**
+ * Facebook — OAuth 2.0. Default scopes: `email public_profile`.
+ *
+ * Facebook also exposes an OIDC discovery doc at
+ * `https://graph.facebook.com`, but the canonical app integration uses
+ * the OAuth 2.0 endpoints below. Pass `useOidc: true` to switch to OIDC.
+ */
+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 schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+  useOidc: z.boolean().optional(),
+})
+
+export const facebookFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "facebook",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> => {
+    if (config.useOidc) {
+      return buildOidcMethod({
+        id,
+        kind,
+        issuer: "https://graph.facebook.com",
+        clientId: config.clientId,
+        clientSecret: config.clientSecret,
+        scopes: config.scopes ?? ["openid", "email", "public_profile"],
+      })
+    }
+    return buildOauth2Method({
+      id,
+      kind,
+      authorizationUrl: "https://www.facebook.com/v12.0/dialog/oauth",
+      tokenUrl: "https://graph.facebook.com/v12.0/oauth/access_token",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["email", "public_profile"],
+    })
+  },
+}

package/src/methods/providers/github.ts

@@ -0,0 +1,42 @@
+/**
+ * GitHub — OAuth 2.0. No id_token; user info via the REST API in the
+ * `success` callback if needed.
+ *
+ * Default scopes: `read:user user:email`.
+ */
+import { z } from "zod"
+
+import { buildOauth2Method } from "../oauth2-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const githubFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "github",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOauth2Method({
+      id,
+      kind,
+      authorizationUrl: "https://github.com/login/oauth/authorize",
+      tokenUrl: "https://github.com/login/oauth/access_token",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["read:user", "user:email"],
+      // GitHub doesn't accept PKCE on the standard OAuth flow.
+      pkce: "none",
+    }),
+}

package/src/methods/providers/google.ts

@@ -0,0 +1,43 @@
+/**
+ * Google — OIDC (auto-discovers `https://accounts.google.com`).
+ *
+ * Default scopes: `openid email profile`. Pass `hostedDomain` to restrict
+ * to a Google Workspace domain.
+ */
+import { z } from "zod"
+
+import { buildOidcMethod } from "../oidc-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+  hostedDomain: z.string().optional(),
+})
+
+export const googleFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "google",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOidcMethod({
+      id,
+      kind,
+      issuer: "https://accounts.google.com",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["openid", "email", "profile"],
+      ...(config.hostedDomain
+        ? { extraAuthorizeParams: { hd: config.hostedDomain } }
+        : {}),
+    }),
+}

package/src/methods/providers/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Pre-configured OAuth/OIDC provider factories.
+ *
+ * Each factory is a thin wrapper over `buildOauth2Method` or
+ * `buildOidcMethod` that bakes in endpoint URLs and provider quirks.
+ * Tenants supply credentials via `MethodConfig.config`; the generic
+ * methods own the rest.
+ */
+export { googleFactory } from "./google"
+export { githubFactory } from "./github"
+export { appleFactory } from "./apple"
+export { microsoftFactory } from "./microsoft"
+export { discordFactory } from "./discord"
+export { facebookFactory } from "./facebook"
+export { linkedinFactory } from "./linkedin"
+export { slackFactory } from "./slack"
+export { spotifyFactory } from "./spotify"
+export { twitchFactory } from "./twitch"
+export { xFactory } from "./x"
+export { yahooFactory } from "./yahoo"
+export { jumpcloudFactory } from "./jumpcloud"
+export { keycloakFactory } from "./keycloak"
+export { cognitoFactory } from "./cognito"

package/src/methods/providers/jumpcloud.ts

@@ -0,0 +1,36 @@
+/**
+ * JumpCloud — OIDC, fully spec-compliant discovery doc.
+ */
+import { z } from "zod"
+
+import { buildOidcMethod } from "../oidc-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const jumpcloudFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "jumpcloud",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOidcMethod({
+      id,
+      kind,
+      issuer: "https://oauth.id.jumpcloud.com",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["openid", "email", "profile"],
+    }),
+}

package/src/methods/providers/keycloak.ts

@@ -0,0 +1,42 @@
+/**
+ * Keycloak — OIDC, per-realm. Issuer is templated from `baseUrl` + `realm`.
+ */
+import { z } from "zod"
+
+import { buildOidcMethod } from "../oidc-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  /** Keycloak base URL, e.g. `https://auth.example.com`. */
+  baseUrl: z.string(),
+  /** Realm name, e.g. `"acme"`. */
+  realm: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const keycloakFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "keycloak",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> => {
+    const base = config.baseUrl.replace(/\/+$/, "")
+    return buildOidcMethod({
+      id,
+      kind,
+      issuer: `${base}/realms/${config.realm}`,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["openid", "email", "profile"],
+    })
+  },
+}