@aweftjs/auth 0.1.0

package/src/modules/Enter.ts

@@ -0,0 +1,189 @@
+// auth/Enter: sign in, or sign up when the email is new, and hand the browser its cookie
+// (design 074). The route counts attempts, bounds the hashing in flight and the password's
+// length before anything is hashed (design 275), and asks the application's sign-up rule at
+// the door (design 291).
+
+import { createId, idToText } from '@aweftjs/codec';
+import { atomic } from '@aweftjs/core';
+import type { ModuleProps } from '@aweftjs/modules';
+import { type Refusal, sliding } from '@aweftjs/server';
+import type { Store } from '@aweftjs/store';
+
+import { type AuthContext, addressOf } from '../context.ts';
+import { hashPassword, verifyPassword } from '../password.ts';
+import { bodyOf, invalidConfig, json, numberOf, storeOf } from '../props.ts';
+import { findUser, idOfUserDoc, looksLikeEmail, normalEmail, userDoc } from '../users.ts';
+import type { Roles } from './Roles.ts';
+import type { Session } from './Session.ts';
+
+export const deps = ['auth/Session', 'auth/Roles'];
+
+export const defaults = {
+	attemptsPerEmail: 5,
+	attemptsPerAddress: 20,
+	attemptsWindowMs: 900_000,
+	hashesInFlight: 8,
+	passwordMin: 8,
+	passwordMax: 256,
+	refusePassword: null,
+	refuseSignUp: null,
+};
+
+/** What `refuseSignUp` is asked about: a sign-up the route is about to make (design 291). */
+export interface SignUp {
+	/** The address as it will be stored, normalised; nobody holds it yet. */
+	readonly email: string;
+	/** Every field of the request body but `email` and `password`: an invite token, a role picked on the form. */
+	readonly extra: Readonly<Record<string, unknown>>;
+	/** What the gate identified for the request: `user` is null, `address` is the peer's. */
+	readonly context: AuthContext;
+	/** The store the battery writes the user into, for a rule that reads a document of yours. */
+	readonly store: Store;
+}
+
+/** The application's sign-up rule: a refusal closes the door to that sign-up, nothing opens it. */
+export type RefuseSignUp = (signUp: SignUp) => Refusal | undefined | Promise<Refusal | undefined>;
+
+/** What a `user:<id>` document holds. `password` is the hash, never the password. */
+export interface UserDocument extends Record<string, unknown> {
+	email: string;
+	name: string | null;
+	password: string;
+	emailVerified: boolean;
+	createdAt: number;
+	modifiedAt: number;
+}
+
+export type Entered = { readonly user: string; readonly created: boolean } | { readonly refused: readonly Refusal[] };
+
+export interface Enter {
+	readonly public: true;
+	/** Sign in, or sign up when nobody has the email. Refuses a wrong password. */
+	enter(email: string, password: string): Promise<Entered>;
+	/**
+	 * The reasons a password is refused: not text, outside the configured length, or refused by
+	 * `refusePassword`. Empty when it is taken. What the sign-in route checks, for a route that
+	 * sets a password elsewhere (design 290).
+	 */
+	checkPassword(password: unknown): Promise<readonly Refusal[]>;
+	readonly routes: Record<string, (request: Request, context: AuthContext) => Promise<Response>>;
+}
+
+const MODULE = 'auth/Enter';
+const refuse = (detail: string, fix: string): Error => invalidConfig(MODULE, detail, fix);
+
+export default ({ imports, config, ...props }: ModuleProps): Enter => {
+	const store = storeOf(props);
+	const Session = imports.Session as Session;
+	const Roles = imports.Roles as Roles;
+	const windowMs = numberOf(MODULE, config, 'attemptsWindowMs');
+	const perEmail = sliding({ count: numberOf(MODULE, config, 'attemptsPerEmail'), windowMs });
+	const perAddress = sliding({ count: numberOf(MODULE, config, 'attemptsPerAddress'), windowMs });
+	const hashesInFlight = numberOf(MODULE, config, 'hashesInFlight');
+	const passwordMin = numberOf(MODULE, config, 'passwordMin');
+	const passwordMax = numberOf(MODULE, config, 'passwordMax');
+	if (passwordMax < passwordMin) throw refuse(`passwordMax ${String(passwordMax)} under passwordMin ${String(passwordMin)}`, 'Give passwordMax at least passwordMin.');
+	if (config.refusePassword !== null && typeof config.refusePassword !== 'function') {
+		throw refuse(`refusePassword ${JSON.stringify(config.refusePassword)}`, 'Give refusePassword a function of the password answering true to refuse it, or null.');
+	}
+	const refusePassword = config.refusePassword as ((password: string) => boolean | Promise<boolean>) | null;
+	if (config.refuseSignUp !== null && typeof config.refuseSignUp !== 'function') {
+		throw refuse(`refuseSignUp ${JSON.stringify(config.refuseSignUp)}`, 'Give refuseSignUp a function of the sign-up answering a refusal to refuse it and nothing to allow it, or null.');
+	}
+	const refuseSignUp = config.refuseSignUp as RefuseSignUp | null;
+	let hashing = 0;
+
+	// The two checks that cost nothing, before anything is counted or hashed.
+	const shapeOf = (password: unknown): Refusal | undefined => {
+		if (typeof password !== 'string' || password === '') return { code: 'password', message: 'password is text' };
+		const length = [...password].length;
+		if (length < passwordMin || length > passwordMax) {
+			return { code: 'password', message: `password is ${String(passwordMin)} to ${String(passwordMax)} characters` };
+		}
+		return undefined;
+	};
+
+	const notAllowed = (): Refusal => ({ code: 'password', message: 'that password is not allowed here' });
+
+	const checkPassword = async (password: unknown): Promise<readonly Refusal[]> => {
+		const shape = shapeOf(password);
+		if (shape !== undefined) return [shape];
+		return refusePassword !== null && await refusePassword(password as string) ? [notAllowed()] : [];
+	};
+
+	const enter = async (email: string, password: string): Promise<Entered> => {
+		const found = await findUser(store, email);
+		if (found === undefined) {
+			const id = idToText(createId());
+			const hash = await hashPassword(password);
+			const handle = await store.open(userDoc(id));
+			const now = Date.now();
+			atomic(() => {
+				Object.assign(handle.root, {
+					email: normalEmail(email), name: null, password: hash, emailVerified: false, createdAt: now, modifiedAt: now,
+				} satisfies UserDocument);
+			});
+			await store.settled(handle);
+			await store.close(handle);
+			await Roles.first(id);
+			return { user: id, created: true };
+		}
+		const handle = await store.open(found);
+		const ok = await verifyPassword(password, (handle.root as UserDocument).password);
+		await store.close(handle);
+		if (!ok) return { refused: [{ code: 'password', message: 'the password is wrong' }] };
+		return { user: idOfUserDoc(found), created: false };
+	};
+
+	const tooMany = (retryAfter: number): Response =>
+		json(429, { reasons: [{ code: 'attempts', message: 'too many sign-in attempts; wait and try again' }] }, { 'retry-after': String(retryAfter) });
+
+	return {
+		public: true,
+		enter,
+		checkPassword,
+		routes: {
+			'POST /api/session': async (request, context) => {
+				const body = await bodyOf(request);
+				const email = body?.email;
+				const password = body?.password;
+				if (typeof email !== 'string' || !looksLikeEmail(normalEmail(email))) {
+					return json(400, { reasons: [{ code: 'email', message: 'email is an address' }] });
+				}
+				const shape = shapeOf(password);
+				if (shape !== undefined) return json(400, { reasons: [shape] });
+				// Counted before anything is hashed, so a flood buys no hashing. The email's count
+				// is cleared on success below; the address's is not, since it counts requests.
+				const key = normalEmail(email);
+				const byAddress = perAddress.take(addressOf(context) ?? 'unknown');
+				if (!byAddress.ok) return tooMany(byAddress.retryAfter);
+				const byEmail = perEmail.take(key);
+				if (!byEmail.ok) return tooMany(byEmail.retryAfter);
+				if (refusePassword !== null && await refusePassword(password as string)) return json(400, { reasons: [notAllowed()] });
+				// The application's rule, asked of a sign-up only: a known email is a sign-in and there
+				// is no door to close. After the password rule, so a refused password spends no invite.
+				if (refuseSignUp !== null && await findUser(store, key) === undefined) {
+					const extra = Object.fromEntries(Object.entries(body ?? {}).filter(([name]) => name !== 'email' && name !== 'password'));
+					const refusal = await refuseSignUp({ email: key, extra, context, store });
+					if (refusal !== undefined) return json(403, { reasons: [refusal] });
+				}
+				if (hashing >= hashesInFlight) {
+					return json(503, { reasons: [{ code: 'busy', message: 'too many sign-ins are being checked; try again in a moment' }] }, { 'retry-after': '1' });
+				}
+				hashing += 1;
+				let outcome: Entered;
+				try {
+					outcome = await enter(email, password as string);
+				} finally {
+					hashing -= 1;
+				}
+				if ('refused' in outcome) return json(401, { reasons: outcome.refused });
+				perEmail.clear(key);
+				const token = await Session.issue(outcome.user);
+				return json(outcome.created ? 201 : 200, { user: outcome.user, created: outcome.created }, {
+					'set-cookie': Session.setCookie(token, request),
+				});
+			},
+		},
+	};
+};

package/src/modules/Gate.ts

@@ -0,0 +1,47 @@
+// auth/Gate: the gate that reads `public` and `needs` (designs 071, 074, 289).
+
+import type { ModuleProps } from '@aweftjs/modules';
+import type { Gate as ServerGate, Named, Refusal } from '@aweftjs/server';
+
+import { type AuthContext, userOf } from '../context.ts';
+import { isName } from '../names.ts';
+import type { Roles } from './Roles.ts';
+import type { Session } from './Session.ts';
+
+export const deps = ['auth/Session', 'auth/Roles'];
+
+const isPublic = (instance: unknown): boolean =>
+	instance !== null && typeof instance === 'object' && (instance as { public?: unknown }).public === true;
+
+/**
+ * The names a module declares it needs: one, a list, or none. A declaration that is neither a
+ * name nor a list of names is `undefined`: the module is refused to everyone, because a word
+ * that reads as narrow and admits broadly is the wrong way to fail.
+ */
+const needsOf = (instance: unknown): readonly string[] | undefined => {
+	if (instance === null || typeof instance !== 'object' || !('needs' in instance)) return [];
+	const held: unknown = (instance as { needs?: unknown }).needs;
+	if (held === undefined) return [];
+	if (isName(held)) return [held];
+	return Array.isArray(held) && held.every(isName) ? held : undefined;
+};
+
+export default ({ imports }: ModuleProps): ServerGate<AuthContext> => {
+	const Session = imports.Session as Session;
+	const Roles = imports.Roles as Roles;
+	return {
+		identify: (request, peer) => Session.whoIs(request, peer),
+		access: async ({ name, instance }: Named, context): Promise<Refusal[]> => {
+			const user = userOf(context);
+			const needs = needsOf(instance);
+			if (needs === undefined) return [{ code: 'needs', message: `${name} declares needs that is not a name or a list of names` }];
+			// A module that needs a name needs a person, whatever else it declares.
+			if (needs.length === 0 && isPublic(instance)) return [];
+			if (user === null) return [{ code: 'private', message: `${name} needs a signed-in user` }];
+			for (const wanted of needs) {
+				if (!(await Roles.may(user, wanted))) return [{ code: 'needs', message: `${name} needs ${wanted}` }];
+			}
+			return [];
+		},
+	};
+};

package/src/modules/Password.ts

@@ -0,0 +1,155 @@
+// auth/Password: change with the current password, forgot by mail, reset by the link (design 290).
+
+import { atomic } from '@aweftjs/core';
+import type { ModuleProps } from '@aweftjs/modules';
+import { type Refusal, sliding } from '@aweftjs/server';
+
+import { type AuthContext, addressOf, userOf } from '../context.ts';
+import { type Links, NOT_LIVE, TAKEN, links } from '../links.ts';
+import { type Mailer, type Outcome, mailLink, textOf, urlOf } from '../mail.ts';
+import { hashPassword, verifyPassword } from '../password.ts';
+import { bodyOf, json, numberOf, storeOf } from '../props.ts';
+import { findUser, idOfUserDoc, looksLikeEmail, normalEmail, userDoc } from '../users.ts';
+import type { Enter, UserDocument } from './Enter.ts';
+import type { Session } from './Session.ts';
+
+export const deps = ['auth/Session', 'auth/Enter', 'notify/Send'];
+
+export const defaults = {
+	subject: 'Reset your password',
+	url: null,
+	resetMs: 3_600_000,
+	attemptsPerUser: 5,
+	attemptsWindowMs: 900_000,
+	forgotPerEmail: 5,
+	forgotPerAddress: 20,
+	forgotWindowMs: 86_400_000,
+	sweepMs: 3_600_000,
+};
+
+export type Reset = { readonly user: string } | { readonly refused: readonly Refusal[] };
+
+export interface Password {
+	readonly public: true;
+	/** Set a new password for a person who gave the current one. Every other session of theirs is ended. */
+	change(user: string, current: unknown, password: unknown, keep?: string): Promise<Outcome>;
+	/** Mail the person with this address a link, or nothing for an address nobody has; `ok` either way. */
+	forgot(email: string): Promise<Outcome>;
+	/** Take a link and set the password. Every session of the person is ended. Refuses `taken` for a link already used and `token` for one that never was or is past its end. */
+	reset(token: unknown, password: unknown): Promise<Reset>;
+	stop(): void;
+	readonly routes: Record<string, (request: Request, context: AuthContext) => Promise<Response>>;
+}
+
+const MODULE = 'auth/Password';
+
+const WRONG: Refusal = { code: 'password', message: 'the current password is wrong' };
+
+export default ({ imports, config, ...props }: ModuleProps): Password => {
+	const store = storeOf(props);
+	const Session = imports.Session as Session;
+	const Enter = imports.Enter as Enter;
+	const mailer = imports.Send as Mailer;
+	const subject = textOf(MODULE, config, 'subject');
+	const url = urlOf(MODULE, config);
+	const attempts = sliding({ count: numberOf(MODULE, config, 'attemptsPerUser'), windowMs: numberOf(MODULE, config, 'attemptsWindowMs') });
+	const forgotWindowMs = numberOf(MODULE, config, 'forgotWindowMs');
+	const perEmail = sliding({ count: numberOf(MODULE, config, 'forgotPerEmail'), windowMs: forgotWindowMs });
+	const perAddress = sliding({ count: numberOf(MODULE, config, 'forgotPerAddress'), windowMs: forgotWindowMs });
+	const held: Links = links(store, 'reset', numberOf(MODULE, config, 'resetMs'), numberOf(MODULE, config, 'sweepMs'));
+
+	const rewrite = async (user: string, password: string): Promise<void> => {
+		const hash = await hashPassword(password);
+		const handle = await store.open(userDoc(user));
+		atomic(() => {
+			const root = handle.root as Partial<UserDocument>;
+			root.password = hash;
+			root.modifiedAt = Date.now();
+		});
+		await store.settled(handle);
+		await store.close(handle);
+	};
+
+	const change = async (user: string, current: unknown, password: unknown, keep?: string): Promise<Outcome> => {
+		if (await store.head(userDoc(user)) === 0) return { refused: [WRONG] };
+		const handle = await store.open(userDoc(user));
+		const ok = typeof current === 'string' && await verifyPassword(current, (handle.root as Partial<UserDocument>).password);
+		await store.close(handle);
+		if (!ok) return { refused: [WRONG] };
+		const refused = await Enter.checkPassword(password);
+		if (refused.length > 0) return { refused };
+		await rewrite(user, password as string);
+		await Session.revokeAll(user, keep);
+		return { ok: true };
+	};
+
+	const forgot = async (email: string): Promise<Outcome> => {
+		const found = await findUser(store, email);
+		if (found === undefined) return { ok: true };
+		const user = idOfUserDoc(found);
+		const token = await held.issue(user);
+		const failed = await mailLink(mailer, user, subject, 'Set a new password by opening this link:', url(token));
+		return failed === undefined ? { ok: true } : { refused: [failed] };
+	};
+
+	// The link is looked at before the password is checked, so a stranger's guess at a token
+	// costs no `refusePassword` lookup, and taken after, so a refused password burns no link.
+	const reset = async (token: unknown, password: unknown): Promise<Reset> => {
+		const seen = await held.peek(token);
+		if (seen === undefined || 'taken' in seen) return { refused: [seen === undefined ? NOT_LIVE : TAKEN] };
+		const refused = await Enter.checkPassword(password);
+		if (refused.length > 0) return { refused };
+		const link = await held.take(token);
+		if (link === undefined || 'taken' in link) return { refused: [link === undefined ? NOT_LIVE : TAKEN] };
+		const { user } = link;
+		await rewrite(user, password as string);
+		await Session.revokeAll(user);
+		return { user };
+	};
+
+	const tooMany = (retryAfter: number): Response =>
+		json(429, { reasons: [{ code: 'attempts', message: 'too many attempts; wait and try again' }] }, { 'retry-after': String(retryAfter) });
+
+	return {
+		public: true,
+		change,
+		forgot,
+		reset,
+		stop: () => { held.stop(); },
+		routes: {
+			'POST /api/password': async (request, context) => {
+				const user = userOf(context);
+				if (user === null) return json(401, { reasons: [{ code: 'private', message: 'sign in to change your password' }] });
+				// The current password is a password being guessed, so it is counted like a sign-in.
+				const taken = attempts.take(user);
+				if (!taken.ok) return tooMany(taken.retryAfter);
+				const body = await bodyOf(request);
+				const outcome = await change(user, body?.current, body?.password, context.session ?? undefined);
+				if ('refused' in outcome) return json(outcome.refused[0] === WRONG ? 401 : 400, { reasons: outcome.refused });
+				attempts.clear(user);
+				return json(200, outcome);
+			},
+			'POST /api/password/forgot': async (request, context) => {
+				const body = await bodyOf(request);
+				const email = body?.email;
+				if (typeof email !== 'string' || !looksLikeEmail(normalEmail(email))) {
+					return json(400, { reasons: [{ code: 'email', message: 'email is an address' }] });
+				}
+				// Counted before the lookup, because the send is what a stranger must not steer.
+				const byAddress = perAddress.take(addressOf(context) ?? 'unknown');
+				if (!byAddress.ok) return tooMany(byAddress.retryAfter);
+				const byEmail = perEmail.take(normalEmail(email));
+				if (!byEmail.ok) return tooMany(byEmail.retryAfter);
+				const outcome = await forgot(email);
+				if ('refused' in outcome) return json(502, { reasons: outcome.refused });
+				return json(200, outcome);
+			},
+			'POST /api/password/reset': async (request) => {
+				const body = await bodyOf(request);
+				const outcome = await reset(body?.token, body?.password);
+				if ('refused' in outcome) return json(400, { reasons: outcome.refused });
+				return json(200, outcome);
+			},
+		},
+	};
+};

package/src/modules/Roles.ts

@@ -0,0 +1,163 @@
+// auth/Roles: the names a person holds, kept in `roles:<user>` and read live (design 289).
+
+import { codecError } from '@aweftjs/codec';
+import { atomic, createArray } from '@aweftjs/core';
+import type { ModuleProps } from '@aweftjs/modules';
+import type { Connection } from '@aweftjs/server';
+
+import { type AuthContext, userOf } from '../context.ts';
+import { type Implies, holds, isName } from '../names.ts';
+import { notGated, storeOf } from '../props.ts';
+
+export const defaults = { implies: {}, first: [] };
+
+/** What a `roles:<user>` document holds. */
+export interface RolesDocument extends Record<string, unknown> {
+	names: string[];
+	modifiedAt: number;
+}
+
+export interface Roles {
+	/** Does the person hold the name: granted, covered by a granted name, or implied by one. Reads the store. False for text that is not a name, since nobody holds one. */
+	may(user: string, name: string): Promise<boolean>;
+	/** Give the person these names. A name already held is left as it is. */
+	grant(user: string, ...names: string[]): Promise<void>;
+	/** Take these names away. A name not held is nothing. */
+	revoke(user: string, ...names: string[]): Promise<void>;
+	/** What the person was granted, and nothing implied. */
+	names(user: string): Promise<string[]>;
+	/** Grant the configured `first` names when nobody signed up before this person. True when they were the first. */
+	first(user: string): Promise<boolean>;
+	/** The table, for a page that runs the same check. */
+	call(args: unknown, context: unknown): { implies: Implies };
+	connection(connection: Connection<AuthContext>): Promise<() => Promise<void>>;
+}
+
+const refuse = (detail: string, fix: string): Error => codecError('invalid-config', `auth/Roles was given ${detail}`, fix);
+
+const NAME_FIX = 'A name is non-empty text with no whitespace: admin, verified, products.abc123.';
+const LIST_FIX = 'Give first, and each entry of implies, a list of names: non-empty text with no whitespace.';
+
+const namesOf = (value: unknown, what: string): readonly string[] => {
+	if (!Array.isArray(value) || !value.every(isName)) throw refuse(`${what} ${JSON.stringify(value)}`, LIST_FIX);
+	return value as string[];
+};
+
+const impliesOf = (value: unknown): Implies => {
+	if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+		throw refuse(`implies ${JSON.stringify(value)}`, 'Give implies an object from a name to the list of names it implies.');
+	}
+	// No prototype, so a key such as `__proto__` is a name in the table and not a write to Object.
+	const table: Record<string, readonly string[]> = Object.create(null) as Record<string, readonly string[]>;
+	for (const [key, listed] of Object.entries(value as Record<string, unknown>)) {
+		if (!isName(key)) throw refuse(`the implies key ${JSON.stringify(key)}`, NAME_FIX);
+		table[key] = namesOf(listed, `implies.${key}`);
+	}
+	return table;
+};
+
+const invalidName = (name: unknown): Error =>
+	codecError('invalid-name', `auth/Roles was handed the name ${JSON.stringify(name)}`, NAME_FIX);
+
+const invalidUser = (user: unknown): Error =>
+	codecError('invalid-user', `auth/Roles was handed the user ${JSON.stringify(user)}`, 'Hand it the id the gate put on the context, which is text.');
+
+/** The one document this module keeps that is nobody's: whether a first sign-up has been seen. */
+const FIRST = 'auth:first';
+
+/** The page's write, refused: the names are the server's to give. */
+const READ_ONLY = { accept: () => [{ code: 'read-only', message: 'names are granted by the server; a page reads them' }] };
+
+export default async ({ config, ...props }: ModuleProps): Promise<Roles> => {
+	const store = storeOf(props);
+	const implies = impliesOf(config.implies);
+	const first = namesOf(config.first, 'first');
+	const doc = (user: string): string => `roles:${user}`;
+
+	const checked = (user: unknown, names: readonly unknown[]): string[] => {
+		if (typeof user !== 'string' || user === '') throw invalidUser(user);
+		for (const name of names) if (!isName(name)) throw invalidName(name);
+		return names as string[];
+	};
+
+	const writeFirst = async (granted: string | null): Promise<boolean> => {
+		const marker = await store.open(FIRST);
+		const root = marker.root as { granted?: string | null };
+		// Two sign-ups in flight open the same live document, so the first to get here writes
+		// it and the second reads it written.
+		const mine = root.granted === undefined;
+		if (mine) atomic(() => { Object.assign(root, { granted, at: Date.now() }); });
+		await store.settled(marker);
+		await store.close(marker);
+		return mine;
+	};
+
+	// The marker says whether a first sign-up has been seen. Where people exist and no marker
+	// does, this module was added to a store that already had them, and the next stranger to
+	// sign up is not the first: the index is read once, here, and the marker written for nobody.
+	if (await store.head(FIRST) === 0) {
+		const hits = await store.find({ where: [{ field: 'email', op: 'gt', value: '' }] });
+		if (hits.some((hit) => hit.doc.startsWith('user:'))) await writeFirst(null);
+	}
+
+	// `open` creates a document, and a check must not write one per person it asks about.
+	const granted = async (user: string): Promise<string[]> => {
+		if (await store.head(doc(user)) === 0) return [];
+		const handle = await store.open(doc(user));
+		const held = [...((handle.root as Partial<RolesDocument>).names ?? [])];
+		await store.close(handle);
+		return held;
+	};
+
+	const write = async (user: string, change: (names: string[]) => void): Promise<void> => {
+		const handle = await store.open(doc(user));
+		const root = handle.root as Partial<RolesDocument>;
+		atomic(() => {
+			if (root.names === undefined) root.names = createArray<string>() as string[];
+			change(root.names);
+			root.modifiedAt = Date.now();
+		});
+		await store.settled(handle);
+		await store.close(handle);
+	};
+
+	const grant = async (user: string, ...names: string[]): Promise<void> => {
+		const wanted = checked(user, names);
+		if (wanted.length === 0) return;
+		await write(user, (held) => {
+			for (const name of wanted) if (!held.includes(name)) held.push(name);
+		});
+	};
+
+	const firstOf = async (user: string): Promise<boolean> => {
+		checked(user, []);
+		if (await store.head(FIRST) !== 0) return false;
+		if (!(await writeFirst(user))) return false;
+		await grant(user, ...first);
+		return true;
+	};
+
+	return {
+		// A name built from a client's input can come out as no name at all, and the answer to
+		// "does anyone hold that" is no, not a fault.
+		may: async (user, name) => { checked(user, []); return isName(name) && holds(await granted(user), implies, name); },
+		grant,
+		revoke: async (user, ...names) => {
+			const unwanted = checked(user, names);
+			if (unwanted.length === 0 || await store.head(doc(user)) === 0) return;
+			await write(user, (held) => {
+				for (let at = held.length - 1; at >= 0; at -= 1) if (unwanted.includes(held[at]!)) held.splice(at, 1);
+			});
+		},
+		names: async (user) => { checked(user, []); return granted(user); },
+		first: firstOf,
+		call: () => ({ implies }),
+		connection: async ({ link, context }) => {
+			const user = userOf(context);
+			if (user === null) throw notGated();
+			const handle = await store.open(doc(user));
+			link.share('roles', handle.root, READ_ONLY);
+			return async () => { await store.close(handle); };
+		},
+	};
+};