move docs to docs/ folder, merge architecture files, update references

docs/LUA-SANDBOX.md

@@ -0,0 +1,126 @@
+# Lua Sandbox System
+
+The sandbox provides secure, isolated Lua environments for third-party apps.
+
+## Security Features
+
+| Feature | Implementation |
+|---------|----------------|
+| Dangerous globals removed | `os`, `io`, `loadfile`, `dofile`, `debug` |
+| Memory limits | Configurable per-app (default 10MB) |
+| CPU limits | Instruction counting with timeout |
+| Bytecode rejected | Only source code allowed |
+| Metatables protected | Cannot modify string/table metatables |
+| Path traversal blocked | `../` and absolute paths rejected |
+
+## Permission Categories
+
+| Category | Auto-Grant | Examples |
+|----------|------------|----------|
+| Normal | Yes | `storage`, `network` |
+| Dangerous | User consent | `camera`, `microphone`, `location`, `contacts` |
+| Signature | System apps only | `system_settings`, `install_packages` |
+
+## Available APIs
+
+**Core APIs** (always available):
+```lua
+-- Timers
+local id = setTimeout(function() end, 1000)
+clearTimeout(id)
+local id = setInterval(function() end, 500)
+clearInterval(id)
+
+-- JSON
+local obj = json.decode('{"key": "value"}')
+local str = json.encode({key = "value"})
+
+-- Crypto
+local bytes = crypto.randomBytes(16)
+local hash = crypto.sha256("data")
+local hmac = crypto.hmac("sha256", "key", "data")
+```
+
+**Storage APIs** (requires `storage` permission):
+```lua
+-- Virtual filesystem (sandboxed to app directory)
+fs.write("data.txt", "content")
+local content = fs.read("data.txt")
+local files = fs.list("/")
+local stat = fs.stat("data.txt")
+fs.delete("data.txt")
+
+-- SQLite database
+local db = database.open("mydb")
+db:execute("CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY, name TEXT)")
+db:execute("INSERT INTO items (name) VALUES (?)", {"item1"})
+local rows = db:query("SELECT * FROM items WHERE id = ?", {1})
+```
+
+**Network APIs** (requires `network` permission):
+```lua
+-- HTTP (HTTPS only, private IPs blocked)
+local response = http.get("https://api.example.com/data")
+local response = http.post("https://api.example.com/data", {
+    headers = {["Content-Type"] = "application/json"},
+    body = json.encode({key = "value"})
+})
+
+-- WebSocket
+local ws = websocket.connect("wss://example.com/ws")
+ws:send("message")
+ws:onMessage(function(data) end)
+ws:close()
+```
+
+**Hardware APIs** (requires dangerous permissions + user gesture):
+```lua
+-- Camera (requires camera permission)
+camera.start(function(frame) end)
+camera.stop()
+
+-- Microphone (requires microphone permission)
+microphone.start(function(samples) end)
+microphone.stop()
+
+-- Location (requires location permission)
+location.getCurrentPosition(function(pos)
+    print(pos.latitude, pos.longitude)
+end)
+
+-- Sensors (requires sensors permission)
+sensors.subscribe("accelerometer", function(data)
+    print(data.x, data.y, data.z)
+end)
+```
+
+## Running Sandbox Tests
+
+```bash
+cd sandbox-test
+cmake -B build -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
+cmake --build build --config Debug
+./build/Debug/sandbox-test.exe
+
+# Output: 149 tests, all passing
+```
+
+## Test Categories
+
+| Category | Tests | Description |
+|----------|-------|-------------|
+| Security | 11 | Globals removal, bytecode, metatables |
+| Resources | 8 | Memory, CPU limits, instruction counting |
+| Permissions | 7 | Normal/dangerous/signature grants |
+| Rate Limiting | 6 | API call throttling |
+| Timers | 7 | setTimeout/setInterval behavior |
+| JSON | 5 | Encode/decode, depth limits |
+| Crypto | 4 | Random, SHA256, HMAC |
+| VirtualFS | 8 | Read/write, quotas, traversal |
+| Database | 8 | SQLite operations, injection prevention |
+| Network | 8 | URL validation, private IP blocking |
+| WebSocket | 7 | Connection limits, message size |
+| Hardware | 42 | Camera, mic, location, sensors, bluetooth |
+| IPC | 7 | Message bus between apps |
+| Integration | 9 | Full app lifecycle |
+| Fuzzing | 3 | Random input crash testing |