pinnace 0.0.0 → 0.1.0

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

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+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 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;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,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;AA+XD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAWjC,CAAC;AAOF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAUhE"}

package/dist/provision/cloud-init.js

@@ -0,0 +1,390 @@
+/** The hosts, in a stable order (help text / iteration / validation). */
+export const HOST_PROVIDERS = ['hetzner'];
+/** Defaults kept in one place so the template + docs never drift. */
+const DEFAULT_KUBO_VERSION = 'v0.38.1';
+const DEFAULT_SITES_DIR = '/sites';
+const DEFAULT_GATEWAYS = [
+    'https://{cid}.ipfs.dweb.link/',
+    'https://{cid}.ipfs.cf-ipfs.com/',
+    'https://ipfs.io/ipfs/{cid}',
+];
+/**
+ * The four timers, ported from the reference bash-unit cadences but pointed at
+ * `pinnace node <verb>` instead of the bash scripts (ADR-0002). Order is stable
+ * (deterministic output). Cadences mirror the reference: IPNS republish/mirror
+ * well under record expiry, warm/status more frequent.
+ */
+const TIMERS = [
+    {
+        verb: 'republish',
+        description: 'Republish + export IPNS records (publisher role)',
+        onBootSec: '8min',
+        onUnitActiveSec: '6h',
+    },
+    {
+        verb: 'mirror',
+        description: 'Mirror publisher IPNS records (replica role)',
+        onBootSec: '9min',
+        onUnitActiveSec: '3h',
+    },
+    {
+        verb: 'warm',
+        description: 'Warm public IPFS gateway caches for our CIDs',
+        onBootSec: '5min',
+        onUnitActiveSec: '30min',
+    },
+    {
+        verb: 'status',
+        description: 'Regenerate the per-site status JSON for the dashboard',
+        onBootSec: '6min',
+        onUnitActiveSec: '15min',
+    },
+];
+/** Render the `pinnace-<verb>` systemd service + timer unit pair. */
+function renderTimerUnits(t) {
+    return `  - path: /etc/systemd/system/pinnace-${t.verb}.service
+    permissions: "0644"
+    owner: root:root
+    content: |
+      [Unit]
+      Description=${t.description}
+      After=ipfs.service
+
+      [Service]
+      Type=oneshot
+      User=ipfs
+      Group=ipfs
+      EnvironmentFile=/etc/pinnace-node.env
+      Environment=IPFS_PATH=/var/lib/ipfs/.ipfs
+      ExecStart=/usr/local/bin/pinnace node ${t.verb}
+
+  - path: /etc/systemd/system/pinnace-${t.verb}.timer
+    permissions: "0644"
+    owner: root:root
+    content: |
+      [Unit]
+      Description=Schedule pinnace node ${t.verb}
+
+      [Timer]
+      OnBootSec=${t.onBootSec}
+      OnUnitActiveSec=${t.onUnitActiveSec}
+      Persistent=true
+
+      [Install]
+      WantedBy=timers.target
+`;
+}
+/**
+ * Render the full Hetzner cloud-init. Deterministic: same input -> byte-
+ * identical output (snapshot-locked). Encodes the hardened-node invariants
+ * (ufw 4001 TCP+UDP + 443, never 5001 raw; localhost-bound API/gateway;
+ * AcceleratedDHTClient + reprovide + `Routing.Type auto`; hardened systemd
+ * Kubo unit; Caddy HTTPS + bearer proxy) and schedules the `pinnace node`
+ * timers (NOT bash).
+ */
+function renderHetznerCloudInit(input) {
+    const dashboardDomain = input.dashboardDomain ?? '';
+    const corsOrigins = input.corsOrigins ?? (dashboardDomain ? `https://${dashboardDomain}` : '');
+    const publisherEndpoint = input.role === 'replica' ? (input.publisherEndpoint ?? '') : '';
+    const gateways = input.gateways ?? DEFAULT_GATEWAYS;
+    const kuboVersion = input.kuboVersion ?? DEFAULT_KUBO_VERSION;
+    const sitesDir = input.sitesDir ?? DEFAULT_SITES_DIR;
+    const warmGateways = gateways.join(' ');
+    const timerUnits = TIMERS.map(renderTimerUnits).join('\n');
+    const enableTimers = TIMERS.map((t) => `  - systemctl enable --now pinnace-${t.verb}.timer`).join('\n');
+    return `#cloud-config
+# =============================================================================
+# ${input.host} Cloud -> self-hosted IPFS (Kubo) node for a static website.
+#
+# Generated by \`pinnace provision --host ${input.host}\`. This is the programmatic
+# successor to the shell \`sed\`-template prototype (superseded).
+#
+# What this gives you:
+#   - Kubo running as a hardened systemd service (user: ipfs)
+#   - Swarm port 4001 (TCP+UDP) open so public gateways can dial you
+#   - RPC API (5001) bound to localhost, exposed ONLY via Caddy HTTPS + bearer
+#   - AcceleratedDHTClient + reprovide tuned so gateways can DISCOVER your node
+#   - The \`pinnace\` binary installed + its on-box subcommands
+#     (\`pinnace node republish|mirror|warm|status\`) scheduled on role-gated
+#     systemd timers. Kubo owns pinning + reprovide; pinnace owns IPNS
+#     republish/export, replica mirror/fallback, gateway warm, and status.
+#     (See docs/adr/0002-on-box-agent-boundary.md.)
+# =============================================================================
+
+package_update: true
+package_upgrade: true
+
+packages:
+  - curl
+  - ca-certificates
+  - ufw
+  - jq
+  - debian-keyring
+  - debian-archive-keyring
+  - apt-transport-https
+
+# ---------------------------------------------------------------------------
+# On-box environment consumed by the pinnace node timers + the setup scripts.
+# ---------------------------------------------------------------------------
+write_files:
+  - path: /etc/pinnace-node.env
+    permissions: "0600"
+    owner: root:root
+    content: |
+      API_DOMAIN="${input.apiDomain}"
+      DASH_DOMAIN="${dashboardDomain}"
+      API_CORS_ORIGINS="${corsOrigins}"
+      ACME_EMAIL="${input.acmeEmail}"
+      RPC_BEARER_TOKEN="${input.bearerToken}"
+
+      # Gateways to warm through. {cid} is replaced with each site's current CID
+      # by \`pinnace node warm\`, which AUTO-DISCOVERS sites from MFS (\${SITES_DIR}).
+      # Any MFS entry whose name ends in .eth is ALSO warmed via eth.limo.
+      WARM_GATEWAYS="${warmGateways}"
+
+      # MFS directory that holds your sites (one entry per site).
+      SITES_DIR="${sitesDir}"
+
+      # Role: "publisher" holds IPNS keys and signs/exports records; "replica"
+      # holds NO key and MIRRORS the publisher's signed records. The pinnace node
+      # timers self-gate on this, so scheduling all timers on every box is safe.
+      NODE_ROLE="${input.role}"
+
+      # REPLICA ONLY: where to fetch the publisher's exported signed records.
+      PUBLISHER_ENDPOINT="${publisherEndpoint}"
+
+      KUBO_VERSION="${kuboVersion}"
+
+  # -- Kubo installer / initializer -----------------------------------------
+  - path: /usr/local/sbin/ipfs-setup.sh
+    permissions: "0755"
+    owner: root:root
+    content: |
+      #!/usr/bin/env bash
+      set -euo pipefail
+      source /etc/pinnace-node.env
+
+      ARCH="$(dpkg --print-architecture)"   # amd64 / arm64
+      TARBALL="kubo_\${KUBO_VERSION}_linux-\${ARCH}.tar.gz"
+      URL="https://dist.ipfs.tech/kubo/\${KUBO_VERSION}/\${TARBALL}"
+
+      cd /tmp
+      curl -fsSL "$URL" -o "$TARBALL"
+      tar -xzf "$TARBALL"
+      bash kubo/install.sh
+      ipfs --version
+
+      if ! id ipfs >/dev/null 2>&1; then
+        useradd --system --create-home --home-dir /var/lib/ipfs --shell /usr/sbin/nologin ipfs
+      fi
+      install -d -o ipfs -g ipfs /var/lib/ipfs
+
+      export IPFS_PATH=/var/lib/ipfs/.ipfs
+      if [ ! -f "$IPFS_PATH/config" ]; then
+        # 'server' profile disables local-network announce (good for a datacenter box)
+        sudo -u ipfs env IPFS_PATH="$IPFS_PATH" ipfs init --profile server
+      fi
+
+      cfg() { sudo -u ipfs env IPFS_PATH="$IPFS_PATH" ipfs config "$@"; }
+
+      # --- Reachability: bind API + gateway to localhost only (NEVER public) ---
+      cfg Addresses.API   "/ip4/127.0.0.1/tcp/5001"
+      cfg Addresses.Gateway "/ip4/127.0.0.1/tcp/8080"
+
+      # --- Discoverability: keep provider records fresh so gateways find us ---
+      cfg --json Routing.AcceleratedDHTClient true
+      cfg Routing.Type "auto"
+      # Re-announce everything we serve; interval well under the record expiry.
+      # (Kubo 0.38 uses Provide.*; the pre-0.38 keys FATAL the daemon at boot.)
+      cfg Provide.Interval "12h"
+      cfg Provide.Strategy "all"
+
+      # --- Resource hygiene for a small box ---
+      cfg Datastore.StorageMax "40GB"
+      cfg --json Swarm.ConnMgr.HighWater 200
+      cfg --json Swarm.ConnMgr.LowWater  100
+
+      # --- RPC API auth: require a bearer token even on localhost ---
+      cfg --json API.Authorizations "{
+        \\"uploader\\": {
+          \\"AuthSecret\\": \\"bearer:\${RPC_BEARER_TOKEN}\\",
+          \\"AllowedPaths\\": [\\"/api/v0\\"]
+        }
+      }"
+
+      cfg --json API.HTTPHeaders.Access-Control-Allow-Origin  "[\\"*\\"]"
+      cfg --json API.HTTPHeaders.Access-Control-Allow-Methods "[\\"POST\\"]"
+      cfg --json API.HTTPHeaders.Access-Control-Allow-Headers "[\\"Authorization\\"]"
+
+      chown -R ipfs:ipfs /var/lib/ipfs
+
+  # -- systemd unit for the daemon (hardened) -------------------------------
+  - path: /etc/systemd/system/ipfs.service
+    permissions: "0644"
+    owner: root:root
+    content: |
+      [Unit]
+      Description=IPFS Kubo daemon
+      After=network-online.target
+      Wants=network-online.target
+
+      [Service]
+      User=ipfs
+      Group=ipfs
+      Environment=IPFS_PATH=/var/lib/ipfs/.ipfs
+      ExecStart=/usr/local/bin/ipfs daemon --migrate=true --enable-gc
+      Restart=on-failure
+      RestartSec=5
+      LimitNOFILE=65536
+      # hardening
+      NoNewPrivileges=true
+      ProtectSystem=strict
+      ProtectHome=true
+      ReadWritePaths=/var/lib/ipfs
+      PrivateTmp=true
+
+      [Install]
+      WantedBy=multi-user.target
+
+  # -- pinnace installer: the box runs the SAME binary as the client --------
+  - path: /usr/local/sbin/pinnace-setup.sh
+    permissions: "0755"
+    owner: root:root
+    content: |
+      #!/usr/bin/env bash
+      set -euo pipefail
+      # Install Node.js (for npm) then the pinnace binary globally. The on-box
+      # timers invoke \`pinnace node <verb>\`: one codebase, client + on-box.
+      if ! command -v npm >/dev/null 2>&1; then
+        curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+        apt-get install -y nodejs
+      fi
+      npm install -g pinnace
+      pinnace version
+
+  # -- Caddy reverse proxy for the HTTPS API (auto TLS) ---------------------
+  - path: /usr/local/sbin/write-caddyfile.sh
+    permissions: "0755"
+    owner: root:root
+    content: |
+      #!/usr/bin/env bash
+      set -euo pipefail
+      source /etc/pinnace-node.env
+      if [ -z "\${API_DOMAIN}" ]; then
+        echo "API_DOMAIN not set; skipping Caddy config (API stays localhost-only)."
+        exit 0
+      fi
+      cat > /etc/caddy/Caddyfile <<EOF
+      {
+        email \${ACME_EMAIL}
+      }
+
+      \${API_DOMAIN} {
+        @cors_preflight method OPTIONS
+        header {
+          Access-Control-Allow-Origin "\${API_CORS_ORIGINS}"
+          Access-Control-Allow-Methods "POST, OPTIONS"
+          Access-Control-Allow-Headers "Authorization, Content-Type"
+          Vary Origin
+        }
+        respond @cors_preflight 204
+
+        # Only the Kubo RPC API. Kubo enforces the bearer token via
+        # API.Authorizations; Caddy just forwards the header.
+        reverse_proxy 127.0.0.1:5001
+      }
+      EOF
+
+      if [ -n "\${DASH_DOMAIN}" ]; then
+      cat >> /etc/caddy/Caddyfile <<EOF
+
+      \${DASH_DOMAIN} {
+        root * /var/www/ipfs-dash
+        file_server
+      }
+      EOF
+      fi
+      systemctl restart caddy
+
+${timerUnits}
+# ---------------------------------------------------------------------------
+# Boot sequence
+# ---------------------------------------------------------------------------
+runcmd:
+  # Install Caddy (official repo)
+  - curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+  - curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
+  - apt-get update
+  - apt-get install -y caddy
+
+  # Firewall: SSH + IPFS swarm + HTTP/HTTPS (for the API). NOT 5001 raw, NOT 8080.
+  - ufw default deny incoming
+  - ufw default allow outgoing
+  - ufw allow 22/tcp
+  - ufw allow 4001/tcp
+  - ufw allow 4001/udp
+  - ufw allow 80/tcp
+  - ufw allow 443/tcp
+  - ufw --force enable
+
+  # Install + start Kubo
+  - /usr/local/sbin/ipfs-setup.sh
+  - systemctl daemon-reload
+  - systemctl enable --now ipfs.service
+
+  # Configure the HTTPS API proxy (no-op if API_DOMAIN unset)
+  - /usr/local/sbin/write-caddyfile.sh
+
+  # Install the pinnace binary (the box runs the same CLI as the client).
+  - /usr/local/sbin/pinnace-setup.sh
+
+  # Enable the pinnace node timers. republish self-gates to publisher, mirror to
+  # replica, so enabling all of them on every box is safe (ADR-0002).
+  - install -d -o ipfs -g ipfs /var/www/ipfs-dash
+${enableTimers}
+
+# =============================================================================
+# NOTES
+# -----
+# 1. DNS: point an A record (API_DOMAIN) at this box's IPv4 BEFORE first boot,
+#    or re-run /usr/local/sbin/write-caddyfile.sh after DNS propagates.
+# 2. Verify discoverability from OUTSIDE the box after ~15 min:
+#       https://delegated-ipfs.dev/routing/v1/providers/<CID>
+#    Your PeerID should appear in the providers list.
+# =============================================================================
+`;
+}
+/**
+ * The Hetzner provider: the first implementation of {@link HostProvider}.
+ * Emits the hardened-node cloud-init to a conventional filename.
+ */
+export const hetznerHostProvider = {
+    host: 'hetzner',
+    provision(input) {
+        return {
+            host: 'hetzner',
+            cloudInit: {
+                path: 'cloud-init.yaml',
+                contents: renderHetznerCloudInit(input),
+            },
+        };
+    },
+};
+/** The provider registry (host -> provider). v1 has a single entry. */
+const PROVIDERS = {
+    hetzner: hetznerHostProvider,
+};
+/**
+ * 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 function provision(input) {
+    const provider = PROVIDERS[input.host];
+    if (!provider) {
+        throw new Error(`unsupported host '${input.host}'; v1 provisions only ${HOST_PROVIDERS.join(', ')} (other hosts are Out of Scope but the HostProvider seam exists)`);
+    }
+    return provider.provision(input);
+}
+//# sourceMappingURL=cloud-init.js.map

package/dist/provision/cloud-init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-init.js","sourceRoot":"","sources":["../../src/provision/cloud-init.ts"],"names":[],"mappings":"AAiDA,yEAAyE;AACzE,MAAM,CAAC,MAAM,cAAc,GAAwB,CAAC,SAAS,CAAC,CAAC;AAiF/D,qEAAqE;AACrE,MAAM,oBAAoB,GAAG,SAAS,CAAC;AACvC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AACnC,MAAM,gBAAgB,GAAsB;IAC3C,+BAA+B;IAC/B,iCAAiC;IACjC,4BAA4B;CAC5B,CAAC;AAmBF;;;;;GAKG;AACH,MAAM,MAAM,GAAyB;IACpC;QACC,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,kDAAkD;QAC/D,SAAS,EAAE,MAAM;QACjB,eAAe,EAAE,IAAI;KACrB;IACD;QACC,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,8CAA8C;QAC3D,SAAS,EAAE,MAAM;QACjB,eAAe,EAAE,IAAI;KACrB;IACD;QACC,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,8CAA8C;QAC3D,SAAS,EAAE,MAAM;QACjB,eAAe,EAAE,OAAO;KACxB;IACD;QACC,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,uDAAuD;QACpE,SAAS,EAAE,MAAM;QACjB,eAAe,EAAE,OAAO;KACxB;CACD,CAAC;AAEF,qEAAqE;AACrE,SAAS,gBAAgB,CAAC,CAAY;IACrC,OAAO,yCAAyC,CAAC,CAAC,IAAI;;;;;oBAKnC,CAAC,CAAC,WAAW;;;;;;;;;8CASa,CAAC,CAAC,IAAI;;wCAEZ,CAAC,CAAC,IAAI;;;;;0CAKJ,CAAC,CAAC,IAAI;;;kBAG9B,CAAC,CAAC,SAAS;wBACL,CAAC,CAAC,eAAe;;;;;CAKxC,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,sBAAsB,CAAC,KAAqB;IACpD,MAAM,eAAe,GAAG,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC;IACpD,MAAM,WAAW,GAChB,KAAK,CAAC,WAAW,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5E,MAAM,iBAAiB,GACtB,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IACpD,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAC9D,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACrD,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAExC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAC9B,CAAC,CAAC,EAAE,EAAE,CAAC,sCAAsC,CAAC,CAAC,IAAI,QAAQ,CAC3D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,OAAO;;IAEJ,KAAK,CAAC,IAAI;;4CAE8B,KAAK,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAmClC,KAAK,CAAC,SAAS;qBACd,eAAe;0BACV,WAAW;oBACjB,KAAK,CAAC,SAAS;0BACT,KAAK,CAAC,WAAW;;;;;uBAKpB,YAAY;;;mBAGhB,QAAQ;;;;;mBAKR,KAAK,CAAC,IAAI;;;4BAGD,iBAAiB;;sBAEvB,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyJ/B,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCV,YAAY;;;;;;;;;;;CAWb,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAiB;IAChD,IAAI,EAAE,SAAS;IACf,SAAS,CAAC,KAAqB;QAC9B,OAAO;YACN,IAAI,EAAE,SAAS;YACf,SAAS,EAAE;gBACV,IAAI,EAAE,iBAAiB;gBACvB,QAAQ,EAAE,sBAAsB,CAAC,KAAK,CAAC;aACvC;SACD,CAAC;IACH,CAAC;CACD,CAAC;AAEF,uEAAuE;AACvE,MAAM,SAAS,GAAmC;IACjD,OAAO,EAAE,mBAAmB;CAC5B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAqB;IAC9C,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACd,qBAAqB,KAAK,CAAC,IAAI,yBAAyB,cAAc,CAAC,IAAI,CAC1E,IAAI,CACJ,kEAAkE,CACnE,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC"}

package/dist/publisher/key-import.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Import a derived per-site IPNS key into the **publisher** node's keystore.
+ *
+ * This module wires the frozen master-key -> per-site key derivation (see
+ * `../derive/ipns-key-derivation.ts`, {@link DerivedIpnsKey}) into a running
+ * publisher node: it serializes the ed25519 keypair into the libp2p-protobuf
+ * form Kubo's `ipfs key import` (`key/import`) expects, then POSTs those bytes
+ * to the publisher's keystore via the {@link KuboRpcClient} seam. The client
+ * only ever supplies key MATERIAL.
+ *
+ * THE LOAD-BEARING INVARIANT (docs/adr/0003-*): deriving a key client-side is
+ * NOT client-side record SIGNING. A future reader will look at client-side key
+ * derivation + import and reasonably wonder "isn't this the fully-keyless C-1
+ * client-signing model the spec excludes?" — it is NOT. This module hands the
+ * node key MATERIAL; the NODE then signs the IPNS record and owns sequence
+ * numbers / validity via `name/publish` (owned by the on-box `republish` verb,
+ * `../node/node-commands.ts`). No signing primitive runs here; the only RPC
+ * this module issues is `key/import`. Spec Out of Scope excludes the C-1
+ * fully-keyless client-signing model; ADR-0003 records that invariant durably.
+ *
+ * PUBLISHER-ONLY (CONTEXT.md `publisher`, `replica`): exactly one node per
+ * shared IPNS name holds the key; replicas are KEYLESS and only re-announce the
+ * publisher's signed record. So this module REFUSES to import onto a `replica`
+ * ({@link KeyImportRoleError}) rather than silently proceeding — a wrong-role
+ * import is a caller error, not a no-op, because it would put a signing key on a
+ * box that must never hold one. (Design note: this refusal is a new, loud ERROR
+ * gated on the existing `HostRole` concept; it does not invent a role. See the
+ * done record's Decisions block.)
+ *
+ * SCOPE: ONLY key import into the publisher. Deriving the key is the
+ * `ipns-key-derivation` task; the publish/refresh timers and the record
+ * export/mirror are the `publisher-replica-model` task. This module does
+ * neither — it lands the key and stops.
+ */
+import type { DerivedIpnsKey } from '../derive/ipns-key-derivation.js';
+import type { HostRole } from '../config/config-resolution.js';
+import type { KuboRpcClient } from '../rpc/kubo-rpc-client.js';
+/**
+ * The frozen libp2p-protobuf `PrivateKey` prefix for an ed25519 key with a
+ * 64-byte `Data`:
+ *
+ *   0x08 0x01  — field 1 (Type), varint, KeyType Ed25519 = 1
+ *   0x12 0x40  — field 2 (Data), length-delimited, length = 64
+ *
+ * followed by the 64-byte ed25519 raw key (32-byte seed || 32-byte public key,
+ * the Go `ed25519.PrivateKey` layout libp2p `Raw()` emits). This is the
+ * `libp2p-protobuf-cleartext` format `ipfs key import` defaults to.
+ *
+ * @see https://github.com/libp2p/go-libp2p/blob/master/core/crypto/pb/crypto.proto
+ * @see https://github.com/libp2p/go-libp2p/blob/master/core/crypto/ed25519.go
+ */
+export declare const LIBP2P_ED25519_PRIVATE_KEY_PREFIX: Uint8Array<ArrayBuffer>;
+/**
+ * Serialize a {@link DerivedIpnsKey} into the libp2p-protobuf-cleartext
+ * `PrivateKey` bytes `ipfs key import` expects.
+ *
+ * The libp2p ed25519 private key `Data` is the 64-byte concatenation of the
+ * 32-byte private seed and the 32-byte public key (so the public key need not
+ * be recomputed on load); we wrap it in the `PrivateKey { Type=Ed25519, Data }`
+ * protobuf via {@link LIBP2P_ED25519_PRIVATE_KEY_PREFIX}. Pure and offline: no
+ * node, network, or signing — this only reshapes bytes we already derived.
+ */
+export declare function serializeIpnsKeyForImport(derived: DerivedIpnsKey): Uint8Array;
+/** A loud refusal to import a key onto a non-publisher node (a replica). */
+export declare class KeyImportRoleError extends Error {
+    /** The role the caller passed (must be `publisher` to import). */
+    readonly role: HostRole;
+    /** The key name the import was attempted under. */
+    readonly keyName: string;
+    constructor(
+    /** The role the caller passed (must be `publisher` to import). */
+    role: HostRole, 
+    /** The key name the import was attempted under. */
+    keyName: string);
+}
+/** Inputs to {@link importIpnsKeyIntoPublisher}. */
+export interface ImportIpnsKeyInput {
+    /** The Kubo RPC client for the PUBLISHER node (per-node, bearer-guarded). */
+    client: KuboRpcClient;
+    /** The target node's role; MUST be `publisher` or the import is refused. */
+    role: HostRole;
+    /** The keystore key name to import under (the site name / `key/list` Name). */
+    keyName: string;
+    /** The derived per-site key (seed + public key) from `ipns-key-derivation`. */
+    derived: DerivedIpnsKey;
+}
+/**
+ * The Kubo `key/import` JSON response (`Name` + IPNS `Id`), as far as we read.
+ */
+export interface KeyImportResult {
+    Name?: string;
+    Id?: string;
+}
+/**
+ * Serialize the derived key and import it into the PUBLISHER node's keystore
+ * via Kubo `key/import`. REFUSES ({@link KeyImportRoleError}) on any non-
+ * publisher role, touching the node not at all, so a replica stays keyless.
+ *
+ * The client supplies key MATERIAL only. The node signs IPNS records itself via
+ * `name/publish` (a separate concern the on-box `republish` verb owns); nothing
+ * here signs, and the only RPC issued is `key/import`. See the module doc +
+ * ADR-0003 for the "no client-side record signing" invariant.
+ */
+export declare function importIpnsKeyIntoPublisher(input: ImportIpnsKeyInput): Promise<KeyImportResult>;
+//# sourceMappingURL=key-import.d.ts.map

package/dist/publisher/key-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-import.d.ts","sourceRoot":"","sources":["../../src/publisher/key-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,gCAAgC,CAAC;AAC7D,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iCAAiC,yBAE5C,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,CAiB7E;AAED,4EAA4E;AAC5E,qBAAa,kBAAmB,SAAQ,KAAK;IAE3C,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,QAAQ;IACvB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM;;IAHxB,kEAAkE;IACzD,IAAI,EAAE,QAAQ;IACvB,mDAAmD;IAC1C,OAAO,EAAE,MAAM;CASzB;AAED,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IAClC,6EAA6E;IAC7E,MAAM,EAAE,aAAa,CAAC;IACtB,4EAA4E;IAC5E,IAAI,EAAE,QAAQ,CAAC;IACf,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,OAAO,EAAE,cAAc,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC/C,KAAK,EAAE,kBAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAM1B"}