@burnt-labs/expo-satya-attest 0.1.0

package/README.md

@@ -0,0 +1,374 @@
+# @burnt-labs/expo-satya-attest
+
+Expo / React Native native module for SATYA mobile app attestation. The module uses
+the Rust `satya-sdk` / `satya-ffi` pipeline for artifact construction and verifier
+policy, while Swift and Kotlin provide platform-specific WebView capture, native HTTPS
+replay, hardware-backed signing, and platform attestation evidence.
+
+## Current Flow
+
+The supported Expo flow is **certificate-pinned native replay**. Third-party apps can
+use the SDK-owned button component for the full managed flow:
+
+1. The app renders `SatyaProviderAttestButton` with a provider id and transport config.
+2. The SDK refreshes SPKI pin policy from the verifier, falling back to registry pins.
+3. The SDK opens an in-app `react-native-webview` modal for login and request discovery.
+4. The SDK waits for a provider request that matches template `requestMatchRules`.
+5. Swift/Kotlin replay the trusted template URL natively with shared WebView cookies.
+6. The native client uses system trust without user roots and requires SPKI pins.
+7. The Rust core emits a `native-pinned-observed` SATYA artifact.
+8. The SDK verifies locally, optionally posts the artifact to `satya-verifier-service`,
+   and returns the result through `onComplete`.
+
+The earlier mock and plain `webview-observed` modes are no longer exposed through the
+high-level Expo client because they do not prove a provider response fetched through a
+pinned native TLS connection.
+
+## Native Trust Tiers
+
+| Platform         | Witness key                           | Platform evidence                | Typical tier                                                                        |
+| ---------------- | ------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
+| iOS device       | Secure Enclave P-256                  | App Attest assertion/attestation | `ios-app-attest-sep-bound`                                                          |
+| iOS simulator    | software P-256                        | honest simulator fallback        | `ios-simulator-dev`                                                                 |
+| Android device   | Keystore EC, StrongBox when available | Play Integrity hook              | `android-strongbox-play-integrity` / `android-keystore-play-integrity-no-strongbox` |
+| Android emulator | software EC                           | honest emulator fallback         | `android-emulator-dev`                                                              |
+
+Artifacts are dev-notary signed by default. Production-grade verification requires
+production notary keys, active templates, fresh revocation epochs, and pass-2 platform
+verification where appropriate.
+
+## Build The Rust Core
+
+The generated native artifacts are gitignored:
+
+- `ios/Frameworks/`
+- `ios/Generated/`
+- `android/src/main/jniLibs/`
+- generated uniffi Swift/Kotlin glue
+
+Build them from the workspace root before opening Xcode or Gradle:
+
+```bash
+# iOS XCFramework + Swift glue
+platform_sdks/expo-satya-attest/scripts/build-rust-ios.sh
+
+# Android .so files + Kotlin glue
+# One-time prereqs: Android NDK, JDK 17, cargo-ndk, and Android Rust targets.
+platform_sdks/expo-satya-attest/scripts/build-rust-android.sh
+```
+
+From the module directory, the same commands are available as:
+
+```bash
+npm run build:native:ios
+npm run build:native:android
+```
+
+`build:native:ios` strips local/debug symbols from the XCFramework and publishes a
+physical-device `arm64` iOS slice by default because the real App Attest flow does not
+work on simulator. See [`PUBLISHING.md`](./PUBLISHING.md) for optional simulator fallback
+builds and other binary-size knobs.
+
+Build TypeScript after editing `src/*.ts` or `src/*.tsx`:
+
+```bash
+cd platform_sdks/expo-satya-attest
+npm install
+npm run build
+npm run lint
+```
+
+The example app consumes the compiled `build/` directory, so restart Metro with
+`--clear` after rebuilding the module.
+
+## Provider Registry
+
+Provider configs live in one SDK-owned JSON file: [`src/providers.json`](./src/providers.json).
+The registry includes Kaggle, Deel, Gusto, Aadhaar, Uber, and Swiggy provider templates
+ported from `mobile_tlsn_plugin`.
+
+Useful exports:
+
+```ts
+import {
+  loadProviderRegistry,
+  listProviderRefs,
+  requireProviderTemplate,
+  SatyaProviderAttestButton,
+  validateProviderRegistry,
+  withProviderSpkiPins,
+  SatyaMobileClient,
+} from '@burnt-labs/expo-satya-attest';
+```
+
+Native replay requires at least one SPKI SHA-256 base64 pin at runtime. By default,
+`SatyaProviderAttestButton` fetches
+`GET /v1/providers/{providerId}/policy` from `transportConfig.notaryUrl` before opening
+the WebView, validates that the returned provider id, host, template hash, and parser
+hash match the selected template, and freezes those pins for the attestation run. If the
+verifier is unavailable, it falls back to the SDK registry pins. Set
+`providerPolicyRefresh="verifier-required"` to fail closed whenever the verifier policy
+cannot be fetched, or `providerPolicyRefresh="template-only"` for offline demos.
+
+## Installation Options
+
+Every install path also needs the WebView peer dependency:
+
+```bash
+npx expo install react-native-webview
+```
+
+Use npm for released apps:
+
+```bash
+npx expo install @burnt-labs/expo-satya-attest
+```
+
+Use a local checkout while developing the SDK or testing unpublished changes:
+
+```bash
+cd /path/to/tls-app-attest/platform_sdks/expo-satya-attest
+npm install
+npm run build
+npm run check:native-artifacts
+
+cd /path/to/your-expo-app
+npm install /path/to/tls-app-attest/platform_sdks/expo-satya-attest
+npx expo install react-native-webview
+```
+
+Re-run `npm run build` in the SDK directory after TypeScript edits. Re-run the native
+build scripts after Rust/UniFFI edits so the local package still contains
+`ios/Generated`, `ios/Frameworks`, Android `jniLibs`, and generated Kotlin.
+
+Use GitHub when you want a pinned unreleased version. The most reliable GitHub install
+is a release tarball produced by `npm pack`, because it contains the same files npm
+would publish:
+
+```bash
+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
+```
+
+Installing from a Git ref also works when that ref has the SDK package at the repository
+root, such as a dedicated SDK repo or a subtree/split branch:
+
+```bash
+npm install github:<owner>/<sdk-repo>#v0.1.0
+npm install git+https://github.com/<owner>/<sdk-repo>.git#v0.1.0
+npx expo install react-native-webview
+```
+
+Do not point npm at the monorepo root unless that Git ref is prepared so
+`package.json`, `build/`, native artifacts, and Expo module files are at the root of the
+Git package. npm does not install this monorepo's `platform_sdks/expo-satya-attest`
+subdirectory directly from a normal GitHub URL.
+
+After changing the install source, rebuild the native app:
+
+```bash
+npx expo prebuild --clean
+npx expo run:ios --device
+npx expo run:android
+```
+
+## Plug-And-Play API
+
+Add the Expo config plugin as shown below, rebuild the native app, then render the
+SDK-owned button:
+
+```tsx
+import { SatyaProviderAttestButton } from '@burnt-labs/expo-satya-attest';
+
+export function KaggleAttestation() {
+  return (
+    <SatyaProviderAttestButton
+      providerId="kaggle.current_user.v1"
+      providerPolicyRefresh="verifier-first"
+      transportConfig={{
+        notaryUrl: 'http://192.168.29.186:7047',
+        cloudProjectNumber: 0,
+      }}
+      verifyBackend
+      buttonLabel="Open Kaggle"
+      onComplete={(result) => {
+        console.log(result.raw);
+        console.log(result.verify);
+        console.log(result.backendVerify);
+      }}
+      onError={(error) => {
+        console.warn(error.message);
+      }}
+    />
+  );
+}
+```
+
+When pressed, the component opens the provider WebView inside the same app, captures the
+matching request, performs native replay with cookie sharing, verifies locally, posts to
+the backend verifier when `verifyBackend` is set, and returns a
+`SatyaProviderAttestationResult`.
+
+Apps can customize the button label, modal title, WebView props, and callbacks. Apps
+that use a custom provider allow-list can pass `providerTemplate` instead of
+`providerId`. Explicit `spkiPins` are still supported for controlled tests and override
+verifier/template policy refresh. The managed WebView uses provider `userAgent` settings
+when present, otherwise it falls back to a mobile Chrome/Safari user agent like
+`mobile_tlsn_plugin`;
+pass `webViewUserAgent` to override it explicitly.
+
+## Low-Level API
+
+```ts
+import {
+  SatyaMobileClient,
+  requireProviderTemplate,
+  withProviderSpkiPins,
+} from '@burnt-labs/expo-satya-attest';
+
+const providerTemplate = withProviderSpkiPins(requireProviderTemplate('kaggle.current_user.v1'), [
+  'KWQsjul7mJDk+i6fAisGLhWLd43FUs5ayVmkz5Y54DU=',
+]);
+
+const client = new SatyaMobileClient();
+const { artifact, raw, verify } = await client.attestNativeReplay({
+  providerTemplate,
+  capturedRequest,
+  transportConfig: {
+    notaryUrl: 'http://127.0.0.1:7047',
+    cloudProjectNumber: 0,
+  },
+});
+```
+
+`capturedRequest` should come from the WebView interceptor and must match the selected
+provider template. The returned `raw` string is the artifact JSON to post to
+`POST /v1/artifacts/verify` on `satya-verifier-service`.
+
+## Custom Provider Registries
+
+Apps can keep provider templates outside the built-in SDK registry by passing
+`providerRegistrySource` to the SDK-owned button:
+
+```tsx
+<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' }}
+/>
+```
+
+Or load it yourself for a custom selector:
+
+```ts
+const registry = await loadProviderRegistry({
+  url: 'https://example.com/.well-known/satya/providers.json',
+});
+const providers = listProviderRefs(registry);
+```
+
+Hosted registries are HTTPS-only by default, size/timeout bounded, and validated before
+the WebView opens. See [`PROVIDER_REGISTRY.md`](./PROVIDER_REGISTRY.md) for the complete
+JSON format, validation rules, and security review notes.
+
+## Config Plugin
+
+Add the plugin to inject App Attest entitlements and platform pinning config:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@burnt-labs/expo-satya-attest",
+        {
+          "appAttestEnvironment": "development",
+          "pinnedProviders": [
+            {
+              "host": "www.kaggle.com",
+              "spkiSha256B64Pins": ["KWQsjul7mJDk+i6fAisGLhWLd43FUs5ayVmkz5Y54DU="]
+            }
+          ]
+        }
+      ]
+    ]
+  }
+}
+```
+
+Use `development` for debug/TestFlight and `production` for App Store builds. iOS App
+Attest requires a real device plus an App ID with the DeviceCheck/App Attest capability.
+
+## Example App
+
+```bash
+cd platform_sdks/expo-satya-attest/expo-satya-attest-example
+npm install --ignore-scripts
+mkdir -p node_modules/@burnt-labs
+ln -sfn ../.. node_modules/@burnt-labs/expo-satya-attest
+npx expo run:ios --device
+npx expo run:android
+```
+
+See [expo-satya-attest-example/README.md](./expo-satya-attest-example/README.md) for
+device env setup and backend verifier commands.
+
+## Verification Backend
+
+Run the SATYA verifier service from the workspace root:
+
+```bash
+cargo run -p satya-verifier-service
+```
+
+The service loads `crates/satya-verifier-service/.env`, which is prefilled locally with
+provider-specific SPKI pins. For a physical device, set the Expo example's
+`EXPO_PUBLIC_NOTARY_URL` to your laptop LAN URL, such as `http://192.168.29.186:7047`.
+
+## Checks
+
+```bash
+cd platform_sdks/expo-satya-attest
+npm run build
+npm run lint
+npm run release:check
+
+cd expo-satya-attest-example
+./node_modules/.bin/tsc --pretty false --noEmit
+
+cd ../../..
+cargo test -p satya-ffi native_replay_observed_nested_json_paths_verify
+cargo test -p satya-verifier-service
+```
+
+## Publishing
+
+The Expo SDK should publish to npm. The npm package must include the generated Android
+`.so` files, generated UniFFI Kotlin/Swift glue, and iOS XCFramework so third-party apps
+can install it without building Rust locally. See [`PUBLISHING.md`](./PUBLISHING.md) for
+the release checklist, dry-run commands, binary-size guidance, and scoped-package naming
+recommendations.
+
+## Security Notes
+
+- WebView response bytes are not attested. The WebView is only a login/request discovery
+  surface.
+- Cookies are shared into native replay through platform cookie stores.
+- Native replay blocks user roots and requires client-side SPKI pins so the replay
+  connection fails closed before producing an artifact.
+- The SDK never learns production trust by fetching the provider's live certificate and
+  trusting it for the same run. Dynamic pins come from verifier policy, are validated
+  against the selected template, and are frozen before WebView capture starts.
+- Backend verification independently re-derives trusted template hashes and pins from
+  backend config, not from the client artifact alone. Client pins protect the fetch;
+  backend pins protect acceptance.
+- For production deployments, serve verifier policy over an authenticated channel
+  controlled by the verifier operator. Raw provider SPKI discovery is only suitable as a
+  manual/dev maintenance aid, not as automatic trust.
+- Development artifacts remain dev-tier and should not be accepted by production
+  verifiers.

package/android/build.gradle

@@ -0,0 +1,37 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'expo.modules.satyaattest'
+version = '0.1.0'
+
+android {
+  namespace "expo.modules.satyaattest"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+    // StrongBox key attestation needs API 28+; basic Keystore attestation API 24+.
+    minSdkVersion 24
+  }
+  lintOptions {
+    abortOnError false
+  }
+  // Prebuilt per-ABI Rust libraries produced by scripts/build-rust-android.sh.
+  sourceSets {
+    main {
+      jniLibs.srcDirs += ['src/main/jniLibs']
+    }
+  }
+}
+
+dependencies {
+  // uniffi-generated Kotlin bindings load the native lib through JNA. The @aar
+  // classifier is mandatory on Android (the plain jar crashes at runtime).
+  implementation "net.java.dev.jna:jna:5.14.0@aar"
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3"
+  // Google Play Integrity (Android analog of iOS App Attest).
+  implementation "com.google.android.play:integrity:1.4.0"
+  // Native provider replay with certificate pinning and handshake capture.
+  implementation "com.squareup.okhttp3:okhttp:4.12.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest>
+</manifest>