@atproto/oauth-provider 0.9.2 → 0.9.3

package/src/errors/authorization-error.ts

@@ -0,0 +1,45 @@
+import { OAuthAuthorizationRequestParameters } from '@atproto/oauth-types'
+import {
+  AuthorizationResponseError,
+  isAuthorizationResponseError,
+} from '../types/authorization-response-error.js'
+import { buildErrorPayload } from './error-parser.js'
+import { OAuthError } from './oauth-error.js'
+
+export type { AuthorizationResponseError, OAuthAuthorizationRequestParameters }
+
+export class AuthorizationError extends OAuthError {
+  constructor(
+    public readonly parameters: OAuthAuthorizationRequestParameters,
+    error_description: string,
+    error: AuthorizationResponseError = 'invalid_request',
+    cause?: unknown,
+  ) {
+    super(error, error_description, 400, cause)
+  }
+
+  static from(
+    parameters: OAuthAuthorizationRequestParameters,
+    cause: unknown,
+  ): AuthorizationError {
+    if (cause instanceof AuthorizationError) return cause
+    const payload = buildErrorPayload(cause)
+    return new AuthorizationError(
+      parameters,
+      payload.error_description,
+      isAuthorizationResponseError(payload.error)
+        ? payload.error // Propagate "error" derived from the cause
+        : rootCause(cause) instanceof OAuthError
+          ? 'invalid_request'
+          : 'server_error',
+      cause,
+    )
+  }
+}
+
+function rootCause(err: unknown): unknown {
+  while (err instanceof Error && err.cause != null) {
+    err = err.cause
+  }
+  return err
+}

package/src/errors/consent-required-error.ts

@@ -1,7 +1,7 @@
 import { OAuthAuthorizationRequestParameters } from '@atproto/oauth-types'
-import { AccessDeniedError } from './access-denied-error.js'
+import { AuthorizationError } from './authorization-error.js'
 
-export class ConsentRequiredError extends AccessDeniedError {
+export class ConsentRequiredError extends AuthorizationError {
   constructor(
     parameters: OAuthAuthorizationRequestParameters,
     error_description = 'User consent required',

package/src/errors/error-parser.ts

@@ -1,6 +1,7 @@
 import { errors } from 'jose'
 import { ZodError } from 'zod'
 import { JwtVerifyError } from '@atproto/jwk'
+import { formatZodError } from '../lib/util/zod-error.js'
 import { OAuthError } from './oauth-error.js'
 
 const { JOSEError } = errors
@@ -63,7 +64,7 @@ export function buildErrorPayload(error: unknown): ErrorPayload {
   if (error instanceof ZodError) {
     return {
       error: INVALID_REQUEST,
-      error_description: error.issues[0]?.message || 'Invalid request',
+      error_description: formatZodError(error, 'Validation error'),
     }
   }
 

package/src/errors/invalid-authorization-details-error.ts

@@ -1,5 +1,5 @@
 import { OAuthAuthorizationRequestParameters } from '@atproto/oauth-types'
-import { AccessDeniedError } from './access-denied-error.js'
+import { AuthorizationError } from './authorization-error.js'
 
 /**
  * @see
@@ -16,7 +16,7 @@ import { AccessDeniedError } from './access-denied-error.js'
  *  - contains fields with invalid values for the authorization details type, or
  *  - is missing required fields for the authorization details type.
  */
-export class InvalidAuthorizationDetailsError extends AccessDeniedError {
+export class InvalidAuthorizationDetailsError extends AuthorizationError {
   constructor(
     parameters: OAuthAuthorizationRequestParameters,
     error_description: string,

package/src/errors/invalid-scope-error.ts

@@ -1,10 +1,10 @@
 import { OAuthAuthorizationRequestParameters } from '@atproto/oauth-types'
-import { AccessDeniedError } from './access-denied-error.js'
+import { AuthorizationError } from './authorization-error.js'
 
 /**
  * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11#section-4.1.2.1}
  */
-export class InvalidScopeError extends AccessDeniedError {
+export class InvalidScopeError extends AuthorizationError {
   constructor(
     parameters: OAuthAuthorizationRequestParameters,
     error_description: string,

package/src/errors/login-required-error.ts

@@ -1,7 +1,7 @@
 import { OAuthAuthorizationRequestParameters } from '@atproto/oauth-types'
-import { AccessDeniedError } from './access-denied-error.js'
+import { AuthorizationError } from './authorization-error.js'
 
-export class LoginRequiredError extends AccessDeniedError {
+export class LoginRequiredError extends AuthorizationError {
   constructor(
     parameters: OAuthAuthorizationRequestParameters,
     error_description = 'Login is required',
@@ -9,14 +9,4 @@ export class LoginRequiredError extends AccessDeniedError {
   ) {
     super(parameters, error_description, 'login_required', cause)
   }
-
-  static from(
-    parameters: OAuthAuthorizationRequestParameters,
-    cause?: unknown,
-    fallbackError?: string,
-  ): LoginRequiredError {
-    if (cause instanceof LoginRequiredError) return cause
-
-    return new LoginRequiredError(parameters, fallbackError, cause)
-  }
 }

package/src/lib/http/response.ts

@@ -101,16 +101,16 @@ export function cacheControlMiddleware(maxAge: number): Middleware<void> {
   }
 }
 
+export type JsonResponse<P = unknown> = WriteResponseOptions & {
+  json: P
+}
+
 export function jsonHandler<
   T,
   Req extends IncomingMessage = IncomingMessage,
   Res extends ServerResponse = ServerResponse,
 >(
-  buildJson: (
-    this: T,
-    req: Req,
-    res: Res,
-  ) => Awaitable<{ payload: unknown; status?: number }>,
+  buildJson: (this: T, req: Req, res: Res) => Awaitable<JsonResponse>,
 ): Middleware<T, Req, Res> {
   return function (req, res, next) {
     // Ensure we can agree on a content encoding & type before starting to
@@ -120,14 +120,11 @@ export function jsonHandler<
       // promise and return it.
       void (async () => {
         try {
-          const { payload, status = 200 } = await buildJson.call(this, req, res)
-          writeJson(res, payload, { status })
-        } catch (cause) {
-          const error =
-            cause instanceof Error
-              ? cause
-              : new Error('Failed to build JSON response', { cause })
-          next(error satisfies Error)
+          const jsonResponse = await buildJson.call(this, req, res)
+          const { json, status = 200, ...options } = jsonResponse
+          writeJson(res, json, { ...options, status })
+        } catch (err) {
+          next(asError(err, 'Failed to build JSON response'))
         }
       })()
     } else {
@@ -135,3 +132,7 @@ export function jsonHandler<
     }
   }
 }
+
+function asError(cause: unknown, message: string): Error {
+  return cause instanceof Error ? cause : new Error(message, { cause })
+}

package/src/lib/http/stream.ts

@@ -49,3 +49,9 @@ export async function parseHttpRequest<A extends readonly KnownNames[]>(
     Extract<KnownParser, { name: A[number] }>
   >
 }
+
+export async function flushStream(stream: AsyncIterable<any>): Promise<void> {
+  for await (const _ of stream) {
+    // Consume the stream to completion
+  }
+}

package/src/lib/util/error.ts

@@ -0,0 +1,7 @@
+import { ZodError } from 'zod'
+import { formatZodError } from './zod-error.js'
+
+export function formatError(err: unknown, prefix: string): string {
+  if (err instanceof ZodError) return formatZodError(err, prefix)
+  return prefix
+}

package/src/lib/util/zod-error.ts

@@ -1,14 +1,26 @@
-import { ZodError } from 'zod'
-
-export function extractZodErrorMessage(err: unknown): string | undefined {
-  if (err instanceof ZodError) {
-    const issue = err.issues[0]
-    if (issue?.path.length) {
-      // "part" will typically be "body" or "query"
-      const [part, ...path] = issue.path
-      return `Validation of "${path.join('.')}" ${part} parameter failed: ${issue.message}`
-    }
+import { ZodError, ZodIssue, ZodIssueCode } from 'zod'
+
+export function formatZodError(err: ZodError, prefix?: string): string {
+  const message = err.issues.length
+    ? err.issues.map(formatZodIssue).join('; ')
+    : err.message // Should never happen (issues should never be empty)
+  return prefix ? `${prefix}: ${message}` : message
+}
+
+export function formatZodIssue(issue: ZodIssue): string {
+  if (issue.code === ZodIssueCode.invalid_union) {
+    return issue.unionErrors
+      .map((err) => err.issues.map(formatZodIssue).join('; '))
+      .join(', or ')
+  }
+
+  if (issue.path.length === 1 && typeof issue.path[0] === 'number') {
+    return `${issue.message} at index ${issue.path[0]}`
+  }
+
+  if (issue.path.length) {
+    return `${issue.message} at ${issue.path.join('.')}`
   }
 
-  return undefined
+  return issue.message
 }

package/src/oauth-errors.ts

@@ -3,6 +3,7 @@ export { OAuthError } from './errors/oauth-error.js'
 
 export * from './errors/access-denied-error.js'
 export * from './errors/account-selection-required-error.js'
+export * from './errors/authorization-error.js'
 export * from './errors/consent-required-error.js'
 export * from './errors/handle-unavailable-error.js'
 export * from './errors/invalid-authorization-details-error.js'
@@ -13,7 +14,6 @@ export * from './errors/invalid-dpop-key-binding-error.js'
 export * from './errors/invalid-dpop-proof-error.js'
 export * from './errors/invalid-grant-error.js'
 export * from './errors/invalid-invite-code-error.js'
-export * from './errors/invalid-parameters-error.js'
 export * from './errors/invalid-redirect-uri-error.js'
 export * from './errors/invalid-request-error.js'
 export * from './errors/invalid-scope-error.js'

package/src/oauth-hooks.ts

@@ -12,7 +12,9 @@ import { ClientAuth } from './client/client-auth.js'
 import { ClientId } from './client/client-id.js'
 import { ClientInfo } from './client/client-info.js'
 import { Client } from './client/client.js'
+import { AccessDeniedError } from './errors/access-denied-error.js'
 import { InvalidRequestError } from './errors/invalid-request-error.js'
+import { OAuthError } from './errors/oauth-error.js'
 import {
   HcaptchaClientTokens,
   HcaptchaConfig,
@@ -20,7 +22,6 @@ import {
 } from './lib/hcaptcha.js'
 import { RequestMetadata } from './lib/http/request.js'
 import { Awaitable } from './lib/util/type.js'
-import { AccessDeniedError, OAuthError } from './oauth-errors.js'
 import { DeviceId, SignUpData } from './oauth-store.js'
 import { RequestId } from './request/request-id.js'
 
@@ -118,7 +119,7 @@ export type OAuthHooks = {
   /**
    * This hook is called when a client is authorized.
    *
-   * @throws {AccessDeniedError} to deny the authorization request and redirect
+   * @throws {AuthorizationError} to deny the authorization request and redirect
    * the user to the client with an OAuth error (other errors will result in an
    * internal server error being displayed to the user)
    *

package/src/oauth-provider.ts

@@ -1,6 +1,5 @@
 import { createHash } from 'node:crypto'
 import type { Redis, RedisOptions } from 'ioredis'
-import { ZodError } from 'zod'
 import { Jwks, Keyset } from '@atproto/jwk'
 import type { Account } from '@atproto/oauth-provider-api'
 import {
@@ -64,8 +63,8 @@ import {
   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'
+import { AuthorizationError } from './errors/authorization-error.js'
 import { ConsentRequiredError } from './errors/consent-required-error.js'
 import { InvalidDpopKeyBindingError } from './errors/invalid-dpop-key-binding-error.js'
 import { InvalidDpopProofError } from './errors/invalid-dpop-proof-error.js'
@@ -75,8 +74,8 @@ import { LoginRequiredError } from './errors/login-required-error.js'
 import { HcaptchaConfig } from './lib/hcaptcha.js'
 import { RequestMetadata } from './lib/http/request.js'
 import { dateToRelativeSeconds } from './lib/util/date.js'
+import { formatError } from './lib/util/error.js'
 import { LocalizedString, MultiLangString } from './lib/util/locale.js'
-import { extractZodErrorMessage } from './lib/util/zod-error.js'
 import { CustomMetadata, buildMetadata } from './metadata/build-metadata.js'
 import { OAuthHooks } from './oauth-hooks.js'
 import {
@@ -104,6 +103,7 @@ import {
   VerifyTokenClaimsOptions,
   VerifyTokenClaimsResult,
 } from './token/verify-token-claims.js'
+import { isPARResponseError } from './types/par-response-error.js'
 
 export { AccessTokenMode, Keyset }
 export type {
@@ -448,11 +448,8 @@ export class OAuthProvider extends OAuthVerifier {
     const parameters = await oauthAuthorizationRequestParametersSchema
       .parseAsync(payload)
       .catch((err) => {
-        const message =
-          err instanceof ZodError
-            ? `Invalid request parameters: ${err.message}`
-            : `Invalid "request" object`
-        throw InvalidRequestError.from(err, message)
+        const msg = formatError(err, 'Invalid parameters in JAR')
+        throw new InvalidRequestError(msg, err)
       })
 
     return parameters
@@ -522,7 +519,7 @@ export class OAuthProvider extends OAuthVerifier {
       // > Since initial processing of the pushed authorization request does not
       // > involve resource owner interaction, error codes related to user
       // > interaction, such as "access_denied", are never returned.
-      if (err instanceof AccessDeniedError) {
+      if (err instanceof AuthorizationError && !isPARResponseError(err.error)) {
         throw new InvalidRequestError(err.error_description, err)
       }
       throw err
@@ -539,10 +536,8 @@ export class OAuthProvider extends OAuthVerifier {
       const requestUri = await requestUriSchema
         .parseAsync(query.request_uri, { path: ['query', 'request_uri'] })
         .catch((err) => {
-          throw new InvalidRequestError(
-            extractZodErrorMessage(err) ?? 'Input validation error',
-            err,
-          )
+          const msg = formatError(err, 'Invalid "request_uri" query parameter')
+          throw new InvalidRequestError(msg, err)
         })
 
       return this.requestManager.get(requestUri, deviceId, client.id)
@@ -592,24 +587,24 @@ export class OAuthProvider extends OAuthVerifier {
     const { issuer } = this
 
     // If there is a chance to redirect the user to the client, let's do
-    // it by wrapping the error in an AccessDeniedError.
-    const accessDeniedCatcher =
+    // it by wrapping the error in an AuthorizationError.
+    const throwAuthorizationError =
       'redirect_uri' in query
         ? (err: unknown): never => {
             // https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11#section-4.1.2.1
-            throw AccessDeniedError.from(query, err, 'invalid_request')
+            throw AuthorizationError.from(query, err)
           }
         : null
 
     const client = await this.clientManager
       .getClient(clientCredentials.client_id)
-      .catch(accessDeniedCatcher)
+      .catch(throwAuthorizationError)
 
     const { parameters, uri } = await this.processAuthorizationRequest(
       client,
       deviceId,
       query,
-    ).catch(accessDeniedCatcher)
+    ).catch(throwAuthorizationError)
 
     try {
       const sessions = await this.getSessions(client.id, deviceId, parameters)
@@ -694,9 +689,7 @@ export class OAuthProvider extends OAuthVerifier {
         // (allowing to log this error)
       }
 
-      // Not using accessDeniedCatcher here because "parameters" will most
-      // likely contain the redirect_uri (using the client default).
-      throw AccessDeniedError.from(parameters, err, 'server_error')
+      throw AuthorizationError.from(parameters, err)
     }
   }
 
@@ -872,12 +865,8 @@ export class OAuthProvider extends OAuthVerifier {
     const code = await codeSchema
       .parseAsync(input.code, { path: ['code'] })
       .catch((err) => {
-        throw InvalidGrantError.from(
-          err,
-          err instanceof ZodError
-            ? `Invalid code: ${err.message}`
-            : `Invalid code`,
-        )
+        const msg = formatError(err, 'Invalid code')
+        throw new InvalidGrantError(msg, err)
       })
 
     const data = await this.requestManager
@@ -999,7 +988,8 @@ export class OAuthProvider extends OAuthVerifier {
     const refreshToken = await refreshTokenSchema
       .parseAsync(input.refresh_token, { path: ['refresh_token'] })
       .catch((err) => {
-        throw InvalidGrantError.from(err, `Invalid refresh token`)
+        const msg = formatError(err, 'Invalid refresh token')
+        throw new InvalidGrantError(msg, err)
       })
 
     const tokenInfo = await this.tokenManager.consumeRefreshToken(refreshToken)

package/src/request/request-manager.ts

@@ -16,10 +16,10 @@ import {
 } from '../constants.js'
 import { DeviceId } from '../device/device-id.js'
 import { AccessDeniedError } from '../errors/access-denied-error.js'
+import { AuthorizationError } from '../errors/authorization-error.js'
 import { ConsentRequiredError } from '../errors/consent-required-error.js'
 import { InvalidAuthorizationDetailsError } from '../errors/invalid-authorization-details-error.js'
 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 { InvalidScopeError } from '../errors/invalid-scope-error.js'
 import { RequestMetadata } from '../lib/http/request.js'
@@ -93,10 +93,7 @@ export class RequestManager {
       'nonce', // note that OIDC "nonce" is redundant with PKCE
     ] as const) {
       if (parameters[k] !== undefined) {
-        throw new InvalidParametersError(
-          parameters,
-          `Unsupported "${k}" parameter`,
-        )
+        throw new AuthorizationError(parameters, `Unsupported "${k}" parameter`)
       }
     }
 
@@ -109,7 +106,7 @@ export class RequestManager {
         parameters.response_type,
       )
     ) {
-      throw new AccessDeniedError(
+      throw new AuthorizationError(
         parameters,
         `Unsupported response_type "${parameters.response_type}"`,
         'unsupported_response_type',
@@ -120,7 +117,7 @@ export class RequestManager {
       parameters.response_type === 'code' &&
       !this.metadata.grant_types_supported?.includes('authorization_code')
     ) {
-      throw new AccessDeniedError(
+      throw new AuthorizationError(
         parameters,
         `Unsupported grant_type "authorization_code"`,
         'invalid_request',
@@ -133,7 +130,7 @@ export class RequestManager {
         // defined in the server metadata. In the future, we might add support
         // for dynamic scopes.
         if (!this.metadata.scopes_supported?.includes(scope)) {
-          throw new InvalidParametersError(
+          throw new AuthorizationError(
             parameters,
             `Scope "${scope}" is not supported by this server`,
           )
@@ -169,7 +166,7 @@ export class RequestManager {
     if (!parameters.redirect_uri) {
       // Should already be ensured by client.validateRequest(). Adding here for
       // clarity & extra safety.
-      throw new InvalidParametersError(parameters, 'Missing "redirect_uri"')
+      throw new AuthorizationError(parameters, 'Missing "redirect_uri"')
     }
 
     // https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-10#section-1.4.1
@@ -195,7 +192,7 @@ export class RequestManager {
         case 'S256':
           break
         default: {
-          throw new InvalidParametersError(
+          throw new AuthorizationError(
             parameters,
             `Unsupported code_challenge_method "${parameters.code_challenge_method}"`,
           )
@@ -204,7 +201,7 @@ export class RequestManager {
     } else {
       if (parameters.code_challenge_method) {
         // https://datatracker.ietf.org/doc/html/rfc7636#section-4.4.1
-        throw new InvalidParametersError(
+        throw new AuthorizationError(
           parameters,
           'code_challenge is required when code_challenge_method is provided',
         )
@@ -225,7 +222,7 @@ export class RequestManager {
       // atproto does not implement the OpenID Connect nonce mechanism, so we
       // require the use of PKCE for all clients.
 
-      throw new InvalidParametersError(parameters, 'Use of PKCE is required')
+      throw new AuthorizationError(parameters, 'Use of PKCE is required')
     }
 
     // -----------------
@@ -233,7 +230,7 @@ export class RequestManager {
     // -----------------
 
     if (parameters.response_type !== 'code') {
-      throw new InvalidParametersError(
+      throw new AuthorizationError(
         parameters,
         'atproto only supports the "code" response_type',
       )
@@ -249,7 +246,7 @@ export class RequestManager {
     }
 
     if (parameters.code_challenge_method !== 'S256') {
-      throw new InvalidParametersError(
+      throw new AuthorizationError(
         parameters,
         'atproto requires use of "S256" code_challenge_method',
       )
@@ -280,10 +277,7 @@ export class RequestManager {
     const hint = parameters.login_hint?.toLowerCase()
     if (hint) {
       if (!isAtprotoDid(hint) && !isValidHandle(hint)) {
-        throw new InvalidParametersError(
-          parameters,
-          `Invalid login_hint "${hint}"`,
-        )
+        throw new AuthorizationError(parameters, `Invalid login_hint "${hint}"`)
       }
 
       // @TODO: ensure that the account actually exists on this server (there is