daniel-ai-permissions-layer 0.2.0

package/LICENSE

@@ -0,0 +1,26 @@
+AI Permissions Layer
+Copyright (C) 2025
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+Full license text: https://www.gnu.org/licenses/gpl-3.0.html

package/README.md

@@ -0,0 +1,302 @@
+# AI Permissions Layer
+
+Middleware that intercepts AI agent tool calls, applies your rules, and returns **allow**, **block**, or **require approval**. Use it to control what your agent can do—block dangerous actions, require approval for sensitive ones, and allow safe operations by default.
+
+---
+
+## Table of Contents
+
+- [Quick Start (OpenClaw)](#quick-start-openclaw)
+- [Writing Rules](#writing-rules)
+- [OpenClaw Setup & Usage](#openclaw-setup--usage)
+- [Rule Reference](#rule-reference)
+- [Approval Flow](#approval-flow)
+- [Path Protection](#path-protection)
+- [Configuration](#configuration)
+- [Standalone Compile](#standalone-compile)
+- [Library Usage](#library-usage)
+
+---
+
+## Quick Start (OpenClaw)
+
+```bash
+openclaw plugins install ai-permissions-openclaw
+openclaw gateway restart
+openclaw ai-permissions compile
+```
+
+The first `compile` creates `~/.openclaw/rules.yaml` with starter rules if none exist. Edit `rules.yaml`, run `compile` again when you change rules, and you're done. No extra API keys needed if you've run `openclaw onboard`.
+
+---
+
+## Writing Rules
+
+Rules define what the agent can do. Each rule has an **action** and applies to one or more **tools**.
+
+### Actions
+
+| Action | Behavior |
+|--------|----------|
+| **block** | Tool is never allowed. The agent sees an error and cannot proceed. |
+| **require_approval** | Tool is blocked until you reply `APPROVE <uuid>` in chat. One-time approval per request. |
+| **allow** | Tool runs without asking. |
+
+### Plain-Text Format (YAML)
+
+Write rules in plain English, one per line, each starting with `-`:
+
+```yaml
+# Block dangerous actions
+- block gmail.delete and gmail.batchDelete - never auto-delete emails
+- block payments and money transfers - no financial actions
+
+# Require approval before risky operations
+- require approval before exec, bash, or process - ask before running commands
+- require approval before write, edit, apply_patch - ask before file changes
+
+# Allow safe read-only operations
+- allow read, search, list - safe read-only operations
+- allow gmail.list and gmail.get - reading emails is fine
+```
+
+**Compile** these into JSON with `openclaw ai-permissions compile` or `npx ai-permissions-compile --openclaw`. The compiler uses an LLM to infer tool names from your wording.
+
+### Compiler Language Hints
+
+The compiler maps natural language to actions:
+
+| You write | Action |
+|-----------|--------|
+| "block", "don't allow", "never" | `block` |
+| "ask me", "prompt me", "require approval", "before X" | `require_approval` |
+| "allow", "ok", "permit" | `allow` |
+
+Include tool names when you know them (e.g. `gmail.delete`, `write`, `exec`). The compiler will infer others (e.g. "payments" → `payments`, "money transfers" → `money_transfers`).
+
+### Compiled JSON Format
+
+After compiling, rules become JSON:
+
+```json
+{
+  "rules": [
+    { "action": "block", "tool": "gmail.delete", "reason": "never auto-delete emails" },
+    { "action": "require_approval", "tool": "write", "reason": "ask before file changes" },
+    { "action": "allow", "tool": "read", "reason": "safe read-only operations" }
+  ]
+}
+```
+
+Each rule: `action`, `tool`, `reason`. The plugin loads this file; you typically edit the YAML and recompile.
+
+### OpenClaw Tool Names
+
+Common OpenClaw tools to reference in rules:
+
+| Category | Tools |
+|----------|-------|
+| **Files** | `read`, `write`, `edit`, `apply_patch` |
+| **Runtime** | `exec`, `bash`, `process` |
+| **Gmail** | `gmail.list`, `gmail.get`, `gmail.send`, `gmail.delete`, `gmail.batchDelete` |
+| **Browser** | `browser_*`, `web_*` |
+| **Internal** | `pairing`, `device-pair`, `openclaw.*` (these bypass rules) |
+
+Internal tools (pairing, device-pair, openclaw.*) are never intercepted.
+
+### Rule Precedence
+
+- **block** wins over **require_approval** when both match the same tool.
+- First matching rule applies. Order matters when you have overlapping rules.
+- When **no rule matches**, behavior is set by `defaultWhenNoMatch` (default: `require_approval`).
+
+---
+
+## OpenClaw Setup & Usage
+
+### Installation
+
+```bash
+openclaw plugins install ai-permissions-openclaw
+openclaw gateway restart
+```
+
+### Compile Rules
+
+```bash
+# Default: ~/.openclaw/rules.yaml → ~/.openclaw/ai-permissions-rules.json
+openclaw ai-permissions compile
+
+# Custom input
+openclaw ai-permissions compile my-rules.yaml
+
+# Custom input and output
+openclaw ai-permissions compile my-rules.yaml ~/.openclaw/ai-permissions-rules.json
+```
+
+**First run:** If `~/.openclaw/rules.yaml` doesn't exist, it is created with starter rules and compiled.
+
+**Credentials:** Uses OpenClaw's primary model from `~/.openclaw/openclaw.json` and credentials from `~/.openclaw/.env`. Run `openclaw onboard` first if you haven't.
+
+### Workflow
+
+1. Edit `~/.openclaw/rules.yaml`
+2. Run `openclaw ai-permissions compile`
+3. Rules take effect immediately (plugin reloads on each tool call)
+4. Restart the gateway only when changing plugin config
+
+---
+
+## Rule Reference
+
+### Exact Tool Match
+
+Rules match by exact tool name:
+
+```yaml
+- block gmail.delete - no auto delete
+- allow read - read-only ok
+```
+
+### Multiple Tools per Rule
+
+List tools in one rule (compiler creates one JSON rule per tool):
+
+```yaml
+- block gmail.delete and gmail.batchDelete - never auto-delete emails
+- require approval before write, edit, apply_patch - ask before file changes
+```
+
+### Advanced: toolPattern and intentPattern (JSON only)
+
+For programmatic use, compiled rules can include:
+
+- **toolPattern** — regex to match tool names (e.g. `gmail\.(delete|batchDelete)`)
+- **intentPattern** — regex to match user intent text (optional)
+
+These are produced by the compiler when it infers patterns. You can also edit the JSON directly for fine-grained control.
+
+---
+
+## Approval Flow
+
+When a tool needs approval:
+
+1. The agent attempts the tool.
+2. The plugin blocks it and returns a message with a **request ID** (UUID).
+3. You reply in chat: `APPROVE <uuid>` to allow once, or `DENY <uuid>` to block.
+4. If you approved, the agent can retry the same action; the approval is consumed.
+
+**Example:**
+
+```
+Agent: I'll run `write` to save the file.
+[Blocked] [Approval required] ask before file changes
+Request ID: a1b2c3d4-...
+Reply APPROVE a1b2c3d4-... to allow, or DENY a1b2c3d4-... to block.
+
+You: APPROVE a1b2c3d4-...
+
+Agent: [retries the write; it succeeds]
+```
+
+---
+
+## Path Protection
+
+The plugin blocks the agent from modifying its own rules file. Writes to paths matching `**/rules*.json` or `**/.config/ai-permissions-layer/**` via `write`, `edit`, or `apply_patch` are blocked regardless of your rules.
+
+This is enabled by default. Disable or customize via `pathProtection` in plugin config.
+
+---
+
+## Configuration
+
+Edit `~/.openclaw/openclaw.json` under `plugins.entries.ai-permissions-openclaw.config`:
+
+| Option | Default | Description |
+|--------|---------|--------------|
+| `rulesPath` | `~/.openclaw/ai-permissions-rules.json` | Path to compiled rules JSON |
+| `defaultWhenNoMatch` | `require_approval` | When no rule matches: `allow`, `require_approval`, or `block` |
+| `pathProtection.enabled` | `true` | Block writes to rules file |
+| `pathProtection.dangerousTools` | `['write','edit','apply_patch']` | Tools that can write files (for path protection) |
+
+**Example:**
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "ai-permissions-openclaw": {
+        "enabled": true,
+        "config": {
+          "rulesPath": "~/.openclaw/ai-permissions-rules.json",
+          "defaultWhenNoMatch": "require_approval",
+          "pathProtection": {
+            "enabled": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Standalone Compile
+
+Without OpenClaw, use the npm CLI:
+
+```bash
+# With OpenAI (requires OPENAI_API_KEY)
+export OPENAI_API_KEY=your_key
+npx ai-permissions-compile examples/rules.yaml ~/.openclaw/ai-permissions-rules.json
+
+# With OpenClaw config (uses ~/.openclaw/.env and openclaw.json)
+npx ai-permissions-compile --openclaw examples/rules.yaml ~/.openclaw/ai-permissions-rules.json
+```
+
+**Format:** One rule per line, each starting with `-`. See [examples/rules.yaml](examples/rules.yaml).
+
+---
+
+## Library Usage
+
+```bash
+npm install ai-permissions-layer
+```
+
+```ts
+import { createMiddleware, match } from 'ai-permissions-layer';
+
+const rules = [
+  { action: 'block', tool: 'gmail.delete', reason: 'no delete' },
+  { action: 'require_approval', tool: 'gmail.send', reason: 'ask first' },
+  { action: 'allow', tool: 'read', reason: 'read-only ok' },
+];
+
+const middleware = createMiddleware(rules, executor, {
+  defaultWhenNoMatch: 'require_approval',
+  pathProtection: {},
+});
+
+const result = await middleware(
+  { toolName: 'gmail.delete', args: {} },
+  { text: 'delete emails' }
+);
+// result.decision === 'BLOCK', result.executed === false
+```
+
+---
+
+## Examples
+
+- [examples/rules.yaml](examples/rules.yaml) — plain-text rules
+- [examples/ai-permissions-rules.json](examples/ai-permissions-rules.json) — compiled JSON
+
+---
+
+## License
+
+GPL v3.

package/dist/adapters/openai-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { LLMAdapter } from '../llm-adapter.js';
+export declare function createOpenAIAdapter(apiKey: string, model?: string): LLMAdapter;

package/dist/adapters/openai-adapter.js

@@ -0,0 +1,19 @@
+export function createOpenAIAdapter(apiKey, model = 'gpt-4o-mini') {
+    return {
+        async complete(prompt) {
+            const res = await fetch('https://api.openai.com/v1/chat/completions', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({
+                    model,
+                    messages: [{ role: 'user', content: prompt }],
+                }),
+            });
+            const data = (await res.json());
+            return data.choices[0].message.content;
+        },
+    };
+}

package/dist/adapters/openclaw-adapter.d.ts

@@ -0,0 +1,6 @@
+import type { LLMAdapter } from '../llm-adapter.js';
+/**
+ * Create an LLM adapter that uses OpenClaw's primary model from ~/.openclaw/openclaw.json.
+ * Falls back to OpenAI if config is missing or model resolution fails.
+ */
+export declare function createOpenClawAdapter(fallbackApiKey?: string): LLMAdapter | null;

package/dist/adapters/openclaw-adapter.js

@@ -0,0 +1,202 @@
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+function resolvePath(p) {
+    if (p.startsWith('~'))
+        return path.join(os.homedir(), p.slice(1));
+    return path.resolve(p);
+}
+function loadOpenClawEnv() {
+    const envPath = resolvePath('~/.openclaw/.env');
+    if (!existsSync(envPath))
+        return;
+    try {
+        const content = readFileSync(envPath, 'utf-8');
+        for (const line of content.split('\n')) {
+            const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+            if (m && !(m[1] in process.env)) {
+                const val = m[2].replace(/^["']|["']$/g, '').trim();
+                process.env[m[1]] = val;
+            }
+        }
+    }
+    catch {
+        /* ignore */
+    }
+}
+function loadOpenClawConfig() {
+    const paths = [
+        resolvePath('~/.openclaw/openclaw.json'),
+        resolvePath('~/.config/openclaw/openclaw.json'),
+    ];
+    for (const p of paths) {
+        if (existsSync(p)) {
+            try {
+                return JSON.parse(readFileSync(p, 'utf-8'));
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+function resolveEnvValue(val) {
+    if (typeof val !== 'string')
+        return undefined;
+    const m = val.match(/^\$\{?([A-Z_][A-Z0-9_]*)\}?$/);
+    if (m)
+        return process.env[m[1]];
+    return val;
+}
+const BUILTIN_PROVIDERS = {
+    openai: {
+        baseUrl: 'https://api.openai.com/v1',
+        getApiKey: () => process.env.OPENAI_API_KEY,
+    },
+    ollama: {
+        baseUrl: 'http://127.0.0.1:11434/v1',
+        getApiKey: () => 'ollama',
+    },
+    'lm-studio': {
+        baseUrl: 'http://localhost:1234/v1',
+        getApiKey: () => 'lm-studio',
+    },
+    lmstudio: {
+        baseUrl: 'http://localhost:1234/v1',
+        getApiKey: () => 'lm-studio',
+    },
+    vllm: {
+        baseUrl: 'http://127.0.0.1:8000/v1',
+        getApiKey: () => '',
+    },
+};
+/**
+ * Create an LLM adapter that uses OpenClaw's primary model from ~/.openclaw/openclaw.json.
+ * Falls back to OpenAI if config is missing or model resolution fails.
+ */
+export function createOpenClawAdapter(fallbackApiKey) {
+    loadOpenClawEnv();
+    const config = loadOpenClawConfig();
+    if (!config)
+        return null;
+    const agents = (config.agents ?? config.agent);
+    const defaults = agents?.defaults;
+    const modelConfig = (defaults?.model ?? agents?.model);
+    const primary = modelConfig?.primary;
+    if (!primary || typeof primary !== 'string')
+        return null;
+    const slash = primary.indexOf('/');
+    const provider = slash >= 0 ? primary.slice(0, slash) : 'openai';
+    const modelId = slash >= 0 ? primary.slice(slash + 1) : primary;
+    const models = config.models;
+    const providers = models?.providers;
+    const providerConfig = providers?.[provider];
+    let baseUrl;
+    let apiKey;
+    if (providerConfig?.baseUrl) {
+        baseUrl = providerConfig.baseUrl.replace(/\/$/, '');
+        if (!baseUrl.endsWith('/v1'))
+            baseUrl += '/v1';
+        apiKey = resolveEnvValue(providerConfig.apiKey) ?? providerConfig.apiKey;
+    }
+    else {
+        const builtin = BUILTIN_PROVIDERS[provider] ?? BUILTIN_PROVIDERS.openai;
+        baseUrl = builtin.baseUrl;
+        apiKey = builtin.getApiKey();
+    }
+    if (!apiKey && provider === 'openai') {
+        apiKey = fallbackApiKey ?? process.env.OPENAI_API_KEY;
+    }
+    if (!apiKey && provider !== 'ollama' && provider !== 'lmstudio' && provider !== 'lm-studio' && provider !== 'vllm') {
+        return null;
+    }
+    const chatUrl = `${baseUrl}/chat/completions`;
+    const completionsUrl = `${baseUrl}/completions`;
+    const headers = {
+        'Content-Type': 'application/json',
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+    };
+    async function tryChatWithModel(model, p) {
+        const res = await fetch(chatUrl, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                model,
+                messages: [{ role: 'user', content: p }],
+            }),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`OpenClaw model request failed: ${res.status} ${err}`);
+        }
+        const data = (await res.json());
+        const content = data.choices?.[0]?.message?.content;
+        if (content == null)
+            throw new Error('No response content from model');
+        return content;
+    }
+    return {
+        async complete(prompt) {
+            const tryChat = async () => {
+                const res = await fetch(chatUrl, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({
+                        model: modelId,
+                        messages: [{ role: 'user', content: prompt }],
+                    }),
+                });
+                if (!res.ok) {
+                    const err = await res.text();
+                    if (res.status === 404 && /not a chat model|chat\/completions/i.test(err)) {
+                        throw new Error('USE_COMPLETIONS');
+                    }
+                    throw new Error(`OpenClaw model request failed: ${res.status} ${err}`);
+                }
+                const data = (await res.json());
+                const content = data.choices?.[0]?.message?.content;
+                if (content == null)
+                    throw new Error('No response content from model');
+                return content;
+            };
+            const tryCompletions = async () => {
+                const res = await fetch(completionsUrl, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({
+                        model: modelId,
+                        prompt,
+                    }),
+                });
+                if (!res.ok) {
+                    const err = await res.text();
+                    throw new Error(`OpenClaw model request failed: ${res.status} ${err}`);
+                }
+                const data = (await res.json());
+                const text = data.choices?.[0]?.text;
+                if (text == null)
+                    throw new Error('No response content from model');
+                return text.trim();
+            };
+            try {
+                return await tryChat();
+            }
+            catch (e) {
+                if (e instanceof Error && e.message === 'USE_COMPLETIONS') {
+                    try {
+                        return await tryCompletions();
+                    }
+                    catch {
+                        /* fall through to chat fallback */
+                    }
+                }
+                if (provider === 'openai' && apiKey) {
+                    console.error(`Primary model ${modelId} does not support chat; using gpt-4o-mini for compile`);
+                    return await tryChatWithModel('gpt-4o-mini', prompt);
+                }
+                throw e;
+            }
+        },
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { compile } from './compiler.js';
+import { createOpenAIAdapter } from './adapters/openai-adapter.js';
+import { createOpenClawAdapter } from './adapters/openclaw-adapter.js';
+async function main() {
+    const args = process.argv.slice(2);
+    const useOpenClaw = args.includes('--openclaw');
+    const filtered = args.filter((a) => a !== '--openclaw');
+    const inputFile = filtered[0] || 'rules.yaml';
+    const outputFile = filtered[1] || 'rules.compiled.json';
+    let llm;
+    if (useOpenClaw) {
+        const openClaw = createOpenClawAdapter(process.env.OPENAI_API_KEY);
+        if (openClaw) {
+            llm = openClaw;
+            console.error('Using OpenClaw primary model');
+        }
+        else {
+            const apiKey = process.env.OPENAI_API_KEY;
+            if (!apiKey) {
+                console.error('OpenClaw config not found or model unresolved. Set OPENAI_API_KEY or run openclaw onboard first.');
+                process.exit(1);
+            }
+            llm = createOpenAIAdapter(apiKey);
+            console.error('OpenClaw config not found, falling back to OpenAI');
+        }
+    }
+    else {
+        const apiKey = process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            console.error('OPENAI_API_KEY required');
+            process.exit(1);
+        }
+        llm = createOpenAIAdapter(apiKey);
+    }
+    if (!existsSync(inputFile)) {
+        console.error(`Input file not found: ${inputFile}`);
+        console.error('Usage: npx ai-permissions-compile [--openclaw] <input.yaml> [output.json]');
+        console.error('Example: npx ai-permissions-compile --openclaw examples/rules.yaml ~/.openclaw/ai-permissions-rules.json');
+        process.exit(1);
+    }
+    const content = readFileSync(inputFile, 'utf-8');
+    const rules = content
+        .split('\n')
+        .filter((l) => l.trim().startsWith('-'))
+        .map((l) => l.replace(/^-\s*["']?|["']?$/g, '').trim());
+    const { rules: compiled } = await compile(rules, llm);
+    writeFileSync(outputFile, JSON.stringify({ rules: compiled }, null, 2));
+    console.log(`Compiled ${compiled.length} rules to ${outputFile}`);
+}
+main().catch(console.error);

package/dist/compiler.d.ts

@@ -0,0 +1,5 @@
+import type { CompiledRule } from './types.js';
+import type { LLMAdapter } from './llm-adapter.js';
+export declare function compile(plainTextRules: string[], llm: LLMAdapter): Promise<{
+    rules: CompiledRule[];
+}>;

package/dist/compiler.js

@@ -0,0 +1,17 @@
+const COMPILER_PROMPT = `You are a rule extractor. Convert user rules into structured JSON.
+
+Rules:
+- "don't allow" / "never" / "block" → action: "block"
+- "ask me" / "prompt me" / "before X" → action: "require_approval" (NEVER "allow")
+- "allow" → action: "allow"
+
+Output ONLY valid JSON: { "rules": [ { "action": "...", "tool": "...", "reason": "..." } ] }
+Include tool names when inferable (e.g. gmail.delete, gmail.batchDelete for email delete).
+`;
+export async function compile(plainTextRules, llm) {
+    const prompt = `${COMPILER_PROMPT}\n\nUser rules:\n${plainTextRules.map((r) => `- ${r}`).join('\n')}`;
+    const raw = await llm.complete(prompt);
+    const stripped = raw.replace(/^```(?:json)?\s*\n?|\n?```\s*$/g, '').trim();
+    const parsed = JSON.parse(stripped);
+    return { rules: parsed.rules };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './matcher.js';
+export * from './compiler.js';
+export * from './middleware.js';
+export * from './llm-adapter.js';
+export * from './rules.js';
+export * from './path-protection.js';
+export { createOpenClawAdapter } from './adapters/openclaw-adapter.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './matcher.js';
+export * from './compiler.js';
+export * from './middleware.js';
+export * from './llm-adapter.js';
+export * from './rules.js';
+export * from './path-protection.js';
+export { createOpenClawAdapter } from './adapters/openclaw-adapter.js';

package/dist/llm-adapter.d.ts

@@ -0,0 +1,3 @@
+export interface LLMAdapter {
+    complete(prompt: string): Promise<string>;
+}

package/dist/llm-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/matcher.d.ts

@@ -0,0 +1,5 @@
+import type { ToolCall, Intent, CompiledRule, CheckResult, DefaultWhenNoMatch } from './types.js';
+export interface MatchOptions {
+    defaultWhenNoMatch?: DefaultWhenNoMatch;
+}
+export declare function match(toolCall: ToolCall, intent: Intent, rules: CompiledRule[], options?: MatchOptions): CheckResult;

package/dist/matcher.js

@@ -0,0 +1,49 @@
+const ACTION_TO_DECISION = {
+    block: 'BLOCK',
+    require_approval: 'REQUIRES_APPROVAL',
+    allow: 'ALLOW',
+};
+function matchArgs(rule, toolCall) {
+    if (!rule.argsPattern)
+        return true;
+    const argsStr = Object.values(toolCall.args)
+        .filter((v) => typeof v === 'string' || typeof v === 'number')
+        .join(' ');
+    return new RegExp(rule.argsPattern).test(argsStr);
+}
+export function match(toolCall, intent, rules, options = {}) {
+    const { defaultWhenNoMatch = 'require_approval' } = options;
+    let matched = null;
+    let matchedAction = null;
+    for (const rule of rules) {
+        const toolMatch = (rule.tool && rule.tool === toolCall.toolName) ||
+            (rule.toolPattern &&
+                new RegExp(rule.toolPattern).test(toolCall.toolName));
+        const argsMatch = matchArgs(rule, toolCall);
+        const intentMatch = !rule.intentPattern ||
+            new RegExp(rule.intentPattern, 'i').test(intent.text);
+        if (toolMatch && argsMatch && intentMatch) {
+            if (!matched || rule.action === 'block') {
+                matched = rule;
+                matchedAction = rule.action;
+                if (rule.action === 'block')
+                    break;
+            }
+        }
+    }
+    if (!matched) {
+        const decision = defaultWhenNoMatch === 'allow'
+            ? 'ALLOW'
+            : defaultWhenNoMatch === 'block'
+                ? 'BLOCK'
+                : 'REQUIRES_APPROVAL';
+        return {
+            decision,
+            reason: 'No matching rule',
+        };
+    }
+    return {
+        decision: ACTION_TO_DECISION[matchedAction],
+        reason: matched.reason,
+    };
+}

package/dist/middleware.d.ts

@@ -0,0 +1,13 @@
+import type { ToolCall, Intent, CompiledRule, DefaultWhenNoMatch, PathProtectionConfig } from './types.js';
+export type ToolExecutor = (toolCall: ToolCall) => Promise<unknown>;
+export interface MiddlewareResult {
+    decision: 'ALLOW' | 'BLOCK' | 'REQUIRES_APPROVAL';
+    reason?: string;
+    executed: boolean;
+    result?: unknown;
+}
+export interface MiddlewareOptions {
+    defaultWhenNoMatch?: DefaultWhenNoMatch;
+    pathProtection?: PathProtectionConfig | Record<string, never>;
+}
+export declare function createMiddleware(rules: CompiledRule[], executor: ToolExecutor, options?: MiddlewareOptions): (toolCall: ToolCall, intent: Intent) => Promise<MiddlewareResult>;

package/dist/middleware.js

@@ -0,0 +1,34 @@
+import { match } from './matcher.js';
+import { isProtectedPathViolation, DEFAULT_DANGEROUS_TOOLS, DEFAULT_PROTECTED_PATTERNS, } from './path-protection.js';
+function resolvePathProtection(pathProtection) {
+    if (!pathProtection)
+        return null;
+    if (Object.keys(pathProtection).length === 0) {
+        return {
+            dangerousTools: DEFAULT_DANGEROUS_TOOLS,
+            protectedPatterns: DEFAULT_PROTECTED_PATTERNS,
+        };
+    }
+    return pathProtection;
+}
+export function createMiddleware(rules, executor, options = {}) {
+    const { defaultWhenNoMatch = 'require_approval', pathProtection, } = options;
+    const pathConfig = resolvePathProtection(pathProtection);
+    return async (toolCall, intent) => {
+        if (pathConfig && isProtectedPathViolation(toolCall, pathConfig)) {
+            return {
+                decision: 'BLOCK',
+                reason: 'Protected path: rules cannot be modified by agent',
+                executed: false,
+            };
+        }
+        const { decision, reason } = match(toolCall, intent, rules, {
+            defaultWhenNoMatch,
+        });
+        if (decision === 'BLOCK' || decision === 'REQUIRES_APPROVAL') {
+            return { decision, reason, executed: false };
+        }
+        const result = await executor(toolCall);
+        return { decision: 'ALLOW', executed: true, result };
+    };
+}

package/dist/path-protection.d.ts

@@ -0,0 +1,6 @@
+import type { ToolCall, PathProtectionConfig } from './types.js';
+export declare const DEFAULT_DANGEROUS_TOOLS: string[];
+/** OpenClaw file tools (group:fs) that can write files */
+export declare const OPENCLAW_DANGEROUS_TOOLS: string[];
+export declare const DEFAULT_PROTECTED_PATTERNS: string[];
+export declare function isProtectedPathViolation(toolCall: ToolCall, config: PathProtectionConfig): boolean;

package/dist/path-protection.js

@@ -0,0 +1,34 @@
+import { minimatch } from 'minimatch';
+export const DEFAULT_DANGEROUS_TOOLS = [
+    'filesystem.write',
+    'filesystem.edit',
+    'write_file',
+    'edit_file',
+    'writeFile',
+    'fs.writeFile',
+];
+/** OpenClaw file tools (group:fs) that can write files */
+export const OPENCLAW_DANGEROUS_TOOLS = ['write', 'edit', 'apply_patch'];
+export const DEFAULT_PROTECTED_PATTERNS = [
+    '**/rules*.json',
+    '**/.config/ai-permissions-layer/**',
+];
+const PATH_KEYS = ['path', 'file_path', 'filePath', 'filename'];
+function extractPath(args) {
+    for (const key of PATH_KEYS) {
+        const val = args[key];
+        if (typeof val === 'string')
+            return val;
+    }
+    return null;
+}
+export function isProtectedPathViolation(toolCall, config) {
+    if (!config.dangerousTools.includes(toolCall.toolName)) {
+        return false;
+    }
+    const path = extractPath(toolCall.args);
+    if (!path)
+        return false;
+    const normalizedPath = path.replace(/\\/g, '/');
+    return config.protectedPatterns.some((pattern) => minimatch(normalizedPath, pattern));
+}

package/dist/rules.d.ts

@@ -0,0 +1,2 @@
+import type { ToolCall, Intent, CompiledRule } from './types.js';
+export declare function createAllowRule(toolCall: ToolCall, _intent: Intent): CompiledRule;

package/dist/rules.js

@@ -0,0 +1,8 @@
+export function createAllowRule(toolCall, _intent) {
+    const date = new Date().toISOString().slice(0, 10);
+    return {
+        action: 'allow',
+        tool: toolCall.toolName,
+        reason: `User approved forever on ${date}`,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+export type Decision = 'ALLOW' | 'BLOCK' | 'REQUIRES_APPROVAL';
+export interface ToolCall {
+    toolName: string;
+    args: Record<string, unknown>;
+}
+export interface Intent {
+    text: string;
+}
+export type RuleAction = 'block' | 'require_approval' | 'allow';
+export interface CompiledRule {
+    action: RuleAction;
+    tool?: string;
+    toolPattern?: string;
+    intentPattern?: string;
+    /** Regex to match against tool call arguments (joined as space-separated string) */
+    argsPattern?: string;
+    reason: string;
+}
+export interface CheckResult {
+    decision: Decision;
+    reason?: string;
+}
+/** When no rule matches: 'allow', 'require_approval', or 'block'. Default: 'require_approval'. */
+export type DefaultWhenNoMatch = 'allow' | 'require_approval' | 'block';
+export interface PathProtectionConfig {
+    /** Tool names that can write files (e.g. "filesystem.write", "edit_file") */
+    dangerousTools: string[];
+    /** Glob patterns for paths the agent must not write to */
+    protectedPatterns: string[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "daniel-ai-permissions-layer",
+  "version": "0.2.0",
+  "description": "Offline-first middleware for AI agent tool call permissions. Intercepts tool calls, applies rules, returns ALLOW | BLOCK | REQUIRES_APPROVAL.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ai-permissions-compile": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build:plugin": "npm run build && cd openclaw-plugin && npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wei292224644/my-ai-permissions-layer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wei292224644/my-ai-permissions-layer/issues"
+  },
+  "homepage": "https://github.com/wei292224644/my-ai-permissions-layer#readme",
+  "keywords": [
+    "ai",
+    "permissions",
+    "middleware",
+    "openclaw",
+    "tool-calls",
+    "agent",
+    "llm"
+  ],
+  "license": "GPL-3.0-or-later",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "minimatch": "^10.2.2"
+  }
+}