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

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @adonis-agora/authkit-server
 
+## 1.0.0-rc.17
+
+### Major Changes
+
+- [#484](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/484) [`4a9eeb4`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/4a9eeb46782e78ad06ad0c2955e49398ab21bc7e) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Lists use the `@adonis-agora/filter` wire format: `filter[field]=…`, `search`, `sort=-field`, then `page`/`size` or a cursor. A filter field, operator or sort a list does not support answers `400 { error: { code: 'invalid_list_query' } }`.
+  
+  `@adonis-agora/authkit-server`:
+  
+  - `GET {admin}/api/users` and Admin API `GET /users`: `?search&sort&page&size` (`sort` accepts `email` only) → `{ data, meta: { total, perPage, currentPage, lastPage, firstPage } }` (was `meta: { page, size, total }`).
+  - `GET {admin}/api/clients` and `GET /clients`: page with `?search&sort&page&size` (`sort`: `clientId`, `clientName`) → `{ data, meta, canList }`.
+  - `GET {admin}/api/orgs` and `GET /organizations`: page with `?search&sort&page&size` (`sort`: `name`, `slug`, `createdAt`, `memberCount`) → `{ data, meta }`.
+  - `GET {admin}/api/audit` and `GET /audit`: newest first, by cursor. `?filter[type]` (one or more), `?filter[subject]`, `after` / `before` + `first` / `last` → `{ data, meta: { nextCursor, prevCursor, hasNext, hasPrev } }`. `?type`, `?subject`, `page` and `size` are gone.
+  - `GET {admin}/api/sessions`: `?filter[accountId]&search&sort&page&size` (`sort`: `loginTs`, `email`; default `-loginTs`) → `{ data, meta, supported, truncated, grants }` (was `{ supported, truncated, sessions, grants }` with `?accountId`).
+  - `GET {admin}/api/personal-agents/connections`: `filter[protocol]`, `filter[clientId]`, `filter[accountId]` (were flat `?protocol=`…) → `{ data, meta }` with the offset meta above.
+  - `GET {admin}/api/overview`: `auditTotal` is `null` when the audit sink cannot count.
+  - `AuditSink.list` pages by cursor: it takes `{ type?: string | string[], subject?, size?, after?, before? }` and returns `{ data, nextCursor, prevCursor, hasNext, hasPrev }` (newest first). New optional `AuditSink.count({ type?, subject? })`. `lucidAuditSink` implements both (keyset on `createdAt`, `id`). Custom sinks with `list` must follow the new shape.
+  - The `authkit_list_audit` dev tool takes `cursor` (the previous result's `next`) instead of `page`, and no longer returns `total`.
+  - The `authkit_get_overview` dev tool returns `auditTotal: null` when the audit sink cannot count.
+  - Removed exports: `ListMeta`, `PaginatedResponse`, `parseListPage`, `parseListSize`. New exports: `listAccountsPage`, `listAuditPage`, `listClientsPage`, `listOrgsPage`, the list filter classes and `CountAuditParams`.
+  - Depends on `@adonis-agora/filter`.
+  
+  `@adonis-agora/authkit-react`:
+  
+  - `client.admin.users.list({ search?, sort?, page?, size? })`, `clients.list(params?)`, `orgs.list(params?)` return `OffsetPage<T>` (`meta: { total, perPage, currentPage, lastPage, firstPage }`).
+  - `client.admin.sessions.list({ accountId?, search?, sort?, page?, size? })` (was `list(accountId?)`) returns `AdminSessionListResult` (`data` instead of `sessions`).
+  - `client.admin.audit.list({ type?, subject?, after?, before?, first?, last? })` returns `CursorPageResponse<AuditEventEntry>`; `page` / `size` are gone.
+  - `useSessionsQueryOptions(params?)`, `useClientsQueryOptions(params?)` and `useOrgsQueryOptions(params?)` take the list params; `authkitKeys.admin.sessions/clients/orgs` take them too.
+  - `ListMeta` is removed; `OffsetPage`, `OffsetPageMeta`, `CursorPageResponse`, `CursorPageMeta`, `AdminListParams`, `CursorListParams`, `AdminSessionListParams` and `AdminSessionListResult` are exported. `AdminOverview.auditTotal` is `number | null`.
+  
+  `@adonis-agora/authkit-sdk`:
+  
+  - `users.list`, `clients.list` and `organizations.list` take `{ search?, sort?, page?, size? }` and return `OffsetPage<T>` (`clients.list` adds `canList`).
+  - `audit.list({ type?, subject?, after?, before?, first?, last? })` returns `CursorPageResponse<AuthkitAuditEvent>`.
+  - `ListMeta` is removed; `OffsetPage`, `CursorPageResponse`, `OffsetListParams`, `CursorListParams`, `ListClientsParams` and `ListOrganizationsParams` are exported.
+
+## 1.0.0-rc.16
+
+### Patch Changes
+
+- [#483](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/483) [`dcfbed1`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/dcfbed164d3d79dae3f37ad70ad07b5450822887) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - The `authkit.server` service gains `bindBearerAccount(ctx, accountId)`. Code that verified an authkit access token outside `oidcBearerGuard` (for example `@adonis-agora/agent`'s dev MCP endpoint) calls it to put the caller on the request: `getAccountId(ctx)` and `realAccountId(ctx)` then return that account, and `impersonationState(ctx)` reports no impersonation. A console session on the same request still wins.
+
 ## 1.0.0-rc.15
 
 ### Patch Changes

package/build/index.d.ts

@@ -21,7 +21,7 @@ export { personalAgentAuth, personalAgentOf, personalAgentReceipt, personalAgent
 export type { BuiltinProtocolId, PactOptions, PersonalAgentProtocol, } from './src/agents/protocol.js';
 export { pact, pactProtocol } from './src/agents/protocol.js';
 export { type PersonalAgentRuntimeSource, personalAgentExtensionRuntime, } from './src/agents/runtime.js';
-export type { AuditEvent, AuditEventType, AuditPage, AuditSink, ListAuditParams, StoredAuditEvent, } from './src/audit/audit_sink.js';
+export type { AuditEvent, AuditEventType, AuditPage, AuditSink, CountAuditParams, ListAuditParams, StoredAuditEvent, } from './src/audit/audit_sink.js';
 export { lucidAuditSink } from './src/audit/lucid_audit_sink.js';
 export type { ConsoleAuthorize, ConsoleAuthorizeResult, ConsoleAuthorizer, ConsoleAuthorizerClass, } from './src/console_authorize.js';
 export { authorizeByToken } from './src/console_authorize.js';
@@ -101,6 +101,7 @@ export type { ImpersonationStartErrorCode, ImpersonationState, StartImpersonatio
 export { ImpersonationStartError, impersonationState, refreshAccessToken, rememberAccessToken, rememberRefreshToken, startImpersonation, stopImpersonation, } from './src/host/impersonation_session.js';
 export type { KeysStatus as ServerKeysStatus } from './src/host/key_rotation_actions.js';
 export { buildKeysStatus, rotateNow } from './src/host/key_rotation_actions.js';
+export { AuditListFilter, ConnectionListFilter, type ListQuery, listAccountsPage, listAuditPage, listClientsPage, listOrgsPage, NoListFilter, SessionListFilter, } from './src/host/list_api.js';
 export type { OidcBearerGuardEvents, OidcBearerGuardOptions, OidcBearerGuardPolicy, } from './src/host/oidc_bearer_guard.js';
 export { OidcBearerGuard, oidcBearerGuard } from './src/host/oidc_bearer_guard.js';
 export type { OidcRpGuardEvents, OidcRpGuardOptions } from './src/host/oidc_rp_guard.js';
@@ -144,8 +145,7 @@ export type { ProviderIdentityClass, ProviderIdentityRow, } from './src/mixins/w
 export { withProviderIdentity } from './src/mixins/with_provider_identity.js';
 export type { WebauthnCredentialClass, WebauthnCredentialRow, } from './src/mixins/with_webauthn_credential.js';
 export { withWebauthnCredential } from './src/mixins/with_webauthn_credential.js';
-export type { ListMeta, PaginatedResponse } from './src/pagination.js';
-export { ADMIN_LIST_DEFAULT_SIZE, ADMIN_LIST_HTTP_DEFAULT_SIZE, ADMIN_LIST_MAX_SIZE, clampListSize, LIST_FIRST_PAGE, normalizeListSize, parseListPage, parseListSize, resolveListPage, } from './src/pagination.js';
+export { ADMIN_LIST_DEFAULT_SIZE, ADMIN_LIST_HTTP_DEFAULT_SIZE, ADMIN_LIST_MAX_SIZE, clampListSize, LIST_FIRST_PAGE, normalizeListSize, resolveListPage, } from './src/pagination.js';
 export type { LegacyPasswordVerifier, PasswordConfigInput, PasswordVerifyResult, } from './src/password/password_manager.js';
 export { PasswordManager, PasswordPolicyError, } from './src/password/password_manager.js';
 export type { PasswordPolicyViolation, ResolvedPasswordConfig, ResolvedPasswordPolicy, } from './src/password/policy.js';

package/build/index.js

@@ -73,6 +73,7 @@ export { buildImpersonationPanel } from './src/host/impersonation.js';
 export { ImpersonationStartError, impersonationState, refreshAccessToken, rememberAccessToken, rememberRefreshToken, startImpersonation, stopImpersonation, } from './src/host/impersonation_session.js';
 // Key rotation actions — shared between the Admin REST API controller and the SDK embedded driver.
 export { buildKeysStatus, rotateNow } from './src/host/key_rotation_actions.js';
+export { AuditListFilter, ConnectionListFilter, listAccountsPage, listAuditPage, listClientsPage, listOrgsPage, NoListFilter, SessionListFilter, } from './src/host/list_api.js';
 // @adonisjs/auth integration (opt-in) — guard de access token (Authorization:
 // Bearer) pra APIs chamadas por apps nativos (RFC 8252), SPAs e serviços. Par do
 // oidcRpGuard para clientes sem sessão web; verifica in-process (issuer embarcado)
@@ -126,7 +127,7 @@ export { withCredentials } from './src/mixins/with_credentials.js';
 export { withPersonalAccessToken } from './src/mixins/with_personal_access_token.js';
 export { withProviderIdentity } from './src/mixins/with_provider_identity.js';
 export { withWebauthnCredential } from './src/mixins/with_webauthn_credential.js';
-export { ADMIN_LIST_DEFAULT_SIZE, ADMIN_LIST_HTTP_DEFAULT_SIZE, ADMIN_LIST_MAX_SIZE, clampListSize, LIST_FIRST_PAGE, normalizeListSize, parseListPage, parseListSize, resolveListPage, } from './src/pagination.js';
+export { ADMIN_LIST_DEFAULT_SIZE, ADMIN_LIST_HTTP_DEFAULT_SIZE, ADMIN_LIST_MAX_SIZE, clampListSize, LIST_FIRST_PAGE, normalizeListSize, resolveListPage, } from './src/pagination.js';
 // Gerência de senha: lazy rehash + legacy verifier, política e checagem de vazamento.
 export { PasswordManager, PasswordPolicyError, } from './src/password/password_manager.js';
 export { checkPasswordPolicy, DEFAULT_PWNED_TIMEOUT_MS, policyViolationParams, } from './src/password/policy.js';

package/build/src/audit/audit_sink.d.ts

@@ -43,31 +43,36 @@ export interface StoredAuditEvent extends AuditEvent {
     createdAt: Date | string | null;
 }
 /**
- * Filtros de listagem do log de auditoria (console admin).
+ * What {@link AuditSink.list} returns: one page of the log, NEWEST FIRST, read by cursor.
  *
- * O par `{ page, size }` espelha INTENCIONALMENTE o shape de paginação por
- * offset de `@adonis-agora/filter` (`FilterInput.page`/`.size`), para manter a
- * mesma interface em todo o ecossistema `@adonis-agora/*`. É um casamento
- * ESTRUTURAL: não há dependência de `@adonis-agora/filter` aqui.
+ * The log is append-only and grows without bound, so it pages by an opaque cursor rather than
+ * by page number: `after` = the `nextCursor` of the previous page (older events), `before` =
+ * the `prevCursor` of a page (newer events). The cursor's content is the sink's business; the
+ * caller hands back what the sink returned.
  */
 export interface ListAuditParams {
-    /** Página (1-based). Default: 1. */
-    page?: number;
-    /**
-     * Itens por página. Default: 20; limitado a `ADMIN_LIST_MAX_SIZE` (200).
-     *
-     * Renomeado de `limit` para `size` para casar com `@adonis-agora/filter`.
-     */
-    size?: number;
-    /** Filtra por tipo de evento exato. */
-    type?: string;
-    /** Filtra pelo subject (accountId) do evento. */
+    /** Only events of this type (or of any of these types). */
+    type?: string | readonly string[];
+    /** Only events about this account (`accountId`). */
     subject?: string;
+    /** Events per page. Default 20. */
+    size?: number;
+    /** The page after this cursor (older events). Wins over `before`. */
+    after?: string;
+    /** The page before this cursor (newer events). */
+    before?: string;
 }
-/** Página de eventos + total absoluto. */
+/** The filters of {@link AuditSink.count}. */
+export type CountAuditParams = Pick<ListAuditParams, 'type' | 'subject'>;
+/** One page of events, newest first, and the cursors around it. */
 export interface AuditPage {
     data: StoredAuditEvent[];
-    total: number;
+    /** Cursor of the next (older) page, `null` on the last one. */
+    nextCursor: string | null;
+    /** Cursor of the previous (newer) page, `null` on the first one. */
+    prevCursor: string | null;
+    hasNext: boolean;
+    hasPrev: boolean;
 }
 /**
  * Sink plugável de auditoria. Implementações devem ser best-effort: `record`
@@ -79,8 +84,10 @@ export interface AuditPage {
  */
 export interface AuditSink {
     record(event: AuditEvent): Promise<void>;
-    /** Lista eventos paginados (opcional — só sinks que suportam consulta). */
+    /** One page of events, newest first (optional: only sinks that can be queried). */
     list?(params: ListAuditParams): Promise<AuditPage>;
+    /** How many events match (optional; the admin overview shows it when present). */
+    count?(params: CountAuditParams): Promise<number>;
     /**
      * Anonimiza (LGPD/GDPR) os eventos de uma conta SEM apagar o histórico: remove
      * os identificadores pessoais (`email`, `ip`) e re-escreve o `accountId` para um

package/build/src/audit/lucid_audit_sink.js

@@ -1,5 +1,58 @@
 import { createHash } from 'node:crypto';
-import { ADMIN_LIST_HTTP_DEFAULT_SIZE, normalizeListSize, resolveListPage } from '../pagination.js';
+import { decodeCursor, encodeCursor } from '@adonis-agora/filter';
+import { DateTime } from 'luxon';
+import { ADMIN_LIST_HTTP_DEFAULT_SIZE, normalizeListSize } from '../pagination.js';
+/** Narrows an audit query to the requested type(s) and subject. */
+function filtered(q, params) {
+    const types = params.type === undefined ? [] : [].concat(params.type);
+    if (types.length === 1)
+        q.where('type', types[0]);
+    else if (types.length > 1)
+        q.whereIn('type', types);
+    if (params.subject)
+        q.where('accountId', params.subject);
+    return q;
+}
+/** A Lucid `createdAt` (luxon), a `Date` or an ISO string, as an ISO string. */
+function isoOf(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value.toISO === 'function')
+        return value.toISO();
+    if (value instanceof Date)
+        return value.toISOString();
+    return String(value);
+}
+function toStored(row) {
+    return {
+        id: String(row.id),
+        type: row.type,
+        accountId: row.accountId ?? null,
+        email: row.email ?? null,
+        clientId: row.clientId ?? null,
+        actorId: row.actorId ?? null,
+        ip: row.ip ?? null,
+        metadata: row.metadata ?? undefined,
+        createdAt: isoOf(row.createdAt),
+    };
+}
+/** The row's position in the log (`createdAt`, primary key), as an opaque cursor. */
+function encodeAuditCursor(row) {
+    return encodeCursor([isoOf(row.createdAt), row.$primaryKeyValue ?? row.id]);
+}
+/** A cursor back to `{ at, id }`; `null` for anything this sink did not produce. */
+function decodeAuditCursor(cursor) {
+    const values = decodeCursor(cursor);
+    if (!values || values.length !== 2 || typeof values[0] !== 'string')
+        return null;
+    const at = DateTime.fromISO(values[0]);
+    if (!at.isValid)
+        return null;
+    const id = values[1];
+    if (typeof id !== 'string' && typeof id !== 'number')
+        return null;
+    return { at, id };
+}
 /**
  * Pseudônimo estável para um accountId anonimizado: `anon:<sha256(accountId)[:16]>`.
  * Mantém os eventos de uma conta deletada correlacionáveis ENTRE SI (mesmo
@@ -36,35 +89,53 @@ export function lucidAuditSink(Model) {
             }
         },
         async list(params) {
-            const page = resolveListPage(params.page);
+            // The primary key breaks ties between events written in the same instant.
+            const pk = Model.primaryKey ?? 'id';
             const size = normalizeListSize(params.size, ADMIN_LIST_HTTP_DEFAULT_SIZE);
-            const base = () => {
-                const q = Model.query();
-                if (params.type)
-                    q.where('type', params.type);
-                if (params.subject)
-                    q.where('accountId', params.subject);
-                return q;
+            const after = params.after ? decodeAuditCursor(params.after) : null;
+            const before = !after && params.before ? decodeAuditCursor(params.before) : null;
+            const backward = before !== null;
+            const seek = after ?? before;
+            // Newest first: (createdAt, id) DESC. Going backward the seek and the order flip, and the
+            // rows are flipped back below. One extra row tells whether a further page exists.
+            const q = filtered(Model.query(), params);
+            if (seek) {
+                const op = backward ? '>' : '<';
+                // Formatted the way Lucid writes `createdAt` for this dialect: nested `where` callbacks
+                // do not convert a luxon value, and the comparison must be against the stored form.
+                const format = q.client?.dialect?.dateTimeFormat;
+                const at = format ? seek.at.toFormat(format) : seek.at.toJSDate();
+                q.where((w) => {
+                    w.where('createdAt', op, at).orWhere((eq) => {
+                        eq.where('createdAt', at).where(pk, op, seek.id);
+                    });
+                });
+            }
+            const dir = backward ? 'asc' : 'desc';
+            const rows = await q
+                .orderBy('createdAt', dir)
+                .orderBy(pk, dir)
+                .limit(size + 1);
+            const hasMore = rows.length > size;
+            let page = hasMore ? rows.slice(0, size) : rows;
+            if (backward)
+                page = page.slice().reverse();
+            const data = page.map(toStored);
+            const first = page[0];
+            const last = page[page.length - 1];
+            const hasNext = backward ? seek !== null : hasMore;
+            const hasPrev = backward ? hasMore : seek !== null;
+            return {
+                data,
+                nextCursor: hasNext && last ? encodeAuditCursor(last) : null,
+                prevCursor: hasPrev && first ? encodeAuditCursor(first) : null,
+                hasNext,
+                hasPrev,
             };
-            const countResult = await base().count('* as total');
-            const total = Number(countResult[0]?.$extras?.total ?? 0);
-            const rows = await base()
-                .orderBy('createdAt', 'desc')
-                .offset((page - 1) * size)
-                .limit(size);
-            const data = rows.map((row) => ({
-                id: String(row.id),
-                type: row.type,
-                accountId: row.accountId ?? null,
-                email: row.email ?? null,
-                clientId: row.clientId ?? null,
-                actorId: row.actorId ?? null,
-                ip: row.ip ?? null,
-                metadata: row.metadata ?? undefined,
-                // createdAt é um luxon DateTime no Lucid; normaliza para ISO string.
-                createdAt: row.createdAt?.toISO?.() ?? row.createdAt ?? null,
-            }));
-            return { data, total };
+        },
+        async count(params) {
+            const result = await filtered(Model.query(), params).count('* as total');
+            return Number(result[0]?.$extras?.total ?? 0);
         },
         /**
          * Anonimiza (LGPD/GDPR) as linhas de audit cujo subject (`accountId`) OU ator

package/build/src/commands/expire_scan_command.js

@@ -150,7 +150,6 @@ async function getLastLoginMs(audit, accountId) {
         const result = await audit.list({
             type: 'login.success',
             subject: accountId,
-            page: LIST_FIRST_PAGE,
             size: 1,
         });
         if (result.data.length === 0)
@@ -174,7 +173,6 @@ async function wasWarnedRecently(audit, accountId, warnDays) {
         const result = await audit.list({
             type: 'account.expiration_warned',
             subject: accountId,
-            page: LIST_FIRST_PAGE,
             size: 1,
         });
         if (result.data.length === 0)

package/build/src/dev_tools/tools.js

@@ -98,9 +98,8 @@ export function authkitDevTools(deps = {}) {
                 const stats = await computeAdminStats(cfg, sessions(svc));
                 const clientSvc = clients(svc);
                 const clientsCount = clientSvc.canList ? (await clientSvc.list()).length : 0;
-                const recent = typeof cfg.audit?.list === 'function'
-                    ? await cfg.audit.list({ page: LIST_FIRST_PAGE, size: 5 })
-                    : null;
+                const recent = 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,
@@ -112,7 +111,7 @@ export function authkitDevTools(deps = {}) {
                     windowDays: stats.windowDays,
                     auditSupported: stats.auditSupported,
                     clientsCount,
-                    auditTotal: recent?.total ?? 0,
+                    auditTotal,
                     recentEvents: (recent?.data ?? []).map(auditDto),
                 };
             },
@@ -290,13 +289,13 @@ export function authkitDevTools(deps = {}) {
         {
             name: 'authkit_list_audit',
             kind: 'read',
-            description: 'The audit log, newest first: event type, account, actor, client, IP, metadata, time. Filter by `type` (e.g. "login.failure") and `subject` (an account id). Returns { supported, items, total, next }.',
+            description: 'The audit log, newest first: event type, account, actor, client, IP, metadata, time. Filter by `type` (e.g. "login.failure") and `subject` (an account id). Pass the `next` of a result as `cursor` for the following (older) page. Returns { supported, items, next }.',
             input: {
                 type: 'object',
                 properties: {
                     type: { type: 'string', description: 'Event type, e.g. "login.success".' },
                     subject: { type: 'string', description: 'Account id the events are about.' },
-                    page,
+                    cursor: { type: 'string', description: 'The `next` of the previous page.' },
                     limit,
                 },
             },
@@ -304,20 +303,19 @@ export function authkitDevTools(deps = {}) {
                 const cfg = (await service(call.ctx)).config;
                 const sink = cfg.audit;
                 if (!sink || typeof sink.list !== 'function') {
-                    return { supported: false, items: [], total: 0, next: null };
+                    return { supported: false, items: [], next: null };
                 }
-                const p = pageOf(input);
+                const cursor = text(input, 'cursor');
                 const result = await sink.list({
-                    page: p.page,
-                    size: p.limit,
+                    size: pageOf(input).limit,
                     type: text(input, 'type'),
                     subject: text(input, 'subject'),
+                    ...(cursor !== undefined && { after: cursor }),
                 });
                 return {
                     supported: true,
                     items: result.data.map(auditDto),
-                    total: result.total,
-                    next: nextPage(p.page, p.limit, result.total),
+                    next: result.hasNext ? result.nextCursor : null,
                 };
             },
         },

package/build/src/host/account_export_service.js

@@ -1,5 +1,4 @@
 import { supportsOrganizations, supportsPasskeys, supportsProviderIdentity, } from '../accounts/account_store.js';
-import { LIST_FIRST_PAGE } from '../pagination.js';
 import { AdminSessionsService } from './admin_sessions_service.js';
 /** Limite de eventos de audit incluídos no export (evita payloads gigantes). */
 const AUDIT_EXPORT_SIZE = 1000;
@@ -103,7 +102,6 @@ export class AccountExportService {
             try {
                 const page = await cfg.audit.list({
                     subject: accountId,
-                    page: LIST_FIRST_PAGE,
                     size: AUDIT_EXPORT_SIZE,
                 });
                 auditLog = page.data.map((e) => ({

package/build/src/host/admin_api/api_clients_controller.d.ts

@@ -7,7 +7,12 @@ import type { HttpContext } from '@adonisjs/core/http';
  */
 export default class ApiClientsController {
     #private;
-    index(ctx: HttpContext): Promise<{
+    /**
+     * GET /clients — `?search=&sort=clientId|clientName&page=&size=` →
+     * `{ data, meta: { total, perPage, currentPage, lastPage, firstPage }, canList }`.
+     */
+    index(ctx: HttpContext): Promise<void | {
+        meta: import("@adonis-agora/filter").OffsetPageMeta;
         data: {
             clientId: string;
             confidential: boolean;

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

@@ -2,6 +2,7 @@ import '../augmentations.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';
 import { apiError, clientDto, createdClientDto } from './dto.js';
 /** Resolve o serviço (== OidcService) + o AdminClientsService. */
 async function clientsService(ctx) {
@@ -21,13 +22,16 @@ function invalidMetadata(ctx, err) {
  * em create/regenerate. Audita create/update/delete.
  */
 export default class ApiClientsController {
+    /**
+     * GET /clients — `?search=&sort=clientId|clientName&page=&size=` →
+     * `{ data, meta: { total, perPage, currentPage, lastPage, firstPage }, canList }`.
+     */
     async index(ctx) {
         const { svc } = await clientsService(ctx);
-        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 };
+        });
     }
     async show(ctx) {
         const { svc } = await clientsService(ctx);

package/build/src/host/admin_api/api_misc_controller.d.ts

@@ -5,14 +5,24 @@ import type { HttpContext } from '@adonisjs/core/http';
  * introspecção genérica de token (`POST /tokens/verify`).
  */
 export default class ApiMiscController {
-    /** GET /audit — `{ meta: { page, size, total }, data }` (501 JSON quando o sink não consulta). */
+    /**
+     * GET /audit — newest first, `?filter[type]=&filter[subject]=&after=&before=&first=&last=` →
+     * `{ data, meta: { nextCursor, prevCursor, hasNext, hasPrev } }` (501 JSON when the sink
+     * cannot be queried).
+     */
     audit(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;
+        }[];
     }>;
     /** GET /stats — métricas-resumo do IdP (totais + MAU + séries de 30 dias). */
     stats(ctx: HttpContext): Promise<import("../admin_stats_service.js").AdminStats>;

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

@@ -1,8 +1,8 @@
 import '../augmentations.js';
-import { ADMIN_LIST_HTTP_DEFAULT_SIZE, parseListPage, parseListSize } from '../../pagination.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { computeAdminStats } from '../admin_stats_service.js';
 import { tokenVerifyValidator } from '../admin_validators.js';
+import { listAuditPage, withListQuery } from '../list_api.js';
 import { apiError, auditDto } from './dto.js';
 import { TokenVerifyService } from './token_verify_service.js';
 /**
@@ -10,7 +10,11 @@ import { TokenVerifyService } from './token_verify_service.js';
  * introspecção genérica de token (`POST /tokens/verify`).
  */
 export default class ApiMiscController {
-    /** GET /audit — `{ meta: { page, size, total }, data }` (501 JSON quando o sink não consulta). */
+    /**
+     * GET /audit — newest first, `?filter[type]=&filter[subject]=&after=&before=&first=&last=` →
+     * `{ data, meta: { nextCursor, prevCursor, hasNext, hasPrev } }` (501 JSON when the sink
+     * cannot be queried).
+     */
     async audit(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
         const cfg = service.config;
@@ -20,12 +24,10 @@ export default class ApiMiscController {
                 .status(501)
                 .send(apiError('not_implemented', '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) };
+        });
     }
     /** GET /stats — métricas-resumo do IdP (totais + MAU + séries de 30 dias). */
     async stats(ctx) {

package/build/src/host/admin_api/api_orgs_controller.d.ts

@@ -5,8 +5,12 @@ import type { HttpContext } from '@adonisjs/core/http';
  * Todas as rotas ficam sob `/api/authkit/v1/organizations`.
  */
 export default class ApiOrgsController {
-    /** GET /organizations — lista todas as orgs com contagem de membros. */
+    /**
+     * GET /organizations — `?search=&sort=name|slug|createdAt|memberCount&page=&size=` →
+     * `{ data, meta: { total, perPage, currentPage, lastPage, firstPage } }`, with member counts.
+     */
     index(ctx: HttpContext): Promise<void | {
+        meta: import("@adonis-agora/filter").OffsetPageMeta;
         data: {
             id: string;
             name: string;

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

@@ -1,5 +1,6 @@
 import '../augmentations.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';
 import { AdminOrgsService } from './admin_orgs_service.js';
@@ -20,19 +21,20 @@ function notSupported(ctx) {
  * Todas as rotas ficam sob `/api/authkit/v1/organizations`.
  */
 export default class ApiOrgsController {
-    /** GET /organizations — lista todas as orgs com contagem de membros. */
+    /**
+     * GET /organizations — `?search=&sort=name|slug|createdAt|memberCount&page=&size=` →
+     * `{ data, meta: { total, perPage, currentPage, lastPage, firstPage } }`, with member counts.
+     */
     async index(ctx) {
         const { cfg, service } = await ctxBits(ctx);
         const svc = new AdminOrgsService(cfg, service);
         const result = await svc.listOrgs();
-        if (!Array.isArray(result)) {
-            if (result.reason === 'not_supported')
-                return notSupported(ctx);
-        }
-        const orgs = result;
-        if (!Array.isArray(orgs))
+        if (!Array.isArray(result))
             return notSupported(ctx);
-        return { data: orgs.map(orgDto) };
+        return withListQuery(ctx, async () => {
+            const page = await listOrgsPage(result, ctx.request.qs());
+            return { ...page, data: page.data.map(orgDto) };
+        });
     }
     /** POST /organizations — cria uma org. Body: { name, slug, ownerAccountId, logoUrl? } */
     async store(ctx) {

package/build/src/host/admin_api/api_users_controller.d.ts

@@ -6,14 +6,21 @@ import type { HttpContext } from '@adonisjs/core/http';
  */
 export default class ApiUsersController {
     #private;
-    /** GET /users — `{ meta: { page, size, total }, data }`, com busca por e-mail. */
-    index(ctx: HttpContext): Promise<{
-        meta: {
-            page: number;
-            size: number;
-            total: any;
-        };
-        data: any[];
+    /**
+     * GET /users — `?search=&sort=email&page=&size=` →
+     * `{ data, meta: { total, perPage, currentPage, lastPage, firstPage } }`.
+     */
+    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 /users/:id */
     show(ctx: HttpContext): Promise<void | {