requestshield 0.0.0-stage → 1.0.0-stg.276

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

@@ -0,0 +1,213 @@
+# Frontend Seamless — Browser SDK
+
+Frontend Seamless supports applications that use page-scope `fetch` or asynchronous
+`XMLHttpRequest`, when the selected Browser SDK release supports it. The SDK matches configured
+application endpoints and adds `X-IntelliFend-Token` automatically, so no call site
+changes are needed.
+
+It works with backend Seamless (Spring Boot 3 MVC starter) or backend Manual (Java core
+SDK). Follow `integration-planning.md` for the default pairing recommendation; preserve
+explicit valid preferences and existing supported integrations.
+
+Prerequisites: a public App Key, the **exact** application API endpoints to protect, and
+backend protection configured for the corresponding operations.
+
+The Install flow may wire this integration before credentials are created. Use the
+application's public configuration mechanism for the App Key when possible. Otherwise
+leave the explicit `YOUR_APP_KEY` placeholder and report its exact location. Do not run
+runtime checks until the user has supplied the real App Key; they belong to the
+explicit Test flow, never Verify.
+After static installation, recommend supplying the real App Key at the reported
+binding or placeholder, configuring the backend variables in its reference, restarting
+or redeploying, and testing the selected endpoint. Perform these steps only when
+separately requested.
+
+## 1. Load the hosted SDK
+
+Place the hosted SDK once in `<head>` before any application bundle that can issue a
+protected request. Use the selected contract URL (`data.browser.scriptUrlVersion` or
+`data.browser.scriptUrlLatest`) and only its matching integrity when provided.
+Bind `data-app-key` or `init()`'s `appKey` through public application configuration when
+it can be wired without a value; otherwise keep `YOUR_APP_KEY` and report its location.
+
+```html
+<script
+  src="SDK_SCRIPT_URL_FROM_RELEASE_DOCS"
+  data-app-key="YOUR_APP_KEY"
+  data-protect='["/api/register"]'
+  defer
+></script>
+```
+
+`defer` keeps order only relative to other `defer` and module scripts. If a bundle that
+can issue a protected request is a classic script with no `defer`, or is `async`, add
+`defer` to that bundle or remove `defer` from the SDK tag.
+
+`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.
+
+Browser SDK 2.0.0 accepts `apiVersion: 'v1' | 'v2'` or
+`data-api-version="v1" | "v2"` and defaults to v2. Existing Browser 1.0.0
+integrations use v1 without this option. Preserve existing pins and API choices.
+API selection is independent of Seamless/Manual mode and does not change the
+2.0.0 WebAssembly or CSP requirements. See `integration-planning.md` for
+mixed-version limits.
+
+## 2. Match application endpoints
+
+RequestShield compares the **exact origin** and the configured pathname. Ordinary paths
+match exactly; named parameters match one non-empty path segment:
+
+- 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.
+- A whole segment such as `:orderId` matches one non-empty segment, never across `/`.
+  Names use `[A-Za-z_][A-Za-z0-9_]*`. Multiple parameters are supported.
+
+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.
+
+For an ID or slug, configure the path once:
+
+```javascript
+IntelliFend.init({
+  appKey: 'YOUR_APP_KEY',
+  protect: ['/api/orders/:orderId/items'],
+});
+```
+
+The script-tag equivalent is
+`data-protect='["/api/orders/:orderId/items"]'`.
+This rule matches `/api/orders/42/items?include=details`
+and `/api/orders/abc-123/items`. It does not match an empty ID,
+an extra path segment, a trailing slash, different pathname case, or another origin.
+Absolute rules such as `https://api.example.com/api/orders/:orderId/items` use the
+same path syntax and match only that origin.
+
+Use `::name` to match a literal `:name` segment. When updating an existing rule
+that contains a literal leading colon, add one colon to preserve its meaning:
+`/orders/:fixed` becomes `/orders/::fixed`. Percent-encoded spelling stays distinct:
+`%3Aname` matches that encoded segment, not `:name`. Browser URL normalization
+applies, including dot segments, but the matcher does not decode the pathname;
+`a%2Fb` is one serialized segment and `a/b` is two. Malformed parameters cause
+`invalid_config`. Wildcards, arbitrary regex, catch-all parameters and method
+filtering are not supported.
+
+## 3. Send requests normally
+
+Application code does not call `getToken()` or construct the header for a
+frontend Seamless 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 combine frontend Seamless and a frontend Manual call site on the same endpoint.
+One protected operation uses one frontend mode; either may pair with either supported
+backend 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 SDK initialization — one script tag with its attributes, **or** one
+   `IntelliFend.init()` call — loaded before application bundles, with valid JSON in
+   `data-protect` (or a valid `protect` array).
+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 (Test flow only, not Verify): during the control request of the
+negative test in `SKILL.md`, confirm the request carries a non-empty
+`X-IntelliFend-Token` without recording the token value. Inspect safe backend decision
+metrics separately; the negative test provides enforcement evidence. `requestshield usage <app-key>` can show approximate
+recent request counts, but does not prove backend enforcement.
+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 contract's `cspAdditions` entries, including `workerSrc` and
+`scriptSrc`, matter just as much here: without them, every intercepted request attaches an empty token and the backend blocks
+traffic that looks correctly integrated.

package/skills/requestshield/references/cli.md

@@ -0,0 +1,314 @@
+# `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. Command/group help comes from the same registry as parsing.
+Legacy aliases are removed; use singular app/secret groups and positional names.
+All result commands support --json, with one document on stdout and diagnostics
+on stderr. Human output is the default; help/version remain text. JSON does not
+skip confirmation: supply --yes only when the action is authorized. Credential-producing
+commands without `--output` display the API Secret, including in JSON, so that output
+must never enter the agent terminal or tool transcript. The skill uses `--output` for
+create and a private user-visible terminal for rotate/reveal.
+
+Every option question, approval, or confirmation in this reference follows
+[Interactive questions](../SKILL.md#interactive-questions): use selectable options
+and resume automatically after the submitted answer. Do not request typed selections.
+
+## Public integration contract
+
+```console
+requestshield contract
+requestshield contract --json
+```
+
+This public read fetches the integration contract without
+login, local session access or file writes. It returns the versioned and latest
+browser URLs; the CLI does not accept a version flag.
+JSON returns `{data: ...}` with `schemaVersion: 2`, `contractVersion`,
+`services.challengeUrl`, `browser`, `backend` and `documentation`.
+Use `data.browser.scriptUrlVersion` or `data.browser.scriptUrlLatest` as selected by the
+integration flow. Use the matching `data.browser.integrity` only with the immutable
+versioned URL. Prefer versioned when controlled upgrades or SRI are needed; latest
+updates automatically and may serve a different version. `data.browser.sdkVersion`
+and `data.browser.availableModes` describe the pinned release only. Before using
+versioned, check its SDK version and modes against release-specific documentation;
+a Browser SDK 2.x guide may not apply to a pinned 1.x release. For latest, establish
+capabilities from current public documentation and release notes, never from pinned
+metadata. Use `tokenHeader` and merge shared `browser.cspAdditions` into the
+application's existing CSP.
+Use `backend.sdkVersion`, `minJdk`, `mavenRepository`, `core` and `springBoot3`
+coordinates for the selected backend integration. Backend Seamless uses `springBoot3`
+(Spring Boot 3 MVC starter); backend Manual uses `core` (explicit Java core SDK
+verification). These are integration labels, not new JSON fields or configuration
+values. `browser.availableModes` describes frontend capabilities only; the starter's
+`BLOCK`/`MONITOR` enforcement setting is separate from integration modes.
+Configure the same returned challenge
+URL in both SDKs. Metadata describes a selected release, not service health or
+application protection.
+
+`CONTRACT_NOT_PUBLISHED` means the docs host returned 404; `CONTRACT_FETCH_FAILED`
+means network/HTTP failure; `CONTRACT_INVALID` means the response failed validation.
+These exit 1. Schema 1 and the old `scriptUrl` field are unsupported; update the
+CLI and retry, then contact support if the error continues. Do not invent a manifest or silently substitute another environment
+or SDK version. An older CLI may not implement this command: use verified release
+documentation for a manual integration and report the missing command or manifest.
+
+## Authentication and local commands
+
+```console
+requestshield login [--no-open]
+requestshield auth status [--json]
+requestshield logout
+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 check online access or renew credentials.
+It returns `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 does not confirm online access.
+Before login or logout, explain the exact
+local-session action and obtain a fresh confirmation under **Interactive questions**; a
+direct request does not replace that confirmation. Sign-out removes the saved CLI
+session; the browser stays signed in.
+
+## Applications
+
+```console
+requestshield app list [--json] [--limit <1-100>] [--cursor <cursor> | --all]
+requestshield app get <app-key>
+requestshield app rename <app-key> <name> [--idempotency-key <key>]
+requestshield app enable <app-key> [--idempotency-key <key>]
+requestshield app disable <app-key> [--idempotency-key <key>] [--yes]
+```
+
+These commands use an authenticated CLI session. 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.
+
+Run list and get automatically. Create, enable, and disable require the skill's fresh
+confirmation under **Interactive questions** because they create or change credential
+validity. A direct request for an exact App Key and new name authorizes rename without
+another confirmation.
+
+JSON list output is `{data:Application[],nextCursor}`. Detail and rename with
+`--json` return `{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
+
+For create, first complete the [sign-in steps](integration-planning.md#sign-in), then
+check installed `app create --help` for `--output` support. Choose a new
+absolute file path in a private directory outside the repository, explain the name and
+path, and obtain confirmation under **Interactive questions**. Run create with
+`--output <absolute-private-file> --json` in the agent terminal. The CLI saves both
+credentials as ENV entries with owner-only permissions and refuses existing files.
+Confirm only the returned `appKey`, `outputPath`, and `secretStored: true`; never read
+the file. Tell the user its path and that their backend must be configured to load it.
+Do not ask whether they saved the secret or open another terminal. If the installed CLI
+lacks `--output`, stop and report that a compatible CLI is required.
+
+Rotate and reveal use the private-terminal workflow. Before running one, explain the
+exact action and target, warn the user that the API Secret is shown only once by that
+command and must be stored immediately, and obtain confirmation under **Interactive
+questions**.
+
+After approval, run the command only in a private user-visible terminal whose stdout
+and stderr are unavailable to the agent. A second agent-controlled shell or PTY does
+not qualify. If the host cannot provide a private terminal, give the user the exact
+command to run in their own terminal. Never capture, redirect, read, copy, or request
+the output. Afterwards ask only whether the command succeeded and the secret was
+stored securely.
+
+```console
+requestshield app create <name> --idempotency-key <key> --output <absolute-private-file> --json
+requestshield secret rotate <app-key> [--idempotency-key <key>] --yes
+requestshield secret reveal <app-key> --yes
+requestshield secret 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. Saving an ENV file does not configure the
+application. For rotate/reveal, the user must save the displayed values securely.
+If create cannot save a file, or the user did not store a displayed secret, explain the
+supported recovery choice. Never create, reveal, or rotate automatically.
+
+Create and enable have no CLI prompt. Disable, rotate, revoke and reveal require CLI
+confirmation; `--yes` skips it. The skill's fresh **Interactive questions** approval is
+required before create, enable, disable, rotate, reveal, or revoke; a direct request or
+missing CLI prompt is not authorization. Rename is not a credential-validity action and
+follows the direct-request rule above.
+
+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. There is no automatic mutation retry. On uncertainty,
+repeat the identical request and key printed in the error within seven days. For
+create and rotate, the agent generates the key and includes it in the command so it
+can repeat the same request key. A create retry must never overwrite an existing
+output file; choose a new private path if needed. A replay with no secret does not
+confirm a saved file; report the CLI's recovery guidance without automatically revealing.
+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. Changes may take a moment. Check application status and test your integration.
+
+## Agent setup and updates
+
+```console
+requestshield agent setup [--codex | --claude] [--force]
+requestshield agent status [--codex | --claude]
+requestshield update check
+requestshield update apply [--yes]
+```
+
+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. A direct request
+to set up the exact target agent authorizes this command without another confirmation.
+
+Agent status inspects both agents by default and returns `installed`, `missing`
+or `invalid` file state. It does not establish that an agent has loaded the Skill.
+
+Update check runs automatically without prompting or installing. When the user
+directly requests a CLI update, run `update apply --yes` without asking for another
+confirmation. A request to check for an update does not authorize installation. A
+global update does not change a pinned invocation. If automatic updates are unavailable
+for the installation, JSON returns `outcome: "unavailable"` without installing.
+
+## Complete command catalog
+
+All result commands support --json. See command help for additional flags.
+
+| Command after `requestshield` | Purpose |
+| --- | --- |
+| `--help`, `-h` | Show help. |
+| `--version`, `-v` | Show the CLI version. |
+| `login [--no-open]` | Sign in through your browser. |
+| `logout` | Remove your saved local session. |
+| `auth status` | Inspect local session status. |
+| `app create <name>` | Create an application and its initial secret. |
+| `app list` | List applications. |
+| `app get <app-key>` | Inspect an application. |
+| `app rename <app-key> <name>` | Rename an application. |
+| `app enable <app-key>` | Enable an application. |
+| `app disable <app-key>` | Disable an application while keeping its secret. |
+| `secret rotate <app-key>` | Replace the current secret. |
+| `secret reveal <app-key>` | Retrieve the current active secret. |
+| `secret revoke <app-key>` | Revoke the current secret. |
+| `agent setup [--codex \| --claude] [--force]` | Install integration guidance. |
+| `agent status [--codex \| --claude]` | Inspect installed Skill files. |
+| `update check` | Check for a newer CLI version. |
+| `update apply [--yes]` | Install the available version globally. |
+| `contract` | Read the SDK integration contract. |
+| `service status` | Check service availability. |
+| `usage <app-key>` | Read approximate recent request counts. |
+| `billing get <app-key>` | Read account usage, quota and estimated cost. |
+
+Never infer secret state from application status or call reveal as a status probe.
+Doctor and app watch are not commands.
+
+Use published SDK documentation for the selected release and safe browser/backend
+observations for integration checks. App status is not traffic or enforcement.
+
+## Account billing
+
+```console
+requestshield billing get your-app-key
+requestshield billing get your-app-key --json
+```
+
+Use the existing saved sign-in session and an exact App Key owned by the user.
+The App Key selects an account-wide report across its applications; do not
+allocate the account charge or included allowance to the requested app. The
+command is read-only and uses the existing application-read permission.
+
+Billing counts authenticated API v2 token verification requests, including
+rejected requests and retries. API v1 activity, unauthenticated requests and
+service errors are excluded.
+
+JSON returns `{data: ...}` with `appKey`, `scope: "account"`, subscription
+`status`, nullable `plan` (`free` for Express or `pro`), nullable
+`billingPeriod: {start,end}`, nullable `includedAllowance`, `usage`,
+`remainingQuota` and `overage`, `unit: "token_verification_requests"`,
+`approximate: true`, `reportedAt`, nullable `usageThrough`, and nullable
+`estimatedCost: {currency,baseAmountMinor,overageAmountMinor,totalAmountMinor}`.
+Dates are UTC; USD amounts use integer cents.
+
+Use the returned billing values, never a calculation from `usage` monitoring,
+app status or remembered prices. Preserve null as unavailable, not zero, free
+or unlimited. Failed reads return an error, never usable zero totals. Without
+a current subscription, plan, period, quantities and cost can be unavailable.
+
+Always label usage approximate and cost as a pre-tax estimate covering the
+period's base charge plus recorded overage. It is not a final invoice or forecast.
+`reportedAt` is report time and `usageThrough` is the usage query cutoff; neither
+guarantees complete ingestion. Data can be delayed or incomplete. Do not modify
+the subscription or start a checkout as part of this read. If the installed CLI
+does not support billing, report that limitation and use the customer's established
+billing/support channel rather than inventing an endpoint.
+
+## Service liveness
+
+```console
+requestshield service status [--json]
+```
+
+Checks Management API and Challenge Service directly without login, an App Key,
+session access or file writes. `service` alone shows group help.
+
+Each check has a five-second deadline and validates the service identity in the
+response. Both results are retained when either check fails. JSON is one
+`{data:{checkedAt,checks}}` document. Each check contains `service`, `url`,
+`status` (`ok` or `failed`), `latencyMs`, nullable `httpStatus`, and nullable
+`reason` (`timeout`, `network_error`, `http_error`, or `invalid_response`). Exit 0
+means both passed; exit 1 means at least one failed and still includes the report.
+`SERVICE_CONFIG_INVALID` exits 2 before network access.
+
+Report this as HTTP liveness at the caller's location and time. It does not test
+authentication or customer enforcement, and it is not a
+global outage or maintenance report. A failed check can reflect connectivity or
+temporary service unavailability. Never substitute it for an integration negative test.
+
+## Recent usage
+
+```console
+requestshield usage <app-key> [--from <UTC-time> --to <UTC-time>] [--json]
+```
+
+Before retrieving usage / request volume, complete the
+[sign-in steps](integration-planning.md#sign-in).
+Uses the saved authenticated session and existing application-read permission.
+Requires an exact owned App Key, including disabled or revoked apps. Default:
+last 24 hours. Both optional UTC bounds must end in Z (seconds, optionally one to
+three fractional digits), with from before to, and fall within the last seven days
+according to the server's clock. No future end, buckets, 30-day history or account-wide
+view. `usage challenges` and `--granularity` are not supported.
+
+The single JSON document is `{data: {appKey, from, to, approximate: true, operations}}`.
+Operations has three fixed keys: `challenge_create`, `challenge_verify` and
+`token_consume`. Each contains nonnegative `requests`, `success`, `rejected` and
+`error` counts; requests is the sum of the outcomes. Success means a challenge was
+created, verification issued a token, or a token was consumed for the first time.
+Replay is rejected. Retries count separately; verifies are not unique challenges.
+Requests without an identified app are excluded.
+
+These are approximate monitoring counts. Data may be delayed or incomplete. Zero means no recorded events,
+not proof of no traffic. Query failures return errors, never zeros. Do not infer
+billing, service health or backend enforcement from usage. Report unavailable-query
+errors without fabricating counts.
+
+Usage reports cover API v2 requests only. API v1 activity is not included.
+If the browser and backend use different API versions, the report may show
+only part of the application's activity; zero counts do not prove no traffic.