@aweftjs/auth 0.1.0

package/src/client-modules/Session.ts

@@ -0,0 +1,70 @@
+// auth/Session on the page: `createAuth` over the connection the stage handed in (design 245).
+
+import { codecError } from '@aweftjs/codec';
+import { type Derived, immutable, mutable } from '@aweftjs/core';
+import type { Client, Handle } from '@aweftjs/client';
+
+import { type Auth, createAuth } from '../auth-client.ts';
+
+const NO_CLIENT_FIX = 'Pass the client createClient answered as the StageContext client, or none at all.';
+const ANONYMOUS_FIX = 'Wait for user to read a string, or call enter first; an anonymous connection has no state.';
+
+const isClient = (value: unknown): value is Client => {
+	const held = value as Partial<Client> | null;
+	return held !== null && typeof held === 'object'
+		&& typeof held.ask === 'function' && typeof held.share === 'function'
+		&& typeof held.status === 'object' && held.status !== null;
+};
+
+const noClient = (what: string): Error =>
+	codecError('no-client', `auth/Session has no connection, so ${what}`, NO_CLIENT_FIX);
+
+/**
+ * Identity with no connection at all: anonymous, at once and for good (design 245).
+ *
+ * What a static render gets, because `render` has no socket to give. `user` reads `null` from the
+ * start, which is a known answer rather than a wait: a factory that awaits identity would
+ * otherwise never return, and `render` waits on every pending promise, so the whole render hung.
+ * A gate refuses at once instead, and the sign-in act is what a static render of a gated page
+ * holds.
+ */
+const anonymous = (): Auth => {
+	const who: Derived<string | null | undefined> = immutable(mutable<string | null | undefined>(null));
+	const nothing: Derived<readonly string[] | undefined> = immutable(mutable<readonly string[] | undefined>([]));
+	return {
+		user: who,
+		names: nothing,
+		may: () => false,
+		enter: async () => { throw noClient('no sign-in was sent'); },
+		leave: async () => { throw noClient('no sign-out was sent'); },
+		check: async () => { throw noClient('no lookup was sent'); },
+		verify: async () => { throw noClient('no verification was sent'); },
+		change: async () => { throw noClient('no password change was sent'); },
+		forgot: async () => { throw noClient('no reset mail was sent'); },
+		reset: async () => { throw noClient('no reset was sent'); },
+		// The same refusal the real one gives an anonymous connection, so a page that reads it
+		// takes one path rather than two.
+		state: <T extends object>(): Handle<T> => {
+			const ready = Promise.reject<T>(codecError('anonymous',
+				'there is no signed-in user to share a state document for', ANONYMOUS_FIX));
+			ready.catch(() => {});
+			return { document: undefined, ready, stop: () => {} };
+		},
+		stop: () => {},
+	};
+};
+
+export default ({ client, config }: { client?: unknown; config: Readonly<Record<string, unknown>> }): Auth => {
+	if (client === undefined) return anonymous();
+	if (!isClient(client)) {
+		throw codecError('no-client',
+			'auth/Session was handed a client with no status, ask or share on it',
+			NO_CLIENT_FIX);
+	}
+	const origin = config['origin'];
+	const fetch = config['fetch'];
+	return createAuth(client, {
+		...(typeof origin === 'string' ? { origin } : {}),
+		...(typeof fetch === 'function' ? { fetch: fetch as Exclude<Parameters<typeof createAuth>[1], undefined>['fetch'] } : {}),
+	});
+};

package/src/client-modules/SignIn.tsx

@@ -0,0 +1,110 @@
+// auth/SignIn: one form for signing in and signing up, because `enter` does both (design 245).
+//
+// It decides nothing an application would want back: no URL of its own, no redirect, and no
+// opinion about who may see what. Where to go afterwards is the application's.
+
+import { mutable } from '@aweftjs/core';
+import { Button, TextField, h, text } from '@aweftjs/ui';
+
+import type { Auth } from '../auth-client.ts';
+
+export const deps = ['auth/Session'];
+
+/** What a refusal from `enter` carries: one entry per problem, each naming the field it is about. */
+interface Reason {
+	readonly code: string;
+	readonly message: string;
+}
+
+const LAYOUT = 'display:flex;flex-direction:column;gap:1rem;max-width:22rem';
+
+const about = (reasons: readonly Reason[], code: string): string =>
+	reasons.filter((one) => one.code === code).map((one) => one.message).join(' ');
+
+/** Everything the refusal said that was not about one of the two fields. */
+const rest = (reasons: readonly Reason[]): string =>
+	reasons.filter((one) => one.code !== 'email' && one.code !== 'password')
+		.map((one) => one.message).join(' ');
+
+/** What the stage hands a refused act beside the refusal (design 244). */
+interface SignInProps {
+	/** Build the act the URL chose again. Present when this act is what `refused` names. */
+	readonly retry?: () => void;
+}
+
+export default ({ imports }: { imports: Readonly<Record<string, unknown>> }): {
+	title: unknown;
+	component: (props: SignInProps) => unknown;
+} => {
+	const session = imports['Session'] as Auth;
+
+	const component = (props: SignInProps): unknown => {
+		const email = mutable('');
+		const password = mutable('');
+		const emailProblem = mutable('');
+		const passwordProblem = mutable('');
+		const problem = mutable('');
+		const busy = mutable(false);
+
+		const submit = async (): Promise<void> => {
+			if (busy.get()) return;
+			busy.set(true);
+			emailProblem.set('');
+			passwordProblem.set('');
+			problem.set('');
+			try {
+				const outcome = await session.enter(email.get(), password.get());
+				if (!('refused' in outcome)) {
+					// This act is standing in for the one the URL asked for, so the thing to do once
+					// the reason has stopped holding is build that act again. The battery still picks
+					// no URL: `retry` is the stage's own, and the address does not move.
+					props.retry?.();
+					return;
+				}
+				const reasons = outcome.refused as readonly Reason[];
+				emailProblem.set(about(reasons, 'email'));
+				passwordProblem.set(about(reasons, 'password'));
+				problem.set(rest(reasons));
+			} catch (error) {
+				problem.set(String((error as Error)?.message ?? error));
+			} finally {
+				busy.set(false);
+			}
+		};
+
+		return (
+			<form
+				aria-label={text('Sign in')}
+				style={LAYOUT}
+				onSubmit={(event: unknown) => {
+					(event as { preventDefault(): void }).preventDefault();
+					void submit();
+				}}
+			>
+				<TextField
+					label={text('Email')}
+					value={email}
+					error={emailProblem}
+					placeholder={text('you@example.com')}
+					name="email"
+					autocomplete="email"
+				/>
+				<TextField
+					label={text('Password')}
+					value={password}
+					error={passwordProblem}
+					password
+					name="password"
+					autocomplete="current-password"
+				/>
+				{/* A refusal that named no field still has to be readable, and read out. */}
+				<p role="alert">{problem}</p>
+				{/* `Button` is a `type="button"`, so the click is the submit and the form's own
+				    handler is what the Enter key reaches. */}
+				<Button label={text('Sign in')} loading={busy} disabled={busy} onClick={submit} />
+			</form>
+		);
+	};
+
+	return { title: text('Sign in'), component };
+};

package/src/client-modules/Verify.tsx

@@ -0,0 +1,82 @@
+// auth/Verify: the page a verification link opens, and the button that asks for one (design 290).
+//
+// With a token in the act's parameters or the URL's query it takes the link as soon as it
+// mounts and says what happened. Without one it offers a signed-in person the mail. It picks no
+// URL: the application names it in the acts map, and points the mail at that address.
+
+import { all, mutable } from '@aweftjs/core';
+import { Button, h, text } from '@aweftjs/ui';
+import type { StageValue } from '@aweftjs/ui';
+
+import type { Auth } from '../auth-client.ts';
+import { tokenOf } from './stage-token.ts';
+
+export const deps = ['auth/Session'];
+
+interface Reason {
+	readonly code: string;
+	readonly message: string;
+}
+
+interface VerifyProps {
+	readonly stage?: StageValue;
+}
+
+const LAYOUT = 'display:flex;flex-direction:column;gap:1rem;max-width:22rem';
+
+const said = (reasons: readonly Reason[]): string => reasons.map((one) => one.message).join(' ');
+
+
+export default ({ imports }: { imports: Readonly<Record<string, unknown>> }): {
+	title: unknown;
+	component: (props: VerifyProps) => unknown;
+} => {
+	const session = imports['Session'] as Auth;
+
+	const component = (props: VerifyProps): unknown => {
+		const token = tokenOf(props.stage);
+		const note = mutable<unknown>('');
+		const problem = mutable('');
+		const busy = mutable(false);
+		const done = mutable(false);
+
+		const outcome = async (run: () => Promise<{ ok: true } | { refused: readonly Reason[] }>, onOk: unknown): Promise<void> => {
+			if (busy.get()) return;
+			busy.set(true);
+			problem.set('');
+			try {
+				const answer = await run();
+				if ('refused' in answer) problem.set(said(answer.refused));
+				else { note.set(onOk); done.set(true); }
+			} catch (error) {
+				problem.set(String((error as Error)?.message ?? error));
+			} finally {
+				busy.set(false);
+			}
+		};
+
+		if (token !== undefined) {
+			void outcome(() => session.verify(token), text('Your email address is verified.'));
+			return (
+				<section aria-label={text('Verify your email')} style={LAYOUT}>
+					<p>{note}</p>
+					<p role="alert">{problem}</p>
+				</section>
+			);
+		}
+
+		const send = (): Promise<void> => outcome(() => session.verify(), text('The link is on its way. Open it from your mail.'));
+		// Reads `user`, so the button follows a sign-in or a sign-out on the same page.
+		const anonymous = session.user.map((who) => who === null);
+		return (
+			<section aria-label={text('Verify your email')} style={LAYOUT}>
+				<p>{anonymous.map((is) => is ? text('Sign in first, then ask for the link.') : text('We will send a link to your email address.'))}</p>
+				<p>{note}</p>
+				<p role="alert">{problem}</p>
+				<Button label={text('Send the link')} loading={busy} disabled={all([anonymous, busy, done]).map(([is, sending, sent]) => is || sending || sent)} onClick={send} />
+			</section>
+		);
+	};
+
+	return { title: text('Verify your email'), component };
+};

package/src/client-modules/stage-token.ts

@@ -0,0 +1,11 @@
+// The token a link put in the URL, as the two link acts read it (design 290).
+
+import type { StageValue } from '@aweftjs/ui';
+
+/** The token the URL carries, from the act's own parameter first and the query second. */
+export const tokenOf = (stage: StageValue | undefined): string | undefined => {
+	const named = stage?.params.get().token;
+	if (typeof named === 'string' && named !== '') return named;
+	const queried = stage?.query.get().token;
+	return typeof queried === 'string' && queried !== '' ? queried : undefined;
+};

package/src/client.ts

@@ -0,0 +1,38 @@
+// The browser half of the battery, as an entry: what a page calls itself, and the source that
+// puts the four client modules on the page (designs 245, 290).
+
+import { fromBundle } from '@aweftjs/modules';
+import type { Source } from '@aweftjs/modules';
+
+export { createAuth } from './auth-client.ts';
+export type { Auth, AuthOptions, Entered, FetchInit, FetchResponse, Fetcher, Outcome } from './auth-client.ts';
+
+/**
+ * The battery's page modules, for a stage's `sources`.
+ *
+ * Four of them. `auth/Session` is `createAuth` over the connection the stage handed the loader,
+ * and its instance is the `Auth`: `user`, `names`, `may`, `enter`, `leave`, `state`, `check`,
+ * `verify`, `change`, `forgot`, `reset` and `stop`. Any module of yours that needs to know who
+ * the page is names it in `deps`. The other three are act modules: `auth/SignIn`, the sign-in
+ * and sign-up form in one, because `enter` does both; `auth/Verify`, the page a verification
+ * link opens, and the button that asks for one; `auth/Reset`, the forgot form, and the
+ * new-password form a reset link opens.
+ *
+ * The battery picks no URL. Put an act on the address you want it at, and it lands there; the
+ * mail links point at those addresses through the server modules' `url`. Put a module of the
+ * same name in an earlier source to replace any of them, or a file exporting only `config` to
+ * configure one: `auth/Session` reads `origin` and `fetch` out of its config.
+ *
+ * Example:
+ *   <StageContext sources={[app, authClient]} client={client}
+ *     acts={{ '': Home, notes: 'notes/Page', join: 'auth/SignIn', verify: 'auth/Verify', reset: 'auth/Reset' }}
+ *     refused="join">
+ *     <Stage />
+ *   </StageContext>
+ */
+export const authClient: Source = fromBundle({
+	'./auth/Session.ts': () => import('./client-modules/Session.ts'),
+	'./auth/SignIn.tsx': () => import('./client-modules/SignIn.tsx'),
+	'./auth/Verify.tsx': () => import('./client-modules/Verify.tsx'),
+	'./auth/Reset.tsx': () => import('./client-modules/Reset.tsx'),
+});

package/src/context.ts

@@ -0,0 +1,21 @@
+// What the auth gate resolves for a connection or a request (designs 074, 275).
+
+/** Who is on a connection: the user's id and the session token, or neither, and where it came from. */
+export interface AuthContext {
+	readonly user: string | null;
+	readonly session: string | null;
+	/** The peer address as far as the listener could tell, so a route can count by it. Absent from a context built by hand. */
+	readonly address?: string | undefined;
+}
+
+/** The user on a context, when the context is one of ours and has one. */
+export const userOf = (context: unknown): string | null => {
+	const user: unknown = (context as { user?: unknown } | null)?.user;
+	return typeof user === 'string' ? user : null;
+};
+
+/** The address on a context, when it carries one. */
+export const addressOf = (context: unknown): string | undefined => {
+	const address: unknown = (context as { address?: unknown } | null)?.address;
+	return typeof address === 'string' ? address : undefined;
+};

package/src/cookie.ts

@@ -0,0 +1,35 @@
+// The session cookie: reading it off a request, and writing the header that sets or clears it.
+
+/**
+ * Every non-empty value of the cookies by that name, in the order the client sent them.
+ *
+ * Several, because a browser sends every cookie of that name whose scope matches, and one
+ * from another path or another application on the host is not this battery's to refuse. An
+ * empty value is what the battery's own clearing header leaves, and counts as absent.
+ */
+export const cookiesOf = (request: Request, name: string): string[] => {
+	const header = request.headers.get('cookie');
+	if (header === null) return [];
+	const values: string[] = [];
+	for (const part of header.split(';')) {
+		const at = part.indexOf('=');
+		if (at < 0 || part.slice(0, at).trim() !== name) continue;
+		const value = part.slice(at + 1).trim();
+		if (value !== '') values.push(value);
+	}
+	return values;
+};
+
+/**
+ * The `Set-Cookie` value that sets the session cookie, or clears it for `null`.
+ *
+ * HttpOnly so script never reads it, SameSite=Lax so a cross-site form cannot present it,
+ * Secure when the request itself came over TLS, and a lifetime only when one is configured.
+ */
+export const setCookie = (name: string, token: string | null, request: Request, maxAgeMs?: number): string => {
+	const parts = [`${name}=${token ?? ''}`, 'Path=/', 'HttpOnly', 'SameSite=Lax'];
+	if (new URL(request.url).protocol === 'https:') parts.push('Secure');
+	if (token === null) parts.push('Max-Age=0');
+	else if (maxAgeMs !== undefined) parts.push(`Max-Age=${Math.floor(maxAgeMs / 1000)}`);
+	return parts.join('; ');
+};

package/src/index.ts

@@ -0,0 +1,53 @@
+// The battery, as two sources of server modules: the six every application loads, the two
+// that mail and so need notify, and the store paths they query (designs 074, 289, 290).
+
+import { fromBundle } from '@aweftjs/modules';
+import type { Source } from '@aweftjs/modules';
+import type { Declaration } from '@aweftjs/store';
+
+/**
+ * The auth modules, for `sources`.
+ *
+ * Put the application's own source first and a module of the same name there wins, which is
+ * how one of these is replaced. Each module reads the `store` the platform handed in, which
+ * on a server is the `store` given to `createServer`.
+ *
+ * Example:
+ *   const server = createServer({ sources: [own, auth], store, gate: 'auth/Gate', listener });
+ *   await server.start();
+ */
+export const auth: Source = fromBundle({
+	'./auth/Gate.ts': () => import('./modules/Gate.ts'),
+	'./auth/Session.ts': () => import('./modules/Session.ts'),
+	'./auth/Roles.ts': () => import('./modules/Roles.ts'),
+	'./auth/Enter.ts': () => import('./modules/Enter.ts'),
+	'./auth/Check.ts': () => import('./modules/Check.ts'),
+	'./auth/State.ts': () => import('./modules/State.ts'),
+});
+
+/**
+ * The two modules that mail: `auth/Verify` and `auth/Password`. Both name `notify/Send` in
+ * their `deps`, so list `notify` beside this, and give each its `url` in a same-named file.
+ *
+ * Example:
+ *   createServer({ sources: [own, auth, mail, notify], store, gate: 'auth/Gate', listener });
+ */
+export const mail: Source = fromBundle({
+	'./auth/Verify.ts': () => import('./modules/Verify.ts'),
+	'./auth/Password.ts': () => import('./modules/Password.ts'),
+});
+
+/**
+ * The paths the application declares on its store for these modules to query: `email` on
+ * user documents, `user` and `expires` on session and link documents.
+ *
+ * Example:
+ *   const store = createStore({ driver, declare: { ...paths, title: ['title'] } });
+ */
+export const paths: Declaration = { email: ['email'], user: ['user'], expires: ['expires'] };
+
+export { holds } from './names.ts';
+export type { Implies } from './names.ts';
+export type { AuthContext } from './context.ts';
+export type { RefuseSignUp, SignUp } from './modules/Enter.ts';
+export type { Roles } from './modules/Roles.ts';

package/src/links.ts

@@ -0,0 +1,107 @@
+// A one-time link: a token naming a `<prefix>:<token>` document that says who it is for and
+// when it stops being valid (design 290). Verification and reset links are both this. A taken
+// link keeps its document, marked, until its end, so a second opening is told it was taken
+// rather than that it never was (design 294).
+
+import { atomic } from '@aweftjs/core';
+import type { Refusal } from '@aweftjs/core';
+import type { Store } from '@aweftjs/store';
+
+import { isToken, mintToken } from './token.ts';
+
+/** What a link document holds. `user` and `expires` are paths the battery declares, so the sweep is a query. `taken` is set once and queried by nothing. */
+export interface LinkDocument extends Record<string, unknown> {
+	user: string;
+	expires: number;
+	createdAt: number;
+	taken?: boolean;
+}
+
+/** What a token names before its end: the user of a live link, or that the link was taken. */
+export type Link = { readonly user: string } | { readonly taken: true };
+
+/** What a route answers for a link it will not open: one nobody issued or past its end, and one already taken. */
+export const NOT_LIVE: Refusal = { code: 'token', message: 'this link is not one that can be used' };
+export const TAKEN: Refusal = { code: 'taken', message: 'this link has already been used' };
+
+export interface Links {
+	/** Mint a link for a user. Returns its token. */
+	issue(user: string): Promise<string>;
+	/** What the token names, leaving it. Undefined for a token nobody issued or one past its end. */
+	peek(token: unknown): Promise<Link | undefined>;
+	/** Take the link: the user it was for, and the document is marked taken. Undefined as `peek`. */
+	take(token: unknown): Promise<Link | undefined>;
+	/** Remove every link past its end, taken or not. Returns how many. */
+	sweep(): Promise<number>;
+	/** Stop the sweep timer. */
+	stop(): void;
+}
+
+/**
+ * The links of one prefix, each living `lifetimeMs` and swept every `sweepMs`.
+ *
+ * The first sweep runs when this is made, so a restart clears what expired while the process
+ * was down; the timer never keeps the process alive.
+ */
+export const links = (store: Store, prefix: string, lifetimeMs: number, sweepMs: number): Links => {
+	const doc = (token: string): string => `${prefix}:${token}`;
+
+	const linkOf = (held: Partial<LinkDocument>): Link | undefined => {
+		if (typeof held.user !== 'string' || typeof held.expires !== 'number' || held.expires <= Date.now()) return undefined;
+		return held.taken === true ? { taken: true } : { user: held.user };
+	};
+
+	const sweep = async (): Promise<number> => {
+		const now = Date.now();
+		let removed = 0;
+		for (const { doc: name, fields } of await store.find({ where: [{ field: 'expires', op: 'lt', value: now }] })) {
+			// The path is declared for every document, so the answer is filtered to this prefix.
+			if (!name.startsWith(`${prefix}:`) || typeof fields.expires !== 'number' || fields.expires >= now) continue;
+			await store.remove(name);
+			removed += 1;
+		}
+		return removed;
+	};
+
+	void sweep().catch(() => undefined);
+	const timer = setInterval(() => { void sweep().catch(() => undefined); }, sweepMs);
+	timer.unref?.();
+
+	return {
+		issue: async (user) => {
+			const token = mintToken();
+			const handle = await store.open(doc(token));
+			const now = Date.now();
+			atomic(() => {
+				Object.assign(handle.root, { user, expires: now + lifetimeMs, createdAt: now } satisfies LinkDocument);
+			});
+			await store.settled(handle);
+			await store.close(handle);
+			return token;
+		},
+		peek: async (token) => {
+			// A document that was never written has no commits, and `open` would create one.
+			if (!isToken(token) || await store.head(doc(token)) === 0) return undefined;
+			const handle = await store.open(doc(token));
+			const link = linkOf(handle.root as Partial<LinkDocument>);
+			await store.close(handle);
+			return link;
+		},
+		take: async (token) => {
+			if (!isToken(token) || await store.head(doc(token)) === 0) return undefined;
+			const handle = await store.open(doc(token));
+			const held = handle.root as Partial<LinkDocument>;
+			// Two takes of one token in flight open the same live document, so the first to get
+			// here marks it and the second reads the mark.
+			const link = linkOf(held);
+			if (link !== undefined && 'user' in link) {
+				atomic(() => { held.taken = true; });
+				await store.settled(handle);
+			}
+			await store.close(handle);
+			return link;
+		},
+		sweep,
+		stop: () => { clearInterval(timer); },
+	};
+};

package/src/mail.ts

@@ -0,0 +1,88 @@
+// What the two mail modules share: the mailer they name in `deps`, the link mail, and the
+// configuration checks (design 290). `notify/Send` is the mailer; its shape is stated here
+// rather than imported, so `auth` alone carries nothing of notify, and the integration suite
+// loads the real one to keep the two agreeing.
+
+import type { Refusal } from '@aweftjs/server';
+
+import { invalidConfig } from './props.ts';
+
+/** What one channel of a send answered, as `notify/Send` records it. */
+export type MailDelivery = { readonly ok: true } | { readonly ok: false; readonly error: string } | { readonly skipped: string };
+
+/** The part of `notify/Send` these modules call. */
+export interface Mailer {
+	send(options: {
+		readonly to: { readonly user: string };
+		readonly title: string;
+		readonly body: string;
+		readonly html: string;
+		readonly channels: readonly ['email'];
+	}): Promise<{ readonly delivery: { readonly email?: MailDelivery | undefined } }>;
+}
+
+/** The link an application's `url` makes for a token. */
+export type LinkUrl = (token: string) => string;
+
+/** What a mail route's call answers: done, or the reasons. */
+export type Outcome = { readonly ok: true } | { readonly refused: readonly Refusal[] };
+
+const escape = (text: string): string =>
+	text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/** Non-empty text, or `invalid-config`. */
+export const textOf = (module: string, config: Readonly<Record<string, unknown>>, key: string): string => {
+	const held: unknown = config[key];
+	if (typeof held !== 'string' || held === '') throw invalidConfig(module, `${key} ${JSON.stringify(held)}`, 'Give that setting some text.');
+	return held;
+};
+
+/** The `url` function, which has no default because a battery picks no URL. */
+export const urlOf = (module: string, config: Readonly<Record<string, unknown>>): LinkUrl => {
+	const held: unknown = config.url;
+	if (typeof held !== 'function') {
+		throw invalidConfig(module, `url ${JSON.stringify(held)}`, 'Give url a function of the token answering the address of the page that takes it: (token) => `https://app.example/verify?token=${token}`.');
+	}
+	return held as LinkUrl;
+};
+
+/**
+ * The `mail` refusal (design 293): `message` is the sentence a page shows the person, `detail`
+ * is what the mailer said, and `fix` is for whoever runs it. The route answers 502 and the
+ * token still stands.
+ */
+export interface MailRefusal extends Refusal {
+	readonly detail: string;
+	readonly fix: string;
+}
+
+export const mailFailed = (detail: string): MailRefusal => ({
+	code: 'mail',
+	message: 'the mail could not be sent; try again later',
+	detail,
+	fix: 'Check the email setting notify/Send was given; what the mailer answered is in detail.',
+});
+
+/**
+ * Mail a person one link. Answers the refusal when it did not go, and nothing when it did.
+ *
+ * The body is the sentence and the address as text; the HTML is the same with the address as a
+ * link, so a reader whose mail shows no HTML has the address to copy.
+ */
+export const mailLink = async (mailer: Mailer, user: string, subject: string, sentence: string, url: string): Promise<MailRefusal | undefined> => {
+	let delivery: MailDelivery | undefined;
+	try {
+		({ delivery: { email: delivery } } = await mailer.send({
+			to: { user },
+			title: subject,
+			body: `${sentence} ${url}`,
+			html: `<p>${escape(sentence)}</p><p><a href="${escape(url)}">${escape(url)}</a></p>`,
+			channels: ['email'],
+		}));
+	} catch (error) {
+		return mailFailed(String((error as Error)?.message ?? error));
+	}
+	if (delivery === null || typeof delivery !== 'object') return mailFailed('the mailer tried no email channel');
+	if ('skipped' in delivery) return mailFailed(String(delivery.skipped));
+	return delivery.ok === true ? undefined : mailFailed(String((delivery as { error?: unknown }).error ?? 'the mailer gave no reason'));
+};

package/src/modules/Check.ts

@@ -0,0 +1,31 @@
+// auth/Check: does anyone have this email. Public, so a sign-in form can ask before it asks
+// for a password.
+
+import { codecError } from '@aweftjs/codec';
+import type { ModuleProps } from '@aweftjs/modules';
+
+import { storeOf } from '../props.ts';
+import { findUser, looksLikeEmail, normalEmail } from '../users.ts';
+
+export interface Check {
+	readonly public: true;
+	exists(email: string): Promise<boolean>;
+	call(args: unknown): Promise<{ exists: boolean }>;
+}
+
+export default (props: ModuleProps): Check => {
+	const store = storeOf(props);
+	const exists = async (email: string): Promise<boolean> =>
+		looksLikeEmail(normalEmail(email)) && (await findUser(store, email)) !== undefined;
+	return {
+		public: true,
+		exists,
+		call: async (args) => {
+			const email: unknown = (args as { email?: unknown } | null)?.email;
+			if (typeof email !== 'string') {
+				throw codecError('malformed', 'auth/Check was called without an email string', 'Call it as { email: "someone@example.com" }.');
+			}
+			return { exists: await exists(email) };
+		},
+	};
+};