@gfean/react-native-bundle-drop 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/BundleDrop.podspec +17 -20
  2. package/README.md +60 -1
  3. package/android/build.gradle +4 -0
  4. package/android/src/main/java/com/bundledrop/BundleDropFileOps.kt +20 -0
  5. package/android/src/main/java/com/bundledrop/BundleDropModule.kt +4 -1
  6. package/android/src/main/java/com/bundledrop/BundleDropNativePaths.kt +5 -1
  7. package/docs/native-fingerprint.md +211 -0
  8. package/expo/android/build.gradle +61 -56
  9. package/ios/BundleDropLocator.swift +12 -0
  10. package/ios/BundleDropModule.swift +31 -13
  11. package/ios/BundleDropReactContent.swift +54 -0
  12. package/ios/BundleDropStartupRecovery.swift +48 -2
  13. package/ios/BundleDropStartupRecoveryAdapter.swift +87 -30
  14. package/lib/CLI/cli.js +9 -0
  15. package/lib/CLI/scripts/doctor.js +18 -7
  16. package/lib/CLI/scripts/expo/configure-expo.js +8 -3
  17. package/lib/CLI/scripts/fingerprint-cli.d.ts +12 -0
  18. package/lib/CLI/scripts/fingerprint-cli.js +36 -0
  19. package/lib/CLI/scripts/native/write-runtime-identity.js +3 -1
  20. package/lib/CLI/scripts/sight-ota.js +12 -3
  21. package/lib/CLI/scripts/upload-cli.d.ts +1 -0
  22. package/lib/CLI/scripts/upload-cli.js +35 -0
  23. package/lib/context.js +9 -1
  24. package/lib/errors.d.ts +2 -1
  25. package/lib/errors.js +2 -1
  26. package/lib/expo/buildIdentity.d.ts +1 -1
  27. package/lib/expo/buildIdentity.js +3 -0
  28. package/lib/expo/runtimeVersion.d.ts +10 -0
  29. package/lib/expo/runtimeVersion.js +11 -9
  30. package/lib/fingerprint/client.d.ts +5 -0
  31. package/lib/fingerprint/client.js +21 -0
  32. package/lib/fingerprint/collect.d.ts +3 -0
  33. package/lib/fingerprint/collect.js +116 -0
  34. package/lib/fingerprint/config.d.ts +14 -0
  35. package/lib/fingerprint/config.js +60 -0
  36. package/lib/fingerprint/normalizeBuildNumber.d.ts +4 -0
  37. package/lib/fingerprint/normalizeBuildNumber.js +55 -0
  38. package/lib/fingerprint/normalizeIosBuildNumber.d.ts +4 -0
  39. package/lib/fingerprint/normalizeIosBuildNumber.js +62 -0
  40. package/lib/fingerprint/types.d.ts +29 -0
  41. package/lib/fingerprint/types.js +2 -0
  42. package/lib/fingerprint/worker.d.ts +1 -0
  43. package/lib/fingerprint/worker.js +24 -0
  44. package/lib/fs/installedReportHistory.d.ts +2 -0
  45. package/lib/fs/installedReportHistory.js +55 -0
  46. package/lib/loadConfig.d.ts +6 -2
  47. package/lib/manager/downloadAndInstall.d.ts +1 -0
  48. package/lib/manager/downloadAndInstall.js +4 -0
  49. package/lib/manager/pendingRollback.d.ts +11 -0
  50. package/lib/manager/pendingRollback.js +54 -0
  51. package/lib/manager/reporting.d.ts +1 -0
  52. package/lib/manager/reporting.js +23 -6
  53. package/lib/manager/updateState.d.ts +3 -0
  54. package/lib/manager/updateState.js +1 -0
  55. package/lib/metro.js +3 -0
  56. package/lib/native/bundleDropNative.d.ts +2 -0
  57. package/lib/native/bundleDropNative.js +15 -5
  58. package/lib/patch-engine/installFromPatchSet.js +1 -1
  59. package/lib/patch-engine/patchTransport.d.ts +2 -1
  60. package/lib/patch-engine/patchTransport.js +4 -2
  61. package/lib/runtime/service.d.ts +2 -1
  62. package/lib/runtime/service.js +77 -22
  63. package/lib/scripts/bundle.js +10 -0
  64. package/lib/scripts/canonicalArtifact.d.ts +3 -0
  65. package/lib/scripts/canonicalArtifact.js +3 -1
  66. package/lib/scripts/exportProject.js +11 -0
  67. package/lib/scripts/nativeBuildNumber.d.ts +9 -0
  68. package/lib/scripts/nativeBuildNumber.js +110 -0
  69. package/lib/scripts/runtimeCompatibilityMetadata.d.ts +10 -0
  70. package/lib/scripts/runtimeCompatibilityMetadata.js +13 -0
  71. package/package.json +25 -11
  72. package/third_party/expo-fingerprint/LICENSE +22 -0
  73. package/third_party/expo-fingerprint/NOTICE +5 -0
  74. package/third_party/expo-fingerprint/PROVENANCE.md +41 -0
  75. package/third_party/expo-fingerprint/build/Config.js +122 -0
  76. package/third_party/expo-fingerprint/build/Dedup.js +89 -0
  77. package/third_party/expo-fingerprint/build/ExpoConfig.js +93 -0
  78. package/third_party/expo-fingerprint/build/ExpoConfigLoader.js +201 -0
  79. package/third_party/expo-fingerprint/build/ExpoResolver.js +84 -0
  80. package/third_party/expo-fingerprint/build/Fingerprint.js +111 -0
  81. package/third_party/expo-fingerprint/build/Fingerprint.types.js +3 -0
  82. package/third_party/expo-fingerprint/build/Options.js +140 -0
  83. package/third_party/expo-fingerprint/build/Presets.js +62 -0
  84. package/third_party/expo-fingerprint/build/ProjectWorkflow.js +163 -0
  85. package/third_party/expo-fingerprint/build/Sort.js +46 -0
  86. package/third_party/expo-fingerprint/build/hash/FileHookTransform.js +42 -0
  87. package/third_party/expo-fingerprint/build/hash/Hash.js +264 -0
  88. package/third_party/expo-fingerprint/build/hash/ReactImportsPatcher.js +344 -0
  89. package/third_party/expo-fingerprint/build/index.js +23 -0
  90. package/third_party/expo-fingerprint/build/sourcer/AutolinkingConfig.js +130 -0
  91. package/third_party/expo-fingerprint/build/sourcer/Bare.js +231 -0
  92. package/third_party/expo-fingerprint/build/sourcer/Expo.js +376 -0
  93. package/third_party/expo-fingerprint/build/sourcer/Packages.js +54 -0
  94. package/third_party/expo-fingerprint/build/sourcer/PatchPackage.js +22 -0
  95. package/third_party/expo-fingerprint/build/sourcer/SourceSkips.js +79 -0
  96. package/third_party/expo-fingerprint/build/sourcer/Sourcer.js +58 -0
  97. package/third_party/expo-fingerprint/build/sourcer/Utils.js +129 -0
  98. package/third_party/expo-fingerprint/build/types/module.d.js +2 -0
  99. package/third_party/expo-fingerprint/build/utils/Concurrency.js +47 -0
  100. package/third_party/expo-fingerprint/build/utils/Env.js +28 -0
  101. package/third_party/expo-fingerprint/build/utils/Path.js +161 -0
  102. package/third_party/expo-fingerprint/build/utils/Predicates.js +6 -0
  103. package/third_party/expo-fingerprint/build/utils/Profile.js +41 -0
  104. package/third_party/expo-fingerprint/build/utils/Spawn.js +38 -0
  105. package/third_party/expo-fingerprint/build/utils/SpawnIPC.js +28 -0
  106. package/third_party/expo-fingerprint/scheme-1-contract.json +132 -0
  107. package/third_party/expo-fingerprint/upstream-files.json +37 -0
@@ -2,15 +2,20 @@ require "digest"
2
2
  require "fileutils"
3
3
  require "json"
4
4
  require "open3"
5
+ require "pathname"
5
6
  require "shellwords"
6
7
 
7
8
  bundle_drop_native_runtime_identity_resource = lambda do
8
9
  return nil unless defined?(Pod::Config)
9
10
 
10
- project_root = File.expand_path("..", Pod::Config.instance.installation_root.to_s)
11
+ project_root = File.realpath(File.expand_path("..", Pod::Config.instance.installation_root.to_s))
12
+ package_root = File.realpath(__dir__)
13
+ # Relocation must not change the podspec checksum. Relative consumer paths also
14
+ # keep different apps using one shared SDK package in separate resource slots.
15
+ project_relative_root = Pathname.new(project_root).relative_path_from(Pathname.new(package_root)).to_s
11
16
  config_path = File.join(project_root, "bundle.drop.config.js")
12
17
  writer_path = File.join(
13
- __dir__,
18
+ package_root,
14
19
  "lib",
15
20
  "CLI",
16
21
  "scripts",
@@ -27,10 +32,10 @@ bundle_drop_native_runtime_identity_resource = lambda do
27
32
  "build",
28
33
  "generated",
29
34
  "runtime-identity",
30
- Digest::SHA256.hexdigest(project_root)[0, 16],
35
+ Digest::SHA256.hexdigest(project_relative_root)[0, 16],
31
36
  "bundle-drop-build-identity.json"
32
37
  )
33
- output_path = File.join(__dir__, resource_path)
38
+ output_path = File.join(package_root, resource_path)
34
39
 
35
40
  if File.file?(config_path)
36
41
  stdout, stderr, status = Open3.capture3(
@@ -65,21 +70,12 @@ bundle_drop_native_runtime_identity_resource = lambda do
65
70
  }) + "\n"
66
71
  )
67
72
  end
68
- resource_path
73
+ { :resource_path => resource_path, :project_relative_root => project_relative_root }
69
74
  end
70
75
 
71
76
  package = JSON.parse(File.read(File.join(__dir__, "package.json")))
72
77
  native_version = package["nativeVersion"] || package["version"]
73
- native_runtime_identity_resource = bundle_drop_native_runtime_identity_resource.call
74
- native_runtime_identity_project_root = if native_runtime_identity_resource
75
- File.expand_path("..", Pod::Config.instance.installation_root.to_s)
76
- end
77
- native_runtime_identity_writer = if native_runtime_identity_resource
78
- File.join(__dir__, "lib", "CLI", "scripts", "native", "write-runtime-identity.js")
79
- end
80
- native_runtime_identity_output = if native_runtime_identity_resource
81
- File.join(__dir__, native_runtime_identity_resource)
82
- end
78
+ native_runtime_identity = bundle_drop_native_runtime_identity_resource.call
83
79
 
84
80
  Pod::Spec.new do |s|
85
81
  s.name = "BundleDrop"
@@ -93,8 +89,8 @@ Pod::Spec.new do |s|
93
89
  s.source = { :git => ".git", :tag => "#{s.version}" }
94
90
 
95
91
  s.source_files = "ios/**/*.{h,m,mm,swift}", "third_party/xdelta/**/*.{c,h}"
96
- s.resources = native_runtime_identity_resource if native_runtime_identity_resource
97
- if native_runtime_identity_resource
92
+ s.resources = native_runtime_identity[:resource_path] if native_runtime_identity
93
+ if native_runtime_identity
98
94
  # Intentionally omit output files so Xcode reruns this when a bare app builds,
99
95
  # even when CocoaPods has not been reinstalled since its config changed.
100
96
  s.script_phase = {
@@ -103,11 +99,12 @@ Pod::Spec.new do |s|
103
99
  :show_env_vars_in_log => "0",
104
100
  :script => <<-SCRIPT
105
101
  set -e
102
+ package_root="$(cd "${PODS_TARGET_SRCROOT:?CocoaPods package root is missing}" && pwd -P)"
106
103
  "${NODE_BINARY:-node}" \
107
- #{Shellwords.escape(native_runtime_identity_writer)} \
108
- --project-root #{Shellwords.escape(native_runtime_identity_project_root)} \
104
+ "$package_root/lib/CLI/scripts/native/write-runtime-identity.js" \
105
+ --project-root "$package_root"/#{Shellwords.escape(native_runtime_identity[:project_relative_root])} \
109
106
  --platform ios \
110
- --output #{Shellwords.escape(native_runtime_identity_output)}
107
+ --output "$package_root"/#{Shellwords.escape(native_runtime_identity[:resource_path])}
111
108
  SCRIPT
112
109
  }
113
110
  end
package/README.md CHANGED
@@ -428,6 +428,25 @@ the entire `.bundle-drop` directory was deleted, and repairs the corresponding
428
428
  `.gitignore` rules. The lockfile contains public identity and verification material,
429
429
  not secrets, so commit it with the application.
430
430
 
431
+ ## Binary build numbers
432
+
433
+ Uploads can record Android `versionCode` or iOS `CFBundleVersion` as optional
434
+ display metadata. The dashboard shows it as `1.0.0 (122132)`. Expo uses its resolved
435
+ build identity; bare projects use recognized literal Gradle/plist/Xcode settings.
436
+ For custom bare build scripts, pass `--build-number 122132` with the upload. Unknown
437
+ or ambiguous values stay absent. Build numbers describe upload context and do not
438
+ restrict delivery or replace runtime compatibility checks.
439
+
440
+ ## Native fingerprinting (Beta)
441
+
442
+ Opt into native fingerprinting to derive `runtimeVersion` from native inputs
443
+ instead of manually bumping it. Compatible JavaScript updates retain the identity;
444
+ detected native changes create a different one and require a new native binary.
445
+ Ship a fingerprint-enabled binary first. Manual runtimes remain the default.
446
+
447
+ You can also keep an explicit runtime version as a manual boundary alongside the
448
+ fingerprint. See [configuration, compatibility rules and coverage limits](docs/native-fingerprint.md).
449
+
431
450
  ## Initialize the Runtime
432
451
 
433
452
  Call `BundleDrop.init` once, as early as possible in the app process.
@@ -483,6 +502,13 @@ Debug builds and development clients also keep Metro as the JavaScript authority
483
502
  they do not start an installed OTA bundle. Test the OTA lifecycle with a non-Debug
484
503
  Release build.
485
504
 
505
+ Implicit Expo Debug/Expo Go suppression applies only to the current process, so
506
+ opening a development build does not disable OTA startup in a later Release build.
507
+ An explicit `init({ enabled: false })` still persists the app's disabled setting.
508
+ For Expo runtime fingerprints, setup excludes transient Kotlin compiler sessions
509
+ under Gradle plugin and Android `.kotlin` directories. Rerun `bundle-drop init`
510
+ and review its setup changes to add missing exclusions to an existing integration.
511
+
486
512
  For managed/CNG projects, setup can leave `ios/` and `android/` absent. The config
487
513
  plugin generates the native integration during a later prebuild, `expo run:*`, or
488
514
  EAS Build. Typical local Release builds are:
@@ -611,7 +637,7 @@ it verifies or persists lane generation state. A missing, invalid, expired, or
611
637
  operator-disabled lease therefore falls back to `/ota/resolve`, even when cached
612
638
  manifest bytes remain cryptographically valid.
613
639
 
614
- Artifact download capabilities are intentionally short-lived. If an artifact URL is
640
+ Managed artifact download capabilities are intentionally short-lived. If an artifact URL is
615
641
  rejected with HTTP 401 or 403 during download, the SDK reauthorizes the original
616
642
  signed selection once and retries only when its generation, target, transport,
617
643
  artifact references, and signed hashes are unchanged. Verification, reconstruction,
@@ -625,6 +651,8 @@ resolve and artifact-authorization decision.
625
651
  Unchanged install state is reported at most once every seven days. A current bundle
626
652
  hash, app environment, or user-property change is reported immediately; successful
627
653
  installs continue to use the separate idempotent installed receipt.
654
+ The SDK's bounded [installed receipt history](docs/install-report-deduplication.md)
655
+ survives recovery to the embedded app without retaining stale installed metadata.
628
656
 
629
657
  The manifest URL is derived from `manifestBaseUrl`, `manifestAccessId`, channel,
630
658
  platform, and runtime version. `manifestAccessId` is an opaque URL-routing value,
@@ -742,6 +770,30 @@ The same actions are available as standalone functions (`checkForUpdate`,
742
770
  `downloadUpdate`, `applyUpdate`, `setChannel`, `reportHealthy`, and others) for use
743
771
  outside React.
744
772
 
773
+ With `policy: 'manual'`, an ordinary server `ROLLBACK` returned by
774
+ `downloadUpdate()` stages a persisted rollback intent without restarting. Its
775
+ result includes `status: 'rollback', pendingApply: true`; the hook and
776
+ `getUpdateState()` also report `pendingApply`. Call `applyUpdate()` to activate it.
777
+ This changes the previous behavior, which rolled back during download itself.
778
+ An ordinary startup check does not activate that rollback.
779
+
780
+ Before applying, Bundle Drop refreshes the decision and checks that the channel,
781
+ runtime and current bundle still match the staged intent. A changed decision or
782
+ selection returns `status: 'blocked', reason: 'ROLLBACK_REVALIDATION_FAILED'`;
783
+ check/download again. If authority is unavailable, apply is blocked and the intent
784
+ remains retryable. A new successful download/staging request replaces the intent.
785
+ The intent does not pin a fallback bundle: at explicit apply, native recovery
786
+ selects and validates a proven previous bundle or falls back to embedded. Missing,
787
+ tampered, incompatible, quarantined and locally known-revoked fallbacks are excluded.
788
+
789
+ Safety recovery remains distinct. The existing `CURRENT_REVOKED_NO_COMPATIBLE_TARGET`,
790
+ `CURRENT_REVOKED_NO_SAFE_TARGET` and `CURRENT_REVOKED_ORIGIN_UNAVAILABLE` decisions
791
+ retain authoritative embedded recovery, including during download or startup
792
+ checking. Native crash recovery, runtime compatibility enforcement and persisted
793
+ revocation checks are unchanged. `NOOP` (including no published bundle) does not
794
+ create a rollback intent. The current backend's no-target revocation decisions
795
+ are safety cases; they are not ordinary manual rollback requests.
796
+
745
797
  ## Targeted Rollouts
746
798
 
747
799
  Attach user properties to target specific cohorts when you stage a release:
@@ -769,6 +821,13 @@ manifest, verifies file hashes and sizes, and only then promotes the bundle.
769
821
  native xdelta support passes its probe.
770
822
  - If patch transport is unavailable or fails, the SDK falls back to the signed
771
823
  full ZIP.
824
+ - For unmanaged delivery, a patch ZIP HTTP 401/403 permits one attempt of the
825
+ full ZIP explicitly supplied by the resolve decision for that same target.
826
+ The SDK does not discover another URL or switch targets. A missing fallback,
827
+ denied full ZIP, or failed verification fails without activation. Resolve/API
828
+ authorization denials and separate manifest/asset download denials do not
829
+ enter this exception. Managed delivery retains its bounded authorization
830
+ refresh and signed-identity checks described above.
772
831
  - Rollback remains a local pointer switch between verified bundle hashes.
773
832
 
774
833
  The production manifest contract is `manifestVersion: 1`. `jsBundleHash` is retained
@@ -133,6 +133,10 @@ if (!project.hasProperty("standalone") && rootProject.findProject(":bundledrop-e
133
133
  task.inputs.file(bundleDropConfigFile)
134
134
  task.inputs.file(bundleDropIdentityWriter)
135
135
  task.outputs.file(bundleDropIdentityOutput)
136
+ // Fingerprint inputs extend beyond the config and writer. Recollect on
137
+ // every build; the writer preserves the output mtime when bytes match.
138
+ task.outputs.upToDateWhen { false }
139
+ task.outputs.cacheIf { false }
136
140
  task.doLast {
137
141
  def nodeBinary = System.getenv("NODE_BINARY") ?: "node"
138
142
  bundleDropCommandExecutor.execute(bundleDropProjectRoot, nodeBinary, [
@@ -32,6 +32,26 @@ object BundleDropFileOps {
32
32
  }
33
33
  }
34
34
 
35
+ fun writeUtf8Atomically(file: File, content: String) {
36
+ val target = file.absoluteFile
37
+ val parent = target.parentFile ?: throw java.io.IOException("Missing parent directory")
38
+ parent.mkdirs()
39
+ val temporary = File.createTempFile(".bundle-drop-write-", ".tmp", parent)
40
+ try {
41
+ FileOutputStream(temporary).use { output ->
42
+ output.write(content.toByteArray(Charsets.UTF_8))
43
+ output.fd.sync()
44
+ }
45
+ // Same-directory rename replaces the file atomically on Android. Never
46
+ // delete the destination or fall back to copying over committed content.
47
+ if (!temporary.renameTo(target)) {
48
+ throw java.io.IOException("Could not atomically replace ${target.name}")
49
+ }
50
+ } finally {
51
+ temporary.delete()
52
+ }
53
+ }
54
+
35
55
  fun unzipFile(
36
56
  zipPath: String,
37
57
  destPath: String,
@@ -206,7 +206,7 @@ class BundleDropModule(reactContext: ReactApplicationContext) :
206
206
  val bytes = android.util.Base64.decode(content, android.util.Base64.DEFAULT)
207
207
  file.writeBytes(bytes)
208
208
  } else {
209
- file.writeText(content, Charsets.UTF_8)
209
+ BundleDropFileOps.writeUtf8Atomically(file, content)
210
210
  }
211
211
  promise.resolve(null)
212
212
  } catch (e: Exception) {
@@ -415,6 +415,9 @@ class BundleDropModule(reactContext: ReactApplicationContext) :
415
415
 
416
416
  override fun getConstants(): MutableMap<String, Any> {
417
417
  val map = mutableMapOf<String, Any>()
418
+ @Suppress("UNCHECKED_CAST")
419
+ (map as MutableMap<String, Any?>)["nativeRuntimeVersion"] =
420
+ BundleDropNativePaths.readEmbeddedRuntimeVersion(reactApplicationContext)
418
421
  map["startupRecoveryProtocolVersion"] = BundleDropStartupRecoveryController.PROTOCOL_VERSION
419
422
  @Suppress("UNCHECKED_CAST")
420
423
  (map as MutableMap<String, Any?>)["startupRecoverySelectedHash"] =
@@ -46,7 +46,11 @@ object BundleDropNativePaths {
46
46
  internal fun readEmbeddedRuntimeVersion(context: Context): String? {
47
47
  return try {
48
48
  context.assets.open(BUILD_IDENTITY_ASSET).bufferedReader().use { reader ->
49
- JSONObject(reader.readText())
49
+ val identity = JSONObject(reader.readText())
50
+ if (identity.optInt("schemaVersion") != 1 || identity.optString("platform") != "android") {
51
+ return null
52
+ }
53
+ identity
50
54
  .optString("runtimeVersion", "")
51
55
  .takeIf { it.trim().isNotEmpty() }
52
56
  }
@@ -0,0 +1,211 @@
1
+ # Native fingerprinting (Beta)
2
+
3
+ Native fingerprinting derives a `bdfp1-` runtime identity from native
4
+ compatibility inputs instead of requiring a manually maintained runtime string.
5
+ Manual runtime literals remain the default; fingerprinting is an explicit opt-in.
6
+ It is currently Beta and intended to become the default in a future release.
7
+ Existing projects keep their selected compatibility mode.
8
+
9
+ ## Enable it in a new native binary
10
+
11
+ In `bundle.drop.config.js`, enable fingerprint compatibility:
12
+
13
+ ```js
14
+ runtimeVersion: {
15
+ compatibilitySource: 'fingerprint',
16
+ },
17
+ ```
18
+
19
+ The SDK detects the native workflow automatically. Keep configuration, installed
20
+ native dependencies and declared build context consistent between native builds
21
+ and OTA uploads.
22
+
23
+ You do not need to set `schemeVersion` in application configuration. Omitting it
24
+ permanently selects scheme 1; SDK upgrades never silently migrate that calculation.
25
+ The version remains in diagnostic reports and artifact metadata for reproducibility.
26
+
27
+ Rebuild and ship the native app after first enabling fingerprinting. Changing an
28
+ OTA configuration alone cannot give an older binary a native fingerprint.
29
+
30
+ - A compatible JavaScript/assets change keeps the runtime identity and may use OTA.
31
+ - A detected native change produces another identity automatically. An old binary
32
+ refuses that OTA; ship a new native binary containing the native change.
33
+ - Optional `ios`/`android` strings beside the selector add manual compatibility
34
+ boundaries. Omitted boundaries are `null`; supplied strings are trimmed.
35
+
36
+ For hybrid control, keep an explicit runtime boundary alongside fingerprinting:
37
+
38
+ ```js
39
+ runtimeVersion: {
40
+ compatibilitySource: 'fingerprint',
41
+ ios: '1.0.0',
42
+ android: '1.0.0',
43
+ },
44
+ ```
45
+
46
+ Both the explicit boundary and detected native inputs must match. Changing either
47
+ requires a matching native binary. To return to manual compatibility, remove the
48
+ fingerprint selector/options and keep the platform runtime strings, then rebuild.
49
+
50
+ A collection error aborts build/upload calculation. It does not reuse an older
51
+ receipt or silently fall back to manual runtime mode. The embedded native identity
52
+ remains authoritative after an OTA replaces JavaScript. Fingerprinting does not
53
+ change update policies, manual apply control, revocation rules or native recovery.
54
+
55
+ ## Inspect the calculation
56
+
57
+ ```sh
58
+ bundle-drop fingerprint --platform android --output report.json
59
+ bundle-drop fingerprint --platform android --compare report.json --json
60
+ ```
61
+
62
+ Reports contain source IDs/digests and `status: "stable"`. Earlier experimental
63
+ reports remain usable for source comparison. Report status, reasons, debug fields
64
+ and this release's descriptive text are not extra runtime-domain fields.
65
+ Source IDs and diagnostics may expose project paths; review reports before sharing.
66
+ Explicit environment values are represented by digests rather than plaintext.
67
+
68
+ ## Bundle metadata and dashboard display
69
+
70
+ New artifacts explicitly include `compatibilitySource: 'manual'` or
71
+ `'fingerprint'` in their metadata. Missing configuration selectors remain manual;
72
+ legacy bundles with no mode metadata are displayed as manual without inferring
73
+ the mode from a runtime string. Explicit Expo-owned runtime resolution continues
74
+ to supply an opaque runtime and is not labeled Bundle Drop scheme-1 fingerprinting.
75
+
76
+ Fingerprint metadata retains the full derived identity, internal scheme version
77
+ and optional manual boundary. The dashboard shows that boundary in Runtime, or
78
+ Automatic when no boundary was declared, and a separate compact Fingerprint
79
+ column with the full value available to inspect and copy. Manual Runtime values
80
+ remain literal. Scheme versions are diagnostic metadata, not a dashboard column.
81
+
82
+ The authoritative `runtimeVersion` remains the complete existing identity in
83
+ manifests, uploads, native checks and patch lanes. Display metadata never changes
84
+ compatibility or permits cross-runtime patches. It is included in the canonical
85
+ file manifest and changes artifact hashes as ordinary metadata bytes do; it does
86
+ not change the frozen native fingerprint calculation. The backend must support
87
+ these metadata fields before the dashboard can display them for new uploads.
88
+
89
+ Optional `buildNumber` metadata records Android `versionCode` or iOS
90
+ `CFBundleVersion`, displayed as `1.0.0 (122132)`. Expo uses the resolved build
91
+ identity, including official versions from an existing local/EAS receipt when
92
+ applicable. Bare uploads read recognized literal values from the selected Gradle
93
+ file or `--plist-file`; the standard Xcode build variable is resolved only when
94
+ the project/settings agree. Flavor-dependent or computed values stay unknown.
95
+ Custom bare build systems can explicitly pass `--build-number 122132`. An Expo
96
+ override must equal its resolved identity. This field describes export context;
97
+ it is not proof that every compatible device has that build number, and never
98
+ narrows runtime or patch matching. Old bundles remain version-only.
99
+
100
+ ## Frozen calculation contract
101
+
102
+ Version 0.11.0 revises the pre-release scheme 1 baseline to use patched minimatch
103
+ 11.0.3 and glob 14.0.3. Some ignore-pattern matches differ from earlier Beta
104
+ previews. Rebuild existing Beta apps and generate their updates with the same
105
+ SDK version and dependency lock. Earlier preview calculators and this release
106
+ are not interchangeable, even though both use the `bdfp1-` prefix.
107
+
108
+ The complete executable baseline is
109
+ `third_party/expo-fingerprint/scheme-1-contract.json`. It pins the first-party
110
+ collector, selector, process adapters, normalization, complete maintained Expo
111
+ adaptation and supporting helpers, generated package files, build configuration,
112
+ production dependency declarations and repository dependency lock. The original
113
+ Expo implementation is `@expo/fingerprint` 0.21.5 at commit
114
+ `d7a68affbace544d36250aa6bdb06e34bda9e8ea`; its notices/provenance ship with the SDK.
115
+
116
+ Scheme 1 uses physical checkout roots, SHA-256, strict collection, one selected
117
+ platform, file-based native-module/config-plugin sources and the fixed options in
118
+ `src/fingerprint/collect.ts`. Source ordering/deduplication and individual source
119
+ hashing follow the pinned adaptation. Required applicable discovery fails closed.
120
+ The source native hash is wrapped as follows, with this exact property order:
121
+
122
+ ```js
123
+ 'bdfp1-' + sha256Utf8(JSON.stringify({
124
+ domain: 'bundle-drop-native-fingerprint',
125
+ schemeVersion: 1,
126
+ platform, // 'ios' or 'android'
127
+ manualBoundary, // trimmed explicit string or null
128
+ nativeHash,
129
+ }))
130
+ ```
131
+
132
+ An omitted `schemeVersion` permanently selects scheme 1. Unsupported schemes fail
133
+ closed. A future change to input selection, normalization, options, ordering,
134
+ hashing, environment handling, helper behavior or dependencies that changes
135
+ identities for unchanged supported inputs requires a new scheme and retained
136
+ scheme-1 support. Do not rewrite old vectors to bless calculation drift. Byte-only
137
+ maintenance must demonstrate unchanged behavior before updating a reviewed pin.
138
+ There is no automatic baseline-update command.
139
+
140
+ `yarn fingerprint:check` checks both source and packaged helper inventories/hashes
141
+ and the dependency lock; it is included in `verify:quick`/`verify:release`.
142
+ Tarball inspection independently checks the shipped helper hashes and dependency
143
+ declarations. `src/tests/fingerprint/scheme-1-golden.json` retains the original
144
+ Android vector and Android/iOS mutation/boundary vectors.
145
+ Consumer projects must retain their own dependency lock and matching toolchain;
146
+ this release baseline does not make every consumer's transitive dependency
147
+ resolution or arbitrary external tool identical. Existing application locks
148
+ must also refresh Axios's `follow-redirects` resolution to 1.16.2 or newer for
149
+ GHSA-8r9p-f939-6h3c, GHSA-q3jh-wrc6-jgq8 and GHSA-mrwp-f3q8-3g9p.
150
+ A library's root Yarn resolutions do not override every consumer's existing lock.
151
+ The transport patch leaves all scheme-1 calculation helper bytes/goldens unchanged.
152
+
153
+ ## Inputs and stability
154
+
155
+ Inherited Expo discovery includes native directories, autolinked packages, package
156
+ scripts, evaluated Expo config and config-plugin files. In CNG mode generated
157
+ native directories are excluded; express native changes through config/plugins
158
+ or explicit sources. `.fingerprintignore` remains effective. Reducing coverage
159
+ through ignores is the application's responsibility; keep ignore rules identical
160
+ between build and upload checkouts.
161
+
162
+ Bundle Drop adds explicit selection/boundaries, native embedding and authority,
163
+ extra inputs, domain hashing and generated-output exclusions. It excludes generated
164
+ Bundle Drop identities/artifacts, runtime-delivery metadata, local SDK paths,
165
+ debug keystores, output metadata and Android/Kotlin compiler session directories.
166
+ The exact exclusions are pinned, including inherited Expo defaults.
167
+
168
+ Android build-number normalization supports only recognized integer literal
169
+ `versionCode 1` / `versionCode = 1` statements in known `defaultConfig` and
170
+ `productFlavors` scopes. Bare iOS normalization supports numeric literal
171
+ `CURRENT_PROJECT_VERSION` in Xcode `buildSettings` dictionaries. Computed values,
172
+ ambiguous syntax, conditional keys, comments and other fields retain their bytes.
173
+ No arbitrary Gradle, Xcode script or plist interpretation is attempted.
174
+
175
+ ## Build context and explicit inputs
176
+
177
+ Selecting a different existing Android flavor or Xcode configuration may leave
178
+ source files unchanged. Declare native context explicitly when it matters:
179
+
180
+ ```js
181
+ fingerprint: {
182
+ extraSources: [
183
+ { id: 'variant', type: 'environment', value: 'APP_NATIVE_VARIANT', platforms: ['android'] },
184
+ { id: 'configuration', type: 'environment', value: 'CONFIGURATION', platforms: ['ios'] },
185
+ { id: 'native-settings', type: 'file', value: 'native/settings.json' },
186
+ ],
187
+ },
188
+ ```
189
+
190
+ Use the same values during the actual native build and independent upload.
191
+ Bind the Android context to the selected build task. Xcode exports `CONFIGURATION`
192
+ during builds; supply it to standalone calculation and relevant Pod installation.
193
+ Missing required values fail calculation. `file`, `dir` and `environment` extra
194
+ sources are supported; optional absence is itself a hashed input.
195
+
196
+ ## Coverage and limitations
197
+
198
+ - React Native core is inherited package-name/version identity. An in-place core
199
+ patch needs an explicit input; it is not universally detected automatically.
200
+ - Other autolinked packages can contribute whole package trees. Tooling/JS-only
201
+ package changes may therefore conservatively create incompatibility.
202
+ - Resolved Gradle artifact digests, installed CocoaPods/SwiftPM contents, arbitrary
203
+ compiler settings and disposable CNG projections are not added by scheme 1.
204
+ - Dependencies that modify their own native files during builds require the same
205
+ persistent patch in both checkouts. The upload collector does not run Gradle
206
+ or repair dependencies. The masked-view 0.3.2 manifest rewrite was one such case.
207
+ - Environment-dependent configuration must be reproducible. The worker uses
208
+ development only when `NODE_ENV` is explicitly `development`, otherwise production.
209
+ - Native-module addition changes the identity within this documented coverage.
210
+ It still requires a new store binary; fingerprinting does not deliver native code.
211
+
@@ -15,6 +15,56 @@ abstract class BundleDropCommandExecutor {
15
15
  }
16
16
  }
17
17
 
18
+ // Keep only plain artifact metadata in the package task action. Capturing an AGP
19
+ // variant or Project in a doLast closure prevents configuration-cache storage.
20
+ class BundleDropPackagedReceiptAction implements Action<Task> {
21
+ BundleDropCommandExecutor commandExecutor
22
+ File receiptWriter
23
+ File workingDirectory
24
+ File projectRoot
25
+ File sdkDirectory
26
+ String nodeBinary
27
+ List<Map<String, String>> outputIdentities
28
+
29
+ @Override
30
+ void execute(Task task) {
31
+ def artifacts = []
32
+ task.outputs.files.files.each { File output ->
33
+ if (output.isFile() && (output.name.endsWith('.apk') || output.name.endsWith('.aab'))) {
34
+ artifacts.add(output.canonicalFile)
35
+ } else if (output.isDirectory()) {
36
+ output.eachFileRecurse { File candidate ->
37
+ if (candidate.isFile() && (candidate.name.endsWith('.apk') || candidate.name.endsWith('.aab'))) {
38
+ artifacts.add(candidate.canonicalFile)
39
+ }
40
+ }
41
+ }
42
+ }
43
+ artifacts = artifacts.unique { it.path }.sort { left, right -> left.path <=> right.path }
44
+ if (artifacts.isEmpty()) return
45
+ if (!receiptWriter.isFile()) {
46
+ throw new GradleException("Bundle Drop receipt writer is missing from the installed package: ${receiptWriter}")
47
+ }
48
+ // Split APKs are separately signed outputs; retain the deterministic exact
49
+ // artifact selection and version mapping used by the receipt writer.
50
+ def artifact = artifacts.first()
51
+ def matching = outputIdentities.findAll { it.fileName == artifact.name }
52
+ def identity
53
+ if (matching.size() == 1) identity = matching.first()
54
+ else if (outputIdentities.size() == 1) identity = outputIdentities.first()
55
+ else throw new GradleException("Bundle Drop could not map ${artifact.name} to an exact Android variant output.")
56
+ commandExecutor.execute(workingDirectory, nodeBinary, [
57
+ receiptWriter.path,
58
+ '--project-root', projectRoot.path,
59
+ '--platform', 'android',
60
+ '--artifact', artifact.path,
61
+ '--android-sdk', sdkDirectory.path,
62
+ '--app-version', identity.appVersion,
63
+ '--native-build-version', identity.nativeBuildVersion
64
+ ])
65
+ }
66
+ }
67
+
18
68
  buildscript {
19
69
  repositories {
20
70
  google()
@@ -60,22 +110,6 @@ dependencies {
60
110
  def bundleDropReceiptWriter = file("../../lib/CLI/scripts/expo/write-build-receipt.js").canonicalFile
61
111
  def bundleDropExpoProjectRoot = rootProject.projectDir.parentFile.canonicalFile
62
112
 
63
- def bundleDropPackagedArtifacts = { Task task ->
64
- def artifacts = []
65
- task.outputs.files.files.each { File output ->
66
- if (output.isFile() && (output.name.endsWith(".apk") || output.name.endsWith(".aab"))) {
67
- artifacts.add(output.canonicalFile)
68
- } else if (output.isDirectory()) {
69
- output.eachFileRecurse { File candidate ->
70
- if (candidate.isFile() && (candidate.name.endsWith(".apk") || candidate.name.endsWith(".aab"))) {
71
- artifacts.add(candidate.canonicalFile)
72
- }
73
- }
74
- }
75
- }
76
- return artifacts.unique { it.path }.sort { left, right -> left.path <=> right.path }
77
- }
78
-
79
113
  def bundleDropVariantForTask = { applicationProject, Task task ->
80
114
  def taskName = task.name.toLowerCase()
81
115
  def matchingVariants = applicationProject.android.applicationVariants.findAll { variant ->
@@ -89,21 +123,7 @@ def bundleDropVariantForTask = { applicationProject, Task task ->
89
123
  return matchingVariants.first()
90
124
  }
91
125
 
92
- def bundleDropVariantIdentity = { variant, File artifact = null ->
93
- def matchingOutputs = artifact == null ? [] : variant.outputs.findAll { output ->
94
- output.outputFileName == artifact.name
95
- }
96
- def output
97
- if (matchingOutputs.size() == 1) {
98
- output = matchingOutputs.first()
99
- } else if (variant.outputs.size() == 1) {
100
- output = variant.outputs.first()
101
- } else {
102
- def outputLabel = artifact == null ? variant.name : artifact.name
103
- throw new GradleException(
104
- "Bundle Drop could not map ${outputLabel} to an exact Android variant output."
105
- )
106
- }
126
+ def bundleDropOutputIdentity = { variant, output ->
107
127
  def appVersion = output.versionNameOverride ?: variant.versionName
108
128
  def nativeBuildVersion = output.versionCodeOverride ?: output.versionCode ?: variant.versionCode
109
129
  if (appVersion == null || nativeBuildVersion == null) {
@@ -111,7 +131,7 @@ def bundleDropVariantIdentity = { variant, File artifact = null ->
111
131
  "Bundle Drop could not resolve the packaged Android versionName/versionCode."
112
132
  )
113
133
  }
114
- return [appVersion: appVersion.toString(), nativeBuildVersion: nativeBuildVersion.toString()]
134
+ return [fileName: output.outputFileName.toString(), appVersion: appVersion.toString(), nativeBuildVersion: nativeBuildVersion.toString()]
115
135
  }
116
136
 
117
137
  // This module is Expo-only. Attach proof after Android's application package/bundle task
@@ -128,30 +148,15 @@ rootProject.gradle.projectsEvaluated {
128
148
  applicationProject.tasks.configureEach { Task task ->
129
149
  if (task.name ==~ /(?i)(package|bundle).*release/) {
130
150
  def variant = bundleDropVariantForTask(applicationProject, task)
131
- task.doLast {
132
- def artifacts = bundleDropPackagedArtifacts(task)
133
- if (!artifacts.isEmpty()) {
134
- if (!bundleDropReceiptWriter.isFile()) {
135
- throw new GradleException(
136
- "Bundle Drop receipt writer is missing from the installed package: ${bundleDropReceiptWriter}"
137
- )
138
- }
139
- // Split APKs are separately signed outputs. Use the lexically first exact
140
- // artifact so the proof is deterministic and can be re-hashed at upload.
141
- def artifact = artifacts.first()
142
- def nodeBinary = System.getenv("NODE_BINARY") ?: "node"
143
- def packagedIdentity = bundleDropVariantIdentity(variant, artifact)
144
- bundleDropCommandExecutor.execute(applicationProject.projectDir, nodeBinary, [
145
- bundleDropReceiptWriter.path,
146
- "--project-root", bundleDropExpoProjectRoot.path,
147
- "--platform", "android",
148
- "--artifact", artifact.path,
149
- "--android-sdk", applicationProject.android.sdkDirectory.canonicalPath,
150
- "--app-version", packagedIdentity.appVersion,
151
- "--native-build-version", packagedIdentity.nativeBuildVersion
152
- ])
153
- }
154
- }
151
+ task.doLast(new BundleDropPackagedReceiptAction(
152
+ commandExecutor: bundleDropCommandExecutor,
153
+ receiptWriter: bundleDropReceiptWriter,
154
+ workingDirectory: applicationProject.projectDir.canonicalFile,
155
+ projectRoot: bundleDropExpoProjectRoot,
156
+ sdkDirectory: applicationProject.android.sdkDirectory.canonicalFile,
157
+ nodeBinary: System.getenv('NODE_BINARY') ?: 'node',
158
+ outputIdentities: variant.outputs.collect { output -> bundleDropOutputIdentity(variant, output) }
159
+ ))
155
160
  }
156
161
  }
157
162
  }
@@ -131,4 +131,16 @@ import Foundation
131
131
  @objc public static func fileSize(at url: URL) -> UInt64 {
132
132
  (try? FileManager.default.attributesOfItem(atPath: url.path)[.size] as? UInt64) ?? 0
133
133
  }
134
+
135
+ static func embeddedBundleURL(bundle: Bundle = .main) -> URL? {
136
+ guard let url = bundle.url(forResource: "main", withExtension: "jsbundle"),
137
+ url.isFileURL else { return nil }
138
+ let root = bundle.bundleURL.standardizedFileURL.resolvingSymlinksInPath().path + "/"
139
+ let resolved = url.standardizedFileURL.resolvingSymlinksInPath()
140
+ guard resolved.path.hasPrefix(root),
141
+ let attributes = try? FileManager.default.attributesOfItem(atPath: url.path),
142
+ attributes[.type] as? FileAttributeType == .typeRegular,
143
+ fileSize(at: url) >= 1024 else { return nil }
144
+ return resolved
145
+ }
134
146
  }