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

package/README.md

@@ -15,30 +15,31 @@ npm install @kurdel/auth
 
 ## Configure authentication
 
-Register one or more named strategies with `AuthModule`. A strategy instance
-can be supplied directly or created from the application container:
+Register one or more named strategies with `AuthModule`. Built-in provider
+helpers resolve their framework dependencies from the application container:
 
 ```ts
-import { ApiKeyStrategy, AUTH_TOKENS, AuthModule } from '@kurdel/auth';
+import { apiKeyStrategy, AuthModule, jwtStrategy } from '@kurdel/auth';
 
 const auth = new AuthModule({
-  strategies: [
-    {
-      name: 'api-key',
-      useFactory: ioc =>
-        new ApiKeyStrategy({
-          header: 'x-api-key',
-          credentials: ioc.get(AUTH_TOKENS.ApiKeyRepository),
-          users: ioc.get(AUTH_TOKENS.UserRepository),
-          usage: ioc.get(AUTH_TOKENS.ApiKeyUsageRecorder),
-        }),
-    },
-  ],
+  strategies: [apiKeyStrategy({ usage: true }), jwtStrategy({ sessions: true })],
 });
 ```
 
+This example assumes the application container already provides `JwtService`,
+the user and credential repositories, `JwtSessionRepository`, and
+`ApiKeyUsageRecorder`. `AuthDatabaseModule` supplies the repository-backed
+dependencies; applications using `@kurdel/auth` alone must register their own
+implementations. Omit `sessions` or `usage` when those optional services are
+not needed.
+
 `AuthModule` registers the authentication middleware automatically. Strategy
-names are application-defined and are referenced by route metadata.
+names are referenced by route metadata. `apiKeyStrategy()` uses `x-api-key` by
+default; `usage: true` resolves the registered usage recorder. `jwtStrategy()`
+uses the standard Bearer header; `sessions: true` resolves the registered JWT
+session repository. Both options also accept explicit repository instances for
+custom integrations. Applications can still register custom names and manual
+strategy instances or factories through `AuthStrategyProvider`.
 
 ## Protect routes
 
@@ -226,18 +227,21 @@ the repository credential ID when one exists. The JWT strategy exposes
 `credential.type` as `jwt`, uses the `jti` claim as its optional ID, and places
 the verified payload in `claims`.
 
-To make JWTs revocable before their cryptographic expiration, configure a
-`JwtSessionRepository` on the strategy. Session-backed JWTs must contain a
-`jti`; authentication then verifies that the referenced session exists, belongs
-to the token subject, has not been revoked, and has not expired:
+To make JWTs revocable before their cryptographic expiration, enable a
+registered `JwtSessionRepository`. Session-backed JWTs must contain a `jti`;
+authentication then verifies that the referenced session exists, belongs to
+the token subject, has not been revoked, and has not expired:
 
 ```ts
-new JwtStrategy(jwtService, users, {
-  sessions: jwtSessions,
-});
+jwtStrategy({ sessions: true });
 ```
 
-Without `sessions`, JWT verification remains stateless and backward compatible.
+An explicit repository instance may be supplied instead of `true`. Without
+`sessions`, JWT verification remains stateless and backward compatible.
+Database-backed applications can pair short-lived access JWTs with rotating
+opaque refresh tokens through `DatabaseJwtSessionService` from
+`@kurdel/auth-db`. Refresh tokens are not JWTs and should never be placed in
+authorization headers or persisted in plaintext by an application.
 
 ## User and credential repositories
 

package/lib/domain/auth-context.d.ts

@@ -1,8 +1,23 @@
 import type { AuthCredential, AuthUser } from '@kurdel/common';
 export type { AuthContext, AuthCredential } from '@kurdel/common';
-/** Data produced by a strategy before middleware attaches the strategy name. */
+/**
+ * ## AuthenticationResult
+ *
+ * Result returned by an authentication strategy after successful
+ * credential validation.
+ *
+ * The authentication middleware enriches this result with the strategy
+ * name before exposing it through `ctx.auth`.
+ */
 export interface AuthenticationResult<TUser extends AuthUser = AuthUser> {
+    /** Authenticated application user. */
     user: TUser;
+    /** Metadata describing the authenticated credential. */
     credential?: AuthCredential;
+    /**
+     * Optional authentication claims produced by the strategy.
+     *
+     * For example, JWT strategies may expose verified token claims.
+     */
     claims?: Record<string, unknown>;
 }

package/lib/domain/auth-event-sink-provider.d.ts

@@ -1,5 +1,15 @@
 import type { Container } from '@kurdel/ioc';
 import type { AuthEventSink } from './auth-event.js';
+/**
+ * ## AuthEventSinkProvider
+ *
+ * Describes how an authentication event sink is supplied to
+ * {@link AuthModule}.
+ *
+ * Applications may provide either:
+ * - an existing event sink instance
+ * - a factory that resolves the sink from the IoC container
+ */
 export type AuthEventSinkProvider = {
     use: AuthEventSink;
 } | {

package/lib/domain/auth-event.d.ts

@@ -1,9 +1,23 @@
 import type { AuthCredential, AuthUser } from '@kurdel/common';
+/**
+ * Common properties shared by every authentication lifecycle event.
+ */
 type AuthEventBase = {
+    /** Time at which the event occurred. */
     occurredAt: Date;
+    /** Authenticated user, when known. */
     userId?: AuthUser['id'];
+    /** Credential involved in the event, when applicable. */
     credential?: AuthCredential;
 };
+/**
+ * ## AuthEvent
+ *
+ * Represents a sanitized authentication or authorization lifecycle event.
+ *
+ * Events intentionally exclude secrets and raw credentials so they can be
+ * safely persisted, logged, or forwarded to external audit systems.
+ */
 export type AuthEvent = (AuthEventBase & {
     type: 'authentication.succeeded';
     strategy: string;
@@ -20,13 +34,30 @@ export type AuthEvent = (AuthEventBase & {
 }) | (AuthEventBase & {
     type: 'api-key.issued' | 'api-key.revoked';
 }) | (AuthEventBase & {
-    type: 'jwt-session.created' | 'jwt-session.revoked';
+    type: 'jwt-session.created' | 'jwt-session.refreshed' | 'jwt-session.revoked';
 });
-/** Receives sanitized authentication and authorization lifecycle events. */
+/**
+ * ## AuthEventSink
+ *
+ * Receives sanitized authentication lifecycle events.
+ *
+ * Implementations may persist events, write them to logs, publish them to
+ * message brokers, or forward them to external audit systems.
+ */
 export interface AuthEventSink {
+    /**
+     * Reports an authentication lifecycle event.
+     */
     report(event: AuthEvent): Promise<void> | void;
 }
-/** Default sink used when an application does not configure event reporting. */
+/**
+ * ## NoopAuthEventSink
+ *
+ * Default {@link AuthEventSink} implementation that silently ignores all
+ * reported events.
+ *
+ * Used when an application does not configure audit reporting.
+ */
 export declare class NoopAuthEventSink implements AuthEventSink {
     report(_event: AuthEvent): void;
 }

package/lib/domain/auth-event.js

@@ -1,4 +1,11 @@
-/** Default sink used when an application does not configure event reporting. */
+/**
+ * ## NoopAuthEventSink
+ *
+ * Default {@link AuthEventSink} implementation that silently ignores all
+ * reported events.
+ *
+ * Used when an application does not configure audit reporting.
+ */
 export class NoopAuthEventSink {
     report(_event) { }
 }

package/lib/domain/auth-event.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-event.js","sourceRoot":"","sources":["../../src/domain/auth-event.ts"],"names":[],"mappings":"AAqCA,gFAAgF;AAChF,MAAM,OAAO,iBAAiB;IAC5B,MAAM,CAAC,MAAiB,IAAS,CAAC;CACnC"}
+{"version":3,"file":"auth-event.js","sourceRoot":"","sources":["../../src/domain/auth-event.ts"],"names":[],"mappings":"AA+DA;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAiB;IAC5B,MAAM,CAAC,MAAiB,IAAS,CAAC;CACnC"}

package/lib/domain/auth-strategy-provider.d.ts

@@ -1,9 +1,26 @@
 import type { Container } from '@kurdel/ioc';
 import type { AuthStrategy } from '../domain/index.js';
+/**
+ * ## AuthStrategyProvider
+ *
+ * Describes how an authentication strategy is supplied to
+ * {@link AuthModule}.
+ *
+ * Applications may provide either:
+ * - an existing strategy instance
+ * - a factory that resolves the strategy from the IoC container
+ *
+ * Each strategy is registered under the specified name and can later be
+ * referenced from route authentication metadata.
+ */
 export type AuthStrategyProvider = {
+    /** Strategy name used by route metadata. */
     name: string;
+    /** Existing strategy instance. */
     use: AuthStrategy;
 } | {
+    /** Strategy name used by route metadata. */
     name: string;
+    /** Factory that resolves the strategy from the IoC container. */
     useFactory: (c: Container) => AuthStrategy;
 };

package/lib/domain/auth-strategy.d.ts

@@ -3,15 +3,25 @@ import type { AuthenticationResult } from './auth-context.js';
 /**
  * ## AuthStrategy
  *
- * A pluggable authentication mechanism.
- * Each strategy decides how to extract and validate credentials
- * from the incoming HTTP request.
+ * Contract implemented by every authentication strategy.
  *
- * The strategy:
- *   - returns an AuthenticationResult on success
- *   - returns null if authentication fails
- *   - must NOT throw on invalid credentials
+ * A strategy is responsible for extracting credentials from an incoming
+ * HTTP request, validating them, and resolving the authenticated
+ * application identity.
+ *
+ * Guarantees:
+ * - returns an {@link AuthenticationResult} after successful authentication
+ * - returns `null` when authentication cannot be established
+ * - does not throw for invalid or missing credentials
+ *
+ * Strategies remain independent of storage. User identities and
+ * credential metadata are resolved through repository contracts.
  */
 export interface AuthStrategy {
+    /**
+     * Attempts to authenticate the incoming request.
+     *
+     * Returns `null` when the request does not contain valid credentials.
+     */
     authenticate(req: HttpRequest): Promise<AuthenticationResult | null>;
 }

package/lib/domain/authorization-policy-composition.d.ts

@@ -1,7 +1,24 @@
 import { type AuthorizationPolicy } from './authorization-policy.js';
-/** Grants access only when every nested policy grants access. */
+/**
+ * Combines multiple authorization policies using logical AND.
+ *
+ * Access is granted only when every nested policy grants access.
+ * Evaluation stops at the first denial.
+ */
 export declare function allOf(...policies: AuthorizationPolicy[]): AuthorizationPolicy;
-/** Grants access when at least one nested policy grants access. */
+/**
+ * Combines multiple authorization policies using logical OR.
+ *
+ * Access is granted when any nested policy grants access.
+ * When every policy denies access, the most informative denial
+ * reason is preserved.
+ */
 export declare function anyOf(...policies: AuthorizationPolicy[]): AuthorizationPolicy;
-/** Inverts a nested policy and uses the supplied reason when inversion denies access. */
+/**
+ * Inverts the result of an authorization policy.
+ *
+ * When the wrapped policy grants access, the returned policy denies
+ * access. An optional denial reason may be supplied for the inverted
+ * decision.
+ */
 export declare function not(policy: AuthorizationPolicy, reason?: string): AuthorizationPolicy;

package/lib/domain/authorization-policy-composition.js

@@ -1,8 +1,17 @@
 import { authorizationDecision, } from './authorization-policy.js';
+/**
+ * Evaluates a policy and normalizes its result into an
+ * {@link AuthorizationDecision}.
+ */
 async function evaluate(policy, auth, ctx) {
     return authorizationDecision(await policy.authorize(auth, ctx));
 }
-/** Grants access only when every nested policy grants access. */
+/**
+ * Combines multiple authorization policies using logical AND.
+ *
+ * Access is granted only when every nested policy grants access.
+ * Evaluation stops at the first denial.
+ */
 export function allOf(...policies) {
     return {
         async authorize(auth, ctx) {
@@ -15,7 +24,13 @@ export function allOf(...policies) {
         },
     };
 }
-/** Grants access when at least one nested policy grants access. */
+/**
+ * Combines multiple authorization policies using logical OR.
+ *
+ * Access is granted when any nested policy grants access.
+ * When every policy denies access, the most informative denial
+ * reason is preserved.
+ */
 export function anyOf(...policies) {
     return {
         async authorize(auth, ctx) {
@@ -31,7 +46,13 @@ export function anyOf(...policies) {
         },
     };
 }
-/** Inverts a nested policy and uses the supplied reason when inversion denies access. */
+/**
+ * Inverts the result of an authorization policy.
+ *
+ * When the wrapped policy grants access, the returned policy denies
+ * access. An optional denial reason may be supplied for the inverted
+ * decision.
+ */
 export function not(policy, reason) {
     return {
         async authorize(auth, ctx) {

package/lib/domain/authorization-policy-composition.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorization-policy-composition.js","sourceRoot":"","sources":["../../src/domain/authorization-policy-composition.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,qBAAqB,GAGtB,MAAM,2BAA2B,CAAC;AAEnC,KAAK,UAAU,QAAQ,CACrB,MAA2B,EAC3B,IAA2B,EAC3B,GAAgB;IAEhB,OAAO,qBAAqB,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,KAAK,CAAC,GAAG,QAA+B;IACtD,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG;YACvB,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC9B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;gBACnD,IAAI,CAAC,QAAQ,CAAC,OAAO;oBAAE,OAAO,QAAQ,CAAC;YACzC,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,KAAK,CAAC,GAAG,QAA+B;IACtD,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG;YACvB,IAAI,MAAM,GAA0B,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YACvD,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC9B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;gBACnD,IAAI,QAAQ,CAAC,OAAO;oBAAE,OAAO,QAAQ,CAAC;gBACtC,IAAI,QAAQ,CAAC,MAAM;oBAAE,MAAM,GAAG,QAAQ,CAAC;YACzC,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,GAAG,CAAC,MAA2B,EAAE,MAAe;IAC9D,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG;YACvB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;YACnD,OAAO,QAAQ,CAAC,OAAO;gBACrB,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;gBACnD,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"authorization-policy-composition.js","sourceRoot":"","sources":["../../src/domain/authorization-policy-composition.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,qBAAqB,GAGtB,MAAM,2BAA2B,CAAC;AAEnC;;;GAGG;AACH,KAAK,UAAU,QAAQ,CACrB,MAA2B,EAC3B,IAA2B,EAC3B,GAAgB;IAEhB,OAAO,qBAAqB,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,GAAG,QAA+B;IACtD,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG;YACvB,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC9B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;gBACnD,IAAI,CAAC,QAAQ,CAAC,OAAO;oBAAE,OAAO,QAAQ,CAAC;YACzC,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,GAAG,QAA+B;IACtD,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG;YACvB,IAAI,MAAM,GAA0B,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YAEvD,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC9B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;gBAEnD,IAAI,QAAQ,CAAC,OAAO;oBAAE,OAAO,QAAQ,CAAC;gBACtC,IAAI,QAAQ,CAAC,MAAM;oBAAE,MAAM,GAAG,QAAQ,CAAC;YACzC,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,GAAG,CACjB,MAA2B,EAC3B,MAAe;IAEf,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG;YACvB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;YAEnD,OAAO,QAAQ,CAAC,OAAO;gBACrB,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;gBACnD,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/lib/domain/authorization-policy-provider.d.ts

@@ -1,9 +1,26 @@
 import type { Container } from '@kurdel/ioc';
 import type { AuthorizationPolicy } from './authorization-policy.js';
+/**
+ * ## AuthorizationPolicyProvider
+ *
+ * Describes how an authorization policy is supplied to
+ * {@link AuthModule}.
+ *
+ * Applications may provide either:
+ * - an existing policy instance
+ * - a factory that resolves the policy from the IoC container
+ *
+ * Each policy is registered under the specified name and can later be
+ * referenced from route authorization metadata.
+ */
 export type AuthorizationPolicyProvider = {
+    /** Policy name used by route metadata. */
     name: string;
+    /** Existing policy instance. */
     use: AuthorizationPolicy;
 } | {
+    /** Policy name used by route metadata. */
     name: string;
+    /** Factory that resolves the policy from the IoC container. */
     useFactory: (container: Container) => AuthorizationPolicy;
 };

package/lib/domain/authorization-policy.d.ts

@@ -1,14 +1,50 @@
 import type { AuthContext } from '@kurdel/common';
 import type { HttpContext } from '@kurdel/core/http';
+/**
+ * ## AuthorizationDecision
+ *
+ * Result of an authorization policy evaluation.
+ */
 export type AuthorizationDecision = {
+    /** Indicates whether access is granted. */
     allowed: boolean;
-    /** Safe, non-sensitive reason code suitable for authorization audit events. */
+    /**
+     * Safe, non-sensitive reason code suitable for audit events.
+     *
+     * This value is intended for diagnostics and should not expose
+     * confidential application details.
+     */
     reason?: string;
 };
+/**
+ * Result returned by an authorization policy.
+ *
+ * Policies may return either a simple boolean or a richer
+ * {@link AuthorizationDecision}.
+ */
 export type AuthorizationPolicyResult = boolean | AuthorizationDecision;
-/** Performs an application-specific authorization check for a request. */
+/**
+ * ## AuthorizationPolicy
+ *
+ * Contract implemented by application authorization policies.
+ *
+ * Policies evaluate an authenticated request and decide whether it
+ * should be allowed to proceed.
+ *
+ * Policies should:
+ * - remain deterministic
+ * - avoid observable side effects
+ * - return diagnostic reasons only when they are safe to expose
+ */
 export interface AuthorizationPolicy {
+    /**
+     * Evaluates whether the authenticated request is authorized.
+     */
     authorize(auth: Readonly<AuthContext>, ctx: HttpContext): AuthorizationPolicyResult | Promise<AuthorizationPolicyResult>;
 }
-/** Converts a boolean-compatible policy result into a diagnostic decision. */
+/**
+ * Normalizes a policy result into an {@link AuthorizationDecision}.
+ *
+ * Boolean results are converted into the equivalent decision object.
+ */
 export declare function authorizationDecision(result: AuthorizationPolicyResult): AuthorizationDecision;

package/lib/domain/authorization-policy.js

@@ -1,5 +1,11 @@
-/** Converts a boolean-compatible policy result into a diagnostic decision. */
+/**
+ * Normalizes a policy result into an {@link AuthorizationDecision}.
+ *
+ * Boolean results are converted into the equivalent decision object.
+ */
 export function authorizationDecision(result) {
-    return typeof result === 'boolean' ? { allowed: result } : result;
+    return typeof result === 'boolean'
+        ? { allowed: result }
+        : result;
 }
 //# sourceMappingURL=authorization-policy.js.map

package/lib/domain/authorization-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorization-policy.js","sourceRoot":"","sources":["../../src/domain/authorization-policy.ts"],"names":[],"mappings":"AAmBA,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,MAAiC;IACrE,OAAO,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AACpE,CAAC"}
+{"version":3,"file":"authorization-policy.js","sourceRoot":"","sources":["../../src/domain/authorization-policy.ts"],"names":[],"mappings":"AAsDA;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAiC;IAEjC,OAAO,OAAO,MAAM,KAAK,SAAS;QAChC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE;QACrB,CAAC,CAAC,MAAM,CAAC;AACb,CAAC"}

package/lib/domain/permission.d.ts

@@ -1,6 +1,16 @@
 import type { AuthUser } from '@kurdel/common';
 import type { AuthorizationPolicy } from './authorization-policy.js';
-/** Returns whether an authenticated user has a resolved capability. */
+/**
+ * Determines whether a user has a resolved permission.
+ *
+ * Permissions are expected to be precomputed during authentication and
+ * attached to the authenticated user.
+ */
 export declare function hasPermission(user: Readonly<AuthUser>, permission: string): boolean;
-/** Creates a policy that requires one resolved permission. */
+/**
+ * Creates an authorization policy that requires a specific permission.
+ *
+ * Access is granted only when the authenticated user has the specified
+ * resolved permission.
+ */
 export declare function permissionPolicy(permission: string): AuthorizationPolicy;

package/lib/domain/permission.js

@@ -1,13 +1,26 @@
-/** Returns whether an authenticated user has a resolved capability. */
+/**
+ * Determines whether a user has a resolved permission.
+ *
+ * Permissions are expected to be precomputed during authentication and
+ * attached to the authenticated user.
+ */
 export function hasPermission(user, permission) {
     return user.permissions?.includes(permission) ?? false;
 }
-/** Creates a policy that requires one resolved permission. */
+/**
+ * Creates an authorization policy that requires a specific permission.
+ *
+ * Access is granted only when the authenticated user has the specified
+ * resolved permission.
+ */
 export function permissionPolicy(permission) {
     return {
         authorize: auth => hasPermission(auth.user, permission)
             ? { allowed: true }
-            : { allowed: false, reason: `missing-permission:${permission}` },
+            : {
+                allowed: false,
+                reason: `missing-permission:${permission}`,
+            },
     };
 }
 //# sourceMappingURL=permission.js.map

package/lib/domain/permission.js.map

@@ -1 +1 @@
-{"version":3,"file":"permission.js","sourceRoot":"","sources":["../../src/domain/permission.ts"],"names":[],"mappings":"AAIA,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAAC,IAAwB,EAAE,UAAkB;IACxE,OAAO,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC;AACzD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;YACrD,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE;YACnB,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,UAAU,EAAE,EAAE;KACnE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../../src/domain/permission.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAwB,EACxB,UAAkB;IAElB,OAAO,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,UAAkB;IAElB,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,EAAE,CAChB,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;YAClC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE;YACnB,CAAC,CAAC;gBACE,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,sBAAsB,UAAU,EAAE;aAC3C;KACR,CAAC;AACJ,CAAC"}

package/lib/infra/in-memory/in-memory-api-key-repository.d.ts

@@ -1,7 +1,17 @@
 import type { ApiKeyCredential, ApiKeyRepository } from '../../repositories/index.js';
-/** In-memory credential source intended for tests, demos and bootstrap code. */
+/**
+ * ## InMemoryApiKeyRepository
+ *
+ * In-memory implementation of {@link ApiKeyRepository}.
+ *
+ * Intended for tests, examples, and small applications where
+ * credential data is managed directly in memory.
+ */
 export declare class InMemoryApiKeyRepository implements ApiKeyRepository {
     private readonly keys;
     constructor(keys: Record<string, ApiKeyCredential>);
+    /**
+     * Resolves the credential associated with an API key.
+     */
     findByKey(key: string): ApiKeyCredential | null;
 }

package/lib/infra/in-memory/in-memory-api-key-repository.js

@@ -1,8 +1,18 @@
-/** In-memory credential source intended for tests, demos and bootstrap code. */
+/**
+ * ## InMemoryApiKeyRepository
+ *
+ * In-memory implementation of {@link ApiKeyRepository}.
+ *
+ * Intended for tests, examples, and small applications where
+ * credential data is managed directly in memory.
+ */
 export class InMemoryApiKeyRepository {
     constructor(keys) {
         this.keys = keys;
     }
+    /**
+     * Resolves the credential associated with an API key.
+     */
     findByKey(key) {
         return this.keys[key] ?? null;
     }

package/lib/infra/in-memory/in-memory-api-key-repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory-api-key-repository.js","sourceRoot":"","sources":["../../../src/infra/in-memory/in-memory-api-key-repository.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,MAAM,OAAO,wBAAwB;IACnC,YAA6B,IAAsC;QAAtC,SAAI,GAAJ,IAAI,CAAkC;IAAG,CAAC;IAEvE,SAAS,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IAChC,CAAC;CACF"}
+{"version":3,"file":"in-memory-api-key-repository.js","sourceRoot":"","sources":["../../../src/infra/in-memory/in-memory-api-key-repository.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,OAAO,wBAAwB;IACnC,YAA6B,IAAsC;QAAtC,SAAI,GAAJ,IAAI,CAAkC;IAAG,CAAC;IAEvE;;OAEG;IACH,SAAS,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IAChC,CAAC;CACF"}

package/lib/infra/in-memory/in-memory-auth-user-repository.d.ts

@@ -1,8 +1,18 @@
 import type { AuthUser } from '@kurdel/common';
 import type { AuthUserRepository } from '../../repositories/index.js';
-/** In-memory identity source intended for tests, demos and bootstrap code. */
+/**
+ * ## InMemoryAuthUserRepository
+ *
+ * In-memory implementation of {@link AuthUserRepository}.
+ *
+ * Intended for tests, examples, and small applications where user
+ * identities are managed directly in memory.
+ */
 export declare class InMemoryAuthUserRepository implements AuthUserRepository {
     private readonly users;
     constructor(users: AuthUser[]);
+    /**
+     * Resolves the current user by identifier.
+     */
     findById(id: string | number): AuthUser | null;
 }

package/lib/infra/in-memory/in-memory-auth-user-repository.js

@@ -1,8 +1,18 @@
-/** In-memory identity source intended for tests, demos and bootstrap code. */
+/**
+ * ## InMemoryAuthUserRepository
+ *
+ * In-memory implementation of {@link AuthUserRepository}.
+ *
+ * Intended for tests, examples, and small applications where user
+ * identities are managed directly in memory.
+ */
 export class InMemoryAuthUserRepository {
     constructor(users) {
         this.users = users;
     }
+    /**
+     * Resolves the current user by identifier.
+     */
     findById(id) {
         return this.users.find(user => user.id === id) ?? null;
     }

package/lib/infra/in-memory/in-memory-auth-user-repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory-auth-user-repository.js","sourceRoot":"","sources":["../../../src/infra/in-memory/in-memory-auth-user-repository.ts"],"names":[],"mappings":"AAIA,8EAA8E;AAC9E,MAAM,OAAO,0BAA0B;IACrC,YAA6B,KAAiB;QAAjB,UAAK,GAAL,KAAK,CAAY;IAAG,CAAC;IAElD,QAAQ,CAAC,EAAmB;QAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC;IACzD,CAAC;CACF"}
+{"version":3,"file":"in-memory-auth-user-repository.js","sourceRoot":"","sources":["../../../src/infra/in-memory/in-memory-auth-user-repository.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,MAAM,OAAO,0BAA0B;IACrC,YAA6B,KAAiB;QAAjB,UAAK,GAAL,KAAK,CAAY;IAAG,CAAC;IAElD;;OAEG;IACH,QAAQ,CAAC,EAAmB;QAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC;IACzD,CAAC;CACF"}

package/lib/infra/in-memory/in-memory-jwt-repository.d.ts

@@ -1,7 +1,11 @@
 import type { AuthUser } from '@kurdel/common';
 import type { JwtRepository } from '../../repositories/index.js';
 import { InMemoryAuthUserRepository } from './in-memory-auth-user-repository.js';
-/** @deprecated Use InMemoryAuthUserRepository. */
+/**
+ * @deprecated Use {@link InMemoryAuthUserRepository} instead.
+ *
+ * Compatibility alias for the previous repository name.
+ */
 export declare class InMemoryJwtRepository extends InMemoryAuthUserRepository implements JwtRepository {
     constructor(users: AuthUser[]);
 }

package/lib/infra/in-memory/in-memory-jwt-repository.js

@@ -1,5 +1,9 @@
 import { InMemoryAuthUserRepository } from './in-memory-auth-user-repository.js';
-/** @deprecated Use InMemoryAuthUserRepository. */
+/**
+ * @deprecated Use {@link InMemoryAuthUserRepository} instead.
+ *
+ * Compatibility alias for the previous repository name.
+ */
 export class InMemoryJwtRepository extends InMemoryAuthUserRepository {
     constructor(users) {
         super(users);

package/lib/infra/in-memory/in-memory-jwt-repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory-jwt-repository.js","sourceRoot":"","sources":["../../../src/infra/in-memory/in-memory-jwt-repository.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAEjF,kDAAkD;AAClD,MAAM,OAAO,qBACX,SAAQ,0BAA0B;IAElC,YAAY,KAAiB;QAC3B,KAAK,CAAC,KAAK,CAAC,CAAC;IACf,CAAC;CACF"}
+{"version":3,"file":"in-memory-jwt-repository.js","sourceRoot":"","sources":["../../../src/infra/in-memory/in-memory-jwt-repository.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAEjF;;;;GAIG;AACH,MAAM,OAAO,qBACX,SAAQ,0BAA0B;IAElC,YAAY,KAAiB;QAC3B,KAAK,CAAC,KAAK,CAAC,CAAC;IACf,CAAC;CACF"}