requestshield 0.0.0-stage → 1.0.0-stg.276

package/skills/requestshield/references/integration-planning.md

@@ -0,0 +1,357 @@
+# Integration planning
+
+Use this reference for sign-in when required by the calling workflow and before
+writing or removing RequestShield integration code. It owns the planning steps that
+are too detailed for `SKILL.md`.
+
+## Workflow by operation
+
+Follow [SKILL.md — Classify the request](../SKILL.md#classify-the-request).
+Use only the planning steps required by that intent.
+
+## Sign-in
+
+1. Run `requestshield auth status --json`. Status confirms the local session,
+   not online access.
+   - `valid`: return to the calling workflow; no new login is needed.
+   - `expired`: return to the calling workflow. The next authenticated command
+     attempts refresh automatically; expiry alone does not require browser sign-in.
+     Preserve that workflow's confirmation requirements before running its command.
+   - `configuration_error`: report the configuration failure and stop the dependent
+     action; browser sign-in does not fix CLI configuration.
+   - `signed_out`, `refresh_uncertain`, `config_mismatch`, or `invalid`: continue
+     with browser sign-in below.
+   If status fails or reports an unknown state, report the failure and follow the
+   CLI's recovery guidance rather than assuming login is required.
+2. When browser sign-in is required, explain that the CLI will start sign-in while the user completes the
+   browser flow. Ask for fresh confirmation through the host's interactive question
+   tool with **Yes** and **No**. Wait for an explicit **Yes**. If no permitted tool is
+   available, pause this step. Silence or a preselected option is not approval.
+3. Run `requestshield login` in an interactive PTY and keep it alive while the user
+   completes authentication in the browser. If an interactive PTY is unavailable,
+   ask the user to run `requestshield login` in their own terminal. Do not emulate
+   login or call authentication APIs manually.
+4. After login completes, run `requestshield auth status --json` again. Continue the
+   calling workflow only when it reports `state: "valid"`. Otherwise report the
+   failure and stop the dependent action. A browser launch, redirect, or user
+   confirmation alone does not establish sign-in.
+
+If the calling workflow's authenticated command fails, follow the CLI's recovery
+guidance. A sign-in-required error returns to step 2. A retryable refresh failure
+(such as `SESSION_REFRESH_FAILED`) does not itself require browser sign-in; report
+the failure and preserve the command's retry rules. Never blindly retry a mutation
+whose result is uncertain; use the existing idempotent-retry guidance in
+[the CLI reference](cli.md#key-and-secret-management).
+
+Never request, read, copy, or enter passwords, passkeys, MFA codes, authentication
+tokens, sign-in URLs, or callback URLs on the user's behalf.
+
+## Discover and select protected endpoints
+
+This is the first Install planning step unless the user already supplied an explicit,
+intentionally narrow set of exact HTTP method/path pairs. Discovery is read-only and
+does not authorize integration changes.
+
+### Build the candidate inventory
+
+Scan application source, excluding generated, vendored, dependency, fixture, and build
+files. Find externally reachable browser operations that mutate state, authenticate,
+expose abuse-sensitive capabilities, or trigger meaningful cost. Inspect browser call
+sites, backend routes/handlers, actual effects, and existing protection.
+
+Use focused framework-appropriate searches, starting with filenames. For example:
+
+```bash
+rg -l "fetch\(|axios\.|XMLHttpRequest|\.request\(|<form|action=" \
+  -g "*.html" -g "*.js" -g "*.jsx" -g "*.ts" -g "*.tsx" \
+  -g "*.vue" -g "*.svelte" -g "!node_modules/**" -g "!**/build/**" .
+
+rg -l "@(Post|Put|Patch|Delete|Request)Mapping|@(POST|PUT|PATCH|DELETE)|RouterFunctions|route\(" \
+  -g "*.java" -g "*.kt" -g "!**/build/**" -g "!**/target/**" .
+```
+
+Resolve base URLs, route prefixes, parameters, and HTTP verbs to the exact method/path
+sent by the browser. Pair each operation with its browser call site and backend handler.
+Mark unresolved ownership or missing pairs **Needs clarification**, not install-ready.
+Inspect relevant logic using the redaction rules in **Detect existing integration**;
+never dump configuration or secret files.
+
+Exclude health/metrics, static reads, internal jobs, and non-browser operations that
+cannot receive a browser token. Judge actual behavior: an expensive GET may need
+protection, while a POST is not automatically sensitive.
+
+### Rank candidates
+
+Rank install-ready candidates using these factors in order:
+
+1. Business/security impact: account recovery, payments, privilege changes, destruction.
+2. Automation attractiveness: sign-in, registration, resets, checkout, submissions.
+3. Exposure and existing controls: public operations without equivalent protection.
+4. Operational cost and volume: messages, paid services, scarce resources, amplification.
+5. Trace confidence and supportability: exact browser/handler pairs and supported transport.
+
+Use `Critical`, `High`, `Medium`, or `Low` with a concrete reason, not an invented
+numeric score. Mark complete integrations **Already protected**; partial integrations
+remain selectable and must identify the missing half.
+
+### Present a multi-select and wait
+
+Present all actionable candidates using
+[Interactive questions](../SKILL.md#interactive-questions). Each option shows priority,
+exact HTTP method/path, reason, and current RequestShield state. Keep browser call-site
+and backend-handler details available when useful. For Uninstall, omit priority and
+use the protected-operation inventory specified in the skill.
+
+Wait for the submitted selection, preserve its exact method/path set, and edit only
+selected operations. Use the skill's Yes/No fallback when multi-select is unavailable.
+
+### Process the selected set
+
+Apply the remaining planning and installation steps from `SKILL.md` to each selected
+operation. Reuse contract metadata, scripts, and configuration only for compatible
+operations in the same application; never combine evidence from different owners.
+Group mode questions only when transport, backend owner, capabilities, and intended
+choice match.
+
+Add missing protection, repair only missing halves, and preserve complete integrations
+without duplicate scripts or verification paths. Validate every selected operation.
+Report unselected recommendations as opportunities, not incomplete authorized work.
+
+## Detect existing integration
+
+Record each SDK's version and API separately from Seamless/Manual modes.
+Preserve existing pins, API choices, credentials, and service base URLs.
+Browser/Java 1.0.0 integrations use v1; newer documentation does not change
+their browser, CSP, or Java requirements.
+
+| SDK | API version |
+| --- | --- |
+| Browser 1.0.0 | v1, without an API-version option. |
+| Browser 2.0.0 | v2 by default; `apiVersion: 'v1' \| 'v2'` or `data-api-version` selects it. |
+| Java 1.0.0 | v1, without an API-version option. |
+| Java 2.0.0 core and Spring Boot starter | v2 only; no builder or Spring API-version option. |
+
+For new integrations, prefer matching browser and backend API versions. Mixed
+versions can verify compatible tokens, and a token remains single-use across
+both APIs. Backend availability checks observe only the API used by its SDK.
+If the browser's other API cannot issue a token while the backend's API is
+healthy, the backend can reject with `missing_token`. Check this behavior when
+validating a mixed-version integration. Do not verify a token twice or add
+automatic fallback from v2 to v1. Both APIs are available to active App Keys;
+selecting v2 does not prevent another caller from obtaining a v1 challenge.
+
+Search for existing RequestShield code before install, verify/troubleshoot, or uninstall. Use `rg` when available. Use `rg -l` for filename-only discovery.
+
+Browser markers:
+
+```bash
+rg -l "data-app-key|data-protect|IntelliFend|X-IntelliFend-Token" \
+  -g "*.html" -g "*.htm" -g "*.js" -g "*.jsx" -g "*.ts" -g "*.tsx" \
+  -g "*.vue" -g "*.svelte" -g "*.astro" \
+  -g "*.erb" -g "*.haml" -g "*.php" -g "*.jinja*" -g "*.j2" -g "*.twig" \
+  -g "*.hbs" -g "*.ejs" -g "*.pug" -g "*.blade.php" \
+  -g "!node_modules/**" -g "!**/skills/requestshield/**" -g "!**/.requestshield/**" .
+```
+
+Include server-rendered layouts and any template extensions used by the application;
+a scan limited to `.html`/`.js` can miss an existing SDK tag.
+
+Backend markers:
+
+```bash
+rg -l "RequestShieldClient|RequestShieldProtected|intellifend|requestshield" \
+  -g "*.java" -g "*.kt" -g "*.xml" -g "*.yml" -g "*.yaml" -g "*.properties" \
+  -g "*.gradle" -g "*.gradle.kts" \
+  -g "!**/skills/requestshield/**" -g "!**/.requestshield/**" .
+```
+
+Inspect marker locations without exposing surrounding values:
+
+```bash
+rg -n -o \
+  "data-app-key|data-protect|IntelliFend|getToken|X-IntelliFend-Token" \
+  <browser-candidate-file>
+
+rg -n -o \
+  "RequestShieldClient|RequestShieldProtected|verify|isAllowed|intellifend|requestshield" \
+  <backend-candidate-file>
+
+rg -n -o \
+  "(INTELLIFEND_)?REQUESTSHIELD_(APP_KEY|KEY|API_SECRET|SECRET)" \
+  <candidate-configuration-file>
+```
+`-o` returns only marker or variable names. For context, use a secret-aware parser or
+redacted view before output reaches the agent. Allow filenames, line numbers, config
+keys, variable names, public App Keys when needed, and reference/literal classification.
+Mask API Secrets, tokens, sessions, CSRF, authorization values, and other credentials.
+Never follow filename discovery with unredacted `cat`, `sed`, full matching lines, or
+configuration dumps. If safe inspection is unavailable, request a sanitized excerpt.
+Exclude installed skill/reference directories so their examples do not count as an
+application integration.
+
+Report one of:
+
+- **Not integrated**: no browser or backend markers.
+- **Browser only**: tokens may be obtained or attached, but no backend enforcement was
+  found. This looks protected and is not.
+- **Backend only**: enforcement exists, but no page sends a token. In BLOCK mode this can
+  reject legitimate users.
+- **Fully integrated**: frontend and backend integration modes are both present. Name
+  both, including the backend mechanism. A supported mixed pair is fully integrated;
+  it does not require migration merely to make the mode names match.
+
+Update an existing SDK tag rather than adding another: configuration from
+`document.currentScript` is replaced, not merged, by a second tag.
+
+## Contract check
+
+Run `requestshield contract --json` with the runner for the intended environment.
+It requires no login. Use the returned URLs unchanged; never derive a versioned URL.
+Confirm:
+
+- Browser: `scriptUrlVersion`, `scriptUrlLatest`, matching integrity, `tokenHeader`,
+  `availableModes`, `cspAdditions`, and `sdkVersion` under `data.browser`.
+- Service: `services.challengeUrl`.
+- Backend: `sdkVersion`, `minJdk`, `mavenRepository`, `core`, and `springBoot3` coordinates.
+- The three release documentation links.
+
+Stop if the command or manifest is unavailable; do not fabricate values or substitute
+an environment/release. Pinned browser metadata describes `scriptUrlVersion`, not
+`scriptUrlLatest`. Use documentation for the selected release; never apply 2.x guidance
+to a pinned 1.x release or infer latest capabilities from pinned metadata.
+
+`browser.availableModes` describes frontend modes only. Establish backend capabilities
+from SDK coordinates, release documentation, and the application stack. Preserve the
+contract's JSON fields and apply mode preferences under **Choosing the modes**.
+
+For a new Install without a selected supported URL, ask for `scriptUrlVersion` or
+`scriptUrlLatest` using **Interactive questions** in `SKILL.md`. Preserve an existing
+supported URL unless the user requests a change or the contract requires correction.
+Do not query applications or credentials for this choice.
+
+Use the chosen URL unchanged. Attach the contract's versioned integrity only to that
+immutable URL; `latest` requires its own matching digest if SRI is used.
+
+## Gate
+
+Establish capabilities before editing; choose modes afterwards under **Choosing the
+modes**. A non-Spring-MVC backend limits backend Seamless, not frontend Seamless.
+
+| Layer / mode | Requirement | Reference |
+| --- | --- | --- |
+| Backend Seamless | Spring Boot 3 MVC, Java 17+, released starter | `backend-spring-boot.md` |
+| Backend Manual | Java 17+, released core SDK, application extraction/enforcement; also works on Boot 3 MVC | `backend-java-core.md` |
+| Frontend Seamless | Released support and page-scope `fetch` / async XHR interception | `browser-seamless.md` |
+| Frontend Manual | Released token acquisition and supported application-controlled carrier | `browser-manual.md` |
+
+Both backend modes accept `X-IntelliFend-Token`; a documented body carrier requires
+backend Manual extraction. Manual mode does not make unsupported transport valid.
+Check the selected browser reference's coverage and carrier requirements.
+
+### Run the check
+
+Locate the route's owning module, then inspect its build file. Repo-wide discovery
+may find candidates, but never combine a route from one module with Java/Spring evidence
+from another. If multiple services could own the endpoint, ask which one before editing.
+
+```bash
+rg --files -g 'pom.xml' -g 'build.gradle*' -g '!**/node_modules/**' \
+  -g '!**/build/**' -g '!**/target/**'
+rg -n "/api/register" -g "*.java" -g "*.kt" .
+```
+
+#### Java target version
+
+Read the project's target, not the machine's JDK:
+
+- Maven: `maven.compiler.release`, compiler-plugin `<release>`, or inherited
+  Spring Boot `<java.version>`; inspect the parent POM where needed.
+- Gradle: `java.toolchain.languageVersion`, `sourceCompatibility`, or Kotlin
+  `jvmToolchain`, including nested configuration blocks.
+- `.java-version`, `.sdkmanrc`, `.tool-versions`, CI JDK settings, and Docker base
+  images are hints only. If build evidence is missing, ask; `java -version` does not
+  establish the project's target.
+
+Java below 17 blocks both backend modes. Report the source and prerequisite upgrade;
+do not substitute an older SDK or install only the browser half.
+
+#### Spring Boot 3, and separately Spring MVC
+
+Check Boot version in the parent POM, dependency BOM, or Gradle plugin, and separately
+identify the stack serving the route:
+
+- `spring-boot-starter-web` / Spring MVC on Boot 3 and Java 17+ supports the starter.
+- WebFlux without MVC does not support the annotation path; use backend Manual.
+- If both stacks are present, determine which owns the route; ask if unclear.
+- Boot 2.x and other Java frameworks use backend Manual when Java 17+ is established.
+
+Report Java target, backend stack, available modes per layer, existing modes, and
+blockers with source evidence before proceeding.
+
+## Then act on what you found
+
+Use this evidence to establish backend capabilities; do not select or migrate a mode
+merely because the other option is available.
+
+| Detected | Do this |
+| --- | --- |
+| Java < 17, or no Java backend | Stop before editing. Report the finding and its source; neither backend mode is supported. Name a supported Java backend as the prerequisite. |
+| Java 17+, no Spring Boot 3 MVC | Backend Manual is the only option. State the capability limit; do not present backend Seamless as a choice. |
+| Java 17+ and Spring Boot 3 MVC | Both backend modes are viable when their artifacts are released. Apply the selection rules below. |
+| Ambiguous module, missing build file, version only in environment hints, or unclear MVC/WebFlux ownership | Ask, showing what you found. |
+
+Report file/line evidence for the owning module, Java target, framework, and available
+modes. Treat unknown values as clarification needs, not inferred compatibility.
+
+## Choosing the modes
+
+Choose one supported mode per layer using the capabilities above and the selected
+browser reference's transport/carrier limits. Apply these priorities in order:
+
+1. **Explicit preferences:** honor supported choices for each named layer. Explain
+   blockers and alternatives for unsupported choices; do not silently substitute.
+2. **Existing integration:** preserve supported modes, including mixed pairs, unless
+   the user requests migration or evidence requires correction. Verify/docs tasks
+   observe modes rather than reopen selection. During migration, replace the old path
+   with the new one in the same change and release; preserve the other layer.
+3. **One layer unselected:** recommend the matching mode if supported; otherwise a
+   compatible mixed pair. Do not change the selected layer just to match names.
+4. **Both layers new:** recommend Seamless/Seamless when all release, stack, transport,
+   and carrier requirements hold; otherwise Manual/Manual when supported. If neither
+   pair works, explain the supported mixed pair or blocker.
+
+Recommendations require the selection step below before implementation.
+
+### Ask and wait before integration edits
+
+For Install, ask about unselected layers using
+[Interactive questions](../SKILL.md#interactive-questions). Present supported modes,
+their differences, and the recommendation with its reason; even a single supported
+option needs confirmation. Wait before integration edits, dependencies, or runtime
+configuration changes; independent read-only discovery may continue.
+
+An explicit supported preference already selects that layer. Preserve existing
+supported modes. A general request to protect an endpoint, a recommendation, or silence
+is not a choice. Do not repeat questions already answered.
+
+The mode and script-URL questions may be combined, but each choice needs an answer;
+choosing one does not choose the other.
+
+Examples (frontend / backend):
+
+| Situation | Recommendation |
+| --- | --- |
+| New Spring Boot 3 MVC + Java 17+, released Seamless support, page-scope `fetch` | Seamless / Seamless |
+| New Java 17+ non-Boot or WebFlux backend; both layers otherwise unselected | Manual / Manual |
+| User requests frontend Manual on Boot 3 MVC; backend not integrated | Manual / Manual |
+| User requests frontend Seamless on a supported browser transport; backend is non-Boot Java 17+ | Seamless / Manual |
+| Frontend Manual already paired with backend Seamless | Preserve Manual / Seamless |
+| Frontend Seamless already paired with backend Manual | Preserve Seamless / Manual |
+
+Different endpoints may use different pairs. A protected operation uses exactly one
+frontend mode and one backend mode. Never combine `@RequestShieldProtected` and a
+direct `RequestShieldClient.verify()` on one request: both consume the token, so the
+second returns `token_replayed`. For the starter, state `BLOCK` or `MONITOR` separately
+as the enforcement mode; integration-mode names are not values for that setting. For
+direct core integration, describe the application's observed handling of `isAllowed()`
+without inventing a starter-style configuration property.

package/skills/requestshield/references/troubleshooting.md

@@ -0,0 +1,131 @@
+# Troubleshooting
+
+Work outward from the request, not from the code. Most reports of "RequestShield is
+broken" are one of four things: the browser never sent a token, the configured carrier
+never reached verification, the backend never verified it, or one token was verified twice.
+
+Name the observed frontend and backend integration modes separately: each can be
+Seamless or Manual where supported. Backend Seamless uses the Spring Boot 3 MVC starter;
+backend Manual uses explicit core SDK verification. A mixed pair alone is not a fault
+or a reason to migrate. Keep integration modes distinct from `BLOCK`/`MONITOR`
+enforcement behavior.
+
+## First checks
+
+Start with source inspection and runtime evidence already supplied by the user.
+Browser requests and safe backend decision metrics provide evidence about runtime behavior;
+collect new endpoint traffic only through the explicit Test flow.
+
+For HTTP liveness, run `requestshield service status --json` without login or an
+App Key. It checks Management API and Challenge Service at the caller's location
+and time; it does not verify application protection or application integration.
+Credential-status metadata remains unavailable; do not reveal a secret to check it.
+
+If supplied evidence points to rejected backend credentials, explain the likely
+configuration issue without reading secret values.
+Credential management is a separate request.
+
+## 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 backend verification | Script tag absent or loaded after the request; frontend Seamless path mismatch (case, trailing slash, wrong origin); an uncovered transport (form POST, sendBeacon, sync XHR, `no-cors`); a frontend Manual call site that never populates the configured carrier; backend extraction reading a different carrier; or CSP missing a `cspAdditions` entry, such as `workerSrc` or `'wasm-unsafe-eval'`, 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 direct `verify()`, or a filter plus a controller). |
+| `consume_unauthorized` | Backend credentials rejected | API Secret wrong, rotated, or not injected — explain the likely configuration issue from supplied evidence 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. Identify the carrier the backend actually reads: `X-IntelliFend-Token`, or a
+   documented dedicated body field for frontend Manual with backend Manual. Check
+   that carrier's presence and whether it is non-empty in the protected request;
+   do not record the token value. An absent header is expected for a body carrier.
+2. **Token absent from the configured carrier** → frontend. Seamless: compare the requested URL against
+   the exact origin and `data-protect` path segments; each `:name` must match one non-empty
+   segment, and literal case and trailing slash are significant. Also
+   check the transport is `fetch` or async XHR from page scope. Manual: find the call
+   site, and every retry path.
+3. **Header transport fails only across origins** → check CORS and preflight. The API's
+   `Access-Control-Allow-Headers` must include `X-IntelliFend-Token` when that header
+   is used, or the browser can block the request. This token-header requirement does
+   not apply to a body carrier; check CORS against that request's actual headers.
+4. **Configured carrier empty** → check token acquisition. Check the CSP
+   includes every `cspAdditions` entry from `requestshield contract --json`,
+   then check connectivity and safe backend health observations. For frontend Manual
+   using the header, an empty token means the header should be omitted, not sent empty
+   — see `browser-manual.md`.
+5. **Configured carrier populated** → backend half. Confirm extraction reads that
+   carrier unchanged, compare the App Key on both sides, then confirm runtime secret
+   injection by presence only.
+
+## "It blocks nothing"
+
+Enumerate rather than assuming the browser is at fault:
+
+- The endpoint uses `MONITOR` enforcement — 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
+
+Troubleshooting reads evidence the user already has; exercising the endpoint belongs to
+the explicit Test flow in `SKILL.md`. There, use browser network observations and
+existing safe backend metrics in an authorized environment. Do not record raw tokens or secrets. `requestshield usage <app-key>`
+provides approximate recent request totals, defaulting to 24 hours within seven-day
+retention. Missing or delayed logs can hide traffic; a zero count does not prove
+enforcement or lack of traffic. 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. Follow the private-terminal
+credential workflow in `SKILL.md`: explain the impact, warn that the replacement API
+Secret is displayed only once, and obtain confirmation under
+[Interactive questions](../SKILL.md#interactive-questions) before running:
+
+```bash
+requestshield secret rotate <app-key> --idempotency-key <agent-generated-uuid> --yes
+```
+
+Run that command only in a user-visible terminal whose output is unavailable to the
+agent. The user stores the new secret privately and confirms only whether it was saved.
+The App Key is unchanged, so no browser edit is needed. Rotation replaces the previous
+secret, but changes may take a moment. A lost response can be recovered with explicit
+reveal; an exposed secret requires rotation.

package/src/agent-detector.mjs

@@ -0,0 +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");
+
+  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;
+  }
+}