@dot-skill/core 0.4.1

package/dist/hash.js

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+/** RFC 8785-inspired JSON Canonicalization for I-JSON-compatible objects. */
+export function canonicalize(value) {
+    return serialize(value);
+}
+function serialize(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("JCS forbids non-finite numbers");
+        }
+        return JSON.stringify(value);
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => serialize(v)).join(",")}]`;
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        const parts = [];
+        for (const key of keys) {
+            const v = obj[key];
+            if (v === undefined)
+                continue;
+            parts.push(`${JSON.stringify(key)}:${serialize(v)}`);
+        }
+        return `{${parts.join(",")}}`;
+    }
+    throw new Error(`Unsupported JSON value type: ${typeof value}`);
+}
+export function sha256Hex(data) {
+    const hash = createHash("sha256");
+    hash.update(typeof data === "string" ? Buffer.from(data, "utf8") : data);
+    return hash.digest("hex");
+}
+export function sha256Digest(data) {
+    return `sha256:${sha256Hex(data)}`;
+}
+export function packageDigestFromContent(content) {
+    const paths = {};
+    for (const entry of [...content].sort((a, b) => a.path.localeCompare(b.path))) {
+        if (entry.path.startsWith("signatures/"))
+            continue;
+        paths[entry.path] = entry.digest;
+    }
+    return sha256Digest(canonicalize({ paths }));
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/** @dot-skill/core — pack, unpack, validate, mint, compile .skill packages. */
+export { canonicalize, sha256Hex, sha256Digest, packageDigestFromContent } from "./hash.js";
+export { normalizePath, assertSafePaths, MAX_ENTRIES, MAX_UNCOMPRESSED_BYTES, MAX_COMPRESSION_RATIO, } from "./paths.js";
+export { buildFileMap, finalizeManifest, packSkill, unpackSkill, } from "./pack.js";
+export type { PackOptions, UnpackResult } from "./pack.js";
+export { validateManifestShape, validateWorkflowShape, validatePackageBytes, inspectSkill, } from "./validate.js";
+export type { ValidationIssue, ValidationResult } from "./validate.js";
+export { migrateLegacySkill, toSkillMdAdapter } from "./migrate.js";
+export { mintSkillPackage, addPermanenceAnchor, verifyMintTrust, } from "./mint.js";
+export type { MintOptions } from "./mint.js";
+export { compileSkillSource, compileRecipeToSkill, approveCompilation, assessCompleteness, redactSecrets, CompileRefusalError, } from "./compile.js";
+export type { CompileOptions, CompileResult } from "./compile.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+/** @dot-skill/core — pack, unpack, validate, mint, compile .skill packages. */
+export { canonicalize, sha256Hex, sha256Digest, packageDigestFromContent } from "./hash.js";
+export { normalizePath, assertSafePaths, MAX_ENTRIES, MAX_UNCOMPRESSED_BYTES, MAX_COMPRESSION_RATIO, } from "./paths.js";
+export { buildFileMap, finalizeManifest, packSkill, unpackSkill, } from "./pack.js";
+export { validateManifestShape, validateWorkflowShape, validatePackageBytes, inspectSkill, } from "./validate.js";
+export { migrateLegacySkill, toSkillMdAdapter } from "./migrate.js";
+export { mintSkillPackage, addPermanenceAnchor, verifyMintTrust, } from "./mint.js";
+export { compileSkillSource, compileRecipeToSkill, approveCompilation, assessCompleteness, redactSecrets, CompileRefusalError, } from "./compile.js";

package/dist/migrate.d.ts

@@ -0,0 +1,8 @@
+import type { Skill } from "@dot-skill/protocol";
+import { type SkillPackageFiles } from "@dot-skill/protocol";
+/** Convert legacy flat skill JSON into a draft `.skill` package (bytes). */
+export declare function migrateLegacySkill(legacy: Skill): {
+    packageBytes: Uint8Array;
+    files: SkillPackageFiles;
+};
+export declare function toSkillMdAdapter(pkg: SkillPackageFiles): string;

package/dist/migrate.js

@@ -0,0 +1,116 @@
+import { DEFAULT_SKILL_POLICY, CONTAINER_VERSION, PROTOCOL_VERSION, WORKFLOW_DIALECT_VERSION, } from "@dot-skill/protocol";
+import { packSkill } from "./pack.js";
+import { randomUUID } from "node:crypto";
+/** Convert legacy flat skill JSON into a draft `.skill` package (bytes). */
+export function migrateLegacySkill(legacy) {
+    const id = legacy.id || `skl_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+    const knowledgeId = "k_legacy_body";
+    const files = {
+        manifest: {
+            kind: "dot-skill",
+            id,
+            version: legacy.version || "0.1.0",
+            title: legacy.title || "Migrated skill",
+            description: "Draft migrated from legacy flat skill format. Needs human review before release.",
+            container_version: CONTAINER_VERSION,
+            protocol_version: PROTOCOL_VERSION,
+            entrypoint: "s_instruct",
+            inputs: [],
+            outputs: [
+                {
+                    name: "result",
+                    schema: { type: "string" },
+                    required: false,
+                    description: "Unstructured result from legacy instruct skill",
+                },
+            ],
+            capabilities: [],
+            permissions: [],
+            policy: { ...DEFAULT_SKILL_POLICY },
+            content: [],
+            package_digest: "sha256:" + "0".repeat(64),
+            provenance_mode: "proof_only",
+            legacy: true,
+            needs_human_review: true,
+        },
+        workflow: {
+            kind: "workflow",
+            dialect_version: WORKFLOW_DIALECT_VERSION,
+            entrypoint: "s_instruct",
+            steps: [
+                {
+                    id: "s_instruct",
+                    kind: "instruct",
+                    title: "Legacy body",
+                    text: legacy.body,
+                    next: "s_emit",
+                    provenance: [{ kind: "legacy_skill", id: legacy.id }],
+                },
+                {
+                    id: "s_emit",
+                    kind: "emit",
+                    output: "result",
+                    from: "s_instruct",
+                },
+            ],
+        },
+        knowledge: [
+            {
+                kind: "knowledge",
+                id: knowledgeId,
+                type: "reference",
+                title: "Legacy skill body",
+                body: legacy.body,
+                fidelity: "exact",
+                provenance: [{ kind: "legacy_skill", id: legacy.id }],
+            },
+        ],
+        provenance: {
+            proof: {
+                sources: legacy.sources,
+                exported_at: legacy.exported_at,
+                legacy_protocol_version: legacy.source_protocol_version,
+            },
+        },
+    };
+    const packageBytes = packSkill(files);
+    return { packageBytes, files };
+}
+export function toSkillMdAdapter(pkg) {
+    const m = pkg.manifest;
+    const lines = [
+        "---",
+        `name: ${m.id.replace(/[^a-z0-9-]/gi, "-").toLowerCase().slice(0, 64)}`,
+        `description: ${m.description.slice(0, 1024)}`,
+        "metadata:",
+        "  dot_skill_authoritative: true",
+        `  skill_id: ${m.id}`,
+        `  skill_version: ${m.version}`,
+        `  package_digest: ${m.package_digest}`,
+        "---",
+        "",
+        `# ${m.title}`,
+        "",
+        m.intent ?? m.description,
+        "",
+        "## Inputs",
+        "",
+    ];
+    for (const input of m.inputs) {
+        lines.push(`- **${input.name}** (${input.source}, ${input.required ? "required" : "optional"}): ${input.description}`);
+    }
+    if (m.inputs.length === 0)
+        lines.push("- (none)");
+    lines.push("", "## Workflow", "");
+    for (const step of pkg.workflow.steps) {
+        lines.push(`### ${step.id} (\`${step.kind}\`)`);
+        if ("text" in step && step.text)
+            lines.push(step.text, "");
+        if ("template" in step && step.template)
+            lines.push(step.template, "");
+        if ("prompt" in step && step.prompt)
+            lines.push(step.prompt, "");
+    }
+    lines.push("", "> This SKILL.md is a **lossy adapter**. The authoritative artifact is the `.skill` package.");
+    return lines.join("\n");
+}

package/dist/mint.d.ts

@@ -0,0 +1,37 @@
+import type { CreationAttestation, PermanenceAnchor, SkillPackageFiles, TrustProfile } from "@dot-skill/protocol";
+import { type ValidationIssue } from "./validate.js";
+export interface MintOptions {
+    host: string;
+    provider?: string;
+    agent_runtime?: string;
+    agent_version?: string;
+    key_id?: string;
+    model?: string;
+    deployment?: "local" | "hosted" | "hybrid" | "unknown";
+    endpoint?: string;
+    actors?: string[];
+    /**
+     * HMAC-style digest seal for development/testing only.
+     * REFERENCE IMPLEMENTATION ONLY — not production PKI.
+     * Default key is `dot-skill-dev-mint-key` and must be replaced in production.
+     */
+    issuer_secret?: string;
+    policy_profile?: TrustProfile;
+}
+/**
+ * Seal a draft package as minted.
+ * Content under signatures/ may change; package_digest (content) stays fixed after finalize.
+ */
+export declare function mintSkillPackage(pkg: SkillPackageFiles, opts: MintOptions): {
+    files: SkillPackageFiles;
+    packageBytes: Uint8Array;
+    attestation: CreationAttestation;
+};
+export declare function addPermanenceAnchor(archive: Uint8Array, anchor: Omit<PermanenceAnchor, "package_digest"> & {
+    package_digest?: string;
+}): Uint8Array;
+export declare function verifyMintTrust(archive: Uint8Array, profile?: TrustProfile, issuer_secret?: string): {
+    ok: boolean;
+    issues: ValidationIssue[];
+    attestation?: CreationAttestation;
+};

package/dist/mint.js

@@ -0,0 +1,250 @@
+import { isValidAgentHost } from "@dot-skill/protocol";
+import { canonicalize, sha256Digest } from "./hash.js";
+import { packSkill, unpackSkill } from "./pack.js";
+import { validatePackageBytes } from "./validate.js";
+/**
+ * Seal a draft package as minted.
+ * Content under signatures/ may change; package_digest (content) stays fixed after finalize.
+ */
+export function mintSkillPackage(pkg, opts) {
+    if (!isValidAgentHost(opts.host)) {
+        throw new Error(`Mint host "${opts.host}" is not a valid AI agent host. Use cursor, ollama, lmstudio, llama-cpp, custom-agent, …`);
+    }
+    if (pkg.manifest.needs_human_review) {
+        throw new Error("Cannot mint while needs_human_review is true — approve inputs/permissions first");
+    }
+    if (pkg.manifest.compile_profile !== "release") {
+        throw new Error("Cannot mint: compile_profile must be release. Complete the journey and release compile first.");
+    }
+    if (!pkg.manifest.completeness?.complete) {
+        throw new Error(`Cannot mint incomplete skill. Missing: ${pkg.manifest.completeness?.missing.join(", ") || "completeness report"}`);
+    }
+    const report = pkg.provenance?.compilation_report;
+    if (!report ||
+        report.profile !== "release" ||
+        !report.completeness.complete ||
+        !report.approved ||
+        report.pending_approvals.length > 0) {
+        throw new Error("Cannot mint: approved release compilation report required");
+    }
+    const pending = pkg.manifest.inputs.filter((i) => i.required && i.approved !== true);
+    if (pending.length) {
+        throw new Error(`Cannot mint with unapproved inputs: ${pending.map((p) => p.name).join(", ")}`);
+    }
+    const draftBytes = packSkill({
+        ...pkg,
+        signatures: undefined,
+        attestation: undefined,
+        anchors: pkg.anchors ?? pkg.manifest.anchors,
+    });
+    const unpacked = unpackSkill(draftBytes);
+    const package_digest = unpacked.manifest.package_digest;
+    const attestation = {
+        kind: "creation_attestation",
+        package_digest,
+        skill_id: pkg.manifest.id,
+        skill_version: pkg.manifest.version,
+        minted_at: new Date().toISOString(),
+        agent: {
+            runtime: opts.agent_runtime ?? "@dot-skill/runtime",
+            version: opts.agent_version ?? "0.4.0",
+            key_id: opts.key_id ?? "dot-skill-dev-mint-key",
+        },
+        host: opts.host,
+        provider: opts.provider,
+        model: opts.model,
+        deployment: opts.deployment,
+        endpoint: opts.endpoint,
+        journey: {
+            source_id: pkg.provenance?.compilation_report?.source_id,
+            source_hash: pkg.provenance?.proof &&
+                typeof pkg.provenance.proof === "object" &&
+                pkg.provenance.proof !== null &&
+                "source_hash" in pkg.provenance.proof
+                ? String(pkg.provenance.proof.source_hash)
+                : undefined,
+            recipe_id: pkg.provenance?.compilation_report?.recipe_id,
+            recipe_hash: pkg.provenance?.recipe &&
+                typeof pkg.provenance.recipe === "object" &&
+                pkg.provenance.recipe !== null &&
+                "hash" in pkg.provenance.recipe
+                ? String(pkg.provenance.recipe.hash)
+                : undefined,
+            proof_digest: pkg.provenance?.proof
+                ? sha256Digest(canonicalize(pkg.provenance.proof))
+                : undefined,
+            summary: pkg.provenance?.journey?.summary,
+        },
+        generation_usage: pkg.provenance?.generation_usage,
+        human_approvals: {
+            inputs: pkg.manifest.inputs.filter((i) => i.approved === true).map((i) => i.name),
+            permissions: pkg.manifest.permissions
+                .filter((p) => p.requires_consent)
+                .map((p) => p.side_effect_class),
+            actors: opts.actors ?? ["human"],
+        },
+        policy_profile: opts.policy_profile ?? "minted",
+    };
+    const payload = canonicalize(attestation);
+    const payloadDigest = sha256Digest(payload);
+    /**
+     * REFERENCE IMPLEMENTATION ONLY.
+     * The default key "dot-skill-dev-mint-key" is a public constant for testing.
+     * Replace issuer_secret with a real private key in any production issuer.
+     */
+    const secret = opts.issuer_secret ?? "dot-skill-dev-mint-key";
+    const sig = sha256Digest(`${secret}:${payloadDigest}`);
+    const dsse = {
+        payloadType: "application/vnd.dot-skill.creation-attestation+json",
+        payload_digest: payloadDigest,
+        signatures: [{ keyid: attestation.agent.key_id, sig }],
+        attestation,
+    };
+    const minted = {
+        ...unpacked.raw,
+        manifest: {
+            ...unpacked.manifest,
+            mint: {
+                mint_status: "minted",
+                minted_at: attestation.minted_at,
+                mint_issuer: attestation.agent.runtime,
+                content_id: package_digest,
+            },
+            attestation_digest: payloadDigest,
+            policy: {
+                ...unpacked.manifest.policy,
+                require_signatures: true,
+                require_minted: true,
+                trust_profile: opts.policy_profile ?? "minted",
+            },
+        },
+        attestation,
+        signatures: {
+            "creation.dsse.json": dsse,
+        },
+        anchors: unpacked.raw.anchors ?? unpacked.manifest.anchors,
+    };
+    const packageBytes = packSkill(minted);
+    const verify = unpackSkill(packageBytes);
+    if (verify.manifest.package_digest !== package_digest) {
+        throw new Error(`Mint changed content digest (${verify.manifest.package_digest} != ${package_digest})`);
+    }
+    return { files: { ...minted, manifest: verify.manifest }, packageBytes, attestation };
+}
+export function addPermanenceAnchor(archive, anchor) {
+    const unpacked = unpackSkill(archive);
+    const package_digest = unpacked.manifest.package_digest;
+    const full = {
+        ...anchor,
+        package_digest: anchor.package_digest ?? package_digest,
+    };
+    if (full.package_digest !== package_digest) {
+        throw new Error("Anchor package_digest must match skill package_digest");
+    }
+    const anchors = [...(unpacked.manifest.anchors ?? []), full];
+    const files = {
+        ...unpacked.raw,
+        manifest: {
+            ...unpacked.manifest,
+            anchors,
+        },
+        anchors,
+        signatures: {
+            ...(unpacked.raw.signatures ?? {}),
+            [`anchors/${anchors.length}-${full.kind}.json`]: full,
+        },
+    };
+    return packSkill(files);
+}
+export function verifyMintTrust(archive, profile = "minted", issuer_secret) {
+    const base = validatePackageBytes(archive);
+    const issues = [...base.issues];
+    const unpacked = unpackSkill(archive);
+    const mintStatus = unpacked.manifest.mint?.mint_status ?? "draft";
+    const attestation = unpacked.raw.signatures?.["creation.dsse.json"]?.attestation
+        ?? unpacked.raw.attestation;
+    const envelope = unpacked.raw.signatures?.["creation.dsse.json"];
+    if (profile !== "open") {
+        if (mintStatus !== "minted") {
+            issues.push({
+                severity: "error",
+                code: "not_minted",
+                message: "Trust profile requires mint_status=minted",
+            });
+        }
+        if (!attestation) {
+            issues.push({
+                severity: "error",
+                code: "missing_attestation",
+                message: "Minted skills require CreationAttestation",
+            });
+        }
+        else if (!envelope?.signatures?.[0]?.sig) {
+            issues.push({
+                severity: "error",
+                code: "missing_attestation_signature",
+                message: "Minted trust profile requires a signed DSSE attestation envelope",
+            });
+        }
+        else if (attestation.package_digest !== unpacked.manifest.package_digest) {
+            issues.push({
+                severity: "error",
+                code: "attestation_digest_mismatch",
+                message: "Attestation package_digest does not match manifest",
+            });
+        }
+        else {
+            const payloadDigest = sha256Digest(canonicalize(attestation));
+            if (envelope.payload_digest !== payloadDigest) {
+                issues.push({
+                    severity: "error",
+                    code: "attestation_payload_digest",
+                    message: "DSSE payload_digest does not match CreationAttestation",
+                });
+            }
+            // REFERENCE IMPLEMENTATION ONLY — replace with real PKI in production.
+            const secret = issuer_secret ?? "dot-skill-dev-mint-key";
+            const expected = sha256Digest(`${secret}:${payloadDigest}`);
+            const sig = envelope?.signatures?.[0]?.sig;
+            if (sig !== expected) {
+                issues.push({
+                    severity: "error",
+                    code: "attestation_sig_invalid",
+                    message: "CreationAttestation signature failed verification",
+                });
+            }
+            if (!issuer_secret && attestation.agent.key_id === "dot-skill-dev-mint-key") {
+                issues.push({
+                    severity: "warning",
+                    code: "development_attestation",
+                    message: "Attestation uses the public development key; provenance is self-asserted, not trusted identity",
+                });
+            }
+        }
+    }
+    if (profile === "anchored") {
+        const anchors = unpacked.manifest.anchors ?? [];
+        if (!anchors.length) {
+            issues.push({
+                severity: "error",
+                code: "anchor_required",
+                message: "Trust profile requires at least one PermanenceAnchor",
+            });
+        }
+    }
+    if (profile.startsWith("issuer:")) {
+        const want = profile.slice("issuer:".length);
+        if (attestation?.agent.runtime !== want && attestation?.agent.key_id !== want) {
+            issues.push({
+                severity: "error",
+                code: "issuer_mismatch",
+                message: `Attestation issuer does not match ${profile}`,
+            });
+        }
+    }
+    return {
+        ok: !issues.some((i) => i.severity === "error"),
+        issues,
+        attestation,
+    };
+}

package/dist/pack.d.ts

@@ -0,0 +1,20 @@
+import type { KnowledgeItem, SkillManifest, SkillPackageFiles, Workflow, CompilationReport } from "@dot-skill/protocol";
+export interface PackOptions {
+    recomputeDigests?: boolean;
+}
+export declare function buildFileMap(pkg: SkillPackageFiles): Record<string, Uint8Array>;
+/**
+ * Content index covers every file except `skill.json` and `signatures/**`.
+ * `package_digest` is the digest of that index (RFC8785 JCS + SHA-256).
+ */
+export declare function finalizeManifest(base: Omit<SkillManifest, "content" | "package_digest"> & Partial<Pick<SkillManifest, "content" | "package_digest">>, files: Record<string, Uint8Array>): SkillManifest;
+export declare function packSkill(pkg: SkillPackageFiles, _opts?: PackOptions): Uint8Array;
+export interface UnpackResult {
+    files: Record<string, Uint8Array>;
+    manifest: SkillManifest;
+    workflow: Workflow;
+    knowledge: KnowledgeItem[];
+    compilation_report?: CompilationReport;
+    raw: SkillPackageFiles;
+}
+export declare function unpackSkill(archive: Uint8Array): UnpackResult;