pinnace 0.0.0 → 0.2.0

package/dist/node/node-commands.js

@@ -0,0 +1,231 @@
+/**
+ * The **on-box** command surface of `pinnace` — the `node` namespace.
+ *
+ * The SAME `pinnace` binary the operator runs as a client also runs the
+ * recurring loop ON a Kubo node (invoked by the cloud-init systemd timers).
+ * This module is that loop's command surface: `pinnace node <verb>` with
+ * `verb` in {`republish`, `mirror`, `warm`, `status`}. Each verb is a THIN
+ * wrapper that discovers sites from the LOCAL Kubo RPC and dispatches to a
+ * core operation, exactly like the client CLI wraps core operations
+ * (CONTEXT.md `core vs cli`). One codebase, two invocation contexts, so the
+ * record/warm/mirror/status logic has a single implementation — no bash/TS
+ * behaviour drift like the reference prototype had.
+ *
+ * BOUNDARY (see docs/adr/0002-*): Kubo owns pinning (`dag/import --pin-roots`)
+ * and provider-record freshness (`Reprovider.Interval`); this recurring loop
+ * owns ONLY IPNS republish/export, replica mirror/fallback, gateway warm, and
+ * status. It does nothing recurring for pinning or reprovide.
+ *
+ * Behaviour ported (not copied as bash) from the reference cloud-init scripts
+ * `ipfs-ipns-publish.sh`, `ipfs-ipns-mirror.sh`, `ipfs-warm.sh`,
+ * `ipfs-status.sh` (`~/searches/ipfs-hetzner/cloud-init.yaml`).
+ *
+ * SEAM NOTE: the publisher/replica record SEQUENCE (export -> fetch ->
+ * routing/put -> fallback) is OWNED and tested by the `publisher-replica-model`
+ * task, and `status`'s per-site checks by the `status-report` task. Both land
+ * in parallel with this task. So the four core operations are injectable via
+ * {@link NodeCommandOps}: this module's default `republish`/`mirror` DELEGATE to
+ * the owned record-sequence core (`../publisher/record-sequence.ts`) so there is
+ * a SINGLE implementation (no bash/TS drift, per ADR-0002), and `status`
+ * delegates to the `status-report` core injected via `ctx.ops`. This task owns
+ * the command surface + role-gating + `warm` + the boundary ADR.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { republishAndExport, mirrorAndReannounce, } from '../publisher/record-sequence.js';
+/** The verbs, in a stable order (for help text / iteration). */
+export const NODE_VERBS = [
+    'republish',
+    'mirror',
+    'warm',
+    'status',
+];
+/** Which role each role-gated verb requires; role-agnostic verbs are absent. */
+const VERB_ROLE_GATE = {
+    republish: 'publisher',
+    mirror: 'replica',
+};
+/**
+ * Auto-discover sites from MFS `/sites/*`: list the directory, then stat each
+ * entry for its current CID. Entries without a resolvable CID are skipped.
+ * Shared by every verb (the reference scripts all begin with this same walk).
+ */
+export async function discoverSites(client, sitesDir = '/sites') {
+    let listing;
+    try {
+        listing = await client.filesLs(sitesDir);
+    }
+    catch {
+        // No /sites dir yet (fresh box) — nothing to do, not an error.
+        return [];
+    }
+    const entries = listing.Entries ?? [];
+    const sites = [];
+    for (const entry of entries) {
+        const id = entry?.Name;
+        if (!id)
+            continue;
+        try {
+            const stat = await client.filesStat(`${sitesDir}/${id}`);
+            if (stat?.Hash)
+                sites.push({ id, cid: stat.Hash });
+        }
+        catch {
+            // A site whose stat fails is skipped, not fatal for the others.
+        }
+    }
+    return sites;
+}
+/**
+ * Run one on-box verb. Resolves the role gate first (a wrong-role verb is a
+ * SKIP — a clean no-op that touches no Kubo RPC, so scheduling all timers on
+ * every box is safe), then discovers sites and dispatches to the (possibly
+ * injected) core op. Throws on an unknown verb (loud, never a silent no-op).
+ */
+export async function runNodeCommand(verb, ctx) {
+    if (!NODE_VERBS.includes(verb)) {
+        throw new Error(`unknown node verb '${verb}'; expected one of ${NODE_VERBS.join(', ')}`);
+    }
+    const requiredRole = VERB_ROLE_GATE[verb];
+    if (requiredRole && ctx.role !== requiredRole) {
+        return {
+            verb,
+            sites: [],
+            skipped: true,
+            skippedReason: `role ${requiredRole} required, this box is ${ctx.role}`,
+        };
+    }
+    const sites = await discoverSites(ctx.client, ctx.sitesDir ?? '/sites');
+    const op = ctx.ops?.[verb] ?? DEFAULT_OPS[verb];
+    const result = await op(ctx, sites);
+    // The dashboard PERSISTENCE is on-box wiring owned by this command layer, so
+    // it happens whether `status` used the default op or the injected
+    // `status-report` core op — the reused core produces the report, this
+    // wrapper writes it where the dashboard reads (and ONLY there).
+    if (verb === 'status') {
+        await writeStatusReport(ctx, result);
+    }
+    return { verb, ...result };
+}
+// ---------------------------------------------------------------------------
+// Default (thin) core-op implementations.
+//
+// The `warm` and `status` defaults are the direct Kubo wiring the reference
+// cloud-init scripts describe. The `republish`/`mirror` defaults DELEGATE to the
+// owned record-sequence core (`../publisher/record-sequence.ts`) so the record
+// SEQUENCE (export -> fetch -> routing/put -> fallback) has a SINGLE
+// implementation shared by client and box (ADR-0002); `status` reuses the
+// `status-report` core injected via `ctx.ops`.
+// ---------------------------------------------------------------------------
+/**
+ * Default `republish` (publisher): DELEGATE to the owned record-sequence core
+ * ({@link republishAndExport}). It refreshes the signed record (`name/publish`,
+ * ~72h/1h) and EXPORTS it (`routing/get`) to {@link NodeCommandContext.recordsDir}
+ * where replicas fetch it. One implementation, no bash/TS drift (ADR-0002).
+ */
+async function defaultRepublish(ctx, sites) {
+    return republishAndExport(ctx, sites);
+}
+/**
+ * Default `mirror` (replica): DELEGATE to the owned record-sequence core
+ * ({@link mirrorAndReannounce}). It fetches the publisher's exported record,
+ * re-announces it (`routing/put`), and FALLS BACK to the last cached record
+ * when the publisher endpoint is unreachable — NEVER signing.
+ */
+async function defaultMirror(ctx, sites) {
+    return mirrorAndReannounce(ctx, sites);
+}
+/**
+ * Default `warm`. Re-fetch each site's current CID through every configured
+ * gateway template (`{cid}` substituted); `.eth` names are ALSO warmed via
+ * eth.limo. Warming failures are recorded, never thrown (a cold gateway must
+ * not fail the whole run).
+ */
+async function defaultWarm(ctx, sites) {
+    const warm = ctx.gatewayFetch ?? httpFetchStatus;
+    const gateways = ctx.gateways ?? [];
+    const outcomes = [];
+    for (const site of sites) {
+        for (const template of gateways) {
+            const url = template.replaceAll('{cid}', site.cid);
+            await safeWarm(warm, url);
+        }
+        // eth.limo warming heuristic: an `id` ending `.eth` is ALSO warmed via
+        // eth.limo (keyed off the MFS entry `id`, the value that flows through
+        // here). Making this an explicit `ensName` hint is the sibling ENS-demotion
+        // idea's job, out of scope for this config-model change.
+        if (site.id.endsWith('.eth')) {
+            await safeWarm(warm, `https://${site.id}.limo/`);
+        }
+        outcomes.push({ id: site.id, cid: site.cid, status: 'warmed' });
+    }
+    return { sites: outcomes };
+}
+/**
+ * Default `status` — a thin stand-in used ONLY when no `status` op is injected.
+ * The PRODUCTION on-box path (`pinnace node status`, wired in cli/run.ts's
+ * `runNodeCli`) injects the OWNED `status` op ({@link makeStatusOp} from
+ * status-report) via {@link NodeCommandContext.ops}.status, which is the real
+ * per-site CID/IPNS/announce/gateway report. This default remains as the
+ * seam's safe fallback (e.g. a direct `runNodeCommand` call that does not want
+ * the live external checks / a hermetic test that injects its own op), so a
+ * bare call still reports current CID + IPNS id without reaching the network.
+ * The dashboard write is done by the command layer ({@link runNodeCommand}).
+ */
+async function defaultStatus(ctx, sites) {
+    // Thin stand-in report until `status-report` supplies the owned op: current
+    // CID from discovery + IPNS id from the keystore. The external announce /
+    // gateway-serves checks are that task's concern (injected here). The
+    // dashboard write is done by the command layer ({@link runNodeCommand}), not
+    // here, so an injected op gets persisted the same way.
+    const keys = await listKeys(ctx.client);
+    const outcomes = sites.map((s) => ({
+        id: s.id,
+        cid: s.cid,
+        ipns: keys.get(s.id) ?? '',
+    }));
+    return { sites: outcomes };
+}
+/** Serialise a status result to `status.json` under the dashboard dir only. */
+async function writeStatusReport(ctx, result) {
+    if (!ctx.dashboardDir)
+        return;
+    await mkdir(ctx.dashboardDir, { recursive: true });
+    const payload = { generated: new Date().toISOString(), sites: result.sites };
+    await writeFile(join(ctx.dashboardDir, 'status.json'), JSON.stringify(payload, null, 2));
+}
+/** The default op table (verb -> thin Kubo wiring). */
+const DEFAULT_OPS = {
+    republish: defaultRepublish,
+    mirror: defaultMirror,
+    warm: defaultWarm,
+    status: defaultStatus,
+};
+// ---------------------------------------------------------------------------
+// Small shared helpers.
+// ---------------------------------------------------------------------------
+/** Map site/key name -> IPNS id from `key/list -l`. */
+async function listKeys(client) {
+    const res = await client.keyList();
+    const map = new Map();
+    for (const k of res.Keys ?? []) {
+        if (k?.Name && k?.Id)
+            map.set(k.Name, k.Id);
+    }
+    return map;
+}
+/** Warm one URL, swallowing any error (a cold gateway must not fail the run). */
+async function safeWarm(warm, url) {
+    try {
+        await warm(url);
+    }
+    catch {
+        // Intentionally ignored: warming is best-effort.
+    }
+}
+/** Production gateway warm: range-request the URL and return the HTTP status. */
+async function httpFetchStatus(url) {
+    const res = await fetch(url, { headers: { range: 'bytes=0-0' } });
+    return res.status;
+}
+//# sourceMappingURL=node-commands.js.map

package/dist/node/node-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-commands.js","sourceRoot":"","sources":["../../src/node/node-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAC,KAAK,EAAE,SAAS,EAAC,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAG/B,OAAO,EACN,kBAAkB,EAClB,mBAAmB,GACnB,MAAM,iCAAiC,CAAC;AAKzC,gEAAgE;AAChE,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC9C,WAAW;IACX,QAAQ;IACR,MAAM;IACN,QAAQ;CACR,CAAC;AAEF,gFAAgF;AAChF,MAAM,cAAc,GAAwC;IAC3D,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,SAAS;CACjB,CAAC;AAqHF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,MAAqB,EACrB,QAAQ,GAAG,QAAQ;IAEnB,IAAI,OAAkD,CAAC;IACvD,IAAI,CAAC;QACJ,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,CAC7B,QAAQ,CACR,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACR,+DAA+D;QAC/D,OAAO,EAAE,CAAC;IACX,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,KAAK,EAAE,IAAI,CAAC;QACvB,IAAI,CAAC,EAAE;YAAE,SAAS;QAClB,IAAI,CAAC;YACJ,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,SAAS,CAAkB,GAAG,QAAQ,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1E,IAAI,IAAI,EAAE,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,EAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,EAAC,CAAC,CAAC;QAClD,CAAC;QAAC,MAAM,CAAC;YACR,gEAAgE;QACjE,CAAC;IACF,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,IAAc,EACd,GAAuB;IAEvB,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACd,sBAAsB,IAAI,sBAAsB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvE,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC/C,OAAO;YACN,IAAI;YACJ,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,IAAI;YACb,aAAa,EAAE,QAAQ,YAAY,0BAA0B,GAAG,CAAC,IAAI,EAAE;SACvE,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,IAAI,QAAQ,CAAC,CAAC;IACxE,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAEpC,6EAA6E;IAC7E,kEAAkE;IAClE,sEAAsE;IACtE,gEAAgE;IAChE,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvB,MAAM,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,OAAO,EAAC,IAAI,EAAE,GAAG,MAAM,EAAC,CAAC;AAC1B,CAAC;AAED,8EAA8E;AAC9E,0CAA0C;AAC1C,EAAE;AACF,4EAA4E;AAC5E,iFAAiF;AACjF,+EAA+E;AAC/E,qEAAqE;AACrE,0EAA0E;AAC1E,+CAA+C;AAC/C,8EAA8E;AAE9E;;;;;GAKG;AACH,KAAK,UAAU,gBAAgB,CAC9B,GAAuB,EACvB,KAAuB;IAEvB,OAAO,kBAAkB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,aAAa,CAC3B,GAAuB,EACvB,KAAuB;IAEvB,OAAO,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,WAAW,CACzB,GAAuB,EACvB,KAAuB;IAEvB,MAAM,IAAI,GAAG,GAAG,CAAC,YAAY,IAAI,eAAe,CAAC;IACjD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAkB,EAAE,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,QAAQ,IAAI,QAAQ,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YACnD,MAAM,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC3B,CAAC;QACD,uEAAuE;QACvE,uEAAuE;QACvE,4EAA4E;QAC5E,yDAAyD;QACzD,IAAI,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,MAAM,QAAQ,CAAC,IAAI,EAAE,WAAW,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;QAClD,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,EAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAC,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,EAAC,KAAK,EAAE,QAAQ,EAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;GAUG;AACH,KAAK,UAAU,aAAa,CAC3B,GAAuB,EACvB,KAAuB;IAEvB,4EAA4E;IAC5E,0EAA0E;IAC1E,qEAAqE;IACrE,6EAA6E;IAC7E,uDAAuD;IACvD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAkB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjD,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE;KAC1B,CAAC,CAAC,CAAC;IACJ,OAAO,EAAC,KAAK,EAAE,QAAQ,EAAC,CAAC;AAC1B,CAAC;AAED,+EAA+E;AAC/E,KAAK,UAAU,iBAAiB,CAC/B,GAAuB,EACvB,MAAoB;IAEpB,IAAI,CAAC,GAAG,CAAC,YAAY;QAAE,OAAO;IAC9B,MAAM,KAAK,CAAC,GAAG,CAAC,YAAY,EAAE,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,EAAC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAC,CAAC;IAC3E,MAAM,SAAS,CACd,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,aAAa,CAAC,EACrC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAChC,CAAC;AACH,CAAC;AAED,uDAAuD;AACvD,MAAM,WAAW,GAAmB;IACnC,SAAS,EAAE,gBAAgB;IAC3B,MAAM,EAAE,aAAa;IACrB,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,aAAa;CACrB,CAAC;AAEF,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,uDAAuD;AACvD,KAAK,UAAU,QAAQ,CAAC,MAAqB;IAC5C,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,OAAO,EAE5B,CAAC;IACL,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;QAChC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,EAAE;YAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,iFAAiF;AACjF,KAAK,UAAU,QAAQ,CAAC,IAAkB,EAAE,GAAW;IACtD,IAAI,CAAC;QACJ,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACR,iDAAiD;IAClD,CAAC;AACF,CAAC;AAED,iFAAiF;AACjF,KAAK,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAC,OAAO,EAAE,EAAC,KAAK,EAAE,WAAW,EAAC,EAAC,CAAC,CAAC;IAC9D,OAAO,GAAG,CAAC,MAAM,CAAC;AACnB,CAAC"}

package/dist/provision/cloud-init.d.ts

@@ -0,0 +1,162 @@
+/**
+ * The **cloud-init generator** behind the `HostProvider` seam (CONTEXT.md `host
+ * provider seam`). `provision` asks the core for a ready-to-paste cloud-init:
+ * the host-specific YAML that stands up a hardened Kubo node. Hetzner is the
+ * FIRST (and, in v1, only) implementation; other hosts are Out of Scope but
+ * slot in behind this same seam later (spec "Out of Scope"; user stories 1, 21).
+ *
+ * This module is PURE: {@link provision} takes a plain host/site/role config
+ * and returns the cloud-init file (path + contents) as data. It does NOT touch
+ * the filesystem, the network, or SSH. The CLI wrapper (`provision` command)
+ * is what hands the YAML to the operator. Keeping the emit pure lets it be
+ * snapshot-tested as a string with no fixtures (test-first policy) and reused
+ * as a TypeScript API (CONTEXT.md `core vs cli`).
+ *
+ * SEAM DISCIPLINE (user story 21): only host-specific provisioning lives behind
+ * `HostProvider`. Deploy/publish/status speak ONLY Kubo RPC and must not import
+ * this module. Adding a host later touches nothing but this file + the
+ * {@link HOST_PROVIDERS} registry. (The dependency direction is one-way: this
+ * module may reference the shared `HostRole` type, but nothing in deploy/
+ * publish/status references this module.)
+ *
+ * KEY CHANGE FROM THE REFERENCE (docs/adr/0002-on-box-agent-boundary.md): the
+ * emitted cloud-init does NOT bake the reference's four bash scripts
+ * (`ipfs-warm.sh`, `ipfs-ipns-publish.sh`, `ipfs-ipns-mirror.sh`,
+ * `ipfs-status.sh`). Instead it INSTALLS the `pinnace` binary on the box and
+ * schedules the on-box subcommands (`pinnace node republish|mirror|warm|
+ * status`) on role-gated systemd timers. One codebase runs both as the
+ * operator's client and as the box's periodic agent, so the record/warm/mirror/
+ * status logic has a single implementation (no bash/TS drift). Kubo still owns
+ * pinning (`dag/import --pin-roots`) + provider-record freshness
+ * (`Provide.Interval`); the pinnace timers own ONLY IPNS republish/export,
+ * replica mirror/fallback, gateway warm, and status. The reference bash is used
+ * here as the BEHAVIOURAL SPEC of what each timer must do, not as code to emit.
+ *
+ * INVARIANTS ENCODED (ported, not copied, from `~/searches/ipfs-hetzner/`):
+ *  - Kubo as a hardened systemd unit (dedicated `ipfs` user, sandboxing).
+ *  - ufw opens 4001 TCP+UDP (swarm, so gateways can dial) + 80/443 (Caddy/ACME);
+ *    the RPC API (5001) and gateway (8080) are bound to localhost and NEVER
+ *    opened in the firewall.
+ *  - discoverability: AcceleratedDHTClient + `Routing.Type auto` + reprovide
+ *    (interval well under the record-expiry window, strategy `all`).
+ *  - Caddy HTTPS reverse proxy for the RPC API (auto TLS), which forwards the
+ *    operator's bearer header straight through to the token-guarded Kubo API.
+ *
+ * INSTALL CHANNEL + BOOT-SAFETY (task `cloud-init-pinnace-install-channel`):
+ *  - The box installs a PINNED `pinnace` ({@link DEFAULT_PINNACE_VERSION}) on a
+ *    named current Node LTS ({@link DEFAULT_NODE_MAJOR}), both overridable per
+ *    box. Pinned (never floating `latest`) so a boot is reproducible.
+ *  - The install is BOOT-SAFE: `pinnace-setup.sh` is invoked with `|| true`, so
+ *    a transient npm/registry failure can NOT abort the boot. Kubo, the
+ *    firewall and Caddy come up regardless of the agent install.
+ *  - The dedicated `ipfs` service user is created by cloud-init's `users:`
+ *    module, which runs BEFORE `runcmd`, so no boot step can hit "invalid user
+ *    'ipfs'" (closes the first-boot race in
+ *    work/notes/observations/cloud-init-first-boot-ipfs-user-race-and-set-e-abort.md).
+ */
+import type { HostRole } from '../config/config-resolution.js';
+/** The hosts pinnace can provision for. v1 = Hetzner ONLY. */
+export type HostName = 'hetzner';
+/** The hosts, in a stable order (help text / iteration / validation). */
+export declare const HOST_PROVIDERS: readonly HostName[];
+/**
+ * The per-box inputs the generator injects into the cloud-init (the values
+ * `make-cloud-init.sh` used to `sed` in). Everything that varies per box lives
+ * here; the hardened invariants are baked into the template.
+ */
+export interface ProvisionInput {
+    /** Which host to provision for (v1: `hetzner`). */
+    host: HostName;
+    /** DNS A-record pointed at this box, used for the HTTPS RPC API vhost. */
+    apiDomain: string;
+    /** Optional read-only status dashboard vhost (also serves exported records). */
+    dashboardDomain?: string;
+    /** Email for Let's Encrypt (ACME) certificate issuance. */
+    acmeEmail: string;
+    /**
+     * The long random bearer token guarding the RPC API. Kubo enforces it via
+     * `API.Authorizations` even on localhost; Caddy forwards the header through.
+     */
+    bearerToken: string;
+    /**
+     * This box's role. `publisher` holds IPNS keys and signs/exports records;
+     * `replica` is keyless and mirrors the publisher's records. Written to the
+     * env file as `NODE_ROLE`, which the `pinnace node` timers self-gate on
+     * (republish only on publisher, mirror only on replica), so scheduling all
+     * timers on every box is safe.
+     */
+    role: HostRole;
+    /**
+     * REPLICA ONLY: base URL to fetch the publisher's exported signed records
+     * from (the publisher's dashboard vhost). Ignored for publishers.
+     */
+    publisherEndpoint?: string;
+    /**
+     * Browser origins allowed to call the RPC API (CORS). Space-separated in the
+     * env file. Defaults to the dashboard domain's URL when a dashboard is set.
+     */
+    corsOrigins?: string;
+    /**
+     * Public gateways to warm through, each a template containing `{cid}`.
+     * Defaults to a sensible dweb.link/ipfs.io set. `.eth` MFS names are ALSO
+     * warmed via eth.limo automatically by `pinnace node warm`.
+     */
+    gateways?: string[];
+    /** The Kubo version to install. Defaults to a pinned known-good release. */
+    kuboVersion?: string;
+    /**
+     * The `pinnace` version to install on the box (`npm install -g
+     * pinnace@<this>`). Defaults to {@link DEFAULT_PINNACE_VERSION} (the current
+     * published release). PINNED, never floating `latest`, so a box boot is
+     * reproducible. Overridable per-box (e.g. to roll a box onto a newer agent).
+     */
+    pinnaceVersion?: string;
+    /**
+     * The Node.js major version to install via NodeSource (`setup_<this>.x`).
+     * Defaults to {@link DEFAULT_NODE_MAJOR} (a current active LTS). A named knob
+     * so the LTS bump is one obvious edit, not a literal buried in a shell line.
+     */
+    nodeMajor?: string;
+    /** The MFS directory sites live under. Defaults to `/sites`. */
+    sitesDir?: string;
+}
+/** A single emitted file: where it goes + what it contains. */
+export interface EmittedFile {
+    /** The path to write the file at (relative; the operator pastes/uploads it). */
+    path: string;
+    /** The full file contents. */
+    contents: string;
+}
+/** What a host provider returns: the ready-to-paste cloud-init file. */
+export interface ProvisionResult {
+    /** Which host this was provisioned for (echoed for the caller). */
+    host: HostName;
+    /** The cloud-init file (path + contents). */
+    cloudInit: EmittedFile;
+}
+/**
+ * The `HostProvider` seam: one method that generates a host's provisioning
+ * artifact (cloud-init) for a given input. v1 has a single implementation
+ * ({@link hetznerHostProvider}); adding DigitalOcean / others later means
+ * adding another provider here and an entry in {@link HOST_PROVIDERS}; deploy/
+ * publish/status logic is untouched (spec user story 21).
+ */
+export interface HostProvider {
+    /** The host this provider provisions for. */
+    readonly host: HostName;
+    /** Generate the cloud-init (+ any host artifacts) for the given input. */
+    provision(input: ProvisionInput): ProvisionResult;
+}
+/**
+ * The Hetzner provider: the first implementation of {@link HostProvider}.
+ * Emits the hardened-node cloud-init to a conventional filename.
+ */
+export declare const hetznerHostProvider: HostProvider;
+/**
+ * Generate the provisioning cloud-init for the requested host: dispatches to
+ * the matching {@link HostProvider} and returns its cloud-init file. Throws
+ * LOUDLY on an unknown/unimplemented host (the seam exists so callers can add
+ * hosts later, but v1 only ships `hetzner`): never a silent no-op.
+ */
+export declare function provision(input: ProvisionInput): ProvisionResult;
+//# sourceMappingURL=cloud-init.d.ts.map

package/dist/provision/cloud-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-init.d.ts","sourceRoot":"","sources":["../../src/provision/cloud-init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,gCAAgC,CAAC;AAE7D,8DAA8D;AAC9D,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC,yEAAyE;AACzE,eAAO,MAAM,cAAc,EAAE,SAAS,QAAQ,EAAgB,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,mDAAmD;IACnD,IAAI,EAAE,QAAQ,CAAC;IACf,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,IAAI,EAAE,QAAQ,CAAC;IACf;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC3B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC/B,mEAAmE;IACnE,IAAI,EAAE,QAAQ,CAAC;IACf,6CAA6C;IAC7C,SAAS,EAAE,WAAW,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,0EAA0E;IAC1E,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAAC;CAClD;AAqcD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAWjC,CAAC;AAOF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAUhE"}