@geekity/plugin-wordpress 0.0.0-stage → 0.1.1

package/dist/bundle/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "@geekity/plugin-wordpress",
+  "version": "0.1.1",
+  "hostApi": 1,
+  "peerDependencies": {
+    "@geekity/cms": ">=0.27.0 <1.0.0"
+  }
+}

package/dist/command.d.ts

@@ -0,0 +1,17 @@
+import type { PluginCommand } from '@geekity/cms/plugin';
+import type { WordPressRecords } from './records.ts';
+/**
+ * `geekity import wordpress-actor <username>`: the cutover, for one person.
+ *
+ * Everything the WordPress ActivityPub plugin holds that the site cannot mint
+ * for itself arrives here (decision-14): the RSA pair its followers have
+ * cached, the actor id they key the account by, the number its paths are
+ * built from, and the followers themselves. It is a command rather than a
+ * screen because a stored actor id is identity for the life of the account,
+ * and it is idempotent because the cutover is a thing an owner runs twice:
+ * once before the DNS moves and once after an instance that was down comes
+ * back. It runs whether or not the plugin is enabled, because the import
+ * comes first.
+ */
+export declare function importCommand(records: WordPressRecords): PluginCommand;
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAwB,MAAM,qBAAqB,CAAC;AAK/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAkDtE"}

package/dist/command.js

@@ -0,0 +1,194 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { importWordPressActor } from './import.js';
+import { WORDPRESS_ACTIVITYPUB_BASE } from './records.js';
+/**
+ * `geekity import wordpress-actor <username>`: the cutover, for one person.
+ *
+ * Everything the WordPress ActivityPub plugin holds that the site cannot mint
+ * for itself arrives here (decision-14): the RSA pair its followers have
+ * cached, the actor id they key the account by, the number its paths are
+ * built from, and the followers themselves. It is a command rather than a
+ * screen because a stored actor id is identity for the life of the account,
+ * and it is idempotent because the cutover is a thing an owner runs twice:
+ * once before the DNS moves and once after an instance that was down comes
+ * back. It runs whether or not the plugin is enabled, because the import
+ * comes first.
+ */
+export function importCommand(records) {
+    return {
+        words: ['import', 'wordpress-actor'],
+        usage: '<username> --actor-id <url> --wordpress-id <n> (--keypair <file> | --private-key <file> [--public-key <file>]) [--followers <url|file|none>] [--force]',
+        summary: "Bring one person across from the WordPress ActivityPub plugin: their key pair, the actor id their followers hold, the plugin's numeric actor id, and their followers.",
+        options: [
+            {
+                name: 'actor-id',
+                value: '<url>',
+                description: 'The actor id WordPress published, query string and all, for example https://example.com/?author=2',
+            },
+            {
+                name: 'wordpress-id',
+                value: '<n>',
+                description: `The WordPress user id, which is the number in the plugin's paths (${WORDPRESS_ACTIVITYPUB_BASE}/actors/<n>/inbox).`,
+            },
+            {
+                name: 'keypair',
+                value: '<file>',
+                description: 'The JSON `wp option get activitypub_keypair_for_<login> --format=json` prints: {"private_key": …, "public_key": …}.',
+            },
+            {
+                name: 'private-key',
+                value: '<file>',
+                description: 'The private key as PEM, instead of --keypair.',
+            },
+            {
+                name: 'public-key',
+                value: '<file>',
+                description: 'The public key as PEM. Optional, and only checked against the private half; it is derived, never stored.',
+            },
+            {
+                name: 'followers',
+                value: '<url|file|none>',
+                description: "Where the followers come from. Left off, the plugin's own public followers collection on the actor id's origin.",
+            },
+            {
+                name: 'force',
+                description: 'Import over a key pair the user already has. Do this only when you are certain the pair being imported is the one the followers hold: a new key means none of them can verify this person again.',
+            },
+        ],
+        run: (context) => run(context, records),
+    };
+}
+async function run(context, records) {
+    const { args, options } = context;
+    const username = args[0];
+    if (username === undefined) {
+        throw new Error('geekity import wordpress-actor <username> needs the account on this site the ' +
+            "plugin's actor becomes.");
+    }
+    const actorId = text(options, 'actor-id');
+    if (actorId === undefined) {
+        throw new Error('--actor-id is the id WordPress published this person under, query string and all, ' +
+            'for example --actor-id "https://example.com/?author=2". Its followers key the ' +
+            'account by it, so it is the one thing the import cannot work out for itself.');
+    }
+    if (!isAbsoluteHttpUrl(actorId)) {
+        throw new Error(`--actor-id must be an http or https URL; "${actorId}" is not one.`);
+    }
+    const number = text(options, 'wordpress-id');
+    if (number === undefined || !/^[1-9][0-9]*$/.test(number)) {
+        throw new Error('--wordpress-id is the WordPress user id, a whole positive number: it is what the ' +
+            `plugin's paths are built from, as in ${WORDPRESS_ACTIVITYPUB_BASE}/actors/2/inbox.`);
+    }
+    const { privateKeyPem, publicKeyPem } = await readKeyPair(context);
+    const report = await importWordPressActor({
+        site: context.site,
+        records,
+        username,
+        actorId,
+        wordpressActorId: Number(number),
+        privateKeyPem,
+        publicKeyPem,
+        followers: followersSource(context),
+        force: options['force'] === true,
+    });
+    context.write(importSummary(report));
+    return 0;
+}
+/**
+ * The key pair, from whichever of the two exports the owner had to hand.
+ *
+ * `--keypair` is the option the current plugin stores, one option holding
+ * both halves, and the two PEM files are what `wp user meta get` prints for a
+ * site old enough to still be on the legacy meta keys. The README says which
+ * command produces which.
+ */
+async function readKeyPair(context) {
+    const { options, cwd } = context;
+    const keypair = text(options, 'keypair');
+    const privateKey = text(options, 'private-key');
+    const publicKey = text(options, 'public-key');
+    if (keypair !== undefined) {
+        if (privateKey !== undefined) {
+            throw new Error('Pass either --keypair or --private-key, not both.');
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(await readFile(path.resolve(cwd, keypair), 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`${keypair} could not be read as the JSON "wp option get … --format=json" prints: ` +
+                `${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        const held = parsed;
+        if (typeof held?.private_key !== 'string') {
+            throw new Error(`${keypair} has no "private_key". Check what the export wrote.`);
+        }
+        return {
+            privateKeyPem: held.private_key,
+            publicKeyPem: typeof held.public_key === 'string' ? held.public_key : undefined,
+        };
+    }
+    if (privateKey === undefined) {
+        throw new Error('The key pair is missing: pass --keypair with the JSON WordPress stores, or ' +
+            '--private-key with the PEM. Without it this person could not sign anything, and ' +
+            'every follower holds the public half of the key that signs it.');
+    }
+    return {
+        privateKeyPem: await readFile(path.resolve(cwd, privateKey), 'utf8'),
+        publicKeyPem: publicKey === undefined ? undefined : await readFile(path.resolve(cwd, publicKey), 'utf8'),
+    };
+}
+/**
+ * What `--followers` means: a URL, a file resolved against the working
+ * directory, `none`, or the plugin's own collection when it was left off.
+ */
+function followersSource(context) {
+    const given = text(context.options, 'followers');
+    if (given === undefined)
+        return undefined;
+    if (given === 'none')
+        return false;
+    return isAbsoluteHttpUrl(given) ? given : path.resolve(context.cwd, given);
+}
+/** What the run did, as the operator reads it. */
+function importSummary(report) {
+    const lines = [];
+    const { followers } = report;
+    lines.push(report.changed
+        ? `Imported ${report.username} from ${report.actorId}`
+        : `Nothing to change: ${report.username} is already ${report.actorId}`);
+    lines.push(`  ids         ${report.identity === 'set' ? 'written to' : 'already in'} ` +
+        `data/users.json and the plugin's actors.json (WordPress actor ${String(report.wordpressActorId)})`);
+    for (const key of report.keys)
+        lines.push(`  key         ${key.state} ${key.file}`);
+    if (followers.source === undefined) {
+        lines.push('  followers   skipped');
+    }
+    else {
+        lines.push(`  followers   ${String(followers.added.length)} added, ` +
+            `${String(followers.refreshed.length)} refreshed, ` +
+            `${String(followers.unchanged.length)} unchanged, ` +
+            `${String(followers.failed.length)} could not be fetched ` +
+            `(${followers.source})`);
+        for (const failure of followers.failed) {
+            lines.push(`    skipped   ${failure.actor}: ${failure.reason}`);
+        }
+        if (followers.failed.length > 0) {
+            lines.push('  Those followers were left out. Run this again once their servers answer; ' +
+                'nothing already imported is touched twice.');
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** One option as the text it carries, or `undefined` when it was not given. */
+function text(options, name) {
+    const value = options[name];
+    return typeof value === 'string' ? value : undefined;
+}
+/** Whether a value is a URL a peer could fetch. */
+function isAbsoluteHttpUrl(value) {
+    const protocol = URL.parse(value)?.protocol;
+    return protocol === 'http:' || protocol === 'https:';
+}
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAI7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAG1D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,OAAyB;IACrD,OAAO;QACL,KAAK,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC;QACpC,KAAK,EACH,wJAAwJ;QAC1J,OAAO,EACL,uKAAuK;QACzK,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,UAAU;gBAChB,KAAK,EAAE,OAAO;gBACd,WAAW,EACT,mGAAmG;aACtG;YACD;gBACE,IAAI,EAAE,cAAc;gBACpB,KAAK,EAAE,KAAK;gBACZ,WAAW,EAAE,qEAAqE,0BAA0B,qBAAqB;aAClI;YACD;gBACE,IAAI,EAAE,SAAS;gBACf,KAAK,EAAE,QAAQ;gBACf,WAAW,EACT,qHAAqH;aACxH;YACD;gBACE,IAAI,EAAE,aAAa;gBACnB,KAAK,EAAE,QAAQ;gBACf,WAAW,EAAE,+CAA+C;aAC7D;YACD;gBACE,IAAI,EAAE,YAAY;gBAClB,KAAK,EAAE,QAAQ;gBACf,WAAW,EACT,0GAA0G;aAC7G;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,KAAK,EAAE,iBAAiB;gBACxB,WAAW,EACT,iHAAiH;aACpH;YACD;gBACE,IAAI,EAAE,OAAO;gBACb,WAAW,EACT,kMAAkM;aACrM;SACF;QACD,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC;KACxC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,GAAG,CAAC,OAA6B,EAAE,OAAyB;IACzE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACzB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,+EAA+E;YAC7E,yBAAyB,CAC5B,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC1C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,oFAAoF;YAClF,gFAAgF;YAChF,8EAA8E,CACjF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,6CAA6C,OAAO,eAAe,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAC7C,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,mFAAmF;YACjF,wCAAwC,0BAA0B,kBAAkB,CACvF,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC;IAEnE,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC;QACxC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO;QACP,QAAQ;QACR,OAAO;QACP,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC;QAChC,aAAa;QACb,YAAY;QACZ,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC;QACnC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI;KACjC,CAAC,CAAC;IAEH,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IACrC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,WAAW,CACxB,OAA6B;IAE7B,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IACjC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACzC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAE9C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC1E,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,yEAAyE;gBACjF,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAC7D,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,MAAgE,CAAC;QAC9E,IAAI,OAAO,IAAI,EAAE,WAAW,KAAK,QAAQ,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,qDAAqD,CAAC,CAAC;QACnF,CAAC;QACD,OAAO;YACL,aAAa,EAAE,IAAI,CAAC,WAAW;YAC/B,YAAY,EAAE,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;SAChF,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,6EAA6E;YAC3E,kFAAkF;YAClF,gEAAgE,CACnE,CAAC;IACJ,CAAC;IAED,OAAO;QACL,aAAa,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpE,YAAY,EACV,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,OAA6B;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACjD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED,kDAAkD;AAClD,SAAS,aAAa,CAAC,MAAkC;IACvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAE7B,KAAK,CAAC,IAAI,CACR,MAAM,CAAC,OAAO;QACZ,CAAC,CAAC,YAAY,MAAM,CAAC,QAAQ,SAAS,MAAM,CAAC,OAAO,EAAE;QACtD,CAAC,CAAC,sBAAsB,MAAM,CAAC,QAAQ,eAAe,MAAM,CAAC,OAAO,EAAE,CACzE,CAAC;IACF,KAAK,CAAC,IAAI,CACR,iBAAiB,MAAM,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,GAAG;QACzE,iEAAiE,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,GAAG,CACtG,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAEpF,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACtC,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CACR,iBAAiB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU;YACvD,GAAG,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,cAAc;YACnD,GAAG,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,cAAc;YACnD,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,wBAAwB;YAC1D,IAAI,SAAS,CAAC,MAAM,GAAG,CAC1B,CAAC;QACF,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,iBAAiB,OAAO,CAAC,KAAK,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CACR,6EAA6E;gBAC3E,4CAA4C,CAC/C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,+EAA+E;AAC/E,SAAS,IAAI,CAAC,OAAgD,EAAE,IAAY;IAC1E,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,mDAAmD;AACnD,SAAS,iBAAiB,CAAC,KAAa;IACtC,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC5C,OAAO,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,QAAQ,CAAC;AACvD,CAAC"}

package/dist/federation.d.ts

@@ -0,0 +1,30 @@
+import type { PluginFederationMiddleware } from '@geekity/cms/plugin';
+import type { WordPressRecords } from './records.ts';
+/**
+ * The WordPress ActivityPub plugin's paths, served while this plugin is
+ * enabled (TASK-70, TASK-282).
+ *
+ * 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 site carries the plugin's layout until the caches have
+ * moved on, and then the plugin is disabled.
+ *
+ * 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.
+ *
+ * A Fedify federation of the plugin's own is how a second inbox path gets
+ * signature verification at all: one federation has exactly one pair of inbox
+ * listeners (doc-8). It shares the site federation's KV store and is set to
+ * `per-origin` idempotence, as the canonical inbox is, so one `Follow`
+ * redelivered to `andrew`'s inbox and to `2`'s is handled once.
+ *
+ * Every document crosses from the site as JSON-LD and is parsed here with
+ * this plugin's own vocabulary, because a bundled plugin carries its own copy
+ * of Fedify and the site's objects are not instances of this copy's classes.
+ */
+export declare function wordPressFederation(records: WordPressRecords): PluginFederationMiddleware;
+//# sourceMappingURL=federation.d.ts.map

package/dist/federation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../src/federation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,0BAA0B,EAC3B,MAAM,qBAAqB,CAAC;AAW7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,0BAA0B,CA8BzF"}

package/dist/federation.js

@@ -0,0 +1,162 @@
+import { createFederation } from '@fedify/fedify';
+import { Activity, Create, Person } from '@fedify/vocab';
+import { WORDPRESS_ACTOR_PATH, WORDPRESS_FOLLOWERS_PATH, WORDPRESS_FOLLOWING_PATH, WORDPRESS_INBOX_PATH, WORDPRESS_OUTBOX_PATH, WORDPRESS_SHARED_INBOX_PATH, wordPressRequestTarget, } from './records.js';
+/**
+ * The WordPress ActivityPub plugin's paths, served while this plugin is
+ * enabled (TASK-70, TASK-282).
+ *
+ * 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 site carries the plugin's layout until the caches have
+ * moved on, and then the plugin is disabled.
+ *
+ * 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.
+ *
+ * A Fedify federation of the plugin's own is how a second inbox path gets
+ * signature verification at all: one federation has exactly one pair of inbox
+ * listeners (doc-8). It shares the site federation's KV store and is set to
+ * `per-origin` idempotence, as the canonical inbox is, so one `Follow`
+ * redelivered to `andrew`'s inbox and to `2`'s is handled once.
+ *
+ * Every document crosses from the site as JSON-LD and is parsed here with
+ * this plugin's own vocabulary, because a bundled plugin carries its own copy
+ * of Fedify and the site's objects are not instances of this copy's classes.
+ */
+export function wordPressFederation(records) {
+    let federation;
+    return async (context, next) => {
+        const target = wordPressRequestTarget(new URL(context.request.url).pathname);
+        if (target === undefined)
+            return await next();
+        await records.recordRequest({
+            target,
+            username: target.wordpressActorId === undefined
+                ? undefined
+                : records.userByNumber(context.site, target.wordpressActorId),
+            at: context.now(),
+        });
+        federation ??= build(context, records);
+        return await federation.fetch(context.request, {
+            contextData: context,
+            onNotFound: next,
+            async onNotAcceptable() {
+                const response = await next();
+                if (response.status !== 404)
+                    return response;
+                return new Response('Not acceptable', {
+                    status: 406,
+                    headers: { 'content-type': 'text/plain', vary: 'Accept' },
+                });
+            },
+        });
+    };
+}
+/**
+ * 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 site.
+ */
+function build(first, records) {
+    const federation = createFederation({
+        kv: first.kv,
+        origin: new URL(first.site.baseUrl).origin,
+        allowPrivateAddress: first.allowPrivateAddress,
+    });
+    /**
+     * The username behind the identifier in a path Fedify matched, which on the
+     * plugin's paths is the number WordPress gave the user.
+     */
+    function usernameOfWordPressNumber(context, wordpressNumber) {
+        return records.userByNumber(context.data.site, wordpressNumber);
+    }
+    /** What parsing a document from the site with this copy's vocabulary needs. */
+    function loaders(context) {
+        return { documentLoader: context.documentLoader, contextLoader: context.contextLoader };
+    }
+    federation
+        .setActorDispatcher(WORDPRESS_ACTOR_PATH, async (context, identifier) => {
+        const username = usernameOfWordPressNumber(context, identifier);
+        if (username === undefined)
+            return null;
+        const actor = await context.data.actor(username);
+        return actor === undefined ? null : await Person.fromJsonLd(actor, loaders(context));
+    })
+        .setKeyPairsDispatcher(async (context, identifier) => {
+        const username = usernameOfWordPressNumber(context, identifier);
+        return username === undefined ? [] : await context.data.keyPairs(username);
+    });
+    federation
+        .setOutboxDispatcher(WORDPRESS_OUTBOX_PATH, async (context, identifier, cursor) => {
+        const username = usernameOfWordPressNumber(context, identifier);
+        const outbox = username === undefined ? undefined : context.data.outbox(username);
+        if (outbox === undefined)
+            return null;
+        const page = await outbox.page(cursor);
+        return {
+            items: await Promise.all(page.items.map((item) => Create.fromJsonLd(item, loaders(context)))),
+            nextCursor: page.nextCursor,
+            prevCursor: page.prevCursor,
+        };
+    })
+        .setCounter((context, identifier) => {
+        const username = usernameOfWordPressNumber(context, identifier);
+        return username === undefined ? null : (context.data.outbox(username)?.totalItems ?? null);
+    })
+        .setFirstCursor((context, identifier) => {
+        const username = usernameOfWordPressNumber(context, identifier);
+        return username === undefined ? null : (context.data.outbox(username)?.firstCursor ?? null);
+    })
+        .setLastCursor((context, identifier) => {
+        const username = usernameOfWordPressNumber(context, identifier);
+        return username === undefined ? null : (context.data.outbox(username)?.lastCursor ?? null);
+    });
+    federation
+        .setFollowersDispatcher(WORDPRESS_FOLLOWERS_PATH, async (context, identifier, cursor) => {
+        const username = usernameOfWordPressNumber(context, identifier);
+        const followers = username === undefined ? undefined : context.data.followers(username);
+        if (followers === undefined)
+            return null;
+        const page = await followers.page(cursor);
+        return {
+            items: page.items.map((recipient) => ({
+                id: new URL(recipient.id),
+                inboxId: new URL(recipient.inboxId),
+                endpoints: {
+                    sharedInbox: recipient.sharedInboxId === null ? null : new URL(recipient.sharedInboxId),
+                },
+            })),
+            nextCursor: page.nextCursor,
+            prevCursor: page.prevCursor,
+        };
+    })
+        .setCounter((context, identifier) => {
+        const username = usernameOfWordPressNumber(context, identifier);
+        return username === undefined ? null : (context.data.followers(username)?.totalItems ?? null);
+    })
+        .setFirstCursor((context, identifier) => {
+        const username = usernameOfWordPressNumber(context, identifier);
+        return username === undefined
+            ? null
+            : (context.data.followers(username)?.firstCursor ?? null);
+    })
+        .setLastCursor((context, identifier) => {
+        const username = usernameOfWordPressNumber(context, identifier);
+        return username === undefined ? null : (context.data.followers(username)?.lastCursor ?? null);
+    });
+    federation.setFollowingDispatcher(WORDPRESS_FOLLOWING_PATH, (context, identifier) => usernameOfWordPressNumber(context, identifier) === undefined ? null : { items: [] });
+    federation
+        .setInboxListeners(WORDPRESS_INBOX_PATH, WORDPRESS_SHARED_INBOX_PATH)
+        .withIdempotency('per-origin')
+        .on(Activity, async (context, activity) => {
+        const wordpressNumber = context.recipient;
+        const recipient = wordpressNumber === null ? undefined : usernameOfWordPressNumber(context, wordpressNumber);
+        await context.data.receive((await activity.toJsonLd()), recipient ?? null);
+    });
+    return federation;
+}
+//# sourceMappingURL=federation.js.map

package/dist/federation.js.map

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

package/dist/import.d.ts

@@ -0,0 +1,123 @@
+import type { PluginKeyAlgorithm, PluginSite } from '@geekity/cms/plugin';
+import type { WordPressRecords } from './records.ts';
+/** What {@link importWordPressActor} is given. */
+export interface ImportWordPressActorOptions {
+    /** The site the person arrives on. */
+    readonly site: PluginSite;
+    /** Where the plugin keeps each person's WordPress number. */
+    readonly records: WordPressRecords;
+    /** Which account on this site the plugin's actor becomes. */
+    readonly username: string;
+    /**
+     * The actor's id exactly as WordPress published it, query string and all:
+     * `https://example.com/?author=2`.
+     */
+    readonly actorId: string;
+    /** The WordPress user id, which is the number in every one of its paths. */
+    readonly wordpressActorId: number;
+    /** The private key as PEM, PKCS#1 or PKCS#8, as `wp` printed it. */
+    readonly privateKeyPem: string;
+    /**
+     * The public key as PEM, when the export carried one.
+     *
+     * Checked against the private half rather than stored: the public key is
+     * derivable, so the only thing a second file can tell us is whether the two
+     * halves of the export belong together — and a pair that does not is an
+     * export somebody got wrong, which is worth finding out now rather than
+     * after the DNS has moved.
+     */
+    readonly publicKeyPem?: string | undefined;
+    /**
+     * Where the followers come from.
+     *
+     * Left off, the plugin's public followers collection on the actor id's own
+     * origin, which is the whole point of running this before the DNS moves. A
+     * URL asks a different one; a path reads a saved collection out of a file,
+     * for a site that is already gone; `false` skips the step, for a run that is
+     * only there to put the key and the ids in place.
+     */
+    readonly followers?: string | false | undefined;
+    /** Replace a key pair this user already has. Refused without it. */
+    readonly force?: boolean | undefined;
+}
+/** What happened to one key file. */
+export interface ImportedKey {
+    /** The file, absolute. */
+    readonly file: string;
+    /** Which pair it holds. */
+    readonly algorithm: PluginKeyAlgorithm;
+    /** What the run did with it. */
+    readonly state: 'imported' | 'generated' | 'unchanged' | 'replaced';
+}
+/** One follower the collection named and nothing could be made of. */
+export interface UnreachableFollower {
+    /** The actor the collection named. */
+    readonly actor: string;
+    /** Why it was skipped, for the report. */
+    readonly reason: string;
+}
+/** What the followers step did. */
+export interface FollowersImportReport {
+    /** The collection it read, or `undefined` when the step was skipped. */
+    readonly source: string | undefined;
+    /** Actors written into the file for the first time. */
+    readonly added: readonly string[];
+    /** Actors the file already held, with nothing about them changed. */
+    readonly unchanged: readonly string[];
+    /** Actors whose profile the file held and this run refreshed. */
+    readonly refreshed: readonly string[];
+    /**
+     * Actors that could not be turned into followers, and why.
+     *
+     * Reported rather than fatal: an instance that is down, or an account that
+     * has been deleted, must not stop the other hundred followers from coming
+     * across, and the owner can run the command again once it is back.
+     */
+    readonly failed: readonly UnreachableFollower[];
+}
+/** What the run did. */
+export interface ImportWordPressActorReport {
+    /** Who was imported. */
+    readonly username: string;
+    /** The id their followers hold. */
+    readonly actorId: string;
+    /** The number the plugin's paths are built from. */
+    readonly wordpressActorId: number;
+    /**
+     * Whether the two ids had to be written, or the record already said so.
+     */
+    readonly identity: 'set' | 'unchanged';
+    /** One entry per key file, RSA first, as the key loader orders them. */
+    readonly keys: readonly ImportedKey[];
+    /** What came of the followers collection. */
+    readonly followers: FollowersImportReport;
+    /** Whether anything on disk is different because of this run. */
+    readonly changed: boolean;
+}
+/**
+ * Thrown when the user already has a key pair and this run was not told to
+ * replace it.
+ *
+ * Its own class because the answer is a flag rather than a correction, and
+ * because losing a private key is the one mistake this CMS cannot help with:
+ * every follower's server has cached the public half, and a new key means none
+ * of them can verify this person again.
+ */
+export declare class ExistingKeyPairError extends Error {
+    readonly name = "ExistingKeyPairError";
+    /** The file that is already there. */
+    readonly file: string;
+    constructor(username: string, file: string);
+}
+/** Thrown when the PEM is not an RSA private key at all. */
+export declare class UnusableKeyPemError extends Error {
+    readonly name = "UnusableKeyPemError";
+}
+/**
+ * Bring one WordPress actor's key pair across, and say what changed.
+ *
+ * Run twice with the same inputs it changes nothing and says so, which is what
+ * makes it safe to run again after a follower's server was down.
+ */
+export declare function importWordPressActor(options: ImportWordPressActorOptions): Promise<ImportWordPressActorReport>;
+//# sourceMappingURL=import.d.ts.map

package/dist/import.d.ts.map

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