@classic-homes/auth 0.1.55 → 1.0.0

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

@@ -1,4 +1,5 @@
-import { authApi } from './chunk-GRQL5FSH.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-BBLX2MKB.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-BBLX2MKB.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-BRxyphcX.js';
-export { a as AuthConfig, b as AuthState, l as ResetPasswordData, S as SSOConfig, o as StorageAdapter, q as getConfig, r as getDefaultStorage, s as getFetch, t as getStorage, u as initAuth, v as isInitialized, w as resetConfig } from '../types-BRxyphcX.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-BSbNN3Hb.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
@@ -47,9 +47,10 @@ declare function getSessionToken(): string | null;
  * Update stored tokens.
  * Also updates the Svelte auth store if available.
  *
- * Note: The read-modify-write on localStorage is not atomic across tabs.
- * A version counter is used to detect and discard stale writes from other tabs.
- * The `storage` event listener (set up via `initCrossTabSync`) keeps tabs in sync.
+ * Note: The read-modify-write on localStorage is not atomic across tabs —
+ * concurrent refreshes in two tabs are last-write-wins. The `storage` event
+ * listener (set up via `initCrossTabSync`) propagates whichever write landed
+ * last, so tabs converge on the same tokens.
  */
 declare function updateStoredTokens(accessToken: string, refreshToken: string): void;
 /**
@@ -283,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>;
 };
 
 /**
@@ -412,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-TUHQ4FHC.js';
-export { api, apiRequest, authApi, clearStoredAuth, extractData, getAccessToken, getRefreshToken, getSessionToken, updateStoredTokens } from '../chunk-GRQL5FSH.js';
-export { decodeJWT, extractClaims, getConfig, getDefaultStorage, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, initAuth, isInitialized, isTokenExpired, resetConfig } from '../chunk-EM7PUNZB.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 getConfig, r as getDefaultStorage, s as getFetch, t as getStorage, u as initAuth, v as isInitialized, w as resetConfig } from './types-BRxyphcX.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-BSbNN3Hb.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-RKSETJ4V.js';
-export { AuthService, RoleDeniedError, authService, formatUserRoles, getAvailableMethods, getAvatarFallback, getDisplayName, getGreeting, getMfaToken, getUserEmail, getUserInitials, isLoginSuccessResponse, isMfaChallengeResponse, isRoleDeniedError } from './chunk-TUHQ4FHC.js';
-export { authActions, authStore, currentUser, isAuthenticated } from './chunk-BK34CVH5.js';
-export { api, apiRequest, authApi, clearStoredAuth, extractData, getAccessToken, getRefreshToken, getSessionToken, updateStoredTokens } from './chunk-GRQL5FSH.js';
-export { decodeJWT, extractClaims, getConfig, getDefaultStorage, getFetch, getStorage, getTokenExpiration, getTokenRemainingTime, initAuth, isInitialized, isTokenExpired, resetConfig } from './chunk-EM7PUNZB.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-BRxyphcX.js';
-export { u as initAuth, v as isInitialized } from '../types-BRxyphcX.js';
-import { a as authService } from '../user-utils-BSbNN3Hb.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-BSbNN3Hb.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-RKSETJ4V.js';
-export { RoleDeniedError, formatUserRoles, getAvatarFallback, getDisplayName, getGreeting, getUserEmail, getUserInitials, isRoleDeniedError } from '../chunk-TUHQ4FHC.js';
-export { authActions, authStore, currentUser, isAuthenticated } from '../chunk-BK34CVH5.js';
-import '../chunk-GRQL5FSH.js';
-export { initAuth, isInitialized } from '../chunk-EM7PUNZB.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-BRxyphcX.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-EM7PUNZB.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-BRxyphcX.d.ts → types-DXLdCdNC.d.ts}

@@ -105,8 +105,29 @@ declare function resetConfig(): void;
 /**
  * Get the default storage adapter.
  * Returns localStorage in browser, or a no-op adapter in SSR.
+ *
+ * SECURITY NOTE: localStorage persists tokens (including the long-lived
+ * refresh token) where any XSS on the page can read them. It is the default
+ * for cross-tab session continuity, but consider the safer alternatives:
+ * `createSessionStorage()` (per-tab, cleared on close),
+ * `createMemoryStorage()` (never persisted, lost on reload), or an
+ * httpOnly-cookie flow on your backend so tokens never reach JS at all.
+ * Pass the adapter via `initAuth({ storage: ... })`.
  */
 declare function getDefaultStorage(): StorageAdapter;
+/**
+ * Storage adapter backed by sessionStorage: tokens live per-tab and are
+ * cleared when the tab closes. Safer than localStorage against persistent
+ * token theft, at the cost of cross-tab session continuity.
+ * Falls back to no-op in SSR.
+ */
+declare function createSessionStorage(): StorageAdapter;
+/**
+ * In-memory storage adapter: tokens are never persisted and are lost on
+ * page reload (the user re-authenticates or a silent SSO flow restores the
+ * session). The safest JS-side option against token exfiltration.
+ */
+declare function createMemoryStorage(): StorageAdapter;
 /**
  * Get the storage adapter from config or use default.
  */
@@ -128,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;
@@ -138,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;
@@ -174,6 +215,12 @@ interface LogoutResponse {
     message?: string;
     ssoLogout?: boolean;
     logoutUrl?: string;
+    /**
+     * Set when the server-side logout call failed. `success` stays true so
+     * callers clear local state, but the server session may still be alive —
+     * check this to warn the user or retry revocation.
+     */
+    serverError?: string;
 }
 interface RegisterResponse {
     message: string;
@@ -200,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;
@@ -320,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, getConfig as q, getDefaultStorage as r, getFetch as s, getStorage as t, initAuth as u, isInitialized as v, resetConfig as w };
+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-BSbNN3Hb.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-BRxyphcX.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.55",
+  "version": "1.0.0",
   "description": "Authentication services and Svelte bindings for Classic Theme apps",
   "type": "module",
   "main": "dist/index.js",

package/dist/auth.svelte-BBLX2MKB.js

@@ -1,3 +0,0 @@
-export { authActions, authStore, currentUser, isAuthenticated } from './chunk-BK34CVH5.js';
-import './chunk-GRQL5FSH.js';
-import './chunk-EM7PUNZB.js';