Interface DPoPOptions

Options that control Demonstration of Proof-of-Possession (DPoP) handling.

Remarks

DPoP (RFC 9449) is an application-level mechanism to sender-constrain OAuth 2.0 access/refresh tokens by proving possession of a private key. This SDK supports validating DPoP proofs on incoming requests when enabled.

Behavior matrix:

  • Default ({ enabled: true, required: false }):
    Accepts both Bearer and DPoP, validating the DPoP proof when present.

  • Bearer-only ({ enabled: false, required: false }):
    Rejects any non-Bearer scheme tokens (including those using the DPoP scheme), accepts DPoP-bound tokens over Bearer (ignoring cnf), and ignores any DPoP proof headers if present.

  • Misconfiguration ({ enabled: false, required: true }):
    This configuration is invalid. DPoP is disabled, and the SDK cannot be used with this setting.

  • DPoP-only ({ enabled: true, required: true }):
    Accepts only tokens using the DPoP scheme, validates the associated DPoP proof, and rejects any token using a different (non-DPoP) scheme.

Proof timing:

  • iatOffset bounds how far in the past a proof’s iat may be (replay window).
  • iatLeeway allows limited clock skew for proofs that appear slightly in the future.

Note: This SDK uses req.protocol and req.host to construct/validate the DPoP htu. If your app runs behind a reverse proxy (Nginx, Cloudflare, etc.), enable Express proxy trust to ensure correct values:

app.enable('trust proxy');

See

https://www.rfc-editor.org/rfc/rfc9449

Hierarchy

  • DPoPOptions

Properties

enabled?: boolean

Enables DPoP support.

When enabled: true:

  • Requests can use the DPoP authorization scheme (Authorization: DPoP … plus a DPoP proof header), and the middleware will validate proofs.

When enabled: false:

  • Only the Bearer scheme is supported.
  • Any token sent with the DPoP scheme is rejected.
  • DPoP-bound tokens sent with Bearer are accepted (the cnf claim is ignored).
  • Any DPoP proof header is ignored.

Default

true

Example

// Accept both Bearer and DPoP (default):
auth({ dpop: { enabled: true, required: false } })

Example

// Bearer-only (DPoP disabled):
auth({ dpop: { enabled: false } })
iatLeeway?: number

Allowed clock skew (in seconds) for future-dated iat values.

Some clients have slightly skewed clocks; a small positive leeway prevents valid proofs from being rejected when iat appears a bit in the future. This is applied only when enabled: true and a DPoP proof is present.

Default

30  // 30 seconds

Example

// Allow up to 60 seconds of client/server clock skew
auth({ dpop: { enabled: true, iatLeeway: 60 } })
iatOffset?: number

Maximum accepted age (in seconds) for a DPoP proof’s iat claim.

Proofs older than iatOffset (relative to current server time) are rejected. This is applied only when enabled: true and a DPoP proof is present.

Default

300  // 5 minutes

Example

// Reject proofs older than 2 minutes
auth({ dpop: { enabled: true, iatOffset: 120 } })
required?: boolean

Requires DPoP tokens exclusively when DPoP is enabled.

When enabled: true and required: true:

  • Only DPoP tokens are accepted, and non-DPoP tokens are rejected.

When enabled: false:

  • Setting this flag results in a misconfiguration (Bearer-only mode).

Default

false

Example

// DPoP-only:
auth({ dpop: { enabled: true, required: true } })