@peac/adapter-openclaw 0.10.7

package/dist/plugin.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @peac/adapter-openclaw - Plugin Entry Point
+ *
+ * OpenClaw plugin types and utilities for PEAC receipts.
+ * This module provides types and factory functions for OpenClaw integration.
+ *
+ * Note: Full plugin activation requires OpenClaw's plugin runtime.
+ * The types and utilities here allow building custom integrations.
+ */
+import type { CaptureSession, SpoolStore, DedupeIndex } from '@peac/capture-core';
+import type { OpenClawAdapterConfig } from './types.js';
+import { type OpenClawHookHandler } from './hooks.js';
+import { type Signer, type ReceiptWriter, type BackgroundEmitterService } from './emitter.js';
+/**
+ * JSON Web Key structure for signing keys (Ed25519).
+ */
+export interface JWK {
+    kty: string;
+    crv?: string;
+    x?: string;
+    d?: string;
+    kid?: string;
+    alg?: string;
+    use?: string;
+}
+/**
+ * Plugin configuration from openclaw.plugin.json configSchema.
+ *
+ * @experimental This interface is experimental and may change.
+ */
+export interface PluginConfig {
+    enabled?: boolean;
+    output_dir?: string;
+    capture?: {
+        mode?: 'hash_only' | 'allowlist';
+        allowlist?: string[];
+        max_payload_size?: number;
+    };
+    signing: {
+        key_ref: string;
+        issuer: string;
+        audience?: string;
+    };
+    correlation?: {
+        include_workflow?: boolean;
+    };
+    background?: {
+        drain_interval_ms?: number;
+        batch_size?: number;
+    };
+}
+/**
+ * OpenClaw plugin context provided by the runtime.
+ */
+export interface PluginContext {
+    /** Plugin configuration from gateway config */
+    config: PluginConfig;
+    /** Agent workspace directory */
+    workspaceDir: string;
+    /** Logger instance */
+    logger: PluginLogger;
+    /** Register a tool call hook */
+    onToolCall: (handler: ToolCallHandler) => void;
+    /** Register a tool result hook */
+    onToolResult: (handler: ToolResultHandler) => void;
+    /** Register tools */
+    registerTools: (tools: PluginTool[]) => void;
+}
+/**
+ * Plugin logger interface.
+ */
+export interface PluginLogger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Tool call event from OpenClaw.
+ */
+export interface ToolCallEvent {
+    tool_call_id: string;
+    run_id: string;
+    session_key?: string;
+    tool_name: string;
+    tool_provider?: string;
+    input: unknown;
+    started_at: string;
+}
+/**
+ * Tool result event from OpenClaw.
+ */
+export interface ToolResultEvent {
+    tool_call_id: string;
+    run_id: string;
+    session_key?: string;
+    tool_name: string;
+    output: unknown;
+    completed_at: string;
+    status: 'ok' | 'error' | 'timeout' | 'canceled';
+    error_code?: string;
+}
+/**
+ * Tool call handler function.
+ */
+export type ToolCallHandler = (event: ToolCallEvent) => void | Promise<void>;
+/**
+ * Tool result handler function.
+ */
+export type ToolResultHandler = (event: ToolResultEvent) => void | Promise<void>;
+/**
+ * Plugin tool definition.
+ */
+export interface PluginTool {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+    execute: (params: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Create a signer from a JWK private key.
+ *
+ * @param jwk - Ed25519 private key in JWK format
+ * @param issuer - Issuer URI for receipts
+ * @param audience - Optional audience URI
+ * @returns Signer instance
+ */
+export declare function createJwkSigner(jwk: JWK, issuer: string, audience?: string): Signer;
+/**
+ * Resolve a signer from a key reference string.
+ *
+ * Supported formats:
+ * - env:VAR_NAME - Load key from environment variable
+ * - file:/path - Load from file (development only)
+ *
+ * @param keyRef - Key reference string
+ * @param issuer - Issuer URI
+ * @param audience - Optional audience URI
+ * @returns Promise resolving to Signer
+ */
+export declare function resolveSigner(keyRef: string, issuer: string, audience?: string): Promise<Signer>;
+/**
+ * Generate a key ID from a JWK by hashing its public components.
+ */
+export declare function generateKeyId(jwk: JWK): string;
+/**
+ * Create a file system receipt writer with atomic writes.
+ *
+ * Writes are atomic: write to .tmp, fsync, rename. This ensures
+ * partially written files are never observable.
+ *
+ * @param outputDir - Directory for receipt files
+ * @returns Promise resolving to ReceiptWriter
+ */
+export declare function createFileReceiptWriter(outputDir: string): Promise<ReceiptWriter>;
+/**
+ * Plugin instance state.
+ */
+export interface PluginInstance {
+    /** Capture session */
+    session: CaptureSession;
+    /** Hook handler for tool calls */
+    hookHandler: OpenClawHookHandler;
+    /** Background emitter service */
+    backgroundService: BackgroundEmitterService;
+    /** Start the plugin */
+    start(): void;
+    /** Stop the plugin */
+    stop(): Promise<void>;
+    /** Get plugin stats */
+    getStats(): PluginStats;
+}
+/**
+ * Plugin statistics.
+ */
+export interface PluginStats {
+    totalCaptured: number;
+    duplicatesSkipped: number;
+    pendingCount: number;
+    totalEmitted: number;
+    totalErrors: number;
+    keyId: string;
+    isRunning: boolean;
+}
+/**
+ * Options for creating a plugin instance.
+ */
+export interface CreatePluginOptions {
+    /** Signer for receipts */
+    signer: Signer;
+    /** Receipt writer */
+    writer: ReceiptWriter;
+    /** Adapter configuration */
+    adapterConfig?: OpenClawAdapterConfig;
+    /** Spool store implementation (required) */
+    store: SpoolStore;
+    /** Dedupe index implementation (required) */
+    dedupe: DedupeIndex;
+    /** Background drain interval in ms (default: 1000) */
+    drainIntervalMs?: number;
+    /** Batch size for draining (default: 100) */
+    batchSize?: number;
+    /** Error callback */
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a plugin instance.
+ *
+ * @param options - Plugin options
+ * @returns Plugin instance
+ */
+export declare function createPluginInstance(options: CreatePluginOptions): Promise<PluginInstance>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

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

package/dist/plugin.js

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * @peac/adapter-openclaw - Plugin Entry Point
+ *
+ * OpenClaw plugin types and utilities for PEAC receipts.
+ * This module provides types and factory functions for OpenClaw integration.
+ *
+ * Note: Full plugin activation requires OpenClaw's plugin runtime.
+ * The types and utilities here allow building custom integrations.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJwkSigner = createJwkSigner;
+exports.resolveSigner = resolveSigner;
+exports.generateKeyId = generateKeyId;
+exports.createFileReceiptWriter = createFileReceiptWriter;
+exports.createPluginInstance = createPluginInstance;
+const capture_core_1 = require("@peac/capture-core");
+const crypto_1 = require("@peac/crypto");
+const hooks_js_1 = require("./hooks.js");
+const emitter_js_1 = require("./emitter.js");
+// =============================================================================
+// Signer Creation
+// =============================================================================
+/**
+ * Create a signer from a JWK private key.
+ *
+ * @param jwk - Ed25519 private key in JWK format
+ * @param issuer - Issuer URI for receipts
+ * @param audience - Optional audience URI
+ * @returns Signer instance
+ */
+function createJwkSigner(jwk, issuer, audience) {
+    const kid = jwk.kid || generateKeyId(jwk);
+    // Extract the private key bytes from JWK
+    if (!jwk.d) {
+        throw new Error('JWK must include private key (d parameter)');
+    }
+    // Decode base64url to get raw key bytes
+    const privateKeyBytes = (0, crypto_1.base64urlDecode)(jwk.d);
+    return {
+        async sign(payload) {
+            return (0, crypto_1.sign)(payload, privateKeyBytes, kid);
+        },
+        getKeyId() {
+            return kid;
+        },
+        getIssuer() {
+            return issuer;
+        },
+        getAudience() {
+            return audience;
+        },
+    };
+}
+/**
+ * Resolve a signer from a key reference string.
+ *
+ * Supported formats:
+ * - env:VAR_NAME - Load key from environment variable
+ * - file:/path - Load from file (development only)
+ *
+ * @param keyRef - Key reference string
+ * @param issuer - Issuer URI
+ * @param audience - Optional audience URI
+ * @returns Promise resolving to Signer
+ */
+async function resolveSigner(keyRef, issuer, audience) {
+    const colonIndex = keyRef.indexOf(':');
+    if (colonIndex === -1) {
+        throw new Error(`Invalid key reference format: ${keyRef}. Expected scheme:value`);
+    }
+    const scheme = keyRef.slice(0, colonIndex);
+    const value = keyRef.slice(colonIndex + 1);
+    switch (scheme) {
+        case 'env': {
+            const keyData = process.env[value];
+            if (!keyData) {
+                throw new Error(`Environment variable ${value} not set for signing key`);
+            }
+            const jwk = JSON.parse(keyData);
+            return createJwkSigner(jwk, issuer, audience);
+        }
+        case 'file': {
+            const fs = await Promise.resolve().then(() => __importStar(require('fs')));
+            const keyData = await fs.promises.readFile(value, 'utf-8');
+            const jwk = JSON.parse(keyData);
+            return createJwkSigner(jwk, issuer, audience);
+        }
+        case 'keychain':
+            throw new Error('Keychain signing not yet implemented. Use env: for development.');
+        case 'sidecar':
+            throw new Error('Sidecar signing not yet implemented. Use env: for development.');
+        default:
+            throw new Error(`Unknown key reference scheme: ${scheme}. Use env: or file:`);
+    }
+}
+/**
+ * Generate a key ID from a JWK by hashing its public components.
+ */
+function generateKeyId(jwk) {
+    const publicPart = jwk.x || '';
+    let hash = 0;
+    for (let i = 0; i < publicPart.length; i++) {
+        const char = publicPart.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash;
+    }
+    return `k_${Math.abs(hash).toString(16).padStart(8, '0')}`;
+}
+// =============================================================================
+// Receipt Writer
+// =============================================================================
+/**
+ * Create a file system receipt writer with atomic writes.
+ *
+ * Writes are atomic: write to .tmp, fsync, rename. This ensures
+ * partially written files are never observable.
+ *
+ * @param outputDir - Directory for receipt files
+ * @returns Promise resolving to ReceiptWriter
+ */
+async function createFileReceiptWriter(outputDir) {
+    const fs = await Promise.resolve().then(() => __importStar(require('fs')));
+    const pathModule = await Promise.resolve().then(() => __importStar(require('path')));
+    // Use path.resolve for portability
+    const resolvedOutputDir = pathModule.resolve(outputDir);
+    // Ensure directory exists
+    await fs.promises.mkdir(resolvedOutputDir, { recursive: true });
+    return {
+        async write(receipt) {
+            const filename = `${receipt.rid}.peac.json`;
+            const filepath = pathModule.join(resolvedOutputDir, filename);
+            const tempPath = `${filepath}.tmp`;
+            const content = JSON.stringify({
+                rid: receipt.rid,
+                interaction_id: receipt.interaction_id,
+                entry_digest: receipt.entry_digest,
+                _jws: receipt.jws,
+            }, null, 2);
+            // Atomic write: write to .tmp, fsync, rename, fsync dir
+            await fs.promises.writeFile(tempPath, content, 'utf-8');
+            // fsync file for durability (open, sync, close)
+            const fd = await fs.promises.open(tempPath, 'r');
+            await fd.sync();
+            await fd.close();
+            // Atomic rename (POSIX guarantees atomicity)
+            await fs.promises.rename(tempPath, filepath);
+            // fsync parent directory for full crash durability (POSIX best practice)
+            // This ensures the rename is persisted even on power loss
+            // Best-effort: may fail on some platforms (Windows, network FS)
+            try {
+                const dirFd = await fs.promises.open(resolvedOutputDir, 'r');
+                await dirFd.sync();
+                await dirFd.close();
+            }
+            catch {
+                // Directory fsync not supported on this platform - continue anyway
+                // Receipt is still atomic via rename, just not fully durable on power loss
+            }
+            return filepath;
+        },
+        async close() {
+            // No-op for file writer
+        },
+    };
+}
+/**
+ * Create a plugin instance.
+ *
+ * @param options - Plugin options
+ * @returns Plugin instance
+ */
+async function createPluginInstance(options) {
+    const { signer, writer, adapterConfig, store, dedupe, drainIntervalMs = 1000, batchSize = 100, onError, } = options;
+    // Create hasher
+    const hasher = await (0, capture_core_1.createHasher)();
+    // Create capture session
+    const session = (0, capture_core_1.createCaptureSession)({
+        store,
+        dedupe,
+        hasher,
+    });
+    // Track stats
+    const stats = {
+        totalCaptured: 0,
+        duplicatesSkipped: 0,
+        pendingCount: 0,
+        totalEmitted: 0,
+        totalErrors: 0,
+        keyId: signer.getKeyId(),
+        isRunning: false,
+    };
+    // Create hook handler
+    const hookHandler = (0, hooks_js_1.createHookHandler)({
+        session,
+        config: adapterConfig,
+        onCapture: (result) => {
+            if (result.success) {
+                stats.totalCaptured++;
+                stats.pendingCount++;
+            }
+            else {
+                stats.duplicatesSkipped++;
+            }
+        },
+    });
+    // Create receipt emitter
+    const emitter = (0, emitter_js_1.createReceiptEmitter)({
+        signer,
+        writer,
+        onEmit: (result) => {
+            if (result.success) {
+                stats.totalEmitted++;
+                stats.pendingCount = Math.max(0, stats.pendingCount - 1);
+            }
+        },
+        onError: (error) => {
+            stats.totalErrors++;
+            if (onError)
+                onError(error);
+        },
+    });
+    // Track last emitted sequence for cursor-based emission
+    // This is the in-memory cursor; on restart, we rebuild from dedupe index
+    let lastEmittedSequence = 0;
+    // Mutex to prevent overlapping drain cycles
+    let drainInProgress = false;
+    // Create background service with proper cursor tracking
+    // Note: For full restart safety, the dedupe index should be persistent.
+    // The getPendingEntries filters out already-emitted entries using the dedupe index.
+    const backgroundService = (0, emitter_js_1.createBackgroundService)({
+        emitter,
+        drainIntervalMs,
+        getPendingEntries: async () => {
+            // Prevent overlapping drain cycles
+            if (drainInProgress)
+                return [];
+            drainInProgress = true;
+            try {
+                // Read entries after the last emitted sequence
+                const currentSequence = await store.getSequence();
+                if (currentSequence <= lastEmittedSequence)
+                    return [];
+                // Read from cursor position
+                const entries = await store.read(lastEmittedSequence, batchSize);
+                // Filter out entries that are already emitted (restart safety)
+                // This uses the persistent dedupe index as source of truth
+                const pending = [];
+                for (const entry of entries) {
+                    if (entry.sequence <= lastEmittedSequence)
+                        continue;
+                    // Check if already emitted in dedupe index
+                    const dedupeEntry = await dedupe.get(entry.action.id);
+                    if (dedupeEntry?.emitted)
+                        continue;
+                    pending.push(entry);
+                }
+                return pending;
+            }
+            finally {
+                drainInProgress = false;
+            }
+        },
+        markEmitted: async (digest) => {
+            // Find the entry with this digest and update cursor
+            const entries = await store.read(lastEmittedSequence, batchSize);
+            const entry = entries.find((e) => e.entry_digest === digest);
+            if (entry) {
+                // Update in-memory cursor
+                if (entry.sequence > lastEmittedSequence) {
+                    lastEmittedSequence = entry.sequence;
+                }
+                // Mark in persistent dedupe index (restart-safe)
+                await dedupe.markEmitted(entry.action.id);
+            }
+        },
+        onError,
+    });
+    return {
+        session,
+        hookHandler,
+        backgroundService,
+        start() {
+            stats.isRunning = true;
+            backgroundService.start();
+        },
+        async stop() {
+            backgroundService.stop();
+            await backgroundService.drain();
+            await hookHandler.close();
+            stats.isRunning = false;
+        },
+        getStats() {
+            return { ...stats };
+        },
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

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

package/dist/tools.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @peac/adapter-openclaw - Plugin Tools
+ *
+ * Tools exposed by the PEAC receipts plugin for OpenClaw.
+ *
+ * @experimental This module is experimental and may change.
+ */
+import type { PluginTool, PluginLogger } from './plugin.js';
+/**
+ * Plugin stats interface matching plugin.ts PluginStats.
+ */
+interface PluginStats {
+    totalCaptured: number;
+    duplicatesSkipped: number;
+    pendingCount: number;
+    totalEmitted: number;
+    totalErrors: number;
+    keyId: string;
+    isRunning: boolean;
+}
+/**
+ * Create the peac_receipts.status tool.
+ * Shows spool size, last receipt time, and config summary.
+ */
+export declare function createStatusTool(stats: PluginStats, outputDir: string): PluginTool;
+/**
+ * Create the peac_receipts.export_bundle tool.
+ * Exports receipts as a bundle directory for audit.
+ *
+ * Note: Creates a directory structure, not a ZIP archive.
+ * Use @peac/audit createDisputeBundle for production ZIP bundles.
+ */
+export declare function createExportBundleTool(outputDir: string, logger: PluginLogger): PluginTool;
+/**
+ * Create the peac_receipts.verify tool.
+ * Verifies a receipt or bundle offline.
+ */
+export declare function createVerifyTool(logger: PluginLogger): PluginTool;
+/**
+ * Create the peac_receipts.query tool.
+ * Query receipts by workflow_id, tool name, or time range.
+ */
+export declare function createQueryTool(outputDir: string, logger: PluginLogger): PluginTool;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAiC5D;;GAEG;AACH,UAAU,WAAW;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,CAoElF;AA4BD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,UAAU,CA2J1F;AAoBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAmDjE;AA6RD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,UAAU,CAoNnF"}