🌊 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.mjsindex 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 thediff --git a/plugins/ruflo-x-gateway/test/gateway.test.mjs b/plugins/ruflo-x-gateway/test/gateway.test.mjsindex 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 credentialconst 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 writeconst 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 keyconst 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.mjsindex 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(); }+});