@burnt-labs/expo-satya-attest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROVIDER_REGISTRY.md

@@ -0,0 +1,271 @@
+# Provider Registry
+
+`@burnt-labs/expo-satya-attest` ships with a built-in provider registry at
+[`src/providers.json`](./src/providers.json). Apps can also supply their own registry
+when they want to keep provider templates outside the SDK package.
+
+Use a custom registry when:
+
+- 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.
+
+## Loading A Custom Registry
+
+For a hosted registry:
+
+```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"
+    />
+  );
+}
+```
+
+For an in-app registry object:
+
+```tsx
+import { SatyaProviderAttestButton, type SatyaProviderRegistry } from '@burnt-labs/expo-satya-attest';
+
+const registry: SatyaProviderRegistry = {
+  schemaVersion: '0.1.0',
+  providers: [
+    // provider templates
+  ],
+};
+
+<SatyaProviderAttestButton
+  providerId="acme.payroll.v1"
+  providerRegistrySource={registry}
+  providerPolicyRefresh="verifier-required"
+  transportConfig={{ notaryUrl: 'https://verifier.example.com' }}
+/>;
+```
+
+To populate your own selector UI:
+
+```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);
+```
+
+`providerTemplate` still works for one-off integrations and wins over
+`providerRegistrySource` when both are supplied.
+
+## Registry URL Rules
+
+Hosted registries are fetched with `GET` and must use HTTPS by default.
+
+```ts
+providerRegistrySource={{
+  url: 'https://example.com/.well-known/satya/providers.json',
+  headers: { Authorization: 'Bearer ...' },
+  timeoutMs: 10000,
+  maxBytes: 524288
+}}
+```
+
+Security rules enforced by the SDK:
+
+- `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.
+- The JSON is validated and cloned before use.
+
+`allowInsecureHttp: true` exists only for local development:
+
+```ts
+providerRegistrySource={{
+  url: 'http://127.0.0.1:8080/providers.json',
+  allowInsecureHttp: true
+}}
+```
+
+Do not use insecure HTTP for production registries. A registry controls which provider
+host, template hash, parser hash, request match rules, and reveal rules the SDK uses.
+
+## File Format
+
+Top-level shape:
+
+```json
+{
+  "schemaVersion": "0.1.0",
+  "providers": []
+}
+```
+
+Provider template shape:
+
+```json
+{
+  "schemaVersion": "0.1.0",
+  "providerId": "acme.payroll.v1",
+  "label": "Acme Payroll",
+  "description": "Current employee payroll proof",
+  "displayName": "Acme Payroll",
+  "version": "v1",
+  "target": {
+    "scheme": "https",
+    "host": "payroll.example.com",
+    "port": 443
+  },
+  "webLogin": {
+    "startUrl": "https://payroll.example.com/login",
+    "callbackUrl": "https://payroll.example.com/",
+    "oauthHosts": ["payroll.example.com"]
+  },
+  "userAgent": {
+    "ios": null,
+    "android": null
+  },
+  "proofTarget": {
+    "method": "GET",
+    "url": "https://payroll.example.com/api/current-user",
+    "requestMatchRules": [
+      {
+        "type": "methodEquals",
+        "pattern": "GET"
+      },
+      {
+        "type": "urlContains",
+        "pattern": "/api/current-user"
+      }
+    ],
+    "revealRules": [
+      {
+        "action": "REVEAL",
+        "direction": "RECV",
+        "part": "BODY",
+        "params": {
+          "type": "json",
+          "path": "$.employeeId"
+        }
+      }
+    ],
+    "maxSentData": 4096,
+    "maxRecvData": 131072
+  },
+  "privacyPolicy": {
+    "allowedRequestHeaders": ["accept", "cookie", "content-type", "user-agent"],
+    "allowedResponseBodyJsonPaths": ["$.employeeId"]
+  },
+  "tlsPolicy": {
+    "requireTls13": true,
+    "allowZeroRtt": false,
+    "allowResumption": false,
+    "allowKeyUpdate": false,
+    "preferredCipher": "TLS_CHACHA20_POLY1305_SHA256",
+    "maxSentBytes": 4096,
+    "maxRecvBytes": 131072
+  },
+  "tlsIdentityPolicy": {
+    "expectedSni": "payroll.example.com",
+    "allowedAlpn": ["h2", "http/1.1"],
+    "spkiSha256Hex": null,
+    "spkiSha256B64Pins": ["KWQsjul7mJDk+i6fAisGLhWLd43FUs5ayVmkz5Y54DU="],
+    "tlsTrustStorePolicy": "web-pki-os-roots-no-user-roots",
+    "userRootsAllowed": false,
+    "redirectPolicyId": "no-cross-origin-redirects-v1"
+  },
+  "templateGovernance": {
+    "templateHash": "prod-acme-payroll-v1-template",
+    "parserHash": "prod-acme-payroll-v1-parser",
+    "fixtureSetHash": "prod-acme-payroll-v1-fixtures",
+    "governancePolicyVersion": "prod-governance-v1",
+    "providerActivationState": "active"
+  },
+  "freshness": {
+    "mode": "notary_nonce",
+    "echoCapable": false,
+    "injection": null,
+    "reflectionPath": null,
+    "cacheKeyAffecting": true,
+    "semanticallyInert": true
+  },
+  "credentialCustody": {
+    "model": "webview_session_cookie",
+    "allowImportedCookies": false,
+    "accountBindingRequired": true
+  }
+}
+```
+
+## Validation Rules
+
+The SDK rejects custom registries unless each provider satisfies these checks:
+
+- provider ids are unique and non-empty,
+- `target.scheme` is `https`,
+- `target.port` is `443`,
+- `proofTarget.url` is HTTPS,
+- `proofTarget.url` host matches `target.host`,
+- `proofTarget.url` host matches `tlsIdentityPolicy.expectedSni`,
+- `tlsIdentityPolicy.tlsTrustStorePolicy` is `web-pki-os-roots-no-user-roots`,
+- `tlsIdentityPolicy.userRootsAllowed` is `false`,
+- SPKI pins are valid SHA-256 base64 strings when present,
+- `templateGovernance.templateHash` and `parserHash` are non-empty,
+- `privacyPolicy.allowedRequestHeaders` is non-empty,
+- `privacyPolicy.allowedResponseBodyJsonPaths` is non-empty,
+- `proofTarget.requestMatchRules` includes a `methodEquals` rule matching
+  `proofTarget.method`,
+- `proofTarget.requestMatchRules` includes a `urlContains` rule matching the
+  `proofTarget.url` path or query.
+
+The SDK validates the registry before opening the WebView and the native iOS/Android
+modules repeat critical checks before replay.
+
+## Security Review Notes
+
+Threat model: a provider registry controls the login URL, request matching rules, replay
+URL, trusted SNI, template hash, parser hash, reveal rules, and optional SPKI pins. Treat
+it as trusted policy, not as 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, target host, and expected SNI must agree.
+- Request matching must bind both method and URL.
+- Verifier SPKI policy is still 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. The client-side
+  registry protects replay setup; the verifier policy decides whether an artifact is
+  acceptable.

package/PUBLISHING.md

@@ -0,0 +1,291 @@
+# Publishing `@burnt-labs/expo-satya-attest`
+
+This SDK should publish as an npm package. Expo and React Native apps install native
+modules from npm, then CocoaPods and Gradle consume the iOS/Android native code from
+`node_modules`. You do not need a separate CocoaPods trunk package or Maven package for
+the current layout.
+
+Use GitHub Releases only as an optional companion for binary provenance, checksums, or
+very large native artifacts. The npm tarball still needs the native artifacts unless the
+package is redesigned to download or build them during install, which is not recommended
+for a plug-and-play Expo SDK.
+
+## Package Name
+
+Use the scoped public package owned by the Burnt npm organization:
+
+```bash
+@burnt-labs/expo-satya-attest
+```
+
+Check before release:
+
+```bash
+npm view @burnt-labs/expo-satya-attest version
+```
+
+If npm returns `E404`, the package has not been published yet. The `NPM_TOKEN` used by
+GitHub Actions must belong to an npm account or automation token with publish rights for
+the `@burnt-labs` scope. Scoped public publishes must use `npm publish --access public`.
+
+## Native Artifacts That Must Ship
+
+The SDK wraps Rust through UniFFI, so the npm package must include prebuilt native
+artifacts. Consumers should not have to install Rust, Android NDK, cargo-ndk, or Xcode
+toolchains just to install the SDK.
+
+Required Android files:
+
+```text
+android/src/main/java/uniffi/satya_ffi/satya_ffi.kt
+android/src/main/jniLibs/arm64-v8a/libsatya_ffi.so
+android/src/main/jniLibs/armeabi-v7a/libsatya_ffi.so
+android/src/main/jniLibs/x86_64/libsatya_ffi.so
+```
+
+Required iOS files:
+
+```text
+ios/Generated/satya_ffi.swift
+ios/Frameworks/libsatya_ffi-rs.xcframework/
+```
+
+These outputs are gitignored because they are generated build products. A release job
+must build them before `npm publish`, or the release manager must build them locally
+before publishing.
+
+Build them from the module directory:
+
+```bash
+cd platform_sdks/expo-satya-attest
+npm run build:native:android
+npm run build:native:ios
+```
+
+iOS artifacts can only be built on macOS with Xcode command line tools. Android artifacts
+need the Android NDK, JDK 17, `cargo-ndk`, and Rust Android targets.
+
+The iOS build strips local/debug symbols from the static archives by default. For a
+diagnostic unstripped iOS build:
+
+```bash
+SATYA_IOS_STRIP=0 npm run build:native:ios
+```
+
+By default, the iOS release build includes only the physical-device `arm64` slice. That
+is intentional: the real App Attest flow does not work on the iOS simulator, and shipping
+simulator slices makes the npm package much larger without helping the production claim
+path.
+
+## Release Checks
+
+Install dependencies:
+
+```bash
+cd platform_sdks/expo-satya-attest
+npm install
+```
+
+Run the full release gate:
+
+```bash
+npm run release:check
+```
+
+This runs:
+
+```bash
+npm run check:metadata
+npm run clean
+npm run build
+npm run lint
+npm run test:providers
+npm run check:example
+npm run check:native-artifacts
+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. |
+| `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
+npm package.
+
+## Dry Run
+
+After `release:check` passes, inspect the package:
+
+```bash
+npm run pack:dry-run
+npm publish --dry-run
+```
+
+Check that the tarball contains:
+
+```text
+build/
+src/providers.json
+app.plugin.js
+expo-module.config.json
+android/src/main/
+ios/SatyaAttest.podspec
+ios/SatyaAttestModule.swift
+ios/Generated/
+ios/Frameworks/
+README.md
+LICENSE
+```
+
+Check that it does not contain:
+
+```text
+expo-satya-attest-example/
+node_modules/
+.env
+.DS_Store
+*.tgz
+internal/module_scripts/
+```
+
+## Publish
+
+Log in and publish:
+
+```bash
+npm login
+npm publish
+```
+
+For a scoped public package, use:
+
+```bash
+npm publish --access public
+```
+
+For prereleases:
+
+```bash
+npm version prerelease --preid alpha
+npm publish --tag alpha
+```
+
+For stable releases:
+
+```bash
+npm version patch
+npm publish
+```
+
+## Post-Publish Smoke Test
+
+Create a temporary Expo app and install from npm:
+
+```bash
+npx create-expo-app SatyaSmoke
+cd SatyaSmoke
+npx expo install @burnt-labs/expo-satya-attest react-native-webview
+```
+
+Add the plugin to `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": [["@burnt-labs/expo-satya-attest", { "appAttestEnvironment": "development" }]]
+  }
+}
+```
+
+Render `SatyaProviderAttestButton`, rebuild a development client, and run on a real
+device:
+
+```bash
+npx expo run:ios
+npx expo run:android
+```
+
+The app still needs access to a running `satya-verifier-service` for verifier-backed SPKI
+policy refresh and backend artifact verification.
+
+## GitHub And Local Install Smoke Tests
+
+Consumers may also install the SDK from a local directory or GitHub release tarball.
+Both paths must include the same built files as the npm package.
+
+Local directory smoke test:
+
+```bash
+cd platform_sdks/expo-satya-attest
+npm run release:check
+
+cd /private/tmp/SatyaSmoke
+npm install /path/to/tls-app-attest/platform_sdks/expo-satya-attest
+npx expo install react-native-webview
+```
+
+GitHub release tarball smoke test:
+
+```bash
+cd /private/tmp/SatyaSmoke
+npm install https://github.com/<owner>/<repo>/releases/download/expo-satya-attest-v0.1.0/burnt-labs-expo-satya-attest-0.1.0.tgz
+npx expo install react-native-webview
+```
+
+For a raw Git install, publish the SDK from a dedicated repo or a subtree/split branch
+where the SDK package is at the Git root:
+
+```bash
+npm install github:<owner>/<sdk-repo>#v0.1.0
+```
+
+Do not document a normal monorepo Git URL as plug-and-play unless the Git ref has
+`platform_sdks/expo-satya-attest` split to the package root. npm does not install a
+package from a GitHub subdirectory directly, and this SDK needs its prebuilt native
+artifacts in the installed package.
+
+## Binary Size Guidance
+
+The native Rust artifacts are expected and should ship in the npm package. They are not
+"extra" optional files for this SDK because the native replay path depends on them.
+
+Keep watching:
+
+- `npm run check:native-artifacts` for Android/iOS unpacked binary size.
+- `npm run check:pack` for npm tarball and unpacked package size.
+- Whether every release includes only the ABIs you actually support.
+
+Current default iOS output includes only device `arm64`. If you need simulator artifacts
+for local fallback/debug work, opt in explicitly:
+
+```bash
+SATYA_IOS_INCLUDE_SIMULATOR=1 npm run build:native:ios
+```
+
+For Apple-Silicon-simulator-only fallback builds:
+
+```bash
+SATYA_IOS_SIMULATOR_TARGETS="aarch64-apple-ios-sim" npm run build:native:ios
+```
+
+Do not publish simulator slices unless you intentionally support a simulator fallback
+experience. They are not useful for real App Attest verification.
+
+If the tarball becomes too large for npm or painful for app installs, the next design
+step is a binary-release model:
+
+1. Publish checksummed XCFramework and Android AAR/native artifacts to GitHub Releases.
+2. Update the podspec/Gradle integration to consume those artifacts deterministically.
+3. Keep install scripts fail-closed and checksum verified.
+
+Do that only if size forces it. For the current plug-and-play SDK shape, bundling the
+native artifacts inside the npm package is simpler and safer for users.