@webskill/sdk 0.2.8 → 0.4.0

package/dist/{dist-BQzncxXg.js → dist-8oQRa8Xz.js}

@@ -24,6 +24,20 @@ function messageOf(e) {
 const SKILL_MANIFEST_FILE = "webskill.skill-manifest.json";
 /** managed root 下的锁定文件名（不参与 files 列表与 digest） */
 const SKILLS_LOCKFILE = "skills.lock.json";
+/** 技能目录内的签名文件名（不参与 files 列表与 digest） */
+const SKILL_SIGNATURE_FILE = "webskill.skill-signature.json";
+/**
+* 不参与 digest 的技能目录内文件。
+*
+* 这份名单原本在 node / browser / console / core 各抄一份，签名文件一旦漏抄一处，
+* 写签名就会改变该处算出的 digest、让签名当场自我失效——而且只在「先签盘上的包、
+* 再从盘上验」时才暴露。收成一处是为了让「漏抄」这件事不再可能发生。
+*/
+const MANIFEST_EXCLUDED_FILES = /* @__PURE__ */ new Set([
+	SKILL_MANIFEST_FILE,
+	SKILLS_LOCKFILE,
+	SKILL_SIGNATURE_FILE
+]);
 /** 整体 digest：逐文件 "<path>:<sha256>\n" 拼接串（文件按 path 排序）的 sha256（hash 由调用方提供，可为 WebCrypto 异步实现） */
 async function computeDigest(files, sha256) {
 	return sha256([...files].sort((a, b) => a.path.localeCompare(b.path)).map((f) => `${f.path}:${f.sha256}\n`).join(""));
@@ -53,7 +67,7 @@ function verifyManifest(manifest, actualHashes, actualFiles = [...actualHashes.k
 		if (actual === void 0) missing.push(file.path);
 		else if (actual !== file.sha256) mismatches.push(file.path);
 	}
-	const extras = actualFiles.filter((p) => p !== "webskill.skill-manifest.json" && p !== "skills.lock.json" && !listed.has(p)).sort();
+	const extras = actualFiles.filter((p) => !MANIFEST_EXCLUDED_FILES.has(p) && !listed.has(p)).sort();
 	return {
 		ok: mismatches.length === 0 && missing.length === 0 && extras.length === 0,
 		mismatches,
@@ -61,6 +75,202 @@ function verifyManifest(manifest, actualHashes, actualFiles = [...actualHashes.k
 		missing
 	};
 }
+/**
+* 原子写文本：先写临时文件再 rename（进程崩溃不留下半写文件；lockfile 等账本场景）。
+* 原子性强弱取决于 provider 的 rename 实现：NodeFS/MemoryFS 为真 rename；
+* OPFS 无原生 move，rename 是 copy+delete（非原子，崩溃可能残留双份），
+* 对崩溃一致性要求极高的场景在浏览器侧需知悉此前提。
+*/
+async function atomicWriteText(fs, path, content) {
+	const tmp = `${path}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+	await fs.writeText(tmp, content);
+	await fs.rename(tmp, path);
+}
+/** 技能目录内的签名文件名（与 manifest 同级，不参与 files 列表与 digest） */
+const SKILL_SIGNATURE_FILE$1 = "webskill.skill-signature.json";
+const SIGNATURE_SCHEMA_VERSION = 1;
+const encoder = new TextEncoder();
+const toBase64Url = (bytes) => {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+const fromBase64Url = (value) => {
+	const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+	const binary = atob(padded);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+};
+const toHex = (bytes) => [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+function subtle() {
+	const available = globalThis.crypto?.subtle;
+	if (!available) throw new WebSkillError("SIGNATURE_UNSUPPORTED", "WebCrypto (globalThis.crypto.subtle) is unavailable in this environment; skill signatures cannot be verified");
+	return available;
+}
+/**
+* 签名载荷：固定键序手写拼装，**不依赖 JSON.stringify 的属性顺序**
+* （对象字面量顺序与运行时插入顺序不是同一件事，签验两侧字节必须逐字一致）。
+*
+* 载荷带 skill/version 而非裸 digest：只签 digest 时，同内容不同名的两个包
+* 签名可以互换，等于允许把 A 技能的签名挪到 B 技能上。
+*/
+function signaturePayloadBytes(manifest) {
+	const json = `{"schemaVersion":${JSON.stringify(1)},"algorithm":${JSON.stringify(manifest.integrity.algorithm)},"digest":${JSON.stringify(manifest.integrity.digest)},"skill":${JSON.stringify(manifest.name)},"version":${JSON.stringify(manifest.version ?? "")}}`;
+	return encoder.encode(json);
+}
+/** Ed25519 在部分浏览器仍在铺开：能力缺失是环境问题，不能报成数据问题 */
+async function importEd25519(key, format, usage) {
+	try {
+		return await subtle().importKey(format, key, { name: "Ed25519" }, false, [usage]);
+	} catch (e) {
+		if (e instanceof WebSkillError) throw e;
+		throw new WebSkillError("SIGNATURE_UNSUPPORTED", `This environment cannot import Ed25519 keys via WebCrypto; skill signature ${usage === "sign" ? "signing" : "verification"} is unavailable`, e);
+	}
+}
+async function keyIdOf(publicKey) {
+	const digest = await subtle().digest("SHA-256", publicKey);
+	return toHex(new Uint8Array(digest).slice(0, 16));
+}
+/** 结构校验：字段缺失/类型错/长度不对一律 SIGNATURE_MALFORMED */
+function parseSignature(raw, origin) {
+	const bad = (why) => {
+		throw new WebSkillError("SIGNATURE_MALFORMED", `Skill signature at ${origin} is invalid: ${why}`);
+	};
+	if (typeof raw !== "object" || raw === null) return bad("not a JSON object");
+	const file = raw;
+	if (typeof file.schemaVersion !== "number") return bad("missing \"schemaVersion\"");
+	if (file.schemaVersion > 1) return bad(`schemaVersion ${file.schemaVersion} is newer than this build understands`);
+	if (file.algorithm !== "ed25519") return bad(`unsupported algorithm ${JSON.stringify(file.algorithm)}`);
+	for (const field of [
+		"keyId",
+		"publicKey",
+		"signature",
+		"signedAt"
+	]) if (typeof file[field] !== "string" || file[field] === "") return bad(`missing "${field}"`);
+	const signature = file;
+	let publicKey;
+	let signatureBytes;
+	try {
+		publicKey = fromBase64Url(signature.publicKey);
+		signatureBytes = fromBase64Url(signature.signature);
+	} catch (e) {
+		return bad(`"publicKey" or "signature" is not valid base64url: ${e instanceof Error ? e.message : String(e)}`);
+	}
+	if (publicKey.length !== 32) return bad(`"publicKey" must be 32 raw bytes, got ${publicKey.length}`);
+	if (signatureBytes.length !== 64) return bad(`"signature" must be 64 raw bytes, got ${signatureBytes.length}`);
+	return signature;
+}
+/** 从技能目录读签名文件；文件不存在返回 undefined（缺签名由策略层判定，不是错误） */
+async function readSkillSignature(fs, skillRoot) {
+	const path = `${skillRoot}/${SKILL_SIGNATURE_FILE$1}`;
+	if (!await fs.exists(path)) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(await fs.readText(path));
+	} catch (e) {
+		throw new WebSkillError("SIGNATURE_MALFORMED", `Skill signature at ${path} is not valid JSON`, e);
+	}
+	return parseSignature(parsed, path);
+}
+/**
+* 验签。四种失败各自一个错误码，因为宿主的处置完全不同：
+* 缺签名要引导选策略，坏文件要提示重下，不受信的 key 要引导添加密钥，
+* 而验签不通过是安全事件，不提供「继续」。
+*
+* 包内自带的 publicKey **不产生任何信任**——它只是让「摘要不匹配」与
+* 「公钥不受信」两种失败可区分。信任判定只认信任库里的 keyId。
+*/
+async function verifySkillSignature(input) {
+	const { manifest, signature, trustedKeys, policy } = input;
+	const skill = JSON.stringify(manifest.name);
+	if (!signature) {
+		if (policy.unsigned === "deny") throw new WebSkillError("SIGNATURE_MISSING", `Skill ${skill} carries no ${SKILL_SIGNATURE_FILE$1} and the unsigned policy is "deny"`);
+		return {
+			ok: true,
+			unsigned: true,
+			...policy.unsigned === "warn" ? { warning: `Skill ${skill} is not signed; it was allowed by the "warn" unsigned policy` } : {}
+		};
+	}
+	const trusted = await trustedKeys.get(signature.keyId);
+	if (!trusted) throw new WebSkillError("SIGNATURE_UNTRUSTED_KEY", `Skill ${skill} is signed by key ${signature.keyId}, which is not in the trusted key store`);
+	if (trusted.publicKey !== signature.publicKey) throw new WebSkillError("SIGNATURE_MISMATCH", `Skill ${skill} declares key ${signature.keyId} but its embedded public key differs from the trusted one`);
+	const key = await importEd25519(fromBase64Url(trusted.publicKey), "raw", "verify");
+	if (!await subtle().verify("Ed25519", key, fromBase64Url(signature.signature), signaturePayloadBytes(manifest))) throw new WebSkillError("SIGNATURE_MISMATCH", `Signature verification failed for skill ${skill}: the signed digest does not match this package`);
+	return {
+		ok: true,
+		unsigned: false,
+		keyId: signature.keyId
+	};
+}
+/**
+* 为已生成 manifest 的技能产出签名。生产与测试走同一条路径——
+* 只提供 CLI 会让测试无法覆盖真正被调用的代码。
+*
+* `publicKey` 必须显式传入：WebCrypto 没有「由私钥导出公钥」的 API，
+* 密钥对的两半只能一起来。
+*/
+async function signSkill(input) {
+	const key = input.privateKey instanceof Uint8Array ? await importEd25519(input.privateKey, "pkcs8", "sign") : input.privateKey;
+	const signature = await subtle().sign("Ed25519", key, signaturePayloadBytes(input.manifest));
+	return {
+		schemaVersion: 1,
+		algorithm: "ed25519",
+		keyId: await keyIdOf(input.publicKey),
+		publicKey: toBase64Url(input.publicKey),
+		signature: toBase64Url(new Uint8Array(signature)),
+		signedAt: input.signedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+/**
+* `FileSystemProvider` 后端的信任库：单个 JSON 文件，写入走原子替换。
+*
+* 「OPFS 还是 IndexedDB 还是宿主注入」不在这层回答——`FileSystemProvider`
+* 已经是那层抽象，浏览器里落在哪由宿主注入的 fs 决定。
+*/
+var FsTrustedKeyStore = class {
+	#fs;
+	#path;
+	constructor(fs, path) {
+		this.#fs = fs;
+		this.#path = path;
+	}
+	async #read() {
+		if (!await this.#fs.exists(this.#path)) return [];
+		let parsed;
+		try {
+			parsed = JSON.parse(await this.#fs.readText(this.#path));
+		} catch (e) {
+			throw new WebSkillError("VALIDATION_FAILED", `Trusted key store at ${this.#path} is not valid JSON`, e);
+		}
+		const file = parsed;
+		if (!Array.isArray(file.keys)) throw new WebSkillError("VALIDATION_FAILED", `Trusted key store at ${this.#path} has no "keys" array`);
+		return file.keys;
+	}
+	async #write(keys) {
+		await atomicWriteText(this.#fs, this.#path, JSON.stringify({
+			schemaVersion: 1,
+			keys
+		}, null, 2));
+	}
+	async list() {
+		return this.#read();
+	}
+	async get(keyId) {
+		return (await this.#read()).find((key) => key.keyId === keyId);
+	}
+	async add(key) {
+		const keys = (await this.#read()).filter((existing) => existing.keyId !== key.keyId);
+		keys.push({
+			...key,
+			addedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		await this.#write(keys);
+	}
+	async remove(keyId) {
+		await this.#write((await this.#read()).filter((key) => key.keyId !== keyId));
+	}
+};
 const ROOT = "/";
 /** 内存文件系统：路径一律规范化为 `/` 分隔，写入自动创建父目录 */
 var MemoryFS = class {
@@ -204,17 +414,6 @@ var MemoryFS = class {
 		this.#entries.delete(src);
 	}
 };
-/**
-* 原子写文本：先写临时文件再 rename（进程崩溃不留下半写文件；lockfile 等账本场景）。
-* 原子性强弱取决于 provider 的 rename 实现：NodeFS/MemoryFS 为真 rename；
-* OPFS 无原生 move，rename 是 copy+delete（非原子，崩溃可能残留双份），
-* 对崩溃一致性要求极高的场景在浏览器侧需知悉此前提。
-*/
-async function atomicWriteText(fs, path, content) {
-	const tmp = `${path}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
-	await fs.writeText(tmp, content);
-	await fs.rename(tmp, path);
-}
 /** 统一分隔符为 `/`，去除 `.` 段与重复分隔符（不解析 `..`） */
 function normalizePath(path) {
 	return path.replace(/\\/g, "/").split("/").filter((s) => s !== "" && s !== ".").join("/");
@@ -836,4 +1035,4 @@ const xmlRenderer = {
 };
 
 //#endregion
-export { resolveArchiveLimits as A, messageOf as C, readResponseWithLimit as D, parseSkillPackManifest as E, xmlRenderer as F, unzipWithLimits as M, validateSkills as N, renderAvailableSkillsXml as O, verifyManifest as P, jsonRenderer as S, parseSkillMarkdown as T, checkSkillRules as _, SKILL_NAME_MAX_LENGTH as a, exportSkills as b, SkillDiscovery as c, assertRemoteUrlAllowed as d, assertSafePathSegment as f, checkDependencyCycles as g, buildManifest as h, SKILL_MANIFEST_FILE as i, resolveInsideRoot as j, renderCatalogJson as k, SkillReader as l, buildCatalog as m, MemoryFS as n, SKILL_NAME_PATTERN as o, atomicWriteText as p, SKILLS_LOCKFILE as r, SKILL_PACK_FILE as s, DEFAULT_ARCHIVE_LIMITS as t, WebSkillError as u, computeDigest as v, normalizePath as w, isValidSkillName as x, escapeXml as y };
+export { parseSkillMarkdown as A, unzipWithLimits as B, escapeXml as C, keyIdOf as D, jsonRenderer as E, renderCatalogJson as F, verifyManifest as H, resolveArchiveLimits as I, resolveInsideRoot as L, readResponseWithLimit as M, readSkillSignature as N, messageOf as O, renderAvailableSkillsXml as P, signSkill as R, computeDigest as S, isValidSkillName as T, verifySkillSignature as U, validateSkills as V, xmlRenderer as W, atomicWriteText as _, SIGNATURE_SCHEMA_VERSION as a, checkDependencyCycles as b, SKILL_NAME_MAX_LENGTH as c, SKILL_SIGNATURE_FILE as d, SkillDiscovery as f, assertSafePathSegment as g, assertRemoteUrlAllowed as h, MemoryFS as i, parseSkillPackManifest as j, normalizePath as k, SKILL_NAME_PATTERN as l, WebSkillError as m, FsTrustedKeyStore as n, SKILLS_LOCKFILE as o, SkillReader as p, MANIFEST_EXCLUDED_FILES as r, SKILL_MANIFEST_FILE as s, DEFAULT_ARCHIVE_LIMITS as t, SKILL_PACK_FILE as u, buildCatalog as v, exportSkills as w, checkSkillRules as x, buildManifest as y, signaturePayloadBytes as z };