@llnvd/openclaw-url-guard 0.0.1

package/.forgejo/workflows/ci.yaml

@@ -0,0 +1,117 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: codeberg-tiny
+    steps:
+      - name: Checkout
+        uses: https://code.forgejo.org/actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: https://code.forgejo.org/actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Format check
+        run: npm run format:check
+
+  build:
+    name: Build
+    runs-on: codeberg-tiny
+    steps:
+      - name: Checkout
+        uses: https://code.forgejo.org/actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: https://code.forgejo.org/actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+  test-unit:
+    name: Unit Tests
+    runs-on: codeberg-small
+    needs: [lint, build]
+    steps:
+      - name: Checkout
+        uses: https://code.forgejo.org/actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: https://code.forgejo.org/actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run unit tests
+        run: npm test -- --exclude 'tests/e2e/**'
+
+  test-e2e:
+    name: E2E Tests
+    runs-on: codeberg-small
+    needs: [lint, build]
+    steps:
+      - name: Checkout
+        uses: https://code.forgejo.org/actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: https://code.forgejo.org/actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run E2E tests
+        run: npm run test:e2e
+
+  test-integration-real:
+    name: Integration Tests (Real Gateway)
+    runs-on: codeberg-small
+    needs: [test-unit, test-e2e]
+    timeout-minutes: 5
+    # Only run on main branch pushes (not PRs)
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - name: Checkout
+        uses: https://code.forgejo.org/actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: https://code.forgejo.org/actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run integration tests with real gateway
+        run: npm run test:integration
+        env:
+          INTEGRATION_TESTS: "true"

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.oxlintrc.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/crates/oxc_linter/schemas/config.schema.json",
+  "plugins": ["typescript"],
+  "rules": {
+    "no-unused-vars": "warn",
+    "no-console": "off",
+    "eqeqeq": "error",
+    "no-var": "error",
+    "prefer-const": "warn",
+    "typescript/no-explicit-any": "warn",
+    "typescript/no-unused-vars": "warn"
+  },
+  "ignorePatterns": ["dist/", "node_modules/", "*.js"]
+}

package/.prettierignore

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+*.md

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}

package/CONTRIBUTING.md

@@ -0,0 +1,173 @@
+# Contributing to openclaw-url-guard
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://codeberg.org/llnvd/openclaw-url-guard.git
+cd openclaw-url-guard
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+## Code Quality
+
+This project uses strict linting enforced by pre-commit hooks.
+
+### Tools
+
+- **oxlint** — Fast Rust-based linter (71 rules)
+- **prettier** — Code formatting
+- **husky + lint-staged** — Pre-commit enforcement
+
+### Commands
+
+```bash
+# Run linter
+npm run lint
+
+# Fix auto-fixable issues
+npm run lint:fix
+
+# Format code
+npm run format
+
+# Check formatting
+npm run format:check
+
+# Run all checks (lint + format + test)
+npm run check
+```
+
+### Pre-commit Hook
+
+Every commit automatically runs:
+1. `oxlint --fix` on staged `.ts` files
+2. `prettier --write` on staged `.ts` files
+
+If linting fails, the commit is rejected. Fix the issues and try again.
+
+## Project Structure
+
+```
+src/
+├── index.ts           # Plugin entry point
+├── config.ts          # Configuration types and defaults
+├── types.ts           # TypeScript interfaces
+├── tools/
+│   ├── safeFetch.ts   # safe_web_fetch implementation
+│   └── safeSearch.ts  # safe_web_search implementation
+└── filters/
+    ├── matcher.ts     # URL/hostname matching logic
+    └── urlhaus.ts     # URLhaus threat feed integration
+
+tests/
+└── matcher.test.ts    # Unit tests for matching logic
+```
+
+## Adding New Threat Feeds
+
+Threat feeds live in `src/filters/`. To add a new feed:
+
+1. Create a new file (e.g., `src/filters/phishtank.ts`)
+2. Implement the `ThreatFeed` interface:
+
+```typescript
+export interface ThreatFeed {
+  name: string;
+  update(): Promise<void>;
+  isBlocked(url: string): boolean;
+  getLastUpdate(): Date | null;
+}
+```
+
+3. Register it in `src/filters/index.ts`
+4. Add configuration options to `src/config.ts`
+5. Add tests in `tests/`
+
+### Feed Implementation Example
+
+```typescript
+import { ThreatFeed } from '../types';
+
+export class PhishTankFeed implements ThreatFeed {
+  name = 'phishtank';
+  private blockedUrls = new Set<string>();
+  private lastUpdate: Date | null = null;
+
+  async update(): Promise<void> {
+    // Fetch feed from https://phishtank.org/
+    // Parse and populate this.blockedUrls
+    this.lastUpdate = new Date();
+  }
+
+  isBlocked(url: string): boolean {
+    return this.blockedUrls.has(url);
+  }
+
+  getLastUpdate(): Date | null {
+    return this.lastUpdate;
+  }
+}
+```
+
+## Testing
+
+We use [Vitest](https://vitest.dev/) for testing.
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run specific test file
+npx vitest run tests/matcher.test.ts
+```
+
+### Writing Tests
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { matchHostname } from '../src/filters/matcher';
+
+describe('matchHostname', () => {
+  it('matches exact domains', () => {
+    expect(matchHostname('example.com', 'example.com')).toBe(true);
+    expect(matchHostname('example.com', 'other.com')).toBe(false);
+  });
+});
+```
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Make your changes
+4. Ensure tests pass (`npm run check`)
+5. Commit with conventional commit messages
+6. Push and open a PR
+
+### Commit Message Format
+
+```
+type: description
+
+feat: add PhishTank threat feed support
+fix: handle URLs with ports correctly
+docs: update configuration examples
+chore: update dependencies
+test: add edge case tests for wildcards
+```
+
+## Questions?
+
+Open an issue on [Codeberg](https://codeberg.org/llnvd/openclaw-url-guard/issues).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llnvd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# openclaw-url-guard
+
+OpenClaw plugin that guards web tool access with hostname allowlist/blocklist policy.
+
+> ⚠️ **Disclaimer:** This project is a proof of concept (PoC). It is provided "as is" without
+> warranty of any kind. We make no guarantees about its security, reliability, or fitness for
+> any particular purpose. Use at your own risk.
+
+## Install
+
+### From Git (recommended for now)
+
+The npm package is not yet published. Install directly from Codeberg:
+
+```bash
+# Clone and build
+git clone https://codeberg.org/llnvd/openclaw-url-guard.git
+cd openclaw-url-guard
+npm install
+npm run build
+
+# Install as OpenClaw plugin (from the repo directory)
+openclaw plugins install .
+```
+
+Or install directly via npm/git URL:
+
+```bash
+npm install git+https://codeberg.org/llnvd/openclaw-url-guard.git
+```
+
+### From npm (once published)
+
+```bash
+npm install @llnvd/openclaw-url-guard
+```
+
+## Quick Start (Secure Installation)
+
+This plugin provides guarded alternatives to the native `web_fetch` and `web_search` tools.
+**For full protection, you must disable the native tools** — otherwise the LLM can bypass
+the guard by calling the unprotected tools directly.
+
+Add to OpenClaw config (`~/.openclaw/openclaw.json`):
+
+```json5
+{
+  // Disable native web tools (required for security)
+  "tools": {
+    "deny": ["web_fetch", "web_search"]
+  },
+
+  // Enable the url-guard plugin
+  "plugins": {
+    "entries": {
+      "@llnvd/openclaw-url-guard": {
+        "enabled": true,
+        "config": {
+          "mode": "allowlist",
+          "allowlist": [
+            "docs.python.org",
+            "developer.mozilla.org",
+            "en.wikipedia.org",
+            "github.com",
+            "stackoverflow.com"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+This configuration:
+1. **Denies** the native `web_fetch` and `web_search` tools (they won't be sent to the LLM)
+2. **Enables** the plugin's `safe_web_fetch` and `safe_web_search` as the only web access tools
+
+The guarded tools:
+- `safe_web_fetch` — fetches URLs through the policy filter
+- `safe_web_search` — searches the web and filters results by policy
+
+> **⚠️ Security Note:** Without `tools.deny`, the native tools remain available and a
+> prompt injection attack could instruct the LLM to use `web_fetch` instead of
+> `safe_web_fetch`, completely bypassing the guard.
+
+Optional threat intel feed settings:
+
+```yaml
+plugins:
+  - name: "@llnvd/openclaw-url-guard"
+    config:
+      mode: allowlist
+      allowlist:
+        - docs.python.org
+      threatFeeds:
+        urlhaus: true
+        mode: fail-open # default: fail-open, alternative: fail-closed
+```
+
+URLhaus behavior:
+
+- applies to `safe_web_fetch` only
+- runs after local allowlist/blocklist checks pass
+- blocks when URLhaus lists the URL
+- on URLhaus API/network failure:
+  - `fail-open`: allow request
+  - `fail-closed`: block request
+
+## Security Defaults
+
+- only `http://` and `https://` URLs are accepted
+- private/internal IP targets are blocked by default (`blockPrivateIps: true`)
+- URLhaus lookups time out after 5 seconds to avoid hanging requests
+- blocked tool responses are minimal by default; set `logging.verboseErrors: true` for detailed reasons and score metadata
+
+## Trust Scoring (Issue #3)
+
+Optional trust scoring replaces binary allow/block with a score range from `+10` to `-10`.
+
+- `+10` to `+7`: Trusted (always allow, skips threat feed checks)
+- `+6` to `+3`: Preferred (allow, still check threat feeds)
+- `+2` to `-2`: Neutral
+- `-3` to `-6`: Suspicious (allow with warning when logging is enabled)
+- `-7` to `-9`: Risky (blocked by default)
+- `-10`: Forbidden (always blocked)
+
+Scoring is disabled by default for backward compatibility. Enable it with:
+
+```yaml
+plugins:
+  - name: "@llnvd/openclaw-url-guard"
+    config:
+      mode: allowlist
+      scoring:
+        enabled: true
+        defaultScore: 0
+        minScore: -6
+        rules:
+          - domain: github.com
+            score: 8
+            reason: trusted source
+```
+
+## Documentation
+
+- [Documentation Index](./docs/README.md)
+- [OpenClaw Integration](./docs/openclaw-integration.md) — **start here**
+- [Agent Installation Guide](./docs/AGENT-INSTALL.md) — for AI agents installing this plugin
+- [API Reference](./docs/api-reference.md)
+- [Configuration](./docs/configuration.md)
+- [Trust Scoring](./docs/scoring.md)
+- [Testing](./docs/testing.md)
+- [Usage Modes](./docs/usage-modes.md)
+
+## Development
+
+```bash
+npm test
+```
+
+Run E2E tests only:
+
+```bash
+npm run test:e2e
+```
+
+Enable live URLhaus network E2E test:
+
+```bash
+E2E_NETWORK_TESTS=true npm run test:e2e
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for contributor workflow.
+
+## CI Pipeline
+
+This project uses Codeberg Actions (Forgejo Actions) for continuous integration.
+
+| Job | Runner | Trigger | Description |
+|-----|--------|---------|-------------|
+| Lint & Format | `codeberg-tiny` | push, PR | oxlint + prettier |
+| Build | `codeberg-tiny` | push, PR | TypeScript compilation |
+| Unit Tests | `codeberg-small` | push, PR | Core functionality tests |
+| E2E Tests | `codeberg-small` | push, PR | Integration test harness |
+| Live Feed Tests | `codeberg-small` | main push only | URLhaus network tests |
+
+Workflow: [`.forgejo/workflows/ci.yaml`](./.forgejo/workflows/ci.yaml)
+
+## License
+
+MIT

package/TASK.md

@@ -0,0 +1,39 @@
+# Task: Improve Documentation for openclaw-url-guard Plugin
+
+## Objective
+Enhance the documentation for the openclaw-url-guard plugin to improve clarity, usability, and completeness.
+
+## Scope
+- Improve README.md with comprehensive documentation
+- Add detailed configuration explanations
+- Include practical usage examples
+- Document security considerations
+- Add development and contribution guidelines
+
+## Current Issues
+The existing documentation was basic and lacked:
+- Detailed configuration explanations
+- Practical usage examples for different modes
+- Security considerations
+- Clear organization and structure
+- Usage of wildcards and threat feeds
+
+## Improvements Made
+1. Enhanced README.md with:
+   - Better organization and structure
+   - Detailed configuration explanations with all options documented
+   - Usage examples for different modes (allowlist, blocklist, hybrid)
+   - Security considerations
+   - Development and contribution guidelines
+   - Clear examples with wildcards and threat feeds
+
+2. Maintained existing functionality while improving clarity
+
+## Documentation Structure
+The improved documentation now includes:
+- Plugin overview and features
+- Clear installation instructions
+- Comprehensive configuration schema documentation
+- Practical usage examples with different modes
+- Security considerations
+- Development and contribution guidelines

package/dist/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@llnvd/openclaw-url-guard",
+    "version": "0.0.1",
+    "description": "OpenClaw plugin for URL allowlisting/blocklisting in web_fetch and web_search tools",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "test": "vitest run",
+        "test:e2e": "vitest run tests/e2e/",
+        "test:integration": "INTEGRATION_TESTS=true vitest run tests/integration/",
+        "lint": "oxlint src/ tests/",
+        "lint:fix": "oxlint --fix src/ tests/",
+        "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts'",
+        "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.ts'",
+        "check": "npm run lint && npm run format:check && npm run test",
+        "prepare": "husky"
+    },
+    "lint-staged": {
+        "*.ts": [
+            "oxlint --fix",
+            "prettier --write"
+        ]
+    },
+    "devDependencies": {
+        "@types/node": "^25.3.5",
+        "husky": "^9.1.7",
+        "lint-staged": "^15.4.3",
+        "oxlint": "^1.51.0",
+        "prettier": "^3.5.3",
+        "typescript": "^5.6.3",
+        "vitest": "^2.1.8"
+    },
+    "openclaw": {
+        "extensions": [
+            "./dist/src/index.js"
+        ]
+    }
+}