@qauth-labs/resource-guard 0.0.0 → 0.1.4-rc.0

package/dist/lib/fastify-plugin.js

@@ -0,0 +1,167 @@
+/**
+ * Fastify adapter for `resource-guard`.
+ *
+ * Registering this plugin:
+ *
+ * 1. serves the RFC 9728 Protected Resource Metadata document at the
+ *    resource's well-known path (and, for a path-bearing resource, also at the
+ *    bare `/.well-known/oauth-protected-resource` for discovery convenience);
+ * 2. decorates the instance with `resourceGuard` (the core), a `requireBearer`
+ *    preHandler, and a `requireScopes(...)` preHandler factory for step-up;
+ * 3. converts `ResourceGuardError`s thrown anywhere in the encapsulation context
+ *    into RFC 6750 §3.1 responses with the correct `WWW-Authenticate` header.
+ *
+ * Because the guard is exposed to parent/sibling contexts, the plugin is
+ * wrapped with `fastify-plugin`.
+ */
+import fp from 'fastify-plugin';
+import { ResourceGuard } from './core.js';
+import { InsufficientScopeError, MissingTokenError, ResourceGuardConfigError, ResourceGuardError, } from './errors.js';
+import { PRM_WELL_KNOWN_PREFIX } from './metadata.js';
+const PLUGIN_NAME = '@qauth-labs/resource-guard';
+/**
+ * Which guard validated `request.tokenClaims`. `requireScopes` may reuse
+ * claims only when its OWN guard checked them: claims a different guard
+ * validated (e.g. a parent scope's `requireBearer` hook) carry that
+ * resource's audience, not this one's.
+ */
+const claimsValidatedBy = new WeakMap();
+/**
+ * Send the RFC 6750 §3.1 response for a guard error, including the
+ * `WWW-Authenticate` challenge with the `resource_metadata` pointer.
+ */
+function sendChallenge(guard, reply, error) {
+    const body = { error: error.bearerError ?? 'invalid_request' };
+    if (error instanceof InsufficientScopeError) {
+        body['error_description'] = error.message;
+        body['scope'] = error.requiredScopes.join(' ');
+    }
+    else if (error.bearerError === 'invalid_token' && 'reason' in error) {
+        body['error_description'] = error.reason;
+    }
+    return reply
+        .code(error.statusCode)
+        .header('WWW-Authenticate', guard.challengeHeader(error))
+        .send(error instanceof MissingTokenError ? {} : body);
+}
+const plugin = async (fastify, options) => {
+    const guard = new ResourceGuard(options);
+    const cacheControl = options.metadataCacheControl ?? 'public, max-age=3600';
+    // --- Guard preHandlers ----------------------------------------------------
+    // The preHandlers reply with the Bearer challenge directly (returning the
+    // reply halts the lifecycle) rather than throwing, so the plugin is fully
+    // self-contained and never has to take over the host app's error handler.
+    // `ResourceGuardError`s that still escape into the host's error path (e.g. thrown
+    // deep inside a route handler) can be mapped with the exported
+    // `sendBearerChallenge` helper.
+    const requireBearer = async (request, reply) => {
+        try {
+            request.tokenClaims = await guard.authenticate(request.headers.authorization);
+            claimsValidatedBy.set(request, guard);
+        }
+        catch (error) {
+            if (error instanceof ResourceGuardError) {
+                return sendChallenge(guard, reply, error);
+            }
+            throw error;
+        }
+    };
+    const requireScopes = (...scopes) => {
+        return async (request, reply) => {
+            try {
+                // Re-use claims an earlier preHandler of THIS guard validated, so we do
+                // not verify the token twice in one request. Claims another guard
+                // validated were checked against another resource's audience.
+                if (request.tokenClaims && claimsValidatedBy.get(request) === guard) {
+                    guard.assertScopes(request.tokenClaims, scopes);
+                    return;
+                }
+                request.tokenClaims = await guard.authenticate(request.headers.authorization, scopes);
+                claimsValidatedBy.set(request, guard);
+            }
+            catch (error) {
+                if (error instanceof ResourceGuardError) {
+                    return sendChallenge(guard, reply, error);
+                }
+                throw error;
+            }
+        };
+    };
+    // --- Convenience decorators -----------------------------------------------
+    // The plugin is wrapped with `fastify-plugin` (no encapsulation) so these
+    // are visible to the scope that registers it and its routes — the documented
+    // single-guard ergonomics (`app.requireBearer`, `app.requireScopes(...)`).
+    //
+    // The decorator names are shared, so a scope carries exactly one guard. A
+    // host that protects several resources registers each guard in its own
+    // encapsulated child scope, where these decorators shadow a guard inherited
+    // from an ancestor. That is why this asks for an OWN property: `hasDecorator`
+    // also answers true for an inherited decorator.
+    //
+    // A second guard on the same scope could never be reached through the
+    // decorators, and its routes would look guarded while checking the first
+    // resource's audience and scopes. Refuse it at boot rather than warn.
+    if (Object.hasOwn(fastify, 'resourceGuard')) {
+        throw new ResourceGuardConfigError(`another guard (resource=${fastify.resourceGuard.resource}) is already registered on this ` +
+            `scope, and \`resourceGuard\`/\`requireBearer\`/\`requireScopes\` can reference only one. ` +
+            `Register the guard for resource=${guard.resource}, and the routes it protects, in an ` +
+            `encapsulated child scope of their own.`);
+    }
+    fastify.decorate('resourceGuard', guard);
+    fastify.decorate('requireBearer', requireBearer);
+    fastify.decorate('requireScopes', requireScopes);
+    // --- RFC 9728 Protected Resource Metadata ---------------------------------
+    const metadataHandler = async (_request, reply) => {
+        reply
+            .header('Cache-Control', cacheControl)
+            .header('Content-Type', 'application/json; charset=utf-8');
+        return reply.send(guard.getProtectedResourceMetadata());
+    };
+    // The per-resource document path is unique per resource (the resource's own
+    // path is nested under the well-known prefix), so this never collides.
+    const metadataPath = guard.getMetadataPath();
+    fastify.get(metadataPath, metadataHandler);
+    // For a path-bearing resource the canonical document lives at a nested
+    // well-known path; also expose the bare prefix so a client that probes the
+    // origin root can still discover an AS. The bare prefix is a single, shared
+    // path: claim it at most once across all guards, otherwise a second
+    // path-bearing guard would crash boot with FST_ERR_DUPLICATED_ROUTE. Ask the
+    // router, which every scope shares — sibling scopes cannot see each other.
+    if (metadataPath !== PRM_WELL_KNOWN_PREFIX) {
+        if (!fastify.hasRoute({ method: 'GET', url: `${fastify.prefix}${PRM_WELL_KNOWN_PREFIX}` })) {
+            fastify.get(PRM_WELL_KNOWN_PREFIX, metadataHandler);
+        }
+        else {
+            fastify.log.debug('resource-guard: bare %s already served by an earlier guard; not re-registering for resource=%s', PRM_WELL_KNOWN_PREFIX, guard.resource);
+        }
+    }
+    fastify.log.debug('resource-guard plugin registered (resource=%s)', guard.resource);
+};
+/**
+ * Reply to `reply` with the RFC 6750 §3.1 Bearer challenge for `error`, using
+ * `guard`'s `resource_metadata` pointer. Exposed so host apps that throw
+ * `ResourceGuardError` from their own handlers can wire it into their error handler:
+ *
+ * @example
+ * ```ts
+ * fastify.setErrorHandler((err, req, reply) => {
+ *   if (err instanceof ResourceGuardError) {
+ *     return sendBearerChallenge(fastify.resourceGuard, reply, err);
+ *   }
+ *   // ...fall through to the app's own handling
+ * });
+ * ```
+ */
+export function sendBearerChallenge(guard, reply, error) {
+    return sendChallenge(guard, reply, error);
+}
+/**
+ * `@qauth-labs/resource-guard` Fastify plugin. Wrapped with `fastify-plugin` so the
+ * `resourceGuard` decorator and the `requireBearer` / `requireScopes` preHandlers
+ * are visible to the parent app and sibling plugins.
+ */
+export const resourceGuardPlugin = fp(plugin, {
+    name: PLUGIN_NAME,
+    fastify: '5.x',
+});
+export default resourceGuardPlugin;

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

@@ -0,0 +1,53 @@
+/**
+ * Token validation via RFC 7662 introspection against the QAuth AS.
+ *
+ * Used when tokens are opaque, or when the RS must honour near-real-time
+ * revocation rather than rely on a token's `exp`. RFC 7662 requires the
+ * introspection caller to authenticate; QAuth accepts `client_secret_basic`
+ * 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: 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
+ * not depend solely on AS-side configuration.
+ */
+import type { FetchLike, IntrospectionClientCredentials, ValidatedToken } from '../types.js';
+export interface IntrospectionValidatorOptions {
+    /** Full URL of the AS introspection endpoint. */
+    endpoint: string;
+    /** Resource identifier that MUST appear in the token's `aud`. */
+    audience: string;
+    /** Confidential client credentials (RFC 7662 requires client auth). */
+    client: IntrospectionClientCredentials;
+    /** Injectable fetch. Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+}
+/** Reusable RFC 7662 introspection validator. */
+export declare class IntrospectionValidator {
+    private readonly endpoint;
+    private readonly audience;
+    private readonly authorization;
+    private readonly fetchImpl;
+    constructor(options: IntrospectionValidatorOptions);
+    /**
+     * Introspect a token and, if active and audience-bound, return normalised
+     * claims.
+     *
+     * Two error classes, deliberately distinct (RFC 6750 §3.1 semantics):
+     *
+     * @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.
+     * @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
+     * from the AS to *us*), or sends a malformed body. This is an operational /
+     * server-side fault and must surface as a 5xx, not a 401 that wrongly blames
+     * the client's token and can trigger pointless refresh loops.
+     *
+     * Reasons are short and non-sensitive; the token is never echoed.
+     */
+    validate(token: string): Promise<ValidatedToken>;
+}

package/dist/lib/introspection-validator.js

@@ -0,0 +1,120 @@
+/**
+ * Token validation via RFC 7662 introspection against the QAuth AS.
+ *
+ * Used when tokens are opaque, or when the RS must honour near-real-time
+ * revocation rather than rely on a token's `exp`. RFC 7662 requires the
+ * introspection caller to authenticate; QAuth accepts `client_secret_basic`
+ * 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: 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
+ * not depend solely on AS-side configuration.
+ */
+import { IntrospectionError, InvalidTokenError } from './errors.js';
+import { parseScopes } from './scope.js';
+function audienceList(aud) {
+    if (aud == null) {
+        return [];
+    }
+    return Array.isArray(aud) ? aud : [aud];
+}
+/** Reusable RFC 7662 introspection validator. */
+export class IntrospectionValidator {
+    endpoint;
+    audience;
+    authorization;
+    fetchImpl;
+    constructor(options) {
+        this.endpoint = options.endpoint;
+        this.audience = options.audience;
+        // `btoa` is a standard global in every modern runtime (Node 16+, Deno,
+        // Bun, Cloudflare Workers) — unlike the Node-only `Buffer` — so the
+        // framework-agnostic core stays portable. Client credentials are ASCII, so
+        // `btoa`'s latin1-only limitation does not apply here.
+        const basic = btoa(`${options.client.clientId}:${options.client.clientSecret}`);
+        this.authorization = `Basic ${basic}`;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+    }
+    /**
+     * Introspect a token and, if active and audience-bound, return normalised
+     * claims.
+     *
+     * Two error classes, deliberately distinct (RFC 6750 §3.1 semantics):
+     *
+     * @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.
+     * @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
+     * from the AS to *us*), or sends a malformed body. This is an operational /
+     * server-side fault and must surface as a 5xx, not a 401 that wrongly blames
+     * the client's token and can trigger pointless refresh loops.
+     *
+     * Reasons are short and non-sensitive; the token is never echoed.
+     */
+    async validate(token) {
+        let response;
+        try {
+            response = await this.fetchImpl(this.endpoint, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/x-www-form-urlencoded',
+                    accept: 'application/json',
+                    authorization: this.authorization,
+                },
+                // RFC 7662 §2.1 — `token` (and optional hint) in the form body.
+                body: new URLSearchParams({
+                    token,
+                    token_type_hint: 'access_token',
+                }).toString(),
+            });
+        }
+        catch (err) {
+            // Network / transport failure: the AS could not be reached. This is an
+            // RS-side operational fault, not an invalid token — surface as 5xx.
+            throw new IntrospectionError(`introspection endpoint unreachable: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!response.ok) {
+            // A non-2xx from the introspection endpoint means OUR request was
+            // rejected — typically a 401 because this RS's introspection client
+            // credentials are misconfigured, or a 5xx from the AS. Either way it is
+            // an operational fault on the server side, NOT a verdict that the
+            // bearer's token is invalid. Do not collapse it into 401 invalid_token.
+            throw new IntrospectionError(`introspection request failed with status ${response.status}`);
+        }
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            // A 2xx with an unparseable body is a broken/misbehaving AS — again an
+            // operational fault rather than an invalid token.
+            throw new IntrospectionError('malformed introspection response');
+        }
+        if (!body.active) {
+            throw new InvalidTokenError('token is not active');
+        }
+        // Defence-in-depth no-passthrough check: even though the AS only returns
+        // active=true to an audience-authoritative introspection client, re-verify
+        // the binding locally (RFC 8707) so a misconfigured AS client cannot widen
+        // what this RS will accept.
+        const auds = audienceList(body.aud);
+        if (!auds.includes(this.audience)) {
+            throw new InvalidTokenError('token audience does not match this resource');
+        }
+        return {
+            sub: body.sub,
+            clientId: body.client_id,
+            scopes: parseScopes(body.scope),
+            audience: auds,
+            issuer: body.iss,
+            expiresAt: body.exp,
+            issuedAt: body.iat,
+            raw: body,
+        };
+    }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * JWT validation against the QAuth AS JWKS.
+ *
+ * This is the recommended, offline validation path. It verifies the bearer's
+ * signature with the AS public keys (RFC 7517 JWKS), pins the algorithm to
+ * defend against algorithm-confusion, and enforces `iss` and — the core
+ * no-passthrough control — that `aud` contains THIS resource (RFC 8707).
+ *
+ * QAuth contract (auth-server): tokens are EdDSA-signed compact JWTs with
+ * claims `sub`, `client_id`, `scope` (space-separated), `aud` (string or
+ * array), `iss`, `iat`, `exp`; JWKS is served at
+ * `${authorizationServer}/.well-known/jwks.json`.
+ */
+import { type FetchImplementation } from 'jose';
+import type { ValidatedToken } from '../types.js';
+export interface JwtValidatorOptions {
+    /** JWKS document URL. */
+    jwksUri: string;
+    /** Expected issuer (`iss`) — the AS identifier. */
+    issuer: string;
+    /** Resource identifier that MUST appear in `aud`. */
+    audience: string;
+    /** Permitted signature algorithms. Defaults to `['EdDSA']`. */
+    allowedAlgorithms?: string[];
+    /**
+     * Require the RFC 9068 `typ: at+jwt` protected header to be PRESENT (#283).
+     * Defaults to `false`. See {@link ACCESS_TOKEN_TYP} for why a WRONG `typ` is
+     * rejected unconditionally while a MISSING one is gated on this flag.
+     */
+    requireAccessTokenTyp?: boolean;
+    /** JWKS reuse window in ms (jose cooldown). Defaults to 300_000 (5m). */
+    cacheTtlMs?: number;
+    /** Injectable fetch passed through to jose's remote JWKS loader. */
+    fetch?: FetchImplementation;
+}
+/**
+ * A reusable JWT validator. Construct once (the JWKS is cached/refreshed
+ * internally by jose) and call {@link JwtValidator.validate} per request.
+ */
+export declare class JwtValidator {
+    private readonly jwks;
+    private readonly issuer;
+    private readonly audience;
+    private readonly algorithms;
+    private readonly requireAccessTokenTyp;
+    constructor(options: JwtValidatorOptions);
+    /**
+     * 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.
+     */
+    validate(token: string): Promise<ValidatedToken>;
+    /**
+     * Reject a token that is not an RFC 9068 access token (#283).
+     *
+     * Two cases, gated differently because only one is a rollout hazard:
+     *
+     * - `typ` present but not `at+jwt` → ALWAYS rejected. This is the control
+     *   that stops an ID token (`typ: JWT`, same signing key, same JWKS entry)
+     *   being replayed as a bearer token, and it is safe to enforce immediately
+     *   because no token issued before #283 carries any `typ`.
+     * - `typ` absent → accepted unless `requireAccessTokenTyp` is set. An AS that
+     *   has not yet deployed #283, or one still draining tokens minted by its
+     *   previous build, emits `typ`-less access tokens that are otherwise
+     *   entirely valid; rejecting them by default would break every such
+     *   deployment on upgrade of THIS library.
+     */
+    private assertAccessTokenTyp;
+}

package/dist/lib/jwt-validator.js

@@ -0,0 +1,181 @@
+/**
+ * JWT validation against the QAuth AS JWKS.
+ *
+ * This is the recommended, offline validation path. It verifies the bearer's
+ * signature with the AS public keys (RFC 7517 JWKS), pins the algorithm to
+ * defend against algorithm-confusion, and enforces `iss` and — the core
+ * no-passthrough control — that `aud` contains THIS resource (RFC 8707).
+ *
+ * QAuth contract (auth-server): tokens are EdDSA-signed compact JWTs with
+ * claims `sub`, `client_id`, `scope` (space-separated), `aud` (string or
+ * array), `iss`, `iat`, `exp`; JWKS is served at
+ * `${authorizationServer}/.well-known/jwks.json`.
+ */
+import { createRemoteJWKSet, customFetch, errors as joseErrors, jwtVerify, } from 'jose';
+import { InvalidTokenError } from './errors.js';
+import { parseScopes } from './scope.js';
+/**
+ * RFC 9068 §2.1 `typ` of a JWT OAuth 2.0 access token.
+ *
+ * A resource server is the party this defends: the AS signs access tokens AND
+ * OIDC ID tokens with the SAME key, so both resolve to the same JWKS entry and
+ * both pass signature verification here. `typ` is the standard structural
+ * discriminator between them, checked before any claim is read.
+ *
+ * Duplicated as a literal rather than imported from `@qauth-labs/server-jwt`
+ * on purpose: `resource-guard` is the resource-server-side library and depends only
+ * on `jose`. Its value is fixed by RFC 9068, not by QAuth.
+ */
+const ACCESS_TOKEN_TYP = 'at+jwt';
+/**
+ * Normalise a jose payload to {@link ValidatedToken}. `aud` is guaranteed
+ * present and matching by the time we get here (jose checked it).
+ */
+function toValidatedToken(payload) {
+    const aud = payload.aud;
+    const audience = aud == null ? [] : Array.isArray(aud) ? aud : [aud];
+    return {
+        sub: payload.sub,
+        clientId: typeof payload['client_id'] === 'string' ? payload['client_id'] : undefined,
+        scopes: parseScopes(payload['scope']),
+        audience,
+        issuer: payload.iss,
+        expiresAt: payload.exp,
+        issuedAt: payload.iat,
+        raw: payload,
+    };
+}
+/**
+ * A reusable JWT validator. Construct once (the JWKS is cached/refreshed
+ * internally by jose) and call {@link JwtValidator.validate} per request.
+ */
+export class JwtValidator {
+    jwks;
+    issuer;
+    audience;
+    algorithms;
+    requireAccessTokenTyp;
+    constructor(options) {
+        this.issuer = options.issuer;
+        this.audience = options.audience;
+        this.algorithms = options.allowedAlgorithms ?? ['EdDSA'];
+        this.requireAccessTokenTyp = options.requireAccessTokenTyp === true;
+        const ttl = options.cacheTtlMs ?? 300_000;
+        this.jwks = createRemoteJWKSet(new URL(options.jwksUri), {
+            // `cooldownDuration` is the minimum interval between JWKS refetches and
+            // `cacheMaxAge` the maximum age before a refetch is forced; together they
+            // bound how stale a key set can be. We tie both to the configured TTL so
+            // a rotated AS key is picked up within `cacheTtlMs`.
+            cooldownDuration: ttl,
+            cacheMaxAge: ttl,
+            ...(options.fetch ? { [customFetch]: options.fetch } : {}),
+        });
+    }
+    /**
+     * 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.
+     */
+    async validate(token) {
+        let payload;
+        let protectedHeader;
+        try {
+            ({ payload, protectedHeader } = await jwtVerify(token, this.jwks, {
+                algorithms: this.algorithms,
+                issuer: this.issuer,
+                // jose enforces audience membership: the token's `aud` (string or
+                // array) MUST contain this resource. This is the RFC 8707 binding
+                // that prevents accepting tokens minted for another audience.
+                audience: this.audience,
+            }));
+        }
+        catch (error) {
+            throw new InvalidTokenError(describeJoseError(error), {
+                jwksUnavailable: isJwksUnavailable(error),
+            });
+        }
+        // #283 RFC 9068 §2.1. `protectedHeader` is the header the verified
+        // SIGNATURE covers — never `decodeProtectedHeader`, whose output an
+        // 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']);
+        return toValidatedToken(payload);
+    }
+    /**
+     * Reject a token that is not an RFC 9068 access token (#283).
+     *
+     * Two cases, gated differently because only one is a rollout hazard:
+     *
+     * - `typ` present but not `at+jwt` → ALWAYS rejected. This is the control
+     *   that stops an ID token (`typ: JWT`, same signing key, same JWKS entry)
+     *   being replayed as a bearer token, and it is safe to enforce immediately
+     *   because no token issued before #283 carries any `typ`.
+     * - `typ` absent → accepted unless `requireAccessTokenTyp` is set. An AS that
+     *   has not yet deployed #283, or one still draining tokens minted by its
+     *   previous build, emits `typ`-less access tokens that are otherwise
+     *   entirely valid; rejecting them by default would break every such
+     *   deployment on upgrade of THIS library.
+     */
+    assertAccessTokenTyp(signedTyp) {
+        if (signedTyp === undefined) {
+            if (this.requireAccessTokenTyp) {
+                throw new InvalidTokenError('token is missing the required at+jwt type');
+            }
+            return;
+        }
+        if (signedTyp !== ACCESS_TOKEN_TYP) {
+            throw new InvalidTokenError('token is not an access token (typ is not at+jwt)');
+        }
+    }
+}
+/**
+ * Whether a verification error means the key set could not be obtained, as
+ * opposed to a verdict on the token: a JWKS fetch timeout, a malformed key set,
+ * jose's generic error for a non-2xx JWKS response, or a transport error that
+ * is not a jose error at all.
+ */
+function isJwksUnavailable(error) {
+    if (error instanceof joseErrors.JWKSTimeout || error instanceof joseErrors.JWKSInvalid) {
+        return true;
+    }
+    if (error instanceof joseErrors.JOSEError) {
+        return error.code === 'ERR_JOSE_GENERIC';
+    }
+    return true;
+}
+/**
+ * Map a jose verification error to a short, non-sensitive reason string.
+ * Deliberately coarse — we do not want to give an attacker a precise oracle,
+ * but the categories below are standard and safe to surface.
+ */
+function describeJoseError(error) {
+    if (error instanceof joseErrors.JWTExpired) {
+        return 'token expired';
+    }
+    if (error instanceof joseErrors.JWTClaimValidationFailed) {
+        // Covers issuer/audience mismatch — the no-passthrough rejection lands here.
+        if (error.claim === 'aud') {
+            return 'token audience does not match this resource';
+        }
+        if (error.claim === 'iss') {
+            return 'token issuer not trusted';
+        }
+        return 'token claim validation failed';
+    }
+    if (error instanceof joseErrors.JWSSignatureVerificationFailed) {
+        return 'signature verification failed';
+    }
+    if (error instanceof joseErrors.JOSEAlgNotAllowed) {
+        return 'token algorithm not allowed';
+    }
+    if (error instanceof joseErrors.JWKSNoMatchingKey) {
+        return 'no matching signing key';
+    }
+    if (error instanceof joseErrors.JOSEError) {
+        return 'token verification failed';
+    }
+    return 'token verification failed';
+}

package/dist/lib/metadata.d.ts

@@ -0,0 +1,59 @@
+/**
+ * RFC 9728 — OAuth 2.0 Protected Resource Metadata (PRM).
+ *
+ * The RS publishes a JSON document describing itself and the authorization
+ * server(s) that protect it. MCP clients fetch it (advertised via the
+ * `WWW-Authenticate: ... resource_metadata="…"` challenge, or discovered at
+ * the well-known location as a fallback) to learn which AS to authenticate
+ * with — the entry point of the MCP authorization handshake.
+ */
+/** Well-known suffix for Protected Resource Metadata (RFC 9728 §3.1). */
+export declare const PRM_WELL_KNOWN_PREFIX = "/.well-known/oauth-protected-resource";
+/**
+ * RFC 9728 Protected Resource Metadata document. Permissive extra keys are
+ * allowed; the fields below are what QAuth-backed MCP clients consume.
+ */
+export interface ProtectedResourceMetadata {
+    /** This resource's identifier (RFC 9728 §3.2 `resource`). */
+    resource: string;
+    /** Issuer identifier(s) of the AS(es) that can authorize this resource. */
+    authorization_servers: string[];
+    /** Scopes the resource understands (advertised for client convenience). */
+    scopes_supported?: string[];
+    /** Supported ways to present the token; QAuth resources use the header. */
+    bearer_methods_supported: string[];
+    /** RFC 9728 §3.2 — where to learn more (docs link). */
+    resource_documentation?: string;
+}
+export interface BuildMetadataInput {
+    /** Resource identifier (`aud` value tokens must carry). */
+    resource: string;
+    /** AS issuer identifier. */
+    authorizationServer: string;
+    /** Scopes to advertise as `scopes_supported`. */
+    scopesSupported?: string[];
+    /** Optional documentation URL. */
+    resourceDocumentation?: string;
+}
+/**
+ * Build the RFC 9728 PRM document. Pure (no I/O) so route handlers control
+ * caching and tests can assert the wire shape directly.
+ */
+export declare function buildProtectedResourceMetadata(input: BuildMetadataInput): ProtectedResourceMetadata;
+/**
+ * Compute the well-known PRM **path** for a resource, per RFC 9728 §3.1.
+ *
+ * For a resource with no path component the document lives at
+ * `/.well-known/oauth-protected-resource`. For a resource that has a path
+ * (e.g. `https://host/mcp/memory`), the path is inserted **after** the
+ * well-known prefix: `/.well-known/oauth-protected-resource/mcp/memory`. This
+ * lets a single host expose distinct metadata per protected resource.
+ *
+ * @returns the path (always starting with the well-known prefix).
+ */
+export declare function metadataPathForResource(resource: string): string;
+/**
+ * Absolute URL where this resource's PRM document is served — the value
+ * advertised in the `resource_metadata` challenge parameter (RFC 9728 §5.1).
+ */
+export declare function metadataUrlForResource(resource: string): string;