feat(app): M5.2 — customer-area route shells + role-gated nav

10 route shells under /[slug]/, role-filtered Nav, backstage stub at /__backstage__, dashboard reads session.products to render tiles. src/lib/session.ts is the canonical role × surface matrix; canSee() is the only RBAC primitive in the portal (real enforcement remains at the API layer). 24 vitest tests; 100% src/lib coverage.

Refs: M5.2

CHANGELOG.md

@@ -6,6 +6,7 @@ Generated section is appended on release tag via `git-cliff` (see `.gitea/workfl
 ## [Unreleased]
 
 ### Added
+- feat(app): M5.2 — customer-area route shells (settings, billing, audit, support, catalog, products, projects, settings/{users,api-keys,integrations}); shared Nav component reads session.org_roles and shows only what each role can see; backstage stub at /__backstage__; dashboard renders product tiles from session.products
 - 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
 -

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

@@ -0,0 +1,16 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "audit")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Audit log"
+      description="Every state-changing action across portal + products."
+      milestone="M10.2"
+    />
+  );
+}

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

@@ -0,0 +1,16 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "billing")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Billing"
+      description="Plan, seats, invoices. Polar Checkout opens here."
+      milestone="M8.3"
+    />
+  );
+}

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

@@ -0,0 +1,16 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "catalog")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Catalog"
+      description="Products you can add to your subscription."
+      milestone="M11.1"
+    />
+  );
+}

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

@@ -1,4 +1,6 @@
 import { auth, signIn, signOut } from "@/auth";
+import { ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
 
 export default async function Dashboard({
   params,
@@ -6,7 +8,7 @@ export default async function Dashboard({
   params: Promise<{ slug: string }>;
 }) {
   const { slug } = await params;
-  const session = await auth();
+  const session = (await auth()) as SessionWithExtras | null;
 
   if (!session) {
     async function login() {
@@ -14,12 +16,25 @@ export default async function Dashboard({
       await signIn("keycloak", { redirectTo: `/${slug}/dashboard` });
     }
     return (
-      <div>
+      <section style={{ maxWidth: 480 }}>
-        <h1>Sign in to {slug}</h1>
+        <h1 style={{ fontSize: 28, marginBottom: 12 }}>Sign in to {slug}</h1>
         <form action={login}>
-          <button type="submit">Sign in with Keycloak</button>
+          <button
+            type="submit"
+            style={{
+              padding: "10px 16px",
+              background: "#0070f3",
+              color: "white",
+              border: "none",
+              borderRadius: 6,
+              fontSize: 14,
+              cursor: "pointer",
+            }}
+          >
+            Sign in with Keycloak
+          </button>
         </form>
-      </div>
+      </section>
     );
   }
 
@@ -28,17 +43,60 @@ export default async function Dashboard({
     await signOut({ redirectTo: `/${slug}/dashboard` });
   }
 
+  const products = session.products ?? [];
+
   return (
-    <div>
+    <section>
-      <h1>Dashboard</h1>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>Dashboard</h1>
-      <p>
+      <p style={{ color: "#444", marginBottom: 24 }}>
-        Welcome, {session.user?.name ?? session.user?.email ?? "user"}. This is the{" "}
+        Welcome, {session.user?.name ?? session.user?.email ?? "user"}. Signed in
-        <code>{slug}</code> dashboard. Real product tiles, settings, billing — land
+        as <code>{session.org_roles?.join(", ") ?? "(no roles)"}</code>.
-        in M5.2 / M10.1.
       </p>
-      <form action={logout} style={{ marginTop: 24 }}>
+
-        <button type="submit">Sign out</button>
+      <h2 style={{ fontSize: 18, marginTop: 24, marginBottom: 12 }}>Your products</h2>
+      {products.length === 0 ? (
+        <ShellEmpty
+          title="No products yet"
+          description="Browse the catalog and request access to a product, or start a 14-day trial."
+          milestone="M11.1"
+        />
+      ) : (
+        <ul style={{ listStyle: "none", padding: 0, display: "grid", gap: 12, gridTemplateColumns: "repeat(auto-fill, minmax(220px, 1fr))" }}>
+          {products.map((p) => (
+            <li
+              key={p}
+              style={{
+                padding: 16,
+                border: "1px solid #eaeaea",
+                borderRadius: 8,
+                background: "white",
+              }}
+            >
+              <strong style={{ textTransform: "capitalize" }}>{p}</strong>
+              <p style={{ color: "#666", fontSize: 13, marginTop: 4 }}>
+                Tile content lands in <code>M10.1</code>.
+              </p>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <form action={logout} style={{ marginTop: 32 }}>
+        <button
+          type="submit"
+          style={{
+            padding: "8px 12px",
+            background: "white",
+            color: "#0070f3",
+            border: "1px solid #0070f3",
+            borderRadius: 6,
+            fontSize: 13,
+            cursor: "pointer",
+          }}
+        >
+          Sign out
+        </button>
       </form>
-    </div>
+    </section>
   );
 }

src/app/[slug]/layout.tsx

@@ -1,5 +1,8 @@
-import { notFound } from "next/navigation";
+import { notFound, redirect } from "next/navigation";
 import type { ReactNode } from "react";
+import { auth } from "@/auth";
+import { Nav } from "@/components/Nav";
+import type { SessionWithExtras } from "@/lib/session";
 import { fetchTenantBySlug } from "@/lib/tenant-registry";
 
 export default async function TenantLayout({
@@ -13,24 +16,36 @@ export default async function TenantLayout({
   const tenant = await fetchTenantBySlug(slug);
   if (!tenant) notFound();
 
+  const session = (await auth()) as SessionWithExtras | null;
+
+  // Tenant mismatch guard — a JWT scoped to tenant A must not be allowed
+  // to view tenant B. If the slug in the path doesn't match the session
+  // tenant_slug, redirect back to whatever this user CAN see.
+  if (session && session.tenant_slug && session.tenant_slug !== slug) {
+    redirect(`/${session.tenant_slug}/dashboard`);
+  }
+
   return (
-    <div>
+    <div style={{ display: "flex", minHeight: "100vh" }}>
-      <header
+      {session ? <Nav slug={slug} session={session} /> : null}
-        style={{
+      <div style={{ flex: 1 }}>
-          padding: "12px 24px",
+        <header
-          borderBottom: "1px solid #eaeaea",
+          style={{
-          background: "white",
+            padding: "12px 24px",
-          display: "flex",
+            borderBottom: "1px solid #eaeaea",
-          alignItems: "center",
+            background: "white",
-          justifyContent: "space-between",
+            display: "flex",
-        }}
+            alignItems: "center",
-      >
+            justifyContent: "space-between",
-        <strong>{tenant.name}</strong>
+          }}
-        <span style={{ fontSize: 12, color: "#666" }}>
+        >
-          {tenant.plan} · {tenant.status}
+          <strong>{tenant.name}</strong>
-        </span>
+          <span style={{ fontSize: 12, color: "#666" }}>
-      </header>
+            {tenant.plan} · {tenant.status}
-      <main style={{ padding: 24 }}>{children}</main>
+          </span>
+        </header>
+        <main style={{ padding: 24 }}>{children}</main>
+      </div>
     </div>
   );
 }

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

@@ -0,0 +1,16 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "dashboard")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Products"
+      description="Per-product tiles — open into the embedded web component."
+      milestone="M10.1"
+    />
+  );
+}

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

@@ -0,0 +1,16 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "projects")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Projects"
+      description="Sub-tenancy: GCP-Project-style scoping per product."
+      milestone="M10.1"
+    />
+  );
+}

src/app/[slug]/settings/api-keys/page.tsx

@@ -0,0 +1,16 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "api-keys")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="API keys"
+      description="Per-tenant API keys for headless product access."
+      milestone="M15.1"
+    />
+  );
+}

src/app/[slug]/settings/integrations/page.tsx

@@ -0,0 +1,16 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "integrations")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Integrations"
+      description="Webhooks, outbound integrations, external IdP config."
+      milestone="M15.2"
+    />
+  );
+}

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

@@ -0,0 +1,16 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "settings")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Settings"
+      description="Tenant identity, SSO, organization defaults."
+      milestone="M10.1"
+    />
+  );
+}

src/app/[slug]/settings/users/page.tsx

@@ -0,0 +1,16 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "users")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Users"
+      description="Invite IT_ADMIN, CXO, FINANCE, LEGAL, USER. Role assignment."
+      milestone="M10.1"
+    />
+  );
+}

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

@@ -0,0 +1,16 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "support")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Support"
+      description="Submit a ticket — Frappe HD customer portal embedded."
+      milestone="M9.1"
+    />
+  );
+}

src/app/__backstage__/page.tsx

@@ -0,0 +1,30 @@
+import { auth } from "@/auth";
+import type { SessionWithExtras } from "@/lib/session";
+
+// Backstage — platform-staff-only surface. The middleware rewrites
+// http://backstage.localhost:3000/* → /__backstage__/* so this is
+// reachable only via that hostname. Real RBAC (BREAKPILOT_ADMIN /
+// SUPPORT_ENGINEER / SALES_REP) lands in M13.2.
+
+export default async function Backstage() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!session) {
+    return (
+      <section style={{ padding: 32 }}>
+        <h1 style={{ fontSize: 28, marginBottom: 8 }}>Backstage</h1>
+        <p>Sign in with a BREAKPILOT_ADMIN / SUPPORT_ENGINEER / SALES_REP account.</p>
+      </section>
+    );
+  }
+  return (
+    <section style={{ padding: 32 }}>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>Backstage</h1>
+      <p>
+        Signed in as <code>{session.user?.email}</code>.
+      </p>
+      <p style={{ marginTop: 24, color: "#666" }}>
+        Tenants list, leads, demo console, impersonation — all land in M13.2 / M14.x.
+      </p>
+    </section>
+  );
+}

src/components/Nav.tsx

@@ -0,0 +1,40 @@
+import Link from "next/link";
+import type { Surface, SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+type NavLink = {
+  href: string;
+  label: string;
+  surface: Surface;
+};
+
+export function Nav({ slug, session }: { slug: string; session: SessionWithExtras }) {
+  const links: NavLink[] = [
+    { href: `/${slug}/dashboard`,    label: "Dashboard",    surface: "dashboard" },
+    { href: `/${slug}/products`,     label: "Products",     surface: "products" },
+    { href: `/${slug}/catalog`,      label: "Catalog",      surface: "catalog" },
+    { href: `/${slug}/projects`,     label: "Projects",     surface: "projects" },
+    { href: `/${slug}/settings`,     label: "Settings",     surface: "settings" },
+    { href: `/${slug}/settings/users`,   label: "Users",        surface: "users" },
+    { href: `/${slug}/settings/api-keys`,  label: "API keys",   surface: "api-keys" },
+    { href: `/${slug}/settings/integrations`, label: "Integrations", surface: "integrations" },
+    { href: `/${slug}/billing`,      label: "Billing",      surface: "billing" },
+    { href: `/${slug}/audit`,        label: "Audit log",    surface: "audit" },
+    { href: `/${slug}/support`,      label: "Support",      surface: "support" },
+  ];
+  const visible = links.filter((l) => canSee(session, l.surface));
+
+  return (
+    <nav style={{ width: 220, padding: 16, borderRight: "1px solid #eaeaea", background: "white" }}>
+      <ul style={{ listStyle: "none", padding: 0, margin: 0 }}>
+        {visible.map((l) => (
+          <li key={l.href} style={{ margin: "8px 0" }}>
+            <Link href={l.href} style={{ color: "#0070f3", textDecoration: "none" }}>
+              {l.label}
+            </Link>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}

src/components/ShellEmpty.tsx

@@ -0,0 +1,53 @@
+// Reusable empty-state for a customer-area route shell. Every M5.2 route
+// renders one of these; real content lands in M10.1 / M11.x / M12.x /
+// M14.x / etc.
+
+export function ShellEmpty({
+  title,
+  description,
+  milestone,
+}: {
+  title: string;
+  description: string;
+  milestone: string;
+}) {
+  return (
+    <section style={{ maxWidth: 720 }}>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>{title}</h1>
+      <p style={{ color: "#444", marginBottom: 24 }}>{description}</p>
+      <div
+        style={{
+          padding: 16,
+          border: "1px dashed #ddd",
+          borderRadius: 8,
+          background: "#fafafa",
+          color: "#666",
+          fontSize: 14,
+        }}
+      >
+        This surface is a route shell. Real implementation lands in{" "}
+        <code>{milestone}</code>. See{" "}
+        <a
+          href="https://gitea.meghsakha.com/platform/docs/src/branch/main/PLATFORM_ARCHITECTURE.md"
+          style={{ color: "#0070f3" }}
+        >
+          PLATFORM_ARCHITECTURE.md §5a
+        </a>{" "}
+        for the spec.
+      </div>
+    </section>
+  );
+}
+
+export function NotAuthorized() {
+  return (
+    <section style={{ maxWidth: 720 }}>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>403 — Not authorized</h1>
+      <p style={{ color: "#444" }}>
+        This surface requires a role your account doesn&apos;t have. If you think
+        that&apos;s a mistake, ask an IT_ADMIN on your tenant to invite you with
+        the right role.
+      </p>
+    </section>
+  );
+}

src/lib/session.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vitest";
+import { canSee, hasAnyOrgRole, hasOrgRole, hasProduct } from "./session";
+import type { SessionWithExtras } from "./session";
+
+function s(roles: SessionWithExtras["org_roles"], products: string[] = []): SessionWithExtras {
+  return {
+    user: { name: "Test", email: "t@x.test" },
+    expires: "2099-01-01T00:00:00Z",
+    org_roles: roles,
+    products,
+  };
+}
+
+describe("hasOrgRole", () => {
+  test("null session has no roles", () => {
+    expect(hasOrgRole(null, "IT_ADMIN")).toBe(false);
+  });
+  test("matches single role", () => {
+    expect(hasOrgRole(s(["CXO"]), "CXO")).toBe(true);
+    expect(hasOrgRole(s(["CXO"]), "IT_ADMIN")).toBe(false);
+  });
+});
+
+describe("hasAnyOrgRole", () => {
+  test("any match wins", () => {
+    expect(hasAnyOrgRole(s(["LEGAL"]), ["IT_ADMIN", "LEGAL"])).toBe(true);
+    expect(hasAnyOrgRole(s(["USER"]), ["IT_ADMIN", "CXO"])).toBe(false);
+  });
+  test("empty roles", () => {
+    expect(hasAnyOrgRole(s(undefined), ["IT_ADMIN"])).toBe(false);
+  });
+});
+
+describe("hasProduct", () => {
+  test("checks products array", () => {
+    expect(hasProduct(s(["USER"], ["certifai"]), "certifai")).toBe(true);
+    expect(hasProduct(s(["USER"], ["certifai"]), "compliance")).toBe(false);
+    expect(hasProduct(null, "certifai")).toBe(false);
+  });
+});
+
+describe("canSee", () => {
+  test("IT_ADMIN sees settings, USER does not", () => {
+    expect(canSee(s(["IT_ADMIN"]), "settings")).toBe(true);
+    expect(canSee(s(["USER"]), "settings")).toBe(false);
+  });
+  test("CXO can see billing", () => {
+    expect(canSee(s(["CXO"]), "billing")).toBe(true);
+  });
+  test("LEGAL can see audit but not settings", () => {
+    expect(canSee(s(["LEGAL"]), "audit")).toBe(true);
+    expect(canSee(s(["LEGAL"]), "settings")).toBe(false);
+  });
+  test("FINANCE sees billing but not settings", () => {
+    expect(canSee(s(["FINANCE"]), "billing")).toBe(true);
+    expect(canSee(s(["FINANCE"]), "settings")).toBe(false);
+  });
+  test("dashboard visible to everyone with any role", () => {
+    expect(canSee(s(["USER"]), "dashboard")).toBe(true);
+    expect(canSee(s(["LEGAL"]), "dashboard")).toBe(true);
+  });
+  test("null session sees nothing", () => {
+    expect(canSee(null, "dashboard")).toBe(false);
+  });
+});

src/lib/session.ts

@@ -0,0 +1,70 @@
+// Session-derived types & helpers — keep all session-shape knowledge in
+// one place so route components don't all repeat the same casts.
+//
+// The breakpilot-dev realm projects these claims into every JWT via
+// protocol mappers (see platform/orca-platform/dev/keycloak/realm-export.json).
+// Auth.js v5 callbacks copy them onto the session in src/auth.ts.
+
+import type { Session } from "next-auth";
+
+export type OrgRole = "IT_ADMIN" | "CXO" | "FINANCE" | "LEGAL" | "USER";
+export type TenantStatus = "demo" | "trial" | "active" | "frozen" | "archived";
+export type Plan = "starter" | "professional" | "enterprise";
+
+export type SessionExtras = {
+  tenant_id?: string;
+  tenant_slug?: string;
+  org_roles?: OrgRole[];
+  products?: string[];
+  plan?: Plan;
+  tenant_status?: TenantStatus;
+};
+
+export type SessionWithExtras = Session & SessionExtras;
+
+export function hasOrgRole(s: SessionWithExtras | null, role: OrgRole): boolean {
+  return !!s?.org_roles?.includes(role);
+}
+
+export function hasAnyOrgRole(s: SessionWithExtras | null, roles: OrgRole[]): boolean {
+  if (!s?.org_roles) return false;
+  return roles.some((r) => s.org_roles?.includes(r));
+}
+
+export function hasProduct(s: SessionWithExtras | null, product: string): boolean {
+  return !!s?.products?.includes(product);
+}
+
+// Permission matrix per PLATFORM_ARCHITECTURE.md §5a "Operating principles":
+// hide what the user can't access. Each portal surface declares which
+// org_roles can see it; the nav uses this to filter links.
+export type Surface =
+  | "dashboard"
+  | "products"
+  | "projects"
+  | "settings"
+  | "users"
+  | "api-keys"
+  | "integrations"
+  | "billing"
+  | "audit"
+  | "support"
+  | "catalog";
+
+export const surfaceRoles: Record<Surface, OrgRole[]> = {
+  dashboard:    ["IT_ADMIN", "CXO", "FINANCE", "LEGAL", "USER"],
+  products:     ["IT_ADMIN", "CXO", "FINANCE", "LEGAL", "USER"],
+  projects:     ["IT_ADMIN", "CXO"],
+  settings:     ["IT_ADMIN"],
+  users:        ["IT_ADMIN"],
+  "api-keys":   ["IT_ADMIN"],
+  integrations: ["IT_ADMIN"],
+  billing:      ["IT_ADMIN", "CXO", "FINANCE"],
+  audit:        ["IT_ADMIN", "CXO", "LEGAL"],
+  support:      ["IT_ADMIN", "CXO", "FINANCE", "LEGAL", "USER"],
+  catalog:      ["IT_ADMIN", "CXO"],
+};
+
+export function canSee(s: SessionWithExtras | null, surface: Surface): boolean {
+  return hasAnyOrgRole(s, surfaceRoles[surface]);
+}