@burnt-labs/expo-satya-attest 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -1,6 +1,128 @@
 # Changelog
 
-## Unreleased
+## 3.3.0 - 2026-08-14
+
+### Fixed
+
+- **iOS crash on launch for any consumer using `prefetch`.** The hidden WebView
+  that warms the WebKit process was sourced from `{ uri: 'about:blank' }`. A
+  source URL with no host is loaded by react-native-webview through
+  `-[WKWebView loadFileURL:]`, which raises `NSInvalidArgumentException`
+  ("about:blank is not a file URL") and terminates the app. It mounts as soon
+  as the provider resolves, so the crash landed at startup, before any provider
+  flow. It now warms via an `html` source, which takes `loadHTMLString` instead.
+- Three further routes could hand the same hostless URL to a WebView and crash
+  it mid-flow: a managed popup opened for the common
+  `window.open('about:blank')` + `w.location = url` pattern; a popup navigating
+  its opener; and a main-frame navigation fed back into the source prop. All
+  three now require a loadable http(s) document URL. `isWebViewSafeUrl` was not
+  sufficient — it is a navigation-policy check that deliberately permits
+  `about:`. As a backstop, the source prop itself refuses a hostless URL rather
+  than trusting its input. `about:blank` is preserved on Android, where it is
+  the deliberate bootstrap URL and loads without incident.
+
+### Added
+
+- **Pre-emptive login cover (`auth.submitSignal`).** The privacy cover can now
+  appear the moment a login is submitted, instead of waiting for the provider
+  injection's `__satyaReady` signal. That signal can only fire once the
+  authenticated DOM exists — and on Android provider injection is deliberately
+  excluded from the document-start payload — so the destination page was
+  briefly visible after every sign-in. A provider opts in with
+  an ordered `auth.submitSignal[]`. Each entry has a unique stable `id`, a
+  canonical HTTPS `url`, and declares `requestMatchRules` matched against the
+  already-intercepted fetch/XHR traffic (no new injected JavaScript) and/or a
+  `navigationUrlPattern` for form-POST logins that never reach the interceptor.
+  Rules must include a `urlContains` or `urlRegex` so a signal cannot match
+  every request.
+- Providers can declare up to 16 login routes (for example password, OAuth,
+  and magic-link endpoints). Entries are ORed in declaration order; the first
+  matching entry owns the attempt, and only that entry's response rules and
+  timeout apply. Request and response evidence cannot be mixed across entries.
+- Login request matching now also supports `bodyContains` and `bodyRegex` for
+  endpoints whose URL is shared across operations. Optional
+  `responseMatchRules` support `bodyContains` and `bodyRegex` success markers.
+  Response matching scans a bounded clone inside the WebView and sends only a
+  one private boolean over the React Native bridge; response contents remain local.
+- Login-submit validation caps every trimmed matcher string—including header
+  keys and JSON paths—at 2048 characters and each rule list at 16 entries,
+  plus 32 regexes / 8192 regex characters across the provider. All regex
+  matchers must compile; backreferences and expressions with unsafe
+  backtracking are rejected by bounded static analysis before they can run
+  on-device. Body regexes should be anchored, with `bodyContains` used for
+  substring checks.
+- Authenticates interceptor request/response messages with a native-generated,
+  per-flow capability so provider subframes cannot forge login-cover signals.
+- Normalizes fetch and URL-encoded request bodies for login matching; bounded
+  XHR matching fails closed when a faithful body representation is unavailable.
+- The pre-emptive cover is **provisional**, because logins fail routinely. It
+  reverts on its own rather than trapping the user behind a spinner: a non-2xx
+  response to the matched login request uncovers immediately, so a wrong
+  password, MFA prompt, or captcha stays visible; a 2xx extends the wait to
+  `max(timeoutMs, 8s)`
+  for `__satyaReady`; an unanswered submission lapses after 4s
+  (the selected `auth.submitSignal[].timeoutMs`, 1000–15000). Reverting is not sticky, so a
+  retry covers again. `__satyaReady` promotes the provisional cover to the
+  confirmed one, which keeps its existing 12s stalled watchdog.
+- A main-frame navigation while the provisional cover is up promotes it to the
+  same `max(timeoutMs, 8s)` window an accepted 2xx grants, bounded at 3 extensions. This keeps
+  supported main-frame redirect chains covered independently of response-body
+  semantics. A rejection that re-renders in place still lapses on `timeoutMs`;
+  a provider that navigates on rejection may consume a bounded extension.
+  A late accepted response followed by all three extensions can keep the cover
+  up for 36s at the defaults, or 75s at `timeoutMs: 15000`. Exhausting the
+  windows uncovers and continues; it never fails the run, because a slow
+  provider must not lose a capture that is still progressing.
+- `auth.submitSignal.ignoreResponseStatus` covers login endpoints whose status
+  is not a reliable success signal. Without `responseMatchRules`, the response
+  remains uncorrelated and the cover lapses on `timeoutMs`. With response rules,
+  the in-WebView body result decides acceptance while the status is ignored.
+  When the flag is absent/false, both a 2xx status and all configured response
+  rules must match.
+- While provisional, the cover reads "Signing you in..." rather than
+  "Verifying your account..." — nothing has been verified at that point — and
+  offers no actions, since only the confirmed cover can stall.
+
+### Notes
+
+- The cover remains **presentation-only**. The pre-emptive signal never marks
+  the session logged in, releases `capture.requireLoginSignal`, authorizes a
+  capture, or affects replay, disclosure, or verifier policy; a matched login
+  request still passes through every normal capture rule. Only `__satyaReady`
+  gates capture.
+- `auth` remains copied verbatim into the hashed security policy, so
+  `auth.submitSignal` is covered without adding a new policy projection.
+  The Rust verifier's canonical object-key ordering now follows JavaScript's
+  UTF-16 ordering, and SDK/Devtool validation rejects unpaired surrogate
+  strings, preventing cross-language hash drift in additive `auth` metadata.
+  Exact TypeScript/Rust golden vectors cover ordered signal arrays. Providers
+  that do not adopt the field keep an **unchanged policy hash**.
+- `auth` was previously documented as preserved-but-uninterpreted metadata and
+  was not validated at all. Sibling keys are still preserved untouched, but a
+  non-object `auth` is now rejected instead of passing through silently — it
+  now carries configuration the SDK acts on, and a malformed value would
+  otherwise disable the cover with nothing to explain why.
+- Popup close is not treated as authentication. This release does not observe
+  provisional submit matchers inside native Android popup WebViews, and managed
+  popup form navigations do not feed `navigationUrlPattern` into the detector.
+  Providers can match an observed session/status request issued by the opener
+  after popup close; otherwise concealment waits for the opener's
+  `__satyaReady`, preserving the previous popup timing.
+
+## 3.2.0 - 2026-08-07
+
+### Added
+
+- An opt-in, SDK-only TeeLS hosted passthrough selected with
+  `initSatyaAttest({ providerId, appId, teelsFlow: true })`. The flow preserves
+  normal provider grants, performs one existing provider-policy access preflight,
+  opens the registry login URL in an origin-bound WebView bridge, and returns the
+  opaque JSON result through `onTeelsComplete` without native replay, SATYA
+  artifact construction, local verification, or verifier artifact submission.
+- TeeLS-specific progress phases and errors for null/invalid results, hosted
+  failures, timeout, and WebView failure. The feature is disabled by default;
+  omitting `teelsFlow` in a later init restores native routing for subsequently
+  mounted buttons.
 
 ## 3.1.0 - 2026-07-31
 
@@ -140,7 +262,7 @@ default-deny provider allowlist.
   id was swallowed by the policy-refresh `try` and resurfaced after the user
   had already completed login, mislabeled as a native-module failure.
 - **Empty overrides no longer erase configuration.** `initSatyaAttest({ appId:
-  '' })` (a common `props.appId ?? ''` pattern) wiped a valid env-derived app
+'' })` (a common `props.appId ?? ''` pattern) wiped a valid env-derived app
   id, and an empty `providerRegistryApi` silently repointed a staging build at
   production.
 

package/PROVIDER_CONFIG.md

@@ -25,6 +25,7 @@ inside a provider:
 Registry                         { schemaVersion?, providers[] }
 └─ Provider                      top-level proof config
    ├─ login                      { url }              → page opened in the WebView
+   ├─ auth?                      { submitSignal? }    → pre-emptive login cover (optional)
    ├─ endpoints[]                one replayable request each
    │  ├─ requestMatchRules[]     which WebView request to capture
    │  ├─ revealRules[]           what the artifact may disclose
@@ -102,7 +103,7 @@ field table (`Req?` = required `yes` / optional `no`).
 | `requiresLocation` | `boolean` | Enables geolocation only for this provider's managed WebView. Defaults to `false`; the host app must opt in with the config plugin's `enableWebViewGeolocation` option. Android runtime access is requested after the provider resolves and before its WebView loads. |
 | `userAgent` | `{ ios, android }` | Per-platform UA (each `string` or `null`) for the WebView when no `webViewUserAgent` prop is set. Use when the provider serves different pages to mobile vs desktop and replay must match. |
 | `injection` | `string` / `string[]` / `null` | Trusted WebView JavaScript run on every page. See §9. |
-| `auth` | `object` | Provider-auth metadata. Preserved but not interpreted by the managed flow. |
+| `auth` | `object` | Authentication metadata. Only `submitSignal` (§2.1) is interpreted; every sibling key is preserved untouched. Must be an object when present. |
 
 Unknown top-level keys are cloned through but ignored by native replay/verification —
 never put security-critical behavior in an undocumented key.
@@ -125,6 +126,123 @@ The page opened in the managed WebView. Use the provider's normal sign-in / acco
 > `login.injection` is **invalid** — provider JavaScript always lives at the top-level
 > `injection` (§9).
 
+### 2.1 `auth.submitSignal` (optional) — covering before the landing page paints
+
+`__satyaReady` (§9) can only fire once the authenticated DOM exists, so the provider's
+destination page is briefly visible after sign-in. `submitSignal` moves the cover earlier:
+the SDK covers the WebView as soon as it sees the login being submitted.
+
+```json
+"login": { "url": "https://acme.example/login" },
+"auth": {
+  "submitSignal": [
+    {
+      "id": "PasswordLogin",
+      "url": "https://acme.example/api/v1/auth/login",
+      "requestMatchRules": [
+        { "type": "methodEquals", "pattern": "POST" },
+        { "type": "urlContains", "pattern": "/api/v1/auth/login" },
+        { "type": "bodyContains", "pattern": "\"grantType\":\"password\"" }
+      ],
+      "responseMatchRules": [
+        { "type": "bodyContains", "pattern": "\"authenticated\":true" },
+        { "type": "bodyRegex", "pattern": "^\\{\"authenticated\":true,\"sessionId\":\"[^\"]+\"\\}$" }
+      ],
+      "ignoreResponseStatus": true,
+      "timeoutMs": 4000
+    }
+  ]
+}
+```
+
+| Field | Req? | Type | Description |
+|---|---|---|---|
+| `id` | yes | `string` | Unique stable signal identifier. Starts with a letter, then letters/numbers/`_`/`-`; maximum 64 characters. |
+| `url` | yes | `string` | Canonical HTTPS login endpoint, without credentials or surrounding whitespace; maximum 2048 characters. Every request URL rule must match it, and navigation matching is restricted to this origin. |
+| `requestMatchRules` | no\* | `array` | ANDed rules matched against intercepted `fetch`/`XHR` traffic. Supports `methodEquals`, `urlContains`, `urlRegex`, `headerEquals`, `bodyJsonPathEquals`, `bodyContains`, and `bodyRegex`. Must include a `urlContains` (≥4 chars) or `urlRegex` rule. |
+| `responseMatchRules` | no | `array` | Optional ANDed success-envelope rules. Supports `bodyContains` and `bodyRegex`. Requires `requestMatchRules` so the response can be correlated to a URL-bound login request. Matching reads at most the first 65,536 response characters inside the WebView; only a private boolean crosses the React Native bridge. |
+| `navigationUrlPattern` | no\* | `string` | Regex matched against same-origin main-frame navigations. For classic `<form>` POST logins, which never reach the request interceptor. |
+| `timeoutMs` | no | `integer` | 1000–15000, default 4000. How long an unanswered submission stays covered. |
+| `ignoreResponseStatus` | no | `boolean` | Without `responseMatchRules`, `true` skips response correlation and the cover lapses on `timeoutMs`. With `responseMatchRules`, status is ignored but the response-body boolean still decides acceptance. When false/absent, acceptance requires both 2xx and all configured response rules. |
+
+`submitSignal` is a non-empty array with at most 16 entries. A provider can list one entry
+per login route (password, OAuth callback, magic link, and so on). Entries are ORed in
+declaration order and the first matching entry owns the attempt; rules within that entry
+are ANDed. The selected entry alone supplies response rules and `timeoutMs`, so request and
+response evidence is never mixed across login routes. IDs must be unique.
+
+\* At least one of `requestMatchRules` / `navigationUrlPattern` is required for each entry.
+Sibling `auth` keys are preserved and never interpreted, so a provider may keep its own
+metadata alongside it. A non-object `auth`, an object-form `submitSignal`, and unknown keys
+inside a signal are rejected outright. Every trimmed matcher string—including header keys
+and JSON paths—is capped at 2048 characters, every rule array is capped at 16 entries, and
+the complete provider may contain at most 32 regexes totaling 8192 characters. Every regex
+must compile. To keep matchers safe for on-device request/response processing,
+backreferences and expressions with unsafe backtracking are rejected by bounded static analysis.
+Anchor body regexes to the complete expected body; use `bodyContains` for substring checks.
+Fetch bodies are normalized through the browser `Request` API. XHR supports text,
+`URLSearchParams`, and byte-buffer request bodies; XHR `FormData`/`Blob` request matching and
+`responseType="json"` response matching fail closed because no bounded faithful wire encoding is
+available. Prefer `fetch` or a text XHR response when body rules are required.
+
+**The cover is provisional and reverts on its own** — logins fail routinely, and a wrong
+password must not sit behind a spinner:
+
+| Outcome | Behavior |
+|---|---|
+| Matched request answered non-2xx | Uncovers immediately, so the provider's error, MFA prompt, or captcha is visible |
+| Matched request answered 2xx | Waits for `max(timeoutMs, 8s)` for `__satyaReady` |
+| `responseMatchRules` configured | Accepts only when every body rule matches; also requires 2xx unless `ignoreResponseStatus` is true |
+| No response observed | Lapses after `timeoutMs` |
+| `ignoreResponseStatus: true`, no response rules | Response is not correlated; always lapses after `timeoutMs` |
+| Main-frame navigation while covered | Grants the same `max(timeoutMs, 8s)` accepted window (up to 3 times) for supported redirect chains |
+| `__satyaReady` arrives | Promotes to the confirmed cover, with its usual 12s stalled watchdog |
+
+Reverting is not sticky: a retried login covers again.
+
+> **Check what a failed login actually returns.** Many login APIs answer `200` with an
+> error envelope rather than a 4xx. Add `responseMatchRules` for a stable success marker so
+> a rejected 200 response uncovers immediately. Use `ignoreResponseStatus: true` together
+> with response rules only when the HTTP status is unreliable. The response is cloned and
+> scanned inside the WebView; its contents never cross the bridge, only the match boolean.
+
+`timeoutMs` does not have to cover the provider's slowest sign-in. A main-frame navigation
+while the cover is up promotes it to the same `max(timeoutMs, 8s)` window an accepted 2xx would grant
+(bounded at 3 extensions), which keeps supported redirect chains covered. A rejected login
+that re-renders in place still uncovers after one `timeoutMs`; a provider that navigates on
+rejection may consume a bounded extension. Set `timeoutMs` to how long you are willing to
+hide a **failed** login, not to how long a successful one takes.
+
+If every window still expires without `__satyaReady`, the cover simply lifts and the flow
+continues. A late accepted response followed by all three navigation extensions can keep it
+covered for up to 36s at the defaults, or 75s with `timeoutMs: 15000`. It never fails the run:
+the cover is presentation-only, and a slow provider must not lose a capture that is still
+progressing.
+
+> The remaining latency is the provider injection's own detection speed. Between the last
+> navigation and `__satyaReady`, only `timeoutMs` is holding the cover. An injection that
+> polls slowly (say `setInterval(…, 1500)` and waits for full DOM hydration) can exceed it
+> and let the destination page flash. Prefer an auth-cookie check at ≤1s (§9).
+
+> Prefer `requestMatchRules` — the SDK already intercepts every `fetch`/`XHR`, so no new
+> injected JavaScript is involved. Scope the rules to the login endpoint itself; a signal
+> that also matches ordinary page traffic will cover the user at random moments.
+> `navigationUrlPattern` must match the **post-login** URL, not the login page's own loads.
+
+> **Popup limitation.** Popup close is not an authentication signal. The current SDK does
+> not observe `submitSignal` requests inside native Android popup WebViews, and managed-popup
+> form navigations do not feed `navigationUrlPattern` into the provisional-cover detector.
+> If the opener/main WebView immediately issues an observed session/status `fetch`/`XHR`
+> after close, match that request instead. Otherwise the popup may remain visible until the
+> opener emits `__satyaReady`; do not invent a popup-close heuristic.
+
+`submitSignal` is presentation-only. It never releases `capture.requireLoginSignal`,
+authorizes a capture, or affects replay or verification — a matched login request still
+passes through every normal capture rule. **Still emit `__satyaReady`** (§9): it is what
+gates capture and what promotes the cover. Because `auth` is copied verbatim into the
+hashed security policy, adding `submitSignal` changes the provider's `policyHash`; not
+adding it leaves the hash unchanged.
+
 ---
 
 ## 3. `endpoints[]` — the Endpoint object
@@ -561,9 +679,82 @@ it while a logged-out state is still possible: a premature signal covers the log
 although the stalled cover offers a way back, that is a degraded experience. (This signal is
 unrelated to the registry catalog flag `metadata.isSatyaReady`.)
 
+Because `__satyaReady` cannot fire until the authenticated DOM exists, even a fast detector
+leaves the destination page briefly visible. To close that gap, also declare
+`auth.submitSignal` (§2.1), which covers the WebView the moment the login is submitted and
+reverts on its own if the login turns out to have failed. The two are complementary:
+`submitSignal` decides how early the cover appears, `__satyaReady` still gates capture and
+promotes the provisional cover to the confirmed one.
+
 > This is distinct from endpoint `capture`: `injection` is page JavaScript at the provider
 > level; `capture` is per-endpoint active-fetch/readiness config.
 
+### Hosted TeeLS passthrough provider injection
+
+An SDK session initialized with `teelsFlow: true` may use a normal granted
+provider as a hosted TeeLS passthrough. There is no Registry flow discriminator:
+the SDK binds TeeLS mode to the configured provider/app pair, performs the
+normal provider-policy access preflight, opens `login.url`, and skips request
+capture and native replay.
+
+Keep the provider structurally valid for the normal Registry. Its existing
+endpoint, SNI, pins, grants, and verifier policy remain ordinary provider
+policy even though the TeeLS attempt does not fire or replay that endpoint.
+The hosted page origin may therefore differ from the inert endpoint/SNI host;
+the TeeLS WebView origin is always derived from `login.url`, while the access
+preflight continues to validate the governed provider policy.
+
+Generate the canonical adapter injection from the Expo SDK checkout:
+
+```bash
+cd platform_sdks/expo-satya-attest
+node scripts/generate-hosted-teels-provider-injection.js \
+  --origin https://hosted-teels.example \
+  --json
+```
+
+Put the resulting JSON string in the provider's top-level `injection`. The
+adapter is additive. It reuses, in order:
+
+1. standard `TeeLS.create({ onSuccess, onError })` callbacks by intercepting the
+   initial `window.TeeLS` assignment before the hosted bundle runs;
+2. the `teels:attestation` `CustomEvent`, reading
+   `event.detail.attestation` and optional `event.detail.data`; and
+3. the durable `window.__teels.attestation` snapshot for success recovery when
+   the adapter attaches after completion.
+
+The adapter calls the page's original callbacks first and forwards to SATYA in
+`finally`, preserving callback arguments, `this`, return values, thrown errors,
+the returned TeeLS handle, and every other TeeLS SDK export. The second argument
+to SATYA is always the attestation; if present, the first `onSuccess` argument is
+forwarded as `claimData` and added to the completion payload as `claimData`.
+Null success maps to `attestation_missing`; all other TeeLS errors map to
+`teels_flow_failed`.
+The SDK bridge and adapter both enforce exactly-once terminal settlement.
+
+The terminal API is distinct from native login readiness and supports the optional
+`claimData` passthrough:
+
+```js
+window.__SATYA_TEELS_BRIDGE__.complete(attestation, claimData);
+window.__SATYA_TEELS_BRIDGE__.fail('attestation_missing');
+window.__SATYA_TEELS_BRIDGE__.fail('teels_flow_failed');
+```
+
+Do not emit or overload `__satyaReady` for TeeLS completion. Do not post the
+opaque result through the native-replay interceptor. The adapter must remain
+main-frame and exact-origin scoped and must tolerate being evaluated only once;
+SATYA installs the bridge before executing the Registry injection.
+
+Success can be recovered from the durable snapshot after a late injection, but
+a past error cannot. Before using a hosted provider beyond development, prove
+on physical iOS and Android—both with the external TeeLS bundle cached and
+uncached—that `injectedJavaScriptBeforeContentLoaded` wraps `TeeLS.create`
+before the page calls it. If that ordering cannot be established, add a minimal
+page-owned error seam instead of relying on best-effort console interception.
+Also confirm the hosted TeeLS SDK invokes its configured `onError` for every
+terminal failure; a rendered SDK error alone cannot be observed by the adapter.
+
 ---
 
 ## 10. Writing regex patterns (HTML / text bodies)
@@ -624,6 +815,14 @@ console.log(body.match(/octolytics-actor-login" content="(.*?)"/)?.[1]);
   is an SDK/verifier session option (§8.1),
 - `injection` is a non-empty string / non-empty string array when present; `login.injection`
   and endpoint `injection` are rejected,
+- `auth.submitSignal` (when present) is an array of 1–16 entries with unique `id` values and
+  canonical HTTPS `url` values; each entry has only `id`, `url`, `requestMatchRules`,
+  `responseMatchRules`, `navigationUrlPattern`, `timeoutMs`, `ignoreResponseStatus`; declares at
+  least one request/navigation detector; request rules use supported request types, include a
+  URL-bounding `urlContains`/`urlRegex`, and match the entry's `url`; response rules use only
+  `bodyContains`/`bodyRegex` and require request rules; request and response rule arrays contain
+  at most 16 entries; every trimmed matcher string is ≤2048 characters; patterns compile;
+  `timeoutMs` is an integer in 1000–15000 (§2.1),
 - raw `allowedRequestHeaders`, `allowedResponseBodyJsonPaths`, and `privacyPolicy` are
   rejected (the loader derives them from `revealRules`),
 - SPKI pins are SHA-256 base64,

package/README.md

@@ -26,6 +26,9 @@ with `CONFIG_INVALID`. An unregistered or unapproved id fails at the verifier
 with `APP_NOT_REGISTERED` / `APP_DISABLED`, and an ungranted provider fails with
 `PROVIDER_ACCESS_DENIED`. See
 [`docs/MULTI_TENANT_VERIFICATION.md`](../../docs/MULTI_TENANT_VERIFICATION.md).
+Flows also fail with `app_platform_not_configured` when the app has no
+registered identity for the current platform, so register every platform you
+develop and test on.
 
 ## Current Flow
 
@@ -51,6 +54,113 @@ The earlier mock and plain `webview-observed` modes are no longer exposed throug
 high-level Expo client because they do not prove a provider response fetched through a
 pinned native TLS connection.
 
+## TeeLS Hosted Passthrough (Opt-In)
+
+The SDK also has an isolated, opt-in TeeLS hosted flow. It uses a normal
+registry provider and the normal app/provider grant, but it does **not** run
+request capture, native replay, SATYA artifact construction, local SATYA
+verification, or verifier artifact submission. SATYA performs one provider-policy
+request before opening the WebView solely to confirm that the configured app is
+active and has access to the provider.
+
+Enable the flow for exactly one provider/app pair at initialization:
+
+```tsx
+import {
+  initSatyaAttest,
+  SatyaProviderAttestButton,
+  type SatyaTeelsAttestation,
+  type SatyaTeelsClaimData,
+} from '@burnt-labs/expo-satya-attest';
+
+initSatyaAttest({
+  providerId: 'satya.teels.v1',
+  appId: 'app_your-registered-app-id',
+  teelsFlow: true,
+});
+
+function TeelsAttestButton() {
+  const verifyTeelsResult = async (
+    attestation: SatyaTeelsAttestation,
+    claimData?: SatyaTeelsClaimData
+  ) => {
+    // Required: verify the TeeLS quote, freshness, and expected data binding
+    // in your application or backend before trusting the result.
+    // `claimData` is the first argument to TeeLS success, usually the
+    // JSON-safe payload forwarded by the hosted provider.
+  };
+
+  return (
+    <SatyaProviderAttestButton
+      providerId="satya.teels.v1"
+      transportConfig={{
+        verifierUrl: 'https://satya-verifier-v2-staging.burnt.com',
+        appId: 'app_your-registered-app-id',
+      }}
+      onTeelsComplete={verifyTeelsResult}
+      onError={(error) => console.error(error.code, error.message)}
+    />
+  );
+}
+```
+
+The provider's existing `login.url` opens in the SDK WebView and its normal
+Registry `injection` adapts the hosted page to the SDK-owned bridge. A page that
+already uses the standard TeeLS callbacks and EarnOS success event/snapshot
+does not need frontend changes. See
+[Provider Config](./PROVIDER_CONFIG.md#hosted-teels-passthrough-provider-injection)
+for the adapter and device-validation contract.
+
+Only a non-null, JSON-safe attestation object can complete the flow. If provided,
+`claimData` is additionally forwarded as a second argument to `onTeelsComplete`.
+Success is returned only through `onTeelsComplete`; invalid/null data, hosted
+failures, timeout, WebView failure, and access denial use the normal `onError`
+path. Closing the sheet before a terminal result uses `onCancel`.
+
+Native-replay-only props are not used by TeeLS. A component may keep an
+`onComplete` handler for normal mode, but TeeLS never calls it. Initialize the
+SDK before mounting the button. A later init with `teelsFlow: false` or with
+the option omitted disables TeeLS for subsequently mounted buttons; normal
+providers continue to use the existing native replay flow unchanged.
+
+The returned object is an opaque, unverified TeeLS result and is delivered as
+the first argument. `claimData` is the hosted-provider payload whose inner
+`data` object is hashed into the quote's `report_data`; treat both as
+untrusted input until verified. Do not treat callback delivery as a SATYA
+verification claim, and do not log or persist the result by default.
+
+### Verifying the TeeLS result
+
+The SATYA SDK performs no verification of the TeeLS result — it neither
+verifies the quote nor checks that the claim data matches it. Before trusting
+the result, the consuming application or its backend must verify it:
+
+1. **DCAP quote.** `attestation.quote` is a hex-encoded Intel TDX quote. Post
+   it to the independent TeeLS verifier service and require `success: true`,
+   `quote.verified: true`, and a `tcb_status` your policy accepts:
+
+   ```bash
+   curl -X POST https://attest.burnt.com/verify \
+     -H 'content-type: application/json' \
+     -d '{"hex":"<quote hex>"}'
+   ```
+
+2. **Measurements.** Compare the verified quote's `mrtd` and `rtmr0`–`rtmr3`
+   against the expected-measurements registry published independently by the
+   verifier (`GET https://attest.burnt.com/measurements`); require a match
+   against one of its `valid[]` sets.
+3. **Data binding.** Use `reportdata` from the **verified quote response**
+   (never the advisory `attestation.reportDataHex` field — it is
+   server-supplied). Its first 32 bytes must equal
+   `SHA-256(JSON.stringify(data))` over the exact result-data object the page
+   delivered (in this flow, `claimData.data`; remaining bytes are
+   zero-padded). When the provider binds a policy hash, the envelope is
+   `{ data, policyHash }` instead of bare `data`. Any mismatch means the claim
+   data was substituted after attestation.
+
+The result carries no nonce, so enforce your own freshness and replay policy
+wherever the attestation crosses a trust boundary.
+
 ## Native Trust Tiers
 
 | Platform         | Witness key                           | Platform evidence                | Typical tier                                                                        |
@@ -80,7 +190,7 @@ New SDK artifacts also include envelope metadata:
   "attestationIdVersion": "statement-sha256-96-v1",
   "producer": {
     "sdk": "@burnt-labs/expo-satya-attest",
-    "sdkVersion": "3.1.0",
+    "sdkVersion": "3.3.0",
     "artifactSchemaVersion": "1.1.0",
     "coreVersion": "0.1.0"
   }
@@ -227,7 +337,7 @@ is a release tarball produced by `npm pack`, because it contains the same files
 would publish:
 
 ```bash
-npm install https://github.com/<owner>/<repo>/releases/download/expo-satya-attest-v3.1.0/burnt-labs-expo-satya-attest-3.1.0.tgz
+npm install https://github.com/<owner>/<repo>/releases/download/expo-satya-attest-v3.3.0/burnt-labs-expo-satya-attest-3.3.0.tgz
 npx expo install react-native-webview react-native-safe-area-context
 ```
 
@@ -235,8 +345,8 @@ Installing from a Git ref also works when that ref has the SDK package at the re
 root, such as a dedicated SDK repo or a subtree/split branch:
 
 ```bash
-npm install github:<owner>/<sdk-repo>#v3.1.0
-npm install git+https://github.com/<owner>/<sdk-repo>.git#v3.1.0
+npm install github:<owner>/<sdk-repo>#v3.3.0
+npm install git+https://github.com/<owner>/<sdk-repo>.git#v3.3.0
 npx expo install react-native-webview react-native-safe-area-context
 ```
 
@@ -313,15 +423,34 @@ pill (lock icon + domain), a reload button, and a page-load line that advances w
 loads and clears when it finishes; both the main page and the managed OAuth popup fade in
 over their first load instead of flashing white.
 
-Once the provider's injection confirms the session is authenticated (the `__satyaReady`
-login signal), the sheet conceals the provider page behind a "Verifying your account…"
-cover while capture and native replay continue underneath, so users see only the login
-window and never the SDK driving the authenticated site. The cover is presentation-only
-(capture gating and verification are unchanged); if capture does not start within a
-short watchdog window it offers a "Return to provider" path that keeps the flow alive.
-Providers whose injection does not emit `__satyaReady` keep the previous behavior and
-are covered from request capture onward. See `PROVIDER_CONFIG.md` for the signal
-contract.
+SDK 3.3.0 providers can declare an ordered `auth.submitSignal[]` to start a provisional
+"Signing you in..." cover as soon as a tightly scoped main-WebView login request or
+navigation is observed. Request matching supports URL-, header-, JSON-path-, and raw-body
+rules. Each entry has a unique `id` and canonical HTTPS `url`; entries are ORed in order,
+the first match wins, and that same entry owns response matching and timeout behavior.
+Optional response body rules are evaluated on a bounded clone inside the WebView; only
+a private boolean crosses the React Native bridge. A rejection uncovers, an unanswered
+submission lapses on timeout, and bounded main-frame navigation extensions keep supported
+redirect chains concealed.
+
+Login-cover configuration is capped at 32 regexes totaling 8192 characters per provider,
+in addition to the per-pattern and per-rule-list limits. Body matching supports normalized
+fetch bodies and text XHR; bounded matching fails closed for XHR `responseType="json"` and
+XHR `FormData`/`Blob` request bodies.
+
+Once the provider's injection confirms authentication with `__satyaReady`, the sheet
+promotes to the "Verifying your account…" cover while capture and native replay continue
+underneath. Only `__satyaReady` releases readiness-gated capture; both covers remain
+presentation-only and never change replay or verification policy. If confirmed capture
+does not start within a short watchdog window, the cover offers a "Return to provider"
+path that keeps the flow alive. Providers without `auth.submitSignal` retain the previous
+timing and policy hash.
+
+Popup close is not an authentication signal. This release does not observe provisional
+submit matchers inside native Android popup WebViews or managed-popup form navigations. A
+provider may instead match an observed session/status request that the opener issues after
+popup close; otherwise concealment waits for the opener's `__satyaReady`. See
+`PROVIDER_CONFIG.md` §2.1 for the complete schema and limitations.
 
 Pass `presentation="fullScreen"` to keep the legacy full-window takeover. Set `prefetch`
 to resolve the provider policy and warm the WebView engine at mount so the sheet opens

package/android/build.gradle

@@ -4,13 +4,13 @@ plugins {
 }
 
 group = 'expo.modules.satyaattest'
-version = '3.1.0'
+version = '3.3.0'
 
 android {
   namespace "expo.modules.satyaattest"
   defaultConfig {
     versionCode 1
-    versionName "3.1.0"
+    versionName "3.3.0"
     // StrongBox key attestation needs API 28+; basic Keystore attestation API 24+.
     minSdkVersion 24
   }

package/android/src/main/java/expo/modules/satyaattest/SatyaAttestModule.kt

@@ -107,6 +107,12 @@ class SatyaAttestModule : Module() {
 
     Function("satyaCoreVersion") { satyaCoreVersion() }
 
+    Function("createWebViewBridgeCapability") {
+      val bytes = ByteArray(32)
+      SecureRandom().nextBytes(bytes)
+      Base64.encodeToString(bytes, Base64.URL_SAFE or Base64.NO_WRAP or Base64.NO_PADDING)
+    }
+
     AsyncFunction("initialize") { configJson: String -> transportConfigJson = configJson }
 
     AsyncFunction("dispose") { transportConfigJson = "{}" }

package/build/SatyaAttestModule.d.ts

@@ -2,6 +2,7 @@ import { NativeModule } from 'expo';
 import { VerifyResult } from './types';
 declare class SatyaAttestModule extends NativeModule<Record<string, never>> {
     satyaCoreVersion(): string;
+    createWebViewBridgeCapability(): string;
     attestNativeReplay(providerTemplateJson: string, capturedRequestJson?: string | null): Promise<string>;
     attestNativeReplayBundle(providerTemplateJson: string, capturedRequestsJson: string, partialEndpointSelectionJson?: string | null): Promise<string>;
     verifyArtifact(artifactJson: string): Promise<boolean>;

package/build/SatyaAttestModule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SatyaAttestModule.d.ts","sourceRoot":"","sources":["../src/SatyaAttestModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,MAAM,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,OAAO,iBAAkB,SAAQ,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzE,gBAAgB,IAAI,MAAM;IAE1B,kBAAkB,CAChB,oBAAoB,EAAE,MAAM,EAC5B,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,GAClC,OAAO,CAAC,MAAM,CAAC;IAElB,wBAAwB,CACtB,oBAAoB,EAAE,MAAM,EAC5B,oBAAoB,EAAE,MAAM,EAC5B,4BAA4B,CAAC,EAAE,MAAM,GAAG,IAAI,GAC3C,OAAO,CAAC,MAAM,CAAC;IAElB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IACtD,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAEnE,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAC7C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IACxB,iCAAiC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAC3F,sBAAsB,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,EAChB,kBAAkB,EAAE,OAAO,GAC1B,OAAO,CAAC,OAAO,CAAC;IACnB,qFAAqF;IACrF,wBAAwB,CAAC,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAC/D,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC;CACtC;;AAED,wBAAqE"}
+{"version":3,"file":"SatyaAttestModule.d.ts","sourceRoot":"","sources":["../src/SatyaAttestModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,MAAM,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,OAAO,iBAAkB,SAAQ,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzE,gBAAgB,IAAI,MAAM;IAC1B,6BAA6B,IAAI,MAAM;IAEvC,kBAAkB,CAChB,oBAAoB,EAAE,MAAM,EAC5B,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,GAClC,OAAO,CAAC,MAAM,CAAC;IAElB,wBAAwB,CACtB,oBAAoB,EAAE,MAAM,EAC5B,oBAAoB,EAAE,MAAM,EAC5B,4BAA4B,CAAC,EAAE,MAAM,GAAG,IAAI,GAC3C,OAAO,CAAC,MAAM,CAAC;IAElB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IACtD,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAEnE,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAC7C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IACxB,iCAAiC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAC3F,sBAAsB,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,EAChB,kBAAkB,EAAE,OAAO,GAC1B,OAAO,CAAC,OAAO,CAAC;IACnB,qFAAqF;IACrF,wBAAwB,CAAC,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAC/D,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC;CACtC;;AAED,wBAAqE"}

package/build/SatyaAttestModule.js.map

@@ -1 +1 @@
-{"version":3,"file":"SatyaAttestModule.js","sourceRoot":"","sources":["../src/SatyaAttestModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,mBAAmB,EAAE,MAAM,MAAM,CAAC;AAkCzD,eAAe,mBAAmB,CAAoB,aAAa,CAAC,CAAC","sourcesContent":["import { NativeModule, requireNativeModule } from 'expo';\n\nimport { VerifyResult } from './types';\n\ndeclare class SatyaAttestModule extends NativeModule<Record<string, never>> {\n  satyaCoreVersion(): string;\n\n  attestNativeReplay(\n    providerTemplateJson: string,\n    capturedRequestJson?: string | null\n  ): Promise<string>;\n\n  attestNativeReplayBundle(\n    providerTemplateJson: string,\n    capturedRequestsJson: string,\n    partialEndpointSelectionJson?: string | null\n  ): Promise<string>;\n\n  verifyArtifact(artifactJson: string): Promise<boolean>;\n  verifyArtifactDetailed(artifactJson: string): Promise<VerifyResult>;\n\n  initialize(configJson: string): Promise<void>;\n  dispose(): Promise<void>;\n  installWebViewDocumentStartScript(viewTag: number, script: string): Promise<boolean | null>;\n  setPopupWindowsEnabled(\n    viewTag: number,\n    enabled: boolean,\n    geolocationEnabled: boolean\n  ): Promise<boolean>;\n  /** Optional for compatibility with native binaries predating privacy concealment. */\n  setPopupWindowsConcealed?(concealed: boolean): Promise<boolean>;\n  closePopupWindows(): Promise<boolean>;\n}\n\nexport default requireNativeModule<SatyaAttestModule>('SatyaAttest');\n"]}
+{"version":3,"file":"SatyaAttestModule.js","sourceRoot":"","sources":["../src/SatyaAttestModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,mBAAmB,EAAE,MAAM,MAAM,CAAC;AAmCzD,eAAe,mBAAmB,CAAoB,aAAa,CAAC,CAAC","sourcesContent":["import { NativeModule, requireNativeModule } from 'expo';\n\nimport { VerifyResult } from './types';\n\ndeclare class SatyaAttestModule extends NativeModule<Record<string, never>> {\n  satyaCoreVersion(): string;\n  createWebViewBridgeCapability(): string;\n\n  attestNativeReplay(\n    providerTemplateJson: string,\n    capturedRequestJson?: string | null\n  ): Promise<string>;\n\n  attestNativeReplayBundle(\n    providerTemplateJson: string,\n    capturedRequestsJson: string,\n    partialEndpointSelectionJson?: string | null\n  ): Promise<string>;\n\n  verifyArtifact(artifactJson: string): Promise<boolean>;\n  verifyArtifactDetailed(artifactJson: string): Promise<VerifyResult>;\n\n  initialize(configJson: string): Promise<void>;\n  dispose(): Promise<void>;\n  installWebViewDocumentStartScript(viewTag: number, script: string): Promise<boolean | null>;\n  setPopupWindowsEnabled(\n    viewTag: number,\n    enabled: boolean,\n    geolocationEnabled: boolean\n  ): Promise<boolean>;\n  /** Optional for compatibility with native binaries predating privacy concealment. */\n  setPopupWindowsConcealed?(concealed: boolean): Promise<boolean>;\n  closePopupWindows(): Promise<boolean>;\n}\n\nexport default requireNativeModule<SatyaAttestModule>('SatyaAttest');\n"]}