@jipsoft/factusync-cli 0.1.2 → 0.1.3

package/README.md

@@ -30,11 +30,12 @@ Requires Node.js 22 or newer.
 | Variable | Required | Meaning |
 |---|---|---|
 | `FACTUSYNC_API_KEY` | yes | A FactuSync API key. Sent as the `X-API-Key` header. |
-| `FACTUSYNC_MCP_URL` | no | The MCP endpoint. Default `https://factusync-api.jipsoft.com/mcp`. |
+| `FACTUSYNC_MCP_URL` | no | The MCP endpoint. Default `https://factusync-api.jipsoft.com/mcp`. Must be `https:`; `http:` is accepted only for a loopback host (`localhost`, `127.x.x.x`, `[::1]`). |
 
 The key is **never** accepted as a flag (`--api-key`, `--key` are rejected as unknown options), so it
 does not end up in shell history or in the process list. Never print the key or paste it into a
-conversation.
+conversation. Redirects are never followed on a request that carries the key (`REDIRECT_REFUSED`,
+`RIDE_REDIRECT_REFUSED`): set `FACTUSYNC_MCP_URL` to the final URL of the endpoint.
 
 A key's **SRI environment** (testing or production) is fixed when the key is created: every document
 created through it goes to that environment. `factusync context` tells you which one it is.
@@ -162,17 +163,23 @@ taxableBase, taxAmount }], totals, payments }`.
 Only after the user approved the draft. Prints `{ documentId, jobId, status, next }`; then follow the
 document with `documents get`. Only `DRAFT` documents can be emitted.
 
-### `factusync ride <id> [--out file.pdf] [--xml file.xml]`
+### `factusync ride <id> [--out file.pdf|dir/] [--xml file.xml|dir/]`
 
 Only for `AUTHORIZED` documents. Prints `{ documentId, status, number, accessKey, rideUrl, rideDownload,
 xml?, xmlTruncated? }`.
 
 - `--out file.pdf` downloads the PDF from `rideUrl` with the same key and adds `rideFile` to the output.
   The key is only sent when `rideUrl` is on the same origin as `FACTUSYNC_MCP_URL`
-  (otherwise `RIDE_URL_UNTRUSTED`).
+  (otherwise `RIDE_URL_UNTRUSTED`). The response must be `application/pdf` (otherwise `RIDE_NOT_PDF`)
+  and at most 20 MiB (otherwise `RIDE_TOO_LARGE`, checked while it streams).
 - `--xml file.xml` writes the authorized XML, adds `xmlFile` and leaves `xml` out of the output. The
   XML is only returned when the key also has `documents:read` (otherwise `XML_NOT_AVAILABLE`); an XML
   the server truncated is not written (`XML_TRUNCATED`).
+- `--out` and `--xml` take a file or a directory. A file path is written exactly as given, replacing
+  what is there. A directory (one that exists, or any path ending in `/`) gets a generated name,
+  `ride-<accessKey>-<UTC time>.pdf` / `.xml` (for example `ride-2409…811-20261007T153012Z.pdf`; the
+  `documentId` when there is no access key), created only if it does not exist yet: an existing
+  file is never replaced (`OUTPUT_FILE_EXISTS`). `rideFile` / `xmlFile` give the path written.
 - If any check fails, no file is written.
 
 ### `factusync tools`
@@ -191,9 +198,9 @@ command for each.
 | Exit | Meaning | Codes |
 |---|---|---|
 | 0 | OK | |
-| 1 | The tool answered with an error | the API code, `TOOL_ERROR`, `TOOL_NOT_AVAILABLE`, `INVALID_INPUT`, `MCP_ERROR`, `XML_NOT_AVAILABLE`, `XML_TRUNCATED`, `RIDE_URL_UNTRUSTED`, `RIDE_DOWNLOAD_FAILED` |
-| 2 | Usage error: nothing was sent | `USAGE`, `CONFIRMATION_REQUIRED`, `INVALID_INPUT_FILE`, `OUTPUT_FILE_NOT_WRITABLE` |
-| 3 | Authentication or network | `MISSING_API_KEY`, `UNAUTHORIZED`, `FORBIDDEN`, `HTTP_ERROR`, `NETWORK_ERROR`, `TIMEOUT` |
+| 1 | The tool answered with an error | the API code, `TOOL_ERROR`, `TOOL_NOT_AVAILABLE`, `INVALID_INPUT`, `MCP_ERROR`, `XML_NOT_AVAILABLE`, `XML_TRUNCATED`, `RIDE_URL_UNTRUSTED`, `RIDE_DOWNLOAD_FAILED`, `RIDE_NOT_PDF`, `RIDE_TOO_LARGE` |
+| 2 | Usage error: nothing was sent | `USAGE`, `CONFIRMATION_REQUIRED`, `INVALID_INPUT_FILE`, `OUTPUT_FILE_NOT_WRITABLE`, `OUTPUT_FILE_EXISTS` |
+| 3 | Authentication or network | `MISSING_API_KEY`, `UNAUTHORIZED`, `FORBIDDEN`, `HTTP_ERROR`, `NETWORK_ERROR`, `TIMEOUT`, `REDIRECT_REFUSED`, `RIDE_REDIRECT_REFUSED` |
 
 A missing `FACTUSYNC_API_KEY` fails with exit 3 before any network request.
 
@@ -210,6 +217,19 @@ factusync documents get "$DOCUMENT_ID"            # until AUTHORIZED or REJECTED
 factusync ride "$DOCUMENT_ID" --out invoice.pdf --xml invoice.xml
 ```
 
+## Security
+
+What the CLI guarantees about the API key and the files it writes:
+
+- The key is read from the environment only, sent as `X-API-Key` only to `FACTUSYNC_MCP_URL`'s origin,
+  and never over plain `http:` except to a loopback host.
+- No request that carries the key follows a redirect (`REDIRECT_REFUSED`, `RIDE_REDIRECT_REFUSED`).
+- A RIDE download must be `application/pdf` and at most 20 MiB; a directory `--out`/`--xml` never
+  replaces an existing file.
+
+0.1.3 added the https-only rule, the redirect refusal, the RIDE checks and the directory naming, and moved to `@modelcontextprotocol/sdk` 1.32.1, after an external
+review of 0.1.2 ([issue #1](https://github.com/jipsoft-labs/factusync-cli/issues/1)).
+
 ## Source and issues
 
 This package is developed inside JipSoft's private monorepo, next to the FactuSync server it talks

package/dist/commands.js

@@ -84,12 +84,18 @@ export const COMMANDS = [
     {
         words: ['ride'],
         tool: 'factusync_get_ride',
-        usage: 'factusync ride <id> [--out <file.pdf>] [--xml <file.xml>]',
+        usage: 'factusync ride <id> [--out <file.pdf|dir/>] [--xml <file.xml|dir/>]',
         summary: 'For an AUTHORIZED document: the RIDE (PDF) URL, and the authorized XML when the key may read documents.',
         positionals: [{ name: 'id', argument: 'id' }],
         flags: {
-            out: { type: 'string', description: 'Download the RIDE PDF to this file (sent with the same API key)' },
-            xml: { type: 'string', description: 'Write the authorized XML to this file (needs documents:read too)' },
+            out: {
+                type: 'string',
+                description: 'Download the RIDE PDF to this file, replacing it, or into this directory under a new timestamped name that never replaces a file (sent with the same API key)',
+            },
+            xml: {
+                type: 'string',
+                description: 'Write the authorized XML to this file, or into this directory under a new timestamped name (needs documents:read too)',
+            },
         },
     },
     {

package/dist/config.js

@@ -1,5 +1,12 @@
 import { CliFailure, EXIT_AUTH_OR_NETWORK, usageFailure } from './failure.js';
 export const DEFAULT_MCP_URL = 'https://factusync-api.jipsoft.com/mcp';
+/**
+ * Plain http would carry the API key in clear text: it is accepted only for a server on this
+ * machine (a local FactuSync, tests). `URL` already normalizes the host, so `127.1` is `127.0.0.1`.
+ */
+function isLoopback(hostname) {
+    return hostname === 'localhost' || hostname === '[::1]' || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname);
+}
 /**
  * Configuration comes from the environment only. The key in particular is never a flag: a flag
  * lands in shell history and in the process list, where other users on the machine can read it.
@@ -13,8 +20,8 @@ export function readConfig(env) {
     catch {
         throw usageFailure(`FACTUSYNC_MCP_URL is not a valid URL: ${rawUrl}`);
     }
-    if (mcpUrl.protocol !== 'https:' && mcpUrl.protocol !== 'http:') {
-        throw usageFailure(`FACTUSYNC_MCP_URL must be an http(s) URL: ${rawUrl}`);
+    if (mcpUrl.protocol !== 'https:' && !(mcpUrl.protocol === 'http:' && isLoopback(mcpUrl.hostname))) {
+        throw usageFailure(`FACTUSYNC_MCP_URL must be an https URL (http only for localhost): ${rawUrl}`);
     }
     const apiKey = env['FACTUSYNC_API_KEY']?.trim();
     if (!apiKey) {

package/dist/help.js

@@ -3,7 +3,7 @@ import { DEFAULT_MCP_URL } from './config.js';
 const COMMON = [
     'Environment:',
     '  FACTUSYNC_API_KEY   Required. Your FactuSync API key. Never accepted as a flag.',
-    `  FACTUSYNC_MCP_URL   Optional. Default ${DEFAULT_MCP_URL}`,
+    `  FACTUSYNC_MCP_URL   Optional. Default ${DEFAULT_MCP_URL}. https only (http for localhost).`,
     '',
     'Output: the tool result as JSON on stdout (--pretty indents it).',
     'Errors: JSON {code, message, details?} on stderr.',

package/dist/mcp-session.js

@@ -12,7 +12,7 @@ import { CLI_VERSION } from './version.js';
 export async function withMcpSession(config, action) {
     const transport = new StreamableHTTPClientTransport(config.mcpUrl, {
         requestInit: { headers: { 'X-API-Key': config.apiKey } },
-        fetch: config.fetch,
+        fetch: refusingRedirects(config.fetch),
     });
     const client = new Client({ name: 'factusync-cli', version: CLI_VERSION });
     const options = config.timeoutMs !== undefined ? { timeout: config.timeoutMs } : undefined;
@@ -50,6 +50,15 @@ export async function withMcpSession(config, action) {
         await client.close().catch(() => undefined);
     }
 }
+/**
+ * Every request here carries `X-API-Key`, and on a cross-origin redirect `fetch` strips
+ * `Authorization` but forwards every other header: following one would hand the key to whatever
+ * host the `Location` names. FactuSync's `POST /mcp` never redirects, so none is ever followed,
+ * whatever `redirect` the SDK passes.
+ */
+function refusingRedirects(fetchFn) {
+    return (input, init) => fetchFn(input, { ...init, redirect: 'error' });
+}
 /** A successful result without `structuredContent`: its first text block, as JSON when it is JSON. */
 function parseTextContent(result) {
     const text = textBlocks(result)[0] ?? '';
@@ -131,10 +140,21 @@ export function transportFailure(error) {
     }
     return networkFailure(error);
 }
-/** `fetch` rejections: refused, unresolvable, reset or aborted connections. */
+/**
+ * `fetch` with `redirect: 'error'` rejecting on a 3xx. Undici reports it only as a `TypeError`
+ * whose cause says so; nothing more structured exists to test against.
+ */
+export function isRefusedRedirect(error) {
+    const cause = error?.cause;
+    return error instanceof TypeError && cause instanceof Error && /redirect/i.test(cause.message);
+}
+/** `fetch` rejections: refused, unresolvable, reset or aborted connections, refused redirects. */
 export function networkFailure(error) {
     if (error instanceof CliFailure)
         return error;
+    if (isRefusedRedirect(error)) {
+        return new CliFailure(EXIT_AUTH_OR_NETWORK, 'REDIRECT_REFUSED', 'FactuSync answered with a redirect, which is never followed: the API key goes only to FACTUSYNC_MCP_URL. Check that it is the final URL of the MCP endpoint.');
+    }
     if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) {
         return new CliFailure(EXIT_AUTH_OR_NETWORK, 'TIMEOUT', 'FactuSync did not answer in time.');
     }

package/dist/run.js

@@ -1,13 +1,16 @@
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile, stat, writeFile } from 'node:fs/promises';
+import { join, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 import { commandForTool, findCommand } from './commands.js';
 import { readConfig } from './config.js';
 import { CliFailure, EXIT_AUTH_OR_NETWORK, EXIT_OK, EXIT_TOOL_ERROR, EXIT_USAGE, usageFailure } from './failure.js';
 import { commandHelp, rootHelp } from './help.js';
-import { networkFailure, withMcpSession } from './mcp-session.js';
+import { isRefusedRedirect, networkFailure, withMcpSession } from './mcp-session.js';
 import { CLI_VERSION } from './version.js';
 /** Same default as the SDK's MCP requests, for the RIDE download. */
 const DEFAULT_TIMEOUT_MS = 60_000;
+/** A RIDE is a one- or two-page PDF of tens of KiB: anything near this is not one. */
+export const MAX_RIDE_BYTES = 20 * 1024 * 1024;
 /** Runs one CLI invocation and returns its exit code. Never throws. */
 export async function run(argv, env, io) {
     try {
@@ -164,8 +167,9 @@ async function listTools(session) {
 }
 /**
  * `ride --out/--xml`: every check runs before anything is written, so a failure leaves no file.
- * The PDF is fetched with the key only from the MCP endpoint's own origin: the key never goes
- * to a host the user did not configure, whatever URL a response carries.
+ * The PDF is fetched with the key only from the MCP endpoint's own origin, and a redirect is
+ * refused rather than followed: the key never goes to a host the user did not configure, whatever
+ * URL a response or its `Location` carries.
  */
 async function saveRide(result, parsed, config, io) {
     const out = parsed.values['out'];
@@ -179,25 +183,55 @@ async function saveRide(result, parsed, config, io) {
             throw new CliFailure(EXIT_TOOL_ERROR, 'XML_TRUNCATED', 'The server truncated this XML; it was not written. Download it from the FactuSync API instead.');
         }
     }
+    const stem = outputStem(result, (io.now ?? (() => new Date()))());
+    const pdfTarget = typeof out === 'string' ? await outputTarget(out, stem, 'pdf') : undefined;
+    const xmlTarget = typeof xmlPath === 'string' ? await outputTarget(xmlPath, stem, 'xml') : undefined;
     let pdf;
-    if (typeof out === 'string')
+    if (pdfTarget)
         pdf = await downloadRide(result['rideUrl'], config, io);
     const saved = { ...result };
+    if (pdf && pdfTarget) {
+        await writeOutput(pdfTarget, pdf);
+        saved['rideFile'] = pdfTarget.path;
+    }
+    if (xmlTarget) {
+        await writeOutput(xmlTarget, result['xml']);
+        delete saved['xml'];
+        saved['xmlFile'] = xmlTarget.path;
+    }
+    return saved;
+}
+/**
+ * `--out`/`--xml` naming a directory (an existing one, or any path ending in a separator) get a
+ * generated file name inside it, so repeated downloads never replace each other. A file path is
+ * the integrator's exact choice and is written as given.
+ */
+async function outputTarget(value, stem, extension) {
+    const isDirectory = value.endsWith('/') ||
+        value.endsWith(sep) ||
+        (await stat(value).then((stats) => stats.isDirectory(), () => false));
+    return isDirectory ? { path: join(value, `${stem}.${extension}`), exclusive: true } : { path: value, exclusive: false };
+}
+/**
+ * `ride-<accessKey or documentId>-<UTC time>`, e.g. `ride-2409…811-20261007T153012Z`. Both come
+ * from the server, so anything outside `[A-Za-z0-9._-]` becomes `_`: no separator can climb out of
+ * the directory the user chose.
+ */
+function outputStem(result, now) {
+    const id = [result['accessKey'], result['documentId']].find((value) => typeof value === 'string' && value !== '');
+    const timestamp = now.toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/[-:]/g, '');
+    return `ride-${(id ?? 'document').replace(/[^A-Za-z0-9._-]/g, '_')}-${timestamp}`;
+}
+async function writeOutput(target, data) {
     try {
-        if (pdf && typeof out === 'string') {
-            await writeFile(out, pdf);
-            saved['rideFile'] = out;
-        }
-        if (typeof xmlPath === 'string') {
-            await writeFile(xmlPath, result['xml'], 'utf8');
-            delete saved['xml'];
-            saved['xmlFile'] = xmlPath;
-        }
+        await writeFile(target.path, data, target.exclusive ? { flag: 'wx' } : {});
     }
     catch (error) {
+        if (target.exclusive && error.code === 'EEXIST') {
+            throw new CliFailure(EXIT_USAGE, 'OUTPUT_FILE_EXISTS', `${target.path} already exists; it was not replaced. Run it again in a moment.`);
+        }
         throw new CliFailure(EXIT_USAGE, 'OUTPUT_FILE_NOT_WRITABLE', `Cannot write the output file: ${error.message}`);
     }
-    return saved;
 }
 async function downloadRide(rideUrl, config, io) {
     let url;
@@ -212,12 +246,17 @@ async function downloadRide(rideUrl, config, io) {
     }
     let response;
     try {
+        // The API serves the PDF itself and never redirects; following one would forward X-API-Key.
         response = await io.fetch(url, {
             headers: { 'X-API-Key': config.apiKey },
+            redirect: 'error',
             signal: AbortSignal.timeout(io.timeoutMs ?? DEFAULT_TIMEOUT_MS),
         });
     }
     catch (error) {
+        if (isRefusedRedirect(error)) {
+            throw new CliFailure(EXIT_AUTH_OR_NETWORK, 'RIDE_REDIRECT_REFUSED', 'The RIDE download answered with a redirect, which is never followed: the API key is not sent to another URL.');
+        }
         throw networkFailure(error);
     }
     if (response.status === 401 || response.status === 403) {
@@ -228,5 +267,53 @@ async function downloadRide(rideUrl, config, io) {
             status: response.status,
         });
     }
-    return new Uint8Array(await response.arrayBuffer());
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.split(';')[0].trim().toLowerCase() !== 'application/pdf') {
+        await response.body?.cancel().catch(() => undefined);
+        throw new CliFailure(EXIT_TOOL_ERROR, 'RIDE_NOT_PDF', `The RIDE download is not a PDF (Content-Type '${contentType}'); nothing was written.`);
+    }
+    return readCapped(response, io.maxRideBytes ?? MAX_RIDE_BYTES);
+}
+/**
+ * The body, refused as soon as it passes `maxBytes`: up front when `Content-Length` says so, and
+ * while streaming otherwise, so a server that lies about it or streams without one cannot fill
+ * the memory or the disk.
+ */
+async function readCapped(response, maxBytes) {
+    const tooLarge = () => new CliFailure(EXIT_TOOL_ERROR, 'RIDE_TOO_LARGE', `The RIDE download is larger than ${maxBytes} bytes; nothing was written.`, {
+        maxBytes,
+    });
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        await response.body?.cancel().catch(() => undefined);
+        throw tooLarge();
+    }
+    if (!response.body)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw tooLarge();
+            }
+            chunks.push(value);
+        }
+    }
+    catch (error) {
+        throw networkFailure(error);
+    }
+    const pdf = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        pdf.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return pdf;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jipsoft/factusync-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "FactuSync command line for AI agents (Pi) and shell scripts: Ecuadorian SRI e-invoicing through the FactuSync MCP endpoint",
   "license": "MIT",
   "keywords": [
@@ -41,7 +41,7 @@
     "prepublishOnly": "npm test"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.30.1",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "zod": "^3.25.0"
   },
   "devDependencies": {