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.

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;
+}