@aweftjs/auth 0.1.0

package/dist/modules/Enter.d.ts

@@ -0,0 +1,57 @@
+import type { ModuleProps } from '@aweftjs/modules';
+import { type Refusal } from '@aweftjs/server';
+import type { Store } from '@aweftjs/store';
+import { type AuthContext } from '../context.ts';
+export declare const deps: string[];
+export declare const defaults: {
+    attemptsPerEmail: number;
+    attemptsPerAddress: number;
+    attemptsWindowMs: number;
+    hashesInFlight: number;
+    passwordMin: number;
+    passwordMax: number;
+    refusePassword: null;
+    refuseSignUp: null;
+};
+/** What `refuseSignUp` is asked about: a sign-up the route is about to make (design 291). */
+export interface SignUp {
+    /** The address as it will be stored, normalised; nobody holds it yet. */
+    readonly email: string;
+    /** Every field of the request body but `email` and `password`: an invite token, a role picked on the form. */
+    readonly extra: Readonly<Record<string, unknown>>;
+    /** What the gate identified for the request: `user` is null, `address` is the peer's. */
+    readonly context: AuthContext;
+    /** The store the battery writes the user into, for a rule that reads a document of yours. */
+    readonly store: Store;
+}
+/** The application's sign-up rule: a refusal closes the door to that sign-up, nothing opens it. */
+export type RefuseSignUp = (signUp: SignUp) => Refusal | undefined | Promise<Refusal | undefined>;
+/** What a `user:<id>` document holds. `password` is the hash, never the password. */
+export interface UserDocument extends Record<string, unknown> {
+    email: string;
+    name: string | null;
+    password: string;
+    emailVerified: boolean;
+    createdAt: number;
+    modifiedAt: number;
+}
+export type Entered = {
+    readonly user: string;
+    readonly created: boolean;
+} | {
+    readonly refused: readonly Refusal[];
+};
+export interface Enter {
+    readonly public: true;
+    /** Sign in, or sign up when nobody has the email. Refuses a wrong password. */
+    enter(email: string, password: string): Promise<Entered>;
+    /**
+     * The reasons a password is refused: not text, outside the configured length, or refused by
+     * `refusePassword`. Empty when it is taken. What the sign-in route checks, for a route that
+     * sets a password elsewhere (design 290).
+     */
+    checkPassword(password: unknown): Promise<readonly Refusal[]>;
+    readonly routes: Record<string, (request: Request, context: AuthContext) => Promise<Response>>;
+}
+declare const _default: ({ imports, config, ...props }: ModuleProps) => Enter;
+export default _default;

package/dist/modules/Enter.js

@@ -0,0 +1,143 @@
+// auth/Enter: sign in, or sign up when the email is new, and hand the browser its cookie
+// (design 074). The route counts attempts, bounds the hashing in flight and the password's
+// length before anything is hashed (design 275), and asks the application's sign-up rule at
+// the door (design 291).
+import { createId, idToText } from '@aweftjs/codec';
+import { atomic } from '@aweftjs/core';
+import { sliding } from '@aweftjs/server';
+import { addressOf } from "../context.js";
+import { hashPassword, verifyPassword } from "../password.js";
+import { bodyOf, invalidConfig, json, numberOf, storeOf } from "../props.js";
+import { findUser, idOfUserDoc, looksLikeEmail, normalEmail, userDoc } from "../users.js";
+export const deps = ['auth/Session', 'auth/Roles'];
+export const defaults = {
+    attemptsPerEmail: 5,
+    attemptsPerAddress: 20,
+    attemptsWindowMs: 900_000,
+    hashesInFlight: 8,
+    passwordMin: 8,
+    passwordMax: 256,
+    refusePassword: null,
+    refuseSignUp: null,
+};
+const MODULE = 'auth/Enter';
+const refuse = (detail, fix) => invalidConfig(MODULE, detail, fix);
+export default ({ imports, config, ...props }) => {
+    const store = storeOf(props);
+    const Session = imports.Session;
+    const Roles = imports.Roles;
+    const windowMs = numberOf(MODULE, config, 'attemptsWindowMs');
+    const perEmail = sliding({ count: numberOf(MODULE, config, 'attemptsPerEmail'), windowMs });
+    const perAddress = sliding({ count: numberOf(MODULE, config, 'attemptsPerAddress'), windowMs });
+    const hashesInFlight = numberOf(MODULE, config, 'hashesInFlight');
+    const passwordMin = numberOf(MODULE, config, 'passwordMin');
+    const passwordMax = numberOf(MODULE, config, 'passwordMax');
+    if (passwordMax < passwordMin)
+        throw refuse(`passwordMax ${String(passwordMax)} under passwordMin ${String(passwordMin)}`, 'Give passwordMax at least passwordMin.');
+    if (config.refusePassword !== null && typeof config.refusePassword !== 'function') {
+        throw refuse(`refusePassword ${JSON.stringify(config.refusePassword)}`, 'Give refusePassword a function of the password answering true to refuse it, or null.');
+    }
+    const refusePassword = config.refusePassword;
+    if (config.refuseSignUp !== null && typeof config.refuseSignUp !== 'function') {
+        throw refuse(`refuseSignUp ${JSON.stringify(config.refuseSignUp)}`, 'Give refuseSignUp a function of the sign-up answering a refusal to refuse it and nothing to allow it, or null.');
+    }
+    const refuseSignUp = config.refuseSignUp;
+    let hashing = 0;
+    // The two checks that cost nothing, before anything is counted or hashed.
+    const shapeOf = (password) => {
+        if (typeof password !== 'string' || password === '')
+            return { code: 'password', message: 'password is text' };
+        const length = [...password].length;
+        if (length < passwordMin || length > passwordMax) {
+            return { code: 'password', message: `password is ${String(passwordMin)} to ${String(passwordMax)} characters` };
+        }
+        return undefined;
+    };
+    const notAllowed = () => ({ code: 'password', message: 'that password is not allowed here' });
+    const checkPassword = async (password) => {
+        const shape = shapeOf(password);
+        if (shape !== undefined)
+            return [shape];
+        return refusePassword !== null && await refusePassword(password) ? [notAllowed()] : [];
+    };
+    const enter = async (email, password) => {
+        const found = await findUser(store, email);
+        if (found === undefined) {
+            const id = idToText(createId());
+            const hash = await hashPassword(password);
+            const handle = await store.open(userDoc(id));
+            const now = Date.now();
+            atomic(() => {
+                Object.assign(handle.root, {
+                    email: normalEmail(email), name: null, password: hash, emailVerified: false, createdAt: now, modifiedAt: now,
+                });
+            });
+            await store.settled(handle);
+            await store.close(handle);
+            await Roles.first(id);
+            return { user: id, created: true };
+        }
+        const handle = await store.open(found);
+        const ok = await verifyPassword(password, handle.root.password);
+        await store.close(handle);
+        if (!ok)
+            return { refused: [{ code: 'password', message: 'the password is wrong' }] };
+        return { user: idOfUserDoc(found), created: false };
+    };
+    const tooMany = (retryAfter) => json(429, { reasons: [{ code: 'attempts', message: 'too many sign-in attempts; wait and try again' }] }, { 'retry-after': String(retryAfter) });
+    return {
+        public: true,
+        enter,
+        checkPassword,
+        routes: {
+            'POST /api/session': async (request, context) => {
+                const body = await bodyOf(request);
+                const email = body?.email;
+                const password = body?.password;
+                if (typeof email !== 'string' || !looksLikeEmail(normalEmail(email))) {
+                    return json(400, { reasons: [{ code: 'email', message: 'email is an address' }] });
+                }
+                const shape = shapeOf(password);
+                if (shape !== undefined)
+                    return json(400, { reasons: [shape] });
+                // Counted before anything is hashed, so a flood buys no hashing. The email's count
+                // is cleared on success below; the address's is not, since it counts requests.
+                const key = normalEmail(email);
+                const byAddress = perAddress.take(addressOf(context) ?? 'unknown');
+                if (!byAddress.ok)
+                    return tooMany(byAddress.retryAfter);
+                const byEmail = perEmail.take(key);
+                if (!byEmail.ok)
+                    return tooMany(byEmail.retryAfter);
+                if (refusePassword !== null && await refusePassword(password))
+                    return json(400, { reasons: [notAllowed()] });
+                // The application's rule, asked of a sign-up only: a known email is a sign-in and there
+                // is no door to close. After the password rule, so a refused password spends no invite.
+                if (refuseSignUp !== null && await findUser(store, key) === undefined) {
+                    const extra = Object.fromEntries(Object.entries(body ?? {}).filter(([name]) => name !== 'email' && name !== 'password'));
+                    const refusal = await refuseSignUp({ email: key, extra, context, store });
+                    if (refusal !== undefined)
+                        return json(403, { reasons: [refusal] });
+                }
+                if (hashing >= hashesInFlight) {
+                    return json(503, { reasons: [{ code: 'busy', message: 'too many sign-ins are being checked; try again in a moment' }] }, { 'retry-after': '1' });
+                }
+                hashing += 1;
+                let outcome;
+                try {
+                    outcome = await enter(email, password);
+                }
+                finally {
+                    hashing -= 1;
+                }
+                if ('refused' in outcome)
+                    return json(401, { reasons: outcome.refused });
+                perEmail.clear(key);
+                const token = await Session.issue(outcome.user);
+                return json(outcome.created ? 201 : 200, { user: outcome.user, created: outcome.created }, {
+                    'set-cookie': Session.setCookie(token, request),
+                });
+            },
+        },
+    };
+};

package/dist/modules/Gate.d.ts

@@ -0,0 +1,6 @@
+import type { ModuleProps } from '@aweftjs/modules';
+import type { Gate as ServerGate } from '@aweftjs/server';
+import { type AuthContext } from '../context.ts';
+export declare const deps: string[];
+declare const _default: ({ imports }: ModuleProps) => ServerGate<AuthContext>;
+export default _default;

package/dist/modules/Gate.js

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

package/dist/modules/Password.d.ts

@@ -0,0 +1,34 @@
+import type { ModuleProps } from '@aweftjs/modules';
+import { type Refusal } from '@aweftjs/server';
+import { type AuthContext } from '../context.ts';
+import { type Outcome } from '../mail.ts';
+export declare const deps: string[];
+export declare const defaults: {
+    subject: string;
+    url: null;
+    resetMs: number;
+    attemptsPerUser: number;
+    attemptsWindowMs: number;
+    forgotPerEmail: number;
+    forgotPerAddress: number;
+    forgotWindowMs: number;
+    sweepMs: number;
+};
+export type Reset = {
+    readonly user: string;
+} | {
+    readonly refused: readonly Refusal[];
+};
+export interface Password {
+    readonly public: true;
+    /** Set a new password for a person who gave the current one. Every other session of theirs is ended. */
+    change(user: string, current: unknown, password: unknown, keep?: string): Promise<Outcome>;
+    /** Mail the person with this address a link, or nothing for an address nobody has; `ok` either way. */
+    forgot(email: string): Promise<Outcome>;
+    /** Take a link and set the password. Every session of the person is ended. Refuses `taken` for a link already used and `token` for one that never was or is past its end. */
+    reset(token: unknown, password: unknown): Promise<Reset>;
+    stop(): void;
+    readonly routes: Record<string, (request: Request, context: AuthContext) => Promise<Response>>;
+}
+declare const _default: ({ imports, config, ...props }: ModuleProps) => Password;
+export default _default;

package/dist/modules/Password.js

@@ -0,0 +1,138 @@
+// auth/Password: change with the current password, forgot by mail, reset by the link (design 290).
+import { atomic } from '@aweftjs/core';
+import { sliding } from '@aweftjs/server';
+import { addressOf, userOf } from "../context.js";
+import { NOT_LIVE, TAKEN, links } from "../links.js";
+import { mailLink, textOf, urlOf } from "../mail.js";
+import { hashPassword, verifyPassword } from "../password.js";
+import { bodyOf, json, numberOf, storeOf } from "../props.js";
+import { findUser, idOfUserDoc, looksLikeEmail, normalEmail, userDoc } from "../users.js";
+export const deps = ['auth/Session', 'auth/Enter', 'notify/Send'];
+export const defaults = {
+    subject: 'Reset your password',
+    url: null,
+    resetMs: 3_600_000,
+    attemptsPerUser: 5,
+    attemptsWindowMs: 900_000,
+    forgotPerEmail: 5,
+    forgotPerAddress: 20,
+    forgotWindowMs: 86_400_000,
+    sweepMs: 3_600_000,
+};
+const MODULE = 'auth/Password';
+const WRONG = { code: 'password', message: 'the current password is wrong' };
+export default ({ imports, config, ...props }) => {
+    const store = storeOf(props);
+    const Session = imports.Session;
+    const Enter = imports.Enter;
+    const mailer = imports.Send;
+    const subject = textOf(MODULE, config, 'subject');
+    const url = urlOf(MODULE, config);
+    const attempts = sliding({ count: numberOf(MODULE, config, 'attemptsPerUser'), windowMs: numberOf(MODULE, config, 'attemptsWindowMs') });
+    const forgotWindowMs = numberOf(MODULE, config, 'forgotWindowMs');
+    const perEmail = sliding({ count: numberOf(MODULE, config, 'forgotPerEmail'), windowMs: forgotWindowMs });
+    const perAddress = sliding({ count: numberOf(MODULE, config, 'forgotPerAddress'), windowMs: forgotWindowMs });
+    const held = links(store, 'reset', numberOf(MODULE, config, 'resetMs'), numberOf(MODULE, config, 'sweepMs'));
+    const rewrite = async (user, password) => {
+        const hash = await hashPassword(password);
+        const handle = await store.open(userDoc(user));
+        atomic(() => {
+            const root = handle.root;
+            root.password = hash;
+            root.modifiedAt = Date.now();
+        });
+        await store.settled(handle);
+        await store.close(handle);
+    };
+    const change = async (user, current, password, keep) => {
+        if (await store.head(userDoc(user)) === 0)
+            return { refused: [WRONG] };
+        const handle = await store.open(userDoc(user));
+        const ok = typeof current === 'string' && await verifyPassword(current, handle.root.password);
+        await store.close(handle);
+        if (!ok)
+            return { refused: [WRONG] };
+        const refused = await Enter.checkPassword(password);
+        if (refused.length > 0)
+            return { refused };
+        await rewrite(user, password);
+        await Session.revokeAll(user, keep);
+        return { ok: true };
+    };
+    const forgot = async (email) => {
+        const found = await findUser(store, email);
+        if (found === undefined)
+            return { ok: true };
+        const user = idOfUserDoc(found);
+        const token = await held.issue(user);
+        const failed = await mailLink(mailer, user, subject, 'Set a new password by opening this link:', url(token));
+        return failed === undefined ? { ok: true } : { refused: [failed] };
+    };
+    // The link is looked at before the password is checked, so a stranger's guess at a token
+    // costs no `refusePassword` lookup, and taken after, so a refused password burns no link.
+    const reset = async (token, password) => {
+        const seen = await held.peek(token);
+        if (seen === undefined || 'taken' in seen)
+            return { refused: [seen === undefined ? NOT_LIVE : TAKEN] };
+        const refused = await Enter.checkPassword(password);
+        if (refused.length > 0)
+            return { refused };
+        const link = await held.take(token);
+        if (link === undefined || 'taken' in link)
+            return { refused: [link === undefined ? NOT_LIVE : TAKEN] };
+        const { user } = link;
+        await rewrite(user, password);
+        await Session.revokeAll(user);
+        return { user };
+    };
+    const tooMany = (retryAfter) => json(429, { reasons: [{ code: 'attempts', message: 'too many attempts; wait and try again' }] }, { 'retry-after': String(retryAfter) });
+    return {
+        public: true,
+        change,
+        forgot,
+        reset,
+        stop: () => { held.stop(); },
+        routes: {
+            'POST /api/password': async (request, context) => {
+                const user = userOf(context);
+                if (user === null)
+                    return json(401, { reasons: [{ code: 'private', message: 'sign in to change your password' }] });
+                // The current password is a password being guessed, so it is counted like a sign-in.
+                const taken = attempts.take(user);
+                if (!taken.ok)
+                    return tooMany(taken.retryAfter);
+                const body = await bodyOf(request);
+                const outcome = await change(user, body?.current, body?.password, context.session ?? undefined);
+                if ('refused' in outcome)
+                    return json(outcome.refused[0] === WRONG ? 401 : 400, { reasons: outcome.refused });
+                attempts.clear(user);
+                return json(200, outcome);
+            },
+            'POST /api/password/forgot': async (request, context) => {
+                const body = await bodyOf(request);
+                const email = body?.email;
+                if (typeof email !== 'string' || !looksLikeEmail(normalEmail(email))) {
+                    return json(400, { reasons: [{ code: 'email', message: 'email is an address' }] });
+                }
+                // Counted before the lookup, because the send is what a stranger must not steer.
+                const byAddress = perAddress.take(addressOf(context) ?? 'unknown');
+                if (!byAddress.ok)
+                    return tooMany(byAddress.retryAfter);
+                const byEmail = perEmail.take(normalEmail(email));
+                if (!byEmail.ok)
+                    return tooMany(byEmail.retryAfter);
+                const outcome = await forgot(email);
+                if ('refused' in outcome)
+                    return json(502, { reasons: outcome.refused });
+                return json(200, outcome);
+            },
+            'POST /api/password/reset': async (request) => {
+                const body = await bodyOf(request);
+                const outcome = await reset(body?.token, body?.password);
+                if ('refused' in outcome)
+                    return json(400, { reasons: outcome.refused });
+                return json(200, outcome);
+            },
+        },
+    };
+};

package/dist/modules/Roles.d.ts

@@ -0,0 +1,32 @@
+import type { ModuleProps } from '@aweftjs/modules';
+import type { Connection } from '@aweftjs/server';
+import { type AuthContext } from '../context.ts';
+import { type Implies } from '../names.ts';
+export declare const defaults: {
+    implies: {};
+    first: never[];
+};
+/** What a `roles:<user>` document holds. */
+export interface RolesDocument extends Record<string, unknown> {
+    names: string[];
+    modifiedAt: number;
+}
+export interface Roles {
+    /** Does the person hold the name: granted, covered by a granted name, or implied by one. Reads the store. False for text that is not a name, since nobody holds one. */
+    may(user: string, name: string): Promise<boolean>;
+    /** Give the person these names. A name already held is left as it is. */
+    grant(user: string, ...names: string[]): Promise<void>;
+    /** Take these names away. A name not held is nothing. */
+    revoke(user: string, ...names: string[]): Promise<void>;
+    /** What the person was granted, and nothing implied. */
+    names(user: string): Promise<string[]>;
+    /** Grant the configured `first` names when nobody signed up before this person. True when they were the first. */
+    first(user: string): Promise<boolean>;
+    /** The table, for a page that runs the same check. */
+    call(args: unknown, context: unknown): {
+        implies: Implies;
+    };
+    connection(connection: Connection<AuthContext>): Promise<() => Promise<void>>;
+}
+declare const _default: ({ config, ...props }: ModuleProps) => Promise<Roles>;
+export default _default;

package/dist/modules/Roles.js

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

package/dist/modules/Session.d.ts

@@ -0,0 +1,39 @@
+import type { ModuleProps } from '@aweftjs/modules';
+import type { Identified, Peer } from '@aweftjs/server';
+import { type AuthContext } from '../context.ts';
+export declare const defaults: {
+    cookie: string;
+    keep: number;
+    sweepMs: number;
+};
+/** What a `session:<token>` document holds. */
+export interface SessionDocument extends Record<string, unknown> {
+    user: string;
+    /** When it stopped, or stops, being valid: the lifetime's end, the moment of revocation, or null for never. */
+    expires: number | null;
+    status: 'active' | 'revoked';
+    createdAt: number;
+}
+export interface Session {
+    readonly public: true;
+    /** Mint a session for a user. Returns its token, which is the cookie's value. */
+    issue(user: string): Promise<string>;
+    /** End a session. True when it was active. */
+    revoke(token: string): Promise<boolean>;
+    /** End every active session of a user but the one named. Returns how many it ended. */
+    revokeAll(user: string, except?: string): Promise<number>;
+    /** Who a request is, from its cookies, and where it came from. Always a context: this gate refuses nobody at the door. */
+    whoIs(request: Request, peer?: Peer): Promise<Identified<AuthContext>>;
+    /** The `Set-Cookie` value that sets the cookie to a token, or clears it for null. */
+    setCookie(token: string | null, request: Request): string;
+    /** Who the asking connection is. The module is public, so an anonymous one hears `{ user: null }`. */
+    call(args: unknown, context: unknown): {
+        user: string | null;
+    };
+    /** Remove every session that has been over for longer than `keep` days. Returns how many. */
+    sweep(): Promise<number>;
+    stop(): Promise<void>;
+    readonly routes: Record<string, (request: Request, context: AuthContext) => Promise<Response>>;
+}
+declare const _default: ({ config, ...props }: ModuleProps) => Promise<Session>;
+export default _default;