fedipod 0.8.0

package/lib/c2s.mjs

@@ -0,0 +1,305 @@
+// c2s.mjs — ActivityPub client-to-server (§6): the spec's own write API,
+// beside the Mastodon facade. A client POSTs an activity — or a bare object,
+// which is wrapped in a Create (§6.2.1) — to this actor's outbox; the agent
+// assigns ids, applies the side-effects and delivers. Every verb lands on the
+// SAME helper the facade and admin surfaces use — this module re-implements
+// no persistence and no delivery, so one write path stays one.
+//
+// GETs are redirects: the pod's documents are the canonical actor and outbox,
+// and a second renderer here would only drift from them.
+
+import * as social from './social.mjs';
+import * as wire from './wire.mjs';
+
+const MAX_BODY = 512 * 1024;          // same ceiling the inbox drain enforces
+
+// §6 names activities; anything else with a type is an object to wrap.
+const ACTIVITY_TYPES = new Set([
+  'Create', 'Update', 'Delete', 'Follow', 'Like', 'Announce', 'Undo',
+  'Block', 'Add', 'Remove', 'Accept', 'Reject', 'Move',
+]);
+
+const arr = (v) => (v === undefined || v === null ? [] : Array.isArray(v) ? v : [v]);
+const idOf = (v) => (typeof v === 'string' ? v : v?.id || null);
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (c) => {
+      size += c.length;
+      if (size > MAX_BODY) { reject(new Error('body too large')); req.destroy(); return; }
+      chunks.push(c);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+export class C2S {
+  constructor({ agent, log = console.log, auth }) {
+    this.agent = agent;
+    this.log = log;
+    this.auth = auth;
+  }
+
+  get store() { return this.agent.store; }
+  get urls() { return this.agent.publisher?.urls; }
+
+  send(res, status, obj, headers = {}) {
+    res.writeHead(status, {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'no-store',
+      ...headers,
+    });
+    res.end(JSON.stringify(obj));
+    return true;
+  }
+
+  byIri(iri) {
+    return iri ? this.store.getStatuses().find((s) => s.noteId === iri) : null;
+  }
+
+  async handle(req, res, pathname, url) {   // eslint-disable-line no-unused-vars
+    if (pathname !== '/ap/outbox' && pathname !== '/ap/actor') return false;
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, { allow: 'GET, POST, OPTIONS' }); res.end(); return true;
+    }
+    if (!this.agent.configured() || !this.urls) {
+      return this.send(res, 409, { error: 'agent not configured' });
+    }
+    if (req.method === 'GET' || req.method === 'HEAD') {
+      // The pod's copy is the document; send the reader there.
+      const target = pathname === '/ap/actor' ? this.urls.actor : this.urls.outbox;
+      res.writeHead(303, { location: target, 'cache-control': 'no-store' });
+      res.end();
+      return true;
+    }
+    if (pathname !== '/ap/outbox' || req.method !== 'POST') {
+      return this.send(res, 405, { error: 'POST the outbox; GET redirects to the pod' });
+    }
+
+    const who = await this.auth(req, pathname);
+    if (!who.ok) return this.send(res, who.status, { error: who.error });
+
+    // A viewer (another agent holds the lease) may not act — but the user
+    // acting HERE outranks an idle active agent elsewhere, exactly as on the
+    // facade: a write attempt claims the lease, and only a failed claim 503s.
+    if (this.agent.viewer) {
+      const took = await this.agent.requestTakeover?.();
+      if (!took) return this.send(res, 503, { error: 'another agent is active for this pod — takeover failed, try again' });
+    }
+
+    let activity;
+    try {
+      activity = JSON.parse(await readBody(req));
+    } catch (e) {
+      return this.send(res, 400, { error: `unreadable body: ${e.message}` });
+    }
+    if (!activity || typeof activity !== 'object' || Array.isArray(activity) || !activity.type) {
+      return this.send(res, 400, { error: 'a typed ActivityStreams object is required' });
+    }
+    // A bare object arrives without an activity around it; the server supplies
+    // the Create (§6.2.1), carrying the object's own addressing up onto it.
+    if (!ACTIVITY_TYPES.has(activity.type)) {
+      activity = { type: 'Create', object: activity, to: activity.to, cc: activity.cc };
+    }
+
+    try {
+      return await this.dispatch(res, activity);
+    } catch (e) {
+      this.log(`c2s ${activity.type}: ${e.message}`);
+      return this.send(res, 422, { error: e.message || String(e) });
+    }
+  }
+
+  // Addressing → the facade's four visibilities, inverting the table the
+  // composer writes (wire.noteDoc). Addressing is required: a post whose
+  // audience the client never stated is not guessed at in either direction.
+  visibilityOf(activity, object) {
+    const to = arr(activity.to ?? object?.to).map(idOf);
+    const cc = arr(activity.cc ?? object?.cc).map(idOf);
+    if (!to.length && !cc.length) return null;
+    if (to.includes(wire.PUBLIC)) return 'public';
+    if (cc.includes(wire.PUBLIC)) return 'unlisted';
+    if (to.includes(this.urls.followers)) return 'private';
+    return 'direct';
+  }
+
+  async dispatch(res, activity) {
+    const agent = this.agent;
+    const object = typeof activity.object === 'object' && activity.object !== null
+      ? activity.object : null;
+    const objectId = idOf(activity.object);
+
+    switch (activity.type) {
+      case 'Create': {
+        if (!object || (object.type && object.type !== 'Note')) {
+          return this.send(res, 422, { error: 'only a Note (or a bare Note) can be created here' });
+        }
+        const visibility = this.visibilityOf(activity, object);
+        if (!visibility) {
+          return this.send(res, 400, { error: 'state the audience: to/cc must address someone (as:Public, your followers collection, or actors)' });
+        }
+        // `source.content` is the client's plain text when it sends one; bare
+        // `content` is TREATED as plain text and escaped — markup survives as
+        // visible characters rather than as markup. Documented v1 limit.
+        const text = String(object.source?.content ?? object.content ?? '');
+        if (!text.trim()) return this.send(res, 422, { error: 'the note has no content' });
+        const attachments = arr(object.attachment).map((a) => ({
+          url: a?.url, mediaType: a?.mediaType,
+          ...(a?.name ? { description: a.name } : {}),
+        })).filter((a) => a.url);
+        const note = await agent.publisher.publishNote(text, {
+          inReplyTo: idOf(object.inReplyTo) || undefined,
+          attachments,
+          visibility,
+          spoilerText: object.summary || null,
+        });
+        return this.send(res, 201, { id: wire.createActivityId(note.id), object: note.id },
+          { location: wire.createActivityId(note.id) });
+      }
+
+      case 'Update': {
+        if (objectId === this.urls.actor) {
+          return this.send(res, 422, { error: 'edit the profile on the admin surface; actor updates are not taken here' });
+        }
+        const s = this.byIri(objectId);
+        if (!s) return this.send(res, 404, { error: 'no such note here' });
+        if (s.actor !== this.urls.actor || s.kind !== 'post') {
+          return this.send(res, 403, { error: 'not your note' });
+        }
+        const text = String(object?.source?.content ?? object?.content ?? '');
+        if (!text.trim()) return this.send(res, 422, { error: 'the edit has no content' });
+        const attachments = object?.attachment !== undefined
+          ? arr(object.attachment).map((a) => ({
+            url: a?.url, mediaType: a?.mediaType,
+            ...(a?.name ? { description: a.name } : {}),
+          })).filter((a) => a.url)
+          : null;
+        await agent.publisher.updateNote(s, {
+          content: text, spoilerText: object?.summary || null, attachments,
+        });
+        return this.send(res, 200, { ok: true, object: s.noteId });
+      }
+
+      case 'Delete': {
+        if (objectId === this.urls.actor) {
+          return this.send(res, 422, { error: 'retiring the actor is done on the admin surface, where it asks twice' });
+        }
+        const s = this.byIri(objectId);
+        if (!s) return this.send(res, 404, { error: 'no such note here' });
+        if (s.actor !== this.urls.actor || s.kind !== 'post') {
+          return this.send(res, 403, { error: 'not your note' });
+        }
+        const r = await social.deleteNote(agent, s);
+        if (!r.ok) return this.send(res, 502, { error: r.error, stillPublished: r.stillPublished });
+        return this.send(res, 200, { ok: true });
+      }
+
+      case 'Follow': {
+        if (!objectId) return this.send(res, 400, { error: 'whom? object must name an actor' });
+        // An acct: form or bare handle resolves through WebFinger; an https
+        // IRI is fetched directly.
+        if (/^acct:|^@|^[^/@]+@[^/@]+$/.test(objectId) && !/^https?:/.test(objectId)) {
+          const r = await social.followHandle(agent, objectId.replace(/^acct:/, ''));
+          const rec = this.store.getContacts().following.find((f) => f.actor === r.actor);
+          return this.send(res, 201, { id: rec?.followActivity?.id, object: r.actor },
+            rec?.followActivity?.id ? { location: rec.followActivity.id } : {});
+        }
+        const doc = await social.followActor(agent, objectId);
+        const rec = this.store.getContacts().following.find((f) => f.actor === doc.id);
+        return this.send(res, 201, { id: rec?.followActivity?.id, object: doc.id },
+          rec?.followActivity?.id ? { location: rec.followActivity.id } : {});
+      }
+
+      case 'Like': {
+        const s = this.byIri(objectId);
+        if (!s) return this.send(res, 422, { error: 'that note is not held here — like what the timeline holds' });
+        const updated = await social.favourite(agent, s);
+        return this.send(res, 201, { id: updated.likeActivity?.id, object: s.noteId },
+          updated.likeActivity?.id ? { location: updated.likeActivity.id } : {});
+      }
+
+      case 'Announce': {
+        const s = this.byIri(objectId);
+        if (!s) return this.send(res, 422, { error: 'that note is not held here — boost what the timeline holds' });
+        const updated = await social.reblog(agent, s);
+        return this.send(res, 201, { id: updated.announceActivity?.id, object: s.noteId },
+          updated.announceActivity?.id ? { location: updated.announceActivity.id } : {});
+      }
+
+      case 'Undo': {
+        // What is being unsaid — by the inner activity's id when the client
+        // sends one, by its type+object when it re-states it instead.
+        const inner = object;
+        const innerId = idOf(activity.object);
+        if (inner?.type === 'Block') {
+          const target = idOf(inner.object);
+          if (!target) return this.send(res, 400, { error: 'unblock whom?' });
+          await social.unblockActor(agent, target);
+          return this.send(res, 200, { ok: true, object: target });
+        }
+        const statuses = this.store.getStatuses();
+        let s = innerId ? statuses.find((x) => x.likeActivity?.id === innerId) : null;
+        if (!s && inner?.type === 'Like') s = this.byIri(idOf(inner.object));
+        if (s?.favourited) {
+          const updated = await social.unfavourite(agent, s);
+          return this.send(res, 200, { ok: true, object: updated.noteId });
+        }
+        s = innerId ? statuses.find((x) => x.announceActivity?.id === innerId) : null;
+        if (!s && inner?.type === 'Announce') s = this.byIri(idOf(inner.object));
+        if (s?.reblogged) {
+          const updated = await social.unreblog(agent, s);
+          return this.send(res, 200, { ok: true, object: updated.noteId });
+        }
+        const following = this.store.getContacts().following;
+        const rec = following.find((f) => f.followActivity?.id === innerId)
+          || (inner?.type === 'Follow' ? following.find((f) => f.actor === idOf(inner.object)) : null);
+        if (rec) {
+          await social.unfollowActor(agent, rec.actor);
+          return this.send(res, 200, { ok: true, object: rec.actor });
+        }
+        return this.send(res, 422, { error: 'nothing here matches what that Undo names' });
+      }
+
+      case 'Block': {
+        if (!objectId) return this.send(res, 400, { error: 'block whom? object must name an actor' });
+        await social.blockActor(agent, objectId);
+        return this.send(res, 200, { ok: true, object: objectId });
+      }
+
+      case 'Add':
+      case 'Remove': {
+        // The one collection a client may edit is the pins (§7.6/§7.9 in the
+        // other direction): target must be the featured collection.
+        if (idOf(activity.target) !== this.urls.featured) {
+          return this.send(res, 422, { error: 'the featured collection is the one Add/Remove edits here' });
+        }
+        const s = this.byIri(objectId);
+        if (!s) return this.send(res, 404, { error: 'no such note here' });
+        const updated = await social.pinStatus(agent, s, activity.type === 'Add');
+        return this.send(res, 200, { ok: true, object: updated.noteId, pinned: !!updated.pinned });
+      }
+
+      case 'Accept':
+      case 'Reject': {
+        // Answering a held follow request: the object is the Follow (or the
+        // requester). Which request is meant comes from the Follow's actor.
+        const requester = object?.actor ? idOf(object.actor) : objectId;
+        if (!requester) return this.send(res, 400, { error: 'whose request? object must name the Follow or its actor' });
+        const r = activity.type === 'Accept'
+          ? await social.admitRequest(agent, requester).catch((e) => ({ error: e.message }))
+          : await social.refuseRequest(agent, requester).catch((e) => ({ error: e.message }));
+        if (r.error) return this.send(res, 404, { error: r.error });
+        return this.send(res, 200, { ok: true, object: requester });
+      }
+
+      case 'Move':
+        return this.send(res, 422, { error: 'moving the account is done on the admin surface, where it asks twice' });
+
+      default:
+        return this.send(res, 422, { error: `no handler for ${activity.type}` });
+    }
+  }
+}

package/lib/certs.mjs

@@ -0,0 +1,265 @@
+// certs.mjs — TLS for the local agent, minted per machine. Nothing here is
+// ever packaged or shared: a certificate that ships with the app would carry
+// one private key for every install, which protects nobody.
+//
+// The first agent start mints a local CA and signs the server certificate
+// with it, and the CA — never the server key — is placed in the user's
+// browser trust store where that can be done without privileges (NSS on
+// Linux). The CA carries a critical name constraint limiting it to localhost
+// names and loopback addresses, so even a stolen CA key can never vouch for
+// a real site. `fedipod https --trust` remains for the system-wide store and
+// for setups where the automatic step could not run.
+//
+// The certificate covers localhost, *.localhost (every named agent origin),
+// and both loopback addresses, so one file serves all identities on the
+// machine. Files live under <root>/certs/, 0600.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const forge = require('node-forge');
+
+const FILES = {
+  key: 'localhost-key.pem',
+  cert: 'localhost-cert.pem',
+  caKey: 'ca-key.pem',
+  caCert: 'ca-cert.pem',
+};
+// Apple platforms reject leaf certificates valid longer than ~825 days.
+const LEAF_DAYS = 820;
+const CA_DAYS = 3650;
+const REMINT_DAYS = 30;        // re-mint when this close to expiry
+
+const SANS = [
+  { type: 2, value: 'localhost' },
+  { type: 2, value: '*.localhost' },
+  { type: 7, ip: '127.0.0.1' },
+  { type: 7, ip: '::1' },
+];
+
+const p = (dir, name) => path.join(dir, name);
+const readPem = (dir, name) => {
+  try { return fs.readFileSync(p(dir, name), 'utf8'); } catch { return null; }
+};
+const writePem = (dir, name, pem) => {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(p(dir, name), pem, { mode: 0o600 });
+};
+
+// RFC 5280 name constraints, permitted-only: dNSName "localhost" (which by
+// the RFC's left-labels rule also covers every *.localhost), 127.0.0.0/8 and
+// ::1. Critical, so a validator that cannot enforce it rejects the chain
+// rather than ignoring the limit. forge has no builder for this extension,
+// so the DER is assembled here.
+function nameConstraintsExtension() {
+  const { asn1 } = forge;
+  const dns = (name) => asn1.create(asn1.Class.CONTEXT_SPECIFIC, 2, false, name);
+  const ip = (bytes) => asn1.create(asn1.Class.CONTEXT_SPECIFIC, 7, false, bytes);
+  const subtree = (generalName) =>
+    asn1.create(asn1.Class.UNIVERSAL, asn1.Type.SEQUENCE, true, [generalName]);
+  const permitted = asn1.create(asn1.Class.CONTEXT_SPECIFIC, 0, true, [
+    subtree(dns('localhost')),
+    subtree(ip('\x7f\x00\x00\x00\xff\x00\x00\x00')),                    // 127.0.0.0/8
+    subtree(ip('\x00'.repeat(15) + '\x01' + '\xff'.repeat(16))),        // ::1/128
+  ]);
+  const der = asn1.toDer(asn1.create(asn1.Class.UNIVERSAL, asn1.Type.SEQUENCE, true, [permitted]));
+  return { id: '2.5.29.30', critical: true, value: der.getBytes() };
+}
+
+function makeCert({ subjectCN, issuer = null, issuerKeyPem = null, isCA = false, days, extraDns = [] }) {
+  const keys = forge.pki.rsa.generateKeyPair({ bits: 2048 });
+  const cert = forge.pki.createCertificate();
+  cert.publicKey = keys.publicKey;
+  cert.serialNumber = '02' + crypto.randomBytes(15).toString('hex');
+  cert.validity.notBefore = new Date(Date.now() - 24 * 3600e3);
+  cert.validity.notAfter = new Date(Date.now() + days * 24 * 3600e3);
+  const subject = [{ name: 'commonName', value: subjectCN }, { name: 'organizationName', value: 'FediPod' }];
+  cert.setSubject(subject);
+  cert.setIssuer(issuer || subject);
+  cert.setExtensions(isCA
+    ? [{ name: 'basicConstraints', cA: true, critical: true },
+       { name: 'keyUsage', keyCertSign: true, cRLSign: true, critical: true },
+       nameConstraintsExtension(),
+       { name: 'subjectKeyIdentifier' }]
+    : [{ name: 'basicConstraints', cA: false },
+       { name: 'keyUsage', digitalSignature: true, keyEncipherment: true },
+       { name: 'extKeyUsage', serverAuth: true },
+       { name: 'subjectAltName',
+         altNames: [...SANS, ...extraDns.map(v => ({ type: 2, value: v }))] }]);
+  const signingKey = issuerKeyPem ? forge.pki.privateKeyFromPem(issuerKeyPem) : keys.privateKey;
+  cert.sign(signingKey, forge.md.sha256.create());
+  return {
+    keyPem: forge.pki.privateKeyToPem(keys.privateKey),
+    certPem: forge.pki.certificateToPem(cert),
+  };
+}
+
+// The DNS names a certificate carries. Wildcards do not help here: strict
+// validators (OpenSSL, browsers) refuse `*.localhost` as a wildcard over a
+// top-level name, so every agent's own <handle>.localhost must be listed
+// outright, and a new identity's first start re-mints to include its name.
+const certDnsNames = (certPem) => {
+  try {
+    return (new crypto.X509Certificate(certPem).subjectAltName || '')
+      .split(',').map(s => s.trim()).filter(s => s.startsWith('DNS:')).map(s => s.slice(4));
+  } catch { return []; }
+};
+
+const daysLeft = (certPem) => {
+  try {
+    const x = new crypto.X509Certificate(certPem);
+    return (new Date(x.validTo).getTime() - Date.now()) / (24 * 3600e3);
+  } catch { return -1; }
+};
+const coversLocalhost = (certPem) => {
+  try {
+    return /\*\.localhost/.test(new crypto.X509Certificate(certPem).subjectAltName || '');
+  } catch { return false; }
+};
+
+// What an agent calls at boot: the current server key + cert, minted or
+// re-minted as needed. Trust mode is sticky — once a CA exists, re-mints are
+// signed by it, so an installed trust anchor keeps working across renewals.
+export function ensureLocalTls(dir, { log = () => {}, names = [] } = {}) {
+  const caKey = readPem(dir, FILES.caKey);
+  const caCert = readPem(dir, FILES.caCert);
+  const trust = !!(caKey && caCert);
+  const isStale = (k, c) => !k || !c || daysLeft(c) < REMINT_DAYS || !coversLocalhost(c)
+    || (trust && !issuedBy(c, caCert))
+    || names.some(n => !certDnsNames(c).includes(n));
+  let key = readPem(dir, FILES.key);
+  let cert = readPem(dir, FILES.cert);
+  if (isStale(key, cert)) {
+    // One minter at a time: agents on a machine start together, and the key
+    // and certificate are two files — unlocked, two concurrent minters can
+    // interleave and pair one's key with the other's certificate. Losers
+    // wait for the winner and take its files; a lock left by a crash is
+    // stolen once it is a minute old.
+    const lock = p(dir, '.mint-lock');
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    let locked = false;
+    try { fs.mkdirSync(lock); locked = true; } catch { /* someone else is minting */ }
+    if (!locked) {
+      const tick = new Int32Array(new SharedArrayBuffer(4));
+      for (let i = 0; i < 100; i++) {
+        Atomics.wait(tick, 0, 0, 100);
+        if (!fs.existsSync(lock)) break;
+        try {
+          if (Date.now() - fs.statSync(lock).mtimeMs > 60_000) { fs.rmdirSync(lock); break; }
+        } catch { break; }
+      }
+      key = readPem(dir, FILES.key);
+      cert = readPem(dir, FILES.cert);
+      if (!isStale(key, cert)) return { key, cert, trust, dir, expiresInDays: Math.floor(daysLeft(cert)) };
+      try { fs.mkdirSync(lock); locked = true; } catch { /* still contended — mint anyway */ }
+    }
+    try {
+      // Keep every name the outgoing certificate carried: agents share one
+      // file, and a re-mint for one identity must not orphan the others.
+      const carried = [...new Set([...certDnsNames(cert || ''), ...names])]
+        .filter(n => n !== 'localhost' && n !== '*.localhost');
+      const minted = makeCert({
+        subjectCN: 'localhost',
+        ...(trust ? { issuer: caSubject(caCert), issuerKeyPem: caKey } : {}),
+        days: LEAF_DAYS,
+        extraDns: carried,
+      });
+      writePem(dir, FILES.key, minted.keyPem);
+      writePem(dir, FILES.cert, minted.certPem);
+      key = minted.keyPem;
+      cert = minted.certPem;
+      log(`minted a ${trust ? 'CA-signed' : 'self-signed'} https certificate for localhost + *.localhost`);
+    } finally {
+      if (locked) { try { fs.rmdirSync(lock); } catch { /* already gone */ } }
+    }
+  }
+  return { key, cert, trust, dir, expiresInDays: Math.floor(daysLeft(cert)) };
+}
+
+const caSubject = (caCertPem) => forge.pki.certificateFromPem(caCertPem).subject.attributes
+  .map(a => ({ name: a.name, value: a.value }));
+const issuedBy = (certPem, caCertPem) => {
+  try {
+    return new crypto.X509Certificate(certPem).checkIssued(new crypto.X509Certificate(caCertPem));
+  } catch { return false; }
+};
+
+// Mint the local CA once. First writer wins: agents on one machine start
+// together at boot, and the key file is claimed exclusively so exactly one
+// of them mints. A loser whose caCert read races the winner's second write
+// runs self-signed for that one boot and heals on the next.
+function mintCaOnce(dir, log) {
+  if (readPem(dir, FILES.caKey)) return;
+  const hostname = (process.env.HOSTNAME || 'this machine').toString().slice(0, 32);
+  const ca = makeCert({ subjectCN: `FediPod Local CA (${hostname})`, isCA: true, days: CA_DAYS });
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    fs.writeFileSync(p(dir, FILES.caKey), ca.keyPem, { mode: 0o600, flag: 'wx' });
+  } catch (e) {
+    if (e.code === 'EEXIST') return;   // another agent minted first
+    throw e;
+  }
+  fs.writeFileSync(p(dir, FILES.caCert), ca.certPem, { mode: 0o600 });
+  log('minted the local CA (name-constrained to localhost)');
+}
+
+// Put the CA where this user's browsers look, where that needs no privilege
+// (NSS on Linux — Chromium reads it). Once per CA: a marker beside the certs
+// remembers the install, and a rotated CA installs again. AP_TRUST_INSTALL=0
+// disables the whole step (the test suite sets it, so throwaway agents never
+// touch a real profile's trust store).
+export function installBrowserTrust(dir, { log = () => {} } = {}) {
+  if (process.env.AP_TRUST_INSTALL === '0') return false;
+  const caCert = readPem(dir, FILES.caCert);
+  if (!caCert) return false;
+  const digest = crypto.createHash('sha256').update(caCert).digest('hex');
+  const markerFile = p(dir, 'trust-installed.json');
+  try {
+    if (JSON.parse(fs.readFileSync(markerFile, 'utf8')).sha256 === digest) return true;
+  } catch { /* not installed yet */ }
+  if (process.platform !== 'linux') return false;   // elevated stores; `https --trust` prints the step
+  try {
+    execFileSync('certutil', ['-d', `sql:${path.join(os.homedir(), '.pki/nssdb')}`, '-A',
+      '-t', 'C,,', '-n', 'FediPod Local CA', '-i', p(dir, FILES.caCert)], { stdio: 'pipe' });
+  } catch {
+    log('browser trust store not updated (certutil unavailable) — `fedipod https --trust` prints the manual step');
+    return false;
+  }
+  fs.writeFileSync(markerFile, JSON.stringify({ sha256: digest, at: new Date().toISOString() }) + '\n',
+    { mode: 0o600 });
+  log('installed the local CA in your browser trust store (NSS)');
+  return true;
+}
+
+// What an agent calls at boot: trusted https with nothing asked of the user.
+// The CA is minted on first use, the leaf rides it from then on, and the CA
+// lands in the browser trust store when that can be done quietly.
+export function ensureTrustedTls(dir, { log = () => {}, names = [] } = {}) {
+  try { mintCaOnce(dir, log); } catch { /* self-signed this boot */ }
+  const tls = ensureLocalTls(dir, { log, names });
+  if (tls.trust) installBrowserTrust(dir, { log });
+  return tls;
+}
+
+// The manual path: mint the CA (once) and re-mint the server certificate
+// under it, for the printed system-store step. The CA's key never leaves the
+// certs directory; the CA's CERT is what a trust store accepts.
+export function enableTrust(dir, { log = () => {} } = {}) {
+  mintCaOnce(dir, log);
+  // Force a re-mint of the leaf under the CA.
+  fs.rmSync(p(dir, FILES.cert), { force: true });
+  fs.rmSync(p(dir, FILES.key), { force: true });
+  const tls = ensureLocalTls(dir, { log });
+  installBrowserTrust(dir, { log });
+  return { ...tls, caCertPath: p(dir, FILES.caCert) };
+}
+
+export const certPaths = (dir) => ({
+  key: p(dir, FILES.key), cert: p(dir, FILES.cert),
+  caKey: p(dir, FILES.caKey), caCert: p(dir, FILES.caCert),
+});