Caffeine

🔧 Sandboxing

Planned Milestone: M3 — Scripting & Runtime Namespace: `Caffeine::Scripting` Arquivos: `src/scripting/Sandbox.hpp`, `src/scripting/Sandbox.cpp` RF: RF6.4 Last updated:

Visão Geral#

O sistema de Sandboxing do Caffeine Studio garante que os scripts de jogo operem num ambiente seguro e controlado. Ao contrário de uma aplicação Lua padrão, os scripts dentro do motor não devem ter acesso direto ao sistema de ficheiros do sistema operativo, execução de comandos externos ou manipulação de recursos críticos que possam comprometer a estabilidade do IDE ou a segurança do utilizador.

Este módulo redefine o ambiente global do Lua, removendo funções perigosas e substituindo-as por alternativas seguras fornecidas pela API caffeine.*. Isto permite que o motor corra scripts de terceiros (como plugins ou assets da comunidade) com um risco reduzido.


Implementação#

Políticas de Acesso#

A LuaVM configura o estado inicial restringindo as bibliotecas padrão.

Categoria Permitido Bloqueado / Removido
Core API caffeine.* os.*, io.* (exceto em modo editor)
Utilitários math.*, string.*, table.* load, loadstring
Módulos require (apenas módulos do projeto) package.loadlib
Debug Nenhuma debug.*

Implementação do Restritor (C++)#

cpp
void LuaVM::applySandbox() {
    // 1. Limpar bibliotecas perigosas
    m_lua["os"] = sol::nil;
    m_lua["io"] = sol::nil;
    m_lua["package"] = sol::nil;
    m_lua["load"] = sol::nil;
    m_lua["loadfile"] = sol::nil;
    m_lua["dofile"] = sol::nil;

    // 2. Criar alternativa segura para 'os.clock' se necessário
    auto os_safe = m_lua["os"].get_or_create<sol::table>();
    os_safe["clock"] = []() { return Timer::GetTotalSeconds(); };

    // 3. Redefinir 'require' para procurar apenas dentro da pasta 'scripts/' do projeto
    m_lua.set_function("require", [this](std::string moduleName) {
        return loadProjectModule(moduleName);
    });
}

Diagrama de Isolamento#

text
      [ SCRIPT LUA ]
            |
            v
+---------------------------+
|   Environment Wrapper     |
+-------------+-------------+
| SAFE API    | BLOCKED API |
| (caffeine.*)| (os.exit)   | ----> [ ERRO DE EXECUÇÃO ]
+-------------+-------------+
            |
            v
      [ ENGINE CORE ]

Decisões de Design#

Decisão Justificativa
Whitelist approach É mais seguro definir explicitamente o que é permitido do que tentar bloquear o que é proibido.
Remoção total de io Garante que scripts não podem ler dados sensíveis do utilizador ou escrever ficheiros maliciosos fora da sandbox.
Custom require Impede que scripts carreguem bibliotecas dinâmicas (.dll / .so) externas ao ecossistema do motor.

Critério de Aceitação#

  • [ ] Tentativas de chamar os.execute() resultam num erro de script.
  • [ ] A biblioteca io não está acessível no ambiente global.
  • [ ] O acesso a math e string permanece funcional.
  • [ ] O motor não crasha ao tentar executar uma função bloqueada.

Dependências#

  • Upstream: LuaVM
  • Downstream: AssetManager (para o carregamento seguro de módulos)

🔗 Tópicos Relacionados#

Tópico Description
docs/scripting/scripting.md Lista de APIs permitidas para programadores.
docs/assets/asset-manager.md Como os scripts são resolvidos no sistema de ficheiros.

Referências#