alepha 0.14.4 → 0.15.1

package/dist/security/index.d.ts

@@ -1,24 +1,43 @@
-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,56 +61,417 @@ 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 {
+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;
   /**
-   * Access token for the user.
+   * Checks basic auth for the given request using this primitive's configuration.
    */
-  token?: string;
+  check(request: ServerRequest, options?: BasicAuthOptions): void;
+}
+//#endregion
+//#region ../../../../node_modules/jose/dist/types/types.d.ts
+/** Generic JSON Web Key Parameters. */
+interface JWKParameters {
+  /** JWK "kty" (Key Type) Parameter */
+  kty?: string;
   /**
-   * Realm name of the user.
+   * JWK "alg" (Algorithm) Parameter
+   *
+   * @see {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}
    */
-  realm?: string;
+  alg?: string;
+  /** JWK "key_ops" (Key Operations) Parameter */
+  key_ops?: string[];
+  /** JWK "ext" (Extractable) Parameter */
+  ext?: boolean;
+  /** JWK "use" (Public Key Use) Parameter */
+  use?: string;
+  /** JWK "x5c" (X.509 Certificate Chain) Parameter */
+  x5c?: string[];
+  /** JWK "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter */
+  x5t?: string;
+  /** JWK "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Parameter */
+  'x5t#S256'?: string;
+  /** JWK "x5u" (X.509 URL) Parameter */
+  x5u?: string;
+  /** JWK "kid" (Key ID) Parameter */
+  kid?: string;
+}
+/**
+ * JSON Web Key ({@link https://www.rfc-editor.org/rfc/rfc7517 JWK}). "RSA", "EC", "OKP", "AKP", and
+ * "oct" key types are supported.
+ *
+ * @see {@link JWK_AKP_Public}
+ * @see {@link JWK_AKP_Private}
+ * @see {@link JWK_OKP_Public}
+ * @see {@link JWK_OKP_Private}
+ * @see {@link JWK_EC_Public}
+ * @see {@link JWK_EC_Private}
+ * @see {@link JWK_RSA_Public}
+ * @see {@link JWK_RSA_Private}
+ * @see {@link JWK_oct}
+ */
+interface JWK extends JWKParameters {
   /**
-   * Is user dedicated to his own resources for this scope ?
-   * Mostly, Admin is false and Customer is true.
+   * - EC JWK "crv" (Curve) Parameter
+   * - OKP JWK "crv" (The Subtype of Key Pair) Parameter
    */
-  ownership?: string | boolean;
+  crv?: string;
+  /**
+   * - Private RSA JWK "d" (Private Exponent) Parameter
+   * - Private EC JWK "d" (ECC Private Key) Parameter
+   * - Private OKP JWK "d" (The Private Key) Parameter
+   */
+  d?: string;
+  /** Private RSA JWK "dp" (First Factor CRT Exponent) Parameter */
+  dp?: string;
+  /** Private RSA JWK "dq" (Second Factor CRT Exponent) Parameter */
+  dq?: string;
+  /** RSA JWK "e" (Exponent) Parameter */
+  e?: string;
+  /** Oct JWK "k" (Key Value) Parameter */
+  k?: string;
+  /** RSA JWK "n" (Modulus) Parameter */
+  n?: string;
+  /** Private RSA JWK "p" (First Prime Factor) Parameter */
+  p?: string;
+  /** Private RSA JWK "q" (Second Prime Factor) Parameter */
+  q?: string;
+  /** Private RSA JWK "qi" (First CRT Coefficient) Parameter */
+  qi?: string;
+  /**
+   * - EC JWK "x" (X Coordinate) Parameter
+   * - OKP JWK "x" (The public key) Parameter
+   */
+  x?: string;
+  /** EC JWK "y" (Y Coordinate) Parameter */
+  y?: string;
+  /** AKP JWK "pub" (Public Key) Parameter */
+  pub?: string;
+  /** AKP JWK "priv" (Private key) Parameter */
+  priv?: string;
 }
-//#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>;
+/**
+ * Flattened JWS definition for verify function inputs, allows payload as {@link !Uint8Array} for
+ * detached signature validation.
+ */
+interface FlattenedJWSInput {
+  /**
+   * The "header" member MUST be present and contain the value JWS Unprotected Header when the JWS
+   * Unprotected Header value is non- empty; otherwise, it MUST be absent. This value is represented
+   * as an unencoded JSON object, rather than as a string. These Header Parameter values are not
+   * integrity protected.
+   */
+  header?: JWSHeaderParameters;
+  /**
+   * The "payload" member MUST be present and contain the value BASE64URL(JWS Payload). When RFC7797
+   * "b64": false is used the value passed may also be a {@link !Uint8Array}.
+   */
+  payload: string | Uint8Array;
+  /**
+   * The "protected" member MUST be present and contain the value BASE64URL(UTF8(JWS Protected
+   * Header)) when the JWS Protected Header value is non-empty; otherwise, it MUST be absent. These
+   * Header Parameter values are integrity protected.
+   */
+  protected?: string;
+  /** The "signature" member MUST be present and contain the value BASE64URL(JWS Signature). */
+  signature: string;
+}
+/** Header Parameters common to JWE and JWS */
+interface JoseHeaderParameters {
+  /** "kid" (Key ID) Header Parameter */
+  kid?: string;
+  /** "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter */
+  x5t?: string;
+  /** "x5c" (X.509 Certificate Chain) Header Parameter */
+  x5c?: string[];
+  /** "x5u" (X.509 URL) Header Parameter */
+  x5u?: string;
+  /** "jku" (JWK Set URL) Header Parameter */
+  jku?: string;
+  /** "jwk" (JSON Web Key) Header Parameter */
+  jwk?: Pick<JWK, 'kty' | 'crv' | 'x' | 'y' | 'e' | 'n' | 'alg' | 'pub'>;
+  /** "typ" (Type) Header Parameter */
+  typ?: string;
+  /** "cty" (Content Type) Header Parameter */
+  cty?: string;
+}
+/** Recognized JWS Header Parameters, any other Header Members may also be present. */
+interface JWSHeaderParameters extends JoseHeaderParameters {
+  /**
+   * JWS "alg" (Algorithm) Header Parameter
+   *
+   * @see {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}
+   */
+  alg?: string;
+  /**
+   * This JWS Extension Header Parameter modifies the JWS Payload representation and the JWS Signing
+   * Input computation as per {@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}.
+   */
+  b64?: boolean;
+  /** JWS "crit" (Critical) Header Parameter */
+  crit?: string[];
+  /** Any other JWS Header member. */
+  [propName: string]: unknown;
+}
+/** Shared Interface with a "crit" property for all sign, verify, encrypt and decrypt operations. */
+interface CritOption {
+  /**
+   * An object with keys representing recognized "crit" (Critical) Header Parameter names. The value
+   * for those is either `true` or `false`. `true` when the Header Parameter MUST be integrity
+   * protected, `false` when it's irrelevant.
+   *
+   * This makes the "Extension Header Parameter "..." is not recognized" error go away.
+   *
+   * Use this when a given JWS/JWT/JWE profile requires the use of proprietary non-registered "crit"
+   * (Critical) Header Parameters. This will only make sure the Header Parameter is syntactically
+   * correct when provided and that it is optionally integrity protected. It will not process the
+   * Header Parameter in any way or reject the operation if it is missing. You MUST still verify the
+   * Header Parameter was present and process it according to the profile's validation steps after
+   * the operation succeeds.
+   *
+   * The JWS extension Header Parameter `b64` is always recognized and processed properly. No other
+   * registered Header Parameters that need this kind of default built-in treatment are currently
+   * available.
+   */
+  crit?: {
+    [propName: string]: boolean;
+  };
+}
+/** JWT Claims Set verification options. */
+interface JWTClaimVerificationOptions {
+  /**
+   * Expected JWT "aud" (Audience) Claim value(s).
+   *
+   * This option makes the JWT "aud" (Audience) Claim presence required.
+   */
+  audience?: string | string[];
+  /**
+   * Clock skew tolerance
+   *
+   * - In seconds when number (e.g. 5)
+   * - Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
+   *
+   * Used when validating the JWT "nbf" (Not Before) and "exp" (Expiration Time) claims, and when
+   * validating the "iat" (Issued At) claim if the {@link maxTokenAge `maxTokenAge` option} is set.
+   */
+  clockTolerance?: string | number;
+  /**
+   * Expected JWT "iss" (Issuer) Claim value(s).
+   *
+   * This option makes the JWT "iss" (Issuer) Claim presence required.
+   */
+  issuer?: string | string[];
+  /**
+   * Maximum time elapsed (in seconds) from the JWT "iat" (Issued At) Claim value.
+   *
+   * - In seconds when number (e.g. 5)
+   * - Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
+   *
+   * This option makes the JWT "iat" (Issued At) Claim presence required.
+   */
+  maxTokenAge?: string | number;
+  /**
+   * Expected JWT "sub" (Subject) Claim value.
+   *
+   * This option makes the JWT "sub" (Subject) Claim presence required.
+   */
+  subject?: string;
+  /**
+   * Expected JWT "typ" (Type) Header Parameter value.
+   *
+   * This option makes the JWT "typ" (Type) Header Parameter presence required.
+   */
+  typ?: string;
+  /** Date to use when comparing NumericDate claims, defaults to `new Date()`. */
+  currentDate?: Date;
+  /**
+   * Array of required Claim Names that must be present in the JWT Claims Set. Default is that: if
+   * the {@link issuer `issuer` option} is set, then JWT "iss" (Issuer) Claim must be present; if the
+   * {@link audience `audience` option} is set, then JWT "aud" (Audience) Claim must be present; if
+   * the {@link subject `subject` option} is set, then JWT "sub" (Subject) Claim must be present; if
+   * the {@link maxTokenAge `maxTokenAge` option} is set, then JWT "iat" (Issued At) Claim must be
+   * present.
+   */
+  requiredClaims?: string[];
+}
+/** JWS Verification options. */
+interface VerifyOptions extends CritOption {
+  /**
+   * A list of accepted JWS "alg" (Algorithm) Header Parameter values. By default all "alg"
+   * (Algorithm) values applicable for the used key/secret are allowed.
+   *
+   * > [!NOTE]\
+   * > Unsecured JWTs (`{ "alg": "none" }`) are never accepted by this API.
+   */
+  algorithms?: string[];
+}
+/** Recognized JWT Claims Set members, any other members may also be present. */
+interface JWTPayload {
+  /**
+   * JWT Issuer
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1 RFC7519#section-4.1.1}
+   */
+  iss?: string;
+  /**
+   * JWT Subject
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2 RFC7519#section-4.1.2}
+   */
+  sub?: string;
+  /**
+   * JWT Audience
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3 RFC7519#section-4.1.3}
+   */
+  aud?: string | string[];
+  /**
+   * JWT ID
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7 RFC7519#section-4.1.7}
+   */
+  jti?: string;
+  /**
+   * JWT Not Before
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5 RFC7519#section-4.1.5}
+   */
+  nbf?: number;
+  /**
+   * JWT Expiration Time
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4 RFC7519#section-4.1.4}
+   */
+  exp?: number;
+  /**
+   * JWT Issued At
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6 RFC7519#section-4.1.6}
+   */
+  iat?: number;
+  /** Any other JWT Claim Set member. */
+  [propName: string]: unknown;
+}
+/** Signed JSON Web Token (JWT) verification result */
+interface JWTVerifyResult<PayloadType = JWTPayload> {
+  /** JWT Claims Set. */
+  payload: PayloadType & JWTPayload;
+  /** JWS Protected Header. */
+  protectedHeader: JWTHeaderParameters;
+}
+/** Recognized Compact JWS Header Parameters, any other Header Members may also be present. */
+interface CompactJWSHeaderParameters extends JWSHeaderParameters {
+  alg: string;
+}
+/** Recognized Signed JWT Header Parameters, any other Header Members may also be present. */
+interface JWTHeaderParameters extends CompactJWSHeaderParameters {
+  b64?: true;
+}
+/** JSON Web Key Set */
+interface JSONWebKeySet {
+  keys: JWK[];
+}
+/**
+ * {@link !KeyObject} is a representation of a key/secret available in the Node.js runtime. You may
+ * use the Node.js runtime APIs {@link !createPublicKey}, {@link !createPrivateKey}, and
+ * {@link !createSecretKey} to obtain a {@link !KeyObject} from your existing key material.
+ */
+interface KeyObject {
+  type: string;
+}
+/**
+ * {@link !CryptoKey} is a representation of a key/secret available in all supported runtimes. In
+ * addition to the {@link key/import Key Import Functions} you may use the
+ * {@link !SubtleCrypto.importKey} API to obtain a {@link !CryptoKey} from your existing key
+ * material.
+ */
+type CryptoKey = Extract<Awaited<ReturnType<typeof crypto.subtle.generateKey>>, {
+  type: string;
 }>;
-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>;
+//#region ../../../../node_modules/jose/dist/types/jwt/verify.d.ts
+/** Combination of JWS Verification options and JWT Claims Set verification options. */
+interface JWTVerifyOptions extends VerifyOptions, JWTClaimVerificationOptions {}
 //#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;
@@ -152,10 +532,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 +567,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;
@@ -179,7 +582,7 @@ declare class SecurityProvider {
    * 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.
    *
@@ -314,72 +717,41 @@ interface SecurityCheckResult {
   ownership: string | boolean | undefined;
 }
 //#endregion
-//#region ../../src/security/primitives/$permission.d.ts
+//#region ../../src/security/primitives/$issuer.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
-/**
- * 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.
+   * 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);
-interface RealmSettings {
+} & (IssuerInternal | IssuerExternal);
+interface IssuerSettings {
   accessToken?: {
     /**
      * Lifetime of the access token.
@@ -407,33 +779,33 @@ interface RealmSettings {
   }>;
   onDeleteSession?: (refreshToken: string) => Promise<void>;
 }
-type RealmInternal = {
+type IssuerInternal = {
   /**
    * 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.
    */
   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>;
   /**
@@ -469,6 +841,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.
@@ -486,7 +892,7 @@ interface RolePrimitiveOptions {
    * Describe the role.
    */
   description?: string;
-  realm?: string | RealmPrimitive;
+  issuer?: string | IssuerPrimitive;
   permissions?: Array<string | {
     name: string;
     ownership?: boolean;
@@ -498,9 +904,9 @@ declare class RolePrimitive extends Primitive<RolePrimitiveOptions> {
   get name(): string;
   protected onInit(): void;
   /**
-   * Get the realm of the role.
+   * Get the issuer of the role.
    */
-  get realm(): string | RealmPrimitive | undefined;
+  get issuer(): string | IssuerPrimitive | undefined;
   can(permission: string | PermissionPrimitive): boolean;
   check(permission: string | PermissionPrimitive): SecurityCheckResult;
 }
@@ -540,7 +946,7 @@ type ServiceAccountPrimitiveOptions = {
 } & ({
   oauth2: Oauth2ServiceAccountPrimitiveOptions;
 } | {
-  realm: RealmPrimitive;
+  issuer: IssuerPrimitive;
   user: UserAccount;
 });
 interface Oauth2ServiceAccountPrimitiveOptions {
@@ -571,6 +977,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 +1017,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