@c9up/transit 0.1.0

package/src/configure.ts

@@ -0,0 +1,47 @@
+/**
+ * `ream configure @c9up/transit` — wire federated sign-in in one command.
+ *
+ * The provider alone is not enough: it reads `config/transit.ts`, and a package
+ * registered without one falls back to a default that is rarely the one an
+ * application wants. Writing both together is what makes `ream add` mean
+ * installed AND working.
+ */
+
+interface Codemods {
+	addProvider(importPath: string): Promise<void>;
+	addEnvVars(vars: Record<string, string>): Promise<void>;
+	writeFile(
+		filePath: string,
+		content: string,
+		options?: { force?: boolean },
+	): Promise<void>;
+}
+
+export async function configure(codemods: Codemods): Promise<void> {
+	// The config below reads these, so they are declared here. Writing the file
+	// without them leaves an application whose config asks the environment for
+	// something nothing ever put there.
+	await codemods.addEnvVars({
+		GOOGLE_CLIENT_ID: "",
+		GOOGLE_CLIENT_SECRET: "",
+	});
+
+	await codemods.addProvider("@c9up/transit/provider");
+	await codemods.writeFile(
+		"config/transit.ts",
+		`import { defineConfig, socials } from '@c9up/transit'
+import env from '#start/env'
+
+export default defineConfig({
+  // The key is yours: it is what \`transit.begin(name)\` asks for.
+  google: socials.google({
+    clientId: env.get('GOOGLE_CLIENT_ID', ''),
+    clientSecret: env.get('GOOGLE_CLIENT_SECRET', ''),
+    callbackUrl: 'http://localhost:3333/auth/google/callback',
+  }),
+
+  // An OpenID Connect provider needs only its issuer:
+  // work: oidc({ issuer: env.get('OIDC_ISSUER'), clientId, clientSecret, callbackUrl }),
+})`,
+	);
+}

package/src/drivers/AppleDriver.ts

@@ -0,0 +1,69 @@
+/**
+ * Sign in with Apple.
+ *
+ * Apple speaks OpenID Connect, so most of this is the generic driver. Three
+ * things differ, and each is a place implementations get caught:
+ *
+ *   - There is no client secret. Apple takes a short-lived JWT signed with the
+ *     `.p8` private key from the developer account.
+ *   - The callback arrives as a **POST**, not a redirect with a query string,
+ *     because asking for a name or an address forces `response_mode=form_post`.
+ *   - The name is sent **once**, in that first POST, and never again.
+ *
+ * Apple publishes no userinfo endpoint: everything there is comes from the
+ * id_token.
+ */
+
+import { type AppleKey, appleClientSecret } from "../apple.js";
+import type { TransitUser } from "../types.js";
+import { OidcDriver } from "./OidcDriver.js";
+
+export interface AppleConfig extends AppleKey {
+	callbackUrl: string;
+	/** Default `["name", "email"]`. */
+	scopes?: string[];
+	/** Extra parameters on the authorize URL. */
+	authorizeParams?: Record<string, string>;
+}
+
+export class AppleDriver extends OidcDriver {
+	constructor(config: AppleConfig) {
+		super({
+			issuer: "https://appleid.apple.com",
+			clientId: config.clientId,
+			clientSecret: () => appleClientSecret(config),
+			callbackUrl: config.callbackUrl,
+			scopes: config.scopes ?? ["name", "email"],
+			authorizeParams: {
+				// Apple refuses to send a name or an address back on a redirect,
+				// so the callback route has to accept a POST.
+				response_mode: "form_post",
+				...config.authorizeParams,
+			},
+			// Apple has no userinfo endpoint; asking would be one failed request
+			// per sign-in.
+			userinfo: false,
+		});
+	}
+
+	/**
+	 * Apple sends `email_verified` and `is_private_email` as the strings
+	 * `"true"` / `"false"`. Read as a boolean, a verified address reads as
+	 * unverified — and an application that gates account linking on that would
+	 * refuse every Apple sign-in.
+	 */
+	protected override mapUser(raw: Record<string, unknown>): TransitUser {
+		const user = super.mapUser(raw);
+		if (user.email === "") return user;
+		return {
+			...user,
+			emailVerificationState: appleFlag(raw.email_verified)
+				? "verified"
+				: "unverified",
+		};
+	}
+}
+
+function appleFlag(value: unknown): boolean {
+	return value === true || value === "true";
+}

package/src/drivers/DiscordDriver.ts

@@ -0,0 +1,50 @@
+/**
+ * Discord OAuth2 driver.
+ */
+
+import { Oauth2Driver } from "../Oauth2Driver.js";
+import type { TransitUser } from "../types.js";
+
+export class DiscordDriver extends Oauth2Driver {
+	protected readonly provider = "Discord";
+	protected readonly authorizeUrl = "https://discord.com/oauth2/authorize";
+	protected readonly accessTokenUrl = "https://discord.com/api/oauth2/token";
+	protected readonly userInfoUrl = "https://discord.com/api/users/@me";
+	/** `email` is what makes the address present at all; `identify` is the rest. */
+	protected readonly defaultScopes = ["identify", "email"] as const;
+
+	protected mapUser(raw: Record<string, unknown>): TransitUser {
+		const id = String(raw.id ?? "");
+		return {
+			id,
+			email: String(raw.email ?? ""),
+			name: String(raw.global_name ?? raw.username ?? ""),
+			nickName: typeof raw.username === "string" ? raw.username : undefined,
+			avatarUrl: avatarUrl(id, raw),
+			// Discord reports it only when the `email` scope was granted.
+			emailVerificationState:
+				"verified" in raw
+					? raw.verified === true
+						? "verified"
+						: "unverified"
+					: "unsupported",
+			raw,
+		};
+	}
+}
+
+/**
+ * Discord serves avatars from a CDN path built from the id and the hash, and
+ * animated ones only as `.gif`. An account with no avatar has a default one
+ * derived from its id.
+ */
+function avatarUrl(id: string, raw: Record<string, unknown>): string {
+	const hash = raw.avatar;
+	if (typeof hash !== "string" || hash === "") {
+		// Post-migration accounts (no discriminator) index the defaults by id.
+		const index = (BigInt(id || "0") >> 22n) % 6n;
+		return `https://cdn.discordapp.com/embed/avatars/${index}.png`;
+	}
+	const extension = hash.startsWith("a_") ? "gif" : "png";
+	return `https://cdn.discordapp.com/avatars/${id}/${hash}.${extension}`;
+}

package/src/drivers/FacebookDriver.ts

@@ -0,0 +1,53 @@
+/**
+ * Facebook OAuth2 driver.
+ */
+
+import { Oauth2Driver } from "../Oauth2Driver.js";
+import type { TransitUser } from "../types.js";
+
+/** The Graph API returns nothing but the id unless the fields are asked for. */
+const USER_FIELDS = [
+	"name",
+	"first_name",
+	"last_name",
+	"link",
+	"email",
+	"picture.width(400).height(400)",
+] as const;
+
+export class FacebookDriver extends Oauth2Driver {
+	protected readonly provider = "Facebook";
+	protected readonly authorizeUrl =
+		"https://www.facebook.com/v21.0/dialog/oauth";
+	protected readonly accessTokenUrl =
+		"https://graph.facebook.com/v21.0/oauth/access_token";
+	protected readonly userInfoUrl = "https://graph.facebook.com/v21.0/me";
+	protected readonly defaultScopes = ["email"] as const;
+
+	protected override userInfoParams(): Record<string, string> {
+		return { fields: USER_FIELDS.join(",") };
+	}
+
+	protected mapUser(raw: Record<string, unknown>): TransitUser {
+		return {
+			id: String(raw.id ?? ""),
+			// The address is absent unless the user granted the `email` scope.
+			email: String(raw.email ?? ""),
+			name: String(raw.name ?? ""),
+			nickName: typeof raw.name === "string" ? raw.name : undefined,
+			avatarUrl: pictureUrl(raw),
+			emailVerificationState: "unsupported",
+			raw,
+		};
+	}
+}
+
+/** The picture arrives nested as `picture.data.url`. */
+function pictureUrl(raw: Record<string, unknown>): string | undefined {
+	const picture = raw.picture;
+	if (typeof picture !== "object" || picture === null) return undefined;
+	const data = Reflect.get(picture, "data");
+	if (typeof data !== "object" || data === null) return undefined;
+	const url = Reflect.get(data, "url");
+	return typeof url === "string" && url !== "" ? url : undefined;
+}

package/src/drivers/GitHubDriver.ts

@@ -0,0 +1,91 @@
+/**
+ * GitHub OAuth2 driver.
+ */
+
+import { Oauth2Driver, str } from "../Oauth2Driver.js";
+import type { TransitUser } from "../types.js";
+
+const EMAILS_URL = "https://api.github.com/user/emails";
+
+/** One entry of `/user/emails`. */
+interface GitHubEmail {
+	email: string;
+	primary: boolean;
+	verified: boolean;
+}
+
+export class GitHubDriver extends Oauth2Driver {
+	protected readonly provider = "GitHub";
+	protected readonly authorizeUrl = "https://github.com/login/oauth/authorize";
+	protected readonly accessTokenUrl =
+		"https://github.com/login/oauth/access_token";
+	protected readonly userInfoUrl = "https://api.github.com/user";
+	protected readonly defaultScopes = ["read:user", "user:email"] as const;
+
+	/**
+	 * An account whose address is private returns `email: null` from `/user`,
+	 * which is most accounts. The address then lives behind `/user/emails`,
+	 * which also says whether GitHub verified it.
+	 */
+	protected override async fetchUser(
+		accessToken: string,
+	): Promise<TransitUser> {
+		const raw = await this.get(this.userInfoUrl, accessToken);
+		const user = this.mapUser(raw);
+		if (user.email !== "") return user;
+
+		const found = await this.fetchEmail(accessToken);
+		if (found === undefined) return user;
+		return {
+			...user,
+			email: found.email,
+			emailVerificationState: found.verified ? "verified" : "unverified",
+		};
+	}
+
+	/**
+	 * The verified primary address, or the best available one. Returns
+	 * `undefined` when the token was not granted `user:email` — a sign-in
+	 * without an address is still a sign-in.
+	 */
+	async fetchEmail(accessToken: string): Promise<GitHubEmail | undefined> {
+		let entries: unknown[];
+		try {
+			entries = await this.getList(EMAILS_URL, accessToken);
+		} catch {
+			return undefined;
+		}
+		const emails = entries.filter(isGitHubEmail);
+		// Primary first, then verified: an unverified primary is still the
+		// address the account is known by.
+		return (
+			emails.find((entry) => entry.primary && entry.verified) ??
+			emails.find((entry) => entry.verified) ??
+			emails.find((entry) => entry.primary) ??
+			emails[0]
+		);
+	}
+
+	protected mapUser(raw: Record<string, unknown>): TransitUser {
+		return {
+			id: String(raw.id ?? ""),
+			email: String(raw.email ?? ""),
+			// An account with no display name still has a login.
+			name: String(raw.name ?? raw.login ?? ""),
+			nickName: str(raw, "login"),
+			avatarUrl: str(raw, "avatar_url"),
+			// `/user` says nothing about the address; `fetchUser` refines this
+			// when it has to read `/user/emails`.
+			emailVerificationState: "unsupported",
+			raw,
+		};
+	}
+}
+
+function isGitHubEmail(value: unknown): value is GitHubEmail {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof Reflect.get(value, "email") === "string"
+	);
+}

package/src/drivers/GoogleDriver.ts

@@ -0,0 +1,38 @@
+/**
+ * Google OAuth2 driver.
+ */
+
+import { Oauth2Driver, str } from "../Oauth2Driver.js";
+import type { TransitUser } from "../types.js";
+
+export class GoogleDriver extends Oauth2Driver {
+	protected readonly provider = "Google";
+	protected readonly authorizeUrl =
+		"https://accounts.google.com/o/oauth2/v2/auth";
+	protected readonly accessTokenUrl = "https://oauth2.googleapis.com/token";
+	protected readonly userInfoUrl =
+		"https://www.googleapis.com/oauth2/v3/userinfo";
+	protected readonly defaultScopes = ["openid", "email", "profile"] as const;
+
+	/** Asking for offline access is what makes Google issue a refresh token. */
+	protected override authorizeParams(): Record<string, string> {
+		return { access_type: "offline" };
+	}
+
+	protected mapUser(raw: Record<string, unknown>): TransitUser {
+		return {
+			// The OpenID Connect endpoint calls the subject `sub`; the older one
+			// called it `id`, and both are the same value.
+			id: String(raw.sub ?? raw.id ?? ""),
+			email: String(raw.email ?? ""),
+			name: String(raw.name ?? ""),
+			nickName: str(raw, "given_name") ?? str(raw, "name"),
+			avatarUrl: str(raw, "picture"),
+			emailVerificationState:
+				raw.email_verified === true || raw.verified_email === true
+					? "verified"
+					: "unverified",
+			raw,
+		};
+	}
+}

package/src/drivers/LdapDirectory.ts

@@ -0,0 +1,185 @@
+/**
+ * An LDAP or Active Directory directory.
+ *
+ * Nothing is redirected: the application already holds the credentials, and the
+ * directory is the authority that says whether they are right. Verifying them
+ * means binding AS that person — a bind that succeeds is the answer, and there
+ * is no other one.
+ *
+ * The flow is two connections on purpose. The first finds the person's DN,
+ * bound as whatever the application is allowed to search with. The second binds
+ * as the person, and is closed immediately: a connection carries the identity
+ * of whatever last bound on it, so nothing else may run on that one.
+ */
+
+import {
+	LdapConnection,
+	type LdapEntry,
+	LdapError,
+	type LdapFilter,
+} from "../ldap.js";
+import type { DirectoryDriver, TransitUser } from "../types.js";
+
+export interface LdapConfig {
+	/** `ldaps://directory.acme.test:636`. */
+	url: string;
+	/** Where to search from — `dc=acme,dc=test`. */
+	baseDn: string;
+	/**
+	 * The attribute a person types. `uid` on OpenLDAP,
+	 * `sAMAccountName` or `userPrincipalName` on Active Directory.
+	 */
+	loginAttribute: string;
+	/** The account the search runs as. Omitted means an anonymous search. */
+	bindDn?: string;
+	bindPassword?: string;
+	/** Extra conditions on the search, ANDed with the login attribute. */
+	filter?: LdapFilter;
+	/** Attributes to read. Defaults to the ones the mapping below uses. */
+	attributes?: string[];
+	/** The attribute names this directory uses, when they are not the usual ones. */
+	claims?: { email?: string; name?: string; nickName?: string };
+	/** Allow a plaintext connection — see the note on `LdapOptions`. */
+	allowInsecure?: boolean;
+	/** Refuse a server certificate that does not check out. Default true. */
+	rejectUnauthorized?: boolean;
+	/** How long to wait for the directory, in milliseconds. Default 10 000. */
+	timeoutMs?: number;
+}
+
+const EMAIL_ATTRS = ["mail", "userPrincipalName", "email"];
+const NAME_ATTRS = ["displayName", "cn", "name"];
+const NICK_ATTRS = ["uid", "sAMAccountName", "givenName"];
+
+export class LdapDirectory implements DirectoryDriver {
+	readonly #config: LdapConfig;
+
+	constructor(config: LdapConfig) {
+		this.#config = config;
+	}
+
+	async authenticate(username: string, password: string): Promise<TransitUser> {
+		// Refused here as well as in the bind: a form that submits an empty
+		// password must not reach the directory, which would answer success to
+		// an anonymous bind.
+		if (password === "") {
+			throw new LdapError(
+				"a password is required — an empty one is an anonymous bind, which the directory would accept",
+			);
+		}
+		if (username === "") {
+			throw new LdapError("a username is required");
+		}
+
+		const entry = await this.#find(username);
+		await this.#bindAs(entry.dn, password);
+		return this.#mapUser(entry);
+	}
+
+	/** Find the person, bound as whatever may search. */
+	async #find(username: string): Promise<LdapEntry> {
+		const connection = this.#open();
+		await connection.connect();
+		try {
+			if (this.#config.bindDn) {
+				await connection.bind(
+					this.#config.bindDn,
+					this.#config.bindPassword ?? "",
+				);
+			}
+
+			// The username is a VALUE in a structure, never text in a filter, so
+			// a login of `*)(uid=admin` is a login containing those characters.
+			const login: LdapFilter = {
+				equals: [this.#config.loginAttribute, username],
+			};
+			const filter: LdapFilter = this.#config.filter
+				? { and: [this.#config.filter, login] }
+				: login;
+
+			const entries = await connection.search({
+				base: this.#config.baseDn,
+				filter,
+				attributes: this.#config.attributes ?? [
+					...EMAIL_ATTRS,
+					...NAME_ATTRS,
+					...NICK_ATTRS,
+				],
+				// Two, so an ambiguous login is seen rather than silently
+				// resolved to whichever the directory returned first.
+				sizeLimit: 2,
+			});
+
+			if (entries.length === 0) {
+				// The same message as a wrong password: which of the two it was
+				// is not something a sign-in form should disclose.
+				throw new LdapError(
+					"the directory refused the bind: invalid credentials",
+					49,
+				);
+			}
+			if (entries.length > 1) {
+				throw new LdapError(
+					`'${username}' matches ${entries.length} entries, and this signs in one person`,
+				);
+			}
+			return entries[0] as LdapEntry;
+		} finally {
+			await connection.close();
+		}
+	}
+
+	/** Bind as the person. A bind that succeeds IS the verification. */
+	async #bindAs(dn: string, password: string): Promise<void> {
+		const connection = this.#open();
+		await connection.connect();
+		try {
+			await connection.bind(dn, password);
+		} finally {
+			// The connection now carries this person's identity; it is closed
+			// rather than reused.
+			await connection.close();
+		}
+	}
+
+	#open(): LdapConnection {
+		return new LdapConnection({
+			url: this.#config.url,
+			allowInsecure: this.#config.allowInsecure,
+			rejectUnauthorized: this.#config.rejectUnauthorized,
+			timeoutMs: this.#config.timeoutMs,
+		});
+	}
+
+	#mapUser(entry: LdapEntry): TransitUser {
+		const claims = this.#config.claims ?? {};
+		const email = pick(entry, claims.email, EMAIL_ATTRS);
+		const name = pick(entry, claims.name, NAME_ATTRS);
+		const nickName = pick(entry, claims.nickName, NICK_ATTRS);
+
+		return {
+			// The DN is what the directory calls this entry, and the only value
+			// guaranteed to be unique and stable.
+			id: entry.dn,
+			email: email ?? "",
+			name: name ?? nickName ?? entry.dn,
+			nickName,
+			// A directory that holds an address has vouched for it: that is what
+			// a directory is.
+			emailVerificationState: email === undefined ? "unsupported" : "verified",
+			raw: { dn: entry.dn, attributes: entry.attributes },
+		};
+	}
+}
+
+function pick(
+	entry: LdapEntry,
+	configured: string | undefined,
+	candidates: string[],
+): string | undefined {
+	for (const name of configured ? [configured] : candidates) {
+		const value = entry.attributes[name]?.[0];
+		if (value !== undefined && value !== "") return value;
+	}
+	return undefined;
+}

package/src/drivers/LinkedInDriver.ts

@@ -0,0 +1,105 @@
+/**
+ * LinkedIn OAuth2 driver — the member API.
+ *
+ * For an application whose LinkedIn app holds `r_liteprofile` /
+ * `r_emailaddress`. It needs two calls: the profile carries no address, and
+ * the address endpoint carries no profile.
+ *
+ * LinkedIn issues new applications OpenID Connect instead — that is
+ * `LinkedInOpenidConnectDriver`.
+ */
+
+import { Oauth2Driver } from "../Oauth2Driver.js";
+import type { TransitUser } from "../types.js";
+
+const EMAIL_URL = "https://api.linkedin.com/v2/emailAddress";
+const PROFILE_PROJECTION =
+	"(id,localizedFirstName,localizedLastName,vanityName,profilePicture(displayImage~:playableStreams))";
+
+export class LinkedInDriver extends Oauth2Driver {
+	protected readonly provider = "LinkedIn";
+	protected readonly authorizeUrl =
+		"https://www.linkedin.com/oauth/v2/authorization";
+	protected readonly accessTokenUrl =
+		"https://www.linkedin.com/oauth/v2/accessToken";
+	protected readonly userInfoUrl = "https://api.linkedin.com/v2/me";
+	protected readonly defaultScopes = [
+		"r_liteprofile",
+		"r_emailaddress",
+	] as const;
+
+	protected override userInfoParams(): Record<string, string> {
+		return { projection: PROFILE_PROJECTION };
+	}
+
+	protected override async fetchUser(
+		accessToken: string,
+	): Promise<TransitUser> {
+		const raw = await this.get(this.userInfoUrl, accessToken, {
+			...this.userInfoParams(),
+		});
+		const email = await this.fetchEmail(accessToken);
+		return { ...this.mapUser(raw), email };
+	}
+
+	/**
+	 * The address lives behind its own endpoint, and only with the
+	 * `r_emailaddress` scope — without it the response has no elements, which is
+	 * reported here rather than surfacing as an empty address downstream.
+	 */
+	async fetchEmail(accessToken: string): Promise<string> {
+		const body = await this.get(EMAIL_URL, accessToken, {
+			q: "members",
+			projection: "(elements*(primary,type,handle~))",
+		});
+		const elements = Array.isArray(body.elements) ? body.elements : [];
+		for (const element of elements) {
+			if (typeof element !== "object" || element === null) continue;
+			if (Reflect.get(element, "type") !== "EMAIL") continue;
+			const handle = Reflect.get(element, "handle~");
+			if (typeof handle !== "object" || handle === null) continue;
+			const address = Reflect.get(handle, "emailAddress");
+			if (typeof address === "string" && address !== "") return address;
+		}
+		throw new Error(
+			"LinkedIn returned no email address — the application needs the 'r_emailaddress' scope.",
+		);
+	}
+
+	protected mapUser(raw: Record<string, unknown>): TransitUser {
+		const first = String(raw.localizedFirstName ?? "");
+		const last = String(raw.localizedLastName ?? "");
+		return {
+			id: String(raw.id ?? ""),
+			email: "",
+			name: [first, last].filter(Boolean).join(" "),
+			nickName:
+				typeof raw.vanityName === "string" && raw.vanityName !== ""
+					? raw.vanityName
+					: [first, last].filter(Boolean).join(" "),
+			avatarUrl: pictureUrl(raw),
+			// The member API vouches for nothing about the address.
+			emailVerificationState: "unsupported",
+			raw,
+		};
+	}
+}
+
+/**
+ * The picture arrives as a list of renditions, largest last. Nothing about
+ * the shape is guaranteed, so every step is checked.
+ */
+function pictureUrl(raw: Record<string, unknown>): string | undefined {
+	const picture = raw.profilePicture;
+	if (typeof picture !== "object" || picture === null) return undefined;
+	const display = Reflect.get(picture, "displayImage~");
+	if (typeof display !== "object" || display === null) return undefined;
+	const elements = Reflect.get(display, "elements");
+	if (!Array.isArray(elements) || elements.length === 0) return undefined;
+	const identifiers = Reflect.get(Object(elements[0]), "identifiers");
+	if (!Array.isArray(identifiers) || identifiers.length === 0) return undefined;
+	const identifier = Reflect.get(Object(identifiers[0]), "identifier");
+	return typeof identifier === "string" && identifier !== ""
+		? identifier
+		: undefined;
+}

package/src/drivers/LinkedInOpenidConnectDriver.ts

@@ -0,0 +1,33 @@
+/**
+ * LinkedIn OAuth2 driver — OpenID Connect.
+ *
+ * This is the flow LinkedIn issues new applications: one `userinfo` call,
+ * standard claims. The member API is `LinkedInDriver`.
+ */
+
+import { Oauth2Driver, str } from "../Oauth2Driver.js";
+import type { TransitUser } from "../types.js";
+
+export class LinkedInOpenidConnectDriver extends Oauth2Driver {
+	protected readonly provider = "LinkedIn";
+	protected readonly authorizeUrl =
+		"https://www.linkedin.com/oauth/v2/authorization";
+	protected readonly accessTokenUrl =
+		"https://www.linkedin.com/oauth/v2/accessToken";
+	protected readonly userInfoUrl = "https://api.linkedin.com/v2/userinfo";
+	protected readonly defaultScopes = ["openid", "profile", "email"] as const;
+
+	protected mapUser(raw: Record<string, unknown>): TransitUser {
+		return {
+			// `sub` is the stable subject identifier; `id` does not exist here.
+			id: String(raw.sub ?? ""),
+			email: String(raw.email ?? ""),
+			name: String(raw.name ?? ""),
+			nickName: str(raw, "given_name"),
+			avatarUrl: str(raw, "picture"),
+			emailVerificationState:
+				raw.email_verified === true ? "verified" : "unverified",
+			raw,
+		};
+	}
+}