@dot-skill/runtime 0.4.3 → 0.5.0

package/README.md

@@ -0,0 +1,36 @@
+# `@dot-skill/runtime`
+
+Reference runtime for the [Open `.skill` Protocol](https://github.com/dot-skill/dot-skill).
+
+Load a `.skill` archive, verify integrity and trust profile, resolve inputs, and run in **inspect**, **dry_run**, or **execute** modes. Prefer inspect and dry-run before execute.
+
+## Install
+
+```bash
+npm i @dot-skill/runtime
+```
+
+## Lifecycle
+
+`LoadAndVerify` → `NegotiateCapabilities` → `ResolveInputs` → `Consent` → `Execute` → `Verify` → `EmitSkillRun`
+
+Modes: `inspect` · `explain` · `dry_run` · `execute` · `resume`
+
+Fails clearly when required capabilities or minted trust profiles are unmet. Does not silently degrade.
+
+## Trust
+
+- Digests and seals are visible without executing workflow steps.
+- Trust profiles: `open` | `minted` | `anchored` | `issuer:<id>`
+- Reference mint verification matches `@dot-skill/core` (dev HMAC ≠ production PKI)
+
+## Related
+
+- [`@dot-skill/core`](https://www.npmjs.com/package/@dot-skill/core) — pack / validate / mint
+- [`skillerr`](https://www.npmjs.com/package/skillerr) — `skill inspect` / `skill run`
+
+Docs: [RUNTIME.md](https://github.com/dot-skill/dot-skill/blob/main/docs/RUNTIME.md) · [SECURITY.md](https://github.com/dot-skill/dot-skill/blob/main/docs/SECURITY.md)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { CapabilityAdapterHint, CapabilityRequirement, InputSlot, RuntimeMode, SkillPackageFiles, SkillRun, TrustProfile } from "@dot-skill/protocol";
-import { inspectSkill, unpackSkill, validatePackageBytes } from "@dot-skill/core";
+import { inspectSkill, inspectTrustView, unpackSkill, validatePackageBytes } from "@dot-skill/core";
 export interface CapabilityAdapter {
     name: string;
     supports: (cap: CapabilityRequirement) => boolean;
@@ -16,7 +16,29 @@ export interface RuntimeHost {
         title: string;
         permissions: string[];
         steps: string[];
-    }) => Promise<boolean>;
+    }) => Promise<{
+        allowed: boolean;
+        actor: string;
+        at: string;
+    }>;
+    decide?: (decision: {
+        id: string;
+        prompt: string;
+        choices?: string[];
+    }) => Promise<{
+        decision: string;
+        actor: string;
+        at: string;
+    }>;
+    verifyAssertion?: (assertion: {
+        id: string;
+        assertion: string;
+        check: "runtime" | "capability" | "human" | "agent";
+        evidence?: string[];
+    }) => Promise<{
+        passed: boolean;
+        detail?: string;
+    }>;
     resolveSecret?: (ref: string) => Promise<string>;
     env?: Record<string, string>;
     adapters?: CapabilityAdapter[];
@@ -32,7 +54,21 @@ export interface RunOptions {
     trust_profile?: TrustProfile;
     /** Reference verifier only; production runtimes should use a real trust store. */
     issuer_secret?: string;
+    /**
+     * Explicit unsafe opt-in to execute unsigned / development / self_reported packages.
+     * Required for execute when TrustView is not verified_issuer.
+     */
+    allow_untrusted?: boolean;
+    /** Allow public-dev HMAC seals for local testing only. */
+    allow_development_issuer?: boolean;
 }
+/**
+ * Deny-by-default: refuse undeclared network / filesystem / secret adapter use.
+ * Fail closed when consent is required but missing.
+ */
+export declare function assertCapabilityAllowed(pkg: SkillPackageFiles, cap: CapabilityRequirement, args?: Record<string, unknown>): void;
+/** Resolve a secret ref only if the input slot declares secret sensitivity/source. */
+export declare function resolveDeclaredSecret(pkg: SkillPackageFiles, slotName: string, host: RuntimeHost): Promise<string>;
 export declare function explainPackage(pkg: SkillPackageFiles): {
     title: string;
     description: string;
@@ -47,4 +83,4 @@ export declare function explainPackage(pkg: SkillPackageFiles): {
 };
 export declare function runSkillPackage(pkg: SkillPackageFiles, host?: RuntimeHost, options?: RunOptions): Promise<SkillRun>;
 export declare function runSkillArchive(archive: Uint8Array, host?: RuntimeHost, options?: RunOptions): Promise<SkillRun>;
-export { inspectSkill, validatePackageBytes, unpackSkill, explainPackage as explain };
+export { inspectSkill, inspectTrustView, validatePackageBytes, unpackSkill, explainPackage as explain, };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { inspectSkill, unpackSkill, validatePackageBytes, verifyMintTrust, sha256Digest, } from "@dot-skill/core";
+import { inspectSkill, inspectTrustView, unpackSkill, validatePackageBytes, verifyMintTrust, sha256Digest, } from "@dot-skill/core";
 function loadRuntimeIdentity() {
     const metadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
     if (typeof metadata.name !== "string" || typeof metadata.version !== "string") {
@@ -9,6 +9,82 @@ function loadRuntimeIdentity() {
     return { name: metadata.name, version: metadata.version };
 }
 const { name: RUNTIME_NAME, version: RUNTIME_VERSION } = loadRuntimeIdentity();
+function permissionCovers(permissions, sideEffect) {
+    return permissions.find((p) => p.side_effect_class === sideEffect);
+}
+/**
+ * Deny-by-default: refuse undeclared network / filesystem / secret adapter use.
+ * Fail closed when consent is required but missing.
+ */
+export function assertCapabilityAllowed(pkg, cap, args = {}) {
+    const policy = pkg.manifest.policy;
+    const side = cap.side_effect_class;
+    if (side === "network") {
+        if (!policy.allow_network) {
+            throw new Error(`Denied: capability ${cap.name} requires network but policy.allow_network=false (deny-by-default)`);
+        }
+        const perm = permissionCovers(pkg.manifest.permissions, "network");
+        if (!perm) {
+            throw new Error(`Denied: capability ${cap.name} uses network but no network permission is declared`);
+        }
+        const hostArg = typeof args.host === "string"
+            ? args.host
+            : typeof args.url === "string"
+                ? args.url
+                : typeof args.endpoint === "string"
+                    ? args.endpoint
+                    : undefined;
+        if (perm.hosts?.length && hostArg) {
+            const ok = perm.hosts.some((h) => hostArg === h || hostArg.includes(h) || hostArg.startsWith(h));
+            if (!ok) {
+                throw new Error(`Denied: network host/url not in declared permission.hosts for ${cap.name}`);
+            }
+        }
+    }
+    if (side === "read" || side === "write" || side === "destructive") {
+        const perm = permissionCovers(pkg.manifest.permissions, side);
+        if (!perm && side !== "read") {
+            throw new Error(`Denied: capability ${cap.name} uses ${side} but no matching permission is declared`);
+        }
+        const pathArg = typeof args.path === "string"
+            ? args.path
+            : typeof args.file === "string"
+                ? args.file
+                : typeof args.root === "string"
+                    ? args.root
+                    : undefined;
+        const roots = policy.filesystem_roots;
+        if (pathArg && roots?.length) {
+            const ok = roots.some((root) => pathArg === root || pathArg.startsWith(root.endsWith("/") ? root : `${root}/`));
+            if (!ok) {
+                throw new Error(`Denied: path ${pathArg} outside policy.filesystem_roots for ${cap.name}`);
+            }
+        }
+        if (pathArg && perm?.paths?.length) {
+            const ok = perm.paths.some((p) => pathArg === p || pathArg.startsWith(p.endsWith("/") ? p : `${p}/`));
+            if (!ok) {
+                throw new Error(`Denied: path ${pathArg} not in declared permission.paths for ${cap.name}`);
+            }
+        }
+    }
+    if (side === "none") {
+        // no side effects — allowed
+    }
+}
+function assertSecretAccessAllowed(pkg, slotName) {
+    const slot = pkg.manifest.inputs.find((i) => i.name === slotName);
+    if (!slot || (slot.sensitivity !== "secret" && slot.source !== "secret")) {
+        throw new Error(`Denied: secret access for undeclared slot ${slotName} (deny-by-default)`);
+    }
+}
+/** Resolve a secret ref only if the input slot declares secret sensitivity/source. */
+export async function resolveDeclaredSecret(pkg, slotName, host) {
+    assertSecretAccessAllowed(pkg, slotName);
+    if (!host.resolveSecret) {
+        throw new Error("Denied: no resolveSecret callback (fail closed for secrets)");
+    }
+    return host.resolveSecret(slotName);
+}
 function substitute(template, inputs) {
     return template.replace(/\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g, (_, name) => {
         const v = inputs[name];
@@ -126,16 +202,28 @@ export async function runSkillPackage(pkg, host = {}, options = {}) {
             error: `Missing required inputs: ${missing.map((m) => m.name).join(", ")}`,
         };
     }
-    const consentNeeded = pkg.manifest.permissions
+    const consentNeeded = new Set(pkg.manifest.permissions
         .filter((p) => p.requires_consent)
-        .map((p) => p.side_effect_class);
-    if (mode === "execute" && consentNeeded.length && host.consent) {
-        const allowed = await host.consent({
+        .map((p) => p.side_effect_class));
+    for (const side of pkg.manifest.policy.consent_for ?? []) {
+        if (pkg.manifest.capabilities.some((c) => c.side_effect_class === side) ||
+            pkg.manifest.permissions.some((p) => p.side_effect_class === side)) {
+            consentNeeded.add(side);
+        }
+    }
+    if (mode === "execute" && consentNeeded.size) {
+        if (!host.consent) {
+            return failRun(runId, pkg, mode, resolved, secret_refs, stepRecords, verifications, started, host, "Explicit permission consent required; runtime host has no authenticated consent callback (fail closed)");
+        }
+        const consent = await host.consent({
             title: pkg.manifest.title,
-            permissions: consentNeeded,
+            permissions: [...consentNeeded],
             steps: pkg.workflow.steps.map((s) => `${s.id}:${s.kind}`),
         });
-        if (!allowed) {
+        if (!consent.actor || !consent.at) {
+            return failRun(runId, pkg, mode, resolved, secret_refs, stepRecords, verifications, started, host, "Permission consent callback returned invalid actor/timestamp evidence");
+        }
+        if (!consent.allowed) {
             return {
                 kind: "skill_run",
                 id: runId,
@@ -389,6 +477,12 @@ async function executeStep(step, ctx) {
             const cap = ctx.pkg.manifest.capabilities.find((c) => c.name === step.capability);
             if (!cap)
                 throw new Error(`Unknown capability ${step.capability}`);
+            const args = { ...(step.arguments ?? {}) };
+            for (const [k, bind] of Object.entries(step.argument_bindings ?? {})) {
+                args[k] = ctx.inputs[bind] ?? ctx.stepOutputs[bind];
+            }
+            // Deny-by-default capability gate (even in dry_run for visibility of refusals).
+            assertCapabilityAllowed(ctx.pkg, cap, args);
             if (ctx.dry) {
                 return {
                     output: { dry_run: true, capability: cap.name, arguments: step.arguments },
@@ -406,10 +500,6 @@ async function executeStep(step, ctx) {
                 }
                 throw new Error(`No adapter for capability ${cap.name}`);
             }
-            const args = { ...(step.arguments ?? {}) };
-            for (const [k, bind] of Object.entries(step.argument_bindings ?? {})) {
-                args[k] = ctx.inputs[bind] ?? ctx.stepOutputs[bind];
-            }
             const inv = await adapter.invoke(cap, args);
             if (!inv.ok)
                 throw new Error(inv.error ?? "tool failed");
@@ -471,11 +561,18 @@ async function executeStep(step, ctx) {
                     resultAs: step.result_as,
                 };
             }
-            const existing = (step.result_as ? ctx.inputs[step.result_as] : undefined) ?? ctx.inputs[step.id];
-            if (existing !== undefined) {
-                return { output: existing, resultAs: step.result_as };
+            if (!ctx.host.decide) {
+                throw new Error(`human_decision ${step.id} unsupported: runtime requires an authenticated decide callback; input values cannot spoof human approval`);
             }
-            throw new Error(`human_decision ${step.id} requires input`);
+            const evidence = await ctx.host.decide({
+                id: step.id,
+                prompt: step.prompt,
+                choices: step.choices,
+            });
+            if (!evidence.actor || !evidence.at || !evidence.decision) {
+                throw new Error(`human_decision ${step.id} returned invalid approval evidence`);
+            }
+            return { output: evidence, resultAs: step.result_as };
         }
         case "verify": {
             const results = [];
@@ -505,6 +602,34 @@ async function executeStep(step, ctx) {
                     const val = ctx.stepOutputs[key] ?? ctx.inputs[key];
                     results.push({ assertion, passed: val !== undefined });
                 }
+                else if (assertion.startsWith("precondition:") ||
+                    assertion.startsWith("contract_assertion:")) {
+                    const id = assertion.slice(assertion.indexOf(":") + 1);
+                    const definition = ctx.pkg.workflow.preconditions?.status === "specified"
+                        ? ctx.pkg.workflow.preconditions.items.find((item) => item.id === id)
+                        : ctx.pkg.workflow.verification?.status === "specified"
+                            ? ctx.pkg.workflow.verification.items.find((item) => item.id === id)
+                            : undefined;
+                    if (!definition) {
+                        results.push({ assertion, passed: false, detail: "Contract assertion missing" });
+                    }
+                    else if (!ctx.host.verifyAssertion) {
+                        results.push({
+                            assertion,
+                            passed: false,
+                            detail: "Unsupported domain assertion: runtime host must provide verifyAssertion; presence is not proof",
+                        });
+                    }
+                    else {
+                        const checked = await ctx.host.verifyAssertion({
+                            id: definition.id,
+                            assertion: "assertion" in definition ? definition.assertion : "",
+                            check: definition.check,
+                            evidence: "evidence" in definition ? definition.evidence : undefined,
+                        });
+                        results.push({ assertion, ...checked });
+                    }
+                }
                 else {
                     results.push({
                         assertion,
@@ -536,8 +661,9 @@ async function executeStep(step, ctx) {
 }
 function evalWhen(expr, inputs, stepOutputs) {
     const m = expr.match(/^input:([a-zA-Z0-9_]+)(?:==(.*))?$/);
-    if (!m)
-        return false;
+    if (!m) {
+        throw new Error(`Unsupported branch expression ${JSON.stringify(expr)}; supported form is input:name or input:name==value`);
+    }
     const val = inputs[m[1]] ?? stepOutputs[m[1]];
     if (m[2] === undefined)
         return Boolean(val);
@@ -570,6 +696,42 @@ export async function runSkillArchive(archive, host = {}, options = {}) {
     }
     const unpacked = unpackSkill(archive);
     const manifest = unpacked.manifest;
+    const mode = options.mode ?? "execute";
+    const trustView = inspectTrustView(archive);
+    // Execute refuses unsigned / development / self_reported unless explicit unsafe flag.
+    if (mode === "execute" || mode === "resume") {
+        const trusted = trustView.trust_state === "verified_issuer";
+        if (!trusted && !options.allow_untrusted) {
+            const started = new Date().toISOString();
+            return {
+                kind: "skill_run",
+                id: `run_${randomUUID().replace(/-/g, "").slice(0, 16)}`,
+                skill_id: manifest.id,
+                skill_version: manifest.version,
+                package_digest: manifest.package_digest,
+                status: "failed",
+                mode,
+                resolved_inputs: {},
+                steps: [],
+                verifications: [
+                    {
+                        assertion: "trust_gate",
+                        passed: false,
+                        detail: `${trustView.label}. Pass allow_untrusted / --allow-untrusted to execute anyway.`,
+                    },
+                ],
+                runtime: {
+                    name: RUNTIME_NAME,
+                    version: RUNTIME_VERSION,
+                    host: host.host,
+                    model: host.model,
+                },
+                started_at: started,
+                finished_at: new Date().toISOString(),
+                error: `Refusing execute: ${trustView.label}`,
+            };
+        }
+    }
     const trustProfile = options.trust_profile ??
         (manifest.policy.require_anchor
             ? "anchored"
@@ -577,7 +739,13 @@ export async function runSkillArchive(archive, host = {}, options = {}) {
                 ? "minted"
                 : manifest.policy.trust_profile ?? "open");
     if (trustProfile !== "open") {
-        const trust = verifyMintTrust(archive, trustProfile, options.issuer_secret);
+        const nonExecute = mode === "dry_run" || mode === "inspect" || mode === "explain";
+        const trust = verifyMintTrust(archive, trustProfile, {
+            issuer_secret: options.issuer_secret,
+            allow_development_issuer: options.allow_development_issuer ??
+                (options.allow_untrusted === true || nonExecute),
+            allow_self_reported: options.allow_untrusted === true || nonExecute,
+        });
         if (!trust.ok) {
             const started = new Date().toISOString();
             return {
@@ -587,7 +755,7 @@ export async function runSkillArchive(archive, host = {}, options = {}) {
                 skill_version: manifest.version,
                 package_digest: manifest.package_digest,
                 status: "failed",
-                mode: options.mode ?? "execute",
+                mode,
                 resolved_inputs: {},
                 steps: [],
                 verifications: trust.issues.map((issue) => ({
@@ -607,6 +775,37 @@ export async function runSkillArchive(archive, host = {}, options = {}) {
             };
         }
     }
+    else if ((mode === "execute" || mode === "resume") && !options.allow_untrusted) {
+        // Open profile packages are explicitly untrusted for execute.
+        const started = new Date().toISOString();
+        return {
+            kind: "skill_run",
+            id: `run_${randomUUID().replace(/-/g, "").slice(0, 16)}`,
+            skill_id: manifest.id,
+            skill_version: manifest.version,
+            package_digest: manifest.package_digest,
+            status: "failed",
+            mode,
+            resolved_inputs: {},
+            steps: [],
+            verifications: [
+                {
+                    assertion: "open_untrusted",
+                    passed: false,
+                    detail: "Open/unsigned packages require --allow-untrusted for execute",
+                },
+            ],
+            runtime: {
+                name: RUNTIME_NAME,
+                version: RUNTIME_VERSION,
+                host: host.host,
+                model: host.model,
+            },
+            started_at: started,
+            finished_at: new Date().toISOString(),
+            error: "Refusing execute of open/untrusted package without --allow-untrusted",
+        };
+    }
     return runSkillPackage(unpacked.raw, host, options);
 }
-export { inspectSkill, validatePackageBytes, unpackSkill, explainPackage as explain };
+export { inspectSkill, inspectTrustView, validatePackageBytes, unpackSkill, explainPackage as explain, };

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "@dot-skill/runtime",
-  "version": "0.4.3",
-  "description": "Open .skill Protocol — reference workflow runtime",
+  "version": "0.5.0",
+  "description": "Inspect, dry-run, and execute portable .skill packages",
   "license": "MIT",
   "author": {
     "name": "Bharat Dudeja",
     "url": "https://github.com/bharatdudeja13-cmd"
   },
+  "keywords": [
+    "skill",
+    "dot-skill",
+    ".skill",
+    "ai-agents",
+    "agent-skills",
+    "runtime",
+    "dry-run"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,8 +27,14 @@
     "url": "https://github.com/dot-skill/dot-skill.git",
     "directory": "packages/runtime"
   },
+  "homepage": "https://github.com/dot-skill/dot-skill#readme",
+  "bugs": {
+    "url": "https://github.com/dot-skill/dot-skill/issues"
+  },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
   "exports": {
     ".": {
@@ -33,8 +48,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@dot-skill/core": "^0.4.3",
-    "@dot-skill/protocol": "^0.4.3"
+    "@dot-skill/core": "^0.5.0",
+    "@dot-skill/protocol": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",