@shipfox/api-auth-dto 18.0.0 → 20.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth-dto",
   "license": "MIT",
-  "version": "18.0.0",
+  "version": "20.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,
@@ -115,6 +119,19 @@ export {
   type JobLeaseTokenClaims,
   jobLeaseTokenClaimsSchema,
 } from './job-lease-token.js';
+export {
+  OAUTH_READ_SCOPE,
+  type OAuthAuthorizationServerMetadataDto,
+  type OAuthClientMetadataDocumentDto,
+  type OAuthDynamicClientRegistrationRequestDto,
+  type OAuthDynamicClientRegistrationResponseDto,
+  type OAuthProtectedResourceMetadataDto,
+  oauthAuthorizationServerMetadataSchema,
+  oauthClientMetadataDocumentSchema,
+  oauthDynamicClientRegistrationRequestSchema,
+  oauthDynamicClientRegistrationResponseSchema,
+  oauthProtectedResourceMetadataSchema,
+} from './oauth.js';
 export {
   RUNNER_SESSION_TOKEN_AUDIENCE,
   type RunnerSessionTokenClaims,

package/src/schemas/oauth.test.ts

@@ -0,0 +1,71 @@
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {
+  oauthAuthorizationServerMetadataSchema,
+  oauthClientMetadataDocumentSchema,
+  oauthDynamicClientRegistrationRequestSchema,
+  oauthProtectedResourceMetadataSchema,
+} from './oauth.js';
+
+describe('OAuth metadata schemas', () => {
+  it('accepts the MCP read-only discovery profile', () => {
+    expect(
+      oauthProtectedResourceMetadataSchema.safeParse({
+        resource: 'https://api.example.test/mcp',
+        authorization_servers: ['https://api.example.test'],
+        scopes_supported: ['read'],
+      }).success,
+    ).toBe(true);
+
+    expect(
+      oauthAuthorizationServerMetadataSchema.safeParse({
+        issuer: 'https://api.example.test',
+        authorization_endpoint: 'https://api.example.test/oauth/authorize',
+        token_endpoint: 'https://api.example.test/oauth/token',
+        registration_endpoint: 'https://api.example.test/oauth/register',
+        response_types_supported: ['code'],
+        grant_types_supported: ['authorization_code', 'refresh_token'],
+        code_challenge_methods_supported: ['S256'],
+        token_endpoint_auth_methods_supported: ['none'],
+        scopes_supported: ['read'],
+        client_id_metadata_document_supported: true,
+      }).success,
+    ).toBe(true);
+  });
+
+  it('requires the bounded public-client registration fields', () => {
+    expect(
+      oauthDynamicClientRegistrationRequestSchema.safeParse({
+        client_name: 'Desktop agent',
+        redirect_uris: ['http://127.0.0.1:43123/callback'],
+      }).success,
+    ).toBe(true);
+
+    expect(
+      oauthDynamicClientRegistrationRequestSchema.safeParse({
+        client_name: 'Desktop agent',
+        redirect_uris: [],
+      }).success,
+    ).toBe(false);
+    expect(
+      oauthDynamicClientRegistrationRequestSchema.safeParse({
+        client_name: 'Desktop agent',
+        redirect_uris: ['https://client.example/callback'],
+        token_endpoint_auth_method: 'client_secret_basic',
+      }).success,
+    ).toBe(false);
+  });
+
+  it('accepts standard optional CIMD fields without changing the identity fields', () => {
+    const result = oauthClientMetadataDocumentSchema.safeParse({
+      client_id: 'https://client.example/.well-known/oauth-client',
+      client_name: 'Desktop agent',
+      redirect_uris: ['https://client.example/callback'],
+      token_endpoint_auth_method: 'none',
+      client_uri: 'https://client.example',
+      contacts: ['security@client.example'],
+      custom_metadata: 'ignored by the profile',
+    });
+
+    expect(result.success).toBe(true);
+  });
+});

package/src/schemas/oauth.ts

@@ -0,0 +1,104 @@
+import {z} from 'zod';
+
+const oauthUrlSchema = z.string().url().max(2048);
+const oauthClientNameSchema = z.string().min(1).max(256);
+const oauthRedirectUriSchema = z.string().min(1).max(2048);
+const oauthScopeSchema = z.string().min(1).max(256);
+const oauthGrantTypeSchema = z.enum(['authorization_code', 'refresh_token']);
+const oauthResponseTypeSchema = z.literal('code');
+
+/** The only scope exposed by the MCP read-only profile. */
+export const OAUTH_READ_SCOPE = 'read' as const;
+
+/** RFC 9728 metadata advertised for the protected MCP resource. */
+export const oauthProtectedResourceMetadataSchema = z
+  .object({
+    resource: oauthUrlSchema,
+    authorization_servers: z.array(oauthUrlSchema).min(1),
+    scopes_supported: z.array(z.literal(OAUTH_READ_SCOPE)).min(1),
+  })
+  .strict();
+
+export type OAuthProtectedResourceMetadataDto = z.infer<
+  typeof oauthProtectedResourceMetadataSchema
+>;
+
+/** RFC 8414 metadata for the MCP authorization server. */
+export const oauthAuthorizationServerMetadataSchema = z
+  .object({
+    issuer: oauthUrlSchema,
+    authorization_endpoint: oauthUrlSchema,
+    token_endpoint: oauthUrlSchema,
+    registration_endpoint: oauthUrlSchema,
+    response_types_supported: z.array(oauthResponseTypeSchema).min(1),
+    grant_types_supported: z.array(oauthGrantTypeSchema).min(1),
+    code_challenge_methods_supported: z.array(z.literal('S256')).min(1),
+    token_endpoint_auth_methods_supported: z.array(z.literal('none')).min(1),
+    scopes_supported: z.array(z.literal(OAUTH_READ_SCOPE)).min(1),
+    client_id_metadata_document_supported: z.literal(true),
+  })
+  .strict();
+
+export type OAuthAuthorizationServerMetadataDto = z.infer<
+  typeof oauthAuthorizationServerMetadataSchema
+>;
+
+const oauthRegistrationProfileFields = {
+  client_name: oauthClientNameSchema,
+  redirect_uris: z.array(oauthRedirectUriSchema).min(1).max(10),
+  grant_types: z.array(oauthGrantTypeSchema).min(1).max(2).optional(),
+  response_types: z.array(oauthResponseTypeSchema).min(1).max(1).optional(),
+  token_endpoint_auth_method: z.literal('none').optional(),
+  scope: oauthScopeSchema.optional(),
+};
+
+/** RFC 7591 request shape accepted by the MCP public-client profile. */
+export const oauthDynamicClientRegistrationRequestSchema = z
+  .object(oauthRegistrationProfileFields)
+  .strict();
+
+export type OAuthDynamicClientRegistrationRequestDto = z.infer<
+  typeof oauthDynamicClientRegistrationRequestSchema
+>;
+
+/** RFC 7591 response shape returned for a newly registered public client. */
+export const oauthDynamicClientRegistrationResponseSchema = z
+  .object({
+    client_id: z.string().min(1).max(2048),
+    client_name: oauthClientNameSchema,
+    redirect_uris: z.array(oauthRedirectUriSchema).min(1).max(10),
+    grant_types: z.array(oauthGrantTypeSchema).min(1).max(2),
+    response_types: z.array(oauthResponseTypeSchema).min(1).max(1),
+    token_endpoint_auth_method: z.literal('none'),
+    scope: z.literal(OAUTH_READ_SCOPE),
+  })
+  .strict();
+
+export type OAuthDynamicClientRegistrationResponseDto = z.infer<
+  typeof oauthDynamicClientRegistrationResponseSchema
+>;
+
+/**
+ * The subset of a Client ID Metadata Document needed before authorization.
+ * Optional standard metadata is retained in the schema so a conforming
+ * document can be validated without treating unrelated fields as identity.
+ */
+export const oauthClientMetadataDocumentSchema = z
+  .object({
+    client_id: z.string().min(1).max(2048),
+    client_name: oauthClientNameSchema,
+    redirect_uris: z.array(oauthRedirectUriSchema).min(1).max(10),
+    grant_types: z.array(oauthGrantTypeSchema).min(1).max(2).optional(),
+    response_types: z.array(oauthResponseTypeSchema).min(1).max(1).optional(),
+    token_endpoint_auth_method: z.string().min(1).max(128).optional(),
+    scope: oauthScopeSchema.optional(),
+    client_uri: oauthUrlSchema.optional(),
+    logo_uri: oauthUrlSchema.optional(),
+    tos_uri: oauthUrlSchema.optional(),
+    policy_uri: oauthUrlSchema.optional(),
+    jwks_uri: oauthUrlSchema.optional(),
+    contacts: z.array(z.string().min(1).max(256)).max(10).optional(),
+  })
+  .passthrough();
+
+export type OAuthClientMetadataDocumentDto = z.infer<typeof oauthClientMetadataDocumentSchema>;