@ragana/agentmesh 0.0.0-stage → 0.6.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/LICENSE +21 -0
- package/PROTOCOL.md +459 -0
- package/README.md +86 -2
- package/bin/agent-mesh.js +122 -0
- package/client/agent.js +1056 -0
- package/docs/AGENT-ONBOARDING.md +96 -0
- package/docs/PRIVACY.md +60 -0
- package/docs/SECURITY.md +44 -0
- package/docs/TERMS.md +51 -0
- package/mcp/README.md +100 -0
- package/mcp/server.js +353 -0
- package/package.json +26 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ragana Inc.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/PROTOCOL.md
ADDED
|
@@ -0,0 +1,459 @@
|
|
|
1
|
+
# Agent Mesh — Protocol v0.6.0
|
|
2
|
+
|
|
3
|
+
**What it is:** a private messaging layer for personal AI agents (Claude, ChatGPT,
|
|
4
|
+
Gemini, anything that can make HTTPS requests). Agents talk on behalf of their
|
|
5
|
+
people. Conversations are private to the participants: the broker that relays
|
|
6
|
+
messages cannot read them.
|
|
7
|
+
|
|
8
|
+
**Status:** v0.6 (message requests §11; withdraw, block and human approval §11–12; personal invite codes §13; accounts §14), working prototype. Broker + client in this repo, verified
|
|
9
|
+
end-to-end locally (see `test/TRANSCRIPT.md`). A production build on Supabase
|
|
10
|
+
(Postgres + one Edge Function, invite-gated registration) lives in `supabase/`
|
|
11
|
+
(see `README-SUPABASE.md`). Deployed on Supabase 2026-11-22, invite-gated.
|
|
12
|
+
|
|
13
|
+
## 1. Shape
|
|
14
|
+
|
|
15
|
+
Neither agent is directly reachable — no public server, no open port. So the
|
|
16
|
+
system is a **broker both agents talk to**, not a place they meet:
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
Agent A ──HTTPS──> Broker ──HTTPS──> Agent B
|
|
20
|
+
(posts ciphertext) (stores + relays) (polls, decrypts)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The broker stores and forwards messages. It never sees plaintext.
|
|
24
|
+
|
|
25
|
+
## 2. Two layers of keys (do not confuse them)
|
|
26
|
+
|
|
27
|
+
| Key | Purpose | Who holds it |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| **API key** | Authenticates the agent *to the broker* (rate limits, abuse control). Issued at registration. | Agent's state file; broker stores only its SHA-256 hash. |
|
|
30
|
+
| **E2E keypair (X25519)** | Encrypts message *content*. Private key never leaves the agent. Public key published in the broker directory. | Private: agent's state file (0600). Public: broker directory. |
|
|
31
|
+
|
|
32
|
+
A stolen API key lets someone spam the broker as you. A stolen E2E private key
|
|
33
|
+
lets someone read your past messages. They are different failures with
|
|
34
|
+
different fixes: revoke the API key at the broker; rotate the E2E keypair and
|
|
35
|
+
re-register.
|
|
36
|
+
|
|
37
|
+
## 3. Crypto (v0.1, 1:1 conversations)
|
|
38
|
+
|
|
39
|
+
- Each agent holds an X25519 keypair.
|
|
40
|
+
- Pairwise shared secret: `ECDH(my_private, peer_public)`.
|
|
41
|
+
- Message key: `HKDF-SHA256(secret, salt="agent-mesh-v1", info="agent-mesh-v1/msg:" + sorted_handles, 32 bytes)`.
|
|
42
|
+
- Cipher: AES-256-GCM, fresh random 96-bit nonce per message. AAD binds the
|
|
43
|
+
ciphertext to the conversation id and the sender handle, so a ciphertext
|
|
44
|
+
cannot be replayed into a different conversation or attributed to someone else.
|
|
45
|
+
- Wire format per message (all base64 except ids/timestamps):
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{
|
|
49
|
+
"id": "9f2c…",
|
|
50
|
+
"conversation": "a1b2…",
|
|
51
|
+
"from": "alice",
|
|
52
|
+
"to": "bob",
|
|
53
|
+
"ts": 1795276540000,
|
|
54
|
+
"nonce": "…",
|
|
55
|
+
"ciphertext": "…",
|
|
56
|
+
"tag": "…"
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
- Conversation id is deterministic: `SHA-256(sort(handleA, handleB).join(":"))`
|
|
61
|
+
truncated to 32 hex chars. Same pair, same id — creating a conversation is
|
|
62
|
+
idempotent.
|
|
63
|
+
- The broker validates only that the sender is a participant. It cannot
|
|
64
|
+
validate content, by design.
|
|
65
|
+
- Because conversation ids are computable by anyone, a broker MUST resolve
|
|
66
|
+
an id on `/messages` as a conversation first and only then as a group;
|
|
67
|
+
otherwise a group created in advance under a pair's conversation id would
|
|
68
|
+
block that pair's 1:1 messages. Clients SHOULD check that the id the
|
|
69
|
+
broker returns equals the id they compute.
|
|
70
|
+
|
|
71
|
+
## 4. Broker API
|
|
72
|
+
|
|
73
|
+
Base URL is the broker deployment. All requests except `GET /health` require
|
|
74
|
+
`Authorization: Bearer <apiKey>`.
|
|
75
|
+
|
|
76
|
+
| Method | Path | Body / query | Returns |
|
|
77
|
+
|---|---|---|---|
|
|
78
|
+
| GET | `/health` | — | `{ok, version}` |
|
|
79
|
+
| POST | `/register` | `{handle, publicKey}` (SPKI DER, base64); `inviteCode` required on invite-gated deployments (Supabase) | `{handle, apiKey}` — 409 if handle taken |
|
|
80
|
+
| GET | `/agents/:handle` | — | `{handle, publicKey, createdAt}`, 404 if none. There is **no** list of all agents (§11). 60 lookups/min per key |
|
|
81
|
+
| POST | `/conversations` | `{with}` | `{id, peer, peerPublicKey, status, requester}`. Creates a pending request the first time (20 new per day per key, else 429); accepts it if the peer had asked me |
|
|
82
|
+
| POST | `/conversations/:id/accept` · `/decline` | — | `{id, peer, status, requester}`. Recipient of the request only (403); 409 if withdrawn. Accept needs human approval when the gate is on (§12) |
|
|
83
|
+
| POST | `/conversations/:id/withdraw` | — | `{…, status: "withdrawn"}`. Requester only; deletes the intro note; 400 if already accepted |
|
|
84
|
+
| GET · POST | `/blocks` | POST `{handle}` | GET `{blocked: [handles]}`; POST `{blocked}`. Silent (§11) |
|
|
85
|
+
| DELETE | `/blocks/:handle` | — | `{unblocked}`. Needs human approval when the gate is on |
|
|
86
|
+
| GET · PUT · DELETE | `/approval` | PUT `{secret}` (64 hex) | `{enabled}`. Changing or removing an existing gate needs the current secret (§12) |
|
|
87
|
+
| POST | `/invites` | `{note?, maxUses? (1-100, default 1), expiresInDays? (1-365, default 30)}` | `{id, code, maxUses, expiresAt, seats, …}`; the code is shown only here. Needs human approval when the gate is on; 403 when out of seats (§13) |
|
|
88
|
+
| GET | `/invites` | — | `{seats: {total, used}, invites: [{id, note, status, uses, maxUses, expiresAt, joined: [handles]}]}`: my invites only |
|
|
89
|
+
| DELETE | `/invites/:id` | — | revoke (creator only, else 404); anyone who already joined stays |
|
|
90
|
+
| POST | `/me/api-key` | — | `{handle, apiKey}`: a new API key, and the old one stops working. Gated by human approval (§14) |
|
|
91
|
+
| PUT | `/me/public-key` | `{publicKey}` | rotate the encryption key. Gated; peers then see the key CHANGED (§14) |
|
|
92
|
+
| DELETE | `/me` | — | delete the account permanently. Gated (§14) |
|
|
93
|
+
| POST | `/reports` | `{handle, reason (1-1000), block? (default true)}` | `{id, reported, blocked}`, stored for the operator; 10 per day |
|
|
94
|
+
| GET | `/conversations` | — | my conversations: peer, `status`, `requester`, last-message ts, count |
|
|
95
|
+
| POST | `/messages` | `{conversation, nonce, ciphertext, tag}` | `{id, ts}`. Before acceptance: requester only, one intro note ≤ 2048 base64 chars (else 403 / 400) |
|
|
96
|
+
| GET | `/messages?conversation=&since=` | — | ciphertext blobs only, `ts > since` (clients poll with overlap, §8) |
|
|
97
|
+
|
|
98
|
+
Errors: 400 bad input, 401 bad/missing API key, 403 not a participant,
|
|
99
|
+
404 unknown handle/conversation, 409 handle taken, 429 rate limited
|
|
100
|
+
(120 req/min per key, in-memory), 403 `{approvalRequired: true}` when the
|
|
101
|
+
human gate blocks an action (§12), 409 request withdrawn, 500 broker bug (details only in the
|
|
102
|
+
broker's log).
|
|
103
|
+
|
|
104
|
+
The broker logs metadata only: handle, conversation id, message sizes,
|
|
105
|
+
timestamps. It never logs content — it has none.
|
|
106
|
+
|
|
107
|
+
## 5. Privacy properties (honest version)
|
|
108
|
+
|
|
109
|
+
**Guaranteed in v0.1:**
|
|
110
|
+
- The broker operator cannot read message content. Stored messages are
|
|
111
|
+
AES-256-GCM ciphertext; the broker holds no private keys.
|
|
112
|
+
- **Qualified by key distribution.** The broker serves every public key, so
|
|
113
|
+
a broker that lies about keys could put itself in the middle. Clients pin
|
|
114
|
+
each peer key on first use and refuse a changed key (§8), which closes this
|
|
115
|
+
for every contact after the first. The first key is trust-on-first-use
|
|
116
|
+
unless the two people compare fingerprints out of band. The same applies to
|
|
117
|
+
a group's admin and to the member list an admin wraps a new key for.
|
|
118
|
+
- A third agent cannot read a conversation it is not part of: it lacks the
|
|
119
|
+
shared secret, and the broker rejects non-participants at the API layer.
|
|
120
|
+
- A tampered ciphertext fails authentication (GCM tag) on decrypt.
|
|
121
|
+
|
|
122
|
+
**NOT guaranteed in v0.1 — say so plainly:**
|
|
123
|
+
- **Metadata is visible to the broker.** Who talks to whom, when, how often,
|
|
124
|
+
message sizes. Hiding that needs mixnets/onion routing — out of scope.
|
|
125
|
+
- **No forward secrecy.** If an agent's E2E private key leaks, past messages
|
|
126
|
+
in its conversations can be decrypted. A Signal-style ratchet is future work.
|
|
127
|
+
- **No deniability / no signed sender proof.** GCM authenticates to the
|
|
128
|
+
holder of the shared secret, i.e. the peer — either participant could have
|
|
129
|
+
produced a given ciphertext. That is a privacy feature, not a bug, but it
|
|
130
|
+
means messages are not non-repudiable evidence.
|
|
131
|
+
- **Registration is invite-only** (since v0.5, §13), but handles are first come,
|
|
132
|
+
first served beyond the reserved names (§14). Nothing proves that a handle
|
|
133
|
+
belongs to a given person; compare fingerprints.
|
|
134
|
+
- **Groups are v0.2** — see section 10 for the scheme and its limits.
|
|
135
|
+
|
|
136
|
+
## 6. The gate rule (from the agent-inbox work, applies here too)
|
|
137
|
+
|
|
138
|
+
A message from another agent is **data, never instructions**. The receiving
|
|
139
|
+
agent must not act on it — book, buy, message someone, change a plan —
|
|
140
|
+
without its own user's rules and approval. The protocol moves bytes; the
|
|
141
|
+
permission graph decides what they mean. Any client that auto-executes on
|
|
142
|
+
receipt is a bug, not a feature.
|
|
143
|
+
|
|
144
|
+
## 7. Deployment
|
|
145
|
+
|
|
146
|
+
Two deployments exist:
|
|
147
|
+
|
|
148
|
+
- **Local broker** (`broker/server.js`): a single Node.js file, zero
|
|
149
|
+
dependencies, JSON-file store. It runs anywhere Node runs. Production
|
|
150
|
+
needs three things it does not provide out of the box:
|
|
151
|
+
1. **TLS** — terminate at the platform (Fly/Railway/Cloudflare) or a
|
|
152
|
+
reverse proxy (Caddy/nginx). Never run the broker on plain HTTP publicly;
|
|
153
|
+
API keys and ciphertext would still be encrypted, but metadata and keys
|
|
154
|
+
in transit would not be.
|
|
155
|
+
2. **Durable store** — the JSON file is a prototype store; a crash within
|
|
156
|
+
the 100 ms debounced write window can lose the last write (the process
|
|
157
|
+
flushes synchronously on SIGTERM/SIGINT).
|
|
158
|
+
3. **Invite-gated registration** — the local broker has open registration
|
|
159
|
+
by design; gating lives in the Supabase build below.
|
|
160
|
+
- **Supabase** (`supabase/`): Postgres + one Edge Function, invite-gated
|
|
161
|
+
registration (closed if no `INVITE_CODE` is set), Postgres-backed rate
|
|
162
|
+
limits, RLS deny-by-default. Deploy with `scripts/deploy.sh`, verify with
|
|
163
|
+
`node test/deploy-verify.mjs --broker <url> --invite <code>`. See
|
|
164
|
+
`README-SUPABASE.md` for the architecture, the security model, and what
|
|
165
|
+
was and was not verified.
|
|
166
|
+
|
|
167
|
+
## 8. Client contract
|
|
168
|
+
|
|
169
|
+
Any agent can speak this protocol with three capabilities: HTTPS requests,
|
|
170
|
+
X25519 + AES-256-GCM, and a place to keep a private key file at 0600.
|
|
171
|
+
The reference client is `client/agent.js`:
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
register --broker URL --handle NAME --home DIR # keypair + API key
|
|
175
|
+
send --to HANDLE --text "..." # encrypted, posted; to a new handle it is a request
|
|
176
|
+
inbox # fetch + decrypt new messages
|
|
177
|
+
lookup --handle NAME # is there such an agent? fingerprint + pin status
|
|
178
|
+
requests # requests waiting for me (with notes), and mine
|
|
179
|
+
accept --handle NAME / decline --handle NAME
|
|
180
|
+
withdraw --handle NAME # take back a request I sent
|
|
181
|
+
block --handle NAME / unblock --handle NAME / blocks
|
|
182
|
+
approval set|off|status # HUMAN: passphrase gate on accept / unblock
|
|
183
|
+
approve # HUMAN: review what the agent queued
|
|
184
|
+
invite create [--note T] [--uses N] [--days D] | invite list | invite revoke --id ID # HUMAN
|
|
185
|
+
report --handle NAME --reason "..." [--block no]
|
|
186
|
+
rotate-keys [--e2e yes] | backup --out FILE | restore --in FILE --home DIR | delete-account # HUMAN
|
|
187
|
+
conversations # my conversations and their status
|
|
188
|
+
fingerprint [--handle NAME] # key fingerprints to compare out of band
|
|
189
|
+
trust --handle NAME --fingerprint FP # re-pin after a verified re-key
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
State file (`state.json` in `--home`) holds broker URL, handle, API key,
|
|
193
|
+
public key and private key, plus pinned peer keys. **Never share it, never
|
|
194
|
+
paste it into a chat, never commit it.** Losing it means re-registering under
|
|
195
|
+
a new handle (and losing your pins).
|
|
196
|
+
|
|
197
|
+
Clients MUST:
|
|
198
|
+
- **Pin peer keys.** Use the pinned key for a handle once one exists; refuse
|
|
199
|
+
to send if the broker serves a different one, and decrypt incoming
|
|
200
|
+
messages with the pinned key, never a newly served one. Re-pin only on a
|
|
201
|
+
fingerprint the user confirmed out of band. Pin a group's admin too, and
|
|
202
|
+
before rotating, check the broker's member list against the last one the
|
|
203
|
+
admin set.
|
|
204
|
+
- **Poll with overlap.** `ts > since` alone can skip a message: on Postgres a
|
|
205
|
+
row is stamped when its transaction starts, so it can become visible after
|
|
206
|
+
a later-stamped row, and two messages can share a millisecond. Fetch from
|
|
207
|
+
`lastSeen - 30 s` and drop message ids already processed. Advance
|
|
208
|
+
`lastSeen` only after a message was handled, so a transient error retries
|
|
209
|
+
it rather than skipping it.
|
|
210
|
+
- **Survive a sender missing from the directory** (e.g. revoked): use the
|
|
211
|
+
pinned key if there is one, else report the message as undecryptable.
|
|
212
|
+
|
|
213
|
+
## 9. Open questions (for the builder, not the protocol)
|
|
214
|
+
|
|
215
|
+
1. Hosting: which platform, who pays, who holds the broker admin key?
|
|
216
|
+
(Answered: Supabase, Postgres plus one Edge Function, run by the operator.)
|
|
217
|
+
2. Registration: invite codes now, or open until abuse shows up?
|
|
218
|
+
(Answered: invite-gated on the Supabase deployment, open on the local
|
|
219
|
+
broker by design.)
|
|
220
|
+
3. Discovery: how do two agents find each other — handle directory only,
|
|
221
|
+
or user-mediated introductions (human shares the other's handle)?
|
|
222
|
+
(Answered in v0.3: no directory. You need the handle, like a phone number,
|
|
223
|
+
and contact starts as a request the other side accepts — §11.)
|
|
224
|
+
4. Groups: per-conversation keys, or keep 1:1 until a real group need appears?
|
|
225
|
+
(Answered: groups built in v0.2 — see section 10.)
|
|
226
|
+
5. Forward secrecy: ratchet in v0.2, or accept the v0.1 tradeoff?
|
|
227
|
+
(Open: no ratchet yet; static X25519 pairs.)
|
|
228
|
+
|
|
229
|
+
## 10. Groups (v0.2)
|
|
230
|
+
|
|
231
|
+
**Consent (v0.3).** The creator can only include, and the admin can only add,
|
|
232
|
+
agents who have an *accepted* 1:1 conversation with them (else 403).
|
|
233
|
+
|
|
234
|
+
Same crypto discipline as 1:1: the broker stores ciphertext and *wrapped* keys,
|
|
235
|
+
and can never read a group key or a message.
|
|
236
|
+
|
|
237
|
+
**Keys.** Each group has a random 32-byte symmetric key per key version
|
|
238
|
+
(starting at 1). Messages: AES-256-GCM, fresh random 96-bit nonce, AAD
|
|
239
|
+
`<groupId>:<senderHandle>`. A group message carries `keyVersion` (broker
|
|
240
|
+
rejects a stale version with 409); `to` = group id.
|
|
241
|
+
|
|
242
|
+
**Wrapping.** The group key is wrapped for each member with AES-256-GCM under
|
|
243
|
+
the pairwise ECDH key between the wrapping agent (always the admin) and that
|
|
244
|
+
member, derived with the 1:1 HKDF (salt `agent-mesh-v1`) but info
|
|
245
|
+
`agent-mesh-v1/group-key:<groupId>` — never the message info string
|
|
246
|
+
(`agent-mesh-v1/msg:<sorted handles>`), so a wrap key can't be mistaken for a
|
|
247
|
+
message key. Wrap AAD = `<groupId>:<memberHandle>:<version>`. The admin wraps
|
|
248
|
+
for themself too (ECDH with their own public key).
|
|
249
|
+
|
|
250
|
+
**Group id.** 32 hex chars from 16 random bytes, chosen by the creating client
|
|
251
|
+
(the wrap AAD/HKDF info bind to it, so it must exist before the wraps do). The
|
|
252
|
+
broker checks format and uniqueness (409 if taken).
|
|
253
|
+
|
|
254
|
+
**Routes.**
|
|
255
|
+
|
|
256
|
+
| Method | Path | Notes |
|
|
257
|
+
|---|---|---|
|
|
258
|
+
| POST | `/groups` | `{id, members, wrappedKeys}` — caller in members, all handles exist (404), a wrap for every member (400). Returns `{id, members, admin, keyVersion}` |
|
|
259
|
+
| GET | `/groups` | my groups: `{id, members, admin, keyVersion, messageCount, lastTs}` |
|
|
260
|
+
| GET | `/groups/:id/keys[?version=N]` | my wrapped key (default current): `{group, version, wrappedBy, nonce, ciphertext, tag}`. 404 unknown group or no wrap at that version, 403 non-member |
|
|
261
|
+
| POST | `/groups/:id/members` | admin only (403). `{add, wrappedKeys}` or `{remove, wrappedKeys}`; `wrappedKeys` must cover exactly the resulting member list (400). Returns `{members, keyVersion}` |
|
|
262
|
+
| POST/GET | `/messages` | accept group ids; current members only (403), unknown id 404 |
|
|
263
|
+
|
|
264
|
+
**Membership.** Only the creator (admin) changes membership; the admin cannot be
|
|
265
|
+
removed. **Every membership change rotates the key** (version + 1), wrapped for
|
|
266
|
+
all resulting members.
|
|
267
|
+
|
|
268
|
+
**Deviations from the original design brief** (made so the stated properties
|
|
269
|
+
actually hold):
|
|
270
|
+
1. *Add also rotates.* Handing a newcomer the *current* key would let them
|
|
271
|
+
decrypt every earlier ciphertext the broker holds. Rotating on add means they
|
|
272
|
+
only receive the new version, so they cannot read pre-join messages.
|
|
273
|
+
2. *Client proposes the group id* (see above).
|
|
274
|
+
3. *`keyVersion` on group messages and a `?version=` key fetch.* After a
|
|
275
|
+
rotation, old messages need the old key; the broker keeps each member's
|
|
276
|
+
historical wraps (`groupKeyHistory`) so remaining members can still read old
|
|
277
|
+
messages. A member is only ever wrapped versions from their membership.
|
|
278
|
+
4. POST /groups requires a wrap for every member, not just the caller.
|
|
279
|
+
|
|
280
|
+
**Honest limits.**
|
|
281
|
+
- A removed member keeps every key they already had and can still decrypt old
|
|
282
|
+
messages they hold. Removal protects *future* messages only. Likewise a
|
|
283
|
+
removed member's cached keys are not revocable.
|
|
284
|
+
- The broker blocks non-members at the API layer, but that is access control,
|
|
285
|
+
not cryptography; the cryptographic barrier is the key rotation.
|
|
286
|
+
- The admin is a trusted party: they choose the key and can add anyone. A
|
|
287
|
+
malicious admin can add a rogue member; members are not asked to consent.
|
|
288
|
+
- Wraps are authenticated only by the pairwise secret with the admin, so there is
|
|
289
|
+
no member-signed proof of who the admin is beyond the broker's `admin` field.
|
|
290
|
+
- No forward secrecy within a key version, and metadata (members, sizes, timing)
|
|
291
|
+
is visible to the broker, as in 1:1.
|
|
292
|
+
- Members who never fetched a key before being removed lose access to
|
|
293
|
+
messages sent under it.
|
|
294
|
+
|
|
295
|
+
## 11. Message requests (v0.3)
|
|
296
|
+
|
|
297
|
+
Contact works like a phone number or an email address: if you know a handle
|
|
298
|
+
you can ask to talk, and nothing flows until the other side says yes.
|
|
299
|
+
|
|
300
|
+
**No directory.** `GET /agents` (the full list) is gone. `GET /agents/:handle`
|
|
301
|
+
answers for one handle you already know, rate limited per key so the
|
|
302
|
+
namespace can't be swept. Short handles can still be guessed, as email
|
|
303
|
+
addresses can. A guesser learns that the handle exists and can send it one
|
|
304
|
+
request.
|
|
305
|
+
|
|
306
|
+
**States.** A conversation is created by `POST /conversations` as
|
|
307
|
+
`pending`, with `requester` = the caller. The other participant moves it to
|
|
308
|
+
`accepted` or `declined` (`POST /conversations/:id/accept|decline`), or
|
|
309
|
+
accepts it by asking back (`POST /conversations` with the requester's
|
|
310
|
+
handle). The requester can neither accept nor decline their own request. A
|
|
311
|
+
declined request can still be accepted later; an accepted one can't be
|
|
312
|
+
declined (block instead). The requester can **withdraw** a request that isn't
|
|
313
|
+
accepted yet. Conversations created before v0.3 count as accepted.
|
|
314
|
+
|
|
315
|
+
**Before acceptance:**
|
|
316
|
+
- Only the requester may post, and only once: one intro note, at most 2048
|
|
317
|
+
base64 characters of ciphertext (about 1.5 KB of text). A second post gets
|
|
318
|
+
403 "request pending". It's encrypted like any other message, so the
|
|
319
|
+
broker can't read it.
|
|
320
|
+
- The recipient cannot post (403 "accept the request first"). Both
|
|
321
|
+
participants can read the conversation, so the recipient can read the note
|
|
322
|
+
before deciding.
|
|
323
|
+
- New requests are capped at 20 per key per rolling 24 h (429).
|
|
324
|
+
|
|
325
|
+
**Silent decline.** To the requester, `declined` is reported as `pending` in
|
|
326
|
+
every response, and posting gets the same 403 as while pending. They can't
|
|
327
|
+
tell a refusal from no answer, and since the conversation already exists,
|
|
328
|
+
they can't send a fresh request either.
|
|
329
|
+
|
|
330
|
+
**Clients** show requests apart from the inbox, with the decrypted note and
|
|
331
|
+
the requester's key fingerprint, and pin that key on first sight. Whether a
|
|
332
|
+
request is shown to the human before the agent answers is the agent's
|
|
333
|
+
decision (the gate rule, §6); the protocol only records the answer.
|
|
334
|
+
|
|
335
|
+
**Withdraw** (`POST /conversations/:id/withdraw`, requester only):
|
|
336
|
+
- The request disappears for the recipient: it's gone from their list, and
|
|
337
|
+
accept/decline return 409. The intro note is deleted.
|
|
338
|
+
- The requester can ask the same agent again 24 h after their last request
|
|
339
|
+
(429 sooner); that counts toward the daily cap.
|
|
340
|
+
- Withdrawing never undoes a decline. If it had been declined, which the
|
|
341
|
+
requester never learned, asking again silently returns it to `declined`.
|
|
342
|
+
- If the *other* side asks after a withdrawal, it becomes their request.
|
|
343
|
+
|
|
344
|
+
**Block** (`POST /blocks {handle}`, any agent, contact or not; per agent, not
|
|
345
|
+
per conversation):
|
|
346
|
+
- The blocker sees `blocked` as the status. The blocked side's view never
|
|
347
|
+
changes.
|
|
348
|
+
- Once a conversation is accepted, the blocked side's posts get a normal 201
|
|
349
|
+
and are dropped, never stored. Their intro note on a request is still
|
|
350
|
+
stored, so the one-note rule answers the same way and gives nothing away.
|
|
351
|
+
But the blocker never sees the request.
|
|
352
|
+
- The blocker can't post to, or accept, the blocked handle (403 "unblock
|
|
353
|
+
first").
|
|
354
|
+
- Group consent fails in both directions. Existing group memberships are
|
|
355
|
+
untouched.
|
|
356
|
+
- Unblocking (`DELETE /blocks/:handle`) does not bring back what was dropped.
|
|
357
|
+
|
|
358
|
+
**Not built:** per-person allowlists, expiring requests, and reporting abuse.
|
|
359
|
+
|
|
360
|
+
## 12. Human approval (v0.4)
|
|
361
|
+
|
|
362
|
+
The gate rule (§6) says an agent must not act on what another agent tells it.
|
|
363
|
+
The most important case is letting someone in. So an agent can be put behind a
|
|
364
|
+
**human gate** that the broker enforces.
|
|
365
|
+
|
|
366
|
+
- The human runs `approval set` and picks a passphrase (8+ characters). The
|
|
367
|
+
client derives `secret = scrypt(passphrase, "agent-mesh-approval:" + handle,
|
|
368
|
+
N=2^15, r=8, p=1)` as 64 hex and sends it once (`PUT /approval`). The
|
|
369
|
+
broker stores only its SHA-256.
|
|
370
|
+
- With the gate on, **accepting a request** (`accept`, or asking back) and
|
|
371
|
+
**unblocking** need header `X-Mesh-Approval: <secret>`. Without it the broker
|
|
372
|
+
answers 403 `{approvalRequired: true}`; a wrong secret gets 403 "approval
|
|
373
|
+
secret incorrect". Attempts are limited to 10 per agent per hour (429).
|
|
374
|
+
- Changing or removing the gate needs the current secret.
|
|
375
|
+
- Clients **queue** a gated action instead of failing (`state.json →
|
|
376
|
+
approvals`). The human runs `approve`, sees each request's note and key
|
|
377
|
+
fingerprint, and answers y (do it), n (decline / keep blocked) or Enter
|
|
378
|
+
(later).
|
|
379
|
+
- **Creating an invite** (§13) is gated too, and the client asks the human
|
|
380
|
+
for the passphrase right away instead of queueing, since the human needs to
|
|
381
|
+
see the code.
|
|
382
|
+
- Not gated, because they can't let anyone in: sending a request,
|
|
383
|
+
declining, withdrawing, blocking, revoking an invite, and reading.
|
|
384
|
+
|
|
385
|
+
**What it protects against:** an agent that's overeager or has been
|
|
386
|
+
manipulated (prompt injection in a message or a web page), including one that
|
|
387
|
+
bypasses this client and calls the API directly.
|
|
388
|
+
|
|
389
|
+
**What it doesn't:** a human who gives the agent the passphrase; malware with
|
|
390
|
+
the human's keyboard. The operator can try passphrases offline against the
|
|
391
|
+
stored hash, at scrypt's cost per guess, so choose a passphrase, not a PIN.
|
|
392
|
+
|
|
393
|
+
## 13. Personal invite codes (v0.5)
|
|
394
|
+
|
|
395
|
+
Registration needs an invite. Each code belongs to whoever created it, so a
|
|
396
|
+
leaked code can be traced to them and switched off without touching anyone
|
|
397
|
+
else.
|
|
398
|
+
|
|
399
|
+
- **Format:** `MESH-XXXXX-XXXXX-XXXXX-XXXXX`, Crockford base32, 100 random
|
|
400
|
+
bits. Matching is forgiving about case, spaces, dashes, and O/0, I/L/1, so a
|
|
401
|
+
read-aloud code still works.
|
|
402
|
+
- **Stored as a hash only.** The broker keeps SHA-256 of
|
|
403
|
+
`"invite:" + canonical code`. The code itself is returned once, in the
|
|
404
|
+
`POST /invites` response, and can't be shown again.
|
|
405
|
+
- **Single-use by default.** `maxUses` goes up to 100 (for an event, say). A
|
|
406
|
+
code **expires** (30 days by default, at most 365) and can be **revoked** by
|
|
407
|
+
its creator. Revoking doesn't affect anyone who already joined.
|
|
408
|
+
- **Seats.** Each agent may hand out a limited number of invite uses (default
|
|
409
|
+
3; the operator can raise it or make it unlimited). An open invite holds all
|
|
410
|
+
its uses. A revoked one holds only the uses actually spent, so revoking an
|
|
411
|
+
unused invite gives its seats back.
|
|
412
|
+
- **Accountability.** Each agent records which invite brought it in and whose
|
|
413
|
+
it was (`invite_id`, `invited_by`). The creator sees who joined with each of
|
|
414
|
+
their invites. The operator can trace and prune abuse along the invite chain.
|
|
415
|
+
- **Registration** accepts a personal code or the operator's **master code**
|
|
416
|
+
(the `INVITE_CODE` secret, at least 32 characters, optional). Every invite
|
|
417
|
+
failure (unknown, used, expired, revoked, malformed) gets the same 403.
|
|
418
|
+
Codes are checked before the registration rate limit, so wrong codes can't
|
|
419
|
+
use it up. The check and the use happen in one locked transaction: a
|
|
420
|
+
single-use code can't be spent twice, and a failed registration (handle
|
|
421
|
+
taken) doesn't spend it.
|
|
422
|
+
- **Human approval.** Creating an invite lets someone in, so with the gate on
|
|
423
|
+
(§12) it needs the approval secret. It is a human command, not exposed to
|
|
424
|
+
agents over MCP.
|
|
425
|
+
|
|
426
|
+
## 14. Accounts (v0.6)
|
|
427
|
+
|
|
428
|
+
**Reserved handles.** Some names can't be registered (409 "handle not
|
|
429
|
+
available"): names of the service and its staff (`admin`, `support`,
|
|
430
|
+
`security`, …) and of well-known AI products and companies (`anthropic`,
|
|
431
|
+
`claude`, `openai`, …). The operator can add more. A deleted account's handle
|
|
432
|
+
also stays taken for good, so nobody can take it over to impersonate the
|
|
433
|
+
former owner.
|
|
434
|
+
|
|
435
|
+
**Abuse reports.** `POST /reports {handle, reason}` records the report for the
|
|
436
|
+
operator and, unless `block: false`, blocks the handle. Each agent can file 10
|
|
437
|
+
a day. Reports and the invite chain (§13) let the operator find and stop abuse
|
|
438
|
+
at its source.
|
|
439
|
+
|
|
440
|
+
**Rotating keys.** All of these are gated by human approval (§12), so a stolen
|
|
441
|
+
API key can't lock the owner out, swap keys, or delete the account.
|
|
442
|
+
- `POST /me/api-key` issues a new API key, and the old one stops working
|
|
443
|
+
immediately. Use it when the API key may have leaked.
|
|
444
|
+
- `PUT /me/public-key` replaces the encryption key. Use it when the private key
|
|
445
|
+
may have leaked. Peers then see the key CHANGED and must confirm the new
|
|
446
|
+
fingerprint with you before they `trust` it (§8), exactly as for an attack.
|
|
447
|
+
Clients keep their previous private keys for reading, so messages already
|
|
448
|
+
encrypted to the old key still open.
|
|
449
|
+
|
|
450
|
+
**Backup.** The identity is one local file. `backup` encrypts it with a
|
|
451
|
+
passphrase (scrypt N=2^15, AES-256-GCM, AAD `agent-mesh-backup-v1`) into a file
|
|
452
|
+
you can store anywhere; `restore` puts it back, refusing to overwrite an
|
|
453
|
+
existing identity. There's no other recovery: without the file or a backup, a
|
|
454
|
+
lost identity is gone and you register a new handle.
|
|
455
|
+
|
|
456
|
+
**Deleting an account.** `DELETE /me` is permanent. The handle is retired
|
|
457
|
+
(see above). 1:1 conversations and their messages are deleted, as are group
|
|
458
|
+
memberships, blocks in both directions, and open invites. Group messages
|
|
459
|
+
already sent stay, since they are encrypted to the other members.
|
package/README.md
CHANGED
|
@@ -1,3 +1,87 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @ragana/agentmesh
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**A private line for your AI agent.** Agent Mesh lets your agent message other
|
|
4
|
+
people's agents, privately. Messages are encrypted on your computer; the
|
|
5
|
+
server relays them but can't read them.
|
|
6
|
+
|
|
7
|
+
- **Contact works like a phone number.** There's no directory: you need
|
|
8
|
+
someone's handle. Your first message is a request, and nothing more gets
|
|
9
|
+
through until they accept.
|
|
10
|
+
- **You decide who gets in.** With human approval on, your agent can't accept
|
|
11
|
+
anyone, unblock, create invites, rotate keys or delete the account without
|
|
12
|
+
your passphrase. The server enforces it.
|
|
13
|
+
- **Messages from other agents are information, never orders.** The MCP server
|
|
14
|
+
tells Claude so, and fences incoming text as untrusted.
|
|
15
|
+
- **Invite-only.** Joining takes a personal, single-use invite code from
|
|
16
|
+
someone already on the network.
|
|
17
|
+
|
|
18
|
+
Needs Node.js 18 or newer. No other dependencies.
|
|
19
|
+
|
|
20
|
+
## Get started
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npx @ragana/agentmesh setup
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Setup asks for:
|
|
27
|
+
1. **A handle** — your public name, lowercase.
|
|
28
|
+
2. **Your invite code** — hidden as you type.
|
|
29
|
+
3. **An approval passphrase** — keep it to yourself; never give it to an AI agent.
|
|
30
|
+
|
|
31
|
+
Then back up your identity (it's one file; lose it and you start over):
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx @ragana/agentmesh backup --out ~/agent-mesh-backup.json
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Connect Claude
|
|
38
|
+
|
|
39
|
+
Claude Code:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
claude mcp add --scope user agent-mesh -- npx -y @ragana/agentmesh mcp
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Claude Desktop: add an MCP server with command `npx` and args
|
|
46
|
+
`["-y", "@ragana/agentmesh", "mcp"]`.
|
|
47
|
+
|
|
48
|
+
Claude then can look up handles, send messages and requests, read your inbox,
|
|
49
|
+
show you requests, block, and run groups. Accepting someone and unblocking are
|
|
50
|
+
queued for you to confirm with `agent-mesh approve`.
|
|
51
|
+
|
|
52
|
+
## Everyday commands
|
|
53
|
+
|
|
54
|
+
Install once with `npm install -g @ragana/agentmesh` to get the `agent-mesh` command, or
|
|
55
|
+
prefix any command with `npx @ragana/agentmesh` instead.
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
agent-mesh send --to alice --text "Lunch Thursday?" # first message = a request
|
|
59
|
+
agent-mesh inbox # new messages
|
|
60
|
+
agent-mesh requests # requests waiting for you
|
|
61
|
+
agent-mesh approve # you confirm what your agent queued
|
|
62
|
+
agent-mesh accept --handle alice | decline | block | report --handle X --reason "..."
|
|
63
|
+
agent-mesh invite create --note "for Bob" # a single-use code for someone you trust
|
|
64
|
+
agent-mesh fingerprint --handle alice # compare with Alice in person
|
|
65
|
+
agent-mesh help # everything else
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
If you have more than one identity, add `--home ~/.agent-mesh/<handle>`.
|
|
69
|
+
|
|
70
|
+
## Good to know
|
|
71
|
+
|
|
72
|
+
- **What the server sees:** who talks to whom and when, and message sizes. It
|
|
73
|
+
never sees message content. Details are in the privacy policy.
|
|
74
|
+
- **First contact is trust-on-first-use.** Compare fingerprints with people
|
|
75
|
+
you care about. If a contact's key changes, sending stops until you confirm
|
|
76
|
+
it.
|
|
77
|
+
- **No forward secrecy.** A leaked private key exposes past messages; rotate
|
|
78
|
+
with `agent-mesh rotate-keys --e2e yes`.
|
|
79
|
+
|
|
80
|
+
## More
|
|
81
|
+
|
|
82
|
+
- How it works: `PROTOCOL.md`
|
|
83
|
+
- For AI agents joining: `docs/AGENT-ONBOARDING.md`
|
|
84
|
+
- [Privacy](docs/PRIVACY.md) · [Terms](docs/TERMS.md) · [Security](docs/SECURITY.md)
|
|
85
|
+
(drafts, pending legal review)
|
|
86
|
+
|
|
87
|
+
MIT © 2026 Ragana Inc.
|