@c9up/transit 0.1.0

package/src/drivers/SpotifyDriver.ts

@@ -0,0 +1,38 @@
+/**
+ * Spotify OAuth2 driver.
+ */
+
+import { Oauth2Driver } from "../Oauth2Driver.js";
+import type { TransitUser } from "../types.js";
+
+export class SpotifyDriver extends Oauth2Driver {
+	protected readonly provider = "Spotify";
+	protected readonly authorizeUrl = "https://accounts.spotify.com/authorize";
+	protected readonly accessTokenUrl = "https://accounts.spotify.com/api/token";
+	protected readonly userInfoUrl = "https://api.spotify.com/v1/me";
+	protected readonly defaultScopes = ["user-read-email"] as const;
+	/** Spotify wants the client credentials as HTTP Basic on the token request. */
+	protected override readonly tokenAuth = "basic" as const;
+
+	protected mapUser(raw: Record<string, unknown>): TransitUser {
+		return {
+			id: String(raw.id ?? ""),
+			email: String(raw.email ?? ""),
+			name: String(raw.display_name ?? ""),
+			nickName:
+				typeof raw.display_name === "string" ? raw.display_name : undefined,
+			avatarUrl: firstImage(raw),
+			// Spotify says nothing about the address it returns.
+			emailVerificationState: "unsupported",
+			raw,
+		};
+	}
+}
+
+/** Spotify returns a list of images; the first is the one to show. */
+function firstImage(raw: Record<string, unknown>): string | undefined {
+	const images = raw.images;
+	if (!Array.isArray(images) || images.length === 0) return undefined;
+	const url = Reflect.get(Object(images[0]), "url");
+	return typeof url === "string" && url !== "" ? url : undefined;
+}

package/src/drivers/TwitterDriver.ts

@@ -0,0 +1,55 @@
+/**
+ * X (Twitter) OAuth1 driver.
+ *
+ * The older of X's two flows. `TwitterXDriver` is the OAuth2 one, and is what
+ * a new application wants; this one exists for an application already built
+ * on OAuth1 tokens, and it is also the only flow that returns the address
+ * through `verify_credentials`.
+ */
+
+import { Oauth1Driver } from "../Oauth1Driver.js";
+import type { TransitUser } from "../types.js";
+
+export class TwitterDriver extends Oauth1Driver {
+	protected readonly provider = "X";
+	protected readonly requestTokenUrl =
+		"https://api.twitter.com/oauth/request_token";
+	/** `authenticate`, not `authorize`: a returning user is not asked twice. */
+	protected readonly authorizeUrl =
+		"https://api.twitter.com/oauth/authenticate";
+	protected readonly accessTokenUrl =
+		"https://api.twitter.com/oauth/access_token";
+	protected readonly userInfoUrl =
+		"https://api.twitter.com/1.1/account/verify_credentials.json";
+
+	protected override userInfoParams(): Record<string, string> {
+		// The address is omitted unless asked for, and only reaches an
+		// application whose X app was granted it.
+		return { include_email: "true" };
+	}
+
+	protected mapUser(raw: Record<string, unknown>): TransitUser {
+		return {
+			// `id_str`, never `id`: the numeric form loses precision past 2^53.
+			id: String(raw.id_str ?? ""),
+			email: String(raw.email ?? ""),
+			name: String(raw.name ?? raw.screen_name ?? ""),
+			nickName:
+				typeof raw.screen_name === "string" ? raw.screen_name : undefined,
+			avatarUrl: fullSizeAvatar(raw),
+			// X vouches for nothing about the address it returns.
+			emailVerificationState: "unsupported",
+			raw,
+		};
+	}
+}
+
+/**
+ * The profile carries the 48px thumbnail. The full-size original is the same
+ * URL with the `_normal` suffix removed.
+ */
+function fullSizeAvatar(raw: Record<string, unknown>): string | undefined {
+	const url = raw.profile_image_url_https;
+	if (typeof url !== "string" || url === "") return undefined;
+	return url.replace(/_normal(\.[a-z]+)$/i, "$1");
+}

package/src/drivers/TwitterXDriver.ts

@@ -0,0 +1,53 @@
+/**
+ * X (Twitter) OAuth2 driver.
+ *
+ * X requires PKCE, so this driver refuses to build a redirect without a code
+ * verifier. Mint one with `createCodeVerifier()`, store it beside the state,
+ * and hand it back to `callback()`.
+ */
+
+import { Oauth2Driver } from "../Oauth2Driver.js";
+import type { TransitUser } from "../types.js";
+
+export class TwitterXDriver extends Oauth2Driver {
+	protected readonly provider = "X";
+	protected readonly authorizeUrl = "https://x.com/i/oauth2/authorize";
+	protected readonly accessTokenUrl = "https://api.x.com/2/oauth2/token";
+	protected readonly userInfoUrl = "https://api.x.com/2/users/me";
+	protected readonly defaultScopes = [
+		"tweet.read",
+		"users.read",
+		"users.email",
+	] as const;
+	protected override readonly requiresPkce = true;
+	/** X accepts the client credentials only as HTTP Basic. */
+	protected override readonly tokenAuth = "basic" as const;
+
+	protected override userInfoParams(): Record<string, string> {
+		// Neither the picture nor the address is returned unless asked for.
+		return { "user.fields": "profile_image_url,confirmed_email" };
+	}
+
+	protected override mapUser(raw: Record<string, unknown>): TransitUser {
+		// The profile arrives wrapped: `{ data: { ... } }`.
+		const data =
+			typeof raw.data === "object" && raw.data !== null
+				? (raw.data as Record<string, unknown>)
+				: raw;
+		return {
+			id: String(data.id ?? ""),
+			email: String(data.confirmed_email ?? ""),
+			name: String(data.name ?? data.username ?? ""),
+			nickName: typeof data.username === "string" ? data.username : undefined,
+			avatarUrl:
+				typeof data.profile_image_url === "string" &&
+				data.profile_image_url !== ""
+					? data.profile_image_url
+					: undefined,
+			// The field is named `confirmed_email`, but X publishes no separate
+			// verification flag, so nothing here can be claimed.
+			emailVerificationState: "unsupported",
+			raw,
+		};
+	}
+}

package/src/dsig.ts

@@ -0,0 +1,405 @@
+/**
+ * XML Signature verification.
+ *
+ * The danger in XML-DSig is not the cryptography — it is that a signature can
+ * be perfectly valid over one part of a document while the application reads
+ * another. That is XML Signature Wrapping, and it has broken SAML
+ * implementations repeatedly. The mitigation is structural, not a check:
+ *
+ *   **This returns the element the signature actually covers, and the caller
+ *   must read that object. Never search the document again afterwards.**
+ *
+ * Everything else here exists to make that guarantee hold:
+ *
+ *   - Exactly one reference. Several is not a shape a signed assertion needs,
+ *     and it multiplies what "the signed element" could mean.
+ *   - The reference must resolve to exactly ONE element. A second element
+ *     carrying the same ID is the classic wrapping payload.
+ *   - The signature must sit inside the element it signs. A signature that
+ *     references a sibling is describing a document this refuses to reason
+ *     about.
+ *   - Only the enveloped-signature and exclusive-c14n transforms are accepted.
+ *     XPath and XSLT transforms are a way to make the digest cover something
+ *     other than the element, and XSLT is executable.
+ *   - SHA-1 is refused. Collisions against it are practical, and a signature
+ *     over attacker-influenced XML is exactly where that matters.
+ *   - The key comes from the caller, from the provider's metadata. The
+ *     certificate embedded in the document is checked against it, never
+ *     trusted on its own: verifying a document against a key it carries is
+ *     verifying it against itself.
+ */
+
+import {
+	createHash,
+	type KeyObject,
+	verify as verifySignature,
+	X509Certificate,
+} from "node:crypto";
+import { canonicalize } from "./c14n.js";
+import {
+	childrenNamed,
+	textOf,
+	walk,
+	type XmlElement,
+	type XmlNode,
+} from "./xml.js";
+
+export const DSIG_NS = "http://www.w3.org/2000/09/xmldsig#";
+const EXC_C14N = "http://www.w3.org/2001/10/xml-exc-c14n#";
+const EXC_C14N_COMMENTS = "http://www.w3.org/2001/10/xml-exc-c14n#WithComments";
+const ENVELOPED = "http://www.w3.org/2000/09/xmldsig#enveloped-signature";
+const EC_NS = "http://www.w3.org/2001/10/xml-exc-c14n#";
+
+/** Digest algorithms, by their URI. SHA-1 is absent on purpose. */
+const DIGESTS: Record<string, string> = {
+	"http://www.w3.org/2001/04/xmlenc#sha256": "sha256",
+	"http://www.w3.org/2001/04/xmldsig-more#sha384": "sha384",
+	"http://www.w3.org/2001/04/xmlenc#sha512": "sha512",
+};
+
+/** Signature algorithms, by their URI. SHA-1 is absent on purpose. */
+const SIGNATURES: Record<string, { hash: string; kind: "rsa" | "ec" }> = {
+	"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256": {
+		hash: "sha256",
+		kind: "rsa",
+	},
+	"http://www.w3.org/2001/04/xmldsig-more#rsa-sha384": {
+		hash: "sha384",
+		kind: "rsa",
+	},
+	"http://www.w3.org/2001/04/xmldsig-more#rsa-sha512": {
+		hash: "sha512",
+		kind: "rsa",
+	},
+	"http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256": {
+		hash: "sha256",
+		kind: "ec",
+	},
+	"http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384": {
+		hash: "sha384",
+		kind: "ec",
+	},
+	"http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512": {
+		hash: "sha512",
+		kind: "ec",
+	},
+};
+
+export class SignatureError extends Error {
+	constructor(message: string) {
+		super(`[transit] ${message}`);
+		this.name = "SignatureError";
+	}
+}
+
+export interface VerifyOptions {
+	/**
+	 * The provider's signing certificates, from its metadata — PEM, or the
+	 * bare base64 an `<X509Certificate>` element carries. Several are accepted
+	 * so a rotation can be prepared before it happens.
+	 */
+	certificates: string[];
+}
+
+/**
+ * Verify one signature under `root`, and answer with the element it covers.
+ *
+ * Read the returned element. Reading anything found by searching the document
+ * afterwards throws the guarantee away.
+ */
+export function verifyXmlSignature(
+	root: XmlElement,
+	options: VerifyOptions,
+): XmlElement {
+	const signatures = [...walk(root)].filter(
+		(element) =>
+			element.namespaceUri === DSIG_NS && element.local === "Signature",
+	);
+	if (signatures.length === 0) {
+		throw new SignatureError("the document carries no signature");
+	}
+	if (signatures.length > 1) {
+		// Which one covers what a reader will use is exactly the ambiguity
+		// wrapping attacks live in.
+		throw new SignatureError(
+			`the document carries ${signatures.length} signatures, and this verifies documents with one`,
+		);
+	}
+	const signature = signatures[0] as XmlElement;
+
+	const signedInfo = only(signature, "SignedInfo");
+	const method = only(signedInfo, "SignatureMethod").attributes.find(
+		(a) => a.local === "Algorithm",
+	)?.value;
+	const spec = method === undefined ? undefined : SIGNATURES[method];
+	if (spec === undefined) {
+		throw new SignatureError(
+			`the signature uses '${method ?? "no algorithm"}', which this refuses. SHA-1 and the symmetric methods are not accepted.`,
+		);
+	}
+
+	const canonicalizationMethod = only(
+		signedInfo,
+		"CanonicalizationMethod",
+	).attributes.find((a) => a.local === "Algorithm")?.value;
+	if (
+		canonicalizationMethod !== EXC_C14N &&
+		canonicalizationMethod !== EXC_C14N_COMMENTS
+	) {
+		throw new SignatureError(
+			`SignedInfo is canonicalized with '${canonicalizationMethod ?? "nothing"}', and this verifies exclusive canonicalization`,
+		);
+	}
+
+	// The signature is over SignedInfo, canonicalized. Everything the reference
+	// claims is only trustworthy once this holds.
+	const signedBytes = Buffer.from(
+		canonicalize(signedInfo, {
+			withComments: canonicalizationMethod === EXC_C14N_COMMENTS,
+		}),
+		"utf8",
+	);
+	const signatureValue = Buffer.from(
+		textOf(only(signature, "SignatureValue")).replace(/\s+/g, ""),
+		"base64",
+	);
+
+	const key = resolveKey(signature, options.certificates);
+	const holds = verifySignature(
+		spec.hash,
+		signedBytes,
+		spec.kind === "ec" ? { key, dsaEncoding: "ieee-p1363" } : key,
+		signatureValue,
+	);
+	if (!holds) {
+		throw new SignatureError("the signature does not verify");
+	}
+
+	return verifyReference(root, signature, signedInfo);
+}
+
+/**
+ * Check the digest, and answer with the element it was computed over.
+ *
+ * The element is resolved once, here, and handed back. That is the whole
+ * defence: a caller that uses this object cannot be reading a different part of
+ * the document than the one the signature covers.
+ */
+function verifyReference(
+	root: XmlElement,
+	signature: XmlElement,
+	signedInfo: XmlElement,
+): XmlElement {
+	const references = childrenNamed(signedInfo, DSIG_NS, "Reference");
+	if (references.length !== 1) {
+		throw new SignatureError(
+			`SignedInfo carries ${references.length} references, and this verifies one`,
+		);
+	}
+	const reference = references[0] as XmlElement;
+
+	const uri = reference.attributes.find((a) => a.local === "URI")?.value;
+	if (uri === undefined || !uri.startsWith("#") || uri.length < 2) {
+		throw new SignatureError(
+			`the reference points at '${uri ?? "nothing"}', and this verifies a same-document '#id' reference`,
+		);
+	}
+	const id = uri.slice(1);
+
+	const matches = [...walk(root)].filter((element) =>
+		element.attributes.some(
+			(a) => a.namespaceUri === "" && isIdAttribute(a.local) && a.value === id,
+		),
+	);
+	if (matches.length === 0) {
+		throw new SignatureError(
+			`the reference names '${id}', which is not in the document`,
+		);
+	}
+	if (matches.length > 1) {
+		// A second element carrying the signed element's ID is the classic
+		// wrapping payload: the signature stays valid, and a reader that looks
+		// the ID up finds the attacker's copy.
+		throw new SignatureError(
+			`${matches.length} elements carry the id '${id}', which is how a signature gets pointed at the wrong one`,
+		);
+	}
+	const signed = matches[0] as XmlElement;
+
+	if (!contains(signed, signature)) {
+		throw new SignatureError(
+			"the signature sits outside the element it references, which this refuses to reason about",
+		);
+	}
+
+	const { inclusivePrefixes, withComments } = readTransforms(
+		reference,
+		signature,
+	);
+
+	const digestMethod = only(reference, "DigestMethod").attributes.find(
+		(a) => a.local === "Algorithm",
+	)?.value;
+	const hash = digestMethod === undefined ? undefined : DIGESTS[digestMethod];
+	if (hash === undefined) {
+		throw new SignatureError(
+			`the digest uses '${digestMethod ?? "no algorithm"}', which this refuses. SHA-1 is not accepted.`,
+		);
+	}
+
+	// The enveloped-signature transform: the element cannot carry a digest of
+	// itself, so the signature is left out of what is hashed.
+	const omit: ReadonlySet<XmlNode> = new Set<XmlNode>([signature]);
+	const digest = createHash(hash)
+		.update(
+			canonicalize(signed, { inclusivePrefixes, withComments, omit }),
+			"utf8",
+		)
+		.digest("base64");
+
+	const expected = textOf(only(reference, "DigestValue")).replace(/\s+/g, "");
+	if (digest !== expected) {
+		throw new SignatureError(
+			"the signed element does not match its digest — it was changed after signing",
+		);
+	}
+
+	return signed;
+}
+
+/** Which transforms the reference asks for, refusing the dangerous ones. */
+function readTransforms(
+	reference: XmlElement,
+	signature: XmlElement,
+): { inclusivePrefixes: string[]; withComments: boolean } {
+	const container = childrenNamed(reference, DSIG_NS, "Transforms")[0];
+	const transforms = container
+		? childrenNamed(container, DSIG_NS, "Transform")
+		: [];
+
+	let sawEnveloped = false;
+	let inclusivePrefixes: string[] = [];
+	let withComments = false;
+
+	for (const transform of transforms) {
+		const algorithm = transform.attributes.find(
+			(a) => a.local === "Algorithm",
+		)?.value;
+		if (algorithm === ENVELOPED) {
+			sawEnveloped = true;
+			continue;
+		}
+		if (algorithm === EXC_C14N || algorithm === EXC_C14N_COMMENTS) {
+			withComments = algorithm === EXC_C14N_COMMENTS;
+			const list = childrenNamed(transform, EC_NS, "InclusiveNamespaces")[0];
+			const prefixes = list?.attributes.find(
+				(a) => a.local === "PrefixList",
+			)?.value;
+			if (prefixes) {
+				inclusivePrefixes = prefixes.split(/\s+/).filter(Boolean);
+			}
+			continue;
+		}
+		// XPath and XSLT can make the digest cover something other than the
+		// element, and one of them is executable.
+		throw new SignatureError(
+			`the reference asks for the transform '${algorithm ?? "(none)"}', which this refuses`,
+		);
+	}
+
+	if (!sawEnveloped && contains(signature.parent ?? signature, signature)) {
+		// A signature inside the element it signs has to be excluded from the
+		// digest, and the transform is how that is declared.
+		throw new SignatureError(
+			"the signature is inside the element it signs and does not declare the enveloped-signature transform",
+		);
+	}
+	return { inclusivePrefixes, withComments };
+}
+
+/**
+ * The key to verify with — the caller's, from the provider's metadata.
+ *
+ * When the document carries a certificate it must be one of them. That check
+ * gives a clear error instead of an opaque "does not verify" when a provider
+ * has rotated and the metadata has not been updated.
+ */
+function resolveKey(signature: XmlElement, certificates: string[]): KeyObject {
+	if (certificates.length === 0) {
+		throw new SignatureError(
+			"no certificate was supplied — the key has to come from the provider's metadata, never from the document itself",
+		);
+	}
+	const known = certificates.map(toCertificate);
+	const embedded = embeddedCertificate(signature);
+	if (embedded !== undefined) {
+		const match = known.find((cert) => cert.raw.equals(embedded.raw));
+		if (!match) {
+			throw new SignatureError(
+				"the document is signed with a certificate the provider's metadata does not list",
+			);
+		}
+		return match.publicKey;
+	}
+	// No certificate in the document: the metadata is all there is, which is
+	// the safer of the two cases.
+	return (known[0] as X509Certificate).publicKey;
+}
+
+function embeddedCertificate(
+	signature: XmlElement,
+): X509Certificate | undefined {
+	for (const element of walk(signature)) {
+		if (
+			element.namespaceUri === DSIG_NS &&
+			element.local === "X509Certificate"
+		) {
+			return toCertificate(textOf(element));
+		}
+	}
+	return undefined;
+}
+
+function toCertificate(value: string): X509Certificate {
+	const trimmed = value.trim();
+	const pem = trimmed.includes("BEGIN CERTIFICATE")
+		? trimmed
+		: `-----BEGIN CERTIFICATE-----\n${trimmed.replace(/\s+/g, "").replace(/(.{64})/g, "$1\n")}\n-----END CERTIFICATE-----`;
+	try {
+		return new X509Certificate(pem);
+	} catch {
+		throw new SignatureError("a certificate could not be read");
+	}
+}
+
+/** Exactly one child named `local`, or a clear refusal. */
+function only(parent: XmlElement, local: string): XmlElement {
+	const found = childrenNamed(parent, DSIG_NS, local);
+	if (found.length !== 1) {
+		throw new SignatureError(
+			`expected one <${local}> under <${parent.local}>, and there are ${found.length}`,
+		);
+	}
+	return found[0] as XmlElement;
+}
+
+/** Whether `descendant` sits inside `ancestor`, or is it. */
+function contains(ancestor: XmlElement, descendant: XmlElement): boolean {
+	for (
+		let node: XmlElement | undefined = descendant;
+		node !== undefined;
+		node = node.parent
+	) {
+		if (node === ancestor) return true;
+	}
+	return false;
+}
+
+/**
+ * SAML identifies signed elements with `ID`; other dialects use `Id` or `id`.
+ * All three are accepted, and a document mixing them is what the
+ * duplicate check above catches.
+ */
+function isIdAttribute(local: string): boolean {
+	return local === "ID" || local === "Id" || local === "id";
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+/**
+ * @c9up/transit — federated sign-in for the Ream framework.
+ *
+ * Everything that lets a person prove who they are through an authority the
+ * application does not own. Today that is OAuth1 and OAuth2, and the providers
+ * that speak them.
+ */
+
+export { type AppleKey, appleClientSecret, parseAppleUser } from "./apple.js";
+export { type CanonicalizeOptions, canonicalize } from "./c14n.js";
+export type {
+	TransitConfig,
+	TransitDriverFactory,
+	TransitProviderEntry,
+} from "./config.js";
+export { defineConfig, ldap, oidc, saml, socials } from "./config.js";
+export { type AppleConfig, AppleDriver } from "./drivers/AppleDriver.js";
+export { DiscordDriver } from "./drivers/DiscordDriver.js";
+export { FacebookDriver } from "./drivers/FacebookDriver.js";
+export { GitHubDriver } from "./drivers/GitHubDriver.js";
+export { GoogleDriver } from "./drivers/GoogleDriver.js";
+export { type LdapConfig, LdapDirectory } from "./drivers/LdapDirectory.js";
+export { LinkedInDriver } from "./drivers/LinkedInDriver.js";
+export { LinkedInOpenidConnectDriver } from "./drivers/LinkedInOpenidConnectDriver.js";
+export { type OidcConfig, OidcDriver } from "./drivers/OidcDriver.js";
+export { type SamlConfig, SamlDriver } from "./drivers/SamlDriver.js";
+export { SpotifyDriver } from "./drivers/SpotifyDriver.js";
+export { TwitterDriver } from "./drivers/TwitterDriver.js";
+export { TwitterXDriver } from "./drivers/TwitterXDriver.js";
+export type { IdTokenClaims, Jwk, SupportedAlg } from "./jwt.js";
+export {
+	LdapConnection,
+	type LdapEntry,
+	LdapError,
+	type LdapFilter,
+	type LdapOptions,
+} from "./ldap.js";
+export { Oauth1Driver } from "./Oauth1Driver.js";
+export { createCodeVerifier, Oauth2Driver } from "./Oauth2Driver.js";
+export type { OidcMetadata, RemoteOptions } from "./oidc.js";
+export {
+	type AssertionReplayStore,
+	MemoryAssertionReplayStore,
+	RedisAssertionReplayStore,
+	type ReplayRedisClient,
+	type ReplayRedisResolver,
+	replayStores,
+} from "./replay.js";
+export {
+	assertionInside,
+	assertResponseSucceeded,
+	SAML_ASSERTION_NS,
+	SAML_PROTOCOL_NS,
+	SamlError,
+	type SamlExpectations,
+	type SamlIdentity,
+	validateAssertion,
+} from "./saml.js";
+export { TransitManager } from "./TransitManager.js";
+export type { TransitAppContext } from "./TransitProvider.js";
+export { default as TransitProvider } from "./TransitProvider.js";
+export type {
+	DirectoryDriver,
+	EmailVerificationState,
+	OAuthConfig,
+	OAuthToken,
+	RedirectRequest,
+	TransitDriver,
+	TransitEntry,
+	TransitUser,
+} from "./types.js";
+export { assertOAuthState, isDirectory } from "./types.js";
+export {
+	childrenNamed,
+	findByAttribute,
+	parseXml,
+	resolvePrefix,
+	textOf,
+	walk,
+	XML_NS,
+	type XmlAttribute,
+	type XmlElement,
+	type XmlNamespace,
+	type XmlNode,
+} from "./xml.js";