@classic-homes/auth 0.1.56 → 1.0.0

package/README.md

@@ -202,6 +202,74 @@ export function load({ url }) {
 }
 ```
 
+## Roles
+
+A user holds a **set** of roles (`user.roles`). Their permissions are the union
+across all of them, so a user's access is broader than any single role.
+
+```typescript
+import { authStore } from '@classic-homes/auth/svelte';
+
+// A manager who is also an agent
+authStore.user?.roles; // ['manager', 'agent']
+
+authStore.hasRole('manager'); // true
+authStore.hasRole('agent'); // true — secondary roles count
+authStore.hasAnyRole(['admin', 'agent']); // true
+authStore.hasAllRoles(['manager', 'agent']); // true
+```
+
+**Role checks are exact membership.** Holding `admin` does not imply `agent`:
+
+```typescript
+authStore.user?.roles; // ['admin']
+authStore.hasRole('agent'); // false
+```
+
+This mirrors the API, so the UI can't offer something the server will reject.
+To let admins through as well, list the roles you accept:
+`checkAuth({ roles: ['admin', 'agent'] })`.
+
+### Displaying a role
+
+`computePrimaryRole` resolves the highest-tier role for display. It's a label,
+not a capability — never gate on it:
+
+```typescript
+import { computePrimaryRole, getEffectiveLevel } from '@classic-homes/auth/core';
+
+computePrimaryRole(['user', 'admin']); // 'admin'
+computePrimaryRole([]); // 'guest'
+getEffectiveLevel(['user', 'manager']); // 3
+
+// Or format the whole set
+import { formatUserRoles } from '@classic-homes/auth/core';
+formatUserRoles(user); // 'Manager, Agent'
+formatUserRoles(user, { max: 1 }); // 'Manager +1 more'
+```
+
+### Managing another user's roles
+
+Requires `users:read` to list and `users:update` to change:
+
+```typescript
+import { authApi } from '@classic-homes/auth/core';
+
+const { roles, primaryRole } = await authApi.getUserRoles(userId);
+
+await authApi.grantUserRole(userId, 'agent'); // idempotent
+await authApi.revokeUserRole(userId, 'agent');
+await authApi.setUserRoles(userId, ['manager', 'agent']); // replaces the set
+```
+
+Two server rules to design around:
+
+- **A role change doesn't affect that user's live session.** Permissions are
+  computed when a token is minted, so a grant takes effect on their next token
+  refresh — not their next request.
+- The server refuses to remove a user's **last** role, or to grant a role at or
+  above the acting user's own level. Both come back as errors.
+
 ## API Reference
 
 ### Core Exports
@@ -231,8 +299,20 @@ import {
   isTokenExpired,
   getTokenRemainingTime,
 
+  // Roles
+  ROLE_NAMES,
+  ROLE_HIERARCHY,
+  getUserRoles,
+  computePrimaryRole,
+  getEffectiveLevel,
+  hasRole,
+  hasAnyRole,
+  hasAllRoles,
+
   // Types
   type User,
+  type UserRolesResponse,
+  type RoleName,
   type AuthState,
   type LoginCredentials,
   type LoginResponse,
@@ -648,7 +728,7 @@ import {
 } from '@classic-homes/auth/testing';
 
 // Use pre-defined users
-expect(mockUser.role).toBe('user');
+expect(mockUser.roles).toEqual(['user']);
 expect(mockAdminUser.permissions).toContain('manage:system');
 
 // Create custom users

package/dist/auth.svelte-J62VV4TA.js

@@ -0,0 +1,3 @@
+export { authActions, authStore, currentUser, isAuthenticated } from './chunk-QBTMNWJH.js';
+import './chunk-2N2MDCWL.js';
+import './chunk-O47YKG2F.js';

package/dist/{chunk-2QYFVJEM.js → chunk-2N2MDCWL.js}

@@ -1,4 +1,4 @@
-import { getConfig, getStorage, getFetch, isValidRedirectUrl } from './chunk-6NTZVDLW.js';
+import { getConfig, getStorage, getFetch, isValidRedirectUrl } from './chunk-O47YKG2F.js';
 
 // src/core/client.ts
 var isRefreshing = false;
@@ -71,7 +71,7 @@ function updateStoredTokens(accessToken, refreshToken) {
   parsed.accessToken = accessToken;
   parsed.refreshToken = refreshToken;
   storage.setItem(storageKey, JSON.stringify(parsed));
-  import('./auth.svelte-WPCYPHEE.js').then(({ authStore }) => {
+  import('./auth.svelte-J62VV4TA.js').then(({ authStore }) => {
     authStore.updateTokens(accessToken, refreshToken);
   }).catch(() => {
   });
@@ -728,6 +728,75 @@ var authApi = {
     if (params?.type) queryParams.append("type", params.type);
     const response = await api.get(`/auth/security/events?${queryParams.toString()}`, true, customFetch);
     return extractData(response);
+  },
+  // ============================================================================
+  // User Roles
+  // ============================================================================
+  //
+  // Managing another user's roles. Requires `users:read` to list and
+  // `users:update` to change.
+  //
+  // Two server rules worth designing around rather than discovering:
+  //  - A role change does NOT affect that user's live session. Permissions are
+  //    computed when a token is minted, so the grant takes effect on their next
+  //    token refresh — not on their next request.
+  //  - The server refuses a change that would remove a user's last role, or
+  //    that would grant a role at or above the acting user's own level. Both
+  //    come back as errors, so surface them rather than assuming success.
+  /**
+   * List a user's roles.
+   *
+   * @example
+   * ```typescript
+   * const { roles, primaryRole } = await authApi.getUserRoles(userId);
+   * ```
+   */
+  async getUserRoles(userId, customFetch) {
+    const response = await api.get(
+      `/users/${userId}/roles`,
+      true,
+      customFetch
+    );
+    return extractData(response);
+  },
+  /**
+   * Grant a role to a user. Idempotent — granting a role they already hold
+   * succeeds and returns the unchanged set.
+   *
+   * @returns The user's full role set after the grant.
+   */
+  async grantUserRole(userId, role) {
+    const response = await api.put(
+      `/users/${userId}/roles/${role}`,
+      {},
+      true
+    );
+    return extractData(response);
+  },
+  /**
+   * Revoke a role from a user.
+   *
+   * Rejected by the server if it would leave the user with no roles.
+   *
+   * @returns The user's full role set after the revoke.
+   */
+  async revokeUserRole(userId, role) {
+    const response = await api.delete(
+      `/users/${userId}/roles/${role}`,
+      true
+    );
+    return extractData(response);
+  },
+  /**
+   * Replace a user's entire role set.
+   *
+   * Roles absent from `roles` are revoked, so read-modify-write against
+   * {@link getUserRoles} rather than passing a set built from stale state.
+   * Use {@link grantUserRole} / {@link revokeUserRole} for additive changes.
+   */
+  async setUserRoles(userId, roles) {
+    const response = await api.put(`/users/${userId}`, { roles }, true);
+    return extractData(response);
   }
 };
 

package/dist/{chunk-UG4GSPGL.js → chunk-ILRNO4WH.js}

@@ -1,6 +1,6 @@
-import { authService } from './chunk-MPPV5S7S.js';
-import { authStore, currentUser, isAuthenticated, authActions } from './chunk-CPFM7JEI.js';
-import { isInitialized, initAuth } from './chunk-6NTZVDLW.js';
+import { authService } from './chunk-VVREZ25E.js';
+import { authStore, currentUser, isAuthenticated, authActions } from './chunk-QBTMNWJH.js';
+import { isInitialized, initAuth, getUserRoles } from './chunk-O47YKG2F.js';
 
 // src/svelte/guards/auth-guard.ts
 function checkAuth(options = {}) {
@@ -88,11 +88,13 @@ function filterByAccess(items, user, options = {}) {
   const {
     requireAllRoles = false,
     requireAllPermissions = false,
-    hideUnrestrictedForGuests = false
+    hideUnrestrictedForGuests = false,
+    childrenKey,
+    pruneEmptyParents = true
   } = options;
-  const userRoles = user?.roles || (user?.role ? [user.role] : []);
+  const userRoles = getUserRoles(user);
   const userPerms = user?.permissions || [];
-  return items.filter((item) => {
+  function isVisible(item) {
     const hasRoleRestriction = item.roles && item.roles.length > 0;
     const hasPermRestriction = item.permissions && item.permissions.length > 0;
     if (!hasRoleRestriction && !hasPermRestriction) {
@@ -117,7 +119,28 @@ function filterByAccess(items, user, options = {}) {
       }
     }
     return true;
-  });
+  }
+  function filterLevel(level) {
+    const visible = level.filter(isVisible);
+    if (!childrenKey) {
+      return visible;
+    }
+    const result = [];
+    for (const item of visible) {
+      const children = item[childrenKey];
+      if (!Array.isArray(children)) {
+        result.push(item);
+        continue;
+      }
+      const filteredChildren = filterLevel(children);
+      if (pruneEmptyParents && children.length > 0 && filteredChildren.length === 0 && !item.href) {
+        continue;
+      }
+      result.push({ ...item, [childrenKey]: filteredChildren });
+    }
+    return result;
+  }
+  return filterLevel(items);
 }
 function filterNavSections(sections, user, options = {}) {
   return sections.map((section) => ({

package/dist/{chunk-6NTZVDLW.js → chunk-O47YKG2F.js}

@@ -151,4 +151,60 @@ function extractClaims(token, claims) {
   return result;
 }
 
-export { createMemoryStorage, createSessionStorage, decodeJWT, extractClaims, getConfig, getDefaultStorage, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, initAuth, isInitialized, isTokenExpired, isValidRedirectUrl, resetConfig };
+// src/core/roles.ts
+var ROLE_NAMES = [
+  "admin",
+  "manager",
+  "agent",
+  "builder",
+  "customer_service",
+  "demo",
+  "user",
+  "vendor",
+  "customer",
+  "subcontractor",
+  "guest"
+];
+var ROLE_HIERARCHY = {
+  guest: 0,
+  user: 1,
+  vendor: 1,
+  customer: 1,
+  subcontractor: 1,
+  agent: 2,
+  builder: 2,
+  customer_service: 2,
+  demo: 2,
+  manager: 3,
+  admin: 4
+};
+function getUserRoles(user) {
+  return user?.roles ?? [];
+}
+function computePrimaryRole(roles) {
+  const held = new Set(roles);
+  for (const role of ROLE_NAMES) {
+    if (held.has(role)) return role;
+  }
+  return "guest";
+}
+function getEffectiveLevel(roles) {
+  let max = 0;
+  for (const role of roles) {
+    max = Math.max(max, ROLE_HIERARCHY[role] ?? 0);
+  }
+  return max;
+}
+function hasRole(user, role) {
+  return getUserRoles(user).includes(role);
+}
+function hasAnyRole(user, roles) {
+  const held = getUserRoles(user);
+  return roles.some((role) => held.includes(role));
+}
+function hasAllRoles(user, roles) {
+  const held = getUserRoles(user);
+  return roles.every((role) => held.includes(role));
+}
+
+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, resetConfig };

package/dist/{chunk-CPFM7JEI.js → chunk-QBTMNWJH.js}

@@ -1,7 +1,8 @@
-import { authApi } from './chunk-2QYFVJEM.js';
-import { decodeJWT, isInitialized, getConfig, getStorage, getDefaultStorage } from './chunk-6NTZVDLW.js';
+import { authApi } from './chunk-2N2MDCWL.js';
+import { isInitialized, getConfig, hasRole, hasAnyRole, hasAllRoles, decodeJWT, getStorage, getDefaultStorage } from './chunk-O47YKG2F.js';
 
 // src/svelte/stores/auth.svelte.ts
+var STORAGE_VERSION = 2;
 function getStorageKey() {
   return isInitialized() ? getConfig().storageKey ?? "classic_auth" : "classic_auth";
 }
@@ -11,32 +12,37 @@ function getSessionTokenKey() {
 function getStorageAdapter() {
   return isInitialized() ? getStorage() : getDefaultStorage();
 }
+function emptyAuthState() {
+  return {
+    accessToken: null,
+    refreshToken: null,
+    user: null,
+    isAuthenticated: false
+  };
+}
 function loadAuthFromStorage() {
   try {
     const storage = getStorageAdapter();
     const data = storage.getItem(getStorageKey());
     if (!data) {
-      return {
-        accessToken: null,
-        refreshToken: null,
-        user: null,
-        isAuthenticated: false
-      };
+      return emptyAuthState();
     }
     const parsed = JSON.parse(data);
+    if (parsed.version !== STORAGE_VERSION) {
+      storage.removeItem(getStorageKey());
+      return emptyAuthState();
+    }
+    const accessToken = parsed.accessToken ?? null;
     return {
-      accessToken: parsed.accessToken ?? null,
+      accessToken,
       refreshToken: parsed.refreshToken ?? null,
-      user: parsed.user ?? null,
-      isAuthenticated: !!parsed.accessToken && !!parsed.user
+      // Normalize on read as well as write: a payload can be stale, hand-written,
+      // or predate a field, and every role predicate downstream reads `roles`.
+      user: parsed.user ? normalizeUser(parsed.user, accessToken) : null,
+      isAuthenticated: !!accessToken && !!parsed.user
     };
   } catch {
-    return {
-      accessToken: null,
-      refreshToken: null,
-      user: null,
-      isAuthenticated: false
-    };
+    return emptyAuthState();
   }
 }
 function saveAuthToStorage(state) {
@@ -46,11 +52,22 @@ function saveAuthToStorage(state) {
     if (!state.accessToken) {
       storage.removeItem(key);
     } else {
-      storage.setItem(key, JSON.stringify(state));
+      storage.setItem(key, JSON.stringify({ ...state, version: STORAGE_VERSION }));
     }
   } catch {
   }
 }
+function normalizeUser(user, accessToken) {
+  const jwtPayload = accessToken ? decodeJWT(accessToken) : null;
+  return {
+    ...user,
+    roles: firstNonEmpty(jwtPayload?.roles, user.roles),
+    permissions: firstNonEmpty(jwtPayload?.permissions, user.permissions)
+  };
+}
+function firstNonEmpty(...candidates) {
+  return candidates.find((candidate) => candidate && candidate.length > 0) ?? [];
+}
 var AuthStore = class {
   constructor() {
     this.subscribers = /* @__PURE__ */ new Set();
@@ -90,12 +107,7 @@ var AuthStore = class {
    * Set auth data after successful login.
    */
   setAuth(accessToken, refreshToken, user, sessionToken) {
-    const jwtPayload = decodeJWT(accessToken);
-    const userWithPermissions = {
-      ...user,
-      permissions: user.permissions || jwtPayload?.permissions || [],
-      roles: user.roles || jwtPayload?.roles || (user.role ? [user.role] : [])
-    };
+    const userWithPermissions = normalizeUser(user, accessToken);
     this.state = {
       accessToken,
       refreshToken,
@@ -119,12 +131,7 @@ var AuthStore = class {
    * Update tokens (e.g., after refresh).
    */
   updateTokens(accessToken, refreshToken) {
-    const jwtPayload = decodeJWT(accessToken);
-    const updatedUser = this.state.user ? {
-      ...this.state.user,
-      permissions: jwtPayload?.permissions || this.state.user.permissions || [],
-      roles: jwtPayload?.roles || this.state.user.roles || (this.state.user.role ? [this.state.user.role] : [])
-    } : null;
+    const updatedUser = this.state.user ? normalizeUser(this.state.user, accessToken) : null;
     this.state = {
       ...this.state,
       accessToken,
@@ -141,12 +148,7 @@ var AuthStore = class {
    * Update user data (e.g., after profile update).
    */
   updateUser(user) {
-    const jwtPayload = this.state.accessToken ? decodeJWT(this.state.accessToken) : null;
-    const updatedUser = {
-      ...user,
-      permissions: user.permissions || jwtPayload?.permissions || [],
-      roles: user.roles || jwtPayload?.roles || (user.role ? [user.role] : [])
-    };
+    const updatedUser = normalizeUser(user, this.state.accessToken);
     this.state = {
       ...this.state,
       user: updatedUser
@@ -235,22 +237,24 @@ var AuthStore = class {
     return this.state.user?.permissions?.includes(permission) ?? false;
   }
   /**
-   * Check if user has a specific role.
+   * Check if the user holds a specific role.
+   *
+   * Exact membership — holding `admin` does not imply `agent`.
    */
   hasRole(role) {
-    return this.state.user?.roles?.includes(role) ?? false;
+    return hasRole(this.state.user, role);
   }
   /**
-   * Check if user has any of the specified roles.
+   * Check if the user holds any of the specified roles.
    */
   hasAnyRole(roles) {
-    return roles.some((role) => this.state.user?.roles?.includes(role)) ?? false;
+    return hasAnyRole(this.state.user, roles);
   }
   /**
-   * Check if user has all of the specified roles.
+   * Check if the user holds all of the specified roles.
    */
   hasAllRoles(roles) {
-    return roles.every((role) => this.state.user?.roles?.includes(role)) ?? false;
+    return hasAllRoles(this.state.user, roles);
   }
   /**
    * Check if user has any of the specified permissions.

package/dist/{chunk-MPPV5S7S.js → chunk-VVREZ25E.js}

@@ -1,4 +1,5 @@
-import { authApi } from './chunk-2QYFVJEM.js';
+import { authApi } from './chunk-2N2MDCWL.js';
+import { getUserRoles, hasAnyRole } from './chunk-O47YKG2F.js';
 
 // src/core/guards.ts
 function isMfaChallengeResponse(response) {
@@ -17,7 +18,7 @@ function getAvailableMethods(response) {
 // src/core/errors.ts
 var RoleDeniedError = class _RoleDeniedError extends Error {
   constructor(user, requiredRoles, redirectTo) {
-    const userRoles = user.roles?.join(", ") || user.role || "none";
+    const userRoles = getUserRoles(user).join(", ") || "none";
     super(
       `User "${user.username}" does not have required role(s). Has: [${userRoles}], Required: [${requiredRoles.join(", ")}]`
     );
@@ -48,9 +49,7 @@ var AuthService = class {
   async login(credentials, options) {
     const response = await authApi.login(credentials);
     if (options?.allowedRoles?.length && !isMfaChallengeResponse(response)) {
-      const userRoles = response.user.roles || (response.user.role ? [response.user.role] : []);
-      const hasAllowedRole = options.allowedRoles.some((r) => userRoles.includes(r));
-      if (!hasAllowedRole) {
+      if (!hasAnyRole(response.user, options.allowedRoles)) {
         throw new RoleDeniedError(
           response.user,
           options.allowedRoles,
@@ -60,7 +59,7 @@ var AuthService = class {
     }
     if (options?.autoSetAuth !== false && !isMfaChallengeResponse(response)) {
       try {
-        const { authStore } = await import('./auth.svelte-WPCYPHEE.js');
+        const { authStore } = await import('./auth.svelte-J62VV4TA.js');
         authStore.setAuth(
           response.accessToken,
           response.refreshToken,
@@ -234,9 +233,7 @@ var AuthService = class {
   async verifyMFAChallenge(data, options) {
     const response = await authApi.verifyMFAChallenge(data);
     if (options?.allowedRoles?.length) {
-      const userRoles = response.user.roles || (response.user.role ? [response.user.role] : []);
-      const hasAllowedRole = options.allowedRoles.some((r) => userRoles.includes(r));
-      if (!hasAllowedRole) {
+      if (!hasAnyRole(response.user, options.allowedRoles)) {
         throw new RoleDeniedError(
           response.user,
           options.allowedRoles,
@@ -246,7 +243,7 @@ var AuthService = class {
     }
     if (options?.autoSetAuth !== false) {
       try {
-        const { authStore } = await import('./auth.svelte-WPCYPHEE.js');
+        const { authStore } = await import('./auth.svelte-J62VV4TA.js');
         authStore.setAuth(
           response.accessToken,
           response.refreshToken,
@@ -392,7 +389,7 @@ function getGreeting(user, includeTime = true) {
 function formatUserRoles(user, options = {}) {
   if (!user) return "";
   const { max, separator = ", ", lowercase = false, capitalize = true } = options;
-  const roles = user.roles || (user.role ? [user.role] : []);
+  const roles = getUserRoles(user);
   if (roles.length === 0) return "";
   const formatRole = (role) => {
     if (lowercase) return role.toLowerCase();

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
-import { e as LoginCredentials, f as LoginResponse, g as LogoutResponse, R as RegisterData, k as RegisterResponse, U as User, j as ProfileUpdateData, C as ChangePasswordData, n as Session, A as ApiKey, c as CreateApiKeyRequest, d as CreateApiKeyResponse, i as MFAStatus, h as MFASetupResponse, M as MFAChallengeData, D as Device, p as UserPreferences, L as LinkedAccount, m as SecurityEvent, P as Pagination } from '../types-Di6SR1q5.js';
-export { a as AuthConfig, b as AuthState, l as ResetPasswordData, S as SSOConfig, o as StorageAdapter, q as createMemoryStorage, r as createSessionStorage, s as getConfig, t as getDefaultStorage, u as getFetch, v as getStorage, w as initAuth, x as isInitialized, y as resetConfig } from '../types-Di6SR1q5.js';
-export { A as AuthService, L as LoginOptions, M as MFAVerifyOptions, R as RoleDeniedError, a as authService, f as formatUserRoles, g as getAvatarFallback, b as getDisplayName, c as getGreeting, d as getUserEmail, e as getUserInitials, i as isRoleDeniedError } from '../user-utils-C-JbXqbj.js';
+import { e as LoginCredentials, f as LoginResponse, g as LogoutResponse, R as RegisterData, k as RegisterResponse, U as User, j as ProfileUpdateData, C as ChangePasswordData, n as Session, A as ApiKey, c as CreateApiKeyRequest, d as CreateApiKeyResponse, i as MFAStatus, h as MFASetupResponse, M as MFAChallengeData, D as Device, p as UserPreferences, L as LinkedAccount, m as SecurityEvent, P as Pagination, q as UserRolesResponse } from '../types-DXLdCdNC.js';
+export { a as AuthConfig, b as AuthState, l as ResetPasswordData, S as SSOConfig, o as StorageAdapter, r as createMemoryStorage, s as createSessionStorage, t as getConfig, u as getDefaultStorage, v as getFetch, w as getStorage, x as initAuth, y as isInitialized, z as resetConfig } from '../types-DXLdCdNC.js';
+export { A as AuthService, L as LoginOptions, M as MFAVerifyOptions, R as RoleDeniedError, a as authService, f as formatUserRoles, g as getAvatarFallback, b as getDisplayName, c as getGreeting, d as getUserEmail, e as getUserInitials, i as isRoleDeniedError } from '../user-utils-mQMLo7Il.js';
 
 /**
  * HTTP Client
@@ -284,6 +284,38 @@ declare const authApi: {
         events: SecurityEvent[];
         pagination: Pagination;
     }>;
+    /**
+     * List a user's roles.
+     *
+     * @example
+     * ```typescript
+     * const { roles, primaryRole } = await authApi.getUserRoles(userId);
+     * ```
+     */
+    getUserRoles(userId: string, customFetch?: typeof fetch): Promise<UserRolesResponse>;
+    /**
+     * Grant a role to a user. Idempotent — granting a role they already hold
+     * succeeds and returns the unchanged set.
+     *
+     * @returns The user's full role set after the grant.
+     */
+    grantUserRole(userId: string, role: string): Promise<UserRolesResponse>;
+    /**
+     * Revoke a role from a user.
+     *
+     * Rejected by the server if it would leave the user with no roles.
+     *
+     * @returns The user's full role set after the revoke.
+     */
+    revokeUserRole(userId: string, role: string): Promise<UserRolesResponse>;
+    /**
+     * Replace a user's entire role set.
+     *
+     * Roles absent from `roles` are revoked, so read-modify-write against
+     * {@link getUserRoles} rather than passing a set built from stale state.
+     * Use {@link grantUserRole} / {@link revokeUserRole} for additive changes.
+     */
+    setUserRoles(userId: string, roles: string[]): Promise<User>;
 };
 
 /**
@@ -413,4 +445,111 @@ declare function getTokenExpiration(token: string): Date | null;
  */
 declare function extractClaims<T extends string>(token: string, claims: T[]): Pick<JWTPayload, T> | null;
 
-export { ApiKey, type ApiRequestOptions, type ApiResponse, ChangePasswordData, CreateApiKeyRequest, CreateApiKeyResponse, Device, type JWTPayload, LinkedAccount, LoginCredentials, LoginResponse, LogoutResponse, MFAChallengeData, MFASetupResponse, MFAStatus, Pagination, ProfileUpdateData, RegisterData, RegisterResponse, SecurityEvent, Session, User, UserPreferences, api, apiRequest, authApi, clearStoredAuth, decodeJWT, extractClaims, extractData, getAccessToken, getAvailableMethods, getMfaToken, getRefreshToken, getSessionToken, getTokenExpiration, getTokenRemainingTime, isLoginSuccessResponse, isMfaChallengeResponse, isTokenExpired, updateStoredTokens };
+/**
+ * Role Utilities
+ *
+ * A user holds a set of roles. Their effective permissions are the UNION of
+ * every role's permissions and their effective level is the MAX tier across
+ * them — the server computes both and bakes the result into the JWT.
+ *
+ * This module mirrors the role *taxonomy* from the API
+ * (`chapi/src/config/roles.ts`, `chapi/src/lib/users/roles.ts`). It deliberately
+ * does NOT mirror the permission definitions: `permissions` arrives pre-computed
+ * on the token, so duplicating the role→permission mapping here would only give
+ * it a second place to drift.
+ *
+ * SECURITY: everything here is for UI decisions only. Authorization is enforced
+ * server-side; a client-side role check is a hint, not a gate.
+ */
+
+/**
+ * Every role name, ordered from most to least privileged.
+ *
+ * Order is load-bearing: {@link computePrimaryRole} walks this list and takes
+ * the first match, which is what makes the result deterministic when several
+ * roles share a tier (e.g. `agent` + `builder`).
+ *
+ * Mirrors `ROLE_NAMES` in the API. `builder`/`customer_service`/`demo` are
+ * staff-tier clones of `agent`; `vendor`/`customer`/`subcontractor` are clones
+ * of `user`, row-scoped to their own homes.
+ */
+declare const ROLE_NAMES: readonly ["admin", "manager", "agent", "builder", "customer_service", "demo", "user", "vendor", "customer", "subcontractor", "guest"];
+/**
+ * A known role name.
+ *
+ * Note that role-carrying values stay `string` at API boundaries — the server
+ * can add a role before this package ships a matching release, and an unknown
+ * role must degrade (contribute no permissions, level 0) rather than break
+ * decoding. This type is for authoring ergonomics, not runtime validation.
+ */
+type RoleName = (typeof ROLE_NAMES)[number];
+/**
+ * Privilege level per role. Higher wins. Mirrors `ROLE_HIERARCHY` in the API.
+ *
+ * Used only to derive a display-facing primary role and effective level —
+ * never to imply one role from another. See {@link computePrimaryRole}.
+ */
+declare const ROLE_HIERARCHY: Record<string, number>;
+/**
+ * Read a user's role set.
+ *
+ * The single place that normalizes roles off a user object, so callers never
+ * have to care whether the field is absent (e.g. a hand-built object, or a
+ * response shape that predates multi-role support).
+ *
+ * @example
+ * ```typescript
+ * const roles = getUserRoles(user); // ['manager', 'agent']
+ * ```
+ */
+declare function getUserRoles(user: Pick<User, 'roles'> | null | undefined): string[];
+/**
+ * The highest-tier role a user holds, for display.
+ *
+ * Resolved by {@link ROLE_NAMES} order rather than by comparing levels, so ties
+ * within a tier resolve deterministically and identically to the server.
+ * Returns `guest` when the set is empty or holds only unrecognized roles.
+ *
+ * This is a label, not a capability — a user's actual access is the union of
+ * all their roles, which is strictly broader than their primary role alone.
+ * Never gate on this; use {@link hasRole} or the store's role predicates.
+ *
+ * @example
+ * ```typescript
+ * computePrimaryRole(['user', 'admin']);   // 'admin'
+ * computePrimaryRole(['agent', 'builder']); // 'agent' — ROLE_NAMES order breaks the tie
+ * computePrimaryRole([]);                   // 'guest'
+ * ```
+ */
+declare function computePrimaryRole(roles: readonly string[]): RoleName;
+/**
+ * Effective privilege level — the MAX across all roles held.
+ * Unrecognized roles contribute 0.
+ *
+ * @example
+ * ```typescript
+ * getEffectiveLevel(['user', 'manager']); // 3
+ * getEffectiveLevel([]);                  // 0
+ * ```
+ */
+declare function getEffectiveLevel(roles: readonly string[]): number;
+/**
+ * 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.
+ */
+declare function hasRole(user: Pick<User, 'roles'> | null | undefined, 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;
+/**
+ * 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;
+
+export { ApiKey, type ApiRequestOptions, type ApiResponse, ChangePasswordData, CreateApiKeyRequest, CreateApiKeyResponse, Device, type JWTPayload, LinkedAccount, LoginCredentials, LoginResponse, LogoutResponse, MFAChallengeData, MFASetupResponse, MFAStatus, Pagination, ProfileUpdateData, ROLE_HIERARCHY, ROLE_NAMES, RegisterData, RegisterResponse, type RoleName, SecurityEvent, Session, User, UserPreferences, UserRolesResponse, api, apiRequest, authApi, clearStoredAuth, computePrimaryRole, decodeJWT, extractClaims, extractData, getAccessToken, getAvailableMethods, getEffectiveLevel, getMfaToken, getRefreshToken, getSessionToken, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, isLoginSuccessResponse, isMfaChallengeResponse, isTokenExpired, updateStoredTokens };

package/dist/core/index.js

@@ -1,3 +1,3 @@
-export { AuthService, RoleDeniedError, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse, isRoleDeniedError } from '../chunk-MPPV5S7S.js';
-export { api, apiRequest, authApi, clearStoredAuth, extractData, getAccessToken, getRefreshToken, getSessionToken, updateStoredTokens } from '../chunk-2QYFVJEM.js';
-export { createMemoryStorage, createSessionStorage, decodeJWT, extractClaims, getConfig, getDefaultStorage, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, initAuth, isInitialized, isTokenExpired, resetConfig } from '../chunk-6NTZVDLW.js';
+export { AuthService, RoleDeniedError, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse, isRoleDeniedError } from '../chunk-VVREZ25E.js';
+export { api, apiRequest, authApi, clearStoredAuth, extractData, getAccessToken, getRefreshToken, getSessionToken, updateStoredTokens } from '../chunk-2N2MDCWL.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-O47YKG2F.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 MFASetupResponse, i as MFAStatus, P as Pagination, j as ProfileUpdateData, R as RegisterData, k as RegisterResponse, l as ResetPasswordData, S as SSOConfig, m as SecurityEvent, n as Session, o as StorageAdapter, U as User, p as UserPreferences, q as createMemoryStorage, r as createSessionStorage, s as getConfig, t as getDefaultStorage, u as getFetch, v as getStorage, w as initAuth, x as isInitialized, y as resetConfig } from './types-Di6SR1q5.js';
-export { ApiRequestOptions, ApiResponse, JWTPayload, api, apiRequest, authApi, clearStoredAuth, decodeJWT, extractClaims, extractData, getAccessToken, getAvailableMethods, getMfaToken, getRefreshToken, getSessionToken, getTokenExpiration, getTokenRemainingTime, isLoginSuccessResponse, isMfaChallengeResponse, isTokenExpired, updateStoredTokens } from './core/index.js';
-export { A as AuthService, L as LoginOptions, M as MFAVerifyOptions, R as RoleDeniedError, a as authService, f as formatUserRoles, g as getAvatarFallback, b as getDisplayName, c as getGreeting, d as getUserEmail, e as getUserInitials, i as isRoleDeniedError } from './user-utils-C-JbXqbj.js';
+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 MFASetupResponse, i as MFAStatus, P as Pagination, j as ProfileUpdateData, R as RegisterData, k as RegisterResponse, l as ResetPasswordData, S as SSOConfig, m as SecurityEvent, n as Session, o as StorageAdapter, U as User, p as UserPreferences, q as UserRolesResponse, r as createMemoryStorage, s as createSessionStorage, t as getConfig, u as getDefaultStorage, v as getFetch, w as getStorage, x as initAuth, y as isInitialized, z as resetConfig } from './types-DXLdCdNC.js';
+export { ApiRequestOptions, ApiResponse, JWTPayload, ROLE_HIERARCHY, ROLE_NAMES, RoleName, api, apiRequest, authApi, clearStoredAuth, computePrimaryRole, decodeJWT, extractClaims, extractData, getAccessToken, getAvailableMethods, getEffectiveLevel, getMfaToken, getRefreshToken, getSessionToken, getTokenExpiration, getTokenRemainingTime, getUserRoles, hasAllRoles, hasAnyRole, hasRole, isLoginSuccessResponse, isMfaChallengeResponse, isTokenExpired, updateStoredTokens } from './core/index.js';
+export { A as AuthService, L as LoginOptions, M as MFAVerifyOptions, R as RoleDeniedError, a as authService, f as formatUserRoles, g as getAvatarFallback, b as getDisplayName, c as getGreeting, d as getUserEmail, e as getUserInitials, i as isRoleDeniedError } from './user-utils-mQMLo7Il.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-UG4GSPGL.js';
-export { AuthService, RoleDeniedError, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse, isRoleDeniedError } from './chunk-MPPV5S7S.js';
-export { authActions, authStore, currentUser, isAuthenticated } from './chunk-CPFM7JEI.js';
-export { api, apiRequest, authApi, clearStoredAuth, extractData, getAccessToken, getRefreshToken, getSessionToken, updateStoredTokens } from './chunk-2QYFVJEM.js';
-export { createMemoryStorage, createSessionStorage, decodeJWT, extractClaims, getConfig, getDefaultStorage, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, initAuth, isInitialized, isTokenExpired, resetConfig } from './chunk-6NTZVDLW.js';
+export { canAccess, checkAuth, createAuthClient, createAuthGuard, createAuthHook, createNavFilter, filterByAccess, filterNavSections, matchesRoute, protectedLoad, requireAuth, requirePermission, requireRole, routePatterns } from './chunk-ILRNO4WH.js';
+export { AuthService, RoleDeniedError, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse, isRoleDeniedError } from './chunk-VVREZ25E.js';
+export { authActions, authStore, currentUser, isAuthenticated } from './chunk-QBTMNWJH.js';
+export { api, apiRequest, authApi, clearStoredAuth, extractData, getAccessToken, getRefreshToken, getSessionToken, updateStoredTokens } from './chunk-2N2MDCWL.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-O47YKG2F.js';

package/dist/svelte/index.d.ts

@@ -1,7 +1,7 @@
-import { b as AuthState, U as User, a as AuthConfig } from '../types-Di6SR1q5.js';
-export { w as initAuth, x as isInitialized } from '../types-Di6SR1q5.js';
-import { a as authService } from '../user-utils-C-JbXqbj.js';
-export { R as RoleDeniedError, f as formatUserRoles, g as getAvatarFallback, b as getDisplayName, c as getGreeting, d as getUserEmail, e as getUserInitials, i as isRoleDeniedError } from '../user-utils-C-JbXqbj.js';
+import { b as AuthState, U as User, a as AuthConfig } from '../types-DXLdCdNC.js';
+export { x as initAuth, y as isInitialized } from '../types-DXLdCdNC.js';
+import { a as authService } from '../user-utils-mQMLo7Il.js';
+export { R as RoleDeniedError, f as formatUserRoles, g as getAvatarFallback, b as getDisplayName, c as getGreeting, d as getUserEmail, e as getUserInitials, i as isRoleDeniedError } from '../user-utils-mQMLo7Il.js';
 
 /**
  * Auth Store
@@ -69,15 +69,17 @@ declare class AuthStore {
      */
     hasPermission(permission: string): boolean;
     /**
-     * Check if user has a specific role.
+     * Check if the user holds a specific role.
+     *
+     * Exact membership — holding `admin` does not imply `agent`.
      */
     hasRole(role: string): boolean;
     /**
-     * Check if user has any of the specified roles.
+     * Check if the user holds any of the specified roles.
      */
     hasAnyRole(roles: string[]): boolean;
     /**
-     * Check if user has all of the specified roles.
+     * Check if the user holds all of the specified roles.
      */
     hasAllRoles(roles: string[]): boolean;
     /**
@@ -379,6 +381,13 @@ declare function createAuthClient(options: CreateAuthClientOptions): AuthClient;
 interface RoleRestrictedItem {
     /** Optional item identifier */
     id?: string;
+    /**
+     * Where this item navigates to, if anywhere.
+     *
+     * Only consulted when pruning empty parents: an item with an `href` survives
+     * losing all its children, since it remains a destination in its own right.
+     */
+    href?: string;
     /**
      * Roles that can see this item.
      * By default, user needs ANY of these roles (use requireAllRoles for ALL).
@@ -411,6 +420,27 @@ interface NavFilterOptions {
      * If false (default), items without restrictions are visible to everyone.
      */
     hideUnrestrictedForGuests?: boolean;
+    /**
+     * Property holding nested child items (e.g. 'children' for submenus).
+     *
+     * Set this for tree-shaped navigation. Without it, filtering is flat: a
+     * restricted child under an unrestricted parent stays visible, because
+     * nothing ever looks inside the parent.
+     *
+     * @example
+     * ```typescript
+     * filterByAccess(navItems, user, { childrenKey: 'children' });
+     * ```
+     */
+    childrenKey?: string;
+    /**
+     * If true, a parent whose children are all filtered away is dropped too.
+     *
+     * Only applies to items that had children to begin with, and only when they
+     * are pure containers — an item with its own `href` stays, since it is still
+     * navigable on its own. Requires `childrenKey`. Default: true.
+     */
+    pruneEmptyParents?: boolean;
 }
 /**
  * Filter navigation items based on user roles and permissions.
@@ -431,6 +461,12 @@ interface NavFilterOptions {
  * const filtered = filterByAccess(navItems, user);
  * // Returns items the user can see based on their roles/permissions
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Tree-shaped navigation — without childrenKey, nested items are NOT filtered
+ * const filtered = filterByAccess(navItems, user, { childrenKey: 'children' });
+ * ```
  */
 declare function filterByAccess<T extends RoleRestrictedItem>(items: T[], user: User | null, options?: NavFilterOptions): T[];
 /**

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-UG4GSPGL.js';
-export { RoleDeniedError, formatUserRoles, getAvatarFallback, getDisplayName, getGreeting, getUserEmail, getUserInitials, isRoleDeniedError } from '../chunk-MPPV5S7S.js';
-export { authActions, authStore, currentUser, isAuthenticated } from '../chunk-CPFM7JEI.js';
-import '../chunk-2QYFVJEM.js';
-export { initAuth, isInitialized } from '../chunk-6NTZVDLW.js';
+export { canAccess, checkAuth, createAuthClient, createAuthGuard, createAuthHook, createNavFilter, filterByAccess, filterNavSections, matchesRoute, protectedLoad, requireAuth, requirePermission, requireRole, routePatterns } from '../chunk-ILRNO4WH.js';
+export { RoleDeniedError, formatUserRoles, getAvatarFallback, getDisplayName, getGreeting, getUserEmail, getUserInitials, isRoleDeniedError } from '../chunk-VVREZ25E.js';
+export { authActions, authStore, currentUser, isAuthenticated } from '../chunk-QBTMNWJH.js';
+import '../chunk-2N2MDCWL.js';
+export { initAuth, isInitialized } from '../chunk-O47YKG2F.js';

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { U as User, D as Device, f as LoginResponse, m as SecurityEvent, n as Session, A as ApiKey, L as LinkedAccount, g as LogoutResponse, h as MFASetupResponse, i as MFAStatus, k as RegisterResponse, p as UserPreferences, o as StorageAdapter, b as AuthState, a as AuthConfig } from '../types-Di6SR1q5.js';
+import { U as User, D as Device, f as LoginResponse, m as SecurityEvent, n as Session, A as ApiKey, L as LinkedAccount, g as LogoutResponse, h as MFASetupResponse, i as MFAStatus, k as RegisterResponse, p as UserPreferences, o as StorageAdapter, b as AuthState, a as AuthConfig } from '../types-DXLdCdNC.js';
 
 /**
  * User Fixtures
@@ -588,15 +588,18 @@ declare class MockAuthStore {
      */
     hasPermission(permission: string): boolean;
     /**
-     * Check if user has a specific role.
+     * Check if the user holds a specific role.
+     *
+     * Delegates to the same helpers as the real store — a mock that decides
+     * access differently from production is worse than no mock.
      */
     hasRole(role: string): boolean;
     /**
-     * Check if user has any of the specified roles.
+     * Check if the user holds any of the specified roles.
      */
     hasAnyRole(roles: string[]): boolean;
     /**
-     * Check if user has all of the specified roles.
+     * Check if the user holds all of the specified roles.
      */
     hasAllRoles(roles: string[]): boolean;
     /**

package/dist/testing/index.js

@@ -1,4 +1,4 @@
-import { initAuth, resetConfig, isTokenExpired, decodeJWT } from '../chunk-6NTZVDLW.js';
+import { hasRole, hasAnyRole, hasAllRoles, initAuth, resetConfig, getUserRoles, isTokenExpired, decodeJWT } from '../chunk-O47YKG2F.js';
 
 // src/testing/fixtures/users.ts
 var mockUser = {
@@ -8,7 +8,6 @@ var mockUser = {
   firstName: "Test",
   lastName: "User",
   phone: "+1234567890",
-  role: "user",
   roles: ["user"],
   permissions: ["read:profile", "write:profile"],
   isActive: true,
@@ -24,7 +23,6 @@ var mockAdminUser = {
   firstName: "Admin",
   lastName: "User",
   phone: "+1234567891",
-  role: "admin",
   roles: ["admin", "user"],
   permissions: [
     "read:profile",
@@ -48,7 +46,6 @@ var mockSSOUser = {
   email: "sso@example.com",
   firstName: "SSO",
   lastName: "User",
-  role: "user",
   roles: ["user"],
   permissions: ["read:profile", "write:profile"],
   isActive: true,
@@ -64,7 +61,6 @@ var mockMFAUser = {
   email: "mfa@example.com",
   firstName: "MFA",
   lastName: "User",
-  role: "user",
   roles: ["user"],
   permissions: ["read:profile", "write:profile"],
   isActive: true,
@@ -79,7 +75,6 @@ var mockUnverifiedUser = {
   email: "unverified@example.com",
   firstName: "Unverified",
   lastName: "User",
-  role: "user",
   roles: ["user"],
   permissions: [],
   isActive: true,
@@ -93,7 +88,6 @@ var mockInactiveUser = {
   email: "inactive@example.com",
   firstName: "Inactive",
   lastName: "User",
-  role: "user",
   roles: ["user"],
   permissions: [],
   isActive: false,
@@ -110,7 +104,6 @@ function createMockUser(overrides = {}) {
 }
 function createMockUserWithRoles(roles, permissions, overrides = {}) {
   return createMockUser({
-    role: roles[0] ?? "user",
     roles,
     permissions,
     ...overrides
@@ -1279,22 +1272,25 @@ var MockAuthStore = class {
     return this.state.user?.permissions?.includes(permission) ?? false;
   }
   /**
-   * Check if user has a specific role.
+   * Check if the user holds a specific role.
+   *
+   * Delegates to the same helpers as the real store — a mock that decides
+   * access differently from production is worse than no mock.
    */
   hasRole(role) {
-    return this.state.user?.roles?.includes(role) ?? false;
+    return hasRole(this.state.user, role);
   }
   /**
-   * Check if user has any of the specified roles.
+   * Check if the user holds any of the specified roles.
    */
   hasAnyRole(roles) {
-    return roles.some((role) => this.state.user?.roles?.includes(role)) ?? false;
+    return hasAnyRole(this.state.user, roles);
   }
   /**
-   * Check if user has all of the specified roles.
+   * Check if the user holds all of the specified roles.
    */
   hasAllRoles(roles) {
-    return roles.every((role) => this.state.user?.roles?.includes(role)) ?? false;
+    return hasAllRoles(this.state.user, roles);
   }
   /**
    * Check if user has any of the specified permissions.
@@ -1833,13 +1829,15 @@ function assertLacksPermissions(user, permissions, message) {
   }
 }
 function assertHasRoles(user, roles, message) {
-  const missing = roles.filter((r) => !user.roles?.includes(r));
+  const held = getUserRoles(user);
+  const missing = roles.filter((r) => !held.includes(r));
   if (missing.length > 0) {
     throw new Error(message ?? `User missing roles: ${missing.join(", ")}`);
   }
 }
 function assertLacksRoles(user, roles, message) {
-  const present = roles.filter((r) => user.roles?.includes(r));
+  const held = getUserRoles(user);
+  const present = roles.filter((r) => held.includes(r));
   if (present.length > 0) {
     throw new Error(message ?? `User should not have roles: ${present.join(", ")}`);
   }

package/dist/{types-Di6SR1q5.d.ts → types-DXLdCdNC.d.ts}

@@ -149,8 +149,13 @@ interface User {
     firstName?: string;
     lastName?: string;
     phone?: string;
-    role: string;
-    roles?: string[];
+    /**
+     * Every role the user holds. `permissions` is the union across all of them,
+     * so this is broader than any single role — see `computePrimaryRole` in
+     * `./roles.js` if you need one role to display.
+     */
+    roles: string[];
+    /** Union of the permissions granted by every role in `roles`. */
     permissions: string[];
     isActive: boolean;
     emailVerified: boolean;
@@ -159,6 +164,21 @@ interface User {
     createdAt: string;
     lastLoginAt?: string;
 }
+/**
+ * The result of reading or changing a user's roles.
+ */
+interface UserRolesResponse {
+    userId: string;
+    /** The user's full role set after the operation. */
+    roles: string[];
+    /**
+     * The highest-tier role in `roles`, as resolved by the server.
+     *
+     * A display label, not a capability — the user's actual access is the union
+     * of every role in `roles`, which is broader than this one alone.
+     */
+    primaryRole: string;
+}
 interface AuthState {
     accessToken: string | null;
     refreshToken: string | null;
@@ -227,6 +247,10 @@ interface ApiKey {
     description?: string;
     keyPreview: string;
     permissions: string[];
+    /**
+     * The single role this key acts as. Unlike a user — who holds a set of roles
+     * whose permissions are unioned — an API key is scoped to at most one role.
+     */
     role: string | null;
     isActive: boolean;
     expiresAt: string | null;
@@ -347,4 +371,4 @@ interface ResetPasswordData {
     newPassword: string;
 }
 
-export { type ApiKey as A, type ChangePasswordData as C, type Device as D, type LinkedAccount as L, type MFAChallengeData as M, type Pagination as P, type RegisterData as R, type SSOConfig as S, type User as U, type AuthConfig as a, type AuthState as b, type CreateApiKeyRequest as c, type CreateApiKeyResponse as d, type LoginCredentials as e, type LoginResponse as f, type LogoutResponse as g, type MFASetupResponse as h, type MFAStatus as i, type ProfileUpdateData as j, type RegisterResponse as k, type ResetPasswordData as l, type SecurityEvent as m, type Session as n, type StorageAdapter as o, type UserPreferences as p, createMemoryStorage as q, createSessionStorage as r, getConfig as s, getDefaultStorage as t, getFetch as u, getStorage as v, initAuth as w, isInitialized as x, resetConfig as y };
+export { type ApiKey as A, type ChangePasswordData as C, type Device as D, type LinkedAccount as L, type MFAChallengeData as M, type Pagination as P, type RegisterData as R, type SSOConfig as S, type User as U, type AuthConfig as a, type AuthState as b, type CreateApiKeyRequest as c, type CreateApiKeyResponse as d, type LoginCredentials as e, type LoginResponse as f, type LogoutResponse as g, type MFASetupResponse as h, type MFAStatus as i, type ProfileUpdateData as j, type RegisterResponse as k, type ResetPasswordData as l, type SecurityEvent as m, type Session as n, type StorageAdapter as o, type UserPreferences as p, type UserRolesResponse as q, createMemoryStorage as r, createSessionStorage as s, getConfig as t, getDefaultStorage as u, getFetch as v, getStorage as w, initAuth as x, isInitialized as y, resetConfig as z };

package/dist/{user-utils-C-JbXqbj.d.ts → user-utils-mQMLo7Il.d.ts}

@@ -1,4 +1,4 @@
-import { e as LoginCredentials, f as LoginResponse, g as LogoutResponse, R as RegisterData, k as RegisterResponse, U as User, j as ProfileUpdateData, n as Session, A as ApiKey, c as CreateApiKeyRequest, d as CreateApiKeyResponse, i as MFAStatus, h as MFASetupResponse, M as MFAChallengeData, D as Device, p as UserPreferences, L as LinkedAccount, m as SecurityEvent, P as Pagination } from './types-Di6SR1q5.js';
+import { e as LoginCredentials, f as LoginResponse, g as LogoutResponse, R as RegisterData, k as RegisterResponse, U as User, j as ProfileUpdateData, n as Session, A as ApiKey, c as CreateApiKeyRequest, d as CreateApiKeyResponse, i as MFAStatus, h as MFASetupResponse, M as MFAChallengeData, D as Device, p as UserPreferences, L as LinkedAccount, m as SecurityEvent, P as Pagination } from './types-DXLdCdNC.js';
 
 /**
  * Auth Service

package/package.json

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

package/dist/auth.svelte-WPCYPHEE.js

@@ -1,3 +0,0 @@
-export { authActions, authStore, currentUser, isAuthenticated } from './chunk-CPFM7JEI.js';
-import './chunk-2QYFVJEM.js';
-import './chunk-6NTZVDLW.js';