fix(railway): report restricted environments instead of a consent error (#22214)

## 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 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-18 15:26:56 -06:00
1 parent 01d74a52a2
commit 35563b7de5
3 files changed
+80 -2

No files matched your search

+45
View File
@@ -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<typeof fixture>) => 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);
+29 -2
View File
@@ -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<string, any>): Promise<boolean> {
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<string, any>) {
const data = await query(RAILWAY_QUERIES.target, { projectId: args.projectId, environmentId: args.environmentId, serviceId: args.serviceId });
let data: Record<string, any>;
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);
}