circleinbox 0.1.0 → 0.2.0

package/README.md

@@ -17,8 +17,8 @@ npx @circleinbox/cli help
 ## Quick Start
 
 ```bash
-# 1. Login with your API key
-circleinbox login --key ci_live_YOUR_KEY
+# 1. Login with your API key (interactive hidden prompt)
+circleinbox login
 
 # 2. Check connection
 circleinbox status
@@ -37,11 +37,15 @@ circleinbox send --from hello@example.com --to user@gmail.com --subject "Hello"
 
 API keys are encrypted with AES-256-GCM and stored at `~/.circleinbox/credentials`. On macOS, the encryption key is stored in the system keychain.
 
+The API key is never accepted as a command-line argument (that would leak it via shell history and `ps aux`). Provide it through one of these safe channels:
+
 ```bash
-circleinbox login                     # Interactive prompt
-circleinbox login --key ci_live_...   # Direct key
-CIRCLEINBOX_API_KEY=ci_live_... circleinbox status  # Env var fallback
-circleinbox logout                    # Remove credentials
+circleinbox login                              # Interactive hidden prompt
+circleinbox login --key-file ./key.txt         # Read from a file (chmod 600)
+echo "$KEY" | circleinbox login --from-stdin   # Pipe via stdin
+CIRCLEINBOX_API_KEY=ci_live_... circleinbox login   # From the environment
+CIRCLEINBOX_API_KEY=ci_live_... circleinbox status  # Env var fallback for any command
+circleinbox logout                             # Remove credentials
 ```
 
 ## Commands
@@ -50,7 +54,7 @@ circleinbox logout                    # Remove credentials
 
 | Command | Description |
 |---------|-------------|
-| `login [--key <key>]` | Store API key (encrypted) |
+| `login [--key-file <path> \| --from-stdin]` | Store API key (encrypted) |
 | `logout` | Remove stored credentials |
 | `status` | Show connection status and org info |
 | `version` | Show CLI version |

package/circleinbox-cli.cjs

@@ -85,6 +85,30 @@ function success(msg) { log(c.green('✓'), msg); }
 function warn(msg) { log(c.yellow('!'), msg); }
 function error(msg) { console.error(c.red('✗'), msg); }
 
+// Read a line from the TTY without echoing it (for secret entry).
+function promptHidden(question) {
+  const readline = require('readline');
+  const { Writable } = require('stream');
+  return new Promise((resolve) => {
+    const masked = new Writable({
+      write(chunk, enc, cb) {
+        if (!masked.isMuted) process.stdout.write(chunk, enc);
+        cb();
+      },
+    });
+    masked.isMuted = false;
+    const rl = readline.createInterface({ input: process.stdin, output: masked, terminal: true });
+    // Intentional sequencing: rl.question() writes the prompt synchronously
+    // (while unmuted), then we mute so the user's keystrokes are not echoed.
+    rl.question(question, (answer) => {
+      rl.close();
+      process.stdout.write('\n');
+      resolve(answer.replace(/[\x00-\x1F\x7F]/g, '').trim());
+    });
+    masked.isMuted = true;
+  });
+}
+
 // ============================================================================
 // Table formatter
 // ============================================================================
@@ -199,7 +223,7 @@ function getEncryptionKey() {
 function encryptCredentials(data) {
   const key = getEncryptionKey();
   const iv = crypto.randomBytes(IV_LENGTH);
-  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv, { authTagLength: 16 });
 
   const plaintext = JSON.stringify(data);
   const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
@@ -221,7 +245,8 @@ function decryptCredentials() {
     const decipher = crypto.createDecipheriv(
       'aes-256-gcm',
       key,
-      Buffer.from(iv, 'hex')
+      Buffer.from(iv, 'hex'),
+      { authTagLength: 16 }
     );
     decipher.setAuthTag(Buffer.from(tag, 'hex'));
 
@@ -403,7 +428,7 @@ ${c.bold('USAGE')}
   circleinbox <command> [options]
 
 ${c.bold('GENERAL')}
-  login [--key <api-key>]     Store API key (encrypted)
+  login [--key-file <path> | --from-stdin]  Store API key (encrypted)
   logout                      Remove stored credentials
   status                      Show connection status and org info
   version                     Show CLI version
@@ -456,18 +481,59 @@ ${c.bold('GLOBAL FLAGS')}
 
 async function commandLogin(args) {
   const { flags, positional } = parseFlags(args);
-  let apiKey = flags.key || positional[0];
 
-  if (!apiKey) {
-    // Read from stdin if available
-    const readline = require('readline');
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    apiKey = await new Promise((resolve) => {
-      rl.question('API Key (ci_live_...): ', (answer) => {
-        rl.close();
-        resolve(answer.replace(/[\x00-\x1F\x7F]/g, '').trim());
-      });
-    });
+  // Secrets must never be passed on the command line — they leak via shell
+  // history and `ps aux`. Reject every leak-prone form (`--key <v>`,
+  // `--key=<v>`, and a bare positional key) and route to safe channels.
+  // Three leak-prone forms, each caught explicitly because parseFlags treats
+  // them differently: `--key <v>` -> flags.key='<v>'; `--key=<v>` -> a flag
+  // literally named "key=<v>" set to true (parseFlags does not split on "=");
+  // and a bare positional. (The middle check guards parseFlags' current "="
+  // behavior — test/login-security.test.cjs exercises `--key=...` end-to-end to catch drift.)
+  const leakedKeyOnCmdline =
+    typeof flags.key === 'string' ||
+    Object.keys(flags).some((k) => k.startsWith('key=')) ||
+    positional.length > 0;
+  if (leakedKeyOnCmdline) {
+    error('Passing the API key on the command line is insecure (it leaks via shell history and `ps aux`).');
+    info('Use one of these instead:');
+    info('  circleinbox login --key-file <path>           Read the key from a file');
+    info('  echo "$KEY" | circleinbox login --from-stdin  Pipe the key via stdin');
+    info('  CIRCLEINBOX_API_KEY=<key> circleinbox login   Read from the environment');
+    info('  circleinbox login                             Interactive hidden prompt');
+    info('If you just ran this with a real key, rotate it — it is now in your shell history.');
+    process.exit(1);
+  }
+
+  let apiKey;
+  if (flags['key-file']) {
+    const keyPath = flags['key-file'];
+    try {
+      const st = fs.statSync(keyPath);
+      if (process.platform !== 'win32' && (st.mode & 0o077)) {
+        warn(`Key file ${keyPath} is group/world-readable (mode ${(st.mode & 0o777).toString(8)}). Run: chmod 600 ${keyPath}`);
+      }
+      apiKey = fs.readFileSync(keyPath, 'utf8').replace(/[\x00-\x1F\x7F]/g, '').trim();
+    } catch (err) {
+      error(`Could not read key file: ${err.message}`);
+      process.exit(1);
+    }
+  } else if (flags['from-stdin']) {
+    if (process.stdin.isTTY) {
+      info('Reading API key from stdin (press Ctrl-D when done)…');
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    apiKey = Buffer.concat(chunks).toString('utf8').replace(/[\x00-\x1F\x7F]/g, '').trim();
+  } else if (process.env.CIRCLEINBOX_API_KEY) {
+    info('Using key from CIRCLEINBOX_API_KEY');
+    apiKey = process.env.CIRCLEINBOX_API_KEY.replace(/[\x00-\x1F\x7F]/g, '').trim();
+  } else if (process.stdin.isTTY) {
+    apiKey = await promptHidden('API Key (ci_live_...): ');
+  } else {
+    error('No API key provided.');
+    info('Use --key-file <path>, --from-stdin, the CIRCLEINBOX_API_KEY env var, or run interactively.');
+    process.exit(1);
   }
 
   if (!apiKey) {
@@ -480,10 +546,10 @@ async function commandLogin(args) {
     process.exit(1);
   }
 
-  // Test the key
+  // Test the key (honor --api-url override, matching getClient resolution)
   info('Verifying API key...');
-  const config = loadConfig();
-  const client = new ApiClient(config.apiUrl || DEFAULT_API_URL, apiKey);
+  const baseUrl = globalFlags.apiUrlOverride || loadConfig().apiUrl || DEFAULT_API_URL;
+  const client = new ApiClient(baseUrl, apiKey);
 
   try {
     const result = await client.get('/domains');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circleinbox",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI for CircleInbox email infrastructure — manage inboxes, send email, store credentials, and more",
   "type": "module",
   "main": "circleinbox-cli.cjs",
@@ -16,10 +16,9 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test lib/**/*.test.cjs"
+    "test": "node --test test/*.test.cjs"
   },
   "files": [
-    "lib/",
     "circleinbox-cli.cjs",
     "README.md",
     "LICENSE"

package/lib/cli/cli-fixes.test.cjs

@@ -1,242 +0,0 @@
-// Tests for the 6 critical/major fixes in circleinbox-cli.cjs
-// Run with: node --test cli/lib/cli/cli-fixes.test.cjs
-
-const { describe, it } = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const path = require('node:path');
-
-// Read the CLI source to verify structural fixes
-const cliSource = fs.readFileSync(
-  path.join(__dirname, '..', '..', 'circleinbox-cli.cjs'),
-  'utf8'
-);
-
-describe('Fix 1: --api-url must not persist to disk', () => {
-  it('should NOT call saveConfig when --api-url is set', () => {
-    // The old code had: saveConfig(config); after setting api-url
-    // The new code should set globalFlags.apiUrlOverride instead
-    const apiUrlBlock = cliSource.match(
-      /if \(gf\['api-url'\]\)[\s\S]*?}/
-    )?.[0];
-    assert.ok(apiUrlBlock, 'api-url handling block exists');
-    assert.ok(
-      !apiUrlBlock.includes('saveConfig'),
-      'saveConfig must not be called in api-url block'
-    );
-    assert.ok(
-      apiUrlBlock.includes('apiUrlOverride'),
-      'should set apiUrlOverride in memory'
-    );
-  });
-
-  it('getClient should use apiUrlOverride', () => {
-    const getClientBlock = cliSource.match(
-      /function getClient\(\)[\s\S]*?^}/m
-    )?.[0];
-    assert.ok(getClientBlock, 'getClient function exists');
-    assert.ok(
-      getClientBlock.includes('apiUrlOverride'),
-      'getClient must check globalFlags.apiUrlOverride'
-    );
-  });
-});
-
-describe('Fix 2: readline rl.close() ordering', () => {
-  it('inboxDelete should close rl inside the question callback', () => {
-    const inboxDeleteBlock = cliSource.match(
-      /async function inboxDelete[\s\S]*?^}/m
-    )?.[0];
-    assert.ok(inboxDeleteBlock, 'inboxDelete function exists');
-
-    // rl.close() must appear INSIDE the callback, not after rl.question
-    // The pattern should be: rl.question('...', (answer) => { rl.close(); resolve(...) })
-    // NOT: rl.question('...', resolve); rl.close();
-    assert.ok(
-      !inboxDeleteBlock.match(/rl\.question\([^)]+,\s*resolve\s*\)\s*;\s*\n\s*rl\.close/),
-      'rl.close() must NOT be on the line after rl.question with bare resolve'
-    );
-    // Positive check: rl.close() appears inside a callback with resolve
-    assert.ok(
-      inboxDeleteBlock.includes('rl.close();\n      resolve('),
-      'rl.close() should be inside the callback before resolve'
-    );
-  });
-
-  it('commandReset password prompt should close rl inside the callback', () => {
-    // Find the commandReset function's readline usage
-    const resetBlock = cliSource.match(
-      /async function commandReset[\s\S]*?^}/m
-    )?.[0];
-    assert.ok(resetBlock, 'commandReset function exists');
-
-    // Should NOT have the pattern: rl.question('...', resolve); rl.close();
-    assert.ok(
-      !resetBlock.match(/rl\.question\([^)]+,\s*resolve\s*\)\s*;\s*\n\s*rl\.close/),
-      'rl.close() must NOT be after rl.question with bare resolve in commandReset'
-    );
-  });
-});
-
-describe('Fix 3: response.json() crash on non-JSON', () => {
-  it('should use response.text() + JSON.parse instead of response.json()', () => {
-    const requestBlock = cliSource.match(
-      /async request\(method[\s\S]*?^\s{2}}/m
-    )?.[0];
-    assert.ok(requestBlock, 'request method exists');
-
-    assert.ok(
-      !requestBlock.includes('response.json()'),
-      'must NOT use response.json() directly'
-    );
-    assert.ok(
-      requestBlock.includes('response.text()'),
-      'must use response.text() first'
-    );
-    assert.ok(
-      requestBlock.includes('JSON.parse(text)'),
-      'must use JSON.parse on text'
-    );
-  });
-
-  it('should handle parse failures gracefully', () => {
-    const requestBlock = cliSource.match(
-      /async request\(method[\s\S]*?^\s{2}}/m
-    )?.[0];
-    // Should have error handling around JSON.parse
-    assert.ok(
-      requestBlock.includes("catch") && requestBlock.includes("INVALID_RESPONSE"),
-      'should catch parse errors and throw with INVALID_RESPONSE code'
-    );
-  });
-});
-
-describe('Fix 4: fetch timeout with AbortController', () => {
-  it('ApiClient.request should use AbortController with 30s timeout', () => {
-    const requestBlock = cliSource.match(
-      /async request\(method[\s\S]*?^\s{2}}/m
-    )?.[0];
-    assert.ok(requestBlock, 'request method exists');
-
-    assert.ok(
-      requestBlock.includes('AbortController'),
-      'must create AbortController'
-    );
-    assert.ok(
-      requestBlock.includes('30000'),
-      'must set 30s timeout'
-    );
-    assert.ok(
-      requestBlock.includes('signal: controller.signal'),
-      'must pass signal to fetch'
-    );
-    assert.ok(
-      requestBlock.includes('clearTimeout'),
-      'must clear timeout after fetch'
-    );
-  });
-
-  it('resetClearAuth fetch calls should also have timeouts', () => {
-    const resetBlock = cliSource.match(
-      /async function resetClearAuth[\s\S]*?^}/m
-    )?.[0];
-    assert.ok(resetBlock, 'resetClearAuth function exists');
-
-    // Should have AbortController for both fetch calls
-    const controllerMatches = resetBlock.match(/new AbortController/g);
-    assert.ok(
-      controllerMatches && controllerMatches.length >= 2,
-      'resetClearAuth must have at least 2 AbortControllers (one per fetch)'
-    );
-  });
-});
-
-describe('Fix 5: subArgs no longer uses fragile indexOf', () => {
-  it('should not use allArgs.indexOf(command) for subArgs', () => {
-    const mainBlock = cliSource.match(
-      /\/\/ Main[\s\S]*$/
-    )?.[0];
-    assert.ok(mainBlock, 'main block exists');
-
-    assert.ok(
-      !mainBlock.includes('allArgs.indexOf(command)'),
-      'must NOT use allArgs.indexOf(command)'
-    );
-  });
-
-  it('should track command position by iterating and skipping global flags', () => {
-    const mainBlock = cliSource.match(
-      /\/\/ Main[\s\S]*$/
-    )?.[0];
-    assert.ok(mainBlock, 'main block exists');
-
-    assert.ok(
-      mainBlock.includes('commandIndex'),
-      'should use a commandIndex variable'
-    );
-    assert.ok(
-      mainBlock.includes('GLOBAL_FLAGS'),
-      'should define known global flags to skip'
-    );
-  });
-});
-
-describe('Fix 6: HTTPS validation for credentials', () => {
-  it('resetClearAuth should refuse HTTP URLs', () => {
-    const resetBlock = cliSource.match(
-      /async function resetClearAuth[\s\S]*?^}/m
-    )?.[0];
-    assert.ok(resetBlock, 'resetClearAuth function exists');
-
-    assert.ok(
-      resetBlock.includes("startsWith('https://')"),
-      'must check for https:// protocol'
-    );
-    assert.ok(
-      resetBlock.includes('insecure HTTP') || resetBlock.includes('Refusing'),
-      'must show error about insecure connection'
-    );
-  });
-});
-
-// ============================================================================
-// PR #22 Review Fixes
-// ============================================================================
-
-describe('Fix 7: Generic password reset flow must also validate HTTPS', () => {
-  it('commandReset generic flow should check for HTTPS before proceeding', () => {
-    const resetBlock = cliSource.match(
-      /async function commandReset[\s\S]*?^}/m
-    )?.[0];
-    assert.ok(resetBlock, 'commandReset function exists');
-
-    // The generic flow starts after the ClearAuth branch (if flags.clearauth)
-    // It should have its own HTTPS check before the generic flow logic
-    const genericFlowSection = resetBlock.split('flags.clearauth')[1];
-    assert.ok(genericFlowSection, 'generic flow section exists after clearauth branch');
-
-    assert.ok(
-      genericFlowSection.includes("startsWith('https://')") ||
-      genericFlowSection.includes('startsWith("https://")'),
-      'generic flow must check for https:// protocol on serviceUrl'
-    );
-    assert.ok(
-      genericFlowSection.includes('insecure') || genericFlowSection.includes('HTTPS'),
-      'generic flow must warn about insecure connections'
-    );
-  });
-});
-
-describe('Fix 8: Retry jitter to prevent thundering herd', () => {
-  it('ApiClient.request should add jitter to retry delays', () => {
-    const requestBlock = cliSource.match(
-      /async request\(method[\s\S]*?^\s{2}}/m
-    )?.[0];
-    assert.ok(requestBlock, 'request method exists');
-
-    assert.ok(
-      requestBlock.includes('Math.random()'),
-      'retry delay must include random jitter via Math.random()'
-    );
-  });
-});