fedipod-server 0.29.0 → 0.31.0

package/README.md

@@ -52,6 +52,10 @@ sign-up refuses rather than half-working.
 npm install fedipod-server
 ```
 
+It installs `fedipod` with it: the agent, the Gateway's front and the pages
+are that package's, and a fix there reaches this component at your next
+`npm install`.
+
 Add the package context to your CSS config and import the shipped snippet:
 
 ```json
@@ -109,7 +113,7 @@ naming the pod the identity runs on. Nothing private is in it.
 | `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 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. |
+| `runPage` | The HTML of the page where a pod owner opts in or out. The page `fedipod` ships 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. |
 | `agentWebIdSuffix` | Path from a pod's base to its owner's WebID. Defaults to `profile/card#me`. |
 | `agentPollSeconds` | How often the inbox is swept. Deliveries also wake the sweep as they land, so this is the fallback. |
@@ -133,10 +137,8 @@ Each identity answers on its pod's origin, so the pod is what a client
 connects to. Point a Mastodon app at `https://mei.example.org/` and it finds
 what it expects: nodeinfo, the client API under `/api/`, sign-in under
 `/oauth/`, the live feed at `/api/v1/streaming`, and the ActivityPub write API
-at `/ap/outbox`. The owner's own pages — the record and, in a repository
-checkout, the bundled web client — are behind `agentUiPath`, which the door
-secret guards. The published package does not carry the web client; point a
-Mastodon app at the pod instead.
+at `/ap/outbox`. The owner's own pages — the record and the bundled web client — are behind
+`agentUiPath`, which the door secret guards.
 
 The client API answers any origin, the way any Mastodon server does, so a
 browser client works too: it registers an app, and the authorize screen names
@@ -154,6 +156,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 followers-only or direct post of the identity's is given, at its own
+address, to a server it was sent to when that server signs its request, the
+way Mastodon gives its own: a follower's server gets a followers-only post,
+the named person's server gets a direct one, and nobody else gets either.
+
 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
@@ -252,7 +259,10 @@ npm run test:e2e:suffix   # the same, for suffixed pods (mode d)
 container listings — through the transport an identity uses, and checks the
 lease protocol and the deletion deny-list still hold across it.
 
-`npm test` is also what a publish runs, so a red suite blocks one.
+`npm test` is also what a publish runs, so a red suite blocks one. In a
+FediPod checkout the tests run against the checkout's own `fedipod`:
+`scripts/link-fedipod.mjs` links it into `node_modules` before each test
+script, and does nothing anywhere else.
 
 `npm run test:e2e` starts a real Community Solid Server with three pods (two
 become identities up front; the third opts in and out at runtime), then signs in as a phone app does, posts,

package/dist/claims.d.ts

@@ -5,6 +5,7 @@ export declare function claims(input: {
     pathname: string;
 }, frontHost: string, runPath?: string): boolean;
 export declare const isInboxPath: (pathname: string) => boolean;
+export declare const isPrivateReadPath: (pathname: string) => boolean;
 /**
  * True when this path belongs to an identity's client surface.
  *
@@ -18,4 +19,5 @@ export declare const isInboxPath: (pathname: string) => boolean;
 export declare function agentClaims(input: {
     pathname: string;
     method?: string;
+    signed?: 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.isInboxPath = exports.DEFAULT_RUN_PATH = void 0;
+exports.isPrivateReadPath = exports.isInboxPath = exports.DEFAULT_RUN_PATH = void 0;
 exports.claims = claims;
 exports.agentClaims = agentClaims;
 // Signing up is CSS's, untouched: a person makes an account and a pod the way
@@ -18,8 +18,8 @@ const FRONT_PATHS = new Set(['/roster',
     '/.well-known/webfinger', '/api/handle', '/api/attach', '/api/agent',
     '/api/roster', '/api/revoke',
     // What the pages that remain load: the sign-in library the opt-in and
-    // roster pages use, and the installer, which is FediPod's own to hand out.
-    '/solid-oidc-client.js', '/install',
+    // roster pages use.
+    '/solid-oidc-client.js',
     // Each page's own script, served beside it; a page without its script has
     // buttons that never wake up.
     '/new-account.js', '/run.js', '/admin.js']);
@@ -58,6 +58,10 @@ const AGENT_PREFIXES = ['/api/', '/oauth/', '/@']; // /@handle: the short profil
 // `/aisha/fedipod/ap/inbox/` arrives here already stripped to `/fedipod/ap/inbox/`.
 const isInboxPath = (pathname) => /^\/(?:[^/]+\/)+ap\/inbox\/$/u.test(pathname);
 exports.isInboxPath = isInboxPath;
+// A document in the identity's private folder — a followers-only or direct
+// post, or one of the owner's own lists — matched by shape like the inbox.
+const isPrivateReadPath = (pathname) => /^\/(?:[^/]+\/)+ap\/private\/[^/]+$/u.test(pathname);
+exports.isPrivateReadPath = isPrivateReadPath;
 /**
  * True when this path belongs to an identity's client surface.
  *
@@ -70,8 +74,13 @@ exports.isInboxPath = isInboxPath;
  */
 function agentClaims(input, uiPath = '/fp/') {
     const { pathname } = input;
+    const method = String(input.method ?? '').toUpperCase();
     if ((0, exports.isInboxPath)(pathname))
-        return String(input.method ?? '').toUpperCase() === 'POST';
+        return method === 'POST';
+    // A signed read of a private post is answered at the door, to a server the
+    // post was sent to (private-read.ts). Unsigned, the document is the pod's.
+    if ((0, exports.isPrivateReadPath)(pathname))
+        return !!input.signed && (method === 'GET' || method === 'HEAD');
     if (AGENT_PATHS.has(pathname))
         return true;
     if (AGENT_PREFIXES.some((prefix) => pathname.startsWith(prefix)))

package/dist/door.d.ts

@@ -0,0 +1,4 @@
+import type { HttpHandlerInput } from '@solid/community-server';
+import type { EmbeddedIdentity } from './identities';
+import type { FediPodServerHandler } from './handler';
+export declare function deliverAtDoor(h: FediPodServerHandler, identity: EmbeddedIdentity, request: HttpHandlerInput['request'], response: HttpHandlerInput['response']): Promise<void>;

package/dist/door.js

@@ -0,0 +1,31 @@
+"use strict";
+// door.ts — a delivery to an identity's own inbox, verified here: the server
+// that stores the inbox is the one the request reached, so the signature is
+// checked while its headers exist and the receipt is written beside the
+// activity. The same door code the front runs; nothing is renamed.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deliverAtDoor = deliverAtDoor;
+const adapt_1 = require("./adapt");
+const fedipod_1 = require("./fedipod");
+async function deliverAtDoor(h, identity, request, response) {
+    const s = h.internals();
+    const { deliverToInbox } = await (0, fedipod_1.esmImport)(fedipod_1.EMBED);
+    let whatwg;
+    try {
+        // The pod's own origin: the signature covers the path and the Host header, and both are the pod's.
+        whatwg = await (0, adapt_1.nodeToWhatwg)(request, new URL(identity.podHome).origin);
+    }
+    catch (e) {
+        const status = e.statusCode === 413 ? 413 : 400;
+        response.writeHead(status, { 'content-type': 'application/json' });
+        response.end(JSON.stringify({ error: e.message }));
+        return;
+    }
+    const out = await deliverToInbox(identity.agent, whatwg, {
+        podPut: (url, body, ct) => s.podPut(url, body, ct),
+        gatewayWebId: s.args.gatewayWebId ?? null,
+    });
+    s.logger.info(`FediPod: delivery for @${identity.handle} at the door — ${out.reason} (${out.status})`);
+    response.writeHead(out.status, { 'content-type': 'application/json' });
+    response.end(JSON.stringify({ reason: out.reason }));
+}

package/dist/fedipod.d.ts

@@ -0,0 +1,15 @@
+export declare const FRONT_CORE = "fedipod/front";
+export declare const FRONT_PAGES = "fedipod/front-pages";
+export declare const EMBED = "fedipod/embed";
+export declare const PLACE = "fedipod/place";
+export declare const TRANSPORT = "fedipod/pod/transport.mjs";
+export declare const esmImport: (s: string) => Promise<Record<string, Function>>;
+/** The front's pages and the files they load, as fedipod/front-pages reads them. */
+export interface FrontPages {
+    signupPage: string | null;
+    runPage: string | null;
+    adminPage: string | null;
+    noticesPage: string | null;
+    authBundle: string | null;
+    pageScripts: Record<string, string | null>;
+}

package/dist/fedipod.js

@@ -0,0 +1,13 @@
+"use strict";
+// fedipod.ts — the fedipod modules this component loads, by name, at runtime.
+// They are an ESM tree; a real dynamic import() built via Function keeps tsc
+// from downleveling it to require(), which cannot load an ESM module with
+// top-level await under a CommonJS build.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.esmImport = exports.TRANSPORT = exports.PLACE = exports.EMBED = exports.FRONT_PAGES = exports.FRONT_CORE = void 0;
+exports.FRONT_CORE = 'fedipod/front';
+exports.FRONT_PAGES = 'fedipod/front-pages';
+exports.EMBED = 'fedipod/embed';
+exports.PLACE = 'fedipod/place';
+exports.TRANSPORT = 'fedipod/pod/transport.mjs';
+exports.esmImport = new Function('s', 'return import(s)');

package/dist/front.d.ts

@@ -0,0 +1,3 @@
+import type { HttpHandlerInput } from '@solid/community-server';
+import type { FediPodServerHandler } from './handler';
+export declare function serveFront(h: FediPodServerHandler, request: HttpHandlerInput['request'], response: HttpHandlerInput['response']): Promise<void>;

package/dist/front.js

@@ -0,0 +1,92 @@
+"use strict";
+// front.ts — a request the Gateway's front answers: the same routeFront the
+// Netlify front runs, given this server's pages, its directory, its store
+// and the opt-in controls.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serveFront = serveFront;
+const adapt_1 = require("./adapt");
+const fedipod_1 = require("./fedipod");
+async function serveFront(h, request, response) {
+    const s = h.internals();
+    const { routeFront } = await (0, fedipod_1.esmImport)(fedipod_1.FRONT_CORE);
+    // Read on each request, so an edited page shows without a restart. A
+    // missing file is not fatal: the route it feeds answers 404.
+    const { frontPages } = await (0, fedipod_1.esmImport)(fedipod_1.FRONT_PAGES);
+    const pages = frontPages();
+    let whatwg;
+    try {
+        whatwg = await (0, adapt_1.nodeToWhatwg)(request, s.args.frontOrigin);
+    }
+    catch (e) {
+        const status = e.statusCode === 413 ? 413 : 400;
+        response.writeHead(status, { 'content-type': 'application/json' });
+        response.end(JSON.stringify({ error: e.message }));
+        return;
+    }
+    const out = await routeFront(whatwg, {
+        host: s.frontHost,
+        frontOrigin: s.args.frontOrigin,
+        // This server issued the session the reader is already using, so it can
+        // read it rather than sending them to an identity provider that has just
+        // told them who they are. Same-origin only; front-core decides that.
+        webIdsFromSession: (req) => h.webIdsFromSession(req),
+        gatewayWebId: s.args.gatewayWebId,
+        offersPods: !!s.args.offersPods,
+        signupPage: s.args.signupPage || pages.signupPage,
+        runPage: s.args.runPage || pages.runPage,
+        runPath: s.runPath,
+        adminPage: s.args.adminPage || pages.adminPage,
+        // The notices page renders here too, and says the server keeps none:
+        // a notices store is the Netlify front's, not this component's.
+        noticesPage: pages.noticesPage,
+        // The opt-in and roster pages load the sign-in library; without it the
+        // pages render but cannot be used.
+        authBundle: pages.authBundle,
+        // Each page's own script, so the pages can be served under
+        // `script-src 'self'` (see fedipod/front).
+        pageScripts: pages.pageScripts,
+        lookup: (handle) => h.dir.lookup(handle),
+        putDirectory: (handle, rec) => h.dir.putDirectory(handle, rec),
+        podPut: (_handle, url, body, ct) => s.podPut(url, body, ct),
+        // Reads for the public proxy. `s.io.read` goes STRAIGHT into the
+        // resource store, which applies no access control of its own — so this is
+        // the one place that has to say what may be read, and it says: only
+        // inside the pod of the handle being served, and never a server-internal
+        // tree. Without it a row could name any location and this would fetch it
+        // (the directory, with every user's receipt secret, included).
+        //
+        // The front now refuses to attach such a row at all (podHomeProblem in
+        // fedipod/front); this is the same refusal at the other end, because
+        // a row can also arrive from a seed or an older deploy.
+        podGet: async (url, opts) => {
+            const denied = { status: 403, text: async () => '', headers: { get: () => null } };
+            let target;
+            try {
+                target = new URL(url);
+            }
+            catch {
+                return denied;
+            }
+            if (/(^|\/)\.internal(\/|$)/u.test(target.pathname))
+                return denied;
+            // Which pod asked: routeFront reads `rec.podHome + rest` and passes
+            // that podHome here, so the confinement is a value on the call rather
+            // than state on the handler. No podHome, no read.
+            const home = opts?.podHome;
+            if (!home || !url.startsWith(home))
+                return denied;
+            const raw = await s.io.read(url);
+            return raw == null
+                ? { status: 404, text: async () => '', headers: { get: () => null } }
+                : { status: 200, text: async () => raw, headers: { get: () => null } };
+        },
+        agentControl: s.registry
+            ? {
+                optIn: (a) => h.optInPod(a),
+                optOut: (a) => h.optOutPod(a),
+                describe: (a) => h.describePod(a),
+            }
+            : undefined,
+    });
+    await (0, adapt_1.applyToNode)(response, out);
+}

package/dist/handler.d.ts

@@ -1,6 +1,8 @@
 import { HttpHandler } from '@solid/community-server';
-import type { HttpHandlerInput, ResourceStore, Initializable, Finalizable, ClusterManager } from '@solid/community-server';
-import type { Directory } from './directory';
+import type { HttpHandlerInput, ResourceStore, Initializable, Finalizable, ClusterManager, Logger } from '@solid/community-server';
+import type { IO, Directory, AgentRegistry } from './directory';
+import type { AgentClaim } from './mounts';
+import type { EmbeddedIdentity } from './identities';
 export interface FediPodServerArgs {
     /** The server's ResourceStore: the handler reads pods and writes inbox items and directory rows directly through it — no HTTP, no credential. */
     resourceStore: ResourceStore;
@@ -41,25 +43,31 @@ export interface FediPodServerArgs {
     /** An internal container URL where the runtime opt-in rows live. */
     agentRegistryContainer?: string;
 }
-/** One running identity, and the call that stops it. */
-interface EmbeddedIdentity {
-    handle: string;
-    host: string;
-    /** Where the identity's own tree begins on its pod, and the actor inside it. */
-    podHome: string;
-    actorUrl: string;
-    surface: {
-        handler: (req: unknown, res: unknown) => Promise<void>;
-        streaming?: unknown;
-    };
-    stop: () => Promise<void>;
-    agent?: {
-        store?: {
-            getConfig?: () => {
-                kind?: string;
-            } | null | undefined;
-        };
-    };
+/**
+ * What the parts beside this file share. Private on the class, because the
+ * component generator would otherwise offer every public field as a
+ * configurable member; read through internals().
+ */
+export interface Internals {
+    args: FediPodServerArgs;
+    io: IO;
+    dir: Directory;
+    runPath: string;
+    uiPath: string;
+    frontHost: string;
+    podPut: (url: string, body: string, contentType: string) => Promise<boolean>;
+    logger: Logger;
+    registry: AgentRegistry | null;
+    claimed: Map<string, AgentClaim>;
+    agentHandles: Map<string, string>;
+    roots: Map<string, string>;
+    identities: Map<string, EmbeddedIdentity>;
+    surfaces: Map<string, EmbeddedIdentity>;
+    doorSecrets: Map<string, string>;
+    starting: Set<string>;
+    startCancelled: Set<string>;
+    stopping: boolean;
+    onSignal: ((signal: NodeJS.Signals) => void) | null;
 }
 export declare class FediPodServerHandler extends HttpHandler implements Initializable, Finalizable {
     private readonly args;
@@ -82,61 +90,13 @@ export declare class FediPodServerHandler extends HttpHandler implements Initial
     private stopping;
     private onSignal;
     constructor(args: FediPodServerArgs);
-    /**
-     * 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 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.
-     */
+    /** The shared state, for the parts beside this file. */
+    internals(): Internals;
+    /** Start an agent for each opted-in pod, before the server listens. */
     initialize(): Promise<void>;
     /** Stop every identity: timers cleared, state written, lease let go. */
     finalize(): Promise<void>;
-    /**
-     * One identity's door secret, in its own pod's state. `agentDataDir` is
-     * handed in as the place an identity set up before this kept it, so its
-     * owner's existing door link survives the move.
-     */
-    private doorSecretFor;
-    private startIdentity;
-    /**
-     * When this server is also the door, give a running identity a
-     * @handle@<frontHost> address: one inbox-only directory row so the
-     * shared-domain handle resolves and the door can take verified delivery for
-     * it. The row names the identity's own tree, which is where its inbox and
-     * its actor are — the door writes deliveries there and the agent watches
-     * that container. A row written by an attach belongs to its owner and is
-     * left alone; one this server wrote itself is corrected. The identity keeps
-     * its own ids on the pod; nothing is moved.
-     */
-    private frontIdentity;
     canHandle({ request }: HttpHandlerInput): Promise<void>;
-    /**
-     * Whether identities run in this process. They run in one: the lease admits
-     * a single drainer, and the state each one holds is in memory. With workers,
-     * that process is the primary — which serves no requests, so every process
-     * still has to know which hosts belong to an identity even though only one
-     * of them can answer for it.
-     */
-    private runsIdentities;
     /**
      * 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
@@ -147,25 +107,13 @@ export declare class FediPodServerHandler extends HttpHandler implements Initial
         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
-     * reply and nowhere else. Re-opting-in rotates the secret — that is how a
-     * lost one is recovered.
-     */
-    /**
-     * The WebIDs behind the account session in the request, or none. The server
-     * keeps that session in a `css-account` cookie; its own account API is what
-     * says which WebIDs the session owns, and it takes the same cookie. Nothing
-     * here trusts the cookie's presence — the account API does the deciding, and
-     * the caller picks the WebID that owns the pod being claimed.
-     */
+    /** What a pod owner asks of this server; see opt-in.ts. */
     webIdsFromSession(request: {
         headers: {
             get(name: string): string | null;
         };
     }): Promise<string[]>;
-    optInPod({ podBase, webId, container, createIndex }: {
+    optInPod(a: {
         podBase: string;
         webId: string;
         container?: string;
@@ -173,11 +121,7 @@ export declare class FediPodServerHandler extends HttpHandler implements Initial
     }): Promise<Record<string, unknown> & {
         httpStatus: number;
     }>;
-    /**
-     * What a pod would be as an identity here, without changing anything: its
-     * handle, the host its address carries, and whether it runs here already.
-     */
-    describePod({ podBase }: {
+    describePod(a: {
         podBase: string;
     }): Promise<{
         handle: string;
@@ -186,19 +130,10 @@ export declare class FediPodServerHandler extends HttpHandler implements Initial
         running: boolean;
         manage: string;
     }>;
-    /** The reverse: stop the identity and let the pod be plain LDP again. */
-    optOutPod({ podBase }: {
+    optOutPod(a: {
         podBase: string;
     }): Promise<Record<string, unknown> & {
         httpStatus: number;
     }>;
-    /**
-     * A delivery to an identity's own inbox, verified here — the server that
-     * stores the inbox is the one the request reached, so the signature is
-     * checked while its headers exist and the receipt is written beside the
-     * activity. The same door code the front runs; nothing is renamed.
-     */
-    private deliverAtDoor;
     handle({ request, response }: HttpHandlerInput): Promise<void>;
 }
-export {};