@_mustachio/openauth 0.9.1 → 0.10.0

package/src/http/router.ts

@@ -0,0 +1,66 @@
+/**
+ * Top-level Hono router for the IdP HTTP surface.
+ *
+ * Routes (Phase 3):
+ *   GET  /authorize                                    — start OAuth flow
+ *   POST /token                                         — exchange code / refresh
+ *   GET  /userinfo, POST /userinfo                      — OIDC claims
+ *   GET  /cb/:methodId{.*}                              — upstream callback
+ *   GET  /.well-known/openid-configuration              — discovery
+ *   GET  /.well-known/oauth-authorization-server        — discovery (alias)
+ *   GET  /.well-known/jwks.json                         — JWKS
+ *   POST /revoke                                        — RFC 7009
+ *   POST /introspect                                    — RFC 7662
+ *
+ * Hono is imported **only** from this directory. `domain/`, `methods/`,
+ * `types/`, `ports/`, and `adapters/` remain framework-agnostic.
+ */
+import { Hono } from "hono"
+
+import { makeAuthorizeHandler } from "./handlers/authorize"
+import { makeCallbackHandler } from "./handlers/callback"
+import { makeDiscoveryHandler, makeJwksHandler } from "./handlers/metadata"
+import { makeMethodRouteHandler } from "./handlers/method-route"
+import { makeIntrospectHandler, makeRevokeHandler } from "./handlers/revocation"
+import { makeTokenHandler } from "./handlers/token"
+import { makeUserinfoHandler } from "./handlers/userinfo"
+import { errorMiddleware } from "./middleware/error"
+import { bootstrapMiddleware, tenantMiddleware } from "./middleware/tenant"
+import type { HttpDeps, HttpEnv } from "./context"
+
+export function buildRouter(deps: HttpDeps): Hono<HttpEnv> {
+  const app = new Hono<HttpEnv>()
+
+  app.use("*", errorMiddleware(deps))
+  app.use("*", bootstrapMiddleware(deps))
+
+  // Public metadata — no tenant middleware required.
+  app.get("/.well-known/openid-configuration", makeDiscoveryHandler(deps))
+  app.get("/.well-known/oauth-authorization-server", makeDiscoveryHandler(deps))
+  app.get("/.well-known/jwks.json", makeJwksHandler(deps))
+
+  // Tenant-scoped endpoints.
+  app.use("/authorize", tenantMiddleware(deps))
+  app.get("/authorize", makeAuthorizeHandler(deps))
+
+  app.use("/cb/*", tenantMiddleware(deps))
+  app.get("/cb/*", makeCallbackHandler(deps))
+  // Apple `response_mode=form_post` and similar POST-binding callbacks.
+  app.post("/cb/*", makeCallbackHandler(deps))
+
+  // Credential-flow method routes — POST and GET allowed.
+  app.use("/m/*", tenantMiddleware(deps))
+  app.all("/m/*", makeMethodRouteHandler(deps))
+
+  // Token endpoint — tenant resolved from auth-code payload, not middleware.
+  app.post("/token", makeTokenHandler(deps))
+
+  // Userinfo — bearer token carries tenant claim (`tid`).
+  app.get("/userinfo", makeUserinfoHandler(deps))
+  app.post("/userinfo", makeUserinfoHandler(deps))
+
+  app.post("/revoke", makeRevokeHandler(deps))
+  app.post("/introspect", makeIntrospectHandler(deps))
+
+  return app
+}

package/src/http/schemas/authorize.ts

@@ -0,0 +1,58 @@
+/**
+ * Zod schemas for the `/authorize` endpoint.
+ *
+ * Parse the raw query into an `AuthorizationRequest` shape. We surface OAuth
+ * `invalid_request` (or the more specific `unsupported_response_type` /
+ * `invalid_scope`) for any structural failure here; downstream domain code
+ * then handles semantic validation (client lookup, redirect-uri match, PKCE
+ * requirement, etc.).
+ */
+import { z } from "zod"
+
+/** RFC 6749 scope-token regex (visible ASCII minus delimiters). */
+const SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]+$/
+
+const csv = z
+  .string()
+  .min(1)
+  .transform((s) =>
+    s
+      .split(/\s+/)
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0),
+  )
+
+const scopeParam = z
+  .string()
+  .transform((s) =>
+    s
+      .split(/\s+/)
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0),
+  )
+  .pipe(z.array(z.string().regex(SCOPE_TOKEN, "invalid scope token")))
+
+export const authorizeQuerySchema = z
+  .object({
+    response_type: z.string({
+      required_error: "missing response_type",
+    }),
+    client_id: z
+      .string({ required_error: "missing client_id" })
+      .min(1, "empty client_id"),
+    redirect_uri: z
+      .string({ required_error: "missing redirect_uri" })
+      .url("redirect_uri must be a valid URL"),
+    scope: scopeParam.optional(),
+    state: z.string().optional(),
+    audience: z.string().optional(),
+    method_id: z.string().optional(),
+    code_challenge: z.string().optional(),
+    code_challenge_method: z.literal("S256").optional(),
+    prompt: csv.optional(),
+    ui_locales: csv.optional(),
+    nonce: z.string().optional(),
+  })
+  .passthrough()
+
+export type AuthorizeQuery = z.infer<typeof authorizeQuerySchema>

package/src/http/schemas/revocation.ts

@@ -0,0 +1,23 @@
+/**
+ * Zod schemas for RFC 7009 `/revoke` and RFC 7662 `/introspect`. Both are
+ * advertised in discovery from Phase 3 onward; their HTTP shims live here so
+ * the domain functions are reachable without waiting for Phase 8.
+ */
+import { z } from "zod"
+
+export const revokeBodySchema = z.object({
+  token: z.string().min(1, "missing token"),
+  token_type_hint: z.enum(["access_token", "refresh_token"]).optional(),
+  client_id: z.string().optional(),
+  client_secret: z.string().optional(),
+})
+
+export const introspectBodySchema = z.object({
+  token: z.string().min(1, "missing token"),
+  token_type_hint: z.enum(["access_token", "refresh_token"]).optional(),
+  client_id: z.string().optional(),
+  client_secret: z.string().optional(),
+})
+
+export type RevokeBody = z.infer<typeof revokeBodySchema>
+export type IntrospectBody = z.infer<typeof introspectBodySchema>

package/src/http/schemas/token.ts

@@ -0,0 +1,85 @@
+/**
+ * Zod schemas for the `/token` endpoint.
+ *
+ * The endpoint accepts `application/x-www-form-urlencoded` per RFC 6749.
+ * `grant_type` discriminates between the supported grants:
+ *   - `authorization_code`
+ *   - `refresh_token`
+ *   - `client_credentials`
+ *   - `urn:ietf:params:oauth:grant-type:token-exchange` (RFC 8693)
+ */
+import { z } from "zod"
+
+/** RFC 8693 §3 token-type identifiers used at this endpoint. */
+export const TOKEN_EXCHANGE_GRANT_TYPE =
+  "urn:ietf:params:oauth:grant-type:token-exchange" as const
+export const ACCESS_TOKEN_TYPE =
+  "urn:ietf:params:oauth:token-type:access_token" as const
+export const REFRESH_TOKEN_TYPE =
+  "urn:ietf:params:oauth:token-type:refresh_token" as const
+
+export const authorizationCodeGrantSchema = z.object({
+  grant_type: z.literal("authorization_code"),
+  code: z.string().min(1, "missing code"),
+  redirect_uri: z.string().url("invalid redirect_uri"),
+  client_id: z.string().min(1, "missing client_id"),
+  client_secret: z.string().optional(),
+  code_verifier: z.string().optional(),
+})
+
+export const refreshTokenGrantSchema = z.object({
+  grant_type: z.literal("refresh_token"),
+  refresh_token: z.string().min(1, "missing refresh_token"),
+  scope: z.string().optional(),
+  client_id: z.string().optional(),
+  client_secret: z.string().optional(),
+})
+
+export const clientCredentialsGrantSchema = z
+  .object({
+    grant_type: z.literal("client_credentials"),
+    client_id: z.string().min(1, "missing client_id"),
+    client_secret: z.string().min(1, "missing client_secret"),
+    scope: z.string().optional(),
+    audience: z.string().optional(),
+    resource: z.string().optional(),
+  })
+  .passthrough()
+
+/**
+ * RFC 8693 §2.1 token-exchange request.
+ *
+ * `subject_token_type` MUST identify the type of `subject_token`. We only
+ * accept access tokens here — refresh-token-as-subject is out of scope.
+ *
+ * `audience` is opaque to the library; the host's `exchangeAudience`
+ * hook decides what counts as a legal target. In our two-level
+ * `App × App-Tenant` encoding pattern this is the new `TenantId`.
+ *
+ * `actor_token` (delegation) is intentionally rejected at the handler;
+ * only impersonation / audience-switching is supported in this phase.
+ */
+export const tokenExchangeGrantSchema = z
+  .object({
+    grant_type: z.literal(TOKEN_EXCHANGE_GRANT_TYPE),
+    subject_token: z.string().min(1, "missing subject_token"),
+    subject_token_type: z.literal(ACCESS_TOKEN_TYPE),
+    audience: z.string().min(1, "missing audience"),
+    requested_token_type: z.literal(ACCESS_TOKEN_TYPE).optional(),
+    scope: z.string().optional(),
+    client_id: z.string().optional(),
+    client_secret: z.string().optional(),
+    actor_token: z.string().optional(),
+    actor_token_type: z.string().optional(),
+    resource: z.string().optional(),
+  })
+  .passthrough()
+
+export const tokenRequestSchema = z.discriminatedUnion("grant_type", [
+  authorizationCodeGrantSchema,
+  refreshTokenGrantSchema,
+  clientCredentialsGrantSchema,
+  tokenExchangeGrantSchema,
+])
+
+export type TokenRequest = z.infer<typeof tokenRequestSchema>

package/src/index.ts

@@ -1,26 +1,272 @@
-export {
-  /**
-   * @deprecated
-   * Use `import { createClient } from "@openauthjs/openauth/client"` instead - it will tree shake better
-   */
-  createClient,
-} from "./client.js"
+/**
+ * `@_mustachio/openauth` — public entry point.
+ *
+ * Library-only IdP surface: domain logic + ports + adapters. Consumers
+ * embed this in a host application that owns UI, RBAC, admin, and tenant
+ * management. See `docs/integration-guide.md` for the embedding pattern.
+ *
+ * `createClient` continues to ship at the dedicated path
+ * `@_mustachio/openauth/client` (better tree-shaking than re-exporting
+ * it from the root).
+ */
+
+// ─── New IdP public API ───
+
+export type { Result } from "./types/result"
+export { err, isErr, isOk, ok } from "./types/result"
+
+export type { AuthError, AuthErrorCode } from "./types/error"
+export { authError } from "./types/error"
+
+export type {
+  ClientConfig,
+  ConfidentialClientConfig,
+  GrantType,
+  MethodConfig,
+  MethodType,
+  PublicClientConfig,
+  StateEnvelope,
+  StateKey,
+  StateKeyRing,
+  TenantConfig,
+  TenantContext,
+  TenantId,
+  TenantRecovery,
+  ThemeConfig,
+} from "./types/tenant"
+export { asTenantId } from "./types/tenant"
+
+export type { FlowRecord } from "./types/flow"
+
+export type {
+  AuthMethod,
+  AuthMethodFactory,
+  CachePolicy,
+  ClientFn,
+  MethodContext,
+  MethodDispatchData,
+  MethodHandler,
+  MethodResult,
+  SetCookie,
+} from "./types/method"
+
+export type {
+  AuthorizationRequest,
+  AuthorizationState,
+} from "./types/authorization"
+
+export type {
+  AccessTokenClaims,
+  CodePayload,
+  RefreshTokenPayload,
+  TokenResponse,
+} from "./types/token"
+
+export type {
+  SubjectClaim,
+  SubjectPayload,
+  SubjectSchema,
+} from "./types/subject"
+
+export type {
+  ExchangeAudience,
+  FailureEvent,
+  IdP,
+  IdPOptions,
+  PersistUpstreamTokens,
+  RenderPicker,
+  SuccessEvent,
+  SuccessMapInput,
+} from "./types/idp"
+
+export type { PickerContext, PickerMethod } from "./types/picker"
+
+export type { AuditEvent, AuditLog } from "./ports/audit-log"
+export type { ConfigStore } from "./ports/config-store"
+export type {
+  EncryptionKey,
+  KeyStore,
+  KeyWrapper,
+  SigningKey,
+} from "./ports/key-store"
+export type { MethodStore } from "./ports/method-store"
+export type { SessionRecord, SessionStore } from "./ports/session-store"
+export type { TokenStore } from "./ports/token-store"
+
+/**
+ * Host-callable primitive for "log me out of all devices" UX. Wraps
+ * `TokenStore.revokeBySubject` with the framework's audit emission so
+ * hosts don't need to reimplement it. Reuse-detection escalation itself
+ * stays at family-scope per OAuth 2.0 Security BCP §4.13.2 (see
+ * ARCHITECTURE.md "Reuse detection scope").
+ */
+export { revokeAllForSubject } from "./domain/revoke"
+
+// Phase 4 — credential + WebAuthn method factories.
+export { passwordMethod } from "./methods/password"
+export type {
+  PasswordMethodOptions,
+  PasswordProperties,
+  PasswordUser,
+  PasswordUserStore,
+  PasswordState,
+} from "./methods/password"
+export { codeMethod } from "./methods/code"
+export type {
+  CodeMethodOptions,
+  CodeProperties,
+  CodeState,
+} from "./methods/code"
+export { m2mMethod } from "./methods/m2m"
+export type { M2MMethodOptions, M2MProperties } from "./methods/m2m"
+export { passkeyMethod } from "./methods/passkey"
+export type {
+  PasskeyMethodOptions,
+  PasskeyProperties,
+  PasskeyState,
+  PasskeyCredentialStore,
+  StoredCredential,
+} from "./methods/passkey"
 
 export {
-  /**
-   * @deprecated
-   * Use `import { createSubjects } from "@openauthjs/openauth/subject"` instead - it will tree shake better
-   */
-  createSubjects,
-} from "./subject.js"
+  argon2idHasher,
+  DEFAULT_ARGON2ID_PARAMS,
+} from "./methods/password-hash"
+export type { PasswordHasher, Argon2idParams } from "./methods/password-hash"
+
+// Phase 5 — OAuth / OIDC provider factories.
+export { buildOauth2Method } from "./methods/oauth2-generic"
+export type {
+  Oauth2MethodInput,
+  Oauth2Properties,
+  Oauth2State,
+} from "./methods/oauth2-generic"
+export { buildOidcMethod } from "./methods/oidc-generic"
+export type { OidcMethodInput } from "./methods/oidc-generic"
 
-import { issuer } from "./issuer.js"
+// Generic multi-tenant factories. Reach for these first when each
+// tenant brings its own issuer / client credentials. The vendor
+// factories above (googleFactory etc.) are convenience wrappers when
+// the issuer is fixed.
+export {
+  oauth2Factory,
+  oidcFactory,
+  type Oauth2FactoryConfig,
+  type OidcFactoryConfig,
+} from "./methods/oauth2-factory"
 
 export {
-  /**
-   * @deprecated
-   * Use `import { issuer } from "@openauthjs/openauth"` instead, it was renamed
-   */
-  issuer as authorizer,
-  issuer,
+  appleFactory,
+  cognitoFactory,
+  discordFactory,
+  facebookFactory,
+  githubFactory,
+  googleFactory,
+  jumpcloudFactory,
+  keycloakFactory,
+  linkedinFactory,
+  microsoftFactory,
+  slackFactory,
+  spotifyFactory,
+  twitchFactory,
+  xFactory,
+  yahooFactory,
+} from "./methods/providers"
+
+import type { IdP, IdPOptions } from "./types/idp"
+import { MethodCache } from "./domain/method-cache"
+import { buildRouter } from "./http/router"
+import type { HttpDeps } from "./http/context"
+
+/**
+ * Construct a new IdP from the supplied options.
+ *
+ * Phase 3 ships the full HTTP surface backed by the Phase 2 domain
+ * functions. Wire up:
+ *
+ *  - A `MethodCache` over the configured factories. The factory map's
+ *    keys MUST equal each factory's `kind`; we throw on construction if
+ *    any disagree.
+ *  - A `HttpDeps` record passed into the Hono router.
+ *  - The returned `IdP.handle` is `app.fetch.bind(app)`; the per-endpoint
+ *    primitives (`authorize`, `token`, etc.) re-enter the same app.
+ */
+export function createIdP(opts: IdPOptions): IdP {
+  // Validate factory-key invariant before any request can hit a bad map.
+  const mismatched = Object.entries(opts.methods)
+    .filter(([key, factory]) => key !== factory.kind)
+    .map(([key, factory]) => `${key}!=${factory.kind}`)
+  if (mismatched.length > 0) {
+    throw new Error(
+      `createIdP: methods map keys must equal factory.kind. Offenders: ${mismatched.join(", ")}`,
+    )
+  }
+
+  const clock = () => Date.now()
+  const auditLog = opts.auditLog
+  const methodCache = new MethodCache({
+    factories: opts.methods,
+    ...(auditLog ? { auditLog } : {}),
+    now: clock,
+  })
+
+  // Tenant-config rotation must bust the cached `AuthMethod` instances,
+  // otherwise upstream client-secret changes (Google / Okta / etc.) are
+  // ignored because `buildOauth2Method` / `buildOidcMethod` capture the
+  // old secret in a closure. `ConfigStore.onInvalidate` is the canonical
+  // signal — adapters fire it from `putTenantConfig` and from any
+  // host-driven cross-process invalidation hook.
+  opts.configStore.onInvalidate?.((tenantId) => {
+    methodCache.invalidate(tenantId)
+  })
+
+  const resolveIssuer = (req: Request): string =>
+    typeof opts.issuerUrl === "string" ? opts.issuerUrl : opts.issuerUrl(req)
+
+  const deps: HttpDeps = {
+    configStore: opts.configStore,
+    tokenStore: opts.tokenStore,
+    sessionStore: opts.sessionStore,
+    keyStore: opts.keyStore,
+    ...(opts.methodStore ? { methodStore: opts.methodStore } : {}),
+    ...(auditLog ? { auditLog } : {}),
+    methodCache,
+    stateKeys: opts.stateKeys,
+    resolveIssuer,
+    ...(opts.callbackHostFor ? { callbackHostFor: opts.callbackHostFor } : {}),
+    resolveTenant: opts.resolveTenant,
+    success: opts.success,
+    ...(opts.persistUpstreamTokens
+      ? { persistUpstreamTokens: opts.persistUpstreamTokens }
+      : {}),
+    ...(opts.exchangeAudience
+      ? { exchangeAudience: opts.exchangeAudience }
+      : {}),
+    ...(opts.renderPicker ? { renderPicker: opts.renderPicker } : {}),
+    ...(opts.buildCustomContext
+      ? { buildCustomContext: opts.buildCustomContext }
+      : {}),
+    clock,
+    cookieDefaults: {
+      secure: opts.cookies?.secure ?? true,
+      ...(opts.cookies?.domain !== undefined
+        ? { domain: opts.cookies.domain }
+        : {}),
+      ...(opts.cookies?.path !== undefined ? { path: opts.cookies.path } : {}),
+    },
+  }
+
+  const app = buildRouter(deps)
+  const fetch = async (req: Request): Promise<Response> => await app.fetch(req)
+
+  return {
+    handle: fetch,
+    authorize: fetch,
+    token: fetch,
+    userinfo: fetch,
+    jwks: fetch,
+    discovery: fetch,
+    revoke: fetch,
+    introspect: fetch,
+  }
 }