feat: add protected application shell

.github/workflows/playwright.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Run Storybook tests
         run: pnpm test:storybook
 
-      - name: Run six Playwright browser checks
+      - name: Run Playwright browser checks
         run: pnpm test:e2e
 
       - name: Upload Playwright report on failure

README.md

@@ -35,7 +35,7 @@ pnpm dev
 
 Open `http://localhost:3000`.
 
-Populate `.env.local` with the development values from the Clerk dashboard. Never commit `.env.local` or real secrets.
+Populate `.env.local` with development values from the Clerk dashboard. Never commit `.env.local` or real secrets.
 
 ```dotenv
 NEXT_PUBLIC_APP_URL=http://localhost:3000
@@ -44,30 +44,100 @@ NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_replace_me
 CLERK_SECRET_KEY=sk_test_replace_me
 ```
 
-`NEXT_PUBLIC_API_BASE_URL` points to the local APISIX gateway.
+`NEXT_PUBLIC_API_BASE_URL` points to the local APISIX gateway. The checked-in `.env.example` intentionally contains placeholders only.
 
-## Clerk bootstrap behavior
+## Authentication configuration
 
-`src/app/layout.tsx` installs `ClerkProvider`, and `src/proxy.ts` installs `clerkMiddleware()` when both Clerk keys are real values.
+`src/lib/clerk-config.ts` classifies the Clerk key pair as one of:
 
-The checked-in placeholders intentionally keep Clerk inactive so dependency installation, static builds, Storybook, and public foundation smoke tests can run without secrets. This is bootstrap behavior only. Protected product routes must be added explicitly and must fail closed before authenticated features are shipped.
+- `configured` — both keys follow Clerk's documented formats and belong to the same test or live environment;
+- `missing` — one or both values are absent or blank;
+- `placeholder` — checked-in example values or other obvious placeholders are present;
+- `malformed` — key formats are invalid or test/live environments do not match.
+
+A Publishable Key is validated as a `pk_test_` or `pk_live_` value containing a base64-encoded Frontend API value with Clerk's trailing `$` delimiter. A Secret Key is treated as opaque after its documented `sk_test_` or `sk_live_` prefix and requires only a non-empty payload; the frontend does not impose an undocumented charset or length.
+
+`src/lib/clerk-config.server.ts` is the only environment-reading boundary. It validates the secret but never returns, logs, renders, or serializes it. `src/lib/clerk-config.server.ts` and `src/lib/auth-session.server.ts` both import `server-only`, so Next.js rejects either module when it is pulled into a Client Component. The root layout receives only the publishable key when configuration is valid.
+
+Secretless builds, public pages, Storybook, unit tests, and public browser tests continue to work. Protected routes never become public when Clerk is unavailable:
+
+| Route | Policy when Clerk is configured | Policy when Clerk is unavailable |
+| --- | --- | --- |
+| `/` | Public | Public |
+| `/sign-in/[[...sign-in]]` | Clerk sign-in; signed-in users return to `/app` | Safe configuration state |
+| `/sign-up/[[...sign-up]]` | Clerk sign-up; signed-in users return to `/app` | Safe configuration state |
+| `/app` and `/app/**` | Authentication required | HTTP 503 fail-closed response |
+| `/api/**` | No global policy; each future route defines its own boundary | No global policy |
+
+The proxy provides an early redirect for unauthenticated document requests. The protected layout and protected page both repeat the server-side Clerk session check. This defense in depth is intentional because a layout check alone is not sufficient for every client-side navigation or future server resource.
+
+## Application shell
+
+The current protected shell provides only one real navigation entry:
+
+```text
+Overview → /app
+```
+
+It includes:
+
+- a skip link and semantic header, navigation, and main landmarks;
+- a keyboard-accessible Radix mobile navigation sheet with Escape handling and focus return;
+- persistent navigation from 1024 px upward;
+- constrained content width at large viewports;
+- a Clerk `UserButton` with stable loading dimensions;
+- loading, configuration unavailable, session unavailable, and unexpected error states;
+- reduced-motion behavior and visible focus states.
+
+No jobs, talent, organizations, marketplace, applications, billing, messaging, fake metrics, fake users, or invented backend calls are included.
+
+## Backend authentication contract
+
+The backend verifies Clerk session JWTs at the service boundary. Browser requests must send `Authorization: Bearer <session token>` through APISIX. APISIX forwards the header, applies browser CORS and `X-Request-Id`, and does not perform JWT verification itself.
+
+This frontend PR does not call a backend endpoint. A future API client must preserve `X-Request-Id`, parse the backend error envelope `{code,message,request_id,details}`, and map account and dependency states without exposing raw backend errors.
 
 ## Commands
 
 ```bash
 pnpm dev                # local development
 pnpm lint               # ESLint
 pnpm typecheck          # TypeScript
-pnpm test               # Vitest
+pnpm test               # unit Vitest project
 pnpm build              # production build
 pnpm storybook          # Storybook development server
 pnpm build-storybook    # static Storybook build
 pnpm test:storybook     # Storybook component tests
-pnpm test:e2e           # local Playwright tests
+pnpm test:e2e           # local Playwright tests in three browsers
 pnpm check              # lint, typecheck, unit test, app build, Storybook build
 ```
 
-Playwright starts the local Next.js server automatically. Local runs cover Chromium, Firefox, and WebKit. CI uses Chromium for a bounded cross-commit smoke check.
+Playwright starts the local Next.js server automatically and never visits an external website.
+
+Without a dedicated Clerk test instance, CI covers:
+
+- public routes;
+- configuration classification;
+- public/protected pathname policy;
+- presentation-only shell rendering and keyboard navigation;
+- deterministic auth-unavailable pages;
+- protected-route HTTP 503 fail-closed behavior;
+- axe checks across public and unavailable states.
+
+CI does not claim an authenticated end-to-end Clerk redirect or sign-in flow without actual Clerk test credentials.
+
+### Manual authenticated smoke checklist
+
+**Status: pending.** This checklist has not been executed for this PR because no dedicated Clerk test instance and credentials were available in the automated environment.
+
+- [ ] A signed-out request to `/app` redirects to `/sign-in` with a valid return path.
+- [ ] The real Clerk sign-in component renders without a configuration or network error.
+- [ ] Successful sign-in returns the user to `/app`.
+- [ ] Refreshing `/app` preserves the authenticated session.
+- [ ] The `UserButton` opens and signing out completes successfully.
+- [ ] After sign-out, accessing `/app` is protected again and returns to the sign-in flow.
+- [ ] `.env.local` remains ignored and is not staged or committed.
+- [ ] Browser HTML, console output, network payloads, and client bundles contain no `CLERK_SECRET_KEY` value or other server secret.
 
 ## Agent instructions and UI skills
 
@@ -82,7 +152,7 @@ BridgeWorks-specific rules, verified backend contracts, and the existing design
 ## Repository boundaries
 
 - Do not invent backend endpoints.
-- Verify routes, auth, status, error-envelope, CORS, and request-ID contracts from the backend `main` branch.
+- Verify routes, auth, status, error-envelope, CORS, and request-ID contracts from backend `main`.
 - Keep generic primitives in `src/components/ui`.
 - Keep feature-specific code in `src/features`.
 - Prefer Server Components and keep Client Components small.
@@ -95,9 +165,9 @@ The frontend workflow validates:
 
 - frozen dependency installation;
 - lint and typecheck;
-- Vitest;
+- Vitest unit tests;
 - Next.js production build;
 - Storybook build and Storybook tests;
-- Playwright smoke and axe checks.
+- Playwright smoke, fail-closed, and axe checks across Chromium, Firefox, and WebKit.
 
 Playwright reports are retained only when the workflow fails.

package.json

@@ -8,7 +8,7 @@
     "start": "next start",
     "lint": "eslint",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests",
+    "test": "vitest run --project=unit --passWithNoTests",
     "test:storybook": "vitest --project=storybook --run --passWithNoTests",
     "test:e2e": "playwright test",
     "storybook": "storybook dev -p 6006",

src/app/(auth)/sign-in/[[...sign-in]]/page.tsx

@@ -0,0 +1,82 @@
+import { SignIn } from "@clerk/nextjs";
+import type { Metadata } from "next";
+import { redirect } from "next/navigation";
+
+import {
+  AuthComponentFallback,
+  AuthPage,
+} from "@/components/layout/auth-page";
+import {
+  AuthState,
+  configurationStateKind,
+} from "@/components/layout/auth-state";
+import { getClerkSessionState } from "@/lib/auth-session.server";
+import {
+  APP_ROUTE,
+  SIGN_IN_ROUTE,
+  SIGN_UP_ROUTE,
+} from "@/lib/auth-routes";
+import { getClerkConfiguration } from "@/lib/clerk-config.server";
+
+export const dynamic = "force-dynamic";
+
+export const metadata: Metadata = {
+  title: "Sign in",
+  description: "Sign in to the protected BridgeWorks application.",
+};
+
+export default async function SignInPage() {
+  const configuration = getClerkConfiguration();
+
+  if (configuration.status !== "configured") {
+    return (
+      <AuthPage
+        title="Sign in to BridgeWorks"
+        description="Continue to the secure application workspace after your account is authenticated."
+      >
+        <AuthState kind={configurationStateKind(configuration)} />
+      </AuthPage>
+    );
+  }
+
+  const session = await getClerkSessionState();
+  if (session.status === "signed-in") {
+    redirect(APP_ROUTE);
+  }
+  if (session.status === "session-unavailable") {
+    return (
+      <AuthPage
+        title="Sign in to BridgeWorks"
+        description="Continue to the secure application workspace after your account is authenticated."
+      >
+        <AuthState kind="session-unavailable" />
+      </AuthPage>
+    );
+  }
+  if (session.status === "unexpected") {
+    return (
+      <AuthPage
+        title="Sign in to BridgeWorks"
+        description="Continue to the secure application workspace after your account is authenticated."
+      >
+        <AuthState kind="unexpected" />
+      </AuthPage>
+    );
+  }
+
+  return (
+    <AuthPage
+      title="Sign in to BridgeWorks"
+      description="Continue to the secure application workspace after your account is authenticated."
+    >
+      <SignIn
+        path={SIGN_IN_ROUTE}
+        routing="path"
+        signUpUrl={SIGN_UP_ROUTE}
+        fallbackRedirectUrl={APP_ROUTE}
+        signUpFallbackRedirectUrl={APP_ROUTE}
+        fallback={<AuthComponentFallback />}
+      />
+    </AuthPage>
+  );
+}

src/app/(auth)/sign-up/[[...sign-up]]/page.tsx

@@ -0,0 +1,82 @@
+import { SignUp } from "@clerk/nextjs";
+import type { Metadata } from "next";
+import { redirect } from "next/navigation";
+
+import {
+  AuthComponentFallback,
+  AuthPage,
+} from "@/components/layout/auth-page";
+import {
+  AuthState,
+  configurationStateKind,
+} from "@/components/layout/auth-state";
+import { getClerkSessionState } from "@/lib/auth-session.server";
+import {
+  APP_ROUTE,
+  SIGN_IN_ROUTE,
+  SIGN_UP_ROUTE,
+} from "@/lib/auth-routes";
+import { getClerkConfiguration } from "@/lib/clerk-config.server";
+
+export const dynamic = "force-dynamic";
+
+export const metadata: Metadata = {
+  title: "Create account",
+  description: "Create an account for the protected BridgeWorks application.",
+};
+
+export default async function SignUpPage() {
+  const configuration = getClerkConfiguration();
+
+  if (configuration.status !== "configured") {
+    return (
+      <AuthPage
+        title="Create your BridgeWorks account"
+        description="Create a secure account before entering the BridgeWorks application workspace."
+      >
+        <AuthState kind={configurationStateKind(configuration)} />
+      </AuthPage>
+    );
+  }
+
+  const session = await getClerkSessionState();
+  if (session.status === "signed-in") {
+    redirect(APP_ROUTE);
+  }
+  if (session.status === "session-unavailable") {
+    return (
+      <AuthPage
+        title="Create your BridgeWorks account"
+        description="Create a secure account before entering the BridgeWorks application workspace."
+      >
+        <AuthState kind="session-unavailable" />
+      </AuthPage>
+    );
+  }
+  if (session.status === "unexpected") {
+    return (
+      <AuthPage
+        title="Create your BridgeWorks account"
+        description="Create a secure account before entering the BridgeWorks application workspace."
+      >
+        <AuthState kind="unexpected" />
+      </AuthPage>
+    );
+  }
+
+  return (
+    <AuthPage
+      title="Create your BridgeWorks account"
+      description="Create a secure account before entering the BridgeWorks application workspace."
+    >
+      <SignUp
+        path={SIGN_UP_ROUTE}
+        routing="path"
+        signInUrl={SIGN_IN_ROUTE}
+        fallbackRedirectUrl={APP_ROUTE}
+        signInFallbackRedirectUrl={APP_ROUTE}
+        fallback={<AuthComponentFallback />}
+      />
+    </AuthPage>
+  );
+}

src/app/(protected)/app/error.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { AlertTriangle } from "lucide-react";
+import Link from "next/link";
+
+import { Button } from "@/components/ui/button";
+import { HOME_ROUTE } from "@/lib/auth-routes";
+
+type AppErrorProps = {
+  error: Error & { digest?: string };
+  reset: () => void;
+};
+
+export default function AppError({ reset }: AppErrorProps) {
+  return (
+    <section
+      aria-labelledby="application-error-title"
+      className="max-w-xl rounded-xl border border-border bg-card p-6 shadow-sm sm:p-8"
+    >
+      <div className="flex size-11 items-center justify-center rounded-lg bg-muted text-foreground">
+        <AlertTriangle aria-hidden="true" className="size-5" />
+      </div>
+      <h1
+        id="application-error-title"
+        className="mt-5 text-2xl font-semibold tracking-tight"
+      >
+        The application could not finish loading
+      </h1>
+      <p className="mt-3 max-w-prose text-base leading-7 text-muted-foreground">
+        BridgeWorks stopped before rendering incomplete protected content. Try
+        the request again, or return to the public site.
+      </p>
+      <div className="mt-6 flex flex-col gap-3 sm:flex-row">
+        <Button type="button" size="lg" onClick={reset}>
+          Try again
+        </Button>
+        <Button asChild variant="outline" size="lg">
+          <Link href={HOME_ROUTE}>Return to BridgeWorks</Link>
+        </Button>
+      </div>
+    </section>
+  );
+}