@latchway/react-native 0.0.0-bootstrap.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows Keep a Changelog, and releases will follow Semantic
+Versioning once package publication begins.
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-01
+
+### Changed
+
+- Added the root React Native installation-family component lifecycle:
+  descriptor-snapshotted prepare, replace, identity-free diagnostics, revoke,
+  and descriptor-bound family retirement, with Android reporting the iOS-only
+  operations explicitly unsupported.
+- Added a Debug-only App Intent integration proof that uses an independently
+  keyed delegated `react_native_ios` session, fully consumes a Responses request,
+  and binds its bounded shared-Keychain receipt to the root's exact-run challenge;
+  the Release fixture remains fail-closed with no AppExtensions linkage.
+- Physical React Native evidence now requires the authorization-first HTTP 403
+  `component_feature_not_granted` mapping for an ungranted feature instead of
+  the feature-enumerating HTTP 404 expectation.
+- Added Metro-runnable OpenAI, Vercel AI OpenAI/Anthropic, and LangChain
+  example consumers plus
+  a 16-case shared-ID React Native framework conformance matrix covering
+  Responses, Chat, embeddings, streaming, tools, structured output, errors,
+  retry dispatches, cancellation, and credential isolation, plus a separate
+  RN-only explicit-refresh, Anthropic Messages, and opaque-route cases.
+- Exposed the canonical non-secret `gatewayURL` and made `fetchFor` preserve
+  Latchway request correlation through the conventional `X-Request-ID` alias
+  without buffering response streams.
+- Removed the obsolete React Native CLI `podspecPath` override; React Native
+  0.82 now discovers the root podspec without an invalid-config warning.
+- Added iOS and Android production Metro bundles to the normal `pnpm check`
+  gate so Node-only framework imports fail before release.
+
+- Replaced JavaScript-owned authorization envelopes and network dispatch with
+  native URLSession/OkHttp dispatch, opaque response handles, pull-streamed
+  response chunks, cancellation, exact origin/path enforcement, and strict
+  safe response metadata. The removed `authorize` API is an intentional
+  security-boundary break; `fetchFor(feature)` supplies framework adapters
+  without exposing reusable credentials.
+- Advanced the exact JavaScript source pin to the reviewed final source commit
+  whose protected release evidence requires both Firebase App Check and
+  Cloudflare Turnstile.
+- Synchronized the release to contract 1.0.0, current wire protocol 2,
+  and the canonical installation-family and component-attestation binding v2
+  fixtures while preserving wire 1 in the core compatibility window.
+- Added an extension-process component client for iOS Action and SSO
+  extensions. It performs native App Attest step-up without a containing-app
+  identity callback and reports composite `delegated_direct_attested` trust;
+  Android reports direct component attestation as unsupported.
+
+### Candidate baseline
+
+#### Changed
+
+- Native consumers now pin the reviewed JavaScript, iOS, Android, Kotlin,
+  React Native, and core source commits through a machine-verified release
+  compatibility lock.
+- The example now includes complete React Native 0.82 New Architecture iOS and
+  Android hosts, including source-development overrides that are excluded from
+  published metadata.
+- The example provider stack now pins the native-build-verified React Native
+  Firebase 25.1.0, Firebase Apple 12.15.0, and Firebase Android BoM 34.15.0 set,
+  and repository installs use pnpm's hoisted linker for CocoaPods framework
+  compatibility.
+- The version 1 release candidate uses the exact reviewed JavaScript, iOS,
+  Android, and core source commits recorded by the synchronized compatibility
+  lock.
+- The Firebase example now selects the Firebase identity provider explicitly
+  and uses the currently supported OpenAI Responses route and request shape.
+- Automatic bodyless retries now require exact canonical, correlated
+  pre-dispatch Problem documents and unambiguous nonce semantics; ambiguous or
+  duplicate response metadata fails closed.
+- Provider credential headers are comprehensively stripped and decoded
+  credential-like query names fail before identity acquisition or dispatch.
+- Native `operation_indeterminate` failures preserve only a canonical
+  reconciliation identifier and reject missing, conflicting, or forbidden
+  operation metadata.
+
+### Added
+
+- Tag-triggered npm trusted publication with provenance, immutable release
+  package verification, draft GitHub releases, and published native consumer
+  gates.
+- Full contract-bundle verification and clean packed-package consumer gates.
+- Handwritten React Native client API with exact-origin authenticated fetch,
+  safe DPoP-nonce/session retries, cancellation, quota, and diagnostics.
+- TurboModule bridges backed by the Latchway iOS and Android SDKs for native
+  keys, attestation, DPoP, secure sessions, and installation revocation.
+- Canonical contract-vector tests, native-boundary checks, deterministic
+  package verification, CI, security documentation, and an example app.
+- Protocol-specific framework feature bindings; the primary example and
+  physical-device path use the setup wizard's OpenAI Responses feature.

package/LatchwayReactNative.podspec

@@ -0,0 +1,33 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |spec|
+  spec.name = "LatchwayReactNative"
+  spec.version = package["version"]
+  spec.summary = package["description"]
+  spec.homepage = package["homepage"]
+  spec.license = { type: "Apache-2.0", file: "LICENSE" }
+  spec.author = { "Latchway Contributors" => "security@latchway.dev" }
+  spec.source = { git: "https://github.com/Latchway/latchway-react-native-sdk.git", tag: "v#{spec.version}" }
+  spec.platforms = { ios: "15.0" }
+  spec.source_files = "ios/**/*.{h,m,mm,swift}"
+  # React Native's generated TurboModule spec is a C++ header. It is an
+  # implementation detail discovered by class name at runtime and must not be
+  # exposed through the framework umbrella module, where Clang may scan it as
+  # plain Objective-C and fail to resolve C++ standard-library headers.
+  spec.private_header_files = "ios/RCTNativeLatchway.h"
+  spec.requires_arc = true
+  spec.swift_version = "6.0"
+  spec.pod_target_xcconfig = {
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20",
+    "DEFINES_MODULE" => "YES",
+  }
+
+  spec.dependency "Latchway/AppAttest", "1.0.0"
+  if respond_to?(:install_modules_dependencies, true)
+    install_modules_dependencies(spec)
+  else
+    spec.dependency "React-Core"
+  end
+end

package/NOTICE

@@ -0,0 +1,7 @@
+Latchway React Native SDK
+Copyright 2026 Latchway contributors
+
+This product includes software developed by Latchway contributors.
+
+The Code of Conduct is adapted from Contributor Covenant version 2.1,
+licensed under the Creative Commons Attribution 4.0 International License.

package/README.md

@@ -1,5 +1,288 @@
-# @latchway/react-native
+# Latchway React Native SDK
 
-This is an inert, one-time namespace bootstrap package. It contains no runtime implementation and must not be used as an SDK dependency.
+`@latchway/react-native` gives iOS and Android applications one fetch-shaped API for a self-hosted Latchway gateway. The JavaScript layer never accepts an upstream AI-provider key. P-256 installation keys, DPoP signing, refresh-token storage, and platform attestation stay in the native Latchway SDKs.
 
-The maintained source repository is https://github.com/Latchway/latchway-react-native-sdk.git.
+> **Release status:** `1.0.0` is the intended stable source candidate, but has not yet been published. Use a workspace dependency or the archive produced by `pnpm pack:check`; do not assume an npm or native artifact exists until the release is announced.
+
+## Requirements
+
+- React Native 0.82.x with the New Architecture enabled
+- iOS 15 or newer, an App Attest-capable application entitlement, and `Latchway/AppAttest` 1.0.0
+- Android API 24 or newer, Play Integrity configured for the application, and the `dev.latchway` 1.0.0 artifacts
+- Node 24.19.0 and pnpm 10.15.0 for repository development
+
+The repository example additionally pins React Native Firebase 25.1.0, Firebase
+Apple SDK 12.15.0, and Firebase Android BoM 34.15.0. These are example identity
+provider dependencies, not runtime dependencies of the published Latchway
+package. Repository installs use pnpm's hoisted linker because React Native's
+CocoaPods static-framework exclusions require conventional `node_modules`
+paths.
+
+## Usage
+
+```ts
+import { createLatchwayClient } from "@latchway/react-native";
+
+const latchway = createLatchwayClient({
+  baseURL: "https://gateway.example.com",
+  // Generated by the Latchway Admin API; names/slugs are not accepted.
+  applicationID: "app_01J00000000000000000000000",
+  environment: "production",
+  getIdentityToken: async () => {
+    const token = await applicationIdentity.currentToken();
+    if (token === undefined) throw new Error("The user must sign in before calling Latchway.");
+    return token;
+  },
+  apple: {
+    rootKeychainAccessGroup: applicationConfiguration.rootPrivateKeychainAccessGroup,
+    legacySharedKeychainAccessGroups: applicationConfiguration.extensionSharedKeychainAccessGroups,
+  },
+  android: {
+    playIntegrityCloudProjectNumber: applicationConfiguration.googleCloudProjectNumber,
+  },
+});
+
+const response = await latchway.fetch("/v1/responses", {
+  method: "POST",
+  latchwayFeature: "habit_assistant",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    model: "assistant-default",
+    input: "Plan tomorrow",
+  }),
+});
+
+// OpenAI-compatible clients, Vercel OpenAI/Anthropic providers, and LangChain
+// adapters receive a normal fetch function permanently scoped to one feature.
+const habitAssistantFetch = latchway.fetchFor("habit_assistant");
+```
+
+`gatewayURL` exposes only the canonical non-secret gateway origin for framework
+constructors that require a base URL. `fetchFor` keeps the feature fixed,
+preserves the pull-driven response stream, and aliases the canonical
+`X-Latchway-Request-ID` as `X-Request-ID` for provider SDK error correlation.
+It never uses or replaces global `fetch`.
+
+The example contains runnable consumers for the exact locally tested versions
+of the official OpenAI JavaScript SDK (7.8.0), Vercel AI SDK (7.0.85 with
+`@ai-sdk/openai` 4.0.52 and `@ai-sdk/anthropic` 4.0.46), and LangChain
+JavaScript (`@langchain/openai` 1.5.10):
+
+```ts
+import {
+  createFrameworkConsumers,
+  runFrameworkConsumerSmoke,
+} from "./framework-consumers";
+
+const frameworks = createFrameworkConsumers(latchway, {
+  responses: "habit_responses",
+  chat: "habit_chat",
+  embeddings: "habit_embeddings",
+  anthropic: "habit_anthropic",
+});
+const result = await runFrameworkConsumerSmoke(frameworks, "Plan tomorrow");
+```
+
+These are compatibility consumers, not another LLM abstraction and not a
+blanket support claim for every package feature. They execute Responses, Chat
+Completions, embeddings, Anthropic Messages, and SSE through native networking.
+Each identifier above must name a separately configured Latchway feature whose
+protocol matches that request family; one feature cannot represent multiple
+protocols.
+Local conformance also covers tools, JSON-schema request preservation, errors,
+framework retry dispatches, explicit refresh, restricted opaque routes, and
+cancellation. Automatic pre-dispatch session recovery remains a native/device
+evidence claim. Audio, images, uploads, Realtime, browser-only middleware,
+streaming request bodies, and any framework path that does not honor the
+injected fetch remain unsupported here. The core
+`compatibility/frameworks.yaml` registry is the canonical release-status and
+version source; `react-native-fetch` remains experimental until hosted and
+physical-device gates pass.
+
+The official `@anthropic-ai/sdk` 0.120.0 package is not claimed as a React
+Native consumer. Its credential-chain module contains Node filesystem imports
+that Metro resolves even when a static constructor placeholder is supplied.
+The runnable Anthropic Messages path therefore uses the custom-fetch seam in
+`@ai-sdk/anthropic`; no Node-module shim or provider credential is bundled.
+
+`applicationID` is the generated application resource ID returned by the
+Admin API, not an app name, package/bundle identifier, or user-chosen slug.
+On iOS, `apple.rootKeychainAccessGroup` is required, fully resolved, and must
+be the first access group in the signed root application. Put every explicit
+extension-shared group in `legacySharedKeychainAccessGroups`; native code scans
+only exact root-record coordinates and surfaces `storage_unavailable` if stale
+implicit root state requires an explicit migration.
+
+Call `dispose()` when the owning application scope is destroyed. Disposal drops the in-memory native client; secure installation state remains available to later instances. `refresh()` explicitly rotates session credentials without exposing them. `revokeCurrentInstallation()` removes only the root installation and leaves independently provisioned family components addressable.
+
+The root application manages the complete native iOS component lifecycle with
+public descriptors:
+
+```ts
+import type { ReactNativeIOSComponent } from "@latchway/react-native";
+
+const appIntent: ReactNativeIOSComponent = {
+  definitionID: "habit_app_intent",
+  kind: "app_intent_extension",
+  keychainAccessGroup: "ABCDE12345.com.example.app.app-intent",
+  requestedFeatures: ["habit_assistant"],
+};
+
+const [prepared] = await latchway.prepareComponents([appIntent]);
+const replaced = await latchway.replaceComponent(appIntent);
+const localState = await latchway.componentDiagnostics(appIntent);
+await latchway.revokeComponent(appIntent);
+
+// On sign-out, native code retires every durably registered component.
+await latchway.revokeCurrentInstallationFamily();
+
+// The descriptor overload remains available for pre-registry legacy state.
+await latchway.revokeCurrentInstallationFamily([appIntent]);
+```
+
+Each descriptor contains exactly a definition ID, kind, fully resolved Keychain
+access group, and requested feature IDs. Its access group must be signed into
+both targets and listed in `apple.legacySharedKeychainAccessGroups`.
+Preparation, replacement, component revocation, and family retirement acquire
+the root identity only transiently inside native code. Root-side
+`componentDiagnostics` reads redacted local state without acquiring identity.
+Inputs are normalized before asynchronous work, and all component credentials,
+keys, grants, and sessions remain native. Before component-local state can be
+created, the iOS SDK records its validated, non-secret Keychain coordinate in
+the root application's private Keychain group. No-argument family retirement
+uses that durable registry across launches, removes entries only after both the
+component credential and key are erased, and retains failed entries for retry.
+The optional descriptor overload can additionally retire legacy component
+state that predates the registry.
+
+An independently executing iOS action or SSO extension whose containing app
+has already provisioned its component descriptor can inspect its isolated,
+independently keyed delegated-session state without moving credentials through
+JavaScript:
+
+```ts
+import { createLatchwayComponentClient } from "@latchway/react-native";
+
+const component = {
+  definitionID: "action_extension",
+  kind: "action_extension",
+  keychainAccessGroup: "ABCDE12345.com.example.app.action-extension",
+  requestedFeatures: ["habit_assistant"],
+} as const;
+
+// Construct this only in the JavaScript runtime hosted by the signed .appex.
+// It is deliberately separate from the containing app's root client.
+const componentClient = createLatchwayComponentClient({
+  baseURL: "https://gateway.example.com",
+  applicationID: "app_01J00000000000000000000000",
+  environment: "production",
+  component,
+  apple: {
+    rootKeychainAccessGroup: "ABCDE12345.com.example.app",
+    legacySharedKeychainAccessGroups: [component.keychainAccessGroup],
+  },
+});
+
+const componentState = await componentClient.diagnostics();
+// This is diagnostics only; RN v1 exposes no component request operation.
+```
+
+The access group must be fully resolved and present in both signed entitlement
+sets; build-setting expressions such as `$(AppIdentifierPrefix)` are rejected.
+Configuration fails unless the current process is an iOS `.appex`. The root
+application may establish App Attest only for itself; it must not attest for an
+extension, and an iOS application extension cannot call
+`DCAppAttestService.generateKey`. The extension client therefore constructs no
+App Attest provider. It has no identity callback or root API and retains only
+component-key and delegated-session isolation inside the pinned iOS SDK. The
+legacy `establishDirectAttestation()` entry point and direct-attestation trust
+source decoders remain for wire/API compatibility, but invocation fails closed
+with `attestation_unsupported`; their presence is not a claim that iOS can
+produce that state. Only redacted component diagnostics return. Android also
+fails closed for direct component attestation.
+
+The example's `AppIntents.appex` does not host a React Native JavaScript runtime.
+In Debug only, its separate CocoaPods target links `Latchway/AppExtensions`
+(Swift module `Latchway`) and constructs a native `LatchwayExtensionClient` with
+runtime `react_native_ios`. After the root prepares the descriptor, the intent
+publishes a nonsecret exact-run challenge in the shared Keychain immediately
+before its waiting marker. The intent captures that challenge before creating
+its client, proves an independently keyed delegated session, fully consumes one
+successful bounded Responses body, rechecks that the challenge is still current,
+and then echoes it in a bounded shared-Keychain receipt. Resume accepts only the
+native-captured exact run and deletes both challenge and receipt. The receipt
+contains only the nonsecret `dev_<32hex>` run nonce, status booleans, and a
+timestamp; it contains no component, installation, or user IDs, tokens, proofs,
+request body, or response body. The intent never receives the root identity or
+root-private Keychain state.
+
+The Release fixture has no AppExtensions dependency or executable Latchway
+client path and its intent fails closed with an unsupported error. Both variants
+retain private-first/shared-second root entitlements and a shared-only extension
+entitlement. The local Debug intent is integration proof only and does not
+broaden or replace the protected Release physical-evidence claim.
+
+Equivalent clients in one JavaScript runtime share one native client and contract compatibility check. Native SDK actors/mutexes own session establishment and refresh single-flight. JavaScript never clones or replays an authenticated request; any bounded pre-dispatch retry is exclusively a native transport decision. Android installs the locked Latchway OkHttp interceptor, origin guard, and authenticator. iOS uses the locked feature transport, whose private redirect-rejecting URL session classifies at most 64 KiB of one canonical pre-dispatch rejection before its single safe retry.
+
+The fetch surface is intentionally bounded. It dispatches only to the configured origin. The structured paths `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, and `/v1/messages` are POST-only. Opaque integrations may use GET, POST, PUT, PATCH, or DELETE only below `/proxy/{feature}/<safe-relative-path>` with an exact feature match and no query; empty segments, traversal, encoded separators, backslashes, and absolute-URL-shaped suffixes fail closed. Fragments and credential-shaped query names fail before identity acquisition. Request bodies are buffered to cross the New Architecture bridge and are limited to 8 MiB. Response bodies remain pull-streamed in chunks with cancellation and backpressure, while native retains the network task and credential-bearing request. Redirects are refused, and JavaScript receives only status, a strict safe-header allowlist, an opaque response handle, and response bytes.
+
+The compatible subset guarantees request method, headers, body, `AbortSignal`, response status/headers, and a pull-driven `ReadableStream`. It does not provide browser cookie or cache modes, service-worker behavior, redirect following, streaming request uploads, response trailers, or native `Response.url`/`redirected` metadata. Frameworks must expose a custom-fetch hook and use one of the allowed data-plane paths; browser-only framework features remain unsupported in React Native. A provider SDK's required placeholder authorization header is discarded, never forwarded. Consult the released framework compatibility registry before claiming support for a specific OpenAI, Vercel AI, or LangChain version.
+
+`errorFromResponse` is re-exported for explicit conversion of a returned problem response. Every resulting `LatchwayError.documentationURL` uses `https://docs.latchway.dev/errors/<hyphenated-code>`, and a server-originated native failure is accepted only when its documentation URL matches its code exactly. An `operation_indeterminate` error includes a required canonical `operationID`; preserve it with the request ID and reconcile the operation before deciding whether to retry.
+
+## Security boundary
+
+The root client's only application credential sent into the TurboModule is the external identity JWT returned by `getIdentityToken`, and it is retained only for the duration of a native operation that requires identity. Root component descriptors and extension-client descriptors contain only definition ID, kind, fully resolved Keychain access group, and requested feature IDs. Root-side and extension-side component diagnostics do not acquire identity. The separate component client cannot acquire the containing app's native root lease. The bridge does not accept App Attest objects, Play Integrity tokens, `client_data_hash`, request hashes, DPoP private keys, access tokens, or refresh tokens as inputs. Native code attaches Authorization and DPoP, sends the request, and owns the response stream. Authorization, DPoP, access tokens, refresh tokens, private keys, attestation evidence, and reusable credentials never return to JavaScript.
+
+Caller-supplied `Authorization`, `DPoP`, cookies, API-key headers, transport-owned headers, and Latchway protocol headers are removed before the request crosses the bridge. This permits SDKs that require a placeholder API-key option without forwarding that placeholder or a real provider credential. Provider-credential query names are rejected, including percent-encoded and case-varied names. Insecure HTTP is limited to explicitly enabled loopback conformance.
+
+See [native installation](docs/native-installation.md), [security details](docs/security.md), and [architecture](docs/architecture.md).
+Release ordering and immutable publication gates are in [releasing](docs/releasing.md).
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check
+pnpm verify:compatibility
+pnpm pack:check
+pnpm verify:reproducible
+```
+
+For a release-candidate checkout, `pnpm verify:compatibility --sources` also
+requires the exact core, JavaScript, iOS, and Android commits recorded in
+`release-compatibility.json`. `pnpm verify:bundle -- /path/to/latchway-contract-<version>.tar.gz`
+verifies the complete immutable contract archive, and `pnpm consumer:check`
+installs the packed JavaScript and React Native archives in a clean temporary
+consumer before compiling it.
+
+`pnpm codegen:check` parses the handwritten TurboModule spec and regenerates both platform surfaces in a disposable directory. Node tests use the explicit `@latchway/react-native/testing` bridge; production applications must never install a test bridge.
+
+`pnpm example:bundle:check` creates production Metro bundles for both iOS and
+Android in a disposable directory. It is part of `pnpm check` so framework
+packages that typecheck but import Node-only modules fail the normal source
+gate.
+
+The example in [`example`](example/README.md) demonstrates Firebase Authentication, environment-supplied deployment configuration, raw fetch, real framework consumers, quota, diagnostics, and lifecycle cleanup without storing or logging credentials.
+
+## Contract lock
+
+The final version 1 source candidate consumes released contract checkpoint `1.0.0`,
+current wire protocol `2` (with wire `1` retained in the core compatibility
+window), core commit `d260e3d7485e9e1487b5e03922b79c7089d94ce2`, and
+bundle SHA-256
+`4866aec1ff70e78d70f07847448161c2b59970fe102d95393b051444536d29a4`.
+Core plus all four SDK locks and fixtures are synchronized. This is source
+compatibility evidence, not a claim that the npm package or native dependencies
+have been published. All gates read `release-compatibility.json` and
+`contract.lock`, so later compatible releases do not require rewriting CI.
+`pnpm verify:contracts` checks the active lock and vendored canonical fixtures
+byte-for-byte, including the installation-family and component-attestation
+binding v2 fixtures. The
+promotion-dispatched release workflow still refuses
+publication until exact native registry, provenance, physical-device, and
+immutable-release evidence passes.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/SECURITY.md

@@ -0,0 +1,69 @@
+# Security Policy
+
+## Release status
+
+Latchway React Native SDK is implemented but remains pre-release. Do not depend
+on an unpublished checkout as a supported production security boundary; use a
+published version whose native compatibility entry is recorded.
+
+Security fixes will target supported releases once the support matrix is
+established. The unreleased branch may change without compatibility guarantees.
+
+## Reporting a vulnerability
+
+Use GitHub private vulnerability reporting for this repository. If that feature
+is unavailable, contact the Latchway organization maintainers privately before
+sharing details. Do not open a public issue for a suspected vulnerability.
+
+Do not include live identity tokens, refresh tokens, DPoP proofs, attestation
+evidence, private keys, signing assets, provider credentials, or user data in a
+report. Revoke exposed credentials before continuing.
+
+A useful report includes:
+
+- The affected revision or released version
+- The React Native, iOS or Android, and device versions
+- Reproduction steps using synthetic or redacted data
+- The expected and observed security behavior
+- Impact, prerequisites, and any known mitigations
+
+## Security-sensitive scope
+
+Treat changes to TurboModule boundaries, native-to-JavaScript data exposure,
+installation state, native SDK version resolution, request retry/replay
+behavior, token redaction, and diagnostics as security-sensitive. Hardware keys,
+attestation, DPoP signing, refresh-token storage, and installation state belong
+to the native SDKs and must not be reimplemented in JavaScript or C++ here.
+
+The application-owned external identity token crosses the TurboModule boundary
+only for the duration of a native operation. Private keys, refresh tokens, raw
+attestation evidence, attestation challenge bindings, and native session state
+must never enter JavaScript. Access tokens and DPoP proofs also remain native:
+the iOS URL session or Android OkHttp client attaches them, dispatches the
+exact-origin request, rejects redirects, and retains the response handle.
+JavaScript receives only safe response metadata and pull-streamed response
+bytes. There is no public or TurboModule authorization-envelope API.
+
+The SDK must never accept an upstream AI-provider secret. Latchway server or
+native-SDK vulnerabilities should be reported to their owning repository, with
+a cross-reference here when bridge behavior is involved.
+
+## Dependency vulnerability gate
+
+CI and release jobs bind `package.json`, `pnpm-lock.yaml`, and the scanner policy
+scripts to the exact candidate commit before scanning. They install the
+checksum-and-size-pinned OSV-Scanner 2.4.0 binary, download the public npm
+advisory database, and then match dependencies locally with network resolution
+disabled. No package inventory or repository path is sent to OSV.dev. Native
+SDK dependency graphs are scanned in their owning iOS and Android repositories.
+
+`pnpm security:dependencies` reproduces the gate. Critical, high, or
+unknown-severity findings fail the candidate; lower-severity findings remain
+visible for routine remediation. Scanner errors, malformed output, an empty
+inventory, or a missing offline database also fail closed.
+
+## Disclosure
+
+Allow maintainers a reasonable opportunity to investigate and coordinate a fix
+before public disclosure. Good-faith research that avoids privacy violations,
+service disruption, and access beyond what is necessary is welcome.

package/android/build.gradle.kts

@@ -0,0 +1,62 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+    id("com.facebook.react")
+}
+
+kotlin {
+    compilerOptions { jvmTarget.set(JvmTarget.JVM_17) }
+}
+
+group = "dev.latchway"
+version = "1.0.0"
+
+react {
+    root.set(file(".."))
+    reactNativeDir.set(file("../node_modules/react-native"))
+    codegenDir.set(file("../node_modules/@react-native/codegen"))
+    libraryName.set("LatchwayReactNativeSpec")
+    codegenJavaPackageName.set("dev.latchway.reactnative")
+}
+
+android {
+    namespace = "dev.latchway.reactnative"
+    // The exact native 1.0.0 AAR metadata requires API 37 consumers.
+    compileSdk = 37
+
+    defaultConfig {
+        minSdk = 24
+        consumerProguardFiles("consumer-rules.pro")
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    lint {
+        abortOnError = true
+        warningsAsErrors = true
+        // These versions are compatibility inputs, not opportunistic upgrades.
+        // scripts/verify-compatibility.mjs enforces the reviewed exact lock.
+        disable += setOf("AndroidGradlePluginVersion", "NewerVersionAvailable")
+    }
+
+    testOptions {
+        unitTests.isIncludeAndroidResources = true
+    }
+}
+
+dependencies {
+    // A real host's React plugin forces this to the installed 0.82.x patch. The
+    // exact baseline keeps standalone package-consumer builds deterministic.
+    implementation("com.facebook.react:react-android:0.82.0")
+    implementation("dev.latchway:latchway-okhttp:1.0.0")
+    implementation("dev.latchway:latchway-play-integrity:1.0.0")
+
+    testImplementation("junit:junit:4.13.2")
+    testImplementation("org.robolectric:robolectric:4.14.1")
+    testImplementation("com.squareup.okhttp3:mockwebserver:5.3.0")
+}

package/android/consumer-rules.pro

@@ -0,0 +1,2 @@
+-keep class dev.latchway.reactnative.NativeLatchwayModule { *; }
+-keep class dev.latchway.reactnative.LatchwayReactNativePackage { *; }

package/android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,9 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip
+distributionSha256Sum=20f1b1176237254a6fc204d8434196fa11a4cfb387567519c61556e8710aed78
+networkTimeout=10000
+retries=0
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

package/android/gradle.properties

@@ -0,0 +1,4 @@
+android.useAndroidX=true
+kotlin.code.style=official
+org.gradle.jvmargs=-Xmx2g -Dfile.encoding=UTF-8
+android.suppressUnsupportedCompileSdk=37,37.0