@adonis-agora/authkit-server 1.0.0-rc.15 → 1.0.0-rc.17

package/build/src/host/admin_api/api_users_controller.js

@@ -1,8 +1,8 @@
 import '../augmentations.js';
-import { ADMIN_LIST_HTTP_DEFAULT_SIZE, parseListPage, parseListSize } from '../../pagination.js';
 import { rolesManagedExternally } from '../account_roles.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { adminUserCreateValidator, adminUserUpdateValidator } from '../admin_validators.js';
+import { listAccountsPage, withListQuery } from '../list_api.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
 import { enrichSessionsWithContext } from '../session_context.js';
 import { AdminUsersService } from './admin_users_service.js';
@@ -28,16 +28,18 @@ async function ctxBits(ctx) {
  * envelope `{ error: { code, message } }`. Toda escrita audita com `actor: 'admin-api'`.
  */
 export default class ApiUsersController {
-    /** GET /users — `{ meta: { page, size, total }, data }`, com busca por e-mail. */
+    /**
+     * GET /users — `?search=&sort=email&page=&size=` →
+     * `{ data, meta: { total, perPage, currentPage, lastPage, firstPage } }`.
+     */
     async index(ctx) {
         const { cfg } = await ctxBits(ctx);
-        const search = ctx.request.input('search', '').trim();
-        const page = parseListPage(ctx.request.input('page'));
-        const size = parseListSize(ctx.request.input('size'), ADMIN_LIST_HTTP_DEFAULT_SIZE);
-        const result = await cfg.accountStore.listAccounts({ search, page, size });
-        const users = new AdminUsersService(cfg);
-        const data = await Promise.all(result.data.map(async (u) => userDtoWithRoles(cfg, u, await users.isDisabled(u.id))));
-        return { meta: { page, size, total: result.total }, data };
+        return withListQuery(ctx, async () => {
+            const result = await listAccountsPage(cfg.accountStore, ctx.request.qs());
+            const users = new AdminUsersService(cfg);
+            const data = await Promise.all(result.data.map(async (u) => userDtoWithRoles(cfg, u, await users.isDisabled(u.id))));
+            return { ...result, data };
+        });
     }
     /** GET /users/:id */
     async show(ctx) {

package/build/src/host/admin_console/console_audit_controller.d.ts

@@ -3,17 +3,24 @@ import type { HttpContext } from '@adonisjs/core/http';
 /**
  * Endpoints JSON do log de auditoria do console admin React.
  *
- * GET {prefix}/api/audit?type=&page=&size=  → `{ meta: { page, size, total }, data }`
+ * GET {prefix}/api/audit?filter[type]=&filter[subject]=&after=&before=&first=&last=
+ *   → `{ data, meta: { nextCursor, prevCursor, hasNext, hasPrev } }`, newest first
  *
  * 404 honesto (`capability_unsupported`) quando o sink não suporta consulta.
  */
 export default class ConsoleAuditController {
     index(ctx: HttpContext): Promise<void | {
-        meta: {
-            page: number;
-            size: number;
-            total: any;
-        };
-        data: any;
+        meta: import("@adonis-agora/filter").CursorPageMeta;
+        data: {
+            id: string;
+            type: "account.deleted" | "account.expiration_warned" | "account.expired_login_blocked" | "account.exported" | "account.extension.action" | "account.extension.redirect" | "account.locked" | "account.signed_out_all" | "agent.allowed" | "agent.blocked" | "agent.delegation_approved" | "agent.delegation_denied" | "agent.grant_revoked" | "agent.grant_revoked_by_admin" | "agent.registry_removed" | "bot_protection.rejected" | "client.created" | "client.deleted" | "client.disabled" | "client.enabled" | "client.secret_regenerated" | "client.updated" | "email.change_requested" | "email.changed" | "email_change.cancelled" | "email_change.confirmed" | "email_change.requested" | "email_verification.consumed" | "email_verification.issued" | "grant.revoked_by_user" | "impersonation" | "impersonation.panel_viewed" | "impersonation.stopped" | "keys.rotated" | "login.failure" | "login.magic_link_sent" | "login.new_device" | "login.new_ip_notified" | "login.otp_failed" | "login.otp_invalidated" | "login.otp_sent" | "login.otp_verified" | "login.success" | "maintenance.disabled" | "maintenance.enabled" | "mfa.disabled" | "mfa.enabled" | "mfa.recovery_codes_regenerated" | "organization.created" | "organization.deactivated" | "organization.deleted" | "organization.invitation_accepted" | "organization.invitation_revoked" | "organization.invitation_sent" | "organization.member_added" | "organization.member_removed" | "organization.member_role_changed" | "organization.member_role_updated" | "organization.switched" | "organization.updated" | "otp.locked" | "otp.unlock_failed" | "otp.unlocked" | "passkey.registered" | "passkey.removed" | "password.changed" | "password.expired_change_forced" | "password.rehashed" | "password_reset.consumed" | "password_reset.issued" | "pat.issued" | "pat.revoked" | "pat.used" | "profile.updated" | "roles_catalog.updated" | "security_notice.sent" | "service_tenant.token_issued" | "session.revoked" | "session.revoked_all" | "session.single_enforced" | "settings.updated" | "signup" | "sudo.confirmed" | "trusted_device.revoked" | "user.created" | "user.deleted" | "user.disabled" | "user.enabled" | "user.password_reset_sent";
+            accountId: string | null;
+            email: string | null;
+            clientId: string | null;
+            actorId: string | null;
+            ip: string | null;
+            metadata: Record<string, unknown> | null;
+            createdAt: string | null;
+        }[];
     }>;
 }

package/build/src/host/admin_console/console_audit_controller.js

@@ -1,10 +1,11 @@
 import '../augmentations.js';
-import { ADMIN_LIST_HTTP_DEFAULT_SIZE, parseListPage, parseListSize } from '../../pagination.js';
 import { apiError, auditDto } from '../admin_api/dto.js';
+import { listAuditPage, withListQuery } from '../list_api.js';
 /**
  * Endpoints JSON do log de auditoria do console admin React.
  *
- * GET {prefix}/api/audit?type=&page=&size=  → `{ meta: { page, size, total }, data }`
+ * GET {prefix}/api/audit?filter[type]=&filter[subject]=&after=&before=&first=&last=
+ *   → `{ data, meta: { nextCursor, prevCursor, hasNext, hasPrev } }`, newest first
  *
  * 404 honesto (`capability_unsupported`) quando o sink não suporta consulta.
  */
@@ -16,11 +17,9 @@ export default class ConsoleAuditController {
         if (!sink || typeof sink.list !== 'function') {
             return ctx.response.notFound(apiError('capability_unsupported', 'O sink de auditoria configurado não suporta consulta.'));
         }
-        const page = parseListPage(ctx.request.input('page'));
-        const size = parseListSize(ctx.request.input('size'), ADMIN_LIST_HTTP_DEFAULT_SIZE);
-        const type = ctx.request.input('type')?.trim() || undefined;
-        const subject = ctx.request.input('subject')?.trim() || undefined;
-        const result = await sink.list({ page, size, type, subject });
-        return { meta: { page, size, total: result.total }, data: result.data.map(auditDto) };
+        return withListQuery(ctx, async () => {
+            const page = await listAuditPage(sink, ctx.request.qs());
+            return { ...page, data: page.data.map(auditDto) };
+        });
     }
 }

package/build/src/host/admin_console/console_clients_controller.d.ts

@@ -15,7 +15,8 @@ import type { HttpContext } from '@adonisjs/core/http';
 export default class ConsoleClientsController {
     #private;
     /** GET {prefix}/api/clients */
-    index(ctx: HttpContext): Promise<{
+    index(ctx: HttpContext): Promise<void | {
+        meta: import("@adonis-agora/filter").OffsetPageMeta;
         data: {
             clientId: string;
             confidential: boolean;

package/build/src/host/admin_console/console_clients_controller.js

@@ -3,6 +3,7 @@ import { apiError, clientDto, createdClientDto } from '../admin_api/dto.js';
 import { AdminClientsService } from '../admin_clients_service.js';
 import { clientCreateInput, clientInputValidator, clientPartialInput, } from '../admin_validators.js';
 import { ClientMetadataError } from '../client_metadata.js';
+import { listClientsPage, withListQuery } from '../list_api.js';
 /**
  * Metadata incoerente com o tipo de client (ex.: nativo com secret, redirect
  * `myapp://` num client web) — 422, igual a um input que falha no Vine.
@@ -27,11 +28,10 @@ export default class ConsoleClientsController {
     async index(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
         const svc = new AdminClientsService(service);
-        if (!svc.canList) {
-            return { data: [], canList: false };
-        }
-        const clients = await svc.list();
-        return { data: clients.map(clientDto), canList: true };
+        return withListQuery(ctx, async () => {
+            const page = await listClientsPage(svc.canList ? await svc.list() : [], ctx.request.qs());
+            return { ...page, data: page.data.map(clientDto), canList: svc.canList };
+        });
     }
     /** GET {prefix}/api/clients/:id */
     async show(ctx) {

package/build/src/host/admin_console/console_orgs_controller.d.ts

@@ -4,7 +4,7 @@ import type { HttpContext } from '@adonisjs/core/http';
  * Endpoints JSON de organizações do console admin React.
  * 404 honesto quando o store não suporta organizações (`capability_unsupported`).
  *
- * GET    {prefix}/api/orgs                                → lista orgs com contagem de membros
+ * GET    {prefix}/api/orgs?search=&sort=&page=&size=     → página de orgs com contagem de membros
  * POST   {prefix}/api/orgs                                → cria uma org
  * GET    {prefix}/api/orgs/:id                            → detalhe da org (membros + convites)
  * PATCH  {prefix}/api/orgs/:id                            → edita nome/slug/logo
@@ -22,6 +22,7 @@ export default class ConsoleOrgsController {
     private settings;
     /** GET {prefix}/api/orgs */
     index(ctx: HttpContext): Promise<void | {
+        meta: import("@adonis-agora/filter").OffsetPageMeta;
         data: {
             id: string;
             name: string;

package/build/src/host/admin_console/console_orgs_controller.js

@@ -3,13 +3,14 @@ import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
 import { AdminOrgsService } from '../admin_api/admin_orgs_service.js';
 import { apiError, orgDetailDto, orgDto } from '../admin_api/dto.js';
 import { orgAddMemberValidator, orgCreateValidator, orgInvitationValidator, orgMemberRoleValidator, orgUpdateValidator, } from '../admin_validators.js';
+import { listOrgsPage, withListQuery } from '../list_api.js';
 import { authkitOrigin } from '../origin.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
 /**
  * Endpoints JSON de organizações do console admin React.
  * 404 honesto quando o store não suporta organizações (`capability_unsupported`).
  *
- * GET    {prefix}/api/orgs                                → lista orgs com contagem de membros
+ * GET    {prefix}/api/orgs?search=&sort=&page=&size=     → página de orgs com contagem de membros
  * POST   {prefix}/api/orgs                                → cria uma org
  * GET    {prefix}/api/orgs/:id                            → detalhe da org (membros + convites)
  * PATCH  {prefix}/api/orgs/:id                            → edita nome/slug/logo
@@ -46,7 +47,10 @@ export default class ConsoleOrgsController {
         if (!Array.isArray(result)) {
             return ctx.response.notFound(apiError('capability_unsupported', 'O store não suporta organizações.'));
         }
-        return { data: result.map((o) => orgDto(o)) };
+        return withListQuery(ctx, async () => {
+            const page = await listOrgsPage(result, ctx.request.qs());
+            return { ...page, data: page.data.map((o) => orgDto(o)) };
+        });
     }
     /** POST {prefix}/api/orgs */
     async store(ctx) {

package/build/src/host/admin_console/console_overview_controller.d.ts

@@ -6,7 +6,7 @@ import type { HttpContext } from '@adonisjs/core/http';
  * Métricas-resumo do IdP para o dashboard do console React. Reutiliza
  * `computeAdminStats` (mesma fonte do console Edge) e adiciona:
  * - `clientsCount`   — número de clients no adapter (0 quando o adapter não enumera)
- * - `auditTotal`     — total de eventos de auditoria (0 quando sink não suporta)
+ * - `auditTotal`     — total de eventos de auditoria (`null` quando o sink não conta)
  * - `recentEvents`   — últimos 5 eventos de auditoria ([] quando não suporta)
  */
 export default class ConsoleOverviewController {

package/build/src/host/admin_console/console_overview_controller.js

@@ -1,5 +1,4 @@
 import '../augmentations.js';
-import { LIST_FIRST_PAGE } from '../../pagination.js';
 import { AdminClientsService } from '../admin_clients_service.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { computeAdminStats } from '../admin_stats_service.js';
@@ -9,7 +8,7 @@ import { computeAdminStats } from '../admin_stats_service.js';
  * Métricas-resumo do IdP para o dashboard do console React. Reutiliza
  * `computeAdminStats` (mesma fonte do console Edge) e adiciona:
  * - `clientsCount`   — número de clients no adapter (0 quando o adapter não enumera)
- * - `auditTotal`     — total de eventos de auditoria (0 quando sink não suporta)
+ * - `auditTotal`     — total de eventos de auditoria (`null` quando o sink não conta)
  * - `recentEvents`   — últimos 5 eventos de auditoria ([] quando não suporta)
  */
 export default class ConsoleOverviewController {
@@ -20,9 +19,8 @@ export default class ConsoleOverviewController {
         const stats = await computeAdminStats(cfg, sessions);
         const clients = new AdminClientsService(service);
         const clientsCount = clients.canList ? (await clients.list()).length : 0;
-        const recentResult = typeof cfg.audit?.list === 'function'
-            ? await cfg.audit.list({ page: LIST_FIRST_PAGE, size: 5 })
-            : null;
+        const recentResult = typeof cfg.audit?.list === 'function' ? await cfg.audit.list({ size: 5 }) : null;
+        const auditTotal = typeof cfg.audit?.count === 'function' ? await cfg.audit.count({}) : null;
         return {
             usersTotal: stats.totalUsers,
             activeSessions: stats.activeSessions,
@@ -34,7 +32,7 @@ export default class ConsoleOverviewController {
             windowDays: stats.windowDays,
             auditSupported: stats.auditSupported,
             clientsCount,
-            auditTotal: recentResult?.total ?? 0,
+            auditTotal,
             recentEvents: (recentResult?.data ?? []).map((e) => ({
                 id: e.id,
                 type: e.type,

package/build/src/host/admin_console/console_personal_agents_controller.d.ts

@@ -44,26 +44,23 @@ export default class ConsolePersonalAgentsController {
         };
         agents: AgentEntry[];
     }>;
-    /** GET {prefix}/api/personal-agents/connections */
-    connections(ctx: HttpContext): Promise<void | {
-        meta: {
-            page: number;
-            size: number;
-            total: number;
-        };
-        data: {
-            id: string;
-            protocol: AgentProtocolId;
-            clientId: string;
-            agentName: string;
-            accountId: string;
-            accountEmail: string | null;
-            scopes: string[];
-            createdAt: string;
-            updatedAt: string;
-            expiresAt: string;
-        }[];
-    }>;
+    /**
+     * GET {prefix}/api/personal-agents/connections — live grants, newest first:
+     * `?filter[protocol]=&filter[clientId]=&filter[accountId]=&sort=-createdAt&page=&size=` →
+     * `{ data, meta: { total, perPage, currentPage, lastPage, firstPage } }`.
+     */
+    connections(ctx: HttpContext): Promise<void | import("@adonis-agora/filter").OffsetPage<{
+        id: string;
+        protocol: AgentProtocolId;
+        clientId: string;
+        agentName: string;
+        accountId: string;
+        accountEmail: string | null;
+        scopes: string[];
+        createdAt: string;
+        updatedAt: string;
+        expiresAt: string;
+    }>>;
     /** POST {prefix}/api/personal-agents/connections/:grantId/revoke */
     revokeConnection(ctx: HttpContext): Promise<void | {}>;
     /**

package/build/src/host/admin_console/console_personal_agents_controller.js

@@ -1,10 +1,11 @@
 import '../augmentations.js';
+import { InvalidColumnFilterError, offsetPage } from '@adonis-agora/filter';
 import { displayNameFor } from '../../agents/agent_identity.js';
 import { parseScope } from '../../agents/config.js';
 import { personalAgentsFor } from '../../agents/runtime.js';
-import { parseListPage, parseListSize } from '../../pagination.js';
 import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
 import { apiError } from '../admin_api/dto.js';
+import { ConnectionListFilter, listQueryError, readListFilter, readPage, readSort, } from '../list_api.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
 import { requireSudo } from '../sudo_mode.js';
 /** Mesmo gate de sudo das outras ações destrutivas do console (sessões, chaves). */
@@ -182,19 +183,39 @@ export default class ConsolePersonalAgentsController {
             agents,
         };
     }
-    /** GET {prefix}/api/personal-agents/connections */
+    /**
+     * GET {prefix}/api/personal-agents/connections — live grants, newest first:
+     * `?filter[protocol]=&filter[clientId]=&filter[accountId]=&sort=-createdAt&page=&size=` →
+     * `{ data, meta: { total, perPage, currentPage, lastPage, firstPage } }`.
+     */
     async connections(ctx) {
         const runtime = await runtimeFor(ctx);
         if (!runtime)
             return notSupported(ctx);
         const qs = ctx.request.qs();
-        const page = parseListPage(qs.page);
-        const size = parseListSize(qs.size);
-        const protocol = qs.protocol && enabledProtocols(runtime).includes(qs.protocol) ? qs.protocol : undefined;
+        let query;
+        try {
+            const f = await readListFilter(qs, ConnectionListFilter);
+            readSort(qs, { sortable: ['createdAt'], default: '-createdAt', fixed: true });
+            const protocol = f.first('protocol');
+            if (protocol !== undefined && !enabledProtocols(runtime).includes(protocol)) {
+                throw new InvalidColumnFilterError(`Unknown protocol: "${protocol}".`);
+            }
+            query = {
+                ...readPage(qs),
+                ...(protocol !== undefined && { protocol }),
+                ...(f.first('clientId') !== undefined && { clientId: f.first('clientId') }),
+                ...(f.first('accountId') !== undefined && { accountId: f.first('accountId') }),
+            };
+        }
+        catch (error) {
+            return listQueryError(ctx, error);
+        }
+        const { page, size, protocol } = query;
         const filter = {
             idPrefix: protocol ? grantPrefixOf(runtime, protocol) : undefined,
-            clientId: qs.clientId?.trim() || undefined,
-            accountId: qs.accountId?.trim() || undefined,
+            clientId: query.clientId,
+            accountId: query.accountId,
         };
         const now = new Date();
         const [total, rows] = await Promise.all([
@@ -226,7 +247,7 @@ export default class ConsolePersonalAgentsController {
                 expiresAt: g.expiresAt.toISOString(),
             };
         }));
-        return { meta: { page, size, total }, data };
+        return offsetPage(data, { total, page, size });
     }
     /** POST {prefix}/api/personal-agents/connections/:grantId/revoke */
     async revokeConnection(ctx) {

package/build/src/host/admin_console/console_sessions_controller.d.ts

@@ -3,7 +3,7 @@ import type { HttpContext } from '@adonisjs/core/http';
 /**
  * Endpoints JSON de sessões/grants do console admin React.
  *
- * GET    {prefix}/api/sessions?accountId=      → lista sessões + grants de uma conta (ou global)
+ * GET    {prefix}/api/sessions?filter[accountId]=&search=&sort=&page=&size= → página de sessões ativas
  * POST   {prefix}/api/sessions/revoke-all      → revoga todas as sessões de ?accountId=
  * GET    {prefix}/api/users/:id/sessions       → lista sessões + grants de um usuário específico
  * POST   {prefix}/api/users/:id/revoke-sessions → revoga todas as sessões de um usuário específico
@@ -14,16 +14,15 @@ export default class ConsoleSessionsController {
      * Retorna o shape UserSessionsResult: { supported, truncated, sessions, grants }.
      */
     private listForAccount;
-    /** GET {prefix}/api/sessions?accountId= */
+    /**
+     * GET {prefix}/api/sessions — active sessions, one page:
+     * `?filter[accountId]=&search=&sort=-loginTs|email&page=&size=` →
+     * `{ data, meta, supported, truncated, grants }`. `search` matches the email or the IP;
+     * `grants` lists the account's grants when `filter[accountId]` is set (`[]` otherwise).
+     */
     index(ctx: HttpContext): Promise<void | {
-        supported: boolean;
-        sessions: never[];
-        grants: never[];
-        truncated?: undefined;
-    } | {
-        supported: boolean;
-        truncated: boolean;
-        sessions: {
+        meta: import("@adonis-agora/filter").OffsetPageMeta;
+        data: {
             id: string;
             accountId: string;
             email: string | null;
@@ -35,6 +34,8 @@ export default class ConsoleSessionsController {
             ip: string | null;
             location: string | null;
         }[];
+        supported: boolean;
+        truncated: boolean;
         grants: {
             id: string;
             accountId: string;

package/build/src/host/admin_console/console_sessions_controller.js

@@ -3,6 +3,7 @@ import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
 import { apiError, grantDto, sessionDto } from '../admin_api/dto.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { sessionAccountValidator } from '../admin_validators.js';
+import { pageRows, readListFilter, readSearch, readSort, SessionListFilter, searchRows, sortRows, withListQuery, } from '../list_api.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
 import { enrichSessionsWithContext } from '../session_context.js';
 import { requireSudo } from '../sudo_mode.js';
@@ -25,7 +26,7 @@ async function gateSudo(ctx) {
 /**
  * Endpoints JSON de sessões/grants do console admin React.
  *
- * GET    {prefix}/api/sessions?accountId=      → lista sessões + grants de uma conta (ou global)
+ * GET    {prefix}/api/sessions?filter[accountId]=&search=&sort=&page=&size= → página de sessões ativas
  * POST   {prefix}/api/sessions/revoke-all      → revoga todas as sessões de ?accountId=
  * GET    {prefix}/api/users/:id/sessions       → lista sessões + grants de um usuário específico
  * POST   {prefix}/api/users/:id/revoke-sessions → revoga todas as sessões de um usuário específico
@@ -55,26 +56,48 @@ export default class ConsoleSessionsController {
             grants: grants.map(grantDto),
         };
     }
-    /** GET {prefix}/api/sessions?accountId= */
+    /**
+     * GET {prefix}/api/sessions — active sessions, one page:
+     * `?filter[accountId]=&search=&sort=-loginTs|email&page=&size=` →
+     * `{ data, meta, supported, truncated, grants }`. `search` matches the email or the IP;
+     * `grants` lists the account's grants when `filter[accountId]` is set (`[]` otherwise).
+     */
     async index(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
-        const accountId = ctx.request.input('accountId', '').trim();
+        const cfg = service.config;
         const adminSvc = new AdminSessionsService(service);
-        if (!adminSvc.canList) {
-            return { supported: false, sessions: [], grants: [] };
-        }
-        // Sem accountId → listagem global de todas as sessões ativas
-        if (!accountId) {
-            const { sessions: rawSessions, truncated } = await adminSvc.listAllSessions();
-            return {
-                supported: true,
-                truncated,
-                sessions: rawSessions.map(sessionDto),
-                grants: [],
-            };
-        }
-        // Com accountId → delega ao helper por-conta
-        return this.listForAccount(ctx, accountId);
+        const qs = ctx.request.qs();
+        return withListQuery(ctx, async () => {
+            const filter = await readListFilter(qs, SessionListFilter);
+            const sort = readSort(qs, { sortable: ['loginTs', 'email'], default: '-loginTs' });
+            if (!adminSvc.canList) {
+                return { ...pageRows([], qs), supported: false, truncated: false, grants: [] };
+            }
+            const accountId = filter.first('accountId');
+            let sessions;
+            let grants = [];
+            let truncated = false;
+            if (accountId) {
+                const account = await cfg.accountStore.findById(accountId);
+                if (!account) {
+                    return ctx.response.notFound(apiError('not_found', 'Usuário não encontrado.'));
+                }
+                sessions = (await enrichSessionsWithContext(cfg, accountId, await adminSvc.listSessions(accountId))).map((s) => ({ ...s, email: s.email ?? account.email }));
+                grants = (await adminSvc.listGrants(accountId)).map(grantDto);
+            }
+            else {
+                const all = await adminSvc.listAllSessions();
+                sessions = all.sessions;
+                truncated = all.truncated;
+            }
+            const found = searchRows(sessions, readSearch(qs), [(s) => s.email, (s) => s.ip]);
+            const sorted = sortRows(found, sort, {
+                loginTs: (s) => s.loginTs ?? null,
+                email: (s) => s.email ?? null,
+            });
+            const page = pageRows(sorted, qs);
+            return { ...page, data: page.data.map(sessionDto), supported: true, truncated, grants };
+        });
     }
     /** GET {prefix}/api/users/:id/sessions */
     async userSessions(ctx) {

package/build/src/host/admin_console/console_users_controller.d.ts

@@ -3,7 +3,7 @@ import type { HttpContext } from '@adonisjs/core/http';
 /**
  * Endpoints JSON de usuários do console admin React.
  *
- * GET  {prefix}/api/users?search=&page=&size=  → `{ meta: { page, size, total }, data }`
+ * GET  {prefix}/api/users?search=&sort=&page=&size= → `{ data, meta: { total, perPage, currentPage, lastPage, firstPage } }`
  * GET  {prefix}/api/users/:id                     → detalhe + sessões + identidades + MFA status
  * POST {prefix}/api/users                         → criar usuário
  * PATCH {prefix}/api/users/:id/roles              → substituir roles globais
@@ -19,13 +19,17 @@ import type { HttpContext } from '@adonisjs/core/http';
 export default class ConsoleUsersController {
     #private;
     /** GET {prefix}/api/users */
-    index(ctx: HttpContext): Promise<{
-        meta: {
-            page: number;
-            size: number;
-            total: any;
-        };
-        data: any[];
+    index(ctx: HttpContext): Promise<void | {
+        meta: import("@adonis-agora/filter").OffsetPageMeta;
+        data: {
+            id: string;
+            email: string;
+            name: string | null;
+            avatarUrl: string | null;
+            globalRoles: string[];
+            disabled: boolean;
+            roles: string[];
+        }[];
     }>;
     /** GET {prefix}/api/users/:id */
     show(ctx: HttpContext): Promise<void | {

package/build/src/host/admin_console/console_users_controller.js

@@ -1,12 +1,12 @@
 import '../augmentations.js';
 import { supportsAccountDeletion, supportsAccountStatus } from '../../accounts/account_store.js';
-import { ADMIN_LIST_HTTP_DEFAULT_SIZE, parseListPage, parseListSize } from '../../pagination.js';
 import { rolesManagedExternally } from '../account_roles.js';
 import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
 import { AdminUsersService } from '../admin_api/admin_users_service.js';
 import { apiError, grantDto, rolesManagedExternallyError, sessionDto, userDtoWithRoles, } from '../admin_api/dto.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { adminUserCreateValidator, adminUserRolesValidator, adminUserUpdateValidator, } from '../admin_validators.js';
+import { listAccountsPage, withListQuery } from '../list_api.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
 import { resolveEffectiveRolesCatalog } from '../runtime_toggles.js';
 import { enrichSessionsWithContext } from '../session_context.js';
@@ -35,7 +35,7 @@ async function gateSudo(ctx) {
 /**
  * Endpoints JSON de usuários do console admin React.
  *
- * GET  {prefix}/api/users?search=&page=&size=  → `{ meta: { page, size, total }, data }`
+ * GET  {prefix}/api/users?search=&sort=&page=&size= → `{ data, meta: { total, perPage, currentPage, lastPage, firstPage } }`
  * GET  {prefix}/api/users/:id                     → detalhe + sessões + identidades + MFA status
  * POST {prefix}/api/users                         → criar usuário
  * PATCH {prefix}/api/users/:id/roles              → substituir roles globais
@@ -53,17 +53,12 @@ export default class ConsoleUsersController {
     async index(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
         const cfg = service.config;
-        const search = ctx.request.input('search', '').trim();
-        const page = parseListPage(ctx.request.input('page'));
-        const size = parseListSize(ctx.request.input('size'), ADMIN_LIST_HTTP_DEFAULT_SIZE);
-        const result = await cfg.accountStore.listAccounts({
-            search,
-            page,
-            size,
+        return withListQuery(ctx, async () => {
+            const result = await listAccountsPage(cfg.accountStore, ctx.request.qs());
+            const users = new AdminUsersService(cfg);
+            const data = await Promise.all(result.data.map(async (u) => userDtoWithRoles(cfg, u, await users.isDisabled(u.id))));
+            return { ...result, data };
         });
-        const users = new AdminUsersService(cfg);
-        const data = await Promise.all(result.data.map(async (u) => userDtoWithRoles(cfg, u, await users.isDisabled(u.id))));
-        return { meta: { page, size, total: result.total }, data };
     }
     /** GET {prefix}/api/users/:id */
     async show(ctx) {

package/build/src/host/admin_stats_service.js

@@ -68,9 +68,9 @@ export async function computeAdminStats(cfg, sessionsService) {
 async function loadEventsInWindow(audit, type, windowStartMs) {
     const out = [];
     const size = ADMIN_LIST_MAX_SIZE;
-    let page = LIST_FIRST_PAGE;
+    let after;
     while (out.length < MAX_EVENTS) {
-        const result = await audit.list({ type, page, size });
+        const result = await audit.list({ type, size, ...(after !== undefined && { after }) });
         if (result.data.length === 0)
             break;
         let allBelowWindow = true;
@@ -88,9 +88,9 @@ async function loadEventsInWindow(audit, type, windowStartMs) {
         // Página inteira anterior à janela → não há mais nada relevante (ordem desc).
         if (allBelowWindow)
             break;
-        if (result.data.length < size)
+        if (!result.hasNext || !result.nextCursor)
             break;
-        page += 1;
+        after = result.nextCursor;
     }
     return out;
 }

package/build/src/host/bearer_account.d.ts

@@ -1,5 +1,13 @@
 /** Registra a conta autenticada via bearer nesta request. */
 export declare function setBearerAccountId(ctx: object, accountId: string): void;
+/**
+ * Vincula a conta de um bearer que foi autenticado FORA do `oidcBearerGuard`
+ * (ex.: o endpoint MCP do agent) a esta request, para que `getAccountId`,
+ * `realAccountId` e `impersonationState` vejam quem chamou. O chamador conta
+ * como "sem impersonation": qualquer impersonation bearer anterior desta request
+ * é esquecida.
+ */
+export declare function bindBearerAccount(ctx: object, accountId: string): void;
 /** Esquece a conta bearer desta request (falha de autenticação). */
 export declare function clearBearerAccountId(ctx: object): void;
 /**

package/build/src/host/bearer_account.js

@@ -16,6 +16,17 @@ const bearerImpersonations = new WeakMap();
 export function setBearerAccountId(ctx, accountId) {
     bearerAccounts.set(ctx, accountId);
 }
+/**
+ * Vincula a conta de um bearer que foi autenticado FORA do `oidcBearerGuard`
+ * (ex.: o endpoint MCP do agent) a esta request, para que `getAccountId`,
+ * `realAccountId` e `impersonationState` vejam quem chamou. O chamador conta
+ * como "sem impersonation": qualquer impersonation bearer anterior desta request
+ * é esquecida.
+ */
+export function bindBearerAccount(ctx, accountId) {
+    bearerAccounts.set(ctx, accountId);
+    bearerImpersonations.delete(ctx);
+}
 /** Esquece a conta bearer desta request (falha de autenticação). */
 export function clearBearerAccountId(ctx) {
     bearerAccounts.delete(ctx);