@c9up/visa 0.1.1 → 0.1.2

package/src/errors.ts

@@ -19,6 +19,8 @@ export type AuthorizationErrorCode =
 	| "access_denied"
 	| "unsupported_response_type"
 	| "invalid_scope"
+	/** RFC 8707 §2 — a resource this server will not issue for, or cannot parse. */
+	| "invalid_target"
 	| "server_error"
 	| "temporarily_unavailable";
 
@@ -29,9 +31,21 @@ export type TokenErrorCode =
 	| "invalid_grant"
 	| "unauthorized_client"
 	| "unsupported_grant_type"
-	| "invalid_scope";
+	| "invalid_scope"
+	/** RFC 8707 §2. */
+	| "invalid_target";
+
+/** Error codes the registration endpoint may return (RFC 7591 §3.2.2). */
+export type RegistrationErrorCode =
+	| "invalid_redirect_uri"
+	| "invalid_client_metadata"
+	| "invalid_software_statement"
+	| "unapproved_software_statement";
 
-export type ProtocolErrorCode = AuthorizationErrorCode | TokenErrorCode;
+export type ProtocolErrorCode =
+	| AuthorizationErrorCode
+	| TokenErrorCode
+	| RegistrationErrorCode;
 
 /**
  * A failure the client is told about, in the words the spec chose.

package/src/guard.ts

@@ -21,6 +21,7 @@
 
 import { hashSecret, randomToken } from "./crypto.js";
 import { verifyAccessToken } from "./introspect.js";
+import { wwwAuthenticate } from "./protectedResource.js";
 import type { VisaStore } from "./store.js";
 
 /**
@@ -214,6 +215,14 @@ export interface VisaGuardConfig {
 	tokenClientId?: string;
 	/** How long a minted token lasts — upstream's `expiresIn`, in seconds. */
 	expiresInSeconds?: number;
+	/**
+	 * The protected resource this guard stands in front of (RFC 9728).
+	 *
+	 * Given, {@link VisaGuard.challenge} returns a `WWW-Authenticate` naming
+	 * the metadata document, which is how an MCP client finds the
+	 * authorization server without being told where it is.
+	 */
+	resource?: string;
 }
 
 /**
@@ -331,6 +340,27 @@ export class VisaGuard {
 		return { headers: { authorization: `Bearer ${token.value}` } };
 	}
 
+	/**
+	 * The `WWW-Authenticate` value a 401 from this guard should carry.
+	 *
+	 * Returned rather than set: a warden strategy answers whether a credential
+	 * is good, and the response belongs to whoever refuses the request. An
+	 * exception handler sets it — `response.header('www-authenticate',
+	 * guard.challenge())` — and with it a client that has no token learns
+	 * where to get one instead of hitting a dead end.
+	 */
+	challenge(
+		options: { error?: string; scope?: readonly string[] } = {},
+	): string {
+		return wwwAuthenticate({
+			...(this.#config.resource === undefined
+				? {}
+				: { resource: this.#config.resource }),
+			...(options.error === undefined ? {} : { error: options.error }),
+			...(options.scope === undefined ? {} : { scope: options.scope }),
+		});
+	}
+
 	async verify(presented: string): Promise<GuardResult> {
 		const store = this.#store();
 		const now = new Date();

package/src/index.ts

@@ -36,6 +36,7 @@ export {
 	type AuthorizationErrorCode,
 	OAuthError,
 	type ProtocolErrorCode,
+	type RegistrationErrorCode,
 	type TokenErrorCode,
 	VisaError,
 } from "./errors.js";
@@ -50,6 +51,29 @@ export {
 	visaGuard,
 } from "./guard.js";
 export { introspect, revoke, verifyAccessToken } from "./introspect.js";
+export {
+	assertResourceIdentifier,
+	type ChallengeOptions,
+	PROTECTED_RESOURCE_PATH,
+	type ProtectedResourceMetadata,
+	type ProtectedResourceOptions,
+	protectedResourceMetadata,
+	protectedResourceMetadataUrl,
+	wwwAuthenticate,
+} from "./protectedResource.js";
+export {
+	type ClientRegistrationRequest,
+	type ClientRegistrationResponse,
+	type RegistrationOptions,
+	registrationResponse,
+	validateRegistration,
+} from "./register.js";
+export {
+	audienceAllows,
+	narrowResources,
+	readResourceParameter,
+	validateResources,
+} from "./resource.js";
 export {
 	clearVisa,
 	default as visa,
@@ -68,6 +92,7 @@ export { type TokenOptions, type TokenRequest, token } from "./token.js";
 export type {
 	AccessToken,
 	AuthorizationCode,
+	AuthorizedApplication,
 	Client,
 	ClientAuthMethod,
 	Consent,

package/src/introspect.ts

@@ -10,6 +10,7 @@
 import { authenticateClient, type ClientCredentials } from "./clients.js";
 import { hashSecret } from "./crypto.js";
 import { OAuthError } from "./errors.js";
+import { audienceAllows } from "./resource.js";
 import type { VisaStore } from "./store.js";
 import type { IntrospectionResponse } from "./types.js";
 
@@ -55,6 +56,9 @@ export async function introspect(
 			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 }),
 		};
 	}
 
@@ -125,16 +129,28 @@ export async function verifyAccessToken(
 	// not have to implement eleven methods it never calls.
 	store: Pick<VisaStore, "findAccessToken">,
 	now: Date = 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?: string,
 ): Promise<{
 	clientId: string;
 	userId?: string;
 	scopes: string[];
 	expiresAt: Date;
 	lastUsedAt?: Date;
+	audience?: string[];
 } | null> {
 	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 }),
@@ -145,6 +161,7 @@ export async function verifyAccessToken(
 		// 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 }),
 	};
 }
 

package/src/protectedResource.ts

@@ -0,0 +1,171 @@
+/**
+ * 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 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: string): string {
+	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: ProtectedResourceOptions,
+): ProtectedResourceMetadata {
+	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 }),
+	};
+}
+
+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 function wwwAuthenticate(options: ChallengeOptions = {}): string {
+	const metadataUrl =
+		options.resourceMetadata ??
+		(options.resource === undefined
+			? undefined
+			: protectedResourceMetadataUrl(options.resource));
+
+	const parameters: Array<[string, string]> = [];
+	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: string, parameter: string): string {
+	// 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: string): void {
+	let url: 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}`);
+	}
+}

package/src/register.ts

@@ -0,0 +1,296 @@
+/**
+ * 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";
+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;
+}
+
+const DEFAULT_GRANTS: readonly GrantType[] = [
+	"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: ClientRegistrationRequest,
+	options: RegistrationOptions,
+	presentedToken?: string,
+): {
+	redirectUris: string[];
+	grantTypes: GrantType[];
+	scopes: string[];
+	tokenEndpointAuthMethod: ClientAuthMethod;
+	name: string;
+} {
+	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: Client,
+	issuedAt: Date,
+	secret: string | undefined,
+	options: RegistrationOptions,
+): ClientRegistrationResponse {
+	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: unknown,
+	options: RegistrationOptions,
+): GrantType[] {
+	const allowed = options.grantTypes ?? DEFAULT_GRANTS;
+	const requested = readStringList(value);
+	if (requested.length === 0) return [...allowed];
+	const grants: GrantType[] = [];
+	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: string): void {
+	let url: 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: unknown): string[] {
+	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): entry is string => typeof entry === "string");
+}
+
+function readScope(value: unknown): string[] {
+	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: unknown): ClientAuthMethod {
+	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: unknown): string {
+	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: string): value is GrantType {
+	return (
+		value === "authorization_code" ||
+		value === "refresh_token" ||
+		value === "client_credentials"
+	);
+}