feat(app): Next.js 16 + Auth.js v5 portal skeleton

Next.js 16 + Auth.js v5 skeleton: host→slug middleware, tenant-context layout, OIDC sign-in flow against breakpilot-dev realm. 100% coverage on src/lib. Bumps next to 16.2.6 to clear trivy CVEs in 15.0.3.

.gitea/workflows/ci.yaml

@@ -57,7 +57,7 @@ jobs:
 
   test:
     runs-on: docker
-    if: hashFiles('package.json') != ''
+
     steps:
       - uses: actions/checkout@v4
 
@@ -72,11 +72,17 @@ jobs:
       - run: pnpm install --frozen-lockfile
       - run: pnpm lint
       - run: pnpm typecheck
-      - run: pnpm test --coverage
+      # `pnpm test` already includes --coverage via the package.json script.
+      - run: pnpm test
       - name: coverage gate
         run: |
           node -e "const c=require('./coverage/coverage-summary.json').total.lines.pct; if (c<70) { console.error('coverage', c, '< 70%'); process.exit(1) }"
-      - run: pnpm build
+      - name: build
+        env:
+          # Required at build-time by Auth.js. Replaced by Infisical-sourced
+          # secret in stage/prod via Orca env injection (M5.1+).
+          AUTH_SECRET: ci-build-dummy-${{ github.sha }}
+        run: pnpm build
 
   e2e:
     needs: test

.gitignore

@@ -35,3 +35,25 @@ vendor/
 
 # Rust
 **/target/
+
+# Next.js
+.next/
+out/
+.vercel/
+
+# Node
+node_modules/
+*.tsbuildinfo
+next-env.d.ts.tmp
+
+# Coverage
+coverage/
+
+# pnpm
+.pnpm-store/
+
+# Local env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local

CHANGELOG.md

@@ -6,6 +6,8 @@ Generated section is appended on release tag via `git-cliff` (see `.gitea/workfl
 ## [Unreleased]
 
 ### Added
+- chore(deps): bump next + eslint-config-next to 16.2.6 to clear trivy CVEs (CVE-2025-29927 critical + 7 highs in next 15.0.3)
+- feat(app): Next.js 16 + Auth.js v5 skeleton with host→slug middleware, tenant context layout, OIDC sign-in flow
 -
 
 ### Changed

Dockerfile

@@ -0,0 +1,25 @@
+# Multi-stage Next.js build using output: 'standalone'.
+
+FROM node:20-alpine AS deps
+WORKDIR /app
+RUN corepack enable && corepack prepare pnpm@9 --activate
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+
+FROM node:20-alpine AS build
+WORKDIR /app
+RUN corepack enable && corepack prepare pnpm@9 --activate
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN pnpm build
+
+FROM node:20-alpine AS run
+WORKDIR /app
+ENV NODE_ENV=production
+ENV PORT=3000
+COPY --from=build /app/public ./public
+COPY --from=build /app/.next/standalone ./
+COPY --from=build /app/.next/static ./.next/static
+USER node
+EXPOSE 3000
+CMD ["node", "server.js"]

Makefile

@@ -0,0 +1,37 @@
+# portal — Next.js 15 + Auth.js v5 customer portal + backstage.
+
+.PHONY: help install dev test lint typecheck build docker clean
+
+help:
+	@echo "portal targets:"
+	@echo "  make install      pnpm install"
+	@echo "  make dev          pnpm dev (http://localhost:3000)"
+	@echo "  make test         pnpm test (vitest + coverage)"
+	@echo "  make lint         pnpm lint"
+	@echo "  make typecheck    pnpm typecheck"
+	@echo "  make build        pnpm build (Next.js production build)"
+	@echo "  make docker       build local image (portal:dev)"
+
+install:
+	@pnpm install --frozen-lockfile
+
+dev:
+	@pnpm dev
+
+test:
+	@pnpm test
+
+lint:
+	@pnpm lint
+
+typecheck:
+	@pnpm typecheck
+
+build:
+	@pnpm build
+
+docker:
+	@docker build -t portal:dev .
+
+clean:
+	@rm -rf .next coverage node_modules/.cache

README.md

@@ -1,6 +1,6 @@
 # portal
 
-Next.js 15 customer area + backstage.
+Next.js 16 customer area + backstage.
 
 > Part of the **Breakpilot Platform**. For the big picture see [`platform/docs`](https://gitea.meghsakha.com/platform/docs):
 > [Architecture](https://gitea.meghsakha.com/platform/docs/src/branch/main/PLATFORM_ARCHITECTURE.md) ·
@@ -10,7 +10,7 @@ Next.js 15 customer area + backstage.
 
 ## What this is
 
-Next.js 15 customer area + backstage. Scaffolded under milestone M5.1. See [`platform/docs`](https://gitea.meghsakha.com/platform/docs) for the full architecture context.
+Next.js 16 customer area + backstage. Scaffolded under milestone M5.1. See [`platform/docs`](https://gitea.meghsakha.com/platform/docs) for the full architecture context.
 
 **Plane:** Control
 **Owner:** @sharang
@@ -20,19 +20,43 @@ Next.js 15 customer area + backstage. Scaffolded under milestone M5.1. See [`pla
 ## Run locally
 
 ```bash
-# prerequisites: see CONTRIBUTING.md for tooling once code lands
-make dev          # starts dependencies + this service on http://localhost:3000
-make test         # unit + integration
-make e2e          # only if this repo ships user-facing flows
+# Prerequisites: Node 20+, pnpm 9+, the dev stack running.
+
+# 1. Bring up Keycloak + Postgres + Redis (separate clone):
+cd /path/to/platform/orca-platform && make dev-up
+
+# 2. Run tenant-registry (separate clone):
+cd /path/to/platform/tenant-registry && make dev
+
+# 3. Run this app:
+make install      # pnpm install --frozen-lockfile
+make dev          # next dev on http://localhost:3000
+
+# Or hit a real tenant immediately:
+# open http://acme.localhost:3000  →  redirects to Keycloak  →  back to /acme/dashboard
 ```
 
-Local secrets come from `.env.local` (gitignored). Template at `.env.example`.
+Seed login (from the dev-stack realm): `test@breakpilot.dev` / `test`.
 
-## Endpoints / surface
+`make test` / `make lint` / `make typecheck` / `make build` run vitest / eslint / tsc / next build respectively.
 
-{{For services: list the top-level routes or commands.
-For libraries: list the public API entry points.
-For IaC: list the make targets.}}
+Env vars live in `.env.example`. Copy to `.env.local` for local overrides (gitignored).
+
+## Surface
+
+| Route                              | Renders                                                                 |
+|---|---|
+| `http://localhost:3000/`           | Apex landing — pointer to tenant subdomains                              |
+| `http://<slug>.localhost:3000/`    | Middleware rewrites to `/[slug]/` → redirects to `/[slug]/dashboard`     |
+| `http://<slug>.localhost:3000/dashboard` | OIDC-gated dashboard; signed-out users see "Sign in with Keycloak" |
+| `http://backstage.localhost:3000/` | (Skeleton) backstage route — rewritten to `/__backstage__/*`             |
+| `/api/auth/[...nextauth]`          | Auth.js v5 endpoints (callback, signin, signout, jwt)                    |
+
+## Architecture notes
+
+- **Host → slug routing**: `src/middleware.ts` parses `Host` header via `parseHost()` (in `src/lib/host.ts`) and rewrites the request path to `/<slug>/...`. URL bar stays unchanged. Apex hosts and unknown subdomains fall through unmodified.
+- **Tenant context**: `src/app/[slug]/layout.tsx` fetches the tenant from `tenant-registry` (`src/lib/tenant-registry.ts`). 404 → `notFound()`; HTTP errors bubble up.
+- **Auth**: `src/auth.ts` is the Auth.js v5 config — Keycloak provider, tenant-context claims (`tenant_id`, `tenant_slug`, `org_roles`, `products`, `plan`, `tenant_status`) propagated via JWT/session callbacks. Real RBAC enforcement lands in M5.2 / M10.1.
 
 ## Deployment
 

eslint.config.mjs

@@ -0,0 +1,13 @@
+// eslint-config-next v16 ships flat-config exports natively; no FlatCompat shim.
+import nextWebVitals from "eslint-config-next/core-web-vitals";
+import nextTypescript from "eslint-config-next/typescript";
+
+const config = [
+  ...nextWebVitals,
+  ...nextTypescript,
+  {
+    ignores: [".next/**", "node_modules/**", "coverage/**", "next-env.d.ts"],
+  },
+];
+
+export default config;

next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

next.config.ts

@@ -0,0 +1,11 @@
+import type { NextConfig } from "next";
+
+const config: NextConfig = {
+  reactStrictMode: true,
+  output: "standalone",
+  experimental: {
+    typedRoutes: true,
+  },
+};
+
+export default config;

package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@breakpilot/portal",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Customer-facing portal + platform-staff backstage. Next.js + Auth.js v5.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20",
+    "pnpm": ">=9"
+  },
+  "scripts": {
+    "dev": "next dev --port 3000",
+    "build": "next build",
+    "start": "next start --port 3000",
+    "lint": "eslint . --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage"
+  },
+  "dependencies": {
+    "next": "16.2.6",
+    "next-auth": "5.0.0-beta.25",
+    "react": "19.0.0",
+    "react-dom": "19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "20.16.10",
+    "@types/react": "19.0.1",
+    "@types/react-dom": "19.0.1",
+    "@vitest/coverage-v8": "2.1.8",
+    "eslint": "9.15.0",
+    "eslint-config-next": "16.2.6",
+    "typescript": "5.7.2",
+    "vitest": "2.1.8"
+  }
+}

src/app/[slug]/dashboard/page.tsx

@@ -0,0 +1,44 @@
+import { auth, signIn, signOut } from "@/auth";
+
+export default async function Dashboard({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const session = await auth();
+
+  if (!session) {
+    async function login() {
+      "use server";
+      await signIn("keycloak", { redirectTo: `/${slug}/dashboard` });
+    }
+    return (
+      <div>
+        <h1>Sign in to {slug}</h1>
+        <form action={login}>
+          <button type="submit">Sign in with Keycloak</button>
+        </form>
+      </div>
+    );
+  }
+
+  async function logout() {
+    "use server";
+    await signOut({ redirectTo: `/${slug}/dashboard` });
+  }
+
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <p>
+        Welcome, {session.user?.name ?? session.user?.email ?? "user"}. This is the{" "}
+        <code>{slug}</code> dashboard. Real product tiles, settings, billing — land
+        in M5.2 / M10.1.
+      </p>
+      <form action={logout} style={{ marginTop: 24 }}>
+        <button type="submit">Sign out</button>
+      </form>
+    </div>
+  );
+}

src/app/[slug]/layout.tsx

@@ -0,0 +1,36 @@
+import { notFound } from "next/navigation";
+import type { ReactNode } from "react";
+import { fetchTenantBySlug } from "@/lib/tenant-registry";
+
+export default async function TenantLayout({
+  children,
+  params,
+}: {
+  children: ReactNode;
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const tenant = await fetchTenantBySlug(slug);
+  if (!tenant) notFound();
+
+  return (
+    <div>
+      <header
+        style={{
+          padding: "12px 24px",
+          borderBottom: "1px solid #eaeaea",
+          background: "white",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "space-between",
+        }}
+      >
+        <strong>{tenant.name}</strong>
+        <span style={{ fontSize: 12, color: "#666" }}>
+          {tenant.plan} · {tenant.status}
+        </span>
+      </header>
+      <main style={{ padding: 24 }}>{children}</main>
+    </div>
+  );
+}

src/app/[slug]/page.tsx

@@ -0,0 +1,10 @@
+import { redirect } from "next/navigation";
+
+export default async function TenantRoot({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  redirect(`/${slug}/dashboard`);
+}

src/app/api/auth/[...nextauth]/route.ts

@@ -0,0 +1,3 @@
+import { handlers } from "@/auth";
+
+export const { GET, POST } = handlers;

src/app/layout.tsx

@@ -0,0 +1,25 @@
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+export const metadata: Metadata = {
+  title: "Breakpilot",
+  description: "Breakpilot Platform — customer portal",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body
+        style={{
+          margin: 0,
+          fontFamily:
+            'system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", sans-serif',
+          background: "#fafafa",
+          color: "#111",
+        }}
+      >
+        {children}
+      </body>
+    </html>
+  );
+}

src/app/page.tsx

@@ -0,0 +1,18 @@
+// Apex landing page. In dev this is what loads at http://localhost:3000.
+// Tenant portals live at http://<slug>.localhost:3000 (middleware rewrites).
+
+export default function Apex() {
+  return (
+    <main style={{ maxWidth: 720, margin: "10vh auto", padding: "0 24px" }}>
+      <h1 style={{ fontSize: 32, marginBottom: 16 }}>Breakpilot</h1>
+      <p>
+        Customer portals live at <code>&lt;tenant&gt;.localhost:3000</code> in dev,{" "}
+        <code>&lt;tenant&gt;.breakpilot.com</code> in prod. Backstage lives at{" "}
+        <code>backstage.&lt;apex&gt;</code>.
+      </p>
+      <p style={{ marginTop: 24 }}>
+        Try: <a href="http://acme.localhost:3000">http://acme.localhost:3000</a>
+      </p>
+    </main>
+  );
+}

src/auth.ts

@@ -0,0 +1,59 @@
+// Auth.js v5 — Keycloak provider.
+//
+// Dev uses the breakpilot-dev realm from platform/orca-platform/dev. The
+// realm's dev-portal client is a public PKCE client; we still pass a
+// non-empty clientSecret because the Keycloak provider requires it
+// structurally — it's unused in the auth code grant for public clients
+// when PKCE is enabled.
+
+import NextAuth from "next-auth";
+import Keycloak from "next-auth/providers/keycloak";
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  providers: [
+    Keycloak({
+      clientId: process.env.KEYCLOAK_CLIENT_ID ?? "dev-portal",
+      clientSecret: process.env.KEYCLOAK_CLIENT_SECRET ?? "unused-public-client",
+      issuer:
+        process.env.KEYCLOAK_ISSUER ??
+        "http://localhost:8080/realms/breakpilot-dev",
+    }),
+  ],
+  callbacks: {
+    async jwt({ token, profile }) {
+      // Pass the breakpilot-dev realm's custom claims through to the session.
+      if (profile) {
+        token.tenant_id = (profile as Record<string, unknown>).tenant_id as
+          | string
+          | undefined;
+        token.tenant_slug = (profile as Record<string, unknown>).tenant_slug as
+          | string
+          | undefined;
+        token.org_roles = (profile as Record<string, unknown>).org_roles as
+          | string[]
+          | undefined;
+        token.products = (profile as Record<string, unknown>).products as
+          | string[]
+          | undefined;
+        token.plan = (profile as Record<string, unknown>).plan as
+          | string
+          | undefined;
+        token.tenant_status = (profile as Record<string, unknown>)
+          .tenant_status as string | undefined;
+      }
+      return token;
+    },
+    async session({ session, token }) {
+      session.user = session.user ?? { name: null, email: null, image: null };
+      Object.assign(session, {
+        tenant_id: token.tenant_id,
+        tenant_slug: token.tenant_slug,
+        org_roles: token.org_roles,
+        products: token.products,
+        plan: token.plan,
+        tenant_status: token.tenant_status,
+      });
+      return session;
+    },
+  },
+});

src/lib/host.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "vitest";
+import { parseHost } from "./host";
+
+describe("parseHost", () => {
+  test("null host → unknown", () => {
+    expect(parseHost(null)).toEqual({ kind: "unknown" });
+    expect(parseHost(undefined)).toEqual({ kind: "unknown" });
+    expect(parseHost("")).toEqual({ kind: "unknown" });
+  });
+
+  test("apex hosts return apex", () => {
+    expect(parseHost("localhost")).toEqual({ kind: "apex" });
+    expect(parseHost("localhost:3000")).toEqual({ kind: "apex" });
+    expect(parseHost("breakpilot.com")).toEqual({ kind: "apex" });
+    expect(parseHost("stage.breakpilot.com")).toEqual({ kind: "apex" });
+  });
+
+  test("tenant subdomain returns slug", () => {
+    expect(parseHost("acme.localhost:3000")).toEqual({ kind: "tenant", slug: "acme" });
+    expect(parseHost("acme.breakpilot.com")).toEqual({ kind: "tenant", slug: "acme" });
+    expect(parseHost("acme.stage.breakpilot.com")).toEqual({ kind: "tenant", slug: "acme" });
+  });
+
+  test("backstage subdomain is reserved", () => {
+    expect(parseHost("backstage.localhost:3000")).toEqual({ kind: "backstage" });
+    expect(parseHost("backstage.breakpilot.com")).toEqual({ kind: "backstage" });
+  });
+
+  test("invalid slugs return unknown", () => {
+    expect(parseHost("a.localhost")).toEqual({ kind: "unknown" }); // too short (1 char)
+    expect(parseHost("foo_bar.localhost")).toEqual({ kind: "unknown" }); // underscore not allowed
+    expect(parseHost("FOO!.localhost")).toEqual({ kind: "unknown" }); // exclamation invalid
+  });
+
+  test("empty subdomain falls back to apex", () => {
+    expect(parseHost(".localhost")).toEqual({ kind: "apex" });
+  });
+
+  test("uppercase host is lowercased", () => {
+    expect(parseHost("ACME.LOCALHOST")).toEqual({ kind: "tenant", slug: "acme" });
+  });
+
+  test("unknown apex returns unknown", () => {
+    expect(parseHost("acme.example.com")).toEqual({ kind: "unknown" });
+  });
+});

src/lib/host.ts

@@ -0,0 +1,41 @@
+// Host → tenant slug parser for the portal middleware.
+//
+// In dev we serve at <slug>.localhost:3000 (e.g. acme.localhost:3000). In
+// prod we serve at <slug>.breakpilot.com. Backstage lives at the apex —
+// no subdomain — and resolves to a fixed `__backstage__` slug.
+
+export type HostMatch =
+  | { kind: "tenant"; slug: string }
+  | { kind: "backstage" }
+  | { kind: "apex" }
+  | { kind: "unknown" };
+
+// Longest-first so `stage.breakpilot.com` is matched before `breakpilot.com`.
+const APEX_HOSTS = ["stage.breakpilot.com", "breakpilot.com", "localhost"];
+const APEX_SET = new Set(APEX_HOSTS);
+
+export function parseHost(host: string | null | undefined): HostMatch {
+  if (!host) return { kind: "unknown" };
+
+  const hostNoPort = host.split(":")[0].toLowerCase();
+
+  if (APEX_SET.has(hostNoPort)) return { kind: "apex" };
+
+  // Strip the known apex suffix to extract the subdomain.
+  for (const apex of APEX_HOSTS) {
+    const suffix = `.${apex}`;
+    if (hostNoPort.endsWith(suffix)) {
+      const sub = hostNoPort.slice(0, -suffix.length);
+      if (!sub) return { kind: "apex" };
+      // Backstage is reserved.
+      if (sub === "backstage") return { kind: "backstage" };
+      // Slugs are [a-z0-9-]{2,40} per the tenant-registry schema check.
+      if (/^[a-z0-9-]{2,40}$/.test(sub)) {
+        return { kind: "tenant", slug: sub };
+      }
+      return { kind: "unknown" };
+    }
+  }
+
+  return { kind: "unknown" };
+}

src/lib/tenant-registry.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { fetchTenantBySlug, type Tenant } from "./tenant-registry";
+
+const SAMPLE: Tenant = {
+  id: "00000000-0000-0000-0000-000000000001",
+  slug: "acme",
+  name: "Acme Inc.",
+  status: "active",
+  plan: "professional",
+  products: ["certifai", "compliance"],
+  created_at: "2026-05-18T22:00:00Z",
+};
+
+const originalFetch = globalThis.fetch;
+const originalRegistryUrl = process.env.TENANT_REGISTRY_URL;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  process.env.TENANT_REGISTRY_URL = originalRegistryUrl;
+  vi.restoreAllMocks();
+});
+
+describe("fetchTenantBySlug", () => {
+  beforeEach(() => {
+    process.env.TENANT_REGISTRY_URL = "http://test:1234";
+  });
+
+  test("200 → parsed tenant", async () => {
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify(SAMPLE), { status: 200 }));
+    const t = await fetchTenantBySlug("acme");
+    expect(t).toEqual(SAMPLE);
+  });
+
+  test("404 → null", async () => {
+    globalThis.fetch = vi.fn(async () => new Response("", { status: 404 }));
+    const t = await fetchTenantBySlug("nope");
+    expect(t).toBeNull();
+  });
+
+  test("500 → throws", async () => {
+    globalThis.fetch = vi.fn(async () => new Response("", { status: 500, statusText: "boom" }));
+    await expect(fetchTenantBySlug("acme")).rejects.toThrow(/tenant-registry: 500/);
+  });
+
+  test("falls back to default base URL when env unset", async () => {
+    delete process.env.TENANT_REGISTRY_URL;
+    const fetchSpy = vi.fn(async () => new Response(JSON.stringify(SAMPLE), { status: 200 }));
+    globalThis.fetch = fetchSpy;
+    await fetchTenantBySlug("acme");
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "http://localhost:8080/v1/tenants/by-slug/acme",
+      expect.any(Object),
+    );
+  });
+
+  test("encodes slug to defend against weird input", async () => {
+    const fetchSpy = vi.fn<typeof fetch>(async () => new Response("", { status: 404 }));
+    globalThis.fetch = fetchSpy;
+    await fetchTenantBySlug("a/b c");
+    const firstCall = fetchSpy.mock.calls[0];
+    expect(firstCall).toBeDefined();
+    expect(firstCall![0]).toBe("http://test:1234/v1/tenants/by-slug/a%2Fb%20c");
+  });
+});

src/lib/tenant-registry.ts

@@ -0,0 +1,29 @@
+// Tenant Registry client — fetches tenant data from the Go service.
+// Skeleton-mode: read-only by-slug lookup. The portal middleware uses this
+// to resolve `<slug>.localhost:3000` → tenant context before rendering.
+
+export type Tenant = {
+  id: string;
+  slug: string;
+  name: string;
+  status: "active" | "trial" | "frozen" | "archived" | "demo";
+  plan: "starter" | "professional" | "enterprise";
+  products: string[];
+  created_at: string;
+};
+
+function baseUrl(): string {
+  return process.env.TENANT_REGISTRY_URL ?? "http://localhost:8080";
+}
+
+export async function fetchTenantBySlug(slug: string): Promise<Tenant | null> {
+  const res = await fetch(`${baseUrl()}/v1/tenants/by-slug/${encodeURIComponent(slug)}`, {
+    headers: { accept: "application/json" },
+    cache: "no-store",
+  });
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    throw new Error(`tenant-registry: ${res.status} ${res.statusText}`);
+  }
+  return (await res.json()) as Tenant;
+}

src/middleware.ts

@@ -0,0 +1,36 @@
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+import { parseHost } from "@/lib/host";
+
+// Host → URL-rewrite. Acme visits acme.localhost:3000/dashboard; we
+// internally rewrite to /acme/dashboard so the [slug] route group renders.
+// URL bar stays unchanged.
+//
+// Backstage (backstage.<apex>) rewrites to /__backstage__/<rest>.
+// Apex hosts (localhost, breakpilot.com) get a marketing/landing page
+// at the root route.
+
+export function middleware(request: NextRequest) {
+  const match = parseHost(request.headers.get("host"));
+  const url = request.nextUrl.clone();
+
+  if (match.kind === "tenant") {
+    if (!url.pathname.startsWith(`/${match.slug}/`) && url.pathname !== `/${match.slug}`) {
+      url.pathname = `/${match.slug}${url.pathname === "/" ? "" : url.pathname}`;
+      return NextResponse.rewrite(url);
+    }
+  } else if (match.kind === "backstage") {
+    if (!url.pathname.startsWith("/__backstage__")) {
+      url.pathname = `/__backstage__${url.pathname === "/" ? "" : url.pathname}`;
+      return NextResponse.rewrite(url);
+    }
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  // Skip Next internals + API + static assets so middleware doesn't
+  // double-rewrite the auth callback or _next/static.
+  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
+};

tsconfig.json

@@ -0,0 +1,43 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    },
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    ".next"
+  ]
+}

vitest.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      // Skeleton-mode: only enforce coverage on the tested module (src/lib).
+      // Re-include the rest of src/ once real code + real tests land.
+      include: ["src/lib/**/*.ts"],
+      reporter: ["text", "json-summary"],
+      thresholds: {
+        lines: 100,
+        functions: 100,
+        branches: 100,
+        statements: 100,
+      },
+    },
+  },
+});