@djangocfg/layouts 2.1.547 → 2.1.548

package/README.md

@@ -66,6 +66,22 @@ provider surface and the Next.js vs Wails wiring, and the demo app
 > **Admin** is not a separate layout — use `PrivateLayout` with an admin `sidebar`
 > config in your `app/.../admin/layout.tsx`.
 
+### Staff-only route groups
+
+`PrivateLayout`'s guard checks the session. For a surface that also requires
+staff, add `requireStaff` (resolved from `useAuth().isAdminUser`, the
+`is_staff || is_superuser` fold):
+
+```tsx
+<PrivateLayout sidebar={sidebar} header={header} requireStaff>{children}</PrivateLayout>
+```
+
+A signed-in non-staff user gets `ForbiddenState` instead of the shell — **not a
+redirect to the auth form**: they are already signed in, so signing in again
+cannot grant the privilege, and since the guard saves the current URL first, a
+redirect would loop back here. Pass `forbiddenFallback` to supply your own
+screen. Details: [PrivateLayout README](./src/layouts/PrivateLayout/README.md).
+
 ### `AuthLayout` shells
 
 Two visual variants, switchable via the `variant` prop:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.547",
+  "version": "2.1.548",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -90,11 +90,11 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/analytics": "^2.1.547",
-    "@djangocfg/api": "^2.1.547",
-    "@djangocfg/devtools": "^2.1.547",
-    "@djangocfg/i18n": "^2.1.547",
-    "@djangocfg/ui-core": "^2.1.547",
+    "@djangocfg/analytics": "^2.1.548",
+    "@djangocfg/api": "^2.1.548",
+    "@djangocfg/devtools": "^2.1.548",
+    "@djangocfg/i18n": "^2.1.548",
+    "@djangocfg/ui-core": "^2.1.548",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -124,12 +124,12 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.547",
-    "@djangocfg/api": "^2.1.547",
-    "@djangocfg/devtools": "^2.1.547",
-    "@djangocfg/i18n": "^2.1.547",
-    "@djangocfg/typescript-config": "^2.1.547",
-    "@djangocfg/ui-core": "^2.1.547",
+    "@djangocfg/analytics": "^2.1.548",
+    "@djangocfg/api": "^2.1.548",
+    "@djangocfg/devtools": "^2.1.548",
+    "@djangocfg/i18n": "^2.1.548",
+    "@djangocfg/typescript-config": "^2.1.548",
+    "@djangocfg/ui-core": "^2.1.548",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -4,6 +4,10 @@
  * Authenticated shell: collapsible sidebar (icon rail vs expanded) + scrollable content.
  * Toggle lives in the sidebar header on desktop; on narrow viewports a `SidebarTrigger` sits in `PrivateContent` (opens the mobile Sheet).
  * Ctrl/Cmd + B still toggles the sidebar width.
+ *
+ * Guarded: no session redirects to `header.authPath`. With `requireStaff`, a
+ * signed-in non-staff user gets `ForbiddenState` instead — never a redirect,
+ * since signing in again cannot grant the privilege.
  */
 
 'use client';
@@ -13,7 +17,7 @@ import React from 'react';
 import { Preloader } from '@djangocfg/ui-core/components';
 import { SidebarInset, SidebarProvider } from '@djangocfg/ui-core/components';
 
-import { PrivateContent, PrivateSidebar } from './components';
+import { ForbiddenState, PrivateContent, PrivateSidebar } from './components';
 import { useAuthGuard } from './hooks';
 import { useLayoutVisual } from './hooks';
 import { useSidebarDefaultOpen } from './hooks';
@@ -49,10 +53,13 @@ export function PrivateLayout({
   contentScroll = 'auto',
   visual,
   requireAuth = true,
+  requireStaff = false,
+  forbiddenFallback,
   settings,
 }: PrivateLayoutProps) {
-  const { isLoading, loadingText } = useAuthGuard({
+  const { isLoading, isForbidden, loadingText } = useAuthGuard({
     requireAuth,
+    requireStaff,
     authPath: header?.authPath,
   });
 
@@ -73,6 +80,13 @@ export function PrivateLayout({
     );
   }
 
+  // Before the shell: a forbidden user must never reach the sidebar or the
+  // children, or every request they trigger returns 403 and the screen cannot
+  // be told apart from a backend outage.
+  if (isForbidden) {
+    return <>{forbiddenFallback ?? <ForbiddenState />}</>;
+  }
+
   return (
     <SidebarProvider
       defaultOpen={defaultOpen}

package/src/layouts/PrivateLayout/README.md

@@ -17,6 +17,38 @@ The auth guard redirects to `header.authPath` when there's no session. Pass `req
 
 ---
 
+## Staff-only surfaces
+
+Add `requireStaff` when the whole route group is staff-only:
+
+```tsx
+<PrivateLayout sidebar={sidebar} header={header} requireStaff>{children}</PrivateLayout>
+```
+
+It resolves from `useAuth().isAdminUser` — the `is_staff || is_superuser` fold,
+never one flag on its own.
+
+| Prop | Type | Default | Role |
+|---|---|---|---|
+| `requireStaff` | `boolean` | `false` | Require staff/admin on top of a session. |
+| `forbiddenFallback` | `ReactNode` | `<ForbiddenState />` | Replaces the built-in screen. |
+
+**On failure the forbidden state renders instead of the shell — there is no
+redirect to the auth form.** The user is already signed in, so the sign-in form
+cannot fix anything; and because the guard saves the current URL before
+redirecting, a re-login on the same account would land straight back here, in a
+loop. The default `ForbiddenState` names the signed-in account and offers sign
+out, which is the one action that helps: it lets them switch accounts.
+
+Gate the shell rather than each control inside it, so the wall renders **before
+any request fires**. Without it a non-staff operator reaches the surface, every
+call returns `403`, and the screen is indistinguishable from a backend outage.
+
+Presentation, not protection: the endpoints behind the surface must withhold the
+data themselves. The gate decides what is *offered*, never what is *permitted*.
+
+---
+
 ## Wiring (canonical)
 
 Mount it in the **route-group `layout.tsx`** that owns the authenticated section

package/src/layouts/PrivateLayout/components/ForbiddenState.tsx

@@ -0,0 +1,62 @@
+/**
+ * Forbidden State
+ *
+ * Shown when a signed-in user lacks the privilege a route requires
+ * (`requireStaff`). Deliberately NOT a redirect to the sign-in form: the
+ * session is valid, so signing in again changes nothing — and since the guard
+ * saves the current URL first, a redirect would loop straight back here.
+ *
+ * It renders before any request fires, so the operator sees "wrong account"
+ * instead of a screen full of 403s indistinguishable from a backend outage.
+ * Sign out is the only action that helps: it lets them switch accounts.
+ */
+
+'use client';
+
+import React from 'react';
+
+import { ShieldAlert } from 'lucide-react';
+
+import { useAuth } from '@djangocfg/api/auth';
+import { Button } from '@djangocfg/ui-core/components';
+
+export interface ForbiddenStateProps {
+  /** Heading. Defaults to a staff-access message. */
+  title?: string;
+  /** Explanation under the heading. */
+  description?: string;
+}
+
+export function ForbiddenState({
+  title = 'Staff access required',
+  description = 'Your account is signed in but does not have staff permissions for this area. Sign out and use a staff account, or ask an administrator to grant access.',
+}: ForbiddenStateProps) {
+  const { user, logout } = useAuth();
+
+  return (
+    <div
+      role="alert"
+      className="flex min-h-svh flex-col items-center justify-center gap-4 p-6 text-center"
+    >
+      <div className="flex size-12 items-center justify-center rounded-full bg-destructive/10">
+        <ShieldAlert className="size-6 text-destructive" />
+      </div>
+
+      <div className="space-y-2">
+        <h1 className="text-lg font-semibold">{title}</h1>
+        <p className="max-w-md text-sm text-muted-foreground">{description}</p>
+        {/* Naming the account is the fastest way to spot the usual cause:
+            signed in on the right site with the wrong account. */}
+        {user?.email && (
+          <p className="text-xs text-muted-foreground">
+            Signed in as <span className="font-medium">{user.email}</span>
+          </p>
+        )}
+      </div>
+
+      <Button variant="outline" size="sm" onClick={logout}>
+        Sign out
+      </Button>
+    </div>
+  );
+}

package/src/layouts/PrivateLayout/components/index.ts

@@ -4,6 +4,8 @@
 
 export { PrivateSidebar } from './PrivateSidebar';
 export { PrivateContent } from './PrivateContent';
+export { ForbiddenState } from './ForbiddenState';
+export type { ForbiddenStateProps } from './ForbiddenState';
 export { SidebarBrand } from './SidebarBrand';
 export { SidebarBrandSwitcher } from './SidebarBrandSwitcher';
 export { SidebarNavGroup } from './SidebarNavGroup';

package/src/layouts/PrivateLayout/hooks/useAuthGuard.ts

@@ -14,10 +14,16 @@ import {
   resolveGuardIsLoading,
   resolveGuardIsAuthenticated,
   shouldRedirectToAuth,
+  isForbidden,
 } from '@djangocfg/api/auth';
 
 interface UseAuthGuardOptions {
   requireAuth?: boolean;
+  /**
+   * Require staff/admin (`is_staff || is_superuser`) on top of a session.
+   * A signed-in non-staff user gets the forbidden state, not a redirect.
+   */
+  requireStaff?: boolean;
   /** Explicit override; defaults to the app's resolved `useAuth().routes.auth`. */
   authPath?: string;
   /**
@@ -34,16 +40,19 @@ interface UseAuthGuardResult {
   isLoading: boolean;
   /** Whether the user is authenticated (or auth is not required) */
   isAuthenticated: boolean;
+  /** Signed in, but lacking the privilege this route requires. */
+  isForbidden: boolean;
   /** Loading text for the preloader */
   loadingText: string;
 }
 
 export function useAuthGuard({
   requireAuth = true,
+  requireStaff = false,
   authPath,
   loadingTimeoutMs = 8000,
 }: UseAuthGuardOptions): UseAuthGuardResult {
-  const { isAuthenticated, isLoading: authLoading, saveRedirectUrl, routes } = useAuth();
+  const { isAuthenticated, isLoading: authLoading, isAdminUser, saveRedirectUrl, routes } = useAuth();
   const resolvedAuthPath = authPath ?? routes.auth;
   const router = useRouter();
   const [isRedirecting, setIsRedirecting] = useState(false);
@@ -78,6 +87,8 @@ export function useAuthGuard({
     authLoading: effectiveAuthLoading,
     isRedirecting,
     isAuthenticated,
+    requireStaff,
+    isAdminUser,
   };
 
   useEffect(() => {
@@ -96,6 +107,9 @@ export function useAuthGuard({
   return {
     isLoading,
     isAuthenticated: resolveGuardIsAuthenticated(guardState),
+    // Never redirects: shouldRedirectToAuth requires !isAuthenticated, so a
+    // forbidden user is structurally excluded from the redirect effect above.
+    isForbidden: isForbidden(guardState),
     loadingText,
   };
 }

package/src/layouts/PrivateLayout/index.ts

@@ -4,7 +4,8 @@
 
 export { PrivateLayout } from './PrivateLayout';
 export { PrivateLayoutProvider, usePrivateLayoutContext } from './context';
-export { SidebarBrandSwitcher } from './components';
+export { SidebarBrandSwitcher, ForbiddenState } from './components';
+export type { ForbiddenStateProps } from './components';
 export type {
   PrivateLayoutProps,
   SidebarItem,

package/src/layouts/PrivateLayout/types.ts

@@ -223,6 +223,21 @@ export interface PrivateLayoutProps {
    * embeds where there's no real session. Default `true` (guard on).
    */
   requireAuth?: boolean;
+  /**
+   * Require staff/admin (`is_staff || is_superuser`) on top of a session.
+   * A signed-in non-staff user gets the forbidden state instead of the shell —
+   * not a redirect, which would loop since signing in again cannot grant the
+   * privilege. Default `false`.
+   *
+   * Presentation only: the endpoints behind this surface must withhold the
+   * data themselves. The gate decides what is offered, never what is permitted.
+   */
+  requireStaff?: boolean;
+  /**
+   * Replaces the built-in "not authorised" screen shown when `requireStaff`
+   * fails. Omit for the default `ForbiddenState`.
+   */
+  forbiddenFallback?: ReactNode;
   /**
    * Mount the global SettingsDialog (Claude-style master/detail settings modal,
    * hash-URL driven, openable via `useSettingsDialog()`). Pass a config object