@ultimabase/password 0.0.0-stage → 0.1.1

package/dist/plugin.js

@@ -0,0 +1,172 @@
+import { authPlugin } from '@ultimabase/auth';
+import { definePlugin, isMaster, master, PublicError, Refused, } from 'ultimabase';
+import manifest from '../package.json' with { type: 'json' };
+import { attemptOf, createUser, setPassword, signedIn, verified, } from './core.js';
+import { emailFunctions, mailerOf } from './email-functions.js';
+import { passwordFunctions } from './functions.js';
+import { emailOf, fieldProperty, passwordOf, valid } from './input.js';
+import { PasswordAttempt, PasswordHash, PasswordRequest } from './models.js';
+import { PasswordToken } from './tokens.js';
+const M = { as: master };
+const states = new WeakMap();
+/** The `create` of each model whose `use` lists `password()`. */
+const using = new WeakSet();
+function stateOf(auth) {
+    const state = states.get(auth);
+    if (state === undefined)
+        throw new Error('password has not started.');
+    return state;
+}
+/** The one model whose `use` lists `password()`. */
+function usersOf(models) {
+    // oxlint-disable-next-line typescript/unbound-method -- compared by identity, never called.
+    const users = models.filter(({ queries }) => using.has(queries.create));
+    const [first, second] = users;
+    if (first === undefined) {
+        throw new Refused('passwordPlugin() needs the user model to list it: add `use: [password()]` to defineUser.');
+    }
+    if (second !== undefined) {
+        throw new Refused(`${first.schema.name} and ${second.schema.name} both use password(): only the user model does.`);
+    }
+    return first;
+}
+const reserved = new Set([
+    'id',
+    'createdAt',
+    'updatedAt',
+    'email',
+    'password',
+    'emailVerified',
+]);
+/** The listed fields' properties; an unknown, a reserved or a missing one stops startup. */
+function signUpFields(users, listed) {
+    const { name, fields } = users.schema;
+    const where = `passwordPlugin({ signUp })`;
+    const properties = new Map();
+    for (const field of listed) {
+        const found = fields.find((each) => each.name === field);
+        if (found === undefined || reserved.has(field)) {
+            throw new Refused(`${where}: ${name}.${field} is not a field sign-up may take.`);
+        }
+        properties.set(field, fieldProperty(found, users.required.includes(field), where, users.validators[field]));
+    }
+    const missing = users.required.filter((field) => !properties.has(field));
+    if (missing.length > 0) {
+        throw new Refused(`${where}: ${name} needs ${missing.join(', ')} to be created; list them.`);
+    }
+    return properties;
+}
+/** A sign-up's data, checked against the list unless the caller is Master. */
+function signUpData(state, data, caller) {
+    if (isMaster(caller))
+        return data;
+    if (state.signUp === false) {
+        throw new PublicError('ACCESS_DENIED', 'Sign-up is closed.');
+    }
+    const { signUp } = state;
+    const issues = Object.keys(data)
+        .filter((key) => !signUp.has(key))
+        .map((key) => ({ path: ['data', key], message: 'Unknown field.' }));
+    if (issues.length > 0) {
+        throw new PublicError('VALIDATION_FAILED', 'Sign-up takes the listed fields only.', {
+            details: { issues },
+        });
+    }
+    return data;
+}
+/** The user model and the sign-up fields, `false` when sign-up is closed. */
+function configOf(options, models) {
+    const users = usersOf(models);
+    const listed = options.signUp ?? [];
+    const fields = listed === false ? false : signUpFields(users, listed);
+    return { users, fields };
+}
+const callerOf = (options) => options?.as ?? { kind: 'anonymous' };
+const definition = definePlugin({
+    name: 'password',
+    manifest,
+    requires: { auth: authPlugin },
+    models: [PasswordHash, PasswordAttempt, PasswordRequest, PasswordToken],
+    addedFields: (f) => ({
+        // Only Master confirms an email: rules read it (D-117).
+        emailVerified: f.boolean({ default: false }).with({
+            access: { create: () => false, update: () => false },
+        }),
+    }),
+    hooks: {
+        // The user's hash and tokens go with them (D-113, D-117).
+        afterDelete: async ({ record }) => {
+            const where = { userId: record.id };
+            await PasswordHash.deleteMany({ where }, M);
+            await PasswordToken.deleteMany({ where }, M);
+            const emails = { kind: 'email', subject: record.id };
+            await PasswordRequest.deleteMany({ where: emails }, M);
+        },
+    },
+    commands: ({ queries, plugins }) => {
+        using.add(queries.create);
+        return {
+            signUp: async ({ email, password, data }, options) => {
+                const state = stateOf(plugins.auth);
+                const checked = signUpData(state, data, callerOf(options));
+                const { user } = await createUser(state, valid(emailOf, email, 'email'), valid(passwordOf, password, 'password'), checked);
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the user model's row, created by its own queries.
+                return user;
+            },
+            signIn: async ({ email, password }, options) => {
+                const state = stateOf(plugins.auth);
+                const subject = valid(emailOf, email, 'email');
+                const client = options?.client;
+                const attempt = attemptOf(subject, client);
+                const checked = await verified(state, subject, password, attempt);
+                const opened = await signedIn(state, checked, client);
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the user model's row, read by its own queries.
+                return opened;
+            },
+            setPassword: async ({ id, password }, options) => {
+                const caller = callerOf(options);
+                const self = caller.kind === 'user' && caller.user.id === id;
+                if (!self && !isMaster(caller)) {
+                    throw new PublicError('ACCESS_DENIED', 'User.setPassword runs as Master or as the user.');
+                }
+                const state = stateOf(plugins.auth);
+                await setPassword(state, id, valid(passwordOf, password, 'password'));
+            },
+        };
+    },
+    // The functions are built before the APIs (D-89): they read the state
+    // when they run, and `api` stores it once auth's API exists.
+    api: ({ options, plugins, models, logger }) => {
+        const { users, fields } = configOf(options, models);
+        const signUp = fields === false ? false : new Set(fields.keys());
+        const { auth } = plugins;
+        states.set(auth, { auth, users, signUp, logger, sending: new Set() });
+    },
+    // The emails under way still query: they end before the database closes.
+    stop: async ({ plugins }) => {
+        await Promise.all(stateOf(plugins.auth).sending);
+    },
+    functions: ({ options, plugins, models }) => {
+        const { users, fields } = configOf(options, models);
+        const state = () => stateOf(plugins.auth);
+        const { sendEmail } = options;
+        const mailer = sendEmail === undefined ? undefined : mailerOf(sendEmail);
+        return [
+            ...passwordFunctions(state, users, fields, mailer),
+            ...(mailer === undefined ? [] : emailFunctions(state, mailer)),
+        ];
+    },
+});
+/**
+ * The password sign-in method; it requires `authPlugin()`.
+ *
+ * Known and kept (D-115): `signUp` refuses a taken email with
+ * `UNIQUE_VIOLATION`, which tells that the email has an account until email
+ * verification can hide it; a hundred failures on one account within 15
+ * minutes, from any addresses, lock it for everyone, and a hundred from one
+ * address lock that address out of every account (D-114); `SignedIn`
+ * holds the token even when the cookie is set.
+ */
+export const passwordPlugin = definition.plugin;
+/** The user model's entry: its commands, and its hash deleted with it. */
+export const password = definition.use;

package/dist/tokens.d.ts

@@ -0,0 +1,34 @@
+import type { Field, ModelOf, ScalarOptions } from 'ultimabase';
+import { PublicError } from 'ultimabase';
+/** What an email's token lets its holder do. */
+export type EmailKind = 'reset' | 'verify';
+/** What `sendEmail` receives: the application writes the text and the link. */
+export interface Email {
+    readonly kind: EmailKind;
+    /** The account's email, normalized. */
+    readonly to: string;
+    /** What the link carries, for `resetPassword` or `verifyEmail`. */
+    readonly token: string;
+    readonly userId: string;
+}
+type TokenFields = {
+    readonly userId: Field<string, ScalarOptions<string>>;
+    readonly kind: Field<string, ScalarOptions<string>>;
+    /** The token's SHA-256: a leaked database gives no working link. */
+    readonly hash: Field<string, {
+        readonly unique: true;
+    }>;
+    readonly expiresAt: Field<Date, ScalarOptions<Date>>;
+};
+export declare const PasswordToken: ModelOf<'PasswordToken', TokenFields, []>;
+/** A new token of `kind` for `userId`, which replaces the older one. */
+export declare function issueToken(userId: string, kind: EmailKind): Promise<string>;
+/** The user a token of `kind` was issued to; a wrong, used or expired one fails. */
+export declare function redeemToken(token: string, kind: EmailKind): Promise<string>;
+/**
+ * Counts an email to `userId`; past three within one hour, the refusal
+ * instead, and the email is not counted.
+ */
+export declare const emailLimited: (userId: string) => Promise<PublicError | undefined>;
+export {};
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/D,OAAO,EAAuB,WAAW,EAAE,MAAM,YAAY,CAAA;AAO7D,gDAAgD;AAChD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE1C,+EAA+E;AAC/E,MAAM,WAAW,KAAK;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACvB;AAOD,KAAK,WAAW,GAAG;IAClB,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACrD,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACnD,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;IACvD,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAA;CACpD,CAAA;AAED,eAAO,MAAM,aAAa,EAAE,OAAO,CAAC,eAAe,EAAE,WAAW,EAAE,EAAE,CAUjE,CAAA;AAKH,wEAAwE;AACxE,wBAAsB,UAAU,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,GACb,OAAO,CAAC,MAAM,CAAC,CAcjB;AAKD,oFAAoF;AACpF,wBAAsB,WAAW,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,GACb,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,WAChB,MAAM,KACZ,OAAO,CAAC,WAAW,GAAG,SAAS,CAAoC,CAAA"}

package/dist/tokens.js

@@ -0,0 +1,52 @@
+// password's emails (D-117): the tokens their links carry, used once, and
+// the emails each account receives within one hour.
+import { createHash, randomBytes } from 'node:crypto';
+import { defineModel, master, PublicError } from 'ultimabase';
+import { hour, hourly } from './models.js';
+const M = { as: master };
+/** The emails an account receives within one hour, of either kind. */
+const emails = 3;
+const lifetimes = {
+    reset: hour,
+    verify: 24 * hour,
+};
+export const PasswordToken = defineModel({
+    name: 'PasswordToken',
+    fields: (f) => ({
+        userId: f.string(),
+        kind: f.string(),
+        hash: f.string({ unique: true }),
+        expiresAt: f.dateTime(),
+    }),
+    indexes: [{ fields: ['userId', 'kind'] }, { fields: ['expiresAt'] }],
+});
+const hashOf = (token) => createHash('sha256').update(token).digest('base64url');
+/** A new token of `kind` for `userId`, which replaces the older one. */
+export async function issueToken(userId, kind) {
+    const now = Date.now();
+    await PasswordToken.deleteMany({ where: { expiresAt: { lte: new Date(now) } } }, M);
+    await PasswordToken.deleteMany({ where: { userId, kind } }, M);
+    const token = randomBytes(32).toString('base64url');
+    const expiresAt = new Date(now + lifetimes[kind]);
+    await PasswordToken.create({ data: { userId, kind, hash: hashOf(token), expiresAt } }, M);
+    return token;
+}
+const invalidLink = () => new PublicError('INVALID_CREDENTIALS', 'This link is invalid or has expired.');
+/** The user a token of `kind` was issued to; a wrong, used or expired one fails. */
+export async function redeemToken(token, kind) {
+    const hash = hashOf(token);
+    const stored = await PasswordToken.findUnique({ where: { hash } }, M);
+    if (stored?.kind !== kind)
+        throw invalidLink();
+    // One delete wins, so a token used twice at once works once.
+    const { count } = await PasswordToken.deleteMany({ where: { hash } }, M);
+    if (count === 0 || stored.expiresAt.getTime() <= Date.now()) {
+        throw invalidLink();
+    }
+    return stored.userId;
+}
+/**
+ * Counts an email to `userId`; past three within one hour, the refusal
+ * instead, and the email is not counted.
+ */
+export const emailLimited = async (userId) => hourly('email', userId, emails);

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@ultimabase/password",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Passwords for UltimaBase: sign-up, sign-in and password changes, hashed with Argon2id.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ultimabase.dev/docs/password",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/password"
+  },
+  "engines": {
+    "node": ">=24.7.0"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist && yarn run -T tsc --project tsconfig.build.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "ipaddr.js": "2.5.0"
+  },
+  "peerDependencies": {
+    "@ultimabase/auth": "^0.1.1",
+    "ultimabase": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/pg": "8.23.1",
+    "@ultimabase/auth": "0.1.1",
+    "@ultimabase/graphql": "0.1.1",
+    "@ultimabase/http": "0.1.1",
+    "@ultimabase/postgres": "0.1.1",
+    "graphql": "17.0.2",
+    "pg": "8.23.1",
+    "ultimabase": "0.1.1",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
 }

package/src/core.ts

@@ -0,0 +1,206 @@
+// What the functions and the commands share (D-113): signing a user up,
+// checking a password, setting one, and the session a success opens.
+import { randomUUID } from 'node:crypto'
+import type { AuthApi } from '@ultimabase/auth'
+import type {
+	Client,
+	Identity,
+	ExposedModel,
+	Logger,
+	Register,
+	Row,
+	UserOf,
+} from 'ultimabase'
+import { master, PublicError, transaction } from 'ultimabase'
+import { dummyHash, hashPassword, verifyPassword } from './hash.ts'
+import { normalized } from './input.ts'
+import type { Attempt } from './models.ts'
+import { limited, PasswordHash } from './models.ts'
+import { PasswordToken } from './tokens.ts'
+
+const M = { as: master }
+/** The method `AuthAccount` links a password's email with (D-113). */
+export const method = 'password'
+
+/** What each running application's password reads, by auth's API. */
+export interface State {
+	readonly auth: AuthApi
+	readonly users: ExposedModel
+	/** The fields a sign-up other than Master's takes, `false` when closed. */
+	readonly signUp: ReadonlySet<string> | false
+	readonly logger: Logger
+	/** The sends under way, which stopping waits for (D-117). */
+	readonly sending: Set<Promise<void>>
+}
+
+/** What a sign-in returns: its session, and the user read as itself. */
+export interface SignedIn<U = Row> {
+	/**
+	 * The session's token, there even when the cookie carries it: a mobile
+	 * client needs it, and a function cannot tell one client from another
+	 * (D-115).
+	 */
+	readonly token: string
+	readonly expiresAt: Date
+	readonly user: U | null
+}
+
+const invalid = () =>
+	new PublicError('INVALID_CREDENTIALS', 'Wrong email or password.')
+
+/** The attempt a client makes for `subject`; server code is not counted. */
+export const attemptOf = (
+	subject: string,
+	client: Client | undefined,
+): Attempt =>
+	client === undefined ? undefined : { subject, address: client.address }
+
+/**
+ * Creates the user, its account and its hash in one transaction, as Master:
+ * the caller's fields were checked against the list (D-113).
+ */
+export async function createUser(
+	state: State,
+	email: string,
+	password: string,
+	data: object,
+): Promise<{ readonly user: Row; readonly stamp: string }> {
+	const hash = await hashPassword(password)
+	const stamp = randomUUID()
+	return transaction(async () => {
+		const user = await state.users.queries.create({ data }, M)
+		await state.auth.linkAccount(user.id, method, email)
+		await PasswordHash.create({ data: { userId: user.id, hash, stamp } }, M)
+		return { user, stamp }
+	})
+}
+
+/** Rehashes the password `stamp` names, unless it was set since. */
+async function rehash(stamp: string, password: string): Promise<void> {
+	const hash = await hashPassword(password)
+	try {
+		await PasswordHash.update({ where: { stamp }, data: { hash } }, M)
+	} catch (error) {
+		if (!(error instanceof PublicError && error.code === 'NOT_FOUND')) {
+			throw error
+		}
+	}
+}
+
+/** No stored password is longer, so a longer one is not hashed. */
+const longest = 256
+
+/**
+ * The stamp of `userId`'s password when `password` is it, rehashing a stale
+ * hash; `undefined` otherwise.
+ */
+async function matches(
+	userId: string | undefined,
+	typed: string,
+): Promise<string | undefined> {
+	const password = normalized(typed)
+	if (Array.from(password).length > longest) return undefined
+	const stored =
+		userId === undefined
+			? null
+			: await PasswordHash.findUnique({ where: { userId } }, M)
+	// An unknown user costs a hash too, so the time tells nothing (D-113).
+	const { valid, stale } = await verifyPassword(
+		password,
+		stored?.hash ?? (await dummyHash()),
+	)
+	if (stored === null || !valid) return undefined
+	if (stale) await rehash(stored.stamp, password)
+	return stored.stamp
+}
+
+/** A user whose password checked, and the stamp it checked against. */
+export interface Verified {
+	readonly userId: string
+	readonly stamp: string
+}
+
+/** The user `email` and `password` sign in as, counting the attempt. */
+export async function verified(
+	state: State,
+	email: string,
+	password: string,
+	attempt: Attempt,
+): Promise<Verified> {
+	return limited(attempt, async () => {
+		const account = await state.auth.accountOf(method, email)
+		const stamp = await matches(account?.userId, password)
+		if (stamp === undefined || account === undefined) throw invalid()
+		return { userId: account.userId, stamp }
+	})
+}
+
+/** Checks `userId`'s current password, counting the attempt. */
+export async function checkCurrent(
+	userId: string,
+	password: string,
+	attempt: Attempt,
+): Promise<void> {
+	await limited(attempt, async () => {
+		if ((await matches(userId, password)) === undefined) throw invalid()
+	})
+}
+
+/**
+ * Replaces `userId`'s hash, ends every session of the user and deletes its
+ * pending reset tokens (D-117); the new stamp.
+ */
+export async function setPassword(
+	state: State,
+	userId: string,
+	password: string,
+): Promise<string> {
+	const stored = await PasswordHash.findUnique({ where: { userId } }, M)
+	if (stored === null) {
+		throw new PublicError(
+			'NOT_FOUND',
+			`User ${userId} has no password: sign it up with signUp.`,
+		)
+	}
+	const hash = await hashPassword(password)
+	const stamp = randomUUID()
+	await transaction(async () => {
+		await PasswordHash.update({ where: { userId }, data: { hash, stamp } }, M)
+		await PasswordToken.deleteMany({ where: { userId, kind: 'reset' } }, M)
+		await state.auth.revokeSessions(userId)
+	})
+	// Again once the stamp is visible: a sign-in that read the old one opened
+	// its session before, so this ends it (see `signedIn`).
+	await state.auth.revokeSessions(userId)
+	return stamp
+}
+
+/** The user as it reads itself, so its own field rules apply (D-113). */
+async function asItself(state: State, userId: string): Promise<Row | null> {
+	const { queries } = state.users
+	// A transport's queries are untyped; this is the user model's row.
+	const user: unknown = await queries.findUnique({ where: { id: userId } }, M)
+	if (user === null) return null
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the user model is the one the application registers (D-62, D-80).
+	const caller: Identity = { kind: 'user', user: user as UserOf<Register> }
+	return queries.findUnique({ where: { id: userId } }, { as: caller })
+}
+
+/**
+ * Opens a session for the user, with its cookie when a client is given. The
+ * stamp is read after: a password set since the check ends the user's
+ * sessions and fails, an older read means `setPassword` ends this one (D-113).
+ */
+export async function signedIn(
+	state: State,
+	{ userId, stamp }: Verified,
+	client: Client | undefined,
+): Promise<SignedIn> {
+	const { token, expiresAt } = await state.auth.signIn(userId, client)
+	const stored = await PasswordHash.findUnique({ where: { userId } }, M)
+	if (stored?.stamp !== stamp) {
+		await state.auth.revokeSessions(userId)
+		throw invalid()
+	}
+	return { token, expiresAt, user: await asItself(state, userId) }
+}

package/src/email-functions.ts

@@ -0,0 +1,137 @@
+// password's email functions (D-117): `requestPasswordReset`,
+// `resetPassword`, `verifyEmail` and `sendVerificationEmail`, there when the
+// application gives `sendEmail`.
+import type { FunctionShape } from 'ultimabase'
+import { allow, defineFunction, master, PublicError } from 'ultimabase'
+import type { State } from './core.ts'
+import { method, setPassword } from './core.ts'
+import {
+	outputSchema,
+	requestResetInput,
+	resetPasswordInput,
+	verifyEmailInput,
+} from './input.ts'
+import { requestLimited } from './models.ts'
+import type { Email, EmailKind } from './tokens.ts'
+import { emailLimited, issueToken, redeemToken } from './tokens.ts'
+
+/**
+ * Runs `work` after the response, so its time tells nothing; a failure is
+ * logged, and stopping the application waits for it.
+ */
+export function later(state: State, work: () => Promise<void>): void {
+	const task: Promise<void> = Promise.resolve()
+		.then(work)
+		.catch((error: unknown) => {
+			state.logger.error({ err: error }, 'An email failed to send.')
+		})
+		.finally(() => {
+			state.sending.delete(task)
+		})
+	state.sending.add(task)
+}
+
+/** The application's `sendEmail` (D-117). */
+export type SendEmail = (email: Email) => Promise<void>
+
+/**
+ * Sends `userId` an email of `kind` to `to`, with a new token; past the
+ * account's hourly limit, the refusal instead.
+ */
+export type Mailer = (
+	kind: EmailKind,
+	userId: string,
+	to: string,
+) => Promise<PublicError | undefined>
+
+export const mailerOf =
+	(sendEmail: SendEmail): Mailer =>
+	async (kind, userId, to) => {
+		const refused = await emailLimited(userId)
+		if (refused !== undefined) return refused
+		const token = await issueToken(userId, kind)
+		await sendEmail({ kind, to, token, userId })
+		return undefined
+	}
+
+const done = outputSchema<boolean>({ type: 'boolean' })
+const M = { as: master }
+
+/** Marks `userId`'s email verified: the user received an email (D-117). */
+async function verify(state: State, userId: string): Promise<void> {
+	const where = { id: userId }
+	await state.users.queries.update({ where, data: { emailVerified: true } }, M)
+}
+
+/** The functions that send an email or redeem its token; each is public. */
+export function emailFunctions(
+	stateOf: () => State,
+	mail: Mailer,
+): readonly FunctionShape[] {
+	const requestPasswordReset = defineFunction({
+		name: 'requestPasswordReset',
+		input: requestResetInput,
+		output: done,
+		run: async ({ input: { input }, client }) => {
+			const state = stateOf()
+			if (client !== undefined) await requestLimited('reset', client.address)
+			const { email } = input
+			// The same answer, and no wait, whether the email has an account.
+			later(state, async () => {
+				const account = await state.auth.accountOf(method, email)
+				if (account === undefined) return
+				await mail('reset', account.userId, email)
+			})
+			return true
+		},
+	}).with({ access: allow.public })
+	const resetPassword = defineFunction({
+		name: 'resetPassword',
+		input: resetPasswordInput,
+		output: done,
+		run: async ({ input: { input } }) => {
+			const state = stateOf()
+			const userId = await redeemToken(input.token, 'reset')
+			await setPassword(state, userId, input.password)
+			await verify(state, userId)
+			return true
+		},
+	}).with({ access: allow.public })
+	const verifyEmail = defineFunction({
+		name: 'verifyEmail',
+		input: verifyEmailInput,
+		output: done,
+		run: async ({ input: { input } }) => {
+			await verify(stateOf(), await redeemToken(input.token, 'verify'))
+			return true
+		},
+	}).with({ access: allow.public })
+	const sendVerificationEmail = defineFunction({
+		name: 'sendVerificationEmail',
+		output: done,
+		run: async ({ caller, client }) => {
+			if (caller.kind !== 'user') {
+				throw new PublicError(
+					'UNAUTHENTICATED',
+					'sendVerificationEmail needs a signed-in user.',
+				)
+			}
+			if (client !== undefined) await requestLimited('verify', client.address)
+			const { user } = caller
+			// The user's row, read as Master, holds the field password adds.
+			if (Reflect.get(user, 'emailVerified') === true) return true
+			const to = await stateOf().auth.subjectOf(user.id, method)
+			// A user signed in another way has no email to verify.
+			if (to === undefined) return true
+			const refused = await mail('verify', user.id, to)
+			if (refused !== undefined) throw refused
+			return true
+		},
+	}).with({ access: allow.public })
+	return [
+		requestPasswordReset,
+		resetPassword,
+		verifyEmail,
+		sendVerificationEmail,
+	]
+}