maqcli 0.4.0 → 0.6.0

package/dist/core/permissions.js

@@ -0,0 +1,147 @@
+/**
+ * permissions — the "request box" the spec describes.
+ *
+ * A single Headroom master controls everything, but it never performs work
+ * itself; its ants (workers) do. So permission is about gating the ants' major
+ * actions, not the master. Two postures:
+ *
+ *   full     — everything is allowed; the box stays empty.
+ *   moderate — every MAJOR or DESTRUCTIVE action stops and is filed as a
+ *              request. A goal-aware policy (the Headroom check) auto-approves
+ *              actions that clearly serve the stated goal and holds the rest for
+ *              an explicit approve/deny (by the master or a human via the UI).
+ *
+ * Requests are held in an in-memory box; each pending request exposes a promise
+ * (`await`) that resolves when it is decided. Low-risk actions never queue.
+ */
+import { randomUUID } from "node:crypto";
+/** Classify an action string into a risk level (deterministic, pattern-based). */
+export function classifyRisk(action, detail = "") {
+    const s = `${action} ${detail}`.toLowerCase();
+    if (/(rm\s+-rf|rmdir\s+\/s|drop\s+(table|database)|truncate|del\s+\/|format\s|mkfs|:\s*>\s|force[-\s]?push|--force\b|\bpush\b.*\s-f\b|reset\s+--hard|git\s+clean\s+-|delete\s+from|shutdown|reboot)/.test(s)) {
+        return "destructive";
+    }
+    if (/(write|create|modify|edit|install|npm\s+i|pip\s+install|deploy|publish|push|commit|merge|migrate|chmod|chown|mv\s|move|rename|apply|patch)/.test(s)) {
+        return "major";
+    }
+    return "low";
+}
+/**
+ * The Headroom check: allow when the action plainly serves the goal.
+ *  - low risk           → always allow
+ *  - destructive        → never auto-allow (must be approved explicitly)
+ *  - major              → allow only if it aligns with the goal (keyword overlap)
+ */
+export function goalAwarePolicy(req) {
+    if (req.risk === "low")
+        return { allow: true, reason: "low-risk action" };
+    if (req.risk === "destructive")
+        return { allow: false, reason: "destructive action requires explicit approval" };
+    // major: align against the goal.
+    const goal = (req.goal ?? "").toLowerCase();
+    if (!goal)
+        return { allow: false, reason: "no goal context to justify a major action" };
+    const words = new Set((req.action + " " + req.detail).toLowerCase().split(/\W+/).filter((w) => w.length >= 4));
+    const goalWords = new Set(goal.split(/\W+/).filter((w) => w.length >= 4));
+    let overlap = 0;
+    for (const w of words)
+        if (goalWords.has(w))
+            overlap++;
+    return overlap > 0
+        ? { allow: true, reason: `major action aligns with the goal (${overlap} matching term(s))` }
+        : { allow: false, reason: "major action does not clearly serve the stated goal" };
+}
+export class PermissionBroker {
+    mode;
+    policy;
+    box = new Map();
+    waiters = new Map();
+    constructor(mode = "moderate", opts = {}) {
+        this.mode = mode;
+        this.policy = opts.policy ?? goalAwarePolicy;
+    }
+    getMode() {
+        return this.mode;
+    }
+    /**
+     * File a request. Returns the (possibly already-decided) request. In `full`
+     * mode everything is approved immediately; in `moderate` mode the policy runs
+     * and only holds what it cannot justify.
+     */
+    request(action, detail, ctx = {}) {
+        const risk = ctx.risk ?? classifyRisk(action, detail);
+        const req = {
+            id: randomUUID(),
+            action,
+            detail,
+            risk,
+            goal: ctx.goal,
+            status: "pending",
+            reason: "",
+            ts: new Date().toISOString(),
+        };
+        if (this.mode === "full") {
+            req.status = "approved";
+            req.reason = "full-permission mode";
+            this.box.set(req.id, req);
+            return req;
+        }
+        const verdict = this.policy({ action, detail, risk, goal: ctx.goal });
+        if (verdict.allow) {
+            req.status = "approved";
+            req.reason = verdict.reason;
+        }
+        else {
+            req.status = "pending";
+            req.reason = verdict.reason;
+        }
+        this.box.set(req.id, req);
+        return req;
+    }
+    /** Resolve once the request is decided. Already-decided requests resolve now. */
+    await(id) {
+        const req = this.box.get(id);
+        if (!req)
+            return Promise.resolve(false);
+        if (req.status !== "pending")
+            return Promise.resolve(req.status === "approved");
+        return new Promise((resolve) => {
+            const list = this.waiters.get(id) ?? [];
+            list.push({ resolve });
+            this.waiters.set(id, list);
+        });
+    }
+    /** Convenience: file + await in one call. */
+    async gate(action, detail, ctx = {}) {
+        const req = this.request(action, detail, ctx);
+        return this.await(req.id);
+    }
+    approve(id, by = "user") {
+        return this.decide(id, "approved", by);
+    }
+    deny(id, by = "user") {
+        return this.decide(id, "denied", by);
+    }
+    decide(id, status, by) {
+        const req = this.box.get(id);
+        if (!req || req.status !== "pending")
+            return false;
+        req.status = status;
+        req.decidedBy = by;
+        req.reason = `${status} by ${by}`;
+        const waiters = this.waiters.get(id) ?? [];
+        for (const w of waiters)
+            w.resolve(status === "approved");
+        this.waiters.delete(id);
+        return true;
+    }
+    pending() {
+        return [...this.box.values()].filter((r) => r.status === "pending");
+    }
+    list() {
+        return [...this.box.values()];
+    }
+    get(id) {
+        return this.box.get(id);
+    }
+}

package/dist/core/providers-catalog.d.ts

@@ -50,6 +50,7 @@ export interface CatalogProvider {
  */
 export declare const PROVIDER_CATALOG: CatalogProvider[];
 export declare function getCatalogProvider(id: string): CatalogProvider | undefined;
+export declare function providerGoodFor(id: string): string[];
 /**
  * Detect which catalog providers are usable RIGHT NOW from the environment
  * only — no network, no tokens. Local providers (Ollama) are reported as

package/dist/core/providers-catalog.js

@@ -156,6 +156,24 @@ export const PROVIDER_CATALOG = [
 export function getCatalogProvider(id) {
     return PROVIDER_CATALOG.find((p) => p.id === id);
 }
+/**
+ * The role each provider tends to play in the pipeline (fed into the Headroom
+ * knowledge doc). Roles: plan | code | review | summarize | fan-out.
+ */
+const PROVIDER_GOOD_FOR = {
+    openai: ["plan", "code", "review"],
+    anthropic: ["plan", "code", "review", "summarize"],
+    gemini: ["summarize", "code", "fan-out"],
+    groq: ["fan-out", "summarize"],
+    xai: ["plan", "code"],
+    deepseek: ["code", "review"],
+    mistral: ["code", "summarize"],
+    ollama: ["fan-out", "summarize"],
+    litellm: ["plan", "code", "review"],
+};
+export function providerGoodFor(id) {
+    return PROVIDER_GOOD_FOR[id] ?? ["code"];
+}
 /**
  * Detect which catalog providers are usable RIGHT NOW from the environment
  * only — no network, no tokens. Local providers (Ollama) are reported as

package/dist/core/sandbox.d.ts

@@ -15,6 +15,8 @@ export interface SandboxPolicy {
     allowedPaths: string[];
     denyCommands: string[];
     readOnlyCommands: string[];
+    /** Project-specific additions to the protected-path denylist (config-driven; the base list is always applied and cannot be removed). */
+    extraProtectedPaths?: string[];
 }
 export interface SandboxCheck {
     allowed: boolean;
@@ -29,7 +31,7 @@ export declare const EXIT_SANDBOX = 4;
  * @param cwd  - Working directory that becomes the default allowed-path root.
  * @param tier - Permission tier (defaults to **2** — scoped-write).
  */
-export declare function createPolicy(cwd: string, tier?: PermissionTier): SandboxPolicy;
+export declare function createPolicy(cwd: string, tier?: PermissionTier, extraProtectedPaths?: string[]): SandboxPolicy;
 /**
  * Determine whether a **read** of `filePath` is permitted under `policy`.
  *
@@ -63,6 +65,17 @@ export declare function checkCommand(command: string | string[], policy: Sandbox
  * `shutdown`, and `reboot`.
  */
 export declare function isDestructive(command: string | string[]): boolean;
+/**
+ * Scan ingested content (README, commit messages, AGENTS.md, tool/HTTP
+ * output, recalled memory) for prompt-injection indicators before it reaches
+ * a model. Never blocks silently — it records a security event and returns
+ * the finding so the caller decides whether to warn, exclude, or gate on
+ * approval. Maps to OWASP ASI04 (Agentic Supply Chain) / ASI06 (Memory and
+ * Context Poisoning).
+ */
+export declare function checkContent(text: string, source: string): SandboxCheck & {
+    severity: "none" | "low" | "high";
+};
 /**
  * Map a pipeline phase name to its appropriate {@link PermissionTier}.
  *

package/dist/core/sandbox.js

@@ -11,6 +11,7 @@
  */
 import { resolve, normalize } from "node:path";
 import { platform } from "node:os";
+import { checkProtectedPath, scanForInjection, securityLog, makeSecurityEvent } from "./security.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 /** Sentinel exit code returned when a sandbox violation terminates a phase. */
 export const EXIT_SANDBOX = 4;
@@ -99,12 +100,13 @@ function isSystemPath(filePath) {
  * @param cwd  - Working directory that becomes the default allowed-path root.
  * @param tier - Permission tier (defaults to **2** — scoped-write).
  */
-export function createPolicy(cwd, tier = 2) {
+export function createPolicy(cwd, tier = 2, extraProtectedPaths = []) {
     return {
         tier,
         allowedPaths: [resolve(cwd)],
         denyCommands: [...DENY_COMMANDS],
         readOnlyCommands: [...READ_ONLY_COMMANDS],
+        extraProtectedPaths,
     };
 }
 /**
@@ -130,6 +132,19 @@ export function checkRead(filePath, policy) {
  */
 export function checkWrite(filePath, policy) {
     const resolved = normalize(resolve(filePath));
+    // Unconditional, tier-independent denylist: dotfiles, credentials, shell
+    // profiles, and the agent's own config/rules files are NEVER writable, no
+    // matter the tier or permission mode. Re-evaluated fresh every call — never
+    // cached, so a prior approval can't be replayed against a new target.
+    const protectedCheck = checkProtectedPath(resolved, policy.extraProtectedPaths ?? []);
+    if (!protectedCheck.allowed) {
+        securityLog.record(makeSecurityEvent("path-blocked", `${resolved}: ${protectedCheck.reason}`, "high"));
+        return {
+            allowed: false,
+            tier: policy.tier,
+            reason: `Write denied: ${protectedCheck.reason}`,
+        };
+    }
     // Tier 1: read-only — no writes ever.
     if (policy.tier === 1) {
         return {
@@ -178,6 +193,19 @@ export function checkWrite(filePath, policy) {
  */
 export function checkCommand(command, policy) {
     const cmd = normalizeCommand(command);
+    // 0. Unconditional: a command that names a protected path as its target
+    // (redirection, well-known config-editing commands) is blocked regardless
+    // of tier. This closes the gap NVIDIA calls out — OS-level path protection
+    // is the primary control, but catching it at the command layer too is
+    // useful defense-in-depth against sandbox misconfiguration.
+    const redirectTarget = /(>>?|\btee\b)\s*([^\s|&;]+)/.exec(cmd);
+    if (redirectTarget) {
+        const protectedCheck = checkProtectedPath(redirectTarget[2], policy.extraProtectedPaths ?? []);
+        if (!protectedCheck.allowed) {
+            securityLog.record(makeSecurityEvent("path-blocked", `command target ${redirectTarget[2]}: ${protectedCheck.reason}`, "high"));
+            return { allowed: false, tier: policy.tier, reason: `Command denied: ${protectedCheck.reason}` };
+        }
+    }
     // 1. Deny-list — always blocked.
     for (const denied of policy.denyCommands) {
         if (cmd.includes(denied)) {
@@ -240,6 +268,26 @@ export function isDestructive(command) {
     const cmd = normalizeCommand(command).toLowerCase();
     return DESTRUCTIVE_PATTERNS.some((p) => cmd.includes(p.toLowerCase()));
 }
+/**
+ * Scan ingested content (README, commit messages, AGENTS.md, tool/HTTP
+ * output, recalled memory) for prompt-injection indicators before it reaches
+ * a model. Never blocks silently — it records a security event and returns
+ * the finding so the caller decides whether to warn, exclude, or gate on
+ * approval. Maps to OWASP ASI04 (Agentic Supply Chain) / ASI06 (Memory and
+ * Context Poisoning).
+ */
+export function checkContent(text, source) {
+    const finding = scanForInjection(text, source);
+    if (finding.severity !== "none") {
+        securityLog.record(makeSecurityEvent("injection-detected", `${source}: ${finding.reason}`, finding.severity === "high" ? "high" : "low"));
+    }
+    return {
+        allowed: finding.severity !== "high",
+        tier: 1,
+        reason: finding.reason,
+        severity: finding.severity,
+    };
+}
 /**
  * Map a pipeline phase name to its appropriate {@link PermissionTier}.
  *

package/dist/core/security.d.ts

@@ -0,0 +1,113 @@
+/**
+ * security — defense-in-depth for a Headroom master that can drive real AI
+ * agents with real shell/file/network access. Prompt-level instructions
+ * ("don't touch secrets") are advisory only; a compromised or over-eager
+ * agent can be talked past them. These controls enforce at the code
+ * chokepoint instead, mapped to:
+ *
+ *  - NVIDIA AI Red Team's mandatory sandbox controls (network egress,
+ *    no writes outside the workspace, no writes to config/dotfiles ever,
+ *    no cached approvals, secret injection not inheritance).
+ *  - OWASP Top 10 for Agentic Applications:
+ *      ASI01 Agent Goal Hijack / ASI05 Unexpected Code Execution
+ *        -> protected-path denylist + destructive-command detection (sandbox.ts)
+ *      ASI02 Tool Misuse            -> network egress allowlist
+ *      ASI03 Identity/Privilege Abuse -> secret scrubbing for spawned processes
+ *      ASI04 Agentic Supply Chain    -> prompt-injection scanning of ingested
+ *                                       content (README, commits, AGENTS.md,
+ *                                       skills, tool output) before it reaches
+ *                                       a model
+ *      ASI06 Memory/Context Poisoning -> same scanner applied to recall memory
+ *
+ * Every check here is a pure function re-evaluated on every call — nothing is
+ * memoized or cached, so a single approval can never be replayed (NVIDIA:
+ * "approvals should never be cached or persisted").
+ */
+/**
+ * Paths that must NEVER be written to by the agent, regardless of tier,
+ * permission mode, or user override. This list is the "enterprise-level
+ * denylist" NVIDIA describes: it cannot be relaxed by config.
+ */
+export declare function baseProtectedPaths(): string[];
+/** File name / extension patterns that are protected wherever they appear
+ * (including inside the project workspace) — agent-config and secret files. */
+export declare const PROTECTED_NAME_PATTERNS: RegExp[];
+export interface PathCheck {
+    allowed: boolean;
+    reason: string;
+    protectedBy?: string;
+}
+/**
+ * Check a write target against the protected-path denylist. `extra` allows
+ * project-specific additions (config), but the base list is always applied on
+ * top and can never be removed — this is the "enterprise policy" backstop.
+ */
+export declare function checkProtectedPath(targetPath: string, extra?: string[]): PathCheck;
+export interface EgressCheck {
+    allowed: boolean;
+    reason: string;
+}
+/** Default-deny egress: only these hosts are reachable unless configured otherwise. */
+export declare const DEFAULT_NET_ALLOWLIST: string[];
+/**
+ * Check an outbound URL against the egress allowlist. Wildcards ("*.example.com")
+ * match subdomains. Default-deny: anything not listed is blocked (NVIDIA:
+ * "network connections ... should not be permitted without manual approval").
+ */
+export declare function checkEgress(url: string, allowlist?: string[]): EgressCheck;
+/**
+ * Scrub secret-shaped env vars from an environment before it's handed to a
+ * spawned process. `allow` explicitly re-admits specific names the current
+ * task actually needs (secret injection, not blanket inheritance — NVIDIA).
+ */
+export declare function scrubEnv(env: NodeJS.ProcessEnv, allow?: string[]): NodeJS.ProcessEnv;
+/** Redact secret-shaped substrings from text before it is logged or shown. */
+export declare function redactSecrets(text: string): string;
+export type InjectionSeverity = "none" | "low" | "high";
+export interface InjectionFinding {
+    severity: InjectionSeverity;
+    matches: string[];
+    reason: string;
+}
+/** Scan a single blob of ingested text for injection indicators. */
+export declare function scanForInjection(text: string, source?: string): InjectionFinding;
+/** Scan several named blobs at once (e.g. scout findings) and keep only hits. */
+export declare function scanAll(blobs: Record<string, string | null | undefined>): Record<string, InjectionFinding>;
+export interface SecurityEvent {
+    ts: string;
+    kind: "path-blocked" | "egress-blocked" | "injection-detected" | "secret-scrubbed";
+    detail: string;
+    severity: "low" | "high";
+}
+export declare function makeSecurityEvent(kind: SecurityEvent["kind"], detail: string, severity?: SecurityEvent["severity"]): SecurityEvent;
+/** In-memory ring buffer of recent security events, for `maq security report` / the UI. */
+export declare class SecurityLog {
+    private cap;
+    private events;
+    constructor(cap?: number);
+    record(e: SecurityEvent): void;
+    list(): SecurityEvent[];
+    clear(): void;
+}
+/** Process-wide default log so independently-imported modules share one feed. */
+export declare const securityLog: SecurityLog;
+export interface SecurityConfigLike {
+    extraProtectedPaths: string[];
+    extraNetAllowlist: string[];
+    permissionMode: string;
+}
+/**
+ * The single source of truth for "what does MAQ enforce right now" — used by
+ * both `maq security rules` (terminal) and `GET /v1/security` (web UI), so the
+ * two surfaces can never drift out of sync with each other or with what
+ * sandbox.ts/exec.ts/tools.ts actually enforce.
+ */
+export declare function securityRules(cfg: SecurityConfigLike): {
+    protectedPaths: string[];
+    protectedNamePatterns: string[];
+    extraProtectedPaths: string[];
+    netAllowlist: string[];
+    permissionMode: string;
+    secretEnvScrubbing: boolean;
+    promptInjectionScanning: string[];
+};