move docs to docs/ folder, merge architecture files, update references
This commit is contained in:
986
docs/SANDBOX_MILESTONES.md
Normal file
986
docs/SANDBOX_MILESTONES.md
Normal file
@@ -0,0 +1,986 @@
|
||||
# Sandbox Implementation Milestones
|
||||
|
||||
Based on SANDBOX.md design document. Implementation order optimized for dependencies.
|
||||
|
||||
---
|
||||
|
||||
## Milestone 1: Core Sandbox Foundation ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Create isolated Lua environments with resource limits.
|
||||
**Estimated Files**: 3 new files
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| LuaSandbox class | `src/main/cpp/sandbox/lua_sandbox.h` | Main sandbox container |
|
||||
| Custom allocator | `src/main/cpp/sandbox/lua_sandbox.cpp` | Per-app memory tracking/limits |
|
||||
| Instruction hook | `src/main/cpp/sandbox/lua_sandbox.cpp` | CPU limit enforcement |
|
||||
| Globals removal | `src/main/cpp/sandbox/lua_sandbox.cpp` | Remove os, io, debug, etc. |
|
||||
| Bytecode prevention | `src/main/cpp/sandbox/lua_sandbox.cpp` | Text-only loading mode |
|
||||
| Metatable protection | `src/main/cpp/sandbox/lua_sandbox.cpp` | Freeze _G and string metatable |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Create `LuaSandbox` class with:
|
||||
- `lua_State* m_L` - isolated state
|
||||
- `SandboxLimits m_limits` - memory/CPU/stack limits
|
||||
- `SandboxContext m_context` - app_id, permissions, etc.
|
||||
- Custom allocator that tracks `m_memory_used`
|
||||
|
||||
2. Implement `RemoveDangerousGlobals()`:
|
||||
- Remove: `os`, `io`, `debug`, `package`, `require`, `ffi`, `jit`
|
||||
- Remove: `dofile`, `loadfile`, `load`, `loadstring`
|
||||
- Remove: `rawget`, `rawset`, `rawequal`, `rawlen`
|
||||
- Remove: `collectgarbage`, `newproxy`
|
||||
- Remove: `string.dump`
|
||||
|
||||
3. Implement instruction hook:
|
||||
- `lua_sethook(L, InstructionHook, LUA_MASKCOUNT, 1000)`
|
||||
- Throw error when limit exceeded
|
||||
|
||||
4. Implement `ProtectBuiltinTables()`:
|
||||
- Set `__metatable` on string metatable
|
||||
- Freeze `_G` with `__newindex` error
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Lua library already linked (via RmlUi)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(LuaSandbox, DangerousGlobalsRemoved);
|
||||
TEST(LuaSandbox, BytecodeRejected);
|
||||
TEST(LuaSandbox, MemoryLimitEnforced);
|
||||
TEST(LuaSandbox, CPULimitEnforced);
|
||||
TEST(LuaSandbox, MetatableProtected);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 2: Permission System ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Gate API access based on app permissions.
|
||||
**Estimated Files**: 2 new files
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| PermissionGate | `src/main/cpp/sandbox/permission_gate.h` | Permission checking |
|
||||
| User gesture tracking | `src/main/cpp/sandbox/permission_gate.cpp` | Recent tap/click detection |
|
||||
| Permission categories | `src/main/cpp/sandbox/permission_gate.cpp` | Normal/Dangerous/Signature |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Define permission categories:
|
||||
```cpp
|
||||
enum class PermissionCategory { Normal, Dangerous, Signature };
|
||||
```
|
||||
|
||||
2. Create `PermissionGate` class:
|
||||
- `bool Check(lua_State* L, const std::string& permission)`
|
||||
- `int RequirePermission(lua_State* L, const char* perm)` - throws Lua error
|
||||
|
||||
3. Implement user gesture tracking:
|
||||
- `void RecordUserGesture()` - called on touch down
|
||||
- `bool HasRecentUserGesture(int ms)` - check within time window
|
||||
|
||||
4. Define permission manifest parsing:
|
||||
- Read `manifest.json` from app package
|
||||
- Extract `permissions` array
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 1 (LuaSandbox)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(PermissionGate, NormalPermissionAutoGranted);
|
||||
TEST(PermissionGate, DangerousPermissionRequiresGrant);
|
||||
TEST(PermissionGate, SignaturePermissionSystemOnly);
|
||||
TEST(PermissionGate, UserGestureRequired);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 3: Audit Logging & Rate Limiting ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Track security events and prevent API abuse.
|
||||
**Estimated Files**: 2 new files
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| AuditLog | `src/main/cpp/sandbox/audit_log.h/cpp` | Security event logging |
|
||||
| RateLimiter | `src/main/cpp/sandbox/rate_limiter.h/cpp` | Token bucket rate limiting |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Create `AuditLog` class:
|
||||
```cpp
|
||||
enum class AuditEvent {
|
||||
AppStart, AppStop, PermissionCheck, PermissionDenied,
|
||||
NetworkRequest, FileAccess, SandboxViolation, ResourceLimitHit
|
||||
};
|
||||
```
|
||||
|
||||
2. Implement thread-safe logging:
|
||||
- Ring buffer with max entries
|
||||
- Log critical events to Android logcat
|
||||
|
||||
3. Create `RateLimiter` class:
|
||||
- Token bucket algorithm
|
||||
- Per-operation limits: `network.request`, `storage.write`, etc.
|
||||
- `bool Check(const std::string& app_id, const std::string& operation)`
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 1 (LuaSandbox)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(AuditLog, LogsSecurityEvents);
|
||||
TEST(AuditLog, ThreadSafe);
|
||||
TEST(RateLimiter, EnforcesLimits);
|
||||
TEST(RateLimiter, RefillsOverTime);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 4: Safe Path & Require ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Secure file access within app sandbox.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| Path validation | `src/main/cpp/sandbox/path_sandbox.h/cpp` | Canonical path checking |
|
||||
| Safe require | `src/main/cpp/sandbox/path_sandbox.cpp` | Module loader from app/scripts/ |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Implement `ValidatePath()`:
|
||||
- Reject `..` traversal
|
||||
- Reject absolute paths
|
||||
- Canonicalize and verify prefix match
|
||||
|
||||
2. Implement `SafeRequire()`:
|
||||
- Validate module name (alphanumeric + underscore)
|
||||
- Load from `app_path/scripts/name.lua`
|
||||
- Cache in registry `__loaded`
|
||||
- Text-only mode (`"t"`)
|
||||
|
||||
3. Register as global `require`:
|
||||
```cpp
|
||||
lua_pushcfunction(L, SafeRequire);
|
||||
lua_setglobal(L, "require");
|
||||
```
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 1 (LuaSandbox)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(PathSandbox, RejectsTraversal);
|
||||
TEST(PathSandbox, RejectsAbsolutePaths);
|
||||
TEST(SafeRequire, LoadsFromScriptsDir);
|
||||
TEST(SafeRequire, CachesModules);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 5: Timer & Callback System ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Safe timer APIs managed by kernel.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| TimerManager | `src/main/cpp/sandbox/timer_manager.h/cpp` | setTimeout/setInterval |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Create `TimerManager` class:
|
||||
- Priority queue of pending timers
|
||||
- Per-app timer limits (max 100)
|
||||
- Minimum 10ms granularity
|
||||
|
||||
2. Implement Lua APIs:
|
||||
```lua
|
||||
setTimeout(callback, ms) -> id
|
||||
clearTimeout(id)
|
||||
setInterval(callback, ms) -> id
|
||||
clearInterval(id)
|
||||
```
|
||||
|
||||
3. Integrate with kernel main loop:
|
||||
- Check and fire timers each frame
|
||||
- Reset instruction count before callback
|
||||
|
||||
4. Implement cleanup:
|
||||
- `ClearAppTimers(app_id)` on app stop
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 1 (LuaSandbox)
|
||||
- Milestone 3 (RateLimiter)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(TimerManager, FiresTimeout);
|
||||
TEST(TimerManager, FiresInterval);
|
||||
TEST(TimerManager, LimitsPerApp);
|
||||
TEST(TimerManager, CleansUpOnStop);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 6: JSON & Crypto APIs ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Safe data parsing and cryptographic primitives.
|
||||
**Estimated Files**: 2 new files
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| JSON API | `src/main/cpp/sandbox/json_api.cpp` | Safe encode/decode |
|
||||
| Crypto API | `src/main/cpp/sandbox/crypto_api.cpp` | Hash, random, HMAC |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Implement `json.decode()`:
|
||||
- Depth limit (32)
|
||||
- String length limit (1 MB)
|
||||
- Array/object size limits
|
||||
|
||||
2. Implement `json.encode()`:
|
||||
- Cycle detection
|
||||
- Output size limit
|
||||
|
||||
3. Implement crypto APIs:
|
||||
- `crypto.randomBytes(n)` - CSPRNG
|
||||
- `crypto.hash("sha256", data)`
|
||||
- `crypto.hmac("sha256", key, data)`
|
||||
- Remove `math.randomseed`, replace `math.random` with per-app RNG
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 1 (LuaSandbox)
|
||||
- nlohmann-json (already in vcpkg)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(JsonApi, DecodesValid);
|
||||
TEST(JsonApi, RejectsDeepNesting);
|
||||
TEST(JsonApi, RejectsTooLarge);
|
||||
TEST(CryptoApi, RandomBytesSecure);
|
||||
TEST(CryptoApi, HashCorrect);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 7: Virtual Filesystem ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Per-app isolated storage with quotas.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| VirtualFS | `src/main/cpp/sandbox/virtual_fs.h/cpp` | App storage API |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Define virtual path mapping:
|
||||
```
|
||||
/data/ → /data/data/com.omixlab.mosis/apps/<app_id>/data/
|
||||
/cache/ → /data/data/com.omixlab.mosis/apps/<app_id>/cache/
|
||||
/temp/ → (session-only, cleared on stop)
|
||||
/shared/ → requires storage.shared permission
|
||||
```
|
||||
|
||||
2. Implement Lua file API:
|
||||
```lua
|
||||
fs.read(path) -> string
|
||||
fs.write(path, data) -> bool
|
||||
fs.append(path, data) -> bool
|
||||
fs.delete(path) -> bool
|
||||
fs.exists(path) -> bool
|
||||
fs.list(dir) -> table
|
||||
fs.mkdir(path) -> bool
|
||||
fs.stat(path) -> {size, modified, isDir}
|
||||
```
|
||||
|
||||
3. Enforce limits:
|
||||
- Per-app quota (50 MB default)
|
||||
- Max file size (10 MB)
|
||||
- Max path depth (10)
|
||||
|
||||
4. Cleanup `/temp/` on app stop.
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 1 (LuaSandbox)
|
||||
- Milestone 2 (PermissionGate)
|
||||
- Milestone 4 (Path validation)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(VirtualFS, ReadsWritesInAppDir);
|
||||
TEST(VirtualFS, BlocksTraversal);
|
||||
TEST(VirtualFS, EnforcesQuota);
|
||||
TEST(VirtualFS, CleansUpTemp);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 8: SQLite Database ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Per-app SQLite with injection prevention.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| DatabaseManager | `src/main/cpp/sandbox/database_manager.h/cpp` | SQLite sandbox |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Create per-app database:
|
||||
- Location: `/data/data/com.omixlab.mosis/apps/<app_id>/db/app.db`
|
||||
- Max database size: 50 MB
|
||||
|
||||
2. Implement SQLite authorizer:
|
||||
```cpp
|
||||
sqlite3_set_authorizer(db, Authorizer, sandbox);
|
||||
// Block: ATTACH, DETACH, dangerous PRAGMAs, load_extension
|
||||
```
|
||||
|
||||
3. Implement Lua API:
|
||||
```lua
|
||||
local db = database.open("mydata")
|
||||
db:execute("CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY, name TEXT)")
|
||||
db:execute("INSERT INTO items (name) VALUES (?)", {"Item 1"})
|
||||
local rows = db:query("SELECT * FROM items WHERE id > ?", {0})
|
||||
db:close()
|
||||
```
|
||||
|
||||
4. Enforce prepared statements only (no raw SQL interpolation).
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 1 (LuaSandbox)
|
||||
- Milestone 2 (PermissionGate)
|
||||
- SQLite3 (add to vcpkg)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(Database, CreatesTables);
|
||||
TEST(Database, PreparedStatements);
|
||||
TEST(Database, BlocksAttach);
|
||||
TEST(Database, BlocksDangerousPragma);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 9: Network - HTTP ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Secure HTTP requests with domain filtering.
|
||||
**Estimated Files**: 2 new files
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| HttpRequestValidator | `src/main/cpp/sandbox/http_validator.h/cpp` | URL/domain validation |
|
||||
| NetworkManager | `src/main/cpp/sandbox/network_manager.h/cpp` | HTTP client wrapper |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Implement URL parsing and validation:
|
||||
- Require HTTPS
|
||||
- Block private IPs, localhost, metadata IPs
|
||||
- Domain whitelist from manifest
|
||||
|
||||
2. Implement Lua HTTP API:
|
||||
```lua
|
||||
local response = network.request({
|
||||
url = "https://api.example.com/data",
|
||||
method = "POST",
|
||||
headers = {...},
|
||||
body = "...",
|
||||
timeout = 30000
|
||||
})
|
||||
```
|
||||
|
||||
3. Integrate with Android HttpURLConnection or libcurl.
|
||||
|
||||
4. Enforce limits:
|
||||
- Request body: 10 MB
|
||||
- Response body: 50 MB
|
||||
- Timeout: 60s
|
||||
- Concurrent requests: 6
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 1 (LuaSandbox)
|
||||
- Milestone 2 (PermissionGate)
|
||||
- Milestone 3 (RateLimiter, AuditLog)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(HttpValidator, BlocksPrivateIP);
|
||||
TEST(HttpValidator, BlocksLocalhost);
|
||||
TEST(HttpValidator, RequiresHttps);
|
||||
TEST(HttpValidator, EnforcesDomainWhitelist);
|
||||
TEST(NetworkManager, MakesRequest);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 10: Network - WebSocket ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Secure WebSocket connections.
|
||||
**Estimated Files**: 1 new file (extends NetworkManager)
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| WebSocketManager | `src/main/cpp/sandbox/websocket_manager.h/cpp` | WS connections |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Implement connection management:
|
||||
- Max 5 connections per app
|
||||
- Idle timeout: 5 minutes
|
||||
- Message size limit: 1 MB
|
||||
|
||||
2. Implement Lua WebSocket API:
|
||||
```lua
|
||||
local ws = network.websocket("wss://api.example.com/ws")
|
||||
ws:on("open", function() ... end)
|
||||
ws:on("message", function(data) ... end)
|
||||
ws:on("close", function(code, reason) ... end)
|
||||
ws:send(data)
|
||||
ws:close()
|
||||
```
|
||||
|
||||
3. Use same URL validation as HTTP.
|
||||
|
||||
4. Cleanup connections on app stop.
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 9 (HttpRequestValidator)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(WebSocketManager, Connects);
|
||||
TEST(WebSocketManager, LimitsPerApp);
|
||||
TEST(WebSocketManager, CleansUpOnStop);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 11: Virtual Hardware - Camera ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Camera access with mandatory indicators.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| CameraInterface | `src/main/cpp/sandbox/camera_interface.h/cpp` | Camera API |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Implement session management:
|
||||
- `startSession(options)` - requires permission + user gesture
|
||||
- `capturePhoto()` - returns frame data
|
||||
- `stopSession()`
|
||||
|
||||
2. Mandatory recording indicator:
|
||||
- Show in system UI (cannot be hidden by app)
|
||||
|
||||
3. Implement Lua API:
|
||||
```lua
|
||||
local session = camera.start({facing = "back", resolution = "720p"})
|
||||
session:on("frame", function(data) ... end)
|
||||
local photo = session:capture()
|
||||
session:stop()
|
||||
```
|
||||
|
||||
4. Rate limit: 1 session at a time, max 30 fps.
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 2 (PermissionGate + user gesture)
|
||||
- Milestone 3 (AuditLog)
|
||||
- Game engine camera bridge (future)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(CameraInterface, RequiresPermission);
|
||||
TEST(CameraInterface, RequiresUserGesture);
|
||||
TEST(CameraInterface, ShowsIndicator);
|
||||
TEST(CameraInterface, StopsOnAppStop);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 12: Virtual Hardware - Microphone ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Audio recording with mandatory indicators.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| MicrophoneInterface | `src/main/cpp/sandbox/microphone_interface.h/cpp` | Mic API |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Implement recording session:
|
||||
- `startRecording(options)` - requires permission + user gesture
|
||||
- `stopRecording()` - returns audio data
|
||||
|
||||
2. Mandatory recording indicator (same as camera).
|
||||
|
||||
3. Implement Lua API:
|
||||
```lua
|
||||
local recording = microphone.start({sampleRate = 44100, channels = 1})
|
||||
recording:on("data", function(samples) ... end)
|
||||
local audio = recording:stop()
|
||||
```
|
||||
|
||||
4. Rate limit: 1 recording at a time.
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 2 (PermissionGate + user gesture)
|
||||
- Milestone 3 (AuditLog)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(MicrophoneInterface, RequiresPermission);
|
||||
TEST(MicrophoneInterface, RequiresUserGesture);
|
||||
TEST(MicrophoneInterface, ShowsIndicator);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 13: Virtual Hardware - Audio Output ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Safe audio playback.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| AudioOutputInterface | `src/main/cpp/sandbox/audio_output.h/cpp` | Speaker API |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Implement playback:
|
||||
- `play(audioData, options)`
|
||||
- `stop()`
|
||||
- `setVolume(0.0-1.0)`
|
||||
|
||||
2. System volume limit (app cannot exceed system volume).
|
||||
|
||||
3. Implement Lua API:
|
||||
```lua
|
||||
local player = audio.play(soundData, {loop = false, volume = 0.8})
|
||||
player:on("ended", function() ... end)
|
||||
player:stop()
|
||||
```
|
||||
|
||||
4. Concurrent sound limit: 10 per app.
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 1 (LuaSandbox)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(AudioOutput, PlaysSound);
|
||||
TEST(AudioOutput, RespectsVolumeLimit);
|
||||
TEST(AudioOutput, LimitsConcurrent);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 14: Virtual Hardware - Location ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Location with privacy controls.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| LocationInterface | `src/main/cpp/sandbox/location_interface.h/cpp` | GPS API |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Two permission levels:
|
||||
- `location.coarse` - city-level (1km accuracy)
|
||||
- `location.fine` - precise GPS
|
||||
|
||||
2. Implement Lua API:
|
||||
```lua
|
||||
location.getCurrentPosition(function(pos)
|
||||
print(pos.latitude, pos.longitude, pos.accuracy)
|
||||
end)
|
||||
|
||||
local watch = location.watchPosition(function(pos) ... end, {
|
||||
enableHighAccuracy = true,
|
||||
timeout = 30000
|
||||
})
|
||||
watch:stop()
|
||||
```
|
||||
|
||||
3. Rate limit: 1 request per second.
|
||||
|
||||
4. Reduce precision for coarse permission.
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 2 (PermissionGate)
|
||||
- Milestone 3 (RateLimiter)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(LocationInterface, RequiresPermission);
|
||||
TEST(LocationInterface, CoarseReducesPrecision);
|
||||
TEST(LocationInterface, RateLimits);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 15: Virtual Hardware - Sensors ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Motion sensors with fingerprinting prevention.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| SensorInterface | `src/main/cpp/sandbox/sensor_interface.h/cpp` | Accelerometer, gyro, etc. |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Supported sensors:
|
||||
- Accelerometer (requires `sensors.motion`)
|
||||
- Gyroscope (requires `sensors.motion`)
|
||||
- Magnetometer (requires `sensors.motion`)
|
||||
- Proximity (auto-granted)
|
||||
- Ambient light (auto-granted)
|
||||
|
||||
2. Implement Lua API:
|
||||
```lua
|
||||
local sub = sensors.subscribe("accelerometer", function(data)
|
||||
print(data.x, data.y, data.z, data.timestamp)
|
||||
end, {frequency = 60})
|
||||
sub:stop()
|
||||
```
|
||||
|
||||
3. Reduce precision to prevent fingerprinting:
|
||||
- Round values to 2 decimal places
|
||||
- Limit update frequency to 60 Hz
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 2 (PermissionGate)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(SensorInterface, RequiresPermission);
|
||||
TEST(SensorInterface, ReducesPrecision);
|
||||
TEST(SensorInterface, LimitsFrequency);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 16: Virtual Hardware - Bluetooth ✅
|
||||
|
||||
**Status**: Complete
|
||||
|
||||
**Goal**: Bluetooth discovery and pairing.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| BluetoothInterface | `src/main/cpp/sandbox/bluetooth_interface.h/cpp` | BT API |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Discovery with user consent:
|
||||
- `startDiscovery()` requires user confirmation
|
||||
- Return device name/address only (no full UUID list)
|
||||
|
||||
2. Implement Lua API:
|
||||
```lua
|
||||
bluetooth.startDiscovery(function(devices)
|
||||
for _, device in ipairs(devices) do
|
||||
print(device.name, device.address)
|
||||
end
|
||||
end, {timeout = 30})
|
||||
|
||||
bluetooth.connect(address, function(connection)
|
||||
connection:send(data)
|
||||
end)
|
||||
```
|
||||
|
||||
3. Limit: 5 connections per app.
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 2 (PermissionGate + user gesture)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(BluetoothInterface, RequiresPermission);
|
||||
TEST(BluetoothInterface, RequiresUserConsent);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone 17: Virtual Hardware - Contacts ✅
|
||||
|
||||
**Status**: Complete
|
||||
|
||||
**Goal**: Contact access with granular permissions.
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| ContactsInterface | `src/main/cpp/sandbox/contacts_interface.h/cpp` | Contacts API |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Separate read/write permissions:
|
||||
- `contacts.read` - query contacts
|
||||
- `contacts.write` - add/modify contacts
|
||||
|
||||
2. Implement Lua API:
|
||||
```lua
|
||||
local contacts = contacts.query({search = "John"})
|
||||
for _, c in ipairs(contacts) do
|
||||
print(c.name, c.phone, c.email)
|
||||
end
|
||||
|
||||
contacts.add({name = "New Contact", phone = "555-1234"})
|
||||
```
|
||||
|
||||
3. Limit fields returned (no raw account data).
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 2 (PermissionGate)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(ContactsInterface, RequiresReadPermission);
|
||||
TEST(ContactsInterface, RequiresWritePermission);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Milestone 18: Inter-App Communication
|
||||
|
||||
**Goal**: Kernel-mediated message passing.
|
||||
**Status**: Complete
|
||||
**Estimated Files**: 1 new file
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| MessageBus | `src/main/cpp/sandbox/message_bus.h/cpp` | App-to-app messaging |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Implement intent system:
|
||||
- Manifest declares received intents
|
||||
- Sender must have required permissions
|
||||
|
||||
2. Implement Lua API:
|
||||
```lua
|
||||
-- Sending
|
||||
intents.send({
|
||||
action = "share",
|
||||
type = "text/plain",
|
||||
data = "Hello world"
|
||||
})
|
||||
|
||||
-- Receiving (in manifest + handler)
|
||||
intents.on("share", function(intent)
|
||||
print(intent.from, intent.data)
|
||||
end)
|
||||
```
|
||||
|
||||
3. Validate sender/receiver at runtime.
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestone 2 (PermissionGate)
|
||||
- Milestone 3 (AuditLog)
|
||||
|
||||
### Test Criteria
|
||||
|
||||
```cpp
|
||||
TEST(MessageBus, SendsToRegisteredReceiver);
|
||||
TEST(MessageBus, BlocksUnregisteredAction);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Milestone 19: Security Testing Suite
|
||||
|
||||
**Goal**: Comprehensive test coverage.
|
||||
**Status**: Complete
|
||||
**Estimated Files**: 3 new files
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| Unit tests | `tests/test_sandbox_security.cpp` | Core sandbox tests |
|
||||
| Integration tests | `tests/test_sandbox_integration.cpp` | Full system tests |
|
||||
| Fuzzer | `tests/fuzz_sandbox.cpp` | Random input testing |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. Write unit tests for all milestones (see individual test criteria).
|
||||
|
||||
2. Write integration tests:
|
||||
- Full app lifecycle
|
||||
- Permission flow
|
||||
- Resource cleanup
|
||||
|
||||
3. Implement fuzzer:
|
||||
- Generate random Lua code
|
||||
- Verify no crashes
|
||||
- Verify sandbox integrity after each run
|
||||
|
||||
4. Security audit checklist (from SANDBOX.md).
|
||||
|
||||
### Dependencies
|
||||
|
||||
- All previous milestones
|
||||
|
||||
---
|
||||
|
||||
## Milestone 20: Kernel Integration ✅
|
||||
|
||||
**Status**: Complete
|
||||
**Goal**: Multi-app sandbox orchestrator for kernel integration.
|
||||
|
||||
### Deliverables
|
||||
|
||||
| Component | File | Description |
|
||||
|-----------|------|-------------|
|
||||
| LuaSandboxManager | `src/main/cpp/sandbox/sandbox_manager.h` | Multi-app orchestrator |
|
||||
| Implementation | `src/main/cpp/sandbox/sandbox_manager.cpp` | App lifecycle management |
|
||||
| AppSandbox struct | `src/main/cpp/sandbox/sandbox_manager.h` | Per-app component container |
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
1. ✅ Create `LuaSandboxManager` class:
|
||||
- Multi-app management with Start/Stop lifecycle
|
||||
- Shared components (AuditLog, RateLimiter, MessageBus, TimerManager)
|
||||
- Thread-safe app map access
|
||||
|
||||
2. ✅ Create `AppSandbox` struct:
|
||||
- Per-app isolated Lua state and permissions
|
||||
- Per-app VirtualFS, DatabaseManager, NetworkManager
|
||||
- Per-app hardware interfaces (camera, mic, audio, location, sensors, bluetooth, contacts)
|
||||
|
||||
3. ✅ Wire up resource cleanup on app stop:
|
||||
- Clear timers, close websockets, shutdown hardware
|
||||
- Clean temp files, close databases, unregister from message bus
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Milestones 1-19
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Phase | Milestones | Description |
|
||||
|-------|------------|-------------|
|
||||
| **Foundation** | 1-4 | Core sandbox, permissions, logging, paths |
|
||||
| **Core APIs** | 5-8 | Timers, JSON, crypto, filesystem, database |
|
||||
| **Network** | 9-10 | HTTP and WebSocket |
|
||||
| **Hardware** | 11-17 | Camera, mic, audio, location, sensors, BT, contacts |
|
||||
| **System** | 18-20 | IPC, testing, integration |
|
||||
|
||||
### Recommended Order
|
||||
|
||||
1. **Milestone 1** - Must be first (foundation)
|
||||
2. **Milestone 2** - Permissions (needed by everything)
|
||||
3. **Milestone 3** - Audit/rate limiting (needed by APIs)
|
||||
4. **Milestone 4** - Path security (needed by fs/require)
|
||||
5. **Milestone 5-6** - Timers, JSON (high value)
|
||||
6. **Milestone 7-8** - Storage, database (app data)
|
||||
7. **Milestone 9-10** - Network (app connectivity)
|
||||
8. **Milestones 11-17** - Hardware (as needed)
|
||||
9. **Milestone 18** - IPC (multi-app)
|
||||
10. **Milestone 19-20** - Testing & integration
|
||||
|
||||
### Quick Start
|
||||
|
||||
Begin with **Milestone 1** to establish the core sandbox. This is the foundation everything else builds on.
|
||||
Reference in New Issue
Block a user