arena-bridge 0.14.1 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,19 @@ All notable changes to this project are documented here.
4
4
  The format follows [Keep a Changelog](https://keepachangelog.com/) and the project uses
5
5
  [Semantic Versioning](https://semver.org/).
6
6
 
7
+ ## 0.15.0
8
+
9
+ ### Added
10
+ - `arena-bridge permissions` checks Screen Recording and Accessibility (exit code 3 when one is missing).
11
+ - The Control card warns when a macOS permission is missing and opens a step-by-step guide.
12
+ - `build.sh` signs with `ARENA_SIGN_IDENTITY`; a certificate keeps the macOS permissions across rebuilds.
13
+
14
+ ### Changed
15
+ - The README and the agent prompt name the Arena Bridge app, not the terminal, as the holder of the permissions.
16
+
17
+ ### Fixed
18
+ - The source of a log entry is its own column.
19
+
7
20
  ## 0.14.1
8
21
 
9
22
  ### Fixed
package/README.md CHANGED
@@ -199,8 +199,7 @@ cookies и localStorage нет.
199
199
 
200
200
  Установить Peekaboo: `brew install peekaboo` (или бинарник в `/usr/local/bin/peekaboo`).
201
201
  Проверено с Peekaboo 4.9 (4.3 тоже работает, но синтаксис команд обновлён под 4.9).
202
- macOS спросит разрешения **Screen Recording** и **Accessibility** для терминала, из которого
203
- запущен мост — без них скриншоты и клики не работают; `mac_permissions` покажет, что не так.
202
+ macOS asks for **Screen Recording** and **Accessibility** for the Arena Bridge app; without them screenshots and clicks fail. See [macOS permissions](#macos-permissions).
204
203
 
205
204
  ### Что даёт доступ Accessibility
206
205
 
@@ -219,8 +218,7 @@ macOS отдаёт приложениям два разных слоя: карт
219
218
 
220
219
  Практический вывод: с выданным Accessibility агент работает заметно точнее и тише. Разрешение
221
220
  даётся один раз в **Системные настройки → Конфиденциальность и безопасность → Универсальный
222
- доступ** (для терминала, из которого запущен мост). `mac_permissions` показывает текущее
223
- состояние разрешений.
221
+ доступ** (for the Arena Bridge app, see [macOS permissions](#macos-permissions)). `mac_permissions` shows the current state.
224
222
 
225
223
  ---
226
224
 
@@ -317,39 +315,45 @@ Apple Silicon. Готовые сборки для обеих архитекту
317
315
  Иконка приложения лежит в `macos/ArenaBridge/Resources/AppIcon.png`; `build.sh` сам собирает
318
316
  из неё `.icns` и кладёт в бандл. Вокруг знака прозрачно — на светлом фоне иконка не белая.
319
317
 
320
- ### Разрешения macOS
318
+ ### macOS permissions
321
319
 
322
- Мосту нужны два разрешения в «Конфиденциальность и безопасность»:
320
+ The bridge takes screenshots and clicks through the helper **arena-bridge-agent** inside **Arena Bridge.app**, so macOS needs two permissions for it:
323
321
 
324
- - **Запись экрана и системного аудио** → включите **Arena Bridge**.
325
- - **Универсальный доступ (Accessibility)** → включите **arena-bridge-agent**.
322
+ - **Screen Recording** (System Settings → Privacy & Security → Screen & System Audio Recording)
323
+ - **Accessibility** (System Settings → Privacy & Security → Accessibility)
326
324
 
327
- Это части одного приложения. После изменения разрешений может потребоваться перезапуск службы.
328
- Старую запись `node` удаляйте только после проверки снимков и дерева элементов (`mac_see`).
329
- Успешное сохранение PNG ещё не доказывает доступ: на снимке должно быть содержимое окон,
330
- а не только обои. Без Accessibility снимок может работать, но дерево элементов будет пустым.
325
+ Check them at any time with `arena-bridge permissions` (exit code 3 when something is missing) or with the `mac_permissions` tool. The app shows a warning on the **Control** card when either permission is missing. Click **Fix…** to open the step-by-step guide.
331
326
 
332
- После установки приложения переустановите службу (`arena-bridge service install` с прежними
333
- параметрами туннеля), чтобы она использовала помощник внутри бандла
334
- (`Contents/Helpers/arena-bridge-agent`). Без приложения CLI продолжает работать, но названия
335
- записей разрешений могут отличаться.
327
+ #### Grant the permissions (about 3 minutes)
336
328
 
337
- Стабильный путь к интерпретатору снижает риск потери разрешений, но не гарантирует их сохранение
338
- после изменения подписи, пути или обновления приложения. Проверяйте разрешения для реально
339
- запущенной установки. В частности, обновление ad-hoc-подписанного помощника может оставить
340
- переключатели включёнными, но фактически лишить процесс доступа: выключите и снова включите
341
- **Arena Bridge** в записи экрана и **arena-bridge-agent** в Accessibility, затем перезапустите службу.
342
- Если это не помогло, удалите только эти две записи кнопкой «−» и добавьте заново через «+»:
343
- `/Applications/Arena Bridge.app` и
344
- `/Applications/Arena Bridge.app/Contents/Helpers/arena-bridge-agent` соответственно.
345
- Не храните резервные сборки с тем же bundle id как зарегистрированные `.app`:
346
- это затрудняет выбор нужной установки.
329
+ The screen runtime is the helper **arena-bridge-agent** inside the app (`/Applications/Arena Bridge.app/Contents/Helpers/arena-bridge-agent`). macOS checks that helper, so it is the entry to switch on. Each missing permission has its own **Fix …** button on the Control card, which opens a guide with that permission's steps.
347
330
 
348
- Переустановка службы выполняется отдельным одноразовым системным заданием через несколько
349
- секунд после команды. Это позволяет переустанавливать мост через сам мост. `scheduled` означает
350
- только постановку задания, не успешный запуск. Результат загрузки службы — в
351
- `~/.arena-bridge/service-reload.status`, ошибки — в `~/.arena-bridge/logs/service-reload.err.log`.
352
- Проверяйте также `arena-bridge service status` и `/health`: `loaded` ещё не гарантирует работу туннеля.
331
+ 1. Click **Fix Screen Recording…** on the Control card. Click the path in the guide to copy it.
332
+ 2. Click **Open Screen Recording settings** in the guide. In the list, click **+**. If **+** is grey, click the lock at the bottom left and enter your Mac password.
333
+ 3. Press ⌘⇧G, paste the path, press Return, then click **Open**. Switch on **arena-bridge-agent**.
334
+ 4. If macOS asks you to quit Arena Bridge, click **Later**. Do not choose Quit & Reopen yet.
335
+ 5. Repeat steps 1–4 for **Accessibility** with its own **Fix Accessibility…** button.
336
+ 6. Quit Arena Bridge with ⌘Q, open it again, and click **Check again** in each guide. The warning disappears when both permissions are granted.
337
+
338
+ Harder cases:
339
+
340
+ - **The switch is on, but the app still says "missing".** The entry is stale, which usually happens after an update. Select arena-bridge-agent, click **−**, then **+**, and add it again.
341
+ - **The app is not in `/Applications`.** Move it there first. macOS ties permissions to the exact file location.
342
+ - **Still missing after all of the above.** Restart the Mac, open Arena Bridge, and click **Check again**.
343
+
344
+ #### Keep the permissions across updates
345
+
346
+ The **Keep permissions after updates…** button in each permission guide opens the same steps inside the app.
347
+
348
+ macOS identifies an app by its signature. Builds without your own certificate are *ad-hoc* signed, and macOS can reset their permissions after every rebuild. To avoid this, create a certificate once:
349
+
350
+ 1. Open **Keychain Access** (Spotlight → "Keychain Access").
351
+ 2. Menu **Keychain Access → Certificate Assistant → Create a Certificate…**
352
+ 3. Name: `Arena Bridge Local`. Identity Type: **Self-Signed Root**. Certificate Type: **Code Signing**. Click **Create**, then **Done**.
353
+ 4. In Keychain Access, choose **login** under Keychains and search for `Arena Bridge Local`. Three items appear: a certificate, a public key and a private key. Double-click the item whose Kind is **certificate**, expand **Trust**, set **When using this certificate** to **Always Trust**, close the window, and enter your password.
354
+ 5. Build with it: `ARENA_SIGN_IDENTITY="Arena Bridge Local" bash macos/ArenaBridge/build.sh`. Install the app and grant the permissions once more. Later builds signed the same way keep them.
355
+
356
+ Release downloads are ad-hoc signed, so after installing one, follow the grant steps again. The Control card warning and `arena-bridge permissions` show the state after every update.
353
357
 
354
358
  ### Как переименовать
355
359
 
@@ -562,7 +566,7 @@ arena_bridge/ тот же функционал на Python (stdlib only)
562
566
  | туннель не поднимается | `cloudflared` по умолчанию использует QUIC и может быть заблокирован — `arena-bridge tunnel --protocol http2` (это поведение по умолчанию) |
563
567
  | агент не видит файлы | проверьте `arena-bridge doctor` и `roots` в `~/.arena-bridge/config.json`; вне `roots` всё равно `PROTECTED` |
564
568
  | `APPROVAL_PENDING` | при `timeout`/`expired` старый запрос закрыт: согласуйте новый вызов или попросите открыть `arena-bridge trust --for 1h` |
565
- | скриншоты не работают | `mac_permissions` — выдайте терминалу Screen Recording и Accessibility |
569
+ | скриншоты не работают | `arena-bridge permissions` — выдайте Arena Bridge Screen Recording и Accessibility (see [macOS permissions](#macos-permissions)) |
566
570
  | `peekaboo_not_found` | поставьте Peekaboo или укажите путь: `arena-bridge init` + `peekabooPath` в конфиге |
567
571
 
568
572
  ## Лицензия
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "arena-bridge",
3
- "version": "0.14.1",
3
+ "version": "0.15.0",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -19,8 +19,8 @@
19
19
  "node": ">=18"
20
20
  },
21
21
  "scripts": {
22
- "test": "node --test test/approvals.test.mjs && node --test test/telegram.test.mjs && node --test test/test_security.mjs && node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs && node test/service.test.mjs && node --test test/log.test.mjs && node --test test/log-paging.test.mjs",
23
- "test:node": "node --test test/approvals.test.mjs && node --test test/telegram.test.mjs && node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs && node test/service.test.mjs && node --test test/log.test.mjs && node --test test/log-paging.test.mjs",
22
+ "test": "node --test test/approvals.test.mjs && node --test test/telegram.test.mjs && node --test test/test_security.mjs && node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs && node test/service.test.mjs && node --test test/log.test.mjs && node --test test/log-paging.test.mjs && node --test test/permissions.test.mjs",
23
+ "test:node": "node --test test/approvals.test.mjs && node --test test/telegram.test.mjs && node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs && node test/service.test.mjs && node --test test/log.test.mjs && node --test test/log-paging.test.mjs && node --test test/permissions.test.mjs",
24
24
  "test:python": "python3 test/test_approvals.py && python3 test/test_bridge.py && python3 test/test_browser.py && python3 test/test_mac.py && python3 test/test_service.py && python3 test/test_telegram.py",
25
25
  "pack:check": "npm pack --dry-run"
26
26
  },
package/src/cli.mjs CHANGED
@@ -16,7 +16,7 @@ import { startTunnel, isPortOpen } from './tunnel.mjs';
16
16
  import { spawn, execSync, spawnSync } from 'node:child_process';
17
17
  import { parseDuration, trustState, openTrust, closeTrust, reconcileTrust } from './trust.mjs';
18
18
  import { bridgeEvent, tunnelEvent } from './lifecycle.mjs';
19
- import { findPeekaboo } from './mac.mjs';
19
+ import { findPeekaboo, permissionStatus } from './mac.mjs';
20
20
  import { coldStartMs, mem, uptimeSec } from './telemetry.mjs';
21
21
  import { tailLog, logPathForCli } from './log.mjs';
22
22
  import { VERSION } from './version.mjs';
@@ -109,6 +109,7 @@ Commands:
109
109
  inbox [-n N] show the messages the user sent
110
110
  poll listen for messages in the foreground
111
111
  doctor [--fix] Check the installation and configuration (--fix repairs perms/dirs)
112
+ permissions [--json] Check macOS Screen Recording and Accessibility for the bridge (exit 3 if missing)
112
113
  status [--json] One-line runtime status (config, url, trust, approvals, service)
113
114
  url Print the public URL the agent should use
114
115
  open Open the public URL in the browser
@@ -589,6 +590,22 @@ function cmdOpen() {
589
590
  }
590
591
  }
591
592
 
593
+ async function cmdPermissions(args) {
594
+ const st = await permissionStatus(loadConfig());
595
+ if (args.flags.json) {
596
+ console.log(JSON.stringify(st));
597
+ } else if (!st.ok && st.error) {
598
+ console.log(`permissions: ${st.error}`);
599
+ } else {
600
+ const label = (v) => (v === true ? 'granted' : v === false ? 'MISSING' : 'unknown');
601
+ console.log(`Screen Recording: ${label(st.screen)}`);
602
+ console.log(`Accessibility: ${label(st.accessibility)}`);
603
+ if (st.source) console.log(`checked by: ${st.source}`);
604
+ if (!st.ok) console.log('Fix: System Settings → Privacy & Security → Screen Recording and Accessibility → add Arena Bridge (see README "macOS permissions").');
605
+ }
606
+ process.exitCode = st.ok ? 0 : 3;
607
+ }
608
+
592
609
  function cmdStatus(args) {
593
610
  const isJson = !!(args.flags.json || args.flags['output-json']);
594
611
  const cfg = loadConfig();
@@ -1118,6 +1135,8 @@ export async function main(argv = process.argv.slice(2)) {
1118
1135
  return cmdTrust(args);
1119
1136
  case 'doctor':
1120
1137
  return cmdDoctor(args);
1138
+ case 'permissions':
1139
+ return cmdPermissions(args);
1121
1140
  case 'status':
1122
1141
  return cmdStatus(args);
1123
1142
  case 'url':
package/src/mac.mjs CHANGED
@@ -881,18 +881,37 @@ export function macTools(cfg = {}) {
881
881
  'Screen Recording and Accessibility are required for screen capture and synthetic input.',
882
882
  };
883
883
  }
884
- const res = await runVariants(p.bin, [['permissions'], ['permissions', '--json']], { timeout: 30 });
884
+ const res = await runVariants(p.bin, [['permissions', '--no-remote'], ['permissions', '--json', '--no-remote']], { timeout: 30 });
885
885
  return {
886
886
  ok: res.exit_code === 0,
887
887
  permissions: res.stdout.slice(0, 4000) || undefined,
888
888
  error: res.exit_code === 0 ? undefined : (res.stderr || '').trim().slice(0, 600),
889
- hint: 'System Settings → Privacy & Security → Screen Recording / Accessibility → enable the terminal that runs the bridge.',
889
+ hint: 'System Settings → Privacy & Security → Screen Recording / Accessibility → enable Arena Bridge (see README, macOS permissions).',
890
890
  };
891
891
  },
892
892
  },
893
893
  ];
894
894
  }
895
895
 
896
+ /**
897
+ * Screen Recording and Accessibility as the bridge's screen runtime reports them.
898
+ * Read-only: it asks Peekaboo for its permission lines and never changes anything.
899
+ */
900
+ export async function permissionStatus(cfg = {}) {
901
+ const p = checkPeek(findPeekaboo(cfg));
902
+ if (!p.ok) return { ok: false, error: 'peekaboo_not_found' };
903
+ const res = await runVariants(p.bin, [['permissions', '--no-remote']], { timeout: 30 });
904
+ const text = res.stdout || '';
905
+ const grant = (label) => {
906
+ const m = text.match(new RegExp(label + '[^:\\n]*:\\s*(Not Granted|Granted)'));
907
+ return m ? m[1] === 'Granted' : null;
908
+ };
909
+ const screen = grant('Screen Recording');
910
+ const accessibility = grant('Accessibility');
911
+ const source = (text.match(/Source:\s*(.+)/) || [])[1]?.trim() || null;
912
+ return { ok: screen === true && accessibility === true, screen, accessibility, source };
913
+ }
914
+
896
915
  /** The Peekaboo envelope reports a host that lost its macOS permissions. */
897
916
  function peekError(json) {
898
917
  if (!json || typeof json !== 'object') return null;
package/src/prompt.mjs CHANGED
@@ -94,7 +94,7 @@ ${toolsLine}
94
94
  2. Then \`mac_click\` (by id, by visible text or by coordinates) → \`mac_type\` → \`mac_key\` → \`mac_scroll\`.
95
95
  3. \`mac_apps\` and \`mac_windows\` show what is running; \`mac_app_launch\`/\`mac_app_focus\` open and switch.
96
96
  4. If a capture or a click fails, run \`mac_permissions\` — macOS needs Screen Recording and
97
- Accessibility permissions for the terminal that runs the bridge.
97
+ Accessibility permissions for the Arena Bridge app.
98
98
  5. Screenshots are saved as PNG inside the authorized roots; read them back with \`file_get\`.
99
99
  6. Stay out of the user's way: do not pass \`foreground\`, do not focus windows and do not move the
100
100
  pointer unless the user asks for it. Background actions are delivered to the target window only.
package/src/version.mjs CHANGED
@@ -3,7 +3,7 @@ import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { fileURLToPath } from 'node:url';
5
5
 
6
- export const VERSION = "0.14.1";
6
+ export const VERSION = "0.15.0";
7
7
 
8
8
  export function getVersion() {
9
9
  try {