airlock-bot 0.0.1 → 0.2.1

package/dist/transport/sse-server.js.map

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

package/dist/transport/stdio-server.d.ts

@@ -0,0 +1,3 @@
+import type { AgentServerDeps } from './agent-server.js';
+export declare function runStdioServer(deps: AgentServerDeps): Promise<void>;
+//# sourceMappingURL=stdio-server.d.ts.map

package/dist/transport/stdio-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-server.d.ts","sourceRoot":"","sources":["../../src/transport/stdio-server.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKzD,wBAAsB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzE"}

package/dist/transport/stdio-server.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createAgentServer, connectAgentServer } from './agent-server.js';
+import { childLogger } from '../util/logger.js';
+const log = childLogger('stdio-server');
+export async function runStdioServer(deps) {
+    log.info({ agentId: deps.agentId }, 'Starting stdio server');
+    const transport = new StdioServerTransport();
+    const server = createAgentServer(deps);
+    await connectAgentServer(server, transport);
+    log.info({ agentId: deps.agentId }, 'Stdio server connected');
+}
+//# sourceMappingURL=stdio-server.js.map

package/dist/transport/stdio-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-server.js","sourceRoot":"","sources":["../../src/transport/stdio-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE1E,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,GAAG,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;AAExC,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAqB;IACxD,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,uBAAuB,CAAC,CAAC;IAC7D,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,kBAAkB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC5C,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,wBAAwB,CAAC,CAAC;AAChE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+export interface ToolCall {
+    tool: string;
+    args: Record<string, unknown>;
+    agentId: string;
+}
+export interface ToolResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    metadata?: {
+        duration_ms?: number;
+        truncated?: boolean;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1D"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/util/id.d.ts

@@ -0,0 +1,5 @@
+/** Generate an 8-char uppercase alphanumeric HITL approval code (no modular bias) */
+export declare function generateApprovalCode(): string;
+/** Generate a unique request ID (UUID-like) */
+export declare function generateId(): string;
+//# sourceMappingURL=id.d.ts.map

package/dist/util/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/util/id.ts"],"names":[],"mappings":"AAKA,qFAAqF;AACrF,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,IAAI,MAAM,CAEnC"}

package/dist/util/id.js

@@ -0,0 +1,16 @@
+import { randomBytes, randomInt } from 'crypto';
+const APPROVAL_CODE_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+const APPROVAL_CODE_LENGTH = 8; // 36^8 ≈ 2.8 trillion
+/** Generate an 8-char uppercase alphanumeric HITL approval code (no modular bias) */
+export function generateApprovalCode() {
+    let code = '';
+    for (let i = 0; i < APPROVAL_CODE_LENGTH; i++) {
+        code += APPROVAL_CODE_CHARS[randomInt(APPROVAL_CODE_CHARS.length)];
+    }
+    return code;
+}
+/** Generate a unique request ID (UUID-like) */
+export function generateId() {
+    return randomBytes(16).toString('hex');
+}
+//# sourceMappingURL=id.js.map

package/dist/util/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/util/id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEhD,MAAM,mBAAmB,GAAG,sCAAsC,CAAC;AACnE,MAAM,oBAAoB,GAAG,CAAC,CAAC,CAAC,sBAAsB;AAEtD,qFAAqF;AACrF,MAAM,UAAU,oBAAoB;IAClC,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,oBAAoB,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,IAAI,IAAI,mBAAmB,CAAC,SAAS,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,UAAU;IACxB,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC"}

package/dist/util/logger.d.ts

@@ -0,0 +1,4 @@
+import pino from 'pino';
+export declare const logger: pino.Logger<never, boolean>;
+export declare function childLogger(component: string): pino.Logger<never, boolean>;
+//# sourceMappingURL=logger.d.ts.map

package/dist/util/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/util/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAkBxB,eAAO,MAAM,MAAM,6BAEuE,CAAC;AAE3F,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,+BAE5C"}

package/dist/util/logger.js

@@ -0,0 +1,24 @@
+import pino from 'pino';
+function createTransport() {
+    if (process.env.NODE_ENV === 'production')
+        return undefined;
+    try {
+        // pino-pretty is optional — only used in development
+        require.resolve('pino-pretty');
+        return { target: 'pino-pretty', options: { colorize: true, destination: 2 } };
+    }
+    catch {
+        return undefined;
+    }
+}
+const transport = createTransport();
+// Always log to stderr (fd 2) so stdout stays clean for MCP stdio transport.
+// When using pino-pretty, destination is set in the transport options.
+// When not using a transport, we pass pino.destination(2) as the stream.
+export const logger = transport
+    ? pino({ name: 'airlock', level: process.env.LOG_LEVEL ?? 'info', transport })
+    : pino({ name: 'airlock', level: process.env.LOG_LEVEL ?? 'info' }, pino.destination(2));
+export function childLogger(component) {
+    return logger.child({ component });
+}
+//# sourceMappingURL=logger.js.map

package/dist/util/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/util/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,SAAS,eAAe;IACtB,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,CAAC;QACH,qDAAqD;QACrD,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC/B,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,SAAS,GAAG,eAAe,EAAE,CAAC;AAEpC,6EAA6E;AAC7E,uEAAuE;AACvE,yEAAyE;AACzE,MAAM,CAAC,MAAM,MAAM,GAAG,SAAS;IAC7B,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM,EAAE,SAAS,EAAE,CAAC;IAC9E,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AAE3F,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;AACrC,CAAC"}

package/examples/claude-code-setup.md

@@ -0,0 +1,77 @@
+# Claude Code Setup (stdio mode)
+
+Airlock can act as an MCP server for Claude Code using stdio transport.
+
+## Add to Claude Code MCP config
+
+In `~/.claude/mcp.json` (or `.claude/mcp.json` in your project):
+
+```json
+{
+  "mcpServers": {
+    "airlock": {
+      "command": "airlock",
+      "args": ["--agent", "claude-code", "--config", "/etc/airlock/gateway.yaml"]
+    }
+  }
+}
+```
+
+Or using `npx` if not globally installed:
+
+```json
+{
+  "mcpServers": {
+    "airlock": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "airlock-bot",
+        "--agent",
+        "claude-code",
+        "--config",
+        "/etc/airlock/gateway.yaml"
+      ]
+    }
+  }
+}
+```
+
+## What This Does
+
+- Claude Code connects to Airlock over stdio
+- Airlock presents only the tools allowed for the `claude-code` agent
+- All tool calls are logged to the audit database
+- Tools requiring HITL will block until approved (or timeout)
+
+## Example Agent Config
+
+```yaml
+agents:
+  claude-code:
+    allow:
+      - 'filesystem/*'
+      - 'github/list*'
+      - 'github/get*'
+      - 'http/get'
+    exec:
+      allow:
+        - 'git status'
+        - 'git diff*'
+        - 'npm test'
+      deny:
+        - '*'
+```
+
+## Testing
+
+```sh
+# Verify the agent works
+airlock --agent claude-code --config examples/gateway.yaml
+```
+
+Then use MCP Inspector or connect from Claude Code to verify:
+
+- `list_tools` returns only allowed tools
+- Denied tools are absent from the manifest
+- Audit log is populated after calls

package/examples/gateway.yaml

@@ -0,0 +1,118 @@
+# yaml-language-server: $schema=../schema.json
+# Airlock Gateway Configuration
+# Environment variables are substituted using ${VAR_NAME} syntax.
+
+server:
+  port: 4111
+  host: 127.0.0.1
+  # api_secret: ${AIRLOCK_API_SECRET}
+
+# Tool providers — MCP servers and builtins
+providers:
+  filesystem:
+    type: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-filesystem', '/home/user/projects']
+
+  github:
+    type: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-github']
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}
+
+  # Example SSE-based MCP
+  # myserver:
+  #   type: sse
+  #   url: http://localhost:8000/sse
+  #   headers:
+  #     Authorization: Bearer ${MY_SERVER_TOKEN}
+
+  exec: builtin
+  http: builtin
+
+# Agents
+agents:
+  # Helena: full-access developer agent with approval on destructive ops
+  helena:
+    allow:
+      - 'filesystem/*'
+      - 'github/*'
+      - 'http/*'
+      - 'exec/run'
+    ask:
+      - 'github/create_pr'
+      - 'github/merge_pull_request'
+      - 'github/delete_branch'
+    exec:
+      allow:
+        - 'git status'
+        - 'git diff*'
+        - 'git log*'
+        - 'npm test*'
+        - 'npm run*'
+      ask:
+        - 'git push*'
+        - 'git merge*'
+      deny:
+        - 'sudo*'
+        - 'rm -rf*'
+    http:
+      domain_allowlist:
+        - 'api.github.com'
+        - '*.sentry.io'
+
+  # Claude Code: read-only, no approval needed
+  claude-code:
+    allow:
+      - 'filesystem/*'
+      - 'github/list*'
+      - 'github/get*'
+      - 'http/get'
+    exec:
+      allow:
+        - 'git status'
+        - 'git diff*'
+        - 'npm test'
+      deny:
+        - '*' # deny everything not explicitly allowed
+
+# Approval configuration
+approvals:
+  # provider:
+  #   type: telegram
+  #   bot_token: ${TELEGRAM_BOT_TOKEN}
+  #   chat_id: ${TELEGRAM_CHAT_ID}
+  #
+  # provider:
+  #   type: openclaw
+  #   gateway_url: ws://localhost:18789
+  #   token: ${OPENCLAW_TOKEN}
+  #   session_key: "agent:main:telegram:channel:123456789"
+  provider:
+    type: stdio # prints to stderr for dev/testing
+  timeout_ms: 300000 # 5 minutes
+  batch_window_ms: 10000 # collect requests for 10s before notifying
+
+# Security defaults
+security:
+  blocked_hosts:
+    - localhost
+    - 127.0.0.1
+    - '::1'
+    - '*.local'
+    - '10.*'
+    - '192.168.*'
+    - '172.16.*'
+  allowed_local: [] # override to allow specific local hosts
+
+# Audit logging
+audit:
+  db_path: ./airlock-audit.db
+  retention_days: 90
+  redact_fields:
+    - password
+    - token
+    - secret
+    - key
+    - authorization

package/examples/local-dev.yaml

@@ -0,0 +1,41 @@
+# yaml-language-server: $schema=../schema.json
+# Local development config with dashboard approval.
+# Uses the echo MCP server — no tokens or external services needed.
+#
+# Run:  npx tsx src/index.ts --agent dev --config examples/local-dev.yaml
+# Then open http://localhost:4112 to see the approval dashboard.
+#
+# Tools "echo/echo" and "echo/add" are available.
+# "echo/add" requires approval — call it to see the dashboard in action.
+
+providers:
+  echo:
+    type: stdio
+    command: npx
+    args: ['tsx', 'test/echo-server.ts']
+
+agents:
+  dev:
+    allow:
+      - 'echo/*'
+    ask:
+      - 'echo/add'
+
+approvals:
+  provider:
+    type: dashboard
+    port: 4112
+  timeout_ms: 300000
+  batch_window_ms: 2000
+
+security:
+  blocked_hosts:
+    - localhost
+    - 127.0.0.1
+    - '::1'
+  allowed_local: []
+
+audit:
+  db_path: ':memory:'
+  retention_days: 1
+  redact_fields: []

package/examples/openclaw-setup.md

@@ -0,0 +1,51 @@
+# OpenClaw Provider Setup
+
+The `openclaw` HITL provider delivers approval requests to your OpenClaw session
+(Telegram, Discord, etc.) and listens for replies.
+
+## Configuration
+
+```yaml
+hitl:
+  provider:
+    type: openclaw
+    gateway_url: ws://localhost:18789
+    token: ${OPENCLAW_TOKEN}
+    session_key: "agent:main:telegram:channel:YOUR_CHAT_ID"
+    # or just "main" for the default session
+```
+
+Set `OPENCLAW_TOKEN` in your environment:
+```sh
+export OPENCLAW_TOKEN=your-openclaw-bearer-token
+```
+
+## How It Works
+
+1. When Airlock needs approval, it sends a `chat.send` RPC over WebSocket to OpenClaw.
+2. OpenClaw delivers the message to your configured channel (Telegram, Discord, etc.).
+3. You reply with: `hitl approve A1B2C3` or `hitl deny A1B2C3`
+4. Airlock's WebSocket listener picks up the reply and resolves the pending request.
+
+## Session Key Format
+
+- Default session: `"main"`
+- Telegram channel: `"agent:main:telegram:channel:<chat_id>"`
+- Discord channel: `"agent:main:discord:channel:<channel_id>"`
+
+## Wire OpenClaw in `openclaw.json`
+
+Ensure the agent that will receive HITL messages has access to the session.
+In your openclaw config, the relevant agent should have the session key configured.
+
+## Systemd Integration
+
+If running both services on the same host, configure Airlock to start after OpenClaw:
+
+```ini
+# airlock.service
+[Unit]
+After=openclaw-gateway.service
+```
+
+See `../airlock.service` for the full unit file.

package/examples/profiles.yaml

@@ -0,0 +1,103 @@
+# yaml-language-server: $schema=../schema.json
+# Composable profiles — define reusable permission sets, then mix them into agents.
+#
+# Profiles are union-merged: an agent that extends [readonly, github-write]
+# gets all allow/ask patterns from both profiles, plus its own.
+# Precedence still applies: deny > ask > allow > default-deny.
+#
+# Run:  npx tsx src/index.ts --agent helena --config examples/profiles.yaml
+
+providers:
+  filesystem:
+    type: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-filesystem', '/home/user/projects']
+
+  github:
+    type: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-github']
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}
+
+  exec: builtin
+  http: builtin
+
+# Reusable permission sets
+profiles:
+  readonly:
+    allow:
+      - 'filesystem/read*'
+      - 'filesystem/list*'
+      - 'github/list*'
+      - 'github/get*'
+      - 'http/get'
+    ask: []
+
+  github-write:
+    allow:
+      - 'github/create_issue'
+      - 'github/create_pr'
+    ask:
+      - 'github/delete_branch'
+      - 'github/merge_pull_request'
+
+  full-fs:
+    allow:
+      - 'filesystem/*'
+    ask: []
+
+# Agents compose profiles with their own overrides
+agents:
+  # Read-only reviewer — gets readonly profile, nothing else
+  reviewer:
+    extends: [readonly]
+
+  # Developer — reads everything, writes to GitHub with approval on destructive ops
+  helena:
+    extends: [readonly, github-write, full-fs]
+    allow:
+      - 'exec/run'
+    exec:
+      allow:
+        - 'git status'
+        - 'git diff*'
+        - 'git log*'
+        - 'npm test*'
+      ask:
+        - 'git push*'
+      deny:
+        - 'sudo*'
+        - 'rm -rf*'
+    http:
+      domain_allowlist:
+        - 'api.github.com'
+
+  # Claude Code — readonly plus filesystem, no approval needed
+  claude-code:
+    extends: [readonly, full-fs]
+    exec:
+      allow:
+        - 'git status'
+        - 'git diff*'
+        - 'npm test'
+      deny:
+        - '*'
+
+approvals:
+  provider:
+    type: stdio
+  timeout_ms: 300000
+  batch_window_ms: 10000
+
+security:
+  blocked_hosts:
+    - localhost
+    - 127.0.0.1
+    - '::1'
+  allowed_local: []
+
+audit:
+  db_path: ':memory:'
+  retention_days: 1
+  redact_fields: []

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "airlock-bot",
-  "version": "0.0.1",
-  "description": "Permissions-aware MCP gateway with human-in-the-loop approval for AI agents.",
-  "license": "MIT"
+  "version": "0.2.1",
+  "description": "Permissions-aware MCP gateway with human-in-the-loop approval for AI agents",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "airlock": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "examples",
+    "schema.json",
+    "airlock.service"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/airlock-dev/airlock.git"
+  },
+  "bugs": {
+    "url": "https://github.com/airlock-dev/airlock/issues"
+  },
+  "homepage": "https://airlock.bot",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "gateway",
+    "ai-agent",
+    "human-in-the-loop",
+    "security",
+    "prompt-injection",
+    "allowlist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "configure-agent": "tsx scripts/configure-agent.ts",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "schema": "tsx scripts/generate-schema.ts",
+    "prepublishOnly": "npm run schema && npm run build"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "ai": "^6.0.116",
+    "ajv": "^8.18.0",
+    "better-sqlite3": "^11.0.0",
+    "chokidar": "^3.6.0",
+    "fastify": "^5.0.0",
+    "pino": "^9.0.0",
+    "ws": "^8.19.0",
+    "yaml": "^2.4.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.1.8",
+    "lefthook": "^2.1.4",
+    "openapi-types": "^12.1.3",
+    "pino-pretty": "^13.0.0",
+    "prettier": "^3.8.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "typescript-eslint": "^8.57.0",
+    "vitest": "^3.0.0",
+    "zod-to-json-schema": "^3.25.1"
+  }
 }