@burnt-labs/expo-satya-attest 0.1.1 → 0.2.0

package/PROVIDER_CONFIG.md

@@ -0,0 +1,520 @@
+# Provider Config
+
+Provider configs are trusted policy for the Expo native replay flow. A config decides
+which provider URL can be replayed, which WebView request counts as a match, which
+request headers may be copied into native replay, which response fields can be
+revealed, and which template/parser identities the verifier accepts.
+
+The built-in registry lives at [`src/providers.json`](./src/providers.json). It is a
+vendored copy of the centralized provider registry maintained in the
+[`burnt-labs/provider-bank`](https://github.com/burnt-labs/provider-bank) repo at
+`provider-bank/providers.json` — edit providers there and sync the copy here
+byte-identically (then run `npm run test:providers`). Custom registries use the same
+provider shape inside a registry wrapper:
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "providers": []
+}
+```
+
+The registry-level `schemaVersion` is optional in the SDK loader. Each provider entry
+must still carry its own `schemaVersion`.
+
+## Minimal Provider
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "providerId": "acme.current_user.v1",
+  "name": "Acme",
+  "iconUrl": "https://acme.example/icon.png",
+  "login": {
+    "url": "https://acme.example/login"
+  },
+  "endpoints": [
+    {
+      "id": "primary",
+      "url": "https://acme.example/api/current-user",
+      "method": "GET",
+      "headers": ["accept", "cookie", "user-agent"],
+      "responseType": "json",
+      "requestMatchRules": [
+        { "type": "methodEquals", "pattern": "GET" },
+        { "type": "urlContains", "pattern": "/api/current-user" }
+      ],
+      "revealRules": [
+        { "action": "REVEAL", "direction": "SENT", "part": "METHOD" },
+        { "action": "REVEAL", "direction": "SENT", "part": "REQUEST_TARGET" },
+        {
+          "action": "REVEAL",
+          "direction": "RECV",
+          "part": "BODY",
+          "params": {
+            "type": "json",
+            "path": "$.accountHolder.name",
+            "alias": "accountHolderName"
+          }
+        }
+      ]
+    }
+  ],
+  "tlsIdentityPolicy": {
+    "expectedSni": "acme.example",
+    "spkiSha256B64Pins": ["AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="]
+  },
+  "templateGovernance": {
+    "templateHash": "dev-acme-current-user-v1-template",
+    "parserHash": "parser-sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  }
+}
+```
+
+Replace the example pin and parser hash with real values. `npm run test:providers`
+computes the expected parser hash and fails if the value is stale.
+
+## Top-Level Fields
+
+Required provider fields:
+
+| Field | Description |
+|---|---|
+| `schemaVersion` | Provider schema version string. The built-in registry currently uses `1.0.0`. |
+| `providerId` | Stable provider id, for example `kaggle.current_user.v1`. It must be unique within a registry. |
+| `name` | User-facing provider name. Legacy `label` and `displayName` are accepted, but new configs should use `name`. |
+| `login.url` | HTTPS page opened in the managed WebView for login and request discovery. |
+| `endpoints` | Non-empty array of proof endpoints. If no endpoint id is selected, the SDK uses the first endpoint. |
+| `tlsIdentityPolicy.expectedSni` | Expected HTTPS host/SNI. Every endpoint URL must use this same host. |
+| `tlsIdentityPolicy.spkiSha256B64Pins` | Public SPKI SHA-256 pins for native replay. Built-in providers and device E2E should keep this non-empty. |
+| `templateGovernance.templateHash` | Template identity accepted by the verifier. |
+| `templateGovernance.parserHash` | Parser identity derived from provider id, endpoint ids, response types, and reveal rules. |
+
+Optional provider fields:
+
+| Field | Description |
+|---|---|
+| `iconUrl` | HTTPS image URL for provider selectors. |
+| `description` | Optional selector/help text. |
+| `label`, `displayName` | Legacy display fields. The loader normalizes them to `name`/`label`/`displayName`. |
+| `version` | Optional version string. If omitted, the SDK infers it from the final `.vN` segment of `providerId`. |
+| `auth` | Optional object for provider-auth metadata. The current SDK preserves it but does not interpret it in the managed flow. |
+| `injection` | Optional JavaScript string, array of strings, or `null`. Runs in the managed WebView on every main and popup page alongside the SDK interceptor. |
+| `target` | Legacy compatibility object. If present, it must be `{ "scheme": "https", "host": expectedSni, "port": 443 }`. The loader generates this when omitted. |
+| `webLogin` | Legacy compatibility object. `login.url` is preferred. If only `webLogin.startUrl` is present, the loader maps it to `login.url`. |
+| `userAgent` | Optional `{ "ios": string | null, "android": string | null }`. Used by the managed WebView when no explicit `webViewUserAgent` prop is supplied. |
+| `tlsIdentityPolicy.allowedAlpn` | Optional ALPN metadata. Native replay measures negotiated ALPN and verifier policy checks the artifact. |
+| `tlsIdentityPolicy.spkiSha256Hex` | Legacy/pass-through metadata. Prefer `spkiSha256B64Pins`. |
+| `tlsIdentityPolicy.tlsTrustStorePolicy` | Optional, but if present it must be `web-pki-os-roots-no-user-roots`. The loader fills this value when omitted. |
+| `tlsIdentityPolicy.userRootsAllowed` | Optional, but if present it must be `false`. The loader fills `false` when omitted. |
+| `tlsIdentityPolicy.redirectPolicyId` | Optional redirect-policy metadata. Native replay currently blocks redirects. |
+| `templateGovernance.fixtureSetHash` | Optional fixture-set identity. Defaults to `unversioned-fixtures`. |
+| `templateGovernance.governancePolicyVersion` | Optional governance policy id. Defaults to `embedded-registry`. |
+| `templateGovernance.providerActivationState` | Optional activation state. Defaults to `experimental`; production policy should require governed active templates. |
+
+Unknown top-level keys are cloned through the JavaScript loader, but native replay and
+backend verification only rely on documented policy fields. Do not place
+security-critical behavior in an unknown key.
+
+## Endpoints
+
+Each provider can define multiple endpoints for the same site:
+
+```json
+{
+  "id": "primary",
+  "url": "https://acme.example/api/current-user",
+  "method": "GET",
+  "headers": ["accept", "cookie", "user-agent"],
+  "responseType": "json",
+  "requestMatchRules": [],
+  "revealRules": []
+}
+```
+
+Required endpoint fields:
+
+| Field | Description |
+|---|---|
+| `id` | Endpoint id. It must start with a letter and contain only letters, numbers, `_`, or `-`. |
+| `url` | HTTPS replay URL. The host must match `tlsIdentityPolicy.expectedSni`. |
+| `method` | HTTP method. Supported values are `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, and `OPTIONS`. |
+| `headers` | Non-empty request-header allowlist used by native replay. This is the collapsed replacement for `privacyPolicy.allowedRequestHeaders`. |
+| `responseType` | Response parser type. One of `json`, `html`, or `text`. `html`/`text` endpoints disclose values via `regex` reveals (see below). |
+| `requestMatchRules` | Non-empty array of rules used to detect the WebView request before native replay. |
+| `revealRules` | Non-empty array of disclosure rules. It must include at least one `RECV BODY` reveal (`json`, `regex`, or `jsonRegex`). |
+
+The raw endpoint schema intentionally does not include `allowedResponseBodyJsonPaths`.
+The loader derives the response reveal allowlist from `revealRules` and emits a
+structured `privacyPolicy.allowedResponseReveals` array (consumed by native replay) plus
+the legacy `allowedResponseBodyJsonPaths` (the JSON-path subset).
+
+### Response types & HTML/text capture
+
+- `json` — the response body is parsed as JSON; reveals may use `json`, `jsonRegex`, or `regex`.
+- `html` / `text` — the body is treated as raw text; reveals must use `regex` only (a
+  JSON path cannot be applied to a non-JSON body).
+
+The WebView request interceptor only sees `fetch`/`XHR` traffic, so a `json` endpoint is
+normally captured when the logged-in page makes its own API call. For `html`/`text`
+endpoints the proof page is a top-level navigation, which is not a `fetch`/`XHR`. When the
+managed WebView lands on a URL that matches an `html`/`text` provider's
+`requestMatchRules`, the SDK re-issues that URL as a same-origin credentialed `fetch()` so
+the normal capture → native-replay path runs. A provider `injection` can drive the WebView
+to the proof page after login (the bundled HTML providers do this).
+
+When `requireProviderTemplate(providerId, registry, endpointId)` is called with an
+endpoint id, that endpoint is normalized into the compatibility `proofTarget` used by
+the native modules. If no endpoint id is supplied, the first endpoint is selected.
+
+### Active-fetch trigger (`triggerFromInjection`)
+
+Some endpoints are cookie-authenticated APIs that **no page ever calls on its own** (e.g.
+`reddit.com/api/me.json`, `spotify.com/api/account-settings/v1/profile`,
+`users.roblox.com/v1/users/authenticated`). There is nothing for the interceptor to
+capture. Set `triggerFromInjection: true` and the SDK actively fires the request itself
+from inside the WebView (with cookies) once the user is logged in:
+
+```json
+{
+  "id": "primary",
+  "url": "https://www.reddit.com/api/me.json?raw_json=1",
+  "method": "GET",
+  "headers": ["accept", "user-agent", "cookie"],
+  "responseType": "json",
+  "triggerFromInjection": true,
+  "requestMatchRules": [
+    { "type": "methodEquals", "pattern": "GET" },
+    { "type": "urlContains", "pattern": "/api/me.json" }
+  ],
+  "revealRules": [ /* … */ ]
+}
+```
+
+How it works:
+
+- The SDK injects a small poller that calls `fetch(url, { method, headers, body, credentials: 'include' })`
+  every ~2s, **skipping login/auth pages**, until it succeeds.
+- **Login gating is automatic via the response status:** the native replay only runs once
+  the injected request comes back **2xx**. Pre-login `401`s / redirects are ignored, so it
+  never captures before sign-in. (Regular, page-triggered endpoints are unaffected — they
+  still capture on the request.)
+- Self-terminating: stops on the first 2xx, after `injectionMaxAttempts` real fetches, or a
+  hard poll cap.
+
+Optional fields that pair with it:
+
+| Field | Description |
+|---|---|
+| `triggerFromInjection` | `true` to enable the active fetch for this endpoint. |
+| `injectionHeaders` | `{ name: value }` extra headers for the fetch. Values may be literals or `{{cookie:NAME}}` templates resolved from `document.cookie` at fire time (for non-httpOnly CSRF / app-id headers). Their names are auto-added to the request-header allowlist for native replay. |
+| `requestBody` | Request body for POST/PUT/PATCH (e.g. a GraphQL query). |
+| `injectionLandingUrl` | HTTPS page to navigate to if the fetch is stuck on a **sibling subdomain** of the proof host (so it becomes same-origin). Defaults to the proof origin root; set a stable signed-in page when the root redirects elsewhere. E.g. after login Spotify lands on `open.spotify.com`, so its endpoint sets `"https://www.spotify.com/account/"`. The poller tries the fetch from wherever it is first (so credentialed cross-origin CORS APIs like Roblox's still need no landing), and only hops after a couple of failures on a same-registrable-domain host — never across registrable domains (won't break a third-party SSO). |
+| `injectionPollMs` | Poll interval in ms (default `2000`, range `500`–`15000`). |
+| `injectionMaxAttempts` | Max real fetch attempts (default `60`, range `1`–`300`). |
+
+Examples needing headers / a body:
+
+```jsonc
+// Instagram — constant app-id + a CSRF token read from a cookie:
+"triggerFromInjection": true,
+"injectionHeaders": {
+  "x-ig-app-id": "936619743392459",
+  "x-csrftoken": "{{cookie:csrftoken}}",
+  "x-requested-with": "XMLHttpRequest"
+}
+
+// DoorDash — POST GraphQL with a body:
+"triggerFromInjection": true,
+"injectionHeaders": { "content-type": "application/json" },
+"requestBody": "{\"operationName\":\"consumer\",\"variables\":{},\"query\":\"query consumer { consumer { id isGuest } }\"}"
+```
+
+Notes:
+
+- Use it for APIs the page doesn't call. For endpoints a page already triggers (the proof
+  fires naturally), leave it off — both work, but the flag is redundant there.
+- Cross-origin APIs (e.g. `api.skillshare.com` from `www.skillshare.com`) work only if the
+  API allows credentialed CORS from the page's origin (the provider's own web app must use
+  the same call). Same-origin APIs always work.
+- `httpOnly` cookies can't be read by `{{cookie:NAME}}` (they're sent automatically by
+  `credentials:'include'` anyway; only header tokens like CSRF need templating).
+- `triggerFromInjection`, `injectionHeaders`, `requestBody`, and the poll tuning are **not**
+  part of the parser hash.
+
+### Dynamic URLs (`replayCapturedUrl`)
+
+Some endpoints have a **dynamic path segment** — e.g. Garmin's
+`/userprofile-service/socialProfile/{userId}`, where the user id varies per account. A fixed
+template `url` can't represent that, and native replay normally uses the template `url`.
+
+Set `"replayCapturedUrl": true` on the endpoint and native replay uses the URL the WebView
+**actually fetched** (the one matched by `requestMatchRules`) instead of the template `url`.
+The captured URL is still constrained to the pinned host (`expectedSni`) and the endpoint's
+match rules, so it can't be redirected to an arbitrary origin. Configure it like:
+
+```json
+{
+  "url": "https://connect.garmin.com/gc-api/userprofile-service/socialProfile",
+  "method": "GET",
+  "replayCapturedUrl": true,
+  "requestMatchRules": [
+    { "type": "methodEquals", "pattern": "GET" },
+    { "type": "urlContains", "pattern": "/userprofile-service/socialProfile" }
+  ]
+}
+```
+
+Here the template `url` is just the stable prefix (used for host/SNI validation and the
+`urlContains` rule); the per-user `…/socialProfile/{userId}` request the page fires is what
+gets captured and replayed. `replayCapturedUrl` is not part of the parser hash.
+
+## Request Match Rules
+
+Request match rules decide which WebView request should trigger native replay. Every
+endpoint must include a method rule and a URL rule:
+
+```json
+[
+  { "type": "methodEquals", "pattern": "POST" },
+  { "type": "urlContains", "pattern": "/api/current-user" }
+]
+```
+
+Supported rule types:
+
+| Rule | Fields | Notes |
+|---|---|---|
+| `methodEquals` | `pattern` | Required. Must match endpoint `method`. |
+| `urlContains` | `pattern` | Required by the current validator. Pattern must be at least four characters and must match the endpoint path or query. |
+| `urlRegex` | `pattern` | Optional. The regex must compile and match either the full endpoint URL or its path/query. Use only when a simple path substring is not enough. |
+| `headerEquals` | `key`, `pattern` | Optional. Supported by the matcher, but avoid it for discovery unless required because WebView-captured auth headers can be inconsistent. `pattern: "*"` means present and non-empty. |
+| `bodyJsonPathEquals` | `path`, `pattern` | Optional. Useful for GraphQL or shared API paths; for example matching `$.operationName`. |
+
+Bundled providers intentionally keep matching reachable: most use `methodEquals` plus
+`urlContains`; Uber additionally uses `bodyJsonPathEquals` to distinguish the GraphQL
+operation.
+
+## Reveal Rules
+
+Reveal rules describe what the artifact may disclose. A `RECV BODY` reveal has a
+`params.type` of `json`, `regex`, or `jsonRegex`.
+
+**`json`** — read the value at a JSON path from a JSON body:
+
+```json
+{
+  "action": "REVEAL",
+  "direction": "RECV",
+  "part": "BODY",
+  "params": { "type": "json", "path": "$.accountHolder.name", "alias": "accountHolderName" }
+}
+```
+
+**`regex`** — match a regex against the raw response body (HTML, text, or JSON) and
+disclose a capture group. Requires an explicit `alias`:
+
+```json
+{
+  "action": "REVEAL",
+  "direction": "RECV",
+  "part": "BODY",
+  "params": { "type": "regex", "pattern": "\"memberSince\":\"([^\"]+)\"", "group": 1, "alias": "member_since" }
+}
+```
+
+**`jsonRegex`** — read a string value at a JSON path, then match a regex against it.
+Useful for pulling a substring out of one JSON field. Requires an explicit `alias`:
+
+```json
+{
+  "action": "REVEAL",
+  "direction": "RECV",
+  "part": "BODY",
+  "params": { "type": "jsonRegex", "path": "$.profile.bio", "pattern": "id:(\\w+)", "alias": "bio_id" }
+}
+```
+
+Supported disclosure fields:
+
+| Field | Description |
+|---|---|
+| `action` | Use `REVEAL` for disclosed values. |
+| `direction` | `SENT` for request metadata or `RECV` for response data. |
+| `part` | Common values are `METHOD`, `REQUEST_TARGET`, and `BODY`. |
+| `params.type` | `json`, `regex`, or `jsonRegex`. |
+| `params.path` | JSON path for `json`/`jsonRegex` reveals, e.g. `$.userProfile.userName` or `$.transactions[0].id`. |
+| `params.pattern` | Regex for `regex`/`jsonRegex` reveals. Must compile and be ≤ 2048 chars. |
+| `params.group` | Optional capture group for `regex`/`jsonRegex`: an integer index in `[0, 99]` (default `1`, falling back to the full match when the pattern has no groups) or a named group string `(?<name>...)`. |
+| `params.alias` | Claim name. Optional for `json` (defaults to the final JSON-path key); **required** for `regex` and `jsonRegex`. |
+
+Alias rules:
+
+- aliases must start with a letter,
+- aliases can contain letters, numbers, `_`, or `-`,
+- aliases are limited to 80 characters,
+- duplicate aliases are rejected case-insensitively across all reveal types.
+
+Native replay (Android/iOS) applies these reveals to the pinned response and emits each
+match as a disclosed claim. The raw response body is size-bounded (8 MiB) before regex
+runs. Regex patterns come from the trusted provider registry, never from page content.
+
+## Writing Regex Patterns For HTML / Text Bodies
+
+`regex` reveals run against the **raw response body** (the exact bytes the pinned replay
+received — HTML, text, or JSON). Use this recipe to keep patterns short and readable.
+
+### The recipe: anchor, lazy capture, anchor
+
+```text
+<text just before the value>(.*?)<text just before the value ends>
+```
+
+- Put a short, unique literal **before** the value and a literal **after** it.
+- Capture the value with a **lazy** group `(.*?)`. Lazy (`*?`) stops at the first
+  following anchor; greedy `(.*)` would run to the *last* match on the line and grab too
+  much.
+- The captured **group 1** is the disclosed value. Set `params.group` only to use a
+  different index or a named group.
+
+Examples (the regex is shown first, then how it appears JSON-escaped in `providers.json`):
+
+| Goal | Regex | In JSON (`"pattern"`) |
+|---|---|---|
+| HTML meta tag | `octolytics-actor-login" content="(.*?)"` | `"octolytics-actor-login\" content=\"(.*?)\""` |
+| JSON string field | `"memberSince":"(.*?)"` | `"\"memberSince\":\"(.*?)\""` |
+| JSON boolean | `"isPrimeCustomer":(true\|false)` | `"\"isPrimeCustomer\":(true\|false)"` |
+| JSON number | `"site_count":([0-9]+)` | `"\"site_count\":([0-9]+)"` |
+| Single-quoted JS var | `firstName:.*?'(.*?)'` | `"firstName:.*?'(.*?)'"` |
+| Email value | `"email":"(.*?@.*?)"` | `"\"email\":\"(.*?@.*?)\""` |
+
+### JSON escaping (the only escaping you usually need)
+
+`providers.json` is JSON, so inside a `"pattern"` string:
+
+- a double quote `"` becomes `\"`,
+- a backslash `\` becomes `\\` (so the regex `\d` is written `\\d` — prefer `[0-9]` to
+  avoid this),
+- everything else is literal.
+
+Two tricks to avoid escaping:
+
+- Match a **single-quoted** value (`'(.*?)'`) — single quotes need no JSON escaping (see
+  Zoom). 
+- Bridge punctuation with `.*?` instead of matching it exactly: `userType:.*?'(.*?)'`
+  skips the colon/space without you having to write `\s*` or `:`.
+
+### Rules and gotchas
+
+- **Use `(.*?)`, not `(.*)`.** Greedy captures overshoot.
+- **`.` does not match newlines.** Values are almost always on one line, so `(.*?)` is
+  fine. If a value spans lines, use `([\s\S]*?)` instead of `(.*)`.
+- **Pick a unique anchor.** `content="(.*?)"` alone matches the first `content="..."` on
+  the page; prefix it with something specific (`octolytics-actor-login" content=`).
+- **`html`/`text` endpoints accept `regex` reveals only.** `json` endpoints accept `json`,
+  `regex`, and `jsonRegex`.
+- Patterns must compile and be ≤ 2048 characters. `params.alias` is **required** for
+  `regex`/`jsonRegex`.
+
+### Advanced: escaped JSON embedded in HTML
+
+Some SSR pages embed JSON with the quotes already backslash-escaped (e.g. Facebook's
+`/settings` ships `\"USER_ID\":\"123\"`). Two robust options:
+
+- **Bridge with `.*?` and capture by shape** — skip the punctuation entirely:
+  `USER_ID.*?([0-9]{5,})` grabs the numeric id whether or not the quotes are escaped.
+- **Match the optional backslash** with `\\?"` (regex `\\?` = an optional literal
+  backslash; JSON-escaped as `\\\\?\"`). This is why Facebook's bundled patterns look
+  busier than the others.
+
+### Testing a pattern
+
+Test against a saved copy of the real (logged-in) page body before adding it — the body
+the replay sees is the raw bytes, so test against *view-source*, not the rendered DOM:
+
+```js
+// node or browser console
+const body = `...paste the raw response body...`;
+const m = body.match(/octolytics-actor-login" content="(.*?)"/);
+console.log(m && m[1]); // the value that will be disclosed
+```
+
+`npm test` validates that every pattern compiles and recomputes the parser hash.
+
+## Parser Hash
+
+`templateGovernance.parserHash` is not an arbitrary hardcoded id. The provider test
+script derives it from a canonical parser policy:
+
+```json
+{
+  "schema": "satya-provider-parser-policy-v1",
+  "providerId": "<provider id>",
+  "endpoints": [
+    {
+      "id": "<endpoint id>",
+      "responseType": "<response type>",
+      "revealRules": []
+    }
+  ]
+}
+```
+
+The canonical JSON is SHA-256 hashed and stored as:
+
+```text
+parser-sha256:<64 lowercase hex characters>
+```
+
+Any change to `providerId`, endpoint ids, endpoint order, `responseType`, or
+`revealRules` changes the parser hash. Run this after editing providers:
+
+```bash
+cd platform_sdks/expo-satya-attest
+npm run test:providers
+```
+
+The client checks verifier policy against the selected template hash and parser hash
+before using verifier-supplied pins. The backend verifier also pins provider id,
+template hash, parser hash, activation state, and SPKI policy before accepting an
+artifact.
+
+## Validation Checklist
+
+The SDK and provider test script enforce the important invariants:
+
+- registry `providers` must be a non-empty array,
+- provider ids must be unique,
+- endpoint arrays cannot be empty and are capped at 20 endpoints per provider,
+- endpoint ids must be unique per provider,
+- login and endpoint URLs must be HTTPS and cannot contain credentials,
+- endpoint URL host must match `tlsIdentityPolicy.expectedSni`,
+- endpoint `headers`, `requestMatchRules`, and `revealRules` cannot be empty,
+- `responseType` must be one of `json`, `html`, or `text`,
+- request matching must bind both method and URL,
+- reveal rules must include at least one `RECV BODY` reveal (`json`, `regex`, or `jsonRegex`),
+- `regex`/`jsonRegex` reveals require a valid (compilable, ≤ 2048 char) `pattern` and an
+  explicit `alias`; `html`/`text` endpoints accept `regex` reveals only,
+- `allowedRequestHeaders`, `allowedResponseBodyJsonPaths`, and raw endpoint
+  `privacyPolicy` are rejected in `src/providers.json`,
+- top-level `injection` must be a non-empty string or non-empty string array when
+  present,
+- `login.injection` is rejected because injection is top-level provider policy,
+- SPKI pins must be SHA-256 base64 values,
+- parser hashes must match the canonical parser policy.
+
+## Provider Authoring Guidance
+
+- Prefer `methodEquals` plus a stable API path in `urlContains`.
+- Add `bodyJsonPathEquals` for shared GraphQL endpoints or overloaded API paths.
+- Avoid `headerEquals` for normal discovery unless there is no reliable URL/body
+  discriminator.
+- Keep `headers` to the minimum request headers needed for native replay. Include
+  `user-agent` when the endpoint is user-agent sensitive (e.g. desktop-only SSR pages) and
+  set the provider `userAgent` so the WebView and the replay agree.
+- Keep reveal rules narrow; every `RECV BODY` reveal becomes a disclosed claim. Prefer
+  `json` for JSON APIs; use `regex` for HTML/text pages or to pull a substring; anchor
+  regex patterns tightly (`"field":"([^"]+)"`) so they match exactly one value.
+- Treat `injection` as trusted code. Do not load registry files from untrusted hosts.
+- Keep backend verifier policy in sync with registry changes before making
+  `providerPolicyRefresh="verifier-required"` the default for a provider.