alepha 0.14.4 → 0.15.0

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",
     );
   }
 

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

@@ -1,5 +1,5 @@
 import { AlephaError } from "alepha";
-import type { RealmPrimitive } from "alepha/security";
+import type { IssuerPrimitive } from "alepha/security";
 import {
   $auth,
   type CredentialsFn,
@@ -13,7 +13,7 @@ import {
  * Uses username and password to authenticate users.
  */
 export const $authCredentials = (
-  realm: RealmPrimitive & WithLoginFn,
+  realm: IssuerPrimitive & WithLoginFn,
   options: Partial<CredentialsOptions> = {},
 ) => {
   const name = "credentials";
@@ -29,7 +29,7 @@ export const $authCredentials = (
   }
 
   return $auth({
-    realm,
+    issuer: realm,
     name,
     credentials: {
       account,

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

@@ -1,5 +1,5 @@
 import { $context, AlephaError, t } from "alepha";
-import type { RealmPrimitive } from "alepha/security";
+import type { IssuerPrimitive } from "alepha/security";
 import type { OAuth2Profile } from "../providers/ServerAuthProvider.ts";
 import {
   $auth,
@@ -19,7 +19,7 @@ import {
  * - `GITHUB_CLIENT_SECRET`: The client secret obtained from the GitHub Developer Settings.
  */
 export const $authGithub = (
-  realm: RealmPrimitive & WithLinkFn,
+  realm: IssuerPrimitive & WithLinkFn,
   options: Partial<OidcOptions> = {},
 ) => {
   const { alepha } = $context();
@@ -45,7 +45,7 @@ export const $authGithub = (
   }
 
   return $auth({
-    realm,
+    issuer: realm,
     name,
     oauth: {
       clientId: env.GITHUB_CLIENT_ID!,

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

@@ -1,5 +1,5 @@
 import { $context, AlephaError, t } from "alepha";
-import type { RealmPrimitive } from "alepha/security";
+import type { IssuerPrimitive } from "alepha/security";
 import {
   $auth,
   type LinkAccountFn,
@@ -18,7 +18,7 @@ import {
  * - `GOOGLE_CLIENT_SECRET`: The client secret obtained from the Google Developer Console.
  */
 export const $authGoogle = (
-  realm: RealmPrimitive & WithLinkFn,
+  realm: IssuerPrimitive & WithLinkFn,
   options: Partial<OidcOptions> = {},
 ) => {
   const { alepha } = $context();
@@ -44,7 +44,7 @@ export const $authGoogle = (
   }
 
   return $auth({
-    realm,
+    issuer: realm,
     name,
     oidc: {
       issuer: "https://accounts.google.com",

package/src/server/auth/providers/ServerAuthProvider.ts

@@ -71,8 +71,8 @@ export class ServerAuthProvider {
 
     for (const identity of this.identities) {
       if (filters.realmName) {
-        const realm = "realm" in identity.options && identity.options.realm;
-        if (!realm || realm.name !== filters.realmName) {
+        const issuer = identity.issuer;
+        if (!issuer || issuer.name !== filters.realmName) {
           continue;
         }
       }
@@ -145,7 +145,7 @@ export class ServerAuthProvider {
       // [feature] support for auth providers with fallback
       if (!request.headers.authorization) {
         for (const provider of this.identities) {
-          if (!("realm" in provider.options) && !!provider.options.fallback) {
+          if ("fallback" in provider.options && !!provider.options.fallback) {
             const token = await provider.options.fallback();
             if (token) {
               request.headers.authorization = `Bearer ${token}`;
@@ -340,8 +340,8 @@ export class ServerAuthProvider {
         realm: query.realm,
       });
 
-      const realm = "realm" in provider.options && provider.options.realm;
-      if (!realm) {
+      const issuer = provider.issuer;
+      if (!issuer) {
         throw new SecurityError(
           `Auth provider '${query.provider}' does not support password grant`,
         );
@@ -373,7 +373,7 @@ export class ServerAuthProvider {
 
       const tokens = {
         provider: query.provider,
-        ...(await realm.createToken(user)),
+        ...(await issuer.createToken(user)),
       };
 
       // for web applications, we store tokens in cookies
@@ -519,10 +519,10 @@ export class ServerAuthProvider {
 
       this.authorizationCode.del({ cookies });
 
-      const realm = "realm" in provider.options && provider.options.realm;
+      const issuer = provider.issuer;
 
       // external, full OIDC System (e.g. Keycloak, Auth0)
-      if (!realm) {
+      if (!issuer) {
         this.setTokens(externalTokens, cookies);
         reply.redirect(redirectUri);
         return;
@@ -531,7 +531,7 @@ export class ServerAuthProvider {
       // internal, we need to create our own tokens
 
       const user = await provider.user(externalTokens);
-      const tokens = await realm.createToken(user);
+      const tokens = await issuer.createToken(user);
 
       this.setTokens(
         {
@@ -570,9 +570,9 @@ export class ServerAuthProvider {
       this.tokens.del({ cookies });
 
       // for internal providers, we can delete the session - if available
-      if ("realm" in provider.options && tokens.refresh_token) {
+      if (provider.issuer && tokens.refresh_token) {
         const onDeleteSession =
-          provider.options.realm.options.settings?.onDeleteSession;
+          provider.issuer.options.settings?.onDeleteSession;
         if (onDeleteSession) {
           try {
             await onDeleteSession(tokens.refresh_token);
@@ -635,8 +635,8 @@ export class ServerAuthProvider {
         return false;
       }
 
-      // If realm filter is specified, match against provider's realm
-      if (realmName && identity.realm?.name !== realmName) {
+      // If realm filter is specified, match against provider's issuer
+      if (realmName && identity.issuer?.name !== realmName) {
         return false;
       }
 

package/src/server/cache/providers/ServerCacheProvider.ts

@@ -204,7 +204,7 @@ export class ServerCacheProvider {
 
   protected readonly onSend = $hook({
     on: "server:onSend",
-    handler: async ({ route, request }) => {
+    handler: ({ route, request }) => {
       // before sending the response, check if the ETag matches
       // and if so, return a 304 Not Modified response
       // -> this is only relevant for etag-only routes, not cached routes <-