skillscript-runtime 0.24.0 → 0.25.1

package/dist/lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"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"}

package/dist/lint.js

@@ -1,4 +1,5 @@
 import { parse, tokenizeKeywordArgs } from "./parser.js";
+import { extractSecretRefs, findMalformedSecretMarkers, countSecretMarkers } from "./secrets.js";
 import { classifyMutation, authorizationGranted } from "./mutation-gate.js";
 import { KNOWN_FILTERS } from "./filters.js";
 // ─── lint() entry point ────────────────────────────────────────────────────
@@ -1458,6 +1459,170 @@ const CREDENTIAL_IN_ARGS = {
         return findings;
     },
 };
+// ─── secret references (v0.25.0) ──────────────────────────────────────────
+// A `{{secret.NAME}}` marker is USE-ONLY: legal only in a sink op (a
+// `shell(...)` op or a `$ connector.tool` dispatch), never where its value
+// could be read, bound, or emitted. These two tier-1 rules enforce the
+// contract at compile time; the runtime resolves markers at the sink
+// (src/secrets.ts holds SECRET_SINK_OP_KINDS, the shared sink list).
+/** True when this `$` op is an unqualified built-in intercept (execute_skill /
+ * json_parse) — a `$`-kind op that is NOT a real external sink. A secret
+ * marker in it would flow into a child skill's scope or a parsed/bound var,
+ * never an external credential, so it's a use-only violation. A *qualified*
+ * `$ conn.execute_skill` is a real connector dispatch and not excluded. */
+function isBuiltinNonSinkDollar(op) {
+    if (op.kind !== "$" || op.mcpConnector !== undefined)
+        return false;
+    const tool = /^([A-Za-z_][\w:-]*)/.exec(op.body.trimStart())?.[1];
+    return tool === "execute_skill" || tool === "json_parse";
+}
+/** Text positions of `op` where a secret marker is a legal sink injection. */
+function secretSinkText(op) {
+    if (op.kind === "shell")
+        return `${op.body ?? ""} ${op.argv?.join(" ") ?? ""}`;
+    if (op.kind === "$" && !isBuiltinNonSinkDollar(op))
+        return op.body ?? "";
+    return "";
+}
+/** Text positions of `op` where a secret marker is ILLEGAL (would expose the
+ * value): every author-controlled field except the sink positions above —
+ * the body of a non-sink op, `$set`/`$append` values, foreach lists, op
+ * fallbacks, and condition expressions. */
+function secretNonSinkText(op) {
+    const parts = [];
+    const bodyIsSink = op.kind === "shell" || (op.kind === "$" && !isBuiltinNonSinkDollar(op));
+    if (!bodyIsSink && op.body)
+        parts.push(op.body);
+    if (op.setValue !== undefined)
+        parts.push(op.setValue);
+    if (op.foreachList !== undefined)
+        parts.push(op.foreachList);
+    if (op.fallback !== undefined)
+        parts.push(op.fallback);
+    if (op.ifBranches !== undefined)
+        for (const b of op.ifBranches)
+            parts.push(b.cond);
+    return parts.join(" ");
+}
+const SECRET_USE_ONLY = {
+    id: "secret-use-only",
+    severity: "error",
+    description: "A `{{secret.NAME}}` marker appears outside a secret sink (a `shell(...)` op or a `$ connector.tool` dispatch). Secrets are use-only: the runtime injects the value at the sink and never lets it reach a readable, bindable, or emittable surface.",
+    remediation: "Use the secret only inside a `shell(command=\"... {{secret.NAME}} ...\")` op or a `$ connector.tool arg={{secret.NAME}}` dispatch. Never put it in `$set`, `emit`, a condition, a `# Output:` template, a `file_*`/`notify` op, or an op `(fallback: ...)` — those would expose the value.",
+    check: (ctx) => {
+        const findings = [];
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                for (const name of extractSecretRefs(secretNonSinkText(op))) {
+                    findings.push({
+                        rule: "secret-use-only",
+                        severity: "error",
+                        block: targetName,
+                        message: `Secret marker {{secret.${name}}} appears in a '${op.kind}' op position that is not a secret sink. A secret may only be injected into a shell(...) op or a '$ connector.tool' dispatch — never where its value could be read, bound, or emitted.`,
+                    });
+                }
+            });
+        }
+        if (ctx.parsed.outputTemplate !== null) {
+            for (const name of extractSecretRefs(ctx.parsed.outputTemplate)) {
+                findings.push({
+                    rule: "secret-use-only",
+                    severity: "error",
+                    message: `Secret marker {{secret.${name}}} appears in the body-text output template. A secret value must never reach an output surface; reference it only inside a shell(...) or '$ connector.tool' sink op.`,
+                });
+            }
+        }
+        // Source-level backstop (adopter finding 24ce83f8). The scans above walk the
+        // parsed op AST + template, so they miss a marker the parser DROPPED — e.g. a
+        // malformed `emit {{secret.X}}` (no parens) parses to no op, yet the marker
+        // sits in source. Compare every marker in the raw source against the markers
+        // the AST scan accounted for (sink positions + non-sink positions + template);
+        // any surplus lives in a dropped/unrecognized position and is still a
+        // use-only violation. Counts (not names) so repeats can't mask a leak.
+        let accounted = 0;
+        for (const [, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                accounted += countSecretMarkers(secretSinkText(op)) + countSecretMarkers(secretNonSinkText(op));
+            });
+        }
+        if (ctx.parsed.outputTemplate !== null)
+            accounted += countSecretMarkers(ctx.parsed.outputTemplate);
+        const surplus = countSecretMarkers(ctx.source) - accounted;
+        if (surplus > 0) {
+            findings.push({
+                rule: "secret-use-only",
+                severity: "error",
+                message: `A {{secret.…}} marker appears outside any recognized op (e.g. a malformed \`emit {{secret.X}}\` without parentheses, or a dropped line). A secret may only be used inside a shell(...) op or a '$ connector.tool' dispatch.`,
+            });
+        }
+        return findings;
+    },
+};
+const SECRET_UNDECLARED = {
+    id: "secret-undeclared",
+    severity: "error",
+    description: "A `{{secret.NAME}}` marker is used without a matching `# Requires: secret.NAME` declaration. Secrets are declared before use so an approver sees which credentials the skill reaches.",
+    remediation: "Add `# Requires: secret.NAME` to the frontmatter for every secret the skill references.",
+    check: (ctx) => {
+        const declared = new Set(ctx.parsed.secretRequires);
+        const findings = [];
+        const seen = new Set();
+        const checkText = (text, block) => {
+            for (const name of extractSecretRefs(text)) {
+                if (declared.has(name) || seen.has(name))
+                    continue;
+                seen.add(name);
+                findings.push({
+                    rule: "secret-undeclared",
+                    severity: "error",
+                    message: `Secret marker {{secret.${name}}} is used but not declared. Add \`# Requires: secret.${name}\` to the frontmatter so an approver can see which secrets this skill reaches.`,
+                    ...(block !== undefined ? { block } : {}),
+                });
+            }
+        };
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                checkText(secretSinkText(op), targetName);
+                checkText(secretNonSinkText(op), targetName);
+            });
+        }
+        if (ctx.parsed.outputTemplate !== null)
+            checkText(ctx.parsed.outputTemplate);
+        return findings;
+    },
+};
+const SECRET_DYNAMIC_NAME = {
+    id: "secret-dynamic-name",
+    severity: "error",
+    description: "A `{{secret.…}}` marker has a non-literal name (e.g. `{{secret.${VAR}}}`) or is otherwise malformed. The secret name must be a compile-time literal so the declare-before-spend gate and the approver-visible `# Requires` reach cannot be evaded by building the name at runtime.",
+    remediation: "Use a literal secret name: `{{secret.NAME}}` where NAME matches a `# Requires: secret.NAME` declaration. Do not interpolate (`{{secret.${VAR}}}`) — the runtime refuses dynamically-named secrets.",
+    check: (ctx) => {
+        const findings = [];
+        const seen = new Set();
+        const scan = (text, block) => {
+            for (const bad of findMalformedSecretMarkers(text)) {
+                if (seen.has(bad))
+                    continue;
+                seen.add(bad);
+                findings.push({
+                    rule: "secret-dynamic-name",
+                    severity: "error",
+                    message: `Malformed/dynamic secret marker '${bad}' — the secret name must be a compile-time literal (\`{{secret.NAME}}\`), not interpolated or built at runtime.`,
+                    ...(block !== undefined ? { block } : {}),
+                });
+            }
+        };
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                scan(secretSinkText(op), targetName);
+                scan(secretNonSinkText(op), targetName);
+            });
+        }
+        if (ctx.parsed.outputTemplate !== null)
+            scan(ctx.parsed.outputTemplate);
+        return findings;
+    },
+};
 const STATUS_DISABLED = {
     id: "status-disabled",
     severity: "error",
@@ -3410,6 +3575,9 @@ const RULES = [
     APPEND_TO_NON_LIST,
     DISABLED_SKILL_REFERENCE,
     CREDENTIAL_IN_ARGS,
+    SECRET_USE_ONLY,
+    SECRET_UNDECLARED,
+    SECRET_DYNAMIC_NAME,
     STATUS_DISABLED,
     CIRCULAR_DEPENDENCY,
     MISSING_DEPENDENCY,