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

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

@@ -13,14 +13,55 @@ export class ActiveJwtSessionUserNotFoundError extends Error {
         this.userId = userId;
     }
 }
-/** Creates and revokes the server-side state referenced by JWT `jti` claims. */
+export class InvalidRefreshTokenError extends Error {
+    constructor() {
+        super('Refresh token is invalid or expired');
+    }
+}
+/**
+ * ## 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 class DatabaseJwtSessionService {
+    /**
+     * 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, tables = {}, events, now = () => new Date()) {
         this.db = db;
         this.events = events;
         this.now = now;
         this.tables = resolveAuthDatabaseTables(tables);
     }
+    // ---------------------------------------------------------------------
+    // JWT session lyfecycle
+    // ---------------------------------------------------------------------
     async create(userId, expiresAt) {
         const expirationTime = expiresAt.getTime();
         if (!Number.isFinite(expirationTime) || expirationTime <= this.now().getTime()) {
@@ -50,6 +91,137 @@ export class DatabaseJwtSessionService {
         });
         return { id, userId, expiresAt: expiresAt.toISOString() };
     }
+    async createRefreshable(userId, refreshExpiresAt) {
+        const expirationTime = refreshExpiresAt.getTime();
+        if (!Number.isFinite(expirationTime) || expirationTime <= this.now().getTime()) {
+            throw new RangeError('JWT refresh session expiration must be in the future');
+        }
+        const id = crypto.randomUUID();
+        const refreshToken = this.generateRefreshToken();
+        await this.db.transaction(async (transaction) => {
+            const user = await transaction.get({
+                sql: `SELECT id FROM ${this.tables.users} WHERE id = ? AND status = 'active';`,
+                params: [userId],
+            });
+            if (!user)
+                throw new ActiveJwtSessionUserNotFoundError(userId);
+            await transaction.run({
+                sql: [
+                    `INSERT INTO ${this.tables.jwtSessions}`,
+                    '(id, user_id, status, expires_at) VALUES (?, ?, ?, ?);',
+                ].join(' '),
+                params: [id, userId, 'active', refreshExpiresAt.toISOString()],
+            });
+            await transaction.run({
+                sql: [
+                    `INSERT INTO ${this.tables.jwtRefreshTokens}`,
+                    '(session_id, token_hash, expires_at) VALUES (?, ?, ?);',
+                ].join(' '),
+                params: [id, this.hashRefreshToken(refreshToken), refreshExpiresAt.toISOString()],
+            });
+            await this.events?.report({
+                type: 'jwt-session.created',
+                occurredAt: this.now(),
+                userId,
+                credential: { type: 'jwt', id },
+            }, transaction);
+        });
+        return {
+            id,
+            userId,
+            expiresAt: refreshExpiresAt.toISOString(),
+            refreshToken,
+            refreshExpiresAt: refreshExpiresAt.toISOString(),
+        };
+    }
+    async refresh(refreshToken) {
+        const nextRefreshToken = this.generateRefreshToken();
+        const now = this.now();
+        return this.db.transaction(async (transaction) => {
+            const record = await transaction.get({
+                sql: [
+                    'SELECT sessions.id, sessions.user_id, sessions.status,',
+                    'refresh_tokens.expires_at AS refresh_expires_at',
+                    `FROM ${this.tables.jwtRefreshTokens} AS refresh_tokens`,
+                    `INNER JOIN ${this.tables.jwtSessions} AS sessions ON sessions.id = refresh_tokens.session_id`,
+                    `INNER JOIN ${this.tables.users} AS users ON users.id = sessions.user_id`,
+                    "WHERE refresh_tokens.token_hash = ? AND users.status = 'active';",
+                ].join(' '),
+                params: [this.hashRefreshToken(refreshToken)],
+            });
+            const expiresAt = record ? new Date(record.refresh_expires_at) : undefined;
+            if (!record ||
+                record.status !== 'active' ||
+                !expiresAt ||
+                !Number.isFinite(expiresAt.getTime()) ||
+                expiresAt.getTime() <= now.getTime()) {
+                throw new InvalidRefreshTokenError();
+            }
+            await transaction.run({
+                sql: [
+                    `UPDATE ${this.tables.jwtRefreshTokens}`,
+                    'SET token_hash = ?, last_used_at = ? WHERE session_id = ?;',
+                ].join(' '),
+                params: [this.hashRefreshToken(nextRefreshToken), now.toISOString(), record.id],
+            });
+            await this.events?.report({
+                type: 'jwt-session.refreshed',
+                occurredAt: now,
+                userId: Number(record.user_id),
+                credential: { type: 'jwt', id: record.id },
+            }, transaction);
+            return {
+                id: record.id,
+                userId: Number(record.user_id),
+                expiresAt: expiresAt.toISOString(),
+                refreshToken: nextRefreshToken,
+                refreshExpiresAt: expiresAt.toISOString(),
+            };
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Session management
+    // ---------------------------------------------------------------------
+    async list(userId) {
+        const now = this.now().getTime();
+        const records = await this.db.all({
+            sql: [
+                'SELECT id, user_id, status, expires_at, created_at',
+                `FROM ${this.tables.jwtSessions} WHERE user_id = ?`,
+                'ORDER BY created_at DESC, id DESC;',
+            ].join(' '),
+            params: [userId],
+        });
+        return records.map(record => ({
+            id: record.id,
+            userId: Number(record.user_id),
+            status: record.status !== 'active'
+                ? 'revoked'
+                : new Date(record.expires_at).getTime() <= now ? 'expired' : 'active',
+            expiresAt: new Date(record.expires_at).toISOString(),
+            createdAt: new Date(record.created_at).toISOString(),
+        }));
+    }
+    async revokeAll(userId) {
+        await this.db.transaction(async (transaction) => {
+            const sessions = await transaction.all({
+                sql: `SELECT id FROM ${this.tables.jwtSessions} WHERE user_id = ? AND status = 'active';`,
+                params: [userId],
+            });
+            await transaction.run({
+                sql: `UPDATE ${this.tables.jwtSessions} SET status = 'revoked' WHERE user_id = ? AND status = 'active';`,
+                params: [userId],
+            });
+            for (const session of sessions) {
+                await this.events?.report({
+                    type: 'jwt-session.revoked',
+                    occurredAt: this.now(),
+                    userId,
+                    credential: { type: 'jwt', id: session.id },
+                }, transaction);
+            }
+        });
+    }
     async revoke(userId, sessionId) {
         await this.db.transaction(async (transaction) => {
             const session = await transaction.get({
@@ -70,5 +242,14 @@ export class DatabaseJwtSessionService {
             }, transaction);
         });
     }
+    // ---------------------------------------------------------------------
+    // Security helpers
+    // ---------------------------------------------------------------------
+    generateRefreshToken() {
+        return `kdl_rt_${crypto.randomBytes(32).toString('base64url')}`;
+    }
+    hashRefreshToken(token) {
+        return crypto.createHash('sha256').update(token).digest('hex');
+    }
 }
 //# sourceMappingURL=database-jwt-session-service.js.map

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

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

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

@@ -1,9 +1,36 @@
 import type { PasswordCredential, PasswordCredentialRepository } from '@kurdel/auth';
 import type { Database } from '@kurdel/db';
 import { type AuthDatabaseTables } from './auth-database-tables.js';
+/**
+ * ## DatabasePasswordCredentialRepository
+ *
+ * Database-backed repository for password authentication credentials.
+ *
+ * Responsibilities:
+ * - locate password credentials by login identifier
+ * - map database records to `PasswordCredential`
+ * - isolate authentication from the underlying database schema
+ *
+ * Guarantees:
+ * - returns `null` when no matching credentials exist
+ * - performs case-insensitive login lookup
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - password verification
+ * - password hashing
+ * - user management
+ * - authentication workflows
+ */
 export declare class DatabasePasswordCredentialRepository implements PasswordCredentialRepository {
     private readonly db;
     private readonly tables;
+    /**
+     * Creates a new database-backed password credential repository.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param tables Optional table name overrides.
+     */
     constructor(db: Database, tables?: Partial<AuthDatabaseTables>);
     findByLogin(login: string): Promise<PasswordCredential | null>;
 }

package/lib/database-password-credential-repository.js

@@ -1,5 +1,32 @@
 import { resolveAuthDatabaseTables } from './auth-database-tables.js';
+/**
+ * ## DatabasePasswordCredentialRepository
+ *
+ * Database-backed repository for password authentication credentials.
+ *
+ * Responsibilities:
+ * - locate password credentials by login identifier
+ * - map database records to `PasswordCredential`
+ * - isolate authentication from the underlying database schema
+ *
+ * Guarantees:
+ * - returns `null` when no matching credentials exist
+ * - performs case-insensitive login lookup
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - password verification
+ * - password hashing
+ * - user management
+ * - authentication workflows
+ */
 export class DatabasePasswordCredentialRepository {
+    /**
+     * Creates a new database-backed password credential 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-password-credential-repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"database-password-credential-repository.js","sourceRoot":"","sources":["../src/database-password-credential-repository.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAI/F,MAAM,OAAO,oCAAoC;IAG/C,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,KAAa;QAC7B,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAChC,GAAG,EAAE;gBACH,8DAA8D,IAAI,CAAC,MAAM,CAAC,mBAAmB,cAAc;gBAC3G,cAAc,IAAI,CAAC,MAAM,CAAC,KAAK,0CAA0C;gBACzE,sCAAsC;aACvC,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SACvB,CAAC,CAAiC,CAAC;QACpC,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACxF,CAAC;CACF"}
+{"version":3,"file":"database-password-credential-repository.js","sourceRoot":"","sources":["../src/database-password-credential-repository.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAI/F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,oCAAoC;IAG/C;;;;;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,KAAa;QAC7B,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YAChC,GAAG,EAAE;gBACH,8DAA8D,IAAI,CAAC,MAAM,CAAC,mBAAmB,cAAc;gBAC3G,cAAc,IAAI,CAAC,MAAM,CAAC,KAAK,0CAA0C;gBACzE,sCAAsC;aACvC,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SACvB,CAAC,CAAiC,CAAC;QACpC,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACxF,CAAC;CACF"}

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

@@ -5,10 +5,41 @@ export declare class PasswordUserNotFoundError extends Error {
     readonly userId: number;
     constructor(userId: number);
 }
+/**
+ * ## DatabasePasswordService
+ *
+ * Application service responsible for managing user password credentials
+ * backed by a relational database through the `Database` abstraction.
+ *
+ * Responsibilities:
+ * - set or replace user password credentials
+ * - hash passwords before persisting them
+ * - ensure the target user exists
+ *
+ * Guarantees:
+ * - never stores plaintext passwords
+ * - delegates password hashing to the configured `PasswordHasher`
+ * - performs updates atomically using a database transaction
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - password verification
+ * - password policy enforcement
+ * - password reset workflows
+ * - authentication
+ * - HTTP request handling
+ */
 export declare class DatabasePasswordService {
     private readonly db;
     private readonly hasher;
     private readonly tables;
+    /**
+     * Creates a new database-backed password management service.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param hasher Password hasher used to derive secure password hashes.
+     * @param tables Optional table name overrides.
+     */
     constructor(db: Database, hasher: PasswordHasher, tables?: Partial<AuthDatabaseTables>);
     set(userId: number, password: string): Promise<void>;
 }

package/lib/database-password-service.js

@@ -5,7 +5,38 @@ export class PasswordUserNotFoundError extends Error {
         this.userId = userId;
     }
 }
+/**
+ * ## DatabasePasswordService
+ *
+ * Application service responsible for managing user password credentials
+ * backed by a relational database through the `Database` abstraction.
+ *
+ * Responsibilities:
+ * - set or replace user password credentials
+ * - hash passwords before persisting them
+ * - ensure the target user exists
+ *
+ * Guarantees:
+ * - never stores plaintext passwords
+ * - delegates password hashing to the configured `PasswordHasher`
+ * - performs updates atomically using a database transaction
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - password verification
+ * - password policy enforcement
+ * - password reset workflows
+ * - authentication
+ * - HTTP request handling
+ */
 export class DatabasePasswordService {
+    /**
+     * Creates a new database-backed password management service.
+     *
+     * @param db Database abstraction used for persistence.
+     * @param hasher Password hasher used to derive secure password hashes.
+     * @param tables Optional table name overrides.
+     */
     constructor(db, hasher, tables = {}) {
         this.db = db;
         this.hasher = hasher;

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

@@ -1 +1 @@
-{"version":3,"file":"database-password-service.js","sourceRoot":"","sources":["../src/database-password-service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAE/F,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YAAqB,MAAc;QACjC,KAAK,CAAC,SAAS,MAAM,iBAAiB,CAAC,CAAC;QADrB,WAAM,GAAN,MAAM,CAAQ;IAEnC,CAAC;CACF;AAED,MAAM,OAAO,uBAAuB;IAGlC,YACmB,EAAY,EACZ,MAAsB,EACvC,SAAsC,EAAE;QAFvB,OAAE,GAAF,EAAE,CAAU;QACZ,WAAM,GAAN,MAAM,CAAgB;QAGvC,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,MAAc,EAAE,QAAgB;QACxC,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtD,MAAM,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,EAAC,WAAW,EAAC,EAAE;YAC5C,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC;gBACjC,GAAG,EAAE,kBAAkB,IAAI,CAAC,MAAM,CAAC,KAAK,gBAAgB;gBACxD,MAAM,EAAE,CAAC,MAAM,CAAC;aACjB,CAAC,CAAC;YACH,IAAI,CAAC,IAAI;gBAAE,MAAM,IAAI,yBAAyB,CAAC,MAAM,CAAC,CAAC;YACvD,MAAM,WAAW,CAAC,GAAG,CAAC;gBACpB,GAAG,EAAE;oBACH,eAAe,IAAI,CAAC,MAAM,CAAC,mBAAmB,uCAAuC;oBACrF,kCAAkC;oBAClC,4GAA4G;iBAC7G,CAAC,IAAI,CAAC,GAAG,CAAC;gBACX,MAAM,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC;aAC/B,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"database-password-service.js","sourceRoot":"","sources":["../src/database-password-service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAE/F,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YAAqB,MAAc;QACjC,KAAK,CAAC,SAAS,MAAM,iBAAiB,CAAC,CAAC;QADrB,WAAM,GAAN,MAAM,CAAQ;IAEnC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,uBAAuB;IAGlC;;;;;;OAMG;IACH,YACmB,EAAY,EACZ,MAAsB,EACvC,SAAsC,EAAE;QAFvB,OAAE,GAAF,EAAE,CAAU;QACZ,WAAM,GAAN,MAAM,CAAgB;QAGvC,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,MAAc,EAAE,QAAgB;QACxC,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtD,MAAM,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,EAAC,WAAW,EAAC,EAAE;YAC5C,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC;gBACjC,GAAG,EAAE,kBAAkB,IAAI,CAAC,MAAM,CAAC,KAAK,gBAAgB;gBACxD,MAAM,EAAE,CAAC,MAAM,CAAC;aACjB,CAAC,CAAC;YACH,IAAI,CAAC,IAAI;gBAAE,MAAM,IAAI,yBAAyB,CAAC,MAAM,CAAC,CAAC;YACvD,MAAM,WAAW,CAAC,GAAG,CAAC;gBACpB,GAAG,EAAE;oBACH,eAAe,IAAI,CAAC,MAAM,CAAC,mBAAmB,uCAAuC;oBACrF,kCAAkC;oBAClC,4GAA4G;iBAC7G,CAAC,IAAI,CAAC,GAAG,CAAC;gBACX,MAAM,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC;aAC/B,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/lib/database-user-service.d.ts

@@ -89,36 +89,70 @@ export declare class RoleInUseError extends Error {
     readonly userCount: number;
     constructor(roleId: number, userCount: number);
 }
+/**
+ * ## DatabaseUserService
+ *
+ * Application service responsible for user, role and permission management
+ * backed by a relational database through the `Database` abstraction.
+ *
+ * Responsibilities:
+ * - manage users and their lifecycle
+ * - assign and revoke user roles
+ * - manage roles and role permissions
+ * - provide paginated user listings
+ * - execute bulk user operations
+ * - expose dashboard statistics
+ *
+ * Guarantees:
+ * - validates referenced roles and permissions before persisting changes
+ * - keeps user-role relationships consistent using database transactions
+ * - translates database constraint violations into domain-specific errors
+ * - remains database-agnostic (SQLite/PostgreSQL)
+ *
+ * Non-responsibilities:
+ * - authentication
+ * - authorization policy evaluation
+ * - password management
+ * - JWT or API key validation
+ * - HTTP request handling
+ */
 export declare class DatabaseUserService {
     private readonly db;
     private readonly tables;
+    /**
+     * Creates a new database-backed user management service.
+     *
+     * @param db Database abstraction used for all persistence operations.
+     * @param tables Optional table name overrides.
+     */
     constructor(db: Database, tables?: Partial<AuthDatabaseTables>);
-    listRoles(): Promise<string[]>;
-    listRoleSummaries(): Promise<RoleSummary[]>;
-    listPermissions(): Promise<string[]>;
-    setRolePermissions(roleId: number, names: string[]): Promise<RoleSummary>;
-    createRole(name: string): Promise<RoleSummary>;
-    renameRole(roleId: number, name: string): Promise<RoleSummary>;
-    deleteRole(roleId: number): Promise<void>;
     create(input: CreateUserInput): Promise<ManagedUser>;
-    list(input: ListUsersInput): Promise<UserList>;
-    bulkUpdate(input: BulkUpdateUsersInput): Promise<ManagedUser[]>;
-    bulkDelete(userIds: number[]): Promise<void>;
-    dashboardStats(): Promise<AdminDashboardStats>;
-    findById(userId: number): Promise<ManagedUser>;
     update(userId: number, input: UpdateUserInput): Promise<ManagedUser>;
     delete(userId: number): Promise<void>;
+    findById(userId: number): Promise<ManagedUser>;
     private findRecord;
+    list(input: ListUsersInput): Promise<UserList>;
+    bulkUpdate(input: BulkUpdateUsersInput): Promise<ManagedUser[]>;
+    bulkDelete(userIds: number[]): Promise<void>;
+    createRole(name: string): Promise<RoleSummary>;
+    renameRole(roleId: number, name: string): Promise<RoleSummary>;
+    deleteRole(roleId: number): Promise<void>;
+    listRoles(): Promise<string[]>;
+    listRoleSummaries(): Promise<RoleSummary[]>;
     private findRole;
+    listPermissions(): Promise<string[]>;
+    setRolePermissions(roleId: number, names: string[]): Promise<RoleSummary>;
+    dashboardStats(): Promise<AdminDashboardStats>;
     private ensureUsersExist;
     private resolveRoles;
     private resolvePermissions;
     private loadRolePermissions;
-    private replaceRoles;
     private loadRoles;
+    private replaceRoles;
     private mapUser;
     private normalizeEmail;
     private rethrowEmailConflict;
     private rethrowRoleConflict;
     private isUniqueConstraintError;
+    private toCount;
 }