@lawrenceliang-btc/atel-sdk 0.8.7

package/dist/service/index.js

@@ -0,0 +1,273 @@
+/**
+ * Trust Score Network Service
+ *
+ * HTTP API wrapping TrustScoreClient and TrustGraph with
+ * JSON file persistence. MVP — no database required.
+ */
+import express from 'express';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { TrustScoreClient, } from '../score/index.js';
+import { TrustGraph, calculateTaskWeight, } from '../graph/index.js';
+// ─── Service ─────────────────────────────────────────────────────
+export class TrustScoreService {
+    app;
+    scoreClient;
+    graph;
+    config;
+    server = null;
+    summaries = [];
+    constructor(config) {
+        this.config = config;
+        this.app = express();
+        this.scoreClient = new TrustScoreClient();
+        this.graph = new TrustGraph();
+        this.app.use(express.json());
+        this.setupRoutes();
+        this.app.use(this.errorHandler.bind(this));
+    }
+    // ── Lifecycle ────────────────────────────────────────────────
+    async start() {
+        this.loadData();
+        return new Promise((resolve) => {
+            this.server = this.app.listen(this.config.port, () => {
+                console.log(`[ATEL] Trust Score Service listening on :${this.config.port}`);
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        return new Promise((resolve, reject) => {
+            if (!this.server)
+                return resolve();
+            this.server.close((err) => (err ? reject(err) : resolve()));
+            this.server = null;
+        });
+    }
+    // ── Persistence ──────────────────────────────────────────────
+    saveData() {
+        const dir = resolve(this.config.dataDir);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(resolve(dir, 'scores.json'), JSON.stringify(this.summaries, null, 2));
+        const graphExport = this.graph.exportGraph();
+        const graphData = {
+            nodes: graphExport.nodes.map((n) => ({
+                ...n,
+                scenes: [...n.scenes],
+            })),
+            edges: graphExport.edges,
+        };
+        writeFileSync(resolve(dir, 'graph.json'), JSON.stringify(graphData, null, 2));
+        console.log(`[ATEL] Data saved to ${dir}`);
+    }
+    loadData() {
+        const dir = resolve(this.config.dataDir);
+        // Load summaries and replay into TrustScoreClient
+        const scoresPath = resolve(dir, 'scores.json');
+        if (existsSync(scoresPath)) {
+            try {
+                const raw = readFileSync(scoresPath, 'utf-8');
+                const loaded = JSON.parse(raw);
+                this.summaries = loaded;
+                this.scoreClient = new TrustScoreClient();
+                for (const s of loaded) {
+                    this.scoreClient.submitExecutionSummary(s);
+                }
+                console.log(`[ATEL] Loaded ${loaded.length} summaries from disk`);
+            }
+            catch (e) {
+                console.error('[ATEL] Failed to load scores.json:', e);
+            }
+        }
+        // Load graph data and replay into TrustGraph
+        const graphPath = resolve(dir, 'graph.json');
+        if (existsSync(graphPath)) {
+            try {
+                const raw = readFileSync(graphPath, 'utf-8');
+                const data = JSON.parse(raw);
+                this.graph = new TrustGraph();
+                // Restore nodes with metadata
+                for (const n of data.nodes) {
+                    this.graph.addNode(n.agent_id, n.metadata);
+                }
+                // Replay interactions from summaries to rebuild edges properly
+                // (edges contain computed fields like consistency_score that need
+                //  the running EMA, so we replay from summaries instead)
+                for (const s of this.summaries) {
+                    const taskWeight = calculateTaskWeight({
+                        tool_calls: s.tool_calls,
+                        duration_ms: s.duration_ms,
+                        max_cost: s.risk_level === 'critical' ? 10 : s.risk_level === 'high' ? 5 : s.risk_level === 'medium' ? 2 : 1,
+                        risk_level: s.risk_level,
+                        similar_task_count: 0,
+                    });
+                    this.graph.recordInteraction({
+                        from: s.issuer,
+                        to: s.executor,
+                        scene: s.task_type,
+                        success: s.success,
+                        task_weight: taskWeight,
+                        duration_ms: s.duration_ms,
+                    });
+                }
+                console.log(`[ATEL] Loaded graph: ${data.nodes.length} nodes, ${data.edges.length} edges`);
+            }
+            catch (e) {
+                console.error('[ATEL] Failed to load graph.json:', e);
+            }
+        }
+    }
+    // ── Routes ───────────────────────────────────────────────────
+    setupRoutes() {
+        const r = express.Router();
+        // Health check
+        r.get('/health', (_req, res) => {
+            res.json({ status: 'ok', timestamp: new Date().toISOString() });
+        });
+        // Submit execution summary
+        r.post('/summary', (req, res, next) => {
+            try {
+                const body = req.body;
+                this.validateSummary(body);
+                // 1. Submit to TrustScoreClient
+                this.scoreClient.submitExecutionSummary(body);
+                // 2. Update TrustGraph
+                const taskWeight = calculateTaskWeight({
+                    tool_calls: body.tool_calls,
+                    duration_ms: body.duration_ms,
+                    max_cost: body.risk_level === 'critical' ? 10 : body.risk_level === 'high' ? 5 : body.risk_level === 'medium' ? 2 : 1,
+                    risk_level: body.risk_level,
+                    similar_task_count: 0,
+                });
+                this.graph.recordInteraction({
+                    from: body.issuer,
+                    to: body.executor,
+                    scene: body.task_type,
+                    success: body.success,
+                    task_weight: taskWeight,
+                    duration_ms: body.duration_ms,
+                });
+                // 3. Persist
+                this.summaries.push(body);
+                this.saveData();
+                // 4. Return updated score
+                const report = this.scoreClient.getAgentScore(body.executor);
+                res.status(201).json(report);
+            }
+            catch (err) {
+                next(err);
+            }
+        });
+        // Query single agent score
+        r.get('/score/:agentId', (req, res) => {
+            const agentId = Array.isArray(req.params.agentId) ? req.params.agentId[0] : req.params.agentId;
+            const report = this.scoreClient.getAgentScore(agentId);
+            res.json(report);
+        });
+        // Query all scores
+        r.get('/scores', (_req, res) => {
+            res.json(this.scoreClient.getAllScores());
+        });
+        // ── Graph routes ───────────────────────────────────────────
+        // Composite trust query
+        r.post('/graph/trust', (req, res, next) => {
+            try {
+                const { from, to, scene } = req.body;
+                if (!from || !to || !scene) {
+                    res.status(400).json({ error: 'from, to, and scene are required' });
+                    return;
+                }
+                const result = this.graph.compositeTrust(from, to, scene);
+                res.json(result);
+            }
+            catch (err) {
+                next(err);
+            }
+        });
+        // Node info
+        r.get('/graph/node/:agentId', (req, res) => {
+            const agentId = Array.isArray(req.params.agentId) ? req.params.agentId[0] : req.params.agentId;
+            const node = this.graph.getNode(agentId);
+            if (!node) {
+                res.status(404).json({ error: 'Agent not found in graph' });
+                return;
+            }
+            // Serialize Set → array
+            res.json({ ...node, scenes: [...node.scenes] });
+        });
+        // Top partners
+        r.get('/graph/partners/:agentId', (req, res) => {
+            const agentId = Array.isArray(req.params.agentId) ? req.params.agentId[0] : req.params.agentId;
+            const k = parseInt(req.query.k) || 10;
+            const partners = this.graph.topPartners(agentId, k);
+            res.json(partners);
+        });
+        // Scene top agents
+        r.get('/graph/scene/:scene', (req, res) => {
+            const scene = Array.isArray(req.params.scene) ? req.params.scene[0] : req.params.scene;
+            const k = parseInt(req.query.k) || 10;
+            const agents = this.graph.topAgentsForScene(scene, k);
+            res.json(agents);
+        });
+        // Behavior consistency
+        r.get('/graph/consistency/:agentId', (req, res) => {
+            const agentId = Array.isArray(req.params.agentId) ? req.params.agentId[0] : req.params.agentId;
+            const result = this.graph.behaviorConsistencyScore(agentId);
+            res.json(result);
+        });
+        // Suspicious clusters
+        r.get('/graph/suspicious', (_req, res) => {
+            const clusters = this.graph.detectSuspiciousClusters();
+            res.json(clusters);
+        });
+        // Graph stats
+        r.get('/graph/stats', (_req, res) => {
+            res.json(this.graph.getStats());
+        });
+        this.app.use('/api/v1', r);
+    }
+    // ── Validation ───────────────────────────────────────────────
+    validateSummary(body) {
+        const required = [
+            'executor', 'issuer', 'task_id', 'task_type',
+            'risk_level', 'proof_id', 'timestamp',
+        ];
+        for (const field of required) {
+            if (!body[field]) {
+                throw new ValidationError(`${field} is required`);
+            }
+        }
+        const validRisk = ['low', 'medium', 'high', 'critical'];
+        if (!validRisk.includes(body.risk_level)) {
+            throw new ValidationError(`risk_level must be one of: ${validRisk.join(', ')}`);
+        }
+        if (typeof body.success !== 'boolean') {
+            throw new ValidationError('success must be a boolean');
+        }
+        if (typeof body.duration_ms !== 'number' || body.duration_ms < 0) {
+            throw new ValidationError('duration_ms must be a non-negative number');
+        }
+        if (typeof body.tool_calls !== 'number' || body.tool_calls < 0) {
+            throw new ValidationError('tool_calls must be a non-negative number');
+        }
+        if (typeof body.policy_violations !== 'number' || body.policy_violations < 0) {
+            throw new ValidationError('policy_violations must be a non-negative number');
+        }
+    }
+    // ── Error handling ───────────────────────────────────────────
+    errorHandler(err, _req, res, _next) {
+        if (err instanceof ValidationError) {
+            res.status(400).json({ error: err.message });
+            return;
+        }
+        console.error('[ATEL] Unhandled error:', err);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+}
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}

package/dist/service/server.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Standalone server entry point.
+ *
+ * Usage:
+ *   ATEL_PORT=3100 ATEL_DATA_DIR=./data tsx src/service/server.ts
+ */
+export {};

package/dist/service/server.js

@@ -0,0 +1,22 @@
+/**
+ * Standalone server entry point.
+ *
+ * Usage:
+ *   ATEL_PORT=3100 ATEL_DATA_DIR=./data tsx src/service/server.ts
+ */
+import { TrustScoreService } from './index.js';
+const service = new TrustScoreService({
+    port: parseInt(process.env.ATEL_PORT || '3100', 10),
+    dataDir: process.env.ATEL_DATA_DIR || './data',
+});
+service.start().then(() => {
+    console.log('ATEL Trust Score Service started');
+});
+// Graceful shutdown
+const shutdown = async () => {
+    console.log('\n[ATEL] Shutting down...');
+    await service.stop();
+    process.exit(0);
+};
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/dist/trace/index.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Module 5: Execution Trace
+ *
+ * Tamper-evident execution trace built on a hash chain.
+ * Every event links to the previous event's hash, forming
+ * an append-only, verifiable log of agent activity.
+ */
+import type { AgentIdentity } from '../identity/index.js';
+/** All recognized trace event types */
+export type TraceEventType = 'TASK_ACCEPTED' | 'TOOL_CALL' | 'TOOL_RESULT' | 'POLICY_CHECK' | 'POLICY_VIOLATION' | 'CHECKPOINT' | 'TASK_RESULT' | 'TASK_FAILED' | 'ROLLBACK';
+/** A single event in the execution trace */
+export interface TraceEvent {
+    /** Monotonically increasing sequence number (0-based) */
+    seq: number;
+    /** ISO 8601 timestamp */
+    ts: string;
+    /** Event type */
+    type: TraceEventType;
+    /** Task this event belongs to */
+    task_id: string;
+    /** Event-specific payload */
+    data: Record<string, unknown>;
+    /** Hash of the previous event ("0x00" for the first event) */
+    prev: string;
+    /** Hash of this event */
+    hash: string;
+    /** Optional signature (present on CHECKPOINT events) */
+    sig?: string;
+}
+/** Options for ExecutionTrace construction */
+export interface TraceOptions {
+    /** Number of events between automatic checkpoints (default: 50) */
+    checkpointInterval?: number;
+    /** Persistence options */
+    storage?: TraceStorageOptions;
+}
+/** Options for trace file persistence */
+export interface TraceStorageOptions {
+    /** Directory to store trace files */
+    dir: string;
+    /** Whether to auto-save after each append (default: false) */
+    autoSave: boolean;
+}
+/** Statistics about the trace */
+export interface TraceStats {
+    task_id: string;
+    event_count: number;
+    tool_calls: number;
+    tool_results: number;
+    policy_checks: number;
+    policy_violations: number;
+    checkpoints: number;
+    first_event_ts: string | null;
+    last_event_ts: string | null;
+    duration_ms: number | null;
+    finalized: boolean;
+    failed: boolean;
+}
+/**
+ * Compute the hash of a trace event.
+ *
+ * Formula:
+ * ```
+ * SHA256( seq + "|" + ts + "|" + type + "|" + SHA256(sortedStringify(data)) + "|" + prev_hash )
+ * ```
+ *
+ * @param seq - Sequence number.
+ * @param ts - ISO 8601 timestamp.
+ * @param type - Event type.
+ * @param data - Event data payload.
+ * @param prev - Previous event hash.
+ * @returns Hex-encoded SHA-256 hash.
+ */
+export declare function computeEventHash(seq: number, ts: string, type: string, data: Record<string, unknown>, prev: string): string;
+/**
+ * Tamper-evident, append-only execution trace.
+ *
+ * Each event is hash-chained to the previous one. Periodic checkpoints
+ * include a signature from the agent identity for non-repudiation.
+ */
+export declare class ExecutionTrace {
+    private readonly taskId;
+    private readonly identity;
+    private readonly checkpointInterval;
+    private readonly storage?;
+    private readonly events;
+    private seq;
+    private finalized;
+    private failed;
+    private eventsSinceCheckpoint;
+    /**
+     * @param taskId - Unique identifier for the task being traced.
+     * @param agentIdentity - The agent's cryptographic identity (for signing).
+     * @param options - Optional configuration.
+     */
+    constructor(taskId: string, agentIdentity: AgentIdentity, options?: TraceOptions);
+    /**
+     * Append a new event to the trace.
+     *
+     * Automatically triggers a checkpoint when the configured interval is reached.
+     *
+     * @param type - The event type.
+     * @param data - Event-specific data payload.
+     * @returns The created TraceEvent.
+     * @throws If the trace has already been finalized or failed.
+     */
+    append(type: TraceEventType, data: Record<string, unknown>): TraceEvent;
+    /**
+     * Create a checkpoint event with a signature.
+     *
+     * The checkpoint captures cumulative statistics and a Merkle root
+     * placeholder (full Merkle tree is built in Module 6).
+     *
+     * @returns The checkpoint TraceEvent.
+     */
+    checkpoint(): TraceEvent;
+    /**
+     * Finalize the trace with a TASK_RESULT event.
+     *
+     * @param result - The task result data.
+     * @returns The hash of the final event (trace_hash).
+     */
+    finalize(result: Record<string, unknown>): string;
+    /**
+     * Mark the trace as failed with a TASK_FAILED event.
+     *
+     * @param error - Error information.
+     * @returns The TASK_FAILED event.
+     */
+    fail(error: Record<string, unknown> | Error): TraceEvent;
+    /**
+     * Verify the integrity of the entire hash chain.
+     *
+     * Recomputes every event hash and checks it matches the stored hash,
+     * and that each event's `prev` matches the preceding event's hash.
+     *
+     * @returns True if the chain is intact, false otherwise.
+     */
+    verify(): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Export the trace as a JSONL (JSON Lines) string.
+     *
+     * @returns Each event serialized as one JSON line.
+     */
+    export(): string;
+    /**
+     * Export the trace to a file in JSONL format.
+     *
+     * @param path - File path to write to.
+     */
+    exportToFile(path: string): Promise<void>;
+    /**
+     * Return a copy of all events.
+     *
+     * @returns Array of TraceEvent objects.
+     */
+    getEvents(): ReadonlyArray<TraceEvent>;
+    /**
+     * Return statistics about the trace.
+     *
+     * @returns A TraceStats object.
+     */
+    getStats(): TraceStats;
+    /**
+     * Get the task ID for this trace.
+     */
+    getTaskId(): string;
+    /**
+     * Check whether the trace has been finalized.
+     */
+    isFinalized(): boolean;
+    /**
+     * Check whether the trace has been marked as failed.
+     */
+    isFailed(): boolean;
+    /**
+     * Save the entire trace to a JSONL file.
+     *
+     * @param filePath - Optional file path. Defaults to `{storage.dir}/{task_id}.trace.jsonl`.
+     * @throws If no filePath is provided and no storage options are configured.
+     */
+    saveToFile(filePath?: string): void;
+    /**
+     * Load a trace from a JSONL file.
+     *
+     * Reconstructs the ExecutionTrace with all events, preserving
+     * the hash chain. Requires an AgentIdentity for signature verification.
+     *
+     * @param filePath - Path to the JSONL trace file.
+     * @param agentIdentity - The agent identity to associate with the loaded trace.
+     * @returns A reconstructed ExecutionTrace.
+     */
+    static loadFromFile(filePath: string, agentIdentity: AgentIdentity): ExecutionTrace;
+    /**
+     * Get the default storage file path.
+     *
+     * @returns The file path, or undefined if no storage is configured.
+     */
+    private getStoragePath;
+    /**
+     * Append a single event to the storage file.
+     *
+     * @param event - The event to append.
+     */
+    private appendEventToFile;
+    /**
+     * Compute a simple Merkle root from a list of hex hashes.
+     * Used internally for checkpoint data.
+     *
+     * @param leaves - Array of hex-encoded hashes.
+     * @returns Hex-encoded Merkle root.
+     */
+    private simpleMerkleRoot;
+}