alepha 0.14.4 → 0.15.0

package/dist/security/index.d.ts

@@ -1,24 +1,45 @@
-import * as alepha1 from "alepha";
+import * as alepha3 from "alepha";
 import { Alepha, KIND, Primitive, Static } from "alepha";
-import * as alepha_logger0 from "alepha/logger";
+import { FetchOptions, ServerRequest, ServerRouterProvider, UnauthorizedError } from "alepha/server";
+import * as alepha_logger2 from "alepha/logger";
 import { DateTimeProvider, Duration, DurationLike } from "alepha/datetime";
 import { CryptoKey, FlattenedJWSInput, JSONWebKeySet, JWSHeaderParameters, JWTHeaderParameters, JWTPayload, JWTVerifyResult, KeyObject } from "jose";
-import { UnauthorizedError } from "alepha/server";
 import { JWTVerifyOptions } from "jose/jwt/verify";
 
 //#region ../../src/security/schemas/userAccountInfoSchema.d.ts
-declare const userAccountInfoSchema: alepha1.TObject<{
-  id: alepha1.TString;
-  name: alepha1.TOptional<alepha1.TString>;
-  email: alepha1.TOptional<alepha1.TString>;
-  username: alepha1.TOptional<alepha1.TString>;
-  picture: alepha1.TOptional<alepha1.TString>;
-  sessionId: alepha1.TOptional<alepha1.TString>;
-  organizations: alepha1.TOptional<alepha1.TArray<alepha1.TString>>;
-  roles: alepha1.TOptional<alepha1.TArray<alepha1.TString>>;
+declare const userAccountInfoSchema: alepha3.TObject<{
+  id: alepha3.TString;
+  name: alepha3.TOptional<alepha3.TString>;
+  email: alepha3.TOptional<alepha3.TString>;
+  username: alepha3.TOptional<alepha3.TString>;
+  picture: alepha3.TOptional<alepha3.TString>;
+  sessionId: alepha3.TOptional<alepha3.TString>;
+  organizations: alepha3.TOptional<alepha3.TArray<alepha3.TString>>;
+  roles: alepha3.TOptional<alepha3.TArray<alepha3.TString>>;
 }>;
 type UserAccount = Static<typeof userAccountInfoSchema>;
 //#endregion
+//#region ../../src/security/interfaces/UserAccountToken.d.ts
+/**
+ * Add contextual metadata to a user account info.
+ * E.g. UserAccountToken is a UserAccountInfo during a request.
+ */
+interface UserAccountToken extends UserAccount {
+  /**
+       * Access token for the user.
+       */
+  token?: string;
+  /**
+       * Realm name of the user.
+       */
+  realm?: string;
+  /**
+       * Is user dedicated to his own resources for this scope ?
+       * Mostly, Admin is false and Customer is true.
+       */
+  ownership?: string | boolean;
+}
+//#endregion
 //#region ../../src/security/errors/InvalidCredentialsError.d.ts
 /**
  * Error thrown when the provided credentials are invalid.
@@ -42,90 +63,126 @@ declare class SecurityError extends Error {
   readonly status = 403;
 }
 //#endregion
-//#region ../../src/security/interfaces/UserAccountToken.d.ts
+//#region ../../src/security/providers/ServerBasicAuthProvider.d.ts
+interface BasicAuthOptions {
+  username: string;
+  password: string;
+}
+interface BasicAuthPrimitiveConfig extends BasicAuthOptions {
+  /** Name identifier for this basic auth (default: property key) */
+  name?: string;
+  /** Path patterns to match (supports wildcards like /devtools/*) */
+  paths?: string[];
+}
+declare class ServerBasicAuthProvider {
+  protected readonly alepha: Alepha;
+  protected readonly log: alepha_logger2.Logger;
+  protected readonly routerProvider: ServerRouterProvider;
+  protected readonly realm = "Secure Area";
+  /**
+       * Registered basic auth primitives with their configurations
+       */
+  readonly registeredAuths: BasicAuthPrimitiveConfig[];
+  /**
+       * Register a basic auth configuration (called by primitives)
+       */
+  registerAuth(config: BasicAuthPrimitiveConfig): void;
+  readonly onStart: alepha3.HookPrimitive<"start">;
+  /**
+       * Hook into server:onRequest to check basic auth
+       */
+  readonly onRequest: alepha3.HookPrimitive<"server:onRequest">;
+  /**
+       * Hook into action:onRequest to check basic auth for actions
+       */
+  readonly onActionRequest: alepha3.HookPrimitive<"action:onRequest">;
+  /**
+       * Check basic authentication
+       */
+  checkAuth(request: ServerRequest, options: BasicAuthOptions): void;
+  /**
+       * Performs a timing-safe comparison of credentials to prevent timing attacks.
+       * Always compares both username and password to avoid leaking which one is wrong.
+       */
+  protected timingSafeCredentialCheck(inputUsername: string, inputPassword: string, expectedUsername: string, expectedPassword: string): boolean;
+  /**
+       * Compares two buffers in constant time, handling different lengths safely.
+       * Returns 1 if equal, 0 if not equal.
+       */
+  protected safeCompare(input: Buffer, expected: Buffer): number;
+  /**
+       * Send WWW-Authenticate header
+       */
+  protected sendAuthRequired(request: ServerRequest): void;
+}
+declare const isBasicAuth: (value: unknown) => value is {
+  basic: BasicAuthOptions;
+};
+//#endregion
+//#region ../../src/security/primitives/$basicAuth.d.ts
 /**
- * Add contextual metadata to a user account info.
- * E.g. UserAccountToken is a UserAccountInfo during a request.
+ * Declares HTTP Basic Authentication for server routes.
+ * This primitive provides methods to protect routes with username/password authentication.
  */
-interface UserAccountToken extends UserAccount {
-  /**
-   * Access token for the user.
-   */
-  token?: string;
-  /**
-   * Realm name of the user.
-   */
-  realm?: string;
+declare const $basicAuth: {
+  (options: BasicAuthPrimitiveConfig): AbstractBasicAuthPrimitive;
+  [KIND]: typeof BasicAuthPrimitive;
+};
+interface AbstractBasicAuthPrimitive {
+  readonly name: string;
+  readonly options: BasicAuthPrimitiveConfig;
+  check(request: ServerRequest, options?: BasicAuthOptions): void;
+}
+declare class BasicAuthPrimitive extends Primitive<BasicAuthPrimitiveConfig> implements AbstractBasicAuthPrimitive {
+  protected readonly serverBasicAuthProvider: ServerBasicAuthProvider;
+  get name(): string;
+  protected onInit(): void;
   /**
-   * Is user dedicated to his own resources for this scope ?
-   * Mostly, Admin is false and Customer is true.
-   */
-  ownership?: string | boolean;
+       * Checks basic auth for the given request using this primitive's configuration.
+       */
+  check(request: ServerRequest, options?: BasicAuthOptions): void;
 }
 //#endregion
-//#region ../../src/security/schemas/permissionSchema.d.ts
-declare const permissionSchema: alepha1.TObject<{
-  name: alepha1.TString;
-  group: alepha1.TOptional<alepha1.TString>;
-  description: alepha1.TOptional<alepha1.TString>;
-  method: alepha1.TOptional<alepha1.TString>;
-  path: alepha1.TOptional<alepha1.TString>;
-}>;
-type Permission = Static<typeof permissionSchema>;
-//#endregion
-//#region ../../src/security/schemas/roleSchema.d.ts
-declare const roleSchema: alepha1.TObject<{
-  name: alepha1.TString;
-  description: alepha1.TOptional<alepha1.TString>;
-  default: alepha1.TOptional<alepha1.TBoolean>;
-  permissions: alepha1.TArray<alepha1.TObject<{
-    name: alepha1.TString;
-    ownership: alepha1.TOptional<alepha1.TBoolean>;
-    exclude: alepha1.TOptional<alepha1.TArray<alepha1.TString>>;
-  }>>;
-}>;
-type Role = Static<typeof roleSchema>;
-//#endregion
 //#region ../../src/security/providers/JwtProvider.d.ts
 /**
  * Provides utilities for working with JSON Web Tokens (JWT).
  */
 declare class JwtProvider {
-  protected readonly log: alepha_logger0.Logger;
+  protected readonly log: alepha_logger2.Logger;
   protected readonly keystore: KeyLoaderHolder[];
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly encoder: TextEncoder;
   /**
-   * Adds a key loader to the embedded keystore.
-   *
-   * @param name
-   * @param secretKeyOrJwks
-   */
+       * Adds a key loader to the embedded keystore.
+       *
+       * @param name
+       * @param secretKeyOrJwks
+       */
   setKeyLoader(name: string, secretKeyOrJwks: string | JSONWebKeySet): void;
   /**
-   * Retrieves the payload from a JSON Web Token (JWT).
-   *
-   * @param token - The JWT to extract the payload from.
-   *
-   * @return A Promise that resolves with the payload object from the token.
-   */
+       * Retrieves the payload from a JSON Web Token (JWT).
+       *
+       * @param token - The JWT to extract the payload from.
+       *
+       * @return A Promise that resolves with the payload object from the token.
+       */
   parse(token: string, keyName?: string, options?: JWTVerifyOptions): Promise<JwtParseResult>;
   /**
-   * Creates a JWT token with the provided payload and secret key.
-   *
-   * @param payload - The payload to be encoded in the token.
-   * 	It should include the `realm_access` property which contains an array of roles.
-   * @param keyName - The name of the key to use when signing the token.
-   *
-   * @returns The signed JWT token.
-   */
+       * Creates a JWT token with the provided payload and secret key.
+       *
+       * @param payload - The payload to be encoded in the token.
+       * 	It should include the `realm_access` property which contains an array of roles.
+       * @param keyName - The name of the key to use when signing the token.
+       *
+       * @returns The signed JWT token.
+       */
   create(payload: ExtendedJWTPayload, keyName?: string, signOptions?: JwtSignOptions): Promise<string>;
   /**
-   * Determines if the provided key is a secret key.
-   *
-   * @param key
-   * @protected
-   */
+       * Determines if the provided key is a secret key.
+       *
+       * @param key
+       * @protected
+       */
   protected isSecretKey(key: string): boolean;
 }
 type KeyLoader = (protectedHeader?: JWSHeaderParameters, token?: FlattenedJWSInput) => Promise<CryptoKey | KeyObject>;
@@ -152,10 +209,33 @@ interface JwtParseResult {
   result: JWTVerifyResult<ExtendedJWTPayload>;
 }
 //#endregion
+//#region ../../src/security/schemas/permissionSchema.d.ts
+declare const permissionSchema: alepha3.TObject<{
+  name: alepha3.TString;
+  group: alepha3.TOptional<alepha3.TString>;
+  description: alepha3.TOptional<alepha3.TString>;
+  method: alepha3.TOptional<alepha3.TString>;
+  path: alepha3.TOptional<alepha3.TString>;
+}>;
+type Permission = Static<typeof permissionSchema>;
+//#endregion
+//#region ../../src/security/schemas/roleSchema.d.ts
+declare const roleSchema: alepha3.TObject<{
+  name: alepha3.TString;
+  description: alepha3.TOptional<alepha3.TString>;
+  default: alepha3.TOptional<alepha3.TBoolean>;
+  permissions: alepha3.TArray<alepha3.TObject<{
+    name: alepha3.TString;
+    ownership: alepha3.TOptional<alepha3.TBoolean>;
+    exclude: alepha3.TOptional<alepha3.TArray<alepha3.TString>>;
+  }>>;
+}>;
+type Role = Static<typeof roleSchema>;
+//#endregion
 //#region ../../src/security/providers/SecurityProvider.d.ts
 declare const DEFAULT_APP_SECRET = "05759934015388327323179852515731";
-declare const envSchema: alepha1.TObject<{
-  APP_SECRET: alepha1.TString;
+declare const envSchema: alepha3.TObject<{
+  APP_SECRET: alepha3.TString;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
@@ -164,7 +244,7 @@ declare class SecurityProvider {
   protected readonly UNKNOWN_USER_NAME = "Anonymous User";
   protected readonly PERMISSION_REGEXP: RegExp;
   protected readonly PERMISSION_REGEXP_WILDCARD: RegExp;
-  protected readonly log: alepha_logger0.Logger;
+  protected readonly log: alepha_logger2.Logger;
   protected readonly jwt: JwtProvider;
   protected readonly env: {
     APP_SECRET: string;
@@ -172,122 +252,122 @@ declare class SecurityProvider {
   protected readonly alepha: Alepha;
   get secretKey(): string;
   /**
-   * The permissions configured for the security provider.
-   */
+       * The permissions configured for the security provider.
+       */
   protected readonly permissions: Permission[];
   /**
-   * The realms configured for the security provider.
-   */
+       * The realms configured for the security provider.
+       */
   protected readonly realms: Realm[];
-  protected start: alepha1.HookPrimitive<"start">;
+  protected start: alepha3.HookPrimitive<"start">;
   /**
-   * Adds a role to one or more realms.
-   *
-   * @param role
-   * @param realms
-   */
+       * Adds a role to one or more realms.
+       *
+       * @param role
+       * @param realms
+       */
   createRole(role: Role, ...realms: string[]): Role;
   /**
-   * Adds a permission to the security provider.
-   *
-   * @param raw - The permission to add.
-   */
+       * Adds a permission to the security provider.
+       *
+       * @param raw - The permission to add.
+       */
   createPermission(raw: Permission | string): Permission;
   createRealm(realm: Realm): void;
   /**
-   * Updates the roles for a realm then synchronizes the user account provider if available.
-   *
-   * Only available when the app is started.
-   *
-   * @param realm - The realm to update the roles for.
-   * @param roles - The roles to update.
-   */
+       * Updates the roles for a realm then synchronizes the user account provider if available.
+       *
+       * Only available when the app is started.
+       *
+       * @param realm - The realm to update the roles for.
+       * @param roles - The roles to update.
+       */
   updateRealm(realm: string, roles: Role[]): Promise<void>;
   /**
-   * Creates a user account from the provided payload.
-   *
-   * @param payload - The payload to create the user account from.
-   * @param [realmName] - The realm containing the roles. Default is all.
-   *
-   * @returns The user info created from the payload.
-   */
+       * Creates a user account from the provided payload.
+       *
+       * @param payload - The payload to create the user account from.
+       * @param [realmName] - The realm containing the roles. Default is all.
+       *
+       * @returns The user info created from the payload.
+       */
   createUserFromPayload(payload: JWTPayload, realmName?: string): UserAccount;
   /**
-   * Checks if the user has the specified permission.
-   *
-   * Bonus: we check also if the user has "ownership" flag.
-   *
-   * @param permissionLike - The permission to check for.
-   * @param roleEntries - The roles to check for the permission.
-   */
+       * Checks if the user has the specified permission.
+       *
+       * Bonus: we check also if the user has "ownership" flag.
+       *
+       * @param permissionLike - The permission to check for.
+       * @param roleEntries - The roles to check for the permission.
+       */
   checkPermission(permissionLike: string | Permission, ...roleEntries: string[]): SecurityCheckResult;
   /**
-   * Creates a user account from the provided payload.
-   */
+       * Creates a user account from the provided payload.
+       */
   createUserFromToken(headerOrToken?: string, options?: {
     permission?: Permission | string;
     realm?: string;
     verify?: JWTVerifyOptions;
   }): Promise<UserAccountToken>;
   /**
-   * Checks if a user has a specific role.
-   *
-   * @param roleName - The role to check for.
-   * @param permission - The permission to check for.
-   * @returns True if the user has the role, false otherwise.
-   */
+       * Checks if a user has a specific role.
+       *
+       * @param roleName - The role to check for.
+       * @param permission - The permission to check for.
+       * @returns True if the user has the role, false otherwise.
+       */
   can(roleName: string, permission: string | Permission): boolean;
   /**
-   * Checks if a user has ownership of a specific permission.
-   */
+       * Checks if a user has ownership of a specific permission.
+       */
   ownership(roleName: string, permission: string | Permission): string | boolean | undefined;
   /**
-   * Converts a permission object to a string.
-   *
-   * @param permission
-   */
+       * Converts a permission object to a string.
+       *
+       * @param permission
+       */
   permissionToString(permission: Permission | string): string;
   getRealms(): Realm[];
   /**
-   * Retrieves the user account from the provided user ID.
-   *
-   * @param realm
-   */
+       * Retrieves the user account from the provided user ID.
+       *
+       * @param realm
+       */
   getRoles(realm?: string): Role[];
   /**
-   * Returns all permissions.
-   *
-   * @param user - Filter permissions by user.
-   *
-   * @return An array containing all permissions.
-   */
+       * Returns all permissions.
+       *
+       * @param user - Filter permissions by user.
+       *
+       * @return An array containing all permissions.
+       */
   getPermissions(user?: {
     roles?: Array<Role | string>;
     realm?: string;
   }): Permission[];
   /**
-   * Retrieves the user ID from the provided payload object.
-   *
-   * @param payload - The payload object from which to extract the user ID.
-   * @return The user ID as a string.
-   */
+       * Retrieves the user ID from the provided payload object.
+       *
+       * @param payload - The payload object from which to extract the user ID.
+       * @return The user ID as a string.
+       */
   getIdFromPayload(payload: Record<string, any>): string;
   getSessionIdFromPayload(payload: Record<string, any>): string | undefined;
   /**
-   * Retrieves the roles from the provided payload object.
-   * @param payload - The payload object from which to extract the roles.
-   * @return An array of role strings.
-   */
+       * Retrieves the roles from the provided payload object.
+       * @param payload - The payload object from which to extract the roles.
+       * @return An array of role strings.
+       */
   getRolesFromPayload(payload: Record<string, any>): string[];
   getPictureFromPayload(payload: Record<string, any>): string | undefined;
   getUsernameFromPayload(payload: Record<string, any>): string | undefined;
   getEmailFromPayload(payload: Record<string, any>): string | undefined;
   /**
-   * Returns the name from the given payload.
-   *
-   * @param payload - The payload object.
-   * @returns The name extracted from the payload, or an empty string if the payload is falsy or no name is found.
-   */
+       * Returns the name from the given payload.
+       *
+       * @param payload - The payload object.
+       * @returns The name extracted from the payload, or an empty string if the payload is falsy or no name is found.
+       */
   getNameFromPayload(payload: Record<string, any>): string;
   getOrganizationsFromPayload(payload: Record<string, any>): string[] | undefined;
 }
@@ -298,15 +378,15 @@ interface Realm {
   name: string;
   roles: Role[];
   /**
-   * The secret key for the realm.
-   *
-   * Can be also a JWKS URL.
-   */
+       * The secret key for the realm.
+       *
+       * Can be also a JWKS URL.
+       */
   secret?: string | JSONWebKeySet | (() => string);
   /**
-   * Create the user account info based on the raw JWT payload.
-   * By default, SecurityProvider has his own implementation, but this method allow to override it.
-   */
+       * Create the user account info based on the raw JWT payload.
+       * By default, SecurityProvider has his own implementation, but this method allow to override it.
+       */
   profile?: (raw: Record<string, any>) => UserAccount;
 }
 interface SecurityCheckResult {
@@ -314,84 +394,53 @@ interface SecurityCheckResult {
   ownership: string | boolean | undefined;
 }
 //#endregion
-//#region ../../src/security/primitives/$permission.d.ts
-/**
- * Create a new permission.
- */
-declare const $permission: {
-  (options?: PermissionPrimitiveOptions): PermissionPrimitive;
-  [KIND]: typeof PermissionPrimitive;
-};
-interface PermissionPrimitiveOptions {
-  /**
-   * Name of the permission. Use Property name is not provided.
-   */
-  name?: string;
-  /**
-   * Group of the permission. Use Class name is not provided.
-   */
-  group?: string;
-  /**
-   * Describe the permission.
-   */
-  description?: string;
-}
-declare class PermissionPrimitive extends Primitive<PermissionPrimitiveOptions> {
-  protected readonly securityProvider: SecurityProvider;
-  get name(): string;
-  get group(): string;
-  toString(): string;
-  protected onInit(): void;
-  /**
-   * Check if the user has the permission.
-   */
-  can(user?: UserAccount): boolean;
-}
-//#endregion
-//#region ../../src/security/primitives/$realm.d.ts
+//#region ../../src/security/primitives/$issuer.d.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).
  */
-declare const $realm: {
-  (options: RealmPrimitiveOptions): RealmPrimitive;
-  [KIND]: typeof RealmPrimitive;
+declare const $issuer: {
+  (options: IssuerPrimitiveOptions): IssuerPrimitive;
+  [KIND]: typeof IssuerPrimitive;
 };
-type RealmPrimitiveOptions = {
+type IssuerPrimitiveOptions = {
   /**
-   * Define the realm name.
-   * If not provided, it will use the property key.
-   */
+       * 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.
-   */
-  settings?: RealmSettings;
+       * Issuer settings.
+       */
+  settings?: IssuerSettings;
   /**
-   * Parse the JWT payload to create a user account info.
-   */
+       * Parse the JWT payload to create a user account info.
+       */
   profile?: (jwtPayload: Record<string, any>) => UserAccount;
-} & (RealmInternal | RealmExternal);
-interface RealmSettings {
+} & (IssuerInternal | IssuerExternal);
+interface IssuerSettings {
   accessToken?: {
     /**
-     * Lifetime of the access token.
-     * @default 15 minutes
-     */
+             * Lifetime of the access token.
+             * @default 15 minutes
+             */
     expiration?: DurationLike;
   };
   refreshToken?: {
     /**
-     * Lifetime of the refresh token.
-     * @default 30 days
-     */
+             * Lifetime of the refresh token.
+             * @default 30 days
+             */
     expiration?: DurationLike;
   };
   onCreateSession?: (user: UserAccount, config: {
@@ -407,43 +456,43 @@ interface RealmSettings {
   }>;
   onDeleteSession?: (refreshToken: string) => Promise<void>;
 }
-type RealmInternal = {
+type IssuerInternal = {
   /**
-   * Internal secret to sign JWT tokens and verify them.
-   */
+       * Internal secret to sign JWT tokens and verify them.
+       */
   secret: string;
 };
-interface RealmExternal {
+interface IssuerExternal {
   /**
-   * URL to the JWKS (JSON Web Key Set) to verify JWT tokens from external providers.
-   */
+       * URL to the JWKS (JSON Web Key Set) to verify JWT tokens from external providers.
+       */
   jwks: (() => string) | JSONWebKeySet;
 }
-declare class RealmPrimitive extends Primitive<RealmPrimitiveOptions> {
+declare class IssuerPrimitive extends Primitive<IssuerPrimitiveOptions> {
   protected readonly securityProvider: SecurityProvider;
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly jwt: JwtProvider;
-  protected readonly log: alepha_logger0.Logger;
+  protected readonly log: alepha_logger2.Logger;
   get name(): string;
   get accessTokenExpiration(): Duration;
   get refreshTokenExpiration(): Duration;
   protected onInit(): void;
   /**
-   * Get all roles in the realm.
-   */
+       * Get all roles in the issuer.
+       */
   getRoles(): Role[];
   /**
-   * Set all roles in the realm.
-   */
+       * Set all roles in the issuer.
+       */
   setRoles(roles: Role[]): Promise<void>;
   /**
-   * Get a role by name, throws an error if not found.
-   */
+       * Get a role by name, throws an error if not found.
+       */
   getRoleByName(name: string): Role;
   parseToken(token: string): Promise<JWTPayload>;
   /**
-   * Create a token for the subject.
-   */
+       * Create a token for the subject.
+       */
   createToken(user: UserAccount, refreshToken?: {
     sid?: string;
     refresh_token?: string;
@@ -469,6 +518,40 @@ interface AccessTokenResponse {
   scope?: string;
 }
 //#endregion
+//#region ../../src/security/primitives/$permission.d.ts
+/**
+ * Create a new permission.
+ */
+declare const $permission: {
+  (options?: PermissionPrimitiveOptions): PermissionPrimitive;
+  [KIND]: typeof PermissionPrimitive;
+};
+interface PermissionPrimitiveOptions {
+  /**
+       * Name of the permission. Use Property name is not provided.
+       */
+  name?: string;
+  /**
+       * Group of the permission. Use Class name is not provided.
+       */
+  group?: string;
+  /**
+       * Describe the permission.
+       */
+  description?: string;
+}
+declare class PermissionPrimitive extends Primitive<PermissionPrimitiveOptions> {
+  protected readonly securityProvider: SecurityProvider;
+  get name(): string;
+  get group(): string;
+  toString(): string;
+  protected onInit(): void;
+  /**
+       * Check if the user has the permission.
+       */
+  can(user?: UserAccount): boolean;
+}
+//#endregion
 //#region ../../src/security/primitives/$role.d.ts
 /**
  * Create a new role.
@@ -479,14 +562,14 @@ declare const $role: {
 };
 interface RolePrimitiveOptions {
   /**
-   * Name of the role.
-   */
+       * Name of the role.
+       */
   name?: string;
   /**
-   * Describe the role.
-   */
+       * Describe the role.
+       */
   description?: string;
-  realm?: string | RealmPrimitive;
+  issuer?: string | IssuerPrimitive;
   permissions?: Array<string | {
     name: string;
     ownership?: boolean;
@@ -498,9 +581,9 @@ declare class RolePrimitive extends Primitive<RolePrimitiveOptions> {
   get name(): string;
   protected onInit(): void;
   /**
-   * Get the realm of the role.
-   */
-  get realm(): string | RealmPrimitive | undefined;
+       * Get the issuer of the role.
+       */
+  get issuer(): string | IssuerPrimitive | undefined;
   can(permission: string | PermissionPrimitive): boolean;
   check(permission: string | PermissionPrimitive): SecurityCheckResult;
 }
@@ -540,21 +623,21 @@ type ServiceAccountPrimitiveOptions = {
 } & ({
   oauth2: Oauth2ServiceAccountPrimitiveOptions;
 } | {
-  realm: RealmPrimitive;
+  issuer: IssuerPrimitive;
   user: UserAccount;
 });
 interface Oauth2ServiceAccountPrimitiveOptions {
   /**
-   * Get Token URL.
-   */
+       * Get Token URL.
+       */
   url: string;
   /**
-   * Client ID.
-   */
+       * Client ID.
+       */
   clientId: string;
   /**
-   * Client Secret.
-   */
+       * Client Secret.
+       */
   clientSecret: string;
 }
 interface ServiceAccountPrimitive {
@@ -571,6 +654,38 @@ declare class CryptoProvider {
   randomUUID(): string;
 }
 //#endregion
+//#region ../../src/security/providers/ServerSecurityProvider.d.ts
+declare class ServerSecurityProvider {
+  protected readonly log: alepha_logger2.Logger;
+  protected readonly securityProvider: SecurityProvider;
+  protected readonly jwtProvider: JwtProvider;
+  protected readonly alepha: Alepha;
+  protected readonly onConfigure: alepha3.HookPrimitive<"configure">;
+  protected readonly onActionRequest: alepha3.HookPrimitive<"action:onRequest">;
+  protected readonly onRequest: alepha3.HookPrimitive<"server:onRequest">;
+  protected check(user: UserAccountToken, secure: ServerRouteSecure): void;
+  /**
+       * Get the user account token for a local action call.
+       * There are three possible sources for the user:
+       * - `options.user`: the user passed in the options
+       * - `"system"`: the system user from the state (you MUST set state `server.security.system.user`)
+       * - `"context"`: the user from the request context (you MUST be in an HTTP request context)
+       *
+       * Priority order: `options.user` > `"system"` > `"context"`.
+       *
+       * In testing environment, if no user is provided, a test user is created based on the SecurityProvider's roles.
+       */
+  protected createUserFromLocalFunctionContext(options: {
+    user?: UserAccountToken | "system" | "context";
+  }, permission?: Permission): UserAccountToken;
+  protected createTestUser(): UserAccountToken;
+  protected readonly onClientRequest: alepha3.HookPrimitive<"client:onRequest">;
+}
+type ServerRouteSecure = {
+  realm?: string;
+  basic?: BasicAuthOptions;
+};
+//#endregion
 //#region ../../src/security/index.d.ts
 declare module "alepha" {
   interface Hooks {
@@ -579,20 +694,68 @@ 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;
+  }
+  interface ServerActionRequest<TConfig> {
+    user: UserAccountToken;
+  }
+  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
  */
-declare const AlephaSecurity: alepha1.Service<alepha1.Module>;
+declare const AlephaSecurity: alepha3.Service<alepha3.Module>;
+/**
+ * @deprecated Use `AlephaSecurity` instead. Server security providers are automatically registered when `AlephaServer` is available.
+ */
+declare const AlephaServerSecurity: alepha3.Service<alepha3.Module>;
 //#endregion
-export { $permission, $realm, $role, $serviceAccount, AccessTokenResponse, AlephaSecurity, CreateTokenOptions, CryptoProvider, DEFAULT_APP_SECRET, ExtendedJWTPayload, InvalidCredentialsError, InvalidPermissionError, JwtParseResult, JwtProvider, JwtSignOptions, KeyLoader, KeyLoaderHolder, Oauth2ServiceAccountPrimitiveOptions, Permission, PermissionPrimitive, PermissionPrimitiveOptions, Realm, RealmExternal, RealmInternal, RealmPrimitive, RealmPrimitiveOptions, RealmSettings, Role, RolePrimitive, RolePrimitiveOptions, SecurityCheckResult, SecurityError, SecurityProvider, ServiceAccountPrimitive, ServiceAccountPrimitiveOptions, ServiceAccountStore, UserAccount, UserAccountToken, permissionSchema, roleSchema, userAccountInfoSchema };
+export { $basicAuth, $issuer, $permission, $role, $serviceAccount, AbstractBasicAuthPrimitive, AccessTokenResponse, AlephaSecurity, AlephaServerSecurity, BasicAuthOptions, BasicAuthPrimitive, BasicAuthPrimitiveConfig, CreateTokenOptions, CryptoProvider, DEFAULT_APP_SECRET, ExtendedJWTPayload, InvalidCredentialsError, InvalidPermissionError, IssuerExternal, IssuerInternal, IssuerPrimitive, IssuerPrimitiveOptions, IssuerSettings, JwtParseResult, JwtProvider, JwtSignOptions, KeyLoader, KeyLoaderHolder, Oauth2ServiceAccountPrimitiveOptions, Permission, PermissionPrimitive, PermissionPrimitiveOptions, Realm, Role, RolePrimitive, RolePrimitiveOptions, SecurityCheckResult, SecurityError, SecurityProvider, ServerBasicAuthProvider, ServerRouteSecure, ServerSecurityProvider, ServiceAccountPrimitive, ServiceAccountPrimitiveOptions, ServiceAccountStore, UserAccount, UserAccountToken, isBasicAuth, permissionSchema, roleSchema, userAccountInfoSchema };
 //# sourceMappingURL=index.d.ts.map