@qauth-labs/resource-guard 0.2.0-rc.1 → 0.2.0

package/README.md

@@ -19,7 +19,8 @@ Drop it into an MCP server and you get spec-correct OAuth in minutes:
   is filtered out of both advertisement surfaces — it concerns refresh-token
   issuance at the AS, not access to this resource
 - Bearer-token validation in two modes — local **JWT** verification against the
-  QAuth JWKS, or **RFC 7662** introspection
+  QAuth JWKS, or **RFC 7662** introspection. Sender-constrained (DPoP-bound or
+  certificate-bound) tokens are refused; see [Security model](#security-model)
 - **No token passthrough**: tokens not audience-bound to this resource
   (**RFC 8707**) are rejected, and the inbound token is never forwarded upstream
 - **Step-up** `403 insufficient_scope` scope challenges for incremental consent
@@ -212,6 +213,22 @@ try {
   never returns the raw token to a call site or forwards it to upstream APIs.
 - **Algorithm pinning.** JWT mode accepts `EdDSA` only by default, closing
   algorithm-confusion attacks.
+- **Sender-constrained tokens are refused.** A token bound to a key, DPoP-bound
+  (`cnf.jkt`, RFC 9449) or certificate-bound (`cnf["x5t#S256"]`, RFC 8705), is
+  refused with `401 invalid_token` in both modes, because this version verifies
+  no proof of possession. JWT mode refuses any token that carries `cnf`;
+  introspection mode refuses a response that carries `cnf` or whose
+  `token_type` is present and is not `Bearer` (compared ignoring case), so a
+  bound type another authorization server names differently is refused too. Accepting such a token as a plain bearer would let anyone who copied
+  it use it (RFC 9449 §7.2). The `DPoP` authorization scheme is not accepted
+  either: it gets the same bare `Bearer` challenge as a request without a token
+  (RFC 6750 §3.1), and the thrown `MissingTokenError` names the scheme. A
+  client that calls a resource server on this SDK must use unbound tokens: it
+  sends no `DPoP` proof to the token endpoint. With QAuth, three kinds of token
+  are always bound, so they cannot be used here until this SDK verifies DPoP
+  proofs: the tokens of a client marked `dpop_bound_access_tokens`, a token
+  exchanged from a DPoP-bound subject token, and an access token issued for a
+  `cnf`-bound ID-JAG. DPoP proof support is planned.
 - **Exact scope matching.** Scopes are compared exactly and case-sensitively
   (RFC 6749 §3.3) — no prefix or wildcard semantics. QAuth's scope vocabulary
   declares no scope hierarchy (no scope implies another), so the MCP 2026-07-28

package/dist/lib/core.d.ts

@@ -58,8 +58,11 @@ export declare class ResourceGuard {
      * @param scopes additional per-operation scopes to require on top of the
      *   guard's default `requiredScopes` (the step-up surface).
      * @returns the validated, audience-bound token claims.
-     * @throws {MissingTokenError} when no bearer is present (→ 401, bare challenge).
-     * @throws {InvalidTokenError} when validation fails (→ 401 `invalid_token`).
+     * @throws {MissingTokenError} when no bearer is present (→ 401, bare
+     *   challenge), the `DPoP` scheme included: this version accepts `Bearer`
+     *   only, and the error's message says so.
+     * @throws {InvalidTokenError} when validation fails (→ 401 `invalid_token`),
+     *   a sender-constrained (`cnf`-carrying) token included.
      * @throws {InsufficientScopeError} when scopes are insufficient
      *   (→ 403 `insufficient_scope` step-up challenge).
      */

package/dist/lib/core.js

@@ -25,6 +25,17 @@ function stripTrailingSlash(value) {
 const BEARER_SCHEME = /^Bearer +/i;
 /** Line terminators, which a credential may not contain (RFC 6750 §2.1 b64token). */
 const LINE_TERMINATOR = /[\n\r\u2028\u2029]/;
+/**
+ * The RFC 9449 §7.1 `DPoP` scheme, matched case-insensitively (RFC 9110
+ * §11.1), which this version does not accept.
+ */
+const DPOP_SCHEME = /^DPoP +/i;
+/**
+ * Why a request under the `DPoP` scheme is refused. This version verifies no
+ * DPoP proof, so it accepts only the `Bearer` scheme, and a sender-constrained
+ * token is refused under that scheme too.
+ */
+const DPOP_SCHEME_UNSUPPORTED = 'The DPoP authorization scheme is not supported; this resource accepts unbound Bearer tokens only';
 /**
  * Extract a bearer token from an `Authorization` header value (RFC 6750 §2.1).
  * The scheme match is case-insensitive; the credential is returned verbatim.
@@ -177,8 +188,11 @@ export class ResourceGuard {
      * @param scopes additional per-operation scopes to require on top of the
      *   guard's default `requiredScopes` (the step-up surface).
      * @returns the validated, audience-bound token claims.
-     * @throws {MissingTokenError} when no bearer is present (→ 401, bare challenge).
-     * @throws {InvalidTokenError} when validation fails (→ 401 `invalid_token`).
+     * @throws {MissingTokenError} when no bearer is present (→ 401, bare
+     *   challenge), the `DPoP` scheme included: this version accepts `Bearer`
+     *   only, and the error's message says so.
+     * @throws {InvalidTokenError} when validation fails (→ 401 `invalid_token`),
+     *   a sender-constrained (`cnf`-carrying) token included.
      * @throws {InsufficientScopeError} when scopes are insufficient
      *   (→ 403 `insufficient_scope` step-up challenge).
      */
@@ -189,7 +203,17 @@ export class ResourceGuard {
             // per-call step-up scopes) on the 401 challenge — #284. Same set the 403
             // step-up would advertise, so an unauthenticated client and a
             // under-scoped one are told the same thing.
-            throw new MissingTokenError(dedupe([...this.requiredScopes, ...scopes]));
+            const required = dedupe([...this.requiredScopes, ...scopes]);
+            // A `DPoP` credential gets the same bare `Bearer` challenge as no
+            // credential at all: RFC 6750 §3.1 gives no error code to a request
+            // that "attempted using an unsupported authentication method", and a
+            // `DPoP` challenge would advertise support this version lacks. The
+            // challenge naming only `Bearer` tells the client which scheme is
+            // accepted; the message tells the host's logs why.
+            if (authorization && DPOP_SCHEME.test(authorization.trim())) {
+                throw new MissingTokenError(required, DPOP_SCHEME_UNSUPPORTED);
+            }
+            throw new MissingTokenError(required);
         }
         const validated = await this.validator.validate(token);
         this.assertScopes(validated, scopes);

package/dist/lib/introspection-validator.d.ts

@@ -7,7 +7,8 @@
  * and `client_secret_post`. We use Basic auth.
  *
  * QAuth contract (auth-server introspect route): returns
- * `{ active, sub, client_id, exp, iat, iss, aud, scope, token_type }` and
+ * `{ active, sub, client_id, exp, iat, iss, aud, scope, token_type }`, plus
+ * `cnf` with `token_type: DPoP` for a DPoP-bound token, and
  * `{ active: false }` for invalid / cross-audience tokens. The AS itself
  * already enforces audience-authoritative introspection; `resource-guard`
  * additionally re-checks `aud` locally so the no-passthrough guarantee does
@@ -39,7 +40,10 @@ export declare class IntrospectionValidator {
      *
      * @throws {InvalidTokenError} when the AS authoritatively says the *token* is
      * unusable — inactive (revoked/expired/unknown) or bound to a different
-     * audience. Maps to a 401 `invalid_token` Bearer challenge.
+     * audience — or reports it as anything but a plain bearer token (a
+     * `token_type` that is present and not `Bearer`, or a `cnf` member): a
+     * sender-constrained token needs a proof this SDK does not verify. Maps to a
+     * 401 `invalid_token` Bearer challenge.
      * @throws {IntrospectionError} when the *introspection call itself* fails for
      * a reason that is not the token's fault — the AS is unreachable, returns a
      * non-2xx (e.g. THIS RS's introspection credentials are misconfigured → 401

package/dist/lib/introspection-validator.js

@@ -7,7 +7,8 @@
  * and `client_secret_post`. We use Basic auth.
  *
  * QAuth contract (auth-server introspect route): returns
- * `{ active, sub, client_id, exp, iat, iss, aud, scope, token_type }` and
+ * `{ active, sub, client_id, exp, iat, iss, aud, scope, token_type }`, plus
+ * `cnf` with `token_type: DPoP` for a DPoP-bound token, and
  * `{ active: false }` for invalid / cross-audience tokens. The AS itself
  * already enforces audience-authoritative introspection; `resource-guard`
  * additionally re-checks `aud` locally so the no-passthrough guarantee does
@@ -15,6 +16,7 @@
  */
 import { IntrospectionError, InvalidTokenError } from './errors.js';
 import { parseScopes } from './scope.js';
+import { refuseNonBearerToken } from './sender-constraint.js';
 function audienceList(aud) {
     if (aud == null) {
         return [];
@@ -46,7 +48,10 @@ export class IntrospectionValidator {
      *
      * @throws {InvalidTokenError} when the AS authoritatively says the *token* is
      * unusable — inactive (revoked/expired/unknown) or bound to a different
-     * audience. Maps to a 401 `invalid_token` Bearer challenge.
+     * audience — or reports it as anything but a plain bearer token (a
+     * `token_type` that is present and not `Bearer`, or a `cnf` member): a
+     * sender-constrained token needs a proof this SDK does not verify. Maps to a
+     * 401 `invalid_token` Bearer challenge.
      * @throws {IntrospectionError} when the *introspection call itself* fails for
      * a reason that is not the token's fault — the AS is unreachable, returns a
      * non-2xx (e.g. THIS RS's introspection credentials are misconfigured → 401
@@ -106,6 +111,13 @@ export class IntrospectionValidator {
         if (!auds.includes(this.audience)) {
             throw new InvalidTokenError('token audience does not match this resource');
         }
+        // RFC 9449 §6.2 / §7.2: QAuth reports a DPoP-bound token with
+        // `token_type: DPoP` and its `cnf`. Such a token needs a proof of
+        // possession, and this SDK verifies none, so it is refused rather than
+        // accepted as a plain bearer. Either signal alone is enough. `token_type`
+        // is an allow-list: absent or `Bearer` only, so a bound type another AS
+        // names differently is refused too.
+        refuseNonBearerToken(body.cnf, body.token_type);
         return {
             sub: body.sub,
             clientId: body.client_id,

package/dist/lib/jwt-validator.d.ts

@@ -48,9 +48,11 @@ export declare class JwtValidator {
      * Verify a bearer token. Resolves to the normalised claims on success.
      *
      * @throws {InvalidTokenError} for any verification failure — bad signature,
-     * expiry, wrong issuer, wrong/absent audience, disallowed algorithm, or a
-     * `typ` that is not `at+jwt` (#283). The reason is short and non-sensitive
-     * (safe for `error_description`/logs); the token is never included.
+     * expiry, wrong issuer, wrong/absent audience, disallowed algorithm, a
+     * `typ` that is not `at+jwt` (#283), or a sender-constrained token (one
+     * carrying `cnf`, such as a DPoP-bound token), which needs a proof this SDK
+     * does not verify. The reason is short and non-sensitive (safe for
+     * `error_description`/logs); the token is never included.
      */
     validate(token: string): Promise<ValidatedToken>;
     /**

package/dist/lib/jwt-validator.js

@@ -14,6 +14,7 @@
 import { createRemoteJWKSet, customFetch, errors as joseErrors, jwtVerify, } from 'jose';
 import { InvalidTokenError } from './errors.js';
 import { parseScopes } from './scope.js';
+import { refuseNonBearerToken } from './sender-constraint.js';
 /**
  * RFC 9068 §2.1 `typ` of a JWT OAuth 2.0 access token.
  *
@@ -75,9 +76,11 @@ export class JwtValidator {
      * Verify a bearer token. Resolves to the normalised claims on success.
      *
      * @throws {InvalidTokenError} for any verification failure — bad signature,
-     * expiry, wrong issuer, wrong/absent audience, disallowed algorithm, or a
-     * `typ` that is not `at+jwt` (#283). The reason is short and non-sensitive
-     * (safe for `error_description`/logs); the token is never included.
+     * expiry, wrong issuer, wrong/absent audience, disallowed algorithm, a
+     * `typ` that is not `at+jwt` (#283), or a sender-constrained token (one
+     * carrying `cnf`, such as a DPoP-bound token), which needs a proof this SDK
+     * does not verify. The reason is short and non-sensitive (safe for
+     * `error_description`/logs); the token is never included.
      */
     async validate(token) {
         let payload;
@@ -102,6 +105,10 @@ export class JwtValidator {
         // attacker rewrites at will. Outside the try/catch above so this rejection
         // is not laundered into a generic jose-error string.
         this.assertAccessTokenTyp(protectedHeader['typ']);
+        // RFC 9449 §7.2: a token bound to a key (`cnf`) needs a proof of
+        // possession, and this SDK verifies none, so it is refused rather than
+        // accepted as a plain bearer. Read from the verified payload only.
+        refuseNonBearerToken(payload['cnf']);
         return toValidatedToken(payload);
     }
     /**

package/dist/lib/sender-constraint.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Refusal of every access token that is not a plain bearer token.
+ *
+ * A token that carries a `cnf` (confirmation) claim (RFC 7800 §3) is bound to
+ * a key. A DPoP-bound token names that key's thumbprint in `cnf.jkt` (RFC 9449
+ * §6) and is reported by introspection with `token_type: DPoP` (RFC 9449
+ * §6.2). A certificate-bound token names a certificate in `cnf["x5t#S256"]`
+ * (RFC 8705 §3.1). Other confirmation methods exist. Whatever the method, the
+ * holder must prove possession of the key on every request, and the resource
+ * server must check that proof before it grants access (RFC 9449 §7.1, RFC
+ * 8705 §3). Accepting such a token as a plain bearer would let anyone who
+ * copied it use it, which is exactly the theft binding exists to stop
+ * (RFC 9449 §7.2).
+ *
+ * This version of the SDK verifies no proof of possession of any kind, so it
+ * refuses every sender-constrained token outright. QAuth's own protected
+ * routes refuse a bound token presented as a Bearer token in the same way.
+ *
+ * An introspection `token_type` is read as an allow-list, not a deny-list:
+ * only an absent one or `Bearer` is a token this SDK can accept. Another
+ * authorization server may name a bound token type this SDK has never heard
+ * of (`PoP`, a misspelt `DPoP`, a non-string value), and a deny-list would let
+ * it through as a bearer token.
+ *
+ * Internal: not exported from the package entry points.
+ */
+/** The reason given for a token bound to a DPoP key. */
+export declare const DPOP_BOUND_REASON = "sender-constrained (DPoP-bound) token presented without a proof";
+/** The reason given for a token bound by any other confirmation method. */
+export declare const SENDER_CONSTRAINED_REASON = "sender-constrained token presented without a proof";
+/** The reason given for an introspected `token_type` that is neither absent nor `Bearer`. */
+export declare const NOT_BEARER_REASON = "token type is not Bearer";
+/**
+ * Refuse a token that is not a plain bearer token. Call it after the token
+ * has been verified, with the verified claims only.
+ *
+ * @param cnf the token's `cnf` claim (JWT payload) or member (introspection
+ *   response). Any value other than `undefined` refuses the token, a malformed
+ *   one included, so an unknown confirmation method fails closed.
+ * @param tokenType the introspection response's `token_type`, when there is
+ *   one. Only `undefined` (absent) or `Bearer` in any case is accepted; `DPoP`
+ *   is refused as DPoP-bound, and any other value as not Bearer. The JWT
+ *   validator passes nothing, since a JWT carries no `token_type`.
+ * @throws {InvalidTokenError} when the token is sender-constrained or its type
+ *   is not Bearer.
+ */
+export declare function refuseNonBearerToken(cnf: unknown, tokenType?: unknown): void;

package/dist/lib/sender-constraint.js

@@ -0,0 +1,69 @@
+/**
+ * Refusal of every access token that is not a plain bearer token.
+ *
+ * A token that carries a `cnf` (confirmation) claim (RFC 7800 §3) is bound to
+ * a key. A DPoP-bound token names that key's thumbprint in `cnf.jkt` (RFC 9449
+ * §6) and is reported by introspection with `token_type: DPoP` (RFC 9449
+ * §6.2). A certificate-bound token names a certificate in `cnf["x5t#S256"]`
+ * (RFC 8705 §3.1). Other confirmation methods exist. Whatever the method, the
+ * holder must prove possession of the key on every request, and the resource
+ * server must check that proof before it grants access (RFC 9449 §7.1, RFC
+ * 8705 §3). Accepting such a token as a plain bearer would let anyone who
+ * copied it use it, which is exactly the theft binding exists to stop
+ * (RFC 9449 §7.2).
+ *
+ * This version of the SDK verifies no proof of possession of any kind, so it
+ * refuses every sender-constrained token outright. QAuth's own protected
+ * routes refuse a bound token presented as a Bearer token in the same way.
+ *
+ * An introspection `token_type` is read as an allow-list, not a deny-list:
+ * only an absent one or `Bearer` is a token this SDK can accept. Another
+ * authorization server may name a bound token type this SDK has never heard
+ * of (`PoP`, a misspelt `DPoP`, a non-string value), and a deny-list would let
+ * it through as a bearer token.
+ *
+ * Internal: not exported from the package entry points.
+ */
+import { InvalidTokenError } from './errors.js';
+/** The reason given for a token bound to a DPoP key. */
+export const DPOP_BOUND_REASON = 'sender-constrained (DPoP-bound) token presented without a proof';
+/** The reason given for a token bound by any other confirmation method. */
+export const SENDER_CONSTRAINED_REASON = 'sender-constrained token presented without a proof';
+/** The reason given for an introspected `token_type` that is neither absent nor `Bearer`. */
+export const NOT_BEARER_REASON = 'token type is not Bearer';
+/**
+ * Whether an introspection `token_type` is `want`, compared ignoring case as
+ * RFC 6749 §5.1 says, but otherwise exactly: no trimming, strings only.
+ */
+function isTokenType(tokenType, want) {
+    return typeof tokenType === 'string' && tokenType.toLowerCase() === want;
+}
+/** Whether a `cnf` value carries the DPoP member `jkt`. */
+function hasJwkThumbprint(cnf) {
+    return typeof cnf === 'object' && cnf !== null && 'jkt' in cnf;
+}
+/**
+ * Refuse a token that is not a plain bearer token. Call it after the token
+ * has been verified, with the verified claims only.
+ *
+ * @param cnf the token's `cnf` claim (JWT payload) or member (introspection
+ *   response). Any value other than `undefined` refuses the token, a malformed
+ *   one included, so an unknown confirmation method fails closed.
+ * @param tokenType the introspection response's `token_type`, when there is
+ *   one. Only `undefined` (absent) or `Bearer` in any case is accepted; `DPoP`
+ *   is refused as DPoP-bound, and any other value as not Bearer. The JWT
+ *   validator passes nothing, since a JWT carries no `token_type`.
+ * @throws {InvalidTokenError} when the token is sender-constrained or its type
+ *   is not Bearer.
+ */
+export function refuseNonBearerToken(cnf, tokenType) {
+    if (isTokenType(tokenType, 'dpop') || hasJwkThumbprint(cnf)) {
+        throw new InvalidTokenError(DPOP_BOUND_REASON);
+    }
+    if (cnf !== undefined) {
+        throw new InvalidTokenError(SENDER_CONSTRAINED_REASON);
+    }
+    if (tokenType !== undefined && !isTokenType(tokenType, 'bearer')) {
+        throw new InvalidTokenError(NOT_BEARER_REASON);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qauth-labs/resource-guard",
-  "version": "0.2.0-rc.1",
+  "version": "0.2.0",
   "description": "Resource-server SDK for QAuth: RFC 9728 protected-resource metadata, RFC 6750 challenges and audience-bound bearer-token validation for MCP servers and other OAuth 2.1 resource servers.",
   "keywords": [
     "oauth",