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

package/dist/lib/core.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Framework-agnostic core of `resource-guard`.
+ *
+ * `ResourceGuard` encapsulates everything that does not depend on a web framework:
+ * config resolution, validator selection (JWT vs introspection), bearer
+ * extraction, the RFC 9728 metadata document, and scope enforcement / step-up.
+ * The Fastify plugin is a thin adapter over this; other frameworks can wrap it
+ * identically.
+ *
+ * No-passthrough guarantee: this core only ever *validates* an inbound token
+ * and returns its claims. It never returns or forwards the raw token to an
+ * upstream call site, and audience binding is enforced by both validators, so
+ * a token minted for another resource cannot be replayed here.
+ */
+import type { ResourceGuardConfig, ValidatedToken, ValidationMode } from '../types.js';
+import { type ResourceGuardError } from './errors.js';
+import { type ProtectedResourceMetadata } from './metadata.js';
+/**
+ * Extract a bearer token from an `Authorization` header value (RFC 6750 §2.1).
+ * The scheme match is case-insensitive; the credential is returned verbatim.
+ * Returns `null` when the header is absent or not a non-empty Bearer.
+ *
+ * Parsed by slicing after a linear scheme match rather than with one
+ * `/^Bearer[ ]+(.+)$/i`: that pattern backtracks polynomially when many spaces
+ * precede a line terminator, and this function is exported for callers that
+ * may not have an HTTP parser's header rules in front of it.
+ */
+export declare function extractBearerToken(authorization: string | undefined | null): string | null;
+export declare class ResourceGuard {
+    /** Canonical resource identifier (`aud` tokens must carry). */
+    readonly resource: string;
+    /** Canonical AS issuer identifier. */
+    readonly authorizationServer: string;
+    /** Default scopes required for any access. */
+    readonly requiredScopes: string[];
+    readonly validationMode: ValidationMode;
+    private readonly validator;
+    private readonly metadata;
+    constructor(config: ResourceGuardConfig);
+    private buildValidator;
+    private buildJwtValidator;
+    /** The RFC 9728 PRM document for this resource. */
+    getProtectedResourceMetadata(): ProtectedResourceMetadata;
+    /** Well-known PRM path for this resource (RFC 9728 §3.1). */
+    getMetadataPath(): string;
+    /** Absolute PRM URL advertised in the `resource_metadata` challenge param. */
+    getMetadataUrl(): string;
+    /**
+     * Build the `WWW-Authenticate` header value for a guard error, with the
+     * `resource_metadata` pointer baked in. The Fastify adapter calls this to
+     * set the header on 401 / 403 responses.
+     */
+    challengeHeader(error: ResourceGuardError): string;
+    /**
+     * Authenticate and authorize a request from its `Authorization` header.
+     *
+     * @param authorization the raw header value.
+     * @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 {InsufficientScopeError} when scopes are insufficient
+     *   (→ 403 `insufficient_scope` step-up challenge).
+     */
+    authenticate(authorization: string | undefined | null, scopes?: string[]): Promise<ValidatedToken>;
+    /**
+     * Assert that a previously validated token satisfies a scope set. Use this
+     * for incremental, mid-handler step-up checks (e.g. a privileged tool call)
+     * where the token was already validated by {@link authenticate}.
+     *
+     * @throws {InsufficientScopeError} listing every scope the request needs.
+     */
+    assertScopes(token: ValidatedToken, scopes?: string[]): void;
+}

package/dist/lib/core.js

@@ -0,0 +1,217 @@
+/**
+ * Framework-agnostic core of `resource-guard`.
+ *
+ * `ResourceGuard` encapsulates everything that does not depend on a web framework:
+ * config resolution, validator selection (JWT vs introspection), bearer
+ * extraction, the RFC 9728 metadata document, and scope enforcement / step-up.
+ * The Fastify plugin is a thin adapter over this; other frameworks can wrap it
+ * identically.
+ *
+ * No-passthrough guarantee: this core only ever *validates* an inbound token
+ * and returns its claims. It never returns or forwards the raw token to an
+ * upstream call site, and audience binding is enforced by both validators, so
+ * a token minted for another resource cannot be replayed here.
+ */
+import { challengeForError } from './challenge.js';
+import { InsufficientScopeError, InvalidTokenError, MissingTokenError, ResourceGuardConfigError, } from './errors.js';
+import { IntrospectionValidator } from './introspection-validator.js';
+import { JwtValidator } from './jwt-validator.js';
+import { buildProtectedResourceMetadata, metadataPathForResource, metadataUrlForResource, } from './metadata.js';
+import { hasRequiredScopes, missingScopes } from './scope.js';
+function stripTrailingSlash(value) {
+    return value.length > 1 && value.endsWith('/') ? value.slice(0, -1) : value;
+}
+/** `Bearer` plus the spaces after it; anchored, one quantifier, so matching is linear. */
+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]/;
+/**
+ * Extract a bearer token from an `Authorization` header value (RFC 6750 §2.1).
+ * The scheme match is case-insensitive; the credential is returned verbatim.
+ * Returns `null` when the header is absent or not a non-empty Bearer.
+ *
+ * Parsed by slicing after a linear scheme match rather than with one
+ * `/^Bearer[ ]+(.+)$/i`: that pattern backtracks polynomially when many spaces
+ * precede a line terminator, and this function is exported for callers that
+ * may not have an HTTP parser's header rules in front of it.
+ */
+export function extractBearerToken(authorization) {
+    if (!authorization) {
+        return null;
+    }
+    const value = authorization.trim();
+    const scheme = BEARER_SCHEME.exec(value);
+    if (!scheme) {
+        return null;
+    }
+    // Checked before trimming: `trim()` would strip a leading line terminator
+    // and let `"Bearer \nx"` through, which the regex form never accepted.
+    const rest = value.slice(scheme[0].length);
+    if (LINE_TERMINATOR.test(rest)) {
+        return null;
+    }
+    const token = rest.trim();
+    return token.length > 0 ? token : null;
+}
+export class ResourceGuard {
+    /** Canonical resource identifier (`aud` tokens must carry). */
+    resource;
+    /** Canonical AS issuer identifier. */
+    authorizationServer;
+    /** Default scopes required for any access. */
+    requiredScopes;
+    validationMode;
+    validator;
+    metadata;
+    constructor(config) {
+        if (!config.resource) {
+            throw new ResourceGuardConfigError('`resource` is required');
+        }
+        if (!config.authorizationServer) {
+            throw new ResourceGuardConfigError('`authorizationServer` is required');
+        }
+        this.resource = stripTrailingSlash(config.resource);
+        this.authorizationServer = stripTrailingSlash(config.authorizationServer);
+        this.requiredScopes = config.requiredScopes ?? [];
+        this.validationMode = config.validationMode ?? 'jwt';
+        this.validator = this.buildValidator(config);
+        this.metadata = buildProtectedResourceMetadata({
+            resource: this.resource,
+            authorizationServer: this.authorizationServer,
+            scopesSupported: this.requiredScopes.length > 0 ? this.requiredScopes : undefined,
+        });
+    }
+    buildValidator(config) {
+        if (this.validationMode === 'introspection') {
+            if (!config.introspectionClient) {
+                throw new ResourceGuardConfigError('introspection mode requires `introspectionClient` credentials (RFC 7662 client auth)');
+            }
+            const introspection = new IntrospectionValidator({
+                endpoint: config.introspectionEndpoint ?? `${this.authorizationServer}/oauth/introspect`,
+                audience: this.resource,
+                client: config.introspectionClient,
+                fetch: config.fetch,
+            });
+            // Verify locally BEFORE introspecting. The AS only ever reports a token
+            // active after verifying it as a JWT it signed, so a bearer the JWKS
+            // cannot verify can never be active and is refused here without an
+            // introspection call. Without this gate every inbound bearer, made-up
+            // ones included, costs one call against the AS's per-caller
+            // introspection rate limit (30/min by default) — anyone able to reach
+            // this RS could empty that budget and have every valid token answered
+            // with an upstream 429 for the rest of the window. The introspection
+            // verdict stays authoritative: it reflects revocation and carries the
+            // detached PQC signature, neither of which the local check can see.
+            //
+            // `introspectionLocalCheck: false` turns the gate off for an AS that
+            // issues opaque tokens. A JWKS outage is not a verdict on the token, so
+            // it falls through to the authoritative introspection call rather than
+            // answering 401 for every caller.
+            if (config.introspectionLocalCheck === false) {
+                return introspection;
+            }
+            const local = this.buildJwtValidator(config);
+            return {
+                validate: async (token) => {
+                    try {
+                        await local.validate(token);
+                    }
+                    catch (error) {
+                        if (!(error instanceof InvalidTokenError && error.jwksUnavailable)) {
+                            throw error;
+                        }
+                    }
+                    return introspection.validate(token);
+                },
+            };
+        }
+        // Default: local JWT verification against the AS JWKS.
+        return this.buildJwtValidator(config);
+    }
+    buildJwtValidator(config) {
+        return new JwtValidator({
+            jwksUri: config.jwksUri ?? `${this.authorizationServer}/.well-known/jwks.json`,
+            issuer: this.authorizationServer,
+            audience: this.resource,
+            allowedAlgorithms: config.allowedAlgorithms,
+            cacheTtlMs: config.jwksCacheTtlMs,
+            // #283 rollout switch. Default-off here mirrors the validator's own
+            // default; a wrong `typ` is rejected either way.
+            requireAccessTokenTyp: config.requireAccessTokenTyp === true,
+            // The injectable FetchLike is API-compatible with what jose calls; the
+            // cast is safe because we only use `(url, init) => Promise<Response-ish>`.
+            fetch: config.fetch,
+        });
+    }
+    /** The RFC 9728 PRM document for this resource. */
+    getProtectedResourceMetadata() {
+        // Return a copy so callers cannot mutate cached state.
+        return {
+            ...this.metadata,
+            authorization_servers: [...this.metadata.authorization_servers],
+            ...(this.metadata.scopes_supported
+                ? { scopes_supported: [...this.metadata.scopes_supported] }
+                : {}),
+        };
+    }
+    /** Well-known PRM path for this resource (RFC 9728 §3.1). */
+    getMetadataPath() {
+        return metadataPathForResource(this.resource);
+    }
+    /** Absolute PRM URL advertised in the `resource_metadata` challenge param. */
+    getMetadataUrl() {
+        return metadataUrlForResource(this.resource);
+    }
+    /**
+     * Build the `WWW-Authenticate` header value for a guard error, with the
+     * `resource_metadata` pointer baked in. The Fastify adapter calls this to
+     * set the header on 401 / 403 responses.
+     */
+    challengeHeader(error) {
+        return challengeForError(error, this.getMetadataUrl());
+    }
+    /**
+     * Authenticate and authorize a request from its `Authorization` header.
+     *
+     * @param authorization the raw header value.
+     * @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 {InsufficientScopeError} when scopes are insufficient
+     *   (→ 403 `insufficient_scope` step-up challenge).
+     */
+    async authenticate(authorization, scopes = []) {
+        const token = extractBearerToken(authorization);
+        if (!token) {
+            // Advertise the FULL requirement for THIS route (guard defaults plus the
+            // 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 validated = await this.validator.validate(token);
+        this.assertScopes(validated, scopes);
+        return validated;
+    }
+    /**
+     * Assert that a previously validated token satisfies a scope set. Use this
+     * for incremental, mid-handler step-up checks (e.g. a privileged tool call)
+     * where the token was already validated by {@link authenticate}.
+     *
+     * @throws {InsufficientScopeError} listing every scope the request needs.
+     */
+    assertScopes(token, scopes = []) {
+        // The challenge advertises the FULL required set (defaults + step-up) so
+        // the client can request a single, sufficient authorization in one round.
+        const required = dedupe([...this.requiredScopes, ...scopes]);
+        if (hasRequiredScopes(token.scopes, required)) {
+            return;
+        }
+        throw new InsufficientScopeError(required, missingScopes(token.scopes, required));
+    }
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Error model for `resource-guard`.
+ *
+ * These map directly to the Bearer-token error responses defined by
+ * RFC 6750 §3.1 and refined by the MCP Authorization profile (2026-07-28):
+ *
+ * - `MissingTokenError`      → 401, no `error` code (RFC 6750: a bare
+ *   `WWW-Authenticate: Bearer` challenge when no credentials were sent).
+ * - `InvalidTokenError`      → 401, `error="invalid_token"` (malformed,
+ *   expired, bad signature, wrong issuer, or wrong audience).
+ * - `InsufficientScopeError` → 403, `error="insufficient_scope"` with the
+ *   set of scopes that would satisfy the request (step-up challenge).
+ *
+ * The classes are intentionally self-contained (no dependency on the QAuth
+ * AS error model) so the SDK stays portable for external MCP-server authors.
+ */
+/** Discriminant for the Bearer challenge an error should produce. */
+export type BearerErrorCode = 'invalid_token' | 'insufficient_scope';
+/** Base class for all guard rejections that should surface a Bearer challenge. */
+export declare abstract class ResourceGuardError extends Error {
+    /** HTTP status the RS should return. */
+    abstract readonly statusCode: 401 | 403;
+    /**
+     * RFC 6750 `error` parameter for the `WWW-Authenticate` header, or
+     * `undefined` for a credential-absent challenge (no `error` per §3.1).
+     */
+    abstract readonly bearerError?: BearerErrorCode;
+    protected constructor(message: string);
+}
+/**
+ * No bearer credentials were presented. RFC 6750 §3: respond 401 with a bare
+ * `WWW-Authenticate: Bearer` challenge (no `error` code), pointing the client
+ * at the resource metadata so it can discover the AS and authenticate.
+ *
+ * The error carries the scopes the attempted route requires so the challenge
+ * can advertise them (#284). MCP Authorization 2026-07-28 ("Scope Selection
+ * Strategy") says the RS SHOULD do this, letting a client authorize correctly
+ * on its first attempt instead of fetching the PRM document and guessing.
+ */
+export declare class MissingTokenError extends ResourceGuardError {
+    readonly statusCode: 401;
+    readonly bearerError: undefined;
+    /**
+     * Scopes the attempted operation requires (guard defaults + any per-route
+     * step-up), for the `scope` challenge parameter. Empty when the route
+     * requires none — the challenge then omits `scope` entirely rather than
+     * emitting a meaningless `scope=""`.
+     */
+    readonly requiredScopes: string[];
+    constructor(requiredScopes?: string[], message?: string);
+}
+/**
+ * The presented token is unusable: malformed, expired, bad signature, wrong
+ * issuer, or — critically for no-passthrough — not audience-bound to this
+ * resource (RFC 8707). RFC 6750 §3.1: 401 `error="invalid_token"`.
+ *
+ * The human-readable `reason` is suitable for the optional
+ * `error_description` challenge parameter and for logs; it must never echo
+ * the token itself.
+ */
+export declare class InvalidTokenError extends ResourceGuardError {
+    readonly statusCode: 401;
+    readonly bearerError: 'invalid_token';
+    /** Short reason for `error_description` / structured logs. */
+    readonly reason: string;
+    /**
+     * True when local verification failed because the AS key set could not be
+     * fetched or parsed (timeout, network error, non-2xx, malformed JWKS), i.e.
+     * no verdict on the token itself was reached.
+     */
+    readonly jwksUnavailable: boolean;
+    constructor(reason: string, options?: {
+        jwksUnavailable?: boolean;
+    });
+}
+/**
+ * The token is valid but lacks one or more required scopes. RFC 6750 §3.1:
+ * 403 `error="insufficient_scope"`, advertising the scopes that would satisfy
+ * the request — the MCP 2026-07-28 incremental-consent step-up signal.
+ */
+export declare class InsufficientScopeError extends ResourceGuardError {
+    readonly statusCode: 403;
+    readonly bearerError: 'insufficient_scope';
+    /** Full set of scopes the request requires (for the `scope` challenge param). */
+    readonly requiredScopes: string[];
+    /** Subset of {@link requiredScopes} the token did not satisfy. */
+    readonly missingScopes: string[];
+    constructor(requiredScopes: string[], missingScopes: string[]);
+}
+/**
+ * Configuration error raised at setup time (e.g. introspection mode without
+ * client credentials). Not a Bearer challenge — it is a programming error in
+ * the host application and should surface as a 500 / startup failure.
+ */
+export declare class ResourceGuardConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * An operational failure while validating a token *that is not the token's
+ * fault*: the authorization server was unreachable, returned a non-2xx (e.g.
+ * because THIS resource server's introspection credentials are misconfigured),
+ * or sent a malformed response.
+ *
+ * Crucially this is **not** an {@link ResourceGuardError}, so it does not produce a
+ * 401 `invalid_token` Bearer challenge. Blaming the client's token for an
+ * RS/AS-side fault is wrong HTTP semantics (RFC 6750 §3.1) and can drive
+ * clients into futile token-refresh loops (OWASP A10, mishandling exceptional
+ * conditions). It propagates to the host's error handler and should surface as
+ * a 5xx so operators see — and clients are told — that the failure is
+ * server-side, not a bad credential.
+ *
+ * The message is short and non-sensitive; the token is never echoed.
+ */
+export declare class IntrospectionError extends Error {
+    constructor(message: string);
+}

package/dist/lib/errors.js

@@ -0,0 +1,137 @@
+/**
+ * Error model for `resource-guard`.
+ *
+ * These map directly to the Bearer-token error responses defined by
+ * RFC 6750 §3.1 and refined by the MCP Authorization profile (2026-07-28):
+ *
+ * - `MissingTokenError`      → 401, no `error` code (RFC 6750: a bare
+ *   `WWW-Authenticate: Bearer` challenge when no credentials were sent).
+ * - `InvalidTokenError`      → 401, `error="invalid_token"` (malformed,
+ *   expired, bad signature, wrong issuer, or wrong audience).
+ * - `InsufficientScopeError` → 403, `error="insufficient_scope"` with the
+ *   set of scopes that would satisfy the request (step-up challenge).
+ *
+ * The classes are intentionally self-contained (no dependency on the QAuth
+ * AS error model) so the SDK stays portable for external MCP-server authors.
+ */
+/** Base class for all guard rejections that should surface a Bearer challenge. */
+export class ResourceGuardError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, new.target);
+        }
+    }
+}
+/**
+ * No bearer credentials were presented. RFC 6750 §3: respond 401 with a bare
+ * `WWW-Authenticate: Bearer` challenge (no `error` code), pointing the client
+ * at the resource metadata so it can discover the AS and authenticate.
+ *
+ * The error carries the scopes the attempted route requires so the challenge
+ * can advertise them (#284). MCP Authorization 2026-07-28 ("Scope Selection
+ * Strategy") says the RS SHOULD do this, letting a client authorize correctly
+ * on its first attempt instead of fetching the PRM document and guessing.
+ */
+export class MissingTokenError extends ResourceGuardError {
+    statusCode = 401;
+    bearerError = undefined;
+    /**
+     * Scopes the attempted operation requires (guard defaults + any per-route
+     * step-up), for the `scope` challenge parameter. Empty when the route
+     * requires none — the challenge then omits `scope` entirely rather than
+     * emitting a meaningless `scope=""`.
+     */
+    requiredScopes;
+    constructor(requiredScopes = [], message = 'No bearer token presented') {
+        super(message);
+        this.requiredScopes = requiredScopes;
+    }
+}
+/**
+ * The presented token is unusable: malformed, expired, bad signature, wrong
+ * issuer, or — critically for no-passthrough — not audience-bound to this
+ * resource (RFC 8707). RFC 6750 §3.1: 401 `error="invalid_token"`.
+ *
+ * The human-readable `reason` is suitable for the optional
+ * `error_description` challenge parameter and for logs; it must never echo
+ * the token itself.
+ */
+export class InvalidTokenError extends ResourceGuardError {
+    statusCode = 401;
+    bearerError = 'invalid_token';
+    /** Short reason for `error_description` / structured logs. */
+    reason;
+    /**
+     * True when local verification failed because the AS key set could not be
+     * fetched or parsed (timeout, network error, non-2xx, malformed JWKS), i.e.
+     * no verdict on the token itself was reached.
+     */
+    jwksUnavailable;
+    constructor(reason, options = {}) {
+        super(`Invalid bearer token: ${reason}`);
+        this.reason = reason;
+        this.jwksUnavailable = options.jwksUnavailable === true;
+    }
+}
+/**
+ * The token is valid but lacks one or more required scopes. RFC 6750 §3.1:
+ * 403 `error="insufficient_scope"`, advertising the scopes that would satisfy
+ * the request — the MCP 2026-07-28 incremental-consent step-up signal.
+ */
+export class InsufficientScopeError extends ResourceGuardError {
+    statusCode = 403;
+    bearerError = 'insufficient_scope';
+    /** Full set of scopes the request requires (for the `scope` challenge param). */
+    requiredScopes;
+    /** Subset of {@link requiredScopes} the token did not satisfy. */
+    missingScopes;
+    constructor(requiredScopes, missingScopes) {
+        super(`Insufficient scope; missing: ${missingScopes.join(' ')}`);
+        this.requiredScopes = requiredScopes;
+        this.missingScopes = missingScopes;
+    }
+}
+/**
+ * Configuration error raised at setup time (e.g. introspection mode without
+ * client credentials). Not a Bearer challenge — it is a programming error in
+ * the host application and should surface as a 500 / startup failure.
+ */
+export class ResourceGuardConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ResourceGuardConfigError';
+        Object.setPrototypeOf(this, ResourceGuardConfigError.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ResourceGuardConfigError);
+        }
+    }
+}
+/**
+ * An operational failure while validating a token *that is not the token's
+ * fault*: the authorization server was unreachable, returned a non-2xx (e.g.
+ * because THIS resource server's introspection credentials are misconfigured),
+ * or sent a malformed response.
+ *
+ * Crucially this is **not** an {@link ResourceGuardError}, so it does not produce a
+ * 401 `invalid_token` Bearer challenge. Blaming the client's token for an
+ * RS/AS-side fault is wrong HTTP semantics (RFC 6750 §3.1) and can drive
+ * clients into futile token-refresh loops (OWASP A10, mishandling exceptional
+ * conditions). It propagates to the host's error handler and should surface as
+ * a 5xx so operators see — and clients are told — that the failure is
+ * server-side, not a bad credential.
+ *
+ * The message is short and non-sensitive; the token is never echoed.
+ */
+export class IntrospectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IntrospectionError';
+        Object.setPrototypeOf(this, IntrospectionError.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, IntrospectionError);
+        }
+    }
+}

package/dist/lib/fastify-plugin.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 type { FastifyPluginAsync, FastifyReply, preHandlerHookHandler } from 'fastify';
+import type { ResourceGuardConfig, ValidatedToken } from '../types.js';
+import { ResourceGuard } from './core.js';
+import { ResourceGuardError } from './errors.js';
+declare module 'fastify' {
+    interface FastifyInstance {
+        /** The framework-agnostic guard core. */
+        resourceGuard: ResourceGuard;
+        /**
+         * preHandler that requires a valid, audience-bound bearer carrying the
+         * guard's default `requiredScopes`. On success, `request.tokenClaims` is
+         * populated. Use as a route `preHandler`.
+         */
+        requireBearer: preHandlerHookHandler;
+        /**
+         * Build a preHandler that additionally requires the given scopes — the
+         * step-up surface for privileged operations (MCP 2026-07-28 incremental
+         * consent). Failures emit a 403 `insufficient_scope` challenge.
+         */
+        requireScopes: (...scopes: string[]) => preHandlerHookHandler;
+    }
+    interface FastifyRequest {
+        /** Claims of the validated bearer, set by `requireBearer`/`requireScopes`. */
+        tokenClaims?: ValidatedToken;
+    }
+}
+/**
+ * Configuration for the Fastify plugin. Extends the core config with route
+ * options.
+ */
+export interface ResourceGuardPluginOptions extends ResourceGuardConfig {
+    /**
+     * `Cache-Control` for the PRM document. RFC 9728 documents are highly
+     * cacheable. Defaults to `public, max-age=3600`.
+     */
+    metadataCacheControl?: string;
+}
+/**
+ * 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 declare function sendBearerChallenge(guard: ResourceGuard, reply: FastifyReply, error: ResourceGuardError): FastifyReply;
+/**
+ * `@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 declare const resourceGuardPlugin: FastifyPluginAsync<ResourceGuardPluginOptions>;
+export default resourceGuardPlugin;