fedipod-server 0.4.0

package/dist/store-pod.js

@@ -0,0 +1,148 @@
+"use strict";
+// store-pod.ts — the agent's transport, over CSS's ResourceStore instead of
+// the network. RemotePod funnels every pod operation through one fetch(), so
+// swapping that one function moves the whole agent inside the server: no
+// credential, no token, no socket to the pod it is already running in.
+//
+// The shape is WHATWG fetch because that is what RemotePod, Lease and Storage
+// already speak — ETags and If-Match included, which is what keeps the lease's
+// conditional-PUT protocol working unchanged.
+//
+// Writing here bypasses WAC by design, exactly as store-css.ts does: the agent
+// acts as the pod's owner, and the server operator put it there. `podBase`
+// confines the transport to that pod's own subtree — the store serves every
+// pod on the server, and an identity's reach must not.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeStoreFetch = makeStoreFetch;
+exports.makeStoreSession = makeStoreSession;
+const community_server_1 = require("@solid/community-server");
+/** Header lookup that does not care about case, over either shape fetch accepts. */
+function headerReader(init) {
+    const raw = init?.headers;
+    if (!raw)
+        return () => null;
+    if (typeof raw.get === 'function')
+        return (n) => raw.get(n);
+    const lower = {};
+    for (const [k, v] of Object.entries(raw))
+        lower[k.toLowerCase()] = String(v);
+    return (n) => lower[n.toLowerCase()] ?? null;
+}
+// Only Turtle needs asking for: a container's listing is quads until something
+// requests a syntax, and listContainer parses Turtle. Everything else is read
+// back exactly as it was written.
+function preferencesFor(accept) {
+    return accept?.includes('text/turtle') ? { type: { 'text/turtle': 1 } } : {};
+}
+function isNotFound(e) {
+    return community_server_1.NotFoundHttpError.isInstance?.(e) === true || e?.statusCode === 404;
+}
+/** A store path is the URL itself; a doubled slash would name a different resource. */
+function pathOf(url) {
+    const u = new URL(url);
+    u.pathname = u.pathname.replace(/\/{2,}/gu, '/');
+    u.hash = '';
+    return u.href;
+}
+async function discard(rep) {
+    rep.data.destroy();
+}
+function makeStoreFetch(resourceStore, podBase) {
+    const stats = { reads: 0, writes: 0, deletes: 0 };
+    const etags = new community_server_1.BasicETagHandler();
+    const base = podBase ? new URL(podBase).href : null;
+    const respond = (status, body, etag, contentType) => {
+        const headers = {};
+        if (etag)
+            headers.etag = etag;
+        if (contentType)
+            headers['content-type'] = contentType;
+        return new Response(status === 204 || status === 205 || status === 304 ? null : body, { status, headers });
+    };
+    const fetchImpl = async (url, init = {}) => {
+        const method = (init.method ?? 'GET').toUpperCase();
+        const header = headerReader(init);
+        const identifier = { path: pathOf(url) };
+        // Confinement, not access control: every legitimate target is under the
+        // pod's own base, so anything else is a bug or an escape — refused here
+        // rather than answered with another pod's resource.
+        if (base && !identifier.path.startsWith(base))
+            return respond(403, 'outside this pod');
+        if (method === 'GET' || method === 'HEAD') {
+            stats.reads++;
+            let rep;
+            try {
+                rep = await resourceStore.getRepresentation(identifier, preferencesFor(header('accept')));
+            }
+            catch (e) {
+                if (isNotFound(e))
+                    return respond(404, 'Not Found');
+                throw e;
+            }
+            const etag = etags.getETag(rep.metadata);
+            const noneMatch = header('if-none-match');
+            // Weak comparison, per RFC 7232 — the drain re-reads the inbox listing
+            // every couple of minutes and it is usually the same listing.
+            if (etag && noneMatch && noneMatch.split(',').some((t) => etags.matchesETag(rep.metadata, t.trim(), false))) {
+                await discard(rep);
+                return respond(304, null, etag);
+            }
+            const contentType = rep.metadata.contentType;
+            if (method === 'HEAD') {
+                await discard(rep);
+                return respond(200, null, etag, contentType);
+            }
+            return respond(200, await (0, community_server_1.readableToString)(rep.data), etag, contentType);
+        }
+        if (method === 'PUT') {
+            stats.writes++;
+            const ifMatch = header('if-match');
+            const conditions = ifMatch
+                ? new community_server_1.BasicConditions(etags, { matchesETag: ifMatch.split(',').map((t) => t.trim()) })
+                : undefined;
+            const contentType = header('content-type') ?? 'application/octet-stream';
+            const rep = new community_server_1.BasicRepresentation(String(init.body ?? ''), identifier, contentType);
+            let changes;
+            try {
+                changes = await resourceStore.setRepresentation(identifier, rep, conditions);
+            }
+            catch (e) {
+                if (community_server_1.PreconditionFailedHttpError.isInstance?.(e))
+                    return respond(412, 'Precondition Failed');
+                throw e;
+            }
+            // The lease renews with a conditional PUT, so hand back the new ETag when
+            // the store reported one; without it the lease re-reads first, which is
+            // slower but just as correct.
+            const written = changes?.get?.(identifier);
+            return respond(205, null, written && etags.getETag(written));
+        }
+        if (method === 'DELETE') {
+            stats.deletes++;
+            try {
+                await resourceStore.deleteResource(identifier);
+            }
+            catch (e) {
+                if (isNotFound(e))
+                    return respond(404, 'Not Found');
+                throw e;
+            }
+            return respond(205, null);
+        }
+        throw new community_server_1.NotImplementedHttpError(`${method} is not something the pod store can answer`);
+    };
+    fetchImpl.stats = () => ({ ...stats });
+    return fetchImpl;
+}
+/**
+ * The session shape RemotePod consumes — the same three members its
+ * credential-backed session has, so the class itself needs no other change.
+ */
+function makeStoreSession(resourceStore, podBase) {
+    const storeFetch = makeStoreFetch(resourceStore, podBase);
+    return {
+        fetch: storeFetch,
+        warmup: async () => undefined, // nothing to mint
+        stats: () => storeFetch.stats(),
+    };
+}

package/dist/streaming-handler.d.ts

@@ -0,0 +1,14 @@
+import { WebSocketHandler } from '@solid/community-server';
+import type { WebSocketHandlerInput } from '@solid/community-server';
+import type { FediPodServerHandler } from './handler';
+export interface FediPodStreamingArgs {
+    /** The server handler, which owns the running identities. */
+    server: FediPodServerHandler;
+}
+export declare class FediPodStreamingHandler extends WebSocketHandler {
+    private readonly server;
+    private readonly logger;
+    constructor(args: FediPodStreamingArgs);
+    canHandle({ upgradeRequest }: WebSocketHandlerInput): Promise<void>;
+    handle({ webSocket, upgradeRequest }: WebSocketHandlerInput): Promise<void>;
+}

package/dist/streaming-handler.js

@@ -0,0 +1,47 @@
+"use strict";
+// streaming-handler.ts — the Mastodon live feed, on the pod's own origin.
+//
+// A second class rather than more of the server handler: CSS routes websocket
+// upgrades through a waterfall of its own, whose handlers take a socket rather
+// than a request and response, and one class cannot be both. It shares the
+// server handler’s state by holding the same instance, so a socket is handed
+// to the identity that owns the host it arrived on.
+//
+// CSS completes the handshake before any of this runs, so a client that may not
+// listen is closed rather than refused — there is no status code left to send.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FediPodStreamingHandler = void 0;
+const community_server_1 = require("@solid/community-server");
+const STREAMING_PATH = '/api/v1/streaming';
+class FediPodStreamingHandler extends community_server_1.WebSocketHandler {
+    server;
+    logger = (0, community_server_1.getLoggerFor)(this);
+    constructor(args) {
+        super();
+        this.server = args.server;
+    }
+    async canHandle({ upgradeRequest }) {
+        const host = upgradeRequest.headers.host;
+        const { pathname } = new URL(upgradeRequest.url ?? '/', `http://${host}`);
+        if (!pathname.startsWith(STREAMING_PATH) || !this.server.surfaceFor(host)) {
+            throw new Error('not a FediPod streaming socket');
+        }
+    }
+    async handle({ webSocket, upgradeRequest }) {
+        const identity = this.server.surfaceFor(upgradeRequest.headers.host);
+        const streaming = identity?.surface?.streaming;
+        if (!streaming) {
+            webSocket.close(1011, 'identity not running');
+            return;
+        }
+        const url = new URL(upgradeRequest.url ?? '/', `http://${upgradeRequest.headers.host}`);
+        const refusal = streaming.authorizeUpgrade(upgradeRequest, url);
+        if (refusal) {
+            this.logger.info(refusal);
+            webSocket.close(1008, refusal);
+            return;
+        }
+        streaming.adopt(webSocket);
+    }
+}
+exports.FediPodStreamingHandler = FediPodStreamingHandler;

package/dist/streaming-handler.jsonld

@@ -0,0 +1,72 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/fedipod-server/^0.0.0/components/context.jsonld",
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^7.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:fedipod-server",
+  "components": [
+    {
+      "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler",
+      "@type": "Class",
+      "requireElement": "FediPodStreamingHandler",
+      "extends": [
+        "css:dist/server/WebSocketHandler.jsonld#WebSocketHandler"
+      ],
+      "parameters": [
+        {
+          "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler_args_server",
+          "range": "fps:dist/handler.jsonld#FediPodServerHandler",
+          "comment": "The server handler, which owns the running identities."
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler__member_server",
+          "memberFieldName": "server"
+        },
+        {
+          "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler__member_logger",
+          "memberFieldName": "logger"
+        },
+        {
+          "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler__member_canHandle",
+          "memberFieldName": "canHandle"
+        },
+        {
+          "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler__member_handle",
+          "memberFieldName": "handle"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler_args__constructorArgument",
+          "fields": [
+            {
+              "keyRaw": "server",
+              "value": {
+                "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingHandler_args_server"
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingArgs",
+      "@type": "AbstractClass",
+      "requireElement": "FediPodStreamingArgs",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "fps:dist/streaming-handler.jsonld#FediPodStreamingArgs__member_server",
+          "memberFieldName": "server"
+        }
+      ],
+      "constructorArguments": []
+    }
+  ]
+}

package/fedipod-server.svg

@@ -0,0 +1,134 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1620 1140" width="1620" height="1140" font-family="system-ui, sans-serif" role="img" aria-labelledby="ttl dsc">
+<title id="ttl">FediPod Server, a Community Solid Server component</title>
+<desc id="dsc">One Community Solid Server hosting many pods, with the FediPod component installed, and down the right-hand side everyone who talks to it. The open social web delivers mail and looks things up: some of that reaches the component, and the rest reaches pod storage directly, because a pod's public record and its inbox are ordinary pod resources the server already serves. Mei's phone and Tamara's laptop sign in, read and post; any authorized Solid app reads and writes the pods directly, except the paths the component claims. Inside, the component is the same FediPod Agent running in the server's own process, in two parts. The endpoints it serves are, on each pod's own address, the client API an app signs in to, the owner's pages behind that owner's own secret, and the live feed; and on the shared address, the front, and the door that verifies deliveries for the handles it fronts. The work it does for each pod is accepting a follow, delivering a post, emptying the inbox, and holding the lease so only one agent at a time acts. Below, server storage holds, outside every pod, each identity's signing key and door secret, plus a handle directory and the opt-in list when the server serves other people; an identity's log goes to the server's own log. Pod storage is one pod per identity, each holding that identity's public face, its inbox and its private state, written directly with no credential and no second connection, and a pod owner opts in from there.</desc>
+<style>
+  .t    { font-size: 18px; font-weight: 600; fill: #1a1a19; }
+  .d    { font-size: 16px; fill: #333; }
+  .sub  { font-size: 15px; fill: #666; }
+  .lbl  { font-size: 15px; fill: #555; }
+  .cc   { font-size: 11px; font-weight: 400; font-style: italic; fill: #555; }
+  .arrow  { stroke: #555; stroke-width: 2; fill: none; marker-end: url(#arr); }
+  .arrow2 { stroke: #555; stroke-width: 2; fill: none; marker-end: url(#arr); marker-start: url(#arr); }
+</style>
+<defs>
+  <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+    <path d="M0,0 L10,5 L0,10 z" fill="#555"/>
+  </marker>
+</defs>
+
+<rect width="1620" height="1140" fill="#ffffff"/>
+
+<!-- ===== the server ===== -->
+<rect x="40" y="40" width="1060" height="1050" rx="12" fill="#f7f6f2" stroke="#9a988f"/>
+<text class="t" x="570" y="80" text-anchor="middle">One Community Solid Server, hosting many pods, with the FediPod component installed</text>
+<text class="sub" x="570" y="104" text-anchor="middle">the pods it already served, and a fediverse identity for each user who opts in</text>
+
+<!-- ===== processing ===== -->
+<rect x="64" y="128" width="1012" height="518" rx="12" fill="#fdeeee" stroke="#b87a7a"/>
+<text class="t" x="570" y="164" text-anchor="middle">Processing — the same FediPod Agent, running inside the server</text>
+
+<text class="sub" x="88" y="196">the endpoints it serves, on each pod's own address</text>
+<rect x="88" y="206" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="106" y="234">The client API</text>
+<text class="sub" x="106" y="256">what a Mastodon app signs in to</text>
+<rect x="88" y="286" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="106" y="314">The owner's pages</text>
+<text class="sub" x="106" y="336">the record and a web client, behind their own secret</text>
+<rect x="88" y="366" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="106" y="394">The live feed</text>
+<text class="sub" x="106" y="416">a socket a client holds open</text>
+
+<text class="sub" x="88" y="464">and on the shared address</text>
+<rect x="88" y="474" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="106" y="502">The front</text>
+<text class="sub" x="106" y="524">signup, name lookups and attach</text>
+<rect x="88" y="554" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="106" y="582">The door</text>
+<text class="sub" x="106" y="604">verifies deliveries for the handles it fronts</text>
+
+<text class="sub" x="584" y="196">the work it does, for each pod it runs</text>
+<rect x="584" y="206" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="602" y="234">Accepts a follow</text>
+<text class="sub" x="602" y="256">answers as that pod's owner</text>
+<rect x="584" y="286" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="602" y="314">Delivers a post</text>
+<text class="sub" x="602" y="336">signs it and sends it on</text>
+<rect x="584" y="366" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="602" y="394">Empties the inbox</text>
+<text class="sub" x="602" y="416">reads what arrived, then clears it</text>
+<rect x="584" y="446" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="602" y="474">Holds the lease</text>
+<text class="sub" x="602" y="496">so only one agent at a time acts on a pod</text>
+
+<!-- ===== processing <-> storage ===== -->
+<path class="arrow" d="M 298 648 L 298 742"/>
+<text class="lbl" x="286" y="678" text-anchor="end">keeps each identity's</text>
+<text class="lbl" x="286" y="700" text-anchor="end">signing key and door secret</text>
+
+<path class="arrow" d="M 798 648 L 798 742"/>
+<text class="lbl" x="786" y="678" text-anchor="end">writes directly to each user's pod</text>
+<text class="lbl" x="786" y="700" text-anchor="end">no credential, no second connection</text>
+
+<path class="arrow" d="M 838 742 L 838 648"/>
+<text class="lbl" x="850" y="678">user opts in to have a</text>
+<text class="lbl" x="850" y="700">fediverse account on their pod</text>
+
+<!-- ===== server storage ===== -->
+<rect x="64" y="746" width="468" height="320" rx="12" fill="#f2ece0" stroke="#b09a5e"/>
+<text class="t" x="298" y="782" text-anchor="middle">Server storage</text>
+<text class="sub" x="298" y="806" text-anchor="middle">on the server, outside every pod</text>
+<text class="sub" x="298" y="826" text-anchor="middle">an identity's log goes to the server's own log</text>
+<rect x="88" y="852" width="420" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="106" y="880">A signing key per identity</text>
+<text class="sub" x="106" y="902">what it means to be able to post as them</text>
+<rect x="88" y="932" width="420" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="106" y="960">A door secret per identity</text>
+<text class="sub" x="106" y="982">opens that identity's pages, nobody else's</text>
+<rect x="88" y="1012" width="420" height="46" rx="10" fill="#ffffff" stroke="#c9c7bf" stroke-dasharray="4 4"/>
+<text class="sub" x="106" y="1040">a handle directory and the opt-in list, if it serves others</text>
+
+<!-- ===== pod storage ===== -->
+<rect x="584" y="746" width="468" height="320" rx="12" fill="#e7f2e7" stroke="#6a9a6a"/>
+<text class="t" x="818" y="782" text-anchor="middle">Pod storage — one pod per identity</text>
+<text class="sub" x="818" y="806" text-anchor="middle">addressable by Solid and by ActivityPub</text>
+<rect x="608" y="832" width="420" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="626" y="860">mei.example.org</text>
+<text class="sub" x="626" y="882">public face, inbox, and her agent's private state</text>
+<rect x="608" y="912" width="420" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
+<text class="d" x="626" y="940">tamara.example.org</text>
+<text class="sub" x="626" y="962">the same again, hers alone</text>
+<rect x="608" y="992" width="420" height="46" rx="10" fill="#ffffff" stroke="#c9c7bf" stroke-dasharray="4 4"/>
+<text class="sub" x="626" y="1020">and every other pod this server hosts, untouched</text>
+
+<!-- ===== everyone who talks to it ===== -->
+<rect x="1160" y="170" width="340" height="104" rx="12" fill="#f0e9f5" stroke="#9a7ab0"/>
+<text class="t" x="1330" y="206" text-anchor="middle">Mei's phone</text>
+<text class="d" x="1330" y="234" text-anchor="middle">any mobile Mastodon client</text>
+<text class="d" x="1330" y="256" text-anchor="middle">signs in, reads, posts</text>
+<path class="arrow2" d="M 1158 222 L 1080 222"/>
+
+<rect x="1160" y="310" width="340" height="104" rx="12" fill="#f0e9f5" stroke="#9a7ab0"/>
+<text class="t" x="1330" y="346" text-anchor="middle">Tamara's laptop</text>
+<text class="d" x="1330" y="374" text-anchor="middle">browser or native app</text>
+<text class="d" x="1330" y="396" text-anchor="middle">signs in, reads, posts</text>
+<path class="arrow2" d="M 1158 362 L 1080 362"/>
+
+<rect x="1160" y="450" width="340" height="126" rx="12" fill="#eef1f8" stroke="#7a88b8"/>
+<text class="t" x="1330" y="486" text-anchor="middle">The open social web</text>
+<text class="d" x="1330" y="514" text-anchor="middle">Mastodon, Lemmy, PeerTube,</text>
+<text class="d" x="1330" y="536" text-anchor="middle">anyone else</text>
+<text class="d" x="1330" y="558" text-anchor="middle">delivers mail, and looks things up</text>
+<path class="arrow2" d="M 1158 513 L 1080 513"/>
+<path class="arrow2" d="M 1330 578 L 1330 906 L 1058 906"/>
+<text class="lbl" x="1348" y="734">to the pod — mail into its inbox</text>
+<text class="lbl" x="1348" y="756">from the pod — its public record</text>
+
+<rect x="1160" y="940" width="340" height="126" rx="12" fill="#f1efe8" stroke="#9a988f"/>
+<text class="t" x="1330" y="976" text-anchor="middle">Any authorized Solid app</text>
+<text class="d" x="1330" y="1004" text-anchor="middle">reads and writes the pod,</text>
+<text class="d" x="1330" y="1026" text-anchor="middle">except the paths the</text>
+<text class="d" x="1330" y="1048" text-anchor="middle">component claims</text>
+<path class="arrow2" d="M 1158 1003 L 1056 1003"/>
+
+<text class="cc" x="1580" y="1120" text-anchor="end">(cc) 4.0 By, Jeff Zucker, 2026</text>
+</svg>

package/lib/account.mjs

@@ -0,0 +1,87 @@
+// account.mjs — create a brand-new account + pod on a CSS server (v7 account
+// API), the `setup --new-account` path. Public-server sibling of
+// data-kitchen's seed-account.cjs, but simpler: the pod.create control makes
+// the pod AND its WebID in one step — no ownership challenge, because the
+// server authors the WebID itself.
+//
+// Flow: POST .account/account/ (or login when the email already exists) →
+// password.create → account.pod {name} → { pod, webId }.
+
+async function jfetch(url, { method = 'GET', body, cookie } = {}) {
+  const headers = { accept: 'application/json' };
+  if (body !== undefined) headers['content-type'] = 'application/json';
+  if (cookie) headers.cookie = cookie;
+  const res = await fetch(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+  let json = null;
+  try { json = await res.json(); } catch { /* non-JSON */ }
+  return { status: res.status, json };
+}
+
+export async function createAccountWithPod({ issuer, email, password, podName }) {
+  const origin = issuer.replace(/\/+$/, '');
+  const accountRoot = `${origin}/.account/`;
+
+  // Authenticate: log in when the email is already registered (idempotent
+  // re-runs), otherwise create the account and set its password.
+  let cookie;
+  const login = await jfetch(`${accountRoot}login/password/`, { method: 'POST', body: { email, password } });
+  if (login.status < 400 && login.json?.authorization) {
+    cookie = `css-account=${login.json.authorization}`;
+  } else {
+    const create = await jfetch(`${accountRoot}account/`, { method: 'POST' });
+    if (!create.json?.authorization) {
+      throw new Error(`account create failed (HTTP ${create.status}): ${create.json?.message || 'is this a CSS server with signup enabled?'}`);
+    }
+    cookie = `css-account=${create.json.authorization}`;
+    const pwCreate = (await jfetch(accountRoot, { cookie })).json?.controls?.password?.create;
+    if (!pwCreate) throw new Error('password.create control missing — not a CSS v7 account API');
+    const pw = await jfetch(pwCreate, { method: 'POST', cookie, body: { email, password } });
+    if (pw.status >= 400) throw new Error(`password create failed (HTTP ${pw.status}): ${pw.json?.message || ''}`);
+  }
+
+  // Create the pod (server picks root-path or subdomain layout). When the
+  // name is already taken BY THIS ACCOUNT — a setup re-run, or a pod made
+  // earlier by hand — reuse it; taken by someone else stays a hard error.
+  const controls = (await jfetch(accountRoot, { cookie })).json?.controls;
+  const podCreate = controls?.account?.pod;
+  if (!podCreate) throw new Error('pod create control missing — not a CSS v7 account API');
+  // Scheme-agnostic on purpose: matching `https://name.` missed every pod on an
+  // http server, so a re-run after a crashed setup always tried to create again
+  // and died on "already registered to this account".
+  const findOwn = async () => {
+    const pods = (await jfetch(podCreate, { cookie })).json?.pods || {};
+    return Object.entries(pods).find(([url]) => {
+      try {
+        const u = new URL(url);
+        return u.hostname === podName || u.hostname.startsWith(`${podName}.`)
+          || u.pathname.split('/').filter(Boolean).includes(podName);
+      } catch { return false; }
+    }) || null;
+  };
+  // One pod per account, refused BEFORE anything is created. A second pod gives
+  // the account a second WebID, and a credential can only be bound to one of
+  // them — so the second actor authenticates and then 403s every write to its
+  // own pod. Reusing a pod of the same name is still fine: that is a re-run of
+  // a setup, not a second identity.
+  const owned = Object.keys((await jfetch(podCreate, { cookie })).json?.pods || {});
+  if (owned.length && !await findOwn()) {
+    throw new Error(`${email} already has a pod on ${new URL(origin).host}: ${owned[0]} — `
+      + 'one account, one pod. A second actor needs its own account and email. '
+      + 'Nothing was created.');
+  }
+  const made = await jfetch(podCreate, { method: 'POST', cookie, body: { name: podName } });
+  let pod = made.json?.pod || made.json?.podBaseUrl || null;
+  let webId = made.json?.webId || null;
+  if (made.status >= 400 || !pod) {
+    const own = await findOwn();
+    if (own) {
+      pod = own[0];
+      webId = webId || own[1]?.webId || null;
+    } else if (made.status >= 400) {
+      throw new Error(`pod create failed (HTTP ${made.status}): ${made.json?.message || `is the name "${podName}" taken by another account?`}`);
+    }
+  }
+  if (!pod) throw new Error('pod created but its URL was not reported — check the account dashboard');
+  pod = pod.endsWith('/') ? pod : pod + '/';
+  return { pod, webId: webId || new URL('profile/card#me', pod).href };
+}