@skillerr/core 0.6.0

package/dist/hash.d.ts

@@ -0,0 +1,18 @@
+import type { SealedManifestClaims, SkillManifest } from "@skillerr/protocol";
+/** RFC 8785-inspired JSON Canonicalization for I-JSON-compatible objects. */
+export declare function canonicalize(value: unknown): string;
+export declare function sha256Hex(data: string | Uint8Array): string;
+export declare function sha256Digest(data: string | Uint8Array): string;
+export declare function packageDigestFromContent(content: Array<{
+    path: string;
+    digest: string;
+}>): string;
+/** Public development HMAC key — forgeable; never production trust. */
+export declare const PUBLIC_DEV_MINT_KEY = "dot-skill-dev-mint-key";
+export declare const PUBLIC_DEV_MINT_KEY_ID = "dot-skill-dev-mint-key";
+/**
+ * Build the claim set covered by the creation seal.
+ * Binds identity, intent, permissions, policy, capabilities, inputs, and content digests.
+ */
+export declare function buildSealedManifestClaims(manifest: SkillManifest): SealedManifestClaims;
+export declare function sealedManifestDigest(manifest: SkillManifest): string;

package/dist/hash.js

@@ -0,0 +1,122 @@
+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 }));
+}
+/** Public development HMAC key — forgeable; never production trust. */
+export const PUBLIC_DEV_MINT_KEY = "dot-skill-dev-mint-key";
+export const PUBLIC_DEV_MINT_KEY_ID = "dot-skill-dev-mint-key";
+/**
+ * Build the claim set covered by the creation seal.
+ * Binds identity, intent, permissions, policy, capabilities, inputs, and content digests.
+ */
+export function buildSealedManifestClaims(manifest) {
+    const claims = {
+        id: manifest.id,
+        version: manifest.version,
+        title: manifest.title,
+        intent: manifest.intent,
+        description: manifest.description,
+        package_digest: manifest.package_digest,
+        permissions: [...manifest.permissions]
+            .map((p) => ({
+            side_effect_class: p.side_effect_class,
+            description: p.description,
+            paths: p.paths,
+            hosts: p.hosts,
+            requires_consent: p.requires_consent,
+        }))
+            .sort((a, b) => `${a.side_effect_class}:${a.description}`.localeCompare(`${b.side_effect_class}:${b.description}`)),
+        policy: {
+            require_signatures: manifest.policy.require_signatures,
+            require_minted: manifest.policy.require_minted,
+            require_anchor: manifest.policy.require_anchor,
+            allow_network: manifest.policy.allow_network,
+            filesystem_roots: manifest.policy.filesystem_roots
+                ? [...manifest.policy.filesystem_roots].sort()
+                : undefined,
+            consent_for: [...manifest.policy.consent_for].sort(),
+            trust_profile: manifest.policy.trust_profile,
+            max_tool_calls: manifest.policy.max_tool_calls,
+            max_runtime_ms: manifest.policy.max_runtime_ms,
+            fail_on_unsupported_step: manifest.policy.fail_on_unsupported_step,
+        },
+        capabilities: [...manifest.capabilities]
+            .map((c) => ({
+            name: c.name,
+            side_effect_class: c.side_effect_class,
+            required: c.required,
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name)),
+        inputs: [...manifest.inputs]
+            .map((i) => ({
+            name: i.name,
+            sensitivity: i.sensitivity,
+            required: i.required,
+            source: i.source,
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name)),
+        content: [...manifest.content]
+            .map((c) => ({ path: c.path, digest: c.digest, media_type: c.media_type, bytes: c.bytes }))
+            .sort((a, b) => a.path.localeCompare(b.path)),
+    };
+    if (manifest.contract) {
+        claims.contract = {
+            title: manifest.contract.title,
+            intent: manifest.contract.intent,
+            skill_kind: manifest.contract.skill_kind,
+            sensitivity: manifest.contract.sensitivity,
+        };
+    }
+    return claims;
+}
+export function sealedManifestDigest(manifest) {
+    return sha256Digest(canonicalize(buildSealedManifestClaims(manifest)));
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/** @skillerr/core — pack, unpack, validate, mint, compile .skill packages. */
+export { canonicalize, sha256Hex, sha256Digest, packageDigestFromContent, buildSealedManifestClaims, sealedManifestDigest, PUBLIC_DEV_MINT_KEY, PUBLIC_DEV_MINT_KEY_ID, } 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, inspectTrustView, } from "./mint.js";
+export type { MintOptions, VerifyMintTrustOptions } 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 @@
+/** @skillerr/core — pack, unpack, validate, mint, compile .skill packages. */
+export { canonicalize, sha256Hex, sha256Digest, packageDigestFromContent, buildSealedManifestClaims, sealedManifestDigest, PUBLIC_DEV_MINT_KEY, PUBLIC_DEV_MINT_KEY_ID, } 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, inspectTrustView, } 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 "@skillerr/protocol";
+import { type SkillPackageFiles } from "@skillerr/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 "@skillerr/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,73 @@
+import type { CreationAttestation, HostClaimBinding, PermanenceAnchor, SkillPackageFiles, TrustProfile, TrustState, TrustView } from "@skillerr/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.
+     * Omit / use the public constant only for local development — never production trust.
+     */
+    issuer_secret?: string;
+    policy_profile?: TrustProfile;
+    /**
+     * Evidence that mint was invoked from an agent runtime path (not a bare human shell
+     * that only exported SKILL_HOST). Markers are still locally spoofable; residual risk
+     * for local LLMs remains.
+     */
+    agent_runtime_evidence?: {
+        markers?: string[];
+        session_id?: string;
+    };
+    /**
+     * Only set when a non-public issuer key authenticates the host/model claim.
+     * Default is always self_reported.
+     */
+    host_claim_binding?: HostClaimBinding;
+    /** Env snapshot for marker detection (defaults to process.env). */
+    env?: Record<string, string | undefined>;
+}
+export interface VerifyMintTrustOptions {
+    issuer_secret?: string;
+    /**
+     * When true, public-dev HMAC may pass structural verification as trust_state=development.
+     * Production execute paths must leave this false (fail closed).
+     */
+    allow_development_issuer?: boolean;
+    /** Accept self_reported host binding as ok for the requested profile. Default false for minted+. */
+    allow_self_reported?: boolean;
+}
+/**
+ * Seal a draft package as minted.
+ * Content under signatures/ may change; package_digest (content) stays fixed after finalize.
+ *
+ * Trust rules:
+ * - Forbidden hosts (human/cli/shell/manual/…) refuse mint entirely.
+ * - Env-only SKILL_HOST without agent runtime markers still mints, but as self_reported
+ *   + public_dev_hmac — never production trust.
+ * - Seal binds sealed_manifest_digest (identity + policy + content claims).
+ */
+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_or_opts?: string | VerifyMintTrustOptions): {
+    ok: boolean;
+    issues: ValidationIssue[];
+    attestation?: CreationAttestation;
+    trust_state: TrustState;
+};
+/**
+ * TrustView from skill.json + signatures + digests only — no compile, no model body ingest.
+ */
+export declare function inspectTrustView(archive: Uint8Array): TrustView;