@atproto/oauth-provider 0.3.1 → 0.5.0

package/src/oauth-provider.ts

@@ -1,5 +1,4 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
-import { mediaType } from '@hapi/accept'
 import createHttpError from 'http-errors'
 import type { Redis, RedisOptions } from 'ioredis'
 import { ZodError, z } from 'zod'
@@ -39,14 +38,16 @@ import { AccountManager } from './account/account-manager.js'
 import {
   AccountStore,
   DeviceAccountInfo,
-  SignInCredentials,
   asAccountStore,
-  signInCredentialsSchema,
+  handleSchema,
+  resetPasswordConfirmDataSchema,
+  resetPasswordRequestDataSchema,
 } from './account/account-store.js'
 import { Account } from './account/account.js'
+import { signInDataSchema } from './account/sign-in-data.js'
+import { signUpDataSchema } from './account/sign-up-data.js'
 import { authorizeAssetsMiddleware } from './assets/assets-middleware.js'
 import { ClientAuth, authJwkThumbprint } from './client/client-auth.js'
-import { ClientId, clientIdSchema } from './client/client-id.js'
 import {
   ClientManager,
   LoopbackMetadataGetter,
@@ -55,7 +56,12 @@ import { ClientStore, ifClientStore } from './client/client-store.js'
 import { Client } from './client/client.js'
 import { AUTHENTICATION_MAX_AGE, TOKEN_MAX_AGE } from './constants.js'
 import { DeviceId } from './device/device-id.js'
-import { DeviceManager, DeviceManagerOptions } from './device/device-manager.js'
+import {
+  DeviceInfo,
+  DeviceManager,
+  DeviceManagerOptions,
+  deviceManagerOptionsSchema,
+} from './device/device-manager.js'
 import { DeviceStore, asDeviceStore } from './device/device-store.js'
 import { AccessDeniedError } from './errors/access-denied-error.js'
 import { AccountSelectionRequiredError } from './errors/account-selection-required-error.js'
@@ -65,13 +71,14 @@ import { InvalidGrantError } from './errors/invalid-grant-error.js'
 import { InvalidParametersError } from './errors/invalid-parameters-error.js'
 import { InvalidRequestError } from './errors/invalid-request-error.js'
 import { LoginRequiredError } from './errors/login-required-error.js'
-import { OAuthError } from './errors/oauth-error.js'
 import { UnauthorizedClientError } from './errors/unauthorized-client-error.js'
 import { WWWAuthenticateError } from './errors/www-authenticate-error.js'
+import { HcaptchaConfig } from './lib/hcaptcha.js'
 import {
   Handler,
   Middleware,
   Router,
+  cacheControlMiddleware,
   combineMiddlewares,
   parseHttpRequest,
   setupCsrfToken,
@@ -84,18 +91,26 @@ import {
   validateSameOrigin,
   writeJson,
 } from './lib/http/index.js'
-import { RequestMetadata } from './lib/http/request.js'
+import {
+  RequestMetadata,
+  extractLocales,
+  negotiateResponseContent as negotiateContent,
+} from './lib/http/request.js'
 import { dateToEpoch, dateToRelativeSeconds } from './lib/util/date.js'
-import { Override } from './lib/util/type.js'
+import { Awaitable, Override } from './lib/util/type.js'
 import { CustomMetadata, buildMetadata } from './metadata/build-metadata.js'
-import { OAuthHooks } from './oauth-hooks.js'
+import { OAuthHooks, SignInData, SignUpData } from './oauth-hooks.js'
 import { OAuthVerifier, OAuthVerifierOptions } from './oauth-verifier.js'
 import { AuthorizationResultAuthorize } from './output/build-authorize-data.js'
+import {
+  BrandingConfig,
+  Customization,
+  customizationSchema,
+} from './output/build-customization-data.js'
 import {
   buildErrorPayload,
   buildErrorStatus,
 } from './output/build-error-payload.js'
-import { Customization } from './output/customization.js'
 import { OutputManager } from './output/output-manager.js'
 import {
   AuthorizationResultRedirect,
@@ -114,32 +129,36 @@ import { TokenManager } from './token/token-manager.js'
 import { TokenStore, asTokenStore } from './token/token-store.js'
 import { VerifyTokenClaimsOptions } from './token/verify-token-claims.js'
 
-export type OAuthProviderStore = Partial<
-  ClientStore &
-    AccountStore &
-    DeviceStore &
-    TokenStore &
-    RequestStore &
-    ReplayStore
->
-
 export {
+  type BrandingConfig,
   type CustomMetadata,
   type Customization,
   type Handler,
+  type HcaptchaConfig,
   Keyset,
   type OAuthAuthorizationServerMetadata,
 }
 
+type ApiContext = {
+  requestUri: RequestUri
+  deviceId: DeviceId
+  deviceMetadata: RequestMetadata
+}
+
+export type ErrorHandler<
+  Req extends IncomingMessage = IncomingMessage,
+  Res extends ServerResponse = ServerResponse,
+> = (req: Req, res: Res, err: unknown, message: string) => void
+
 export type RouterOptions<
   Req extends IncomingMessage = IncomingMessage,
   Res extends ServerResponse = ServerResponse,
-> = DeviceManagerOptions & {
-  onError?: (req: Req, res: Res, err: unknown, message: string) => void
+> = {
+  onError?: ErrorHandler<Req, Res>
 }
 
 export type OAuthProviderOptions = Override<
-  OAuthVerifierOptions & OAuthHooks,
+  OAuthVerifierOptions & OAuthHooks & DeviceManagerOptions & Customization,
   {
     /**
      * Maximum age a device/account session can be before requiring
@@ -157,11 +176,6 @@ export type OAuthProviderOptions = Override<
      */
     metadata?: CustomMetadata
 
-    /**
-     * UI customizations
-     */
-    customization?: Customization
-
     /**
      * A custom fetch function that can be used to fetch the client metadata from
      * the internet. By default, the fetch function is a safeFetchWrap() function
@@ -184,11 +198,18 @@ export type OAuthProviderOptions = Override<
      * this store implements all the interfaces not provided in the other
      * `<name>Store` options.
      */
-    store?: OAuthProviderStore
+    store?: Partial<
+      AccountStore &
+        ClientStore &
+        DeviceStore &
+        ReplayStore &
+        RequestStore &
+        TokenStore
+    >
 
     accountStore?: AccountStore
-    deviceStore?: DeviceStore
     clientStore?: ClientStore
+    deviceStore?: DeviceStore
     replayStore?: ReplayStore
     requestStore?: RequestStore
     tokenStore?: TokenStore
@@ -223,19 +244,18 @@ export type OAuthProviderOptions = Override<
 
 export class OAuthProvider extends OAuthVerifier {
   public readonly metadata: OAuthAuthorizationServerMetadata
-  public readonly customization?: Customization
 
   public readonly authenticationMaxAge: number
 
   public readonly accountManager: AccountManager
-  public readonly deviceStore: DeviceStore
+  public readonly deviceManager: DeviceManager
   public readonly clientManager: ClientManager
   public readonly requestManager: RequestManager
   public readonly tokenManager: TokenManager
+  public readonly outputManager: OutputManager
 
   public constructor({
     metadata,
-    customization = undefined,
     authenticationMaxAge = AUTHENTICATION_MAX_AGE,
     tokenMaxAge = TOKEN_MAX_AGE,
 
@@ -264,10 +284,30 @@ export class OAuthProvider extends OAuthVerifier {
 
     loopbackMetadata = atprotoLoopbackClientMetadata,
 
-    // OAuthHooks & OAuthVerifierOptions
+    // OAuthHooks &
+    // OAuthVerifierOptions &
+    // DeviceManagerOptions &
+    // Customization
     ...rest
   }: OAuthProviderOptions) {
-    super({ replayStore, redis, ...rest })
+    const customization: Customization = customizationSchema.parse(rest)
+    const deviceManagerOptions: DeviceManagerOptions =
+      deviceManagerOptionsSchema.parse(rest)
+
+    // @NOTE: hooks don't really need a type parser, as all zod can actually
+    // check at runtime is the fact that the values are functions. The only way
+    // we would benefit from zod here would be to wrap the functions with a
+    // validator for the provided function's return types, which we do not add
+    // because it would impact runtime performance and we trust the users of
+    // this lib (basically ourselves) to rely on the typing system to ensure the
+    // correct types are returned.
+    const hooks: OAuthHooks = rest
+
+    // @NOTE: validation of super params (if we wanted to implement it) should
+    // be the responsibility of the super class.
+    const superOptions: OAuthVerifierOptions = rest
+
+    super({ replayStore, redis, ...superOptions })
 
     requestStore ??= redis
       ? new RequestStoreRedis({ redis })
@@ -275,15 +315,19 @@ export class OAuthProvider extends OAuthVerifier {
 
     this.authenticationMaxAge = authenticationMaxAge
     this.metadata = buildMetadata(this.issuer, this.keyset, metadata)
-    this.customization = customization
-
-    this.deviceStore = deviceStore
 
-    this.accountManager = new AccountManager(accountStore)
+    this.deviceManager = new DeviceManager(deviceStore, deviceManagerOptions)
+    this.outputManager = new OutputManager(customization)
+    this.accountManager = new AccountManager(
+      this.issuer,
+      accountStore,
+      hooks,
+      customization,
+    )
     this.clientManager = new ClientManager(
       this.metadata,
       this.keyset,
-      rest,
+      hooks,
       clientStore || null,
       loopbackMetadata || null,
       safeFetch,
@@ -294,12 +338,12 @@ export class OAuthProvider extends OAuthVerifier {
       requestStore,
       this.signer,
       this.metadata,
-      rest,
+      hooks,
     )
     this.tokenManager = new TokenManager(
       tokenStore,
       this.signer,
-      rest,
+      hooks,
       this.accessTokenType,
       tokenMaxAge,
     )
@@ -452,8 +496,7 @@ export class OAuthProvider extends OAuthVerifier {
       // https://datatracker.ietf.org/doc/html/rfc9126#section-2.3-1
       // > Since initial processing of the pushed authorization request does not
       // > involve resource owner interaction, error codes related to user
-      // > interaction, such as consent_required defined by [OIDC], are never
-      // > returned.
+      // > interaction, such as "access_denied", are never returned.
       if (err instanceof AccessDeniedError) {
         throw new InvalidRequestError(err.error_description, err)
       }
@@ -471,7 +514,7 @@ export class OAuthProvider extends OAuthVerifier {
         .parseAsync(query.request_uri, { path: ['query', 'request_uri'] })
         .catch(throwInvalidRequest)
 
-      return this.requestManager.get(requestUri, client.id, deviceId)
+      return this.requestManager.get(requestUri, deviceId, client.id)
     }
 
     if ('request' in query) {
@@ -515,11 +558,11 @@ export class OAuthProvider extends OAuthVerifier {
   }
 
   private async deleteRequest(
-    uri: RequestUri,
+    requestUri: RequestUri,
     parameters: OAuthAuthorizationRequestParameters,
   ) {
     try {
-      await this.requestManager.delete(uri)
+      await this.requestManager.delete(requestUri)
     } catch (err) {
       throw AccessDeniedError.from(parameters, err)
     }
@@ -691,24 +734,46 @@ export class OAuthProvider extends OAuthVerifier {
     }))
   }
 
-  protected async signIn(
-    deviceId: DeviceId,
-    uri: RequestUri,
-    clientId: ClientId,
-    credentials: SignInCredentials,
+  protected async signUp(
+    { requestUri, deviceId, deviceMetadata }: ApiContext,
+    data: SignUpData,
   ): Promise<{
     account: Account
     consentRequired: boolean
   }> {
+    const { clientId } = await this.requestManager.get(requestUri, deviceId)
+
     const client = await this.clientManager.getClient(clientId)
 
+    const { account } = await this.accountManager.signUp(
+      data,
+      deviceId,
+      deviceMetadata,
+    )
+
+    return {
+      account,
+      consentRequired: !client.info.isFirstParty,
+    }
+  }
+
+  protected async signIn(
+    { requestUri, deviceId, deviceMetadata }: ApiContext,
+    data: SignInData,
+  ): Promise<{
+    account: Account
+    consentRequired: boolean
+  }> {
     // Ensure the request is still valid (and update the request expiration)
     // @TODO use the returned scopes to determine if consent is required
-    await this.requestManager.get(uri, clientId, deviceId)
+    const { clientId } = await this.requestManager.get(requestUri, deviceId)
+
+    const client = await this.clientManager.getClient(clientId)
 
     const { account, info } = await this.accountManager.signIn(
-      credentials,
+      data,
       deviceId,
+      deviceMetadata,
     )
 
     return {
@@ -723,22 +788,21 @@ export class OAuthProvider extends OAuthVerifier {
   }
 
   protected async acceptRequest(
-    uri: RequestUri,
-    clientId: ClientId,
+    { requestUri, deviceId, deviceMetadata }: ApiContext,
     sub: string,
-    deviceId: DeviceId,
-    deviceMetadata: RequestMetadata,
   ): Promise<AuthorizationResultRedirect> {
     const { issuer } = this
-    const client = await this.clientManager.getClient(clientId)
 
-    const { parameters, clientAuth } = await this.requestManager.get(
-      uri,
-      clientId,
+    const { parameters, clientId, clientAuth } = await this.requestManager.get(
+      requestUri,
       deviceId,
     )
 
+    const client = await this.clientManager.getClient(clientId)
+
     try {
+      // @TODO Currently, a user can "accept" a request for any did that sing-in
+      // on the device, even if "remember" was set to false.
       const { account, info } = await this.accountManager.get(deviceId, sub)
 
       // The user is trying to authorize without a fresh login
@@ -750,7 +814,7 @@ export class OAuthProvider extends OAuthVerifier {
       }
 
       const code = await this.requestManager.setAuthorized(
-        uri,
+        requestUri,
         client,
         account,
         deviceId,
@@ -766,24 +830,19 @@ export class OAuthProvider extends OAuthVerifier {
 
       return { issuer, parameters, redirect: { code } }
     } catch (err) {
-      await this.deleteRequest(uri, parameters)
+      await this.deleteRequest(requestUri, parameters)
 
       throw AccessDeniedError.from(parameters, err)
     }
   }
 
-  protected async rejectRequest(
-    deviceId: DeviceId,
-    uri: RequestUri,
-    clientId: ClientId,
-  ): Promise<AuthorizationResultRedirect> {
-    const { parameters } = await this.requestManager.get(
-      uri,
-      clientId,
-      deviceId,
-    )
+  protected async rejectRequest({
+    requestUri,
+    deviceId,
+  }: ApiContext): Promise<AuthorizationResultRedirect> {
+    const { parameters } = await this.requestManager.get(requestUri, deviceId)
 
-    await this.deleteRequest(uri, parameters)
+    await this.deleteRequest(requestUri, parameters)
 
     return {
       issuer: this.issuer,
@@ -1025,10 +1084,7 @@ export class OAuthProvider extends OAuthVerifier {
     T = void,
     Req extends IncomingMessage = IncomingMessage,
     Res extends ServerResponse = ServerResponse,
-  >(options?: RouterOptions<Req, Res>) {
-    const deviceManager = new DeviceManager(this.deviceStore, options)
-    const outputManager = new OutputManager(this.customization)
-
+  >(options?: RouterOptions<Req, Res>): Router<T, Req, Res> {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const server = this
     const issuerUrl = new URL(server.issuer)
@@ -1037,57 +1093,67 @@ export class OAuthProvider extends OAuthVerifier {
 
     // Utils
 
-    const csrfCookie = (uri: RequestUri) => `csrf-${uri}`
-    const onError =
+    const csrfCookie = (requestUri: RequestUri) => `csrf-${requestUri}`
+    const onError: null | ErrorHandler<Req, Res> =
       options?.onError ??
       (process.env['NODE_ENV'] === 'development'
-        ? (req, res, err, msg): void =>
+        ? (req, res, err, msg) => {
             console.error(`OAuthProvider error (${msg}):`, err)
-        : undefined)
+          }
+        : null)
 
-    /**
-     * Creates a middleware that will serve static JSON content.
-     */
-    const staticJson = (json: unknown): Middleware<void, Req, Res> =>
-      combineMiddlewares([
-        function (req, res, next) {
-          res.setHeader('Access-Control-Allow-Origin', '*')
-          res.setHeader('Access-Control-Allow-Headers', '*')
+    // CORS preflight
+    const corsHeaders: Middleware = function (req, res, next) {
+      res.setHeader('Access-Control-Max-Age', '86400') // 1 day
 
-          res.setHeader('Cache-Control', 'max-age=300')
-          next()
-        },
-        staticJsonMiddleware(json),
-      ])
+      // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin
+      //
+      // > For requests without credentials, the literal value "*" can be
+      // > specified as a wildcard; the value tells browsers to allow
+      // > requesting code from any origin to access the resource.
+      // > Attempting to use the wildcard with credentials results in an
+      // > error.
+      //
+      // A "*" is safer to use than reflecting the request origin.
+      res.setHeader('Access-Control-Allow-Origin', '*')
+
+      // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods
+      // > The value "*" only counts as a special wildcard value for
+      // > requests without credentials (requests without HTTP cookies or
+      // > HTTP authentication information). In requests with credentials,
+      // > it is treated as the literal method name "*" without special
+      // > semantics.
+      res.setHeader('Access-Control-Allow-Methods', '*')
+
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type,DPoP')
+
+      next()
+    }
+
+    const corsPreflight: Middleware = combineMiddlewares([
+      corsHeaders,
+      (req, res) => {
+        res.writeHead(200).end()
+      },
+    ])
 
     /**
      * Wrap an OAuth endpoint in a middleware that will set the appropriate
      * response headers and format the response as JSON.
      */
     const jsonHandler = <T, TReq extends Req, TRes extends Res, Json>(
-      buildJson: (this: T, req: TReq, res: TRes) => Json | Promise<Json>,
+      buildJson: (this: T, req: TReq, res: TRes) => Awaitable<Json>,
       status?: number,
     ): Handler<T, TReq, TRes> =>
       async function (req, res) {
-        res.setHeader('Access-Control-Allow-Origin', '*')
-        res.setHeader('Access-Control-Allow-Headers', '*')
-
-        // https://www.rfc-editor.org/rfc/rfc6749.html#section-5.1
-        res.setHeader('Cache-Control', 'no-store')
-        res.setHeader('Pragma', 'no-cache')
-
-        // https://datatracker.ietf.org/doc/html/rfc9449#section-8.2
-        const dpopNonce = server.nextDpopNonce()
-        if (dpopNonce) {
-          const name = 'DPoP-Nonce'
-          res.setHeader(name, dpopNonce)
-          res.appendHeader('Access-Control-Expose-Headers', name)
-        }
-
         try {
+          // https://www.rfc-editor.org/rfc/rfc6749.html#section-5.1
+          res.setHeader('Cache-Control', 'no-store')
+          res.setHeader('Pragma', 'no-cache')
+
           // Ensure we can agree on a content encoding & type before starting to
           // build the JSON response.
-          if (!mediaType(req.headers['accept'], ['application/json'])) {
+          if (!negotiateContent(req, ['application/json'])) {
             throw createHttpError(406, 'Unsupported media type')
           }
 
@@ -1098,39 +1164,107 @@ export class OAuthProvider extends OAuthVerifier {
             res.writeHead(status ?? 204).end()
           }
         } catch (err) {
-          if (!res.headersSent) {
-            if (err instanceof WWWAuthenticateError) {
-              const name = 'WWW-Authenticate'
-              res.setHeader(name, err.wwwAuthenticateHeader)
-              res.appendHeader('Access-Control-Expose-Headers', name)
-            }
+          onError?.(req, res, err, 'OAuth request error')
 
+          if (!res.headersSent) {
             const payload = buildErrorPayload(err)
             const status = buildErrorStatus(err)
             writeJson(res, payload, { status })
           } else {
             res.destroy()
           }
-
-          // OAuthError are used to build expected responses, so we don't log
-          // them as errors.
-          if (!(err instanceof OAuthError) || err.statusCode >= 500) {
-            onError?.(req, res, err, 'Unexpected error')
-          }
         }
       }
 
+    const oauthHandler = <T, TReq extends Req, TRes extends Res, Json>(
+      buildOAuthResponse: (this: T, req: TReq, res: TRes) => Awaitable<Json>,
+      status?: number,
+    ) =>
+      combineMiddlewares([
+        corsHeaders,
+        jsonHandler<T, TReq, TRes, Json>(async function (req, res) {
+          try {
+            // https://datatracker.ietf.org/doc/html/rfc9449#section-8.2
+            const dpopNonce = server.nextDpopNonce()
+            if (dpopNonce) {
+              const name = 'DPoP-Nonce'
+              res.setHeader(name, dpopNonce)
+              res.appendHeader('Access-Control-Expose-Headers', name)
+            }
+
+            return await buildOAuthResponse.call(this, req, res)
+          } catch (err) {
+            if (!res.headersSent && err instanceof WWWAuthenticateError) {
+              const name = 'WWW-Authenticate'
+              res.setHeader(name, err.wwwAuthenticateHeader)
+              res.appendHeader('Access-Control-Expose-Headers', name)
+            }
+
+            throw err
+          }
+        }, status),
+      ])
+
+    const apiHandler = <
+      T,
+      TReq extends Req,
+      TRes extends Res,
+      S extends z.ZodTypeAny,
+      Json,
+    >(
+      inputSchema: S,
+      buildJson: (
+        this: T,
+        req: TReq,
+        res: TRes,
+        input: z.infer<S>,
+        context: ApiContext,
+      ) => Json | Promise<Json>,
+      status?: number,
+    ) =>
+      jsonHandler<T, TReq, TRes, Json>(async function (req, res) {
+        validateFetchMode(req, res, ['same-origin'])
+        validateFetchSite(req, res, ['same-origin'])
+        validateSameOrigin(req, res, issuerOrigin)
+        const referer = validateReferer(req, res, {
+          origin: issuerOrigin,
+          pathname: '/oauth/authorize',
+        })
+
+        const requestUri = await requestUriSchema.parseAsync(
+          referer.searchParams.get('request_uri'),
+          { path: ['query', 'request_uri'] },
+        )
+
+        validateCsrfToken(
+          req,
+          res,
+          req.headers['x-csrf-token'],
+          csrfCookie(requestUri),
+        )
+
+        const { deviceId, deviceMetadata } = await server.deviceManager.load(
+          req,
+          res,
+        )
+
+        const payload = await parseHttpRequest(req, ['json'])
+        const input = await inputSchema.parseAsync(payload, { path: ['body'] })
+
+        const context: ApiContext = { requestUri, deviceId, deviceMetadata }
+        return buildJson.call(this, req, res, input, context)
+      }, status)
+
     const navigationHandler = <T, TReq extends Req, TRes extends Res>(
-      handler: (this: T, req: TReq, res: TRes) => void | Promise<void>,
+      handler: (this: T, req: TReq, res: TRes) => Awaitable<void>,
     ): Handler<T, TReq, TRes> =>
       async function (req, res) {
-        res.setHeader('Access-Control-Allow-Origin', '*')
-        res.setHeader('Access-Control-Allow-Headers', '*')
+        try {
+          res.setHeader('Cache-Control', 'no-store')
+          res.setHeader('Pragma', 'no-cache')
 
-        res.setHeader('Cache-Control', 'no-store')
-        res.setHeader('Pragma', 'no-cache')
+          res.setHeader('Referrer-Policy', 'same-origin')
 
-        try {
           validateFetchMode(req, res, ['navigate'])
           validateFetchDest(req, res, ['document'])
           validateSameOrigin(req, res, issuerOrigin)
@@ -1145,11 +1279,78 @@ export class OAuthProvider extends OAuthVerifier {
           )
 
           if (!res.headersSent) {
-            await outputManager.sendErrorPage(res, err)
+            await server.outputManager.sendErrorPage(res, err, {
+              preferredLocales: extractLocales(req),
+            })
           }
         }
       }
 
+    // Simple GET requests fall under the category of "no-cors" request, meaning
+    // that the browser will allow any cross-origin request, with credentials,
+    // to be sent to the oauth server. The OAuth Server will, however:
+    // 1) validate the request origin (see navigationHandler),
+    // 2) validate the CSRF token,
+    // 3) validate the referer,
+    // 4) validate the sec-fetch-site header,
+    // 4) validate the sec-fetch-mode header (see navigationHandler),
+    // 5) validate the sec-fetch-dest header (see navigationHandler).
+    // And will error (refuse to serve the request) if any of these checks fail.
+    const sameOriginNavigationHandler = <
+      T extends { url: URL },
+      TReq extends Req,
+      TRes extends Res,
+    >(
+      handler: (
+        this: T,
+        req: TReq,
+        res: TRes,
+        deviceInfo: DeviceInfo,
+      ) => Awaitable<void>,
+    ): Handler<T, TReq, TRes> =>
+      navigationHandler(async function (req, res) {
+        validateFetchSite(req, res, ['same-origin'])
+
+        const deviceInfo = await server.deviceManager.load(req, res)
+
+        return handler.call(this, req, res, deviceInfo)
+      })
+
+    const authorizeRedirectNavigationHandler = <
+      T extends { url: URL },
+      TReq extends Req,
+      TRes extends Res,
+    >(
+      handler: (
+        this: T,
+        req: TReq,
+        res: TRes,
+        context: ApiContext,
+      ) => Awaitable<AuthorizationResultRedirect>,
+    ): Handler<T, TReq, TRes> =>
+      sameOriginNavigationHandler(async function (req, res, deviceInfo) {
+        const referer = validateReferer(req, res, {
+          origin: issuerOrigin,
+          pathname: '/oauth/authorize',
+        })
+
+        const requestUri = await requestUriSchema.parseAsync(
+          referer.searchParams.get('request_uri'),
+        )
+
+        const csrfToken = this.url.searchParams.get('csrf_token')
+        const csrfCookieName = csrfCookie(requestUri)
+
+        // Next line will "clear" the CSRF token cookie, preventing replay of
+        // this request (navigating "back" will result in an error).
+        validateCsrfToken(req, res, csrfToken, csrfCookieName, true)
+
+        const context: ApiContext = { ...deviceInfo, requestUri }
+
+        const redirect = await handler.call(this, req, res, context)
+        return sendAuthorizeRedirect(res, redirect)
+      })
+
     /**
      * Provides a better UX when a request is denied by redirecting to the
      * client with the error details. This will also log any error that caused
@@ -1176,44 +1377,26 @@ export class OAuthProvider extends OAuthVerifier {
 
     //- Public OAuth endpoints
 
+    router.options('/.well-known/oauth-authorization-server', corsPreflight)
     router.get(
       '/.well-known/oauth-authorization-server',
-      staticJson(server.metadata),
+      corsHeaders,
+      cacheControlMiddleware(300),
+      staticJsonMiddleware(server.metadata),
     )
 
-    // CORS preflight
-    const corsPreflight: Middleware = function (req, res, _next) {
-      res
-        .writeHead(204, {
-          // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin
-          //
-          // > For requests without credentials, the literal value "*" can be
-          // > specified as a wildcard; the value tells browsers to allow
-          // > requesting code from any origin to access the resource.
-          // > Attempting to use the wildcard with credentials results in an
-          // > error.
-          //
-          // A "*" is safer to use than reflecting the request origin.
-          'Access-Control-Allow-Origin': '*',
-          // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods
-          // > The value "*" only counts as a special wildcard value for
-          // > requests without credentials (requests without HTTP cookies or
-          // > HTTP authentication information). In requests with credentials,
-          // > it is treated as the literal method name "*" without special
-          // > semantics.
-          'Access-Control-Allow-Methods': '*',
-          'Access-Control-Allow-Headers': 'Content-Type,Authorization,DPoP',
-          'Access-Control-Max-Age': '86400', // 1 day
-        })
-        .end()
-    }
-
-    router.get('/oauth/jwks', staticJson(server.jwks))
+    router.options('/oauth/jwks', corsPreflight)
+    router.get(
+      '/oauth/jwks',
+      corsHeaders,
+      cacheControlMiddleware(300),
+      staticJsonMiddleware(server.jwks),
+    )
 
     router.options('/oauth/par', corsPreflight)
     router.post(
       '/oauth/par',
-      jsonHandler(async function (req, _res) {
+      oauthHandler(async function (req, _res) {
         const payload = await parseHttpRequest(req, ['json', 'urlencoded'])
 
         const credentials = await oauthClientCredentialsSchema
@@ -1237,11 +1420,9 @@ export class OAuthProvider extends OAuthVerifier {
         )
       }, 201),
     )
-
     // https://datatracker.ietf.org/doc/html/rfc9126#section-2.3
     // > If the request did not use the POST method, the authorization server
     // > responds with an HTTP 405 (Method Not Allowed) status code.
-    router.options('/oauth/par', corsPreflight)
     router.all('/oauth/par', (req, res) => {
       res.writeHead(405).end()
     })
@@ -1249,10 +1430,11 @@ export class OAuthProvider extends OAuthVerifier {
     router.options('/oauth/token', corsPreflight)
     router.post(
       '/oauth/token',
-      jsonHandler(async function (req, _res) {
+      oauthHandler(async function (req, _res) {
         const payload = await parseHttpRequest(req, ['json', 'urlencoded'])
 
-        const clientMetadata = await deviceManager.getRequestMetadata(req)
+        const clientMetadata =
+          await server.deviceManager.getRequestMetadata(req)
 
         const clientCredentials = await oauthClientCredentialsSchema
           .parseAsync(payload, { path: ['body'] })
@@ -1280,7 +1462,7 @@ export class OAuthProvider extends OAuthVerifier {
     router.options('/oauth/revoke', corsPreflight)
     router.post(
       '/oauth/revoke',
-      jsonHandler(async function (req, res) {
+      oauthHandler(async function (req, res) {
         const payload = await parseHttpRequest(req, ['json', 'urlencoded'])
 
         const tokenIdentification = await oauthTokenIdentificationSchema
@@ -1294,8 +1476,6 @@ export class OAuthProvider extends OAuthVerifier {
         }
       }),
     )
-
-    router.options('/oauth/revoke', corsPreflight)
     router.get(
       '/oauth/revoke',
       navigationHandler(async function (req, res) {
@@ -1320,9 +1500,10 @@ export class OAuthProvider extends OAuthVerifier {
       }),
     )
 
+    router.options('/oauth/introspect', corsPreflight)
     router.post(
       '/oauth/introspect',
-      jsonHandler(async function (req, _res) {
+      oauthHandler(async function (req, _res) {
         const payload = await parseHttpRequest(req, ['json', 'urlencoded'])
 
         const credentials = await oauthClientCredentialsSchema
@@ -1349,7 +1530,7 @@ export class OAuthProvider extends OAuthVerifier {
         const query = Object.fromEntries(this.url.searchParams)
 
         const clientCredentials = await oauthClientCredentialsSchema
-          .parseAsync(query, { path: ['body'] })
+          .parseAsync(query, { path: ['query'] })
           .catch(throwInvalidRequest)
 
         if ('client_secret' in clientCredentials) {
@@ -1360,9 +1541,14 @@ export class OAuthProvider extends OAuthVerifier {
           .parseAsync(query, { path: ['query'] })
           .catch(throwInvalidRequest)
 
-        const { deviceId, deviceMetadata } = await deviceManager.load(req, res)
+        const { deviceId, deviceMetadata } = await server.deviceManager.load(
+          req,
+          res,
+        )
 
-        const data = await server
+        const result:
+          | AuthorizationResultRedirect
+          | AuthorizationResultAuthorize = await server
           .authorize(
             clientCredentials,
             authorizationRequest,
@@ -1371,170 +1557,79 @@ export class OAuthProvider extends OAuthVerifier {
           )
           .catch((err) => accessDeniedToRedirectCatcher(req, res, err))
 
-        switch (true) {
-          case 'redirect' in data: {
-            return sendAuthorizeRedirect(res, data)
-          }
-          case 'authorize' in data: {
-            await setupCsrfToken(req, res, csrfCookie(data.authorize.uri))
-            return outputManager.sendAuthorizePage(res, data)
-          }
-          default: {
-            // Should never happen
-            throw new Error('Unexpected authorization result')
-          }
+        if ('redirect' in result) {
+          return sendAuthorizeRedirect(res, result)
+        } else {
+          await setupCsrfToken(req, res, csrfCookie(result.authorize.uri))
+          return server.outputManager.sendAuthorizePage(res, result, {
+            preferredLocales: extractLocales(req),
+          })
         }
       }),
     )
 
-    const signInPayloadSchema = z.object({
-      csrf_token: z.string(),
-      request_uri: requestUriSchema,
-      client_id: clientIdSchema,
-      credentials: signInCredentialsSchema,
-    })
-
-    router.options('/oauth/authorize/sign-in', corsPreflight)
     router.post(
-      '/oauth/authorize/sign-in',
-      jsonHandler(async function (req, res) {
-        validateFetchMode(req, res, ['same-origin'])
-        validateFetchSite(req, res, ['same-origin'])
-        validateSameOrigin(req, res, issuerOrigin)
-
-        const payload = await parseHttpRequest(req, ['json'])
-        const input = await signInPayloadSchema.parseAsync(payload, {
-          path: ['body'],
-        })
-
-        validateReferer(req, res, {
-          origin: issuerOrigin,
-          pathname: '/oauth/authorize',
-        })
-        validateCsrfToken(
-          req,
-          res,
-          input.csrf_token,
-          csrfCookie(input.request_uri),
-        )
+      '/oauth/authorize/verify-handle-availability',
+      apiHandler(
+        z.object({ handle: handleSchema }).strict(),
+        async function (req, res, data) {
+          return server.accountManager.verifyHandleAvailability(data.handle)
+        },
+      ),
+    )
 
-        const { deviceId } = await deviceManager.load(req, res, true)
+    router.post(
+      '/oauth/authorize/sign-up',
+      apiHandler(signUpDataSchema, async function (req, res, data, ctx) {
+        return server.signUp(ctx, data)
+      }),
+    )
 
-        return server.signIn(
-          deviceId,
-          input.request_uri,
-          input.client_id,
-          input.credentials,
-        )
+    router.post(
+      '/oauth/authorize/sign-in',
+      apiHandler(signInDataSchema, async function (req, res, data, ctx) {
+        return server.signIn(ctx, data)
       }),
     )
 
-    const acceptQuerySchema = z.object({
-      csrf_token: z.string(),
-      request_uri: requestUriSchema,
-      client_id: clientIdSchema,
-      account_sub: z.string(),
-    })
+    router.post(
+      '/oauth/authorize/reset-password-request',
+      apiHandler(
+        resetPasswordRequestDataSchema,
+        async function (req, res, data) {
+          await server.accountManager.resetPasswordRequest(data)
+        },
+      ),
+    )
+
+    router.post(
+      '/oauth/authorize/reset-password-confirm',
+      apiHandler(
+        resetPasswordConfirmDataSchema,
+        async function (req, res, data) {
+          await server.accountManager.resetPasswordConfirm(data)
+        },
+      ),
+    )
 
-    // Though this is a "no-cors" request, meaning that the browser will allow
-    // any cross-origin request, with credentials, to be sent, the handler will
-    // 1) validate the request origin,
-    // 2) validate the CSRF token,
-    // 3) validate the referer,
-    // 4) validate the sec-fetch-site header,
-    // 4) validate the sec-fetch-mode header,
-    // 5) validate the sec-fetch-dest header (see navigationHandler).
-    // And will error if any of these checks fail.
     router.get(
       '/oauth/authorize/accept',
-      navigationHandler(async function (req, res) {
-        validateFetchSite(req, res, ['same-origin'])
-
-        const query = Object.fromEntries(this.url.searchParams)
-        const input = await acceptQuerySchema.parseAsync(query, {
-          path: ['query'],
-        })
-
-        validateReferer(req, res, {
-          origin: issuerOrigin,
-          pathname: '/oauth/authorize',
-          searchParams: [
-            ['request_uri', input.request_uri],
-            ['client_id', input.client_id],
-          ],
-        })
-        validateCsrfToken(
-          req,
-          res,
-          input.csrf_token,
-          csrfCookie(input.request_uri),
-          true,
-        )
-
-        const { deviceId, deviceMetadata } = await deviceManager.load(req, res)
+      authorizeRedirectNavigationHandler(async function (req, res, ctx) {
+        const sub = this.url.searchParams.get('account_sub')
+        if (!sub) throw new InvalidRequestError('Account sub not provided')
 
-        const data = await server
-          .acceptRequest(
-            input.request_uri,
-            input.client_id,
-            input.account_sub,
-            deviceId,
-            deviceMetadata,
-          )
+        return server
+          .acceptRequest(ctx, sub)
           .catch((err) => accessDeniedToRedirectCatcher(req, res, err))
-
-        return await sendAuthorizeRedirect(res, data)
       }),
     )
 
-    const rejectQuerySchema = z.object({
-      csrf_token: z.string(),
-      request_uri: requestUriSchema,
-      client_id: clientIdSchema,
-    })
-
-    // Though this is a "no-cors" request, meaning that the browser will allow
-    // any cross-origin request, with credentials, to be sent, the handler will
-    // 1) validate the request origin,
-    // 2) validate the CSRF token,
-    // 3) validate the referer,
-    // 4) validate the sec-fetch-site header,
-    // 4) validate the sec-fetch-mode header,
-    // 5) validate the sec-fetch-dest header (see navigationHandler).
-    // And will error if any of these checks fail.
     router.get(
       '/oauth/authorize/reject',
-      navigationHandler(async function (req, res) {
-        validateFetchSite(req, res, ['same-origin'])
-
-        const query = Object.fromEntries(this.url.searchParams)
-        const input = await rejectQuerySchema.parseAsync(query, {
-          path: ['query'],
-        })
-
-        validateReferer(req, res, {
-          origin: issuerOrigin,
-          pathname: '/oauth/authorize',
-          searchParams: [
-            ['request_uri', input.request_uri],
-            ['client_id', input.client_id],
-          ],
-        })
-        validateCsrfToken(
-          req,
-          res,
-          input.csrf_token,
-          csrfCookie(input.request_uri),
-          true,
-        )
-
-        const { deviceId } = await deviceManager.load(req, res)
-
-        const data = await server
-          .rejectRequest(deviceId, input.request_uri, input.client_id)
+      authorizeRedirectNavigationHandler(async function (req, res, ctx) {
+        return server
+          .rejectRequest(ctx)
           .catch((err) => accessDeniedToRedirectCatcher(req, res, err))
-
-        return await sendAuthorizeRedirect(res, data)
       }),
     )