@withstudiocms/auth-kit 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present StudioCMS - withstudiocms (https://github.com/withstudiocms)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @withstudiocms/auth-kit
+
+Authentication Management utilities for StudioCMS
+
+## Example Astro DB Tables
+
+The following are example tables that would work with this auth-kit system. The same tables are used within StudioCMS.
+
+```ts
+import { defineTable, column, NOW } from 'astro:db';
+
+const Users = defineTable({
+	columns: {
+		id: column.text({ primaryKey: true }),
+		url: column.text({ optional: true }),
+		name: column.text(),
+		email: column.text({ unique: true, optional: true }),
+		avatar: column.text({
+			optional: true,
+			default: 'https://seccdn.libravatar.org/static/img/mm/80.png',
+		}),
+		username: column.text(),
+		password: column.text({ optional: true }),
+		updatedAt: column.date({ default: NOW, optional: true }),
+		createdAt: column.date({ default: NOW, optional: true }),
+		emailVerified: column.boolean({ default: false }),
+		notifications: column.text({ optional: true }),
+	},
+});
+
+const OAuthAccounts = defineTable({
+	columns: {
+		providerUserId: column.text({ primaryKey: true }),
+		provider: column.text(), // i.e: github, google, discord, auth0 (dynamic to allow new providers on the fly)
+		userId: column.text({ references: () => Users.columns.id }),
+	},
+});
+
+const Sessions = defineTable({
+	columns: {
+		id: column.text({ primaryKey: true }),
+		userId: column.text({ references: () => Users.columns.id, optional: false }),
+		expiresAt: column.date(),
+	},
+});
+
+const Permissions = defineTable({
+	columns: {
+		user: column.text({ references: () => Users.columns.id }),
+		rank: column.text({ enum: ['owner', 'admin', 'editor', 'visitor', 'unknown'] }),
+	},
+});
+```
+
+## License
+
+[MIT Licensed](./LICENSE)

package/dist/config.d.ts

@@ -0,0 +1,76 @@
+import { Brand, Context, Layer } from '@withstudiocms/effect';
+import { ScryptConfigOptions } from '@withstudiocms/effect/scrypt';
+import type { SessionConfig, UserTools } from './types.js';
+/**
+ * Represents the raw configuration object for the Auth Kit.
+ *
+ * @property CMS_ENCRYPTION_KEY - The encryption key used by the CMS for securing sensitive data.
+ * @property session - The required session configuration settings.
+ * @property userTools - The user tools configuration.
+ */
+export type RawAuthKitConfig = {
+    CMS_ENCRYPTION_KEY: string;
+    session: Required<SessionConfig>;
+    userTools: UserTools;
+};
+/**
+ * Configuration options for the AuthKit module.
+ *
+ * @property CMS_ENCRYPTION_KEY - The encryption key used for securing CMS data.
+ * @property scrypt - Configuration options for the scrypt password hashing algorithm.
+ * @property session - Required session configuration options.
+ * @property userTools - Tools and utilities related to user management.
+ * @remarks
+ * This type is branded as 'AuthKitConfig' to provide nominal typing.
+ */
+export type AuthKitConfig = {
+    CMS_ENCRYPTION_KEY: string;
+    scrypt: ScryptConfigOptions;
+    session: Required<SessionConfig>;
+    userTools: UserTools;
+} & Brand.Brand<'AuthKitConfig'>;
+/**
+ * A nominal type for the AuthKit configuration object.
+ *
+ * This constant uses the `Brand.nominal` utility to create a strongly-typed
+ * identifier for the `AuthKitConfig` type, ensuring type safety and preventing
+ * accidental misuse of configuration objects.
+ *
+ * @see AuthKitConfig
+ * @see Brand.nominal
+ */
+export declare const AuthKitConfig: Brand.Brand.Constructor<AuthKitConfig>;
+declare const AuthKitOptions_base: Context.TagClass<AuthKitOptions, "AuthKitOptions", AuthKitConfig>;
+/**
+ * Provides configuration options for the AuthKit module.
+ *
+ * @remarks
+ * This class extends a tagged context for dependency injection and configuration management.
+ *
+ * @example
+ * ```typescript
+ * const options = AuthKitOptions.Live({
+ *   CMS_ENCRYPTION_KEY: 'secret-key',
+ *   session: { ... },
+ *   userTools: { ... }
+ * });
+ * ```
+ */
+export declare class AuthKitOptions extends AuthKitOptions_base {
+    /**
+     * Creates a live instance of `AuthKitOptions` using the provided raw configuration.
+     *
+     * @param CMS_ENCRYPTION_KEY - The encryption key used for cryptographic operations.
+     * @param session - session configuration overrides.
+     * @param userTools - Tools or utilities related to user management.
+     * @returns A Layer that provides the configured `AuthKitOptions`.
+     *
+     * @remarks
+     * - Scrypt parameters (`N`, `r`, `p`) are read from environment variables (`SCRYPT_N`, `SCRYPT_R`, `SCRYPT_P`),
+     *   with sensible defaults and minimum values enforced for security.
+     * - The session configuration merges defaults with any provided overrides.
+     * - The returned Layer can be used for dependency injection in the application.
+     */
+    static Live: ({ CMS_ENCRYPTION_KEY, session: _session, userTools }: RawAuthKitConfig) => Layer.Layer<AuthKitOptions, never, never>;
+}
+export {};

package/dist/config.js

@@ -0,0 +1,73 @@
+import { Brand, Context, Layer } from "@withstudiocms/effect";
+import { ScryptConfigOptions } from "@withstudiocms/effect/scrypt";
+import { defaultSessionConfig } from "./utils/session.js";
+const AuthKitConfig = Brand.nominal();
+class AuthKitOptions extends Context.Tag("AuthKitOptions")() {
+  /**
+   * Creates a live instance of `AuthKitOptions` using the provided raw configuration.
+   *
+   * @param CMS_ENCRYPTION_KEY - The encryption key used for cryptographic operations.
+   * @param session - session configuration overrides.
+   * @param userTools - Tools or utilities related to user management.
+   * @returns A Layer that provides the configured `AuthKitOptions`.
+   *
+   * @remarks
+   * - Scrypt parameters (`N`, `r`, `p`) are read from environment variables (`SCRYPT_N`, `SCRYPT_R`, `SCRYPT_P`),
+   *   with sensible defaults and minimum values enforced for security.
+   * - The session configuration merges defaults with any provided overrides.
+   * - 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 session = {
+      ...defaultSessionConfig,
+      ..._session ?? {}
+    };
+    if (typeof session.cookieName !== "string" || session.cookieName.trim() === "") {
+      throw new Error("session.cookieName must be a non-empty string");
+    }
+    if (!Number.isSafeInteger(session.expTime) || session.expTime <= 0) {
+      throw new Error("session.expTime must be a positive integer (ms)");
+    }
+    return Layer.succeed(
+      this,
+      this.of(AuthKitConfig({ CMS_ENCRYPTION_KEY, scrypt, session, userTools }))
+    );
+  };
+}
+export {
+  AuthKitConfig,
+  AuthKitOptions
+};

package/dist/errors.d.ts

@@ -0,0 +1,158 @@
+import { Effect } from '@withstudiocms/effect';
+declare const EncryptionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "EncryptionError";
+} & Readonly<A>;
+/**
+ * Represents an error that occurs during encryption operations.
+ *
+ * @extends Data.TaggedError<'EncryptionError'>
+ * @template { cause: unknown } - The shape of the error details.
+ *
+ * @property {unknown} cause - The underlying cause of the encryption error.
+ */
+export declare class EncryptionError extends EncryptionError_base<{
+    cause: unknown;
+}> {
+}
+declare const DecryptionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DecryptionError";
+} & Readonly<A>;
+/**
+ * Represents an error that occurs during the decryption process.
+ *
+ * @extends Data.TaggedError
+ * @tag DecryptionError
+ * @property {unknown} cause - The underlying cause of the decryption failure.
+ */
+export declare class DecryptionError extends DecryptionError_base<{
+    cause: unknown;
+}> {
+}
+declare const PasswordError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PasswordError";
+} & Readonly<A>;
+/**
+ * PasswordError is a custom error class for handling password-related errors.
+ * It extends the TaggedError class from the Data module, allowing for structured error handling.
+ */
+export declare class PasswordError extends PasswordError_base<{
+    cause?: unknown;
+    message?: string;
+}> {
+}
+declare const CheckIfUnsafeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CheckIfUnsafeError";
+} & Readonly<A>;
+/**
+ * Error thrown when a safety check fails, indicating an unsafe condition.
+ *
+ * @extends Data.TaggedError
+ * @template {object} T - The shape of the error data.
+ * @property {string} message - A descriptive message explaining why the error was thrown.
+ */
+export declare class CheckIfUnsafeError extends CheckIfUnsafeError_base<{
+    message: string;
+}> {
+}
+declare const SessionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SessionError";
+} & Readonly<A>;
+/**
+ * Represents an error related to session handling within the authentication kit.
+ *
+ * @extends {Data.TaggedError<'SessionError', { cause: unknown }>}
+ *
+ * @example
+ * throw new SessionError({ cause: someError });
+ *
+ * @property {unknown} cause - The underlying cause of the session error.
+ */
+export declare class SessionError extends SessionError_base<{
+    cause: unknown;
+}> {
+}
+declare const UserError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "UserError";
+} & Readonly<A>;
+/**
+ * Represents an error related to user operations within the authentication kit.
+ *
+ * @extends Data.TaggedError
+ * @template { cause: unknown } - The shape of the error details.
+ *
+ * @example
+ * throw new UserError({ cause: someError });
+ */
+export declare class UserError extends UserError_base<{
+    cause: unknown;
+}> {
+}
+/**
+ * Executes a function within an Effect context, capturing any thrown errors as an `EncryptionError`.
+ *
+ * @template A - The return type of the function to execute.
+ * @param _try - A function that may throw an error.
+ * @returns An `Effect` that yields the result of the function or an `EncryptionError` if an exception is thrown.
+ */
+export declare const useEncryptionError: <A>(_try: () => A) => Effect.Effect<A, EncryptionError>;
+/**
+ * Executes the provided function within an Effect context, mapping any thrown error
+ * to a `DecryptionError`.
+ *
+ * @typeParam A - The type of the value returned by the function.
+ * @param _try - A function that may throw an error during execution.
+ * @returns An `Effect` that yields the result of the function or a `DecryptionError` if an error is thrown.
+ */
+export declare const useDecryptionError: <A>(_try: () => A) => Effect.Effect<A, DecryptionError>;
+/**
+ * Executes a function that may throw and wraps any thrown error in a `PasswordError`.
+ *
+ * @template A - The return type of the function to execute.
+ * @param _try - A function that may throw an error.
+ * @returns An `Effect` that yields the result of the function or a `PasswordError` if an error is thrown.
+ */
+export declare const usePasswordError: <A>(_try: () => A) => Effect.Effect<A, PasswordError>;
+/**
+ * Executes a function within an Effect, mapping any thrown error to a `SessionError`.
+ *
+ * @template A - The return type of the function to execute.
+ * @param _try - A function that returns a value of type `A`. If this function throws, the error is caught and wrapped in a `SessionError`.
+ * @returns An `Effect` that yields the result of `_try` or fails with a `SessionError` if an error is thrown.
+ */
+export declare const useSessionError: <A>(_try: () => A) => Effect.Effect<A, SessionError>;
+/**
+ * Wraps an asynchronous function in an Effect that captures any thrown errors
+ * and converts them into a `SessionError`.
+ *
+ * @template A The type of the resolved value from the promise.
+ * @param _try - A function that returns a promise to be executed.
+ * @returns An `Effect` that resolves with the value of the promise or fails with a `SessionError`.
+ */
+export declare const useSessionErrorPromise: <A>(_try: () => Promise<A>) => Effect.Effect<A, SessionError>;
+/**
+ * Executes a provided function within an Effect, catching any thrown errors and wrapping them
+ * in a `CheckIfUnsafeError` with a prefixed message.
+ *
+ * @template A - The return type of the function to execute.
+ * @param _try - A function to execute that may throw an error.
+ * @param prefix - A string to prefix to the error message if an error is caught.
+ * @returns An Effect that yields the result of the function or a `CheckIfUnsafeError` if an error occurs.
+ */
+export declare const useUnsafeCheckError: <A>(_try: () => A, prefix: string) => Effect.Effect<A, CheckIfUnsafeError>;
+/**
+ * Executes a function within an Effect, mapping any thrown error to a `UserError`.
+ *
+ * @typeParam A - The return type of the function to execute.
+ * @param _try - A function to execute that may throw an error.
+ * @returns An `Effect` that yields the result of the function or a `UserError` if an error is thrown.
+ */
+export declare const useUserError: <A>(_try: () => A) => Effect.Effect<A, UserError>;
+/**
+ * Wraps a promise-returning function in an Effect, mapping any thrown error to a `UserError`.
+ *
+ * @template A The type of the resolved value from the promise.
+ * @param _try - A function that returns a promise of type `A`.
+ * @returns An `Effect` that resolves with the value of type `A` or fails with a `UserError`.
+ */
+export declare const useUserErrorPromise: <A>(_try: () => Promise<A>) => Effect.Effect<A, UserError>;
+export {};

package/dist/errors.js

@@ -0,0 +1,61 @@
+import { Data, Effect } from "@withstudiocms/effect";
+class EncryptionError extends Data.TaggedError("EncryptionError") {
+}
+class DecryptionError extends Data.TaggedError("DecryptionError") {
+}
+class PasswordError extends Data.TaggedError("PasswordError") {
+}
+class CheckIfUnsafeError extends Data.TaggedError("CheckIfUnsafeError") {
+}
+class SessionError extends Data.TaggedError("SessionError") {
+}
+class UserError extends Data.TaggedError("UserError") {
+}
+const useEncryptionError = (_try) => Effect.try({
+  try: _try,
+  catch: (cause) => new EncryptionError({ cause })
+});
+const useDecryptionError = (_try) => Effect.try({
+  try: _try,
+  catch: (cause) => new DecryptionError({ cause })
+});
+const usePasswordError = (_try) => Effect.try({
+  try: _try,
+  catch: (cause) => new PasswordError({ cause })
+});
+const useSessionError = (_try) => Effect.try({
+  try: _try,
+  catch: (cause) => new SessionError({ cause })
+});
+const useSessionErrorPromise = (_try) => Effect.tryPromise({
+  try: _try,
+  catch: (cause) => new SessionError({ cause })
+});
+const useUnsafeCheckError = (_try, prefix) => Effect.try({
+  try: _try,
+  catch: (cause) => new CheckIfUnsafeError({ message: `${prefix}: ${cause}` })
+});
+const useUserError = (_try) => Effect.try({
+  try: _try,
+  catch: (cause) => new UserError({ cause })
+});
+const useUserErrorPromise = (_try) => Effect.tryPromise({
+  try: _try,
+  catch: (cause) => new UserError({ cause })
+});
+export {
+  CheckIfUnsafeError,
+  DecryptionError,
+  EncryptionError,
+  PasswordError,
+  SessionError,
+  UserError,
+  useDecryptionError,
+  useEncryptionError,
+  usePasswordError,
+  useSessionError,
+  useSessionErrorPromise,
+  useUnsafeCheckError,
+  useUserError,
+  useUserErrorPromise
+};

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import { Effect } from '@withstudiocms/effect';
+import { AuthKitOptions, type RawAuthKitConfig } from './config.js';
+declare const AuthKit_base: Effect.Service.Class<AuthKit, "@withstudiocms/AuthKit", {
+    readonly effect: Effect.Effect<{
+        readonly Encryption: Effect.Effect<{
+            readonly encrypt: (data: Uint8Array<ArrayBufferLike>) => Effect.Effect.AsEffect<Effect.Effect<Uint8Array<ArrayBufferLike>, import("./errors.js").EncryptionError, never>>;
+            readonly encryptToString: (data: string) => Effect.Effect<Uint8Array<ArrayBufferLike>, import("./errors.js").EncryptionError, never>;
+            readonly decrypt: (data: Uint8Array<ArrayBufferLike>) => Effect.Effect.AsEffect<Effect.Effect<Uint8Array<ArrayBufferLike>, import("./errors.js").DecryptionError, never>>;
+            readonly decryptToString: (data: Uint8Array<ArrayBufferLike>) => Effect.Effect<string, import("./errors.js").DecryptionError, never>;
+        }, import("./errors.js").EncryptionError, never>;
+        readonly Password: Effect.Effect<{
+            readonly hashPassword: (password: string, _salt?: string | undefined) => Effect.Effect<string, import("@withstudiocms/effect/scrypt").ScryptError, never>;
+            readonly verifyPasswordHash: (hash: string, password: string) => Effect.Effect<boolean, import("@withstudiocms/effect/scrypt").ScryptError | import("./errors.js").PasswordError, never>;
+            readonly verifyPasswordStrength: (pass: string) => Effect.Effect<string | true, import("./errors.js").PasswordError | import("./errors.js").CheckIfUnsafeError | import("@effect/platform/HttpClientError").ResponseError, never>;
+        }, never, never>;
+        readonly Session: Effect.Effect<{
+            readonly generateSessionToken: () => Effect.Effect.AsEffect<Effect.Effect<string, import("./errors.js").SessionError, never>>;
+            readonly createSession: (token: string, userId: string) => Effect.Effect<import("./types.js").UserSession, import("./errors.js").SessionError, never>;
+            readonly validateSessionToken: (token: string) => Effect.Effect<import("./types.js").SessionValidationResult, import("./errors.js").SessionError, never>;
+            readonly invalidateSession: (sessionId: string) => Effect.Effect.AsEffect<Effect.Effect<void, import("./errors.js").SessionError, never>>;
+            readonly setSessionTokenCookie: (context: import("astro").APIContext<Record<string, any>, Record<string, string | undefined>> | import("astro").AstroGlobal<Record<string, any>, import("astro/runtime/server/index.js").AstroComponentFactory, Record<string, string | undefined>>, token: string, expiresAt: Date, secure?: boolean | undefined) => Effect.Effect.AsEffect<Effect.Effect<void, import("./errors.js").SessionError, never>>;
+            readonly deleteSessionTokenCookie: (context: import("astro").APIContext<Record<string, any>, Record<string, string | undefined>> | import("astro").AstroGlobal<Record<string, any>, import("astro/runtime/server/index.js").AstroComponentFactory, Record<string, string | undefined>>, secure?: boolean | undefined) => Effect.Effect.AsEffect<Effect.Effect<void, import("./errors.js").SessionError, never>>;
+            readonly setOAuthSessionTokenCookie: (context: import("astro").APIContext<Record<string, any>, Record<string, string | undefined>> | import("astro").AstroGlobal<Record<string, any>, import("astro/runtime/server/index.js").AstroComponentFactory, Record<string, string | undefined>>, key: string, value: string, secure?: boolean | undefined) => Effect.Effect.AsEffect<Effect.Effect<void, import("./errors.js").SessionError, never>>;
+            readonly createUserSession: (userId: string, context: import("astro").APIContext<Record<string, any>, Record<string, string | undefined>> | import("astro").AstroGlobal<Record<string, any>, import("astro/runtime/server/index.js").AstroComponentFactory, Record<string, string | undefined>>, secure?: boolean | undefined) => Effect.Effect<void, import("./errors.js").SessionError, never>;
+        }, import("./errors.js").SessionError, never>;
+        readonly User: Effect.Effect<{
+            readonly verifyUsernameInput: (username: string) => Effect.Effect<string | true, import("./errors.js").CheckIfUnsafeError | import("./errors.js").UserError, never>;
+            readonly createUserAvatar: (email: string) => Effect.Effect.AsEffect<Effect.Effect<string, import("./errors.js").UserError, never>>;
+            readonly createLocalUser: (name: string, username: string, email: string, password: string) => Effect.Effect<{
+                name: string;
+                username: string;
+                id: string;
+                url: string | null;
+                email: string | null;
+                avatar: string | null;
+                password: string | null;
+                updatedAt: Date | null;
+                createdAt: Date | null;
+                emailVerified: boolean;
+                notifications: string | null;
+            }, import("@withstudiocms/effect/scrypt").ScryptError | import("./errors.js").UserError, never>;
+            readonly createOAuthUser: (data: import("./types.js").UserData, oAuthFields: {
+                provider: string;
+                providerUserId: string;
+            }) => Effect.Effect<{
+                name: string;
+                username: string;
+                id: string;
+                url: string | null;
+                email: string | null;
+                avatar: string | null;
+                password: string | null;
+                updatedAt: Date | null;
+                createdAt: Date | null;
+                emailVerified: boolean;
+                notifications: string | null;
+            }, import("./errors.js").UserError, never>;
+            readonly updateUserPassword: (userId: string, password: string) => Effect.Effect<{
+                name: string;
+                username: string;
+                id: string;
+                url: string | null;
+                email: string | null;
+                avatar: string | null;
+                password: string | null;
+                updatedAt: Date | null;
+                createdAt: Date | null;
+                emailVerified: boolean;
+                notifications: string | null;
+            }, import("@withstudiocms/effect/scrypt").ScryptError | import("./errors.js").UserError, never>;
+            readonly getUserPasswordHash: (userId: string) => Effect.Effect<string, import("./errors.js").UserError, never>;
+            readonly getUserFromEmail: (email: string) => Effect.Effect.AsEffect<Effect.Effect<import("./types.js").CombinedUserData | null | undefined, import("./errors.js").UserError, never>>;
+            readonly getUserData: (context: import("astro").APIContext<Record<string, any>, Record<string, string | undefined>> | import("astro").AstroGlobal<Record<string, any>, import("astro/runtime/server/index.js").AstroComponentFactory, Record<string, string | undefined>>) => Effect.Effect<import("./types.js").UserSessionData, import("./errors.js").SessionError | import("./errors.js").UserError, never>;
+            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>;
+}>;
+/**
+ * The `AuthKit` service provides a collection of authentication utilities for use within the
+ * @withstudiocms ecosystem. It exposes encryption, password management, session management,
+ * and user management utilities, all configured via dependency injection.
+ *
+ * @remarks
+ * This service is built on top of the Effect system, allowing for composable and testable
+ * authentication logic. Each utility is wrapped with tracing spans for observability.
+ *
+ * @example
+ * ```typescript
+ * const authKit = AuthKit.makeConfig({
+ *   CMS_ENCRYPTION_KEY: 'secret-key',
+ *   session: ...,
+ *   userTools: ...
+ * });
+ * ```
+ *
+ * @property Encryption - Provides encryption and decryption utilities using the configured key.
+ * @property Password - Utilities for password hashing and verification using Scrypt.
+ * @property Session - Session management utilities for handling user sessions.
+ * @property User - User management utilities, including authentication and user lookup.
+ *
+ * @method static makeConfig
+ * Creates a live configuration for the AuthKit service using the provided raw configuration.
+ *
+ * @see AuthKitOptions
+ * @see _Scrypt
+ * @see _Encryption
+ * @see _Password
+ * @see _Session
+ * @see _User
+ */
+export declare class AuthKit extends AuthKit_base {
+    /**
+     * Creates a live instance of `AuthKitOptions` using the provided raw configuration.
+     *
+     * @param CMS_ENCRYPTION_KEY - The encryption key used for cryptographic operations.
+     * @param session - session configuration overrides.
+     * @param userTools - Tools or utilities related to user management.
+     * @returns A Layer that provides the configured `AuthKitOptions`.
+     *
+     * @remarks
+     * - Scrypt parameters (`N`, `r`, `p`) are read from environment variables (`SCRYPT_N`, `SCRYPT_R`, `SCRYPT_P`),
+     *   with sensible defaults and minimum values enforced for security.
+     * - The session configuration merges defaults with any provided overrides.
+     * - The returned Layer can be used for dependency injection in the application.
+     */
+    static makeConfig: (config: RawAuthKitConfig) => import("effect/Layer").Layer<AuthKitOptions, never, never>;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,48 @@
+import { Effect } from "@withstudiocms/effect";
+import { Scrypt as _Scrypt } from "@withstudiocms/effect/scrypt";
+import { AuthKitOptions } from "./config.js";
+import { _Encryption, _Password, _Session, _User } from "./modules/index.js";
+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 Encryption = Effect.withSpan("@withstudiocms/AuthKit.Encryption")(
+      _Encryption(CMS_ENCRYPTION_KEY)
+    );
+    const Password = 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,
+      Session,
+      User
+    };
+  })
+}) {
+  /**
+   * Creates a live instance of `AuthKitOptions` using the provided raw configuration.
+   *
+   * @param CMS_ENCRYPTION_KEY - The encryption key used for cryptographic operations.
+   * @param session - session configuration overrides.
+   * @param userTools - Tools or utilities related to user management.
+   * @returns A Layer that provides the configured `AuthKitOptions`.
+   *
+   * @remarks
+   * - Scrypt parameters (`N`, `r`, `p`) are read from environment variables (`SCRYPT_N`, `SCRYPT_R`, `SCRYPT_P`),
+   *   with sensible defaults and minimum values enforced for security.
+   * - The session configuration merges defaults with any provided overrides.
+   * - The returned Layer can be used for dependency injection in the application.
+   */
+  static makeConfig = (config) => AuthKitOptions.Live(config);
+}
+export {
+  AuthKit
+};

package/dist/modules/encryption.d.ts

@@ -0,0 +1,22 @@
+import { Effect } from '@withstudiocms/effect';
+/**
+ * Factory function to create an encryption module using AES-128-GCM.
+ *
+ * @param CMS_ENCRYPTION_KEY - The base64-encoded encryption key to use for encryption and decryption.
+ * @returns An Effect that yields an object containing encryption and decryption utilities:
+ * - `encrypt`: Encrypts a Uint8Array and returns the encrypted data as a Uint8Array.
+ * - `encryptToString`: Encrypts a string and returns the encrypted data as a Uint8Array.
+ * - `decrypt`: Decrypts an encrypted Uint8Array and returns the decrypted data as a Uint8Array.
+ * - `decryptToString`: Decrypts an encrypted Uint8Array and returns the decrypted data as a string.
+ *
+ * @remarks
+ * The encrypted data format is: [IV (16 bytes)] + [encrypted content] + [auth tag (16 bytes)].
+ * The encryption key must be a valid base64-encoded string suitable for AES-128-GCM.
+ * Throws errors if encryption or decryption fails, or if the input data is invalid.
+ */
+export declare const Encryption: (CMS_ENCRYPTION_KEY: string) => Effect.Effect<{
+    readonly encrypt: (data: Uint8Array<ArrayBufferLike>) => Effect.Effect.AsEffect<Effect.Effect<Uint8Array<ArrayBufferLike>, import("../errors.js").EncryptionError, never>>;
+    readonly encryptToString: (data: string) => Effect.Effect<Uint8Array<ArrayBufferLike>, import("../errors.js").EncryptionError, never>;
+    readonly decrypt: (data: Uint8Array<ArrayBufferLike>) => Effect.Effect.AsEffect<Effect.Effect<Uint8Array<ArrayBufferLike>, import("../errors.js").DecryptionError, never>>;
+    readonly decryptToString: (data: Uint8Array<ArrayBufferLike>) => Effect.Effect<string, import("../errors.js").DecryptionError, never>;
+}, import("../errors.js").EncryptionError, never>;