pi-roundtable 0.8.0 → 0.9.0

package/src/core/identity/access-policy.ts

@@ -0,0 +1,227 @@
+import type { Pronouns } from "../config/config.ts";
+import { ConfigError } from "../domain/errors.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type {
+	SpeakerFacts,
+	SpeakerMap,
+	SpeakerPolicy,
+	Tier,
+	TierMembers,
+} from "../speakers.ts";
+import {
+	type ActorFacts,
+	identityOf,
+	parseIdentity,
+	surfaceOf,
+} from "./actor-facts.ts";
+import { SYSTEM_PRINCIPAL } from "./principal-store.ts";
+
+/** One owner the configuration names: whom they are, and the identities that are theirs. */
+export interface AccessOwner {
+	name: string;
+	pronouns?: Pronouns;
+	/** Their principal's id, such as the 0.8 `owner.id`; without it, a new `p_` principal is made at the first boot and found again by the identities after. */
+	principal?: string;
+	/** `<provider>:<subject>` strings, such as `discord:<user id>` or `token:remote-mcp`. */
+	identities: readonly string[];
+}
+
+/**
+ * Who holds a tier besides the owners: identities, roles, or everyone. Roles are written
+ * `<surface>:role:<name>`. `everyone: true` admits everyone on every surface, a list only on
+ * those surfaces.
+ */
+export interface AccessTier {
+	identities?: readonly string[];
+	roles?: readonly string[];
+	everyone?: boolean | readonly string[];
+}
+
+/** Who the host serves, and at which tier. */
+export interface AccessRules {
+	/** The owners, the first of them the primary owner. The owner tier comes only from here or the CLI, never from a role a surface reports. */
+	owners: readonly AccessOwner[];
+	admins?: AccessTier;
+	members?: AccessTier;
+	/** `admitted`: someone the rules admit gets a principal at first contact, and a 0.8 speaker claims theirs; `linked`: only identities already linked, such as by the CLI or the configuration, are served. Owners are never admitted. */
+	provisioning: "admitted" | "linked";
+	/** How many days a principal whose tier came only from the rules on contact may go unseen before their background turns are refused. */
+	backgroundStaleDays: number;
+}
+
+const holds = (
+	tier: AccessTier | undefined,
+	facts: ActorFacts,
+	surface: string,
+): boolean => {
+	if (!tier) return false;
+	const { everyone } = tier;
+	if (everyone === true) return true;
+	if (Array.isArray(everyone) && everyone.includes(surface)) return true;
+	if (tier.identities?.includes(identityOf(facts))) return true;
+	return (facts.roles ?? []).some((role) => tier.roles?.includes(role));
+};
+
+/**
+ * The tier the rules give these facts on this contact: admin, member, or none. Never owner: an
+ * owner is one by the configuration's owners or a lasting role, not by what a surface reports.
+ */
+export function factsTier(
+	rules: Pick<AccessRules, "admins" | "members">,
+	facts: ActorFacts,
+	conversation?: ChannelKey,
+): Exclude<Tier, "owner"> | undefined {
+	const surface = surfaceOf(facts, conversation);
+	if (holds(rules.admins, facts, surface)) return "admin";
+	if (holds(rules.members, facts, surface)) return "member";
+	return undefined;
+}
+
+/** The configured owner whose identities include these facts', if any. */
+export function ownerOfFacts(
+	rules: Pick<AccessRules, "owners">,
+	facts: ActorFacts,
+): AccessOwner | undefined {
+	const identity = identityOf(facts);
+	return rules.owners.find((owner) => owner.identities.includes(identity));
+}
+
+const ROLE = /^[^:]+:role:.+$/;
+
+function checkTier(tier: AccessTier | undefined, path: string): void {
+	if (!tier) return;
+	tier.identities?.forEach((identity, i) => {
+		if (!parseIdentity(identity))
+			throw new ConfigError(
+				`config ${path}.identities[${i}]: expected <provider>:<subject>, got ${JSON.stringify(identity)}. Write it like discord:<user id>; roundtable principal list prints them.`,
+			);
+	});
+	tier.roles?.forEach((role, i) => {
+		if (!ROLE.test(role))
+			throw new ConfigError(
+				`config ${path}.roles[${i}]: expected <surface>:role:<name>, got ${JSON.stringify(role)}. Write it like discord:role:<role id> or web:role:<role name>.`,
+			);
+	});
+}
+
+/** The rules, checked: identities and roles well formed, no identity or principal under two owners, no owner as the system principal. */
+export function checkAccessRules(rules: AccessRules): AccessRules {
+	const seenIdentity = new Map<string, number>();
+	const seenPrincipal = new Map<string, number>();
+	rules.owners.forEach((owner, n) => {
+		const path = `access.owners[${n}]`;
+		if (owner.principal === SYSTEM_PRINCIPAL)
+			throw new ConfigError(
+				`config ${path}.principal: "${SYSTEM_PRINCIPAL}" is the host's own principal. Give the owner's own id, or leave principal out.`,
+			);
+		if (owner.principal === undefined && owner.identities.length === 0)
+			throw new ConfigError(
+				`config ${path}: give the owner a principal id or at least one identity, so each boot finds the same principal.`,
+			);
+		if (owner.principal !== undefined) {
+			const other = seenPrincipal.get(owner.principal);
+			if (other !== undefined)
+				throw new ConfigError(
+					`config ${path}.principal: access.owners[${other}] has the same principal ${owner.principal}. Merge the two owners into one.`,
+				);
+			seenPrincipal.set(owner.principal, n);
+		}
+		owner.identities.forEach((identity, i) => {
+			if (!parseIdentity(identity))
+				throw new ConfigError(
+					`config ${path}.identities[${i}]: expected <provider>:<subject>, got ${JSON.stringify(identity)}. Write it like discord:<user id>; roundtable principal list prints them.`,
+				);
+			const other = seenIdentity.get(identity);
+			if (other !== undefined)
+				throw new ConfigError(
+					`config ${path}.identities[${i}]: ${identity} is also listed under access.owners[${other}]. An identity is one person's; keep it under one owner.`,
+				);
+			seenIdentity.set(identity, n);
+		});
+	});
+	checkTier(rules.admins, "access.admins");
+	checkTier(rules.members, "access.members");
+	if (
+		!(
+			Number.isInteger(rules.backgroundStaleDays) &&
+			rules.backgroundStaleDays > 0
+		)
+	)
+		throw new ConfigError(
+			`config access.backgroundStaleDays: expected a positive whole number of days, got ${JSON.stringify(rules.backgroundStaleDays)}.`,
+		);
+	return rules;
+}
+
+function tierOfMembers(
+	members: TierMembers | undefined,
+	provider: string,
+): AccessTier | undefined {
+	if (!members) return undefined;
+	return {
+		...(members.users
+			? { identities: members.users.map((id) => `${provider}:${id}`) }
+			: {}),
+		...(members.roles
+			? { roles: members.roles.map((role) => `${provider}:role:${role}`) }
+			: {}),
+		...(members.everyone === undefined
+			? {}
+			: { everyone: members.everyone ? [provider] : false }),
+	};
+}
+
+/**
+ * The rules a 0.8 speaker map means on one surface: its owners by id, its users as identities of
+ * that surface, its roles as that surface's roles, and `everyone` as everyone there.
+ */
+export function rulesOfSpeakerMap(
+	map: SpeakerMap,
+	provider = "discord",
+): Pick<AccessRules, "owners" | "admins" | "members"> {
+	const admins = tierOfMembers(map.admins, provider);
+	const members = tierOfMembers(map.members, provider);
+	return {
+		owners: map.owners.map((id) => ({
+			name: id,
+			principal: id,
+			identities: [`${provider}:${id}`],
+		})),
+		...(admins ? { admins } : {}),
+		...(members ? { members } : {}),
+	};
+}
+
+/**
+ * The 0.8 policy over these rules on one surface, for the code that still resolves a speaker
+ * from a surface's facts by itself: an author is an owner when one of the owners lists their
+ * identity there, and otherwise holds the tier the rules give them. Each speaker's principal is
+ * their own id, as for a person carried over from 0.8; the identity service knows the others.
+ */
+export function speakerPolicyOf(
+	rules: Pick<AccessRules, "owners" | "admins" | "members">,
+	provider = "discord",
+): SpeakerPolicy {
+	return {
+		resolve(author: SpeakerFacts) {
+			const facts: ActorFacts = {
+				provider,
+				subject: author.id,
+				name: author.name,
+				surface: provider,
+				roles: (author.roleIds ?? []).map((role) => `${provider}:role:${role}`),
+			};
+			const tier: Tier | undefined = ownerOfFacts(rules, facts)
+				? "owner"
+				: factsTier(rules, facts);
+			return (
+				tier && {
+					id: author.id,
+					name: author.name,
+					tier,
+					principalId: author.id,
+				}
+			);
+		},
+	};
+}

package/src/core/identity/actor-facts.ts

@@ -0,0 +1,65 @@
+import { parseChannelKey } from "../contract/surface.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type { IdentityRef } from "./principal-store.ts";
+
+/**
+ * What a surface reports about the person behind a message or a connection; the identity
+ * service decides who they are and the tier they hold.
+ */
+export interface ActorFacts {
+	/** The identity provider: `discord`, `oidc:<base64url issuer>`, `token`, … */
+	provider: string;
+	/** The person's id at the provider. */
+	subject: string;
+	/** The name to address them by on this contact. */
+	name: string;
+	/** The roles they hold, each prefixed with its surface: `discord:role:<id>`, `web:role:<name>`. */
+	roles?: readonly string[];
+	/**
+	 * The surface they reached the host through, as `everyone` lists name it, such as `discord` or
+	 * `web`; default the conversation's surface, then the provider up to its first colon.
+	 */
+	surface?: string;
+	/** Where on the surface, such as a guild; informational. */
+	space?: string;
+	/**
+	 * The speaker id 0.8 gave this person, which a principal carried over from 0.8 has as its id:
+	 * the user id on Discord, `oidc:<issuer>:<subject>` on the web. At first contact it claims that
+	 * principal. It is also the speaker's `id`, the id the surface knows them by.
+	 */
+	legacyId?: string;
+}
+
+/** An identity as configuration and the CLI write it: `<provider>:<subject>`. */
+export function identityOf(ref: IdentityRef): string {
+	return `${ref.provider}:${ref.subject}`;
+}
+
+/**
+ * An identity string read back: the provider is the part before the first colon, and for `oidc`
+ * the issuer after it too, so `oidc:<issuer>:<subject>` is the 0.8 web speaker id. Undefined
+ * when a part is missing.
+ */
+export function parseIdentity(identity: string): IdentityRef | undefined {
+	const first = identity.indexOf(":");
+	if (first <= 0) return undefined;
+	let cut = first;
+	if (identity.slice(0, first) === "oidc") {
+		cut = identity.indexOf(":", first + 1);
+		if (cut <= first + 1) return undefined;
+	}
+	const subject = identity.slice(cut + 1);
+	if (subject === "") return undefined;
+	return { provider: identity.slice(0, cut), subject };
+}
+
+/** The surface the facts came through: their own, the conversation's, or the provider's first part. */
+export function surfaceOf(
+	facts: ActorFacts,
+	conversation?: ChannelKey,
+): string {
+	if (facts.surface) return facts.surface;
+	if (conversation) return parseChannelKey(conversation).surface;
+	const colon = facts.provider.indexOf(":");
+	return colon < 0 ? facts.provider : facts.provider.slice(0, colon);
+}

package/src/core/identity/caching-principal-store.ts

@@ -0,0 +1,111 @@
+import type { Tier } from "../speakers.ts";
+import type {
+	IdentityRef,
+	LinkSource,
+	NewPrincipal,
+	PrincipalStore,
+	Pronouns,
+	RoleSource,
+} from "./principal-store.ts";
+
+/** How long a read of the store is reused; a change another process makes is seen after it. */
+export const CACHE_MS = 30_000;
+
+/**
+ * The store with its reads reused for `CACHE_MS`; any write through it drops them all, so this
+ * process sees its own changes at once. Recording a principal as seen drops only theirs.
+ */
+export class CachingPrincipalStore implements PrincipalStore {
+	readonly #store: PrincipalStore;
+	readonly #now: () => number;
+	readonly #reads = new Map<string, { at: number; value: Promise<unknown> }>();
+
+	constructor(store: PrincipalStore, now: () => number) {
+		this.#store = store;
+		this.#now = now;
+	}
+
+	#cached<T>(key: string, read: () => Promise<T>): Promise<T> {
+		const now = this.#now();
+		const hit = this.#reads.get(key);
+		if (hit && now - hit.at < CACHE_MS) return hit.value as Promise<T>;
+		const value = read();
+		this.#reads.set(key, { at: now, value });
+		value.catch(() => this.#reads.delete(key));
+		return value;
+	}
+
+	async #write<T>(write: Promise<T>): Promise<T> {
+		try {
+			return await write;
+		} finally {
+			this.#reads.clear();
+		}
+	}
+
+	get(id: string) {
+		return this.#cached(`p\0${id}`, () => this.#store.get(id));
+	}
+	list() {
+		return this.#store.list();
+	}
+	identity(provider: string, subject: string) {
+		return this.#cached(`i\0${provider}\0${subject}`, () =>
+			this.#store.identity(provider, subject),
+		);
+	}
+	identitiesOf(principalId: string) {
+		return this.#store.identitiesOf(principalId);
+	}
+	rolesOf(principalId: string) {
+		return this.#cached(`r\0${principalId}`, () =>
+			this.#store.rolesOf(principalId),
+		);
+	}
+	holders(role: Tier) {
+		return this.#store.holders(role);
+	}
+	linksFrom(source: LinkSource) {
+		return this.#store.linksFrom(source);
+	}
+	create(input: NewPrincipal) {
+		return this.#write(this.#store.create(input));
+	}
+	update(
+		id: string,
+		change: { displayName?: string; pronouns?: Pronouns | null },
+	) {
+		return this.#write(this.#store.update(id, change));
+	}
+	link(principalId: string, identity: IdentityRef, source: LinkSource) {
+		return this.#write(this.#store.link(principalId, identity, source));
+	}
+	claim(principalId: string, identity: IdentityRef, displayName?: string) {
+		return this.#write(this.#store.claim(principalId, identity, displayName));
+	}
+	admit(identity: IdentityRef, displayName: string, id?: string) {
+		return this.#write(this.#store.admit(identity, displayName, id));
+	}
+	unlink(provider: string, subject: string) {
+		return this.#write(this.#store.unlink(provider, subject));
+	}
+	grant(principalId: string, role: Tier, source: RoleSource) {
+		return this.#write(this.#store.grant(principalId, role, source));
+	}
+	revoke(principalId: string, role: Tier, source?: RoleSource) {
+		return this.#write(this.#store.revoke(principalId, role, source));
+	}
+	disable(id: string) {
+		return this.#write(this.#store.disable(id));
+	}
+	enable(id: string) {
+		return this.#write(this.#store.enable(id));
+	}
+	async touch(id: string, tier: Tier | null, at?: Date) {
+		try {
+			await this.#store.touch(id, tier, at);
+		} finally {
+			this.#reads.delete(`p\0${id}`);
+		}
+	}
+}

package/src/core/identity/config-owner.ts

@@ -0,0 +1,145 @@
+import { ConfigError } from "../domain/errors.ts";
+import type { Logger } from "../log.ts";
+import type { AccessOwner } from "./access-policy.ts";
+import { identityOf } from "./actor-facts.ts";
+import type { DeclaredIdentity } from "./plugin-identities.ts";
+import type {
+	IdentityLink,
+	IdentityRef,
+	PrincipalStore,
+} from "./principal-store.ts";
+
+/** A configured owner, where the configuration lists them, and what the boot knows of the plugins. */
+export interface ConfiguredOwner {
+	owner: AccessOwner;
+	/** The owner's index in `access.owners`. */
+	index: number;
+	/** The owner's identities, parsed, in the configuration's order. */
+	refs: readonly IdentityRef[];
+	/** Each identity the plugins declare, with the plugin and the principal it names. */
+	declaredBy: ReadonlyMap<string, DeclaredIdentity>;
+	/** The primary owner's principal, which a plugin naming none binds to; undefined while syncing the primary owner. */
+	primary: string | undefined;
+	logger: Logger;
+}
+
+/** A configured owner's identity that stops the start, and how to fix it. */
+export interface OwnerConflict {
+	problem: string;
+	fix: string;
+}
+
+/**
+ * Whether a configured owner may list an identity a plugin declares. The principal the plugin binds
+ * it to on this boot, its `principal` or else the primary owner, must be this owner, whatever it
+ * was bound to before: the boot moves it there. A plugin's credential never tells who the owner is,
+ * so an owner nothing else tells conflicts unless they are the primary owner the plugin defaults to
+ * and the credential is not a plugin's link to someone already. `primary` undefined with `first`
+ * false is a primary owner the start makes.
+ */
+export function declaredConflict({
+	index: n,
+	i,
+	identity,
+	id,
+	link,
+	declared: { plugin, principal },
+	primary,
+	first,
+}: {
+	index: number;
+	i: number;
+	identity: string;
+	/** The principal this owner is, as everything but a plugin's credential tells; undefined for one the boot makes. */
+	id: string | undefined;
+	link: IdentityLink | undefined;
+	declared: DeclaredIdentity;
+	primary: string | undefined;
+	first: boolean;
+}): OwnerConflict | undefined {
+	const at = `access.owners[${n}].identities[${i}]: ${identity} is an identity plugin ${plugin} declares`;
+	const remove = `Remove it from access.owners[${n}].identities`;
+	const untold: OwnerConflict = {
+		problem: "a plugin's credential does not tell who this owner is",
+		fix: `${remove}, or give this owner its principal and bind plugin ${plugin} to it`,
+	};
+	if (principal === undefined && first) {
+		// Bound to this owner, the primary owner: whoever they are, unless only that link would tell.
+		if (id !== undefined || link?.source !== "plugin") return undefined;
+		return {
+			...untold,
+			problem: `${at}, bound to principal ${link.principalId}, and ${untold.problem}`,
+		};
+	}
+	const target = principal ?? primary;
+	if (target !== undefined && target === id) return undefined;
+	const bound = `${at}, bound to ${target === undefined ? "the principal the start makes for access.owners[0]" : `principal ${target}`}`;
+	return id === undefined
+		? { ...untold, problem: `${bound}, and ${untold.problem}` }
+		: {
+				problem: `${bound}, not to this owner's ${id}`,
+				fix: `${remove}, or bind plugin ${plugin} to ${id} in its options`,
+			};
+}
+
+/**
+ * The principal a configured owner is: their `principal`, else the principal an identity of theirs
+ * is linked to; undefined for someone the boot makes. A plugin's credential is not the person's own
+ * identity, so a plugin's link never tells who the owner is, and one no plugin declares any more is
+ * unlinked first, as the boot would anyway. An identity linked to another principal stops the
+ * boot, and so does an identity a plugin declares that `declaredConflict` refuses. One a plugin
+ * declares and binds to this owner on this boot, still the plugin's link to someone else, is moved
+ * now, before the owner's identities are linked.
+ */
+export async function configuredOwnerId(
+	store: PrincipalStore,
+	{ owner, index: n, refs, declaredBy, primary, logger }: ConfiguredOwner,
+): Promise<string | undefined> {
+	const links = await Promise.all(
+		refs.map(async (ref) => {
+			const link = await store.identity(ref.provider, ref.subject);
+			if (link?.source !== "plugin" || declaredBy.has(identityOf(link)))
+				return link;
+			// No plugin declares it any more, so this boot unlinks it anyway: before it tells anyone anything.
+			await store.unlink(link.provider, link.subject);
+			logger.info(
+				`${identityOf(link)} is no longer an identity a plugin declares; it was unlinked from principal ${link.principalId}`,
+			);
+			return undefined;
+		}),
+	);
+	let id = owner.principal;
+	links.forEach((link, i) => {
+		if (!link || link.source === "plugin") return;
+		id ??= link.principalId;
+		if (link.principalId !== id)
+			throw new ConfigError(
+				`config access.owners[${n}].identities[${i}]: ${owner.identities[i]} is linked to principal ${link.principalId}, not to this owner's ${id}. Unlink it with roundtable principal unlink ${owner.identities[i]}, or fix the configuration.`,
+			);
+	});
+	for (const [i, ref] of refs.entries()) {
+		const declared = declaredBy.get(identityOf(ref));
+		if (!declared) continue;
+		const link = links[i];
+		const conflict = declaredConflict({
+			index: n,
+			i,
+			identity: owner.identities[i] ?? identityOf(ref),
+			id,
+			link,
+			declared,
+			primary,
+			first: n === 0,
+		});
+		// The CLI refuses to unlink a plugin's identity: the plugin's options move it.
+		if (conflict)
+			throw new ConfigError(`config ${conflict.problem}. ${conflict.fix}.`);
+		if (link?.source !== "plugin" || link.principalId === id) continue;
+		// The plugin binds it to this owner on this boot, and a link refuses an identity linked elsewhere.
+		await store.unlink(link.provider, link.subject);
+		logger.info(
+			`${identityOf(link)} of plugin ${declared.plugin} moved from principal ${link.principalId} to ${id}`,
+		);
+	}
+	return id;
+}

package/src/core/identity/contact.ts

@@ -0,0 +1,27 @@
+import type { ChannelKey } from "../sessions.ts";
+import type { Speaker } from "../speakers.ts";
+import type { ActorFacts } from "./actor-facts.ts";
+
+/**
+ * A person a surface reports, assessed before any claim takes their message: who they would be,
+ * with nothing written yet.
+ */
+export interface Contact {
+	/** The speaker they would be: their principal's, or at a first contact the principal they would claim or be admitted as. */
+	readonly speaker: Speaker;
+	/**
+	 * Records the contact once a claim takes their message: claims their 0.8 principal or admits
+	 * them first, then records them as seen. The speaker they are now, whose principal differs from
+	 * the assessed one only when another process linked them meanwhile; undefined when they are no
+	 * one now.
+	 */
+	take(): Promise<Speaker | undefined>;
+}
+
+/** Assesses the people of messages before a claim takes them, so nobody's message that no claim serves writes anything. Core-internal: the router's. */
+export interface ContactAssessor {
+	assess(
+		facts: ActorFacts,
+		scope?: { conversation?: ChannelKey },
+	): Promise<Contact | undefined>;
+}

package/src/core/identity/identity-plugin.ts

@@ -0,0 +1,56 @@
+import type { RoundtablePlugin } from "../plugin.ts";
+import { IDENTITY } from "../services.ts";
+import type { AccessRules } from "./access-policy.ts";
+import { type BackfillSummary, identityMigrations } from "./identity-schema.ts";
+import { PgIdentityService } from "./identity-service.ts";
+import { identityView } from "./identity-view.ts";
+import { declaredIdentities } from "./plugin-identities.ts";
+import { PgPrincipalStore } from "./principal-store.ts";
+
+/** The name of the identity plugin, as the migration ledger names it. */
+export const IDENTITY_PLUGIN = "identity";
+
+export interface IdentityOptions {
+	/** Who the host serves; the backfill makes the owners with a principal id first, by their names, and caps what a carried-over author of schedules is seen at by the tiers. */
+	rules: AccessRules;
+	/** The host's other plugins, whose declared `identities` setup links; checked when this plugin is made. */
+	plugins?: readonly RoundtablePlugin[];
+}
+
+/** One line for the log: what the boot's backfill made, and from where. */
+export function backfillLine(summary: BackfillSummary): string {
+	const sources = Object.entries(summary.sources)
+		.map(([source, count]) => `${source} ${count}`)
+		.join(", ");
+	return `principal backfill: ${summary.created} created; ids found: ${sources}`;
+}
+
+/**
+ * The principals, their identity links, and their roles: the tables, the backfill that makes a
+ * principal of every person 0.8 stored, and the identity service over them provided as
+ * `IDENTITY`, read-only, its configured owners and the plugins' declared identities synced at
+ * setup. It runs first, so every later plugin may read it.
+ */
+export function identityPlugin(options: IdentityOptions): RoundtablePlugin {
+	const { rules } = options;
+	const identities = declaredIdentities(options.plugins ?? []);
+	let summary: BackfillSummary | undefined;
+	return {
+		name: IDENTITY_PLUGIN,
+		migrations: identityMigrations(rules, (made) => {
+			summary = made;
+		}),
+		provides: [IDENTITY],
+		setup: async ({ database, services, logger }) => {
+			if (summary) logger.info(backfillLine(summary));
+			const identity = new PgIdentityService(
+				await PgPrincipalStore.attach(database()),
+				rules,
+				{ logger, identities },
+			);
+			await identity.syncConfig();
+			services.provide(IDENTITY, identityView(identity));
+			return {};
+		},
+	};
+}