@geekity/cms 0.3.0 → 0.5.0

package/dist/federation/relays.js

@@ -0,0 +1,290 @@
+import { randomUUID } from 'node:crypto';
+import { Accept, Follow, PUBLIC_COLLECTION, Reject, Undo } from '@fedify/vocab';
+import { primaryUser } from '../admin/accounts.js';
+import { readSiteSettings } from '../admin/settings.js';
+import { actorId, senderKeyPairs } from './actor.js';
+/**
+ * One relay as the {@link Recipient} Fedify delivers to.
+ *
+ * The inbox stands in for the id until the relay has answered, because the
+ * `Follow` goes out before the site knows what to call it: Fedify drops a
+ * recipient with no id, so `null` would silently send nothing. The id is only
+ * ever used to key the inbox and to build a collection synchronisation header
+ * for a shared inbox, and a relay publishes no shared inbox — a relay *is* one
+ * — so standing the inbox in for it costs the relay nothing.
+ */
+export function relayRecipient(relay) {
+    return {
+        id: new URL(relay.actorId ?? relay.inboxId),
+        inboxId: new URL(relay.inboxId),
+    };
+}
+/**
+ * The relays a public activity is delivered to: the accepted ones, and only
+ * those.
+ *
+ * A pending subscription has not been agreed to and a rejected one has been
+ * refused; delivering to either would be posting into an inbox that has not
+ * said it wants this, which is what the handshake exists to establish.
+ */
+export function acceptedRelays(admin) {
+    return admin.listRelays().filter((relay) => relay.state === 'accepted');
+}
+/**
+ * Build the relay service for one site.
+ *
+ * FEP-ae0c is the whole of the protocol: a `Follow` whose object is the
+ * literal Public collection, sent to the relay's inbox and signed the way any
+ * other activity is; an `Accept` or a `Reject` back, which may take days
+ * because a relay is allowed to hold a subscription for a human to approve;
+ * and an `Undo` of that same `Follow` to leave.
+ */
+export function createRelayService(options) {
+    const { federation, admin, store, config } = options;
+    const logger = options.logger ?? console;
+    // Follows and undos are chained rather than run at once, for the reason
+    // deliveries are: a relay that is told to unfollow before it has been told
+    // to follow keeps the subscription. The chain never rejects.
+    let chain = Promise.resolve();
+    function enqueue(task) {
+        const result = chain.then(task);
+        chain = result.then(ignore, ignore);
+        return result;
+    }
+    /** A context outside any request, which is where a follow is sent from. */
+    function relayContext() {
+        return federation.createContext(new URL(config.baseUrl), { admin, store, config });
+    }
+    /**
+     * Who subscribes to a relay: the site's first account (decision-14).
+     *
+     * A relay subscription is an instance-wide agreement — it boosts everything
+     * public this site sends, whoever wrote it — and after decision-14 there is
+     * no site actor left to make one. The first account is the one actor that
+     * can be chosen without asking, and it is the account a one-person blog has
+     * anyway. `undefined` before anybody has signed up, and then nothing is
+     * sent: a site in first-run setup has no identity to sign with.
+     */
+    function subscriber() {
+        return primaryUser(config.dataDir);
+    }
+    /**
+     * Send one activity to one relay inbox.
+     *
+     * The key that signs the request is the subscriber's whether or not the
+     * relay has answered yet; see {@link relayRecipient} for what stands in for
+     * the id until it has.
+     */
+    async function send(context, user, relay, activity) {
+        await context.sendActivity(await senderKeyPairs(context, user), relayRecipient(relay), activity, {
+            // A relay has one inbox and no shared one, and its activities are about
+            // the subscription rather than about any post, so they are ordered
+            // against each other rather than against a post's Create.
+            orderingKey: relay.inboxId,
+        });
+    }
+    /**
+     * Follow one relay: write the record first, then send the `Follow`.
+     *
+     * The record is written before the activity goes out, not after, so an
+     * `Accept` that arrives while the POST is still in flight — a fast relay,
+     * a synchronous test — finds something to mark accepted.
+     */
+    async function follow(relay) {
+        const context = relayContext();
+        const user = subscriber();
+        if (user === undefined) {
+            logger.warn(`Could not follow the relay at ${relay.inboxId}: the site has no accounts, ` +
+                'and decision-14 makes a user the actor a subscription is made by.');
+            return admin.putRelay({ ...relay, reason: 'The site has no account to subscribe with.' });
+        }
+        const id = actorId(context, user);
+        const followId = new URL(`#relay-follow/${randomUUID()}`, id);
+        const stored = admin.putRelay({
+            inboxId: relay.inboxId,
+            actorId: relay.actorId,
+            state: 'pending',
+            reason: null,
+            followId: followId.href,
+            createdAt: relay.createdAt,
+        });
+        try {
+            await send(context, user, stored, new Follow({
+                id: followId,
+                actor: id,
+                // The literal Public collection, expanded, which is what FEP-ae0c
+                // says a relay looks for and what tells it this is a subscription
+                // rather than somebody following an account.
+                object: PUBLIC_COLLECTION,
+            }));
+        }
+        catch (thrown) {
+            // The record stays pending with the reason on it: the relay may simply
+            // have been down, and Retry is what the screen offers for that.
+            const message = messageOf(thrown);
+            logger.warn(`Could not follow the relay at ${stored.inboxId}: ${message}`);
+            return admin.putRelay({ ...stored, reason: message });
+        }
+        return stored;
+    }
+    /** Undo one relay's follow and forget it. */
+    async function unfollow(relay) {
+        const user = subscriber();
+        if (relay.followId !== null && user !== undefined) {
+            try {
+                const context = relayContext();
+                const id = actorId(context, user);
+                await send(context, user, relay, new Undo({
+                    id: new URL(`#undo/${randomUUID()}`, id),
+                    actor: id,
+                    // The follow by id rather than embedded, which FEP-ae0c allows and
+                    // which is what the relay matched its own record on.
+                    object: new URL(relay.followId),
+                }));
+            }
+            catch (thrown) {
+                // The subscription is gone from this side whatever the relay heard: a
+                // relay that keeps sending is one whose activities land in the inbox
+                // log, which is a nuisance rather than a leak, and re-adding it would
+                // strand the record against a list that no longer names it.
+                logger.warn(`Could not tell the relay at ${relay.inboxId} to stop: ${messageOf(thrown)}`);
+            }
+        }
+        admin.deleteRelay(relay.inboxId);
+    }
+    return {
+        sync() {
+            const listed = readSiteSettings(config.contentDir).relays;
+            const known = admin.listRelays();
+            const followed = [];
+            const unfollowed = [];
+            for (const inboxId of listed) {
+                if (known.some((relay) => relay.inboxId === inboxId))
+                    continue;
+                followed.push(inboxId);
+                queue(() => follow({
+                    inboxId,
+                    actorId: null,
+                    state: 'pending',
+                    reason: null,
+                    followId: null,
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                }));
+            }
+            for (const relay of known) {
+                if (listed.includes(relay.inboxId))
+                    continue;
+                unfollowed.push(relay.inboxId);
+                queue(() => unfollow(relay));
+            }
+            return { followed, unfollowed };
+        },
+        async retry(inboxId) {
+            const relay = admin.getRelay(inboxId);
+            if (relay === undefined)
+                return undefined;
+            return await enqueue(() => follow(relay));
+        },
+        settled() {
+            return chain.then(ignore);
+        },
+    };
+    /**
+     * Put one subscription change on the queue and stop caring about its result.
+     *
+     * Nothing is waiting for the follow a settings save set off, so a rejection
+     * here has nowhere to go but the log; a failed follow has already been
+     * written to its record by then.
+     */
+    function queue(task) {
+        enqueue(task).catch((thrown) => {
+            logger.warn(`A relay subscription failed: ${messageOf(thrown)}`);
+        });
+    }
+}
+/**
+ * Mark the subscription an `Accept` answers as accepted, and record who the
+ * relay turned out to be. `undefined` when it answers no follow this site
+ * sent — the site follows nothing but relays (doc-4), so that is a stray.
+ *
+ * A free function over the store rather than a method on the service: nothing
+ * about it is queued or sent, and the inbox listener that calls it has the
+ * store on its context and no service.
+ */
+export function acceptRelay(admin, activity) {
+    const relay = relayAnswering(admin, activity);
+    if (relay === undefined)
+        return undefined;
+    return admin.putRelay({
+        ...relay,
+        actorId: activity.actorId?.href ?? relay.actorId,
+        state: 'accepted',
+        reason: null,
+    });
+}
+/** The same for a `Reject`, which marks the relay rejected with its reason. */
+export function rejectRelay(admin, activity) {
+    const relay = relayAnswering(admin, activity);
+    if (relay === undefined)
+        return undefined;
+    return admin.putRelay({
+        ...relay,
+        actorId: activity.actorId?.href ?? relay.actorId,
+        state: 'rejected',
+        reason: rejectionReason(activity),
+    });
+}
+/**
+ * Match an `Accept` or a `Reject` to the subscription it answers.
+ *
+ * The follow id is what FEP-ae0c says the answer names, so it is tried first.
+ * A relay that has answered before is then recognised by its actor id, which
+ * covers a re-follow whose answer echoes a stale id. Last, a single pending
+ * subscription on the answering relay's own origin is taken as the one meant:
+ * a relay answering from the host its inbox is on is answering about that
+ * inbox, and there is nothing else it could be about. Two pending
+ * subscriptions on one host are left alone rather than guessed between.
+ */
+export function relayAnswering(admin, activity) {
+    const followId = activity.objectId?.href;
+    if (followId !== undefined) {
+        const byFollow = admin.getRelayByFollow(followId);
+        if (byFollow !== undefined)
+            return byFollow;
+    }
+    const actorId = activity.actorId?.href;
+    if (actorId === undefined)
+        return undefined;
+    const relays = admin.listRelays();
+    const byActor = relays.find((relay) => relay.actorId === actorId);
+    if (byActor !== undefined)
+        return byActor;
+    const origin = originOf(actorId);
+    if (origin === undefined)
+        return undefined;
+    const pending = relays.filter((relay) => relay.state === 'pending' && originOf(relay.inboxId) === origin);
+    return pending.length === 1 ? pending[0] : undefined;
+}
+/** Why a `Reject` was a rejection, in the relay's own words, or `null`. */
+function rejectionReason(activity) {
+    const summary = activity.summary?.toString() ?? activity.content?.toString();
+    return summary === undefined || summary === '' ? null : summary;
+}
+/** A URL's origin, or `undefined` for something that is not one. */
+function originOf(value) {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function ignore() {
+    // Deliberately empty: the chain must not reject, and a failure has already
+    // been logged and written to the record it happened to.
+}
+//# sourceMappingURL=relays.js.map

package/dist/federation/relays.js.map

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

package/dist/federation/replies.d.ts

@@ -0,0 +1,80 @@
+/**
+ * What a logged inbound activity means as a reply.
+ *
+ * The inbox keeps every `Create` it is sent whole (doc-4), and a reply is
+ * simply one whose object answers something: `inReplyTo` naming a post's
+ * ActivityStreams object id. Everything the comments feeds show is read back
+ * out of that stored JSON-LD rather than out of columns, so the index can be
+ * thrown away and rebuilt from the files TASK-32 writes.
+ */
+import type { InboxActivity } from '../admin/store.ts';
+/** The activity type a reply arrives as. A comment is a note somebody created. */
+export declare const REPLY_ACTIVITY_TYPE = "Create";
+/** One logged reply, as everything that shows a comment wants it. */
+export interface Reply {
+    /** The note's own id: its name in the fediverse, and the feed item's `guid`. */
+    id: string;
+    /** Where the note can be read — its `url`, else its id. */
+    url: string;
+    /** Who wrote it, as a name to show. */
+    author: string;
+    /** Who wrote it, as an id. */
+    actorId: string;
+    /**
+     * What it says, as the remote server rendered it and *not* sanitised.
+     *
+     * Sanitising belongs to whatever publishes the reply, so there is one place
+     * that has to be right rather than one per caller.
+     */
+    html: string;
+    /** When the note says it was published, or when it arrived if it did not. */
+    published: Date;
+    /** The object it answers: a post's ActivityStreams id. */
+    inReplyTo: string;
+}
+/**
+ * A logged activity as the reply it is, or `undefined` when it is not one.
+ *
+ * Everything is read back out of the stored JSON-LD rather than out of columns
+ * beside it, so what a comment shows survives the index being deleted.
+ *
+ * `nameFor` is the site's chance to name the author better than the activity
+ * can: the actor document is not in the activity, so without it the best
+ * available name is the `@user@host` the actor's own URL implies.
+ */
+export declare function replyFrom(activity: InboxActivity, nameFor?: (actorId: string) => string | undefined): Reply | undefined;
+/**
+ * `@user@host` for an actor URL, or `undefined` when the URL implies none.
+ *
+ * A guess, and deliberately so: naming the author properly would mean
+ * dereferencing the actor, which is a network round trip per comment shown. A
+ * follower the site already knows is named from its stored profile instead,
+ * and this is the fallback for everybody else.
+ */
+export declare function actorHandle(actorId: string): string | undefined;
+/**
+ * What a stored activity replies to, or `null` when it replies to nothing.
+ *
+ * This is the whole definition of the `in_reply_to` index column: it is
+ * derived from the activity and never supplied, so a database rebuilt from the
+ * inbox log holds exactly what the live one holds.
+ *
+ * JSON-LD lets `inReplyTo` be a string, a node object or an array of either,
+ * and a compacted activity may carry the object as a bare id instead of
+ * inlining it. Anything that is not a single absolute URI is no target.
+ */
+export declare function replyTargetOf(json: string): string | null;
+/**
+ * A JSON-LD value as the one absolute URI it names, or `null`.
+ *
+ * The three spellings a compacted document may use — a string, `{"id": …}`,
+ * and either of those wrapped in an array — all mean the same thing here, and
+ * the first of a list is the one that is kept: a note that answers several
+ * things is shown under the first one it names.
+ *
+ * Exported for the inbox log's sake: every id column of the index is read out
+ * of the stored activity by this, so what a rebuilt row says about an actor or
+ * an object is what a live one says.
+ */
+export declare function uriOf(value: unknown): string | null;
+//# sourceMappingURL=replies.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"replies.d.ts","sourceRoot":"","sources":["../../src/federation/replies.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAE5C,qEAAqE;AACrE,MAAM,WAAW,KAAK;IACpB,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,SAAS,EAAE,IAAI,CAAC;IAChB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAChD,KAAK,GAAG,SAAS,CAsBnB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAc/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIzD;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAkBnD"}

package/dist/federation/replies.js

@@ -0,0 +1,166 @@
+/**
+ * What a logged inbound activity means as a reply.
+ *
+ * The inbox keeps every `Create` it is sent whole (doc-4), and a reply is
+ * simply one whose object answers something: `inReplyTo` naming a post's
+ * ActivityStreams object id. Everything the comments feeds show is read back
+ * out of that stored JSON-LD rather than out of columns, so the index can be
+ * thrown away and rebuilt from the files TASK-32 writes.
+ */
+/** The activity type a reply arrives as. A comment is a note somebody created. */
+export const REPLY_ACTIVITY_TYPE = 'Create';
+/**
+ * A logged activity as the reply it is, or `undefined` when it is not one.
+ *
+ * Everything is read back out of the stored JSON-LD rather than out of columns
+ * beside it, so what a comment shows survives the index being deleted.
+ *
+ * `nameFor` is the site's chance to name the author better than the activity
+ * can: the actor document is not in the activity, so without it the best
+ * available name is the `@user@host` the actor's own URL implies.
+ */
+export function replyFrom(activity, nameFor) {
+    if (activity.activityType !== REPLY_ACTIVITY_TYPE)
+        return undefined;
+    const object = activityObject(activity.json);
+    if (object === undefined)
+        return undefined;
+    const inReplyTo = uriOf(object['inReplyTo']);
+    const id = uriOf(object['id']) ?? activity.objectId;
+    if (inReplyTo === null || id === null)
+        return undefined;
+    const actorId = activity.actorId;
+    const published = new Date(textOf(object['published']) ?? '');
+    return {
+        id,
+        url: uriOf(object['url']) ?? id,
+        author: nameFor?.(actorId) ?? actorHandle(actorId) ?? actorId,
+        actorId,
+        html: textOf(object['content']) ?? languageText(object['contentMap']) ?? '',
+        published: Number.isNaN(published.getTime()) ? new Date(activity.receivedAt) : published,
+        inReplyTo,
+    };
+}
+/**
+ * `@user@host` for an actor URL, or `undefined` when the URL implies none.
+ *
+ * A guess, and deliberately so: naming the author properly would mean
+ * dereferencing the actor, which is a network round trip per comment shown. A
+ * follower the site already knows is named from its stored profile instead,
+ * and this is the fallback for everybody else.
+ */
+export function actorHandle(actorId) {
+    let url;
+    try {
+        url = new URL(actorId);
+    }
+    catch {
+        return undefined;
+    }
+    const last = url.pathname
+        .split('/')
+        .filter((segment) => segment !== '')
+        .pop();
+    if (last === undefined || last === '')
+        return undefined;
+    return `@${last.replace(/^@/, '')}@${url.host}`;
+}
+/**
+ * What a stored activity replies to, or `null` when it replies to nothing.
+ *
+ * This is the whole definition of the `in_reply_to` index column: it is
+ * derived from the activity and never supplied, so a database rebuilt from the
+ * inbox log holds exactly what the live one holds.
+ *
+ * JSON-LD lets `inReplyTo` be a string, a node object or an array of either,
+ * and a compacted activity may carry the object as a bare id instead of
+ * inlining it. Anything that is not a single absolute URI is no target.
+ */
+export function replyTargetOf(json) {
+    const object = activityObject(json);
+    if (object === undefined)
+        return null;
+    return uriOf(object['inReplyTo']);
+}
+/** The inlined object of a stored activity, or `undefined` when there is none. */
+function activityObject(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        // A row whose JSON does not parse is not a reply. It is not anything.
+        return undefined;
+    }
+    if (!isRecord(parsed))
+        return undefined;
+    const object = parsed['object'];
+    return isRecord(object) ? object : undefined;
+}
+/**
+ * A JSON-LD value as the one absolute URI it names, or `null`.
+ *
+ * The three spellings a compacted document may use — a string, `{"id": …}`,
+ * and either of those wrapped in an array — all mean the same thing here, and
+ * the first of a list is the one that is kept: a note that answers several
+ * things is shown under the first one it names.
+ *
+ * Exported for the inbox log's sake: every id column of the index is read out
+ * of the stored activity by this, so what a rebuilt row says about an actor or
+ * an object is what a live one says.
+ */
+export function uriOf(value) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = uriOf(item);
+            if (found !== null)
+                return found;
+        }
+        return null;
+    }
+    // A node object names its subject with `id`; a `Link` — which is how a note
+    // often spells its `url` — names its target with `href`.
+    if (isRecord(value))
+        return uriOf(value['id'] ?? value['@id'] ?? value['href']);
+    if (typeof value !== 'string')
+        return null;
+    try {
+        return new URL(value).href;
+    }
+    catch {
+        return null;
+    }
+}
+/** A JSON-LD value as the one string it holds, or `undefined`. */
+function textOf(value) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = textOf(item);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    if (isRecord(value))
+        return textOf(value['@value']);
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * One value out of a language map, which is how a compacted document spells a
+ * property that named its language. Which language is not worth choosing: a
+ * note is written in one, and the map holds that one.
+ */
+function languageText(value) {
+    if (!isRecord(value))
+        return undefined;
+    for (const entry of Object.values(value)) {
+        const found = textOf(entry);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=replies.js.map

package/dist/federation/replies.js.map

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