@withstudiocms/auth-kit 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -1,5 +1,7 @@
 # @withstudiocms/auth-kit
 
+[![codecov](https://codecov.io/github/withstudiocms/studiocms/graph/badge.svg?token=RN8LT1O5E2&component=withstudiocms_auth_kit)](https://codecov.io/github/withstudiocms/studiocms)
+
 Authentication Management utilities for StudioCMS
 
 ## Example Astro DB Tables

package/dist/config.d.ts

@@ -1,6 +1,36 @@
 import { Brand, Context, Layer } from '@withstudiocms/effect';
 import { ScryptConfigOptions } from '@withstudiocms/effect/scrypt';
 import type { SessionConfig, UserTools } from './types.js';
+/**
+ * Configuration options for the password module.
+ *
+ * @property CMS_ENCRYPTION_KEY - The encryption key used for securing CMS passwords.
+ */
+export type PasswordModConfig = {
+    CMS_ENCRYPTION_KEY: string;
+};
+/**
+ * The finalized configuration object for the password module.
+ *
+ * @property CMS_ENCRYPTION_KEY - The encryption key used by the CMS for securing sensitive data.
+ * @property scrypt - Configuration options for the scrypt password hashing algorithm.
+ * @remarks
+ * This type is branded as 'PasswordModConfigFinal' to provide nominal typing and prevent accidental misuse.
+ */
+export type PasswordModConfigFinal = {
+    scrypt: ScryptConfigOptions;
+} & Brand.Brand<'PasswordModConfigFinal'>;
+/**
+ * A nominal type for the finalized password module configuration object.
+ *
+ * This constant uses the `Brand.nominal` utility to create a strongly-typed
+ * identifier for the `PasswordModConfigFinal` type, ensuring type safety and preventing
+ * accidental misuse of configuration objects.
+ *
+ * @see PasswordModConfigFinal
+ * @see Brand.nominal
+ */
+export declare const PasswordModConfigFinal: Brand.Brand.Constructor<PasswordModConfigFinal>;
 /**
  * Represents the raw configuration object for the Auth Kit.
  *
@@ -40,6 +70,39 @@ export type AuthKitConfig = {
  * @see Brand.nominal
  */
 export declare const AuthKitConfig: Brand.Brand.Constructor<AuthKitConfig>;
+/**
+ * Generates and validates the final password module configuration using the provided encryption key and optional scrypt parameters.
+ *
+ * @param config - An object containing the `CMS_ENCRYPTION_KEY` as a base64-encoded string.
+ * @returns The finalized password module configuration object.
+ *
+ * @throws {Error} If the `CMS_ENCRYPTION_KEY` is empty, not valid base64, or does not decode to exactly 16 bytes.
+ *
+ * @remarks
+ * - The `CMS_ENCRYPTION_KEY` must be a base64-encoded string representing 16 bytes (128 bits) for AES-128 encryption.
+ * - Scrypt parameters (`SCRYPT_N`, `SCRYPT_R`, `SCRYPT_P`) can be overridden via environment variables. They are clamped to safe ranges.
+ * - The function normalizes and validates the encryption key, then constructs the scrypt configuration for password hashing.
+ */
+export declare function makePasswordModConfig({ CMS_ENCRYPTION_KEY, }: PasswordModConfig): PasswordModConfigFinal;
+declare const PasswordModOptions_base: Context.TagClass<PasswordModOptions, "PasswordModOptions", PasswordModConfigFinal>;
+/**
+ * Represents the options for the Password Module, extending the Context.Tag utility.
+ *
+ * @template PasswordModOptions - The type of the options for the Password Module.
+ * @template PasswordModConfigFinal - The finalized configuration type for the Password Module.
+ *
+ * @example
+ * // Create a live layer with the provided configuration
+ * const layer = PasswordModOptions.Live({ CMS_ENCRYPTION_KEY: 'your-key' });
+ *
+ * @method
+ * @static
+ * @param {PasswordModConfig} config - The configuration object containing the CMS encryption key.
+ * @returns {Layer<PasswordModOptions, PasswordModConfigFinal>} A Layer instance with the provided configuration.
+ */
+export declare class PasswordModOptions extends PasswordModOptions_base {
+    static Live: ({ CMS_ENCRYPTION_KEY }: PasswordModConfig) => Layer.Layer<PasswordModOptions, never, never>;
+}
 declare const AuthKitOptions_base: Context.TagClass<AuthKitOptions, "AuthKitOptions", AuthKitConfig>;
 /**
  * Provides configuration options for the AuthKit module.

package/dist/config.js

@@ -1,7 +1,50 @@
 import { Brand, Context, Layer } from "@withstudiocms/effect";
 import { ScryptConfigOptions } from "@withstudiocms/effect/scrypt";
 import { defaultSessionConfig } from "./utils/session.js";
+const PasswordModConfigFinal = Brand.nominal();
 const AuthKitConfig = Brand.nominal();
+function makePasswordModConfig({
+  CMS_ENCRYPTION_KEY
+}) {
+  const normalizedKey = CMS_ENCRYPTION_KEY.trim();
+  if (normalizedKey.length === 0) {
+    throw new Error("CMS_ENCRYPTION_KEY must be a non-empty base64 string");
+  }
+  let raw;
+  try {
+    raw = typeof Buffer !== "undefined" ? Buffer.from(normalizedKey, "base64") : new Uint8Array(
+      atob(normalizedKey).split("").map((c) => c.charCodeAt(0))
+    );
+  } catch {
+    throw new Error("CMS_ENCRYPTION_KEY is not valid base64");
+  }
+  if (raw.byteLength !== 16) {
+    throw new Error(`CMS_ENCRYPTION_KEY must decode to 16 bytes, got ${raw.byteLength}`);
+  }
+  const clamp = (v, min, max) => Number.isSafeInteger(v) ? Math.min(max, Math.max(min, v)) : min;
+  const env = (k) => typeof process !== "undefined" && process.env ? process.env[k] : void 0;
+  const parsedN = Number.parseInt(env("SCRYPT_N") ?? "", 10);
+  const parsedR = Number.parseInt(env("SCRYPT_R") ?? "", 10);
+  const parsedP = Number.parseInt(env("SCRYPT_P") ?? "", 10);
+  const toPowerOfTwo = (n) => 1 << Math.floor(Math.log2(n));
+  const baseN = clamp(parsedN, 16384, 1 << 20);
+  const SCRYPT_N = toPowerOfTwo(baseN);
+  const SCRYPT_R = clamp(parsedR, 8, 32);
+  const SCRYPT_P = clamp(parsedP, 1, 16);
+  const scrypt = ScryptConfigOptions({
+    encryptionKey: normalizedKey,
+    keylen: 64,
+    options: {
+      N: SCRYPT_N,
+      r: SCRYPT_R,
+      p: SCRYPT_P
+    }
+  });
+  return PasswordModConfigFinal({ scrypt });
+}
+class PasswordModOptions extends Context.Tag("PasswordModOptions")() {
+  static Live = ({ CMS_ENCRYPTION_KEY }) => Layer.succeed(this, makePasswordModConfig({ CMS_ENCRYPTION_KEY }));
+}
 class AuthKitOptions extends Context.Tag("AuthKitOptions")() {
   /**
    * Creates a live instance of `AuthKitOptions` using the provided raw configuration.
@@ -18,39 +61,7 @@ class AuthKitOptions extends Context.Tag("AuthKitOptions")() {
    * - The returned Layer can be used for dependency injection in the application.
    */
   static Live = ({ CMS_ENCRYPTION_KEY, session: _session, userTools }) => {
-    const normalizedKey = CMS_ENCRYPTION_KEY.trim();
-    if (normalizedKey.length === 0) {
-      throw new Error("CMS_ENCRYPTION_KEY must be a non-empty base64 string");
-    }
-    try {
-      const raw = typeof Buffer !== "undefined" ? Buffer.from(CMS_ENCRYPTION_KEY, "base64") : new Uint8Array(
-        atob(CMS_ENCRYPTION_KEY).split("").map((c) => c.charCodeAt(0))
-      );
-      if (raw.byteLength !== 16) {
-        throw new Error(`CMS_ENCRYPTION_KEY must decode to 16 bytes, got ${raw.byteLength}`);
-      }
-    } catch {
-      throw new Error("CMS_ENCRYPTION_KEY is not valid base64");
-    }
-    const clamp = (v, min, max) => Number.isSafeInteger(v) ? Math.min(max, Math.max(min, v)) : min;
-    const env = (k) => typeof process !== "undefined" && process.env ? process.env[k] : void 0;
-    const parsedN = Number.parseInt(env("SCRYPT_N") ?? "", 10);
-    const parsedR = Number.parseInt(env("SCRYPT_R") ?? "", 10);
-    const parsedP = Number.parseInt(env("SCRYPT_P") ?? "", 10);
-    const toPowerOfTwo = (n) => 1 << Math.floor(Math.log2(n));
-    const baseN = clamp(parsedN, 16384, 1 << 20);
-    const SCRYPT_N = toPowerOfTwo(baseN);
-    const SCRYPT_R = clamp(parsedR, 8, 32);
-    const SCRYPT_P = clamp(parsedP, 1, 16);
-    const scrypt = ScryptConfigOptions({
-      encryptionKey: normalizedKey,
-      keylen: 64,
-      options: {
-        N: SCRYPT_N,
-        r: SCRYPT_R,
-        p: SCRYPT_P
-      }
-    });
+    const { scrypt } = makePasswordModConfig({ CMS_ENCRYPTION_KEY });
     const session = {
       ...defaultSessionConfig,
       ..._session ?? {}
@@ -69,5 +80,8 @@ class AuthKitOptions extends Context.Tag("AuthKitOptions")() {
 }
 export {
   AuthKitConfig,
-  AuthKitOptions
+  AuthKitOptions,
+  PasswordModConfigFinal,
+  PasswordModOptions,
+  makePasswordModConfig
 };

package/dist/index.d.ts

@@ -1,5 +1,15 @@
 import { Effect } from '@withstudiocms/effect';
-import { AuthKitOptions, type RawAuthKitConfig } from './config.js';
+import { AuthKitOptions, PasswordModConfigFinal, type RawAuthKitConfig } from './config.js';
+export { Password } from './modules/password.js';
+/**
+ * Creates a scrypt password hashing utility using the provided scrypt configuration.
+ *
+ * @param scrypt - The scrypt configuration object from `PasswordModConfigFinal`.
+ * @returns An Effect that provides an object with a `run` method for performing scrypt operations.
+ */
+export declare const makeScrypt: (config: PasswordModConfigFinal) => Effect.Effect.AsEffect<Effect.Effect<Effect.Effect<{
+    run: (password: import("crypto").BinaryLike) => Effect.Effect<Buffer<ArrayBufferLike>, import("@withstudiocms/effect/scrypt").ScryptError, never>;
+}, never, never>, Error, never>>;
 declare const AuthKit_base: Effect.Service.Class<AuthKit, "@withstudiocms/AuthKit", {
     readonly effect: Effect.Effect<{
         readonly Encryption: Effect.Effect<{
@@ -74,7 +84,7 @@ declare const AuthKit_base: Effect.Service.Class<AuthKit, "@withstudiocms/AuthKi
             readonly getUserPermissionLevel: (userData: import("./types.js").UserSessionData | import("./types.js").CombinedUserData | null) => Effect.Effect<import("./types.js").UserPermissionLevel, import("./errors.js").UserError, never>;
             readonly isUserAllowed: (userData: import("./types.js").UserSessionData | import("./types.js").CombinedUserData | null, requiredPerms: "owner" | "admin" | "editor" | "visitor" | "unknown") => Effect.Effect<boolean, import("./errors.js").UserError, never>;
         }, import("./errors.js").SessionError | import("./errors.js").UserError, never>;
-    }, never, AuthKitOptions>;
+    }, Error, AuthKitOptions>;
 }>;
 /**
  * The `AuthKit` service provides a collection of authentication utilities for use within the
@@ -126,4 +136,3 @@ export declare class AuthKit extends AuthKit_base {
      */
     static makeConfig: (config: RawAuthKitConfig) => import("effect/Layer").Layer<AuthKitOptions, never, never>;
 }
-export {};

package/dist/index.js

@@ -1,27 +1,34 @@
 import { Effect } from "@withstudiocms/effect";
 import { Scrypt as _Scrypt } from "@withstudiocms/effect/scrypt";
-import { AuthKitOptions } from "./config.js";
+import { AuthKitOptions, PasswordModConfigFinal } from "./config.js";
 import { _Encryption, _Password, _Session, _User } from "./modules/index.js";
+import { Password } from "./modules/password.js";
+const makeScrypt = Effect.fn(
+  (config) => Effect.try({
+    try: () => Effect.gen(function* () {
+      const { run } = yield* _Scrypt;
+      return { run };
+    }).pipe(Effect.provide(_Scrypt.makeLive(config.scrypt))),
+    catch: (error) => new Error(`Failed to create Scrypt instance: ${error.message}`)
+  })
+);
 class AuthKit extends Effect.Service()("@withstudiocms/AuthKit", {
   effect: Effect.gen(function* () {
     const { CMS_ENCRYPTION_KEY, scrypt, session, userTools } = yield* AuthKitOptions;
-    const Scrypt = Effect.withSpan("@withstudiocms/AuthKit.Scrypt")(
-      Effect.gen(function* () {
-        const { run } = yield* _Scrypt;
-        return { run };
-      }).pipe(Effect.provide(_Scrypt.makeLive(scrypt)))
+    const Scrypt = yield* Effect.withSpan("@withstudiocms/AuthKit.Scrypt")(
+      makeScrypt(PasswordModConfigFinal({ scrypt }))
     );
     const Encryption = Effect.withSpan("@withstudiocms/AuthKit.Encryption")(
       _Encryption(CMS_ENCRYPTION_KEY)
     );
-    const Password = Effect.withSpan("@withstudiocms/AuthKit.Password")(_Password(Scrypt));
+    const Password2 = Effect.withSpan("@withstudiocms/AuthKit.Password")(_Password(Scrypt));
     const Session = Effect.withSpan("@withstudiocms/AuthKit.Session")(_Session(session));
     const User = Effect.withSpan("@withstudiocms/AuthKit.User")(
       _User({ Scrypt, session, userTools })
     );
     return {
       Encryption,
-      Password,
+      Password: Password2,
       Session,
       User
     };
@@ -44,5 +51,7 @@ class AuthKit extends Effect.Service()("@withstudiocms/AuthKit", {
   static makeConfig = (config) => AuthKitOptions.Live(config);
 }
 export {
-  AuthKit
+  AuthKit,
+  Password,
+  makeScrypt
 };

package/dist/utils/unsafeCheck.d.ts

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/suspicious/noTsIgnore: Working with auto-generated modules */
 import { Effect } from '@withstudiocms/effect';
 declare const CheckIfUnsafe_base: Effect.Service.Class<CheckIfUnsafe, "studiocms/virtuals/auth/utils/unsafeCheck/CheckIfUnsafe", {
     readonly effect: Effect.Effect<{

package/dist/utils/user.js

@@ -41,6 +41,7 @@ const normalizeRank = (v) => {
     case "visitor":
     case "unknown":
       return v;
+    /* v8 ignore next 2 */
     default:
       return "unknown";
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withstudiocms/auth-kit",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Utilities for managing authentication",
   "author": {
     "name": "withstudiocms",
@@ -59,7 +59,7 @@
     "@oslojs/binary": "^1.0.0",
     "@oslojs/crypto": "^1.0.1",
     "@oslojs/encoding": "^1.1.0",
-    "@withstudiocms/effect": "0.1.0-beta.2"
+    "@withstudiocms/effect": "0.1.0-beta.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"
@@ -73,7 +73,7 @@
     "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'",
+    "test": "vitest",
     "typecheck": "tspc -p tsconfig.tspc.json"
   }
 }