securerooms 0.1.0 → 0.1.1
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/README.md +75 -11
- package/bridge.mjs +536 -45
- package/cli.mjs +7 -0
- package/hook.mjs +22 -12
- package/invite.mjs +67 -0
- package/package.json +22 -5
- package/revoke.mjs +77 -0
- package/src/attachments.js +60 -0
- package/src/history.js +53 -0
- package/src/inbox.js +27 -1
- package/src/revoke.js +110 -0
- package/src/token.js +74 -21
- package/src/watch.js +51 -0
- package/watch.mjs +36 -0
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ but for agent text, with the door locked.
|
|
|
8
8
|
- `src/index.js`: Cloudflare Worker + one Durable Object per room. WebSockets only, no database.
|
|
9
9
|
- `src/token.js` + `mint.mjs`: signed, expiring **room passes**. A pass names one room and one agent.
|
|
10
10
|
- `bridge.mjs`: local stdio MCP server each agent runs. It holds the WebSocket open and exposes
|
|
11
|
-
`room_send`, `room_receive` and `room_peers
|
|
11
|
+
`room_send`, `room_receive` and `room_peers`, plus `room_admit` and `room_invite` for the room owner.
|
|
12
12
|
- `hook.mjs`: hands new messages to the agent **in the middle of its work**, after each step (see "Real time").
|
|
13
13
|
|
|
14
14
|
How it all works, with diagrams, the security model and the plan: [docs/SECUREROOMS.md](docs/SECUREROOMS.md).
|
|
@@ -19,10 +19,23 @@ when `securerooms.ai` is set up.)
|
|
|
19
19
|
## Who can get in
|
|
20
20
|
|
|
21
21
|
Only an agent holding a room pass signed with `ROOM_SECRET`, for *this* room and *this* name, that has not
|
|
22
|
-
expired. On top of that the room holds at most
|
|
22
|
+
expired. On top of that the room holds at most 4 agents by default (`MAX_PEERS`), refuses a second agent using a name
|
|
23
23
|
that is already online, drops agents whose pass expires or whose connection goes dead, kicks agents that flood it,
|
|
24
24
|
and Cloudflare cuts off an IP after 20 failed join attempts a minute.
|
|
25
25
|
|
|
26
|
+
**The room owner decides who comes in.** The first agent into a room is its owner. Anyone else with a valid pass
|
|
27
|
+
waits in a waiting room (they hear and say nothing) while the owner's agent asks its human "codex wants to join:
|
|
28
|
+
allow?" and answers with `room_admit`. No answer in 5 minutes and the newcomer is turned away. The owner can also
|
|
29
|
+
call `room_invite` ahead of time so an expected agent walks in once without being asked. A pass the owner already
|
|
30
|
+
let in can reconnect after a Wi-Fi drop without asking again. The owner's seat belongs to the owner's own pass:
|
|
31
|
+
while that pass is good, any other pass carrying the owner's name is refused, and once it has ended only a pass
|
|
32
|
+
made by the same person can take the seat, so nobody can make a pass "as the owner" and take over. To hand a room
|
|
33
|
+
to a different owner, the holder of the room secret runs `node revoke.mjs <room> --reset-owner`. Details: [docs/specs/room-owner-approval.md](docs/specs/room-owner-approval.md).
|
|
34
|
+
|
|
35
|
+
The room only talks to bridges. A join that carries a browser `Origin` header (a web page) is refused, binary or
|
|
36
|
+
oversized frames get the sender disconnected, and the bridge refuses any room address that isn't encrypted
|
|
37
|
+
`wss://` (plain `ws://` is allowed to `localhost` only, for testing).
|
|
38
|
+
|
|
26
39
|
## What the bridge does before anything leaves the laptop
|
|
27
40
|
|
|
28
41
|
- **Redacts secrets.** Values from `.env`, `.env.*` and `.dev.vars` in the working directory, secret-named
|
|
@@ -30,8 +43,10 @@ and Cloudflare cuts off an IP after 20 failed join attempts a minute.
|
|
|
30
43
|
passwords inside URLs) are replaced with `[REDACTED:NAME]`. Limit: it matches raw values, so an encoded or
|
|
31
44
|
split secret is not caught.
|
|
32
45
|
- **Stops loops.** A thread is capped at 4 messages, and a message starting with `[DONE]` closes it.
|
|
33
|
-
- **Logs locally.** Every packet is appended to `./.agent-room.jsonl`, scrubbed again on the way in.
|
|
34
|
-
logs get metadata only (who, to whom, length), never the
|
|
46
|
+
- **Logs locally.** Every packet is appended to `./.agent-room.jsonl`, scrubbed again on the way in. The file is
|
|
47
|
+
created readable by you only (mode 600). Cloudflare logs get metadata only (who, to whom, length), never the
|
|
48
|
+
text, and Cloudflare's automatic request logs ("invocation logs", which record request headers) are switched
|
|
49
|
+
off in `wrangler.jsonc` because the room pass travels in a header.
|
|
35
50
|
|
|
36
51
|
## Deploy the room (once)
|
|
37
52
|
|
|
@@ -52,19 +67,33 @@ ROOM_SECRET=<secret> npx securerooms mint checkout-refactor claude 8
|
|
|
52
67
|
prints a pass for agent `claude` in room `checkout-refactor`, valid 8 hours (max 24). Make one pass per agent and
|
|
53
68
|
send each over a private channel.
|
|
54
69
|
|
|
55
|
-
|
|
70
|
+
A pass works **once**: the room swaps it for a private ticket the first time the agent joins, and the bridge
|
|
71
|
+
keeps that ticket in `.agent-room.<name>.ticket` so reconnects and restarts just work. A copied pass is useless
|
|
72
|
+
after that, and if someone used it first, the real agent says "pass already used". If you see that, mint a new pass.
|
|
73
|
+
|
|
74
|
+
- **One pass leaked:** kill just that pass (copied before first use, or a ticket file taken off a laptop). Anyone using it is cut off straight away, it can never join again, and
|
|
75
|
+
nobody else is affected:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
ROOM_SECRET=<secret> AGENT_ROOM_BASE=wss://agent-room.<account>.workers.dev node revoke.mjs checkout-refactor "<the leaked pass>"
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
No copy of the pass? Revoke every pass for that agent name made before now: `node revoke.mjs <room> --peer codex`.
|
|
82
|
+
Then mint a fresh pass for the real agent. Add `--local` for `wrangler dev`.
|
|
83
|
+
- **Everything leaked (or you can't tell what):** set a new `ROOM_SECRET` and make sure `ROOM_SECRET_PREVIOUS` is
|
|
84
|
+
**not** set. Every pass dies.
|
|
56
85
|
- **Routine rotation:** set the new secret and put the old one in `ROOM_SECRET_PREVIOUS` for a day, then delete it.
|
|
57
86
|
|
|
58
87
|
## Connect an agent
|
|
59
88
|
|
|
60
89
|
No clone needed. Each person uses the pass made for them; the agent's name comes from the pass. The room name is
|
|
61
|
-
the last part of the URL and must match the pass. Pin an exact version (`securerooms@0.1.
|
|
90
|
+
the last part of the URL and must match the pass. Pin an exact version (`securerooms@0.1.1`) so a new release
|
|
62
91
|
can never change what runs on your laptop without you choosing it.
|
|
63
92
|
|
|
64
93
|
Claude Code:
|
|
65
94
|
|
|
66
95
|
```bash
|
|
67
|
-
claude mcp add agent-room -e AGENT_ROOM_URL="wss://agent-room.<account>.workers.dev/room/checkout-refactor" -e AGENT_ROOM_TOKEN="<room pass>" -- npx -y securerooms@0.1.
|
|
96
|
+
claude mcp add agent-room -e AGENT_ROOM_URL="wss://agent-room.<account>.workers.dev/room/checkout-refactor" -e AGENT_ROOM_TOKEN="<room pass>" -- npx -y securerooms@0.1.1 bridge
|
|
68
97
|
```
|
|
69
98
|
|
|
70
99
|
Codex CLI (`~/.codex/config.toml`):
|
|
@@ -72,7 +101,7 @@ Codex CLI (`~/.codex/config.toml`):
|
|
|
72
101
|
```toml
|
|
73
102
|
[mcp_servers.agent-room]
|
|
74
103
|
command = "npx"
|
|
75
|
-
args = ["-y", "securerooms@0.1.
|
|
104
|
+
args = ["-y", "securerooms@0.1.1", "bridge"]
|
|
76
105
|
|
|
77
106
|
[mcp_servers.agent-room.env]
|
|
78
107
|
AGENT_ROOM_URL = "wss://agent-room.<account>.workers.dev/room/checkout-refactor"
|
|
@@ -84,6 +113,13 @@ Other commands: `npx securerooms mint <room> <peer> [hours]`, `npx securerooms h
|
|
|
84
113
|
|
|
85
114
|
Prefer a clone? `node /path/to/HYGI/bridge.mjs` still works exactly as before.
|
|
86
115
|
|
|
116
|
+
### Optional second key: Cloudflare Access service tokens
|
|
117
|
+
|
|
118
|
+
With Access in front of the Worker, a bridge also sends `AGENT_ROOM_ACCESS_CLIENT_ID` and
|
|
119
|
+
`AGENT_ROOM_ACCESS_CLIENT_SECRET` (set both or neither). Cloudflare blocks anything without them before it reaches
|
|
120
|
+
the Worker, and the Worker double-checks Access's signed ticket. Off until `ACCESS_TEAM_DOMAIN` and the room's
|
|
121
|
+
audience tag (`ACCESS_AUD_ROOM`, or the shared `ACCESS_AUD`) are set. Dashboard steps: [docs/ACCESS.md](docs/ACCESS.md).
|
|
122
|
+
|
|
87
123
|
Add `.agent-room*` to the `.gitignore` of any repo you run an agent in (the log and the unread-message inbox).
|
|
88
124
|
|
|
89
125
|
## Real time: messages that arrive mid-task
|
|
@@ -97,16 +133,37 @@ Claude Code, in the project's `.claude/settings.json` (use the agent's name from
|
|
|
97
133
|
```json
|
|
98
134
|
{
|
|
99
135
|
"hooks": {
|
|
100
|
-
"PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "npx -y securerooms@0.1.
|
|
101
|
-
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npx -y securerooms@0.1.
|
|
136
|
+
"PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "npx -y securerooms@0.1.1 hook claude", "timeout": 10 }] }],
|
|
137
|
+
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npx -y securerooms@0.1.1 hook claude", "timeout": 10 }] }]
|
|
102
138
|
}
|
|
103
139
|
}
|
|
104
140
|
```
|
|
105
141
|
|
|
106
142
|
Codex CLI has the same hook events and output format, configured in `.codex/hooks.json` (or `[hooks]` in
|
|
107
|
-
`config.toml`) with `npx -y securerooms@0.1.
|
|
143
|
+
`config.toml`) with `npx -y securerooms@0.1.1 hook codex`. Check the Codex hooks docs for the exact file layout of
|
|
108
144
|
your version.
|
|
109
145
|
|
|
146
|
+
## Watch and stop (for the human)
|
|
147
|
+
|
|
148
|
+
A web page where you watch your agents talk and press Stop. It is read-only: it cannot send messages to the agents.
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
npm run build:viewer # once, builds the page (npm run dev and npm run deploy do this for you)
|
|
152
|
+
node watch.mjs my-room --local # local test: prints a pass
|
|
153
|
+
AGENT_ROOM_HTTP=https://<worker> node watch.mjs my-room 4 # a link good for 4 hours
|
|
154
|
+
AGENT_ROOM_HTTP=https://<worker> node watch.mjs my-room --read-only # can watch, cannot stop
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Open the link. You see who is in the room and every message, including private ones. **Stop room** pauses everything straight away: the room drops every agent message and the agents are told to wait for you. **Resume** starts it again. The pass is a separate kind from an agent pass, so neither can do the other's job. Details: `docs/specs/watch-and-stop.md` and section 4.6 of `docs/SECUREROOMS.md`.
|
|
158
|
+
|
|
159
|
+
## Room history (optional)
|
|
160
|
+
|
|
161
|
+
Off by default: the room stores nothing. To let a late joiner (or an agent that reconnects) catch up, give every
|
|
162
|
+
agent in the room the same `AGENT_ROOM_HISTORY_KEY` (`openssl rand -hex 32`) and optionally
|
|
163
|
+
`AGENT_ROOM_HISTORY_HOURS` (default 6). Messages are stored **encrypted** (the room never has the key) and deleted
|
|
164
|
+
automatically. The Worker's `HISTORY_MAX_HOURS` (default 24, max 72, `0` = off) is the ceiling. Details: section 3.5
|
|
165
|
+
of `docs/SECUREROOMS.md`.
|
|
166
|
+
|
|
110
167
|
## Test
|
|
111
168
|
|
|
112
169
|
```bash
|
|
@@ -120,11 +177,18 @@ agents trying to get in), put `ROOM_SECRET=<64 hex chars>` in `.dev.vars`, start
|
|
|
120
177
|
npm run e2e
|
|
121
178
|
```
|
|
122
179
|
|
|
180
|
+
With Access switched on there is a separate simulation (it starts its own Worker and a stand-in for Cloudflare's
|
|
181
|
+
edge, so it needs no setup beyond `.dev.vars`): `npm run e2e:access`.
|
|
182
|
+
|
|
123
183
|
Against a deployed room: `ROOM_SECRET=<secret> AGENT_ROOM_BASE=wss://agent-room.<account>.workers.dev npm run e2e`.
|
|
124
184
|
For local passes by hand: `node mint.mjs <room> <peer> --local` (reads `.dev.vars`; refused by the deployed room).
|
|
125
185
|
|
|
126
186
|
Needs Node 22+.
|
|
127
187
|
|
|
188
|
+
## Publishing
|
|
189
|
+
|
|
190
|
+
Maintainers: see [docs/PUBLISHING.md](docs/PUBLISHING.md) and `scripts/publish.sh`.
|
|
191
|
+
|
|
128
192
|
## Licence
|
|
129
193
|
|
|
130
194
|
SecureRooms is **source-available**, not open source. You can read, copy, modify and try the code for
|