@dot-skill/core 0.4.1

package/dist/pack.js

@@ -0,0 +1,191 @@
+import { zipSync, unzipSync, strToU8, strFromU8 } from "fflate";
+import { packageDigestFromContent, sha256Digest } from "./hash.js";
+import { assertSafePaths, MAX_COMPRESSION_RATIO, MAX_ENTRIES, MAX_UNCOMPRESSED_BYTES, normalizePath, } from "./paths.js";
+function toBytes(data) {
+    return typeof data === "string" ? strToU8(data) : data;
+}
+function textEncode(obj) {
+    return strToU8(JSON.stringify(obj, null, 2) + "\n");
+}
+export function buildFileMap(pkg) {
+    const files = {};
+    files["workflow.json"] = textEncode(pkg.workflow);
+    for (const item of pkg.knowledge) {
+        files[`knowledge/${item.id}.json`] = textEncode(item);
+    }
+    if (pkg.prompts) {
+        for (const [name, body] of Object.entries(pkg.prompts)) {
+            files[`prompts/${normalizePath(name)}`] = toBytes(body);
+        }
+    }
+    if (pkg.resources) {
+        for (const [name, body] of Object.entries(pkg.resources)) {
+            files[`resources/${normalizePath(name)}`] = toBytes(body);
+        }
+    }
+    if (pkg.artifacts) {
+        for (const [name, body] of Object.entries(pkg.artifacts)) {
+            files[`artifacts/${normalizePath(name)}`] = toBytes(body);
+        }
+    }
+    if (pkg.provenance?.recipe) {
+        files["provenance/recipe.json"] = textEncode(pkg.provenance.recipe);
+    }
+    if (pkg.provenance?.source) {
+        files["provenance/source.json"] = textEncode(pkg.provenance.source);
+    }
+    if (pkg.provenance?.journey) {
+        files["provenance/journey.json"] = textEncode(pkg.provenance.journey);
+    }
+    if (pkg.provenance?.generation_usage) {
+        files["provenance/generation_usage.json"] = textEncode(pkg.provenance.generation_usage);
+    }
+    if (pkg.provenance?.proof) {
+        files["provenance/proof.json"] = textEncode(pkg.provenance.proof);
+    }
+    if (pkg.provenance?.compilation_report) {
+        files["provenance/compilation_report.json"] = textEncode(pkg.provenance.compilation_report);
+    }
+    if (pkg.attestation && !pkg.signatures?.["creation.dsse.json"]) {
+        files["signatures/creation.attestation.json"] = textEncode(pkg.attestation);
+    }
+    if (pkg.signatures) {
+        for (const [name, body] of Object.entries(pkg.signatures)) {
+            files[`signatures/${normalizePath(name)}`] = textEncode(body);
+        }
+    }
+    if (pkg.anchors) {
+        pkg.anchors.forEach((anchor, i) => {
+            const path = `signatures/anchors/${i}-${anchor.kind}.json`;
+            if (!files[path])
+                files[path] = textEncode(anchor);
+        });
+    }
+    return files;
+}
+/**
+ * Content index covers every file except `skill.json` and `signatures/**`.
+ * `package_digest` is the digest of that index (RFC8785 JCS + SHA-256).
+ */
+export function finalizeManifest(base, files) {
+    const content = Object.keys(files)
+        .filter((p) => p !== "skill.json" && !p.startsWith("signatures/"))
+        .sort()
+        .map((path) => ({
+        path,
+        digest: sha256Digest(files[path]),
+        bytes: files[path].byteLength,
+    }));
+    return {
+        ...base,
+        mint: base.mint ?? { mint_status: "draft" },
+        content,
+        package_digest: packageDigestFromContent(content),
+    };
+}
+export function packSkill(pkg, _opts = {}) {
+    const files = buildFileMap(pkg);
+    const manifest = finalizeManifest(pkg.manifest, files);
+    files["skill.json"] = textEncode(manifest);
+    assertSafePaths(Object.keys(files));
+    if (Object.keys(files).length > MAX_ENTRIES) {
+        throw new Error(`Too many entries: ${Object.keys(files).length}`);
+    }
+    let total = 0;
+    for (const bytes of Object.values(files))
+        total += bytes.byteLength;
+    if (total > MAX_UNCOMPRESSED_BYTES) {
+        throw new Error(`Package too large: ${total} bytes`);
+    }
+    return zipSync(files, { level: 6 });
+}
+export function unpackSkill(archive) {
+    if (archive.byteLength > MAX_UNCOMPRESSED_BYTES * 2) {
+        throw new Error("Archive too large to unpack");
+    }
+    const unzipped = unzipSync(archive);
+    const paths = Object.keys(unzipped);
+    if (paths.length > MAX_ENTRIES)
+        throw new Error("Too many zip entries");
+    assertSafePaths(paths);
+    let uncompressed = 0;
+    for (const data of Object.values(unzipped)) {
+        uncompressed += data.byteLength;
+        if (uncompressed > MAX_UNCOMPRESSED_BYTES) {
+            throw new Error("Uncompressed size exceeds limit");
+        }
+        const ratio = archive.byteLength > 0 ? uncompressed / archive.byteLength : 0;
+        if (ratio > MAX_COMPRESSION_RATIO && uncompressed > 1_000_000) {
+            throw new Error("Suspicious compression ratio");
+        }
+    }
+    const skillJson = unzipped["skill.json"];
+    if (!skillJson)
+        throw new Error("Missing skill.json");
+    const workflowJson = unzipped["workflow.json"];
+    if (!workflowJson)
+        throw new Error("Missing workflow.json");
+    const manifest = JSON.parse(strFromU8(skillJson));
+    const workflow = JSON.parse(strFromU8(workflowJson));
+    const knowledge = [];
+    for (const [path, data] of Object.entries(unzipped)) {
+        if (path.startsWith("knowledge/") && path.endsWith(".json")) {
+            knowledge.push(JSON.parse(strFromU8(data)));
+        }
+    }
+    let compilation_report;
+    if (unzipped["provenance/compilation_report.json"]) {
+        compilation_report = JSON.parse(strFromU8(unzipped["provenance/compilation_report.json"]));
+    }
+    const prompts = {};
+    const resources = {};
+    const artifacts = {};
+    const signatures = {};
+    for (const [path, data] of Object.entries(unzipped)) {
+        if (path.startsWith("prompts/"))
+            prompts[path.slice("prompts/".length)] = strFromU8(data);
+        if (path.startsWith("resources/"))
+            resources[path.slice("resources/".length)] = data;
+        if (path.startsWith("artifacts/"))
+            artifacts[path.slice("artifacts/".length)] = data;
+        if (path.startsWith("signatures/") && path.endsWith(".json")) {
+            signatures[path.slice("signatures/".length)] = JSON.parse(strFromU8(data));
+        }
+    }
+    const creation = signatures["creation.dsse.json"];
+    const attestation = creation?.attestation ??
+        signatures["creation.attestation.json"];
+    const anchorsFromSig = Object.entries(signatures)
+        .filter(([k]) => k.startsWith("anchors/"))
+        .map(([, v]) => v);
+    const raw = {
+        manifest,
+        workflow,
+        knowledge,
+        prompts,
+        artifacts,
+        resources,
+        provenance: {
+            recipe: unzipped["provenance/recipe.json"]
+                ? JSON.parse(strFromU8(unzipped["provenance/recipe.json"]))
+                : undefined,
+            source: unzipped["provenance/source.json"]
+                ? JSON.parse(strFromU8(unzipped["provenance/source.json"]))
+                : undefined,
+            journey: unzipped["provenance/journey.json"]
+                ? JSON.parse(strFromU8(unzipped["provenance/journey.json"]))
+                : undefined,
+            generation_usage: unzipped["provenance/generation_usage.json"]
+                ? JSON.parse(strFromU8(unzipped["provenance/generation_usage.json"]))
+                : undefined,
+            proof: unzipped["provenance/proof.json"]
+                ? JSON.parse(strFromU8(unzipped["provenance/proof.json"]))
+                : undefined,
+            compilation_report,
+        },
+        signatures,
+        attestation,
+        anchors: manifest.anchors?.length ? manifest.anchors : anchorsFromSig,
+    };
+    return { files: unzipped, manifest, workflow, knowledge, compilation_report, raw };
+}

package/dist/paths.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizePath(path: string): string;
+export declare function assertSafePaths(paths: string[]): void;
+export declare const MAX_ENTRIES = 10000;
+export declare const MAX_UNCOMPRESSED_BYTES: number;
+export declare const MAX_COMPRESSION_RATIO = 100;

package/dist/paths.js

@@ -0,0 +1,22 @@
+const UNSAFE = /(^\/)|(\.\.)|(^$)/;
+export function normalizePath(path) {
+    const nfc = path.normalize("NFC").replace(/\\/g, "/");
+    if (nfc.includes("\0"))
+        throw new Error(`Null byte in path: ${path}`);
+    if (UNSAFE.test(nfc) || nfc.split("/").some((s) => s === "" || s === "." || s === "..")) {
+        throw new Error(`Unsafe path: ${path}`);
+    }
+    return nfc;
+}
+export function assertSafePaths(paths) {
+    const seen = new Set();
+    for (const p of paths) {
+        const n = normalizePath(p);
+        if (seen.has(n))
+            throw new Error(`Duplicate path: ${n}`);
+        seen.add(n);
+    }
+}
+export const MAX_ENTRIES = 10_000;
+export const MAX_UNCOMPRESSED_BYTES = 64 * 1024 * 1024;
+export const MAX_COMPRESSION_RATIO = 100;

package/dist/validate.d.ts

@@ -0,0 +1,32 @@
+import type { SkillManifest, Workflow } from "@dot-skill/protocol";
+export interface ValidationIssue {
+    severity: "error" | "warning";
+    code: string;
+    message: string;
+    path?: string;
+}
+export interface ValidationResult {
+    ok: boolean;
+    issues: ValidationIssue[];
+    manifest?: SkillManifest;
+    workflow?: Workflow;
+}
+export declare function validateManifestShape(manifest: SkillManifest): ValidationIssue[];
+export declare function validateWorkflowShape(workflow: Workflow, entrypoint: string): ValidationIssue[];
+export declare function validatePackageBytes(archive: Uint8Array): ValidationResult;
+export declare function inspectSkill(archive: Uint8Array): {
+    ok: boolean;
+    summary: {
+        id: string;
+        version: string;
+        title: string;
+        description: string;
+        inputs: string[];
+        permissions: string[];
+        capabilities: string[];
+        package_digest: string;
+        mint_status?: string;
+        needs_human_review?: boolean;
+    };
+    issues: ValidationIssue[];
+};

package/dist/validate.js

@@ -0,0 +1,215 @@
+import { CONTAINER_VERSION, PROTOCOL_VERSION, WORKFLOW_DIALECT_VERSION, } from "@dot-skill/protocol";
+import { packageDigestFromContent, sha256Digest } from "./hash.js";
+import { unpackSkill } from "./pack.js";
+export function validateManifestShape(manifest) {
+    const issues = [];
+    if (manifest.kind !== "dot-skill") {
+        issues.push({ severity: "error", code: "kind", message: "kind must be dot-skill" });
+    }
+    if (!manifest.id)
+        issues.push({ severity: "error", code: "id", message: "id required" });
+    if (!manifest.version)
+        issues.push({ severity: "error", code: "version", message: "version required" });
+    if (!manifest.title)
+        issues.push({ severity: "error", code: "title", message: "title required" });
+    if (!manifest.description)
+        issues.push({
+            severity: "error",
+            code: "description",
+            message: "description required",
+        });
+    if (!manifest.entrypoint)
+        issues.push({
+            severity: "error",
+            code: "entrypoint",
+            message: "entrypoint required",
+        });
+    if (manifest.container_version !== CONTAINER_VERSION) {
+        issues.push({
+            severity: "warning",
+            code: "container_version",
+            message: `Unexpected container_version ${manifest.container_version}`,
+        });
+    }
+    if (manifest.protocol_version !== PROTOCOL_VERSION) {
+        issues.push({
+            severity: "error",
+            code: "protocol_version",
+            message: `Unsupported protocol_version ${manifest.protocol_version}; expected ${PROTOCOL_VERSION}`,
+        });
+    }
+    if (manifest.mint?.mint_status === "minted") {
+        if (manifest.compile_profile !== "release") {
+            issues.push({
+                severity: "error",
+                code: "minted_profile",
+                message: "Minted packages must use compile_profile=release",
+            });
+        }
+        if (!manifest.completeness?.complete) {
+            issues.push({
+                severity: "error",
+                code: "minted_incomplete",
+                message: "Minted packages require a complete release report",
+            });
+        }
+    }
+    for (const input of manifest.inputs ?? []) {
+        if (input.sensitivity === "secret" && input.examples?.length) {
+            issues.push({
+                severity: "error",
+                code: "secret_examples",
+                message: `Input ${input.name} is secret but includes examples`,
+                path: input.name,
+            });
+        }
+    }
+    return issues;
+}
+export function validateWorkflowShape(workflow, entrypoint) {
+    const issues = [];
+    if (workflow.kind !== "workflow") {
+        issues.push({ severity: "error", code: "workflow_kind", message: "kind must be workflow" });
+    }
+    if (workflow.dialect_version !== WORKFLOW_DIALECT_VERSION) {
+        issues.push({
+            severity: "warning",
+            code: "dialect",
+            message: `Unexpected dialect_version ${workflow.dialect_version}`,
+        });
+    }
+    const ids = new Set(workflow.steps.map((s) => s.id));
+    if (!ids.has(entrypoint)) {
+        issues.push({
+            severity: "error",
+            code: "entrypoint_missing",
+            message: `Entrypoint ${entrypoint} not in steps`,
+        });
+    }
+    for (const step of workflow.steps) {
+        if (!step.id || !step.kind) {
+            issues.push({
+                severity: "error",
+                code: "step",
+                message: "Each step needs id and kind",
+            });
+        }
+    }
+    return issues;
+}
+export function validatePackageBytes(archive) {
+    const issues = [];
+    let unpacked;
+    try {
+        unpacked = unpackSkill(archive);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            issues: [
+                {
+                    severity: "error",
+                    code: "unpack",
+                    message: e instanceof Error ? e.message : String(e),
+                },
+            ],
+        };
+    }
+    issues.push(...validateManifestShape(unpacked.manifest));
+    issues.push(...validateWorkflowShape(unpacked.workflow, unpacked.manifest.entrypoint));
+    const computed = [];
+    for (const [path, data] of Object.entries(unpacked.files)) {
+        if (path === "skill.json" || path.startsWith("signatures/"))
+            continue;
+        const digest = sha256Digest(data);
+        computed.push({ path, digest });
+        const listed = unpacked.manifest.content.find((c) => c.path === path);
+        if (!listed) {
+            issues.push({
+                severity: "error",
+                code: "missing_content_entry",
+                message: `File ${path} not listed in manifest.content`,
+                path,
+            });
+        }
+        else if (listed.digest !== digest) {
+            issues.push({
+                severity: "error",
+                code: "digest_mismatch",
+                message: `Digest mismatch for ${path}`,
+                path,
+            });
+        }
+    }
+    for (const entry of unpacked.manifest.content) {
+        if (!unpacked.files[entry.path]) {
+            issues.push({
+                severity: "error",
+                code: "missing_file",
+                message: `Manifest lists missing file ${entry.path}`,
+                path: entry.path,
+            });
+        }
+    }
+    const expectedPkg = packageDigestFromContent(computed);
+    if (unpacked.manifest.package_digest !== expectedPkg) {
+        issues.push({
+            severity: "error",
+            code: "package_digest",
+            message: "package_digest does not match content index",
+        });
+    }
+    if (unpacked.manifest.policy.require_signatures) {
+        const sigs = Object.keys(unpacked.files).filter((p) => p.startsWith("signatures/"));
+        if (sigs.length === 0) {
+            issues.push({
+                severity: "error",
+                code: "signatures_required",
+                message: "Policy requires signatures but none present",
+            });
+        }
+    }
+    const ok = !issues.some((i) => i.severity === "error");
+    return {
+        ok,
+        issues,
+        manifest: unpacked.manifest,
+        workflow: unpacked.workflow,
+    };
+}
+export function inspectSkill(archive) {
+    const result = validatePackageBytes(archive);
+    if (!result.manifest) {
+        return {
+            ok: false,
+            summary: {
+                id: "",
+                version: "",
+                title: "",
+                description: "",
+                inputs: [],
+                permissions: [],
+                capabilities: [],
+                package_digest: "",
+            },
+            issues: result.issues,
+        };
+    }
+    const m = result.manifest;
+    return {
+        ok: result.ok,
+        summary: {
+            id: m.id,
+            version: m.version,
+            title: m.title,
+            description: m.description,
+            inputs: m.inputs.filter((i) => i.required).map((i) => i.name),
+            permissions: m.permissions.map((p) => p.side_effect_class),
+            capabilities: m.capabilities.map((c) => c.name),
+            package_digest: m.package_digest,
+            mint_status: m.mint?.mint_status ?? "draft",
+            needs_human_review: m.needs_human_review,
+        },
+        issues: result.issues,
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dot-skill/core",
+  "version": "0.4.1",
+  "description": "Open .skill Protocol — pack, validate, compile, mint",
+  "license": "MIT",
+  "author": {
+    "name": "Bharat Dudeja",
+    "url": "https://github.com/bharatdudeja13-cmd"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dot-skill/dot-skill.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "prepack": "npm run build",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@dot-skill/protocol": "^0.4.1",
+    "fflate": "^0.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^5.4.5"
+  }
+}