@appattest/react-native 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bault LLC
+
+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/README.md

@@ -0,0 +1,150 @@
+# @appattest/react-native
+
+React Native bridge for [AppAttest](https://www.appattest.dev) — App-Attest-gated
+secret delivery for iOS.
+
+> **Status: pre-release.** Ships in lockstep with the Swift SDK at
+> `v0.1.0`. Not yet published to npm.
+> The JS/TS API shape is stable.
+
+## Platform support
+
+- **iOS 17+** — full support. Uses Apple's `DCAppAttestService` via the
+  native AppAttest Swift SDK.
+- **Android / other** — not supported. Apple's App Attest is iOS-only and
+  there is no equivalent on other platforms; the native module is not
+  registered outside iOS.
+
+## Install
+
+> Not yet on npm — publication is upcoming. Until then the bridge ships as
+> source in `bridges/react-native` of the SDK repository. Once published:
+
+```bash
+npm install @appattest/react-native
+cd ios && pod install
+```
+
+The iOS pod depends on `AppAttestObjC` (a companion pod from the same
+monorepo). That's wired automatically through the pod's `s.dependency`.
+
+## Quick start
+
+```tsx
+import { AppAttest, useSecret } from '@appattest/react-native';
+
+// Once, at app launch:
+AppAttest.start();
+
+// In any component — re-renders when secrets land:
+function Chat() {
+  const openaiKey = useSecret('OPENAI_API_KEY');
+  if (!openaiKey) return <Splash />;
+  return <ChatView apiKey={openaiKey} />;
+}
+```
+
+Outside components:
+
+```ts
+await AppAttest.waitForReady();
+const key = await AppAttest.getSecret('OPENAI_API_KEY'); // string | null
+const all = await AppAttest.getAllSecrets();             // Record<string, string>
+```
+
+`start()` is fire-and-forget: the first launch attests the device once
+(persists across launches), then syncs secrets; later launches hydrate
+from the Keychain and re-sync in the background. Foreground re-entry
+re-syncs automatically — your app does no lifecycle wiring.
+
+## State
+
+```ts
+import { AppAttest, useAppAttestState } from '@appattest/react-native';
+
+const state = useAppAttestState(); // { name, error? }, re-renders on change
+
+// or imperatively:
+const s = await AppAttest.getState();
+const unsubscribe = AppAttest.addStateListener((s) => console.log(s.name));
+```
+
+`state.name` is one of `'initializing' | 'attesting' | 'syncing' | 'ready' |
+'subscription_required' | 'credits_required' | 'unavailable'`. The
+non-`ready` terminal states carry `state.error`.
+
+**End-user-facing apps:** show a generic "temporarily unavailable" notice
+for the non-`ready` terminal states. **Developer / staff builds:** log the
+full error (including `actionUrl`) so the developer knows whether to
+subscribe, top up, or investigate.
+
+## Refresh & recovery
+
+```ts
+await AppAttest.retry();            // re-run the sync (no re-attestation)
+await AppAttest.invalidateBundle(); // drop the cached bundle, force a fresh sync
+await AppAttest.reset();            // full wipe; next start() re-attests
+```
+
+`retry()` recovers from transient failures. `invalidateBundle()` forces
+fresh secret bytes when you don't want to wait for the next rotation
+pickup. `reset()` is the nuclear option, for sign-out / data-clearing flows.
+
+## Debug mode (simulator, tests, CI)
+
+The simulator can't produce a real App Attest attestation. Use local stubs:
+
+```ts
+if (__DEV__) {
+  await AppAttest.setDebugMode('local', {
+    OPENAI_API_KEY: 'sk-test-stub',
+  });
+}
+AppAttest.start();
+```
+
+Pass `null` to return to real attestation. The native debug surface is
+`#if DEBUG`-gated — physically absent from Release builds, which always
+run real attestation; calling it there rejects with
+`debug_mode_release_blocked`.
+
+Dev builds on **real devices** don't need debug mode — they attest for
+real and read the sandbox bucket (below).
+
+## Buckets (sandbox vs production)
+
+There is no environment configuration. Apple's AAGUID in each attestation
+determines the bucket server-side: dev / TestFlight builds read the
+**sandbox** secrets column; App Store builds read **production**. Same
+code in both, no flags.
+
+## Error handling
+
+All methods reject with `AppAttestError` (`code`, plus `subscribeUrl` /
+`topupUrl` / `actionUrl` on the billing cases):
+
+```ts
+import { AppAttest, AppAttestError, ErrorCode } from '@appattest/react-native';
+
+try {
+  await AppAttest.waitForReady();
+} catch (e) {
+  if (e instanceof AppAttestError && e.code === ErrorCode.SubscriptionRequired) {
+    console.log('project needs a subscription:', e.actionUrl);
+  }
+}
+```
+
+| Code | Meaning |
+|------|---------|
+| `subscription_required` | Project subscription not active (`subscribeUrl`). |
+| `credits_required` | Allowance exhausted and balance empty (`topupUrl`). |
+| `attestation_rejected` | Apple or AppAttest rejected this install — terminal until reinstall. |
+| `service_unavailable` | Temporary service condition; retryable (the SDK backs off automatically). |
+| `network` | Device-side transport failure; retryable. |
+| `debug_mode_release_blocked` | `setDebugMode` called in a Release build. |
+| `invalid_argument` | Malformed call input. |
+
+## License
+
+MIT © 2026 Bault LLC. See [LICENSE](LICENSE).

package/ios/AppAttestModule.mm

@@ -0,0 +1,52 @@
+// AppAttestModule.mm — React Native module registration macros.
+//
+// Exposes the Swift class `AppAttestModule` to RN as `RNAppAttest`
+// (matches the JS-side TurboModuleRegistry.getEnforcing<Spec>('RNAppAttest')).
+// Each RCT_EXTERN_METHOD declares a method the RN runtime may invoke and
+// its argument shape. Keep in lockstep with ../src/NativeAppAttest.ts.
+
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+
+#if __has_include(<React/RCTBridgeModule.h>)
+@interface RCT_EXTERN_REMAP_MODULE(RNAppAttest, AppAttestModule, RCTEventEmitter)
+
+RCT_EXTERN_METHOD(start:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(waitForReady:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(retry:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(reset:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(invalidateBundle:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getSecret:(NSString *)name
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getAllSecrets:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getState:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(setDebugMode:(nullable NSString *)name
+                  stubs:(nullable NSDictionary *)stubs
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+// setApiBaseUrl is not exposed — base URL is hardcoded.
+
++ (BOOL)requiresMainQueueSetup
+{
+  return NO;
+}
+
+@end
+#endif

package/ios/AppAttestModule.swift

@@ -0,0 +1,173 @@
+// AppAttestModule.swift — iOS native module for @appattest/react-native.
+//
+// Adapter between React Native's module system and the AppAttest SDK's
+// @objc facade (AppAttestObjC). Every method matches the TurboModule spec
+// in ../src/NativeAppAttest.ts.
+//
+// Errors: rejection bodies carry { code, message,
+// subscribeUrl? | topupUrl? }. The 402 envelope key matches the code:
+// `subscription_required` → subscribeUrl; `credits_required` → topupUrl.
+//
+// State events: emitted on `stateChanged` whenever the SDK's state
+// transitions. JS hooks subscribe via the `addStateListener` wrapper.
+
+import Foundation
+import AppAttestObjC
+import React
+
+@objc(AppAttestModule)
+final class AppAttestModule: RCTEventEmitter {
+
+    private let client = AppAttestObjCClient.shared
+    private var stateToken: AppAttestObservationToken?
+    private var hasJSListeners = false
+
+    override static func requiresMainQueueSetup() -> Bool { false }
+
+    // MARK: - Event emitter
+
+    override func supportedEvents() -> [String]! { ["stateChanged"] }
+
+    override func startObserving() {
+        hasJSListeners = true
+        stateToken?.invalidate()
+        stateToken = client.addStateObserver { [weak self] state in
+            guard let self else { return }
+            self.sendEvent(withName: "stateChanged", body: Self.encodeState(state))
+        }
+    }
+
+    /// Encode an `AppAttestState` for the JS bridge — flattens the nested
+    /// NSError userInfo into a JSON-safe dict. Forwards every 402 URL key
+    /// (`subscribeUrl`, `topupUrl`); JS picks whichever matches its current
+    /// state.
+    private static func encodeState(_ state: AppAttestState) -> [String: Any] {
+        var body: [String: Any] = ["name": state.name]
+        if let err = state.error {
+            var errBody: [String: Any] = [
+                "code": (err.userInfo["code"] as? String) ?? "internal_error",
+                "message": (err.userInfo["message"] as? String) ?? err.localizedDescription
+            ]
+            if let url = err.userInfo["subscribeUrl"] as? String { errBody["subscribeUrl"] = url }
+            if let url = err.userInfo["topupUrl"] as? String { errBody["topupUrl"] = url }
+            body["error"] = errBody
+        }
+        return body
+    }
+
+    override func stopObserving() {
+        hasJSListeners = false
+        stateToken?.invalidate()
+        stateToken = nil
+    }
+
+    // MARK: - Lifecycle
+
+    @objc func start(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        client.start()
+        resolve(NSNull())
+    }
+
+    @objc func waitForReady(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        client.waitForReady { error in
+            Self.complete((), error: error, resolve: resolve, reject: reject)
+        }
+    }
+
+    @objc func retry(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        client.retry()
+        resolve(NSNull())
+    }
+
+    @objc func reset(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        client.reset { error in
+            Self.complete((), error: error, resolve: resolve, reject: reject)
+        }
+    }
+
+    @objc func invalidateBundle(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        client.invalidateBundle()
+        resolve(NSNull())
+    }
+
+    // MARK: - Reads
+
+    @objc func getSecret(
+        _ name: NSString,
+        resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        DispatchQueue.main.async {
+            let value = self.client.secret(forKey: name as String)
+            resolve(value as Any? ?? NSNull())
+        }
+    }
+
+    @objc func getAllSecrets(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        DispatchQueue.main.async {
+            resolve(self.client.allSecrets())
+        }
+    }
+
+    @objc func getState(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        DispatchQueue.main.async {
+            resolve(Self.encodeState(self.client.currentState()))
+        }
+    }
+
+    // MARK: - Configuration
+
+    @objc func setDebugMode(
+        _ name: NSString?,
+        stubs: NSDictionary?,
+        resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        let dict = (stubs as? [String: String]) ?? [:]
+        client.setDebugMode(name as String?, stubs: dict.isEmpty ? nil : dict) { error in
+            Self.complete((), error: error, resolve: resolve, reject: reject)
+        }
+    }
+
+    // setApiBaseUrl is not exposed — the base URL is hardcoded in the
+    // Swift SDK (https://edge.appattest.dev). No way to point at any
+    // other URL from a published binary; that's the security model.
+
+    // MARK: - Promise plumbing
+
+    private static func complete<T>(
+        _ value: T,
+        error: NSError?,
+        resolve: RCTPromiseResolveBlock,
+        reject: RCTPromiseRejectBlock
+    ) {
+        if let error {
+            let code = (error.userInfo["code"] as? String) ?? "internal_error"
+            let message = (error.userInfo["message"] as? String) ?? error.localizedDescription
+            reject(code, message, error)
+        } else {
+            resolve(value)
+        }
+    }
+}

package/ios/AppAttestReactNative.podspec

@@ -0,0 +1,34 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name             = 'AppAttestReactNative'
+  s.version          = package['version']
+  s.summary          = package['description']
+  s.homepage         = 'https://github.com/AppAttest/appAttest-sdk'
+  s.license          = 'MIT'
+  s.author           = { 'AppAttest' => 'support@appattest.dev' }
+  s.source           = {
+    :git => 'https://github.com/AppAttest/appAttest-sdk.git',
+    :tag => "v#{s.version}"
+  }
+
+  s.platforms = { :ios => '17.0' }
+  s.swift_versions = ['5.9']
+
+  s.source_files = '**/*.{swift,m,mm,h}'
+
+  # Depend on the Swift SDK's Objective-C facade. The facade transitively
+  # pulls in `AppAttest` (the pure Swift module).
+  s.dependency 'AppAttestObjC', "= #{s.version}"
+
+  # React Native core — this is the standard pattern from @react-native/
+  # official modules. `install_modules_dependencies` is exposed by RN's
+  # podspec helpers and ensures new-arch / TurboModule deps are wired.
+  if respond_to?(:install_modules_dependencies, true)
+    install_modules_dependencies(s)
+  else
+    s.dependency 'React-Core'
+  end
+end

package/lib/commonjs/NativeAppAttest.js

@@ -0,0 +1,20 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _reactNative = require("react-native");
+/**
+ * TurboModule spec for the AppAttest iOS native module.
+ *
+ * Codegen reads this file. The shape is restricted to what TurboModule
+ * codegen can serialize (primitives, Object, arrays of primitives,
+ * Promises, null).
+ *
+ * Errors: rejection objects carry `{ code, message,
+ * subscribeUrl?, topupUrl? }`. The TS wrapper in `index.ts` translates
+ * these into `AppAttestError`.
+ */
+var _default = exports.default = _reactNative.TurboModuleRegistry.getEnforcing('RNAppAttest');
+//# sourceMappingURL=NativeAppAttest.js.map

package/lib/commonjs/NativeAppAttest.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_reactNative","require","_default","exports","default","TurboModuleRegistry","getEnforcing"],"sourceRoot":"../../src","sources":["NativeAppAttest.ts"],"mappings":";;;;;;AAYA,IAAAA,YAAA,GAAAC,OAAA;AAZA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAVA,IAAAC,QAAA,GAAAC,OAAA,CAAAC,OAAA,GAqEeC,gCAAmB,CAACC,YAAY,CAAO,aAAa,CAAC","ignoreList":[]}