@djangocfg/api 2.1.547 → 2.1.548

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.547",
+  "version": "2.1.548",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -85,7 +85,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.547",
+    "@djangocfg/typescript-config": "^2.1.548",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/auth/__tests__/guard.test.ts

@@ -15,6 +15,7 @@ import {
   resolveGuardIsLoading,
   resolveGuardIsAuthenticated,
   shouldRedirectToAuth,
+  isForbidden,
   type GuardInput,
 } from '../utils/guard';
 
@@ -101,6 +102,70 @@ describe('safety-net timeout (effectiveAuthLoading = authLoading && !timedOut)',
   });
 });
 
+/**
+ * Staff gate. A signed-in non-staff user reaching a staff-only shell is NOT an
+ * auth failure: signing in again cannot fix it. The guard must resolve to a
+ * distinct "forbidden" state — never a redirect (which loops, since the guard
+ * saves the current URL first) and never a spinner (the original hang bug).
+ */
+describe('isForbidden (staff gate)', () => {
+  const staff = (o: Partial<GuardInput>): GuardInput =>
+    s({ requireStaff: true, isAdminUser: false, ...o });
+
+  it('signed-in non-staff user on a staff route is forbidden', () => {
+    expect(isForbidden(staff({}))).toBe(true);
+  });
+
+  it('staff user passes the gate', () => {
+    expect(isForbidden(staff({ isAdminUser: true }))).toBe(false);
+  });
+
+  it('a superuser who is not is_staff passes (isAdminUser folds both flags)', () => {
+    // useAuth() computes isAdminUser as is_staff || is_superuser, so the guard
+    // only ever sees the fold. Checking is_staff alone here would hide the
+    // surface from the people most likely to need it.
+    expect(isForbidden(staff({ isAdminUser: true }))).toBe(false);
+  });
+
+  it('is not forbidden while auth is still resolving (role unknown yet)', () => {
+    expect(isForbidden(staff({ authLoading: true }))).toBe(false);
+  });
+
+  it('is not forbidden before mount (SSR never knows the role)', () => {
+    expect(isForbidden(staff({ mounted: false }))).toBe(false);
+  });
+
+  it('unauthenticated is a redirect, not a forbidden wall', () => {
+    expect(isForbidden(staff({ isAuthenticated: false }))).toBe(false);
+    expect(shouldRedirectToAuth(staff({ isAuthenticated: false }))).toBe(true);
+  });
+
+  it('routes that do not require staff are never forbidden', () => {
+    expect(isForbidden(s({ requireStaff: false, isAdminUser: false }))).toBe(false);
+    expect(isForbidden(base)).toBe(false); // requireStaff undefined
+  });
+
+  it('a public route is never forbidden', () => {
+    expect(isForbidden(staff({ requireAuth: false }))).toBe(false);
+  });
+
+  it('REGRESSION: a forbidden user stops loading (renders the wall, never spins)', () => {
+    expect(resolveGuardIsLoading(staff({}))).toBe(false);
+  });
+
+  it('REGRESSION: a forbidden user never triggers a redirect (no login loop)', () => {
+    expect(shouldRedirectToAuth(staff({}))).toBe(false);
+  });
+
+  it('a staff user on a staff route renders content', () => {
+    expect(resolveGuardIsLoading(staff({ isAdminUser: true }))).toBe(false);
+  });
+
+  it('still blocks while a staff route is resolving auth', () => {
+    expect(resolveGuardIsLoading(staff({ authLoading: true }))).toBe(true);
+  });
+});
+
 describe('resolveGuardIsAuthenticated', () => {
   it('is true on a public route regardless of session', () => {
     expect(resolveGuardIsAuthenticated({ requireAuth: false, isAuthenticated: false })).toBe(true);

package/src/auth/utils/guard.ts

@@ -9,7 +9,9 @@
  *
  * Invariant that fixes the bug: once auth is resolved (`authLoading === false`)
  * and the user is unauthenticated, `isLoading` must become false so the guard
- * redirects to the form instead of spinning forever.
+ * redirects to the form instead of spinning forever. The same invariant covers
+ * the forbidden case: a signed-in user without the required privilege must stop
+ * loading too, or the preloader spins on a state no redirect will ever clear.
  */
 
 export interface GuardInput {
@@ -23,6 +25,29 @@ export interface GuardInput {
   isRedirecting: boolean;
   /** User currently has a (valid-looking) session. */
   isAuthenticated: boolean;
+  /** Route requires staff/admin privileges, not just a session. */
+  requireStaff?: boolean;
+  /** `is_staff || is_superuser`, from `useAuth().isAdminUser`. */
+  isAdminUser?: boolean;
+}
+
+/**
+ * True when the session is valid but lacks the required privilege.
+ *
+ * Distinct from unauthenticated: the fix is a different account, not signing
+ * in, so this must never redirect to the auth form. Redirecting would also
+ * loop — the guard saves the current URL first, so a successful re-login on
+ * the same account returns straight to the wall.
+ */
+export function isForbidden(s: GuardInput): boolean {
+  return Boolean(
+    s.mounted &&
+    s.requireAuth &&
+    s.requireStaff &&
+    !s.authLoading &&
+    s.isAuthenticated &&
+    !s.isAdminUser
+  );
 }
 
 /**
@@ -32,6 +57,7 @@ export interface GuardInput {
 export function resolveGuardIsLoading(s: GuardInput): boolean {
   if (!s.mounted) return true; // pre-hydration: always preloader
   if (!s.requireAuth) return false; // public route: never blocks
+  if (isForbidden(s)) return false; // resolved: render the wall, don't spin
   return s.authLoading || s.isRedirecting || !s.isAuthenticated;
 }
 

package/src/auth/utils/index.ts

@@ -4,6 +4,7 @@ export {
   resolveGuardIsLoading,
   shouldRedirectToAuth,
   resolveGuardIsAuthenticated,
+  isForbidden,
   type GuardInput,
 } from './guard';
 export { normalizePath, isAllowedAuthPath } from './path';