@withstudiocms/auth-kit 0.1.0-beta.1

package/dist/utils/session.d.ts

@@ -0,0 +1,22 @@
+import { Effect } from '@withstudiocms/effect';
+import type { SessionConfig } from '../types.js';
+/**
+ * The default configuration for user sessions.
+ *
+ * @remarks
+ * - `expTime` sets the session expiration time in milliseconds (default: 14 days).
+ * - `cookieName` specifies the name of the cookie used to store the session.
+ *
+ * @example
+ * // Use the default session configuration
+ * app.useSession(defaultSessionConfig);
+ */
+export declare const defaultSessionConfig: SessionConfig;
+/**
+ * Generates a session ID by hashing the provided token using SHA-256 and encoding it in hexadecimal format.
+ */
+export declare const makeSessionId: (token: string) => Effect.Effect.AsEffect<Effect.Effect<string, import("../errors.js").SessionError, never>>;
+/**
+ * Generates a new expiration date for a session.
+ */
+export declare const makeExpirationDate: (expTime: number) => Effect.Effect.AsEffect<Effect.Effect<Date, import("../errors.js").SessionError, never>>;

package/dist/utils/session.js

@@ -0,0 +1,29 @@
+import { sha256 } from "@oslojs/crypto/sha2";
+import { encodeHexLowerCase } from "@oslojs/encoding";
+import { Effect, pipe } from "@withstudiocms/effect";
+import { useSessionError } from "../errors.js";
+const defaultSessionConfig = {
+  expTime: 1e3 * 60 * 60 * 24 * 14,
+  cookieName: "auth_session"
+};
+const makeSessionId = Effect.fn(
+  (token) => useSessionError(() => {
+    if (typeof token !== "string" || token.length === 0) {
+      throw new TypeError("Invalid token");
+    }
+    return pipe(new TextEncoder().encode(token), sha256, encodeHexLowerCase);
+  })
+);
+const makeExpirationDate = Effect.fn(
+  (expTime) => useSessionError(() => {
+    if (!Number.isFinite(expTime) || expTime <= 0) {
+      throw new TypeError("Invalid expiration time");
+    }
+    return new Date(Date.now() + expTime);
+  })
+);
+export {
+  defaultSessionConfig,
+  makeExpirationDate,
+  makeSessionId
+};

package/dist/utils/unsafeCheck.d.ts

@@ -0,0 +1,27 @@
+import { Effect } from '@withstudiocms/effect';
+declare const CheckIfUnsafe_base: Effect.Service.Class<CheckIfUnsafe, "studiocms/virtuals/auth/utils/unsafeCheck/CheckIfUnsafe", {
+    readonly effect: Effect.Effect<{
+        username: (val: string) => Effect.Effect<boolean, import("../errors.js").CheckIfUnsafeError, never>;
+        password: (val: string) => Effect.Effect<boolean, import("../errors.js").CheckIfUnsafeError, never>;
+    }, never, never>;
+}>;
+/**
+ * A service class that provides utility functions to check if a value is unsafe,
+ * such as being a reserved username or a password.
+ *
+ * @remarks
+ * This service uses logging and effect-based programming to perform the checks.
+ *
+ * @example
+ * ```typescript
+ * const checkIfUnsafe = CheckIfUnsafe;
+ * const isReservedUsername = yield* checkIfUnsafe.username('admin');
+ * const isPassword = yield* checkIfUnsafe.password('123456');
+ * ```
+ *
+ * @class
+ * @implements {Effect.Service<CheckIfUnsafe>}
+ */
+export declare class CheckIfUnsafe extends CheckIfUnsafe_base {
+}
+export {};

package/dist/utils/unsafeCheck.js

@@ -0,0 +1,27 @@
+import { Effect } from "@withstudiocms/effect";
+import { useUnsafeCheckError } from "../errors.js";
+import { isReservedPassword } from "./lists/passwords.js";
+import { isReservedUsername } from "./lists/usernames.js";
+class CheckIfUnsafe extends Effect.Service()(
+  "studiocms/virtuals/auth/utils/unsafeCheck/CheckIfUnsafe",
+  {
+    effect: Effect.gen(function* () {
+      const username = (val) => useUnsafeCheckError(
+        () => isReservedUsername(val),
+        "An unknown Error occurred when checking the username list"
+      );
+      const password = (val) => useUnsafeCheckError(
+        () => isReservedPassword(val),
+        "An unknown Error occurred when checking the password list"
+      );
+      return {
+        username,
+        password
+      };
+    })
+  }
+) {
+}
+export {
+  CheckIfUnsafe
+};

package/dist/utils/user.d.ts

@@ -0,0 +1,62 @@
+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>;

package/dist/utils/user.js

@@ -0,0 +1,80 @@
+import { Effect } from "@withstudiocms/effect";
+import { useUserError } from "../errors.js";
+import {
+  UserPermissionLevel
+} from "../types.js";
+import { CheckIfUnsafe } from "./unsafeCheck.js";
+const verifyUsernameLength = (username) => useUserError(() => {
+  if (username.length < 3 || username.length > 32) {
+    return "Username must be between 3 and 32 characters long";
+  }
+  return void 0;
+});
+const verifyUsernameCharacters = Effect.fn(
+  (username) => useUserError(() => {
+    if (!/^[a-z0-9_-]+$/.test(username)) {
+      return "Username can only contain lowercase letters, numbers, hyphens (-), and underscores (_)";
+    }
+    return void 0;
+  })
+);
+const verifyUsernameSafe = (username) => Effect.gen(function* () {
+  const check = yield* CheckIfUnsafe;
+  const isUnsafe = yield* check.username(username);
+  if (isUnsafe) {
+    return "Username should not be a commonly used unsafe username (admin, root, etc.)";
+  }
+  return void 0;
+}).pipe(Effect.provide(CheckIfUnsafe.Default));
+const getDefaultUserSession = Effect.fn(
+  () => Effect.succeed({
+    isLoggedIn: false,
+    user: null,
+    permissionLevel: "unknown"
+  })
+);
+const normalizeRank = (v) => {
+  switch (v) {
+    case "owner":
+    case "admin":
+    case "editor":
+    case "visitor":
+    case "unknown":
+      return v;
+    default:
+      return "unknown";
+  }
+};
+const getLevel = (userData) => useUserError(() => {
+  if (!userData) return "unknown";
+  let userPermissionLevel = "unknown";
+  if ("permissionLevel" in userData) {
+    userPermissionLevel = normalizeRank(userData.permissionLevel);
+  }
+  if ("permissionsData" in userData && userData.permissionsData?.rank) {
+    userPermissionLevel = normalizeRank(userData.permissionsData.rank);
+  }
+  return userPermissionLevel;
+});
+const parseRequiredPerms = (requiredPerms) => useUserError(() => {
+  switch (requiredPerms) {
+    case "owner":
+      return UserPermissionLevel.owner;
+    case "admin":
+      return UserPermissionLevel.admin;
+    case "editor":
+      return UserPermissionLevel.editor;
+    case "visitor":
+      return UserPermissionLevel.visitor;
+    default:
+      return UserPermissionLevel.unknown;
+  }
+});
+export {
+  getDefaultUserSession,
+  getLevel,
+  parseRequiredPerms,
+  verifyUsernameCharacters,
+  verifyUsernameLength,
+  verifyUsernameSafe
+};

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@withstudiocms/auth-kit",
+  "version": "0.1.0-beta.1",
+  "description": "Utilities for managing authentication",
+  "author": {
+    "name": "withstudiocms",
+    "url": "https://studiocms.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstudiocms/studiocms.git",
+    "directory": "packages/@withstudiocms/auth-kit"
+  },
+  "contributors": [
+    "Adammatthiesen",
+    "jdtjenkins",
+    "dreyfus92",
+    "code.spirit"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "astro-studiocms",
+    "cms",
+    "studiocms"
+  ],
+  "homepage": "https://studiocms.dev",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./utils/*": {
+      "types": "./dist/utils/*.d.ts",
+      "default": "./dist/utils/*.js"
+    }
+  },
+  "type": "module",
+  "dependencies": {
+    "@oslojs/binary": "^1.0.0",
+    "@oslojs/crypto": "^1.0.1",
+    "@oslojs/encoding": "^1.1.0",
+    "@withstudiocms/effect": "0.1.0-beta.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "peerDependencies": {
+    "astro": "^5.12.9"
+  },
+  "scripts": {
+    "update:username-list": "node ./scripts/update-usernames.js",
+    "update:password-list": "node ./scripts/update-passwords.js",
+    "update:lists": "pnpm update:username-list && pnpm update:password-list",
+    "build": "pnpm update:lists && pnpm buildkit build 'src/**/*.{ts,astro,css,json,png}'",
+    "dev": "pnpm update:lists && pnpm buildkit dev 'src/**/*.{ts,astro,css,json,png}'",
+    "test": "buildkit test 'test/**/*.test.js'",
+    "typecheck": "tspc -p tsconfig.tspc.json"
+  }
+}