@burnt-labs/expo-satya-attest 0.3.2 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.0.0 - 2026-06-22
+
+- Breaking: providers now load at runtime from `PROVIDER_REGISTRY_API` / `providerRegistryApi` by configured `providerId`; the SDK no longer ships or reads a bundled provider JSON.
+- Breaking: current SDK artifacts use `policyHash` as the provider policy binding. `templateHash` and `parserHash` are no longer part of the SDK-side provider contract.
+- Removed notary-facing SDK flow. Mobile apps act as the witness and submit app/device attestations to the verifier service.
+- Added typed SDK errors via `SatyaErrorCode`, verifier URL normalization, provider-registry validation, and configurable redacted logging.
+- Added `autoStart` and `renderButton` props so apps can use their own connect buttons or auto-open the managed WebView when app state is ready.
+- Updated the example app to display SDK/debug logs in the UI when logging is enabled.
+
 ## 0.3.2 - 2026-06-16
 
 - Added a visible close button to the managed provider WebView header. It uses the same cancel path as the device back action and iOS edge-swipe gesture, so users can exit login or capture flows without relying only on platform gestures.

package/PROVIDER_CONFIG.md

@@ -8,11 +8,13 @@ A provider config is **trusted policy** for the native replay flow. One config d
 - which response fields may be disclosed (`revealRules`),
 - which template/parser identities the verifier accepts (`templateGovernance`).
 
-The built-in registry lives at [`src/providers.json`](./src/providers.json). It is a
-byte-identical copy of the central registry in
-[`burnt-labs/provider-bank`](https://github.com/burnt-labs/provider-bank)
-(`provider-bank/providers.json`). Edit it there, sync the copy here, then run
-`npm run test:providers`.
+Provider configs are loaded from the Provider Registry API runtime artifact at
+`/.well-known/provider-registry/providers.json`. Edit provider data in the registry
+backend, then run the backend registry validation and the SDK validator tests:
+
+```bash
+npm run test:providers
+```
 
 ## Object map
 
@@ -40,6 +42,10 @@ field table (`Req?` = required `yes` / optional `no`).
 ```json
 {
   "schemaVersion": "1.0.0",
+  "registryVersion": 42,
+  "minimumAllowedRegistryVersion": 40,
+  "currentSnapshotSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  "generatedAt": "2026-06-16T00:00:00.000Z",
   "providers": []
 }
 ```
@@ -48,6 +54,10 @@ field table (`Req?` = required `yes` / optional `no`).
 |---|---|---|---|
 | `providers` | yes | `Provider[]` | Non-empty array of provider objects. Provider ids must be unique. |
 | `schemaVersion` | no | `string` | Registry-level version. Optional in the SDK loader; each provider still needs its own `schemaVersion`. |
+| `registryVersion` | no | `number` | Monotonic committed registry version emitted by the provider registry backend. Required when a loader/verifier sets a minimum version floor. |
+| `minimumAllowedRegistryVersion` | no | `number` | Registry-published rollback floor for registry-wide loaders such as verifier startup. |
+| `currentSnapshotSha256` | no | `string` | SHA-256 hex of the canonical current snapshot. Used for diagnostics/cache keys. |
+| `generatedAt` | no | `string` | Snapshot generation timestamp. |
 
 ---
 
@@ -65,8 +75,7 @@ field table (`Req?` = required `yes` / optional `no`).
     "spkiSha256B64Pins": ["AAAA…="]
   },
   "templateGovernance": {
-    "templateHash": "dev-acme-current-user-v1-template",
-    "parserHash": "parser-sha256:0000…0000"
+    "policyHash": "policy-sha256:0000…0000"
   }
 }
 ```
@@ -76,12 +85,12 @@ field table (`Req?` = required `yes` / optional `no`).
 | Field | Type | Description |
 |---|---|---|
 | `schemaVersion` | `string` | Provider schema version (built-ins use `1.0.0`). |
-| `providerId` | `string` | Stable, unique id, e.g. `kaggle.current_user.v1`. Include a proof name + `.vN` suffix so verifier policy can pin it. Participates in `parserHash`. |
+| `providerId` | `string` | Stable, unique id, e.g. `kaggle.current_user.v1`. Include a proof name + `.vN` suffix so verifier policy can pin it. Participates in `policyHash`. |
 | `name` | `string` | User-facing name shown in selectors/UI. |
 | `login` | `object` | Page opened in the managed WebView. See §2. |
 | `endpoints` | `Endpoint[]` | Non-empty (max 20). Each is one replayable request. If no endpoint is selected, the SDK uses the first. See §3. |
 | `tlsIdentityPolicy` | `object` | Pinned host + SPKI pins. See §7. |
-| `templateGovernance` | `object` | Template/parser identity. See §8. |
+| `templateGovernance` | `object` | Provider policy identity. See §8. |
 
 **Optional fields**
 
@@ -93,9 +102,6 @@ field table (`Req?` = required `yes` / optional `no`).
 | `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. |
-| `label`, `displayName` | `string` | Legacy display fields; normalized for compatibility. Prefer `name`. |
-| `target` | `object` | Legacy `{ scheme: "https", host: expectedSni, port: 443 }`. Auto-generated when omitted. |
-| `webLogin` | `object` | Legacy; `login.url` is preferred. `webLogin.startUrl` maps to `login.url`. |
 
 Unknown top-level keys are cloned through but ignored by native replay/verification —
 never put security-critical behavior in an undocumented key.
@@ -150,7 +156,7 @@ Each endpoint describes one replayable request and its disclosure policy.
 
 | Field | Type | Description |
 |---|---|---|
-| `id` | `string` | Starts with a letter; letters/digits/`_`/`-` only; unique per provider. Participates in `parserHash`. |
+| `id` | `string` | Starts with a letter; letters/digits/`_`/`-` only; unique per provider. Participates in `policyHash`. |
 | `url` | `string` | HTTPS replay URL. Host must equal `tlsIdentityPolicy.expectedSni`. For dynamic endpoints (`replayCapturedUrl`) this is a stable prefix used for host pinning + match rules. |
 | `method` | `string` | One of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`. Must agree with the `methodEquals` rule. |
 | `headers` | `string[]` | Non-empty request-header allowlist for native replay. Only these captured headers are forwarded. Include `cookie` for cookie-auth endpoints, `user-agent` when behavior depends on it. `capture.headers` names are auto-added here. |
@@ -190,7 +196,7 @@ proof request matches. **Every endpoint must include a method rule and a URL rul
 ## 5. `revealRules[]`
 
 Describes exactly what the artifact may disclose. Each disclosed `RECV BODY` value becomes
-a claim. These rules are part of `parserHash`.
+a claim. These rules are part of `policyHash`.
 
 | Field | Req? | Type | Description |
 |---|---|---|---|
@@ -324,7 +330,8 @@ instead of the template `url`, still constrained to the pinned host:
 ```
 
 The template `url` is just the stable prefix (host/SNI + `urlContains`); the per-user URL
-is captured and replayed. Not part of the parser hash.
+is captured and replayed. It does not change the policy identity unless governance
+tooling explicitly includes it.
 
 ---
 
@@ -358,39 +365,40 @@ Ties the provider to verifier-side allowlists.
 
 ```json
 "templateGovernance": {
-  "templateHash": "dev-acme-current-user-v1-template",
-  "parserHash": "parser-sha256:0000…0000"
+  "policyHash": "policy-sha256:0000…0000"
 }
 ```
 
 | Field | Req? | Type | Description |
 |---|---|---|---|
-| `templateHash` | yes | `string` | Template identity accepted by the verifier. |
-| `parserHash` | yes | `string` | `parser-sha256:<64 hex>` derived from provider id, endpoint ids/order, response types, and reveal rules. See below. |
+| `policyHash` | yes | `string` | `policy-sha256:<64 hex>` identity accepted by the SDK and verifier for this provider policy. |
 | `fixtureSetHash` | no | `string` | Fixture-set identity. Defaults to `unversioned-fixtures`. |
 | `governancePolicyVersion` | no | `string` | Defaults to `embedded-registry`. |
-| `providerActivationState` | no | `string` | Defaults to `experimental`; production policy should require governed active templates. |
 
-**Parser hash.** It is derived, not arbitrary. The test script canonicalizes:
+**Policy hash.** It is derived, not arbitrary. The provider-policy tooling
+canonicalizes security-sensitive provider policy fields:
 
 ```json
 {
-  "schema": "satya-provider-parser-policy-v1",
+  "schema": "satya-provider-policy-v1",
   "providerId": "<provider id>",
+  "target": { "host": "<host>" },
+  "tlsIdentityPolicy": { "expectedSni": "<sni>", "spkiSha256B64Pins": [] },
   "endpoints": [{ "id": "<id>", "responseType": "<type>", "revealRules": [] }]
 }
 ```
 
-…SHA-256 hashes it, and stores `parser-sha256:<hex>`. Any change to `providerId`, endpoint
-ids/order, `responseType`, or `revealRules` changes it. After editing providers:
+It SHA-256 hashes the canonical policy and stores `policy-sha256:<hex>`. Any
+change to provider id, target host, TLS identity policy, endpoint ids/order,
+response type, or reveal rules should change it. After editing providers:
 
 ```bash
 cd platform_sdks/expo-satya-attest
-npm run test:providers   # prints the expected parser hash when stale
+npm run test:providers
 ```
 
-The client and backend verifier pin provider id, template hash, parser hash, activation
-state, and SPKI policy before accepting an artifact.
+The client and backend verifier pin provider id, policy hash, and SPKI policy before
+accepting an artifact.
 
 ---
 
@@ -487,7 +495,7 @@ console.log(body.match(/octolytics-actor-login" content="(.*?)"/)?.[1]);
 - raw `allowedRequestHeaders`, `allowedResponseBodyJsonPaths`, and `privacyPolicy` are
   rejected (the loader derives them from `revealRules`),
 - SPKI pins are SHA-256 base64,
-- `parserHash` matches the canonical parser policy.
+- `policyHash` matches the canonical provider policy.
 
 ## 12. Authoring tips
 

package/PROVIDER_REGISTRY.md

@@ -1,235 +1,137 @@
-# Provider Registry
+# Provider Registry Runtime
 
-`@burnt-labs/expo-satya-attest` ships with a built-in provider registry at
-[`src/providers.json`](./src/providers.json) — a vendored copy of the centralized
-registry in [`burnt-labs/provider-bank`](https://github.com/burnt-labs/provider-bank)
-(`provider-bank/providers.json`), which is the source of truth shared across
-services. Apps can also supply their own registry when they want provider templates
-outside the SDK package.
+`@burnt-labs/expo-satya-attest` loads provider policy from the Provider Registry API at
+runtime. The SDK no longer ships a bundled registry JSON or supports local registry
+fallbacks.
 
-Use a custom registry when:
+Default API:
 
-- your app needs providers that are not in the SDK package,
-- your app wants to pin a private allow-list,
-- your team wants to update provider templates through its own release process.
+```text
+https://api.provider-registry.burnt.com
+```
 
-For the provider JSON schema, optional fields, parser hash rules, and authoring
-guidance, see [`PROVIDER_CONFIG.md`](./PROVIDER_CONFIG.md).
+Default SDK load flow:
 
-## Loading A Custom Registry
+1. `GET {PROVIDER_REGISTRY_API}/api/providers/{providerId}`
+2. Reject missing or inactive provider records.
+3. Normalize the raw provider into the runtime shape needed by the SDK.
+4. Enforce SDK-owned runtime safety checks: HTTPS URLs, no user roots, SPKI pin syntax,
+   selected endpoint request matching, and supported reveal parsing.
 
-For a hosted registry:
+The SDK intentionally loads one provider at a time. The Provider Registry service owns
+provider-schema governance, migration compatibility, versioning, and registry-wide
+metadata checks.
 
-```tsx
-import { SatyaProviderAttestButton } from '@burnt-labs/expo-satya-attest';
-
-export function PayrollProof() {
-  return (
-    <SatyaProviderAttestButton
-      providerId="acme.payroll.v1"
-      providerRegistrySource={{
-        url: 'https://example.com/.well-known/satya/providers.json',
-        timeoutMs: 10000,
-        maxBytes: 524288,
-      }}
-      providerPolicyRefresh="verifier-required"
-      transportConfig={{
-        notaryUrl: 'https://verifier.example.com',
-        cloudProjectNumber: 0,
-      }}
-      verifyBackend
-      buttonLabel="Open payroll"
-    />
-  );
-}
+## SDK Init
+
+Configure the SDK once during app startup:
+
+```ts
+import { initSatyaAttest } from '@burnt-labs/expo-satya-attest';
+
+initSatyaAttest({
+  providerId: 'kaggle.current_user.v1',
+  providerRegistryApi: 'https://api.provider-registry.burnt.com',
+  registryTimeoutMs: 15000,
+  registryMaxBytes: 524288,
+  logLevel: 'warn',
+  logger: (entry) => {
+    // Send to your app logger, if desired.
+  },
+});
 ```
 
-For an in-app registry object:
+Options:
 
-```tsx
-import {
-  SatyaProviderAttestButton,
-  type SatyaProviderRegistry,
-} from '@burnt-labs/expo-satya-attest';
-
-const registry: SatyaProviderRegistry = {
-  schemaVersion: '1.0.0',
-  providers: [
-    // provider templates
-  ],
-};
+| Option                |                                   Default | Description                                                                 |
+| --------------------- | ----------------------------------------: | --------------------------------------------------------------------------- |
+| `providerId`          |                                      none | Provider id to load from the registry API. Required before provider lookup. |
+| `providerRegistryApi` | `https://api.provider-registry.burnt.com` | HTTPS base URL for the Provider Registry API.                               |
+| `registryTimeoutMs`   |                                   `15000` | Per-request timeout for provider fetches.                                   |
+| `registryMaxBytes`    |                                  `524288` | Maximum response body size.                                                 |
+| `logLevel`            |                    env-driven or `silent` | One of `silent`, `error`, `warn`, `info`, `debug`, `trace`.                 |
+| `logger`              |                                      none | Optional structured log sink.                                               |
+| `verboseLogging`      |                                   `false` | When true, disables default redaction. Do not enable in production.         |
 
-<SatyaProviderAttestButton
-  providerId="acme.payroll.v1"
-  providerRegistrySource={registry}
-  providerPolicyRefresh="verifier-required"
-  transportConfig={{ notaryUrl: 'https://verifier.example.com' }}
-/>;
+The Expo example also reads `EXPO_PUBLIC_PROVIDER_ID` and
+`EXPO_PUBLIC_PROVIDER_REGISTRY_API` so app developers can point a build at one provider
+and registry API without code changes.
+
+## Provider Lookup
+
+Load the configured provider template for diagnostics or custom UI:
+
+```ts
+import { initSatyaAttest, loadProviderTemplate } from '@burnt-labs/expo-satya-attest';
+
+initSatyaAttest({ providerId: 'kaggle.current_user.v1' });
+
+const template = await loadProviderTemplate();
 ```
 
-To populate your own selector UI:
+The SDK-owned button resolves the configured provider from the Provider Registry API:
 
 ```tsx
-import { listProviderRefs, loadProviderRegistry } from '@burnt-labs/expo-satya-attest';
-
-const registry = await loadProviderRegistry({
-  url: 'https://example.com/.well-known/satya/providers.json',
-});
-const providers = listProviderRefs(registry);
+<SatyaProviderAttestButton
+  providerPolicyRefresh="verifier-first"
+  transportConfig={{ verifierUrl: 'https://verifier.example.com' }}
+  verifyBackend
+/>
 ```
 
-`providerTemplate` still works for one-off integrations and wins over
-`providerRegistrySource` when both are supplied.
+`providerTemplate` remains available for tightly controlled tests or one-off
+integrations where the host app already owns a full template object. There is no
+alternate registry-source prop and no local HTTP registry mode.
 
-## Registry URL Rules
+## Supporting Endpoints
 
-Hosted registries are fetched with `GET` and must use HTTPS by default.
+- `GET /api/providers` is useful for registry diagnostics and admin UIs.
+- `GET /api/providers/{providerId}` is the SDK provider config source.
+- `GET /.well-known/provider-registry/providers.json` is still useful for verifier
+  startup and registry-wide diagnostics.
 
-```ts
-providerRegistrySource={{
-  url: 'https://example.com/.well-known/satya/providers.json',
-  headers: { Authorization: 'Bearer ...' },
-  timeoutMs: 10000,
-  maxBytes: 524288
-}}
-```
+## Errors
+
+Provider registry failures throw `SatyaError` with a stable `code`, message, optional
+context, and optional cause. Codes include:
 
-Security rules enforced by the SDK:
+- `SATYA_REGISTRY_INFO_MISMATCH`
+- `SATYA_REGISTRY_FETCH_FAILED`
+- `SATYA_REGISTRY_INVALID`
+- `SATYA_PROVIDER_NOT_FOUND`
+- `SATYA_PROVIDER_POLICY_MISMATCH`
 
-- `https://` is required by default,
-- URL credentials such as `https://user:pass@example.com/...` are rejected,
-- request headers cannot contain newline characters,
-- fetches are timeout bounded,
-- response bodies are size bounded,
-- JSON is validated and cloned before use.
+The SDK fails closed: it does not open the provider WebView when the registry cannot be
+loaded or validated.
 
-`allowInsecureHttp: true` exists only for local development:
+## Logging And Redaction
+
+SDK logs are structured and redacted by default. Tokens, cookies, auth headers, request
+bodies, and response bodies are replaced with byte-count placeholders unless
+`verboseLogging` is enabled. Use `logger` to mirror logs into a host app sink.
 
 ```ts
-providerRegistrySource={{
-  url: 'http://127.0.0.1:8080/providers.json',
-  allowInsecureHttp: true
-}}
+initSatyaAttest({
+  logLevel: 'debug',
+  logger: (entry) => myLogger.debug(entry),
+});
 ```
 
-Do not use insecure HTTP for production registries. A registry controls provider
-hosts, login URLs, WebView injection, request match rules, reveal rules, template
-hashes, parser hashes, and SPKI pin fallback policy.
+## Registry Shape
 
-## File Format
-
-Top-level registry shape:
+Top-level artifact:
 
 ```json
 {
   "schemaVersion": "1.0.0",
-  "providers": [
-    {
-      "schemaVersion": "1.0.0",
-      "providerId": "acme.current_user.v1",
-      "name": "Acme",
-      "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": "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"
-      }
-    }
-  ]
+  "registryVersion": 42,
+  "minimumAllowedRegistryVersion": 40,
+  "currentSnapshotSha256": "0123456789abcdef",
+  "generatedAt": "2026-06-18T00:00:00.000Z",
+  "providers": []
 }
 ```
 
-The SDK normalizes an endpoint into the compatibility `proofTarget` shape used by
-native replay. Raw provider configs should use endpoint `headers` instead of
-`privacyPolicy.allowedRequestHeaders`; the response reveal allowlist
-(`privacyPolicy.allowedResponseReveals`, plus the legacy `allowedResponseBodyJsonPaths`
-subset) is derived from `revealRules`, so raw configs should not include those keys.
-
-`responseType` may be `json`, `html`, or `text`. Reveal rules support three
-`params.type` values: `json` (JSON path), `regex` (a capture group over the raw body —
-the mechanism behind HTML/text providers), and `jsonRegex` (a JSON-path value run through
-a regex). `regex`/`jsonRegex` reveals require an explicit `params.alias`. See
-[`PROVIDER_CONFIG.md`](./PROVIDER_CONFIG.md#reveal-rules) for the full reveal-rule schema.
-
-## Validation Rules
-
-The SDK rejects custom registries unless each provider satisfies the runtime checks
-documented in [`PROVIDER_CONFIG.md`](./PROVIDER_CONFIG.md#validation-checklist). The
-built-in `src/providers.json` has an additional test guard:
-
-```bash
-cd platform_sdks/expo-satya-attest
-npm run test:providers
-```
-
-That script validates provider ids, endpoints, request matching, `responseType`, reveal
-rules (`json` / `regex` / `jsonRegex`), reveal aliases, SPKI pin syntax, and canonical
-parser hashes. It also rejects the old raw schema fields `privacyPolicy`,
-`allowedRequestHeaders`, and `allowedResponseBodyJsonPaths`.
-
-`npm test` runs this provider check and then a reveal-rule unit suite
-(`test:reveal`, `internal/module_scripts/test-reveal-rules.mjs`) that exercises the
-compiled validator against positive and negative reveal-rule cases.
-
-## Security Review Notes
-
-Threat model: a provider registry controls the login URL, WebView injection scripts,
-request matching rules, replay URL, trusted SNI, template hash, parser hash, reveal
-rules, and optional SPKI pins. Treat it as trusted policy, not ordinary app content.
-
-Confirmed protections in the SDK:
-
-- remote registries are HTTPS-only by default, with timeout and size limits,
-- registry URLs with embedded credentials are rejected,
-- registry request headers are sanitized for newline injection,
-- templates are validated and cloned before use,
-- custom templates cannot enable user-installed roots,
-- replay URL, endpoint host, and expected SNI must agree,
-- request matching must bind both method and URL,
-- verifier SPKI policy is checked against provider id, host, template hash, and
-  parser hash before those pins are used,
-- backend verification independently re-derives trusted template and pin policy.
-
-Residual risks and required operating practices:
-
-- a malicious host app can intentionally pass a malicious registry or template. The SDK
-  is not a trust boundary against the application that embeds it,
-- a compromised registry host can change templates. Production backends must reject
-  unknown `templateHash` / `parserHash` values and should use
-  `providerPolicyRefresh="verifier-required"`,
-- do not put secrets in registry URLs. Use short-lived headers if a private registry
-  needs authentication,
-- do not use `allowInsecureHttp` outside local development,
-- keep verifier provider policy in sync with custom registry templates. Client-side
-  registry validation protects replay setup; verifier policy decides whether an
-  artifact is acceptable.
+Provider and endpoint fields are documented in [`PROVIDER_CONFIG.md`](./PROVIDER_CONFIG.md).
+The SDK validates only the fields it needs to execute the mobile flow safely; registry
+schema governance and migrations stay on the Provider Registry service.

package/PUBLISHING.md

@@ -107,16 +107,16 @@ npm run check:pack
 
 What each check covers:
 
-| Check | Purpose |
-|---|---|
-| `check:metadata` | Confirms package metadata, README, LICENSE, plugin, and module config exist. |
-| `clean` + `build` | Rebuilds TypeScript output in `build/`. |
-| `lint` | Runs ESLint over `src/`. |
-| `test:providers` | Validates provider ids, template hashes, parser hashes, request match rules, HTTPS proof URLs, SNI, and SPKI pins. |
-| `test:publishing-workflows` | Confirms publish workflows build iOS artifacts with simulator slices and matching Rust targets. |
-| `check:example` | Type-checks the Expo example when its dependencies are installed. |
-| `check:native-artifacts` | Fails if Android `.so`, generated Kotlin, iOS XCFramework, or generated Swift glue are missing. |
-| `check:pack` | Runs `npm pack --dry-run --json` and verifies the actual tarball contents. |
+| Check                       | Purpose                                                                                           |
+| --------------------------- | ------------------------------------------------------------------------------------------------- |
+| `check:metadata`            | Confirms package metadata, README, LICENSE, plugin, and module config exist.                      |
+| `clean` + `build`           | Rebuilds TypeScript output in `build/`.                                                           |
+| `lint`                      | Runs ESLint over `src/`.                                                                          |
+| `test:providers`            | Validates provider ids, policy hashes, request match rules, HTTPS proof URLs, SNI, and SPKI pins. |
+| `test:publishing-workflows` | Confirms publish workflows build iOS artifacts with simulator slices and matching Rust targets.   |
+| `check:example`             | Type-checks the Expo example when its dependencies are installed.                                 |
+| `check:native-artifacts`    | Fails if Android `.so`, generated Kotlin, iOS XCFramework, or generated Swift glue are missing.   |
+| `check:pack`                | Runs `npm pack --dry-run --json` and verifies the actual tarball contents.                        |
 
 The package uses a `files` whitelist in `package.json`, so `node_modules`, the example
 app, `.env` files, `.DS_Store`, build caches, and generated tarballs are kept out of the
@@ -135,7 +135,6 @@ Check that the tarball contains:
 
 ```text
 build/
-src/providers.json
 app.plugin.js
 expo-module.config.json
 android/src/main/
@@ -189,33 +188,37 @@ npm version patch
 npm publish
 ```
 
-## GitHub Packages Preview
+## npm Snapshots
 
-Pushes to `earnos-ready-plugin` publish a preview package to GitHub Packages with a
+Every push to `main` publishes a snapshot package to the public npm registry with a
 unique prerelease version:
 
 ```text
-0.1.0-earnos.<run>.<attempt>.sha-<commit>
+1.0.1-snapshot.<run>.<attempt>.sha-<commit>
 ```
 
-The workflow uses the `earnos-ready` dist-tag so test apps do not need to know the
-generated version:
+The snapshot workflow increments the package's patch base in CI before publishing. For
+example, if `package.json` is `1.0.0`, the snapshot version is based on `1.0.1`:
+`1.0.1-snapshot.<run>.<attempt>.sha-<commit>`.
+
+Snapshots use the `snapshot` dist-tag so test apps do not need to know the generated
+version:
 
 ```bash
-@burnt-labs:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+npm install @burnt-labs/expo-satya-attest@snapshot
+npx expo install react-native-webview
 ```
 
-Then install the preview package:
+To inspect the exact snapshot version currently behind the dist-tag:
 
 ```bash
-npm install @burnt-labs/expo-satya-attest@earnos-ready
-npx expo install react-native-webview
+npm view @burnt-labs/expo-satya-attest dist-tags.snapshot
 ```
 
-Use a GitHub token with `read:packages` for `GITHUB_PACKAGES_TOKEN`. The branch preview
-workflow publishes with the repository `GITHUB_TOKEN`, `packages: write`, and does not
-publish to npm.
+Snapshots are not tagged as `latest`. Stable releases still require a matching
+`expo-satya-attest-vX.Y.Z` or `vX.Y.Z` tag and publish through the stable release
+workflow. Prefer the package-specific `expo-satya-attest-vX.Y.Z` form in this
+monorepo.
 
 ## Post-Publish Smoke Test
 
@@ -268,7 +271,7 @@ GitHub release tarball smoke test:
 
 ```bash
 cd /private/tmp/SatyaSmoke
-npm install https://github.com/<owner>/<repo>/releases/download/expo-satya-attest-v0.2.2/burnt-labs-expo-satya-attest-0.2.2.tgz
+npm install https://github.com/<owner>/<repo>/releases/download/expo-satya-attest-v1.0.0/burnt-labs-expo-satya-attest-1.0.0.tgz
 npx expo install react-native-webview
 ```
 
@@ -276,7 +279,7 @@ For a raw Git install, publish the SDK from a dedicated repo or a subtree/split
 where the SDK package is at the Git root:
 
 ```bash
-npm install github:<owner>/<sdk-repo>#v0.2.2
+npm install github:<owner>/<sdk-repo>#v1.0.0
 ```
 
 Do not document a normal monorepo Git URL as plug-and-play unless the Git ref has