lib/auth/user

Variables

LinkNewOAuthCookieName

const LinkNewOAuthCookieName: "link-new-o-auth" = 'link-new-o-auth';

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:132

The name of the cookie used for linking a new OAuth account. This constant is used to identify the specific cookie that handles the linking process for new OAuth accounts.

---

permissionRanksMap

const permissionRanksMap: Record<AvailablePermissionRanks, string[]>;

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:283

A mapping of permission ranks to their respective allowed roles.

This map defines the hierarchy of permissions, where each rank includes all the roles of the ranks below it. For example, an ‘admin’ has the roles of both ‘owner’ and ‘admin’, while an ‘editor’ has the roles of ‘owner’, ‘admin’, and ‘editor’.

Functions

createLocalUser()

function createLocalUser(
   name: string,
   username: string,
   email: string,
   password: string): Promise<{
  avatar: null | string;
  createdAt: null | Date;
  email: null | string;
  emailVerified: boolean;
  id: string;
  name: string;
  notifications: null | string;
  password: null | string;
  updatedAt: null | Date;
  url: null | string;
  username: string;
}>

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:73

Creates a new local user with the provided details.

Parameters

name

string

The full name of the user.

username

string

The username for the user.

email

string

The email address of the user.

password

string

The password for the user.

Returns

Promise<{ avatar: null | string; createdAt: null | Date; email: null | string; emailVerified: boolean; id: string; name: string; notifications: null | string; password: null | string; updatedAt: null | Date; url: null | string; username: string; }>

A promise that resolves to the newly created user record.

---

createOAuthUser()

function createOAuthUser(userFields: {
  avatar: null | string;
  createdAt: null | Date;
  email: null | string;
  emailVerified: boolean;
  id: string;
  name: string;
  notifications: null | string;
  password: null | string;
  updatedAt: null | Date;
  url: null | string;
  username: string;
 }, oAuthFields: {
  provider: string;
  providerUserId: string;
 }): Promise<
  | {
  avatar: null | string;
  createdAt: null | Date;
  email: null | string;
  emailVerified: boolean;
  id: string;
  name: string;
  notifications: null | string;
  password: null | string;
  updatedAt: null | Date;
  url: null | string;
  username: string;
 }
  | {
  error: string;
}>

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:105

Creates a new user with OAuth credentials.

Parameters

userFields

The fields required to create a new user.

avatar?

null | string

createdAt?

null | Date

email?

null | string

emailVerified?

boolean

id?

string

name

string

notifications?

null | string

password?

null | string

updatedAt?

null | Date

url?

null | string

username

string

oAuthFields

The OAuth provider information, including the provider name and provider user ID.

provider

string

providerUserId

string

Returns

Promise< | { avatar: null | string; createdAt: null | Date; email: null | string; emailVerified: boolean; id: string; name: string; notifications: null | string; password: null | string; updatedAt: null | Date; url: null | string; username: string; } | { error: string; }>

The newly created user object or an error object if the creation fails.

---

createUserAvatar()

function createUserAvatar(email: string): Promise<string>

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:49

Creates a user avatar URL based on the provided email.

This function takes an email address, processes it to generate a unique hash, and returns a URL for the user’s avatar using the Libravatar service.

Parameters

email

string

The email address of the user.

Returns

Promise<string>

A promise that resolves to the URL of the user’s avatar.

---

getUserData()

function getUserData(Astro:
  | APIContext<Record<string, any>, Record<string, undefined | string>>
| AstroGlobal<Record<string, any>, AstroComponentFactory, Record<string, undefined | string>>): Promise<UserSessionData>

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:196

Retrieves user session data based on the provided Astro context.

Parameters

Astro

The Astro global object or API context containing cookies.

APIContext<Record<string, any>, Record<string, undefined | string>> | AstroGlobal<Record<string, any>, AstroComponentFactory, Record<string, undefined | string>>

Returns

Promise<UserSessionData>

A promise that resolves to the user session data.

The function performs the following steps:

1. Extracts the session token from cookies.
2. If no session token is found, returns an object indicating the user is not logged in.
3. Validates the session token.
4. If the session is invalid, deletes the session token cookie and returns an object indicating the user is not logged in.
5. If the user is not found, returns an object indicating the user is not logged in.
6. Retrieves the user’s permission level from the database.
7. Returns an object containing the user’s login status, user information, and permission level.

---

getUserFromEmail()

function getUserFromEmail(email: string): Promise<
  | null
  | {
  avatar: null | string;
  createdAt: null | Date;
  email: null | string;
  emailVerified: boolean;
  id: string;
  name: string;
  notifications: null | string;
  password: null | string;
  updatedAt: null | Date;
  url: null | string;
  username: string;
}>

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:177

Retrieves a user from the database based on their email address.

Parameters

email

string

The email address of the user to retrieve.

Returns

Promise< | null | { avatar: null | string; createdAt: null | Date; email: null | string; emailVerified: boolean; id: string; name: string; notifications: null | string; password: null | string; updatedAt: null | Date; url: null | string; username: string; }>

A promise that resolves to the user data if found, or null if no user is found with the given email.

---

getUserPasswordHash()

function getUserPasswordHash(userId: string): Promise<string>

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:157

Retrieves the password hash for a given user by their user ID.

Parameters

userId

string

The unique identifier of the user whose password hash is to be retrieved.

Returns

Promise<string>

A promise that resolves to the password hash of the user.

Throws

Will throw an error if the user is not found or if the user does not have a password.

---

updateUserPassword()

function updateUserPassword(userId: string, password: string): Promise<void>

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:144

Updates the password for a user.

This function hashes the provided password and updates the user’s password in the database with the hashed password.

Parameters

userId

string

The unique identifier of the user whose password is to be updated.

password

string

The new password to be set for the user.

Returns

Promise<void>

A promise that resolves when the password has been successfully updated.

---

verifyUsernameInput()

function verifyUsernameInput(username: string): string | true

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:21

Verifies if the provided username meets the required criteria.

The username must:

• Be between 3 and 32 characters in length.
• Contain only lowercase letters, numbers, hyphens (-), and underscores (_).
• Not be considered unsafe.

Parameters

username

string

The username to verify.

Returns

string | true

true if the username is valid, false otherwise.

---

verifyUserPermissionLevel()

function verifyUserPermissionLevel(userData:
  | CombinedUserData
| UserSessionData, requiredPermission: "unknown" | "visitor" | "editor" | "admin" | "owner"): Promise<boolean>

Defined in: studiocms/packages/studiocms/src/lib/auth/user.ts:298

Verifies if the user’s permission level meets the required permission rank.

Parameters

userData

The session data of the user, which includes their permission level.

CombinedUserData | UserSessionData

requiredPermission

The required permission rank to be verified against the user’s permission level.

"unknown" | "visitor" | "editor" | "admin" | "owner"

Returns

Promise<boolean>

A promise that resolves to a boolean indicating whether the user’s permission level meets the required rank.