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

package/dist/lib/metadata.js

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ */
+import { advertisableScopes } from './scope.js';
+/** Well-known suffix for Protected Resource Metadata (RFC 9728 §3.1). */
+export const PRM_WELL_KNOWN_PREFIX = '/.well-known/oauth-protected-resource';
+/** Strip a single trailing slash; leaves the root path `/` untouched-ish. */
+function stripTrailingSlash(value) {
+    return value.length > 1 && value.endsWith('/') ? value.slice(0, -1) : value;
+}
+/**
+ * Build the RFC 9728 PRM document. Pure (no I/O) so route handlers control
+ * caching and tests can assert the wire shape directly.
+ */
+export function buildProtectedResourceMetadata(input) {
+    const metadata = {
+        resource: stripTrailingSlash(input.resource),
+        authorization_servers: [stripTrailingSlash(input.authorizationServer)],
+        bearer_methods_supported: ['header'],
+    };
+    // Advertise only scopes that are genuinely a requirement of THIS resource:
+    // `offline_access` and friends concern refresh-token issuance at the AS, not
+    // resource authorization, and MCP Authorization 2026-07-28 ("Refresh
+    // Tokens") says a protected resource SHOULD NOT list them here (#284).
+    // Filtering can empty the list, in which case the key is omitted —
+    // RFC 9728 §3.2 makes `scopes_supported` OPTIONAL, and an empty array would
+    // wrongly assert the resource understands no scopes at all.
+    const scopesSupported = advertisableScopes(input.scopesSupported ?? []);
+    if (scopesSupported.length > 0) {
+        metadata.scopes_supported = scopesSupported;
+    }
+    if (input.resourceDocumentation) {
+        metadata.resource_documentation = input.resourceDocumentation;
+    }
+    return metadata;
+}
+/**
+ * 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 function metadataPathForResource(resource) {
+    let pathname;
+    try {
+        pathname = new URL(resource).pathname;
+    }
+    catch {
+        // Not parseable as a URL — treat as opaque, root path.
+        pathname = '/';
+    }
+    // Only hierarchical (http/https) URLs have a `/`-rooted path we can insert
+    // after the well-known prefix. Opaque URIs (e.g. `urn:example:resource`)
+    // expose a non-rooted `pathname`; for those we serve the bare prefix.
+    if (!pathname.startsWith('/')) {
+        return PRM_WELL_KNOWN_PREFIX;
+    }
+    const normalized = stripTrailingSlash(pathname);
+    if (normalized === '' || normalized === '/') {
+        return PRM_WELL_KNOWN_PREFIX;
+    }
+    return `${PRM_WELL_KNOWN_PREFIX}${normalized}`;
+}
+/**
+ * Absolute URL where this resource's PRM document is served — the value
+ * advertised in the `resource_metadata` challenge parameter (RFC 9728 §5.1).
+ */
+export function metadataUrlForResource(resource) {
+    const path = metadataPathForResource(resource);
+    try {
+        const url = new URL(resource);
+        return `${url.origin}${path}`;
+    }
+    catch {
+        return path;
+    }
+}

package/dist/lib/scope.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Scope utilities. OAuth scopes are a space-delimited, case-sensitive set
+ * (RFC 6749 §3.3). QAuth emits the `scope` claim as a single space-separated
+ * string; introspection returns the same shape (RFC 7662 §2.2).
+ */
+/**
+ * Parse a scope claim into a de-duplicated list. Accepts the wire string
+ * form, an already-split array, or `undefined`/empty (→ no scopes). Splits on
+ * any run of ASCII whitespace and discards empty segments.
+ */
+export declare function parseScopes(scope: string | string[] | undefined | null): string[];
+/**
+ * Return the required scopes the granted set does not satisfy. Empty result
+ * means the granted set is sufficient. Matching is exact and case-sensitive
+ * per RFC 6749 §3.3 (no hierarchical/prefix semantics).
+ *
+ * MCP Authorization 2026-07-28 ("Step-Up Authorization Flow") adds: servers
+ * MUST account for scope hierarchies, "where a broader scope implies narrower
+ * ones", when deciding whether a token is sufficient. QAuth's scope vocabulary
+ * declares no such implications — every scope is independent, so no broader
+ * scope stands in for a narrower one — which makes exact matching the complete
+ * and correct reading of that rule here, not a shortfall. A host that defines a
+ * genuinely hierarchical vocabulary of its own must expand the implied set
+ * itself when it configures `requiredScopes` / `requireScopes(...)`.
+ */
+export declare function missingScopes(granted: string[], required: string[]): string[];
+/** True when every required scope is present in the granted set. */
+export declare function hasRequiredScopes(granted: string[], required: string[]): boolean;
+/**
+ * Filter a scope list down to what is meaningful to advertise as a resource
+ * requirement — see {@link NON_RESOURCE_SCOPES}.
+ *
+ * This is applied at the two *advertisement* surfaces only (the
+ * `WWW-Authenticate` challenge and PRM `scopes_supported`), never to
+ * enforcement: a host that configures such a scope still has it checked
+ * against the token, so this cannot widen access.
+ */
+export declare function advertisableScopes(scopes: string[]): string[];

package/dist/lib/scope.js

@@ -0,0 +1,73 @@
+/**
+ * Scope utilities. OAuth scopes are a space-delimited, case-sensitive set
+ * (RFC 6749 §3.3). QAuth emits the `scope` claim as a single space-separated
+ * string; introspection returns the same shape (RFC 7662 §2.2).
+ */
+/**
+ * Parse a scope claim into a de-duplicated list. Accepts the wire string
+ * form, an already-split array, or `undefined`/empty (→ no scopes). Splits on
+ * any run of ASCII whitespace and discards empty segments.
+ */
+export function parseScopes(scope) {
+    if (scope == null) {
+        return [];
+    }
+    const tokens = Array.isArray(scope) ? scope : scope.split(/\s+/);
+    const seen = new Set();
+    for (const token of tokens) {
+        const trimmed = token.trim();
+        if (trimmed.length > 0) {
+            seen.add(trimmed);
+        }
+    }
+    return [...seen];
+}
+/**
+ * Return the required scopes the granted set does not satisfy. Empty result
+ * means the granted set is sufficient. Matching is exact and case-sensitive
+ * per RFC 6749 §3.3 (no hierarchical/prefix semantics).
+ *
+ * MCP Authorization 2026-07-28 ("Step-Up Authorization Flow") adds: servers
+ * MUST account for scope hierarchies, "where a broader scope implies narrower
+ * ones", when deciding whether a token is sufficient. QAuth's scope vocabulary
+ * declares no such implications — every scope is independent, so no broader
+ * scope stands in for a narrower one — which makes exact matching the complete
+ * and correct reading of that rule here, not a shortfall. A host that defines a
+ * genuinely hierarchical vocabulary of its own must expand the implied set
+ * itself when it configures `requiredScopes` / `requireScopes(...)`.
+ */
+export function missingScopes(granted, required) {
+    if (required.length === 0) {
+        return [];
+    }
+    const grantedSet = new Set(granted);
+    return required.filter((scope) => !grantedSet.has(scope));
+}
+/** True when every required scope is present in the granted set. */
+export function hasRequiredScopes(granted, required) {
+    return missingScopes(granted, required).length === 0;
+}
+/**
+ * Scopes that describe the client's relationship with the *authorization
+ * server* rather than anything this resource will authorize, and which must
+ * therefore never be advertised as a resource requirement (#284).
+ *
+ * MCP Authorization 2026-07-28 ("Refresh Tokens") names `offline_access`
+ * explicitly — a protected resource SHOULD NOT include it in a
+ * `WWW-Authenticate` scope or in PRM `scopes_supported`, since it only governs
+ * whether the AS issues a refresh token. Advertising it would tell a client to
+ * obtain consent that has no bearing on the call it is trying to make.
+ */
+const NON_RESOURCE_SCOPES = new Set(['offline_access']);
+/**
+ * Filter a scope list down to what is meaningful to advertise as a resource
+ * requirement — see {@link NON_RESOURCE_SCOPES}.
+ *
+ * This is applied at the two *advertisement* surfaces only (the
+ * `WWW-Authenticate` challenge and PRM `scopes_supported`), never to
+ * enforcement: a host that configures such a scope still has it checked
+ * against the token, so this cannot widen access.
+ */
+export function advertisableScopes(scopes) {
+    return scopes.filter((scope) => !NON_RESOURCE_SCOPES.has(scope));
+}

package/dist/types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Public types for `@qauth-labs/resource-guard`.
+ *
+ * `resource-guard` is the resource-server (RS) side of the QAuth OAuth 2.1 stack.
+ * An MCP-server author drops it in to obtain spec-correct OAuth from a
+ * self-hosted QAuth authorization server (AS), per the MCP Authorization
+ * profile revision 2026-07-28 and the RFCs it references:
+ *
+ * - RFC 9728 — OAuth 2.0 Protected Resource Metadata (PRM)
+ * - RFC 8707 — Resource Indicators (audience binding; no token passthrough)
+ * - RFC 7662 — OAuth 2.0 Token Introspection
+ * - RFC 6750 §3 — Bearer token `WWW-Authenticate` challenges
+ */
+/**
+ * Token-validation strategy.
+ *
+ * - `jwt` — verify the bearer locally against the AS JWKS (offline, fast,
+ *   the recommended path). Checks signature, `iss`, `exp`, and that `aud`
+ *   contains this resource's identifier.
+ * - `introspection` — verify the bearer locally as in `jwt` mode, then call
+ *   the AS RFC 7662 endpoint for the authoritative verdict. Use when the RS
+ *   must honour near-real-time revocation (or needs the detached PQC
+ *   signature the AS delivers over introspection). Only a token the AS signed
+ *   is ever introspected, so an unauthenticated caller cannot spend the RS's
+ *   introspection rate-limit budget. Requires confidential
+ *   introspection-client credentials.
+ */
+export type ValidationMode = 'jwt' | 'introspection';
+/**
+ * Result of a successful token validation. Claims are normalised to the
+ * shapes QAuth emits (see auth-server `signAccessToken` / introspect route).
+ */
+export interface ValidatedToken {
+    /** Subject — user UUID (authorization_code) or client id (client_credentials). */
+    sub?: string;
+    /** OAuth client that the token was issued to (`client_id` claim). */
+    clientId?: string;
+    /** Granted scopes, already split on whitespace (RFC 8693 `scope`). */
+    scopes: string[];
+    /** Audience — always the resource identifier(s) this token is bound to. */
+    audience: string[];
+    /** Issuer (`iss`). */
+    issuer?: string;
+    /** Expiry, seconds since epoch. */
+    expiresAt?: number;
+    /** Issued-at, seconds since epoch. */
+    issuedAt?: number;
+    /**
+     * Raw claims as received (JWT payload, or introspection response body).
+     * Provided for advanced callers; prefer the normalised fields above.
+     */
+    raw: Record<string, unknown>;
+}
+/**
+ * Confidential client credentials used to authenticate to the AS
+ * introspection endpoint (RFC 7662 requires client authentication).
+ */
+export interface IntrospectionClientCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Minimal `fetch` shape used by the JWKS and introspection clients. Defaults
+ * to the global `fetch`; injectable so tests need no network and deployments
+ * can wrap it with an SSRF-guarded / instrumented implementation.
+ */
+export type FetchLike = (input: string | URL, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+    text: () => Promise<string>;
+}>;
+/**
+ * Configuration shared by the framework-agnostic core and the Fastify plugin.
+ */
+export interface ResourceGuardConfig {
+    /**
+     * Identifier of THIS protected resource — the canonical URL clients use to
+     * reach it (RFC 9728 `resource`, RFC 8707 resource indicator). Every
+     * accepted token MUST carry this value in `aud`; tokens minted for a
+     * different audience are rejected (no token passthrough).
+     *
+     * @example 'https://memory.mcp.example.com'
+     */
+    resource: string;
+    /**
+     * Issuer identifier of the QAuth authorization server. Advertised in PRM
+     * as `authorization_servers[]` and used to validate the JWT `iss` claim.
+     * Trailing slashes are normalised away.
+     *
+     * @example 'https://auth.example.com'
+     */
+    authorizationServer: string;
+    /**
+     * Scopes a caller must hold to access the resource by default. An empty
+     * array means "any valid, audience-bound token is accepted". Per-operation
+     * step-up requirements are expressed at the call site (see `requireScopes`).
+     */
+    requiredScopes?: string[];
+    /** Token-validation strategy. Defaults to `'jwt'`. */
+    validationMode?: ValidationMode;
+    /**
+     * JWKS URL of the AS. Defaults to `${authorizationServer}/.well-known/jwks.json`,
+     * matching the QAuth AS contract. Used in both modes: introspection mode
+     * verifies the bearer against the JWKS before introspecting it.
+     */
+    jwksUri?: string;
+    /**
+     * How long (ms) a fetched JWKS may be reused before the next refresh is
+     * allowed. Maps to the jose remote-JWKS cooldown. Defaults to 300_000 (5m).
+     */
+    jwksCacheTtlMs?: number;
+    /**
+     * Introspection endpoint URL. Defaults to `${authorizationServer}/oauth/introspect`,
+     * matching the QAuth AS contract. Only used in `introspection` mode.
+     */
+    introspectionEndpoint?: string;
+    /**
+     * In `introspection` mode, verify the bearer locally against the JWKS before
+     * introspecting it, so a bearer the AS never signed is refused without
+     * spending an introspection call (the AS rate-limits introspection per
+     * caller). Defaults to `true`. Set `false` only for an AS that issues opaque
+     * (non-JWT) access tokens.
+     */
+    introspectionLocalCheck?: boolean;
+    /**
+     * Confidential credentials for the introspection endpoint. REQUIRED in
+     * `introspection` mode (RFC 7662 mandates client authentication).
+     */
+    introspectionClient?: IntrospectionClientCredentials;
+    /**
+     * Accepted JWT signature algorithms. Defaults to `['EdDSA']` — the only
+     * algorithm QAuth signs with (Ed25519). Constrained to defend against
+     * algorithm-confusion attacks.
+     */
+    allowedAlgorithms?: string[];
+    /**
+     * Require the RFC 9068 `typ: at+jwt` protected header to be PRESENT on every
+     * bearer token (#283). Defaults to `false`.
+     *
+     * A token whose `typ` is present but WRONG — an OIDC ID token, `typ: JWT`,
+     * signed by the same AS key — is rejected regardless of this flag. The flag
+     * governs only whether a `typ`-LESS token is tolerated, which matters when
+     * the upstream AS predates #283 or is still draining tokens its previous
+     * build minted (up to one `ACCESS_TOKEN_LIFESPAN`, default 900s).
+     *
+     * Set it to `true` once the AS you point at is known to stamp `typ`.
+     */
+    requireAccessTokenTyp?: boolean;
+    /**
+     * Injectable `fetch`. Defaults to the global `fetch`. Override for tests or
+     * to apply an SSRF-guarded / instrumented HTTP client.
+     */
+    fetch?: FetchLike;
+}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * Public types for `@qauth-labs/resource-guard`.
+ *
+ * `resource-guard` is the resource-server (RS) side of the QAuth OAuth 2.1 stack.
+ * An MCP-server author drops it in to obtain spec-correct OAuth from a
+ * self-hosted QAuth authorization server (AS), per the MCP Authorization
+ * profile revision 2026-07-28 and the RFCs it references:
+ *
+ * - RFC 9728 — OAuth 2.0 Protected Resource Metadata (PRM)
+ * - RFC 8707 — Resource Indicators (audience binding; no token passthrough)
+ * - RFC 7662 — OAuth 2.0 Token Introspection
+ * - RFC 6750 §3 — Bearer token `WWW-Authenticate` challenges
+ */
+export {};

package/package.json

@@ -1,17 +1,69 @@
 {
   "name": "@qauth-labs/resource-guard",
-  "version": "0.0.0",
-  "description": "Placeholder; see https://github.com/qauth-labs/qauth",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
+  "version": "0.2.0-rc.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",
+    "oauth2.1",
+    "mcp",
+    "resource-server",
+    "rfc9728",
+    "bearer",
+    "jwt",
+    "qauth"
+  ],
   "license": "Apache-2.0",
-  "type": "commonjs",
+  "homepage": "https://docs.qauth.dev/integrate/mcp-quickstart/",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/qauth-labs/qauth.git"
-  }
-}
+    "url": "git+https://github.com/qauth-labs/qauth.git",
+    "directory": "libs/sdk/resource-guard"
+  },
+  "bugs": {
+    "url": "https://github.com/qauth-labs/qauth/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./fastify": {
+      "types": "./dist/fastify.d.ts",
+      "import": "./dist/fastify.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fastify-plugin": "^6.0.1",
+    "jose": "^6.2.12"
+  },
+  "peerDependencies": {
+    "fastify": "^5.12.7"
+  },
+  "peerDependenciesMeta": {
+    "fastify": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^5.0.5",
+    "@vitest/ui": "^5.0.5",
+    "fastify": "^5.12.7",
+    "vitest": "^5.0.5"
+  },
+  "types": "./dist/index.d.ts"
+}