pinnace 0.0.0 → 0.1.0

package/src/provision/cloud-init.ts

@@ -0,0 +1,551 @@
+/**
+ * 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 const HOST_PROVIDERS: readonly HostName[] = ['hetzner'];
+
+/**
+ * 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;
+}
+
+/** 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: readonly string[] = [
+	'https://{cid}.ipfs.dweb.link/',
+	'https://{cid}.ipfs.cf-ipfs.com/',
+	'https://ipfs.io/ipfs/{cid}',
+];
+
+/**
+ * One `pinnace node` verb scheduled on a systemd timer. The verb self-gates on
+ * `NODE_ROLE` (republish -> publisher, mirror -> replica) or is role-agnostic
+ * (warm/status), so scheduling ALL of them on EVERY box is safe: the
+ * wrong-role verb is a clean no-op (ADR-0002).
+ */
+interface TimerSpec {
+	/** The `pinnace node <verb>` this timer runs. */
+	verb: 'republish' | 'mirror' | 'warm' | 'status';
+	/** Human description for the unit files. */
+	description: string;
+	/** `OnBootSec` for the timer (staggered so timers don't all fire at once). */
+	onBootSec: string;
+	/** `OnUnitActiveSec`, the recurring cadence. */
+	onUnitActiveSec: string;
+}
+
+/**
+ * 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: readonly TimerSpec[] = [
+	{
+		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: TimerSpec): string {
+	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: ProvisionInput): string {
+	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: HostProvider = {
+	host: 'hetzner',
+	provision(input: ProvisionInput): ProvisionResult {
+		return {
+			host: 'hetzner',
+			cloudInit: {
+				path: 'cloud-init.yaml',
+				contents: renderHetznerCloudInit(input),
+			},
+		};
+	},
+};
+
+/** The provider registry (host -> provider). v1 has a single entry. */
+const PROVIDERS: Record<HostName, HostProvider> = {
+	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: ProvisionInput): ProvisionResult {
+	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);
+}

package/src/publisher/key-import.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 const LIBP2P_ED25519_PRIVATE_KEY_PREFIX = Uint8Array.from([
+	0x08, 0x01, 0x12, 0x40,
+]);
+
+/**
+ * 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 function serializeIpnsKeyForImport(derived: DerivedIpnsKey): Uint8Array {
+	if (derived.seed.length !== 32) {
+		throw new Error(
+			`expected a 32-byte ed25519 seed, got ${derived.seed.length}`,
+		);
+	}
+	if (derived.publicKey.length !== 32) {
+		throw new Error(
+			`expected a 32-byte ed25519 public key, got ${derived.publicKey.length}`,
+		);
+	}
+	const prefix = LIBP2P_ED25519_PRIVATE_KEY_PREFIX;
+	const out = new Uint8Array(prefix.length + 64);
+	out.set(prefix, 0);
+	out.set(derived.seed, prefix.length); // Data[0..32): the private seed.
+	out.set(derived.publicKey, prefix.length + 32); // Data[32..64): the pubkey.
+	return out;
+}
+
+/** A loud refusal to import a key onto a non-publisher node (a replica). */
+export class KeyImportRoleError extends Error {
+	constructor(
+		/** The role the caller passed (must be `publisher` to import). */
+		readonly role: HostRole,
+		/** The key name the import was attempted under. */
+		readonly keyName: string,
+	) {
+		super(
+			`refusing key/import '${keyName}' onto a ${role}: only the publisher ` +
+				`holds the IPNS key; replicas are keyless and re-announce the ` +
+				`publisher's signed record`,
+		);
+		this.name = 'KeyImportRoleError';
+	}
+}
+
+/** 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 async function importIpnsKeyIntoPublisher(
+	input: ImportIpnsKeyInput,
+): Promise<KeyImportResult> {
+	if (input.role !== 'publisher') {
+		throw new KeyImportRoleError(input.role, input.keyName);
+	}
+	const keyBytes = serializeIpnsKeyForImport(input.derived);
+	return await input.client.keyImport<KeyImportResult>(input.keyName, keyBytes);
+}