Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix(gateway): tool descriptions that tell the truth about authorisation

ruvd423bd3a659f
diff --git a/plugins/ruflo-x-gateway/src/server.mjs b/plugins/ruflo-x-gateway/src/server.mjs
index ae12d6f086..9e4591b548 100644
--- a/plugins/ruflo-x-gateway/src/server.mjs
+++ b/plugins/ruflo-x-gateway/src/server.mjs
@@ -83,6 +83,14 @@ export function createGateway({ relay, keyFile, port } = {}) {
(checkAdmin(args.adminToken) || (auth?.mode === 'oauth' && hasScope(auth.scopes, SCOPE_PUBLISH)))
? fn(args)
: denied();
+
+ // Membership changes are NOT publishing. `swarm:publish` says "may post a
+ // message"; admitting a member or minting an invite decides who may join the
+ // federation at all. A self-registered client can obtain swarm:publish with
+ // nothing but a sign-in, so letting that scope grant membership control would
+ // make the registration gate the only thing standing between a stranger and
+ // the relay roster. These stay admin-token only.
+ const adminOnly = (fn) => async (args) => (checkAdmin(args.adminToken) ? fn(args) : denied());
// OPTIONAL, deliberately: there are now two ways to earn write authority, and a
// required adminToken would make every OAuth-authorised write fail at schema
// validation before the handler could consider the token at all. The handler
@@ -99,24 +107,24 @@ export function createGateway({ relay, keyFile, port } = {}) {
mcp.tool('claims_status', 'Current owner-per-resource claims ledger from recent verified claim events. Open read.', {},
async () => { const ev = await fetchRecent(RELAY, sk, { sinceSeconds: 86400, limit: 500 }); return text(reduceClaims(ev.filter((e) => String(e.type).startsWith('Claim')))); });
// ---- admin-gated writes (use the GATEWAY identity) ----
- mcp.tool('federation_join', 'Publish a signed PeerHello AS THE GATEWAY. Admin-gated. Users should join with their own key via invite→claim instead.',
+ mcp.tool('federation_join', 'Publish a signed PeerHello AS THE GATEWAY. Authorised by an OAuth access token carrying swarm:publish, or by the admin token. Almost always the wrong tool for a person: it announces the GATEWAY, not you. Join with your own key via invite→claim — see federation_onboarding.',
{ name: z.string(), platform: z.string().optional(), note: z.string().optional(), ...adminArg },
gated(auth, async ({ name, platform, note }) => text({ ok: true, eventId: await publish(RELAY, sk, 'PeerHello', { from: name, platform, note }) })));
- mcp.tool('federation_publish', 'Publish a signed coordination message AS THE GATEWAY (Status/Task/Result…). Admin-gated.',
+ mcp.tool('federation_publish', 'Publish a signed coordination message AS THE GATEWAY (Status/Task/Result…). Authorised by an OAuth access token carrying swarm:publish, or by the admin token for service-side callers. Use when a gateway-identity message is what you want; to speak AS YOURSELF publish with your own key over the relay — see federation_onboarding. Never ask a person to paste the admin token: it also authorises every other gateway write.',
{ msgType: z.string(), payload: z.record(z.any()), ...adminArg },
gated(auth, async ({ msgType, payload }) => text({ ok: true, eventId: await publish(RELAY, sk, msgType, payload) })));
- mcp.tool('claims_issue', 'Issue a work claim AS THE GATEWAY. Admin-gated. One owner per resourceId.',
+ mcp.tool('claims_issue', 'Issue a work claim AS THE GATEWAY. One owner per resourceId. Authorised by an OAuth access token carrying swarm:publish, or by the admin token. Use to reserve a resource so two agents do not both act on it; claiming on behalf of another identity is wrong because the ledger records the GATEWAY as owner.',
{ resourceId: z.string(), ttlSeconds: z.number().optional(), ...adminArg },
gated(auth, async ({ resourceId, ttlSeconds }) => text({ ok: true, eventId: await publish(RELAY, sk, 'ClaimIssued', { from: pubkey, resourceId, ttlSeconds }), resourceId })));
- mcp.tool('claims_release', 'Release a gateway-held work claim. Admin-gated.',
+ mcp.tool('claims_release', 'Release a gateway-held work claim. Authorised by an OAuth access token carrying swarm:publish, or by the admin token. Only releases claims the GATEWAY holds — a claim issued by another identity must be released by that identity.',
{ resourceId: z.string(), ...adminArg },
gated(auth, async ({ resourceId }) => text({ ok: true, eventId: await publish(RELAY, sk, 'ClaimReleased', { from: pubkey, resourceId }), resourceId })));
- mcp.tool('federation_invite_mint', 'Mint a self-service invite code (v2, use-limited, expiring) so a new ruflo user can claim relay membership with their own key. Admin-gated; the gateway must hold relay admin role.',
+ mcp.tool('federation_invite_mint', 'Mint a self-service invite code (v2, use-limited, expiring) so a new ruflo user can claim relay membership with their own key. Requires the admin token — an OAuth swarm:publish token is NOT sufficient, because minting invites grants relay membership rather than publishing a message. The gateway must hold the relay admin role. An invite code is a bearer secret: send it to one person directly, never to a channel.',
{ ttlSecs: z.number().optional(), maxUses: z.number().optional(), ...adminArg },
- gated(auth, async ({ ttlSecs, maxUses }) => text(await mintInvite(HTTP_BASE, sk, { ttlSecs, maxUses }))));
- mcp.tool('federation_admit', 'Admit a pubkey as a relay member directly (NIP-43 kind 9030). Admin-gated.',
+ adminOnly(async ({ ttlSecs, maxUses }) => text(await mintInvite(HTTP_BASE, sk, { ttlSecs, maxUses }))));
+ mcp.tool('federation_admit', 'Admit a pubkey as a relay member directly (NIP-43 kind 9030). Requires the admin token — an OAuth swarm:publish token is NOT sufficient, because admission changes who may join rather than publishing a message. Prefer federation_invite_mint so the newcomer proves possession of their own key.',
{ pubkey: z.string(), role: z.enum(['member', 'admin']).optional(), ...adminArg },
- gated(auth, async ({ pubkey: pk, role }) => text(await admitMember(RELAY, sk, pk, role))));
+ adminOnly(async ({ pubkey: pk, role }) => text(await admitMember(RELAY, sk, pk, role))));
// ---- ADR-386 channels ----
mcp.tool('channel_list', 'List swarm channels seen recently, with visibility, message count and publisher count. Open read. Public channel ids carry their name (pub:<name>); private ids are opaque (prv:<hex>) and reveal nothing about the topic. Well-known channels (pub:announce, pub:help, pub:claims, pub:showcase) are always listed even when quiet, with messages:0 and a purpose — a channel nobody posted in today is otherwise undiscoverable, which is how it stays empty. Use when you want to find where coordination is happening before reading a stream. Reading the flat firehose with federation_sync instead is wrong once channels are in use, because it mixes unrelated work and cannot show you private traffic exists at all.',
{ sinceSeconds: z.number().optional(), limit: z.number().optional() },
@@ -128,7 +136,7 @@ export function createGateway({ relay, keyFile, port } = {}) {
const messages = await fetchChannel(RELAY, sk, { channelId: channel, sinceSeconds, limit });
return text({ channel, visibility: isPrivateChannel(channel) ? 'private' : 'public', count: messages.length, messages });
});
- mcp.tool('channel_publish', 'Publish a message to a PUBLIC channel as the gateway. Admin-gated. Private channels are refused here on purpose: their content is encrypted with a key only clients hold, so publish to them with your own key via `ruflo federation channel publish`. Use when a service-side process needs to post to a shared public stream; for anything attributable to a person or agent, publish with that identity instead.',
+ mcp.tool('channel_publish', 'Publish a message to a PUBLIC channel as the gateway. Authorised by an OAuth access token carrying swarm:publish, or by the admin token for service-side callers. Private channels are refused here on purpose: their content is encrypted with a key only clients hold, so publish to them with your own key via `ruflo federation channel publish`. Use when a service-side process needs to post to a shared public stream; for anything attributable to a person or agent, publish with that identity instead.',
{ channel: z.string(), msgType: z.string(), payload: z.record(z.any()), ...adminArg },
gated(auth, async ({ channel, msgType, payload }) => {
// Refuse private BEFORE normalising, so a prv: id gets the real reason rather
@@ -142,8 +150,8 @@ export function createGateway({ relay, keyFile, port } = {}) {
"How to join and publish as yourself, and which identity signs what. Open — no token. Use when you are new here, when a publish was refused for a credential, or before telling someone to paste a token anywhere. Reaching for federation_publish to speak as a person is the usual wrong turn: it signs as the GATEWAY, which is why it is gated; you publish with your own key over the relay connection. This never generates or asks for a secret key — it returns the code for you to run locally, because a service that mints your key has seen it.",
{},
async () => text(onboardingGuide({ relay: RELAY, httpBase: HTTP_BASE, gatewayPubkey: pubkey, defaultChannels: DEFAULT_CHANNELS })));
- // ---- Seraphina: swarm queen guidance (admin-gated: it spends meta-llm budget) ----
- mcp.tool('seraphina_guidance', 'Ask Seraphina — swarm queen / primary coordinator — for guidance on a goal. Reads the live roster, claims board and recent messages, reasons via the cognitum meta-llm gateway (cognitum-auto default; tier override), returns {guidance, proposals[], risks[]}. Admin-gated because it spends meta-llm budget. Use when deciding what the swarm should do next or how to resolve a claim conflict. Assigning work from raw sync output is wrong because it ignores current claims and node liveness, which Seraphina checks first.',
+ // ---- Seraphina: swarm queen guidance (OPEN, bounded by a shared budget) ----
+ mcp.tool('seraphina_guidance', 'Ask Seraphina — swarm queen / primary coordinator — for guidance on a goal. Reads the live roster, claims board and recent messages, reasons via the cognitum meta-llm gateway (cognitum-auto default; tier override), returns {guidance, proposals[], risks[]}. Open to anyone, bounded by a shared daily/hourly budget rather than a credential, because it reads and advises and writes nothing. The admin token is OPTIONAL: it lifts that cap and unlocks the high/ultra tiers — it is not required to ask. Use when deciding what the swarm should do next or how to resolve a claim conflict. Assigning work from raw sync output is wrong because it ignores current claims and node liveness, which Seraphina checks first.',
{ goal: z.string(), tier: z.enum(['cognitum-auto','cognitum-low','cognitum-mid','cognitum-high','cognitum-ultra']).optional(), adminToken: z.string().optional().describe('Optional. Lifts the shared budget cap and allows the high/ultra tiers. Never put this in a browser — it also authorises gateway-identity writes.'), sinceSeconds: z.number().optional(), limit: z.number().optional() },
(async ({ goal, tier, sinceSeconds, limit, adminToken }) => {
// Seraphina reads and advises; it writes nothing and carries no authority,
diff --git a/plugins/ruflo-x-gateway/test/oauth.test.mjs b/plugins/ruflo-x-gateway/test/oauth.test.mjs
index e155c80458..e5fe2a948e 100644
--- a/plugins/ruflo-x-gateway/test/oauth.test.mjs
+++ b/plugins/ruflo-x-gateway/test/oauth.test.mjs
@@ -264,3 +264,59 @@ test('GET /mcp is refused immediately instead of hanging a stateless stream', as
});
} finally { as.close(); }
});
+
+test('swarm:publish may post, but may NOT change relay membership', async () => {
+ // Publishing and deciding who may join are different powers. A self-registered
+ // client can obtain swarm:publish with nothing but a sign-in, so if that scope
+ // also admitted members, the registration gate would be the only thing between
+ // a stranger and the relay roster.
+ const as = await fakeAuthServer();
+ try {
+ await withGateway(as, async (port) => {
+ const tok = await as.mint({ scope: `${SCOPE_READ} ${SCOPE_PUBLISH}`, audience: CLIENT_ID });
+ const auth = { authorization: `Bearer ${tok}` };
+
+ // Allowed: posting.
+ const pub = await call(port, 'federation_publish', { msgType: 'Status', payload: {} }, auth);
+ assert.doesNotMatch(toolText(pub), /admin token required/, 'swarm:publish must be able to post');
+
+ // Refused: membership control.
+ for (const [name, args] of [
+ ['federation_admit', { pubkey: 'a'.repeat(64), role: 'member' }],
+ ['federation_invite_mint', { ttlSecs: 60, maxUses: 1 }],
+ ]) {
+ const r = await call(port, name, args, auth);
+ assert.match(toolText(r), /admin token required/,
+ `${name} must not be reachable with swarm:publish alone`);
+ }
+ });
+ } finally { as.close(); }
+});
+
+test('every write tool documents the OAuth path, not just the admin token', async () => {
+ // A description saying only "Admin-gated" leads a model to ask a person for
+ // the admin token — which also authorises every other gateway write and must
+ // never be pasted into a browser.
+ const as = await fakeAuthServer();
+ try {
+ await withGateway(as, async (port) => {
+ const r = await fetch(`http://127.0.0.1:${port}/mcp`, { method: 'POST',
+ headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+ body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }) });
+ const raw = await r.text();
+ const line = raw.split('\n').find((l) => l.startsWith('data: '));
+ for (const t of JSON.parse(line ? line.slice(6) : raw).result.tools) {
+ if (!('adminToken' in (t.inputSchema?.properties || {}))) continue;
+ // "Admin-gated" is now always an incomplete answer: either an OAuth
+ // token also authorises the tool, or the admin token is required and
+ // the description must say the scope is not sufficient — or, as with
+ // seraphina_guidance, the tool is not gated at all and the phrase was
+ // simply wrong. Every tool must state its real authorisation.
+ assert.ok(!/Admin-gated/.test(t.description),
+ `${t.name} says "Admin-gated", which no longer describes how it is authorised`);
+ assert.match(t.description, /swarm:publish|admin token is OPTIONAL/,
+ `${t.name} must state whether an OAuth token can authorise it`);
+ }
+ });
+ } finally { as.close(); }
+});