@c9up/transit 0.1.0

package/src/saml.ts

@@ -0,0 +1,309 @@
+/**
+ * Reading a SAML response, once its signature has been verified.
+ *
+ * A valid signature says the identity provider wrote this. It says nothing
+ * about whether the statement was meant for THIS application, at THIS moment,
+ * in answer to THIS request — and a response that is genuine but not any of
+ * those is exactly what a replay or a redirect to another service provider
+ * looks like. Every condition below is one of those questions.
+ *
+ * Everything here works on the element the signature covers. Nothing searches
+ * the document again: that is the guarantee `verifyXmlSignature` hands over,
+ * and re-finding an element would throw it away.
+ */
+
+import { childrenNamed, textOf, walk, type XmlElement } from "./xml.js";
+
+export const SAML_PROTOCOL_NS = "urn:oasis:names:tc:SAML:2.0:protocol";
+export const SAML_ASSERTION_NS = "urn:oasis:names:tc:SAML:2.0:assertion";
+const STATUS_SUCCESS = "urn:oasis:names:tc:SAML:2.0:status:Success";
+const BEARER = "urn:oasis:names:tc:SAML:2.0:cm:bearer";
+
+export class SamlError extends Error {
+	constructor(message: string) {
+		super(`[transit] ${message}`);
+		this.name = "SamlError";
+	}
+}
+
+/** What a validated assertion says about the person. */
+export interface SamlIdentity {
+	/** The `NameID`, which is what the provider calls this person. */
+	nameId: string;
+	nameIdFormat: string | undefined;
+	/** Every attribute the assertion carried, values kept as a list. */
+	attributes: Record<string, string[]>;
+	/** The assertion's own id, for the replay check. */
+	assertionId: string;
+	/** When the assertion stops being usable, epoch seconds. */
+	notOnOrAfter: number;
+	/** The provider's session, when it named one. */
+	sessionIndex: string | undefined;
+}
+
+export interface SamlExpectations {
+	/** The provider's entity id, as its metadata declares it. */
+	issuer: string;
+	/** This application's entity id, which the assertion must be addressed to. */
+	audience: string;
+	/** The assertion consumer URL the response was meant to land on. */
+	recipient: string;
+	/**
+	 * The id of the request this answers. Required for a sign-in this
+	 * application started: without it, an assertion obtained elsewhere can be
+	 * posted here.
+	 */
+	inResponseTo?: string;
+	/** Tolerance for clock drift against the provider. Default 60 seconds. */
+	clockSkewSeconds?: number;
+	/** Injected in tests; seconds since the epoch. */
+	now?: number;
+}
+
+/**
+ * Check the `Status` of a response, and say what the provider refused.
+ *
+ * A failed status is the provider declining — an unknown user, a cancelled
+ * consent — and it arrives signed just like a success.
+ */
+export function assertResponseSucceeded(response: XmlElement): void {
+	const status = childrenNamed(response, SAML_PROTOCOL_NS, "Status")[0];
+	const code = status
+		? childrenNamed(status, SAML_PROTOCOL_NS, "StatusCode")[0]
+		: undefined;
+	const value = code?.attributes.find((a) => a.local === "Value")?.value;
+	if (value === STATUS_SUCCESS) return;
+
+	const message = status
+		? childrenNamed(status, SAML_PROTOCOL_NS, "StatusMessage")[0]
+		: undefined;
+	throw new SamlError(
+		`the provider refused the sign-in: ${value ?? "no status"}${
+			message ? ` — ${textOf(message).trim()}` : ""
+		}`,
+	);
+}
+
+/**
+ * Validate an assertion and read what it says.
+ *
+ * `assertion` must be the element the signature covers, or an element inside
+ * it — never one looked up in the document afterwards.
+ */
+export function validateAssertion(
+	assertion: XmlElement,
+	expected: SamlExpectations,
+): SamlIdentity {
+	if (
+		assertion.namespaceUri !== SAML_ASSERTION_NS ||
+		assertion.local !== "Assertion"
+	) {
+		throw new SamlError(
+			`expected a signed <Assertion>, and the signature covers <${assertion.qname}>`,
+		);
+	}
+
+	const skew = expected.clockSkewSeconds ?? 60;
+	const now = expected.now ?? Math.floor(Date.now() / 1000);
+
+	const issuer = childrenNamed(assertion, SAML_ASSERTION_NS, "Issuer")[0];
+	const issuerValue = issuer ? textOf(issuer).trim() : undefined;
+	if (issuerValue !== expected.issuer) {
+		throw new SamlError(
+			`the assertion is issued by '${issuerValue ?? "nobody"}', not by '${expected.issuer}'`,
+		);
+	}
+
+	const assertionId = assertion.attributes.find((a) => a.local === "ID")?.value;
+	if (!assertionId) {
+		throw new SamlError("the assertion carries no id, so it cannot be tracked");
+	}
+
+	const subject = one(assertion, "Subject");
+	const confirmation = childrenNamed(
+		subject,
+		SAML_ASSERTION_NS,
+		"SubjectConfirmation",
+	).find(
+		(c) => c.attributes.find((a) => a.local === "Method")?.value === BEARER,
+	);
+	if (!confirmation) {
+		throw new SamlError(
+			"the assertion has no bearer subject confirmation, which is the only method a browser sign-in uses",
+		);
+	}
+	const data = childrenNamed(
+		confirmation,
+		SAML_ASSERTION_NS,
+		"SubjectConfirmationData",
+	)[0];
+	if (!data) {
+		throw new SamlError("the bearer confirmation carries no data to check");
+	}
+
+	const recipient = data.attributes.find((a) => a.local === "Recipient")?.value;
+	if (recipient !== expected.recipient) {
+		// A response addressed to another service provider is a genuine
+		// assertion pointed at the wrong door.
+		throw new SamlError(
+			`the assertion was sent to '${recipient ?? "nowhere"}', and this application answers at '${expected.recipient}'`,
+		);
+	}
+
+	const answered = data.attributes.find(
+		(a) => a.local === "InResponseTo",
+	)?.value;
+	if (expected.inResponseTo !== undefined) {
+		if (answered !== expected.inResponseTo) {
+			// Without this, an assertion obtained anywhere else can be posted
+			// here and accepted.
+			throw new SamlError(
+				"the assertion answers a different request than the one this sign-in made",
+			);
+		}
+	} else if (answered !== undefined) {
+		throw new SamlError(
+			"the assertion answers a request this application did not make",
+		);
+	}
+
+	const confirmationExpiry = epoch(
+		data.attributes.find((a) => a.local === "NotOnOrAfter")?.value,
+	);
+	if (confirmationExpiry === undefined) {
+		throw new SamlError("the bearer confirmation never expires, which it must");
+	}
+	if (now - skew >= confirmationExpiry) {
+		throw new SamlError("the assertion is no longer usable");
+	}
+
+	const conditions = one(assertion, "Conditions");
+	const notBefore = epoch(
+		conditions.attributes.find((a) => a.local === "NotBefore")?.value,
+	);
+	const notOnOrAfter = epoch(
+		conditions.attributes.find((a) => a.local === "NotOnOrAfter")?.value,
+	);
+	if (notBefore !== undefined && now + skew < notBefore) {
+		throw new SamlError("the assertion is not valid yet");
+	}
+	if (notOnOrAfter === undefined) {
+		throw new SamlError("the assertion has no expiry, which it must");
+	}
+	if (now - skew >= notOnOrAfter) {
+		throw new SamlError("the assertion has expired");
+	}
+
+	const audiences = childrenNamed(
+		conditions,
+		SAML_ASSERTION_NS,
+		"AudienceRestriction",
+	).flatMap((restriction) =>
+		childrenNamed(restriction, SAML_ASSERTION_NS, "Audience").map((a) =>
+			textOf(a).trim(),
+		),
+	);
+	if (audiences.length === 0) {
+		throw new SamlError(
+			"the assertion restricts no audience, so it does not say who it is for",
+		);
+	}
+	if (!audiences.includes(expected.audience)) {
+		throw new SamlError(
+			`the assertion is for ${audiences.map((a) => `'${a}'`).join(", ")}, and this application is '${expected.audience}'`,
+		);
+	}
+
+	const nameIdElement = childrenNamed(subject, SAML_ASSERTION_NS, "NameID")[0];
+	if (!nameIdElement) {
+		throw new SamlError("the assertion names nobody");
+	}
+
+	const authn = childrenNamed(
+		assertion,
+		SAML_ASSERTION_NS,
+		"AuthnStatement",
+	)[0];
+
+	return {
+		nameId: textOf(nameIdElement).trim(),
+		nameIdFormat: nameIdElement.attributes.find((a) => a.local === "Format")
+			?.value,
+		attributes: readAttributes(assertion),
+		assertionId,
+		notOnOrAfter,
+		sessionIndex: authn?.attributes.find((a) => a.local === "SessionIndex")
+			?.value,
+	};
+}
+
+/**
+ * Every `<Attribute>` of the assertion, values kept as a list because SAML
+ * attributes are multi-valued and collapsing them loses group memberships.
+ */
+function readAttributes(assertion: XmlElement): Record<string, string[]> {
+	const out: Record<string, string[]> = {};
+	for (const statement of childrenNamed(
+		assertion,
+		SAML_ASSERTION_NS,
+		"AttributeStatement",
+	)) {
+		for (const attribute of childrenNamed(
+			statement,
+			SAML_ASSERTION_NS,
+			"Attribute",
+		)) {
+			const name =
+				attribute.attributes.find((a) => a.local === "Name")?.value ??
+				attribute.attributes.find((a) => a.local === "FriendlyName")?.value;
+			if (!name) continue;
+			const values = childrenNamed(
+				attribute,
+				SAML_ASSERTION_NS,
+				"AttributeValue",
+			).map((value) => textOf(value).trim());
+			const existing = out[name] ?? [];
+			existing.push(...values);
+			out[name] = existing;
+		}
+	}
+	return out;
+}
+
+/** The assertion inside a signed response, when the response is what was signed. */
+export function assertionInside(signed: XmlElement): XmlElement {
+	if (
+		signed.local === "Assertion" &&
+		signed.namespaceUri === SAML_ASSERTION_NS
+	) {
+		return signed;
+	}
+	const assertions = [...walk(signed)].filter(
+		(element) =>
+			element.namespaceUri === SAML_ASSERTION_NS &&
+			element.local === "Assertion",
+	);
+	if (assertions.length !== 1) {
+		throw new SamlError(
+			`the signed element contains ${assertions.length} assertions, and this reads one`,
+		);
+	}
+	return assertions[0] as XmlElement;
+}
+
+function one(parent: XmlElement, local: string): XmlElement {
+	const found = childrenNamed(parent, SAML_ASSERTION_NS, local);
+	if (found.length !== 1) {
+		throw new SamlError(
+			`expected one <${local}> in the assertion, and there are ${found.length}`,
+		);
+	}
+	return found[0] as XmlElement;
+}
+
+/** A SAML instant, in seconds. Anything unparseable is treated as absent. */
+function epoch(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const parsed = Date.parse(value);
+	return Number.isNaN(parsed) ? undefined : Math.floor(parsed / 1000);
+}

package/src/services/main.ts

@@ -0,0 +1,47 @@
+/**
+ * Container service accessor — `import transit from '@c9up/transit/services/main'`.
+ *
+ * Populated by `TransitProvider.boot()`. Reading it before the provider has
+ * booted throws rather than answering with an empty manager, because a manager
+ * with no providers fails on the first sign-in instead of at startup.
+ */
+
+import type { TransitManager } from "../TransitManager.js";
+
+let instance: TransitManager | undefined;
+
+/** @internal Called by the provider once the manager exists. */
+export function setTransit(manager: TransitManager): void {
+	instance = manager;
+}
+
+/** @internal Test helper — forget the manager between cases. */
+export function clearTransit(): void {
+	instance = undefined;
+}
+
+function resolve(): TransitManager {
+	if (!instance) {
+		throw new Error(
+			"[transit] accessed before initialization — register TransitProvider, or call setTransit() 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 itself.
+ */
+const transit = new Proxy({} as TransitManager, {
+	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 TransitManager;
+
+export default transit;

package/src/testing/FakeTransit.ts

@@ -0,0 +1,233 @@
+/**
+ * FakeTransit — a test double for `TransitManager`.
+ *
+ * A sign-in cannot be exercised against a real provider in a test, so this
+ * stands in for one: it hands back a redirect, and answers the callback with
+ * whatever user the test declared.
+ *
+ * It is deliberately NOT lenient. The state round trip and the value `begin()`
+ * asked to keep are enforced here exactly as the real drivers enforce them,
+ * because a fake that lets a forgetful controller pass is a fake that teaches
+ * applications to ship one. A test that fails here would have been a session
+ * fixation in production.
+ *
+ *   import { FakeTransit } from '@c9up/transit/testing'
+ *
+ *   const transit = new FakeTransit()
+ *   transit.willReturn('google', { email: 'ada@acme.test' })
+ *   container.singleton(TransitManager, () => transit)
+ *
+ *   // ... the code under test runs its sign-in
+ *   transit.assertSignedIn('google')
+ */
+
+import { randomUUID } from "node:crypto";
+import { TransitManager } from "../TransitManager.js";
+import type { OAuthToken, RedirectRequest, TransitUser } from "../types.js";
+import { assertOAuthState } from "../types.js";
+
+/** What a test declares a provider will answer with. */
+export interface FakeIdentity extends Partial<TransitUser> {
+	email?: string;
+}
+
+export interface BegunSignIn {
+	name: string;
+	state: string;
+	secret: string;
+}
+
+export interface CompletedSignIn {
+	name: string;
+	user: TransitUser;
+}
+
+const DEFAULT_TOKEN: OAuthToken = { accessToken: "fake-access-token" };
+
+export class FakeTransit extends TransitManager {
+	readonly #identities = new Map<string, TransitUser>();
+	readonly #tokens = new Map<string, OAuthToken>();
+	readonly #credentials = new Map<
+		string,
+		{ username: string; password: string }
+	>();
+	/** Every `begin()` this saw, oldest first. */
+	readonly begun: BegunSignIn[] = [];
+	/** Every sign-in that completed, oldest first. */
+	readonly signedIn: CompletedSignIn[] = [];
+
+	/**
+	 * Declare who comes back from `name`. Anything left out is filled in, so a
+	 * test states only what it is about.
+	 */
+	/**
+	 * Declare the credentials a directory accepts under `name`. Without this,
+	 * `authenticate` accepts any pair — which is what a test about roles wants,
+	 * and a test about a wrong password does not.
+	 */
+	willAccept(name: string, username: string, password: string): this {
+		this.#credentials.set(name, { username, password });
+		return this;
+	}
+
+	willReturn(
+		name: string,
+		identity: FakeIdentity = {},
+		token?: OAuthToken,
+	): this {
+		this.#identities.set(name, {
+			id: identity.id ?? `fake-${name}-user`,
+			email: identity.email ?? `${name}@example.test`,
+			name: identity.name ?? "Fake User",
+			nickName: identity.nickName,
+			avatarUrl: identity.avatarUrl,
+			emailVerificationState: identity.emailVerificationState ?? "verified",
+			raw: identity.raw ?? {},
+		});
+		if (token) this.#tokens.set(name, token);
+		return this;
+	}
+
+	override async begin(
+		name: string,
+		state: string = randomUUID(),
+	): Promise<RedirectRequest> {
+		const secret = randomUUID();
+		this.begun.push({ name, state, secret });
+		return {
+			url: `https://transit.test/${encodeURIComponent(name)}?state=${encodeURIComponent(state)}`,
+			state,
+			secret,
+		};
+	}
+
+	override redirect(name: string, state?: string): string {
+		this.begun.push({ name, state: state ?? "", secret: "" });
+		return `https://transit.test/${encodeURIComponent(name)}?state=${encodeURIComponent(state ?? "")}`;
+	}
+
+	override async callback(
+		name: string,
+		_code: string,
+		state?: string,
+		expectedState?: string,
+		secret?: string,
+	): Promise<{ user: TransitUser; token: OAuthToken }> {
+		// The same refusal the real drivers make. A controller that forgets to
+		// store the state, or to hand it back, fails in the test rather than in
+		// production.
+		assertOAuthState(state, expectedState);
+
+		const started = this.begun.find((entry) => entry.name === name);
+		if (started?.secret && secret !== started.secret) {
+			throw new Error(
+				`[transit] the callback for '${name}' did not carry the value begin() returned as \`secret\` — store it with the state.`,
+			);
+		}
+
+		const user = this.#identities.get(name);
+		if (!user) {
+			throw new Error(
+				`[transit] nothing declared for '${name}'. Call willReturn('${name}', …) before the sign-in runs.`,
+			);
+		}
+		this.signedIn.push({ name, user });
+		return { user, token: this.#tokens.get(name) ?? DEFAULT_TOKEN };
+	}
+
+	/**
+	 * A directory sign-in, doubled.
+	 *
+	 * The empty-password refusal is repeated here for the same reason the state
+	 * check is: a bind with no password is an anonymous bind the directory
+	 * accepts, and a fake that let it through would teach an application to
+	 * submit one.
+	 */
+	override async authenticate(
+		name: string,
+		username: string,
+		password: string,
+	): Promise<TransitUser> {
+		if (password === "") {
+			throw new Error(
+				"[transit] a password is required — an empty one is an anonymous bind, which the directory would accept",
+			);
+		}
+		if (username === "") {
+			throw new Error("[transit] a username is required");
+		}
+		const user = this.#identities.get(name);
+		if (!user) {
+			throw new Error(
+				`[transit] nothing declared for '${name}'. Call willReturn('${name}', …) before the sign-in runs.`,
+			);
+		}
+		const credentials = this.#credentials.get(name);
+		if (credentials && credentials.password !== password) {
+			throw new Error(
+				"[transit] the directory refused the bind: invalid credentials",
+			);
+		}
+		if (credentials && credentials.username !== username) {
+			throw new Error(
+				"[transit] the directory refused the bind: invalid credentials",
+			);
+		}
+		this.signedIn.push({ name, user });
+		return user;
+	}
+
+	override async userFromToken(name: string): Promise<TransitUser> {
+		const user = this.#identities.get(name);
+		if (!user) {
+			throw new Error(
+				`[transit] nothing declared for '${name}'. Call willReturn('${name}', …) first.`,
+			);
+		}
+		return user;
+	}
+
+	/** A sign-in through `name` was started. */
+	assertBegan(name: string): void {
+		if (!this.begun.some((entry) => entry.name === name)) {
+			throw new Error(
+				`Expected a sign-in to begin through '${name}'. ${this.#saw(this.begun.map((e) => e.name))}`,
+			);
+		}
+	}
+
+	/** A sign-in through `name` completed. */
+	assertSignedIn(name: string): void {
+		if (!this.signedIn.some((entry) => entry.name === name)) {
+			throw new Error(
+				`Expected a sign-in to complete through '${name}'. ${this.#saw(this.signedIn.map((e) => e.name))}`,
+			);
+		}
+	}
+
+	/** Nobody was signed in — what a rejected callback should leave behind. */
+	assertNobodySignedIn(): void {
+		if (this.signedIn.length > 0) {
+			throw new Error(
+				`Expected nobody to be signed in, and ${this.signedIn.length} was: ${this.signedIn.map((e) => e.name).join(", ")}`,
+			);
+		}
+	}
+
+	/** The user handed back by the last completed sign-in. */
+	lastUser(): TransitUser | undefined {
+		return this.signedIn.at(-1)?.user;
+	}
+
+	/** Forget everything recorded, keeping what was declared. */
+	reset(): void {
+		this.begun.length = 0;
+		this.signedIn.length = 0;
+	}
+
+	#saw(names: string[]): string {
+		return names.length === 0
+			? "Nothing was recorded."
+			: `Recorded: ${names.join(", ")}.`;
+	}
+}