alepha 0.15.0 → 0.15.2

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,6 +24,8 @@ 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 () => {
@@ -119,20 +122,35 @@ 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.)
+        request.user = await this.securityProvider.resolveUserFromServerRequest(
+          request,
+          { permission, realm },
         );
 
+        // No user resolved?
+        if (!request.user) {
+          // Route requires auth → throw
+          if (route.secure || 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
+          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,7 +161,7 @@ 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,
         });
@@ -209,19 +227,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 +273,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 +305,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;
 }
 

package/src/server/core/index.ts

@@ -114,14 +114,24 @@ export * from "./services/UserAgentParser.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides high-performance HTTP server capabilities with declarative routing and action primitives.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | epic | stable |
  *
- * The server module enables building REST APIs and web applications using `$route` and `$action` primitives
- * on class properties. It provides automatic request/response handling, schema validation, middleware support,
- * and seamless integration with other Alepha modules for a complete backend solution.
+ * Convention-driven HTTP server with automatic validation and type inference.
+ *
+ * **Features:**
+ * - Type-safe API endpoints with schema validation
+ * - Lower-level HTTP route definitions
+ * - Automatic request/response validation via TypeBox
+ * - Convention-based URL generation (`/api/{ActionName}`)
+ * - Direct invocation (`run()`) or HTTP (`fetch()`)
+ * - Built-in authentication integration
+ * - Multipart file upload handling
+ * - Content-type auto-negotiation (JSON, form-data, text)
+ * - HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
+ * - Error handling: BadRequestError, ValidationError, ForbiddenError, UnauthorizedError, ConflictError, NotFoundError
  *
- * @see {@link $route}
- * @see {@link $action}
  * @module alepha.server
  */
 export const AlephaServer = $module({
@@ -141,7 +151,7 @@ export const AlephaServer = $module({
     ServerRouterProvider,
   ],
   register: (alepha: Alepha) => {
-    if (!alepha.isServerless() && !alepha.isViteDev()) {
+    if (!alepha.isServerless()) {
       if (alepha.isBun()) {
         alepha.with({
           optional: true,

package/src/server/core/interfaces/ServerRequest.ts

@@ -83,7 +83,7 @@ export interface ServerRequest<
 
   /**
    * Client IP address.
-   * Will parse `X-Forwarded-For` header if present.
+   * Uses `X-Forwarded-For` header when `TRUST_PROXY=true`.
    */
   ip?: string;
 
@@ -100,6 +100,42 @@ export interface ServerRequest<
    */
   userAgent: UserAgentInfo;
 
+  /**
+   * Geolocation information derived from proxy headers.
+   * Available when behind Cloudflare, Vercel, or similar CDNs.
+   */
+  geo: RequestGeo;
+
+  /**
+   * Whether the request appears to be from a bot/crawler.
+   * Based on user-agent analysis.
+   */
+  isBot: boolean;
+
+  /**
+   * Whether the request is from a mobile device.
+   * Based on user-agent analysis.
+   */
+  isMobile: boolean;
+
+  /**
+   * Request protocol (http or https).
+   * Uses `X-Forwarded-Proto` header when behind a proxy.
+   */
+  protocol: "http" | "https";
+
+  /**
+   * Preferred language from `Accept-Language` header.
+   * Returns the first/most preferred language code (e.g., "en", "fr", "en-US").
+   */
+  language?: string;
+
+  /**
+   * Parsed referer information.
+   * Undefined if no Referer header or invalid URL.
+   */
+  referer?: RequestReferer;
+
   /**
    * Arbitrary metadata attached to the request. Can be used by middlewares to store information.
    */
@@ -208,3 +244,49 @@ export interface WebRequestEvent {
   req: Request;
   res?: Response;
 }
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Geolocation information from proxy headers (Cloudflare, Vercel, etc.)
+ */
+export interface RequestGeo {
+  /**
+   * ISO 3166-1 alpha-2 country code (e.g., "US", "FR", "JP").
+   */
+  country?: string;
+  /**
+   * City name (e.g., "San Francisco", "Paris").
+   */
+  city?: string;
+  /**
+   * Region/state (e.g., "California", "Île-de-France").
+   */
+  region?: string;
+  /**
+   * Latitude (if available).
+   */
+  latitude?: string;
+  /**
+   * Longitude (if available).
+   */
+  longitude?: string;
+}
+
+/**
+ * Parsed referer information.
+ */
+export interface RequestReferer {
+  /**
+   * Full referer URL.
+   */
+  url: string;
+  /**
+   * Hostname of the referer (e.g., "google.com").
+   */
+  hostname: string;
+  /**
+   * Path of the referer URL.
+   */
+  pathname: string;
+}

package/src/server/core/primitives/$action.spec.ts

@@ -1,5 +1,5 @@
 import { Alepha, t } from "alepha";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { describe, test } from "vitest";
 import { $action } from "../index.ts";