@kurdel/auth 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/password/password-authentication-service.d.ts

@@ -2,10 +2,39 @@ import type { AuthUser } from '@kurdel/common';
 import type { PasswordCredentialRepository } from '../repositories/password/index.js';
 import type { AuthUserRepository } from '../repositories/user/index.js';
 import type { PasswordHasher } from './password-hasher.js';
+/**
+ * ## PasswordAuthenticationService
+ *
+ * Coordinates password-based authentication.
+ *
+ * Responsibilities:
+ * - resolve password credentials from an application-defined login
+ * - verify the presented password
+ * - resolve the current authenticated user
+ *
+ * Guarantees:
+ * - unknown credentials never authenticate
+ * - invalid passwords never authenticate
+ * - user identity is resolved only after successful password verification
+ *
+ * Non-responsibilities:
+ * - password persistence
+ * - password hashing implementation
+ * - user management
+ */
 export declare class PasswordAuthenticationService {
     private readonly credentials;
     private readonly users;
     private readonly hasher;
     constructor(credentials: PasswordCredentialRepository, users: AuthUserRepository, hasher: PasswordHasher);
+    /**
+     * Authenticates a user using a login identifier and password.
+     *
+     * Returns `null` when the login cannot be authenticated or the
+     * associated user is unavailable.
+     *
+     * Unknown logins intentionally perform a password hashing operation
+     * before returning to reduce observable timing differences.
+     */
     authenticate(login: string, password: string): Promise<AuthUser | null>;
 }

package/lib/password/password-authentication-service.js

@@ -1,9 +1,38 @@
+/**
+ * ## PasswordAuthenticationService
+ *
+ * Coordinates password-based authentication.
+ *
+ * Responsibilities:
+ * - resolve password credentials from an application-defined login
+ * - verify the presented password
+ * - resolve the current authenticated user
+ *
+ * Guarantees:
+ * - unknown credentials never authenticate
+ * - invalid passwords never authenticate
+ * - user identity is resolved only after successful password verification
+ *
+ * Non-responsibilities:
+ * - password persistence
+ * - password hashing implementation
+ * - user management
+ */
 export class PasswordAuthenticationService {
     constructor(credentials, users, hasher) {
         this.credentials = credentials;
         this.users = users;
         this.hasher = hasher;
     }
+    /**
+     * Authenticates a user using a login identifier and password.
+     *
+     * Returns `null` when the login cannot be authenticated or the
+     * associated user is unavailable.
+     *
+     * Unknown logins intentionally perform a password hashing operation
+     * before returning to reduce observable timing differences.
+     */
     async authenticate(login, password) {
         const credential = await this.credentials.findByLogin(login);
         if (!credential) {
@@ -11,8 +40,9 @@ export class PasswordAuthenticationService {
             await this.hasher.hash(password);
             return null;
         }
-        if (!(await this.hasher.verify(password, credential.passwordHash)))
+        if (!(await this.hasher.verify(password, credential.passwordHash))) {
             return null;
+        }
         return this.users.findById(credential.userId);
     }
 }

package/lib/password/password-authentication-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"password-authentication-service.js","sourceRoot":"","sources":["../../src/password/password-authentication-service.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,6BAA6B;IACxC,YACmB,WAAyC,EACzC,KAAyB,EACzB,MAAsB;QAFtB,gBAAW,GAAX,WAAW,CAA8B;QACzC,UAAK,GAAL,KAAK,CAAoB;QACzB,WAAM,GAAN,MAAM,CAAgB;IACtC,CAAC;IAEJ,KAAK,CAAC,YAAY,CAAC,KAAa,EAAE,QAAgB;QAChD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC7D,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,uEAAuE;YACvE,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACjC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAChF,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;CACF"}
+{"version":3,"file":"password-authentication-service.js","sourceRoot":"","sources":["../../src/password/password-authentication-service.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,6BAA6B;IACxC,YACmB,WAAyC,EACzC,KAAyB,EACzB,MAAsB;QAFtB,gBAAW,GAAX,WAAW,CAA8B;QACzC,UAAK,GAAL,KAAK,CAAoB;QACzB,WAAM,GAAN,MAAM,CAAgB;IACtC,CAAC;IAEJ;;;;;;;;OAQG;IACH,KAAK,CAAC,YAAY,CAAC,KAAa,EAAE,QAAgB;QAChD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAE7D,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,uEAAuE;YACvE,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACjC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;YACnE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;CACF"}

package/lib/password/password-hasher.d.ts

@@ -1,4 +1,22 @@
+/**
+ * ## PasswordHasher
+ *
+ * Hashes and verifies passwords.
+ *
+ * Implementations are responsible only for password hashing and
+ * verification. They neither manage password persistence nor enforce
+ * application-specific password policies.
+ */
 export interface PasswordHasher {
+    /**
+     * Derives a password hash suitable for persistent storage.
+     */
     hash(password: string): Promise<string> | string;
+    /**
+     * Verifies a password against a previously generated hash.
+     *
+     * Returns `false` when the password does not match or the encoded
+     * hash cannot be verified.
+     */
     verify(password: string, encodedHash: string): Promise<boolean> | boolean;
 }

package/lib/password/scrypt-password-hasher.d.ts

@@ -1,12 +1,44 @@
 import type { PasswordHasher } from './password-hasher.js';
+/**
+ * ## ScryptPasswordHasherOptions
+ *
+ * Configures password hashing parameters.
+ *
+ * The defaults follow conservative values suitable for general-purpose
+ * password authentication.
+ */
 export interface ScryptPasswordHasherOptions {
+    /** CPU/memory cost parameter (`N`). */
     cost?: number;
+    /** Block size parameter (`r`). */
     blockSize?: number;
+    /** Parallelization parameter (`p`). */
     parallelization?: number;
+    /** Derived key length in bytes. */
     keyLength?: number;
+    /** Random salt length in bytes. */
     saltLength?: number;
 }
-/** Password hasher with a self-describing format that supports future rehashing. */
+/**
+ * ## ScryptPasswordHasher
+ *
+ * Password hasher based on the scrypt key derivation function.
+ *
+ * Responsibilities:
+ * - derive password hashes using scrypt
+ * - verify passwords against persisted hashes
+ * - embed hashing parameters into the stored hash format
+ *
+ * Guarantees:
+ * - every generated hash uses a cryptographically secure random salt
+ * - password verification uses constant-time comparison
+ * - malformed or unsupported hashes never authenticate
+ *
+ * Non-responsibilities:
+ * - password persistence
+ * - password policy enforcement
+ * - credential management
+ */
 export declare class ScryptPasswordHasher implements PasswordHasher {
     private readonly cost;
     private readonly blockSize;
@@ -14,7 +46,20 @@ export declare class ScryptPasswordHasher implements PasswordHasher {
     private readonly keyLength;
     private readonly saltLength;
     constructor(options?: ScryptPasswordHasherOptions);
+    /**
+     * Derives a self-describing password hash.
+     *
+     * The resulting hash embeds the algorithm, parameters, salt,
+     * and derived key, allowing future verification without
+     * additional metadata.
+     */
     hash(password: string): Promise<string>;
+    /**
+     * Verifies a password against a previously generated hash.
+     *
+     * Returns `false` for malformed hashes, unsupported parameters,
+     * or verification failures.
+     */
     verify(password: string, encodedHash: string): Promise<boolean>;
     private derive;
     private validParameters;

package/lib/password/scrypt-password-hasher.js

@@ -1,5 +1,24 @@
 import crypto from 'node:crypto';
-/** Password hasher with a self-describing format that supports future rehashing. */
+/**
+ * ## ScryptPasswordHasher
+ *
+ * Password hasher based on the scrypt key derivation function.
+ *
+ * Responsibilities:
+ * - derive password hashes using scrypt
+ * - verify passwords against persisted hashes
+ * - embed hashing parameters into the stored hash format
+ *
+ * Guarantees:
+ * - every generated hash uses a cryptographically secure random salt
+ * - password verification uses constant-time comparison
+ * - malformed or unsupported hashes never authenticate
+ *
+ * Non-responsibilities:
+ * - password persistence
+ * - password policy enforcement
+ * - credential management
+ */
 export class ScryptPasswordHasher {
     constructor(options = {}) {
         this.cost = options.cost ?? 16384;
@@ -8,6 +27,13 @@ export class ScryptPasswordHasher {
         this.keyLength = options.keyLength ?? 64;
         this.saltLength = options.saltLength ?? 16;
     }
+    /**
+     * Derives a self-describing password hash.
+     *
+     * The resulting hash embeds the algorithm, parameters, salt,
+     * and derived key, allowing future verification without
+     * additional metadata.
+     */
     async hash(password) {
         const salt = crypto.randomBytes(this.saltLength);
         const derived = await this.derive(password, salt, this.cost, this.blockSize, this.parallelization, this.keyLength);
@@ -20,6 +46,12 @@ export class ScryptPasswordHasher {
             derived.toString('base64url'),
         ].join('$');
     }
+    /**
+     * Verifies a password against a previously generated hash.
+     *
+     * Returns `false` for malformed hashes, unsupported parameters,
+     * or verification failures.
+     */
     async verify(password, encodedHash) {
         const parts = encodedHash.split('$');
         if (parts.length !== 6 || parts[0] !== 'scrypt')

package/lib/password/scrypt-password-hasher.js.map

@@ -1 +1 @@
-{"version":3,"file":"scrypt-password-hasher.js","sourceRoot":"","sources":["../../src/password/scrypt-password-hasher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scrypt-password-hasher.js","sourceRoot":"","sources":["../../src/password/scrypt-password-hasher.ts"],"names":[],"mappings":"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"}

package/lib/repositories/api-key/api-key-repository.d.ts

@@ -1,30 +1,40 @@
+/**
+ * ## ApiKeyCredential
+ *
+ * Metadata describing an API key after successful lookup.
+ *
+ * The credential contains only the information required for
+ * authentication. User identity, roles, and permissions are resolved
+ * separately through {@link AuthUserRepository}.
+ */
 export interface ApiKeyCredential {
     /** Stable credential identifier, when the backing store exposes one. */
     id?: string;
-    /** Stable identity resolved after credential validation. */
+    /** Identifier of the associated application user. */
     userId: string | number;
-    /** Revoked credentials must never authenticate. */
+    /** Indicates whether the credential has been revoked. */
     revoked?: boolean;
-    /** Optional absolute expiry time. */
+    /** Optional absolute expiration time. */
     expiresAt?: Date;
 }
 /**
  * ## ApiKeyRepository
  *
- * Abstraction for retrieving credential metadata by API key.
+ * Resolves API-key credentials from presented secrets.
  *
- * A repository implementation may:
- * - load records from an in-memory map
- * - query a database
- * - read from Redis or any other KV store
- * - call an external authentication service
+ * Implementations may retrieve credentials from any backing store,
+ * including databases, in-memory collections, key-value stores, or
+ * external authentication services.
  *
- * Strategies depend only on this interface, not on the storage details.
+ * The returned credential contains only authentication metadata.
+ * Authorization data is resolved separately through
+ * {@link AuthUserRepository}.
  */
 export interface ApiKeyRepository {
     /**
-     * Returns credential metadata associated with the given API key.
-     * If the key is unknown, must return `null`.
+     * Resolves the credential associated with an API key.
+     *
+     * Returns `null` when the key is unknown or cannot be authenticated.
      */
     findByKey(key: string): Promise<ApiKeyCredential | null> | ApiKeyCredential | null;
 }

package/lib/repositories/api-key/api-key-usage-recorder.d.ts

@@ -1,4 +1,15 @@
-/** Persists successful API-key usage without coupling strategies to storage. */
+/**
+ * ## ApiKeyUsageRecorder
+ *
+ * Records successful API-key authentication events.
+ *
+ * Implementations may persist usage information in any backing store,
+ * such as a database or cache, without coupling authentication
+ * strategies to storage details.
+ */
 export interface ApiKeyUsageRecorder {
+    /**
+     * Records the successful use of an API-key credential.
+     */
     recordUsage(credentialId: string, usedAt: Date): Promise<void> | void;
 }

package/lib/repositories/jwt/jwt-repository.d.ts

@@ -1,3 +1,9 @@
 import type { AuthUserRepository } from '../../repositories/user/index.js';
-/** @deprecated Use AuthUserRepository. JWT is a credential, not a user store. */
+/**
+ * @deprecated Use {@link AuthUserRepository} instead.
+ *
+ * This alias reflected an earlier design where JWT authentication was
+ * coupled to user lookup. User identity is now resolved independently
+ * of the presented credential.
+ */
 export type JwtRepository = AuthUserRepository;

package/lib/repositories/jwt/jwt-session-repository.d.ts

@@ -1,10 +1,34 @@
-export type JwtSession = {
+/**
+ * ## JwtSession
+ *
+ * Server-side state associated with a JWT through its `jti` claim.
+ *
+ * The session allows signed tokens to be revoked before their
+ * cryptographic expiration without maintaining server-side token data.
+ */
+export interface JwtSession {
+    /** Stable session identifier referenced by the JWT `jti` claim. */
     id: string;
+    /** Identifier of the associated application user. */
     userId: string | number;
+    /** Indicates whether the session has been revoked. */
     revoked: boolean;
+    /** Optional server-side expiration time. */
     expiresAt?: Date;
-};
-/** Resolves server-side JWT session state used for token revocation. */
+}
+/**
+ * ## JwtSessionRepository
+ *
+ * Resolves the current state of server-side JWT sessions.
+ *
+ * Implementations expose whether a session exists, has been revoked,
+ * or has expired independently of the JWT itself.
+ */
 export interface JwtSessionRepository {
+    /**
+     * Resolves a JWT session by its identifier.
+     *
+     * Returns `null` when the session does not exist.
+     */
     findById(id: string): Promise<JwtSession | null>;
 }

package/lib/repositories/password/password-credential-repository.d.ts

@@ -1,8 +1,32 @@
+/**
+ * ## PasswordCredential
+ *
+ * Password credential associated with an application user.
+ *
+ * The credential contains only the information required for password
+ * verification. User identity, roles, and permissions are resolved
+ * separately through {@link AuthUserRepository}.
+ */
 export interface PasswordCredential {
+    /** Identifier of the associated application user. */
     userId: string | number;
+    /** Persisted password hash. */
     passwordHash: string;
 }
-/** Resolves a password credential by an application-defined login. */
+/**
+ * ## PasswordCredentialRepository
+ *
+ * Resolves password credentials from an application-defined login.
+ *
+ * The login identifier is application-specific (for example, an email
+ * address or username). Implementations are responsible for mapping the
+ * supplied login to the corresponding credential.
+ */
 export interface PasswordCredentialRepository {
+    /**
+     * Resolves the password credential associated with a login.
+     *
+     * Returns `null` when the login cannot be authenticated.
+     */
     findByLogin(login: string): Promise<PasswordCredential | null> | PasswordCredential | null;
 }

package/lib/repositories/user/auth-user-repository.d.ts

@@ -1,11 +1,23 @@
 import type { AuthUser } from '@kurdel/common';
 /**
- * Resolves the current application identity used for authorization.
+ * ## AuthUserRepository
  *
- * Implementations exclude identities that must not authenticate, such as
- * disabled or deleted users. Roles come from this source of truth rather than
- * from the presented credential.
+ * Resolves the current application identity for authentication and
+ * authorization.
+ *
+ * Implementations expose the application's current source of truth.
+ * Users that are no longer allowed to authenticate (for example,
+ * disabled or deleted accounts) should not be returned.
+ *
+ * Authorization data such as roles and permissions is resolved from
+ * this repository rather than from the presented credential.
  */
 export interface AuthUserRepository {
+    /**
+    * Resolves the current authenticated user by identifier.
+    *
+    * Returns `null` when the user does not exist or is no longer
+    * eligible for authentication.
+    */
     findById(id: string | number): Promise<AuthUser | null> | AuthUser | null;
 }

package/lib/runtime/auth-module.d.ts

@@ -4,19 +4,14 @@ import { type AuthEventSinkProvider, type AuthStrategyProvider, type Authorizati
 /**
  * ## AuthModuleConfig
  *
- * Defines authentication strategies supplied by the application.
+ * Configures authentication infrastructure provided by `AuthModule`.
  *
- * Example:
- * ```ts
- * new AuthModule({
- *   strategies: [
- *     { name: 'api-key', use: new ApiKeyStrategy({...}) },
- *     { name: 'jwt', use: new JwtStrategy({...}) },
- *   ]
- * })
- * ```
+ * Applications declare:
+ * - authentication strategies
+ * - authorization policies
+ * - optional authentication event sink
  *
- * Strategies are registered **once** during module initialization.
+ * All configured components are registered once during application startup.
  */
 export interface AuthModuleConfig {
     /** List of user-provided authentication strategies. */
@@ -29,36 +24,45 @@ export interface AuthModuleConfig {
 /**
  * ## AuthModule
  *
+ * Registers the authentication runtime.
+ *
  * Provides:
- * - singleton `AuthStrategyRegistry`
- * - automatic registration of configured strategies
+ * - AuthStrategyRegistry
+ * - AuthorizationPolicyRegistry
+ * - AuthEventSink
+ *
+ * Registers:
+ * - authentication middleware
  *
  * Responsibilities:
- * - expose a DI-managed registry storing all auth strategies
- * - populate it during `register()`
+ * - register configured strategies
+ * - register configured authorization policies
+ * - register the authentication middleware
+ * - expose authentication infrastructure through DI
  *
- * Non-responsibilities:
- * - no transport logic
- * - no middleware ordering
- * - no policy evaluation
+ * Guarantees:
+ * - configured strategies are registered exactly once
+ * - configured policies are registered exactly once
+ * - authentication middleware is installed in the `auth` zone
+ * - an `AuthEventSink` is always available
  *
- * Identity repositories, credentials and strategy-specific services are
- * application concerns and must be supplied outside this module.
+ * Non-responsibilities:
+ * - credential persistence
+ * - authentication implementations
+ * - authorization decisions
+ * - user management
  */
 export declare class AuthModule implements AppModule<AuthModuleConfig> {
     private readonly config;
     readonly priority = ModulePriority.Auth;
-    /**
-     * Providers exposed by the module.
-     *
-     * - `StrategyRegistry` → a singleton container of auth strategies
-     */
     readonly providers: ProviderConfig[];
     constructor(config?: AuthModuleConfig);
     /**
-     * Registers all configured authentication strategies.
+     * Registers authentication runtime components.
      *
-     * Called once during app startup.
+     * 1. Registers authentication strategies.
+     * 2️. Registers authorization policies.
+     * 3️. Installs the authentication middleware.
      */
     register(ioc: Container): Promise<void>;
 }

package/lib/runtime/auth-module.js

@@ -6,21 +6,33 @@ import { AUTH_TOKENS } from '../tokens.js';
 /**
  * ## AuthModule
  *
+ * Registers the authentication runtime.
+ *
  * Provides:
- * - singleton `AuthStrategyRegistry`
- * - automatic registration of configured strategies
+ * - AuthStrategyRegistry
+ * - AuthorizationPolicyRegistry
+ * - AuthEventSink
+ *
+ * Registers:
+ * - authentication middleware
  *
  * Responsibilities:
- * - expose a DI-managed registry storing all auth strategies
- * - populate it during `register()`
+ * - register configured strategies
+ * - register configured authorization policies
+ * - register the authentication middleware
+ * - expose authentication infrastructure through DI
  *
- * Non-responsibilities:
- * - no transport logic
- * - no middleware ordering
- * - no policy evaluation
+ * Guarantees:
+ * - configured strategies are registered exactly once
+ * - configured policies are registered exactly once
+ * - authentication middleware is installed in the `auth` zone
+ * - an `AuthEventSink` is always available
  *
- * Identity repositories, credentials and strategy-specific services are
- * application concerns and must be supplied outside this module.
+ * Non-responsibilities:
+ * - credential persistence
+ * - authentication implementations
+ * - authorization decisions
+ * - user management
  */
 export class AuthModule {
     constructor(config = {}) {
@@ -51,9 +63,11 @@ export class AuthModule {
         ];
     }
     /**
-     * Registers all configured authentication strategies.
+     * Registers authentication runtime components.
      *
-     * Called once during app startup.
+     * 1. Registers authentication strategies.
+     * 2️. Registers authorization policies.
+     * 3️. Installs the authentication middleware.
      */
     async register(ioc) {
         const registry = ioc.get(AUTH_TOKENS.StrategyRegistry);

package/lib/runtime/auth-module.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-module.js","sourceRoot":"","sources":["../../src/runtime/auth-module.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAuC,MAAM,kBAAkB,CAAC;AAEvF,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,OAAO,EACL,iBAAiB,GAKlB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AA4B5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,UAAU;IAUrB,YAA6B,SAA2B,EAAE;QAA7B,WAAM,GAAN,MAAM,CAAuB;QATjD,aAAQ,GAAG,cAAc,CAAC,IAAI,CAAC;QAUtC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG;YACf;gBACE,OAAO,EAAE,WAAW,CAAC,gBAAgB;gBACrC,QAAQ,EAAE,oBAAoB;gBAC9B,SAAS,EAAE,IAAI;aAChB;YACD;gBACE,OAAO,EAAE,WAAW,CAAC,cAAc;gBACnC,QAAQ,EAAE,2BAA2B;gBACrC,SAAS,EAAE,IAAI;aAChB;YACD,SAAS,IAAI,YAAY,IAAI,SAAS;gBACpC,CAAC,CAAC;oBACE,OAAO,EAAE,WAAW,CAAC,SAAS;oBAC9B,UAAU,EAAE,SAAS,CAAC,UAAU;oBAChC,SAAS,EAAE,IAAI;iBAChB;gBACH,CAAC,CAAC;oBACE,OAAO,EAAE,WAAW,CAAC,SAAS;oBAC9B,WAAW,EAAE,SAAS,EAAE,GAAG,IAAI,IAAI,iBAAiB,EAAE;iBACvD;SACN,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,GAAc;QAC3B,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAuB,WAAW,CAAC,gBAAgB,CAAC,CAAC;QAC7E,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAA8B,WAAW,CAAC,cAAc,CAAC,CAAC;QAClF,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAgB,WAAW,CAAC,SAAS,CAAC,CAAC;QAE7D,2BAA2B;QAC3B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;YAC7C,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBACf,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACN,MAAM,QAAQ,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBACnC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;QAED,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;YAChD,QAAQ,CAAC,QAAQ,CACf,MAAM,CAAC,IAAI,EACX,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CACtD,CAAC;QACJ,CAAC;QAED,kCAAkC;QAClC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAqB,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACrE,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE;YAC1D,IAAI,EAAE,MAAM;YACZ,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"auth-module.js","sourceRoot":"","sources":["../../src/runtime/auth-module.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAuC,MAAM,kBAAkB,CAAC;AAEvF,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,OAAO,EACL,iBAAiB,GAKlB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAuB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,UAAU;IAKrB,YAA6B,SAA2B,EAAE;QAA7B,WAAM,GAAN,MAAM,CAAuB;QAJjD,aAAQ,GAAG,cAAc,CAAC,IAAI,CAAC;QAKtC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG;YACf;gBACE,OAAO,EAAE,WAAW,CAAC,gBAAgB;gBACrC,QAAQ,EAAE,oBAAoB;gBAC9B,SAAS,EAAE,IAAI;aAChB;YACD;gBACE,OAAO,EAAE,WAAW,CAAC,cAAc;gBACnC,QAAQ,EAAE,2BAA2B;gBACrC,SAAS,EAAE,IAAI;aAChB;YACD,SAAS,IAAI,YAAY,IAAI,SAAS;gBACpC,CAAC,CAAC;oBACE,OAAO,EAAE,WAAW,CAAC,SAAS;oBAC9B,UAAU,EAAE,SAAS,CAAC,UAAU;oBAChC,SAAS,EAAE,IAAI;iBAChB;gBACH,CAAC,CAAC;oBACE,OAAO,EAAE,WAAW,CAAC,SAAS;oBAC9B,WAAW,EAAE,SAAS,EAAE,GAAG,IAAI,IAAI,iBAAiB,EAAE;iBACvD;SACN,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAC,GAAc;QAC3B,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAuB,WAAW,CAAC,gBAAgB,CAAC,CAAC;QAC7E,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAA8B,WAAW,CAAC,cAAc,CAAC,CAAC;QAClF,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAgB,WAAW,CAAC,SAAS,CAAC,CAAC;QAE7D,2BAA2B;QAC3B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;YAC7C,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBACf,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACN,MAAM,QAAQ,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBACnC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;QAED,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;YAChD,QAAQ,CAAC,QAAQ,CACf,MAAM,CAAC,IAAI,EACX,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CACtD,CAAC;QACJ,CAAC;QAED,kCAAkC;QAClC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAqB,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACrE,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE;YAC1D,IAAI,EAAE,MAAM;YACZ,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC;CACF"}

package/lib/runtime/auth-strategy-registry.d.ts

@@ -2,24 +2,41 @@ import type { AuthStrategy } from '../domain/index.js';
 /**
  * ## AuthStrategyRegistry
  *
- * Holds named authentication strategies (e.g. `jwt`, `apikey`, `session`).
- * Strategies are resolved by middleware per request.
+ * Stores authentication strategies by name.
+ *
+ * Responsibilities:
+ * - register authentication strategies during application startup
+ * - resolve strategies by name during request processing
+ * - allow strategies to be replaced or removed if required
+ *
+ * Guarantees:
+ * - at most one strategy exists for a given name
+ * - registering an existing name replaces the previous strategy
+ *
+ * Non-responsibilities:
+ * - strategy execution
+ * - authentication orchestration
+ * - request handling
  */
 export declare class AuthStrategyRegistry {
     private readonly strategies;
     /**
-     * Registers a new authentication strategy.
+     * Registers or replaces an authentication strategy.
      *
-     * @param name - Strategy identifier (e.g. "jwt", "apikey").
-     * @param strategy - Implementation of {@link AuthStrategy}.
+     * @param name Strategy identifier.
+     * @param strategy Authentication strategy implementation.
      */
     register(name: string, strategy: AuthStrategy): void;
     /**
-     * Returns a strategy by name, if registered.
+     * Returns the strategy registered under the specified name.
+     *
+     * @param name Strategy identifier.
      */
     get(name: string): AuthStrategy | undefined;
     /**
-     * Removes a strategy (rarely used).
+     * Removes the strategy associated with the specified name.
+     *
+     * @param name Strategy identifier.
      */
     unregister(name: string): void;
 }