@atproto/oauth-provider 0.11.1 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/oauth-provider",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "license": "MIT",
   "description": "Generic OAuth2 and OpenID Connect provider for Node.js. Currently only supports features needed for Atproto.",
   "keywords": [
@@ -43,21 +43,21 @@
     "jose": "^5.2.0",
     "zod": "^3.23.8",
     "@atproto-labs/fetch": "0.2.3",
-    "@atproto-labs/pipe": "0.1.1",
     "@atproto-labs/fetch-node": "0.1.10",
+    "@atproto-labs/pipe": "0.1.1",
     "@atproto-labs/simple-store": "0.3.0",
     "@atproto-labs/simple-store-memory": "0.1.4",
-    "@atproto/common": "^0.4.11",
+    "@atproto/common": "^0.4.12",
     "@atproto/did": "0.2.0",
     "@atproto/jwk": "0.5.0",
     "@atproto/jwk-jose": "0.1.10",
-    "@atproto/lexicon": "0.5.0",
-    "@atproto/lexicon-resolver": "0.2.0",
+    "@atproto/lexicon": "0.5.1",
+    "@atproto/lexicon-resolver": "0.2.1",
     "@atproto/oauth-types": "0.4.1",
     "@atproto/oauth-provider-api": "0.3.0",
-    "@atproto/oauth-provider-frontend": "0.2.0",
-    "@atproto/oauth-provider-ui": "0.3.0",
-    "@atproto/oauth-scopes": "0.1.0",
+    "@atproto/oauth-provider-frontend": "0.2.1",
+    "@atproto/oauth-provider-ui": "0.3.1",
+    "@atproto/oauth-scopes": "0.2.0",
     "@atproto/syntax": "0.4.1"
   },
   "devDependencies": {

package/src/access-token/access-token-mode.ts

@@ -1,4 +1,4 @@
 export enum AccessTokenMode {
   stateless = 'stateless',
-  light = 'light',
+  stateful = 'stateful',
 }

package/src/lib/util/function.ts

@@ -33,3 +33,7 @@ export function invokeOnce<T extends (this: any, ...a: any[]) => any>(
     throw new Error('Function called multiple times')
   } as T
 }
+
+export function includedIn<T>(this: readonly T[], value: T): boolean {
+  return this.includes(value)
+}

package/src/oauth-hooks.ts

@@ -1,10 +1,12 @@
 import { Jwks } from '@atproto/jwk'
 import type { Account } from '@atproto/oauth-provider-api'
 import {
+  OAuthAccessToken,
   OAuthAuthorizationDetails,
   OAuthAuthorizationRequestParameters,
   OAuthClientMetadata,
   OAuthTokenResponse,
+  OAuthTokenType,
 } from '@atproto/oauth-types'
 import { SignInData } from './account/sign-in-data.js'
 import { SignUpInput } from './account/sign-up-input.js'
@@ -12,6 +14,7 @@ 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 { DpopProof } from './dpop/dpop-proof.js'
 import { AccessDeniedError } from './errors/access-denied-error.js'
 import { AuthorizationError } from './errors/authorization-error.js'
 import { InvalidRequestError } from './errors/invalid-request-error.js'
@@ -22,13 +25,16 @@ import {
   HcaptchaVerifyResult,
 } from './lib/hcaptcha.js'
 import { RequestMetadata } from './lib/http/request.js'
-import { Awaitable } from './lib/util/type.js'
+import { Awaitable, OmitKey } from './lib/util/type.js'
 import { DeviceId, SignUpData } from './oauth-store.js'
 import { RequestId } from './request/request-id.js'
+import { AccessTokenPayload } from './signer/access-token-payload.js'
+import { TokenClaims } from './token/token-claims.js'
 
 // Make sure all types needed to implement the OAuthHooks are exported
 export {
   AccessDeniedError,
+  type AccessTokenPayload,
   type Account,
   AuthorizationError,
   type Awaitable,
@@ -37,20 +43,24 @@ export {
   type ClientId,
   type ClientInfo,
   type DeviceId,
+  type DpopProof,
   type HcaptchaClientTokens,
   type HcaptchaConfig,
   type HcaptchaVerifyResult,
   InvalidRequestError,
   type Jwks,
+  type OAuthAccessToken,
   type OAuthAuthorizationDetails,
   type OAuthAuthorizationRequestParameters,
   type OAuthClientMetadata,
   OAuthError,
   type OAuthTokenResponse,
+  type OAuthTokenType,
   type RequestMetadata,
   type SignInData,
   type SignUpData,
   type SignUpInput,
+  type TokenClaims,
 }
 
 export type OAuthHooks = {
@@ -151,6 +161,38 @@ export type OAuthHooks = {
     requestId: RequestId
   }) => Awaitable<void>
 
+  /**
+   * This hook is called whenever a token is about to be created. You can use
+   * it to modify the token claims or perform additional validation.
+   *
+   * This hook should never throw an error.
+   */
+  onCreateToken?: (data: {
+    client: Client
+    account: Account
+    parameters: OAuthAuthorizationRequestParameters
+    claims: TokenClaims
+  }) => Awaitable<void | OmitKey<AccessTokenPayload, 'iss'>>
+
+  /**
+   * This hook is called whenever a token was just decoded, and basic validation
+   * was performed (signature, expiration, not-before).
+   *
+   * It can be used to modify the payload (e.g., to add custom claims), or to
+   * perform additional validation.
+   *
+   * This hook is called when authenticating requests through the
+   * `authenticateRequest()` method in `OAuthVerifier` and `OAuthProvider`.
+   *
+   * Any error thrown here will be propagated.
+   */
+  onDecodeToken?: (data: {
+    tokenType: OAuthTokenType
+    token: OAuthAccessToken
+    payload: AccessTokenPayload
+    dpopProof: null | DpopProof
+  }) => Promise<AccessTokenPayload | void>
+
   /**
    * This hook is called when an authorized client exchanges an authorization
    * code for an access token.

package/src/oauth-provider.ts

@@ -85,6 +85,7 @@ import {
   DpopProof,
   OAuthVerifier,
   OAuthVerifierOptions,
+  VerifyTokenPayloadOptions,
 } from './oauth-verifier.js'
 import { ReplayStore, ifReplayStore } from './replay/replay-store.js'
 import { codeSchema } from './request/code.js'
@@ -95,6 +96,7 @@ import { AuthorizationRedirectParameters } from './result/authorization-redirect
 import { AuthorizationResultAuthorizePage } from './result/authorization-result-authorize-page.js'
 import { AuthorizationResultRedirect } from './result/authorization-result-redirect.js'
 import { ErrorHandler } from './router/error-handler.js'
+import { AccessTokenPayload } from './signer/access-token-payload.js'
 import { TokenData } from './token/token-data.js'
 import { TokenManager } from './token/token-manager.js'
 import {
@@ -102,14 +104,11 @@ import {
   asTokenStore,
   refreshTokenSchema,
 } from './token/token-store.js'
-import {
-  VerifyTokenClaimsOptions,
-  VerifyTokenClaimsResult,
-} from './token/verify-token-claims.js'
 import { isPARResponseError } from './types/par-response-error.js'
 
 export { AccessTokenMode, Keyset }
 export type {
+  AccessTokenPayload,
   AuthorizationRedirectParameters,
   AuthorizationResultAuthorizePage as AuthorizationResultAuthorize,
   AuthorizationResultRedirect,
@@ -123,6 +122,7 @@ export type {
   LexiconResolver,
   MultiLangString,
   OAuthAuthorizationServerMetadata,
+  VerifyTokenPayloadOptions,
 }
 
 type OAuthProviderConfig = {
@@ -1075,41 +1075,27 @@ export class OAuthProvider extends OAuthVerifier {
     }
   }
 
-  protected override async verifyToken(
+  protected override async decodeToken(
     tokenType: OAuthTokenType,
     token: OAuthAccessToken,
     dpopProof: null | DpopProof,
-    verifyOptions?: VerifyTokenClaimsOptions,
-  ): Promise<VerifyTokenClaimsResult> {
-    if (this.accessTokenMode === AccessTokenMode.stateless) {
-      return super.verifyToken(tokenType, token, dpopProof, verifyOptions)
-    }
-
-    if (this.accessTokenMode === AccessTokenMode.light) {
-      const { tokenClaims } = await super.verifyToken(
-        tokenType,
-        token,
-        dpopProof,
-        // Do not verify the scope and audience in case of "light" tokens.
-        // these will be checked through the tokenManager hereafter.
-        undefined,
-      )
+  ): Promise<AccessTokenPayload> {
+    const tokenPayload = await super.decodeToken(tokenType, token, dpopProof)
 
-      const tokenId = tokenClaims.jti
+    if (this.accessTokenMode !== AccessTokenMode.stateless) {
+      // @NOTE in non stateless mode, some claims can be omitted (most notably
+      // "scope"). We load the token claims here (allowing to ensure that the
+      // token is still valid, and to retrieve a (potentially updated) set of
+      // claims).
 
-      // In addition to verifying the signature (through the verifier above), we
-      // also verify the tokenId is still valid using a database to fetch
-      // missing data from "light" token.
-      return this.tokenManager.verifyToken(
-        token,
+      const tokenClaims = await this.tokenManager.loadTokenClaims(
         tokenType,
-        tokenId,
-        dpopProof,
-        verifyOptions,
+        tokenPayload,
       )
+
+      Object.assign(tokenPayload, tokenClaims)
     }
 
-    // Fool-proof
-    throw new Error('Invalid access token mode')
+    return tokenPayload
   }
 }

package/src/oauth-verifier.ts

@@ -9,53 +9,65 @@ import {
 import { DpopManager, DpopManagerOptions } from './dpop/dpop-manager.js'
 import { DpopNonce } from './dpop/dpop-nonce.js'
 import { DpopProof } from './dpop/dpop-proof.js'
+import { InvalidDpopKeyBindingError } from './errors/invalid-dpop-key-binding-error.js'
 import { InvalidDpopProofError } from './errors/invalid-dpop-proof-error.js'
 import { InvalidTokenError } from './errors/invalid-token-error.js'
 import { UseDpopNonceError } from './errors/use-dpop-nonce-error.js'
 import { WWWAuthenticateError } from './errors/www-authenticate-error.js'
 import { parseAuthorizationHeader } from './lib/util/authorization-header.js'
-import { Override } from './lib/util/type.js'
+import { includedIn } from './lib/util/function.js'
+import { OAuthHooks } from './oauth-hooks.js'
 import { ReplayManager } from './replay/replay-manager.js'
 import { ReplayStoreMemory } from './replay/replay-store-memory.js'
 import { ReplayStoreRedis } from './replay/replay-store-redis.js'
 import { ReplayStore } from './replay/replay-store.js'
+import { AccessTokenPayload } from './signer/access-token-payload.js'
 import { Signer } from './signer/signer.js'
-import {
-  VerifyTokenClaimsOptions,
-  VerifyTokenClaimsResult,
-  verifyTokenClaims,
-} from './token/verify-token-claims.js'
-
-export type * from './token/verify-token-claims.js'
-
-export type OAuthVerifierOptions = Override<
-  DpopManagerOptions,
-  {
-    /**
-     * The "issuer" identifier of the OAuth provider, this is the base URL of the
-     * OAuth provider.
-     */
-    issuer: URL | string
-
-    /**
-     * The keyset used to sign access tokens.
-     */
-    keyset: Keyset | Iterable<Key | undefined | null | false>
-
-    /**
-     * A redis instance to use for replay protection. If not provided, replay
-     * protection will use memory storage.
-     */
-    redis?: Redis | RedisOptions | string
-
-    replayStore?: ReplayStore
-  }
->
+
+export type DecodeTokenHook = OAuthHooks['onDecodeToken']
+
+export type OAuthVerifierOptions = DpopManagerOptions & {
+  /**
+   * The "issuer" identifier of the OAuth provider, this is the base URL of the
+   * OAuth provider.
+   */
+  issuer: URL | string
+
+  /**
+   * The keyset used to sign access tokens.
+   */
+  keyset: Keyset | Iterable<Key | undefined | null | false>
+
+  /**
+   * A redis instance to use for replay protection. If not provided, replay
+   * protection will use memory storage.
+   */
+  redis?: Redis | RedisOptions | string
+
+  replayStore?: ReplayStore
+
+  onDecodeToken?: DecodeTokenHook
+}
+
+export type VerifyTokenPayloadOptions = {
+  /** One of these audience must be included in the token audience(s) */
+  audience?: [string, ...string[]]
+  /** One of these scope must be included in the token scope(s) */
+  scope?: [string, ...string[]]
+}
 
 export { DpopNonce, Key, Keyset }
-export type { DpopProof, RedisOptions, ReplayStore }
+export type {
+  AccessTokenPayload,
+  DpopProof,
+  OAuthTokenType,
+  RedisOptions,
+  ReplayStore,
+}
 
 export class OAuthVerifier {
+  private readonly onDecodeToken?: DecodeTokenHook
+
   public readonly issuer: OAuthIssuerIdentifier
   public readonly keyset: Keyset
 
@@ -70,6 +82,7 @@ export class OAuthVerifier {
     replayStore = redis != null
       ? new ReplayStoreRedis({ redis })
       : new ReplayStoreMemory(),
+    onDecodeToken,
 
     ...rest
   }: OAuthVerifierOptions) {
@@ -118,12 +131,11 @@ export class OAuthVerifier {
     return dpopProof
   }
 
-  protected async verifyToken(
+  protected async decodeToken(
     tokenType: OAuthTokenType,
     token: OAuthAccessToken,
     dpopProof: null | DpopProof,
-    verifyOptions?: VerifyTokenClaimsOptions,
-  ): Promise<VerifyTokenClaimsResult> {
+  ): Promise<AccessTokenPayload> {
     if (!isSignedJwt(token)) {
       throw new InvalidTokenError(tokenType, `Malformed token`)
     }
@@ -134,22 +146,56 @@ export class OAuthVerifier {
         throw InvalidTokenError.from(err, tokenType)
       })
 
-    return verifyTokenClaims(
-      token,
-      payload.jti,
+    if (payload.cnf?.jkt) {
+      // An access token with a cnf.jkt claim must be a DPoP token
+      if (tokenType !== 'DPoP') {
+        throw new InvalidTokenError(
+          'DPoP',
+          `Access token is bound to a DPoP proof, but token type is ${tokenType}`,
+        )
+      }
+
+      // DPoP token type must be used with a DPoP proof
+      if (!dpopProof) {
+        throw new InvalidDpopProofError(`DPoP proof required`)
+      }
+
+      // DPoP proof must be signed with the key that matches the "cnf" claim
+      if (payload.cnf.jkt !== dpopProof.jkt) {
+        throw new InvalidDpopKeyBindingError()
+      }
+    } else {
+      // An access token without a cnf.jkt claim must be a Bearer token
+      if (tokenType !== 'Bearer') {
+        throw new InvalidTokenError(
+          'Bearer',
+          `Bearer token type must be used without a DPoP proof`,
+        )
+      }
+
+      // @NOTE We ignore (but allow) DPoP proofs for Bearer tokens
+    }
+
+    const payloadOverride = await this.onDecodeToken?.call(null, {
       tokenType,
+      token,
       payload,
       dpopProof,
-      verifyOptions,
-    )
+    })
+
+    return payloadOverride ?? payload
   }
 
+  /**
+   * @throws {WWWAuthenticateError}
+   * @throws {InvalidTokenError}
+   */
   public async authenticateRequest(
     httpMethod: string,
     httpUrl: Readonly<URL>,
     httpHeaders: Record<string, undefined | string | string[]>,
-    verifyOptions?: VerifyTokenClaimsOptions,
-  ): Promise<VerifyTokenClaimsResult> {
+    verifyOptions?: VerifyTokenPayloadOptions,
+  ): Promise<AccessTokenPayload> {
     const [tokenType, token] = parseAuthorizationHeader(
       httpHeaders['authorization'],
     )
@@ -161,14 +207,11 @@ export class OAuthVerifier {
         token,
       )
 
-      const tokenResult = await this.verifyToken(
-        tokenType,
-        token,
-        dpopProof,
-        verifyOptions,
-      )
+      const tokenPayload = await this.decodeToken(tokenType, token, dpopProof)
 
-      return tokenResult
+      this.verifyTokenPayload(tokenType, tokenPayload, verifyOptions)
+
+      return tokenPayload
     } catch (err) {
       if (err instanceof UseDpopNonceError) throw err.toWwwAuthenticateError()
       if (err instanceof WWWAuthenticateError) throw err
@@ -176,4 +219,33 @@ export class OAuthVerifier {
       throw InvalidTokenError.from(err, tokenType)
     }
   }
+
+  protected verifyTokenPayload(
+    tokenType: OAuthTokenType,
+    tokenPayload: AccessTokenPayload,
+    options?: VerifyTokenPayloadOptions,
+  ): void {
+    if (options?.audience) {
+      const { aud } = tokenPayload
+      const hasMatch =
+        aud != null &&
+        (Array.isArray(aud)
+          ? options.audience.some(includedIn, aud)
+          : options.audience.includes(aud))
+      if (!hasMatch) {
+        throw new InvalidTokenError(tokenType, `Invalid audience`)
+      }
+    }
+
+    if (options?.scope) {
+      const scopes = tokenPayload.scope?.split(' ')
+      if (!scopes || !options.scope.some(includedIn, scopes)) {
+        throw new InvalidTokenError(tokenType, `Invalid scope`)
+      }
+    }
+
+    if (tokenPayload.exp != null && tokenPayload.exp * 1000 <= Date.now()) {
+      throw new InvalidTokenError(tokenType, `Token expired`)
+    }
+  }
 }

package/src/request/request-manager.ts

@@ -293,18 +293,22 @@ export class RequestManager {
     // Make sure that every nsid in the scope resolves to a valid permission set
     // lexicon
     if (parameters.scope) {
-      await this.lexiconManager
-        .getPermissionSetsFromScope(parameters.scope)
-        .catch((cause) => {
+      try {
+        await this.lexiconManager.getPermissionSetsFromScope(parameters.scope)
+      } catch (err) {
+        // Parse expected errors
+        if (err instanceof LexiconResolutionError) {
           throw new AuthorizationError(
             parameters,
-            cause instanceof LexiconResolutionError
-              ? cause.message
-              : 'Unable to retrieve included permission sets',
+            err.message,
             'invalid_scope',
-            cause,
+            err,
           )
-        })
+        }
+
+        // Unexpected error
+        throw err
+      }
     }
 
     return parameters

package/src/signer/{signed-token-payload.ts → access-token-payload.ts}

@@ -4,7 +4,7 @@ import { clientIdSchema } from '../client/client-id.js'
 import { subSchema } from '../oidc/sub.js'
 import { tokenIdSchema } from '../token/token-id.js'
 
-export const signedTokenPayloadSchema = jwtPayloadSchema
+export const accessTokenPayloadSchema = jwtPayloadSchema
   .partial()
   .extend({
     // Following are required
@@ -22,4 +22,4 @@ export const signedTokenPayloadSchema = jwtPayloadSchema
   })
   .passthrough()
 
-export type SignedTokenPayload = z.infer<typeof signedTokenPayloadSchema>
+export type AccessTokenPayload = z.infer<typeof accessTokenPayloadSchema>

package/src/signer/signer.ts

@@ -9,11 +9,11 @@ import {
 import { EPHEMERAL_SESSION_MAX_AGE } from '../constants.js'
 import { dateToEpoch } from '../lib/util/date.js'
 import { OmitKey, RequiredKey } from '../lib/util/type.js'
-import { ApiTokenPayload, apiTokenPayloadSchema } from './api-token-payload.js'
 import {
-  SignedTokenPayload,
-  signedTokenPayloadSchema,
-} from './signed-token-payload.js'
+  AccessTokenPayload,
+  accessTokenPayloadSchema,
+} from './access-token-payload.js'
+import { ApiTokenPayload, apiTokenPayloadSchema } from './api-token-payload.js'
 
 export type SignPayload = JwtPayload & { iss?: never }
 
@@ -49,7 +49,7 @@ export class Signer {
   }
 
   async createAccessToken(
-    payload: OmitKey<SignedTokenPayload, 'iss'>,
+    payload: OmitKey<AccessTokenPayload, 'iss'>,
   ): Promise<SignedJwt> {
     return this.sign(
       {
@@ -68,8 +68,8 @@ export class Signer {
     const result = await this.verify<C>(token, { ...options, typ: 'at+jwt' })
     return {
       protectedHeader: result.protectedHeader,
-      payload: signedTokenPayloadSchema.parse(result.payload) as RequiredKey<
-        SignedTokenPayload,
+      payload: accessTokenPayloadSchema.parse(result.payload) as RequiredKey<
+        AccessTokenPayload,
         C
       >,
     }

package/src/token/token-claims.ts

@@ -0,0 +1,21 @@
+import { OAuthScope } from '@atproto/oauth-types'
+import { ClientId } from '../client/client-id.js'
+import { TokenId } from './token-id.js'
+
+/**
+ * The access token claims that will be set by the {@link TokenManager} and that
+ * will be passed to the "onCreateToken" hook.
+ *
+ * @note "iss" is missing here because it cannot be altered and will always be
+ * set to the Authorization Server's identifier.
+ */
+export type TokenClaims = {
+  jti: TokenId
+  sub: string
+  iat: number
+  exp: number
+  aud: string | [string, ...string[]]
+  cnf?: { jkt: string }
+  scope?: OAuthScope
+  client_id: ClientId
+}