From 35563b7de5e01347a82de39cdad3970a1ea2f1ce Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:26:56 -0600 Subject: [PATCH] fix(railway): report restricted environments instead of a consent error (#22214) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Railway connection gives agents governed deployment tools, such as `list-deployments` > - Railway Environment RBAC lets non-admin members see a restricted environment, but Railway denies reads of its services, deployments, and logs > - The client maps this denial to `railway_api_authorization_required` and tells the user to reconnect or to use IDs from a consented workspace > - That advice is wrong for this case: workspace consent is correct, and reconnecting does not change the result > - This pull request identifies the restricted environment and reports the correct remedy > - The benefit is that agents and operators get a clear, actionable error instead of an incorrect reconnect loop ## Linked Issues or Issue Description (B) No public issue exists. Bug description: **What happened?** An agent called `paperclip-railway-list-deployments` for a service. In the same session, `list-projects`, `list-services`, and `list-environments` succeeded for the same project. The deployment-history call failed every time with `railway_api_authorization_required` and the message "Use IDs from a workspace selected during consent, or reconnect". The project-level reads prove that workspace consent is correct. The denied environment is restricted for the connected member, so the message sends the user to the wrong fix. **Expected behavior** When Railway denies the environment-scoped target check because the environment is restricted, the tool must report a distinct error. The error must say that a Railway project admin must grant access. It must not tell the user to reconnect. **Steps to reproduce** 1. Connect Railway with a member (non-admin) account in a workspace that has a restricted environment. 2. Call `paperclip-railway-list-environments` for the project. The restricted environment is in the list. 3. Call `paperclip-railway-list-deployments` (or `service-status`) for a service in that environment. 4. Railway returns `Not Authorized`, and Paperclip reports a workspace consent error. **Paperclip version or commit** `master` at 8282d386da. ## What Changed - `server/src/services/railway.ts`: When the target query fails with an authorization denial, the client reads the project's environments with `canAccess`. If the requested environment has `canAccess: false`, the client throws `railway_environment_restricted` (HTTP 403) with the admin-access remedy. In all other cases, the client throws the original error. If the access check fails, the client also throws the original error. The access check is a read query. No mutation runs after a denied target check. - `server/src/services/railway.ts`: `list-environments` now returns `canAccess` for each environment, so agents can choose an accessible environment before they call a target tool. - `server/src/__tests__/railway.test.ts`: Adds a regression test for the restricted, accessible, and unknown cases. - `doc/connections/RAILWAY.md`: Adds a recovery entry for the new error code. ## Verification - Failing before the fix: `cd server && npx vitest run src/__tests__/railway.test.ts`. The new test "reports a restricted environment instead of a workspace consent error when Railway denies the target" failed. It expected `code: "railway_environment_restricted"`, but it received `code: "railway_api_authorization_required"`. The other 28 tests passed. - Passing after the fix: the same file passes (29/29). - Related suites pass: `npx vitest run src/__tests__/railway.test.ts src/__tests__/railway-connection.test.ts src/__tests__/railway-ssh.test.ts src/__tests__/connector-tool-policy.test.ts` (4 files, 63 tests). - Scoped `tsc --noEmit` with the server `tsconfig.json` for the changed files passes. - Not run: the full server typecheck and `pnpm verify`. In the test sandbox, they used more than the 8 GB memory limit. CI must confirm them. - Public reference for the provider behavior: https://docs.railway.com/enterprise/environment-rbac ## Risks - Low risk. The change applies only after Railway has already denied the target check. It adds one read query in that case. - If Railway removes or renames `canAccess`, the access check fails, and the client throws the original error, as before this change. - The access check reads the first 100 environments of the project. If a project has more environments, the client throws the original error. - `list-environments` output gets one more field. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), agentic coding with tool use (shell, file edits, test execution). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 5.5 --- doc/connections/RAILWAY.md | 6 ++++ server/src/__tests__/railway.test.ts | 45 ++++++++++++++++++++++++++++ server/src/services/railway.ts | 31 +++++++++++++++++-- 3 files changed, 80 insertions(+), 2 deletions(-) diff --git a/doc/connections/RAILWAY.md b/doc/connections/RAILWAY.md index a71c6332c9d..fd69df0c8cc 100644 --- a/doc/connections/RAILWAY.md +++ b/doc/connections/RAILWAY.md @@ -164,6 +164,12 @@ manifest contains runtime artwork paths; this record retains source provenance. Raw provider error descriptions and tokens are not shown. - Insufficient API permissions: verify workspace access, reconnect, then refresh actions. Direct tools stay unavailable until the API probe succeeds. +- Restricted environment (`railway_environment_restricted`): Railway Environment + RBAC lets non-admin members see a restricted environment but not read its + services, deployments or logs. When a target read is denied, the client checks + `canAccess` and reports this code instead of a consent error. Ask a project + admin for access; reconnecting does not help. `list-environments` returns + `canAccess` for each environment. - An older preview reported a generic deployment error immediately after consent: its API probe omitted the workspace ID. Refresh actions with the current server; reconnect is unnecessary when the selected workspace is already authorized. diff --git a/server/src/__tests__/railway.test.ts b/server/src/__tests__/railway.test.ts index 760aa55e5e0..00dffe235d9 100644 --- a/server/src/__tests__/railway.test.ts +++ b/server/src/__tests__/railway.test.ts @@ -45,6 +45,51 @@ describe("Railway governed operations", () => { await expect(f.client.probe(target.projectId)).rejects.toMatchObject({ code: "railway_api_authorization_required", status: 403, message: expect.stringContaining("workspace selected during consent") }); expect(f.request).toHaveBeenCalledTimes(1); }); + it("reports a restricted environment instead of a workspace consent error when Railway denies the target", async () => { + const denied = () => Response.json({ errors: [{ message: "Not Authorized" }], data: null }); + const other = "66666666-6666-4666-8666-666666666666"; + const page = (nodes: { id: string; canAccess: boolean }[], endCursor?: string) => Response.json({ data: { project: { id: target.projectId, environments: { edges: nodes.map((node) => ({ node: { ...node, name: "env", projectId: target.projectId } })), pageInfo: { hasNextPage: !!endCursor, endCursor: endCursor ?? null } } } } }); + const queries = (f: ReturnType) => f.request.mock.calls.map(([, init]) => JSON.parse(String(init.body))); + const { deploymentId: _, ...ids } = target; + + const restricted = fixture((q) => q === RAILWAY_QUERIES.target ? denied() : undefined); + restricted.request.mockImplementation(async (_url, init) => { + const { query, variables } = JSON.parse(String(init.body)); + if (query === RAILWAY_QUERIES.target) return denied(); + return variables.after ? page([{ id: target.environmentId, canAccess: false }]) : page([{ id: other, canAccess: true }], "next"); + }); + await expect(restricted.client.call("paperclip-railway-list-deployments", ids)).rejects.toMatchObject({ code: "railway_environment_restricted", status: 403, message: expect.stringContaining("restricted") }); + expect(queries(restricted).map((body) => [body.query, body.variables.after])).toEqual([[RAILWAY_QUERIES.target, undefined], [RAILWAY_QUERIES.environments, undefined], [RAILWAY_QUERIES.environments, "next"]]); + + const http403 = fixture((q) => q === RAILWAY_QUERIES.target ? new Response(null, { status: 403 }) : page([{ id: target.environmentId, canAccess: false }])); + await expect(http403.client.call("paperclip-railway-service-status", ids)).rejects.toMatchObject({ code: "railway_environment_restricted" }); + + const accessible = fixture((q) => q === RAILWAY_QUERIES.target ? denied() : page([{ id: target.environmentId, canAccess: true }])); + await expect(accessible.client.call("paperclip-railway-service-status", ids)).rejects.toMatchObject({ code: "railway_api_authorization_required" }); + const unknown = fixture((q) => q === RAILWAY_QUERIES.target || q === RAILWAY_QUERIES.environments ? denied() : undefined); + await expect(unknown.client.call("paperclip-railway-restart", target)).rejects.toMatchObject({ code: "railway_api_authorization_required" }); + expect(queries(unknown).every((body) => !body.query.startsWith("mutation"))).toBe(true); + + const revoked = fixture((q) => q === RAILWAY_QUERIES.target ? new Response(null, { status: 401 }) : page([{ id: target.environmentId, canAccess: false }])); + await expect(revoked.client.call("paperclip-railway-service-status", ids)).rejects.toMatchObject({ code: "railway_api_authorization_required", status: 401 }); + expect(revoked.request).toHaveBeenCalledTimes(1); + + const aborted = fixture(); + aborted.request.mockImplementation(async (_url, init) => { + if (JSON.parse(String(init.body)).query === RAILWAY_QUERIES.target) return denied(); + aborted.controller.abort(new Error("cancelled")); + throw new Error("network"); + }); + await expect(aborted.client.call("paperclip-railway-service-status", ids)).rejects.toThrow("cancelled"); + }); + + it("returns each environment's access flag from list-environments", async () => { + const edges = [{ node: { id: target.environmentId, name: "production", projectId: target.projectId, canAccess: false } }, { node: { id: target.serviceId, name: "staging", projectId: target.projectId, canAccess: true } }]; + const f = fixture(() => Response.json({ data: { project: { id: target.projectId, environments: { edges, pageInfo: { hasNextPage: false, endCursor: null } } } } })); + await expect(f.client.call("paperclip-railway-list-environments", { projectId: target.projectId })).resolves.toMatchObject({ project: { environments: { edges: [{ node: { canAccess: false } }, { node: { canAccess: true } }] } } }); + expect(JSON.parse(String(f.request.mock.calls[0][1].body)).query).toBe(RAILWAY_QUERIES.environments); + }); + it("requires exact provider identity and treats shell and remote agents as privileged", () => { expect(isRailwayEndpoint("https://mcp.railway.com/")).toBe(true); for (const url of ["https://mcp.railway.com/path", "https://mcp.railway.com?token=x", "https://mcp.railway.com.evil.test", "http://mcp.railway.com"]) expect(isRailwayEndpoint(url)).toBe(false); diff --git a/server/src/services/railway.ts b/server/src/services/railway.ts index 463a82f97a7..2bc9c024a8f 100644 --- a/server/src/services/railway.ts +++ b/server/src/services/railway.ts @@ -135,7 +135,7 @@ const instanceFields = "id environmentId serviceId serviceName source { repo } l export const RAILWAY_QUERIES = { projects: `query PaperclipRailwayProjects($workspaceId:String!,$first:Int!,$after:String) { projects(workspaceId:$workspaceId,first:$first,after:$after) { edges { node { id name workspaceId } } ${pageInfo} } }`, services: `query PaperclipRailwayServices($projectId:String!,$first:Int!,$after:String) { project(id:$projectId) { id services(first:$first,after:$after) { edges { node { id name projectId } } ${pageInfo} } } }`, - environments: `query PaperclipRailwayEnvironments($projectId:String!,$first:Int!,$after:String) { project(id:$projectId) { id environments(first:$first,after:$after) { edges { node { id name projectId } } ${pageInfo} } } }`, + environments: `query PaperclipRailwayEnvironments($projectId:String!,$first:Int!,$after:String) { project(id:$projectId) { id environments(first:$first,after:$after) { edges { node { id name projectId canAccess } } ${pageInfo} } } }`, target: `query PaperclipRailwayTarget($projectId:String!,$environmentId:String!,$serviceId:String!) { project(id:$projectId) { id } environment(id:$environmentId) { id projectId } service(id:$serviceId) { id projectId } serviceInstance(environmentId:$environmentId,serviceId:$serviceId) { ${instanceFields} } }`, deployment: `query PaperclipRailwayDeployment($deploymentId:String!) { deployment(id:$deploymentId) { ${deploymentFields} instances { id } } }`, deployments: `query PaperclipRailwayDeployments($input:DeploymentListInput!,$first:Int!,$after:String) { deployments(input:$input,first:$first,after:$after) { edges { node { ${deploymentFields} } } ${pageInfo} } }`, @@ -234,8 +234,35 @@ export function createRailwayClient(options: RailwayClientOptions) { return payload.data; } + async function environmentRestricted(args: Record): Promise { + try { + let after: string | undefined; + for (let page = 0; page < 10; page++) { + const data = await query(RAILWAY_QUERIES.environments, { projectId: args.projectId, first: 100, after }); + const environments = record(record(data.project).environments); + const match = Array.isArray(environments.edges) ? environments.edges.find((edge) => edge?.node?.id === args.environmentId) : undefined; + if (match) return match.node.canAccess === false; + const pageInfo = record(environments.pageInfo); + if (!pageInfo.hasNextPage || typeof pageInfo.endCursor !== "string") return false; + after = pageInfo.endCursor; + } + return false; + } catch (error) { + if (options.signal.aborted) throw error; + return false; + } + } + async function validateTarget(args: Record) { - const data = await query(RAILWAY_QUERIES.target, { projectId: args.projectId, environmentId: args.environmentId, serviceId: args.serviceId }); + let data: Record; + try { + data = await query(RAILWAY_QUERIES.target, { projectId: args.projectId, environmentId: args.environmentId, serviceId: args.serviceId }); + } catch (error) { + if (error instanceof RailwayError && error.code === "railway_api_authorization_required" && error.status === 403 && await environmentRestricted(args)) { + throw new RailwayError("railway_environment_restricted", "This Railway environment is restricted. The connected account can see it but cannot read its services, deployments, or logs. Ask a Railway project admin for access to the environment, or use an environment the account can access. Reconnecting does not change this.", 403); + } + throw error; + } if (data.project?.id !== args.projectId || data.environment?.id !== args.environmentId || data.environment?.projectId !== args.projectId || data.service?.id !== args.serviceId || data.service?.projectId !== args.projectId || data.serviceInstance?.environmentId !== args.environmentId || data.serviceInstance?.serviceId !== args.serviceId) { throw new RailwayError("railway_target_mismatch", "The service and environment do not belong to the selected Railway project.", 403); }