fedipod-server 0.4.0

package/README.md

@@ -0,0 +1,198 @@
+# FediPod Server
+
+-- a full ActivityPub server deployed as a Community Solid Server component
+
+This is a CSS component. Install it in a fresh server instance or an instance
+you already run for pods, and turn sign-up on. A pod owner signs in at the
+server's `/run` page and opts in; from then on their pod is a full fediverse
+account: it accepts follows, delivers their posts, and serves their Mastodon
+client at the pod's own address. Signing up is the only way an account is
+made, and opting out is the only way one ends.
+
+With nothing configured beyond the defaults, installing the component changes
+nothing about how the server serves pods.
+
+![FediPod as a component of a Solid server](fedipod-server.svg)
+
+## Install
+
+```
+npm install fedipod-server
+```
+
+Add the package context to your CSS config and import the shipped snippet:
+
+```json
+{
+  "@context": [
+    "...your CSS context...",
+    "https://linkedsoftwaredependencies.org/bundles/npm/fedipod-server/^0.0.0/components/context.jsonld"
+  ],
+  "import": [
+    "css:config/default.json",
+    "fps:config/server.json"
+  ]
+}
+```
+
+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.
+ 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.
+
+## Turning sign-up on
+
+```json
+{
+  "@id": "urn:fedipod:server:Handler",
+  "@type": "FediPodServerHandler",
+  "args_agentRuntimeOptIn": true,
+  "args_agentDataDir": "/var/lib/css/fedipod-agent/"
+}
+```
+
+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. Its state lives on the pod. Its signing key lives in
+`agentDataDir`, one directory per identity — and beside it,
+`door-secret.json`: the secret guarding that identity's own pages. Each
+identity has its own; one owner's secret opens nobody else's door.
+
+| Setting | What it is |
+|---|---|
+| `agentRuntimeOptIn` | Whether pod owners can sign up. With it off, nothing runs. |
+| `agentDataDir` | Where each identity keeps its signing key, credential and door secret; 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. |
+| `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`. |
+| `agentPollSeconds` | How often the inbox is swept. Deliveries also wake the sweep as they land, so this is the fallback. |
+| `agentAutoAcceptFollows` | Whether a newly provisioned identity accepts follows without review. On by default. |
+
+| Setting | What it is |
+|---|---|
+| `frontHost` | The apex host the shared front answers on. Defaults to this server's own base URL, so a plain install answers on its own address; set it only to front a different apex. |
+| `frontOrigin` | Its origin. |
+| `directoryContainer` | The internal container holding the handle directory. |
+| `agentAutoFront` | Whether every identity that starts also gets a `@handle@frontHost` address — an inbox-only directory row, written once. Off by default. |
+| `offersPods` | Whether the signup page offers to create pods here. |
+| `signupPage` | The signup page served at `/`, `/signup` and `/new-account`. The package's own is served unless you set this. |
+| `gatewayWebId` | The WebID stamped on verification receipts. |
+
+`signupPage` and `runPage` are the page's HTML itself, not a path to a file.
+
+### The pod is the instance
+
+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.
+
+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
+what is asking and where the code will be sent before the owner approves it
+with the password. The authorization code is bound to the client's registered
+redirect, and only that client, holding its secret, can exchange it for a
+token.
+
+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.
+
+### Before you turn it on
+
+**The server holds the keys.** Whoever runs the server can act as the
+identities it runs. For a self-hoster that is their own machine either way;
+for anyone hosting other people, it is a promise being made to them.
+
+**Sign-in needs a password.** These routes face the whole internet, so
+`/oauth/authorize` refuses until the identity has one. Set it once through the
+owner's door, with that identity's own door secret:
+
+```
+curl -X POST https://mei.example.org/fedipod/config \
+  -H 'x-dk-token: THE_DOOR_SECRET_FROM_door-secret.json' -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
+belong to the identity, so pod resources at those names — a container called
+`api`, `oauth` or `fedipod`, or documents at `ap/actor`, `ap/outbox`,
+`.well-known/nodeinfo` and `nodeinfo/2.0` — are not served over HTTP there.
+They stay in the pod and in its listings. Every other path is the pod, exactly
+as before.
+
+**Run one worker.** A delivery is picked up the moment it lands only in a
+single-worker server. With `--workers` above one the inbox is swept on the
+timer instead, and the server says so at startup. Sign-up requires a
+single worker outright, and says so when refused.
+
+## How sign-up works
+
+A pod owner opens the `/run` page, signs in with their pod,
+and opts in or out. Underneath it is one endpoint:
+
+```
+POST /api/agent
+{"action": "opt-in", "podBase": "https://mei.example.org/"}
+```
+
+The request carries a Solid-OIDC token; the WebID it proves must live under
+the pod being claimed. The reply carries the identity's door secret, shown
+that once and never again — losing it is not fatal, because opting in again
+mints a fresh one and retires the old, with no restart and no dropped
+connections. `{"action": "opt-out", "podBase": "https://mei.example.org/"}`,
+with the same token as opt-in, stops the identity and returns the pod
+to plain pod serving; deliveries keep landing in its inbox and simply wait.
+Opted-in pods are recorded in the registry container and come back after a
+server restart — which is also why sign-up wants a persistent storage
+backend: rows kept in a memory backend vanish when the server stops.
+
+## What is in the package
+
+| File | What it does |
+|---|---|
+| `src/handler.ts` | The HTTP handler, and the identities' lifecycle. Claims each identity's routes; everything else falls through to the server. |
+| `src/streaming-handler.ts` | The live feed. Websocket upgrades never enter the request waterfall, so they arrive here. |
+| `src/claims.ts` | Which paths belong to an identity. |
+| `src/store-pod.ts` | An identity's whole conversation with its pod, carried by the server's store instead of the network. |
+| `src/store-css.ts` | The component's own reads and writes, likewise. |
+| `src/directory.ts` | The handle-to-pod directory, one document per handle. |
+| `src/adapt.ts` | Node request and response to the WHATWG pair the shared core speaks. |
+
+Writing through the store bypasses access control by design: the component is
+the thing that decided the write is legitimate — a verified delivery, or an
+identity acting on its own pod.
+
+The agent is FediPod's own, unchanged: this package is the part that knows
+about CSS.
+
+## Build and test
+
+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 test` drives a genuine CSS store stack — ETags, conditional writes,
+container listings — through the transport an identity uses, and checks the
+lease protocol and the deletion deny-list still hold across it.
+
+`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,
+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.
+
+`dist/` and `node_modules/` are gitignored; `src/`, `config/` and this file are
+the sources.

package/config/server.json

@@ -0,0 +1,66 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^7.0.0/components/context.jsonld",
+    "https://linkedsoftwaredependencies.org/bundles/npm/fedipod-server/^0.0.0/components/context.jsonld"
+  ],
+  "@graph": [
+    {
+      "comment": "The FediPod server handler. The front answers on this server's own base URL unless args_frontHost names another apex; pod subdomains fall through to CSS untouched. Field names carry the args_ prefix the generator produced from the constructor's options object.",
+      "@id": "urn:fedipod:server:Handler",
+      "@type": "FediPodServerHandler",
+      "args_resourceStore": { "@id": "urn:solid-server:default:ResourceStore" },
+      "args_frontOrigin": { "@id": "urn:solid-server:default:variable:baseUrl" },
+      "args_directoryContainer": "/.internal/fedipod/directory/",
+      "args_offersPods": false,
+      "args_clusterManager": { "@id": "urn:solid-server:default:ClusterManager" },
+      "args_agentRegistryContainer": "/.internal/fedipod/agents/"
+    },
+    {
+      "comment": "The live feed for a pod-hosted identity. A websocket upgrade never enters the request waterfall — CSS routes it through a handler list of its own — so this is a second class holding the same handler instance. Appending to the list here unions with whichever notification configuration the deployment loads.",
+      "@id": "urn:fedipod:server:StreamingHandler",
+      "@type": "FediPodStreamingHandler",
+      "args_server": { "@id": "urn:fedipod:server:Handler" }
+    },
+    {
+      "@id": "urn:solid-server:default:WebSocketHandler",
+      "@type": "WaterfallHandler",
+      "handlers": [
+        { "@id": "urn:fedipod:server:StreamingHandler" }
+      ]
+    },
+    {
+      "comment": "Starting each opted-in identity when the server starts, and stopping it cleanly when the server stops. The same handler instance does both, which is what InitializableHandler and FinalizableHandler are for. With sign-up off both are no-ops.",
+      "@id": "urn:solid-server:default:PrimaryParallelInitializer",
+      "@type": "ParallelHandler",
+      "handlers": [
+        {
+          "@type": "InitializableHandler",
+          "initializable": { "@id": "urn:fedipod:server:Handler" }
+        }
+      ]
+    },
+    {
+      "@id": "urn:solid-server:default:Finalizer",
+      "@type": "ParallelHandler",
+      "handlers": [
+        {
+          "@type": "FinalizableHandler",
+          "finalizable": { "@id": "urn:fedipod:server:Handler" }
+        }
+      ]
+    },
+    {
+      "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",
+      "overrideInstance": { "@id": "urn:solid-server:default:BaseHttpHandler" },
+      "overrideSteps": [
+        {
+          "@type": "OverrideListInsertBefore",
+          "overrideParameter": { "@id": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^7.0.0/dist/util/handlers/WaterfallHandler.jsonld#WaterfallHandler_handlers" },
+          "overrideTarget": { "@id": "urn:solid-server:default:LdpHandler" },
+          "overrideValue": { "@id": "urn:fedipod:server:Handler" }
+        }
+      ]
+    }
+  ]
+}

package/dist/adapt.d.ts

@@ -0,0 +1,18 @@
+type NodeReq = {
+    method?: string;
+    url?: string;
+    headers: Record<string, unknown>;
+    on(event: string, cb: (arg?: unknown) => void): void;
+};
+type NodeRes = {
+    writeHead(status: number, headers?: Record<string, string>): void;
+    end(body?: string | null): void;
+};
+type CoreResult = Response | {
+    status: number;
+    headers?: Record<string, string>;
+    body?: string | null;
+};
+export declare function nodeToWhatwg(req: NodeReq, origin: string): Promise<Request>;
+export declare function applyToNode(res: NodeRes, out: CoreResult): Promise<void>;
+export {};

package/dist/adapt.js

@@ -0,0 +1,79 @@
+"use strict";
+// adapt.ts — the one glue layer between CSS and the gateway core.
+//
+// CSS hands a handler Node's own request/response. The FediPod core
+// (routeFront/handleDelivery) speaks WHATWG Request/Response. These convert
+// both ways; they are the only CSS-shaped code that needs unit coverage.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeToWhatwg = nodeToWhatwg;
+exports.applyToNode = applyToNode;
+// The same ceiling the agent surface's own readBody has. Everything the front
+// accepts is far smaller; without this a stranger's POST buffers unbounded.
+const MAX_BODY_BYTES = 1024 * 1024;
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            resolve(null);
+            return;
+        }
+        const chunks = [];
+        let total = 0;
+        let done = false;
+        const fail = (err) => {
+            if (done)
+                return;
+            done = true;
+            reject(err);
+        };
+        req.on('data', (c) => {
+            if (done)
+                return;
+            total += c.length;
+            if (total > MAX_BODY_BYTES) {
+                const err = new Error('request body too large');
+                err.statusCode = 413;
+                fail(err);
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => { if (!done)
+            resolve(chunks.length ? Buffer.concat(chunks) : null); });
+        req.on('error', (e) => fail(e));
+    });
+}
+// A Node request → a WHATWG Request. `origin` is the public origin CSS serves
+// on, so the core sees the same absolute URL a remote used.
+async function nodeToWhatwg(req, origin) {
+    const url = new URL(req.url ?? '/', origin).href;
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (Array.isArray(v))
+            for (const one of v)
+                headers.append(k, String(one));
+        else if (v !== undefined && v !== null)
+            headers.set(k, String(v));
+    }
+    const body = await readBody(req);
+    return new Request(url, {
+        method: req.method,
+        headers,
+        ...(body ? { body: body, duplex: 'half' } : {}),
+    });
+}
+// Apply a core result onto the Node response. The core returns either a WHATWG
+// Response or a plain { status, headers, body } (front-core uses the latter).
+async function applyToNode(res, out) {
+    if (out && typeof out.status === 'number' && !(out instanceof Response)) {
+        const o = out;
+        res.writeHead(o.status, o.headers || {});
+        res.end(o.body ?? null);
+        return;
+    }
+    const r = out;
+    const headers = {};
+    r.headers.forEach((v, k) => { headers[k] = v; });
+    res.writeHead(r.status, headers);
+    const text = await r.text();
+    res.end(text || null);
+}

package/dist/claims.d.ts

@@ -0,0 +1,12 @@
+export declare function claims(input: {
+    host?: string;
+    pathname: string;
+}, frontHost: string): boolean;
+/**
+ * True when this request belongs to an identity's client surface.
+ * `agentHosts` is keyed by host including port, as the Host header carries it.
+ */
+export declare function agentClaims(input: {
+    host?: string;
+    pathname: string;
+}, agentHosts: Set<string>, uiPath?: string): boolean;

package/dist/claims.js

@@ -0,0 +1,43 @@
+"use strict";
+// claims.ts — which requests the gateway owns, so canHandle can reject the rest
+// and let normal pod/LDP traffic fall through to CSS. Scoped by HOST: on the
+// 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.claims = claims;
+exports.agentClaims = agentClaims;
+const FRONT_PATHS = new Set(['/', '/signup', '/new-account', '/run',
+    '/.well-known/webfinger', '/api/handle', '/api/attach', '/api/agent',
+    // What the two pages load: the sign-in library both use, and the installer
+    // the signup page hands every new user.
+    '/solid-client-authn.bundle.js', '/install']);
+function claims(input, frontHost) {
+    if (!input.host || !frontHost)
+        return false;
+    const bare = String(input.host).split(':')[0].toLowerCase();
+    if (bare !== String(frontHost).toLowerCase())
+        return false; // a pod subdomain → not ours
+    return FRONT_PATHS.has(input.pathname) || input.pathname.startsWith('/u/');
+}
+// What an identity answers on its own pod's origin: the protocol routes other
+// software addresses it by, and the one path its owner's pages live under.
+// Everything else on that origin is the pod, and falls through to CSS.
+const AGENT_PATHS = new Set(['/ap/actor', '/ap/outbox', '/.well-known/nodeinfo', '/nodeinfo/2.0']);
+const AGENT_PREFIXES = ['/api/', '/oauth/'];
+/**
+ * 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;
+    const { pathname } = input;
+    if (AGENT_PATHS.has(pathname))
+        return true;
+    if (AGENT_PREFIXES.some((prefix) => pathname.startsWith(prefix)))
+        return true;
+    // The owner's door, when there is one: '' turns the pages off entirely.
+    return uiPath !== '' && (pathname === uiPath.slice(0, -1) || pathname.startsWith(uiPath));
+}

package/dist/components/components.jsonld

@@ -0,0 +1,12 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/fedipod-server/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:fedipod-server",
+  "@type": "Module",
+  "requireName": "fedipod-server",
+  "import": [
+    "fps:dist/handler.jsonld",
+    "fps:dist/streaming-handler.jsonld"
+  ]
+}

package/dist/components/context.jsonld

@@ -0,0 +1,136 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^5.0.0/components/context.jsonld",
+    {
+      "npmd": "https://linkedsoftwaredependencies.org/bundles/npm/",
+      "fps": "npmd:fedipod-server/^0.0.0/",
+      "FediPodServerHandler": {
+        "@id": "fps:dist/handler.jsonld#FediPodServerHandler",
+        "@prefix": true,
+        "@context": {
+          "args_resourceStore": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_resourceStore"
+          },
+          "args_frontHost": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_frontHost"
+          },
+          "args_frontOrigin": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_frontOrigin"
+          },
+          "args_directoryContainer": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_directoryContainer"
+          },
+          "args_gatewayWebId": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_gatewayWebId"
+          },
+          "args_offersPods": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_offersPods"
+          },
+          "args_signupPage": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_signupPage"
+          },
+          "args_runPage": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_runPage"
+          },
+          "args_agentDataDir": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentDataDir"
+          },
+          "args_agentWebIdSuffix": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentWebIdSuffix"
+          },
+          "args_agentPollSeconds": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentPollSeconds"
+          },
+          "args_agentAutoAcceptFollows": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentAutoAcceptFollows"
+          },
+          "args_clusterManager": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_clusterManager"
+          },
+          "args_agentUiPath": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentUiPath"
+          },
+          "args_agentRuntimeOptIn": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentRuntimeOptIn"
+          },
+          "args_agentAutoFront": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentAutoFront"
+          },
+          "args_agentRegistryContainer": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentRegistryContainer"
+          },
+          "resourceStore": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_resourceStore"
+          },
+          "frontHost": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_frontHost"
+          },
+          "frontOrigin": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_frontOrigin"
+          },
+          "directoryContainer": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_directoryContainer"
+          },
+          "gatewayWebId": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_gatewayWebId"
+          },
+          "offersPods": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_offersPods"
+          },
+          "signupPage": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_signupPage"
+          },
+          "runPage": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_runPage"
+          },
+          "agentDataDir": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentDataDir"
+          },
+          "agentWebIdSuffix": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentWebIdSuffix"
+          },
+          "agentPollSeconds": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentPollSeconds"
+          },
+          "agentAutoAcceptFollows": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentAutoAcceptFollows"
+          },
+          "clusterManager": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_clusterManager"
+          },
+          "agentUiPath": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentUiPath"
+          },
+          "agentRuntimeOptIn": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentRuntimeOptIn"
+          },
+          "agentAutoFront": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentAutoFront"
+          },
+          "agentRegistryContainer": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentRegistryContainer"
+          }
+        }
+      },
+      "FediPodServerArgs": {
+        "@id": "fps:dist/handler.jsonld#FediPodServerArgs",
+        "@prefix": true,
+        "@context": {}
+      },
+      "FediPodStreamingHandler": {
+        "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler",
+        "@prefix": true,
+        "@context": {
+          "args_server": {
+            "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler_args_server"
+          }
+        }
+      },
+      "FediPodStreamingArgs": {
+        "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingArgs",
+        "@prefix": true,
+        "@context": {}
+      }
+    }
+  ]
+}

package/dist/directory.d.ts

@@ -0,0 +1,38 @@
+export interface IO {
+    read(url: string): Promise<string | null>;
+    write(url: string, body: string, contentType: string): Promise<void>;
+    /** Absence is not an error: removing what is already gone succeeds. */
+    remove?(url: string): Promise<void>;
+}
+export interface DirectoryRecord {
+    handle: string;
+    podHome: string;
+    actorUrl: string;
+    kind: string;
+    webId?: string;
+    hmacSecret?: string;
+    gatewayWebId?: string | null;
+    /** Inbox-only fronting: the row exists to resolve @handle@front and take verified delivery; the actor keeps its own ids on the pod. */
+    inboxOnly?: boolean;
+}
+export interface Directory {
+    lookup(handle: string): Promise<DirectoryRecord | null>;
+    putDirectory(handle: string, record: DirectoryRecord): Promise<void>;
+}
+export declare function makeDirectory(io: IO, containerUrl: string): Directory;
+/** A pod whose owner opted in at runtime. The door secret is never in the row. */
+export interface AgentRegistryRecord {
+    podBase: string;
+    handle: string;
+    host: string;
+    webId: string;
+    optedInAt: string;
+}
+export interface AgentRegistry {
+    listHosts(): Promise<string[]>;
+    get(host: string): Promise<AgentRegistryRecord | null>;
+    add(record: AgentRegistryRecord): Promise<void>;
+    remove(host: 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>;