@atproto/oauth-provider 0.9.2 → 0.10.0

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/metadata/build-metadata.ts

@@ -8,7 +8,6 @@ import { Client } from '../client/client.js'
 import { VERIFY_ALGOS } from '../lib/util/crypto.js'
 
 export type CustomMetadata = {
-  scopes_supported?: string[]
   authorization_details_types_supported?: string[]
   protected_resources?: string[]
 }
@@ -27,8 +26,14 @@ export function buildMetadata(
 
     scopes_supported: [
       'atproto',
-      //
-      ...(customMetadata?.scopes_supported ?? []),
+
+      // These serve as hint that this server supports the transitional scopes.
+      // This is not a specced behavior.
+      'transition:email',
+      'transition:generic',
+      'transition:chat.bsky',
+
+      // Other atproto scopes can't be enumerated as they are dynamic.
     ],
     subject_types_supported: [
       //

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,10 @@ 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 { AuthorizationError } from './errors/authorization-error.js'
 import { InvalidRequestError } from './errors/invalid-request-error.js'
+import { OAuthError } from './errors/oauth-error.js'
 import {
   HcaptchaClientTokens,
   HcaptchaConfig,
@@ -20,7 +23,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'
 
@@ -28,6 +30,7 @@ import { RequestId } from './request/request-id.js'
 export {
   AccessDeniedError,
   type Account,
+  AuthorizationError,
   type Awaitable,
   Client,
   type ClientAuth,
@@ -115,10 +118,23 @@ export type OAuthHooks = {
     deviceMetadata: RequestMetadata
   }) => Awaitable<void>
 
+  /**
+   * Allows validating an authorization request (typically the requested scopes)
+   * before it is created. Note that the validity against the client metadata is
+   * already enforced by the OAuth provider.
+   *
+   * @throws {AuthorizationError}
+   */
+  onAuthorizationRequest?: (data: {
+    client: Client
+    clientAuth: null | ClientAuth
+    parameters: Readonly<OAuthAuthorizationRequestParameters>
+  }) => Awaitable<void>
+
   /**
    * 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 {
@@ -233,6 +233,7 @@ export type OAuthProviderOptions = OAuthProviderConfig &
 
 export class OAuthProvider extends OAuthVerifier {
   protected readonly accessTokenMode: AccessTokenMode
+  protected readonly hooks: OAuthHooks
 
   public readonly metadata: OAuthAuthorizationServerMetadata
   public readonly customization: Customization
@@ -286,21 +287,19 @@ export class OAuthProvider extends OAuthVerifier {
     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, ...superOptions })
 
+    // @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 don't
+    // really need if types are respected.
+    this.hooks = rest
+
     this.accessTokenMode = accessTokenMode
     this.authenticationMaxAge = authenticationMaxAge
     this.metadata = buildMetadata(this.issuer, this.keyset, metadata)
@@ -310,13 +309,13 @@ export class OAuthProvider extends OAuthVerifier {
     this.accountManager = new AccountManager(
       this.issuer,
       accountStore,
-      hooks,
+      this.hooks,
       this.customization,
     )
     this.clientManager = new ClientManager(
       this.metadata,
       this.keyset,
-      hooks,
+      this.hooks,
       clientStore || null,
       loopbackMetadata || null,
       safeFetch,
@@ -327,12 +326,12 @@ export class OAuthProvider extends OAuthVerifier {
       requestStore,
       this.signer,
       this.metadata,
-      hooks,
+      this.hooks,
     )
     this.tokenManager = new TokenManager(
       tokenStore,
       this.signer,
-      hooks,
+      this.hooks,
       this.accessTokenMode,
       tokenMaxAge,
     )
@@ -448,11 +447,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
@@ -505,7 +501,7 @@ export class OAuthProvider extends OAuthVerifier {
         }
       }
 
-      const { uri, expiresAt } =
+      const { requestUri, expiresAt } =
         await this.requestManager.createAuthorizationRequest(
           client,
           clientAuth,
@@ -514,7 +510,7 @@ export class OAuthProvider extends OAuthVerifier {
         )
 
       return {
-        request_uri: uri,
+        request_uri: requestUri,
         expires_in: dateToRelativeSeconds(expiresAt),
       }
     } catch (err) {
@@ -522,7 +518,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 +535,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 +586,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(
+    const { parameters, requestUri } = await this.processAuthorizationRequest(
       client,
       deviceId,
       query,
-    ).catch(accessDeniedCatcher)
+    ).catch(throwAuthorizationError)
 
     try {
       const sessions = await this.getSessions(client.id, deviceId, parameters)
@@ -632,7 +626,7 @@ export class OAuthProvider extends OAuthVerifier {
         }
 
         const code = await this.requestManager.setAuthorized(
-          uri,
+          requestUri,
           client,
           ssoSession.account,
           deviceId,
@@ -649,7 +643,7 @@ export class OAuthProvider extends OAuthVerifier {
           const ssoSession = ssoSessions[0]!
           if (!ssoSession.loginRequired && !ssoSession.consentRequired) {
             const code = await this.requestManager.setAuthorized(
-              uri,
+              requestUri,
               client,
               ssoSession.account,
               deviceId,
@@ -665,7 +659,7 @@ export class OAuthProvider extends OAuthVerifier {
         issuer,
         client,
         parameters,
-        uri,
+        requestUri,
         sessions: sessions.map((session) => ({
           // Map to avoid leaking other data that might be present in the session
           account: session.account,
@@ -673,20 +667,10 @@ export class OAuthProvider extends OAuthVerifier {
           loginRequired: session.loginRequired,
           consentRequired: session.consentRequired,
         })),
-        scopeDetails: parameters.scope
-          ?.split(/\s+/)
-          .filter(Boolean)
-          .sort((a, b) => a.localeCompare(b))
-          .map((scope) => ({
-            scope,
-            // @TODO Allow to customize the scope descriptions (e.g.
-            // using a hook)
-            description: undefined,
-          })),
       }
     } catch (err) {
       try {
-        await this.requestManager.delete(uri)
+        await this.requestManager.delete(requestUri)
       } catch {
         // There are two error here. Better keep the outer one.
         //
@@ -694,9 +678,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 +854,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 +977,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/oauth-verifier.ts

@@ -26,6 +26,8 @@ import {
   verifyTokenClaims,
 } from './token/verify-token-claims.js'
 
+export type * from './token/verify-token-claims.js'
+
 export type OAuthVerifierOptions = Override<
   DpopManagerOptions,
   {
@@ -51,7 +53,7 @@ export type OAuthVerifierOptions = Override<
 >
 
 export { DpopNonce, Key, Keyset }
-export type { DpopProof, RedisOptions, ReplayStore, VerifyTokenClaimsOptions }
+export type { DpopProof, RedisOptions, ReplayStore }
 
 export class OAuthVerifier {
   public readonly issuer: OAuthIssuerIdentifier