Files
PaperClipAI/server/src/services/environment-custom-image-terminal-sessions.ts
T
Devin FoleyandPaperclip bcac517f3b Add browser SSH terminal for custom image setup (#8911)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Environment sandboxes already support custom image creation and
refresh through a temporary SSH setup session.
> - The existing workflow makes operators copy an SSH command into an
external terminal before they can install packages or make image
changes.
> - That extra context switch is slower, easier to get wrong, and less
integrated with the setup session Paperclip already tracks.
> - This pull request adds an embedded browser SSH terminal for custom
image setup, so operators can start working in the target sandbox
directly from the environment configuration flow.
> - The implementation uses short-lived websocket attachment tokens,
session-lifetime SSH host-key pinning, and server-managed terminal
cleanup so the feature fits the existing setup-session boundary.
> - The benefit is a smoother custom image creation and refresh
experience without asking users to leave Paperclip for routine sandbox
setup work.

## Linked Issues or Issue Description

No public GitHub issue exists.

### Subsystem affected

Cross-cutting: `server/` custom image setup APIs and websocket handling,
`ui/` environment configuration UI, and shared custom image contracts.

### Problem or motivation

Custom image creation and refresh require an operator to open a separate
SSH client, paste the command shown by Paperclip, perform setup work,
then return to the browser to finish the image flow. This is functional
but awkward for a setup process that already starts and tracks a
temporary sandbox session.

### Proposed solution

Embed an SSH terminal in the custom image setup UI. When a setup session
exposes an SSH payload, Paperclip should open a browser terminal backed
by a server-side websocket session, let the operator run setup commands
in-place, and then close the terminal when setup is finished, cancelled,
expired, or disconnected.

### Alternatives considered

- Keep the existing copy/paste SSH command workflow. This remains a
fallback, but it does not streamline the common path.
- Put SSH credentials directly into websocket URLs. This was avoided so
terminal authentication can happen in an explicit first websocket auth
frame rather than in logged URLs.
- Trust the SSH host blindly for every reconnect. This PR instead pins
the observed host-key fingerprint for the setup-session lifetime.

### Roadmap alignment

This fits the roadmap theme of making agent workspaces usable in more
remote and sandboxed environments while preserving Paperclip's
control-plane model.

### Additional context

Public GitHub search did not find a duplicate issue or PR for `custom
image terminal ssh` in `paperclipai/paperclip`.

## What Changed

- Added server-side terminal session tracking for custom image setup
sessions, including connect-token issuance, websocket attachment,
expiry, resize, input, and shutdown handling.
- Added an embedded browser terminal to the custom image creation and
refresh flow when a setup session provides SSH connection details.
- Moved terminal token authentication out of the websocket URL and into
the first websocket JSON auth frame.
- Added SSH host-key SHA-256 pinning for each terminal session and
documented the provider convention for username-embedded SSH
credentials.
- Updated the custom image environment API and UI so the setup terminal
can open, reconnect, show status, authenticate, resize, and remain
active for the setup-session lifetime once attached.
- Kept custom image setup routes company-scoped and closed active
terminal sessions on setup finish/cancel.
- Added focused unit/integration/UI coverage for token expiry,
setup-session expiry, websocket close paths, host-key pinning, and
terminal session lifecycle behavior.
- Removed the generated lockfile delta from the PR; CI owns temporary
lockfile regeneration for manifest-changing PRs.

## Verification

- `pnpm exec vitest run
server/src/__tests__/server-startup-feedback-export.test.ts
server/src/__tests__/environment-custom-image-terminal-ws.test.ts
server/src/services/environment-custom-image-terminal-sessions.test.ts
server/src/__tests__/environment-custom-image-routes.test.ts
packages/shared/src/environment-custom-images.test.ts
ui/src/pages/CompanyEnvironments.test.tsx`
  - 6 test files passed
  - 58 tests passed
- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/ui typecheck`
- `pnpm --filter @paperclipai/server build`
- `pnpm --filter @paperclipai/ui build`
- `pnpm run typecheck:build-gaps`
- `git diff --check`
- Local sensitive-content scan over the PR diff using patterns for API
keys, private keys, private hostnames, local paths, token fields, and
credential-like strings.
- Findings were limited to removed URL-token code and synthetic test
placeholders such as `ssh-token-secret` and
`terminal-token-terminal-token-123456`.
- No real credentials, private hostnames, local filesystem paths, or
instance-local links were found.
- Remote PR checks were green after the implementation commit, including
Build, Typecheck + Release Registry, General tests, serialized server
suites, e2e, verify, Socket, Snyk, Superagent, and Greptile 5/5.
- Post-merge PR hardening on July 3, 2026: merged `origin/master` at
`47448721e` into the branch, resolved the `CompanyEnvironments.tsx`
import conflict, reran focused tests, server/UI typechecks, server/UI
builds, `pnpm run typecheck:build-gaps`, and `git diff --check`, scanned
the final diff for sensitive content, pushed `4b43558cc`, and confirmed
all remote checks plus Greptile 5/5 were green.
- PR metadata correction on July 3, 2026: changed the title/body framing
from bug-fix language to feature-request language. No source files
changed for this metadata-only update.

## Risks

- Moderate surface area because this adds websocket routing,
setup-session runtime state, package dependencies, and a new custom
image UI path.
- New websocket attachments still require valid short-lived tokens;
established terminal sessions remain bounded by setup-session expiry,
explicit finish/cancel, client close, or server shutdown.
- The terminal-session store is in-memory, so active terminal websocket
tokens and host-key pins do not survive server restarts.
- SSH host-key verification uses session-lifetime TOFU pinning because
the current provider payload does not expose a trusted host-key
fingerprint.
- The external SSH command remains important as a fallback if a browser,
proxy, or network environment cannot sustain the websocket terminal.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

OpenAI Codex, GPT-5 coding agent with shell/tool execution. Context
window size was not exposed in this runtime.

## 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
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-07-03 16:44:21 -07:00

354 lines
11 KiB
TypeScript

import { createHash, randomBytes, randomUUID } from "node:crypto";
import {
readFutureDate,
readNullableDate,
} from "./environment-custom-image-setup-session-utils.js";
const DEFAULT_TERMINAL_SESSION_TOKEN_TTL_MS = 5 * 60 * 1000;
const TERMINAL_SESSION_TOKEN_BYTES = 32;
export interface ParsedCustomImageSetupSshCommand {
username: string;
host: string;
port: number;
}
export type EnvironmentCustomImageTerminalPayloadValidationFailureCode =
| "unsupported_payload"
| "missing_command"
| "unsupported_command"
| "invalid_expiry"
| "expired_payload";
export type EnvironmentCustomImageTerminalPayloadValidationResult =
| {
ok: true;
ssh: ParsedCustomImageSetupSshCommand;
connectionExpiresAt: Date | null;
}
| {
ok: false;
status: 409 | 422;
code: EnvironmentCustomImageTerminalPayloadValidationFailureCode;
message: string;
};
export interface EnvironmentCustomImageTerminalSessionRecord {
id: string;
setupSessionId: string;
companyId: string;
environmentId: string;
provider: string;
connectionType: "ssh";
ssh: ParsedCustomImageSetupSshCommand;
hostKeySha256: string | null;
createdAt: Date;
connectExpiresAt: Date;
sessionExpiresAt: Date;
}
export interface MintedEnvironmentCustomImageTerminalSession {
token: string;
session: EnvironmentCustomImageTerminalSessionRecord;
}
interface StoredEnvironmentCustomImageTerminalSession {
tokenHash: string;
session: EnvironmentCustomImageTerminalSessionRecord;
}
function parsePort(value: string): number | null {
if (!/^\d{1,5}$/.test(value)) return null;
const port = Number(value);
return Number.isInteger(port) && port >= 1 && port <= 65_535 ? port : null;
}
function parseDestination(value: string): Pick<ParsedCustomImageSetupSshCommand, "username" | "host"> | null {
if (value.startsWith("-")) return null;
const parts = value.split("@");
if (parts.length !== 2) return null;
const [username, host] = parts;
if (!username || !host) return null;
if (!/^[^\s@/]+$/.test(username)) return null;
if (!/^[^\s@/:]+$/.test(host)) return null;
return { username, host };
}
export function parseCustomImageSetupSshCommand(command: string): ParsedCustomImageSetupSshCommand | null {
const tokens = command.trim().split(/\s+/).filter(Boolean);
if (tokens[0] !== "ssh") return null;
if (tokens.length === 2) {
const destination = parseDestination(tokens[1]!);
return destination ? { ...destination, port: 22 } : null;
}
if (tokens.length !== 4) return null;
if (tokens[1] === "-p") {
const port = parsePort(tokens[2]!);
const destination = parseDestination(tokens[3]!);
return port && destination ? { ...destination, port } : null;
}
if (tokens[2] === "-p") {
const destination = parseDestination(tokens[1]!);
const port = parsePort(tokens[3]!);
return port && destination ? { ...destination, port } : null;
}
return null;
}
function readConnectionPayload(payload: unknown): Record<string, unknown> | null {
return payload && typeof payload === "object" && !Array.isArray(payload)
? payload as Record<string, unknown>
: null;
}
export function validateCustomImageSetupSshPayload(
payload: unknown,
now: Date,
): EnvironmentCustomImageTerminalPayloadValidationResult {
const record = readConnectionPayload(payload);
if (!record || record.type !== "ssh") {
return {
ok: false,
status: 422,
code: "unsupported_payload",
message: "Setup session terminal connections require an SSH connection payload.",
};
}
const command = typeof record.command === "string" ? record.command.trim() : "";
if (!command) {
return {
ok: false,
status: 422,
code: "missing_command",
message: "Setup session SSH payload is missing a supported command.",
};
}
const ssh = parseCustomImageSetupSshCommand(command);
if (!ssh) {
return {
ok: false,
status: 422,
code: "unsupported_command",
message: "Setup session SSH payload uses an unsupported command shape.",
};
}
const connectionExpiresAt = readNullableDate(record.expiresAt);
if (record.expiresAt != null && !connectionExpiresAt) {
return {
ok: false,
status: 422,
code: "invalid_expiry",
message: "Setup session SSH payload has an invalid expiry.",
};
}
if (connectionExpiresAt && connectionExpiresAt.getTime() <= now.getTime()) {
return {
ok: false,
status: 409,
code: "expired_payload",
message: "Setup session SSH connection payload has expired.",
};
}
return { ok: true, ssh, connectionExpiresAt };
}
function hashTerminalSessionToken(token: string): string {
return createHash("sha256").update(token).digest("hex");
}
function minDate(dates: Date[]): Date {
return new Date(Math.min(...dates.map((date) => date.getTime())));
}
function toValidFutureDate(value: Date | string | null | undefined, now: Date): Date | null {
return readFutureDate(value, now);
}
function normalizeHostKeySha256(value: unknown): string | null {
if (typeof value !== "string") return null;
const normalized = value.trim();
return normalized && normalized.length <= 256 ? normalized : null;
}
export class EnvironmentCustomImageTerminalSessionStore {
private readonly sessionsById = new Map<string, StoredEnvironmentCustomImageTerminalSession>();
create(input: {
setupSessionId: string;
companyId: string;
environmentId: string;
provider: string;
ssh: ParsedCustomImageSetupSshCommand;
setupExpiresAt: Date | string;
connectionExpiresAt?: Date | string | null;
now?: Date;
}): MintedEnvironmentCustomImageTerminalSession {
const now = input.now ?? new Date();
this.cleanupExpired(now);
const setupExpiresAt = toValidFutureDate(input.setupExpiresAt, now);
if (!setupExpiresAt) {
throw new Error("Terminal sessions require a future setup session expiry.");
}
const candidateExpirations = [
new Date(now.getTime() + DEFAULT_TERMINAL_SESSION_TOKEN_TTL_MS),
setupExpiresAt,
toValidFutureDate(input.connectionExpiresAt, now),
].filter((date): date is Date => date !== null);
const connectExpiresAt = minDate(candidateExpirations);
const token = randomBytes(TERMINAL_SESSION_TOKEN_BYTES).toString("base64url");
const id = randomUUID();
const session: EnvironmentCustomImageTerminalSessionRecord = {
id,
setupSessionId: input.setupSessionId,
companyId: input.companyId,
environmentId: input.environmentId,
provider: input.provider,
connectionType: "ssh",
ssh: input.ssh,
hostKeySha256: null,
createdAt: now,
connectExpiresAt,
sessionExpiresAt: setupExpiresAt,
};
this.sessionsById.set(id, {
tokenHash: hashTerminalSessionToken(token),
session,
});
return { token, session };
}
get(input: { id: string; token: string }, now = new Date()): EnvironmentCustomImageTerminalSessionRecord | null {
if (!input.id || !input.token) return null;
const stored = this.sessionsById.get(input.id) ?? null;
if (!stored) return null;
if (stored.tokenHash !== hashTerminalSessionToken(input.token)) return null;
if (stored.session.connectExpiresAt.getTime() <= now.getTime()) {
this.sessionsById.delete(input.id);
return null;
}
return stored.session;
}
getById(id: string, now = new Date()): EnvironmentCustomImageTerminalSessionRecord | null {
if (!id) return null;
const stored = this.sessionsById.get(id) ?? null;
if (!stored) return null;
if (stored.session.sessionExpiresAt.getTime() <= now.getTime()) {
this.sessionsById.delete(id);
return null;
}
return stored.session;
}
verifyOrPinHostKey(input: { id: string; hostKeySha256: string }, now = new Date()): boolean {
const hostKeySha256 = normalizeHostKeySha256(input.hostKeySha256);
if (!input.id || !hostKeySha256) return false;
const stored = this.sessionsById.get(input.id) ?? null;
if (!stored) return false;
if (stored.session.sessionExpiresAt.getTime() <= now.getTime()) {
this.sessionsById.delete(input.id);
return false;
}
if (!stored.session.hostKeySha256) {
stored.session.hostKeySha256 = hostKeySha256;
return true;
}
return stored.session.hostKeySha256 === hostKeySha256;
}
delete(id: string): boolean {
if (!id) return false;
return this.sessionsById.delete(id);
}
deleteBySetupSessionId(setupSessionId: string): number {
if (!setupSessionId) return 0;
let removed = 0;
for (const [id, stored] of this.sessionsById) {
if (stored.session.setupSessionId !== setupSessionId) continue;
this.sessionsById.delete(id);
removed += 1;
}
return removed;
}
cleanupExpired(now = new Date()): number {
let removed = 0;
for (const [id, stored] of this.sessionsById) {
if (stored.session.sessionExpiresAt.getTime() <= now.getTime()) {
this.sessionsById.delete(id);
removed += 1;
}
}
return removed;
}
clear(): void {
this.sessionsById.clear();
}
}
export const environmentCustomImageTerminalSessionStore =
new EnvironmentCustomImageTerminalSessionStore();
export type EnvironmentCustomImageTerminalConnectionClose = (reason: string) => void;
export class EnvironmentCustomImageTerminalConnectionRegistry {
private readonly connectionsBySetupSessionId = new Map<string, Set<EnvironmentCustomImageTerminalConnectionClose>>();
add(input: {
setupSessionId: string;
close: EnvironmentCustomImageTerminalConnectionClose;
}): () => void {
const existing = this.connectionsBySetupSessionId.get(input.setupSessionId);
const connections = existing ?? new Set<EnvironmentCustomImageTerminalConnectionClose>();
connections.add(input.close);
if (!existing) {
this.connectionsBySetupSessionId.set(input.setupSessionId, connections);
}
return () => {
connections.delete(input.close);
if (connections.size === 0) {
this.connectionsBySetupSessionId.delete(input.setupSessionId);
}
};
}
closeBySetupSessionId(setupSessionId: string, reason: string): number {
const connections = this.connectionsBySetupSessionId.get(setupSessionId);
if (!connections) return 0;
let closed = 0;
for (const close of [...connections]) {
close(reason);
closed += 1;
}
return closed;
}
closeAll(reason: string): number {
let closed = 0;
for (const setupSessionId of [...this.connectionsBySetupSessionId.keys()]) {
closed += this.closeBySetupSessionId(setupSessionId, reason);
}
return closed;
}
clear(): void {
this.connectionsBySetupSessionId.clear();
}
}
export const environmentCustomImageTerminalConnectionRegistry =
new EnvironmentCustomImageTerminalConnectionRegistry();