@dcyfr/ai 2.1.3 → 3.0.0

package/dist/ai/src/plugins/permissions/permission-audit-logger.js

@@ -0,0 +1,176 @@
+/**
+ * Permission Audit Logger
+ *
+ * Logs permission events to Axiom (when configured) or to
+ * stdout/stderr as a fallback. Used by the enforcer and validator
+ * to create an immutable audit trail for each plugin execution.
+ *
+ * @module plugins/permissions/permission-audit-logger
+ * @version 1.0.0
+ * @date 2026-02-28
+ * @license MIT
+ */
+const AXIOM_INGEST_URL = 'https://api.axiom.co/v1/datasets';
+/**
+ * Formats an audit event as a compact JSONL line for stdout/stderr.
+ */
+function formatForConsole(event) {
+    return JSON.stringify({
+        timestamp: event.timestamp,
+        eventType: event.eventType,
+        pluginId: event.pluginId,
+        category: event.category,
+        action: event.action,
+        resource: event.resource,
+        granted: event.granted,
+        reason: event.reason,
+    });
+}
+/**
+ * Logs permission audit events to Axiom or stdout.
+ *
+ * @example
+ * ```ts
+ * const logger = new PermissionAuditLogger({ axiomDataset: 'dcyfr-plugins' });
+ * await logger.log({
+ *   timestamp: new Date().toISOString(),
+ *   eventType: 'permission_granted',
+ *   pluginId: 'my-plugin',
+ *   pluginVersion: '1.0.0',
+ *   category: 'filesystem',
+ *   action: 'read',
+ *   resource: '/src/index.ts',
+ *   granted: true,
+ * });
+ * ```
+ */
+export class PermissionAuditLogger {
+    dataset;
+    token;
+    alwaysConsole;
+    constructor(config) {
+        this.dataset =
+            config?.axiomDataset ?? process.env['AXIOM_DATASET'];
+        this.token =
+            config?.axiomToken ?? process.env['AXIOM_TOKEN'];
+        this.alwaysConsole = config?.alwaysConsole ?? false;
+    }
+    /**
+     * Whether Axiom is configured and events will be sent there.
+     */
+    get isAxiomEnabled() {
+        return Boolean(this.dataset && this.token);
+    }
+    /**
+     * Log a single permission audit event.
+     * Returns a result object describing where the event was sent.
+     */
+    async log(event) {
+        if (this.alwaysConsole) {
+            this.writeToConsole(event);
+        }
+        if (this.isAxiomEnabled) {
+            return this.sendToAxiom(event);
+        }
+        if (!this.alwaysConsole) {
+            this.writeToConsole(event);
+        }
+        return { destination: 'stdout', success: true };
+    }
+    /**
+     * Log multiple events in a single batch request (Axiom supports this).
+     */
+    async logBatch(events) {
+        if (events.length === 0)
+            return [];
+        if (this.alwaysConsole) {
+            for (const ev of events)
+                this.writeToConsole(ev);
+        }
+        if (this.isAxiomEnabled) {
+            return this.sendBatchToAxiom(events);
+        }
+        if (!this.alwaysConsole) {
+            for (const ev of events)
+                this.writeToConsole(ev);
+        }
+        return events.map(() => ({ destination: 'stdout', success: true }));
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    writeToConsole(event) {
+        const line = formatForConsole(event);
+        if (event.granted) {
+            process.stdout.write(`${line}\n`);
+        }
+        else {
+            process.stderr.write(`${line}\n`);
+        }
+    }
+    async sendToAxiom(event) {
+        try {
+            const url = `${AXIOM_INGEST_URL}/${this.dataset}/ingest`;
+            const resp = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    'Content-Type': 'application/x-ndjson',
+                },
+                body: JSON.stringify(event) + '\n',
+            });
+            if (!resp.ok) {
+                const err = `Axiom ingest failed: ${resp.status} ${resp.statusText}`;
+                process.stderr.write(`[PermissionAuditLogger] ${err}\n`);
+                // Fall back to console when Axiom rejects
+                this.writeToConsole(event);
+                return { destination: 'axiom', success: false, error: err };
+            }
+            return { destination: 'axiom', success: true };
+        }
+        catch (error_) {
+            const msg = error_ instanceof Error ? error_.message : String(error_);
+            process.stderr.write(`[PermissionAuditLogger] Axiom fetch error: ${msg}\n`);
+            this.writeToConsole(event);
+            return { destination: 'axiom', success: false, error: msg };
+        }
+    }
+    async sendBatchToAxiom(events) {
+        try {
+            const url = `${AXIOM_INGEST_URL}/${this.dataset}/ingest`;
+            const body = events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+            const resp = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    'Content-Type': 'application/x-ndjson',
+                },
+                body,
+            });
+            if (!resp.ok) {
+                const err = `Axiom batch ingest failed: ${resp.status} ${resp.statusText}`;
+                process.stderr.write(`[PermissionAuditLogger] ${err}\n`);
+                for (const ev of events)
+                    this.writeToConsole(ev);
+                return events.map(() => ({
+                    destination: 'axiom',
+                    success: false,
+                    error: err,
+                }));
+            }
+            return events.map(() => ({ destination: 'axiom', success: true }));
+        }
+        catch (error_) {
+            const msg = error_ instanceof Error ? error_.message : String(error_);
+            process.stderr.write(`[PermissionAuditLogger] Axiom batch fetch error: ${msg}\n`);
+            for (const ev of events)
+                this.writeToConsole(ev);
+            return events.map(() => ({
+                destination: 'axiom',
+                success: false,
+                error: msg,
+            }));
+        }
+    }
+}
+//# sourceMappingURL=permission-audit-logger.js.map

package/dist/ai/src/plugins/permissions/permission-audit-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-audit-logger.js","sourceRoot":"","sources":["../../../../../packages/ai/src/plugins/permissions/permission-audit-logger.ts"],"names":[],"mappings":"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"}

package/dist/ai/src/plugins/permissions/permission-enforcer.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Runtime Permission Enforcement Layer
+ *
+ * Intercepts filesystem, network, and child_process operations at runtime
+ * to enforce declared plugin permissions. Wraps Node.js APIs with permission
+ * checks before delegating to the original implementation.
+ *
+ * @module plugins/permissions/permission-enforcer
+ * @version 1.0.0
+ * @date 2026-02-28
+ * @license MIT
+ */
+import type { PluginPermissions, PermissionAuditEvent } from './types.js';
+export interface EnforcementContext {
+    pluginId: string;
+    pluginVersion: string;
+    executionId?: string;
+    /** Called when a permission is granted. Optional — used for audit logging. */
+    onGrant?: (event: Omit<PermissionAuditEvent, 'timestamp'>) => void;
+    /** Called when a permission is denied. Optional — used for audit logging. */
+    onDeny?: (event: Omit<PermissionAuditEvent, 'timestamp'>) => void;
+}
+export interface RealFs {
+    readFile(path: string, options?: {
+        encoding?: BufferEncoding | null;
+    } | BufferEncoding | null): Promise<Buffer | string>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    unlink(path: string): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<string | undefined>;
+    readdir(path: string): Promise<string[] | Buffer[]>;
+    stat(path: string): Promise<{
+        isFile(): boolean;
+        size: number;
+        mtime: Date;
+    }>;
+}
+export interface EnforcedFsApis {
+    readFile(path: string, encoding?: BufferEncoding): Promise<string | Buffer>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    unlink(path: string): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<string | undefined>;
+    readdir(path: string): Promise<string[] | Buffer[]>;
+    stat(path: string): Promise<{
+        isFile(): boolean;
+        size: number;
+        mtime: Date;
+    }>;
+}
+export type EnforcedFetch = (url: string | URL, init?: RequestInit) => Promise<Response>;
+export interface EnforcedExec {
+    execFile(command: string, args?: string[]): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare class PermissionDeniedError extends Error {
+    readonly category: keyof PluginPermissions;
+    readonly action: string;
+    readonly resource: string;
+    readonly denialReason: string;
+    constructor(category: keyof PluginPermissions, action: string, resource: string, denialReason: string);
+}
+/**
+ * Wraps Node.js APIs with permission enforcement for a given plugin.
+ *
+ * Usage:
+ * ```ts
+ * const enforcer = new PermissionEnforcer(permissions, ctx);
+ * const safeFs = enforcer.createFsProxy(realFsPromises);
+ * const safeFetch = enforcer.createFetchProxy();
+ * ```
+ */
+export declare class PermissionEnforcer {
+    readonly permissions: PluginPermissions;
+    private readonly ctx;
+    private readonly validator;
+    constructor(permissions: PluginPermissions, ctx: EnforcementContext);
+    private emitGrant;
+    private emitDeny;
+    private enforce;
+    /**
+     * Create a `fs.promises`-compatible proxy for the plugin.
+     * Only the methods covered by declared permissions work; others throw.
+     */
+    createFsProxy(realFs: RealFs): EnforcedFsApis;
+    /**
+     * Create a `fetch`-compatible proxy that enforces network permissions.
+     */
+    createFetchProxy(realFetch?: typeof globalThis.fetch): EnforcedFetch;
+    /**
+     * Create an `execFile`-compatible proxy that enforces execution permissions.
+     */
+    createExecProxy(): EnforcedExec;
+}
+//# sourceMappingURL=permission-enforcer.d.ts.map

package/dist/ai/src/plugins/permissions/permission-enforcer.d.ts.map

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

package/dist/ai/src/plugins/permissions/permission-enforcer.js

@@ -0,0 +1,151 @@
+/**
+ * Runtime Permission Enforcement Layer
+ *
+ * Intercepts filesystem, network, and child_process operations at runtime
+ * to enforce declared plugin permissions. Wraps Node.js APIs with permission
+ * checks before delegating to the original implementation.
+ *
+ * @module plugins/permissions/permission-enforcer
+ * @version 1.0.0
+ * @date 2026-02-28
+ * @license MIT
+ */
+import { PluginPermissionValidator } from './plugin-permission-validator.js';
+// ---------------------------------------------------------------------------
+// Error type
+// ---------------------------------------------------------------------------
+export class PermissionDeniedError extends Error {
+    category;
+    action;
+    resource;
+    denialReason;
+    constructor(category, action, resource, denialReason) {
+        super(`Permission denied: [${category}] ${action} on "${resource}" — ${denialReason}`);
+        this.name = 'PermissionDeniedError';
+        this.category = category;
+        this.action = action;
+        this.resource = resource;
+        this.denialReason = denialReason;
+    }
+}
+// ---------------------------------------------------------------------------
+// Permission enforcer
+// ---------------------------------------------------------------------------
+/**
+ * Wraps Node.js APIs with permission enforcement for a given plugin.
+ *
+ * Usage:
+ * ```ts
+ * const enforcer = new PermissionEnforcer(permissions, ctx);
+ * const safeFs = enforcer.createFsProxy(realFsPromises);
+ * const safeFetch = enforcer.createFetchProxy();
+ * ```
+ */
+export class PermissionEnforcer {
+    permissions;
+    ctx;
+    validator;
+    constructor(permissions, ctx) {
+        this.permissions = permissions;
+        this.ctx = ctx;
+        this.validator = new PluginPermissionValidator(permissions);
+    }
+    emitGrant(category, action, resource) {
+        this.ctx.onGrant?.({
+            eventType: 'permission_granted',
+            pluginId: this.ctx.pluginId,
+            pluginVersion: this.ctx.pluginVersion,
+            executionId: this.ctx.executionId,
+            category,
+            action,
+            resource,
+            granted: true,
+        });
+    }
+    emitDeny(category, action, resource, reason) {
+        this.ctx.onDeny?.({
+            eventType: 'permission_denied',
+            pluginId: this.ctx.pluginId,
+            pluginVersion: this.ctx.pluginVersion,
+            executionId: this.ctx.executionId,
+            category,
+            action,
+            resource,
+            granted: false,
+            reason,
+        });
+    }
+    enforce(check, category, action, resource) {
+        if (check.granted) {
+            this.emitGrant(category, action, resource);
+        }
+        else {
+            const reason = check.reason ?? 'Permission denied';
+            this.emitDeny(category, action, resource, reason);
+            throw new PermissionDeniedError(category, action, resource, reason);
+        }
+    }
+    /**
+     * Create a `fs.promises`-compatible proxy for the plugin.
+     * Only the methods covered by declared permissions work; others throw.
+     */
+    createFsProxy(realFs) {
+        const validate = (check, category, action, resource) => this.enforce(check, category, action, resource);
+        const val = this.validator;
+        return {
+            readFile: async (path, encoding) => {
+                validate(val.checkFileRead(path), 'filesystem', 'read', path);
+                return realFs.readFile(path, encoding ?? null);
+            },
+            writeFile: async (path, data) => {
+                validate(val.checkFileWrite(path), 'filesystem', 'write', path);
+                await realFs.writeFile(path, data);
+            },
+            unlink: async (path) => {
+                validate(val.checkFileDelete(path), 'filesystem', 'delete', path);
+                await realFs.unlink(path);
+            },
+            mkdir: async (path, options) => {
+                validate(val.checkFileWrite(path), 'filesystem', 'mkdir', path);
+                return realFs.mkdir(path, options);
+            },
+            readdir: async (path) => {
+                validate(val.checkFileRead(path), 'filesystem', 'readdir', path);
+                return realFs.readdir(path);
+            },
+            stat: async (path) => {
+                validate(val.checkFileRead(path), 'filesystem', 'stat', path);
+                return realFs.stat(path);
+            },
+        };
+    }
+    /**
+     * Create a `fetch`-compatible proxy that enforces network permissions.
+     */
+    createFetchProxy(realFetch = globalThis.fetch) {
+        const validate = (check, category, action, resource) => this.enforce(check, category, action, resource);
+        const val = this.validator;
+        return async (url, init) => {
+            const urlStr = url.toString();
+            validate(val.checkNetworkRequest(urlStr), 'network', 'request', urlStr);
+            return realFetch(url, init);
+        };
+    }
+    /**
+     * Create an `execFile`-compatible proxy that enforces execution permissions.
+     */
+    createExecProxy() {
+        const validate = (check, category, action, resource) => this.enforce(check, category, action, resource);
+        const val = this.validator;
+        return {
+            execFile: async (command, args = []) => {
+                validate(val.checkCommandExecution(command), 'execution', 'execFile', command);
+                const { execFile: nodeExecFile } = await import('node:child_process');
+                const { promisify } = await import('node:util');
+                const execFileAsync = promisify(nodeExecFile);
+                return execFileAsync(command, args);
+            },
+        };
+    }
+}
+//# sourceMappingURL=permission-enforcer.js.map

package/dist/ai/src/plugins/permissions/permission-enforcer.js.map

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

package/dist/ai/src/plugins/permissions/plugin-permission-validator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Plugin Permission Validator
+ *
+ * Validates plugin permission requests against declared capabilities using
+ * glob pattern matching. Implements the capability-based least-privilege model.
+ *
+ * Uses Node.js v22+ built-in `path.matchesGlob()` for filesystem patterns.
+ *
+ * @module plugins/permissions/plugin-permission-validator
+ * @version 1.0.0
+ * @date 2026-02-28
+ * @license MIT
+ */
+import type { PluginPermissions, PermissionCheckResult } from './types.js';
+/** Stateless validator — create once and reuse across permission checks */
+export declare class PluginPermissionValidator {
+    private readonly permissions;
+    constructor(permissions: PluginPermissions);
+    /** Check if the plugin may read a given file/directory path */
+    checkFileRead(path: string): PermissionCheckResult;
+    /** Check if the plugin may write to a given file/directory path */
+    checkFileWrite(path: string): PermissionCheckResult;
+    /** Check if the plugin may delete a given file/directory path */
+    checkFileDelete(path: string): PermissionCheckResult;
+    /**
+     * Check if the plugin may make a network request to the given hostname.
+     * Pass `url` as a full URL string (e.g. "https://api.github.com/repos/...").
+     */
+    checkNetworkRequest(url: string): PermissionCheckResult;
+    /** Check if the plugin may execute a given command */
+    checkCommandExecution(command: string): PermissionCheckResult;
+    /** Check if the plugin may call a given MCP server */
+    checkMcpAccess(serverName: string): PermissionCheckResult;
+    /** Check if the plugin may access environment variables */
+    checkEnvAccess(): PermissionCheckResult;
+    /** Check if the plugin may access secrets */
+    checkSecretAccess(): PermissionCheckResult;
+}
+//# sourceMappingURL=plugin-permission-validator.d.ts.map

package/dist/ai/src/plugins/permissions/plugin-permission-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-permission-validator.d.ts","sourceRoot":"","sources":["../../../../../packages/ai/src/plugins/permissions/plugin-permission-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAgCpB,2EAA2E;AAC3E,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,iBAAiB;IAM3D,+DAA+D;IAC/D,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB;IA+BlD,mEAAmE;IACnE,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB;IA+BnD,iEAAiE;IACjE,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB;IAmCpD;;;OAGG;IACH,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB;IAiDvD,sDAAsD;IACtD,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB;IAgD7D,sDAAsD;IACtD,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,qBAAqB;IAwCzD,2DAA2D;IAC3D,cAAc,IAAI,qBAAqB;IAkBvC,6CAA6C;IAC7C,iBAAiB,IAAI,qBAAqB;CAa3C"}