pinnace 0.0.0 → 0.2.0

package/dist/provision/cloud-init.js

@@ -0,0 +1,460 @@
+/** 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';
+/**
+ * The pinned `pinnace` version the box installs (`npm install -g
+ * pinnace@<this>`). Mirrors {@link DEFAULT_KUBO_VERSION}: a NAMED knob, not a
+ * literal, so a release bump is one obvious edit here. PINNED (never floating
+ * `latest`) so a box boot is reproducible: the same cloud-init always installs
+ * the same agent. Overridable per-box via {@link ProvisionInput.pinnaceVersion}.
+ * `pinnace@0.1.0` is the first published release (npm, public, OIDC provenance).
+ */
+const DEFAULT_PINNACE_VERSION = '0.2.0';
+/**
+ * The pinned Node.js major the box installs via NodeSource (`setup_<this>.x`).
+ * Node 22 is a current active LTS; Node 20 (the old literal) is the OLDEST LTS
+ * (EOL ~2026-04) and incoherent with the repo's own Node 24 toolchain. A NAMED
+ * knob (mirrors {@link DEFAULT_KUBO_VERSION}) so the LTS bump is one edit.
+ * Overridable per-box via {@link ProvisionInput.nodeMajor}.
+ */
+const DEFAULT_NODE_MAJOR = '22';
+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 pinnaceVersion = input.pinnaceVersion ?? DEFAULT_PINNACE_VERSION;
+    const nodeMajor = input.nodeMajor ?? DEFAULT_NODE_MAJOR;
+    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
+
+# ---------------------------------------------------------------------------
+# Service users. cloud-init's \`users:\` module runs BEFORE \`runcmd\`, so the
+# dedicated \`ipfs\` user is GUARANTEED to exist before any boot step uses it
+# (e.g. \`install -o ipfs ...\`). Creating it here (not mid-\`ipfs-setup.sh\`,
+# which is a \`set -e\` block that could abort before its \`useradd\`) closes the
+# first-boot race where a later step hit "invalid user 'ipfs'".
+# \`default\` keeps cloud-init's normal login user; we only ADD \`ipfs\`.
+# ---------------------------------------------------------------------------
+users:
+  - default
+  - name: ipfs
+    system: true
+    home: /var/lib/ipfs
+    shell: /usr/sbin/nologin
+    lock_passwd: true
+
+# ---------------------------------------------------------------------------
+# 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}"
+
+      # On-box PATHS the \`pinnace node\` verbs read (they assemble their
+      # NodeCommandContext from these keys):
+      #   DASHBOARD_DIR  - where \`node status\` writes status.json (the dashboard
+      #                    vhost \${DASH_DOMAIN} serves this dir).
+      #   RECORDS_DIR    - where \`node republish\` (publisher) EXPORTS the signed
+      #                    record; UNDER the dashboard dir so it is served at
+      #                    \${DASH_DOMAIN}/records/<id>.ipns-record, exactly where a
+      #                    replica's PUBLISHER_ENDPOINT + /records/ fetch looks.
+      #   CACHE_DIR      - where \`node mirror\` (replica) CACHES the last good
+      #                    record for the publisher-outage fallback (under the
+      #                    ipfs user's writable home).
+      DASHBOARD_DIR="/var/www/ipfs-dash"
+      RECORDS_DIR="/var/www/ipfs-dash/records"
+      CACHE_DIR="/var/lib/ipfs/records-cache"
+
+      # 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}"
+
+      # Node.js major installed via NodeSource (setup_<major>.x) and the PINNED
+      # pinnace version installed on the box. Both are reproducible: the same
+      # cloud-init always installs the same agent on the same runtime.
+      NODE_MAJOR="${nodeMajor}"
+      PINNACE_VERSION="${pinnaceVersion}"
+
+  # -- 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
+      source /etc/pinnace-node.env
+      # Install Node.js (for npm) then the PINNED pinnace binary globally. The
+      # on-box timers invoke \`pinnace node <verb>\`: one codebase, client +
+      # on-box. NODE_MAJOR / PINNACE_VERSION come from /etc/pinnace-node.env so
+      # the runtime + agent version are reproducible and one-edit overridable.
+      # This script is invoked NON-FATALLY at boot (\`|| true\`): a transient
+      # npm/registry hiccup must NOT abort provisioning (Kubo, the firewall and
+      # Caddy are already up by the time this runs). Re-run it manually to retry.
+      if ! command -v npm >/dev/null 2>&1; then
+        curl -fsSL "https://deb.nodesource.com/setup_\${NODE_MAJOR}.x" | bash -
+        apt-get install -y nodejs
+      fi
+      npm install -g "pinnace@\${PINNACE_VERSION}"
+      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
+
+  # Dashboard dir, owned by the ipfs service user (guaranteed to exist: created
+  # by the \`users:\` module above, BEFORE runcmd). Done BEFORE the pinnace
+  # install so a transient install failure can never skip it.
+  - install -d -o ipfs -g ipfs /var/www/ipfs-dash
+
+  # Install the pinned pinnace binary (the box runs the same CLI as the client).
+  # BOOT-SAFE: \`|| true\` so a transient npm/registry failure does NOT abort the
+  # boot (Kubo, the firewall and Caddy are already up). Re-run
+  # /usr/local/sbin/pinnace-setup.sh manually to retry; the timers below pick it
+  # up on their next tick once the binary is present.
+  - /usr/local/sbin/pinnace-setup.sh || true
+
+  # 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).
+${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":"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"}

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"}

package/dist/publisher/key-import.js

@@ -0,0 +1,76 @@
+/**
+ * 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) {
+    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 {
+    role;
+    keyName;
+    constructor(
+    /** The role the caller passed (must be `publisher` to import). */
+    role, 
+    /** The key name the import was attempted under. */
+    keyName) {
+        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.role = role;
+        this.keyName = keyName;
+        this.name = 'KeyImportRoleError';
+    }
+}
+/**
+ * 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) {
+    if (input.role !== 'publisher') {
+        throw new KeyImportRoleError(input.role, input.keyName);
+    }
+    const keyBytes = serializeIpnsKeyForImport(input.derived);
+    return await input.client.keyImport(input.keyName, keyBytes);
+}
+//# sourceMappingURL=key-import.js.map

package/dist/publisher/key-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-import.js","sourceRoot":"","sources":["../../src/publisher/key-import.ts"],"names":[],"mappings":"AAsCA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,UAAU,CAAC,IAAI,CAAC;IAChE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;CACtB,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAuB;IAChE,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACd,wCAAwC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAC7D,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACd,8CAA8C,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,CACxE,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,iCAAiC,CAAC;IACjD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC/C,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACnB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,iCAAiC;IACvE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,4BAA4B;IAC5E,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,4EAA4E;AAC5E,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAGlC;IAEA;IAJV;IACC,kEAAkE;IACzD,IAAc;IACvB,mDAAmD;IAC1C,OAAe;QAExB,KAAK,CACJ,wBAAwB,OAAO,YAAY,IAAI,uBAAuB;YACrE,+DAA+D;YAC/D,2BAA2B,CAC5B,CAAC;QARO,SAAI,GAAJ,IAAI,CAAU;QAEd,YAAO,GAAP,OAAO,CAAQ;QAOxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IAClC,CAAC;CACD;AAsBD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,KAAyB;IAEzB,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,MAAM,IAAI,kBAAkB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,QAAQ,GAAG,yBAAyB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC1D,OAAO,MAAM,KAAK,CAAC,MAAM,CAAC,SAAS,CAAkB,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC/E,CAAC"}