ton-mesh-harness 0.13.0

package/dist/daemon/installer-utils.d.ts

@@ -0,0 +1,103 @@
+/** All daemon binaries live here. Created on demand by callers. */
+export declare const BIN_DIR: string;
+/**
+ * Atomically download `url` to `dest`. Uses `curl -fsSL` (HTTPS, follow
+ * redirects, fail on HTTP error) and writes through a `.tmp` file
+ * renamed via Node's `renameSync` so the move is portable across
+ * darwin/linux/win32 (`mv` isn't on PATH on stock Windows).
+ *
+ * Throws on non-zero curl exit. The caller is responsible for `chmod +x`
+ * and quarantine removal (see `chmodExecutable` / `removeQuarantine`).
+ */
+export declare function downloadFile(url: string, dest: string): void;
+/**
+ * Apply executable permission on POSIX. No-op on Windows (the .exe
+ * extension is the executable marker there).
+ */
+export declare function chmodExecutable(absPath: string): void;
+/**
+ * Strip platform-specific download quarantine markers:
+ *   - macOS: `xattr -c <file>` removes `com.apple.quarantine` (and
+ *     other extended attributes — equivalent to a fresh download).
+ *   - Windows: PowerShell `Unblock-File` clears the
+ *     `Zone.Identifier` alternate data stream that triggers the
+ *     "this file came from another computer" prompt.
+ *   - Linux: no-op (no quarantine system).
+ *
+ * Failures are silent — the binary may still launch fine.
+ */
+export declare function removeQuarantine(absPath: string): void;
+/**
+ * Spec for a daemon installer. `installBinary` and `resolveBinaryPaths`
+ * consume one. Lets the two release-asset-shaped installers
+ * (tonutils-storage, rldp-http-proxy) live as ~25 LOC each instead of
+ * 85 LOC of copy-paste.
+ */
+export interface BinaryInstallerSpec {
+    /** Human-readable banner name (`Downloading <name> (<version>)…`). */
+    name: string;
+    /** Pinned version string written into the on-disk version file. */
+    version: string;
+    /** Base file name; `.exe` is appended on win32 automatically. */
+    exeName: string;
+    /** Version-stamp file name (kept next to the binary in BIN_DIR). */
+    versionFileName: string;
+    /** `${process.platform}-${process.arch}` → release asset file name. */
+    assetMap: Record<string, string>;
+    /** Builds the download URL for a given (version, asset). */
+    downloadUrl: (version: string, asset: string) => string;
+    /** Trailing line appended to the "no asset for $platform-$arch" error. */
+    unsupportedHint: string;
+    /**
+     * Pinned SHA-256 hashes per `${platform}-${arch}` key. Verified after
+     * download — mismatch deletes the partial file and throws. Required
+     * for supply-chain integrity: without it, a compromised GitHub
+     * release asset or MITM'd CDN endpoint would execute as the user.
+     * Codex pre-GA review round 11 (self-audit) caught the missing
+     * verification. v0.8 hashes pinned for the version of each binary
+     * embedded above; bump them in lockstep with `version` when
+     * upgrading.
+     *
+     * An empty / missing entry for the current platform-arch falls back
+     * to TOFU (trust on first use) + a loud stderr warning. Hashes for
+     * ALL supported platforms should be pinned before GA tag.
+     */
+    expectedSha256?: Partial<Record<string, string>>;
+}
+export interface BinaryPaths {
+    binDir: string;
+    daemon: string;
+    versionFile: string;
+}
+export declare function resolveBinaryPaths(spec: BinaryInstallerSpec): BinaryPaths;
+export interface InstallBinaryOptions {
+    /** Suppress the human-readable download banner (JSON-output mode). */
+    silent?: boolean;
+}
+/**
+ * Idempotent installer: returns immediately if the binary at
+ * `spec.exeName` already matches `spec.version`; otherwise downloads
+ * the platform-appropriate asset, chmods it, strips quarantine, and
+ * writes the version stamp.
+ *
+ * Throws if no asset is mapped for the current platform/arch.
+ */
+export declare function installBinary(spec: BinaryInstallerSpec, opts?: InstallBinaryOptions): void;
+/**
+ * Verify a downloaded file's SHA-256 against an expected hash. Throws
+ * + `unlinkSync`'s the file on mismatch so the next install attempt
+ * starts fresh. Pass `expected: undefined` to opt into TOFU (emits a
+ * loud stderr warning and proceeds).
+ *
+ * Public helper exported for installers that don't go through
+ * `installBinary` — e.g. `src/daemon/installer.ts` downloads two
+ * binaries + two config files in its own loop. Used inline there
+ * after each `downloadFile` call.
+ */
+export declare function verifyFileSha256(args: {
+    name: string;
+    version: string;
+    platformKey: string;
+    filePath: string;
+    expected: string | undefined;
+}): void;

package/dist/daemon/installer.d.ts

@@ -0,0 +1,30 @@
+/** @internal Exported for the #101 regression test (TOFU-gap guard). */
+export declare const STORAGE_DAEMON_HASHES: Record<string, string>;
+/** @internal Exported for the #101 regression test (TOFU-gap guard). */
+export declare const STORAGE_DAEMON_CLI_HASHES: Record<string, string>;
+export interface DaemonPaths {
+    binDir: string;
+    daemon: string;
+    cli: string;
+    mainnetConfig: string;
+    testnetConfig: string;
+    versionFile: string;
+}
+/**
+ * Get all daemon-related file paths
+ */
+export declare function getDaemonPaths(): DaemonPaths;
+export interface EnsureBinariesOptions {
+    /** Suppress the download banner. Use when stdout must stay JSON-clean. */
+    silent?: boolean;
+}
+/**
+ * Ensure daemon binaries (storage-daemon + storage-daemon-cli) are
+ * installed and up-to-date. Also downloads the appropriate network
+ * config JSON if missing. Idempotent.
+ *
+ * All progress banners go to STDERR so `--json-output` stdout stays
+ * parseable (matches the convention `tonutils-installer.ts` /
+ * `rldp-http-proxy-installer.ts` use via `installer-utils`).
+ */
+export declare function ensureBinaries(useTestnet?: boolean, opts?: EnsureBinariesOptions): void;

package/dist/daemon/linger.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Advisory line when a `--daemon-mode service` unit will NOT survive an
+ * unattended reboot — i.e. the host is Linux AND systemd lingering is disabled
+ * for the current user. Returns `null` when:
+ *   - not Linux (launchd handles reboot via RunAtLoad), or
+ *   - lingering is already enabled, or
+ *   - we can't determine it (loginctl absent / user not known to logind) —
+ *     stay quiet rather than print a command that might not apply.
+ */
+export declare function lingerAdvisory(): string | null;

package/dist/daemon/platform.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Platform detection and binary naming utilities
+ */
+export declare const PLATFORM_MAP: Record<string, string>;
+/**
+ * Get the platform key for the current system
+ * @throws {Error} if platform is not supported
+ */
+export declare function getPlatformKey(): string;
+/**
+ * Get the release-asset name for the current platform.
+ *
+ * Asset naming on ton-blockchain/ton GitHub releases:
+ *   - macOS / Linux: `<base>-<platform-suffix>`     (e.g. `storage-daemon-mac-arm64`)
+ *   - Windows:       `<base>.exe`                   (NO platform suffix — single
+ *                                                     x86_64 asset across Win
+ *                                                     architectures)
+ *
+ * Pre-rc11 the Windows branch returned `<base>-<suffix>.exe` (e.g.
+ * `storage-daemon-win-x86-64.exe`) which doesn't exist on GitHub —
+ * Windows users got a 404 from curl. Self-audit caught this while
+ * pinning SHA-256 hashes for the legacy installer.
+ *
+ * @param base - Base binary name
+ */
+export declare function getBinaryName(base: 'storage-daemon' | 'storage-daemon-cli'): string;
+/**
+ * Resolve the platform key used to look up a pinned SHA-256 for the legacy
+ * storage-daemon binaries (src/daemon/installer.ts).
+ *
+ * TON publishes a SINGLE x86-64 Windows asset (`storage-daemon.exe`) for all
+ * Windows architectures — `getBinaryName` returns that one file regardless of
+ * arch — but the hash map only pins `win32-x64`. Without this mapping,
+ * `win32-arm64` / `win32-ia32` look up an `undefined` hash and the integrity
+ * check is silently skipped (trust-on-first-use), installing an unverified —
+ * and on 32-bit, unrunnable — binary.
+ *
+ * - `win32-arm64` → `win32-x64`: the downloaded file IS the x64 `.exe`, which
+ *   64-bit ARM Windows runs under its built-in x64 emulation; verify it against
+ *   the known x64 hash.
+ * - `win32-ia32` → throw: a 32-bit OS cannot run an x64 binary, so fail fast
+ *   with a clear message instead of installing a broken, unverified binary.
+ * - every other key passes through unchanged.
+ *
+ * @throws {Error} on 32-bit Windows (`win32-ia32`).
+ */
+export declare function daemonHashKey(platformKey: string): string;

package/dist/daemon/ports.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Probe TCP ports in `[min, max]` on 127.0.0.1. Returns the first port
+ * that accepts a listener. Throws if the entire range is busy.
+ *
+ * Default range matches the legacy export from `tonutils-process.ts`
+ * (7100–7199) so call sites that did `findFreePort()` without arguments
+ * keep working.
+ */
+export declare function findFreeTcpPort(min?: number, max?: number): Promise<number>;
+/**
+ * Probe UDP ports in `[min, max]` on 0.0.0.0. Returns the first that
+ * binds. Throws if every port in the range is busy.
+ */
+export declare function findFreeUdpPort(min?: number, max?: number): Promise<number>;

package/dist/daemon/rldp-http-proxy-installer.d.ts

@@ -0,0 +1,10 @@
+import { type BinaryPaths, type InstallBinaryOptions } from './installer-utils';
+export declare const RLDP_HTTP_PROXY_VERSION: string;
+export type RldpHttpProxyPaths = BinaryPaths;
+export type EnsureRldpHttpProxyBinaryOptions = InstallBinaryOptions;
+export declare function getRldpHttpProxyPaths(): RldpHttpProxyPaths;
+/**
+ * Idempotently install the rldp-http-proxy binary at the expected version.
+ * No-ops when already installed.
+ */
+export declare function ensureRldpHttpProxyBinary(opts?: EnsureRldpHttpProxyBinaryOptions): void;

package/dist/daemon/service.d.ts

@@ -0,0 +1,36 @@
+export declare const SEEDS_ROOT: string;
+export interface ServiceMeta {
+    bag_id: string;
+    label: string;
+    db_dir: string;
+    api_port: number;
+    network_config_path: string | null;
+    daemon_path: string;
+    created_at: string;
+}
+export interface ServiceStatus {
+    bag_id: string;
+    label: string;
+    running: boolean;
+    api_url: string;
+    db_dir: string;
+}
+export declare class ServiceError extends Error {
+}
+export declare function serviceLabel(bagId: string): string;
+export declare function seedDir(bagId: string): string;
+export declare function buildLaunchdPlist(meta: ServiceMeta): string;
+export declare function buildSystemdUnit(meta: ServiceMeta): string;
+/**
+ * Install + load a per-bag seed service. `db_dir` must already contain the
+ * created bag (the daemon will resume seeding it from there).
+ */
+export declare function installService(meta: ServiceMeta): void;
+export declare function listServices(): ServiceStatus[];
+/**
+ * Stop + unload a bag's seed service. Removes the unit file; removes the
+ * seed dir (db + metadata) only when `removeDb` is true.
+ */
+export declare function stopService(bagId: string, opts?: {
+    removeDb?: boolean;
+}): void;

package/dist/daemon/tonutils-installer.d.ts

@@ -0,0 +1,10 @@
+import { type BinaryPaths, type InstallBinaryOptions } from './installer-utils';
+export type TonutilsPaths = BinaryPaths;
+export type EnsureTonutilsBinaryOptions = InstallBinaryOptions;
+export declare function getTonutilsPaths(): TonutilsPaths;
+/**
+ * Ensure the tonutils-storage binary is installed and at the expected
+ * version. Idempotent — does nothing if the binary is already present
+ * with a matching .tonutils-version file.
+ */
+export declare function ensureTonutilsBinary(opts?: EnsureTonutilsBinaryOptions): void;

package/dist/daemon/tonutils-process.d.ts

@@ -0,0 +1,90 @@
+import { type ChildProcess } from 'child_process';
+import { findFreeTcpPort, findFreeUdpPort } from './ports';
+export interface TonutilsHandle {
+    apiUrl: string;
+    dbDir: string;
+    process: ChildProcess;
+    kill: () => void;
+    reachable?: boolean | null;
+}
+export { findFreeTcpPort as findFreePort, findFreeUdpPort };
+export declare function ensureTonutilsNetworkConfig(testnet: boolean): Promise<string | undefined>;
+export interface EnsureTonutilsConfigOptions {
+    tunnelConfigPath?: string;
+    externalIp?: string;
+    listenPort?: number;
+}
+export interface AnnounceConfig {
+    externalIp?: string;
+    listenPort?: number;
+}
+export declare function announceIpFromEnv(env: NodeJS.ProcessEnv): string | undefined;
+export declare function announcePortFromEnv(env: NodeJS.ProcessEnv): number | undefined;
+export declare function parseAnnounceEnv(env: NodeJS.ProcessEnv): AnnounceConfig;
+export declare function resolveAnnounce(explicit: AnnounceConfig, env: NodeJS.ProcessEnv): AnnounceConfig;
+export declare function ensureTonutilsConfig(daemonPath: string, dbDir: string, cfgOpts?: EnsureTonutilsConfigOptions): Promise<void>;
+export declare function parseServerMode(output: string): boolean | null;
+export interface StartTonutilsDaemonOptions {
+    tunnelConfigPath?: string;
+    /** Path to a global network config (testnet); omit for mainnet default. */
+    networkConfigPath?: string;
+    /**
+     * Cloud-seeder announce overrides (#69), already validated by the caller.
+     * Take precedence (per-field) over the MESH_ANNOUNCE_IP / _PORT env
+     * vars; when both are omitted the env vars are used (the #67 behaviour).
+     */
+    externalIp?: string;
+    listenPort?: number;
+    /**
+     * Persistent db dir (#37 service mode). When set, the daemon uses this
+     * dir instead of an ephemeral mkdtemp one, and kill() does NOT delete it
+     * (the OS service unit resumes seeding from here). Omit for the default
+     * ephemeral behaviour.
+     */
+    dbDir?: string;
+}
+export declare function startTonutilsDaemon(opts?: StartTonutilsDaemonOptions): Promise<TonutilsHandle>;
+export interface TonutilsBagSummary {
+    bag_id: string;
+    description: string;
+    downloaded: number;
+    size: number;
+    files_count: number;
+    dir_name: string;
+    completed: boolean;
+    header_loaded: boolean;
+    info_loaded: boolean;
+    active: boolean;
+    seeding: boolean;
+}
+export interface TonutilsBagDetails extends TonutilsBagSummary {
+    piece_size: number;
+    bag_size: number;
+    merkle_hash: string;
+    path: string;
+    files: Array<{
+        index: number;
+        name: string;
+        size: number;
+    }>;
+    peers?: Array<{
+        addr: string;
+        id: string;
+    }>;
+}
+export declare function tonutilsCreate(handle: TonutilsHandle, args: {
+    path: string;
+    description: string;
+}): Promise<{
+    bag_id: string;
+}>;
+export declare function tonutilsDetails(handle: TonutilsHandle, bagId: string): Promise<TonutilsBagDetails>;
+export declare function tonutilsList(handle: TonutilsHandle): Promise<{
+    bags: TonutilsBagSummary[];
+}>;
+export declare function tonutilsRemove(handle: TonutilsHandle, args: {
+    bag_id: string;
+    with_files?: boolean;
+}): Promise<{
+    ok: boolean;
+}>;

package/dist/deeplink.d.ts

@@ -0,0 +1,25 @@
+import { Address, Cell } from '@ton/ton';
+/**
+ * RFC 4648 §5 base64url: `+`→`-`, `/`→`_`, strip `=` padding. Tonkeeper's
+ * `bin` parameter expects the message-body BOC encoded this way.
+ */
+export declare function toBase64Url(buf: Buffer): string;
+export interface TonkeeperTransferLink {
+    /** Destination contract (here: the `.ton` domain NFT item). */
+    to: Address;
+    /** Attached value in nanoTON; must be positive (covers gas). */
+    amountNano: bigint;
+    /** Message body cell (here: a `change_dns_record` op). */
+    body: Cell;
+    /** Encode `to` in testnet form (`testOnly` address flag). */
+    testnet?: boolean;
+}
+/**
+ * Build a Tonkeeper transfer deeplink for a single signed message.
+ *
+ * The address is encoded bounceable (it targets a deployed contract) and
+ * url-safe; the body is serialized to BOC and base64url-encoded into `bin`.
+ * Both `amount` and `bin` use URL-safe characters, so the query string is
+ * left intact by `URLSearchParams`.
+ */
+export declare function buildTonkeeperTransferDeeplink(link: TonkeeperTransferLink): string;

package/dist/dns.d.ts

@@ -0,0 +1,39 @@
+import { Address, Cell } from '@ton/ton';
+export interface DnsRegistrationOptions {
+    domain: string;
+    bagId: string;
+}
+export interface DnsCheckResult {
+    registered: boolean;
+    currentBagId?: string;
+}
+export declare function buildDnsStorageRecord(bagId: string): Cell;
+export declare function buildDnsAdnlRecord(adnlHex: string, flags?: number): Cell;
+export declare function buildChangeDnsRecordBody(bagId: string): Cell;
+export declare function buildChangeDnsSiteRecordBody(adnlHex: string, flags?: number): Cell;
+export declare function getDomainNftAddress(domain: string, testnet?: boolean): Promise<Address>;
+interface TonApiDnsRecord {
+    storage?: string | {
+        bag_id?: string;
+    };
+    sites?: string[];
+}
+export declare function extractStorageBagId(data: TonApiDnsRecord | null | undefined): string | null;
+/**
+ * @param opts.silent suppresses ora spinner + console.log fallback message
+ *   so the SDK / MCP path can call this without polluting stdout (the MCP
+ *   stdio framing breaks if console.log writes to stdout). CLI continues
+ *   to pass silent: false (default) for human output.
+ */
+export declare function pollDnsRecord(domain: string, expectedBagId: string, timeoutMs?: number, intervalMs?: number, testnet?: boolean, opts?: {
+    silent?: boolean;
+    signal?: AbortSignal;
+}): Promise<boolean>;
+/**
+ * @param opts.silent see pollDnsRecord.
+ */
+export declare function pollDnsSiteRecord(domain: string, expectedAdnlHex: string, timeoutMs?: number, intervalMs?: number, testnet?: boolean, opts?: {
+    silent?: boolean;
+    signal?: AbortSignal;
+}): Promise<boolean>;
+export {};