@classic-homes/auth 1.42.0 → 1.45.0

package/README.md

@@ -337,6 +337,44 @@ token.
 Call `initCrossTabSync()` once at app start so a refresh or sign-out in another
 tab rehydrates this tab's Svelte store.
 
+## API errors and access debugging
+
+A non-2xx response from `apiRequest` / `api.*` throws an `ApiError`. Its
+`message` is the server's message (as before), plus `status`, the CHAPI `code`,
+`details`, `method` and `endpoint`:
+
+```typescript
+import { isApiError } from '@classic-homes/auth/core';
+
+try {
+  await api.get('/homes', true);
+} catch (e) {
+  if (isApiError(e) && e.status === 403) {
+    console.log(e.details?.required); // e.g. ['homes:read']
+  }
+}
+```
+
+### Access probe
+
+Hooks for troubleshooting tools such as the Access Inspector. They are inert
+until installed and do nothing on the server.
+
+- `setAccessProbe(fn)` receives every access decision: core `hasRole*`, store
+  `has*`, `checkAuth` (`source: 'route'`), `filterByAccess`/`canAccess`
+  (`'nav'`) and API 403s (`'http'`, path only, never the query string).
+  Each event carries the requirement, `allowed` and what was `missing`.
+- `setAccessSubject(userId, { roles, permissions })` previews the UI as another
+  role set ("view as") for that user only. Checks for other users are
+  unaffected, `authStore.user` is never changed, and the preview ends on any
+  login, logout or session expiry. Sign-in role gating (`allowedRoles`) always
+  uses the real roles.
+- `evaluateAccess(subject, requirement)` is the shared any/all decision
+  `checkAuth` uses; `checkAuth` results now include `missing` on denial.
+
+These change UI decisions only. The API authorizes every request with the real
+token, so a preview can never grant access.
+
 ## API Reference
 
 ### Core Exports
@@ -376,6 +414,16 @@ import {
   hasAnyRole,
   hasAllRoles,
 
+  // Errors
+  ApiError,
+  isApiError,
+
+  // Access probe (see "API errors and access debugging")
+  setAccessProbe,
+  setAccessSubject,
+  clearAccessSubject,
+  evaluateAccess,
+
   // Types
   type User,
   type UserRolesResponse,

package/dist/auth.svelte-AN7ZNZ2W.js

@@ -0,0 +1,3 @@
+export { authActions, authStore, currentUser, isAuthenticated } from './chunk-W2ASN4NE.js';
+import './chunk-ADCPJOPQ.js';
+import './chunk-5X6E5MZG.js';

package/dist/{chunk-LPQKZRPC.js → chunk-42EO3FSU.js}

@@ -1,5 +1,5 @@
-import { authApi, InvalidAuthResponseError, RoleDeniedError } from './chunk-7AQYLLTA.js';
-import { hasAnyRole, getUserRoles } from './chunk-K6TV3ZVS.js';
+import { authApi, InvalidAuthResponseError, RoleDeniedError } from './chunk-ADCPJOPQ.js';
+import { getUserRoles } from './chunk-5X6E5MZG.js';
 
 // src/core/guards.ts
 function isMfaChallengeResponse(response) {
@@ -19,7 +19,7 @@ function getAvailableMethods(response) {
 async function setStoreAuth(response) {
   let store;
   try {
-    store = (await import('./auth.svelte-XY4FQFZQ.js')).authStore;
+    store = (await import('./auth.svelte-AN7ZNZ2W.js')).authStore;
   } catch {
     return;
   }
@@ -44,7 +44,7 @@ var AuthService = class {
       throw new InvalidAuthResponseError();
     }
     if (options?.allowedRoles?.length) {
-      if (!hasAnyRole(response.user, options.allowedRoles)) {
+      if (!holdsAnyRole(response.user, options.allowedRoles)) {
         throw new RoleDeniedError(
           response.user,
           options.allowedRoles,
@@ -224,7 +224,7 @@ var AuthService = class {
       throw new InvalidAuthResponseError();
     }
     if (options?.allowedRoles?.length) {
-      if (!hasAnyRole(response.user, options.allowedRoles)) {
+      if (!holdsAnyRole(response.user, options.allowedRoles)) {
         throw new RoleDeniedError(
           response.user,
           options.allowedRoles,
@@ -332,6 +332,10 @@ var AuthService = class {
   }
 };
 var authService = new AuthService();
+function holdsAnyRole(user, allowed) {
+  const held = getUserRoles(user);
+  return allowed.some((role) => held.includes(role));
+}
 
 // src/core/user-utils.ts
 function getDisplayName(user) {

package/dist/{chunk-K6TV3ZVS.js → chunk-5X6E5MZG.js}

@@ -193,6 +193,101 @@ function extractClaims(token, claims) {
   return result;
 }
 
+// src/core/access-probe.ts
+var isBrowser = typeof window !== "undefined";
+var probe = null;
+var override = null;
+var overrideListeners = /* @__PURE__ */ new Set();
+function setAccessProbe(next) {
+  const previous = probe;
+  if (isBrowser || next === null) probe = next;
+  return previous;
+}
+function isAccessProbeActive() {
+  return probe !== null;
+}
+function reportAccess(event) {
+  if (!probe) return;
+  try {
+    probe(event);
+  } catch {
+  }
+}
+function setAccessSubject(userId, subject) {
+  if (!isBrowser) return;
+  override = {
+    userId,
+    subject: { roles: [...subject.roles], permissions: [...subject.permissions] }
+  };
+  notifyOverride();
+}
+function clearAccessSubject() {
+  if (!override) return;
+  override = null;
+  notifyOverride();
+}
+function getAccessSubjectOverride() {
+  return override;
+}
+function onAccessSubjectChange(listener) {
+  overrideListeners.add(listener);
+  return () => overrideListeners.delete(listener);
+}
+function notifyOverride() {
+  for (const listener of overrideListeners) {
+    try {
+      listener();
+    } catch {
+    }
+  }
+}
+function effectiveSubject(user) {
+  if (override && user?.id !== void 0 && user.id === override.userId) {
+    return { ...override.subject, simulated: true };
+  }
+  return { roles: user?.roles ?? [], permissions: user?.permissions ?? [], simulated: false };
+}
+function evaluateList(required, held, requireAll) {
+  if (!required || required.length === 0) return { ok: true, missing: [] };
+  const absent = required.filter((item) => !held.includes(item));
+  const ok = requireAll ? absent.length === 0 : absent.length < required.length;
+  return { ok, missing: ok ? [] : requireAll ? absent : [...required] };
+}
+function evaluateAccess(subject, requirement) {
+  const roles = evaluateList(requirement.roles, subject.roles, requirement.requireAllRoles);
+  const permissions = evaluateList(
+    requirement.permissions,
+    subject.permissions,
+    requirement.requireAllPermissions
+  );
+  return {
+    allowed: roles.ok && permissions.ok,
+    missing: { roles: roles.missing, permissions: permissions.missing }
+  };
+}
+function reportDecision(source, user, requirement, allowed, label) {
+  if (!probe) return;
+  const subject = effectiveSubject(user);
+  reportAccess({
+    source,
+    requirement,
+    allowed,
+    missing: allowed ? { roles: [], permissions: [] } : evaluateAccess(subject, requirement).missing,
+    subjectId: user?.id ?? null,
+    simulated: subject.simulated,
+    label
+  });
+}
+function requirementFromDenial(code, details) {
+  if (!details || typeof details !== "object") return null;
+  const { required, mode } = details;
+  const list = typeof required === "string" ? [required] : Array.isArray(required) ? required.filter((item) => typeof item === "string") : [];
+  if (list.length === 0) return null;
+  const isPermission = code === "INSUFFICIENT_PERMISSIONS" || list.some((p) => p.includes(":"));
+  const requireAll = mode === "any" ? false : mode === "all" ? true : isPermission;
+  return isPermission ? { permissions: list, requireAllPermissions: requireAll } : { roles: list, requireAllRoles: requireAll };
+}
+
 // src/core/roles.ts
 var ROLE_NAMES = [
   "admin",
@@ -275,15 +370,21 @@ function getEffectiveLevel(roles) {
   return max;
 }
 function hasRole(user, role) {
-  return getUserRoles(user).includes(role);
+  const allowed = effectiveSubject(user).roles.includes(role);
+  reportDecision("check", user, { roles: [role] }, allowed);
+  return allowed;
 }
 function hasAnyRole(user, roles) {
-  const held = getUserRoles(user);
-  return roles.some((role) => held.includes(role));
+  const held = effectiveSubject(user).roles;
+  const allowed = roles.some((role) => held.includes(role));
+  if (roles.length > 0) reportDecision("check", user, { roles }, allowed);
+  return allowed;
 }
 function hasAllRoles(user, roles) {
-  const held = getUserRoles(user);
-  return roles.every((role) => held.includes(role));
+  const held = effectiveSubject(user).roles;
+  const allowed = roles.every((role) => held.includes(role));
+  if (roles.length > 0) reportDecision("check", user, { roles, requireAllRoles: true }, allowed);
+  return allowed;
 }
 
-export { ROLE_HIERARCHY, ROLE_NAMES, computePrimaryRole, createMemoryStorage, createSessionStorage, decodeJWT, extractClaims, getConfig, getDefaultStorage, getEffectiveLevel, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, initAuth, isInitialized, isTokenExpired, isValidRedirectUrl, isValidSSOLogoutUrl, resetConfig };
+export { ROLE_HIERARCHY, ROLE_NAMES, clearAccessSubject, computePrimaryRole, createMemoryStorage, createSessionStorage, decodeJWT, effectiveSubject, evaluateAccess, extractClaims, getAccessSubjectOverride, getConfig, getDefaultStorage, getEffectiveLevel, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, initAuth, isAccessProbeActive, isInitialized, isTokenExpired, isValidRedirectUrl, isValidSSOLogoutUrl, onAccessSubjectChange, reportAccess, reportDecision, requirementFromDenial, resetConfig, setAccessProbe, setAccessSubject };

package/dist/{chunk-7AQYLLTA.js → chunk-ADCPJOPQ.js}

@@ -1,4 +1,4 @@
-import { isInitialized, getConfig, getUserRoles, getStorage, isTokenExpired, getFetch, isValidRedirectUrl, decodeJWT } from './chunk-K6TV3ZVS.js';
+import { isInitialized, getConfig, getUserRoles, clearAccessSubject, getStorage, isTokenExpired, getFetch, isAccessProbeActive, isValidRedirectUrl, requirementFromDenial, reportAccess, decodeJWT } from './chunk-5X6E5MZG.js';
 
 // src/core/sso-state.ts
 var SSO_CLIENT_STATE_PARAM = "client_state";
@@ -119,11 +119,29 @@ var MFAChallengeEmailError = class _MFAChallengeEmailError extends Error {
     }
   }
 };
+var ApiError = class _ApiError extends Error {
+  constructor(message, init) {
+    super(message);
+    this.name = "ApiError";
+    this.status = init.status;
+    this.code = init.code;
+    this.details = init.details;
+    this.method = init.method;
+    this.endpoint = init.endpoint;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _ApiError);
+    }
+  }
+};
+function isApiError(error) {
+  return error instanceof ApiError || error?.name === "ApiError";
+}
 
 // src/core/session.ts
 var generation = 0;
 function bumpSessionGeneration() {
   generation += 1;
+  clearAccessSubject();
 }
 function readIdentity() {
   let parsed = {};
@@ -218,7 +236,7 @@ function writeStoredTokens(accessToken, refreshToken) {
 }
 async function syncSvelteStore(apply) {
   try {
-    const { authStore } = await import('./auth.svelte-XY4FQFZQ.js');
+    const { authStore } = await import('./auth.svelte-AN7ZNZ2W.js');
     apply(authStore);
   } catch {
   }
@@ -371,6 +389,31 @@ function isApiOrigin(url, baseUrl) {
     return false;
   }
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function reportForbidden(method, endpoint, code, details) {
+  let path = endpoint.split(/[?#]/, 1)[0];
+  try {
+    if (/^https?:\/\//i.test(path)) path = new URL(path).pathname;
+  } catch {
+  }
+  const requirement = requirementFromDenial(code, details) ?? {};
+  reportAccess({
+    source: "http",
+    requirement,
+    allowed: false,
+    missing: {
+      roles: [...requirement.roles ?? []],
+      permissions: [...requirement.permissions ?? []]
+    },
+    // The server decided against the real token; whose id is the caller's business.
+    subjectId: null,
+    simulated: false,
+    label: `${method} ${path}`,
+    http: { method, endpoint: path, status: 403, code }
+  });
+}
 function apiRequest(endpoint, options = {}) {
   return apiRequestInternal(endpoint, options, false);
 }
@@ -439,7 +482,6 @@ async function apiRequestInternal(endpoint, options, isRetry, startedIn) {
       body: body ? JSON.stringify(body) : void 0,
       signal: controller.signal
     });
-    clearTimeout(timeoutId);
     if (response.status === 401 && authenticated && !noAuthRetry && typeof window !== "undefined") {
       await assertSameSession();
       if (isRetry) {
@@ -462,13 +504,17 @@ async function apiRequestInternal(endpoint, options, isRetry, startedIn) {
       try {
         data = await response.json();
       } catch (parseError) {
+        if (controller.signal.aborted) throw parseError;
         if (!response.ok) {
           throw new Error(`Server error (${response.status}): Invalid JSON response`);
         }
         throw parseError;
       }
     } else {
-      const responseText = await response.text().catch(() => "");
+      const responseText = await response.text().catch((readError) => {
+        if (controller.signal.aborted) throw readError;
+        return "";
+      });
       if (responseText) {
         try {
           data = JSON.parse(responseText);
@@ -493,13 +539,24 @@ async function apiRequestInternal(endpoint, options, isRetry, startedIn) {
     if (!response.ok) {
       const errorBody = data ?? {};
       const errorMessage = errorBody.error?.message || (typeof errorBody.message === "string" ? errorBody.message : void 0) || errorBody.meta?.message || (typeof errorBody.detail === "string" ? errorBody.detail : void 0) || `Request failed (${response.status})`;
-      const error = new Error(errorMessage);
+      const code = typeof errorBody.error?.code === "string" ? errorBody.error.code : void 0;
+      const details = isRecord(errorBody.error?.details) ? errorBody.error.details : void 0;
+      const method = (fetchOptions.method ?? "GET").toUpperCase();
+      const error = new ApiError(errorMessage, {
+        status: response.status,
+        code,
+        details,
+        method,
+        endpoint
+      });
+      if (response.status === 403 && isAccessProbeActive()) {
+        reportForbidden(method, endpoint, code, details);
+      }
       config.onAuthError?.(error);
       throw error;
     }
     return data;
   } catch (error) {
-    clearTimeout(timeoutId);
     if (error instanceof DOMException && error.name === "AbortError") {
       if (signal?.aborted) throw error;
       throw new Error(`Request timed out after ${timeoutMs}ms`);
@@ -509,6 +566,7 @@ async function apiRequestInternal(endpoint, options, isRetry, startedIn) {
     }
     throw new Error("API request failed");
   } finally {
+    clearTimeout(timeoutId);
     signal?.removeEventListener("abort", onCallerAbort);
   }
 }
@@ -553,16 +611,19 @@ var api = {
 };
 
 // src/core/api.ts
-async function fetchWithTimeout(url, init) {
+async function fetchWithTimeout(url, init, read) {
   const config = getConfig();
   const fetchFn = config.fetch ?? fetch;
   const timeoutMs = config.requestTimeout ?? 3e4;
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    return await fetchFn(url, { ...init, signal: controller.signal });
+    const response = await fetchFn(url, { ...init, signal: controller.signal });
+    const result = await read(response);
+    if (controller.signal.aborted) throw new Error("aborted");
+    return result;
   } catch (error) {
-    if (error instanceof DOMException && error.name === "AbortError") {
+    if (controller.signal.aborted) {
       throw new Error(`Request timed out after ${timeoutMs}ms`);
     }
     throw error;
@@ -814,19 +875,24 @@ var authApi = {
       type: data.method === "backup" || data.method === "email" ? data.method : "totp",
       trustDevice: data.trustDevice
     };
-    const response = await fetchWithTimeout(`${config.baseUrl}/auth/mfa/challenge`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${data.mfaToken}`
+    const result = await fetchWithTimeout(
+      `${config.baseUrl}/auth/mfa/challenge`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${data.mfaToken}`
+        },
+        body: JSON.stringify(requestBody)
       },
-      body: JSON.stringify(requestBody)
-    });
-    if (!response.ok) {
-      const error = await response.json().catch(() => ({ message: "Verification failed" }));
-      throw new Error(error.error?.message || error.message || "Invalid verification code");
-    }
-    const result = await response.json();
+      async (response) => {
+        if (!response.ok) {
+          const error = await response.json().catch(() => ({ message: "Verification failed" }));
+          throw new Error(error.error?.message || error.message || "Invalid verification code");
+        }
+        return response.json();
+      }
+    );
     return extractData(result);
   },
   /**
@@ -837,11 +903,14 @@ var authApi = {
    */
   async sendMFAChallengeEmail(mfaToken) {
     const config = getConfig();
-    const response = await fetchWithTimeout(`${config.baseUrl}/auth/mfa/challenge/email/send`, {
-      method: "POST",
-      headers: { Authorization: `Bearer ${mfaToken}` }
-    });
-    const body = await response.json().catch(() => ({}));
+    const { response, body } = await fetchWithTimeout(
+      `${config.baseUrl}/auth/mfa/challenge/email/send`,
+      {
+        method: "POST",
+        headers: { Authorization: `Bearer ${mfaToken}` }
+      },
+      async (response2) => ({ response: response2, body: await response2.json().catch(() => ({})) })
+    );
     if (!response.ok) {
       const details = body?.error?.details;
       const retryAfter = typeof details?.retryAfterSeconds === "number" ? details.retryAfterSeconds : typeof body?.retryAfterSeconds === "number" ? body.retryAfterSeconds : void 0;
@@ -969,19 +1038,24 @@ var authApi = {
       throw new Error("Not authenticated");
     }
     const config = getConfig();
-    const response = await fetchWithTimeout(`${config.baseUrl}/auth/sso/link`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${accessToken}`
+    const result = await fetchWithTimeout(
+      `${config.baseUrl}/auth/sso/link`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${accessToken}`
+        },
+        body: JSON.stringify({ provider })
       },
-      body: JSON.stringify({ provider })
-    });
-    if (!response.ok) {
-      const error = await response.json().catch(() => ({ message: "Failed to link SSO account" }));
-      throw new Error(error.error?.message || error.message || "Failed to link SSO account");
-    }
-    const result = await response.json();
+      async (response) => {
+        if (!response.ok) {
+          const error = await response.json().catch(() => ({ message: "Failed to link SSO account" }));
+          throw new Error(error.error?.message || error.message || "Failed to link SSO account");
+        }
+        return response.json();
+      }
+    );
     const authorizationUrl = extractData(result).authorizationUrl;
     if (authorizationUrl) {
       if (!isValidRedirectUrl(authorizationUrl)) {
@@ -1081,4 +1155,4 @@ var authApi = {
   }
 };
 
-export { InvalidAuthResponseError, MFAChallengeEmailError, RoleDeniedError, SSO_CLIENT_STATE_PARAM, SSO_CLIENT_STATE_TTL_MS, SessionChangedError, api, apiRequest, authApi, bumpSessionGeneration, clearStoredAuth, consumeSsoClientState, createSsoClientState, extractData, getAccessToken, getRefreshToken, getSessionToken, initCrossTabSync, isRoleDeniedError, isSessionChangedError, refreshSession, updateStoredTokens, verifySsoClientState };
+export { ApiError, InvalidAuthResponseError, MFAChallengeEmailError, RoleDeniedError, SSO_CLIENT_STATE_PARAM, SSO_CLIENT_STATE_TTL_MS, SessionChangedError, api, apiRequest, authApi, bumpSessionGeneration, clearStoredAuth, consumeSsoClientState, createSsoClientState, extractData, getAccessToken, getRefreshToken, getSessionToken, initCrossTabSync, isApiError, isRoleDeniedError, isSessionChangedError, refreshSession, updateStoredTokens, verifySsoClientState };

package/dist/{chunk-7JLCFRUU.js → chunk-J2WAFXA6.js}

@@ -1,6 +1,6 @@
-import { authService } from './chunk-LPQKZRPC.js';
-import { authStore, currentUser, isAuthenticated, authActions } from './chunk-MBVOLE5U.js';
-import { isInitialized, initAuth, getUserRoles } from './chunk-K6TV3ZVS.js';
+import { authService } from './chunk-42EO3FSU.js';
+import { authStore, currentUser, isAuthenticated, authActions } from './chunk-W2ASN4NE.js';
+import { evaluateAccess, effectiveSubject, isAccessProbeActive, reportDecision, isInitialized, initAuth } from './chunk-5X6E5MZG.js';
 
 // src/svelte/guards/auth-guard.ts
 function checkAuth(options = {}) {
@@ -12,28 +12,26 @@ function checkAuth(options = {}) {
       redirectTo: "/login"
     };
   }
-  if (roles && roles.length > 0) {
-    const hasRoles = requireAllRoles ? authStore.hasAllRoles(roles) : authStore.hasAnyRole(roles);
-    if (!hasRoles) {
-      return {
-        allowed: false,
-        reason: "missing_role",
-        redirectTo: "/unauthorized"
-      };
-    }
+  const requirement = { roles, permissions, requireAllRoles, requireAllPermissions };
+  const user = authStore.user;
+  const { allowed, missing } = evaluateAccess(effectiveSubject(user), requirement);
+  if (isAccessProbeActive() && ((roles?.length ?? 0) > 0 || (permissions?.length ?? 0) > 0)) {
+    reportDecision("route", user, requirement, allowed, routeLabel());
   }
-  if (permissions && permissions.length > 0) {
-    const hasPermissions = requireAllPermissions ? authStore.hasAllPermissions(permissions) : authStore.hasAnyPermission(permissions);
-    if (!hasPermissions) {
-      return {
-        allowed: false,
-        reason: "missing_permission",
-        redirectTo: "/unauthorized"
-      };
-    }
+  if (!allowed) {
+    return {
+      allowed: false,
+      // Roles are checked first: a role miss is reported even if permissions also fail.
+      reason: missing.roles.length > 0 ? "missing_role" : "missing_permission",
+      redirectTo: "/unauthorized",
+      missing
+    };
   }
   return { allowed: true };
 }
+function routeLabel() {
+  return typeof window !== "undefined" ? window.location?.pathname : void 0;
+}
 function createAuthGuard(options = {}) {
   return (onDenied) => {
     const result = checkAuth(options);
@@ -92,8 +90,9 @@ function filterByAccess(items, user, options = {}) {
     childrenKey,
     pruneEmptyParents = true
   } = options;
-  const userRoles = getUserRoles(user);
-  const userPerms = user?.permissions || [];
+  const subject = effectiveSubject(user);
+  const userRoles = subject.roles;
+  const userPerms = subject.permissions;
   function isVisible(item) {
     const hasRoleRestriction = item.roles && item.roles.length > 0;
     const hasPermRestriction = item.permissions && item.permissions.length > 0;
@@ -106,6 +105,24 @@ function filterByAccess(items, user, options = {}) {
     if (!user) {
       return false;
     }
+    const allowed = isAllowed(item);
+    reportDecision(
+      "nav",
+      user,
+      {
+        roles: item.roles,
+        permissions: item.permissions,
+        requireAllRoles,
+        requireAllPermissions
+      },
+      allowed,
+      item.id ?? item.href
+    );
+    return allowed;
+  }
+  function isAllowed(item) {
+    const hasRoleRestriction = item.roles && item.roles.length > 0;
+    const hasPermRestriction = item.permissions && item.permissions.length > 0;
     if (hasRoleRestriction) {
       const hasRoles = requireAllRoles ? item.roles.every((r) => userRoles.includes(r)) : item.roles.some((r) => userRoles.includes(r));
       if (!hasRoles) {

package/dist/{chunk-MBVOLE5U.js → chunk-W2ASN4NE.js}

@@ -1,5 +1,5 @@
-import { InvalidAuthResponseError, bumpSessionGeneration, authApi } from './chunk-7AQYLLTA.js';
-import { isInitialized, getConfig, isValidSSOLogoutUrl, hasRole, hasAnyRole, hasAllRoles, decodeJWT, getStorage, getDefaultStorage } from './chunk-K6TV3ZVS.js';
+import { InvalidAuthResponseError, bumpSessionGeneration, authApi } from './chunk-ADCPJOPQ.js';
+import { onAccessSubjectChange, isInitialized, getConfig, isValidSSOLogoutUrl, hasRole, hasAnyRole, hasAllRoles, effectiveSubject, reportDecision, decodeJWT, getStorage, getDefaultStorage } from './chunk-5X6E5MZG.js';
 
 // src/svelte/stores/auth.svelte.ts
 var STORAGE_VERSION = 2;
@@ -72,6 +72,7 @@ var AuthStore = class {
   constructor() {
     this.subscribers = /* @__PURE__ */ new Set();
     this.state = loadAuthFromStorage();
+    onAccessSubjectChange(() => this.notify());
   }
   /**
    * Subscribe to state changes (Svelte store contract).
@@ -249,7 +250,7 @@ var AuthStore = class {
    * Check if user has a specific permission.
    */
   hasPermission(permission) {
-    return this.state.user?.permissions?.includes(permission) ?? false;
+    return this.checkPermissions([permission], false);
   }
   /**
    * Check if the user holds a specific role.
@@ -275,13 +276,27 @@ var AuthStore = class {
    * Check if user has any of the specified permissions.
    */
   hasAnyPermission(permissions) {
-    return permissions.some((perm) => this.state.user?.permissions?.includes(perm)) ?? false;
+    return this.checkPermissions(permissions, false);
   }
   /**
    * Check if user has all of the specified permissions.
    */
   hasAllPermissions(permissions) {
-    return permissions.every((perm) => this.state.user?.permissions?.includes(perm)) ?? false;
+    return this.checkPermissions(permissions, true);
+  }
+  /**
+   * Permission checks share one path so they honor the access probe's
+   * "view as" override and report to it. A guest holds no permissions.
+   */
+  checkPermissions(permissions, requireAll) {
+    const user = this.state.user;
+    const held = effectiveSubject(user).permissions;
+    const allowed = requireAll ? permissions.every((perm) => held.includes(perm)) : permissions.some((perm) => held.includes(perm));
+    if (permissions.length > 0) {
+      const requirement = { permissions, requireAllPermissions: requireAll };
+      reportDecision("check", user, requirement, allowed);
+    }
+    return allowed;
   }
   /**
    * Re-hydrate state from storage (useful after config changes).

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
 import { e as LoginCredentials, f as LoginResponse, g as LogoutResponse, R as RegisterData, l as RegisterResponse, q as User, k as ProfileUpdateData, C as ChangePasswordData, o as Session, A as ApiKey, c as CreateApiKeyRequest, d as CreateApiKeyResponse, U as UpdateApiKeyRequest, j as MFAStatus, i as MFASetupResponse, M as MFAChallengeData, h as MFAChallengeEmailResponse, D as Device, r as UserPreferences, L as LinkedAccount, n as SecurityEvent, P as Pagination, s as UserRolesResponse } from '../types-DF5Ny2IA.js';
 export { a as AuthConfig, b as AuthState, m as ResetPasswordData, S as SSOConfig, p as StorageAdapter, t as createMemoryStorage, u as createSessionStorage, v as getConfig, w as getDefaultStorage, x as getFetch, y as getStorage, z as initAuth, B as isInitialized, E as resetConfig } from '../types-DF5Ny2IA.js';
-export { A as AuthService, I as InvalidAuthResponseError, L as LoginOptions, M as MFAChallengeEmailError, a as MFAVerifyOptions, R as RoleDeniedError, S as SessionChangedError, b as authService, f as formatUserRoles, g as getAvatarFallback, c as getDisplayName, d as getGreeting, e as getUserEmail, h as getUserInitials, i as isRoleDeniedError, j as isSessionChangedError } from '../user-utils-Bo3lMsuT.js';
+export { A as ApiError, a as AuthService, I as InvalidAuthResponseError, L as LoginOptions, M as MFAChallengeEmailError, b as MFAVerifyOptions, R as RoleDeniedError, S as SessionChangedError, c as authService, f as formatUserRoles, g as getAvatarFallback, d as getDisplayName, e as getGreeting, h as getUserEmail, i as getUserInitials, j as isApiError, k as isRoleDeniedError, l as isSessionChangedError } from '../user-utils-DYyljbJR.js';
 
 /**
  * SSO client state
@@ -684,23 +684,156 @@ declare function computePrimaryRole(roles: readonly string[]): RoleName;
  * ```
  */
 declare function getEffectiveLevel(roles: readonly string[]): number;
+/** A user as the role checks accept it; `id` lets "view as" target the session user. */
+type RoleSubject = (Pick<User, 'roles'> & {
+    id?: string;
+    permissions?: string[];
+}) | null | undefined;
 /**
  * Whether a user holds a specific role.
  *
  * Exact membership — holding `admin` does NOT imply `agent`. This matches the
  * API's `requireRole`, so the UI can't offer something the server will then
  * reject with a 403.
+ *
+ * Honors the access probe's "view as" override for the user it targets.
  */
-declare function hasRole(user: Pick<User, 'roles'> | null | undefined, role: string): boolean;
+declare function hasRole(user: RoleSubject, role: string): boolean;
 /**
  * Whether a user holds at least one of the given roles.
  * An empty `roles` list matches nothing.
  */
-declare function hasAnyRole(user: Pick<User, 'roles'> | null | undefined, roles: readonly string[]): boolean;
+declare function hasAnyRole(user: RoleSubject, roles: readonly string[]): boolean;
 /**
  * Whether a user holds every one of the given roles.
  * An empty `roles` list matches vacuously (nothing was required).
  */
-declare function hasAllRoles(user: Pick<User, 'roles'> | null | undefined, roles: readonly string[]): boolean;
+declare function hasAllRoles(user: RoleSubject, roles: readonly string[]): boolean;
+
+/**
+ * Access probe
+ *
+ * Hooks that let a troubleshooting tool (the Access Inspector) see every
+ * role/permission decision the UI makes, and preview the UI as another
+ * role set ("view as").
+ *
+ * Both hooks are inert by default: with no probe installed a check costs one
+ * null test, and with no subject override every check reads the real user.
+ * They are browser-only: on the server the module state would be shared by
+ * every request, so the setters are no-ops there.
+ *
+ * SECURITY: this changes UI decisions only. The API still authorizes every
+ * request with the real token, so "view as" can never grant access.
+ */
+/** What a piece of UI or a request requires. Empty or absent lists are no restriction. */
+interface AccessRequirement {
+    roles?: readonly string[];
+    permissions?: readonly string[];
+    /** Require every listed role (default: any one of them). */
+    requireAllRoles?: boolean;
+    /** Require every listed permission (default: any one of them). */
+    requireAllPermissions?: boolean;
+}
+/** The roles and permissions a decision was made against. */
+interface AccessSubject {
+    roles: readonly string[];
+    permissions: readonly string[];
+}
+/** Outcome of {@link evaluateAccess}. */
+interface AccessEvaluation {
+    allowed: boolean;
+    /**
+     * What the subject lacks. In "any" mode a failed list is reported whole
+     * (holding any one of them would do); in "all" mode only the absent items.
+     */
+    missing: {
+        roles: string[];
+        permissions: string[];
+    };
+}
+/** Where a reported decision came from. */
+type AccessCheckSource = 
+/** `hasRole` / `hasPermission` and friends (core helpers and the store). */
+'check'
+/** `checkAuth` and the route guards built on it. */
+ | 'route'
+/** `filterByAccess` / `canAccess` (navigation). */
+ | 'nav'
+/** A 403 from the API. */
+ | 'http'
+/** A UI element (the inspector's own `RequireAccess` / `requires`). */
+ | 'element';
+interface AccessCheckEvent extends AccessEvaluation {
+    source: AccessCheckSource;
+    requirement: AccessRequirement;
+    /** Id of the user checked, or null for a guest. Checks also run for other users (admin lists). */
+    subjectId: string | null;
+    /** True when the decision used the "view as" override instead of the real user. */
+    simulated: boolean;
+    /** Human-readable context: a nav item id/href, or `METHOD /path` for HTTP. */
+    label?: string;
+    /** Present for `http` events. */
+    http?: {
+        method: string;
+        endpoint: string;
+        status: number;
+        code?: string;
+    };
+}
+type AccessProbe = (event: AccessCheckEvent) => void;
+type SubjectUser = {
+    id?: string;
+    roles?: readonly string[];
+    permissions?: readonly string[];
+};
+/**
+ * Install (or with `null`, remove) the function that receives every access
+ * decision. Only one probe at a time; returns the previous one. No-op on the server.
+ */
+declare function setAccessProbe(next: AccessProbe | null): AccessProbe | null;
+/** Whether a probe is installed — check before building an event. */
+declare function isAccessProbeActive(): boolean;
+/** Hand an event to the probe, if any. A throwing probe never breaks the check. */
+declare function reportAccess(event: AccessCheckEvent): void;
+/**
+ * Make access checks for `userId` use `subject` instead of that user's real
+ * roles and permissions. Checks for any other user are unaffected, so admin
+ * screens listing other people keep working. No-op on the server.
+ */
+declare function setAccessSubject(userId: string, subject: AccessSubject): void;
+/** Remove the "view as" override. */
+declare function clearAccessSubject(): void;
+/** The active override, if any. */
+declare function getAccessSubjectOverride(): {
+    userId: string;
+    subject: AccessSubject;
+} | null;
+/** Called whenever the override changes, so stores can re-run their checks. */
+declare function onAccessSubjectChange(listener: () => void): () => void;
+/**
+ * The roles and permissions to decide access with for `user`: the override
+ * when it targets this user, otherwise the user's own.
+ */
+declare function effectiveSubject(user: SubjectUser | null | undefined): AccessSubject & {
+    simulated: boolean;
+};
+/**
+ * Decide a requirement against a subject. Roles and permissions must both
+ * pass when both are given; within each list `requireAll*` picks all vs any.
+ * Exact membership, like the API (`admin` does not imply `agent`).
+ */
+declare function evaluateAccess(subject: AccessSubject, requirement: AccessRequirement): AccessEvaluation;
+/**
+ * Report a decision the caller already made. Recomputes `missing` against
+ * the same subject so every source reports it the same way.
+ */
+declare function reportDecision(source: AccessCheckSource, user: SubjectUser | null | undefined, requirement: AccessRequirement, allowed: boolean, label?: string): void;
+/**
+ * Read what a CHAPI 403 says was required. `requirePermissions` sends
+ * `{ required: string[] }` with code `INSUFFICIENT_PERMISSIONS`;
+ * `requireRole` sends `{ required: string }` with code `FORBIDDEN`. An
+ * optional `mode: 'any' | 'all'` overrides the defaults (permissions: all).
+ */
+declare function requirementFromDenial(code: string | undefined, details: unknown): AccessRequirement | null;
 
-export { ApiKey, type ApiRequestOptions, type ApiResponse, ChangePasswordData, CreateApiKeyRequest, CreateApiKeyResponse, Device, type JWTPayload, LinkedAccount, LoginCredentials, LoginResponse, LogoutResponse, MFAChallengeData, MFAChallengeEmailResponse, MFASetupResponse, MFAStatus, Pagination, ProfileUpdateData, ROLE_HIERARCHY, ROLE_NAMES, type RefreshOutcome, type RefreshSessionOptions, RegisterData, RegisterResponse, type RoleName, SSO_CLIENT_STATE_PARAM, SSO_CLIENT_STATE_TTL_MS, SecurityEvent, Session, type SsoClientStateResult, type SsoClientStateVerification, UpdateApiKeyRequest, User, UserPreferences, UserRolesResponse, api, apiRequest, authApi, clearStoredAuth, computePrimaryRole, consumeSsoClientState, createSsoClientState, decodeJWT, extractClaims, extractData, getAccessToken, getAvailableMethods, getEffectiveLevel, getMfaToken, getRefreshToken, getSessionToken, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, initCrossTabSync, isLoginSuccessResponse, isMfaChallengeResponse, isTokenExpired, refreshSession, updateStoredTokens, verifySsoClientState };
+export { type AccessCheckEvent, type AccessCheckSource, type AccessEvaluation, type AccessProbe, type AccessRequirement, type AccessSubject, ApiKey, type ApiRequestOptions, type ApiResponse, ChangePasswordData, CreateApiKeyRequest, CreateApiKeyResponse, Device, type JWTPayload, LinkedAccount, LoginCredentials, LoginResponse, LogoutResponse, MFAChallengeData, MFAChallengeEmailResponse, MFASetupResponse, MFAStatus, Pagination, ProfileUpdateData, ROLE_HIERARCHY, ROLE_NAMES, type RefreshOutcome, type RefreshSessionOptions, RegisterData, RegisterResponse, type RoleName, SSO_CLIENT_STATE_PARAM, SSO_CLIENT_STATE_TTL_MS, SecurityEvent, Session, type SsoClientStateResult, type SsoClientStateVerification, UpdateApiKeyRequest, User, UserPreferences, UserRolesResponse, api, apiRequest, authApi, clearAccessSubject, clearStoredAuth, computePrimaryRole, consumeSsoClientState, createSsoClientState, decodeJWT, effectiveSubject, evaluateAccess, extractClaims, extractData, getAccessSubjectOverride, getAccessToken, getAvailableMethods, getEffectiveLevel, getMfaToken, getRefreshToken, getSessionToken, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, initCrossTabSync, isAccessProbeActive, isLoginSuccessResponse, isMfaChallengeResponse, isTokenExpired, onAccessSubjectChange, refreshSession, reportAccess, reportDecision, requirementFromDenial, setAccessProbe, setAccessSubject, updateStoredTokens, verifySsoClientState };

package/dist/core/index.js

@@ -1,3 +1,3 @@
-export { AuthService, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse } from '../chunk-LPQKZRPC.js';
-export { InvalidAuthResponseError, MFAChallengeEmailError, RoleDeniedError, SSO_CLIENT_STATE_PARAM, SSO_CLIENT_STATE_TTL_MS, SessionChangedError, api, apiRequest, authApi, clearStoredAuth, consumeSsoClientState, createSsoClientState, extractData, getAccessToken, getRefreshToken, getSessionToken, initCrossTabSync, isRoleDeniedError, isSessionChangedError, refreshSession, updateStoredTokens, verifySsoClientState } from '../chunk-7AQYLLTA.js';
-export { ROLE_HIERARCHY, ROLE_NAMES, computePrimaryRole, createMemoryStorage, createSessionStorage, decodeJWT, extractClaims, getConfig, getDefaultStorage, getEffectiveLevel, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, initAuth, isInitialized, isTokenExpired, resetConfig } from '../chunk-K6TV3ZVS.js';
+export { AuthService, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse } from '../chunk-42EO3FSU.js';
+export { ApiError, InvalidAuthResponseError, MFAChallengeEmailError, RoleDeniedError, SSO_CLIENT_STATE_PARAM, SSO_CLIENT_STATE_TTL_MS, SessionChangedError, api, apiRequest, authApi, clearStoredAuth, consumeSsoClientState, createSsoClientState, extractData, getAccessToken, getRefreshToken, getSessionToken, initCrossTabSync, isApiError, isRoleDeniedError, isSessionChangedError, refreshSession, updateStoredTokens, verifySsoClientState } from '../chunk-ADCPJOPQ.js';
+export { ROLE_HIERARCHY, ROLE_NAMES, clearAccessSubject, computePrimaryRole, createMemoryStorage, createSessionStorage, decodeJWT, effectiveSubject, evaluateAccess, extractClaims, getAccessSubjectOverride, getConfig, getDefaultStorage, getEffectiveLevel, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, initAuth, isAccessProbeActive, isInitialized, isTokenExpired, onAccessSubjectChange, reportAccess, reportDecision, requirementFromDenial, resetConfig, setAccessProbe, setAccessSubject } from '../chunk-5X6E5MZG.js';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { A as ApiKey, a as AuthConfig, b as AuthState, C as ChangePasswordData, c as CreateApiKeyRequest, d as CreateApiKeyResponse, D as Device, L as LinkedAccount, e as LoginCredentials, f as LoginResponse, g as LogoutResponse, M as MFAChallengeData, h as MFAChallengeEmailResponse, i as MFASetupResponse, j as MFAStatus, P as Pagination, k as ProfileUpdateData, R as RegisterData, l as RegisterResponse, m as ResetPasswordData, S as SSOConfig, n as SecurityEvent, o as Session, p as StorageAdapter, U as UpdateApiKeyRequest, q as User, r as UserPreferences, s as UserRolesResponse, t as createMemoryStorage, u as createSessionStorage, v as getConfig, w as getDefaultStorage, x as getFetch, y as getStorage, z as initAuth, B as isInitialized, E as resetConfig } from './types-DF5Ny2IA.js';
-export { ApiRequestOptions, ApiResponse, JWTPayload, ROLE_HIERARCHY, ROLE_NAMES, RefreshOutcome, RefreshSessionOptions, RoleName, SSO_CLIENT_STATE_PARAM, SSO_CLIENT_STATE_TTL_MS, SsoClientStateResult, SsoClientStateVerification, api, apiRequest, authApi, clearStoredAuth, computePrimaryRole, consumeSsoClientState, createSsoClientState, decodeJWT, extractClaims, extractData, getAccessToken, getAvailableMethods, getEffectiveLevel, getMfaToken, getRefreshToken, getSessionToken, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, initCrossTabSync, isLoginSuccessResponse, isMfaChallengeResponse, isTokenExpired, refreshSession, updateStoredTokens, verifySsoClientState } from './core/index.js';
-export { A as AuthService, I as InvalidAuthResponseError, L as LoginOptions, M as MFAChallengeEmailError, a as MFAVerifyOptions, R as RoleDeniedError, S as SessionChangedError, b as authService, f as formatUserRoles, g as getAvatarFallback, c as getDisplayName, d as getGreeting, e as getUserEmail, h as getUserInitials, i as isRoleDeniedError, j as isSessionChangedError } from './user-utils-Bo3lMsuT.js';
+export { AccessCheckEvent, AccessCheckSource, AccessEvaluation, AccessProbe, AccessRequirement, AccessSubject, ApiRequestOptions, ApiResponse, JWTPayload, ROLE_HIERARCHY, ROLE_NAMES, RefreshOutcome, RefreshSessionOptions, RoleName, SSO_CLIENT_STATE_PARAM, SSO_CLIENT_STATE_TTL_MS, SsoClientStateResult, SsoClientStateVerification, api, apiRequest, authApi, clearAccessSubject, clearStoredAuth, computePrimaryRole, consumeSsoClientState, createSsoClientState, decodeJWT, effectiveSubject, evaluateAccess, extractClaims, extractData, getAccessSubjectOverride, getAccessToken, getAvailableMethods, getEffectiveLevel, getMfaToken, getRefreshToken, getSessionToken, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, initCrossTabSync, isAccessProbeActive, isLoginSuccessResponse, isMfaChallengeResponse, isTokenExpired, onAccessSubjectChange, refreshSession, reportAccess, reportDecision, requirementFromDenial, setAccessProbe, setAccessSubject, updateStoredTokens, verifySsoClientState } from './core/index.js';
+export { A as ApiError, a as AuthService, I as InvalidAuthResponseError, L as LoginOptions, M as MFAChallengeEmailError, b as MFAVerifyOptions, R as RoleDeniedError, S as SessionChangedError, c as authService, f as formatUserRoles, g as getAvatarFallback, d as getDisplayName, e as getGreeting, h as getUserEmail, i as getUserInitials, j as isApiError, k as isRoleDeniedError, l as isSessionChangedError } from './user-utils-DYyljbJR.js';
 export { AuthClient, AuthGuardOptions, AuthGuardResult, AuthHookOptions, CreateAuthClientOptions, NavFilterOptions, RoleRestrictedItem, authActions, authStore, canAccess, checkAuth, createAuthClient, createAuthGuard, createAuthHook, createNavFilter, currentUser, filterByAccess, filterNavSections, isAuthenticated, matchesRoute, protectedLoad, requireAuth, requirePermission, requireRole, routePatterns } from './svelte/index.js';

package/dist/index.js

@@ -1,5 +1,5 @@
-export { canAccess, checkAuth, createAuthClient, createAuthGuard, createAuthHook, createNavFilter, filterByAccess, filterNavSections, matchesRoute, protectedLoad, requireAuth, requirePermission, requireRole, routePatterns } from './chunk-7JLCFRUU.js';
-export { AuthService, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse } from './chunk-LPQKZRPC.js';
-export { authActions, authStore, currentUser, isAuthenticated } from './chunk-MBVOLE5U.js';
-export { InvalidAuthResponseError, MFAChallengeEmailError, RoleDeniedError, SSO_CLIENT_STATE_PARAM, SSO_CLIENT_STATE_TTL_MS, SessionChangedError, api, apiRequest, authApi, clearStoredAuth, consumeSsoClientState, createSsoClientState, extractData, getAccessToken, getRefreshToken, getSessionToken, initCrossTabSync, isRoleDeniedError, isSessionChangedError, refreshSession, updateStoredTokens, verifySsoClientState } from './chunk-7AQYLLTA.js';
-export { ROLE_HIERARCHY, ROLE_NAMES, computePrimaryRole, createMemoryStorage, createSessionStorage, decodeJWT, extractClaims, getConfig, getDefaultStorage, getEffectiveLevel, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, initAuth, isInitialized, isTokenExpired, resetConfig } from './chunk-K6TV3ZVS.js';
+export { canAccess, checkAuth, createAuthClient, createAuthGuard, createAuthHook, createNavFilter, filterByAccess, filterNavSections, matchesRoute, protectedLoad, requireAuth, requirePermission, requireRole, routePatterns } from './chunk-J2WAFXA6.js';
+export { AuthService, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse } from './chunk-42EO3FSU.js';
+export { authActions, authStore, currentUser, isAuthenticated } from './chunk-W2ASN4NE.js';
+export { ApiError, InvalidAuthResponseError, MFAChallengeEmailError, RoleDeniedError, SSO_CLIENT_STATE_PARAM, SSO_CLIENT_STATE_TTL_MS, SessionChangedError, api, apiRequest, authApi, clearStoredAuth, consumeSsoClientState, createSsoClientState, extractData, getAccessToken, getRefreshToken, getSessionToken, initCrossTabSync, isApiError, isRoleDeniedError, isSessionChangedError, refreshSession, updateStoredTokens, verifySsoClientState } from './chunk-ADCPJOPQ.js';
+export { ROLE_HIERARCHY, ROLE_NAMES, clearAccessSubject, computePrimaryRole, createMemoryStorage, createSessionStorage, decodeJWT, effectiveSubject, evaluateAccess, extractClaims, getAccessSubjectOverride, getConfig, getDefaultStorage, getEffectiveLevel, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, initAuth, isAccessProbeActive, isInitialized, isTokenExpired, onAccessSubjectChange, reportAccess, reportDecision, requirementFromDenial, resetConfig, setAccessProbe, setAccessSubject } from './chunk-5X6E5MZG.js';

package/dist/svelte/index.d.ts

@@ -1,7 +1,7 @@
 import { b as AuthState, q as User, a as AuthConfig } from '../types-DF5Ny2IA.js';
 export { z as initAuth, B as isInitialized } from '../types-DF5Ny2IA.js';
-import { b as authService } from '../user-utils-Bo3lMsuT.js';
-export { I as InvalidAuthResponseError, R as RoleDeniedError, S as SessionChangedError, f as formatUserRoles, g as getAvatarFallback, c as getDisplayName, d as getGreeting, e as getUserEmail, h as getUserInitials, i as isRoleDeniedError, j as isSessionChangedError } from '../user-utils-Bo3lMsuT.js';
+import { c as authService } from '../user-utils-DYyljbJR.js';
+export { I as InvalidAuthResponseError, R as RoleDeniedError, S as SessionChangedError, f as formatUserRoles, g as getAvatarFallback, d as getDisplayName, e as getGreeting, h as getUserEmail, i as getUserInitials, k as isRoleDeniedError, l as isSessionChangedError } from '../user-utils-DYyljbJR.js';
 
 /**
  * Auth Store
@@ -90,6 +90,11 @@ declare class AuthStore {
      * Check if user has all of the specified permissions.
      */
     hasAllPermissions(permissions: string[]): boolean;
+    /**
+     * Permission checks share one path so they honor the access probe's
+     * "view as" override and report to it. A guest holds no permissions.
+     */
+    private checkPermissions;
     /**
      * Re-hydrate state from storage (useful after config changes).
      */
@@ -174,6 +179,14 @@ interface AuthGuardResult {
     reason?: 'not_authenticated' | 'missing_role' | 'missing_permission';
     /** Redirect URL suggestion */
     redirectTo?: string;
+    /**
+     * What the user lacks when denied for a role or permission: the whole
+     * list in "any" mode, only the absent items in "all" mode.
+     */
+    missing?: {
+        roles: string[];
+        permissions: string[];
+    };
 }
 /**
  * Check if the current user passes the auth guard.

package/dist/svelte/index.js

@@ -1,5 +1,5 @@
-export { canAccess, checkAuth, createAuthClient, createAuthGuard, createAuthHook, createNavFilter, filterByAccess, filterNavSections, matchesRoute, protectedLoad, requireAuth, requirePermission, requireRole, routePatterns } from '../chunk-7JLCFRUU.js';
-export { formatUserRoles, getAvatarFallback, getDisplayName, getGreeting, getUserEmail, getUserInitials } from '../chunk-LPQKZRPC.js';
-export { authActions, authStore, currentUser, isAuthenticated } from '../chunk-MBVOLE5U.js';
-export { InvalidAuthResponseError, RoleDeniedError, SessionChangedError, isRoleDeniedError, isSessionChangedError } from '../chunk-7AQYLLTA.js';
-export { initAuth, isInitialized } from '../chunk-K6TV3ZVS.js';
+export { canAccess, checkAuth, createAuthClient, createAuthGuard, createAuthHook, createNavFilter, filterByAccess, filterNavSections, matchesRoute, protectedLoad, requireAuth, requirePermission, requireRole, routePatterns } from '../chunk-J2WAFXA6.js';
+export { formatUserRoles, getAvatarFallback, getDisplayName, getGreeting, getUserEmail, getUserInitials } from '../chunk-42EO3FSU.js';
+export { authActions, authStore, currentUser, isAuthenticated } from '../chunk-W2ASN4NE.js';
+export { InvalidAuthResponseError, RoleDeniedError, SessionChangedError, isRoleDeniedError, isSessionChangedError } from '../chunk-ADCPJOPQ.js';
+export { initAuth, isInitialized } from '../chunk-5X6E5MZG.js';

package/dist/testing/index.js

@@ -1,4 +1,4 @@
-import { hasRole, hasAnyRole, hasAllRoles, initAuth, resetConfig, getUserRoles, isTokenExpired, decodeJWT } from '../chunk-K6TV3ZVS.js';
+import { hasRole, hasAnyRole, hasAllRoles, initAuth, resetConfig, getUserRoles, isTokenExpired, decodeJWT } from '../chunk-5X6E5MZG.js';
 
 // src/testing/fixtures/users.ts
 var mockUser = {

package/dist/{user-utils-Bo3lMsuT.d.ts → user-utils-DYyljbJR.d.ts}

@@ -356,6 +356,38 @@ declare class MFAChallengeEmailError extends Error {
     readonly retryAfterSeconds?: number;
     constructor(message: string, status: number, retryAfterSeconds?: number);
 }
+/**
+ * Error thrown by `apiRequest` (and the `api.*` helpers) when the API answers
+ * with a non-2xx status. `message` is the server's message, exactly as the
+ * plain `Error` used to carry, so existing `catch (e) { e.message }` code is
+ * unaffected; the status, CHAPI error code and `details` are kept alongside.
+ *
+ * For a 403, `details.required` lists what CHAPI said was missing.
+ */
+declare class ApiError extends Error {
+    readonly name = "ApiError";
+    /** HTTP status. */
+    readonly status: number;
+    /** CHAPI error code (e.g. `INSUFFICIENT_PERMISSIONS`), when sent. */
+    readonly code?: string;
+    /** CHAPI `error.details`, when sent. */
+    readonly details?: Record<string, unknown>;
+    /** Request method. */
+    readonly method: string;
+    /** The endpoint as passed to `apiRequest`. */
+    readonly endpoint: string;
+    constructor(message: string, init: {
+        status: number;
+        code?: string;
+        details?: Record<string, unknown>;
+        method: string;
+        endpoint: string;
+    });
+}
+/**
+ * Type guard to check if an error is an ApiError.
+ */
+declare function isApiError(error: unknown): error is ApiError;
 
 /**
  * User Display Utilities
@@ -460,4 +492,4 @@ declare function formatUserRoles(user: User | null | undefined, options?: {
     capitalize?: boolean;
 }): string;
 
-export { AuthService as A, InvalidAuthResponseError as I, type LoginOptions as L, MFAChallengeEmailError as M, RoleDeniedError as R, SessionChangedError as S, type MFAVerifyOptions as a, authService as b, getDisplayName as c, getGreeting as d, getUserEmail as e, formatUserRoles as f, getAvatarFallback as g, getUserInitials as h, isRoleDeniedError as i, isSessionChangedError as j };
+export { ApiError as A, InvalidAuthResponseError as I, type LoginOptions as L, MFAChallengeEmailError as M, RoleDeniedError as R, SessionChangedError as S, AuthService as a, type MFAVerifyOptions as b, authService as c, getDisplayName as d, getGreeting as e, formatUserRoles as f, getAvatarFallback as g, getUserEmail as h, getUserInitials as i, isApiError as j, isRoleDeniedError as k, isSessionChangedError as l };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/auth",
-  "version": "1.42.0",
+  "version": "1.45.0",
   "description": "Authentication services and Svelte bindings for Classic Theme apps",
   "type": "module",
   "main": "dist/index.js",

package/dist/auth.svelte-XY4FQFZQ.js

@@ -1,3 +0,0 @@
-export { authActions, authStore, currentUser, isAuthenticated } from './chunk-MBVOLE5U.js';
-import './chunk-7AQYLLTA.js';
-import './chunk-K6TV3ZVS.js';