@c9up/visa 0.1.0 → 0.1.2

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 }),
 		};
 	}
 
@@ -121,16 +125,43 @@ export async function revoke(
  */
 export async function verifyAccessToken(
 	presented: string,
-	store: VisaStore,
+	// Only the one read: a resource server that keeps nothing but tokens should
+	// not have to implement eleven methods it never calls.
+	store: Pick<VisaStore, "findAccessToken">,
 	now: Date = new Date(),
-): Promise<{ clientId: string; userId?: string; scopes: string[] } | null> {
+	/**
+	 * 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 }),
 		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 }),
 	};
 }
 

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"
+	);
+}

package/src/resource.ts

@@ -0,0 +1,123 @@
+/**
+ * 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.
+ */
+
+import { OAuthError } from "./errors.js";
+
+/**
+ * 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 function readResourceParameter(value: unknown): string[] {
+	if (value === undefined || value === null) return [];
+	if (Array.isArray(value)) {
+		return value.filter((entry): entry is string => typeof entry === "string");
+	}
+	return typeof value === "string" && value !== "" ? [value] : [];
+}
+
+/**
+ * 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 function validateResources(
+	requested: readonly string[],
+	accepted?: readonly string[],
+): string[] {
+	const resources: string[] = [];
+	for (const value of requested) {
+		let url: URL;
+		try {
+			url = new URL(value);
+		} catch {
+			throw new OAuthError(
+				"invalid_target",
+				`resource must be an absolute URI: ${value}`,
+			);
+		}
+		if (url.hash !== "") {
+			throw new OAuthError(
+				"invalid_target",
+				`resource must not carry a fragment: ${value}`,
+			);
+		}
+		// §2 SHOULD NOT include a query, and recognises that some cases need
+		// one — so it travels rather than being refused or stripped. Stripping
+		// would hand back a token for a resource nobody asked for.
+		if (accepted !== undefined && !accepted.includes(value)) {
+			throw new OAuthError(
+				"invalid_target",
+				`this server does not issue tokens for ${value}`,
+			);
+		}
+		if (!resources.includes(value)) resources.push(value);
+	}
+	return resources;
+}
+
+/**
+ * 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 function narrowResources(
+	requested: readonly string[],
+	granted: readonly string[],
+): string[] {
+	if (requested.length === 0) return [...granted];
+	if (granted.length === 0) {
+		// Nothing was bound at authorization time, so there is nothing to narrow
+		// FROM. Letting the request name one here would mint a token for an
+		// audience the user never saw.
+		throw new OAuthError(
+			"invalid_target",
+			"this grant is not bound to any resource",
+		);
+	}
+	const outside = requested.filter((value) => !granted.includes(value));
+	if (outside.length > 0) {
+		throw new OAuthError(
+			"invalid_target",
+			`this grant does not cover ${outside.join(", ")}`,
+		);
+	}
+	return [...requested];
+}
+
+/**
+ * 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 function audienceAllows(
+	audience: readonly string[] | undefined,
+	resource: string | undefined,
+): boolean {
+	if (audience === undefined || audience.length === 0) return true;
+	if (resource === undefined) return true;
+	return audience.includes(resource);
+}

package/src/store.ts

@@ -51,6 +51,44 @@ export interface VisaStore {
 	findConsent(userId: string, clientId: string): Promise<Consent | null>;
 	saveConsent(consent: Consent): Promise<void>;
 
+	/**
+	 * Everything this user has granted, so they can be shown it.
+	 *
+	 * The consent is the unit a person manages: they authorised an
+	 * application, not a token. Tokens come and go under that decision.
+	 */
+	listConsents(userId: string): Promise<Consent[]>;
+
+	/**
+	 * Every access token of this user, EXPIRED ONES INCLUDED.
+	 *
+	 * Included deliberately: "last used" is most interesting precisely when
+	 * nothing is live any more, and a screen that hid them would tell a user an
+	 * application never touched their data when it did.
+	 */
+	listAccessTokens(userId: string): Promise<AccessToken[]>;
+
+	/**
+	 * Cut one application off for one user: every token, both kinds.
+	 *
+	 * Not the consent — {@link deleteConsent} is separate, because forgetting
+	 * the grant and ending the sessions are two different things and a caller
+	 * revoking in a panic wants the second one first.
+	 */
+	revokeAccessFor(userId: string, clientId: string, at: Date): Promise<void>;
+
+	/** Forget the grant, so the user is asked again next time. */
+	deleteConsent(userId: string, clientId: string): Promise<void>;
+
+	/**
+	 * Record that an access token was just used.
+	 *
+	 * Optional, and deliberately best-effort: it is one write per authenticated
+	 * request, which a store on a hot path may not want. A store without it
+	 * authenticates exactly the same, it simply reports no last use.
+	 */
+	touchAccessToken?(tokenHash: string, at: Date): Promise<void>;
+
 	/** Drop what has expired. Optional: a store with a TTL does it itself. */
 	prune?(now: Date): Promise<void>;
 }