Integrate bluesky: 16 plugins, 151 tests

- compose.test.js + serve.js load all 16 (appPaths widened to
  /api,/oauth,/xrpc); 17-check compose.
- README/ISSUES tables updated; tally now 10 built as plugins.
- NOTES: the multi-prefix finding upgraded to TWO independent
  confirmations (mastodon + bluesky, separate shims) and renamed the seam
  api.reservePath() — bluesky needs only ONE fixed root and still can't
  self-exempt it, so the ask is 'declare owned paths independent of the
  mount prefix', now the #3 most-demanded seam after api.authorize and
  api.events.

Author: melvincarvalho

ISSUES.md

@@ -26,6 +26,7 @@ evidence. Legend:
 | #515 / #516 | `mastodon/` | Mastodon-API shim — a client can log into its own pod (needs `appPaths` widened → 🔩) |
 | #505 | `otp/` | one-time-password session flow (account *recovery* → 🔩 core auth) |
 | #157 | `carddav/` | CardDAV contact sync (iOS/macOS/Thunderbird/DAVx5) |
+| #211 | `bluesky/` | AT-Protocol XRPC shim — a client logs into its own pod (needs `appPaths` widened → 🔩) |
 
 Plus six **ports of bundled features** proving the migration path for #564 /
 #164: `relay/` `webrtc/` `terminal/` `tunnel/` `notifications/`, and `pay/`
@@ -45,7 +46,6 @@ Plus six **ports of bundled features** proving the migration path for #564 /
 
 | Issue | Shape |
 |---|---|
-| #211 | Bluesky / AT-Protocol shim — same shape as `mastodon/`, different wire format |
 | #527 | Tunnel client mode — extends `tunnel/` to dial *out* to a relay |
 | #277 | MongoDB-backed relay — `relay/` with a Mongo store (needs the infra) |
 
@@ -58,7 +58,7 @@ Each names the seam and the consumer that proves it. Ranked in
 |---|---|
 | #509 (write-index), #501 | `api.events.onResourceChange` — react to pod writes |
 | #382 (per-pod ACL), #506 (pod grants) | `api.authorize(request, path, mode)` — ask the host's WAC |
-| #515/#516 (fixed roots), #211 | `api.appPaths.add()` / multi-prefix — an API-shim owns roots outside one prefix and can't self-exempt them from WAC |
+| #515/#516, #211 (both built, but need operator `appPaths`) | `api.reservePath()` — an API-shim owns fixed roots outside its prefix and can't self-exempt them from WAC; **two independent confirmations** |
 | #505 (recovery) | `api.auth.mintSession` / `api.identity.addAuthKey` — turn a proven channel into pod authority |
 | #495 #496 #500 #501 | `api.mcp.registerTool` — MCP has no plugin-tool seam; all four MCP issues want new tools a plugin can't add today |
 | #463 #464 | app-registry primitive — surfacing installed plugins as Solid resources |
@@ -87,8 +87,8 @@ exists.
 
 ## Tally
 
-Of ~40 plugin-tagged issues: **9 built as plugins here**, **6 ported**, **5
-shipped upstream**, **3 more plugin-able with no blocker**, **6 clusters
+Of ~40 plugin-tagged issues: **10 built as plugins here**, **6 ported**, **5
+shipped upstream**, **2 more plugin-able with no blocker**, **6 clusters
 blocked on a named seam** (each with a proof-of-need consumer), the rest
 core-by-nature or product-scale. The plugin api reaches most of the backlog
 today; ranked by how many independent plugins demanded them, the seams that

NOTES.md

@@ -64,17 +64,22 @@ ports reached for it without coordinating.
    `appPaths`). Consequences, in increasing severity:
    - nip05/webdav/carddav land on `/.well-known/*`, which core *happens* to
      blanket-exempt — so they work **by luck**, not by contract.
-   - mastodon needs `/api` **and** `/oauth`, which core does **not** exempt,
-     so **the plugin cannot serve its own surface** — every call 401s at the
-     WAC hook until the operator hand-passes `appPaths: ['/api','/oauth']`.
-     A plugin has no `api.appPaths.add()` to fix this itself.
+   - **mastodon** needs `/api` **and** `/oauth`, and **bluesky** needs
+     `/xrpc` — none of which core exempts, so **the plugin cannot serve its
+     own surface**: every call 401s at the WAC hook until the operator
+     hand-passes `appPaths: ['/api','/oauth','/xrpc']`. A plugin has no way
+     to exempt a path it owns. **Two independent confirmations** (two
+     protocol shims, built separately), and bluesky sharpens it: it needs
+     only *one* extra root and still can't reach it, so the seam is not
+     "more prefixes" but **"a plugin declares the paths it owns,
+     independent of its mount prefix."**
    - none of it has conflict detection: a future core route at a
      plugin-claimed path throws `FST_ERR_DUPLICATED_ROUTE` at boot.
-   The seam: entries declare the paths they own (`paths: ['/api','/oauth']`
-   or a plural `prefix`), the loader exempts and claims them deliberately
-   and reports collisions. This is the seam **API-shim plugins**
-   (mastodon, and any future Bluesky/ActivityPub/gateway) structurally
-   require.
+   The seam: `api.reservePath('/xrpc')` (or `paths: [...]` in the entry) —
+   the loader exempts *and* claims each deliberately and reports collisions.
+   This is the seam **every API-shim plugin** (mastodon, bluesky, and any
+   future ActivityPub/Matrix/gateway) structurally requires; it's the third
+   most-demanded after `api.authorize` and `api.events`.
 6. **Can't set fastify server options** — consumer: capability/ hit
    `maxParamLength` (100) silently 404ing long tokens in named params;
    workaround is a wildcard route. A plugin has no way to raise per-route

README.md

@@ -64,9 +64,10 @@ README and NOTES.md, ship the closest honest approximation.
 | `otp/` | #505 | one-time-password session flow; account recovery needs core auth |
 | `carddav/` | #157 | contact sync (iOS/macOS/Thunderbird/DAVx5); the DAV bridge, generalized |
 | `mastodon/` | #515/#516 | Mastodon-API shim — a client logs into its own pod; needs `appPaths` widened |
+| `bluesky/` | #211 | AT-Protocol XRPC shim — same shape, `/xrpc` root; token bridge generalizes |
 
-**~130 tests, all green** (`npm test`), including `compose.test.js` — all
-fifteen plugins on one server from pure config, pods + WAC intact beside
+**~150 tests, all green** (`npm test`), including `compose.test.js` — all
+sixteen plugins on one server from pure config, pods + WAC intact beside
 them. Findings consolidated in [NOTES.md](./NOTES.md); the full
 plugin-tagged backlog triaged in [ISSUES.md](./ISSUES.md).
 

compose.test.js

@@ -46,7 +46,7 @@ describe('composition: every plugin on one server', () => {
 
   after(async () => { if (jss) await jss.close(); });
 
-  it('boots pods + idp + fifteen plugins from config', async () => {
+  it('boots pods + idp + sixteen plugins from config', async () => {
     const port = await probePort();
     base = `http://127.0.0.1:${port}`;
     wsBase = `ws://127.0.0.1:${port}`;
@@ -55,9 +55,10 @@ describe('composition: every plugin on one server', () => {
       port,
       root,
       idp: true,
-      // mastodon owns fixed roots outside its prefix; a plugin can't
-      // self-exempt them (finding), so the operator widens appPaths.
-      appPaths: ['/api', '/oauth'],
+      // mastodon (/api,/oauth) and bluesky (/xrpc) own fixed roots outside
+      // their prefix; a plugin can't self-exempt them (finding), so the
+      // operator widens appPaths.
+      appPaths: ['/api', '/oauth', '/xrpc'],
       // Explicit ids: the <name>/plugin.js convention makes every basename
       // reduce to 'plugin' — the loader's duplicate-id guard requires ids
       // here (finding: derive from the parent dir for generic basenames).
@@ -82,6 +83,7 @@ describe('composition: every plugin on one server', () => {
         { id: 'otp', module: at('otp/plugin.js'), prefix: '/otp', config: {} },
         { id: 'carddav', module: at('carddav/plugin.js'), prefix: '/carddav', config: { baseUrl: base, loopbackUrl: base } },
         { id: 'mastodon', module: at('mastodon/plugin.js'), prefix: '/mastodon', config: { baseUrl: base, loopbackUrl: base } },
+        { id: 'bluesky', module: at('bluesky/plugin.js'), prefix: '/bluesky', config: { baseUrl: base, loopbackUrl: base } },
       ],
     });
     assert.ok(jss.base);
@@ -215,6 +217,11 @@ describe('composition: every plugin on one server', () => {
     assert.ok('title' in (await res.json()));
   });
 
+  it('bluesky: the XRPC describeServer answers (fixed /xrpc root)', async () => {
+    const res = await fetch(`${base}/xrpc/com.atproto.server.describeServer`);
+    assert.strictEqual(res.status, 200);
+  });
+
   it('pods still work beside all of it (idp register + WAC)', async () => {
     let res = await fetch(`${base}/idp/register`, {
       method: 'POST',

serve.js

@@ -28,9 +28,10 @@ const fastify = createServer({
   root: PODS,
   idp: true,
   idpIssuer: PUBLIC_URL,
-  // mastodon owns fixed roots (/api, /oauth) outside its prefix; a plugin
-  // can't self-exempt them from WAC, so the operator widens appPaths.
-  appPaths: ['/api', '/oauth'],
+  // mastodon (/api,/oauth) and bluesky (/xrpc) own fixed roots outside
+  // their prefix; a plugin can't self-exempt them from WAC, so the
+  // operator widens appPaths.
+  appPaths: ['/api', '/oauth', '/xrpc'],
   // Explicit ids — the <name>/plugin.js convention collides on basename.
   plugins: [
     { id: 'relay', module: at('relay/plugin.js'), prefix: '/relay' },
@@ -53,6 +54,7 @@ const fastify = createServer({
     { id: 'otp', module: at('otp/plugin.js'), prefix: '/otp', config: {} },
     { id: 'carddav', module: at('carddav/plugin.js'), prefix: '/carddav', config: { baseUrl: PUBLIC_URL, loopbackUrl: `http://127.0.0.1:${PORT}` } },
     { id: 'mastodon', module: at('mastodon/plugin.js'), prefix: '/mastodon', config: { baseUrl: PUBLIC_URL, loopbackUrl: `http://127.0.0.1:${PORT}` } },
+    { id: 'bluesky', module: at('bluesky/plugin.js'), prefix: '/bluesky', config: { baseUrl: PUBLIC_URL, loopbackUrl: `http://127.0.0.1:${PORT}` } },
   ],
 });
 
@@ -81,3 +83,4 @@ console.log(`  sparql:         POST ${PUBLIC_URL}/sparql  (auth)`);
 console.log(`  otp:            POST ${PUBLIC_URL}/otp/request`);
 console.log(`  carddav:        ${PUBLIC_URL}/carddav/  (contact sync)`);
 console.log(`  mastodon:       GET ${PUBLIC_URL}/api/v1/instance  (point a client here)`);
+console.log(`  bluesky:        GET ${PUBLIC_URL}/xrpc/com.atproto.server.describeServer`);