@c9up/visa 0.1.0

package/src/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Visa — an OAuth 2.1 authorization server.
+ *
+ * It issues tokens to OTHER applications on a user's behalf. Knowing who that
+ * user is stays warden's job; visa never authenticates anyone, it only asks
+ * the application who is signed in.
+ *
+ * Nothing here depends on a transport or on a database: the manager takes
+ * values and returns values, the store is a contract. The HTTP endpoints are
+ * in the provider.
+ */
+
+import "./augmentations.js";
+
+export {
+	type AuthorizationRequest,
+	type AuthorizeOptions,
+	errorRedirect,
+	issueAuthorizationCode,
+	successRedirect,
+	UnredirectableError,
+	type ValidatedRequest,
+	validateAuthorizationRequest,
+} from "./authorize.js";
+export {
+	assertGrantAllowed,
+	authenticateClient,
+	type ClientCredentials,
+	readCredentials,
+	redirectUriMatches,
+	resolveScopes,
+} from "./clients.js";
+export { defineConfig, type VisaConfigInput } from "./config.js";
+export { hashSecret, randomToken, secretMatches, sha256 } from "./crypto.js";
+export {
+	type AuthorizationErrorCode,
+	OAuthError,
+	type ProtocolErrorCode,
+	type TokenErrorCode,
+	VisaError,
+} from "./errors.js";
+export { introspect, revoke, verifyAccessToken } from "./introspect.js";
+export {
+	clearVisa,
+	default as visa,
+	getVisa,
+	setVisa,
+} from "./services/main.js";
+export type { VisaStore } from "./store.js";
+export { MemoryStore } from "./stores/memory.js";
+export { type TokenOptions, type TokenRequest, token } from "./token.js";
+export type {
+	AccessToken,
+	AuthorizationCode,
+	Client,
+	ClientAuthMethod,
+	Consent,
+	GrantType,
+	IntrospectionResponse,
+	RefreshToken,
+	TokenResponse,
+} from "./types.js";
+export {
+	type AuthorizationOutcome,
+	type VisaConfig,
+	VisaManager,
+} from "./VisaManager.js";

package/src/introspect.ts

@@ -0,0 +1,139 @@
+/**
+ * Revocation (RFC 7009) and introspection (RFC 7662).
+ *
+ * Both answer the same way to a token that is unknown, expired, revoked or
+ * belongs to someone else — revocation with 200, introspection with
+ * `{ active: false }`. That uniformity IS the security property: a different
+ * answer per case turns either endpoint into an oracle for guessing tokens.
+ */
+
+import { authenticateClient, type ClientCredentials } from "./clients.js";
+import { hashSecret } from "./crypto.js";
+import { OAuthError } from "./errors.js";
+import type { VisaStore } from "./store.js";
+import type { IntrospectionResponse } from "./types.js";
+
+/** `{ active: false }` — the only thing an inactive token ever reveals. */
+const INACTIVE: IntrospectionResponse = { active: false };
+
+export async function introspect(
+	request: Record<string, unknown>,
+	credentials: ClientCredentials,
+	store: VisaStore,
+	now: Date = new Date(),
+	issuer?: string,
+): Promise<IntrospectionResponse> {
+	// The CALLER authenticates — introspection tells you whether a credential
+	// is live, which is exactly what an attacker wants to ask.
+	const caller = await authenticateClient(credentials, (id) =>
+		store.findClient(id),
+	);
+	const presented = asString(request.token);
+	if (presented === undefined) {
+		throw new OAuthError("invalid_request", "token is required.");
+	}
+
+	const hash = hashSecret(presented);
+	const hint =
+		asString(request.token_hint) ?? asString(request.token_type_hint);
+
+	// The hint is an optimisation, never a filter: a wrong hint must still
+	// find the token (RFC 7662 §2.1).
+	const access =
+		hint === "refresh_token" ? null : await store.findAccessToken(hash);
+	if (access !== null) {
+		if (access.revokedAt !== undefined || access.expiresAt <= now) {
+			return INACTIVE;
+		}
+		// A client may only introspect its own tokens.
+		if (access.clientId !== caller.id) return INACTIVE;
+		return {
+			active: true,
+			...(issuer === undefined ? {} : { iss: issuer }),
+			scope: access.scopes.join(" "),
+			client_id: access.clientId,
+			token_type: "Bearer",
+			exp: Math.floor(access.expiresAt.getTime() / 1000),
+			...(access.userId === undefined ? {} : { sub: access.userId }),
+		};
+	}
+
+	const refresh = await store.findRefreshToken(hash);
+	if (refresh === null) return INACTIVE;
+	if (
+		refresh.revokedAt !== undefined ||
+		refresh.consumedAt !== undefined ||
+		refresh.expiresAt <= now ||
+		refresh.clientId !== caller.id
+	) {
+		return INACTIVE;
+	}
+	return {
+		active: true,
+		...(issuer === undefined ? {} : { iss: issuer }),
+		scope: refresh.scopes.join(" "),
+		client_id: refresh.clientId,
+		exp: Math.floor(refresh.expiresAt.getTime() / 1000),
+		...(refresh.userId === undefined ? {} : { sub: refresh.userId }),
+	};
+}
+
+/**
+ * Revoke a token. Answers nothing, always successfully (RFC 7009 §2.2).
+ *
+ * Revoking a REFRESH token takes its whole family with it, access tokens
+ * included: "sign me out" has to mean the session is over, not that one of
+ * its two credentials was retired.
+ */
+export async function revoke(
+	request: Record<string, unknown>,
+	credentials: ClientCredentials,
+	store: VisaStore,
+	now: Date = new Date(),
+): Promise<void> {
+	const caller = await authenticateClient(credentials, (id) =>
+		store.findClient(id),
+	);
+	const presented = asString(request.token);
+	if (presented === undefined) {
+		throw new OAuthError("invalid_request", "token is required.");
+	}
+	const hash = hashSecret(presented);
+
+	const refresh = await store.findRefreshToken(hash);
+	if (refresh !== null) {
+		// Someone else's token: nothing happens, and they are not told so.
+		if (refresh.clientId !== caller.id) return;
+		await store.revokeFamily(refresh.familyId, now);
+		return;
+	}
+
+	const access = await store.findAccessToken(hash);
+	if (access === null || access.clientId !== caller.id) return;
+	await store.revokeAccessToken(hash, now);
+}
+
+/**
+ * Is this bearer token good, and for what?
+ *
+ * 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: string,
+	store: VisaStore,
+	now: Date = new Date(),
+): Promise<{ clientId: string; userId?: string; scopes: string[] } | null> {
+	const token = await store.findAccessToken(hashSecret(presented));
+	if (token === null) return null;
+	if (token.revokedAt !== undefined || token.expiresAt <= now) return null;
+	return {
+		clientId: token.clientId,
+		...(token.userId === undefined ? {} : { userId: token.userId }),
+		scopes: token.scopes,
+	};
+}
+
+function asString(value: unknown): string | undefined {
+	return typeof value === "string" && value !== "" ? value : undefined;
+}

package/src/services/main.ts

@@ -0,0 +1,57 @@
+/**
+ * Container service accessor — `import visa from '@c9up/visa/services/main'`.
+ *
+ * Populated by `VisaProvider.boot()`. Reading it before the provider booted
+ * throws rather than answering with a half-built server: an authorization
+ * server with no store would mint tokens nobody can verify.
+ */
+
+import type { VisaManager } from "../VisaManager.js";
+
+let instance: VisaManager | undefined;
+
+/** @internal Called by the provider once the manager exists. */
+export function setVisa(manager: VisaManager): void {
+	instance = manager;
+}
+
+/** @internal Read the seated manager, if there is one. */
+export function getVisa(): VisaManager | undefined {
+	return instance;
+}
+
+/**
+ * @internal Forget the manager — the provider on shutdown, tests between cases.
+ *
+ * The caller checks ownership first (`getVisa() === mine`): two applications
+ * share this module in one process, and the one shutting down must not clear a
+ * manager the other has since seated.
+ */
+export function clearVisa(): void {
+	instance = undefined;
+}
+
+function resolve(): VisaManager {
+	if (!instance) {
+		throw new Error(
+			"[visa] accessed before initialization — register VisaProvider, or call setVisa() yourself.",
+		);
+	}
+	return instance;
+}
+
+/**
+ * A proxy so the import can be held before the provider boots.
+ *
+ * Symbols and `then` answer undefined: a module namespace is probed for `then`
+ * when it is imported, and a proxy that threw there would crash the import.
+ */
+const visa = new Proxy({} as VisaManager, {
+	get(_target, property) {
+		if (typeof property === "symbol" || property === "then") return undefined;
+		const value = Reflect.get(resolve(), property);
+		return typeof value === "function" ? value.bind(resolve()) : value;
+	},
+}) as VisaManager;
+
+export default visa;

package/src/store.ts

@@ -0,0 +1,56 @@
+/**
+ * What the server needs from wherever its state lives.
+ *
+ * A contract rather than a table, the same way echo, eclipse and bay do it:
+ * an application already running atlas gets a driver, one running on Redis or
+ * on a schema it does not own writes twelve methods.
+ *
+ * Every method that takes a credential takes it HASHED. The plaintext never
+ * reaches the store, so a database dump is not a set of working tokens.
+ */
+
+import type {
+	AccessToken,
+	AuthorizationCode,
+	Client,
+	Consent,
+	RefreshToken,
+} from "./types.js";
+
+export interface VisaStore {
+	findClient(id: string): Promise<Client | null>;
+
+	saveAuthorizationCode(code: AuthorizationCode): Promise<void>;
+	findAuthorizationCode(codeHash: string): Promise<AuthorizationCode | null>;
+	/**
+	 * Mark a code as used. MUST be atomic against a concurrent exchange: two
+	 * requests racing with the same code must not both succeed, which is the
+	 * whole of the single-use guarantee (§7.5.1).
+	 *
+	 * Answers `false` when it was already consumed.
+	 */
+	consumeAuthorizationCode(codeHash: string, at: Date): Promise<boolean>;
+
+	saveAccessToken(token: AccessToken): Promise<void>;
+	findAccessToken(tokenHash: string): Promise<AccessToken | null>;
+	revokeAccessToken(tokenHash: string, at: Date): Promise<void>;
+
+	saveRefreshToken(token: RefreshToken): Promise<void>;
+	findRefreshToken(tokenHash: string): Promise<RefreshToken | null>;
+	/** Same atomicity requirement as a code: rotation depends on it. */
+	consumeRefreshToken(tokenHash: string, at: Date): Promise<boolean>;
+	/**
+	 * Revoke every token of a family, refresh and access alike.
+	 *
+	 * Called when a consumed refresh token comes back: that is a leak, and the
+	 * only safe answer is to end the session it belongs to rather than guess
+	 * which of the two holders is the thief.
+	 */
+	revokeFamily(familyId: string, at: Date): Promise<void>;
+
+	findConsent(userId: string, clientId: string): Promise<Consent | null>;
+	saveConsent(consent: Consent): Promise<void>;
+
+	/** Drop what has expired. Optional: a store with a TTL does it itself. */
+	prune?(now: Date): Promise<void>;
+}

package/src/stores/memory.ts

@@ -0,0 +1,118 @@
+/**
+ * The store that needs no database.
+ *
+ * For tests and for a single-process development server — never for
+ * production, where a restart would sign every user out and a second instance
+ * would not see the first one's tokens.
+ *
+ * It is also the reference implementation of the contract: the atomicity the
+ * interface demands is trivially true here, in one event loop, which is
+ * exactly why a driver on a real database has to say how it achieves it.
+ */
+
+import type { VisaStore } from "../store.js";
+import type {
+	AccessToken,
+	AuthorizationCode,
+	Client,
+	Consent,
+	RefreshToken,
+} from "../types.js";
+
+export class MemoryStore implements VisaStore {
+	readonly #clients = new Map<string, Client>();
+	readonly #codes = new Map<string, AuthorizationCode>();
+	readonly #accessTokens = new Map<string, AccessToken>();
+	readonly #refreshTokens = new Map<string, RefreshToken>();
+	readonly #consents = new Map<string, Consent>();
+
+	constructor(clients: readonly Client[] = []) {
+		for (const client of clients) this.#clients.set(client.id, client);
+	}
+
+	/** Register a client. Returns it, so a caller can keep the reference. */
+	addClient(client: Client): Client {
+		this.#clients.set(client.id, client);
+		return client;
+	}
+
+	async findClient(id: string): Promise<Client | null> {
+		return this.#clients.get(id) ?? null;
+	}
+
+	async saveAuthorizationCode(code: AuthorizationCode): Promise<void> {
+		this.#codes.set(code.codeHash, code);
+	}
+
+	async findAuthorizationCode(
+		codeHash: string,
+	): Promise<AuthorizationCode | null> {
+		return this.#codes.get(codeHash) ?? null;
+	}
+
+	async consumeAuthorizationCode(codeHash: string, at: Date): Promise<boolean> {
+		const code = this.#codes.get(codeHash);
+		if (code === undefined || code.consumedAt !== undefined) return false;
+		code.consumedAt = at;
+		return true;
+	}
+
+	async saveAccessToken(token: AccessToken): Promise<void> {
+		this.#accessTokens.set(token.tokenHash, token);
+	}
+
+	async findAccessToken(tokenHash: string): Promise<AccessToken | null> {
+		return this.#accessTokens.get(tokenHash) ?? null;
+	}
+
+	async revokeAccessToken(tokenHash: string, at: Date): Promise<void> {
+		const token = this.#accessTokens.get(tokenHash);
+		if (token !== undefined) token.revokedAt = at;
+	}
+
+	async saveRefreshToken(token: RefreshToken): Promise<void> {
+		this.#refreshTokens.set(token.tokenHash, token);
+	}
+
+	async findRefreshToken(tokenHash: string): Promise<RefreshToken | null> {
+		return this.#refreshTokens.get(tokenHash) ?? null;
+	}
+
+	async consumeRefreshToken(tokenHash: string, at: Date): Promise<boolean> {
+		const token = this.#refreshTokens.get(tokenHash);
+		if (token === undefined || token.consumedAt !== undefined) return false;
+		token.consumedAt = at;
+		return true;
+	}
+
+	async revokeFamily(familyId: string, at: Date): Promise<void> {
+		// Both kinds: a leaked refresh token has usually already bought an
+		// access token, and leaving that one alive defeats the revocation.
+		for (const token of this.#refreshTokens.values()) {
+			if (token.familyId === familyId) token.revokedAt = at;
+		}
+		for (const token of this.#accessTokens.values()) {
+			if (token.familyId === familyId) token.revokedAt = at;
+		}
+	}
+
+	async findConsent(userId: string, clientId: string): Promise<Consent | null> {
+		return this.#consents.get(`${userId}\u0000${clientId}`) ?? null;
+	}
+
+	async saveConsent(consent: Consent): Promise<void> {
+		this.#consents.set(`${consent.userId}\u0000${consent.clientId}`, consent);
+	}
+
+	async prune(now: Date): Promise<void> {
+		for (const [key, code] of this.#codes) {
+			if (code.expiresAt <= now) this.#codes.delete(key);
+		}
+		for (const [key, token] of this.#accessTokens) {
+			if (token.expiresAt <= now) this.#accessTokens.delete(key);
+		}
+		for (const [key, token] of this.#refreshTokens) {
+			if (token.expiresAt <= now) this.#refreshTokens.delete(key);
+		}
+	}
+}

package/src/stubs.ts

@@ -0,0 +1,16 @@
+/**
+ * Where this package's stubs live.
+ *
+ * Its own module, as upstream keeps it: a stub root is a path a package
+ * publishes, and a caller importing it should not have to import the
+ * configure hook to get it.
+ *
+ * `import.meta.dirname` rather than a URL — upstream reads it straight off
+ * `import.meta`, and deriving it from `import.meta.url` breaks wherever that
+ * is not a `file://` URL, which is what a test runner serving modules over
+ * HTTP hands you.
+ */
+
+import { join } from "node:path";
+
+export const stubsRoot = join(import.meta.dirname, "..", "stubs");

package/src/testing/main.ts

@@ -0,0 +1,119 @@
+/**
+ * Test helpers — `import { testVisa } from '@c9up/visa/testing'`.
+ *
+ * Not a fake of the server: the real one, on a memory store. An authorization
+ * server whose test double is lenient teaches applications to ship the leniency
+ * — a consent screen tested against a stub that always grants is a consent
+ * screen nobody has ever seen refuse.
+ *
+ * What it removes is the setup, not the rules: a registered client, a PKCE
+ * pair, and one call that walks authorize → consent → code → token.
+ */
+
+import { randomToken, sha256 } from "../crypto.js";
+import { MemoryStore } from "../stores/memory.js";
+import type { Client, GrantType, TokenResponse } from "../types.js";
+import { type VisaConfig, VisaManager } from "../VisaManager.js";
+
+export interface TestVisa {
+	visa: VisaManager;
+	store: MemoryStore;
+	/** The client that was registered for you. */
+	client: Client;
+	/** Its secret, in the clear — it exists only in this process. */
+	secret: string;
+	/** Credentials shaped the way the endpoints take them. */
+	credentials: { clientId: string; clientSecret?: string };
+	/** A fresh PKCE pair. */
+	pkce(): { verifier: string; challenge: string };
+	/**
+	 * Everything at once: authorize as `userId`, consent, exchange the code.
+	 * What a test protecting a resource needs, without the four steps.
+	 */
+	tokensFor(userId: string, scope?: string): Promise<TokenResponse>;
+}
+
+export interface TestVisaOptions {
+	issuer?: string;
+	clientId?: string;
+	redirectUri?: string;
+	scopes?: string[];
+	grantTypes?: GrantType[];
+	/** A public client: no secret, and no client_credentials. */
+	publicClient?: boolean;
+	config?: Partial<Omit<VisaConfig, "issuer" | "store">>;
+}
+
+export async function testVisa(
+	options: TestVisaOptions = {},
+): Promise<TestVisa> {
+	const redirectUri = options.redirectUri ?? "https://app.test/callback";
+	const store = new MemoryStore();
+	const visa = new VisaManager({
+		issuer: options.issuer ?? "https://auth.test",
+		store,
+		...options.config,
+	});
+	const { client, secret } = await visa.registerClient({
+		id: options.clientId ?? "test-client",
+		name: "Test client",
+		redirectUris: [redirectUri],
+		scopes: options.scopes ?? ["profile", "email"],
+		grantTypes: options.grantTypes ?? ["authorization_code", "refresh_token"],
+		...(options.publicClient === true
+			? { tokenEndpointAuthMethod: "none" as const }
+			: {}),
+	});
+
+	const credentials =
+		secret === undefined
+			? { clientId: client.id }
+			: { clientId: client.id, clientSecret: secret };
+
+	return {
+		visa,
+		store,
+		client,
+		secret: secret ?? "",
+		credentials,
+		pkce() {
+			const verifier = randomToken();
+			return { verifier, challenge: sha256(verifier) };
+		},
+		async tokensFor(userId: string, scope?: string): Promise<TokenResponse> {
+			const verifier = randomToken();
+			const outcome = await visa.authorize(
+				{
+					response_type: "code",
+					client_id: client.id,
+					redirect_uri: redirectUri,
+					code_challenge: sha256(verifier),
+					code_challenge_method: "S256",
+					...(scope === undefined ? {} : { scope }),
+				},
+				userId,
+			);
+			// The real path, consent screen included — a helper that skipped it
+			// would let an application forget the screen and still pass.
+			const url =
+				outcome.type === "consent"
+					? await visa.grant(outcome.request, userId)
+					: outcome.type === "redirect"
+						? outcome.url
+						: (() => {
+								throw new Error(`authorize failed: ${outcome.error.message}`);
+							})();
+			const code = new URL(url).searchParams.get("code");
+			if (code === null) throw new Error(`no code in ${url}`);
+			return visa.token(
+				{
+					grant_type: "authorization_code",
+					code,
+					redirect_uri: redirectUri,
+					code_verifier: verifier,
+				},
+				credentials,
+			);
+		},
+	};
+}