fedipod-server 0.28.1 → 0.29.0

package/README.md

@@ -30,13 +30,12 @@ before installing: a server that does not meet them cannot offer accounts, and
 sign-up refuses rather than half-working.
 
 - **Community Solid Server 7.**
-- **Pods on subdomains or on paths.** A subdomain pod answers on its own
-  address (`@mei@mei.example.org`); a suffix pod on a path of the server's own
-  host answers under that path, and the server fronts it so its address is the
-  server's host (`@aisha@server.example`, for a pod at
-  `https://server.example/aisha/`). Either works — a suffix pod cannot resolve
-  its own handle, so it is followable only through the server's apex, which the
-  server also runs.
+- **Subdomained or suffixed pods.** A subdomained pod answers on its own
+  address (`@mei@mei.example.org`); a suffixed pod answers under its path, and
+  the server fronts it so its address is the server's host
+  (`@aisha@server.example`, for a pod at `https://server.example/aisha/`).
+  Either works — a suffixed pod cannot resolve its own handle, so it is
+  followable only through the server's apex, which the server also runs.
 - **A single worker.** Run the server as one copy of itself — `--workers 1`,
   which is the default. With more, it still serves pods normally, but no pod
   can be an account: sign-up is refused, and an account set up earlier goes on
@@ -70,8 +69,8 @@ Add the package context to your CSS config and import the shipped snippet:
 
 Then set what you need on the `urn:fedipod:server:Handler` node and restart
 the server.
-A subdomain-pods CSS config gives each identity an origin of its own; a
-suffix (path) config hosts each on a path of the shared host. Both opt in.
+A CSS config with subdomained pods gives each identity an origin of its own;
+one with suffixed pods hosts each under its own path. Both opt in.
  The snippet places the component in the routing waterfall ahead of
 the LDP catch-all, on the initializer and finalizer lists so identities start
 and stop with the server, and on the websocket handler list for the live feed.
@@ -88,9 +87,9 @@ and stop with the server, and on the websocket handler list for the live feed.
 ```
 
 An identity is provisioned when its owner opts in: its name is the pod's
-subdomain label, or its last path segment on a suffix pod, and it publishes an
+subdomain label, or its last path segment on a suffixed pod, and it publishes an
 actor and a signing key on the pod itself. Its handle resolves on the pod for a
-subdomain, and through the server's apex for a suffix pod. Everything it is made of lives on its pod — its state, its private
+subdomained pod, and through the server's apex for a suffixed pod. Everything it is made of lives on its pod — its state, its private
 signing key, the secret guarding its own pages, and the credentials for any
 accounts its owner connects on other servers. Each identity has its own
 secret; one owner's opens nobody else's door. The opt-in reply is where the
@@ -108,7 +107,7 @@ naming the pod the identity runs on. Nothing private is in it.
 |---|---|
 | `agentRuntimeOptIn` | Whether pod owners can sign up. With it off, nothing runs. |
 | `agentDataDir` | Where each identity keeps the file naming its pod; its log lines go to the server's own log. Required whenever sign-up is on. |
-| `agentUiPath` | Where the owner's pages live on the pod's origin. `/fp/` by default; empty serves no pages. On a suffix pod it is under the pod's path, e.g. `/aisha/fp/`. |
+| `agentUiPath` | Where the owner's pages live on the pod's origin. `/fp/` by default; empty serves no pages. On a suffixed pod it is under the pod's path, e.g. `/aisha/fp/`. |
 | `agentRegistryContainer` | The internal container holding the sign-up rows. |
 | `runPage` | The HTML of the page where a pod owner opts in or out. The package's own `web/front/run.html` is served unless you set this. |
 | `runPath` | Where that page answers. `/.fediverse-account` unless you set it. The path it takes is one the pod no longer serves, so it is yours to name; the dot keeps it out of the way of anybody's data. |
@@ -155,11 +154,11 @@ that document's address and registers nothing here. Once in, it posts to the
 outbox the actor names, and reads what the identity received at `/ap/inbox`,
 which nobody but the owner may read.
 
-A subdomain pod gets an origin of its own and answers at its root; a suffix
-pod shares the host and answers under its own path (`/aisha/ap/actor`,
-`/aisha/api/…`, `/aisha/oauth/…`, its door at `/aisha/fp/`). So a host carries
-at most one root identity, but any number of path pods beside it; a second
-root identity on a host, or a path pod nesting under another, is refused at
+A subdomained pod gets an origin of its own and answers at its root; a
+suffixed pod answers under its own path (`/aisha/ap/actor`, `/aisha/api/…`,
+`/aisha/oauth/…`, its door at `/aisha/fp/`). So a host carries at most one
+root identity, but any number of suffixed pods beside it; a second root
+identity on a host, or a suffixed pod nesting under another, is refused at
 opt-in rather than half-working.
 
 ### Before you turn it on
@@ -173,22 +172,22 @@ for anyone hosting other people, it is a promise being made to them.
 owner's door, with that identity's own door secret:
 
 ```
-# subdomain pod:
+# subdomained pod:
 curl -X POST https://mei.example.org/fp/config \
   -H 'x-dk-token: THE_DOOR_SECRET_FROM_THE_OPT_IN_REPLY' -H 'content-type: application/json' \
   -d '{"password":"the one you will type into your phone"}'
-# suffix pod — the door is under the pod's path:
+# suffixed pod — the door is under the pod's path:
 curl -X POST https://server.example/aisha/fp/config \
   -H 'x-dk-token: THE_DOOR_SECRET_FROM_THE_OPT_IN_REPLY' -H 'content-type: application/json' \
   -d '{"password":"the one you will type into your phone"}'
 ```
 
-**Some pod paths stop being served.** On a subdomain pod the paths above
+**Some pod paths stop being served.** On a subdomained pod the paths above
 belong to the identity, so pod resources at those names — a container called
 `api`, `oauth` or `fp`, or documents at `ap/actor`, `ap/outbox`,
 `ap/inbox`, `.well-known/oauth-authorization-server`,
 `.well-known/nodeinfo` and `nodeinfo/2.0` — are not served over HTTP there.
-On a suffix pod the same names are taken under the pod's own path
+On a suffixed pod the same names are taken under the pod's own path
 (`/aisha/api/…`, `/aisha/ap/actor`, `/aisha/fp/`, and so on); the rest of the
 path, and every other pod on the host, is untouched.
 They stay in the pod and in its listings. Every other path is the pod, exactly
@@ -245,8 +244,8 @@ TypeScript, built the way CSS builds its own components.
 npm install
 npm run build       # tsc → dist, then componentsjs-generator → dist/components
 npm test            # unit tests, plus the transport against a real CSS store
-npm run test:e2e    # boots a real server (subdomain pods) and uses it as a client would
-npm run test:e2e:suffix   # the same, for pods on paths of one host (mode d)
+npm run test:e2e    # boots a real server (subdomained pods) and uses it as a client would
+npm run test:e2e:suffix   # the same, for suffixed pods (mode d)
 ```
 
 `npm test` drives a genuine CSS store stack — ETags, conditional writes,
@@ -259,11 +258,11 @@ lease protocol and the deletion deny-list still hold across it.
 become identities up front; the third opts in and out at runtime), then signs in as a phone app does, posts,
 receives a follow from another server, and watches the live feed. It takes
 about a minute. `FEDIPOD_E2E_LOG=info` shows the server's log while it runs.
-`npm run test:e2e:suffix` does the same on a server whose pods live on paths of
-one host (`@aisha@server`): it proves the apex WebFinger resolves straight to
-the pod actor, that the actor, inbox, client API, OAuth and door all answer
-under the pod's path, that two path pods on one origin stay separate, and that
-a signed delivery is verified at the pod's own door.
+`npm run test:e2e:suffix` does the same on a server whose pods are suffixed
+(`@aisha@server`): it proves the apex WebFinger resolves straight to the pod
+actor, that the actor, inbox, client API, OAuth and door all answer under the
+pod's path, that two suffixed pods on one origin stay separate, and that a
+signed delivery is verified at the pod's own door.
 
 `dist/` and `node_modules/` are gitignored; `src/`, `config/` and this file are
 the sources.

package/config/server.json

@@ -60,6 +60,28 @@
         }
       ]
     },
+    {
+      "comment": "ActivityStreams documents are stored as application/activity+json. The spec asks a server to answer application/ld+json with the ActivityStreams profile for them too, and CSS alone refuses that form with 501. This relabels the one type as the other, both ways, without touching the bytes, so either Accept reads the same document.",
+      "@id": "urn:fedipod:server:ActivityStreamsReplacer",
+      "@type": "ContentTypeReplacer",
+      "replacements": [
+        { "ContentTypeReplacer:_replacements_key": "application/activity+json", "ContentTypeReplacer:_replacements_value": "application/ld+json" },
+        { "ContentTypeReplacer:_replacements_key": "application/ld+json", "ContentTypeReplacer:_replacements_value": "application/activity+json" }
+      ]
+    },
+    {
+      "comment": "The replacer goes first in the converter chain, before CSS's own ContentTypeReplacer.",
+      "@type": "Override",
+      "overrideInstance": { "@id": "urn:solid-server:default:ChainedConverter" },
+      "overrideSteps": [
+        {
+          "@type": "OverrideListInsertBefore",
+          "overrideParameter": { "@id": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^7.0.0/dist/storage/conversion/ChainedConverter.jsonld#ChainedConverter_converters" },
+          "overrideTarget": { "@id": "urn:solid-server:default:ContentTypeReplacer" },
+          "overrideValue": { "@id": "urn:fedipod:server:ActivityStreamsReplacer" }
+        }
+      ]
+    },
     {
       "comment": "Insert the handler into the routing waterfall just before the LDP catch-all, so it claims only the front routes and everything else stays normal CSS. OverrideListInsertBefore is available in componentsjs 5.x (which CSS 7 uses).",
       "@type": "Override",

package/dist/claims.js

@@ -51,11 +51,12 @@ const AGENT_PATHS = new Set([
 ]);
 const AGENT_PREFIXES = ['/api/', '/oauth/', '/@']; // /@handle: the short profile address
 // An identity's inbox is the container `/<root>/ap/inbox/`, matched by shape
-// rather than a fixed root. A POST here is a delivery, verified at the door
+// rather than a fixed root — and the root may be nested, wherever its owner put
+// the `fedipod/` container. A POST here is a delivery, verified at the door
 // before it is written; the handler checks the exact path per identity. The
 // path is relative to the identity's mount (see agentClaims), so a suffix pod's
 // `/aisha/fedipod/ap/inbox/` arrives here already stripped to `/fedipod/ap/inbox/`.
-const isInboxPath = (pathname) => /^\/[^/]+\/ap\/inbox\/$/u.test(pathname);
+const isInboxPath = (pathname) => /^\/(?:[^/]+\/)+ap\/inbox\/$/u.test(pathname);
 exports.isInboxPath = isInboxPath;
 /**
  * True when this path belongs to an identity's client surface.

package/dist/directory.d.ts

@@ -38,6 +38,8 @@ export interface AgentRegistryRecord {
     host: string;
     webId: string;
     optedInAt: string;
+    /** Where on the pod the account lives, relative to it; absent on older rows, which are at fedipod/. */
+    root?: string;
 }
 /**
  * The registry key for an opted-in pod: its host plus its path. Several pods

package/dist/handler.d.ts

@@ -70,6 +70,7 @@ export declare class FediPodServerHandler extends HttpHandler implements Initial
     private readonly logger;
     private readonly claimed;
     private readonly agentHandles;
+    private readonly roots;
     private readonly frontHost;
     private readonly uiPath;
     private readonly identities;
@@ -164,9 +165,11 @@ export declare class FediPodServerHandler extends HttpHandler implements Initial
             get(name: string): string | null;
         };
     }): Promise<string[]>;
-    optInPod({ podBase, webId }: {
+    optInPod({ podBase, webId, container, createIndex }: {
         podBase: string;
         webId: string;
+        container?: string;
+        createIndex?: boolean;
     }): Promise<Record<string, unknown> & {
         httpStatus: number;
     }>;

package/dist/handler.js

@@ -36,6 +36,8 @@ function pathContains(a, b) {
 const LIB_ROOT = (0, node_fs_1.existsSync)((0, node_path_1.join)(__dirname, '../lib/server/embed.mjs')) ? '../lib' : '../../../lib';
 const FRONT_CORE = `${LIB_ROOT}/gateway/front-core.mjs`;
 const EMBED = `${LIB_ROOT}/server/embed.mjs`;
+const PLACE = `${LIB_ROOT}/core/place.mjs`;
+const TRANSPORT = `${LIB_ROOT}/pod/transport.mjs`;
 const esmImport = new Function('s', 'return import(s)');
 // The front's pages and the files they load, carried in the same two layouts
 // as lib/. A missing file is not fatal: the route it feeds answers 404.
@@ -86,6 +88,7 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
     // request is matched to an identity by host AND mount, never host alone.
     claimed = new Map(); // pod base → claim
     agentHandles = new Map(); // handle → pod base
+    roots = new Map(); // pod base → where on it the account lives
     frontHost;
     uiPath;
     identities = new Map();
@@ -165,7 +168,7 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
                 if (c.host !== host)
                     continue;
                 if (pathContains(c.mount, mount) || pathContains(mount, c.mount)) {
-                    throw new Error(`${podBase} nests with the identity already at ${c.podBase} — a path pod owns only its own subtree`);
+                    throw new Error(`${podBase} nests with the identity already at ${c.podBase} — a suffixed pod owns only its own subtree`);
                 }
             }
         }
@@ -254,6 +257,7 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
                 }
                 this.claimed.set(row.podBase, claim);
                 this.agentHandles.set(row.handle, row.podBase);
+                this.roots.set(row.podBase, row.root || 'fedipod/');
                 pods.push(row.podBase);
             }
         }
@@ -298,6 +302,7 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
         const { ensureDoorSecret } = await esmImport(EMBED);
         return ensureDoorSecret(session ?? (0, store_pod_1.makeStoreSession)(this.args.resourceStore, podBase), podBase, {
             ...opts,
+            root: this.roots.get(podBase) ?? 'fedipod/',
             dataDir: this.args.agentDataDir,
             handle: deriveHandle(podBase),
             log: (message) => { this.logger.info(`@${deriveHandle(podBase)}: ${message}`); },
@@ -322,6 +327,7 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
                     }
                     const identity = await startEmbeddedAgent({
                         podBase,
+                        root: this.roots.get(podBase) ?? 'fedipod/',
                         dataDir: this.args.agentDataDir,
                         session,
                         resourceStore: this.args.resourceStore,
@@ -474,7 +480,7 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
             return [];
         }
     }
-    async optInPod({ podBase, webId }) {
+    async optInPod({ podBase, webId, container = '', createIndex = false }) {
         if (!this.registry)
             return { httpStatus: 501, error: 'this server does not offer runtime opt-in' };
         if (this.args.clusterManager && !this.args.clusterManager.isSingleThreaded()) {
@@ -498,8 +504,31 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
             return { httpStatus: 409, error: e.message };
         }
         const { host } = claim;
+        // Where on the pod: the container its owner named holds `fedipod/`. The
+        // place is recorded in their public type index — made only on their yes —
+        // before anything else is written, and read here with the server's own
+        // access to the pod.
+        const place = await esmImport(PLACE);
+        const chosen = place.chosenRoot(base, container);
+        if (chosen.problem || !chosen.root)
+            return { httpStatus: 400, error: `Where to store it: ${chosen.problem}.` };
+        const root = chosen.root;
+        const { PodTransport } = await esmImport(TRANSPORT);
+        const pod = new PodTransport((0, store_pod_1.makeStoreSession)(this.args.resourceStore, base), { webId });
+        if (!createIndex && !await place.hasPublicIndex(pod, base)) {
+            return { httpStatus: 409, code: 'needs-index',
+                error: 'Your pod has no public type index, the list Solid apps use to find your things. '
+                    + 'FediPod needs one to record where your account lives.' };
+        }
+        try {
+            await place.recordPlace(pod, base, `${base}${root}ap/actor`, { create: createIndex });
+        }
+        catch (e) {
+            return { httpStatus: 500, error: `could not record where the account lives in your type index (${e.message})` };
+        }
+        this.roots.set(base, root);
         try {
-            await this.registry.add({ podBase: base, handle, host, webId, optedInAt: new Date().toISOString() });
+            await this.registry.add({ podBase: base, handle, host, webId, root, optedInAt: new Date().toISOString() });
         }
         catch (e) {
             this.logger.error(`opt-in row for ${base} could not be written: ${e.message}`);

package/dist/handler.jsonld

@@ -273,6 +273,10 @@
           "@id": "fps:dist/handler.jsonld#FediPodServerHandler__member_agentHandles",
           "memberFieldName": "agentHandles"
         },
+        {
+          "@id": "fps:dist/handler.jsonld#FediPodServerHandler__member_roots",
+          "memberFieldName": "roots"
+        },
         {
           "@id": "fps:dist/handler.jsonld#FediPodServerHandler__member_frontHost",
           "memberFieldName": "frontHost"

package/dist/store-pod.js

@@ -15,6 +15,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeStoreFetch = makeStoreFetch;
 exports.makeStoreSession = makeStoreSession;
+const node_stream_1 = require("node:stream");
 const community_server_1 = require("@solid/community-server");
 /** Header lookup that does not care about case, over either shape fetch accepts. */
 function headerReader(init) {
@@ -131,6 +132,42 @@ function makeStoreFetch(resourceStore, podBase) {
             const written = changes?.get?.(identifier);
             return respond(205, null, written && etags.getETag(written));
         }
+        // An N3 Patch of an RDF document — a profile, a type index — read by the
+        // parser a Solid server reads one with, and applied by the store's own
+        // patching. Only the statements change; the document is never rewritten
+        // around them. A store that cannot patch answers 501, which is the one
+        // answer that sends a caller to writing the whole document instead.
+        if (method === 'PATCH') {
+            stats.writes++;
+            if (!/^text\/n3\b/u.test(header('content-type') ?? ''))
+                return respond(415, 'an N3 Patch is the patch this takes');
+            let patch;
+            try {
+                patch = await new community_server_1.N3PatchBodyParser().handle({
+                    metadata: new community_server_1.RepresentationMetadata(identifier, 'text/n3'),
+                    request: (0, community_server_1.guardStream)(node_stream_1.Readable.from([String(init.body ?? '')])),
+                });
+            }
+            catch (e) {
+                return respond(400, `not a patch this can read: ${e.message}`);
+            }
+            const ifMatch = header('if-match');
+            const conditions = ifMatch
+                ? new community_server_1.BasicConditions(etags, { matchesETag: ifMatch.split(',').map((t) => t.trim()) })
+                : undefined;
+            try {
+                await resourceStore.modifyResource(identifier, patch, conditions);
+            }
+            catch (e) {
+                // What the store said, as the status it said it with: 409 for a
+                // deletion of something not there, 412 for a stale If-Match, 501
+                // for a store with no patching at all.
+                if (community_server_1.HttpError.isInstance(e))
+                    return respond(e.statusCode, e.message);
+                throw e;
+            }
+            return respond(205, null);
+        }
         if (method === 'DELETE') {
             stats.deletes++;
             try {