@ultimabase/password 0.1.2 → 0.2.0

package/dist/plugin.js

@@ -1,7 +1,8 @@
 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 { attemptOf, checkCurrent, createUser, setPassword, signedIn, verified, } from './core.js';
+import { created, committed, creating, readsEmail, updated, updating, } from './email-field.js';
 import { emailFunctions, mailerOf } from './email-functions.js';
 import { passwordFunctions } from './functions.js';
 import { emailOf, fieldProperty, passwordOf, valid } from './input.js';
@@ -17,6 +18,14 @@ function stateOf(auth) {
         throw new Error('password has not started.');
     return state;
 }
+/** Deletes the user's hash, links and email requests (D-113, D-160). */
+async function forget(userId) {
+    const where = { userId };
+    await PasswordHash.deleteMany({ where }, M);
+    await PasswordToken.deleteMany({ where }, M);
+    const emails = { kind: 'email', subject: userId };
+    await PasswordRequest.deleteMany({ where: emails }, M);
+}
 /** The one model whose `use` lists `password()`. */
 function usersOf(models) {
     // oxlint-disable-next-line typescript/unbound-method -- compared by identity, never called.
@@ -82,6 +91,14 @@ function configOf(options, models) {
     return { users, fields };
 }
 const callerOf = (options) => options?.as ?? { kind: 'anonymous' };
+/** Refuses `command` on user `id` but as Master or as that user. */
+function selfOrMaster(options, id, command) {
+    const caller = callerOf(options);
+    const self = caller.kind === 'user' && caller.user.id === id;
+    if (!self && !isMaster(caller)) {
+        throw new PublicError('ACCESS_DENIED', `User.${command} runs as Master or as the user.`);
+    }
+}
 const definition = definePlugin({
     name: 'password',
     manifest,
@@ -92,15 +109,31 @@ const definition = definePlugin({
         emailVerified: f.boolean({ default: false }).with({
             access: { create: () => false, update: () => false },
         }),
+        // Only Master writes it; the hooks keep the account in step (D-162).
+        email: f.string({ optional: true, unique: true }).with({
+            access: { read: readsEmail, create: () => false, update: () => false },
+        }),
     }),
     hooks: {
+        // The email and the password account stay one (D-162).
+        beforeCreate: ({ data }) => {
+            creating(data);
+        },
+        afterCreate: async ({ record, plugins }) => {
+            await created(stateOf(plugins.auth), record);
+        },
+        beforeUpdate: async ({ record, data, plugins }) => {
+            await updating(stateOf(plugins.auth), record, data);
+        },
+        afterUpdate: async ({ record, previous, plugins }) => {
+            await updated(stateOf(plugins.auth), record, previous);
+        },
+        afterUpdateCommit: ({ record, previous, plugins }) => {
+            committed(stateOf(plugins.auth), record, previous);
+        },
         // 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);
+            await forget(record.id);
         },
     },
     commands: ({ queries, plugins }) => {
@@ -124,14 +157,16 @@ const definition = definePlugin({
                 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.');
-                }
+                selfOrMaster(options, id, 'setPassword');
                 const state = stateOf(plugins.auth);
                 await setPassword(state, id, valid(passwordOf, password, 'password'));
             },
+            checkPassword: async ({ id, password }, options) => {
+                selfOrMaster(options, id, 'checkPassword');
+                const client = options?.client;
+                // Counted without a client too: the check guards an action (D-161).
+                await checkCurrent(id, password, attemptOf(id, client) ?? { subject: id });
+            },
         };
     },
     // The functions are built before the APIs (D-89): they read the state
@@ -140,7 +175,22 @@ const definition = definePlugin({
         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() });
+        const { sendEmail } = options;
+        const sending = new Set();
+        states.set(auth, { auth, users, signUp, logger, sending, sendEmail });
+        // A closed account keeps its row, without a password, an email or a
+        // verified one (D-160, D-162).
+        auth.onCloseAccount(async (userId) => {
+            await forget(userId);
+            const where = { id: userId };
+            const user = await users.queries.findUnique({ where }, M);
+            if (user === null)
+                return;
+            if (user.email === null && user.emailVerified !== true)
+                return;
+            const data = { email: null, emailVerified: false };
+            await users.queries.update({ where, data }, M);
+        });
     },
     // The emails under way still query: they end before the database closes.
     stop: async ({ plugins }) => {

package/dist/tokens.d.ts

@@ -1,16 +1,25 @@
 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 {
+export type EmailKind = 'reset' | 'verify' | 'emailChange';
+/**
+ * What `sendEmail` receives: the application writes the text and the link.
+ * `'emailChanged'` tells the old address its email changed (D-162).
+ */
+export type Email = {
     readonly kind: EmailKind;
-    /** The account's email, normalized. */
+    /** The address the link goes to, normalized. */
     readonly to: string;
-    /** What the link carries, for `resetPassword` or `verifyEmail`. */
+    /** What the link carries, for the function its kind names. */
     readonly token: string;
     readonly userId: string;
-}
+} | {
+    readonly kind: 'emailChanged';
+    /** The old address. */
+    readonly to: string;
+    readonly newEmail: string;
+    readonly userId: string;
+};
 type TokenFields = {
     readonly userId: Field<string, ScalarOptions<string>>;
     readonly kind: Field<string, ScalarOptions<string>>;
@@ -19,12 +28,22 @@ type TokenFields = {
         readonly unique: true;
     }>;
     readonly expiresAt: Field<Date, ScalarOptions<Date>>;
+    /** The address the email went to (D-162). */
+    readonly email: Field<string | null, {
+        readonly optional: true;
+    }>;
 };
 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>;
+/** A new token of `kind` for `userId`, sent to `email`; it replaces the older one. */
+export declare function issueToken(userId: string, kind: EmailKind, email: string): Promise<string>;
+/**
+ * The user a token of `kind` was issued to, and the address it was sent to;
+ * a wrong, used or expired one fails.
+ */
+export declare function redeemToken(token: string, kind: EmailKind): Promise<{
+    readonly userId: string;
+    readonly email: string | null;
+}>;
 /**
  * Counts an email to `userId`; past three within one hour, the refusal
  * instead, and the email is not counted.

package/dist/tokens.d.ts.map

@@ -1 +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"}
+{"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,GAAG,aAAa,CAAA;AAE1D;;;GAGG;AACH,MAAM,MAAM,KAAK,GACd;IACA,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACtB,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,uBAAuB;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACtB,CAAA;AAQJ,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;IACpD,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;CACjE,CAAA;AAED,eAAO,MAAM,aAAa,EAAE,OAAO,CAAC,eAAe,EAAE,WAAW,EAAE,EAAE,CAWjE,CAAA;AAKH,sFAAsF;AACtF,wBAAsB,UAAU,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAcjB;AAKD;;;GAGG;AACH,wBAAsB,WAAW,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,GACb,OAAO,CAAC;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAUrE;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,WAChB,MAAM,KACZ,OAAO,CAAC,WAAW,GAAG,SAAS,CAAoC,CAAA"}

package/dist/tokens.js

@@ -9,6 +9,7 @@ const emails = 3;
 const lifetimes = {
     reset: hour,
     verify: 24 * hour,
+    emailChange: hour,
 };
 export const PasswordToken = defineModel({
     name: 'PasswordToken',
@@ -17,22 +18,26 @@ export const PasswordToken = defineModel({
         kind: f.string(),
         hash: f.string({ unique: true }),
         expiresAt: f.dateTime(),
+        email: f.string({ optional: true }),
     }),
     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) {
+/** A new token of `kind` for `userId`, sent to `email`; it replaces the older one. */
+export async function issueToken(userId, kind, email) {
     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);
+    await PasswordToken.create({ data: { userId, kind, hash: hashOf(token), expiresAt, email } }, 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. */
+/**
+ * The user a token of `kind` was issued to, and the address it was sent 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);
@@ -43,7 +48,7 @@ export async function redeemToken(token, kind) {
     if (count === 0 || stored.expiresAt.getTime() <= Date.now()) {
         throw invalidLink();
     }
-    return stored.userId;
+    return { userId: stored.userId, email: stored.email };
 }
 /**
  * Counts an email to `userId`; past three within one hour, the refusal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimabase/password",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Passwords for UltimaBase: sign-up, sign-in and password changes, hashed with Argon2id.",
   "type": "module",
   "license": "Apache-2.0",
@@ -34,18 +34,18 @@
     "ipaddr.js": "2.5.0"
   },
   "peerDependencies": {
-    "@ultimabase/auth": "^0.1.2",
-    "ultimabase": "^0.1.2"
+    "@ultimabase/auth": "^0.2.0",
+    "ultimabase": "^0.2.0"
   },
   "devDependencies": {
     "@types/pg": "8.23.1",
-    "@ultimabase/auth": "0.1.2",
-    "@ultimabase/graphql": "0.1.2",
-    "@ultimabase/http": "0.1.2",
-    "@ultimabase/postgres": "0.1.2",
+    "@ultimabase/auth": "0.2.0",
+    "@ultimabase/graphql": "0.2.0",
+    "@ultimabase/http": "0.2.0",
+    "@ultimabase/postgres": "0.2.0",
     "graphql": "17.0.2",
     "pg": "8.23.1",
-    "ultimabase": "0.1.2",
+    "ultimabase": "0.2.0",
     "vite": "8.3.4",
     "vitest": "5.0.5"
   }

package/src/core.ts

@@ -13,6 +13,7 @@ import type {
 } from 'ultimabase'
 import { master, PublicError, transaction } from 'ultimabase'
 import { dummyHash, hashPassword, verifyPassword } from './hash.ts'
+import type { SendEmail } from './email-functions.ts'
 import { normalized } from './input.ts'
 import type { Attempt } from './models.ts'
 import { limited, PasswordHash } from './models.ts'
@@ -31,6 +32,7 @@ export interface State {
 	readonly logger: Logger
 	/** The sends under way, which stopping waits for (D-117). */
 	readonly sending: Set<Promise<void>>
+	readonly sendEmail: SendEmail | undefined
 }
 
 /** What a sign-in returns: its session, and the user read as itself. */
@@ -48,6 +50,10 @@ export interface SignedIn<U = Row> {
 const invalid = () =>
 	new PublicError('INVALID_CREDENTIALS', 'Wrong email or password.')
 
+/** The current password is known to be the user's: no email to name (D-161). */
+const wrongPassword = () =>
+	new PublicError('INVALID_CREDENTIALS', 'Wrong password.')
+
 /** The attempt a client makes for `subject`; server code is not counted. */
 export const attemptOf = (
 	subject: string,
@@ -57,7 +63,8 @@ export const attemptOf = (
 
 /**
  * Creates the user, its account and its hash in one transaction, as Master:
- * the caller's fields were checked against the list (D-113).
+ * the caller's fields were checked against the list (D-113). The email's
+ * hook links the account (D-162).
  */
 export async function createUser(
 	state: State,
@@ -68,8 +75,10 @@ export async function createUser(
 	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)
+		const user = await state.users.queries.create(
+			{ data: { ...data, email } },
+			M,
+		)
 		await PasswordHash.create({ data: { userId: user.id, hash, stamp } }, M)
 		return { user, stamp }
 	})
@@ -142,13 +151,14 @@ export async function checkCurrent(
 	attempt: Attempt,
 ): Promise<void> {
 	await limited(attempt, async () => {
-		if ((await matches(userId, password)) === undefined) throw invalid()
+		if ((await matches(userId, password)) === undefined) throw wrongPassword()
 	})
 }
 
 /**
- * Replaces `userId`'s hash, ends every session of the user and deletes its
- * pending reset tokens (D-117); the new stamp.
+ * Replaces `userId`'s hash, or gives one to an email without (D-162), ends
+ * every session of the user and deletes its pending reset tokens (D-117);
+ * the new stamp.
  */
 export async function setPassword(
 	state: State,
@@ -156,7 +166,10 @@ export async function setPassword(
 	password: string,
 ): Promise<string> {
 	const stored = await PasswordHash.findUnique({ where: { userId } }, M)
-	if (stored === null) {
+	const linked =
+		stored !== null ||
+		(await state.auth.subjectOf(userId, method)) !== undefined
+	if (!linked) {
 		throw new PublicError(
 			'NOT_FOUND',
 			`User ${userId} has no password: sign it up with signUp.`,
@@ -165,7 +178,10 @@ export async function setPassword(
 	const hash = await hashPassword(password)
 	const stamp = randomUUID()
 	await transaction(async () => {
-		await PasswordHash.update({ where: { userId }, data: { hash, stamp } }, M)
+		const data = { hash, stamp }
+		await (stored === null
+			? PasswordHash.create({ data: { userId, ...data } }, M)
+			: PasswordHash.update({ where: { userId }, data }, M))
 		await PasswordToken.deleteMany({ where: { userId, kind: 'reset' } }, M)
 		await state.auth.revokeSessions(userId)
 	})

package/src/email-field.ts

@@ -0,0 +1,104 @@
+// The user's `email` (D-162): the password account's subject, which
+// password's hooks keep in step with the field, whichever path writes it.
+import type { Caller } from 'ultimabase'
+import { isMaster, master, PublicError } from 'ultimabase'
+import type { State } from './core.ts'
+import { method } from './core.ts'
+import { later } from './email-functions.ts'
+import { emailOf, valid } from './input.ts'
+import { PasswordToken } from './tokens.ts'
+
+const M = { as: master }
+
+type Emailed = { readonly id: string; readonly email: string | null }
+type Draft = {
+	email?: string | null | undefined
+	emailVerified?: boolean | undefined
+}
+
+/** Only the user itself and Master read the email. */
+export const readsEmail = (facts: {
+	readonly caller: Caller
+	readonly record: { readonly id: string }
+}): boolean => {
+	const { caller, record } = facts
+	return (
+		isMaster(caller) || (caller.kind === 'user' && caller.user.id === record.id)
+	)
+}
+
+/** Normalizes a created user's email, as at sign-up. */
+export function creating(data: Draft): void {
+	if (typeof data.email === 'string') {
+		data.email = valid(emailOf, data.email, 'email')
+	}
+}
+
+/** Links the created user's email as its password account. */
+export async function created(state: State, record: Emailed): Promise<void> {
+	if (record.email === null) return
+	await state.auth.linkAccount(record.id, method, record.email)
+}
+
+/**
+ * Normalizes an updated email, refuses `null` while the account is linked,
+ * and unverifies another email unless the write verifies it.
+ */
+export async function updating(
+	state: State,
+	record: Emailed,
+	data: Draft,
+): Promise<void> {
+	if (data.email === undefined) return
+	const subject = await state.auth.subjectOf(record.id, method)
+	if (data.email === null) {
+		if (subject === undefined) return
+		const message = 'closeAccount removes the email.'
+		throw new PublicError('VALIDATION_FAILED', `email: ${message}`, {
+			details: { issues: [{ path: ['email'], message }] },
+		})
+	}
+	data.email = valid(emailOf, data.email, 'email')
+	if (data.email !== subject) data.emailVerified ??= false
+}
+
+/**
+ * Moves the password account to the new email, in the write's transaction,
+ * and deletes the links the old one received.
+ */
+export async function updated(
+	state: State,
+	record: Emailed,
+	previous: Emailed,
+): Promise<void> {
+	if (record.email === null || record.email === previous.email) return
+	const { auth } = state
+	const subject = await auth.subjectOf(record.id, method)
+	// Filling the field from the account changes nothing else.
+	if (subject === record.email) return
+	if (subject !== undefined) await auth.unlinkAccount(record.id, method)
+	await auth.linkAccount(record.id, method, record.email)
+	const where = { userId: record.id, kind: { in: ['reset', 'verify'] } }
+	await PasswordToken.deleteMany({ where }, M)
+}
+
+/** Tells the old address, once the change commits, when `sendEmail` exists. */
+export function committed(
+	state: State,
+	record: Emailed,
+	previous: Emailed,
+): void {
+	const { sendEmail } = state
+	const [from, to] = [previous.email, record.email]
+	if (sendEmail === undefined || from === null || to === null || from === to) {
+		return
+	}
+	later(state, async () => {
+		await sendEmail({
+			kind: 'emailChanged',
+			to: from,
+			newEmail: to,
+			userId: record.id,
+		})
+	})
+}

package/src/email-functions.ts

@@ -1,12 +1,21 @@
-// password's email functions (D-117): `requestPasswordReset`,
-// `resetPassword`, `verifyEmail` and `sendVerificationEmail`, there when the
-// application gives `sendEmail`.
+// password's email functions (D-117, D-162): `requestPasswordReset`,
+// `resetPassword`, `verifyEmail`, `sendVerificationEmail`,
+// `requestEmailChange` and `confirmEmailChange`, there when the application
+// gives `sendEmail`.
 import type { FunctionShape } from 'ultimabase'
-import { allow, defineFunction, master, PublicError } from 'ultimabase'
+import {
+	allow,
+	defineFunction,
+	master,
+	PublicError,
+	transaction,
+} from 'ultimabase'
 import type { State } from './core.ts'
-import { method, setPassword } from './core.ts'
+import { attemptOf, checkCurrent, method, setPassword } from './core.ts'
 import {
+	confirmEmailChangeInput,
 	outputSchema,
+	requestEmailChangeInput,
 	requestResetInput,
 	resetPasswordInput,
 	verifyEmailInput,
@@ -49,7 +58,7 @@ export const mailerOf =
 	async (kind, userId, to) => {
 		const refused = await emailLimited(userId)
 		if (refused !== undefined) return refused
-		const token = await issueToken(userId, kind)
+		const token = await issueToken(userId, kind, to)
 		await sendEmail({ kind, to, token, userId })
 		return undefined
 	}
@@ -91,7 +100,7 @@ export function emailFunctions(
 		output: done,
 		run: async ({ input: { input } }) => {
 			const state = stateOf()
-			const userId = await redeemToken(input.token, 'reset')
+			const { userId } = await redeemToken(input.token, 'reset')
 			await setPassword(state, userId, input.password)
 			await verify(state, userId)
 			return true
@@ -102,7 +111,8 @@ export function emailFunctions(
 		input: verifyEmailInput,
 		output: done,
 		run: async ({ input: { input } }) => {
-			await verify(stateOf(), await redeemToken(input.token, 'verify'))
+			const { userId } = await redeemToken(input.token, 'verify')
+			await verify(stateOf(), userId)
 			return true
 		},
 	}).with({ access: allow.public })
@@ -133,5 +143,52 @@ export function emailFunctions(
 		resetPassword,
 		verifyEmail,
 		sendVerificationEmail,
+		...emailChangeFunctions(stateOf, mail),
 	]
 }
+
+/** `requestEmailChange` and `confirmEmailChange` (D-162). */
+function emailChangeFunctions(
+	stateOf: () => State,
+	mail: Mailer,
+): readonly FunctionShape[] {
+	const requestEmailChange = defineFunction({
+		name: 'requestEmailChange',
+		input: requestEmailChangeInput,
+		output: done,
+		run: async ({ input: { input }, caller, client }) => {
+			if (caller.kind !== 'user') {
+				throw new PublicError(
+					'UNAUTHENTICATED',
+					'requestEmailChange needs a signed-in user.',
+				)
+			}
+			const { id } = caller.user
+			await checkCurrent(id, input.currentPassword, attemptOf(id, client))
+			const { newEmail } = input
+			// The caller proved the password: telling it is no enumeration.
+			if ((await stateOf().auth.accountOf(method, newEmail)) !== undefined) {
+				throw new PublicError('UNIQUE_VIOLATION', 'This email has an account.')
+			}
+			const refused = await mail('emailChange', id, newEmail)
+			if (refused !== undefined) throw refused
+			return true
+		},
+	}).with({ access: allow.public })
+	const confirmEmailChange = defineFunction({
+		name: 'confirmEmailChange',
+		input: confirmEmailChangeInput,
+		output: done,
+		run: async ({ input: { input } }) => {
+			const { users } = stateOf()
+			// A taken email undoes the redeem too: the link works until it expires.
+			await transaction(async () => {
+				const { userId, email } = await redeemToken(input.token, 'emailChange')
+				const data = { email, emailVerified: true }
+				await users.queries.update({ where: { id: userId }, data }, M)
+			})
+			return true
+		},
+	}).with({ access: allow.public })
+	return [requestEmailChange, confirmEmailChange]
+}

package/src/input.ts

@@ -332,6 +332,32 @@ export const verifyEmailInput: StandardSchema<
 	Named<{ readonly token: string }>
 > = namedInput('VerifyEmail', new Map([['token', property(text, string)]]))
 
+type RequestEmailChange = {
+	readonly newEmail: string
+	readonly currentPassword: string
+}
+
+/** What `requestEmailChange` takes: the new email and the password (D-162). */
+export const requestEmailChangeInput: StandardSchema<
+	Named<RequestEmailChange>,
+	Named<RequestEmailChange>
+> = namedInput(
+	'RequestEmailChange',
+	new Map([
+		['newEmail', email],
+		['currentPassword', property(text, string)],
+	]),
+)
+
+/** What `confirmEmailChange` takes: the email's token (D-162). */
+export const confirmEmailChangeInput: StandardSchema<
+	Named<{ readonly token: string }>,
+	Named<{ readonly token: string }>
+> = namedInput(
+	'ConfirmEmailChange',
+	new Map([['token', property(text, string)]]),
+)
+
 /** The email, the password and the listed user fields, by their names. */
 export const signUpInput = (
 	fields: ReadonlyMap<string, Property>,