Skip to content

SPEC.md

Latest commit

 

History

History
44 lines (31 loc) · 4.99 KB

SPEC.md

File metadata and controls

44 lines (31 loc) · 4.99 KB
Raw

Bundle Crypto Native Contract

Status: Implemented. The native checks listed below provide focused runtime evidence only where noted.

Purpose and ownership

This package verifies signed update metadata, computes file hashes, checks a bundle directory against expected hashes, and provides local file operations to other OneKey native modules. The caller owns download, signature-file acquisition, metadata parsing, and the decision to install an update. The embedded OneKey public key is native-only and is not returned to JavaScript.

Public API and data

  • verifyGpgCleartext verifies a PGP cleartext-signed JSON message and requires signed fileName == "metadata.json". When a caller supplies expectedAppType, expectedAppVersion, or expectedBundleVersion, the corresponding signed field must be present, non-empty, and equal to it. It returns the signed sha256 only after successful signature and field verification. verifyDetachedAsc verifies a PGP cleartext-signed SHA256SUMS body, matches expectedFileName when filename columns are present, and returns the matching 64-character hex token. Verification or binding failures return valid: false with a reason and no hash.
  • sha256OfFile streams a file and returns either a lowercase SHA-256 hex digest or a failure reason. The exact failure-reason taxonomy differs by platform.
  • secureEqualHex compares two UTF-8 strings byte by byte after checking equal length.
  • hashDir returns relative paths and SHA-256 hashes for files under a directory. verifyDirAgainstHashes checks that every non-exempt on-disk file has a matching expected hash and that every expected file exists. Files whose exact basename is metadata.json or .DS_Store are exempt from hashing.
  • validateExtractedPathSafety rejects symbolic links and paths resolving outside an extracted directory. atomicWriteFile, safeRename, and listVersionDirs perform local file operations; the caller owns when to invoke them.

Directory hash safety and failure

Each DirHashEntry.relativePath passed to verifyDirAgainstHashes must name a file below dirPath. Empty paths, absolute paths, and paths that resolve to the root or outside it are invalid. Resolution includes .. segments and symbolic links. Invalid entries, missing expected files, unlisted files, and hash mismatches return false. An outside path is never accepted merely because the named file exists. Both Android and iOS enforce this boundary before checking directory contents.

Lifecycle, platform behavior, and resource limits

The verification and file operations are synchronous inside each native core; the Nitro wrappers return promises for the asynchronous API methods. No long-lived request state is retained by the core. File hashing streams input rather than loading entire files into memory. Android uses BouncyCastle for PGP verification and Java MessageDigest; iOS uses Gopenpgp and CommonCrypto. Both platforms use the same embedded public key and directory-path boundary. The caller must separately limit downloaded data and decide how to handle failed verification.

Mac Catalyst framework packaging

Implemented; extracted npm-package Catalyst Swift import verified. Full consumer runtime acceptance remains pending. The Catalyst Gopenpgp slice uses a versioned macOS framework. npm does not preserve its framework symlinks, so podspec evaluation MUST restore missing Versions/Current and the binary, Headers, Modules, and Resources links before CocoaPods selects the slice. Existing symbolic links with a different target MUST be replaced, including dangling links; correct links and materialized files or directories MUST be preserved. Targets stay inside the packaged framework. This repair MUST NOT modify the versioned binary or headers, verification behavior, or iOS/Android runtime behavior, and repeated Pod installation MUST be idempotent.

Conformance and acceptance

  • Framework packaging regression: ruby native-modules/react-native-bundle-crypto/ios/tests/PodspecFrameworkLinksTest.rb evaluates the podspec against temporary framework layouts, covering missing, dangling, stale, and correct links, materialized entries, and an absent Catalyst slice. These checks do not prove a consumer build or cryptographic operation.
  • Android implementation: android/src/main/java/com/margelo/nitro/reactnativebundlecrypto/BundleCryptoCore.kt. JVM tests: android/src/test/java/com/margelo/nitro/reactnativebundlecrypto/BundleCryptoCoreTest.kt.
  • iOS implementation: ios/BundleCryptoCore.swift. XCTest: ios/tests/BundleCryptoCoreTests.swift.
  • Focused tests exercise the real native cores on both Android JVM and iOS XCTest for valid signed metadata acceptance, signed-message tampering/unsigned rejection, wrong-body ASC rejection, directory hash matching and failure, invalid expected paths, and extracted symlink rejection.
  • The focused tests do not prove Nitro bridge behavior, download/install integration, actual archive extraction, or physical-device filesystem behavior. Those remain integration and device acceptance cases.