pinnace 0.0.0 → 0.2.0

package/dist/publisher/record-sequence.d.ts

@@ -0,0 +1,90 @@
+import type { KuboRpcClient } from '../rpc/kubo-rpc-client.js';
+import type { HostRole } from '../config/config-resolution.js';
+import type { DerivedIpnsKey } from '../derive/ipns-key-derivation.js';
+import type { DiscoveredSite, NodeCommandContext, NodeOpResult } from '../node/node-commands.js';
+/**
+ * Records are ~72h valid, refreshed with a ~1h ttl (the reference values). The
+ * republish timer fires well within 72h so the record never lapses. Exported so
+ * tests pin the exact validity contract and callers do not re-magic-number it.
+ */
+export declare const RECORD_LIFETIME = "72h";
+export declare const RECORD_TTL = "1h";
+/**
+ * PUBLISHER op. For each discovered site the node holds a key for:
+ *   1. `name/publish` to refresh the signed record (~72h lifetime, ~1h ttl),
+ *   2. `routing/get` to EXPORT the raw signed record, then
+ *   3. write the record + its ipns id under {@link NodeCommandContext.recordsDir}
+ *      where replicas fetch them.
+ * Sites the node holds NO key for are ipfs-mode only and are left alone
+ * (reported `no-key`, never published). This is the ONLY place a signing
+ * primitive (`name/publish`) runs in the whole sequence.
+ */
+export declare function republishAndExport(ctx: NodeCommandContext, sites: DiscoveredSite[]): Promise<NodeOpResult>;
+/**
+ * REPLICA op. For each discovered site:
+ *   1. FETCH the publisher's exported record (+ its ipns id) from the publisher
+ *      endpoint;
+ *   2. on ANY fetch failure, FALL BACK to the last cached record for that site;
+ *   3. re-announce whichever record it got via `routing/put`.
+ * A freshly fetched record is cached so a later publisher outage can fall back
+ * to it. A site with neither a live publisher NOR a cache is REPORTED
+ * (`no-record`), never thrown — one unreachable site must not fail the others.
+ *
+ * A replica NEVER signs: this op issues NO `name/publish`. It only re-announces
+ * a record the publisher already signed.
+ */
+export declare function mirrorAndReannounce(ctx: NodeCommandContext, sites: DiscoveredSite[]): Promise<NodeOpResult>;
+/**
+ * Adapt {@link republishAndExport} into a {@link NodeCommandContext} `republish`
+ * op so the on-box `republish` verb injects it (its `ops.republish` seam). The
+ * command layer discovers sites and passes them in; this op signs+exports over
+ * them. So the box runs THIS code, not a re-implementation.
+ */
+export declare function makeRepublishOp(): (ctx: NodeCommandContext, sites: DiscoveredSite[]) => Promise<NodeOpResult>;
+/**
+ * Adapt {@link mirrorAndReannounce} into a {@link NodeCommandContext} `mirror`
+ * op so the on-box `mirror` verb injects it (its `ops.mirror` seam). Same core,
+ * one implementation.
+ */
+export declare function makeMirrorOp(): (ctx: NodeCommandContext, sites: DiscoveredSite[]) => Promise<NodeOpResult>;
+/** Inputs to {@link promoteReplicaToPublisher}. */
+export interface PromoteReplicaInput {
+    /** The Kubo RPC client for the node being promoted (per-node, bearer-guarded). */
+    client: KuboRpcClient;
+    /** The node's CURRENT role (typically `replica`; `publisher` is a safe re-run). */
+    currentRole: 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 outcome of a promotion: the flipped role + the key that was imported. */
+export interface PromoteReplicaResult {
+    /** Always `publisher` after a successful promotion (the flipped role). */
+    role: HostRole;
+    /** The key name imported into the (now) publisher's keystore. */
+    keyName: string;
+    /** The IPNS id the imported key resolves to (from the `key/import` response). */
+    ipns?: string;
+}
+/**
+ * PROMOTE a keyless replica to publisher (spec user story 14): import the
+ * derived key into the node's keystore and flip its role to `publisher`, so the
+ * former replica can now sign/refresh the record itself — recovering the name
+ * without downtime of the CONTENT (the CID stays pinned throughout).
+ *
+ * This is a client-driven operation (run by the operator against the target
+ * node's RPC), NOT an on-box recurring verb: it reuses the `key-import-publisher`
+ * seam ({@link importIpnsKeyIntoPublisher}) to land the key material. Because
+ * that seam REFUSES a non-publisher role, we call it with role `publisher` (the
+ * target role) — promotion is precisely the act of making this node the
+ * publisher, so importing under the publisher role is correct.
+ *
+ * MUST happen WITHIN the current record's validity window: while the old
+ * publisher's ~72h record is still valid (kept alive by replica re-announcement
+ * during the grace window), the promoted node's first `name/publish` re-signs
+ * before the record lapses, so the name never goes dark. Promotion imports the
+ * key ONLY; it does not itself sign — the node signs on its next `republish`.
+ */
+export declare function promoteReplicaToPublisher(input: PromoteReplicaInput): Promise<PromoteReplicaResult>;
+//# sourceMappingURL=record-sequence.d.ts.map

package/dist/publisher/record-sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-sequence.d.ts","sourceRoot":"","sources":["../../src/publisher/record-sequence.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,gCAAgC,CAAC;AAC7D,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,kCAAkC,CAAC;AAErE,OAAO,KAAK,EACX,cAAc,EACd,kBAAkB,EAClB,YAAY,EAGZ,MAAM,0BAA0B,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAQ,CAAC;AACrC,eAAO,MAAM,UAAU,OAAO,CAAC;AAW/B;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACvC,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,cAAc,EAAE,GACrB,OAAO,CAAC,YAAY,CAAC,CAoCvB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACxC,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,cAAc,EAAE,GACrB,OAAO,CAAC,YAAY,CAAC,CA4DvB;AAOD;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,CAClC,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,cAAc,EAAE,KACnB,OAAO,CAAC,YAAY,CAAC,CAEzB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,CAC/B,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,cAAc,EAAE,KACnB,OAAO,CAAC,YAAY,CAAC,CAEzB;AAMD,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IACnC,kFAAkF;IAClF,MAAM,EAAE,aAAa,CAAC;IACtB,mFAAmF;IACnF,WAAW,EAAE,QAAQ,CAAC;IACtB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,OAAO,EAAE,cAAc,CAAC;CACxB;AAED,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,QAAQ,CAAC;IACf,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,yBAAyB,CAC9C,KAAK,EAAE,mBAAmB,GACxB,OAAO,CAAC,oBAAoB,CAAC,CAW/B"}

package/dist/publisher/record-sequence.js

@@ -0,0 +1,250 @@
+/**
+ * The **publisher / keyless-replica IPNS record SEQUENCE** — pinnace's C-2
+ * grace-window machinery (CONTEXT.md `publisher`, `replica`, `IPNS record`;
+ * spec "Publisher / keyless-replica model" + user stories 12, 13, 14).
+ *
+ * A shared IPNS name stays reachable with a grace window even if the publisher
+ * dies. Exactly ONE publisher per name holds the derived key and:
+ *   - refreshes the record's validity by re-SIGNING it (`name/publish`,
+ *     ~72h lifetime, ~1h ttl — refreshed well within validity), then
+ *   - EXPORTS the raw signed record (`routing/get`) plus its ipns id to a
+ *     records dir where keyless replicas fetch it.
+ * Keyless REPLICAS hold no key. For each site they:
+ *   - FETCH the publisher's exported record from the publisher endpoint,
+ *   - re-announce it (`routing/put`) — they NEVER sign,
+ *   - FALL BACK to their last cached record if the publisher is unreachable,
+ *     so the name keeps announcing through a publisher outage.
+ *
+ * THE LOAD-BEARING INVARIANT (spec Out of Scope C-1; ADR-0003): a replica NEVER
+ * signs. The only signing primitive in the whole sequence is the publisher's
+ * `name/publish` (the NODE signs, owning sequence numbers + validity). A replica
+ * issues ONLY `routing/put` (re-announce) — never `name/publish`. Re-announcing
+ * a signed record is not signing it. The tests assert no `name/publish` ever
+ * reaches a replica's Kubo, including on the cache-fallback path.
+ *
+ * ONE IMPLEMENTATION (ADR-0002): this module is the SINGLE home of the record
+ * sequence. The on-box `pinnace node republish|mirror` verbs
+ * (`../node/node-commands.ts`) do NOT re-implement it — they inject the ops
+ * this module exposes ({@link makeRepublishOp}, {@link makeMirrorOp}) through
+ * their `NodeCommandOps` seam, exactly as `status-report` supplies the `status`
+ * op via `makeStatusOp`. So the client and the box run the same code; there is
+ * no bash/TS behaviour drift like the reference prototype had.
+ *
+ * Behaviour ported (NOT copied as bash) from the reference cloud-init scripts
+ * `ipfs-ipns-publish.sh` (publisher: `name publish` + `routing get` export to
+ * the dashboard vhost) and `ipfs-ipns-mirror.sh` (replica: curl the publisher's
+ * `/records/<name>.ipns-record`, `routing put`, fall back to cache)
+ * (`~/searches/ipfs-hetzner/cloud-init.yaml`).
+ *
+ * Promotion (story 14) — {@link promoteReplicaToPublisher} — reuses the
+ * `key-import-publisher` seam ({@link importIpnsKeyIntoPublisher}) to import the
+ * derived key and flip the role, recovering the name within the record's
+ * validity window without content downtime.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { importIpnsKeyIntoPublisher } from './key-import.js';
+/**
+ * Records are ~72h valid, refreshed with a ~1h ttl (the reference values). The
+ * republish timer fires well within 72h so the record never lapses. Exported so
+ * tests pin the exact validity contract and callers do not re-magic-number it.
+ */
+export const RECORD_LIFETIME = '72h';
+export const RECORD_TTL = '1h';
+/** The exported record file suffix (raw signed record bytes). */
+const RECORD_SUFFIX = '.ipns-record';
+/** The exported ipns-id file suffix (the `k51...` name `routing/put` targets). */
+const NAME_SUFFIX = '.ipns-name';
+// ---------------------------------------------------------------------------
+// Publisher: refresh (sign) + export.
+// ---------------------------------------------------------------------------
+/**
+ * PUBLISHER op. For each discovered site the node holds a key for:
+ *   1. `name/publish` to refresh the signed record (~72h lifetime, ~1h ttl),
+ *   2. `routing/get` to EXPORT the raw signed record, then
+ *   3. write the record + its ipns id under {@link NodeCommandContext.recordsDir}
+ *      where replicas fetch them.
+ * Sites the node holds NO key for are ipfs-mode only and are left alone
+ * (reported `no-key`, never published). This is the ONLY place a signing
+ * primitive (`name/publish`) runs in the whole sequence.
+ */
+export async function republishAndExport(ctx, sites) {
+    const keys = await listKeys(ctx.client);
+    const outcomes = [];
+    for (const site of sites) {
+        const ipns = keys.get(site.id);
+        if (!ipns) {
+            // ipfs-mode site (no key): nothing to sign or export.
+            outcomes.push({ id: site.id, cid: site.cid, status: 'no-key' });
+            continue;
+        }
+        // The NODE signs here (refreshing validity). Not the client, not a replica.
+        await ctx.client.namePublish({
+            cidPath: `/ipfs/${site.cid}`,
+            key: site.id,
+            lifetime: RECORD_LIFETIME,
+            ttl: RECORD_TTL,
+            allowOffline: true,
+        });
+        // Export the raw signed record for replicas to mirror.
+        const record = await ctx.client.routingGet(`/ipns/${ipns}`);
+        if (ctx.recordsDir) {
+            await mkdir(ctx.recordsDir, { recursive: true });
+            await writeFile(join(ctx.recordsDir, site.id + NAME_SUFFIX), ipns);
+            await writeFile(join(ctx.recordsDir, site.id + RECORD_SUFFIX), Buffer.from(record));
+        }
+        outcomes.push({ id: site.id, cid: site.cid, ipns, status: 'exported' });
+    }
+    return { sites: outcomes };
+}
+// ---------------------------------------------------------------------------
+// Replica: fetch + re-announce, with cache fallback. NEVER signs.
+// ---------------------------------------------------------------------------
+/**
+ * REPLICA op. For each discovered site:
+ *   1. FETCH the publisher's exported record (+ its ipns id) from the publisher
+ *      endpoint;
+ *   2. on ANY fetch failure, FALL BACK to the last cached record for that site;
+ *   3. re-announce whichever record it got via `routing/put`.
+ * A freshly fetched record is cached so a later publisher outage can fall back
+ * to it. A site with neither a live publisher NOR a cache is REPORTED
+ * (`no-record`), never thrown — one unreachable site must not fail the others.
+ *
+ * A replica NEVER signs: this op issues NO `name/publish`. It only re-announces
+ * a record the publisher already signed.
+ */
+export async function mirrorAndReannounce(ctx, sites) {
+    const base = (ctx.publisherEndpoint ?? '').replace(/\/+$/, '');
+    const fetchRecord = ctx.publisherFetch ?? httpFetchText;
+    const outcomes = [];
+    for (const site of sites) {
+        let record;
+        let ipnsId;
+        let fromCache = false;
+        // Try the publisher first; on ANY failure fall back to the cache.
+        if (base) {
+            try {
+                record = await fetchRecord(`${base}/records/${site.id}${RECORD_SUFFIX}`);
+                ipnsId = (await fetchRecord(`${base}/records/${site.id}${NAME_SUFFIX}`)).trim();
+            }
+            catch {
+                record = undefined;
+                ipnsId = undefined;
+            }
+        }
+        if (record === undefined && ctx.cacheDir) {
+            const cached = await readCached(ctx.cacheDir, site.id);
+            if (cached) {
+                record = cached.record;
+                ipnsId = cached.ipnsId;
+                fromCache = true;
+            }
+        }
+        if (record === undefined || !ipnsId) {
+            // Neither a live publisher nor a cache: report, don't throw.
+            outcomes.push({ id: site.id, status: 'no-record' });
+            continue;
+        }
+        // Persist a freshly-fetched record so a later outage can fall back to it.
+        // (Cache-sourced records are already on disk.)
+        if (!fromCache && ctx.cacheDir) {
+            await mkdir(ctx.cacheDir, { recursive: true });
+            await writeFile(join(ctx.cacheDir, site.id + RECORD_SUFFIX), record);
+            await writeFile(join(ctx.cacheDir, site.id + NAME_SUFFIX), ipnsId);
+        }
+        // Re-announce ONLY. No signing — this is a replica.
+        await ctx.client.routingPut(`/ipns/${ipnsId}`, new Uint8Array(Buffer.from(record)));
+        outcomes.push({
+            id: site.id,
+            ipns: ipnsId,
+            status: fromCache ? 're-announced-cached' : 're-announced',
+        });
+    }
+    return { sites: outcomes };
+}
+// ---------------------------------------------------------------------------
+// Node-command adapters: supply the owned ops behind the SAME NodeCommandOps
+// seam the on-box `republish`/`mirror` verbs inject (mirrors makeStatusOp).
+// ---------------------------------------------------------------------------
+/**
+ * Adapt {@link republishAndExport} into a {@link NodeCommandContext} `republish`
+ * op so the on-box `republish` verb injects it (its `ops.republish` seam). The
+ * command layer discovers sites and passes them in; this op signs+exports over
+ * them. So the box runs THIS code, not a re-implementation.
+ */
+export function makeRepublishOp() {
+    return (ctx, sites) => republishAndExport(ctx, sites);
+}
+/**
+ * Adapt {@link mirrorAndReannounce} into a {@link NodeCommandContext} `mirror`
+ * op so the on-box `mirror` verb injects it (its `ops.mirror` seam). Same core,
+ * one implementation.
+ */
+export function makeMirrorOp() {
+    return (ctx, sites) => mirrorAndReannounce(ctx, sites);
+}
+/**
+ * PROMOTE a keyless replica to publisher (spec user story 14): import the
+ * derived key into the node's keystore and flip its role to `publisher`, so the
+ * former replica can now sign/refresh the record itself — recovering the name
+ * without downtime of the CONTENT (the CID stays pinned throughout).
+ *
+ * This is a client-driven operation (run by the operator against the target
+ * node's RPC), NOT an on-box recurring verb: it reuses the `key-import-publisher`
+ * seam ({@link importIpnsKeyIntoPublisher}) to land the key material. Because
+ * that seam REFUSES a non-publisher role, we call it with role `publisher` (the
+ * target role) — promotion is precisely the act of making this node the
+ * publisher, so importing under the publisher role is correct.
+ *
+ * MUST happen WITHIN the current record's validity window: while the old
+ * publisher's ~72h record is still valid (kept alive by replica re-announcement
+ * during the grace window), the promoted node's first `name/publish` re-signs
+ * before the record lapses, so the name never goes dark. Promotion imports the
+ * key ONLY; it does not itself sign — the node signs on its next `republish`.
+ */
+export async function promoteReplicaToPublisher(input) {
+    // Reuse the key-import seam. It refuses any non-publisher role, so we pass
+    // the TARGET role (`publisher`): promotion IS making this node the publisher.
+    const imported = await importIpnsKeyIntoPublisher({
+        client: input.client,
+        role: 'publisher',
+        keyName: input.keyName,
+        derived: input.derived,
+    });
+    // Flip the role. From here the node is the single signer for this name.
+    return { role: 'publisher', keyName: input.keyName, ipns: imported.Id };
+}
+// ---------------------------------------------------------------------------
+// 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;
+}
+/** Read a cached record + its ipns id for a site, or undefined if absent. */
+async function readCached(cacheDir, name) {
+    try {
+        const record = await readFile(join(cacheDir, name + RECORD_SUFFIX), 'utf8');
+        const ipnsId = (await readFile(join(cacheDir, name + NAME_SUFFIX), 'utf8')).trim();
+        if (!ipnsId)
+            return undefined;
+        return { record, ipnsId };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Production publisher-record fetch: GET the URL and return its body text. */
+async function httpFetchText(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`fetch ${url} -> ${res.status}`);
+    return await res.text();
+}
+//# sourceMappingURL=record-sequence.js.map

package/dist/publisher/record-sequence.js.map

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

package/dist/rpc/kubo-rpc-client.d.ts

@@ -0,0 +1,154 @@
+/**
+ * A typed, per-node Kubo RPC client. It wraps `POST {baseUrl}/api/v0/<path>`
+ * with an `Authorization: Bearer <token>` header on EVERY call. No Kubo binary
+ * runs on the client — all interaction is HTTP.
+ *
+ * This is the seam every host-agnostic pinnace operation (deploy, publish,
+ * status, site management) speaks. It is deliberately PER-NODE (one base URL +
+ * one token); multi-target fan-out lives in the deploy task, not here.
+ *
+ * Behaviour ported (not copied) from the reference prototype
+ * `~/searches/ipfs-hetzner/deploy-car.mjs`: the exact query params
+ * (`files/mkdir?arg=/sites&parents=true`, `dag/import?pin-roots=true`, ...) and
+ * the throw-on-`!ok` error handling.
+ */
+/** A minimal `fetch`-shaped function, so tests can inject a recording mock. */
+export type FetchLike = (input: string | URL, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+}) => Promise<Response>;
+/** Options for constructing a per-node {@link KuboRpcClient}. */
+export interface KuboRpcClientOptions {
+    /** The node's Kubo RPC base URL, e.g. `https://ipfs-api.example.com`. */
+    baseUrl: string;
+    /** The node's bearer token (sent on every call). */
+    token: string;
+    /** Injectable fetch (defaults to the global `fetch`); tests pass the mock. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * A loud error carrying the endpoint + HTTP status of a non-2xx Kubo response,
+ * so a caller (and a log) can see exactly which call failed and how.
+ */
+export declare class KuboRpcError extends Error {
+    /** The `/api/v0/<endpoint>` path that failed. */
+    readonly endpoint: string;
+    /** The HTTP status returned. */
+    readonly status: number;
+    /** The response body text (for diagnostics). */
+    readonly bodyText: string;
+    constructor(
+    /** The `/api/v0/<endpoint>` path that failed. */
+    endpoint: string, 
+    /** The HTTP status returned. */
+    status: number, 
+    /** The response body text (for diagnostics). */
+    bodyText: string);
+}
+/** Flags accepted by `files/mkdir`. */
+export interface FilesMkdirOptions {
+    /** Create parent directories as needed (`parents=true`). */
+    parents?: boolean;
+}
+/** Flags accepted by `files/rm`. */
+export interface FilesRmOptions {
+    /** Remove directories recursively (`recursive=true`). */
+    recursive?: boolean;
+    /** Ignore nonexistent files (`force=true`). */
+    force?: boolean;
+}
+/** Parameters for `name/publish`. */
+export interface NamePublishOptions {
+    /** The `/ipfs/<cid>` path to publish. */
+    cidPath: string;
+    /** The keystore key name to sign with. */
+    key: string;
+    /** Record lifetime (e.g. `72h`). */
+    lifetime?: string;
+    /** Record TTL (e.g. `1h`). */
+    ttl?: string;
+    /** Publish even with no online peers (`allow-offline=true`). */
+    allowOffline?: boolean;
+}
+export declare class KuboRpcClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly fetchImpl;
+    constructor(options: KuboRpcClientOptions);
+    /**
+     * The core request primitive: POST `/api/v0/<endpoint>?<query>` with the
+     * bearer token. Throws {@link KuboRpcError} on any non-2xx. Returns the raw
+     * {@link Response} so callers can decode JSON or bytes as they need.
+     */
+    request(endpoint: string, query?: URLSearchParams, body?: unknown, extraHeaders?: Record<string, string>): Promise<Response>;
+    /** POST an endpoint and parse the JSON response body. */
+    private requestJson;
+    /** `id` — the node's identity (PeerID etc.). */
+    id<T = unknown>(): Promise<T>;
+    /**
+     * `add` — add raw bytes (returned shape is Kubo-defined). Kubo requires the
+     * payload as a `multipart/form-data` `file` part, NOT a raw body, so we send
+     * a {@link FormData} and let `fetch` set the multipart boundary itself (see
+     * {@link fileUpload}).
+     */
+    add<T = unknown>(data: Uint8Array): Promise<T>;
+    /** `dag/import?pin-roots=true` — import a CAR and pin its roots. */
+    dagImport<T = unknown>(car: Uint8Array): Promise<T>;
+    /**
+     * `pin/rm?arg=<cid>` — UNPIN content so Kubo can garbage-collect it and
+     * reclaim storage. The counterpart to `dag/import?pin-roots=true`: removing a
+     * site unpins its CID here so it stops being served/announced. `arg` takes a
+     * bare CID (or an `/ipfs/<cid>` path); callers pass the CID from `files/stat`.
+     */
+    pinRm<T = unknown>(cid: string): Promise<T>;
+    /** `files/mkdir?arg=<path>[&parents=true]`. */
+    filesMkdir(path: string, options?: FilesMkdirOptions): Promise<void>;
+    /** `files/rm?arg=<path>[&recursive=true][&force=true]`. */
+    filesRm(path: string, options?: FilesRmOptions): Promise<void>;
+    /** `files/cp?arg=<from>&arg=<to>`. */
+    filesCp(from: string, to: string): Promise<void>;
+    /** `files/stat?arg=<path>` — returns the MFS entry stat (Hash, Type, ...). */
+    filesStat<T = unknown>(path: string): Promise<T>;
+    /** `files/ls?arg=<path>[&l=true]` — list an MFS directory. */
+    filesLs<T = unknown>(path: string, long?: boolean): Promise<T>;
+    /** `key/list?l=true` — list keystore keys with their IPNS ids. */
+    keyList<T = unknown>(): Promise<T>;
+    /** `key/gen?arg=<name>&type=ed25519` — generate a new keystore key. */
+    keyGen<T = unknown>(name: string): Promise<T>;
+    /**
+     * `key/import?arg=<name>` — import key MATERIAL (libp2p/protobuf bytes) into
+     * the keystore. The node, not the client, signs records with it.
+     */
+    keyImport<T = unknown>(name: string, keyBytes: Uint8Array): Promise<T>;
+    /**
+     * Kubo's file-upload endpoints require the payload as a `multipart/form-data`
+     * body with the bytes as a named file part (confirmed by the Kubo RPC docs'
+     * `-F <field>=@…` cURL examples and a live daemon). A raw
+     * `application/octet-stream` body is rejected with
+     * `400 file argument '<field>' is required`.
+     *
+     * The field name is endpoint-specific: `add`, `dag/import` and `key/import`
+     * expect `file` (the default), while `routing/put` expects `value-file`.
+     *
+     * We build a {@link FormData} and pass it as the body WITHOUT a hand-set
+     * `content-type`: `fetch` serialises the FormData and sets
+     * `content-type: multipart/form-data; boundary=…` itself. Setting it manually
+     * would omit/override the boundary and break the request.
+     */
+    private fileUpload;
+    /** `name/publish?arg=<cidPath>&key=<key>&lifetime=..&ttl=..` — sign+publish IPNS. */
+    namePublish<T = unknown>(options: NamePublishOptions): Promise<T>;
+    /** `routing/get?arg=<ipnsPath>` — fetch the raw signed record for a name. */
+    routingGet(ipnsPath: string): Promise<Uint8Array>;
+    /**
+     * `routing/put?arg=<ipnsPath>` — (re-)announce a signed record body. Kubo's
+     * `routing/put` takes the record as a `multipart/form-data` file part named
+     * **`value-file`** (NOT the generic `file` the other upload endpoints use); a
+     * raw `application/octet-stream` body is rejected with
+     * `400 file argument 'value-file' is required`. Goes through {@link fileUpload}
+     * so `fetch` owns the multipart boundary (no hand-set content-type).
+     */
+    routingPut(ipnsPath: string, record: Uint8Array): Promise<void>;
+}
+//# sourceMappingURL=kubo-rpc-client.d.ts.map

package/dist/rpc/kubo-rpc-client.d.ts.map

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