shieldcortex 4.38.0 → 4.40.0

package/dist/memory/store.js

@@ -21,7 +21,7 @@ import { syncMemoryDeleteToCloud, syncMemoryUpsertToCloud } from '../cloud/memor
 import { isFeatureEnabled } from '../license/gate.js';
 import { checkAccess } from '../defence/trust/access-control.js';
 import { scoreSource } from '../defence/trust/source-scorer.js';
-import { logAudit } from '../defence/audit/logger.js';
+import { logAudit, createContentHash } from '../defence/audit/logger.js';
 import { dispatchWebhook } from '../events/webhooks.js';
 import { safeJsonParse } from './fts.js';
 // Internal use of the link API. links.ts also imports from store.ts (getMemoryById,
@@ -230,7 +230,7 @@ function checkRateLimit(source) {
 // ── Read-Time Access Control ──
 // Exported because search-recall.ts also calls logAccessDenial inside its
 // post-search ACL filter (cycle artifact, not intended public API).
-export function logAccessDenial(memoryId, source, reason) {
+export function logAccessDenial(memoryId, source, reason, operation = 'read') {
     const trust = scoreSource(source).score;
     logAudit({
         memory_id: memoryId,
@@ -241,6 +241,7 @@ export function logAccessDenial(memoryId, source, reason) {
         trust_score: trust,
         sensitivity_level: 'INTERNAL',
         firewall_result: 'BLOCK',
+        operation,
         anomaly_score: 0,
         threat_indicators: '[]',
         blocked_patterns: '[]',
@@ -249,6 +250,58 @@ export function logAccessDenial(memoryId, source, reason) {
         pipeline_duration_ms: 0,
     });
 }
+/**
+ * Provenance ledger: record an ALLOWED read. Emitted ONCE per tool call (not per
+ * row) to keep the audit table bounded — recall returns up to 50 rows, so a
+ * per-row emit would flood it. memory_id carries the single id for single-target
+ * reads; the full id list (capped) goes in blocked_patterns for forensics.
+ */
+export function logAllowedRead(source, tool, memoryIds, project) {
+    if (memoryIds.length === 0)
+        return;
+    logAudit({
+        memory_id: memoryIds.length === 1 ? memoryIds[0] : null,
+        project: project ?? null,
+        timestamp: new Date().toISOString(),
+        source_type: source.type,
+        source_identifier: source.identifier,
+        trust_score: scoreSource(source).score,
+        sensitivity_level: 'INTERNAL',
+        firewall_result: 'ALLOW',
+        operation: 'read',
+        anomaly_score: 0,
+        threat_indicators: '[]',
+        blocked_patterns: JSON.stringify(memoryIds.slice(0, 50)),
+        reason: `read ${memoryIds.length} memor${memoryIds.length === 1 ? 'y' : 'ies'} via ${tool}`,
+        fragmentation_score: null,
+        pipeline_duration_ms: null,
+    });
+}
+/**
+ * Provenance ledger: record an ALLOWED delete (one row per deleted memory).
+ * memory_id is NULL by design — the row is emitted after the DELETE, and the
+ * audit.memory_id FK is ON DELETE SET NULL, so a live reference can't survive.
+ * The deleted id is preserved in `reason` + `blocked_patterns` for forensics.
+ */
+export function logAllowedDelete(memoryId, source, project, operation = 'delete') {
+    logAudit({
+        memory_id: null,
+        project: project ?? null,
+        timestamp: new Date().toISOString(),
+        source_type: source.type,
+        source_identifier: source.identifier,
+        trust_score: scoreSource(source).score,
+        sensitivity_level: 'INTERNAL',
+        firewall_result: 'ALLOW',
+        operation,
+        anomaly_score: 0,
+        threat_indicators: '[]',
+        blocked_patterns: JSON.stringify([memoryId]),
+        reason: `deleted memory #${memoryId}`,
+        fragmentation_score: null,
+        pipeline_duration_ms: null,
+    });
+}
 /**
  * Filter raw DB rows by access control before converting to Memory objects.
  * Returns only rows the source is allowed to read.
@@ -324,6 +377,7 @@ export function addMemory(input, config = DEFAULT_CONFIG, source) {
             trust_score: scoreSource(source).score,
             sensitivity_level: 'INTERNAL',
             firewall_result: 'BLOCK',
+            operation: 'write',
             anomaly_score: 1.0,
             threat_indicators: JSON.stringify(['rate_limit_exceeded']),
             blocked_patterns: '[]',
@@ -413,8 +467,11 @@ export function addMemory(input, config = DEFAULT_CONFIG, source) {
         // defenceResult is always set now (every write is scanned), so always stamp
         // the pipeline's real trust + sensitivity alongside the resolved source —
         // no source-less branch can default to trust 1.0 / unscanned INTERNAL.
-        db.prepare(`UPDATE memories SET trust_score = ?, sensitivity_level = ?, source = ? WHERE id = ?`)
-            .run(defenceResult.trust.score, defenceResult.sensitivity.level, sourceDetails.sourceValue, result.lastInsertRowid);
+        db.prepare(`UPDATE memories SET trust_score = ?, sensitivity_level = ?, source = ?, content_hash = ? WHERE id = ?`)
+            // content_hash = SHA-256 of the SUBMITTED content (a write-time provenance
+            // snapshot), matching the write-audit row in pipeline.ts. Consistent for
+            // >10KB memories too (where the STORED content is truncated).
+            .run(defenceResult.trust.score, defenceResult.sensitivity.level, sourceDetails.sourceValue, createContentHash(input.content), result.lastInsertRowid);
         return result.lastInsertRowid;
     })();
     const memory = getMemoryById(insertedId);
@@ -701,6 +758,14 @@ export function updateMemory(id, updates) {
     if (embeddedTextChanged) {
         fields.push('embedding = NULL');
     }
+    // STALENESS: content_hash is a write-time integrity snapshot. When content
+    // changes it must be recomputed in the SAME UPDATE — otherwise the stored hash
+    // refers to the old content and any tamper check false-positives on a
+    // legitimately-edited memory.
+    if (updates.content !== undefined) {
+        fields.push('content_hash = ?');
+        values.push(createContentHash(updates.content));
+    }
     if (fields.length === 0)
         return existing;
     values.push(id);
@@ -721,6 +786,28 @@ export function updateMemory(id, updates) {
             console.error('[shieldcortex] Entity extraction refresh failed:', e);
         }
     }
+    // Provenance ledger: a content/title change is an update-class mutation.
+    if (updates.content !== undefined || updates.title !== undefined) {
+        const changed = [updates.title !== undefined ? 'title' : null, updates.content !== undefined ? 'content' : null].filter(Boolean).join('+');
+        logAudit({
+            memory_id: id,
+            project: updatedMemory.project ?? null,
+            timestamp: new Date().toISOString(),
+            source_type: 'cli',
+            source_identifier: 'memory-update',
+            trust_score: updatedMemory.trustScore ?? 1,
+            sensitivity_level: updatedMemory.sensitivityLevel ?? 'INTERNAL',
+            firewall_result: 'ALLOW',
+            operation: 'update',
+            content_hash: updates.content !== undefined ? createContentHash(updates.content) : null,
+            anomaly_score: 0,
+            threat_indicators: '[]',
+            blocked_patterns: '[]',
+            reason: `updated memory #${id} (${changed})`,
+            fragmentation_score: null,
+            pipeline_duration_ms: null,
+        });
+    }
     // Emit event for real-time dashboard (in-process)
     emitMemoryUpdated(updatedMemory);
     // Persist event for cross-process IPC (MCP → Dashboard)
@@ -804,6 +891,7 @@ export function mergeMemories(keptId, removedId, options, source = { type: 'cli'
         db.prepare(`
       UPDATE memories
       SET content = ?,
+          content_hash = ?,
           tags = ?,
           salience = ?,
           project = ?,
@@ -822,7 +910,7 @@ export function mergeMemories(keptId, removedId, options, source = { type: 'cli'
           embedding = NULL,
           updated_at = CURRENT_TIMESTAMP
       WHERE id = ?
-    `).run(mergedContent, JSON.stringify(mergedTags), mergedSalience, mergedProject, JSON.stringify(mergedMetadata), mergedScope, mergedTransferable ? 1 : 0, mergedStatus, mergedPinned ? 1 : 0, mergedReviewedBy, new Date().toISOString(), mergedTrustScore, mergedSensitivity, mergedCloudExcluded ? 1 : 0, mergedAccessCount, mergedLastAccessed, kept.id);
+    `).run(mergedContent, createContentHash(mergedContent), JSON.stringify(mergedTags), mergedSalience, mergedProject, JSON.stringify(mergedMetadata), mergedScope, mergedTransferable ? 1 : 0, mergedStatus, mergedPinned ? 1 : 0, mergedReviewedBy, new Date().toISOString(), mergedTrustScore, mergedSensitivity, mergedCloudExcluded ? 1 : 0, mergedAccessCount, mergedLastAccessed, kept.id);
         const updatedMemory = getMemoryById(kept.id);
         try {
             const extraction = extractFromMemory(updatedMemory.title, updatedMemory.content, updatedMemory.category);
@@ -848,15 +936,17 @@ export function mergeMemories(keptId, removedId, options, source = { type: 'cli'
 /**
  * Delete a memory
  */
-export function deleteMemory(id, source) {
+export function deleteMemory(id, source, opts) {
     const db = getDatabase();
-    // ACCESS CONTROL: Check delete permission
+    const aclOp = opts?.mode ?? 'delete';
+    // ACCESS CONTROL: Check delete permission. mode 'revoke' uses the
+    // trust-hierarchy rule (own OR outrank); 'delete' (default) stays own-only.
     if (source) {
         const row = db.prepare('SELECT id, source, sensitivity_level FROM memories WHERE id = ?').get(id);
         if (row) {
-            const policy = checkAccess({ id: row.id, source: row.source, sensitivity_level: row.sensitivity_level }, source, 'delete');
+            const policy = checkAccess({ id: row.id, source: row.source, sensitivity_level: row.sensitivity_level }, source, aclOp);
             if (!policy.canDelete) {
-                logAccessDenial(id, source, policy.reason);
+                logAccessDenial(id, source, policy.reason, aclOp);
                 return false;
             }
         }
@@ -874,6 +964,12 @@ export function deleteMemory(id, source) {
     const result = db.prepare('DELETE FROM memories WHERE id = ?').run(id);
     // Emit event for real-time dashboard (in-process)
     if (result.changes > 0 && memory) {
+        // Provenance ledger: record the allowed delete (one row per memory) when the
+        // caller is attributed. Internal source-less deletes (merge/consolidation)
+        // are machinery, not user actions, so they're not audited here.
+        if (source) {
+            logAllowedDelete(id, source, memory.project ?? null, aclOp);
+        }
         if (isFeatureEnabled('cloud_sync')) {
             syncMemoryDeleteToCloud(memory);
             syncGraphDeleteForMemoryToCloud(memory);

package/dist/server.js

@@ -23,6 +23,7 @@ import { checkDatabaseSize } from './database/init.js';
 import { queryAuditLogs, getAuditStats, getLifetimeStats } from './defence/audit/index.js';
 import { scanExistingMemories } from './defence/scanner/index.js';
 import { resolveToolSource as resolveToolSourceImpl } from './defence/trust/resolve-tool-source.js';
+import { inferSourceFromEnvironment } from './defence/trust/env-detector.js';
 import { scanToolResponse, shouldScanToolResponse } from './defence/tool-response-scanner.js';
 import { UNTRUSTED_TOOL_TAG } from './defence/tool-response-enforce.js';
 import { guardReadBySensitivity, guardContextSummary } from './defence/trust/read-guard.js';
@@ -287,8 +288,15 @@ Modes: search (query-based), recent (by time), important (by salience)`, {
         confirm: z.boolean().optional().default(false)
             .describe('Confirm bulk delete'),
         source: sourceParam,
+        fromSource: z.string().optional()
+            .describe('Revoke-by-source: delete all memories written by this source ("type:identifier", or "type:*" for a whole type). Authorised by the trust-hierarchy revoke ACL (own the source or outrank it). Use project:"*" to revoke across all projects.'),
     }, { title: 'Delete Memories', readOnlyHint: false, destructiveHint: true, idempotentHint: false }, withKillSwitchGuard('memory_write', async (args) => {
-        const source = resolveToolSource(args.source, 'forget');
+        // Delete is destructive, and revoke-by-source grants cross-identity power,
+        // so the caller identity MUST be the unspoofable runtime identity — derive
+        // it from the environment, NOT the MCP-declared `source` param. Honouring a
+        // declared identity would let a caller claim ownership of any peer source's
+        // memories (the clamp only caps trust SCORE, not identity).
+        const source = inferSourceFromEnvironment().source;
         const result = await executeForget({ ...args, source });
         return {
             content: [{ type: 'text', text: formatForgetResult(result) }],

package/dist/tools/context.js

@@ -6,7 +6,7 @@
  */
 import { z } from 'zod';
 import { generateContextSummary, formatContextSummary, startSession, endSession, getSuggestedContext, consolidate, previewConsolidation, exportMemories, importMemories, } from '../memory/consolidate.js';
-import { getMemoryStats } from '../memory/store.js';
+import { getMemoryStats, logAllowedRead } from '../memory/store.js';
 import { getSalienceDistribution } from '../memory/metrics.js';
 import { getDatabase } from '../database/init.js';
 import { resolveProject } from '../context/project-context.js';
@@ -61,6 +61,16 @@ export async function executeGetContext(input) {
                 }
                 break;
         }
+        // Provenance ledger: one allowed-read row per get_context call, covering
+        // every memory surfaced into the context.
+        const source = input.source;
+        if (source) {
+            const surfacedIds = [
+                ...summary.recentMemories, ...summary.keyDecisions,
+                ...summary.activePatterns, ...summary.pendingItems, ...relevantMemories,
+            ].map(m => m.id);
+            logAllowedRead(source, 'get_context', [...new Set(surfacedIds)], projectFilter);
+        }
         return {
             success: true,
             context,
@@ -270,6 +280,10 @@ export function executeExport(input) {
         // Read ACL: filter the bulk dump to rows this caller may read.
         const data = exportMemories(projectFilter, input.source);
         const memories = JSON.parse(data);
+        // Provenance ledger: a bulk export is the highest-value read to audit.
+        if (input.source) {
+            logAllowedRead(input.source, 'export_memories', memories.map(m => m.id), projectFilter);
+        }
         return {
             success: true,
             data,

package/dist/tools/forget.d.ts

@@ -23,6 +23,7 @@ export declare const forgetSchema: z.ZodObject<{
         type: "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "api" | "tool_response";
         identifier: string;
     }>>;
+    fromSource: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     confirm: boolean;
     dryRun: boolean;
@@ -36,6 +37,7 @@ export declare const forgetSchema: z.ZodObject<{
     query?: string | undefined;
     olderThan?: number | undefined;
     belowSalience?: number | undefined;
+    fromSource?: string | undefined;
 }, {
     source?: {
         type: "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "api" | "tool_response";
@@ -49,6 +51,7 @@ export declare const forgetSchema: z.ZodObject<{
     olderThan?: number | undefined;
     belowSalience?: number | undefined;
     dryRun?: boolean | undefined;
+    fromSource?: string | undefined;
 }>;
 export type ForgetInput = z.infer<typeof forgetSchema>;
 /**

package/dist/tools/forget.js

@@ -8,6 +8,13 @@ import { deleteMemory, searchMemories, getMemoryById } from '../memory/store.js'
 import { getDatabase, withTransaction } from '../database/init.js';
 import { MemoryNotFoundError, BulkDeleteSafetyError, formatErrorForMcp, } from '../errors.js';
 import { resolveProject } from '../context/project-context.js';
+import { isRevokeBySourceEnabled } from '../cloud/config.js';
+/**
+ * Upper bound on rows a single revoke-by-source call may delete. Caps the blast
+ * radius of the mass-delete primitive — a larger match must be narrowed (by
+ * project/category/etc.) or paged.
+ */
+const MAX_REVOKE_ROWS = 500;
 // Input schema for the forget tool
 export const forgetSchema = z.object({
     id: z.number().optional().describe('Specific memory ID to delete'),
@@ -28,6 +35,8 @@ export const forgetSchema = z.object({
         type: z.enum(['user', 'cli', 'hook', 'email', 'web', 'agent', 'file', 'api', 'tool_response']),
         identifier: z.string(),
     }).optional().describe('Caller identity for access control'),
+    fromSource: z.string().optional()
+        .describe('Revoke-by-source: delete all memories written by this source. Exact "type:identifier", or a "type:*" / "type:" prefix to revoke a whole source type. Authorised by the trust-hierarchy revoke ACL (you must own the source or outrank it). Distinct from `source` (the caller).'),
 });
 /**
  * Execute the forget tool
@@ -35,6 +44,15 @@ export const forgetSchema = z.object({
 export async function executeForget(input) {
     try {
         const db = getDatabase();
+        // Revoke-by-source gate: a destructive mass-delete primitive that a hijacked
+        // agent must not be able to invoke. OFF by default; only an out-of-band human
+        // action (`shieldcortex config --allow-revoke-by-source`) enables it.
+        if (input.fromSource !== undefined && !isRevokeBySourceEnabled()) {
+            return {
+                success: false,
+                error: 'revoke-by-source is disabled. Enable it deliberately with `shieldcortex config --allow-revoke-by-source` (an out-of-band action), then re-run.',
+            };
+        }
         // Resolve project (auto-detect if not provided)
         const resolvedProject = resolveProject(input.project);
         const source = input.source;
@@ -101,6 +119,28 @@ export async function executeForget(input) {
             conditions.push('salience < ?');
             params.push(input.belowSalience);
         }
+        // Revoke-by-source: target every memory written by a given source. Exact
+        // "type:identifier", or a "type:*" / "type:" prefix for a whole source type.
+        // Per-row authorisation is the trust-hierarchy revoke ACL (in deleteMemory
+        // via mode:'revoke') — this clause only SELECTS the candidates. Project scope
+        // still applies; pass project:"*" to revoke a source across all projects.
+        if (input.fromSource !== undefined) {
+            const fs = input.fromSource.trim();
+            if (!fs || fs === '*' || fs === ':' || fs === ':*') {
+                return {
+                    success: false,
+                    error: 'fromSource must name a source (e.g. "agent:agent-spawned" or "agent:*"), not a blanket wildcard.',
+                };
+            }
+            if (fs.endsWith(':*') || fs.endsWith(':')) {
+                conditions.push('source LIKE ?');
+                params.push(`${fs.replace(/:\*?$/, '')}:%`);
+            }
+            else {
+                conditions.push('source = ?');
+                params.push(fs);
+            }
+        }
         if (conditions.length === 0) {
             return {
                 success: false,
@@ -113,6 +153,15 @@ export async function executeForget(input) {
         if (affected.length === 0) {
             return { success: true, deleted: 0, memories: [] };
         }
+        // Blast-radius cap on revoke-by-source: refuse a single call that would
+        // delete more than MAX_REVOKE_ROWS — narrow it (by project/category/etc.).
+        if (input.fromSource !== undefined && affected.length > MAX_REVOKE_ROWS) {
+            return {
+                success: false,
+                wouldDelete: affected.length,
+                error: `revoke-by-source matched ${affected.length} memories (cap ${MAX_REVOKE_ROWS}). Narrow the scope (project/category/query) and re-run.`,
+            };
+        }
         // Dry run - just show what would be deleted
         if (input.dryRun) {
             return {
@@ -138,10 +187,13 @@ export async function executeForget(input) {
         // delete, and the dashboard `memory_deleted` event. A low-trust / non-owner
         // caller therefore can't mass-delete protected memories. better-sqlite3 is
         // synchronous, so the per-row loop stays inside one transaction atomically.
+        // revoke-by-source uses the trust-hierarchy revoke ACL (own OR outrank);
+        // every other bulk forget stays own-only.
+        const deleteMode = input.fromSource !== undefined ? 'revoke' : 'delete';
         const deletedMemories = [];
         withTransaction(() => {
             for (const memory of affected) {
-                if (deleteMemory(memory.id, source)) {
+                if (deleteMemory(memory.id, source, { mode: deleteMode })) {
                     deletedMemories.push(memory);
                 }
             }

package/dist/tools/recall.js

@@ -4,7 +4,7 @@
  * Search and retrieve memories using semantic search and filters.
  */
 import { z } from 'zod';
-import { searchMemories, recallWithEmbeddings, accessMemory, getRecentMemories, getHighPriorityMemories, getRelatedMemories } from '../memory/store.js';
+import { searchMemories, recallWithEmbeddings, accessMemory, getRecentMemories, getHighPriorityMemories, getRelatedMemories, logAllowedRead } from '../memory/store.js';
 import { formatTimeSinceAccess } from '../memory/decay.js';
 import { MemoryNotFoundError, formatErrorForMcp } from '../errors.js';
 import { resolveProject } from '../context/project-context.js';
@@ -115,6 +115,9 @@ export async function executeRecall(input) {
             }
             return m;
         });
+        // Provenance ledger: one allowed-read row per recall call (not per memory).
+        if (source)
+            logAllowedRead(source, `recall:${input.mode}`, memories.map(m => m.id), projectFilter);
         return {
             success: true,
             memories,
@@ -196,6 +199,8 @@ export function executeGetMemory(input) {
                 error: error.toUserMessage(),
             };
         }
+        if (input.source)
+            logAllowedRead(input.source, 'get_memory', [allowed.id], allowed.project ?? null);
         return { success: true, memory: allowed };
     }
     catch (error) {
@@ -215,6 +220,9 @@ export function executeGetRelated(input) {
     try {
         const related = getRelatedMemories(input.id);
         const allowedIds = new Set(guardReadMemories(related.map((r) => r.memory), input.source).map((m) => m.id));
+        if (input.source && allowedIds.size > 0) {
+            logAllowedRead(input.source, 'get_related', [...allowedIds]);
+        }
         return { success: true, related: related.filter((r) => allowedIds.has(r.memory.id)) };
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shieldcortex",
-  "version": "4.38.0",
+  "version": "4.40.0",
   "description": "Trustworthy memory and security for AI agents. Recall debugging, review queue, OpenClaw session capture, and memory poisoning defence for Claude Code, Codex, OpenClaw, LangChain, and MCP agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",