crewbus 10.0.11 → 11.3.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/AGENTS.template.md +4 -4
- package/CHANGELOG.md +151 -0
- package/README.md +713 -706
- package/TEAM.template.md +1 -1
- package/bin/crewbus-hook.js +22 -5
- package/bin/crewbus-mcp.js +56 -48
- package/bin/crewbus.js +486 -355
- package/bin/lib/channels.js +1 -1
- package/bin/lib/export.js +1 -1
- package/bin/lib/groups.js +1 -5
- package/bin/lib/identity.js +92 -152
- package/bin/lib/launch.js +128 -30
- package/bin/lib/qrcode.js +2971 -0
- package/bin/lib/relay.js +26 -54
- package/bin/lib/spawn.js +241 -194
- package/bin/lib/store.js +2 -2
- package/bin/lib/web.js +277 -59
- package/claude-plugin/skills/crewbus/SKILL.md +1 -1
- package/docs/APPROVALS.md +8 -8
- package/docs/AUDIT_EXPORT.md +7 -7
- package/docs/CERT_READINESS.md +120 -120
- package/docs/COMPATIBILITY.md +196 -194
- package/docs/CONSOLIDATOR.md +6 -6
- package/docs/CONTROL_PLANE_SPEC.md +12 -14
- package/docs/CREWS.md +16 -13
- package/docs/DELIVERY.md +213 -210
- package/docs/GROUPS.md +8 -8
- package/docs/HA.md +151 -151
- package/docs/IDENTITY.md +6 -6
- package/docs/LEAD_ASSIGN.md +3 -85
- package/docs/LONG_RUNS.md +3 -3
- package/docs/M1_CLI_DRAFT.md +9 -9
- package/docs/ORCHESTRATOR.md +87 -0
- package/docs/PAIRING.md +7 -7
- package/docs/QUICKSTART.md +24 -13
- package/docs/RBAC.md +84 -73
- package/docs/SPLIT.md +82 -82
- package/docs/TENANCY.md +10 -10
- package/docs/THREAT_MODEL.md +68 -69
- package/docs/VERIFIER.md +10 -10
- package/docs/VERSION_SKEW.md +57 -57
- package/documentation.html +37 -29
- package/examples/hermes-pairing.md +3 -3
- package/examples/t3-pairing.md +1 -1
- package/index.html +13 -14
- package/opencode/plugins/dm-watch.js +1 -1
- package/opencode/tools/dm-send.js +4 -13
- package/package.json +75 -50
- package/packages/client-runtime/README.md +40 -40
- package/packages/contracts/harness.json +108 -111
- package/packages/contracts/launch.json +2 -3
- package/packages/contracts/pairing.json +3 -3
- package/docs/DESKTOP_SPIKE.md +0 -223
package/docs/AUDIT_EXPORT.md
CHANGED
|
@@ -12,8 +12,8 @@ HMAC-signed for independent off-box verification.
|
|
|
12
12
|
"v": 1,
|
|
13
13
|
"seq": 4,
|
|
14
14
|
"at": "2026-10-02T23:04:27.106Z",
|
|
15
|
-
"actor": "
|
|
16
|
-
"role": "
|
|
15
|
+
"actor": "orchestrator",
|
|
16
|
+
"role": "orchestrator",
|
|
17
17
|
"action": "send",
|
|
18
18
|
"target": "aud1",
|
|
19
19
|
"board": "C:/data/.crewbus",
|
|
@@ -31,7 +31,7 @@ HMAC-signed for independent off-box verification.
|
|
|
31
31
|
| `seq` | 1-based per-stream sequence (`chain` and `audit` number independently) |
|
|
32
32
|
| `at` | ISO-8601 UTC timestamp |
|
|
33
33
|
| `actor` | agent (or `system`/`unknown`) that caused the event |
|
|
34
|
-
| `role` | actor role at write time (`
|
|
34
|
+
| `role` | actor role at write time (`orchestrator`/`worker`/`unknown`) |
|
|
35
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
36
|
| `target` | primary target (`to`/`target`/`agent`, comma-joined, max 200 chars; `""` when none) |
|
|
37
37
|
| `board` | board root path the event was written on |
|
|
@@ -90,13 +90,13 @@ Env equivalents: `CREWBUS_AUDIT_FORWARD`,
|
|
|
90
90
|
## Legal hold
|
|
91
91
|
|
|
92
92
|
```sh
|
|
93
|
-
crewbus hold place --from
|
|
94
|
-
crewbus hold lift --from
|
|
93
|
+
crewbus hold place --from orchestrator [--reason "..."]
|
|
94
|
+
crewbus hold lift --from orchestrator
|
|
95
95
|
crewbus hold status [--from <you>] [--json]
|
|
96
96
|
```
|
|
97
97
|
|
|
98
|
-
- `place`/`lift` are
|
|
99
|
-
- `status` is a read — any role, including
|
|
98
|
+
- `place`/`lift` are orchestrator-only (token-checked + authorized).
|
|
99
|
+
- `status` is a read — any role, including workers, may call it
|
|
100
100
|
(with `--from` it is token-checked; without, it is an operator read).
|
|
101
101
|
- While a hold is active, `prune` (dm/broadcast + logs) is **refused**
|
|
102
102
|
loudly and names the hold:
|
package/docs/CERT_READINESS.md
CHANGED
|
@@ -1,120 +1,120 @@
|
|
|
1
|
-
# Cert-readiness checklist
|
|
2
|
-
|
|
3
|
-
Control-by-control mapping of common audit expectations to what the product
|
|
4
|
-
implements (with exact commands/flags) and what remains a customer runbook
|
|
5
|
-
item. Statuses: **done** (in the tree, covered by `npm test`), **manual**
|
|
6
|
-
(stub runbook below — your cadence, your evidence).
|
|
7
|
-
|
|
8
|
-
## 1. Access control (RBAC)
|
|
9
|
-
|
|
10
|
-
- [done] Roles + authorization gates: `agents`, `role-grant`, privileged
|
|
11
|
-
ops gated by `authorize()` (`prune`, `acl-set`, `role-grant`, `offboard`,
|
|
12
|
-
`group-restrict`, `serve-remote`, `import`, `snapshot-schedule`,
|
|
13
|
-
`quota-set`, `hold-place`, `hold-lift`). See `docs/RBAC.md`.
|
|
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
|
|
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
|
|
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
|
|
84
|
-
--out <file>`), safe restore (`board import --force` semantics + hold
|
|
85
|
-
interaction), declarative schedules (`snapshot schedule --from
|
|
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
|
|
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
|
+
# Cert-readiness checklist
|
|
2
|
+
|
|
3
|
+
Control-by-control mapping of common audit expectations to what the product
|
|
4
|
+
implements (with exact commands/flags) and what remains a customer runbook
|
|
5
|
+
item. Statuses: **done** (in the tree, covered by `npm test`), **manual**
|
|
6
|
+
(stub runbook below — your cadence, your evidence).
|
|
7
|
+
|
|
8
|
+
## 1. Access control (RBAC)
|
|
9
|
+
|
|
10
|
+
- [done] Roles + authorization gates: `agents`, `role-grant`, privileged
|
|
11
|
+
ops gated by `authorize()` (`prune`, `acl-set`, `role-grant`, `offboard`,
|
|
12
|
+
`group-restrict`, `serve-remote`, `import`, `snapshot-schedule`,
|
|
13
|
+
`quota-set`, `hold-place`, `hold-lift`). See `docs/RBAC.md`.
|
|
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 |
|