alepha 0.14.4 → 0.15.1

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;
 
 // ---------------------------------------------------------------------------------------------------------------------
 

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

@@ -1,7 +1,7 @@
 import { $inject, createPrimitive, KIND, Primitive } from "alepha";
 import { SecurityProvider } from "../providers/SecurityProvider.ts";
+import type { IssuerPrimitive } from "./$issuer.ts";
 import type { PermissionPrimitive } from "./$permission.ts";
-import type { RealmPrimitive } from "./$realm.ts";
 
 /**
  * Create a new role.
@@ -23,7 +23,7 @@ export interface RolePrimitiveOptions {
    */
   description?: string;
 
-  realm?: string | RealmPrimitive;
+  issuer?: string | IssuerPrimitive;
 
   permissions?: Array<
     | string
@@ -60,10 +60,10 @@ export class RolePrimitive extends Primitive<RolePrimitiveOptions> {
   }
 
   /**
-   * Get the realm of the role.
+   * Get the issuer of the role.
    */
-  public get realm(): string | RealmPrimitive | undefined {
-    return this.options.realm;
+  public get issuer(): string | IssuerPrimitive | undefined {
+    return this.options.issuer;
   }
 
   public can(permission: string | PermissionPrimitive): boolean {

package/src/security/primitives/$serviceAccount.spec.ts

@@ -1,7 +1,7 @@
 import { Alepha } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { describe, expect, it } from "vitest";
-import { $realm, $serviceAccount } from "../index.ts";
+import { $issuer, $serviceAccount } from "../index.ts";
 
 class App {
   oauth2 = $serviceAccount({
@@ -16,12 +16,12 @@ class App {
     expiresIn: 300, // 5 minutes
   };
 
-  realm = $realm({
-    secret: "your-realm-secret",
+  issuer = $issuer({
+    secret: "your-issuer-secret",
   });
 
   jwt = $serviceAccount({
-    realm: this.realm,
+    issuer: this.issuer,
     user: {
       id: "service-account",
     },
@@ -42,7 +42,7 @@ describe("$serviceAccount", () => {
     );
     expect(payload).toEqual({
       sub: expect.any(String),
-      aud: "realm",
+      aud: "issuer",
       iat: expect.any(Number),
       exp: expect.any(Number),
       sid: expect.any(String),

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

@@ -1,7 +1,7 @@
 import { $context } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import type { UserAccount } from "../schemas/userAccountInfoSchema.ts";
-import type { AccessTokenResponse, RealmPrimitive } from "./$realm.ts";
+import type { AccessTokenResponse, IssuerPrimitive } from "./$issuer.ts";
 
 /**
  * Allow to get an access token for a service account.
@@ -138,7 +138,7 @@ export const $serviceAccount = (
         return tokenFromCache;
       }
 
-      const token = await options.realm.createToken(options.user);
+      const token = await options.issuer.createToken(options.user);
 
       cacheToken({
         ...token,
@@ -157,7 +157,7 @@ export type ServiceAccountPrimitiveOptions = {
       oauth2: Oauth2ServiceAccountPrimitiveOptions;
     }
   | {
-      realm: RealmPrimitive;
+      issuer: IssuerPrimitive;
       user: UserAccount;
     }
 );

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

@@ -1,19 +1,17 @@
 import { randomUUID } from "node:crypto";
 import { $hook, $inject, Alepha } from "alepha";
 import { $logger } from "alepha/logger";
-import {
-  JwtProvider,
-  type Permission,
-  SecurityProvider,
-  type UserAccountToken,
-  userAccountInfoSchema,
-} from "alepha/security";
 import {
   $action,
   ForbiddenError,
   type ServerRequest,
   UnauthorizedError,
 } from "alepha/server";
+import type { UserAccountToken } from "../interfaces/UserAccountToken.ts";
+import type { Permission } from "../schemas/permissionSchema.ts";
+import { userAccountInfoSchema } from "../schemas/userAccountInfoSchema.ts";
+import { JwtProvider } from "./JwtProvider.ts";
+import { SecurityProvider } from "./SecurityProvider.ts";
 import {
   type BasicAuthOptions,
   isBasicAuth,

package/src/server/auth/primitives/$auth.ts

@@ -9,7 +9,7 @@ import {
 import { DateTimeProvider } from "alepha/datetime";
 import {
   type AccessTokenResponse,
-  type RealmPrimitive,
+  type IssuerPrimitive,
   SecurityError,
   SecurityProvider,
   type UserAccount,
@@ -105,10 +105,10 @@ export type AuthExternal = {
  * When using your own authentication system, e.g. using a database to store user accounts.
  * This is usually used with a custom login form.
  *
- * This relies on the `realm`, which is used to create/verify the access token.
+ * This relies on the `issuer`, which is used to create/verify the access token.
  */
 export type AuthInternal = {
-  realm: RealmPrimitive;
+  issuer: IssuerPrimitive;
 } & (
   | {
       /**
@@ -261,9 +261,9 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
     return this.options.name ?? this.config.propertyKey;
   }
 
-  public get realm(): RealmPrimitive | undefined {
-    if ("realm" in this.options) {
-      return this.options.realm;
+  public get issuer(): IssuerPrimitive | undefined {
+    if ("issuer" in this.options) {
+      return this.options.issuer;
     }
     return undefined;
   }
@@ -308,13 +308,13 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
     refreshToken: string,
     accessToken?: string,
   ): Promise<AccessTokenResponse> {
-    if ("realm" in this.options) {
-      return this.options.realm
+    if ("issuer" in this.options) {
+      return this.options.issuer
         .refreshToken(refreshToken, accessToken)
         .then((it) => it.tokens)
         .catch((error) => {
           throw new SecurityError(
-            "Failed to refresh access token using the refresh token (realm)",
+            "Failed to refresh access token using the refresh token (issuer)",
             {
               cause: error,
             },
@@ -337,7 +337,7 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
     }
 
     throw new AlephaError(
-      "No realm or OAuth2 configuration available for refreshing the access token",
+      "No issuer or OAuth2 configuration available for refreshing the access token",
     );
   }