@geekity/cms 0.3.0 → 0.4.0

package/dist/federation/wordpress.d.ts

@@ -0,0 +1,131 @@
+import type { InboxContext } from '@fedify/fedify';
+import type { User } from '../admin/accounts.ts';
+import type { CreateSiteFederationOptions, FederationContextData } from './federation.ts';
+import type { SiteFederation } from './federation.ts';
+/**
+ * The WordPress ActivityPub plugin's paths, served behind a switch (TASK-70).
+ *
+ * A follower's server delivers to the inbox URL it cached from the actor
+ * document, and replaces it only when it next refetches the actor. A site that
+ * moved here from the plugin therefore goes on being delivered to at
+ * `/wp-json/activitypub/1.0/actors/2/inbox` and `/wp-json/activitypub/1.0/inbox`
+ * for as long as those caches last, and decision-14 calls that **cache rather
+ * than identity**: the CMS carries the plugin's layout until the caches have
+ * moved on, and no longer.
+ *
+ * So everything here is behind the `wordpressActivityPub` site setting, and
+ * everything a peer reads back is the canonical identity. The actor served at
+ * `…/actors/2` is the same `Person` the author URL serves — same `id`, same
+ * canonical `inbox` — so a peer that refetches here learns the new endpoints
+ * rather than being handed the old ones again. That is what eventually makes
+ * the switch safe to turn off.
+ *
+ * A second `Federation` is how Fedify serves a second inbox path at all: one
+ * object may have exactly one pair of inbox listeners, and `ctx.routeActivity`
+ * re-verifies from scratch in a way a Mastodon or WordPress `Follow` cannot
+ * satisfy (doc-8). The second object shares the canonical one's KV store, and
+ * both sets of listeners are set to `per-origin` idempotence, because the
+ * default folds the recipient identifier into the key — so the same `Follow`
+ * redelivered to `andrew` and to `2` would otherwise be handled twice.
+ */
+/** Where the plugin's REST namespace lives, on the site's origin. */
+export declare const WORDPRESS_ACTIVITYPUB_BASE = "/wp-json/activitypub/1.0";
+/** The plugin's actor path. Its identifier is the WordPress user's number. */
+export declare const WORDPRESS_ACTOR_PATH: "/wp-json/activitypub/1.0/actors/{identifier}";
+/** The actor's inbox, outbox and two follow collections, as the plugin spells them. */
+export declare const WORDPRESS_INBOX_PATH: "/wp-json/activitypub/1.0/actors/{identifier}/inbox";
+export declare const WORDPRESS_OUTBOX_PATH: "/wp-json/activitypub/1.0/actors/{identifier}/outbox";
+export declare const WORDPRESS_FOLLOWERS_PATH: "/wp-json/activitypub/1.0/actors/{identifier}/followers";
+export declare const WORDPRESS_FOLLOWING_PATH: "/wp-json/activitypub/1.0/actors/{identifier}/following";
+/** The plugin's instance-wide inbox, which its `sharedInbox` endpoint names. */
+export declare const WORDPRESS_SHARED_INBOX_PATH: "/wp-json/activitypub/1.0/inbox";
+/** What {@link createWordPressFederation} takes beyond the canonical options. */
+export interface CreateWordPressFederationOptions extends CreateSiteFederationOptions {
+    /**
+     * The site's own federation, whose contexts every identity here is built
+     * from.
+     *
+     * Fedify derives an actor's id, its key ids and its collection URLs from the
+     * path it dispatches the actor at, and the paths here are the plugin's. A
+     * document built off this object's own context would tell a peer that the
+     * person *is* `…/wp-json/…/actors/2` and sign with a key id under it, which
+     * is the opposite of what the switch is for.
+     */
+    canonical: SiteFederation;
+}
+/**
+ * Build the compatibility federation: the plugin's inbox and collections,
+ * mapped to users by the number WordPress gave them.
+ *
+ * Nothing else is registered. WebFinger, NodeInfo and the actor's real
+ * endpoints belong to the canonical federation and stay there; this object
+ * exists only so that deliveries and fetches aimed at the old layout land
+ * somewhere, signature-verified at the real request path exactly as the
+ * canonical inbox verifies them.
+ */
+export declare function createWordPressFederation(options: CreateWordPressFederationOptions): SiteFederation;
+/**
+ * The user the WordPress ActivityPub plugin numbered `identifier`, or
+ * `undefined`.
+ *
+ * The identifier is a path segment, so it is compared as the decimal the
+ * plugin writes: `02` and `2.0` name nobody, because neither is a URL the
+ * plugin ever published.
+ */
+export declare function userByWordPressActorId(dataDir: string, identifier: string): User | undefined;
+/** One of the plugin's paths, as the record of what was asked for names it. */
+export type WordPressRoute = 'actor' | 'inbox' | 'outbox' | 'followers' | 'following';
+/** Which compatibility path a request is for, and whose. */
+export interface WordPressRequestTarget {
+    /** The path it is, or `sharedInbox` for the instance-wide one. */
+    readonly route: WordPressRoute | 'sharedInbox';
+    /** The WordPress number in the path, or `undefined` for the shared inbox. */
+    readonly wordpressActorId?: string | undefined;
+}
+/**
+ * The compatibility path a request asks for, or `undefined` for anything else.
+ *
+ * Matched here rather than left to Fedify because the record of what was last
+ * asked for has to be written whether or not a user answers: a delivery to a
+ * number nobody carries is still a peer holding the old URL, and it is exactly
+ * the sort of thing the owner watching the screen wants to see. Fedify's
+ * router still decides what is actually served.
+ */
+export declare function wordPressRequestTarget(pathname: string): WordPressRequestTarget | undefined;
+/** The file the instants live in, relative to `dataDir`. */
+export declare const WORDPRESS_REQUESTS_FILE = "wordpress-activitypub.json";
+/** Where that file lives for a given data directory. */
+export declare function wordPressRequestsFile(dataDir: string): string;
+/**
+ * When each compatibility path was last asked for.
+ *
+ * A file under `data/` rather than a table, because the database is a cache a
+ * site may delete (decision-9) and this is the one thing the switch is watched
+ * by: an owner deciding whether every follower's server has refetched the
+ * actor should not have that answer reset by a rebuild.
+ */
+export interface WordPressRequests {
+    /** When the instance-wide inbox was last delivered to, or `undefined`. */
+    readonly sharedInbox?: string | undefined;
+    /** When each of a user's own paths was last asked for, by username. */
+    readonly users: Readonly<Record<string, Readonly<Partial<Record<WordPressRoute, string>>>>>;
+}
+/** The file as it reads now; a site nobody has asked has nothing to say. */
+export declare function readWordPressRequests(dataDir: string): WordPressRequests;
+/**
+ * Record that one compatibility path was just asked for.
+ *
+ * Written through {@link updateFileAtomically}, so two deliveries arriving
+ * together cannot lose one another's instant and a reader never sees a
+ * half-written file. A path whose number names nobody is not recorded: the
+ * record is per user, and there is no user to record it against.
+ */
+export declare function recordWordPressRequest(options: {
+    dataDir: string;
+    target: WordPressRequestTarget;
+    username?: string | undefined;
+    at: Date;
+}): Promise<void>;
+/** A compatibility context, for the handlers that are handed one. */
+export type WordPressInboxContext = InboxContext<FederationContextData>;
+//# sourceMappingURL=wordpress.d.ts.map

package/dist/federation/wordpress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wordpress.d.ts","sourceRoot":"","sources":["../../src/federation/wordpress.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAW,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAK5D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAKjD,OAAO,KAAK,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAa1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,qEAAqE;AACrE,eAAO,MAAM,0BAA0B,6BAA6B,CAAC;AAErE,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,gDAA+D,CAAC;AAEjG,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,sDAA2C,CAAC;AAC7E,eAAO,MAAM,qBAAqB,uDAA4C,CAAC;AAC/E,eAAO,MAAM,wBAAwB,0DAA+C,CAAC;AACrF,eAAO,MAAM,wBAAwB,0DAA+C,CAAC;AAErF,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,kCAAiD,CAAC;AAE1F,iFAAiF;AACjF,MAAM,WAAW,gCAAiC,SAAQ,2BAA2B;IACnF;;;;;;;;;OASG;IACH,SAAS,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gCAAgC,GACxC,cAAc,CAuIhB;AA6BD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAI5F;AAED,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CAAC;AAEtF,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,CAAC;IAC/C,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAc3F;AAED,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,+BAA+B,CAAC;AAEpE,wDAAwD;AACxD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7F;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAaxE;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,sBAAsB,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,EAAE,EAAE,IAAI,CAAC;CACV,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB;AAsDD,qEAAqE;AACrE,MAAM,MAAM,qBAAqB,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAC"}

package/dist/federation/wordpress.js

@@ -0,0 +1,341 @@
+import path from 'node:path';
+import { createFederation, InProcessMessageQueue, MemoryKvStore } from '@fedify/fedify';
+import { Accept, Announce, Create, Delete, Follow, Like, Reject, Undo } from '@fedify/vocab';
+import { listUsers } from '../admin/accounts.js';
+import { readFileIfPresentSync, updateFileAtomically } from '../files/atomic.js';
+import { authorNames } from '../web/authors.js';
+import { userActor } from './actor.js';
+import { federationOrigin } from './paths.js';
+import { outboxPage, OUTBOX_PAGE_SIZE } from './federation.js';
+import { followersPage, lastFollowersCursor } from './followers.js';
+import { handleAccept, handleDelete, handleFollow, handleLoggedActivity, handleReject, handleUndo, } from './inbox.js';
+import { loadActorKeyPairs } from './keys.js';
+/**
+ * The WordPress ActivityPub plugin's paths, served behind a switch (TASK-70).
+ *
+ * A follower's server delivers to the inbox URL it cached from the actor
+ * document, and replaces it only when it next refetches the actor. A site that
+ * moved here from the plugin therefore goes on being delivered to at
+ * `/wp-json/activitypub/1.0/actors/2/inbox` and `/wp-json/activitypub/1.0/inbox`
+ * for as long as those caches last, and decision-14 calls that **cache rather
+ * than identity**: the CMS carries the plugin's layout until the caches have
+ * moved on, and no longer.
+ *
+ * So everything here is behind the `wordpressActivityPub` site setting, and
+ * everything a peer reads back is the canonical identity. The actor served at
+ * `…/actors/2` is the same `Person` the author URL serves — same `id`, same
+ * canonical `inbox` — so a peer that refetches here learns the new endpoints
+ * rather than being handed the old ones again. That is what eventually makes
+ * the switch safe to turn off.
+ *
+ * A second `Federation` is how Fedify serves a second inbox path at all: one
+ * object may have exactly one pair of inbox listeners, and `ctx.routeActivity`
+ * re-verifies from scratch in a way a Mastodon or WordPress `Follow` cannot
+ * satisfy (doc-8). The second object shares the canonical one's KV store, and
+ * both sets of listeners are set to `per-origin` idempotence, because the
+ * default folds the recipient identifier into the key — so the same `Follow`
+ * redelivered to `andrew` and to `2` would otherwise be handled twice.
+ */
+/** Where the plugin's REST namespace lives, on the site's origin. */
+export const WORDPRESS_ACTIVITYPUB_BASE = '/wp-json/activitypub/1.0';
+/** The plugin's actor path. Its identifier is the WordPress user's number. */
+export const WORDPRESS_ACTOR_PATH = `${WORDPRESS_ACTIVITYPUB_BASE}/actors/{identifier}`;
+/** The actor's inbox, outbox and two follow collections, as the plugin spells them. */
+export const WORDPRESS_INBOX_PATH = `${WORDPRESS_ACTOR_PATH}/inbox`;
+export const WORDPRESS_OUTBOX_PATH = `${WORDPRESS_ACTOR_PATH}/outbox`;
+export const WORDPRESS_FOLLOWERS_PATH = `${WORDPRESS_ACTOR_PATH}/followers`;
+export const WORDPRESS_FOLLOWING_PATH = `${WORDPRESS_ACTOR_PATH}/following`;
+/** The plugin's instance-wide inbox, which its `sharedInbox` endpoint names. */
+export const WORDPRESS_SHARED_INBOX_PATH = `${WORDPRESS_ACTIVITYPUB_BASE}/inbox`;
+/**
+ * Build the compatibility federation: the plugin's inbox and collections,
+ * mapped to users by the number WordPress gave them.
+ *
+ * Nothing else is registered. WebFinger, NodeInfo and the actor's real
+ * endpoints belong to the canonical federation and stay there; this object
+ * exists only so that deliveries and fetches aimed at the old layout land
+ * somewhere, signature-verified at the real request path exactly as the
+ * canonical inbox verifies them.
+ */
+export function createWordPressFederation(options) {
+    const { canonical } = options;
+    const federation = createFederation({
+        kv: options.kv ?? new MemoryKvStore(),
+        origin: federationOrigin(options.baseUrl),
+        ...(options.queue === null ? {} : { queue: options.queue ?? new InProcessMessageQueue() }),
+        ...(options.allowPrivateAddress === undefined
+            ? {}
+            : { allowPrivateAddress: options.allowPrivateAddress }),
+        ...options.federationOptions,
+    });
+    /** The user a dispatcher's identifier names, which here is a number. */
+    function actorFor(context, identifier) {
+        return userByWordPressActorId(context.data.config.dataDir, identifier);
+    }
+    /**
+     * A context of the canonical federation over the same data.
+     *
+     * Every id a peer reads or verifies comes from here rather than from the
+     * compatibility context, so the actor, the key ids, the `Accept` and the
+     * collections a peer is pointed at are the ones the site really publishes.
+     */
+    function identity(context) {
+        return canonical.createContext(new URL(context.origin), context.data);
+    }
+    /** Every stored `author` string that reads as this user (TASK-67). */
+    function namesOf(context, user) {
+        return authorNames(listUsers(context.data.config.dataDir), user);
+    }
+    federation
+        .setActorDispatcher(WORDPRESS_ACTOR_PATH, async (context, identifier) => {
+        const user = actorFor(context, identifier);
+        if (user === undefined)
+            return null;
+        // The canonical document, verbatim: a peer refetching the actor at the
+        // old URL is exactly the peer that should learn the new inbox.
+        return await userActor(identity(context), user, { baseUrl: context.data.config.baseUrl });
+    })
+        .setKeyPairsDispatcher(async (context, identifier) => {
+        const user = actorFor(context, identifier);
+        return user === undefined
+            ? []
+            : await loadActorKeyPairs(context.data.config.dataDir, user.username);
+    });
+    federation
+        .setOutboxDispatcher(WORDPRESS_OUTBOX_PATH, (context, identifier, cursor) => {
+        const user = actorFor(context, identifier);
+        return user === undefined
+            ? null
+            : outboxPage(identity(context), namesOf(context, user), cursor);
+    })
+        .setCounter((context, identifier) => {
+        const user = actorFor(context, identifier);
+        return user === undefined ? null : context.data.store.countByAuthor(namesOf(context, user));
+    })
+        .setFirstCursor((context, identifier) => actorFor(context, identifier) === undefined ? null : '0')
+        .setLastCursor((context, identifier) => {
+        const user = actorFor(context, identifier);
+        if (user === undefined)
+            return null;
+        const total = context.data.store.countByAuthor(namesOf(context, user));
+        return String(total === 0 ? 0 : Math.floor((total - 1) / OUTBOX_PAGE_SIZE) * OUTBOX_PAGE_SIZE);
+    });
+    federation
+        .setFollowersDispatcher(WORDPRESS_FOLLOWERS_PATH, (context, identifier, cursor) => {
+        const user = actorFor(context, identifier);
+        return user === undefined ? null : followersPage(context, user.username, cursor);
+    })
+        .setCounter((context, identifier) => {
+        const user = actorFor(context, identifier);
+        return user === undefined ? null : context.data.admin.countFollowers(user.username);
+    })
+        .setFirstCursor((context, identifier) => actorFor(context, identifier) === undefined ? null : '0')
+        .setLastCursor((context, identifier) => {
+        const user = actorFor(context, identifier);
+        return user === undefined
+            ? null
+            : lastFollowersCursor(context.data.admin.countFollowers(user.username));
+    });
+    federation.setFollowingDispatcher(WORDPRESS_FOLLOWING_PATH, (context, identifier) => actorFor(context, identifier) === undefined ? null : { items: [] });
+    // The same five handlers the canonical inbox runs, over a canonical context.
+    // `per-origin` idempotence is what keeps one `Follow` redelivered to both
+    // inboxes from being handled twice (doc-8); the canonical federation is set
+    // the same way, and they share a KV store so the two agree about what they
+    // have already seen.
+    federation
+        .setInboxListeners(WORDPRESS_INBOX_PATH, WORDPRESS_SHARED_INBOX_PATH)
+        .withIdempotency('per-origin')
+        .on(Follow, canonically(handleFollow))
+        .on(Accept, canonically(handleAccept))
+        .on(Reject, canonically(handleReject))
+        .on(Undo, canonically(handleUndo))
+        .on(Delete, canonically(handleDelete))
+        .on(Like, canonically(handleLoggedActivity))
+        .on(Announce, canonically(handleLoggedActivity))
+        .on(Create, canonically(handleLoggedActivity));
+    /**
+     * One inbox handler, run against the canonical federation.
+     *
+     * Two things are swapped. The context is the canonical one, so `parseUri`
+     * recognises the site's own actor URLs, the `Accept` is signed with the key
+     * the actor document publishes and sent from the id its followers hold. And
+     * `recipient` — which arrives here as the WordPress number, straight off the
+     * path — is the username, because that is what every handler and the inbox
+     * log mean by a recipient.
+     */
+    function canonically(handle) {
+        return async (context, activity) => {
+            const user = context.recipient === null ? undefined : actorFor(context, context.recipient);
+            await handle(withRecipient(identity(context), context, user?.username ?? null), activity);
+        };
+    }
+    return federation;
+}
+/**
+ * A canonical context wearing one inbox delivery's recipient.
+ *
+ * A `Proxy` rather than a copy: Fedify's context is a class with private state,
+ * so its methods have to keep running against the object they were made for.
+ * Everything but `recipient` and `forwardActivity` is the canonical context's
+ * own.
+ */
+function withRecipient(canonical, delivered, recipient) {
+    return new Proxy(canonical, {
+        get(target, property) {
+            if (property === 'recipient')
+                return recipient;
+            // Forwarding is the one thing only the delivering context can do: it
+            // holds the bytes that arrived, signatures and all.
+            if (property === 'forwardActivity')
+                return delivered.forwardActivity.bind(delivered);
+            const value = Reflect.get(target, property, target);
+            return typeof value === 'function'
+                ? value.bind(target)
+                : value;
+        },
+    });
+}
+/**
+ * The user the WordPress ActivityPub plugin numbered `identifier`, or
+ * `undefined`.
+ *
+ * The identifier is a path segment, so it is compared as the decimal the
+ * plugin writes: `02` and `2.0` name nobody, because neither is a URL the
+ * plugin ever published.
+ */
+export function userByWordPressActorId(dataDir, identifier) {
+    if (!/^[1-9][0-9]*$/.test(identifier))
+        return undefined;
+    const wanted = Number(identifier);
+    return listUsers(dataDir).find((user) => user.wordpressActorId === wanted);
+}
+/**
+ * The compatibility path a request asks for, or `undefined` for anything else.
+ *
+ * Matched here rather than left to Fedify because the record of what was last
+ * asked for has to be written whether or not a user answers: a delivery to a
+ * number nobody carries is still a peer holding the old URL, and it is exactly
+ * the sort of thing the owner watching the screen wants to see. Fedify's
+ * router still decides what is actually served.
+ */
+export function wordPressRequestTarget(pathname) {
+    if (pathname === WORDPRESS_SHARED_INBOX_PATH)
+        return { route: 'sharedInbox' };
+    const under = `${WORDPRESS_ACTIVITYPUB_BASE}/actors/`;
+    if (!pathname.startsWith(under))
+        return undefined;
+    const [number, name, ...rest] = pathname.slice(under.length).split('/');
+    if (number === undefined || number === '' || rest.length > 0)
+        return undefined;
+    if (name === undefined || name === '')
+        return { route: 'actor', wordpressActorId: number };
+    if (name === 'inbox' || name === 'outbox' || name === 'followers' || name === 'following') {
+        return { route: name, wordpressActorId: number };
+    }
+    return undefined;
+}
+/** The file the instants live in, relative to `dataDir`. */
+export const WORDPRESS_REQUESTS_FILE = 'wordpress-activitypub.json';
+/** Where that file lives for a given data directory. */
+export function wordPressRequestsFile(dataDir) {
+    return path.join(dataDir, WORDPRESS_REQUESTS_FILE);
+}
+/** The file as it reads now; a site nobody has asked has nothing to say. */
+export function readWordPressRequests(dataDir) {
+    const source = readFileIfPresentSync(wordPressRequestsFile(dataDir));
+    if (source === undefined)
+        return { users: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        // A record of who asked for what is not worth failing a request over, and
+        // "never" is the honest answer when the file cannot be read.
+        return { users: {} };
+    }
+    return requestsFrom(parsed);
+}
+/**
+ * Record that one compatibility path was just asked for.
+ *
+ * Written through {@link updateFileAtomically}, so two deliveries arriving
+ * together cannot lose one another's instant and a reader never sees a
+ * half-written file. A path whose number names nobody is not recorded: the
+ * record is per user, and there is no user to record it against.
+ */
+export async function recordWordPressRequest(options) {
+    const { target, username } = options;
+    if (target.route !== 'sharedInbox' && username === undefined)
+        return;
+    const instant = options.at.toISOString();
+    const file = wordPressRequestsFile(options.dataDir);
+    await updateFileAtomically(file, (current) => {
+        const requests = requestsFrom(parseOrEmpty(current));
+        const next = target.route === 'sharedInbox'
+            ? { ...requests, sharedInbox: instant }
+            : {
+                ...requests,
+                users: {
+                    ...requests.users,
+                    [username ?? '']: {
+                        ...requests.users[username ?? ''],
+                        [target.route]: instant,
+                    },
+                },
+            };
+        return `${JSON.stringify(next, null, 2)}\n`;
+    });
+}
+/** The bytes of the file as whatever JSON they hold, or nothing usable. */
+function parseOrEmpty(source) {
+    if (source === undefined)
+        return undefined;
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whatever the file held as the instants this version understands.
+ *
+ * Read key by key and dropped rather than refused, on the rule the users file
+ * and `site.json` are read by: this is a record of what happened, and a
+ * damaged one should cost the screen a column, not the site a boot.
+ */
+function requestsFrom(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return { users: {} };
+    const record = value;
+    const users = {};
+    const listed = record['users'];
+    if (typeof listed === 'object' && listed !== null && !Array.isArray(listed)) {
+        for (const [username, routes] of Object.entries(listed)) {
+            if (typeof routes !== 'object' || routes === null || Array.isArray(routes))
+                continue;
+            const kept = {};
+            for (const [name, instant] of Object.entries(routes)) {
+                if (typeof instant === 'string' && isWordPressRoute(name))
+                    kept[name] = instant;
+            }
+            if (Object.keys(kept).length > 0)
+                users[username] = kept;
+        }
+    }
+    const shared = record['sharedInbox'];
+    return {
+        ...(typeof shared === 'string' ? { sharedInbox: shared } : {}),
+        users,
+    };
+}
+/** Whether a stored key names a path this version serves. */
+function isWordPressRoute(name) {
+    return (name === 'actor' ||
+        name === 'inbox' ||
+        name === 'outbox' ||
+        name === 'followers' ||
+        name === 'following');
+}
+//# sourceMappingURL=wordpress.js.map

package/dist/federation/wordpress.js.map

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

package/dist/files/atomic.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Writing a file the way decision-9 needs it written.
+ *
+ * Files are the source of truth for everything durable, and SQLite is a cache
+ * that may be deleted — which means the transactions that used to cover a
+ * settings save or a new follower cover nothing any more. Two properties take
+ * their place, and both live here so no caller has to remember them:
+ *
+ * - **Atomic.** The bytes go to a temporary sibling and are renamed over the
+ *   target, and `rename(2)` within one directory is atomic. A reader — an
+ *   Eleventy build, the site data source, another process entirely — sees the
+ *   whole old file or the whole new one, never half of either, and a crash
+ *   half way through leaves the old file intact.
+ * - **Serialised.** Every write to one path queues behind the last, in this
+ *   process, so two requests that both rewrite `site.json` cannot interleave.
+ *   {@link updateFileAtomically} puts the read inside that queue as well,
+ *   which is what stops the second writer reading the file before the first
+ *   has written it and then overwriting what it wrote.
+ *
+ * The queue is per path, so writes to different files still run at once, and
+ * a path is forgotten again as soon as its queue drains.
+ */
+/** What every write here takes besides the bytes. */
+export interface WriteFileAtomicallyOptions {
+    /**
+     * The permissions the file ends up with, e.g. `0o600` for a private key.
+     *
+     * It is applied to the temporary file before the rename, so the bytes are
+     * never readable by anybody the finished file would not be readable by.
+     * Left off, the file is created with the process's usual mode — and, because
+     * the rename replaces the target rather than writing through it, that is
+     * true of a rewrite too: the mode is the one named here, not the one the old
+     * file happened to have.
+     */
+    mode?: number | undefined;
+}
+/** What a write puts in a file: text, or bytes as they are. */
+export type FileContents = string | Uint8Array;
+/**
+ * Produce the new contents from the current ones.
+ *
+ * `current` is `undefined` when the file does not exist yet, which is a real
+ * state rather than an error: the first follower, the first settings save on a
+ * site that has no `site.json`.
+ */
+export type ProduceFileContents = (current: string | undefined) => FileContents | Promise<FileContents>;
+/**
+ * Write a file atomically, behind whatever is already being written to it.
+ *
+ * The directory it lives in is created if it is missing, so a caller writing
+ * the first file under `data/keys` or `content/_data` does not have to.
+ */
+export declare function writeFileAtomically(file: string, contents: FileContents, options?: WriteFileAtomicallyOptions): Promise<void>;
+/**
+ * Read a file, decide what it should say next, and write it — all three as one
+ * step nothing else writing that file can get between.
+ *
+ * The read-modify-write is the shape almost every file in this CMS is changed
+ * by: `site.json` keeps the keys the settings form does not manage,
+ * `followers.json` gains or loses one entry, a month's inbox log gains a line.
+ * A queue around the write alone would not be enough for any of them, because
+ * two writers could both read the old file first.
+ */
+export declare function updateFileAtomically(file: string, produce: ProduceFileContents, options?: WriteFileAtomicallyOptions): Promise<void>;
+/**
+ * Run a task with one path's queue to itself, and hand back what it returned.
+ *
+ * The queue {@link updateFileAtomically} keeps around a read and a write, for
+ * a caller whose step is more than those two. The one that needs it is a file
+ * that SQLite indexes: a follower arriving has to reach `followers.json` and
+ * the `followers` table, and if the second of those were a step after the lock
+ * rather than inside it, a follow and an unfollow racing could leave the index
+ * saying something the file does not — and the file is the truth, so the index
+ * would be wrong until the next boot rebuilt it.
+ *
+ * The task is not handed a writer, because the writer it wants is the one that
+ * does not queue: {@link readFileIfPresentSync} and
+ * {@link writeFileAtomicallySync} inside the lock are the whole pattern.
+ * Calling {@link writeFileAtomically} or {@link updateFileAtomically} on the
+ * same path from inside a task would wait for a queue the task is itself at
+ * the head of, and never return.
+ */
+export declare function withFileLock<T>(file: string, task: () => T | Promise<T>): Promise<T>;
+/**
+ * The same write for a caller that cannot await: boot.
+ *
+ * `createCms` is synchronous — a site calls it and reads `cms.app` — so the
+ * once-only migrations that turn an old database's rows into files have no
+ * `await` to spend. They run before the server is listening and before
+ * anything else has written a file, so stepping outside the queue costs
+ * nothing; the rename still makes the write atomic against a reader.
+ */
+export declare function writeFileAtomicallySync(file: string, contents: FileContents, options?: WriteFileAtomicallyOptions): void;
+/**
+ * Read a file's whole contents as text, or `undefined` when it is not there.
+ *
+ * The counterpart of the writes above, for the same reason they exist: a file
+ * that is the source of truth is read on the way to being written, and a
+ * missing one means "nothing stored yet" everywhere in this CMS rather than an
+ * error to handle at each call site.
+ */
+export declare function readFileIfPresentSync(file: string): string | undefined;
+//# sourceMappingURL=atomic.d.ts.map

package/dist/files/atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../../src/files/atomic.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,qDAAqD;AACrD,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,MAAM,GAAG,SAAS,KACxB,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AAa1C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,EAC5B,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,0BAA+B,GACvC,IAAI,CAeN;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMtE"}