alepha 0.15.1 → 0.15.3

package/src/security/primitives/$issuer.ts

@@ -5,8 +5,10 @@ import {
   type DurationLike,
 } from "alepha/datetime";
 import { $logger } from "alepha/logger";
+import type { ServerRequest } from "alepha/server";
 import type { JSONWebKeySet, JWTPayload } from "jose";
 import { SecurityError } from "../errors/SecurityError.ts";
+import type { IssuerResolver } from "../interfaces/IssuerResolver.ts";
 import { JwtProvider } from "../providers/JwtProvider.ts";
 import { SecurityProvider } from "../providers/SecurityProvider.ts";
 import type { Role } from "../schemas/roleSchema.ts";
@@ -50,6 +52,11 @@ export type IssuerPrimitiveOptions = {
    * Parse the JWT payload to create a user account info.
    */
   profile?: (jwtPayload: Record<string, any>) => UserAccount;
+
+  /**
+   * Custom resolvers (in addition to default JWT resolver).
+   */
+  resolvers?: IssuerResolver[];
 } & (IssuerInternal | IssuerExternal);
 
 export interface IssuerSettings {
@@ -147,7 +154,55 @@ export class IssuerPrimitive extends Primitive<IssuerPrimitiveOptions> {
       profile: this.options.profile,
       secret: "jwks" in this.options ? this.options.jwks : this.options.secret,
       roles,
+      resolvers: [],
     });
+
+    // Register custom resolvers first (they usually have lower priority)
+    for (const resolver of this.options.resolvers ?? []) {
+      this.registerResolver(resolver);
+    }
+
+    // Register default JWT resolver (priority 100)
+    this.registerResolver(this.createJwtResolver());
+  }
+
+  /**
+   * Creates the default JWT resolver.
+   */
+  protected createJwtResolver(): IssuerResolver {
+    return {
+      priority: 100,
+      onRequest: async (req: ServerRequest) => {
+        const auth = req.headers.authorization;
+        if (!auth?.startsWith("Bearer ")) {
+          return null;
+        }
+
+        const token = auth.slice(7);
+
+        // Check if it looks like a JWT (has dots)
+        if (!token.includes(".")) {
+          return null;
+        }
+
+        // Parse and validate JWT
+        const { result } = await this.jwt.parse(token, this.name);
+
+        // Extract user info from JWT payload
+        return this.securityProvider.createUserFromPayload(
+          result.payload,
+          this.name,
+        );
+      },
+    };
+  }
+
+  /**
+   * Register a resolver to this issuer.
+   * Resolvers are sorted by priority (lower = first).
+   */
+  public registerResolver(resolver: IssuerResolver): void {
+    this.securityProvider.registerResolver(resolver, this.name);
   }
 
   /**

package/src/security/providers/SecurityProvider.ts

@@ -15,6 +15,7 @@ import { InvalidPermissionError } from "../errors/InvalidPermissionError.ts";
 import { InvalidTokenError } from "../errors/InvalidTokenError.ts";
 import { RealmNotFoundError } from "../errors/RealmNotFoundError.ts";
 import { SecurityError } from "../errors/SecurityError.ts";
+import type { IssuerResolver, UserInfo } from "../interfaces/IssuerResolver.ts";
 import type { UserAccountToken } from "../interfaces/UserAccountToken.ts";
 import type { Permission } from "../schemas/permissionSchema.ts";
 import type { Role } from "../schemas/roleSchema.ts";
@@ -90,10 +91,46 @@ export class SecurityProvider {
             typeof realm.secret === "function" ? realm.secret() : realm.secret;
           this.jwt.setKeyLoader(realm.name, secret);
         }
+
+        // Register default JWT resolver for realms without resolvers
+        if (!realm.resolvers || realm.resolvers.length === 0) {
+          this.registerResolver(
+            this.createDefaultJwtResolver(realm.name),
+            realm.name,
+          );
+        }
       }
     },
   });
 
+  /**
+   * Creates a default JWT resolver for a realm.
+   */
+  protected createDefaultJwtResolver(realmName: string): IssuerResolver {
+    return {
+      priority: 100,
+      onRequest: async (req) => {
+        const auth = req.headers.authorization;
+        if (!auth?.startsWith("Bearer ")) {
+          return null;
+        }
+
+        const token = auth.slice(7);
+
+        // Check if it looks like a JWT (has dots)
+        if (!token.includes(".")) {
+          return null;
+        }
+
+        // Parse and validate JWT
+        const { result } = await this.jwt.parse(token, realmName);
+
+        // Extract user info from JWT payload
+        return this.createUserFromPayload(result.payload, realmName);
+      },
+    };
+  }
+
   /**
    * Adds a role to one or more realms.
    *
@@ -305,6 +342,143 @@ export class SecurityProvider {
     };
   }
 
+  /**
+   * Generic user creation from any source (JWT, API key, etc.).
+   * Handles permission checking, ownership, default roles.
+   */
+  public createUser(
+    userInfo: UserInfo,
+    options: {
+      realm?: string;
+      permission?: Permission | string;
+    } = {},
+  ): UserAccountToken {
+    const realmRoles = this.getRoles(options.realm).filter((it) => it.default);
+    const roles = [...(userInfo.roles ?? [])];
+
+    // Add default roles
+    for (const role of realmRoles) {
+      if (!roles.includes(role.name)) {
+        roles.push(role.name);
+      }
+    }
+
+    let ownership: string | boolean | undefined;
+
+    // Permission check
+    if (options.permission) {
+      const check = this.checkPermission(options.permission, ...roles);
+      if (!check.isAuthorized) {
+        throw new SecurityError(
+          `User is not allowed to access '${this.permissionToString(options.permission)}'`,
+        );
+      }
+      ownership = check.ownership;
+    }
+
+    return {
+      ...userInfo,
+      roles,
+      ownership,
+      realm: options.realm,
+    };
+  }
+
+  /**
+   * Register a resolver to a realm.
+   * Resolvers are sorted by priority (lower = first).
+   */
+  public registerResolver(resolver: IssuerResolver, realmName?: string): void {
+    const realm = this.getRealm(realmName);
+    if (!realm.resolvers) {
+      realm.resolvers = [];
+    }
+
+    realm.resolvers.push(resolver);
+    realm.resolvers.sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+  }
+
+  /**
+   * Get a realm by name.
+   * Throws if realm not found.
+   */
+  public getRealm(realmName?: string): Realm {
+    const realm = realmName
+      ? this.realms.find((it) => it.name === realmName)
+      : this.realms[0];
+
+    if (!realm) {
+      throw new RealmNotFoundError(realmName ?? "default");
+    }
+
+    return realm;
+  }
+
+  /**
+   * Resolve user from request using registered resolvers.
+   * Returns undefined if no resolver could authenticate (no auth provided).
+   * Throws UnauthorizedError if auth was provided but invalid.
+   *
+   * Note: This method tries resolvers from ALL realms to find a match,
+   * regardless of the `realm` option. The `realm` option is only used for
+   * permission checking after the user is resolved.
+   */
+  public async resolveUserFromServerRequest(
+    req: { url: URL | string; headers: { authorization?: string } },
+    options: {
+      realm?: string;
+      permission?: Permission | string;
+    } = {},
+  ): Promise<UserAccountToken | undefined> {
+    // Collect all resolvers from all realms with their realm name
+    const allResolvers: Array<{
+      resolver: IssuerResolver;
+      realmName: string;
+    }> = [];
+
+    for (const realm of this.realms) {
+      for (const resolver of realm.resolvers ?? []) {
+        allResolvers.push({ resolver, realmName: realm.name });
+      }
+    }
+
+    // Sort by priority
+    allResolvers.sort(
+      (a, b) => (a.resolver.priority ?? 100) - (b.resolver.priority ?? 100),
+    );
+
+    // Try resolvers in priority order
+    for (const { resolver, realmName } of allResolvers) {
+      let userInfo: UserInfo | null;
+
+      try {
+        userInfo = await resolver.onRequest(req as any);
+      } catch {
+        // Resolver failed (e.g., wrong key), try next
+        continue;
+      }
+
+      if (userInfo) {
+        // User was resolved - now create user and check permissions
+        // (errors from createUser should propagate, not be caught)
+        const user = this.createUser(userInfo, {
+          realm: realmName,
+          permission: options.permission,
+        });
+
+        await this.alepha.events.emit("security:user:created", {
+          realm: realmName,
+          user,
+        });
+
+        return user;
+      }
+    }
+
+    // No resolver matched = no auth provided
+    return undefined;
+  }
+
   /**
    * Checks if the user has the specified permission.
    *
@@ -783,6 +957,11 @@ export interface Realm {
    * By default, SecurityProvider has his own implementation, but this method allow to override it.
    */
   profile?: (raw: Record<string, any>) => UserAccount;
+
+  /**
+   * Custom resolvers for this realm (sorted by priority).
+   */
+  resolvers?: IssuerResolver[];
 }
 
 export interface SecurityCheckResult {

package/src/security/providers/ServerBasicAuthProvider.ts

@@ -15,9 +15,13 @@ export interface BasicAuthOptions {
 }
 
 export interface BasicAuthPrimitiveConfig extends BasicAuthOptions {
-  /** Name identifier for this basic auth (default: property key) */
+  /**
+   * Name identifier for this basic auth (default: property key).
+   */
   name?: string;
-  /** Path patterns to match (supports wildcards like /devtools/*) */
+  /**
+   * Path patterns to match (supports wildcards like /devtools/*).
+   */
   paths?: string[];
 }
 

package/src/security/providers/ServerSecurityProvider.ts

@@ -7,6 +7,7 @@ import {
   type ServerRequest,
   UnauthorizedError,
 } from "alepha/server";
+import { InvalidTokenError } from "../errors/InvalidTokenError.ts";
 import type { UserAccountToken } from "../interfaces/UserAccountToken.ts";
 import type { Permission } from "../schemas/permissionSchema.ts";
 import { userAccountInfoSchema } from "../schemas/userAccountInfoSchema.ts";
@@ -23,30 +24,30 @@ export class ServerSecurityProvider {
   protected readonly jwtProvider = $inject(JwtProvider);
   protected readonly alepha = $inject(Alepha);
 
+  protected readonly resolvers: Array<ServerSecurityUserResolver> = [];
+
   protected readonly onConfigure = $hook({
     on: "configure",
     handler: async () => {
       for (const action of this.alepha.primitives($action)) {
         // -------------------------------------------------------------------------------------------------------------
-        // if the action is disabled or not secure, we do NOT create a permission for it
+        // Only create permission when secure is explicitly set to true
+        // Actions are public by default (like $route)
         // -------------------------------------------------------------------------------------------------------------
         if (
           action.options.disabled ||
-          action.options.secure === false ||
+          action.options.secure !== true ||
           this.securityProvider.getRealms().length === 0
         ) {
           continue;
         }
 
-        const secure = action.options.secure;
-        if (typeof secure !== "object") {
-          this.securityProvider.createPermission({
-            name: action.name,
-            group: action.group,
-            method: action.route.method,
-            path: action.route.path,
-          });
-        }
+        this.securityProvider.createPermission({
+          name: action.name,
+          group: action.group,
+          method: action.route.method,
+          path: action.route.path,
+        });
       }
     },
   });
@@ -56,10 +57,12 @@ export class ServerSecurityProvider {
   protected readonly onActionRequest = $hook({
     on: "action:onRequest",
     handler: async ({ action, request, options }) => {
-      // if you set explicitly secure: false, we assume you don't want any security check
-      // but only if no user is provided in options
-      if (action.options.secure === false && !options.user) {
-        this.log.trace("Skipping security check for route");
+      const secure = action.options.secure;
+
+      // Skip security if not explicitly enabled (secure: true or secure: { realm: ... })
+      // Actions are public by default (like $route)
+      if (secure !== true && typeof secure !== "object" && !options.user) {
+        this.log.trace("Skipping security check for action - not secured");
         return;
       }
 
@@ -90,7 +93,7 @@ export class ServerSecurityProvider {
           this.alepha.codec.decode(userAccountInfoSchema, request.user),
         );
       } catch (error) {
-        if (action.options.secure || permission) {
+        if (secure === true || typeof secure === "object" || permission) {
           throw error;
         }
         // else, we skip the security check
@@ -103,7 +106,7 @@ export class ServerSecurityProvider {
     on: "server:onRequest",
     priority: "last",
     handler: async ({ request, route }) => {
-      // if you set explicitly secure: false, we assume you don't want any security check
+      // Skip entirely only if explicitly disabled
       if (route.secure === false) {
         this.log.trace(
           "Skipping security check for route - explicitly disabled",
@@ -119,20 +122,39 @@ export class ServerSecurityProvider {
         .getPermissions()
         .find((it) => it.path === route.path && it.method === route.method);
 
-      if (!request.headers.authorization && !route.secure && !permission) {
-        this.log.trace(
-          "Skipping security check for route - no authorization header and not secure",
-        );
-        return;
-      }
+      const realm =
+        typeof route.secure === "object" ? route.secure.realm : undefined;
 
       try {
-        // set user to request
-        request.user = await this.securityProvider.createUserFromToken(
-          request.headers.authorization,
-          { permission },
+        // Try to resolve user (JWT, API key, etc.) - even for public routes (optional auth)
+        request.user = await this.securityProvider.resolveUserFromServerRequest(
+          request,
+          { permission, realm },
         );
 
+        // No user resolved?
+        if (!request.user) {
+          // Route requires auth → throw
+          if (
+            route.secure === true ||
+            typeof route.secure === "object" ||
+            permission
+          ) {
+            // Provide a more specific error message when no auth header was provided
+            if (!request.headers.authorization) {
+              throw new InvalidTokenError(
+                "Invalid authorization header, maybe token is missing ?",
+              );
+            }
+            throw new UnauthorizedError("Authentication required");
+          }
+          // Route is public → skip (but we tried to resolve user for optional auth)
+          this.log.trace(
+            "Skipping security check for route - no auth provided and not required",
+          );
+          return;
+        }
+
         if (typeof route.secure === "object") {
           this.check(request.user, route.secure);
         }
@@ -143,16 +165,20 @@ export class ServerSecurityProvider {
           this.alepha.codec.decode(userAccountInfoSchema, request.user),
         );
 
-        this.log.trace("User set from request token", {
+        this.log.trace("User set from request", {
           user: request.user,
           permission,
         });
       } catch (error) {
-        if (route.secure || permission) {
+        if (
+          route.secure === true ||
+          typeof route.secure === "object" ||
+          permission
+        ) {
           throw error;
         }
 
-        // else, we skip the security check
+        // else, we skip the security check (route is public)
         this.log.trace(
           "Skipping security check for route - error occurred",
           error,
@@ -209,19 +235,10 @@ export class ServerSecurityProvider {
     }
 
     if (!user) {
-      // in testing mode, we create a test user
-      if (this.alepha.isTest() && !("user" in options)) {
-        return this.createTestUser();
-      }
-
       throw new UnauthorizedError("User is required for calling this action");
     }
 
-    const roles =
-      user.roles ??
-      (this.alepha.isTest()
-        ? this.securityProvider.getRoles().map((role) => role.name)
-        : []);
+    const roles = user.roles ?? [];
     let ownership: boolean | string | undefined;
 
     if (permission) {
@@ -264,7 +281,8 @@ export class ServerSecurityProvider {
       }
 
       // skip helper if user is explicitly set to undefined
-      if ("user" in options && options.user === undefined) {
+      //if ("user" in options && options.user === undefined) {
+      if (!options.user) {
         return;
       }
 
@@ -295,3 +313,7 @@ export type ServerRouteSecure = {
   realm?: string;
   basic?: BasicAuthOptions;
 };
+
+export type ServerSecurityUserResolver = (
+  request: ServerRequest,
+) => Promise<UserAccountToken | undefined>;

package/src/server/auth/index.ts

@@ -29,16 +29,21 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Allow authentication services for server applications.
- * It provides login and logout functionalities.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
  *
- * There are multiple authentication providers available (e.g., Google, GitHub).
- * You can also delegate authentication to your own OIDC/OAuth2, for example using Keycloak or Auth0.
+ * OAuth2/OIDC authentication with social login providers.
  *
- * It's cookie-based and SSR friendly.
+ * **Features:**
+ * - OAuth authentication provider
+ * - Username/password authentication
+ * - Google OAuth integration
+ * - GitHub OAuth integration
+ * - Apple OAuth integration
+ * - Cookie-based, SSR-friendly authentication
+ * - Token management and refresh
  *
- * @see {@link $auth}
- * @see {@link ServerAuthProvider}
  * @module alepha.server.auth
  */
 export const AlephaServerAuth = $module({

package/src/server/cache/index.ts

@@ -9,31 +9,16 @@ export * from "./providers/ServerCacheProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Plugin for Alepha Server that provides server-side caching capabilities.
- * It uses the Alepha Cache module to cache responses from server actions ($action).
- * It also provides a ETag-based cache invalidation mechanism.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * @example
- * ```ts
- * import { Alepha } from "alepha";
- * import { $action } from "alepha/server";
- * import { AlephaServerCache } from "alepha/server/cache";
+ * ETag-based response caching.
  *
- * class ApiServer {
- *   hello = $action({
- *     cache: true,
- *     handler: () => "Hello, World!",
- *   });
- * }
+ * **Features:**
+ * - ETag generation and validation
+ * - Conditional request handling
  *
- * const alepha = Alepha.create()
- *   .with(AlephaServerCache)
- *   .with(ApiServer);
- *
- * run(alepha);
- * ```
- *
- * @see {@link ServerCacheProvider}
  * @module alepha.server.cache
  */
 export const AlephaServerCache = $module({

package/src/server/compress/index.ts

@@ -9,9 +9,17 @@ export * from "./providers/ServerCompressProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Plugin for Alepha Server that provides server-side compression capabilities.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * Compresses responses using gzip, brotli, or zstd based on the `Accept-Encoding` header.
+ * Response compression.
+ *
+ * **Features:**
+ * - Gzip compression
+ * - Brotli compression
+ *
+ * @module alepha.server.compress
  */
 export const AlephaServerCompress = $module({
   name: "alepha.server.compress",

package/src/server/cookies/index.ts

@@ -18,13 +18,15 @@ declare module "alepha/server" {
 }
 
 /**
- * Provides HTTP cookie management capabilities for server requests and responses with type-safe cookie primitives.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * The server-cookies module enables declarative cookie handling using the `$cookie` primitive on class properties.
- * It offers automatic cookie parsing, secure cookie configuration, and seamless integration with server routes
- * for managing user sessions, preferences, and authentication tokens.
+ * Server and browser-safe cookie handling.
+ *
+ * **Features:**
+ * - Cookie management on server and browser
  *
- * @see {@link $cookie}
  * @module alepha.server.cookies
  */
 export const AlephaServerCookies = $module({

package/src/server/cookies/primitives/$cookie.ts

@@ -23,37 +23,59 @@ export const $cookie = <T extends TSchema>(
 // ---------------------------------------------------------------------------------------------------------------------
 
 export interface CookiePrimitiveOptions<T extends TSchema> {
-  /** The schema for the cookie's value, used for validation and type safety. */
+  /**
+   * The schema for the cookie's value, used for validation and type safety.
+   */
   schema: T;
 
-  /** The name of the cookie. */
+  /**
+   * The name of the cookie.
+   */
   name?: string;
 
-  /** The cookie's path. Defaults to "/". */
+  /**
+   * The cookie's path. Defaults to "/".
+   */
   path?: string;
 
-  /** Time-to-live for the cookie. Maps to `Max-Age`. */
+  /**
+   * Time-to-live for the cookie. Maps to `Max-Age`.
+   */
   ttl?: DurationLike;
 
-  /** If true, the cookie is only sent over HTTPS. Defaults to true in production. */
+  /**
+   * If true, the cookie is only sent over HTTPS. Defaults to true in production.
+   */
   secure?: boolean;
 
-  /** If true, the cookie cannot be accessed by client-side scripts. */
+  /**
+   * If true, the cookie cannot be accessed by client-side scripts.
+   */
   httpOnly?: boolean;
 
-  /** SameSite policy for the cookie. Defaults to "lax". */
+  /**
+   * SameSite policy for the cookie. Defaults to "lax".
+   */
   sameSite?: "strict" | "lax" | "none";
 
-  /** The domain for the cookie. */
+  /**
+   * The domain for the cookie.
+   */
   domain?: string;
 
-  /** If true, the cookie value will be compressed using zlib. */
+  /**
+   * If true, the cookie value will be compressed using zlib.
+   */
   compress?: boolean;
 
-  /** If true, the cookie value will be encrypted. Requires `COOKIE_SECRET` env var. */
+  /**
+   * If true, the cookie value will be encrypted. Requires `COOKIE_SECRET` env var.
+   */
   encrypt?: boolean;
 
-  /** If true, the cookie will be signed to prevent tampering. Requires `COOKIE_SECRET` env var. */
+  /**
+   * If true, the cookie will be signed to prevent tampering. Requires `COOKIE_SECRET` env var.
+   */
   sign?: boolean;
 }