@hwip/cli 0.0.1 → 0.1.1

package/dist/desktop-notify.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Desktop banner for a file that just landed (ADR-0013): macOS through
+ * `osascript`, Linux through `notify-send` when it is on PATH, otherwise
+ * nothing — the listener log line is the fallback everywhere.
+ *
+ * The banner names the file and the folder it is in, because "a file
+ * arrived" is only useful to someone who can then go and find it. On macOS
+ * a click reveals the file in Finder when `terminal-notifier` is on PATH
+ * (Homebrew; the service's PATH includes /opt/homebrew/bin). `osascript`
+ * cannot attach a click action, so without `terminal-notifier` the text is
+ * the whole UI.
+ *
+ * Best-effort by design. Never throws, never rejects; a failed banner
+ * must not turn a delivered file into an error.
+ */
+export interface DesktopNotification {
+    title: string;
+    body: string;
+    /** Absolute path a click should reveal in the file manager, where the notifier supports it. */
+    reveal?: string;
+}
+export interface DesktopNotifyDeps {
+    platform?: NodeJS.Platform;
+    /** `execFile`-shaped: argv, not a shell string, so nothing is interpolated. */
+    run?: (cmd: string, args: string[]) => Promise<void>;
+    onPath?: (cmd: string) => boolean;
+}
+/**
+ * Show the banner. Resolves true when a command ran and exited cleanly,
+ * false when there is no notifier here or it failed.
+ */
+export declare const notifyDesktop: (note: DesktopNotification, deps?: DesktopNotifyDeps) => Promise<boolean>;
+//# sourceMappingURL=desktop-notify.d.ts.map

package/dist/desktop-notify.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notifyDesktop = void 0;
+const node_child_process_1 = require("node:child_process");
+const agents_js_1 = require("./agents.js");
+const runCommand = (cmd, args) => new Promise((resolve, reject) => {
+    (0, node_child_process_1.execFile)(cmd, args, { timeout: 5_000 }, (err) => (err ? reject(err) : resolve()));
+});
+const commandOnPath = (cmd) => (0, agents_js_1.findOnPath)(cmd) !== null;
+/** POSIX shell single-quoted literal: nothing is special inside it but `'` itself. */
+const shellQuote = (s) => `'${s.split("'").join(`'\\''`)}'`;
+/** AppleScript string literal: only `\` and `"` need escaping inside double quotes. */
+const appleScriptString = (s) => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+/**
+ * Show the banner. Resolves true when a command ran and exited cleanly,
+ * false when there is no notifier here or it failed.
+ */
+const notifyDesktop = async (note, deps = {}) => {
+    const platform = deps.platform ?? process.platform;
+    const run = deps.run ?? runCommand;
+    const onPath = deps.onPath ?? commandOnPath;
+    try {
+        if (platform === 'darwin') {
+            if (note.reveal && onPath('terminal-notifier')) {
+                // `-execute` goes through a shell, so the path is quoted, and
+                // `--` keeps a name starting with '-' from reading as a flag.
+                await run('terminal-notifier', [
+                    '-title', note.title,
+                    '-message', note.body,
+                    '-execute', `open -R -- ${shellQuote(note.reveal)}`,
+                ]);
+                return true;
+            }
+            const script = `display notification ${appleScriptString(note.body)} with title ${appleScriptString(note.title)}`;
+            await run('osascript', ['-e', script]);
+            return true;
+        }
+        if (platform === 'linux' && onPath('notify-send')) {
+            // `--`: a title or body starting with '-' is text, not a flag.
+            await run('notify-send', ['--', note.title, note.body]);
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+};
+exports.notifyDesktop = notifyDesktop;

package/dist/device-directory.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Local transfer (ADR-0013) — who is allowed to send to this machine.
+ *
+ * A LAN upload is authenticated against the sender's *registered* public
+ * key, and the registry is the account's device list (`GET /devices`).
+ * This caches it so a burst of uploads does not become a burst of API
+ * calls, and refreshes on a miss — once per `refreshMinMs` — so a device
+ * registered a moment ago is accepted without waiting a whole TTL. An
+ * unknown id after a fresh fetch is simply not a device of this account.
+ */
+export interface DeviceDirectoryDeps {
+    apiKey: string;
+    baseUrl: string;
+    log: (msg: string) => void;
+    fetchFn?: typeof fetch;
+    now?: () => number;
+    /** Age after which the next lookup refetches even on a hit. */
+    ttlMs?: number;
+    /** Shortest interval between two miss-triggered refetches. */
+    refreshMinMs?: number;
+    timeoutMs?: number;
+}
+/** What the account's device list says about a device besides its key. */
+export interface DeviceInfo {
+    deviceId: string;
+    type?: string;
+    nickname?: string;
+    publicKey?: string;
+}
+export interface DeviceDirectory {
+    publicKeyOf: (deviceId: string) => Promise<string | null>;
+    /** The devices the account lists, refetched when the cache is stale; the last list fetched (empty before any) when the refetch fails. */
+    devices: () => Promise<DeviceInfo[]>;
+}
+export declare const createDeviceDirectory: (deps: DeviceDirectoryDeps) => DeviceDirectory;
+//# sourceMappingURL=device-directory.d.ts.map

package/dist/device-directory.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Local transfer (ADR-0013) — who is allowed to send to this machine.
+ *
+ * A LAN upload is authenticated against the sender's *registered* public
+ * key, and the registry is the account's device list (`GET /devices`).
+ * This caches it so a burst of uploads does not become a burst of API
+ * calls, and refreshes on a miss — once per `refreshMinMs` — so a device
+ * registered a moment ago is accepted without waiting a whole TTL. An
+ * unknown id after a fresh fetch is simply not a device of this account.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeviceDirectory = void 0;
+const api_js_1 = require("./api.js");
+const DEFAULT_TTL_MS = 60_000;
+const DEFAULT_REFRESH_MIN_MS = 10_000;
+const createDeviceDirectory = (deps) => {
+    const fetchFn = deps.fetchFn ?? fetch;
+    const now = deps.now ?? (() => Date.now());
+    const ttlMs = deps.ttlMs ?? DEFAULT_TTL_MS;
+    const refreshMinMs = deps.refreshMinMs ?? DEFAULT_REFRESH_MIN_MS;
+    const url = (0, api_js_1.apiUrl)(deps.baseUrl, '/devices');
+    let keys = new Map();
+    let infos = [];
+    let fetchedAt = -Infinity;
+    /** Last attempt, successful or not — the miss brake counts failures too,
+     *  or an unreachable API is hit on every unknown id. */
+    let triedAt = -Infinity;
+    let inFlight = null;
+    const refresh = () => {
+        if (inFlight)
+            return inFlight;
+        triedAt = now();
+        inFlight = (async () => {
+            const res = await (0, api_js_1.apiFetch)(fetchFn, url, deps.apiKey, deps.timeoutMs ?? 5_000);
+            if (!res.ok)
+                throw new Error(`devices ${res.status}`);
+            const json = (await res.json());
+            const next = new Map();
+            const listed = [];
+            for (const d of json.data ?? []) {
+                if (typeof d.deviceId !== 'string')
+                    continue;
+                const publicKey = typeof d.publicKey === 'string' && d.publicKey.length > 0 ? d.publicKey : undefined;
+                if (publicKey)
+                    next.set(d.deviceId, publicKey);
+                listed.push({
+                    deviceId: d.deviceId,
+                    ...(typeof d.type === 'string' ? { type: d.type } : {}),
+                    ...(typeof d.nickname === 'string' ? { nickname: d.nickname } : {}),
+                    ...(publicKey ? { publicKey } : {}),
+                });
+            }
+            keys = next;
+            infos = listed;
+            fetchedAt = now();
+        })().finally(() => { inFlight = null; });
+        return inFlight;
+    };
+    return {
+        publicKeyOf: async (deviceId) => {
+            const stale = now() - fetchedAt > ttlMs;
+            const hit = keys.get(deviceId);
+            if (hit && !stale)
+                return hit;
+            // Miss or stale: refetch, but a miss alone only once per refreshMinMs —
+            // an attacker probing unknown ids must not drive the API.
+            if (inFlight) {
+                await inFlight.catch(() => undefined); // logged by the caller that started it
+            }
+            else if ((stale || now() - fetchedAt > refreshMinMs) && now() - triedAt > refreshMinMs) {
+                try {
+                    await refresh();
+                }
+                catch (err) {
+                    deps.log(`local transfer: device list unavailable — ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            return keys.get(deviceId) ?? null;
+        },
+        devices: async () => {
+            if (inFlight) {
+                await inFlight.catch(() => undefined);
+            }
+            else if (now() - fetchedAt > ttlMs && now() - triedAt > refreshMinMs) {
+                try {
+                    await refresh();
+                }
+                catch (err) {
+                    deps.log(`local transfer: device list unavailable — ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            return infos;
+        },
+    };
+};
+exports.createDeviceDirectory = createDeviceDirectory;

package/dist/device-presence.d.ts

@@ -0,0 +1,17 @@
+/** The one message both halves of presence ride; the server answers
+ *  `listener.presence.ack` or `listener.presence.error`. */
+export declare const LISTENER_PRESENCE = "listener.presence";
+export interface DeviceKeyRegistrationDeps {
+    log: (msg: string) => void;
+    /** Send one frame on the live socket; false when there is none. */
+    send: (msg: object) => boolean;
+    /** Load-or-create the keypair; resolves the Base64 SPKI public key. */
+    publicKey: () => Promise<string>;
+}
+export interface DeviceKeyRegistration {
+    /** Call on every WebSocket open. Never throws; resolves true once the
+     *  frame went out. A failure waits for the next open. */
+    onOpen: () => Promise<boolean>;
+}
+export declare const createDeviceKeyRegistration: (deps: DeviceKeyRegistrationDeps) => DeviceKeyRegistration;
+//# sourceMappingURL=device-presence.d.ts.map

package/dist/device-presence.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeviceKeyRegistration = exports.LISTENER_PRESENCE = void 0;
+/**
+ * Per-device E2E (ADR-0007) — put this machine's public key on its device
+ * record, so other devices can wrap pushes and files for it.
+ *
+ * Senders only encrypt for devices whose record carries a `publicKey`, and
+ * a local transfer (ADR-0013 decision 3) is only attempted to such a device.
+ * The listener held a keypair from the start but never registered it, so
+ * the Mac was neither an E2E recipient nor a local-transfer target.
+ *
+ * It goes over the WebSocket, not an HTTP write: the device-record route
+ * (`PATCH /v1/devices/{deviceId}`) is behind the JWT authorizer and this
+ * daemon holds an API key, so the socket — which already proves which
+ * device is speaking, and which created the record at `$connect` — is the
+ * write path. `lan-endpoint.ts` publishes the transfer endpoint on the same
+ * message.
+ *
+ * Sent on every WebSocket open: `$connect` is what makes the record exist,
+ * and a record that was recreated has lost its key. The server broadcasts
+ * `device.publicKey.changed` only when the key actually differs, so an
+ * unchanged re-registration is one quiet write. Senders seal for every listed
+ * device that has a key, so a missing key means nothing can be read there. The
+ * private half never leaves `~/.hwip/device-keys.json`.
+ *
+ * The same frame says what this build opens (`capabilities`): a sender seals
+ * a file in chunks only for a device that lists `file-chunk-v1`, and one over
+ * the relay's ceiling over LAN only to one that lists `lan-large-v1`. In one frame
+ * with the key, because a server from before `capabilities` answers a frame
+ * that carries nothing else it knows with an error.
+ */
+const file_crypto_js_1 = require("./file-crypto.js");
+const lan_receiver_js_1 = require("./lan-receiver.js");
+/** The one message both halves of presence ride; the server answers
+ *  `listener.presence.ack` or `listener.presence.error`. */
+exports.LISTENER_PRESENCE = 'listener.presence';
+const createDeviceKeyRegistration = (deps) => {
+    // Two opens in quick succession (a flapping socket) share one load. A
+    // record recreated inside that window waits for the open after — accepted.
+    let inFlight = null;
+    const register = async () => {
+        try {
+            const publicKey = await deps.publicKey();
+            const sent = deps.send({ type: exports.LISTENER_PRESENCE, data: { publicKey, capabilities: [file_crypto_js_1.FILE_CHUNK_CAPABILITY, lan_receiver_js_1.LAN_LARGE_CAPABILITY] } });
+            if (!sent)
+                deps.log('device key: not registered — no connection right now, retried at the next open');
+            return sent;
+        }
+        catch (err) {
+            deps.log(`device key: registration failed — ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    };
+    return {
+        onOpen: () => {
+            inFlight ??= register().finally(() => { inFlight = null; });
+            return inFlight;
+        },
+    };
+};
+exports.createDeviceKeyRegistration = createDeviceKeyRegistration;

package/dist/downloads.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where a file push addressed to this machine lands (ADR-0013): a flat
+ * `~/Downloads/Hwip/`, never garbage-collected — it is the user's folder,
+ * not the daemon's cache. `~/.hwip/attachments/` stays what it is: the
+ * `agent.command` scratch space with the hourly sweep.
+ */
+export declare const downloadsDir: () => string;
+/**
+ * Remove the `.part` files a daemon that died mid-download left in the
+ * downloads folder — up to 1 GiB each, hidden, and nothing else ever
+ * removes them. Only our own temp names, only plain files, only stale ones;
+ * the user's files in the folder are never looked at. Returns how many went.
+ */
+export declare const sweepStaleParts: (dir?: string, now?: number) => number;
+/**
+ * Reduce whatever the sender called the file to one safe path segment:
+ * basename (so `../../x` and absolute paths lose their directories),
+ * no control characters or separators, no leading dots (a hidden file
+ * is not what the user asked to receive), `file` when nothing is left.
+ */
+export declare const safeFileName: (raw: string) => string;
+/**
+ * Absolute path to write `fileName` under `dir`, never overwriting: an
+ * existing `a.png` yields `a (2).png`, then `a (3).png`. The counter starts
+ * at 2 because the first copy has no suffix — that is the convention macOS
+ * and the browsers use, and the one users already read.
+ */
+export declare const resolveDownloadPath: (fileName: string, dir?: string, exists?: (path: string) => boolean) => string;
+//# sourceMappingURL=downloads.d.ts.map

package/dist/downloads.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDownloadPath = exports.safeFileName = exports.sweepStaleParts = exports.downloadsDir = void 0;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/**
+ * Where a file push addressed to this machine lands (ADR-0013): a flat
+ * `~/Downloads/Hwip/`, never garbage-collected — it is the user's folder,
+ * not the daemon's cache. `~/.hwip/attachments/` stays what it is: the
+ * `agent.command` scratch space with the hourly sweep.
+ */
+const downloadsDir = () => (0, node_path_1.join)((0, node_os_1.homedir)(), 'Downloads', 'Hwip');
+exports.downloadsDir = downloadsDir;
+/** The temp name `saveStream` (file-crypto.ts) streams a download into. */
+const PART_FILE = /^\.hwip-[0-9a-f]{12}\.part$/;
+/**
+ * A `.part` untouched this long has no download behind it: a live one is
+ * written to at least every minute (DOWNLOAD_IDLE_MS) or aborted.
+ */
+const STALE_PART_MS = 60 * 60 * 1000;
+/**
+ * Remove the `.part` files a daemon that died mid-download left in the
+ * downloads folder — up to 1 GiB each, hidden, and nothing else ever
+ * removes them. Only our own temp names, only plain files, only stale ones;
+ * the user's files in the folder are never looked at. Returns how many went.
+ */
+const sweepStaleParts = (dir = (0, exports.downloadsDir)(), now = Date.now()) => {
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(dir);
+    }
+    catch {
+        return 0; // no downloads yet
+    }
+    let removed = 0;
+    for (const name of entries) {
+        if (!PART_FILE.test(name))
+            continue;
+        const path = (0, node_path_1.join)(dir, name);
+        try {
+            const st = (0, node_fs_1.lstatSync)(path);
+            if (!st.isFile() || now - st.mtimeMs < STALE_PART_MS)
+                continue;
+            (0, node_fs_1.unlinkSync)(path);
+            removed++;
+        }
+        catch { /* gone already, or not ours to remove */ }
+    }
+    return removed;
+};
+exports.sweepStaleParts = sweepStaleParts;
+/** Longest name most filesystems take; the suffix has to fit inside it too. */
+const MAX_NAME_BYTES = 255;
+/** `.tar.gz`-class extensions are ~8 bytes; nothing real is near this. */
+const MAX_EXT_BYTES = 32;
+const byteLength = (s) => Buffer.byteLength(s, 'utf8');
+/** Trim `stem` until `stem + tail` fits MAX_NAME_BYTES, never splitting a code point. */
+const fitStem = (stem, tail) => {
+    let out = stem;
+    while (out.length > 0 && byteLength(out) + byteLength(tail) > MAX_NAME_BYTES) {
+        out = Array.from(out).slice(0, -1).join('');
+    }
+    return out;
+};
+/**
+ * Reduce whatever the sender called the file to one safe path segment:
+ * basename (so `../../x` and absolute paths lose their directories),
+ * no control characters or separators, no leading dots (a hidden file
+ * is not what the user asked to receive), `file` when nothing is left.
+ */
+const safeFileName = (raw) => {
+    const cleaned = (0, node_path_1.basename)(raw)
+        .replace(/[\x00-\x1f\x7f]/g, '')
+        .replace(/[/\\]/g, '_')
+        .replace(/^\.+/, '')
+        .trim();
+    return cleaned || 'file';
+};
+exports.safeFileName = safeFileName;
+/**
+ * Absolute path to write `fileName` under `dir`, never overwriting: an
+ * existing `a.png` yields `a (2).png`, then `a (3).png`. The counter starts
+ * at 2 because the first copy has no suffix — that is the convention macOS
+ * and the browsers use, and the one users already read.
+ */
+const resolveDownloadPath = (fileName, dir = (0, exports.downloadsDir)(), exists = node_fs_1.existsSync) => {
+    const safe = (0, exports.safeFileName)(fileName);
+    // An "extension" longer than any real one is a sender playing with the
+    // trimming rule: treat it as part of the stem so it gets cut like the rest.
+    const rawExt = (0, node_path_1.extname)(safe);
+    const ext = byteLength(rawExt) <= MAX_EXT_BYTES ? rawExt : '';
+    const stem = ext ? safe.slice(0, -ext.length) : safe;
+    // The trim can empty the stem and leave `.ext` — a hidden file — so the
+    // name rules run once more on what is actually written.
+    const nameFor = (tail) => (0, exports.safeFileName)(fitStem(stem, tail) + tail);
+    const first = (0, node_path_1.join)(dir, nameFor(ext));
+    if (!exists(first))
+        return first;
+    for (let n = 2;; n++) {
+        const candidate = (0, node_path_1.join)(dir, nameFor(` (${n})${ext}`));
+        if (!exists(candidate))
+            return candidate;
+    }
+};
+exports.resolveDownloadPath = resolveDownloadPath;

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class HwipError extends Error {
+    code: string;
+    status: number;
+    constructor(message: string, code: string, status: number);
+}
+export declare class AuthenticationError extends HwipError {
+    constructor(message?: string);
+}
+export declare class QuotaExceededError extends HwipError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuotaExceededError = exports.AuthenticationError = exports.HwipError = void 0;
+class HwipError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = 'HwipError';
+        this.code = code;
+        this.status = status;
+    }
+}
+exports.HwipError = HwipError;
+class AuthenticationError extends HwipError {
+    constructor(message = 'Authentication failed') {
+        super(message, 'AUTHENTICATION_ERROR', 401);
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class QuotaExceededError extends HwipError {
+    constructor(message = 'Quota exceeded') {
+        super(message, 'QUOTA_EXCEEDED', 403);
+        this.name = 'QuotaExceededError';
+    }
+}
+exports.QuotaExceededError = QuotaExceededError;

package/dist/file-crypto.d.ts

@@ -0,0 +1,94 @@
+import { Transform, type Readable } from 'node:stream';
+/**
+ * Streaming decrypt of a file the web / MCP side produced with
+ * `libs/crypto` `encryptFile` (WebCrypto AES-256-GCM, 12-byte IV). That
+ * API is one-shot; a 1 GiB attachment would sit in memory here, so this
+ * is the same wire format on `node:crypto`'s incremental cipher:
+ * WebCrypto appends the 16-byte GCM tag to the ciphertext, and the stream
+ * holds back the last 16 bytes of whatever it is fed as that tag.
+ *
+ * The key is the raw per-file AES key, already unwrapped from the
+ * attachment's `deviceKeyMap` slot (see `unwrapDeviceKey` in crypto.ts).
+ */
+export declare const GCM_TAG_BYTES = 16;
+export declare const GCM_IV_BYTES = 12;
+export declare const createFileDecryptStream: (rawKey: Buffer, iv: Buffer) => Transform;
+/**
+ * A file sealed in chunks (`file-chunk-v1`), the format a phone seals a file
+ * in that is too large to hold in memory. The padded plaintext is cut into
+ * `FILE_CHUNK_BYTES` pieces — the last one shorter or equal, never empty —
+ * and each is sealed alone with AES-256-GCM under the file key, no AAD:
+ *
+ *   nonce = prefix[7] ‖ piece index (u32 big-endian) ‖ 0x01 on the last piece, else 0x00
+ *   file  = every `ciphertext ‖ tag[16]`, in order
+ *
+ * The index in the nonce refuses a piece moved or repeated; the last-piece
+ * flag refuses a file cut at a piece's end, and bytes added after it. The
+ * prefix travels where a whole-sealed file's IV does (`iv`), and the sealed
+ * message says `chunk` next to it — see `chunkOf`. Vectors:
+ * `file-chunk.vectors.json` (scripts/gen-file-chunk-vectors.py).
+ */
+export declare const FILE_CHUNK_BYTES = 1048576;
+export declare const FILE_CHUNK_PREFIX_BYTES = 7;
+/** What a listener tells senders it opens (`capabilities` on its device record). */
+export declare const FILE_CHUNK_CAPABILITY = "file-chunk-v1";
+/**
+ * The `chunk` a sender wrote beside a file's `iv`: absent for a file sealed
+ * whole, `FILE_CHUNK_BYTES` for one sealed in chunks. Any other value is a
+ * format this build does not open — `ok: false`, and the file is left alone.
+ */
+export declare const chunkOf: (said: unknown) => {
+    ok: true;
+    chunk?: number;
+} | {
+    ok: false;
+};
+/**
+ * Streaming decrypt of a file sealed in chunks. A piece is opened only once
+ * a byte past it has arrived, because whether it is the last one is in its
+ * nonce: what is left when the stream ends is the last piece, and it has to
+ * open as one. Pieces already opened have reached the `.part` file by then;
+ * `saveStream` removes it on any failure, so nothing a later piece disowns
+ * is ever linked into place.
+ */
+export declare const createChunkedFileDecryptStream: (rawKey: Buffer, prefix: Buffer, chunk?: number) => Transform;
+/**
+ * Abort `controller` when `source` goes quiet for `idleMs`. A stalled S3
+ * connection would otherwise park a download — and its part file — for
+ * the life of the daemon with nothing in the log. Bytes still flowing,
+ * however slowly, never trip it: a 1 GiB file on a bad link is not a stall.
+ * More than `maxBytes` fails the stream: a body that never ends is not a
+ * stall either, and would fill the disk.
+ */
+export declare const withIdleTimeout: (source: Readable, idleMs: number, controller: AbortController, maxBytes?: number) => Readable;
+/**
+ * The most bytes one download may carry: the largest file any tier may send
+ * (1 GiB, `fileMaxBytes`), plus the Padmé padding (at most about 12%) and
+ * the GCM tag a sealed file adds. The record's `fileSize` is the relay's
+ * word, so it cannot be the limit; without one, a URL that streams forever
+ * fills the disk.
+ */
+export declare const DOWNLOAD_MAX_BYTES: number;
+export interface SavedFile {
+    path: string;
+    bytes: number;
+}
+/**
+ * Stream `source` to the path `nextDest()` names, optionally decrypting
+ * on the way — a file sealed whole, or with `chunk` one sealed in chunks
+ * (`iv` is then its 7-byte prefix). The bytes go to a private `.part` file first (a per-call
+ * random name, so two saves of the same file cannot touch each other's
+ * temp) and are fsynced before being linked into place — a reader never
+ * sees a half file, and an authentication failure (which GCM only reports
+ * at the very end) leaves nothing behind. `link` refuses an existing dest
+ * where `rename` would replace it; on that collision `nextDest()` is asked
+ * again, so a name taken between the caller's check and here costs a
+ * ` (n)` suffix, never the download. Resolves with the path written and
+ * the plaintext byte count.
+ */
+export declare const saveStream: (source: Readable, nextDest: () => string, decrypt?: {
+    rawKey: Buffer;
+    iv: Buffer;
+    chunk?: number;
+}) => Promise<SavedFile>;
+//# sourceMappingURL=file-crypto.d.ts.map