pinnace 0.0.0 → 0.1.0

package/dist/derive/ipns-key-derivation.js

@@ -0,0 +1,130 @@
+/**
+ * Master-key -> per-site IPNS key derivation. **THIS IS A FROZEN CONTRACT.**
+ *
+ * Every `ipns`-mode site's key is derived deterministically from one operator
+ * master secret, so names are recoverable from the master alone and
+ * provisioning is stateless (CONTEXT.md `master key`, `keyId`). The scheme,
+ * pinned FOREVER by docs/adr/0001-frozen-ipns-key-derivation.md:
+ *
+ *   seed = HKDF-SHA256(ikm = master, salt = "", info = "pinnace:ipns:v1:" + keyId, length = 32)
+ *   -> the 32 bytes ARE the ed25519 private seed
+ *   -> its public key IS the IPNS name, rendered as a CIDv1 `k51...` id.
+ *
+ * Frozen invariants (changing ANY of these moves every live name irreversibly):
+ *   - the KDF is HKDF-SHA256;
+ *   - the `info` prefix is exactly `pinnace:ipns:v1:` (the version `v1` lives in
+ *     the `info` string, NOT in a separate parameter — a v2 scheme would use a
+ *     new prefix and never re-derive existing names);
+ *   - `keyId` is the SOLE per-site input, appended verbatim (UTF-8) to the info
+ *     prefix. The ENS name is mutable and MUST NEVER enter derivation, so this
+ *     surface has no `ensName` parameter at all;
+ *   - the HKDF `salt` is the RFC 5869 default (empty / zero-length). The spec
+ *     pins only ikm/info/length; an empty salt is the standard "no salt" case
+ *     and is pinned here so the contract is total (see ADR-0001);
+ *   - the 32 HKDF output bytes are used directly as the ed25519 seed (RFC 8032
+ *     private key), NOT hashed or expanded again.
+ *
+ * Key IMPORT into a node keystore and the "no client signing" boundary are a
+ * SEPARATE concern (the `key-import-publisher` task): this module derives the
+ * key + id only, with no node, network, or deploy.
+ */
+import { createPrivateKey, createPublicKey, hkdfSync } from 'node:crypto';
+/** The frozen `info`-string prefix. The version (`v1`) is encoded HERE. */
+export const IPNS_INFO_PREFIX = 'pinnace:ipns:v1:';
+/** PKCS#8 DER prefix wrapping a raw 32-byte ed25519 seed (RFC 8410). */
+const ED25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+/** base36 lowercase alphabet (multibase `k`), per the multiformats spec. */
+const BASE36_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+function toBytes(master) {
+    return typeof master === 'string' ? new TextEncoder().encode(master) : master;
+}
+/**
+ * HKDF-SHA256(master, salt = "", info = IPNS_INFO_PREFIX + keyId, 32).
+ * Returns the 32-byte ed25519 seed. Frozen — see the module doc.
+ */
+function deriveSeed(master, keyId) {
+    const info = new TextEncoder().encode(IPNS_INFO_PREFIX + keyId);
+    const seed = hkdfSync('sha256', toBytes(master), new Uint8Array(0), // RFC 5869 default (empty) salt — pinned by ADR-0001.
+    info, 32);
+    return new Uint8Array(seed);
+}
+/** Derive the raw 32-byte ed25519 public key from a 32-byte private seed. */
+function ed25519PublicKeyFromSeed(seed) {
+    const pkcs8 = Buffer.concat([ED25519_PKCS8_PREFIX, Buffer.from(seed)]);
+    const priv = createPrivateKey({ key: pkcs8, format: 'der', type: 'pkcs8' });
+    const spki = createPublicKey(priv).export({ format: 'der', type: 'spki' });
+    // An ed25519 SPKI DER is a fixed 12-byte header + the 32 raw public bytes.
+    return new Uint8Array(spki.subarray(spki.length - 32));
+}
+/** Encode bytes as multibase-less base36 (lowercase), preserving leading zeros. */
+function base36Encode(bytes) {
+    const digits = [0];
+    for (const byte of bytes) {
+        let carry = byte;
+        for (let i = 0; i < digits.length; i++) {
+            const value = digits[i] * 256 + carry;
+            digits[i] = value % 36;
+            carry = (value / 36) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 36);
+            carry = (carry / 36) | 0;
+        }
+    }
+    let out = '';
+    for (let i = 0; i < bytes.length && bytes[i] === 0; i++)
+        out += '0';
+    for (let i = digits.length - 1; i >= 0; i--)
+        out += BASE36_ALPHABET[digits[i]];
+    return out;
+}
+/**
+ * Encode a raw 32-byte ed25519 public key as an IPNS name (`k51...`).
+ *
+ * The name is a CIDv1 with the libp2p-key multicodec, whose multihash inlines
+ * the libp2p PublicKey protobuf via the identity hash (the default for
+ * ed25519), rendered in case-insensitive base36 with the `k` multibase prefix:
+ *
+ *   0x01 (CIDv1) 0x72 (libp2p-key)
+ *   0x00 (identity mh) 0x24 (len 36)
+ *   0x08 0x01 (protobuf field1 Type = Ed25519) 0x12 0x20 (field2 Data, len 32)
+ *   <32 raw public key bytes>
+ *
+ * @see https://specs.ipfs.tech/ipns/ipns-record/
+ */
+function ipnsIdFromPublicKey(publicKey) {
+    const pbHeader = Uint8Array.from([0x08, 0x01, 0x12, 0x20]);
+    const protobuf = new Uint8Array(pbHeader.length + publicKey.length);
+    protobuf.set(pbHeader, 0);
+    protobuf.set(publicKey, pbHeader.length);
+    const multihash = new Uint8Array(2 + protobuf.length);
+    multihash[0] = 0x00; // identity multihash function
+    multihash[1] = protobuf.length; // digest length (36)
+    multihash.set(protobuf, 2);
+    const cid = new Uint8Array(2 + multihash.length);
+    cid[0] = 0x01; // CIDv1
+    cid[1] = 0x72; // libp2p-key multicodec
+    cid.set(multihash, 2);
+    return 'k' + base36Encode(cid); // multibase base36 (lowercase) prefix.
+}
+/**
+ * Derive the full per-site IPNS key (seed + public key + `k51...` id) from the
+ * master secret and the frozen `keyId`. Pure and deterministic — no node,
+ * network, or deploy. This is the FROZEN CONTRACT; see the module doc.
+ */
+export function deriveIpnsKey(input) {
+    const seed = deriveSeed(input.master, input.keyId);
+    const publicKey = ed25519PublicKeyFromSeed(seed);
+    const ipnsId = ipnsIdFromPublicKey(publicKey);
+    return { seed, publicKey, ipnsId };
+}
+/**
+ * Derive-and-print path (user story 22): return a site's `k51...` IPNS id from
+ * the master + keyId with NO deploy and NO network, so an operator can set the
+ * ENS contenthash to `ipns://<id>` before the first deploy. The id depends ONLY
+ * on (master, keyId) — never the ENS name.
+ */
+export function deriveIpnsId(input) {
+    return deriveIpnsKey(input).ipnsId;
+}
+//# sourceMappingURL=ipns-key-derivation.js.map

package/dist/derive/ipns-key-derivation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipns-key-derivation.js","sourceRoot":"","sources":["../../src/derive/ipns-key-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAC,gBAAgB,EAAE,eAAe,EAAE,QAAQ,EAAC,MAAM,aAAa,CAAC;AAExE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AA0BnD,wEAAwE;AACxE,MAAM,oBAAoB,GAAG,MAAM,CAAC,IAAI,CACvC,kCAAkC,EAClC,KAAK,CACL,CAAC;AAEF,4EAA4E;AAC5E,MAAM,eAAe,GAAG,sCAAsC,CAAC;AAE/D,SAAS,OAAO,CAAC,MAAc;IAC9B,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/E,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,MAAc,EAAE,KAAa;IAChD,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,gBAAgB,GAAG,KAAK,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,QAAQ,CACpB,QAAQ,EACR,OAAO,CAAC,MAAM,CAAC,EACf,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,sDAAsD;IACzE,IAAI,EACJ,EAAE,CACF,CAAC;IACF,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,6EAA6E;AAC7E,SAAS,wBAAwB,CAAC,IAAgB;IACjD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACvE,MAAM,IAAI,GAAG,gBAAgB,CAAC,EAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAC,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,EAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAC,CAAC,CAAC;IACzE,2EAA2E;IAC3E,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,mFAAmF;AACnF,SAAS,YAAY,CAAC,KAAiB;IACtC,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IACnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC;YACtC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,EAAE,CAAC;YACvB,KAAK,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,KAAK,GAAG,CAAC,EAAE,CAAC;YAClB,MAAM,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;YACxB,KAAK,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACF,CAAC;IACD,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE;QAAE,GAAG,IAAI,GAAG,CAAC;IACpE,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;QAC1C,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,OAAO,GAAG,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,mBAAmB,CAAC,SAAqB;IACjD,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IACpE,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEzC,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtD,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,8BAA8B;IACnD,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,qBAAqB;IACrD,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAE3B,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IACjD,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,QAAQ;IACvB,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,wBAAwB;IACvC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAEtB,OAAO,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,uCAAuC;AACxE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAsB;IACnD,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC9C,OAAO,EAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAC,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAsB;IAClD,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AACpC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * pinnace library core — the public TypeScript API.
+ *
+ * All logic lives in the core (see CONTEXT.md `core vs cli`); the `pinnace`
+ * CLI bin (src/cli/bin.ts) is a thin wrapper that imports from here, so every
+ * operation is equally usable as a TypeScript API. Subsequent tracer-bullet
+ * tasks (Kubo RPC client, CAR build, key derivation, cloud-init, CI emitter,
+ * status, config, deploy, site management, CLI) hang off this entrypoint.
+ */
+/** The package name, exposed so the CLI and API can report a consistent identity. */
+export declare const PINNACE = "pinnace";
+/** Returns the pinnace package name (a trivial seam proving the toolchain is wired). */
+export declare function name(): string;
+export { KuboRpcClient, KuboRpcError, type KuboRpcClientOptions, type FetchLike, type FilesMkdirOptions, type FilesRmOptions, type NamePublishOptions, } from './rpc/kubo-rpc-client.js';
+export { MockKuboApi, type RecordedRequest, type MockResponseSpec, } from './rpc/mock-kubo.js';
+export { buildCar, writeCar, type BuiltCar } from './car/car-build.js';
+export { deriveIpnsKey, deriveIpnsId, IPNS_INFO_PREFIX, type Master, type DeriveIpnsInput, type DerivedIpnsKey, } from './derive/ipns-key-derivation.js';
+export { resolveConfig, resolveMasterSecret, resolveHostToken, hostTokenEnvVar, MissingHostTokenError, type PinnaceConfigFile, type ResolvedConfig, type HostConfig, type SiteConfig, type HostRole, type SiteMode, type EnvRecord, type CliOverrides, type ResolveConfigInput, type ResolveMasterInput, type ResolveHostTokenInput, } from './config/config-resolution.js';
+export { emitCi, githubCiProvider, CI_SYSTEMS, type CiSystem, type CIProvider, type EmitCiInput, type EmittedCi, type EmittedFile, type RequiredCiSetting, } from './ci/ci-emit.js';
+export { provision, hetznerHostProvider, HOST_PROVIDERS, type HostName, type HostProvider, type ProvisionInput, type ProvisionResult, } from './provision/cloud-init.js';
+export { serializeIpnsKeyForImport, importIpnsKeyIntoPublisher, KeyImportRoleError, LIBP2P_ED25519_PRIVATE_KEY_PREFIX, type ImportIpnsKeyInput, type KeyImportResult, } from './publisher/key-import.js';
+export { republishAndExport, mirrorAndReannounce, makeRepublishOp, makeMirrorOp, promoteReplicaToPublisher, RECORD_LIFETIME, RECORD_TTL, type PromoteReplicaInput, type PromoteReplicaResult, } from './publisher/record-sequence.js';
+export { runNodeCommand, discoverSites, NODE_VERBS, type NodeVerb, type NodeCommandContext, type NodeCommandOps, type NodeCommandResult, type NodeOpResult, type DiscoveredSite, type SiteOutcome, type PublisherFetch, type GatewayFetch, } from './node/node-commands.js';
+export { listSites, removeSite, addSite, placeInMfs, SITE_VERBS, type SiteVerb, type SiteListing, type ListSitesInput, type RemoveSiteInput, type RemoveSiteResult, type AddSiteInput, type AddSiteResult, } from './site/site-management.js';
+export { deploy, type DeployInput, type DeployTarget, type DeployResult, type DeployNodeOk, type DeployNodeFailure, } from './deploy/deploy.js';
+export { statusReport, makeStatusOp, defaultProvidersLookup, defaultGatewayProbe, type StatusReport, type SiteStatus, type StatusReportInput, type ProvidersLookup, type ProvidersResponse, type GatewayProbe, } from './status/status-report.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * pinnace library core — the public TypeScript API.
+ *
+ * All logic lives in the core (see CONTEXT.md `core vs cli`); the `pinnace`
+ * CLI bin (src/cli/bin.ts) is a thin wrapper that imports from here, so every
+ * operation is equally usable as a TypeScript API. Subsequent tracer-bullet
+ * tasks (Kubo RPC client, CAR build, key derivation, cloud-init, CI emitter,
+ * status, config, deploy, site management, CLI) hang off this entrypoint.
+ */
+/** The package name, exposed so the CLI and API can report a consistent identity. */
+export const PINNACE = 'pinnace';
+/** Returns the pinnace package name (a trivial seam proving the toolchain is wired). */
+export function name() {
+    return PINNACE;
+}
+export { KuboRpcClient, KuboRpcError, } from './rpc/kubo-rpc-client.js';
+export { MockKuboApi, } from './rpc/mock-kubo.js';
+export { buildCar, writeCar } from './car/car-build.js';
+export { deriveIpnsKey, deriveIpnsId, IPNS_INFO_PREFIX, } from './derive/ipns-key-derivation.js';
+export { resolveConfig, resolveMasterSecret, resolveHostToken, hostTokenEnvVar, MissingHostTokenError, } from './config/config-resolution.js';
+export { emitCi, githubCiProvider, CI_SYSTEMS, } from './ci/ci-emit.js';
+export { provision, hetznerHostProvider, HOST_PROVIDERS, } from './provision/cloud-init.js';
+export { serializeIpnsKeyForImport, importIpnsKeyIntoPublisher, KeyImportRoleError, LIBP2P_ED25519_PRIVATE_KEY_PREFIX, } from './publisher/key-import.js';
+export { republishAndExport, mirrorAndReannounce, makeRepublishOp, makeMirrorOp, promoteReplicaToPublisher, RECORD_LIFETIME, RECORD_TTL, } from './publisher/record-sequence.js';
+export { runNodeCommand, discoverSites, NODE_VERBS, } from './node/node-commands.js';
+export { listSites, removeSite, addSite, placeInMfs, SITE_VERBS, } from './site/site-management.js';
+export { deploy, } from './deploy/deploy.js';
+export { statusReport, makeStatusOp, defaultProvidersLookup, defaultGatewayProbe, } from './status/status-report.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,qFAAqF;AACrF,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AAEjC,wFAAwF;AACxF,MAAM,UAAU,IAAI;IACnB,OAAO,OAAO,CAAC;AAChB,CAAC;AAED,OAAO,EACN,aAAa,EACb,YAAY,GAMZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,WAAW,GAGX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,QAAQ,EAAE,QAAQ,EAAgB,MAAM,oBAAoB,CAAC;AACrE,OAAO,EACN,aAAa,EACb,YAAY,EACZ,gBAAgB,GAIhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACN,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,GAYrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACN,MAAM,EACN,gBAAgB,EAChB,UAAU,GAOV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACN,SAAS,EACT,mBAAmB,EACnB,cAAc,GAKd,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACN,yBAAyB,EACzB,0BAA0B,EAC1B,kBAAkB,EAClB,iCAAiC,GAGjC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,yBAAyB,EACzB,eAAe,EACf,UAAU,GAGV,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACN,cAAc,EACd,aAAa,EACb,UAAU,GAUV,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACN,SAAS,EACT,UAAU,EACV,OAAO,EACP,UAAU,EACV,UAAU,GAQV,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACN,MAAM,GAMN,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,YAAY,EACZ,YAAY,EACZ,sBAAsB,EACtB,mBAAmB,GAOnB,MAAM,2BAA2B,CAAC"}

package/dist/node/node-commands.d.ts

@@ -0,0 +1,115 @@
+import type { HostRole } from '../config/config-resolution.js';
+import type { KuboRpcClient } from '../rpc/kubo-rpc-client.js';
+/** The four on-box verbs, under the `node` namespace. */
+export type NodeVerb = 'republish' | 'mirror' | 'warm' | 'status';
+/** The verbs, in a stable order (for help text / iteration). */
+export declare const NODE_VERBS: readonly NodeVerb[];
+/** One site as auto-discovered from MFS `/sites/*`: its `id` and current CID. */
+export interface DiscoveredSite {
+    /** The MFS entry `id` under `/sites/` (the site's single identifier). */
+    id: string;
+    /** The current content root CID (`files/stat --hash`). */
+    cid: string;
+}
+/** Per-site outcome line a verb reports (shape is verb-specific but uniform). */
+export interface SiteOutcome {
+    /** The site's single `id` (its MFS entry / KDF input). */
+    id: string;
+    cid?: string;
+    ipns?: string;
+    /** A short machine-readable status token (e.g. `re-announced`, `no-record`). */
+    status?: string;
+    /**
+     * `status`-verb only: whether the network announces this node for the CID
+     * (the delegated-routing providers list contains our PeerID). Owned + filled
+     * by the `status-report` core op; absent for other verbs.
+     */
+    announced?: boolean;
+    /** `status`-verb only: whether a cold public gateway served the CID (2xx/206). */
+    gatewayServes?: boolean;
+    /** `status`-verb only: the raw HTTP status the cold-gateway probe returned. */
+    gatewayHttp?: number;
+}
+/** The uniform result an op returns: the per-site outcomes it produced. */
+export interface NodeOpResult {
+    sites: SiteOutcome[];
+}
+/** The full result {@link runNodeCommand} returns for one verb invocation. */
+export interface NodeCommandResult extends NodeOpResult {
+    /** The verb that ran. */
+    verb: NodeVerb;
+    /** True when role-gating (or a missing precondition) skipped the op. */
+    skipped?: boolean;
+    /** Why it was skipped (e.g. `role publisher required, this box is replica`). */
+    skippedReason?: string;
+}
+/**
+ * An injectable HTTP fetch for a single URL, returning the body text. Used for
+ * fetching the publisher's exported record on a replica. Tests inject a fake;
+ * production passes a `fetch`-backed implementation. Throwing signals the
+ * endpoint is unreachable (the replica then falls back to its cache).
+ */
+export type PublisherFetch = (url: string) => Promise<string>;
+/**
+ * An injectable HTTP fetch for gateway WARMING: fetch the URL (a small range is
+ * enough to seat the cache) and return the HTTP status. Tests inject a fake so
+ * no live gateway is hit.
+ */
+export type GatewayFetch = (url: string) => Promise<number>;
+/**
+ * The four core operations, injectable so the parallel `publisher-replica-model`
+ * (republish/mirror) and `status-report` (status) tasks can supply the owned,
+ * fully-tested implementations behind this SAME seam. Any op left unset uses
+ * this module's thin default (the direct Kubo wiring the reference describes).
+ */
+export interface NodeCommandOps {
+    republish: (ctx: NodeCommandContext, sites: DiscoveredSite[]) => Promise<NodeOpResult>;
+    mirror: (ctx: NodeCommandContext, sites: DiscoveredSite[]) => Promise<NodeOpResult>;
+    warm: (ctx: NodeCommandContext, sites: DiscoveredSite[]) => Promise<NodeOpResult>;
+    status: (ctx: NodeCommandContext, sites: DiscoveredSite[]) => Promise<NodeOpResult>;
+}
+/**
+ * Everything a verb needs to run on the box. On-box PATHS (records/cache/
+ * dashboard) are explicit fields so tests isolate them to temp fixtures and
+ * production points them at the real box locations (`/var/www/ipfs-dash/...`,
+ * `/var/lib/ipfs/records`) — no global default location is baked into the
+ * logic.
+ */
+export interface NodeCommandContext {
+    /** The LOCAL Kubo RPC client (this box's daemon). */
+    client: KuboRpcClient;
+    /** This box's role; gates `republish` (publisher) and `mirror` (replica). */
+    role: HostRole;
+    /** The MFS directory sites live under (default `/sites`). */
+    sitesDir?: string;
+    /** Gateway URL templates with a `{cid}` placeholder to warm through. */
+    gateways?: string[];
+    /** For replicas: base URL to fetch the publisher's exported records from. */
+    publisherEndpoint?: string;
+    /** Where the publisher EXPORTS signed records (replicas fetch these). */
+    recordsDir?: string;
+    /** Where a replica CACHES the last good record for fallback. */
+    cacheDir?: string;
+    /** Where `status` writes its dashboard JSON. */
+    dashboardDir?: string;
+    /** Injected publisher-record fetch (replica); defaults to a `fetch` call. */
+    publisherFetch?: PublisherFetch;
+    /** Injected gateway warm fetch; defaults to a `fetch` range request. */
+    gatewayFetch?: GatewayFetch;
+    /** Override any of the four core ops (parallel tasks supply the owned impl). */
+    ops?: Partial<NodeCommandOps>;
+}
+/**
+ * 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 declare function discoverSites(client: KuboRpcClient, sitesDir?: string): Promise<DiscoveredSite[]>;
+/**
+ * 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 declare function runNodeCommand(verb: NodeVerb, ctx: NodeCommandContext): Promise<NodeCommandResult>;
+//# sourceMappingURL=node-commands.d.ts.map

package/dist/node/node-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-commands.d.ts","sourceRoot":"","sources":["../../src/node/node-commands.ts"],"names":[],"mappings":"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"}

package/dist/node/node-commands.js

@@ -0,0 +1,227 @@
+/**
+ * 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`. Reuses the `status-report` core logic (injected via
+ * {@link NodeCommandContext.ops}.status; this default is a thin stand-in until
+ * that task lands) and writes the resulting report as `status.json` under the
+ * box's dashboard directory ONLY. Reporting per-site CID / IPNS id happens in
+ * the reused core; this wrapper just persists it where the dashboard reads.
+ */
+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":"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"}