requestshield 0.1.0 → 0.1.3

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

@@ -7,7 +7,9 @@ const HELP = `RequestShield customer CLI
 Usage:
   requestshield signin
   requestshield keys create [--yes]
-  requestshield agent setup --agent codex [--force]
+  requestshield agent setup [--force]
+  requestshield agent setup --codex [--force]
+  requestshield agent setup --claude [--force]
   requestshield --help
   requestshield --version`;
 
@@ -16,7 +18,7 @@ Usage:
  * | { command: "version" }
  * | { command: "signin" }
  * | { command: "keys-create", yes: boolean }
- * | { command: "agent-setup", agent: "codex", force: boolean }} ParsedArgs
+ * | { command: "agent-setup", agent?: "codex" | "claude", force: boolean }} ParsedArgs
  */
 
 /** @param {string[]} argv @returns {ParsedArgs} */
@@ -37,28 +39,30 @@ export function parseArgs(argv) {
   }
   if (argv[0] === "agent" && argv[1] === "setup") {
     const rest = argv.slice(2);
-    /** @type {string | undefined} */
+    /** @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 === "--agent") {
-        agent = rest[++index];
-        if (!agent || agent.startsWith("--")) {
-          throw new CliError("--agent needs a value", { exitCode: 2 });
+      } 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 (agent !== "codex") {
-      throw new CliError("--agent codex is required; no other agent is supported", {
-        exitCode: 2,
-      });
-    }
-    return { command: "agent-setup", agent: "codex", force };
+    return {
+      command: "agent-setup",
+      ...(agent ? { agent } : {}),
+      force,
+    };
   }
   throw new CliError(`Unknown command.\n\n${HELP}`, { exitCode: 2 });
 }

package/src/cli.mjs

@@ -11,7 +11,7 @@ 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> }} [deps]
+ * @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> }} [deps]
  */
 export async function run(argv, deps = {}) {
   const parsed = parseArgs(argv);

package/src/commands/agent-setup.mjs

@@ -1,25 +1,28 @@
 // @ts-check
 
-import { cp, lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { cp, lstat, mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
 import { CliError } from "../errors.mjs";
+import { detectAgents } from "../agent-detector.mjs";
 import { getAsset, isSea } from "node:sea";
 
 const skillAsset = "requestshield-skill.md";
 
 /**
- * @param {{ agent: string, force: boolean }} options
- * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, log: (message: string) => void, sourceDir?: string }} deps
+ * @param {{ agent?: "codex" | "claude", force: boolean }} options
+ * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, log: (message: string) => void, sourceDir?: string, executablePath?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude"> }} deps
  */
 export async function setupAgent(options, deps) {
-  if (options.agent !== "codex") {
-    throw new CliError(`Unsupported agent: ${options.agent}`, { exitCode: 2 });
-  }
-  const env = deps.env ?? process.env;
-  const codexHome = env.CODEX_HOME || path.join(deps.homeDir ?? os.homedir(), ".codex");
-  const skillsRoot = path.join(codexHome, "skills");
+  const agent = await resolveAgent(options.agent, deps);
+  const homeDir = deps.homeDir ?? os.homedir();
+
+  // Codex and Claude discover personal skills from different directories.
+  const skillsRoot = agent === "codex"
+    ? path.join(homeDir, ".agents", "skills")
+    : path.join(homeDir, ".claude", "skills");
   const destination = path.join(skillsRoot, "requestshield");
   await mkdir(skillsRoot, { recursive: true });
 
@@ -31,17 +34,19 @@ export async function setupAgent(options, deps) {
     });
   }
 
+  // Copy into a staging directory so an interrupted copy cannot leave a
+  // partially installed skill at the final destination.
   const staging = path.join(skillsRoot, `.requestshield-${randomUUID()}.tmp`);
   const backup = `${destination}.${randomUUID()}.backup`;
   try {
     if (deps.sourceDir) {
-      // Dùng trong test hoặc khi caller chỉ định source.
+      // Tests and alternate packagers can provide an explicit skill source.
       await cp(deps.sourceDir, staging, {
         recursive: true,
         errorOnExist: true,
       });
     } else if (isSea()) {
-      // SEA không có thư mục source trên disk, đọc skill đã nhúng.
+      // A single-executable build reads the skill from its embedded assets.
       await mkdir(staging);
 
       await writeFile(
@@ -49,11 +54,14 @@ export async function setupAgent(options, deps) {
           Buffer.from(getAsset(skillAsset)),
       );
     } else {
-      // Chạy từ source/npm hoặc chạy bundle CJS trên disk.
+      // Source, npm, and on-disk CJS builds keep the skill beside the program.
       //
       // src/main.mjs                 -> ../skills/requestshield
       // dist/requestshield.cjs      -> ../skills/requestshield
-      const executableDir = path.dirname(path.resolve(process.argv[1]));
+      // npm link and global npm installs expose a symlink in their bin folder.
+      // Follow it before resolving the adjacent packaged skills directory.
+      const executable = await realpath(deps.executablePath ?? process.argv[1]);
+      const executableDir = path.dirname(executable);
       const source = path.resolve(
           executableDir,
           "../skills/requestshield",
@@ -64,6 +72,8 @@ export async function setupAgent(options, deps) {
         errorOnExist: true,
       });
     }
+
+    // Keep the old installation recoverable until the staged copy is in place.
     if (exists) await rename(destination, backup);
     await rename(staging, destination);
     if (exists) await rm(backup, { recursive: true, force: true });
@@ -75,8 +85,92 @@ export async function setupAgent(options, deps) {
     }
     throw error;
   }
-  deps.log(`Installed RequestShield skill for Codex at ${destination}`);
-  deps.log("Restart Codex or start a new task before using the skill.");
+  const agentLabel = agent === "codex" ? "Codex" : "Claude";
+  deps.log(`Installed RequestShield skill for ${agentLabel} at ${destination}`);
+  deps.log(`Restart ${agentLabel} or start a new task before using the skill.`);
+}
+
+/**
+ * Explicit selection bypasses detection. Automatic setup selects a single
+ * detected agent or asks the user when both agents are present.
+ *
+ * @param {"codex" | "claude" | undefined} requested
+ * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude"> }} deps
+ * @returns {Promise<"codex" | "claude">}
+ */
+async function resolveAgent(requested, deps) {
+  // A command-line choice is authoritative and avoids probing the machine.
+  if (requested) return requested;
+
+  const detected = deps.detectAgents
+    ? await deps.detectAgents()
+    : await detectAgents({ env: deps.env, homeDir: deps.homeDir });
+
+  if (detected.length === 1) return detected[0];
+  if (detected.length === 0) {
+    throw new CliError(
+      [
+        "No supported coding agent detected.",
+        "",
+        "Choose one explicitly:",
+        "  requestshield agent setup --codex",
+        "  requestshield agent setup --claude",
+      ].join("\n"),
+      { code: "AGENT_NOT_FOUND", exitCode: 2 },
+    );
+  }
+
+  // Never choose silently when both agents are present. Interactive users get
+  // a prompt; non-interactive callers receive a stable conflict error.
+  const selectAgent = deps.selectAgent ?? promptForAgent;
+  const selected = await selectAgent(detected);
+  if (!detected.includes(selected)) {
+    throw new CliError(`Selected agent is not available: ${selected}`, {
+      code: "INVALID_AGENT",
+      exitCode: 2,
+    });
+  }
+  return selected;
+}
+
+/**
+ * Ask an interactive user which detected agent should receive the skill.
+ *
+ * @returns {Promise<"codex" | "claude">}
+ */
+async function promptForAgent() {
+  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+    throw new CliError(
+      [
+        "Multiple coding agents detected.",
+        "",
+        "Choose one explicitly:",
+        "  requestshield agent setup --codex",
+        "  requestshield agent setup --claude",
+      ].join("\n"),
+      { code: "INSTALL_CONFLICT", exitCode: 2 },
+    );
+  }
+
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    process.stdout.write(
+      "Multiple coding agents detected.\n\n  1. Codex\n  2. Claude\n\n",
+    );
+    while (true) {
+      const answer = (await prompt.question("Select an agent [1-2]: "))
+        .trim()
+        .toLowerCase();
+      if (answer === "1" || answer === "codex") return "codex";
+      if (answer === "2" || answer === "claude") return "claude";
+      process.stdout.write("Enter 1 for Codex or 2 for Claude.\n");
+    }
+  } finally {
+    prompt.close();
+  }
 }
 
 /** @param {string} target */

package/src/main.mjs

@@ -1,25 +1,25 @@
 #!/usr/bin/env node
-// @ts-check
-
-import { run } from "./cli.mjs";
-import { CliError } from "./errors.mjs";
-
-async function main() {
-    try {
-        await run(process.argv.slice(2));
-    } catch (error) {
-        const message =
-            error instanceof Error
-                ? error.message
-                : String(error);
-
-        console.error(`requestshield: ${message}`);
-
-        process.exitCode =
-            error instanceof CliError
-                ? error.exitCode
-                : 1;
-    }
-}
-
-void main();
+// @ts-check
+
+import { run } from "./cli.mjs";
+import { CliError } from "./errors.mjs";
+
+async function main() {
+    try {
+        await run(process.argv.slice(2));
+    } catch (error) {
+        const message =
+            error instanceof Error
+                ? error.message
+                : String(error);
+
+        console.error(`requestshield: ${message}`);
+
+        process.exitCode =
+            error instanceof CliError
+                ? error.exitCode
+                : 1;
+    }
+}
+
+void main();