@djangocfg/api 2.1.547 → 2.1.548

package/README.md

@@ -77,6 +77,31 @@ import {
 } from '@djangocfg/api/auth';
 ```
 
+### Guard resolvers
+
+The "spinner vs redirect vs render" decision is pure and separately testable.
+`useAuthGuard` (and `@djangocfg/layouts`' `PrivateLayout`) just wire React state
+into these:
+
+```typescript
+import {
+  resolveGuardIsLoading,      // show the preloader?
+  shouldRedirectToAuth,       // no session → send to the auth form
+  isForbidden,                // signed in, but lacks the required privilege
+  resolveGuardIsAuthenticated,
+  type GuardInput,
+} from '@djangocfg/api/auth';
+```
+
+`GuardInput` takes two optional fields for the role gate: `requireStaff` (the
+route needs staff/admin) and `isAdminUser` (from `useAuth()` — the
+`is_staff || is_superuser` fold, never one flag).
+
+`isForbidden` is deliberately **not** a redirect condition: the session is
+valid, so the auth form cannot fix it, and redirecting would loop on the saved
+URL. Render a distinct "not authorised" state instead. `resolveGuardIsLoading`
+returns `false` once forbidden, so the preloader never spins on it.
+
 ## Token storage & DPoP
 
 The token lives in the shared `auth` store (localStorage by default, switchable

package/dist/auth.cjs

@@ -50,6 +50,7 @@ __export(auth_exports, {
   getCachedProfile: () => getCachedProfile,
   hasValidCache: () => hasValidCache,
   isAllowedAuthPath: () => isAllowedAuthPath,
+  isForbidden: () => isForbidden,
   logger: () => logger,
   normalizePath: () => normalizePath,
   peekSavedRedirect: () => peekSavedRedirect,
@@ -5210,9 +5211,16 @@ var formatAuthError = /* @__PURE__ */ __name((error) => {
 }, "formatAuthError");
 
 // src/auth/utils/guard.ts
+function isForbidden(s) {
+  return Boolean(
+    s.mounted && s.requireAuth && s.requireStaff && !s.authLoading && s.isAuthenticated && !s.isAdminUser
+  );
+}
+__name(isForbidden, "isForbidden");
 function resolveGuardIsLoading(s) {
   if (!s.mounted) return true;
   if (!s.requireAuth) return false;
+  if (isForbidden(s)) return false;
   return s.authLoading || s.isRedirecting || !s.isAuthenticated;
 }
 __name(resolveGuardIsLoading, "resolveGuardIsLoading");