@webskill/sdk 0.1.5 → 0.2.1

package/README.md

@@ -15,12 +15,16 @@ governance.
   the LLM, guardrails, lifecycle events, memory, human interaction
   (missing-parameter forms, confirmations, authorization prompts), and
   resumable interrupted runs.
-- **Script sandbox** — `worker_threads` sandbox for Node, Web Worker sandbox for
-  the browser. Deny-by-default network policy, deny-by-default builtin-module
-  allowlist, per-capability forced approval, timeouts kill runaway scripts.
-  **Honest note:** these executors reduce the capability surface — they are NOT
-  a security boundary. Scripts share the host process/origin and bypasses
-  exist; never rely on them to isolate untrusted scripts.
+- **Script sandbox** — two tiers. Isolation-grade: Node `ProcessSandboxExecutor`
+  (`child_process.fork` + `--permission`, experimental; fs scoped to the skill
+  root, workers/child processes/addons denied by default — note the permission
+  model has NO network dimension, so `fetch`/`WebSocket` stay patch-enforced and
+  bare `node:net` imports remain a documented residual), and the browser opaque
+  origin sandbox (`sandbox="allow-scripts"` iframe hosting a classic Worker —
+  `type:"module"` workers cannot load in opaque origins, verified). Capability
+  tier (NOT a security boundary): `SandboxedScriptExecutor` /
+  `BrowserWorkerScriptExecutor` in blob-Worker mode, with deny-by-default
+  network policy, builtin-module allowlist, forced approval, timeouts.
 - **`navigator.webskill`** — a browser facade (`discover` / `read` / `validate` /
   `run` / `install` / `uninstall`) assembled explicitly in one call.
 - **MCP** — call page-provided tools and consume page-declared dynamic skills
@@ -102,7 +106,8 @@ const run = await api.run('Summarize the references of skill greeter.');
 
 ### `@webskill/sdk/node`
 
-Node host: `NodeFS`, script executors (in-process + `worker_threads` sandbox),
+Node host: `NodeFS`, script executors (in-process, `worker_threads` sandbox, and
+`ProcessSandboxExecutor` for real process isolation),
 file-backed stores, `SkillManager` (install/export incl. multi-skill packs),
 CLI UI bridge, schema inference.
 
@@ -117,9 +122,10 @@ console.log((await manager.verifyIntegrity('greeter')).ok);
 
 ### `@webskill/sdk/browser`
 
-Browser host: OPFS provider, Web Worker script sandbox (deny-by-default network
-policy), worker runtime host/client, `BrowserSkillManager`, and the
-`navigator.webskill` assembler. See
+Browser host: OPFS provider, opaque origin iframe script sandbox (default on
+the main thread; engines running inside a Worker automatically fall back to the
+blob Worker form — no iframe is available there, documented), worker runtime
+host/client, `BrowserSkillManager`, and the `navigator.webskill` assembler. See
 [`examples/quickstart-browser`](../examples/quickstart-browser).
 
 ```js

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-import { C as FileStat, I as SkillInstallSource, K as VerifyResult, W as SkillsLockfile, _ as RenderResultRequest, a as InteractionPolicy, c as LlmClient, d as LlmResponse, f as LlmStreamEvent, o as InteractionRequest, s as InteractionResponse, v as UiBridge, w as FileSystemProvider, y as ArchiveLimits, z as SkillManifest } from "./types-CgNC-oQu-DEcIBJKG.js";
-import { N as NetworkPolicy, St as parseBridgeRequest, X as ScriptExecutionContext, Z as ScriptExecutor, ct as WebSkillApi, d as BridgeCapabilities, dt as bridgeError, et as ToolDefinition, m as BridgeResponse, nt as ToolResult, p as BridgeRequest, u as ApprovalScope, v as ExternalSkillProvider, y as ExternalToolSource } from "./index-COuOu6gw.js";
+import { C as FileStat, I as SkillInstallSource, K as VerifyResult, W as SkillsLockfile, _ as RenderResultRequest, a as InteractionPolicy, c as LlmClient, d as LlmResponse, f as LlmStreamEvent, o as InteractionRequest, s as InteractionResponse, v as UiBridge, w as FileSystemProvider, y as ArchiveLimits, z as SkillManifest } from "./types-CKm5G_eQ-8W8FnP4u.js";
+import { N as NetworkPolicy, Q as ScriptExecutor, Z as ScriptExecutionContext, d as BridgeCapabilities, it as ToolResult, m as BridgeResponse, nt as ToolDefinition, p as BridgeRequest, pt as bridgeError, u as ApprovalScope, ut as WebSkillApi, v as ExternalSkillProvider, wt as parseBridgeRequest, y as ExternalToolSource } from "./index-gjFuBevI.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -24,6 +24,7 @@ declare class OpfsProvider implements FileSystemProvider {
   remove(p: string, options?: {
     recursive?: boolean;
   }): Promise<void>;
+  rename(from: string, to: string): Promise<void>;
 }
 //#endregion
 //#region src/executor/workerBootstrap.d.ts
@@ -122,6 +123,8 @@ interface WorkerLike {
   terminate(): void;
 }
 type WorkerFactory = () => WorkerLike;
+/** 沙箱形态：opaque iframe（默认，主线程可用 document 时）/ blob Worker（Worker 内引擎回退） */
+type SandboxMode = 'iframe' | 'worker' | 'auto';
 /**
  * Web Worker 脚本沙箱执行器：loadDefinition 与 execute 都在 Worker 内完成，
  * 主线程从不 import 技能脚本；每次执行独立 Worker；超时 terminate 强杀。
@@ -132,6 +135,12 @@ declare class BrowserWorkerScriptExecutor implements ScriptExecutor {
   constructor(deps: {
     fs: FileSystemProvider;
     workerFactory?: WorkerFactory;
+    /**
+     * 沙箱形态：'auto'（默认）——主线程用 opaque origin iframe（sandbox=allow-scripts srcdoc，
+     * 真实隔离）；Worker 内引擎自动回退 blob Worker（无 iframe 可用，文档明示）。
+     * 显式 'worker' 强制 blob Worker（0.1.x 旧形态）。
+     */
+    sandbox?: SandboxMode;
     capabilities?: BridgeCapabilities;
     /** 网络策略：默认 'deny-all'（白名单见 runtime/sandbox/networkPolicy） */
     networkPolicy?: NetworkPolicy;
@@ -152,6 +161,31 @@ declare class BrowserWorkerScriptExecutor implements ScriptExecutor {
   }): Promise<ToolResult>;
 }
 //#endregion
+//#region src/executor/iframeSandbox.d.ts
+/**
+ * opaque origin 沙箱 iframe（sandbox="allow-scripts" srcdoc）：
+ * iframe 内建 module Worker（Blob URL），iframe window 作 postMessage 中继。
+ * opaque origin：沙箱内摸不到页面 DOM/localStorage/OPFS（独立 storage 分区）。
+ * 就绪握手：iframe 加载完成发 sandbox-ready 后才放行出站消息（防丢失）。
+ */
+declare class IframeWorkerLike implements WorkerLike {
+  #private;
+  constructor(iframe: HTMLIFrameElement);
+  get ready(): boolean;
+  markReady(): void;
+  postMessage(data: unknown): void;
+  addEventListener(_type: 'message', listener: (event: {
+    data: unknown;
+  }) => void): void;
+  emit(data: unknown): void;
+  terminate(): void;
+}
+/**
+ * 创建 opaque iframe 沙箱 Worker：sandbox="allow-scripts" srcdoc iframe 承载 module Worker。
+ * 返回 IframeWorkerLike（协议与 blob Worker 完全一致：load/execute/bridge/network-blocked）。
+ */
+declare function createIframeWorker(bootstrapSource: string, doc?: Document): IframeWorkerLike;
+//#endregion
 //#region src/navigator.d.ts
 declare global {
   /** 0.0.6：installWebSkillNavigator 显式装配后可用（不自动挂全局） */
@@ -342,4 +376,4 @@ declare class WorkerUiBridge implements UiBridge {
   onTextDelta(runId: string, delta: string): Promise<void>;
 }
 //#endregion
-export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, BrowserSkillManager, BrowserWorkerScriptExecutor, type LlmClientConfig, type MainToWorkerMessage, OpfsProvider, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, WORKER_BOOTSTRAP_SOURCE, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, bridgeError, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, startWorkerRuntimeHost };
+export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, BrowserSkillManager, BrowserWorkerScriptExecutor, IframeWorkerLike, type LlmClientConfig, type MainToWorkerMessage, OpfsProvider, type SandboxMode, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, WORKER_BOOTSTRAP_SOURCE, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, bridgeError, createIframeWorker, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, startWorkerRuntimeHost };

package/dist/browser.js

@@ -1,6 +1,6 @@
-import { A as validateSkills, C as parseSkillPackManifest, O as resolveInsideRoot, S as parseSkillMarkdown, c as SkillDiscovery, f as buildCatalog, i as SKILL_MANIFEST_FILE, j as verifyManifest, k as unzipWithLimits, p as buildManifest, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, v as exportSkills, w as readResponseWithLimit, y as isValidSkillName } from "./dist-fZFZaf43.js";
-import { A as mergeCatalogEntries, M as normalizeToolContent, N as parseBridgeRequest, S as bridgeError, T as createWebSkillApi, c as FsArtifactStore, h as ProgressiveRouter, i as AgentLoop, j as networkUrlHost, k as isNetworkAllowed, l as FsMemoryStore, m as OpenAiCompatibleClient, o as CapabilityApproval, u as FsRunSnapshotStore, y as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-DuGN5x0v.js";
-import { n as MockLlmClient } from "./testing-BmR48Pn1.js";
+import { A as unzipWithLimits, C as parseSkillMarkdown, M as verifyManifest, T as readResponseWithLimit, b as isValidSkillName, c as SkillDiscovery, f as atomicWriteText, i as SKILL_MANIFEST_FILE, j as validateSkills, k as resolveInsideRoot, m as buildManifest, p as buildCatalog, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, w as parseSkillPackManifest, y as exportSkills } from "./dist-D0saNPi_.js";
+import { A as isNetworkAllowed, C as bridgeError, E as createWebSkillApi, M as networkUrlHost, N as normalizeToolContent, P as parseBridgeRequest, c as FsArtifactStore, h as ProgressiveRouter, i as AgentLoop, j as mergeCatalogEntries, l as FsMemoryStore, m as OpenAiCompatibleClient, o as CapabilityApproval, u as FsRunSnapshotStore, y as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-DrySSQ5R.js";
+import { n as MockLlmClient } from "./testing-B4pq6JYa.js";
 
 //#region ../browser/dist/index.js
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -132,6 +132,11 @@ var OpfsProvider = class {
 			await (await this.#walkDir(`/${segments.join("/")}`, false)).removeEntry(name, { recursive: options?.recursive ?? false });
 		});
 	}
+	async rename(from, to) {
+		if ((await this.stat(from)).type === "directory") throw new WebSkillError("FS_PERMISSION_DENIED", `rename of directories is not supported on OPFS: ${from}`);
+		await this.writeBinary(to, await this.readBinary(from));
+		await this.remove(from);
+	}
 };
 /**
 * Worker 引导源码（字符串 → Blob URL → new Worker(url, {type:'module'})）。
@@ -700,21 +705,114 @@ var BrowserSkillManager = class {
 	async #upsertLockEntry(name, entry) {
 		const lockfile = await this.listInstalled();
 		lockfile.skills[name] = entry;
-		await this.#fs.writeText(lockfilePath(this.#managedRoot), JSON.stringify(lockfile, null, 2));
+		await atomicWriteText(this.#fs, lockfilePath(this.#managedRoot), JSON.stringify(lockfile, null, 2));
 	}
 	async #removeLockEntry(name) {
 		const lockfile = await this.listInstalled();
 		delete lockfile.skills[name];
-		await this.#fs.writeText(lockfilePath(this.#managedRoot), JSON.stringify(lockfile, null, 2));
+		await atomicWriteText(this.#fs, lockfilePath(this.#managedRoot), JSON.stringify(lockfile, null, 2));
+	}
+};
+const ENVELOPE = "__webskill_sandbox__";
+/**
+* opaque origin 沙箱 iframe（sandbox="allow-scripts" srcdoc）：
+* iframe 内建 module Worker（Blob URL），iframe window 作 postMessage 中继。
+* opaque origin：沙箱内摸不到页面 DOM/localStorage/OPFS（独立 storage 分区）。
+* 就绪握手：iframe 加载完成发 sandbox-ready 后才放行出站消息（防丢失）。
+*/
+var IframeWorkerLike = class {
+	#iframe;
+	#ready = false;
+	#queue = [];
+	constructor(iframe) {
+		this.#iframe = iframe;
+	}
+	get ready() {
+		return this.#ready;
+	}
+	markReady() {
+		this.#ready = true;
+		for (const payload of this.#queue) this.#post(payload);
+		this.#queue = [];
+	}
+	#post(payload) {
+		this.#iframe.contentWindow?.postMessage({
+			[ENVELOPE]: true,
+			payload
+		}, "*");
+	}
+	postMessage(data) {
+		if (this.#ready) this.#post(data);
+		else this.#queue.push(data);
+	}
+	addEventListener(_type, listener) {
+		this.#listeners.add(listener);
+	}
+	#listeners = /* @__PURE__ */ new Set();
+	emit(data) {
+		for (const listener of this.#listeners) listener({ data });
+	}
+	terminate() {
+		this.#iframe.remove();
 	}
 };
-const defaultWorkerFactory = () => {
+/** srcdoc 文档：内嵌 Worker 引导源码 + 双向中继（BOOTSTRAP 经 JSON 字符串注入，防 <\/script> 截断） */
+function sandboxDocument(bootstrapSource) {
+	const bootstrapJson = JSON.stringify(bootstrapSource).replace(/<\//g, "<\\/");
+	return `<!doctype html>
+<html><head><meta charset="utf-8"></head><body><script>
+const ENVELOPE = ${JSON.stringify(ENVELOPE)};
+const blob = new Blob([${bootstrapJson}], { type: 'text/javascript' });
+const url = URL.createObjectURL(blob);
+// 注意：opaque origin 下 module Worker 无法加载（实证），classic Worker + data: URL 动态导入可用
+const worker = new Worker(url);
+URL.revokeObjectURL(url);
+window.addEventListener('message', (event) => {
+  const data = event.data;
+  if (data && data[ENVELOPE]) worker.postMessage(data.payload);
+});
+worker.addEventListener('message', (event) => {
+  parent.postMessage({ [ENVELOPE]: true, payload: event.data }, '*');
+});
+worker.addEventListener('error', (event) => {
+  parent.postMessage({ [ENVELOPE]: true, payload: { type: 'sandbox-worker-error', message: event.message } }, '*');
+});
+parent.postMessage({ [ENVELOPE]: true, payload: { type: 'sandbox-ready' } }, '*');
+<\/script></body></html>`;
+}
+/**
+* 创建 opaque iframe 沙箱 Worker：sandbox="allow-scripts" srcdoc iframe 承载 module Worker。
+* 返回 IframeWorkerLike（协议与 blob Worker 完全一致：load/execute/bridge/network-blocked）。
+*/
+function createIframeWorker(bootstrapSource, doc = document) {
+	const iframe = doc.createElement("iframe");
+	iframe.setAttribute("sandbox", "allow-scripts");
+	iframe.style.display = "none";
+	iframe.srcdoc = sandboxDocument(bootstrapSource);
+	const worker = new IframeWorkerLike(iframe);
+	(doc.defaultView ?? window).addEventListener("message", (event) => {
+		const data = event.data;
+		if (!data || data[ENVELOPE] !== true) return;
+		if (data.payload && data.payload.type === "sandbox-ready") {
+			worker.markReady();
+			return;
+		}
+		worker.emit(data.payload);
+	});
+	doc.body.appendChild(iframe);
+	return worker;
+}
+const blobWorkerFactory = () => {
 	const blob = new Blob([WORKER_BOOTSTRAP_SOURCE], { type: "text/javascript" });
 	const url = URL.createObjectURL(blob);
 	const worker = new Worker(url, { type: "module" });
 	URL.revokeObjectURL(url);
 	return worker;
 };
+const resolveWorkerFactory = (mode) => {
+	if (mode === "iframe" || mode === "auto" && typeof document !== "undefined") return () => createIframeWorker(WORKER_BOOTSTRAP_SOURCE);
+	return blobWorkerFactory;
+};
 const baseName = (p) => p.split("/").pop() ?? p;
 const messageOf = (e) => e instanceof Error ? e.message : String(e);
 /**
@@ -731,7 +829,7 @@ var BrowserWorkerScriptExecutor = class {
 	#transpiler;
 	constructor(deps) {
 		this.#fs = deps.fs;
-		this.#workerFactory = deps.workerFactory ?? defaultWorkerFactory;
+		this.#workerFactory = deps.workerFactory ?? resolveWorkerFactory(deps.sandbox ?? "auto");
 		this.#transpiler = deps.typescript ? new TsTranspiler({
 			fs: deps.fs,
 			options: deps.typescript
@@ -1478,4 +1576,4 @@ var WorkerRuntimeClient = class {
 };
 
 //#endregion
-export { BrowserSkillManager, BrowserWorkerScriptExecutor, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, startWorkerRuntimeHost };
+export { BrowserSkillManager, BrowserWorkerScriptExecutor, IframeWorkerLike, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, createIframeWorker, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, startWorkerRuntimeHost };

package/dist/{dist-CfBOjJ4p.js → dist-BJobG0i-.js}

@@ -1,4 +1,4 @@
-import { u as WebSkillError } from "./dist-fZFZaf43.js";
+import { u as WebSkillError } from "./dist-D0saNPi_.js";
 
 //#region ../ui/dist/index.js
 /** 提交值按请求类型归形（WebFormBridge 与框架组件库共享单一来源） */
@@ -524,6 +524,8 @@ var WebFormBridge = class {
 	#doc;
 	#styles;
 	#progressEl;
+	/** 等待中的 request 取消句柄（id → 触发 cancelled 并卸载 DOM） */
+	#pending = /* @__PURE__ */ new Map();
 	constructor(options) {
 		this.#mount = options.mount;
 		this.#doc = options.document ?? options.mount.ownerDocument;
@@ -535,13 +537,27 @@ var WebFormBridge = class {
 		const model = interactionToFormModel(input);
 		const { form, cleanup } = this.#renderForm(model);
 		return new Promise((resolve) => {
+			const cancel = () => {
+				cleanup();
+				this.#pending.delete(input.id);
+				resolve({
+					id: input.id,
+					cancelled: true
+				});
+			};
+			this.#pending.set(input.id, cancel);
 			form.addEventListener("submit", (event) => {
 				event.preventDefault();
 				const { values, missingRequired } = collectValues(model.controls, form);
 				if (missingRequired.length > 0) {
-					for (const name of missingRequired) form.querySelector(`[${CONTROL_TAG}="${name}"]`)?.closest(".webskill-form__control")?.classList.add("webskill-form__control--invalid");
+					for (const name of missingRequired) {
+						const wrapper = form.querySelector(`[${CONTROL_TAG}="${name}"]`)?.closest(".webskill-form__control");
+						wrapper?.classList.add("webskill-form__control--invalid");
+						wrapper?.querySelector(".webskill-form__input")?.setAttribute("aria-invalid", "true");
+					}
 					return;
 				}
+				this.#pending.delete(input.id);
 				cleanup();
 				resolve({
 					id: input.id,
@@ -550,15 +566,15 @@ var WebFormBridge = class {
 			});
 			form.querySelector("[data-webskill-cancel]")?.addEventListener("click", (event) => {
 				event.preventDefault();
-				cleanup();
-				resolve({
-					id: input.id,
-					cancelled: true
-				});
+				cancel();
 			});
 			this.#mount.appendChild(form);
 		});
 	}
+	/** 尽力取消等待中的 request（超时后清理遗留表单） */
+	cancel(id) {
+		this.#pending.get(id)?.();
+	}
 	async renderResult(input) {
 		if (this.#styles) ensureStyles(this.#doc);
 		this.#clearProgress();
@@ -622,9 +638,12 @@ var WebFormBridge = class {
 		const doc = this.#doc;
 		const wrapper = doc.createElement("div");
 		wrapper.className = "webskill-form__control";
+		const controlId = `webskill-field-${control.name}`;
+		const errorId = `webskill-error-${control.name}`;
 		const label = doc.createElement("label");
 		label.className = control.required ? "webskill-form__label webskill-form__label-required" : "webskill-form__label";
 		label.textContent = control.label;
+		label.htmlFor = controlId;
 		wrapper.appendChild(label);
 		if (control.description) {
 			const desc = doc.createElement("div");
@@ -663,9 +682,13 @@ var WebFormBridge = class {
 			input = textInput;
 		}
 		input.setAttribute(CONTROL_TAG, control.name);
+		input.id = controlId;
+		input.setAttribute("aria-describedby", errorId);
 		wrapper.appendChild(input);
 		const error = doc.createElement("div");
 		error.className = "webskill-form__error";
+		error.id = errorId;
+		error.setAttribute("role", "alert");
 		error.textContent = "This field is required";
 		wrapper.appendChild(error);
 		return wrapper;