@toolgrain/mcp 0.1.3 → 0.2.0-rc.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @toolgrain/mcp
 
+## 0.2.0-rc.0
+
+### Minor Changes
+
+- 9c5bffd: Declare resource OAuth scopes with `scopesSupported` on auth providers, including direct Clerk and JWT configuration. Validate and copy scope catalogs and emit them as `scopes_supported` in protected-resource discovery without imposing a required-scope policy.
+
+  Export Clerk's built-in OAuth scope catalog and named scope types, preserving editor completion and support for instance-defined custom scopes.
+
+  Add `AuthError("insufficient_scope", { requiredScopes, description })` for verified-token scope denials. HTTP adapters return a 403 Bearer challenge with optional required scopes and explicit public guidance, preserving private causes and existing authentication behavior.
+
+### Patch Changes
+
+- @toolgrain/protocol@0.2.0-rc.0
+
 ## 0.1.3
 
 ### Patch Changes

package/dist/auth/authorization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../../src/auth/authorization.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,YAAY,CAAC;AASpB,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,YAAY;IAsBvD,QAAQ;IACF,SAAS,QACN,MAAM,YACH,MAAM,UACR,WAAW,UACX,MAAM,IAAI,GACjB,OAAO,CAAC,SAAS,CAAC;IA0BrB,OAAO,SAAS,SAAS,GAAG,YAAY,GAAG,SAAS;EASvD"}
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../../src/auth/authorization.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,YAAY,CAAC;AASpB,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,YAAY;IAyBvD,QAAQ;IACF,SAAS,QACN,MAAM,YACH,MAAM,UACR,WAAW,UACX,MAAM,IAAI,GACjB,OAAO,CAAC,SAAS,CAAC;IA0BrB,OAAO,SAAS,SAAS,GAAG,YAAY,GAAG,SAAS;EASvD"}

package/dist/auth/authorization.js

@@ -1,6 +1,7 @@
 import { abortable } from "./abort.js";
 import { identitySnapshot } from "./context.js";
 import { AuthError } from "./errors.js";
+import { validateAuthScopes } from "./scopes.js";
 import { authUrl } from "./url.js";
 export function createAuthorization(provider) {
     const scopes = new WeakMap();
@@ -12,6 +13,9 @@ export function createAuthorization(provider) {
             authUrl(issuer);
             return issuer;
         }),
+        ...(provider.scopesSupported === undefined
+            ? {}
+            : { scopesSupported: validateAuthScopes(provider.scopesSupported) }),
     };
     if (provider &&
         (typeof provider.type !== "symbol" ||

package/dist/auth/authorization.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../../src/auth/authorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAOxC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAQnC,MAAM,UAAU,mBAAmB,CAAC,QAAuB;IACzD,MAAM,MAAM,GAAG,IAAI,OAAO,EAAoB,CAAC;IAC/C,MAAM,QAAQ,GAA6B,QAAQ,IAAI;QACrD,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS;YACjC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7C,oBAAoB,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;YACjE,OAAO,CAAC,MAAM,CAAC,CAAC;YAChB,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC;KACH,CAAC;IACF,IACE,QAAQ;QACR,CAAC,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ;YAChC,CAAC,QAAQ,EAAE,oBAAoB,CAAC,MAAM,CAAC;QAEzC,MAAM,IAAI,SAAS,CACjB,4EAA4E,CAC7E,CAAC;IACJ,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,QAAQ,EAAE,IAAI,CAAC;IAC5B,OAAO;QACL,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,IAAI,eAAe,CAAC,QAAQ,CAAC;QACrD,KAAK,CAAC,SAAS,CACb,KAAa,EACb,QAAgB,EAChB,MAAmB,EACnB,MAAkB;YAElB,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;YACrE,MAAM,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,QAAQ,GAAG,QAAQ,EAAE,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;YACzD,MAAM,QAAQ,GAAG;gBACf,IAAI;gBACJ,KAAK,EAAE,gBAAgB,CACrB,MAAM,SAAS,CACb,MAAM,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,EAC7C,MAAM,CACP,CACF;aACF,CAAC;YACF,MAAM,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,KAAK,GAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YACpE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;gBAC1B,MAAM;gBACN,OAAO;oBACL,IAAI,KAAK,CAAC,QAAQ;wBAAE,OAAO;oBAC3B,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;oBACtB,MAAM,EAAE,CAAC;gBACX,CAAC;aACF,CAAC,CAAC;YACH,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,CAAC,KAAiB;YACvB,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK;gBAAE,OAAO;YAChC,MAAM,KAAK,GAAG,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACzC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ;gBAC5C,MAAM,IAAI,SAAS,CAAC,eAAe,CAAC,CAAC;YACvC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;YACtB,OAAO,KAAK,CAAC,QAAQ,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../../src/auth/authorization.ts"],"names":[],"mappings":"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"}

package/dist/auth/errors.d.ts

@@ -1,5 +1,5 @@
 /** Public authorization failure categories mapped by HTTP adapters to 400, 401, 403, or 503. */
-export type AuthErrorCode = "invalid_request" | "invalid_token" | "access_denied" | "temporarily_unavailable";
+export type AuthErrorCode = "invalid_request" | "invalid_token" | "access_denied" | "insufficient_scope" | "temporarily_unavailable";
 declare const brand: unique symbol;
 /** Only an explicitly public description is exposed; provider causes stay private. */
 export declare class AuthError extends Error {
@@ -8,17 +8,22 @@ export declare class AuthError extends Error {
     readonly [brand] = true;
     /** Explicitly client-visible guidance; omitted descriptions keep HTTP responses generic. */
     readonly description?: string | undefined;
+    /** Copied, frozen required scopes for an `insufficient_scope` Bearer challenge; never inferred from supported scopes. */
+    readonly requiredScopes?: readonly string[] | undefined;
     /**
      * Create an authorization failure with optional public guidance and a private cause.
      *
      * @param code - Authorization failure category used by HTTP adapters.
-     * @param options - Optional public description and private standard `Error` options.
+     * @param options - Optional public description/required scopes and private standard `Error` options.
+     * @throws `TypeError` for invalid required scopes or required scopes on another error code.
      */
     constructor(
     /** Failure category; determines the default message and HTTP status. */
     code: AuthErrorCode, options?: ErrorOptions & {
         /** Public message included in HTTP error bodies and challenges; never include secrets. */
         description?: string;
+        /** Public required scope tokens, only for `insufficient_scope`; an empty array omits the challenge's scope field. */
+        requiredScopes?: readonly string[];
     });
 }
 /**

package/dist/auth/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,MAAM,MAAM,aAAa,GACrB,iBAAiB,GACjB,eAAe,GACf,eAAe,GACf,yBAAyB,CAAC;AAE9B,QAAA,MAAM,KAAK,eAA4C,CAAC;AAExD,sFAAsF;AACtF,qBAAa,SAAU,SAAQ,KAAK;IAYhC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,aAAa;IAZ9B,QAAQ,CAAC,CAAC,KAAK,CAAC,QAAQ;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1C;;;;;OAKG;IACH;IACE,wEAAwE;IAC/D,IAAI,EAAE,aAAa,EAC5B,OAAO,CAAC,EAAE,YAAY,GAAG;QACvB,0FAA0F;QAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,EAcF;CACF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAEA,gGAAgG;AAChG,MAAM,MAAM,aAAa,GACrB,iBAAiB,GACjB,eAAe,GACf,eAAe,GACf,oBAAoB,GACpB,yBAAyB,CAAC;AAE9B,QAAA,MAAM,KAAK,eAA4C,CAAC;AAExD,sFAAsF;AACtF,qBAAa,SAAU,SAAQ,KAAK;IAehC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,aAAa;IAf9B,QAAQ,CAAC,CAAC,KAAK,CAAC,QAAQ;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,yHAAyH;IACzH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAExD;;;;;;OAMG;IACH;IACE,wEAAwE;IAC/D,IAAI,EAAE,aAAa,EAC5B,OAAO,CAAC,EAAE,YAAY,GAAG;QACvB,0FAA0F;QAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,qHAAqH;QACrH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,EAsBF;CACF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D"}

package/dist/auth/errors.js

@@ -1,3 +1,4 @@
+import { validateAuthScopes } from "./scopes.js";
 const brand = Symbol.for("@toolgrain/mcp/AuthError/v1");
 /** Only an explicitly public description is exposed; provider causes stay private. */
 export class AuthError extends Error {
@@ -5,11 +6,14 @@ export class AuthError extends Error {
     [brand] = true;
     /** Explicitly client-visible guidance; omitted descriptions keep HTTP responses generic. */
     description;
+    /** Copied, frozen required scopes for an `insufficient_scope` Bearer challenge; never inferred from supported scopes. */
+    requiredScopes;
     /**
      * Create an authorization failure with optional public guidance and a private cause.
      *
      * @param code - Authorization failure category used by HTTP adapters.
-     * @param options - Optional public description and private standard `Error` options.
+     * @param options - Optional public description/required scopes and private standard `Error` options.
+     * @throws `TypeError` for invalid required scopes or required scopes on another error code.
      */
     constructor(
     /** Failure category; determines the default message and HTTP status. */
@@ -19,11 +23,17 @@ export class AuthError extends Error {
                 invalid_request: "Invalid authorization request",
                 invalid_token: "Invalid access token",
                 access_denied: "Access denied",
+                insufficient_scope: "Access token has insufficient scope",
                 temporarily_unavailable: "Authorization service unavailable",
             }[code], options);
         this.code = code;
         this.name = "AuthError";
         this.description = options?.description;
+        if (options?.requiredScopes !== undefined) {
+            if (code !== "insufficient_scope")
+                throw new TypeError("Required scopes apply only to insufficient_scope errors");
+            this.requiredScopes = validateAuthScopes(options.requiredScopes);
+        }
     }
 }
 /**

package/dist/auth/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAOA,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;AAExD,sFAAsF;AACtF,MAAM,OAAO,SAAU,SAAQ,KAAK;IAavB,IAAI;IAZN,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACxB,4FAA4F;IACnF,WAAW,CAAsB;IAE1C;;;;;OAKG;IACH;IACE,wEAAwE;IAC/D,IAAmB,EAC5B,OAGC;QAED,KAAK,CACH,OAAO,EAAE,WAAW;YAClB;gBACE,eAAe,EAAE,+BAA+B;gBAChD,aAAa,EAAE,sBAAsB;gBACrC,aAAa,EAAE,eAAe;gBAC9B,uBAAuB,EAAE,mCAAmC;aAC7D,CAAC,IAAI,CAAC,EACT,OAAO,CACR,CAAC;oBAfO,IAAI;QAgBb,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,OAAO,EAAE,WAAW,CAAC;IAC1C,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;AACtE,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAUjD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;AAExD,sFAAsF;AACtF,MAAM,OAAO,SAAU,SAAQ,KAAK;IAgBvB,IAAI;IAfN,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACxB,4FAA4F;IACnF,WAAW,CAAsB;IAC1C,yHAAyH;IAChH,cAAc,CAAiC;IAExD;;;;;;OAMG;IACH;IACE,wEAAwE;IAC/D,IAAmB,EAC5B,OAKC;QAED,KAAK,CACH,OAAO,EAAE,WAAW;YAClB;gBACE,eAAe,EAAE,+BAA+B;gBAChD,aAAa,EAAE,sBAAsB;gBACrC,aAAa,EAAE,eAAe;gBAC9B,kBAAkB,EAAE,qCAAqC;gBACzD,uBAAuB,EAAE,mCAAmC;aAC7D,CAAC,IAAI,CAAC,EACT,OAAO,CACR,CAAC;oBAlBO,IAAI;QAmBb,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,OAAO,EAAE,WAAW,CAAC;QACxC,IAAI,OAAO,EAAE,cAAc,KAAK,SAAS,EAAE,CAAC;YAC1C,IAAI,IAAI,KAAK,oBAAoB;gBAC/B,MAAM,IAAI,SAAS,CACjB,yDAAyD,CAC1D,CAAC;YACJ,IAAI,CAAC,cAAc,GAAG,kBAAkB,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;AACtE,CAAC"}

package/dist/auth/scopes.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Validate OAuth scope tokens and return a frozen copy, preserving case and order.
+ * An empty array explicitly declares no scopes; omission is handled by the caller.
+ *
+ * @param scopes - Unique, nonempty ASCII scope tokens from RFC 6749 section 3.3.
+ * @returns A readonly snapshot suitable for resource metadata or scope challenges.
+ * @throws `TypeError` for non-arrays, duplicates, whitespace, quotes, backslashes, or non-ASCII tokens.
+ */
+export declare function validateAuthScopes(scopes: readonly string[]): readonly string[];
+//# sourceMappingURL=scopes.d.ts.map

package/dist/auth/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/auth/scopes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,SAAS,MAAM,EAAE,CAmBnB"}

package/dist/auth/scopes.js

@@ -0,0 +1,25 @@
+/**
+ * Validate OAuth scope tokens and return a frozen copy, preserving case and order.
+ * An empty array explicitly declares no scopes; omission is handled by the caller.
+ *
+ * @param scopes - Unique, nonempty ASCII scope tokens from RFC 6749 section 3.3.
+ * @returns A readonly snapshot suitable for resource metadata or scope challenges.
+ * @throws `TypeError` for non-arrays, duplicates, whitespace, quotes, backslashes, or non-ASCII tokens.
+ */
+export function validateAuthScopes(scopes) {
+    const copy = [];
+    const seen = new Set();
+    if (!Array.isArray(scopes))
+        throw new TypeError("OAuth scopes must be an array of scope tokens");
+    for (const scope of scopes) {
+        if (typeof scope !== "string" ||
+            !scope.length ||
+            /[^\x21\x23-\x5b\x5d-\x7e]/.test(scope) ||
+            seen.has(scope))
+            throw new TypeError("OAuth scopes must be unique, nonempty RFC 6749 scope tokens");
+        seen.add(scope);
+        copy.push(scope);
+    }
+    return Object.freeze(copy);
+}
+//# sourceMappingURL=scopes.js.map

package/dist/auth/scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../../src/auth/scopes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAyB;IAEzB,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACxB,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACvE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IACE,OAAO,KAAK,KAAK,QAAQ;YACzB,CAAC,KAAK,CAAC,MAAM;YACb,2BAA2B,CAAC,IAAI,CAAC,KAAK,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAEf,MAAM,IAAI,SAAS,CACjB,6DAA6D,CAC9D,CAAC;QACJ,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/auth/types.d.ts

@@ -6,6 +6,8 @@ export interface AuthProvider<Identity extends object = object> {
     readonly resource?: string;
     /** Nonempty list of trusted authorization-server URLs advertised in public metadata. */
     readonly authorizationServers: readonly string[];
+    /** Optional resource scope catalog for discovery, copied at server creation; not a required-scope policy. */
+    readonly scopesSupported?: readonly string[];
     /**
      * Verify token authenticity, validity, and resource audience before returning plain identity data.
      * The server copies and deeply freezes the identity before exposing it to handlers.
@@ -30,6 +32,8 @@ export interface AuthMetadata {
     readonly resource?: string;
     /** Trusted authorization-server URLs advertised by protected-resource metadata. */
     readonly authorizationServers: readonly string[];
+    /** Resource scopes advertised as `scopes_supported`; absent means unspecified, empty means none. */
+    readonly scopesSupported?: readonly string[];
 }
 /** An opaque, single-use authorization for one server invocation. Always dispose it. */
 export interface AuthScope {

package/dist/auth/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM;IAC5D,iGAAiG;IACjG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD;;;;;;;;OAQG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5E;AAED,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;CAClD;AAED,wFAAwF;AACxF,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,uFAAuF;IACvF,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,0FAA0F;AAC1F,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,MAAM,IAAI,CAAC,EAAE,GAC3D,SAAS,YAAY,CAAC,IAAI,CAAC,EAAE,GAC7B,CAAC,SAAS,MAAM,GACd;IAAE,QAAQ,EAAE,GAAG,IAAI,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CAAE,GACnD,CAAC,CAAC;AAER,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM;IAC5D,iGAAiG;IACjG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,6GAA6G;IAC7G,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;;;;;OAQG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5E;AAED,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,oGAAoG;IACpG,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,wFAAwF;AACxF,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,uFAAuF;IACvF,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,0FAA0F;AAC1F,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,MAAM,IAAI,CAAC,EAAE,GAC3D,SAAS,YAAY,CAAC,IAAI,CAAC,EAAE,GAC7B,CAAC,SAAS,MAAM,GACd;IAAE,QAAQ,EAAE,GAAG,IAAI,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CAAE,GACnD,CAAC,CAAC;AAER,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB"}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { validateTokenAudience } from "./auth/audience.js";
 export { createAuthAccessor } from "./auth/context.js";
 export type { AuthErrorCode } from "./auth/errors.js";
 export { AuthError, isAuthError } from "./auth/errors.js";
+export { validateAuthScopes } from "./auth/scopes.js";
 export type { AuthMetadata, AuthProvider, AuthReadonly, AuthScope, AuthVerifyOptions, } from "./auth/types.js";
 export { authUrl as validateAuthUrl } from "./auth/url.js";
 export type { ContextProvider } from "./context/definition.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EACV,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACV,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,kBAAkB,GACnB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EACV,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACV,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,kBAAkB,GACnB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export { validateTokenAudience } from "./auth/audience.js";
 export { createAuthAccessor } from "./auth/context.js";
 export { AuthError, isAuthError } from "./auth/errors.js";
+export { validateAuthScopes } from "./auth/scopes.js";
 export { authUrl as validateAuthUrl } from "./auth/url.js";
 export { createContext } from "./context/definition.js";
 export { createServer } from "./server.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQ1D,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAGxD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAO3C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAQhD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAQtD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAGxD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAO3C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAQhD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolgrain/mcp",
-  "version": "0.1.3",
+  "version": "0.2.0-rc.0",
   "description": "Define reusable, typed MCP tools and servers with Zod validation.",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "latest"
+    "tag": "rc"
   },
   "type": "module",
   "exports": {
@@ -59,7 +59,7 @@
     "@toolgrain/repo-tools": "0.0.0"
   },
   "dependencies": {
-    "@toolgrain/protocol": "0.1.3"
+    "@toolgrain/protocol": "0.2.0-rc.0"
   },
   "engines": {
     "node": "^24.20.0",

package/src/auth/authorization.ts

@@ -1,6 +1,7 @@
 import { abortable } from "./abort.js";
 import { identitySnapshot } from "./context.js";
 import { AuthError } from "./errors.js";
+import { validateAuthScopes } from "./scopes.js";
 import type {
   AuthIdentity,
   AuthMetadata,
@@ -25,6 +26,9 @@ export function createAuthorization(provider?: AuthProvider) {
       authUrl(issuer);
       return issuer;
     }),
+    ...(provider.scopesSupported === undefined
+      ? {}
+      : { scopesSupported: validateAuthScopes(provider.scopesSupported) }),
   };
   if (
     provider &&

package/src/auth/errors.ts

@@ -1,8 +1,11 @@
+import { validateAuthScopes } from "./scopes.js";
+
 /** Public authorization failure categories mapped by HTTP adapters to 400, 401, 403, or 503. */
 export type AuthErrorCode =
   | "invalid_request"
   | "invalid_token"
   | "access_denied"
+  | "insufficient_scope"
   | "temporarily_unavailable";
 
 const brand = Symbol.for("@toolgrain/mcp/AuthError/v1");
@@ -12,12 +15,15 @@ export class AuthError extends Error {
   readonly [brand] = true;
   /** Explicitly client-visible guidance; omitted descriptions keep HTTP responses generic. */
   readonly description?: string | undefined;
+  /** Copied, frozen required scopes for an `insufficient_scope` Bearer challenge; never inferred from supported scopes. */
+  readonly requiredScopes?: readonly string[] | undefined;
 
   /**
    * Create an authorization failure with optional public guidance and a private cause.
    *
    * @param code - Authorization failure category used by HTTP adapters.
-   * @param options - Optional public description and private standard `Error` options.
+   * @param options - Optional public description/required scopes and private standard `Error` options.
+   * @throws `TypeError` for invalid required scopes or required scopes on another error code.
    */
   constructor(
     /** Failure category; determines the default message and HTTP status. */
@@ -25,6 +31,8 @@ export class AuthError extends Error {
     options?: ErrorOptions & {
       /** Public message included in HTTP error bodies and challenges; never include secrets. */
       description?: string;
+      /** Public required scope tokens, only for `insufficient_scope`; an empty array omits the challenge's scope field. */
+      requiredScopes?: readonly string[];
     },
   ) {
     super(
@@ -33,12 +41,20 @@ export class AuthError extends Error {
           invalid_request: "Invalid authorization request",
           invalid_token: "Invalid access token",
           access_denied: "Access denied",
+          insufficient_scope: "Access token has insufficient scope",
           temporarily_unavailable: "Authorization service unavailable",
         }[code],
       options,
     );
     this.name = "AuthError";
     this.description = options?.description;
+    if (options?.requiredScopes !== undefined) {
+      if (code !== "insufficient_scope")
+        throw new TypeError(
+          "Required scopes apply only to insufficient_scope errors",
+        );
+      this.requiredScopes = validateAuthScopes(options.requiredScopes);
+    }
   }
 }
 

package/src/auth/scopes.ts

@@ -0,0 +1,30 @@
+/**
+ * Validate OAuth scope tokens and return a frozen copy, preserving case and order.
+ * An empty array explicitly declares no scopes; omission is handled by the caller.
+ *
+ * @param scopes - Unique, nonempty ASCII scope tokens from RFC 6749 section 3.3.
+ * @returns A readonly snapshot suitable for resource metadata or scope challenges.
+ * @throws `TypeError` for non-arrays, duplicates, whitespace, quotes, backslashes, or non-ASCII tokens.
+ */
+export function validateAuthScopes(
+  scopes: readonly string[],
+): readonly string[] {
+  const copy: string[] = [];
+  const seen = new Set<string>();
+  if (!Array.isArray(scopes))
+    throw new TypeError("OAuth scopes must be an array of scope tokens");
+  for (const scope of scopes) {
+    if (
+      typeof scope !== "string" ||
+      !scope.length ||
+      /[^\x21\x23-\x5b\x5d-\x7e]/.test(scope) ||
+      seen.has(scope)
+    )
+      throw new TypeError(
+        "OAuth scopes must be unique, nonempty RFC 6749 scope tokens",
+      );
+    seen.add(scope);
+    copy.push(scope);
+  }
+  return Object.freeze(copy);
+}

package/src/auth/types.ts

@@ -6,6 +6,8 @@ export interface AuthProvider<Identity extends object = object> {
   readonly resource?: string;
   /** Nonempty list of trusted authorization-server URLs advertised in public metadata. */
   readonly authorizationServers: readonly string[];
+  /** Optional resource scope catalog for discovery, copied at server creation; not a required-scope policy. */
+  readonly scopesSupported?: readonly string[];
   /**
    * Verify token authenticity, validity, and resource audience before returning plain identity data.
    * The server copies and deeply freezes the identity before exposing it to handlers.
@@ -32,6 +34,8 @@ export interface AuthMetadata {
   readonly resource?: string;
   /** Trusted authorization-server URLs advertised by protected-resource metadata. */
   readonly authorizationServers: readonly string[];
+  /** Resource scopes advertised as `scopes_supported`; absent means unspecified, empty means none. */
+  readonly scopesSupported?: readonly string[];
 }
 
 /** An opaque, single-use authorization for one server invocation. Always dispose it. */

package/src/index.ts

@@ -2,6 +2,7 @@ export { validateTokenAudience } from "./auth/audience.js";
 export { createAuthAccessor } from "./auth/context.js";
 export type { AuthErrorCode } from "./auth/errors.js";
 export { AuthError, isAuthError } from "./auth/errors.js";
+export { validateAuthScopes } from "./auth/scopes.js";
 export type {
   AuthMetadata,
   AuthProvider,