Files
PaperClipAI/ui/src/components/WorkspaceAccessCard.tsx
T
DottaandPaperclip a2bf936f9a 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>
2026-08-19 02:37:02 -05:00

150 lines
5.3 KiB
TypeScript

import { ExternalLink, Loader2, Play, ScrollText, Wrench } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
import { cn } from "../lib/utils";
import type { WorkspaceAccessState } from "../lib/workspace-access-state";
/**
* Workspace access surface (PAP-17572).
*
* One card per workspace that names the state, the cause, and the single safe
* next action. It replaces the previous behavior where a cloned workspace whose
* database was missing still rendered a plain "Open" link and answered with
* "invalid email or password".
*/
/**
* Badge tones come from the semantic status token layer, so a theme change moves
* these states with every other status surface. `ready` reuses the "done" tone
* and `degraded` the "todo" (amber) tone; the icon variants are the contrast-
* corrected pair the token layer already tunes per mode.
*/
const STATE_BADGE_CLASSES: Record<WorkspaceAccessState["state"], string> = {
provisioning: "border-border text-muted-foreground",
validating: "border-border text-muted-foreground",
ready: "border-(--status-task-done) text-(--status-task-icon-done)",
degraded: "border-(--status-task-todo) text-(--status-task-icon-todo)",
repairing: "border-border text-muted-foreground",
failed: "border-destructive/50 text-destructive",
};
const STATE_LABELS: Record<WorkspaceAccessState["state"], string> = {
provisioning: "Provisioning",
validating: "Validating clone",
ready: "Ready",
degraded: "Degraded",
repairing: "Repairing",
failed: "Failed",
};
const ACTION_ICONS = {
open: ExternalLink,
start: Play,
repair: Wrench,
view_logs: ScrollText,
wait: Loader2,
} as const;
export function WorkspaceAccessCard({
access,
isBusy,
onOpen,
onStart,
onRepair,
onViewLogs,
errorMessage,
}: {
access: WorkspaceAccessState;
isBusy?: boolean;
onOpen: () => void;
onStart: () => void;
onRepair: () => void;
onViewLogs: () => void;
errorMessage?: string | null;
}) {
const Icon = ACTION_ICONS[access.action.kind];
const isWaiting = access.action.kind === "wait";
const handlers: Record<WorkspaceAccessState["action"]["kind"], () => void> = {
open: onOpen,
start: onStart,
repair: onRepair,
view_logs: onViewLogs,
wait: () => undefined,
};
const SecondaryNoticeIcon = access.secondaryNotice
? ACTION_ICONS[access.secondaryNotice.action.kind]
: null;
return (
<Card data-testid="workspace-access-card" data-state={access.state}>
<CardHeader>
<div className="flex flex-wrap items-center gap-2">
<CardTitle>{access.title}</CardTitle>
<span
data-testid="workspace-access-badge"
className={cn(
"inline-flex items-center rounded-full border bg-background px-2.5 py-1 text-xs",
STATE_BADGE_CLASSES[access.state],
)}
>
{(access.state === "repairing" || access.state === "provisioning") && (
<Loader2 className="mr-1.5 h-3 w-3 animate-spin" />
)}
{STATE_LABELS[access.state]}
</span>
</div>
<CardDescription>{access.description}</CardDescription>
</CardHeader>
<CardContent className="flex flex-col gap-3">
<div className="flex flex-wrap items-center gap-2">
<Button
type="button"
variant={access.action.kind === "open" ? "default" : "outline"}
disabled={isWaiting || isBusy}
onClick={handlers[access.action.kind]}
>
{isBusy && !isWaiting ? (
<Loader2 className="mr-2 h-4 w-4 animate-spin" />
) : (
<Icon className={cn("mr-2 h-4 w-4", isWaiting && "animate-spin")} />
)}
{access.action.label}
</Button>
{access.state === "ready" && !access.handoffAvailable ? (
<span className="text-xs text-muted-foreground">
Signs in with the snapshot-local credentials captured when this clone was made.
</span>
) : null}
{access.state === "ready" && access.handoffAvailable ? (
<span className="text-xs text-muted-foreground">
Uses a single-use login handoff — no password needed.
</span>
) : null}
</div>
{errorMessage ? (
<p data-testid="workspace-access-error" className="text-sm text-destructive">
{errorMessage}
</p>
) : null}
{access.secondaryNotice && SecondaryNoticeIcon ? (
<div data-testid="workspace-access-secondary-notice" className="flex flex-col gap-1.5 text-sm">
<p className="font-medium text-destructive">{access.secondaryNotice.title}</p>
<p className="text-muted-foreground">{access.secondaryNotice.description}</p>
<Button
type="button"
variant="link"
size="sm"
className="h-auto w-fit p-0"
disabled={isBusy}
onClick={handlers[access.secondaryNotice.action.kind]}
>
<SecondaryNoticeIcon className="mr-2 h-4 w-4" />
{access.secondaryNotice.action.label}
</Button>
</div>
) : null}
</CardContent>
</Card>
);
}