@hwip/cli 0.0.1 → 0.1.1

package/dist/hwip-hook.js

@@ -0,0 +1,340 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HwipHook = exports.uploadContentType = void 0;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const agent_session_js_1 = require("./agent-session.js");
+const channel_js_1 = require("./channel.js");
+const errors_js_1 = require("./errors.js");
+const ws_url_js_1 = require("./ws-url.js");
+const http_failure_js_1 = require("./http-failure.js");
+const insecure_url_js_1 = require("./insecure-url.js");
+const crypto_js_1 = require("./crypto.js");
+const listener_device_id_js_1 = require("./listener-device-id.js");
+const trust_pins_js_1 = require("./trust-pins.js");
+const self_register_js_1 = require("./self-register.js");
+const DEFAULT_TIMEOUT_MS = 30_000;
+const BODY_FILE_THRESHOLD = 512;
+const PREVIEW_LENGTH = 200;
+/**
+ * The Content-Type header an upload PUT has to carry, whatever its body: the address is signed for it,
+ * and S3 answers 403 to any other. It is the type as sent to `POST /files/upload-request`, with
+ * `; charset=utf-8` added to `text/*` that has no charset (the hwip server's `uploadContentType`).
+ * It used to follow the body's shape (a string got a charset, a Buffer none), which only held while
+ * the only uploads were `response.md` text and sealed bytes.
+ */
+const uploadContentType = (contentType) => contentType.startsWith('text/') && !contentType.includes('charset') ? `${contentType}; charset=utf-8` : contentType;
+exports.uploadContentType = uploadContentType;
+const inferMimeType = (fileName) => {
+    const ext = fileName.split('.').pop()?.toLowerCase();
+    const map = { md: 'text/markdown', txt: 'text/plain', json: 'application/json' };
+    return map[ext ?? ''] ?? 'text/plain';
+};
+/** A push this computer could not seal is not sent: never in the clear. */
+const notSealed = (why) => new errors_js_1.HwipError(`${why}; the push was not sent`, 'E2E_REQUIRED', 400);
+class HwipHook {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    /** The account this hook talks as: what `hwip ask` and `hwip agent send` need to read the device list. */
+    get account() {
+        return { apiKey: this.apiKey, baseUrl: this.baseUrl };
+    }
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new errors_js_1.HwipError('apiKey is required', 'INVALID_OPTIONS', 400);
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? ws_url_js_1.DEFAULT_API_BASE).replace(/\/$/, '');
+        (0, insecure_url_js_1.warnInsecureUrl)(this.baseUrl);
+        this.timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    }
+    /**
+     * Who this push is sealed for. Every push is sealed: when this computer's keys do not load, the device list
+     * cannot be read, no phone app is signed in or no device lists a key, the push is not sent — never sent in the
+     * clear. The device list is fetched per send rather than cached: a phone that registered its key a minute ago
+     * must be able to read the next push. Every device it lists is pinned on the way (`observeDevices`); a pin whose
+     * device now lists another key is replaced and recorded for a person (`key-changes.ts`). Returned rather than kept
+     * on the instance: two concurrent sends on one SDK hook must not overwrite each other's.
+     */
+    async audience() {
+        try {
+            await (0, crypto_js_1.initDeviceCrypto)();
+        }
+        catch {
+            throw notSealed("this computer's keys did not load");
+        }
+        let listed;
+        try {
+            listed = (await this.request('GET', '/devices')).data;
+        }
+        catch (err) {
+            // A rejected key, a used-up quota, a server that is down or limiting, a connection that failed: the record
+            // names those kinds, and they are not this push's to explain. What is left is the server saying no to the list.
+            if (!(err instanceof errors_js_1.HwipError) || err instanceof errors_js_1.AuthenticationError || err instanceof errors_js_1.QuotaExceededError
+                || err.code === 'TIMEOUT' || err.code === 'NETWORK_ERROR' || err.status === 429 || err.status >= 500) {
+                // A failure from the configuration (bad key, bad base URL) is said as it is, not rethrown raw.
+                if (err instanceof errors_js_1.HwipError && (0, http_failure_js_1.isConfigFailure)(err))
+                    throw notSealed(err.message);
+                throw err;
+            }
+            throw notSealed('the device list could not be fetched');
+        }
+        if (!Array.isArray(listed))
+            throw notSealed('the device list could not be read');
+        if (!listed.some(crypto_js_1.isAppDevice)) {
+            throw new errors_js_1.HwipError('no app is signed in to this account: sign in to the Hwip app on an iPhone or Android phone, then send again', 'NO_APP_DEVICE', 400);
+        }
+        // A computer that runs no listener puts its own key on the list here, so the app can tell who sent the push. The
+        // push does not need it — the app reads it either way, and it is not sealed for this computer — so one that cannot
+        // be registered still goes, with one line.
+        const publicKey = (0, crypto_js_1.getDevicePublicKey)();
+        if (publicKey) {
+            const listing = await (0, self_register_js_1.ensureSelfListed)(listed, { deviceId: (0, listener_device_id_js_1.listenerDeviceId)(), publicKey }, (0, self_register_js_1.registerOverApi)(this.account));
+            if (!listing.ok)
+                console.error(`hwip: could not register this computer's key (${(0, self_register_js_1.registerWhyText)(listing.why)}) — the app cannot verify who sent this push`);
+        }
+        // At the HOME of the moment, not config's TRUST_FILE (fixed at import): `hwip trust` and the listener change it while this runs.
+        (0, trust_pins_js_1.observeDevices)((0, node_path_1.join)((0, node_os_1.homedir)(), '.hwip', 'trusted-devices.json'), listed, {
+            selfId: (0, listener_device_id_js_1.listenerDeviceId)(),
+            warn: (line) => console.error(`hwip: ${line}`),
+        });
+        const recipients = (0, crypto_js_1.selectRecipients)(listed);
+        if (recipients.length === 0)
+            throw notSealed('no device has a key to encrypt for');
+        return recipients;
+    }
+    /**
+     * A push to a channel's subscribers. Always plain text, whatever the account
+     * encrypts: the server fans a channel push out after dropping the sender's
+     * device keys, so a sealed one could not be opened by any subscriber (m7.md §3).
+     * It is also not an agent-session push, so no tmux session context is attached,
+     * and a long body goes inline for the server's own limit to judge — the file
+     * path would hand subscribers an attachment this CLI has no evidence they can open.
+     */
+    async notifyChannel(payload) {
+        const json = await this.request('POST', '/pushes/send', payload);
+        const pushId = json.data?.pushId;
+        if (!pushId)
+            throw new errors_js_1.HwipError('Server returned no pushId', 'INVALID_RESPONSE', 500);
+        return { pushId };
+    }
+    /** The channels this account owns and follows (`GET /channels`, scope `channel:read`). */
+    async listChannels() {
+        const json = await this.request('GET', '/channels');
+        if (!Array.isArray(json.data))
+            throw new errors_js_1.HwipError('Server returned no channel list', 'INVALID_RESPONSE', 500);
+        return (0, channel_js_1.parseChannels)(json.data);
+    }
+    async notify(payload) {
+        if (payload.channelId)
+            return this.notifyChannel(payload);
+        // Attach the stable session key when in a tmux agent session so the push
+        // joins the agent chat. Merged into `payload` here so both the inline and
+        // file-upload (notifyWithFile) paths — which each spread `...payload` —
+        // carry it. Explicit caller values win.
+        const agentCtx = (0, agent_session_js_1.agentSessionContext)();
+        if (agentCtx)
+            payload = { ...agentCtx, ...payload };
+        const recipients = await this.audience();
+        const body = payload.body;
+        const bodyBytes = body ? new TextEncoder().encode(body).byteLength : 0;
+        const isLongBody = bodyBytes > BODY_FILE_THRESHOLD;
+        if (isLongBody && body) {
+            return this.notifyWithFile(payload, body, bodyBytes, recipients);
+        }
+        let sendPayload;
+        try {
+            const enc = await (0, crypto_js_1.encryptPushBodyForDevices)({ title: payload.title, body: payload.body, url: payload.url }, recipients);
+            // `url: undefined` alongside the title: it is already sealed inside the
+            // ciphertext, and on a link push it IS the payload. Spreading `payload`
+            // would leave the plaintext copy at the top level, handing the server the
+            // one thing `isEncrypted` promises it cannot see.
+            sendPayload = { ...payload, title: undefined, url: undefined, body: enc.body, isEncrypted: true, deviceKeyMap: enc.deviceKeyMap, senderPublicKey: enc.senderPublicKey };
+        }
+        catch {
+            throw notSealed('sealing the push failed');
+        }
+        const json = await this.request('POST', '/pushes/send', sendPayload);
+        const pushId = json.data?.pushId;
+        if (!pushId) {
+            throw new errors_js_1.HwipError('Server returned no pushId', 'INVALID_RESPONSE', 500);
+        }
+        return { pushId };
+    }
+    async notifyWithFile(payload, body, fileSize, recipients) {
+        const fileName = 'response.md';
+        const preview = body.length > PREVIEW_LENGTH ? body.slice(0, PREVIEW_LENGTH) + '...' : body;
+        // Encrypt the attachment and the push body together, before anything is
+        // uploaded. Doing them one at a time around the upload let a failure land
+        // in between and ship ciphertext under a push with no `isEncrypted` — an
+        // attachment no client would even try to open.
+        let encrypted;
+        try {
+            encrypted = {
+                file: await (0, crypto_js_1.encryptFileForDevices)(body, recipients),
+                push: await (0, crypto_js_1.encryptPushBodyForDevices)({ title: payload.title, body: preview, url: payload.url }, recipients),
+            };
+        }
+        catch {
+            throw notSealed('sealing the push failed');
+        }
+        const upload = await this.requestUpload({ fileName, fileType: 'application/octet-stream', fileSize: encrypted.file.ciphertext.length });
+        await this.uploadToS3(upload.uploadUrl, encrypted.file.ciphertext, 'application/octet-stream');
+        const sendPayload = {
+            ...payload,
+            title: undefined,
+            body: encrypted.push.body,
+            type: payload.type ?? 'file',
+            files: [{
+                    fileKey: upload.fileKey,
+                    fileName,
+                    fileSize,
+                    fileType: inferMimeType(fileName),
+                    iv: encrypted.file.iv,
+                    deviceKeyMap: encrypted.file.deviceKeyMap,
+                }],
+            // See notify: the url must not survive in the clear either.
+            url: undefined,
+            isEncrypted: true,
+            deviceKeyMap: encrypted.push.deviceKeyMap,
+            senderPublicKey: encrypted.push.senderPublicKey,
+        };
+        const json = await this.request('POST', '/pushes/send', sendPayload);
+        const pushId = json.data?.pushId;
+        if (!pushId) {
+            throw new errors_js_1.HwipError('Server returned no pushId', 'INVALID_RESPONSE', 500);
+        }
+        return { pushId, fileKey: upload.fileKey, autoFile: true };
+    }
+    async requestUpload(params) {
+        const json = await this.request('POST', '/files/upload-request', params);
+        return json.data;
+    }
+    async uploadToS3(url, content, contentType) {
+        const body = typeof content === 'string' ? content : new Uint8Array(content);
+        const response = await fetch(url, {
+            method: 'PUT',
+            headers: { 'Content-Type': (0, exports.uploadContentType)(contentType) },
+            body,
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!response.ok) {
+            throw new errors_js_1.HwipError(`S3 upload failed with status ${response.status}`, 'UPLOAD_FAILED', response.status);
+        }
+    }
+    async list(params) {
+        const query = new URLSearchParams();
+        if (params?.limit)
+            query.set('limit', String(params.limit));
+        if (params?.type)
+            query.set('type', params.type);
+        const qs = query.toString();
+        const json = await this.request('GET', `/pushes${qs ? `?${qs}` : ''}`);
+        const pushes = json.data.map((p) => ({
+            pushId: p.pushId,
+            type: p.type,
+            // An encrypted push carries no plaintext title and a JSON envelope in
+            // `body`; slicing that renders `{"ciphertext":"AAAB...` as if it were the
+            // message. This host cannot decrypt (send-only), so say so instead.
+            title: p.isEncrypted ? undefined : p.title,
+            body: p.isEncrypted ? '[encrypted]' : p.body?.slice(0, 100),
+            isEncrypted: p.isEncrypted,
+            createdAt: p.createdAt,
+        }));
+        return { pushes, count: pushes.length, hasMore: json.pagination?.hasMore ?? false };
+    }
+    async dismiss(pushId) {
+        await this.request('POST', `/pushes/${encodeURIComponent(pushId)}/dismiss`);
+        return { dismissed: true };
+    }
+    async dismissAll() {
+        const json = await this.request('POST', '/pushes/dismiss-all');
+        return { dismissed: json.data?.dismissed ?? 0 };
+    }
+    /**
+     * Set (or clear, with an empty alias) the display name for an agent session,
+     * keyed by its tmux `name` on `deviceId`. The alias overrides the app's
+     * computed session label; it survives listener re-reports (server-side).
+     */
+    async renameAgentSession(deviceId, name, alias) {
+        const res = await this.request('PATCH', `/devices/${encodeURIComponent(deviceId)}/agent-sessions/${encodeURIComponent(name)}`, { alias });
+        return { deviceId: res.data.deviceId };
+    }
+    /** The account's devices, with the agent sessions each listener reports. */
+    async listDevices() {
+        const json = await this.request('GET', '/devices');
+        // A missing list is a bad response, not an account with no devices — the
+        // latter would read as "unknown target" and hide the real failure.
+        if (!Array.isArray(json.data))
+            throw new errors_js_1.HwipError('Server returned no device list', 'INVALID_RESPONSE', 500);
+        return json.data;
+    }
+    /**
+     * Type `body` into the tmux session `agentSessionName` on `targetDeviceId`.
+     *
+     * Never through `notify`'s encryption: a sealed command is made by `sealedCommand` (command-seal.ts), which
+     * decides whether to seal at all, and arrives here as its fields. No `agentDeviceId` — the server groups by
+     * `agentDeviceId ?? targetDeviceId`, so it would file the push under a chat that is not the target's.
+     */
+    async sendAgentCommand(payload) {
+        const json = await this.request('POST', '/pushes/send', { type: 'agent.command', ...payload });
+        const pushId = json.data?.pushId;
+        if (!pushId)
+            throw new errors_js_1.HwipError('Server returned no pushId', 'INVALID_RESPONSE', 500);
+        return { pushId };
+    }
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const headers = { 'X-API-Key': this.apiKey };
+        if (body)
+            headers['Content-Type'] = 'application/json';
+        const url = `${this.baseUrl}${path}`;
+        let response;
+        let json;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+                // A redirect would carry the X-API-Key header to another host.
+                redirect: 'error',
+            });
+            json = await (0, http_failure_js_1.readJsonBody)(response);
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === 'AbortError') {
+                throw new errors_js_1.HwipError(`Request timed out after ${this.timeoutMs}ms`, 'TIMEOUT', 408);
+            }
+            // fetch reports every network failure as a TypeError; anything else is
+            // not "could not reach".
+            if (err instanceof TypeError)
+                throw new errors_js_1.HwipError((0, http_failure_js_1.networkFailureMessage)(err, url), 'NETWORK_ERROR', 0);
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            throw this.parseError(response.status, json);
+        }
+        // A 2xx that is not our JSON (a captive portal, a cut-off body) is a
+        // failed call, not an empty answer.
+        if (json === null) {
+            throw new errors_js_1.HwipError(`the server answered ${response.status} with a page that is not the API's (a captive portal, or a proxy in the way)`, 'INVALID_RESPONSE', response.status);
+        }
+        return json;
+    }
+    parseError(status, body) {
+        const message = (0, http_failure_js_1.httpFailureMessage)(status, body);
+        const code = body?.error?.code ?? 'UNKNOWN_ERROR';
+        if (status === 401)
+            return new errors_js_1.AuthenticationError(`${message} — ${http_failure_js_1.AUTH_HINT}`);
+        if (status === 403 && code === 'QUOTA_EXCEEDED')
+            return new errors_js_1.QuotaExceededError(message);
+        return new errors_js_1.HwipError(message, code, status);
+    }
+}
+exports.HwipHook = HwipHook;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { HwipHook } from './hwip-hook.js';
+export type { AgentTargetDevice } from './agent-target.js';
+export { HwipError, AuthenticationError, QuotaExceededError } from './errors.js';
+export type { HwipOptions, NotifyPayload, NotifyResult, ListParams, ListResult, DismissOneResult, DismissAllResult, PushItem } from './types.js';
+export { decidePush, GATE_DEFAULTS, normalizeMarker, normalizePushMode } from './gate.js';
+export type { GateInput, GateVerdict, GateMarker, GatePushMode } from './gate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePushMode = exports.normalizeMarker = exports.GATE_DEFAULTS = exports.decidePush = exports.QuotaExceededError = exports.AuthenticationError = exports.HwipError = exports.HwipHook = void 0;
+var hwip_hook_js_1 = require("./hwip-hook.js");
+Object.defineProperty(exports, "HwipHook", { enumerable: true, get: function () { return hwip_hook_js_1.HwipHook; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "HwipError", { enumerable: true, get: function () { return errors_js_1.HwipError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
+Object.defineProperty(exports, "QuotaExceededError", { enumerable: true, get: function () { return errors_js_1.QuotaExceededError; } });
+var gate_js_1 = require("./gate.js");
+Object.defineProperty(exports, "decidePush", { enumerable: true, get: function () { return gate_js_1.decidePush; } });
+Object.defineProperty(exports, "GATE_DEFAULTS", { enumerable: true, get: function () { return gate_js_1.GATE_DEFAULTS; } });
+Object.defineProperty(exports, "normalizeMarker", { enumerable: true, get: function () { return gate_js_1.normalizeMarker; } });
+Object.defineProperty(exports, "normalizePushMode", { enumerable: true, get: function () { return gate_js_1.normalizePushMode; } });

package/dist/input-sequencer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Inbound ordering guard for keys/text arriving over the ephemeral relay.
+ *
+ * The outbound stream stamps every frame with `seq` + `epoch` so the viewer
+ * can drop what it has already painted (see listener.ts buildStreamFrame's
+ * send site); this is the inverse for the inbound direction. A dropped or
+ * reordered keystroke is not a cosmetic glitch the way a stale frame is —
+ * it lands in a real editor buffer — so the rules differ:
+ *
+ * - in-order seq delivers immediately (typing latency is the whole point of
+ *   this path; nothing is buffered on the happy path)
+ * - a gap holds later keys for INPUT_HOLD_MS, then delivers what arrived anyway.
+ *   Approximate order beats dropped keys: the relay is at-most-once, so a
+ *   never-arriving seq must not wedge everything behind it forever.
+ * - a new epoch (sender restart) resets the high-water mark, and the old
+ *   epoch's held keys are discarded rather than typed into the new run
+ * - a seq at or below the high-water mark is a straggler the hold already
+ *   flushed past — typing it now would put it out of order. The transport is
+ *   at-most-once, so this is never a transport duplicate; the sender is told
+ *   (`stale`) so it can decide whether the key still matters.
+ *
+ * Every outcome that drops a message is reported — as a non-'ok' AcceptResult
+ * for the message being accepted, or through `onDiscard` for held messages
+ * swept out by an epoch change or reset. The caller's contract ("every
+ * refusal reaches the sender") is only as honest as this accounting.
+ */
+/** How long a key waits for the gap in front of it to fill. */
+export declare const INPUT_HOLD_MS = 500;
+/** Ceiling on the reorder buffer. A gap that never fills lets every later key
+ *  pile up for the whole hold, and the flush then delivers them back to back —
+ *  one blocking tmux inject each. 32 is far past any real burst at
+ *  INPUT_HOLD_MS, so this only bites on a stuck or hostile sender. */
+export declare const MAX_PENDING_INPUTS = 32;
+/** Non-'ok' means this message was dropped and the caller owes its sender a
+ *  refusal: `overflow` (buffer full), `superseded` (older epoch than the
+ *  current run), `stale` (at or below the high-water mark — the hold already
+ *  flushed past it). 'ok' covers delivered AND held; held messages that are
+ *  later swept out surface through `onDiscard` instead. */
+export type AcceptResult = 'ok' | 'overflow' | 'superseded' | 'stale';
+/** Cancels a pending flush. */
+type CancelFlush = () => void;
+/** Injectable timer so tests drive the hold deadline instead of sleeping. */
+export type ScheduleFlush = (fn: () => void, ms: number) => CancelFlush;
+export type SequencedInput = {
+    /** Sender-side monotonic counter within `epoch`. */
+    seq: number;
+    /** Sender incarnation — a restart bumps it and restarts `seq`. */
+    epoch: number;
+};
+export type InputSequencerOptions<T> = {
+    schedule?: ScheduleFlush;
+    /** Called for each HELD message dropped without delivery — an epoch change
+     *  or reset() sweeping the buffer. Accept-time drops are reported via the
+     *  AcceptResult instead, so no message can vanish through both cracks. */
+    onDiscard?: (msg: T) => void;
+};
+export type InputSequencer<T extends SequencedInput> = {
+    accept: (msg: T) => AcceptResult;
+    /** Drop everything held (reported via onDiscard) and forget the epoch —
+     *  the run is over. */
+    reset: () => void;
+};
+export declare const createInputSequencer: <T extends SequencedInput>(deliver: (msg: T) => void, opts?: InputSequencerOptions<T>) => InputSequencer<T>;
+export {};
+//# sourceMappingURL=input-sequencer.d.ts.map

package/dist/input-sequencer.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Inbound ordering guard for keys/text arriving over the ephemeral relay.
+ *
+ * The outbound stream stamps every frame with `seq` + `epoch` so the viewer
+ * can drop what it has already painted (see listener.ts buildStreamFrame's
+ * send site); this is the inverse for the inbound direction. A dropped or
+ * reordered keystroke is not a cosmetic glitch the way a stale frame is —
+ * it lands in a real editor buffer — so the rules differ:
+ *
+ * - in-order seq delivers immediately (typing latency is the whole point of
+ *   this path; nothing is buffered on the happy path)
+ * - a gap holds later keys for INPUT_HOLD_MS, then delivers what arrived anyway.
+ *   Approximate order beats dropped keys: the relay is at-most-once, so a
+ *   never-arriving seq must not wedge everything behind it forever.
+ * - a new epoch (sender restart) resets the high-water mark, and the old
+ *   epoch's held keys are discarded rather than typed into the new run
+ * - a seq at or below the high-water mark is a straggler the hold already
+ *   flushed past — typing it now would put it out of order. The transport is
+ *   at-most-once, so this is never a transport duplicate; the sender is told
+ *   (`stale`) so it can decide whether the key still matters.
+ *
+ * Every outcome that drops a message is reported — as a non-'ok' AcceptResult
+ * for the message being accepted, or through `onDiscard` for held messages
+ * swept out by an epoch change or reset. The caller's contract ("every
+ * refusal reaches the sender") is only as honest as this accounting.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInputSequencer = exports.MAX_PENDING_INPUTS = exports.INPUT_HOLD_MS = void 0;
+/** How long a key waits for the gap in front of it to fill. */
+exports.INPUT_HOLD_MS = 500;
+/** Ceiling on the reorder buffer. A gap that never fills lets every later key
+ *  pile up for the whole hold, and the flush then delivers them back to back —
+ *  one blocking tmux inject each. 32 is far past any real burst at
+ *  INPUT_HOLD_MS, so this only bites on a stuck or hostile sender. */
+exports.MAX_PENDING_INPUTS = 32;
+const defaultSchedule = (fn, ms) => {
+    const timer = setTimeout(fn, ms);
+    // A pending flush must not keep the daemon's event loop alive.
+    timer.unref?.();
+    return () => clearTimeout(timer);
+};
+const createInputSequencer = (deliver, opts = {}) => {
+    const schedule = opts.schedule ?? defaultSchedule;
+    let epoch = null;
+    let highWater = 0;
+    let cancelFlush = null;
+    /** The seq whose absence the armed deadline is waiting out. */
+    let holdingFor = 0;
+    const pending = new Map();
+    const arm = () => {
+        holdingFor = highWater + 1;
+        cancelFlush = schedule(flush, exports.INPUT_HOLD_MS);
+    };
+    const disarm = () => {
+        cancelFlush?.();
+        cancelFlush = null;
+    };
+    /** Sweep the hold buffer without delivering — each swept message is a
+     *  keystroke its sender still waits on, so each is reported. */
+    const discardPending = () => {
+        const swept = [...pending.values()];
+        pending.clear();
+        disarm();
+        for (const msg of swept)
+            opts.onDiscard?.(msg);
+    };
+    const emit = (msg) => {
+        highWater = msg.seq;
+        deliver(msg);
+    };
+    /** Release the unbroken run sitting on top of the high-water mark. */
+    const drain = () => {
+        for (;;) {
+            const next = pending.get(highWater + 1);
+            if (!next)
+                break;
+            pending.delete(next.seq);
+            emit(next);
+        }
+        if (!pending.size) {
+            disarm();
+        }
+        else if (cancelFlush && highWater + 1 !== holdingFor) {
+            // The hole the deadline was for is filled and a later one is now
+            // first in line. Its deadline dates from now: inherited from the
+            // first gap, it fired while that run's keys were still arriving
+            // and flushed past them as stale — dropped letters.
+            disarm();
+            arm();
+        }
+    };
+    /** Hold expired: the missing seq is not coming. Deliver the rest in seq
+     *  order, which also moves the high-water mark past the hole. */
+    const flush = () => {
+        cancelFlush = null;
+        const held = [...pending.values()].sort((a, b) => a.seq - b.seq);
+        pending.clear();
+        for (const msg of held)
+            emit(msg);
+    };
+    const accept = (msg) => {
+        if (epoch === null || msg.epoch > epoch) {
+            // First message of a run — whatever seq it carries is in order by
+            // definition, so joining a stream mid-flight costs no hold.
+            discardPending();
+            epoch = msg.epoch;
+            highWater = msg.seq - 1;
+        }
+        else if (msg.epoch < epoch) {
+            return 'superseded';
+        }
+        if (msg.seq <= highWater || pending.has(msg.seq))
+            return 'stale';
+        if (msg.seq === highWater + 1) {
+            emit(msg);
+            drain();
+            return 'ok';
+        }
+        // Drop the NEW message, not a held one: the buffer already holds the
+        // keys closest to the gap, and evicting those would reorder what is
+        // about to be typed.
+        if (pending.size >= exports.MAX_PENDING_INPUTS)
+            return 'overflow';
+        pending.set(msg.seq, msg);
+        // One deadline per gap: it dates from when the hole opened, so a
+        // steady stream of later keys can't extend the wait indefinitely —
+        // only filling the hole moves it on to the next one (drain).
+        if (!cancelFlush)
+            arm();
+        return 'ok';
+    };
+    return {
+        accept,
+        reset: () => {
+            discardPending();
+            epoch = null;
+            highWater = 0;
+        },
+    };
+};
+exports.createInputSequencer = createInputSequencer;

package/dist/insecure-url.d.ts

@@ -0,0 +1,16 @@
+/** Whether `hostname` (from `URL.hostname`) is this machine. */
+export declare const isLoopbackHost: (hostname: string) => boolean;
+/** One line of warning for a URL that sends the key in the clear to a non-loopback host, else null. */
+export declare const insecureUrlWarning: (url: string) => string | null;
+/** `insecureUrlWarning` to stderr, once per URL per process (a command may build several clients). */
+export declare const warnInsecureUrl: (url: string) => void;
+/**
+ * Why the client will not fetch `url` as a file download, or null when it may.
+ * The URL comes from the API (`GET /files/<key>`), so a relay that rewrites
+ * the answer picks where this machine sends a GET: its own loopback services,
+ * the cloud metadata address, the LAN. Only S3 over `https` is a download
+ * address; a loopback one only when the API is loopback too (the local server
+ * hands out its LocalStack endpoint).
+ */
+export declare const downloadUrlProblem: (url: string, baseUrl: string) => string | null;
+//# sourceMappingURL=insecure-url.d.ts.map

package/dist/insecure-url.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadUrlProblem = exports.warnInsecureUrl = exports.insecureUrlWarning = exports.isLoopbackHost = void 0;
+/**
+ * The API key goes wherever the base URL and the socket URL point. Over `https`
+ * and `wss` it is encrypted on the way; over plain `http` and `ws` anyone on the
+ * path reads it. Nothing forbids that — a dev server on the LAN is a real use —
+ * but a machine that does it unknowingly (a base URL typed without the `s`)
+ * should hear about it once.
+ */
+// `localhost.` (a trailing dot), the unspecified address and its IPv4-mapped loopback form are this machine too.
+const LOOPBACK = /^(localhost|.*\.localhost|127(\.\d{1,3}){3}|0\.0\.0\.0|\[::1?\]|\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\])$/i;
+/** Whether `hostname` (from `URL.hostname`) is this machine. */
+const isLoopbackHost = (hostname) => LOOPBACK.test(hostname.replace(/\.$/, ''));
+exports.isLoopbackHost = isLoopbackHost;
+/** One line of warning for a URL that sends the key in the clear to a non-loopback host, else null. */
+const insecureUrlWarning = (url) => {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if ((0, exports.isLoopbackHost)(parsed.hostname))
+        return null;
+    if (parsed.protocol === 'http:') {
+        return `hwip: ${parsed.host} is reached over plain http:// — your API key travels in the clear. Use an https:// base URL.`;
+    }
+    if (parsed.protocol === 'ws:') {
+        return `hwip: the WebSocket at ${parsed.host} is reached over plain ws:// — your API key travels in the clear. Use a wss:// URL.`;
+    }
+    return null;
+};
+exports.insecureUrlWarning = insecureUrlWarning;
+const warned = new Set();
+/** `insecureUrlWarning` to stderr, once per URL per process (a command may build several clients). */
+const warnInsecureUrl = (url) => {
+    const warning = (0, exports.insecureUrlWarning)(url);
+    if (!warning || warned.has(warning))
+        return;
+    warned.add(warning);
+    console.error(warning);
+};
+exports.warnInsecureUrl = warnInsecureUrl;
+/**
+ * Why the client will not fetch `url` as a file download, or null when it may.
+ * The URL comes from the API (`GET /files/<key>`), so a relay that rewrites
+ * the answer picks where this machine sends a GET: its own loopback services,
+ * the cloud metadata address, the LAN. Only S3 over `https` is a download
+ * address; a loopback one only when the API is loopback too (the local server
+ * hands out its LocalStack endpoint).
+ */
+const downloadUrlProblem = (url, baseUrl) => {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return 'not a URL';
+    }
+    const host = parsed.hostname.replace(/\.$/, '').toLowerCase();
+    if (parsed.protocol === 'https:' && (host === 'amazonaws.com' || host.endsWith('.amazonaws.com')))
+        return null;
+    let apiHost = '';
+    try {
+        apiHost = new URL(baseUrl).hostname;
+    }
+    catch {
+        // An unreadable base URL is not a loopback one.
+    }
+    if ((parsed.protocol === 'http:' || parsed.protocol === 'https:') && (0, exports.isLoopbackHost)(host) && (0, exports.isLoopbackHost)(apiHost))
+        return null;
+    return `${parsed.protocol}//${parsed.host} is not an S3 download address`;
+};
+exports.downloadUrlProblem = downloadUrlProblem;