@shipfox/api-auth-dto 18.0.0 → 19.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth-dto",
   "license": "MIT",
-  "version": "18.0.0",
+  "version": "19.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/schemas/admin.ts

@@ -13,6 +13,22 @@ export function isAdminRole(value: unknown): value is AdminRole {
 const timestampSchema = z.string().datetime();
 const identifierEmailSchema = z.string().email();
 const CONTROL_OR_FORMAT_CHARACTER_RE = /[\p{Cc}\p{Cf}]/u;
+const DIRECTORY_CURSOR_MAX_LENGTH = 512;
+const DIRECTORY_SEARCH_MAX_LENGTH = 128;
+const DIRECTORY_SEARCH_MAX_UTF16_LENGTH = DIRECTORY_SEARCH_MAX_LENGTH * 2;
+const DIRECTORY_PAGE_SIZE_MAX = 100;
+const DIRECTORY_LIMIT_PATTERN = /^\d+$/u;
+
+function hasAtMostCodePoints(value: string, maxLength: number): boolean {
+  let length = 0;
+  for (const _codePoint of value) {
+    length += 1;
+    if (length > maxLength) return false;
+  }
+
+  return true;
+}
+
 const reasonSchema = z
   .string()
   .min(1)
@@ -87,6 +103,82 @@ export const administratorUserSummarySchema = administratorUserIdentitySchema.ex
 
 export type AdministratorUserSummaryDto = z.infer<typeof administratorUserSummarySchema>;
 
+const directoryCursorSchema = z
+  .string()
+  .min(1)
+  .max(DIRECTORY_CURSOR_MAX_LENGTH)
+  .refine((value) => !CONTROL_OR_FORMAT_CHARACTER_RE.test(value), {
+    message: 'must not contain control or format characters',
+  });
+
+const directorySearchSchema = z
+  .string()
+  .max(DIRECTORY_SEARCH_MAX_UTF16_LENGTH)
+  .optional()
+  .transform((value) => {
+    if (
+      typeof value === 'string' &&
+      !CONTROL_OR_FORMAT_CHARACTER_RE.test(value) &&
+      value.trim().length === 0
+    ) {
+      return undefined;
+    }
+
+    return value;
+  })
+  .pipe(
+    z
+      .string()
+      .refine((value) => !CONTROL_OR_FORMAT_CHARACTER_RE.test(value), {
+        message: 'must not contain control or format characters',
+      })
+      .transform((value) => value.trim())
+      .pipe(
+        z
+          .string()
+          .min(1)
+          .refine((value) => hasAtMostCodePoints(value, DIRECTORY_SEARCH_MAX_LENGTH), {
+            message: `String must contain at most ${DIRECTORY_SEARCH_MAX_LENGTH} character(s)`,
+          }),
+      )
+      .optional(),
+  );
+
+const checkedBooleanSchema = z.preprocess((value) => {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  return value;
+}, z.boolean());
+
+const checkedDirectoryLimitSchema = z.preprocess((value) => {
+  if (typeof value === 'number' && Number.isInteger(value)) return value;
+  if (typeof value === 'string' && DIRECTORY_LIMIT_PATTERN.test(value)) return Number(value);
+  return value;
+}, z.number().int().min(1).max(DIRECTORY_PAGE_SIZE_MAX));
+
+export const administratorUserDirectoryQuerySchema = z
+  .object({
+    search: directorySearchSchema,
+    status: userStatusSchema.optional(),
+    impersonation_eligible: checkedBooleanSchema.optional(),
+    cursor: directoryCursorSchema.optional(),
+    limit: checkedDirectoryLimitSchema.default(50),
+  })
+  .strict();
+
+export type AdministratorUserDirectoryQueryDto = z.infer<
+  typeof administratorUserDirectoryQuerySchema
+>;
+
+export const administratorUserDirectoryResponseSchema = z.object({
+  users: z.array(administratorUserSummarySchema).max(DIRECTORY_PAGE_SIZE_MAX),
+  next_cursor: directoryCursorSchema.nullable(),
+});
+
+export type AdministratorUserDirectoryResponseDto = z.infer<
+  typeof administratorUserDirectoryResponseSchema
+>;
+
 const correlationIdSchema = z.string().min(1).max(255);
 
 export const suspendAdministratorUserBodySchema = z.object({

package/src/schemas/administrator-user-directory.test.ts

@@ -0,0 +1,148 @@
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {
+  administratorUserDirectoryQuerySchema,
+  administratorUserDirectoryResponseSchema,
+} from './admin.js';
+
+const user = {
+  id: '11111111-1111-4111-8111-111111111111',
+  email: 'alex@example.com',
+  name: 'Alex Shipfox',
+  status: 'active' as const,
+  email_verified_at: '2026-08-31T12:00:00.000Z',
+  created_at: '2026-08-01T12:00:00.000Z',
+  admin_role: null,
+};
+
+const parseQuery = (query: unknown) => administratorUserDirectoryQuerySchema.safeParse(query);
+
+const parseResponse = (users: unknown[]) =>
+  administratorUserDirectoryResponseSchema.safeParse({users, next_cursor: null});
+
+describe('administrator user directory query schema', () => {
+  it('defaults the page size and accepts every optional field', () => {
+    const query = administratorUserDirectoryQuerySchema.parse({
+      search: ' alex ',
+      status: 'suspended',
+      impersonation_eligible: 'true',
+      cursor: 'eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0wMSJ9',
+    });
+
+    expect(query).toEqual({
+      search: 'alex',
+      status: 'suspended',
+      impersonation_eligible: true,
+      cursor: 'eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0wMSJ9',
+      limit: 50,
+    });
+  });
+
+  it('accepts valid UUIDs as exact search values', () => {
+    const uuid = '22222222-2222-4222-8222-222222222222';
+
+    expect(administratorUserDirectoryQuerySchema.parse({search: uuid}).search).toBe(uuid);
+    expect(administratorUserDirectoryQuerySchema.parse({search: ` ${uuid} `}).search).toBe(uuid);
+  });
+
+  it('accepts text searches from one through 128 visible code points', () => {
+    expect(parseQuery({search: 'a'}).success).toBe(true);
+    expect(parseQuery({search: 'a'.repeat(128)}).success).toBe(true);
+    expect(parseQuery({search: 'a'.repeat(129)}).success).toBe(false);
+    expect(parseQuery({search: '😀'.repeat(128)}).success).toBe(true);
+  });
+
+  it('treats an empty search as omitted', () => {
+    expect(parseQuery({search: ''}).success).toBe(true);
+  });
+
+  it('rejects control and format characters in searches', () => {
+    for (const search of ['alex\nshipfox', 'alex\u0000shipfox', 'alex\u200Bshipfox', '\n', '\t']) {
+      expect(parseQuery({search})).toMatchObject({success: false});
+    }
+  });
+
+  it('keeps wildcard characters literal and trims only outer whitespace', () => {
+    const query = administratorUserDirectoryQuerySchema.parse({
+      search: '  100%_\\ alex   shipfox  ',
+    });
+
+    expect(query.search).toBe('100%_\\ alex   shipfox');
+  });
+
+  it('treats a blank search as omitted', () => {
+    expect(administratorUserDirectoryQuerySchema.parse({search: '   '})).toEqual({limit: 50});
+  });
+
+  it('accepts each known status and rejects unknown statuses', () => {
+    for (const status of ['active', 'suspended', 'deleted']) {
+      expect(parseQuery({status}).success).toBe(true);
+    }
+
+    expect(parseQuery({status: 'pending'}).success).toBe(false);
+  });
+
+  it('coerces only checked boolean query values', () => {
+    expect(
+      administratorUserDirectoryQuerySchema.parse({impersonation_eligible: 'true'}),
+    ).toMatchObject({impersonation_eligible: true});
+    expect(
+      administratorUserDirectoryQuerySchema.parse({impersonation_eligible: 'false'}),
+    ).toMatchObject({impersonation_eligible: false});
+    expect(
+      administratorUserDirectoryQuerySchema.parse({impersonation_eligible: true}),
+    ).toMatchObject({impersonation_eligible: true});
+
+    for (const value of ['1', '0', 'yes', 'TRUE', '']) {
+      expect(parseQuery({impersonation_eligible: value}).success).toBe(false);
+    }
+  });
+
+  it('bounds opaque cursors and rejects control or format characters', () => {
+    expect(parseQuery({cursor: 'a'}).success).toBe(true);
+    expect(parseQuery({cursor: 'not a cursor'}).success).toBe(true);
+    expect(parseQuery({cursor: 'a'.repeat(512)}).success).toBe(true);
+    expect(parseQuery({cursor: 'a'.repeat(513)}).success).toBe(false);
+
+    for (const cursor of ['cursor\nvalue', 'cursor\u0000value', 'cursor\u200Bvalue']) {
+      expect(parseQuery({cursor}).success).toBe(false);
+    }
+  });
+
+  it('coerces page sizes and enforces both bounds', () => {
+    expect(administratorUserDirectoryQuerySchema.parse({limit: '1'}).limit).toBe(1);
+    expect(administratorUserDirectoryQuerySchema.parse({limit: '100'}).limit).toBe(100);
+    expect(parseQuery({limit: '0'}).success).toBe(false);
+    expect(parseQuery({limit: '101'}).success).toBe(false);
+    expect(parseQuery({limit: '1.5'}).success).toBe(false);
+    expect(parseQuery({limit: true}).success).toBe(false);
+    expect(parseQuery({limit: 'abc'}).success).toBe(false);
+    expect(parseQuery({limit: '1e2'}).success).toBe(false);
+  });
+
+  it('rejects unknown query fields', () => {
+    expect(parseQuery({unexpected: 'value'}).success).toBe(false);
+  });
+});
+
+describe('administrator user directory response schema', () => {
+  it('accepts an empty response with no next page', () => {
+    expect(parseResponse([])).toMatchObject({success: true});
+  });
+
+  it('accepts a complete user summary and a nullable next cursor', () => {
+    const result = administratorUserDirectoryResponseSchema.parse({
+      users: [{...user, admin_role: 'admin-owner'}],
+      next_cursor: 'eyJjdXJzb3IiOiJuZXh0In0',
+    });
+
+    expect(result).toEqual({
+      users: [{...user, admin_role: 'admin-owner'}],
+      next_cursor: 'eyJjdXJzb3IiOiJuZXh0In0',
+    });
+  });
+
+  it('accepts 100 users and rejects a 101st user', () => {
+    expect(parseResponse(Array.from({length: 100}, () => user)).success).toBe(true);
+    expect(parseResponse(Array.from({length: 101}, () => user)).success).toBe(false);
+  });
+});

package/src/schemas/index.ts

@@ -12,6 +12,8 @@ export {
   type AdminBootstrapStateDto,
   type AdminGrantDto,
   type AdministratorGrantSummaryDto,
+  type AdministratorUserDirectoryQueryDto,
+  type AdministratorUserDirectoryResponseDto,
   type AdministratorUserIdentityDto,
   type AdministratorUserLookupQueryDto,
   type AdministratorUserMutationResponseDto,
@@ -20,6 +22,8 @@ export {
   adminBootstrapStateSchema,
   adminGrantDtoSchema,
   administratorGrantSummarySchema,
+  administratorUserDirectoryQuerySchema,
+  administratorUserDirectoryResponseSchema,
   administratorUserIdentitySchema,
   administratorUserLookupQuerySchema,
   administratorUserMutationResponseSchema,