@withstudiocms/auth-kit/dist/utils/user.d.ts

Utilities for managing authentication

import { Effect } from '@withstudiocms/effect';
import { type AvailablePermissionRanks, type CombinedUserData, UserPermissionLevel, type UserSessionData } from '../types.js';
/**
 * Verifies that the provided username meets the required length constraints.
 *
 * @param username - The username string to validate.
 * @returns A user error message if the username is not between 3 and 32 characters long, otherwise `undefined`.
 */
export declare const verifyUsernameLength: (username: string) => Effect.Effect<string | undefined, import("../errors.js").UserError, never>;
/**
 * Verifies that the provided username contains only allowed characters.
 *
 * Allowed characters are:
 * - Lowercase letters (`a-z`)
 * - Numbers (`0-9`)
 * - Hyphens (`-`)
 * - Underscores (`_`)
 *
 * @param username - The username string to validate.
 * @returns An error message if the username contains invalid characters, otherwise `undefined`.
 */
export declare const verifyUsernameCharacters: (username: string) => Effect.Effect.AsEffect<Effect.Effect<string | undefined, import("../errors.js").UserError, never>>;
/**
 * Verifies if the provided username is considered unsafe (e.g., commonly used usernames like "admin", "root", etc.).
 *
 * @param username - The username string to be checked for safety.
 * @returns An `Effect` that yields a string with an error message if the username is unsafe,
 *          or `undefined` if the username is safe.
 *
 * @remarks
 * This function uses the `CheckIfUnsafe` service to determine if the username is unsafe.
 * It is intended to prevent the use of common or reserved usernames.
 */
export declare const verifyUsernameSafe: (username: string) => Effect.Effect<string | undefined, import("../errors.js").CheckIfUnsafeError, never>;
/**
 * Returns a default user session wrapped in an Effect.
 *
 * The default session indicates that the user is not logged in,
 * has no user data, and an 'unknown' permission level.
 *
 * @returns {Effect<UserSessionData>} An Effect containing the default UserSessionData.
 */
export declare const getDefaultUserSession: () => Effect.Effect.AsEffect<Effect.Effect<UserSessionData, never, never>>;
/**
 * Determines the user's permission level based on the provided user data.
 *
 * This function checks the `permissionLevel` property if present, otherwise it checks
 * the `permissionsData.rank` property. If neither is available or `userData` is null,
 * it returns `'unknown'`.
 *
 * @param userData - The user session or combined user data object, or null.
 * @returns The user's permission level as an `AvailablePermissionRanks` value, or `'unknown'` if not determinable.
 */
export declare const getLevel: (userData: UserSessionData | CombinedUserData | null) => Effect.Effect<"owner" | "admin" | "editor" | "visitor" | "unknown", import("../errors.js").UserError, never>;
/**
 * Parses the given required permission rank and returns the corresponding `UserPermissionLevel`.
 * If the provided permission rank does not match any known value, it returns `UserPermissionLevel.unknown`.
 *
 * @param requiredPerms - The required permission rank to parse. Should be one of the values defined in `AvailablePermissionRanks`.
 * @returns The corresponding `UserPermissionLevel` for the given permission rank.
 */
export declare const parseRequiredPerms: (requiredPerms: AvailablePermissionRanks) => Effect.Effect<UserPermissionLevel, import("../errors.js").UserError, never>;