@hwip/cli 0.0.1 → 0.1.1

package/dist/lan-receiver.js

@@ -0,0 +1,510 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startLanReceiver = exports.createConnectionLimiter = exports.LAN_BODY_IDLE_MS = exports.LAN_MAX_CONNECTIONS_PER_IP = exports.LAN_MAX_CONNECTIONS = exports.LAN_LANDED_IV = exports.LAN_MAX_IN_FLIGHT = exports.LAN_MAX_BODY_BYTES = exports.LAN_DISK_RESERVE_BYTES = exports.LAN_LARGE_CAPABILITY = exports.LAN_MAX_FILE_BYTES = void 0;
+const node_http_1 = require("node:http");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_stream_1 = require("node:stream");
+const promises_1 = require("node:stream/promises");
+const downloads_js_1 = require("./downloads.js");
+const file_crypto_js_1 = require("./file-crypto.js");
+const lan_auth_js_1 = require("./lan-auth.js");
+const private_files_js_1 = require("./private-files.js");
+/**
+ * 16 GiB — a long phone video in 4K fits — and the tag each piece of a file
+ * that size sealed in chunks adds. No plan's limit applies here: the bytes
+ * never reach the relay, and only a device of this account gets past the MAC.
+ * What bounds it is the disk (`freeBytes`). A sender sends a file over the
+ * relay's ceiling here only to a listener that lists `LAN_LARGE_CAPABILITY`;
+ * one from before it takes 1 GiB.
+ */
+exports.LAN_MAX_FILE_BYTES = 16 * 1024 ** 3;
+/** What a listener tells senders when it takes `LAN_MAX_FILE_BYTES` over LAN (`capabilities` on its device record). */
+exports.LAN_LARGE_CAPABILITY = 'lan-large-v1';
+/** Room left on the landing volume after a file, so a transfer never fills the disk to its last byte. */
+exports.LAN_DISK_RESERVE_BYTES = 1024 ** 3;
+exports.LAN_MAX_BODY_BYTES = exports.LAN_MAX_FILE_BYTES + (exports.LAN_MAX_FILE_BYTES / file_crypto_js_1.FILE_CHUNK_BYTES) * file_crypto_js_1.GCM_TAG_BYTES;
+exports.LAN_MAX_IN_FLIGHT = 2;
+/**
+ * Beside a landed file, the iv it was sealed under (base64, as the meta gave
+ * it). The push record that claims the file comes from the relay; this is what
+ * the claim holds it against. A leading dot: no landed file can have this name
+ * (`safeFileName` strips them).
+ */
+exports.LAN_LANDED_IV = '.iv';
+/** The sockets are the daemon's file descriptors, shared with the relay
+ *  WebSocket: a LAN flood may exhaust local transfer (sends fall back to the
+ *  relay), never the daemon. */
+exports.LAN_MAX_CONNECTIONS = 64;
+/**
+ * Sockets one remote address may hold. The pool above is shared by the whole
+ * LAN, and a host that opens 64 sockets and sends nothing holds every slot for
+ * the 5 s `headersTimeout` — and reopens them — which locks every real sender
+ * out of the LAN path (they fall back to the relay, nothing worse). A real
+ * sender needs a ping and at most `LAN_MAX_IN_FLIGHT` uploads, so a handful per
+ * address is plenty, and it takes this many remote addresses to fill the pool —
+ * a host with several addresses on the subnet counts as several.
+ *
+ * Not "bind only the published address": the attacker is on the same LAN and
+ * reaches that address as well as any other, so a narrower bind removes nothing
+ * from this problem — it only hides the port from other interfaces (a VPN, a
+ * docker bridge). It also costs: the publisher re-picks the address every
+ * minute as the machine changes networks, and the port is what it publishes, so
+ * a socket bound to one address would have to be rebound, and republished under
+ * a new port, on every move.
+ */
+exports.LAN_MAX_CONNECTIONS_PER_IP = 8;
+exports.LAN_BODY_IDLE_MS = 60_000;
+/** Derived key sets kept; the account has a handful of devices. */
+const KEY_CACHE_MAX = 64;
+/** After a pre-body refusal, how long the client may keep sending before the socket goes. */
+const REFUSE_GRACE_MS = 1_000;
+/** One line per refused check per window: anyone on the network can ask. */
+const REFUSAL_LOG_WINDOW_MS = 10 * 60_000;
+const asMeta = (parsed) => {
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const m = parsed;
+    const isStr = (v) => typeof v === 'string' && v.length > 0;
+    if (!isStr(m.fileName) || !isStr(m.iv) || !isStr(m.transferId))
+        return null;
+    if (typeof m.deviceKeyMap !== 'object' || m.deviceKeyMap === null)
+        return null;
+    const deviceKeyMap = {};
+    for (const [k, v] of Object.entries(m.deviceKeyMap)) {
+        if (typeof v !== 'string')
+            return null;
+        deviceKeyMap[k] = v;
+    }
+    const said = (0, file_crypto_js_1.chunkOf)(m.chunk);
+    if (!said.ok)
+        return null;
+    if (Buffer.from(m.iv, 'base64').length !== (said.chunk === undefined ? file_crypto_js_1.GCM_IV_BYTES : file_crypto_js_1.FILE_CHUNK_PREFIX_BYTES))
+        return null;
+    return {
+        fileName: m.fileName,
+        fileType: isStr(m.fileType) ? m.fileType : undefined,
+        fileSize: typeof m.fileSize === 'number' ? m.fileSize : undefined,
+        iv: m.iv,
+        deviceKeyMap,
+        transferId: m.transferId,
+        chunk: said.chunk,
+    };
+};
+const end = (res, status, body) => {
+    res.statusCode = status;
+    if (body) {
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify(body));
+    }
+    else {
+        res.end();
+    }
+};
+/**
+ * Refuse before the body: answer, then discard what the client is still
+ * writing for a short grace; a body still arriving after it takes the
+ * socket down. A client mid-write whose bytes stop being read — or whose
+ * socket is closed under it, which is what `Connection: close` does —
+ * sees a reset, not the 413 it needs to fall back on. The grace bounds
+ * what that costs: never the whole gigabyte. A body that finishes inside
+ * it leaves the connection usable.
+ */
+const refuse = (req, res, status) => {
+    res.statusCode = status;
+    // A refused peer does not get to keep its socket: left alive, one small
+    // request per keep-alive window holds a connection slot forever with no
+    // reconnect, and the per-address cap would only slow that down. Only when
+    // there is no body still arriving — closing under a client mid-write is the
+    // reset the grace below exists to avoid. A real sender's refusals (409, 413,
+    // 503) carry a body and keep their connection as before.
+    if (req.headers['content-length'] === undefined && req.headers['transfer-encoding'] === undefined) {
+        res.setHeader('Connection', 'close');
+    }
+    req.resume();
+    res.end(() => {
+        if (req.complete)
+            return;
+        const timer = setTimeout(() => req.socket.destroy(), REFUSE_GRACE_MS);
+        timer.unref();
+        const clear = () => clearTimeout(timer);
+        req.once('end', clear);
+        req.socket.once('close', clear);
+    });
+};
+/**
+ * Open-socket count per remote address. `admit` before the socket is used,
+ * `release` when it closes; an address with no sockets is forgotten, so the map
+ * is as large as the number of hosts connected right now and never larger.
+ */
+const createConnectionLimiter = (max) => {
+    const open = new Map();
+    return {
+        admit: (address) => {
+            const count = open.get(address) ?? 0;
+            if (count >= max)
+                return false;
+            open.set(address, count + 1);
+            return true;
+        },
+        release: (address) => {
+            const count = open.get(address);
+            if (count === undefined)
+                return;
+            if (count <= 1)
+                open.delete(address);
+            else
+                open.set(address, count - 1);
+        },
+        tracked: () => open.size,
+    };
+};
+exports.createConnectionLimiter = createConnectionLimiter;
+const startLanReceiver = (opts) => new Promise((resolve, reject) => {
+    const now = opts.now ?? (() => Date.now());
+    const maxBody = opts.maxBodyBytes ?? exports.LAN_MAX_BODY_BYTES;
+    const freeBytes = opts.freeBytes ?? ((dir) => {
+        const stats = (0, node_fs_1.statfsSync)(dir);
+        return stats.bavail * stats.bsize;
+    });
+    const maxInFlight = opts.maxInFlight ?? exports.LAN_MAX_IN_FLIGHT;
+    const idleMs = opts.idleTimeoutMs ?? exports.LAN_BODY_IDLE_MS;
+    const nonces = opts.nonces ?? (0, lan_auth_js_1.createNonceRegistry)();
+    // sender public key → derived keys. The secret is static per pair, and
+    // a P-256 derive per request would be the cheapest CPU an outsider
+    // who sniffed a device id could buy. With this cache and the device
+    // directory's miss brake, the pre-MAC work anyone can buy is a header
+    // parse and two map lookups — nothing worth rationing, so there is no
+    // request budget for an outsider to drain and lock real senders out.
+    const keyCache = new Map();
+    let inFlight = 0;
+    // Transfer ids with an upload in progress: the 409 must hold from the
+    // first byte, not from when the directory appears.
+    const active = new Set();
+    const keysFor = async (publicKey) => {
+        const hit = keyCache.get(publicKey);
+        if (hit)
+            return hit;
+        const keys = (0, lan_auth_js_1.deriveLanKeys)(await opts.deriveSharedSecret(publicKey));
+        if (keyCache.size >= KEY_CACHE_MAX)
+            keyCache.delete(keyCache.keys().next().value ?? '');
+        keyCache.set(publicKey, keys);
+        return keys;
+    };
+    /** Spend a nonce whose MAC held. A refusal here is a replay race or a
+     *  sender over its quota — the peer sees the same 401, the log says which. */
+    const commitNonce = (sender, nonce) => {
+        if (nonces.commit(sender, nonce, now()))
+            return true;
+        opts.log(`local transfer: nonce refused for ${sender} (a replay, or the sender is over its quota)`);
+        return false;
+    };
+    /**
+     * The 401 stays one empty answer for the peer; the log says which check
+     * failed (C67) — a phone whose clock is off by minutes otherwise never
+     * reaches this machine over LAN and nobody can see why. Anyone can
+     * trigger these, and every sender id here is the peer's unproven
+     * claim, so the limit is per check: one line per check per
+     * REFUSAL_LOG_WINDOW_MS, naming the first sender and how many more
+     * were refused since.
+     */
+    const refusalLogged = new Map();
+    const logRefusal = (check, detail, sender) => {
+        const at = now();
+        const last = refusalLogged.get(check);
+        if (last && at - last.at < REFUSAL_LOG_WINDOW_MS) {
+            last.suppressed++;
+            return;
+        }
+        refusalLogged.set(check, { at, suppressed: 0 });
+        // The id is the peer's unauthenticated claim: printable, short.
+        const who = sender === null ? 'an unnamed sender' : sender.replace(/[^\w.-]/g, '?').slice(0, 64);
+        const more = last?.suppressed ? ` (${last.suppressed} more since the last line)` : '';
+        opts.log(`local transfer: refused ${who} — ${detail ?? check} (401)${more}`);
+    };
+    /**
+     * Everything an outsider can reach ends here with one answer: 401,
+     * empty. Resolves the sender's keys once the headers are well formed,
+     * fresh, unreplayed, and name a device of this account with a key we
+     * can derive against; the MAC itself is the caller's, because on an
+     * upload it binds a body that has not arrived yet.
+     */
+    const authenticate = async (req, res) => {
+        const fields = (0, lan_auth_js_1.parseLanAuthHeaders)(req.headers);
+        if (!fields) {
+            logRefusal('malformed auth headers', null, null);
+            refuse(req, res, 401);
+            return null;
+        }
+        const sender = fields.senderDeviceId;
+        if (!(0, lan_auth_js_1.isTimestampFresh)(fields.timestamp, now())) {
+            const skewS = Math.round((fields.timestamp - now()) / 1000);
+            logRefusal('clock', `its clock is ${Math.abs(skewS)} s ${skewS < 0 ? 'behind' : 'ahead of'} this machine's (limit ${lan_auth_js_1.LAN_CLOCK_SKEW_MS / 1000} s)`, sender);
+            refuse(req, res, 401);
+            return null;
+        }
+        if (nonces.seen(sender, fields.nonce, now())) {
+            logRefusal('a replayed request', null, sender);
+            refuse(req, res, 401);
+            return null;
+        }
+        let senderPublicKey = null;
+        try {
+            senderPublicKey = await opts.lookupSenderPublicKey(fields.senderDeviceId);
+        }
+        catch (err) {
+            opts.log(`local transfer: device lookup failed — ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!senderPublicKey) {
+            logRefusal('not a device of this account', null, sender);
+            refuse(req, res, 401);
+            return null;
+        }
+        let keys;
+        try {
+            keys = await keysFor(senderPublicKey);
+        }
+        catch {
+            logRefusal('its device key does not import', null, sender);
+            refuse(req, res, 401); // a public key that will not import is not a sender we can trust
+            return null;
+        }
+        return { keys, fields, senderPublicKey };
+    };
+    const ping = async (req, res) => {
+        const auth = await authenticate(req, res);
+        if (!auth)
+            return;
+        const { keys, fields } = auth;
+        const ok = fields.transferId === lan_auth_js_1.LAN_PING_TRANSFER_ID
+            && (0, lan_auth_js_1.verifyLanMac)(keys.macKey, { ...fields, method: 'GET', path: lan_auth_js_1.LAN_PATHS.ping, bodySha256: lan_auth_js_1.EMPTY_BODY_SHA256 }, fields.mac)
+            && commitNonce(fields.senderDeviceId, fields.nonce);
+        if (!ok) {
+            logRefusal('the ping does not verify', null, fields.senderDeviceId);
+            refuse(req, res, 401);
+            return;
+        }
+        res.setHeader(lan_auth_js_1.LAN_HEADERS.receipt, (0, lan_auth_js_1.signLanReceipt)(keys.macKey, fields.mac));
+        end(res, 200, { deviceId: opts.deviceId() });
+    };
+    const upload = async (req, res) => {
+        const auth = await authenticate(req, res);
+        if (!auth)
+            return;
+        const { keys, fields, senderPublicKey } = auth;
+        // The sealed meta only opens under the real sender's key: this is
+        // where an impersonator with a genuine device id stops, at the
+        // same 401 as everyone else.
+        const opened = (0, lan_auth_js_1.openMeta)(keys.metaKey, req.headers[lan_auth_js_1.LAN_HEADERS.meta]);
+        if (opened === null) {
+            logRefusal('the upload header does not open under its key', null, fields.senderDeviceId);
+            refuse(req, res, 401);
+            return;
+        }
+        // From here the peer is a device of this account: the answers may
+        // say something about this machine. Still all before the body.
+        const meta = asMeta(opened);
+        if (!meta || meta.transferId !== fields.transferId) {
+            refuse(req, res, 400);
+            return;
+        }
+        if (active.has(meta.transferId)) {
+            refuse(req, res, 409);
+            return;
+        }
+        if (inFlight >= maxInFlight) {
+            refuse(req, res, 503);
+            return;
+        }
+        inFlight++;
+        active.add(meta.transferId);
+        const reserved = meta.transferId;
+        try {
+            const lengthHeader = req.headers['content-length'];
+            if (lengthHeader === undefined || req.headers['transfer-encoding'] !== undefined) {
+                refuse(req, res, 411);
+                return;
+            }
+            const declared = Number(lengthHeader);
+            if (!Number.isInteger(declared) || declared < 0) {
+                refuse(req, res, 400);
+                return;
+            }
+            if (declared > maxBody) {
+                refuse(req, res, 413);
+                return;
+            }
+            const slot = meta.deviceKeyMap[opts.deviceId()];
+            if (!slot) {
+                refuse(req, res, 400);
+                return;
+            }
+            const transferDir = (0, node_path_1.join)(opts.landingDir(), meta.transferId);
+            let rawKey;
+            try {
+                rawKey = await opts.unwrapFileKey(slot, senderPublicKey);
+            }
+            catch {
+                refuse(req, res, 400); // wrapped, but not for this device's key
+                return;
+            }
+            try {
+                // The parent on demand (a fresh install has no ~/.hwip/attachments/lan);
+                // the transfer dir itself exclusively, so a second upload is 409.
+                (0, private_files_js_1.mkdirHandedBack)(opts.landingDir());
+                // 507 before a byte is written: the file and the reserve must fit, or the sender goes by the relay.
+                if (freeBytes(opts.landingDir()) < declared + exports.LAN_DISK_RESERVE_BYTES) {
+                    opts.log(`local transfer: refused ${declared}B — not enough free disk (507)`);
+                    refuse(req, res, 507);
+                    return;
+                }
+                (0, private_files_js_1.mkdirExclusiveHandedBack)(transferDir);
+            }
+            catch (err) {
+                if (err.code === 'EEXIST') {
+                    refuse(req, res, 409);
+                    return;
+                }
+                throw err;
+            }
+            const hasher = (0, lan_auth_js_1.createBodyHasher)();
+            let received = 0;
+            const tee = new node_stream_1.Transform({
+                transform(chunk, _enc, done) {
+                    received += chunk.length;
+                    if (received > declared) {
+                        done(new Error('body exceeds Content-Length'));
+                        return;
+                    }
+                    hasher.update(chunk);
+                    done(null, chunk);
+                },
+            });
+            // `pipeline`, not `pipe`: a client that drops mid-body must error
+            // the tee, or the save waits for bytes that never come and the
+            // half-written transfer dir stays until the socket times out.
+            void (0, promises_1.pipeline)(req, tee).catch(() => undefined);
+            req.setTimeout(idleMs, () => req.destroy(new Error(`no bytes for ${idleMs} ms`)));
+            const dest = (0, node_path_1.join)(transferDir, (0, downloads_js_1.safeFileName)(meta.fileName));
+            try {
+                const saved = await (0, file_crypto_js_1.saveStream)(tee, () => dest, { rawKey, iv: Buffer.from(meta.iv, 'base64'), chunk: meta.chunk });
+                // Everything is on disk, decrypted and tag-checked; now the
+                // MAC that binds those bytes to this sender and this moment,
+                // and the nonce is spent only for a MAC that held.
+                const bound = { ...fields, method: 'POST', path: lan_auth_js_1.LAN_PATHS.upload, bodySha256: hasher.digestHex() };
+                const ok = received === declared
+                    && (0, lan_auth_js_1.verifyLanMac)(keys.macKey, bound, fields.mac)
+                    && commitNonce(fields.senderDeviceId, fields.nonce);
+                if (!ok) {
+                    (0, node_fs_1.rmSync)(transferDir, { recursive: true, force: true });
+                    logRefusal(received === declared ? 'the upload does not verify' : 'the upload is shorter or longer than declared', null, fields.senderDeviceId);
+                    end(res, 401);
+                    return;
+                }
+                (0, node_fs_1.writeFileSync)((0, node_path_1.join)(transferDir, exports.LAN_LANDED_IV), meta.iv, { mode: 0o600 });
+                opts.log(`local transfer: received "${meta.fileName}" (${saved.bytes}B) from ${fields.senderDeviceId} as ${meta.transferId}`);
+                res.setHeader(lan_auth_js_1.LAN_HEADERS.receipt, (0, lan_auth_js_1.signLanReceipt)(keys.macKey, fields.mac));
+                end(res, 201, { transferId: meta.transferId });
+            }
+            catch (err) {
+                (0, node_fs_1.rmSync)(transferDir, { recursive: true, force: true });
+                opts.log(`local transfer: upload ${meta.transferId} failed — ${err instanceof Error ? err.message : String(err)}`);
+                if (!res.headersSent)
+                    end(res, 400);
+                else
+                    res.destroy();
+            }
+        }
+        finally {
+            inFlight--;
+            active.delete(reserved);
+        }
+    };
+    const route = (req, res) => {
+        const url = req.url ?? '';
+        const handler = req.method === 'GET' && url === lan_auth_js_1.LAN_PATHS.ping ? ping
+            : req.method === 'POST' && url === lan_auth_js_1.LAN_PATHS.upload ? upload
+                : null;
+        if (!handler) {
+            refuse(req, res, 404);
+            return;
+        }
+        handler(req, res).catch((err) => {
+            opts.log(`local transfer: request failed — ${err instanceof Error ? err.message : String(err)}`);
+            if (!res.headersSent)
+                refuse(req, res, 500);
+            else
+                res.destroy();
+        });
+    };
+    // A client that opens a socket and never sends headers must not hold
+    // it: Node enforces `headersTimeout` only on each connections check
+    // (30 s by default), so the check runs every second for the 5 s to be
+    // real. The body has no wall-clock budget — a 16 GiB file on Wi-Fi
+    // takes what it takes — only the idle timeout set per upload above.
+    const server = (0, node_http_1.createServer)({ connectionsCheckingInterval: 1_000 }, route);
+    server.headersTimeout = 5_000;
+    server.requestTimeout = 0;
+    server.maxConnections = opts.maxConnections ?? exports.LAN_MAX_CONNECTIONS;
+    const perIp = opts.maxConnectionsPerIp ?? exports.LAN_MAX_CONNECTIONS_PER_IP;
+    const limiter = (0, exports.createConnectionLimiter)(perIp);
+    let lastCapLogAt = -Infinity;
+    // Before Node's own connection handler, so a socket over its address's
+    // cap is destroyed before anything is read from it (Node still sets it up
+    // and tears it down on the close that follows). `maxConnections` is
+    // checked earlier still, at accept — that one is the global bound.
+    server.prependListener('connection', (socket) => {
+        // No address means the peer is already gone: nothing to count.
+        const address = socket.remoteAddress;
+        if (!address)
+            return;
+        if (!limiter.admit(address)) {
+            socket.destroy();
+            // Anyone on the network can cause this line, so one per window.
+            const at = now();
+            if (at - lastCapLogAt >= REFUSAL_LOG_WINDOW_MS) {
+                lastCapLogAt = at;
+                opts.log(`local transfer: dropped a connection from ${address} — it already holds ${perIp} open connections`);
+            }
+            return;
+        }
+        socket.once('close', () => limiter.release(address));
+    });
+    let listening = false;
+    // Stays attached for the server's whole life: an `error` with no
+    // listener is an uncaught throw, and this socket must never be the
+    // thing that takes the relay-serving daemon down with it.
+    server.on('error', (err) => {
+        if (!listening) {
+            reject(err);
+            return;
+        }
+        opts.log(`local transfer: server error — ${err.message}`);
+        opts.onError?.(err);
+    });
+    server.listen(0, '0.0.0.0', () => {
+        listening = true;
+        const address = server.address();
+        if (typeof address !== 'object' || address === null) {
+            // Cannot happen after a TCP listen; if it does, publishing
+            // port 0 would only be refused by the server, silently.
+            server.close();
+            reject(new Error('bound socket reported no address'));
+            return;
+        }
+        const port = address.port;
+        opts.log(`local transfer: listening on 0.0.0.0:${port}`);
+        let closed = null;
+        const stop = () => {
+            if (closed)
+                return closed;
+            closed = new Promise((done) => {
+                server.close(() => done());
+                server.closeAllConnections();
+            });
+            return closed;
+        };
+        resolve({ port, stop });
+    });
+});
+exports.startLanReceiver = startLanReceiver;

package/dist/lan-sender.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Local transfer (ADR-0013) — the sending half; the contract is `lan-auth.ts`.
+ * Nothing calls it yet outside tests (`@hwip/mcp-server` has no copy; its
+ * `hwip_file` always goes by relay). The caller that wires it in must send
+ * to a published `lan` host (a private IPv4, see `isPrivateIpv4`) without
+ * the proxy: see `fetchFn` and backlog C78.
+ *
+ * A file already sealed for its recipients (`encryptFileForDevices`) goes
+ * straight to the one target device when that device says, in the device
+ * list the send already fetched, that it can be reached: a registered key,
+ * a published `lan` endpoint, online. Everything here answers
+ * `{ delivered: false, reason }` rather than throwing — the caller's relay
+ * path is the fallback for every failure. A device that is not there costs
+ * the ping timeout; one that answers the ping and then fails the upload
+ * costs up to the upload budget.
+ *
+ * What counts as delivered is a receipt the sender can check, not a status
+ * code: see `signLanReceipt`. A 201 without one is treated as not delivered,
+ * and the file goes by relay.
+ */
+export interface LanDeviceRecord {
+    deviceId: string;
+    publicKey?: string;
+    isOnline?: boolean;
+    lan?: {
+        host?: unknown;
+        port?: unknown;
+    } | null;
+}
+export interface LanTarget {
+    deviceId: string;
+    publicKey: string;
+    host: string;
+    port: number;
+}
+/**
+ * The device a push can go to directly, or null for the relay: a push with
+ * no single target (a broadcast) never qualifies, nor does a target without
+ * a key, an endpoint, or a live connection.
+ */
+export declare const pickLanTarget: (devices: LanDeviceRecord[], targetDeviceId: string | undefined) => LanTarget | null;
+export interface LanSealedFile {
+    fileName: string;
+    fileType?: string;
+    /** Plaintext size, as the push record reports it. */
+    fileSize: number;
+    iv: string;
+    deviceKeyMap: Record<string, string>;
+    ciphertext: Buffer;
+}
+export interface LanDeliveryInput {
+    target: LanTarget;
+    senderDeviceId: string;
+    /** ECDH secret between this sender's private key and `publicKey` (raw 32 bytes). */
+    deriveSharedSecret: (publicKey: string) => Promise<Buffer>;
+    file: LanSealedFile;
+    fetchFn?: typeof fetch;
+    pingTimeoutMs?: number;
+    /** Upload budget; defaults to `lanUploadTimeoutMs(ciphertext.length)`. */
+    uploadTimeoutMs?: number;
+    /** The caller's own cancellation (a tool call the agent abandoned). */
+    signal?: AbortSignal;
+}
+export type LanDeliveryResult = {
+    delivered: true;
+    transferId: string;
+} | {
+    delivered: false;
+    reason: string;
+};
+/** A receiver that is there answers a ping on the same network in milliseconds. */
+export declare const LAN_PING_TIMEOUT_MS = 1500;
+/** 30 s, plus one second per MiB — slower than any Wi-Fi a LAN transfer is worth trying on. */
+export declare const lanUploadTimeoutMs: (bytes: number) => number;
+export declare const tryLanDelivery: (input: LanDeliveryInput) => Promise<LanDeliveryResult>;
+//# sourceMappingURL=lan-sender.d.ts.map