# Mosis Lua Sandbox Security

**Status**: Design Phase
**Goal**: Secure app isolation with defense-in-depth approach.

---

## Overview

Third-party apps run in isolated Lua environments with restricted access to system resources. Each app gets its own `lua_State` with carefully controlled APIs.

```
┌─────────────────────────────────────────────────────────────────────┐
│                         Mosis Kernel                                 │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                    LuaSandboxManager                           │  │
│  │  - Creates per-app lua_State with custom allocator             │  │
│  │  - Enforces memory/CPU limits                                  │  │
│  │  - Routes permission-gated API calls                           │  │
│  └───────────────────────────────────────────────────────────────┘  │
│          │                    │                    │                 │
│          ▼                    ▼                    ▼                 │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐          │
│  │ App A State  │    │ App B State  │    │ App C State  │          │
│  │ (isolated)   │    │ (isolated)   │    │ (isolated)   │          │
│  └──────────────┘    └──────────────┘    └──────────────┘          │
│         │                   │                   │                   │
│         └───────────────────┴───────────────────┘                   │
│                             │                                        │
│                    ┌────────▼────────┐                              │
│                    │ Permission Gate │                              │
│                    └────────┬────────┘                              │
│                             │                                        │
│  ┌──────────────────────────▼──────────────────────────────────┐   │
│  │                    System Services                           │   │
│  │  Camera │ Network │ Storage │ Contacts │ Messages │ ...     │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Threat Model

### Threat Categories

| Category | Threat | Severity | Mitigation |
|----------|--------|----------|------------|
| **Code Execution** | `os.execute()`, `io.popen()` | Critical | Remove globals |
| **File Access** | `io.open()`, `loadfile()` | Critical | Remove globals |
| **Bytecode Injection** | `load()` with binary chunks | Critical | Text-only loading |
| **Memory Exhaustion** | Infinite tables/strings | High | Custom allocator with limits |
| **CPU Exhaustion** | Infinite loops | High | Instruction count hook |
| **Sandbox Escape** | `debug.getregistry()` | Critical | Remove debug library |
| **Global Pollution** | Modifying `_G`, `string` | Medium | Frozen globals |
| **Path Traversal** | `require("../../etc/passwd")` | Critical | Path validation |
| **Data Exfiltration** | Unauthorized network access | High | Permission-gated network |
| **Privilege Escalation** | Access other app's data | High | Per-app storage isolation |
| **Timing Attacks** | High-resolution timers | Low | Limit timer precision |
| **Side Channels** | Memory/CPU usage patterns | Low | Rate limiting |

### Attacker Capabilities

We assume a malicious app developer can:
- Write arbitrary Lua code within the sandbox
- Attempt to exploit any exposed API
- Try to escape the sandbox via Lua language features
- Attempt DoS via resource exhaustion
- Try to access other apps' data
- Attempt to exfiltrate user data

---

## Security Layers

### Layer 1: Dangerous Globals Removal

**Status**: Designed

Remove all dangerous functions before any app code runs.

```cpp
void RemoveDangerousGlobals(lua_State* L) {
    const char* dangerous[] = {
        // Execution
        "dofile", "loadfile", "load", "loadstring",

        // Raw access (bypass metatables)
        "rawget", "rawset", "rawequal", "rawlen",

        // Metatable manipulation
        "getmetatable", "setmetatable",

        // GC manipulation
        "collectgarbage",

        // Must not exist
        "os", "io", "debug", "package", "require",
        "ffi", "jit", "newproxy",

        nullptr
    };

    for (const char** p = dangerous; *p; ++p) {
        lua_pushnil(L);
        lua_setglobal(L, *p);
    }

    // Remove string.dump (creates bytecode)
    lua_getglobal(L, "string");
    lua_pushnil(L);
    lua_setfield(L, -2, "dump");
    lua_pop(L, 1);
}
```

**Safe globals retained**:
- `print` (redirected to logger)
- `type`, `tonumber`, `tostring`
- `pairs`, `ipairs`, `next`
- `pcall`, `xpcall`
- `assert`, `error`
- `select`, `unpack`
- `string.*` (except `dump`)
- `table.*`
- `math.*`
- `utf8.*`

### Layer 2: Bytecode Prevention

**Status**: Designed

Prevent loading of binary Lua chunks which can bypass sandbox checks.

```cpp
// Only allow text chunks, reject bytecode
int result = luaL_loadbufferx(L, code, len, name, "t");
//                                              mode: "t" = text only
```

Bytecode starts with `\27Lua` signature - the "t" mode rejects this.

### Layer 3: Memory Limits

**Status**: Designed

Custom allocator tracks and limits memory usage per app.

```cpp
void* SandboxAlloc(void* ud, void* ptr, size_t osize, size_t nsize) {
    auto* sandbox = static_cast<LuaSandbox*>(ud);

    size_t new_usage = sandbox->m_memory_used - osize + nsize;

    if (nsize > 0 && new_usage > sandbox->m_limits.memory_bytes) {
        return nullptr;  // Allocation fails
    }

    sandbox->m_memory_used = new_usage;

    if (nsize == 0) {
        free(ptr);
        return nullptr;
    }
    return realloc(ptr, nsize);
}

lua_State* L = lua_newstate(SandboxAlloc, sandbox);
```

**Default limits**:
| Resource | Limit | Rationale |
|----------|-------|-----------|
| Memory | 16 MB | Enough for UI, prevents DoS |
| String size | 1 MB | Prevent single huge allocation |
| Table entries | 100,000 | Prevent hash DoS |

### Layer 4: CPU Limits

**Status**: Designed

Instruction count hook prevents infinite loops and excessive computation.

```cpp
void InstructionHook(lua_State* L, lua_Debug* ar) {
    auto* sandbox = GetSandbox(L);
    sandbox->m_instructions += 1000;

    if (sandbox->m_instructions > sandbox->m_limits.instructions) {
        luaL_error(L, "instruction limit exceeded");
    }
}

lua_sethook(L, InstructionHook, LUA_MASKCOUNT, 1000);
```

**Default limits**:
| Context | Limit | Approx Time |
|---------|-------|-------------|
| Event handler | 1,000,000 | ~10ms |
| Frame update | 100,000 | ~1ms |
| App initialization | 10,000,000 | ~100ms |

### Layer 5: Path Sandboxing

**Status**: Designed

All file access restricted to app's own directory.

```cpp
bool ValidatePath(const std::string& app_path, const std::string& requested) {
    // Reject obvious traversal attempts
    if (requested.find("..") != std::string::npos) return false;
    if (requested.find(':') != std::string::npos) return false;  // Windows drive
    if (requested[0] == '/' || requested[0] == '\\') return false;  // Absolute

    // Canonicalize and verify within app directory
    std::filesystem::path base = std::filesystem::canonical(app_path);
    std::filesystem::path full = std::filesystem::weakly_canonical(
        base / requested
    );

    // Must be within app directory
    auto [base_end, full_it] = std::mismatch(
        base.begin(), base.end(), full.begin()
    );
    return base_end == base.end();
}
```

### Layer 6: Safe `require` Replacement

**Status**: Designed

Custom module loader only loads from app's scripts directory.

```cpp
int SafeRequire(lua_State* L) {
    const char* module = luaL_checkstring(L, 1);
    auto* sandbox = GetSandbox(L);

    // Validate module name
    std::string name(module);
    if (!IsValidModuleName(name)) {
        return luaL_error(L, "invalid module name");
    }

    // Check cache
    lua_getfield(L, LUA_REGISTRYINDEX, "__loaded");
    lua_getfield(L, -1, module);
    if (!lua_isnil(L, -1)) return 1;
    lua_pop(L, 2);

    // Load from app/scripts/name.lua
    std::string path = sandbox->app_path + "/scripts/" + name + ".lua";
    if (!ValidatePath(sandbox->app_path, "scripts/" + name + ".lua")) {
        return luaL_error(L, "path validation failed");
    }

    // Load as text only
    if (luaL_loadfilex(L, path.c_str(), "t") != LUA_OK) {
        return lua_error(L);
    }

    // Execute and cache
    lua_call(L, 0, 1);
    lua_getfield(L, LUA_REGISTRYINDEX, "__loaded");
    lua_pushvalue(L, -2);
    lua_setfield(L, -2, module);
    lua_pop(L, 1);

    return 1;
}
```

### Layer 7: Metatable Protection

**Status**: Designed

Prevent modification of built-in metatables and sandbox escape via metatables.

```cpp
void ProtectBuiltinTables(lua_State* L) {
    // Protect string metatable
    lua_pushstring(L, "");
    lua_getmetatable(L, -1);
    lua_pushstring(L, "string");
    lua_setfield(L, -2, "__metatable");  // Prevents getmetatable
    lua_pop(L, 2);

    // Freeze _G
    lua_pushglobaltable(L);
    lua_newtable(L);
    lua_pushstring(L, "globals");
    lua_setfield(L, -2, "__metatable");
    lua_pushcfunction(L, [](lua_State* L) -> int {
        return luaL_error(L, "cannot modify global environment");
    });
    lua_setfield(L, -2, "__newindex");
    lua_setmetatable(L, -2);
    lua_pop(L, 1);
}
```

**Safe metatable access**:
```cpp
// getmetatable returns __metatable field (not real metatable)
// setmetatable blocked on protected tables
```

### Layer 8: Permission-Gated APIs

**Status**: Designed

Sensitive APIs check permissions before execution.

```cpp
class PermissionGate {
public:
    static bool Check(lua_State* L, const std::string& permission) {
        auto* sandbox = GetSandbox(L);
        auto& perms = sandbox->m_context.permissions;
        return std::find(perms.begin(), perms.end(), permission) != perms.end();
    }

    static int RequirePermission(lua_State* L, const char* perm) {
        if (!Check(L, perm)) {
            return luaL_error(L, "permission denied: %s", perm);
        }
        return 0;
    }
};

// Usage in API
int CameraCapture(lua_State* L) {
    PermissionGate::RequirePermission(L, "camera");
    // ... actual implementation
}
```

**Permission categories**:

| Permission | Required For | Risk Level |
|------------|--------------|------------|
| `storage` | App-private file access | Normal (auto-granted) |
| `camera` | Camera access | Dangerous |
| `microphone` | Audio recording | Dangerous |
| `location` | GPS/location | Dangerous |
| `contacts.read` | Read contacts | Dangerous |
| `contacts.write` | Modify contacts | Dangerous |
| `network` | HTTP requests | Dangerous |
| `network.websocket` | WebSocket connections | Dangerous |
| `bluetooth` | Bluetooth access | Dangerous |
| `system.notifications` | Show notifications | Normal |

---

## Additional Security Measures

### Network Request Sandboxing

**Status**: Planned

Network requests are proxied through the kernel with domain filtering.

```cpp
struct NetworkPolicy {
    std::vector<std::string> allowed_domains;  // Whitelist
    std::vector<std::string> blocked_domains;  // Blacklist
    bool allow_localhost = false;
    bool allow_private_ips = false;
    size_t max_request_size = 10 * 1024 * 1024;   // 10 MB
    size_t max_response_size = 50 * 1024 * 1024;  // 50 MB
    int timeout_ms = 30000;
};

class NetworkSandbox {
public:
    bool ValidateRequest(const HttpRequest& req) {
        // Parse URL
        auto url = ParseUrl(req.url);

        // Block private IPs
        if (!m_policy.allow_private_ips && IsPrivateIP(url.host)) {
            return false;
        }

        // Block localhost
        if (!m_policy.allow_localhost && IsLocalhost(url.host)) {
            return false;
        }

        // Check domain whitelist/blacklist
        if (!m_policy.allowed_domains.empty()) {
            if (!MatchesDomain(url.host, m_policy.allowed_domains)) {
                return false;
            }
        }
        if (MatchesDomain(url.host, m_policy.blocked_domains)) {
            return false;
        }

        // Size limits
        if (req.body.size() > m_policy.max_request_size) {
            return false;
        }

        return true;
    }

private:
    bool IsPrivateIP(const std::string& host) {
        // 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 169.254.x.x
        // Also check for IPv6 private ranges
    }
};
```

**Manifest declaration**:
```json
{
  "permissions": ["network"],
  "network": {
    "allowed_domains": [
      "api.example.com",
      "*.cdn.example.com"
    ]
  }
}
```

### Timer and Callback Security

**Status**: Planned

Timers and callbacks are managed by the kernel, not exposed directly.

```cpp
class TimerManager {
public:
    uint32_t SetTimeout(LuaSandbox* sandbox, int callback_ref, int ms) {
        // Validate delay
        if (ms < 0) return 0;
        if (ms < 10) ms = 10;  // Minimum 10ms granularity

        // Limit active timers per app
        if (m_app_timers[sandbox->app_id()].size() >= MAX_TIMERS_PER_APP) {
            return 0;
        }

        Timer timer{
            .id = ++m_next_id,
            .sandbox = sandbox,
            .callback_ref = callback_ref,
            .fire_time = Now() + ms,
            .repeat = false
        };

        m_timers.push(timer);
        m_app_timers[sandbox->app_id()].insert(timer.id);
        return timer.id;
    }

    void ClearAppTimers(const std::string& app_id) {
        // Called when app is stopped
        for (uint32_t id : m_app_timers[app_id]) {
            // Mark timer as cancelled
        }
        m_app_timers.erase(app_id);
    }

private:
    static constexpr size_t MAX_TIMERS_PER_APP = 100;
};
```

**Lua API**:
```lua
-- Safe timer APIs (kernel-managed)
local id = setTimeout(function()
    print("fired!")
end, 1000)

clearTimeout(id)

local id = setInterval(function()
    print("tick")
end, 1000)

clearInterval(id)
```

### Inter-App Communication

**Status**: Planned

Apps communicate through kernel-mediated message passing.

```cpp
struct AppMessage {
    std::string from_app;
    std::string to_app;
    std::string action;
    std::string data;  // JSON
    std::vector<std::string> required_permissions;
};

class MessageBus {
public:
    bool Send(const AppMessage& msg) {
        // Validate sender
        if (!IsAppRunning(msg.from_app)) return false;

        // Check if target accepts this action
        if (!CanReceive(msg.to_app, msg.action)) return false;

        // Check permissions
        for (const auto& perm : msg.required_permissions) {
            if (!HasPermission(msg.from_app, perm)) return false;
        }

        // Deliver (async)
        QueueMessage(msg);
        return true;
    }
};
```

**Manifest declaration**:
```json
{
  "intents": {
    "receive": [
      {
        "action": "share",
        "types": ["image/*", "text/plain"]
      }
    ],
    "send": [
      "share", "view"
    ]
  }
}
```

### Audit Logging

**Status**: Planned

All security-relevant operations are logged for debugging and forensics.

```cpp
enum class AuditEvent {
    AppStart,
    AppStop,
    PermissionCheck,
    PermissionDenied,
    NetworkRequest,
    FileAccess,
    StorageAccess,
    TimerCreated,
    MessageSent,
    SandboxViolation,
    ResourceLimitHit
};

struct AuditEntry {
    std::chrono::system_clock::time_point timestamp;
    std::string app_id;
    AuditEvent event;
    std::string detail;
    bool success;
};

class AuditLog {
public:
    void Log(const AuditEntry& entry) {
        // Thread-safe append
        std::lock_guard lock(m_mutex);
        m_entries.push_back(entry);

        // Trim old entries
        if (m_entries.size() > MAX_ENTRIES) {
            m_entries.erase(m_entries.begin(),
                           m_entries.begin() + TRIM_COUNT);
        }

        // Log security events to system log
        if (entry.event == AuditEvent::SandboxViolation ||
            entry.event == AuditEvent::PermissionDenied) {
            Logger::Warn("[SECURITY] {} - {} - {}",
                        entry.app_id, EventName(entry.event), entry.detail);
        }
    }

    std::vector<AuditEntry> GetAppLogs(const std::string& app_id, size_t limit);
};
```

### Coroutine Safety

**Status**: Planned

Coroutines are allowed but resource-tracked.

```cpp
void SetupSafeCoroutines(lua_State* L) {
    // Allow coroutine.* but track
    luaL_requiref(L, "coroutine", luaopen_coroutine, 1);
    lua_pop(L, 1);

    // Wrap coroutine.create to track
    lua_getglobal(L, "coroutine");
    lua_getfield(L, -1, "create");
    lua_pushcclosure(L, [](lua_State* L) -> int {
        auto* sandbox = GetSandbox(L);

        // Limit active coroutines
        if (sandbox->m_coroutine_count >= MAX_COROUTINES) {
            return luaL_error(L, "too many coroutines");
        }

        // Call original create
        lua_pushvalue(L, lua_upvalueindex(1));
        lua_pushvalue(L, 1);
        lua_call(L, 1, 1);

        sandbox->m_coroutine_count++;
        return 1;
    }, 1);
    lua_setfield(L, -2, "create");
    lua_pop(L, 1);
}
```

### String Pattern DoS Prevention

**Status**: Planned

Complex regex patterns can cause catastrophic backtracking.

```cpp
int SafeStringMatch(lua_State* L) {
    size_t slen, plen;
    const char* s = luaL_checklstring(L, 1, &slen);
    const char* p = luaL_checklstring(L, 2, &plen);

    // Limit pattern complexity
    if (plen > 256) {
        return luaL_error(L, "pattern too long");
    }

    // Count pattern operators
    int complexity = 0;
    for (size_t i = 0; i < plen; i++) {
        if (p[i] == '*' || p[i] == '+' || p[i] == '-' || p[i] == '?') {
            complexity++;
        }
    }

    // Reject overly complex patterns
    if (complexity > 10) {
        return luaL_error(L, "pattern too complex");
    }

    // Also limit based on string length * complexity
    if (slen * complexity > 1000000) {
        return luaL_error(L, "operation too expensive");
    }

    // Call original
    return original_match(L);
}
```

---

## Runtime Security Audit

### Audit Function

```cpp
std::vector<SecurityIssue> AuditSandbox(lua_State* L) {
    std::vector<SecurityIssue> issues;

    // Check dangerous globals
    const char* dangerous[] = {
        "os", "io", "debug", "package", "ffi", "jit",
        "dofile", "loadfile", "load", "loadstring",
        "rawget", "rawset", "rawequal", "rawlen",
        "collectgarbage", "newproxy",
        nullptr
    };

    for (const char** p = dangerous; *p; ++p) {
        lua_getglobal(L, *p);
        if (!lua_isnil(L, -1)) {
            issues.push_back({
                .severity = Severity::Critical,
                .type = "dangerous_global",
                .detail = *p
            });
        }
        lua_pop(L, 1);
    }

    // Check string.dump
    lua_getglobal(L, "string");
    if (lua_istable(L, -1)) {
        lua_getfield(L, -1, "dump");
        if (!lua_isnil(L, -1)) {
            issues.push_back({
                .severity = Severity::Critical,
                .type = "bytecode_dump",
                .detail = "string.dump exists"
            });
        }
        lua_pop(L, 1);
    }
    lua_pop(L, 1);

    // Check instruction hook
    if (lua_gethook(L) == nullptr) {
        issues.push_back({
            .severity = Severity::High,
            .type = "no_cpu_limit",
            .detail = "instruction hook not set"
        });
    }

    // Check allocator (verify it's our sandbox allocator)
    // ...

    return issues;
}
```

### Startup Audit

```cpp
bool LuaSandbox::Initialize() {
    SetupSandbox();

    // Audit before running any app code
    auto issues = AuditSandbox(L);
    for (const auto& issue : issues) {
        if (issue.severity == Severity::Critical) {
            Logger::Error("Sandbox audit failed: {} - {}",
                         issue.type, issue.detail);
            return false;
        }
    }

    return true;
}
```

---

## Testing Strategy

### Unit Tests

```cpp
// test_sandbox_security.cpp

TEST(LuaSandbox, DangerousGlobalsRemoved) {
    LuaSandbox sandbox(TestContext());

    EXPECT_FALSE(sandbox.LoadString("return os"));
    EXPECT_FALSE(sandbox.LoadString("return io"));
    EXPECT_FALSE(sandbox.LoadString("return debug"));
    EXPECT_FALSE(sandbox.LoadString("os.execute('ls')"));
    EXPECT_FALSE(sandbox.LoadString("io.open('/etc/passwd')"));
}

TEST(LuaSandbox, BytecodeRejected) {
    LuaSandbox sandbox(TestContext());

    // Try to load bytecode
    EXPECT_FALSE(sandbox.LoadString("\x1bLuaS\x00..."));
    EXPECT_TRUE(sandbox.GetLastError().find("binary") != std::string::npos);
}

TEST(LuaSandbox, MemoryLimitEnforced) {
    SandboxLimits limits;
    limits.memory_limit_bytes = 1024 * 1024;  // 1 MB

    LuaSandbox sandbox(TestContext(limits));

    EXPECT_FALSE(sandbox.LoadString(R"(
        local t = {}
        while true do
            t[#t+1] = string.rep('x', 100000)
        end
    )"));
}

TEST(LuaSandbox, CPULimitEnforced) {
    SandboxLimits limits;
    limits.instruction_limit = 10000;

    LuaSandbox sandbox(TestContext(limits));

    EXPECT_FALSE(sandbox.LoadString("while true do end"));
    EXPECT_TRUE(sandbox.GetLastError().find("instruction") != std::string::npos);
}

TEST(LuaSandbox, PathTraversalBlocked) {
    LuaSandbox sandbox(TestContext());

    EXPECT_FALSE(sandbox.LoadString("require('../../../etc/passwd')"));
    EXPECT_FALSE(sandbox.LoadString("require('..\\\\..\\\\..\\\\windows\\\\system32\\\\config')"));
    EXPECT_FALSE(sandbox.LoadString("require('/etc/passwd')"));
    EXPECT_FALSE(sandbox.LoadString("require('C:\\\\Windows\\\\System32\\\\config')"));
}

TEST(LuaSandbox, MetatableProtected) {
    LuaSandbox sandbox(TestContext());

    // Cannot access string metatable internals
    EXPECT_TRUE(sandbox.LoadString(R"(
        local mt = getmetatable("")
        assert(mt == "string", "metatable should be protected")
    )"));

    // Cannot modify globals
    EXPECT_FALSE(sandbox.LoadString("_G.print = nil"));
}

TEST(LuaSandbox, SafeOperationsWork) {
    LuaSandbox sandbox(TestContext());

    EXPECT_TRUE(sandbox.LoadString(R"(
        -- Math
        local x = math.sin(1.5) + math.floor(3.7)

        -- String
        local s = string.format("hello %d", 42)
        local upper = string.upper("test")

        -- Table
        local t = {1, 2, 3}
        table.insert(t, 4)
        table.sort(t)

        -- Iteration
        for i, v in ipairs(t) do end
        for k, v in pairs({a=1, b=2}) do end

        -- Error handling
        local ok, err = pcall(function() error("test") end)
        assert(not ok)

        -- Type checks
        assert(type({}) == "table")
        assert(type("") == "string")
    )"));
}
```

### Fuzzing

```cpp
// Fuzz the sandbox with random Lua code
void FuzzSandbox() {
    std::random_device rd;
    std::mt19937 gen(rd());

    for (int i = 0; i < 10000; i++) {
        std::string code = GenerateRandomLuaCode(gen);

        LuaSandbox sandbox(TestContext());
        sandbox.LoadString(code);  // Should never crash

        // Verify sandbox integrity after each run
        auto issues = AuditSandbox(sandbox.GetState());
        ASSERT(issues.empty()) << "Sandbox compromised by: " << code;
    }
}
```

---

## Implementation Status

### Core Sandbox (Milestone 1)

| Component | Status | File |
|-----------|--------|------|
| LuaSandbox class | ✅ Implemented | `src/main/cpp/sandbox/lua_sandbox.h/cpp` |
| Custom allocator | ✅ Implemented | `src/main/cpp/sandbox/lua_sandbox.cpp` |
| Instruction hook | ✅ Implemented | `src/main/cpp/sandbox/lua_sandbox.cpp` |
| Globals removal | ✅ Implemented | `src/main/cpp/sandbox/lua_sandbox.cpp` |
| Bytecode prevention | ✅ Implemented | `src/main/cpp/sandbox/lua_sandbox.cpp` |
| Safe require | ❌ Planned | Milestone 4 |
| Metatable protection | ✅ Implemented | `src/main/cpp/sandbox/lua_sandbox.cpp` |
| Path validation | ❌ Planned | Milestone 4 |

### APIs

| Component | Status | File |
|-----------|--------|------|
| Storage API | ❌ Planned | Milestone 7 |
| Timer API | ❌ Planned | Milestone 5 |
| Network API | ❌ Planned | Milestone 9-10 |
| RmlUi bridge | ❌ Planned | Milestone 20 |

### Security

| Component | Status | File |
|-----------|--------|------|
| Permission gate | ❌ Planned | Milestone 2 |
| Audit logging | ❌ Planned | Milestone 3 |
| Network sandbox | ❌ Planned | Milestone 9 |
| Message bus | ❌ Planned | Milestone 18 |

### Testing

| Component | Status | File |
|-----------|--------|------|
| Unit tests | ✅ Implemented | `sandbox-test/` (11 tests) |
| Integration tests | ❌ Planned | Milestone 19 |
| Fuzzing | ❌ Planned | Milestone 19 |

---

## Additional Security Measures (Continued)

### JSON Parsing Security

**Status**: Planned

Untrusted JSON from network/storage must be safely parsed.

```cpp
struct JsonLimits {
    size_t max_depth = 32;
    size_t max_string_length = 1024 * 1024;  // 1 MB
    size_t max_array_elements = 100000;
    size_t max_object_keys = 10000;
};

int SafeJsonDecode(lua_State* L) {
    size_t len;
    const char* json = luaL_checklstring(L, 1, &len);

    // Size check
    if (len > 10 * 1024 * 1024) {  // 10 MB max
        return luaL_error(L, "JSON too large");
    }

    auto* sandbox = GetSandbox(L);

    try {
        auto parsed = ParseJsonWithLimits(json, len, sandbox->json_limits);
        PushJsonValue(L, parsed);
        return 1;
    } catch (const JsonDepthError&) {
        return luaL_error(L, "JSON nesting too deep");
    } catch (const JsonSizeError&) {
        return luaL_error(L, "JSON element too large");
    }
}
```

**Lua API**:
```lua
local data = json.decode(json_string)  -- Safe parsing
local str = json.encode(table)          -- Safe encoding
```

### Cryptographic APIs

**Status**: Planned

Provide safe crypto primitives (apps shouldn't implement their own).

```cpp
void SetupCryptoAPI(lua_State* L) {
    lua_newtable(L);

    // crypto.randomBytes(n) - cryptographically secure random
    lua_pushcfunction(L, [](lua_State* L) -> int {
        int n = luaL_checkinteger(L, 1);
        if (n < 1 || n > 1024) {
            return luaL_error(L, "invalid byte count (1-1024)");
        }

        std::vector<uint8_t> bytes(n);
        if (!CSPRNG(bytes.data(), n)) {
            return luaL_error(L, "random generation failed");
        }

        lua_pushlstring(L, reinterpret_cast<char*>(bytes.data()), n);
        return 1;
    });
    lua_setfield(L, -2, "randomBytes");

    // crypto.hash(algorithm, data) - SHA-256, SHA-512
    lua_pushcfunction(L, [](lua_State* L) -> int {
        const char* algo = luaL_checkstring(L, 1);
        size_t len;
        const char* data = luaL_checklstring(L, 2, &len);

        if (strcmp(algo, "sha256") == 0) {
            auto hash = SHA256(data, len);
            lua_pushlstring(L, hash.data(), hash.size());
            return 1;
        } else if (strcmp(algo, "sha512") == 0) {
            auto hash = SHA512(data, len);
            lua_pushlstring(L, hash.data(), hash.size());
            return 1;
        }

        return luaL_error(L, "unknown algorithm: %s", algo);
    });
    lua_setfield(L, -2, "hash");

    // crypto.hmac(algorithm, key, data)
    // crypto.encrypt(algorithm, key, iv, plaintext) - AES-256-GCM only
    // crypto.decrypt(algorithm, key, iv, ciphertext)

    lua_setglobal(L, "crypto");
}
```

### Random Number Security

**Status**: Planned

`math.random()` uses a per-app seed to prevent cross-app prediction.

```cpp
void SetupSafeRandom(lua_State* L) {
    auto* sandbox = GetSandbox(L);

    // Seed with cryptographic random + app ID hash
    uint64_t seed;
    CSPRNG(&seed, sizeof(seed));
    seed ^= std::hash<std::string>{}(sandbox->app_id);

    // Store RNG state in registry
    auto* rng = new std::mt19937_64(seed);
    lua_pushlightuserdata(L, rng);
    lua_setfield(L, LUA_REGISTRYINDEX, "__rng");

    // Replace math.random
    lua_getglobal(L, "math");
    lua_pushcfunction(L, [](lua_State* L) -> int {
        lua_getfield(L, LUA_REGISTRYINDEX, "__rng");
        auto* rng = static_cast<std::mt19937_64*>(lua_touserdata(L, -1));
        lua_pop(L, 1);

        int nargs = lua_gettop(L);
        if (nargs == 0) {
            // [0, 1)
            std::uniform_real_distribution<double> dist(0.0, 1.0);
            lua_pushnumber(L, dist(*rng));
        } else if (nargs == 1) {
            // [1, n]
            int n = luaL_checkinteger(L, 1);
            std::uniform_int_distribution<int> dist(1, n);
            lua_pushinteger(L, dist(*rng));
        } else {
            // [m, n]
            int m = luaL_checkinteger(L, 1);
            int n = luaL_checkinteger(L, 2);
            std::uniform_int_distribution<int> dist(m, n);
            lua_pushinteger(L, dist(*rng));
        }
        return 1;
    });
    lua_setfield(L, -2, "random");

    // Remove math.randomseed (prevent manipulation)
    lua_pushnil(L);
    lua_setfield(L, -2, "randomseed");

    lua_pop(L, 1);
}
```

### Environment Fingerprinting Prevention

**Status**: Planned

Limit information leakage about device/user.

```cpp
void SetupEnvironmentAPI(lua_State* L) {
    lua_newtable(L);

    // Only expose safe, non-identifying info
    lua_pushstring(L, "1.0.0");
    lua_setfield(L, -2, "mosis_version");

    lua_pushinteger(L, 540);
    lua_setfield(L, -2, "screen_width");

    lua_pushinteger(L, 960);
    lua_setfield(L, -2, "screen_height");

    // NOT exposed:
    // - Device model
    // - OS version
    // - Unique identifiers
    // - Installed apps list
    // - Precise time (only second precision)
    // - Memory/CPU info
    // - Network interfaces

    lua_setglobal(L, "env");
}

// Time with reduced precision
int SafeTime(lua_State* L) {
    // Round to seconds (no milliseconds)
    time_t now = time(nullptr);
    lua_pushinteger(L, static_cast<lua_Integer>(now));
    return 1;
}
```

### Rate Limiting

**Status**: Planned

Prevent abuse of expensive operations.

```cpp
class RateLimiter {
public:
    struct Limit {
        int max_calls;
        std::chrono::milliseconds window;
    };

    bool Check(const std::string& operation) {
        auto now = std::chrono::steady_clock::now();
        auto& bucket = m_buckets[operation];

        // Remove old entries
        while (!bucket.empty() &&
               now - bucket.front() > m_limits[operation].window) {
            bucket.pop_front();
        }

        // Check limit
        if (bucket.size() >= m_limits[operation].max_calls) {
            return false;
        }

        bucket.push_back(now);
        return true;
    }

private:
    std::unordered_map<std::string, Limit> m_limits = {
        {"network.request", {100, std::chrono::minutes(1)}},
        {"storage.write", {1000, std::chrono::minutes(1)}},
        {"crypto.hash", {1000, std::chrono::seconds(1)}},
        {"timer.create", {100, std::chrono::seconds(1)}},
    };

    std::unordered_map<std::string, std::deque<TimePoint>> m_buckets;
};

// Usage
int NetworkRequest(lua_State* L) {
    auto* sandbox = GetSandbox(L);
    if (!sandbox->rate_limiter.Check("network.request")) {
        return luaL_error(L, "rate limit exceeded");
    }
    // ... proceed with request
}
```

### Resource Cleanup on Termination

**Status**: Planned

Ensure all resources are released when app stops.

```cpp
class LuaSandbox {
public:
    ~LuaSandbox() {
        Cleanup();
    }

    void Cleanup() {
        // Cancel all timers
        m_timer_manager->CancelAll(m_context.app_id);

        // Close all network connections
        m_network_manager->CloseAll(m_context.app_id);

        // Release all file handles
        m_file_manager->CloseAll(m_context.app_id);

        // Clear message queue
        m_message_bus->ClearPending(m_context.app_id);

        // Release Lua callbacks
        for (int ref : m_callback_refs) {
            luaL_unref(L, LUA_REGISTRYINDEX, ref);
        }

        // Close Lua state (releases memory)
        if (L) {
            lua_close(L);
            L = nullptr;
        }

        // Log cleanup
        AuditLog::Log({
            .app_id = m_context.app_id,
            .event = AuditEvent::AppStop,
            .detail = "cleanup completed"
        });
    }

private:
    std::vector<int> m_callback_refs;
};
```

### App Signature Verification

**Status**: Planned

Verify app packages haven't been tampered with.

```cpp
struct AppSignature {
    std::string algorithm;  // "ed25519"
    std::string public_key; // Base64
    std::string signature;  // Base64
};

class PackageVerifier {
public:
    bool Verify(const std::string& mpkg_path) {
        // Read manifest
        auto manifest = ReadManifest(mpkg_path);
        if (!manifest) return false;

        // Check signature exists
        if (!manifest->signature) {
            // Unsigned packages allowed in dev mode only
            return IsDevMode();
        }

        // Get developer's public key from store/registry
        auto pub_key = GetDeveloperKey(manifest->author_id);
        if (!pub_key) return false;

        // Compute package hash (all files except signature)
        auto hash = ComputePackageHash(mpkg_path);

        // Verify signature
        return VerifyEd25519(
            pub_key->data(),
            hash.data(), hash.size(),
            Base64Decode(manifest->signature->signature)
        );
    }

private:
    std::vector<uint8_t> ComputePackageHash(const std::string& path) {
        // Hash all files in deterministic order
        SHA256_CTX ctx;
        SHA256_Init(&ctx);

        for (const auto& file : ListFilesRecursive(path)) {
            if (file.name == "signature.json") continue;

            // Include filename in hash
            SHA256_Update(&ctx, file.name.data(), file.name.size());

            // Include content
            auto content = ReadFile(file.path);
            SHA256_Update(&ctx, content.data(), content.size());
        }

        std::vector<uint8_t> hash(32);
        SHA256_Final(hash.data(), &ctx);
        return hash;
    }
};
```

### Debug Mode Restrictions

**Status**: Planned

Development features disabled in production.

```cpp
class DebugMode {
public:
    static bool IsEnabled() {
        #ifdef NDEBUG
            return false;
        #else
            return s_debug_enabled;
        #endif
    }

    // Only available in debug mode
    static void EnableHotReload(LuaSandbox* sandbox) {
        if (!IsEnabled()) return;
        // ...
    }

    static void EnableInspector(LuaSandbox* sandbox) {
        if (!IsEnabled()) return;
        // ...
    }

    // Log debug state for security audit
    static void LogDebugState() {
        if (IsEnabled()) {
            Logger::Warn("[SECURITY] Debug mode enabled - "
                        "sandbox restrictions relaxed");
        }
    }

private:
    static bool s_debug_enabled;
};

// In production builds, these are completely compiled out
#ifdef NDEBUG
    #define DEBUG_ONLY(x) ((void)0)
#else
    #define DEBUG_ONLY(x) x
#endif
```

### Clipboard Isolation

**Status**: Planned

Apps can only access clipboard with permission and user gesture.

```cpp
class ClipboardManager {
public:
    // Requires permission + recent user gesture
    std::optional<std::string> Read(LuaSandbox* sandbox) {
        if (!sandbox->HasPermission("clipboard.read")) {
            return std::nullopt;
        }

        // Must be within 1 second of user gesture (click/tap)
        if (!sandbox->HasRecentUserGesture(1000)) {
            Logger::Warn("Clipboard read blocked - no recent user gesture");
            return std::nullopt;
        }

        return GetSystemClipboard();
    }

    bool Write(LuaSandbox* sandbox, const std::string& text) {
        if (!sandbox->HasPermission("clipboard.write")) {
            return false;
        }

        // Size limit
        if (text.size() > 1024 * 1024) {
            return false;
        }

        SetSystemClipboard(text);
        return true;
    }
};
```

### Stack Depth Limiting

**Status**: Planned

Prevent stack overflow via deep recursion.

```cpp
void SetupStackLimit(lua_State* L, int max_depth) {
    // Set C stack limit
    // Note: Lua 5.4 has LUAI_MAXCSTACK

    // Also use debug hook to check Lua call depth
    lua_sethook(L, [](lua_State* L, lua_Debug* ar) {
        lua_Debug info;
        int depth = 0;

        while (lua_getstack(L, depth, &info)) {
            depth++;
        }

        auto* sandbox = GetSandbox(L);
        if (depth > sandbox->m_limits.stack_depth) {
            luaL_error(L, "stack overflow (depth %d)", depth);
        }
    }, LUA_MASKCALL, 0);
}
```

---

## Security Testing Checklist

### Before Release

- [ ] All dangerous globals removed
- [ ] Bytecode loading blocked
- [ ] Memory limits enforced
- [ ] CPU limits enforced
- [ ] Path traversal blocked
- [ ] Metatable protection working
- [ ] Permission checks on all APIs
- [ ] Network domain filtering working
- [ ] Rate limiting active
- [ ] Audit logging enabled
- [ ] Debug mode disabled in release
- [ ] Fuzzing completed with no crashes
- [ ] Security audit by external party

### Per-App Review (Store Submission)

- [ ] Manifest permissions justified
- [ ] No obfuscated code
- [ ] Network domains declared
- [ ] Package signature valid
- [ ] No known vulnerability patterns
- [ ] Resource usage reasonable

---

## Virtual Hardware Interfaces

Mosis provides virtualized hardware interfaces that apps can access through permission-gated APIs. Each interface has specific security requirements based on the sensitivity of the data it exposes.

### Hardware Permission Model

```
┌─────────────────────────────────────────────────────────────────────┐
│                      Permission Categories                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  NORMAL (auto-granted)         DANGEROUS (user prompt required)     │
│  ├── storage.app               ├── camera                           │
│  ├── network.metadata          ├── microphone                       │
│  ├── system.vibrate            ├── location.fine                    │
│  └── audio.playback            ├── location.coarse                  │
│                                ├── contacts.read                    │
│  SIGNATURE (system apps only)  ├── contacts.write                   │
│  ├── system.settings           ├── storage.shared                   │
│  ├── app.install               ├── network.internet                 │
│  └── hardware.control          ├── bluetooth                        │
│                                ├── phone.call                       │
│                                ├── sms.send                         │
│                                └── sensors.body                     │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
```

### Hardware Security Threat Model

| Interface | Threat | Impact | Mitigation |
|-----------|--------|--------|------------|
| **Camera** | Silent recording | Critical privacy | Indicator, gesture gate |
| **Microphone** | Eavesdropping | Critical privacy | Indicator, gesture gate |
| **Location** | Tracking | High privacy | Precision reduction, rate limit |
| **Network** | Data exfiltration | High privacy | Domain filtering, inspection |
| **Filesystem** | Data theft/corruption | High integrity | Path sandboxing |
| **Database** | SQL injection | High integrity | Prepared statements only |
| **Bluetooth** | Device tracking | Medium privacy | Pairing consent |
| **Sensors** | Fingerprinting | Medium privacy | Reduced precision |
| **Speaker** | Audio spam | Low annoyance | Volume limits, rate limit |

---

## Network Interface Security

### Network Sandbox Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                         App Lua Code                                 │
│                              │                                       │
│                     network.request(url, opts)                       │
│                              │                                       │
├──────────────────────────────▼──────────────────────────────────────┤
│                      NetworkSandbox                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────────┐ │
│  │ Permission  │  │   Domain     │  │    Content                 │ │
│  │   Check     │→ │  Validation  │→ │    Inspection              │ │
│  └─────────────┘  └──────────────┘  └────────────────────────────┘ │
│                              │                                       │
│                    ┌─────────▼──────────┐                           │
│                    │    Rate Limiter    │                           │
│                    └─────────┬──────────┘                           │
│                              │                                       │
├──────────────────────────────▼──────────────────────────────────────┤
│                      System HTTP Client                              │
│                  (libcurl / Android HttpClient)                      │
└─────────────────────────────────────────────────────────────────────┘
```

### HTTP Request Security

**Status**: Designed

```cpp
struct HttpRequestPolicy {
    // Domain restrictions
    std::vector<std::string> allowed_domains;   // Whitelist from manifest
    std::vector<std::string> blocked_domains;   // System blacklist
    bool allow_localhost = false;               // Block 127.0.0.1, ::1
    bool allow_private_ips = false;             // Block 10.x, 192.168.x, etc.
    bool allow_metadata_ips = false;            // Block 169.254.x (cloud metadata)

    // Protocol restrictions
    bool require_https = true;                  // Block plain HTTP
    std::vector<std::string> allowed_schemes = {"https"};

    // Size limits
    size_t max_request_body = 10 * 1024 * 1024;   // 10 MB
    size_t max_response_body = 50 * 1024 * 1024;  // 50 MB
    size_t max_header_size = 64 * 1024;           // 64 KB

    // Timeout
    int connect_timeout_ms = 10000;
    int read_timeout_ms = 30000;
    int total_timeout_ms = 60000;

    // Rate limits
    int max_concurrent_requests = 6;
    int max_requests_per_minute = 100;
};

class HttpRequestValidator {
public:
    enum class Result {
        Allowed,
        PermissionDenied,
        DomainBlocked,
        PrivateIPBlocked,
        MetadataIPBlocked,
        LocalhostBlocked,
        InsecureProtocol,
        RequestTooLarge,
        RateLimitExceeded
    };

    Result Validate(const HttpRequest& req, const AppContext& ctx) {
        // 1. Permission check
        if (!ctx.HasPermission("network.internet")) {
            return Result::PermissionDenied;
        }

        // 2. Parse URL
        auto url = ParseUrl(req.url);
        if (!url) return Result::DomainBlocked;

        // 3. Protocol check
        if (m_policy.require_https && url->scheme != "https") {
            return Result::InsecureProtocol;
        }

        // 4. Resolve hostname to IP (detect IP-based bypass)
        auto ips = ResolveHostname(url->host);

        // 5. Block private IPs
        for (const auto& ip : ips) {
            if (IsPrivateIP(ip) && !m_policy.allow_private_ips) {
                return Result::PrivateIPBlocked;
            }
            if (IsMetadataIP(ip) && !m_policy.allow_metadata_ips) {
                return Result::MetadataIPBlocked;
            }
            if (IsLocalhost(ip) && !m_policy.allow_localhost) {
                return Result::LocalhostBlocked;
            }
        }

        // 6. Domain whitelist/blacklist
        if (!m_policy.allowed_domains.empty()) {
            if (!MatchesDomainList(url->host, m_policy.allowed_domains)) {
                return Result::DomainBlocked;
            }
        }
        if (MatchesDomainList(url->host, m_policy.blocked_domains)) {
            return Result::DomainBlocked;
        }

        // 7. Size check
        if (req.body.size() > m_policy.max_request_body) {
            return Result::RequestTooLarge;
        }

        // 8. Rate limit
        if (!m_rate_limiter.Check(ctx.app_id, "http_request")) {
            return Result::RateLimitExceeded;
        }

        return Result::Allowed;
    }

private:
    bool IsPrivateIP(const std::string& ip) {
        // IPv4 private ranges
        if (ip.starts_with("10.")) return true;
        if (ip.starts_with("172.")) {
            int second_octet = std::stoi(ip.substr(4, ip.find('.', 4) - 4));
            if (second_octet >= 16 && second_octet <= 31) return true;
        }
        if (ip.starts_with("192.168.")) return true;

        // Link-local
        if (ip.starts_with("169.254.")) return true;

        // IPv6 private ranges
        if (ip.starts_with("fc") || ip.starts_with("fd")) return true;  // ULA
        if (ip.starts_with("fe80:")) return true;  // Link-local

        return false;
    }

    bool IsMetadataIP(const std::string& ip) {
        // AWS/GCP/Azure metadata endpoints
        return ip == "169.254.169.254" ||
               ip == "metadata.google.internal" ||
               ip.starts_with("fd00:ec2::");
    }
};
```

### WebSocket Security

**Status**: Designed

```cpp
struct WebSocketPolicy {
    bool enabled = true;
    int max_connections_per_app = 5;
    size_t max_message_size = 1 * 1024 * 1024;  // 1 MB
    int ping_interval_ms = 30000;
    int idle_timeout_ms = 300000;  // 5 minutes

    // Same domain validation as HTTP
    std::vector<std::string> allowed_origins;
};

class WebSocketManager {
public:
    struct Connection {
        uint32_t id;
        std::string app_id;
        std::string url;
        ConnectionState state;
        std::chrono::steady_clock::time_point created_at;
        std::chrono::steady_clock::time_point last_activity;
        size_t bytes_sent = 0;
        size_t bytes_received = 0;
    };

    std::optional<uint32_t> Connect(LuaSandbox* sandbox, const std::string& url) {
        // Permission check
        if (!sandbox->HasPermission("network.websocket")) {
            return std::nullopt;
        }

        // Validate URL (same as HTTP)
        auto result = m_validator.Validate({.url = url}, sandbox->context());
        if (result != HttpRequestValidator::Result::Allowed) {
            return std::nullopt;
        }

        // Connection limit
        if (CountAppConnections(sandbox->app_id()) >= m_policy.max_connections_per_app) {
            return std::nullopt;
        }

        // Create connection
        auto conn = CreateConnection(url);
        conn.app_id = sandbox->app_id();

        m_connections[conn.id] = conn;
        return conn.id;
    }

    bool Send(LuaSandbox* sandbox, uint32_t conn_id, const std::string& data) {
        auto it = m_connections.find(conn_id);
        if (it == m_connections.end()) return false;

        // Verify ownership
        if (it->second.app_id != sandbox->app_id()) return false;

        // Size limit
        if (data.size() > m_policy.max_message_size) return false;

        // Rate limit
        if (!m_rate_limiter.Check(sandbox->app_id(), "ws_send")) return false;

        // Send
        it->second.bytes_sent += data.size();
        it->second.last_activity = std::chrono::steady_clock::now();
        return DoSend(conn_id, data);
    }

    void CloseAll(const std::string& app_id) {
        // Called when app stops
        for (auto it = m_connections.begin(); it != m_connections.end(); ) {
            if (it->second.app_id == app_id) {
                DoClose(it->first);
                it = m_connections.erase(it);
            } else {
                ++it;
            }
        }
    }

private:
    std::unordered_map<uint32_t, Connection> m_connections;
    WebSocketPolicy m_policy;
    HttpRequestValidator m_validator;
    RateLimiter m_rate_limiter;
};
```

### Network Lua API

```lua
-- HTTP Requests (requires "network.internet" permission)
local response = network.request({
    url = "https://api.example.com/data",
    method = "POST",  -- GET, POST, PUT, DELETE, PATCH
    headers = {
        ["Content-Type"] = "application/json",
        ["Authorization"] = "Bearer " .. token
    },
    body = json.encode({key = "value"}),
    timeout = 30000  -- milliseconds
})

-- Response structure
-- response.status: number (200, 404, etc.)
-- response.headers: table
-- response.body: string
-- response.error: string (nil if success)

-- WebSocket (requires "network.websocket" permission)
local ws = network.websocket("wss://api.example.com/ws")

ws:on("open", function()
    ws:send(json.encode({type = "hello"}))
end)

ws:on("message", function(data)
    local msg = json.decode(data)
    print("Received:", msg.type)
end)

ws:on("close", function(code, reason)
    print("Closed:", code, reason)
end)

ws:on("error", function(err)
    print("Error:", err)
end)

ws:close()
```

### Manifest Declaration

```json
{
  "permissions": ["network.internet", "network.websocket"],
  "network": {
    "allowed_domains": [
      "api.example.com",
      "*.cdn.example.com",
      "wss://realtime.example.com"
    ],
    "allow_http": false,
    "max_connections": 10
  }
}
```

---

## Filesystem Interface Security

### Virtual Filesystem Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                         Physical Storage                             │
│  /data/data/com.omixlab.mosis/                                      │
│  ├── apps/                                                           │
│  │   ├── com.example.app1/                                          │
│  │   │   ├── data/           ← App-private storage                  │
│  │   │   ├── cache/          ← Clearable cache                      │
│  │   │   └── temp/           ← Session-only                         │
│  │   └── com.example.app2/                                          │
│  ├── shared/                                                         │
│  │   ├── photos/             ← Shared media (permission required)   │
│  │   ├── downloads/                                                  │
│  │   └── documents/                                                  │
│  └── system/                 ← System apps only                      │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                            ┌───────▼───────┐
                            │ VirtualFS API │
                            └───────┬───────┘
                                    │
┌───────────────────────────────────▼─────────────────────────────────┐
│                        App's Virtual View                            │
│  /                                                                   │
│  ├── data/        → /apps/<app_id>/data/     (auto-granted)         │
│  ├── cache/       → /apps/<app_id>/cache/    (auto-granted)         │
│  ├── temp/        → /apps/<app_id>/temp/     (auto-granted)         │
│  ├── shared/      → /shared/                 (permission required)  │
│  └── (nothing else visible)                                          │
└─────────────────────────────────────────────────────────────────────┘
```

### Filesystem Security Implementation

**Status**: Designed

```cpp
struct FilesystemPolicy {
    // Storage quotas
    size_t max_app_storage = 100 * 1024 * 1024;    // 100 MB per app
    size_t max_cache_storage = 50 * 1024 * 1024;   // 50 MB cache
    size_t max_file_size = 50 * 1024 * 1024;       // 50 MB single file

    // File limits
    size_t max_files_per_directory = 10000;
    size_t max_path_depth = 32;
    size_t max_filename_length = 255;

    // Allowed extensions (whitelist approach)
    std::vector<std::string> allowed_extensions = {
        ".txt", ".json", ".xml", ".html", ".css", ".js", ".lua",
        ".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg",
        ".mp3", ".ogg", ".wav",
        ".mp4", ".webm",
        ".db", ".sqlite"
    };

    // Blocked patterns
    std::vector<std::string> blocked_patterns = {
        "*.exe", "*.dll", "*.so", "*.dylib",  // Executables
        "*.sh", "*.bat", "*.cmd", "*.ps1",     // Scripts
        ".*",                                   // Hidden files
    };
};

class VirtualFilesystem {
public:
    VirtualFilesystem(const std::string& app_id, const std::string& base_path)
        : m_app_id(app_id)
        , m_base_path(base_path)
        , m_app_root(base_path + "/apps/" + app_id) {}

    // Resolve virtual path to physical path with security checks
    std::optional<std::string> ResolvePath(const std::string& virtual_path,
                                           AccessMode mode) {
        // 1. Validate path format
        if (!IsValidPathFormat(virtual_path)) {
            AuditLog::Log({m_app_id, AuditEvent::FileAccess,
                          "invalid path format: " + virtual_path, false});
            return std::nullopt;
        }

        // 2. Parse virtual path
        auto parts = SplitPath(virtual_path);
        if (parts.empty()) return std::nullopt;

        // 3. Determine physical root based on virtual root
        std::string physical_root;
        bool requires_permission = false;

        if (parts[0] == "data") {
            physical_root = m_app_root + "/data";
        } else if (parts[0] == "cache") {
            physical_root = m_app_root + "/cache";
        } else if (parts[0] == "temp") {
            physical_root = m_app_root + "/temp";
        } else if (parts[0] == "shared") {
            physical_root = m_base_path + "/shared";
            requires_permission = true;
        } else {
            // Unknown root - access denied
            return std::nullopt;
        }

        // 4. Permission check for shared storage
        if (requires_permission) {
            std::string perm = (mode == AccessMode::Read)
                ? "storage.shared.read"
                : "storage.shared.write";
            if (!HasPermission(perm)) {
                AuditLog::Log({m_app_id, AuditEvent::PermissionDenied, perm, false});
                return std::nullopt;
            }
        }

        // 5. Build full path
        std::filesystem::path full_path = physical_root;
        for (size_t i = 1; i < parts.size(); ++i) {
            full_path /= parts[i];
        }

        // 6. Canonicalize and verify containment
        std::filesystem::path canonical;
        try {
            if (mode == AccessMode::Read) {
                // Must exist for read
                canonical = std::filesystem::canonical(full_path);
            } else {
                // May not exist for write - canonicalize parent
                canonical = std::filesystem::weakly_canonical(full_path);
            }
        } catch (const std::filesystem::filesystem_error&) {
            return std::nullopt;
        }

        // 7. Verify path is within allowed root (prevent traversal)
        std::string canonical_str = canonical.string();
        if (!canonical_str.starts_with(physical_root)) {
            AuditLog::Log({m_app_id, AuditEvent::SandboxViolation,
                          "path traversal attempt: " + virtual_path, false});
            return std::nullopt;
        }

        // 8. Check file extension
        if (!IsAllowedExtension(canonical.extension().string())) {
            return std::nullopt;
        }

        return canonical_str;
    }

    // Quota enforcement
    bool HasStorageQuota(size_t bytes_needed) {
        size_t current = CalculateDirectorySize(m_app_root + "/data");
        return (current + bytes_needed) <= m_policy.max_app_storage;
    }

    std::optional<size_t> GetUsedStorage() {
        return CalculateDirectorySize(m_app_root + "/data");
    }

    std::optional<size_t> GetAvailableStorage() {
        auto used = GetUsedStorage();
        if (!used) return std::nullopt;
        return m_policy.max_app_storage - *used;
    }

private:
    bool IsValidPathFormat(const std::string& path) {
        // Must start with /
        if (path.empty() || path[0] != '/') return false;

        // No .. components
        if (path.find("..") != std::string::npos) return false;

        // No double slashes
        if (path.find("//") != std::string::npos) return false;

        // No null bytes
        if (path.find('\0') != std::string::npos) return false;

        // Length check
        if (path.length() > 4096) return false;

        // Check each component
        for (const auto& part : SplitPath(path)) {
            if (part.length() > m_policy.max_filename_length) return false;
            if (part.empty()) return false;
            if (MatchesBlockedPattern(part)) return false;
        }

        return true;
    }

    bool IsAllowedExtension(const std::string& ext) {
        if (ext.empty()) return true;  // Directories
        std::string lower_ext = ToLower(ext);
        return std::find(m_policy.allowed_extensions.begin(),
                        m_policy.allowed_extensions.end(),
                        lower_ext) != m_policy.allowed_extensions.end();
    }

    std::string m_app_id;
    std::string m_base_path;
    std::string m_app_root;
    FilesystemPolicy m_policy;
};
```

### File Operations with Security Gates

```cpp
class SecureFileAPI {
public:
    // Read file
    std::optional<std::string> ReadFile(LuaSandbox* sandbox,
                                        const std::string& path) {
        auto physical = m_vfs.ResolvePath(path, AccessMode::Read);
        if (!physical) return std::nullopt;

        // Rate limit
        if (!m_rate_limiter.Check(sandbox->app_id(), "file_read")) {
            return std::nullopt;
        }

        // Read with size limit
        std::ifstream file(*physical, std::ios::binary);
        if (!file) return std::nullopt;

        file.seekg(0, std::ios::end);
        size_t size = file.tellg();
        if (size > m_policy.max_file_size) return std::nullopt;

        file.seekg(0, std::ios::beg);
        std::string content(size, '\0');
        file.read(content.data(), size);

        AuditLog::Log({sandbox->app_id(), AuditEvent::FileAccess,
                      "read: " + path + " (" + std::to_string(size) + " bytes)", true});

        return content;
    }

    // Write file
    bool WriteFile(LuaSandbox* sandbox, const std::string& path,
                   const std::string& content) {
        auto physical = m_vfs.ResolvePath(path, AccessMode::Write);
        if (!physical) return false;

        // Size check
        if (content.size() > m_policy.max_file_size) return false;

        // Quota check
        if (!m_vfs.HasStorageQuota(content.size())) {
            AuditLog::Log({sandbox->app_id(), AuditEvent::ResourceLimitHit,
                          "storage quota exceeded", false});
            return false;
        }

        // Rate limit
        if (!m_rate_limiter.Check(sandbox->app_id(), "file_write")) {
            return false;
        }

        // Create parent directories
        std::filesystem::create_directories(
            std::filesystem::path(*physical).parent_path());

        // Write atomically (temp file + rename)
        std::string temp_path = *physical + ".tmp." + GenerateRandomId();
        {
            std::ofstream file(temp_path, std::ios::binary);
            if (!file) return false;
            file.write(content.data(), content.size());
        }

        std::error_code ec;
        std::filesystem::rename(temp_path, *physical, ec);
        if (ec) {
            std::filesystem::remove(temp_path);
            return false;
        }

        AuditLog::Log({sandbox->app_id(), AuditEvent::FileAccess,
                      "write: " + path + " (" + std::to_string(content.size()) + " bytes)",
                      true});

        return true;
    }

    // List directory
    std::optional<std::vector<FileInfo>> ListDirectory(LuaSandbox* sandbox,
                                                       const std::string& path) {
        auto physical = m_vfs.ResolvePath(path, AccessMode::Read);
        if (!physical) return std::nullopt;

        std::vector<FileInfo> entries;
        for (const auto& entry : std::filesystem::directory_iterator(*physical)) {
            if (entries.size() >= m_policy.max_files_per_directory) break;

            FileInfo info;
            info.name = entry.path().filename().string();
            info.is_directory = entry.is_directory();
            info.size = entry.is_regular_file() ? entry.file_size() : 0;
            info.modified = GetModificationTime(entry.path());
            entries.push_back(info);
        }

        return entries;
    }

    // Delete file
    bool Delete(LuaSandbox* sandbox, const std::string& path) {
        auto physical = m_vfs.ResolvePath(path, AccessMode::Write);
        if (!physical) return false;

        // Rate limit
        if (!m_rate_limiter.Check(sandbox->app_id(), "file_delete")) {
            return false;
        }

        std::error_code ec;
        bool removed = std::filesystem::remove(*physical, ec);

        AuditLog::Log({sandbox->app_id(), AuditEvent::FileAccess,
                      "delete: " + path, removed});

        return removed;
    }

private:
    VirtualFilesystem m_vfs;
    FilesystemPolicy m_policy;
    RateLimiter m_rate_limiter;
};
```

### Filesystem Lua API

```lua
-- File operations (app-private storage is auto-granted)
local content = storage.read("/data/config.json")
local success = storage.write("/data/config.json", json.encode(config))

-- Directory operations
local files = storage.list("/data/saves/")
for _, file in ipairs(files) do
    print(file.name, file.size, file.is_directory)
end

-- File info
local info = storage.info("/data/save.json")
-- info.exists, info.size, info.modified, info.is_directory

-- Delete
storage.delete("/data/old_file.json")

-- Create directory
storage.mkdir("/data/saves/slot1/")

-- Check storage quota
local quota = storage.quota()
-- quota.used, quota.available, quota.total

-- Shared storage (requires "storage.shared.read" / "storage.shared.write")
local photos = storage.list("/shared/photos/")
storage.write("/shared/documents/report.txt", "Hello")
```

---

## Database Interface Security

### SQLite Sandbox

**Status**: Designed

Apps can use SQLite databases with security restrictions.

```cpp
struct DatabasePolicy {
    size_t max_database_size = 50 * 1024 * 1024;  // 50 MB
    size_t max_databases_per_app = 5;
    size_t max_query_time_ms = 5000;
    size_t max_result_rows = 10000;
    bool allow_attach = false;           // Prevent ATTACH to other DBs
    bool allow_load_extension = false;   // No extensions
};

class SecureDatabase {
public:
    SecureDatabase(const std::string& app_id, const std::string& db_name)
        : m_app_id(app_id)
        , m_db_name(db_name) {

        // Validate database name
        if (!IsValidDatabaseName(db_name)) {
            throw std::invalid_argument("invalid database name");
        }

        // Open database in app's data directory
        std::string path = GetAppDataPath(app_id) + "/databases/" + db_name + ".db";

        int rc = sqlite3_open_v2(path.c_str(), &m_db,
            SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE |
            SQLITE_OPEN_NOMUTEX,  // Single-threaded access per app
            nullptr);

        if (rc != SQLITE_OK) {
            throw std::runtime_error("failed to open database");
        }

        // Security configuration
        ConfigureSecurity();
    }

    ~SecureDatabase() {
        if (m_db) sqlite3_close(m_db);
    }

    // Execute query with prepared statement (prevents SQL injection)
    QueryResult Execute(const std::string& sql,
                       const std::vector<SqlValue>& params) {
        // 1. Validate SQL (basic sanity checks)
        if (!ValidateSql(sql)) {
            return {.error = "invalid SQL"};
        }

        // 2. Prepare statement
        sqlite3_stmt* stmt;
        int rc = sqlite3_prepare_v2(m_db, sql.c_str(), -1, &stmt, nullptr);
        if (rc != SQLITE_OK) {
            return {.error = sqlite3_errmsg(m_db)};
        }

        // 3. Bind parameters
        for (size_t i = 0; i < params.size(); ++i) {
            BindParameter(stmt, i + 1, params[i]);
        }

        // 4. Execute with timeout
        QueryResult result;
        auto start = std::chrono::steady_clock::now();

        while (true) {
            rc = sqlite3_step(stmt);

            // Check timeout
            auto elapsed = std::chrono::steady_clock::now() - start;
            if (elapsed > std::chrono::milliseconds(m_policy.max_query_time_ms)) {
                sqlite3_finalize(stmt);
                return {.error = "query timeout"};
            }

            if (rc == SQLITE_ROW) {
                // Check row limit
                if (result.rows.size() >= m_policy.max_result_rows) {
                    result.truncated = true;
                    break;
                }
                result.rows.push_back(ExtractRow(stmt));
            } else if (rc == SQLITE_DONE) {
                break;
            } else {
                result.error = sqlite3_errmsg(m_db);
                break;
            }
        }

        result.changes = sqlite3_changes(m_db);
        result.last_insert_id = sqlite3_last_insert_rowid(m_db);

        sqlite3_finalize(stmt);
        return result;
    }

private:
    void ConfigureSecurity() {
        // Disable dangerous features
        sqlite3_db_config(m_db, SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION, 0, nullptr);

        // Set authorizer to block dangerous operations
        sqlite3_set_authorizer(m_db, Authorizer, this);

        // Set database size limit
        sqlite3_soft_heap_limit64(m_policy.max_database_size);

        // Set busy timeout
        sqlite3_busy_timeout(m_db, 1000);
    }

    static int Authorizer(void* user_data, int action, const char* arg1,
                         const char* arg2, const char* arg3, const char* arg4) {
        auto* self = static_cast<SecureDatabase*>(user_data);

        switch (action) {
            case SQLITE_ATTACH:
            case SQLITE_DETACH:
                // Block ATTACH/DETACH to prevent accessing other databases
                return SQLITE_DENY;

            case SQLITE_PRAGMA:
                // Allow only safe pragmas
                if (arg1 && !IsSafePragma(arg1)) {
                    return SQLITE_DENY;
                }
                break;

            case SQLITE_FUNCTION:
                // Block dangerous functions
                if (arg2 && IsDangerousFunction(arg2)) {
                    return SQLITE_DENY;
                }
                break;
        }

        return SQLITE_OK;
    }

    static bool IsSafePragma(const char* pragma) {
        // Whitelist of safe pragmas
        static const std::unordered_set<std::string> safe = {
            "table_info", "index_list", "foreign_keys",
            "journal_mode", "synchronous", "cache_size"
        };
        return safe.count(pragma) > 0;
    }

    static bool IsDangerousFunction(const char* func) {
        // Block functions that can access filesystem or execute code
        static const std::unordered_set<std::string> dangerous = {
            "load_extension", "readfile", "writefile", "edit",
            "fts3_tokenizer", "sqlite_compileoption_get"
        };
        return dangerous.count(func) > 0;
    }

    bool ValidateSql(const std::string& sql) {
        std::string upper = ToUpper(sql);

        // Block dangerous statements
        if (upper.find("ATTACH") != std::string::npos) return false;
        if (upper.find("DETACH") != std::string::npos) return false;
        if (upper.find("LOAD_EXTENSION") != std::string::npos) return false;

        return true;
    }

    sqlite3* m_db = nullptr;
    std::string m_app_id;
    std::string m_db_name;
    DatabasePolicy m_policy;
};
```

### Database Lua API

```lua
-- Open database (stored in /data/databases/)
local db = database.open("myapp")

-- Create table
db:execute([[
    CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY,
        name TEXT NOT NULL,
        email TEXT UNIQUE,
        created_at INTEGER DEFAULT (strftime('%s', 'now'))
    )
]])

-- Insert with parameters (SQL injection safe)
db:execute("INSERT INTO users (name, email) VALUES (?, ?)", {"John", "john@example.com"})

-- Query with parameters
local result = db:query("SELECT * FROM users WHERE name LIKE ?", {"%John%"})
for _, row in ipairs(result.rows) do
    print(row.id, row.name, row.email)
end

-- Transaction
db:transaction(function()
    db:execute("UPDATE accounts SET balance = balance - ? WHERE id = ?", {100, 1})
    db:execute("UPDATE accounts SET balance = balance + ? WHERE id = ?", {100, 2})
end)

-- Close
db:close()
```

---

## Camera Interface Security

### Camera Security Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                         App Lua Code                                 │
│                    camera.capture(callback)                          │
│                              │                                       │
├──────────────────────────────▼──────────────────────────────────────┤
│                       CameraManager                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────────┐ │
│  │ Permission  │  │    Active    │  │     Frame Rate             │ │
│  │   Check     │→ │  Indicator   │→ │     Limiter                │ │
│  └─────────────┘  └──────────────┘  └────────────────────────────┘ │
│                              │                                       │
├──────────────────────────────▼──────────────────────────────────────┤
│                      Game Engine Camera                              │
│              (Unity RenderTexture / Unreal SceneCapture)             │
└─────────────────────────────────────────────────────────────────────┘
```

### Camera Security Implementation

**Status**: Designed

```cpp
struct CameraPolicy {
    // Access control
    bool require_user_gesture = true;      // Must be triggered by tap/click
    int max_active_sessions = 1;            // Only one app can use camera

    // Frame limits
    int max_fps = 30;
    int max_resolution_width = 1920;
    int max_resolution_height = 1080;

    // Privacy
    bool show_indicator = true;             // Always show recording indicator
    int indicator_min_duration_ms = 500;    // Indicator shows at least 500ms
    bool allow_silent_capture = false;      // Require shutter sound

    // Storage
    bool auto_save_to_gallery = false;      // App must explicitly save
    std::string watermark_text = "";        // Optional watermark
};

class CameraManager {
public:
    struct CameraSession {
        uint32_t id;
        std::string app_id;
        CameraFacing facing;
        Resolution resolution;
        bool active;
        std::chrono::steady_clock::time_point started_at;
    };

    // Start camera session
    std::optional<uint32_t> StartSession(LuaSandbox* sandbox,
                                         const CameraOptions& opts) {
        // 1. Permission check
        if (!sandbox->HasPermission("camera")) {
            AuditLog::Log({sandbox->app_id(), AuditEvent::PermissionDenied,
                          "camera", false});
            return std::nullopt;
        }

        // 2. User gesture check
        if (m_policy.require_user_gesture && !sandbox->HasRecentUserGesture(1000)) {
            AuditLog::Log({sandbox->app_id(), AuditEvent::CameraAccess,
                          "blocked - no user gesture", false});
            return std::nullopt;
        }

        // 3. Check exclusive access
        if (HasActiveSession() && m_active_session->app_id != sandbox->app_id()) {
            return std::nullopt;  // Another app is using camera
        }

        // 4. Validate resolution
        Resolution res = opts.resolution;
        res.width = std::min(res.width, m_policy.max_resolution_width);
        res.height = std::min(res.height, m_policy.max_resolution_height);

        // 5. Start session
        CameraSession session{
            .id = ++m_next_session_id,
            .app_id = sandbox->app_id(),
            .facing = opts.facing,
            .resolution = res,
            .active = true,
            .started_at = std::chrono::steady_clock::now()
        };

        m_active_session = session;

        // 6. Show indicator
        if (m_policy.show_indicator) {
            ShowCameraIndicator(true);
        }

        // 7. Request frames from game engine
        m_hardware_camera->Start(res, [this, session_id = session.id](Frame frame) {
            OnFrameReceived(session_id, frame);
        });

        AuditLog::Log({sandbox->app_id(), AuditEvent::CameraAccess,
                      "session started", true});

        return session.id;
    }

    // Capture single frame
    std::optional<ImageData> CaptureFrame(LuaSandbox* sandbox, uint32_t session_id) {
        // Verify session ownership
        if (!m_active_session || m_active_session->id != session_id ||
            m_active_session->app_id != sandbox->app_id()) {
            return std::nullopt;
        }

        // Rate limit
        if (!m_rate_limiter.Check(sandbox->app_id(), "camera_capture")) {
            return std::nullopt;
        }

        // Get latest frame
        auto frame = m_latest_frame;
        if (!frame) return std::nullopt;

        // Play shutter sound (if configured)
        if (!m_policy.allow_silent_capture) {
            PlayShutterSound();
        }

        // Apply watermark if configured
        if (!m_policy.watermark_text.empty()) {
            ApplyWatermark(frame, m_policy.watermark_text);
        }

        return frame;
    }

    // Stop session
    void StopSession(LuaSandbox* sandbox, uint32_t session_id) {
        if (!m_active_session || m_active_session->id != session_id ||
            m_active_session->app_id != sandbox->app_id()) {
            return;
        }

        m_hardware_camera->Stop();

        // Keep indicator visible for minimum duration
        auto elapsed = std::chrono::steady_clock::now() - m_active_session->started_at;
        if (elapsed < std::chrono::milliseconds(m_policy.indicator_min_duration_ms)) {
            std::this_thread::sleep_for(
                std::chrono::milliseconds(m_policy.indicator_min_duration_ms) - elapsed);
        }

        ShowCameraIndicator(false);
        m_active_session.reset();

        AuditLog::Log({sandbox->app_id(), AuditEvent::CameraAccess,
                      "session stopped", true});
    }

    // Stop all sessions for app (called on app termination)
    void StopAllSessions(const std::string& app_id) {
        if (m_active_session && m_active_session->app_id == app_id) {
            m_hardware_camera->Stop();
            ShowCameraIndicator(false);
            m_active_session.reset();
        }
    }

private:
    void OnFrameReceived(uint32_t session_id, Frame frame) {
        if (!m_active_session || m_active_session->id != session_id) {
            return;
        }

        // Apply frame rate limit
        auto now = std::chrono::steady_clock::now();
        auto elapsed = now - m_last_frame_time;
        if (elapsed < std::chrono::milliseconds(1000 / m_policy.max_fps)) {
            return;
        }
        m_last_frame_time = now;

        m_latest_frame = frame;

        // Notify app (if callback registered)
        if (m_frame_callback) {
            m_frame_callback(frame);
        }
    }

    std::optional<CameraSession> m_active_session;
    std::optional<Frame> m_latest_frame;
    std::chrono::steady_clock::time_point m_last_frame_time;
    CameraPolicy m_policy;
    IHardwareCamera* m_hardware_camera;
    RateLimiter m_rate_limiter;
    uint32_t m_next_session_id = 0;
};
```

### Camera Lua API

```lua
-- Request camera permission (shows system dialog)
local granted = permissions.request("camera")
if not granted then return end

-- Start camera session
local session = camera.start({
    facing = "back",  -- "back" or "front"
    resolution = {width = 1280, height = 720}
})

-- Preview frames
session:onFrame(function(frame)
    -- frame.width, frame.height, frame.data (base64 JPEG)
    ui.setImage("preview", frame.data)
end)

-- Capture photo
local photo = session:capture()
if photo then
    -- Save to app storage
    storage.write("/data/photos/photo_" .. os.time() .. ".jpg",
                  base64.decode(photo.data))

    -- Or save to shared gallery (requires storage.shared.write)
    storage.write("/shared/photos/MyApp/photo.jpg", base64.decode(photo.data))
end

-- Stop session
session:stop()
```

---

## Microphone Interface Security

### Microphone Security Implementation

**Status**: Designed

```cpp
struct MicrophonePolicy {
    // Access control
    bool require_user_gesture = true;
    int max_active_sessions = 1;

    // Audio limits
    int max_sample_rate = 48000;
    int max_duration_ms = 300000;  // 5 minutes max recording
    int max_buffer_size = 4096;

    // Privacy
    bool show_indicator = true;
    int indicator_min_duration_ms = 500;
    bool allow_background_recording = false;
};

class MicrophoneManager {
public:
    struct AudioSession {
        uint32_t id;
        std::string app_id;
        int sample_rate;
        int channels;
        bool active;
        std::chrono::steady_clock::time_point started_at;
        size_t samples_recorded = 0;
    };

    std::optional<uint32_t> StartRecording(LuaSandbox* sandbox,
                                           const AudioOptions& opts) {
        // 1. Permission check
        if (!sandbox->HasPermission("microphone")) {
            AuditLog::Log({sandbox->app_id(), AuditEvent::PermissionDenied,
                          "microphone", false});
            return std::nullopt;
        }

        // 2. User gesture check
        if (m_policy.require_user_gesture && !sandbox->HasRecentUserGesture(1000)) {
            return std::nullopt;
        }

        // 3. Exclusive access
        if (HasActiveSession() && m_active_session->app_id != sandbox->app_id()) {
            return std::nullopt;
        }

        // 4. Background recording check
        if (!m_policy.allow_background_recording && !sandbox->IsAppForeground()) {
            return std::nullopt;
        }

        // 5. Validate options
        int sample_rate = std::min(opts.sample_rate, m_policy.max_sample_rate);

        AudioSession session{
            .id = ++m_next_session_id,
            .app_id = sandbox->app_id(),
            .sample_rate = sample_rate,
            .channels = opts.channels,
            .active = true,
            .started_at = std::chrono::steady_clock::now()
        };

        m_active_session = session;

        // 6. Show indicator
        if (m_policy.show_indicator) {
            ShowMicrophoneIndicator(true);
        }

        // 7. Start hardware recording
        m_hardware_mic->Start(sample_rate, opts.channels,
            [this, session_id = session.id](AudioBuffer buffer) {
                OnAudioReceived(session_id, buffer);
            });

        AuditLog::Log({sandbox->app_id(), AuditEvent::MicrophoneAccess,
                      "recording started", true});

        return session.id;
    }

    void StopRecording(LuaSandbox* sandbox, uint32_t session_id) {
        if (!m_active_session || m_active_session->id != session_id ||
            m_active_session->app_id != sandbox->app_id()) {
            return;
        }

        m_hardware_mic->Stop();

        // Minimum indicator duration
        auto elapsed = std::chrono::steady_clock::now() - m_active_session->started_at;
        if (elapsed < std::chrono::milliseconds(m_policy.indicator_min_duration_ms)) {
            std::this_thread::sleep_for(
                std::chrono::milliseconds(m_policy.indicator_min_duration_ms) - elapsed);
        }

        ShowMicrophoneIndicator(false);
        m_active_session.reset();

        AuditLog::Log({sandbox->app_id(), AuditEvent::MicrophoneAccess,
                      "recording stopped", true});
    }

private:
    void OnAudioReceived(uint32_t session_id, AudioBuffer buffer) {
        if (!m_active_session || m_active_session->id != session_id) {
            return;
        }

        // Check duration limit
        auto elapsed = std::chrono::steady_clock::now() - m_active_session->started_at;
        if (elapsed > std::chrono::milliseconds(m_policy.max_duration_ms)) {
            // Auto-stop after max duration
            StopRecordingInternal(session_id);
            return;
        }

        m_active_session->samples_recorded += buffer.samples;

        // Deliver to app callback
        if (m_audio_callback) {
            m_audio_callback(buffer);
        }
    }

    std::optional<AudioSession> m_active_session;
    MicrophonePolicy m_policy;
    IHardwareMicrophone* m_hardware_mic;
    uint32_t m_next_session_id = 0;
};
```

### Microphone Lua API

```lua
-- Request permission
local granted = permissions.request("microphone")
if not granted then return end

-- Start recording
local session = microphone.start({
    sample_rate = 44100,
    channels = 1
})

-- Receive audio data
session:onAudio(function(buffer)
    -- buffer.samples: number of samples
    -- buffer.data: base64 encoded PCM data
end)

-- Stop recording
session:stop()

-- Get recorded audio
local audio = session:getRecording()
storage.write("/data/recordings/voice.wav", audio)
```

---

## Speaker/Audio Output Security

### Audio Output Policy

**Status**: Designed

```cpp
struct AudioOutputPolicy {
    float max_volume = 1.0f;
    int max_concurrent_sounds = 8;
    int max_sound_duration_ms = 300000;  // 5 minutes
    size_t max_audio_data_size = 50 * 1024 * 1024;  // 50 MB
    bool require_audio_focus = true;  // Respect other apps
};

class AudioOutputManager {
public:
    std::optional<uint32_t> PlaySound(LuaSandbox* sandbox,
                                      const AudioData& audio,
                                      const PlaybackOptions& opts) {
        // No dangerous permission needed for audio output,
        // but still track and limit

        // 1. Validate audio data
        if (audio.size() > m_policy.max_audio_data_size) {
            return std::nullopt;
        }

        // 2. Check concurrent sounds limit
        int app_sounds = CountAppSounds(sandbox->app_id());
        if (app_sounds >= m_policy.max_concurrent_sounds) {
            return std::nullopt;
        }

        // 3. Clamp volume
        float volume = std::clamp(opts.volume, 0.0f, m_policy.max_volume);

        // 4. Request audio focus
        if (m_policy.require_audio_focus) {
            if (!RequestAudioFocus(sandbox->app_id())) {
                return std::nullopt;
            }
        }

        // 5. Create sound instance
        Sound sound{
            .id = ++m_next_id,
            .app_id = sandbox->app_id(),
            .volume = volume,
            .looping = opts.loop,
            .started_at = std::chrono::steady_clock::now()
        };

        m_sounds[sound.id] = sound;
        m_hardware_audio->Play(audio, volume, opts.loop);

        return sound.id;
    }

    void StopSound(LuaSandbox* sandbox, uint32_t sound_id) {
        auto it = m_sounds.find(sound_id);
        if (it == m_sounds.end() || it->second.app_id != sandbox->app_id()) {
            return;
        }

        m_hardware_audio->Stop(sound_id);
        m_sounds.erase(it);
    }

    void StopAllSounds(const std::string& app_id) {
        for (auto it = m_sounds.begin(); it != m_sounds.end(); ) {
            if (it->second.app_id == app_id) {
                m_hardware_audio->Stop(it->first);
                it = m_sounds.erase(it);
            } else {
                ++it;
            }
        }
    }

private:
    std::unordered_map<uint32_t, Sound> m_sounds;
    AudioOutputPolicy m_policy;
    IHardwareAudio* m_hardware_audio;
    uint32_t m_next_id = 0;
};
```

### Audio Lua API

```lua
-- Play sound (no permission required)
local sound = audio.play("/data/sounds/notification.wav", {
    volume = 0.8,
    loop = false
})

-- Control playback
sound:pause()
sound:resume()
sound:stop()

-- System sounds
audio.playSystem("notification")
audio.playSystem("click")

-- Vibration (requires nothing or system.vibrate on some platforms)
audio.vibrate(100)  -- 100ms
audio.vibrate({100, 50, 100})  -- pattern: vibrate, pause, vibrate
```

---

## Location Interface Security

### Location Security Implementation

**Status**: Designed

```cpp
struct LocationPolicy {
    // Precision control
    int coarse_accuracy_meters = 1000;    // City-level
    int fine_accuracy_meters = 10;         // GPS precision

    // Rate limiting
    int min_update_interval_ms = 1000;     // Max 1 update/sec
    int background_update_interval_ms = 60000;  // 1/min in background

    // Privacy
    bool require_user_gesture_for_first = true;
    bool allow_background_updates = false;
    int max_cached_locations = 100;
};

class LocationManager {
public:
    std::optional<Location> GetLocation(LuaSandbox* sandbox, LocationAccuracy accuracy) {
        // 1. Permission check
        std::string perm = (accuracy == LocationAccuracy::Fine)
            ? "location.fine" : "location.coarse";

        if (!sandbox->HasPermission(perm)) {
            AuditLog::Log({sandbox->app_id(), AuditEvent::PermissionDenied,
                          perm, false});
            return std::nullopt;
        }

        // 2. Rate limit
        if (!m_rate_limiter.Check(sandbox->app_id(), "location")) {
            return std::nullopt;
        }

        // 3. Get location from hardware
        auto location = m_hardware_location->GetCurrent();
        if (!location) return std::nullopt;

        // 4. Apply precision reduction for coarse
        if (accuracy == LocationAccuracy::Coarse) {
            location = ReducePrecision(*location, m_policy.coarse_accuracy_meters);
        }

        AuditLog::Log({sandbox->app_id(), AuditEvent::LocationAccess,
                      "single location request", true});

        return location;
    }

    std::optional<uint32_t> WatchLocation(LuaSandbox* sandbox,
                                          LocationAccuracy accuracy,
                                          LocationCallback callback) {
        std::string perm = (accuracy == LocationAccuracy::Fine)
            ? "location.fine" : "location.coarse";

        if (!sandbox->HasPermission(perm)) {
            return std::nullopt;
        }

        // Background check
        if (!sandbox->IsAppForeground() && !m_policy.allow_background_updates) {
            return std::nullopt;
        }

        uint32_t watch_id = ++m_next_watch_id;

        LocationWatch watch{
            .id = watch_id,
            .app_id = sandbox->app_id(),
            .accuracy = accuracy,
            .callback = callback,
            .last_update = std::chrono::steady_clock::time_point::min()
        };

        m_watches[watch_id] = watch;

        // Start hardware updates if first watch
        if (m_watches.size() == 1) {
            m_hardware_location->StartUpdates([this](Location loc) {
                OnLocationUpdate(loc);
            });
        }

        return watch_id;
    }

    void ClearWatch(LuaSandbox* sandbox, uint32_t watch_id) {
        auto it = m_watches.find(watch_id);
        if (it == m_watches.end() || it->second.app_id != sandbox->app_id()) {
            return;
        }

        m_watches.erase(it);

        if (m_watches.empty()) {
            m_hardware_location->StopUpdates();
        }
    }

private:
    Location ReducePrecision(const Location& loc, int meters) {
        // Round coordinates to reduce precision
        // 0.01 degree ≈ 1.1km at equator
        double precision = meters / 111000.0;  // degrees per meter

        Location reduced = loc;
        reduced.latitude = std::round(loc.latitude / precision) * precision;
        reduced.longitude = std::round(loc.longitude / precision) * precision;
        reduced.accuracy = std::max(loc.accuracy, static_cast<float>(meters));
        return reduced;
    }

    void OnLocationUpdate(Location loc) {
        auto now = std::chrono::steady_clock::now();

        for (auto& [id, watch] : m_watches) {
            // Check update interval
            int interval = m_policy.min_update_interval_ms;
            auto elapsed = now - watch.last_update;
            if (elapsed < std::chrono::milliseconds(interval)) {
                continue;
            }

            // Apply precision reduction
            Location delivered = loc;
            if (watch.accuracy == LocationAccuracy::Coarse) {
                delivered = ReducePrecision(loc, m_policy.coarse_accuracy_meters);
            }

            watch.last_update = now;
            watch.callback(delivered);
        }
    }

    std::unordered_map<uint32_t, LocationWatch> m_watches;
    LocationPolicy m_policy;
    IHardwareLocation* m_hardware_location;
    RateLimiter m_rate_limiter;
    uint32_t m_next_watch_id = 0;
};
```

### Location Lua API

```lua
-- Request permission
local granted = permissions.request("location.fine")  -- or "location.coarse"

-- Get current location
local loc = location.get()
if loc then
    print(loc.latitude, loc.longitude, loc.accuracy)
end

-- Watch location changes
local watch_id = location.watch(function(loc)
    print("Moved to:", loc.latitude, loc.longitude)
end, {
    accuracy = "fine",  -- "fine" or "coarse"
    interval = 5000     -- minimum ms between updates
})

-- Stop watching
location.clearWatch(watch_id)
```

---

## Sensor Interface Security

### Sensor Security (Accelerometer, Gyroscope, etc.)

**Status**: Designed

```cpp
struct SensorPolicy {
    // Rate limiting (prevent fingerprinting via sensor noise patterns)
    int max_sample_rate_hz = 60;

    // Precision reduction
    float accelerometer_precision = 0.01f;  // m/s²
    float gyroscope_precision = 0.001f;     // rad/s

    // Background access
    bool allow_background_sensors = false;

    // Body sensors (heart rate, etc.) require special permission
    std::vector<std::string> body_sensors = {"heart_rate", "blood_pressure"};
};

class SensorManager {
public:
    std::optional<uint32_t> RegisterListener(LuaSandbox* sandbox,
                                             SensorType type,
                                             SensorCallback callback) {
        // Body sensors require dangerous permission
        if (IsBodySensor(type) && !sandbox->HasPermission("sensors.body")) {
            return std::nullopt;
        }

        // Background check
        if (!sandbox->IsAppForeground() && !m_policy.allow_background_sensors) {
            return std::nullopt;
        }

        uint32_t listener_id = ++m_next_listener_id;

        SensorListener listener{
            .id = listener_id,
            .app_id = sandbox->app_id(),
            .type = type,
            .callback = callback,
            .last_reading = std::chrono::steady_clock::time_point::min()
        };

        m_listeners[listener_id] = listener;

        // Start sensor if first listener
        EnableSensorIfNeeded(type);

        return listener_id;
    }

    void UnregisterListener(LuaSandbox* sandbox, uint32_t listener_id) {
        auto it = m_listeners.find(listener_id);
        if (it == m_listeners.end() || it->second.app_id != sandbox->app_id()) {
            return;
        }

        SensorType type = it->second.type;
        m_listeners.erase(it);

        // Stop sensor if no more listeners
        DisableSensorIfUnneeded(type);
    }

private:
    void OnSensorReading(SensorType type, SensorReading reading) {
        auto now = std::chrono::steady_clock::now();
        int min_interval_ms = 1000 / m_policy.max_sample_rate_hz;

        for (auto& [id, listener] : m_listeners) {
            if (listener.type != type) continue;

            // Rate limit
            auto elapsed = now - listener.last_reading;
            if (elapsed < std::chrono::milliseconds(min_interval_ms)) {
                continue;
            }

            // Apply precision reduction
            SensorReading reduced = ReducePrecision(reading, type);

            listener.last_reading = now;
            listener.callback(reduced);
        }
    }

    SensorReading ReducePrecision(const SensorReading& reading, SensorType type) {
        SensorReading reduced = reading;

        float precision = 0.01f;
        switch (type) {
            case SensorType::Accelerometer:
                precision = m_policy.accelerometer_precision;
                break;
            case SensorType::Gyroscope:
                precision = m_policy.gyroscope_precision;
                break;
            default:
                break;
        }

        reduced.x = std::round(reading.x / precision) * precision;
        reduced.y = std::round(reading.y / precision) * precision;
        reduced.z = std::round(reading.z / precision) * precision;

        return reduced;
    }

    std::unordered_map<uint32_t, SensorListener> m_listeners;
    SensorPolicy m_policy;
    uint32_t m_next_listener_id = 0;
};
```

### Sensor Lua API

```lua
-- Motion sensors (no special permission)
local accel_id = sensors.listen("accelerometer", function(reading)
    print("Acceleration:", reading.x, reading.y, reading.z)
end)

local gyro_id = sensors.listen("gyroscope", function(reading)
    print("Rotation:", reading.x, reading.y, reading.z)
end)

-- Stop listening
sensors.unlisten(accel_id)
sensors.unlisten(gyro_id)

-- Body sensors (requires "sensors.body" permission)
local granted = permissions.request("sensors.body")
if granted then
    sensors.listen("heart_rate", function(reading)
        print("Heart rate:", reading.value, "bpm")
    end)
end
```

---

## Bluetooth Interface Security

### Bluetooth Security Implementation

**Status**: Designed

```cpp
struct BluetoothPolicy {
    // Discovery
    bool allow_discovery = true;
    int discovery_timeout_seconds = 30;
    int max_discovered_devices = 50;

    // Connections
    int max_connections_per_app = 3;
    bool require_pairing_consent = true;

    // Data
    size_t max_transfer_size = 1 * 1024 * 1024;  // 1 MB
};

class BluetoothManager {
public:
    // Discover nearby devices
    std::optional<uint32_t> StartDiscovery(LuaSandbox* sandbox,
                                           DiscoveryCallback callback) {
        if (!sandbox->HasPermission("bluetooth")) {
            return std::nullopt;
        }

        // Only one discovery at a time per app
        if (HasActiveDiscovery(sandbox->app_id())) {
            return std::nullopt;
        }

        uint32_t discovery_id = ++m_next_discovery_id;

        Discovery discovery{
            .id = discovery_id,
            .app_id = sandbox->app_id(),
            .callback = callback,
            .devices = {},
            .started_at = std::chrono::steady_clock::now()
        };

        m_discoveries[discovery_id] = discovery;

        // Start hardware discovery with timeout
        m_hardware_bt->StartDiscovery(
            m_policy.discovery_timeout_seconds,
            [this, discovery_id](BluetoothDevice device) {
                OnDeviceDiscovered(discovery_id, device);
            });

        return discovery_id;
    }

    // Connect to device
    std::optional<uint32_t> Connect(LuaSandbox* sandbox,
                                    const std::string& device_address) {
        if (!sandbox->HasPermission("bluetooth")) {
            return std::nullopt;
        }

        // Connection limit
        if (CountAppConnections(sandbox->app_id()) >= m_policy.max_connections_per_app) {
            return std::nullopt;
        }

        // Require user consent for pairing
        if (m_policy.require_pairing_consent) {
            if (!ShowPairingDialog(device_address)) {
                return std::nullopt;
            }
        }

        // Connect
        auto conn = m_hardware_bt->Connect(device_address);
        if (!conn) return std::nullopt;

        uint32_t conn_id = ++m_next_conn_id;

        BluetoothConnection connection{
            .id = conn_id,
            .app_id = sandbox->app_id(),
            .device_address = device_address,
            .hardware_handle = *conn
        };

        m_connections[conn_id] = connection;
        return conn_id;
    }

private:
    void OnDeviceDiscovered(uint32_t discovery_id, BluetoothDevice device) {
        auto it = m_discoveries.find(discovery_id);
        if (it == m_discoveries.end()) return;

        // Limit discovered devices
        if (it->second.devices.size() >= m_policy.max_discovered_devices) {
            return;
        }

        it->second.devices.push_back(device);
        it->second.callback(device);
    }

    std::unordered_map<uint32_t, Discovery> m_discoveries;
    std::unordered_map<uint32_t, BluetoothConnection> m_connections;
    BluetoothPolicy m_policy;
    IHardwareBluetooth* m_hardware_bt;
    uint32_t m_next_discovery_id = 0;
    uint32_t m_next_conn_id = 0;
};
```

### Bluetooth Lua API

```lua
-- Request permission
local granted = permissions.request("bluetooth")
if not granted then return end

-- Discover devices
local discovery = bluetooth.discover(function(device)
    print("Found:", device.name, device.address)
end)

-- Stop discovery
discovery:stop()

-- Connect to device (shows pairing dialog)
local conn = bluetooth.connect("AA:BB:CC:DD:EE:FF")
if conn then
    -- Send data
    conn:send("Hello")

    -- Receive data
    conn:onData(function(data)
        print("Received:", data)
    end)

    -- Disconnect
    conn:close()
end
```

---

## Contacts Interface Security

### Contacts Security Implementation

**Status**: Designed

```cpp
struct ContactsPolicy {
    // Access scope
    bool allow_read_all = true;
    bool allow_write = true;
    bool allow_delete = true;

    // Rate limits
    int max_contacts_per_query = 1000;
    int max_writes_per_minute = 100;

    // Privacy
    bool require_purpose_string = true;  // App must explain why
    bool log_all_access = true;
};

class ContactsManager {
public:
    std::optional<std::vector<Contact>> GetContacts(LuaSandbox* sandbox,
                                                    const ContactQuery& query) {
        if (!sandbox->HasPermission("contacts.read")) {
            return std::nullopt;
        }

        // Rate limit
        if (!m_rate_limiter.Check(sandbox->app_id(), "contacts_read")) {
            return std::nullopt;
        }

        // Query contacts
        auto contacts = m_contacts_store->Query(query);

        // Limit results
        if (contacts.size() > m_policy.max_contacts_per_query) {
            contacts.resize(m_policy.max_contacts_per_query);
        }

        AuditLog::Log({sandbox->app_id(), AuditEvent::ContactsAccess,
                      "read " + std::to_string(contacts.size()) + " contacts", true});

        return contacts;
    }

    bool CreateContact(LuaSandbox* sandbox, const Contact& contact) {
        if (!sandbox->HasPermission("contacts.write")) {
            return false;
        }

        // Rate limit
        if (!m_rate_limiter.Check(sandbox->app_id(), "contacts_write")) {
            return false;
        }

        // Validate contact data
        if (!ValidateContact(contact)) {
            return false;
        }

        bool success = m_contacts_store->Create(contact);

        AuditLog::Log({sandbox->app_id(), AuditEvent::ContactsAccess,
                      "create contact: " + contact.name, success});

        return success;
    }

    bool DeleteContact(LuaSandbox* sandbox, const std::string& contact_id) {
        if (!sandbox->HasPermission("contacts.write")) {
            return false;
        }

        // Rate limit
        if (!m_rate_limiter.Check(sandbox->app_id(), "contacts_write")) {
            return false;
        }

        bool success = m_contacts_store->Delete(contact_id);

        AuditLog::Log({sandbox->app_id(), AuditEvent::ContactsAccess,
                      "delete contact: " + contact_id, success});

        return success;
    }

private:
    bool ValidateContact(const Contact& contact) {
        // Name required
        if (contact.name.empty()) return false;
        if (contact.name.length() > 256) return false;

        // Validate phone numbers
        for (const auto& phone : contact.phones) {
            if (phone.number.length() > 50) return false;
        }

        // Validate emails
        for (const auto& email : contact.emails) {
            if (!IsValidEmail(email.address)) return false;
        }

        return true;
    }

    ContactsPolicy m_policy;
    IContactsStore* m_contacts_store;
    RateLimiter m_rate_limiter;
};
```

### Contacts Lua API

```lua
-- Request permission
local granted = permissions.request("contacts.read")

-- Query contacts
local contacts = contacts.getAll()
for _, c in ipairs(contacts) do
    print(c.name, c.phones[1], c.emails[1])
end

-- Search contacts
local results = contacts.search("John")

-- Get single contact
local contact = contacts.get(contact_id)

-- Create contact (requires contacts.write)
contacts.create({
    name = "John Doe",
    phones = {{type = "mobile", number = "+1234567890"}},
    emails = {{type = "home", address = "john@example.com"}}
})

-- Update contact
contacts.update(contact_id, {
    name = "John Smith"
})

-- Delete contact
contacts.delete(contact_id)
```

---

## Implementation Status - Virtual Hardware

| Interface | Design | Implementation | Testing |
|-----------|--------|----------------|---------|
| Network HTTP | ✅ Complete | ❌ Not started | ❌ |
| Network WebSocket | ✅ Complete | ❌ Not started | ❌ |
| Filesystem | ✅ Complete | ❌ Not started | ❌ |
| Database | ✅ Complete | ❌ Not started | ❌ |
| Camera | ✅ Complete | ❌ Not started | ❌ |
| Microphone | ✅ Complete | ❌ Not started | ❌ |
| Speaker/Audio | ✅ Complete | ❌ Not started | ❌ |
| Location | ✅ Complete | ❌ Not started | ❌ |
| Sensors | ✅ Complete | ❌ Not started | ❌ |
| Bluetooth | ✅ Complete | ❌ Not started | ❌ |
| Contacts | ✅ Complete | ❌ Not started | ❌ |

---

## References

- [Lua 5.4 Manual - Sandboxing](https://www.lua.org/manual/5.4/manual.html#4.6)
- [Sandboxing Lua](http://lua-users.org/wiki/SandBoxes)
- [Lapis Lua Sandbox](https://github.com/leafo/lapis/blob/master/lapis/util/sandbox.moon)
- [Cloudflare Workers Lua Isolation](https://blog.cloudflare.com/cloudflare-workers-unleashed/)
- [OWASP Sandboxing Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Sandboxing_Cheat_Sheet.html)
- [Android Permission Model](https://developer.android.com/guide/topics/permissions/overview)
- [iOS App Sandbox Design Guide](https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/)
- [SQLite Security](https://www.sqlite.org/security.html)

---

*Last updated: 2026-01-18*