@feralfile/cli 2.10.1 → 4.0.0

package/dist/src/utilities/control/strict-json.js

@@ -0,0 +1,376 @@
+"use strict";
+/**
+ * Strict JSON and base64url decoding for the FF1 control protocol v1
+ * (ffos-user docs/ff1-control-v1.md §1).
+ *
+ * Why this exists instead of `JSON.parse`: two implementations that disagree
+ * about what a byte string means (which of two duplicate `kid` members wins,
+ * whether `1.0` is the integer 1) are a signature-confusion bug. `JSON.parse`
+ * silently keeps the LAST duplicate and erases the difference between `1`,
+ * `1.0` and `1e0`, so every header, claims object and JWK that crosses the
+ * trust boundary is parsed here instead. The Go reference (control/json.go)
+ * applies the same rules; keep the two in step.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControlFormatError = void 0;
+exports.b64uDecode = b64uDecode;
+exports.b64uEncode = b64uEncode;
+exports.isB64uOfLength = isB64uOfLength;
+exports.utf8Decode = utf8Decode;
+exports.parseStrictJson = parseStrictJson;
+exports.isPlainObject = isPlainObject;
+exports.strictObject = strictObject;
+exports.stringMember = stringMember;
+exports.uintMember = uintMember;
+exports.boolMember = boolMember;
+exports.toPlainJson = toPlainJson;
+/** ControlFormatError is thrown for every malformed protocol object. */
+class ControlFormatError extends Error {
+    constructor(message) {
+        super(`ff1-control: ${message}`);
+        this.name = 'ControlFormatError';
+    }
+}
+exports.ControlFormatError = ControlFormatError;
+/** MAX_SAFE_CLAIM_INT is 2^53-1, the integer ceiling of §1. */
+const MAX_SAFE_CLAIM_INT = Number.MAX_SAFE_INTEGER;
+/** MAX_JSON_DEPTH bounds nesting, matching the Go reference's maxJSONDepth. */
+const MAX_JSON_DEPTH = 128;
+/**
+ * rawNumbers remembers the exact source text of every number member of every
+ * parsed object, so integer claims can be checked for canonical form after
+ * parsing (JSON.parse-style values cannot tell `1` from `1.0`).
+ */
+const rawNumbers = new WeakMap();
+const B64U_ALPHABET = /^[A-Za-z0-9_-]*$/;
+/**
+ * b64uDecode decodes unpadded base64url strictly: `=` padding, whitespace,
+ * any non-alphabet byte and non-zero trailing bits are all rejected (§1). The
+ * round-trip comparison is what catches non-canonical trailing bits, which
+ * Node's lenient decoder would otherwise accept.
+ *
+ * @param value - Candidate base64url text
+ * @returns The decoded bytes
+ * @throws {ControlFormatError} When the text is not canonical base64url
+ */
+function b64uDecode(value) {
+    if (typeof value !== 'string' || !B64U_ALPHABET.test(value) || value.length % 4 === 1) {
+        throw new ControlFormatError('invalid base64url');
+    }
+    const bytes = Buffer.from(value, 'base64url');
+    if (bytes.toString('base64url') !== value) {
+        throw new ControlFormatError('non-canonical base64url');
+    }
+    return new Uint8Array(bytes);
+}
+/**
+ * b64uEncode encodes bytes as unpadded base64url.
+ *
+ * @param bytes - Bytes or UTF-8 text to encode
+ * @returns Unpadded base64url text
+ */
+function b64uEncode(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+/**
+ * isB64uOfLength reports whether value is canonical base64url of exactly n bytes.
+ *
+ * @param value - Candidate value
+ * @param n - Required decoded length
+ * @returns True when the value decodes to exactly n bytes
+ */
+function isB64uOfLength(value, n) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    try {
+        return b64uDecode(value).length === n;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * utf8Decode decodes bytes as UTF-8, rejecting invalid sequences (§1). A
+ * lenient decoder would map them to U+FFFD and let two different byte strings
+ * read as the same JSON.
+ *
+ * @param bytes - Raw bytes
+ * @returns The decoded string
+ * @throws {ControlFormatError} On invalid UTF-8
+ */
+function utf8Decode(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new ControlFormatError('invalid UTF-8');
+    }
+}
+/** StrictParser is a small recursive-descent JSON parser with duplicate-key detection. */
+class StrictParser {
+    text;
+    pos = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    parseDocument() {
+        const value = this.parseValue(0);
+        this.skipWhitespace();
+        if (this.pos !== this.text.length) {
+            throw new ControlFormatError('trailing data after JSON value');
+        }
+        return value;
+    }
+    fail(message) {
+        throw new ControlFormatError(`invalid JSON at ${this.pos}: ${message}`);
+    }
+    skipWhitespace() {
+        while (this.pos < this.text.length && ' \t\r\n'.includes(this.text[this.pos])) {
+            this.pos += 1;
+        }
+    }
+    parseValue(depth) {
+        if (depth > MAX_JSON_DEPTH) {
+            this.fail('nested too deeply');
+        }
+        this.skipWhitespace();
+        const ch = this.text[this.pos];
+        if (ch === '{') {
+            return this.parseObject(depth);
+        }
+        if (ch === '[') {
+            return this.parseArray(depth);
+        }
+        if (ch === '"') {
+            return this.parseString();
+        }
+        if (ch === '-' || (ch >= '0' && ch <= '9')) {
+            return Number(this.parseNumberText());
+        }
+        for (const [literal, value] of [
+            ['true', true],
+            ['false', false],
+            ['null', null],
+        ]) {
+            if (this.text.startsWith(literal, this.pos)) {
+                this.pos += literal.length;
+                return value;
+            }
+        }
+        return this.fail('unexpected token');
+    }
+    parseObject(depth) {
+        this.pos += 1;
+        // A null-prototype object keeps a member named "__proto__" an ordinary
+        // member instead of a prototype assignment.
+        const out = Object.create(null);
+        const numbers = new Map();
+        this.skipWhitespace();
+        if (this.text[this.pos] === '}') {
+            this.pos += 1;
+            rawNumbers.set(out, numbers);
+            return out;
+        }
+        for (;;) {
+            this.skipWhitespace();
+            if (this.text[this.pos] !== '"') {
+                this.fail('object key is not a string');
+            }
+            // Keys are compared after unescaping, so "typ" and "typ" collide.
+            const key = this.parseString();
+            if (Object.prototype.hasOwnProperty.call(out, key)) {
+                this.fail(`duplicate member ${JSON.stringify(key)}`);
+            }
+            this.skipWhitespace();
+            if (this.text[this.pos] !== ':') {
+                this.fail('expected ":"');
+            }
+            this.pos += 1;
+            this.skipWhitespace();
+            const start = this.pos;
+            out[key] = this.parseValue(depth + 1);
+            if (typeof out[key] === 'number') {
+                numbers.set(key, this.text.slice(start, this.pos));
+            }
+            this.skipWhitespace();
+            const sep = this.text[this.pos];
+            this.pos += 1;
+            if (sep === '}') {
+                rawNumbers.set(out, numbers);
+                return out;
+            }
+            if (sep !== ',') {
+                this.fail('expected "," or "}"');
+            }
+        }
+    }
+    parseArray(depth) {
+        this.pos += 1;
+        const out = [];
+        this.skipWhitespace();
+        if (this.text[this.pos] === ']') {
+            this.pos += 1;
+            return out;
+        }
+        for (;;) {
+            out.push(this.parseValue(depth + 1));
+            this.skipWhitespace();
+            const sep = this.text[this.pos];
+            this.pos += 1;
+            if (sep === ']') {
+                return out;
+            }
+            if (sep !== ',') {
+                this.fail('expected "," or "]"');
+            }
+        }
+    }
+    parseString() {
+        const start = this.pos;
+        this.pos += 1;
+        for (;;) {
+            const ch = this.text[this.pos];
+            if (ch === undefined) {
+                this.fail('unterminated string');
+            }
+            if (ch === '"') {
+                this.pos += 1;
+                break;
+            }
+            if (ch === '\\') {
+                this.pos += 2;
+                continue;
+            }
+            if (ch < ' ') {
+                this.fail('control character in string');
+            }
+            this.pos += 1;
+        }
+        // The span is grammar-checked by JSON.parse, which also unescapes it.
+        try {
+            return JSON.parse(this.text.slice(start, this.pos));
+        }
+        catch {
+            return this.fail('invalid string escape');
+        }
+    }
+    parseNumberText() {
+        const match = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(this.text.slice(this.pos));
+        if (!match) {
+            this.fail('invalid number');
+        }
+        this.pos += match[0].length;
+        return match[0];
+    }
+}
+/**
+ * parseStrictJson parses UTF-8 JSON text with the §1 rules: one value, no
+ * trailing data, no duplicate member names at any depth.
+ *
+ * @param input - JSON text or raw UTF-8 bytes
+ * @returns The parsed value; objects have a null prototype
+ * @throws {ControlFormatError} On any violation
+ */
+function parseStrictJson(input) {
+    const text = typeof input === 'string' ? input : utf8Decode(input);
+    return new StrictParser(text).parseDocument();
+}
+/**
+ * isPlainObject reports whether value is a parsed JSON object (not an array or null).
+ *
+ * @param value - Candidate value
+ * @returns True for JSON objects
+ */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * strictObject requires value to be an object whose member names are all in
+ * required ∪ optional, with every required member present (§1 closed sets).
+ *
+ * @param value - Parsed JSON value
+ * @param required - Members that must be present
+ * @param optional - Members that may be present
+ * @param what - Name used in error messages
+ * @returns The object, typed as a record
+ * @throws {ControlFormatError} On any extra or missing member
+ */
+function strictObject(value, required, optional, what) {
+    if (!isPlainObject(value)) {
+        throw new ControlFormatError(`${what} is not a JSON object`);
+    }
+    for (const key of Object.keys(value)) {
+        if (!required.includes(key) && !optional.includes(key)) {
+            throw new ControlFormatError(`${what} has unexpected member ${JSON.stringify(key)}`);
+        }
+    }
+    for (const key of required) {
+        if (!Object.prototype.hasOwnProperty.call(value, key)) {
+            throw new ControlFormatError(`${what} is missing member ${JSON.stringify(key)}`);
+        }
+    }
+    return value;
+}
+/**
+ * stringMember returns a required string member.
+ *
+ * @param obj - Parsed object
+ * @param key - Member name
+ * @returns The string value
+ * @throws {ControlFormatError} When the member is absent or not a string
+ */
+function stringMember(obj, key) {
+    const value = obj[key];
+    if (typeof value !== 'string') {
+        throw new ControlFormatError(`member ${JSON.stringify(key)} is not a string`);
+    }
+    return value;
+}
+/**
+ * uintMember returns a canonical non-negative integer member in [0, 2^53-1].
+ * `1.0`, `1e3`, `-0`, `01` and quoted numbers are rejected (§1): the Dart,
+ * JS and Go encoders never produce them, so seeing one means a hand-built or
+ * hostile object. Only objects produced by parseStrictJson can be checked.
+ *
+ * @param obj - Object returned by parseStrictJson
+ * @param key - Member name
+ * @returns The integer value
+ * @throws {ControlFormatError} When absent, non-canonical or out of range
+ */
+function uintMember(obj, key) {
+    const raw = rawNumbers.get(obj)?.get(key);
+    if (raw === undefined || !/^(?:0|[1-9]\d*)$/.test(raw)) {
+        throw new ControlFormatError(`member ${JSON.stringify(key)} is not a canonical integer`);
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value > MAX_SAFE_CLAIM_INT) {
+        throw new ControlFormatError(`member ${JSON.stringify(key)} is out of range`);
+    }
+    return value;
+}
+/**
+ * boolMember returns a required boolean member.
+ *
+ * @param obj - Parsed object
+ * @param key - Member name
+ * @returns The boolean value
+ * @throws {ControlFormatError} When absent or not a boolean
+ */
+function boolMember(obj, key) {
+    const value = obj[key];
+    if (typeof value !== 'boolean') {
+        throw new ControlFormatError(`member ${JSON.stringify(key)} is not a boolean`);
+    }
+    return value;
+}
+/**
+ * toPlainJson deep-copies a parsed value onto ordinary prototypes so callers
+ * outside the codec (printing, deepEqual in tests) see normal objects.
+ *
+ * @param value - Value from parseStrictJson
+ * @returns Equivalent value with ordinary object prototypes
+ */
+function toPlainJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/src/utilities/device-lookup.js

@@ -11,8 +11,9 @@ const device_normalize_1 = require("./device-normalize");
  *     so a stale row that happens to share the same IP cannot shadow the correct
  *     entry. Requires the stored entry to have been written with an id field.
  *  2. Exact URL match — normal case after ID (same host format, no migration).
- *  3. mDNS hostname component match — both URLs are parsed and only the hostname
- *     part is compared (same .local name, different underlying IP or port).
+ *  3. Hostname component match — both URLs are parsed and the hostname compared.
+ *     For a `.local` name, port and protocol are ignored (same device, stored a
+ *     different way); for any other host the port must match too.
  *  4a. Discovered IP → stored IP: the mDNS discovery reports a resolved IP that
  *     matches the IP in a stored entry. Bridges .local ↔ stored-IP migration for
  *     pre-id configs with no stored id.
@@ -41,18 +42,28 @@ function findExistingDeviceEntry(existingDevices, newHost, discoveredName, disco
     if (byHost) {
         return byHost;
     }
-    // 3. mDNS hostname component match (ignores port and protocol differences)
-    let newHostname = '';
+    // 3. Hostname component match. A `.local` name is the device itself, so port
+    //    and protocol differences are ignored. Any other host (an IP, a tunnel or
+    //    port-forwarding front) can serve several devices on different ports, so
+    //    the port must match as well: matching on the address alone made
+    //    `device add --host <same-ip>:<other-port> --name Kitchen` overwrite the
+    //    existing device while reporting "Added device: Kitchen".
+    let newUrl = null;
     try {
-        newHostname = new URL(newHost).hostname;
+        newUrl = new URL(newHost);
     }
     catch {
         // not a valid URL — skip hostname matching
     }
-    if (newHostname) {
+    if (newUrl?.hostname) {
+        const candidate = newUrl;
         const byHostname = existingDevices.find((d) => {
             try {
-                return new URL(d.host || '').hostname === newHostname;
+                const stored = new URL(d.host || '');
+                if (stored.hostname !== candidate.hostname) {
+                    return false;
+                }
+                return (candidate.hostname.toLowerCase().endsWith('.local') || stored.port === candidate.port);
             }
             catch {
                 return false;
@@ -76,8 +87,12 @@ function findExistingDeviceEntry(existingDevices, newHost, discoveredName, disco
                 return false; // different physical devices — do not conflate
             }
             try {
-                const storedIp = stripBrackets(new URL(d.host || '').hostname);
-                return discoveredAddresses.includes(storedIp);
+                const stored = new URL(d.host || '');
+                const storedIp = stripBrackets(stored.hostname);
+                // Same port rule as steps 3 and 4b: an address match on another port is
+                // another device. (A matching stable id already returned in step 1.)
+                const samePort = stored.port === (newUrl?.port ?? stored.port);
+                return discoveredAddresses.includes(storedIp) && samePort;
             }
             catch {
                 return false;
@@ -91,9 +106,19 @@ function findExistingDeviceEntry(existingDevices, newHost, discoveredName, disco
     //     and a stored entry has that IP in its stored addresses list (populated from
     //     prior mDNS discoveries). This bridges --host <ip/ipv6> → existing .local entry.
     //     Strip IPv6 brackets before comparing (Node URL.hostname returns '[fe80::1]').
-    const rawHostname = stripBrackets(newHostname);
+    //     The port must match the stored entry's port, for the same reason as step 3:
+    //     another port at a remembered address is another device, not this one.
+    const rawHostname = stripBrackets(newUrl?.hostname ?? '');
     if (rawHostname && (/^[0-9.]+$/.test(rawHostname) || rawHostname.includes(':'))) {
-        const byStoredAddress = existingDevices.find((d) => d.addresses?.includes(rawHostname));
+        const samePort = (stored) => {
+            try {
+                return new URL(stored || '').port === newUrl?.port;
+            }
+            catch {
+                return false;
+            }
+        };
+        const byStoredAddress = existingDevices.find((d) => d.addresses?.includes(rawHostname) && samePort(d.host));
         if (byStoredAddress) {
             return byStoredAddress;
         }

package/dist/src/utilities/device-network.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Network classification shared by the FF1 LAN delivery paths (legacy
+ * plaintext casts in ff1-device.ts and the secure envelope transport in
+ * control/secure-transport.ts), so both apply the same retry and relayer
+ * fallback rules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTransientDeviceNetworkError = isTransientDeviceNetworkError;
+exports.isConnectPhaseNetworkError = isConnectPhaseNetworkError;
+exports.parseRetryAfterMs = parseRetryAfterMs;
+/**
+ * isTransientDeviceNetworkError returns true when a send failure is likely temporary.
+ *
+ * This classifier intentionally targets resolver and route-level failures that are
+ * common on local mDNS/Wi-Fi environments. Permanent command errors should surface
+ * immediately without retry loops.
+ *
+ * @param {unknown} error - Error thrown by fetch
+ * @returns {boolean} True when retrying is likely to recover
+ */
+function isTransientDeviceNetworkError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const networkCodes = new Set([
+        'EHOSTUNREACH',
+        'ENETUNREACH',
+        'ENOTFOUND',
+        'EAI_AGAIN',
+        'ETIMEDOUT',
+        'ECONNREFUSED',
+        'ECONNRESET',
+    ]);
+    const message = error.message || '';
+    const messageLooksTransient = message.includes('fetch failed') ||
+        message.includes('getaddrinfo') ||
+        message.includes('EHOSTUNREACH') ||
+        message.includes('ENOTFOUND') ||
+        message.includes('ETIMEDOUT') ||
+        message.includes('network timeout') ||
+        message.includes('No route to host');
+    if (messageLooksTransient) {
+        return true;
+    }
+    const causeCode = error.cause &&
+        typeof error.cause === 'object' &&
+        'code' in error.cause &&
+        typeof error.cause.code === 'string'
+        ? error.cause.code
+        : undefined;
+    return Boolean(causeCode && networkCodes.has(causeCode));
+}
+// Codes that can only come from opening the connection (resolving the name,
+// routing, or a refused/timed-out TCP connect): the request bytes were never
+// written, so the FF1 cannot have run it.
+const CONNECT_PHASE_CODES = new Set([
+    'ECONNREFUSED',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'UND_ERR_CONNECT_TIMEOUT',
+]);
+// Codes that prove the same only when the failing call was the TCP connect.
+// macOS answers a connect to an absent LAN host with EHOSTDOWN (no ARP reply),
+// where Linux says EHOSTUNREACH.
+const CONNECT_SYSCALL_CODES = new Set(['ETIMEDOUT', 'EHOSTDOWN', 'ENETDOWN', 'EADDRNOTAVAIL']);
+/**
+ * isConnectPhaseNetworkError reports a send failure that proves the request
+ * never reached the FF1, so sending it again (even on another route, with a new
+ * counter) cannot run it twice. `fetch failed` on its own, ECONNRESET, a closed
+ * socket or a response timeout may follow a delivered request, and are not
+ * connect-phase (feral-file#3551 spec §14.4).
+ *
+ * @param {unknown} error - Error thrown by fetch
+ * @returns {boolean} True when the failure happened before any request byte was sent
+ */
+function isConnectPhaseNetworkError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const causes = [error, error.cause];
+    const cause = error.cause;
+    if (cause && Array.isArray(cause.errors)) {
+        // Happy-eyeballs connects report one error per address.
+        causes.push(...cause.errors);
+    }
+    return causes.some((candidate) => {
+        if (!candidate || typeof candidate !== 'object') {
+            return false;
+        }
+        const { code, syscall } = candidate;
+        if (typeof code !== 'string') {
+            return false;
+        }
+        return (CONNECT_PHASE_CODES.has(code) || (syscall === 'connect' && CONNECT_SYSCALL_CODES.has(code)));
+    });
+}
+/**
+ * parseRetryAfterMs converts an HTTP `Retry-After` header into milliseconds.
+ *
+ * Supports both forms from RFC 7231: a delta-seconds integer (e.g. "5") and an
+ * HTTP-date (e.g. "Wed, 21 Oct 2025 07:28:00 GMT"). Returns undefined when the
+ * header is absent or unparseable, so callers can fall back to their own
+ * backoff. A past date clamps to 0 (retry immediately).
+ *
+ * @param {string | null | undefined} headerValue - Raw Retry-After header value
+ * @returns {number | undefined} Delay in milliseconds, or undefined if unknown
+ */
+function parseRetryAfterMs(headerValue) {
+    if (!headerValue) {
+        return undefined;
+    }
+    const trimmed = headerValue.trim();
+    if (/^\d+$/.test(trimmed)) {
+        return Number(trimmed) * 1000;
+    }
+    // A valid HTTP-date always contains letters (month/day names, or the ISO
+    // 'T'/'Z'). Requiring one rejects bare numeric junk (e.g. "-5", "5.5") that
+    // Date.parse would otherwise misinterpret as a date.
+    if (/[a-zA-Z]/.test(trimmed)) {
+        const dateMs = Date.parse(trimmed);
+        if (!Number.isNaN(dateMs)) {
+            return Math.max(0, dateMs - Date.now());
+        }
+    }
+    return undefined;
+}

package/dist/src/utilities/device-upsert.js

@@ -58,7 +58,7 @@ function applyPatch(existing, patch) {
  * 1. Same mDNS device ID → update in-place (preserves position, handles host change).
  * 2. Same host → update in-place (preserves position and metadata).
  * 3. Same name, different host → replace in-place (preserves position so that
- *    devices[0] — the implicit default for play/send/ssh — does not silently change).
+ *    devices[0] — the implicit default for display/send/ssh — does not silently change).
  * 4. Neither match → append.
  */
 function upsertDevice(existingDevices, newDevice, 

package/dist/src/utilities/feral-file-artwork.js

@@ -13,12 +13,12 @@ exports.parseFeralFileArtworkId = parseFeralFileArtworkId;
 const http_1 = require("./http");
 const user_agent_1 = require("./user-agent");
 /**
- * resolveFeralFileArtwork resolves a public Feral File artwork id into indexer
+ * resolveFeralFileArtwork resolves a public Feral File artwork id into token
  * token coordinates using the self-describing artwork API response.
  *
  * @param artworkId - Public artwork id from Feral File.
  * @param fetchImpl - Fetch implementation, injected by tests.
- * @returns Token coordinates suitable for ff-indexer-v2 lookup.
+ * @returns Token coordinates for the configured token source.
  */
 async function resolveFeralFileArtwork(artworkId, fetchImpl = http_1.defaultDeadlineFetch) {
     const normalizedArtworkId = artworkId.trim();