requestshield 0.1.2 → 0.1.4

package/skills/requestshield/references/troubleshooting.md

@@ -0,0 +1,118 @@
+# Troubleshooting
+
+Work outward from the request, not from the code. Most reports of "RequestShield is
+broken" are one of four things: the browser never attached a token, CORS stripped the
+header, the backend never verified it, or one token was verified twice.
+
+## First three checks
+
+```bash
+requestshield server                          # platform healthy or degraded?
+requestshield apps get <app-key>              # status: ready (no traffic yet) or active?
+requestshield credentials status <app-key>    # provisioned and active?
+```
+
+`status: ready` means the platform has never seen traffic for that key — the integration
+is not wired up yet, so debugging backend enforcement logic is premature. Start at the
+browser.
+
+Run `credentials status` even when the pre-edit Credentials check in
+`integration-planning.md` passed during the install. That check greps the **local
+shell**; it says nothing about what the deployed backend actually receives, and a secret
+can be rotated, or missed by the deploy environment, after it passed. This is the check
+that answers `consume_unauthorized`.
+
+## Reason codes
+
+`result.getReason().getCode()` returns a stable code, safe to log. Use codes to explain
+a decision, never to amend one.
+
+The table below is a working list, not the authoritative one — the customer
+documentation owns that. Check a code against it before quoting a meaning to the user,
+and treat a code that is not listed here as unrecognised rather than guessing from its
+name.
+
+| Code | Means | Usual cause |
+| --- | --- | --- |
+| `ok` | Verified and consumed | — |
+| `missing_token` | No token reached the backend | Script tag absent or loaded after the request; Seamless path mismatch (case, trailing slash, wrong origin); an uncovered transport (form POST, sendBeacon, sync XHR, `no-cors`); a Manual call site that never attaches the header; CORS not allowing `X-IntelliFend-Token`; or CSP missing `worker-src blob:` so `getToken()` returns empty. |
+| `unknown_customer` | App Key not recognised | Typo, deactivated key, or browser and backend configured with different App Keys. |
+| `token_tampered` | Token failed integrity checks | Something modified the value in transit — a proxy rewriting headers, or application code trimming or re-encoding it. Pass the value through unchanged. |
+| `token_expired` | Token too old | The page held a token instead of obtaining a fresh one per request, or a very slow round trip. |
+| `token_replayed` | Already consumed | The same token verified twice: a retry reusing the first token, or two verification paths on one request (`@RequestShieldProtected` plus a manual `verify()`, or a filter plus a controller). |
+| `consume_unauthorized` | Backend credentials rejected | API Secret wrong, rotated, or not injected — check `credentials status` and the environment variable. |
+| `invalid_request` | Malformed verification request | Usually a mis-set `challenge-server-url`. |
+| `not_found` | Token unknown to the platform | Cross-environment mismatch — a staging page's token verified against production, or the reverse. |
+| `service_unavailable` | Platform unreachable | Check `requestshield server`. See degraded behaviour below. |
+
+## "It blocks everything"
+
+Almost always `missing_token` or `unknown_customer`. Confirm in this order — each step is
+cheap and rules out a whole class:
+
+1. Open the network tab. Does the protected request carry `X-IntelliFend-Token` with a
+   non-empty value?
+2. **Header absent** → browser half. Seamless: compare the requested URL against
+   `data-protect` character for character — case and trailing slash are significant — and
+   check the transport is `fetch` or async XHR from page scope. Manual: find the call
+   site, and every retry path.
+3. **Header absent on a cross-origin request only** → CORS. The API's
+   `Access-Control-Allow-Headers` must include `X-IntelliFend-Token`, or the browser
+   strips it before it ever leaves.
+4. **Header present but empty** → the SDK ran and could not obtain a token. Check the CSP
+   includes `worker-src 'self' blob:` and that `connect-src` allows the challenge host,
+   then check `requestshield server`. (In Manual mode an empty token means the header
+   should be omitted, not sent empty — see `browser-manual.md`.)
+5. **Header present and populated** → backend half. Compare the App Key on both sides
+   character for character, then confirm the secret is actually injected at runtime.
+
+## "It blocks nothing"
+
+Enumerate rather than assuming the browser is at fault:
+
+- The endpoint is in `MONITOR` mode — evaluating and always continuing. Protection-shaped,
+  not protection.
+- The decision is computed but only logged, never enforced.
+- Verification happens after the mutation has already been performed.
+- Application code overrides `isAllowed()` from a reason code — a separate decision table
+  in application code removes the protection.
+- The backend never verifies at all: a browser-only install. Grep for the client or the
+  annotation before trusting a claim that the backend is wired up.
+- Results are `isDegraded()` — the platform was unreachable and requests were allowed by
+  the availability policy.
+
+## Degraded results are allowed by design
+
+When the Challenge Server cannot be reached, `verify()` returns a result that is
+**allowed** and **degraded**. Availability is deliberately chosen over enforcement so a
+platform outage cannot take down a customer's checkout flow.
+
+Communicate the consequence clearly: during a degraded window, traffic passes without
+real verification. Log the degraded rate as its own metric so it is visible, and check
+`requestshield server` when it rises. Never "fix" a degraded result by overriding
+`isAllowed()` — that converts a platform incident into a customer-facing outage.
+
+## Confirming traffic reaches the platform
+
+```bash
+requestshield challenge volume <app-key> --from 2026-08-01T00:00:00Z \
+  --to 2026-08-27T23:59:59Z --granularity day
+```
+
+Challenge volume is runtime evidence that the browser/platform half is active. It does
+not prove that the backend enforces a blocking decision. Report static correctness,
+platform traffic, and backend enforcement separately. Use the controlled negative test
+in `SKILL.md` to prove enforcement.
+
+## Secret exposure
+
+If the API Secret appears in a repo, a log, a build artifact, or a chat transcript,
+rotate it — deleting the line does not un-expose it:
+
+```bash
+requestshield app key rotate --app-key <app-key>
+```
+
+The App Key is unchanged, so no browser edit is needed. Deploy the new secret to backend
+secret storage; the previous one is deactivated automatically. Warn the user that the new
+secret is displayed once.

package/src/agent-detector.mjs

@@ -0,0 +1,74 @@
+// @ts-check
+
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Detect supported agents from their executable or local configuration.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string }} [options]
+ * @returns {Promise<Array<"codex" | "claude">>}
+ */
+export async function detectAgents(options = {}) {
+  const env = options.env ?? process.env;
+  const homeDir = options.homeDir ?? os.homedir();
+  const codexHome = env.CODEX_HOME ?? path.join(homeDir, ".codex");
+
+  // Executables prove the CLI is on PATH. Configuration files cover desktop
+  // installs and agents that were previously configured but are not on PATH.
+  const [codexCommand, claudeCommand, codexConfig, claudeConfig, claudeState] =
+    await Promise.all([
+      commandExists("codex", env),
+      commandExists("claude", env),
+      pathExists(codexHome),
+      pathExists(path.join(homeDir, ".claude")),
+      pathExists(path.join(homeDir, ".claude.json")),
+    ]);
+
+  /** @type {Array<"codex" | "claude">} */
+  const detected = [];
+  if (codexCommand || codexConfig) detected.push("codex");
+  if (claudeCommand || claudeConfig || claudeState) detected.push("claude");
+  return detected;
+}
+
+/**
+ * Inspect PATH without starting the coding agent.
+ *
+ * @param {string} command
+ * @param {NodeJS.ProcessEnv} env
+ */
+async function commandExists(command, env) {
+  const searchPath = env.PATH ?? env.Path ?? "";
+  const extensions = process.platform === "win32"
+    ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+    : [""];
+
+  for (const directory of searchPath.split(path.delimiter)) {
+    if (!directory) continue;
+    for (const extension of extensions) {
+      try {
+        await access(
+          path.join(directory, `${command}${extension}`),
+          process.platform === "win32" ? constants.F_OK : constants.X_OK,
+        );
+        return true;
+      } catch {
+        // Continue through the remaining executable candidates.
+      }
+    }
+  }
+  return false;
+}
+
+/** @param {string} target */
+async function pathExists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/args.mjs

@@ -1,122 +1,85 @@
-// @ts-check
-
-import { CliError } from "./errors.mjs";
-
-const HELP = `RequestShield CLI
-
-Usage:
-  requestshield [command] [options]
-
-Commands:
-  update
-    check                           Check for and install the latest CLI version
-
-  auth
-    signin                         Sign in to RequestShield
-    status                         Show authentication status
-
-  keys
-    create                         Create a new application and key pair
-    deactivate                     Deactivate application credentials
-    rotate                         Rotate the Secret Key for an application
-
-  agent
-    setup                          Install the RequestShield Agent Skill
-    setup --agent codex            Install the Skill for Codex
-    setup --agent claude           Install the Skill for Claude
-    setup --status                 Show Agent Skill installation status
-
-  contract
-    get                            Get the RequestShield integration contract
-
-  apps
-    list                           List accessible applications
-    get <app-key>                  Get application information
-    readiness <app-key>            Check application readiness
-
-  credentials
-    status <app-key>               Show credential status without exposing secrets
-
-  challenge
-    volume <app-key>               Get challenge volume for an application
-
-  billing
-    get <app-key>                  Get billing and plan information
-
-  protect
-    list <app-key>                 List protected endpoints
-    add                            Add a protected endpoint
-    remove                         Remove a protected endpoint
-
-Options:
-  -h, --help                       Show help
-  -v, --version                    Show CLI version
-  --json                           Output machine-readable JSON`;
-
-/**
- * @typedef {{ command: "help", help: string }
- * | { command: "version" }
- * | { command: "update-check" }
- * | { command: "signin" }
- * | { command: "keys-create", yes: boolean }
- * | { command: "agent-setup", agent: "codex", 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[0] === "keys" && argv[1] === "create") {
-    assertOnly(argv.slice(2), new Set(["--yes"]));
-    return { command: "keys-create", yes: argv.includes("--yes") };
-  }
-  if (argv[0] === "agent" && argv[1] === "setup") {
-    const rest = argv.slice(2);
-    /** @type {string | 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 === "--agent") {
-        agent = rest[++index];
-        if (!agent || agent.startsWith("--")) {
-          throw new CliError("--agent needs a value", { exitCode: 2 });
-        }
-      } else {
-        throw new CliError(`Unknown option: ${arg}`, { exitCode: 2 });
-      }
-    }
-    if (agent !== "codex") {
-      throw new CliError("--agent codex is required; no other agent is supported", {
-        exitCode: 2,
-      });
-    }
-    return { command: "agent-setup", agent: "codex", force };
-  }
-  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 });
-    }
-  }
-}
-
-export { HELP };
+// @ts-check
+
+import { CliError } from "./errors.mjs";
+
+const HELP = `RequestShield CLI
+
+Usage:
+  requestshield signin
+  requestshield keys create [--yes]
+  requestshield agent setup [--force]
+  requestshield agent setup --codex [--force]
+  requestshield agent setup --claude [--force]
+  requestshield update check
+  requestshield --help
+  requestshield --version`;
+
+/**
+ * @typedef {{ command: "help", help: string }
+ * | { command: "version" }
+ * | { command: "update-check" }
+ * | { command: "signin" }
+ * | { command: "keys-create", yes: boolean }
+ * | { 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[0] === "keys" && argv[1] === "create") {
+    assertOnly(argv.slice(2), new Set(["--yes"]));
+    return { command: "keys-create", yes: argv.includes("--yes") };
+  }
+  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 });
+      }
+    }
+    return {
+      command: "agent-setup",
+      ...(agent ? { agent } : {}),
+      force,
+    };
+  }
+  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 });
+    }
+  }
+}
+
+export { HELP };

package/src/cli.mjs

@@ -1,51 +1,51 @@
-#!/usr/bin/env node
-// @ts-check
-
-import { parseArgs } from "./args.mjs";
-import { ManagementApiClient } from "./api-client.mjs";
-import { SessionStore } from "./session-store.mjs";
-import { signin } from "./commands/signin.mjs";
-import { createKeys } from "./commands/keys-create.mjs";
-import { setupAgent } from "./commands/agent-setup.mjs";
-import { checkForUpdate } from "./commands/update-check.mjs";
-import packageJson from "../package.json" with { type: "json" };
-
-/**
- * @param {string[]} argv
- * @param {{ log?: (message: string) => void, api?: ManagementApiClient, sessions?: SessionStore, env?: NodeJS.ProcessEnv, homeDir?: string, sourceDir?: string, wait?: (milliseconds: number) => Promise<unknown>, confirm?: () => Promise<boolean>, fetchImpl?: typeof fetch, confirmUpdate?: () => Promise<boolean>, installLatest?: (packageName: string, version: string) => Promise<void> }} [deps]
- */
-export async function run(argv, deps = {}) {
-  const parsed = parseArgs(argv);
-  const log = deps.log ?? ((message) => console.log(message));
-  if (parsed.command === "help") return log(parsed.help);
-  if (parsed.command === "version") return log("requestshield " + packageJson.version);
-  if (parsed.command === "update-check") {
-    return checkForUpdate({
-      currentVersion: packageJson.version,
-      packageName: packageJson.name,
-      log,
-      fetchImpl: deps.fetchImpl,
-      confirm: deps.confirmUpdate,
-      install: deps.installLatest,
-    });
-  }
-
-  if (parsed.command === "agent-setup") {
-    return setupAgent(parsed, { log, ...deps });
-  }
-
-  const env = deps.env ?? process.env;
-
-  const api = deps.api ?? new ManagementApiClient({
-    baseUrl:
-        env.REQUESTSHIELD_API_URL ??
-        "https://api.intellifend.ai",
-  });
-
-  const sessions = deps.sessions ?? new SessionStore({
-    env,
-    homeDir: deps.homeDir,
-  });
-  if (parsed.command === "signin") return signin({ api, sessions, log, ...deps });
-  if (parsed.command === "keys-create") return createKeys(parsed, { api, sessions, log, ...deps });
-}
+#!/usr/bin/env node
+// @ts-check
+
+import { parseArgs } from "./args.mjs";
+import { ManagementApiClient } from "./api-client.mjs";
+import { SessionStore } from "./session-store.mjs";
+import { signin } from "./commands/signin.mjs";
+import { createKeys } from "./commands/keys-create.mjs";
+import { setupAgent } from "./commands/agent-setup.mjs";
+import { checkForUpdate } from "./commands/update-check.mjs";
+import packageJson from "../package.json" with { type: "json" };
+
+/**
+ * @param {string[]} argv
+ * @param {{ log?: (message: string) => void, api?: ManagementApiClient, sessions?: SessionStore, env?: NodeJS.ProcessEnv, homeDir?: string, sourceDir?: string, executablePath?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude">, wait?: (milliseconds: number) => Promise<unknown>, confirm?: () => Promise<boolean>, fetchImpl?: typeof fetch, confirmUpdate?: () => Promise<boolean>, installLatest?: (packageName: string, version: string) => Promise<void> }} [deps]
+ */
+export async function run(argv, deps = {}) {
+  const parsed = parseArgs(argv);
+  const log = deps.log ?? ((message) => console.log(message));
+  if (parsed.command === "help") return log(parsed.help);
+  if (parsed.command === "version") return log("requestshield " + packageJson.version);
+  if (parsed.command === "update-check") {
+    return checkForUpdate({
+      currentVersion: packageJson.version,
+      packageName: packageJson.name,
+      log,
+      fetchImpl: deps.fetchImpl,
+      confirm: deps.confirmUpdate,
+      install: deps.installLatest,
+    });
+  }
+
+  if (parsed.command === "agent-setup") {
+    return setupAgent(parsed, { log, ...deps });
+  }
+
+  const env = deps.env ?? process.env;
+
+  const api = deps.api ?? new ManagementApiClient({
+    baseUrl:
+        env.REQUESTSHIELD_API_URL ??
+        "https://api.intellifend.ai",
+  });
+
+  const sessions = deps.sessions ?? new SessionStore({
+    env,
+    homeDir: deps.homeDir,
+  });
+  if (parsed.command === "signin") return signin({ api, sessions, log, ...deps });
+  if (parsed.command === "keys-create") return createKeys(parsed, { api, sessions, log, ...deps });
+}