KossJS

Appearance

安全与沙箱指南 ​

KossJS 默认行为与 Node.js 一致：信任运行在其中的 JS 代码，赋予其完整的文件系统、网络和加密能力。对于运行可信代码的场景，这是合理的设计。

然而，当 KossJS 被嵌入到运行不可信 JS 代码的应用中时（如第三方插件引擎、用户脚本沙箱），这些能力成为安全风险。KossJS 提供了位掩码能力集（Capability Bitmask）来精确控制每个实例的权限。

能力位定义 ​

c
typedef enum {
    KOSS_CAP_FS              = 1 << 0,  // 文件系统：read/write/delete/mkdir/readdir/link 等全部操作
    KOSS_CAP_NET             = 1 << 1,  // 网络：fetch() + 原始 TCP/UDP socket + DNS 解析
    KOSS_CAP_CRYPTO          = 1 << 2,  // 加密：hash/hmac/pbkdf2/random/randomUUID
    KOSS_CAP_WORKER          = 1 << 3,  // Worker 线程池 + Worker 相关 JS API
    KOSS_CAP_EXTERNAL_LOADER = 1 << 4,  // 外部模块加载器（koss_register_module_loader 回调）

    // 预设组合
    KOSS_CAP_ALL     = 0xFFFFFFFF,  // 全部启用（默认，向后兼容）
    KOSS_CAP_SANDBOX = 0,           // 沙箱：禁用 fs|net|crypto|worker|external_loader
} KossCapability;

使用方式 ​

C 语言 ​

c
// 纯计算实例（无 IO）
KossInstance *k = koss_create_with_caps(KOSS_CAP_SANDBOX);
koss_eval(k, "1 + 1");  // 正常工作
koss_eval(k, "require('fs').readFileSync('/etc/passwd')");  // 抛出错误 — fs 不可用

// 只允许网络请求
KossInstance *k2 = koss_create_with_caps(KOSS_CAP_NET);

// 允许 fs + net，禁止 crypto + worker + 外部加载器
KossInstance *k3 = koss_create_with_caps(KOSS_CAP_FS | KOSS_CAP_NET);

// 模块 + 能力组合
KossInstance *k4 = koss_create_with_modules_and_caps(".", KOSS_CAP_FS | KOSS_CAP_NET);

Python 语言 ​

python
from kossjs_interface import KossJS

# 沙箱模式（纯计算）
koss = KossJS(capabilities=KossJS.KOSS_CAP_SANDBOX)

# 部分启用
koss2 = KossJS(capabilities=KossJS.KOSS_CAP_NET | KossJS.KOSS_CAP_CRYPTO)

# 完全启用（默认，向后兼容）
koss3 = KossJS()  # 等价于 capabilities=KossJS.KOSS_CAP_ALL

# 搭配模块加载
koss4 = KossJS(with_modules=True, root_dir="./modules",
               capabilities=KossJS.KOSS_CAP_NET)

禁用后的行为 ​

当 JS 代码尝试使用被禁用的能力时：

javascript
// 假设实例禁用了 KOSS_CAP_FS

const fs = require('fs');     // require 仍然可以解析模块名
fs.readFileSync('/etc/passwd') // → TypeError: fs.readFileSync is not a function

原因是禁用的 internalBinding() 返回 undefined，导致该能力的原生函数不存在，JS 侧调用时报 TypeError。

Worker API 在 KOSS_CAP_WORKER 禁用时不会被注册到全局作用域，fetch polyfill 和原生 fetch 在 KOSS_CAP_NET 禁用时不会注册。

不受能力限制的模块 ​

以下模块始终可用（纯计算，无 I/O 副作用）：

模块说明
os基本系统信息（CPU、内存、hostname），不涉及 I/O 操作
timerssetTimeout / setInterval 是 JS 运行时的基本功能
bufferBuffer 字节操作是纯内存计算
constants常量值查询，无副作用
urlURL 解析是纯计算
console标准输出

不���能力控制的操作 ​

以下 API 由宿主主动调用，属于宿主权限范围：

API说明
koss_run_file()宿主决定执行哪个文件
koss_eval() / koss_run_string()代码执行是 JS 运行时的核心功能
koss_set_global_*宿主向 JS 注入数据
koss_register_function / koss_register_class宿主注入自定义能力

Python 常量参考 ​

python
KossJS.KOSS_CAP_FS              = 1 << 0  # 1
KossJS.KOSS_CAP_NET             = 1 << 1  # 2
KossJS.KOSS_CAP_CRYPTO          = 1 << 2  # 4
KossJS.KOSS_CAP_WORKER          = 1 << 3  # 8
KossJS.KOSS_CAP_EXTERNAL_LOADER = 1 << 4  # 16
KossJS.KOSS_CAP_SANDBOX         = 0
KossJS.KOSS_CAP_ALL             = 0xFFFFFFFF

安全建议 ​

  1. 运行不可信代码时始终使用最小权限原则：仅启用必要的���力
  2. 不要暴露敏感原生函数：koss_register_function 注入的函数不受能力控制
  3. 设置合理的 timeout：koss_run_async 的超时参数可防止无限执行
  4. 限制 Worker 数量：koss_create_worker_pool 最大 64 个
  5. 查询当前能力：用 koss_get_capabilities 验证实例权限状态

相关 API ​