@withstudiocms/auth-kit 0.1.0-beta.1

package/dist/types.d.ts

@@ -0,0 +1,220 @@
+import type { BinaryLike } from 'node:crypto';
+import type { Effect } from '@withstudiocms/effect';
+import type { ScryptError } from '@withstudiocms/effect/scrypt';
+/**
+ * Mocked internal Scrypt type
+ */
+export type IScrypt = Effect.Effect<{
+    run: (password: BinaryLike) => Effect.Effect<Buffer<ArrayBufferLike>, ScryptError, never>;
+}, never, never>;
+/**
+ * Represents a user session with expiration information.
+ *
+ * @property expiresAt - The date and time when the session expires.
+ * @property id - The unique identifier for the session.
+ * @property userId - The unique identifier of the user associated with the session.
+ */
+export interface UserSession {
+    expiresAt: Date;
+    id: string;
+    userId: string;
+}
+/**
+ * Represents the user data structure for authentication and profile management.
+ *
+ * @property name - The full name of the user.
+ * @property id - The unique identifier for the user.
+ * @property url - The user's personal or profile URL, if available.
+ * @property email - The user's email address, or null if not set.
+ * @property avatar - The URL to the user's avatar image, or null if not set.
+ * @property username - The user's unique username.
+ * @property password - The user's password (hashed or plain), or null if not set.
+ * @property updatedAt - The date and time when the user was last updated, or null if not set.
+ * @property createdAt - The date and time when the user was created, or null if not set.
+ * @property emailVerified - Indicates whether the user's email has been verified.
+ * @property notifications - Notification settings or preferences for the user, or null if not set.
+ */
+export interface UserData {
+    name: string;
+    username: string;
+    id?: string | undefined;
+    url?: string | null | undefined;
+    email?: string | null | undefined;
+    avatar?: string | null | undefined;
+    password?: string | null | undefined;
+    updatedAt?: Date | null | undefined;
+    createdAt?: Date | null | undefined;
+    emailVerified?: boolean | undefined;
+    notifications?: string | null | undefined;
+}
+/**
+ * Represents the data associated with an OAuth authentication event.
+ *
+ * @property userId - The unique identifier of the user in the local system.
+ * @property provider - The name of the OAuth provider (e.g., 'google', 'github').
+ * @property providerUserId - The unique identifier of the user as provided by the OAuth provider.
+ */
+export interface OAuthData {
+    userId: string;
+    provider: string;
+    providerUserId: string;
+}
+/**
+ * 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.
+ */
+export 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.
+ */
+export type AvailablePermissionRanks = (typeof availablePermissionRanks)[number];
+/**
+ * Represents the permissions data for a user.
+ *
+ * @property user - The unique identifier of the user.
+ * @property rank - The permission rank assigned to the user.
+ */
+export interface PermissionsData {
+    user: string;
+    rank: AvailablePermissionRanks;
+}
+type Present<T> = {
+    [K in keyof T]-?: Exclude<T[K], undefined>;
+};
+/**
+ * Represents the session data for a user.
+ *
+ * @property isLoggedIn - Indicates whether the user is currently logged in.
+ * @property user - The user data object, or `null` if no user is logged in.
+ * @property permissionLevel - The user's permission level, represented by an available permission rank.
+ */
+export type UserSessionData = {
+    isLoggedIn: boolean;
+    user: Present<UserData> | null;
+    permissionLevel: AvailablePermissionRanks;
+};
+/**
+ * Represents a user object that combines base user data with optional OAuth and permissions data.
+ *
+ * @extends UserData
+ * @property {OAuthData[] | undefined} oAuthData - An array of OAuth provider data associated with the user, or undefined if not available.
+ * @property {PermissionsData | undefined} permissionsData - The permissions data for the user, or undefined if not available.
+ */
+export interface CombinedUserData extends UserData {
+    oAuthData?: OAuthData[];
+    permissionsData?: PermissionsData;
+}
+/**
+ * Represents the combined session and user data.
+ *
+ * @property session - The current user's session information.
+ * @property user - The current user's profile and related data.
+ */
+export interface SessionAndUserData {
+    session: UserSession;
+    user: Present<UserData>;
+}
+/**
+ * Represents the result of validating a session.
+ *
+ * This type is either a valid session and user data (`SessionAndUserData`),
+ * or an object indicating that there is no valid session or user.
+ *
+ * - If the session is valid, it returns `SessionAndUserData`.
+ * - If the session is invalid or not found, it returns an object with both `session` and `user` set to `null`.
+ */
+export type SessionValidationResult = SessionAndUserData | {
+    session: null;
+    user: null;
+};
+/**
+ * Provides methods for managing user sessions.
+ *
+ * @interface SessionTools
+ */
+export interface SessionTools {
+    createSession(params: UserSession): Promise<UserSession>;
+    sessionAndUserData(sessionId: string): Promise<SessionAndUserData[]>;
+    deleteSession(sessionId: string): Promise<void>;
+    updateSession(sessionId: string, data: UserSession): Promise<UserSession[]>;
+}
+/**
+ * Configuration options for managing user sessions.
+ *
+ * @property expTime - The expiration time for the session, in milliseconds.
+ * @property cookieName - The name of the cookie used to store the session identifier.
+ * @property sessionTools - Utilities or tools for session management.
+ */
+export interface SessionConfig {
+    expTime: number;
+    cookieName: string;
+    sessionTools?: SessionTools;
+}
+/**
+ * Provides utility methods for user management and notification within the authentication system.
+ *
+ * @remarks
+ * This interface defines methods for creating, updating, and retrieving user data,
+ * as well as generating unique IDs and sending notifications to administrators.
+ */
+export interface UserTools {
+    idGenerator(): string;
+    notifier?: {
+        admin(type: 'new_user', message: string): Promise<void>;
+    };
+    createLocalUser(data: UserData): Promise<Present<UserData>>;
+    createOAuthUser(data: {
+        provider: string;
+        providerUserId: string;
+        userId: string;
+    }): Promise<{
+        userId: string;
+        provider: string;
+        providerUserId: string;
+    }>;
+    updateLocalUser(id: string, data: Partial<UserData>): Promise<Present<UserData>>;
+    getUserById(id: string): Promise<CombinedUserData | undefined | null>;
+    getUserByEmail(email: string): Promise<CombinedUserData | undefined | null>;
+    getCurrentPermissions(userId: string): Promise<PermissionsData | undefined | null>;
+}
+/**
+ * Configuration options for user authentication and session management.
+ *
+ * @property Scrypt - The Scrypt configuration used for password hashing.
+ * @property session - The required session configuration object.
+ * @property userTools - Optional utilities or tools related to user management.
+ */
+export interface UserConfig {
+    Scrypt: IScrypt;
+    session: Required<SessionConfig>;
+    userTools?: UserTools;
+}
+/**
+ * An enumeration representing different user permission levels.
+ *
+ * The permission levels are defined as follows:
+ * - visitor: 1
+ * - editor: 2
+ * - admin: 3
+ * - owner: 4
+ * - unknown: 0
+ */
+export declare enum UserPermissionLevel {
+    visitor = 1,
+    editor = 2,
+    admin = 3,
+    owner = 4,
+    unknown = 0
+}
+export declare const rankToLevel: Record<AvailablePermissionRanks, UserPermissionLevel>;
+export declare const levelToRank: Record<UserPermissionLevel, AvailablePermissionRanks>;
+export {};

package/dist/types.js

@@ -0,0 +1,29 @@
+const availablePermissionRanks = ["owner", "admin", "editor", "visitor", "unknown"];
+var UserPermissionLevel = /* @__PURE__ */ ((UserPermissionLevel2) => {
+  UserPermissionLevel2[UserPermissionLevel2["visitor"] = 1] = "visitor";
+  UserPermissionLevel2[UserPermissionLevel2["editor"] = 2] = "editor";
+  UserPermissionLevel2[UserPermissionLevel2["admin"] = 3] = "admin";
+  UserPermissionLevel2[UserPermissionLevel2["owner"] = 4] = "owner";
+  UserPermissionLevel2[UserPermissionLevel2["unknown"] = 0] = "unknown";
+  return UserPermissionLevel2;
+})(UserPermissionLevel || {});
+const rankToLevel = {
+  unknown: 0 /* unknown */,
+  visitor: 1 /* visitor */,
+  editor: 2 /* editor */,
+  admin: 3 /* admin */,
+  owner: 4 /* owner */
+};
+const levelToRank = {
+  [0 /* unknown */]: "unknown",
+  [1 /* visitor */]: "visitor",
+  [2 /* editor */]: "editor",
+  [3 /* admin */]: "admin",
+  [4 /* owner */]: "owner"
+};
+export {
+  UserPermissionLevel,
+  availablePermissionRanks,
+  levelToRank,
+  rankToLevel
+};

package/dist/utils/libravatar.d.ts

@@ -0,0 +1,57 @@
+interface SrvRecord {
+    priority: number;
+    weight: number;
+    port: number;
+    name: string;
+}
+interface AvatarOptions {
+    email?: string;
+    openid?: string;
+    https?: boolean;
+    [key: string]: any;
+}
+interface UserIdentity {
+    hash: string | null;
+    domain: string | null;
+}
+type TargetComponents = [string | null, number | null];
+/**
+ * Return the right (target, port) pair from a list of SRV records.
+ */
+export declare const srvHostname: (records: SrvRecord[]) => TargetComponents;
+/**
+ * Ensure we are getting a (mostly) valid hostname and port number
+ * from the DNS resolver and return the final hostname:port string.
+ */
+export declare const sanitizedTarget: (targetComponents: TargetComponents, https: boolean) => string | null;
+/**
+ * Generate user hash based on the email address or OpenID and return
+ * it along with the relevant domain.
+ */
+export declare const parseUserIdentity: (email?: string, openid?: string) => UserIdentity;
+/**
+ * Return the DNS service to query for a given domain and scheme.
+ */
+export declare const serviceName: (domain: string | null, https: boolean) => string | null;
+/**
+ * Assemble the final avatar URL based on the provided components.
+ */
+export declare const composeAvatarUrl: (delegationServer: string | null, avatarHash: string, queryString: string, https: boolean) => string;
+/**
+ * Get the delegation server for a given domain.
+ */
+export declare const getDelegationServer: (domain: string | null, https: boolean) => Promise<string | null>;
+/**
+ * Generate an avatar URL for the given options.
+ */
+export declare const getAvatarUrl: (options: AvatarOptions) => Promise<string>;
+declare const _default: {
+    getAvatarUrl: (options: AvatarOptions) => Promise<string>;
+    sanitizedTarget: (targetComponents: TargetComponents, https: boolean) => string | null;
+    srvHostname: (records: SrvRecord[]) => TargetComponents;
+    parseUserIdentity: (email?: string, openid?: string) => UserIdentity;
+    serviceName: (domain: string | null, https: boolean) => string | null;
+    composeAvatarUrl: (delegationServer: string | null, avatarHash: string, queryString: string, https: boolean) => string;
+    getDelegationServer: (domain: string | null, https: boolean) => Promise<string | null>;
+};
+export default _default;

package/dist/utils/libravatar.js

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+import { resolveSrv } from "node:dns/promises";
+import { stringify } from "node:querystring";
+const BASE_URL = "http://cdn.libravatar.org/avatar/";
+const SECURE_BASE_URL = "https://seccdn.libravatar.org/avatar/";
+const SERVICE_BASE = "_avatars._tcp";
+const SECURE_SERVICE_BASE = "_avatars-sec._tcp";
+const srvHostname = (records) => {
+  if (records.length < 1) {
+    return [null, null];
+  }
+  if (records.length === 1) {
+    return [records[0].name, records[0].port];
+  }
+  let priorityRecords = [];
+  let totalWeight = 0;
+  let topPriority = records[0].priority;
+  records.forEach((srvRecord) => {
+    if (srvRecord.priority <= topPriority) {
+      if (srvRecord.priority < topPriority) {
+        topPriority = srvRecord.priority;
+        totalWeight = 0;
+        priorityRecords = [];
+      }
+      totalWeight += srvRecord.weight;
+      if (srvRecord.weight > 0) {
+        priorityRecords.push([totalWeight, srvRecord]);
+      } else {
+        priorityRecords.unshift([0, srvRecord]);
+      }
+    }
+  });
+  if (priorityRecords.length === 1) {
+    const srvRecord = priorityRecords[0][1];
+    return [srvRecord.name, srvRecord.port];
+  }
+  const randomNumber = Math.floor(Math.random() * (totalWeight + 1));
+  for (let i = 0; i < priorityRecords.length; i++) {
+    const weightedIndex = priorityRecords[i][0];
+    const target = priorityRecords[i][1];
+    if (weightedIndex >= randomNumber) {
+      return [target.name, target.port];
+    }
+  }
+  console.log("There is something wrong with our SRV weight ordering algorithm");
+  return [null, null];
+};
+const sanitizedTarget = (targetComponents, https) => {
+  const target = targetComponents[0];
+  const port = targetComponents[1];
+  if (target === null || port === null || Number.isNaN(port)) {
+    return null;
+  }
+  if (port < 1 || port > 65535) {
+    return null;
+  }
+  if (target.search(/^[0-9a-zA-Z\-.]+$/) === -1) {
+    return null;
+  }
+  if (target && (https && port !== 443 || !https && port !== 80)) {
+    return `${target}:${port}`;
+  }
+  return target;
+};
+const parseUserIdentity = (email, openid) => {
+  let hash = null;
+  let domain = null;
+  if (email != null) {
+    const lowercaseValue = email.trim().toLowerCase();
+    const emailParts = lowercaseValue.split("@");
+    if (emailParts.length > 1) {
+      domain = emailParts[emailParts.length - 1];
+      hash = createHash("md5").update(lowercaseValue).digest("hex");
+    }
+  } else if (openid != null) {
+    try {
+      const parsedUrl = new URL(openid);
+      let normalizedUrl = parsedUrl.protocol.toLowerCase();
+      normalizedUrl += "//";
+      if (parsedUrl.username || parsedUrl.password) {
+        const auth = parsedUrl.username + (parsedUrl.password ? `:${parsedUrl.password}` : "");
+        normalizedUrl += `${auth}@`;
+      }
+      normalizedUrl += parsedUrl.hostname.toLowerCase() + parsedUrl.pathname;
+      domain = parsedUrl.hostname.toLowerCase();
+      hash = createHash("sha256").update(normalizedUrl).digest("hex");
+    } catch (_error) {
+      return { hash: null, domain: null };
+    }
+  }
+  return { hash, domain };
+};
+const serviceName = (domain, https) => {
+  if (domain) {
+    return `${https ? SECURE_SERVICE_BASE : SERVICE_BASE}.${domain}`;
+  }
+  return null;
+};
+const composeAvatarUrl = (delegationServer, avatarHash, queryString, https) => {
+  let baseUrl = https ? SECURE_BASE_URL : BASE_URL;
+  if (delegationServer) {
+    baseUrl = `http${https ? "s" : ""}://${delegationServer}/avatar/`;
+  }
+  return baseUrl + avatarHash + queryString;
+};
+const getDelegationServer = async (domain, https) => {
+  if (!domain) {
+    return null;
+  }
+  const service = serviceName(domain, https);
+  if (!service) {
+    return null;
+  }
+  try {
+    const addresses = await resolveSrv(service);
+    return sanitizedTarget(srvHostname(addresses), https);
+  } catch (_error) {
+    return null;
+  }
+};
+const getAvatarUrl = async (options) => {
+  const identity = parseUserIdentity(options.email, options.openid);
+  const hash = identity.hash;
+  const domain = identity.domain;
+  const https = options.https || false;
+  if (!hash) {
+    throw new Error("An email or an OpenID must be provided.");
+  }
+  const queryOptions = { ...options };
+  delete queryOptions.email;
+  delete queryOptions.openid;
+  delete queryOptions.https;
+  const queryData = stringify(queryOptions);
+  const query = queryData ? `?${queryData}` : "";
+  const delegationServer = await getDelegationServer(domain, https);
+  return composeAvatarUrl(delegationServer, hash, query, https);
+};
+var libravatar_default = {
+  getAvatarUrl,
+  // Export utility functions for testing
+  sanitizedTarget,
+  srvHostname,
+  parseUserIdentity,
+  serviceName,
+  composeAvatarUrl,
+  getDelegationServer
+};
+export {
+  composeAvatarUrl,
+  libravatar_default as default,
+  getAvatarUrl,
+  getDelegationServer,
+  parseUserIdentity,
+  sanitizedTarget,
+  serviceName,
+  srvHostname
+};

package/dist/utils/lists/passwords.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Set of common passwords that should be blocked for security reasons.
+ * This list contains the most commonly used passwords from various data breaches.
+ *
+ * Usage:
+ * import { blockedPasswords } from './passwords';
+ *
+ * const isPasswordBlocked = blockedPasswords.has(userPassword.toLowerCase());
+ */
+export declare const passwords: Set<string>;
+/**
+ * Check if a password is in the blocked list (case-insensitive)
+ * @param pass - The password to check
+ * @returns true if the password is blocked, false otherwise
+ */
+export declare const isReservedPassword: (pass: string) => boolean;
+export default passwords;