@atproto/pds 0.4.164 → 0.4.166

package/src/auth-verifier.ts

@@ -1,6 +1,5 @@
 import { KeyObject, createPublicKey, createSecretKey } from 'node:crypto'
 import { IncomingMessage, ServerResponse } from 'node:http'
-import { Request } from 'express'
 import * as jose from 'jose'
 import KeyEncoder from 'key-encoder'
 import { getVerificationMaterial } from '@atproto/common'
@@ -8,108 +7,56 @@ import { IdResolver, getDidKeyFromMultibase } from '@atproto/identity'
 import {
   OAuthError,
   OAuthVerifier,
+  VerifyTokenClaimsOptions,
   WWWAuthenticateError,
 } from '@atproto/oauth-provider'
+import { PermissionSet, PermissionSetTransition } from '@atproto/oauth-scopes'
 import {
   AuthRequiredError,
+  Awaitable,
   ForbiddenError,
   InvalidRequestError,
+  MethodAuthContext,
+  MethodAuthVerifier,
+  Params,
   XRPCError,
   parseReqNsid,
   verifyJwt as verifyServiceJwt,
 } from '@atproto/xrpc-server'
 import { AccountManager } from './account-manager/account-manager'
+import {
+  AccessOutput,
+  AdminTokenOutput,
+  ModServiceOutput,
+  OAuthOutput,
+  RefreshOutput,
+  UnauthenticatedOutput,
+  UserServiceAuthOutput,
+} from './auth-output'
+import { ACCESS_STANDARD, AuthScope, isAuthScope } from './auth-scope'
 import { softDeleted } from './db'
 import { oauthLogger } from './logger'
+import { appendVary } from './util/http'
+import { WithRequired } from './util/types'
 
-type ReqCtx = { req: IncomingMessage; res?: ServerResponse }
-
-// @TODO sync-up with current method names, consider backwards compat.
-export enum AuthScope {
-  Access = 'com.atproto.access',
-  Refresh = 'com.atproto.refresh',
-  AppPass = 'com.atproto.appPass',
-  AppPassPrivileged = 'com.atproto.appPassPrivileged',
-  SignupQueued = 'com.atproto.signupQueued',
-  Takendown = 'com.atproto.takendown',
-}
-
-export type AccessOpts = {
-  additional: AuthScope[]
-  checkTakedown: boolean
-  checkDeactivated: boolean
-}
-
-export enum RoleStatus {
-  Valid,
-  Invalid,
-  Missing,
+export type VerifiedOptions = {
+  checkTakedown?: boolean
+  checkDeactivated?: boolean
 }
 
-export type NullOutput = {
-  credentials: null
+export type ScopedOptions<S extends AuthScope = AuthScope> = {
+  scopes?: readonly S[]
 }
 
-export type AdminTokenOutput = {
-  credentials: {
-    type: 'admin_token'
-  }
+export type ExtraScopedOptions<S extends AuthScope = AuthScope> = {
+  additional?: readonly S[]
 }
 
-export type ModServiceOutput = {
-  credentials: {
-    type: 'mod_service'
-    aud: string
-    iss: string
-  }
-}
-
-export type AccessOutput = {
-  credentials: {
-    type: 'access'
-    did: string
-    scope: AuthScope
-    isPrivileged: boolean
-  }
-}
-
-export type OAuthOutput = {
-  credentials: {
-    type: 'oauth'
-    did: string
-    scope: AuthScope
-    isPrivileged: boolean
-    oauthScopes: Set<string>
-  }
-}
-
-export type RefreshOutput = {
-  credentials: {
-    type: 'refresh'
-    did: string
-    scope: AuthScope
-    tokenId: string
-  }
-}
-
-export type UserServiceAuthOutput = {
-  credentials: {
-    type: 'user_service_auth'
-    aud: string
-    did: string
-  }
-}
-
-type ValidatedBearer = {
-  did: string
-  scope: AuthScope
-  token: string
-  payload: jose.JWTPayload
-  audience: string | undefined
-}
-
-type ValidatedRefreshBearer = ValidatedBearer & {
-  tokenId: string
+export type AuthorizedOptions<P extends Params = Params> = {
+  authorize: (
+    permissions: PermissionSet,
+    ctx: MethodAuthContext<P>,
+  ) => Awaitable<void>
 }
 
 export type AuthVerifierOpts = {
@@ -123,6 +70,21 @@ export type AuthVerifierOpts = {
   }
 }
 
+export type VerifyBearerJwtOptions<S extends AuthScope = AuthScope> =
+  WithRequired<
+    Omit<jose.JWTVerifyOptions, 'scopes'> & {
+      scopes: readonly S[]
+    },
+    'audience' | 'typ'
+  >
+
+export type VerifyBearerJwtResult<S extends AuthScope = AuthScope> = {
+  sub: string
+  aud: string
+  jti: string | undefined
+  scope: S
+}
+
 export class AuthVerifier {
   private _publicUrl: string
   private _jwtKey: KeyObject
@@ -143,360 +105,279 @@ export class AuthVerifier {
 
   // verifiers (arrow fns to preserve scope)
 
-  accessStandard =
-    (opts: Partial<AccessOpts> = {}) =>
-    async (ctx: ReqCtx): Promise<AccessOutput | OAuthOutput> => {
-      return this.validateAccessToken(
-        ctx,
-        [
-          AuthScope.Access,
-          AuthScope.AppPassPrivileged,
-          AuthScope.AppPass,
-          ...(opts.additional ?? []),
-        ],
-        opts,
-      )
-    }
-
-  accessFull =
-    (opts: Partial<AccessOpts> = {}) =>
-    (ctx: ReqCtx): Promise<AccessOutput | OAuthOutput> => {
-      return this.validateAccessToken(
-        ctx,
-        [AuthScope.Access, ...(opts.additional ?? [])],
-        opts,
-      )
-    }
-
-  accessPrivileged =
-    (opts: Partial<AccessOpts> = {}) =>
-    (ctx: ReqCtx): Promise<AccessOutput | OAuthOutput> => {
-      return this.validateAccessToken(ctx, [
-        AuthScope.Access,
-        AuthScope.AppPassPrivileged,
-        ...(opts.additional ?? []),
-      ])
-    }
+  public unauthenticated: MethodAuthVerifier<UnauthenticatedOutput> = (ctx) => {
+    setAuthHeaders(ctx.res)
 
-  refresh = async (ctx: ReqCtx): Promise<RefreshOutput> => {
-    const { did, scope, tokenId } = await this.validateRefreshToken(ctx)
-
-    return {
-      credentials: {
-        type: 'refresh',
-        did,
-        scope,
-        tokenId,
-      },
+    // @NOTE this auth method is typically used as fallback when no other auth
+    // method is applicable. This means that the presence of an "authorization"
+    // header means that that header is invalid (as it did not match any of the
+    // other auth methods).
+    if (ctx.req.headers['authorization']) {
+      throw new AuthRequiredError('Invalid authorization header')
     }
-  }
-
-  refreshExpired = async (ctx: ReqCtx): Promise<RefreshOutput> => {
-    const { did, scope, tokenId } = await this.validateRefreshToken(ctx, {
-      clockTolerance: Infinity,
-    })
 
     return {
-      credentials: {
-        type: 'refresh',
-        did,
-        scope,
-        tokenId,
-      },
+      credentials: null,
     }
   }
 
-  adminToken = async (ctx: ReqCtx): Promise<AdminTokenOutput> => {
-    this.setAuthHeaders(ctx)
-    return this.validateAdminToken(ctx)
-  }
-
-  optionalAccessOrAdminToken =
-    (opts: Partial<AccessOpts> = {}) =>
-    async (
-      ctx: ReqCtx,
-    ): Promise<AccessOutput | OAuthOutput | AdminTokenOutput | NullOutput> => {
-      if (isAccessToken(ctx.req)) {
-        return await this.accessStandard(opts)(ctx)
-      } else if (isBasicToken(ctx.req)) {
-        return await this.adminToken(ctx)
-      } else {
-        return this.null(ctx)
-      }
-    }
-
-  userServiceAuth = async (ctx: ReqCtx): Promise<UserServiceAuthOutput> => {
-    const payload = await this.verifyServiceJwt(ctx, {
-      aud: null,
-      iss: null,
-    })
-    if (
-      payload.aud !== this.dids.pds &&
-      (!this.dids.entryway || payload.aud !== this.dids.entryway)
-    ) {
-      throw new AuthRequiredError(
-        'jwt audience does not match service did',
-        'BadJwtAudience',
-      )
+  public adminToken: MethodAuthVerifier<AdminTokenOutput> = async (ctx) => {
+    setAuthHeaders(ctx.res)
+    const parsed = parseBasicAuth(ctx.req)
+    if (!parsed) {
+      throw new AuthRequiredError()
     }
-    return {
-      credentials: {
-        type: 'user_service_auth',
-        aud: payload.aud,
-        did: payload.iss,
-      },
+    const { username, password } = parsed
+    if (username !== 'admin' || password !== this._adminPass) {
+      throw new AuthRequiredError()
     }
-  }
 
-  userServiceAuthOptional = async (
-    ctx: ReqCtx,
-  ): Promise<UserServiceAuthOutput | NullOutput> => {
-    if (isBearerToken(ctx.req)) {
-      return await this.userServiceAuth(ctx)
-    } else {
-      return this.null(ctx)
-    }
+    return { credentials: { type: 'admin_token' } }
   }
 
-  accessOrUserServiceAuth =
-    (opts: Partial<AccessOpts> = {}) =>
-    async (
-      ctx: ReqCtx,
-    ): Promise<UserServiceAuthOutput | AccessOutput | OAuthOutput> => {
-      const token = bearerTokenFromReq(ctx.req)
-      if (token) {
-        const payload = jose.decodeJwt(token)
-        if (payload['lxm']) {
-          return this.userServiceAuth(ctx)
-        }
-      }
-      return this.accessStandard(opts)(ctx)
-    }
-
-  modService = async (ctx: ReqCtx): Promise<ModServiceOutput> => {
+  public modService: MethodAuthVerifier<ModServiceOutput> = async (ctx) => {
+    setAuthHeaders(ctx.res)
     if (!this.dids.modService) {
       throw new AuthRequiredError('Untrusted issuer', 'UntrustedIss')
     }
-    const payload = await this.verifyServiceJwt(ctx, {
-      aud: null,
+    const payload = await this.verifyServiceJwt(ctx.req, {
       iss: [this.dids.modService, `${this.dids.modService}#atproto_labeler`],
     })
-    if (
-      payload.aud !== this.dids.pds &&
-      (!this.dids.entryway || payload.aud !== this.dids.entryway)
-    ) {
-      throw new AuthRequiredError(
-        'jwt audience does not match service did',
-        'BadJwtAudience',
-      )
-    }
     return {
       credentials: {
         type: 'mod_service',
-        aud: payload.aud,
-        iss: payload.iss,
+        did: payload.iss,
       },
     }
   }
 
-  moderator = async (
-    ctx: ReqCtx,
-  ): Promise<AdminTokenOutput | ModServiceOutput> => {
-    if (isBearerToken(ctx.req)) {
-      return this.modService(ctx)
-    } else {
-      return this.adminToken(ctx)
+  public moderator: MethodAuthVerifier<AdminTokenOutput | ModServiceOutput> =
+    async (ctx) => {
+      const type = extractAuthType(ctx.req)
+      if (type === AuthType.BEARER) {
+        return this.modService(ctx)
+      } else {
+        return this.adminToken(ctx)
+      }
     }
-  }
 
-  protected async validateAdminToken({
-    req,
-  }: ReqCtx): Promise<AdminTokenOutput> {
-    const parsed = parseBasicAuth(req.headers.authorization)
-    if (!parsed) {
-      throw new AuthRequiredError()
-    }
-    const { username, password } = parsed
-    if (username !== 'admin' || password !== this._adminPass) {
-      throw new AuthRequiredError()
+  protected access<S extends AuthScope>(
+    options: VerifiedOptions & Required<ScopedOptions<S>>,
+  ): MethodAuthVerifier<AccessOutput<S>> {
+    const { scopes, ...statusOptions } = options
+
+    const verifyJwtOptions: VerifyBearerJwtOptions<S> = {
+      audience: this.dids.pds,
+      typ: 'at+jwt',
+      scopes:
+        // @NOTE We can reject taken down credentials based on the scope if
+        // "checkTakedown" is set.
+        statusOptions.checkTakedown && scopes.includes(AuthScope.Takendown as S)
+          ? scopes.filter((s) => s !== AuthScope.Takendown)
+          : scopes,
     }
 
-    return { credentials: { type: 'admin_token' } }
+    return async (ctx) => {
+      setAuthHeaders(ctx.res)
+
+      const { sub: did, scope } = await this.verifyBearerJwt(
+        ctx.req,
+        verifyJwtOptions,
+      )
+
+      await this.verifyStatus(did, statusOptions)
+
+      return {
+        credentials: { type: 'access', did, scope },
+      }
+    }
   }
 
-  protected async validateRefreshToken(
-    ctx: ReqCtx,
-    verifyOptions?: Omit<jose.JWTVerifyOptions, 'audience' | 'typ'>,
-  ): Promise<ValidatedRefreshBearer> {
-    const result = await this.validateBearerToken(ctx, [AuthScope.Refresh], {
-      ...verifyOptions,
+  public refresh(options?: {
+    allowExpired?: boolean
+  }): MethodAuthVerifier<RefreshOutput> {
+    const verifyOptions: VerifyBearerJwtOptions<AuthScope.Refresh> = {
+      clockTolerance: options?.allowExpired ? Infinity : undefined,
       typ: 'refresh+jwt',
       // when using entryway, proxying refresh credentials
       audience: this.dids.entryway ? this.dids.entryway : this.dids.pds,
-    })
-    const tokenId = result.payload.jti
-    if (!tokenId) {
-      throw new AuthRequiredError(
-        'Unexpected missing refresh token id',
-        'MissingTokenId',
-      )
+      scopes: [AuthScope.Refresh],
     }
-    return { ...result, tokenId }
-  }
-
-  protected async validateBearerToken(
-    ctx: ReqCtx,
-    scopes: AuthScope[],
-    verifyOptions: jose.JWTVerifyOptions &
-      Required<Pick<jose.JWTVerifyOptions, 'audience' | 'typ'>>,
-  ): Promise<ValidatedBearer> {
-    this.setAuthHeaders(ctx)
 
-    const token = bearerTokenFromReq(ctx.req)
-    if (!token) {
-      throw new AuthRequiredError(undefined, 'AuthMissing')
-    }
+    return async (ctx) => {
+      setAuthHeaders(ctx.res)
 
-    const { payload, protectedHeader } = await this.jwtVerify(
-      token,
-      // @TODO: Once all access & refresh tokens have a "typ" claim (i.e. 90
-      // days after this code was deployed), replace the following line with
-      // "verifyOptions," (to re-enable the verification of the "typ" property
-      // from verifyJwt()). Once the change is made, the "if" block below that
-      // checks for "typ" can be removed.
-      {
-        ...verifyOptions,
-        typ: undefined,
-      },
-    )
+      const result = await this.verifyBearerJwt(ctx.req, verifyOptions)
 
-    // @TODO: remove the next check once all access & refresh tokens have "typ"
-    // Note: when removing the check, make sure that the "verifyOptions"
-    // contains the "typ" property, so that the token is verified correctly by
-    // this.verifyJwt()
-    if (protectedHeader.typ && verifyOptions.typ !== protectedHeader.typ) {
-      // Temporarily allow historical tokens without "typ" to pass through. See:
-      // createAccessToken() and createRefreshToken() in
-      // src/account-manager/helpers/auth.ts
-      throw new InvalidRequestError('Invalid token type', 'InvalidToken')
-    }
+      const tokenId = result.jti
+      if (!tokenId) {
+        throw new AuthRequiredError(
+          'Unexpected missing refresh token id',
+          'MissingTokenId',
+        )
+      }
 
-    const { sub, aud, scope } = payload
-    if (typeof sub !== 'string' || !sub.startsWith('did:')) {
-      throw new InvalidRequestError('Malformed token', 'InvalidToken')
-    }
-    if (
-      aud !== undefined &&
-      (typeof aud !== 'string' || !aud.startsWith('did:'))
-    ) {
-      throw new InvalidRequestError('Malformed token', 'InvalidToken')
-    }
-    if (payload['cnf'] !== undefined) {
-      // Proof-of-Possession (PoP) tokens are not allowed here
-      // https://www.rfc-editor.org/rfc/rfc7800.html
-      throw new InvalidRequestError('Malformed token', 'InvalidToken')
-    }
-    if (!isAuthScope(scope) || (scopes.length > 0 && !scopes.includes(scope))) {
-      throw new InvalidRequestError('Bad token scope', 'InvalidToken')
-    }
-    return {
-      did: sub,
-      scope,
-      audience: aud,
-      token,
-      payload,
+      return {
+        credentials: {
+          type: 'refresh',
+          did: result.sub,
+          scope: result.scope,
+          tokenId,
+        },
+      }
     }
   }
 
-  protected async validateAccessToken(
-    ctx: ReqCtx,
-    scopes: AuthScope[],
-    {
-      checkTakedown = false,
-      checkDeactivated = false,
-    }: { checkTakedown?: boolean; checkDeactivated?: boolean } = {},
-  ): Promise<AccessOutput | OAuthOutput> {
-    this.setAuthHeaders(ctx)
-
-    let accessOutput: AccessOutput | OAuthOutput
-
-    const [type] = parseAuthorizationHeader(ctx.req.headers.authorization)
-    switch (type) {
-      case AuthType.BEARER: {
-        accessOutput = await this.validateBearerAccessToken(ctx, scopes)
-        break
+  public authorization<P extends Params>({
+    scopes = ACCESS_STANDARD,
+    additional = [],
+    ...options
+  }: VerifiedOptions &
+    ScopedOptions &
+    ExtraScopedOptions &
+    AuthorizedOptions<P>): MethodAuthVerifier<AccessOutput | OAuthOutput, P> {
+    const access = this.access({
+      ...options,
+      scopes: [...scopes, ...additional],
+    })
+    const oauth = this.oauth(options)
+
+    return async (ctx) => {
+      const type = extractAuthType(ctx.req)
+
+      if (type === AuthType.BEARER) {
+        return access(ctx)
       }
-      case AuthType.DPOP: {
-        accessOutput = await this.validateDpopAccessToken(ctx, scopes)
-        break
+
+      if (type === AuthType.DPOP) {
+        return oauth(ctx)
       }
-      case null:
-        throw new AuthRequiredError(undefined, 'AuthMissing')
-      default:
+
+      // Auth headers are set through the access and oauth methods so we only
+      // need to set them here if we reach this point
+      setAuthHeaders(ctx.res)
+
+      if (type !== null) {
         throw new InvalidRequestError(
           'Unexpected authorization type',
           'InvalidToken',
         )
+      }
+
+      throw new AuthRequiredError(undefined, 'AuthMissing')
     }
+  }
 
-    if (checkTakedown || checkDeactivated) {
-      const found = await this.accountManager.getAccount(
-        accessOutput.credentials.did,
-        {
-          includeDeactivated: true,
-          includeTakenDown: true,
-        },
-      )
-      if (!found) {
-        // will be turned into ExpiredToken for the client if proxied by entryway
-        throw new ForbiddenError('Account not found', 'AccountNotFound')
-      }
-      if (checkTakedown && softDeleted(found)) {
-        throw new AuthRequiredError(
-          'Account has been taken down',
-          'AccountTakedown',
-        )
-      }
-      if (checkDeactivated && found.deactivatedAt) {
-        throw new AuthRequiredError(
-          'Account is deactivated',
-          'AccountDeactivated',
-        )
+  public authorizationOrAdminTokenOptional<P extends Params>(
+    opts: VerifiedOptions & ExtraScopedOptions & AuthorizedOptions<P>,
+  ): MethodAuthVerifier<
+    OAuthOutput | AccessOutput | AdminTokenOutput | UnauthenticatedOutput,
+    P
+  > {
+    const authorization = this.authorization(opts)
+    return async (ctx) => {
+      const type = extractAuthType(ctx.req)
+      if (type === AuthType.BEARER || type === AuthType.DPOP) {
+        return authorization(ctx)
+      } else if (type === AuthType.BASIC) {
+        return this.adminToken(ctx)
+      } else {
+        return this.unauthenticated(ctx)
       }
     }
+  }
+
+  public userServiceAuth: MethodAuthVerifier<UserServiceAuthOutput> = async (
+    ctx,
+  ) => {
+    setAuthHeaders(ctx.res)
+    const payload = await this.verifyServiceJwt(ctx.req)
+    return {
+      credentials: {
+        type: 'user_service_auth',
+        did: payload.iss,
+      },
+    }
+  }
 
-    return accessOutput
+  public userServiceAuthOptional: MethodAuthVerifier<
+    UserServiceAuthOutput | UnauthenticatedOutput
+  > = async (ctx) => {
+    const type = extractAuthType(ctx.req)
+    if (type === AuthType.BEARER) {
+      return await this.userServiceAuth(ctx)
+    } else {
+      return this.unauthenticated(ctx)
+    }
+  }
+
+  public authorizationOrUserServiceAuth<P extends Params>(
+    options: VerifiedOptions &
+      ScopedOptions &
+      ExtraScopedOptions &
+      AuthorizedOptions<P>,
+  ): MethodAuthVerifier<UserServiceAuthOutput | OAuthOutput | AccessOutput, P> {
+    const authorizationVerifier = this.authorization(options)
+    return async (ctx) => {
+      if (isDefinitelyServiceAuth(ctx.req)) {
+        return this.userServiceAuth(ctx)
+      } else {
+        return authorizationVerifier(ctx)
+      }
+    }
   }
 
-  protected async validateDpopAccessToken(
-    ctx: ReqCtx,
-    scopes: AuthScope[],
-  ): Promise<OAuthOutput> {
-    this.setAuthHeaders(ctx)
+  protected oauth<P extends Params>({
+    authorize,
+    ...verifyStatusOptions
+  }: VerifiedOptions & AuthorizedOptions<P>): MethodAuthVerifier<
+    OAuthOutput,
+    P
+  > {
+    const verifyTokenOptions: VerifyTokenClaimsOptions = {
+      audience: [this.dids.pds],
+      scope: ['atproto'],
+    }
 
-    const { req } = ctx
-    const res = 'res' in ctx ? ctx.res : null
+    return async (ctx) => {
+      setAuthHeaders(ctx.res)
 
-    // https://datatracker.ietf.org/doc/html/rfc9449#section-8.2
-    if (res) {
+      const { req, res } = ctx
+
+      // https://datatracker.ietf.org/doc/html/rfc9449#section-8.2
       const dpopNonce = this.oauthVerifier.nextDpopNonce()
       if (dpopNonce) {
         res.setHeader('DPoP-Nonce', dpopNonce)
         res.appendHeader('Access-Control-Expose-Headers', 'DPoP-Nonce')
       }
-    }
 
-    try {
-      const originalUrl =
-        ('originalUrl' in req && (req as Request).originalUrl) || req.url || '/'
+      const originalUrl = req.originalUrl || req.url || '/'
       const url = new URL(originalUrl, this._publicUrl)
-      const { tokenClaims, dpopProof } =
-        await this.oauthVerifier.authenticateRequest(
+
+      const { tokenClaims, dpopProof } = await this.oauthVerifier
+        .authenticateRequest(
           req.method || 'GET',
           url,
           req.headers,
-          { audience: [this.dids.pds] },
+          verifyTokenOptions,
         )
+        .catch((err) => {
+          // Make sure to include any WWW-Authenticate header in the response
+          // (particularly useful for DPoP's "use_dpop_nonce" error)
+          if (err instanceof WWWAuthenticateError) {
+            res.setHeader('WWW-Authenticate', err.wwwAuthenticateHeader)
+            res.appendHeader(
+              'Access-Control-Expose-Headers',
+              'WWW-Authenticate',
+            )
+          }
+
+          if (err instanceof OAuthError) {
+            throw new XRPCError(err.status, err.error_description, err.error)
+          }
+
+          throw err
+        })
 
       // @TODO drop this once oauth provider no longer accepts DPoP proof with
       // query or fragment in "htu" claim.
@@ -510,99 +391,142 @@ export class AuthVerifier {
         )
       }
 
-      const { sub } = tokenClaims
-      if (typeof sub !== 'string' || !sub.startsWith('did:')) {
+      const { sub: did } = tokenClaims
+      if (typeof did !== 'string' || !did.startsWith('did:')) {
         throw new InvalidRequestError('Malformed token', 'InvalidToken')
       }
 
-      const oauthScopes = new Set(tokenClaims.scope?.split(' '))
+      await this.verifyStatus(did, verifyStatusOptions)
 
-      if (!oauthScopes.has('transition:generic')) {
-        throw new AuthRequiredError(
-          'Missing required scope: transition:generic',
-          'InvalidToken',
-        )
-      }
-
-      const scopeEquivalent: AuthScope = oauthScopes.has('transition:chat.bsky')
-        ? AuthScope.AppPassPrivileged
-        : AuthScope.AppPass
-
-      if (!scopes.includes(scopeEquivalent)) {
-        // AppPassPrivileged is sufficient but was not provided "transition:chat.bsky"
-        if (scopes.includes(AuthScope.AppPassPrivileged)) {
-          throw new InvalidRequestError(
-            'Missing required scope: transition:chat.bsky',
-            'InvalidToken',
-          )
-        }
+      const permissions = new PermissionSetTransition(
+        tokenClaims.scope?.split(' '),
+      )
 
-        // AuthScope.Access and AuthScope.SignupQueued do not have an OAuth
-        // scope equivalent.
+      // Should never happen
+      if (!permissions.scopes.has('atproto')) {
         throw new InvalidRequestError(
-          'DPoP access token cannot be used for this request',
+          'OAuth token does not have "atproto" scope',
           'InvalidToken',
         )
       }
 
+      await authorize(permissions, ctx)
+
       return {
         credentials: {
           type: 'oauth',
-          did: tokenClaims.sub,
-          scope: scopeEquivalent,
-          oauthScopes,
-          isPrivileged: scopeEquivalent === AuthScope.AppPassPrivileged,
+          did,
+          permissions,
         },
       }
-    } catch (err) {
-      // Make sure to include any WWW-Authenticate header in the response
-      // (particularly useful for DPoP's "use_dpop_nonce" error)
-      if (res && err instanceof WWWAuthenticateError) {
-        res.setHeader('WWW-Authenticate', err.wwwAuthenticateHeader)
-        res.appendHeader('Access-Control-Expose-Headers', 'WWW-Authenticate')
-      }
+    }
+  }
 
-      if (err instanceof OAuthError) {
-        throw new XRPCError(err.status, err.error_description, err.error)
+  protected async verifyStatus(
+    did: string,
+    { checkTakedown = false, checkDeactivated = false }: VerifiedOptions,
+  ): Promise<void> {
+    if (checkTakedown || checkDeactivated) {
+      const found = await this.accountManager.getAccount(did, {
+        includeDeactivated: true,
+        includeTakenDown: true,
+      })
+      if (!found) {
+        // will be turned into ExpiredToken for the client if proxied by entryway
+        throw new ForbiddenError('Account not found', 'AccountNotFound')
+      }
+      if (checkTakedown && softDeleted(found)) {
+        throw new AuthRequiredError(
+          'Account has been taken down',
+          'AccountTakedown',
+        )
+      }
+      if (checkDeactivated && found.deactivatedAt) {
+        throw new AuthRequiredError(
+          'Account is deactivated',
+          'AccountDeactivated',
+        )
       }
-
-      throw err
     }
   }
 
-  protected async validateBearerAccessToken(
-    ctx: ReqCtx,
-    scopes: AuthScope[],
-  ): Promise<AccessOutput> {
-    const { did, scope } = await this.validateBearerToken(ctx, scopes, {
-      audience: this.dids.pds,
-      typ: 'at+jwt',
-    })
+  /**
+   * Wraps {@link jose.jwtVerify} into a function that also validates the token
+   * payload's type and wraps errors into {@link InvalidRequestError}.
+   */
+  protected async verifyBearerJwt<S extends AuthScope = AuthScope>(
+    req: IncomingMessage,
+    { scopes, ...options }: VerifyBearerJwtOptions<S>,
+  ): Promise<VerifyBearerJwtResult<S>> {
+    const token = bearerTokenFromReq(req)
+    if (!token) {
+      throw new AuthRequiredError(undefined, 'AuthMissing')
+    }
 
-    const isPrivileged =
-      scope === AuthScope.Access || scope === AuthScope.AppPassPrivileged
+    const { payload, protectedHeader } = await jose
+      .jwtVerify(token, this._jwtKey, { ...options, typ: undefined })
+      .catch((cause) => {
+        if (cause instanceof jose.errors.JWTExpired) {
+          throw new InvalidRequestError('Token has expired', 'ExpiredToken', {
+            cause,
+          })
+        } else {
+          throw new InvalidRequestError(
+            'Token could not be verified',
+            'InvalidToken',
+            { cause },
+          )
+        }
+      })
 
-    return {
-      credentials: {
-        type: 'access',
-        did,
-        scope,
-        isPrivileged,
-      },
+    // @NOTE: the "typ" is now set in production environments, so we should be
+    // able to safely check it through jose.jwtVerify(). However, tests depend
+    // on @atproto/pds-entryway which does not set "typ" in the access tokens.
+    // For that reason, we still allow it to be missing.
+    if (protectedHeader.typ && options.typ !== protectedHeader.typ) {
+      throw new InvalidRequestError('Invalid token type', 'InvalidToken')
     }
+
+    const { sub, aud, scope, lxm, cnf, jti } = payload
+
+    if (typeof lxm !== 'undefined') {
+      // Service auth tokens should never make it to here. But since service
+      // auth tokens do not have a "typ" header, the "typ" check above will not
+      // catch them. This check here is mainly to protect against the
+      // hypothetical case in which a PDS would issue service auth tokens using
+      // its private key.
+      throw new InvalidRequestError('Malformed token', 'InvalidToken')
+    }
+    if (typeof cnf !== 'undefined') {
+      // Proof-of-Possession (PoP) tokens are not allowed here
+      // https://www.rfc-editor.org/rfc/rfc7800.html
+      throw new InvalidRequestError('Malformed token', 'InvalidToken')
+    }
+    if (typeof sub !== 'string' || !sub.startsWith('did:')) {
+      throw new InvalidRequestError('Malformed token', 'InvalidToken')
+    }
+    if (typeof aud !== 'string' || !aud.startsWith('did:')) {
+      throw new InvalidRequestError('Malformed token', 'InvalidToken')
+    }
+    if (typeof jti !== 'string' && typeof jti !== 'undefined') {
+      throw new InvalidRequestError('Malformed token', 'InvalidToken')
+    }
+    if (!isAuthScope(scope) || !scopes.includes(scope as any)) {
+      throw new InvalidRequestError('Bad token scope', 'InvalidToken')
+    }
+
+    return { sub, aud, jti, scope: scope as S }
   }
 
   protected async verifyServiceJwt(
-    ctx: ReqCtx,
-    opts: { aud: string | null; iss: string[] | null },
+    req: IncomingMessage,
+    opts?: { iss?: string[] },
   ) {
-    this.setAuthHeaders(ctx)
-
     const getSigningKey = async (
       iss: string,
       forceRefresh: boolean,
     ): Promise<string> => {
-      if (opts.iss !== null && !opts.iss.includes(iss)) {
+      if (opts?.iss && !opts.iss.includes(iss)) {
         throw new AuthRequiredError('Untrusted issuer', 'UntrustedIss')
       }
       const [did, serviceId] = iss.split('#')
@@ -623,78 +547,51 @@ export class AuthVerifier {
       return didKey
     }
 
-    const jwtStr = bearerTokenFromReq(ctx.req)
+    const jwtStr = bearerTokenFromReq(req)
     if (!jwtStr) {
       throw new AuthRequiredError('missing jwt', 'MissingJwt')
     }
-    const nsid = parseReqNsid(ctx.req)
-    const payload = await verifyServiceJwt(
-      jwtStr,
-      opts.aud,
-      nsid,
-      getSigningKey,
-    )
-    return { iss: payload.iss, aud: payload.aud }
-  }
-
-  protected null(ctx: ReqCtx): NullOutput {
-    this.setAuthHeaders(ctx)
-    return {
-      credentials: null,
-    }
-  }
-
-  isUserOrAdmin(
-    auth: AccessOutput | OAuthOutput | AdminTokenOutput | NullOutput,
-    did: string,
-  ): boolean {
-    if (!auth.credentials) {
-      return false
-    } else if (auth.credentials.type === 'admin_token') {
-      return true
-    } else {
-      return auth.credentials.did === did
-    }
-  }
-
-  protected async jwtVerify(
-    token: string,
-    verifyOptions?: jose.JWTVerifyOptions,
-  ) {
-    try {
-      return await jose.jwtVerify(token, this._jwtKey, verifyOptions)
-    } catch (err) {
-      if (err?.['code'] === 'ERR_JWT_EXPIRED') {
-        throw new InvalidRequestError('Token has expired', 'ExpiredToken')
-      }
-      throw new InvalidRequestError(
-        'Token could not be verified',
-        'InvalidToken',
+    const nsid = parseReqNsid(req)
+    const payload = await verifyServiceJwt(jwtStr, null, nsid, getSigningKey)
+    if (
+      payload.aud !== this.dids.pds &&
+      (!this.dids.entryway || payload.aud !== this.dids.entryway)
+    ) {
+      throw new AuthRequiredError(
+        'jwt audience does not match service did',
+        'BadJwtAudience',
       )
     }
-  }
-
-  protected setAuthHeaders(ctx: ReqCtx) {
-    const res = 'res' in ctx ? ctx.res : null
-    if (res) {
-      res.setHeader('Cache-Control', 'private')
-      vary(res, 'Authorization')
-    }
+    return payload
   }
 }
 
 // HELPERS
 // ---------
 
+export function isUserOrAdmin(
+  auth: AccessOutput | OAuthOutput | AdminTokenOutput | UnauthenticatedOutput,
+  did: string,
+): boolean {
+  if (!auth.credentials) {
+    return false
+  } else if (auth.credentials.type === 'admin_token') {
+    return true
+  } else {
+    return auth.credentials.did === did
+  }
+}
+
 enum AuthType {
   BASIC = 'Basic',
   BEARER = 'Bearer',
   DPOP = 'DPoP',
 }
 
-export const parseAuthorizationHeader = (
-  authorization?: string,
+const parseAuthorizationHeader = (
+  req: IncomingMessage,
 ): [type: null] | [type: AuthType, token: string] => {
+  const authorization = req.headers['authorization']
   if (!authorization) return [null]
 
   const result = authorization.split(' ')
@@ -717,31 +614,33 @@ export const parseAuthorizationHeader = (
   )
 }
 
-const isAccessToken = (req: IncomingMessage): boolean => {
-  const [type] = parseAuthorizationHeader(req.headers.authorization)
-  return type === AuthType.BEARER || type === AuthType.DPOP
-}
-
-const isBearerToken = (req: IncomingMessage): boolean => {
-  const [type] = parseAuthorizationHeader(req.headers.authorization)
-  return type === AuthType.BEARER
+/**
+ * @note Not all service auth tokens are guaranteed to have "lxm" claim, so this
+ * function should not be used to verify service auth tokens. It is only used to
+ * check if a token is definitely a service auth token.
+ */
+const isDefinitelyServiceAuth = (req: IncomingMessage): boolean => {
+  const token = bearerTokenFromReq(req)
+  if (!token) return false
+  const payload = jose.decodeJwt(token)
+  return payload['lxm'] != null
 }
 
-const isBasicToken = (req: IncomingMessage): boolean => {
-  const [type] = parseAuthorizationHeader(req.headers.authorization)
-  return type === AuthType.BASIC
+const extractAuthType = (req: IncomingMessage): AuthType | null => {
+  const [type] = parseAuthorizationHeader(req)
+  return type
 }
 
 const bearerTokenFromReq = (req: IncomingMessage) => {
-  const [type, token] = parseAuthorizationHeader(req.headers.authorization)
+  const [type, token] = parseAuthorizationHeader(req)
   return type === AuthType.BEARER ? token : null
 }
 
-export const parseBasicAuth = (
-  authorizationHeader?: string,
+const parseBasicAuth = (
+  req: IncomingMessage,
 ): { username: string; password: string } | null => {
   try {
-    const [type, b64] = parseAuthorizationHeader(authorizationHeader)
+    const [type, b64] = parseAuthorizationHeader(req)
     if (type !== AuthType.BASIC) return null
     const decoded = Buffer.from(b64, 'base64').toString('utf8')
     // We must not use split(':') because the password can contain colons
@@ -755,32 +654,17 @@ export const parseBasicAuth = (
   }
 }
 
-const authScopes = new Set(Object.values(AuthScope))
-const isAuthScope = (val: unknown): val is AuthScope => {
-  return authScopes.has(val as any)
-}
-
 export const createSecretKeyObject = (secret: string): KeyObject => {
   return createSecretKey(Buffer.from(secret))
 }
 
+const keyEncoder = new KeyEncoder('secp256k1')
 export const createPublicKeyObject = (publicKeyHex: string): KeyObject => {
   const key = keyEncoder.encodePublic(publicKeyHex, 'raw', 'pem')
   return createPublicKey({ format: 'pem', key })
 }
 
-const keyEncoder = new KeyEncoder('secp256k1')
-
-function vary(res: ServerResponse, value: string) {
-  const current = res.getHeader('Vary')
-  if (current == null || typeof current === 'number') {
-    res.setHeader('Vary', value)
-  } else {
-    const alreadyIncluded = Array.isArray(current)
-      ? current.some((value) => value.includes(value))
-      : current.includes(value)
-    if (!alreadyIncluded) {
-      res.appendHeader('Vary', value)
-    }
-  }
+function setAuthHeaders(res: ServerResponse) {
+  res.setHeader('Cache-Control', 'private')
+  appendVary(res, 'Authorization')
 }