@geekity/cms 0.3.0 → 0.4.0

package/dist/admin/store.d.ts

@@ -3,26 +3,6 @@ export interface OpenAdminStoreOptions {
     /** Directory the database lives in. Created if it is missing. */
     dataDir: string;
 }
-/** An admin user. There is one role, so there is no role column. */
-export interface User {
-    /** Row id, stable for the life of the user. */
-    readonly id: number;
-    /** Login name, unique and compared case sensitively. */
-    readonly username: string;
-    /** When the user was created, as an ISO 8601 instant. */
-    readonly createdAt: string;
-}
-/** A user with the column no screen may render: its password hash. */
-export interface StoredUser extends User {
-    /** The PHC-encoded argon2id hash. */
-    readonly passwordHash: string;
-}
-/** What {@link AdminStore.createUser} is given. */
-export interface CreateUserInput {
-    username: string;
-    /** The plain password. It is hashed on the way in and never stored. */
-    password: string;
-}
 /**
  * A login, or the anonymous session that carries a CSRF token to a visitor who
  * has not logged in yet.
@@ -70,45 +50,59 @@ export interface CreateSessionInput {
 /** How long a session id is, in bytes. 32 is the 256 bits doc-5 asks for. */
 export declare const SESSION_ID_BYTES = 32;
 /**
- * The two signature algorithms doc-4 asks a site actor to hold.
+ * One outstanding password reset: the right to set one user's password once,
+ * until it is used or it expires.
  *
- * `RSASSA-PKCS1-v1_5` signs HTTP Signatures, which is what Mastodon and most
- * of the fediverse verify; `Ed25519` signs FEP-8b32 object integrity proofs.
- * They are Fedify's own spellings, so a row round-trips into
- * `generateCryptoKeyPair` without translation.
+ * The token is only ever in hand at the moment it is made, because the link is
+ * the only copy: the database keeps its SHA-256, so reading the table tells
+ * somebody that a reset was asked for and nothing more.
  */
-export declare const ACTOR_KEY_ALGORITHMS: readonly ['RSASSA-PKCS1-v1_5', 'Ed25519'];
-/** One of {@link ACTOR_KEY_ALGORITHMS}. */
-export type ActorKeyAlgorithm = (typeof ACTOR_KEY_ALGORITHMS)[number];
-/** A stored actor key pair, both halves as serialized JWK. */
-export interface ActorKey {
-    /**
-     * Which actor the pair belongs to. The site actor's identifier is a
-     * constant, not the handle, so renaming the handle does not orphan the keys.
-     */
-    readonly identifier: string;
-    /** Which algorithm the pair is for. */
-    readonly algorithm: ActorKeyAlgorithm;
-    /** The private key as JWK, JSON encoded. Never leaves the server. */
-    readonly privateJwk: string;
-    /** The public key as JWK, JSON encoded. This is what the actor publishes. */
-    readonly publicJwk: string;
-    /** When the pair was generated, as an ISO 8601 instant. */
+export interface PasswordReset {
+    /** Whose password this sets. */
+    readonly userId: number;
+    /** When it was asked for, as an ISO 8601 instant. */
     readonly createdAt: string;
+    /** When it stops working, as an ISO 8601 instant. */
+    readonly expiresAt: string;
+}
+/** A {@link PasswordReset} with the one thing the database never keeps. */
+export interface IssuedPasswordReset extends PasswordReset {
+    /**
+     * The token itself, 256 random bits hex encoded, handed back exactly once.
+     * It goes in the link and nowhere else.
+     */
+    readonly token: string;
+}
+/** What {@link AdminStore.createPasswordReset} is given. */
+export interface CreatePasswordResetInput {
+    /** Whose password the link will set. */
+    userId: number;
+    /** How long the link lasts, in seconds. */
+    lifetimeSeconds: number;
+    /** The clock, injectable so expiry is testable. Defaults to now. */
+    now?: Date | undefined;
 }
-/** An {@link ActorKey} before the store has stamped it with a creation time. */
-export type NewActorKey = Omit<ActorKey, 'createdAt'>;
 /**
  * A remote actor that follows this site.
  *
- * doc-4 keeps the followers in SQLite rather than in Fedify's KV store,
- * because they are the one thing an ActivityPub site cannot regenerate: an
- * actor that followed and was forgotten never hears from the site again and
- * has no way of noticing. The display columns are a copy of what the actor
- * said about itself when it followed, so the admin can list its followers
- * without dereferencing every one of them.
+ * The followers are irreplaceable — an actor that followed and was forgotten
+ * never hears from the site again and has no way of noticing — so
+ * `content/_data/federation/followers.json` is where they are kept
+ * (decision-9), and this row is the index of that file, emptied and read back
+ * on every boot. The display columns are a copy of what the actor said about
+ * itself when it followed, so the admin can list its followers without
+ * dereferencing every one of them.
  */
 export interface Follower {
+    /**
+     * Which user is followed (decision-14).
+     *
+     * Every user is an actor with followers of their own, so a follower is only
+     * ever a follower *of somebody*: the column is what makes one person's
+     * followers collection, and one person's delivery, theirs. It is the name of
+     * the directory the file came from rather than anything the file says.
+     */
+    readonly username: string;
     /** The follower's ActivityStreams id, which is what identifies it. */
     readonly actorId: string;
     /** Where an activity addressed to this follower is delivered. */
@@ -166,40 +160,48 @@ export interface InboxActivity {
     readonly actorId: string;
     /** What it was about — the post that was liked, the note replied to — or `null`. */
     readonly objectId: string | null;
+    /**
+     * Which of this site's users it was addressed to, or `null` for one
+     * delivered to the shared inbox without naming one.
+     *
+     * decision-14 makes every user an actor, so the log records whose inbox was
+     * told as well as what it was told. Derived from the log line rather than
+     * from the activity, because the addressee is a fact about the delivery.
+     */
+    readonly recipient: string | null;
+    /**
+     * The object this activity answers, for a `Create` that carried an
+     * `inReplyTo`, and `null` for everything else.
+     *
+     * Derived from {@link InboxActivity.json} by {@link replyTargetOf} rather
+     * than supplied, so an index rebuilt from the inbox log holds exactly what
+     * the live one holds. It is a column so a post's replies can be counted
+     * without reading every activity the site was ever sent.
+     */
+    readonly inReplyTo: string | null;
     /** When it arrived, as an ISO 8601 instant. */
     readonly receivedAt: string;
     /** The activity as compacted JSON-LD, exactly as it was received. */
     readonly json: string;
 }
-/** An {@link InboxActivity} before the store has given it a row and a time. */
-export type NewInboxActivity = Omit<InboxActivity, 'id' | 'receivedAt'>;
 /**
- * One activity this site sent, kept whole so it can be sent again.
+ * An {@link InboxActivity} before the store has given it a row and the reply
+ * target it derives.
  *
- * decision-5 accepts that an activity queued when the process exits is lost,
- * on the understanding that the outcome is recorded per follower and that an
- * admin can re-send. Re-sending needs the activity itself, and rebuilding one
- * from the content directory is not always possible — a `Delete` is about a
- * post that is no longer there — so the compacted JSON-LD is stored as it went
- * out.
+ * `receivedAt` is optional and defaults to now, exactly as a follower's
+ * `followedAt` is: naming one is what lets the boot rebuild put the log's own
+ * arrival times back rather than stamping every activity with the moment the
+ * index was rebuilt.
  */
-export interface OutboundActivity {
-    /** The activity's own id, which is what a redelivery is asked for by. */
-    readonly activityId: string;
-    /** `Create`, `Update` or `Delete`. */
-    readonly activityType: string;
-    /** The ActivityStreams id of the post the activity is about. */
-    readonly objectId: string;
-    /** The post's slug when the activity was built, for a human reading the log. */
-    readonly slug: string | null;
-    /** When the activity was first built, as an ISO 8601 instant. */
-    readonly createdAt: string;
-    /** The activity as compacted JSON-LD, exactly as it was delivered. */
-    readonly json: string;
-}
-/** An {@link OutboundActivity} before the store has timed it. */
-export type NewOutboundActivity = Omit<OutboundActivity, 'createdAt'> & {
-    createdAt?: string | undefined;
+export type NewInboxActivity = Omit<InboxActivity, 'id' | 'receivedAt' | 'inReplyTo' | 'recipient'> & {
+    receivedAt?: string | undefined;
+    /**
+     * Who it was addressed to, when the delivery said. Optional and `null` by
+     * default: an activity that reached the shared inbox without naming one of
+     * this site's actors is addressed to nobody in particular, and so is every
+     * line of a log written before decision-14.
+     */
+    recipient?: string | null | undefined;
 };
 /** How one delivery of one activity to one follower ended. */
 export declare const DELIVERY_STATUSES: readonly ['sent', 'queued', 'failed'];
@@ -212,11 +214,37 @@ export declare const DELIVERY_STATUSES: readonly ['sent', 'queued', 'failed'];
  * `failed` is a delivery that threw, with the reason in the row.
  */
 export type DeliveryStatus = (typeof DELIVERY_STATUSES)[number];
-/** How one attempt to deliver one activity to one follower ended. */
+/**
+ * How one attempt to deliver one activity to one recipient ended, and what the
+ * activity was.
+ *
+ * The whole of what SQLite keeps about anything the site has sent (decision-9).
+ * No payload goes with it: an activity is rebuilt from the post's file at the
+ * moment somebody asks for it to go again, so storing the bytes that went out
+ * last time would only be a second, staler answer to the same question. What
+ * is left is a cache of outcomes, and a site that deletes its database loses
+ * nothing but the record of how yesterday's delivery went.
+ *
+ * The activity's own columns are here rather than in a table of their own
+ * because there is no longer anything else to put in one: they are what the
+ * federation screen reads to say what went out and when.
+ */
 export interface Delivery {
-    /** Which activity was delivered. */
+    /** The id of the activity that was delivered. */
     readonly activityId: string;
-    /** Which follower it was delivered to. */
+    /** `Create`, `Update` or `Delete`. */
+    readonly activityType: string;
+    /**
+     * The ActivityStreams id of what it was about: a post, or the site's own
+     * actor when the profile itself was what moved.
+     */
+    readonly objectId: string;
+    /**
+     * The post's slug when the activity went out, or `null` for an activity
+     * about no post — which is what an actor `Update` is.
+     */
+    readonly slug: string | null;
+    /** Which follower or relay it was delivered to. */
     readonly actorId: string;
     /** The inbox actually used, which is the shared one when the follower has one. */
     readonly inboxId: string;
@@ -231,48 +259,237 @@ export interface Delivery {
 export type NewDelivery = Omit<Delivery, 'attemptedAt'> & {
     attemptedAt?: string | undefined;
 };
+/** Where a relay subscription stands (FEP-ae0c). */
+export declare const RELAY_STATES: readonly ['pending', 'accepted', 'rejected'];
 /**
- * The auth half of the SQLite database: the data doc-1 says lives only there.
+ * One of {@link RELAY_STATES}.
  *
- * It is deliberately not part of the {@link ContentStore}. That store is the
- * derived index over the Markdown files and can be deleted and rebuilt at any
- * time; users and sessions are the one thing in the database that cannot. They
- * share the file (one database per site, one set of migrations on boot) and
- * nothing else.
+ * `pending` is a `Follow` that has gone out and not been answered — which may
+ * take days, because a relay is allowed to hold one for a human to approve.
+ * `accepted` is one the relay answered `Accept` to, and the only state the
+ * site delivers to. `rejected` is one it answered `Reject` to, with whatever
+ * it said in {@link Relay.reason}.
  */
-export interface AdminStore {
-    /** Absolute path of the SQLite file, the same one the content index uses. */
-    readonly file: string;
-    /** How many users exist. Zero is what puts the admin into first-run setup. */
-    countUsers(): number;
-    /** Every user, by name, without password hashes. */
-    listUsers(): User[];
-    /** One user with its password hash, or `undefined`. For auth, not for screens. */
-    getUser(username: string): StoredUser | undefined;
-    /** The user behind a session's `userId`, or `undefined`. */
-    getUserById(id: number): User | undefined;
-    /**
-     * Hash the password and insert the user.
+export type RelayState = (typeof RELAY_STATES)[number];
+/**
+ * The site's subscription to one relay.
+ *
+ * The list of relays itself is a setting, and so lives in `site.json`; this is
+ * the state of the handshake with each of them, which is operational rather
+ * than editorial. Keyed by the inbox because that is the only thing known when the
+ * `Follow` goes out: a relay's actor id is not learned until it answers.
+ */
+export interface Relay {
+    /** The relay's inbox, which is what the site was given and what it delivers to. */
+    readonly inboxId: string;
+    /** The relay actor's id, once it has answered, and `null` until then. */
+    readonly actorId: string | null;
+    /** Where the subscription stands. */
+    readonly state: RelayState;
+    /** Why a `Reject` was a reject, when it gave a reason, or `null`. */
+    readonly reason: string | null;
+    /** The id of the `Follow` that was sent, which an `Accept` names. */
+    readonly followId: string | null;
+    /** When the site first subscribed, as an ISO 8601 instant. */
+    readonly createdAt: string;
+    /** When the subscription last moved — accepted, rejected, re-followed. */
+    readonly updatedAt: string;
+}
+/** A {@link Relay} before the store has timed it. */
+export type NewRelay = Omit<Relay, 'createdAt' | 'updatedAt'> & {
+    createdAt?: string | undefined;
+};
+/** How one webmention this site sent to one page ended. */
+export declare const WEBMENTION_SEND_STATUSES: readonly ['sent', 'none', 'failed'];
+/**
+ * One of {@link WEBMENTION_SEND_STATUSES}.
+ *
+ * `sent` is an endpoint that accepted the notification. `none` is a page that
+ * advertises no endpoint, which is most of the web and is not a failure —
+ * recording it is what stops the sender asking the same page again on every
+ * edit and what tells a person why nothing went. `failed` is an endpoint that
+ * was there and refused, with the reason in the row.
+ */
+export type WebmentionSendStatus = (typeof WEBMENTION_SEND_STATUSES)[number];
+/**
+ * How one attempt to tell one page that a post links to it ended.
+ *
+ * The whole of what SQLite keeps about the webmentions a site has sent, and a
+ * cache like every other outcome here (decision-9): the links are in the
+ * post's file, so a database thrown away costs the record of how yesterday's
+ * notification went and nothing else. One row per (post, target), because the
+ * question it answers is "where does this post stand with that page" and a
+ * resend moves that answer rather than adding a second one.
+ */
+export interface SentWebmention {
+    /** The post the links were in. */
+    readonly slug: string;
+    /** The post's absolute URL, which is the `source` that was sent. */
+    readonly source: string;
+    /** The page that was linked to, which is the `target` that was sent. */
+    readonly target: string;
+    /** The endpoint it was sent to, or `null` when the target advertised none. */
+    readonly endpoint: string | null;
+    /** How it went. */
+    readonly status: WebmentionSendStatus;
+    /** Why it failed, or `null`. */
+    readonly error: string | null;
+    /** When the attempt was made, as an ISO 8601 instant. */
+    readonly attemptedAt: string;
+}
+/** A {@link SentWebmention} before the store has timed it. */
+export type NewSentWebmention = Omit<SentWebmention, 'attemptedAt'> & {
+    attemptedAt?: string | undefined;
+};
+/** Where a comment came from. */
+export declare const COMMENT_SOURCES: readonly ['comment', 'webmention'];
+/**
+ * One of {@link COMMENT_SOURCES}.
+ *
+ * `comment` is the form under the post. `webmention` is another site's post
+ * pointing at this one (TASK-51), which lands in the same file with the same
+ * shape and is told apart only by this.
+ */
+export type CommentSource = (typeof COMMENT_SOURCES)[number];
+/** What a comment is: something written, or a wordless pointer at the post. */
+export declare const COMMENT_KINDS: readonly ['reply', 'like', 'boost', 'mention', 'repost'];
+/**
+ * One of {@link COMMENT_KINDS}. The same five a conversation knows.
+ *
+ * `reply`, `like` and `boost` are the fediverse's three. `repost` and
+ * `mention` are the webmention vocabulary's two extra: a repost is a boost by
+ * another name and is shown with them, and a mention is the one thing neither
+ * of the others is — somebody's page pointing at this one without answering
+ * it (TASK-51).
+ */
+export type CommentKind = (typeof COMMENT_KINDS)[number];
+/** Where a comment stands with the moderator. */
+export declare const COMMENT_STATUSES: readonly ['pending', 'approved', 'spam'];
+/**
+ * One of {@link COMMENT_STATUSES}.
+ *
+ * `pending` is waiting for somebody to look at it, and is the state almost
+ * every comment starts in; `approved` is on the page and in the feeds; `spam`
+ * is kept rather than deleted, so a checker can be told it was wrong and so a
+ * mistake can be undone.
+ */
+export type CommentStatus = (typeof COMMENT_STATUSES)[number];
+/** Who wrote a comment, as much as the site knows. */
+export interface CommentAuthor {
+    /** The name they gave, which is what the page shows. */
+    name: string;
+    /** Their website, or `null`. Shown, and marked `nofollow ugc` like any link. */
+    url: string | null;
+    /**
+     * Their email, or `null`. **Never shown**: it is here for the moderator, for
+     * the auto-approval rule, and for the spam checker.
+     */
+    email: string | null;
+    /**
+     * Their avatar, or `null`.
      *
-     * Throws {@link DuplicateUsernameError} when the name is taken.
+     * Only a webmention ever has one, out of the `u-photo` of the source page's
+     * `h-card` (TASK-51): a form asks for no picture, and one it did ask for
+     * would be a stranger's file on somebody else's page. It is a URL on the
+     * author's own site, printed as an `<img>` exactly as a fediverse reply's is.
      */
-    createUser(input: CreateUserInput): User;
+    avatar: string | null;
+}
+/** What a comment says, in both the forms the site keeps. */
+export interface CommentContent {
+    /** What was typed, which is what a person wrote and the source of truth. */
+    markdown: string;
+    /** {@link CommentContent.markdown} through the restricted profile. */
+    html: string;
+}
+/**
+ * One comment, as its post's file under `content/_data/comments/` holds it.
+ *
+ * The shape is deliberately wider than a form submission. A webmention
+ * (TASK-51) is somebody else's post pointing at this one: it has a `url` and no
+ * email, it may be a like rather than a reply, and it belongs in the same file
+ * and the same thread. So every entry says its `source` and its `kind`, and
+ * nothing assumes a person filled in a form.
+ */
+export interface CommentRecord {
+    /** Its name, unique across the site, and what a reply puts in `inReplyTo`. */
+    id: string;
+    /** Where it came from. */
+    source: CommentSource;
+    /** What it is. */
+    kind: CommentKind;
+    /** Where it stands with the moderator. */
+    status: CommentStatus;
+    /** Who wrote it. */
+    author: CommentAuthor;
+    /** What it says. */
+    content: CommentContent;
+    /** When it was submitted, as an ISO 8601 instant. */
+    submitted: string;
     /**
-     * The user, when the password is theirs; `undefined` when it is not, or when
-     * there is no such user. The two failures are deliberately indistinguishable.
+     * A salted hash of the address it came from, or `null`.
+     *
+     * The address itself is not kept: the file is published with the site and
+     * goes into git, and an IP address there would be a reader's home written
+     * into a public repository. The hash is enough to see that two comments came
+     * from one place, which is what a moderator is actually asking.
      */
-    verifyPassword(username: string, password: string): User | undefined;
+    addressHash: string | null;
+    /** The comment it answers, or `null` for one answering the post itself. */
+    inReplyTo: string | null;
     /**
-     * Hash a new password and put it on a user, replacing the old one. Returns
-     * `false` when there is no such user. Sessions are left alone; deciding
-     * which of them a password change should end is the caller's business.
+     * Where it lives when it lives somewhere else: the source page of a
+     * webmention, and `null` for a comment written on this site.
+     *
+     * It is what a later webmention from the same page is recognised by, which
+     * is how one updates the comment it made before instead of adding a second,
+     * and it is where the thread's permalink points for an entry this site did
+     * not host.
      */
-    setPassword(userId: number, password: string): boolean;
+    url: string | null;
     /**
-     * Delete a user. Their sessions go with them, because the foreign key
-     * cascades. Returns `false` when there was nothing to delete.
+     * Whether whoever wrote it asked to hear about replies to it (TASK-55).
+     *
+     * Only ever true for a comment that carries an `author.email`, because there
+     * would be nowhere to send it otherwise, and only ever set by somebody
+     * ticking the box on the form — a webmention has nobody to ask. What it buys
+     * is one message when a reply to this comment is approved, carrying an
+     * unsubscribe link that needs no login.
      */
-    deleteUser(userId: number): boolean;
+    notify: boolean;
+}
+/**
+ * A {@link CommentRecord} with the post it is on.
+ *
+ * The file it lives in is named after the post's slug and records the post's
+ * permalink, so both are facts of the file rather than of the entry; the index
+ * carries them on the row because a query by id has no file to read them from.
+ */
+export interface PostComment extends CommentRecord {
+    /** The post's slug, which names the file the comment lives in. */
+    slug: string;
+    /** That post's permalink, for the moderation screen and the feeds. */
+    permalink: string;
+}
+/** How {@link AdminStore.listComments} narrows and pages. */
+export interface ListCommentsOptions extends ListPageOptions {
+    /** Only comments at this status. Every status when it is not given. */
+    status?: CommentStatus | undefined;
+}
+/**
+ * Everything the database holds that is not the content index: the sessions,
+ * the followers and inbox indexes, the delivery outcomes, the relay handshake
+ * and the scheduler's watermark.
+ *
+ * All of it is a cache (decision-9). The followers and the inbox rows are read
+ * back from `content/_data/federation/` on every boot; the rest a site is free
+ * to lose, and the README says what losing it costs. It is deliberately not
+ * part of the {@link ContentStore}: the two share the file, one database per
+ * site with a migration ledger each, and nothing else.
+ */
+export interface AdminStore {
+    /** Absolute path of the SQLite file, the same one the content index uses. */
+    readonly file: string;
     /** Start a session and hand back its id and CSRF token. */
     createSession(input: CreateSessionInput): Session;
     /**
@@ -294,35 +511,102 @@ export interface AdminStore {
         except?: string;
     }): number;
     /**
-     * How many settings are stored. Zero on a site that has never saved the
-     * settings form, which is what decides whether to seed from
-     * `content/_data/site.json`.
+     * Issue a password reset link and hand back its token, which is the only
+     * time the token exists outside the link.
      */
-    countSettings(): number;
+    createPasswordReset(input: CreatePasswordResetInput): IssuedPasswordReset;
     /**
-     * Every stored setting, by key. The store keeps no opinion about what the
-     * keys mean or what they are worth; `readSiteSettings` in `settings.ts` is
-     * what turns them into a typed shape with defaults.
+     * What a token entitles its holder to, or `undefined` when it entitles them
+     * to nothing: no such token, or one that has expired. An expired row is
+     * deleted on the way past, as an expired session's is.
      */
-    allSettings(): Record<string, string>;
+    getPasswordReset(token: string, now?: Date): PasswordReset | undefined;
+    /** Spend a token. Returns `false` when there was nothing to spend. */
+    deletePasswordReset(token: string): boolean;
     /**
-     * Write settings, in one transaction, leaving keys not named alone. An
-     * existing key is replaced.
+     * Cancel every reset a user has outstanding, and say how many went.
+     *
+     * What a finished reset calls: the link that was used is spent, and so is
+     * every other one asked for in the meantime, because whoever set the
+     * password now owns the account and the others are only ways back in for
+     * somebody who does not.
      */
-    setSettings(values: Record<string, string>): void;
+    deletePasswordResetsForUser(userId: number): number;
+    /** Delete every expired reset. Returns how many went. */
+    prunePasswordResets(now?: Date): number;
     /**
-     * Every key pair an actor holds, in {@link ACTOR_KEY_ALGORITHMS} order, so a
-     * caller handing them to Fedify gets HTTP Signatures first whatever order
-     * they were written in. Empty on a site that has not federated yet.
+     * Spend a one-click link's token, and say whether it had anything left.
+     *
+     * `true` the first time and `false` for ever after, which is what makes a
+     * link in an email single use (TASK-55). Only the token's SHA-256 is kept,
+     * as a password reset's is, so a copy of this file is not a list of the
+     * links a site has sent. `expiresAt` is the moment the token's own signature
+     * stops meaning anything, and is only there so the row can be swept.
      */
-    listActorKeys(identifier: string): ActorKey[];
+    spendToken(token: string, expiresAt: string, now?: Date): boolean;
+    /** Delete every spent token that has expired. Returns how many went. */
+    pruneSpentTokens(now?: Date): number;
     /**
-     * Store one key pair, replacing whatever that actor held for the same
-     * algorithm. Rotating a key is therefore a write rather than a migration.
+     * The rows of the settings table an older version of this CMS wrote, or
+     * `undefined` when the table is gone — which it is on every site that has
+     * booted this version once.
+     *
+     * Settings live in `content/_data/site.json` now (decision-9). This is the
+     * one read left of the table they used to live in, so the first boot after
+     * the upgrade can write them out; `migrateSettingsToFile` in `settings.ts`
+     * is what decides what they mean.
      */
-    putActorKey(key: NewActorKey): ActorKey;
-    /** How many actors follow the site. What the followers collection counts. */
-    countFollowers(): number;
+    legacySettings(): LegacySetting[] | undefined;
+    /**
+     * The rows of the actor key table an older version of this CMS wrote, or
+     * `undefined` when the table is gone — which it is on every site that has
+     * booted this version once.
+     *
+     * Key pairs live in `data/keys` now (decision-9). This is the one read left
+     * of the table they used to live in, and the reason it exists at all is that
+     * losing an actor's private key is the one loss a federated site cannot
+     * recover from; `migrateActorKeysToFiles` in `federation/keys.ts` writes them
+     * out before the table is dropped.
+     */
+    legacyActorKeys(): LegacyActorKey[] | undefined;
+    /**
+     * The rows of the users table an older version of this CMS wrote, or
+     * `undefined` when the table is gone — which it is on every site that has
+     * booted this version once.
+     *
+     * Accounts live in `data/users.json` now (decision-9). This is the one read
+     * left of the table they used to live in, so the first boot after the
+     * upgrade can write them out; `migrateUsersToFile` in `accounts.ts` is what
+     * does it, ids and all, so a session that names a user still finds them.
+     */
+    legacyUsers(): LegacyUser[] | undefined;
+    /**
+     * Drop a table whose contents this version keeps in files instead.
+     *
+     * Called once the rows have been written out, and safe when the table is
+     * already gone. It is deliberately not a schema migration: a migration runs
+     * when the database is opened, which is before anything knows where the
+     * content directory is, and dropping the rows before they are written out is
+     * the one mistake this milestone cannot make.
+     */
+    dropLegacyTable(name: string): void;
+    /**
+     * One piece of the CMS's own operational state, or `undefined`.
+     *
+     * Not a setting: nothing here is a site's choice and nothing here belongs in
+     * `content/_data/site.json`, which is where a setting lives. It is a cache
+     * like the rest of the database, and losing it costs a site nothing it
+     * cannot work out again. The scheduler's watermark — how far through the
+     * calendar it has got — lives here.
+     */
+    getState(key: string): string | undefined;
+    /** Write one piece of that state. */
+    setState(key: string, value: string): void;
+    /**
+     * How many actors follow one user, or the whole site when no user is named.
+     * What a user's followers collection counts.
+     */
+    countFollowers(username?: string): number;
     /**
      * Followers, newest follow first, optionally one page of them.
      *
@@ -331,17 +615,26 @@ export interface AdminStore {
      * arrives while somebody is walking the collection shifts the pages under
      * them by one, which is the same trade the outbox makes.
      */
-    listFollowers(options?: ListPageOptions): Follower[];
-    /** One follower by actor id, or `undefined`. */
-    getFollower(actorId: string): Follower | undefined;
+    listFollowers(username?: string, options?: ListPageOptions): Follower[];
+    /** One user's follower by actor id, or `undefined`. */
+    getFollower(username: string, actorId: string): Follower | undefined;
     /**
      * Store a follower, replacing whatever was known about that actor. The
      * original `followedAt` is kept, because a repeat `Follow` from an actor
      * that already follows is a redelivery rather than a new follow.
      */
     putFollower(follower: NewFollower): Follower;
-    /** Forget a follower. Returns `false` when there was nothing to forget. */
-    deleteFollower(actorId: string): boolean;
+    /** Forget one user's follower. Returns `false` when there was nothing to forget. */
+    deleteFollower(username: string, actorId: string): boolean;
+    /**
+     * Make the followers index say exactly this, in one transaction.
+     *
+     * What a rebuild from every `content/_data/federation/{username}/followers.json` calls
+     * (decision-9): the file is the source, so a row it does not carry is a row
+     * that should not be delivered to, and replacing the lot is the only way to
+     * say that. Nothing outside a rebuild should reach for it.
+     */
+    replaceFollowers(followers: readonly NewFollower[]): void;
     /** How many activities the inbound log holds. */
     countInboxActivities(): number;
     /** Logged activities, newest first, optionally one page of them. */
@@ -353,27 +646,140 @@ export interface AdminStore {
      * against.
      */
     logInboxActivity(activity: NewInboxActivity): InboxActivity;
-    /** How many activities this site has sent. */
-    countOutboundActivities(): number;
-    /** Activities this site sent, newest first, optionally one page of them. */
-    listOutboundActivities(options?: ListPageOptions): OutboundActivity[];
-    /** One sent activity by its id, or `undefined`. */
-    getOutboundActivity(activityId: string): OutboundActivity | undefined;
     /**
-     * Record an activity on its way out, leaving the original `created_at` alone
-     * so a redelivery does not pretend the activity is new.
+     * Make the inbound log index say exactly this, in one transaction, with the
+     * row ids starting again from one.
+     *
+     * The counterpart of {@link AdminStore.replaceFollowers} over
+     * `content/_data/federation/inbox/{yyyy}-{mm}.jsonl`. The ids restart
+     * because a row id is the order things arrived in and nothing else: letting
+     * them climb on every boot would give the same log different ids on two
+     * machines holding the same files.
      */
-    putOutboundActivity(activity: NewOutboundActivity): OutboundActivity;
+    replaceInboxActivities(activities: readonly NewInboxActivity[]): void;
+    /** How many logged activities are replies to anything at all. */
+    countReplies(): number;
+    /** Every logged reply, newest first, optionally one page of them. */
+    listReplies(options?: ListPageOptions): InboxActivity[];
+    /** How many replies one object — a post's ActivityStreams id — has. */
+    countRepliesTo(objectId: string): number;
+    /** One object's replies, newest first, optionally one page of them. */
+    listRepliesTo(objectId: string, options?: ListPageOptions): InboxActivity[];
+    /**
+     * Every logged activity that names one of these objects — as what it is
+     * about, or as what it answers — oldest first.
+     *
+     * The query a conversation is built from: the likes and boosts of a post,
+     * the replies to it, and the `Delete` or `Undo` that takes one of those
+     * back, all name an object this side already knows the id of. Both columns
+     * are read because a `Create` is *about* the note it carries and only
+     * `in_reply_to` says which post that note answers.
+     *
+     * Oldest first, because that is the order a thread reads in; a caller
+     * wanting the newest can reverse a page it has. Naming nothing returns
+     * nothing rather than everything.
+     */
+    listActivitiesAbout(objectIds: readonly string[]): InboxActivity[];
+    /** One post's comments, oldest first, whatever status they are at. */
+    listCommentsFor(slug: string): PostComment[];
+    /**
+     * How many of one post's comments stand at one status.
+     *
+     * A count rather than a list because that is what the feeds want: the RSS
+     * `source:comments` element carries a number per item, and reading every
+     * comment on every post of a feed page to arrive at it would be a page of
+     * text for a page of integers.
+     */
+    countCommentsFor(slug: string, status: CommentStatus): number;
+    /**
+     * Comments across the site, newest first, optionally of one status and one
+     * page of them. What the moderation screen and the site-wide feed read.
+     */
+    listComments(options: ListCommentsOptions): PostComment[];
+    /** One comment by id, or `undefined`. */
+    getComment(id: string): PostComment | undefined;
+    /** How many comments stand at each status. What the dashboard shows. */
+    countCommentsByStatus(): Record<CommentStatus, number>;
+    /**
+     * Whether this name and email have had a comment approved before.
+     *
+     * WordPress's rule, and the whole of the auto-approval decision: somebody a
+     * moderator has already let through does not queue again. Both have to
+     * match, so a stranger typing a regular's name is still held.
+     */
+    hasApprovedAuthor(name: string, email: string | null): boolean;
+    /** Store a comment, replacing whatever was known about that id. */
+    putComment(comment: PostComment): PostComment;
+    /** Forget a comment. Returns `false` when there was nothing to forget. */
+    deleteComment(id: string): boolean;
+    /**
+     * Make the comment index say exactly this, in one transaction.
+     *
+     * What a rebuild from `content/_data/comments/` calls (decision-9): the
+     * files are the source, so a row they do not carry is a comment that should
+     * not be on the page. Nothing outside a rebuild should reach for it.
+     */
+    replaceComments(comments: readonly PostComment[]): void;
     /**
      * Record how one delivery to one follower ended, replacing the previous
      * outcome for that pair: the table answers "where does this activity stand
-     * with each follower", which a redelivery moves rather than adds to.
+     * with each follower", which a resend moves rather than adds to.
      */
     recordDelivery(delivery: NewDelivery): Delivery;
     /** Every follower's outcome for one activity, in follower order. */
     listDeliveries(activityId: string): Delivery[];
     /** How many followers this activity stands at each status with. */
     countDeliveriesByStatus(activityId: string): Record<DeliveryStatus, number>;
+    /**
+     * The most recent delivery to one inbox, whichever activity it carried, or
+     * `undefined` when nothing has ever gone there.
+     *
+     * Keyed by the inbox rather than by the actor because that is what a relay
+     * has: it is not a follower, so there is no follower row to look its
+     * outcomes up by, and the inbox is the thing the site was told to deliver to.
+     */
+    lastDeliveryToInbox(inboxId: string): Delivery | undefined;
+    /**
+     * The most recent delivery about one object — a post's ActivityStreams id,
+     * or the site actor's — or `undefined` when nothing about it has ever gone
+     * out.
+     *
+     * What the federation screen's per-post row is filled in from. Keyed by the
+     * object rather than by the activity because a post is a series of
+     * activities and the row is about the post: the newest outcome is the one
+     * that says where the post currently stands with the fediverse.
+     */
+    lastDeliveryToObject(objectId: string): Delivery | undefined;
+    /**
+     * Record how one webmention to one page ended, replacing the previous
+     * outcome for that (post, target): the table answers "where does this post
+     * stand with that page", which a resend moves rather than adds to.
+     */
+    recordSentWebmention(sent: NewSentWebmention): SentWebmention;
+    /** What one post's links came to, target by target, in target order. */
+    listSentWebmentions(slug: string): SentWebmention[];
+    /** How many of one post's targets stand at each status. */
+    countSentWebmentionsByStatus(slug: string): Record<WebmentionSendStatus, number>;
+    /** Every relay subscription, oldest first, however it stands. */
+    listRelays(): Relay[];
+    /** One relay subscription by the inbox it was made to, or `undefined`. */
+    getRelay(inboxId: string): Relay | undefined;
+    /**
+     * The subscription one `Follow` established, or `undefined`.
+     *
+     * This is how an `Accept` or a `Reject` arriving later finds the relay it
+     * answers: the activity names the follow, and the follow names the record.
+     */
+    getRelayByFollow(followId: string): Relay | undefined;
+    /**
+     * Store a relay subscription, replacing whatever was known about that inbox
+     * and leaving the original `createdAt` alone: a subscription that moves from
+     * pending to accepted is the same subscription, and when it began is a fact
+     * only the row remembers.
+     */
+    putRelay(relay: NewRelay): Relay;
+    /** Forget a relay subscription. Returns `false` when there was nothing to forget. */
+    deleteRelay(inboxId: string): boolean;
     /** Delete every expired session. Returns how many went. */
     pruneSessions(now?: Date): number;
     /**
@@ -389,13 +795,6 @@ export interface AdminStore {
     /** Close the database. Safe to call twice. */
     close(): void;
 }
-/** Thrown when a username is already taken. Usernames are the login key. */
-export declare class DuplicateUsernameError extends Error {
-    readonly name = "DuplicateUsernameError";
-    /** The name that was already in use. */
-    readonly username: string;
-    constructor(username: string);
-}
 /**
  * Open (and if needed create) the admin tables in `dataDir`, applying every
  * migration the package ships. Applying them is idempotent.
@@ -404,4 +803,59 @@ export declare class DuplicateUsernameError extends Error {
  * index holding a second one on the same file.
  */
 export declare function openAdminStore(options: OpenAdminStoreOptions): AdminStore;
+/**
+ * One row of the settings table TASK-14 wrote, for the one boot that reads it.
+ *
+ * Settings live in `content/_data/site.json` now (decision-9), so this shape
+ * exists only so `migrateSettingsToFile` can write the rows out before the
+ * table goes. `updatedAt` is what tells a row written by the settings screen
+ * from a `site.json` a person edited afterwards.
+ */
+export interface LegacySetting {
+    /** The setting's name, e.g. `title`. */
+    key: string;
+    /** Its value, always a string; numbers and lists were spelled as text. */
+    value: string;
+    /** When it was last written, as an ISO instant. */
+    updatedAt: string;
+}
+/**
+ * One row of the actor key table TASK-16 wrote, for the one boot that reads it.
+ *
+ * Key pairs live in `data/keys` as JWK files now (decision-9), so this shape
+ * exists only so `migrateActorKeysToFiles` can write the rows out before the
+ * table goes. The public half the table also held is not here: it is derived
+ * from the private one, and reading it would only invite the two to disagree.
+ */
+export interface LegacyActorKey {
+    /** Which actor the pair belonged to: the sentinel identifier, not a handle. */
+    identifier: string;
+    /**
+     * Which algorithm it is for, as the table spelled it. A bare string rather
+     * than one of the algorithms this version knows, on purpose: a row a later
+     * version wrote is still a key that must reach a file rather than go with
+     * the table.
+     */
+    algorithm: string;
+    /** The private key as JWK, JSON encoded. What the file ends up holding. */
+    privateJwk: string;
+}
+/**
+ * One row of the users table TASK-9 wrote, for the one boot that reads it.
+ *
+ * Accounts live in `data/users.json` now (decision-9), so this shape exists
+ * only so `migrateUsersToFile` can write the rows out before the table goes.
+ * The id comes with them: a session in the same database names its user by it,
+ * and a migration that renumbered everybody would sign the whole site out.
+ */
+export interface LegacyUser {
+    /** The row id, which the file keeps. */
+    id: number;
+    /** The login name. */
+    username: string;
+    /** The PHC-encoded argon2id hash, moved into the file as it stands. */
+    passwordHash: string;
+    /** When the user was created, as an ISO instant. */
+    createdAt: string;
+}
 //# sourceMappingURL=store.d.ts.map