pinnace 0.0.0 → 0.2.0

package/dist/deploy/deploy.js

@@ -0,0 +1,150 @@
+/**
+ * Host-agnostic **deploy** — build one CAR and land the SAME CID on every node.
+ *
+ * This is the core operation user stories 4, 6, 7 describe: build a site's
+ * **CAR** ONCE (via the `car-build` seam), then fan out across every configured
+ * **node** (each with its OWN bearer token) so all nodes serve the IDENTICAL
+ * **CID** with no single point of failure. Per node the flow is: import + pin
+ * the CAR (`dag/import?pin-roots=true`), then place it in MFS at `/sites/<id>`
+ * (mkdir parents / rm old / cp `/ipfs/<cid>`) so `gateway warming`, IPNS
+ * republish, and `status` auto-discover it. Deploy speaks ONLY the Kubo RPC seam
+ * ({@link KuboRpcClient}); it is not host-specific.
+ *
+ * Behaviour ported (not copied) from the reference prototype
+ * `~/searches/ipfs-hetzner/deploy-car.mjs`: the multi-target fan-out, the MFS
+ * placement, the per-`mode` branch, and the `Promise.allSettled` partial-failure
+ * semantics (a non-empty subset of nodes succeeding is still an overall success:
+ * "the site is up on the rest").
+ *
+ * PER-SITE `mode` BRANCH (CONTEXT.md `mode`; spec's "Per-site mode branch"):
+ *  - `ipfs` mode: land + pin + MFS ONLY (no key, no publish). ENS uses
+ *    `ipfs://<cid>`, updated per deploy.
+ *  - `ipns` mode: everything above PLUS the publish path (`key/list` then
+ *    `name/publish`) and ONLY on a PUBLISHER target. A `replica` (or a target
+ *    with {@link DeployTarget.publish} disabled) NEVER signs — it re-announces
+ *    the publisher's record via the on-box `mirror` verb instead. This mirrors
+ *    the prototype's `doPublish = mode === "ipns" && PUBLISH_IPNS` gate, with
+ *    role standing in for the prototype's `PUBLISH_IPNS=0` replica flag.
+ *
+ * SEAM BOUNDARY (see the sibling tasks): this module wires the per-mode call
+ * SEQUENCE only. The full publisher/replica record export+mirror lives in
+ * `publisher-replica-model`, and importing the derived key into the publisher's
+ * keystore lives in `key-import-publisher`. So deploy here does NOT `key/gen`
+ * or `key/import` — it assumes the publisher already holds the key (looked up
+ * via `key/list`) and issues `name/publish`. If a publisher has no matching key
+ * yet, the publish is reported as skipped rather than silently generating one
+ * (key provisioning is that other task's job, not deploy's).
+ */
+import { KuboRpcClient } from '../rpc/kubo-rpc-client.js';
+import { buildCar } from '../car/car-build.js';
+import { placeInMfs } from '../site/site-management.js';
+/** The MFS directory sites live under (matches site-management). */
+const DEFAULT_SITES_DIR = '/sites';
+/** Reference record values (ported from the prototype / on-box republish). */
+const RECORD_LIFETIME = '72h';
+const RECORD_TTL = '1h';
+/**
+ * Deploy a site: build the CAR ONCE, then import the SAME CAR into every target
+ * (each with its own token), pin it, place it in MFS, and (in `ipns` mode, on
+ * publisher targets) publish the IPNS record. Fans out with
+ * `Promise.allSettled`: a node that fails is reported in {@link DeployResult.failed}
+ * and does not sink the others; a non-empty success subset is still an overall
+ * success ({@link DeployResult.success}). Throws only if NO node succeeds is
+ * NOT the contract here — deploy always RESOLVES with the per-node breakdown;
+ * callers inspect `success`.
+ *
+ * @throws if neither `sourceDir` nor `car` is supplied, or both are.
+ */
+export async function deploy(input) {
+    const { sourceDir, car, id, mode, targets } = input;
+    if ((sourceDir === undefined) === (car === undefined)) {
+        throw new Error('deploy requires exactly one of `sourceDir` or `car`');
+    }
+    const sitesDir = input.sitesDir ?? DEFAULT_SITES_DIR;
+    // Build the CAR ONCE — the same bytes (and thus the same CID) land on every
+    // node (redundancy, no single point of failure).
+    const built = car ?? (await buildCar(sourceDir));
+    // Fan out. allSettled so one node's failure never sinks the others.
+    const settled = await Promise.allSettled(targets.map((target) => deployToNode(target, built, id, mode, sitesDir)));
+    const ok = [];
+    const failed = [];
+    settled.forEach((outcome, i) => {
+        const baseUrl = targets[i].baseUrl;
+        if (outcome.status === 'fulfilled') {
+            ok.push(outcome.value);
+        }
+        else {
+            failed.push({ baseUrl, error: asError(outcome.reason) });
+        }
+    });
+    return {
+        cid: built.rootCid,
+        mode,
+        ok,
+        failed,
+        success: ok.length > 0,
+    };
+}
+/**
+ * Deploy the (already-built) CAR to ONE node: import + pin, place in MFS, then
+ * (in ipns mode on a publishing publisher) key/list + name/publish. Rejects on
+ * any RPC failure so the caller's allSettled records it as a per-node failure.
+ */
+async function deployToNode(target, built, id, mode, sitesDir) {
+    const client = new KuboRpcClient({
+        baseUrl: target.baseUrl,
+        token: target.token,
+        fetchImpl: target.fetchImpl,
+    });
+    // 1. Import + pin the CAR (same CID as every other node).
+    await client.dagImport(built.carBytes);
+    // 2. Place it in MFS /sites/<id> (mkdir parents / rm old / cp /ipfs/<cid>).
+    //    Reuses the single implementation of that sequence (site-management).
+    await placeInMfs(client, sitesDir, id, built.rootCid);
+    // 3. Mode branch: ipns mode ADDS publish, and ONLY on a publishing publisher.
+    if (mode === 'ipns' && shouldPublish(target)) {
+        const ipns = await publish(client, id, built.rootCid);
+        return { baseUrl: target.baseUrl, cid: built.rootCid, ipns, published: true };
+    }
+    return { baseUrl: target.baseUrl, cid: built.rootCid, published: false };
+}
+/**
+ * Whether this target signs the IPNS record: a `publisher` whose publish switch
+ * is not explicitly disabled. A `replica` NEVER publishes (it re-announces the
+ * publisher's signed record via the on-box `mirror` verb instead).
+ */
+function shouldPublish(target) {
+    return target.role === 'publisher' && target.publish !== false;
+}
+/**
+ * The publish path (ipns mode, publisher only): `key/list` to resolve the site
+ * key's IPNS id, then `name/publish` to sign+refresh the record for
+ * `/ipfs/<cid>`. The keystore key name is the site's single `id` (the same
+ * value key-import imports under — one identifier, so the lookup cannot miss by
+ * a name/keyId split). Does NOT `key/gen`/`key/import`: the key is provisioned
+ * by the sibling `key-import-publisher` task; here we assume it exists. If it
+ * does not yet, we skip the publish (returning undefined) rather than silently
+ * generating a key deploy has no business owning.
+ */
+async function publish(client, id, cid) {
+    const keys = await client.keyList();
+    const ipns = (keys.Keys ?? []).find((k) => k?.Name === id)?.Id;
+    if (!ipns) {
+        // The publisher has no key for this site yet (key-import-publisher owns
+        // provisioning it). Land the content but do not sign.
+        return undefined;
+    }
+    await client.namePublish({
+        cidPath: `/ipfs/${cid}`,
+        key: id,
+        lifetime: RECORD_LIFETIME,
+        ttl: RECORD_TTL,
+        allowOffline: true,
+    });
+    return ipns;
+}
+/** Coerce an unknown rejection reason into an Error. */
+function asError(reason) {
+    return reason instanceof Error ? reason : new Error(String(reason));
+}
+//# sourceMappingURL=deploy.js.map

package/dist/deploy/deploy.js.map

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

package/dist/derive/ipns-key-derivation.d.ts

@@ -0,0 +1,37 @@
+/** The frozen `info`-string prefix. The version (`v1`) is encoded HERE. */
+export declare const IPNS_INFO_PREFIX = "pinnace:ipns:v1:";
+/** The master secret: a UTF-8 string or raw bytes. Never read from a node/file. */
+export type Master = string | Uint8Array;
+/** Inputs to the derivation: the master secret and the frozen per-site keyId. */
+export interface DeriveIpnsInput {
+    /** The operator master secret (env-only in production; see config module). */
+    master: Master;
+    /**
+     * The site's frozen, internal key identity — the SOLE per-site KDF input.
+     * NOT the ENS name (which is mutable and never enters derivation).
+     */
+    keyId: string;
+}
+/** A fully derived per-site IPNS key. */
+export interface DerivedIpnsKey {
+    /** The 32-byte ed25519 private seed (the raw HKDF output). */
+    readonly seed: Uint8Array;
+    /** The 32-byte raw ed25519 public key. */
+    readonly publicKey: Uint8Array;
+    /** The IPNS name: a CIDv1 (libp2p-key, base36) `k51...` id. */
+    readonly ipnsId: string;
+}
+/**
+ * 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 declare function deriveIpnsKey(input: DeriveIpnsInput): DerivedIpnsKey;
+/**
+ * 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 declare function deriveIpnsId(input: DeriveIpnsInput): string;
+//# sourceMappingURL=ipns-key-derivation.d.ts.map

package/dist/derive/ipns-key-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipns-key-derivation.d.ts","sourceRoot":"","sources":["../../src/derive/ipns-key-derivation.ts"],"names":[],"mappings":"AAgCA,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD,mFAAmF;AACnF,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEzC,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC/B,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACd;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AA+FD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,cAAc,CAKpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAE3D"}

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