corpus-core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,117 @@
+/** The outcome of evaluating an agent action against all policies. */
+export type Verdict = 'PASS' | 'BLOCK' | 'CONFIRM';
+/** Reason categories for BLOCK verdicts. Human-readable by design. */
+export type BlockReason = 'DESTRUCTIVE_ACTION' | 'AUTO_SEND' | 'EXTERNAL_WRITE' | 'SCOPE_VIOLATION' | 'LOW_CONFIDENCE' | 'RATE_EXCEEDED' | 'UNKNOWN_ACTION' | 'CUSTOM';
+/** Result returned by a single policy check. */
+export interface PolicyResult {
+    verdict: Verdict;
+    blockReason: BlockReason | null;
+    /** Human-readable message, safe to show to end users. */
+    message: string;
+    /** Which policy produced this result. */
+    policyName: string;
+    requiresConfirmation: boolean;
+}
+/** A single YAML policy rule. */
+export interface PolicyRule {
+    name: string;
+    verdict: Verdict;
+    message: string;
+    blockReason?: BlockReason;
+    trigger: {
+        actionType?: string | string[];
+        actionContains?: string | string[];
+        actionStartsWith?: string | string[];
+        contextKey?: string;
+        contextValueIn?: unknown[];
+        contextValueBelow?: number;
+        contextValueAbove?: number;
+        userApproved?: boolean;
+    };
+}
+/** A complete corpus.policy.yaml file parsed into memory. */
+export interface PolicyFile {
+    agent: string;
+    version: string;
+    rules: PolicyRule[];
+    /** Path to a .jac file for complex rules evaluated after YAML rules. */
+    jacExtension?: string;
+    /** Allowed action prefixes for scope guard. */
+    allowedActions?: string[];
+    /** Rate limits per action type. */
+    rateLimits?: Record<string, {
+        count: number;
+        windowSeconds: number;
+    }>;
+}
+/**
+ * What the developer passes to corpus.protect().
+ * actionPayload is accepted but never stored or logged.
+ */
+export interface CorpusInput {
+    /** What the agent wants to do. Maps to policy rule triggers. */
+    actionType: string;
+    /** The data the action will operate on. Never stored by Corpus. */
+    actionPayload?: Record<string, unknown>;
+    /**
+     * Arbitrary key-value context from the agent.
+     * Use this to pass intent, confidence, source, etc.
+     */
+    context?: Record<string, unknown>;
+    /** True if the user has already explicitly confirmed this action. */
+    userApproved?: boolean;
+}
+/** What gets stored in the database. Intentionally minimal. No user content. */
+export interface ActionLogEntry {
+    id: string;
+    projectSlug: string;
+    actionType: string;
+    verdict: Verdict;
+    userDecision: 'CONFIRMED' | 'CANCELLED' | null;
+    policyTriggered: string;
+    blockReason: BlockReason | null;
+    durationMs: number;
+    timestamp: string;
+}
+export interface CorpusConfig {
+    projectSlug: string;
+    apiEndpoint: string;
+    apiKey: string;
+    /**
+     * observe: records verdicts but never blocks execution. Use during beta.
+     * enforce: fully enforces BLOCK and CONFIRM verdicts.
+     */
+    mode: 'observe' | 'enforce';
+    /** Path to corpus.policy.yaml or a directory of policy files. */
+    policyPath: string;
+    thresholds?: {
+        /** Actions with context.confidence below this are BLOCK. Default: 0.50 */
+        confidenceBlock?: number;
+        /** Actions with context.confidence below this are CONFIRM. Default: 0.72 */
+        confidenceConfirm?: number;
+    };
+    timeouts?: {
+        /** Max ms for Jac policy subprocess. Default: 200 */
+        policyEvalMs?: number;
+        /** Undo window in ms after action executes. Default: 5000 */
+        undoWindowMs?: number;
+    };
+}
+/**
+ * Callbacks the developer implements to connect Corpus to their UI.
+ * All hooks are optional in observe mode.
+ */
+export interface CorpusHooks<TResult = unknown> {
+    onConfirmRequired?: (message: string, confirm: () => Promise<TResult | null>, cancel: () => void) => void;
+    onBlocked?: (message: string, reason: BlockReason | null) => void;
+    onUndoAvailable?: (message: string, undo: () => Promise<void>, msRemaining: number) => void;
+    onPolicyEvalComplete?: (result: PolicyResult, durationMs: number) => void;
+}
+export declare class CorpusBlockedError extends Error {
+    readonly policyName: string;
+    readonly blockReason: BlockReason | null;
+    constructor(policyName: string, blockReason: BlockReason | null, message: string);
+}
+export declare class CorpusConfigError extends Error {
+    constructor(message: string);
+}

package/dist/types.js

@@ -0,0 +1,16 @@
+export class CorpusBlockedError extends Error {
+    policyName;
+    blockReason;
+    constructor(policyName, blockReason, message) {
+        super(`[corpus] Policy '${policyName}' blocked this action: ${message}`);
+        this.name = 'CorpusBlockedError';
+        this.policyName = policyName;
+        this.blockReason = blockReason;
+    }
+}
+export class CorpusConfigError extends Error {
+    constructor(message) {
+        super(`[corpus] Config error: ${message}`);
+        this.name = 'CorpusConfigError';
+    }
+}

package/dist/yaml-evaluator.d.ts

@@ -0,0 +1,12 @@
+import type { PolicyFile, PolicyResult, CorpusInput } from './types.js';
+/**
+ * Evaluates a CorpusInput against a PolicyFile.
+ * Returns the first matching rule's verdict, or PASS if no rule matches.
+ * Rules are evaluated in order. First match wins.
+ */
+export declare function evaluateYamlPolicies(input: CorpusInput, policyFile: PolicyFile): PolicyResult;
+/**
+ * Loads and parses a corpus.policy.yaml file.
+ * Throws if the file is missing or malformed.
+ */
+export declare function loadPolicyFile(policyPath: string): Promise<PolicyFile>;

package/dist/yaml-evaluator.js

@@ -0,0 +1,105 @@
+/**
+ * Evaluates a CorpusInput against a PolicyFile.
+ * Returns the first matching rule's verdict, or PASS if no rule matches.
+ * Rules are evaluated in order. First match wins.
+ */
+export function evaluateYamlPolicies(input, policyFile) {
+    for (const rule of policyFile.rules) {
+        if (ruleMatches(rule, input)) {
+            return {
+                verdict: rule.verdict,
+                blockReason: rule.blockReason ?? null,
+                message: rule.message,
+                policyName: rule.name,
+                requiresConfirmation: rule.verdict === 'CONFIRM',
+            };
+        }
+    }
+    return {
+        verdict: 'PASS',
+        blockReason: null,
+        message: '',
+        policyName: '__no_match__',
+        requiresConfirmation: false,
+    };
+}
+function ruleMatches(rule, input) {
+    if (!rule.trigger)
+        return false;
+    const t = rule.trigger;
+    if (!input.actionType)
+        return false;
+    const actionLower = input.actionType.toLowerCase();
+    // actionType: exact match (string or array)
+    if (t.actionType !== undefined) {
+        const types = Array.isArray(t.actionType) ? t.actionType : [t.actionType];
+        if (!types.some((a) => actionLower === a.toLowerCase()))
+            return false;
+    }
+    // actionContains: substring match
+    if (t.actionContains !== undefined) {
+        const needles = Array.isArray(t.actionContains) ? t.actionContains : [t.actionContains];
+        if (!needles.some((n) => actionLower.includes(n.toLowerCase())))
+            return false;
+    }
+    // actionStartsWith: prefix match
+    if (t.actionStartsWith !== undefined) {
+        const prefixes = Array.isArray(t.actionStartsWith) ? t.actionStartsWith : [t.actionStartsWith];
+        if (!prefixes.some((p) => actionLower.startsWith(p.toLowerCase())))
+            return false;
+    }
+    // contextKey + contextValue* checks
+    if (t.contextKey !== undefined) {
+        const ctxValue = input.context?.[t.contextKey];
+        if (ctxValue === undefined)
+            return false;
+        if (t.contextValueIn !== undefined) {
+            // Use loose comparison to handle YAML type coercion (number vs string)
+            if (!t.contextValueIn.some((v) => String(v) === String(ctxValue)))
+                return false;
+        }
+        if (t.contextValueBelow !== undefined) {
+            if (typeof ctxValue !== 'number' || ctxValue >= t.contextValueBelow)
+                return false;
+        }
+        if (t.contextValueAbove !== undefined) {
+            if (typeof ctxValue !== 'number' || ctxValue <= t.contextValueAbove)
+                return false;
+        }
+    }
+    // userApproved check
+    if (t.userApproved !== undefined) {
+        if ((input.userApproved ?? false) !== t.userApproved)
+            return false;
+    }
+    return true;
+}
+/**
+ * Loads and parses a corpus.policy.yaml file.
+ * Throws if the file is missing or malformed.
+ */
+export async function loadPolicyFile(policyPath) {
+    const { readFile } = await import('fs/promises');
+    const { parse } = await import('yaml');
+    const raw = await readFile(policyPath, 'utf-8');
+    const parsed = parse(raw);
+    if (!parsed.agent || !Array.isArray(parsed.rules)) {
+        throw new Error(`Invalid policy file at ${policyPath}. Must have 'agent' and 'rules' fields.`);
+    }
+    if (!parsed.version) {
+        parsed.version = '1.0';
+    }
+    // Validate individual rules have required fields
+    for (let i = 0; i < parsed.rules.length; i++) {
+        const rule = parsed.rules[i];
+        if (!rule.name || !rule.verdict || !rule.trigger) {
+            throw new Error(`Invalid rule at index ${i} in ${policyPath}. Rules must have 'name', 'verdict', and 'trigger' fields.`);
+        }
+        // Normalize verdict to uppercase (PASS, BLOCK, CONFIRM)
+        rule.verdict = rule.verdict.toUpperCase();
+        if (!['PASS', 'BLOCK', 'CONFIRM'].includes(rule.verdict)) {
+            throw new Error(`Invalid verdict '${rule.verdict}' in rule '${rule.name}' at ${policyPath}. Must be PASS, BLOCK, or CONFIRM.`);
+        }
+    }
+    return parsed;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "corpus-core",
+  "version": "0.1.0",
+  "description": "Core security scanning engine for Corpus — the immune system for AI-generated code",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/cve-database.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
+  },
+  "keywords": ["ai", "security", "trust-score", "scanner", "policy-engine", "secrets", "pii", "cve", "vibe-coding"],
+  "repository": { "type": "git", "url": "https://github.com/fluentflier/corpus" },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}