requestshield 0.1.4 → 0.1.5

package/skills/requestshield/references/troubleshooting.md

@@ -1,118 +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.
+# 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

@@ -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;
+  }
+}

package/src/api-client.mjs

@@ -2,6 +2,14 @@
 
 import { CliError } from "./errors.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",
+};
+
 export class ManagementApiClient {
   /** @param {{ baseUrl: string, fetchImpl?: typeof fetch }} options */
   constructor({ baseUrl, fetchImpl = fetch }) {
@@ -21,7 +29,7 @@ export class ManagementApiClient {
   }
 
   async startSignin() {
-    return this.#request("/v1/cli/signin", {
+    return this.#request(API_ENDPOINTS.SIGNIN, {
       method: "POST",
       body: JSON.stringify({ client: "requestshield-cli" }),
     });
@@ -30,7 +38,7 @@ export class ManagementApiClient {
   /** @param {string} deviceCode */
   async pollSignin(deviceCode) {
     return this.#request(
-      "/v1/cli/signin/token",
+      API_ENDPOINTS.SIGNIN_TOKEN,
       { method: "POST", body: JSON.stringify({ deviceCode }) },
       true,
     );
@@ -38,13 +46,97 @@ export class ManagementApiClient {
 
   /** @param {string} accessToken */
   async rotateKeys(accessToken) {
-    return this.#request("/v1/cli/keys/rotate", {
+    return this.#request(API_ENDPOINTS.KEYS_ROTATE, {
       method: "POST",
       headers: { Authorization: `Bearer ${accessToken}` },
       body: "{}",
     });
   }
 
+  /** @param {string} accessToken */
+  async integrationContract(accessToken) {
+    return this.#request(API_ENDPOINTS.INTEGRATION_CONTRACT, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+  }
+
+  /** @param {string} accessToken */
+  async listApps(accessToken) {
+    return this.#request(API_ENDPOINTS.APPLICATIONS, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+  }
+
+  /** @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} 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;
+
+    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} path
    * @param {RequestInit} init
@@ -77,10 +169,13 @@ export class ManagementApiClient {
       }
     }
     if (!response.ok && !allowErrorBody) {
-      const detail = objectString(body, "message") ?? `HTTP ${response.status}`;
+      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(body, "code") ?? "API_ERROR",
+        code: objectString(nestedError, "code") ?? objectString(body, "code") ?? "API_ERROR",
         exitCode,
       });
     }