agentic-flow 2.0.6 → 3.0.0-alpha.1

package/dist/packages/agentdb/src/security/AttestationLog.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ADR-060: Attestation Log
+ *
+ * Append-only audit log for every MutationProof and MutationDenial.
+ * Backed by a better-sqlite3 (or sql.js) compatible database instance.
+ *
+ * The caller is responsible for opening the database and passing it in.
+ * This class only creates the table schema if it does not exist yet.
+ */
+import type { MutationProof, MutationDenial } from './MutationGuard.js';
+export interface DatabaseLike {
+    exec(sql: string): void;
+    prepare(sql: string): {
+        run(...params: unknown[]): {
+            changes?: number;
+        };
+        all(...params: unknown[]): unknown[];
+        get(...params: unknown[]): unknown;
+    };
+}
+export interface AttestationQueryOptions {
+    agentId?: string;
+    namespace?: string;
+    status?: 'proved' | 'denied';
+    since?: number;
+    limit?: number;
+}
+export interface DenialPattern {
+    code: string;
+    count: number;
+    lastSeen: number;
+}
+export interface AttestationStats {
+    total: number;
+    proved: number;
+    denied: number;
+    uniqueAgents: number;
+    oldestTs: number;
+}
+export declare class AttestationLog {
+    private readonly db;
+    constructor(db: DatabaseLike);
+    /**
+     * Record a successful mutation proof.
+     */
+    record(proof: MutationProof): void;
+    /**
+     * Record a denied mutation.
+     */
+    recordDenial(denial: MutationDenial, agentId: string, namespace: string): void;
+    /**
+     * Query attestation records with optional filters.
+     * All filters use parameterized queries to prevent injection.
+     */
+    query(opts?: AttestationQueryOptions): any[];
+    /**
+     * Aggregate denial patterns grouped by denial_code.
+     */
+    getDenialPatterns(since?: number): DenialPattern[];
+    /**
+     * Delete attestation records older than the given age in milliseconds.
+     * Returns the number of deleted rows.
+     */
+    prune(olderThanMs: number): number;
+    /**
+     * Summary statistics for the attestation log.
+     */
+    getStats(): AttestationStats;
+}
+//# sourceMappingURL=AttestationLog.d.ts.map

package/dist/packages/agentdb/src/security/AttestationLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttestationLog.d.ts","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/security/AttestationLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMxE,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG;YAAE,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAChD,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;QACrC,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;KACpC,CAAC;CACH;AAgCD,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;gBAEtB,EAAE,EAAE,YAAY;IAW5B;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAmBlC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAmB9E;;;OAGG;IACH,KAAK,CAAC,IAAI,GAAE,uBAA4B,GAAG,GAAG,EAAE;IAuChD;;OAEG;IACH,iBAAiB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE;IAgClD;;;OAGG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAQlC;;OAEG;IACH,QAAQ,IAAI,gBAAgB;CAmB7B"}

package/dist/packages/agentdb/src/security/AttestationLog.js

@@ -0,0 +1,174 @@
+/**
+ * ADR-060: Attestation Log
+ *
+ * Append-only audit log for every MutationProof and MutationDenial.
+ * Backed by a better-sqlite3 (or sql.js) compatible database instance.
+ *
+ * The caller is responsible for opening the database and passing it in.
+ * This class only creates the table schema if it does not exist yet.
+ */
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const CREATE_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS mutation_attestations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL DEFAULT (strftime('%s','now')),
+  operation TEXT NOT NULL,
+  proof_hash TEXT,
+  agent_id TEXT NOT NULL,
+  namespace TEXT NOT NULL DEFAULT 'default',
+  status TEXT NOT NULL CHECK (status IN ('proved','denied')),
+  denial_reason TEXT,
+  denial_code TEXT,
+  wasm_proof_id INTEGER,
+  metadata TEXT
+);
+`;
+const CREATE_INDEXES_SQL = `
+CREATE INDEX IF NOT EXISTS idx_attestations_ts ON mutation_attestations(ts);
+CREATE INDEX IF NOT EXISTS idx_attestations_agent ON mutation_attestations(agent_id);
+CREATE INDEX IF NOT EXISTS idx_attestations_status ON mutation_attestations(status);
+`;
+// ---------------------------------------------------------------------------
+// AttestationLog
+// ---------------------------------------------------------------------------
+export class AttestationLog {
+    db;
+    constructor(db) {
+        this.db = db;
+        try {
+            this.db.exec(CREATE_TABLE_SQL);
+            this.db.exec(CREATE_INDEXES_SQL);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`AttestationLog schema creation failed: ${msg}`);
+        }
+    }
+    /**
+     * Record a successful mutation proof.
+     */
+    record(proof) {
+        const stmt = this.db.prepare(`
+      INSERT INTO mutation_attestations
+        (ts, operation, proof_hash, agent_id, namespace, status, wasm_proof_id, metadata)
+      VALUES
+        (?, ?, ?, ?, ?, 'proved', ?, ?)
+    `);
+        const ts = Math.floor(proof.timestamp / 1000);
+        stmt.run(ts, proof.operation, proof.structuralHash, proof.attestation.agentId, proof.attestation.namespace, proof.wasmProofId ?? null, JSON.stringify({ invariantChecks: proof.invariantChecks }));
+    }
+    /**
+     * Record a denied mutation.
+     */
+    recordDenial(denial, agentId, namespace) {
+        const stmt = this.db.prepare(`
+      INSERT INTO mutation_attestations
+        (ts, operation, agent_id, namespace, status, denial_reason, denial_code, metadata)
+      VALUES
+        (?, ?, ?, ?, 'denied', ?, ?, ?)
+    `);
+        const ts = Math.floor(denial.timestamp / 1000);
+        stmt.run(ts, denial.operation, agentId, namespace, denial.reason, denial.code, denial.field ? JSON.stringify({ field: denial.field }) : null);
+    }
+    /**
+     * Query attestation records with optional filters.
+     * All filters use parameterized queries to prevent injection.
+     */
+    query(opts = {}) {
+        const conditions = [];
+        const params = [];
+        if (opts.agentId !== undefined) {
+            conditions.push('agent_id = ?');
+            params.push(opts.agentId);
+        }
+        if (opts.namespace !== undefined) {
+            conditions.push('namespace = ?');
+            params.push(opts.namespace);
+        }
+        if (opts.status !== undefined) {
+            conditions.push('status = ?');
+            params.push(opts.status);
+        }
+        if (opts.since !== undefined) {
+            conditions.push('ts >= ?');
+            params.push(Math.floor(opts.since / 1000));
+        }
+        const where = conditions.length > 0
+            ? `WHERE ${conditions.join(' AND ')}`
+            : '';
+        const limit = opts.limit !== undefined && opts.limit > 0
+            ? `LIMIT ?`
+            : '';
+        if (limit) {
+            params.push(opts.limit);
+        }
+        const sql = `SELECT * FROM mutation_attestations ${where} ORDER BY ts DESC ${limit}`;
+        return this.db.prepare(sql).all(...params);
+    }
+    /**
+     * Aggregate denial patterns grouped by denial_code.
+     */
+    getDenialPatterns(since) {
+        let sql;
+        const params = [];
+        if (since !== undefined) {
+            sql = `
+        SELECT
+          denial_code AS code,
+          COUNT(*) AS count,
+          MAX(ts) AS lastSeen
+        FROM mutation_attestations
+        WHERE status = 'denied' AND ts >= ?
+        GROUP BY denial_code
+        ORDER BY count DESC
+      `;
+            params.push(Math.floor(since / 1000));
+        }
+        else {
+            sql = `
+        SELECT
+          denial_code AS code,
+          COUNT(*) AS count,
+          MAX(ts) AS lastSeen
+        FROM mutation_attestations
+        WHERE status = 'denied'
+        GROUP BY denial_code
+        ORDER BY count DESC
+      `;
+        }
+        return this.db.prepare(sql).all(...params);
+    }
+    /**
+     * Delete attestation records older than the given age in milliseconds.
+     * Returns the number of deleted rows.
+     */
+    prune(olderThanMs) {
+        const cutoffTs = Math.floor((Date.now() - olderThanMs) / 1000);
+        const result = this.db.prepare('DELETE FROM mutation_attestations WHERE ts < ?').run(cutoffTs);
+        return result.changes ?? 0;
+    }
+    /**
+     * Summary statistics for the attestation log.
+     */
+    getStats() {
+        const row = this.db.prepare(`
+      SELECT
+        COUNT(*) AS total,
+        SUM(CASE WHEN status = 'proved' THEN 1 ELSE 0 END) AS proved,
+        SUM(CASE WHEN status = 'denied' THEN 1 ELSE 0 END) AS denied,
+        COUNT(DISTINCT agent_id) AS uniqueAgents,
+        MIN(ts) AS oldestTs
+      FROM mutation_attestations
+    `).get();
+        return {
+            total: row?.total ?? 0,
+            proved: row?.proved ?? 0,
+            denied: row?.denied ?? 0,
+            uniqueAgents: row?.uniqueAgents ?? 0,
+            oldestTs: row?.oldestTs ?? 0,
+        };
+    }
+}
+//# sourceMappingURL=AttestationLog.js.map

package/dist/packages/agentdb/src/security/AttestationLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttestationLog.js","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/security/AttestationLog.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ADR-060: Attestation Log\n *\n * Append-only audit log for every MutationProof and MutationDenial.\n * Backed by a better-sqlite3 (or sql.js) compatible database instance.\n *\n * The caller is responsible for opening the database and passing it in.\n * This class only creates the table schema if it does not exist yet.\n */\n\nimport type { MutationProof, MutationDenial } from './MutationGuard.js';\n\n// ---------------------------------------------------------------------------\n// Database interface\n// ---------------------------------------------------------------------------\n\nexport interface DatabaseLike {\n  exec(sql: string): void;\n  prepare(sql: string): {\n    run(...params: unknown[]): { changes?: number };\n    all(...params: unknown[]): unknown[];\n    get(...params: unknown[]): unknown;\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Schema\n// ---------------------------------------------------------------------------\n\nconst CREATE_TABLE_SQL = `\nCREATE TABLE IF NOT EXISTS mutation_attestations (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  ts INTEGER NOT NULL DEFAULT (strftime('%s','now')),\n  operation TEXT NOT NULL,\n  proof_hash TEXT,\n  agent_id TEXT NOT NULL,\n  namespace TEXT NOT NULL DEFAULT 'default',\n  status TEXT NOT NULL CHECK (status IN ('proved','denied')),\n  denial_reason TEXT,\n  denial_code TEXT,\n  wasm_proof_id INTEGER,\n  metadata TEXT\n);\n`;\n\nconst CREATE_INDEXES_SQL = `\nCREATE INDEX IF NOT EXISTS idx_attestations_ts ON mutation_attestations(ts);\nCREATE INDEX IF NOT EXISTS idx_attestations_agent ON mutation_attestations(agent_id);\nCREATE INDEX IF NOT EXISTS idx_attestations_status ON mutation_attestations(status);\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface AttestationQueryOptions {\n  agentId?: string;\n  namespace?: string;\n  status?: 'proved' | 'denied';\n  since?: number;\n  limit?: number;\n}\n\nexport interface DenialPattern {\n  code: string;\n  count: number;\n  lastSeen: number;\n}\n\nexport interface AttestationStats {\n  total: number;\n  proved: number;\n  denied: number;\n  uniqueAgents: number;\n  oldestTs: number;\n}\n\n// ---------------------------------------------------------------------------\n// AttestationLog\n// ---------------------------------------------------------------------------\n\nexport class AttestationLog {\n  private readonly db: DatabaseLike;\n\n  constructor(db: DatabaseLike) {\n    this.db = db;\n    try {\n      this.db.exec(CREATE_TABLE_SQL);\n      this.db.exec(CREATE_INDEXES_SQL);\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new Error(`AttestationLog schema creation failed: ${msg}`);\n    }\n  }\n\n  /**\n   * Record a successful mutation proof.\n   */\n  record(proof: MutationProof): void {\n    const stmt = this.db.prepare(`\n      INSERT INTO mutation_attestations\n        (ts, operation, proof_hash, agent_id, namespace, status, wasm_proof_id, metadata)\n      VALUES\n        (?, ?, ?, ?, ?, 'proved', ?, ?)\n    `);\n    const ts = Math.floor(proof.timestamp / 1000);\n    stmt.run(\n      ts,\n      proof.operation,\n      proof.structuralHash,\n      proof.attestation.agentId,\n      proof.attestation.namespace,\n      proof.wasmProofId ?? null,\n      JSON.stringify({ invariantChecks: proof.invariantChecks }),\n    );\n  }\n\n  /**\n   * Record a denied mutation.\n   */\n  recordDenial(denial: MutationDenial, agentId: string, namespace: string): void {\n    const stmt = this.db.prepare(`\n      INSERT INTO mutation_attestations\n        (ts, operation, agent_id, namespace, status, denial_reason, denial_code, metadata)\n      VALUES\n        (?, ?, ?, ?, 'denied', ?, ?, ?)\n    `);\n    const ts = Math.floor(denial.timestamp / 1000);\n    stmt.run(\n      ts,\n      denial.operation,\n      agentId,\n      namespace,\n      denial.reason,\n      denial.code,\n      denial.field ? JSON.stringify({ field: denial.field }) : null,\n    );\n  }\n\n  /**\n   * Query attestation records with optional filters.\n   * All filters use parameterized queries to prevent injection.\n   */\n  query(opts: AttestationQueryOptions = {}): any[] {\n    const conditions: string[] = [];\n    const params: any[] = [];\n\n    if (opts.agentId !== undefined) {\n      conditions.push('agent_id = ?');\n      params.push(opts.agentId);\n    }\n\n    if (opts.namespace !== undefined) {\n      conditions.push('namespace = ?');\n      params.push(opts.namespace);\n    }\n\n    if (opts.status !== undefined) {\n      conditions.push('status = ?');\n      params.push(opts.status);\n    }\n\n    if (opts.since !== undefined) {\n      conditions.push('ts >= ?');\n      params.push(Math.floor(opts.since / 1000));\n    }\n\n    const where = conditions.length > 0\n      ? `WHERE ${conditions.join(' AND ')}`\n      : '';\n\n    const limit = opts.limit !== undefined && opts.limit > 0\n      ? `LIMIT ?`\n      : '';\n    if (limit) {\n      params.push(opts.limit);\n    }\n\n    const sql = `SELECT * FROM mutation_attestations ${where} ORDER BY ts DESC ${limit}`;\n    return this.db.prepare(sql).all(...params);\n  }\n\n  /**\n   * Aggregate denial patterns grouped by denial_code.\n   */\n  getDenialPatterns(since?: number): DenialPattern[] {\n    let sql: string;\n    const params: any[] = [];\n\n    if (since !== undefined) {\n      sql = `\n        SELECT\n          denial_code AS code,\n          COUNT(*) AS count,\n          MAX(ts) AS lastSeen\n        FROM mutation_attestations\n        WHERE status = 'denied' AND ts >= ?\n        GROUP BY denial_code\n        ORDER BY count DESC\n      `;\n      params.push(Math.floor(since / 1000));\n    } else {\n      sql = `\n        SELECT\n          denial_code AS code,\n          COUNT(*) AS count,\n          MAX(ts) AS lastSeen\n        FROM mutation_attestations\n        WHERE status = 'denied'\n        GROUP BY denial_code\n        ORDER BY count DESC\n      `;\n    }\n\n    return this.db.prepare(sql).all(...params) as DenialPattern[];\n  }\n\n  /**\n   * Delete attestation records older than the given age in milliseconds.\n   * Returns the number of deleted rows.\n   */\n  prune(olderThanMs: number): number {\n    const cutoffTs = Math.floor((Date.now() - olderThanMs) / 1000);\n    const result = this.db.prepare(\n      'DELETE FROM mutation_attestations WHERE ts < ?',\n    ).run(cutoffTs);\n    return result.changes ?? 0;\n  }\n\n  /**\n   * Summary statistics for the attestation log.\n   */\n  getStats(): AttestationStats {\n    const row = this.db.prepare(`\n      SELECT\n        COUNT(*) AS total,\n        SUM(CASE WHEN status = 'proved' THEN 1 ELSE 0 END) AS proved,\n        SUM(CASE WHEN status = 'denied' THEN 1 ELSE 0 END) AS denied,\n        COUNT(DISTINCT agent_id) AS uniqueAgents,\n        MIN(ts) AS oldestTs\n      FROM mutation_attestations\n    `).get() as Record<string, number> | undefined;\n\n    return {\n      total: row?.total ?? 0,\n      proved: row?.proved ?? 0,\n      denied: row?.denied ?? 0,\n      uniqueAgents: row?.uniqueAgents ?? 0,\n      oldestTs: row?.oldestTs ?? 0,\n    };\n  }\n}\n"]}

package/dist/packages/agentdb/src/security/MutationGuard.d.ts

@@ -0,0 +1,83 @@
+/**
+ * ADR-060: Proof-Gated State Mutation
+ *
+ * MutationGuard is the single validation gate between controllers and backends.
+ * Every mutation must produce a MutationProof before the backend executes it.
+ * If validation fails a MutationDenial is returned instead.
+ * Optional WASM-accelerated proofs via @ruvnet/ruvector-verified-wasm.
+ */
+export interface MutationProof {
+    id: string;
+    operation: 'insert' | 'search' | 'remove' | 'batch_insert' | 'save' | 'load';
+    timestamp: number;
+    structuralHash: string;
+    attestation: AttestationToken;
+    invariantChecks: InvariantResult[];
+    wasmProofId?: number;
+    valid: true;
+}
+export interface AttestationToken {
+    agentId: string;
+    namespace: string;
+    scope: 'read' | 'write' | 'admin';
+    issuedAt: number;
+    expiresAt: number;
+}
+export interface InvariantResult {
+    check: string;
+    passed: boolean;
+}
+export interface MutationDenial {
+    operation: string;
+    reason: string;
+    code: string;
+    field?: string;
+    timestamp: number;
+}
+export interface GuardConfig {
+    dimension: number;
+    maxElements: number;
+    enableWasmProofs: boolean;
+    enableAttestationLog: boolean;
+    defaultNamespace: string;
+}
+export declare class MutationGuard {
+    private readonly config;
+    private vectorCount;
+    private wasmEnv;
+    private wasmAvailable;
+    private engineType;
+    private nextWasmProofId;
+    private proofsIssuedCount;
+    private denialsCount;
+    private proofTimesNs;
+    constructor(config: GuardConfig);
+    initialize(): Promise<void>;
+    private validateToken;
+    proveInsert(id: string, embedding: Float32Array, metadata?: Record<string, any>, token?: AttestationToken): MutationProof | MutationDenial;
+    proveSearch(query: Float32Array, k: number, options?: any, token?: AttestationToken): MutationProof | MutationDenial;
+    proveBatchInsert(items: Array<{
+        id: string;
+        embedding: Float32Array;
+        metadata?: Record<string, any>;
+    }>, token?: AttestationToken): MutationProof | MutationDenial;
+    proveRemove(id: string, token?: AttestationToken): MutationProof | MutationDenial;
+    proveSave(path: string, token?: AttestationToken): MutationProof | MutationDenial;
+    proveLoad(path: string, token?: AttestationToken): MutationProof | MutationDenial;
+    createToken(agentId: string, namespace: string, scope: 'read' | 'write' | 'admin', ttlMs?: number): AttestationToken;
+    getStats(): {
+        proofsIssued: number;
+        denials: number;
+        wasmAvailable: boolean;
+        engineType: string;
+        avgProofTimeNs: number;
+    };
+    static isDenial(result: MutationProof | MutationDenial): result is MutationDenial;
+    getVectorCount(): number;
+    setVectorCount(count: number): void;
+    private buildProof;
+    private validateSafePath;
+    private hrtimeNs;
+    private recordProofTime;
+}
+//# sourceMappingURL=MutationGuard.d.ts.map

package/dist/packages/agentdb/src/security/MutationGuard.d.ts.map

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