@a5c-ai/babysitter-sdk 5.0.0 → 5.0.1-staging.00fa5317c

package/dist/breakpoints/evaluator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Auto-approval evaluator.
+ *
+ * Precedence (highest wins):
+ *   0. [GAP-SEC-005] Posture: allowAutoApprove === false (category block)
+ *   0b.[GAP-SEC-005] Posture: requireExplicitRule with no matching rule
+ *   1. never-auto-approve rule match
+ *   2. alwaysBreakOn profile tags
+ *   3. auto-approve rule match
+ *   4. autoApproveAfterN threshold (clamped by posture minConsecutiveApprovalsForAutoN)
+ *   5. prompt (default — no auto-approval)
+ */
+import type { BreakpointRule, AutoApprovalResult, ActionCategory, ApprovalPosture } from "./types";
+import type { BreakpointConfig } from "../profiles/types";
+export interface EvaluateAutoApprovalOptions {
+    breakpointId: string;
+    tags?: string[];
+    expert?: string;
+    rules: BreakpointRule[];
+    profileConfig?: BreakpointConfig;
+    /** Number of consecutive past approvals for this breakpointId. */
+    consecutiveApprovals?: number;
+    /** autoApproveAfterN from breakpoint definition (-1 = disabled). */
+    autoApproveAfterN?: number;
+    /** GAP-SEC-005: Explicit action category. Overrides prefix-derived category. */
+    actionCategory?: ActionCategory;
+    /** GAP-SEC-005: Override posture for this evaluation (skips DEFAULT_POSTURES lookup). */
+    postureOverride?: ApprovalPosture;
+    /** GAP-SEC-005: When true, posture enforcement is skipped entirely. */
+    skipPostureEnforcement?: boolean;
+}
+export declare function evaluateAutoApproval(options: EvaluateAutoApprovalOptions): AutoApprovalResult;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/breakpoints/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/breakpoints/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACnG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAmC1D,MAAM,WAAW,2BAA2B;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,gBAAgB,CAAC;IACjC,kEAAkE;IAClE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,yFAAyF;IACzF,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,uEAAuE;IACvE,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,kBAAkB,CA8H7F"}

package/dist/breakpoints/evaluator.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Auto-approval evaluator.
+ *
+ * Precedence (highest wins):
+ *   0. [GAP-SEC-005] Posture: allowAutoApprove === false (category block)
+ *   0b.[GAP-SEC-005] Posture: requireExplicitRule with no matching rule
+ *   1. never-auto-approve rule match
+ *   2. alwaysBreakOn profile tags
+ *   3. auto-approve rule match
+ *   4. autoApproveAfterN threshold (clamped by posture minConsecutiveApprovalsForAutoN)
+ *   5. prompt (default — no auto-approval)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateAutoApproval = evaluateAutoApproval;
+const patterns_1 = require("./patterns");
+// ---------------------------------------------------------------------------
+// Inlined posture helpers (canonical implementation moved to babysitter-agent)
+// ---------------------------------------------------------------------------
+const DEFAULT_POSTURES = {
+    read: { name: 'permissive', allowAutoApprove: true, minConsecutiveApprovalsForAutoN: 0, requireExplicitRule: false, requiredApproverLevel: 'any' },
+    write: { name: 'cautious', allowAutoApprove: true, minConsecutiveApprovalsForAutoN: 3, requireExplicitRule: false, requiredApproverLevel: 'any' },
+    execute: { name: 'guarded', allowAutoApprove: true, minConsecutiveApprovalsForAutoN: 5, requireExplicitRule: true, requiredApproverLevel: 'any' },
+    destroy: { name: 'locked', allowAutoApprove: false, minConsecutiveApprovalsForAutoN: -1, requireExplicitRule: true, requiredApproverLevel: 'owner' },
+    network: { name: 'cautious', allowAutoApprove: true, minConsecutiveApprovalsForAutoN: 3, requireExplicitRule: false, requiredApproverLevel: 'any' },
+    auth: { name: 'locked', allowAutoApprove: false, minConsecutiveApprovalsForAutoN: -1, requireExplicitRule: true, requiredApproverLevel: 'owner' },
+};
+const PREFIX_TO_CATEGORY = {
+    'read': 'read', 'write': 'write', 'exec': 'execute', 'execute': 'execute',
+    'destroy': 'destroy', 'delete': 'destroy', 'net': 'network', 'network': 'network',
+    'auth': 'auth', 'cred': 'auth',
+};
+function getPostureForCategory(category, overrides) {
+    const base = DEFAULT_POSTURES[category];
+    if (!overrides)
+        return base;
+    return { ...base, ...overrides };
+}
+function resolvePostureFromBreakpointId(breakpointId) {
+    const dotIndex = breakpointId.indexOf('.');
+    if (dotIndex === -1)
+        return undefined;
+    const prefix = breakpointId.substring(0, dotIndex);
+    return PREFIX_TO_CATEGORY[prefix];
+}
+function evaluateAutoApproval(options) {
+    const { breakpointId, tags, expert, rules, profileConfig, consecutiveApprovals = 0, skipPostureEnforcement = false, } = options;
+    let { autoApproveAfterN = -1 } = options;
+    const attributes = { tags, expert };
+    // Resolve posture
+    const effectiveCategory = options.actionCategory ?? resolvePostureFromBreakpointId(breakpointId);
+    let posture;
+    if (!skipPostureEnforcement && effectiveCategory) {
+        const profileOverrides = profileConfig?.postureOverrides?.[effectiveCategory];
+        posture = options.postureOverride ?? getPostureForCategory(effectiveCategory, profileOverrides);
+    }
+    // Check if profile disables posture enforcement globally
+    if (profileConfig?.disablePostureEnforcement) {
+        posture = undefined;
+    }
+    // 0. Posture: allowAutoApprove === false (category block)
+    if (posture && !posture.allowAutoApprove) {
+        return {
+            recommended: false,
+            reason: `Category '${effectiveCategory}' requires explicit human approval (posture: ${posture.name})`,
+            consecutiveApprovals,
+            blockedByPosture: true,
+            effectiveCategory,
+        };
+    }
+    // 0b. Posture: requireExplicitRule with no matching auto-approve rule
+    if (posture && posture.requireExplicitRule) {
+        const hasExplicitRule = rules.some(rule => {
+            if (rule.action !== "auto-approve")
+                return false;
+            const pattern = (0, patterns_1.parsePattern)(rule.pattern);
+            return (0, patterns_1.matchPattern)(pattern, breakpointId, attributes);
+        });
+        if (!hasExplicitRule) {
+            return {
+                recommended: false,
+                reason: `Category '${effectiveCategory}' requires an explicit auto-approve rule (posture: ${posture.name})`,
+                consecutiveApprovals,
+                blockedByPosture: true,
+                effectiveCategory,
+            };
+        }
+    }
+    // 1. Check never-auto-approve rules (highest explicit rule precedence)
+    for (const rule of rules) {
+        if (rule.action !== "never-auto-approve")
+            continue;
+        const pattern = (0, patterns_1.parsePattern)(rule.pattern);
+        if ((0, patterns_1.matchPattern)(pattern, breakpointId, attributes)) {
+            return {
+                recommended: false,
+                reason: `Blocked by never-auto-approve rule: ${rule.id}`,
+                matchedRule: rule.id,
+                consecutiveApprovals,
+                effectiveCategory,
+            };
+        }
+    }
+    // 2. Check alwaysBreakOn profile tags
+    if (profileConfig?.alwaysBreakOn && tags) {
+        for (const alwaysTag of profileConfig.alwaysBreakOn) {
+            if (tags.includes(alwaysTag)) {
+                return {
+                    recommended: false,
+                    reason: `Blocked by alwaysBreakOn tag: ${alwaysTag}`,
+                    consecutiveApprovals,
+                    effectiveCategory,
+                };
+            }
+        }
+    }
+    // 3. Check auto-approve rules
+    for (const rule of rules) {
+        if (rule.action !== "auto-approve")
+            continue;
+        const pattern = (0, patterns_1.parsePattern)(rule.pattern);
+        if ((0, patterns_1.matchPattern)(pattern, breakpointId, attributes)) {
+            return {
+                recommended: true,
+                reason: `Matched auto-approve rule: ${rule.id}`,
+                matchedRule: rule.id,
+                consecutiveApprovals,
+                effectiveCategory,
+            };
+        }
+    }
+    // 4. Check autoApproveAfterN threshold (clamped by posture)
+    if (posture && posture.minConsecutiveApprovalsForAutoN === -1) {
+        // Posture disables autoApproveAfterN entirely
+        autoApproveAfterN = -1;
+    }
+    else if (posture && autoApproveAfterN > 0) {
+        // Clamp threshold to at least posture minimum
+        autoApproveAfterN = Math.max(autoApproveAfterN, posture.minConsecutiveApprovalsForAutoN);
+    }
+    if (autoApproveAfterN > 0 && consecutiveApprovals >= autoApproveAfterN) {
+        return {
+            recommended: true,
+            reason: `Auto-approved after ${consecutiveApprovals} consecutive approvals (threshold: ${autoApproveAfterN})`,
+            consecutiveApprovals,
+            effectiveCategory,
+        };
+    }
+    // 5. Default: prompt (no auto-approval)
+    return {
+        recommended: false,
+        reason: "No matching auto-approval rule",
+        consecutiveApprovals,
+        effectiveCategory,
+    };
+}

package/dist/breakpoints/index.d.ts

@@ -0,0 +1,9 @@
+export type { BreakpointRule, BreakpointRuleAction, BreakpointRulesFile, AutoApprovalResult, BreakpointPattern, AttributePredicate, PredicateOp, InteractionKind, ActionCategory, ApprovalPosture, } from "./types";
+export { BREAKPOINT_RULES_SCHEMA_VERSION } from "./types";
+export { parsePattern, matchPattern } from "./patterns";
+export { readRules, writeRules, addRule, removeRule, listRules } from "./rules";
+export { evaluateAutoApproval } from "./evaluator";
+export type { EvaluateAutoApprovalOptions } from "./evaluator";
+export { verifyBreakpointResult, hasSignatureFields } from "./proven-verification";
+export type { BreakpointVerificationConfig, BreakpointVerificationResult, } from "./proven-verification";
+//# sourceMappingURL=index.d.ts.map

package/dist/breakpoints/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/breakpoints/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,GAChB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,+BAA+B,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACnF,YAAY,EACV,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC"}

package/dist/breakpoints/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasSignatureFields = exports.verifyBreakpointResult = exports.evaluateAutoApproval = exports.listRules = exports.removeRule = exports.addRule = exports.writeRules = exports.readRules = exports.matchPattern = exports.parsePattern = exports.BREAKPOINT_RULES_SCHEMA_VERSION = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "BREAKPOINT_RULES_SCHEMA_VERSION", { enumerable: true, get: function () { return types_1.BREAKPOINT_RULES_SCHEMA_VERSION; } });
+var patterns_1 = require("./patterns");
+Object.defineProperty(exports, "parsePattern", { enumerable: true, get: function () { return patterns_1.parsePattern; } });
+Object.defineProperty(exports, "matchPattern", { enumerable: true, get: function () { return patterns_1.matchPattern; } });
+var rules_1 = require("./rules");
+Object.defineProperty(exports, "readRules", { enumerable: true, get: function () { return rules_1.readRules; } });
+Object.defineProperty(exports, "writeRules", { enumerable: true, get: function () { return rules_1.writeRules; } });
+Object.defineProperty(exports, "addRule", { enumerable: true, get: function () { return rules_1.addRule; } });
+Object.defineProperty(exports, "removeRule", { enumerable: true, get: function () { return rules_1.removeRule; } });
+Object.defineProperty(exports, "listRules", { enumerable: true, get: function () { return rules_1.listRules; } });
+var evaluator_1 = require("./evaluator");
+Object.defineProperty(exports, "evaluateAutoApproval", { enumerable: true, get: function () { return evaluator_1.evaluateAutoApproval; } });
+var proven_verification_1 = require("./proven-verification");
+Object.defineProperty(exports, "verifyBreakpointResult", { enumerable: true, get: function () { return proven_verification_1.verifyBreakpointResult; } });
+Object.defineProperty(exports, "hasSignatureFields", { enumerable: true, get: function () { return proven_verification_1.hasSignatureFields; } });

package/dist/breakpoints/patterns.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pattern parsing and matching for breakpoint auto-approval rules.
+ *
+ * Pattern syntax:
+ *   <id-glob>                          — e.g., "confirm.*"
+ *   <id-glob>(<predicate> [AND ...])   — e.g., "*.review(tags contains 'design')"
+ *
+ * Id-glob supports * as a wildcard matching any segment(s).
+ * Attribute predicates: "tags contains '<value>'" or "expert = '<value>'"
+ * Multiple predicates joined with AND.
+ */
+import type { BreakpointPattern } from "./types";
+/**
+ * Parse a pattern string into a structured BreakpointPattern.
+ */
+export declare function parsePattern(raw: string): BreakpointPattern;
+/**
+ * Match a breakpointId and attributes against a parsed pattern.
+ */
+export declare function matchPattern(pattern: BreakpointPattern, breakpointId: string, attributes: {
+    tags?: string[];
+    expert?: string;
+}): boolean;
+//# sourceMappingURL=patterns.d.ts.map

package/dist/breakpoints/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/breakpoints/patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAsB,iBAAiB,EAAe,MAAM,SAAS,CAAC;AAElF;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAsB3D;AAwBD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,iBAAiB,EAC1B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,OAAO,CAYT"}

package/dist/breakpoints/patterns.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Pattern parsing and matching for breakpoint auto-approval rules.
+ *
+ * Pattern syntax:
+ *   <id-glob>                          — e.g., "confirm.*"
+ *   <id-glob>(<predicate> [AND ...])   — e.g., "*.review(tags contains 'design')"
+ *
+ * Id-glob supports * as a wildcard matching any segment(s).
+ * Attribute predicates: "tags contains '<value>'" or "expert = '<value>'"
+ * Multiple predicates joined with AND.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePattern = parsePattern;
+exports.matchPattern = matchPattern;
+/**
+ * Parse a pattern string into a structured BreakpointPattern.
+ */
+function parsePattern(raw) {
+    const trimmed = raw.trim();
+    const parenOpen = trimmed.indexOf("(");
+    if (parenOpen === -1) {
+        return { idGlob: trimmed, predicates: [] };
+    }
+    const parenClose = trimmed.lastIndexOf(")");
+    if (parenClose === -1 || parenClose <= parenOpen) {
+        throw new Error(`Invalid pattern: unmatched parenthesis in "${raw}"`);
+    }
+    const idGlob = trimmed.slice(0, parenOpen).trim();
+    const predicateStr = trimmed.slice(parenOpen + 1, parenClose).trim();
+    if (!predicateStr) {
+        return { idGlob, predicates: [] };
+    }
+    const predicates = parsePredicates(predicateStr);
+    return { idGlob, predicates };
+}
+function parsePredicates(str) {
+    // Split on " AND " (case-insensitive)
+    const parts = str.split(/\s+AND\s+/i);
+    return parts.map(parseSinglePredicate);
+}
+function parseSinglePredicate(str) {
+    const trimmed = str.trim();
+    // Match: attr contains 'value' or attr = 'value'
+    const match = trimmed.match(/^(\w+)\s+(contains|=)\s+'([^']*)'$/);
+    if (!match) {
+        throw new Error(`Invalid predicate: "${trimmed}". Expected: attr contains 'value' or attr = 'value'`);
+    }
+    return {
+        attr: match[1],
+        op: match[2],
+        value: match[3],
+    };
+}
+/**
+ * Match a breakpointId and attributes against a parsed pattern.
+ */
+function matchPattern(pattern, breakpointId, attributes) {
+    if (!matchGlob(pattern.idGlob, breakpointId)) {
+        return false;
+    }
+    for (const pred of pattern.predicates) {
+        if (!matchPredicate(pred, attributes)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Simple glob matching with * wildcards.
+ * Each * matches zero or more characters (including dots).
+ */
+function matchGlob(glob, value) {
+    // Escape regex special chars except *, then replace * with .*
+    const escaped = glob.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    const regexStr = "^" + escaped.replace(/\*/g, ".*") + "$";
+    return new RegExp(regexStr).test(value);
+}
+function matchPredicate(pred, attributes) {
+    if (pred.attr === "tags" && pred.op === "contains") {
+        return Array.isArray(attributes.tags) && attributes.tags.includes(pred.value);
+    }
+    if (pred.attr === "expert" && pred.op === "=") {
+        return attributes.expert === pred.value;
+    }
+    // Unknown attribute — no match
+    return false;
+}

package/dist/breakpoints/proven-verification.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Optional integration with @a5c-ai/breakpoints-mux proven subsystem.
+ *
+ * Provides cryptographic verification of breakpoint answers when the
+ * breakpoints-mux package is available as an optional peer dependency.
+ * Never throws -- always returns a graceful result.
+ */
+/**
+ * Configuration for breakpoint answer verification.
+ */
+export interface BreakpointVerificationConfig {
+    /** Whether verification is enabled. When false, verification is skipped. */
+    enabled: boolean;
+    /** Directory containing trusted public keys. Passed to breakpoints-mux verifyAnswer. */
+    trustedKeysDir?: string;
+}
+/**
+ * Result of a breakpoint answer verification attempt.
+ */
+export interface BreakpointVerificationResult {
+    /** Whether the answer was successfully verified as authentic. */
+    verified: boolean;
+    /** Detailed verification result from breakpoints-mux (when available). */
+    verificationResult?: {
+        valid: boolean;
+        publicKeyFingerprint?: string;
+        responderName?: string;
+        reason?: string;
+        verifiedAt: string;
+    };
+    /** Reason verification was skipped or failed (when verified is false). */
+    reason?: string;
+}
+/**
+ * Check whether a breakpoint result carries signature fields,
+ * indicating it was cryptographically signed via the proven subsystem.
+ */
+export declare function hasSignatureFields(result: Record<string, unknown>): boolean;
+/**
+ * Verify a breakpoint result's cryptographic signature using the
+ * breakpoints-mux proven subsystem.
+ *
+ * This function never throws. If breakpoints-mux is not installed,
+ * verification is disabled, or the result is unsigned, it returns
+ * a graceful { verified: false } result with an explanatory reason.
+ *
+ * @param result - The breakpoint result (may or may not contain signature fields).
+ * @param config - Verification configuration. If omitted, defaults to { enabled: true }.
+ */
+export declare function verifyBreakpointResult(result: Record<string, unknown>, config?: BreakpointVerificationConfig): Promise<BreakpointVerificationResult>;
+//# sourceMappingURL=proven-verification.d.ts.map

package/dist/breakpoints/proven-verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proven-verification.d.ts","sourceRoot":"","sources":["../../src/breakpoints/proven-verification.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,iEAAiE;IACjE,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE;QACnB,KAAK,EAAE,OAAO,CAAC;QACf,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAaD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAI3E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,CAAC,EAAE,4BAA4B,GACpC,OAAO,CAAC,4BAA4B,CAAC,CAuEvC"}

package/dist/breakpoints/proven-verification.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Optional integration with @a5c-ai/breakpoints-mux proven subsystem.
+ *
+ * Provides cryptographic verification of breakpoint answers when the
+ * breakpoints-mux package is available as an optional peer dependency.
+ * Never throws -- always returns a graceful result.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasSignatureFields = hasSignatureFields;
+exports.verifyBreakpointResult = verifyBreakpointResult;
+/**
+ * Signature fields expected on a proven breakpoint result.
+ * If all four are present, the result is considered signed.
+ */
+const SIGNATURE_FIELDS = [
+    "signature",
+    "publicKeyFingerprint",
+    "signedAt",
+    "signedFields",
+];
+/**
+ * Check whether a breakpoint result carries signature fields,
+ * indicating it was cryptographically signed via the proven subsystem.
+ */
+function hasSignatureFields(result) {
+    return SIGNATURE_FIELDS.every((field) => result[field] !== undefined && result[field] !== null);
+}
+/**
+ * Verify a breakpoint result's cryptographic signature using the
+ * breakpoints-mux proven subsystem.
+ *
+ * This function never throws. If breakpoints-mux is not installed,
+ * verification is disabled, or the result is unsigned, it returns
+ * a graceful { verified: false } result with an explanatory reason.
+ *
+ * @param result - The breakpoint result (may or may not contain signature fields).
+ * @param config - Verification configuration. If omitted, defaults to { enabled: true }.
+ */
+async function verifyBreakpointResult(result, config) {
+    const effectiveConfig = config ?? { enabled: true };
+    // Short-circuit if verification is disabled
+    if (!effectiveConfig.enabled) {
+        return { verified: false, reason: "verification disabled" };
+    }
+    // Short-circuit if result does not carry signature fields
+    if (!hasSignatureFields(result)) {
+        return { verified: false, reason: "result is not signed" };
+    }
+    // Attempt to dynamically import breakpoints-mux proven subsystem.
+    // The module is an optional peer dependency -- the import may fail at runtime.
+    // We use a string variable to prevent TypeScript from statically resolving the import.
+    try {
+        const modulePath = "@a5c-ai/breakpoints-mux/proven";
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const proven = await Promise.resolve(`${modulePath}`).then(s => __importStar(require(s)));
+        const { verifyAnswer } = proven;
+        if (typeof verifyAnswer !== "function") {
+            return {
+                verified: false,
+                reason: "breakpoints-mux/proven does not export verifyAnswer",
+            };
+        }
+        const verificationResult = await verifyAnswer(result, effectiveConfig.trustedKeysDir);
+        return {
+            verified: verificationResult.valid === true,
+            verificationResult,
+        };
+    }
+    catch (err) {
+        // Dynamic import failed -- breakpoints-mux is not installed or broken
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("Cannot find module") ||
+            message.includes("MODULE_NOT_FOUND") ||
+            message.includes("ERR_MODULE_NOT_FOUND") ||
+            message.includes("Could not resolve")) {
+            return {
+                verified: false,
+                reason: "breakpoints-mux not installed",
+            };
+        }
+        return {
+            verified: false,
+            reason: `verification failed: ${message}`,
+        };
+    }
+}

package/dist/breakpoints/rules.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Rules CRUD for breakpoint auto-approval.
+ * Rules stored at ~/.a5c/breakpoint-approvals/rules.json with atomic writes.
+ */
+import type { BreakpointRule } from "./types";
+/**
+ * Read rules from the rules file. Returns empty array if file doesn't exist.
+ */
+export declare function readRules(rulesPath?: string): Promise<BreakpointRule[]>;
+/**
+ * Write rules to the rules file atomically.
+ */
+export declare function writeRules(rules: BreakpointRule[], rulesPath?: string): Promise<void>;
+/**
+ * Add a rule. Deduplicates by rule id.
+ */
+export declare function addRule(rule: BreakpointRule, rulesPath?: string): Promise<BreakpointRule[]>;
+/**
+ * Remove a rule by id. Returns the updated list.
+ */
+export declare function removeRule(ruleId: string, rulesPath?: string): Promise<BreakpointRule[]>;
+/**
+ * List all rules.
+ */
+export declare function listRules(rulesPath?: string): Promise<BreakpointRule[]>;
+//# sourceMappingURL=rules.d.ts.map

package/dist/breakpoints/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/breakpoints/rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,SAAS,CAAC;AAOnE;;GAEG;AACH,wBAAsB,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAe7E;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3F;AAED;;GAEG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAMjG;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAK9F;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE7E"}

package/dist/breakpoints/rules.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Rules CRUD for breakpoint auto-approval.
+ * Rules stored at ~/.a5c/breakpoint-approvals/rules.json with atomic writes.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRules = readRules;
+exports.writeRules = writeRules;
+exports.addRule = addRule;
+exports.removeRule = removeRule;
+exports.listRules = listRules;
+const node_fs_1 = require("node:fs");
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const atomic_1 = require("../storage/atomic");
+const types_1 = require("./types");
+function defaultRulesPath() {
+    return path.join(os.homedir(), ".a5c", "breakpoint-approvals", "rules.json");
+}
+/**
+ * Read rules from the rules file. Returns empty array if file doesn't exist.
+ */
+async function readRules(rulesPath) {
+    const filePath = rulesPath ?? defaultRulesPath();
+    try {
+        const raw = await node_fs_1.promises.readFile(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.rules)) {
+            return [];
+        }
+        return parsed.rules;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return [];
+        }
+        throw err;
+    }
+}
+/**
+ * Write rules to the rules file atomically.
+ */
+async function writeRules(rules, rulesPath) {
+    const filePath = rulesPath ?? defaultRulesPath();
+    const dir = path.dirname(filePath);
+    await node_fs_1.promises.mkdir(dir, { recursive: true });
+    const data = {
+        schemaVersion: types_1.BREAKPOINT_RULES_SCHEMA_VERSION,
+        rules,
+    };
+    await (0, atomic_1.writeFileAtomic)(filePath, JSON.stringify(data, null, 2) + "\n");
+}
+/**
+ * Add a rule. Deduplicates by rule id.
+ */
+async function addRule(rule, rulesPath) {
+    const existing = await readRules(rulesPath);
+    const filtered = existing.filter(r => r.id !== rule.id);
+    filtered.push(rule);
+    await writeRules(filtered, rulesPath);
+    return filtered;
+}
+/**
+ * Remove a rule by id. Returns the updated list.
+ */
+async function removeRule(ruleId, rulesPath) {
+    const existing = await readRules(rulesPath);
+    const filtered = existing.filter(r => r.id !== ruleId);
+    await writeRules(filtered, rulesPath);
+    return filtered;
+}
+/**
+ * List all rules.
+ */
+async function listRules(rulesPath) {
+    return readRules(rulesPath);
+}