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

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

@@ -19,7 +19,40 @@ export class ApiKeyNotFoundError extends Error {
         this.apiKeyId = apiKeyId;
     }
 }
+/**
+ * ## 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 class DatabaseApiKeyService {
+    /**
+     * 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, hasher, tables = {}, events, now = () => new Date()) {
         this.db = db;
         this.hasher = hasher;

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

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

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

@@ -1,10 +1,34 @@
 import type { ApiKeyUsageRecorder } from '@kurdel/auth';
 import type { Database } from '@kurdel/db';
 import { type AuthDatabaseTables } from './auth-database-tables.js';
-/** Records the most recent successful use of a database-backed API key. */
+/**
+ * ## DatabaseApiKeyUsageRecorder
+ *
+ * Database-backed recorder for API key usage.
+ *
+ * Responsibilities:
+ * - record the most recent successful use of an API key
+ * - isolate API key usage persistence from the underlying database schema
+ *
+ * Guarantees:
+ * - updates only the API key usage timestamp
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - API key validation
+ * - authentication
+ * - audit event persistence
+ * - HTTP request handling
+ */
 export declare class DatabaseApiKeyUsageRecorder implements ApiKeyUsageRecorder {
     private readonly db;
     private readonly tables;
+    /**
+     * Creates a new database-backed API key usage recorder.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param tables Optional table name overrides.
+     */
     constructor(db: Database, tables?: Partial<AuthDatabaseTables>);
     recordUsage(credentialId: string, usedAt: Date): Promise<void>;
 }

package/lib/database-api-key-usage-recorder.js

@@ -1,6 +1,30 @@
 import { resolveAuthDatabaseTables } from './auth-database-tables.js';
-/** Records the most recent successful use of a database-backed API key. */
+/**
+ * ## DatabaseApiKeyUsageRecorder
+ *
+ * Database-backed recorder for API key usage.
+ *
+ * Responsibilities:
+ * - record the most recent successful use of an API key
+ * - isolate API key usage persistence from the underlying database schema
+ *
+ * Guarantees:
+ * - updates only the API key usage timestamp
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - API key validation
+ * - authentication
+ * - audit event persistence
+ * - HTTP request handling
+ */
 export class DatabaseApiKeyUsageRecorder {
+    /**
+     * Creates a new database-backed API key usage recorder.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param tables Optional table name overrides.
+     */
     constructor(db, tables = {}) {
         this.db = db;
         this.tables = resolveAuthDatabaseTables(tables);

package/lib/database-api-key-usage-recorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"database-api-key-usage-recorder.js","sourceRoot":"","sources":["../src/database-api-key-usage-recorder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAE/F,2EAA2E;AAC3E,MAAM,OAAO,2BAA2B;IAGtC,YACmB,EAAY,EAC7B,SAAsC,EAAE;QADvB,OAAE,GAAF,EAAE,CAAU;QAG7B,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,YAAoB,EAAE,MAAY;QAClD,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAChB,GAAG,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,OAAO,qCAAqC;YACvE,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,YAAY,CAAC;SAC7C,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"database-api-key-usage-recorder.js","sourceRoot":"","sources":["../src/database-api-key-usage-recorder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAE/F;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,2BAA2B;IAGtC;;;;;OAKG;IACH,YACmB,EAAY,EAC7B,SAAsC,EAAE;QADvB,OAAE,GAAF,EAAE,CAAU;QAG7B,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,YAAoB,EAAE,MAAY;QAClD,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAChB,GAAG,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,OAAO,qCAAqC;YACvE,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,YAAY,CAAC;SAC7C,CAAC,CAAC;IACL,CAAC;CACF"}

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

@@ -0,0 +1,8 @@
+import type { AuthEventSinkProvider } from '@kurdel/auth';
+/**
+ * Resolves the database-backed authentication event sink for `AuthModule`.
+ *
+ * `AuthDatabaseModule` must be configured with `audit: true` so that the
+ * event store is registered in the application container.
+ */
+export declare function databaseAuthEventSink(): AuthEventSinkProvider;

package/lib/database-auth-event-sink-provider.js

@@ -0,0 +1,15 @@
+import { AUTH_DB_TOKENS } from './tokens.js';
+/**
+ * Resolves the database-backed authentication event sink for `AuthModule`.
+ *
+ * `AuthDatabaseModule` must be configured with `audit: true` so that the
+ * event store is registered in the application container.
+ */
+export function databaseAuthEventSink() {
+    return {
+        useFactory(container) {
+            return container.get(AUTH_DB_TOKENS.EventStore);
+        },
+    };
+}
+//# sourceMappingURL=database-auth-event-sink-provider.js.map

package/lib/database-auth-event-sink-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-auth-event-sink-provider.js","sourceRoot":"","sources":["../src/database-auth-event-sink-provider.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,UAAU,CAAC,SAAoB;YAC7B,OAAO,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAClD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/lib/database-auth-event-store.d.ts

@@ -26,10 +26,37 @@ export type AuthEventList = {
     limit: number;
     offset: number;
 };
-/** Persists and queries sanitized authentication audit events. */
+/**
+ * ## DatabaseAuthEventStore
+ *
+ * Database-backed store for authentication audit events.
+ *
+ * Responsibilities:
+ * - persist authentication audit events
+ * - provide filtered and paginated audit queries
+ * - map database records to audit event DTOs
+ * - isolate audit persistence from the underlying database schema
+ *
+ * Guarantees:
+ * - stores sanitized authentication events only
+ * - supports transactional event persistence
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - authentication
+ * - authorization policy evaluation
+ * - event dispatching
+ * - HTTP request handling
+ */
 export declare class DatabaseAuthEventStore implements AuthEventSink {
     private readonly db;
     private readonly tables;
+    /**
+     * Creates a new database-backed authentication audit store.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param tables Optional table name overrides.
+     */
     constructor(db: Database, tables?: Partial<AuthDatabaseTables>);
     report(event: AuthEvent, database?: DatabaseSession): Promise<void>;
     list(input?: ListAuthEventsInput): Promise<StoredAuthEvent[]>;

package/lib/database-auth-event-store.js

@@ -1,10 +1,40 @@
 import { resolveAuthDatabaseTables } from './auth-database-tables.js';
-/** Persists and queries sanitized authentication audit events. */
+/**
+ * ## DatabaseAuthEventStore
+ *
+ * Database-backed store for authentication audit events.
+ *
+ * Responsibilities:
+ * - persist authentication audit events
+ * - provide filtered and paginated audit queries
+ * - map database records to audit event DTOs
+ * - isolate audit persistence from the underlying database schema
+ *
+ * Guarantees:
+ * - stores sanitized authentication events only
+ * - supports transactional event persistence
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - authentication
+ * - authorization policy evaluation
+ * - event dispatching
+ * - HTTP request handling
+ */
 export class DatabaseAuthEventStore {
+    /**
+     * Creates a new database-backed authentication audit store.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param tables Optional table name overrides.
+     */
     constructor(db, tables = {}) {
         this.db = db;
         this.tables = resolveAuthDatabaseTables(tables);
     }
+    // ---------------------------------------------------------------------
+    // Event persistence
+    // ---------------------------------------------------------------------
     async report(event, database = this.db) {
         await database.run({
             sql: [
@@ -24,6 +54,9 @@ export class DatabaseAuthEventStore {
             ],
         });
     }
+    // ---------------------------------------------------------------------
+    // Event queries
+    // ---------------------------------------------------------------------
     async list(input = {}) {
         return (await this.listPage(input)).events;
     }
@@ -79,6 +112,9 @@ export class DatabaseAuthEventStore {
             offset,
         };
     }
+    // ---------------------------------------------------------------------
+    // Utilities
+    // ---------------------------------------------------------------------
     serializeDate(value) {
         return value instanceof Date ? value.toISOString() : value;
     }

package/lib/database-auth-event-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"database-auth-event-store.js","sourceRoot":"","sources":["../src/database-auth-event-store.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AA0C/F,kEAAkE;AAClE,MAAM,OAAO,sBAAsB;IAGjC,YACmB,EAAY,EAC7B,SAAsC,EAAE;QADvB,OAAE,GAAF,EAAE,CAAU;QAG7B,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAgB,EAAE,WAA4B,IAAI,CAAC,EAAE;QAChE,MAAM,QAAQ,CAAC,GAAG,CAAC;YACjB,GAAG,EAAE;gBACH,eAAe,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE;gBACvC,wFAAwF;gBACxF,kCAAkC;aACnC,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE;gBACN,KAAK,CAAC,IAAI;gBACV,KAAK,CAAC,UAAU,CAAC,WAAW,EAAE;gBAC9B,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;gBACrD,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;gBACxD,KAAK,CAAC,UAAU,EAAE,IAAI,IAAI,IAAI;gBAC9B,KAAK,CAAC,UAAU,EAAE,EAAE,IAAI,IAAI;gBAC5B,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;gBACvC,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;aAClD;SACF,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,QAA6B,EAAE;QACxC,OAAO,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,QAA6B,EAAE;QAC5C,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACpC,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,UAAU,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACpC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9C,CAAC;QACD,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;YACb,UAAU,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACpC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5C,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YACjC,GAAG,EAAE;gBACH,kDAAkD;gBAClD,gDAAgD;gBAChD,QAAQ,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,KAAK,EAAE;gBACzC,sDAAsD;aACvD,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;SACnC,CAAC,CAAsB,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAC/B,GAAG,EAAE,iCAAiC,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,KAAK,GAAG;YACxE,MAAM;SACP,CAAC,CAAsB,CAAC;QAEzB,OAAO;YACL,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAC7B,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,UAAU,EAAE,MAAM,CAAC,WAAW;gBAC9B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,MAAM,EAAE,MAAM,CAAC,OAAO;gBACtB,cAAc,EAAE,MAAM,CAAC,eAAe;gBACtC,YAAY,EAAE,MAAM,CAAC,aAAa;gBAClC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,MAAM,EAAE,MAAM,CAAC,MAAM;aACtB,CAAC,CAAC;YACH,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,KAAK;YACL,MAAM;SACP,CAAC;IACJ,CAAC;IAEO,aAAa,CAAC,KAAoB;QACxC,OAAO,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7D,CAAC;CACF"}
+{"version":3,"file":"database-auth-event-store.js","sourceRoot":"","sources":["../src/database-auth-event-store.ts"],"names":[],"mappings":"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"}

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

@@ -2,9 +2,37 @@ import type { AuthUserRepository } from '@kurdel/auth';
 import type { AuthUser } from '@kurdel/common';
 import type { Database } from '@kurdel/db';
 import { type AuthDatabaseTables } from './auth-database-tables.js';
+/**
+ * ## DatabaseAuthUserRepository
+ *
+ * Database-backed repository for authenticated users.
+ *
+ * Responsibilities:
+ * - resolve authenticated users by identifier
+ * - load user roles and effective permissions
+ * - map database records to `AuthUser`
+ * - isolate authentication from the underlying database schema
+ *
+ * Guarantees:
+ * - returns `null` for missing or inactive users
+ * - resolves effective permissions from assigned roles
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - user management
+ * - role or permission management
+ * - authentication workflows
+ * - HTTP request handling
+ */
 export declare class DatabaseAuthUserRepository implements AuthUserRepository {
     private readonly db;
     private readonly tables;
+    /**
+     * Creates a new database-backed authenticated user repository.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param tables Optional table name overrides.
+     */
     constructor(db: Database, tables?: Partial<AuthDatabaseTables>);
     findById(id: string | number): Promise<AuthUser | null>;
 }

package/lib/database-auth-user-repository.js

@@ -1,5 +1,33 @@
 import { resolveAuthDatabaseTables } from './auth-database-tables.js';
+/**
+ * ## DatabaseAuthUserRepository
+ *
+ * Database-backed repository for authenticated users.
+ *
+ * Responsibilities:
+ * - resolve authenticated users by identifier
+ * - load user roles and effective permissions
+ * - map database records to `AuthUser`
+ * - isolate authentication from the underlying database schema
+ *
+ * Guarantees:
+ * - returns `null` for missing or inactive users
+ * - resolves effective permissions from assigned roles
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - user management
+ * - role or permission management
+ * - authentication workflows
+ * - HTTP request handling
+ */
 export class DatabaseAuthUserRepository {
+    /**
+     * Creates a new database-backed authenticated user repository.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param tables Optional table name overrides.
+     */
     constructor(db, tables = {}) {
         this.db = db;
         this.tables = resolveAuthDatabaseTables(tables);

package/lib/database-auth-user-repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"database-auth-user-repository.js","sourceRoot":"","sources":["../src/database-auth-user-repository.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAM/F,MAAM,OAAO,0BAA0B;IAGrC,YACmB,EAAY,EAC7B,SAAsC,EAAE;QADvB,OAAE,GAAF,EAAE,CAAU;QAG7B,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,EAAmB;QAChC,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAC9B,GAAG,EAAE,0BAA0B,IAAI,CAAC,MAAM,CAAC,KAAK,gBAAgB;YAChE,MAAM,EAAE,CAAC,EAAE,CAAC;SACb,CAAC,CAA2B,CAAC;QAC9B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAEnD,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAC/B,GAAG,EAAE;gBACH,UAAU,IAAI,CAAC,MAAM,CAAC,KAAK,OAAO;gBAClC,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;gBAC3B,cAAc,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE;gBACrC,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,cAAc,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK;gBAC/D,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,cAAc;gBAC5C,YAAY,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ;aACtC,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;SAClB,CAAC,CAAiB,CAAC;QAEpB,MAAM,WAAW,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YACrC,GAAG,EAAE;gBACH,mBAAmB,IAAI,CAAC,MAAM,CAAC,WAAW,OAAO;gBACjD,QAAQ,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE;gBACjC,cAAc,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE;gBAC3C,MAAM,IAAI,CAAC,MAAM,CAAC,eAAe,oBAAoB,IAAI,CAAC,MAAM,CAAC,WAAW,KAAK;gBACjF,cAAc,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE;gBACrC,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,cAAc,IAAI,CAAC,MAAM,CAAC,eAAe,UAAU;gBAC9E,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,cAAc;gBAC5C,YAAY,IAAI,CAAC,MAAM,CAAC,WAAW,QAAQ;aAC5C,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;SAClB,CAAC,CAAuB,CAAC;QAE1B,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;YACnC,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;SAC5D,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"database-auth-user-repository.js","sourceRoot":"","sources":["../src/database-auth-user-repository.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAM/F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,0BAA0B;IAGrC;;;;;OAKG;IACH,YACmB,EAAY,EAC7B,SAAsC,EAAE;QADvB,OAAE,GAAF,EAAE,CAAU;QAG7B,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,EAAmB;QAChC,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAC9B,GAAG,EAAE,0BAA0B,IAAI,CAAC,MAAM,CAAC,KAAK,gBAAgB;YAChE,MAAM,EAAE,CAAC,EAAE,CAAC;SACb,CAAC,CAA2B,CAAC;QAC9B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAEnD,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAC/B,GAAG,EAAE;gBACH,UAAU,IAAI,CAAC,MAAM,CAAC,KAAK,OAAO;gBAClC,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;gBAC3B,cAAc,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE;gBACrC,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,cAAc,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK;gBAC/D,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,cAAc;gBAC5C,YAAY,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ;aACtC,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;SAClB,CAAC,CAAiB,CAAC;QAEpB,MAAM,WAAW,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YACrC,GAAG,EAAE;gBACH,mBAAmB,IAAI,CAAC,MAAM,CAAC,WAAW,OAAO;gBACjD,QAAQ,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE;gBACjC,cAAc,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE;gBAC3C,MAAM,IAAI,CAAC,MAAM,CAAC,eAAe,oBAAoB,IAAI,CAAC,MAAM,CAAC,WAAW,KAAK;gBACjF,cAAc,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE;gBACrC,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,cAAc,IAAI,CAAC,MAAM,CAAC,eAAe,UAAU;gBAC9E,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,cAAc;gBAC5C,YAAY,IAAI,CAAC,MAAM,CAAC,WAAW,QAAQ;aAC5C,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;SAClB,CAAC,CAAuB,CAAC;QAE1B,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;YACnC,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;SAC5D,CAAC;IACJ,CAAC;CACF"}

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

@@ -1,10 +1,36 @@
 import type { JwtSession, JwtSessionRepository } from '@kurdel/auth';
 import type { Database } from '@kurdel/db';
 import { type AuthDatabaseTables } from './auth-database-tables.js';
-/** Resolves persisted JWT sessions for token revocation checks. */
+/**
+ * ## DatabaseJwtSessionRepository
+ *
+ * Database-backed repository for persisted JWT sessions.
+ *
+ * Responsibilities:
+ * - resolve JWT sessions by identifier
+ * - map database records to `JwtSession`
+ * - isolate JWT validation from the underlying database schema
+ *
+ * Guarantees:
+ * - returns `null` when the session does not exist
+ * - exposes session revocation and expiration state
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - session creation or revocation
+ * - refresh token management
+ * - JWT signing or verification
+ * - HTTP request handling
+ */
 export declare class DatabaseJwtSessionRepository implements JwtSessionRepository {
     private readonly db;
     private readonly tables;
+    /**
+     * Creates a new database-backed JWT session repository.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param tables Optional table name overrides.
+     */
     constructor(db: Database, tables?: Partial<AuthDatabaseTables>);
     findById(id: string): Promise<JwtSession | null>;
 }

package/lib/database-jwt-session-repository.js

@@ -1,6 +1,32 @@
 import { resolveAuthDatabaseTables } from './auth-database-tables.js';
-/** Resolves persisted JWT sessions for token revocation checks. */
+/**
+ * ## DatabaseJwtSessionRepository
+ *
+ * Database-backed repository for persisted JWT sessions.
+ *
+ * Responsibilities:
+ * - resolve JWT sessions by identifier
+ * - map database records to `JwtSession`
+ * - isolate JWT validation from the underlying database schema
+ *
+ * Guarantees:
+ * - returns `null` when the session does not exist
+ * - exposes session revocation and expiration state
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - session creation or revocation
+ * - refresh token management
+ * - JWT signing or verification
+ * - HTTP request handling
+ */
 export class DatabaseJwtSessionRepository {
+    /**
+     * Creates a new database-backed JWT session repository.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param tables Optional table name overrides.
+     */
     constructor(db, tables = {}) {
         this.db = db;
         this.tables = resolveAuthDatabaseTables(tables);

package/lib/database-jwt-session-repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"database-jwt-session-repository.js","sourceRoot":"","sources":["../src/database-jwt-session-repository.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAS/F,mEAAmE;AACnE,MAAM,OAAO,4BAA4B;IAGvC,YACmB,EAAY,EAC7B,SAAsC,EAAE;QADvB,OAAE,GAAF,EAAE,CAAU;QAG7B,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,EAAU;QACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAC/B,GAAG,EAAE;gBACH,wCAAwC;gBACxC,QAAQ,IAAI,CAAC,MAAM,CAAC,WAAW,gBAAgB;aAChD,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,EAAE,CAAC;SACb,CAAiC,CAAC;QACnC,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,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzE,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"database-jwt-session-repository.js","sourceRoot":"","sources":["../src/database-jwt-session-repository.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAS/F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,4BAA4B;IAGvC;;;;;OAKG;IACH,YACmB,EAAY,EAC7B,SAAsC,EAAE;QADvB,OAAE,GAAF,EAAE,CAAU;QAG7B,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,EAAU;QACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAC/B,GAAG,EAAE;gBACH,wCAAwC;gBACxC,QAAQ,IAAI,CAAC,MAAM,CAAC,WAAW,gBAAgB;aAChD,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,EAAE,CAAC;SACb,CAAiC,CAAC;QACnC,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,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzE,CAAC;IACJ,CAAC;CACF"}

package/lib/database-jwt-session-service.d.ts

@@ -9,6 +9,18 @@ export type CreatedJwtSession = {
     userId: number;
     expiresAt: string;
 };
+export type CreatedRefreshableJwtSession = CreatedJwtSession & {
+    refreshToken: string;
+    refreshExpiresAt: string;
+};
+export type RefreshedJwtSession = CreatedRefreshableJwtSession;
+export type JwtSessionSummary = {
+    id: string;
+    userId: number;
+    status: 'active' | 'revoked' | 'expired';
+    expiresAt: string;
+    createdAt: string;
+};
 export declare class JwtSessionNotFoundError extends Error {
     readonly userId: number;
     readonly sessionId: string;
@@ -18,14 +30,56 @@ export declare class ActiveJwtSessionUserNotFoundError extends Error {
     readonly userId: number;
     constructor(userId: number);
 }
-/** Creates and revokes the server-side state referenced by JWT `jti` claims. */
+export declare class InvalidRefreshTokenError extends Error {
+    constructor();
+}
+/**
+ * ## DatabaseJwtSessionService
+ *
+ * Application service responsible for managing persistent JWT sessions
+ * backed by a relational database through the `Database` abstraction.
+ *
+ * Responsibilities:
+ * - create server-side JWT sessions
+ * - issue and rotate refresh tokens
+ * - list active and historical sessions
+ * - revoke individual or all user sessions
+ * - emit JWT session audit events
+ *
+ * Guarantees:
+ * - validates that sessions belong to active users
+ * - stores refresh tokens as SHA-256 hashes only
+ * - rotates refresh tokens atomically
+ * - performs all state changes inside database transactions
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - JWT signing or verification
+ * - access token generation
+ * - authorization policy evaluation
+ * - HTTP request handling
+ */
 export declare class DatabaseJwtSessionService {
     private readonly db;
     private readonly events?;
     private readonly now;
     private readonly tables;
+    /**
+     * Creates a new database-backed JWT session service.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param tables Optional table name overrides.
+     * @param events Optional transactional audit event sink.
+     * @param now Time provider used for expiration checks and timestamps.
+     */
     constructor(db: Database, tables?: Partial<AuthDatabaseTables>, events?: TransactionalAuthEventSink | undefined, now?: () => Date);
     create(userId: number, expiresAt: Date): Promise<CreatedJwtSession>;
+    createRefreshable(userId: number, refreshExpiresAt: Date): Promise<CreatedRefreshableJwtSession>;
+    refresh(refreshToken: string): Promise<RefreshedJwtSession>;
+    list(userId: number): Promise<JwtSessionSummary[]>;
+    revokeAll(userId: number): Promise<void>;
     revoke(userId: number, sessionId: string): Promise<void>;
+    private generateRefreshToken;
+    private hashRefreshToken;
 }
 export {};