Audit Trail

                         +-----------------------+
  tx.ts routes --------->|                       |
  approval-service.ts -->| AuditTraceService     |---> SQLite (WAL mode)
  wallet-service.ts ---->|   .log(event, data)   |      audit_events
  approval-ui.ts ------->|   .getTrail(intentId) |      rate_limit_events
  skills.ts routes ----->|   .getRecentEvents(n) |
                         +-----------------------+

CREATE TABLE IF NOT EXISTS audit_events (
  id         TEXT PRIMARY KEY,
  timestamp  INTEGER NOT NULL,
  intent_id  TEXT NOT NULL,
  event      TEXT NOT NULL,
  data       TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS rate_limit_events (
  wallet_address TEXT NOT NULL,
  timestamp      INTEGER NOT NULL
);

curl http://localhost:3000/v1/approvals/history?limit=5

{
  "events": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "timestamp": 1706900000000,
      "intentId": "550e8400-e29b-41d4-a716-446655440000",
      "event": "tx_broadcast",
      "data": {
        "intentId": "550e8400-e29b-41d4-a716-446655440000",
        "txHash": "0xabc123..."
      }
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "timestamp": 1706899999000,
      "intentId": "550e8400-e29b-41d4-a716-446655440000",
      "event": "signature_created",
      "data": {
        "intentId": "550e8400-e29b-41d4-a716-446655440000",
        "txRequestHash": "0xdef456...",
        "signerAddress": "0x1234...5678",
        "txHash": "0xabc123..."
      }
    }
  ]
}

import { AuditTraceService } from "@clavion/audit";

const auditTrace = new AuditTraceService("/path/to/audit.db");

// Get all events for a specific transaction, ordered chronologically (ASC)
const trail = auditTrace.getTrail("550e8400-e29b-41d4-a716-446655440000");

// Get the 20 most recent events across all intents (DESC order)
const recent = auditTrace.getRecentEvents(20);

interface AuditEvent {
  id: string;          // UUID
  timestamp: number;   // Unix ms
  intentId: string;    // correlation ID
  event: string;       // event type name
  data: Record<string, unknown>;  // parsed JSON payload
}

SELECT id, timestamp, event, data
FROM audit_events
WHERE intent_id = '550e8400-e29b-41d4-a716-446655440000'
ORDER BY timestamp ASC;

SELECT id, timestamp, intent_id, json_extract(data, '$.reason') AS reason
FROM audit_events
WHERE event = 'signing_denied'
  AND timestamp > (strftime('%s', 'now') * 1000 - 86400000)
ORDER BY timestamp DESC;

SELECT wallet_address, COUNT(*) AS tx_count
FROM rate_limit_events
WHERE timestamp > (strftime('%s', 'now') * 1000 - 3600000)
GROUP BY wallet_address
ORDER BY tx_count DESC;

SELECT intent_id,
       timestamp,
       json_extract(data, '$.decision') AS decision,
       json_extract(data, '$.reasons') AS reasons
FROM audit_events
WHERE event = 'policy_evaluated'
  AND json_extract(data, '$.decision') = 'deny'
ORDER BY timestamp DESC
LIMIT 50;

SELECT intent_id,
       timestamp,
       json_extract(data, '$.txHash') AS tx_hash,
       json_extract(data, '$.error') AS error_message
FROM audit_events
WHERE event = 'broadcast_failed'
ORDER BY timestamp DESC;

recordRateLimitTick(walletAddress: string): void {
  this.rateLimitInsertStmt.run(walletAddress, Date.now());
}

const recentTxCount = auditTrace.countRecentTxByWallet(
  intent.wallet.address,
  3_600_000,  // 1 hour in milliseconds
);

SELECT COUNT(*) AS count
FROM rate_limit_events
WHERE wallet_address = ?
  AND timestamp > ?

{
  "maxTxPerHour": 10
}

INSERT INTO audit_events (id, timestamp, intent_id, event, data) VALUES (?, ?, ?, ?, ?)
INSERT INTO rate_limit_events (wallet_address, timestamp) VALUES (?, ?)

sqlite3 /path/to/audit.db \
  "SELECT json_object(
     'id', id,
     'timestamp', timestamp,
     'intentId', intent_id,
     'event', event,
     'data', json(data)
   ) FROM audit_events ORDER BY timestamp ASC;" \
  > audit-export.jsonl

-- Remove rate-limit ticks older than 7 days (safe, does not affect rate limiting)
DELETE FROM rate_limit_events
WHERE timestamp < (strftime('%s', 'now') * 1000 - 604800000);