fedipod 1.40.0 → 1.42.0

package/lib/device/home.mjs

@@ -13,7 +13,9 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { writeJsonAtomic } from '../shared/files.mjs';
+
+export { writeFileAtomic, writeJsonAtomic, tildify } from '../shared/files.mjs';
 
 export const CURRENT_ROOT = '.fedipod';
 export const LEGACY_ROOTS = ['.solid-activitypub', '.activitypod'];  // most recent first
@@ -31,39 +33,6 @@ export function apRoot(homedir = os.homedir()) {
 
 export const isLegacyRoot = (root) => LEGACY_ROOTS.includes(path.basename(root));
 
-// Write one of this home's files without a window in which it is half there.
-//
-// lib/storage.mjs goes to the trouble of tmp+rename for state documents that
-// its own header calls rebuildable from the pod. The files here are the ones
-// that are NOT: keys.json is the private key remote servers have cached, and
-// credential.json holds a secret a Solid server mints once and will not mint
-// again. A plain writeFileSync truncates first, so a crash, a power loss or a
-// full disk between truncate and write leaves an empty or half-written file
-// where the identity used to be.
-//
-// rename(2) is atomic on POSIX, so a reader — or a backup running at the wrong
-// moment — sees either the old file or the new one. fsync before it, so the
-// content is on the platter and not merely in the page cache when the rename
-// lands. Windows has no atomic rename over an existing file; there the copy
-// path is still better than a truncate, and this is a best effort by design.
-export function writeFileAtomic(file, body, { mode = 0o600 } = {}) {
-  const tmp = `${file}.${process.pid}.tmp`;
-  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-  const fd = fs.openSync(tmp, 'w', mode);
-  try {
-    fs.writeFileSync(fd, body);
-    fs.fsyncSync(fd);
-  } finally {
-    fs.closeSync(fd);
-  }
-  fs.renameSync(tmp, file);
-}
-
-// The same, for the JSON these files all happen to be.
-export function writeJsonAtomic(file, obj, opts) {
-  writeFileAtomic(file, JSON.stringify(obj, null, 2) + '\n', opts);
-}
-
 export const profilesDir = (root) => path.join(root, 'profiles');
 
 // The root an arbitrary home belongs to. `<root>/profiles/<name>` is a profile;
@@ -136,22 +105,6 @@ export const profileHome = (root, name) => path.join(profilesDir(root), name);
 export const rootHoldsIdentity = (root) => fs.existsSync(path.join(root, 'credential.json'));
 
 
-// For DISPLAY only: `~/.fedipod` reads at a glance where
-// `/home/jeff/.fedipod` has to be parsed, and the home directory is
-// the least interesting part of every path this prints. A `file:` URL is a path
-// wearing a scheme, so it is shown as the path — which is also what you would
-// type, since `state --to` takes either.
-//
-// Never used to build a path. `~` is the shell's, not the filesystem's, and
-// anything that resolves one must expand it first.
-export function tildify(p, homedir = os.homedir()) {
-  if (!p) return p;
-  let s = String(p);
-  if (s.startsWith('file://')) { try { s = fileURLToPath(s); } catch { return s; } }
-  if (s === homedir) return '~';
-  return s.startsWith(homedir + path.sep) ? '~' + s.slice(homedir.length) : s;
-}
-
 // Using an identity is what makes it the default. Called when an agent starts
 // for one — not on every read, or `--profile other status` would quietly move
 // the machine's idea of "you" while only asking a question.

package/lib/{client → device}/localapi.mjs

@@ -12,8 +12,8 @@
 import https from 'node:https';
 import fs from 'node:fs';
 import path from 'node:path';
-import { rootOf, apRoot } from '../device/home.mjs';
-import { certPaths } from '../device/certs.mjs';
+import { rootOf, apRoot } from './home.mjs';
+import { certPaths } from './certs.mjs';
 
 /**
  * The authorities worth offering for a loopback call: this install's, and the

package/lib/device/remote.mjs

@@ -1,54 +1,3 @@
-// remote.mjs — the Node agent's pod transport: CSS client-credentials + DPoP
-// (vendor/idp-grant.cjs, extracted from data-kitchen's "remember this IdP"
-// machinery — plain Node, no Electron).
-//
-// Everything about talking to a pod — the verbs, the ACL documents, the
-// deletion deny-list, the Retry-After cooldown, the container listing — lives
-// in lib/pod/transport.mjs, which knows nothing about Node and is shared with
-// the browser. What is left here is the one thing that genuinely differs: how
-// the session is obtained. That top-level `require` of the vendor grant is also
-// exactly why the split exists — it cannot be bundled for a service worker.
-
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { PodTransport } from '../pod/transport.mjs';
-
-const require = createRequire(import.meta.url);
-const vendorDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../vendor');
-const { mintCredential, discoverTokenEndpoint, createGrantSession, revokeCredentialViaAccount } =
-  require(path.join(vendorDir, 'idp-grant.cjs'));
-
-export { mintCredential, discoverTokenEndpoint, revokeCredentialViaAccount };
-
-// Re-exported so the callers that guard their own deletions — run-agent, the
-// server package's live test, the smoke suite — keep importing it from here.
-export { protectedFromDeletion } from '../pod/transport.mjs';
-
-export class RemotePod extends PodTransport {
-  constructor(credential, { log = () => {}, home = null, session = null, role = 'agent' } = {}) {
-    // An injected session replaces the credential-backed one, and everything
-    // above it — the cooldown, the deny-list, the url map — is unchanged. That
-    // is how the agent runs inside a pod server: same class, no token to mint.
-    super(session || createGrantSession(credential, home ? {
-      backoffFile: path.join(home, 'backoff.json'),
-      tokenFile: path.join(home, 'token.json'),
-    } : {}), {
-      webId: credential.webId,
-      log,
-      role,
-      runtime: 'node',
-      // Fail fast for the window rather than sleeping it out: a daemon has
-      // timers behind it, and a request that waits is a timer that does not
-      // fire. The callers' existing retry paths take it from there.
-      cooldownMode: 'refuse',
-    });
-  }
-
-  async warmup() { return this.session.warmup(); }
-
-  /** The grant's own counters, under the transport's. */
-  stats() {
-    return { ...(this.session.stats?.() || {}), ...super.stats() };
-  }
-}
+// The pod transport lives in lib/core/remote.mjs; this path is kept for the
+// callers that import it from here.
+export { RemotePod, mintCredential, discoverTokenEndpoint, revokeCredentialViaAccount, protectedFromDeletion } from '../core/remote.mjs';

package/lib/gateway/copy.mjs

@@ -263,7 +263,13 @@ export async function lockCopy(kv, h, { ms = 60_000, waitMs = 8_000, by = crypto
 export async function fillCopy(kv, h, { pod, podFetch, stateUrl, webId = null, log = () => {} }) {
   if (await copyMeta(kv, h)) return { ok: true, already: true };
   const podLease = new Lease({ url: stateUrl + 'lease.json', fetchImpl: podFetch, log, id: POD_HOLDER });
-  if (!await podLease.acquire()) return { ok: false, why: 'the account is active on another device' };
+  if (!await podLease.acquire()) {
+    // Held is another device acting on the pod; unreadable is the gateway's
+    // own identity refused or unanswered there, which no device has to do with.
+    return podLease.denied === 'unreadable'
+      ? { ok: false, why: `the pod could not be read (${podLease.unreadable})` }
+      : { ok: false, why: 'the account is active on another device' };
+  }
   const undo = async (why) => {
     for (const b of await kv.list(`${h}/d/`).catch(() => [])) await kv.delete(b.key).catch(() => {});
     await podLease.release().catch(() => {});

package/lib/gateway/front-core.mjs

@@ -16,7 +16,8 @@
 // HTTPS box is another. UN-DEPLOYED — nothing in FediPod runs it.
 
 import crypto from 'node:crypto';
-import { handleDelivery, handleOwnerPost } from './gateway-core.mjs';
+import { handleDelivery } from './gateway-core.mjs';
+import { ownerPostAtDoor } from './outbox-door.mjs';
 import { readCapped, safeFetch, isLoopbackHost } from '../shared/safefetch.mjs';
 import * as podRoot from '../pod/root.mjs';
 import * as podPolicy from '../pod/policy.mjs';
@@ -529,6 +530,9 @@ async function route(request, ctx) {
       handle, address, podHome, webId: webid, actorUrl,
       kind: body.kind === 'group' ? 'group' : body.kind === 'application' ? 'application' : 'person',
       gatewayWebId: ctx.gatewayWebId || null, hmacSecret,
+      // When the account was set up here: an app signing in a moment later is
+      // told it is still being got ready, not that it cannot be used.
+      attachedAt: new Date().toISOString(),
       ...(inboxUrl ? { inboxUrl } : {}),
       ...(fronted ? {} : { inboxOnly: true }),
     };
@@ -847,21 +851,7 @@ async function route(request, ctx) {
       return { status: 301, headers: { ...cors, location: movedBase + up.rest, 'cache-control': 'no-store' }, body: '' };
     }
     if (request.method === 'POST') {
-      const json = (status, obj, extra = {}) => ({ status,
-        headers: { ...cors, 'content-type': 'application/json', 'cache-control': 'no-store', ...extra },
-        body: JSON.stringify(obj) });
-      const webid = await verifyPodToken(request, pathname, ctx.verifier);
-      if (!webid) return json(401, { error: 'a Solid-OIDC token proving this account\'s owner is required' });
-      const owner = rec.webId ? webid === rec.webId : webidUnderPod(webid, rec.podHome);
-      if (!owner) return json(403, { error: 'this outbox belongs to its owner alone' });
-      const onPod = (u) => u.replace(rec.actorUrl.replace(/ap\/actor$/u, ''), rec.podHome);
-      const { status, reason, location, object } = await handleOwnerPost(request, identFor(rec),
-        { podPut: (u, b, ct) => ctx.podPut(up.handle, u, b, ct), ownerWebId: webid,
-          exists: async (u) => ((await (ctx.podGet || fetch)(onPod(u), { podHome: rec.podHome })).status !== 404) });
-      console.log(`door @${up.handle}: owner post → ${status} (${reason})`);
-      if (status !== 201) return json(status, { error: reason });
-      return json(201, { accepted: true, ...(location ? { id: location } : {}), ...(object ? { object } : {}),
-        note: 'it goes out when your FediPod agent next runs' }, location ? { location } : {});
+      return ownerPostAtDoor(request, pathname, ctx, rec, up.handle, { cors, identFor, verifyPodToken, webidUnderPod });
     }
     // Its owner, signed in, reads every message the account produced (§5.1:
     // the outbox is filtered by who asks); that view is on the pod, under the

package/lib/gateway/front-pages.mjs

@@ -0,0 +1,31 @@
+// front-pages.mjs — the front's pages and the files they load, read from
+// beside this package: the opt-in page, the roster, the notices page, the
+// new-account page, each page's own script, the sign-in library and the
+// installer. A file that is not there comes back null, and the route it
+// feeds answers 404.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const FRONT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../web/front');
+const SCRIPTS = ['new-account.js', 'run.js', 'admin.js', 'notices.js'];
+
+const readOrNull = (name) => {
+  try { return fs.readFileSync(path.join(FRONT_DIR, name), 'utf8'); } catch { return null; }
+};
+
+/** The pages routeFront serves, in the shape its options take them. */
+export function frontPages() {
+  const pageScripts = {};
+  for (const name of SCRIPTS) pageScripts[name] = readOrNull(name);
+  return {
+    signupPage: readOrNull('new-account.html'),
+    runPage: readOrNull('run.html'),
+    adminPage: readOrNull('admin.html'),
+    noticesPage: readOrNull('notices.html'),
+    authBundle: readOrNull('solid-oidc-client.js'),
+    pageScripts,
+    installScript: readOrNull('install.sh'),
+  };
+}

package/lib/gateway/keeper-session.mjs

@@ -1,10 +1,19 @@
 // keeper-session.mjs — the gateway's own pod identity at work: one grant per
 // running copy, shared by every account it works for, so a round is one token,
 // not one per account (keeper.mjs, state-api.mjs).
+import crypto from 'node:crypto';
 import grant from '../../vendor/idp-grant.cjs';
 
+// The same credential is the same session, however it arrives: the deployment
+// reads its settings into a new object each time, and comparing objects made
+// a new session, and so a new sign-in at the issuer, for every request that
+// reached a pod. Kept as a hash, so the secret is not held here a second time.
+const markOf = (cred) => crypto.createHash('sha256')
+  .update(`${cred.clientId}\n${cred.secret}\n${cred.tokenEndpoint}`).digest('hex');
+
 let shared = null;
 export function keeperSession(cred) {
-  if (!shared || shared.cred !== cred) shared = { cred, session: grant.createGrantSession(cred) };
+  const mark = markOf(cred);
+  if (!shared || shared.mark !== mark) shared = { mark, session: grant.createGrantSession(cred) };
   return shared.session;
 }

package/lib/gateway/masto-gateway.mjs

@@ -7,7 +7,7 @@
 //                                       (/app-signin/, web/app-signin/), which
 //                                       signs them in at their own pod
 //   GET  /api/authorize?client_id=…     what the page shows: the app's name
-//   GET  /api/authorize?address=…       the pod an address here belongs to
+//   GET  /api/authorize?address=…       the pod an address here, or a WebID, belongs to
 //   POST /api/authorize                 the pod sign-in, proved: a code for the app
 //   POST /oauth/token, /oauth/revoke    the code for a token, and back
 //   GET  /api/v1/instance, /api/v2/instance   fedipod.net itself
@@ -97,6 +97,56 @@ function handleOf(address, host) {
   return !at || at === String(host || '').toLowerCase() ? name : a;
 }
 
+/**
+ * The account an address names: a Fediverse address here ("you", "@you",
+ * "you@host", "@you@host", or a whole address on the person's own pod), or a
+ * WebID, which names the browser account here that belongs to it. An account
+ * FediPod has not finished setting up counts: the caller says it is not ready.
+ * Returns { handle, rec }, or { error: [status, message] }.
+ */
+async function accountFor(ctx, address, host) {
+  const a = String(address || '').trim();
+  const here = (r) => !!r && !r.movedTo && !r.closedAt;
+  if (/^https?:\/\//iu.test(a)) {
+    const mine = Object.entries(await ctx.listDirectory?.() || {}).filter(([, r]) => r?.webId === a && here(r));
+    // Kept running first: that is the one an app can use; then opened ones.
+    const kept = mine.filter(([, r]) => r.openedAt && r.keeper);
+    const opened = mine.filter(([, r]) => r.openedAt);
+    const pick = kept.length ? kept : opened.length ? opened : mine;
+    if (pick.length > 1) return { error: [409, 'this WebID has more than one account here; give the Fediverse address of the one to use'] };
+    if (!pick.length) return { error: [404, 'there is no account here for that WebID'] };
+    return { handle: pick[0][0], rec: pick[0][1] };
+  }
+  const handle = handleOf(a, host);
+  // Read fresh: a person is signing in, perhaps a moment after signing up.
+  const rec = handle ? await (ctx.lookupFresh || ctx.lookup)(handle) : null;
+  if (!here(rec)) return { error: [404, 'there is no account with that address here'] };
+  return { handle, rec };
+}
+
+// An account here that an app cannot use. The forum and its categories are
+// run by a server. A personal account set up in the last few minutes and not
+// yet opened: FediPod has not finished its first start. An older one never
+// opened in a browser: made before FediPod noted openings, or run by a server;
+// the gateway cannot tell which. Opened but not kept: new, or its owner
+// stopped keeping it running. The minute rests on a first start seen on
+// 2026-09-26 (24 seconds from opening to kept).
+const NEW_FOR_MS = 10 * 60_000;
+const SERVER_RUN = 'This account is run by a server, not by FediPod in a browser, so apps can\'t sign in to it here.';
+const NOT_READY_NEW = 'This account was set up moments ago, and FediPod is still getting it ready for apps. '
+  + 'That usually takes under a minute. Leave FediPod open in your browser, then try again.';
+const NOT_IN_BROWSER = 'An app can only sign in to an account that FediPod runs in your browser. '
+  + 'If this is one, open it in FediPod first, then try again.';
+const NOT_READY = 'This account can\'t be used from an app yet. If you set it up in the last few minutes, FediPod is '
+  + 'still getting it ready: that usually takes under a minute, so leave FediPod open in your browser and try again. '
+  + 'Otherwise, press "Keep my account running while I\'m away" on your account\'s manage page, then try again.';
+function notReady(rec) {
+  if (rec.kind === 'group' || rec.kind === 'application') return SERVER_RUN;
+  if (rec.openedAt) return NOT_READY;
+  const setUp = Date.parse(rec.attachedAt || '');
+  return setUp && Date.now() - setUp < NEW_FOR_MS ? NOT_READY_NEW : NOT_IN_BROWSER;
+}
+
 // An account an app may sign in to: a browser account here, kept running, not
 // moved or closed.
 const usable = (ctx, rec) => !!(rec && rec.openedAt && keptNow(ctx, rec) && !rec.movedTo && !rec.closedAt);
@@ -409,14 +459,11 @@ async function route(request, pathname, ctx, deps, log) {
       let where = null; try { where = redirect.startsWith('urn:') ? null : new URL(redirect).host || null; } catch { /* a custom scheme */ }
       return json(200, { name: app.name, website: app.website || null, sendsTo: where });
     }
-    const handle = handleOf(url.searchParams.get('address'), host);
-    const rec = handle ? await ctx.lookup(handle) : null;
-    if (!rec?.openedAt || rec.movedTo || rec.closedAt) return json(404, { error: 'there is no account with that address here' });
+    const found = await accountFor(ctx, url.searchParams.get('address'), host);
+    if (found.error) return json(found.error[0], { error: found.error[1] });
+    const { handle, rec } = found;
     if (keptBefore(ctx, rec)) return json(503, { error: MOVING });
-    if (!rec.keeper) {
-      return json(409, { error: 'this account works only while FediPod is open. To use it from an app, turn on '
-        + '"Keep my account running while I\'m away" on its manage page first.' });
-    }
+    if (!rec.openedAt || !rec.keeper) return json(409, { error: notReady(rec) });
     return json(200, { handle, webId: rec.webId });
   }
 
@@ -425,10 +472,11 @@ async function route(request, pathname, ctx, deps, log) {
     const webid = await deps.verifyPodToken(request, pathname, ctx.verifier);
     if (!webid) return json(401, { error: 'sign in at your pod first' });
     const body = await request.clone().json().catch(() => ({}));
-    const handle = handleOf(body.address, host);
-    const rec = handle ? await ctx.lookup(handle) : null;
+    const found = await accountFor(ctx, body.address, host);
+    if (found.error) return json(found.error[0], { error: found.error[1] });
+    const { handle, rec } = found;
     if (keptBefore(ctx, rec)) return json(503, { error: MOVING });
-    if (!usable(ctx, rec)) return json(404, { error: 'there is no account kept running with that address here' });
+    if (!usable(ctx, rec)) return json(409, { error: notReady(rec) });
     if (rec.webId !== webid) return json(403, { error: `you signed in as ${webid}, and this account belongs to ${rec.webId}` });
     const app = await appOf(kv, body.client_id);
     if (!app) return json(400, { error: 'this app has not registered here' });
@@ -436,7 +484,8 @@ async function route(request, pathname, ctx, deps, log) {
     if (redirect !== 'urn:ietf:wg:oauth:2.0:oob' && !app.redirectUris.includes(redirect)) {
       return json(400, { error: 'this app asked to be sent somewhere it did not register' });
     }
-    const made = await ensureCopy(ctx, handle, rec, log);
+    // The owner, proved: not an app checking in, so not made to wait.
+    const made = await ensureCopy(ctx, handle, rec, log, { owner: true });
     if (!made.ok) return json(made.status === 409 ? 503 : made.status, { error: made.why });
     const code = rand(24);
     await putJson(kv, `code/${sha(code)}`, {

package/lib/gateway/outbox-door.mjs

@@ -0,0 +1,31 @@
+// outbox-door.mjs — the owner's own post, taken at the outbox door
+// (front-core.mjs routes it here). The owner is proved by a pod sign-in. The
+// post is written into the pod inbox with a receipt (gateway-core:
+// handleOwnerPost); for a kept account whose FediPod is closed, the keeper is
+// started at once to publish it.
+import { handleOwnerPost } from './gateway-core.mjs';
+import { keptNow } from './copy.mjs';
+import { isPresent } from './held-mail.mjs';
+
+export async function ownerPostAtDoor(request, pathname, ctx, rec, handle, { cors, identFor, verifyPodToken, webidUnderPod }) {
+  const json = (status, obj, extra = {}) => ({ status,
+    headers: { ...cors, 'content-type': 'application/json', 'cache-control': 'no-store', ...extra },
+    body: JSON.stringify(obj) });
+  const webid = await verifyPodToken(request, pathname, ctx.verifier);
+  if (!webid) return json(401, { error: 'a Solid-OIDC token proving this account\'s owner is required' });
+  const owner = rec.webId ? webid === rec.webId : webidUnderPod(webid, rec.podHome);
+  if (!owner) return json(403, { error: 'this outbox belongs to its owner alone' });
+  const onPod = (u) => u.replace(rec.actorUrl.replace(/ap\/actor$/u, ''), rec.podHome);
+  const { status, reason, location, object } = await handleOwnerPost(request, identFor(rec),
+    { podPut: (u, b, ct) => ctx.podPut(handle, u, b, ct), ownerWebId: webid,
+      exists: async (u) => ((await (ctx.podGet || fetch)(onPod(u), { podHome: rec.podHome })).status !== 404) });
+  console.log(`door @${handle}: owner post → ${status} (${reason})`);
+  if (status !== 201) return json(status, { error: reason });
+  // Kept and closed: the keeper publishes it now rather than at the next visit.
+  let now = false;
+  if (keptNow(ctx, rec) && ctx.startKeeper && !(await isPresent(ctx, handle).catch(() => false))) {
+    now = await ctx.startKeeper(handle).then(() => true, (e) => { console.log(`door @${handle}: keeper not started: ${e?.message || e}`); return false; });
+  }
+  return json(201, { accepted: true, ...(location ? { id: location } : {}), ...(object ? { object } : {}),
+    note: now ? 'it goes out in a moment' : 'it goes out when your FediPod agent next runs' }, location ? { location } : {});
+}

package/lib/gateway/state-api.mjs

@@ -49,19 +49,44 @@ export const stateUrlOf = (rec) => `${rec.podHome.replace(/\/?$/u, '/')}ap-state
 export const keepsCopies = (ctx) => !!(ctx.copyKv && ctx.keeperWebId && ctx.keeperFetch && ctx.stateSecret);
 
 const FILL_RETRY_MS = 5 * 60_000;
+// The gateway's own sign-in at its pod's issuer refused: nothing an account
+// does changes that, so no account's copy is tried for this long. Held against
+// the credential it failed with (ctx.keeperMark); a new one is tried at once.
+const LOGIN_PAUSE_MS = 15 * 60_000;
+const LOGIN_REFUSED = '_keeper/login-refused';
+const refusedSignIn = (why) => /token request failed \(HTTP 40[01]\)/u.test(why || '');
+async function loginRefused(ctx) {
+  let r = null;
+  try { r = JSON.parse((await ctx.copyKv.get(LOGIN_REFUSED))?.text || 'null'); } catch { /* none */ }
+  return r && r.mark === (ctx.keeperMark || '') && Date.now() - r.at < LOGIN_PAUSE_MS ? r : null;
+}
+
+// The last failed attempt: { at, why }. Written as a bare time before 2026-09-26.
+async function lastFailure(kv, handle) {
+  const text = (await kv.get(`${handle}/fill-failed-at`))?.text || '';
+  try { const f = JSON.parse(text); return typeof f === 'number' ? { at: f, why: null } : { at: Number(f?.at) || 0, why: f?.why || null }; }
+  catch { return { at: 0, why: null }; }
+}
+const noteFailure = (kv, handle, why = null) => kv.set(`${handle}/fill-failed-at`, JSON.stringify({ at: Date.now(), why })).catch(() => {});
 
 /**
  * The copy for an account, made from the pod when there is none: one maker at
  * a time, and after a failed attempt not again for five minutes, so an app
  * checking in every minute does not read the pod every minute. `owner`: the
- * owner's own browser asking, which is not made to wait. Returns { ok } or
- * { ok: false, status, why }.
+ * owner asking, from their own browser or by signing in at the app sign-in
+ * page, which is not made to wait. After the gateway's own sign-in is refused,
+ * no account is tried for fifteen minutes, the owner's included, unless the
+ * credential has changed since. Returns { ok } or { ok: false, status, why }.
  */
 export async function ensureCopy(ctx, handle, rec, log = console.log, { owner = false } = {}) {
   if (await copyMeta(ctx.copyKv, handle)) return { ok: true };
-  const failedAt = Number((await ctx.copyKv.get(`${handle}/fill-failed-at`))?.text || 0);
-  if (!owner && Date.now() - failedAt < FILL_RETRY_MS) {
-    return { ok: false, status: 503, why: 'this account could not be opened a moment ago; try again in a few minutes' };
+  // The owner too: it is the gateway's credential that has to change.
+  const refused = await loginRefused(ctx);
+  if (refused) return { ok: false, status: 503, why: `this account could not be opened: ${refused.why}. Try again later` };
+  const failed = await lastFailure(ctx.copyKv, handle);
+  if (!owner && Date.now() - failed.at < FILL_RETRY_MS) {
+    return { ok: false, status: 503,
+      why: `this account could not be opened a moment ago${failed.why ? `: ${failed.why}` : ''}. Try again in a few minutes` };
   }
   const podFetch = await ctx.keeperFetch();
   if (!podFetch) return { ok: false, status: 501, why: 'this gateway cannot reach pods for accounts' };
@@ -71,11 +96,16 @@ export async function ensureCopy(ctx, handle, rec, log = console.log, { owner =
     if (await copyMeta(ctx.copyKv, handle)) return { ok: true };
     // Marked failed before it starts and cleared when it is done, so an attempt
     // cut off part way (a request's time running out) counts as failed too.
-    await ctx.copyKv.set(`${handle}/fill-failed-at`, String(Date.now())).catch(() => {});
+    await noteFailure(ctx.copyKv, handle);
     const stateUrl = stateUrlOf(rec);
     const made = await fillCopy(ctx.copyKv, handle, { pod: new HttpStorage(stateUrl, podFetch), podFetch, stateUrl, webId: rec.webId, log })
       .catch((e) => ({ ok: false, why: e.message }));
     if (made.ok) { await ctx.copyKv.delete(`${handle}/fill-failed-at`).catch(() => {}); return { ok: true }; }
+    await noteFailure(ctx.copyKv, handle, made.why);
+    log(`copy @${handle}: not made: ${made.why}`);
+    if (refusedSignIn(made.why)) {
+      await ctx.copyKv.set(LOGIN_REFUSED, JSON.stringify({ at: Date.now(), mark: ctx.keeperMark || '', why: made.why })).catch(() => {});
+    }
     return { ok: false, status: /active on another device/.test(made.why) ? 409 : 502, why: made.why };
   } finally { await unlock(); }
 }
@@ -107,7 +137,9 @@ export async function routeStateApi(request, pathname, ctx, deps) {
     try { body = JSON.parse((await request.clone().text()) || '{}'); } catch { return j(400, { error: 'bad JSON' }); }
     // The account: named, or the one browser account kept here for this WebID.
     let handle = String(body.handle || '').toLowerCase();
-    let rec = handle ? await ctx.lookup(handle) : null;
+    // Read fresh: FediPod asks this the moment it has turned keeping on, and a
+    // row read a minute earlier would still say the account is not kept.
+    let rec = handle ? await (ctx.lookupFresh || ctx.lookup)(handle) : null;
     if (!handle) {
       const rows = Object.entries(await ctx.listDirectory?.() || {})
         .filter(([, r]) => r?.webId === webid && r.openedAt && r.keeper && !r.movedTo && !r.closedAt);

package/lib/server/embed.mjs

@@ -16,12 +16,12 @@ import path from 'node:path';
 
 import { createRequire } from 'node:module';
 
-import { Agent } from '../../run-agent.mjs';
-import { RemotePod } from '../device/remote.mjs';
+import { Agent } from '../core/agent.mjs';
+import { RemotePod } from '../core/remote.mjs';
 import { apUrls, DEFAULT_ROOT } from '../core/wire.mjs';
 import { handleDelivery } from '../gateway/gateway-core.mjs';
-import { writeJsonAtomic } from '../device/home.mjs';
-import { buildAdminSurface } from '../device/admin/index.mjs';
+import { writeJsonAtomic } from '../shared/files.mjs';
+import { buildAdminSurface } from '../surface/index.mjs';
 import { FixedAuthorities } from '../shared/guard.mjs';
 import { CONNECTION_PREFIX, fileVault, moveVault, podVault } from '../connections/vault.mjs';
 

package/lib/shared/files.mjs

@@ -0,0 +1,49 @@
+// files.mjs — writing a file without a window in which it is half there, and
+// showing a path the way a person types it.
+//
+// The files written this way are the ones nothing can rebuild: keys.json is
+// the private key remote servers have cached, and credential.json holds a
+// secret a Solid server mints once and will not mint again. A plain
+// writeFileSync truncates first, so a crash, a power loss or a full disk
+// between truncate and write leaves an empty or half-written file where the
+// identity used to be.
+//
+// rename(2) is atomic on POSIX, so a reader — or a backup running at the wrong
+// moment — sees either the old file or the new one. fsync before it, so the
+// content is on the platter and not merely in the page cache when the rename
+// lands. Windows has no atomic rename over an existing file; there the copy
+// path is still better than a truncate, and this is a best effort by design.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function writeFileAtomic(file, body, { mode = 0o600 } = {}) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const fd = fs.openSync(tmp, 'w', mode);
+  try {
+    fs.writeFileSync(fd, body);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+}
+
+// The same, for the JSON these files all happen to be.
+export function writeJsonAtomic(file, obj, opts) {
+  writeFileAtomic(file, JSON.stringify(obj, null, 2) + '\n', opts);
+}
+
+// A path for display: the home directory becomes `~`, a `file:` URL is shown
+// as the path it is. Never used to build a path — `~` is the shell's, not the
+// filesystem's, and anything that resolves one must expand it first.
+export function tildify(p, homedir = os.homedir()) {
+  if (!p) return p;
+  let s = String(p);
+  if (s.startsWith('file://')) { try { s = fileURLToPath(s); } catch { return s; } }
+  if (s === homedir) return '~';
+  return s.startsWith(homedir + path.sep) ? '~' + s.slice(homedir.length) : s;
+}

package/lib/shared/ua.mjs

@@ -27,3 +27,6 @@ try {
 // Renamed 2026-07-31, once solidcommunity.net was back up and both actors there
 // were retired: the name in their logs no longer has to match the name in here.
 export const USER_AGENT = `fedipod/${version} (+https://github.com/jeff-zucker/FediPod)`;
+// The same version, for anything else that reports it (the publisher's
+// nodeinfo and status), read the same best-effort way.
+export const AGENT_VERSION = version;

package/lib/surface/index.mjs

@@ -0,0 +1,7 @@
+// The identity's HTTP surface: the Mastodon client API and OAuth, the
+// ActivityPub client-to-server door, nodeinfo, the owner's door and routes,
+// and the pages and client served off disk. buildAdminSurface returns one
+// request handler; whatever listens hands it requests.
+
+export { buildAdminSurface } from './surface.mjs';
+export { namedOrigin, secureOrigin, wsOrigins } from './origins.mjs';

package/lib/{device/admin → surface}/origins.mjs

@@ -1,7 +1,7 @@
 // origins.mjs — the addresses an identity answers on, as a browser must be
 // sent to them.
 
-import { allowedAuthorities, hostLabel } from '../../shared/guard.mjs';
+import { allowedAuthorities, hostLabel } from '../shared/guard.mjs';
 
 // The origin a browser should be sent to for an identity. A browser keys
 // storage per ORIGIN, so linking every identity at localhost:<port> files them

package/lib/{device/admin → surface}/routes/gateway.mjs

@@ -4,10 +4,9 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
 
 export async function post(p, body, ctx, req, res) {   // eslint-disable-line no-unused-vars
-  const { agent, log, allowed, embedded, port, publicOrigin, versionOnDisk, isGroup } = ctx;   // eslint-disable-line no-unused-vars
+  const { agent, log, allowed, embedded, port, publicOrigin, versionOnDisk, isGroup, restart } = ctx;   // eslint-disable-line no-unused-vars
   const json = (res, status, obj) => { ctx.json(res, status, obj); return true; };
   switch (p) {
     // The inbox gateway lifecycle (opt-in). `configure` points at a
@@ -50,15 +49,10 @@ export async function post(p, body, ctx, req, res) {   // eslint-disable-line no
         const root = cfg.root ? (cfg.root.endsWith('/') ? cfg.root : `${cfg.root}/`) : 'fedipod/';
         return `${base}${root}ap/actor`;
       };
-      // The reply first, the restart a beat later — same shape as /update.
-      const selfRestart = (why) => setTimeout(() => {
-        log(why);
-        if (process.env.INVOCATION_ID) { process.exit(1); return; }   // systemd: Restart=on-failure respawns
-        const child = spawn(process.execPath, process.argv.slice(1),
-          { detached: true, stdio: 'ignore', env: process.env });
-        child.unref();
-        setTimeout(() => process.exit(0), 300);
-      }, 200);
+      // Fronting and un-fronting rename every id, which only a restart
+      // applies. A host that cannot restart itself refuses them.
+      const selfRestart = restart;
+      const noRestart = { error: 'this identity runs inside its pod server, which cannot restart for it — front it, or un-front it, from a standalone agent' };
       if (body.action === 'configure') {
         if (!/^https:\/\/\S+$/.test(String(body.url || ''))) return json(res, 400, { error: 'gateway url must be https' });
         if (!/^https?:\/\/\S+$/.test(String(body.webId || ''))) return json(res, 400, { error: 'gateway webId must be a URL' });
@@ -121,6 +115,7 @@ export async function post(p, body, ctx, req, res) {   // eslint-disable-line no
         if (agent.embedded) {
           return json(res, 400, { error: 'this identity runs inside its pod server and has no portable credential — attach from a standalone agent' });
         }
+        if (body.fronted === true && !selfRestart) return json(res, 400, noRestart);
         const named = !!String(body.handle || '').trim();
         let handle = String(body.handle || cfg.handle || '').toLowerCase().trim();
         if (!handle) return json(res, 400, { error: 'a name at the gateway is required' });
@@ -177,6 +172,7 @@ export async function post(p, body, ctx, req, res) {   // eslint-disable-line no
       if (body.action === 'forget') {
         const wasLocked = g.mode === 'locked';
         const wasFronted = !!g.frontActor;
+        if (wasFronted && !selfRestart) return json(res, 400, noRestart);
         delete cfg.gateway; agent.store.setConfig(cfg);
         if (agent.publisher) agent.publisher.config.gateway = undefined;
         await agent.store.flush();