@vainplex/shieldapi-cli 1.2.1 → 1.3.0

package/README.md

@@ -109,18 +109,42 @@ if [ $? -eq 1 ]; then
 fi
 ```
 
-## Security
+## Security & Privacy
 
-- **Passwords are hashed locally** with SHA-1 before any network request. Plaintext never leaves your machine.
-- **Private keys are never persisted** to disk, logs, or displayed in output.
-- **No telemetry** — zero phone-home, zero analytics.
-- **Shell history warning** — the CLI warns when passwords are passed as arguments (use `--stdin` for sensitive passwords).
+### Your password never leaves your machine in plaintext
+
+1. Your password is **SHA-1 hashed locally** on your machine — plaintext never touches the network.
+2. The SHA-1 hash is sent over **HTTPS** to the ShieldAPI server.
+3. The server uses the [HIBP k-Anonymity protocol](https://haveibeenpwned.com/API/v3#SearchingPwnedPasswordsByRange) — only the **first 5 characters** of the hash go to the upstream breach database. The full hash never leaves ShieldAPI.
+
+**Want true end-to-end k-Anonymity?** Use the `check-password-range` endpoint directly via the API — it only accepts a 5-character prefix and returns all matching suffixes, so you can check locally.
+
+### Avoiding shell history exposure
+
+Passing a password as a CLI argument stores it in your shell history (`~/.bash_history`). Use these safer alternatives:
 
 ```bash
-# Secure password checking (avoids shell history)
-echo "mysecretpassword" | shieldapi password dummy --stdin
+# Option 1: Read from stdin (recommended)
+read -sp "Password: " PW && echo -n "$PW" | shieldapi password dummy --stdin --demo
+
+# Option 2: Pipe directly
+echo -n "mypassword" | shieldapi password dummy --stdin --demo
+
+# Option 3: Hash first, then check the hash
+shieldapi hash "mypassword"           # → shows SHA-1 locally
+shieldapi password "7C6A18..." --hash --demo  # check by hash, not password
+
+# Option 4: Clear history after
+shieldapi password "test" --demo && history -d $(history 1 | awk '{print $1}')
 ```
 
+### Other security guarantees
+
+- **Private keys are never persisted** to disk, logs, or displayed in output.
+- **No telemetry** — zero phone-home, zero analytics.
+- **HTTPS only** — all API communication is encrypted.
+- **Shell history warning** — the CLI warns when passwords are passed as arguments.
+
 ## How x402 Works
 
 [x402](https://x402.org) is an open protocol for HTTP payments. Instead of API keys:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vainplex/shieldapi-cli",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Security intelligence from your terminal. Pay-per-request with USDC.",
   "type": "module",
   "bin": {

package/src/commands/password.js

@@ -13,11 +13,15 @@ import { exitCodeFromResult, exitCodeFromError, EXIT } from '../lib/exit.js';
 function readStdin() {
   return new Promise((resolve, reject) => {
     let data = '';
-    const rl = createInterface({ input: process.stdin });
-    rl.on('line', (line) => { data = line; rl.close(); });
-    rl.on('close', () => resolve(data.trim()));
-    rl.on('error', reject);
-    setTimeout(() => { rl.close(); reject(new Error('Stdin timeout — no input received')); }, 10000);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data.trim()));
+    process.stdin.on('error', reject);
+    setTimeout(() => {
+      process.stdin.destroy();
+      if (data) resolve(data.trim());
+      else reject(new Error('Stdin timeout — no input received'));
+    }, 10000);
   });
 }
 
@@ -31,8 +35,8 @@ export async function passwordCommand(password, opts) {
   try {
     let hash;
 
-    // --stdin: read password from stdin
     if (opts.stdin) {
+      // --stdin: read password from stdin, ignore positional argument
       if (!opts.quiet) {
         process.stderr.write(chalk.gray('Reading password from stdin...\n'));
       }
@@ -43,6 +47,13 @@ export async function passwordCommand(password, opts) {
         return;
       }
       hash = createHash('sha1').update(stdinPassword).digest('hex').toUpperCase();
+    } else if (!password) {
+      // No password argument and no --stdin
+      process.stderr.write(chalk.red('Error: Provide a password argument or use --stdin.\n'));
+      process.stderr.write(chalk.gray('  shieldapi password "mypassword" --demo\n'));
+      process.stderr.write(chalk.gray('  echo -n "mypassword" | shieldapi password --stdin --demo\n'));
+      process.exitCode = EXIT.USAGE;
+      return;
     } else if (opts.hash) {
       // --hash: treat input as pre-computed SHA-1
       hash = password.toUpperCase();
@@ -56,7 +67,7 @@ export async function passwordCommand(password, opts) {
       hash = createHash('sha1').update(password).digest('hex').toUpperCase();
 
       // Shell history warning (SR-5)
-      if (!opts.quiet && process.stdout.isTTY) {
+      if (!opts.quiet && process.stderr.isTTY) {
         process.stderr.write(
           chalk.yellow('⚠  Password may appear in shell history. Use --stdin for sensitive passwords.\n')
         );

package/src/index.js

@@ -14,7 +14,7 @@ export function run(argv) {
   program
     .name('shieldapi')
     .description('🛡️  ShieldAPI CLI — Security intelligence from your terminal. Pay-per-request with USDC.')
-    .version('1.2.1')
+    .version('1.3.0')
     .option('--wallet <key>', 'Private key for x402 payments (or set SHIELDAPI_WALLET_KEY)')
     .option('--json', 'Output raw JSON instead of formatted output')
     .option('--no-color', 'Disable colors')
@@ -24,7 +24,7 @@ export function run(argv) {
   program
     .command('password')
     .description('Check a password against breach databases')
-    .argument('<password>', 'Password to check (hashed locally with SHA-1)')
+    .argument('[password]', 'Password to check (hashed locally with SHA-1)')
     .option('--demo', 'Use demo mode (free, no wallet needed)')
     .option('--stdin', 'Read password from stdin (avoids shell history)')
     .option('--hash', 'Treat input as pre-computed SHA-1 hash')