@c9up/visa 0.1.0 → 0.1.2

package/dist/introspect.js

@@ -9,6 +9,7 @@
 import { authenticateClient } from "./clients.js";
 import { hashSecret } from "./crypto.js";
 import { OAuthError } from "./errors.js";
+import { audienceAllows } from "./resource.js";
 /** `{ active: false }` — the only thing an inactive token ever reveals. */
 const INACTIVE = { active: false };
 export async function introspect(request, credentials, store, now = new Date(), issuer) {
@@ -39,6 +40,9 @@ export async function introspect(request, credentials, store, now = new Date(),
             token_type: "Bearer",
             exp: Math.floor(access.expiresAt.getTime() / 1000),
             ...(access.userId === undefined ? {} : { sub: access.userId }),
+            // RFC 8707 §3 names introspection as where a resource server learns
+            // what a token was minted for.
+            ...(access.audience === undefined ? {} : { aud: access.audience }),
         };
     }
     const refresh = await store.findRefreshToken(hash);
@@ -92,16 +96,38 @@ export async function revoke(request, credentials, store, now = new Date()) {
  * What a resource server calls on every request — so it reads the store
  * directly instead of going through introspection's client authentication.
  */
-export async function verifyAccessToken(presented, store, now = new Date()) {
+export async function verifyAccessToken(presented, 
+// Only the one read: a resource server that keeps nothing but tokens should
+// not have to implement eleven methods it never calls.
+store, now = new Date(), 
+/**
+ * This resource's identifier (RFC 8707).
+ *
+ * Given, a token minted for a different resource is refused here rather
+ * than honoured — which is the entire point of binding one.
+ */
+resource) {
     const token = await store.findAccessToken(hashSecret(presented));
     if (token === null)
         return null;
     if (token.revokedAt !== undefined || token.expiresAt <= now)
         return null;
+    // RFC 8707: a token bound to a resource is refused anywhere else. Unbound
+    // tokens are accepted — that is every token issued before a client started
+    // asking, and refusing them would break each one.
+    if (!audienceAllows(token.audience, resource))
+        return null;
     return {
         clientId: token.clientId,
         ...(token.userId === undefined ? {} : { userId: token.userId }),
         scopes: token.scopes,
+        // Carried out so a caller can report the expiry it just checked, rather
+        // than reading the store a second time to say the same thing.
+        expiresAt: token.expiresAt,
+        // The PREVIOUS use, before this one is recorded — which is what the
+        // upstream guard shows on `currentAccessToken.lastUsedAt`.
+        ...(token.lastUsedAt === undefined ? {} : { lastUsedAt: token.lastUsedAt }),
+        ...(token.audience === undefined ? {} : { audience: token.audience }),
     };
 }
 function asString(value) {

package/dist/introspect.js.map

@@ -1 +1 @@
-{"version":3,"file":"introspect.js","sourceRoot":"","sources":["../src/introspect.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"introspect.js","sourceRoot":"","sources":["../src/introspect.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAA0B,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAI/C,2EAA2E;AAC3E,MAAM,QAAQ,GAA0B,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAE1D,MAAM,CAAC,KAAK,UAAU,UAAU,CAC/B,OAAgC,EAChC,WAA8B,EAC9B,KAAgB,EAChB,MAAY,IAAI,IAAI,EAAE,EACtB,MAAe;IAEf,0EAA0E;IAC1E,2DAA2D;IAC3D,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,CAC3D,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CACpB,CAAC;IACF,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IACnC,MAAM,IAAI,GACT,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAEnE,uEAAuE;IACvE,kCAAkC;IAClC,MAAM,MAAM,GACX,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACrE,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACrB,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC;YAC/D,OAAO,QAAQ,CAAC;QACjB,CAAC;QACD,+CAA+C;QAC/C,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,EAAE;YAAE,OAAO,QAAQ,CAAC;QACnD,OAAO;YACN,MAAM,EAAE,IAAI;YACZ,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;YAChD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;YAC9B,SAAS,EAAE,MAAM,CAAC,QAAQ;YAC1B,UAAU,EAAE,QAAQ;YACpB,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;YAClD,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;YAC9D,oEAAoE;YACpE,+BAA+B;YAC/B,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;SAClE,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACnD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IACtC,IACC,OAAO,CAAC,SAAS,KAAK,SAAS;QAC/B,OAAO,CAAC,UAAU,KAAK,SAAS;QAChC,OAAO,CAAC,SAAS,IAAI,GAAG;QACxB,OAAO,CAAC,QAAQ,KAAK,MAAM,CAAC,EAAE,EAC7B,CAAC;QACF,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,OAAO;QACN,MAAM,EAAE,IAAI;QACZ,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;QAChD,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QAC/B,SAAS,EAAE,OAAO,CAAC,QAAQ;QAC3B,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;QACnD,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;KAChE,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC3B,OAAgC,EAChC,WAA8B,EAC9B,KAAgB,EAChB,MAAY,IAAI,IAAI,EAAE;IAEtB,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,CAC3D,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CACpB,CAAC;IACF,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IAEnC,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACnD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACtB,mEAAmE;QACnE,IAAI,OAAO,CAAC,QAAQ,KAAK,MAAM,CAAC,EAAE;YAAE,OAAO;QAC3C,MAAM,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAChD,OAAO;IACR,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,EAAE;QAAE,OAAO;IAC7D,MAAM,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,SAAiB;AACjB,4EAA4E;AAC5E,uDAAuD;AACvD,KAAyC,EACzC,MAAY,IAAI,IAAI,EAAE;AACtB;;;;;GAKG;AACH,QAAiB;IASjB,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,eAAe,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IACjE,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IACzE,0EAA0E;IAC1E,2EAA2E;IAC3E,kDAAkD;IAClD,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,OAAO;QACN,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAC/D,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,wEAAwE;QACxE,8DAA8D;QAC9D,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,oEAAoE;QACpE,2DAA2D;QAC3D,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;QAC3E,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;KACrE,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACtE,CAAC"}

package/dist/protectedResource.d.ts

@@ -0,0 +1,81 @@
+/**
+ * What a protected resource says when it refuses, so a client can find its way
+ * in on its own (RFC 9728).
+ *
+ * Without this, a 401 is a dead end: the caller knows it needs a token and has
+ * no way to learn where tokens come from. With it, the refusal names a
+ * metadata document, the document names the authorization server, and an MCP
+ * client walks from one to the other unattended. That is the whole point — it
+ * is the difference between an agent that can connect and one that needs
+ * somebody to paste a URL into a config file.
+ *
+ * Nothing here is visa-specific: a resource server is free to be a different
+ * process from the authorization server, which is why the metadata takes the
+ * issuer as a value rather than reading one.
+ */
+/** The metadata document, §3.2. Only `resource` is required. */
+export interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers?: string[];
+    scopes_supported?: string[];
+    bearer_methods_supported?: string[];
+    resource_name?: string;
+    resource_documentation?: string;
+    jwks_uri?: string;
+}
+export interface ProtectedResourceOptions {
+    /** This resource's identifier — an absolute URI, no fragment. */
+    resource: string;
+    /** The authorization servers that issue tokens for it. */
+    authorizationServers?: readonly string[];
+    /** What a client may ask for here. RECOMMENDED by §3.2. */
+    scopesSupported?: readonly string[];
+    /** Where the token may travel. Defaults to the header, which is all visa reads. */
+    bearerMethodsSupported?: readonly string[];
+    resourceName?: string;
+    resourceDocumentation?: string;
+}
+/** The path the document is served at, §3. */
+export declare const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+/**
+ * The well-known URL for a resource identifier.
+ *
+ * §3 inserts the well-known segment BETWEEN the host and the path, so a
+ * resource at `https://api.example/mcp` publishes at
+ * `https://api.example/.well-known/oauth-protected-resource/mcp` — not at the
+ * resource's own path with the segment appended, which is the easy mistake and
+ * the one that leaves a client fetching 404s.
+ */
+export declare function protectedResourceMetadataUrl(resource: string): string;
+/** Build the document a client fetches after a 401. */
+export declare function protectedResourceMetadata(options: ProtectedResourceOptions): ProtectedResourceMetadata;
+export interface ChallengeOptions {
+    /** Where the metadata lives. Derived from the resource when omitted. */
+    resourceMetadata?: string;
+    /** This resource's identifier, used to derive the metadata URL. */
+    resource?: string;
+    /** `invalid_token`, `insufficient_scope` — RFC 6750 §3.1. */
+    error?: string;
+    errorDescription?: string;
+    /** What the caller would have needed, with `insufficient_scope`. */
+    scope?: readonly string[];
+}
+/**
+ * The `WWW-Authenticate` value for a 401, §5.1.
+ *
+ * Quoted values are checked rather than escaped: the header is a
+ * comma-separated list of quoted strings, and a value carrying a quote or a
+ * control character cannot be represented in it at all. A caller that built
+ * one from user input should hear about it here, not ship a header a client
+ * parses into something else.
+ */
+export declare function wwwAuthenticate(options?: ChallengeOptions): string;
+/**
+ * A resource identifier is an absolute URI with no fragment (RFC 8707 §2).
+ *
+ * Checked where the metadata is built, because a resource that publishes an
+ * identifier its own tokens will not match is broken in a way only visible at
+ * the moment a client is refused.
+ */
+export declare function assertResourceIdentifier(resource: string): void;
+//# sourceMappingURL=protectedResource.d.ts.map

package/dist/protectedResource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protectedResource.d.ts","sourceRoot":"","sources":["../src/protectedResource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gEAAgE;AAChE,MAAM,WAAW,yBAAyB;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACxC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,2DAA2D;IAC3D,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,mFAAmF;IACnF,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,8CAA8C;AAC9C,eAAO,MAAM,uBAAuB,0CAA0C,CAAC;AAE/E;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOrE;AAED,uDAAuD;AACvD,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,wBAAwB,GAC/B,yBAAyB,CAoB3B;AAED,MAAM,WAAW,gBAAgB;IAChC,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAwBtE;AAsBD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAU/D"}

package/dist/protectedResource.js

@@ -0,0 +1,124 @@
+/**
+ * What a protected resource says when it refuses, so a client can find its way
+ * in on its own (RFC 9728).
+ *
+ * Without this, a 401 is a dead end: the caller knows it needs a token and has
+ * no way to learn where tokens come from. With it, the refusal names a
+ * metadata document, the document names the authorization server, and an MCP
+ * client walks from one to the other unattended. That is the whole point — it
+ * is the difference between an agent that can connect and one that needs
+ * somebody to paste a URL into a config file.
+ *
+ * Nothing here is visa-specific: a resource server is free to be a different
+ * process from the authorization server, which is why the metadata takes the
+ * issuer as a value rather than reading one.
+ */
+/** The path the document is served at, §3. */
+export const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+/**
+ * The well-known URL for a resource identifier.
+ *
+ * §3 inserts the well-known segment BETWEEN the host and the path, so a
+ * resource at `https://api.example/mcp` publishes at
+ * `https://api.example/.well-known/oauth-protected-resource/mcp` — not at the
+ * resource's own path with the segment appended, which is the easy mistake and
+ * the one that leaves a client fetching 404s.
+ */
+export function protectedResourceMetadataUrl(resource) {
+    const url = new URL(resource);
+    const path = url.pathname === "/" ? "" : url.pathname.replace(/\/$/, "");
+    url.pathname = `${PROTECTED_RESOURCE_PATH}${path}`;
+    url.search = "";
+    url.hash = "";
+    return url.href;
+}
+/** Build the document a client fetches after a 401. */
+export function protectedResourceMetadata(options) {
+    assertResourceIdentifier(options.resource);
+    return {
+        resource: options.resource,
+        ...(options.authorizationServers === undefined
+            ? {}
+            : { authorization_servers: [...options.authorizationServers] }),
+        ...(options.scopesSupported === undefined
+            ? {}
+            : { scopes_supported: [...options.scopesSupported] }),
+        bearer_methods_supported: [
+            ...(options.bearerMethodsSupported ?? ["header"]),
+        ],
+        ...(options.resourceName === undefined
+            ? {}
+            : { resource_name: options.resourceName }),
+        ...(options.resourceDocumentation === undefined
+            ? {}
+            : { resource_documentation: options.resourceDocumentation }),
+    };
+}
+/**
+ * The `WWW-Authenticate` value for a 401, §5.1.
+ *
+ * Quoted values are checked rather than escaped: the header is a
+ * comma-separated list of quoted strings, and a value carrying a quote or a
+ * control character cannot be represented in it at all. A caller that built
+ * one from user input should hear about it here, not ship a header a client
+ * parses into something else.
+ */
+export function wwwAuthenticate(options = {}) {
+    const metadataUrl = options.resourceMetadata ??
+        (options.resource === undefined
+            ? undefined
+            : protectedResourceMetadataUrl(options.resource));
+    const parameters = [];
+    if (options.error !== undefined)
+        parameters.push(["error", options.error]);
+    if (options.errorDescription !== undefined) {
+        parameters.push(["error_description", options.errorDescription]);
+    }
+    if (options.scope !== undefined && options.scope.length > 0) {
+        parameters.push(["scope", options.scope.join(" ")]);
+    }
+    if (metadataUrl !== undefined) {
+        parameters.push(["resource_metadata", metadataUrl]);
+    }
+    if (parameters.length === 0)
+        return "Bearer";
+    const rendered = parameters
+        .map(([key, value]) => `${key}="${quotable(value, key)}"`)
+        .join(", ");
+    return `Bearer ${rendered}`;
+}
+function quotable(value, parameter) {
+    // A quoted-string holds neither a bare quote nor a control character, and
+    // neither can be escaped into one usefully — a client would read the header
+    // as a different set of parameters.
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (character === '"' ||
+            character === "\\" ||
+            code < 0x20 ||
+            code === 0x7f) {
+            throw new Error(`[visa] ${parameter} cannot go in a WWW-Authenticate header: it holds a quote, a backslash or a control character`);
+        }
+    }
+    return value;
+}
+/**
+ * A resource identifier is an absolute URI with no fragment (RFC 8707 §2).
+ *
+ * Checked where the metadata is built, because a resource that publishes an
+ * identifier its own tokens will not match is broken in a way only visible at
+ * the moment a client is refused.
+ */
+export function assertResourceIdentifier(resource) {
+    let url;
+    try {
+        url = new URL(resource);
+    }
+    catch {
+        throw new Error(`[visa] resource must be an absolute URI: ${resource}`);
+    }
+    if (url.hash !== "") {
+        throw new Error(`[visa] resource must not carry a fragment: ${resource}`);
+    }
+}
+//# sourceMappingURL=protectedResource.js.map

package/dist/protectedResource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protectedResource.js","sourceRoot":"","sources":["../src/protectedResource.ts"],"names":[],"mappings":"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"}

package/dist/register.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Clients that register themselves (RFC 7591).
+ *
+ * An MCP client such as claude.ai or ChatGPT has nobody to fill in a form for
+ * it: it discovers this server, registers, and comes back with an id. Without
+ * this the only way in is a human pasting credentials somewhere.
+ *
+ * OFF unless the application turns it on, and that is the important part. Open
+ * registration means anyone who can reach the endpoint can create a client —
+ * the RFC says a server SHOULD allow it for interoperability, and also says
+ * the endpoint MAY be protected (§1.2, §3). The safe default here is the one
+ * the RFC permits rather than the one it encourages, because an authorization
+ * server that silently accepts registrations is a thing nobody asked for. Turn
+ * it on deliberately, and with an initial access token if the deployment is
+ * not meant to be open.
+ *
+ * A registered client gets exactly what this server allows: the grants,
+ * scopes and auth methods in the configuration, never what the request asked
+ * for. That is the difference between letting a client name itself and letting
+ * it decide what it may do.
+ */
+import type { Client, ClientAuthMethod, GrantType } from "./types.js";
+/** The metadata a request may send (§2). Unknown members are ignored. */
+export interface ClientRegistrationRequest {
+    redirect_uris?: unknown;
+    token_endpoint_auth_method?: unknown;
+    grant_types?: unknown;
+    response_types?: unknown;
+    client_name?: unknown;
+    client_uri?: unknown;
+    logo_uri?: unknown;
+    scope?: unknown;
+    contacts?: unknown;
+    tos_uri?: unknown;
+    policy_uri?: unknown;
+    software_id?: unknown;
+    software_version?: unknown;
+    software_statement?: unknown;
+    /**
+     * Whatever else the client sent.
+     *
+     * §2 says a server ignores metadata it does not understand, and this is a
+     * parsed HTTP body — a client that sends `client_id` hoping to pick its own
+     * is a real thing, and it lands here rather than being a type error nobody
+     * sees at run time.
+     */
+    [member: string]: unknown;
+}
+/** The 201 body (§3.2.1). */
+export interface ClientRegistrationResponse {
+    client_id: string;
+    client_secret?: string;
+    /** Seconds since the epoch. */
+    client_id_issued_at: number;
+    /** REQUIRED when a secret was issued. `0` means it does not expire. */
+    client_secret_expires_at?: number;
+    redirect_uris: string[];
+    grant_types: GrantType[];
+    token_endpoint_auth_method: ClientAuthMethod;
+    client_name: string;
+    scope?: string;
+}
+export interface RegistrationOptions {
+    /** Nothing happens unless this is true. */
+    enabled?: boolean;
+    /**
+     * Require this bearer token on the registration request.
+     *
+     * Left out, the endpoint is open — which is what an MCP client that has
+     * never met you needs, and what a deployment on the public internet should
+     * think about before shipping.
+     */
+    initialAccessToken?: string;
+    /** What a self-registered client may ever ask for. Defaults to none. */
+    scopes?: readonly string[];
+    /** Which grants it may use. Defaults to the authorization code flow and refresh. */
+    grantTypes?: readonly GrantType[];
+    /** Seconds until an issued secret expires. Omitted means it does not (§3.2.1). */
+    secretTtlSeconds?: number;
+}
+/**
+ * Check a registration request and say what the client may be.
+ *
+ * Returns the client to store and the plaintext secret, if one was issued —
+ * the caller persists the first and hands back the second, once.
+ */
+export declare function validateRegistration(request: ClientRegistrationRequest, options: RegistrationOptions, presentedToken?: string): {
+    redirectUris: string[];
+    grantTypes: GrantType[];
+    scopes: string[];
+    tokenEndpointAuthMethod: ClientAuthMethod;
+    name: string;
+};
+/** The 201 body for a client that was just created. */
+export declare function registrationResponse(client: Client, issuedAt: Date, secret: string | undefined, options: RegistrationOptions): ClientRegistrationResponse;
+//# sourceMappingURL=register.d.ts.map

package/dist/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEtE,yEAAyE;AACzE,MAAM,WAAW,yBAAyB;IACzC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;OAOG;IACH,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,6BAA6B;AAC7B,MAAM,WAAW,0BAA0B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,0BAA0B,EAAE,gBAAgB,CAAC;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IACnC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,oFAAoF;IACpF,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAClC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAOD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,yBAAyB,EAClC,OAAO,EAAE,mBAAmB,EAC5B,cAAc,CAAC,EAAE,MAAM,GACrB;IACF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,uBAAuB,EAAE,gBAAgB,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;CACb,CAmDA;AAED,uDAAuD;AACvD,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,IAAI,EACd,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,mBAAmB,GAC1B,0BAA0B,CAsB5B"}

package/dist/register.js

@@ -0,0 +1,173 @@
+/**
+ * Clients that register themselves (RFC 7591).
+ *
+ * An MCP client such as claude.ai or ChatGPT has nobody to fill in a form for
+ * it: it discovers this server, registers, and comes back with an id. Without
+ * this the only way in is a human pasting credentials somewhere.
+ *
+ * OFF unless the application turns it on, and that is the important part. Open
+ * registration means anyone who can reach the endpoint can create a client —
+ * the RFC says a server SHOULD allow it for interoperability, and also says
+ * the endpoint MAY be protected (§1.2, §3). The safe default here is the one
+ * the RFC permits rather than the one it encourages, because an authorization
+ * server that silently accepts registrations is a thing nobody asked for. Turn
+ * it on deliberately, and with an initial access token if the deployment is
+ * not meant to be open.
+ *
+ * A registered client gets exactly what this server allows: the grants,
+ * scopes and auth methods in the configuration, never what the request asked
+ * for. That is the difference between letting a client name itself and letting
+ * it decide what it may do.
+ */
+import { OAuthError } from "./errors.js";
+const DEFAULT_GRANTS = [
+    "authorization_code",
+    "refresh_token",
+];
+/**
+ * Check a registration request and say what the client may be.
+ *
+ * Returns the client to store and the plaintext secret, if one was issued —
+ * the caller persists the first and hands back the second, once.
+ */
+export function validateRegistration(request, options, presentedToken) {
+    if (options.enabled !== true) {
+        throw new OAuthError("invalid_client_metadata", "This server does not accept client registrations.");
+    }
+    if (options.initialAccessToken !== undefined) {
+        // Constant-time is not the point here: the token is compared once per
+        // registration, and a registration endpoint is not a guessing oracle
+        // worth the machinery. Absent or wrong reads the same to the caller.
+        if (presentedToken !== options.initialAccessToken) {
+            throw new OAuthError("invalid_client_metadata", "Registration on this server needs an initial access token.");
+        }
+    }
+    const redirectUris = readStringList(request.redirect_uris);
+    const grantTypes = resolveGrants(request.grant_types, options);
+    // A client using the authorization code flow has somewhere to come back to,
+    // and this is the last moment anyone checks.
+    if (grantTypes.includes("authorization_code") && redirectUris.length === 0) {
+        throw new OAuthError("invalid_redirect_uri", "redirect_uris is required for the authorization_code grant.");
+    }
+    for (const uri of redirectUris)
+        assertRedirectUri(uri);
+    const allowed = options.scopes ?? [];
+    const requested = readScope(request.scope);
+    const outside = requested.filter((scope) => !allowed.includes(scope));
+    if (outside.length > 0) {
+        throw new OAuthError("invalid_client_metadata", `This server does not grant ${outside.join(", ")} to a self-registered client.`);
+    }
+    return {
+        redirectUris,
+        grantTypes,
+        // What was asked for, narrowed to what is allowed — never the allowed
+        // set, or every client would be registered with everything.
+        scopes: requested,
+        tokenEndpointAuthMethod: readAuthMethod(request.token_endpoint_auth_method),
+        name: readName(request.client_name),
+    };
+}
+/** The 201 body for a client that was just created. */
+export function registrationResponse(client, issuedAt, secret, options) {
+    const seconds = Math.floor(issuedAt.getTime() / 1000);
+    return {
+        client_id: client.id,
+        ...(secret === undefined ? {} : { client_secret: secret }),
+        client_id_issued_at: seconds,
+        // REQUIRED when a secret was issued, and `0` is the spelling for "never"
+        // — not an omission, which would mean the field was not answered.
+        ...(secret === undefined
+            ? {}
+            : {
+                client_secret_expires_at: options.secretTtlSeconds === undefined
+                    ? 0
+                    : seconds + options.secretTtlSeconds,
+            }),
+        redirect_uris: client.redirectUris,
+        grant_types: client.grantTypes,
+        token_endpoint_auth_method: client.tokenEndpointAuthMethod,
+        client_name: client.name,
+        ...(client.scopes.length === 0 ? {} : { scope: client.scopes.join(" ") }),
+    };
+}
+function resolveGrants(value, options) {
+    const allowed = options.grantTypes ?? DEFAULT_GRANTS;
+    const requested = readStringList(value);
+    if (requested.length === 0)
+        return [...allowed];
+    const grants = [];
+    for (const grant of requested) {
+        if (!isGrantType(grant) || !allowed.includes(grant)) {
+            throw new OAuthError("invalid_client_metadata", `This server does not allow the ${grant} grant to a self-registered client.`);
+        }
+        if (!grants.includes(grant))
+            grants.push(grant);
+    }
+    return grants;
+}
+/**
+ * A redirect URI a self-registered client may use.
+ *
+ * https, or http on a loopback address — a native app's callback. Anything
+ * else is refused: an authorization code sent over plain http to a host
+ * someone else controls is the code given away.
+ */
+function assertRedirectUri(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new OAuthError("invalid_redirect_uri", `${value} is not an absolute URI.`);
+    }
+    if (url.hash !== "") {
+        throw new OAuthError("invalid_redirect_uri", `${value} must not carry a fragment.`);
+    }
+    if (url.protocol === "https:")
+        return;
+    const loopback = url.hostname === "127.0.0.1" ||
+        url.hostname === "[::1]" ||
+        url.hostname === "localhost";
+    if (url.protocol === "http:" && loopback)
+        return;
+    throw new OAuthError("invalid_redirect_uri", `${value} must use https, or http on a loopback address.`);
+}
+function readStringList(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new OAuthError("invalid_client_metadata", "redirect_uris and grant_types must be arrays of strings.");
+    }
+    return value.filter((entry) => typeof entry === "string");
+}
+function readScope(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (typeof value !== "string") {
+        throw new OAuthError("invalid_client_metadata", "scope must be a space-separated string.");
+    }
+    return value.split(/\s+/).filter((scope) => scope !== "");
+}
+function readAuthMethod(value) {
+    if (value === undefined || value === null)
+        return "client_secret_basic";
+    if (value === "client_secret_basic" ||
+        value === "client_secret_post" ||
+        value === "none") {
+        return value;
+    }
+    throw new OAuthError("invalid_client_metadata", `token_endpoint_auth_method ${String(value)} is not supported.`);
+}
+function readName(value) {
+    if (typeof value === "string" && value.trim() !== "")
+        return value.trim();
+    // A client with no name shows as one on a consent screen, which is worse
+    // than a placeholder nobody mistakes for a brand.
+    return "Unnamed client";
+}
+function isGrantType(value) {
+    return (value === "authorization_code" ||
+        value === "refresh_token" ||
+        value === "client_credentials");
+}
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"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"}

package/dist/resource.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Which resource a token is for (RFC 8707).
+ *
+ * A token with no stated audience is a token for everything. Send it to the
+ * wrong server — or let a compromised one replay it — and every other resource
+ * that trusts the same issuer accepts it. The `resource` parameter is how a
+ * client says "this one is for the calendar API", and how the calendar API
+ * refuses one minted for somebody else.
+ *
+ * Read off the RFC rather than recalled: the value MUST be an absolute URI
+ * without a fragment (§2), it MAY repeat, and a resource the server does not
+ * accept is refused with `invalid_target` (§2) — not `invalid_request`, which
+ * would tell a client its request was malformed when it was merely aimed
+ * somewhere it may not go.
+ */
+/**
+ * Normalise however the parameter arrived into a list.
+ *
+ * A form body gives one value or several under the same name, and a query
+ * string the same; both are `resource=` repeated, which parsers hand over
+ * either way.
+ */
+export declare function readResourceParameter(value: unknown): string[];
+/**
+ * Check each one, and refuse the request if any is unusable.
+ *
+ * `invalid_target` for every rejection here, including a malformed URI: §2
+ * names that code for "cannot parse the provided value(s)" as well as for a
+ * resource the server will not issue for.
+ */
+export declare function validateResources(requested: readonly string[], accepted?: readonly string[]): string[];
+/**
+ * What a token request may narrow to.
+ *
+ * A refresh or an exchange may ask for fewer resources than were authorised,
+ * never for more — the same rule scopes follow, and for the same reason: the
+ * user agreed to a set, and a later request must not widen it.
+ */
+export declare function narrowResources(requested: readonly string[], granted: readonly string[]): string[];
+/**
+ * Is this token for me?
+ *
+ * What a resource server asks. A token bound to nothing is accepted — that is
+ * every token issued before a client started sending `resource`, and refusing
+ * them would break each one. A token bound to SOMETHING must name this
+ * resource, or it was minted for another server and arriving here means it
+ * travelled.
+ */
+export declare function audienceAllows(audience: readonly string[] | undefined, resource: string | undefined): boolean;
+//# sourceMappingURL=resource.d.ts.map

package/dist/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAM9D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAChC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,EAAE,CA8BV;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,OAAO,EAAE,SAAS,MAAM,EAAE,GACxB,MAAM,EAAE,CAmBV;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACvC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC1B,OAAO,CAIT"}