refactor(server): move the install audit trail from core to the server (P1.2, UF-040)

Core keeps only shared infrastructure, so InstallAuditStore leaves it and
lives in packages/server/src/local/install-audit.ts. The trail itself stays:
the Audit and Activity tabs, the extend and export routes, and the threat
model entry keep working on the same waggle.db table.

- @waggle/shared gets RecordAuditInput and the narrow InstallAuditRecorder
  (record only), which the agent's skill tools now depend on.
- The server creates the audit table before the one-time legacy copy, which
  no longer constructs it in core.
- UF-040: GET /api/debug/logs called prepare() on the store's private db
  wrapper, which has none, so the support bundle never carried recent
  installs. It now reads them through getRecentSummary().
This commit is contained in:
shumeiko.it
2026-10-25 21:32:38 +01:00
parent 3befcd8e9b
commit 2e08f2ae96
22 changed files with 118 additions and 79 deletions

View File

@@ -12,7 +12,7 @@ import type { ToolDefinition } from './tools.js';
import { SkillRecommender } from './skill-recommender.js';
import { searchCapabilities, validateInstallCandidate, type MarketplaceCandidate } from './capability-acquisition.js';
import { assessTrust, formatTrustSummary } from './trust-model.js';
import type { InstallAuditStore } from '@waggle/core';
import type { InstallAuditRecorder } from '@waggle/shared';
// Type-only import — erased at runtime, so it does NOT reintroduce the
// agent ↔ marketplace runtime cycle that the lazy import below guards against.
import type { SecurityGate, MarketplacePackage } from '@waggle/marketplace';
@@ -50,7 +50,7 @@ export interface SkillToolsDeps {
/** Native tool names (for acquisition search — avoids proposing install when a tool exists) */
nativeToolNames?: string[];
/** Audit store for recording install events (optional — degrades gracefully) */
auditStore?: InstallAuditStore;
auditStore?: InstallAuditRecorder;
/** Optional callback to search the marketplace catalog for capabilities */
searchMarketplace?: (query: string) => Promise<MarketplaceCandidate[]>;
/**

View File

@@ -17,14 +17,14 @@ import * as path from 'node:path';
import { redactSkillContent } from './skill-redaction.js';
import type { SkillInitiator } from './skill-frontmatter.js';
import { parseSkillFrontmatter } from './skill-frontmatter.js';
import type { InstallAuditStore } from '@waggle/core';
import type { InstallAuditRecorder } from '@waggle/shared';
/** Shared deps for every skill-write op. auditStore/onChange degrade gracefully. */
export interface SkillWriteDeps {
/** Directory holding personal-scope SKILL.md files (~/.waggle/skills). */
skillsDir: string;
/** Audit store — when present, every op records an install_audit row. */
auditStore?: InstallAuditStore;
auditStore?: InstallAuditRecorder;
/** Called after a successful write/delete so the caller can hot-reload skills. */
onChange?: () => void;
}

View File

@@ -2,8 +2,8 @@
* Cron Store — SQLite persistence for solo cron schedules.
*
* Stores cron job definitions with expression validation via cron-parser,
* due-job queries, and run tracking. Follows the same pattern as
* InstallAuditStore — operates on the .mind DB with lazy table creation.
* due-job queries, and run tracking. Operates on waggle.db with lazy table
* creation.
*/
import cronParser from 'cron-parser';

View File

@@ -56,12 +56,6 @@ export { importLegacyMindData, type LegacyMindSource, type LegacyImportReport }
// ── Waggle-specific orchestration ──
export { WaggleConfig, type ProviderEntry } from './config.js';
export {
InstallAuditStore, INSTALL_AUDIT_TABLE_SQL,
type InstallAuditEntry, type RecordAuditInput,
type AuditAction, type AuditRiskLevel, type AuditTrustSource,
type AuditApprovalClass, type AuditInitiator, type AuditCapabilityType,
} from './install-audit.js';
export {
CronStore, CRON_SCHEDULES_TABLE_SQL, CRON_RUN_LEASES_TABLE_SQL, VALID_JOB_TYPES, cronExprError,
type CronSchedule, type CreateScheduleInput, type CronJobType,

View File

@@ -1,9 +1,9 @@
/**
* Skill Hash Store — SHA-256 content hashing for skill update detection.
*
* Stores hashes of skill file content in the .mind DB. On server startup,
* Stores hashes of skill file content in waggle.db. On server startup,
* compares current file hashes to stored hashes to detect changes.
* Follows the same ensureTable pattern as CronStore / InstallAuditStore.
* Follows the same ensureTable pattern as CronStore.
*/
import * as crypto from 'node:crypto';

View File

@@ -15,7 +15,6 @@ import { AwarenessLayer } from './awareness.js';
import { CronStore } from './cron-store.js';
import { ExecutionTraceStore } from './execution-traces.js';
import { IdentityLayer } from './identity.js';
import { InstallAuditStore } from './install-audit.js';
import { SkillHashStore } from './skill-hashes.js';
import type { DataScope, WaggleDB } from './waggle-db.js';
@@ -121,13 +120,15 @@ function copyScopedTables(source: DatabaseType, target: DatabaseType, scope: Dat
* Copies Waggle data from each legacy source into `waggleDb`, once per scope.
* The personal source also brings the app-wide tables; workspace sources bring
* their profile and awareness items.
*
* Tables owned outside core (install_audit, owned by the server) must be created
* by their owner before this call; otherwise they take the legacy definition.
*/
export function importLegacyMindData(waggleDb: WaggleDB, sources: LegacyMindSource[]): LegacyImportReport[] {
// Create every target table with its current schema first.
// Create every core target table with its current schema first.
new CronStore(waggleDb);
new SkillHashStore(waggleDb);
new ExecutionTraceStore(waggleDb);
new InstallAuditStore(waggleDb);
new IdentityLayer(waggleDb);
new AwarenessLayer(waggleDb);

View File

@@ -10,8 +10,9 @@ import Fastify, { type FastifyInstance, type FastifyRequest } from 'fastify';
import cors from '@fastify/cors';
import fastifyStatic from '@fastify/static';
import websocket from '@fastify/websocket';
import { WaggleDB, importLegacyMindData, workspaceDataScope, type LegacyMindSource, WorkspaceManager, WaggleConfig, createEmbeddingProvider, type EmbeddingProviderConfig, type EmbeddingProviderInstance, InstallAuditStore, CronStore, AwarenessLayer, VaultStore, SkillHashStore, TelemetryStore, TELEMETRY_EVENTS, ExecutionTraceStore } from '@waggle/core';
import { WaggleDB, importLegacyMindData, workspaceDataScope, type LegacyMindSource, WorkspaceManager, WaggleConfig, createEmbeddingProvider, type EmbeddingProviderConfig, type EmbeddingProviderInstance, CronStore, AwarenessLayer, VaultStore, SkillHashStore, TelemetryStore, TELEMETRY_EVENTS, ExecutionTraceStore } from '@waggle/core';
import { corsOriginAllowed } from './cors-config.js';
import { InstallAuditStore } from './install-audit.js';
import { getStorageProvider } from './storage/index.js';
import { isLoopbackBind, resolveBindHost } from './net-config.js';
import { isLocalRequest } from './origin-guard.js';
@@ -362,7 +363,7 @@ declare module 'fastify' {
eventBus: EventEmitter;
agentRunner?: AgentRunner;
agentState: AgentState;
auditStore: import('@waggle/core').InstallAuditStore;
auditStore: InstallAuditStore;
cronStore: import('@waggle/core').CronStore;
waggleDb: import('@waggle/core').WaggleDB;
/** Memory (ADR-0007): personal and workspace memories, reached only through the contract. */
@@ -501,6 +502,11 @@ export async function buildLocalServer(config: Partial<LocalConfig> = {}) {
// A workspace whose directory fails the path checks has nothing to copy.
}
}
// Install audit store — persistent trail for capability install events. Its
// table must exist before the legacy copy below, which fills it.
const auditStore = new InstallAuditStore(waggleDb);
server.decorate('auditStore', auditStore);
for (const report of importLegacyMindData(waggleDb, legacySources)) {
if (report.status === 'imported') {
log.info(`[waggle-db] copied legacy data for ${report.scope}: ${JSON.stringify(report.copied)}`);
@@ -509,10 +515,6 @@ export async function buildLocalServer(config: Partial<LocalConfig> = {}) {
}
}
// Install audit store — persistent trail for capability install events
const auditStore = new InstallAuditStore(waggleDb);
server.decorate('auditStore', auditStore);
// Cron store — SQLite-backed schedule persistence for Solo
const cronStore = new CronStore(waggleDb);
server.decorate('cronStore', cronStore);
@@ -1933,13 +1935,10 @@ export async function buildLocalServer(config: Partial<LocalConfig> = {}) {
};
try { payload.health = await server.inject({ method: 'GET', url: '/health' }).then(r => JSON.parse(r.payload)); } catch { /* non-blocking */ }
try {
const raw = (server.auditStore as unknown as { db?: { prepare: (sql: string) => { all: () => unknown[] } } })?.db;
if (raw) {
// R2-006: expose only a coarse, non-recon column subset (no capability
// names/versions/sources, risk_level, approval_class, initiator or detail)
// and cap the rows — the support bundle needs activity shape, not an inventory.
payload.auditRecent = raw.prepare('SELECT timestamp, action, capability_type FROM install_audit ORDER BY timestamp DESC LIMIT 50').all();
}
// R2-006: expose only a coarse, non-recon column subset (no capability
// names/versions/sources, risk_level, approval_class, initiator or detail)
// and cap the rows — the support bundle needs activity shape, not an inventory.
payload.auditRecent = server.auditStore.getRecentSummary(50);
} catch { /* non-blocking */ }
// R2-006: vault key NAMES dropped — even names are recon material and the
// support bundle does not need them.

View File

@@ -5,31 +5,23 @@
* failed) so there is a verifiable history of what was installed, when, why,
* and by whom.
*
* Lives in waggle.db with Waggle's other own data (ADR-0007).
* Lives in waggle.db with Waggle's other own data (ADR-0007). The server owns
* the store; core keeps only shared infrastructure (P1.2), and producers outside
* the server write through InstallAuditRecorder from @waggle/shared.
*/
import type { WaggleDB } from './waggle-db.js';
import type { WaggleDB } from '@waggle/core';
import {
sqlInList, RISK_LEVELS, APPROVAL_CLASSES, AUDIT_ACTIONS,
AUDIT_CAPABILITY_TYPES, AUDIT_INITIATORS, TRUST_SOURCES,
} from '@waggle/shared';
import type {
AuditAction, AuditCapabilityType, AuditInitiator, ApprovalClass,
InstallAuditRecorder, RecordAuditInput, RiskLevel, TrustSource,
} from '@waggle/shared';
// ── Types ──────────────────────────────────────────────────────────────
// P7/D15 A2b: the audit vocabulary is now canonical in @waggle/shared. The
// Audit*-prefixed names are kept as aliases (re-exported) so every downstream
// `import { AuditAction, ... } from '@waggle/core'` keeps working unchanged.
// All six sets were already byte-identical to the shared ones (incl. P5/D4's
// 'uninstalled'), so this is a pure structural re-point — no value change.
export type {
AuditAction, AuditCapabilityType, AuditInitiator,
RiskLevel as AuditRiskLevel, ApprovalClass as AuditApprovalClass, TrustSource as AuditTrustSource,
} from '@waggle/shared';
import type {
AuditAction, AuditCapabilityType, AuditInitiator,
RiskLevel as AuditRiskLevel, ApprovalClass as AuditApprovalClass, TrustSource as AuditTrustSource,
} from '@waggle/shared';
export interface InstallAuditEntry {
id: number;
timestamp: string;
@@ -37,26 +29,16 @@ export interface InstallAuditEntry {
capability_type: AuditCapabilityType;
source: string;
version: string | null;
risk_level: AuditRiskLevel;
trust_source: AuditTrustSource;
approval_class: AuditApprovalClass;
risk_level: RiskLevel;
trust_source: TrustSource;
approval_class: ApprovalClass;
action: AuditAction;
initiator: AuditInitiator;
detail: string;
}
export interface RecordAuditInput {
capabilityName: string;
capabilityType: AuditCapabilityType;
source: string;
version?: string | null;
riskLevel: AuditRiskLevel;
trustSource: AuditTrustSource;
approvalClass: AuditApprovalClass;
action: AuditAction;
initiator: AuditInitiator;
detail?: string;
}
/** The coarse columns the support bundle may carry (R2-006). */
export type InstallAuditSummary = Pick<InstallAuditEntry, 'timestamp' | 'action' | 'capability_type'>;
// ── Table DDL ──────────────────────────────────────────────────────────
@@ -89,7 +71,7 @@ CREATE INDEX IF NOT EXISTS idx_audit_timestamp ON install_audit (timestamp DESC)
// ── Store ──────────────────────────────────────────────────────────────
export class InstallAuditStore {
export class InstallAuditStore implements InstallAuditRecorder {
private db: WaggleDB;
constructor(db: WaggleDB) {
@@ -205,6 +187,13 @@ export class InstallAuditStore {
).all(type, limit) as InstallAuditEntry[];
}
/** Recent entries without names, versions, sources, risk or detail. */
getRecentSummary(limit: number = 50): InstallAuditSummary[] {
return this.db.getDatabase().prepare(
'SELECT timestamp, action, capability_type FROM install_audit ORDER BY id DESC LIMIT ?',
).all(limit) as InstallAuditSummary[];
}
/** Get all entries (for testing). */
getAll(): InstallAuditEntry[] {
return this.db.getDatabase().prepare(

View File

@@ -1,6 +1,5 @@
import type { FastifyInstance } from 'fastify';
import type { ConnectorHealth } from '@waggle/shared';
import type { RecordAuditInput } from '@waggle/core';
import type { ConnectorHealth, RecordAuditInput } from '@waggle/shared';
import {
JiraConnector, SalesforceConnector,
getConnectorCredential, setConnectorCredential, setConnectorCredentialBundle,

View File

@@ -13,8 +13,8 @@
*/
import type { FastifyInstance } from 'fastify';
import { EXTENSION_TYPES, type ExtensionType } from '@waggle/shared';
import type { AuditCapabilityType, InstallAuditEntry } from '@waggle/core';
import { EXTENSION_TYPES, type AuditCapabilityType, type ExtensionType } from '@waggle/shared';
import type { InstallAuditEntry } from '../install-audit.js';
import { authHeaders } from './validate.js';
/** ExtensionType → marketplace InstallationType, where representable (A5). */

View File

@@ -30,9 +30,10 @@ import {
MCP_CATALOG,
type McpInstance,
type McpServer,
type RecordAuditInput,
} from '@waggle/shared';
import type { McpRuntime, McpServerState } from '@waggle/agent';
import { scanForInjection, type RecordAuditInput } from '@waggle/core';
import { scanForInjection } from '@waggle/core';
import {
MCP_SERVERS,
MarketplaceInstaller,

View File

@@ -12,7 +12,8 @@ import Fastify from 'fastify';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import { WaggleDB, InstallAuditStore, VaultStore, type SecretStore } from '@waggle/core';
import { WaggleDB, VaultStore, type SecretStore } from '@waggle/core';
import { InstallAuditStore } from '../../src/local/install-audit.js';
import {
ConnectorRegistry,
BaseConnector,

View File

@@ -8,7 +8,9 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import Fastify from 'fastify';
import { WaggleDB, InstallAuditStore, type RecordAuditInput } from '@waggle/core';
import { WaggleDB } from '@waggle/core';
import type { RecordAuditInput } from '@waggle/shared';
import { InstallAuditStore } from '../../src/local/install-audit.js';
import { extendRoutes } from '../../src/local/routes/extend.js';
import { marketplaceRoutes } from '../../src/local/routes/marketplace.js';

View File

@@ -10,7 +10,7 @@ import {
sqlInList, RISK_LEVELS, APPROVAL_CLASSES, AUDIT_ACTIONS,
AUDIT_CAPABILITY_TYPES, AUDIT_INITIATORS, TRUST_SOURCES,
} from '@waggle/shared';
import { INSTALL_AUDIT_TABLE_SQL } from '../src/install-audit.js';
import { INSTALL_AUDIT_TABLE_SQL } from '../../src/local/install-audit.js';
const COLUMNS = [
{ col: 'capability_type', values: AUDIT_CAPABILITY_TYPES },
@@ -25,7 +25,7 @@ describe('install_audit CHECK parity (A3)', () => {
for (const { col, values } of COLUMNS) {
const expected = `${col} IN (${sqlInList(values)})`;
it(`core install-audit DDL pins ${col} to the canonical list`, () => {
it(`install-audit DDL pins ${col} to the canonical list`, () => {
expect(INSTALL_AUDIT_TABLE_SQL).toContain(expected);
});
}

View File

@@ -5,8 +5,9 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import { WaggleDB } from '../src/waggle-db.js';
import { InstallAuditStore, type RecordAuditInput } from '../src/install-audit.js';
import { WaggleDB } from '@waggle/core';
import type { RecordAuditInput } from '@waggle/shared';
import { InstallAuditStore } from '../../src/local/install-audit.js';
describe('InstallAuditStore', () => {
let tmpDir: string;
@@ -45,6 +46,15 @@ describe('InstallAuditStore', () => {
expect(store.getByAction('uninstalled')).toHaveLength(1);
});
it('summarises recent entries without names, sources, risk or detail', () => {
store.record(makeInput({ capabilityName: 'first', action: 'proposed' }));
store.record(makeInput({ capabilityName: 'second', capabilityType: 'mcp', action: 'installed' }));
const summary = store.getRecentSummary(1);
expect(summary).toHaveLength(1);
expect(summary[0]).toEqual({ timestamp: expect.any(String), action: 'installed', capability_type: 'mcp' });
});
it("migrates a legacy-CHECK table to accept 'uninstalled' (P5/D4)", () => {
const tmp2 = fs.mkdtempSync(path.join(os.tmpdir(), 'waggle-audit-legacy-'));
const legacyDb = new WaggleDB(path.join(tmp2, 'waggle.db'));

View File

@@ -20,7 +20,7 @@ import * as os from 'node:os';
import { PassThrough } from 'node:stream';
import Database from 'better-sqlite3';
import { WaggleDB } from '@waggle/core';
import { InstallAuditStore } from '@waggle/core';
import { InstallAuditStore } from '../../src/local/install-audit.js';
import { MCP_CATALOG } from '@waggle/shared';
import { SecurityGate } from '@waggle/marketplace';
import { McpRuntime, type McpProcess, type SpawnFn } from '@waggle/agent';

View File

@@ -103,6 +103,18 @@ describe('Trust Model Runtime Wiring', () => {
// so no new audit entries should be created via the API route
expect(after).toBe(before);
});
it('the support bundle carries recent installs without capability names (UF-040)', async () => {
const res = await injectWithAuth(server, { method: 'GET', url: '/api/debug/logs' });
expect(res.statusCode).toBe(200);
const { auditRecent } = JSON.parse(res.payload) as { auditRecent?: Array<Record<string, unknown>> };
expect(auditRecent).toBeDefined();
expect(auditRecent!.some(e => e.action === 'installed' && e.capability_type === 'skill')).toBe(true);
for (const entry of auditRecent!) {
expect(Object.keys(entry).sort()).toEqual(['action', 'capability_type', 'timestamp']);
}
});
});
describe('Audit REST endpoint', () => {

View File

@@ -62,6 +62,26 @@ export type AuditCapabilityType = (typeof AUDIT_CAPABILITY_TYPES)[number];
export const AUDIT_INITIATORS = ['agent', 'user', 'system'] as const;
export type AuditInitiator = (typeof AUDIT_INITIATORS)[number];
/** One event for the install audit trail. */
export interface RecordAuditInput {
capabilityName: string;
capabilityType: AuditCapabilityType;
source: string;
version?: string | null;
riskLevel: RiskLevel;
trustSource: TrustSource;
approvalClass: ApprovalClass;
action: AuditAction;
initiator: AuditInitiator;
detail?: string;
}
/** Write side of the install audit trail. Producers such as the agent's skill
* tools only record; the store that also reads the trail lives in the server. */
export interface InstallAuditRecorder {
record(input: RecordAuditInput): void;
}
/** Ascending severity order — index = rank. Used to compare/sort risk levels so a
* `critical` always outranks `low` (the team-governance bug was a `?? 0` that
* sorted `critical` BELOW `low`). */