@shipfox/api-auth 18.0.0 → 20.0.0

package/src/core/oauth-client.ts

@@ -0,0 +1,331 @@
+import {
+  OAUTH_READ_SCOPE,
+  type OAuthClientMetadataDocumentDto,
+  type OAuthDynamicClientRegistrationRequestDto,
+  oauthClientMetadataDocumentSchema,
+  oauthDynamicClientRegistrationRequestSchema,
+} from '@shipfox/api-auth-dto';
+import type {AgentClient} from './entities/agent-access.js';
+import {
+  InvalidOAuthClientMetadataError,
+  InvalidOAuthConfigurationError,
+  OAuthRedirectUriNotRegisteredError,
+} from './errors.js';
+
+const URI_SUFFIX_PATTERN = /[/?#]/u;
+const PORT_PATTERN = /^\d+$/u;
+const BRACKETED_PORT_PATTERN = /^:\d+$/u;
+
+function hasControlCharacter(value: string): boolean {
+  return [...value].some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint < 0x20 || codePoint === 0x7f;
+  });
+}
+
+export const OAUTH_CLIENT_ID_MAX_BYTES = 2048;
+export const OAUTH_CLIENT_NAME_MAX_BYTES = 256;
+export const OAUTH_REDIRECT_URI_MAX_BYTES = 2048;
+export const OAUTH_REDIRECT_URI_MAX_COUNT = 10;
+export const OAUTH_CIMD_CACHE_MAX_AGE_SECONDS = 15 * 60;
+
+export type OAuthGrantType = 'authorization_code' | 'refresh_token';
+
+export interface ValidatedOAuthClientMetadata {
+  clientId: string;
+  clientName: string;
+  redirectUris: string[];
+  grantTypes: OAuthGrantType[];
+  responseTypes: ['code'];
+  tokenEndpointAuthMethod: 'none';
+  scope: typeof OAUTH_READ_SCOPE;
+}
+
+function hasByteLengthAtMost(value: string, maxBytes: number): boolean {
+  return Buffer.byteLength(value, 'utf8') <= maxBytes;
+}
+
+function rejectInvalidMetadata(): never {
+  throw new InvalidOAuthClientMetadataError();
+}
+
+function rejectInvalidConfiguration(): never {
+  throw new InvalidOAuthConfigurationError();
+}
+
+function parseUrl(value: string): URL {
+  try {
+    return new URL(value);
+  } catch {
+    return rejectInvalidMetadata();
+  }
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/gu, '');
+  return normalized === 'localhost' || normalized === '127.0.0.1' || normalized === '::1';
+}
+
+function validateUrlShape(url: URL): void {
+  if (
+    url.username ||
+    url.password ||
+    url.hash ||
+    url.hostname.length === 0 ||
+    hasControlCharacter(url.href)
+  ) {
+    rejectInvalidMetadata();
+  }
+}
+
+/** Validates an OAuth redirect URI without making network assumptions. */
+export function validateOAuthRedirectUri(value: string): URL {
+  if (
+    !hasByteLengthAtMost(value, OAUTH_REDIRECT_URI_MAX_BYTES) ||
+    value.length === 0 ||
+    value.trim() !== value ||
+    hasControlCharacter(value)
+  ) {
+    return rejectInvalidMetadata();
+  }
+
+  const url = parseUrl(value);
+  validateUrlShape(url);
+
+  if (url.protocol === 'https:') return url;
+  if (url.protocol !== 'http:' || !isLoopbackHostname(url.hostname)) {
+    return rejectInvalidMetadata();
+  }
+  return url;
+}
+
+export function isOAuthLoopbackRedirectUri(value: string): boolean {
+  try {
+    const url = validateOAuthRedirectUri(value);
+    return url.protocol === 'http:' && isLoopbackHostname(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Redirect URI comparison is byte-for-byte for public HTTPS clients. Only a
+ * loopback HTTP client's port may vary, as required by native-app OAuth.
+ */
+export function oauthRedirectUriMatches(registered: string, requested: string): boolean {
+  try {
+    const registeredUrl = validateOAuthRedirectUri(registered);
+    const requestedUrl = validateOAuthRedirectUri(requested);
+    if (registered === requested) return true;
+    if (
+      registeredUrl.protocol !== 'http:' ||
+      requestedUrl.protocol !== 'http:' ||
+      !isLoopbackHostname(registeredUrl.hostname) ||
+      !isLoopbackHostname(requestedUrl.hostname)
+    ) {
+      return false;
+    }
+
+    return withoutLoopbackPort(registered) === withoutLoopbackPort(requested);
+  } catch {
+    return false;
+  }
+}
+
+function withoutLoopbackPort(value: string): string {
+  const authorityStart = value.indexOf('//') + 2;
+  const suffixOffset = value.slice(authorityStart).search(URI_SUFFIX_PATTERN);
+  const authorityEnd = suffixOffset === -1 ? value.length : authorityStart + suffixOffset;
+  const authority = value.slice(authorityStart, authorityEnd);
+
+  let authorityWithoutPort = authority;
+  if (authority.startsWith('[')) {
+    const closingBracket = authority.indexOf(']');
+    const port = closingBracket === -1 ? '' : authority.slice(closingBracket + 1);
+    if (closingBracket !== -1 && BRACKETED_PORT_PATTERN.test(port)) {
+      authorityWithoutPort = authority.slice(0, closingBracket + 1);
+    }
+  } else {
+    const colon = authority.lastIndexOf(':');
+    if (colon !== -1 && PORT_PATTERN.test(authority.slice(colon + 1))) {
+      authorityWithoutPort = authority.slice(0, colon);
+    }
+  }
+
+  return `${value.slice(0, authorityStart)}${authorityWithoutPort}${value.slice(authorityEnd)}`;
+}
+
+export function assertOAuthRedirectUriRegistered(
+  redirectUris: readonly string[],
+  requested: string,
+): void {
+  validateOAuthRedirectUri(requested);
+  if (!redirectUris.some((registered) => oauthRedirectUriMatches(registered, requested))) {
+    throw new OAuthRedirectUriNotRegisteredError();
+  }
+}
+
+/** Client ID Metadata Documents must be HTTPS URLs with a non-root path. */
+export function validateOAuthClientId(value: string): URL {
+  if (
+    !hasByteLengthAtMost(value, OAUTH_CLIENT_ID_MAX_BYTES) ||
+    value.trim() !== value ||
+    hasControlCharacter(value)
+  ) {
+    return rejectInvalidMetadata();
+  }
+
+  const url = parseUrl(value);
+  validateUrlShape(url);
+  if (url.protocol !== 'https:' || url.pathname === '/' || url.pathname.length === 0) {
+    return rejectInvalidMetadata();
+  }
+  return url;
+}
+
+/** Validates the public origin injected into the dormant route factory. */
+export function validateOAuthPublicOrigin(value: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return rejectInvalidConfiguration();
+  }
+
+  if (
+    (url.protocol !== 'https:' &&
+      !(url.protocol === 'http:' && isLoopbackHostname(url.hostname))) ||
+    value.trim() !== value ||
+    hasControlCharacter(value) ||
+    url.username ||
+    url.password ||
+    url.pathname !== '/' ||
+    url.search ||
+    url.hash ||
+    url.hostname.length === 0
+  ) {
+    return rejectInvalidConfiguration();
+  }
+  return url.origin;
+}
+
+function validateByteBoundedString(value: string, maxBytes: number): void {
+  if (!hasByteLengthAtMost(value, maxBytes) || value.length === 0 || hasControlCharacter(value)) {
+    rejectInvalidMetadata();
+  }
+}
+
+function validateGrantTypes(value: readonly OAuthGrantType[] | undefined): OAuthGrantType[] {
+  const grantTypes = [...(value ?? ['authorization_code'])];
+  if (
+    grantTypes.length === 0 ||
+    grantTypes.length > 2 ||
+    new Set(grantTypes).size !== grantTypes.length ||
+    !grantTypes.includes('authorization_code') ||
+    grantTypes.some(
+      (grantType) => grantType !== 'authorization_code' && grantType !== 'refresh_token',
+    )
+  ) {
+    rejectInvalidMetadata();
+  }
+  return grantTypes;
+}
+
+function validateResponseTypes(value: readonly 'code'[] | undefined): ['code'] {
+  const responseTypes = [...(value ?? ['code'])];
+  if (responseTypes.length !== 1 || responseTypes[0] !== 'code') rejectInvalidMetadata();
+  return ['code'];
+}
+
+function validateScope(value: string | undefined): typeof OAUTH_READ_SCOPE {
+  if (value !== undefined && value !== OAUTH_READ_SCOPE) rejectInvalidMetadata();
+  return OAUTH_READ_SCOPE;
+}
+
+function validateRedirectUris(redirectUris: readonly string[]): string[] {
+  if (
+    redirectUris.length === 0 ||
+    redirectUris.length > OAUTH_REDIRECT_URI_MAX_COUNT ||
+    new Set(redirectUris).size !== redirectUris.length
+  ) {
+    rejectInvalidMetadata();
+  }
+  for (const redirectUri of redirectUris) validateOAuthRedirectUri(redirectUri);
+  return [...redirectUris];
+}
+
+function validateTokenEndpointAuthMethod(value: string | undefined): 'none' {
+  if (value !== undefined && value !== 'none') rejectInvalidMetadata();
+  return 'none';
+}
+
+export function validateOAuthDynamicClientRegistration(
+  input: OAuthDynamicClientRegistrationRequestDto,
+): Omit<ValidatedOAuthClientMetadata, 'clientId'> {
+  const parsed = oauthDynamicClientRegistrationRequestSchema.safeParse(input);
+  if (!parsed.success) rejectInvalidMetadata();
+
+  const value = parsed.data;
+  validateByteBoundedString(value.client_name, OAUTH_CLIENT_NAME_MAX_BYTES);
+  const grantTypes = validateGrantTypes(value.grant_types);
+  // Registered rows do not persist grant types yet. Keep the registration
+  // response and later resolution consistent until refresh-token support lands.
+  if (grantTypes.length !== 1 || grantTypes[0] !== 'authorization_code') {
+    rejectInvalidMetadata();
+  }
+  return {
+    clientName: value.client_name,
+    redirectUris: validateRedirectUris(value.redirect_uris),
+    grantTypes,
+    responseTypes: validateResponseTypes(value.response_types),
+    tokenEndpointAuthMethod: validateTokenEndpointAuthMethod(value.token_endpoint_auth_method),
+    scope: validateScope(value.scope),
+  };
+}
+
+export function validateOAuthClientMetadataDocument(
+  input: OAuthClientMetadataDocumentDto,
+  fetchedUrl: string,
+): ValidatedOAuthClientMetadata {
+  const parsed = oauthClientMetadataDocumentSchema.safeParse(input);
+  if (!parsed.success || parsed.data.client_id !== fetchedUrl) rejectInvalidMetadata();
+
+  validateOAuthClientId(fetchedUrl);
+  const value = parsed.data;
+  validateByteBoundedString(value.client_name, OAUTH_CLIENT_NAME_MAX_BYTES);
+  return {
+    clientId: fetchedUrl,
+    clientName: value.client_name,
+    redirectUris: validateRedirectUris(value.redirect_uris),
+    grantTypes: validateGrantTypes(value.grant_types),
+    responseTypes: validateResponseTypes(value.response_types),
+    tokenEndpointAuthMethod: validateTokenEndpointAuthMethod(value.token_endpoint_auth_method),
+    scope: validateScope(value.scope),
+  };
+}
+
+export function metadataForAgentClient(client: AgentClient): ValidatedOAuthClientMetadata {
+  validateByteBoundedString(client.clientId, OAUTH_CLIENT_ID_MAX_BYTES);
+  validateByteBoundedString(client.name, OAUTH_CLIENT_NAME_MAX_BYTES);
+  validateRedirectUris(client.redirectUris);
+  return {
+    clientId: client.clientId,
+    clientName: client.name,
+    redirectUris: [...client.redirectUris],
+    grantTypes: ['authorization_code'],
+    responseTypes: ['code'],
+    tokenEndpointAuthMethod: 'none',
+    scope: OAUTH_READ_SCOPE,
+  };
+}
+
+export function assertOAuthClientMetadataMatchesRequest(params: {
+  metadata: ValidatedOAuthClientMetadata;
+  redirectUri?: string | undefined;
+  tokenEndpointAuthMethod?: string | undefined;
+}): void {
+  if (params.redirectUri !== undefined) {
+    assertOAuthRedirectUriRegistered(params.metadata.redirectUris, params.redirectUri);
+  }
+  validateTokenEndpointAuthMethod(params.tokenEndpointAuthMethod);
+}

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

@@ -139,6 +139,58 @@ async function revokeActiveSessions(tx: Tx, userId: string): Promise<number> {
   return new Set(revoked.map(({sessionId}) => sessionId)).size;
 }
 
+async function suspendUser(tx: Tx, user: Awaited<ReturnType<typeof readTargetUserForUpdate>>) {
+  if (user.status !== 'active') return;
+  const activeOwners = await tx
+    .select({id: adminGrants.id})
+    .from(adminGrants)
+    .innerJoin(users, eq(adminGrants.userId, users.id))
+    .where(
+      and(
+        eq(adminGrants.role, 'admin-owner'),
+        isNull(adminGrants.revokedAt),
+        eq(users.status, 'active'),
+      ),
+    )
+    .limit(2);
+  const targetIsActiveOwner = await tx
+    .select({id: adminGrants.id})
+    .from(adminGrants)
+    .where(
+      and(
+        eq(adminGrants.userId, user.id),
+        eq(adminGrants.role, 'admin-owner'),
+        isNull(adminGrants.revokedAt),
+      ),
+    )
+    .limit(1);
+  if (targetIsActiveOwner.length > 0 && activeOwners.length <= 1) throw new LastAdminOwnerError();
+  await tx
+    .update(users)
+    .set({status: 'suspended', updatedAt: sql`now()`})
+    .where(eq(users.id, user.id));
+}
+
+async function applyModerationOperation(
+  tx: Tx,
+  user: Awaited<ReturnType<typeof readTargetUserForUpdate>>,
+  operation: 'suspend' | 'reactivate' | 'revoke-sessions',
+): Promise<number> {
+  if (operation === 'suspend') {
+    await suspendUser(tx, user);
+    return await revokeActiveSessions(tx, user.id);
+  }
+  if (operation === 'reactivate' && user.status === 'suspended') {
+    await tx
+      .update(users)
+      .set({status: 'active', updatedAt: sql`now()`})
+      .where(eq(users.id, user.id));
+    return 0;
+  }
+  if (operation === 'revoke-sessions') return await revokeActiveSessions(tx, user.id);
+  return 0;
+}
+
 async function executeUserModerationCommand(
   params: UserModerationCommandParams & {
     operation: 'suspend' | 'reactivate' | 'revoke-sessions';
@@ -157,51 +209,7 @@ async function executeUserModerationCommand(
     await lockUserSessionMutations(tx, params.userId);
     const user = await readTargetUserForUpdate(tx, params.userId);
     await requireActiveAdminOperator(tx, params.actorId);
-    let sessionsRevoked = 0;
-
-    if (params.operation === 'suspend') {
-      if (user.status === 'active') {
-        const activeOwners = await tx
-          .select({id: adminGrants.id})
-          .from(adminGrants)
-          .innerJoin(users, eq(adminGrants.userId, users.id))
-          .where(
-            and(
-              eq(adminGrants.role, 'admin-owner'),
-              isNull(adminGrants.revokedAt),
-              eq(users.status, 'active'),
-            ),
-          )
-          .limit(2);
-        const targetIsActiveOwner = await tx
-          .select({id: adminGrants.id})
-          .from(adminGrants)
-          .where(
-            and(
-              eq(adminGrants.userId, user.id),
-              eq(adminGrants.role, 'admin-owner'),
-              isNull(adminGrants.revokedAt),
-            ),
-          )
-          .limit(1);
-        if (targetIsActiveOwner.length > 0 && activeOwners.length <= 1) {
-          throw new LastAdminOwnerError();
-        }
-
-        await tx
-          .update(users)
-          .set({status: 'suspended', updatedAt: sql`now()`})
-          .where(eq(users.id, user.id));
-      }
-      sessionsRevoked = await revokeActiveSessions(tx, user.id);
-    } else if (params.operation === 'reactivate' && user.status === 'suspended') {
-      await tx
-        .update(users)
-        .set({status: 'active', updatedAt: sql`now()`})
-        .where(eq(users.id, user.id));
-    } else if (params.operation === 'revoke-sessions') {
-      sessionsRevoked = await revokeActiveSessions(tx, user.id);
-    }
+    const sessionsRevoked = await applyModerationOperation(tx, user, params.operation);
 
     const summary = await findUserSummary(tx, user.id);
     const result: StoredAdminUserModerationResult = {

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);
+  });
+});