@aweftjs/auth 0.1.0

package/dist/client-modules/SignIn.d.ts

@@ -0,0 +1,13 @@
+export declare const deps: string[];
+/** 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;
+}
+declare const _default: ({ imports }: {
+    imports: Readonly<Record<string, unknown>>;
+}) => {
+    title: unknown;
+    component: (props: SignInProps) => unknown;
+};
+export default _default;

package/dist/client-modules/SignIn.js

@@ -0,0 +1,58 @@
+import { template as _template } from '@aweftjs/ui';
+const _t0 = _template(["form", null, ["p", null]], [["props", []], ["child", [], 0], ["child", [], 0], ["props", [0]], ["child", [0], -1], ["child", [], -1]]);
+// 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';
+export const deps = ['auth/Session'];
+const LAYOUT = 'display:flex;flex-direction:column;gap:1rem;max-width:22rem';
+const about = (reasons, code) => 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) => reasons.filter((one) => one.code !== 'email' && one.code !== 'password')
+    .map((one) => one.message).join(' ');
+export default ({ imports }) => {
+    const session = imports['Session'];
+    const component = (props) => {
+        const email = mutable('');
+        const password = mutable('');
+        const emailProblem = mutable('');
+        const passwordProblem = mutable('');
+        const problem = mutable('');
+        const busy = mutable(false);
+        const submit = async () => {
+            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;
+                emailProblem.set(about(reasons, 'email'));
+                passwordProblem.set(about(reasons, 'password'));
+                problem.set(rest(reasons));
+            }
+            catch (error) {
+                problem.set(String(error?.message ?? error));
+            }
+            finally {
+                busy.set(false);
+            }
+        };
+        return (_t0([{ "aria-label": text('Sign in'), style: LAYOUT, onSubmit: (event) => {
+                    event.preventDefault();
+                    void submit();
+                } }, h(TextField, { label: text('Email'), value: email, error: emailProblem, placeholder: text('you@example.com'), name: "email", autocomplete: "email" }), h(TextField, { label: text('Password'), value: password, error: passwordProblem, password: true, name: "password", autocomplete: "current-password" }), { role: "alert" }, problem, h(Button, { label: text('Sign in'), loading: busy, disabled: busy, onClick: submit })]));
+    };
+    return { title: text('Sign in'), component };
+};

package/dist/client-modules/Verify.d.ts

@@ -0,0 +1,12 @@
+import type { StageValue } from '@aweftjs/ui';
+export declare const deps: string[];
+interface VerifyProps {
+    readonly stage?: StageValue;
+}
+declare const _default: ({ imports }: {
+    imports: Readonly<Record<string, unknown>>;
+}) => {
+    title: unknown;
+    component: (props: VerifyProps) => unknown;
+};
+export default _default;

package/dist/client-modules/Verify.js

@@ -0,0 +1,54 @@
+import { template as _template } from '@aweftjs/ui';
+const _t0 = _template(["section", null, ["p", null], ["p", null]], [["props", []], ["child", [0], -1], ["props", [1]], ["child", [1], -1]]);
+const _t1 = _template(["section", null, ["p", null], ["p", null], ["p", null]], [["props", []], ["child", [0], -1], ["child", [1], -1], ["props", [2]], ["child", [2], -1], ["child", [], -1]]);
+// 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 { tokenOf } from "./stage-token.js";
+export const deps = ['auth/Session'];
+const LAYOUT = 'display:flex;flex-direction:column;gap:1rem;max-width:22rem';
+const said = (reasons) => reasons.map((one) => one.message).join(' ');
+export default ({ imports }) => {
+    const session = imports['Session'];
+    const component = (props) => {
+        const token = tokenOf(props.stage);
+        const note = mutable('');
+        const problem = mutable('');
+        const busy = mutable(false);
+        const done = mutable(false);
+        const outcome = async (run, onOk) => {
+            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?.message ?? error));
+            }
+            finally {
+                busy.set(false);
+            }
+        };
+        if (token !== undefined) {
+            void outcome(() => session.verify(token), text('Your email address is verified.'));
+            return (_t0([{ "aria-label": text('Verify your email'), style: LAYOUT }, note, { role: "alert" }, problem]));
+        }
+        const send = () => 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 (_t1([{ "aria-label": text('Verify your email'), style: LAYOUT }, anonymous.map((is) => is ? text('Sign in first, then ask for the link.') : text('We will send a link to your email address.')), note, { role: "alert" }, problem, h(Button, { label: text('Send the link'), loading: busy, disabled: all([anonymous, busy, done]).map(([is, sending, sent]) => is || sending || sent), onClick: send })]));
+    };
+    return { title: text('Verify your email'), component };
+};

package/dist/client-modules/stage-token.d.ts

@@ -0,0 +1,3 @@
+import type { StageValue } from '@aweftjs/ui';
+/** The token the URL carries, from the act's own parameter first and the query second. */
+export declare const tokenOf: (stage: StageValue | undefined) => string | undefined;

package/dist/client-modules/stage-token.js

@@ -0,0 +1,9 @@
+// The token a link put in the URL, as the two link acts read it (design 290).
+/** The token the URL carries, from the act's own parameter first and the query second. */
+export const tokenOf = (stage) => {
+    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/dist/client.d.ts

@@ -0,0 +1,27 @@
+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 declare const authClient: Source;

package/dist/client.js

@@ -0,0 +1,33 @@
+// 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';
+export { createAuth } from "./auth-client.js";
+/**
+ * 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 = fromBundle({
+    './auth/Session.ts': () => import("./client-modules/Session.js"),
+    './auth/SignIn.tsx': () => import("./client-modules/SignIn.js"),
+    './auth/Verify.tsx': () => import("./client-modules/Verify.js"),
+    './auth/Reset.tsx': () => import("./client-modules/Reset.js"),
+});

package/dist/context.d.ts

@@ -0,0 +1,11 @@
+/** 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 declare const userOf: (context: unknown) => string | null;
+/** The address on a context, when it carries one. */
+export declare const addressOf: (context: unknown) => string | undefined;

package/dist/context.js

@@ -0,0 +1,11 @@
+// What the auth gate resolves for a connection or a request (designs 074, 275).
+/** The user on a context, when the context is one of ours and has one. */
+export const userOf = (context) => {
+    const user = context?.user;
+    return typeof user === 'string' ? user : null;
+};
+/** The address on a context, when it carries one. */
+export const addressOf = (context) => {
+    const address = context?.address;
+    return typeof address === 'string' ? address : undefined;
+};

package/dist/cookie.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare const cookiesOf: (request: Request, name: string) => string[];
+/**
+ * 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 declare const setCookie: (name: string, token: string | null, request: Request, maxAgeMs?: number) => string;

package/dist/cookie.js

@@ -0,0 +1,39 @@
+// 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, name) => {
+    const header = request.headers.get('cookie');
+    if (header === null)
+        return [];
+    const values = [];
+    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, token, request, maxAgeMs) => {
+    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/dist/index.d.ts

@@ -0,0 +1,35 @@
+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 declare const auth: Source;
+/**
+ * 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 declare const mail: Source;
+/**
+ * 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 declare const paths: Declaration;
+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/dist/index.js

@@ -0,0 +1,42 @@
+// 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';
+/**
+ * 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 = fromBundle({
+    './auth/Gate.ts': () => import("./modules/Gate.js"),
+    './auth/Session.ts': () => import("./modules/Session.js"),
+    './auth/Roles.ts': () => import("./modules/Roles.js"),
+    './auth/Enter.ts': () => import("./modules/Enter.js"),
+    './auth/Check.ts': () => import("./modules/Check.js"),
+    './auth/State.ts': () => import("./modules/State.js"),
+});
+/**
+ * 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 = fromBundle({
+    './auth/Verify.ts': () => import("./modules/Verify.js"),
+    './auth/Password.ts': () => import("./modules/Password.js"),
+});
+/**
+ * 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 = { email: ['email'], user: ['user'], expires: ['expires'] };
+export { holds } from "./names.js";

package/dist/links.d.ts

@@ -0,0 +1,37 @@
+import type { Refusal } from '@aweftjs/core';
+import type { Store } from '@aweftjs/store';
+/** 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 declare const NOT_LIVE: Refusal;
+export declare const TAKEN: Refusal;
+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 declare const links: (store: Store, prefix: string, lifetimeMs: number, sweepMs: number) => Links;

package/dist/links.js

@@ -0,0 +1,77 @@
+// 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 { isToken, mintToken } from "./token.js";
+/** 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 = { code: 'token', message: 'this link is not one that can be used' };
+export const TAKEN = { code: 'taken', message: 'this link has already been used' };
+/**
+ * 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, prefix, lifetimeMs, sweepMs) => {
+    const doc = (token) => `${prefix}:${token}`;
+    const linkOf = (held) => {
+        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 () => {
+        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 });
+            });
+            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);
+            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;
+            // 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/dist/mail.d.ts

@@ -0,0 +1,55 @@
+import type { Refusal } from '@aweftjs/server';
+/** 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[];
+};
+/** Non-empty text, or `invalid-config`. */
+export declare const textOf: (module: string, config: Readonly<Record<string, unknown>>, key: string) => string;
+/** The `url` function, which has no default because a battery picks no URL. */
+export declare const urlOf: (module: string, config: Readonly<Record<string, unknown>>) => 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 declare const mailFailed: (detail: string) => MailRefusal;
+/**
+ * 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 declare const mailLink: (mailer: Mailer, user: string, subject: string, sentence: string, url: string) => Promise<MailRefusal | undefined>;

package/dist/mail.js

@@ -0,0 +1,53 @@
+// 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 { invalidConfig } from "./props.js";
+const escape = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** Non-empty text, or `invalid-config`. */
+export const textOf = (module, config, key) => {
+    const held = 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, config) => {
+    const held = 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;
+};
+export const mailFailed = (detail) => ({
+    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, user, subject, sentence, url) => {
+    let delivery;
+    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?.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.error ?? 'the mailer gave no reason'));
+};

package/dist/modules/Check.d.ts

@@ -0,0 +1,10 @@
+import type { ModuleProps } from '@aweftjs/modules';
+export interface Check {
+    readonly public: true;
+    exists(email: string): Promise<boolean>;
+    call(args: unknown): Promise<{
+        exists: boolean;
+    }>;
+}
+declare const _default: (props: ModuleProps) => Check;
+export default _default;

package/dist/modules/Check.js

@@ -0,0 +1,20 @@
+// 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 { storeOf } from "../props.js";
+import { findUser, looksLikeEmail, normalEmail } from "../users.js";
+export default (props) => {
+    const store = storeOf(props);
+    const exists = async (email) => looksLikeEmail(normalEmail(email)) && (await findUser(store, email)) !== undefined;
+    return {
+        public: true,
+        exists,
+        call: async (args) => {
+            const email = args?.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) };
+        },
+    };
+};