@c9up/transit 0.1.0

package/src/oauth1.ts

@@ -0,0 +1,144 @@
+/**
+ * OAuth 1.0a request signing (RFC 5849), HMAC-SHA1.
+ *
+ * OAuth1 authenticates each request by signing it, rather than by carrying a
+ * bearer token, which is why it needs this at all and OAuth2 does not. The
+ * signature covers the method, the URL and every parameter — so getting the
+ * base string wrong is the failure mode, and it fails as an opaque 401 from
+ * the provider.
+ *
+ * Everything here is pure: no network, no clock, no randomness. The nonce and
+ * timestamp are passed in, which is also what makes the result testable
+ * against the vector in the specification.
+ */
+
+import { createHmac, randomBytes } from "node:crypto";
+
+/** One parameter. Duplicates of a key are allowed, as the spec permits. */
+export type Param = readonly [key: string, value: string];
+
+export interface SignatureInput {
+	method: string;
+	/** Full URL. Its query string is folded into the signed parameters. */
+	url: string;
+	/** Parameters beyond the URL query and the `oauth_*` set — a form body. */
+	params?: readonly Param[];
+	/** The `oauth_*` parameters, without `oauth_signature`. */
+	oauth: readonly Param[];
+	consumerSecret: string;
+	/** Absent on the very first call, when no token exists yet. */
+	tokenSecret?: string;
+}
+
+/**
+ * Percent-encoding as the specification defines it: unreserved characters
+ * stay, everything else is uppercase `%XX`.
+ *
+ * `encodeURIComponent` is close but leaves `!'()*` alone, and a signature
+ * computed with those unescaped does not match the one the provider computes.
+ */
+export function percentEncode(value: string): string {
+	return encodeURIComponent(value).replace(
+		/[!'()*]/g,
+		(character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+	);
+}
+
+/** A fresh nonce. Only its uniqueness matters. */
+export function nonce(): string {
+	return randomBytes(16).toString("hex");
+}
+
+/**
+ * The signature base string — the exact bytes both sides hash.
+ *
+ * Query and body parameters are decoded, then re-encoded, then sorted by
+ * encoded key and encoded value. That round trip is deliberate: two requests
+ * differing only in how they spelled an escape have to produce the same
+ * string, or the signature depends on the spelling.
+ */
+export function signatureBaseString(input: SignatureInput): string {
+	const url = new URL(input.url);
+	const query: Param[] = [...url.searchParams.entries()].map(
+		([key, value]) => [key, value] as Param,
+	);
+
+	const encoded = [...query, ...(input.params ?? []), ...input.oauth]
+		.map(([key, value]): Param => [percentEncode(key), percentEncode(value)])
+		.sort((a, b) => (a[0] === b[0] ? compare(a[1], b[1]) : compare(a[0], b[0])))
+		.map(([key, value]) => `${key}=${value}`)
+		.join("&");
+
+	// The base URL carries no query, no fragment, and no default port.
+	url.search = "";
+	url.hash = "";
+	const base = url.toString().replace(/\/$/, url.pathname === "/" ? "/" : "");
+
+	return [
+		input.method.toUpperCase(),
+		percentEncode(base),
+		percentEncode(encoded),
+	].join("&");
+}
+
+/** The signature itself, base64 of HMAC-SHA1 over the base string. */
+export function sign(input: SignatureInput): string {
+	const key = `${percentEncode(input.consumerSecret)}&${percentEncode(
+		input.tokenSecret ?? "",
+	)}`;
+	return createHmac("sha1", key)
+		.update(signatureBaseString(input))
+		.digest("base64");
+}
+
+/**
+ * The `Authorization: OAuth …` header value, signature included.
+ *
+ * Only the `oauth_*` parameters go in the header; the query and body ones are
+ * signed but stay where they were.
+ */
+export function authorizationHeader(input: SignatureInput): string {
+	const signed: Param[] = [
+		...input.oauth,
+		["oauth_signature", sign(input)] as Param,
+	];
+	const parts = signed
+		.map(([key, value]) => `${percentEncode(key)}="${percentEncode(value)}"`)
+		.join(", ");
+	return `OAuth ${parts}`;
+}
+
+/** The `oauth_*` parameters every signed request carries. */
+export function baseOauthParams(options: {
+	consumerKey: string;
+	token?: string;
+	timestamp: number;
+	nonce: string;
+}): Param[] {
+	const params: Param[] = [
+		["oauth_consumer_key", options.consumerKey],
+		["oauth_nonce", options.nonce],
+		["oauth_signature_method", "HMAC-SHA1"],
+		["oauth_timestamp", String(options.timestamp)],
+		["oauth_version", "1.0"],
+	];
+	if (options.token) params.push(["oauth_token", options.token]);
+	return params;
+}
+
+/**
+ * Parse a `key=value&…` response body. The token endpoints answer in this
+ * form rather than JSON.
+ */
+export function parseFormBody(body: string): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const [key, value] of new URLSearchParams(body).entries()) {
+		out[key] = value;
+	}
+	return out;
+}
+
+/** Byte-order comparison, which is what the specification asks for. */
+function compare(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/oidc.ts

@@ -0,0 +1,208 @@
+/**
+ * The two documents an OpenID Connect provider publishes about itself: where
+ * its endpoints are, and which keys it signs with.
+ *
+ * Both are cached, and both are refetched on a rule rather than on demand.
+ * Keys rotate, so a cache that never refreshes locks an application out at
+ * the worst moment; a cache that refreshes whenever a token names an unknown
+ * key hands anyone a way to make this application hammer the provider. The
+ * middle is a rate limit.
+ */
+
+import type { Jwk } from "./jwt.js";
+
+/** The slice of the discovery document this reads. */
+export interface OidcMetadata {
+	issuer: string;
+	authorization_endpoint: string;
+	token_endpoint: string;
+	jwks_uri: string;
+	userinfo_endpoint?: string;
+	id_token_signing_alg_values_supported?: string[];
+	code_challenge_methods_supported?: string[];
+}
+
+export interface RemoteOptions {
+	/** How long a fetched document is trusted, in milliseconds. Default 1 hour. */
+	ttlMs?: number;
+	/** Shortest interval between two key refetches. Default 5 minutes. */
+	minRefetchMs?: number;
+	/** Injected in tests. */
+	now?: () => number;
+}
+
+const DEFAULT_TTL_MS = 3_600_000;
+const DEFAULT_MIN_REFETCH_MS = 300_000;
+
+/**
+ * Reads and caches `/.well-known/openid-configuration`.
+ *
+ * The document's own `issuer` is checked against the configured one. They are
+ * allowed to differ in the specification's letter about as much as a passport
+ * is allowed to name someone else: a mismatch means the URL that was asked is
+ * not the authority that answered.
+ */
+export class OidcDiscovery {
+	readonly #issuer: string;
+	readonly #ttlMs: number;
+	readonly #now: () => number;
+	#cached: { metadata: OidcMetadata; fetchedAt: number } | undefined;
+	#inFlight: Promise<OidcMetadata> | undefined;
+
+	constructor(issuer: string, options: RemoteOptions = {}) {
+		// A trailing slash changes the well-known URL and, on some providers,
+		// the issuer claim it must be compared against.
+		this.#issuer = issuer.replace(/\/+$/, "");
+		this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+		this.#now = options.now ?? Date.now;
+	}
+
+	get issuer(): string {
+		return this.#issuer;
+	}
+
+	get url(): string {
+		return `${this.#issuer}/.well-known/openid-configuration`;
+	}
+
+	async metadata(): Promise<OidcMetadata> {
+		const cached = this.#cached;
+		if (cached && this.#now() - cached.fetchedAt < this.#ttlMs) {
+			return cached.metadata;
+		}
+		// One fetch at a time: a burst of sign-ins on a cold cache would
+		// otherwise open one request per sign-in.
+		this.#inFlight ??= this.#fetch().finally(() => {
+			this.#inFlight = undefined;
+		});
+		return this.#inFlight;
+	}
+
+	async #fetch(): Promise<OidcMetadata> {
+		const response = await fetch(this.url, {
+			headers: { Accept: "application/json" },
+		});
+		if (!response.ok) {
+			throw new Error(
+				`[transit] OpenID Connect discovery failed for '${this.#issuer}' (HTTP ${response.status})`,
+			);
+		}
+		const body = (await response.json()) as Partial<OidcMetadata>;
+		const metadata = assertMetadata(body, this.#issuer);
+		this.#cached = { metadata, fetchedAt: this.#now() };
+		return metadata;
+	}
+}
+
+/**
+ * Reads and caches a provider's signing keys, and knows when it is allowed to
+ * look again.
+ */
+export class JwksCache {
+	readonly #minRefetchMs: number;
+	readonly #now: () => number;
+	#keys: Jwk[] = [];
+	#fetchedAt = 0;
+	#inFlight: Promise<Jwk[]> | undefined;
+
+	constructor(options: RemoteOptions = {}) {
+		this.#minRefetchMs = options.minRefetchMs ?? DEFAULT_MIN_REFETCH_MS;
+		this.#now = options.now ?? Date.now;
+	}
+
+	/**
+	 * The key a token names.
+	 *
+	 * A `kid` that is not held triggers at most one refetch per interval — that
+	 * is how a rotated key is picked up, and how a stream of tokens naming
+	 * invented keys stays cheap.
+	 */
+	async key(uri: string, kid: string | undefined): Promise<Jwk> {
+		const found = this.#find(kid);
+		if (found) return found;
+
+		if (
+			this.#keys.length > 0 &&
+			this.#now() - this.#fetchedAt < this.#minRefetchMs
+		) {
+			throw new Error(
+				`[transit] id_token names a signing key ('${kid ?? "no kid"}') the provider did not publish`,
+			);
+		}
+
+		await this.#fetch(uri);
+		const refreshed = this.#find(kid);
+		if (!refreshed) {
+			throw new Error(
+				`[transit] id_token names a signing key ('${kid ?? "no kid"}') the provider did not publish`,
+			);
+		}
+		return refreshed;
+	}
+
+	#find(kid: string | undefined): Jwk | undefined {
+		const usable = this.#keys.filter(
+			(jwk) => jwk.use === undefined || jwk.use === "sig",
+		);
+		if (kid !== undefined) return usable.find((jwk) => jwk.kid === kid);
+		// No `kid` is only unambiguous when the provider publishes one key.
+		return usable.length === 1 ? usable[0] : undefined;
+	}
+
+	async #fetch(uri: string): Promise<Jwk[]> {
+		this.#inFlight ??= this.#fetchOnce(uri).finally(() => {
+			this.#inFlight = undefined;
+		});
+		return this.#inFlight;
+	}
+
+	async #fetchOnce(uri: string): Promise<Jwk[]> {
+		const response = await fetch(uri, {
+			headers: { Accept: "application/json" },
+		});
+		if (!response.ok) {
+			throw new Error(
+				`[transit] fetching the provider's signing keys failed (HTTP ${response.status})`,
+			);
+		}
+		const body = (await response.json()) as { keys?: unknown };
+		if (!Array.isArray(body.keys)) {
+			throw new Error("[transit] the provider's JWKS has no `keys` array");
+		}
+		this.#keys = body.keys.filter(isJwk);
+		this.#fetchedAt = this.#now();
+		return this.#keys;
+	}
+}
+
+function isJwk(value: unknown): value is Jwk {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof Reflect.get(value, "kty") === "string"
+	);
+}
+
+function assertMetadata(
+	body: Partial<OidcMetadata>,
+	expectedIssuer: string,
+): OidcMetadata {
+	for (const field of [
+		"issuer",
+		"authorization_endpoint",
+		"token_endpoint",
+		"jwks_uri",
+	] as const) {
+		if (typeof body[field] !== "string" || body[field] === "") {
+			throw new Error(
+				`[transit] the discovery document of '${expectedIssuer}' has no ${field}`,
+			);
+		}
+	}
+	if (body.issuer !== expectedIssuer) {
+		throw new Error(
+			`[transit] discovery answered for issuer '${body.issuer}', not '${expectedIssuer}' — the URL asked is not the authority that replied`,
+		);
+	}
+	return body as OidcMetadata;
+}

package/src/quasar.ts

@@ -0,0 +1,64 @@
+/**
+ * Resolving a Redis connection by name, from `@c9up/quasar`.
+ *
+ * Transit does not depend on quasar: it is an optional peer, and this module
+ * never imports it statically — the specifier is built at runtime so the
+ * TypeScript build stays free of it too.
+ */
+
+interface ConnectionSource {
+	connection(name?: string): unknown;
+}
+
+function isConnectionSource(value: unknown): value is ConnectionSource {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof Reflect.get(value, "connection") === "function"
+	);
+}
+
+/**
+ * The named connection, checked for the commands the caller needs before it is
+ * handed over — a connection missing one would fail on the first sign-in, far
+ * from the cause.
+ */
+export async function quasarConnection<T>(
+	name: string | undefined,
+	required: readonly string[],
+	what: string,
+): Promise<T> {
+	const specifier = "@c9up/quasar/services/main";
+	let loaded: unknown;
+	try {
+		loaded = await import(/* @vite-ignore */ specifier);
+	} catch (cause) {
+		throw new Error(
+			`[transit] naming a Redis connection needs @c9up/quasar, which is not installed.\n  pnpm add @c9up/quasar`,
+			{ cause },
+		);
+	}
+
+	const manager = isConnectionSource(loaded)
+		? loaded
+		: Reflect.get(Object(loaded), "default");
+	if (!isConnectionSource(manager)) {
+		throw new Error(
+			"[transit] @c9up/quasar/services/main did not expose a connection() manager",
+		);
+	}
+
+	const connection = manager.connection(name);
+	const missing = required.filter(
+		(command) =>
+			typeof connection !== "object" ||
+			connection === null ||
+			typeof Reflect.get(connection, command) !== "function",
+	);
+	if (missing.length > 0) {
+		throw new Error(
+			`[transit] the quasar connection${name ? ` '${name}'` : ""} is missing ${missing.join(", ")}, which ${what} issues`,
+		);
+	}
+	return connection as T;
+}

package/src/replay.ts

@@ -0,0 +1,136 @@
+/**
+ * Refusing an assertion that has already been used.
+ *
+ * A SAML assertion is a bearer token: whoever holds it is who it says they
+ * are, until it expires. A signature does not change that, and neither does
+ * any condition on it — a response captured once and posted twice is valid
+ * both times. Remembering the id until the assertion expires is what makes the
+ * second time fail.
+ *
+ * The window is short, so what is stored stays small: an id is forgotten as
+ * soon as the assertion it names could no longer have been accepted anyway.
+ */
+
+import { quasarConnection } from "./quasar.js";
+
+export interface AssertionReplayStore {
+	/**
+	 * Remember `assertionId` until `expiresAt` (epoch seconds).
+	 *
+	 * Answers `true` when this is the first time, `false` when the assertion
+	 * has already been used. Implementations must decide that atomically:
+	 * checking and then storing lets two concurrent posts of the same response
+	 * both win.
+	 */
+	remember(assertionId: string, expiresAt: number): Promise<boolean>;
+}
+
+/**
+ * Remembers in this process's memory.
+ *
+ * Correct while the application runs in one process, and only then: two
+ * replicas each keep their own table, so the same assertion is accepted once
+ * per replica. Reach for the Redis store the moment a second one exists.
+ */
+export class MemoryAssertionReplayStore implements AssertionReplayStore {
+	readonly #seen = new Map<string, number>();
+
+	async remember(assertionId: string, expiresAt: number): Promise<boolean> {
+		const now = Math.floor(Date.now() / 1000);
+		// An opportunistic sweep, bounded by the map's own size: the window is
+		// minutes, so nothing accumulates.
+		for (const [id, expiry] of this.#seen) {
+			if (expiry <= now) this.#seen.delete(id);
+		}
+		if (this.#seen.has(assertionId)) return false;
+		this.#seen.set(assertionId, expiresAt);
+		return true;
+	}
+}
+
+/** The commands the Redis store issues. */
+export interface ReplayRedisClient {
+	/** `SET key value EX <ttl> NX` — answers null when the key already exists. */
+	set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+}
+
+export type ReplayRedisResolver =
+	| ReplayRedisClient
+	| (() => ReplayRedisClient | Promise<ReplayRedisClient>);
+
+export interface RedisReplayOptions {
+	/** Key prefix. Default `"transit:saml:assertion:"`. */
+	prefix?: string;
+}
+
+/**
+ * Remembers in Redis, so every replica refuses the assertion the first one
+ * accepted.
+ *
+ * `SET … NX` decides in one round trip, atomically on the server, which is
+ * what stops two concurrent posts of the same response from both winning.
+ */
+export class RedisAssertionReplayStore implements AssertionReplayStore {
+	readonly #source: ReplayRedisResolver;
+	readonly #prefix: string;
+	#resolved: Promise<ReplayRedisClient> | undefined;
+
+	constructor(client: ReplayRedisResolver, options: RedisReplayOptions = {}) {
+		this.#source = client;
+		this.#prefix = options.prefix ?? "transit:saml:assertion:";
+	}
+
+	async remember(assertionId: string, expiresAt: number): Promise<boolean> {
+		const client = await this.#client();
+		// The key outlives the assertion by a minute, so an assertion accepted
+		// at the edge of its window cannot be replayed just after it.
+		const ttl = Math.max(
+			1,
+			Math.ceil(expiresAt - Math.floor(Date.now() / 1000)) + 60,
+		);
+		const stored = await client.set(
+			`${this.#prefix}${assertionId}`,
+			"1",
+			"EX",
+			ttl,
+			"NX",
+		);
+		return stored !== null && stored !== undefined;
+	}
+
+	#client(): Promise<ReplayRedisClient> {
+		this.#resolved ??= Promise.resolve(
+			typeof this.#source === "function" ? this.#source() : this.#source,
+		);
+		return this.#resolved;
+	}
+}
+
+/** The replay stores a config names. */
+export const replayStores = {
+	/** In this process's memory. Bounds nothing across replicas. */
+	memory(): () => AssertionReplayStore {
+		return () => new MemoryAssertionReplayStore();
+	},
+
+	/**
+	 * Redis. `connection` takes a client, a function answering one, or the NAME
+	 * of a `@c9up/quasar` connection.
+	 */
+	redis(options: {
+		connection: ReplayRedisResolver | string;
+		prefix?: string;
+	}): () => AssertionReplayStore {
+		const client: ReplayRedisResolver =
+			typeof options.connection === "string"
+				? () =>
+						quasarConnection<ReplayRedisClient>(
+							options.connection as string,
+							["set"],
+							"the assertion replay store",
+						)
+				: options.connection;
+		return () =>
+			new RedisAssertionReplayStore(client, { prefix: options.prefix });
+	},
+};