arena-bridge 0.0.0-stage → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## 0.5.1
+
+### Fixed
+- `setup` and `tunnel` now say how to install `cloudflared` when the binary is missing.
+
+## 0.5.0
+
+### Added
+- macOS desktop control: 13 `mac_*` tools (screen capture with element ids, mouse, keyboard,
+  scrolling, drag, applications, windows) on top of the Peekaboo CLI.
+- `arena-bridge setup` — one command from zero to a working bridge: config, machine check,
+  API, tunnel and the ready-to-paste prompt.
+- `arena-bridge update` — self-update from the npm registry (`--check` only reports).
+- `arena-bridge service` — run the bridge as a macOS launchd service (`install`/`uninstall`/`status`).
+- `arena-bridge url` and `arena-bridge version` commands.
+- `doctor` now checks Peekaboo, Chrome and the service.
+
+### Fixed
+- `list_dir` returned one level of subdirectory content mixed into the top level, which made
+  the agent believe folders were missing. It is now top-level only unless `recursive` is set.
+- `list_dir` no longer follows symlinks while listing, so a dead link cannot block it, and it
+  reports unreadable directories in `errors` instead of silently skipping them.
+- A blocked call now answers `APPROVAL_PENDING` (with the `approval_id` and what to run)
+  instead of `PROTECTED`, so the agent can tell "waiting for a human" from "not allowed".
+- The default approval wait dropped from 90 s to 45 s.
+- `arena-bridge trust` no longer crashes with `trustState is not defined` (Node CLI).
+- The agent token, the device token and the local token are separate; approvals now require the
+  local token, so the agent cannot approve its own requests.
+
+## 0.4.0
+
+### Added
+- Chrome control over CDP with a dependency-free WebSocket/CDP client: 12 `chrome_*` tools,
+  an agent-owned browser (headless or visible) and attaching to the user's own Chrome on 9222.
+- Trust windows: `arena-bridge trust --for 2h [--tools ...] [--paths ...]`, local only, and
+  it lifts approvals without weakening the path policy.
+- `localToken` gates approval decisions; `~/.arena-bridge` joined the protected paths.
+
+## 0.3.0
+
+### Fixed
+- Repeated `--root` flags accumulate instead of overwriting each other; comma lists are split.
+- A friendly message when the port is already in use.
+- The policy is re-read from disk on every call, so changes apply without a restart.
+
+## 0.2.0
+
+### Added
+- Cloudflared quick tunnel helper (`arena-bridge tunnel`), HTTP/2 transport by default.
+- Token rotation (`arena-bridge rotate`).
+
+## 0.1.0
+
+- First release: local HTTP API, MCP endpoint, files, shell, processes, approvals, audit log.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arena-bridge contributors
+
+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

@@ -1,3 +1,284 @@
-# Temporary Holding Version
+<div align="center">
+  <img src="docs/cover.png" alt="arena-bridge" width="100%">
+</div>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">arena-bridge</h1>
+
+<p align="center"><b>Облачный ИИ-агент получает управление вашим компьютером — и только с вашего разрешения.</b></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/arena-bridge"><img src="https://img.shields.io/npm/v/arena-bridge.svg?style=flat-square" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/arena-bridge"><img src="https://img.shields.io/npm/dm/arena-bridge.svg?style=flat-square" alt="downloads"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-green.svg?style=flat-square" alt="node">
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square" alt="dependencies">
+  <img src="https://img.shields.io/badge/tests-92%20passed-brightgreen.svg?style=flat-square" alt="tests">
+</p>
+
+<p align="center">
+  <code>npm i -g arena-bridge</code> &nbsp;→&nbsp; <code>arena-bridge setup</code> &nbsp;→&nbsp; вставьте готовый промпт в чат с агентом
+</p>
+
+---
+
+## Что это
+
+Облачный агент (Arena.ai Agent Mode, Claude, Cursor, любой MCP-клиент) работает в песочнице
+с выходом в интернет, но не имеет доступа к вашему компьютеру. `arena-bridge` — это маленький
+HTTP-сервис на вашей машине: он слушает только localhost, выставляется наружу туннелем
+(cloudflared / ngrok / Tailscale) и отдаёт агенту инструменты, которые вы ему разрешили:
+
+* **файлы и шелл** — прочитать, найти, изменить, запустить;
+* **Chrome** — свой браузер агента (headless или с окном) или ваш настоящий Chrome на порту 9222;
+* **macOS-десктоп** — скриншоты, мышь, клавиатура, приложения (через Peekaboo);
+* **процессы** — фоновые дев-серверы с чтением вывода.
+
+Всё, что меняет состояние, проходит через гейт подтверждений, а каждое действие пишется в журнал.
+Без вашего `arena-bridge approve` агент ничего не сделает. Наблюдать за машиной можно без
+подтверждений, а работать «без вопросов» — внутри окна доверия, которое вы открываете сами.
+
+---
+
+## Быстрый старт
+
+```bash
+# 1. установить
+npm i -g arena-bridge
+
+# 2. один раз: создать конфиг, проверить машину, поднять API + туннель
+arena-bridge setup --root ~/projects --root ~/Documents
+
+# 3. скопировать блок «Paste this into the agent chat» и вставить его в чат с агентом
+```
+
+`setup` печатает готовый промпт и публичный URL. Дальше — просто говорите агенту задачу.
+
+Нужен туннель? Поставьте `cloudflared` (`brew install cloudflared` или бинарник в `/usr/local/bin`).
+Подойдёт и любой другой: `ngrok http 8787`, `tailscale funnel --bg 8787`.
+
+### В фоне, чтобы не открывать терминал
+
+```bash
+arena-bridge service install   # launchd: стартует вместе с системой, URL всегда живой
+arena-bridge url                # текущий публичный URL
+```
+
+### Python
+
+```bash
+pipx install arena-bridge       # или: pip install arena-bridge
+arena-bridge setup --root ~/projects
+```
+
+---
+
+## Что агент умеет
+
+| Группа | Инструменты | Что это |
+| --- | --- | --- |
+| Файлы | `list_dir` `read_file` `write_file` `edit_file` `delete_path` `search_files` `file_get` `file_put` | работа с файлами в разрешённых папках |
+| Шелл | `bash` `sysinfo` | команды и сведения о машине |
+| Процессы | `start_process` `read_process_output` `write_process` `kill_process` | фоновые дев-серверы |
+| Chrome | `chrome_launch` `chrome_attach` `chrome_open` `chrome_navigate` `chrome_snapshot` `chrome_click` `chrome_type` `chrome_press` `chrome_screenshot` `chrome_evaluate` `chrome_tabs` `chrome_stop` | браузер через CDP |
+| Десктоп | `mac_see` `mac_click` `mac_type` `mac_key` `mac_scroll` `mac_move` `mac_drag` `mac_apps` `mac_windows` `mac_app_launch` `mac_app_focus` `mac_app_quit` `mac_permissions` | macOS через Peekaboo |
+
+Полный каталог с JSON-схемами: `GET /tools` или `arena-bridge tools`.
+
+### Как выбрать инструмент
+
+| Агент хочет | Инструмент |
+| --- | --- |
+| прочитать страницу | `chrome_snapshot` (`{"mode":"ax"}` — роли и имена, `{"mode":"text"}`, `{"mode":"html"}`) |
+| кликнуть на странице | `chrome_click` (CSS-селектор или видимый текст) |
+| работать в вашем залогиненном Chrome | `chrome_attach` (порт 9222) и те же `chrome_*` |
+| посмотреть на экран или нативное приложение | `mac_see` (скриншот + id кликабельных элементов) |
+| кликнуть в нативном приложении | `mac_click` (id элемента, видимый текст или координаты) |
+| напечатать | `mac_type`, затем `mac_key` для Enter/Tab/cmd+s |
+| посмотреть файлы | `list_dir` (только верхний уровень; глубже — `{"recursive":true}`) |
+
+---
+
+## Управление Chrome
+
+Свой минимальный CDP-клиент внутри пакета: **ни puppeteer, ни playwright не нужны**.
+
+```jsonc
+// браузер агента: свой профиль, без ваших cookie
+{"tool": "chrome_launch", "args": {"headless": true, "url": "https://example.com"}}
+// прочитать структуру страницы
+{"tool": "chrome_snapshot", "args": {"mode": "ax"}}
+// кликнуть и ввести
+{"tool": "chrome_click", "args": {"text": "Sign in"}}
+{"tool": "chrome_type", "args": {"selector": "input[name=q]", "text": "hello", "submit": true}}
+// скриншот
+{"tool": "chrome_screenshot", "args": {"path": "shot.png"}}
+```
+
+* `headless: true` — без окна (по умолчанию), `headless: false` — видимое окно;
+* профиль отдельный (`~/.arena-bridge/chrome-profile-*`), в ваши сессии агент не попадает;
+* действия в браузере агента подтверждения не требуют — это его песочница.
+
+**Ваш настоящий Chrome** (с вашими логинами) — через `chrome_attach`:
+
+```bash
+open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug"
+```
+
+```jsonc
+{"tool": "chrome_attach", "args": {"port": 9222}}
+```
+
+Любое действие в присоединённом браузере требует локального подтверждения. Инструментов чтения
+cookies и localStorage нет.
+
+---
+
+## Управление macOS-десктопом
+
+Через [Peekaboo](https://github.com/openclaw/Peekaboo) (это же использует и MCP-режим Peekaboo):
+
+```jsonc
+{"tool": "mac_see", "args": {"app": "Safari", "mode": "window"}}  // скриншот + id элементов
+{"tool": "mac_click", "args": {"on": "B3"}}                        // клик по id из mac_see
+{"tool": "mac_type", "args": {"text": "hello", "submit": true}}
+{"tool": "mac_key", "args": {"key": "cmd+s"}}
+{"tool": "mac_apps", "args": {}}                                  // что запущено
+{"tool": "mac_permissions", "args": {}}                           // чего не хватает в macOS
+```
+
+Установить Peekaboo: `brew install peekaboo` (или бинарник в `/usr/local/bin/peekaboo`).
+macOS спросит разрешения **Screen Recording** и **Accessibility** для терминала, из которого
+запущен мост — без них скриншоты и клики не работают; `mac_permissions` покажет, что не так.
+
+---
+
+## Доверенное окно: работать без подтверждений
+
+```bash
+arena-bridge trust --for 2h                                   # всё, на 2 часа
+arena-bridge trust --for 30m --tools bash                     # только команды
+arena-bridge trust --for 1h --paths ~/projects/my-app         # только эта папка
+arena-bridge trust --status
+arena-bridge trust --off
+```
+
+* окно снимает требование **подтверждения**, но не снимает **политику путей**: за пределами
+  `roots` и в защищённых каталогах по-прежнему `PROTECTED`;
+* `--paths` ограничивает доверие конкретными папками; `bash` под такое ограничение не попадает —
+  чтобы доверять командам, укажите `--tools bash` явно;
+* окно живёт локально (`~/.arena-bridge/trust.json`), агент открыть его не может;
+* после истечения срока подтверждения возвращаются сами, а все действия остаются в журнале.
+
+---
+
+## Безопасность
+
+| Токен | Кто знает | Что позволяет |
+| --- | --- | --- |
+| `token` | агент | вызывать инструменты по HTTP/MCP |
+| `deviceToken` | только устройство | подключаться к хабу |
+| `localToken` | только вы | подтверждать запросы и открывать окно доверия |
+
+* **Агент не может одобрить сам себя**: `POST /approvals/:id` требует локальный токен.
+* **Пути ограничены**: всё вне `roots` — `PROTECTED`. Защищённый список по умолчанию включает
+  `~/.ssh`, `~/.aws`, `~/.arena-bridge`, `~/.npmrc`, профили браузеров, ключи.
+* **Подтверждения**: `bash`, запись, удаление, управление вашим Chrome и десктопом ждут
+  `arena-bridge approve <id>`. Ответ `APPROVAL_PENDING` содержит `approval_id` — покажите его
+  пользователю и повторите вызов один раз.
+* **Журнал**: `~/.arena-bridge/audit.log` (JSONL) — кто, что и когда вызвал.
+* **Транспорт**: сервер слушает `127.0.0.1`, наружу — только туннель с HTTPS.
+
+```bash
+arena-bridge rotate            # новый агентский токен (действует мгновенно)
+arena-bridge rotate --device   # новый девайсный токен
+arena-bridge audit -n 50       # что происходило
+```
+
+---
+
+## Команды
+
+| Команда | Что делает |
+| --- | --- |
+| `setup` | конфиг + проверка машины + API + туннель + готовый промпт |
+| `init` | создать `~/.arena-bridge/config.json` с токенами (`--root` повторяемый) |
+| `start` | локальный API-сервер |
+| `tunnel` | API + облачный туннель, печатает промпт |
+| `hub` / `connect` | режим «хаб»: VPS принимает подключения многих машин |
+| `prompt` | готовый промпт для чата с агентом |
+| `tools` | каталог инструментов в JSON |
+| `trust` | окно доверия (`--for`, `--tools`, `--paths`, `--off`, `--status`) |
+| `approvals` / `approve <id>` | ожидающие подтверждения и ответ на них (`--deny`) |
+| `audit [-n N]` | журнал действий |
+| `doctor` | проверка установки, токенов, путей, Peekaboo, Chrome |
+| `url` | текущий публичный URL |
+| `version` | установленная и последняя версии |
+| `update` | обновить пакет с npm (`--check` — только проверить) |
+| `service` | macOS-фоновый сервис: `install` / `uninstall` / `status` |
+| `rotate` | сменить агентский или девайсный токен |
+
+---
+
+## API и MCP
+
+```
+GET  /health          liveness (без авторизации)
+GET  /tools           каталог инструментов с JSON-схемами
+GET  /prompt          этот промпт для агента
+GET  /approvals       ожидающие подтверждения
+POST /call            {"tool":"bash","args":{...}}
+POST /exec            {"command":"...","cwd":"...","timeout_sec":120}
+GET|PUT|DELETE /files?path=/abs/path
+POST /approvals/:id   {"decision":"approve"|"deny"}   — только по локальному токену
+POST /mcp             MCP Streamable HTTP (protocolVersion 2025-06-18)
+```
+
+```bash
+curl -sS -X POST "https://<ваш-url>/call" \
+  -H "Authorization: Bearer $ARENA_BRIDGE_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tool":"sysinfo","args":{}}'
+```
+
+---
+
+## Разработка
+
+```bash
+npm install          # зависимостей нет — только dev-тесты
+npm test             # 50 тестов Node: direct, approval, trust, MCP, hub, туннель, Chrome, десктоп
+npm run test:python  # 42 теста Python: то же самое
+```
+
+Тесты не требуют ни Chrome, ни Peekaboo: используются фейковые CDP- и Peekaboo-серверы
+(`test/fake-cdp.mjs`, `test/fake-peekaboo.sh`).
+
+```
+src/            Node-реализация (zero dependencies)
+  ws.mjs        минимальный WebSocket-клиент
+  cdp.mjs       клиент Chrome DevTools Protocol
+  browser.mjs   12 инструментов chrome_*
+  mac.mjs       13 инструментов mac_* (Peekaboo)
+  trust.mjs     окно доверия
+  policy.mjs    проверка путей (roots / protected)
+  engine.mjs    каталог, гейт подтверждений, аудит
+  direct.mjs    HTTP-сервер
+  hub.mjs       хаб для нескольких машин
+  cli.mjs       команды
+arena_bridge/  тот же функционал на Python (stdlib only)
+```
+
+## Частые проблемы
+
+| Симптом | Что делать |
+| --- | --- |
+| `port 8787 is already in use` | остановите старый экземпляр (`Ctrl+C`) или `arena-bridge start --port 8788` |
+| туннель не поднимается | `cloudflared` по умолчанию использует QUIC и может быть заблокирован — `arena-bridge tunnel --protocol http2` (это поведение по умолчанию) |
+| агент не видит файлы | проверьте `arena-bridge doctor` и `roots` в `~/.arena-bridge/config.json`; вне `roots` всё равно `PROTECTED` |
+| `APPROVAL_PENDING` | покажите пользователю `arena-bridge approve <id>` или откройте `arena-bridge trust --for 1h` |
+| скриншоты не работают | `mac_permissions` — выдайте терминалу Screen Recording и Accessibility |
+| `peekaboo_not_found` | поставьте Peekaboo или укажите путь: `arena-bridge init` + `peekabooPath` в конфиге |
+
+## Лицензия
+
+MIT

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security policy
+
+## Threat model
+
+`arena-bridge` gives a remote AI agent access to a machine. The package is designed so that a
+compromise of the agent, of the chat or of the tunnel does not automatically become a compromise
+of the machine.
+
+## What protects the machine
+
+- **Localhost only.** The server binds `127.0.0.1` by default. Public access requires an explicit
+  tunnel.
+- **Three separate tokens.** The agent token can only call tools, the device token only connects
+  a device to a hub, and the local token approves requests. The agent never receives the local
+  token and cannot approve its own requests.
+- **Path policy.** Every file operation is limited to the configured `roots`. A protected list
+  (`~/.ssh`, `~/.aws`, `~/.arena-bridge`, browser profiles, credential files) is denied even
+  inside a root.
+- **Approval gate.** Side-effecting tools wait for a human decision. The answer identifies the
+  pending approval so the user can approve it with `arena-bridge approve <id>`.
+- **Trust windows are local.** Only the local CLI can open one, and it never weakens the path
+  policy — it only removes the approval requirement.
+- **Audit log.** Every call is appended to `~/.arena-bridge/audit.log` (0600) with the tool, the
+  arguments and the outcome.
+
+## Reporting a vulnerability
+
+Please report issues privately to the repository owner instead of opening a public issue.

package/bin/arena-bridge.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs';
+
+main().catch((e) => {
+  console.error(`error: ${e?.message || e}`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "arena-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.1",
+  "description": "Give a cloud AI agent (Arena.ai Agent Mode, Claude, Cursor, ...) controlled access to your own machine over HTTP/MCP: files, shell, Chrome and the macOS desktop, with an approval gate, trust windows and an audit log.",
+  "type": "module",
+  "bin": {
+    "arena-bridge": "bin/arena-bridge.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs/cover.png",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs",
+    "test:node": "node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs",
+    "test:python": "python3 test/test_bridge.py && python3 test/test_browser.py && python3 test/test_mac.py",
+    "pack:check": "npm pack --dry-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vernikr-personal/arena-bridge.git"
+  },
+  "homepage": "https://github.com/vernikr-personal/arena-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/vernikr-personal/arena-bridge/issues"
+  },
+  "keywords": [
+    "mcp",
+    "arena",
+    "agent",
+    "agent-mode",
+    "remote-control",
+    "macos",
+    "chrome",
+    "cdp",
+    "peekaboo",
+    "automation",
+    "sandbox",
+    "mcp-server",
+    "self-hosted"
+  ],
+  "author": "vernikr-personal",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/approvals.mjs

@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { APPROVALS_DIR, ensureDirs } from './config.mjs';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function fileOf(id) {
+  return path.join(APPROVALS_DIR, `${id}.json`);
+}
+
+export function listApprovals() {
+  if (!fs.existsSync(APPROVALS_DIR)) return [];
+  return fs
+    .readdirSync(APPROVALS_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(APPROVALS_DIR, f), 'utf8'));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.createdAt - a.createdAt);
+}
+
+export function decide(id, decision, by = 'cli') {
+  const file = fileOf(id);
+  if (!fs.existsSync(file)) return { ok: false, error: `unknown approval id: ${id}` };
+  let rec;
+  try {
+    rec = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+  if (rec.status !== 'pending') return { ok: false, error: `already ${rec.status}` };
+  rec.status = decision === 'approve' ? 'approved' : 'denied';
+  rec.decidedAt = Date.now();
+  rec.decidedBy = by;
+  fs.writeFileSync(file, JSON.stringify(rec, null, 2), { mode: 0o600 });
+  return { ok: true, approval: rec };
+}
+
+function redact(args) {
+  const clone = { ...args };
+  for (const k of Object.keys(clone)) {
+    if (/token|secret|password|key/i.test(k)) clone[k] = '***';
+  }
+  if (typeof clone.command === 'string' && clone.command.length > 4000) {
+    clone.command = clone.command.slice(0, 4000) + '…';
+  }
+  return clone;
+}
+
+/**
+ * Create a pending approval request and wait for a local human decision.
+ * The request lives in a file so that the `arena-bridge approve` CLI (a separate
+ * process) can pick it up.
+ */
+export async function requestApproval(tool, args, cfg) {
+  ensureDirs();
+  const id = crypto.randomUUID();
+  const now = Date.now();
+  const rec = {
+    id,
+    tool,
+    args: redact(args),
+    status: 'pending',
+    createdAt: now,
+    expiresAt: now + (cfg.approvalTtlSec ?? 900) * 1000,
+    decidedAt: null,
+    decidedBy: null,
+  };
+  fs.writeFileSync(fileOf(id), JSON.stringify(rec, null, 2), { mode: 0o600 });
+
+  const waitSec = Math.min(cfg.approvalWaitSec ?? 90, cfg.approvalTtlSec ?? 900);
+  const deadline = now + waitSec * 1000;
+  while (Date.now() < deadline) {
+    await sleep(400);
+    let cur;
+    try {
+      cur = JSON.parse(fs.readFileSync(fileOf(id), 'utf8'));
+    } catch {
+      continue;
+    }
+    if (cur.status === 'approved') return { approved: true, rec: cur };
+    if (cur.status === 'denied') return { approved: false, rec: cur };
+    if (cur.expiresAt && Date.now() > cur.expiresAt) {
+      return { approved: false, rec: { ...cur, status: 'expired' } };
+    }
+  }
+  return { approved: false, rec: { ...rec, status: 'timeout' } };
+}

package/src/audit.mjs

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_DIR, AUDIT_PATH } from './config.mjs';
+
+export function audit(entry) {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    const rec = { ts: new Date().toISOString(), ...entry };
+    fs.appendFileSync(AUDIT_PATH, JSON.stringify(rec) + '\n', { mode: 0o600 });
+  } catch {
+    /* auditing must never break the request */
+  }
+}
+
+export function tailAudit(n = 50) {
+  if (!fs.existsSync(AUDIT_PATH)) return [];
+  const lines = fs.readFileSync(AUDIT_PATH, 'utf8').trim().split('\n').filter(Boolean);
+  return lines
+    .slice(-n)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return { raw: l };
+      }
+    });
+}