pi-roundtable 0.25.0 → 0.26.1

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

@@ -17,6 +17,7 @@ import {
 import { CachingPrincipalStore } from "./caching-principal-store.ts";
 import { configuredOwnerId, refuseOwnerDeclarations } from "./config-owner.ts";
 import type { Contact, ContactAssessor } from "./contact.ts";
+import type { IdentityService } from "./identity-port.ts";
 import {
 	type DeclaredIdentity,
 	refuseUnboundIdentities,
@@ -35,53 +36,7 @@ import {
 import { SeenThrottle } from "./seen-throttle.ts";
 import { isPrincipalId, newPrincipalId } from "./ulid.ts";
 
-/**
- * Who the host serves: its principals, their identities, and their roles, read-only. Provided as
- * `IDENTITY` by the `identity` plugin; the principals are written by the host's own configuration
- * and the `roundtable principal` CLI, never through it. A change another process makes is seen
- * within half a minute.
- */
-export interface IdentityService {
-	/**
-	 * The speaker behind these facts, or undefined when the access rules serve no one by them: a
-	 * linked identity is its principal's; an unlinked one first claims the principal of its 0.8
-	 * id (`legacyId`) when the backfill made it and no identity was ever linked to it, unless it
-	 * holds the owner role, taking the facts' name when the backfill named it by its id, and is
-	 * otherwise admitted as a new principal when the rules give it a tier. Both happen only when `provisioning` is `admitted` on the contact's surface; under `linked` only identities
-	 * already linked are served. A disabled principal is no one. The tier is the higher of the
-	 * principal's lasting roles and what the rules give the facts on this contact.
-	 */
-	resolve(
-		facts: ActorFacts,
-		scope?: { conversation?: ChannelKey },
-	): Promise<Speaker | undefined>;
-	principal(id: string): Promise<Principal | undefined>;
-	/** Every principal, the oldest first. */
-	list(): Promise<readonly Principal[]>;
-	/** The identities linked to the principal. */
-	identities(principalId: string): Promise<readonly IdentityLink[]>;
-	/** The principal's lasting roles, granted by the configuration or the CLI. */
-	roles(principalId: string): Promise<readonly RoleGrant[]>;
-	/** The tier of the principal's lasting roles; undefined when they hold none, are disabled, or are unknown. */
-	tierOf(principalId: string): Promise<Tier | undefined>;
-	/**
-	 * A speaker for a turn started on a principal's behalf, at `tier` or their own, whichever is
-	 * lower. Their own is their lasting roles' tier, or, when their tier comes only from the rules
-	 * on contact, the tier they were last seen at, refused once `access.backgroundStaleDays` pass
-	 * unseen or once a contact of theirs is refused. Throws IdentityError for a principal that is
-	 * unknown, disabled, or holds no tier, and for the system principal, whose turns only the core
-	 * starts.
-	 */
-	speakerFor(principalId: string, tier?: Tier): Promise<Speaker>;
-	/** The principals holding the owner role, the configured owners first in their order. */
-	owners(): Promise<readonly Principal[]>;
-	/**
-	 * The id of the principal an identity, written `<provider>:<subject>`, is linked to, such as the
-	 * one a plugin's declared identity stands for; undefined when it is linked to no one. Throws
-	 * IdentityError for text that is no identity.
-	 */
-	principalOf(identity: string): Promise<string | undefined>;
-}
+export type { IdentityService } from "./identity-port.ts";
 
 /** The system principal's speaker for a turn the core itself starts, such as an ops report, at the tier its starter gives. Core-internal: no plugin reaches it. */
 export function systemSpeaker(tier: Tier): Speaker {
@@ -97,8 +52,15 @@ const DAY_MS = 24 * 60 * 60_000;
 /** How many people assessed at a first contact but not yet taken are remembered. */
 const PROVISIONAL_MAX = 1_000;
 
+/** What names a principal to the agents: the profile name when the host lists its provider as model-visible. */
+export interface ModelNames {
+	modelName(principalId: string): Promise<string | undefined>;
+}
+
 export interface IdentityServiceOptions {
 	logger: Logger;
+	/** The profiles that name people to the agents; without them every name is the facts'. */
+	profiles?: ModelNames;
 	/** The identities the plugins declare, checked by `declaredIdentities`; `syncConfig` links them. */
 	identities?: readonly DeclaredIdentity[];
 	/** The clock, in milliseconds; a test gives its own. */
@@ -111,6 +73,7 @@ export class PgIdentityService implements IdentityService, ContactAssessor {
 	readonly store: PrincipalStore;
 	readonly #rules: AccessRules;
 	readonly #logger: Logger;
+	readonly #profiles: ModelNames | undefined;
 	readonly #now: () => number;
 	/** When each principal is written as seen. */
 	readonly #seen = new SeenThrottle();
@@ -140,6 +103,13 @@ export class PgIdentityService implements IdentityService, ContactAssessor {
 			...this.#declared.map((declared) => declared.identity),
 		]);
 		this.#logger = options.logger;
+		this.#profiles = options.profiles;
+	}
+
+	/** The speaker under the name the profiles give the principal, when the host lets agents see it. */
+	async #named(speaker: Speaker): Promise<Speaker> {
+		const name = await this.#profiles?.modelName(speaker.principalId);
+		return name ? { ...speaker, name } : speaker;
 	}
 
 	/** The refusals `syncConfig` makes from the configuration and the declarations alone, for `Roundtable.check()`. */
@@ -227,6 +197,19 @@ export class PgIdentityService implements IdentityService, ContactAssessor {
 		return (await this.assess(facts, scope))?.take();
 	}
 
+	async peek(
+		facts: ActorFacts,
+		scope: { conversation?: ChannelKey } = {},
+	): Promise<Speaker | undefined> {
+		if (facts.provider === LEGACY_PROVIDER) return undefined;
+		const link = await this.store.identity(facts.provider, facts.subject);
+		if (!link) return undefined;
+		const principal = await this.store.get(link.principalId);
+		if (!principal || principal.disabled) return undefined;
+		const tier = await this.#tier(principal.id, facts, scope.conversation);
+		return tier ? this.#named(speakerOf(facts, principal.id, tier)) : undefined;
+	}
+
 	/**
 	 * The contact of these facts, read only: a linked identity's principal, else at a first contact
 	 * the principal they would claim or be admitted as, the same new id for the same person until
@@ -255,10 +238,19 @@ export class PgIdentityService implements IdentityService, ContactAssessor {
 			assessed = { principalId: principal.id, tier };
 		} else assessed = await this.#firstContact(facts, conversation);
 		if (!assessed) return undefined;
-		const speaker = speakerOf(facts, assessed.principalId, assessed.tier);
+		const speaker = await this.#named(
+			speakerOf(facts, assessed.principalId, assessed.tier),
+		);
 		return {
 			speaker,
-			take: () => this.#take(facts, conversation, assessed.principalId),
+			take: async () => {
+				const taken = await this.#take(
+					facts,
+					conversation,
+					assessed.principalId,
+				);
+				return taken && this.#named(taken);
+			},
 		};
 	}
 
@@ -308,12 +300,12 @@ export class PgIdentityService implements IdentityService, ContactAssessor {
 			throw new IdentityError(`principal ${principalId} is disabled`);
 		const cap =
 			(await this.#lastingTier(principalId)) ?? this.#lastSeenTier(principal);
-		return {
+		return this.#named({
 			id: principal.id,
 			name: principal.displayName,
 			tier: tier ? lowest(tier, cap) : cap,
 			principalId: principal.id,
-		};
+		});
 	}
 
 	async principalOf(identity: string): Promise<string | undefined> {
@@ -372,11 +364,12 @@ export class PgIdentityService implements IdentityService, ContactAssessor {
 		]);
 	}
 
-	/** Whether the facts carry what the rules decide by: the roles, when the rules name a role of their surface. */
+	/** Whether the facts carry what the rules decide by: the roles, when the rules name a role of their surface; never for partial facts. */
 	#knowsRoles(
 		facts: ActorFacts,
 		conversation: ChannelKey | undefined,
 	): boolean {
+		if (facts.partial) return false;
 		if (facts.roles !== undefined) return true;
 		const prefix = `${surfaceOf(facts, conversation)}:role:`;
 		return ![this.#rules.admins, this.#rules.members].some((tier) =>

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

@@ -30,6 +30,7 @@ export function identityView(
 	const view = Object.freeze({
 		resolve: async (facts, scope) =>
 			frozenCopy(await service.resolve(facts, scope)),
+		peek: async (facts, scope) => frozenCopy(await service.peek(facts, scope)),
 		principal: async (id) => frozenCopy(await service.principal(id)),
 		list: async () => frozenCopy(await service.list()),
 		identities: async (principalId) =>

package/src/core/identity/person-profiles.ts

@@ -0,0 +1,275 @@
+import type { SQL } from "bun";
+import { IdentityError } from "../domain/errors.ts";
+import type { Logger } from "../log.ts";
+import { ProfileChoices } from "./profile-choices.ts";
+import { cleanName, ExpiringMap } from "./profile-memory.ts";
+import {
+	fetchPicture,
+	type Picture,
+	pictureResponse,
+} from "./profile-picture.ts";
+import type {
+	PersonDisplay,
+	PersonProfiles,
+	ProfileRules,
+	ProfileSource,
+} from "./profiles.ts";
+
+const HOUR_MS = 60 * 60_000;
+const MISS_MS = 10 * 60_000;
+const CHOICE_MS = 30_000;
+const FETCH_BUDGET_MS = 2_000;
+const PICTURES_MAX_BYTES = 32 * 1024 * 1024;
+
+/** What a person's linked identities and display name are, as the directory reads them. */
+export interface ProfileLinks {
+	/** The providers and subjects linked to the principal. */
+	identities(
+		principalId: string,
+	): Promise<readonly { provider: string; subject: string }[]>;
+	/** The principal's own display name; undefined for an unknown principal. */
+	displayName(principalId: string): Promise<string | undefined>;
+}
+
+export interface PersonProfilesOptions {
+	sql: SQL;
+	links: ProfileLinks;
+	rules: ProfileRules;
+	logger: Logger;
+	/** The clock, in milliseconds; a test gives its own. */
+	now?: () => number;
+	/** What a source's fetch may take; default two seconds. */
+	fetchBudgetMs?: number;
+	/** Replaces `fetch` for pictures, for a test. */
+	fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+}
+
+interface Fetched {
+	name?: string;
+	pictureUrl?: string;
+}
+
+/** A call that did not finish in its budget. */
+class Slow extends Error {}
+
+const sleepFor = (ms: number): { done: Promise<never>; cancel(): void } => {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const done = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => reject(new Slow("budget")), ms);
+	});
+	return { done, cancel: () => clearTimeout(timer) };
+};
+
+/**
+ * The directory behind `PROFILES`: sources, the names they and the sessions report (memory only,
+ * an hour at most), each person's stored choice, and the picture proxy. Names reach
+ * `Speaker.name` only through `modelName`, which the identity service calls, and only for a
+ * provider the host lists in `profiles.modelVisible`.
+ */
+export class PersonDirectory implements PersonProfiles {
+	readonly #sources = new Map<string, ProfileSource>();
+	readonly #observed = new ExpiringMap<string>(10_000);
+	readonly #fetched = new ExpiringMap<Fetched | null>(10_000);
+	readonly #pending = new Map<string, Promise<Fetched | null>>();
+	readonly #pictures = new ExpiringMap<Picture | null>(512);
+	readonly #choices: ProfileChoices;
+	readonly #chosen = new ExpiringMap<string | null>(10_000);
+	readonly #links: ProfileLinks;
+	readonly #prefer: readonly string[];
+	readonly #modelVisible: ReadonlySet<string>;
+	readonly #logger: Logger;
+	readonly #now: () => number;
+	readonly #budget: number;
+	readonly #fetch: PersonProfilesOptions["fetch"];
+
+	constructor(options: PersonProfilesOptions) {
+		this.#choices = new ProfileChoices(options.sql);
+		this.#links = options.links;
+		this.#prefer = options.rules.prefer;
+		this.#modelVisible = new Set(options.rules.modelVisible);
+		this.#logger = options.logger;
+		this.#now = options.now ?? Date.now;
+		this.#budget = options.fetchBudgetMs ?? FETCH_BUDGET_MS;
+		this.#fetch = options.fetch;
+	}
+
+	register(source: ProfileSource): void {
+		if (source.provider.trim() === "")
+			throw new IdentityError("a profile source needs a provider");
+		if (this.#sources.has(source.provider))
+			throw new IdentityError(
+				`a profile source for ${source.provider} is already registered`,
+			);
+		this.#sources.set(source.provider, source);
+	}
+
+	sources(): readonly { provider: string; label: string }[] {
+		return [...this.#sources.values()].map(({ provider, label }) => ({
+			provider,
+			label,
+		}));
+	}
+
+	observed(principalId: string, provider: string, name: string): void {
+		const clean = cleanName(name);
+		if (clean)
+			this.#observed.set(
+				`${principalId}\0${provider}`,
+				clean,
+				this.#now(),
+				HOUR_MS,
+			);
+	}
+
+	async sourceOf(principalId: string): Promise<string | undefined> {
+		const linked = new Set(
+			(await this.#links.identities(principalId)).map((link) => link.provider),
+		);
+		const chosen = await this.#choice(principalId);
+		if (chosen && linked.has(chosen)) return chosen;
+		return this.#prefer.find((provider) => linked.has(provider));
+	}
+
+	async choose(principalId: string, provider: string | null): Promise<void> {
+		if ((await this.#links.displayName(principalId)) === undefined)
+			throw new IdentityError(`there is no principal ${principalId}`);
+		if (provider === null) await this.#choices.clear(principalId);
+		else {
+			const linked = (await this.#links.identities(principalId)).some(
+				(link) => link.provider === provider,
+			);
+			if (!linked)
+				throw new IdentityError(
+					`${provider} is not linked to principal ${principalId}, so it cannot name them`,
+				);
+			await this.#choices.set(principalId, provider);
+		}
+		this.#chosen.delete(principalId);
+	}
+
+	async of(principalId: string): Promise<PersonDisplay> {
+		const provider = await this.sourceOf(principalId);
+		const profile = provider
+			? await this.#profile(principalId, provider)
+			: undefined;
+		if (provider && profile?.name)
+			return {
+				name: profile.name,
+				source: provider,
+				picture: profile.pictureUrl !== undefined,
+			};
+		return {
+			name: (await this.#links.displayName(principalId)) ?? principalId,
+			picture: false,
+		};
+	}
+
+	async picture(principalId: string): Promise<Response | undefined> {
+		const provider = await this.sourceOf(principalId);
+		const source = provider ? this.#sources.get(provider) : undefined;
+		if (!provider || !source) return undefined;
+		const address = (await this.#profile(principalId, provider))?.pictureUrl;
+		if (!address) return undefined;
+		const now = this.#now();
+		let picture = this.#pictures.get(address, now);
+		if (picture === undefined) {
+			picture =
+				(await fetchPicture(address, source.pictureHosts, this.#fetch)) ?? null;
+			const at = this.#now();
+			this.#pictures.set(address, picture, at, picture ? HOUR_MS : MISS_MS);
+			while (
+				this.#pictures.weigh((held) => held?.bytes.byteLength ?? 0) >
+				PICTURES_MAX_BYTES
+			)
+				if (!this.#pictures.evictOldest()) break;
+		}
+		return picture ? pictureResponse(picture) : undefined;
+	}
+
+	/**
+	 * The name `Speaker.name` takes for the principal: their source's name when the host lists its
+	 * provider in `profiles.modelVisible`, else undefined. Core-internal: `PROFILES` does not carry it.
+	 */
+	async modelName(principalId: string): Promise<string | undefined> {
+		if (this.#modelVisible.size === 0) return undefined;
+		const provider = await this.sourceOf(principalId);
+		if (!provider || !this.#modelVisible.has(provider)) return undefined;
+		return (await this.#profile(principalId, provider))?.name;
+	}
+
+	async #choice(principalId: string): Promise<string | undefined> {
+		const now = this.#now();
+		const held = this.#chosen.get(principalId, now);
+		if (held !== undefined) return held ?? undefined;
+		const stored = (await this.#choices.get(principalId)) ?? null;
+		this.#chosen.set(principalId, stored, now, CHOICE_MS);
+		return stored ?? undefined;
+	}
+
+	/** The name a session reported or the source fetched for this provider, and the picture address. */
+	async #profile(
+		principalId: string,
+		provider: string,
+	): Promise<Fetched | undefined> {
+		const observed = this.#observed.get(
+			`${principalId}\0${provider}`,
+			this.#now(),
+		);
+		const source = this.#sources.get(provider);
+		const link = (await this.#links.identities(principalId)).find(
+			(candidate) => candidate.provider === provider,
+		);
+		const fetched =
+			source && link ? await this.#fetchOnce(source, link.subject) : null;
+		const name = observed ?? fetched?.name;
+		if (!name) return undefined;
+		return {
+			name,
+			...(fetched?.pictureUrl ? { pictureUrl: fetched.pictureUrl } : {}),
+		};
+	}
+
+	#fetchOnce(source: ProfileSource, subject: string): Promise<Fetched | null> {
+		const key = `${source.provider}\0${subject}`;
+		const held = this.#fetched.get(key, this.#now());
+		if (held !== undefined) return Promise.resolve(held);
+		const running = this.#pending.get(key);
+		if (running) return running;
+		const call = this.#ask(source, subject).then((found) => {
+			this.#fetched.set(key, found, this.#now(), found ? HOUR_MS : MISS_MS);
+			this.#pending.delete(key);
+			return found;
+		});
+		this.#pending.set(key, call);
+		return call;
+	}
+
+	/** One fetch inside its budget; a miss, a failure and a timeout all read as nothing. */
+	async #ask(source: ProfileSource, subject: string): Promise<Fetched | null> {
+		const controller = new AbortController();
+		const budget = sleepFor(this.#budget);
+		try {
+			const found = await Promise.race([
+				source.fetch(subject, controller.signal),
+				budget.done,
+			]);
+			const name = cleanName(found?.name);
+			return found && (name || found.pictureUrl)
+				? {
+						...(name ? { name } : {}),
+						...(found.pictureUrl ? { pictureUrl: found.pictureUrl } : {}),
+					}
+				: null;
+		} catch (error) {
+			// Only the provider and the kind of failure: no subject, no name, no address.
+			this.#logger.warn(
+				{ provider: source.provider, slow: error instanceof Slow },
+				"a profile source gave no profile",
+			);
+			return null;
+		} finally {
+			budget.cancel();
+			controller.abort();
+		}
+	}
+}

package/src/core/identity/principal-tables.ts

@@ -59,3 +59,13 @@ export const PRINCIPAL_SELF_LINKS = async (sql: SQL): Promise<void> => {
 		ALTER TABLE principal_identities ADD CONSTRAINT principal_identities_source_check
 		CHECK (source IN ('config', 'plugin', 'cli', 'jit', 'legacy', 'self'))`;
 };
+
+/** Which linked account represents each person (`PROFILES.choose`): only the choice, never a name or a picture address. */
+export const PRINCIPAL_PROFILE_CHOICES = async (sql: SQL): Promise<void> => {
+	await sql`
+		CREATE TABLE IF NOT EXISTS principal_profile_choices (
+			principal_id text PRIMARY KEY REFERENCES principals (id) ON DELETE CASCADE,
+			provider text NOT NULL,
+			chosen_at timestamptz NOT NULL DEFAULT now()
+		)`;
+};

package/src/core/identity/profile-choices.ts

@@ -0,0 +1,45 @@
+import type { SQL } from "bun";
+
+/**
+ * Which linked account represents each person, the one thing about profiles that is stored. A
+ * name or a picture address is never written to a table.
+ */
+export class ProfileChoices {
+	readonly #sql: SQL;
+
+	constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	async get(principalId: string): Promise<string | undefined> {
+		const rows: { provider: string }[] = await this.#sql`
+			SELECT provider FROM principal_profile_choices WHERE principal_id = ${principalId}`;
+		return rows[0]?.provider;
+	}
+
+	async set(principalId: string, provider: string): Promise<void> {
+		await this.#sql`
+			INSERT INTO principal_profile_choices (principal_id, provider, chosen_at)
+			VALUES (${principalId}, ${provider}, now())
+			ON CONFLICT (principal_id)
+			DO UPDATE SET provider = EXCLUDED.provider, chosen_at = EXCLUDED.chosen_at`;
+	}
+
+	async clear(principalId: string): Promise<void> {
+		await this.#sql`
+			DELETE FROM principal_profile_choices WHERE principal_id = ${principalId}`;
+	}
+}
+
+/**
+ * The provider a principal chose, read for the CLI beside a host that may not have made the table
+ * yet; undefined for no choice or no table.
+ */
+export async function chosenProfileSource(
+	sql: SQL,
+	principalId: string,
+): Promise<string | undefined> {
+	const [table] = await sql`
+		SELECT to_regclass('principal_profile_choices') IS NOT NULL AS made`;
+	return table?.made ? new ProfileChoices(sql).get(principalId) : undefined;
+}

package/src/core/identity/profile-memory.ts

@@ -0,0 +1,65 @@
+/** A map whose entries expire, holding at most `max`; the oldest goes first. Memory only. */
+export class ExpiringMap<V> {
+	readonly #entries = new Map<string, { value: V; until: number }>();
+	readonly #max: number;
+
+	constructor(max: number) {
+		this.#max = max;
+	}
+
+	get(key: string, now: number): V | undefined {
+		const entry = this.#entries.get(key);
+		if (!entry) return undefined;
+		if (entry.until <= now) {
+			this.#entries.delete(key);
+			return undefined;
+		}
+		return entry.value;
+	}
+
+	set(key: string, value: V, now: number, ttlMs: number): void {
+		this.#entries.delete(key);
+		this.#entries.set(key, { value, until: now + ttlMs });
+		for (const old of this.#entries.keys()) {
+			if (this.#entries.size <= this.#max) break;
+			this.#entries.delete(old);
+		}
+	}
+
+	delete(key: string): void {
+		this.#entries.delete(key);
+	}
+
+	/** The summed `weight` of what is held, for a cache bounded by size. */
+	weigh(weight: (value: V) => number): number {
+		let total = 0;
+		for (const entry of this.#entries.values()) total += weight(entry.value);
+		return total;
+	}
+
+	/** Drops the oldest entry; false when there is none. */
+	evictOldest(): boolean {
+		for (const old of this.#entries.keys()) {
+			this.#entries.delete(old);
+			return true;
+		}
+		return false;
+	}
+}
+
+const NAME_MAX = 80;
+
+/**
+ * A name a provider or a session reported, made safe to show and to give an agent: control and
+ * invisible formatting characters become spaces, runs of space one, at most 80 characters.
+ * Undefined when nothing is left.
+ */
+export function cleanName(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const text = value
+		.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+	if (text === "") return undefined;
+	return [...text].slice(0, NAME_MAX).join("").trim() || undefined;
+}

package/src/core/identity/profile-picture.ts

@@ -0,0 +1,117 @@
+/** The most a picture may weigh. */
+export const PICTURE_MAX_BYTES = 2 * 1024 * 1024;
+const PICTURE_BUDGET_MS = 5_000;
+
+/** A picture the proxy accepted: its bytes and the type they really are. */
+export interface Picture {
+	bytes: Uint8Array<ArrayBuffer>;
+	type: string;
+}
+
+type Fetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+/** The type a body's first bytes show, for the four accepted formats. */
+function sniff(bytes: Uint8Array): string | undefined {
+	const starts = (...values: number[]) =>
+		values.every((value, i) => bytes[i] === value);
+	if (starts(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a))
+		return "image/png";
+	if (starts(0xff, 0xd8, 0xff)) return "image/jpeg";
+	if (starts(0x47, 0x49, 0x46, 0x38)) return "image/gif";
+	if (
+		starts(0x52, 0x49, 0x46, 0x46) &&
+		bytes[8] === 0x57 &&
+		bytes[9] === 0x45 &&
+		bytes[10] === 0x42 &&
+		bytes[11] === 0x50
+	)
+		return "image/webp";
+	return undefined;
+}
+
+/** Reads a body up to the cap; undefined when it is longer. */
+async function readCapped(
+	response: Response,
+): Promise<Uint8Array<ArrayBuffer> | undefined> {
+	const length = Number(response.headers.get("content-length"));
+	if (Number.isFinite(length) && length > PICTURE_MAX_BYTES) {
+		await response.body?.cancel().catch(() => undefined);
+		return undefined;
+	}
+	const reader = response.body?.getReader();
+	if (!reader) return undefined;
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > PICTURE_MAX_BYTES) {
+			await reader.cancel().catch(() => undefined);
+			return undefined;
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(total);
+	let at = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, at);
+		at += chunk.byteLength;
+	}
+	return bytes;
+}
+
+/**
+ * Fetches a picture for the proxy: only an `https` address on one of the allowed hosts, no
+ * redirect followed, only PNG, JPEG, GIF or WebP whose header and first bytes agree (so an SVG is
+ * refused), at most 2 MiB. Undefined for anything else, a failure included.
+ */
+export async function fetchPicture(
+	address: string,
+	hosts: readonly string[],
+	fetchImpl: Fetch = fetch,
+): Promise<Picture | undefined> {
+	const url = URL.parse(address);
+	if (!url) return undefined;
+	if (
+		url.protocol !== "https:" ||
+		url.username !== "" ||
+		url.password !== "" ||
+		url.port !== "" ||
+		!hosts.some((host) => host.toLowerCase() === url.hostname)
+	)
+		return undefined;
+	try {
+		const response = await fetchImpl(url.href, {
+			redirect: "manual",
+			signal: AbortSignal.timeout(PICTURE_BUDGET_MS),
+			headers: { accept: "image/png,image/jpeg,image/gif,image/webp" },
+		});
+		if (response.status !== 200) {
+			await response.body?.cancel().catch(() => undefined);
+			return undefined;
+		}
+		const declared = (response.headers.get("content-type") ?? "")
+			.split(";")[0]
+			?.trim()
+			.toLowerCase();
+		const bytes = await readCapped(response);
+		if (!bytes) return undefined;
+		const type = sniff(bytes);
+		return type && type === declared ? { bytes, type } : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** The proxy's answer: `nosniff`, kept by the one browser for an hour. */
+export function pictureResponse(picture: Picture): Response {
+	return new Response(picture.bytes, {
+		headers: {
+			"content-type": picture.type,
+			"content-length": String(picture.bytes.byteLength),
+			"x-content-type-options": "nosniff",
+			"cache-control": "private, max-age=3600",
+		},
+	});
+}