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

package/lib/runtime/auth-strategy-registry.js

@@ -1,30 +1,47 @@
 /**
  * ## 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 class AuthStrategyRegistry {
     constructor() {
         this.strategies = new Map();
     }
     /**
-     * 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, strategy) {
         this.strategies.set(name, strategy);
     }
     /**
-     * Returns a strategy by name, if registered.
+     * Returns the strategy registered under the specified name.
+     *
+     * @param name Strategy identifier.
      */
     get(name) {
         return this.strategies.get(name);
     }
     /**
-     * Removes a strategy (rarely used).
+     * Removes the strategy associated with the specified name.
+     *
+     * @param name Strategy identifier.
      */
     unregister(name) {
         this.strategies.delete(name);

package/lib/runtime/auth-strategy-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-strategy-registry.js","sourceRoot":"","sources":["../../src/runtime/auth-strategy-registry.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAAjC;QACmB,eAAU,GAAG,IAAI,GAAG,EAAwB,CAAC;IAyBhE,CAAC;IAvBC;;;;;OAKG;IACH,QAAQ,CAAC,IAAY,EAAE,QAAsB;QAC3C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF"}
+{"version":3,"file":"auth-strategy-registry.js","sourceRoot":"","sources":["../../src/runtime/auth-strategy-registry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,oBAAoB;IAAjC;QACmB,eAAU,GAAG,IAAI,GAAG,EAAwB,CAAC;IA6BhE,CAAC;IA3BC;;;;;OAKG;IACH,QAAQ,CAAC,IAAY,EAAE,QAAsB;QAC3C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/lib/runtime/authorization-policy-registry.d.ts

@@ -1,8 +1,42 @@
 import type { AuthorizationPolicy } from '../domain/index.js';
-/** Stores the named authorization policies available to route metadata. */
+/**
+ * ## AuthorizationPolicyRegistry
+ *
+ * Stores authorization policies by name.
+ *
+ * Responsibilities:
+ * - register authorization policies during application startup
+ * - resolve policies by name during request processing
+ * - allow policies to be replaced or removed if required
+ *
+ * Guarantees:
+ * - at most one policy exists for a given name
+ * - registering an existing name replaces the previous policy
+ *
+ * Non-responsibilities:
+ * - policy evaluation
+ * - authentication
+ * - request handling
+ */
 export declare class AuthorizationPolicyRegistry {
     private readonly policies;
+    /**
+     * Registers or replaces an authorization policy.
+     *
+     * @param name Policy identifier.
+     * @param policy Authorization policy implementation.
+     */
     register(name: string, policy: AuthorizationPolicy): void;
+    /**
+     * Returns the policy registered under the specified name.
+     *
+     * @param name Policy identifier.
+     */
     get(name: string): AuthorizationPolicy | undefined;
+    /**
+     * Removes the policy associated with the specified name.
+     *
+     * @param name Policy identifier.
+     */
     unregister(name: string): void;
 }

package/lib/runtime/authorization-policy-registry.js

@@ -1,14 +1,48 @@
-/** Stores the named authorization policies available to route metadata. */
+/**
+ * ## AuthorizationPolicyRegistry
+ *
+ * Stores authorization policies by name.
+ *
+ * Responsibilities:
+ * - register authorization policies during application startup
+ * - resolve policies by name during request processing
+ * - allow policies to be replaced or removed if required
+ *
+ * Guarantees:
+ * - at most one policy exists for a given name
+ * - registering an existing name replaces the previous policy
+ *
+ * Non-responsibilities:
+ * - policy evaluation
+ * - authentication
+ * - request handling
+ */
 export class AuthorizationPolicyRegistry {
     constructor() {
         this.policies = new Map();
     }
+    /**
+     * Registers or replaces an authorization policy.
+     *
+     * @param name Policy identifier.
+     * @param policy Authorization policy implementation.
+     */
     register(name, policy) {
         this.policies.set(name, policy);
     }
+    /**
+     * Returns the policy registered under the specified name.
+     *
+     * @param name Policy identifier.
+     */
     get(name) {
         return this.policies.get(name);
     }
+    /**
+     * Removes the policy associated with the specified name.
+     *
+     * @param name Policy identifier.
+     */
     unregister(name) {
         this.policies.delete(name);
     }

package/lib/runtime/authorization-policy-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorization-policy-registry.js","sourceRoot":"","sources":["../../src/runtime/authorization-policy-registry.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,MAAM,OAAO,2BAA2B;IAAxC;QACmB,aAAQ,GAAG,IAAI,GAAG,EAA+B,CAAC;IAarE,CAAC;IAXC,QAAQ,CAAC,IAAY,EAAE,MAA2B;QAChD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;CACF"}
+{"version":3,"file":"authorization-policy-registry.js","sourceRoot":"","sources":["../../src/runtime/authorization-policy-registry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,2BAA2B;IAAxC;QACmB,aAAQ,GAAG,IAAI,GAAG,EAA+B,CAAC;IA6BrE,CAAC;IA3BC;;;;;OAKG;IACH,QAAQ,CAAC,IAAY,EAAE,MAA2B;QAChD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;CACF"}

package/lib/runtime/create-auth-middleware.d.ts

@@ -2,4 +2,36 @@ import type { Middleware } from '@kurdel/core/http';
 import { type AuthEventSink } from '../domain/index.js';
 import type { AuthStrategyRegistry } from './auth-strategy-registry.js';
 import { AuthorizationPolicyRegistry } from './authorization-policy-registry.js';
+/**
+ * ## createAuthMiddleware
+ *
+ * Creates the authentication and authorization middleware.
+ *
+ * Responsibilities:
+ * - authenticate incoming requests
+ * - populate `HttpContext.auth` and `HttpContext.user`
+ * - enforce route role requirements
+ * - evaluate configured authorization policies
+ * - emit sanitized authentication lifecycle events
+ *
+ * Guarantees:
+ * - authentication executes before authorization
+ * - route handlers execute only after successful authorization
+ * - authentication events are emitted in execution order
+ * - authorization policies execute sequentially
+ *
+ * Non-responsibilities:
+ * - credential persistence
+ * - user management
+ * - session management
+ *
+ * Pipeline:
+ *
+ * 1. Skip public routes.
+ * 2. Authenticate using the configured strategy.
+ * 3. Populate the authentication context.
+ * 4. Validate required roles.
+ * 5. Evaluate authorization policies.
+ * 6. Continue the middleware pipeline.
+ */
 export declare function createAuthMiddleware(registry: AuthStrategyRegistry, policies?: AuthorizationPolicyRegistry, events?: AuthEventSink, now?: () => Date): Middleware;

package/lib/runtime/create-auth-middleware.js

@@ -1,5 +1,37 @@
 import { authorizationDecision, NoopAuthEventSink, } from '../domain/index.js';
 import { AuthorizationPolicyRegistry } from './authorization-policy-registry.js';
+/**
+ * ## createAuthMiddleware
+ *
+ * Creates the authentication and authorization middleware.
+ *
+ * Responsibilities:
+ * - authenticate incoming requests
+ * - populate `HttpContext.auth` and `HttpContext.user`
+ * - enforce route role requirements
+ * - evaluate configured authorization policies
+ * - emit sanitized authentication lifecycle events
+ *
+ * Guarantees:
+ * - authentication executes before authorization
+ * - route handlers execute only after successful authorization
+ * - authentication events are emitted in execution order
+ * - authorization policies execute sequentially
+ *
+ * Non-responsibilities:
+ * - credential persistence
+ * - user management
+ * - session management
+ *
+ * Pipeline:
+ *
+ * 1. Skip public routes.
+ * 2. Authenticate using the configured strategy.
+ * 3. Populate the authentication context.
+ * 4. Validate required roles.
+ * 5. Evaluate authorization policies.
+ * 6. Continue the middleware pipeline.
+ */
 export function createAuthMiddleware(registry, policies = new AuthorizationPolicyRegistry(), events = new NoopAuthEventSink(), now = () => new Date()) {
     return async (ctx, next) => {
         const meta = ctx.route?.auth;
@@ -8,7 +40,9 @@ export function createAuthMiddleware(registry, policies = new AuthorizationPolic
             return next();
         }
         const { strategy, roles, policies: requiredPolicies } = meta;
-        // --- 1️⃣ Authenticate ---
+        // ---------------------------------------------------------------------
+        // 1. Authentication
+        // ---------------------------------------------------------------------
         let auth;
         if (strategy) {
             const strat = registry.get(strategy);
@@ -39,7 +73,9 @@ export function createAuthMiddleware(registry, policies = new AuthorizationPolic
                 ...(auth.credential ? { credential: auth.credential } : {}),
             });
         }
-        // --- 2️⃣ Authorize ---
+        // ---------------------------------------------------------------------
+        // 2. Role authorization
+        // ---------------------------------------------------------------------
         if (roles && roles.length > 0) {
             const ok = auth && Array.isArray(auth.user.roles)
                 ? roles.some(r => auth.user.roles.includes(r))
@@ -55,6 +91,9 @@ export function createAuthMiddleware(registry, policies = new AuthorizationPolic
                 return ctx.json(403, { error: 'Forbidden' });
             }
         }
+        // ---------------------------------------------------------------------
+        // 3. Policy authorization
+        // ---------------------------------------------------------------------
         if (requiredPolicies && requiredPolicies.length > 0) {
             if (!auth) {
                 await events.report({

package/lib/runtime/create-auth-middleware.js.map

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

package/lib/strategies/api-key/api-key-strategy-provider.d.ts

@@ -0,0 +1,18 @@
+import type { AuthStrategyProvider } from '../../domain/auth-strategy-provider.js';
+import type { ApiKeyUsageRecorder } from '../../repositories/api-key/api-key-usage-recorder.js';
+/** Declarative options for the built-in API-key strategy provider. */
+export interface ApiKeyStrategyProviderOptions {
+    /** Request header containing the API key. @default "x-api-key" */
+    header?: string;
+    /** Enables usage recording or supplies a custom recorder. */
+    usage?: boolean | ApiKeyUsageRecorder;
+    /** Injectable clock for deterministic expiration behavior. */
+    now?: () => Date;
+}
+/**
+ * Creates a DI-backed API-key authentication strategy provider.
+ *
+ * Credential and user repositories are resolved from the application
+ * container. Set `usage` to `true` to resolve the registered usage recorder.
+ */
+export declare function apiKeyStrategy(options?: ApiKeyStrategyProviderOptions): AuthStrategyProvider;

package/lib/strategies/api-key/api-key-strategy-provider.js

@@ -0,0 +1,30 @@
+import { AUTH_TOKENS } from '../../tokens.js';
+import { ApiKeyStrategy } from './api-key-strategy.js';
+/**
+ * Creates a DI-backed API-key authentication strategy provider.
+ *
+ * Credential and user repositories are resolved from the application
+ * container. Set `usage` to `true` to resolve the registered usage recorder.
+ */
+export function apiKeyStrategy(options = {}) {
+    return {
+        name: 'api-key',
+        useFactory(container) {
+            const { usage, ...strategyOptions } = options;
+            return new ApiKeyStrategy({
+                header: strategyOptions.header ?? 'x-api-key',
+                credentials: container.get(AUTH_TOKENS.ApiKeyRepository),
+                users: container.get(AUTH_TOKENS.UserRepository),
+                ...(usage
+                    ? {
+                        usage: usage === true
+                            ? container.get(AUTH_TOKENS.ApiKeyUsageRecorder)
+                            : usage,
+                    }
+                    : {}),
+                ...(strategyOptions.now ? { now: strategyOptions.now } : {}),
+            });
+        },
+    };
+}
+//# sourceMappingURL=api-key-strategy-provider.js.map

package/lib/strategies/api-key/api-key-strategy-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-strategy-provider.js","sourceRoot":"","sources":["../../../src/strategies/api-key/api-key-strategy-provider.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAYvD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAyC,EAAE;IAE3C,OAAO;QACL,IAAI,EAAE,SAAS;QACf,UAAU,CAAC,SAAoB;YAC7B,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC;YAC9C,OAAO,IAAI,cAAc,CAAC;gBACxB,MAAM,EAAE,eAAe,CAAC,MAAM,IAAI,WAAW;gBAC7C,WAAW,EAAE,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,gBAAgB,CAAC;gBACxD,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,cAAc,CAAC;gBAChD,GAAG,CAAC,KAAK;oBACP,CAAC,CAAC;wBACE,KAAK,EAAE,KAAK,KAAK,IAAI;4BACnB,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,mBAAmB,CAAC;4BAChD,CAAC,CAAC,KAAK;qBACV;oBACH,CAAC,CAAC,EAAE,CAAC;gBACP,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC7D,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/lib/strategies/api-key/api-key-strategy.d.ts

@@ -1,6 +1,11 @@
 import type { HttpRequest } from '@kurdel/common';
 import type { AuthenticationResult, AuthStrategy } from '../../domain/index.js';
 import type { ApiKeyRepository, ApiKeyUsageRecorder, AuthUserRepository } from '../../repositories/index.js';
+/**
+ * ## ApiKeyStrategyOptions
+ *
+ * Configures API-key authentication.
+ */
 export interface ApiKeyStrategyOptions {
     /** Name of the request header containing the API key. */
     header: string;
@@ -13,10 +18,43 @@ export interface ApiKeyStrategyOptions {
     /** Injectable clock keeps expiration behavior deterministic in tests. */
     now?: () => Date;
 }
-/** Authenticates an API key and resolves its current application identity. */
+/**
+ * ## ApiKeyStrategy
+ *
+ * Authenticates requests using opaque API keys.
+ *
+ * Responsibilities:
+ * - resolve API-key credentials
+ * - validate revocation and expiration
+ * - resolve the current authenticated user
+ * - optionally record successful credential usage
+ *
+ * Guarantees:
+ * - revoked credentials never authenticate
+ * - expired credentials never authenticate
+ * - inactive or missing users never authenticate
+ * - raw API keys are never exposed outside the strategy
+ *
+ * Non-responsibilities:
+ * - API-key persistence
+ * - user management
+ * - authorization policy evaluation
+ */
 export declare class ApiKeyStrategy implements AuthStrategy {
     private readonly options;
     constructor(options: ApiKeyStrategyOptions);
+    /**
+     * Authenticates a request using the configured API-key header.
+     *
+     * Returns `null` when the credential is missing, invalid, revoked,
+     * expired, or its associated user cannot be authenticated.
+     */
     authenticate(req: HttpRequest): Promise<AuthenticationResult | null>;
+    /**
+     * Returns the current time.
+     *
+     * Uses the injected clock when provided to keep authentication
+     * deterministic in tests.
+     */
     private now;
 }

package/lib/strategies/api-key/api-key-strategy.js

@@ -1,8 +1,35 @@
-/** Authenticates an API key and resolves its current application identity. */
+/**
+ * ## ApiKeyStrategy
+ *
+ * Authenticates requests using opaque API keys.
+ *
+ * Responsibilities:
+ * - resolve API-key credentials
+ * - validate revocation and expiration
+ * - resolve the current authenticated user
+ * - optionally record successful credential usage
+ *
+ * Guarantees:
+ * - revoked credentials never authenticate
+ * - expired credentials never authenticate
+ * - inactive or missing users never authenticate
+ * - raw API keys are never exposed outside the strategy
+ *
+ * Non-responsibilities:
+ * - API-key persistence
+ * - user management
+ * - authorization policy evaluation
+ */
 export class ApiKeyStrategy {
     constructor(options) {
         this.options = options;
     }
+    /**
+     * Authenticates a request using the configured API-key header.
+     *
+     * Returns `null` when the credential is missing, invalid, revoked,
+     * expired, or its associated user cannot be authenticated.
+     */
     async authenticate(req) {
         const raw = req.headers?.[this.options.header.toLowerCase()];
         const key = Array.isArray(raw) ? raw[0] : raw;
@@ -29,6 +56,12 @@ export class ApiKeyStrategy {
             },
         };
     }
+    /**
+     * Returns the current time.
+     *
+     * Uses the injected clock when provided to keep authentication
+     * deterministic in tests.
+     */
     now() {
         return this.options.now?.() ?? new Date();
     }

package/lib/strategies/api-key/api-key-strategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-key-strategy.js","sourceRoot":"","sources":["../../../src/strategies/api-key/api-key-strategy.ts"],"names":[],"mappings":"AAsBA,8EAA8E;AAC9E,MAAM,OAAO,cAAc;IACzB,YAA6B,OAA8B;QAA9B,YAAO,GAAP,OAAO,CAAuB;IAAG,CAAC;IAE/D,KAAK,CAAC,YAAY,CAAC,GAAgB;QACjC,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QAC7D,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC9C,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAEjD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACjE,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAEnD,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACnC,IAAI,UAAU,CAAC,SAAS,IAAI,UAAU,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,eAAe,CAAC,OAAO,EAAE,EAAE,CAAC;YACxF,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QAEvB,IAAI,UAAU,CAAC,EAAE,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC;QACxE,CAAC;QAED,OAAO;YACL,IAAI;YACJ,UAAU,EAAE;gBACV,IAAI,EAAE,SAAS;gBACf,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChD;SACF,CAAC;IACJ,CAAC;IAEO,GAAG;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC;IAC5C,CAAC;CACF"}
+{"version":3,"file":"api-key-strategy.js","sourceRoot":"","sources":["../../../src/strategies/api-key/api-key-strategy.ts"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,cAAc;IACzB,YAA6B,OAA8B;QAA9B,YAAO,GAAP,OAAO,CAAuB;IAAG,CAAC;IAE/D;;;;;OAKG;IACH,KAAK,CAAC,YAAY,CAAC,GAAgB;QACjC,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QAC7D,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC9C,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAEjD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACjE,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAEnD,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACnC,IAAI,UAAU,CAAC,SAAS,IAAI,UAAU,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,eAAe,CAAC,OAAO,EAAE,EAAE,CAAC;YACxF,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QAEvB,IAAI,UAAU,CAAC,EAAE,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC;QACxE,CAAC;QAED,OAAO;YACL,IAAI;YACJ,UAAU,EAAE;gBACV,IAAI,EAAE,SAAS;gBACf,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChD;SACF,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACK,GAAG;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC;IAC5C,CAAC;CACF"}

package/lib/strategies/api-key/index.d.ts

@@ -1 +1,2 @@
 export * from './api-key-strategy.js';
+export * from './api-key-strategy-provider.js';

package/lib/strategies/api-key/index.js

@@ -1,2 +1,3 @@
 export * from './api-key-strategy.js';
+export * from './api-key-strategy-provider.js';
 //# sourceMappingURL=index.js.map

package/lib/strategies/api-key/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/strategies/api-key/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/strategies/api-key/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC"}

package/lib/strategies/jwt/index.d.ts

@@ -1,2 +1,3 @@
 export * from './jwt-service.js';
 export * from './jwt-strategy.js';
+export * from './jwt-strategy-provider.js';

package/lib/strategies/jwt/index.js

@@ -1,3 +1,4 @@
 export * from './jwt-service.js';
 export * from './jwt-strategy.js';
+export * from './jwt-strategy-provider.js';
 //# sourceMappingURL=index.js.map

package/lib/strategies/jwt/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/strategies/jwt/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/strategies/jwt/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC"}

package/lib/strategies/jwt/jwt-service.d.ts

@@ -1,48 +1,99 @@
 /**
  * ## JwtPayload
- * Standard JWT claims plus application-level fields.
+ *
+ * Standard JWT claims together with application-defined claims.
+ *
+ * The payload is intentionally extensible to support application-specific
+ * authentication metadata.
  */
 export interface JwtPayload {
+    /** Subject (`sub`) identifying the authenticated principal. */
     sub: string | number;
+    /** Roles embedded into the signed token. */
     roles: string[];
+    /** Issued-at time (`iat`), expressed as Unix time in seconds. */
     iat?: number;
+    /** Expiration time (`exp`), expressed as Unix time in seconds. */
     exp?: number;
+    /** Not-before time (`nbf`), expressed as Unix time in seconds. */
     nbf?: number;
+    /** Expected token issuer (`iss`). */
     iss?: string;
+    /** Intended token audience (`aud`). */
     aud?: string;
+    /** Additional application-defined claims. */
     [key: string]: unknown;
 }
 /**
  * ## JwtServiceOptions
- * The minimal configuration required to sign and verify JWT tokens.
+ *
+ * Configures JWT signing and verification.
  */
 export interface JwtServiceOptions {
+    /** Secret used for HS256 signing. */
     secret: string;
+    /** Expected issuer claim. */
     issuer?: string;
+    /** Expected audience claim. */
     audience?: string;
+    /**
+     * Default token lifetime in seconds.
+     *
+     * When omitted, generated tokens do not receive an `exp` claim.
+     */
     expiresIn?: number;
 }
 /**
  * ## JwtService
  *
- * Lightweight JWT (HS256) implementation with zero dependencies.
- * Provides signing, decoding and verification.
+ * Signs and verifies JSON Web Tokens using the HS256 algorithm.
+ *
+ * Responsibilities:
+ * - create signed JWT tokens
+ * - verify token integrity and registered claims
+ * - decode JWT payloads without verification when explicitly requested
+ *
+ * Guarantees:
+ * - every generated token is signed with the configured secret
+ * - verification validates the signature before returning claims
+ * - configured issuer, audience, and lifetime constraints are enforced
+ *
+ * Non-responsibilities:
+ * - user authentication
+ * - authorization
+ * - session persistence
+ * - key rotation
  */
 export declare class JwtService {
     private readonly opts;
     constructor(opts: JwtServiceOptions);
     /**
-     * Signs a new JWT token with the configured HS256 secret.
+     * Creates and signs a JWT.
+     *
+     * Standard claims (`iat`, `exp`, `iss`, `aud`) are populated
+     * automatically from the configured options.
      */
     sign(payload: Omit<JwtPayload, 'iat' | 'exp'>): string;
     /**
-     * Decodes the payload **without validating the signature**.
-     * Useful for debugging or optional preview.
-     */
+    * Decodes a JWT payload without verifying its signature.
+    *
+    * The returned payload must be treated as untrusted until
+    * {@link verify} succeeds.
+    */
     decode(token: string): JwtPayload | null;
     /**
-     * Verifies signature + exp/nbf/iss/aud constraints.
-     * Returns the decoded payload or throws an Error.
+     * Verifies a JWT and returns its decoded payload.
+     *
+     * Validation includes:
+     * - signature
+     * - expiration (`exp`)
+     * - not-before (`nbf`)
+     * - issuer (`iss`) when configured
+     * - audience (`aud`) when configured
+     *
+     * @throws Error
+     * If the token is malformed, has an invalid signature,
+     * or violates any configured validation constraint.
      */
     verify(token: string): JwtPayload;
     private b64;