swarm-deploy 0.0.0 → 0.2.0

package/dist/tar-protocol/tree.js

@@ -0,0 +1,269 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TREE_DIGEST_DOMAIN = exports.tarEntryName = exports.MAX_TREE_NAME_BYTES = exports.MAX_TREE_ENTRIES = exports.MAX_TREE_DEPTH = exports.compareTreePaths = exports.assertTreeStoredName = exports.assertTreeEntryPath = void 0;
+exports.assertCanonicalTreeEntries = assertCanonicalTreeEntries;
+exports.hashField = hashField;
+exports.treeDigest = treeDigest;
+exports.classifyTreeEntry = classifyTreeEntry;
+exports.treeDirectoryReadError = treeDirectoryReadError;
+exports.normalizeRevalidateFailure = normalizeRevalidateFailure;
+exports.snapshotTree = snapshotTree;
+exports.assertSameTreeIdentity = assertSameTreeIdentity;
+exports.revalidateTreeSnapshot = revalidateTreeSnapshot;
+const b4a_1 = __importDefault(require("b4a"));
+const _fs_1 = __importDefault(require("#fs"));
+const _path_1 = __importDefault(require("#path"));
+const abort_js_1 = require("../abort.js");
+const errors_js_1 = require("../errors.js");
+const hash_js_1 = require("./hash.js");
+const tree_path_js_1 = require("./tree-path.js");
+const ustar_js_1 = require("./ustar.js");
+var tree_path_js_2 = require("./tree-path.js");
+Object.defineProperty(exports, "assertTreeEntryPath", { enumerable: true, get: function () { return tree_path_js_2.assertTreeEntryPath; } });
+Object.defineProperty(exports, "assertTreeStoredName", { enumerable: true, get: function () { return tree_path_js_2.assertTreeStoredName; } });
+Object.defineProperty(exports, "compareTreePaths", { enumerable: true, get: function () { return tree_path_js_2.compareTreePaths; } });
+Object.defineProperty(exports, "MAX_TREE_DEPTH", { enumerable: true, get: function () { return tree_path_js_2.MAX_TREE_DEPTH; } });
+Object.defineProperty(exports, "MAX_TREE_ENTRIES", { enumerable: true, get: function () { return tree_path_js_2.MAX_TREE_ENTRIES; } });
+Object.defineProperty(exports, "MAX_TREE_NAME_BYTES", { enumerable: true, get: function () { return tree_path_js_2.MAX_TREE_NAME_BYTES; } });
+Object.defineProperty(exports, "tarEntryName", { enumerable: true, get: function () { return tree_path_js_2.tarEntryName; } });
+exports.TREE_DIGEST_DOMAIN = 'swarm-deploy/tree/v1';
+function invalid(message, cause = null) {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, message, cause);
+}
+function unsafeName(message) {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.INVALID_FILENAME, message);
+}
+function fileBusy(message) {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, message);
+}
+function isTreeFileDigest(value) {
+    if (!b4a_1.default.isBuffer(value) || value.byteLength !== 32)
+        return false;
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))
+        return true;
+    return value.constructor.name === 'Buffer';
+}
+const REVALIDATE_BUSY_MESSAGE = 'Tree changed during TAR generation';
+function finishRevalidate(error) {
+    if (error instanceof errors_js_1.SwarmDeployError && error.code === errors_js_1.ERRORS.ABORTED)
+        throw error;
+    throw fileBusy(REVALIDATE_BUSY_MESSAGE);
+}
+function assertCanonicalTreeEntries(entries) {
+    if (!Array.isArray(entries))
+        throw invalid('Invalid tree entry list');
+    if (entries.length > tree_path_js_1.MAX_TREE_ENTRIES)
+        throw invalid('Tree has too many entries');
+    const directories = new Set();
+    const folded = new Set();
+    let previous = null;
+    for (const entry of entries) {
+        if (entry.kind !== 'file' && entry.kind !== 'directory') {
+            throw invalid('Invalid tree entry kind');
+        }
+        if (entry.kind === 'directory' && entry.size !== 0)
+            throw invalid('Invalid tree directory size');
+        if (typeof entry.size !== 'number' || !Number.isSafeInteger(entry.size) || entry.size < 0) {
+            throw invalid('Invalid tree entry size');
+        }
+        if (entry.kind === 'file' && entry.size > ustar_js_1.MAX_USTAR_FILE_BYTES) {
+            throw invalid('Tree file exceeds canonical USTAR capacity');
+        }
+        (0, tree_path_js_1.assertTreeEntryPath)(entry.path, entry.kind);
+        if (previous !== null && (0, tree_path_js_1.compareTreePaths)(previous, entry.path) >= 0) {
+            throw invalid('Noncanonical tree entry order');
+        }
+        const fold = entry.path.toLowerCase();
+        if (folded.has(fold))
+            throw invalid('Case-folded duplicate tree entry path');
+        folded.add(fold);
+        const separator = entry.path.lastIndexOf('/');
+        if (separator !== -1 && !directories.has(entry.path.slice(0, separator))) {
+            throw invalid('Tree entry has no parent directory entry');
+        }
+        if (entry.kind === 'directory')
+            directories.add(entry.path);
+        previous = entry.path;
+    }
+}
+/** Length-prefixed, labelled field framing shared by tree digests and tree transfer IDs. */
+function hashField(hash, label, value) {
+    const valueBytes = typeof value === 'number' ? b4a_1.default.from(String(value)) : b4a_1.default.from(value);
+    hash
+        .update(b4a_1.default.from(`${label}\u0000`))
+        .update(b4a_1.default.from(`${valueBytes.byteLength}:`))
+        .update(valueBytes);
+}
+function treeDigest(entries) {
+    assertCanonicalTreeEntries(entries.map((value) => value.entry));
+    const hash = new hash_js_1.SodiumSha256();
+    hashField(hash, 'domain', exports.TREE_DIGEST_DOMAIN);
+    hashField(hash, 'entryCount', entries.length);
+    for (const { entry, sha256 } of entries) {
+        hashField(hash, 'kind', entry.kind);
+        hashField(hash, 'path', entry.path);
+        hashField(hash, 'size', entry.size);
+        if (entry.kind === 'directory') {
+            if (sha256 !== undefined)
+                throw invalid('Unexpected tree directory digest');
+            continue;
+        }
+        if (!isTreeFileDigest(sha256))
+            throw invalid('Invalid tree file digest');
+        hashField(hash, 'sha256', sha256);
+    }
+    return hash.digest();
+}
+function identityOf(stat) {
+    return { dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs };
+}
+function classifyTreeEntry(stat) {
+    if (stat.isSymbolicLink())
+        throw unsafeName('Tree entries cannot be symbolic links');
+    if (stat.isDirectory())
+        return 'directory';
+    if (!stat.isFile())
+        throw unsafeName('Tree entries must be regular files or directories');
+    if (typeof stat.nlink === 'number' && stat.nlink > 1) {
+        throw unsafeName('Tree entries cannot be hard links');
+    }
+    return 'file';
+}
+function classify(stat) {
+    return classifyTreeEntry(stat);
+}
+/** Stable error for unreadable directory listings during snapshot walks. */
+function treeDirectoryReadError() {
+    return invalid('Unable to read tree directory');
+}
+/** Maps revalidation failures to FILE_BUSY while preserving ABORTED. */
+function normalizeRevalidateFailure(error) {
+    finishRevalidate(error);
+}
+/**
+ * Walks `rootPath` recursively and returns the canonical entry list with one
+ * snapshotted identity per entry. Any unsafe or non-regular member rejects the
+ * whole directory; nothing is ever silently dropped.
+ */
+async function snapshotTree(rootPath, { signal = null } = {}) {
+    (0, abort_js_1.throwIfAborted)(signal);
+    const rootStat = await _fs_1.default.promises.lstat(rootPath);
+    if (classify(rootStat) !== 'directory')
+        throw unsafeName('Tree root must be a directory');
+    const seen = new Set([`${rootStat.dev}:${rootStat.ino}`]);
+    const entries = [];
+    let payloadBytes = 0;
+    const walk = async (absolute, prefix) => {
+        let names;
+        try {
+            names = await _fs_1.default.promises.readdir(absolute);
+        }
+        catch {
+            throw treeDirectoryReadError();
+        }
+        names.sort((left, right) => (0, tree_path_js_1.compareTreePaths)(left, right));
+        for (const name of names) {
+            (0, abort_js_1.throwIfAborted)(signal);
+            const entryPath = prefix === '' ? name : `${prefix}/${name}`;
+            const entryAbsolute = _path_1.default.join(absolute, name);
+            const stat = await _fs_1.default.promises.lstat(entryAbsolute);
+            const kind = classify(stat);
+            (0, tree_path_js_1.assertTreeEntryPath)(entryPath, kind);
+            if (entries.length >= tree_path_js_1.MAX_TREE_ENTRIES)
+                throw invalid('Tree has too many entries');
+            if (kind === 'directory') {
+                const identity = `${stat.dev}:${stat.ino}`;
+                if (seen.has(identity))
+                    throw unsafeName('Tree contains a filesystem cycle');
+                seen.add(identity);
+                entries.push({
+                    kind,
+                    path: entryPath,
+                    size: 0,
+                    absolutePath: entryAbsolute,
+                    identity: identityOf(stat)
+                });
+                await walk(entryAbsolute, entryPath);
+                continue;
+            }
+            if (stat.size > ustar_js_1.MAX_USTAR_FILE_BYTES) {
+                throw invalid('Tree file exceeds canonical USTAR capacity');
+            }
+            if (payloadBytes > Number.MAX_SAFE_INTEGER - stat.size) {
+                throw invalid('Tree payload exceeds safe integer range');
+            }
+            payloadBytes += stat.size;
+            entries.push({
+                kind,
+                path: entryPath,
+                size: stat.size,
+                absolutePath: entryAbsolute,
+                identity: identityOf(stat)
+            });
+        }
+    };
+    await walk(rootPath, '');
+    entries.sort((left, right) => (0, tree_path_js_1.compareTreePaths)(left.path, right.path));
+    assertCanonicalTreeEntries(entries);
+    return {
+        rootPath,
+        root: identityOf(rootStat),
+        entries,
+        entryCount: entries.length,
+        payloadBytes
+    };
+}
+function assertSameTreeIdentity(expected, actual, message) {
+    if (actual.dev !== expected.dev ||
+        actual.ino !== expected.ino ||
+        actual.size !== expected.size ||
+        actual.mtimeMs !== expected.mtimeMs) {
+        throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, message);
+    }
+}
+/**
+ * Reproves every snapshotted identity and re-walks the source tree before a resume
+ * regenerates the archive. Any mutation, disappearance, unreadable path, collision,
+ * limit breach, or newly unsafe member becomes FILE_BUSY; ABORTED is preserved.
+ */
+async function revalidateTreeSnapshot(snapshot, { signal = null } = {}) {
+    (0, abort_js_1.throwIfAborted)(signal);
+    try {
+        const rootStat = await _fs_1.default.promises.lstat(snapshot.rootPath);
+        if (classify(rootStat) !== 'directory')
+            throw unsafeName('Tree root must be a directory');
+        if (rootStat.dev !== snapshot.root.dev || rootStat.ino !== snapshot.root.ino) {
+            throw fileBusy(REVALIDATE_BUSY_MESSAGE);
+        }
+        for (const entry of snapshot.entries) {
+            (0, abort_js_1.throwIfAborted)(signal);
+            const stat = await _fs_1.default.promises.lstat(entry.absolutePath);
+            const kind = classify(stat);
+            if (kind !== entry.kind)
+                throw fileBusy(REVALIDATE_BUSY_MESSAGE);
+            if (entry.kind === 'directory') {
+                if (stat.dev !== entry.identity.dev || stat.ino !== entry.identity.ino) {
+                    throw fileBusy(REVALIDATE_BUSY_MESSAGE);
+                }
+                continue;
+            }
+            assertSameTreeIdentity(entry.identity, stat, REVALIDATE_BUSY_MESSAGE);
+        }
+        const refreshed = await snapshotTree(snapshot.rootPath, { signal });
+        if (refreshed.entryCount !== snapshot.entryCount)
+            throw fileBusy(REVALIDATE_BUSY_MESSAGE);
+        for (let index = 0; index < refreshed.entries.length; index++) {
+            if (refreshed.entries[index].path !== snapshot.entries[index].path ||
+                refreshed.entries[index].kind !== snapshot.entries[index].kind) {
+                throw fileBusy(REVALIDATE_BUSY_MESSAGE);
+            }
+        }
+    }
+    catch (error) {
+        finishRevalidate(error);
+    }
+}
+//# sourceMappingURL=tree.js.map

package/dist/tar-protocol/tree.js.map

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

package/dist/tar-protocol/ustar.d.ts

@@ -0,0 +1,36 @@
+export declare const TAR_BLOCK_BYTES = 512;
+export declare const MAX_USTAR_FILE_BYTES = 8589934591;
+/**
+ * Every USTAR metadata field is pinned to a constant so that the same content
+ * always frames to the same bytes. The transfer ID commits to these values, so
+ * changing one changes every transfer ID.
+ */
+export declare const TAR_MODE = 420;
+export declare const TAR_DIRECTORY_MODE = 493;
+export declare const TAR_UID = 0;
+export declare const TAR_GID = 0;
+export declare const TAR_MTIME_MS = 0;
+export declare const TAR_UNAME = "";
+export declare const TAR_GNAME = "";
+export declare function assertUstarFileSize(size: unknown): asserts size is number;
+export declare function deterministicTarSize(fileSize: number): number;
+/**
+ * Builds the single canonical USTAR header block for `name`/`fileSize`.
+ *
+ * Both the send path and receive validator use this exact block. A test also
+ * pins it byte-for-byte against tar-stream's portable USTAR representation.
+ */
+export declare function canonicalUstarHeader(name: string, fileSize: number): Buffer;
+/**
+ * Builds the canonical USTAR header block for one tree entry.
+ *
+ * `storedName` is the exact TAR name field: the relative path for a file and
+ * the relative path plus `/` for a directory. For a one-component file name
+ * this returns exactly `canonicalUstarHeader(storedName, size)`.
+ */
+export declare function canonicalUstarTreeHeader(storedName: string, kind: 'file' | 'directory', size: number): Buffer;
+/** The exact deterministic archive length for an ordered canonical entry list. */
+export declare function deterministicTreeTarSize(entries: readonly {
+    kind: 'file' | 'directory';
+    size: number;
+}[]): number;

package/dist/tar-protocol/ustar.js

@@ -0,0 +1,167 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAR_GNAME = exports.TAR_UNAME = exports.TAR_MTIME_MS = exports.TAR_GID = exports.TAR_UID = exports.TAR_DIRECTORY_MODE = exports.TAR_MODE = exports.MAX_USTAR_FILE_BYTES = exports.TAR_BLOCK_BYTES = void 0;
+exports.assertUstarFileSize = assertUstarFileSize;
+exports.deterministicTarSize = deterministicTarSize;
+exports.canonicalUstarHeader = canonicalUstarHeader;
+exports.canonicalUstarTreeHeader = canonicalUstarTreeHeader;
+exports.deterministicTreeTarSize = deterministicTreeTarSize;
+const b4a_1 = __importDefault(require("b4a"));
+const errors_js_1 = require("../errors.js");
+const tree_path_js_1 = require("./tree-path.js");
+exports.TAR_BLOCK_BYTES = 512;
+exports.MAX_USTAR_FILE_BYTES = 0o77777777777;
+const TAR_END_BYTES = 2 * exports.TAR_BLOCK_BYTES;
+/**
+ * Every USTAR metadata field is pinned to a constant so that the same content
+ * always frames to the same bytes. The transfer ID commits to these values, so
+ * changing one changes every transfer ID.
+ */
+exports.TAR_MODE = 0o644;
+exports.TAR_DIRECTORY_MODE = 0o755;
+exports.TAR_UID = 0;
+exports.TAR_GID = 0;
+exports.TAR_MTIME_MS = 0;
+exports.TAR_UNAME = '';
+exports.TAR_GNAME = '';
+function invalidSize() {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Invalid deterministic TAR file size');
+}
+function assertUstarFileSize(size) {
+    if (typeof size !== 'number' ||
+        !Number.isSafeInteger(size) ||
+        size < 0 ||
+        size > exports.MAX_USTAR_FILE_BYTES) {
+        throw invalidSize();
+    }
+}
+function deterministicTarSize(fileSize) {
+    assertUstarFileSize(fileSize);
+    const padding = (exports.TAR_BLOCK_BYTES - (fileSize % exports.TAR_BLOCK_BYTES)) % exports.TAR_BLOCK_BYTES;
+    const total = exports.TAR_BLOCK_BYTES + fileSize + padding + TAR_END_BYTES;
+    if (!Number.isSafeInteger(total))
+        throw invalidSize();
+    return total;
+}
+function assertCanonicalTreeStoredName(storedName, kind) {
+    try {
+        (0, tree_path_js_1.assertTreeStoredName)(storedName, kind);
+    }
+    catch (error) {
+        if (error instanceof errors_js_1.SwarmDeployError && error.code === errors_js_1.ERRORS.INVALID_FILENAME) {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Invalid canonical TAR name');
+        }
+        throw error;
+    }
+}
+function octal(value, digits) {
+    const encoded = value.toString(8);
+    if (encoded.length > digits) {
+        throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Canonical TAR field overflow');
+    }
+    return b4a_1.default.from(`${'0'.repeat(digits - encoded.length)}${encoded} `);
+}
+/**
+ * Builds the single canonical USTAR header block for `name`/`fileSize`.
+ *
+ * Both the send path and receive validator use this exact block. A test also
+ * pins it byte-for-byte against tar-stream's portable USTAR representation.
+ */
+function canonicalUstarHeader(name, fileSize) {
+    assertUstarFileSize(fileSize);
+    const header = b4a_1.default.alloc(exports.TAR_BLOCK_BYTES);
+    const set = (offset, value) => {
+        header.set(value, offset);
+    };
+    set(0, b4a_1.default.from(name));
+    set(100, octal(exports.TAR_MODE, 6));
+    set(108, octal(exports.TAR_UID, 6));
+    set(116, octal(exports.TAR_GID, 6));
+    set(124, octal(fileSize, 11));
+    set(136, octal(exports.TAR_MTIME_MS / 1000, 11));
+    header[156] = 48;
+    set(257, b4a_1.default.from([0x75, 0x73, 0x74, 0x61, 0x72, 0]));
+    set(263, b4a_1.default.from('00'));
+    if (exports.TAR_UNAME)
+        set(265, b4a_1.default.from(exports.TAR_UNAME));
+    if (exports.TAR_GNAME)
+        set(297, b4a_1.default.from(exports.TAR_GNAME));
+    set(329, octal(0, 6));
+    set(337, octal(0, 6));
+    let checksum = 8 * 32;
+    for (let index = 0; index < 148; index++)
+        checksum += header[index];
+    for (let index = 156; index < exports.TAR_BLOCK_BYTES; index++)
+        checksum += header[index];
+    set(148, octal(checksum, 6));
+    return header;
+}
+/**
+ * Builds the canonical USTAR header block for one tree entry.
+ *
+ * `storedName` is the exact TAR name field: the relative path for a file and
+ * the relative path plus `/` for a directory. For a one-component file name
+ * this returns exactly `canonicalUstarHeader(storedName, size)`.
+ */
+function canonicalUstarTreeHeader(storedName, kind, size) {
+    if (kind !== 'file' && kind !== 'directory') {
+        throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Invalid canonical TAR entry kind');
+    }
+    if (kind === 'directory' && size !== 0) {
+        throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Invalid canonical TAR directory size');
+    }
+    assertUstarFileSize(size);
+    assertCanonicalTreeStoredName(storedName, kind);
+    if (kind === 'file')
+        return canonicalUstarHeader(storedName, size);
+    const encoded = b4a_1.default.from(storedName);
+    const header = b4a_1.default.alloc(exports.TAR_BLOCK_BYTES);
+    const set = (offset, value) => {
+        header.set(value, offset);
+    };
+    set(0, encoded);
+    set(100, octal(exports.TAR_DIRECTORY_MODE, 6));
+    set(108, octal(exports.TAR_UID, 6));
+    set(116, octal(exports.TAR_GID, 6));
+    set(124, octal(size, 11));
+    set(136, octal(exports.TAR_MTIME_MS / 1000, 11));
+    header[156] = 53;
+    set(257, b4a_1.default.from([0x75, 0x73, 0x74, 0x61, 0x72, 0]));
+    set(263, b4a_1.default.from('00'));
+    if (exports.TAR_UNAME)
+        set(265, b4a_1.default.from(exports.TAR_UNAME));
+    if (exports.TAR_GNAME)
+        set(297, b4a_1.default.from(exports.TAR_GNAME));
+    set(329, octal(0, 6));
+    set(337, octal(0, 6));
+    let checksum = 8 * 32;
+    for (let index = 0; index < 148; index++)
+        checksum += header[index];
+    for (let index = 156; index < exports.TAR_BLOCK_BYTES; index++)
+        checksum += header[index];
+    set(148, octal(checksum, 6));
+    return header;
+}
+/** The exact deterministic archive length for an ordered canonical entry list. */
+function deterministicTreeTarSize(entries) {
+    let total = TAR_END_BYTES;
+    for (const entry of entries) {
+        if (entry.kind !== 'file' && entry.kind !== 'directory') {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Invalid canonical TAR entry kind');
+        }
+        if (entry.kind === 'directory' && entry.size !== 0) {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Invalid canonical TAR directory size');
+        }
+        assertUstarFileSize(entry.size);
+        const payload = entry.kind === 'directory' ? 0 : entry.size;
+        const padding = (exports.TAR_BLOCK_BYTES - (payload % exports.TAR_BLOCK_BYTES)) % exports.TAR_BLOCK_BYTES;
+        total += exports.TAR_BLOCK_BYTES + payload + padding;
+        if (!Number.isSafeInteger(total))
+            throw invalidSize();
+    }
+    return total;
+}
+//# sourceMappingURL=ustar.js.map

package/dist/tar-protocol/ustar.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+import type { ErrorCode } from './errors.js';
+/**
+ * A byte buffer accepted by identity, transport, and file APIs. Values that
+ * represent keys, digests, or transfer IDs must be exactly 32 bytes.
+ */
+export type Binary = Buffer;
+/** Whether a managed artifact is one regular file or one recursive directory. */
+export type ArtifactKind = 'file' | 'directory';
+/** Byte input accepted by APIs that normalize values to a b4a/Node Buffer. */
+export type BinaryInput = Uint8Array;
+/** A 32-byte seed used to derive a HyperDHT identity. */
+export type Seed = Binary;
+/** A 32-byte buffer or canonical lowercase 64-character hex seed string. */
+export type SeedInput = BinaryInput | string;
+/** A 32-byte HyperDHT public key. */
+export type PublicKey = Binary;
+/** A 32-byte public key accepted by identity, constructor, and allowlist APIs. */
+export type PublicKeyInput = BinaryInput;
+/** A SHA-256 digest. */
+export type Digest = Binary;
+/** A SHA-256-derived transfer identifier. */
+export type TransferId = Binary;
+export interface KeyPair {
+    publicKey: PublicKey;
+    secretKey: Binary;
+}
+export interface Logger {
+    info?(message: string, details?: Record<string, unknown>): void;
+    warn?(message: string, details?: Record<string, unknown>): void;
+    error?(message: string, details?: Record<string, unknown>): void;
+}
+export interface Scheduler {
+    setTimeout(callback: () => void, delay: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface ServerScheduler extends Scheduler {
+    setInterval(callback: () => void, delay: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+export interface Clock {
+    now(): number;
+}
+export interface FingerprintEvent {
+    /** First 12 lowercase hexadecimal characters of SHA-256(public key). */
+    fingerprint: string;
+}
+export interface AuthenticationEvent extends FingerprintEvent {
+    status: 'accepted' | 'rejected';
+    reason?: ErrorCode;
+}
+export interface TransferEvent {
+    /** A 12-character SHA-256 fingerprint of the transfer ID. */
+    transfer: string;
+    name: string;
+    kind: ArtifactKind;
+    size: number;
+}
+export interface TransferLifecycleEvent extends TransferEvent {
+    status: 'started' | 'succeeded' | 'failed';
+    reason?: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validation.d.ts

@@ -0,0 +1,4 @@
+export declare function isFixed32(value: unknown): value is Uint8Array;
+export declare function assertFixed32(value: unknown, name: string): asserts value is Uint8Array;
+export declare function assertSafeUint(value: unknown, name: string): asserts value is number;
+export declare function assertPositiveSafeUint(value: unknown, name: string): asserts value is number;

package/dist/validation.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFixed32 = isFixed32;
+exports.assertFixed32 = assertFixed32;
+exports.assertSafeUint = assertSafeUint;
+exports.assertPositiveSafeUint = assertPositiveSafeUint;
+const errors_js_1 = require("./errors.js");
+function isFixed32(value) {
+    return value instanceof Uint8Array && value.byteLength === 32;
+}
+function assertFixed32(value, name) {
+    if (!isFixed32(value)) {
+        throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, `Invalid ${name}`);
+    }
+}
+function assertSafeUint(value, name) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, `Invalid ${name}`);
+    }
+}
+function assertPositiveSafeUint(value, name) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, `Invalid ${name}`);
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":";;;;;;AAAA,2CAAsD;AAEtD,mBAA0B,KAAc;IACtC,OAAO,KAAK,YAAY,UAAU,IAAI,KAAK,CAAC,UAAU,KAAK,EAAE,CAAA;AAC/D,CAAC;AAED,uBAA8B,KAAc,EAAE,IAAY;IACxD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,4BAAgB,CAAC,kBAAM,CAAC,gBAAgB,EAAE,WAAW,IAAI,EAAE,CAAC,CAAA;IACxE,CAAC;AACH,CAAC;AAED,wBAA+B,KAAc,EAAE,IAAY;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,4BAAgB,CAAC,kBAAM,CAAC,gBAAgB,EAAE,WAAW,IAAI,EAAE,CAAC,CAAA;IACxE,CAAC;AACH,CAAC;AAED,gCAAuC,KAAc,EAAE,IAAY;IACjE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC5E,MAAM,IAAI,4BAAgB,CAAC,kBAAM,CAAC,gBAAgB,EAAE,WAAW,IAAI,EAAE,CAAC,CAAA;IACxE,CAAC;AACH,CAAC"}