@atproto/oauth-provider 0.7.10 → 0.8.0

package/dist/token/verify-token-claims.js

@@ -5,34 +5,49 @@ const invalid_dpop_key_binding_error_js_1 = require("../errors/invalid-dpop-key-
 const invalid_dpop_proof_error_js_1 = require("../errors/invalid-dpop-proof-error.js");
 const cast_js_1 = require("../lib/util/cast.js");
 const oauth_errors_js_1 = require("../oauth-errors.js");
-function verifyTokenClaims(token, tokenId, tokenType, dpopJkt, claims, options) {
+const BEARER = 'Bearer';
+const DPOP = 'DPoP';
+function verifyTokenClaims(token, tokenId, tokenType, tokenClaims, dpopProof, options) {
     const dateReference = Date.now();
-    const claimsJkt = claims.cnf?.jkt ?? null;
-    const expectedTokenType = claimsJkt ? 'DPoP' : 'Bearer';
-    if (expectedTokenType !== tokenType) {
-        throw new oauth_errors_js_1.InvalidTokenError(expectedTokenType, `Invalid token type`);
-    }
-    if (tokenType === 'DPoP' && !dpopJkt) {
-        throw new invalid_dpop_proof_error_js_1.InvalidDpopProofError(`jkt is required for DPoP tokens`);
+    if (tokenClaims.cnf?.jkt) {
+        // An access token with a cnf.jkt claim must be a DPoP token
+        if (tokenType !== DPOP) {
+            throw new oauth_errors_js_1.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 invalid_dpop_proof_error_js_1.InvalidDpopProofError(`DPoP proof required`);
+        }
+        // DPoP proof must be signed with the key that matches the "cnf" claim
+        if (tokenClaims.cnf.jkt !== dpopProof.jkt) {
+            throw new invalid_dpop_key_binding_error_js_1.InvalidDpopKeyBindingError();
+        }
     }
-    if (claimsJkt !== dpopJkt) {
-        throw new invalid_dpop_key_binding_error_js_1.InvalidDpopKeyBindingError();
+    else {
+        // An access token without a cnf.jkt claim must be a Bearer token
+        if (tokenType !== BEARER) {
+            throw new oauth_errors_js_1.InvalidTokenError(BEARER, `Bearer token type must be used without a DPoP proof`);
+        }
+        // Unexpected DPoP proof received for a Bearer token
+        if (dpopProof) {
+            throw new oauth_errors_js_1.InvalidTokenError(BEARER, `DPoP proof not expected for Bearer token type`);
+        }
     }
     if (options?.audience) {
-        const aud = (0, cast_js_1.asArray)(claims.aud);
+        const aud = (0, cast_js_1.asArray)(tokenClaims.aud);
         if (!options.audience.some((v) => aud.includes(v))) {
             throw new oauth_errors_js_1.InvalidTokenError(tokenType, `Invalid audience`);
         }
     }
     if (options?.scope) {
-        const scopes = claims.scope?.split(' ');
+        const scopes = tokenClaims.scope?.split(' ');
         if (!scopes || !options.scope.some((v) => scopes.includes(v))) {
             throw new oauth_errors_js_1.InvalidTokenError(tokenType, `Invalid scope`);
         }
     }
-    if (claims.exp != null && claims.exp * 1000 <= dateReference) {
+    if (tokenClaims.exp != null && tokenClaims.exp * 1000 <= dateReference) {
         throw new oauth_errors_js_1.InvalidTokenError(tokenType, `Token expired`);
     }
-    return { token, tokenId, tokenType, claims };
+    return { token, tokenId, tokenType, tokenClaims, dpopProof };
 }
 //# sourceMappingURL=verify-token-claims.js.map

package/dist/token/verify-token-claims.js.map

@@ -1 +1 @@
-{"version":3,"file":"verify-token-claims.js","sourceRoot":"","sources":["../../src/token/verify-token-claims.ts"],"names":[],"mappings":";;AAsBA,8CAyCC;AA9DD,mGAAwF;AACxF,uFAA6E;AAC7E,iDAA6C;AAC7C,wDAAsD;AAkBtD,SAAgB,iBAAiB,CAC/B,KAAuB,EACvB,OAAgB,EAChB,SAAyB,EACzB,OAAsB,EACtB,MAA0B,EAC1B,OAAkC;IAElC,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAChC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAA;IAEzC,MAAM,iBAAiB,GAAmB,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAA;IACvE,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,IAAI,mCAAiB,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAA;IACtE,CAAC;IACD,IAAI,SAAS,KAAK,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrC,MAAM,IAAI,mDAAqB,CAAC,iCAAiC,CAAC,CAAA;IACpE,CAAC;IACD,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QAC1B,MAAM,IAAI,8DAA0B,EAAE,CAAA;IACxC,CAAC;IAED,IAAI,OAAO,EAAE,QAAQ,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,IAAA,iBAAO,EAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAC/B,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,mCAAiB,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAA;QAC5D,CAAC;IACH,CAAC;IAED,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;QACnB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;QACvC,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,mCAAiB,CAAC,SAAS,EAAE,eAAe,CAAC,CAAA;QACzD,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,GAAG,IAAI,IAAI,IAAI,MAAM,CAAC,GAAG,GAAG,IAAI,IAAI,aAAa,EAAE,CAAC;QAC7D,MAAM,IAAI,mCAAiB,CAAC,SAAS,EAAE,eAAe,CAAC,CAAA;IACzD,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAA;AAC9C,CAAC"}
+{"version":3,"file":"verify-token-claims.js","sourceRoot":"","sources":["../../src/token/verify-token-claims.ts"],"names":[],"mappings":";;AA2BA,8CAiEC;AA3FD,mGAAwF;AACxF,uFAA6E;AAC7E,iDAA6C;AAC7C,wDAAsD;AAKtD,MAAM,MAAM,GAAG,QAAiC,CAAA;AAChD,MAAM,IAAI,GAAG,MAA+B,CAAA;AAiB5C,SAAgB,iBAAiB,CAC/B,KAAuB,EACvB,OAAgB,EAChB,SAAyB,EACzB,WAA+B,EAC/B,SAA2B,EAC3B,OAAkC;IAElC,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAEhC,IAAI,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;QACzB,4DAA4D;QAC5D,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,MAAM,IAAI,mCAAiB,CACzB,IAAI,EACJ,4DAA4D,SAAS,EAAE,CACxE,CAAA;QACH,CAAC;QAED,iDAAiD;QACjD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,mDAAqB,CAAC,qBAAqB,CAAC,CAAA;QACxD,CAAC;QAED,sEAAsE;QACtE,IAAI,WAAW,CAAC,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,GAAG,EAAE,CAAC;YAC1C,MAAM,IAAI,8DAA0B,EAAE,CAAA;QACxC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,iEAAiE;QACjE,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;YACzB,MAAM,IAAI,mCAAiB,CACzB,MAAM,EACN,qDAAqD,CACtD,CAAA;QACH,CAAC;QAED,oDAAoD;QACpD,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,IAAI,mCAAiB,CACzB,MAAM,EACN,+CAA+C,CAChD,CAAA;QACH,CAAC;IACH,CAAC;IAED,IAAI,OAAO,EAAE,QAAQ,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,IAAA,iBAAO,EAAC,WAAW,CAAC,GAAG,CAAC,CAAA;QACpC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,mCAAiB,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAA;QAC5D,CAAC;IACH,CAAC;IAED,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;QACnB,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;QAC5C,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,mCAAiB,CAAC,SAAS,EAAE,eAAe,CAAC,CAAA;QACzD,CAAC;IACH,CAAC;IAED,IAAI,WAAW,CAAC,GAAG,IAAI,IAAI,IAAI,WAAW,CAAC,GAAG,GAAG,IAAI,IAAI,aAAa,EAAE,CAAC;QACvE,MAAM,IAAI,mCAAiB,CAAC,SAAS,EAAE,eAAe,CAAC,CAAA;IACzD,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,CAAA;AAC9D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/oauth-provider",
-  "version": "0.7.10",
+  "version": "0.8.0",
   "license": "MIT",
   "description": "Generic OAuth2 and OpenID Connect provider for Node.js. Currently only supports features needed for Atproto.",
   "keywords": [
@@ -42,18 +42,18 @@
     "ioredis": "^5.3.2",
     "jose": "^5.2.0",
     "zod": "^3.23.8",
-    "@atproto-labs/fetch-node": "0.1.9",
     "@atproto-labs/fetch": "0.2.3",
+    "@atproto-labs/fetch-node": "0.1.9",
     "@atproto-labs/pipe": "0.1.1",
     "@atproto-labs/simple-store": "0.2.0",
     "@atproto-labs/simple-store-memory": "0.1.3",
     "@atproto/common": "^0.4.11",
-    "@atproto/jwk": "0.1.5",
-    "@atproto/jwk-jose": "0.1.6",
-    "@atproto/oauth-types": "0.2.7",
-    "@atproto/oauth-provider-api": "0.1.2",
-    "@atproto/oauth-provider-frontend": "0.1.5",
-    "@atproto/oauth-provider-ui": "0.1.7",
+    "@atproto/jwk": "0.2.0",
+    "@atproto/jwk-jose": "0.1.7",
+    "@atproto/oauth-types": "0.2.8",
+    "@atproto/oauth-provider-api": "0.1.3",
+    "@atproto/oauth-provider-frontend": "0.1.6",
+    "@atproto/oauth-provider-ui": "0.1.8",
     "@atproto/syntax": "0.4.0"
   },
   "devDependencies": {

package/src/dpop/dpop-manager.ts

@@ -1,15 +1,18 @@
 import { createHash } from 'node:crypto'
 import { EmbeddedJWK, calculateJwkThumbprint, errors, jwtVerify } from 'jose'
 import { z } from 'zod'
+import { ValidationError } from '@atproto/jwk'
 import { DPOP_NONCE_MAX_AGE } from '../constants.js'
 import { InvalidDpopProofError } from '../errors/invalid-dpop-proof-error.js'
 import { UseDpopNonceError } from '../errors/use-dpop-nonce-error.js'
+import { ifURL } from '../lib/util/cast.js'
 import {
   DpopNonce,
   DpopSecret,
   dpopSecretSchema,
   rotationIntervalSchema,
 } from './dpop-nonce.js'
+import { DpopProof } from './dpop-proof.js'
 
 const { JOSEError } = errors
 
@@ -47,111 +50,163 @@ export class DpopManager {
    * @see {@link https://datatracker.ietf.org/doc/html/rfc9449#section-4.3}
    */
   async checkProof(
-    proof: unknown,
-    htm: string, // HTTP Method
-    htu: string | URL, // HTTP URL
-    accessToken?: string, // Access Token
-  ) {
-    if (Array.isArray(proof) && proof.length === 1) {
-      proof = proof[0]
+    httpMethod: string,
+    httpUrl: Readonly<URL>,
+    httpHeaders: Record<string, undefined | string | string[]>,
+    accessToken?: string,
+  ): Promise<null | DpopProof> {
+    // Fool proofing against use of empty string
+    if (!httpMethod) {
+      throw new TypeError('HTTP method is required')
     }
 
-    if (!proof || typeof proof !== 'string') {
-      throw new InvalidDpopProofError('DPoP proof required')
-    }
+    const proof = extractProof(httpHeaders)
+    if (!proof) return null
 
-    const { protectedHeader, payload } = await jwtVerify<{
-      iat: number
-      jti: string
-    }>(proof, EmbeddedJWK, {
+    const { protectedHeader, payload } = await jwtVerify(proof, EmbeddedJWK, {
       typ: 'dpop+jwt',
-      maxTokenAge: 10,
+      maxTokenAge: 10, // Will ensure presence & validity of "iat" claim
       clockTolerance: DPOP_NONCE_MAX_AGE / 1e3,
-      requiredClaims: ['iat', 'jti'],
     }).catch((err) => {
-      const message =
-        err instanceof JOSEError
-          ? `Invalid DPoP proof (${err.message})`
-          : 'Invalid DPoP proof'
-      throw new InvalidDpopProofError(message, err)
+      throw newInvalidDpopProofError('Failed to verify DPoP proof', err)
     })
 
-    if (!payload.jti || typeof payload.jti !== 'string') {
-      throw new InvalidDpopProofError('Invalid or missing jti property')
+    // @NOTE For legacy & backwards compatibility reason, we cannot use
+    // `jwtPayloadSchema` here as it will reject DPoP proofs containing a query
+    // or fragment component in the "htu" claim.
+
+    // const { ath, htm, htu, jti, nonce } = await jwtPayloadSchema
+    //   .parseAsync(payload)
+    //   .catch((err) => {
+    //     throw buildInvalidDpopProofError('Invalid DPoP proof', err)
+    //   })
+
+    // @TODO Uncomment previous lines (and remove redundant checks bellow) once
+    // we decide to drop legacy support.
+    const { ath, htm, htu, jti, nonce } = payload
+
+    if (nonce !== undefined && typeof nonce !== 'string') {
+      throw newInvalidDpopProofError('Invalid DPoP "nonce" type')
     }
 
-    // Note rfc9110#section-9.1 states that the method name is case-sensitive
-    if (!htm || htm !== payload['htm']) {
-      throw new InvalidDpopProofError('DPoP htm mismatch')
+    if (!jti || typeof jti !== 'string') {
+      throw newInvalidDpopProofError('DPoP "jti" missing')
     }
 
-    if (
-      payload['nonce'] !== undefined &&
-      typeof payload['nonce'] !== 'string'
-    ) {
-      throw new InvalidDpopProofError('DPoP nonce must be a string')
+    // Note rfc9110#section-9.1 states that the method name is case-sensitive
+    if (!htm || htm !== httpMethod) {
+      throw newInvalidDpopProofError('DPoP "htm" mismatch')
     }
 
-    if (!payload['nonce'] && this.dpopNonce) {
-      throw new UseDpopNonceError()
+    if (!htu || typeof htu !== 'string') {
+      throw newInvalidDpopProofError('Invalid DPoP "htu" type')
     }
 
-    if (payload['nonce'] && !this.dpopNonce?.check(payload['nonce'])) {
-      throw new UseDpopNonceError('DPoP nonce mismatch')
+    // > To reduce the likelihood of false negatives, servers SHOULD employ
+    // > syntax-based normalization (Section 6.2.2 of [RFC3986]) and
+    // > scheme-based normalization (Section 6.2.3 of [RFC3986]) before
+    // > comparing the htu claim.
+    //
+    // RFC9449 section 4.3. Checking DPoP Proofs - https://datatracker.ietf.org/doc/html/rfc9449#section-4.3
+    if (!htu || parseHtu(htu) !== normalizeHtuUrl(httpUrl)) {
+      throw newInvalidDpopProofError('DPoP "htu" mismatch')
     }
 
-    const htuNorm = normalizeHtu(htu)
-    if (!htuNorm) {
-      throw new TypeError('Invalid "htu" argument')
+    if (!nonce && this.dpopNonce) {
+      throw new UseDpopNonceError()
     }
 
-    if (htuNorm !== normalizeHtu(payload['htu'])) {
-      throw new InvalidDpopProofError('DPoP htu mismatch')
+    if (nonce && !this.dpopNonce?.check(nonce)) {
+      throw new UseDpopNonceError('DPoP "nonce" mismatch')
     }
 
     if (accessToken) {
-      const athBuffer = createHash('sha256').update(accessToken).digest()
-      if (payload['ath'] !== athBuffer.toString('base64url')) {
-        throw new InvalidDpopProofError('DPoP ath mismatch')
+      const accessTokenHash = createHash('sha256').update(accessToken).digest()
+      if (ath !== accessTokenHash.toString('base64url')) {
+        throw newInvalidDpopProofError('DPoP "ath" mismatch')
       }
-    } else if (payload['ath']) {
-      throw new InvalidDpopProofError('DPoP ath not allowed')
+    } else if (ath !== undefined) {
+      throw newInvalidDpopProofError('DPoP "ath" claim not allowed')
     }
 
-    try {
-      return {
-        protectedHeader,
-        payload,
-        jkt: await calculateJwkThumbprint(protectedHeader['jwk']!, 'sha256'), // EmbeddedJWK
-      }
-    } catch (err) {
-      const message =
-        err instanceof JOSEError ? err.message : 'Failed to calculate jkt'
-      throw new InvalidDpopProofError(message, err)
-    }
+    // @NOTE we can assert there is a jwk because the jwtVerify used the
+    // EmbeddedJWK key getter mechanism.
+    const jwk = protectedHeader.jwk!
+    const jkt = await calculateJwkThumbprint(jwk, 'sha256').catch((err) => {
+      throw newInvalidDpopProofError('Failed to calculate jkt', err)
+    })
+
+    return { jti, jkt, htm, htu }
+  }
+}
+
+function extractProof(
+  httpHeaders: Record<string, undefined | string | string[]>,
+): string | null {
+  const dpopHeader = httpHeaders['dpop']
+  switch (typeof dpopHeader) {
+    case 'string':
+      if (dpopHeader) return dpopHeader
+      throw newInvalidDpopProofError('DPoP header cannot be empty')
+    case 'object':
+      // @NOTE the "0" case should never happen a node.js HTTP server will only
+      // return an array if the header is set multiple times.
+      if (dpopHeader.length === 1 && dpopHeader[0]) return dpopHeader[0]!
+      throw newInvalidDpopProofError('DPoP header must contain a single proof')
+    default:
+      return null
   }
 }
 
 /**
- * @note
- * > The htu claim matches the HTTP URI value for the HTTP request in which the
- * > JWT was received, ignoring any query and fragment parts.
+ * Constructs the HTTP URI (htu) claim as defined in RFC9449.
+ *
+ * The htu claim is the normalized URL of the HTTP request, excluding the query
+ * string and fragment. This function ensures that the URL is normalized by
+ * removing the search and hash components, as well as by using an URL object to
+ * simplify the pathname (e.g. removing dot segments).
  *
- * > To reduce the likelihood of false negatives, servers SHOULD employ
- * > syntax-based normalization (Section 6.2.2 of [RFC3986]) and scheme-based
- * > normalization (Section 6.2.3 of [RFC3986]) before comparing the htu claim.
- * @see {@link https://datatracker.ietf.org/doc/html/rfc9449#section-4.3 | RFC9449 section 4.3. Checking DPoP Proofs}
+ * @returns The normalized URL as a string.
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc9449#section-4.3}
  */
-function normalizeHtu(htu: unknown): string | null {
-  // Optimization
-  if (!htu) return null
-
-  try {
-    const url = new URL(String(htu))
-    url.hash = ''
-    url.search = ''
-    return url.href
-  } catch {
-    return null
+function normalizeHtuUrl(url: Readonly<URL>): string {
+  // NodeJS's `URL` normalizes the pathname, so we can just use that.
+  return url.origin + url.pathname
+}
+
+function parseHtu(htu: string): string {
+  const url = ifURL(htu)
+  if (!url) {
+    throw newInvalidDpopProofError('DPoP "htu" is not a valid URL')
+  }
+
+  // @NOTE the checks bellow can be removed once once jwtPayloadSchema is used
+  // to validate the DPoP proof payload as it already performs these checks
+  // (though the htuSchema).
+
+  if (url.password || url.username) {
+    throw newInvalidDpopProofError('DPoP "htu" must not contain credentials')
   }
+
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw newInvalidDpopProofError('DPoP "htu" must be http or https')
+  }
+
+  // @NOTE For legacy & backwards compatibility reason, we allow a query and
+  // fragment in the DPoP proof's htu. This is not a standard behavior as the
+  // htu is not supposed to contain query or fragment.
+
+  // NodeJS's `URL` normalizes the pathname.
+  return normalizeHtuUrl(url)
+}
+
+function newInvalidDpopProofError(
+  title: string,
+  err?: unknown,
+): InvalidDpopProofError {
+  const msg =
+    err instanceof JOSEError || err instanceof ValidationError
+      ? `${title}: ${err.message}`
+      : title
+  return new InvalidDpopProofError(msg, err)
 }

package/src/dpop/dpop-proof.ts

@@ -0,0 +1,6 @@
+export type DpopProof = {
+  jti: string
+  jkt: string
+  htm: string
+  htu: string
+}

package/src/lib/util/authorization-header.ts

@@ -11,8 +11,8 @@ export const authorizationHeaderSchema = z.tuple([
   oauthAccessTokenSchema,
 ])
 
-export const parseAuthorizationHeader = (header?: string) => {
-  if (header == null) {
+export const parseAuthorizationHeader = (header: unknown) => {
+  if (typeof header !== 'string') {
     throw new WWWAuthenticateError(
       'invalid_request',
       'Authorization header required',

package/src/lib/util/cast.ts

@@ -2,3 +2,17 @@ export function asArray<T>(value: T | T[]): T[] {
   if (value == null) return []
   return Array.isArray(value) ? value : [value]
 }
+
+export function asURL(value: string | { toString: () => string }): URL {
+  return new URL(value)
+}
+
+export function ifURL(
+  value: string | { toString: () => string },
+): URL | undefined {
+  try {
+    return asURL(value)
+  } catch {
+    return undefined
+  }
+}

package/src/oauth-provider.ts

@@ -69,7 +69,11 @@ 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 { OAuthVerifier, OAuthVerifierOptions } from './oauth-verifier.js'
+import {
+  DpopProof,
+  OAuthVerifier,
+  OAuthVerifierOptions,
+} from './oauth-verifier.js'
 import { ReplayStore, ifReplayStore } from './replay/replay-store.js'
 import { codeSchema } from './request/code.js'
 import { RequestInfo } from './request/request-info.js'
@@ -458,7 +462,7 @@ export class OAuthProvider extends OAuthVerifier {
   public async pushedAuthorizationRequest(
     credentials: OAuthClientCredentials,
     authorizationRequest: OAuthAuthorizationRequestPar,
-    dpopJkt: null | string,
+    dpopProof: null | DpopProof,
   ): Promise<OAuthParResponse> {
     try {
       const [client, clientAuth] = await this.authenticateClient(credentials)
@@ -474,7 +478,7 @@ export class OAuthProvider extends OAuthVerifier {
           clientAuth,
           parameters,
           null,
-          dpopJkt,
+          dpopProof,
         )
 
       return {
@@ -717,7 +721,7 @@ export class OAuthProvider extends OAuthVerifier {
     clientCredentials: OAuthClientCredentials,
     clientMetadata: RequestMetadata,
     request: OAuthTokenRequest,
-    dpopJkt: null | string,
+    dpopProof: null | DpopProof,
   ): Promise<OAuthTokenResponse> {
     const [client, clientAuth] =
       await this.authenticateClient(clientCredentials)
@@ -740,7 +744,7 @@ export class OAuthProvider extends OAuthVerifier {
         clientAuth,
         clientMetadata,
         request,
-        dpopJkt,
+        dpopProof,
       )
     }
 
@@ -750,7 +754,7 @@ export class OAuthProvider extends OAuthVerifier {
         clientAuth,
         clientMetadata,
         request,
-        dpopJkt,
+        dpopProof,
       )
     }
 
@@ -764,7 +768,7 @@ export class OAuthProvider extends OAuthVerifier {
     clientAuth: ClientAuth,
     clientMetadata: RequestMetadata,
     input: OAuthAuthorizationCodeGrantTokenRequest,
-    dpopJkt: null | string,
+    dpopProof: null | DpopProof,
   ): Promise<OAuthTokenResponse> {
     const code = codeSchema.parse(input.code)
     try {
@@ -807,7 +811,7 @@ export class OAuthProvider extends OAuthVerifier {
         deviceId,
         parameters,
         input,
-        dpopJkt,
+        dpopProof,
       )
     } catch (err) {
       // If a token is replayed, requestManager.findCode will throw. In that
@@ -835,14 +839,14 @@ export class OAuthProvider extends OAuthVerifier {
     clientAuth: ClientAuth,
     clientMetadata: RequestMetadata,
     input: OAuthRefreshTokenGrantTokenRequest,
-    dpopJkt: null | string,
+    dpopProof: null | DpopProof,
   ): Promise<OAuthTokenResponse> {
     return this.tokenManager.refresh(
       client,
       clientAuth,
       clientMetadata,
       input,
-      dpopJkt,
+      dpopProof,
     )
   }
 
@@ -874,24 +878,24 @@ export class OAuthProvider extends OAuthVerifier {
   protected override async verifyToken(
     tokenType: OAuthTokenType,
     token: OAuthAccessToken,
-    dpopJkt: string | null,
+    dpopProof: null | DpopProof,
     verifyOptions?: VerifyTokenClaimsOptions,
   ): Promise<VerifyTokenClaimsResult> {
     if (this.accessTokenMode === AccessTokenMode.stateless) {
-      return super.verifyToken(tokenType, token, dpopJkt, verifyOptions)
+      return super.verifyToken(tokenType, token, dpopProof, verifyOptions)
     }
 
     if (this.accessTokenMode === AccessTokenMode.light) {
-      const { claims } = await super.verifyToken(
+      const { tokenClaims } = await super.verifyToken(
         tokenType,
         token,
-        dpopJkt,
+        dpopProof,
         // Do not verify the scope and audience in case of "light" tokens.
         // these will be checked through the tokenManager hereafter.
         undefined,
       )
 
-      const tokenId = claims.jti
+      const tokenId = tokenClaims.jti
 
       // In addition to verifying the signature (through the verifier above), we
       // also verify the tokenId is still valid using a database to fetch
@@ -900,7 +904,7 @@ export class OAuthProvider extends OAuthVerifier {
         token,
         tokenType,
         tokenId,
-        dpopJkt,
+        dpopProof,
         verifyOptions,
       )
     }

package/src/oauth-verifier.ts

@@ -8,6 +8,7 @@ import {
 } from '@atproto/oauth-types'
 import { DpopManager, DpopManagerOptions } from './dpop/dpop-manager.js'
 import { DpopNonce } from './dpop/dpop-nonce.js'
+import { DpopProof } from './dpop/dpop-proof.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'
@@ -50,7 +51,7 @@ export type OAuthVerifierOptions = Override<
 >
 
 export { DpopNonce, Key, Keyset }
-export type { RedisOptions, ReplayStore, VerifyTokenClaimsOptions }
+export type { DpopProof, RedisOptions, ReplayStore, VerifyTokenClaimsOptions }
 
 export class OAuthVerifier {
   public readonly issuer: OAuthIssuerIdentifier
@@ -95,30 +96,30 @@ export class OAuthVerifier {
   }
 
   public async checkDpopProof(
-    proof: unknown,
-    htm: string,
-    htu: string | URL,
+    httpMethod: string,
+    httpUrl: Readonly<URL>,
+    httpHeaders: Record<string, undefined | string | string[]>,
     accessToken?: string,
-  ): Promise<string | null> {
-    if (proof === undefined) return null
-
-    const { payload, jkt } = await this.dpopManager.checkProof(
-      proof,
-      htm,
-      htu,
+  ): Promise<null | DpopProof> {
+    const dpopProof = await this.dpopManager.checkProof(
+      httpMethod,
+      httpUrl,
+      httpHeaders,
       accessToken,
     )
 
-    const unique = await this.replayManager.uniqueDpop(payload.jti)
-    if (!unique) throw new InvalidDpopProofError('DPoP proof jti is not unique')
+    if (dpopProof) {
+      const unique = await this.replayManager.uniqueDpop(dpopProof.jti)
+      if (!unique) throw new InvalidDpopProofError('DPoP proof replayed')
+    }
 
-    return jkt
+    return dpopProof
   }
 
   protected async verifyToken(
     tokenType: OAuthTokenType,
     token: OAuthAccessToken,
-    dpopJkt: string | null,
+    dpopProof: null | DpopProof,
     verifyOptions?: VerifyTokenClaimsOptions,
   ): Promise<VerifyTokenClaimsResult> {
     if (!isSignedJwt(token)) {
@@ -135,35 +136,37 @@ export class OAuthVerifier {
       token,
       payload.jti,
       tokenType,
-      dpopJkt,
       payload,
+      dpopProof,
       verifyOptions,
     )
   }
 
   public async authenticateRequest(
-    method: string,
-    url: URL,
-    headers: {
-      authorization?: string
-      dpop?: unknown
-    },
+    httpMethod: string,
+    httpUrl: Readonly<URL>,
+    httpHeaders: Record<string, undefined | string | string[]>,
     verifyOptions?: VerifyTokenClaimsOptions,
-  ) {
-    const [tokenType, token] = parseAuthorizationHeader(headers.authorization)
+  ): Promise<VerifyTokenClaimsResult> {
+    const [tokenType, token] = parseAuthorizationHeader(
+      httpHeaders['authorization'],
+    )
     try {
-      const dpopJkt = await this.checkDpopProof(
-        headers.dpop,
-        method,
-        url,
+      const dpopProof = await this.checkDpopProof(
+        httpMethod,
+        httpUrl,
+        httpHeaders,
         token,
       )
 
-      if (tokenType === 'DPoP' && !dpopJkt) {
-        throw new InvalidDpopProofError(`DPoP proof required`)
-      }
+      const tokenResult = await this.verifyToken(
+        tokenType,
+        token,
+        dpopProof,
+        verifyOptions,
+      )
 
-      return await this.verifyToken(tokenType, token, dpopJkt, verifyOptions)
+      return tokenResult
     } catch (err) {
       if (err instanceof UseDpopNonceError) throw err.toWwwAuthenticateError()
       if (err instanceof WWWAuthenticateError) throw err