requestshield 0.1.4 → 0.1.6

package/skills/requestshield/references/troubleshooting.md

@@ -1,118 +1,114 @@
-# 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.
+# 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 checks
+
+```console
+requestshield auth status --json
+requestshield apps get <app-key>
+```
+
+Session status is local only. Application status is configuration state, not
+traffic: `pending`, `enabled`, `disabled`, `revoked` or `attention_required`.
+It cannot prove that the browser sent a request or that a deployed backend has the
+current secret. Inspect browser requests and safe backend decision metrics separately.
+The CLI has no service-health or credential-status command.
+
+Confirm runtime secret injection by presence only. A secret absent from the current
+shell may still be supplied by the deployed environment; a rotated secret may not
+have reached that backend yet. Never read or print the value to diagnose this.
+
+## 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 — confirm runtime secret injection and recent rotations without reading the value. |
+| `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 backend connectivity and safe health metrics. 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 connectivity and safe backend health observations. (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
+backend connectivity and service health through established monitoring when it rises. Never "fix" a degraded result by overriding
+`isAllowed()` — that converts a platform incident into a customer-facing outage.
+
+## Confirming traffic and enforcement
+
+Use browser network observations and existing safe backend metrics in an authorized
+environment. Do not record raw tokens or secrets. CLI challenge-volume analytics are
+unavailable; application status is not a traffic measurement. Report static correctness,
+observed requests and backend enforcement separately. Use the controlled negative
+test in `SKILL.md` to demonstrate 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 keys rotate <app-key>
+```
+
+The App Key is unchanged, so no browser edit is needed. Deploy the new secret to backend
+secret storage. Rotation replaces the previous secret, but publication is asynchronous.
+Warn the user that the new secret is displayed and must stay out of transcripts. A lost
+response can be recovered with explicit reveal; an exposed secret requires rotation.

package/src/agent-detector.mjs

@@ -1,74 +1,102 @@
-// @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;
-  }
-}
+// @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");
+
+  const codexConfigPath =
+    path.join(codexHome, "config.toml");
+
+  const claudeConfigPath =
+    path.join(homeDir, ".claude.json");
+
+  // 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(";")
+        .filter(Boolean)
+    : [""];
+
+  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;
+  }
+}