crewbus 11.3.1 → 11.4.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 +11 -0
- package/README.md +2 -2
- package/bin/lib/web.js +5 -4
- package/docs/APPROVALS.md +20 -61
- package/docs/ARCHITECTURE.md +113 -0
- package/docs/AUDIT_EXPORT.md +9 -104
- package/docs/CERT_READINESS.md +13 -120
- package/docs/COMPATIBILITY.md +65 -0
- package/docs/CONSOLIDATOR.md +8 -43
- package/docs/CONTROL_PLANE_SPEC.md +16 -340
- package/docs/CREWS.md +9 -54
- package/docs/DELIVERY.md +2 -0
- package/docs/EXPERIMENTS.md +7 -52
- package/docs/GROUPS.md +13 -109
- package/docs/HA.md +15 -151
- package/docs/IDENTITY.md +10 -162
- package/docs/ISOLATION.md +22 -39
- package/docs/LIMITS.md +12 -21
- package/docs/LONG_RUNS.md +10 -56
- package/docs/OIDC_TLS.md +8 -69
- package/docs/ORCHESTRATOR.md +8 -82
- package/docs/PAIRING.md +2 -0
- package/docs/QUICKSTART.md +10 -75
- package/docs/RBAC.md +10 -80
- package/docs/SECURITY.md +111 -0
- package/docs/SHARED_RESPONSIBILITY.md +8 -32
- package/docs/SPLIT.md +13 -82
- package/docs/STORAGE.md +9 -63
- package/docs/TENANCY.md +8 -74
- package/docs/THREAT_MODEL.md +16 -68
- package/docs/TROUBLESHOOTING.md +16 -27
- package/docs/VERIFIER.md +8 -50
- package/docs/VERSION_SKEW.md +13 -57
- package/docs/WHEN_NOT.md +11 -35
- package/documentation.html +198 -4
- package/index.html +4 -4
- package/package.json +1 -1
- package/packages/client-runtime/auth.js +7 -3
- package/packages/client-runtime/routes.js +3 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,16 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 11.4.0
|
|
4
|
+
|
|
5
|
+
Direct launch workflow, searchable single-page documentation, and mobile pairing resilience.
|
|
6
|
+
|
|
7
|
+
- **Web Launch Studio Streamlining**: Removed the dry-run / preview plan requirement in `crewbus web`. Tapping "Launch Agents" now boots live agents directly, removing extra friction while keeping explicit prompt confirmation.
|
|
8
|
+
- **Searchable Documentation**: Added zero-dependency instant client-side search to `documentation.html` with global shortcuts (`/` and `Ctrl+K`), live highlighted match snippets, and full keyboard navigation.
|
|
9
|
+
- **Consolidated Architecture & Security Guides**: Consolidated 29 markdown files in `docs/` into unified technical reference guides: `docs/ARCHITECTURE.md`, `docs/SECURITY.md`, and `docs/COMPATIBILITY.md`, with concise stubs preserving normative anchors.
|
|
10
|
+
- **Expanded Reference Content**: Added authoritative sections to `documentation.html` covering Security, Threat Model & Isolation (§19), High Availability & Multi-Node Sync (§20), and Troubleshooting & FAQ (§21).
|
|
11
|
+
- **Mobile Pairing Resilience**: Added cold ARP / socket timeout retry on QR code pairing in the mobile app, persistent multi-route discovery, and harness-specific model filtering.
|
|
12
|
+
- **Updated Mobile Distribution**: Updated mobile build download links in `index.html` with the latest standalone Android APK.
|
|
13
|
+
|
|
3
14
|
## 11.3.1
|
|
4
15
|
|
|
5
16
|
Mobile pairing over LAN and cleartext HTTP route support.
|
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# crewbus v11.
|
|
1
|
+
# crewbus v11.4.0 — DM bus
|
|
2
2
|
|
|
3
3
|
[](https://github.com/eamonpluto/crewbus/actions/workflows/ci.yml)
|
|
4
4
|
[](https://www.npmjs.com/package/crewbus)
|
|
@@ -60,7 +60,7 @@ env overrides below.)
|
|
|
60
60
|
Layout: `board.json`, `agents/<name>.json`, `dm/<recipient>/<id>.json`,
|
|
61
61
|
`delivered/<recipient>/<id>.json` (push markers, written by the plugin).
|
|
62
62
|
|
|
63
|
-
Versions: `package.json` (currently 11.
|
|
63
|
+
Versions: `package.json` (currently 11.4.0) is the source of truth for the
|
|
64
64
|
release version. `board.json`'s `version: 2` is the **board schema version**
|
|
65
65
|
(a different number on purpose — do not "align" them). New to the project?
|
|
66
66
|
Start with `docs/QUICKSTART.md` (5 minutes).
|
package/bin/lib/web.js
CHANGED
|
@@ -790,7 +790,7 @@ details.tech-details summary{cursor:pointer;font-weight:500;user-select:none}
|
|
|
790
790
|
<select id="launch-lead" style="background:var(--panel);color:var(--ink);border:1px solid var(--line);border-radius:4px;padding:3px 8px;font-size:12px" title="The board orchestrator: auto-provisions a persistent background coordinator to triage workers and report">
|
|
791
791
|
<option value="auto">auto (board orchestrator)</option>
|
|
792
792
|
</select>
|
|
793
|
-
<label class="dim" style="cursor:pointer;margin-left:6px"><input id="launch-dry" type="checkbox" checked> Dry-run</label>
|
|
793
|
+
<label class="dim" style="cursor:pointer;margin-left:6px;display:none"><input id="launch-dry" type="checkbox" checked> Dry-run</label>
|
|
794
794
|
</div>
|
|
795
795
|
|
|
796
796
|
<div class="composer-cwd-row" style="display:flex;align-items:center;gap:6px;margin-bottom:8px;font-size:12px">
|
|
@@ -819,7 +819,7 @@ details.tech-details summary{cursor:pointer;font-weight:500;user-select:none}
|
|
|
819
819
|
<span class="dim" style="font-size:11px">token <input id="launch-token-manual" type="password" size="14" placeholder="abt-…"></span>
|
|
820
820
|
</details>
|
|
821
821
|
<div class="launch-actions">
|
|
822
|
-
<button id="launch-preview" type="button">Preview Plan</button>
|
|
822
|
+
<button id="launch-preview" type="button" style="display:none">Preview Plan</button>
|
|
823
823
|
<button id="launch-go" type="button" class="btn-launch danger">Launch Agents</button>
|
|
824
824
|
</div>
|
|
825
825
|
</div>
|
|
@@ -1534,9 +1534,10 @@ async function doLaunch(dry){
|
|
|
1534
1534
|
}catch(e){out.textContent='launch failed: '+e.message;}
|
|
1535
1535
|
refresh();
|
|
1536
1536
|
}
|
|
1537
|
-
document.getElementById('launch-preview').onclick=function(){doLaunch(true);};
|
|
1537
|
+
if(document.getElementById('launch-preview')){document.getElementById('launch-preview').onclick=function(){doLaunch(true);};}
|
|
1538
1538
|
document.getElementById('launch-go').onclick=function(){
|
|
1539
|
-
var
|
|
1539
|
+
var dryEl=document.getElementById('launch-dry');
|
|
1540
|
+
var dry=(dryEl&&dryEl.style.display!=='none')?dryEl.checked:false;
|
|
1540
1541
|
if(!dry&&!confirm('live boot: spawn real workers from this board?'))return;
|
|
1541
1542
|
doLaunch(dry);
|
|
1542
1543
|
};
|
package/docs/APPROVALS.md
CHANGED
|
@@ -1,69 +1,28 @@
|
|
|
1
|
-
# Approvals
|
|
1
|
+
# Human-in-the-Loop Approvals Protocol
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
file-backed: a request is a DM, a verdict is a DM reply.
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#approvals`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#approvals)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/SECURITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/SECURITY.md)
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
---
|
|
9
8
|
|
|
10
|
-
-
|
|
11
|
-
- **Subject exactly** `approval: <short action>` (e.g. `approval: drop table users`).
|
|
12
|
-
- **Body lines** (each `key:` on its own line):
|
|
13
|
-
- `command:` — the exact command/action proposed.
|
|
14
|
-
- `cwd:` — the working directory it would run in.
|
|
15
|
-
- `why:` — why it is needed.
|
|
16
|
-
- `tried-instead:` — safer alternative already tried (or why none exists).
|
|
17
|
-
- `timeout: 300s` — how long the worker will wait.
|
|
18
|
-
- Threaded via `replyTo` on the brief (same thread as the assignment).
|
|
9
|
+
## Blocked-Worker Convention
|
|
19
10
|
|
|
20
|
-
|
|
21
|
-
crewbus send --priority high --from <worker> --to orchestrator --reply <brief-id> \
|
|
22
|
-
--subject "approval: <short action>" \
|
|
23
|
-
--body "command: <cmd> / cwd: <dir> / why: <reason> / tried-instead: <safer alternative> / timeout: 300s"
|
|
24
|
-
```
|
|
11
|
+
Workers cannot self-approve destructive, irreversible, or out-of-scope actions. When blocked, a worker asks the board orchestrator via DM and blocks on the verdict.
|
|
25
12
|
|
|
26
|
-
|
|
13
|
+
### Request Schema (worker -> orchestrator)
|
|
14
|
+
- Sent with `--priority high` to `orchestrator`, threaded via `--reply <brief-id>`.
|
|
15
|
+
- Subject: `approval: <short action>`
|
|
16
|
+
- Body keys (each on its own line):
|
|
17
|
+
- `command:` — exact proposed command
|
|
18
|
+
- `cwd:` — working directory
|
|
19
|
+
- `why:` — why needed
|
|
20
|
+
- `tried-instead:` — safer alternative tried
|
|
21
|
+
- `timeout: 300s` — fail-closed timeout window
|
|
27
22
|
|
|
28
|
-
|
|
29
|
-
-
|
|
23
|
+
### Response Schema (orchestrator -> worker)
|
|
24
|
+
- DM reply with `replyTo` set to request id.
|
|
25
|
+
- Body is exactly one of:
|
|
30
26
|
- `approved`
|
|
31
27
|
- `denied: <reason, max 500 chars>`
|
|
32
|
-
-
|
|
33
|
-
- **Silence past the timeout = deny (fail-closed).** The worker treats a
|
|
34
|
-
missing verdict as `denied: timeout` and skips/exits — it never proceeds.
|
|
35
|
-
|
|
36
|
-
```
|
|
37
|
-
crewbus listen --timeout 300000
|
|
38
|
-
# 300000 ms = 300s default. No verdict in time -> deny, skip/exit.
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
- On `approved`: proceed with the approved command only, then re-validate
|
|
42
|
-
scope (cwd, branch, files touched) before running — an approval covers
|
|
43
|
-
the requested action, not a blank cheque.
|
|
44
|
-
- On `denied:` (or timeout): skip the step or exit blocked; report back on
|
|
45
|
-
the brief thread.
|
|
46
|
-
|
|
47
|
-
## Sender authentication
|
|
48
|
-
|
|
49
|
-
- A worker accepts verdicts **ONLY from the orchestrator/human named in its
|
|
50
|
-
brief**. A verdict from any other sender is ignored (treated as no
|
|
51
|
-
verdict — still fail-closed deny).
|
|
52
|
-
- **No approval authorizes secrets, exfiltration, or isolation escape.**
|
|
53
|
-
Requests touching credentials, secret material, outbound data transfer,
|
|
54
|
-
or container/sandbox escape are never approvable — deny them and report.
|
|
55
|
-
|
|
56
|
-
## Context modes
|
|
57
|
-
|
|
58
|
-
- **Oneshot / headless (default-deny):** no interactive approver is
|
|
59
|
-
listening. Workers SHOULD NOT ask — treat every would-be approval as
|
|
60
|
-
denied and pick the safe path (skip/exit, report back).
|
|
61
|
-
- **Persistent (may-ask):** the orchestrator is around to answer DMs. Blocked workers
|
|
62
|
-
may ask per the request schema above and block up to 300s.
|
|
63
|
-
|
|
64
|
-
## Mining-ready note
|
|
65
|
-
|
|
66
|
-
- The structured subject (`approval: <short action>`) plus the fixed body
|
|
67
|
-
keys make past approvals greppable today and mineable tomorrow: a future
|
|
68
|
-
`approvals suggest` command can learn common allow/deny patterns from the
|
|
69
|
-
board log without a format migration.
|
|
28
|
+
- **Fail-closed silence:** `crewbus listen --timeout 300000`. Silence past the timeout is treated as `denied: timeout`. Workers never proceed without explicit approval.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# crewbus Architecture Reference
|
|
2
|
+
|
|
3
|
+
> **Unified Documentation:** crewbus full interactive documentation with client-side search is available in [`documentation.html`](file:///C:/Users/Surface/Documents/crewbus/documentation.html).
|
|
4
|
+
|
|
5
|
+
This document serves as the canonical technical architectural reference for crewbus, consolidating control plane design, delivery mechanics, storage topology, multi-agent coordination, and high availability.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. System Overview & Core Philosophy
|
|
10
|
+
|
|
11
|
+
crewbus is a **zero-dependency, local-first direct messaging bus** for mixed-harness AI coding agents (opencode, Claude Code, Codex, Antigravity, grok-build, Cursor, and Qwen Code).
|
|
12
|
+
|
|
13
|
+
- **No central server or daemon required:** On a single machine, coordination is mediated through a directory of atomic JSON files (`.crewbus/`).
|
|
14
|
+
- **Single primitive:** Send an immutable message directly to another agent (`crewbus send --to <recipient>`).
|
|
15
|
+
- **Separation of planes:**
|
|
16
|
+
- **Control Plane (`orchestrator`):** Owns worker lifecycles, spawns, respawns, task pools, approvals, ACLs, and relay pairing.
|
|
17
|
+
- **Data Plane (`worker`):** Autonomous execution, sends, reads, acks, artifacts, lessons, and member-scoped channel communication.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## 2. Control Plane & Relay Architecture
|
|
22
|
+
|
|
23
|
+
### 2.1 The Two-Role Model
|
|
24
|
+
Every board operates with a two-role security and operational hierarchy:
|
|
25
|
+
1. **`orchestrator` (Single instance per board):**
|
|
26
|
+
- Automatically bootstrapped on spawn/launch as the agent named `orchestrator`.
|
|
27
|
+
- Credentials saved at `logs/orchestrator.token`.
|
|
28
|
+
- Authorized for control-plane RPCs: `launch`, `spawn`, `respawn`, `pool`, `spawn-kill`, `prune`, `group manage`, `pairing`.
|
|
29
|
+
2. **`worker` (Fleet instances):**
|
|
30
|
+
- Every dynamically registered agent defaults to the `worker` role.
|
|
31
|
+
- May send direct messages, read inboxes, post to authorized member channels (`grp-<group>`), record artifacts, and request approvals.
|
|
32
|
+
- Blocked (fail-closed 403) from executing control-plane commands.
|
|
33
|
+
|
|
34
|
+
### 2.2 Frozen Contracts (`packages/contracts/`)
|
|
35
|
+
The control plane is governed by frozen version 1 contracts:
|
|
36
|
+
- `launch.json`: Request validation for `POST /api/launch` and `crewbus launch`.
|
|
37
|
+
- `harness.json`: Driver definitions, execution capabilities, and model flags.
|
|
38
|
+
- `pairing.json`: Per-device QR pairing URLs (`crewbus://pair?...#secret`) with fragment-only secrets.
|
|
39
|
+
- `board-caps.json`: Capability negotiation (`hlc`, `tombstones`, `channels`, `revoked`, `holds`, `standby`).
|
|
40
|
+
|
|
41
|
+
### 2.3 Shared Client Runtime (`packages/client-runtime/`)
|
|
42
|
+
Both the Web Dashboard (`crewbus web`) and Mobile Shell (`apps/mobile/`) build upon the shared client runtime:
|
|
43
|
+
- **Route Walk & Learned Routes:** Probes advertised relay endpoints, fallback routes, and direct LAN IPs.
|
|
44
|
+
- **Reconnect Supervisor:** Exponential backoff with jitter and health checks (`GET /healthz`).
|
|
45
|
+
- **Offline Mutation Outbox:** Queues actions offline; retries on explicit user action only.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## 3. Message Delivery Protocol & Long Runs
|
|
50
|
+
|
|
51
|
+
### 3.1 Delivery Semantics
|
|
52
|
+
- **Fire-once push, at-least-once reliability:** Harness hooks and background waiters trigger notifications; failed pushes fall back to pull polling.
|
|
53
|
+
- **Ordering:** Causal order tracked via timestamps and parent reply IDs (`--reply <id>`); cross-sender ordering is timestamp-based.
|
|
54
|
+
- **Deduplication:** Maintained via `delivered/<agent>/<msg-id>` marker files.
|
|
55
|
+
|
|
56
|
+
### 3.2 Poll Discipline for Long-Running Tasks
|
|
57
|
+
When workers run unattended long-duration tasks, they follow the poll ladder:
|
|
58
|
+
```sh
|
|
59
|
+
# Long-run poll discipline ladder
|
|
60
|
+
crewbus inbox --from <you> --unacked --digest
|
|
61
|
+
crewbus inbox --grep "<keyword>"
|
|
62
|
+
crewbus inbox --priority high
|
|
63
|
+
crewbus thread <brief-id>
|
|
64
|
+
crewbus gather <brief-id>
|
|
65
|
+
```
|
|
66
|
+
- Workers mark progress with `[checkpoint]` log tags.
|
|
67
|
+
- Asynchronous push notifications wake sleeping workers immediately without polling loops.
|
|
68
|
+
|
|
69
|
+
### 3.3 Session Compaction & Recovery
|
|
70
|
+
Harnesses periodically compact context windows during multi-hour runs. To prevent agents from losing their identity:
|
|
71
|
+
- `crewbus recover [--session <id>]` inspects registered board bindings, token-file hashes, and working directory markers to restore identity without creating duplicate accounts.
|
|
72
|
+
- `respawn` captures session IDs and refreshes process timestamps (`spawnedAt`), ensuring continuity across process restarts.
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## 4. Workbenches, Groups & Channels
|
|
77
|
+
|
|
78
|
+
- **Task-Scoped Groups:** Workforces are partitioned into groups (`crewbus group create <name> --members a,b,c`).
|
|
79
|
+
- **Member-Scoped Channels (`grp-<name>`):** Workers may broadcast to channels corresponding to their group memberships. Orchestrators may broadcast globally.
|
|
80
|
+
- **Artifacts & Compound Memory:** Workers record structured deliverables and dependencies (`crewbus artifact record --name <key> --file <path>`).
|
|
81
|
+
- **Consolidator & Verifier:** Specialized patterns where an observer agent reconciles parallel outputs and verifies criteria before closing a task.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## 5. Storage Engine & Board Layout
|
|
86
|
+
|
|
87
|
+
Boards use standard filesystem hierarchies:
|
|
88
|
+
```
|
|
89
|
+
.crewbus/
|
|
90
|
+
├── board.json # Board schema version and metadata
|
|
91
|
+
├── agents/ # Registered agent records ({role, tokenHash, salt})
|
|
92
|
+
├── mail/ # Immutable direct messages (<id>.json)
|
|
93
|
+
├── delivered/ # Deduplication delivery markers (<agent>/<id>)
|
|
94
|
+
├── cursors/ # Sync cursors per peer
|
|
95
|
+
├── groups/ # Group memberships
|
|
96
|
+
├── channels/ # Channel message streams
|
|
97
|
+
├── artifacts/ # Task deliverables and dependency graphs
|
|
98
|
+
├── locks/ # Named advisory locks with TTL
|
|
99
|
+
└── logs/
|
|
100
|
+
├── chain.jsonl # Hash-chained CLI audit log
|
|
101
|
+
├── audit.jsonl # Hash-chained relay audit log
|
|
102
|
+
└── orchestrator.token # Local orchestrator secret
|
|
103
|
+
```
|
|
104
|
+
Atomic file operations ensure cross-process safety without file locking overhead: writes stream to temporary files and atomically rename into place.
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 6. High Availability & Multi-Node Sync
|
|
109
|
+
|
|
110
|
+
- **Active / Passive Single Writer:** The Primary relay accepts all writes (`POST /api/spawn`, sync push). Standby relays replicate via pull (`--relay-interval 5s`).
|
|
111
|
+
- **Scale-Out Reads:** Standbys serve read-heavy queries (`GET /sync/manifest`, `/sync/file`, `/sync/wait`, `/healthz`) locally.
|
|
112
|
+
- **Failover:** Promoted manually via `crewbus relay promote --from orchestrator` or automatically via `--promote-on-miss <sec>` with split-brain safeguards.
|
|
113
|
+
- **Mesh Transport:** Relay communication is recommended over encrypted peer mesh networks (such as Tailscale) for seamless NAT traversal and authenticated TLS encryption.
|
package/docs/AUDIT_EXPORT.md
CHANGED
|
@@ -1,108 +1,13 @@
|
|
|
1
|
-
# Audit
|
|
1
|
+
# Audit Export & Legal Holds
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
HMAC-signed for independent off-box verification.
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#tamper-evident`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#tamper-evident)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/SECURITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/SECURITY.md)
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
---
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
{
|
|
12
|
-
"v": 1,
|
|
13
|
-
"seq": 4,
|
|
14
|
-
"at": "2026-10-02T23:04:27.106Z",
|
|
15
|
-
"actor": "orchestrator",
|
|
16
|
-
"role": "orchestrator",
|
|
17
|
-
"action": "send",
|
|
18
|
-
"target": "aud1",
|
|
19
|
-
"board": "C:/data/.crewbus",
|
|
20
|
-
"result": "ok",
|
|
21
|
-
"prevHash": "ec0cd4…",
|
|
22
|
-
"sig": "bdb72b…",
|
|
23
|
-
"hash": "2783fe…",
|
|
24
|
-
"authMethod": "token"
|
|
25
|
-
}
|
|
26
|
-
```
|
|
9
|
+
## Tamper-Evident Logging
|
|
27
10
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
| `seq` | 1-based per-stream sequence (`chain` and `audit` number independently) |
|
|
32
|
-
| `at` | ISO-8601 UTC timestamp |
|
|
33
|
-
| `actor` | agent (or `system`/`unknown`) that caused the event |
|
|
34
|
-
| `role` | actor role at write time (`orchestrator`/`worker`/`unknown`) |
|
|
35
|
-
| `action` | stable verb — the existing audit action names (`register`, `role-grant`, `offboard`, `acl-set`, `login`, `token-revoke`, `token-rotate`, `send`, `spawn`, `spawn-kill`, `remote-spawn`, `api-spawn`, `api-kill`, `hold-place`, `hold-lift`, …) |
|
|
36
|
-
| `target` | primary target (`to`/`target`/`agent`, comma-joined, max 200 chars; `""` when none) |
|
|
37
|
-
| `board` | board root path the event was written on |
|
|
38
|
-
| `result` | `ok` / `fail` (from `data.ok` / `data.error`, default `ok`) |
|
|
39
|
-
| `prevHash` | `hash` of the previous record (`GENESIS` for seq 1); duplicates `prev` |
|
|
40
|
-
| `sig` | HMAC-SHA256 over `seq|prev|at|actor|type|canonical(data)`, hex (`""` when no key was configured) |
|
|
41
|
-
| `hash` | keyless SHA256 chain link over the same core (verifiable without any secret) |
|
|
42
|
-
| `authMethod` | how the actor authenticated, best-effort where known: `token` (CLI), `secret` (relay secret), `oidc` (Bearer JWT), `mtls` (client cert, `/sync/*`), else `unknown` |
|
|
43
|
-
|
|
44
|
-
Stored records keep the legacy core fields (`seq, prev, hash, at, actor,
|
|
45
|
-
type, data`) untouched, so old readers keep working; the envelope fields
|
|
46
|
-
are additive.
|
|
47
|
-
|
|
48
|
-
## Signing key
|
|
49
|
-
|
|
50
|
-
`CREWBUS_AUDIT_KEY`, else the board secret (`CREWBUS_SECRET`).
|
|
51
|
-
Use ONE key per board — records signed under different keys (or none)
|
|
52
|
-
fail verification under the current key at the first mismatch.
|
|
53
|
-
|
|
54
|
-
## Verify
|
|
55
|
-
|
|
56
|
-
```sh
|
|
57
|
-
crewbus log --verify [--audit] [--json] [--limit 50]
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
Checks the hash chain, then — when a key is configured — every present
|
|
61
|
-
`sig`. Failures name the position twice: `chain INVALID at seq N
|
|
62
|
-
(first-broken-seq N, bad hash|bad sig|bad seq|broken prev link)`.
|
|
63
|
-
`--json` returns the same fields machine-readably (`ok`, `at`,
|
|
64
|
-
`firstBrokenSeq`, `reason`, `count`).
|
|
65
|
-
|
|
66
|
-
## SIEM forwarder
|
|
67
|
-
|
|
68
|
-
```sh
|
|
69
|
-
crewbus serve --audit-forward <https-url> [--audit-forward-key <bearer>]
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
The relay POSTs each audit event (same v:1 schema, `application/json`;
|
|
73
|
-
`Authorization: Bearer <key>` when configured) off-box:
|
|
74
|
-
|
|
75
|
-
- **Spool first**: every event is written to `audit-spool/` before any
|
|
76
|
-
POST, so a crash never loses an event (at-least-once).
|
|
77
|
-
- **Never blocks**: POSTs are fire-and-forget off the request path; the
|
|
78
|
-
relay answers peers without waiting for the SIEM.
|
|
79
|
-
- **Retry queue**: a 1s loop re-POSTs spooled files oldest-first and
|
|
80
|
-
deletes on 2xx. Duplicates are possible (retry + crash replay) —
|
|
81
|
-
dedupe downstream on `(board, seq, hash)`.
|
|
82
|
-
- **Cross-process tail**: the relay also tails `logs/chain.jsonl` and
|
|
83
|
-
`logs/audit.jsonl`, so CLI-side events (`hold place`, `send`, …)
|
|
84
|
-
written while it runs are forwarded too. Baseline is taken at startup
|
|
85
|
-
(history is not re-posted); pre-existing spool files still drain.
|
|
86
|
-
|
|
87
|
-
Env equivalents: `CREWBUS_AUDIT_FORWARD`,
|
|
88
|
-
`CREWBUS_AUDIT_FORWARD_KEY`.
|
|
89
|
-
|
|
90
|
-
## Legal hold
|
|
91
|
-
|
|
92
|
-
```sh
|
|
93
|
-
crewbus hold place --from orchestrator [--reason "..."]
|
|
94
|
-
crewbus hold lift --from orchestrator
|
|
95
|
-
crewbus hold status [--from <you>] [--json]
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
- `place`/`lift` are orchestrator-only (token-checked + authorized).
|
|
99
|
-
- `status` is a read — any role, including workers, may call it
|
|
100
|
-
(with `--from` it is token-checked; without, it is an operator read).
|
|
101
|
-
- While a hold is active, `prune` (dm/broadcast + logs) is **refused**
|
|
102
|
-
loudly and names the hold:
|
|
103
|
-
`prune REFUSED — legal hold ACTIVE (placed by …) — lift with: …`.
|
|
104
|
-
Tombstone creation/sync mechanics are untouched (the gate fires before
|
|
105
|
-
anything is deleted or tombstoned).
|
|
106
|
-
- The hold record (`holds/legal.json`, HLC-stamped) syncs to peers like
|
|
107
|
-
groups/cursors; every place/lift is audit-logged (`hold-place` /
|
|
108
|
-
`hold-lift`).
|
|
11
|
+
- Every privileged CLI op appends to `logs/chain.jsonl`; relay operations append to `logs/audit.jsonl`.
|
|
12
|
+
- Versioned `v:1` envelopes contain `seq`, `at`, `actor`, `role`, `action`, `target`, `board`, `result`, `prevHash`, `sig`, and `hash`.
|
|
13
|
+
- Off-box verification: `crewbus log --verify` scans from genesis to tip, verifying SHA-256 chain continuity and HMAC-SHA256 signatures.
|
package/docs/CERT_READINESS.md
CHANGED
|
@@ -1,120 +1,13 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
- [done] Default-deny remote spawn/kill: `serve` without
|
|
15
|
-
`--allow-remote-spawn` answers 403; `--allow-cmd` regex constrains remote
|
|
16
|
-
`--cmd`; `--workdir-root` constrains remote cwd.
|
|
17
|
-
- [done] Standby replicas refuse writes: `serve --standby` answers 503 +
|
|
18
|
-
`X-Relay-Role: standby` on `POST /sync/put`, `/api/spawn`, `/api/kill`.
|
|
19
|
-
See `docs/HA.md`.
|
|
20
|
-
- [manual] **Access-review cadence (quarterly stub):** run `agents --json`,
|
|
21
|
-
confirm each identity still needs its role, `offboard` leavers
|
|
22
|
-
(`register --offboard <name> --from orchestrator` preserves inbox for audit),
|
|
23
|
-
record the review date + reviewer. Evidence: the signed `role-grant` /
|
|
24
|
-
`offboard` events in the log.
|
|
25
|
-
|
|
26
|
-
## 2. Authentication
|
|
27
|
-
|
|
28
|
-
- [done] Per-identity tokens: first claim mints (`register --from <you>`
|
|
29
|
-
prints `abt-…` once), afterwards `--token` / `CREWBUS_TOKEN` required;
|
|
30
|
-
only salted hashes stored; `token rotate`, `token status`, `token revoke`
|
|
31
|
-
(revocations sync, never resurrected). Service accounts:
|
|
32
|
-
`register --service <name>`; expiry: `register --expires-in 30/90s/15m/
|
|
33
|
-
24h/7d`.
|
|
34
|
-
- [done] OIDC: `login --issuer <url> --client-id <id> --token <jwt>` binds
|
|
35
|
-
`oidc-<sub>`; relays accept Bearer with
|
|
36
|
-
`serve --oidc-issuer <url> [--oidc-audience <id>]`; `sync`/`listen` send
|
|
37
|
-
it via `--bearer` / `--oidc-token`. See `docs/OIDC_TLS.md`.
|
|
38
|
-
- [done] Relay secret: `--secret` / `CREWBUS_SECRET` via
|
|
39
|
-
`x-crewbus-secret` / `?secret=` (constant-time compare); remote serve
|
|
40
|
-
without one refuses + warns.
|
|
41
|
-
- [manual] **Credential-lifecycle schedule (stub):** rotate service-account
|
|
42
|
-
tokens every N days (`token rotate --from <svc>`), rotate the relay
|
|
43
|
-
secret on staff changes (restart relays), expire IdP clients for leavers.
|
|
44
|
-
Evidence: `token status` output + signed rotation events.
|
|
45
|
-
|
|
46
|
-
## 3. Encryption
|
|
47
|
-
|
|
48
|
-
- [done] In transit: in-box TLS `serve --tls-cert <pem> --tls-key <pem>`;
|
|
49
|
-
mTLS on `/sync/*` with `--tls-ca` / `--mtls-ca`; outbound
|
|
50
|
-
`--mtls-cert`/`--mtls-key`; plain-HTTP-behind-terminator stays supported.
|
|
51
|
-
See `docs/OIDC_TLS.md`.
|
|
52
|
-
- [done] At rest (backups): `board export` encrypts AES-256-GCM
|
|
53
|
-
(32-byte hex/base64 used raw, else scrypt + random salt in the header);
|
|
54
|
-
GCM tag verified *before* any byte is written on `import`; secrets
|
|
55
|
-
stripped unless `--include-secrets` (loud warning).
|
|
56
|
-
- [manual] **Key-rotation schedule (stub):** rotate backup keys yearly (or
|
|
57
|
-
on incident): set the new `CREWBUS_BACKUP_KEY`, take a fresh export,
|
|
58
|
-
verify `board import --into <fresh-dir>` decrypts, retire the old key in
|
|
59
|
-
the vault. Evidence: dated exports + restore-drill log (below).
|
|
60
|
-
|
|
61
|
-
## 4. Audit logging
|
|
62
|
-
|
|
63
|
-
- [done] Hash-chained tamper-evident log (`logs/chain.jsonl` for CLI ops,
|
|
64
|
-
`logs/audit.jsonl` for relay ops); per-event HMAC signatures;
|
|
65
|
-
`log [--audit] [--verify] [--limit 50]` verifies chain + sigs.
|
|
66
|
-
- [done] SIEM export: versioned `v:1` envelope
|
|
67
|
-
(`seq/at/actor/role/action/target/board/result/prevHash/sig`, `sig` =
|
|
68
|
-
64-hex HMAC); `serve --audit-forward <https-url>
|
|
69
|
-
[--audit-forward-key <bearer>]` POSTs off-box with an `audit-spool/`
|
|
70
|
-
at-least-once retry queue that drains (never blocks the relay path).
|
|
71
|
-
See `docs/AUDIT_EXPORT.md`.
|
|
72
|
-
- [done] Legal holds: `hold place --from orchestrator [--reason]` /
|
|
73
|
-
`hold lift` / `hold status`; `prune` (and `import` over a held board)
|
|
74
|
-
refuse while held; hold record syncs to peers.
|
|
75
|
-
- [manual] **Log-review + retention (stub):** forward to your SIEM, alert
|
|
76
|
-
on `audit-spool/` growth (forwarder down), review privileged actions
|
|
77
|
-
(`role-grant`, `offboard`, `hold-*`, `import`, `quota-set`) weekly,
|
|
78
|
-
retain per your policy (`prune --older-than` only when no hold).
|
|
79
|
-
Evidence: SIEM queries + `log --verify` output.
|
|
80
|
-
|
|
81
|
-
## 5. Backup
|
|
82
|
-
|
|
83
|
-
- [done] Portable encrypted backups (`board export --from orchestrator
|
|
84
|
-
--out <file>`), safe restore (`board import --force` semantics + hold
|
|
85
|
-
interaction), declarative schedules (`snapshot schedule --from orchestrator
|
|
86
|
-
--every 24h --keep 7 --out-dir <dir>`), `snapshot run` for cron/systemd/
|
|
87
|
-
Task Scheduler, quotas/tenancy (`quota set/show`, `storage`, separate
|
|
88
|
-
boards per tenant). See `docs/TENANCY.md`.
|
|
89
|
-
- [manual] **Restore-drill runbook (quarterly stub):**
|
|
90
|
-
1. `board export --from orchestrator --out /offsite/drill-<date>.abbackup.json`
|
|
91
|
-
2. `board import --in /offsite/drill-<date>.abbackup.json --into <fresh-dir> --force`
|
|
92
|
-
3. `gather`/inbox spot-checks + `log --verify` on the restored board
|
|
93
|
-
4. Record date, operator, result. Evidence: the drill log + restored-board
|
|
94
|
-
`log --verify` output.
|
|
95
|
-
|
|
96
|
-
## 6. Incident response hooks
|
|
97
|
-
|
|
98
|
-
- [done] Kill switches: `spawn-kill --to <w,…> | --all`, `stop --all
|
|
99
|
-
--from <you>`, remote `/api/kill` (token-checked, RBAC matrix = CLI).
|
|
100
|
-
- [done] Containment: `offboard` (tokens die now, inbox preserved),
|
|
101
|
-
`token revoke`, `hold place` (freeze destructive retention), standby
|
|
102
|
-
promotion path (`relay promote`, `/healthz`; see `docs/HA.md`).
|
|
103
|
-
- [done] Evidence capture: `board export` (encrypted), `log --verify`,
|
|
104
|
-
SIEM stream, `relay status --json` + `/healthz` snapshots.
|
|
105
|
-
- [manual] **IR runbook stub:** detect (SIEM alert / spool growth / anomalous
|
|
106
|
-
`agents --active`), contain (offboard + revoke + hold), preserve
|
|
107
|
-
(export before prune), recover (promote standby / restore import),
|
|
108
|
-
review (access review + key rotation out of cycle). Assign owners and a
|
|
109
|
-
severity scale; rehearse with the restore drill above.
|
|
110
|
-
|
|
111
|
-
## Auditor evidence index (where to look)
|
|
112
|
-
|
|
113
|
-
| Artifact | Produces |
|
|
114
|
-
|---|---|
|
|
115
|
-
| `log --verify` | chain + signature validity (first-broken-seq on tamper) |
|
|
116
|
-
| SIEM receiver | `v:1` envelopes (`role`, `authMethod`, `board`, `sig`) |
|
|
117
|
-
| `holds/legal.json` + `hold status` | hold provenance (placer, reason, time) |
|
|
118
|
-
| `quota show` / `storage --json` | tenant label + limit-vs-actual |
|
|
119
|
-
| `relay status --json` / `/healthz` | HA role, lag, promotion history |
|
|
120
|
-
| `board export` envelope | `{manifest, files[]}` + algo/kdf header |
|
|
1
|
+
# Certification Readiness & Compliance
|
|
2
|
+
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#tamper-evident`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#tamper-evident)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/SECURITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/SECURITY.md)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Compliance & Audit Controls
|
|
10
|
+
|
|
11
|
+
- Documents control mappings for SOC 2 Type II, ISO 27001, and NIST CSF.
|
|
12
|
+
- Audit trail integrity via append-only hash chains.
|
|
13
|
+
- Strict isolation of keys and secrets; credential scrub on worker spawns.
|
package/docs/COMPATIBILITY.md
CHANGED
|
@@ -194,3 +194,68 @@ Verification: `node test/crewbus.approvals-init.mjs` asserts the three
|
|
|
194
194
|
wired harnesses (entries written, re-run byte-identical, user config
|
|
195
195
|
preserved) and that the skipped harnesses gain no approval files. Re-verify
|
|
196
196
|
a row when its vendor changes the allowlist format.
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Scale Limits & Budgets
|
|
202
|
+
|
|
203
|
+
Stated plainly:
|
|
204
|
+
- `crewbus send --to` fans out to up to **10,000 recipients** (a broadcast messaging ceiling).
|
|
205
|
+
- `crewbus spawn` boots one harness process per worker (default max 20 per invocation). Live processes consume CPU/RAM and should be budgeted like compute.
|
|
206
|
+
- `MAX_FWD_DEPTH` is capped at 16 to prevent infinite message bounce loops.
|
|
207
|
+
- Rate limits: standard send rate cap is 60 messages/minute per agent (`--no-rate-limit` to override).
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## Version Skew & Backwards Compatibility
|
|
212
|
+
|
|
213
|
+
Mixed-version fleets are supported with strict backwards compatibility:
|
|
214
|
+
- Relays negotiate capabilities via `packages/contracts/board-caps.json`.
|
|
215
|
+
- Missing or older relay features degrade loudly with human-readable guidance, never obscure 500 crashes.
|
|
216
|
+
- Older agent records without `role` automatically default to `worker`.
|
|
217
|
+
- Plaintext token migration: legacy agent records with plaintext tokens are re-hashed upon successful login and plaintext is deleted.
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## Operational Troubleshooting Matrix
|
|
222
|
+
|
|
223
|
+
Start with `crewbus doctor` — it validates board resolution, working copy path, git revision, and hook/MCP configuration.
|
|
224
|
+
|
|
225
|
+
| Symptom | Probable Cause | Corrective Action |
|
|
226
|
+
|---|---|---|
|
|
227
|
+
| `offline - harness detection failed` | Harness CLI binary is missing from system `PATH` | Run `crewbus harnesses detect`. Install the harness CLI (e.g. `claude`, `opencode`) and verify `PATH`. |
|
|
228
|
+
| `no route worked (Aborted)` | Socket timeout or firewall drop during QR pairing | Mobile shell v0.6.4+ retries automatically; check Wi-Fi / LAN route or use Tailscale. |
|
|
229
|
+
| Split board / different inboxes | Agents resolved different `.crewbus/` directories | Check `[board <path>]` echo in CLI output. Set `CREWBUS_DIR` explicitly. |
|
|
230
|
+
| `wrong token` / auth failure | Token missing or from a different name | Tokens print once at mint. Reuse the saved token or run `crewbus token rotate --from <name>`. |
|
|
231
|
+
| Post-compaction identity loss | Harness context summary wiped session memory | Run `crewbus recover [--session <id>]`. Never register temporary names like `unknown` or `me`. |
|
|
232
|
+
| PowerShell comma list splatting | PowerShell splats unquoted `,` into arguments | Quote comma lists in PowerShell: `--add "w1,w2"` or `--to "w1,w2"`. |
|
|
233
|
+
| Drive root refusal (`C:\.crewbus`) | Detached process ran without parent directory | Set `CREWBUS_DIR` explicitly or run `crewbus init` in the repo root. |
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## When NOT to Use crewbus
|
|
238
|
+
|
|
239
|
+
crewbus is optimized for local-first, mixed-harness multi-agent collaboration. Do NOT use crewbus when:
|
|
240
|
+
- **Parent-to-subagent hierarchy in a single harness:** Native subagents (e.g., Claude Code subagents) are simpler when helpers do not need peer messaging or outliving parent sessions.
|
|
241
|
+
- **Thousands of concurrent live processes:** Spawning boots actual OS processes per worker. Use distributed runners (Kubernetes, Slurm) for massive concurrency.
|
|
242
|
+
- **Strict transactional total ordering:** Delivery is fire-once per push path with at-least-once retry; cross-agent ordering uses timestamps rather than strict total consensus.
|
|
243
|
+
- **Untrusted code execution on a shared board:** Board files are unsegmented on the local disk. Use container sandboxes with separate `CREWBUS_DIR` roots for untrusted tasks.
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## Quickstart
|
|
248
|
+
|
|
249
|
+
```sh
|
|
250
|
+
# 1. Initialize crewbus in your repository
|
|
251
|
+
crewbus init --harness claude
|
|
252
|
+
|
|
253
|
+
# 2. Check wiring health
|
|
254
|
+
crewbus doctor
|
|
255
|
+
|
|
256
|
+
# 3. Launch a live agent crew
|
|
257
|
+
crewbus launch --from orchestrator --harness claude --body "Review test coverage and suggest improvements"
|
|
258
|
+
|
|
259
|
+
# 4. Open the interactive Web Dashboard & QR Pairing Studio
|
|
260
|
+
crewbus web --open
|
|
261
|
+
```
|