fedipod-server 0.9.0 → 0.11.0

package/lib/pod/inbox.mjs

@@ -0,0 +1,144 @@
+// inbox.mjs — ap/inbox/: what arrives, and who may touch it.
+//
+// One file for the whole inbox, because the inbox is where two different
+// parties meet and neither half is comprehensible alone: a delivery gateway
+// may only ADD to it, holding at most an Append token; the owner's agent
+// lists, reads and removes, holding the pod's own credential. Splitting them
+// by who does them would put the two ends of one contract in two files.
+
+const DELIVERY_CT = 'application/activity+json';
+const RECEIPT_CT = 'application/json';
+
+// ---- a delivery gateway: appends verified mail, and can do nothing else ----
+
+/**
+ * PUT one document into a pod inbox, with an Append token when the caller
+ * holds one and anonymously when it does not.
+ *
+ * Sending no `authorization` header is not the same as sending an empty one:
+ * `Bearer undefined` is a credential the pod will reject, where absence is a
+ * public Append the pod may well allow. This is the one place that gets to
+ * decide that, because it lived in two adapters and had to be right in both.
+ *
+ * @returns {Promise<boolean>} whether it landed
+ */
+export async function appendWithToken(url, body, contentType, { appendToken = null, fetchImpl = fetch } = {}) {
+  const headers = { 'content-type': contentType,
+    ...(appendToken ? { authorization: `Bearer ${appendToken}` } : {}) };
+  const r = await fetchImpl(url, { method: 'PUT', headers, body }).catch(() => null);
+  return !!r && r.status < 400;
+}
+
+/**
+ * The delivery itself, named by the hash of its own bytes.
+ *
+ * Content-addressed on purpose: the same activity delivered twice writes the
+ * same document twice, so a retrying origin cannot produce duplicates in
+ * someone's inbox.
+ *
+ * A failure here must reach the ORIGIN as a 5xx so it retries over its own
+ * ladder — that is what preserves the pod's buffer property without the
+ * gateway holding any state of its own.
+ */
+export async function appendVerifiedDelivery(podPut, inboxUrl, hash, raw) {
+  return podPut(inboxUrl + hash, raw, DELIVERY_CT);
+}
+
+/**
+ * The verification receipt, written beside the delivery it vouches for.
+ *
+ * Best-effort by design: a delivery that landed but whose receipt did not is
+ * read as unverified at the drain, which is a lesser thing than losing it.
+ */
+export async function writeReceiptBeside(podPut, inboxUrl, hash, receipt) {
+  await podPut(inboxUrl + hash + '.receipt.json', JSON.stringify(receipt), RECEIPT_CT)
+    .catch(() => {});
+}
+
+// ---- the owner's agent: brings it into being and decides who may post ----
+
+/**
+ * The canary that makes the container exist.
+ *
+ * Written without an access rule of its own, because the rule that matters is
+ * the container's and is stated separately — see setPosture, which a caller
+ * must reach for deliberately rather than inherit by accident.
+ */
+export async function writeKeep(pod, urls) {
+  await pod.putJson(urls.inbox + '.keep', { keep: true }, 'application/json');
+}
+
+/**
+ * Who may deliver here.
+ *
+ *   'open'                 anyone may Append — an inbox the fediverse can post to
+ *   'closed'               nobody may — a quiesced actor, still resolving, taking no mail
+ *   { gatewayWebId }       only that WebID may — mail arrives through a door that
+ *                          verifies it first, and nobody may go round the door
+ *
+ * One operation because the three are one decision, and they were made in five
+ * places: the profile publish, three separate methods, and the manage surface
+ * reaching past all of them to set the ACL directly. A posture set in one of
+ * those and not the others is an inbox that is open when it should be shut.
+ */
+export async function setPosture(pod, urls, posture) {
+  if (posture === 'open') return pod.setAcl(urls.inbox, ['Append']);
+  if (posture === 'closed') return pod.setAcl(urls.inbox, []);
+  const webId = posture?.gatewayWebId;
+  if (!webId) throw new Error(`inbox.setPosture: unknown posture ${JSON.stringify(posture)}`);
+  // Public loses Append; the door keeps it. Both halves in one write, because
+  // between two writes the inbox is either open to everyone or shut to the door.
+  return pod.setAcl(urls.inbox, [], { appendAgents: [webId] });
+}
+
+/**
+ * What is waiting, oldest first.
+ *
+ * A defensive copy, because the transport hands back the SAME array on a 304
+ * and the inbox is polled constantly — a caller that sorted or spliced in
+ * place would corrupt the cache for every later reader.
+ */
+export async function list(pod, urls) {
+  const children = await pod.listContainer(urls.inbox);
+  return children.map((c) => ({ ...c }));
+}
+
+/**
+ * One item's bytes.
+ *
+ * A pod that would not GIVE us the item has told us nothing about it. Reading
+ * a 500 as an empty body once made it "unparsable JSON" — which is a
+ * REJECTION, so the delivery was dead-lettered with nothing recorded and then
+ * DELETED: destroyed by a transient fault, with no trace of what it had been.
+ * Anything but 404 throws, and the caller's retry path takes it. 404 is the
+ * exception: the item is already gone, so removing it is right.
+ *
+ * Capped rather than read whole: the listing's size is advisory, the inbox is
+ * public-Append, and the body is whatever a stranger chose to send.
+ *
+ * @returns {Promise<{status:number, raw:string|null}>}
+ */
+export async function readItem(pod, url, { maxBytes, readCapped }) {
+  const res = await pod.fetch(url, { headers: { accept: '*/*' } });
+  if (res.status >= 400 && res.status !== 404) throw new Error(`inbox item GET → ${res.status}`);
+  return { status: res.status, raw: res.status < 400 ? await readCapped(res, maxBytes) : null };
+}
+
+/** The gateway's receipt for an item, unparsed and unverified, or null. */
+export async function readDeliveryReceipt(pod, itemUrl, { maxBytes, readCapped }) {
+  const res = await pod.fetch(itemUrl + '.receipt.json', { headers: { accept: 'application/json' } });
+  if (res.status >= 400) return null;
+  return JSON.parse(await readCapped(res, maxBytes));
+}
+
+/**
+ * Remove an item that has been dealt with.
+ *
+ * This must NOT know about the caller's state: the drain deletes only after
+ * its own state write has landed, and folding that gate in here would put the
+ * decision somewhere with no view of whether it did. Getting that wrong
+ * deletes deliveries whose record never persisted — silent, and unrecoverable.
+ *
+ * @returns {Promise<boolean>} whether the pod removed it
+ */
+export const dropHandledItem = (pod, url) => pod.delete(url);

package/lib/pod/links.mjs

@@ -0,0 +1,35 @@
+// links.mjs — reading RFC 8288 Link headers.
+//
+// Solid says where a resource's access control lives, where a storage
+// describes itself, and who owns a storage, by putting a link on the response.
+// Working any of those out from the resource's own URL instead is exactly what
+// the specs tell clients not to do, so this is the one place that reads them.
+
+/**
+ * Every target a Link header gives for one relation, resolved against the URL
+ * the header came from. A header may carry several links, and one link may
+ * carry several relation names.
+ */
+export function linkTargets(headerValue, rel, baseUrl) {
+  if (!headerValue) return [];
+  const wanted = String(rel).toLowerCase();
+  const out = [];
+  // Split on the commas BETWEEN links: one inside a URI has its closing angle
+  // bracket still ahead of it, and is left alone.
+  for (const part of String(headerValue).split(/,(?![^<]*>)/u)) {
+    const link = /^\s*<([^>]*)>\s*(.*)$/u.exec(part);
+    if (!link) continue;
+    const relParam = /(?:^|;)\s*rel\s*=\s*(?:"([^"]*)"|([^;"\s]+))/iu.exec(link[2]);
+    const names = (relParam?.[1] ?? relParam?.[2] ?? '').toLowerCase().split(/\s+/u);
+    if (!names.includes(wanted)) continue;
+    try { out.push(new URL(link[1], baseUrl).href); } catch { /* not a URL we can follow */ }
+  }
+  return out;
+}
+
+/** The relations this library follows. */
+export const REL = {
+  acl: 'acl',
+  storageDescription: 'http://www.w3.org/ns/solid/terms#storageDescription',
+  owner: 'http://www.w3.org/ns/solid/terms#owner',
+};

package/lib/pod/media.mjs

@@ -0,0 +1,27 @@
+// media.mjs — ap/media/: the bytes an attachment points at.
+//
+// The only tree here holding things that are not documents. Public-Read,
+// because an attachment url travels inside a post to servers that will fetch
+// it without credentials — and unlike an actor or a note, nothing checks that
+// the url belongs to the identity that posted it, which is why media stays on
+// the pod even for an identity whose ids are advertised elsewhere: proxying
+// blobs would be pure cost for no verification gained.
+
+const PUBLIC_READ = ['Read'];
+
+// ---- the owner's agent ----
+
+export async function provisionContainer(pod, urls) {
+  await pod.putJson(urls.media + '.keep', { keep: true }, 'application/json');
+  await pod.setAcl(urls.media, PUBLIC_READ);
+}
+
+/**
+ * One uploaded file.
+ *
+ * Takes the container as given: an upload into a container that was never
+ * provisioned is a 404, or worse a file nobody outside can read, so the caller
+ * ensures the container first — see provisionContainer, and the `exists` probe
+ * in containers.mjs that keeps a worker restart from re-provisioning.
+ */
+export const write = (pod, url, bytes, contentType) => pod.put(url, bytes, contentType);

package/lib/pod/notes.mjs

@@ -0,0 +1,80 @@
+// notes.mjs — ap/notes/: the posts themselves, and the two documents each one
+// drags with it.
+//
+// A published post is not one document. It is the Note, the Create activity
+// that announced it, and a replies collection remote servers will dereference
+// — and they have different lifetimes, which is the whole reason this file
+// exists. Deleting a post REPLACES the Note with a Tombstone (a peer learns
+// the post was deleted, rather than getting a bare 404 it reads as a temporary
+// failure) while DELETING the Create outright, because the Create was an
+// action that has been withdrawn rather than an object that still exists.
+//
+// The container is public-Read and the notes inherit it. The Tombstone is the
+// exception that has to state its own rule: a private post lives in a
+// different, owner-only container, so there is nothing public to inherit.
+
+const PUBLIC_READ = ['Read'];
+
+// ---- the owner's agent ----
+
+/** The notes container itself, public-Read so everything under it inherits. */
+export async function provisionContainer(pod, urls) {
+  await pod.putJson(urls.notes + '.keep', { keep: true }, 'application/json');
+  await pod.setAcl(urls.notes, PUBLIC_READ);
+}
+
+/** The Note. Inherits the container's rule; states none of its own. */
+export const write = (pod, noteId, doc) => pod.putJson(noteId, doc);
+
+/** The Create that announced it — its own document, at a derived id. */
+export const writeCreate = (pod, createId, doc) => pod.putJson(createId, doc);
+
+/**
+ * An empty replies collection, written with the note.
+ *
+ * Remote servers dereference `replies`, and a dangling pointer that 404s is
+ * worse than no pointer at all.
+ */
+export const writeEmptyReplies = (pod, repliesId, doc) => pod.putJson(repliesId, doc);
+
+/** The replies collection as it stands. */
+export const readReplies = (pod, repliesId) => pod.getJson(repliesId);
+export const writeReplies = (pod, repliesId, doc) => pod.putJson(repliesId, doc);
+
+/** One published note, as the pod currently serves it. */
+export const read = (pod, noteId) => pod.getJson(noteId);
+
+/**
+ * Replace a note with a Tombstone, and keep it readable.
+ *
+ * The Read rule is stated explicitly here even though the public container
+ * grants it: a private or direct post lives in the owner-only container, and
+ * its Tombstone still has to be fetchable by the servers being told about the
+ * deletion.
+ */
+export async function writeTombstone(pod, noteId, doc) {
+  await pod.putJson(noteId, doc);
+  await pod.setAcl(noteId, PUBLIC_READ);
+}
+
+/** Withdraw the Create. Returns whether the pod actually removed it. */
+export const dropCreate = (pod, createId) => pod.delete(createId).catch(() => false);
+
+/** The replies collection, once the note it belonged to is gone. */
+export const dropReplies = (pod, repliesId) => pod.delete(repliesId).catch(() => {});
+
+/**
+ * What the container holds, with the derived documents filtered out.
+ *
+ * A listing returns the Note, its `-create` and its `-replies` alike; only the
+ * first is a post, and handing the other two to a reader that expects posts
+ * produces failures that read like corruption.
+ */
+export async function list(pod, urls) {
+  const children = await pod.listContainer(urls.notes);
+  return children
+    .filter((c) => !/(-create|-replies)$/.test(c.url) && !c.url.endsWith('.keep'))
+    // A defensive copy: the transport hands back the same array on a 304, so a
+    // caller that sorts in place would corrupt it for every later reader.
+    .map((c) => ({ ...c }));
+}

package/lib/pod/notifications.mjs

@@ -0,0 +1,89 @@
+// notifications.mjs — being told when the inbox changes, instead of asking.
+//
+// A pod that offers Solid Notifications lets a client open a socket and hear
+// about a container the moment it changes, which is the difference between
+// mail arriving and mail being noticed two minutes later. Discovering that
+// service takes two unauthenticated reads of the pod's own description, and
+// then one authenticated POST to subscribe.
+//
+// This is the ONLY module here that parses RDF itself, which is why it is its
+// own file: a service that only ever appends to an inbox can import inbox.mjs
+// without pulling a parser in behind it.
+
+import * as $rdf from 'rdflib';
+import { readCapped } from './http.mjs';
+import { linkTargets, REL } from './links.mjs';
+
+const RDF = $rdf.Namespace('http://www.w3.org/1999/02/22-rdf-syntax-ns#');
+const NOTIFY = $rdf.Namespace('http://www.w3.org/ns/solid/notifications#');
+const WS_CHANNEL = 'WebSocketChannel2023';
+
+// ---- anyone at all: a pod describes its own services publicly ----
+
+/**
+ * Where this pod describes the services it offers.
+ *
+ * The pod says so on any response about one of its resources; the well-known
+ * path is only what a pod that says nothing has always used. Unauthenticated
+ * on purpose — this is a public fact about the server, asked before there is
+ * anything to authenticate about.
+ */
+export async function storageDescriptionUrl(podBase, { fetchImpl = fetch, headers = {}, timeoutMs = 20_000 } = {}) {
+  try {
+    const head = await fetchImpl(podBase, {
+      method: 'HEAD', headers, signal: AbortSignal.timeout(timeoutMs),
+    });
+    const [found] = linkTargets(head.headers.get('link'), REL.storageDescription, podBase);
+    if (found) return found;
+  } catch { /* the well-known path below */ }
+  return podBase + '.well-known/solid';
+}
+
+/**
+ * The websocket channel service this pod offers, or null when it offers none.
+ *
+ * Asked of rdflib rather than pattern-matched: the description is RDF, and the
+ * gap between "a string that appears in the document" and "the service this
+ * pod actually advertises" is where quiet bugs live. A pod may name the type
+ * on the service, or name the service's channelType — both are asked for.
+ */
+export async function readWebSocketChannel(descUrl, { fetchImpl = fetch, headers = {}, timeoutMs = 20_000 } = {}) {
+  const res = await fetchImpl(descUrl, {
+    headers: { accept: 'text/turtle', ...headers },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const g = $rdf.graph();
+  try {
+    $rdf.parse(await readCapped(res), g, descUrl, 'text/turtle');
+  } catch (e) {
+    return { channel: null, error: `service description unparsable (${e.message})` };
+  }
+  const channel = g.each(null, RDF('type'), NOTIFY(WS_CHANNEL), null).map((n) => n.value).find(Boolean)
+    || g.each(null, NOTIFY('channelType'), NOTIFY(WS_CHANNEL), null).map((n) => n.value).find(Boolean);
+  return { channel: channel || null, error: channel ? null : `no ${WS_CHANNEL} service` };
+}
+
+// ---- the owner's agent ----
+
+/**
+ * Subscribe to changes on the inbox.
+ *
+ * `podTopicUrl` is POD-SPACE, and the parameter is named that way because
+ * getting it wrong fails in a way nothing else here does: the topic travels in
+ * the BODY, so the advertised-to-pod url map a transport applies to the
+ * request LINE never reaches it. An identity whose ids are advertised
+ * elsewhere would name a container the pod cannot grant read on, and the
+ * subscription comes back 403.
+ */
+export async function subscribeToInbox(pod, { channelUrl, podTopicUrl, ...rest }) {
+  return pod.fetch(channelUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/ld+json' },
+    body: JSON.stringify({
+      '@context': ['https://www.w3.org/ns/solid/notification/v1'],
+      type: `http://www.w3.org/ns/solid/notifications#${WS_CHANNEL}`,
+      topic: podTopicUrl,
+      ...rest,
+    }),
+  });
+}

package/lib/pod/outbox.mjs

@@ -0,0 +1,18 @@
+// outbox.mjs — ap/outbox: everything this actor has published, paged.
+//
+// Public by definition, and read by strangers rather than by us: a remote
+// server walks it to backfill an account it has just met. It is also what a
+// rebuild reads to recover posts a lost machine no longer has, which is why
+// readPublished tolerates the flat shape this project used to write.
+
+import * as collection from './collection.mjs';
+
+// ---- the owner's agent ----
+
+export const writePage = (pod, pageUrl, doc, opts) => collection.writePage(pod, pageUrl, doc, opts);
+export const writeHead = (pod, urls, doc, opts) => collection.writeHead(pod, urls.outbox, doc, opts);
+export const dropPage = (pod, pageUrl) => collection.dropPage(pod, pageUrl);
+
+/** Every activity the pod currently publishes, or null if it publishes none. */
+export const readPublished = (pod, urls) =>
+  collection.readPaged(pod, urls.outbox, { max: 10_000 });

package/lib/pod/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "solid-ap-pod",
+  "version": "0.1.0",
+  "description": "Read and write an ActivityPub actor's documents on a Solid pod: the container layout, an injected-session transport, WAC access control, and one module per pod resource.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    "./urls.mjs": "./urls.mjs",
+    "./transport.mjs": "./transport.mjs",
+    "./http.mjs": "./http.mjs",
+    "./links.mjs": "./links.mjs"
+  },
+  "dependencies": {
+    "rdflib": "^2.4.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/lib/pod/policy.mjs

@@ -0,0 +1,58 @@
+// policy.mjs — ap/gateway-policy.json: what the pod's owner has published
+// about which mail they want.
+//
+// The point of the document is that a service filtering on someone's behalf
+// reads their stated wishes from their own pod rather than holding a private
+// copy of them. So the reader here is deliberately unauthenticated: the
+// document is public, and a service that needed a credential to read it would
+// be holding something about the person it should not have to.
+
+import { readCapped } from './http.mjs';
+
+const POLICY_TTL_MS = 5 * 60_000;
+const POLICY_MAX_BYTES = 256 * 1024;
+
+/**
+ * The published policy, or null when there is none to read.
+ *
+ * The cache is passed IN rather than kept here. A library that holds
+ * process-global state decides its own lifetime, and the lifetime that matters
+ * belongs to the service: on a warm serverless container one Map is shared
+ * across every user it serves, so what it is keyed by is a correctness
+ * property, not an optimisation. Keyed by `podHome`, it is one person's policy
+ * under one person's key.
+ *
+ * Cached at all because a delivery flood must not become one read per delivery
+ * against the person's pod — which is the load the whole arrangement exists to
+ * spare them.
+ *
+ * ---- asked by: a delivery gateway, deciding what concerns this person ----
+ */
+export async function read(fetchImpl, podHome, { cache = null, ttlMs = POLICY_TTL_MS } = {}) {
+  const hit = cache?.get(podHome);
+  if (hit && Date.now() - hit.at < ttlMs) return hit.policy;
+  let policy = null;
+  try {
+    const res = await fetchImpl(podHome + 'ap/gateway-policy.json',
+      { headers: { accept: 'application/json' } });
+    if (res && res.status < 400) policy = JSON.parse(await readCapped(res, POLICY_MAX_BYTES));
+  } catch { /* unpublished or unreachable: the caller's own fields stand */ }
+  cache?.set(podHome, { at: Date.now(), policy });
+  return policy;
+}
+
+// ---- the owner's agent ----
+
+/**
+ * Publish the policy.
+ *
+ * Public-Read on purpose, and the only document in this library written
+ * public specifically so that a service holding no credential can act on the
+ * owner's behalf. What goes IN it — which follows count, which blocks — is the
+ * caller's to decide; that it is readable is the point of it existing.
+ */
+export async function write(pod, urls, doc) {
+  const url = urls.home + 'ap/gateway-policy.json';
+  await pod.putJson(url, doc, 'application/json');
+  await pod.setAcl(url, ['Read']);
+}

package/lib/pod/private.mjs

@@ -0,0 +1,19 @@
+// private.mjs — ap/private/: the collections that are nobody else's business.
+//
+// pending-followers and pending-following are FEP-4ccd's follows in limbo;
+// blocked is FEP-c648's block list. All three live in the private container so
+// the owner-only rule is INHERITED rather than re-stated per document — which
+// is why none of these writes sets an ACL of its own, and why writing one into
+// the wrong container would silently publish it.
+
+import * as collection from './collection.mjs';
+
+// ---- the owner's agent ----
+
+export async function writePending(pod, urls, { followers, following }) {
+  await collection.writeFlat(pod, urls.pendingFollowers, followers);
+  await collection.writeFlat(pod, urls.pendingFollowing, following);
+}
+
+export const writeBlocked = (pod, urls, doc) =>
+  collection.writeFlat(pod, urls.blocked, doc);

package/lib/pod/root.mjs

@@ -0,0 +1,63 @@
+// root.mjs — the pod itself, before any of its containers.
+//
+// Three questions get asked of a pod root rather than of a document in it: who
+// owns it, whether it is there at all, and — for a service publishing someone
+// else's pod on their behalf — what one of its public documents says.
+//
+// Every operation here takes a plain fetcher, not a transport. That is the
+// honest shape: these are asked by parties that hold no credential for the pod
+// — a keyless delivery gateway, a sign-up page looking at a pod the person
+// brought with them — and giving them an authenticated transport would let
+// them ask questions they have no business asking.
+
+import { readCapped } from './http.mjs';
+import { linkTargets, REL } from './links.mjs';
+
+const OWNER_LOOKUP_MS = 5_000;
+const PUBLIC_DOC_MAX_BYTES = 1024 * 1024;
+
+/**
+ * Who the pod server says owns this pod.
+ *
+ * The server hosting it is the authority on that, so when it answers, its
+ * answer decides. A server that says nothing leaves where the WebID lives as
+ * the only evidence there is — which is weaker, and the caller's problem.
+ *
+ * ---- asked by: a service deciding whether someone may speak for a pod ----
+ */
+export async function readOwnerLinks(fetchImpl, podBase, { timeoutMs = OWNER_LOOKUP_MS } = {}) {
+  try {
+    const res = await fetchImpl(podBase, {
+      method: 'HEAD', signal: AbortSignal.timeout(timeoutMs),
+    });
+    return linkTargets(res?.headers?.get?.('link'), REL.owner, podBase);
+  } catch { return []; }
+}
+
+/**
+ * Does anything answer at this pod?
+ *
+ * ---- asked by: a provisioning client, about a pod the person brought ----
+ */
+export async function probeAnswers(podUrl, fetchImpl = fetch) {
+  try {
+    const res = await fetchImpl(podUrl, { method: 'HEAD' });
+    return { ok: res.status < 400, status: res.status };
+  } catch (e) { return { ok: false, status: 0, error: e.message }; }
+}
+
+/**
+ * One public document, read on behalf of someone who is not its owner.
+ *
+ * `getter` is how the read happens, which is not always a network fetch: a
+ * component running inside the pod server reads its own store directly and has
+ * no access control of its own, so the pod this read belongs to travels with
+ * the request and the getter is told what it may reach.
+ *
+ * ---- asked by: a front publishing a pod's public face under its own name ----
+ */
+export async function readPublicDocument(getter, podTarget, { podHome, maxBytes = PUBLIC_DOC_MAX_BYTES } = {}) {
+  const res = await getter(podTarget, { podHome });
+  if (!res || res.status >= 400) return { status: res?.status || 502, text: null };
+  return { status: 200, text: await readCapped(res, maxBytes) };
+}

package/lib/pod/state.mjs

@@ -0,0 +1,39 @@
+// state.mjs — ap-state/: what the agent knows, kept where the agent is not.
+//
+// A browser has no disk you can carry to the next machine, so the durable copy
+// of an identity's state lives on its pod. Most of that tree is handled by a
+// caching store; what is here is the two documents read and written OUTSIDE
+// it, before there is a store to read them with.
+//
+// The container is owner-only, and every operation here assumes that has
+// already been established — see provisionKey, which is the one place that
+// establishes it, and does so in an order that is not negotiable.
+
+// ---- the owner's agent ----
+
+export const readWrappedKeys = (pod, urls) => pod.getJson(urls.state + 'keys.json');
+export const readConfig = (pod, urls) => pod.getJson(urls.state + 'config.json');
+
+export const writeWrappedKeys = (pod, urls, envelope) =>
+  pod.putJson(urls.state + 'keys.json', envelope, 'application/json');
+export const writeConfig = (pod, urls, config) =>
+  pod.putJson(urls.state + 'config.json', config, 'application/json');
+
+// ---- a provisioning client, setting an identity up for the first time ----
+
+/**
+ * Lock the state container, THEN write the signing key into it.
+ *
+ * The order is the operation. Writing the key first leaves a window in which a
+ * pod whose root is world-readable serves it to anyone who asks — and a pod
+ * the person brought with them is exactly the case where that root may be
+ * public. As two statements this was two chances to get it wrong; as one
+ * operation there is nowhere to put them in the other order.
+ *
+ * The envelope is built by the caller. This library does not choose how a key
+ * is wrapped, and should not be able to write an unwrapped one by accident.
+ */
+export async function provisionKey(pod, { stateUrl, keysUrl, envelope }) {
+  await pod.setAcl(stateUrl, []);
+  await pod.putJson(keysUrl, envelope, 'application/json');
+}