@c9up/transit 0.1.0

package/src/TransitProvider.ts

@@ -0,0 +1,51 @@
+/**
+ * Wires `config/transit.ts` into the container.
+ *
+ * Transit does not import `@c9up/ream`: the slice of the host it needs is
+ * duck-typed below, which is what keeps the package publishable on its own and
+ * usable from a host that is not Ream.
+ */
+
+import type { TransitConfig } from "./config.js";
+import { setTransit } from "./services/main.js";
+import { TransitManager } from "./TransitManager.js";
+
+interface TransitContainer {
+	singleton(token: unknown, factory: () => unknown): void;
+	resolve<T = unknown>(token: unknown): Promise<T>;
+}
+
+interface TransitConfigStore {
+	get<T = unknown>(key: string): T | undefined;
+}
+
+export interface TransitAppContext {
+	container: TransitContainer;
+	config: TransitConfigStore;
+}
+
+export default class TransitProvider {
+	constructor(protected app: TransitAppContext) {}
+
+	register(): void {
+		this.app.container.singleton(TransitManager, () => {
+			const config = this.app.config.get<TransitConfig>("transit") ?? {};
+			const manager = new TransitManager();
+			for (const [name, entry] of Object.entries(config)) {
+				manager.register(name, typeof entry === "function" ? entry() : entry);
+			}
+			return manager;
+		});
+		// String alias, so a consumer that cannot import Transit still resolves
+		// it — the same convention the other providers follow.
+		this.app.container.singleton("transit", () =>
+			this.app.container.resolve<TransitManager>(TransitManager),
+		);
+	}
+
+	async boot(): Promise<void> {
+		setTransit(
+			await this.app.container.resolve<TransitManager>(TransitManager),
+		);
+	}
+}

package/src/apple.ts

@@ -0,0 +1,101 @@
+/**
+ * The two things Sign in with Apple does differently from every other OpenID
+ * Connect provider.
+ *
+ * Apple has no client secret. It has a private key, and expects a short-lived
+ * JWT minted from it on every token request — which is why `clientSecret` is
+ * allowed to be a function.
+ *
+ * And it sends the user's name exactly ONCE, in the body of the first consent
+ * callback, never in a token and never again. An application that does not
+ * store it then has no way to ask for it later.
+ */
+
+import { createPrivateKey, sign as signData } from "node:crypto";
+
+export interface AppleKey {
+	/** The Services ID (web) or App ID this signs for. */
+	clientId: string;
+	/** The ten-character Team ID from the developer account. */
+	teamId: string;
+	/** The Key ID of the .p8 this signs with. */
+	keyId: string;
+	/** The contents of the .p8 file, PEM as Apple issues it. */
+	privateKey: string;
+}
+
+/** Apple rejects a secret valid for more than six months; minutes are plenty. */
+const LIFETIME_SECONDS = 300;
+
+/**
+ * Mint the JWT Apple takes in place of a client secret.
+ *
+ * Signed ES256 with the .p8, naming the team as issuer and the client as
+ * subject. Minted per request rather than cached: it costs one signature, and
+ * a long-lived one is a credential sitting in memory for no reason.
+ */
+export function appleClientSecret(
+	key: AppleKey,
+	now: number = Math.floor(Date.now() / 1000),
+): string {
+	const header = { alg: "ES256", kid: key.keyId, typ: "JWT" };
+	const claims = {
+		iss: key.teamId,
+		iat: now,
+		exp: now + LIFETIME_SECONDS,
+		aud: "https://appleid.apple.com",
+		sub: key.clientId,
+	};
+
+	const signingInput = `${b64(header)}.${b64(claims)}`;
+	// JOSE wants R concatenated with S; node emits DER unless told, and Apple
+	// rejects DER.
+	const signature = signData("sha256", Buffer.from(signingInput, "ascii"), {
+		key: createPrivateKey(key.privateKey),
+		dsaEncoding: "ieee-p1363",
+	});
+	return `${signingInput}.${signature.toString("base64url")}`;
+}
+
+/**
+ * Read the `user` field of Apple's first consent callback.
+ *
+ * It arrives as JSON in the POST body, on that one request only. Store what
+ * comes out — the id_token never carries a name, and a second sign-in by the
+ * same person will not carry one either.
+ *
+ * Returns `undefined` for anything unreadable rather than throwing: a returning
+ * user simply has no `user` field, and that is the normal case.
+ */
+export function parseAppleUser(
+	value: unknown,
+): { name?: string; email?: string } | undefined {
+	if (typeof value !== "string" || value === "") return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		return undefined;
+	}
+	if (typeof parsed !== "object" || parsed === null) return undefined;
+
+	const email = Reflect.get(parsed, "email");
+	const rawName = Reflect.get(parsed, "name");
+	const name =
+		typeof rawName === "object" && rawName !== null
+			? [Reflect.get(rawName, "firstName"), Reflect.get(rawName, "lastName")]
+					.filter(
+						(part): part is string => typeof part === "string" && part !== "",
+					)
+					.join(" ")
+			: undefined;
+
+	const out: { name?: string; email?: string } = {};
+	if (name) out.name = name;
+	if (typeof email === "string" && email !== "") out.email = email;
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function b64(value: unknown): string {
+	return Buffer.from(JSON.stringify(value)).toString("base64url");
+}

package/src/ber.ts

@@ -0,0 +1,175 @@
+/**
+ * The encoding LDAP speaks: BER, the subset of it LDAP actually uses.
+ *
+ * This exists so that nothing an application passes ever becomes part of a
+ * string that a server then parses. A search filter here is a structure, not
+ * text — its values are written as length-prefixed octets, so a username
+ * containing `)(uid=*` is a username containing those characters and cannot
+ * become syntax. LDAP injection is not escaped away here; it is unrepresentable.
+ */
+
+/** Universal tags, and the two LDAP builds everything else from. */
+export const BOOLEAN = 0x01;
+export const INTEGER = 0x02;
+export const OCTET_STRING = 0x04;
+export const ENUMERATED = 0x0a;
+export const SEQUENCE = 0x30;
+
+/** `[APPLICATION n]`, constructed. */
+export const application = (n: number): number => 0x60 | n;
+/** `[APPLICATION n]`, primitive — which a couple of LDAP operations are. */
+export const applicationPrimitive = (n: number): number => 0x40 | n;
+/** `[n]` context-specific, constructed. */
+export const context = (n: number): number => 0xa0 | n;
+/** `[n]` context-specific, primitive. */
+export const contextPrimitive = (n: number): number => 0x80 | n;
+
+export class BerError extends Error {
+	constructor(message: string) {
+		super(`[transit] ${message}`);
+		this.name = "BerError";
+	}
+}
+
+/** One tag-length-value element. */
+export function encode(tag: number, value: Buffer): Buffer {
+	return Buffer.concat([Buffer.from([tag]), encodeLength(value.length), value]);
+}
+
+export function encodeInteger(value: number, tag = INTEGER): Buffer {
+	if (!Number.isSafeInteger(value)) {
+		throw new BerError(`cannot encode ${value} as an integer`);
+	}
+	const bytes: number[] = [];
+	let remaining = value;
+	do {
+		bytes.unshift(remaining & 0xff);
+		remaining >>= 8;
+	} while (remaining !== 0 && remaining !== -1);
+	// A leading bit set on a positive number would read as negative.
+	if (value >= 0 && (bytes[0] as number) & 0x80) bytes.unshift(0);
+	if (value < 0 && !((bytes[0] as number) & 0x80)) bytes.unshift(0xff);
+	return encode(tag, Buffer.from(bytes));
+}
+
+export function encodeString(value: string, tag = OCTET_STRING): Buffer {
+	// The value is written as length-prefixed bytes, never interpolated. That
+	// is what makes injection impossible rather than merely escaped.
+	return encode(tag, Buffer.from(value, "utf8"));
+}
+
+export function encodeBoolean(value: boolean, tag = BOOLEAN): Buffer {
+	return encode(tag, Buffer.from([value ? 0xff : 0x00]));
+}
+
+export function encodeSequence(parts: Buffer[], tag = SEQUENCE): Buffer {
+	return encode(tag, Buffer.concat(parts));
+}
+
+/** A decoded element: its tag, its contents, and where it ended. */
+export interface BerElement {
+	tag: number;
+	value: Buffer;
+	end: number;
+}
+
+/** Read one element at `offset`. */
+export function decode(buffer: Buffer, offset = 0): BerElement {
+	if (offset >= buffer.length) {
+		throw new BerError("the message ends where an element was expected");
+	}
+	const tag = buffer[offset] as number;
+	const { length, at } = decodeLength(buffer, offset + 1);
+	const end = at + length;
+	if (end > buffer.length) {
+		throw new BerError(
+			`an element claims ${length} bytes and the message holds ${buffer.length - at}`,
+		);
+	}
+	return { tag, value: buffer.subarray(at, end), end };
+}
+
+/** Every element inside a constructed one. */
+export function decodeSequence(value: Buffer): BerElement[] {
+	const out: BerElement[] = [];
+	let offset = 0;
+	while (offset < value.length) {
+		const element = decode(value, offset);
+		out.push(element);
+		offset = element.end;
+	}
+	return out;
+}
+
+export function decodeInteger(value: Buffer): number {
+	if (value.length === 0) throw new BerError("an integer has no bytes");
+	if (value.length > 6) {
+		// Beyond this a result code or message id is not something this reads.
+		throw new BerError(`an integer of ${value.length} bytes is out of range`);
+	}
+	let out = (value[0] as number) & 0x80 ? -1 : 0;
+	for (const byte of value) out = out * 256 + byte;
+	return out;
+}
+
+export function decodeString(value: Buffer): string {
+	return value.toString("utf8");
+}
+
+/**
+ * How many bytes a whole message occupies, or `undefined` while it is still
+ * arriving. LDAP runs over a stream, so a read can stop anywhere.
+ */
+export function messageLength(buffer: Buffer): number | undefined {
+	if (buffer.length < 2) return undefined;
+	const first = buffer[1] as number;
+	if (first < 0x80) return 2 + first;
+	const count = first & 0x7f;
+	if (count === 0 || count > 4) {
+		throw new BerError("a message declares a length this refuses to read");
+	}
+	if (buffer.length < 2 + count) return undefined;
+	let length = 0;
+	for (let i = 0; i < count; i += 1) {
+		length = length * 256 + (buffer[2 + i] as number);
+	}
+	return 2 + count + length;
+}
+
+function encodeLength(length: number): Buffer {
+	if (length < 0x80) return Buffer.from([length]);
+	const bytes: number[] = [];
+	let remaining = length;
+	while (remaining > 0) {
+		bytes.unshift(remaining & 0xff);
+		remaining = Math.floor(remaining / 256);
+	}
+	return Buffer.from([0x80 | bytes.length, ...bytes]);
+}
+
+function decodeLength(
+	buffer: Buffer,
+	offset: number,
+): { length: number; at: number } {
+	if (offset >= buffer.length) {
+		throw new BerError("an element has no length");
+	}
+	const first = buffer[offset] as number;
+	if (first < 0x80) return { length: first, at: offset + 1 };
+	const count = first & 0x7f;
+	if (count === 0) {
+		// Indefinite length is legal BER and not legal LDAP; accepting it would
+		// mean scanning for a terminator supplied by the other side.
+		throw new BerError(
+			"an element uses an indefinite length, which LDAP does not",
+		);
+	}
+	if (count > 4 || offset + 1 + count > buffer.length) {
+		throw new BerError("an element declares a length this refuses to read");
+	}
+	let length = 0;
+	for (let i = 0; i < count; i += 1) {
+		length = length * 256 + (buffer[offset + 1 + i] as number);
+	}
+	return { length, at: offset + 1 + count };
+}

package/src/c14n.ts

@@ -0,0 +1,187 @@
+/**
+ * Exclusive XML Canonicalization (`xml-exc-c14n#`).
+ *
+ * A signature is over BYTES, and two parties only agree on which bytes if they
+ * agree on this algorithm exactly. Every rule below comes from the
+ * specification, and the awkward ones are the ones that matter:
+ *
+ *   - Only namespaces an element **visibly utilizes** are written out, and only
+ *     when an output ancestor has not already written the same prefix with the
+ *     same value. That is what makes a signed fragment survive being moved
+ *     between documents — and it is the whole reason exclusive exists.
+ *   - An unprefixed attribute is in NO namespace, so it never makes the default
+ *     namespace visibly utilized.
+ *   - The `xml` prefix is bound by the XML specification and is never declared.
+ *
+ * Getting any of these wrong yields a canonical form that differs from the
+ * signer's by a few bytes, and every signature then fails — or, worse, one is
+ * accepted over a document that is not the one that was signed.
+ */
+
+import {
+	resolvePrefix,
+	XML_NS,
+	type XmlAttribute,
+	type XmlElement,
+	type XmlNode,
+} from "./xml.js";
+
+export interface CanonicalizeOptions {
+	/**
+	 * Prefixes to treat the inclusive way, from a `<InclusiveNamespaces
+	 * PrefixList="…">` transform parameter.
+	 */
+	inclusivePrefixes?: string[];
+	/** Comments are excluded unless the algorithm says otherwise. */
+	withComments?: boolean;
+	/**
+	 * Nodes to leave out of the output — what the enveloped-signature transform
+	 * needs, since an element cannot carry a digest of itself.
+	 */
+	omit?: ReadonlySet<XmlNode>;
+}
+
+/** The canonical form of an element and everything under it. */
+export function canonicalize(
+	element: XmlElement,
+	options: CanonicalizeOptions = {},
+): string {
+	const out: string[] = [];
+	writeElement(element, out, new Map(), options);
+	return out.join("");
+}
+
+/**
+ * The prefixes this element makes visible: its own, and those of its
+ * attributes. The default namespace counts only when the element itself has no
+ * prefix.
+ */
+function visiblyUtilized(
+	element: XmlElement,
+	inclusivePrefixes: string[],
+): Set<string> {
+	const used = new Set<string>([element.prefix]);
+	for (const attribute of element.attributes) {
+		if (attribute.prefix !== "") used.add(attribute.prefix);
+	}
+	// The prefix list is handled inclusively: a listed prefix is rendered
+	// whenever it is in scope, utilized or not.
+	for (const prefix of inclusivePrefixes) {
+		if (resolvePrefix(element, prefix) !== undefined) used.add(prefix);
+	}
+	// Never declared — the specification binds it.
+	used.delete("xml");
+	return used;
+}
+
+function writeElement(
+	element: XmlElement,
+	out: string[],
+	rendered: Map<string, string>,
+	options: CanonicalizeOptions,
+): void {
+	const inclusive = options.inclusivePrefixes ?? [];
+	const utilized = [...visiblyUtilized(element, inclusive)].sort(compare);
+
+	const declarations: Array<[prefix: string, uri: string]> = [];
+	const childRendered = new Map(rendered);
+
+	for (const prefix of utilized) {
+		const uri = resolvePrefix(element, prefix) ?? "";
+		if (prefix === "" && uri === "") {
+			// `xmlns=""` is written only to undo a default namespace an output
+			// ancestor put in scope. Writing it otherwise is noise the signer
+			// did not produce.
+			if ((rendered.get("") ?? "") !== "") {
+				declarations.push(["", ""]);
+				childRendered.set("", "");
+			}
+			continue;
+		}
+		if (rendered.get(prefix) !== uri) {
+			declarations.push([prefix, uri]);
+			childRendered.set(prefix, uri);
+		}
+	}
+
+	out.push("<", element.qname);
+	for (const [prefix, uri] of declarations) {
+		out.push(
+			" ",
+			prefix === "" ? "xmlns" : `xmlns:${prefix}`,
+			'="',
+			escapeAttribute(uri),
+			'"',
+		);
+	}
+	for (const attribute of [...element.attributes].sort(byNamespaceThenLocal)) {
+		out.push(" ", attribute.qname, '="', escapeAttribute(attribute.value), '"');
+	}
+	out.push(">");
+
+	for (const child of element.children) {
+		if (options.omit?.has(child)) continue;
+		writeNode(child, out, childRendered, options);
+	}
+
+	// Empty elements are written as a start/end pair, never self-closed.
+	out.push("</", element.qname, ">");
+}
+
+function writeNode(
+	node: XmlNode,
+	out: string[],
+	rendered: Map<string, string>,
+	options: CanonicalizeOptions,
+): void {
+	switch (node.type) {
+		case "element":
+			writeElement(node, out, rendered, options);
+			return;
+		case "text":
+			out.push(escapeText(node.value));
+			return;
+		case "comment":
+			if (options.withComments) out.push("<!--", node.value, "-->");
+			return;
+		case "instruction":
+			out.push(
+				"<?",
+				node.target,
+				node.data === "" ? "" : ` ${node.data}`,
+				"?>",
+			);
+			return;
+	}
+}
+
+/** Namespace URI first, then local name; an empty URI sorts least. */
+function byNamespaceThenLocal(a: XmlAttribute, b: XmlAttribute): number {
+	const uri = compare(a.namespaceUri, b.namespaceUri);
+	return uri !== 0 ? uri : compare(a.local, b.local);
+}
+
+/** Byte order, which is what the specification means by lexicographic here. */
+function compare(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function escapeText(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/\r/g, "&#xD;");
+}
+
+function escapeAttribute(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/"/g, "&quot;")
+		.replace(/\t/g, "&#x9;")
+		.replace(/\n/g, "&#xA;")
+		.replace(/\r/g, "&#xD;");
+}
+
+export { XML_NS };

package/src/config.ts

@@ -0,0 +1,160 @@
+/**
+ * Author-time config for `config/transit.ts`.
+ *
+ *   import { defineConfig, socials } from '@c9up/transit'
+ *
+ *   export default defineConfig({
+ *     google: socials.google({
+ *       clientId: env.get('GOOGLE_CLIENT_ID'),
+ *       clientSecret: env.get('GOOGLE_CLIENT_SECRET'),
+ *       callbackUrl: 'https://acme.test/auth/google/callback',
+ *     }),
+ *   })
+ *
+ * The keys are yours. Two entries may reach the same provider with different
+ * credentials — a `staff` sign-in and a `customers` one, both on Google — and
+ * `use(name)` asks for the key, not for the provider.
+ */
+
+import { type AppleConfig, AppleDriver } from "./drivers/AppleDriver.js";
+import { DiscordDriver } from "./drivers/DiscordDriver.js";
+import { FacebookDriver } from "./drivers/FacebookDriver.js";
+import { GitHubDriver } from "./drivers/GitHubDriver.js";
+import { GoogleDriver } from "./drivers/GoogleDriver.js";
+import { type LdapConfig, LdapDirectory } from "./drivers/LdapDirectory.js";
+import { LinkedInDriver } from "./drivers/LinkedInDriver.js";
+import { LinkedInOpenidConnectDriver } from "./drivers/LinkedInOpenidConnectDriver.js";
+import { type OidcConfig, OidcDriver } from "./drivers/OidcDriver.js";
+import { type SamlConfig, SamlDriver } from "./drivers/SamlDriver.js";
+import { SpotifyDriver } from "./drivers/SpotifyDriver.js";
+import { TwitterDriver } from "./drivers/TwitterDriver.js";
+import { TwitterXDriver } from "./drivers/TwitterXDriver.js";
+import type { OAuthConfig, TransitEntry } from "./types.js";
+
+/** A provider, built when the manager is. */
+export type TransitDriverFactory = () => TransitEntry;
+
+/** One declared provider: the driver itself, or a factory answering one. */
+export type TransitProviderEntry = TransitEntry | TransitDriverFactory;
+
+export type TransitConfig = Record<string, TransitProviderEntry>;
+
+export function defineConfig<T extends TransitConfig>(config: T): T {
+	return config;
+}
+
+/**
+ * The social providers Transit speaks to.
+ *
+ * Factories are lazy, so a config naming a provider this environment never
+ * selects costs nothing to declare.
+ */
+/**
+ * Any provider that speaks OpenID Connect, from its issuer alone — Keycloak,
+ * Auth0, Okta, Entra ID, Authentik, Zitadel, and the rest.
+ *
+ *   work: oidc({
+ *     issuer: 'https://id.acme.com',
+ *     clientId: env.get('OIDC_CLIENT_ID'),
+ *     clientSecret: env.get('OIDC_CLIENT_SECRET'),
+ *     callbackUrl: 'https://acme.test/auth/work/callback',
+ *   })
+ *
+ * The endpoints, the signing keys and the algorithms come from what the
+ * provider publishes, so there is nothing else to configure and nothing to
+ * update when it rotates a key.
+ */
+export function oidc(config: OidcConfig): TransitDriverFactory {
+	return () => new OidcDriver(config);
+}
+
+/**
+ * A SAML 2.0 identity provider — the enterprise directories that speak it:
+ * Okta, Entra ID, ADFS, OneLogin, Shibboleth.
+ *
+ *   corp: saml({
+ *     entityId: 'https://acme.test/saml',
+ *     callbackUrl: 'https://acme.test/saml/acs',
+ *     issuer: 'https://idp.acme.test/metadata',
+ *     signOnUrl: 'https://idp.acme.test/sso',
+ *     certificates: [env.get('IDP_CERTIFICATE')],
+ *   })
+ *
+ * The certificates come from the provider's metadata and nowhere else: a
+ * response is never verified against a key it carries itself.
+ */
+export function saml(config: SamlConfig): TransitDriverFactory {
+	return () => new SamlDriver(config);
+}
+
+/**
+ * An LDAP or Active Directory directory.
+ *
+ *   staff: ldap({
+ *     url: 'ldaps://directory.acme.test',
+ *     baseDn: 'dc=acme,dc=test',
+ *     loginAttribute: 'uid',
+ *     bindDn: 'cn=reader,dc=acme,dc=test',
+ *     bindPassword: env.get('LDAP_PASSWORD'),
+ *   })
+ *
+ * Reached with `transit.authenticate(name, username, password)`: nothing is
+ * redirected, so there is no `begin()` for it.
+ */
+export function ldap(config: LdapConfig): TransitDriverFactory {
+	return () => new LdapDirectory(config);
+}
+
+export const socials = {
+	/**
+	 * Sign in with Apple. Required on iOS as soon as another social sign-in is
+	 * offered.
+	 *
+	 * It takes a key rather than a secret — the Services ID, the Team ID, the
+	 * Key ID and the contents of the `.p8` — and its callback arrives as a
+	 * POST, because asking for a name forces `response_mode=form_post`. The
+	 * name comes once, in that POST: read it with `parseAppleUser` and store
+	 * it, because Apple never sends it again.
+	 */
+	apple(config: AppleConfig): TransitDriverFactory {
+		return () => new AppleDriver(config);
+	},
+	discord(config: OAuthConfig): TransitDriverFactory {
+		return () => new DiscordDriver(config);
+	},
+	facebook(config: OAuthConfig): TransitDriverFactory {
+		return () => new FacebookDriver(config);
+	},
+	github(config: OAuthConfig): TransitDriverFactory {
+		return () => new GitHubDriver(config);
+	},
+	google(config: OAuthConfig): TransitDriverFactory {
+		return () => new GoogleDriver(config);
+	},
+	/**
+	 * LinkedIn through the member API, for an application whose LinkedIn app
+	 * holds `r_liteprofile` / `r_emailaddress`.
+	 */
+	linkedin(config: OAuthConfig): TransitDriverFactory {
+		return () => new LinkedInDriver(config);
+	},
+	/** LinkedIn through OpenID Connect — what a new application is issued. */
+	linkedinOpenidConnect(config: OAuthConfig): TransitDriverFactory {
+		return () => new LinkedInOpenidConnectDriver(config);
+	},
+	spotify(config: OAuthConfig): TransitDriverFactory {
+		return () => new SpotifyDriver(config);
+	},
+	/**
+	 * X through OAuth1 — the older flow, and the one whose profile call returns
+	 * the address. Its redirect needs a request token from X, so it is reached
+	 * through `begin()` rather than `redirect()`.
+	 */
+	twitter(config: OAuthConfig): TransitDriverFactory {
+		return () => new TwitterDriver(config);
+	},
+	/** X through OAuth2. It requires PKCE, which `begin()` handles. */
+	twitterX(config: OAuthConfig): TransitDriverFactory {
+		return () => new TwitterXDriver(config);
+	},
+};