fedipod-server 0.28.1 → 0.30.0

package/lib/gateway/gateway-core.mjs

@@ -1,165 +0,0 @@
-// gateway-core.mjs — the runtime-agnostic logic of an inbox gateway: verify a
-// delivery at the door (where the HTTP-Signature headers still exist), drop
-// spam and forgeries at the edge, and forward what remains — with a signed
-// verification receipt — into the pod inbox for the ordinary drain.
-//
-// This holds NO signing key. It verifies with remotes' PUBLIC keys, writes to
-// the pod inbox with an Append-only credential the adapter supplies, and stamps
-// the receipt with a shared HMAC secret. A compromise here can inject inbox
-// items (which still meet verify-by-dereference in the drain) but cannot
-// impersonate the actor, read the private tree, or post as it.
-//
-// `netlify/functions/inbox.mjs` is a thin adapter over this; an agent-side
-// endpoint could be another. The core is what the smoke suite exercises.
-
-import crypto from 'node:crypto';
-import { verifyHttpSignature, makeSafeLoader, makeReceipt, signReceipt } from './httpsig.mjs';
-import * as inbox from '../pod/inbox.mjs';
-import { senderKeys } from './caches.mjs';
-
-const DEFAULT_MAX_BYTES = 512 * 1024;   // mirror intake.mjs MAX_ITEM_BYTES
-
-// Control activities are the message itself and must always pass — you want
-// Follows from strangers. Only CONTENT is subject to the concerns-us drop,
-// and to a pause: an account nobody is reading still takes its follows.
-export const CONTROL = new Set(['Follow', 'Undo', 'Accept', 'Reject', 'Delete', 'Move',
-  'Add', 'Remove', 'Block']);
-export const isControl = (type) => CONTROL.has(type);
-
-const idOf = (v) => (typeof v === 'string' ? v : v?.id) || null;
-const sha256hex = (s) => crypto.createHash('sha256').update(s).digest('hex');
-
-function httpUrl(u) {
-  try { const p = new URL(u).protocol; return p === 'http:' || p === 'https:'; } catch { return false; }
-}
-
-// Mirror of intake.isBlocked over the policy doc's public blocklist mirror.
-function isBlocked(actor, blocklist = {}) {
-  if (!actor) return true;
-  if ((blocklist.actors || []).includes(actor)) return true;
-  // hostname, not host: the agent's own isBlocked strips the port, and a door
-  // that keeps it lets a blocked domain back in on a non-default port.
-  let host; try { host = new URL(actor).hostname; } catch { return false; }
-  return (blocklist.domains || []).some(d => host === d || host.endsWith('.' + d));
-}
-
-// The edge form of intake.concernsUs — pure addressing, no I/O. Conservative:
-// only DROPS content it is confident does not concern the identity. A GROUP
-// owns conversations under anything it has carried, which the keyless edge
-// cannot see, so a group defers the whole check to the drain (returns true).
-function concernsUsAtEdge(activity, ident) {
-  if (ident.kind === 'group') return true;
-  const actor = idOf(activity.actor);
-  if ((ident.following || []).includes(actor)) return true;
-  const obj = typeof activity.object === 'object' ? activity.object : null;
-  const audience = []
-    .concat(activity.to || [], activity.cc || [], activity.bto || [], activity.bcc || [], activity.audience || [],
-      obj?.to || [], obj?.cc || [], obj?.audience || [])
-    .map(idOf).filter(Boolean);
-  if (audience.includes(ident.actorUrl) || audience.includes(ident.followersUrl)) return true;
-  const tag = [].concat(obj?.tag || activity.tag || []);
-  if (tag.some(t => t?.type === 'Mention' && (t.href === ident.actorUrl || t.name?.includes(ident.actorUrl)))) return true;
-  const inReplyTo = idOf(obj?.inReplyTo ?? activity.inReplyTo);
-  return !!inReplyTo && ident.notesPrefix && String(inReplyTo).startsWith(ident.notesPrefix);
-}
-
-// Handle one inbound delivery. `request` is a WHATWG Request. `ident` is the
-// resolved identity policy: { inboxUrl, actorUrl, followersUrl, notesPrefix,
-// following, blocklist, kind, gatewayWebId, hmacSecret }. `podPut(url, body,
-// contentType) → boolean` appends to the pod with the gateway's credential.
-// `paused` says nobody is reading this inbox: content is accepted and
-// discarded (the same quiet 202 a blocked sender gets, so nothing retries
-// and nothing counts a failure against this host), control still lands.
-// Returns { status, reason } — the adapter turns it into an HTTP response —
-// and, for a delivery that reached the pod, `content` (whether it was
-// content rather than control) and `bytes`, so the caller can keep count.
-export async function handleDelivery(request, ident, { podPut, fetchImpl = fetch, maxBytes = DEFAULT_MAX_BYTES, paused = false } = {}) {
-  // Read the body once from a clone; the original, unconsumed, goes to the
-  // verifier (which needs the body for the Digest check).
-  let raw;
-  try { raw = await request.clone().text(); } catch { return { status: 400, reason: 'unreadable body' }; }
-  if (Buffer.byteLength(raw) > maxBytes) return { status: 413, reason: 'too large' };
-
-  let activity;
-  try { activity = JSON.parse(raw); } catch { return { status: 400, reason: 'unparsable JSON' }; }
-  const actor = idOf(activity.actor);
-  if (!httpUrl(actor)) return { status: 400, reason: 'actor is not an http(s) URL' };
-
-  // Edge drops — silent 202 so a rejected sender does not retry a delivery we
-  // will never accept. None of these becomes a pod write.
-  if (isBlocked(actor, ident.blocklist)) return { status: 202, reason: 'blocked' };
-  const content = !CONTROL.has(activity.type);
-  if (content && paused) return { status: 202, reason: 'paused' };
-  if (content && !concernsUsAtEdge(activity, ident)) {
-    return { status: 202, reason: 'does not concern us' };
-  }
-
-  // The sender's key, kept between deliveries: a server pushing a hundred
-  // items is asked for its key once (caches.mjs).
-  const v = await verifyHttpSignature(request, {
-    documentLoader: makeSafeLoader({ fetchImpl }), keyCache: senderKeys,
-  });
-  // A present-but-invalid signature is a forgery — dropped here, so it never
-  // reaches the pod (today it would, drain, and die unapplied). An absent or
-  // unfetchable-key signature is NOT dropped: it forwards unverified and the
-  // drain's verify-by-dereference still stands behind it.
-  if (v.verified === false && v.reason === 'bad-signature') {
-    return { status: 202, reason: 'forged signature' };
-  }
-
-  // No per-user secret on record = no receipt: the delivery still filters and
-  // forwards, it just reads as unverified at the drain — never a failure.
-  const receipt = ident.hmacSecret
-    ? signReceipt(makeReceipt(v, { gateway: ident.gatewayWebId }), ident.hmacSecret)
-    : null;
-  const hash = sha256hex(raw);
-  const okA = await inbox.appendVerifiedDelivery(podPut, ident.inboxUrl, hash, raw);
-  // A pod-write failure returns 5xx so the ORIGIN retries over its own ladder —
-  // that is what preserves the pod's buffer property without the gateway
-  // holding any state.
-  if (!okA) return { status: 502, reason: 'pod inbox write failed' };
-  if (receipt) await inbox.writeReceiptBeside(podPut, ident.inboxUrl, hash, receipt);
-  return { status: 202, reason: v.verified ? 'verified' : 'buffered-unverified', content, bytes: Buffer.byteLength(raw) };
-}
-
-// The outbox door: the owner's own post, taken on their behalf.
-//
-// A client such as dokieli POSTs an activity — or a bare object — to the
-// outbox address the actor advertises. The door holds no key and mints nothing:
-// it checks that the token proves the account's owner (the caller has already
-// done that and hands in `owner`), writes the bytes into the pod inbox exactly
-// as verified mail is written, and stamps them with a receipt whose method is
-// `c2s` and whose actor is this account. The drain hands such an item to the
-// client-to-server dispatcher, which publishes and delivers it — so the post
-// goes out when the agent next runs, the same way inbound mail is read.
-//
-// `slug` is the name the client asked for its new document. It rides in the
-// receipt so the dispatcher can use it, and it is what lets the door answer a
-// Location before anything exists: the object will live at notesPrefix+slug
-// unless that name is taken, in which case the agent mints another.
-export const SLUG_OK = /^[A-Za-z0-9._-]{1,64}$/u;
-export const safeSlug = (s) => (typeof s === 'string' && SLUG_OK.test(s) && !/^\.+$/u.test(s) ? s : null);
-
-export async function handleOwnerPost(request, ident, { podPut, ownerWebId, maxBytes = DEFAULT_MAX_BYTES } = {}) {
-  if (!ident.hmacSecret) return { status: 409, reason: 'this account has no door secret — attach it again' };
-  let raw;
-  try { raw = await request.text(); } catch { return { status: 400, reason: 'unreadable body' }; }
-  if (Buffer.byteLength(raw) > maxBytes) return { status: 413, reason: 'too large' };
-  let doc;
-  try { doc = JSON.parse(raw); } catch { return { status: 400, reason: 'unparsable JSON' }; }
-  if (!doc || typeof doc !== 'object' || Array.isArray(doc) || !doc.type) {
-    return { status: 400, reason: 'a typed ActivityStreams object is required' };
-  }
-  const slug = safeSlug(request.headers.get('slug'));
-  const receipt = signReceipt({
-    v: 1, verified: true, method: 'c2s', keyId: ownerWebId || null, actor: ident.actorUrl,
-    checks: ['owner-token'], reason: 'owner', gateway: ident.gatewayWebId, ...(slug ? { slug } : {}),
-  }, ident.hmacSecret);
-  const hash = sha256hex(raw);
-  const okA = await inbox.appendVerifiedDelivery(podPut, ident.inboxUrl, hash, raw);
-  if (!okA) return { status: 502, reason: 'pod inbox write failed' };
-  await inbox.writeReceiptBeside(podPut, ident.inboxUrl, hash, receipt);
-  return { status: 201, reason: 'accepted', location: slug && ident.notesPrefix ? ident.notesPrefix + slug : null };
-}
-
-export const _internal = { isBlocked, concernsUsAtEdge, httpUrl, sha256hex };

package/lib/gateway/headers.mjs

@@ -1,49 +0,0 @@
-// headers.mjs — the hardening every front response carries, in one place.
-// Split out of front-core.mjs, which is at its size gate; nothing here knows
-// about routes.
-
-// Every response this file makes, hardened in one place rather than in each of
-// the dozen shapes below.
-//
-// `nosniff` matters most: the front serves user-supplied JSON straight from
-// somebody's pod (the proxied actor and object documents), and without it a
-// browser is free to decide for itself that a document is HTML and run what is
-// inside it. The rest is the same posture the app already has — nothing may be
-// framed, no base tag may be rewritten, no plugin content.
-//
-// A content-security-policy goes on the HTML only: it would mean nothing on a
-// JSON document, and `frame-ancestors` has to be a header rather than a meta
-// tag anyway.
-//
-// `script-src 'self'` is the one that matters, and it is only possible because
-// none of these pages carries inline script any more — each has its own file and
-// its own route above. A policy cannot tell an inline block the author wrote
-// from one an attacker injected, so as long as any inline script has to run,
-// every inline script may.
-//
-// `connect-src` allows https: because the pages sign in against the user's own
-// pod, which is a different origin by definition and not one we can name here.
-export function withSecurityHeaders(headers = {}, body = null) {
-  const ct = String(headers['content-type'] || '');
-  const isHtml = ct.startsWith('text/html');
-  return {
-    ...headers,
-    'x-content-type-options': 'nosniff',
-    'referrer-policy': 'same-origin',
-    'x-frame-options': 'SAMEORIGIN',
-    ...(isHtml && body ? {
-      'content-security-policy': [
-        "default-src 'self'",
-        "script-src 'self'",             // no inline script: see above
-        "style-src 'self' 'unsafe-inline'",
-        "img-src 'self' https: data:",
-        "connect-src 'self' https:",     // sign-in goes to the user's own pod
-        "object-src 'none'",             // no plugin content, ever
-        "base-uri 'none'",               // no rewriting where relative URLs resolve
-        "frame-ancestors 'self'",        // nobody else may frame these pages
-        "form-action 'self'",            // a form here submits here
-      ].join('; '),
-    } : {}),
-  };
-}
-

package/lib/gateway/httpsig.mjs

@@ -1,159 +0,0 @@
-// httpsig.mjs — inbound HTTP-Signature verification, and the verification
-// receipt that carries the outcome from wherever the verify happened (an
-// always-on gateway, or the agent's own endpoint when it is publicly reachable)
-// into the drain, which cannot see the delivery's headers.
-//
-// We SIGN outbound with Fedify draft-cavage (lib/deliver.mjs); we VERIFY with
-// the same library, so the signing-string reconstruction can never drift out
-// of step with what we produce. The one thing Fedify must be prevented from
-// doing on its own is fetching an attacker-named key over an unguarded socket
-// — so the key deref is injected as a loader that goes through safefetch.
-
-import crypto from 'node:crypto';
-import { verifyRequestDetailed } from '@fedify/fedify/sig';
-import { assertPublicUrl, safeFetch, readCapped } from '../shared/safefetch.mjs';
-
-// An SSRF-safe JSON-LD document loader for Fedify's key fetch. The keyId in a
-// delivery is chosen by the sender, so every deref it triggers is untrusted
-// input and must pass the same address policy as the rest of our outbound
-// path. `skipActor` forces a network read past any cache, for the one refetch
-// a rotated key needs.
-export function makeSafeLoader({ getActors = null, fetchImpl = fetch } = {}) {
-  return async (url) => {
-    // A cached actor document short-circuits the network entirely — and it was
-    // only cached after its own origin vouched for its id (intake.fetchAP).
-    if (getActors) {
-      const hit = getActors()[url];
-      if (hit) return { document: hit, documentUrl: url, contextUrl: null };
-    }
-    await assertPublicUrl(url);
-    const res = await safeFetch(url, {
-      headers: { accept: 'application/activity+json, application/ld+json' },
-    }, fetchImpl);
-    if (res.status >= 400) throw new Error(`key fetch ${url} → ${res.status}`);
-    const document = JSON.parse(await readCapped(res));
-    return { document, documentUrl: url, contextUrl: null };
-  };
-}
-
-// Verify a delivery's signature. `request` is a WHATWG Request (the gateway
-// has one natively; an agent-side endpoint builds one from its req). Returns a
-// normalized result both the gateway and the drain understand — never throws
-// on a bad signature, because "unverified" is a routine outcome, not an error.
-//
-// Three outcomes, kept apart because the door acts on them differently. Only a
-// signature we could CHECK and found wrong is a forgery. A key we could not
-// fetch proves nothing: a sender in secure mode — Threads, Mastodon with
-// AUTHORIZED_FETCH — answers this keyless loader 404 or 401, so its deliveries
-// have to degrade to unverified rather than be read as forged.
-export async function verifyHttpSignature(request, { documentLoader, keyCache, timeWindow } = {}) {
-  const hadSig = request.headers.get('signature') != null;
-  let result = null;
-  try {
-    result = await verifyRequestDetailed(request, {
-      documentLoader,
-      ...(keyCache ? { keyCache } : {}),
-      timeWindow: timeWindow ?? { hours: 1 },
-    });
-  } catch {
-    result = null;   // the library itself failed — no more informative than a bad signature
-  }
-  // Which signature the sender used: RFC 9421 carries a Signature-Input
-  // header beside Signature; the cavage draft carries Signature alone. The
-  // library picks the verifier by the same header.
-  const method = request.headers.has('signature-input') ? 'rfc9421' : 'draft-cavage';
-  if (result?.verified) {
-    const key = result.key;
-    return {
-      verified: true, method,
-      keyId: key.id?.href ?? null, actor: key.ownerId?.href ?? null, reason: null,
-      checks: { signature: true, digest: true, dateSkew: true, keyFetched: true },
-    };
-  }
-  const kind = result?.reason?.type;
-  if (!hadSig || kind === 'noSignature') {
-    return {
-      verified: false, method: 'none', keyId: null, actor: null,
-      reason: 'no-signature', checks: { signature: false },
-    };
-  }
-  if (kind === 'keyFetchError') {
-    return {
-      verified: false, method, keyId: null, actor: null,
-      reason: 'key-unfetchable', checks: { signature: false, keyFetched: false },
-    };
-  }
-  return {
-    verified: false, method, keyId: null, actor: null,
-    reason: 'bad-signature', checks: { signature: false },
-  };
-}
-
-// The receipt: what the door concluded, HMAC-stamped so the drain can trust it
-// even while the inbox is still public-Append (a forger without the secret
-// cannot mint `verified: true`). The HMAC is over the receipt minus the hmac
-// field itself, with sorted keys so gateway and drain canonicalize alike.
-//
-// JSON.stringify's replacer ARRAY applies at EVERY level, not just the top: the
-// old canonical() passed the top-level key names, so `checks` — whose own keys
-// are `signature`, `digest`, `dateSkew`, `keyFetched` — serialized as `{}` and
-// was covered by no signature at all. Anything nested was equally unstamped.
-// Sort recursively instead, and exclude `hmac` only where it actually lives.
-function sortedKeys(v) {
-  if (Array.isArray(v)) return v.map(sortedKeys);
-  if (v && typeof v === 'object') {
-    const out = {};
-    for (const k of Object.keys(v).sort()) out[k] = sortedKeys(v[k]);
-    return out;
-  }
-  return v;
-}
-function canonical(obj) {
-  const { hmac, ...rest } = obj;       // eslint-disable-line no-unused-vars
-  return JSON.stringify(sortedKeys(rest));
-}
-
-// What canonical() used to produce. Kept ONLY for verification, and only until
-// every door has been redeployed: a gateway (fedipod.net) and an agent update
-// independently, so for a while a receipt signed by an old door has to keep
-// verifying against a new drain. Receipts are short-lived — one per inbox item,
-// deleted with the item — so this can go once the doors have turned over.
-// Nothing signs with it.
-function canonicalLegacy(obj) {
-  return JSON.stringify(obj, Object.keys(obj).filter(k => k !== 'hmac').sort());
-}
-
-export function makeReceipt(result, { gateway = null } = {}) {
-  return {
-    v: 1,
-    verified: !!result.verified,
-    method: result.method,
-    keyId: result.keyId,
-    actor: result.actor,
-    checks: result.checks,
-    reason: result.reason,
-    gateway,
-  };
-}
-
-export function signReceipt(receipt, secret) {
-  const hmac = crypto.createHmac('sha256', secret).update(canonical(receipt)).digest('base64');
-  return { ...receipt, hmac };
-}
-
-// True only when the receipt carries a valid HMAC for `secret`. A missing
-// secret, a missing hmac, or a mismatch all read as "not ours" → the drain
-// treats the receipt as absent (today's unverified behavior). timingSafeEqual
-// over equal-length buffers; unequal lengths are a straight mismatch.
-export function verifyReceipt(receipt, secret) {
-  if (!receipt || typeof receipt !== 'object' || !receipt.hmac || !secret) return false;
-  let given;
-  try { given = Buffer.from(receipt.hmac, 'base64'); } catch { return false; }
-  const matches = (text) => {
-    const expected = crypto.createHmac('sha256', secret).update(text).digest();
-    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
-  };
-  // The current stamp first; the pre-2026-09-09 one second, for receipts a door
-  // that has not been redeployed yet is still writing. See canonicalLegacy.
-  return matches(canonical(receipt)) || matches(canonicalLegacy(receipt));
-}

package/lib/gateway/notices.mjs

@@ -1,84 +0,0 @@
-// notices.mjs — notices from whoever runs the front, to every account here.
-//
-// The operator writes them on the /notices page, proved as the admin the way
-// the roster is; every page of ours asks GET /api/notices once per load and
-// shows a bell when there are any. A notice is a title, a plain-text body and
-// a time. The body is never markup: the pages render it as text.
-//
-// Kept beside the directory, in a store the adapter supplies:
-//   listNotices() -> { id: notice }     putNotice(id, notice)     deleteNotice(id)
-// A front that supplies none has no notices to offer, and says so.
-
-import crypto from 'node:crypto';
-
-const TITLE_MAX = 120;
-const BODY_MAX = 4000;
-const NOTICES_EDGE_SECONDS = 60;
-
-const clean = (v, max) => String(v ?? '').replace(/\r\n?/gu, '\n').trim().slice(0, max);
-const newest = (a, b) => String(b.at || '').localeCompare(String(a.at || ''));
-
-export async function listNotices(ctx) {
-  const all = ctx.listNotices ? await ctx.listNotices() : {};
-  return Object.values(all || {}).filter(Boolean).sort(newest);
-}
-
-// GET is public: what every account is shown. POST is the admin's alone. The
-// /notices page is where the admin writes them; it signs in like the roster.
-// Returns a response, or null when the path is neither.
-export async function routeNoticesApi(request, pathname, ctx, { j, verifyPodToken, publicFor, notFound }) {
-  // The two admin pages: the roster (who has accounts here) and the notices.
-  // Each signs in and calls its API; a deploy with no admin supplies no page.
-  const page = pathname === '/notices' ? ctx.noticesPage : pathname === '/roster' ? ctx.adminPage : undefined;
-  if (page !== undefined) {
-    if (request.method !== 'GET' && request.method !== 'HEAD') return { status: 405, headers: {}, body: '' };
-    if (!page) return notFound();
-    return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: page };
-  }
-  if (pathname !== '/api/notices') return null;
-  const open = { 'access-control-allow-origin': '*' };
-  if (request.method === 'OPTIONS') {
-    return { status: 204, headers: { ...open, 'access-control-allow-methods': 'GET, OPTIONS',
-      'access-control-allow-headers': 'Accept', allow: 'GET, POST, OPTIONS' }, body: null };
-  }
-  if (request.method === 'GET') {
-    if (!ctx.listNotices) return j(501, { error: 'this front keeps no notices' });
-    const out = j(200, { notices: await listNotices(ctx) });
-    Object.assign(out.headers, open, publicFor(NOTICES_EDGE_SECONDS));
-    return out;
-  }
-  if (request.method !== 'POST') return { status: 405, headers: {}, body: '' };
-  if (!ctx.putNotice || !ctx.deleteNotice || !ctx.adminWebId) return j(501, { error: 'this front keeps no notices' });
-  const webid = await verifyPodToken(request, pathname, ctx.verifier);
-  if (!webid) return j(401, { error: 'a Solid-OIDC token is required' });
-  if (webid !== ctx.adminWebId) return j(403, { error: 'that WebID is not the admin of this front' });
-  let body;
-  try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
-  const action = String(body.action || '');
-  const all = (ctx.listNotices ? await ctx.listNotices() : {}) || {};
-  if (action === 'delete') {
-    const id = String(body.id || '');
-    if (!all[id]) return j(404, { error: 'no such notice' });
-    await ctx.deleteNotice(id);
-    console.log(`front: notice ${id} deleted by the admin`);
-    return j(200, { ok: true, id, deleted: true });
-  }
-  if (action !== 'create' && action !== 'update') return j(400, { error: 'action must be create, update or delete' });
-  const title = clean(body.title, TITLE_MAX);
-  const text = clean(body.body, BODY_MAX);
-  if (!title) return j(400, { error: 'a title is required' });
-  if (!text) return j(400, { error: 'a body is required' });
-  const now = new Date().toISOString();
-  let notice;
-  if (action === 'create') {
-    const id = `${Date.now().toString(36)}-${crypto.randomBytes(4).toString('hex')}`;
-    notice = { id, title, body: text, at: now, updatedAt: now };
-  } else {
-    const prior = all[String(body.id || '')];
-    if (!prior) return j(404, { error: 'no such notice' });
-    notice = { ...prior, title, body: text, updatedAt: now };
-  }
-  await ctx.putNotice(notice.id, notice);
-  console.log(`front: notice ${notice.id} ${action}d by the admin`);
-  return j(action === 'create' ? 201 : 200, { ok: true, notice });
-}

package/lib/gateway/quiet.mjs

@@ -1,189 +0,0 @@
-// quiet.mjs — accounts that go quiet: what the front knows about an account
-// nobody opens, and what its owner may say about it. The router in
-// front-core.mjs asks closedState/accountState at the door and on every
-// public read, stamps noteOpened from the relay, counts noteReceived after
-// a forwarded delivery, and hands /api/open, /api/pause and /api/close here.
-
-// ---- accounts that go quiet -------------------------------------------------
-//
-// The gateway holds no mail: every delivery it takes is two writes into the
-// owner's pod inbox, read only when their browser is open. An account nobody
-// opens grows on its pod without limit, and its owner comes back to a drain
-// of everything at once. So the front keeps two facts about each browser
-// account — when its owner was last here, and how much content has arrived
-// since — and acts on them.
-//
-// `openedAt` is written when the owner signs in (POST /api/open, always) and
-// while they act through the relay (at most hourly). The count of content
-// deliveries since then lives in its own record, keyed by handle AND
-// openedAt: a fresh stamp starts a fresh count with nothing to reset, and a
-// delivery's write can never overwrite a sign-in's. Two deliveries landing
-// together may each read the same total and one increment is lost — the cap
-// comes out slightly soft, never too strict.
-//
-// PAUSED: the count has reached the cap, or the owner said so. Content is
-// accepted and discarded, control (follows, unfollows, moves, deletions,
-// blocks) still lands. The owner's next sign-in ends a cap pause by itself; a
-// pause they set lasts until they lift it.
-//
-// CLOSED: the owner said so, or nothing has opened the account for the close
-// window. Found closed by time, it is written down so it stays closed. From
-// then on the door, the actor and the handle answer 410 — never a failure
-// code, which senders retry and count against this whole host, and never a
-// success, which would keep them sending. Nothing on the pod is touched. An
-// address that moved (see /api/move) keeps answering as moved; closing does
-// not take that away.
-//
-// Only an account whose owner has signed in from a browser carries
-// `openedAt`. A DeviceAgent behind this door never does: it drains its own
-// inbox as it runs, so it is never counted, never paused and never closed by
-// time. Accounts from before this was built are counted from their next
-// sign-in.
-export const DEFAULT_PAUSE_ITEMS = 5000;
-export const DEFAULT_CLOSE_DAYS = 183;                // six months
-const OPEN_STAMP_EVERY_MS = 60 * 60_000;              // the relay's stamp, at most hourly
-const pauseItemsOf = (ctx) => (Number(ctx.pauseItems) > 0 ? Number(ctx.pauseItems) : DEFAULT_PAUSE_ITEMS);
-const closeDaysOf = (ctx) => (Number(ctx.closeDays) > 0 ? Number(ctx.closeDays) : DEFAULT_CLOSE_DAYS);
-const receivedKey = (key, rec) => `${key}/${rec.openedAt}`;
-
-export async function receivedSince(ctx, key, rec) {
-  if (!ctx.readReceived || !rec.openedAt) return { items: 0, bytes: 0 };
-  const got = await ctx.readReceived(receivedKey(key, rec)).catch(() => null);
-  return { items: Number(got?.items) || 0, bytes: Number(got?.bytes) || 0 };
-}
-
-// One more content delivery reached the pod. Nothing to count against until
-// the owner has been here once.
-export async function noteReceived(ctx, key, rec, bytes) {
-  if (!ctx.readReceived || !ctx.writeReceived || !rec.openedAt) return;
-  const so = await receivedSince(ctx, key, rec);
-  await ctx.writeReceived(receivedKey(key, rec), { items: so.items + 1, bytes: so.bytes + (Number(bytes) || 0) })
-    .catch((e) => console.log(`front @${key}: count not written: ${e?.message || e}`));
-}
-
-// The owner is here. `always` is a sign-in; the relay stamps at most hourly,
-// so a busy hour of posting is one write. The count that went with the old
-// stamp is dropped: it is over, and a store should not keep one per hour.
-export async function noteOpened(ctx, key, rec, { always = false } = {}) {
-  if (!ctx.putDirectory) return rec;
-  if (!always && rec.openedAt && Date.now() - Date.parse(rec.openedAt) < OPEN_STAMP_EVERY_MS) return rec;
-  const next = { ...rec, openedAt: new Date().toISOString() };
-  await ctx.putDirectory(key, next);
-  if (rec.openedAt && ctx.dropReceived) await ctx.dropReceived(receivedKey(key, rec)).catch(() => {});
-  return next;
-}
-
-// Closed, and why. Reads no count: this is asked on every public read.
-export async function closedState(ctx, key, rec) {
-  if (rec.movedTo) return { closed: false };
-  if (rec.closedAt) return { closed: true, closedAt: rec.closedAt, closedBy: rec.closedBy || 'owner' };
-  if (rec.openedAt && Date.now() - Date.parse(rec.openedAt) > closeDaysOf(ctx) * 86400_000) {
-    const closedAt = new Date().toISOString();
-    if (ctx.putDirectory) await ctx.putDirectory(key, { ...rec, closedAt, closedBy: 'quiet' });
-    console.log(`front @${key}: closed — nothing opened it since ${rec.openedAt}`);
-    return { closed: true, closedAt, closedBy: 'quiet' };
-  }
-  return { closed: false };
-}
-
-// The whole standing of an account, for the door and for its owner's page.
-export async function accountState(ctx, key, rec) {
-  const c = await closedState(ctx, key, rec);
-  const received = c.closed ? { items: 0, bytes: 0 } : await receivedSince(ctx, key, rec);
-  const cap = pauseItemsOf(ctx);
-  const pausedBy = c.closed ? null : rec.pausedAt ? 'owner' : received.items >= cap ? 'quiet' : null;
-  return {
-    closed: c.closed, closedAt: c.closedAt || null, closedBy: c.closedBy || null,
-    paused: !!pausedBy, pausedBy, pausedAt: rec.pausedAt || null,
-    openedAt: rec.openedAt || null, received, pauseItems: cap, closeDays: closeDaysOf(ctx),
-  };
-}
-
-// A 410 with a reason, the shape every closed or moved id answers with.
-export const closedAnswer = (headers = {}, why = 'this address is closed') => ({
-  status: 410, headers: { 'cache-control': 'no-store', ...headers, 'content-type': 'application/json' },
-  body: JSON.stringify({ error: why }) });
-
-// The owner of a row, proved the way the relay proves them: a pod token whose
-// WebID is the row's, or lives on the row's pod for a row from before WebIDs
-// were recorded.
-async function provedOwner(request, pathname, ctx, rec, { j, verifyPodToken, webidUnderPod }) {
-  const webid = await verifyPodToken(request, pathname, ctx.verifier);
-  if (!webid) return { error: j(401, { error: 'a Solid-OIDC token proving the pod is required' }) };
-  const owner = rec.webId ? webid === rec.webId : webidUnderPod(webid, rec.podHome);
-  if (!owner) return { error: j(403, { error: "the token proves a different pod than this account's" }) };
-  return { webid };
-}
-
-// The owner's three routes. `deps` are front-core's own JSON reply and
-// token check, handed in so this module stays free of the router's privates.
-// Returns a response, or null when the path is not one of these.
-export async function routeQuietApi(request, pathname, ctx, deps) {
-  const { j } = deps;
-  if (!['/api/open', '/api/pause', '/api/close'].includes(pathname)) return null;
-  // A page at another origin asks first whether it may call, and is answered
-  // as the relay answers it. Unanswered, the browser never sends the call and
-  // some pages asked again every minute.
-  if (request.method === 'OPTIONS') return deps.apiPreflight();
-  if (request.method !== 'POST') return null;
-  // The owner is here: their browser says so as it opens the account. The
-  // answer is the account's standing at this gateway, which the manage page
-  // shows. A closed address is told so and nothing is written.
-  if (pathname === '/api/open' && request.method === 'POST') {
-    if (!ctx.putDirectory) return j(501, { error: 'this front keeps no directory' });
-    let body;
-    try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
-    const handle = String(body.handle || '').toLowerCase();
-    let rec = await ctx.lookup(handle);
-    if (!rec) return j(404, { error: 'no such account' });
-    const who = await provedOwner(request, pathname, ctx, rec, deps);
-    if (who.error) return who.error;
-    const before = await closedState(ctx, handle, rec);
-    if (before.closed) return j(410, { error: 'this address is closed', closedAt: before.closedAt, closedBy: before.closedBy });
-    rec = await noteOpened(ctx, handle, rec, { always: true });
-    return j(200, { ok: true, handle, ...await accountState(ctx, handle, rec) });
-  }
-
-  // The owner pausing their own account, or lifting the pause they set.
-  if (pathname === '/api/pause' && request.method === 'POST') {
-    if (!ctx.putDirectory) return j(501, { error: 'this front keeps no directory' });
-    let body;
-    try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
-    const handle = String(body.handle || '').toLowerCase();
-    let rec = await ctx.lookup(handle);
-    if (!rec) return j(404, { error: 'no such account' });
-    const who = await provedOwner(request, pathname, ctx, rec, deps);
-    if (who.error) return who.error;
-    const before = await closedState(ctx, handle, rec);
-    if (before.closed) return j(410, { error: 'this address is closed', closedAt: before.closedAt });
-    if (typeof body.paused !== 'boolean') return j(400, { error: 'paused must be true or false' });
-    if (body.paused && !rec.pausedAt) rec = { ...rec, pausedAt: new Date().toISOString() };
-    if (!body.paused && rec.pausedAt) { rec = { ...rec }; delete rec.pausedAt; }
-    // Lifting a pause is a sign-in's worth of "I am here": the count starts over.
-    if (!body.paused) rec = { ...rec, openedAt: new Date().toISOString() };
-    await ctx.putDirectory(handle, rec);
-    console.log(`front @${handle}: ${body.paused ? 'paused' : 'resumed'} by its owner`);
-    return j(200, { ok: true, handle, ...await accountState(ctx, handle, rec) });
-  }
-
-  // The owner closing their address for good. Repeating it changes nothing.
-  if (pathname === '/api/close' && request.method === 'POST') {
-    if (!ctx.putDirectory) return j(501, { error: 'this front keeps no directory' });
-    let body;
-    try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
-    const handle = String(body.handle || '').toLowerCase();
-    let rec = await ctx.lookup(handle);
-    if (!rec) return j(404, { error: 'no such account' });
-    const who = await provedOwner(request, pathname, ctx, rec, deps);
-    if (who.error) return who.error;
-    if (body.confirm !== true) return j(400, { error: 'closing is for good — send confirm: true' });
-    if (!rec.closedAt) {
-      rec = { ...rec, closedAt: new Date().toISOString(), closedBy: 'owner' };
-      await ctx.putDirectory(handle, rec);
-      console.log(`front @${handle}: closed by its owner`);
-    }
-    return j(200, { ok: true, handle, ...await accountState(ctx, handle, rec) });
-  }
-
-  return null;
-}