studiocms 0.1.0-beta.10

package/dist/lib/auth/rate-limit.js

@@ -0,0 +1,214 @@
+class RefillingTokenBucket {
+  /**
+   * The maximum number of tokens that the bucket can hold.
+   * @type {number}
+   */
+  max;
+  /**
+   * The interval in seconds at which tokens are refilled.
+   * @type {number}
+   */
+  refillIntervalSeconds;
+  /**
+   * Initializes a new instance of the RefillingTokenBucket class.
+   *
+   * @param {number} max - The maximum number of tokens the bucket can hold.
+   * @param {number} refillIntervalSeconds - The refill interval in seconds.
+   */
+  constructor(max, refillIntervalSeconds) {
+    this.max = max;
+    this.refillIntervalSeconds = refillIntervalSeconds;
+  }
+  /**
+   * A map storing individual token buckets associated with specific keys.
+   * @private
+   */
+  storage = /* @__PURE__ */ new Map();
+  /**
+   * Checks if there are enough tokens available in the bucket for the specified key and cost.
+   *
+   * @param {_Key} key - The key associated with the token bucket.
+   * @param {number} cost - The number of tokens required.
+   * @returns {boolean} - Returns `true` if there are enough tokens; otherwise, `false`.
+   */
+  check(key, cost) {
+    const bucket = this.storage.get(key) ?? null;
+    if (bucket === null) {
+      return true;
+    }
+    const now = Date.now();
+    const refill = Math.floor((now - bucket.refilledAt) / (this.refillIntervalSeconds * 1e3));
+    if (refill > 0) {
+      return Math.min(bucket.count + refill, this.max) >= cost;
+    }
+    return bucket.count >= cost;
+  }
+  /**
+   * Consumes tokens from the bucket for the specified key and cost.
+   *
+   * @param {_Key} key - The key associated with the token bucket.
+   * @param {number} cost - The number of tokens to consume.
+   * @returns {boolean} - Returns `true` if tokens were successfully consumed; otherwise, `false`.
+   */
+  consume(key, cost) {
+    let bucket = this.storage.get(key) ?? null;
+    const now = Date.now();
+    if (bucket === null) {
+      bucket = {
+        count: this.max - cost,
+        refilledAt: now
+      };
+      this.storage.set(key, bucket);
+      return true;
+    }
+    const refill = Math.floor((now - bucket.refilledAt) / (this.refillIntervalSeconds * 1e3));
+    bucket.count = Math.min(bucket.count + refill, this.max);
+    bucket.refilledAt = now;
+    if (bucket.count < cost) {
+      return false;
+    }
+    bucket.count -= cost;
+    this.storage.set(key, bucket);
+    return true;
+  }
+}
+class Throttler {
+  /**
+   * Array of timeout durations (in seconds) for each consecutive attempt.
+   * @type {number[]}
+   */
+  timeoutSeconds;
+  /**
+   * A map storing individual throttling counters associated with specific keys.
+   * @private
+   */
+  storage = /* @__PURE__ */ new Map();
+  /**
+   * Initializes a new instance of the Throttler class.
+   *
+   * @param {number[]} timeoutSeconds - Array of timeout durations in seconds for each consecutive attempt.
+   */
+  constructor(timeoutSeconds) {
+    this.timeoutSeconds = timeoutSeconds;
+  }
+  /**
+   * Attempts to consume an action for the specified key.
+   *
+   * @param {_Key} key - The key associated with the throttling counter.
+   * @returns {boolean} - Returns `true` if the action is allowed; otherwise, `false`.
+   */
+  consume(key) {
+    let counter = this.storage.get(key) ?? null;
+    const now = Date.now();
+    if (counter === null) {
+      counter = {
+        timeout: 0,
+        updatedAt: now
+      };
+      this.storage.set(key, counter);
+      return true;
+    }
+    const allowed = now - counter.updatedAt >= this.timeoutSeconds[counter.timeout] * 1e3;
+    if (!allowed) {
+      return false;
+    }
+    counter.updatedAt = now;
+    counter.timeout = Math.min(counter.timeout + 1, this.timeoutSeconds.length - 1);
+    this.storage.set(key, counter);
+    return true;
+  }
+  /**
+   * Resets the throttling counter for a specified key.
+   *
+   * @param {_Key} key - The key associated with the throttling counter to reset.
+   */
+  reset(key) {
+    this.storage.delete(key);
+  }
+}
+class ExpiringTokenBucket {
+  /**
+   * The maximum number of tokens the bucket can hold.
+   * @type {number}
+   */
+  max;
+  /**
+   * The duration (in seconds) after which tokens in the bucket expire.
+   * @type {number}
+   */
+  expiresInSeconds;
+  /**
+   * A map storing individual expiring token buckets associated with specific keys.
+   * @private
+   */
+  storage = /* @__PURE__ */ new Map();
+  /**
+   * Initializes a new instance of the ExpiringTokenBucket class.
+   *
+   * @param {number} max - The maximum number of tokens the bucket can hold.
+   * @param {number} expiresInSeconds - The duration in seconds after which tokens expire.
+   */
+  constructor(max, expiresInSeconds) {
+    this.max = max;
+    this.expiresInSeconds = expiresInSeconds;
+  }
+  /**
+   * Checks if there are enough tokens available in the bucket for the specified key and cost.
+   *
+   * @param {_Key} key - The key associated with the token bucket.
+   * @param {number} cost - The number of tokens required.
+   * @returns {boolean} - Returns `true` if there are enough tokens or if the tokens have expired; otherwise, `false`.
+   */
+  check(key, cost) {
+    const bucket = this.storage.get(key) ?? null;
+    const now = Date.now();
+    if (bucket === null) {
+      return true;
+    }
+    if (now - bucket.createdAt >= this.expiresInSeconds * 1e3) {
+      return true;
+    }
+    return bucket.count >= cost;
+  }
+  /**
+   * Consumes tokens from the bucket for the specified key and cost.
+   *
+   * @param {_Key} key - The key associated with the token bucket.
+   * @param {number} cost - The number of tokens to consume.
+   * @returns {boolean} - Returns `true` if tokens were successfully consumed; otherwise, `false`.
+   */
+  consume(key, cost) {
+    let bucket = this.storage.get(key) ?? null;
+    const now = Date.now();
+    if (bucket === null) {
+      bucket = {
+        count: this.max - cost,
+        createdAt: now
+      };
+      this.storage.set(key, bucket);
+      return true;
+    }
+    if (now - bucket.createdAt >= this.expiresInSeconds * 1e3) {
+      bucket.count = this.max;
+    }
+    if (bucket.count < cost) {
+      return false;
+    }
+    bucket.count -= cost;
+    this.storage.set(key, bucket);
+    return true;
+  }
+  /**
+   * Resets the token bucket for a specified key, removing all tokens.
+   *
+   * @param {_Key} key - The key associated with the token bucket to reset.
+   */
+  reset(key) {
+    this.storage.delete(key);
+  }
+}
+export {
+  ExpiringTokenBucket,
+  RefillingTokenBucket,
+  Throttler
+};

package/dist/lib/auth/session.d.ts

@@ -0,0 +1,85 @@
+import type { tsSessionTableSelect } from 'studiocms:sdk/types';
+import type { APIContext, AstroGlobal } from 'astro';
+import type { SessionValidationResult } from './types.js';
+/**
+ * Generates a session token.
+ *
+ * This function creates a random 20-byte array and encodes it using
+ * base32 encoding without padding. The resulting string is used as
+ * a session token.
+ *
+ * @returns {string} The generated session token.
+ */
+export declare function generateSessionToken(): string;
+/**
+ * The session expiration time in milliseconds.
+ * This value represents 14 days.
+ */
+export declare const sessionExpTime: number;
+/**
+ * Generates a new expiration date for a session.
+ *
+ * @returns {Date} The expiration date calculated by adding the session expiration time to the current date and time.
+ */
+export declare function makeExpirationDate(): Date;
+/**
+ * The name of the cookie used to store the authentication session.
+ *
+ * @constant {string}
+ */
+export declare const sessionCookieName = "auth_session";
+/**
+ * Creates a new session for a user.
+ *
+ * @param token - The token used to create the session.
+ * @param userId - The ID of the user for whom the session is being created.
+ * @returns A promise that resolves to the created session object.
+ */
+export declare function createSession(token: string, userId: string): Promise<tsSessionTableSelect>;
+/**
+ * Validates a session token by checking its existence and expiration in the database.
+ * If the session is valid but close to expiration, it extends the session expiration time.
+ * If the session is expired, it deletes the session from the database.
+ *
+ * @param token - The session token to validate.
+ * @returns A promise that resolves to an object containing the session and user information.
+ *          If the session is invalid or expired, both session and user will be null.
+ */
+export declare function validateSessionToken(token: string): Promise<SessionValidationResult>;
+/**
+ * Invalidates a session by deleting it from the database.
+ *
+ * @param sessionId - The unique identifier of the session to be invalidated.
+ * @returns A promise that resolves when the session has been successfully deleted.
+ */
+export declare function invalidateSession(sessionId: string): Promise<void>;
+/**
+ * Sets a session token cookie in the provided API context.
+ *
+ * @param context - The API context where the cookie will be set.
+ * @param token - The session token to be stored in the cookie.
+ * @param expiresAt - The expiration date of the cookie.
+ */
+export declare function setSessionTokenCookie(context: APIContext, token: string, expiresAt: Date): void;
+/**
+ * Deletes the session token cookie by setting it with an empty value and a max age of 0.
+ *
+ * @param context - The context in which the cookie is being set. This can be either an APIContext or AstroGlobal.
+ */
+export declare function deleteSessionTokenCookie(context: APIContext | AstroGlobal): void;
+/**
+ * Sets an OAuth session token cookie in the given API context.
+ *
+ * @param context - The API context which contains the cookies object.
+ * @param key - The name of the cookie to set.
+ * @param value - The value of the cookie to set.
+ */
+export declare function setOAuthSessionTokenCookie(context: APIContext, key: string, value: string): void;
+/**
+ * Creates a new user session.
+ *
+ * @param userId - The ID of the user for whom the session is being created.
+ * @param context - The API context which includes request and response objects.
+ * @returns A promise that resolves when the session has been successfully created.
+ */
+export declare function createUserSession(userId: string, context: APIContext): Promise<void>;

package/dist/lib/auth/session.js

@@ -0,0 +1,93 @@
+import studioCMS_SDK from "studiocms:sdk";
+import { sha256 } from "@oslojs/crypto/sha2";
+import { encodeBase32LowerCaseNoPadding, encodeHexLowerCase } from "@oslojs/encoding";
+function generateSessionToken() {
+  const bytes = new Uint8Array(20);
+  crypto.getRandomValues(bytes);
+  const token = encodeBase32LowerCaseNoPadding(bytes);
+  return token;
+}
+const sessionExpTime = 1e3 * 60 * 60 * 24 * 14;
+const expTimeHalf = sessionExpTime / 2;
+function makeExpirationDate() {
+  return new Date(Date.now() + sessionExpTime);
+}
+const sessionCookieName = "auth_session";
+async function createSession(token, userId) {
+  const sessionId = encodeHexLowerCase(sha256(new TextEncoder().encode(token)));
+  const session = {
+    id: sessionId,
+    userId,
+    expiresAt: new Date(Date.now() + sessionExpTime)
+  };
+  return await studioCMS_SDK.AUTH.session.create(session);
+}
+async function validateSessionToken(token) {
+  const sessionId = encodeHexLowerCase(sha256(new TextEncoder().encode(token)));
+  const result = await studioCMS_SDK.AUTH.session.sessionWithUser(sessionId);
+  if (result.length < 1) {
+    return { session: null, user: null };
+  }
+  const userSession = result[0];
+  if (!userSession) {
+    return { session: null, user: null };
+  }
+  const { user, session } = userSession;
+  if (Date.now() >= session.expiresAt.getTime()) {
+    await studioCMS_SDK.AUTH.session.delete(session.id);
+    return { session: null, user: null };
+  }
+  if (Date.now() >= session.expiresAt.getTime() - expTimeHalf) {
+    session.expiresAt = new Date(Date.now() + sessionExpTime);
+    await studioCMS_SDK.AUTH.session.update(session.id, session.expiresAt);
+  }
+  return { session, user };
+}
+async function invalidateSession(sessionId) {
+  await studioCMS_SDK.AUTH.session.delete(sessionId);
+}
+function setSessionTokenCookie(context, token, expiresAt) {
+  context.cookies.set(sessionCookieName, token, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: false,
+    expires: expiresAt,
+    path: "/"
+  });
+}
+function deleteSessionTokenCookie(context) {
+  context.cookies.set(sessionCookieName, "", {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: false,
+    maxAge: 0,
+    path: "/"
+  });
+}
+function setOAuthSessionTokenCookie(context, key, value) {
+  context.cookies.set(key, value, {
+    path: "/",
+    secure: false,
+    httpOnly: true,
+    maxAge: 60 * 10,
+    sameSite: "lax"
+  });
+}
+async function createUserSession(userId, context) {
+  const sessionToken = generateSessionToken();
+  await createSession(sessionToken, userId);
+  setSessionTokenCookie(context, sessionToken, makeExpirationDate());
+}
+export {
+  createSession,
+  createUserSession,
+  deleteSessionTokenCookie,
+  generateSessionToken,
+  invalidateSession,
+  makeExpirationDate,
+  sessionCookieName,
+  sessionExpTime,
+  setOAuthSessionTokenCookie,
+  setSessionTokenCookie,
+  validateSessionToken
+};

package/dist/lib/auth/types.d.ts

@@ -0,0 +1,83 @@
+import type { tsOAuthAccountsSelect, tsPermissionsSelect, tsSessionTableSelect, tsUsersSelect } from 'studiocms:sdk/types';
+/**
+ * Represents a table of OAuth accounts.
+ *
+ * @interface OAuthAccountsTable
+ * @property {string} provider - The name of the OAuth provider (e.g., Google, Facebook).
+ * @property {string} providerUserId - The unique identifier for the user provided by the OAuth provider.
+ * @property {string} userId - The unique identifier for the user within the application.
+ */
+export interface OAuthAccountsTable extends tsOAuthAccountsSelect {
+}
+/**
+ * Interface representing a table of user permissions.
+ *
+ * @property {string} user - The username of the individual.
+ * @property {string} rank - The rank or role assigned to the user.
+ */
+export interface PermissionsTable extends tsPermissionsSelect {
+}
+/**
+ * Represents the session data for a user.
+ *
+ * @property {boolean} isLoggedIn - Indicates whether the user is logged in.
+ * @property {UserTable | null} user - The user data, or null if no user is logged in.
+ * @property {'owner' | 'admin' | 'editor' | 'visitor' | 'unknown'} permissionLevel - The permission level of the user.
+ */
+export type UserSessionData = {
+    isLoggedIn: boolean;
+    user: tsUsersSelect | null;
+    permissionLevel: 'owner' | 'admin' | 'editor' | 'visitor' | 'unknown';
+};
+/**
+ * Represents a user session which includes user information and session details.
+ *
+ * @property {UserTable} user - The user information.
+ * @property {SessionTable} session - The session details.
+ */
+export type UserSession = {
+    user: tsUsersSelect;
+    session: tsSessionTableSelect;
+};
+/**
+ * Represents the result of a session validation.
+ *
+ * This type can either be a valid `UserSession` or an object indicating
+ * an invalid session with both `session` and `user` properties set to `null`.
+ */
+export type SessionValidationResult = UserSession | {
+    session: null;
+    user: null;
+};
+/**
+ * Represents an individual refillable token bucket.
+ *
+ * @interface RefillBucket
+ * @property {number} count - The current token count in the bucket.
+ * @property {number} refilledAt - The last timestamp when tokens were refilled.
+ */
+export interface RefillBucket {
+    count: number;
+    refilledAt: number;
+}
+/**
+ * Represents a bucket with an expiration mechanism.
+ *
+ * @interface ExpiringBucket
+ * @property {number} count - The number of items in the bucket.
+ * @property {number} createdAt - The timestamp when the bucket was created.
+ */
+export interface ExpiringBucket {
+    count: number;
+    createdAt: number;
+}
+/**
+ * Interface representing a throttling counter.
+ *
+ * @property {number} timeout - The duration (in milliseconds) for which the throttling is applied.
+ * @property {number} updatedAt - The timestamp (in milliseconds since epoch) when the throttling counter was last updated.
+ */
+export interface ThrottlingCounter {
+    timeout: number;
+    updatedAt: number;
+}

package/dist/lib/auth/user.d.ts

@@ -0,0 +1,148 @@
+import type { tsUsersInsert, tsUsersSelect } from 'studiocms:sdk/types';
+import type { APIContext, AstroGlobal } from 'astro';
+import type { UserSessionData } from './types.js';
+/**
+ * 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.
+ *
+ * @param username - The username to verify.
+ * @returns `true` if the username is valid, `false` otherwise.
+ */
+export declare function verifyUsernameInput(username: string): boolean;
+/**
+ * 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.
+ *
+ * @param email - The email address of the user.
+ * @returns A promise that resolves to the URL of the user's avatar.
+ */
+export declare function createUserAvatar(email: string): Promise<string>;
+/**
+ * Creates a new local user with the provided details.
+ *
+ * @param name - The full name of the user.
+ * @param username - The username for the user.
+ * @param email - The email address of the user.
+ * @param password - The password for the user.
+ * @returns A promise that resolves to the newly created user record.
+ */
+export declare function createLocalUser(name: string, username: string, email: string, password: string): Promise<tsUsersSelect>;
+/**
+ * Creates a new user with OAuth credentials.
+ *
+ * @param userFields - The fields required to create a new user.
+ * @param oAuthFields - The OAuth provider information, including the provider name and provider user ID.
+ * @returns The newly created user object or an error object if the creation fails.
+ */
+export declare function createOAuthUser(userFields: tsUsersInsert, oAuthFields: {
+    provider: string;
+    providerUserId: string;
+}): Promise<{
+    name: string;
+    username: string;
+    email: string | null;
+    id: string;
+    url: string | null;
+    avatar: string | null;
+    password: string | null;
+    updatedAt: Date | null;
+    createdAt: Date | null;
+} | {
+    error: string;
+}>;
+/**
+ * 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.
+ */
+export declare const LinkNewOAuthCookieName = "link-new-o-auth";
+/**
+ * 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.
+ *
+ * @param userId - The unique identifier of the user whose password is to be updated.
+ * @param password - The new password to be set for the user.
+ * @returns A promise that resolves when the password has been successfully updated.
+ */
+export declare function updateUserPassword(userId: string, password: string): Promise<void>;
+/**
+ * Retrieves the password hash for a given user by their user ID.
+ *
+ * @param userId - The unique identifier of the user whose password hash is to be retrieved.
+ * @returns 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.
+ */
+export declare function getUserPasswordHash(userId: string): Promise<string>;
+/**
+ * Retrieves a user from the database based on their email address.
+ *
+ * @param email - The email address of the user to retrieve.
+ * @returns A promise that resolves to the user data if found, or null if no user is found with the given email.
+ */
+export declare function getUserFromEmail(email: string): Promise<tsUsersSelect | null>;
+/**
+ * Retrieves user session data based on the provided Astro context.
+ *
+ * @param Astro - The Astro global object or API context containing cookies.
+ * @returns 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.
+ */
+export declare function getUserData(Astro: AstroGlobal | APIContext): Promise<UserSessionData>;
+/**
+ * An array of available permission ranks for users.
+ *
+ * The permission ranks are defined as a constant tuple and include the following values:
+ * - 'owner': The highest level of permission, typically the creator or primary administrator.
+ * - 'admin': A high level of permission, usually for users who manage the system.
+ * - 'editor': A mid-level permission, for users who can modify content.
+ * - 'visitor': A low-level permission, for users who can view content but not modify it.
+ * - 'unknown': A default or fallback permission rank for users with undefined roles.
+ */
+declare const availablePermissionRanks: readonly ["owner", "admin", "editor", "visitor", "unknown"];
+/**
+ * Represents the available permission ranks for a user.
+ *
+ * This type is derived from the `availablePermissionRanks` array,
+ * and it includes all the possible values that a user can have as a permission rank.
+ */
+type AvailablePermissionRanks = (typeof availablePermissionRanks)[number];
+/**
+ * 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'.
+ *
+ * @property {string[]} owner - The 'owner' rank, which includes only the 'owner' role.
+ * @property {string[]} admin - The 'admin' rank, which includes 'owner' and 'admin' roles.
+ * @property {string[]} editor - The 'editor' rank, which includes 'owner', 'admin', and 'editor' roles.
+ * @property {string[]} visitor - The 'visitor' rank, which includes 'owner', 'admin', 'editor', and 'visitor' roles.
+ * @property {string[]} unknown - The 'unknown' rank, which includes all roles: 'owner', 'admin', 'editor', 'visitor', and 'unknown'.
+ */
+export declare const permissionRanksMap: Record<AvailablePermissionRanks, string[]>;
+/**
+ * Verifies if the user's permission level meets the required permission rank.
+ *
+ * @param userData - The session data of the user, which includes their permission level.
+ * @param requiredPermission - The required permission rank to be verified against the user's permission level.
+ * @returns A promise that resolves to a boolean indicating whether the user's permission level meets the required rank.
+ */
+export declare function verifyUserPermissionLevel(userData: UserSessionData, requiredPermission: AvailablePermissionRanks): Promise<boolean>;
+export {};