@terpjs/react-core 0.1.0

package/src/bootstrap.tsx

@@ -0,0 +1,270 @@
+import { RouterProvider } from "@tanstack/react-router";
+import { StrictMode } from "react";
+import type { ComponentType, ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import type { ModuleManifest } from "@terpjs/contract";
+
+import { LoginView } from "./LoginView";
+import type { DevCredentials } from "./LoginView";
+import { RequireAuth } from "./RequireAuth";
+import { TerpProvider } from "./TerpProvider";
+import { AdminHub } from "./admin/AdminHub";
+import { adminModule } from "./admin/module";
+import { LocaleProvider } from "./locale";
+import type { LocaleCatalog } from "./locale";
+import { buildAppRouter } from "./router";
+import type { SsoProvider } from "./sso";
+import { ThemeProvider } from "./theme";
+import type { Theme } from "./theme";
+import { ToastProvider } from "./toast";
+
+/** A frontend module: its stack-agnostic manifest and the view components it names. */
+export interface TerpModule {
+  manifest: ModuleManifest;
+  views: Record<string, ComponentType>;
+}
+
+/**
+ * Which packaged admin screens to ship — one flag per backend capability the area
+ * fronts. Omitted flags default to `true`, so `{ groups: false }` is the whole
+ * "users + audit without groups" configuration: the groups routes, hub card and
+ * stat call disappear while the rest of the area stays packaged.
+ */
+export interface AdminAreaSections {
+  /** The users overview / create / detail screens (terp-cap-users). */
+  users?: boolean;
+  /** The groups overview / create / detail screens (terp-cap-groups). */
+  groups?: boolean;
+  /** The audit-log overview (terp-cap-audit). */
+  audit?: boolean;
+}
+
+/** Route-path prefix per admin section, used to filter the packaged manifest. */
+const ADMIN_SECTION_PREFIXES: Record<keyof AdminAreaSections, string> = {
+  users: "/admin/users",
+  groups: "/admin/groups",
+  audit: "/admin/audit",
+};
+
+function resolveAdminSections(
+  config: boolean | AdminAreaSections,
+): Required<AdminAreaSections> {
+  const sections = typeof config === "boolean" ? {} : config;
+  return {
+    users: sections.users !== false,
+    groups: sections.groups !== false,
+    audit: sections.audit !== false,
+  };
+}
+
+function isTerpModule(value: unknown): value is TerpModule {
+  return (
+    typeof value === "object" && value !== null && "manifest" in value && "views" in value
+  );
+}
+
+/**
+ * Merge discovered module files into the manifests + views that build the app router.
+ * Pass the result of an import.meta.glob over "./modules/<name>/module.tsx"; each module
+ * file must export `manifest` and `views`, so a new module is wired by dropping a
+ * folder — no central registry to edit.
+ */
+export function collectModules(modules: Record<string, unknown>): {
+  manifests: ModuleManifest[];
+  views: Record<string, ComponentType>;
+} {
+  const manifests: ModuleManifest[] = [];
+  const views: Record<string, ComponentType> = {};
+  for (const [path, mod] of Object.entries(modules)) {
+    if (!isTerpModule(mod)) {
+      throw new Error(`Terp module '${path}' must export \`manifest\` and \`views\`.`);
+    }
+    manifests.push(mod.manifest);
+    for (const [viewId, View] of Object.entries(mod.views)) {
+      if (views[viewId] !== undefined) {
+        throw new Error(`Terp view '${viewId}' is exported by more than one module.`);
+      }
+      views[viewId] = View;
+    }
+  }
+  return { manifests, views };
+}
+
+export interface RenderTerpAppOptions {
+  /** App title shown in the shell's sidebar brand (and the default footer). */
+  title: string;
+  /** Discovered modules from an import.meta.glob over "./modules/<name>/module.tsx" (eager). */
+  modules: Record<string, unknown>;
+  /** Brand mark in the sidebar (any rendered node); default: the placeholder TerpMark. */
+  logo?: ReactNode;
+  /** Footer line under the content; default: a muted line with the app title. */
+  footer?: ReactNode;
+  /**
+   * Ship the packaged admin area (default `true`): the admin-gated sidebar entry, the
+   * `/admin` hub, and the users / groups / audit screens over the base-profile
+   * capabilities. An app route claiming one of its paths overrides that screen;
+   * `false` drops the whole area (e.g. an app building its own admin surface).
+   * A partial {@link AdminAreaSections} object keeps the area but selects which
+   * capability screens it ships — e.g. `{ groups: false }` for a users + audit
+   * profile without groups.
+   */
+  adminArea?: boolean | AdminAreaSections;
+  /** Backend API origin; default "" (same-origin, for a dev proxy). */
+  baseUrl?: string;
+  /** Signed-out screen; default the built-in {@link LoginView}. */
+  login?: ReactNode;
+  /** SSO providers offered by the default {@link LoginView} (ignored when `login` is set). */
+  ssoProviders?: readonly SsoProvider[];
+  /**
+   * Dev-only fill button on the default {@link LoginView} (ignored when `login` is set).
+   * Gate it on the build — `import.meta.env.DEV ? { email, password } : undefined` — so the
+   * credentials are statically stripped from production bundles; never pass real secrets.
+   */
+  devCredentials?: DevCredentials;
+  /** SPA path prefix the IdP redirects back to; default "/auth/callback" (ADR 0058). */
+  ssoCallbackPath?: string;
+  /**
+   * The app's locales, keyed by BCP-47 code (default `{ en: LOCALE_EN }`). Each catalog
+   * overrides the framework strings for that locale; the built-in {@link UserMenu} offers
+   * a language switcher as soon as more than one locale is declared.
+   */
+  locales?: Record<string, LocaleCatalog>;
+  /** Starting locale when the user has not chosen one; default: the first `locales` key. */
+  defaultLocale?: string;
+  /** Starting theme when the user has not chosen one; default "system" (OS preference). */
+  defaultTheme?: Theme;
+  /**
+   * Opt into a slot-typed layout contract (ADR 0079), e.g. `"standard"`: every routed
+   * archetype's body slot then accepts only the components the contract allows there,
+   * verified at runtime (fail closed). Keep it in sync with the app's checked-in
+   * `layout-contract.json` (the `terp/layout-contract` lint half).
+   */
+  layoutContract?: string;
+  /** Mount point; default `document.getElementById("root")`. */
+  rootElement?: HTMLElement | null;
+}
+
+/**
+ * Merge the packaged admin area into collected modules (the `renderTerpApp` default).
+ * Pure and collision-aware: per path the app wins — an app route claiming an admin
+ * path drops that packaged screen (mirroring the built-in /profile rule) — and the
+ * sidebar's Admin entry disappears with the hub. Disabled (`false`) it returns the
+ * inputs untouched; an {@link AdminAreaSections} object keeps the area but ships
+ * only the selected capability screens (the hub renders one card per kept section).
+ */
+export function withAdminArea(
+  manifests: ModuleManifest[],
+  views: Record<string, ComponentType>,
+  config: boolean | AdminAreaSections,
+): { manifests: ModuleManifest[]; views: Record<string, ComponentType> } {
+  if (config === false) {
+    return { manifests, views };
+  }
+  const sections = resolveAdminSections(config);
+  const sectionAllows = (path: string): boolean =>
+    (Object.keys(ADMIN_SECTION_PREFIXES) as (keyof AdminAreaSections)[]).every(
+      (section) =>
+        sections[section] || !path.startsWith(ADMIN_SECTION_PREFIXES[section]),
+    );
+  const claimed = new Set(
+    manifests.flatMap((manifest) => manifest.routes.map((route) => route.path)),
+  );
+  const routes = adminModule.manifest.routes.filter(
+    (route) => !claimed.has(route.path) && sectionAllows(route.path),
+  );
+  // A view-id collision without a path claim would silently drop a packaged screen
+  // the hub still links to — refuse it loudly (claim the path to override a screen,
+  // or rename the app view; mirrors collectModules' duplicate-view error).
+  const collisions = routes
+    .filter((route) => views[route.view] !== undefined)
+    .map((route) => route.view);
+  if (collisions.length > 0) {
+    throw new Error(
+      "Terp view id(s) collide with the packaged admin area: " +
+        collisions.join(", ") +
+        ". Rename the app view(s), claim the admin route path(s) to override the " +
+        "screen(s), or disable the area with adminArea: false.",
+    );
+  }
+  if (routes.length === 0) {
+    return { manifests, views };
+  }
+  const merged = { ...views };
+  const allSections = sections.users && sections.groups && sections.audit;
+  for (const route of routes) {
+    if (route.view === "TerpAdminHub" && !allSections) {
+      // The hub mirrors the selection: one card per kept section (and no stat
+      // call for a dropped one), so a lean profile never dead-links.
+      merged[route.view] = function TerpAdminHubSelected() {
+        return <AdminHub sections={sections} />;
+      };
+      continue;
+    }
+    merged[route.view] = adminModule.views[route.view]!;
+  }
+  return {
+    manifests: [
+      ...manifests,
+      {
+        ...adminModule.manifest,
+        routes,
+        nav: routes.some((route) => route.path === "/admin")
+          ? adminModule.manifest.nav
+          : [],
+      },
+    ],
+    views: merged,
+  };
+}
+
+/**
+ * Render a complete Terp app in one call: discover the modules, build the router, and mount
+ * the provider + auth gate + shell. A consumer's `main.tsx` is just this plus the token
+ * stylesheet import. Drop to `TerpProvider` + `buildAppRouter` for full control.
+ */
+export function renderTerpApp(options: RenderTerpAppOptions): void {
+  const collected = collectModules(options.modules);
+  const { manifests, views } = withAdminArea(
+    collected.manifests,
+    collected.views,
+    options.adminArea ?? true,
+  );
+  const router = buildAppRouter(manifests, {
+    views,
+    title: options.title,
+    logo: options.logo,
+    footer: options.footer,
+    layoutContract: options.layoutContract,
+  });
+  const root = options.rootElement ?? document.getElementById("root");
+  if (!root) {
+    throw new Error('renderTerpApp: no root element (add <div id="root"> or pass rootElement).');
+  }
+  createRoot(root).render(
+    <StrictMode>
+      <ThemeProvider defaultTheme={options.defaultTheme}>
+        <LocaleProvider
+          locales={options.locales ?? { en: {} }}
+          defaultLocale={options.defaultLocale}
+        >
+          <TerpProvider baseUrl={options.baseUrl ?? ""} ssoCallbackPath={options.ssoCallbackPath}>
+            <ToastProvider>
+              <RequireAuth
+                fallback={
+                  options.login ?? (
+                    <LoginView
+                      ssoProviders={options.ssoProviders}
+                      devCredentials={options.devCredentials}
+                    />
+                  )
+                }
+              >
+                <RouterProvider router={router} />
+              </RequireAuth>
+            </ToastProvider>
+          </TerpProvider>
+        </LocaleProvider>
+      </ThemeProvider>
+    </StrictMode>,
+  );
+}

package/src/capabilities.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+
+import { canPerform, DEFAULT_RANK_THRESHOLDS, type RankThresholds } from "./capabilities";
+
+describe("canPerform", () => {
+  it("gates by the default viewer/editor/admin ladder", () => {
+    expect(canPerform(10, "read")).toBe(true);
+    expect(canPerform(10, "write")).toBe(false);
+    expect(canPerform(20, "write")).toBe(true);
+    expect(canPerform(20, "admin")).toBe(false);
+    expect(canPerform(30, "admin")).toBe(true);
+  });
+
+  it("honours custom thresholds for a different role model", () => {
+    const flat: RankThresholds = { read: 0, write: 0, admin: 100 };
+    expect(canPerform(0, "write", flat)).toBe(true);
+    expect(canPerform(0, "admin", flat)).toBe(false);
+    expect(canPerform(100, "admin", flat)).toBe(true);
+  });
+
+  it("exposes the bundled ladder as the default", () => {
+    expect(DEFAULT_RANK_THRESHOLDS).toEqual({ read: 10, write: 20, admin: 30 });
+  });
+});

package/src/capabilities.ts

@@ -0,0 +1,26 @@
+import type { Action } from "@terpjs/contract";
+
+/**
+ * The minimum backend role rank that may perform each coarse UI {@link Action}.
+ * The default is the bundled viewer/editor/admin ladder (ADR 0004 / 0022); an app
+ * overrides the thresholds for a different role model.
+ */
+export type RankThresholds = Record<Action, number>;
+
+export const DEFAULT_RANK_THRESHOLDS: RankThresholds = {
+  read: 10,
+  write: 20,
+  admin: 30,
+};
+
+/**
+ * Whether a caller with `roleRank` may perform `action` under `thresholds`. This is the
+ * UI gate only; the backend independently enforces authorization on every request.
+ */
+export function canPerform(
+  roleRank: number,
+  action: Action,
+  thresholds: RankThresholds = DEFAULT_RANK_THRESHOLDS,
+): boolean {
+  return roleRank >= thresholds[action];
+}

package/src/createAuthClient.test.ts

@@ -0,0 +1,176 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAuthClient } from "./createAuthClient";
+
+function jsonResponse(): Response {
+  return new Response("{}", {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("createAuthClient", () => {
+  it("omits the Authorization header when there is no token", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async () => jsonResponse());
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = createAuthClient("https://api.test", () => null);
+    await client.GET("/api/v1/me/", {});
+
+    const request = fetchMock.mock.calls[0][0] as Request;
+    expect(request.headers.get("Authorization")).toBeNull();
+    expect(request.credentials).toBe("include");
+  });
+
+  it("attaches the live bearer token, reflecting a post-login change", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async () => jsonResponse());
+    vi.stubGlobal("fetch", fetchMock);
+
+    let token: string | null = null;
+    const client = createAuthClient("https://api.test", () => token);
+
+    await client.GET("/api/v1/me/", {});
+    expect((fetchMock.mock.calls[0][0] as Request).headers.get("Authorization")).toBeNull();
+
+    token = "abc123";
+    await client.GET("/api/v1/me/", {});
+    expect((fetchMock.mock.calls[1][0] as Request).headers.get("Authorization")).toBe(
+      "Bearer abc123",
+    );
+  });
+
+  it("refreshes and retries once on a 401 to an authenticated request", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async () => {
+      if (fetchMock.mock.calls.length === 1) {
+        return new Response("{}", { status: 401 });
+      }
+      return jsonResponse();
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const onUnauthorized = vi.fn();
+    const refreshAccessToken = vi.fn(async () => "new-token");
+    const client = createAuthClient("https://api.test", () => "old-token", {
+      refreshAccessToken,
+      onUnauthorized,
+    });
+
+    await client.GET("/api/v1/me/", {});
+
+    expect(refreshAccessToken).toHaveBeenCalledOnce();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect((fetchMock.mock.calls[0][0] as Request).headers.get("Authorization")).toBe(
+      "Bearer old-token",
+    );
+    expect((fetchMock.mock.calls[1][0] as Request).headers.get("Authorization")).toBe(
+      "Bearer new-token",
+    );
+    expect(onUnauthorized).not.toHaveBeenCalled();
+  });
+
+  it("coalesces concurrent 401s into one refresh call", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async (input) => {
+      const auth = (input as Request).headers.get("Authorization");
+      if (auth === "Bearer old-token") {
+        return new Response("{}", { status: 401 });
+      }
+      return jsonResponse();
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    let resolveRefresh!: (token: string) => void;
+    const refreshAccessToken = vi.fn(
+      () => new Promise<string>((resolve) => {
+        resolveRefresh = resolve;
+      }),
+    );
+    const client = createAuthClient("https://api.test", () => "old-token", {
+      refreshAccessToken,
+      onUnauthorized: vi.fn(),
+    });
+
+    const first = client.GET("/api/v1/me/", {});
+    const second = client.GET("/api/v1/me/", {});
+    await vi.waitFor(() => expect(refreshAccessToken).toHaveBeenCalledOnce());
+    resolveRefresh("fresh-token");
+    await Promise.all([first, second]);
+
+    expect(refreshAccessToken).toHaveBeenCalledOnce();
+    const freshRetries = fetchMock.mock.calls.filter(
+      ([input]) => (input as Request).headers.get("Authorization") === "Bearer fresh-token",
+    );
+    expect(freshRetries).toHaveLength(2);
+  });
+
+  it("clears the session when a 401 cannot be refreshed", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async () => new Response("{}", { status: 401 })),
+    );
+    const onUnauthorized = vi.fn();
+    const client = createAuthClient("https://api.test", () => "tok", {
+      refreshAccessToken: vi.fn(async () => null),
+      onUnauthorized,
+    });
+
+    await client.GET("/api/v1/me/", {});
+    expect(onUnauthorized).toHaveBeenCalledOnce();
+  });
+
+  it("clears the session when the replayed request is also rejected with 401", async () => {
+    // Refresh succeeds but the subject was revoked between refresh and replay: the replay
+    // 401 must still clear the session instead of leaving a signed-in shell over empty data.
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async () => new Response("{}", { status: 401 })),
+    );
+    const onUnauthorized = vi.fn();
+    const client = createAuthClient("https://api.test", () => "tok", {
+      refreshAccessToken: vi.fn(async () => "fresh-token"),
+      onUnauthorized,
+    });
+
+    await client.GET("/api/v1/me/", {});
+    expect(onUnauthorized).toHaveBeenCalledOnce();
+  });
+
+  it("does not refresh auth endpoints themselves", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async () => new Response("{}", { status: 401 })),
+    );
+    const refreshAccessToken = vi.fn(async () => "new-token");
+    const onUnauthorized = vi.fn();
+    const client = createAuthClient("https://api.test", () => "tok", {
+      refreshAccessToken,
+      onUnauthorized,
+    });
+
+    await client.POST("/api/v1/auth/logout", {});
+    expect(refreshAccessToken).not.toHaveBeenCalled();
+    expect(onUnauthorized).not.toHaveBeenCalled();
+  });
+
+  it("does not clear the session on a 401 without a token (a bad-credentials login)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async () => new Response("{}", { status: 401 })),
+    );
+    const onUnauthorized = vi.fn();
+    const client = createAuthClient("https://api.test", () => null, { onUnauthorized });
+
+    await client.POST("/api/v1/auth/login", { body: { email: "x", password: "y" } });
+    expect(onUnauthorized).not.toHaveBeenCalled();
+  });
+
+  it("does not clear the session on a successful authenticated request", async () => {
+    vi.stubGlobal("fetch", vi.fn<typeof fetch>(async () => jsonResponse()));
+    const onUnauthorized = vi.fn();
+    const client = createAuthClient("https://api.test", () => "tok", { onUnauthorized });
+
+    await client.GET("/api/v1/me/", {});
+    expect(onUnauthorized).not.toHaveBeenCalled();
+  });
+});

package/src/createAuthClient.ts

@@ -0,0 +1,105 @@
+import { createTerpClient, type TerpClient } from "@terpjs/contract";
+
+/** Returns the current bearer token, or null when signed out. */
+export type TokenGetter = () => string | null;
+
+/** Optional hooks for the authenticated client. */
+export interface AuthClientOptions {
+  /**
+   * Try to exchange the httpOnly refresh cookie for a fresh access token (ADR 0054). Called once
+   * when an authenticated, non-auth endpoint returns 401; a returned token is installed by the
+   * provider, then the original request is replayed with the new bearer.
+   */
+  refreshAccessToken?: () => Promise<string | null>;
+  /**
+   * Called when a request that carried a token is rejected with 401 and refresh also failed — i.e.
+   * the session was revoked server-side or the refresh cookie is absent/expired. The provider
+   * clears the session here so the app falls back to the login screen instead of leaving a
+   * signed-in shell over empty data.
+   */
+  onUnauthorized?: () => void;
+}
+
+/**
+ * Create a {@link TerpClient} that attaches `Authorization: Bearer <token>` to every
+ * request, reading the live token from `getToken`. A token set after login (or cleared
+ * on logout) is honoured without re-creating the client, and unauthenticated requests
+ * simply omit the header. Cookies are sent too, so the httpOnly refresh token can ride
+ * `/auth/refresh` without exposing it to JS. A 401 to an authenticated non-auth request
+ * first tries one refresh+replay; if that fails, `onUnauthorized` clears the stale session.
+ */
+export function createAuthClient(
+  baseUrl: string,
+  getToken: TokenGetter,
+  options: AuthClientOptions = {},
+): TerpClient {
+  const client = createTerpClient({ baseUrl, credentials: "include" });
+  const retryRequests = new Map<string, Request>();
+  let refreshInFlight: Promise<string | null> | null = null;
+  client.use({
+    onRequest({ request, id, schemaPath }) {
+      const token = getToken();
+      if (token) {
+        request.headers.set("Authorization", `Bearer ${token}`);
+      }
+      if (token && !isAuthEndpoint(schemaPath)) {
+        retryRequests.set(id, request.clone());
+      }
+      return request;
+    },
+    async onResponse({ id, response, schemaPath }) {
+      const retryRequest = retryRequests.get(id);
+      retryRequests.delete(id);
+      if (
+        response.status !== 401 ||
+        getToken() === null ||
+        isAuthEndpoint(schemaPath) ||
+        retryRequest === undefined
+      ) {
+        return response;
+      }
+      const refreshed = await refreshOnce(options.refreshAccessToken, () => refreshInFlight, (next) => {
+        refreshInFlight = next;
+      });
+      if (refreshed) {
+        retryRequest.headers.set("Authorization", `Bearer ${refreshed}`);
+        const replayed = await fetch(retryRequest);
+        if (replayed.status === 401) {
+          // The subject was revoked between refresh and replay: the session is dead even
+          // though the refresh succeeded — clear it so the app falls back to login.
+          options.onUnauthorized?.();
+        }
+        return replayed;
+      }
+      options.onUnauthorized?.();
+      return response;
+    },
+    onError({ id }) {
+      // A network failure produces no onResponse; drop the retained clone here so the
+      // retry map cannot grow unboundedly under flaky connectivity.
+      retryRequests.delete(id);
+    },
+  });
+  return client;
+}
+
+function refreshOnce(
+  refreshAccessToken: AuthClientOptions["refreshAccessToken"],
+  getInFlight: () => Promise<string | null> | null,
+  setInFlight: (next: Promise<string | null> | null) => void,
+): Promise<string | null> {
+  if (!refreshAccessToken) return Promise.resolve(null);
+  const existing = getInFlight();
+  if (existing) return existing;
+  const next = refreshAccessToken().finally(() => setInFlight(null));
+  setInFlight(next);
+  return next;
+}
+
+function isAuthEndpoint(schemaPath: string): boolean {
+  return (
+    schemaPath === "/api/v1/auth/login" ||
+    schemaPath === "/api/v1/auth/logout" ||
+    schemaPath === "/api/v1/auth/refresh"
+  );
+}