@coffeexdev/openclaw-sentinel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 coffeebot-agent
+
+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,173 @@
+# @coffeexdev/openclaw-sentinel
+
+Secure, declarative, gateway-native background watcher plugin for OpenClaw.
+
+## Why Sentinel
+
+OpenClaw Sentinel runs watcher lifecycles inside the gateway using fixed strategies and declarative conditions.
+It **does not** execute user-authored code from watcher definitions.
+
+## Features
+
+- Tool registration: `sentinel_control`
+  - actions: `create`, `enable`, `disable`, `remove`, `status`, `list`
+- Strict schema validation (`zod.strict`) + code-like field/value rejection
+- Strategies:
+  - `http-poll`
+  - `websocket`
+  - `sse`
+  - `http-long-poll`
+- Condition operators:
+  - `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `exists`, `absent`, `contains`, `matches`, `changed`
+- Match mode: `all` / `any`
+- Fire templating: substitution-only placeholders, non-Turing-complete
+- Fire route: local internal webhook dispatch path (no outbound fire URL)
+- Persistence: `~/.openclaw/sentinel-state.json`
+- Resource limits and per-skill limits
+- `allowedHosts` endpoint enforcement
+- CLI surface: `list`, `status`, `enable`, `disable`, `audit`
+
+## JSON Schema
+
+Formal JSON Schema for sentinel config/watchers is available at:
+
+- `schema/sentinel.schema.json`
+
+You can validate a watcher config document (for example `.sentinel.json`) against this schema in CI or local tooling.
+
+## Install
+
+```bash
+npm i @coffeexdev/openclaw-sentinel
+```
+
+## Quick usage
+
+```ts
+import { createSentinelPlugin } from "@coffeexdev/openclaw-sentinel";
+
+const sentinel = createSentinelPlugin({
+  allowedHosts: ["api.github.com", "api.coingecko.com"],
+  localDispatchBase: "http://127.0.0.1:4389",
+});
+
+await sentinel.init();
+sentinel.register({
+  registerTool(name, handler) {
+    // gateway tool registry hook
+  },
+});
+```
+
+## Tool input example (`sentinel_control:create`)
+
+```json
+{
+  "action": "create",
+  "watcher": {
+    "id": "sentinel-poker-alert",
+    "skillId": "skills.sentinel-poker",
+    "enabled": true,
+    "strategy": "http-poll",
+    "endpoint": "https://api.github.com/events",
+    "intervalMs": 15000,
+    "match": "any",
+    "conditions": [{ "path": "type", "op": "eq", "value": "PushEvent" }],
+    "fire": {
+      "webhookPath": "/internal/sentinel/fire",
+      "eventName": "sentinel-poker_push",
+      "payloadTemplate": {
+        "watcher": "${watcher.id}",
+        "event": "${event.name}",
+        "type": "${payload.type}",
+        "ts": "${timestamp}"
+      }
+    },
+    "retry": { "maxRetries": 5, "baseMs": 250, "maxMs": 5000 }
+  }
+}
+```
+
+## CLI
+
+```bash
+openclaw-sentinel list
+openclaw-sentinel status <watcher-id>
+openclaw-sentinel enable <watcher-id>
+openclaw-sentinel disable <watcher-id>
+openclaw-sentinel audit
+```
+
+### One-shot watchers
+
+Set `"fireOnce": true` to automatically disable a watcher after its first matched event.
+
+## Example scenarios
+
+### Sentinel Poker feed monitoring
+
+Watch API changes and fire internal webhook events for orchestration.
+
+### Blockchain price watch
+
+`http-poll` against `api.coingecko.com`, `gt/lte/changed` conditions, routed to local webhook.
+
+### CI monitoring
+
+`sse` or `http-long-poll` against approved CI host endpoint; fire standardized internal events.
+
+## Security model
+
+- No dynamic code execution from watcher definitions
+- No dynamic imports/requires from definitions
+- Strict input schema, unknown field rejection
+- Code-like fields/values rejected
+- Allowed-host enforcement on endpoints
+- Local-only fire routing through `localDispatchBase + webhookPath`
+- Bounded retries with backoff
+- Global/per-skill/condition limits
+
+## Future Improvements
+
+1. **WebSocket/SSE resilience tuning**
+   - Improve reconnect behavior and dedupe close+error failure handling.
+   - Add stronger circuit-breaker/backoff controls under bursty failures.
+
+2. **State persistence hardening**
+   - Add optional payload redaction or `do-not-persist-payload` mode so `lastPayload` does not store sensitive data on disk.
+   - Keep `changed` semantics while minimizing persisted sensitive fields.
+
+3. **Dispatch integrity hardening**
+   - Add optional HMAC signing for internal webhook dispatch payloads in addition to bearer auth token support.
+   - Validate signature at receiver to prevent tampering in misconfigured local planes.
+
+4. **Regex safety simplification and compatibility policy**
+   - Continue standardizing on `re2` with `re2-wasm` fallback.
+   - Document/centralize behavior for unsupported regex features (e.g., lookahead/backrefs).
+
+5. **Lifecycle completeness**
+   - Add explicit `stopAll()` shutdown path in plugin lifecycle hooks for deterministic cleanup.
+   - Expand startup/reload behavior tests to ensure no orphaned watchers/timers.
+
+6. **Test coverage expansion (priority)**
+   - Add websocket reconnection/error-dedupe tests.
+   - Add retry/backoff timing behavior tests.
+   - Add state file permission assertions and payload persistence tests.
+   - Add dispatch auth matrix tests (token on/off).
+
+## Development
+
+```bash
+npm i
+npm run lint
+npm run test
+npm run build
+```
+
+## License
+
+MIT
+
+CI trigger probe: 2026-03-03T22:51:37Z
+
+Push trigger probe 2026-03-03T22:56:44Z

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@coffeexdev/openclaw-sentinel",
+  "version": "0.1.0",
+  "description": "Secure declarative gateway-native watcher plugin for OpenClaw",
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "security",
+    "sentinel",
+    "watcher"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coffeexcoin/openclaw-sentinel.git"
+  },
+  "bin": {
+    "openclaw-sentinel": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "re2-wasm": "^1.0.2",
+    "ws": "^8.18.3",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.7",
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.5.13",
+    "oxfmt": "^0.36.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
+  },
+  "optionalDependencies": {
+    "re2": "^1.23.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}