@shipfox/api-auth 17.0.0 → 19.0.0

package/src/db/admin-user-summary.test.ts

@@ -0,0 +1,228 @@
+import {eq} from 'drizzle-orm';
+import {userFactory} from '#test/index.js';
+import {createAdminGrant, revokeAdminGrant} from './admin-grants.js';
+import {listAdministratorUserSummaries} from './admin-user-summary.js';
+import {db} from './db.js';
+import {users} from './schema/users.js';
+
+async function setCreatedAt(userId: string, createdAt: Date): Promise<void> {
+  await db().update(users).set({createdAt}).where(eq(users.id, userId));
+}
+
+describe('administrator user summaries db', () => {
+  test('lists users in descending created-at and id order with a limit-plus-one cursor', async () => {
+    const marker = `directory-order-${crypto.randomUUID()}`;
+    const actor = await userFactory.create({email: `${marker}-actor@example.com`});
+    const first = await userFactory.create({email: `${marker}-first@example.com`});
+    const second = await userFactory.create({email: `${marker}-second@example.com`});
+    const third = await userFactory.create({email: `${marker}-third@example.com`});
+    const base = new Date('2099-01-01T00:00:00.000Z');
+    await setCreatedAt(actor.id, new Date(base.getTime() - 1_000));
+    await setCreatedAt(first.id, new Date(base.getTime() + 2_000));
+    await setCreatedAt(second.id, new Date(base.getTime() + 2_000));
+    await setCreatedAt(third.id, new Date(base.getTime() + 1_000));
+    const sameTimestampOrder = [first, second].sort((left, right) => {
+      if (right.id < left.id) return -1;
+      if (right.id > left.id) return 1;
+      return 0;
+    });
+    const newerSameTimestamp = sameTimestampOrder[0];
+    const olderSameTimestamp = sameTimestampOrder[1];
+    if (!newerSameTimestamp || !olderSameTimestamp) {
+      throw new Error('Expected two users with the same timestamp');
+    }
+
+    const unfiltered = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      limit: 4,
+    });
+    expect(unfiltered.rows.slice(0, 4).map(({id}) => id)).toEqual([
+      newerSameTimestamp.id,
+      olderSameTimestamp.id,
+      third.id,
+      actor.id,
+    ]);
+
+    const firstPage = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      limit: 2,
+      search: marker,
+    });
+
+    expect(firstPage.rows.map(({id}) => id)).toEqual([
+      newerSameTimestamp.id,
+      olderSameTimestamp.id,
+    ]);
+    expect(firstPage.nextCursor).toEqual({
+      createdAt: new Date(base.getTime() + 2_000),
+      id: olderSameTimestamp.id,
+    });
+
+    const insertedAfterPage = await userFactory.create({
+      email: `${marker}-inserted@example.com`,
+    });
+    await setCreatedAt(insertedAfterPage.id, new Date(base.getTime() + 4_000));
+
+    const secondPage = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      limit: 2,
+      search: marker,
+      ...(firstPage.nextCursor ? {cursor: firstPage.nextCursor} : {}),
+    });
+
+    expect(secondPage.rows.map(({id}) => id)).toEqual([third.id, actor.id]);
+    expect(secondPage.nextCursor).toBeNull();
+  });
+
+  test('uses exact UUID search and case-insensitive multi-term literal matching', async () => {
+    const actor = await userFactory.create({email: `actor-${crypto.randomUUID()}@example.com`});
+    const user = await userFactory.create({
+      email: `literal%_\\${crypto.randomUUID()}@Example.com`,
+      name: 'Ada Lovelace',
+    });
+    await userFactory.create({
+      email: `control-${crypto.randomUUID()}@example.com`,
+      name: 'Ada Byron',
+    });
+
+    const exact = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      search: user.id,
+      limit: 10,
+    });
+    expect(exact.rows.map(({id}) => id)).toEqual([user.id]);
+
+    const matching = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      search: '  ADA   LOVELACE  ',
+      limit: 10,
+    });
+    expect(matching.rows.map(({id}) => id)).toEqual([user.id]);
+
+    const literal = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      search: '%_',
+      limit: 10,
+    });
+    expect(literal.rows.map(({id}) => id)).toEqual([user.id]);
+
+    const literalBackslash = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      search: '\\',
+      limit: 10,
+    });
+    expect(literalBackslash.rows.map(({id}) => id)).toEqual([user.id]);
+  });
+
+  test('ignores revoked grants when filtering eligibility and projecting roles', async () => {
+    const marker = `directory-revoked-${crypto.randomUUID()}`;
+    const actor = await userFactory.create({email: `${marker}-actor@example.com`});
+    const revoked = await userFactory.create({
+      email: `${marker}-revoked@example.com`,
+      emailVerifiedAt: new Date(),
+    });
+    const grant = await createAdminGrant({userId: revoked.id, role: 'admin-observer'});
+    await revokeAdminGrant({grantId: grant.id});
+
+    const eligibleRows = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      search: marker,
+      eligible: true,
+      limit: 10,
+    });
+    const allRows = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      search: marker,
+      limit: 10,
+    });
+
+    expect(eligibleRows.rows.map(({id}) => id)).toEqual([revoked.id]);
+    expect(allRows.rows).toHaveLength(2);
+    expect(allRows.rows).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({id: revoked.id, adminRole: null}),
+        expect.objectContaining({id: actor.id, adminRole: null}),
+      ]),
+    );
+  });
+
+  test.each(['active', 'suspended', 'deleted'] as const)('filters by %s status', async (status) => {
+    const marker = `directory-status-${status}-${crypto.randomUUID()}`;
+    const actor = await userFactory.create({email: `actor-${crypto.randomUUID()}@example.com`});
+    const user = await userFactory.create({email: `${marker}-user@example.com`});
+    await db().update(users).set({status}).where(eq(users.id, user.id));
+
+    const result = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      search: marker,
+      status,
+      limit: 10,
+    });
+
+    expect(result.rows).toEqual([expect.objectContaining({id: user.id, status})]);
+  });
+
+  test('applies eligibility rules and projects the highest effective role once per user', async () => {
+    const marker = `directory-eligible-${crypto.randomUUID()}`;
+    const actor = await userFactory.create({
+      email: `${marker}-actor@example.com`,
+      emailVerifiedAt: new Date(),
+    });
+    const eligible = await userFactory.create({
+      email: `${marker}-eligible@example.com`,
+      emailVerifiedAt: new Date(),
+    });
+    const unverified = await userFactory.create({email: `${marker}-unverified@example.com`});
+    const granted = await userFactory.create({
+      email: `${marker}-granted@example.com`,
+      emailVerifiedAt: new Date(),
+    });
+    const suspended = await userFactory.create({
+      email: `${marker}-suspended@example.com`,
+      emailVerifiedAt: new Date(),
+    });
+    const deleted = await userFactory.create({
+      email: `${marker}-deleted@example.com`,
+      emailVerifiedAt: new Date(),
+    });
+    await db().update(users).set({status: 'suspended'}).where(eq(users.id, suspended.id));
+    await db().update(users).set({status: 'deleted'}).where(eq(users.id, deleted.id));
+    await createAdminGrant({userId: granted.id, role: 'admin-observer'});
+    await createAdminGrant({userId: granted.id, role: 'admin-operator'});
+    await createAdminGrant({userId: suspended.id, role: 'admin-observer'});
+    await createAdminGrant({userId: deleted.id, role: 'admin-owner'});
+
+    const all = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      search: marker,
+      limit: 20,
+    });
+    expect(all.rows.filter(({id}) => id === granted.id)).toHaveLength(1);
+    expect(all.rows.find(({id}) => id === granted.id)?.adminRole).toBe('admin-operator');
+    expect(all.rows.find(({id}) => id === suspended.id)?.adminRole).toBeNull();
+    expect(all.rows.find(({id}) => id === deleted.id)?.adminRole).toBeNull();
+
+    const eligibleRows = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      search: marker,
+      eligible: true,
+      limit: 20,
+    });
+    expect(eligibleRows.rows.map(({id}) => id)).toEqual([eligible.id]);
+    expect(eligibleRows.rows).not.toEqual(
+      expect.arrayContaining([expect.objectContaining({id: actor.id})]),
+    );
+    expect(unverified.id).not.toBe(eligibleRows.rows[0]?.id);
+
+    const ineligibleRows = await listAdministratorUserSummaries(db(), {
+      actorId: actor.id,
+      search: marker,
+      eligible: false,
+      limit: 20,
+    });
+    expect(ineligibleRows.rows.map(({id}) => id)).toEqual(
+      expect.arrayContaining([actor.id, unverified.id, granted.id, suspended.id, deleted.id]),
+    );
+    expect(ineligibleRows.rows.map(({id}) => id)).not.toContain(eligible.id);
+  });
+});

package/src/db/admin-user-summary.ts

@@ -1,6 +1,25 @@
-import {and, eq, isNull} from 'drizzle-orm';
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import {
+  paginateTimestampIdRows,
+  type TimestampIdCursor,
+  timestampIdCursorWhere,
+} from '@shipfox/node-drizzle';
+import {
+  and,
+  desc,
+  eq,
+  isNotNull,
+  isNull,
+  ne,
+  not,
+  or,
+  type SQL,
+  type SQLWrapper,
+  sql,
+} from 'drizzle-orm';
 import {highestAdminRole} from '#core/admin-role-model.js';
 import type {AdministratorUserSummary} from '#core/entities/administrator-read-model.js';
+import type {UserStatus} from '#core/entities/user.js';
 import type {db} from './db.js';
 import {adminGrants} from './schema/admin-grants.js';
 import {users} from './schema/users.js';
@@ -10,6 +29,64 @@ export type AdministratorUserSummaryExecutor = ReturnType<typeof db> | Tx;
 
 type AdministratorUserLookup = {id: string; email?: never} | {email: string; id?: never};
 
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SEARCH_TERM_SEPARATOR = /\s+/;
+
+export interface ListAdministratorUserSummariesParams {
+  actorId: string;
+  limit: number;
+  cursor?: TimestampIdCursor | undefined;
+  search?: string | undefined;
+  status?: UserStatus | undefined;
+  eligible?: boolean | undefined;
+}
+
+export interface ListAdministratorUserSummariesResult {
+  rows: AdministratorUserSummary[];
+  nextCursor: TimestampIdCursor | null;
+}
+
+function escapeLikeTerm(term: string): string {
+  return term.replace(/[\\%_]/g, (character) => `\\${character}`);
+}
+
+function isUuid(value: string): boolean {
+  return UUID_PATTERN.test(value);
+}
+
+function containsTerm(column: SQLWrapper, term: string): SQLWrapper {
+  return sql`${column} ILIKE ${`%${escapeLikeTerm(term)}%`}`;
+}
+
+function addEligibilityCondition(
+  conditions: SQL[],
+  params: Pick<ListAdministratorUserSummariesParams, 'actorId' | 'eligible'>,
+  activeAdminRoleUserId: SQLWrapper,
+): void {
+  const eligibleCondition = and(
+    eq(users.status, 'active'),
+    isNotNull(users.emailVerifiedAt),
+    isNull(activeAdminRoleUserId),
+    ne(users.id, params.actorId),
+  );
+  if (eligibleCondition && params.eligible === true) conditions.push(eligibleCondition);
+  if (eligibleCondition && params.eligible === false) conditions.push(not(eligibleCondition));
+}
+
+function addSearchConditions(conditions: SQL[], search: string | undefined): void {
+  const normalizedSearch = search?.trim() ?? '';
+  if (!normalizedSearch) return;
+  if (isUuid(normalizedSearch)) {
+    conditions.push(eq(users.id, normalizedSearch));
+    return;
+  }
+
+  for (const term of normalizedSearch.split(SEARCH_TERM_SEPARATOR)) {
+    const termCondition = or(containsTerm(users.name, term), containsTerm(users.email, term));
+    if (termCondition) conditions.push(termCondition);
+  }
+}
+
 export async function findAdministratorUserSummary(
   executor: AdministratorUserSummaryExecutor,
   params: AdministratorUserLookup,
@@ -49,3 +126,68 @@ export async function findAdministratorUserSummary(
     adminRole: highestAdminRole(rows.flatMap(({adminRole}) => (adminRole ? [adminRole] : []))),
   } satisfies AdministratorUserSummary;
 }
+
+/**
+ * Lists a live directory view using keyset pagination.
+ *
+ * Pages are not a consistent snapshot. Each page reads current account and grant state, so
+ * inserts and account or grant changes can make consecutive pages differ. Re-run the listing
+ * before acting on a row.
+ */
+export async function listAdministratorUserSummaries(
+  executor: AdministratorUserSummaryExecutor,
+  params: ListAdministratorUserSummariesParams,
+): Promise<ListAdministratorUserSummariesResult> {
+  // Aggregate grants in a subquery so pagination is over users, not grants.
+  const activeAdminRoles = executor
+    .select({
+      userId: adminGrants.userId,
+      roles: sql<AdminRole[]>`json_agg(${adminGrants.role})`.as('roles'),
+    })
+    .from(adminGrants)
+    .where(isNull(adminGrants.revokedAt))
+    .groupBy(adminGrants.userId)
+    .as('active_admin_roles');
+
+  const conditions: SQL[] = [];
+  const cursorCondition = timestampIdCursorWhere({
+    timestampColumn: users.createdAt,
+    idColumn: users.id,
+    cursor: params.cursor,
+  });
+  if (cursorCondition) conditions.push(cursorCondition);
+  if (params.status) conditions.push(eq(users.status, params.status));
+
+  addEligibilityCondition(conditions, params, activeAdminRoles.userId);
+  addSearchConditions(conditions, params.search);
+
+  const rows = await executor
+    .select({
+      id: users.id,
+      email: users.email,
+      name: users.name,
+      emailVerifiedAt: users.emailVerifiedAt,
+      status: users.status,
+      createdAt: users.createdAt,
+      adminRoles: activeAdminRoles.roles,
+    })
+    .from(users)
+    .leftJoin(activeAdminRoles, eq(activeAdminRoles.userId, users.id))
+    .where(and(...conditions))
+    .orderBy(desc(users.createdAt), desc(users.id))
+    .limit(params.limit + 1);
+
+  const mappedRows = rows.map(
+    ({adminRoles, ...row}): AdministratorUserSummary => ({
+      ...row,
+      adminRole: row.status === 'active' ? highestAdminRole(adminRoles ?? []) : null,
+    }),
+  );
+  const page = paginateTimestampIdRows({
+    rows: mappedRows,
+    limit: params.limit,
+    timestampKey: 'createdAt',
+  });
+
+  return {rows: page.pageRows, nextCursor: page.nextCursor};
+}

package/src/db/admin-users.ts

@@ -1,5 +1,10 @@
+import type {TimestampIdCursor} from '@shipfox/node-drizzle';
 import type {AdministratorUserSummary} from '#core/entities/administrator-read-model.js';
-import {findAdministratorUserSummary} from './admin-user-summary.js';
+import {
+  findAdministratorUserSummary,
+  type ListAdministratorUserSummariesResult,
+  listAdministratorUserSummaries,
+} from './admin-user-summary.js';
 import {db} from './db.js';
 
 export type AdministratorUserRecord = AdministratorUserSummary;
@@ -11,3 +16,18 @@ export async function findAdministratorUser(
 ): Promise<AdministratorUserRecord | undefined> {
   return await findAdministratorUserSummary(db(), params);
 }
+
+export interface ListAdministratorUsersParams {
+  actorId: string;
+  limit: number;
+  cursor?: TimestampIdCursor | undefined;
+  search?: string | undefined;
+  status?: AdministratorUserSummary['status'] | undefined;
+  eligible?: boolean | undefined;
+}
+
+export async function listAdministratorUsers(
+  params: ListAdministratorUsersParams,
+): Promise<ListAdministratorUserSummariesResult> {
+  return await listAdministratorUserSummaries(db(), params);
+}