@c9up/visa 0.1.0

package/src/authorize.ts

@@ -0,0 +1,250 @@
+/**
+ * The authorization endpoint.
+ *
+ * It is the half a human sees, and the half where an error must NOT be
+ * redirected: if the redirect URI is missing, unregistered or malformed, the
+ * server tells the user and stops (§4.1.2.1). Bouncing the error to an
+ * unverified URI is how an attacker learns that a client exists and gets a
+ * page of their choosing loaded in the user's session.
+ */
+
+import {
+	assertGrantAllowed,
+	redirectUriMatches,
+	resolveScopes,
+} from "./clients.js";
+import { hashSecret, randomToken } from "./crypto.js";
+import { OAuthError } from "./errors.js";
+import type { VisaStore } from "./store.js";
+import type { AuthorizationCode, Client } from "./types.js";
+
+/** The query as it arrived, untrusted. */
+export interface AuthorizationRequest {
+	response_type?: string;
+	client_id?: string;
+	redirect_uri?: string;
+	scope?: string;
+	state?: string;
+	code_challenge?: string;
+	code_challenge_method?: string;
+	nonce?: string;
+	/** A client may ask to always see the consent screen. */
+	prompt?: string;
+}
+
+/** A request that passed every check, with the values it resolved to. */
+export interface ValidatedRequest {
+	client: Client;
+	redirectUri: string;
+	scopes: string[];
+	state: string | undefined;
+	codeChallenge: string;
+	codeChallengeMethod: "S256" | "plain";
+	nonce: string | undefined;
+}
+
+/**
+ * A failure that cannot be redirected — the user must be told directly.
+ *
+ * Separate from `OAuthError` because the CALLER has to treat it differently:
+ * render a page, never `Location:`.
+ */
+export class UnredirectableError extends Error {
+	readonly error: OAuthError;
+	constructor(error: OAuthError) {
+		super(error.message);
+		this.name = "UnredirectableError";
+		this.error = error;
+	}
+}
+
+export interface AuthorizeOptions {
+	/** Lifetime of the code. Short on purpose — see `issueAuthorizationCode`. */
+	codeTtlSeconds?: number;
+	/**
+	 * Accept `plain` as a code challenge method.
+	 *
+	 * NAMED DEVIATION — the spec allows `plain`; this refuses it by default.
+	 * `plain` puts the verifier in the authorization request, so anything that
+	 * can read that request (a log, a referrer, a proxy) can complete the
+	 * exchange, which is precisely what PKCE exists to stop. Every client that
+	 * can hash can use S256.
+	 */
+	allowPlainChallenge?: boolean;
+}
+
+/**
+ * Check an authorization request. Throws `UnredirectableError` when the error
+ * must not be bounced back, `OAuthError` when it may.
+ */
+export async function validateAuthorizationRequest(
+	request: AuthorizationRequest,
+	store: VisaStore,
+	options: AuthorizeOptions = {},
+): Promise<ValidatedRequest> {
+	// Order matters: everything that decides WHERE an error may go has to be
+	// settled before any error is produced.
+	if (request.client_id === undefined || request.client_id === "") {
+		throw new UnredirectableError(
+			new OAuthError("invalid_request", "client_id is required."),
+		);
+	}
+	const client = await store.findClient(request.client_id);
+	if (client === null) {
+		throw new UnredirectableError(
+			new OAuthError("invalid_request", "Unknown client."),
+		);
+	}
+
+	const redirectUri = resolveRedirectUri(request.redirect_uri, client);
+
+	// From here the redirect URI is verified, so an error may travel back.
+	if (request.response_type !== "code") {
+		throw new OAuthError(
+			request.response_type === undefined
+				? "invalid_request"
+				: "unsupported_response_type",
+			// The implicit grant is gone in 2.1, and `token` is its response
+			// type — saying so beats a blank refusal for whoever is porting.
+			request.response_type === "token"
+				? "The implicit grant is not supported; use response_type=code."
+				: "Only response_type=code is supported.",
+		);
+	}
+
+	assertGrantAllowed(client, "authorization_code");
+
+	const { codeChallenge, codeChallengeMethod } = readChallenge(
+		request,
+		options,
+	);
+	const scopes = resolveScopes(request.scope, client);
+
+	return {
+		client,
+		redirectUri,
+		scopes,
+		state: request.state,
+		codeChallenge,
+		codeChallengeMethod,
+		nonce: request.nonce,
+	};
+}
+
+/**
+ * Which redirect URI this request lands on.
+ *
+ * Omitting it is allowed only when the client registered exactly one — with
+ * two or more, "the first one" would be a choice the server makes on the
+ * client's behalf, and the wrong choice sends the code elsewhere.
+ */
+function resolveRedirectUri(
+	requested: string | undefined,
+	client: Client,
+): string {
+	if (client.redirectUris.length === 0) {
+		throw new UnredirectableError(
+			new OAuthError("invalid_request", "This client has no redirect URI."),
+		);
+	}
+	if (requested === undefined || requested === "") {
+		const only = client.redirectUris[0];
+		if (client.redirectUris.length > 1 || only === undefined) {
+			throw new UnredirectableError(
+				new OAuthError(
+					"invalid_request",
+					"redirect_uri is required when a client registers more than one.",
+				),
+			);
+		}
+		return only;
+	}
+	if (!redirectUriMatches(requested, client.redirectUris)) {
+		throw new UnredirectableError(
+			new OAuthError("invalid_request", "redirect_uri is not registered."),
+		);
+	}
+	return requested;
+}
+
+function readChallenge(
+	request: AuthorizationRequest,
+	options: AuthorizeOptions,
+): { codeChallenge: string; codeChallengeMethod: "S256" | "plain" } {
+	const challenge = request.code_challenge;
+	if (challenge === undefined || challenge === "") {
+		// Mandatory in 2.1 for every client, confidential ones included.
+		throw new OAuthError("invalid_request", "code_challenge is required.");
+	}
+	const method = request.code_challenge_method ?? "plain";
+	if (method === "S256")
+		return { codeChallenge: challenge, codeChallengeMethod: "S256" };
+	if (method === "plain" && options.allowPlainChallenge === true) {
+		return { codeChallenge: challenge, codeChallengeMethod: "plain" };
+	}
+	throw new OAuthError(
+		"invalid_request",
+		"code_challenge_method must be S256.",
+	);
+}
+
+/**
+ * Mint the code, once the user is known and has consented.
+ *
+ * Thirty seconds by default. A code is exchanged by a server the client
+ * controls, milliseconds after the redirect — a long window buys the client
+ * nothing and gives anything that can read a URL (a log, a referrer header, a
+ * shoulder) time to use it.
+ */
+export async function issueAuthorizationCode(
+	validated: ValidatedRequest,
+	userId: string,
+	store: VisaStore,
+	options: AuthorizeOptions = {},
+	now: Date = new Date(),
+): Promise<string> {
+	const code = randomToken();
+	const ttl = options.codeTtlSeconds ?? 30;
+	const record: AuthorizationCode = {
+		codeHash: hashSecret(code),
+		clientId: validated.client.id,
+		userId,
+		redirectUri: validated.redirectUri,
+		scopes: validated.scopes,
+		codeChallenge: validated.codeChallenge,
+		codeChallengeMethod: validated.codeChallengeMethod,
+		expiresAt: new Date(now.getTime() + ttl * 1000),
+		...(validated.nonce === undefined ? {} : { nonce: validated.nonce }),
+	};
+	await store.saveAuthorizationCode(record);
+	return code;
+}
+
+/** Build the redirect a successful authorization ends on. */
+export function successRedirect(
+	validated: ValidatedRequest,
+	code: string,
+): string {
+	const url = new URL(validated.redirectUri);
+	url.searchParams.set("code", code);
+	// Returned verbatim when the client sent one, absent when it did not —
+	// inventing a state would break the client's own CSRF check.
+	if (validated.state !== undefined)
+		url.searchParams.set("state", validated.state);
+	return url.toString();
+}
+
+/** Build the redirect a refused or failed authorization ends on. */
+export function errorRedirect(
+	redirectUri: string,
+	error: OAuthError,
+	state?: string,
+): string {
+	const url = new URL(redirectUri);
+	url.searchParams.set("error", error.code);
+	if (error.description !== undefined) {
+		url.searchParams.set("error_description", error.description);
+	}
+	if (state !== undefined) url.searchParams.set("state", state);
+	return url.toString();
+}

package/src/clients.ts

@@ -0,0 +1,231 @@
+/**
+ * Who is asking, and are they allowed to ask that.
+ *
+ * Three checks live here and each one closes a known attack: the redirect URI
+ * comparison (an open redirect on the client's domain turns into a stolen
+ * code), the client authentication (a leaked client_id is not a credential),
+ * and the scope narrowing (a client must not be able to grant itself more
+ * than it was registered for).
+ */
+
+import { secretMatches } from "./crypto.js";
+import { OAuthError } from "./errors.js";
+import type { Client, ClientAuthMethod, GrantType } from "./types.js";
+
+/**
+ * Does this redirect URI match one the client registered?
+ *
+ * EXACT string comparison, as OAuth 2.1 §2.3.1 requires — with the single
+ * exception it names: a loopback redirect may differ in its port, because a
+ * native app cannot know in advance which port the OS will hand it.
+ *
+ * No prefix matching, no wildcard, no "same origin is close enough": every
+ * one of those has a published attack where the code lands on a URL the
+ * attacker controls.
+ */
+export function redirectUriMatches(
+	candidate: string,
+	registered: readonly string[],
+): boolean {
+	if (registered.includes(candidate)) return true;
+
+	let url: URL;
+	try {
+		url = new URL(candidate);
+	} catch {
+		return false;
+	}
+	if (!isLoopback(url.hostname)) return false;
+
+	return registered.some((entry) => {
+		let known: URL;
+		try {
+			known = new URL(entry);
+		} catch {
+			return false;
+		}
+		if (!isLoopback(known.hostname)) return false;
+		// Everything but the port has to be identical.
+		return (
+			known.protocol === url.protocol &&
+			known.hostname === url.hostname &&
+			known.pathname === url.pathname &&
+			known.search === url.search
+		);
+	});
+}
+
+function isLoopback(hostname: string): boolean {
+	return hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+}
+
+/** Credentials as they arrived, from either place the spec allows. */
+export interface ClientCredentials {
+	clientId?: string;
+	clientSecret?: string;
+	/**
+	 * WHERE they came from.
+	 *
+	 * A client registers one authentication method and must use that one: a
+	 * client declared `client_secret_basic` sending its secret in the body is
+	 * either misconfigured or being replayed by something that could only read
+	 * the body. Accepting both makes the registered method decorative.
+	 */
+	method?: ClientAuthMethod;
+	/** The raw `Authorization` header, if there was one. */
+	authorization?: string;
+}
+
+/**
+ * Read `client_id` / `client_secret` out of a request.
+ *
+ * A client MUST NOT use more than one authentication method in a single
+ * request (§2.4): sending both Basic and body credentials is a sign of a
+ * confused proxy or of an attempt to have one of them ignored, so it is
+ * refused rather than resolved by precedence.
+ */
+export function readCredentials(input: {
+	authorization?: string;
+	body: Record<string, unknown>;
+}): ClientCredentials {
+	const basic = parseBasic(input.authorization);
+	const bodyId = stringOrUndefined(input.body.client_id);
+	const bodySecret = stringOrUndefined(input.body.client_secret);
+
+	if (basic !== undefined && bodySecret !== undefined) {
+		throw new OAuthError(
+			"invalid_request",
+			"More than one client authentication method was used.",
+		);
+	}
+	if (basic !== undefined) {
+		// A body client_id that disagrees with the header is not a mismatch to
+		// resolve — it is two different claims about who is asking.
+		if (bodyId !== undefined && bodyId !== basic.clientId) {
+			throw new OAuthError(
+				"invalid_request",
+				"The client_id in the body does not match the one authenticated.",
+			);
+		}
+		return basic;
+	}
+	return {
+		clientId: bodyId,
+		...(bodySecret === undefined
+			? { method: "none" as const }
+			: { clientSecret: bodySecret, method: "client_secret_post" as const }),
+	};
+}
+
+function parseBasic(header?: string): ClientCredentials | undefined {
+	if (header === undefined) return undefined;
+	const [scheme, encoded] = header.split(" ");
+	if (scheme?.toLowerCase() !== "basic" || encoded === undefined) {
+		return undefined;
+	}
+	const decoded = Buffer.from(encoded, "base64").toString("utf8");
+	const separator = decoded.indexOf(":");
+	if (separator === -1) {
+		throw new OAuthError("invalid_client", "Malformed Basic credentials.");
+	}
+	// RFC 6749 §2.3.1 form-encodes both halves before base64. A malformed
+	// escape throws `URIError`, which would leave the endpoint answering 500
+	// to anything that sends `Basic %zz` — an unauthenticated caller choosing
+	// the failure mode.
+	try {
+		return {
+			clientId: decodeURIComponent(decoded.slice(0, separator)),
+			clientSecret: decodeURIComponent(decoded.slice(separator + 1)),
+			method: "client_secret_basic",
+		};
+	} catch {
+		throw new OAuthError("invalid_client", "Malformed Basic credentials.");
+	}
+}
+
+function stringOrUndefined(value: unknown): string | undefined {
+	return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/**
+ * Authenticate a client for the token endpoint.
+ *
+ * Every failure answers `invalid_client` with no detail — "no such client",
+ * "wrong secret" and "that client has no secret" are the same sentence to the
+ * caller, because telling them apart is how a client list gets enumerated.
+ */
+export async function authenticateClient(
+	credentials: ClientCredentials,
+	load: (id: string) => Promise<Client | null>,
+): Promise<Client> {
+	if (credentials.clientId === undefined) {
+		throw new OAuthError("invalid_client", "Client authentication failed.");
+	}
+	const client = await load(credentials.clientId);
+	if (client === null) {
+		throw new OAuthError("invalid_client", "Client authentication failed.");
+	}
+
+	// The registered method is the only one accepted. Checked before the
+	// secret so a client cannot pick the weaker of two paths.
+	if (
+		credentials.method !== undefined &&
+		credentials.method !== client.tokenEndpointAuthMethod
+	) {
+		throw new OAuthError("invalid_client", "Client authentication failed.");
+	}
+
+	if (client.tokenEndpointAuthMethod === "none") {
+		// A public client authenticates by not authenticating. Accepting a
+		// secret here would let one be registered as public and used as
+		// confidential, which is a downgrade the client chooses.
+		if (credentials.clientSecret !== undefined) {
+			throw new OAuthError("invalid_client", "Client authentication failed.");
+		}
+		return client;
+	}
+
+	if (
+		credentials.clientSecret === undefined ||
+		client.secretHash === undefined ||
+		!secretMatches(credentials.clientSecret, client.secretHash)
+	) {
+		throw new OAuthError("invalid_client", "Client authentication failed.");
+	}
+	return client;
+}
+
+/** Is this grant one the client was registered for? */
+export function assertGrantAllowed(client: Client, grant: GrantType): void {
+	if (client.grantTypes.includes(grant)) return;
+	throw new OAuthError(
+		"unauthorized_client",
+		`This client may not use the ${grant} grant.`,
+	);
+}
+
+/**
+ * Narrow a requested scope against what the client may ever have.
+ *
+ * Absent, the request gets the client's registered set — never "everything".
+ * A scope the client was not registered for is refused rather than dropped:
+ * silently granting less than asked is how a client ends up believing it has
+ * a permission it does not.
+ */
+export function resolveScopes(
+	requested: string | undefined,
+	client: Client,
+): string[] {
+	if (requested === undefined || requested.trim() === "") {
+		return [...client.scopes];
+	}
+	const asked = requested.split(/\s+/).filter((scope) => scope !== "");
+	const unknown = asked.filter((scope) => !client.scopes.includes(scope));
+	if (unknown.length > 0) {
+		throw new OAuthError(
+			"invalid_scope",
+			`Not registered for: ${unknown.join(" ")}`,
+		);
+	}
+	return asked;
+}

package/src/config.ts

@@ -0,0 +1,34 @@
+/**
+ * `config/visa.ts` — the Adonis shape: a `defineConfig` that returns what the
+ * provider reads out of the config store.
+ */
+
+import type { VisaStore } from "./store.js";
+
+export interface VisaConfigInput {
+	/**
+	 * The public URL this server answers on — `https://auth.example.com`.
+	 *
+	 * It is the `iss` every token is bound to, so it is not cosmetic: a client
+	 * that validates the issuer rejects tokens minted under a different one.
+	 */
+	issuer: string;
+	/** Where clients, codes, tokens and consents live. */
+	store: VisaStore;
+	/** Seconds. Default 3600 — an hour is long enough to be useful, short
+	 * enough that a leaked token is not a standing invitation. */
+	accessTokenTtlSeconds?: number;
+	/** Seconds. Default 30 days. */
+	refreshTokenTtlSeconds?: number;
+	/** Seconds. Default 30 — a code is exchanged in milliseconds. */
+	codeTtlSeconds?: number;
+	issueRefreshTokens?: boolean;
+	/** See `AuthorizeOptions.allowPlainChallenge` — off, and stay off. */
+	allowPlainChallenge?: boolean;
+	/** Where the endpoints are mounted. Default `/oauth`. */
+	prefix?: string;
+}
+
+export function defineConfig(config: VisaConfigInput): VisaConfigInput {
+	return config;
+}

package/src/configure.ts

@@ -0,0 +1,42 @@
+/**
+ * `ream configure @c9up/visa` — wire the server in one command.
+ *
+ * The provider alone is not enough: it reads `config/visa.ts` and refuses to
+ * boot without one, on purpose — an authorization server that invented its own
+ * issuer would mint tokens nobody can validate.
+ *
+ * What it does NOT write is the store and the `/authorize` route. Both are
+ * decisions rather than boilerplate, and a generated guess at either is wrong
+ * in a way that only shows up in production: a memory store loses every
+ * session on deploy, and a consent screen nobody wrote grants silently.
+ */
+
+import { stubsRoot } from "./stubs.js";
+
+interface Codemods {
+	addProvider(importPath: string): Promise<void>;
+	addEnvVars(vars: Record<string, string>): Promise<void>;
+	writeFile(
+		filePath: string,
+		content: string,
+		options?: { force?: boolean },
+	): Promise<void>;
+	makeUsingStub(
+		stubsRoot: string,
+		stubPath: string,
+		state?: Record<string, string | number | boolean>,
+		options?: { force?: boolean },
+	): Promise<{ path: string; contents: string }>;
+}
+
+export async function configure(codemods: Codemods): Promise<void> {
+	// The config below reads this, so it is declared here. Writing the file
+	// without it leaves an application whose config asks the environment for
+	// something nothing ever put there.
+	await codemods.addEnvVars({
+		VISA_ISSUER: "http://localhost:3333",
+	});
+
+	await codemods.addProvider("@c9up/visa/provider");
+	await codemods.makeUsingStub(stubsRoot, "config/visa.stub");
+}

package/src/crypto.ts

@@ -0,0 +1,59 @@
+/**
+ * Every secret in this package goes through here.
+ *
+ * `node:crypto` only — a dependency in the path that mints and compares
+ * credentials is a dependency that can replace them.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+/**
+ * 256 bits of randomness, base64url.
+ *
+ * The length is not a preference: a token is guessed offline, so its entropy
+ * is the only thing standing between an attacker and someone's session.
+ */
+export function randomToken(bytes = 32): string {
+	return randomBytes(bytes).toString("base64url");
+}
+
+/** SHA-256, base64url — the shape PKCE's `S256` needs (RFC 7636 §4.2). */
+export function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("base64url");
+}
+
+/**
+ * What goes in the store for a token or a client secret.
+ *
+ * SHA-256 with no salt and no stretching, DELIBERATELY: these are values this
+ * package generated with 256 bits of entropy, so there is no dictionary to run
+ * and nothing for a slow hash to buy. Stretching here would only make every
+ * token lookup expensive — and a token lookup happens on every single request.
+ * A USER password is the opposite case and belongs in sigil.
+ */
+export function hashSecret(secret: string): string {
+	return sha256(secret);
+}
+
+/**
+ * Compare in constant time.
+ *
+ * A `===` on a secret leaks its prefix through timing, one byte at a time,
+ * which is enough to reconstruct it remotely given patience.
+ */
+export function secretMatches(candidate: string, stored: string): boolean {
+	const a = Buffer.from(hashSecret(candidate));
+	const b = Buffer.from(stored);
+	// Different lengths cannot be compared in constant time by
+	// `timingSafeEqual`, and a length mismatch is not a secret anyway.
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(a, b);
+}
+
+/** The same comparison for two already-hashed values. */
+export function hashMatches(a: string, b: string): boolean {
+	const left = Buffer.from(a);
+	const right = Buffer.from(b);
+	if (left.length !== right.length) return false;
+	return timingSafeEqual(left, right);
+}

package/src/errors.ts

@@ -0,0 +1,79 @@
+/**
+ * Two kinds of failure, and they are not interchangeable.
+ *
+ * A PROTOCOL error is part of the OAuth response: the spec names the string
+ * (`invalid_grant`, `invalid_client`…), the client reads it, and leaking no
+ * more than that string is deliberate — "which of the four checks failed" is
+ * information an attacker uses to enumerate.
+ *
+ * A FRAMEWORK error is a mistake in the application: a store that does not
+ * answer, a client registered without a redirect URI. Those carry a
+ * `E_VISA_*` code and a message meant for a developer, never for a response
+ * body.
+ */
+
+/** Error codes the authorization endpoint may return (OAuth 2.1 §4.1.2.1). */
+export type AuthorizationErrorCode =
+	| "invalid_request"
+	| "unauthorized_client"
+	| "access_denied"
+	| "unsupported_response_type"
+	| "invalid_scope"
+	| "server_error"
+	| "temporarily_unavailable";
+
+/** Error codes the token endpoint may return (OAuth 2.1 §4.1.4). */
+export type TokenErrorCode =
+	| "invalid_request"
+	| "invalid_client"
+	| "invalid_grant"
+	| "unauthorized_client"
+	| "unsupported_grant_type"
+	| "invalid_scope";
+
+export type ProtocolErrorCode = AuthorizationErrorCode | TokenErrorCode;
+
+/**
+ * A failure the client is told about, in the words the spec chose.
+ *
+ * `description` is optional and OPTIONAL on purpose: it goes on the wire, so
+ * it says what the client can act on and never why a check failed internally.
+ */
+export class OAuthError extends Error {
+	readonly code: ProtocolErrorCode;
+	readonly description: string | undefined;
+	/** 401 for `invalid_client`, 400 for everything else (§4.1.4). */
+	readonly status: number;
+
+	constructor(
+		code: ProtocolErrorCode,
+		description?: string,
+		options: { status?: number } = {},
+	) {
+		super(description === undefined ? code : `${code}: ${description}`);
+		this.name = "OAuthError";
+		this.code = code;
+		this.description = description;
+		this.status = options.status ?? (code === "invalid_client" ? 401 : 400);
+	}
+
+	/** The body, exactly as §4.1.4 shapes it. */
+	toResponse(): { error: ProtocolErrorCode; error_description?: string } {
+		return this.description === undefined
+			? { error: this.code }
+			: { error: this.code, error_description: this.description };
+	}
+}
+
+/** A mistake in the application, addressed to whoever wired it. */
+export class VisaError extends Error {
+	readonly code: string;
+	readonly hint: string | undefined;
+
+	constructor(code: string, message: string, options: { hint?: string } = {}) {
+		super(message);
+		this.name = "VisaError";
+		this.code = code;
+		this.hint = options.hint;
+	}
+}