koss_create_with_caps 函数

功能描述：按能力位掩码创建 JavaScript 实例，精确控制沙箱权限。
返回值：成功返回实例指针，失败返回 NULL。

函数签名

KossInstance* koss_create_with_caps(uint32_t caps);

参数

参数	类型	说明
caps	uint32_t	能力位掩码（见 KossCapability）

能力位定义

KOSS_CAP_FS              = 1 << 0  // 文件系统
KOSS_CAP_NET             = 1 << 1  // 网络（fetch + socket + DNS）
KOSS_CAP_CRYPTO          = 1 << 2  // 加密（hash/hmac/pbkdf2/random）
KOSS_CAP_WORKER          = 1 << 3  // Worker 线程池
KOSS_CAP_EXTERNAL_LOADER = 1 << 4  // 外部模块加载器
KOSS_CAP_ALL             = 0xFFFFFFFF  // 全部启用（默认）
KOSS_CAP_SANDBOX         = 0           // 纯计算沙箱

说明

创建一个新的 JS 实例，通过位掩码精确控制可用的能力（文件系统、网络、加密、Worker、外部模块加载器）。被禁用的能力在 JS 侧调用时返回 undefined。

详见 安全与沙箱指南。

使用示例

C

// 纯计算实例（无 IO）
KossInstance* inst = koss_create_with_caps(KOSS_CAP_SANDBOX);
koss_eval(inst, "1 + 1");  // 正常工作
koss_destroy(inst);

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

// 允许 fs + net，禁止 crypto + worker
KossInstance* inst3 = koss_create_with_caps(KOSS_CAP_FS | KOSS_CAP_NET);

Python

from kossjs_interface import KossJS

# 沙箱模式
koss = KossJS(capabilities=KossJS.KOSS_CAP_SANDBOX)

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