@classic-homes/auth 1.42.1 → 1.46.0

package/README.md

@@ -337,6 +337,51 @@ 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`.
+- While a probe is installed, requests to the API origin (never other hosts)
+  send `X-Access-Debug: 1`. CHAPI answers admin sessions with
+  `X-Access-Redacted: taxId=vendors:read:sensitive, notes=*`, reported as an
+  informational `source: 'redacted'` event (`allowed: true`, path only) with
+  `fields: { name, permission }[]`; `*` means no permission is configured
+  (default-deny). It reflects the real token, never "view as". No header, no
+  event. The custom header makes cross-origin API requests preflighted.
+- `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 +421,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-IWSWWF6U.js

@@ -0,0 +1,3 @@
+export { authActions, authStore, currentUser, isAuthenticated } from './chunk-Q4Q3CJVC.js';
+import './chunk-7SFVHDFP.js';
+import './chunk-EFS272S3.js';

package/dist/{chunk-QV3DUSP5.js → chunk-7SFVHDFP.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, ACCESS_DEBUG_HEADER, ACCESS_REDACTED_HEADER, ACCESS_REDACTED_TRUNCATED_HEADER, parseRedactedHeader, reportAccess, requirementFromDenial, decodeJWT } from './chunk-EFS272S3.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-FUCU4DYP.js');
+    const { authStore } = await import('./auth.svelte-IWSWWF6U.js');
     apply(authStore);
   } catch {
   }
@@ -371,6 +389,65 @@ function isApiOrigin(url, baseUrl) {
     return false;
   }
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function probePath(endpoint) {
+  let path = endpoint.split(/[?#]/, 1)[0];
+  try {
+    if (/^https?:\/\//i.test(path)) path = new URL(path).pathname;
+  } catch {
+  }
+  return path;
+}
+function reportRedacted(method, endpoint, response) {
+  let header;
+  let truncated;
+  try {
+    header = response.headers.get(ACCESS_REDACTED_HEADER);
+    truncated = response.headers.get(ACCESS_REDACTED_TRUNCATED_HEADER);
+  } catch {
+    return;
+  }
+  const { fields, omitted } = parseRedactedHeader(header);
+  if (fields.length === 0) return;
+  const serverOmitted = Number.parseInt(truncated ?? "", 10);
+  const fieldsOmitted = omitted + (Number.isFinite(serverOmitted) && serverOmitted > 0 ? Math.min(serverOmitted, 1e6) : 0);
+  const permissions = [...new Set(fields.map((f) => f.permission).filter((p) => p !== "*"))];
+  const path = probePath(endpoint);
+  reportAccess({
+    source: "redacted",
+    requirement: permissions.length ? { permissions } : {},
+    // Informational: the request succeeded, the fields say what was withheld.
+    allowed: true,
+    missing: { roles: [], permissions: [] },
+    // The server redacted for the real token, never the "view as" preview.
+    subjectId: null,
+    simulated: false,
+    label: `${method} ${path}`,
+    http: { method, endpoint: path, status: response.status },
+    fields,
+    ...fieldsOmitted > 0 && { fieldsOmitted }
+  });
+}
+function reportForbidden(method, endpoint, code, details) {
+  const path = probePath(endpoint);
+  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);
 }
@@ -422,6 +499,8 @@ async function apiRequestInternal(endpoint, options, isRetry, startedIn) {
     "Content-Type": "application/json",
     ...fetchOptions.headers
   };
+  const accessDebug = isAccessProbeActive() && (!isAbsolute || isApiOrigin(url, config.baseUrl));
+  if (accessDebug) headers[ACCESS_DEBUG_HEADER] = "1";
   if (authenticated) {
     const accessToken = getAccessToken();
     const sessionToken = getSessionToken();
@@ -455,6 +534,9 @@ async function apiRequestInternal(endpoint, options, isRetry, startedIn) {
       }
       throw new Error("Authentication service unavailable. Please try again.");
     }
+    if (accessDebug && isAccessProbeActive()) {
+      reportRedacted((fetchOptions.method ?? "GET").toUpperCase(), endpoint, response);
+    }
     let data;
     const contentType = response.headers.get("content-type");
     if (contentType?.includes("application/json")) {
@@ -496,7 +578,19 @@ 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;
     }
@@ -1100,4 +1194,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-A6JJQCBU.js → chunk-BGQVBSXN.js}

@@ -1,5 +1,5 @@
-import { authApi, InvalidAuthResponseError, RoleDeniedError } from './chunk-QV3DUSP5.js';
-import { hasAnyRole, getUserRoles } from './chunk-K6TV3ZVS.js';
+import { authApi, InvalidAuthResponseError, RoleDeniedError } from './chunk-7SFVHDFP.js';
+import { getUserRoles } from './chunk-EFS272S3.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-FUCU4DYP.js')).authStore;
+    store = (await import('./auth.svelte-IWSWWF6U.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-EFS272S3.js}

@@ -193,6 +193,121 @@ 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 };
+}
+var ACCESS_DEBUG_HEADER = "X-Access-Debug";
+var ACCESS_REDACTED_HEADER = "X-Access-Redacted";
+var ACCESS_REDACTED_TRUNCATED_HEADER = "X-Access-Redacted-Truncated";
+var MAX_REDACTED_FIELDS = 100;
+var MAX_REDACTED_HEADER = 16384;
+var REDACTED_ENTRY = /^([A-Za-z0-9_.:*-]{1,128})=([A-Za-z0-9_.:*-]{1,128})$/;
+function parseRedactedHeader(value) {
+  const fields = [];
+  let omitted = 0;
+  if (!value) return { fields, omitted };
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of value.slice(0, MAX_REDACTED_HEADER).split(",")) {
+    const match = REDACTED_ENTRY.exec(raw.trim());
+    if (!match || seen.has(match[1])) continue;
+    seen.add(match[1]);
+    if (fields.length >= MAX_REDACTED_FIELDS) omitted += 1;
+    else fields.push({ name: match[1], permission: match[2] });
+  }
+  return { fields, omitted };
+}
+
 // src/core/roles.ts
 var ROLE_NAMES = [
   "admin",
@@ -275,15 +390,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 { ACCESS_DEBUG_HEADER, ACCESS_REDACTED_HEADER, ACCESS_REDACTED_TRUNCATED_HEADER, 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, parseRedactedHeader, reportAccess, reportDecision, requirementFromDenial, resetConfig, setAccessProbe, setAccessSubject };

package/dist/{chunk-IR6DVUUF.js → chunk-Q4Q3CJVC.js}

@@ -1,5 +1,5 @@
-import { InvalidAuthResponseError, bumpSessionGeneration, authApi } from './chunk-QV3DUSP5.js';
-import { isInitialized, getConfig, isValidSSOLogoutUrl, hasRole, hasAnyRole, hasAllRoles, decodeJWT, getStorage, getDefaultStorage } from './chunk-K6TV3ZVS.js';
+import { InvalidAuthResponseError, bumpSessionGeneration, authApi } from './chunk-7SFVHDFP.js';
+import { onAccessSubjectChange, isInitialized, getConfig, isValidSSOLogoutUrl, hasRole, hasAnyRole, hasAllRoles, effectiveSubject, reportDecision, decodeJWT, getStorage, getDefaultStorage } from './chunk-EFS272S3.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/{chunk-G6UH4HBI.js → chunk-TJRFP24M.js}

@@ -1,6 +1,6 @@
-import { authService } from './chunk-A6JJQCBU.js';
-import { authStore, currentUser, isAuthenticated, authActions } from './chunk-IR6DVUUF.js';
-import { isInitialized, initAuth, getUserRoles } from './chunk-K6TV3ZVS.js';
+import { authService } from './chunk-BGQVBSXN.js';
+import { authStore, currentUser, isAuthenticated, authActions } from './chunk-Q4Q3CJVC.js';
+import { evaluateAccess, effectiveSubject, isAccessProbeActive, reportDecision, isInitialized, initAuth } from './chunk-EFS272S3.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/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,187 @@ 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'
+/**
+ * Fields the API left out of a response (`X-Access-Redacted`). Informational,
+ * not a denial: `allowed` is true and `missing` is empty; see `fields`.
+ */
+ | 'redacted';
+/** A top-level response field the API withheld, and the permission that would reveal it. */
+interface RedactedField {
+    name: string;
+    /** `*` = the field has no permission configured and is dropped by default-deny. */
+    permission: string;
+}
+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` and `redacted` events. */
+    http?: {
+        method: string;
+        endpoint: string;
+        status: number;
+        code?: string;
+    };
+    /** Present for `redacted` events: the withheld fields, in the order the server listed them. */
+    fields?: RedactedField[];
+    /** `redacted` events: entries the server (or the parser's cap) left out of `fields`. */
+    fieldsOmitted?: number;
+}
+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;
+/** Request header asking CHAPI to say which fields it redacted (admin sessions only). */
+declare const ACCESS_DEBUG_HEADER = "X-Access-Debug";
+/** Response header: `name=permission` entries joined by `", "`. */
+declare const ACCESS_REDACTED_HEADER = "X-Access-Redacted";
+/** Response header: how many entries the server left out of {@link ACCESS_REDACTED_HEADER}. */
+declare const ACCESS_REDACTED_TRUNCATED_HEADER = "X-Access-Redacted-Truncated";
+/**
+ * Parse an `X-Access-Redacted` value (`taxId=vendors:read:sensitive, notes=*`).
+ * Malformed entries are skipped, a repeated name keeps its first permission,
+ * and at most 100 fields are kept; `omitted` counts the valid ones dropped by
+ * that cap. A missing or empty header yields no fields.
+ */
+declare function parseRedactedHeader(value: string | null | undefined): {
+    fields: RedactedField[];
+    omitted: number;
+};
 
-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 { ACCESS_DEBUG_HEADER, ACCESS_REDACTED_HEADER, ACCESS_REDACTED_TRUNCATED_HEADER, 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 RedactedField, 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, parseRedactedHeader, 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-A6JJQCBU.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-QV3DUSP5.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-BGQVBSXN.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-7SFVHDFP.js';
+export { ACCESS_DEBUG_HEADER, ACCESS_REDACTED_HEADER, ACCESS_REDACTED_TRUNCATED_HEADER, 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, parseRedactedHeader, reportAccess, reportDecision, requirementFromDenial, resetConfig, setAccessProbe, setAccessSubject } from '../chunk-EFS272S3.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 { ACCESS_DEBUG_HEADER, ACCESS_REDACTED_HEADER, ACCESS_REDACTED_TRUNCATED_HEADER, AccessCheckEvent, AccessCheckSource, AccessEvaluation, AccessProbe, AccessRequirement, AccessSubject, ApiRequestOptions, ApiResponse, JWTPayload, ROLE_HIERARCHY, ROLE_NAMES, RedactedField, 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, parseRedactedHeader, 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-G6UH4HBI.js';
-export { AuthService, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse } from './chunk-A6JJQCBU.js';
-export { authActions, authStore, currentUser, isAuthenticated } from './chunk-IR6DVUUF.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-QV3DUSP5.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-TJRFP24M.js';
+export { AuthService, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse } from './chunk-BGQVBSXN.js';
+export { authActions, authStore, currentUser, isAuthenticated } from './chunk-Q4Q3CJVC.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-7SFVHDFP.js';
+export { ACCESS_DEBUG_HEADER, ACCESS_REDACTED_HEADER, ACCESS_REDACTED_TRUNCATED_HEADER, 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, parseRedactedHeader, reportAccess, reportDecision, requirementFromDenial, resetConfig, setAccessProbe, setAccessSubject } from './chunk-EFS272S3.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-G6UH4HBI.js';
-export { formatUserRoles, getAvatarFallback, getDisplayName, getGreeting, getUserEmail, getUserInitials } from '../chunk-A6JJQCBU.js';
-export { authActions, authStore, currentUser, isAuthenticated } from '../chunk-IR6DVUUF.js';
-export { InvalidAuthResponseError, RoleDeniedError, SessionChangedError, isRoleDeniedError, isSessionChangedError } from '../chunk-QV3DUSP5.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-TJRFP24M.js';
+export { formatUserRoles, getAvatarFallback, getDisplayName, getGreeting, getUserEmail, getUserInitials } from '../chunk-BGQVBSXN.js';
+export { authActions, authStore, currentUser, isAuthenticated } from '../chunk-Q4Q3CJVC.js';
+export { InvalidAuthResponseError, RoleDeniedError, SessionChangedError, isRoleDeniedError, isSessionChangedError } from '../chunk-7SFVHDFP.js';
+export { initAuth, isInitialized } from '../chunk-EFS272S3.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-EFS272S3.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.1",
+  "version": "1.46.0",
   "description": "Authentication services and Svelte bindings for Classic Theme apps",
   "type": "module",
   "main": "dist/index.js",

package/dist/auth.svelte-FUCU4DYP.js

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