forked from farhoodlabs/paperclip
[codex] Add private browser first-admin claim flow (#6755)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - Fresh self-hosted deployments need an operator path before any invite exists. > - Umbrel installs are private LAN deployments, so a one-time browser claim is appropriate only when the deployment is private and unclaimed. > - Public deployments and installs with active invites must keep the existing invite-only model so admin creation is not exposed broadly. > - GitHub PR #2927 established the useful direction, but it needed to be adapted onto current `master` rather than merged as-is. > - This pull request adds that adapted private-only claim flow across server, UI, docs, and regression coverage. > - The benefit is that a fresh private Umbrel-style install can be claimed from the browser without weakening public deployment access. ## What Changed - Added a first-admin claim service and access route support for one-time admin claim eligibility on private unclaimed deployments. - Updated the bootstrap/access UI so eligible private installs show a setup claim path, while public and invited deployments keep invite-first behavior. - Added a bootstrap-pending setup UX lab covering claim, invite, public, and signed-in access states. - Updated deployment and local development docs for authenticated private/public behavior and the Umbrel-style claim path. - Added server and UI regression tests for private claim, public no-claim, active invite fallback, existing board/no-access flows, and health exposure reporting. - Stabilized PR handoff verification by serializing the aggregate server Vitest workspace run, forcing `NODE_ENV=test`, and relaxing the heartbeat batching test around legitimate recovery follow-up runs. ## Verification - `pnpm -r typecheck` - `pnpm build` - `pnpm vitest --run server/src/__tests__/heartbeat-comment-wake-batching.test.ts` - `pnpm vitest --run server/src/__tests__/health-dev-server-token.test.ts` - `pnpm test:run` - QA validation: PAP-10115 passed browser validation with screenshots for private fresh install claim, active invite versus claim conflict, public invite-only/claim-absent behavior, existing invite fallback, and normal board/no-access flows. - GitHub closeout: issue #2579 and PR #2927 were updated with the accepted direction: adapt the implementation, do not direct-merge #2927 as-is. ## Risks - The claim endpoint must remain private-only and one-time; a regression here could expose admin creation on public deployments. - Existing invite behavior must remain intact for public deployments and installs that already have an active invite. - The stable Vitest harness now serializes the aggregate server workspace group; this is slower, but it avoids DB-backed suite collisions under root workspace mode. > 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`. > > ROADMAP.md checked: this is a scoped deployment bootstrap/access fix and does not duplicate a listed roadmap project. ## Model Used - OpenAI GPT-5 Codex via Paperclip `codex_local` for product engineering, implementation, and verification, with tool-enabled local code execution. Paperclip QA browser validation was performed in PAP-10115 by the assigned QA agent; exact adapter model metadata for that QA run is not exposed in this PR context. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
@@ -0,0 +1,176 @@
|
||||
import type { ReactNode } from "react";
|
||||
import { Loader2, ShieldCheck, Terminal, TriangleAlert } from "lucide-react";
|
||||
import { Link } from "@/lib/router";
|
||||
import { Button } from "@/components/ui/button";
|
||||
import { BOOTSTRAP_FALLBACK_COMMAND } from "@/bootstrapSetup";
|
||||
import type { AuthSession } from "@paperclipai/shared";
|
||||
|
||||
type BootstrapPendingPageProps = {
|
||||
claimAvailable: boolean;
|
||||
hasActiveInvite?: boolean;
|
||||
session: AuthSession | null | undefined;
|
||||
claimState: "idle" | "claiming" | "success";
|
||||
claimError?: { status?: number; message?: string } | null;
|
||||
onClaim: () => void;
|
||||
};
|
||||
|
||||
function CliFallback({ hasActiveInvite = false }: { hasActiveInvite?: boolean }) {
|
||||
return (
|
||||
<div className="mt-6 border-t border-border pt-5">
|
||||
<div className="flex items-center gap-2 text-sm font-medium">
|
||||
<Terminal className="size-4 text-muted-foreground" aria-hidden />
|
||||
<span>Prefer to finish setup from the host?</span>
|
||||
</div>
|
||||
<p className="mt-2 text-sm text-muted-foreground">
|
||||
{hasActiveInvite
|
||||
? "A bootstrap invite is already active. Check your Paperclip startup logs for the first-admin URL, or run this command on the host to rotate it:"
|
||||
: "Run this command on the host that runs Paperclip to print a one-time first-admin invite URL:"}
|
||||
</p>
|
||||
<pre className="mt-3 overflow-x-auto rounded-md border border-border bg-muted/30 p-3 font-mono text-xs">
|
||||
{BOOTSTRAP_FALLBACK_COMMAND}
|
||||
</pre>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
function StateChrome({ children }: { children: ReactNode }) {
|
||||
return (
|
||||
<div className="mx-auto max-w-xl py-10">
|
||||
<div className="rounded-lg border border-border bg-card p-6">{children}</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
function displayIdentity(session: AuthSession) {
|
||||
return session.user.email || session.user.name || session.user.id;
|
||||
}
|
||||
|
||||
function claimErrorCopy(error: BootstrapPendingPageProps["claimError"]) {
|
||||
if (error?.status === 409) {
|
||||
return {
|
||||
title: "Someone else has already claimed this instance.",
|
||||
body: "Refresh to sign in, or ask the existing admin to invite you from Instance settings -> Access.",
|
||||
};
|
||||
}
|
||||
if (error?.status === 401) {
|
||||
return {
|
||||
title: "Your session expired. Sign in again to claim this instance.",
|
||||
body: "",
|
||||
};
|
||||
}
|
||||
return {
|
||||
title: "We couldn't reach the server. Try again in a moment.",
|
||||
body: "",
|
||||
};
|
||||
}
|
||||
|
||||
export function BootstrapPendingPage({
|
||||
claimAvailable,
|
||||
hasActiveInvite = false,
|
||||
session,
|
||||
claimState,
|
||||
claimError,
|
||||
onClaim,
|
||||
}: BootstrapPendingPageProps) {
|
||||
if (!claimAvailable) {
|
||||
return (
|
||||
<StateChrome>
|
||||
<h1 className="text-xl font-semibold">This Paperclip is waiting on its first admin</h1>
|
||||
<p className="mt-2 text-sm text-muted-foreground">
|
||||
This instance runs in invite-only mode. The operator must generate a one-time first-admin invite URL
|
||||
from the host. Once you have the link, open it from this browser to finish setup.
|
||||
</p>
|
||||
<CliFallback hasActiveInvite={hasActiveInvite} />
|
||||
<p className="mt-4 text-xs text-muted-foreground">
|
||||
Browser-based claim is intentionally disabled in public mode so anyone on the network can't promote
|
||||
themselves.
|
||||
</p>
|
||||
</StateChrome>
|
||||
);
|
||||
}
|
||||
|
||||
if (claimState === "success") {
|
||||
return (
|
||||
<StateChrome>
|
||||
<div className="flex items-start gap-3">
|
||||
<div className="mt-0.5 flex size-9 flex-shrink-0 items-center justify-center rounded-full bg-emerald-500/15 text-emerald-600 dark:text-emerald-400">
|
||||
<ShieldCheck className="size-5" aria-hidden />
|
||||
</div>
|
||||
<div>
|
||||
<h1 className="text-xl font-semibold">You're the instance admin</h1>
|
||||
<p className="mt-2 text-sm text-muted-foreground">
|
||||
Setup is complete. Taking you to onboarding to create your first company...
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div className="mt-5 flex items-center gap-3">
|
||||
<Loader2 className="size-4 animate-spin text-muted-foreground" aria-hidden />
|
||||
<span className="text-sm text-muted-foreground">Redirecting...</span>
|
||||
</div>
|
||||
<div className="mt-5">
|
||||
<Button asChild variant="outline">
|
||||
<a href="/">Continue to dashboard</a>
|
||||
</Button>
|
||||
</div>
|
||||
</StateChrome>
|
||||
);
|
||||
}
|
||||
|
||||
if (!session) {
|
||||
return (
|
||||
<StateChrome>
|
||||
<h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
|
||||
<p className="mt-2 text-sm text-muted-foreground">
|
||||
No admin has claimed this instance yet. Sign in or create your Paperclip account to become the first
|
||||
admin from this browser.
|
||||
</p>
|
||||
<div className="mt-5">
|
||||
<Button asChild>
|
||||
<Link to="/auth?next=/">Sign in / Create account</Link>
|
||||
</Button>
|
||||
</div>
|
||||
<CliFallback hasActiveInvite={hasActiveInvite} />
|
||||
</StateChrome>
|
||||
);
|
||||
}
|
||||
|
||||
const errorCopy = claimErrorCopy(claimError);
|
||||
const isClaiming = claimState === "claiming";
|
||||
return (
|
||||
<StateChrome>
|
||||
<h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
|
||||
<p className="mt-2 text-sm text-muted-foreground">
|
||||
No admin has claimed this instance yet. Claim it now to become the first admin and start onboarding.
|
||||
</p>
|
||||
<div className="mt-5 flex flex-wrap items-center gap-3">
|
||||
<Button onClick={onClaim} disabled={isClaiming}>
|
||||
{isClaiming && <Loader2 className="mr-2 size-4 animate-spin" aria-hidden />}
|
||||
{isClaiming ? "Claiming..." : "Claim this instance"}
|
||||
</Button>
|
||||
<span className="text-sm text-muted-foreground">
|
||||
Signed in as <span className="font-medium text-foreground">{displayIdentity(session)}</span>
|
||||
</span>
|
||||
</div>
|
||||
<p className="mt-3 text-xs text-muted-foreground">
|
||||
Wrong account?{" "}
|
||||
<Link to="/auth?next=/" className="underline underline-offset-2">
|
||||
Switch account
|
||||
</Link>
|
||||
.
|
||||
</p>
|
||||
{claimError && (
|
||||
<div
|
||||
role="alert"
|
||||
className="mt-4 flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/10 p-3 text-sm text-destructive"
|
||||
>
|
||||
<TriangleAlert className="mt-0.5 size-4 flex-shrink-0" aria-hidden />
|
||||
<div>
|
||||
<p className="font-medium">{errorCopy.title}</p>
|
||||
{errorCopy.body && <p className="mt-1 text-destructive/90">{errorCopy.body}</p>}
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
<CliFallback hasActiveInvite={hasActiveInvite} />
|
||||
</StateChrome>
|
||||
);
|
||||
}
|
||||
@@ -1,27 +1,11 @@
|
||||
import { Navigate, Outlet, useLocation } from "@/lib/router";
|
||||
import { useQuery } from "@tanstack/react-query";
|
||||
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
|
||||
import { accessApi } from "@/api/access";
|
||||
import { ApiError } from "@/api/client";
|
||||
import { authApi } from "@/api/auth";
|
||||
import { healthApi } from "@/api/health";
|
||||
import { queryKeys } from "@/lib/queryKeys";
|
||||
|
||||
function BootstrapPendingPage({ hasActiveInvite = false }: { hasActiveInvite?: boolean }) {
|
||||
return (
|
||||
<div className="mx-auto max-w-xl py-10">
|
||||
<div className="rounded-lg border border-border bg-card p-6">
|
||||
<h1 className="text-xl font-semibold">Instance setup required</h1>
|
||||
<p className="mt-2 text-sm text-muted-foreground">
|
||||
{hasActiveInvite
|
||||
? "No instance admin exists yet. A bootstrap invite is already active. Check your Paperclip startup logs for the first admin invite URL, or run this command to rotate it:"
|
||||
: "No instance admin exists yet. Run this command in your Paperclip environment to generate the first admin invite URL:"}
|
||||
</p>
|
||||
<pre className="mt-4 overflow-x-auto rounded-md border border-border bg-muted/30 p-3 text-xs">
|
||||
{`pnpm paperclipai auth bootstrap-ceo`}
|
||||
</pre>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
import { BootstrapPendingPage } from "@/components/BootstrapPendingPage";
|
||||
|
||||
function NoBoardAccessPage() {
|
||||
return (
|
||||
@@ -42,6 +26,7 @@ function NoBoardAccessPage() {
|
||||
|
||||
export function CloudAccessGate() {
|
||||
const location = useLocation();
|
||||
const queryClient = useQueryClient();
|
||||
const healthQuery = useQuery({
|
||||
queryKey: queryKeys.health,
|
||||
queryFn: () => healthApi.get(),
|
||||
@@ -58,6 +43,7 @@ export function CloudAccessGate() {
|
||||
});
|
||||
|
||||
const isAuthenticatedMode = healthQuery.data?.deploymentMode === "authenticated";
|
||||
const isBootstrapPending = isAuthenticatedMode && healthQuery.data?.bootstrapStatus === "bootstrap_pending";
|
||||
const sessionQuery = useQuery({
|
||||
queryKey: queryKeys.auth.session,
|
||||
queryFn: () => authApi.getSession(),
|
||||
@@ -68,14 +54,24 @@ export function CloudAccessGate() {
|
||||
const boardAccessQuery = useQuery({
|
||||
queryKey: queryKeys.access.currentBoardAccess,
|
||||
queryFn: () => accessApi.getCurrentBoardAccess(),
|
||||
enabled: isAuthenticatedMode && !!sessionQuery.data,
|
||||
enabled: isAuthenticatedMode && !isBootstrapPending && !!sessionQuery.data,
|
||||
retry: false,
|
||||
});
|
||||
const claimMutation = useMutation({
|
||||
mutationFn: () => accessApi.claimBootstrapAdmin(),
|
||||
onSuccess: async () => {
|
||||
await queryClient.invalidateQueries({ queryKey: queryKeys.auth.session });
|
||||
await queryClient.invalidateQueries({ queryKey: queryKeys.health });
|
||||
await queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
|
||||
await queryClient.invalidateQueries({ queryKey: queryKeys.companies.stats });
|
||||
await queryClient.invalidateQueries({ queryKey: queryKeys.access.currentBoardAccess });
|
||||
},
|
||||
});
|
||||
|
||||
if (
|
||||
healthQuery.isLoading ||
|
||||
(isAuthenticatedMode && sessionQuery.isLoading) ||
|
||||
(isAuthenticatedMode && !!sessionQuery.data && boardAccessQuery.isLoading)
|
||||
(isAuthenticatedMode && !isBootstrapPending && !!sessionQuery.data && boardAccessQuery.isLoading)
|
||||
) {
|
||||
return <div className="mx-auto max-w-xl py-10 text-sm text-muted-foreground">Loading...</div>;
|
||||
}
|
||||
@@ -92,8 +88,26 @@ export function CloudAccessGate() {
|
||||
);
|
||||
}
|
||||
|
||||
if (isAuthenticatedMode && healthQuery.data?.bootstrapStatus === "bootstrap_pending") {
|
||||
return <BootstrapPendingPage hasActiveInvite={healthQuery.data.bootstrapInviteActive} />;
|
||||
if (isBootstrapPending) {
|
||||
const health = healthQuery.data;
|
||||
if (!health) {
|
||||
return <div className="mx-auto max-w-xl py-10 text-sm text-muted-foreground">Loading...</div>;
|
||||
}
|
||||
const claimError = claimMutation.error instanceof ApiError
|
||||
? { status: claimMutation.error.status, message: claimMutation.error.message }
|
||||
: claimMutation.error instanceof Error
|
||||
? { message: claimMutation.error.message }
|
||||
: null;
|
||||
return (
|
||||
<BootstrapPendingPage
|
||||
claimAvailable={health.deploymentExposure === "private"}
|
||||
hasActiveInvite={health.bootstrapInviteActive}
|
||||
session={sessionQuery.data}
|
||||
claimState={claimMutation.isSuccess ? "success" : claimMutation.isPending ? "claiming" : "idle"}
|
||||
claimError={claimError}
|
||||
onClaim={() => claimMutation.mutate()}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
if (isAuthenticatedMode && !sessionQuery.data) {
|
||||
|
||||
Reference in New Issue
Block a user