requestshield 0.1.4 → 0.1.6

package/skills/requestshield/references/browser-seamless.md

@@ -1,164 +1,156 @@
-# Browser SDK — Seamless mode
-
-Seamless mode is the recommended browser integration for applications that use `fetch`
-or asynchronous `XMLHttpRequest`. Browser SDK 1.1 matches configured application
-endpoints and adds `X-IntelliFend-Token` automatically, so no call site changes.
-
-Prerequisites: a public App Key, the **exact** application API endpoints to protect, and
-backend protection configured for the corresponding operations.
-
-## 1. Load the hosted SDK
-
-Place the script before any application bundle that can issue a protected request —
-otherwise an early request leaves the page before interception is installed:
-
-```html
-<script
-  src="SCRIPT_URL_FROM_CONTRACT"
-  data-app-key="YOUR_APP_KEY"
-  data-protect='["/api/register"]'
-  defer
-></script>
-```
-
-`data-protect` is a **JSON array** — note the single quotes around the attribute so the
-inner double quotes survive. Each entry is either a root-relative pathname beginning
-with `/`, or an absolute URL without embedded credentials. Malformed JSON is a configuration
-error — validate the attribute before shipping rather than assuming a parse failure will
-announce itself.
-
-Applications with a custom script loader can configure the same behaviour after the
-hosted script loads:
-
-```javascript
-IntelliFend.init({
-  appKey: 'YOUR_APP_KEY',
-  protect: ['/api/register'],
-});
-```
-
-Use script attributes *or* explicit initialization for initial setup, not both.
-
-## 2. Match application endpoints exactly
-
-RequestShield compares the **exact origin and exact pathname**. This is where a Seamless
-install either works or quietly does nothing, so resolve it before writing the attribute:
-
-- Query strings and fragments are ignored on both sides.
-- **Pathname case and trailing slash are significant.**
-- Root-relative entries resolve against the page origin.
-- Cross-origin entries use HTTPS, except for loopback development.
-- The same endpoint rule applies to every HTTP method.
-
-So `/api/register` matches `/api/register?source=campaign`, but it does **not** match
-`/api/Register` or `/api/register/`.
-
-The practical consequence: **list the URL the application passes to `fetch` or
-asynchronous `XMLHttpRequest`.** With a normal development proxy, the application
-requests `/api/register` on the frontend origin. The proxy then rewrites and forwards
-that request to an upstream route such as `https://api.example.com/register`. The
-rewrite happens outside the browser and does not change the URL matched by Seamless.
-Configure `/api/register`, and ensure the proxy forwards `X-IntelliFend-Token`
-unchanged.
-
-If the application directly requests `https://api.example.com/register`, configure
-that absolute URL instead and configure CORS to allow the page origin, request method,
-and `X-IntelliFend-Token`.
-
-A redirect is different from a proxy rewrite. With an HTTP redirect, the server returns
-a `3xx` response and the browser follows its `Location`. Seamless matches the original
-URL passed by application code; it does not separately match the browser's internal
-redirect request. Do not configure only the redirect destination when the application
-initially requests `/api/register`. Avoid redirects for protected mutation endpoints
-when possible, or verify the method, header, and CORS behavior end to end.
-
-A path built with an ID or slug (`/api/orders/42`) has no wildcard support — list every
-concrete path, or use Manual mode for that operation.
-
-## 3. Send requests normally
-
-Application code does not call `getToken()` or construct the header for a
-Seamless-mode endpoint:
-
-```javascript
-const response = await fetch('/api/register', {
-  method: 'POST',
-  headers: {'Content-Type': 'application/json'},
-  body: JSON.stringify({email, password}),
-});
-```
-
-Browser configuration controls token attachment only. Configure the corresponding
-backend operation independently — `data-protect` creates no backend protection.
-
-## What Seamless covers
-
-Supported: `fetch` (string, `URL`, and `Request` inputs) and asynchronous
-`XMLHttpRequest`.
-
-Do not rely on Seamless and a Manual call site coexisting on the same endpoint. One
-protected operation uses one mode — see the prerequisites in `browser-manual.md`.
-
-## What Seamless does not cover
-
-Any of these means the request leaves without a token, with no error — which is why
-they are worth checking *before* choosing the mode:
-
-- Synchronous XHR.
-- Native form navigation (a plain `<form>` submit).
-- `navigator.sendBeacon`.
-- WebSocket and EventSource.
-- Service-worker-owned requests. Web workers and server-side rendering have their own
-  global scope too — in Next.js, Nuxt, Remix and similar, confirm the protected call
-  runs in the browser.
-- A `fetch` using `no-cors`, which cannot carry a custom header at all.
-
-For an operation on this list, use Manual mode **only if** the application can carry the
-token in a supported header or request-body field. Otherwise the right answer is an
-application-specific integration agreed with IntelliFend — say that plainly rather than
-improvising a carrier.
-
-## Cross-origin APIs
-
-When the protected endpoint is on another origin, its CORS response must allow the page
-origin, the intended methods, and the `X-IntelliFend-Token` header. Missing that header
-in `Access-Control-Allow-Headers` means the browser strips it and every request reads as
-missing a token.
-
-## Verifying Seamless
-
-Static checks:
-
-1. Exactly one script tag, loaded before application bundles, with valid JSON in
-   `data-protect`.
-2. Every listed entry matches a URL the browser actually requests — origin, case, and
-   trailing slash included.
-3. Every protected endpoint reaches the network via `fetch` or async XHR from page
-   scope.
-
-Runtime check: exercise the endpoint, confirm the network request carries a non-empty
-`X-IntelliFend-Token`, then confirm the platform saw it. This proves the browser half is
-firing; the negative test in `SKILL.md` proves backend enforcement.
-
-```bash
-requestshield challenge volume <app-key> \
-  --from <start> \
-  --to <end> \
-  --granularity hour
-```
-
-Zero volume with a correct-looking `data-protect` is nearly always a path mismatch
-(trailing slash, case, a different origin than assumed) or one of the uncovered
-transports above. Re-read the actual request URL before changing anything else.
-
-## Expected result
-
-Matching requests carry one non-empty `X-IntelliFend-Token` header; requests outside the
-configured list are unchanged.
-
-## CSP and token handling
-
-Identical to Manual mode — see the CSP and token-handling sections of
-`browser-manual.md`. The `worker-src 'self' blob:` directive matters just as much here:
-without it, every intercepted request attaches an empty token and the backend blocks
-traffic that looks correctly integrated.
+# Browser SDK — Seamless mode
+
+Seamless mode is the recommended browser integration for applications that use `fetch`
+or asynchronous `XMLHttpRequest`. Browser SDK 1.1 matches configured application
+endpoints and adds `X-IntelliFend-Token` automatically, so no call site changes.
+
+Prerequisites: a public App Key, the **exact** application API endpoints to protect, and
+backend protection configured for the corresponding operations.
+
+## 1. Load the hosted SDK
+
+Place the script before any application bundle that can issue a protected request —
+otherwise an early request leaves the page before interception is installed:
+
+```html
+<script
+  src="SDK_SCRIPT_URL_FROM_RELEASE_DOCS"
+  data-app-key="YOUR_APP_KEY"
+  data-protect='["/api/register"]'
+  defer
+></script>
+```
+
+`data-protect` is a **JSON array** — note the single quotes around the attribute so the
+inner double quotes survive. Each entry is either a root-relative pathname beginning
+with `/`, or an absolute URL without embedded credentials. Malformed JSON is a configuration
+error — validate the attribute before shipping rather than assuming a parse failure will
+announce itself.
+
+Applications with a custom script loader can configure the same behaviour after the
+hosted script loads:
+
+```javascript
+IntelliFend.init({
+  appKey: 'YOUR_APP_KEY',
+  protect: ['/api/register'],
+});
+```
+
+Use script attributes *or* explicit initialization for initial setup, not both.
+
+## 2. Match application endpoints exactly
+
+RequestShield compares the **exact origin and exact pathname**. This is where a Seamless
+install either works or quietly does nothing, so resolve it before writing the attribute:
+
+- Query strings and fragments are ignored on both sides.
+- **Pathname case and trailing slash are significant.**
+- Root-relative entries resolve against the page origin.
+- Cross-origin entries use HTTPS, except for loopback development.
+- The same endpoint rule applies to every HTTP method.
+
+So `/api/register` matches `/api/register?source=campaign`, but it does **not** match
+`/api/Register` or `/api/register/`.
+
+The practical consequence: **list the URL the application passes to `fetch` or
+asynchronous `XMLHttpRequest`.** With a normal development proxy, the application
+requests `/api/register` on the frontend origin. The proxy then rewrites and forwards
+that request to an upstream route such as `https://api.example.com/register`. The
+rewrite happens outside the browser and does not change the URL matched by Seamless.
+Configure `/api/register`, and ensure the proxy forwards `X-IntelliFend-Token`
+unchanged.
+
+If the application directly requests `https://api.example.com/register`, configure
+that absolute URL instead and configure CORS to allow the page origin, request method,
+and `X-IntelliFend-Token`.
+
+A redirect is different from a proxy rewrite. With an HTTP redirect, the server returns
+a `3xx` response and the browser follows its `Location`. Seamless matches the original
+URL passed by application code; it does not separately match the browser's internal
+redirect request. Do not configure only the redirect destination when the application
+initially requests `/api/register`. Avoid redirects for protected mutation endpoints
+when possible, or verify the method, header, and CORS behavior end to end.
+
+A path built with an ID or slug (`/api/orders/42`) has no wildcard support — list every
+concrete path, or use Manual mode for that operation.
+
+## 3. Send requests normally
+
+Application code does not call `getToken()` or construct the header for a
+Seamless-mode endpoint:
+
+```javascript
+const response = await fetch('/api/register', {
+  method: 'POST',
+  headers: {'Content-Type': 'application/json'},
+  body: JSON.stringify({email, password}),
+});
+```
+
+Browser configuration controls token attachment only. Configure the corresponding
+backend operation independently — `data-protect` creates no backend protection.
+
+## What Seamless covers
+
+Supported: `fetch` (string, `URL`, and `Request` inputs) and asynchronous
+`XMLHttpRequest`.
+
+Do not rely on Seamless and a Manual call site coexisting on the same endpoint. One
+protected operation uses one mode — see the prerequisites in `browser-manual.md`.
+
+## What Seamless does not cover
+
+Any of these means the request leaves without a token, with no error — which is why
+they are worth checking *before* choosing the mode:
+
+- Synchronous XHR.
+- Native form navigation (a plain `<form>` submit).
+- `navigator.sendBeacon`.
+- WebSocket and EventSource.
+- Service-worker-owned requests. Web workers and server-side rendering have their own
+  global scope too — in Next.js, Nuxt, Remix and similar, confirm the protected call
+  runs in the browser.
+- A `fetch` using `no-cors`, which cannot carry a custom header at all.
+
+For an operation on this list, use Manual mode **only if** the application can carry the
+token in a supported header or request-body field. Otherwise the right answer is an
+application-specific integration agreed with IntelliFend — say that plainly rather than
+improvising a carrier.
+
+## Cross-origin APIs
+
+When the protected endpoint is on another origin, its CORS response must allow the page
+origin, the intended methods, and the `X-IntelliFend-Token` header. Missing that header
+in `Access-Control-Allow-Headers` means the browser strips it and every request reads as
+missing a token.
+
+## Verifying Seamless
+
+Static checks:
+
+1. Exactly one script tag, loaded before application bundles, with valid JSON in
+   `data-protect`.
+2. Every listed entry matches a URL the browser actually requests — origin, case, and
+   trailing slash included.
+3. Every protected endpoint reaches the network via `fetch` or async XHR from page
+   scope.
+
+Runtime check: exercise the endpoint in an authorized environment and confirm its
+request carries a non-empty `X-IntelliFend-Token` without recording the token value.
+Inspect safe backend decision metrics separately; the negative test in `SKILL.md`
+provides enforcement evidence. The CLI challenge-volume command is unavailable.
+A missing header can indicate a path mismatch or an uncovered transport; compare
+the actual request URL and transport before changing backend code.
+
+## Expected result
+
+Matching requests carry one non-empty `X-IntelliFend-Token` header; requests outside the
+configured list are unchanged.
+
+## CSP and token handling
+
+Identical to Manual mode — see the CSP and token-handling sections of
+`browser-manual.md`. The `worker-src 'self' blob:` directive matters just as much here:
+without it, every intercepted request attaches an empty token and the backend blocks
+traffic that looks correctly integrated.

package/skills/requestshield/references/cli.md

@@ -1,182 +1,107 @@
-# `requestshield` CLI reference
-
-Every RequestShield platform action goes through this CLI. There is no supported way
-to create keys, read the contract, or check traffic by hand-crafting HTTP calls, so if
-a task needs one of these values, run the command rather than guessing.
-
-Commands marked **auth** require a signed-in session (`requestshield signin`). The CLI
-also exposes local commands that do not need platform API access, such as `--help`,
-`--version`, and agent setup. Check once with `auth status` before a multi-step
-platform task instead of discovering it halfway through an edit.
-
-Most commands print JSON shaped `{"ok": true, "data": {...}}`. Parse `data`; treat
-`ok: false` as a hard stop and surface the message rather than continuing with edits.
-
-## Contents
-
-- [General](#general)
-- [Authentication](#authentication)
-- [Key management](#key-management)
-- [Integration contract](#integration-contract)
-- [Applications](#applications)
-- [Credentials](#credentials)
-- [Service and monitoring](#service-and-monitoring)
-- [Billing](#billing)
-- [Agent integration](#agent-integration)
-
-## General
-
-| Command | Purpose |
-| --- | --- |
-| `requestshield --help` | Usage and the full command list. Run this if a command below is rejected — the installed CLI may be older or newer than this file. |
-| `requestshield --version` | Installed CLI version, e.g. `requestshield 1.0.0`. |
-| `requestshield update check` | Latest available version. Use it when behaviour disagrees with this reference. |
-
-## Authentication
-
-```bash
-requestshield signin
-requestshield auth status
-```
-
-**auth/API.**
-
-`signin` is interactive and stores a session on the machine. **Never try to automate
-it or ask for the user's credentials** — if the user is signed out, tell them to run it
-themselves and wait.
-
-`auth status` returns `{"ok":true,"data":{"authenticated":true,"customer_id":"customer_456"}}`.
-The `customer_id` is useful context to echo back so the user can confirm they are
-operating on the right account before you create or deactivate anything.
-
-## Key management
-
-**The user runs these, not you.** They print the API Secret or change state for a live
-App Key, so hand over the exact command and let them run it in their own terminal. See
-"Key and secret management" in `SKILL.md` for the hand-off and the follow-up
-presence check.
-
-```bash
-requestshield keys create --app-name <name>
-requestshield keys deactive --app-key <app-key>      # or --app-name <name>
-requestshield app key rotate --app-key <app-key>     # or --app-name <name>
-```
-
-`keys create` returns both halves:
-
-```
-App Key: app_123
-Secret Key: rs_sk_xxxxx
-Save this Secret Key now. It will not be shown again.
-```
-
-The Secret Key appears exactly once. Warn the user *before* they run the command that
-they need somewhere to put it, and afterwards point them at the environment variable
-rather than repeating the value. Never ask them to paste the secret back — confirm it
-only by presence. See the secret-handling rules in `SKILL.md`.
-
-`keys deactive` (spelled that way in the CLI) needs at least one of `--app-key` or
-`--app-name`; if both are given, `--app-key` wins. Deactivation stops traffic being
-verified for that key, so name the affected app explicitly when you hand the command
-over and make sure the user means that key.
-
-`app key rotate` issues a new Secret Key for an existing App Key and deactivates the
-previous one. This is the correct response to a leaked or lost secret — it keeps the
-App Key stable, so no browser or config change is needed beyond the new secret. Like
-`keys create`, the user runs it.
-
-## Integration contract
-
-```bash
-requestshield contract
-```
-
-**auth.** The authoritative integration surface — run this before writing any
-integration code. The block below is an **illustration of the shape only**; never read
-values out of it, and in particular do not treat its `available_modes` as the modes your
-customer has:
-
-```json
-{"ok":true,"data":{
-  "contract_version":"2026-08-27",
-  "browser":{"script_url":"https://.../intellifend.js","token_header":"X-IntelliFend-Token",
-             "available_modes":["manual"]},
-  "backend":{"supported_languages":["java"],"min_jdk":17},
-  "release_state":"..."}}
-```
-
-Use `script_url` and `token_header` verbatim. Check `available_modes` before committing
-to seamless or manual — a mode absent from that list is not released, and writing an
-integration against it produces code that will not work. Check `supported_languages`
-before promising a backend integration for a stack that is not listed; the browser side
-alone provides no protection, so an unsupported backend means the honest answer is
-"not yet supported here".
-
-## Applications
-
-```bash
-requestshield apps list
-requestshield apps get <app-key>
-```
-
-**auth.** `apps list` returns the applications the current user can access, each with
-`app_key`, `name`, and `status`. Use it to resolve a human-supplied app name to a key
-rather than asking the user to retype one.
-
-`apps get <app-key>` returns `app_id`, `app_name`, and `status`. Status distinguishes a
-key that has never seen traffic (`ready`) from one in normal service (`active`) — which
-is exactly the difference between "the integration is not wired up yet" and "it is
-working", so check it before spending time debugging code.
-
-## Credentials
-
-```bash
-requestshield credentials status <app-key>
-```
-
-**auth.** Returns metadata only — `provisioned`, `active`, `shared` — and never the
-secret value. Use it to answer "is the secret configured?" without anyone having to
-paste a credential. A key that is `provisioned: false` explains backend failures far
-faster than reading code.
-
-## Service and monitoring
-
-```bash
-requestshield server
-requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]
-```
-
-**auth.** `server` reports `healthy` or `degraded`. Check it first when an integration
-that was working starts behaving oddly — a degraded platform explains fail-open
-behaviour on the backend without anything being wrong in the customer's code.
-
-`challenge volume` is runtime evidence that the browser/platform half is active. It is
-not proof that the protected backend enforces a blocking decision; the controlled
-negative test in `SKILL.md` provides that evidence. Times are ISO-8601
-(`2026-08-01T00:00:00Z`); `--granularity` takes values such as `hour` or `day`. A
-`challenge_count` of zero after the user has exercised the endpoint means the browser
-half is not firing — that is a browser-side bug, not a backend one, so start with the
-mode's reference file.
-
-## Billing
-
-```bash
-requestshield get billing
-```
-
-**auth.** Current plan and usage for the application. Read-only; surface it when the
-user asks about cost or limits.
-
-## Agent integration
-
-```bash
-requestshield agent setup
-requestshield agent setup --agent claude
-requestshield agent setup --agent codex
-```
-
-Local setup. Installs this skill for the named agent. With no `--agent`, the CLI detects
-which agent is in use. Run it when the user wants the skill available in another repo or
-for the other agent; it is the supported alternative to copying files by hand. It should
-not require a RequestShield App Key or API Secret, and it must not create, rotate, or
-deactivate customer credentials.
+# `requestshield` CLI reference
+
+Check `requestshield --version` and `requestshield --help` against this guide.
+An older published version may not contain these commands. Use the CLI for its
+supported application and credential operations; do not invent endpoints for
+unavailable commands.
+
+## Authentication and local commands
+
+```console
+requestshield signin [--no-open]
+requestshield auth status [--json]
+requestshield signout
+requestshield --help
+requestshield --version
+```
+
+Sign-in uses the user's browser on the same computer. Let the user complete it;
+never ask for their password, tokens or callback URL. `auth status --json` reads
+local metadata only and does not contact the provider or refresh credentials.
+It returns `profile`, `apiUrl`, `issuer`, `clientId`, `state`, `localOnly: true`
+and applicable `expiresAt`/`scopes`, never tokens or a customer/account identity.
+States are `signed_out`, `valid`, `expired`, `refresh_uncertain`, `config_mismatch`,
+`invalid` and `configuration_error`. Local validity is not provider acceptance.
+Sign-out removes only the selected local session, not the browser session or
+provider grant.
+
+## Applications
+
+```console
+requestshield apps list [--json] [--limit <1-100>] [--cursor <cursor> | --all]
+requestshield apps get <app-key>
+requestshield apps rename <app-key> --name <name> [--idempotency-key <key>]
+requestshield apps enable <app-key> [--idempotency-key <key>]
+requestshield apps disable <app-key> [--idempotency-key <key>] [--yes]
+```
+
+These commands require sign-in. Existing-app commands use exact App Keys; names
+are not unique. List defaults to one page. `--all` follows at most 100 pages and
+fails for repeated cursors or unfinished traversal at that bound. It cannot be
+combined with `--cursor`. For name discovery, inspect all necessary pages and
+resolve ambiguity with the user before choosing an App Key.
+
+JSON list output is `{data:Application[],nextCursor}`. Detail and rename output
+is `{data:Application}`. Application has exactly `appKey`, `name`, `status`,
+`createdAt`, `updatedAt`. Status is `pending`, `enabled`, `disabled`, `revoked`
+or `attention_required`; it describes configuration, not traffic or enforcement.
+Pending, attention and disabled states do not expose the exact credential state.
+Disable retains the secret; enable requires an active one.
+
+## Key and secret management
+
+Have the user run commands that print secrets in their own terminal so secret
+values stay out of tool output and transcripts. Give the exact command and
+confirm storage by presence only.
+
+```console
+requestshield keys create --app-name <name> [--idempotency-key <key>]
+requestshield keys rotate <app-key> [--idempotency-key <key>] [--yes]
+requestshield keys reveal <app-key> [--yes]
+requestshield keys revoke <app-key> [--idempotency-key <key>] [--yes]
+```
+
+Create makes a new application and initial secret. Rotate preserves the App Key
+and replaces the secret. Reveal retrieves the current active secret; use it to
+recover a lost issuance response. Exposure requires rotation, not reveal.
+Revoke invalidates the current secret. Create, rotate and reveal can display an
+API secret; the CLI never persists it. Store it in backend secret storage.
+
+Create, rename and enable have no prompt. Disable, rotate, revoke and reveal
+require confirmation; `--yes` skips it. These commands can change live state or
+disclose secrets, so ensure the target and action match the user's request.
+
+All mutations except reveal accept an idempotency key. A fresh key is generated
+per invocation when omitted and printed to stderr before dispatch so interrupted
+commands can reuse it; JSON stdout is unchanged. There is no automatic mutation retry. On uncertainty,
+repeat the identical request and key printed in the error within seven days.
+A new key is a new operation. After seven days inspect state before acting.
+Create/rotate replay can have `apiSecret: null`; the CLI directs explicit reveal
+without running it. HTTP 202 and `enabled` do not prove global propagation.
+
+## Agent setup and updates
+
+```console
+requestshield agent setup [--codex | --claude] [--force]
+requestshield update check
+```
+
+Agent setup copies the skill to `~/.agents/skills/requestshield` for Codex or
+`~/.claude/skills/requestshield` for Claude. With neither flag, it detects the
+agent or asks if both are available. `--force` replaces an existing installation.
+It does not edit repository `AGENTS.md` or customer application code.
+
+Production update check queries npm and asks before a global installation.
+Explain that target before accepting an update; it does not update a pinned
+invocation or source checkout. Repository-only QAT/STG runners return local
+source-update guidance without registry access or installation.
+
+## Unavailable commands
+
+Integration contract, service health, credential-status metadata, challenge
+volume and billing are not implemented CLI capabilities. `contract`,
+`challenge volume` and `get billing` fail with `COMMAND_UNAVAILABLE` before
+configuration, authentication or network access. `server` and
+`credentials status` are unsupported. Use the published SDK documentation for
+the chosen release and safe browser/backend observations for integration checks.
+Do not infer traffic or enforcement from `apps get` status.