@c9up/visa 0.1.1 → 0.1.3

package/src/VisaManager.ts

@@ -24,9 +24,18 @@ import {
 import { hashSecret, randomToken } from "./crypto.js";
 import { OAuthError, VisaError } from "./errors.js";
 import { introspect, revoke, verifyAccessToken } from "./introspect.js";
+import {
+	type ClientRegistrationRequest,
+	type ClientRegistrationResponse,
+	type RegistrationOptions,
+	registrationResponse,
+	secretExpiryFor,
+	validateRegistration,
+} from "./register.js";
 import type { VisaStore } from "./store.js";
 import { type TokenOptions, token } from "./token.js";
 import type {
+	AuthorizedApplication,
 	Client,
 	ClientAuthMethod,
 	GrantType,
@@ -38,6 +47,8 @@ export interface VisaConfig extends AuthorizeOptions, TokenOptions {
 	/** Where this server lives — `https://auth.example.com`. */
 	issuer: string;
 	store: VisaStore;
+	/** Whether clients may register themselves, and on what terms (RFC 7591). */
+	registration?: RegistrationOptions;
 }
 
 /** What `authorize()` decided. */
@@ -85,6 +96,8 @@ export class VisaManager {
 		scopes?: string[];
 		tokenEndpointAuthMethod?: ClientAuthMethod;
 		trusted?: boolean;
+		/** When the issued secret stops working. Omitted means it does not. */
+		secretExpiresAt?: Date;
 	}): Promise<{ client: Client; secret?: string }> {
 		// Refused at registration, not at the first authorization request: a
 		// URI that cannot be parsed would otherwise throw out of
@@ -102,6 +115,11 @@ export class VisaManager {
 			tokenEndpointAuthMethod: method,
 			...(input.trusted === undefined ? {} : { trusted: input.trusted }),
 			...(secret === undefined ? {} : { secretHash: hashSecret(secret) }),
+			// Only alongside a secret: an expiry on a client that has none is a
+			// date nothing would ever read.
+			...(secret === undefined || input.secretExpiresAt === undefined
+				? {}
+				: { secretExpiresAt: input.secretExpiresAt }),
 		};
 		const store = this.#config.store;
 		if (!("addClient" in store) || typeof store.addClient !== "function") {
@@ -117,6 +135,37 @@ export class VisaManager {
 		return secret === undefined ? { client } : { client, secret };
 	}
 
+	/**
+	 * A client registering itself (RFC 7591).
+	 *
+	 * Refused unless the application turned registration on. What comes back is
+	 * the 201 body, secret included — the one time it exists.
+	 */
+	async register(
+		request: ClientRegistrationRequest,
+		presentedToken?: string,
+		now: Date = new Date(),
+	): Promise<ClientRegistrationResponse> {
+		const options = this.#config.registration ?? {};
+		const metadata = validateRegistration(request, options, presentedToken);
+		// Computed once, here: the same value is stored on the client and
+		// answered in the 201 body, so the server cannot announce an expiry it
+		// does not enforce.
+		const secretExpiresAt = secretExpiryFor(now, options.secretTtlSeconds);
+		const { client, secret } = await this.registerClient({
+			// The id is ours to choose: a client naming itself could claim one
+			// that already exists and read another application's tokens.
+			id: randomToken(),
+			name: metadata.name,
+			redirectUris: metadata.redirectUris,
+			grantTypes: metadata.grantTypes,
+			scopes: metadata.scopes,
+			tokenEndpointAuthMethod: metadata.tokenEndpointAuthMethod,
+			...(secretExpiresAt === undefined ? {} : { secretExpiresAt }),
+		});
+		return registrationResponse(client, now, secret);
+	}
+
 	/**
 	 * Step one: check the request, and decide what happens to the user.
 	 *
@@ -229,12 +278,82 @@ export class VisaManager {
 		return revoke(body, credentials, this.#config.store, now);
 	}
 
-	/** What a resource server calls on every request. */
+	/**
+	 * What a resource server calls on every request.
+	 *
+	 * `resource` is this server's own identifier (RFC 8707): given, a token
+	 * minted for a different one is refused here rather than honoured.
+	 */
 	async verify(
 		presented: string,
 		now: Date = new Date(),
-	): Promise<{ clientId: string; userId?: string; scopes: string[] } | null> {
-		return verifyAccessToken(presented, this.#config.store, now);
+		resource?: string,
+	): ReturnType<typeof verifyAccessToken> {
+		return verifyAccessToken(presented, this.#config.store, now, resource);
+	}
+
+	/**
+	 * Every application this user has authorised.
+	 *
+	 * What a "connected applications" screen renders. Includes an application
+	 * whose tokens have all expired: "last used" matters most when nothing is
+	 * live any more, and hiding it would tell someone an application never
+	 * touched their data when it did.
+	 */
+	async listAuthorizations(
+		userId: string,
+		now: Date = new Date(),
+	): Promise<AuthorizedApplication[]> {
+		const store = this.#config.store;
+		const consents = await store.listConsents(userId);
+		const tokens = await store.listAccessTokens(userId);
+
+		return Promise.all(
+			consents.map(async (consent) => {
+				const mine = tokens.filter(
+					(token) => token.clientId === consent.clientId,
+				);
+				const client = await store.findClient(consent.clientId);
+				const lastUsedAt = mine.reduce<Date | undefined>((latest, token) => {
+					if (token.lastUsedAt === undefined) return latest;
+					if (latest === undefined) return token.lastUsedAt;
+					return token.lastUsedAt > latest ? token.lastUsedAt : latest;
+				}, undefined);
+
+				return {
+					clientId: consent.clientId,
+					// A client that has since been deleted still shows, under its id:
+					// the grant is the user's and they must be able to end it.
+					name: client?.name ?? consent.clientId,
+					scopes: consent.scopes,
+					grantedAt: consent.grantedAt,
+					...(lastUsedAt === undefined ? {} : { lastUsedAt }),
+					active: mine.some(
+						(token) => token.revokedAt === undefined && token.expiresAt > now,
+					),
+				};
+			}),
+		);
+	}
+
+	/**
+	 * End one application's access for one user.
+	 *
+	 * Tokens first, consent second, and deliberately in that order: someone
+	 * revoking in a hurry wants the sessions dead, and a failure half-way
+	 * through must not leave an application still holding live tokens with the
+	 * grant already forgotten.
+	 *
+	 * Both kinds of token go — revoking only the refresh half would leave the
+	 * access token it already bought alive for its full lifetime.
+	 */
+	async revokeAuthorization(
+		userId: string,
+		clientId: string,
+		now: Date = new Date(),
+	): Promise<void> {
+		await this.#config.store.revokeAccessFor(userId, clientId, now);
+		await this.#config.store.deleteConsent(userId, clientId);
 	}
 
 	/** Read credentials out of a request, both places the spec allows. */

package/src/VisaProvider.ts

@@ -19,6 +19,11 @@
 import "./augmentations.js";
 import type { VisaConfigInput } from "./config.js";
 import { OAuthError } from "./errors.js";
+import {
+	PROTECTED_RESOURCE_PATH,
+	protectedResourceMetadata,
+	protectedResourceMetadataUrl,
+} from "./protectedResource.js";
 import { clearVisa, getVisa, setVisa } from "./services/main.js";
 import { VisaManager } from "./VisaManager.js";
 
@@ -132,6 +137,24 @@ export default class VisaProvider {
 			});
 		});
 
+		// RFC 7591 — a client that registers itself. Mounted only when the
+		// application turned it on: an authorization server quietly accepting
+		// registrations is a thing nobody asked for.
+		if (config?.registration?.enabled === true) {
+			router.post(`${prefix}/register`, async (ctx) => {
+				await this.#answer(ctx, async () => {
+					const bearer = readBearer(ctx);
+					const created = await manager.register(ctx.request.all(), bearer);
+					// §3.2.1: 201, and the body carries a secret — no cache may
+					// keep it.
+					ctx.response.status(201);
+					ctx.response.header("cache-control", "no-store");
+					ctx.response.header("pragma", "no-cache");
+					return created;
+				});
+			});
+		}
+
 		// RFC 8414 — what a client fetches to discover the endpoints.
 		router.get("/.well-known/oauth-authorization-server", async (ctx) => {
 			ctx.response.header("content-type", "application/json");
@@ -150,6 +173,9 @@ export default class VisaProvider {
 				// S256 only unless the application turned `plain` back on.
 				code_challenge_methods_supported:
 					config?.allowPlainChallenge === true ? ["S256", "plain"] : ["S256"],
+				...(config?.registration?.enabled === true
+					? { registration_endpoint: `${manager.issuer}${prefix}/register` }
+					: {}),
 				token_endpoint_auth_methods_supported: [
 					"client_secret_basic",
 					"client_secret_post",
@@ -157,6 +183,34 @@ export default class VisaProvider {
 				],
 			});
 		});
+
+		// RFC 9728 — what a client fetches after a 401 to learn where tokens
+		// come from. Mounted only when the application named its resource: a
+		// document announcing a resource nobody declared would point clients at
+		// something that does not exist.
+		const protectedResource = config?.protectedResource;
+		if (protectedResource !== undefined) {
+			const document = protectedResourceMetadata({
+				...protectedResource,
+				authorizationServers: [manager.issuer],
+			});
+			router.get(PROTECTED_RESOURCE_PATH, async (ctx) => {
+				ctx.response.header("content-type", "application/json");
+				ctx.response.send(document);
+			});
+			// §3: the well-known segment goes BETWEEN the host and the resource's
+			// path, so a resource at `/mcp` publishes at `…/oauth-protected-
+			// resource/mcp`. Both are served: a client may ask for either.
+			const withPath = new URL(
+				protectedResourceMetadataUrl(protectedResource.resource),
+			).pathname;
+			if (withPath !== PROTECTED_RESOURCE_PATH) {
+				router.get(withPath, async (ctx) => {
+					ctx.response.header("content-type", "application/json");
+					ctx.response.send(document);
+				});
+			}
+		}
 	}
 
 	async shutdown(): Promise<void> {
@@ -191,6 +245,16 @@ export default class VisaProvider {
 	}
 }
 
+/** The initial access token a registration may carry (RFC 7591 §3). */
+function readBearer(ctx: VisaHttpContext): string | undefined {
+	const header = ctx.request.header("authorization");
+	if (header === undefined) return undefined;
+	const [scheme, value] = header.split(" ");
+	if (scheme?.toLowerCase() !== "bearer" || value === undefined)
+		return undefined;
+	return value;
+}
+
 function readAuthorization(ctx: VisaHttpContext): { authorization?: string } {
 	const header = ctx.request.header("authorization");
 	return header === undefined ? {} : { authorization: header };

package/src/authorize.ts

@@ -15,6 +15,7 @@ import {
 } from "./clients.js";
 import { hashSecret, randomToken } from "./crypto.js";
 import { OAuthError } from "./errors.js";
+import { readResourceParameter, validateResources } from "./resource.js";
 import type { VisaStore } from "./store.js";
 import type { AuthorizationCode, Client } from "./types.js";
 
@@ -30,6 +31,13 @@ export interface AuthorizationRequest {
 	nonce?: string;
 	/** A client may ask to always see the consent screen. */
 	prompt?: string;
+	/**
+	 * Which resource the token is for (RFC 8707). One, or several.
+	 *
+	 * A parser hands repeated parameters over as an array, so both shapes are
+	 * accepted rather than one being silently the only one that works.
+	 */
+	resource?: string | string[];
 }
 
 /** A request that passed every check, with the values it resolved to. */
@@ -41,6 +49,8 @@ export interface ValidatedRequest {
 	codeChallenge: string;
 	codeChallengeMethod: "S256" | "plain";
 	nonce: string | undefined;
+	/** The resources the token will be bound to (RFC 8707). Empty means unbound. */
+	resources: string[];
 }
 
 /**
@@ -61,6 +71,15 @@ export class UnredirectableError extends Error {
 export interface AuthorizeOptions {
 	/** Lifetime of the code. Short on purpose — see `issueAuthorizationCode`. */
 	codeTtlSeconds?: number;
+	/**
+	 * The resources this server will issue tokens for (RFC 8707).
+	 *
+	 * Left out, any well-formed resource is accepted and carried — which is
+	 * useful while a deployment finds its names, and worth replacing with the
+	 * list once it has: an unknown resource should be refused with
+	 * `invalid_target` rather than minted for.
+	 */
+	resourcesSupported?: readonly string[];
 	/**
 	 * Accept `plain` as a code challenge method.
 	 *
@@ -119,6 +138,10 @@ export async function validateAuthorizationRequest(
 		options,
 	);
 	const scopes = resolveScopes(request.scope, client);
+	const resources = validateResources(
+		readResourceParameter(request.resource),
+		options.resourcesSupported,
+	);
 
 	return {
 		client,
@@ -128,6 +151,7 @@ export async function validateAuthorizationRequest(
 		codeChallenge,
 		codeChallengeMethod,
 		nonce: request.nonce,
+		resources,
 	};
 }
 
@@ -215,6 +239,9 @@ export async function issueAuthorizationCode(
 		codeChallengeMethod: validated.codeChallengeMethod,
 		expiresAt: new Date(now.getTime() + ttl * 1000),
 		...(validated.nonce === undefined ? {} : { nonce: validated.nonce }),
+		...(validated.resources.length === 0
+			? {}
+			: { resources: validated.resources }),
 	};
 	await store.saveAuthorizationCode(record);
 	return code;

package/src/clients.ts

@@ -157,6 +157,7 @@ function stringOrUndefined(value: unknown): string | undefined {
 export async function authenticateClient(
 	credentials: ClientCredentials,
 	load: (id: string) => Promise<Client | null>,
+	now: Date = new Date(),
 ): Promise<Client> {
 	if (credentials.clientId === undefined) {
 		throw new OAuthError("invalid_client", "Client authentication failed.");
@@ -192,6 +193,15 @@ export async function authenticateClient(
 	) {
 		throw new OAuthError("invalid_client", "Client authentication failed.");
 	}
+
+	// Registration may have answered `client_secret_expires_at`. This is where
+	// that answer becomes true: checked after the secret matched, so a wrong
+	// secret and an expired one are still the same sentence to the caller.
+	// Every endpoint that authenticates a client — token, introspection,
+	// revocation — arrives here, so one check covers all three.
+	if (client.secretExpiresAt !== undefined && client.secretExpiresAt <= now) {
+		throw new OAuthError("invalid_client", "Client authentication failed.");
+	}
 	return client;
 }
 

package/src/config.ts

@@ -3,6 +3,7 @@
  * provider reads out of the config store.
  */
 
+import type { RegistrationOptions } from "./register.js";
 import type { VisaStore } from "./store.js";
 
 export interface VisaConfigInput {
@@ -27,6 +28,40 @@ export interface VisaConfigInput {
 	allowPlainChallenge?: boolean;
 	/** Where the endpoints are mounted. Default `/oauth`. */
 	prefix?: string;
+	/**
+	 * The resources this server issues tokens for (RFC 8707).
+	 *
+	 * Left out, any well-formed `resource` is accepted and carried. Named, an
+	 * unknown one is refused with `invalid_target` — which is what stops a
+	 * client asking for a token aimed at a server you do not run.
+	 */
+	resourcesSupported?: string[];
+	/**
+	 * Let clients register themselves (RFC 7591).
+	 *
+	 * OFF unless you say otherwise. An MCP client such as claude.ai has nobody
+	 * to fill in a form for it, so it needs this; a server on the public
+	 * internet with it open lets anyone create a client, so think about
+	 * `initialAccessToken` before shipping one.
+	 */
+	registration?: RegistrationOptions;
+	/**
+	 * The protected resource this server issues tokens for (RFC 9728).
+	 *
+	 * Declare it and two things follow: the metadata document is served at
+	 * `/.well-known/oauth-protected-resource`, and a refusal can name it. An
+	 * MCP client walks from the 401 to that document to this server without
+	 * anybody pasting a URL into a config file, which is the whole reason the
+	 * RFC exists.
+	 */
+	protectedResource?: {
+		/** The resource identifier — an absolute URI, no fragment. */
+		resource: string;
+		/** What a client may ask for. RECOMMENDED by §3.2. */
+		scopesSupported?: string[];
+		resourceName?: string;
+		resourceDocumentation?: string;
+	};
 }
 
 export function defineConfig(config: VisaConfigInput): VisaConfigInput {

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,10 +340,41 @@ 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();
-		const verified = await verifyAccessToken(presented, store, now);
+		// The resource this guard declares is the resource it enforces. Passing
+		// it is the whole of RFC 8707 on this side: without it a token minted
+		// for another resource server — one the same authorization server also
+		// serves — is honoured here, and the `resource` advertised in the
+		// challenge is a claim nothing backs.
+		const verified = await verifyAccessToken(
+			presented,
+			store,
+			now,
+			this.#config.resource,
+		);
 		if (verified === null) {
 			return { authenticated: false, error: "Invalid or expired access token" };
 		}

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 }),
 	};
 }