fedipod-server 0.16.0 → 0.18.0

package/README.md

@@ -30,9 +30,13 @@ 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.** Each account answers on its own pod's address, so
-  every pod needs a host to itself. A server that puts its pods on paths of
-  one suffix-based host cannot offer accounts at all.
+- **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.
 - **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
@@ -66,8 +70,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.
-Use a subdomain-pods CSS config: identities need an origin of their own, and
-a path-pod config cannot opt anyone in.
+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.
  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.
@@ -84,8 +88,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, and it publishes an actor, a signing key and WebFinger on the
-pod itself. Everything it is made of lives on its pod — its state, its private
+subdomain label, or its last path segment on a suffix 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
 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
@@ -103,7 +108,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. `/fedipod/` by default; empty serves no pages. |
+| `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/`. |
 | `agentRegistryContainer` | The internal container holding the sign-up rows. |
 | `runPage` | The HTML served at `/run`: the page where a pod owner opts in or out. The package's own `web/front/run.html` is served unless you set this. |
 | `agentWebIdSuffix` | Path from a pod's base to its owner's WebID. Defaults to `profile/card#me`. |
@@ -149,9 +154,12 @@ 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 client API is rooted at an origin, so each identity needs an origin of its
-own: subdomain pods, one per identity. A second identity on a host is
-refused at opt-in rather than half-working.
+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
+opt-in rather than half-working.
 
 ### Before you turn it on
 
@@ -164,16 +172,24 @@ for anyone hosting other people, it is a promise being made to them.
 owner's door, with that identity's own door secret:
 
 ```
-curl -X POST https://mei.example.org/fedipod/config \
+# subdomain 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:
+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 an identity's origin the paths above
+**Some pod paths stop being served.** On a subdomain pod the paths above
 belong to the identity, so pod resources at those names — a container called
-`api`, `oauth` or `fedipod`, or documents at `ap/actor`, `ap/outbox`,
+`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
+(`/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
 as before.
 
@@ -228,7 +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 and uses it as a client would
+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 test` drives a genuine CSS store stack — ETags, conditional writes,
@@ -241,6 +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.
 
 `dist/` and `node_modules/` are gitignored; `src/`, `config/` and this file are
 the sources.

package/dist/claims.d.ts

@@ -2,19 +2,18 @@ export declare function claims(input: {
     host?: string;
     pathname: string;
 }, frontHost: string): boolean;
+export declare const isInboxPath: (pathname: string) => boolean;
 /**
- * The inbox container of an identity this server runs, under the root the
- * embedded credential uses (lib/server/embed.mjs). A delivery POSTed here is
- * verified at the door before it is written, so the request is claimed from
- * the LDP handler; every other method on the container is the pod's.
- */
-export declare const INBOX_PATH = "/activitypods-js/ap/inbox/";
-/**
- * True when this request belongs to an identity's client surface.
- * `agentHosts` is keyed by host including port, as the Host header carries it.
+ * True when this path belongs to an identity's client surface.
+ *
+ * `pathname` is RELATIVE to the identity's mount: the handler has already
+ * matched the request's host and mount to one identity (see resolveClaim) and
+ * stripped the mount, so a host-root/subdomain pod passes its path unchanged
+ * and a suffix pod on `/aisha/` passes the part after `/aisha`. That keeps this
+ * a pure statement about which routes an identity owns, with no notion of host
+ * or of where on the origin it lives.
  */
 export declare function agentClaims(input: {
-    host?: string;
     pathname: string;
     method?: string;
-}, agentHosts: Set<string>, uiPath?: string): boolean;
+}, uiPath?: string): boolean;

package/dist/claims.js

@@ -4,7 +4,7 @@
 // front's apex the gateway answers the fediverse routes; a pod subdomain is a
 // real Solid pod and is never claimed.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INBOX_PATH = void 0;
+exports.isInboxPath = void 0;
 exports.claims = claims;
 exports.agentClaims = agentClaims;
 const FRONT_PATHS = new Set(['/', '/signup', '/new-account', '/run', '/roster',
@@ -36,27 +36,29 @@ const AGENT_PATHS = new Set([
     '/.well-known/oauth-authorization-server',
 ]);
 const AGENT_PREFIXES = ['/api/', '/oauth/'];
+// 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
+// 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);
+exports.isInboxPath = isInboxPath;
 /**
- * The inbox container of an identity this server runs, under the root the
- * embedded credential uses (lib/server/embed.mjs). A delivery POSTed here is
- * verified at the door before it is written, so the request is claimed from
- * the LDP handler; every other method on the container is the pod's.
+ * True when this path belongs to an identity's client surface.
+ *
+ * `pathname` is RELATIVE to the identity's mount: the handler has already
+ * matched the request's host and mount to one identity (see resolveClaim) and
+ * stripped the mount, so a host-root/subdomain pod passes its path unchanged
+ * and a suffix pod on `/aisha/` passes the part after `/aisha`. That keeps this
+ * a pure statement about which routes an identity owns, with no notion of host
+ * or of where on the origin it lives.
  */
-exports.INBOX_PATH = '/activitypods-js/ap/inbox/';
-/**
- * True when this request belongs to an identity's client surface.
- * `agentHosts` is keyed by host including port, as the Host header carries it.
- */
-function agentClaims(input, agentHosts, uiPath = '/fedipod/') {
-    if (!input.host || agentHosts.size === 0)
-        return false;
-    if (!agentHosts.has(String(input.host).toLowerCase()))
-        return false;
+function agentClaims(input, uiPath = '/fp/') {
     const { pathname } = input;
+    if ((0, exports.isInboxPath)(pathname))
+        return String(input.method ?? '').toUpperCase() === 'POST';
     if (AGENT_PATHS.has(pathname))
         return true;
-    if (pathname === exports.INBOX_PATH)
-        return String(input.method ?? '').toUpperCase() === 'POST';
     if (AGENT_PREFIXES.some((prefix) => pathname.startsWith(prefix)))
         return true;
     // The owner's door, when there is one: '' turns the pages off entirely.

package/dist/directory.d.ts

@@ -39,11 +39,19 @@ export interface AgentRegistryRecord {
     webId: string;
     optedInAt: string;
 }
+/**
+ * The registry key for an opted-in pod: its host plus its path. Several pods
+ * can share a host (suffix pods on one origin), so the host alone is not
+ * unique. A host-root or subdomain pod has an empty path, so its key is just
+ * its host — exactly the shape rows were keyed by before suffix pods existed,
+ * which is why old rows still resolve with no migration.
+ */
+export declare function agentKey(host: string, podBase: string): string;
 export interface AgentRegistry {
-    listHosts(): Promise<string[]>;
-    get(host: string): Promise<AgentRegistryRecord | null>;
+    listKeys(): Promise<string[]>;
+    get(key: string): Promise<AgentRegistryRecord | null>;
     add(record: AgentRegistryRecord): Promise<void>;
-    remove(host: string): Promise<void>;
+    remove(key: string): Promise<void>;
 }
 export declare function makeAgentRegistry(io: IO, containerUrl: string): AgentRegistry;
 export declare function makeStorePodPut(io: IO): (url: string, body: string, contentType: string) => Promise<boolean>;

package/dist/directory.js

@@ -5,6 +5,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.frontRow = frontRow;
 exports.makeDirectory = makeDirectory;
+exports.agentKey = agentKey;
 exports.makeAgentRegistry = makeAgentRegistry;
 exports.makeStorePodPut = makeStorePodPut;
 // One JSON document per key in a container — the shape both registries share.
@@ -57,28 +58,41 @@ function makeDirectory(io, containerUrl) {
         putDirectory: (handle, record) => table.put(handle, record),
     };
 }
-// The registry of runtime-opted-in pods, keyed by host (the claim key). The
-// IO layer cannot enumerate a container, so index.json carries the host list;
+/**
+ * The registry key for an opted-in pod: its host plus its path. Several pods
+ * can share a host (suffix pods on one origin), so the host alone is not
+ * unique. A host-root or subdomain pod has an empty path, so its key is just
+ * its host — exactly the shape rows were keyed by before suffix pods existed,
+ * which is why old rows still resolve with no migration.
+ */
+function agentKey(host, podBase) {
+    return host + new URL(podBase).pathname.replace(/\/+$/u, '');
+}
+// The registry of runtime-opted-in pods, keyed by agentKey (host+path). The
+// IO layer cannot enumerate a container, so index.json carries the key list;
 // the row is written FIRST, so a crash between the two writes still leaves a
-// row the next boot claims once the index catches up on the next change.
+// row the next boot claims once the index catches up on the next change. The
+// index field stays named `hosts`: for a host-root pod a key IS its host, so
+// documents an older server wrote are read back unchanged.
 function makeAgentRegistry(io, containerUrl) {
     const table = jsonTable(io, containerUrl);
     const index = jsonTable(io, containerUrl);
     const INDEX = 'index';
-    const hosts = async () => (await index.get(INDEX))?.hosts ?? [];
+    const keys = async () => (await index.get(INDEX))?.hosts ?? [];
     return {
-        listHosts: hosts,
-        get: (host) => table.get(host),
+        listKeys: keys,
+        get: (key) => table.get(key),
         async add(record) {
-            await table.put(record.host, record);
-            const list = await hosts();
-            if (!list.includes(record.host))
-                await index.put(INDEX, { hosts: [...list, record.host] });
+            const key = agentKey(record.host, record.podBase);
+            await table.put(key, record);
+            const list = await keys();
+            if (!list.includes(key))
+                await index.put(INDEX, { hosts: [...list, key] });
         },
-        async remove(host) {
-            const list = await hosts();
-            await index.put(INDEX, { hosts: list.filter((h) => h !== host) });
-            await table.remove(host);
+        async remove(key) {
+            const list = await keys();
+            await index.put(INDEX, { hosts: list.filter((h) => h !== key) });
+            await table.remove(key);
         },
     };
 }

package/dist/handler.d.ts

@@ -65,7 +65,7 @@ export declare class FediPodServerHandler extends HttpHandler implements Initial
     readonly dir: Directory;
     private readonly podPut;
     private readonly logger;
-    private readonly agentHosts;
+    private readonly claimed;
     private readonly agentHandles;
     private readonly frontHost;
     private readonly uiPath;
@@ -79,11 +79,26 @@ export declare class FediPodServerHandler extends HttpHandler implements Initial
     private onSignal;
     constructor(args: FediPodServerArgs);
     /**
-     * Whether this pod may become an identity here: a real URL, an origin of its
-     * own, not the front's host, and a handle no other identity already uses —
-     * two pods must never share <agentDataDir>/<handle>/.
+     * Whether this pod may become an identity here, and the claim it earns: a
+     * real URL, a place no other identity already sits, and a handle no other
+     * identity uses — two pods must never share <agentDataDir>/<handle>/.
+     *
+     * A HOST-ROOT or subdomain pod needs an origin of its own, and it may not be
+     * the front's host: the whole surface answers at the origin root, so two of
+     * them, or one sharing the front, would collide. A SUFFIX pod lives on a path
+     * (`server/aisha/`), so it may share its host — with the front and with other
+     * suffix pods — provided no claim already contains or nests under its path.
      */
-    private validateAgentHost;
+    private validateAgentPod;
+    /**
+     * The claim a request belongs to, or null. A request matches when its host is
+     * the claim's host and its path is at or under the claim's mount; the deepest
+     * mount wins, so a suffix pod's own routes are never swallowed by a shallower
+     * claim on the same host.
+     */
+    private resolveClaim;
+    /** A request path relative to a mount: `/aisha/ap/actor` under `/aisha` → `/ap/actor`. */
+    private stripMount;
     /**
      * Start an agent for each opted-in pod. Runs before the server listens, so
      * the identities come up in the background and boot is never held on a pod.
@@ -118,8 +133,16 @@ export declare class FediPodServerHandler extends HttpHandler implements Initial
      * of them can answer for it.
      */
     private runsIdentities;
-    /** The running identity answering on a host, if it has finished starting. */
-    surfaceFor(host?: string): EmbeddedIdentity | undefined;
+    /**
+     * The identity a request belongs to (matched by host and mount) and the
+     * request path relative to that identity's mount, or null. The identity is
+     * undefined when the pod is claimed but still starting. Used by the streaming
+     * upgrade, which has only the request to go on.
+     */
+    matchIdentity(host?: string, pathname?: string): {
+        identity: EmbeddedIdentity | undefined;
+        rel: string;
+    } | null;
     /**
      * A pod owner, already proven to control podBase, asks this server to run
      * their identity. Returns { httpStatus, ...body }; the secret appears in the