@geekity/cms 0.3.0 → 0.4.0

package/dist/notifications/preferences.d.ts

@@ -0,0 +1,158 @@
+import type { User } from '../admin/accounts.ts';
+/**
+ * Which notices a user wants, as a switchboard rather than a field per notice.
+ *
+ * The point of this module is that adding the next event — a new follower, a
+ * digest of what could not be delivered — is one entry in
+ * {@link NOTIFICATION_EVENTS} and nothing else. The users screen renders a
+ * checkbox per entry, `data/users.json` stores whatever is not the default,
+ * and the feature that sends asks {@link notificationRecipients} who wants it.
+ * Nothing else has to be edited, and nothing anywhere hard-codes the word
+ * "comments".
+ *
+ * Two rules keep a stored preference honest across versions:
+ *
+ * - **A default rather than a value.** An event a user has said nothing about
+ *   is at its default, so a site that upgrades into a new notice gets it
+ *   without anybody visiting the users screen, and turning one off is the only
+ *   thing that has to be written down.
+ * - **An unknown name is not a preference.** A key for an event this version
+ *   has never heard of is dropped on the way in and on the way out, so a file
+ *   written by a newer version does not leave a switch nothing can reach.
+ *
+ * An event may also say that it can be *batched* (TASK-60), which adds a
+ * second question beside the switch: not whether to send it, but how often. The
+ * two are separate on purpose — a user who wants none of a notice turns it off,
+ * and a user who wants it in one message a day is still a recipient. Both
+ * rules above apply to the mode exactly as they do to the switch: the default
+ * is not written down, and a mode this version has never heard of is dropped
+ * and read as the default.
+ */
+/**
+ * How often a notice that can be batched arrives.
+ *
+ * `immediately` is one message per thing that happened, which is what every
+ * notice did before there was a choice. The other two are one message per
+ * window listing everything still waiting, which is what makes a spam wave a
+ * single email rather than fifty.
+ */
+export declare const NOTIFICATION_DELIVERY_MODES: readonly ['immediately', 'hourly', 'daily'];
+/** One of {@link NOTIFICATION_DELIVERY_MODES}. */
+export type NotificationDeliveryMode = (typeof NOTIFICATION_DELIVERY_MODES)[number];
+/**
+ * What a user who has never chosen gets: the behaviour every notice had before
+ * this existed, so upgrading changes nothing for anybody.
+ */
+export declare const DEFAULT_DELIVERY_MODE: NotificationDeliveryMode;
+/**
+ * How long a batched mode waits between messages.
+ *
+ * `immediately` is zero because it never waits: it is here so that the map is
+ * total and nothing has to special-case the mode that does not batch.
+ */
+export declare const DELIVERY_WINDOW_MS: Readonly<Record<NotificationDeliveryMode, number>>;
+/** What the users screen calls each mode. */
+export declare const DELIVERY_MODE_LABELS: Readonly<Record<NotificationDeliveryMode, string>>;
+/** Whether a mode collects things up rather than sending each one. */
+export declare function isBatchedMode(mode: NotificationDeliveryMode): boolean;
+/** One thing a user can be told about. */
+export interface NotificationEvent {
+    /** What it is called in `data/users.json` and in the form. */
+    readonly name: string;
+    /** What the users screen calls it. */
+    readonly label: string;
+    /** The sentence under the label, so a switch says what it will send. */
+    readonly description: string;
+    /** Whether a user who has said nothing gets it. */
+    readonly byDefault: boolean;
+    /**
+     * Whether a user may choose how often it arrives (TASK-60).
+     *
+     * `false` for a notice that is only ever one message about one thing — a
+     * password having been changed, say — where "hourly" would mean nothing. An
+     * event that says `true` gets a delivery mode beside its switch, and
+     * whatever sends it is responsible for honouring one.
+     */
+    readonly batched: boolean;
+}
+/**
+ * Every event, in the order the users screen offers them.
+ *
+ * One line each. TASK-55 ships the first.
+ */
+export declare const NOTIFICATION_EVENTS: readonly NotificationEvent[];
+/** The event of that name, or `undefined` for one nothing here knows. */
+export declare function notificationEvent(name: string): NotificationEvent | undefined;
+/**
+ * Whether this user wants that notice.
+ *
+ * `false` for an event nothing knows about, and for no user at all, so a
+ * caller can hand in whatever it has.
+ */
+export declare function notificationWanted(user: User | undefined, name: string): boolean;
+/**
+ * How often this user wants that notice.
+ *
+ * {@link DEFAULT_DELIVERY_MODE} for an event nothing knows about, for one that
+ * cannot be batched, for no user at all, and for a stored value this version
+ * does not recognise — so a caller can hand in whatever it has and always gets
+ * a mode it can act on.
+ */
+export declare function notificationMode(user: User | undefined, name: string): NotificationDeliveryMode;
+/** That string as a mode, or `undefined` for one this version has never heard of. */
+export declare function deliveryMode(value: unknown): NotificationDeliveryMode | undefined;
+/**
+ * Everybody who should get one message of this kind: a user with an address
+ * who has not turned it off.
+ *
+ * The address is what makes somebody a recipient. A user with none has said,
+ * by leaving the field empty, that the site has nowhere to write.
+ */
+export declare function notificationRecipients(users: readonly User[], name: string): {
+    user: User;
+    email: string;
+}[];
+/**
+ * The stored map with one switch moved, or `undefined` when nothing needs
+ * storing any more.
+ *
+ * A preference that matches its default is removed rather than written as
+ * `true`, so the file says only what somebody actually changed and the default
+ * stays the thing this module decides.
+ */
+export declare function withNotification(stored: Readonly<Record<string, boolean>> | undefined, name: string, on: boolean): Record<string, boolean> | undefined;
+/**
+ * The stored mode map with one event moved, or `undefined` when nothing needs
+ * storing any more.
+ *
+ * The twin of {@link withNotification}, and it drops for the same three
+ * reasons: a mode that matches the default, a mode this version does not know,
+ * and an event that cannot be batched are all things the file should not be
+ * carrying. The last two are how a value written by hand, or by a newer
+ * version, is cleaned up rather than left to sit there meaning nothing.
+ */
+export declare function withNotificationMode(stored: Readonly<Record<string, string>> | undefined, name: string, mode: string): Record<string, string> | undefined;
+/** One event as the users screen renders it: the switch, and the mode when it has one. */
+export interface NotificationSwitch {
+    /** The event's name, which is what the form submits. */
+    name: string;
+    /** What the screen calls it. */
+    label: string;
+    /** The sentence that says what it will send. */
+    description: string;
+    /** Whether this user gets it. */
+    on: boolean;
+    /** Whether it offers a delivery mode at all. */
+    batched: boolean;
+    /** How often this user gets it. {@link DEFAULT_DELIVERY_MODE} when it does not batch. */
+    mode: NotificationDeliveryMode;
+    /** The modes to offer, which is nothing at all for an event that cannot batch. */
+    modes: {
+        value: NotificationDeliveryMode;
+        label: string;
+        chosen: boolean;
+    }[];
+}
+/** Every event with what this user has it set to, for the users screen. */
+export declare function notificationSwitches(user: User): NotificationSwitch[];
+//# sourceMappingURL=preferences.d.ts.map

package/dist/notifications/preferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preferences.d.ts","sourceRoot":"","sources":["../../src/notifications/preferences.ts"],"names":[],"mappings":"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"}

package/dist/notifications/preferences.js

@@ -0,0 +1,195 @@
+/**
+ * Which notices a user wants, as a switchboard rather than a field per notice.
+ *
+ * The point of this module is that adding the next event — a new follower, a
+ * digest of what could not be delivered — is one entry in
+ * {@link NOTIFICATION_EVENTS} and nothing else. The users screen renders a
+ * checkbox per entry, `data/users.json` stores whatever is not the default,
+ * and the feature that sends asks {@link notificationRecipients} who wants it.
+ * Nothing else has to be edited, and nothing anywhere hard-codes the word
+ * "comments".
+ *
+ * Two rules keep a stored preference honest across versions:
+ *
+ * - **A default rather than a value.** An event a user has said nothing about
+ *   is at its default, so a site that upgrades into a new notice gets it
+ *   without anybody visiting the users screen, and turning one off is the only
+ *   thing that has to be written down.
+ * - **An unknown name is not a preference.** A key for an event this version
+ *   has never heard of is dropped on the way in and on the way out, so a file
+ *   written by a newer version does not leave a switch nothing can reach.
+ *
+ * An event may also say that it can be *batched* (TASK-60), which adds a
+ * second question beside the switch: not whether to send it, but how often. The
+ * two are separate on purpose — a user who wants none of a notice turns it off,
+ * and a user who wants it in one message a day is still a recipient. Both
+ * rules above apply to the mode exactly as they do to the switch: the default
+ * is not written down, and a mode this version has never heard of is dropped
+ * and read as the default.
+ */
+/**
+ * How often a notice that can be batched arrives.
+ *
+ * `immediately` is one message per thing that happened, which is what every
+ * notice did before there was a choice. The other two are one message per
+ * window listing everything still waiting, which is what makes a spam wave a
+ * single email rather than fifty.
+ */
+export const NOTIFICATION_DELIVERY_MODES = ['immediately', 'hourly', 'daily'];
+/**
+ * What a user who has never chosen gets: the behaviour every notice had before
+ * this existed, so upgrading changes nothing for anybody.
+ */
+export const DEFAULT_DELIVERY_MODE = 'immediately';
+/**
+ * How long a batched mode waits between messages.
+ *
+ * `immediately` is zero because it never waits: it is here so that the map is
+ * total and nothing has to special-case the mode that does not batch.
+ */
+export const DELIVERY_WINDOW_MS = {
+    immediately: 0,
+    hourly: 60 * 60 * 1000,
+    daily: 24 * 60 * 60 * 1000,
+};
+/** What the users screen calls each mode. */
+export const DELIVERY_MODE_LABELS = {
+    immediately: 'As they arrive',
+    hourly: 'Hourly digest',
+    daily: 'Daily digest',
+};
+/** Whether a mode collects things up rather than sending each one. */
+export function isBatchedMode(mode) {
+    return DELIVERY_WINDOW_MS[mode] > 0;
+}
+/**
+ * Every event, in the order the users screen offers them.
+ *
+ * One line each. TASK-55 ships the first.
+ */
+export const NOTIFICATION_EVENTS = [
+    {
+        name: 'comments',
+        label: 'New comments',
+        description: 'A comment or a webmention has arrived and is waiting to be approved. The message carries ' +
+            'approve, spam and delete links that work without signing in.',
+        byDefault: true,
+        batched: true,
+    },
+];
+/** The event of that name, or `undefined` for one nothing here knows. */
+export function notificationEvent(name) {
+    return NOTIFICATION_EVENTS.find((event) => event.name === name);
+}
+/**
+ * Whether this user wants that notice.
+ *
+ * `false` for an event nothing knows about, and for no user at all, so a
+ * caller can hand in whatever it has.
+ */
+export function notificationWanted(user, name) {
+    const event = notificationEvent(name);
+    if (user === undefined || event === undefined)
+        return false;
+    const stored = user.notifications?.[name];
+    return stored ?? event.byDefault;
+}
+/**
+ * How often this user wants that notice.
+ *
+ * {@link DEFAULT_DELIVERY_MODE} for an event nothing knows about, for one that
+ * cannot be batched, for no user at all, and for a stored value this version
+ * does not recognise — so a caller can hand in whatever it has and always gets
+ * a mode it can act on.
+ */
+export function notificationMode(user, name) {
+    const event = notificationEvent(name);
+    if (user === undefined || event === undefined || !event.batched)
+        return DEFAULT_DELIVERY_MODE;
+    return deliveryMode(user.notificationModes?.[name]) ?? DEFAULT_DELIVERY_MODE;
+}
+/** That string as a mode, or `undefined` for one this version has never heard of. */
+export function deliveryMode(value) {
+    return NOTIFICATION_DELIVERY_MODES.find((mode) => mode === value);
+}
+/**
+ * Everybody who should get one message of this kind: a user with an address
+ * who has not turned it off.
+ *
+ * The address is what makes somebody a recipient. A user with none has said,
+ * by leaving the field empty, that the site has nowhere to write.
+ */
+export function notificationRecipients(users, name) {
+    const wanted = [];
+    for (const user of users) {
+        if (user.email === undefined || user.email === '')
+            continue;
+        if (!notificationWanted(user, name))
+            continue;
+        wanted.push({ user, email: user.email });
+    }
+    return wanted;
+}
+/**
+ * The stored map with one switch moved, or `undefined` when nothing needs
+ * storing any more.
+ *
+ * A preference that matches its default is removed rather than written as
+ * `true`, so the file says only what somebody actually changed and the default
+ * stays the thing this module decides.
+ */
+export function withNotification(stored, name, on) {
+    const event = notificationEvent(name);
+    if (event === undefined)
+        return stored === undefined ? undefined : { ...stored };
+    const next = { ...stored };
+    if (on === event.byDefault)
+        delete next[name];
+    else
+        next[name] = on;
+    return Object.keys(next).length === 0 ? undefined : next;
+}
+/**
+ * The stored mode map with one event moved, or `undefined` when nothing needs
+ * storing any more.
+ *
+ * The twin of {@link withNotification}, and it drops for the same three
+ * reasons: a mode that matches the default, a mode this version does not know,
+ * and an event that cannot be batched are all things the file should not be
+ * carrying. The last two are how a value written by hand, or by a newer
+ * version, is cleaned up rather than left to sit there meaning nothing.
+ */
+export function withNotificationMode(stored, name, mode) {
+    const event = notificationEvent(name);
+    const wanted = deliveryMode(mode);
+    if (event === undefined || !event.batched)
+        return stored === undefined ? undefined : { ...stored };
+    const next = { ...stored };
+    if (wanted === undefined || wanted === DEFAULT_DELIVERY_MODE)
+        delete next[name];
+    else
+        next[name] = wanted;
+    return Object.keys(next).length === 0 ? undefined : next;
+}
+/** Every event with what this user has it set to, for the users screen. */
+export function notificationSwitches(user) {
+    return NOTIFICATION_EVENTS.map((event) => {
+        const mode = notificationMode(user, event.name);
+        return {
+            name: event.name,
+            label: event.label,
+            description: event.description,
+            on: notificationWanted(user, event.name),
+            batched: event.batched,
+            mode,
+            modes: event.batched
+                ? NOTIFICATION_DELIVERY_MODES.map((candidate) => ({
+                    value: candidate,
+                    label: DELIVERY_MODE_LABELS[candidate],
+                    chosen: candidate === mode,
+                }))
+                : [],
+        };
+    });
+}
+//# sourceMappingURL=preferences.js.map

package/dist/notifications/preferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preferences.js","sourceRoot":"","sources":["../../src/notifications/preferences.ts"],"names":[],"mappings":"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"}

package/dist/notifications/routes.d.ts

@@ -0,0 +1,28 @@
+import type { Hono } from 'hono';
+import type { GeekityEnv } from '../env.ts';
+/**
+ * Where the links in a notification land.
+ *
+ * Two endpoints under `/_geekity/`, and neither has a session behind it: the
+ * token in the URL is the whole of the authority, which is the point — a
+ * moderator reading mail on a phone should not have to sign in to approve a
+ * comment, and somebody unsubscribing has no account to sign in to.
+ *
+ * **Opening a link does nothing.** Every link lands on a page with a button on
+ * it, and only pressing the button acts. That is not politeness: mail readers,
+ * spam filters and link-safety scanners fetch the URLs in a message as a
+ * matter of course, and a GET that moderated would mean a corporate mail
+ * gateway silently deleting this site's comments. The button posts the same
+ * token back, and there is no CSRF field on it because there is no session to
+ * confuse — anybody who could make a browser post this form already has the
+ * token, which is everything.
+ *
+ * **A moderation link works once.** The token's signature is checked, and then
+ * it is spent against the cache before anything is written, so a link forwarded
+ * to somebody else is a link that has already been used. An unsubscribe link is
+ * deliberately not spent: clicking it a second time should say "you are
+ * unsubscribed", not "that link is dead".
+ */
+/** Register both landing pages. Mounted by the public site. */
+export declare function mountNotificationLinks(app: Hono<GeekityEnv>): void;
+//# sourceMappingURL=routes.d.ts.map

package/dist/notifications/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/notifications/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAI1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAU5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,+DAA+D;AAC/D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAMlE"}

package/dist/notifications/routes.js

@@ -0,0 +1,184 @@
+import { isModerationAction, moderateComment } from '../comments/moderate.js';
+import { MODERATE_PATH, NOTIFICATION_FIELDS, UNSUBSCRIBE_ACTION, UNSUBSCRIBE_PATH, } from './links.js';
+import { addCommentOptOut, hasOptedOut } from './optouts.js';
+import { notificationTokenExpiry, readNotificationToken } from './tokens.js';
+/**
+ * Where the links in a notification land.
+ *
+ * Two endpoints under `/_geekity/`, and neither has a session behind it: the
+ * token in the URL is the whole of the authority, which is the point — a
+ * moderator reading mail on a phone should not have to sign in to approve a
+ * comment, and somebody unsubscribing has no account to sign in to.
+ *
+ * **Opening a link does nothing.** Every link lands on a page with a button on
+ * it, and only pressing the button acts. That is not politeness: mail readers,
+ * spam filters and link-safety scanners fetch the URLs in a message as a
+ * matter of course, and a GET that moderated would mean a corporate mail
+ * gateway silently deleting this site's comments. The button posts the same
+ * token back, and there is no CSRF field on it because there is no session to
+ * confuse — anybody who could make a browser post this form already has the
+ * token, which is everything.
+ *
+ * **A moderation link works once.** The token's signature is checked, and then
+ * it is spent against the cache before anything is written, so a link forwarded
+ * to somebody else is a link that has already been used. An unsubscribe link is
+ * deliberately not spent: clicking it a second time should say "you are
+ * unsubscribed", not "that link is dead".
+ */
+/** Register both landing pages. Mounted by the public site. */
+export function mountNotificationLinks(app) {
+    app.get(MODERATE_PATH, async (c) => await moderationLanding(c, false));
+    app.post(MODERATE_PATH, async (c) => await moderationLanding(c, true));
+    app.get(UNSUBSCRIBE_PATH, async (c) => await unsubscribeLanding(c, false));
+    app.post(UNSUBSCRIBE_PATH, async (c) => await unsubscribeLanding(c, true));
+}
+/** The moderation link: the confirm page, and the thing it confirms. */
+async function moderationLanding(c, act) {
+    const { config, admin } = c.var;
+    const submitted = act ? await c.req.parseBody() : {};
+    const token = act ? field(submitted[NOTIFICATION_FIELDS.token]) : (c.req.query('token') ?? '');
+    const named = act ? field(submitted[NOTIFICATION_FIELDS.action]) : (c.req.query('action') ?? '');
+    const claim = readNotificationToken(config.dataDir, token, config.now());
+    // The named action has to be the signed one. It is in the query so a person
+    // can read what a link does; if the two disagree, the link has been edited.
+    if (claim === undefined || claim.action !== named || !isModerationAction(claim.action)) {
+        return refuse(c, 'This link is no longer valid. Sign in to the Comments screen instead.');
+    }
+    const action = claim.action;
+    const comment = admin.getComment(claim.subject);
+    if (!act) {
+        if (comment === undefined)
+            return done(c, 'That comment is not here any more.');
+        return confirm(c, {
+            action,
+            token,
+            heading: `${verb(action)} this comment?`,
+            author: comment.author.name,
+            html: comment.content.html,
+            button: verb(action),
+        });
+    }
+    // Spent before anything is written, so two clicks cannot both act, and a
+    // forwarded link is a link that has already been used.
+    const expiry = notificationTokenExpiry(config.dataDir, token);
+    if (expiry === undefined || !admin.spendToken(token, expiry, config.now())) {
+        return done(c, 'That link has already been used. Sign in to the Comments screen instead.');
+    }
+    // A good moment to sweep: this is the one handler that writes such a row.
+    admin.pruneSpentTokens(config.now());
+    const outcome = await moderateComment({
+        records: { admin, contentDir: config.contentDir },
+        id: claim.subject,
+        action,
+        checker: config.commentChecker,
+        baseUrl: config.baseUrl,
+    });
+    if (outcome.kind === 'gone')
+        return done(c, 'That comment is not here any more.');
+    if (outcome.kind === 'unchanged') {
+        return done(c, `${outcome.comment.author.name}’s comment was already ${was(action)}.`);
+    }
+    // A newly approved reply is what somebody upthread asked to hear about.
+    if (outcome.kind === 'moved' && outcome.comment.status === 'approved') {
+        c.var.notifications.replyApproved(outcome.comment);
+    }
+    return done(c, `${outcome.comment.author.name}’s comment has been ${was(action)}.`);
+}
+/** The unsubscribe link: the confirm page, and the thing it confirms. */
+async function unsubscribeLanding(c, act) {
+    const { config } = c.var;
+    const submitted = act ? await c.req.parseBody() : {};
+    const token = act ? field(submitted[NOTIFICATION_FIELDS.token]) : (c.req.query('token') ?? '');
+    const claim = readNotificationToken(config.dataDir, token, config.now());
+    if (claim === undefined || claim.action !== UNSUBSCRIBE_ACTION) {
+        return refuse(c, 'This link is no longer valid.');
+    }
+    if (!act) {
+        if (hasOptedOut(config.dataDir, claim.subject)) {
+            return done(c, `${claim.subject} is not being emailed about replies.`);
+        }
+        return confirm(c, {
+            action: UNSUBSCRIBE_ACTION,
+            token,
+            heading: 'Stop emailing you about replies?',
+            author: claim.subject,
+            html: `<p>Nothing more will be sent to ${escapeHtml(claim.subject)} about replies to comments on this site. Your comments stay where they are.</p>`,
+            button: 'Unsubscribe',
+        });
+    }
+    await addCommentOptOut(config.dataDir, claim.subject);
+    return done(c, `${claim.subject} will not be emailed about replies again.`);
+}
+/** The verb a button and a heading use for one action. */
+function verb(action) {
+    return action === 'approve' ? 'Approve' : action === 'spam' ? 'Mark as spam' : 'Delete';
+}
+/** What that action left behind, as a sentence says it. */
+function was(action) {
+    return action === 'approve' ? 'approved' : action === 'spam' ? 'filed as spam' : 'deleted';
+}
+/** The page a link lands on: what it would do, and a button that does it. */
+function confirm(c, options) {
+    return c.html(page(options.heading, `<h1>${escapeHtml(options.heading)}</h1>
+      <p class="who">${escapeHtml(options.author)}</p>
+      <blockquote>${options.html}</blockquote>
+      <form method="post">
+        <input type="hidden" name="${NOTIFICATION_FIELDS.action}" value="${escapeHtml(options.action)}" />
+        <input type="hidden" name="${NOTIFICATION_FIELDS.token}" value="${escapeHtml(options.token)}" />
+        <button type="submit">${escapeHtml(options.button)}</button>
+      </form>`));
+}
+/** The page a finished action leaves behind. */
+function done(c, message) {
+    return c.html(page(message, `<h1>${escapeHtml(message)}</h1>`));
+}
+/** The page a link that buys nothing lands on. */
+function refuse(c, message) {
+    c.status(400);
+    return c.html(page(message, `<h1>${escapeHtml(message)}</h1>`));
+}
+/**
+ * One whole HTML document, built here rather than through the theme.
+ *
+ * These two pages are the CMS's own, like the health check: they are reached
+ * from an email by somebody who may never have seen the site, they have to
+ * work on a theme that has been half rewritten, and there is nothing about
+ * them a theme would want to say. Deliberately one file, no assets and no
+ * script, so nothing about them can fail to load.
+ */
+function page(title, body) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex, nofollow" />
+<title>${escapeHtml(title)}</title>
+<style>
+  body { font: 16px/1.5 system-ui, sans-serif; margin: 0; padding: 2rem 1rem; max-width: 40rem; }
+  h1 { font-size: 1.3rem; }
+  .who { color: #555; margin: 0 0 .5rem; }
+  blockquote { border-left: 3px solid #ccc; margin: 0 0 1.5rem; padding: 0 0 0 1rem; }
+  button { font: inherit; padding: .5rem 1rem; }
+</style>
+</head>
+<body>
+${body}
+</body>
+</html>
+`;
+}
+/** Text as it may safely be printed into the page. */
+function escapeHtml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+/** A form field as a string. A file upload, or a missing field, is the empty one. */
+function field(value) {
+    return typeof value === 'string' ? value : '';
+}
+//# sourceMappingURL=routes.js.map

package/dist/notifications/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../src/notifications/routes.ts"],"names":[],"mappings":"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"}

package/dist/notifications/tokens.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The thing that makes a link in an email work without a login.
+ *
+ * A notification is only worth sending if acting on it is one click. That
+ * means the link itself has to carry the authority, and the two ways of doing
+ * that are a random string written down somewhere and a signed claim that
+ * needs nothing written down. This is the second, for one reason: a link lives
+ * in an inbox for a week, and `data/geekity.db` is a cache that a site may
+ * legitimately delete, rebuild or restore from a backup at any moment
+ * (decision-9). A stack of rows would take every link in flight with it.
+ *
+ * So the token says what it is for — approve *this* comment, unsubscribe
+ * *this* address — and carries an HMAC over exactly that, taken with a secret
+ * in `data/notification-secret`. Nothing but the secret is needed to check
+ * one, the claim cannot be edited without breaking the signature, and a token
+ * signed by one site means nothing to another.
+ *
+ * What is *not* in the token is the right to be used twice. That is a row in
+ * the cache (`spent_tokens`), and it is deliberately the half that a lost
+ * database forgets: forgetting that a link was spent re-enables an action that
+ * has already happened and is idempotent — approving an approved comment, or
+ * deleting one that is gone — whereas forgetting the secret would break every
+ * link a site had sent.
+ */
+/** Where the signing secret lives, under `dataDir`. */
+export declare const NOTIFICATION_SECRET_FILE = "notification-secret";
+/** What a link is allowed to do, once its signature checks out. */
+export interface NotificationClaim {
+    /** Which one-click action this link performs. */
+    action: string;
+    /**
+     * What it acts on: a comment's id for the moderation links, an email address
+     * for an unsubscribe.
+     */
+    subject: string;
+}
+/** A claim on its way into a link, with how long the link should last. */
+export interface NewNotificationToken extends NotificationClaim {
+    /** How long it works for, in seconds. */
+    lifetimeSeconds: number;
+}
+/** Mint a signed link token. It is the whole of what the link carries. */
+export declare function signNotificationToken(dataDir: string, claim: NewNotificationToken, now?: Date): string;
+/**
+ * What a token entitles its holder to, or `undefined` when it entitles them to
+ * nothing: not a token at all, edited, signed by somebody else, or expired.
+ *
+ * The signature is checked before the payload is believed, so nothing here
+ * ever acts on bytes a stranger chose.
+ */
+export declare function readNotificationToken(dataDir: string, token: string, now?: Date): NotificationClaim | undefined;
+/**
+ * When a token stops working, as an ISO 8601 instant, or `undefined` when it
+ * never worked.
+ *
+ * What the spent-token row is pruned by: a ledger of links that can never be
+ * used again is a ledger that can be thrown away.
+ */
+export declare function notificationTokenExpiry(dataDir: string, token: string): string | undefined;
+//# sourceMappingURL=tokens.d.ts.map