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

package/README.md

@@ -1,102 +1,170 @@
 # @kurdel/auth-db
 
-Database-backed repository adapters for `@kurdel/auth`.
-
-The package keeps authentication strategies storage-agnostic while providing
-standard implementations over Kurdel's `Database` contract.
-
-`DatabaseAuthUserRepository` resolves the current user and roles, while
-`DatabaseApiKeyRepository` resolves safe credential metadata including its
-stable ID. After a strategy succeeds, this data is available through
-`ctx.auth.user` and `ctx.auth.credential`; raw API keys are never exposed in the
-authentication context.
-
-The package also provides `DatabaseUserService` and `DatabaseApiKeyService` for
-administrative workflows. They create, list, update, and delete users, manage
-role assignments, and issue, list, or revoke API keys. `AuthDatabaseModule`
-registers both services as `AUTH_DB_TOKENS.UserService` and
-`AUTH_DB_TOKENS.ApiKeyService`.
-
-The module also exposes `DatabaseJwtSessionRepository` and
-`DatabaseJwtSessionService`. Applications can create a server-side session,
-place its ID in the JWT `jti` claim, configure that repository on `JwtStrategy`,
-and revoke the session before the signed token expires. Session creation and
-revocation are transactional and emit sanitized audit events when auditing is
-enabled.
-
-Password authentication uses a separate `password_credentials` table rather
-than adding secrets to the user profile. `DatabasePasswordCredentialRepository`
-resolves credentials by case-insensitive email, while
-`DatabasePasswordService.set()` hashes and upserts a user's password.
-`AuthDatabaseModule` wires both to `PasswordAuthenticationService` and uses
-`ScryptPasswordHasher` by default. Applications can replace it with
-`passwordHasher` in the module configuration.
-
-User listings support status and text filters, stable sorting, and offset
-pagination. `DatabaseUserService` also provides transactional bulk status,
-role, and deletion operations; role lifecycle management with usage counts;
-and dashboard statistics for users, credentials, and recent authentication
-failures. `DatabaseAuthEventStore.listPage()` exposes global or per-user audit
-history with type, date range, and offset filters while the existing `list()`
-method remains available for simple queries.
-
-Applications may also model authorization as roles containing permissions.
-`DatabaseUserService.listPermissions()` exposes the application-owned catalog,
-and `setRolePermissions()` replaces a role's assignments transactionally.
-`DatabaseAuthUserRepository` resolves the union of permissions from every
-current role into `AuthUser.permissions`. The application schema must provide
-`permissions` and `role_permissions` tables; the runnable sample contains the
-corresponding migration and seed data.
-
-`DatabaseApiKeyUsageRecorder` updates `last_used_at` after successful
-authentication. `AuthDatabaseModule` exposes it through
-`AUTH_TOKENS.ApiKeyUsageRecorder`, ready to pass to `ApiKeyStrategy` as its
-`usage` option.
-
-Database audit persistence is opt-in because applications own their schema:
+Database-backed infrastructure for `@kurdel/auth`.
 
-```ts
-new AuthDatabaseModule({ audit: true });
-```
+The package provides reusable implementations of the repositories and
+application services defined by `@kurdel/auth` on top of Kurdel's `Database`
+abstraction. Authentication strategies remain storage-agnostic while
+applications own their database schema and migrations.
+
+## Features
+
+- Database-backed authentication repositories
+- User, role and permission management
+- API key lifecycle management
+- JWT session persistence and revocation
+- Refresh token rotation
+- Password credential storage
+- Authentication audit persistence
+- SQLite and PostgreSQL support
+
+## Registered services
+
+`AuthDatabaseModule` registers the following infrastructure:
+
+| Token | Implementation |
+|-------|----------------|
+| `AUTH_TOKENS.UserRepository` | `DatabaseAuthUserRepository` |
+| `AUTH_TOKENS.ApiKeyRepository` | `DatabaseApiKeyRepository` |
+| `AUTH_TOKENS.JwtSessionRepository` | `DatabaseJwtSessionRepository` |
+| `AUTH_TOKENS.PasswordCredentialRepository` | `DatabasePasswordCredentialRepository` |
+| `AUTH_TOKENS.ApiKeyUsageRecorder` | `DatabaseApiKeyUsageRecorder` |
+| `AUTH_TOKENS.PasswordAuthenticationService` | `PasswordAuthenticationService` |
+| `AUTH_DB_TOKENS.UserService` | `DatabaseUserService` |
+| `AUTH_DB_TOKENS.ApiKeyService` | `DatabaseApiKeyService` |
+| `AUTH_DB_TOKENS.JwtSessionService` | `DatabaseJwtSessionService` |
+| `AUTH_DB_TOKENS.PasswordService` | `DatabasePasswordService` |
+
+When audit persistence is enabled, the module also registers:
 
-This registers `DatabaseAuthEventStore` as `AUTH_DB_TOKENS.EventStore` and
-wires API-key issue and revoke events into the management service. Pass the
-same store to `AuthModule.events` to persist runtime authentication and
-authorization events. The application must provide the configured
-`auth_events` table; the runnable sample includes a migration with the expected
-columns and indexes.
+| Token | Implementation |
+|-------|----------------|
+| `AUTH_DB_TOKENS.EventStore` | `DatabaseAuthEventStore` |
 
-API-key issue or revocation and its database audit event run in the same
-`Database.transaction` callback. If audit persistence fails, the credential
-mutation is rolled back and the service returns the original error. User
-creation, role replacement, profile updates, and deletion use the same
-transaction API for their multi-statement operations.
+## Usage
 
 ```ts
-import { ApiKeyStrategy, AUTH_TOKENS, AuthModule } from '@kurdel/auth';
-import { AuthDatabaseModule } from '@kurdel/auth-db';
+import { apiKeyStrategy, AuthModule, jwtStrategy } from '@kurdel/auth';
+import { AuthDatabaseModule, databaseAuthEventSink } from '@kurdel/auth-db';
 
 const modules = [
-  new AuthDatabaseModule(),
+  new AuthDatabaseModule({ audit: true }),
+
   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),
-          }),
-      },
-    ],
+    events: databaseAuthEventSink(),
+    strategies: [apiKeyStrategy({ usage: true }), jwtStrategy({ sessions: true })],
   }),
 ];
 ```
 
-Custom table names and hashing implementations can be supplied through the
-module configuration:
+`databaseAuthEventSink()` connects `AuthModule` to the event store registered by
+`AuthDatabaseModule({ audit: true })` without exposing its internal DI token.
+
+## User management
+
+`DatabaseUserService` provides transactional user administration.
+
+Features include:
+
+- create, update and delete users
+- paginated user listing
+- bulk status updates
+- bulk role assignment
+- bulk deletion
+- role lifecycle management
+- permission assignment
+- dashboard statistics
+
+Applications may model authorization as roles containing permissions.
+`DatabaseAuthUserRepository` resolves the union of permissions from all
+assigned roles into `AuthUser.permissions`.
+
+## API keys
+
+`DatabaseApiKeyService` manages the complete lifecycle of API keys.
+
+It supports:
+
+- issuing new keys
+- listing key metadata and status history
+- revoking keys
+- expiration
+- usage tracking
+
+Only SHA-256 hashes are persisted. Raw API keys are returned only during
+creation and are never stored.
+
+`DatabaseApiKeyUsageRecorder` automatically updates `last_used_at` after
+successful authentication.
+
+## JWT sessions
+
+`DatabaseJwtSessionService` manages server-side JWT sessions referenced by the
+JWT `jti` claim.
+
+It provides:
+
+- `create()`
+- `createRefreshable()`
+- `refresh()`
+- `list()`
+- `revoke()`
+- `revokeAll()`
+
+Refresh tokens are stored only as SHA-256 hashes and rotated atomically on
+every successful refresh.
+
+Applications are free to choose independent lifetimes for access tokens and
+refresh tokens.
+
+`DatabaseJwtSessionRepository` resolves persisted session metadata used by
+`JwtStrategy` to detect revoked sessions.
+
+## Password authentication
+
+Passwords are stored separately from user profiles.
+
+The package provides:
+
+- `DatabasePasswordCredentialRepository`
+- `DatabasePasswordService`
+- `PasswordAuthenticationService`
+
+`DatabasePasswordService` hashes and stores passwords using
+`ScryptPasswordHasher` by default.
+
+Applications may replace the hasher:
+
+```ts
+new AuthDatabaseModule({
+  passwordHasher: customHasher,
+});
+```
+
+## Authentication audit
+
+Audit persistence is optional.
+
+```ts
+new AuthDatabaseModule({
+  audit: true,
+});
+```
+
+When enabled:
+
+- `DatabaseAuthEventStore` is registered
+- management services persist audit events
+- the same store can be passed to `AuthModule.events`
+
+Authentication events are stored in the application's `auth_events` table.
+
+API key creation, revocation and audit persistence execute within the same
+database transaction.
+
+## Configuration
+
+Applications may customize table names and hashing implementations.
 
 ```ts
 new AuthDatabaseModule({
@@ -104,22 +172,50 @@ new AuthDatabaseModule({
     users: 'application_users',
     apiKeys: 'application_api_keys',
   },
-  apiKeyHasher: customHasher,
+
+  apiKeyHasher: customApiKeyHasher,
+  passwordHasher: customPasswordHasher,
 });
 ```
 
-By default, the package expects `users`, `roles`, `user_roles`, `api_keys`, and
-`password_credentials`
-tables and uses SHA-256 for API-key lookup. Schema ownership remains with the
-application; see `sample/auth-db` for migrations and a runnable example.
-The management services expect the profile and credential metadata columns
-shown in those migrations, including user name, email, status and timestamps,
-plus API-key name, status, expiration and last-use timestamps.
-When audit persistence is enabled, the default event table is `auth_events`;
-it can be changed through `tables.authEvents`.
+## Database schema
+
+By default the package expects the following tables:
+
+- `users`
+- `roles`
+- `user_roles`
+- `permissions`
+- `role_permissions`
+- `api_keys`
+- `jwt_sessions`
+- `jwt_refresh_tokens`
+- `password_credentials`
+- `auth_events`
+
+Applications own the schema and migrations.
+
+See `sample/auth-db` for a complete runnable example including migrations and
+seed data.
+
+## Architecture
+
+`@kurdel/auth-db` is an infrastructure package.
+
+Its responsibilities are:
+
+- resolve persisted authentication data
+- manage authentication-related entities
+- persist authentication audit events
+- integrate authentication with relational databases
+
+It does **not** implement authentication strategies.
+
+Authentication strategies remain part of `@kurdel/auth`, while this package
+provides the storage layer they depend on.
 
 See the [`@kurdel/auth` documentation](../auth/README.md) for route protection,
-authentication context, and custom strategy contracts.
+authentication middleware, and custom authentication strategies.
 
 ## License
 

package/lib/api-key-hasher.d.ts

@@ -1,6 +1,21 @@
+/**
+ * ## ApiKeyHasher
+ *
+ * Computes deterministic hashes of API keys for secure storage
+ * and lookup.
+ *
+ * Implementations must always produce the same hash for the same
+ * input key.
+ */
 export interface ApiKeyHasher {
     hash(key: string): string;
 }
+/**
+ * SHA-256 implementation of {@link ApiKeyHasher}.
+ *
+ * Produces hexadecimal SHA-256 digests suitable for database
+ * storage and credential lookup.
+ */
 export declare class Sha256ApiKeyHasher implements ApiKeyHasher {
     hash(key: string): string;
 }

package/lib/api-key-hasher.js

@@ -1,4 +1,10 @@
 import crypto from 'node:crypto';
+/**
+ * SHA-256 implementation of {@link ApiKeyHasher}.
+ *
+ * Produces hexadecimal SHA-256 digests suitable for database
+ * storage and credential lookup.
+ */
 export class Sha256ApiKeyHasher {
     hash(key) {
         return crypto.createHash('sha256').update(key).digest('hex');

package/lib/api-key-hasher.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-key-hasher.js","sourceRoot":"","sources":["../src/api-key-hasher.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAMjC,MAAM,OAAO,kBAAkB;IAC7B,IAAI,CAAC,GAAW;QACd,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/D,CAAC;CACF"}
+{"version":3,"file":"api-key-hasher.js","sourceRoot":"","sources":["../src/api-key-hasher.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAejC;;;;;GAKG;AACH,MAAM,OAAO,kBAAkB;IAC7B,IAAI,CAAC,GAAW;QACd,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/D,CAAC;CACF"}

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

@@ -2,6 +2,11 @@ import { type PasswordHasher } from '@kurdel/auth';
 import { ModulePriority, type AppModule, type ProviderConfig } from '@kurdel/core/app';
 import { type ApiKeyHasher } from './api-key-hasher.js';
 import type { AuthDatabaseTables } from './auth-database-tables.js';
+/**
+ * ## AuthDatabaseModuleConfig
+ *
+ * Configures database-backed authentication services.
+ */
 export interface AuthDatabaseModuleConfig {
     tables?: Partial<AuthDatabaseTables>;
     apiKeyHasher?: ApiKeyHasher;
@@ -9,6 +14,29 @@ export interface AuthDatabaseModuleConfig {
     /** Enables persistence of sanitized authentication audit events. */
     audit?: boolean;
 }
+/**
+ * ## AuthDatabaseModule
+ *
+ * Integrates `@kurdel/auth` with a relational database.
+ *
+ * Provides:
+ * - authentication repositories
+ * - application services
+ * - password authentication
+ * - JWT session persistence
+ * - API key management
+ * - optional authentication audit storage
+ *
+ * Responsibilities:
+ * - register database-backed auth infrastructure
+ * - expose public DI services
+ * - configure hashing implementations
+ *
+ * Non-responsibilities:
+ * - database migrations
+ * - runtime authentication pipeline
+ * - authorization policies
+ */
 export declare class AuthDatabaseModule implements AppModule {
     readonly priority = ModulePriority.User;
     readonly imports: {

package/lib/auth-database-module.js

@@ -13,6 +13,29 @@ import { DatabasePasswordCredentialRepository } from './database-password-creden
 import { DatabasePasswordService } from './database-password-service.js';
 import { DatabaseUserService } from './database-user-service.js';
 import { AUTH_DB_TOKENS } from './tokens.js';
+/**
+ * ## AuthDatabaseModule
+ *
+ * Integrates `@kurdel/auth` with a relational database.
+ *
+ * Provides:
+ * - authentication repositories
+ * - application services
+ * - password authentication
+ * - JWT session persistence
+ * - API key management
+ * - optional authentication audit storage
+ *
+ * Responsibilities:
+ * - register database-backed auth infrastructure
+ * - expose public DI services
+ * - configure hashing implementations
+ *
+ * Non-responsibilities:
+ * - database migrations
+ * - runtime authentication pipeline
+ * - authorization policies
+ */
 export class AuthDatabaseModule {
     constructor(config = {}) {
         this.priority = ModulePriority.User;

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

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

package/lib/auth-database-tables.d.ts

@@ -1,3 +1,11 @@
+/**
+ * ## AuthDatabaseTables
+ *
+ * Names of all database tables used by `@kurdel/auth-db`.
+ *
+ * Applications may override these names to integrate with an
+ * existing database schema.
+ */
 export interface AuthDatabaseTables {
     users: string;
     roles: string;
@@ -6,8 +14,26 @@ export interface AuthDatabaseTables {
     rolePermissions: string;
     apiKeys: string;
     jwtSessions: string;
+    jwtRefreshTokens: string;
     passwordCredentials: string;
     authEvents: string;
 }
+/**
+ * Default table names used by `@kurdel/auth-db`.
+ */
 export declare const DEFAULT_AUTH_DATABASE_TABLES: Readonly<AuthDatabaseTables>;
+export declare class InvalidDatabaseTableNameError extends Error {
+    readonly identifier: string;
+    constructor(identifier: string);
+}
+/**
+ * Resolves the effective table mapping.
+ *
+ * User-provided table names override the defaults.
+ *
+ * All identifiers are validated to ensure they are safe for
+ * interpolation into SQL statements.
+ *
+ * @throws Error If any table name is not a valid SQL identifier.
+ */
 export declare function resolveAuthDatabaseTables(tables?: Partial<AuthDatabaseTables>): AuthDatabaseTables;

package/lib/auth-database-tables.js

@@ -1,3 +1,6 @@
+/**
+ * Default table names used by `@kurdel/auth-db`.
+ */
 export const DEFAULT_AUTH_DATABASE_TABLES = {
     users: 'users',
     roles: 'roles',
@@ -6,17 +9,41 @@ export const DEFAULT_AUTH_DATABASE_TABLES = {
     rolePermissions: 'role_permissions',
     apiKeys: 'api_keys',
     jwtSessions: 'jwt_sessions',
+    jwtRefreshTokens: 'jwt_refresh_tokens',
     passwordCredentials: 'password_credentials',
     authEvents: 'auth_events',
 };
+export class InvalidDatabaseTableNameError extends Error {
+    constructor(identifier) {
+        super(`Invalid auth database table name '${identifier}'`);
+        this.identifier = identifier;
+    }
+}
+/**
+ * Resolves the effective table mapping.
+ *
+ * User-provided table names override the defaults.
+ *
+ * All identifiers are validated to ensure they are safe for
+ * interpolation into SQL statements.
+ *
+ * @throws Error If any table name is not a valid SQL identifier.
+ */
 export function resolveAuthDatabaseTables(tables = {}) {
     const resolved = { ...DEFAULT_AUTH_DATABASE_TABLES, ...tables };
     Object.values(resolved).forEach(assertSqlIdentifier);
     return resolved;
 }
+/**
+ * Ensures that a table name is a valid SQL identifier.
+ *
+ * SQL identifiers cannot be bound as query parameters.
+ * Therefore every configured table name is validated before being
+ * interpolated into SQL statements.
+ */
 function assertSqlIdentifier(identifier) {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
-        throw new Error(`Invalid auth database table name '${identifier}'`);
+        throw new InvalidDatabaseTableNameError(identifier);
     }
 }
 //# sourceMappingURL=auth-database-tables.js.map

package/lib/auth-database-tables.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-database-tables.js","sourceRoot":"","sources":["../src/auth-database-tables.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,4BAA4B,GAAiC;IACxE,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,YAAY;IACvB,WAAW,EAAE,aAAa;IAC1B,eAAe,EAAE,kBAAkB;IACnC,OAAO,EAAE,UAAU;IACnB,WAAW,EAAE,cAAc;IAC3B,mBAAmB,EAAE,sBAAsB;IAC3C,UAAU,EAAE,aAAa;CAC1B,CAAC;AAEF,MAAM,UAAU,yBAAyB,CACvC,SAAsC,EAAE;IAExC,MAAM,QAAQ,GAAG,EAAE,GAAG,4BAA4B,EAAE,GAAG,MAAM,EAAE,CAAC;IAChE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,mBAAmB,CAAC,UAAkB;IAC7C,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,qCAAqC,UAAU,GAAG,CAAC,CAAC;IACtE,CAAC;AACH,CAAC"}
+{"version":3,"file":"auth-database-tables.js","sourceRoot":"","sources":["../src/auth-database-tables.ts"],"names":[],"mappings":"AAqBA;;GAEG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAiC;IACxE,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,YAAY;IACvB,WAAW,EAAE,aAAa;IAC1B,eAAe,EAAE,kBAAkB;IACnC,OAAO,EAAE,UAAU;IACnB,WAAW,EAAE,cAAc;IAC3B,gBAAgB,EAAE,oBAAoB;IACtC,mBAAmB,EAAE,sBAAsB;IAC3C,UAAU,EAAE,aAAa;CAC1B,CAAC;AAEF,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACtD,YAAqB,UAAkB;QACrC,KAAK,CAAC,qCAAqC,UAAU,GAAG,CAAC,CAAC;QADvC,eAAU,GAAV,UAAU,CAAQ;IAEvC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CACvC,SAAsC,EAAE;IAExC,MAAM,QAAQ,GAAG,EAAE,GAAG,4BAA4B,EAAE,GAAG,MAAM,EAAE,CAAC;IAChE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,mBAAmB,CAAC,UAAkB;IAC7C,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,6BAA6B,CAAC,UAAU,CAAC,CAAC;IACtD,CAAC;AACH,CAAC"}

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

@@ -2,10 +2,39 @@ import type { ApiKeyCredential, ApiKeyRepository } from '@kurdel/auth';
 import type { Database } from '@kurdel/db';
 import type { ApiKeyHasher } from './api-key-hasher.js';
 import { type AuthDatabaseTables } from './auth-database-tables.js';
+/**
+ * ## DatabaseApiKeyRepository
+ *
+ * Repository that resolves persisted API key credentials for
+ * authentication.
+ *
+ * Responsibilities:
+ * - locate API key credentials by plaintext API key
+ * - resolve credential metadata required for authentication
+ *
+ * Guarantees:
+ * - hashes incoming API keys before querying the database
+ * - never exposes or returns stored key hashes
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - API key issuance
+ * - API key revocation
+ * - usage recording
+ * - authorization policy evaluation
+ * - HTTP request handling
+ */
 export declare class DatabaseApiKeyRepository implements ApiKeyRepository {
     private readonly db;
     private readonly hasher;
     private readonly tables;
+    /**
+     * Creates a new database-backed API key repository.
+     *
+     * @param db Database abstraction used for credential lookups.
+     * @param hasher Hashing strategy used to derive lookup hashes.
+     * @param tables Optional table name overrides.
+     */
     constructor(db: Database, hasher: ApiKeyHasher, tables?: Partial<AuthDatabaseTables>);
     findByKey(key: string): Promise<ApiKeyCredential | null>;
 }

package/lib/database-api-key-repository.js

@@ -1,5 +1,34 @@
 import { resolveAuthDatabaseTables } from './auth-database-tables.js';
+/**
+ * ## DatabaseApiKeyRepository
+ *
+ * Repository that resolves persisted API key credentials for
+ * authentication.
+ *
+ * Responsibilities:
+ * - locate API key credentials by plaintext API key
+ * - resolve credential metadata required for authentication
+ *
+ * Guarantees:
+ * - hashes incoming API keys before querying the database
+ * - never exposes or returns stored key hashes
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - API key issuance
+ * - API key revocation
+ * - usage recording
+ * - authorization policy evaluation
+ * - HTTP request handling
+ */
 export class DatabaseApiKeyRepository {
+    /**
+     * Creates a new database-backed API key repository.
+     *
+     * @param db Database abstraction used for credential lookups.
+     * @param hasher Hashing strategy used to derive lookup hashes.
+     * @param tables Optional table name overrides.
+     */
     constructor(db, hasher, tables = {}) {
         this.db = db;
         this.hasher = hasher;

package/lib/database-api-key-repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"database-api-key-repository.js","sourceRoot":"","sources":["../src/database-api-key-repository.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAS/F,MAAM,OAAO,wBAAwB;IAGnC,YACmB,EAAY,EACZ,MAAoB,EACrC,SAAsC,EAAE;QAFvB,OAAE,GAAF,EAAE,CAAU;QACZ,WAAM,GAAN,MAAM,CAAc;QAGrC,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,GAAW;QACzB,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAChC,GAAG,EAAE;gBACH,wCAAwC;gBACxC,QAAQ,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE;gBAC7B,qBAAqB;aACtB,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SAChC,CAAC,CAA6B,CAAC;QAChC,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAEzB,OAAO;YACL,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,MAAM,EAAE,MAAM,CAAC,OAAO;YACtB,OAAO,EAAE,MAAM,CAAC,MAAM,KAAK,QAAQ;YACnC,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS;SACvE,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"database-api-key-repository.js","sourceRoot":"","sources":["../src/database-api-key-repository.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAS/F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,wBAAwB;IAGnC;;;;;;OAMG;IACH,YACmB,EAAY,EACZ,MAAoB,EACrC,SAAsC,EAAE;QAFvB,OAAE,GAAF,EAAE,CAAU;QACZ,WAAM,GAAN,MAAM,CAAc;QAGrC,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,GAAW;QACzB,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAChC,GAAG,EAAE;gBACH,wCAAwC;gBACxC,QAAQ,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE;gBAC7B,qBAAqB;aACtB,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SAChC,CAAC,CAA6B,CAAC;QAChC,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAEzB,OAAO;YACL,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,MAAM,EAAE,MAAM,CAAC,OAAO;YACtB,OAAO,EAAE,MAAM,CAAC,MAAM,KAAK,QAAQ;YACnC,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS;SACvE,CAAC;IACJ,CAAC;CACF"}

package/lib/database-api-key-service.d.ts

@@ -37,12 +37,45 @@ export declare class ApiKeyNotFoundError extends Error {
     readonly apiKeyId: string;
     constructor(userId: number, apiKeyId: string);
 }
+/**
+ * ## DatabaseApiKeyService
+ *
+ * Application service responsible for issuing, listing and revoking
+ * database-backed API keys.
+ *
+ * Responsibilities:
+ * - issue API keys for active users
+ * - list API keys owned by a user
+ * - revoke existing API keys
+ * - publish API key lifecycle audit events
+ *
+ * Guarantees:
+ * - only active users can receive new API keys
+ * - API keys are persisted atomically using database transactions
+ * - plaintext API keys are returned only during creation
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - API key authentication
+ * - API key hash verification
+ * - authorization policy evaluation
+ * - HTTP request handling
+ */
 export declare class DatabaseApiKeyService {
     private readonly db;
     private readonly hasher;
     private readonly events?;
     private readonly now;
     private readonly tables;
+    /**
+     * Creates a new database-backed API key management service.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param hasher Hashing strategy used before storing API keys.
+     * @param tables Optional table name overrides.
+     * @param events Optional authentication audit event sink.
+     * @param now Clock provider used for timestamps and testing.
+     */
     constructor(db: Database, hasher: ApiKeyHasher, tables?: Partial<AuthDatabaseTables>, events?: TransactionalAuthEventSink | undefined, now?: () => Date);
     list(userId: number): Promise<ApiKeyMetadata[]>;
     create(input: CreateApiKeyInput): Promise<CreatedApiKey>;