run402 1.54.1 → 1.54.3

package/lib/argparse.mjs

@@ -0,0 +1,234 @@
+import { fail } from "./sdk-errors.mjs";
+import { resolveProjectId } from "./config.mjs";
+
+export function normalizeArgv(argv = []) {
+  const out = [];
+  for (const arg of argv ?? []) {
+    if (typeof arg === "string" && arg.startsWith("--") && arg.includes("=")) {
+      const eq = arg.indexOf("=");
+      out.push(arg.slice(0, eq), arg.slice(eq + 1));
+    } else {
+      out.push(arg);
+    }
+  }
+  return out;
+}
+
+export function hasHelp(args = []) {
+  return args.includes("--help") || args.includes("-h");
+}
+
+export function assertKnownFlags(args = [], knownFlags = [], flagsWithValues = []) {
+  const known = new Set(knownFlags);
+  const valueFlags = new Set(flagsWithValues);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (valueFlags.has(arg)) {
+      i += 1;
+      continue;
+    }
+    if (typeof arg !== "string" || !arg.startsWith("-") || arg === "-") continue;
+    if (known.has(arg)) continue;
+    failUnknownFlag(arg, known);
+  }
+}
+
+export function failUnknownFlag(flag, knownFlags = []) {
+  const known = [...knownFlags].filter((f) => typeof f === "string" && f.startsWith("-"));
+  const closest = closestFlag(flag, known);
+  fail({
+    code: "UNKNOWN_FLAG",
+    message: closest ? `Unknown flag: ${flag}. Did you mean ${closest}?` : `Unknown flag: ${flag}.`,
+    details: { flag, closest: closest ? [closest] : [] },
+  });
+}
+
+export function flagValue(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return null;
+  if (idx + 1 >= args.length) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${flag} requires a value`,
+      details: { flag },
+    });
+  }
+  return args[idx + 1];
+}
+
+export function parseIntegerFlag(name, value, { min = 1, max = Number.POSITIVE_INFINITY, def } = {}) {
+  if (value === undefined || value === null) {
+    if (def !== undefined) return def;
+    fail({
+      code: "BAD_FLAG",
+      message: `${name} requires an integer value`,
+      details: { flag: name },
+    });
+  }
+  const raw = String(value);
+  if (!/^-?\d+$/.test(raw)) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${name} must be an integer, got: ${raw}`,
+      details: { flag: name, value: raw },
+    });
+  }
+  const n = Number.parseInt(raw, 10);
+  if (n < min) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${name} must be >= ${min}, got: ${n}`,
+      details: { flag: name, value: n, min },
+    });
+  }
+  if (n > max) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${name} must be <= ${max}, got: ${n}`,
+      details: { flag: name, value: n, max },
+    });
+  }
+  return n;
+}
+
+export function failBadProjectId(value) {
+  fail({
+    code: "BAD_PROJECT_ID",
+    message: `Argument '${value}' is not a project id. Project IDs must start with 'prj_'.`,
+    hint: "Omit the project id to use the active project, or pass the full prj_... id.",
+    details: { value, expected_prefix: "prj_" },
+  });
+}
+
+/**
+ * Validate a webhook URL: parse it locally and reject non-https:// schemes.
+ *
+ * Scope (GH-192): scheme-only validation. Reject `javascript:`, `file:`,
+ * `http:`, `data:`, `ftp:`, etc. before the request leaves the CLI process.
+ * Server-side SSRF defenses (private-IP filtering, DNS rebinding, IMDS
+ * blocking) live on the gateway, not here — this helper is the cheap
+ * client-side guard against the obvious classes.
+ *
+ * No-op when `url` is null/undefined/empty so callers can pass optional
+ * flag values directly. Required-vs-optional handling stays at the call
+ * site (e.g. `webhooks register` does its own missing-flag check first).
+ *
+ * On failure: `fail()` writes the canonical error envelope and exits 1.
+ *
+ * @param {string|null|undefined} url - The webhook URL to validate.
+ * @param {string} fieldName - The CLI flag name for the error envelope (e.g. "--url", "--webhook").
+ */
+export function validateWebhookUrl(url, fieldName = "--url") {
+  if (!url) return;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    fail({
+      code: "BAD_WEBHOOK_URL",
+      message: `${fieldName} is not a valid URL: ${JSON.stringify(url)}`,
+      field: fieldName,
+      hint: "Webhook URL must be a fully-qualified https:// URL.",
+      details: { flag: fieldName, value: url },
+    });
+  }
+  if (parsed.protocol !== "https:") {
+    fail({
+      code: "BAD_WEBHOOK_URL",
+      message: `${fieldName} must use https://, got ${parsed.protocol}`,
+      field: fieldName,
+      hint: "Webhook URLs must be https:// for transport security.",
+      details: { flag: fieldName, value: url, scheme: parsed.protocol },
+    });
+  }
+}
+
+export function positionalArgs(args = [], flagsWithValues = []) {
+  const valueFlags = new Set(flagsWithValues);
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (valueFlags.has(arg)) {
+      i += 1;
+      continue;
+    }
+    if (typeof arg === "string" && arg.startsWith("-")) continue;
+    out.push(arg);
+  }
+  return out;
+}
+
+// Resolve a positional project_id argument with active-project fallback (GH-102, GH-187).
+// If the first positional starts with "prj_", treat it as the project id and
+// strip it from the rest. Otherwise, fall through to the active project from
+// the keystore. Callers can tighten the legacy shorthand when a bare non-prj
+// positional is more likely a mistyped project id than an argument for the
+// active project.
+//
+// Options:
+//   rejectBareFirst:                   when true, error if the first positional
+//                                      is non-empty and doesn't start with "prj_".
+//   rejectBareFirstWhenFlagPresent:    when one of these flags is present in
+//                                      args AND the first positional doesn't
+//                                      start with "prj_", error out.
+//   maxBarePositionals + valueFlags:   when set, count the bare (non-flag)
+//                                      positionals using `positionalArgs(args,
+//                                      valueFlags)` and error if the count
+//                                      exceeds maxBarePositionals.
+export function resolvePositionalProject(args, opts = {}) {
+  const first = Array.isArray(args) ? args[0] : undefined;
+  if (typeof first === "string" && first.startsWith("prj_")) {
+    return { projectId: first, rest: args.slice(1) };
+  }
+  if (
+    typeof first === "string" &&
+    first.length > 0 &&
+    !first.startsWith("-") &&
+    Array.isArray(opts.rejectBareFirstWhenFlagPresent) &&
+    opts.rejectBareFirstWhenFlagPresent.some((flag) => args.includes(flag))
+  ) {
+    failBadProjectId(first);
+  }
+  if (typeof first === "string" && first.length > 0 && !first.startsWith("-") && opts.rejectBareFirst) {
+    failBadProjectId(first);
+  }
+  if (typeof first === "string" && first.length > 0 && !first.startsWith("-") && opts.maxBarePositionals !== undefined) {
+    const bare = positionalArgs(args, opts.valueFlags ?? []);
+    if (bare.length > opts.maxBarePositionals) {
+      failBadProjectId(first);
+    }
+  }
+  return { projectId: resolveProjectId(null), rest: Array.isArray(args) ? args : [] };
+}
+
+function closestFlag(flag, candidates) {
+  let best = null;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const d = levenshtein(flag, candidate);
+    if (d < bestDistance) {
+      best = candidate;
+      bestDistance = d;
+    }
+  }
+  if (!best) return null;
+  return bestDistance <= 3 ? best : null;
+}
+
+function levenshtein(a, b) {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const curr = Array.from({ length: b.length + 1 }, () => 0);
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        prev[j] + 1,
+        prev[j - 1] + cost,
+      );
+    }
+    for (let j = 0; j <= b.length; j++) prev[j] = curr[j];
+  }
+  return prev[b.length];
+}

package/lib/auth.mjs

@@ -93,7 +93,7 @@ Notes:
 
 Examples:
   run402 auth settings --allow-password-set true
-  run402 auth settings --allow-password-set false --project abc123
+  run402 auth settings --allow-password-set false --project prj_abc123
 `,
   providers: `run402 auth providers — List available auth providers
 
@@ -105,7 +105,7 @@ Options:
 
 Examples:
   run402 auth providers
-  run402 auth providers --project abc123
+  run402 auth providers --project prj_abc123
 `,
 };
 
@@ -187,10 +187,23 @@ async function settings(args) {
       message: "Missing --allow-password-set <true|false>",
     });
   }
+  // Reject anything that isn't literally "true" or "false". Without this guard,
+  // the previous `=== "true"` coercion silently turned every other input
+  // (including "1", "yes", "TRUE", "bogus") into `false` and printed
+  // `{"status":"ok"}`, giving the user the OPPOSITE of what they likely
+  // intended for this security-adjacent flag. See GH-204.
+  if (allowPasswordSet !== "true" && allowPasswordSet !== "false") {
+    fail({
+      code: "BAD_FLAG",
+      message: "--allow-password-set must be 'true' or 'false'",
+      hint: "Use the literal strings 'true' or 'false'.",
+    });
+  }
 
+  const allow = allowPasswordSet === "true";
   try {
-    await getSdk().auth.settings(projectId, { allow_password_set: allowPasswordSet === "true" });
-    console.log(JSON.stringify({ status: "ok", allow_password_set: allowPasswordSet === "true" }));
+    await getSdk().auth.settings(projectId, { allow_password_set: allow });
+    console.log(JSON.stringify({ status: "ok", allow_password_set: allow }));
   } catch (err) {
     reportSdkError(err);
   }

package/lib/billing.mjs

@@ -84,6 +84,41 @@ Options:
 Examples:
   run402 billing history user@example.com
   run402 billing history 0x1234... --limit 100
+`,
+  balance: `run402 billing balance — Show balance for an email or wallet
+
+Usage:
+  run402 billing balance <identifier>
+
+Arguments:
+  <identifier>        Email address or wallet (0x...)
+
+Examples:
+  run402 billing balance user@example.com
+  run402 billing balance 0x1234abcd...
+`,
+  "create-email": `run402 billing create-email — Create an email billing account
+
+Usage:
+  run402 billing create-email <email>
+
+Arguments:
+  <email>             Email address to register as a billing account
+
+Examples:
+  run402 billing create-email user@example.com
+`,
+  "link-wallet": `run402 billing link-wallet — Link a wallet to an email billing account
+
+Usage:
+  run402 billing link-wallet <account_id> <wallet>
+
+Arguments:
+  <account_id>        Billing account ID (e.g. acct_abc123)
+  <wallet>            Wallet address (0x...) to link
+
+Examples:
+  run402 billing link-wallet acct_abc123 0x1234abcd...
 `,
 };
 

package/lib/blob.mjs

@@ -37,6 +37,7 @@ import { pipeline } from "node:stream/promises";
 import { resolveProject, resolveProjectId, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag } from "./argparse.mjs";
 
 const HELP = `run402 blob — Direct-to-S3 blob storage
 
@@ -62,13 +63,13 @@ Options:
   --ttl <seconds>     Signed-URL TTL (sign only; default 3600, max 604800)
 
 Examples:
-  run402 blob put ./artifact.tgz --project abc123
-  run402 blob put ./dist/**/*.png --project abc123 --key assets/
-  run402 blob put huge.bin --project abc123 --immutable
-  run402 blob get images/logo.png --output /tmp/logo.png --project abc123
-  run402 blob ls --project abc123 --prefix images/
-  run402 blob rm images/logo.png --project abc123
-  run402 blob sign images/logo.png --project abc123 --ttl 600
+  run402 blob put ./artifact.tgz --project prj_abc123
+  run402 blob put ./dist/**/*.png --project prj_abc123 --key assets/
+  run402 blob put huge.bin --project prj_abc123 --immutable
+  run402 blob get images/logo.png --output /tmp/logo.png --project prj_abc123
+  run402 blob ls --project prj_abc123 --prefix images/
+  run402 blob rm images/logo.png --project prj_abc123
+  run402 blob sign images/logo.png --project prj_abc123 --ttl 600
 `;
 
 const SUB_HELP = {
@@ -90,9 +91,9 @@ Options:
   --json              Emit NDJSON progress events on stdout (for agent consumption)
 
 Examples:
-  run402 blob put ./artifact.tgz --project abc123
-  run402 blob put ./dist/**/*.png --project abc123 --key assets/
-  run402 blob put huge.bin --project abc123 --immutable --concurrency 8
+  run402 blob put ./artifact.tgz --project prj_abc123
+  run402 blob put ./dist/**/*.png --project prj_abc123 --key assets/
+  run402 blob put huge.bin --project prj_abc123 --immutable --concurrency 8
 `,
   get: `run402 blob get — Download a blob by key
 
@@ -107,7 +108,7 @@ Options:
   --project <id>      Project ID (defaults to active project)
 
 Examples:
-  run402 blob get images/logo.png --output /tmp/logo.png --project abc123
+  run402 blob get images/logo.png --output /tmp/logo.png --project prj_abc123
 `,
   ls: `run402 blob ls — List blob keys in a project
 
@@ -120,8 +121,8 @@ Options:
   --limit <n>         Max results (default 100, max 1000)
 
 Examples:
-  run402 blob ls --project abc123
-  run402 blob ls --project abc123 --prefix images/ --limit 500
+  run402 blob ls --project prj_abc123
+  run402 blob ls --project prj_abc123 --prefix images/ --limit 500
 `,
   rm: `run402 blob rm — Delete a blob
 
@@ -135,7 +136,7 @@ Options:
   --project <id>      Project ID (defaults to active project)
 
 Examples:
-  run402 blob rm images/logo.png --project abc123
+  run402 blob rm images/logo.png --project prj_abc123
 `,
   sign: `run402 blob sign — Create a presigned download URL for a blob
 
@@ -150,7 +151,7 @@ Options:
   --ttl <seconds>     Signed-URL TTL (default 3600, max 604800)
 
 Examples:
-  run402 blob sign reports/2025-q4.pdf --project abc123 --ttl 600
+  run402 blob sign reports/2025-q4.pdf --project prj_abc123 --ttl 600
 `,
   diagnose: `run402 blob diagnose — Inspect the live CDN state for a public blob URL
 
@@ -186,7 +187,38 @@ function die(msg, exit_code = 1) {
   fail({ code: "BAD_USAGE", message: msg, exit_code });
 }
 
-function parseArgs(args) {
+function dieApiFailure(prefix, http, body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    const envelope = { status: "error", http, ...body };
+    if (!envelope.message && envelope.error) envelope.message = envelope.error;
+    console.error(JSON.stringify(envelope));
+    process.exit(1);
+  }
+  fail({
+    message: `${prefix}: HTTP ${http}${typeof body === "string" && body ? `: ${body.slice(0, 500)}` : ""}`,
+    details: { http },
+  });
+}
+
+function parseArgs(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  const valueFlags = ["--project", "--key", "--concurrency", "--prefix", "--limit", "--output", "-o", "--ttl"];
+  assertKnownFlags(args, [
+    "--project",
+    "--key",
+    "--private",
+    "--immutable",
+    "--concurrency",
+    "--no-resume",
+    "--json",
+    "--prefix",
+    "--limit",
+    "--output",
+    "-o",
+    "--ttl",
+    "--help",
+    "-h",
+  ], valueFlags);
   const out = { positional: [], project: null, key: null, private: false, immutable: false,
                  concurrency: 4, resume: true, json: false, prefix: null, limit: null,
                  output: null, ttl: null };
@@ -196,13 +228,13 @@ function parseArgs(args) {
     else if (a === "--key") out.key = args[++i];
     else if (a === "--private") out.private = true;
     else if (a === "--immutable") out.immutable = true;
-    else if (a === "--concurrency") out.concurrency = parseInt(args[++i], 10);
+    else if (a === "--concurrency") out.concurrency = parseIntegerFlag("--concurrency", args[++i], { min: 1 });
     else if (a === "--no-resume") out.resume = false;
     else if (a === "--json") out.json = true;
     else if (a === "--prefix") out.prefix = args[++i];
-    else if (a === "--limit") out.limit = parseInt(args[++i], 10);
+    else if (a === "--limit") out.limit = parseIntegerFlag("--limit", args[++i], { min: 1, max: 1000 });
     else if (a === "--output" || a === "-o") out.output = args[++i];
-    else if (a === "--ttl") out.ttl = parseInt(args[++i], 10);
+    else if (a === "--ttl") out.ttl = parseIntegerFlag("--ttl", args[++i], { min: 1, max: 604800 });
     else if (!a.startsWith("--")) out.positional.push(a);
   }
   return out;
@@ -284,7 +316,7 @@ async function putOne(project, filePath, opts) {
       immutable: opts.immutable,
       sha256,
     });
-    if (init.status !== 201) die(`Init failed: HTTP ${init.status}: ${JSON.stringify(init.body)}`);
+    if (init.status !== 201) dieApiFailure("Init failed", init.status, init.body);
     initRes = init.body;
     saveState({
       upload_id: initRes.upload_id,
@@ -330,7 +362,7 @@ async function putOne(project, filePath, opts) {
     ? { parts: etags.map((e, i) => ({ part_number: i + 1, etag: e.etag })) }
     : {};
   const complete = await apiFetch(`${API}/storage/v1/uploads/${state.upload_id}/complete`, "POST", project, body);
-  if (complete.status !== 200) die(`Complete failed: HTTP ${complete.status}: ${JSON.stringify(complete.body)}`);
+  if (complete.status !== 200) dieApiFailure("Complete failed", complete.status, complete.body);
 
   removeState(state.upload_id);
   log(opts, { event: "done", ...complete.body });
@@ -565,7 +597,8 @@ export async function run(sub, args) {
     console.log(HELP);
     process.exit(0);
   }
-  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
+  args = normalizeArgv(args);
+  if (Array.isArray(args) && hasHelp(args)) {
     console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }

package/lib/config.mjs

@@ -14,8 +14,27 @@ export const ALLOWANCE_FILE = getAllowancePath();
 export const PROJECTS_FILE = getKeystorePath();
 export const API = getApiBase();
 
+/**
+ * Wraps core's `readAllowance()` and converts the malformed-shape throw
+ * (GH-194) into the canonical CLI failure envelope. Without this guard, every
+ * CLI subcommand that touches the allowance leaks a Node stack trace and
+ * source paths the moment a user has a malformed `allowance.json`.
+ *
+ * The unparseable-JSON case still returns `null` (matching the historical
+ * "no_allowance" UX); only valid-JSON-but-wrong-shape becomes a structured
+ * error with `code: BAD_ALLOWANCE_FILE`.
+ */
 export function readAllowance() {
-  return coreReadAllowance();
+  try {
+    return coreReadAllowance();
+  } catch (err) {
+    fail({
+      code: "BAD_ALLOWANCE_FILE",
+      message: err?.message ?? "allowance.json is malformed",
+      hint: "Back up ~/.config/run402/allowance.json and run 'run402 init' to recreate it.",
+      details: { path: ALLOWANCE_FILE },
+    });
+  }
 }
 
 export function saveAllowance(data) {

package/lib/contracts.mjs

@@ -83,6 +83,47 @@ Usage:
 
 Usage:
   run402 contracts delete <project_id> <wallet_id> --confirm
+`,
+  "get-wallet": `run402 contracts get-wallet — Get wallet metadata + live balance
+
+Usage:
+  run402 contracts get-wallet <project_id> <wallet_id>
+
+Arguments:
+  <project_id>        Project ID that owns the wallet
+  <wallet_id>         Wallet ID (e.g. cwlt_abc123)
+
+Examples:
+  run402 contracts get-wallet prj_abc123 cwlt_abc123
+`,
+  "list-wallets": `run402 contracts list-wallets — List all KMS wallets for a project
+
+Usage:
+  run402 contracts list-wallets <project_id>
+
+Arguments:
+  <project_id>        Project ID to list wallets for
+
+Notes:
+  - Includes deleted wallets
+
+Examples:
+  run402 contracts list-wallets prj_abc123
+`,
+  status: `run402 contracts status — Get a contract call's status and receipt
+
+Usage:
+  run402 contracts status <project_id> <call_id>
+
+Arguments:
+  <project_id>        Project ID that submitted the call
+  <call_id>           Contract call ID returned from 'contracts call'
+
+Notes:
+  - Returns status, gas used, gas cost (USD-micros), and receipt
+
+Examples:
+  run402 contracts status prj_abc123 ccall_abc123
 `,
 };