alepha 0.15.0 → 0.15.2

package/dist/security/index.d.ts

@@ -1,10 +1,8 @@
 import * as alepha3 from "alepha";
 import { Alepha, KIND, Primitive, Static } from "alepha";
 import { FetchOptions, ServerRequest, ServerRouterProvider, UnauthorizedError } from "alepha/server";
-import * as alepha_logger2 from "alepha/logger";
+import * as alepha_logger0 from "alepha/logger";
 import { DateTimeProvider, Duration, DurationLike } from "alepha/datetime";
-import { CryptoKey, FlattenedJWSInput, JSONWebKeySet, JWSHeaderParameters, JWTHeaderParameters, JWTPayload, JWTVerifyResult, KeyObject } from "jose";
-import { JWTVerifyOptions } from "jose/jwt/verify";
 
 //#region ../../src/security/schemas/userAccountInfoSchema.d.ts
 declare const userAccountInfoSchema: alepha3.TObject<{
@@ -26,17 +24,17 @@ type UserAccount = Static<typeof userAccountInfoSchema>;
  */
 interface UserAccountToken extends UserAccount {
   /**
-       * Access token for the user.
-       */
+   * Access token for the user.
+   */
   token?: string;
   /**
-       * Realm name of the user.
-       */
+   * 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.
-       */
+   * Is user dedicated to his own resources for this scope ?
+   * Mostly, Admin is false and Customer is true.
+   */
   ownership?: string | boolean;
 }
 //#endregion
@@ -63,56 +61,84 @@ declare class SecurityError extends Error {
   readonly status = 403;
 }
 //#endregion
+//#region ../../src/security/interfaces/IssuerResolver.d.ts
+/**
+ * User info that a resolver returns.
+ * This is the input to `SecurityProvider.createUser()`.
+ */
+type UserInfo = Omit<UserAccount, "sessionId"> & {
+  sessionId?: string;
+};
+/**
+ * Resolver definition for authenticating users from requests.
+ */
+interface IssuerResolver {
+  /**
+   * Priority (lower = first). Default: 100
+   */
+  priority?: number;
+  /**
+   * Resolve user from HTTP request.
+   * Return UserInfo if authenticated, null to try next resolver.
+   * Throw UnauthorizedError to stop chain.
+   */
+  onRequest: (req: ServerRequest) => Promise<UserInfo | null>;
+}
+//#endregion
 //#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 identifier for this basic auth (default: property key).
+   */
   name?: string;
-  /** Path patterns to match (supports wildcards like /devtools/*) */
+  /**
+   * 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 log: alepha_logger0.Logger;
   protected readonly routerProvider: ServerRouterProvider;
   protected readonly realm = "Secure Area";
   /**
-       * Registered basic auth primitives with their configurations
-       */
+   * Registered basic auth primitives with their configurations
+   */
   readonly registeredAuths: BasicAuthPrimitiveConfig[];
   /**
-       * Register a basic auth configuration (called by primitives)
-       */
+   * 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
-       */
+   * Hook into server:onRequest to check basic auth
+   */
   readonly onRequest: alepha3.HookPrimitive<"server:onRequest">;
   /**
-       * Hook into action:onRequest to check basic auth for actions
-       */
+   * Hook into action:onRequest to check basic auth for actions
+   */
   readonly onActionRequest: alepha3.HookPrimitive<"action:onRequest">;
   /**
-       * Check basic authentication
-       */
+   * 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.
-       */
+   * 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.
-       */
+   * 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
-       */
+   * Send WWW-Authenticate header
+   */
   protected sendAuthRequired(request: ServerRequest): void;
 }
 declare const isBasicAuth: (value: unknown) => value is {
@@ -138,51 +164,376 @@ declare class BasicAuthPrimitive extends Primitive<BasicAuthPrimitiveConfig> imp
   get name(): string;
   protected onInit(): void;
   /**
-       * Checks basic auth for the given request using this primitive's configuration.
-       */
+   * Checks basic auth for the given request using this primitive's configuration.
+   */
   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;
+  /**
+   * JWK "alg" (Algorithm) Parameter
+   *
+   * @see {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}
+   */
+  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 {
+  /**
+   * - EC JWK "crv" (Curve) Parameter
+   * - OKP JWK "crv" (The Subtype of Key Pair) Parameter
+   */
+  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;
+}
+/**
+ * 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;
+}>;
+//#endregion
+//#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_logger2.Logger;
+  protected readonly log: alepha_logger0.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>;
@@ -244,7 +595,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_logger2.Logger;
+  protected readonly log: alepha_logger0.Logger;
   protected readonly jwt: JwtProvider;
   protected readonly env: {
     APP_SECRET: string;
@@ -252,122 +603,162 @@ 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: alepha3.HookPrimitive<"start">;
   /**
-       * Adds a role to one or more realms.
-       *
-       * @param role
-       * @param realms
-       */
+   * Creates a default JWT resolver for a realm.
+   */
+  protected createDefaultJwtResolver(realmName: string): IssuerResolver;
+  /**
+   * 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.
-       */
+   * Generic user creation from any source (JWT, API key, etc.).
+   * Handles permission checking, ownership, default roles.
+   */
+  createUser(userInfo: UserInfo, options?: {
+    realm?: string;
+    permission?: Permission | string;
+  }): UserAccountToken;
+  /**
+   * Register a resolver to a realm.
+   * Resolvers are sorted by priority (lower = first).
+   */
+  registerResolver(resolver: IssuerResolver, realmName?: string): void;
+  /**
+   * Get a realm by name.
+   * Throws if realm not found.
+   */
+  getRealm(realmName?: string): Realm;
+  /**
+   * Resolve user from request using registered resolvers.
+   * Returns undefined if no resolver could authenticate (no auth provided).
+   * Throws UnauthorizedError if auth was provided but invalid.
+   *
+   * Note: This method tries resolvers from ALL realms to find a match,
+   * regardless of the `realm` option. The `realm` option is only used for
+   * permission checking after the user is resolved.
+   */
+  resolveUserFromServerRequest(req: {
+    url: URL | string;
+    headers: {
+      authorization?: string;
+    };
+  }, options?: {
+    realm?: string;
+    permission?: Permission | string;
+  }): Promise<UserAccountToken | undefined>;
+  /**
+   * 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;
 }
@@ -378,16 +769,20 @@ 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;
+  /**
+   * Custom resolvers for this realm (sorted by priority).
+   */
+  resolvers?: IssuerResolver[];
 }
 interface SecurityCheckResult {
   isAuthorized: boolean;
@@ -407,40 +802,44 @@ declare const $issuer: {
 };
 type IssuerPrimitiveOptions = {
   /**
-       * Define the issuer 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 issuer.
-       */
+   * Short description about the issuer.
+   */
   description?: string;
   /**
-       * All roles available in the issuer. 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>;
   /**
-       * Issuer settings.
-       */
+   * 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;
+  /**
+   * Custom resolvers (in addition to default JWT resolver).
+   */
+  resolvers?: IssuerResolver[];
 } & (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: {
@@ -458,41 +857,50 @@ interface IssuerSettings {
 }
 type IssuerInternal = {
   /**
-       * Internal secret to sign JWT tokens and verify them.
-       */
+   * Internal secret to sign JWT tokens and verify them.
+   */
   secret: string;
 };
 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 IssuerPrimitive extends Primitive<IssuerPrimitiveOptions> {
   protected readonly securityProvider: SecurityProvider;
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly jwt: JwtProvider;
-  protected readonly log: alepha_logger2.Logger;
+  protected readonly log: alepha_logger0.Logger;
   get name(): string;
   get accessTokenExpiration(): Duration;
   get refreshTokenExpiration(): Duration;
   protected onInit(): void;
   /**
-       * Get all roles in the issuer.
-       */
+   * Creates the default JWT resolver.
+   */
+  protected createJwtResolver(): IssuerResolver;
+  /**
+   * Register a resolver to this issuer.
+   * Resolvers are sorted by priority (lower = first).
+   */
+  registerResolver(resolver: IssuerResolver): void;
+  /**
+   * Get all roles in the issuer.
+   */
   getRoles(): Role[];
   /**
-       * Set all roles in the issuer.
-       */
+   * 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;
@@ -528,16 +936,16 @@ declare const $permission: {
 };
 interface PermissionPrimitiveOptions {
   /**
-       * Name of the permission. Use Property name is not provided.
-       */
+   * Name of the permission. Use Property name is not provided.
+   */
   name?: string;
   /**
-       * Group of the permission. Use Class name is not provided.
-       */
+   * Group of the permission. Use Class name is not provided.
+   */
   group?: string;
   /**
-       * Describe the permission.
-       */
+   * Describe the permission.
+   */
   description?: string;
 }
 declare class PermissionPrimitive extends Primitive<PermissionPrimitiveOptions> {
@@ -547,8 +955,8 @@ declare class PermissionPrimitive extends Primitive<PermissionPrimitiveOptions>
   toString(): string;
   protected onInit(): void;
   /**
-       * Check if the user has the permission.
-       */
+   * Check if the user has the permission.
+   */
   can(user?: UserAccount): boolean;
 }
 //#endregion
@@ -562,12 +970,12 @@ declare const $role: {
 };
 interface RolePrimitiveOptions {
   /**
-       * Name of the role.
-       */
+   * Name of the role.
+   */
   name?: string;
   /**
-       * Describe the role.
-       */
+   * Describe the role.
+   */
   description?: string;
   issuer?: string | IssuerPrimitive;
   permissions?: Array<string | {
@@ -581,8 +989,8 @@ declare class RolePrimitive extends Primitive<RolePrimitiveOptions> {
   get name(): string;
   protected onInit(): void;
   /**
-       * Get the issuer of the role.
-       */
+   * Get the issuer of the role.
+   */
   get issuer(): string | IssuerPrimitive | undefined;
   can(permission: string | PermissionPrimitive): boolean;
   check(permission: string | PermissionPrimitive): SecurityCheckResult;
@@ -628,16 +1036,16 @@ type ServiceAccountPrimitiveOptions = {
 });
 interface Oauth2ServiceAccountPrimitiveOptions {
   /**
-       * Get Token URL.
-       */
+   * Get Token URL.
+   */
   url: string;
   /**
-       * Client ID.
-       */
+   * Client ID.
+   */
   clientId: string;
   /**
-       * Client Secret.
-       */
+   * Client Secret.
+   */
   clientSecret: string;
 }
 interface ServiceAccountPrimitive {
@@ -656,25 +1064,26 @@ declare class CryptoProvider {
 //#endregion
 //#region ../../src/security/providers/ServerSecurityProvider.d.ts
 declare class ServerSecurityProvider {
-  protected readonly log: alepha_logger2.Logger;
+  protected readonly log: alepha_logger0.Logger;
   protected readonly securityProvider: SecurityProvider;
   protected readonly jwtProvider: JwtProvider;
   protected readonly alepha: Alepha;
+  protected readonly resolvers: Array<ServerSecurityUserResolver>;
   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.
-       */
+   * 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;
@@ -685,6 +1094,7 @@ type ServerRouteSecure = {
   realm?: string;
   basic?: BasicAuthOptions;
 };
+type ServerSecurityUserResolver = (request: ServerRequest) => Promise<UserAccountToken | undefined>;
 //#endregion
 //#region ../../src/security/index.d.ts
 declare module "alepha" {
@@ -696,17 +1106,17 @@ declare module "alepha" {
   }
   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.
-             */
+     * 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
-             */
+     * The authenticated user account attached to the server request state.
+     *
+     * @internal
+     */
     "alepha.server.request.user"?: UserAccount;
   }
 }
@@ -719,36 +1129,40 @@ declare module "alepha/server" {
   }
   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.
-             */
+     * 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.
-             */
+     * 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.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | epic | stable |
  *
- * 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.
+ * Complete authentication and authorization system with JWT, RBAC, and multi-issuer support.
  *
- * When used with `AlephaServer`, this module automatically registers `ServerSecurityProvider` and `ServerBasicAuthProvider`
- * to protect HTTP routes and actions with JWT and Basic Auth.
+ * **Features:**
+ * - JWT token issuer with role definitions
+ * - Role-based access control (RBAC)
+ * - Fine-grained permissions
+ * - HTTP Basic Authentication
+ * - Service-to-service authentication
+ * - Multi-issuer support for federated auth
+ * - JWKS (JSON Web Key Set) for external issuers
+ * - Token refresh logic
+ * - User profile extraction from JWT
  *
- * @see {@link $issuer}
- * @see {@link $role}
- * @see {@link $permission}
- * @see {@link $basicAuth}
  * @module alepha.security
  */
 declare const AlephaSecurity: alepha3.Service<alepha3.Module>;
@@ -757,5 +1171,5 @@ declare const AlephaSecurity: alepha3.Service<alepha3.Module>;
  */
 declare const AlephaServerSecurity: alepha3.Service<alepha3.Module>;
 //#endregion
-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 };
+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, IssuerResolver, IssuerSettings, JwtParseResult, JwtProvider, JwtSignOptions, KeyLoader, KeyLoaderHolder, Oauth2ServiceAccountPrimitiveOptions, Permission, PermissionPrimitive, PermissionPrimitiveOptions, Realm, Role, RolePrimitive, RolePrimitiveOptions, SecurityCheckResult, SecurityError, SecurityProvider, ServerBasicAuthProvider, ServerRouteSecure, ServerSecurityProvider, ServerSecurityUserResolver, ServiceAccountPrimitive, ServiceAccountPrimitiveOptions, ServiceAccountStore, UserAccount, UserAccountToken, UserInfo, isBasicAuth, permissionSchema, roleSchema, userAccountInfoSchema };
 //# sourceMappingURL=index.d.ts.map