mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-11 13:24:55 +01:00
feat(workspaces): sign the workspace login handoff and gate readiness (#11671)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Managed worktree services run isolated Paperclip instances with cloned databases. > - A reachable service was reported as ready even when its database, runtime identity, or login path was not usable. > - The first candidate added verified database seeding and managed repair in #11665. > - This pull request consolidates that candidate with signed login handoff and a complete readiness contract. > - Post-QA fixes close five defects in repair identity, repair responses, UI retry, seed journal handling, and seed-source trust. > - The benefit is a workspace that either opens safely or reports one accurate recovery action. ## Linked Issues or Issue Description No public GitHub issue exists for this work, so the problem is described here. **What happened** Managed workspace URLs could return HTTP 200 and report ready while login failed. QA also found cases where repair used the wrong instance identity, returned a generic error, left the UI stuck, rejected a safe journal lag, or trusted a mutable workspace manifest. **Expected behavior** Opening a ready workspace signs the board user in to the correct isolated instance. Provisioning and repair use a registered source and report a structured recovery state. **Actual behavior** Entry depended on a password copied into the clone. Several failure paths could publish stale readiness, hide the repair precondition, or trust state that the workspace could modify. **Additional context** This pull request includes the commits first published in #11665. That pull request keeps the original base head for review history. This consolidated pull request is the merge candidate. Related open readiness work includes #11575 and #11621. ## What Changed - Adds a short-lived, signed, single-use login ticket. It binds the user, workspace, instance, and runtime origin. - Exchanges the ticket through Better Auth. It creates the session and cookie through the supported adapter path. - Adds protected workspace readiness fields for the database, clone data, login handoff, seed phase, and runtime identity. - Fails readiness closed when the guest has no company or execution-workspace binding. - Binds ticket issuance to the exact cloned user and active company membership selected for the handoff. - Verifies every current active board identity through the exact-user handoff before publication or reuse. - Gates managed runtime publication on the readiness contract and the recorded worktree instance identity. - Refreshes runtime work products from the live runtime row after a port change. - Adds one workspace access card with ready, degraded, repairing, and failed states. - Uses the runtime response identity for repair. It returns structured repair precondition errors. - Lets a valid source journal lag converge during provisioning. - Binds seed and repair manifests to a source registered outside the agent-writable worktree. - Clears recovered UI errors so a successful retry can open the workspace. - Makes runtime tests register canonical sources and avoid ports owned by live host listeners. - Keeps Vitest on source suites when compiled `dist` trees exist. - Isolates CLI and adapter tests from ambient AWS and runtime API environment variables. - Preserves a 404 response for cross-company workspace ID lookups before runtime authorization. - Makes concurrent single-flight coverage independent of path-canonicalization scheduling order. ## Verification The following checks passed on the integrated head: ```sh pnpm -r typecheck pnpm build pnpm check:token-gates pnpm --filter @paperclipai/db check:migrations ``` - The server source lane passed 420 files and 4,953 tests. Five tests were skipped. - The CLI lane passed 57 files and 385 tests. - The database lane passed 26 files and 97 tests. - The shared package passed 58 files and 506 tests. - The adapter utility lane passed 640 tests. Four tests were skipped. - The Claude adapter passed 220 tests. One test was skipped. - The Codex adapter passed 323 tests. - The OpenClaw adapter passed 13 tests. - The OpenCode adapter passed 42 tests. - The plugin SDK passed 45 tests. - The workspace runtime suite passed 124 tests. - The caller-scoped readiness and handoff suite passed 52 tests. - The workspace provisioning shell suite passed 7 tests. - The runtime exposure suite passed 17 tests while live host mappings occupied fixed test ports. - `git diff --check` passed and the worktree is clean. The serialized route lane will run in GitHub CI with its normal shards. No deployment or active-workspace migration was performed. ## Risks - This is a medium-risk authentication and runtime-readiness change. - The login ticket uses exact origin, workspace, instance, and user binding. It has a short expiry and a one-time nonce. - Runtime publication is stricter. A real readiness, identity, per-user handoff, or control-plane database disagreement now blocks publication. - This pull request supersedes #11665 as the merge candidate. Close #11665 after this pull request merges. - No new database migration is included. The lockfile and workflow files are unchanged. - Deployment and active-workspace migration are intentionally outside this pull request. > 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 Claude Opus 5 (`claude-opus-5[1m]`), 1M context, extended thinking, tool use, and code execution produced the main candidate. OpenAI GPT-5 (`gpt-5`) through Codex, with agentic reasoning, tool use, and code execution, integrated the post-QA fixes and hardened the test gates. The Codex context-window size was not exposed. ## 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>
This commit is contained in:
DottaandPaperclip authored and GitHub committed
1 parent
6aaef2998f
commit
a2bf936f9a
59 files changed
+7754
-243
No files matched your search
@@ -876,6 +876,11 @@ export type {
|
||||
WorkspaceOperation,
|
||||
WorkspaceOperationPhase,
|
||||
WorkspaceOperationStatus,
|
||||
WorkspaceLoginHandoffTicketResponse,
|
||||
WorkspaceReadiness,
|
||||
WorkspaceReadinessProbeResult,
|
||||
WorkspaceReadinessState,
|
||||
WorkspaceSeedReadinessState,
|
||||
NormalizedWorkspaceFileAvailabilityQuery,
|
||||
WorkspaceFileAvailabilityQuery,
|
||||
WorkspaceFileAvailabilityRequest,
|
||||
@@ -1436,6 +1441,7 @@ export type {
|
||||
QuotaWindow,
|
||||
ProviderQuotaResult,
|
||||
} from "./types/index.js";
|
||||
export { WORKSPACE_READINESS_STATES } from "./types/index.js";
|
||||
export {
|
||||
COMPANY_SEARCH_EXTRACT_KINDS,
|
||||
COMPANY_SEARCH_EXTRACT_SCOPES,
|
||||
|
||||
@@ -407,6 +407,14 @@ export type {
|
||||
WorkspaceOperationPhase,
|
||||
WorkspaceOperationStatus,
|
||||
} from "./workspace-operation.js";
|
||||
export { WORKSPACE_READINESS_STATES } from "./workspace-readiness.js";
|
||||
export type {
|
||||
WorkspaceLoginHandoffTicketResponse,
|
||||
WorkspaceReadiness,
|
||||
WorkspaceReadinessProbeResult,
|
||||
WorkspaceReadinessState,
|
||||
WorkspaceSeedReadinessState,
|
||||
} from "./workspace-readiness.js";
|
||||
export type {
|
||||
NormalizedWorkspaceFileAvailabilityQuery,
|
||||
WorkspaceFileAvailabilityQuery,
|
||||
|
||||
@@ -3,6 +3,7 @@ export type WorkspaceOperationPhase =
|
||||
| "workspace_config_freshness"
|
||||
| "workspace_provision"
|
||||
| "workspace_runtime_provision"
|
||||
| "workspace_repair"
|
||||
| "workspace_teardown"
|
||||
| "worktree_cleanup"
|
||||
| "workspace_finalize";
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
/**
|
||||
* Workspace readiness contract (PAP-17572).
|
||||
*
|
||||
* Transport health ("the port answered") is not user readiness. A cloned
|
||||
* workspace is only usable when its own database is reachable, the seed
|
||||
* manifest reached a verified terminal state, representative cloned rows are
|
||||
* readable, the password-independent login handoff is configured, and the
|
||||
* instance/workspace/company identity matches the one the control plane expects.
|
||||
*
|
||||
* These fields ride on the *protected* health response only. Public health
|
||||
* stays redacted: an anonymous caller learns liveness, never which instance or
|
||||
* execution workspace answered.
|
||||
*/
|
||||
|
||||
export const WORKSPACE_READINESS_STATES = [
|
||||
/** The isolated database is still being restored. */
|
||||
"provisioning",
|
||||
/** Restore finished; the clone is being validated. */
|
||||
"validating",
|
||||
/** Every readiness signal agrees; the workspace can be opened. */
|
||||
"ready",
|
||||
/** Serving, but at least one readiness signal regressed after being ready. */
|
||||
"degraded",
|
||||
/** A managed repair is running right now. */
|
||||
"repairing",
|
||||
/** A terminal provisioning or repair failure needs an operator action. */
|
||||
"failed",
|
||||
] as const;
|
||||
|
||||
export type WorkspaceReadinessState = (typeof WORKSPACE_READINESS_STATES)[number];
|
||||
|
||||
/** Terminal state of the versioned seed manifest, or `unknown` for a legacy marker. */
|
||||
export type WorkspaceSeedReadinessState =
|
||||
| "pending"
|
||||
| "running"
|
||||
| "verified"
|
||||
| "failed"
|
||||
| "unknown"
|
||||
| "absent";
|
||||
|
||||
export interface WorkspaceReadiness {
|
||||
state: WorkspaceReadinessState;
|
||||
/** `SELECT 1` plus a readable migration journal on this instance's own database. */
|
||||
databaseReady: boolean;
|
||||
/** A representative cloned company/issue pair is readable. */
|
||||
cloneDataReady: boolean;
|
||||
/** A signing key and a resolvable cloned admin identity are both present. */
|
||||
authHandoffReady: boolean;
|
||||
/** Exact cloned user checked for a caller-scoped handoff probe, or null. */
|
||||
authHandoffUserId: string | null;
|
||||
seedState: WorkspaceSeedReadinessState;
|
||||
/** Last recorded seed phase, e.g. `restore` or `post_restore_validation`. */
|
||||
seedPhase: string | null;
|
||||
seedMode: "minimal" | "full" | null;
|
||||
/** Resolved instance identity of the process that answered, never a branch heuristic. */
|
||||
instanceId: string | null;
|
||||
/** Execution workspace this instance was provisioned for, when known. */
|
||||
executionWorkspaceId: string | null;
|
||||
/** Company whose cloned board this workspace serves, when known. */
|
||||
companyId: string | null;
|
||||
/** Phase that failed, so operators do not need host-shell archaeology. */
|
||||
failurePhase: string | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of the control plane's protected readiness probe against a managed
|
||||
* workspace runtime. `reason` is a stable machine code so the runtime gate and
|
||||
* the UI can branch without parsing prose.
|
||||
*/
|
||||
export type WorkspaceReadinessProbeResult =
|
||||
| { ok: true; readiness: WorkspaceReadiness }
|
||||
| {
|
||||
ok: false;
|
||||
reason:
|
||||
| "unreachable"
|
||||
| "http_error"
|
||||
| "unhealthy_payload"
|
||||
| "readiness_missing"
|
||||
| "not_ready"
|
||||
| "identity_mismatch";
|
||||
readiness: WorkspaceReadiness | null;
|
||||
detail: string | null;
|
||||
};
|
||||
|
||||
export interface WorkspaceLoginHandoffTicketResponse {
|
||||
/** Absolute URL that exchanges the ticket and redirects to the cloned board. */
|
||||
url: string;
|
||||
expiresAt: string;
|
||||
/** `handoff` for the signed path, `credentials` when only the fallback is available. */
|
||||
mode: "handoff" | "credentials";
|
||||
}
|
||||
@@ -0,0 +1,61 @@
|
||||
import fs from "node:fs";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
import { resolveCanonicalWorktreeSeedSource } from "./worktree-seed-source.js";
|
||||
|
||||
const cleanup: string[] = [];
|
||||
|
||||
function makeInstance(prefix: string, instanceId: string) {
|
||||
const cwd = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
|
||||
cleanup.push(cwd);
|
||||
const configDir = path.join(cwd, ".paperclip");
|
||||
const configPath = path.join(configDir, "config.json");
|
||||
fs.mkdirSync(configDir, { recursive: true });
|
||||
fs.writeFileSync(configPath, "{}\n");
|
||||
fs.writeFileSync(path.join(configDir, ".env"), `PAPERCLIP_INSTANCE_ID=${instanceId}\n`);
|
||||
return { cwd, configPath, instanceId };
|
||||
}
|
||||
|
||||
afterEach(() => {
|
||||
for (const dir of cleanup.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
describe("resolveCanonicalWorktreeSeedSource", () => {
|
||||
it("returns only the registered base workspace config", () => {
|
||||
const source = makeInstance("paperclip-seed-source-", "source-instance");
|
||||
const target = makeInstance("paperclip-seed-target-", "target-instance");
|
||||
|
||||
expect(resolveCanonicalWorktreeSeedSource({
|
||||
registeredBaseWorkspaceCwd: source.cwd,
|
||||
targetConfigPath: target.configPath,
|
||||
expectedTargetInstanceId: target.instanceId,
|
||||
manifestSource: { configPath: source.configPath, instanceId: source.instanceId },
|
||||
manifestTargetInstanceId: target.instanceId,
|
||||
})).toMatchObject({
|
||||
baseWorkspaceCwd: source.cwd,
|
||||
configPath: source.configPath,
|
||||
targetConfigPath: target.configPath,
|
||||
});
|
||||
});
|
||||
|
||||
it("fails closed without registration and when source equals target", () => {
|
||||
const target = makeInstance("paperclip-seed-same-target-", "target-instance");
|
||||
const diagnostic = { configPath: target.configPath, instanceId: target.instanceId };
|
||||
|
||||
expect(() => resolveCanonicalWorktreeSeedSource({
|
||||
targetConfigPath: target.configPath,
|
||||
expectedTargetInstanceId: target.instanceId,
|
||||
manifestSource: diagnostic,
|
||||
manifestTargetInstanceId: target.instanceId,
|
||||
})).toThrow(/not registered/);
|
||||
|
||||
expect(() => resolveCanonicalWorktreeSeedSource({
|
||||
registeredBaseWorkspaceCwd: target.cwd,
|
||||
targetConfigPath: target.configPath,
|
||||
expectedTargetInstanceId: target.instanceId,
|
||||
manifestSource: diagnostic,
|
||||
manifestTargetInstanceId: target.instanceId,
|
||||
})).toThrow(/same canonical file/);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,150 @@
|
||||
import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
|
||||
import path from "node:path";
|
||||
|
||||
export type WorktreeSeedSourceDiagnostic = {
|
||||
configPath?: unknown;
|
||||
instanceId?: unknown;
|
||||
};
|
||||
|
||||
export type CanonicalWorktreeSeedSource = {
|
||||
baseWorkspaceCwd: string | null;
|
||||
configPath: string;
|
||||
instanceId: string;
|
||||
targetConfigPath: string;
|
||||
targetInstanceId: string;
|
||||
};
|
||||
|
||||
function readInstanceId(configPath: string, label: "source" | "target"): string {
|
||||
const envPath = path.join(path.dirname(configPath), ".env");
|
||||
if (!existsSync(envPath)) {
|
||||
throw new Error(`Registered ${label} Paperclip config is missing its adjacent .env instance pointer.`);
|
||||
}
|
||||
const contents = readFileSync(envPath, "utf8");
|
||||
for (const rawLine of contents.split(/\r?\n/)) {
|
||||
const match = rawLine.match(
|
||||
/^\s*(?:export\s+)?PAPERCLIP_INSTANCE_ID\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s#]+))/,
|
||||
);
|
||||
const value = (match?.[1] ?? match?.[2] ?? match?.[3] ?? "").trim();
|
||||
if (value) return value;
|
||||
}
|
||||
throw new Error(`Registered ${label} Paperclip config has no PAPERCLIP_INSTANCE_ID binding.`);
|
||||
}
|
||||
|
||||
function canonicalRegularFile(filePath: string, label: string): string {
|
||||
const resolved = path.resolve(filePath);
|
||||
let canonical: string;
|
||||
try {
|
||||
canonical = realpathSync(resolved);
|
||||
} catch {
|
||||
throw new Error(`${label} does not exist at ${resolved}.`);
|
||||
}
|
||||
if (canonical !== resolved || lstatSync(resolved).isSymbolicLink()) {
|
||||
throw new Error(`${label} must be a canonical path and cannot use a symlink alias.`);
|
||||
}
|
||||
if (!lstatSync(canonical).isFile()) {
|
||||
throw new Error(`${label} is not a regular file at ${canonical}.`);
|
||||
}
|
||||
return canonical;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a worktree seed source without granting authority to the seed manifest.
|
||||
*
|
||||
* A managed caller supplies the project-workspace cwd from its server-owned row.
|
||||
* An operator may instead supply an explicit source config. When both are present,
|
||||
* the explicit path must still equal the registered project-workspace config.
|
||||
* Manifest source fields are diagnostic assertions only and can only make this
|
||||
* validation fail; they never select the returned source.
|
||||
*/
|
||||
export function resolveCanonicalWorktreeSeedSource(input: {
|
||||
registeredBaseWorkspaceCwd?: string | null;
|
||||
explicitSourceConfigPath?: string | null;
|
||||
targetConfigPath: string;
|
||||
expectedTargetInstanceId: string;
|
||||
manifestSource: WorktreeSeedSourceDiagnostic | null | undefined;
|
||||
manifestTargetInstanceId?: unknown;
|
||||
}): CanonicalWorktreeSeedSource {
|
||||
const registeredCwd = input.registeredBaseWorkspaceCwd?.trim();
|
||||
const explicitSource = input.explicitSourceConfigPath?.trim();
|
||||
if (!registeredCwd && !explicitSource) {
|
||||
throw new Error(
|
||||
"Worktree seed source is not registered. Managed boot requires a project workspace; manual boot requires --from-config.",
|
||||
);
|
||||
}
|
||||
|
||||
let canonicalBaseCwd: string | null = null;
|
||||
let registeredConfigPath: string | null = null;
|
||||
if (registeredCwd) {
|
||||
const resolvedRegisteredCwd = path.resolve(registeredCwd);
|
||||
try {
|
||||
canonicalBaseCwd = realpathSync(resolvedRegisteredCwd);
|
||||
} catch {
|
||||
throw new Error(`Registered base project workspace does not exist at ${resolvedRegisteredCwd}.`);
|
||||
}
|
||||
if (canonicalBaseCwd !== resolvedRegisteredCwd) {
|
||||
throw new Error("Registered base project workspace must be canonical and cannot use a symlink alias.");
|
||||
}
|
||||
if (!lstatSync(canonicalBaseCwd).isDirectory()) {
|
||||
throw new Error(`Registered base project workspace is not a directory at ${canonicalBaseCwd}.`);
|
||||
}
|
||||
registeredConfigPath = path.join(canonicalBaseCwd, ".paperclip", "config.json");
|
||||
}
|
||||
|
||||
const selectedPath = registeredConfigPath ?? explicitSource!;
|
||||
const canonicalSourceConfigPath = canonicalRegularFile(selectedPath, "Registered source Paperclip config");
|
||||
if (registeredConfigPath && canonicalSourceConfigPath !== registeredConfigPath) {
|
||||
throw new Error("Registered source Paperclip config escapes the base project workspace or uses a symlink alias.");
|
||||
}
|
||||
|
||||
if (explicitSource) {
|
||||
const canonicalExplicitSource = canonicalRegularFile(explicitSource, "Explicit source Paperclip config");
|
||||
if (canonicalExplicitSource !== canonicalSourceConfigPath) {
|
||||
throw new Error("Explicit source Paperclip config does not match the registered base project workspace.");
|
||||
}
|
||||
}
|
||||
|
||||
const canonicalTargetConfigPath = canonicalRegularFile(
|
||||
input.targetConfigPath,
|
||||
"Target worktree Paperclip config",
|
||||
);
|
||||
if (canonicalSourceConfigPath === canonicalTargetConfigPath) {
|
||||
throw new Error("Source and target Paperclip configs are the same canonical file.");
|
||||
}
|
||||
|
||||
const sourceInstanceId = readInstanceId(canonicalSourceConfigPath, "source");
|
||||
const targetInstanceId = readInstanceId(canonicalTargetConfigPath, "target");
|
||||
if (targetInstanceId !== input.expectedTargetInstanceId) {
|
||||
throw new Error("Target Paperclip instance does not match the registered worktree instance.");
|
||||
}
|
||||
if (sourceInstanceId === targetInstanceId) {
|
||||
throw new Error("Source and target Paperclip configs name the same instance.");
|
||||
}
|
||||
|
||||
const diagnosticPath = typeof input.manifestSource?.configPath === "string"
|
||||
? input.manifestSource.configPath.trim()
|
||||
: "";
|
||||
if (!diagnosticPath) {
|
||||
throw new Error("Worktree seed manifest is missing source path diagnostics.");
|
||||
}
|
||||
const canonicalDiagnosticPath = canonicalRegularFile(
|
||||
diagnosticPath,
|
||||
"Worktree seed manifest source diagnostic",
|
||||
);
|
||||
if (path.resolve(diagnosticPath) !== canonicalSourceConfigPath || canonicalDiagnosticPath !== canonicalSourceConfigPath) {
|
||||
throw new Error("Worktree seed manifest source path does not match the registered canonical source.");
|
||||
}
|
||||
if (input.manifestSource?.instanceId !== sourceInstanceId) {
|
||||
throw new Error("Worktree seed manifest source instance does not match the registered source instance.");
|
||||
}
|
||||
if (input.manifestTargetInstanceId !== targetInstanceId) {
|
||||
throw new Error("Worktree seed manifest target instance does not match the registered target instance.");
|
||||
}
|
||||
|
||||
return {
|
||||
baseWorkspaceCwd: canonicalBaseCwd,
|
||||
configPath: canonicalSourceConfigPath,
|
||||
instanceId: sourceInstanceId,
|
||||
targetConfigPath: canonicalTargetConfigPath,
|
||||
targetInstanceId,
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user