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): a refused write names the cause instead of blaming the admin token

ruv19e7b32e24b4
diff --git a/plugins/ruflo-x-gateway/src/server.mjs b/plugins/ruflo-x-gateway/src/server.mjs
index 9e4591b548..a889f9eeb9 100644
--- a/plugins/ruflo-x-gateway/src/server.mjs
+++ b/plugins/ruflo-x-gateway/src/server.mjs
@@ -79,10 +79,34 @@ export function createGateway({ relay, keyFile, port } = {}) {
// Either credential may authorise a write: the long-standing admin token, or
// an access token carrying swarm:publish. `auth` is per-request, closed over
// by buildMcp.
+ // Say WHY the write was refused. "admin token required or invalid" is true of
+ // every refusal and useful for none: a caller holding a valid token that is
+ // merely missing a scope reads it as a broken credential and goes looking in
+ // the wrong place. This distinction cost several round trips to diagnose from
+ // logs that only the operator could see.
+ const refusedWrite = (auth) => {
+ if (auth?.mode === 'oauth') {
+ const held = (auth.scopes || []).join(' ') || '(none)';
+ return { isError: true, content: [{ type: 'text', text: JSON.stringify({
+ error: `access token lacks ${SCOPE_PUBLISH}`,
+ granted_scopes: held,
+ remedy: `This token was granted ${held}. Re-authorise this connection and approve `
+ + `${SCOPE_PUBLISH} — an already-issued token cannot gain a scope, and refreshing it `
+ + `keeps the original grant. Do NOT paste an admin token: it authorises every gateway write.`,
+ }) }] };
+ }
+ return { isError: true, content: [{ type: 'text', text: JSON.stringify({
+ error: 'no write credential',
+ remedy: `Authorise with an OAuth access token carrying ${SCOPE_PUBLISH} (see the `
+ + `WWW-Authenticate challenge on a 401), or supply the gateway admin token if you are a `
+ + `service-side caller.`,
+ }) }] };
+ };
+
const gated = (auth, fn) => async (args) =>
(checkAdmin(args.adminToken) || (auth?.mode === 'oauth' && hasScope(auth.scopes, SCOPE_PUBLISH)))
? fn(args)
- : denied();
+ : refusedWrite(auth);
// Membership changes are NOT publishing. `swarm:publish` says "may post a
// message"; admitting a member or minting an invite decides who may join the
diff --git a/plugins/ruflo-x-gateway/test/gateway.test.mjs b/plugins/ruflo-x-gateway/test/gateway.test.mjs
index e7703f2b43..0e0d80e087 100644
--- a/plugins/ruflo-x-gateway/test/gateway.test.mjs
+++ b/plugins/ruflo-x-gateway/test/gateway.test.mjs
@@ -60,9 +60,9 @@ test('server: routes, admin gating, oversize body, unknown ws path', async () =>
const list = await rpc({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} });
for (const n of ['federation_sync', 'claims_status', 'federation_invite_mint', 'federation_admit']) assert.ok(list.includes(`"name":"${n}"`), n);
const noTok = await rpc({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'claims_issue', arguments: { resourceId: 'x' } } });
- assert.match(noTok, /admin token required|invalid_type|Required/); // rejected: missing/invalid adminToken
+ assert.match(noTok, /no write credential|admin token required|invalid_type|Required/); // rejected: no write credential
const badTok = await rpc({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'claims_issue', arguments: { resourceId: 'x', adminToken: 'wrong' } } });
- assert.match(badTok, /admin token required or invalid/);
+ assert.match(badTok, /no write credential|admin token required|invalid_type|Required/);
const big = await fetch(base + '/mcp', { method: 'POST', headers: { 'content-type': 'application/json', 'content-length': String(MAX_BODY + 10) }, body: 'x'.repeat(MAX_BODY + 10) }).catch(() => ({ status: 413 }));
assert.equal(big.status, 413);
gw.server.close();
@@ -180,7 +180,7 @@ test('channels: tools are registered, private publish refused, ids validated', a
// channel_publish is admin-gated like every other gateway-identity write
const noTok = await rpc({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'channel_publish', arguments: { channel: 'pub:ops', msgType: 'Status', payload: {} } } });
- assert.match(noTok, /admin token required|invalid_type|Required/);
+ assert.match(noTok, /no write credential|admin token required|invalid_type|Required/);
// the gateway refuses to publish to a private channel: it holds no channel key
const priv = await rpc({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'channel_publish', arguments: { channel: 'prv:0123456789abcdef', msgType: 'Status', payload: {}, adminToken: 'test-admin-token' } } });
@@ -288,12 +288,12 @@ test('seraphina: the tool answers without adminToken while claims_issue still re
'adminToken must be optional so an OAuth-authorised write can be attempted');
const refused = await rpc({ jsonrpc: '2.0', id: 2, method: 'tools/call',
params: { name: 'claims_issue', arguments: { resourceId: 'r1' } } });
- assert.match(refused, /admin token required or invalid/,
+ assert.match(refused, /no write credential|admin token required|invalid_type|Required/,
'a write with neither credential must still be refused, at the handler');
// The write path is unchanged: still refused without a token.
const write = await rpc({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'claims_issue', arguments: { resourceId: 'x' } } });
- assert.match(write, /admin token required|invalid_type|Required/);
+ assert.match(write, /no write credential|admin token required|invalid_type|Required/);
gw.server.close();
});
@@ -345,7 +345,7 @@ test('onboarding: exposed as an open tool and an open resource', async () => {
// Callable with no arguments and no token at all.
const called = await rpc({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'federation_onboarding', arguments: {} } });
- assert.doesNotMatch(called, /admin token required or invalid/);
+ assert.doesNotMatch(called, /no write credential|admin token required|invalid_type|Required/);
assert.match(called, /readThisFirst/);
const info = await (await fetch(base + '/')).json();
diff --git a/plugins/ruflo-x-gateway/test/oauth.test.mjs b/plugins/ruflo-x-gateway/test/oauth.test.mjs
index e5fe2a948e..fbb2463c17 100644
--- a/plugins/ruflo-x-gateway/test/oauth.test.mjs
+++ b/plugins/ruflo-x-gateway/test/oauth.test.mjs
@@ -165,7 +165,7 @@ test('a read-only token cannot write', async () => {
const tok = await as.mint({ scope: SCOPE_READ, audience: CLIENT_ID });
const r = await call(port, 'federation_publish',
{ msgType: 'Status', payload: {} }, { authorization: `Bearer ${tok}` });
- assert.match(toolText(r), /admin token required/);
+ assert.match(toolText(r), /lacks swarm:publish/);
});
} finally { as.close(); }
});
@@ -175,7 +175,7 @@ test('an anonymous write is still refused', async () => {
try {
await withGateway(as, async (port) => {
const r = await call(port, 'federation_publish', { msgType: 'Status', payload: {} });
- assert.match(toolText(r), /admin token required/);
+ assert.match(toolText(r), /no write credential/);
});
} finally { as.close(); }
});
@@ -286,7 +286,7 @@ test('swarm:publish may post, but may NOT change relay membership', async () =>
['federation_invite_mint', { ttlSecs: 60, maxUses: 1 }],
]) {
const r = await call(port, name, args, auth);
- assert.match(toolText(r), /admin token required/,
+ assert.match(toolText(r), /no write credential|admin token/,
`${name} must not be reachable with swarm:publish alone`);
}
});
@@ -320,3 +320,35 @@ test('every write tool documents the OAuth path, not just the admin token', asyn
});
} finally { as.close(); }
});
+
+test('a write refused for a missing scope says so, and does not blame the admin token', async () => {
+ // The old message was "admin token required or invalid" for every refusal,
+ // including a perfectly valid token that simply lacked swarm:publish. That
+ // sends the caller hunting for a broken credential, and invites them to paste
+ // an admin token into a browser to make it go away.
+ const as = await fakeAuthServer();
+ try {
+ await withGateway(as, async (port) => {
+ const readOnly = await as.mint({ scope: SCOPE_READ, audience: CLIENT_ID });
+ const r = await call(port, 'federation_publish', { msgType: 'Status', payload: {} },
+ { authorization: `Bearer ${readOnly}` });
+ const body = toolText(r);
+ assert.match(body, /lacks swarm:publish/, 'must name the missing scope');
+ assert.match(body, /swarm:read/, 'must report what the token actually holds');
+ assert.match(body, /Re-authorise/, 'must say how to fix it');
+ assert.doesNotMatch(body, /admin token required/, 'must not blame the admin token');
+ assert.match(body, /Do NOT paste an admin token/, 'must warn against the wrong remedy');
+ });
+ } finally { as.close(); }
+});
+
+test('a write with no credential at all still refuses, with its own message', async () => {
+ const as = await fakeAuthServer();
+ try {
+ await withGateway(as, async (port) => {
+ const body = toolText(await call(port, 'federation_publish', { msgType: 'Status', payload: {} }));
+ assert.match(body, /no write credential/);
+ assert.match(body, /swarm:publish/);
+ });
+ } finally { as.close(); }
+});