Files
PaperClipAI/doc/connections/RAILWAY.md
T
DottaandClaude Opus 5.5 35563b7de5 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>
2026-11-18 15:26:56 -06:00

15 KiB
Raw Blame History

Railway

Updated: 2026-09-16. Status: implementation review; live provider qualification outstanding.

Railway appears in Apps and uses Paperclip's shared remote-MCP OAuth connection, vault, catalog, grants, policies, gateway, and audit trail. It is a resource connection, not Paperclip sign-in. No plugin or database migration is required.

Connect and use

  1. Open Apps → Railway → Connect.
  2. Sign in to Railway and choose the workspaces offered on its consent page. If dynamic registration is rejected, supply a registered Railway OAuth client in the existing customer-client setup. Local loopback consent has succeeded; HTTPS and customer-client registration still require qualification. Do not supply a Railway project token to the hosted MCP endpoint.
  3. Review the discovered actions. Install the connection for selected agents. Active actions start Allowed under the current product default. Choose Ask first for deployment actions or commands that need operator review.
  4. Refresh actions to check API access. Paperclip uses the hosted list-workspaces read to discover a workspace, then makes a bounded project query with that explicit workspace ID and the actual OAuth credential before adding direct tools. Account-wide project queries are not valid probes for workspace-scoped consent. Railway documents OAuth access to GraphQL, but a hosted-MCP token is not assumed to have a suitable audience. Rejection leaves hosted tools available and direct operations unavailable. No other credential is used as a fallback.
  5. Have an agent list projects, services and environments through the gateway, then inspect an explicit service/deployment target. Never paste OAuth tokens or private SSH keys into agent prompts or runtime configuration.

Use a public HTTPS Paperclip origin, or a loopback HTTP origin such as http://localhost:3100. The shared callback is /api/tools/oauth/callback. The configured canonical auth origin controls the callback. A plain HTTP tailnet hostname is not loopback; use HTTPS or change the local canonical origin before connecting. Loopback consent succeeded locally; HTTPS still needs live proof.

Capabilities and policy

Action Scope and limits Classification
Hosted project/service listing and feature-flag reads Actual discovered schemas; provider credential scope Read for reviewed names
Other hosted actions Actual discovered schemas; provider credential scope Write or destructive
Hosted railway-agent and accept-deploy Disabled at discovery and denied at dispatch, including normalized aliases Destructive; unavailable
paperclip-railway-list-projects, list-services, list-environments Explicit workspace ID for projects, project ID for services/environments; 1–100 results per page, cursor ≤512 characters Read
service-status, list-deployments, deployment-status Explicit project/environment/service IDs; deployment ID where applicable Read
read-logs Build/runtime; ≤500 lines; time bounds/filter; ≤64 KiB of log entries Read; sensitive application data
redeploy, restart, rollback Exact deployment membership checked before mutation Destructive
deploy-revision Unavailable: the provider mutation cannot atomically bind the approved repository and commit; old catalog entries and calls are blocked Destructive; unavailable
run-command Exact running deployment/container instance, ≤60 seconds, ≤64 KiB combined output Destructive; broad privileged access

Direct tool names have the paperclip-railway- prefix. Railway may not shadow this reserved namespace. These are fixed first-party gateway operations, not a REST catalog entry or arbitrary GraphQL passthrough. GraphQL responses have a 1 MiB hard limit, redirects are refused, provider error bodies are not surfaced, and deployment mutations are never automatically retried. After a timeout or ambiguous error, inspect status before retrying. Redeploy returns the provider's resulting deployment ID; restart/rollback use the provider's boolean result and exact target ID rather than inventing a new deployment ID.

Railway enforces the workspace/account permissions granted by consent. The project/environment/service labels in the catalog are not local allowlists. Dedicated operations verify that all supplied IDs belong to the same target. They do not narrow a workspace-wide credential to one service. Use provider access controls and explicit Paperclip action policies to constrain authorization. Hosted tool arguments and filters do not establish authorization boundaries.

The broad hosted Railway agent can perform multiple internal operations; a request to read logs does not make it read-only. Staged changes accepted by accept-deploy cannot be bound to the exact changes reviewed here. Both are blocked by a narrow provider policy. Other providers and global defaults are unchanged. New or changed Railway schemas are quarantined after initial discovery, including reconnect flows that normally enable newly discovered actions.

Source deployment (paperclip-railway-deploy-revision) is also blocked. The serviceInstanceDeployV2 mutation accepts a commit SHA but cannot atomically verify the approved repository. A separate repository check can race a provider configuration change. Paperclip therefore offers 11 direct actions and no source deployment action. Calls saved by an older server are denied before upstream execution, including normalized aliases; refreshing actions marks their catalog entries disabled. Source deployment requires an atomic provider binding before it can be re-enabled. Redeploy uses an existing deployment's previous image.

Container access

The connection's Permissions page includes Container access:

  1. Select an authorization and generate a dedicated Ed25519 key.
  2. Register its public key in the Railway account associated with that authorization. Workspace key management can require workspace-admin rights.
  3. Supply an independently verified ssh.railway.com known_hosts line. A key collected over an untrusted connection is not verification. No trust-on-first-use or host-key-check bypass is provided.
  4. Enable access, then grant the Run command action to trusted agents.

The private key stays in the instance vault, attached to one exact grant. Personal keys retain their owner binding. Each command resolves that grant's key after normal company/run/grant/policy checks. It uses a fresh temporary directory, 0600 key files, a fixed system OpenSSH executable, a minimal environment, and no ambient SSH agent, user configuration, host directory, forwarding, or shared control socket. Files are removed on success, error, timeout and cancellation. The process must confirm remote command completion; SSH exit code zero alone is insufficient. Noninteractive commands receive no stdin.

SSH connects to a deployed service container, not the underlying Railway host. The SSH username is a deployment instance ID, checked against that deployment. Commands can read secrets, change data, and make network calls. They can accomplish mutations internally even if a dedicated deployment action is Ask first. Per-tool policy cannot approve each shell sub-operation. Log and command output is sensitive; known credentials and recognized secret patterns are redacted, but arbitrary application secrets cannot all be recognized.

The default gateway budget includes the requested command timeout plus ten seconds for target checks, capped at sixty seconds. An explicit caller deadline takes precedence and can stop the command earlier. Timeout/cancellation terminates the local SSH connection. Remote child process termination is not guaranteed. Persistent interactive sessions, file upload, unrestricted Railway CLI use and arbitrary local workspace deployment are out of scope. Source deployment is unavailable as described above.

Removing the container key deletes local private material and its grant binding in one transaction, including for revoked grants or disconnected connections. Reconnect preserves the key binding. Also remove the public key in Railway to revoke provider-side enrollment. Revoking the grant blocks new upstream executions. The shared gateway can replay already completed results from invocation history; a replay does not contact Railway. Revocation does not recall commands already running remotely.

Protocol qualification record

Public probes and official documentation checked 2026-09-13:

Property Evidence / remaining qualification
Endpoint Exact https://mcp.railway.com or root slash; other paths, query strings and lookalike hosts are not bridged
Transport Provider documents hosted MCP; unauthenticated Streamable HTTP initialize POST with JSON/SSE Accept returns HTTP 401
Challenge Bearer realm="mcp", resource_metadata="https://mcp.railway.com/.well-known/oauth-protected-resource"
Protected resource Resource https://mcp.railway.com, issuer https://backboard.railway.com, header bearer
Authorization /oauth/auth?resource=https%3A%2F%2Fbackboard.railway.com on issuer; generic OAuth flow binds the requested MCP resource
Token / registration /oauth/token, /oauth/register advertised on issuer
Revocation endpoint Not advertised in observed metadata; local gateway revocation is enforced independently
Registration DCR advertised, customer client supported by docs; no CIMD advertisement. Loopback automatic consent succeeded; public HTTPS and customer-client consent unproven
PKCE S256 advertised and exercised by deterministic fixture
Scopes Advertised: openid, profile, email, offline_access, workspace:member. Request openid/offline_access/workspace:member with prompt=consent
Refresh Refresh grant advertised; docs require offline_access and explicit consent. Fixture covers failure; live refresh pending
Tool schemas Live tools/list captured locally: 46 hosted actions, including narrow get-status and get-logs; 44 active after the two blocked opaque actions
Plan / approval Account and appropriate workspace permissions required; plan limits, app approval and SSH enrollment permissions need verification on the test account

Sources: hosted MCP, OAuth, OAuth tokens, consent/scopes, GraphQL, SSH, and official CLI GraphQL schema and commands. Brand marks were sanitized from the inline SVG at Railway's official homepage on 2026-09-13. The original mark contains the Railway train silhouette; the dark variant changes only its fill for contrast. The public manifest contains runtime artwork paths; this record retains source provenance.

Recovery

  • Cancelled consent: use Connect again; cancelled callback state cannot be reused.
  • Expired/revoked OAuth or refresh failure: reconnect the affected authorization. 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. New direct actions remain quarantined until reviewed.
  • Missing service or mismatched IDs: list current resources and use one consistent project/environment/service/deployment target. No mutation precedes validation.
  • Railway unavailable/rate-limited: wait, inspect status, then retry deliberately.
  • SSH not configured or host-key mismatch: verify enrollment and host identity through the provider; update the connection setup. Do not disable host checks.

Verification and release gate

railway.test.ts covers fixed API dispatch, bounds, errors, target checks and credential redaction, including source-deployment denial with no upstream request. railway-ssh.test.ts covers isolated SSH state, completion, output limits, timeout, cancellation and cleanup. railway-connection.test.ts uses observed metadata with synthetic provider responses to exercise the shared OAuth/catalog/grant/gateway lifecycle and denies retired source-deployment catalog entries before refresh. The fixture explicitly does not claim an authenticated provider tool capture. Shared generic MCP suites cover callback state/issuer binding, consent cancellation and credential handling.

Independent security review accepted the architecture for local preview on 2026-09-13. The operator subsequently completed local consent. A follow-up live check reproduced HTTP 200 with Not Authorized for account-wide projects, while the same credential succeeded with an explicit workspace. After the fix, catalog refresh reported API access available, 44 active hosted actions, two disabled actions, and 12 new direct actions quarantined for review. Direct project, service and environment reads succeeded; the inspected project had no services, so deployment status and logs could not be exercised. No provider mutation ran. That preview included source deployment; the 2026-09-16 security fix removes it and blocks existing entries, leaving 11 supported direct actions.

Full release acceptance remains outstanding. The operator must identify a disposable service and deployment for the remaining checks. Required live proof: HTTPS and supported loopback consent; actual catalog capture; agent gateway read/logs; rejected Ask-first write with no upstream mutation; approved scoped redeploy and resulting deployment; refresh/reconnect; revoked grant denial; enrolled SSH key, harmless command, wrong-target denial, timeout/cancellation, key removal and provider cleanup. The successful direct read diagnostic does not replace the required agent-through-gateway proof.

Regenerate with pnpm connections:ingest-app-definitions --definitions-only when the external research corpus is unavailable. This preserves its ingestion report. Run targeted suites, shared definitions, pnpm check:token-gates, then the full repository checks before release. See the verification record for actual results.

Rollback: remove Railway's curated slug/promotion and setup panel to stop new setup; disable direct runtime dispatch if needed. Preserve connection rows, grants, vault records and the generic remote-MCP path. Existing connections must remain recoverable and disconnectable. Remove registered SSH keys deliberately; do not delete provider projects or application data as rollback.