@atproto/oauth-provider 0.9.2 → 0.10.0

package/src/router/create-api-middleware.ts

@@ -20,16 +20,22 @@ import {
 import { signInDataSchema } from '../account/sign-in-data.js'
 import { signUpInputSchema } from '../account/sign-up-input.js'
 import { DeviceId, deviceIdSchema } from '../device/device-id.js'
-import { AccessDeniedError } from '../errors/access-denied-error.js'
-import { buildErrorPayload, buildErrorStatus } from '../errors/error-parser.js'
+import { AuthorizationError } from '../errors/authorization-error.js'
+import {
+  ErrorPayload,
+  buildErrorPayload,
+  buildErrorStatus,
+} from '../errors/error-parser.js'
 import { InvalidRequestError } from '../errors/invalid-request-error.js'
 import { WWWAuthenticateError } from '../errors/www-authenticate-error.js'
 import {
+  JsonResponse,
   Middleware,
   RequestMetadata,
   Router,
   RouterCtx,
   SubCtx,
+  flushStream,
   jsonHandler,
   parseHttpRequest,
   subCtx,
@@ -84,7 +90,7 @@ export function createApiMiddleware<
       schema: verifyHandleSchema,
       async handler() {
         await server.accountManager.verifyHandleAvailability(this.input.handle)
-        return { available: true }
+        return { json: { available: true } }
       },
     }),
   )
@@ -121,7 +127,8 @@ export function createApiMiddleware<
               requestUri: this.requestUri,
             })
 
-        return { account, ephemeralToken }
+        const json = { account, ephemeralToken }
+        return { json }
       },
     }),
   )
@@ -173,7 +180,7 @@ export function createApiMiddleware<
             account.sub,
           )
 
-          return {
+          const json = {
             account,
             ephemeralToken,
             consentRequired: server.checkConsentRequired(
@@ -181,9 +188,12 @@ export function createApiMiddleware<
               authorizedClients.get(clientId),
             ),
           }
+
+          return { json }
         }
 
-        return { account, ephemeralToken }
+        const json = { account, ephemeralToken }
+        return { json }
       },
     }),
   )
@@ -205,7 +215,7 @@ export function createApiMiddleware<
           await server.accountManager.removeDeviceAccount(this.deviceId, sub)
         }
 
-        return { success: true as const }
+        return { json: { success: true as const } }
       },
     }),
   )
@@ -222,7 +232,7 @@ export function createApiMiddleware<
         .strict(),
       async handler() {
         await server.accountManager.resetPasswordRequest(this.input)
-        return { success: true }
+        return { json: { success: true } }
       },
     }),
   )
@@ -239,7 +249,7 @@ export function createApiMiddleware<
         .strict(),
       async handler() {
         await server.accountManager.resetPasswordConfirm(this.input)
-        return { success: true }
+        return { json: { success: true } }
       },
     }),
   )
@@ -254,12 +264,14 @@ export function createApiMiddleware<
           this.deviceId,
         )
 
-        return deviceAccounts.map(
+        const json = deviceAccounts.map(
           (deviceAccount): ActiveDeviceSession => ({
             account: deviceAccount.account,
             loginRequired: server.checkLoginRequired(deviceAccount),
           }),
         )
+
+        return { json }
       },
     }),
   )
@@ -289,7 +301,7 @@ export function createApiMiddleware<
         // expose the expiration date). This requires a change to the way
         // TokenInfo are stored (see TokenManager#isTokenExpired and
         // TokenManager#isTokenInactive).
-        return tokenInfos.map(({ id, data }): ActiveOAuthSession => {
+        const json = tokenInfos.map(({ id, data }): ActiveOAuthSession => {
           return {
             tokenId: id,
 
@@ -302,6 +314,8 @@ export function createApiMiddleware<
             scope: data.parameters.scope,
           }
         })
+
+        return { json }
       },
     }),
   )
@@ -318,7 +332,7 @@ export function createApiMiddleware<
           account.sub,
         )
 
-        return deviceAccounts.map(
+        const json = deviceAccounts.map(
           (accountSession): ActiveAccountSession => ({
             deviceId: accountSession.deviceId,
             deviceMetadata: {
@@ -331,6 +345,8 @@ export function createApiMiddleware<
             isCurrentDevice: accountSession.deviceId === this.deviceId,
           }),
         )
+
+        return { json }
       },
     }),
   )
@@ -350,7 +366,7 @@ export function createApiMiddleware<
           this.input.sub,
         )
 
-        return { success: true }
+        return { json: { success: true } }
       },
     }),
   )
@@ -374,7 +390,7 @@ export function createApiMiddleware<
 
         await server.tokenManager.deleteToken(tokenInfo.id)
 
-        return { success: true }
+        return { json: { success: true } }
       },
     }),
   )
@@ -382,8 +398,13 @@ export function createApiMiddleware<
   router.use(
     apiRoute({
       method: 'POST',
-      endpoint: '/accept',
-      schema: z.object({ sub: z.union([subSchema, signedJwtSchema]) }).strict(),
+      endpoint: '/consent',
+      schema: z
+        .object({
+          sub: z.union([subSchema, signedJwtSchema]),
+          scope: z.string().optional(),
+        })
+        .strict(),
       async handler(req, res) {
         if (!this.requestUri) {
           throw new InvalidRequestError(
@@ -391,7 +412,7 @@ export function createApiMiddleware<
           )
         }
 
-        // Any AccessDeniedError caught in this block will result in a redirect
+        // Any AuthorizationError caught in this block will result in a redirect
         // to the client's redirect_uri with an error.
         try {
           const { clientId, parameters } = await server.requestManager.get(
@@ -400,7 +421,7 @@ export function createApiMiddleware<
           )
 
           // Any error thrown in this block will be transformed into an
-          // AccessDeniedError.
+          // AuthorizationError.
           try {
             const { account, authorizedClients } = await authenticate.call(
               this,
@@ -416,6 +437,7 @@ export function createApiMiddleware<
               account,
               this.deviceId,
               this.deviceMetadata,
+              this.input.scope,
             )
 
             const clientData = authorizedClients.get(clientId)
@@ -436,13 +458,15 @@ export function createApiMiddleware<
 
             const url = buildRedirectUrl(server.issuer, parameters, { code })
 
-            return { url }
+            return { json: { url } }
           } catch (err) {
             // Since we have access to the parameters, we can re-throw an
-            // AccessDeniedError with the redirect_uri parameter.
-            throw AccessDeniedError.from(parameters, err, 'server_error')
+            // AuthorizationError with the redirect_uri parameter.
+            throw AuthorizationError.from(parameters, err)
           }
         } catch (err) {
+          onError?.(req, res, err, 'Failed to consent authorization request')
+
           // If any error happened (unauthenticated, invalid request, etc.),
           // lets make sure the request can no longer be used.
           try {
@@ -451,20 +475,24 @@ export function createApiMiddleware<
             onError?.(req, res, err, 'Failed to delete request')
           }
 
-          if (err instanceof AccessDeniedError && err.parameters.redirect_uri) {
-            // Prefer logging the cause
-            onError?.(req, res, err.cause ?? err, 'Authorization failed')
-
-            const url = buildRedirectUrl(
-              server.issuer,
-              err.parameters,
-              err.toJSON(),
-            )
+          if (err instanceof AuthorizationError) {
+            try {
+              const url = buildRedirectUrl(
+                server.issuer,
+                err.parameters,
+                err.toJSON(),
+              )
 
-            return { url }
+              return { json: { url } }
+            } catch {
+              // Unable to build redirect URL, ignore
+            }
           }
 
-          throw err
+          // @NOTE Not re-throwing the error here, as the error was already
+          // handled by the `onError` callback, and apiRoute (`apiMiddleware`)
+          // would call `onError` again.
+          return buildErrorJsonResponse(err)
         }
       },
     }),
@@ -507,22 +535,25 @@ export function createApiMiddleware<
             error_description: 'The user rejected the request',
           })
 
-          return { url }
+          return { json: { url } }
         } catch (err) {
-          if (err instanceof AccessDeniedError && err.parameters.redirect_uri) {
-            // Prefer logging the cause
-            onError?.(req, res, err.cause ?? err, 'Authorization failed')
-
-            const url = buildRedirectUrl(
-              server.issuer,
-              err.parameters,
-              err.toJSON(),
-            )
+          onError?.(req, res, err, 'Failed to reject authorization request')
+
+          if (err instanceof AuthorizationError) {
+            try {
+              const url = buildRedirectUrl(
+                server.issuer,
+                err.parameters,
+                err.toJSON(),
+              )
 
-            return { url }
+              return { json: { url } }
+            } catch {
+              // Unable to build redirect URL, ignore
+            }
           }
 
-          throw err
+          return buildErrorJsonResponse(err)
         } finally {
           await server.requestManager.delete(requestUri).catch((err) => {
             onError?.(req, res, err, 'Failed to delete request')
@@ -637,7 +668,7 @@ export function createApiMiddleware<
       this: ApiContext<RouteCtx<C>, InferValidation<S>>,
       req: Req,
       res: Res,
-    ) => Awaitable<ApiEndpoints[E]['output']>
+    ) => Awaitable<JsonResponse<ErrorPayload | ApiEndpoints[E]['output']>>
   }): Middleware<C, Req, Res> {
     return createRoute(
       options.method,
@@ -659,12 +690,12 @@ export function createApiMiddleware<
       this: ApiContext<C, InferValidation<S>>,
       req: Req,
       res: Res,
-    ) => unknown
+    ) => Awaitable<JsonResponse>
   }): Middleware<C, Req, Res> {
     const parseInput: (this: C, req: Req) => Promise<InferValidation<S>> =
       schema == null // No schema means endpoint doesn't accept any input
         ? async function (req) {
-            req.resume() // Flush body
+            await flushStream(req)
             return undefined
           }
         : method === 'POST'
@@ -673,12 +704,7 @@ export function createApiMiddleware<
               return schema.parseAsync(body, { path: ['body'] })
             }
           : async function (req) {
-              // @NOTE This should not be necessary with GET requests
-              req.resume().once('error', (_err) => {
-                // Ignore errors when flushing the request body
-                // (e.g. client closed connection)
-              })
-
+              await flushStream(req)
               const query = Object.fromEntries(this.url.searchParams)
               return schema.parseAsync(query, { path: ['query'] })
             }
@@ -726,30 +752,32 @@ export function createApiMiddleware<
           rotateDeviceCookies,
         )
 
-        const context = subCtx(this, {
+        const context: ApiContext<C, InferValidation<S>> = subCtx(this, {
           input,
           requestUri,
           deviceId,
           deviceMetadata,
         })
 
-        // Generate the API response
-        const payload = await handler.call(context, req, res)
-
-        return { payload, status: 200 }
+        return await handler.call(context, req, res)
       } catch (err) {
-        onError?.(req, res, err, 'Failed to handle API request')
-
-        // @TODO Rework the API error responses (relying on codes)
-        const payload = buildErrorPayload(err)
-        const status = buildErrorStatus(err)
+        onError?.(req, res, err, `Failed to handle API request`)
 
-        return { payload, status }
+        // Make sore to always return a JSON response
+        return buildErrorJsonResponse(err)
       }
     })
   }
 }
 
+function buildErrorJsonResponse(err: unknown) {
+  // @TODO Rework the API error responses (relying on codes)
+  const json = buildErrorPayload(err)
+  const status = buildErrorStatus(err)
+
+  return { json, status }
+}
+
 function buildRedirectUrl(
   iss: string,
   parameters: OAuthAuthorizationRequestParameters,

package/src/router/create-authorization-page-middleware.ts

@@ -3,7 +3,7 @@ import {
   oauthAuthorizationRequestQuerySchema,
   oauthClientCredentialsSchema,
 } from '@atproto/oauth-types'
-import { AccessDeniedError } from '../errors/access-denied-error.js'
+import { AuthorizationError } from '../errors/authorization-error.js'
 import { InvalidRequestError } from '../errors/invalid-request-error.js'
 import {
   Middleware,
@@ -15,8 +15,8 @@ import {
   validateOrigin,
   validateReferrer,
 } from '../lib/http/index.js'
+import { formatError } from '../lib/util/error.js'
 import type { Awaitable } from '../lib/util/type.js'
-import { extractZodErrorMessage } from '../lib/util/zod-error.js'
 import type { OAuthProvider } from '../oauth-provider.js'
 import { requestUriSchema } from '../request/request-uri.js'
 import { AuthorizationResultRedirect } from '../result/authorization-result-redirect.js'
@@ -62,7 +62,7 @@ export function createAuthorizationPageMiddleware<
 
       const clientCredentials = await oauthClientCredentialsSchema
         .parseAsync(query, { path: ['query'] })
-        .catch(throwInvalidRequest)
+        .catch((err) => throwInvalidRequest(err, 'Invalid client credentials'))
 
       if ('client_secret' in clientCredentials) {
         throw new InvalidRequestError('Client secret must not be provided')
@@ -70,7 +70,7 @@ export function createAuthorizationPageMiddleware<
 
       const authorizationRequest = await oauthAuthorizationRequestQuerySchema
         .parseAsync(query, { path: ['query'] })
-        .catch(throwInvalidRequest)
+        .catch((err) => throwInvalidRequest(err, 'Invalid request parameters'))
 
       const deviceInfo = await server.deviceManager.load(req, res)
 
@@ -88,20 +88,21 @@ export function createAuthorizationPageMiddleware<
           return sendAuthorizePage(req, res, result)
         }
       } catch (err) {
-        // If we have the "redirect_uri" parameter, we can redirect the user
-        // to the client with an error.
-        if (err instanceof AccessDeniedError && err.parameters.redirect_uri) {
-          // Prefer logging the cause
-          onError?.(req, res, err.cause ?? err, 'Authorization failed')
-
-          return sendAuthorizeRedirect(res, {
-            issuer: server.issuer,
-            parameters: err.parameters,
-            redirect: err.toJSON(),
-          })
+        onError?.(req, res, err, 'Authorization request denied')
+
+        if (err instanceof AuthorizationError) {
+          try {
+            return sendAuthorizeRedirect(res, {
+              issuer: server.issuer,
+              parameters: err.parameters,
+              redirect: err.toJSON(),
+            })
+          } catch {
+            // If we fail to send the redirect, we fall back to sending an error
+          }
         }
 
-        throw err
+        return sendErrorPage(req, res, err)
       }
     }),
   )
@@ -155,11 +156,8 @@ export function createAuthorizationPageMiddleware<
   }
 }
 
-function throwInvalidRequest(err: unknown): never {
-  throw new InvalidRequestError(
-    extractZodErrorMessage(err) ?? 'Input validation error',
-    err,
-  )
+function throwInvalidRequest(err: unknown, prefix: string): never {
+  throw new InvalidRequestError(formatError(err, prefix), err)
 }
 
 function sendAuthorizeRedirect(

package/src/router/create-oauth-middleware.ts

@@ -19,7 +19,8 @@ import {
   parseHttpRequest,
   staticJsonMiddleware,
 } from '../lib/http/index.js'
-import { extractZodErrorMessage } from '../lib/util/zod-error.js'
+import { formatError } from '../lib/util/error.js'
+import { OAuthError } from '../oauth-errors.js'
 import type { OAuthProvider } from '../oauth-provider.js'
 import type { MiddlewareOptions } from './middleware-options.js'
 
@@ -98,11 +99,13 @@ export function createOAuthMiddleware<
 
       const credentials = await oauthClientCredentialsSchema
         .parseAsync(payload, { path: ['body'] })
-        .catch(throwInvalidClient)
+        .catch((err) => throwInvalidClient(err, 'Client credentials missing'))
 
       const authorizationRequest = await oauthAuthorizationRequestParSchema
         .parseAsync(payload, { path: ['body'] })
-        .catch(throwInvalidRequest)
+        .catch((err) =>
+          throwInvalidRequest(err, 'Invalid authorization request'),
+        )
 
       const dpopProof = await server.checkDpopProof(
         req.method!,
@@ -135,11 +138,11 @@ export function createOAuthMiddleware<
 
       const clientCredentials = await oauthClientCredentialsSchema
         .parseAsync(payload, { path: ['body'] })
-        .catch(throwInvalidGrant)
+        .catch((err) => throwInvalidGrant(err, 'Client credentials missing'))
 
       const tokenRequest = await oauthTokenRequestSchema
         .parseAsync(payload, { path: ['body'] })
-        .catch(throwInvalidGrant)
+        .catch((err) => throwInvalidGrant(err, 'Invalid request payload'))
 
       const dpopProof = await server.checkDpopProof(
         req.method!,
@@ -165,11 +168,11 @@ export function createOAuthMiddleware<
 
       const credentials = await oauthClientCredentialsSchema
         .parseAsync(payload, { path: ['body'] })
-        .catch(throwInvalidRequest)
+        .catch((err) => throwInvalidRequest(err, 'Client credentials missing'))
 
       const tokenIdentification = await oauthTokenIdentificationSchema
         .parseAsync(payload, { path: ['body'] })
-        .catch(throwInvalidRequest)
+        .catch((err) => throwInvalidRequest(err, 'Invalid request payload'))
 
       const dpopProof = await server.checkDpopProof(
         req.method!,
@@ -214,10 +217,17 @@ export function createOAuthMiddleware<
           res.appendHeader('Access-Control-Expose-Headers', name)
         }
 
-        const payload = await buildOAuthResponse.call(this, req, res)
-        return { payload, status }
+        const json = await buildOAuthResponse.call(this, req, res)
+        return { json, status }
       } catch (err) {
-        onError?.(req, res, err, 'OAuth request error')
+        onError?.(
+          req,
+          res,
+          err,
+          err instanceof OAuthError
+            ? `OAuth "${err.error}" error`
+            : 'Unexpected error',
+        )
 
         if (!res.headersSent && err instanceof WWWAuthenticateError) {
           const name = 'WWW-Authenticate'
@@ -226,31 +236,22 @@ export function createOAuthMiddleware<
         }
 
         const status = buildErrorStatus(err)
-        const payload = buildErrorPayload(err)
+        const json = buildErrorPayload(err)
 
-        return { payload, status }
+        return { json, status }
       }
     })
   }
 }
 
-function throwInvalidGrant(err: unknown): never {
-  throw new InvalidGrantError(
-    extractZodErrorMessage(err) ?? 'Invalid grant',
-    err,
-  )
+function throwInvalidGrant(err: unknown, prefix: string): never {
+  throw new InvalidGrantError(formatError(err, prefix), err)
 }
 
-function throwInvalidClient(err: unknown): never {
-  throw new InvalidClientError(
-    extractZodErrorMessage(err) ?? 'Client authentication failed',
-    err,
-  )
+function throwInvalidClient(err: unknown, prefix: string): never {
+  throw new InvalidClientError(formatError(err, prefix), err)
 }
 
-function throwInvalidRequest(err: unknown): never {
-  throw new InvalidRequestError(
-    extractZodErrorMessage(err) ?? 'Input validation error',
-    err,
-  )
+function throwInvalidRequest(err: unknown, prefix: string): never {
+  throw new InvalidRequestError(formatError(err, prefix), err)
 }

package/src/router/send-redirect.ts

@@ -3,7 +3,7 @@ import {
   OAuthAuthorizationRequestParameters,
   OAuthResponseMode,
 } from '@atproto/oauth-types'
-import { AccessDeniedError } from '../errors/access-denied-error.js'
+import { AuthorizationError } from '../errors/authorization-error.js'
 import { html, js } from '../lib/html/index.js'
 import { sendWebPage } from '../lib/send-web-page.js'
 import { AuthorizationRedirectParameters } from '../result/authorization-redirect-parameters.js'
@@ -37,7 +37,7 @@ export function buildRedirectUri(
   const uri = parameters.redirect_uri
   if (uri) return uri
 
-  throw new AccessDeniedError(parameters, 'No redirect_uri', 'invalid_request')
+  throw new AuthorizationError(parameters, 'No redirect_uri', 'invalid_request')
 }
 
 export function buildRedirectMode(

package/src/token/token-manager.ts

@@ -299,7 +299,7 @@ export class TokenManager {
     // @TODO Add another store method that atomically consumes the refresh token
     // with a lock.
     const tokenInfo = await this.findByRefreshToken(token).catch((err) => {
-      throw InvalidTokenError.from(err, `Invalid refresh token`)
+      throw InvalidGrantError.from(err, `Invalid refresh token`)
     })
 
     if (!tokenInfo) {

package/src/token/verify-token-claims.ts

@@ -10,6 +10,14 @@ import { TokenId } from './token-id.js'
 const BEARER = 'Bearer' satisfies OAuthTokenType
 const DPOP = 'DPoP' satisfies OAuthTokenType
 
+export type {
+  DpopProof,
+  OAuthAccessToken,
+  OAuthTokenType,
+  SignedTokenPayload,
+  TokenId,
+}
+
 export type VerifyTokenClaimsOptions = {
   /** One of these audience must be included in the token audience(s) */
   audience?: [string, ...string[]]

package/src/types/authorization-response-error.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod'
+import {
+  oauthAuthorizationResponseErrorSchema,
+  oidcAuthorizationResponseErrorSchema,
+} from '@atproto/oauth-types'
+
+export const authorizationResponseErrorSchema = z.union([
+  oauthAuthorizationResponseErrorSchema,
+  // OIDC authentication error response are not part of the ATproto flavoured
+  // OAuth but we allow them because they provide better feedback to the client
+  // (in particular when SSO is used).
+  oidcAuthorizationResponseErrorSchema,
+  // This error is defined by rfc9396 (not part of the OAuth 2.1 or OIDC). But
+  // since, in ATproto flavoured OAuth, client registration is a dynamic part of
+  // the authorization process, we allow it.
+  z.literal('invalid_authorization_details'),
+])
+
+export type AuthorizationResponseError = z.infer<
+  typeof authorizationResponseErrorSchema
+>
+
+export function isAuthorizationResponseError<T>(
+  value: T,
+): value is T & AuthorizationResponseError {
+  return authorizationResponseErrorSchema.safeParse(value).success
+}

package/src/types/par-response-error.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+import { authorizationResponseErrorSchema } from './authorization-response-error.js'
+
+// 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 "access_denied", are never returned.
+
+export const parResponseErrorSchema = z.intersection(
+  authorizationResponseErrorSchema,
+  z.enum([
+    'invalid_request',
+    'unauthorized_client',
+    'unsupported_response_type',
+    'invalid_scope',
+    'server_error',
+    'temporarily_unavailable',
+  ]),
+)
+
+export type PARResponseError = z.infer<typeof parResponseErrorSchema>
+
+export function isPARResponseError<T>(value: T): value is T & PARResponseError {
+  return parResponseErrorSchema.safeParse(value).success
+}