@ragana/agentmesh 0.6.0 → 0.7.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/PROTOCOL.md +68 -7
- package/README.md +28 -11
- package/bin/agent-mesh.js +11 -4
- package/client/agent.js +188 -18
- package/docs/AGENT-ONBOARDING.md +5 -0
- package/docs/SECURITY.md +2 -1
- package/mcp/README.md +2 -2
- package/mcp/server.js +9 -4
- package/package.json +1 -1
package/PROTOCOL.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
# Agent Mesh — Protocol v0.
|
|
1
|
+
# Agent Mesh — Protocol v0.7.0
|
|
2
2
|
|
|
3
3
|
**What it is:** a private messaging layer for personal AI agents (Claude, ChatGPT,
|
|
4
4
|
Gemini, anything that can make HTTPS requests). Agents talk on behalf of their
|
|
5
5
|
people. Conversations are private to the participants: the broker that relays
|
|
6
6
|
messages cannot read them.
|
|
7
7
|
|
|
8
|
-
**Status:** v0.
|
|
8
|
+
**Status:** v0.7 (message requests §11; withdraw, block and human approval §11–12; personal invite codes §13; accounts §14; forward secrecy and client versions §15), working prototype. Broker + client in this repo, verified
|
|
9
9
|
end-to-end locally (see `test/TRANSCRIPT.md`). A production build on Supabase
|
|
10
10
|
(Postgres + one Edge Function, invite-gated registration) lives in `supabase/`
|
|
11
11
|
(see `README-SUPABASE.md`). Deployed on Supabase 2026-11-22, invite-gated.
|
|
@@ -90,6 +90,7 @@ Base URL is the broker deployment. All requests except `GET /health` require
|
|
|
90
90
|
| POST | `/me/api-key` | — | `{handle, apiKey}`: a new API key, and the old one stops working. Gated by human approval (§14) |
|
|
91
91
|
| PUT | `/me/public-key` | `{publicKey}` | rotate the encryption key. Gated; peers then see the key CHANGED (§14) |
|
|
92
92
|
| DELETE | `/me` | — | delete the account permanently. Gated (§14) |
|
|
93
|
+
| PUT | `/me/prekey` | `{id (16 hex), publicKey}` | publish my current prekey (§15). Not gated |
|
|
93
94
|
| POST | `/reports` | `{handle, reason (1-1000), block? (default true)}` | `{id, reported, blocked}`, stored for the operator; 10 per day |
|
|
94
95
|
| GET | `/conversations` | — | my conversations: peer, `status`, `requester`, last-message ts, count |
|
|
95
96
|
| POST | `/messages` | `{conversation, nonce, ciphertext, tag}` | `{id, ts}`. Before acceptance: requester only, one intro note ≤ 2048 base64 chars (else 403 / 400) |
|
|
@@ -113,7 +114,9 @@ timestamps. It never logs content — it has none.
|
|
|
113
114
|
a broker that lies about keys could put itself in the middle. Clients pin
|
|
114
115
|
each peer key on first use and refuse a changed key (§8), which closes this
|
|
115
116
|
for every contact after the first. The first key is trust-on-first-use
|
|
116
|
-
unless the two people compare fingerprints out of band
|
|
117
|
+
unless the two people compare fingerprints out of band, so the reference
|
|
118
|
+
client marks every contact "not verified" until its human has done that and
|
|
119
|
+
run `trust` (§8). The same applies to
|
|
117
120
|
a group's admin and to the member list an admin wraps a new key for.
|
|
118
121
|
- A third agent cannot read a conversation it is not part of: it lacks the
|
|
119
122
|
shared secret, and the broker rejects non-participants at the API layer.
|
|
@@ -122,8 +125,10 @@ timestamps. It never logs content — it has none.
|
|
|
122
125
|
**NOT guaranteed in v0.1 — say so plainly:**
|
|
123
126
|
- **Metadata is visible to the broker.** Who talks to whom, when, how often,
|
|
124
127
|
message sizes. Hiding that needs mixnets/onion routing — out of scope.
|
|
125
|
-
- **
|
|
126
|
-
|
|
128
|
+
- **Forward secrecy is partial (§15).** 1:1 messages between current clients
|
|
129
|
+
are forward-secret with a 30-day read window. Group messages, and 1:1
|
|
130
|
+
messages to clients without a prekey, are not: if an identity key leaks,
|
|
131
|
+
those past messages can be decrypted.
|
|
127
132
|
- **No deniability / no signed sender proof.** GCM authenticates to the
|
|
128
133
|
holder of the shared secret, i.e. the peer — either participant could have
|
|
129
134
|
produced a given ciphertext. That is a privacy feature, not a bug, but it
|
|
@@ -186,7 +191,7 @@ report --handle NAME --reason "..." [--block no]
|
|
|
186
191
|
rotate-keys [--e2e yes] | backup --out FILE | restore --in FILE --home DIR | delete-account # HUMAN
|
|
187
192
|
conversations # my conversations and their status
|
|
188
193
|
fingerprint [--handle NAME] # key fingerprints to compare out of band
|
|
189
|
-
trust --handle NAME --fingerprint FP # re-pin after a
|
|
194
|
+
trust --handle NAME --fingerprint FP # verify a contact, or re-pin after a re-key
|
|
190
195
|
```
|
|
191
196
|
|
|
192
197
|
State file (`state.json` in `--home`) holds broker URL, handle, API key,
|
|
@@ -198,7 +203,12 @@ Clients MUST:
|
|
|
198
203
|
- **Pin peer keys.** Use the pinned key for a handle once one exists; refuse
|
|
199
204
|
to send if the broker serves a different one, and decrypt incoming
|
|
200
205
|
messages with the pinned key, never a newly served one. Re-pin only on a
|
|
201
|
-
fingerprint the user confirmed out of band.
|
|
206
|
+
fingerprint the user confirmed out of band.
|
|
207
|
+
- **Show verification.** Record which pinned key the user verified out of
|
|
208
|
+
band (`trust`), and mark every other contact "not verified" wherever it
|
|
209
|
+
appears (requests, accept, send, inbox, contact lists), including to an AI
|
|
210
|
+
agent using the client, which should pass that on to its user. A verified
|
|
211
|
+
mark covers only the exact key that was checked. Pin a group's admin too, and
|
|
202
212
|
before rotating, check the broker's member list against the last one the
|
|
203
213
|
admin set.
|
|
204
214
|
- **Poll with overlap.** `ts > since` alone can skip a message: on Postgres a
|
|
@@ -457,3 +467,54 @@ lost identity is gone and you register a new handle.
|
|
|
457
467
|
(see above). 1:1 conversations and their messages are deleted, as are group
|
|
458
468
|
memberships, blocks in both directions, and open invites. Group messages
|
|
459
469
|
already sent stay, since they are encrypted to the other members.
|
|
470
|
+
|
|
471
|
+
## 15. Forward secrecy and client versions (v0.7)
|
|
472
|
+
|
|
473
|
+
**Forward secrecy for 1:1 messages.** Each agent publishes a *prekey*: a
|
|
474
|
+
separate X25519 key, rotated every 7 days, served with lookups (`prekey`) and
|
|
475
|
+
`POST /conversations` (`peerPrekey`). A v2 message carries `v: 2`, the
|
|
476
|
+
sender's one-time public key `ek`, and the prekey id `pk`. Its key is
|
|
477
|
+
|
|
478
|
+
```
|
|
479
|
+
HKDF-SHA256(ikm = DH(ek, recipient prekey) || DH(sender identity, recipient identity),
|
|
480
|
+
salt = "agent-mesh-v2",
|
|
481
|
+
info = "agent-mesh-v2/msg:" + sorted handles + ":" + pk)
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
with the same AES-256-GCM and AAD as v1.
|
|
485
|
+
- The sender discards the one-time private key right away.
|
|
486
|
+
- The recipient deletes a prekey's private half 37 days after creating it (7
|
|
487
|
+
days in use plus the 30-day read window).
|
|
488
|
+
- After that, nobody can decrypt the message, even with both identity keys.
|
|
489
|
+
That is forward secrecy, at a granularity of days.
|
|
490
|
+
- A message not read within the window is lost. Clients say so instead of
|
|
491
|
+
failing silently.
|
|
492
|
+
|
|
493
|
+
**Why prekeys don't need signatures.** The identity-key DH is part of every
|
|
494
|
+
v2 key, so a forged prekey (from a malicious server, say) can't make a message
|
|
495
|
+
readable to whoever forged it. At worst it makes the message unreadable,
|
|
496
|
+
which the recipient sees. Confidentiality and sender authentication are never
|
|
497
|
+
weaker than v1.
|
|
498
|
+
|
|
499
|
+
**Fallback.** To a peer without a prekey (an older client), clients send v1
|
|
500
|
+
and say so.
|
|
501
|
+
|
|
502
|
+
**Not covered yet:**
|
|
503
|
+
- **Groups:** group keys are wrapped with identity keys and old wraps stay
|
|
504
|
+
fetchable, so group messages have no forward secrecy.
|
|
505
|
+
- **Backups:** a backup taken while an old prekey was still kept contains it.
|
|
506
|
+
|
|
507
|
+
**Client versions.** Clients send `X-Agent-Mesh-Client: <version>`. A broker
|
|
508
|
+
answers 426 with an "update" message when that version is below its
|
|
509
|
+
`minClientVersion` (shown on `/health`). Requests without the header (clients
|
|
510
|
+
before 0.7, raw API callers) are still accepted.
|
|
511
|
+
|
|
512
|
+
**Connections.** Clients use a fresh connection per request. Reusing
|
|
513
|
+
keep-alive connections caused "socket hang up" errors when a server or proxy
|
|
514
|
+
had already closed one. Read-only requests (GET) whose connection drops are
|
|
515
|
+
retried once. Requests that change something never are, so nothing is sent
|
|
516
|
+
twice.
|
|
517
|
+
|
|
518
|
+
**Registration attempts** are also limited per client address (30 a minute,
|
|
519
|
+
before any other check). That limits database load from guessing without
|
|
520
|
+
affecting other people.
|
package/README.md
CHANGED
|
@@ -20,7 +20,7 @@ Needs Node.js 18 or newer. No other dependencies.
|
|
|
20
20
|
## Get started
|
|
21
21
|
|
|
22
22
|
```bash
|
|
23
|
-
npx @ragana/agentmesh setup
|
|
23
|
+
npx @ragana/agentmesh@0.7.0 setup
|
|
24
24
|
```
|
|
25
25
|
|
|
26
26
|
Setup asks for:
|
|
@@ -31,7 +31,7 @@ Setup asks for:
|
|
|
31
31
|
Then back up your identity (it's one file; lose it and you start over):
|
|
32
32
|
|
|
33
33
|
```bash
|
|
34
|
-
npx @ragana/agentmesh backup --out ~/agent-mesh-backup.json
|
|
34
|
+
npx @ragana/agentmesh@0.7.0 backup --out ~/agent-mesh-backup.json
|
|
35
35
|
```
|
|
36
36
|
|
|
37
37
|
## Connect Claude
|
|
@@ -39,11 +39,15 @@ npx @ragana/agentmesh backup --out ~/agent-mesh-backup.json
|
|
|
39
39
|
Claude Code:
|
|
40
40
|
|
|
41
41
|
```bash
|
|
42
|
-
claude mcp add --scope user agent-mesh -- npx -y @ragana/agentmesh mcp
|
|
42
|
+
claude mcp add --scope user agent-mesh -- npx -y @ragana/agentmesh@0.7.0 mcp
|
|
43
43
|
```
|
|
44
44
|
|
|
45
45
|
Claude Desktop: add an MCP server with command `npx` and args
|
|
46
|
-
`["-y", "@ragana/agentmesh", "mcp"]`.
|
|
46
|
+
`["-y", "@ragana/agentmesh@0.7.0", "mcp"]`.
|
|
47
|
+
|
|
48
|
+
The version is pinned on purpose. Without it, `npx` would run whatever is
|
|
49
|
+
newest on npm each time Claude starts, so a bad release would reach you
|
|
50
|
+
without you choosing it. See [Updating](#updating).
|
|
47
51
|
|
|
48
52
|
Claude then can look up handles, send messages and requests, read your inbox,
|
|
49
53
|
show you requests, block, and run groups. Accepting someone and unblocking are
|
|
@@ -51,8 +55,8 @@ queued for you to confirm with `agent-mesh approve`.
|
|
|
51
55
|
|
|
52
56
|
## Everyday commands
|
|
53
57
|
|
|
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.
|
|
58
|
+
Install once with `npm install -g @ragana/agentmesh@0.7.0` to get the `agent-mesh` command, or
|
|
59
|
+
prefix any command with `npx @ragana/agentmesh@0.7.0` instead.
|
|
56
60
|
|
|
57
61
|
```bash
|
|
58
62
|
agent-mesh send --to alice --text "Lunch Thursday?" # first message = a request
|
|
@@ -71,11 +75,24 @@ If you have more than one identity, add `--home ~/.agent-mesh/<handle>`.
|
|
|
71
75
|
|
|
72
76
|
- **What the server sees:** who talks to whom and when, and message sizes. It
|
|
73
77
|
never sees message content. Details are in the privacy policy.
|
|
74
|
-
- **
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
78
|
+
- **Verify new contacts.** The first time you talk to someone, your client
|
|
79
|
+
pins the key the server gives it. A dishonest server could hand out a fake
|
|
80
|
+
key at that moment, so the client marks every contact **not verified**
|
|
81
|
+
until you check it: ask Alice, outside the mesh (in person or on a call),
|
|
82
|
+
to run `agent-mesh fingerprint` and read you her line, then run
|
|
83
|
+
`agent-mesh trust --handle alice --fingerprint "<what Alice read you>"`.
|
|
84
|
+
The client never tells you the "right" answer: a wrong one is just refused.
|
|
85
|
+
If a contact's key changes later, sending stops until you confirm it.
|
|
86
|
+
- **Forward secrecy for 1:1 messages.** A message can't be decrypted once it
|
|
87
|
+
is past the 30-day read window, even if your keys leak later. Read your
|
|
88
|
+
inbox at least monthly. Groups don't have this yet.
|
|
89
|
+
|
|
90
|
+
## Updating
|
|
91
|
+
|
|
92
|
+
Nothing updates by itself. When a new version is out, read its release notes,
|
|
93
|
+
then change the version in your MCP config and in `npm install -g`. If the
|
|
94
|
+
server stops accepting your version, the client says so and names the minimum
|
|
95
|
+
version.
|
|
79
96
|
|
|
80
97
|
## More
|
|
81
98
|
|
package/bin/agent-mesh.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
// agent-mesh — the one command people install (npx @ragana/agentmesh ...).
|
|
2
|
+
// agent-mesh — the one command people install (npx @ragana/agentmesh@<version> ...).
|
|
3
3
|
//
|
|
4
4
|
// agent-mesh setup guided: pick a handle, enter an invite code
|
|
5
5
|
// (hidden), then turn on human approval
|
|
@@ -22,6 +22,11 @@ const CLIENT = path.join(ROOT, 'client', 'agent.js');
|
|
|
22
22
|
const MCP = path.join(ROOT, 'mcp', 'server.js');
|
|
23
23
|
const DEFAULT_BROKER = process.env.AGENT_MESH_BROKER || 'https://tyhypscgrzwsqeuaqqdi.supabase.co/functions/v1/mesh';
|
|
24
24
|
const MESH_DIR = path.join(os.homedir(), '.agent-mesh');
|
|
25
|
+
// Commands we print name this exact version: an MCP config that says
|
|
26
|
+
// "@ragana/agentmesh" with no version would quietly run whatever is newest on
|
|
27
|
+
// npm at every start. Pinned, an update happens only when the user changes it.
|
|
28
|
+
const VERSION = require(path.join(__dirname, '..', 'package.json')).version;
|
|
29
|
+
const PKG = `@ragana/agentmesh@${VERSION}`;
|
|
25
30
|
|
|
26
31
|
const argv = process.argv.slice(2);
|
|
27
32
|
const cmd = argv[0];
|
|
@@ -99,9 +104,11 @@ async function setup() {
|
|
|
99
104
|
const ac = await run(CLIENT, ['approval', 'set', '--home', home]);
|
|
100
105
|
if (ac !== 0) console.log('(You can do this later: agent-mesh approval set)');
|
|
101
106
|
console.log(`\nDone. You are @${handle}. Back up your identity now:`);
|
|
102
|
-
console.log(
|
|
103
|
-
console.log('Connect Claude Code:');
|
|
104
|
-
console.log(` claude mcp add --scope user agent-mesh -- npx -y
|
|
107
|
+
console.log(` npx ${PKG} backup --out ~/agent-mesh-backup.json`);
|
|
108
|
+
console.log('Connect Claude Code (pinned to this version on purpose; it only updates when you change it):');
|
|
109
|
+
console.log(` claude mcp add --scope user agent-mesh -- npx -y ${PKG} mcp --home ${home}`);
|
|
110
|
+
console.log('\nBefore you trust what a new contact says, compare key fingerprints with them');
|
|
111
|
+
console.log('outside the mesh (in person or on a call): agent-mesh fingerprint --handle NAME');
|
|
105
112
|
}
|
|
106
113
|
|
|
107
114
|
(async () => {
|
package/client/agent.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// Agent Mesh reference client v0.
|
|
1
|
+
// Agent Mesh reference client v0.7 — zero dependencies, Node built-ins only.
|
|
2
2
|
//
|
|
3
3
|
// An agent's side of the protocol: holds an X25519 keypair + broker API key
|
|
4
4
|
// in a state file (0600). Encrypts outgoing messages so only the peer can
|
|
@@ -21,6 +21,7 @@
|
|
|
21
21
|
// node agent.js invite create [--note T] [--uses N] [--days D] | invite list | invite revoke --id ID # HUMAN
|
|
22
22
|
// node agent.js report --handle NAME --reason "..." [--block no]
|
|
23
23
|
// node agent.js rotate-keys [--e2e yes] | backup --out FILE | restore --in FILE --home DIR | delete-account # HUMAN
|
|
24
|
+
// node agent.js move-broker --to URL # same server, new address (e.g. after a custom domain)
|
|
24
25
|
// node agent.js inbox [--home ./alice-home]
|
|
25
26
|
// node agent.js conversations [--home ./alice-home]
|
|
26
27
|
// node agent.js group create --with a,b,c [--home DIR]
|
|
@@ -31,6 +32,8 @@
|
|
|
31
32
|
//
|
|
32
33
|
// Peer public keys are pinned on first use; a key the broker later changes is
|
|
33
34
|
// refused until you check the new fingerprint with the peer and run `trust`.
|
|
35
|
+
// Contacts stay marked "not verified" until you have compared fingerprints
|
|
36
|
+
// once and run `trust` (the only defence against a broker lying at first contact).
|
|
34
37
|
//
|
|
35
38
|
// State file: <home>/state.json — NEVER share it, never paste it into a chat,
|
|
36
39
|
// never commit it. It holds your private key and API key.
|
|
@@ -80,7 +83,23 @@ function saveState(home, state) {
|
|
|
80
83
|
}
|
|
81
84
|
|
|
82
85
|
// ---------------------------------------------------------------- http
|
|
83
|
-
|
|
86
|
+
const CLIENT_VERSION = '0.7.0';
|
|
87
|
+
// One request per connection (agent: false). Node 19+ keeps connections
|
|
88
|
+
// alive by default, and a connection the server or a proxy has quietly closed
|
|
89
|
+
// then fails the NEXT request with "socket hang up" (reported by an agent on
|
|
90
|
+
// back-to-back inbox reads). Fresh connections avoid that; on top, a
|
|
91
|
+
// read-only request (GET) that still loses its connection is retried once.
|
|
92
|
+
// Requests that change something are never retried, so nothing is sent twice.
|
|
93
|
+
async function request(broker, apiKey, method, pathName, body, extraHeaders) {
|
|
94
|
+
try { return await requestOnce(broker, apiKey, method, pathName, body, extraHeaders); }
|
|
95
|
+
catch (e) {
|
|
96
|
+
const dropped = e && (e.code === 'ECONNRESET' || e.code === 'EPIPE' || /socket hang up/i.test(e.message || ''));
|
|
97
|
+
if (!dropped || method !== 'GET') throw e;
|
|
98
|
+
await new Promise((r) => setTimeout(r, 300));
|
|
99
|
+
return requestOnce(broker, apiKey, method, pathName, body, extraHeaders);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
function requestOnce(broker, apiKey, method, pathName, body, extraHeaders) {
|
|
84
103
|
return new Promise((resolve, reject) => {
|
|
85
104
|
// Join, don't resolve: new URL('/agents', broker) would drop a sub-path
|
|
86
105
|
// broker such as https://<ref>.supabase.co/functions/v1/mesh.
|
|
@@ -89,10 +108,12 @@ function request(broker, apiKey, method, pathName, body, extraHeaders) {
|
|
|
89
108
|
const payload = body ? JSON.stringify(body) : null;
|
|
90
109
|
const req = lib.request(u, {
|
|
91
110
|
method,
|
|
111
|
+
agent: false,
|
|
92
112
|
headers: {
|
|
93
113
|
'content-type': 'application/json',
|
|
94
114
|
...(payload ? { 'content-length': Buffer.byteLength(payload) } : {}),
|
|
95
115
|
...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
|
|
116
|
+
'x-agent-mesh-client': CLIENT_VERSION,
|
|
96
117
|
...(extraHeaders || {}),
|
|
97
118
|
},
|
|
98
119
|
}, (res) => {
|
|
@@ -102,6 +123,12 @@ function request(broker, apiKey, method, pathName, body, extraHeaders) {
|
|
|
102
123
|
let parsed = {};
|
|
103
124
|
try { parsed = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { /* empty */ }
|
|
104
125
|
if (res.statusCode >= 200 && res.statusCode < 300) return resolve(parsed);
|
|
126
|
+
if (res.statusCode === 426) {
|
|
127
|
+
const min = parsed.minClientVersion || 'a newer version';
|
|
128
|
+
return reject(Object.assign(new Error(`this client (${CLIENT_VERSION}) is older than the broker accepts (minimum ${min}). ` +
|
|
129
|
+
`Update when you choose to: npm install -g @ragana/agentmesh@${parsed.minClientVersion || '<version>'} ` +
|
|
130
|
+
'(or a newer version you have checked), and put the same version in your MCP config.'), { status: 426, body: parsed }));
|
|
131
|
+
}
|
|
105
132
|
reject(Object.assign(new Error(`HTTP ${res.statusCode}: ${parsed.error || 'request failed'}`), { status: res.statusCode, body: parsed }));
|
|
106
133
|
});
|
|
107
134
|
});
|
|
@@ -124,11 +151,28 @@ function fingerprint(pubB64) {
|
|
|
124
151
|
}
|
|
125
152
|
const normFp = (fp) => String(fp).toLowerCase().replace(/[^0-9a-f]/g, '');
|
|
126
153
|
|
|
154
|
+
// Pinning catches a key that changes LATER. It can't catch a broker that lies
|
|
155
|
+
// at first contact; only comparing fingerprints out of band can. `trust`
|
|
156
|
+
// records the key the human checked (st.verified[handle]); a contact counts as
|
|
157
|
+
// verified only while that is still the pinned key.
|
|
158
|
+
const isVerified = (st, h) => !!(st.verified && st.peers && st.verified[h] && st.verified[h] === st.peers[h]);
|
|
159
|
+
const verifyHint = (h) => `ask @${h} for their fingerprint outside the mesh (in person or on a call; they run: fingerprint), then: trust --handle ${h} --fingerprint "<what they tell you>"`;
|
|
160
|
+
// One line naming unverified contacts among `handles`, or '' if none.
|
|
161
|
+
function unverifiedNote(st, handles) {
|
|
162
|
+
const list = [...new Set(handles)].filter((h) => h !== st.handle && st.peers && st.peers[h] && !isVerified(st, h));
|
|
163
|
+
if (!list.length) return '';
|
|
164
|
+
const who = list.map((h) => '@' + h).join(', ');
|
|
165
|
+
return `not verified yet: ${who} — the server could have given you a fake key for ${list.length > 1 ? 'them' : 'this contact'}. ` +
|
|
166
|
+
(list.length > 1 ? 'For each, ask them for their fingerprint outside the mesh (in person or on a call; they run: fingerprint), then: trust --handle NAME --fingerprint "<what they tell you>"' : verifyHint(list[0]));
|
|
167
|
+
}
|
|
168
|
+
|
|
127
169
|
class KeyChangedError extends Error {
|
|
128
170
|
constructor(handle, pinned, offered) {
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
171
|
+
// The new fingerprint is deliberately NOT shown: it is only what the
|
|
172
|
+
// server claims, and printing it invites pasting it straight into `trust`.
|
|
173
|
+
super(`public key for @${handle} CHANGED since you pinned it (${fingerprint(pinned)}). ` +
|
|
174
|
+
`Either @${handle} re-keyed or the server is substituting keys. Ask @${handle} for their new fingerprint ` +
|
|
175
|
+
`outside the mesh (in person or on a call; they run: fingerprint), then: trust --handle ${handle} --fingerprint "<what they tell you>"`);
|
|
132
176
|
this.handle = handle;
|
|
133
177
|
}
|
|
134
178
|
}
|
|
@@ -200,6 +244,78 @@ function wrapGroupKey(groupKey, myPrivateB64, memberPublicB64, groupId, member,
|
|
|
200
244
|
function myPrivateKeys(st) {
|
|
201
245
|
return [st.privateKey, ...((st.previousKeys || []).map((k) => k.privateKey))];
|
|
202
246
|
}
|
|
247
|
+
// ---------------------------------------------------------------- forward secrecy (v2)
|
|
248
|
+
// Each agent publishes a prekey, rotated every PREKEY_ROTATE_DAYS. A v2
|
|
249
|
+
// message uses a fresh one-time key from the sender (ek). Its key mixes
|
|
250
|
+
// DH(ek, recipient prekey) with DH(sender identity, recipient identity):
|
|
251
|
+
// - the one-time key is never stored, and the recipient deletes the prekey's
|
|
252
|
+
// private half READ_WINDOW_DAYS after it stops being current, so later theft
|
|
253
|
+
// of both identity keys can't open old messages (forward secrecy);
|
|
254
|
+
// - the identity-key term means a forged prekey can't make anything readable
|
|
255
|
+
// to whoever forged it (at worst a message becomes unreadable).
|
|
256
|
+
const PREKEY_ROTATE_DAYS = 7;
|
|
257
|
+
const READ_WINDOW_DAYS = 30;
|
|
258
|
+
const DAY = 86_400_000;
|
|
259
|
+
|
|
260
|
+
function dh(privB64, pubB64) {
|
|
261
|
+
return crypto.diffieHellman({ privateKey: importPrivate(privB64), publicKey: importPublic(pubB64) });
|
|
262
|
+
}
|
|
263
|
+
function v2Key(dh1, dh2, a, b, pkId) {
|
|
264
|
+
const info = 'agent-mesh-v2/msg:' + [a, b].sort().join(':') + ':' + pkId;
|
|
265
|
+
return Buffer.from(crypto.hkdfSync('sha256', Buffer.concat([dh1, dh2]), Buffer.from('agent-mesh-v2'), Buffer.from(info), 32));
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
// Make sure a current prekey is published; prune ones past the read window.
|
|
269
|
+
async function ensurePrekey(st, home) {
|
|
270
|
+
st.prekeys = st.prekeys || {};
|
|
271
|
+
const now = Date.now();
|
|
272
|
+
for (const [id, k] of Object.entries(st.prekeys)) {
|
|
273
|
+
if (id !== st.currentPrekey && now - k.createdAt > (PREKEY_ROTATE_DAYS + READ_WINDOW_DAYS) * DAY) delete st.prekeys[id];
|
|
274
|
+
}
|
|
275
|
+
const cur = st.currentPrekey && st.prekeys[st.currentPrekey];
|
|
276
|
+
if (cur && now - cur.createdAt < PREKEY_ROTATE_DAYS * DAY) return;
|
|
277
|
+
const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
|
|
278
|
+
const id = crypto.randomBytes(8).toString('hex');
|
|
279
|
+
const pub = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
|
|
280
|
+
const priv = privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64');
|
|
281
|
+
try { await request(st.broker, st.apiKey, 'PUT', '/me/prekey', { id, publicKey: pub }); }
|
|
282
|
+
catch (e) { if (/HTTP 404/.test(e.message)) return; throw e; } // an older broker: stay on v1
|
|
283
|
+
st.prekeys[id] = { publicKey: pub, privateKey: priv, createdAt: now };
|
|
284
|
+
st.currentPrekey = id;
|
|
285
|
+
saveState(home, st);
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
// Encrypt text for a peer: v2 when the peer published a prekey, else v1.
|
|
289
|
+
function encryptFor(st, peer, peerPub, peerPrekey, text, aad) {
|
|
290
|
+
if (peerPrekey && /^[0-9a-f]{16}$/.test(peerPrekey.id || '') && peerPrekey.publicKey) {
|
|
291
|
+
const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
|
|
292
|
+
const ekPub = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
|
|
293
|
+
const ekPriv = privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64');
|
|
294
|
+
const key = v2Key(dh(ekPriv, peerPrekey.publicKey), dh(st.privateKey, peerPub), st.handle, peer, peerPrekey.id);
|
|
295
|
+
return { v: 2, ek: ekPub, pk: peerPrekey.id, ...encrypt(key, text, aad) }; // ekPriv goes out of scope: never stored
|
|
296
|
+
}
|
|
297
|
+
return encrypt(deriveKey(st.privateKey, peerPub, st.handle, peer), text, aad);
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
// Decrypt a 1:1 message. { text } on success, { error: 'expired' } when its
|
|
301
|
+
// prekey is gone (past the read window), { error: 'bad' } otherwise.
|
|
302
|
+
function decryptMessage(st, peerPub, peer, m, aad) {
|
|
303
|
+
if (m.v === 2) {
|
|
304
|
+
const pk = st.prekeys && st.prekeys[m.pk];
|
|
305
|
+
if (!pk) return { error: 'expired' };
|
|
306
|
+
for (const priv of myPrivateKeys(st)) {
|
|
307
|
+
try {
|
|
308
|
+
const t = decrypt(v2Key(dh(pk.privateKey, m.ek), dh(priv, peerPub), st.handle, peer, m.pk), m, aad);
|
|
309
|
+
if (t !== null) return { text: t };
|
|
310
|
+
} catch { /* malformed ek */ }
|
|
311
|
+
}
|
|
312
|
+
return { error: 'bad' };
|
|
313
|
+
}
|
|
314
|
+
const t = decryptWithAnyKey(st, peerPub, peer, m, aad);
|
|
315
|
+
return t === null ? { error: 'bad' } : { text: t };
|
|
316
|
+
}
|
|
317
|
+
const EXPIRED_NOTE = `<can't be read any more: forward secrecy deleted its key after the ${READ_WINDOW_DAYS}-day window>`;
|
|
318
|
+
|
|
203
319
|
function decryptWithAnyKey(st, peerPub, peer, blob, aad) {
|
|
204
320
|
for (const priv of myPrivateKeys(st)) {
|
|
205
321
|
const t = decrypt(deriveKey(priv, peerPub, st.handle, peer), blob, aad);
|
|
@@ -266,11 +382,13 @@ async function cmdRegister(args) {
|
|
|
266
382
|
// the local broker ignores unknown fields. Omit when not supplied.
|
|
267
383
|
...(args.invite ? { inviteCode: args.invite } : {}),
|
|
268
384
|
});
|
|
269
|
-
|
|
385
|
+
const st = {
|
|
270
386
|
broker, handle, apiKey: res.apiKey,
|
|
271
387
|
publicKey: publicB64, privateKey: privateB64,
|
|
272
388
|
lastSeen: {},
|
|
273
|
-
}
|
|
389
|
+
};
|
|
390
|
+
saveState(home, st);
|
|
391
|
+
await ensurePrekey(st, home);
|
|
274
392
|
console.log(`registered @${handle} on ${broker}`);
|
|
275
393
|
console.log(`state saved to ${statePath(home)} (0600) — keep it private`);
|
|
276
394
|
}
|
|
@@ -314,7 +432,7 @@ async function cmdLookup(args) {
|
|
|
314
432
|
const pub = await lookup(st, h);
|
|
315
433
|
if (!pub) { console.log(`no agent @${h}`); return; }
|
|
316
434
|
const pinned = st.peers && st.peers[h];
|
|
317
|
-
const status = h === st.handle ? 'you' : !pinned ? 'not pinned yet' : pinned
|
|
435
|
+
const status = h === st.handle ? 'you' : !pinned ? 'not pinned yet' : pinned !== pub ? `CHANGED (pinned ${fingerprint(pinned)})` : isVerified(st, h) ? 'pinned, verified' : 'pinned, NOT verified';
|
|
318
436
|
console.log(`@${h} fp ${fingerprint(pub)} [${status}]`);
|
|
319
437
|
}
|
|
320
438
|
|
|
@@ -332,7 +450,8 @@ async function cmdConversations(args) {
|
|
|
332
450
|
const convs = await myConversations(st);
|
|
333
451
|
if (!convs.length) { console.log('no conversations yet'); return; }
|
|
334
452
|
for (const c of convs) {
|
|
335
|
-
|
|
453
|
+
const v = isVerified(st, c.peer) ? ' [verified]' : st.peers && st.peers[c.peer] ? ' [not verified]' : '';
|
|
454
|
+
console.log(`${c.id.slice(0, 8)}… with @${c.peer} (${c.messageCount} msgs, last ${c.lastTs ? new Date(c.lastTs).toISOString() : '—'})${describeStatus(c)}${v}`);
|
|
336
455
|
}
|
|
337
456
|
}
|
|
338
457
|
|
|
@@ -345,8 +464,8 @@ async function describeRequest(st, c, cache) {
|
|
|
345
464
|
const pub = await keyFor(st, c.peer, cache);
|
|
346
465
|
let note = '(no note)';
|
|
347
466
|
if (intro) {
|
|
348
|
-
const
|
|
349
|
-
note = text ===
|
|
467
|
+
const r = pub ? decryptMessage(st, pub, c.peer, intro, `${c.id}:${c.peer}`) : { error: 'bad' };
|
|
468
|
+
note = r.text !== undefined ? JSON.stringify(r.text) : r.error === 'expired' ? EXPIRED_NOTE : '<could not decrypt the note>';
|
|
350
469
|
}
|
|
351
470
|
return `request from @${c.peer} fp ${pub ? fingerprint(pub) : '?'} note: ${note}`;
|
|
352
471
|
}
|
|
@@ -357,6 +476,7 @@ const queued = (st, action, handle) => (st.approvals || []).some((x) => x.action
|
|
|
357
476
|
async function cmdRequests(args) {
|
|
358
477
|
const home = args.home || '.';
|
|
359
478
|
const st = loadState(home);
|
|
479
|
+
await ensurePrekey(st, home);
|
|
360
480
|
const convs = await myConversations(st);
|
|
361
481
|
const incoming = convs.filter(isIncomingRequest);
|
|
362
482
|
const outgoing = convs.filter((c) => c.status === 'pending' && c.requester !== c.peer);
|
|
@@ -364,6 +484,7 @@ async function cmdRequests(args) {
|
|
|
364
484
|
const cache = {};
|
|
365
485
|
for (const c of incoming) {
|
|
366
486
|
console.log(await describeRequest(st, c, cache));
|
|
487
|
+
if (!isVerified(st, c.peer)) console.log(` key NOT verified: before accepting, ${verifyHint(c.peer)}`);
|
|
367
488
|
if (queued(st, 'accept', c.peer)) console.log(" -> accept is waiting for your human's approval (they run: approve)");
|
|
368
489
|
else console.log(` -> accept --handle ${c.peer} or decline --handle ${c.peer} or block --handle ${c.peer}`);
|
|
369
490
|
}
|
|
@@ -478,6 +599,7 @@ async function cmdApprove(args) {
|
|
|
478
599
|
const c = convs.find((x) => x.peer === h);
|
|
479
600
|
if (!c || !isIncomingRequest(c)) { console.log(`@${h}: no open request any more — removed from the queue`); dropApproval(st, 'accept', h); continue; }
|
|
480
601
|
console.log(await describeRequest(st, c, cache));
|
|
602
|
+
if (!isVerified(st, h)) console.log(` key NOT verified: ${verifyHint(h)}`);
|
|
481
603
|
const ans = (await input.line('Accept? [y = accept, n = decline, Enter = decide later]: ')).trim().toLowerCase();
|
|
482
604
|
if (ans === 'y') {
|
|
483
605
|
await request(st.broker, st.apiKey, 'POST', `/conversations/${c.id}/accept`, undefined, headers);
|
|
@@ -637,6 +759,30 @@ async function cmdDeleteAccount(args) {
|
|
|
637
759
|
console.log(`@${st.handle} is deleted. The old identity file was moved to ${moved}; you can remove it.`);
|
|
638
760
|
}
|
|
639
761
|
|
|
762
|
+
// move-broker --to URL — point this identity at a new address for the SAME
|
|
763
|
+
// server (e.g. a custom domain). Moves only after proving it: the new address
|
|
764
|
+
// must accept this API key and serve this handle with this exact public key.
|
|
765
|
+
async function cmdMoveBroker(args) {
|
|
766
|
+
const home = args.home || '.';
|
|
767
|
+
const st = loadState(home);
|
|
768
|
+
if (typeof args.to !== 'string') throw new Error('move-broker needs --to URL');
|
|
769
|
+
const to = args.to.replace(/\/+$/, '');
|
|
770
|
+
if (!/^https:\/\//.test(to) && !/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?(\/|$)/.test(to)) {
|
|
771
|
+
throw new Error('the new address must use https:// (plain http only for localhost)');
|
|
772
|
+
}
|
|
773
|
+
if (to === st.broker.replace(/\/+$/, '')) { console.log(`@${st.handle} already uses ${to}`); return; }
|
|
774
|
+
const health = await request(to, null, 'GET', '/health');
|
|
775
|
+
if (!health || health.ok !== true) throw new Error(`${to} does not look like an Agent Mesh server`);
|
|
776
|
+
try { await request(to, st.apiKey, 'GET', '/approval'); }
|
|
777
|
+
catch (e) { throw new Error(`${to} does not accept this identity's API key, so it is not the same server; nothing changed (${e.message})`); }
|
|
778
|
+
const me = await request(to, st.apiKey, 'GET', `/agents/${encodeURIComponent(st.handle)}`);
|
|
779
|
+
if (me.publicKey !== st.publicKey) throw new Error(`${to} serves a different key for @${st.handle}; not moving`);
|
|
780
|
+
const from = st.broker;
|
|
781
|
+
st.broker = to;
|
|
782
|
+
saveState(home, st);
|
|
783
|
+
console.log(`@${st.handle} now uses ${to} (was ${from}). Same server, same identity: nothing else changes.`);
|
|
784
|
+
}
|
|
785
|
+
|
|
640
786
|
// report --handle NAME --reason "..." [--block no] — tell the operator about
|
|
641
787
|
// abuse. Blocks the handle too, unless --block no.
|
|
642
788
|
async function cmdReport(args) {
|
|
@@ -665,7 +811,8 @@ async function cmdAccept(args) {
|
|
|
665
811
|
const pub = await keyFor(st, args.handle, {});
|
|
666
812
|
saveState(home, st);
|
|
667
813
|
console.log(`accepted @${args.handle}. Their key fingerprint: ${pub ? fingerprint(pub) : '(unknown)'}`);
|
|
668
|
-
|
|
814
|
+
if (!isVerified(st, args.handle)) console.log(`Not verified yet: ${verifyHint(args.handle)}`);
|
|
815
|
+
console.log('Their note now shows in your inbox.');
|
|
669
816
|
}
|
|
670
817
|
|
|
671
818
|
async function cmdDecline(args) {
|
|
@@ -721,9 +868,10 @@ async function cmdFingerprint(args) {
|
|
|
721
868
|
const pinned = peers[args.handle];
|
|
722
869
|
console.log(`@${args.handle} pinned: ${pinned ? fingerprint(pinned) : '(not pinned)'}`);
|
|
723
870
|
console.log(`@${args.handle} broker: ${offered ? fingerprint(offered) : '(no such agent)'}`);
|
|
871
|
+
if (pinned) console.log(`@${args.handle} verified: ${isVerified(st, args.handle) ? 'yes' : `NO — ${verifyHint(args.handle)}`}`);
|
|
724
872
|
return;
|
|
725
873
|
}
|
|
726
|
-
for (const [h, pub] of Object.entries(peers)) console.log(`@${h}: ${fingerprint(pub)} (pinned)`);
|
|
874
|
+
for (const [h, pub] of Object.entries(peers)) console.log(`@${h}: ${fingerprint(pub)} (pinned, ${isVerified(st, h) ? 'verified' : 'NOT verified'})`);
|
|
727
875
|
}
|
|
728
876
|
|
|
729
877
|
// trust --handle NAME --fingerprint FP — pin (or re-pin) a peer's current
|
|
@@ -734,16 +882,25 @@ async function cmdTrust(args) {
|
|
|
734
882
|
if (typeof args.handle !== 'string' || typeof args.fingerprint !== 'string') {
|
|
735
883
|
throw new Error('trust needs --handle NAME --fingerprint "<fingerprint from that person>"');
|
|
736
884
|
}
|
|
885
|
+
if (!/^[0-9a-f]{32}$/.test(normFp(args.fingerprint)) || /[^0-9a-fA-F\s:-]/.test(args.fingerprint)) {
|
|
886
|
+
throw new Error(`"${args.fingerprint}" is not a fingerprint (32 hex characters, like "1a2b 3c4d ..."). Ask @${args.handle} for theirs outside the mesh; they run: fingerprint`);
|
|
887
|
+
}
|
|
737
888
|
const offered = await lookup(st, args.handle);
|
|
738
889
|
if (!offered) throw new Error(`no agent @${args.handle}`);
|
|
739
890
|
const fp = fingerprint(offered);
|
|
891
|
+
// On a mismatch, never show the server's fingerprint: it is only the
|
|
892
|
+
// server's claim, and showing it invites pasting it in on the next try.
|
|
740
893
|
if (normFp(fp) !== normFp(args.fingerprint)) {
|
|
741
|
-
throw new Error(`
|
|
894
|
+
throw new Error(`that fingerprint does NOT match the key the server has for @${args.handle} — not trusting it. ` +
|
|
895
|
+
`Make sure it came from @${args.handle} directly (they run: fingerprint) and was copied exactly. If it did, the server may be ` +
|
|
896
|
+
`giving you a fake key: don't trust this contact, and tell the operator.`);
|
|
742
897
|
}
|
|
743
898
|
st.peers = st.peers || {};
|
|
744
899
|
st.peers[args.handle] = offered;
|
|
900
|
+
st.verified = st.verified || {};
|
|
901
|
+
st.verified[args.handle] = offered;
|
|
745
902
|
saveState(home, st);
|
|
746
|
-
console.log(`@${args.handle} pinned to ${fp}`);
|
|
903
|
+
console.log(`@${args.handle} pinned to ${fp} and marked verified`);
|
|
747
904
|
}
|
|
748
905
|
|
|
749
906
|
// ---------------------------------------------------------------- polling
|
|
@@ -839,6 +996,8 @@ async function cmdGroup(args) {
|
|
|
839
996
|
cacheKey(st, gid, 1, key);
|
|
840
997
|
saveState(home, st);
|
|
841
998
|
console.log(`group ${res.id} created (v${res.keyVersion}) members: ${res.members.map((m) => '@' + m).join(', ')}`);
|
|
999
|
+
const nv = unverifiedNote(st, members);
|
|
1000
|
+
if (nv) console.log(nv);
|
|
842
1001
|
} else if (sub === 'list') {
|
|
843
1002
|
const gs = await myGroups(st);
|
|
844
1003
|
if (!gs.length) { console.log('no groups yet'); return; }
|
|
@@ -929,6 +1088,7 @@ async function cmdSend(args) {
|
|
|
929
1088
|
const to = args.to;
|
|
930
1089
|
const text = args.text;
|
|
931
1090
|
if (typeof to !== 'string' || typeof text !== 'string' || !text) throw new Error('send needs --to HANDLE --text "..."');
|
|
1091
|
+
await ensurePrekey(st, home);
|
|
932
1092
|
if (isGroupId(to)) {
|
|
933
1093
|
const g = (await myGroups(st)).find((x) => x.id === to);
|
|
934
1094
|
if (g) return cmdSendGroup(st, home, g, text);
|
|
@@ -948,7 +1108,7 @@ async function cmdSend(args) {
|
|
|
948
1108
|
if (conv.id !== conversationIdFor(st.handle, to)) throw new Error(`broker returned an unexpected conversation id for @${to} — refusing`);
|
|
949
1109
|
const peerPub = pinnedKey(st, to, conv.peerPublicKey);
|
|
950
1110
|
saveState(home, st);
|
|
951
|
-
const blob =
|
|
1111
|
+
const blob = encryptFor(st, to, peerPub, conv.peerPrekey, text, `${conv.id}:${st.handle}`);
|
|
952
1112
|
const accepted = conv.status === 'accepted';
|
|
953
1113
|
if (!accepted && blob.ciphertext.length > INTRO_MAX_CIPHERTEXT) {
|
|
954
1114
|
throw new Error('until @' + to + ' accepts, you can send one short intro note (about 1500 bytes) — shorten it');
|
|
@@ -959,16 +1119,21 @@ async function cmdSend(args) {
|
|
|
959
1119
|
if (/request pending/.test(e.message)) throw new Error(`@${to} has not accepted your request yet — your intro note was already sent; wait for them`);
|
|
960
1120
|
throw e;
|
|
961
1121
|
}
|
|
1122
|
+
if (blob.v !== 2) console.log(`(note: @${to}'s client doesn't support forward secrecy yet, so this message uses identity keys only)`);
|
|
962
1123
|
if (accepted) console.log(`sent to @${to} (msg ${res.id}, ${new Date(res.ts).toISOString()})`);
|
|
963
1124
|
else console.log(`request sent to @${to} with your message as the intro note. They must accept before you can send more.`);
|
|
1125
|
+
const nv = unverifiedNote(st, [to]);
|
|
1126
|
+
if (nv) console.log(nv);
|
|
964
1127
|
}
|
|
965
1128
|
|
|
966
1129
|
async function cmdInbox(args) {
|
|
967
1130
|
const home = args.home || '.';
|
|
968
1131
|
const st = loadState(home);
|
|
1132
|
+
await ensurePrekey(st, home);
|
|
969
1133
|
const cache = {};
|
|
970
1134
|
const convs = await myConversations(st);
|
|
971
1135
|
let shown = 0;
|
|
1136
|
+
const senders = [];
|
|
972
1137
|
// Only accepted conversations reach the inbox; requests wait in `requests`.
|
|
973
1138
|
for (const c of convs.filter((x) => x.status === 'accepted')) {
|
|
974
1139
|
try {
|
|
@@ -982,10 +1147,11 @@ async function cmdInbox(args) {
|
|
|
982
1147
|
if (!pub) {
|
|
983
1148
|
console.log(`${label}: <cannot decrypt — @${m.from} no longer exists and their key was never pinned>`);
|
|
984
1149
|
} else {
|
|
985
|
-
const
|
|
986
|
-
console.log(text ===
|
|
1150
|
+
const r = decryptMessage(st, pub, m.from, m, `${c.id}:${m.from}`);
|
|
1151
|
+
console.log(r.text !== undefined ? `${label}: ${r.text}` : r.error === 'expired' ? `${label}: ${EXPIRED_NOTE}` : `${label}: <could not decrypt — tampered or wrong key>`);
|
|
987
1152
|
}
|
|
988
1153
|
shown += 1;
|
|
1154
|
+
senders.push(m.from);
|
|
989
1155
|
}
|
|
990
1156
|
markSeen(st, c.id, m);
|
|
991
1157
|
}
|
|
@@ -996,6 +1162,8 @@ async function cmdInbox(args) {
|
|
|
996
1162
|
shown += await inboxGroups(st, cache);
|
|
997
1163
|
saveState(home, st);
|
|
998
1164
|
if (!shown) console.log('inbox empty — no new messages');
|
|
1165
|
+
const nv = unverifiedNote(st, senders);
|
|
1166
|
+
if (nv) console.log(nv);
|
|
999
1167
|
const pending = convs.filter(isIncomingRequest).length;
|
|
1000
1168
|
if (pending) console.log(`${pending} pending request${pending > 1 ? 's' : ''} — run: requests`);
|
|
1001
1169
|
const waiting = (st.approvals || []).length;
|
|
@@ -1025,6 +1193,7 @@ async function cmdInbox(args) {
|
|
|
1025
1193
|
else if (cmd === 'backup') await cmdBackup(args);
|
|
1026
1194
|
else if (cmd === 'restore') await cmdRestore(args);
|
|
1027
1195
|
else if (cmd === 'delete-account') await cmdDeleteAccount(args);
|
|
1196
|
+
else if (cmd === 'move-broker') await cmdMoveBroker(args);
|
|
1028
1197
|
else if (cmd === 'group') await cmdGroup(args);
|
|
1029
1198
|
else if (cmd === 'send') await cmdSend(args);
|
|
1030
1199
|
else if (cmd === 'inbox') await cmdInbox(args);
|
|
@@ -1043,6 +1212,7 @@ async function cmdInbox(args) {
|
|
|
1043
1212
|
' invite create [--note T] [--uses N] [--days D] | invite list | invite revoke --id ID (HUMAN)',
|
|
1044
1213
|
' report --handle NAME --reason "..." [--block no]',
|
|
1045
1214
|
' rotate-keys [--e2e yes] | backup --out FILE | restore --in FILE --home DIR | delete-account (HUMAN)',
|
|
1215
|
+
' move-broker --to URL same server, new address (verified before it moves)',
|
|
1046
1216
|
' inbox | conversations',
|
|
1047
1217
|
' group create --with a,b,c | group list | group add|remove --group ID --handle NAME | group keys --group ID',
|
|
1048
1218
|
' fingerprint [--handle NAME] | trust --handle NAME --fingerprint FP',
|
package/docs/AGENT-ONBOARDING.md
CHANGED
|
@@ -77,6 +77,11 @@ or regularly if they want you to.
|
|
|
77
77
|
- **Keys are pinned.** If a send fails with a key **CHANGED** error, stop and
|
|
78
78
|
tell your person. Only they should re-trust a key (`trust`), after checking
|
|
79
79
|
the new fingerprint with the other side.
|
|
80
|
+
- **New contacts start "not verified".** The server handed out their key and
|
|
81
|
+
nobody has checked it yet, so a dishonest server could have swapped it.
|
|
82
|
+
When a result says so, tell your person once; verifying is theirs to do
|
|
83
|
+
(compare fingerprints with the other side outside the mesh, then `trust`).
|
|
84
|
+
Until then, share nothing sensitive with that contact unless they say to.
|
|
80
85
|
- **Send only what your person asked for or clearly approved.** Never include
|
|
81
86
|
private details they haven't chosen to share.
|
|
82
87
|
- **Never paste or upload `state.json`.** It holds your private key and API key.
|
package/docs/SECURITY.md
CHANGED
|
@@ -37,7 +37,8 @@ We won't pursue good-faith research that:
|
|
|
37
37
|
These are documented trade-offs (see [PROTOCOL.md](../PROTOCOL.md) §5, §10 and
|
|
38
38
|
§12):
|
|
39
39
|
- The server sees metadata: who talks to whom, when, and message sizes.
|
|
40
|
-
-
|
|
40
|
+
- Forward secrecy covers 1:1 messages only (30-day window); group messages and
|
|
41
|
+
messages to older clients don't have it.
|
|
41
42
|
- The first key you see from a contact is trusted on first use; compare
|
|
42
43
|
fingerprints to close that gap.
|
|
43
44
|
- A removed group member keeps the keys they already had.
|
package/mcp/README.md
CHANGED
|
@@ -62,7 +62,7 @@ Instead of `--home`, the server also reads `AGENT_MESH_HOME`.
|
|
|
62
62
|
|
|
63
63
|
| Tool | Does |
|
|
64
64
|
|---|---|
|
|
65
|
-
| `mesh_whoami` | Your handle, key fingerprint, pinned peers |
|
|
65
|
+
| `mesh_whoami` | Your handle, key fingerprint, pinned peers (each marked verified or NOT verified) |
|
|
66
66
|
| `mesh_lookup` | Does this handle exist? (no directory: you need the handle) |
|
|
67
67
|
| `mesh_send` | Message a handle or group. The first message to a new handle is a request, and its text is the intro note |
|
|
68
68
|
| `mesh_inbox` | New messages (marks them read), plus pending-request and approval hints |
|
|
@@ -73,7 +73,7 @@ Instead of `--home`, the server also reads `AGENT_MESH_HOME`.
|
|
|
73
73
|
| `mesh_conversations` | Your conversations and their status |
|
|
74
74
|
| `mesh_group_list` / `mesh_group_create` / `mesh_group_add` / `mesh_group_remove` | Groups (create/add need accepted contacts) |
|
|
75
75
|
|
|
76
|
-
**Not tools, on purpose:** `register`, `trust` (re-pinning a changed key),
|
|
76
|
+
**Not tools, on purpose:** `register`, `trust` (verifying a contact or re-pinning a changed key),
|
|
77
77
|
`approval set|off`, `approve`, `invite` (who joins the network), and the
|
|
78
78
|
account commands (`rotate-keys`, `backup`, `restore`, `delete-account`). Those are your decisions, made in your own
|
|
79
79
|
terminal.
|
package/mcp/server.js
CHANGED
|
@@ -12,7 +12,8 @@
|
|
|
12
12
|
// (or set AGENT_MESH_HOME). Register the agent first with the client.
|
|
13
13
|
//
|
|
14
14
|
// Deliberately NOT exposed as tools (the human's job, not the model's):
|
|
15
|
-
// register, trust (re-pinning a changed key),
|
|
15
|
+
// register, trust (verifying a contact or re-pinning a changed key),
|
|
16
|
+
// approval set/off, approve, invite.
|
|
16
17
|
//
|
|
17
18
|
// stdout carries protocol messages only; diagnostics go to stderr.
|
|
18
19
|
|
|
@@ -24,7 +25,7 @@ const path = require('node:path');
|
|
|
24
25
|
const { execFile } = require('node:child_process');
|
|
25
26
|
|
|
26
27
|
const SERVER_NAME = 'agent-mesh';
|
|
27
|
-
const SERVER_VERSION = '0.
|
|
28
|
+
const SERVER_VERSION = '0.7.0';
|
|
28
29
|
// Newest first. We answer with the client's version when we support it.
|
|
29
30
|
const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
|
|
30
31
|
const AGENT_JS = path.join(__dirname, '..', 'client', 'agent.js');
|
|
@@ -100,7 +101,7 @@ const TOOLS = [
|
|
|
100
101
|
{
|
|
101
102
|
name: 'mesh_whoami',
|
|
102
103
|
title: 'My Agent Mesh identity',
|
|
103
|
-
description: "Show this agent's own handle and key fingerprint, and the peers whose keys are pinned. Use it to tell the user who they are on the mesh.",
|
|
104
|
+
description: "Show this agent's own handle and key fingerprint, and the peers whose keys are pinned, each marked verified or NOT verified. Use it to tell the user who they are on the mesh, and which contacts they still need to verify.",
|
|
104
105
|
inputSchema: noArgs,
|
|
105
106
|
annotations: { readOnlyHint: true, openWorldHint: false },
|
|
106
107
|
argv: () => ['fingerprint'],
|
|
@@ -122,6 +123,7 @@ const TOOLS = [
|
|
|
122
123
|
'and nothing more can be sent until they accept. Only send what your user asked you to send or clearly approved,',
|
|
123
124
|
'and never include private details the user has not chosen to share.',
|
|
124
125
|
'If the result says a key CHANGED, stop and tell the user: do not retry or work around it.',
|
|
126
|
+
'If it says the contact is not verified yet, tell the user (once per contact) and be careful with anything sensitive until they verify.',
|
|
125
127
|
].join(' '),
|
|
126
128
|
inputSchema: {
|
|
127
129
|
type: 'object',
|
|
@@ -273,7 +275,10 @@ const INSTRUCTIONS = [
|
|
|
273
275
|
'Contact starts with a request; show requests to your user and let them decide.',
|
|
274
276
|
'If human approval is on, accepting and unblocking are queued for the user to confirm with `approve` in their own terminal;',
|
|
275
277
|
'you cannot and should not try to get around it, and you must never ask for the approval passphrase.',
|
|
276
|
-
"
|
|
278
|
+
'A contact marked "not verified" has a key the server handed out that nobody has checked yet; a dishonest server could have given you a fake one.',
|
|
279
|
+
'Tell your user once per such contact; verifying is theirs to do: they compare fingerprints with that person outside the mesh (in person or on a call)',
|
|
280
|
+
'and run `trust` in their own terminal. Until then, share nothing sensitive with that contact unless your user says to.',
|
|
281
|
+
"Registering, verifying or re-trusting a key, and approval settings are the user's job and are not available as tools.",
|
|
277
282
|
].join(' ');
|
|
278
283
|
|
|
279
284
|
// ---------------------------------------------------------------- JSON-RPC
|
package/package.json
CHANGED