@hwip/cli 0.0.1 → 0.1.1

package/dist/lan-auth.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Local transfer (ADR-0013) — sender authentication, shared by every
+ * implementation of the contract: `src/lan-auth.ts` in `@hwip/cli`, the iOS
+ * app's uploader (hwip `LanAuth.swift`), and any Kotlin one to come. They
+ * stay in step by `lan-auth.vectors.json`, not by reading each other.
+ *
+ * The device keys are ECDH-only (WebCrypto `deriveKey`), so there is no
+ * signature primitive. What both sides can compute offline is the ECDH
+ * secret, and from it two keys:
+ *
+ *   macKey  = HKDF-SHA256(ikm = ECDH(sender priv, receiver pub), salt = "", info = "hwip-lan-v1", 32)
+ *   metaKey = HKDF-SHA256(same ikm,                               salt = "", info = "hwip-lan-v1-meta", 32)
+ *   mac     = HMAC-SHA256(macKey, method | path | senderDeviceId | transferId | timestamp | nonce | sha256(body))
+ *   meta    = base64( iv[12] || AES-256-GCM(metaKey, iv, json) )      — upload only
+ *   receipt = HMAC-SHA256(macKey, "hwip-lan-receipt|" + mac)            — on the 200 / 201
+ *
+ * The receiver derives the same keys from its own private key and the
+ * sender's registered public key (the device list it already fetches), so
+ * a valid MAC proves the sender holds the private half of a key the
+ * account registered — and binds the route, the body, the transfer and
+ * the moment. The MAC over `sha256(body)` can only be checked once the
+ * body has arrived; the header-level checks (shape, clock, nonce, known
+ * sender) run before a byte of it is read. The metadata is sealed because
+ * the transport is plain HTTP on a LAN: a sniffer sees a sender device id
+ * and a transfer id, never a file name or the account's device list.
+ *
+ * The receipt runs the other way. Without it any host that answers on the
+ * published address — an ARP spoof is enough — could return 201, and the
+ * sender would skip the relay for a file that never landed. Only the device
+ * holding the receiver's private key derives `macKey`, so a receipt over the
+ * request's own MAC proves this answer, for this request, came from it.
+ */
+export declare const LAN_AUTH_INFO = "hwip-lan-v1";
+export declare const LAN_META_INFO = "hwip-lan-v1-meta";
+/** A request whose timestamp is further from now than this is refused. */
+export declare const LAN_CLOCK_SKEW_MS: number;
+export declare const LAN_NONCE_TTL_MS: number;
+/** Nonces remembered per sender within the window — a legitimate device sends
+ *  two per transfer, so this is hundreds of transfers in five minutes. A sender
+ *  that exceeds it is refused until entries expire, never trimmed. */
+export declare const LAN_NONCES_PER_SENDER = 1000;
+/** The ping has no transfer; this stands in so the canonical string keeps its shape. */
+export declare const LAN_PING_TRANSFER_ID = "ping";
+export declare const LAN_PATHS: {
+    readonly ping: "/hwip/lan/v1/ping";
+    readonly upload: "/hwip/lan/v1/upload";
+};
+/** Header names, lower-case as Node hands them to a server. */
+export declare const LAN_HEADERS: {
+    readonly sender: "x-hwip-lan-sender";
+    readonly transfer: "x-hwip-lan-transfer";
+    readonly timestamp: "x-hwip-lan-timestamp";
+    readonly nonce: "x-hwip-lan-nonce";
+    readonly mac: "x-hwip-lan-mac";
+    /** Sealed `{ fileName, fileType, fileSize, iv, deviceKeyMap, transferId }` — upload only. */
+    readonly meta: "x-hwip-lan-meta";
+    /** On the receiver's 200 / 201: `signLanReceipt(macKey, request mac)`. */
+    readonly receipt: "x-hwip-lan-receipt";
+};
+export interface LanAuthFields {
+    /** HTTP method, upper-case. */
+    method: string;
+    /** Request path, one of `LAN_PATHS`. */
+    path: string;
+    senderDeviceId: string;
+    transferId: string;
+    /** Unix time in milliseconds, the sender's clock. */
+    timestamp: number;
+    /** 16 random bytes, lower-case hex. */
+    nonce: string;
+    /** SHA-256 of the raw request body, lower-case hex. Empty body → hash of nothing. */
+    bodySha256: string;
+}
+/** A transfer id is a single safe path segment — it names a landing directory. */
+export declare const isTransferId: (v: string) => boolean;
+export declare const sha256Hex: (data: Buffer | string) => string;
+export declare const EMPTY_BODY_SHA256: string;
+/** Incremental body hash for a streamed request. */
+export declare const createBodyHasher: () => {
+    update: (chunk: Buffer) => void;
+    digestHex: () => string;
+};
+export interface LanKeys {
+    macKey: Buffer;
+    metaKey: Buffer;
+}
+/** Both keys from the raw ECDH secret. */
+export declare const deriveLanKeys: (sharedSecret: Buffer) => LanKeys;
+export declare const canonicalString: (f: LanAuthFields) => string;
+export declare const signLanRequest: (macKey: Buffer, f: LanAuthFields) => string;
+/** Constant-time compare; a MAC of the wrong length is simply wrong. */
+export declare const verifyLanMac: (macKey: Buffer, f: LanAuthFields, mac: string) => boolean;
+export declare const newNonce: () => string;
+/** The receiver's proof that it, and not whatever answered on the address, accepted `requestMac`. */
+export declare const signLanReceipt: (macKey: Buffer, requestMac: string) => string;
+/** Constant-time; a missing or malformed receipt is simply wrong. */
+export declare const verifyLanReceipt: (macKey: Buffer, requestMac: string, receipt: string | null | undefined) => boolean;
+/** Largest sealed header accepted (base64 characters). A 5-device key map is
+ *  well under 2 KiB; the ceiling stays under Node's 16 KiB `maxHeaderSize`
+ *  for all headers together, so it is this check that refuses, not the parser. */
+export declare const LAN_META_MAX_BYTES: number;
+/** `iv || ciphertext || tag`, base64 — what goes in `X-Hwip-Lan-Meta`. */
+export declare const sealMeta: (metaKey: Buffer, meta: object, iv?: Buffer) => string;
+/** Inverse of `sealMeta`. Null on any shape or authentication failure — never throws. */
+export declare const openMeta: (metaKey: Buffer, sealed: string | string[] | undefined) => unknown;
+export type LanAuthHeaderFields = Omit<LanAuthFields, 'bodySha256' | 'method' | 'path'> & {
+    mac: string;
+};
+/** What a sender puts on the request; the receiver parses it back with `parseLanAuthHeaders`. */
+export declare const toLanAuthHeaders: (f: Omit<LanAuthFields, "bodySha256" | "method" | "path">, mac: string) => Record<string, string>;
+/**
+ * Shape check only — null when any header is missing or malformed. Runs
+ * before the body, before any crypto, before any lookup: a probe that
+ * gets the shape wrong costs nothing and learns nothing.
+ */
+export declare const parseLanAuthHeaders: (headers: Record<string, string | string[] | undefined>) => LanAuthHeaderFields | null;
+export declare const isTimestampFresh: (timestamp: number, now?: number, skewMs?: number) => boolean;
+export interface NonceRegistry {
+    /** True when `nonce` has been recorded for `sender` within the TTL. */
+    seen: (sender: string, nonce: string, now?: number) => boolean;
+    /** Record a verified nonce. False when it was already there (a concurrent
+     *  replay won the race) or the sender's bucket is full — the caller
+     *  refuses in both cases. */
+    commit: (sender: string, nonce: string, now?: number) => boolean;
+    size: () => number;
+}
+/**
+ * Replay guard. In memory on purpose (ADR-0013): a restart reopens a
+ * window of one clock-skew period, and the worst case is the same
+ * ciphertext saved once more as `name (2).ext`.
+ *
+ * Two properties an earlier shape lacked: nothing is recorded until the
+ * MAC has verified, so an unauthenticated peer cannot touch it; and it is
+ * partitioned per sender with a fixed quota that refuses rather than
+ * evicts, so no device — not even a hostile one on the account — can push
+ * another device's nonce out and reopen a replay. Expired entries are the
+ * only thing ever removed.
+ */
+export declare const createNonceRegistry: (perSender?: number, ttlMs?: number) => NonceRegistry;
+//# sourceMappingURL=lan-auth.d.ts.map

package/dist/lan-auth.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNonceRegistry = exports.isTimestampFresh = exports.parseLanAuthHeaders = exports.toLanAuthHeaders = exports.openMeta = exports.sealMeta = exports.LAN_META_MAX_BYTES = exports.verifyLanReceipt = exports.signLanReceipt = exports.newNonce = exports.verifyLanMac = exports.signLanRequest = exports.canonicalString = exports.deriveLanKeys = exports.createBodyHasher = exports.EMPTY_BODY_SHA256 = exports.sha256Hex = exports.isTransferId = exports.LAN_HEADERS = exports.LAN_PATHS = exports.LAN_PING_TRANSFER_ID = exports.LAN_NONCES_PER_SENDER = exports.LAN_NONCE_TTL_MS = exports.LAN_CLOCK_SKEW_MS = exports.LAN_META_INFO = exports.LAN_AUTH_INFO = void 0;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Local transfer (ADR-0013) — sender authentication, shared by every
+ * implementation of the contract: `src/lan-auth.ts` in `@hwip/cli`, the iOS
+ * app's uploader (hwip `LanAuth.swift`), and any Kotlin one to come. They
+ * stay in step by `lan-auth.vectors.json`, not by reading each other.
+ *
+ * The device keys are ECDH-only (WebCrypto `deriveKey`), so there is no
+ * signature primitive. What both sides can compute offline is the ECDH
+ * secret, and from it two keys:
+ *
+ *   macKey  = HKDF-SHA256(ikm = ECDH(sender priv, receiver pub), salt = "", info = "hwip-lan-v1", 32)
+ *   metaKey = HKDF-SHA256(same ikm,                               salt = "", info = "hwip-lan-v1-meta", 32)
+ *   mac     = HMAC-SHA256(macKey, method | path | senderDeviceId | transferId | timestamp | nonce | sha256(body))
+ *   meta    = base64( iv[12] || AES-256-GCM(metaKey, iv, json) )      — upload only
+ *   receipt = HMAC-SHA256(macKey, "hwip-lan-receipt|" + mac)            — on the 200 / 201
+ *
+ * The receiver derives the same keys from its own private key and the
+ * sender's registered public key (the device list it already fetches), so
+ * a valid MAC proves the sender holds the private half of a key the
+ * account registered — and binds the route, the body, the transfer and
+ * the moment. The MAC over `sha256(body)` can only be checked once the
+ * body has arrived; the header-level checks (shape, clock, nonce, known
+ * sender) run before a byte of it is read. The metadata is sealed because
+ * the transport is plain HTTP on a LAN: a sniffer sees a sender device id
+ * and a transfer id, never a file name or the account's device list.
+ *
+ * The receipt runs the other way. Without it any host that answers on the
+ * published address — an ARP spoof is enough — could return 201, and the
+ * sender would skip the relay for a file that never landed. Only the device
+ * holding the receiver's private key derives `macKey`, so a receipt over the
+ * request's own MAC proves this answer, for this request, came from it.
+ */
+exports.LAN_AUTH_INFO = 'hwip-lan-v1';
+exports.LAN_META_INFO = 'hwip-lan-v1-meta';
+/** A request whose timestamp is further from now than this is refused. */
+exports.LAN_CLOCK_SKEW_MS = 5 * 60_000;
+exports.LAN_NONCE_TTL_MS = exports.LAN_CLOCK_SKEW_MS;
+/** Nonces remembered per sender within the window — a legitimate device sends
+ *  two per transfer, so this is hundreds of transfers in five minutes. A sender
+ *  that exceeds it is refused until entries expire, never trimmed. */
+exports.LAN_NONCES_PER_SENDER = 1000;
+/** The ping has no transfer; this stands in so the canonical string keeps its shape. */
+exports.LAN_PING_TRANSFER_ID = 'ping';
+exports.LAN_PATHS = {
+    ping: '/hwip/lan/v1/ping',
+    upload: '/hwip/lan/v1/upload',
+};
+/** Header names, lower-case as Node hands them to a server. */
+exports.LAN_HEADERS = {
+    sender: 'x-hwip-lan-sender',
+    transfer: 'x-hwip-lan-transfer',
+    timestamp: 'x-hwip-lan-timestamp',
+    nonce: 'x-hwip-lan-nonce',
+    mac: 'x-hwip-lan-mac',
+    /** Sealed `{ fileName, fileType, fileSize, iv, deviceKeyMap, transferId }` — upload only. */
+    meta: 'x-hwip-lan-meta',
+    /** On the receiver's 200 / 201: `signLanReceipt(macKey, request mac)`. */
+    receipt: 'x-hwip-lan-receipt',
+};
+const DEVICE_ID = /^[A-Za-z0-9_.:-]{1,128}$/;
+const TRANSFER_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const HEX_32 = /^[0-9a-f]{32}$/;
+const HEX_64 = /^[0-9a-f]{64}$/;
+const TIMESTAMP = /^[0-9]{1,16}$/;
+/** A transfer id is a single safe path segment — it names a landing directory. */
+const isTransferId = (v) => TRANSFER_ID.test(v);
+exports.isTransferId = isTransferId;
+const sha256Hex = (data) => (0, node_crypto_1.createHash)('sha256').update(data).digest('hex');
+exports.sha256Hex = sha256Hex;
+exports.EMPTY_BODY_SHA256 = (0, exports.sha256Hex)(Buffer.alloc(0));
+/** Incremental body hash for a streamed request. */
+const createBodyHasher = () => {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    return { update: (chunk) => { hash.update(chunk); }, digestHex: () => hash.digest('hex') };
+};
+exports.createBodyHasher = createBodyHasher;
+/** Both keys from the raw ECDH secret. */
+const deriveLanKeys = (sharedSecret) => ({
+    macKey: Buffer.from((0, node_crypto_1.hkdfSync)('sha256', sharedSecret, Buffer.alloc(0), exports.LAN_AUTH_INFO, 32)),
+    metaKey: Buffer.from((0, node_crypto_1.hkdfSync)('sha256', sharedSecret, Buffer.alloc(0), exports.LAN_META_INFO, 32)),
+});
+exports.deriveLanKeys = deriveLanKeys;
+const canonicalString = (f) => [f.method, f.path, f.senderDeviceId, f.transferId, String(f.timestamp), f.nonce, f.bodySha256].join('|');
+exports.canonicalString = canonicalString;
+const signLanRequest = (macKey, f) => (0, node_crypto_1.createHmac)('sha256', macKey).update((0, exports.canonicalString)(f)).digest('hex');
+exports.signLanRequest = signLanRequest;
+/** Constant-time compare; a MAC of the wrong length is simply wrong. */
+const verifyLanMac = (macKey, f, mac) => {
+    if (!HEX_64.test(mac))
+        return false;
+    const expected = Buffer.from((0, exports.signLanRequest)(macKey, f), 'hex');
+    return (0, node_crypto_1.timingSafeEqual)(expected, Buffer.from(mac, 'hex'));
+};
+exports.verifyLanMac = verifyLanMac;
+const newNonce = () => (0, node_crypto_1.randomBytes)(16).toString('hex');
+exports.newNonce = newNonce;
+const LAN_RECEIPT_PREFIX = 'hwip-lan-receipt|';
+/** The receiver's proof that it, and not whatever answered on the address, accepted `requestMac`. */
+const signLanReceipt = (macKey, requestMac) => (0, node_crypto_1.createHmac)('sha256', macKey).update(LAN_RECEIPT_PREFIX + requestMac).digest('hex');
+exports.signLanReceipt = signLanReceipt;
+/** Constant-time; a missing or malformed receipt is simply wrong. */
+const verifyLanReceipt = (macKey, requestMac, receipt) => {
+    if (typeof receipt !== 'string' || !HEX_64.test(receipt))
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(Buffer.from((0, exports.signLanReceipt)(macKey, requestMac), 'hex'), Buffer.from(receipt, 'hex'));
+};
+exports.verifyLanReceipt = verifyLanReceipt;
+// ─── Sealed metadata ───
+const META_IV_BYTES = 12;
+const META_TAG_BYTES = 16;
+/** Largest sealed header accepted (base64 characters). A 5-device key map is
+ *  well under 2 KiB; the ceiling stays under Node's 16 KiB `maxHeaderSize`
+ *  for all headers together, so it is this check that refuses, not the parser. */
+exports.LAN_META_MAX_BYTES = 8 * 1024;
+/** `iv || ciphertext || tag`, base64 — what goes in `X-Hwip-Lan-Meta`. */
+const sealMeta = (metaKey, meta, iv = (0, node_crypto_1.randomBytes)(META_IV_BYTES)) => {
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', metaKey, iv);
+    const body = Buffer.concat([cipher.update(Buffer.from(JSON.stringify(meta), 'utf8')), cipher.final()]);
+    return Buffer.concat([iv, body, cipher.getAuthTag()]).toString('base64');
+};
+exports.sealMeta = sealMeta;
+/** Inverse of `sealMeta`. Null on any shape or authentication failure — never throws. */
+const openMeta = (metaKey, sealed) => {
+    if (typeof sealed !== 'string' || sealed.length === 0 || sealed.length > exports.LAN_META_MAX_BYTES)
+        return null;
+    const raw = Buffer.from(sealed, 'base64');
+    if (raw.length < META_IV_BYTES + META_TAG_BYTES)
+        return null;
+    try {
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', metaKey, raw.subarray(0, META_IV_BYTES));
+        decipher.setAuthTag(raw.subarray(raw.length - META_TAG_BYTES));
+        const json = Buffer.concat([decipher.update(raw.subarray(META_IV_BYTES, raw.length - META_TAG_BYTES)), decipher.final()]);
+        return JSON.parse(json.toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+};
+exports.openMeta = openMeta;
+/** What a sender puts on the request; the receiver parses it back with `parseLanAuthHeaders`. */
+const toLanAuthHeaders = (f, mac) => ({
+    [exports.LAN_HEADERS.sender]: f.senderDeviceId,
+    [exports.LAN_HEADERS.transfer]: f.transferId,
+    [exports.LAN_HEADERS.timestamp]: String(f.timestamp),
+    [exports.LAN_HEADERS.nonce]: f.nonce,
+    [exports.LAN_HEADERS.mac]: mac,
+});
+exports.toLanAuthHeaders = toLanAuthHeaders;
+const one = (v) => (Array.isArray(v) ? undefined : v);
+/**
+ * Shape check only — null when any header is missing or malformed. Runs
+ * before the body, before any crypto, before any lookup: a probe that
+ * gets the shape wrong costs nothing and learns nothing.
+ */
+const parseLanAuthHeaders = (headers) => {
+    const senderDeviceId = one(headers[exports.LAN_HEADERS.sender]);
+    const transferId = one(headers[exports.LAN_HEADERS.transfer]);
+    const timestamp = one(headers[exports.LAN_HEADERS.timestamp]);
+    const nonce = one(headers[exports.LAN_HEADERS.nonce]);
+    const mac = one(headers[exports.LAN_HEADERS.mac]);
+    if (senderDeviceId === undefined || !DEVICE_ID.test(senderDeviceId)
+        || transferId === undefined || !TRANSFER_ID.test(transferId)
+        || timestamp === undefined || !TIMESTAMP.test(timestamp)
+        || nonce === undefined || !HEX_32.test(nonce)
+        || mac === undefined || !HEX_64.test(mac))
+        return null;
+    return { senderDeviceId, transferId, timestamp: Number(timestamp), nonce, mac };
+};
+exports.parseLanAuthHeaders = parseLanAuthHeaders;
+const isTimestampFresh = (timestamp, now = Date.now(), skewMs = exports.LAN_CLOCK_SKEW_MS) => Math.abs(now - timestamp) <= skewMs;
+exports.isTimestampFresh = isTimestampFresh;
+/**
+ * Replay guard. In memory on purpose (ADR-0013): a restart reopens a
+ * window of one clock-skew period, and the worst case is the same
+ * ciphertext saved once more as `name (2).ext`.
+ *
+ * Two properties an earlier shape lacked: nothing is recorded until the
+ * MAC has verified, so an unauthenticated peer cannot touch it; and it is
+ * partitioned per sender with a fixed quota that refuses rather than
+ * evicts, so no device — not even a hostile one on the account — can push
+ * another device's nonce out and reopen a replay. Expired entries are the
+ * only thing ever removed.
+ */
+const createNonceRegistry = (perSender = exports.LAN_NONCES_PER_SENDER, ttlMs = exports.LAN_NONCE_TTL_MS) => {
+    const buckets = new Map(); // sender → nonce → recorded at (insertion-ordered)
+    const bucketFor = (sender, now) => {
+        const bucket = buckets.get(sender) ?? new Map();
+        for (const [nonce, at] of bucket) {
+            if (now - at <= ttlMs)
+                break; // the rest are newer
+            bucket.delete(nonce);
+        }
+        if (bucket.size === 0)
+            buckets.delete(sender);
+        else
+            buckets.set(sender, bucket);
+        return bucket;
+    };
+    return {
+        seen: (sender, nonce, now = Date.now()) => bucketFor(sender, now).has(nonce),
+        commit: (sender, nonce, now = Date.now()) => {
+            const bucket = bucketFor(sender, now);
+            if (bucket.has(nonce) || bucket.size >= perSender)
+                return false;
+            bucket.set(nonce, now);
+            buckets.set(sender, bucket);
+            return true;
+        },
+        size: () => { let n = 0; for (const b of buckets.values())
+            n += b.size; return n; },
+    };
+};
+exports.createNonceRegistry = createNonceRegistry;

package/dist/lan-endpoint.d.ts

@@ -0,0 +1,41 @@
+import { type NetworkInterfaceInfo } from 'node:os';
+export declare const isPrivateIpv4: (host: string) => boolean;
+/**
+ * The private, non-internal IPv4 a phone on the same network is likeliest to
+ * reach, or null when the machine has none up. Taking the first one found
+ * published a Tailscale, docker or VM-bridge address whenever that interface
+ * sorted first, and every file then waited out the 1.5 s LAN probe before
+ * taking the relay. Wi-Fi / Ethernet beat unknown interfaces, which beat
+ * tunnels and bridges; within that, RFC 1918 beats link-local beats CGNAT.
+ * Ties keep the OS's order. Names only — no route lookup, so it stays a pure
+ * function of `networkInterfaces()`.
+ */
+export declare const pickLanIpv4: (interfaces?: NodeJS.Dict<NetworkInterfaceInfo[]>) => string | null;
+export interface LanPublisherDeps {
+    log: (msg: string) => void;
+    /** Send one frame on the live socket; false when there is none. The
+     *  server's answer (`listener.presence.ack` / `.error`) arrives on the
+     *  socket's message handler, not here. */
+    send: (msg: object) => boolean;
+    pickHost?: () => string | null;
+}
+export interface LanPublisher {
+    /**
+     * Publish `{host, port}` if it differs from what was last published (or
+     * always, with `force` — used on every WebSocket open, because the device
+     * record may have been recreated). True when a frame went out. Never
+     * throws: a socket that is not there leaves the relay path unaffected.
+     */
+    publish: (port: number, opts?: {
+        force?: boolean;
+    }) => boolean;
+    /** `lan: null` on the device record — shutdown, or the LAN went away.
+     *  Best-effort: every reader gates on `isOnline`, so an endpoint left
+     *  behind by a socket that dropped is already inert. */
+    clear: () => void;
+    /** Poll the address and republish on change. One watcher at a time. */
+    startWatch: (port: number, intervalMs?: number) => void;
+    stopWatch: () => void;
+}
+export declare const createLanPublisher: (deps: LanPublisherDeps) => LanPublisher;
+//# sourceMappingURL=lan-endpoint.d.ts.map

package/dist/lan-endpoint.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLanPublisher = exports.pickLanIpv4 = exports.isPrivateIpv4 = void 0;
+const node_os_1 = require("node:os");
+const device_presence_js_1 = require("./device-presence.js");
+/**
+ * Local transfer (ADR-0013) — the listener's side of the rendezvous.
+ *
+ * There is no mDNS. The listener writes `lan: { host, port }` on its own
+ * device record by sending `listener.presence` over the WebSocket it already
+ * holds; a sender on the same network reads it back from `GET /devices` and
+ * tries a direct upload before the S3 relay. The socket is the transport
+ * because it is what proves which device is speaking — the HTTP device-record
+ * route is JWT-only and the daemon holds an API key.
+ *
+ * Liveness is the device's `isOnline` (that same socket), so this module
+ * republishes on every reconnect and otherwise only when the address moves.
+ *
+ * The server refuses anything but a private IPv4, so `pickLanIpv4` applies
+ * the same ranges here: a VPN or public address never reaches the wire.
+ */
+/** RFC 1918, CGNAT (100.64/10) and link-local. Same set as the server's validator. */
+const PRIVATE_IPV4 = /^(10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.\d{1,3}\.\d{1,3}|169\.254\.\d{1,3}\.\d{1,3})$/;
+const isPrivateIpv4 = (host) => PRIVATE_IPV4.test(host) && host.split('.').every((octet) => Number(octet) <= 255);
+exports.isPrivateIpv4 = isPrivateIpv4;
+/** Wi-Fi and Ethernet: macOS `en*`, Linux `eth*` / `en*` / `wlan*` / `wl*`. */
+const PHYSICAL_IFACE = /^(en|eth|wlan|wl)/;
+/** Tunnels, VPNs, containers and VM bridges: a phone on the Wi-Fi cannot reach these. */
+const VIRTUAL_IFACE = /^(utun|tun|tap|ppp|ipsec|wg|tailscale|zt|docker|br-|bridge|virbr|veth|vmnet|vboxnet|awdl|llw|anpi)/;
+const ifaceRank = (name) => (VIRTUAL_IFACE.test(name) ? 2 : PHYSICAL_IFACE.test(name) ? 0 : 1);
+/** RFC 1918 first; link-local next; CGNAT (Tailscale's 100.64/10) last. */
+const addressRank = (address) => address.startsWith('169.254.') ? 1 : address.startsWith('100.') ? 2 : 0;
+/**
+ * The private, non-internal IPv4 a phone on the same network is likeliest to
+ * reach, or null when the machine has none up. Taking the first one found
+ * published a Tailscale, docker or VM-bridge address whenever that interface
+ * sorted first, and every file then waited out the 1.5 s LAN probe before
+ * taking the relay. Wi-Fi / Ethernet beat unknown interfaces, which beat
+ * tunnels and bridges; within that, RFC 1918 beats link-local beats CGNAT.
+ * Ties keep the OS's order. Names only — no route lookup, so it stays a pure
+ * function of `networkInterfaces()`.
+ */
+const pickLanIpv4 = (interfaces = (0, node_os_1.networkInterfaces)()) => {
+    let best = null;
+    for (const [name, entries] of Object.entries(interfaces)) {
+        for (const entry of entries ?? []) {
+            if (entry.family !== 'IPv4' || entry.internal || !(0, exports.isPrivateIpv4)(entry.address))
+                continue;
+            const rank = ifaceRank(name) * 10 + addressRank(entry.address);
+            if (best === null || rank < best.rank)
+                best = { address: entry.address, rank };
+        }
+    }
+    return best?.address ?? null;
+};
+exports.pickLanIpv4 = pickLanIpv4;
+const DEFAULT_WATCH_INTERVAL_MS = 60_000;
+const createLanPublisher = (deps) => {
+    const pickHost = deps.pickHost ?? (() => (0, exports.pickLanIpv4)());
+    let published = null;
+    let watchTimer = null;
+    /** One frame. Synchronous, so a watch tick cannot interleave with the
+     *  forced publish from a socket open the way two in-flight writes could. */
+    const announce = (lan) => {
+        const sent = deps.send({ type: device_presence_js_1.LISTENER_PRESENCE, data: { lan } });
+        if (!sent)
+            deps.log('local transfer: endpoint not published — no connection right now, relay until the next open');
+        return sent;
+    };
+    const publish = (port, opts) => {
+        try {
+            const host = pickHost();
+            if (host === null) {
+                // The LAN went away (or never existed). Retract a stale endpoint
+                // so no sender is pointed at an address we no longer hold.
+                if (published !== null && announce(null))
+                    published = null;
+                return false;
+            }
+            const unchanged = published !== null && published.host === host && published.port === port;
+            if (unchanged && !opts?.force)
+                return false;
+            const sent = announce({ host, port });
+            if (sent)
+                published = { host, port };
+            return sent;
+        }
+        catch (err) {
+            // Called from timers and socket events; a throw here (a host
+            // picker that fails) must not take the daemon down.
+            deps.log(`local transfer: publish skipped — ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    };
+    const clear = () => {
+        if (published === null)
+            return;
+        // Forgotten either way: the socket is closing, and what keeps a
+        // sender away from this port after that is `isOnline`, not this field.
+        announce(null);
+        published = null;
+    };
+    const stopWatch = () => {
+        if (watchTimer)
+            clearInterval(watchTimer);
+        watchTimer = null;
+    };
+    const startWatch = (port, intervalMs = DEFAULT_WATCH_INTERVAL_MS) => {
+        stopWatch();
+        watchTimer = setInterval(() => publish(port), intervalMs);
+        watchTimer.unref();
+    };
+    return { publish, clear, startWatch, stopWatch };
+};
+exports.createLanPublisher = createLanPublisher;

package/dist/lan-receiver.d.ts

@@ -0,0 +1,122 @@
+import { type NonceRegistry } from './lan-auth.js';
+/**
+ * Local transfer (ADR-0013) — the listener's LAN-facing HTTP server.
+ *
+ * Binds an OS-assigned port on every interface; the port is what
+ * `lan-endpoint.ts` publishes. A remote address may hold only a few of the
+ * sockets (`LAN_MAX_CONNECTIONS_PER_IP`), so one address cannot starve the rest. Nothing here is reachable from the internet
+ * on purpose (the server only ever stores a private IPv4 for it), but a
+ * public Wi-Fi is a LAN too, so every route authenticates before it reads
+ * a body, and an unauthenticated peer learns nothing: every refusal it can
+ * reach is a 401 with an empty body — the same one, whatever the reason.
+ *
+ * Two routes:
+ *   GET  /hwip/lan/v1/ping    — "are you the device I think, and on my LAN?"
+ *                               MAC over an empty body; answers `{deviceId}`.
+ *   POST /hwip/lan/v1/upload  — raw ciphertext body, sealed metadata in
+ *                               `X-Hwip-Lan-Meta`; decrypted as it streams
+ *                               into `<landingDir>/<transferId>/<fileName>`.
+ *                               The push record for it arrives over the
+ *                               WebSocket afterwards and moves the file to
+ *                               the Downloads folder (listener.ts).
+ *
+ * Order on an upload: header shape → clock → nonce not
+ * yet seen → sender on the account → keys → the sealed meta opens. That
+ * last step is the pre-body proof: the meta is AES-GCM under a key only
+ * the real holder of that device's private key can derive, so a peer that
+ * merely knows a registered device id gets no further than 401 either.
+ * Only then do the statuses that say anything about this machine appear
+ * (409 transfer known, 503 busy, 411/413 length, 400 not wrapped for us),
+ * all still before the body. The MAC binds sha256(body), so it is checked
+ * when the last byte is in; so is the GCM tag. Either failing removes what
+ * was written. The nonce is recorded only once the MAC has verified.
+ */
+export interface LanReceiverOptions {
+    log: (msg: string) => void;
+    /** A server error after the bind. The socket is unusable from here;
+     *  the caller retracts the endpoint and turns the feature off. */
+    onError?: (err: Error) => void;
+    deviceId: () => string;
+    /** Registered public key (Base64 SPKI) of a device on this account, or null. */
+    lookupSenderPublicKey: (deviceId: string) => Promise<string | null>;
+    /** ECDH secret between this device and `peerPublicKeyRaw` (crypto.ts `deriveLanSharedSecret`). */
+    deriveSharedSecret: (peerPublicKeyRaw: string) => Promise<Buffer>;
+    /** Open this device's `deviceKeyMap` slot (crypto.ts `unwrapDeviceKey`). */
+    unwrapFileKey: (entryJson: string, senderPublicKeyRaw: string) => Promise<Buffer>;
+    /** Where finished transfers wait for their push record: `~/.hwip/attachments/lan`. */
+    landingDir: () => string;
+    now?: () => number;
+    maxBodyBytes?: number;
+    /** Bytes free for an unprivileged writer on the volume of `dir`; `statfsSync` unless a test says. */
+    freeBytes?: (dir: string) => number;
+    maxInFlight?: number;
+    /** Open sockets, of any state, the receiver holds at once. */
+    maxConnections?: number;
+    /** Open sockets one remote address may hold at once. */
+    maxConnectionsPerIp?: number;
+    nonces?: NonceRegistry;
+    /** A body that sends no bytes for this long is dead. */
+    idleTimeoutMs?: number;
+}
+export interface LanReceiver {
+    port: number;
+    /** Close the socket. Idempotent; resolves once the port is released. */
+    stop: () => Promise<void>;
+}
+/**
+ * 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.
+ */
+export declare const LAN_MAX_FILE_BYTES: number;
+/** What a listener tells senders when it takes `LAN_MAX_FILE_BYTES` over LAN (`capabilities` on its device record). */
+export declare const 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. */
+export declare const LAN_DISK_RESERVE_BYTES: number;
+export declare const LAN_MAX_BODY_BYTES: number;
+export declare const 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).
+ */
+export declare const 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. */
+export declare const 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.
+ */
+export declare const LAN_MAX_CONNECTIONS_PER_IP = 8;
+export declare const LAN_BODY_IDLE_MS = 60000;
+/**
+ * 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.
+ */
+export declare const createConnectionLimiter: (max: number) => {
+    admit: (address: string) => boolean;
+    release: (address: string) => void;
+    tracked: () => number;
+};
+export declare const startLanReceiver: (opts: LanReceiverOptions) => Promise<LanReceiver>;
+//# sourceMappingURL=lan-receiver.d.ts.map