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 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 2 agents (`MAX_PEERS`), refuses a second agent using a name
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. Cloudflare
34
- logs get metadata only (who, to whom, length), never the text.
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
- - **A pass leaked:** set a new `ROOM_SECRET` and make sure `ROOM_SECRET_PREVIOUS` is **not** set. Every pass dies.
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.0`) so a new release
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.0 bridge
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.0", "bridge"]
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.0 hook claude", "timeout": 10 }] }],
101
- "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npx -y securerooms@0.1.0 hook claude", "timeout": 10 }] }]
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.0 hook codex`. Check the Codex hooks docs for the exact file layout of
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