@c9up/transit 0.1.0

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@c9up/transit",
+  "version": "0.1.0",
+  "description": "Transit — federated sign-in for the Ream framework: SAML 2.0, LDAP, OpenID Connect, OAuth1, OAuth2",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./provider": {
+      "types": "./dist/TransitProvider.d.ts",
+      "import": "./dist/TransitProvider.js"
+    },
+    "./configure": {
+      "types": "./dist/configure.d.ts",
+      "import": "./dist/configure.js"
+    },
+    "./services/main": {
+      "types": "./dist/services/main.d.ts",
+      "import": "./dist/services/main.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/FakeTransit.d.ts",
+      "import": "./dist/testing/FakeTransit.js"
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@types/node": "^22.19.15",
+    "@vitest/coverage-v8": "^4.1.5",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "peerDependencies": {
+    "@c9up/quasar": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@c9up/quasar": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/transit.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/Oauth1Driver.ts

@@ -0,0 +1,216 @@
+/**
+ * The OAuth 1.0a three-legged flow.
+ *
+ * A different protocol from OAuth2, not a variation on it. Two things follow
+ * from that, and both shape this class:
+ *
+ *   - The redirect cannot be built offline. The application first asks the
+ *     provider for a request token, and only then knows where to send the
+ *     user — so `redirectUrl()` throws here and `begin()` is the way in.
+ *   - There is no bearer token. Every call is SIGNED, request token included,
+ *     which is what `oauth1.ts` exists for.
+ *
+ * The CSRF check is the same idea as OAuth2's `state` under another name: the
+ * provider hands back the request token it was given, and it has to match the
+ * one this application issued. So it maps onto `callback(code, state,
+ * expectedState, secret)` without inventing a second shape — the verifier is
+ * the code, the returned token is the state, and the request-token secret is
+ * the secret kept from `begin()`.
+ */
+
+import {
+	authorizationHeader,
+	baseOauthParams,
+	nonce,
+	type Param,
+	parseFormBody,
+} from "./oauth1.js";
+import type {
+	OAuthConfig,
+	OAuthToken,
+	RedirectRequest,
+	TransitDriver,
+	TransitUser,
+} from "./types.js";
+import { assertOAuthState } from "./types.js";
+
+export abstract class Oauth1Driver implements TransitDriver {
+	/** Named in errors, so a failure says which provider refused. */
+	protected abstract readonly provider: string;
+	/** Where a request token is obtained, before anything else can happen. */
+	protected abstract readonly requestTokenUrl: string;
+	/** Where the user approves. */
+	protected abstract readonly authorizeUrl: string;
+	/** Where the request token is traded for an access token. */
+	protected abstract readonly accessTokenUrl: string;
+	/** Where the profile is read. */
+	protected abstract readonly userInfoUrl: string;
+
+	constructor(protected readonly config: OAuthConfig) {}
+
+	/** Extra query parameters this provider wants on the profile request. */
+	protected userInfoParams(): Record<string, string> {
+		return {};
+	}
+
+	/** Turn this provider's profile payload into the shape Warden hands back. */
+	protected abstract mapUser(raw: Record<string, unknown>): TransitUser;
+
+	/**
+	 * OAuth1 has no offline redirect: the URL carries a request token that only
+	 * the provider can issue. Saying so is more useful than returning a URL
+	 * that would be refused.
+	 */
+	redirectUrl(): string {
+		throw new Error(
+			`[transit] ${this.provider} uses OAuth1, whose redirect needs a request token from the provider. Use begin() instead of redirect().`,
+		);
+	}
+
+	/**
+	 * Ask for a request token, and answer with where to send the user plus the
+	 * two values to keep: the token, which the callback has to match, and its
+	 * secret, without which the exchange cannot be signed.
+	 */
+	async begin(): Promise<RedirectRequest> {
+		const oauth = this.#oauth();
+		oauth.push(["oauth_callback", this.config.callbackUrl]);
+
+		const body = await this.#post(this.requestTokenUrl, oauth);
+		if (body.oauth_callback_confirmed !== "true") {
+			// The provider rejects a callback URL it does not have registered,
+			// and says so here rather than at the end of the flow.
+			throw new Error(
+				`${this.provider} did not confirm the callback URL — check that '${this.config.callbackUrl}' is registered on the application.`,
+			);
+		}
+		const token = body.oauth_token;
+		const secret = body.oauth_token_secret;
+		if (!token || !secret) {
+			throw new Error(
+				`${this.provider} OAuth: no request token in the response`,
+			);
+		}
+
+		return {
+			url: `${this.authorizeUrl}?oauth_token=${encodeURIComponent(token)}`,
+			state: token,
+			secret,
+		};
+	}
+
+	/**
+	 * `code` is the `oauth_verifier`, `state` the `oauth_token` the provider
+	 * sent back, `expectedState` the one issued at `begin()`, and `secret` its
+	 * secret.
+	 */
+	async callback(
+		code: string,
+		state?: string,
+		expectedState?: string,
+		secret?: string,
+	): Promise<{ user: TransitUser; token: OAuthToken }> {
+		assertOAuthState(state, expectedState);
+		if (!secret) {
+			throw new Error(
+				`[transit] ${this.provider} needs the request-token secret from begin() — store it with the token and pass it back here.`,
+			);
+		}
+
+		const oauth = this.#oauth(expectedState);
+		oauth.push(["oauth_verifier", code]);
+		const body = await this.#post(this.accessTokenUrl, oauth, secret);
+
+		const accessToken = body.oauth_token;
+		const tokenSecret = body.oauth_token_secret;
+		if (!accessToken || !tokenSecret) {
+			throw new Error(`${this.provider} OAuth: no access token in response`);
+		}
+
+		const user = await this.fetchUser(accessToken, tokenSecret);
+		return { user, token: { accessToken, tokenSecret } };
+	}
+
+	/**
+	 * Read the profile behind a token already held. Unlike OAuth2 this needs
+	 * the secret too — an OAuth1 token alone signs nothing.
+	 */
+	async userFromToken(
+		accessToken: string,
+		tokenSecret?: string,
+	): Promise<TransitUser> {
+		if (!tokenSecret) {
+			throw new Error(
+				`[transit] ${this.provider} needs the token secret as well: an OAuth1 access token cannot sign a request on its own.`,
+			);
+		}
+		return this.fetchUser(accessToken, tokenSecret);
+	}
+
+	/** Read the profile with a signed GET. */
+	protected async fetchUser(
+		accessToken: string,
+		tokenSecret: string,
+	): Promise<TransitUser> {
+		const params = this.userInfoParams();
+		const query = new URLSearchParams(params).toString();
+		const url = query ? `${this.userInfoUrl}?${query}` : this.userInfoUrl;
+
+		const response = await fetch(url, {
+			headers: {
+				Authorization: authorizationHeader({
+					method: "GET",
+					url,
+					oauth: this.#oauth(accessToken),
+					consumerSecret: this.config.clientSecret,
+					tokenSecret,
+				}),
+				Accept: "application/json",
+			},
+		});
+		if (!response.ok) {
+			throw new Error(
+				`${this.provider} profile request failed (HTTP ${response.status})`,
+			);
+		}
+		return this.mapUser((await response.json()) as Record<string, unknown>);
+	}
+
+	/** The `oauth_*` set for one request, stamped now. */
+	#oauth(token?: string): Param[] {
+		return baseOauthParams({
+			consumerKey: this.config.clientId,
+			token,
+			timestamp: Math.floor(Date.now() / 1000),
+			nonce: nonce(),
+		});
+	}
+
+	/** A signed POST to one of the token endpoints, whose body is form-encoded. */
+	async #post(
+		url: string,
+		oauth: Param[],
+		tokenSecret?: string,
+	): Promise<Record<string, string>> {
+		const response = await fetch(url, {
+			method: "POST",
+			headers: {
+				Authorization: authorizationHeader({
+					method: "POST",
+					url,
+					oauth,
+					consumerSecret: this.config.clientSecret,
+					tokenSecret,
+				}),
+				"Content-Type": "application/x-www-form-urlencoded",
+			},
+		});
+		if (!response.ok) {
+			throw new Error(
+				`${this.provider} OAuth token exchange failed (HTTP ${response.status})`,
+			);
+		}
+		// These endpoints answer `key=value&…`, not JSON.
+		return parseFormBody(await response.text());
+	}
+}

package/src/Oauth2Driver.ts

@@ -0,0 +1,271 @@
+/**
+ * The half of an OAuth2 sign-in every provider shares.
+ *
+ * Each provider differs in three places — where you send the user, where the
+ * code is exchanged, and what the profile payload is called — and agrees on
+ * everything else. This holds the everything else, so a driver is the three
+ * URLs, the default scopes, and the mapping from that provider's payload to
+ * {@link TransitUser}.
+ *
+ * Nothing here is stateful: the `state` and, where a provider requires it, the
+ * PKCE verifier are passed in and handed back by the caller. Warden does not
+ * own your session, so it cannot store them for you — and that is also what
+ * lets one driver serve several concurrent sign-ins.
+ */
+
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import type {
+	OAuthConfig,
+	OAuthToken,
+	RedirectRequest,
+	TransitDriver,
+	TransitUser,
+} from "./types.js";
+import { assertOAuthState } from "./types.js";
+
+/** A provider's token response, before it is narrowed. */
+type TokenResponse = Record<string, unknown>;
+
+/**
+ * Mint a PKCE code verifier.
+ *
+ * Store it next to the `state` — the same place, with the same lifetime — and
+ * hand it back to `callback()`. A provider that requires PKCE binds the
+ * authorization code to this value, so a code intercepted on its way back is
+ * useless to whoever intercepted it.
+ */
+export function createCodeVerifier(): string {
+	// 32 bytes of entropy, base64url — 43 characters, the shortest length
+	// RFC 7636 allows, and the length every provider accepts.
+	return randomBytes(32).toString("base64url");
+}
+
+export abstract class Oauth2Driver implements TransitDriver {
+	/** Named in errors, so a failure says which provider refused. */
+	protected abstract readonly provider: string;
+	/** Where the user is sent to approve. */
+	protected abstract readonly authorizeUrl: string;
+	/** Where the authorization code is exchanged for a token. */
+	protected abstract readonly accessTokenUrl: string;
+	/** Where the profile is read. */
+	protected abstract readonly userInfoUrl: string;
+	/** Scopes requested when the config names none. */
+	protected abstract readonly defaultScopes: readonly string[];
+
+	/**
+	 * Providers that require PKCE. The redirect then refuses to build without
+	 * a verifier rather than sending the user to a URL the provider rejects.
+	 */
+	protected readonly requiresPkce: boolean = false;
+
+	/**
+	 * Send the client credentials as HTTP Basic on the token request instead of
+	 * in the body. A handful of providers accept nothing else.
+	 */
+	protected readonly tokenAuth: "body" | "basic" = "body";
+
+	constructor(protected readonly config: OAuthConfig) {}
+
+	/** Extra parameters this provider wants on the authorize URL. */
+	protected authorizeParams(): Record<string, string> {
+		return {};
+	}
+
+	/** Extra query parameters this provider wants on the profile request. */
+	protected userInfoParams(): Record<string, string> {
+		return {};
+	}
+
+	/** Turn this provider's profile payload into the shape Warden hands back. */
+	protected abstract mapUser(raw: Record<string, unknown>): TransitUser;
+
+	scopes(): string[] {
+		return [...(this.config.scopes ?? this.defaultScopes)];
+	}
+
+	redirectUrl(state?: string, secret?: string): string {
+		const params = new URLSearchParams({
+			client_id: this.config.clientId,
+			redirect_uri: this.config.callbackUrl,
+			response_type: "code",
+			scope: this.scopes().join(" "),
+			...this.authorizeParams(),
+			...this.config.authorizeParams,
+			...(state ? { state } : {}),
+		});
+
+		if (this.requiresPkce) {
+			if (!secret) {
+				throw new Error(
+					`[transit] ${this.provider} requires PKCE: pass the code verifier from createCodeVerifier() to redirectUrl(), store it with the state, and hand it back to callback().`,
+				);
+			}
+			params.set("code_challenge", challengeFor(secret));
+			params.set("code_challenge_method", "S256");
+		}
+
+		return `${this.authorizeUrl}?${params}`;
+	}
+
+	/**
+	 * Where to send the user, plus what has to be kept until they come back.
+	 * The state is minted here when the caller has no reason to choose one,
+	 * and a provider requiring PKCE gets its verifier without the caller
+	 * having to know it needed one.
+	 */
+	async begin(state: string = randomUUID()): Promise<RedirectRequest> {
+		if (!this.requiresPkce) return { url: this.redirectUrl(state), state };
+		const secret = createCodeVerifier();
+		return { url: this.redirectUrl(state, secret), state, secret };
+	}
+
+	async callback(
+		code: string,
+		state?: string,
+		expectedState?: string,
+		secret?: string,
+	): Promise<{ user: TransitUser; token: OAuthToken }> {
+		assertOAuthState(state, expectedState);
+		if (this.requiresPkce && !secret) {
+			throw new Error(
+				`[transit] ${this.provider} requires PKCE: pass back the code verifier you stored at redirect time.`,
+			);
+		}
+		const tokens = await this.exchange(code, secret);
+		const accessToken = String(tokens.access_token);
+		const user = await this.fetchUser(accessToken);
+		return { user, token: readToken(tokens, accessToken) };
+	}
+
+	/**
+	 * Read the profile behind a token you already hold, with no code to
+	 * exchange — a refreshed token, or one a mobile client obtained itself.
+	 */
+	async userFromToken(accessToken: string): Promise<TransitUser> {
+		return this.fetchUser(accessToken);
+	}
+
+	/** Trade the authorization code for an access token. */
+	protected async exchange(
+		code: string,
+		secret?: string,
+	): Promise<TokenResponse> {
+		const body = new URLSearchParams({
+			code,
+			redirect_uri: this.config.callbackUrl,
+			grant_type: "authorization_code",
+			...(secret ? { code_verifier: secret } : {}),
+		});
+		const headers: Record<string, string> = {
+			Accept: "application/json",
+			"Content-Type": "application/x-www-form-urlencoded",
+		};
+
+		if (this.tokenAuth === "basic") {
+			const credentials = Buffer.from(
+				`${this.config.clientId}:${this.config.clientSecret}`,
+			).toString("base64");
+			headers.Authorization = `Basic ${credentials}`;
+			// Sending them twice is what makes some providers reject the request
+			// outright, so the body carries them only in the other mode.
+			body.set("client_id", this.config.clientId);
+		} else {
+			body.set("client_id", this.config.clientId);
+			body.set("client_secret", this.config.clientSecret);
+		}
+
+		const response = await fetch(this.accessTokenUrl, {
+			method: "POST",
+			headers,
+			body,
+		});
+		if (!response.ok) {
+			throw new Error(
+				`${this.provider} OAuth token exchange failed (HTTP ${response.status})`,
+			);
+		}
+		const tokens = (await response.json()) as TokenResponse;
+		if (!tokens.access_token) {
+			throw new Error(`${this.provider} OAuth: no access_token in response`);
+		}
+		return tokens;
+	}
+
+	/** Read the profile. Providers needing a second call override this. */
+	protected async fetchUser(accessToken: string): Promise<TransitUser> {
+		const raw = await this.get(this.userInfoUrl, accessToken, {
+			...this.userInfoParams(),
+		});
+		return this.mapUser(raw);
+	}
+
+	/** An authenticated GET returning a JSON array — some endpoints answer one. */
+	protected async getList(
+		url: string,
+		accessToken: string,
+		params: Record<string, string> = {},
+	): Promise<unknown[]> {
+		const body = await this.#requestJson(url, accessToken, params);
+		return Array.isArray(body) ? body : [];
+	}
+
+	/** An authenticated GET returning the decoded JSON body. */
+	protected async get(
+		url: string,
+		accessToken: string,
+		params: Record<string, string> = {},
+	): Promise<Record<string, unknown>> {
+		const body = await this.#requestJson(url, accessToken, params);
+		return typeof body === "object" && body !== null && !Array.isArray(body)
+			? (body as Record<string, unknown>)
+			: {};
+	}
+
+	/** The authenticated GET itself, before anything is assumed of the body. */
+	async #requestJson(
+		url: string,
+		accessToken: string,
+		params: Record<string, string> = {},
+	): Promise<unknown> {
+		const query = new URLSearchParams(params).toString();
+		const response = await fetch(query ? `${url}?${query}` : url, {
+			headers: {
+				Authorization: `Bearer ${accessToken}`,
+				Accept: "application/json",
+			},
+		});
+		if (!response.ok) {
+			throw new Error(
+				`${this.provider} profile request failed (HTTP ${response.status})`,
+			);
+		}
+		return await response.json();
+	}
+}
+
+/** The S256 challenge a provider compares the verifier against. */
+export function challengeFor(secret: string): string {
+	return createHash("sha256").update(secret).digest("base64url");
+}
+
+/** Narrow a provider's token payload to the fields Warden promises. */
+function readToken(tokens: TokenResponse, accessToken: string): OAuthToken {
+	return {
+		accessToken,
+		...(typeof tokens.refresh_token === "string"
+			? { refreshToken: tokens.refresh_token }
+			: {}),
+		...(typeof tokens.expires_in === "number"
+			? { expiresIn: tokens.expires_in }
+			: {}),
+	};
+}
+
+/** Read a string field, or `undefined` when it is absent or not a string. */
+export function str(
+	raw: Record<string, unknown>,
+	key: string,
+): string | undefined {
+	const value = raw[key];
+	return typeof value === "string" && value !== "" ? value : undefined;
+}

package/src/TransitManager.ts

@@ -0,0 +1,145 @@
+/**
+ * The providers an application signs people in through, keyed by the names its
+ * config chose.
+ *
+ *   const { url, state, secret } = await transit.begin('google')
+ *   const { user } = await transit.callback('google', code, state, expected, secret)
+ *
+ * The key is the caller's: two entries may speak to the same provider with
+ * different credentials, and `use(name)` asks for the key, not the protocol.
+ */
+
+import type {
+	DirectoryDriver,
+	OAuthToken,
+	RedirectRequest,
+	TransitDriver,
+	TransitEntry,
+	TransitUser,
+} from "./types.js";
+import { isDirectory } from "./types.js";
+
+export class TransitManager {
+	#drivers: Map<string, TransitEntry> = new Map();
+
+	/** The provider a browser is sent to, under `name`. */
+	use(name: string): TransitDriver {
+		const entry = this.#entry(name);
+		if (isDirectory(entry)) {
+			throw new Error(
+				`[transit] '${name}' is a directory: it verifies credentials rather than redirecting. Use authenticate('${name}', …).`,
+			);
+		}
+		return entry;
+	}
+
+	/** The directory under `name`. */
+	directory(name: string): DirectoryDriver {
+		const entry = this.#entry(name);
+		if (!isDirectory(entry)) {
+			throw new Error(
+				`[transit] '${name}' is a redirect provider, not a directory. Use begin('${name}').`,
+			);
+		}
+		return entry;
+	}
+
+	/**
+	 * Verify a login against the directory under `name`.
+	 *
+	 * No redirect and no state: the application already holds the credentials,
+	 * and the directory is the authority that says whether they are right.
+	 */
+	async authenticate(
+		name: string,
+		username: string,
+		password: string,
+	): Promise<TransitUser> {
+		return this.directory(name).authenticate(username, password);
+	}
+
+	#entry(name: string): TransitEntry {
+		const driver = this.#drivers.get(name);
+		if (!driver)
+			throw new Error(
+				`OAuth driver '${name}' not registered. Available: ${[...this.#drivers.keys()].join(", ")}`,
+			);
+		return driver;
+	}
+
+	register(name: string, driver: TransitEntry): void {
+		this.#drivers.set(name, driver);
+	}
+
+	/**
+	 * Where to send the user, plus what to keep until they come back.
+	 *
+	 * This is the path that works for every provider: it mints the state,
+	 * fetches a request token where the protocol needs one, and returns the
+	 * secret to store when there is one.
+	 */
+	async begin(name: string, state?: string): Promise<RedirectRequest> {
+		const driver = this.use(name);
+		if (typeof driver.begin !== "function") {
+			throw new Error(
+				`[transit] The '${name}' driver does not support begin(); use redirect().`,
+			);
+		}
+		return driver.begin(state);
+	}
+
+	/**
+	 * Where to send the user, when the provider can say so offline. `secret`
+	 * is only read by providers that require PKCE — mint one with
+	 * `createCodeVerifier()` and store it beside the state.
+	 *
+	 * An OAuth1 provider cannot answer here; call {@link begin} instead.
+	 */
+	redirect(name: string, state?: string, secret?: string): string {
+		return this.use(name).redirectUrl(state, secret);
+	}
+
+	/**
+	 * Handle the OAuth callback. Pass `state` (from the query string) and
+	 * `expectedState` (from the session, stored at redirect time) for CSRF
+	 * protection. Omitting `expectedState` logs a security warning.
+	 */
+	async callback(
+		name: string,
+		code: string,
+		state?: string,
+		expectedState?: string,
+		secret?: string,
+	): Promise<{ user: TransitUser; token: OAuthToken }> {
+		if (!expectedState) {
+			throw new Error(
+				`[transit] OAuth callback for '${name}' requires expectedState for CSRF protection. ` +
+					`Store the state from redirect() in the session and pass it here.`,
+			);
+		}
+		return this.use(name).callback(code, state, expectedState, secret);
+	}
+
+	/**
+	 * Read the profile behind a token already held, through the named provider.
+	 * Throws when that driver has no way to — rather than answering with a
+	 * profile it did not fetch.
+	 */
+	async userFromToken(
+		name: string,
+		accessToken: string,
+		tokenSecret?: string,
+	): Promise<TransitUser> {
+		const driver = this.use(name);
+		if (typeof driver.userFromToken !== "function") {
+			throw new Error(
+				`[transit] The '${name}' driver cannot read a profile from an existing token.`,
+			);
+		}
+		return driver.userFromToken(accessToken, tokenSecret);
+	}
+
+	get registeredDrivers(): string[] {
+		return [...this.#drivers.keys()];
+	}
+}