handoff-app 2.0.0-2 → 2.0.0-3

package/drizzle/meta/_journal.json

@@ -36,6 +36,13 @@
       "when": 1783442253186,
       "tag": "0004_add_assets",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1785229875267,
+      "tag": "0005_add_registry_auth",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "2.0.0-2",
+  "version": "2.0.0-3",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",
@@ -90,9 +90,6 @@
     "dotenv": "^16.0.3",
     "drizzle-orm": "^0.45.2",
     "esbuild": "^0.25.0",
-    "eslint": "^8.23.1",
-    "eslint-config-next": "^15.3.4",
-    "eslint-config-prettier": "^10.0.2",
     "fs-extra": "^11.3.0",
     "gray-matter": "^4.0.3",
     "handlebars": "^4.7.8",
@@ -102,6 +99,7 @@
     "lodash": "^4.17.21",
     "lucide-react": "^0.518.0",
     "next": "^15.3.4",
+    "next-auth": "^4.24.15",
     "next-themes": "^0.4.4",
     "node-html-parser": "^6.1.4",
     "pg": "^8.22.0",
@@ -137,6 +135,9 @@
     "@types/pg": "^8.20.0",
     "@types/yargs": "^17.0.33",
     "drizzle-kit": "^0.31.10",
+    "eslint": "^8.23.1",
+    "eslint-config-next": "^15.3.4",
+    "eslint-config-prettier": "^10.0.2",
     "np": "^10.2.0",
     "prettier-plugin-tailwindcss": "^0.7.0",
     "sass-embedded": "^1.89.0",

package/src/app/components/Auth/AccountLayout.tsx

@@ -0,0 +1,87 @@
+import { useSession } from 'next-auth/react';
+import Link from 'next/link';
+import { useRouter } from 'next/router';
+import { useEffect, type ReactNode } from 'react';
+import { cn } from '../../lib/utils';
+import { AuthShell } from './AuthShell';
+
+const navGroups = [
+  {
+    label: 'Account',
+    links: [
+      { href: '/account', label: 'Profile' },
+      { href: '/account/tokens', label: 'Access tokens' },
+    ],
+  },
+  {
+    label: 'Administration',
+    links: [{ href: '/account/users', label: 'Users', adminOnly: true }],
+  },
+];
+
+export function AccountLayout({ children, title }: { children: ReactNode; title: string }) {
+  if (process.env.HANDOFF_RUNTIME_MODE !== 'registry') {
+    return <AuthShell title={title}>{null}</AuthShell>;
+  }
+
+  return <RegistryAccountLayout title={title}>{children}</RegistryAccountLayout>;
+}
+
+function RegistryAccountLayout({ children, title }: { children: ReactNode; title: string }) {
+  const { data: session, status } = useSession();
+  const router = useRouter();
+  const role = (session?.user as { role?: string } | undefined)?.role;
+
+  // Redirect to login whenever there's no live user, not just on `unauthenticated`. An invalidated
+  // token still reports `authenticated` but carries no user, so checking status alone leaves the
+  // shell stuck in a broken half-signed-in state.
+  useEffect(() => {
+    if (status !== 'loading' && !session?.user) {
+      void router.replace(`/login?callbackUrl=${encodeURIComponent(router.asPath)}`);
+    }
+  }, [router, session, status]);
+
+  return (
+    <AuthShell title={title} wide>
+      {status === 'loading' || !session?.user ? (
+        <p className="py-20 text-center text-sm text-muted-foreground">Loading account…</p>
+      ) : (
+        <div className="grid gap-8 md:grid-cols-[200px_minmax(0,1fr)]">
+          <aside className="space-y-6">
+            {navGroups
+              .map((group) => ({
+                ...group,
+                links: group.links.filter((link) => !('adminOnly' in link && link.adminOnly) || role === 'admin'),
+              }))
+              .filter((group) => group.links.length > 0)
+              .map((group) => (
+                <div key={group.label}>
+                  <p className="mb-3 px-3 text-xs font-medium uppercase tracking-wide text-muted-foreground">{group.label}</p>
+                  <nav className="flex gap-1 overflow-x-auto md:flex-col">
+                    {group.links.map((link) => {
+                      const active = router.pathname === link.href;
+                      return (
+                        <Link
+                          key={link.href}
+                          href={link.href}
+                          className={cn(
+                            'whitespace-nowrap rounded-md px-3 py-2 text-sm',
+                            active
+                              ? 'bg-accent font-medium text-accent-foreground'
+                              : 'text-muted-foreground hover:bg-accent/50 hover:text-foreground'
+                          )}
+                        >
+                          {link.label}
+                        </Link>
+                      );
+                    })}
+                  </nav>
+                </div>
+              ))}
+          </aside>
+          <section className="min-w-0">{children}</section>
+        </div>
+      )}
+    </AuthShell>
+  );
+}

package/src/app/components/Auth/AuthControls.tsx

@@ -0,0 +1,99 @@
+import { LogOut, UserRound } from 'lucide-react';
+import { signOut, useSession } from 'next-auth/react';
+import Link from 'next/link';
+import { useRouter } from 'next/router';
+import { Badge } from '../ui/badge';
+import { Button } from '../ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '../ui/dropdown-menu';
+
+const isRegistryRuntime = process.env.HANDOFF_RUNTIME_MODE === 'registry';
+
+export function AuthControls({ mobile = false }: { mobile?: boolean }) {
+  if (!isRegistryRuntime) return null;
+  return <RegistryAuthControls mobile={mobile} />;
+}
+
+function RegistryAuthControls({ mobile }: { mobile: boolean }) {
+  const { data: session, status } = useSession();
+  const router = useRouter();
+
+  if (status === 'loading')
+    return <div className={mobile ? 'h-9 w-full animate-pulse rounded-md bg-muted' : 'h-8 w-20 animate-pulse rounded-md bg-muted'} />;
+
+  if (!session?.user) {
+    return (
+      <Button asChild variant="outline" size="sm" className={mobile ? 'w-full' : undefined}>
+        <Link href="/login">Sign in</Link>
+      </Button>
+    );
+  }
+
+  const user = session.user as typeof session.user & { role?: string };
+  const displayName = user.name || user.email || 'Account';
+
+  if (mobile) {
+    return (
+      <div className="space-y-2 border-t pt-4">
+        <Link href="/account" className="flex items-center gap-2 rounded-md px-4 py-2 text-sm hover:bg-accent/50">
+          <UserRound className="h-4 w-4" />
+          <span className="truncate">{displayName}</span>
+        </Link>
+        <Button
+          variant="ghost"
+          className="w-full justify-start font-normal"
+          onClick={() => void signOut({ callbackUrl: `${process.env.HANDOFF_APP_BASE_PATH ?? ''}/login` })}
+        >
+          <LogOut className="mr-2 h-4 w-4" />
+          Sign out
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="outline" size="sm" className="max-w-48 gap-2">
+          <span className="flex h-5 w-5 items-center justify-center rounded-full bg-muted text-[10px]">
+            {displayName.slice(0, 1).toUpperCase()}
+          </span>
+          <span className="truncate">{displayName}</span>
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-56">
+        <DropdownMenuLabel className="space-y-1 font-normal">
+          <p className="truncate text-sm font-medium">{displayName}</p>
+          <p className="truncate text-xs text-muted-foreground">{user.email}</p>
+          {user.role ? (
+            <Badge className="mt-1" variant="secondary">
+              {user.role}
+            </Badge>
+          ) : null}
+        </DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem asChild>
+          <Link href="/account">
+            <UserRound />
+            Account settings
+          </Link>
+        </DropdownMenuItem>
+        <DropdownMenuItem
+          onSelect={(event) => {
+            event.preventDefault();
+            void signOut({ redirect: false }).then(() => void router.push('/login'));
+          }}
+        >
+          <LogOut />
+          Sign out
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/app/components/Auth/AuthShell.tsx

@@ -0,0 +1,73 @@
+import { ArrowLeft } from 'lucide-react';
+import Head from 'next/head';
+import Link from 'next/link';
+import type { ReactNode } from 'react';
+import { Badge } from '../ui/badge';
+import { Button } from '../ui/button';
+import { ThemeProvider } from '../util/theme-provider';
+
+const isRegistryRuntime = process.env.HANDOFF_RUNTIME_MODE === 'registry';
+
+interface AuthShellProps {
+  children: ReactNode;
+  title: string;
+  description?: string;
+  wide?: boolean;
+  hideNav?: boolean;
+}
+
+export function AuthShell({ children, title, description, wide = false, hideNav = false }: AuthShellProps) {
+  if (!isRegistryRuntime) {
+    return (
+      <main className="flex min-h-screen items-center justify-center px-6">
+        <div className="max-w-md text-center">
+          <h1 className="text-2xl font-semibold">Registry only</h1>
+          <p className="mt-2 text-sm text-muted-foreground">Account management is available only in a deployed registry.</p>
+          <Button asChild variant="ghost" size="sm" className="mt-6 gap-2 text-muted-foreground hover:text-foreground">
+            <Link href="/">
+              <ArrowLeft className="h-4 w-4" />
+              Back to documentation
+            </Link>
+          </Button>
+        </div>
+      </main>
+    );
+  }
+
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+      <Head>
+        <title>{title} · Handoff Registry</title>
+        {description ? <meta name="description" content={description} /> : null}
+      </Head>
+      <div className="min-h-screen bg-background">
+        <header className="border-b">
+          <div className="container mx-auto flex h-16 max-w-[1200px] items-center justify-between px-6">
+            {hideNav ? (
+              <span className="flex items-center gap-3">
+                {/* eslint-disable-next-line @next/next/no-img-element */}
+                <img className="max-h-5" src={`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/logo.svg`} alt="Handoff" />
+                <Badge variant="info">Registry</Badge>
+              </span>
+            ) : (
+              <Link href="/" className="flex items-center gap-3">
+                {/* eslint-disable-next-line @next/next/no-img-element */}
+                <img className="max-h-5" src={`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/logo.svg`} alt="Handoff" />
+                <Badge variant="info">Registry</Badge>
+              </Link>
+            )}
+            {hideNav ? null : (
+              <Button asChild variant="ghost" size="sm" className="gap-2 text-muted-foreground hover:text-foreground">
+                <Link href="/">
+                  <ArrowLeft className="h-4 w-4" />
+                  Back to documentation
+                </Link>
+              </Button>
+            )}
+          </div>
+        </header>
+        <main className={`container mx-auto px-6 py-10 ${wide ? 'max-w-[1200px]' : 'max-w-xl'}`}>{children}</main>
+      </div>
+    </ThemeProvider>
+  );
+}

package/src/app/components/Auth/RegistryInstallGate.tsx

@@ -0,0 +1,23 @@
+import { useRouter } from 'next/router';
+import { useEffect, type ReactNode } from 'react';
+import { authApiUrl } from './api';
+
+const isRegistryRuntime = process.env.HANDOFF_RUNTIME_MODE === 'registry';
+
+/** Keep every registry browser page on the one-time installer until setup is complete. */
+export function RegistryInstallGate({ children }: { children: ReactNode }) {
+  const router = useRouter();
+
+  useEffect(() => {
+    if (!isRegistryRuntime || !router.isReady || router.pathname === '/install') return;
+    void fetch(authApiUrl('/api/install'), { credentials: 'include', cache: 'no-store' })
+      .then(async (response) => {
+        if (!response.ok) return;
+        const status = (await response.json()) as { installed?: boolean };
+        if (status.installed === false) await router.replace('/install');
+      })
+      .catch(() => undefined);
+  }, [router]);
+
+  return <>{children}</>;
+}

package/src/app/components/Auth/RegistrySessionProvider.tsx

@@ -0,0 +1,15 @@
+import { SessionProvider } from 'next-auth/react';
+import type { ReactNode } from 'react';
+
+const isRegistryRuntime = process.env.HANDOFF_RUNTIME_MODE === 'registry';
+const authBasePath = `${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/auth`;
+
+export function RegistrySessionProvider({ children }: { children: ReactNode }) {
+  if (!isRegistryRuntime) return <>{children}</>;
+
+  return (
+    <SessionProvider basePath={authBasePath} refetchOnWindowFocus refetchInterval={5 * 60}>
+      {children}
+    </SessionProvider>
+  );
+}

package/src/app/components/Auth/api.ts

@@ -0,0 +1,20 @@
+const basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
+
+export const authApiUrl = (path: string): string => {
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${basePath}${normalizedPath}`;
+};
+
+export const authPageUrl = (path: string): string => {
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${basePath}${normalizedPath}`;
+};
+
+export const readApiError = async (response: Response, fallback: string): Promise<string> => {
+  const body = (await response.json().catch(() => null)) as { error?: string | { message?: string }; message?: string } | null;
+
+  if (typeof body?.error === 'string') return body.error;
+  if (typeof body?.error === 'object' && body.error?.message) return body.error.message;
+  if (body?.message) return body.message;
+  return fallback;
+};

package/src/app/components/Layout/Header.tsx

@@ -6,6 +6,7 @@ import { MobileNav } from '../../components/Navigation/MobileNav';
 import { cn } from '../../lib/utils';
 import { Badge } from '../ui/badge';
 import { useConfigContext } from '../context/ConfigContext';
+import { AuthControls } from '../Auth/AuthControls';
 
 const RUNTIME_MODE_LABEL: Record<'workspace' | 'registry', string> = {
   workspace: 'Workspace',
@@ -51,6 +52,7 @@ export function Header() {
           </div>
           <div className="hidden items-center gap-4 @2xl:flex">
             <MainNav />
+            {runtimeMode === 'registry' ? <AuthControls /> : null}
             <ModeToggle />
           </div>
           <div className="flex items-center gap-4 @2xl:hidden">

package/src/app/components/Navigation/MobileNav.tsx

@@ -8,6 +8,7 @@ import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger } from '../.
 import { cn } from '../../lib/utils';
 import { useConfigContext } from '../context/ConfigContext';
 import { useNav } from '../context/NavProvider';
+import { AuthControls } from '../Auth/AuthControls';
 
 const trimSlashes = (input: string): string => {
   return input.replace(/^\/+|\/+$/g, '');
@@ -90,6 +91,7 @@ export function MobileNav() {
               )}
             </Button>
           </div>
+          {context.config?.runtime?.mode === 'registry' ? <AuthControls mobile /> : null}
         </div>
       </SheetContent>
     </Sheet>

package/src/app/lib/auth/api.ts

@@ -0,0 +1,113 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import type { RegistryDatabase } from '@handoff/registry/db/client';
+import { getRegistryInstallationState, type RegistryUser } from '@handoff/registry/auth';
+import { getServerRuntimeConfig } from '../docs-api/runtime-config';
+import { getRegistryConnection, RegistryConnectionError } from '../registry-connection';
+import { canonicalRegistryUrl, getRegistrySessionUser } from './config';
+
+export const allowApiMethods = (req: NextApiRequest, res: NextApiResponse, methods: string[]): string | null => {
+  const method = (req.method ?? 'GET').toUpperCase();
+  if (methods.includes(method)) return method;
+  res.setHeader('Allow', methods.join(', '));
+  res.status(405).json({ error: `Method ${method} is not allowed.` });
+  return null;
+};
+
+export const registryPageUrl = (
+  path: string,
+  query?: Record<string, string>,
+  fragment?: Record<string, string>
+): string | null => {
+  const canonical = canonicalRegistryUrl();
+  if (!canonical) return null;
+  const base = canonical.pathname.replace(/\/+$/, '');
+  canonical.pathname = `${base}/${path.replace(/^\/+/, '')}`;
+  canonical.search = '';
+  canonical.hash = '';
+  if (query) {
+    for (const [key, value] of Object.entries(query)) canonical.searchParams.set(key, value);
+  }
+  // Put secrets (invite/reset tokens) in the fragment rather than the query string. The fragment
+  // never reaches the server, so it stays out of access logs, proxies, and Referer headers.
+  if (fragment) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(fragment)) params.set(key, value);
+    canonical.hash = params.toString();
+  }
+  return canonical.toString();
+};
+
+const requestOriginIsAllowed = (req: NextApiRequest): boolean => {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  const canonical = canonicalRegistryUrl();
+  if (canonical) return origin === canonical.origin;
+  const proto = String(req.headers['x-forwarded-proto'] || 'http')
+    .split(',')[0]
+    .trim();
+  return origin === `${proto}://${req.headers.host}`;
+};
+
+export interface RegistryApiContext {
+  db: RegistryDatabase;
+  user?: RegistryUser;
+}
+
+export interface RegistryApiOptions {
+  installed?: boolean;
+  auth?: 'user' | 'admin';
+  mutation?: boolean;
+}
+
+/**
+ * Shared browser-auth API boundary. Client redirects are convenience only; installation, live user
+ * status, role, and same-origin mutation checks are enforced here on every protected request.
+ */
+export const prepareRegistryApi = async (
+  req: NextApiRequest,
+  res: NextApiResponse,
+  options: RegistryApiOptions = {}
+): Promise<RegistryApiContext | null> => {
+  if (getServerRuntimeConfig().mode !== 'registry') {
+    res.status(409).json({ error: 'This endpoint is available only in registry mode.' });
+    return null;
+  }
+  if (options.mutation && !requestOriginIsAllowed(req)) {
+    res.status(403).json({ error: 'The request origin is not allowed.' });
+    return null;
+  }
+
+  let db: RegistryDatabase;
+  try {
+    ({ db } = await getRegistryConnection());
+  } catch (error) {
+    const message = error instanceof RegistryConnectionError ? error.message : 'The registry database is unavailable.';
+    res.status(503).json({ error: message });
+    return null;
+  }
+
+  if (options.installed !== false) {
+    try {
+      const installation = await getRegistryInstallationState(db);
+      if (installation.status !== 'installed') {
+        res.status(409).json({ error: 'Complete the registry installation before using this endpoint.', code: 'installation_required' });
+        return null;
+      }
+    } catch {
+      res.status(503).json({ error: 'Registry authentication migrations are missing. Run `handoff-app db:migrate`.' });
+      return null;
+    }
+  }
+
+  if (!options.auth) return { db };
+  const user = await getRegistrySessionUser(req, res);
+  if (!user) {
+    res.status(401).json({ error: 'Sign in with an active registry account.' });
+    return null;
+  }
+  if (options.auth === 'admin' && user.role !== 'admin') {
+    res.status(403).json({ error: 'Administrator access is required.' });
+    return null;
+  }
+  return { db, user };
+};