alepha 0.14.3 → 0.15.0

package/src/redis/providers/NodeRedisProvider.ts

@@ -4,19 +4,23 @@ import {
   type RedisClientType,
   type SetOptions,
 } from "@redis/client";
-import { $env, $hook, $inject, Alepha, type Static, t } from "alepha";
+import {
+  $env,
+  $hook,
+  $inject,
+  Alepha,
+  AlephaError,
+  type Static,
+  t,
+} from "alepha";
 import { $logger } from "alepha/logger";
 import { RedisProvider, type RedisSetOptions } from "./RedisProvider.ts";
 
 const envSchema = t.object({
-  REDIS_URL: t.optional(t.text()),
-  REDIS_PORT: t.integer({
-    default: "6379",
-  }),
-  REDIS_HOST: t.text({
-    default: "localhost",
+  REDIS_URL: t.text({
+    default: "redis://localhost:6379",
+    description: "Redis connection URL",
   }),
-  REDIS_PASSWORD: t.optional(t.text()),
 });
 
 declare module "alepha" {
@@ -39,10 +43,8 @@ export type NodeRedisClientOptions = Parameters<typeof createClient>[0];
  *
  * @example
  * ```ts
- * // Set REDIS_URL environment variable
- * // REDIS_URL=redis://localhost:6379
- *
- * // Or configure via REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
+ * // Set REDIS_URL environment variable (default: redis://localhost:6379)
+ * // REDIS_URL=redis://:password@myredis.example.com:6379
  *
  * // Or configure programmatically
  * alepha.with({
@@ -59,7 +61,7 @@ export class NodeRedisProvider extends RedisProvider {
 
   public get publisher(): NodeRedisClient {
     if (!this.client.isReady) {
-      throw new Error("Redis client is not ready");
+      throw new AlephaError("Redis client is not ready");
     }
 
     return this.client;
@@ -235,27 +237,7 @@ export class NodeRedisProvider extends RedisProvider {
    * Get the Redis connection URL.
    */
   protected getUrl(): string {
-    // Prefer REDIS_URL if set
-    if (this.env.REDIS_URL) {
-      return this.env.REDIS_URL;
-    }
-
-    // Build URL from components
-    const url = new URL("redis://127.0.0.1:6379");
-
-    if (this.env.REDIS_PASSWORD) {
-      url.password = this.env.REDIS_PASSWORD;
-    }
-
-    if (this.env.REDIS_HOST) {
-      url.hostname = this.env.REDIS_HOST;
-    }
-
-    if (this.env.REDIS_PORT) {
-      url.port = String(this.env.REDIS_PORT);
-    }
-
-    return url.toString();
+    return this.env.REDIS_URL;
   }
 
   /**

package/src/{server/security → security}/__tests__/BasicAuth.spec.ts

@@ -3,7 +3,7 @@ import { $action, AlephaServer } from "alepha/server";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   $basicAuth,
-  AlephaServerSecurity,
+  AlephaSecurity,
   ServerBasicAuthProvider,
 } from "../index.ts";
 
@@ -58,7 +58,7 @@ describe("Basic Authentication", () => {
   beforeEach(async () => {
     alepha = Alepha.create()
       .with(AlephaServer)
-      .with(AlephaServerSecurity)
+      .with(AlephaSecurity)
       .with(TestApp);
 
     await alepha.start();
@@ -269,7 +269,7 @@ describe("Basic Authentication", () => {
 
       const edgeAlepha = Alepha.create()
         .with(AlephaServer)
-        .with(AlephaServerSecurity)
+        .with(AlephaSecurity)
         .with(EdgeCaseApp);
 
       await edgeAlepha.start();
@@ -301,7 +301,7 @@ describe("Basic Authentication", () => {
 
       const emptyAlepha = Alepha.create()
         .with(AlephaServer)
-        .with(AlephaServerSecurity)
+        .with(AlephaSecurity)
         .with(EmptyPasswordApp);
 
       await emptyAlepha.start();
@@ -333,7 +333,7 @@ describe("Basic Authentication", () => {
 
       const specialAlepha = Alepha.create()
         .with(AlephaServer)
-        .with(AlephaServerSecurity)
+        .with(AlephaSecurity)
         .with(SpecialCharsApp);
 
       await specialAlepha.start();
@@ -365,7 +365,7 @@ describe("Basic Authentication", () => {
 
       const unicodeAlepha = Alepha.create()
         .with(AlephaServer)
-        .with(AlephaServerSecurity)
+        .with(AlephaSecurity)
         .with(UnicodeApp);
 
       await unicodeAlepha.start();
@@ -397,7 +397,7 @@ describe("Basic Authentication", () => {
 
       const unicodeAlepha = Alepha.create()
         .with(AlephaServer)
-        .with(AlephaServerSecurity)
+        .with(AlephaSecurity)
         .with(UnicodeApp);
 
       await unicodeAlepha.start();
@@ -434,7 +434,7 @@ describe("Basic Authentication", () => {
 
       const longAlepha = Alepha.create()
         .with(AlephaServer)
-        .with(AlephaServerSecurity)
+        .with(AlephaSecurity)
         .with(LongCredsApp);
 
       await longAlepha.start();
@@ -466,7 +466,7 @@ describe("Basic Authentication", () => {
 
       const emptyUserAlepha = Alepha.create()
         .with(AlephaServer)
-        .with(AlephaServerSecurity)
+        .with(AlephaSecurity)
         .with(EmptyUsernameApp);
 
       await emptyUserAlepha.start();
@@ -549,7 +549,7 @@ describe("Basic Authentication", () => {
 
       const wsAlepha = Alepha.create()
         .with(AlephaServer)
-        .with(AlephaServerSecurity)
+        .with(AlephaSecurity)
         .with(WhitespaceApp);
 
       await wsAlepha.start();
@@ -582,7 +582,7 @@ describe("Basic Authentication", () => {
 
       const wsAlepha = Alepha.create()
         .with(AlephaServer)
-        .with(AlephaServerSecurity)
+        .with(AlephaSecurity)
         .with(WhitespaceApp);
 
       await wsAlepha.start();

package/src/{server/security → security}/__tests__/ServerSecurityProvider-realm.spec.ts

@@ -1,14 +1,19 @@
 import { randomUUID } from "node:crypto";
 import { Alepha } from "alepha";
-import { $realm } from "alepha/security";
-import { $action, $route, ForbiddenError, ServerProvider } from "alepha/server";
+import {
+  $action,
+  $route,
+  AlephaServer,
+  ForbiddenError,
+  ServerProvider,
+} from "alepha/server";
 import { describe, expect, it } from "vitest";
-import { AlephaServerSecurity } from "../index.ts";
+import { $issuer, AlephaSecurity } from "../index.ts";
 
 describe("ServerSecurityProvider - Realm Protection", () => {
   it("should allow access when user belongs to the required realm", async () => {
     class TestApp {
-      realmA = $realm({
+      realmA = $issuer({
         secret: "test-realm-a",
         roles: [
           {
@@ -18,7 +23,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
         ],
       });
 
-      realmB = $realm({
+      realmB = $issuer({
         secret: "test-realm-b",
         roles: [
           {
@@ -43,7 +48,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
       });
     }
 
-    const alepha = Alepha.create().with(AlephaServerSecurity);
+    const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity);
     const app = alepha.inject(TestApp);
     await alepha.start();
 
@@ -85,7 +90,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
 
   it("should deny access when user does not belong to the required realm", async () => {
     class TestApp {
-      realmA = $realm({
+      realmA = $issuer({
         secret: "test-realm-a",
         roles: [
           {
@@ -95,7 +100,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
         ],
       });
 
-      realmB = $realm({
+      realmB = $issuer({
         secret: "test-realm-b",
         roles: [
           {
@@ -120,7 +125,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
       });
     }
 
-    const alepha = Alepha.create().with(AlephaServerSecurity);
+    const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity);
     const app = alepha.inject(TestApp);
     await alepha.start();
 
@@ -172,7 +177,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
 
   it("should work with actions when user has no realm attribute", async () => {
     class TestApp {
-      realmA = $realm({
+      realmA = $issuer({
         secret: "test-realm-a",
         roles: [
           {
@@ -188,7 +193,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
       });
     }
 
-    const alepha = Alepha.create().with(AlephaServerSecurity);
+    const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity);
     const app = alepha.inject(TestApp);
     await alepha.start();
 
@@ -215,7 +220,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
 
   it("should combine realm and permission checks", async () => {
     class TestApp {
-      realmA = $realm({
+      realmA = $issuer({
         secret: "test-realm-a",
         roles: [
           {
@@ -229,7 +234,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
         ],
       });
 
-      realmB = $realm({
+      realmB = $issuer({
         secret: "test-realm-b",
       });
 
@@ -248,7 +253,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
       });
     }
 
-    const alepha = Alepha.create().with(AlephaServerSecurity);
+    const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity);
     const app = alepha.inject(TestApp);
     await alepha.start();
 
@@ -336,7 +341,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
 
   it("should work with fetch requests when realm is valid", async () => {
     class TestApp {
-      realmA = $realm({
+      realmA = $issuer({
         secret: "test-realm-a",
         roles: [
           {
@@ -352,7 +357,7 @@ describe("ServerSecurityProvider - Realm Protection", () => {
       });
     }
 
-    const alepha = Alepha.create().with(AlephaServerSecurity);
+    const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity);
     const app = alepha.inject(TestApp);
     await alepha.start();
 

package/src/{server/security/providers → security/__tests__}/ServerSecurityProvider.spec.ts

@@ -1,15 +1,15 @@
 import { randomUUID } from "node:crypto";
 import { Alepha } from "alepha";
-import { $realm } from "alepha/security";
 import {
   $action,
+  AlephaServer,
   ForbiddenError,
   HttpError,
   ServerProvider,
   UnauthorizedError,
 } from "alepha/server";
 import { describe, expect, it } from "vitest";
-import { AlephaServerSecurity } from "../index.ts";
+import { $issuer, AlephaSecurity } from "../index.ts";
 
 describe("ServerSecurityProvider", () => {
   it("should protect action from unauthorized users", async () => {
@@ -19,7 +19,7 @@ describe("ServerSecurityProvider", () => {
       });
     }
 
-    const alepha = Alepha.create().with(AlephaServerSecurity);
+    const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity);
     const app = alepha.inject(TestApp);
     await alepha.start();
 
@@ -62,7 +62,7 @@ describe("ServerSecurityProvider", () => {
         group: "read",
         handler: () => "USER",
       });
-      realm = $realm({
+      issuer = $issuer({
         secret: "test",
         roles: [
           {
@@ -77,7 +77,7 @@ describe("ServerSecurityProvider", () => {
       });
     }
 
-    const alepha = Alepha.create().with(AlephaServerSecurity);
+    const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity);
     const app = alepha.inject(TestApp);
     await alepha.start();
 

package/src/security/index.browser.ts

@@ -11,3 +11,8 @@ export * from "./schemas/userAccountInfoSchema.ts";
 export const AlephaSecurity = $module({
   name: "alepha.security",
 });
+
+/**
+ * @deprecated Use `AlephaSecurity` instead. Server security providers are automatically registered when `AlephaServer` is available.
+ */
+export const AlephaServerSecurity = AlephaSecurity;

package/src/security/index.ts

@@ -1,27 +1,37 @@
-import { $module } from "alepha";
+import { $module, type Alepha } from "alepha";
+import { AlephaServer, type FetchOptions } from "alepha/server";
+import type { UserAccountToken } from "./interfaces/UserAccountToken.ts";
+import { $basicAuth } from "./primitives/$basicAuth.ts";
+import { $issuer } from "./primitives/$issuer.ts";
 import { $permission } from "./primitives/$permission.ts";
-import { $realm } from "./primitives/$realm.ts";
 import { $role } from "./primitives/$role.ts";
 import { CryptoProvider } from "./providers/CryptoProvider.ts";
 import { JwtProvider } from "./providers/JwtProvider.ts";
 import { SecurityProvider } from "./providers/SecurityProvider.ts";
+import { ServerBasicAuthProvider } from "./providers/ServerBasicAuthProvider.ts";
+import { ServerSecurityProvider } from "./providers/ServerSecurityProvider.ts";
 import type { UserAccount } from "./schemas/userAccountInfoSchema.ts";
 
 export * from "./errors/InvalidCredentialsError.ts";
 export * from "./errors/InvalidPermissionError.ts";
 export * from "./errors/SecurityError.ts";
 export * from "./interfaces/UserAccountToken.ts";
+export * from "./primitives/$basicAuth.ts";
+export * from "./primitives/$issuer.ts";
 export * from "./primitives/$permission.ts";
-export * from "./primitives/$realm.ts";
 export * from "./primitives/$role.ts";
 export * from "./primitives/$serviceAccount.ts";
 export * from "./providers/CryptoProvider.ts";
 export * from "./providers/JwtProvider.ts";
 export * from "./providers/SecurityProvider.ts";
+export * from "./providers/ServerBasicAuthProvider.ts";
+export * from "./providers/ServerSecurityProvider.ts";
 export * from "./schemas/permissionSchema.ts";
 export * from "./schemas/roleSchema.ts";
 export * from "./schemas/userAccountInfoSchema.ts";
 
+import type { ServerRouteSecure } from "./providers/ServerSecurityProvider.ts";
+
 declare module "alepha" {
   interface Hooks {
     "security:user:created": {
@@ -29,22 +39,95 @@ declare module "alepha" {
       user: UserAccount;
     };
   }
+
+  interface State {
+    /**
+     * Real (or fake) user account, used for internal actions.
+     *
+     * If you define this, you assume that all actions are executed by this user by default.
+     * > To force a different user, you need to pass it explicitly in the options.
+     */
+    "alepha.server.security.system.user"?: UserAccountToken;
+
+    /**
+     * The authenticated user account attached to the server request state.
+     *
+     * @internal
+     */
+    "alepha.server.request.user"?: UserAccount;
+  }
+}
+
+declare module "alepha/server" {
+  interface ServerRequest<TConfig> {
+    user?: UserAccountToken; // for all routes, user is maybe present
+  }
+
+  interface ServerActionRequest<TConfig> {
+    user: UserAccountToken; // for actions, user is always present
+  }
+
+  interface ServerRoute {
+    /**
+     * If true, the route will be protected by the security provider.
+     * All actions are secure by default, but you can disable it for specific actions.
+     */
+    secure?: boolean | ServerRouteSecure;
+  }
+
+  interface ClientRequestOptions extends FetchOptions {
+    /**
+     * Forward user from the previous request.
+     * If "system", use system user. @see {ServerSecurityProvider.localSystemUser}
+     * If "context", use the user from the current context (e.g. request).
+     *
+     * @default "system" if provided, else "context" if available.
+     */
+    user?: UserAccountToken | "system" | "context";
+  }
 }
 
 /**
  * Provides comprehensive authentication and authorization capabilities with JWT tokens, role-based access control, and user management.
  *
- * The security module enables building secure applications using primitives like `$realm`, `$role`, and `$permission`
+ * The security module enables building secure applications using primitives like `$issuer`, `$role`, and `$permission`
  * on class properties. It offers JWT-based authentication, fine-grained permissions, service accounts, and seamless
  * integration with various authentication providers and user management systems.
  *
- * @see {@link $realm}
+ * When used with `AlephaServer`, this module automatically registers `ServerSecurityProvider` and `ServerBasicAuthProvider`
+ * to protect HTTP routes and actions with JWT and Basic Auth.
+ *
+ * @see {@link $issuer}
  * @see {@link $role}
  * @see {@link $permission}
+ * @see {@link $basicAuth}
  * @module alepha.security
  */
 export const AlephaSecurity = $module({
   name: "alepha.security",
-  primitives: [$realm, $role, $permission],
-  services: [SecurityProvider, JwtProvider, CryptoProvider],
+  primitives: [$issuer, $role, $permission, $basicAuth],
+  services: [
+    SecurityProvider,
+    JwtProvider,
+    CryptoProvider,
+    ServerSecurityProvider,
+    ServerBasicAuthProvider,
+  ],
+  register: (alepha: Alepha) => {
+    // Always register core security providers
+    alepha.with(SecurityProvider);
+    alepha.with(JwtProvider);
+    alepha.with(CryptoProvider);
+
+    // Register server security providers only if AlephaServer is available
+    if (alepha.has(AlephaServer)) {
+      alepha.with(ServerSecurityProvider);
+      alepha.with(ServerBasicAuthProvider);
+    }
+  },
 });
+
+/**
+ * @deprecated Use `AlephaSecurity` instead. Server security providers are automatically registered when `AlephaServer` is available.
+ */
+export const AlephaServerSecurity = AlephaSecurity;

package/src/security/primitives/{$realm.spec.ts → $issuer.spec.ts}

@@ -2,9 +2,9 @@ import { randomUUID } from "node:crypto";
 import { Alepha } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { describe, test } from "vitest";
-import { $realm } from "../index.ts";
+import { $issuer } from "../index.ts";
 
-describe("$realm", () => {
+describe("$issuer", () => {
   const roles = [
     {
       name: "admin",
@@ -18,7 +18,7 @@ describe("$realm", () => {
 
   test("should create token (access & refresh)", async ({ expect }) => {
     class App {
-      realm = $realm({
+      issuer = $issuer({
         secret: "test",
         roles,
       });
@@ -37,15 +37,15 @@ describe("$realm", () => {
 
     const now = dt.pause();
 
-    const token = await app.realm.createToken(user);
+    const token = await app.issuer.createToken(user);
 
     expect(token).toEqual({
       access_token: expect.any(String),
-      expires_in: app.realm.accessTokenExpiration.asSeconds(),
+      expires_in: app.issuer.accessTokenExpiration.asSeconds(),
       refresh_token: expect.any(String),
       token_type: "Bearer",
       issued_at: now.unix(),
-      refresh_token_expires_in: app.realm.refreshTokenExpiration.asSeconds(),
+      refresh_token_expires_in: app.issuer.refreshTokenExpiration.asSeconds(),
     });
 
     expect(
@@ -54,9 +54,9 @@ describe("$realm", () => {
       ),
     ).toEqual({
       sub: user.id,
-      aud: app.realm.name,
+      aud: app.issuer.name,
       iat: now.unix(),
-      exp: now.unix() + app.realm.accessTokenExpiration.asSeconds(),
+      exp: now.unix() + app.issuer.accessTokenExpiration.asSeconds(),
       name: user.name,
       roles: ["admin", "user"],
       sid: expect.any(String),
@@ -71,9 +71,9 @@ describe("$realm", () => {
       ),
     ).toEqual({
       sub: user.id,
-      aud: app.realm.name,
+      aud: app.issuer.name,
       iat: now.unix(),
-      exp: now.unix() + app.realm.refreshTokenExpiration.asSeconds(),
+      exp: now.unix() + app.issuer.refreshTokenExpiration.asSeconds(),
     });
 
     expect(
@@ -88,7 +88,7 @@ describe("$realm", () => {
       typ: "refresh",
     });
 
-    const newToken = await app.realm.createToken(user, token);
+    const newToken = await app.issuer.createToken(user, token);
     expect(newToken).toEqual({
       access_token: expect.any(String),
       issued_at: now.unix(),

package/src/security/primitives/{$realm.ts → $issuer.ts}

@@ -13,43 +13,46 @@ import type { Role } from "../schemas/roleSchema.ts";
 import type { UserAccount } from "../schemas/userAccountInfoSchema.ts";
 
 /**
- * Create a new realm.
+ * Create a new issuer.
+ *
+ * An issuer is responsible for creating and verifying JWT tokens.
+ * It can be internal (with a secret) or external (with a JWKS).
  */
-export const $realm = (options: RealmPrimitiveOptions): RealmPrimitive => {
-  return createPrimitive(RealmPrimitive, options);
+export const $issuer = (options: IssuerPrimitiveOptions): IssuerPrimitive => {
+  return createPrimitive(IssuerPrimitive, options);
 };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export type RealmPrimitiveOptions = {
+export type IssuerPrimitiveOptions = {
   /**
-   * Define the realm name.
+   * Define the issuer name.
    * If not provided, it will use the property key.
    */
   name?: string;
 
   /**
-   * Short description about the realm.
+   * Short description about the issuer.
    */
   description?: string;
 
   /**
-   * All roles available in the realm. Role is a string (role name) or a Role object (embedded role).
+   * All roles available in the issuer. Role is a string (role name) or a Role object (embedded role).
    */
   roles?: Array<string | Role>;
 
   /**
-   * Realm settings.
+   * Issuer settings.
    */
-  settings?: RealmSettings;
+  settings?: IssuerSettings;
 
   /**
    * Parse the JWT payload to create a user account info.
    */
   profile?: (jwtPayload: Record<string, any>) => UserAccount;
-} & (RealmInternal | RealmExternal);
+} & (IssuerInternal | IssuerExternal);
 
-export interface RealmSettings {
+export interface IssuerSettings {
   accessToken?: {
     /**
      * Lifetime of the access token.
@@ -87,14 +90,14 @@ export interface RealmSettings {
   onDeleteSession?: (refreshToken: string) => Promise<void>;
 }
 
-export type RealmInternal = {
+export type IssuerInternal = {
   /**
    * Internal secret to sign JWT tokens and verify them.
    */
   secret: string;
 };
 
-export interface RealmExternal {
+export interface IssuerExternal {
   /**
    * URL to the JWKS (JSON Web Key Set) to verify JWT tokens from external providers.
    */
@@ -103,7 +106,7 @@ export interface RealmExternal {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class RealmPrimitive extends Primitive<RealmPrimitiveOptions> {
+export class IssuerPrimitive extends Primitive<IssuerPrimitiveOptions> {
   protected readonly securityProvider = $inject(SecurityProvider);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly jwt = $inject(JwtProvider);
@@ -148,14 +151,14 @@ export class RealmPrimitive extends Primitive<RealmPrimitiveOptions> {
   }
 
   /**
-   * Get all roles in the realm.
+   * Get all roles in the issuer.
    */
   public getRoles(): Role[] {
     return this.securityProvider.getRoles(this.name);
   }
 
   /**
-   * Set all roles in the realm.
+   * Set all roles in the issuer.
    */
   public async setRoles(roles: Role[]): Promise<void> {
     await this.securityProvider.updateRealm(this.name, roles);
@@ -336,7 +339,7 @@ export class RealmPrimitive extends Primitive<RealmPrimitiveOptions> {
   }
 }
 
-$realm[KIND] = RealmPrimitive;
+$issuer[KIND] = IssuerPrimitive;
 
 // ---------------------------------------------------------------------------------------------------------------------