@prestyj/cli 5.32.0 → 5.32.2

package/dist/core/skill-scan.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Load-time malware scan for skills (ez-safe S1).
+ *
+ * Few, narrow, high-confidence rules tied to real incidents (ClawHavoc fake
+ * "prerequisite" installers, Snyk ToxicSkills droppers and webhook exfil,
+ * tag-character smuggling). A hit means the skill is not loaded; there is no
+ * prompt. Rules distinguish *instructing* from *describing*: in markdown a
+ * line that sits in warning/analysis prose ("never", "attack", "e.g.") is not
+ * a hit unless it is under an imperative setup/prerequisite heading. Script
+ * files get no such allowance — code runs.
+ *
+ * Results are cached by content hash in memory and (via `loadSkillScanCacheFile`
+ * / `saveSkillScanCacheFile`) on disk, so an unchanged skill costs a file read
+ * and a hash, even on a fresh app start.
+ */
+export type SkillScanRule = "decode-to-shell" | "download-to-shell" | "quarantine-strip" | "reverse-shell" | "fake-prerequisite" | "credential-exfil" | "secret-in-url" | "hide-from-user" | "invisible-text" | "symlink-escape";
+export interface SkillScanFinding {
+    rule: SkillScanRule;
+    /** Path relative to the skill folder. */
+    file: string;
+    /** 1-based line, 0 when not line-specific. */
+    line: number;
+    reason: string;
+}
+/**
+ * `hash` (blocked content scans only) is the content hash of everything that
+ * was scanned, so a caller can tell "the same blocked skill again" from "a new
+ * version of it".
+ */
+export type SkillScanResult = {
+    ok: true;
+} | {
+    ok: false;
+    finding: SkillScanFinding;
+    hash?: string;
+};
+export type SkillFileKind = "markdown" | "script";
+/** A host data should never be sent to: request catcher, paste, tunnel, raw public IP. */
+export declare function isExfilUrl(raw: string): boolean;
+/**
+ * Wording that orders the agent to keep something from the user. Shared with
+ * the MCP tool guard. Each form names the hidden object ("this step", "these
+ * instructions") so ordinary advice like "don't tell the user it's done before
+ * tests pass" stays clean.
+ */
+export declare const HIDE_FROM_USER: readonly RegExp[];
+export declare function findHideFromUser(text: string): string | null;
+/** Hidden characters in raw text: tag smuggling, bidi, ANSI, zero-width runs. */
+export declare function findInvisibleText(raw: string): {
+    reason: string;
+    index: number;
+} | null;
+/**
+ * Scan one skill file's raw text. Returns the first finding, or null.
+ * `kind: "script"` treats every line as code that runs.
+ */
+export declare function scanSkillText(raw: string, file: string, kind: SkillFileKind): SkillScanFinding | null;
+/**
+ * One stat fingerprint per scanned directory and file. A directory's mtime
+ * changes when an entry is added, removed or renamed in it; a file's
+ * size/mtime/ctime/inode change when it is written or replaced. ctime and
+ * inode can't be reset by `touch`/`tar`, so a swapped file can't fake a match.
+ */
+type StatSig = readonly [rel: string, size: number, mtimeMs: number, ctimeMs: number, ino: number];
+/**
+ * Content-hash keyed verdict cache. An explicit object (not module state) so
+ * tests can use a fresh one; `defaultSkillScanCache` is the process-wide one.
+ */
+export interface StatEntry {
+    sigs: readonly StatSig[];
+    verdict: SkillScanResult;
+}
+export declare class SkillScanCache {
+    private readonly verdicts;
+    /** Path → stat fingerprint + verdict: the no-read, no-hash warm path. */
+    private readonly byStats;
+    /** Disk files already merged in, so each session start doesn't re-read them. */
+    readonly loadedFiles: Set<string>;
+    /** Bumped on every new verdict; lets a caller skip a no-op disk write. */
+    changes: number;
+    get(key: string): SkillScanResult | undefined;
+    set(key: string, value: SkillScanResult): void;
+    getStats(key: string): StatEntry | undefined;
+    setStats(key: string, value: StatEntry): void;
+    statEntries(): [string, StatEntry][];
+    entries(): [string, SkillScanResult][];
+    get size(): number;
+}
+/**
+ * Bump whenever a rule changes what it catches: verdicts saved under another
+ * version are ignored, so an old "ok" can never hide a newly caught skill.
+ */
+export declare const SKILL_SCAN_RULES_VERSION = 2;
+/**
+ * Merge saved verdicts from `file` into `cache` (once per file per cache).
+ * A missing, corrupt or other-version file is simply ignored: the skills are
+ * then scanned as usual.
+ */
+export declare function loadSkillScanCacheFile(cache: SkillScanCache, file: string): Promise<void>;
+/** Write `cache` to `file` (temp file + rename). Best effort: it is only a cache. */
+export declare function saveSkillScanCacheFile(cache: SkillScanCache, file: string): Promise<void>;
+export declare const defaultSkillScanCache: SkillScanCache;
+/**
+ * Scan a directory-layout skill: `<root>/SKILL.md` (passed raw as read by the
+ * loader) plus every script in the folder, and every symlink in it.
+ */
+export declare function scanSkillFolder(root: string, skillMd: string, cache?: SkillScanCache): Promise<SkillScanResult>;
+/** Scan a flat-layout skill (`<dir>/<name>.md`), refusing a symlink that leaves `dir`. */
+export declare function scanSkillFile(filePath: string, content: string, cache?: SkillScanCache): Promise<SkillScanResult>;
+/** One plain line for logs and the user: which skill, and why. */
+export declare function skillBlockMessage(name: string, finding: SkillScanFinding): string;
+export {};