@seamless-auth/types 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @seamless-auth/types
 
+## 0.4.1
+
+### Patch Changes
+
+- 9ae3092: No contract changes. Schemas, types, and exports are untouched.
+
+  Packaging: the non-test sources under `src` now ship in the tarball. The published `dist` has
+  always included declaration maps and source maps, but the sources they pointed at were not in the
+  package, so the maps were dangling. Go to Definition now lands on the actual schema instead of a
+  `.d.ts`.
+
+  Documentation: the README now carries npm, CI, Node, and license badges, a requirements section
+  that spells out the module resolution the subpath exports need, a conventions section covering the
+  schema and type alias pairing, and sections on versioning, supply chain, and security.
+  `SECURITY.md` states which versions are supported and what is in scope for this repository.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -1,24 +1,35 @@
 # @seamless-auth/types
 
+[![npm](https://img.shields.io/npm/v/@seamless-auth/types?logo=npm&color=cb3837)](https://www.npmjs.com/package/@seamless-auth/types)
+[![CI](https://github.com/fells-code/seamless-auth-types/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fells-code/seamless-auth-types/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/node/v/@seamless-auth/types?logo=node.js&logoColor=white)](.nvmrc)
+[![License: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-blue.svg)](LICENSE)
+
 Shared TypeScript types and Zod schemas for the SeamlessAuth ecosystem.
 
-This package provides a single source of truth for domain models like Users, Credentials, Sessions, and Auth Events, ensuring consistency across:
+This package is the single source of truth for the SeamlessAuth domain models (Users,
+Credentials, Sessions, Auth, Auth Events, Organizations) and for the request and response
+contracts built on top of them. Every layer of the stack validates against the same schemas:
 
 - API servers
-- SDKs
+- SDKs and server adapters
 - Frontend applications
 - CLI tools
 
----
+Because everything downstream imports these contracts, a change here is treated as
+breaking by default. See [Versioning and stability](#versioning-and-stability).
 
-## Features
+## Requirements
 
-- Zod-first schemas with runtime validation and type inference
-- Strict typing across all models
-- Framework-agnostic
-- Minimal dependencies (Zod only)
+|                      |                           |
+| -------------------- | ------------------------- |
+| Node                 | 24 (`>=24 <25`)           |
+| TypeScript           | 5.x                       |
+| Runtime dependencies | `zod@^4` and nothing else |
 
----
+The package ships as ESM only. The root import works under any module resolution, but the
+[subpath exports](#subpath-exports) are resolved from `package.json` `exports`, so consumers
+that use them need `moduleResolution` set to `node16`, `nodenext`, or `bundler`.
 
 ## Installation
 
@@ -26,24 +37,47 @@ This package provides a single source of truth for domain models like Users, Cre
 npm install @seamless-auth/types
 ```
 
----
+## Quick start
+
+```ts
+import { UserSchema, type User } from '@seamless-auth/types';
+
+// Validate untrusted input and get a fully typed value back.
+const user: User = UserSchema.parse(await response.json());
+```
 
 ## Usage
 
-### Import schemas
+### Validate data
+
+Every model is a Zod schema, so you get runtime validation and the static type from one
+declaration:
 
 ```ts
-import { UserSchema } from '@seamless-auth/types';
+import { LoginRequestSchema } from '@seamless-auth/types';
+
+const parsed = LoginRequestSchema.safeParse(req.body);
+if (!parsed.success) {
+  return res.status(400).json({ error: parsed.error.issues });
+}
 ```
 
-### Validate data
+### Infer types
 
 ```ts
-const user = UserSchema.parse(data);
+import type { User } from '@seamless-auth/types';
+
+function handleUser(user: User) {
+  console.log(user.email);
+}
 ```
 
-User role schemas accept plain roles such as `admin` and colon-separated scoped roles such as
-`admin:read` and `admin:write`. Whitespace, underscores, slashes, and backslashes are rejected.
+### Roles
+
+Role schemas accept plain roles such as `admin` and colon-separated scoped roles such as
+`admin:read` and `admin:write`. Whitespace, underscores, slashes, and backslashes are
+rejected, so a role name is always safe to embed in a JWT claim, a URL path segment, or a
+config file without escaping.
 
 ### Match roles without Zod
 
@@ -62,22 +96,10 @@ if (!hasScopedRole(user.roles, 'billing:invoices:read')) {
 `@seamless-auth/types/role` adds `RoleNameSchema` on top of the same matchers, and the package
 root still exports all of them, so existing imports keep working.
 
-### Infer types
-
-```ts
-import type { User } from '@seamless-auth/types';
-
-function handleUser(user: User) {
-  console.log(user.email);
-}
-```
-
----
-
 ## Modules
 
-Every module is re-exported from the package root, so import from
-`@seamless-auth/types` unless one of the subpath exports below fits better.
+Every module is re-exported from the package root, so import from `@seamless-auth/types`
+unless one of the subpath exports below fits better.
 
 | Module         | Covers                                                              |
 | -------------- | ------------------------------------------------------------------- |
@@ -106,69 +128,105 @@ Every module is re-exported from the package root, so import from
 | `@seamless-auth/types/role`          | Role name schema plus the matchers     |
 | `@seamless-auth/types/role/matching` | The matchers alone, with no Zod import |
 
----
-
-## Zod as the Source of Truth
+## Conventions
 
-All models are defined using Zod:
+**Zod is the source of truth.** Models are declared as schemas and the TypeScript type is
+inferred from the schema. No type in this package is hand-written alongside a schema that
+already describes it:
 
 ```ts
 export const UserSchema = z.object({
-  id: z.string().uuid(),
-  email: z.string().email(),
+  id: z.uuid(),
+  email: z.email(),
 });
-```
-
-Types are inferred:
 
-```ts
 export type User = z.infer<typeof UserSchema>;
 ```
 
----
+**Every exported schema has a matching type alias.** `XSchema` is always paired with `X`, so
+you never have to write `z.infer<typeof XSchema>` at a call site. This is enforced by a test,
+not by convention alone.
+
+**Framework-agnostic.** No server, browser, or Node-only APIs, and no runtime dependency
+beyond Zod, so the same contracts load in an API process, a browser bundle, and a CLI.
+
+**Strict typing throughout.** No `any` and no non-null assertions. Wire-facing schemas are
+`.strict()` where unknown keys should be rejected rather than silently dropped.
 
-## Versioning
+## Versioning and stability
 
 This package follows semantic versioning:
 
-- PATCH for fixes and non-breaking improvements
-- MINOR for additive changes such as new fields or models
-- MAJOR for breaking changes such as field removals or type changes
+- **PATCH** for fixes with no effect on the contract, including docs and internal tidying
+- **MINOR** for additive changes such as a new module, export, or optional field
+- **MAJOR** for breaking changes such as a removed or renamed export, a field whose type
+  changes, or a schema that now rejects input it used to accept
+
+A widening change (a wider enum, a field that becomes nullable) is not breaking at runtime,
+but it does change the inferred TypeScript type, so it is called out in the release notes.
+
+Releases are managed with [Changesets](https://github.com/changesets/changesets). See
+[RELEASES.md](RELEASES.md) for the release flow and [CHANGELOG.md](CHANGELOG.md) for the
+history.
 
----
+## Supply chain
+
+- Published from CI only, from a tagged release on `main`, never from a developer machine.
+- Every release carries [npm provenance](https://docs.npmjs.com/generating-provenance-statements),
+  so the published tarball is cryptographically linked to the commit and workflow that built it.
+- One runtime dependency (`zod`). Dependency updates are automated and reviewed like any other
+  change.
+- The published tarball is limited to `dist`, the non-test sources under `src`, `README.md`,
+  `CHANGELOG.md`, `LICENSE`, and `package.json`. `npm run check-npm-build` prints the contents in
+  CI on every push and release.
+- Sources ship alongside the declaration maps and source maps, so Go to Definition in your editor
+  lands on the actual schema rather than a `.d.ts`.
+
+## Security
+
+Do not open a public issue for a vulnerability. Report it privately to
+**security@seamlessauth.com**. See [SECURITY.md](SECURITY.md) for what to include, our
+acknowledgement window, and the coordinated disclosure process.
 
 ## Development
 
 ```bash
-# build
-npm run build
+nvm use          # Node 24, pinned by .nvmrc
+npm ci
 
-# watch mode
-npm run dev
-
-# type check
+npm run build      # compile to dist/
+npm run dev        # tsc --watch
 npm run typecheck
+npm run lint
+npm run format:check
+npm test
 ```
 
 ## Contributing
 
-Contributions are welcome.
+Contributions are welcome. Start with the organization
+[contributing guide](https://github.com/fells-code/.github/blob/main/CONTRIBUTING.md) and the
+[repository standards](https://github.com/fells-code/.github/blob/main/REPO-STANDARDS.md).
+[AGENTS.md](AGENTS.md) documents the repository layout and the working standards in more detail.
 
-Please ensure:
+For a change in this repository specifically:
 
-- strict TypeScript compliance
-- schemas remain Zod-based
-- no framework-specific dependencies are introduced
+1. Add or change the schema under `src/schemas/<model>/`.
+2. Export it from `src/index.ts` if it is part of the public API.
+3. Run `npm run typecheck`, `npm run lint`, `npm run format:check`, `npm test`, and `npm run build`.
+4. Run `npm run changeset` and write the notes for the repositories that consume these
+   contracts, not for the implementation. A change to `src/` without a changeset ships nothing.
 
----
+Keep schemas Zod-based, keep the package framework-agnostic, and treat any change to an
+existing schema as breaking until you can argue otherwise.
 
 ## License
 
-AGPL-3.0 © Fells Code, LLC
-
----
+[AGPL-3.0-only](LICENSE) © Fells Code, LLC
 
 ## Links
 
-- GitHub: [https://github.com/fells-code/seamless-auth-types](https://github.com/fells-code/seamless-auth-types)
-- SeamlessAuth: [https://seamlessauth.com](https://seamlessauth.com)
+- [npm package](https://www.npmjs.com/package/@seamless-auth/types)
+- [GitHub repository](https://github.com/fells-code/seamless-auth-types)
+- [SeamlessAuth](https://seamlessauth.com)
+- [Fells Code](https://github.com/fells-code)

package/dist/schemas/webauthn/schema.d.ts

@@ -9,8 +9,8 @@ export declare const WebAuthnPrfRequestSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type WebAuthnPrfRequest = z.infer<typeof WebAuthnPrfRequestSchema>;
 export declare const WebAuthnRegisterStartQuerySchema: z.ZodObject<{
-    requestPrf: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodBoolean>>;
-    requirePrf: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodBoolean>>;
+    requestPrf: z.ZodPreprocess<z.ZodOptional<z.ZodBoolean>>;
+    requirePrf: z.ZodPreprocess<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 export type WebAuthnRegisterStartQuery = z.infer<typeof WebAuthnRegisterStartQuerySchema>;
 export declare const WebAuthnAssertionStartSchema: z.ZodDefault<z.ZodObject<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamless-auth/types",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Shared TypeScript types and Zod schemas for SeamlessAuth.",
   "author": "Fells Code, LLC",
   "license": "AGPL-3.0-only",
@@ -24,6 +24,8 @@
   "sideEffects": false,
   "files": [
     "dist",
+    "src",
+    "!src/**/*.test.ts",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -58,7 +60,6 @@
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
-    "coverage": "vitest run --coverage",
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release:stable": "npm run build && changeset publish",
@@ -78,15 +79,14 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.1",
-    "@commitlint/cli": "^20.5.0",
-    "@commitlint/config-conventional": "^20.5.0",
+    "@commitlint/cli": "^21.2.1",
+    "@commitlint/config-conventional": "^21.2.0",
     "@typescript-eslint/eslint-plugin": "^8.57.2",
     "@typescript-eslint/parser": "^8.57.2",
-    "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "husky": "^9.1.7",
-    "lint-staged": "^16.4.0",
+    "lint-staged": "^17.2.0",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.1"

package/src/index.ts

@@ -0,0 +1,19 @@
+export * from './shared.js';
+
+export * from './schemas/common/schema.js';
+export * from './schemas/role/schema.js';
+export * from './schemas/user/schema.js';
+export * from './schemas/credential/schema.js';
+export * from './schemas/session/schema.js';
+export * from './schemas/authEvent/schema.js';
+export * from './schemas/messaging/schema.js';
+export * from './schemas/systemConfig/schema.js';
+export * from './schemas/auth/auth.schema.js';
+export * from './schemas/oauth/schema.js';
+export * from './schemas/webauthn/schema.js';
+export * from './schemas/totp/schema.js';
+export * from './schemas/stepUp/schema.js';
+export * from './schemas/organization/schema.js';
+export * from './schemas/me/schema.js';
+export * from './schemas/metrics/schema.js';
+export * from './schemas/admin/schema.js';

package/src/schemas/admin/schema.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { AuthEventSchema } from '../authEvent/schema.js';
+import { CredentialResponseSchema } from '../credential/schema.js';
+import { SessionSchema } from '../session/schema.js';
+import { ApiUserSchema } from '../user/schema.js';
+
+export const UserIdParamSchema = z.object({
+  userId: z.string(),
+});
+
+export type UserIdParam = z.infer<typeof UserIdParamSchema>;
+
+/**
+ * What an operator clears when a user replaces a lost device. Each step is
+ * opt-out rather than opt-in so a hurried recovery does not leave the old
+ * device's credentials in place.
+ */
+export const DeviceReplacementRecoverySchema = z
+  .object({
+    revokeSessions: z.boolean().default(true),
+    removePasskeys: z.boolean().default(true),
+    disableTotp: z.boolean().default(true),
+  })
+  .strict();
+
+export type DeviceReplacementRecoveryRequest = z.infer<typeof DeviceReplacementRecoverySchema>;
+
+export const DeviceReplacementRecoveryResponseSchema = z.object({
+  userId: z.string(),
+  revokedSessions: z.number().int().nonnegative(),
+  removedCredentials: z.number().int().nonnegative(),
+  disabledTotpCredentials: z.number().int().nonnegative(),
+});
+
+export type DeviceReplacementRecoveryResponse = z.infer<
+  typeof DeviceReplacementRecoveryResponseSchema
+>;
+
+export const AdminUserDetailResponseSchema = z.object({
+  user: ApiUserSchema,
+  sessions: z.array(SessionSchema),
+  credentials: z.array(CredentialResponseSchema),
+  events: z.array(AuthEventSchema),
+});
+
+export type AdminUserDetailResponse = z.infer<typeof AdminUserDetailResponseSchema>;
+
+export const AdminUserAnomaliesResponseSchema = z.object({
+  suspiciousEvents: z.array(AuthEventSchema),
+  relatedIps: z.array(z.string()),
+  relatedAgents: z.array(z.string()),
+});
+
+export type AdminUserAnomaliesResponse = z.infer<typeof AdminUserAnomaliesResponseSchema>;

package/src/schemas/auth/auth.schema.ts

@@ -0,0 +1,139 @@
+import z from 'zod';
+import { AuthDeliverySchema } from '../messaging/schema.js';
+import { LoginMethodSchema } from '../systemConfig/schema.js';
+
+export const IdentifierTypeSchema = z.enum(['email', 'phone']);
+
+export type IdentifierType = z.infer<typeof IdentifierTypeSchema>;
+
+export const LoginRequestSchema = z.object({
+  identifier: z.string(),
+  passkeyAvailable: z.boolean().optional(),
+});
+
+export type LoginRequest = z.infer<typeof LoginRequestSchema>;
+
+export const LoginSuccessResponseSchema = z.object({
+  message: z.string(),
+  token: z.string().optional(),
+  sub: z.string().optional(),
+  identifierType: IdentifierTypeSchema.optional(),
+  loginMethods: z.array(LoginMethodSchema).optional(),
+  ttl: z.number().optional(),
+});
+
+export type LoginSuccessResponse = z.infer<typeof LoginSuccessResponseSchema>;
+
+export const RefreshTokenRequestSchema = z.object({});
+
+export type RefreshTokenRequest = z.infer<typeof RefreshTokenRequestSchema>;
+
+/** @deprecated Use {@link RefreshTokenRequestSchema}. */
+export const RefreshRequestSchema = RefreshTokenRequestSchema;
+
+/** @deprecated Use {@link RefreshTokenRequest}. */
+export type RefreshRequest = z.infer<typeof RefreshRequestSchema>;
+
+/**
+ * The token envelope every completed authentication returns, whatever the
+ * method. `sessionId` is only present where the flow names the session it
+ * created; OTP, magic link, and OAuth completions omit it.
+ */
+export const RefreshSuccessResponseSchema = z.object({
+  message: z.string(),
+  token: z.string().optional(),
+  refreshToken: z.string().optional(),
+  sub: z.string().optional(),
+  sessionId: z.string().optional(),
+  organizationId: z.string().nullable().optional(),
+  roles: z.array(z.string()).optional(),
+  email: z.string().optional(),
+  phone: z.string().nullable().optional(),
+  ttl: z.number().optional(),
+  refreshTtl: z.number().optional(),
+});
+
+export type RefreshSuccessResponse = z.infer<typeof RefreshSuccessResponseSchema>;
+
+export const LogoutScopeSchema = z.enum(['current_session', 'all_sessions']);
+
+export type LogoutScope = z.infer<typeof LogoutScopeSchema>;
+
+export const RegistrationRequestSchema = z.object({
+  email: z.email(),
+  // Registration only needs an email. A phone can be added and verified later.
+  phone: z.string().nullish(),
+});
+
+export type RegistrationRequest = z.infer<typeof RegistrationRequestSchema>;
+
+export const RegistrationSuccessSchema = z.object({
+  message: z.string(),
+  sub: z.string().optional(),
+  token: z.string().optional(),
+  ttl: z.string().optional(),
+  delivery: AuthDeliverySchema.optional(),
+});
+
+export type RegistrationSuccessResponse = z.infer<typeof RegistrationSuccessSchema>;
+
+export const RegisterPhoneRequestSchema = z.object({
+  phone: z.string(),
+});
+
+export type RegisterPhoneRequest = z.infer<typeof RegisterPhoneRequestSchema>;
+
+export const RegisterPhoneSuccessSchema = z.object({
+  message: z.string(),
+  phone: z.string(),
+  delivery: AuthDeliverySchema.optional(),
+});
+
+export type RegisterPhoneSuccess = z.infer<typeof RegisterPhoneSuccessSchema>;
+
+export const VerifyOTPRequestSchema = z.object({
+  verificationToken: z.string(),
+});
+
+export type VerifyOTPRequest = z.infer<typeof VerifyOTPRequestSchema>;
+
+export const OTPVerifyTokenSuccessSchema = RefreshSuccessResponseSchema.omit({
+  sessionId: true,
+});
+
+export type OTPVerifyTokenSuccess = z.infer<typeof OTPVerifyTokenSuccessSchema>;
+
+export const MagicLinkVerifyParamsSchema = z.object({
+  token: z.string(),
+});
+
+export type MagicLinkVerifyParams = z.infer<typeof MagicLinkVerifyParamsSchema>;
+
+export const MagicLinkPollSuccessSchema = RefreshSuccessResponseSchema.omit({
+  sessionId: true,
+  organizationId: true,
+});
+
+export type MagicLinkPollSuccess = z.infer<typeof MagicLinkPollSuccessSchema>;
+
+/** Body for endpoints that acknowledge a request and may hand back a delivery. */
+export const AuthMessageResponseSchema = z.object({
+  message: z.string(),
+  token: z.string().optional(),
+  delivery: AuthDeliverySchema.optional(),
+});
+
+export type AuthMessageResponse = z.infer<typeof AuthMessageResponseSchema>;
+
+/** The access token's claims, as a resource server reads them off a request. */
+export const SeamlessAuthUserSchema = z.object({
+  id: z.string(),
+  roles: z.array(z.string()),
+  email: z.string().optional(),
+  phone: z.string().nullable().optional(),
+  iat: z.number().optional(),
+  exp: z.number().optional(),
+  token: z.string().optional(),
+});
+
+export type SeamlessAuthUser = z.infer<typeof SeamlessAuthUserSchema>;

package/src/schemas/authEvent/schema.ts

@@ -0,0 +1,120 @@
+import z from 'zod';
+import { IsoDate } from '../../shared.js';
+
+export const AUTH_EVENT_TYPES = [
+  'admin_device_replacement_recovery',
+  'admin_session_revoked',
+  'auth_action_incremented',
+  'bearer_token_failed',
+  'bearer_token_success',
+  'bearer_token_suspicious',
+  'credentials_deleted',
+  'informational',
+  'internal_user_updated_by_owner',
+  'jwks_failed',
+  'jwks_success',
+  'jwks_suspicious',
+  'login_challenge',
+  'login_failed',
+  'login_success',
+  'login_suspicious',
+  'logout_failed',
+  'logout_success',
+  'logout_suspicious',
+  'magic_link_failed',
+  'magic_link_poll_completed_successfully',
+  'magic_link_requested',
+  'magic_link_success',
+  'mfa_otp_failed',
+  'mfa_otp_success',
+  'mfa_otp_suspicious',
+  'notification_sent',
+  'oauth_login_failed',
+  'oauth_login_started',
+  'oauth_login_success',
+  'otp_failed',
+  'otp_success',
+  'otp_suspicious',
+  'recovery_otp_failed',
+  'recovery_otp_success',
+  'recovery_otp_suspicious',
+  'refresh_token_failed',
+  'refresh_token_success',
+  'refresh_token_suspicious',
+  'registration_failed',
+  'registration_success',
+  'registration_suspicious',
+  'request_suspicious',
+  'service_token_failed',
+  'service_token_rotated',
+  'service_token_success',
+  'service_token_suspicious',
+  'step_up_challenge',
+  'step_up_failed',
+  'step_up_success',
+  'step_up_suspicious',
+  'system_config_error',
+  'system_config_read',
+  'system_config_updated',
+  'totp_disabled',
+  'totp_enrollment_started',
+  'totp_enrollment_success',
+  'totp_failed',
+  'totp_success',
+  'totp_suspicious',
+  'user_created',
+  'user_data_failed',
+  'user_data_success',
+  'user_data_suspicious',
+  'user_deleted',
+  'verify_otp_failed',
+  'verify_otp_success',
+  'verify_otp_suspicious',
+  'webauthn_login_failed',
+  'webauthn_login_success',
+  'webauthn_login_suspicious',
+  'webauthn_registration_failed',
+  'webauthn_registration_success',
+  'webauthn_registration_suspicious',
+] as const;
+
+export const AuthEventTypeEnum = z.enum(AUTH_EVENT_TYPES);
+
+export type AuthEventType = z.infer<typeof AuthEventTypeEnum>;
+
+// `type` stays a plain string: a stored event written by a newer server must
+// still parse on an older consumer. Use AuthEventTypeEnum to validate input.
+export const AuthEventSchema = z.object({
+  id: z.string(),
+  user_id: z.string().nullable().optional(),
+  type: z.string(),
+  ip_address: z.string().nullable().optional(),
+  user_agent: z.string().nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+  created_at: IsoDate,
+  updated_at: IsoDate,
+});
+
+export type AuthEvent = z.infer<typeof AuthEventSchema>;
+
+export const AuthEventQuerySchema = z.object({
+  limit: z.coerce.number().min(1).max(100).default(10),
+  offset: z.coerce.number().min(0).default(0),
+
+  userId: z.string().optional(),
+  type: z
+    .union([AuthEventTypeEnum, z.string(), z.array(z.union([AuthEventTypeEnum, z.string()]))])
+    .optional(),
+
+  from: z.string().optional(),
+  to: z.string().optional(),
+});
+
+export type AuthEventQuery = z.infer<typeof AuthEventQuerySchema>;
+
+export const AuthEventsResponseSchema = z.object({
+  events: z.array(AuthEventSchema),
+  total: z.number(),
+});
+
+export type AuthEventsResponse = z.infer<typeof AuthEventsResponseSchema>;