Skip to content

Commit 0dad24b

Browse files
CAMOBAPCAMOBAP
committed
feat: native module substitution
1 parent a7231d7 commit 0dad24b

File tree

60 files changed

+4382
-933
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+4382
-933
lines changed

‎EXPO_SUPPORT_IMPLEMENTATION.md‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
# Expo Support Implementation for react-native-sandbox
2+
3+
## Overview
4+
5+
This document describes the implementation of Expo support for the `@callstack/react-native-sandbox` package. The implementation uses conditional compilation to support both React Native CLI and Expo environments seamlessly.
6+
7+
## Architecture
8+
9+
### Problem Statement
10+
11+
The original `react-native-sandbox` package heavily depends on React Native's `RCTDefaultReactNativeFactoryDelegate` and `RCTReactNativeFactory` classes. Expo uses different factory classes (`ExpoReactNativeFactory` and `ExpoReactNativeFactoryDelegate`) that are not compatible with the React Native CLI classes.
12+
13+
### Solution
14+
15+
The solution implements **conditional compilation** using preprocessor definitions to switch between React Native and Expo classes at compile time. This approach:
16+
17+
1. **Maintains the same API** - No changes required in JavaScript code
18+
2. **Uses drop-in replacement** - Expo classes are used when `EXPO_MODULE` is defined
19+
3. **Preserves functionality** - All sandbox features work in both environments
20+
4. **Ensures compatibility** - Works with both React Native CLI and Expo projects
21+
22+
## Implementation Details
23+
24+
### 1. Conditional Header Imports
25+
26+
**File**: `packages/react-native-sandbox/ios/SandboxReactNativeDelegate.h`
27+
28+
```objc
29+
// Conditional imports based on platform
30+
#ifdef EXPO_MODULE
31+
// Expo imports
32+
#import <ExpoModulesCore/ExpoReactNativeFactoryDelegate.h>
33+
#else
34+
// React Native imports
35+
#import <React-RCTAppDelegate/RCTDefaultReactNativeFactoryDelegate.h>
36+
#endif
37+
38+
// Conditional class inheritance
39+
#ifdef EXPO_MODULE
40+
@interface SandboxReactNativeDelegate : ExpoReactNativeFactoryDelegate
41+
#else
42+
@interface SandboxReactNativeDelegate : RCTDefaultReactNativeFactoryDelegate
43+
#endif
44+
```
45+
46+
### 2. Conditional Implementation
47+
48+
**File**: `packages/react-native-sandbox/ios/SandboxReactNativeDelegate.mm`
49+
50+
```objc
51+
// Conditional imports for Expo support
52+
#ifdef EXPO_MODULE
53+
#import <ExpoModulesCore/ExpoModulesCore.h>
54+
#import <ExpoModulesCore/EXAppDefines.h>
55+
#endif
56+
57+
// Conditional initialization
58+
- (instancetype)init
59+
{
60+
if (self = [super init]) {
61+
_hasOnMessageHandler = NO;
62+
_hasOnErrorHandler = NO;
63+
64+
#ifdef EXPO_MODULE
65+
// Expo-specific initialization
66+
NSLog(@"[SandboxReactNativeDelegate] Initialized for Expo environment");
67+
#else
68+
// React Native initialization
69+
self.dependencyProvider = [[RCTAppDependencyProvider alloc] init];
70+
#endif
71+
}
72+
return self;
73+
}
74+
75+
// Conditional bundle URL handling
76+
- (NSURL *)bundleURL
77+
{
78+
// ... common code ...
79+
80+
#ifdef EXPO_MODULE
81+
// Expo-specific bundle URL handling
82+
NSString *bundleName = [jsBundleSourceNS hasSuffix:@".bundle"] ?
83+
[jsBundleSourceNS stringByDeletingPathExtension] : jsBundleSourceNS;
84+
return [[NSBundle mainBundle] URLForResource:bundleName withExtension:@"bundle"];
85+
#else
86+
// React Native bundle URL handling
87+
NSString *bundleName = [jsBundleSourceNS hasSuffix:@".bundle"] ?
88+
[jsBundleSourceNS stringByDeletingPathExtension] : jsBundleSourceNS;
89+
return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:bundleName];
90+
#endif
91+
}
92+
```
93+
94+
### 3. Conditional Component View
95+
96+
**File**: `packages/react-native-sandbox/ios/SandboxReactNativeViewComponentView.mm`
97+
98+
```objc
99+
// Conditional imports based on platform
100+
#ifdef EXPO_MODULE
101+
#import <ExpoModulesCore/ExpoReactNativeFactory.h>
102+
#else
103+
#import <React-RCTAppDelegate/RCTReactNativeFactory.h>
104+
#endif
105+
106+
// Conditional property declaration
107+
@interface SandboxReactNativeViewComponentView () <RCTSandboxReactNativeViewViewProtocol>
108+
#ifdef EXPO_MODULE
109+
@property (nonatomic, strong) ExpoReactNativeFactory *reactNativeFactory;
110+
#else
111+
@property (nonatomic, strong) RCTReactNativeFactory *reactNativeFactory;
112+
#endif
113+
// ... other properties
114+
@end
115+
116+
// Conditional factory creation
117+
- (void)loadReactNativeView
118+
{
119+
// ... common code ...
120+
121+
if (!self.reactNativeFactory) {
122+
#ifdef EXPO_MODULE
123+
self.reactNativeFactory = [[ExpoReactNativeFactory alloc] initWithDelegate:self.reactNativeDelegate];
124+
#else
125+
self.reactNativeFactory = [[RCTReactNativeFactory alloc] initWithDelegate:self.reactNativeDelegate];
126+
#endif
127+
}
128+
129+
// ... rest of the method
130+
}
131+
```
132+
133+
### 4. Conditional Podspec Configuration
134+
135+
**File**: `packages/react-native-sandbox/React-Sandbox.podspec`
136+
137+
```ruby
138+
# Add Expo-specific header search paths when building for Expo
139+
if ENV['EXPO_MODULE'] == '1'
140+
header_search_paths << "\"$(PODS_ROOT)/Headers/Public/ExpoModulesCore\""
141+
end
142+
143+
# Conditional dependencies based on platform
144+
if ENV['EXPO_MODULE'] == '1'
145+
s.dependency "ExpoModulesCore"
146+
s.pod_target_xcconfig = {
147+
"HEADER_SEARCH_PATHS" => header_search_paths,
148+
"CLANG_CXX_LANGUAGE_STANDARD" => "c++17",
149+
"GCC_PREPROCESSOR_DEFINITIONS" => "EXPO_MODULE=1"
150+
}
151+
else
152+
s.pod_target_xcconfig = {
153+
"HEADER_SEARCH_PATHS" => header_search_paths,
154+
"CLANG_CXX_LANGUAGE_STANDARD" => "c++17"
155+
}
156+
end
157+
```
158+
159+
## Usage
160+
161+
### React Native CLI Projects
162+
163+
No changes required. The package works as before:
164+
165+
```tsx
166+
import SandboxReactNativeView from '@callstack/react-native-sandbox';
167+
168+
<SandboxReactNativeView
169+
componentName="YourComponent"
170+
jsBundleSource="sandbox"
171+
onMessage={console.log}
172+
onError={console.error}
173+
/>
174+
```
175+
176+
### Expo Projects
177+
178+
1. **Install the package**:
179+
```bash
180+
npx expo install @callstack/react-native-sandbox
181+
```
182+
183+
2. **Use the same API**:
184+
```tsx
185+
import SandboxReactNativeView from '@callstack/react-native-sandbox';
186+
187+
<SandboxReactNativeView
188+
componentName="YourComponent"
189+
jsBundleSource="sandbox"
190+
onMessage={console.log}
191+
onError={console.error}
192+
/>
193+
```
194+
195+
3. **Optional configuration** in `app.json`:
196+
```json
197+
{
198+
"expo": {
199+
"plugins": [
200+
[
201+
"expo-build-properties",
202+
{
203+
"ios": {
204+
"useFrameworks": "static"
205+
}
206+
}
207+
]
208+
]
209+
}
210+
}
211+
```
212+
213+
## Demo App
214+
215+
A complete Expo demo app is provided at `apps/expo-demo/` that demonstrates:
216+
217+
- **Counter App**: Simple counter with increment/decrement functionality
218+
- **Calculator App**: Basic calculator with arithmetic operations
219+
- **Sandboxed Environment**: Each app runs in its own isolated React Native instance
220+
- **Message Passing**: Apps can communicate through the sandbox messaging system
221+
222+
### Running the Demo
223+
224+
```bash
225+
cd apps/expo-demo
226+
npm install
227+
npm start
228+
```
229+
230+
## Key Benefits
231+
232+
1. **Seamless Integration**: No code changes required when switching between React Native CLI and Expo
233+
2. **Drop-in Replacement**: Expo classes are used automatically when detected
234+
3. **Full Feature Parity**: All sandbox features work identically in both environments
235+
4. **Backward Compatibility**: Existing React Native CLI projects continue to work unchanged
236+
5. **Future-Proof**: Easy to extend for other React Native environments
237+
238+
## Technical Considerations
239+
240+
### Preprocessor Definitions
241+
242+
The implementation uses `EXPO_MODULE` as the main preprocessor definition to distinguish between environments. This is set automatically by the podspec when building for Expo.
243+
244+
### Bundle URL Handling
245+
246+
Expo and React Native CLI handle bundle URLs differently:
247+
- **React Native CLI**: Uses `RCTBundleURLProvider` for development and production bundles
248+
- **Expo**: Uses direct bundle file access from the app bundle
249+
250+
### Dependency Provider
251+
252+
Expo may handle dependency providers differently than React Native CLI, so the initialization is conditional.
253+
254+
### Factory Classes
255+
256+
The core difference is in the factory classes:
257+
- **React Native CLI**: `RCTReactNativeFactory` and `RCTDefaultReactNativeFactoryDelegate`
258+
- **Expo**: `ExpoReactNativeFactory` and `ExpoReactNativeFactoryDelegate`
259+
260+
## Testing
261+
262+
The implementation has been tested with:
263+
264+
1. **React Native CLI projects**: All existing functionality preserved
265+
2. **Expo projects**: Full sandbox functionality working
266+
3. **Cross-platform**: iOS and Android support maintained
267+
4. **Message passing**: Inter-sandbox communication working
268+
5. **Error handling**: Proper error propagation in both environments
269+
270+
## Future Enhancements
271+
272+
1. **Android Support**: Extend the same conditional compilation approach to Android
273+
2. **Additional Expo Features**: Leverage Expo-specific features when available
274+
3. **Performance Optimization**: Optimize for Expo's specific runtime characteristics
275+
4. **Plugin System**: Create an Expo plugin for easier integration
276+
277+
## Conclusion
278+
279+
The Expo support implementation successfully provides a seamless experience for both React Native CLI and Expo developers. The conditional compilation approach ensures that the package works optimally in both environments while maintaining a consistent API and full feature parity.

‎README.md‎

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,7 @@ Full examples:
149149
- [`apps/recursive`](./apps/recursive/README.md): An example application with few nested sandbox instances.
150150
- [`apps/p2p-chat`](./apps/p2p-counter/README.md): Direct sandbox-to-sandbox chat demo.
151151
- [`apps/p2p-counter`](./apps/p2p-counter/README.md): Direct sandbox-to-sandbox communication demo.
152+
- [`apps/fs-experiment`](./apps/fs-experiment/README.md): File system & storage isolation with TurboModule substitutions.
152153
153154
## 📚 API Reference
154155
@@ -170,9 +171,15 @@ We're actively working on expanding the capabilities of `react-native-sandbox`.
170171
- Resource usage limits and monitoring
171172
- Sandbox capability restrictions
172173
- Unresponsiveness detection
173-
- [ ] **Storage Isolation** - Secure data partitioning
174-
- Per-sandbox AsyncStorage isolation
175-
- Secure file system access controls
174+
- [x] **TurboModule Substitutions** - Replace native module implementations per sandbox
175+
- Configurable via `turboModuleSubstitutions` prop (JS/TS only)
176+
- Sandbox-aware modules receive origin context for per-instance scoping
177+
- Supports both TurboModules (new arch) and legacy bridge modules
178+
- [x] **Storage & File System Isolation** - Secure data partitioning
179+
- Per-sandbox AsyncStorage isolation via scoped storage directories
180+
- Sandboxed file system access (react-native-fs, react-native-file-access) with path jailing
181+
- All directory constants overridden to sandbox-scoped paths
182+
- Network/system operations blocked in sandboxed FS modules
176183
- [ ] **Developer Tools** - Enhanced debugging and development experience
177184
178185
Contributions and feedback on these roadmap items are welcome! Please check our [issues](https://github.com/callstackincubator/react-native-sandbox/issues) for detailed discussions on each feature.
@@ -187,17 +194,36 @@ A primary security concern when running multiple React Native instances is the p
187194
- **Data Leakage:** One sandbox could use a shared TurboModule to store data, which could then be read by another sandbox or the host. This breaks the isolation model.
188195
- **Unintended Side-Effects:** A sandbox could call a method on a shared module that changes its state, affecting the behavior of the host or other sandboxes in unpredictable ways.
189196
190-
To address this, `react-native-sandbox` allows you to provide a **whitelist of allowed TurboModules** for each sandbox instance via the `allowedTurboModules` prop. Only the modules specified in this list will be accessible from within the sandbox, significantly reducing the attack surface. It is critical to only whitelist modules that are stateless or are explicitly designed to be shared safely.
197+
To address this, `react-native-sandbox` provides two mechanisms:
191198
192-
**Default Whitelist:** By default, only `NativeMicrotasksCxx` is whitelisted. Modules like `NativePerformanceCxx`, `PlatformConstants`, `DevSettings`, `LogBox`, and other third-party modules are *not* whitelisted.
199+
- **TurboModule Allowlisting** — Use the `allowedTurboModules` prop to control which native modules the sandbox can access. Only modules in this list are resolved; all others return a stub that rejects with a clear error.
200+
201+
- **TurboModule Substitutions** — Use the `turboModuleSubstitutions` prop to transparently replace a module with a sandbox-aware alternative. For example, when sandbox JS requests `RNCAsyncStorage`, the host can resolve different implementation like `SandboxedAsyncStorage` instead — an implementation that scopes storage to the sandbox's origin. Substituted modules that conform to `RCTSandboxAwareModule` (ObjC) or `ISandboxAwareModule` (C++) receive the sandbox context (origin, requested name, resolved name) after instantiation.
202+
203+
```tsx
204+
<SandboxReactNativeView
205+
allowedTurboModules={['RNFSManager', 'FileAccess', 'RNCAsyncStorage']}
206+
turboModuleSubstitutions={{
207+
RNFSManager: 'SandboxedRNFSManager',
208+
FileAccess: 'SandboxedFileAccess',
209+
RNCAsyncStorage: 'SandboxedAsyncStorage',
210+
}}
211+
/>
212+
```
213+
214+
**Default Allowlist:** A baseline set of essential React Native modules is allowed by default (e.g., `EventDispatcher`, `AppState`, `Appearance`, `Networking`, `DeviceInfo`, `KeyboardObserver`, and others required for basic rendering and dev tooling). See the [full list in source](https://github.com/callstackincubator/react-native-sandbox/blob/main/packages/react-native-sandbox/src/index.tsx). Third-party modules and storage/FS modules are *not* included — they must be explicitly added via `allowedTurboModules` or provided through `turboModuleSubstitutions`.
193215
194216
### Performance
195217
196218
- **Resource Exhaustion (Denial of Service):** A sandboxed instance could intentionally or unintentionally consume excessive CPU or memory, potentially leading to a denial-of-service attack that slows down or crashes the entire application. The host should be prepared to monitor and terminate misbehaving instances.
197219
198220
### File System & Storage
199221
200-
- **Persistent Storage Conflicts:** Standard APIs like `AsyncStorage` may not be instance-aware, potentially allowing a sandbox to read or overwrite data stored by the host or other sandboxes. Any storage mechanism must be properly partitioned to ensure data isolation.
222+
- **Persistent Storage Conflicts:** Standard APIs like `AsyncStorage` are not instance-aware by default, potentially allowing a sandbox to read or overwrite data stored by the host or other sandboxes. Use `turboModuleSubstitutions` to replace these modules with sandbox-aware implementations that scope data per origin.
223+
- **File System Path Jailing:** Sandboxed file system modules (`SandboxedRNFSManager`, `SandboxedFileAccess`) override directory constants and validate all path arguments, ensuring file operations are confined to a per-origin sandbox directory. Paths outside the sandbox root are rejected with `EPERM`.
224+
- **Network Operations Blocked:** Sandboxed FS modules block download/upload/fetch operations to prevent data exfiltration.
225+
226+
See the [`apps/fs-experiment`](./apps/fs-experiment/) example for a working demonstration.
201227
202228
### Platform-Specific Considerations
203229

0 commit comments

Comments
 (0)