mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +01:00
## 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>
354 lines
11 KiB
TypeScript
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();
|