requestshield 0.1.5 → 0.1.7

package/src/api-client.mjs

@@ -1,192 +1,138 @@
 // @ts-check
-
 import { CliError } from "./errors.mjs";
+import { validateBearerToken, validatedUrl } from "./config.mjs";
 
-const API_ENDPOINTS = {
-  SIGNIN: "/v1/cli/signin",
-  SIGNIN_TOKEN: "/v1/cli/signin/token",
-  KEYS_ROTATE: "/v1/cli/keys/rotate",
-  INTEGRATION_CONTRACT: "/v1/integration-contract",
-  APPLICATIONS: "/v1/applications",
-};
+const APPLICATIONS = "/v1/applications";
+const MAX_BODY_BYTES = 1024 * 1024;
+const API_ERRORS = new Set(["invalid_request", "invalid_token", "insufficient_scope", "application_not_found",
+  "idempotency_conflict", "secret_revoked", "dependency_unavailable", "rate_limited"]);
 
 export class ManagementApiClient {
-  /** @param {{ baseUrl: string, fetchImpl?: typeof fetch }} options */
-  constructor({ baseUrl, fetchImpl = fetch }) {
-    let url;
-    try {
-      url = new URL(baseUrl);
-    } catch {
-      throw new CliError("REQUESTSHIELD_API_URL must be a valid URL", { exitCode: 2 });
-    }
-    if (url.protocol !== "https:" && !isLoopback(url)) {
-      throw new CliError("The management API must use HTTPS except on loopback", {
-        exitCode: 2,
-      });
-    }
-    this.baseUrl = url.href.replace(/\/$/, "");
+  /** @param {{baseUrl: string, fetchImpl?: typeof fetch, timeoutMs?: number}} options */
+  constructor({baseUrl, fetchImpl = fetch, timeoutMs = 15_000}) {
+    this.baseUrl = validatedUrl(baseUrl, "API_URL");
     this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
   }
 
-  async startSignin() {
-    return this.#request(API_ENDPOINTS.SIGNIN, {
-      method: "POST",
-      body: JSON.stringify({ client: "requestshield-cli" }),
-    });
+  /** @param {string} token @param {{limit?: number, cursor?: string}} [options] */
+  listApps(token, options = {}) {
+    const query = new URLSearchParams();
+    if (options.limit !== undefined) query.set("limit", String(options.limit));
+    if (options.cursor !== undefined) query.set("cursor", options.cursor);
+    return this.#request(`${APPLICATIONS}${query.size ? `?${query}` : ""}`, token, "GET");
   }
 
-  /** @param {string} deviceCode */
-  async pollSignin(deviceCode) {
-    return this.#request(
-      API_ENDPOINTS.SIGNIN_TOKEN,
-      { method: "POST", body: JSON.stringify({ deviceCode }) },
-      true,
-    );
-  }
+  /** @param {string} token @param {string} appKey */
+  getApp(token, appKey) { return this.#request(appPath(appKey), token, "GET"); }
 
-  /** @param {string} accessToken */
-  async rotateKeys(accessToken) {
-    return this.#request(API_ENDPOINTS.KEYS_ROTATE, {
-      method: "POST",
-      headers: { Authorization: `Bearer ${accessToken}` },
-      body: "{}",
-    });
+  /** @param {string} token @param {{name: string, idempotencyKey: string}} options */
+  createApp(token, {name, idempotencyKey}) {
+    return this.#request(APPLICATIONS, token, "POST", {name}, idempotencyKey);
   }
 
-  /** @param {string} accessToken */
-  async integrationContract(accessToken) {
-    return this.#request(API_ENDPOINTS.INTEGRATION_CONTRACT, {
-      method: "GET",
-      headers: {
-        Accept: "application/json",
-        Authorization: `Bearer ${accessToken}`,
-      },
-    });
+  /** @param {string} token @param {string} appKey @param {{name: string, idempotencyKey: string}} options */
+  renameApp(token, appKey, {name, idempotencyKey}) {
+    return this.#request(appPath(appKey), token, "PATCH", {name}, idempotencyKey);
   }
 
-  /** @param {string} accessToken */
-  async listApps(accessToken) {
-    return this.#request(API_ENDPOINTS.APPLICATIONS, {
-      method: "GET",
-      headers: {
-        Accept: "application/json",
-        Authorization: `Bearer ${accessToken}`,
-      },
-    });
+  /** @param {string} token @param {string} appKey @param {{enabled: boolean, idempotencyKey: string}} options */
+  setAppEnabled(token, appKey, {enabled, idempotencyKey}) {
+    return this.#request(`${appPath(appKey)}/${enabled ? "enable" : "disable"}`, token, "POST", undefined, idempotencyKey);
   }
 
-  /** @param {string} accessToken @param {string} appKey */
-  async getApp(accessToken, appKey) {
-    return this.#request(
-      `${API_ENDPOINTS.APPLICATIONS}/${encodeURIComponent(appKey)}`,
-      {
-        method: "GET",
-        headers: {
-          Accept: "application/json",
-          Authorization: `Bearer ${accessToken}`,
-        },
-      },
-    );
+  /** @param {string} token @param {string} appKey @param {{idempotencyKey: string}} options */
+  rotateSecret(token, appKey, {idempotencyKey}) {
+    return this.#request(`${appPath(appKey)}/secret/rotate`, token, "POST", undefined, idempotencyKey);
   }
 
-  /**
-   * @param {string} accessToken
-   * @param {string} appKey
-   * @param {{ from?: string, to?: string, granularity?: string }} options
-   */
-  async challengeVolume(accessToken, appKey, options) {
-    const query = new URLSearchParams();
-
-    if (options.from)
-      query.set("from", options.from);
-
-    if (options.to)
-      query.set("to", options.to);
-
-    if (options.granularity)
-      query.set("granularity", options.granularity);
-
-    const suffix = query.size > 0 ? `?${query}` : "";
-
-    const endpoint =
-      `${API_ENDPOINTS.APPLICATIONS}/` +
-      `${encodeURIComponent(appKey)}/challenge-volume` +
-      suffix;
+  /** @param {string} token @param {string} appKey */
+  revealSecret(token, appKey) { return this.#request(`${appPath(appKey)}/secret/reveal`, token, "POST"); }
 
-    return this.#request(endpoint, {
-      method: "GET",
-      headers: {
-        Accept: "application/json",
-        Authorization: `Bearer ${accessToken}`,
-      },
-    });
-  }
-
-
-  /** @param {string} accessToken @param {string} appKey */
-  async getBilling(accessToken, appKey) {
-    return this.#request(
-      `${API_ENDPOINTS.APPLICATIONS}/${encodeURIComponent(appKey)}/billing`,
-      {
-        method: "GET",
-        headers: {
-          Accept: "application/json",
-          Authorization: `Bearer ${accessToken}`,
-        },
-      },
-    );
+  /** @param {string} token @param {string} appKey @param {{idempotencyKey: string}} options */
+  revokeSecret(token, appKey, {idempotencyKey}) {
+    return this.#request(`${appPath(appKey)}/secret/revoke`, token, "POST", undefined, idempotencyKey);
   }
 
-  /**
-   * @param {string} path
-   * @param {RequestInit} init
-   * @param {boolean} [allowErrorBody]
+  /** No retries: a lost mutation response may represent a committed operation.
+   * @param {string} path @param {string} token @param {string} method
+   * @param {{name: string}} [payload] @param {string} [idempotencyKey]
    */
-  async #request(path, init, allowErrorBody = false) {
-    let response;
-    try {
-      response = await this.fetchImpl(`${this.baseUrl}${path}`, {
-        ...init,
-        headers: { "Content-Type": "application/json", ...init.headers },
-        signal: AbortSignal.timeout(15_000),
-      });
-    } catch (error) {
-      throw new CliError(`Could not reach the RequestShield API: ${messageOf(error)}`, {
-        code: "NETWORK_ERROR",
-        exitCode: 7,
-      });
-    }
-
-    const text = await response.text();
-    let body = {};
-    if (text !== "") {
-      try {
-        body = JSON.parse(text);
-      } catch {
-        throw new CliError("The RequestShield API returned invalid JSON", {
-          code: "INVALID_RESPONSE",
-        });
+  async #request(path, token, method, payload, idempotencyKey) {
+    const headers = {Accept: "application/json", Authorization: `Bearer ${validateBearerToken(token)}`};
+    if (idempotencyKey !== undefined) {
+      if (!/^[A-Za-z0-9._~-]{1,128}$/.test(idempotencyKey)) {
+        throw new CliError("Invalid idempotency key", {code: "INVALID_ARGUMENT", exitCode: 2});
       }
+      Object.assign(headers, {"Idempotency-Key": idempotencyKey});
     }
-    if (!response.ok && !allowErrorBody) {
-      const nestedError = body && typeof body === "object" ? Reflect.get(body, "error") : undefined;
-      const detail = objectString(nestedError, "message")
-        ?? objectString(body, "message")
-        ?? `HTTP ${response.status}`;
-      const exitCode = response.status === 401 || response.status === 403 ? 3 : 1;
-      throw new CliError(`RequestShield API error: ${detail}`, {
-        code: objectString(nestedError, "code") ?? objectString(body, "code") ?? "API_ERROR",
-        exitCode,
-      });
+    if (payload !== undefined) Object.assign(headers, {"Content-Type": "application/json"});
+    const controller = new AbortController();
+    /** @type {ReadableStreamDefaultReader<Uint8Array> | undefined} */
+    let reader;
+    let expired = false;
+    const deadline = new Promise((_, reject) => {
+      controller.signal.addEventListener("abort", () => reject(new CliError(
+        "The RequestShield API request timed out. Check connectivity and try again.",
+        {code: "REQUEST_TIMEOUT", exitCode: 7},
+      )), {once: true});
+    });
+    const timer = setTimeout(() => { expired = true; controller.abort(); }, this.timeoutMs);
+    try {
+      const operation = (async () => {
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+          method, headers, ...(payload !== undefined ? {body: JSON.stringify(payload)} : {}),
+          signal: controller.signal, redirect: "error", credentials: "omit", cache: "no-store",
+        });
+        if (expired) { void response.body?.cancel().catch(() => {}); throw new Error(); }
+        if (Number(response.headers.get("content-length")) > MAX_BODY_BYTES) {
+          void response.body?.cancel().catch(() => {}); throw invalidResponse();
+        }
+        const chunks = [];
+        let size = 0;
+        if (response.body) {
+          reader = response.body.getReader();
+          while (true) {
+            const {done, value} = await reader.read();
+            if (expired) throw new Error();
+            if (done) break;
+            size += value.length;
+            if (size > MAX_BODY_BYTES) throw invalidResponse();
+            chunks.push(value);
+          }
+        }
+        let body;
+        try { body = JSON.parse(new TextDecoder("utf-8", {fatal: true}).decode(Buffer.concat(chunks))); }
+        catch { if (response.ok) throw invalidResponse(); }
+        if (!response.ok) {
+          const providerCode = objectString(body?.error, "code");
+          const safeCode = providerCode && API_ERRORS.has(providerCode) ? providerCode : undefined;
+          const guidance = response.status === 401 ? "; run `requestshield signin` again"
+            : safeCode === "insufficient_scope" ? "; this session lacks the required permissions" : "";
+          throw new CliError(`RequestShield API error: HTTP ${response.status}${safeCode ? ` (${safeCode})` : ""}${guidance}`, {
+            code: response.status === 401 ? "UNAUTHENTICATED" : "API_ERROR",
+            exitCode: response.status === 401 || response.status === 403 ? 3 : 1,
+            httpStatus: response.status, apiErrorCode: safeCode,
+          });
+        }
+        if (!body || typeof body !== "object" || Array.isArray(body)) throw invalidResponse();
+        return {ok: true, status: response.status, body, replayed: response.headers.get("Idempotency-Replayed") === "true"};
+      })();
+      return await Promise.race([operation, /** @type {Promise<never>} */ (deadline)]);
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw new CliError("Could not reach the RequestShield API", {code: "NETWORK_ERROR", exitCode: 7});
+    } finally {
+      clearTimeout(timer);
+      if (reader) { void reader.cancel().catch(() => {}); }
+      controller.abort();
     }
-    return { ok: response.ok, status: response.status, body };
   }
 }
 
-/** @param {URL} url */
-function isLoopback(url) {
-  return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
-}
+/** @param {string} appKey */
+function appPath(appKey) { return `${APPLICATIONS}/${encodeURIComponent(appKey)}`; }
+function invalidResponse() { return new CliError("The RequestShield API returned an invalid or oversized response", {code: "INVALID_RESPONSE"}); }
 
 /** @param {unknown} value @param {string} property */
 export function objectString(value, property) {
@@ -194,8 +140,3 @@ export function objectString(value, property) {
   const found = Reflect.get(value, property);
   return typeof found === "string" ? found : undefined;
 }
-
-/** @param {unknown} error */
-function messageOf(error) {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/args.mjs

@@ -1,188 +1,145 @@
 // @ts-check
-
 import { CliError } from "./errors.mjs";
 
 const HELP = `RequestShield CLI
 
 Usage:
-  requestshield signin
-  requestshield keys create [--yes]
-  requestshield contract
-  requestshield apps list [--json]
+  requestshield signin [--no-open]
+  requestshield auth status [--json]
+  requestshield signout
+  requestshield keys create --app-name <name> [--idempotency-key <key>]
+  requestshield keys rotate <app-key> [--idempotency-key <key>] [--yes]
+  requestshield keys reveal <app-key> [--yes]
+  requestshield keys revoke <app-key> [--idempotency-key <key>] [--yes]
+  requestshield apps list [--json] [--limit <1-100>] [--cursor <cursor> | --all]
   requestshield apps get <app-key>
-  requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]
-  requestshield get billing <app-key>
+  requestshield apps rename <app-key> --name <name> [--idempotency-key <key>]
+  requestshield apps enable <app-key> [--idempotency-key <key>]
+  requestshield apps disable <app-key> [--idempotency-key <key>] [--yes]
   requestshield agent setup [--force]
   requestshield agent setup --codex [--force]
   requestshield agent setup --claude [--force]
   requestshield update check
   requestshield --help
-  requestshield --version`;
+  requestshield --version
+
+List defaults to one page. Use --all for a bounded complete listing.
+contract, challenge volume and get billing are not available yet.`;
 
 /**
- * @typedef {{ command: "help", help: string }
- * | { command: "version" }
- * | { command: "update-check" }
- * | { command: "signin" }
- * | { command: "keys-create", yes: boolean }
- * | { command: "contract" }
- * | { command: "apps-list", json: boolean }
- * | { command: "apps-get", appKey: string }
- * | { command: "challenge-volume", appKey: string, from?: string, to?: string, granularity?: string }
- * | { command: "billing-get", appKey: string }
- * | { command: "agent-setup", agent?: "codex" | "claude", force: boolean }} ParsedArgs
+ * @typedef {{command:"help",help:string} | {command:"version"|"update-check"|"signout"}
+ * | {command:"signin",noOpen:boolean} | {command:"auth-status",json:boolean}
+ * | {command:"keys-create",appName:string,yes:boolean,idempotencyKey?:string}
+ * | {command:"keys-rotate"|"keys-reveal"|"keys-revoke",appKey:string,yes:boolean,idempotencyKey?:string}
+ * | {command:"apps-list",json:boolean,all:boolean,limit?:number,cursor?:string}
+ * | {command:"apps-get",appKey:string}
+ * | {command:"apps-rename",appKey:string,name:string,yes:boolean,idempotencyKey?:string}
+ * | {command:"apps-enable"|"apps-disable",appKey:string,enabled:boolean,yes:boolean,idempotencyKey?:string}
+ * | {command:"agent-setup",agent?:"codex"|"claude",force:boolean}} ParsedArgs
  */
 
 /** @param {string[]} argv @returns {ParsedArgs} */
 export function parseArgs(argv) {
-  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-    return { command: "help", help: HELP };
-  }
-  if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "-V")) {
-    return { command: "version" };
-  }
-  if (argv[0] === "update" && argv[1] === "check") {
-    assertOnly(argv.slice(2), new Set());
-    return { command: "update-check" };
-  }
-  if (argv[0] === "signin") {
-    assertOnly(argv.slice(1), new Set());
-    return { command: "signin" };
+  if (!argv.length || argv.includes("--help") || argv.includes("-h")) return {command:"help",help:HELP};
+  if (argv.length === 1 && ["--version","-v","-V"].includes(argv[0])) return {command:"version"};
+  const [group, action] = argv;
+  if (group === "contract" || group === "challenge" && action === "volume" || group === "get" && action === "billing") {
+    throw new CliError("This command is not available: its Management API endpoint has not been implemented.", {code:"COMMAND_UNAVAILABLE",exitCode:2});
   }
-  if (argv[0] === "keys" && argv[1] === "create") {
-    assertOnly(argv.slice(2), new Set(["--yes"]));
-    return { command: "keys-create", yes: argv.includes("--yes") };
+  if (group === "signin") {
+    const flags = parseFlags(argv.slice(1), ["--no-open"]);
+    return {command:"signin",noOpen:flags.has("--no-open")};
   }
-  if (argv[0] === "contract") {
-    assertOnly(argv.slice(1), new Set());
-    return { command: "contract" };
+  if (group === "signout") { parseFlags(argv.slice(1), []); return {command:"signout"}; }
+  if (group === "auth" && action === "status") {
+    const flags = parseFlags(argv.slice(2), ["--json"]);
+    return {command:"auth-status",json:flags.has("--json")};
   }
-  if (argv[0] === "apps" && argv[1] === "list") {
-    assertOnly(argv.slice(2), new Set(["--json"]));
-    return { command: "apps-list", json: argv.includes("--json") };
+  if (group === "update" && action === "check") { parseFlags(argv.slice(2), []); return {command:"update-check"}; }
+  if (group === "keys" && action === "create") {
+    const flags = parseFlags(argv.slice(2), ["--yes"], ["--app-name","--idempotency-key"]);
+    const name = flags.get("--app-name");
+    if (typeof name !== "string") usage("keys create --app-name <name> [--idempotency-key <key>]");
+    return {command:"keys-create",appName:applicationName(name),...mutationFlags(flags)};
   }
-  if (argv[0] === "apps" && argv[1] === "get") {
-    return {
-      command: "apps-get",
-      appKey: parseAppKey(argv, "Usage: requestshield apps get <app-key>"),
-    };
+  if (group === "keys" && ["rotate","reveal","revoke"].includes(action)) {
+    const appKey = requiredAppKey(argv, `keys ${action} <app-key>`);
+    const flags = parseFlags(argv.slice(3), ["--yes"], action === "reveal" ? [] : ["--idempotency-key"]);
+    return {command:/** @type {"keys-rotate"|"keys-reveal"|"keys-revoke"} */ (`keys-${action}`),appKey,...mutationFlags(flags)};
   }
-  if (argv[0] === "challenge" && argv[1] === "volume") {
-    return parseChallengeVolume(argv);
+  if (group === "apps" && action === "list") {
+    const flags = parseFlags(argv.slice(2), ["--json","--all"], ["--limit","--cursor"]);
+    const limit = flags.get("--limit");
+    if (limit !== undefined && (typeof limit !== "string" || !/^[1-9][0-9]{0,2}$/.test(limit) || Number(limit) > 100)) {
+      throw invalid("--limit must be an integer from 1 to 100");
+    }
+    const cursor = flags.get("--cursor");
+    if (cursor !== undefined && (typeof cursor !== "string" || !/^[A-Za-z0-9_-]{1,1024}$/.test(cursor))) throw invalid("Invalid --cursor");
+    if (cursor !== undefined && flags.has("--all")) throw invalid("--cursor and --all cannot be combined");
+    return {command:"apps-list",json:flags.has("--json"),all:flags.has("--all"),
+      ...(limit !== undefined ? {limit:Number(limit)} : {}),...(typeof cursor === "string" ? {cursor} : {})};
   }
-  if (argv[0] === "get" && argv[1] === "billing") {
-    return {
-      command: "billing-get",
-      appKey: parseAppKey(argv, "Usage: requestshield get billing <app-key>"),
-    };
+  if (group === "apps" && action === "get") {
+    const appKey = requiredAppKey(argv, "apps get <app-key>");
+    parseFlags(argv.slice(3), []);
+    return {command:"apps-get",appKey};
   }
-  if (argv[0] === "agent" && argv[1] === "setup") {
-    const rest = argv.slice(2);
-    /** @type {"codex" | "claude" | undefined} */
-    let agent;
-    let force = false;
-    for (let index = 0; index < rest.length; index++) {
-      const arg = rest[index];
-      if (arg === "--force") {
-        force = true;
-      } else if (arg === "--codex" || arg === "--claude") {
-        if (agent !== undefined) {
-          throw new CliError("Only one of --codex or --claude may be provided", {
-            code: "INVALID_AGENT",
-            exitCode: 2,
-          });
-        }
-        agent = arg === "--codex" ? "codex" : "claude";
-      } else {
-        throw new CliError(`Unknown option: ${arg}`, { exitCode: 2 });
-      }
+  if (group === "apps" && ["rename","enable","disable"].includes(action)) {
+    const appKey = requiredAppKey(argv, `apps ${action} <app-key>${action === "rename" ? " --name <name>" : ""}`);
+    const flags = parseFlags(argv.slice(3), ["--yes"], ["--idempotency-key",...(action === "rename" ? ["--name"] : [])]);
+    if (action === "rename") {
+      const name = flags.get("--name");
+      if (typeof name !== "string") usage("apps rename <app-key> --name <name>");
+      return {command:"apps-rename",appKey,name:applicationName(name),...mutationFlags(flags)};
     }
-    return {
-      command: "agent-setup",
-      ...(agent ? { agent } : {}),
-      force,
-    };
+    return {command:action === "enable" ? "apps-enable" : "apps-disable",appKey,enabled:action === "enable",...mutationFlags(flags)};
   }
-  throw new CliError(`Unknown command.\n\n${HELP}`, { exitCode: 2 });
-}
-
-/** @param {string[]} args @param {Set<string>} allowed */
-function assertOnly(args, allowed) {
-  for (const arg of args) {
-    if (!allowed.has(arg)) {
-      throw new CliError(`Unknown option: ${arg}`, { exitCode: 2 });
-    }
+  if (group === "agent" && action === "setup") {
+    const flags = parseFlags(argv.slice(2), ["--codex","--claude","--force"]);
+    if (flags.has("--codex") && flags.has("--claude")) throw invalid("Only one of --codex or --claude may be provided");
+    return {command:"agent-setup",force:flags.has("--force"),
+      ...(flags.has("--codex") ? {agent:/** @type {const} */ ("codex")} : flags.has("--claude") ? {agent:/** @type {const} */ ("claude")} : {})};
   }
+  throw invalid(`Unknown command.\n\n${HELP}`);
 }
 
-/** @param {string[]} argv @param {string} usage */
-function parseAppKey(argv, usage) {
-  if (argv.length !== 3) throw new CliError(usage, { exitCode: 2 });
-  return validateAppKey(argv[2]);
-}
-
-/** @param {string[]} argv @returns {Extract<ParsedArgs, {command: "challenge-volume"}>} */
-function parseChallengeVolume(argv) {
-  const usage = "Usage: requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]";
-  if (argv.length < 3) throw new CliError(usage, { exitCode: 2 });
-  const appKey = validateAppKey(argv[2]);
-  /** @type {{ from?: string, to?: string, granularity?: string }} */
-  const options = {};
-  /** @type {Map<string, "from" | "to" | "granularity">} */
-  const optionNames = new Map([
-    ["--from", "from"],
-    ["--to", "to"],
-    ["--granularity", "granularity"],
-  ]);
-  for (let index = 3; index < argv.length; index += 2) {
-    const option = argv[index];
-    const property = optionNames.get(option);
-    if (!property) throw new CliError(`Unknown option: ${option}`, { exitCode: 2 });
-    const value = argv[index + 1];
-    if (!value || value.startsWith("--")) {
-      throw new CliError(`${option} requires a value`, { exitCode: 2 });
-    }
-    if (options[property] !== undefined) {
-      throw new CliError(`${option} may only be provided once`, { exitCode: 2 });
-    }
-    if ((property === "from" || property === "to") && !isIsoTime(value)) {
-      throw new CliError(`${option} must be an ISO-8601 timestamp`, {
-        code: "INVALID_TIME",
-        exitCode: 2,
-      });
+/** @param {string[]} args @param {string[]} booleans @param {string[]} [values] */
+function parseFlags(args, booleans, values = []) {
+  /** @type {Map<string,string|true>} */
+  const flags = new Map();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!booleans.includes(arg) && !values.includes(arg)) throw invalid(`Unknown option: ${arg}`);
+    if (flags.has(arg)) throw invalid(`${arg} may only be provided once`);
+    if (booleans.includes(arg)) flags.set(arg, true);
+    else {
+      const value = args[++i];
+      if (!value || value.startsWith("--")) throw invalid(`${arg} requires a value`);
+      flags.set(arg,value);
     }
-    if (property === "granularity" && !/^[a-z][a-z0-9_-]{0,31}$/.test(value)) {
-      throw new CliError(
-        "--granularity must be 1-32 lowercase letters, numbers, '_' or '-'",
-        { code: "INVALID_GRANULARITY", exitCode: 2 },
-      );
-    }
-    options[property] = value;
-  }
-  if (options.from && options.to && Date.parse(options.from) > Date.parse(options.to)) {
-    throw new CliError("--from must not be later than --to", {
-      code: "INVALID_TIME_RANGE",
-      exitCode: 2,
-    });
   }
-  return { command: "challenge-volume", appKey, ...options };
+  return flags;
 }
-
-/** @param {string} appKey */
-function validateAppKey(appKey) {
-  if (!/^[A-Za-z0-9._~-]{1,128}$/.test(appKey)) {
-    throw new CliError(
-      "App Key must be 1-128 characters using letters, numbers, '.', '_', '~', or '-'",
-      { code: "INVALID_APP_KEY", exitCode: 2 },
-    );
-  }
-  return appKey;
+/** @param {Map<string,string|true>} flags */
+function mutationFlags(flags) {
+  const key = flags.get("--idempotency-key");
+  if (key !== undefined && (typeof key !== "string" || !/^[A-Za-z0-9._~-]{1,128}$/.test(key))) throw invalid("Invalid --idempotency-key");
+  return {yes:flags.has("--yes"),...(typeof key === "string" ? {idempotencyKey:key} : {})};
+}
+/** @param {string[]} argv @param {string} help */
+function requiredAppKey(argv, help) {
+  if (!argv[2] || argv[2].startsWith("--")) usage(help);
+  if (!/^[A-Za-z0-9._~-]{1,128}$/.test(argv[2])) throw invalid("App Key must be 1-128 letters, numbers, '.', '_', '~' or '-'");
+  return argv[2];
 }
-
 /** @param {string} value */
-function isIsoTime(value) {
-  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)
-    && Number.isFinite(Date.parse(value));
+function applicationName(value) {
+  const name = value.trim();
+  if (!name || [...name].length > 100 || /[\p{Cc}\p{Cs}]/u.test(name)) throw invalid("Application name must contain 1-100 characters without control characters");
+  return name;
 }
-
+/** @param {string} command @returns {never} */
+function usage(command) { throw invalid(`Usage: requestshield ${command}`); }
+/** @param {string} message */
+function invalid(message) { return new CliError(message,{code:"INVALID_ARGUMENT",exitCode:2}); }
 export { HELP };

package/src/browser-opener.mjs

@@ -0,0 +1,32 @@
+// @ts-check
+import { spawn } from "node:child_process";
+import { CliError } from "./errors.mjs";
+
+/** Uses argument arrays and a fixed Windows script; never interpolate URL into shell code.
+ * @param {string} url
+ * @param {{signal?: AbortSignal, platform?: NodeJS.Platform, spawnImpl?: typeof spawn}} [options]
+ */
+export async function openBrowser(url, {signal, platform = process.platform, spawnImpl = spawn} = {}) {
+  const failure = () => new CliError("Could not open the browser automatically", {code: "BROWSER_OPEN_FAILED"});
+  const command = platform === "win32" ? "powershell.exe" : platform === "darwin" ? "open" : "xdg-open";
+  const args = platform === "win32"
+    ? ["-NoProfile", "-NonInteractive", "-Command", "Start-Process -FilePath $env:REQUESTSHIELD_SIGNIN_BROWSER_URL"]
+    : [url];
+  await new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(failure()); return; }
+    let child;
+    try {
+      child = spawnImpl(command, args, {
+        windowsHide: true, stdio: "ignore", shell: false,
+        env: platform === "win32" ? {...process.env, REQUESTSHIELD_SIGNIN_BROWSER_URL: url} : process.env,
+      });
+    } catch { reject(failure()); return; }
+    const abort = () => { cleanup(); child.kill(); reject(failure()); };
+    const timer = setTimeout(abort, 10_000);
+    const cleanup = () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); };
+    child.once("error", () => { cleanup(); reject(failure()); });
+    child.once("exit", code => { cleanup(); code === 0 ? resolve(undefined) : reject(failure()); });
+    signal?.addEventListener("abort", abort, {once: true});
+    if (signal?.aborted) abort();
+  });
+}