@seamless-auth/types 0.4.0 → 0.5.0

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>;

package/src/schemas/common/schema.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+export const PaginationQuerySchema = z.object({
+  limit: z.coerce.number().min(1).max(100).optional().default(50),
+  offset: z.coerce.number().min(0).optional().default(0),
+});
+
+export type PaginationQuery = z.infer<typeof PaginationQuerySchema>;
+
+/** Body for endpoints that only acknowledge the request. */
+export const MessageResponseSchema = z.object({
+  message: z.string(),
+});
+
+export type MessageResponse = z.infer<typeof MessageResponseSchema>;
+
+export const ErrorResponseSchema = z.object({
+  message: z.string().optional(),
+  error: z.string(),
+});
+
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+
+export const InvalidPayloadResponseSchema = z.object({
+  error: z.string(),
+  details: z.unknown().optional(),
+});
+
+export type InvalidPayloadResponse = z.infer<typeof InvalidPayloadResponseSchema>;
+
+export const MetadataSchema = z.record(z.string(), z.unknown()).nullable().optional();
+
+export type Metadata = z.infer<typeof MetadataSchema>;

package/src/schemas/credential/schema.ts

@@ -0,0 +1,103 @@
+import z from 'zod';
+import { IsoDate } from '../../shared.js';
+
+// Mirrors WebAuthn's AuthenticatorTransportFuture. Authenticators report
+// transports the browser passes through verbatim, so anything narrower rejects
+// credentials the platform considers valid.
+export const TransportSchema = z.enum([
+  'ble',
+  'cable',
+  'hybrid',
+  'internal',
+  'nfc',
+  'smart-card',
+  'usb',
+]);
+
+export type Transport = z.infer<typeof TransportSchema>;
+
+export const DeviceTypeSchema = z.enum(['singleDevice', 'multiDevice']);
+
+export type DeviceType = z.infer<typeof DeviceTypeSchema>;
+
+export const CredentialSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+
+  publicKey: z.string(),
+  counter: z.number(),
+
+  transports: z.array(TransportSchema).optional(),
+
+  deviceType: DeviceTypeSchema.optional(),
+
+  backedUp: z.boolean(),
+
+  friendlyName: z.string().nullable().optional(),
+  lastUsedAt: IsoDate.nullable().optional(),
+
+  platform: z.string().nullable().optional(),
+  browser: z.string().nullable().optional(),
+  deviceInfo: z.string().nullable().optional(),
+
+  createdAt: IsoDate,
+  updatedAt: IsoDate.optional(),
+});
+
+export type Credential = z.infer<typeof CredentialSchema>;
+
+export const UpdateCredentialRequestSchema = z.object({
+  id: z.string(),
+  friendlyName: z.string().min(1).max(128).optional(),
+  deviceInfo: z.string().max(256).optional(),
+});
+
+export type UpdateCredentialRequest = z.infer<typeof UpdateCredentialRequestSchema>;
+
+export const DeleteCredentialRequestSchema = z.object({
+  id: z.string(),
+});
+
+export type DeleteCredentialRequest = z.infer<typeof DeleteCredentialRequestSchema>;
+
+export const CredentialApiSchema = CredentialSchema.pick({
+  id: true,
+  transports: true,
+  deviceType: true,
+  backedUp: true,
+  counter: true,
+  friendlyName: true,
+  lastUsedAt: true,
+  platform: true,
+  browser: true,
+  deviceInfo: true,
+  createdAt: true,
+});
+
+export type CredentialApi = z.infer<typeof CredentialApiSchema>;
+
+/**
+ * A credential as the API returns it. `backedup` is the historical lowercase
+ * spelling kept alongside `backedUp` so older SDK builds keep working; new
+ * consumers should read `backedUp`.
+ */
+export const CredentialResponseSchema = CredentialApiSchema.extend({
+  backedup: z.boolean(),
+  backedUp: z.boolean(),
+  prfCapable: z.boolean().optional(),
+});
+
+export type CredentialResponse = z.infer<typeof CredentialResponseSchema>;
+
+export const CredentialUpdateResponseSchema = z.object({
+  message: z.string(),
+  credential: CredentialResponseSchema,
+});
+
+export type CredentialUpdateResponse = z.infer<typeof CredentialUpdateResponseSchema>;
+
+export const CredentialCountResponseSchema = z.object({
+  count: z.number(),
+});
+
+export type CredentialCountResponse = z.infer<typeof CredentialCountResponseSchema>;

package/src/schemas/me/schema.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { IsoDate } from '../../shared.js';
+import { CredentialResponseSchema } from '../credential/schema.js';
+import { OrganizationSchema } from '../organization/schema.js';
+import { RoleNameSchema } from '../role/schema.js';
+
+/**
+ * The caller's own user record. `lastLogin` is null until the first login, and
+ * `activeOrganizationId` is null when the access token carries no org context.
+ */
+export const MeUserSchema = z.object({
+  id: z.string(),
+  email: z.email(),
+  phone: z.string().nullable(),
+  roles: z.array(RoleNameSchema),
+  lastLogin: IsoDate.nullable().optional(),
+  activeOrganizationId: z.string().nullable().optional(),
+});
+
+export type MeUser = z.infer<typeof MeUserSchema>;
+
+/** @deprecated Use {@link MeUser}. */
+export type SeamlessUser = MeUser;
+
+export const MeResponseSchema = z.object({
+  user: MeUserSchema,
+  credentials: z.array(CredentialResponseSchema),
+  organizations: z.array(OrganizationSchema).optional(),
+  activeOrganization: OrganizationSchema.nullable().optional(),
+});
+
+export type MeResponse = z.infer<typeof MeResponseSchema>;

package/src/schemas/messaging/schema.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+
+export const MessagingChannelSchema = z.enum(['email', 'sms']);
+
+export type MessagingChannel = z.infer<typeof MessagingChannelSchema>;
+
+export const DeliveryResultSchema = z.object({
+  accepted: z.boolean(),
+  provider: z.string(),
+  channel: MessagingChannelSchema,
+  messageId: z.string().optional(),
+  raw: z.unknown().optional(),
+});
+
+export type DeliveryResult = z.infer<typeof DeliveryResultSchema>;
+
+export const EmailMessageSchema = z.object({
+  to: z.string(),
+  from: z.string().optional(),
+  subject: z.string(),
+  text: z.string(),
+  html: z.string().optional(),
+});
+
+export type EmailMessage = z.infer<typeof EmailMessageSchema>;
+
+export const SmsMessageSchema = z.object({
+  to: z.string(),
+  from: z.string().optional(),
+  body: z.string(),
+});
+
+export type SmsMessage = z.infer<typeof SmsMessageSchema>;
+
+export const SendOtpEmailInputSchema = z.object({
+  to: z.string(),
+  token: z.string(),
+  from: z.string().optional(),
+  subject: z.string().optional(),
+});
+
+export type SendOtpEmailInput = z.infer<typeof SendOtpEmailInputSchema>;
+
+export const SendOtpSmsInputSchema = z.object({
+  to: z.string(),
+  token: z.union([z.string(), z.number()]),
+  from: z.string().optional(),
+});
+
+export type SendOtpSmsInput = z.infer<typeof SendOtpSmsInputSchema>;
+
+export const SendMagicLinkEmailInputSchema = z.object({
+  to: z.string(),
+  magicLinkUrl: z.string(),
+  token: z.string().optional(),
+  from: z.string().optional(),
+  subject: z.string().optional(),
+});
+
+export type SendMagicLinkEmailInput = z.infer<typeof SendMagicLinkEmailInputSchema>;
+
+/**
+ * What the auth API tells a self-hosted server to deliver. The API never sends
+ * the message itself when the adopter owns delivery, so this is the contract
+ * between the two.
+ */
+export const AuthDeliverySchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('otp_email'),
+    to: z.string(),
+    token: z.string(),
+  }),
+  z.object({
+    kind: z.literal('otp_sms'),
+    to: z.string(),
+    token: z.union([z.string(), z.number()]),
+  }),
+  z.object({
+    kind: z.literal('magic_link_email'),
+    to: z.string(),
+    token: z.string().optional(),
+    magicLinkUrl: z.string(),
+  }),
+]);
+
+export type AuthDeliveryInstruction = z.infer<typeof AuthDeliverySchema>;

package/src/schemas/metrics/schema.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+import { AuthEventSchema } from '../authEvent/schema.js';
+
+const MAX_METRICS_WINDOW_MS = 1000 * 60 * 60 * 24 * 366; // ~1 year
+
+export const MetricsIntervalSchema = z.enum(['hour', 'day']);
+
+export type MetricsInterval = z.infer<typeof MetricsIntervalSchema>;
+
+export const MetricsQuerySchema = z
+  .object({
+    userId: z.string().optional(),
+    from: z.string().optional(),
+    to: z.string().optional(),
+    interval: MetricsIntervalSchema.optional().default('hour'),
+  })
+  .superRefine((data, ctx) => {
+    const fromDate = data.from ? new Date(data.from) : undefined;
+    const toDate = data.to ? new Date(data.to) : undefined;
+
+    const fromValid = fromDate !== undefined && !Number.isNaN(fromDate.getTime());
+    const toValid = toDate !== undefined && !Number.isNaN(toDate.getTime());
+
+    if (data.from !== undefined && !fromValid) {
+      ctx.addIssue({ code: 'custom', path: ['from'], message: 'Invalid from date' });
+    }
+
+    if (data.to !== undefined && !toValid) {
+      ctx.addIssue({ code: 'custom', path: ['to'], message: 'Invalid to date' });
+    }
+
+    if (!fromValid || !toValid || !fromDate || !toDate) {
+      return;
+    }
+
+    if (fromDate.getTime() > toDate.getTime()) {
+      ctx.addIssue({ code: 'custom', path: ['to'], message: 'from must be on or before to' });
+      return;
+    }
+
+    // Unbounded windows let a single request scan the whole event table.
+    if (toDate.getTime() - fromDate.getTime() > MAX_METRICS_WINDOW_MS) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['to'],
+        message: 'time range exceeds the maximum window',
+      });
+    }
+  });
+
+export type MetricsQuery = z.infer<typeof MetricsQuerySchema>;
+
+export const AuthEventSummaryItemSchema = z.object({
+  type: z.string(),
+  count: z.number(),
+});
+
+export type AuthEventSummaryItem = z.infer<typeof AuthEventSummaryItemSchema>;
+
+export const AuthEventSummaryResponseSchema = z.object({
+  summary: z.array(AuthEventSummaryItemSchema),
+});
+
+export type AuthEventSummaryResponse = z.infer<typeof AuthEventSummaryResponseSchema>;
+
+export const AuthEventTimeseriesPointSchema = z.object({
+  bucket: z.string(),
+  success: z.number(),
+  failed: z.number(),
+});
+
+export type AuthEventTimeseriesPoint = z.infer<typeof AuthEventTimeseriesPointSchema>;
+
+export const AuthEventTimeseriesResponseSchema = z.object({
+  timeseries: z.array(AuthEventTimeseriesPointSchema),
+});
+
+export type AuthEventTimeseriesResponse = z.infer<typeof AuthEventTimeseriesResponseSchema>;
+
+export const LoginStatsResponseSchema = z.object({
+  success: z.number(),
+  failed: z.number(),
+  successRate: z.number(),
+});
+
+export type LoginStatsResponse = z.infer<typeof LoginStatsResponseSchema>;
+
+/**
+ * Anomaly rows come straight out of the event store, where a partially written
+ * event is still worth surfacing, so every field is optional here.
+ */
+export const PartialAuthEventSchema = AuthEventSchema.partial();
+
+export type PartialAuthEvent = z.infer<typeof PartialAuthEventSchema>;
+
+export const SecurityAnomaliesResponseSchema = z.object({
+  suspiciousEvents: z.array(PartialAuthEventSchema),
+  total: z.number().int().nonnegative(),
+});
+
+export type SecurityAnomaliesResponse = z.infer<typeof SecurityAnomaliesResponseSchema>;
+
+export const DashboardMetricsResponseSchema = z.object({
+  totalUsers: z.number(),
+  activeSessions: z.number(),
+  newUsers24h: z.number(),
+  loginSuccess24h: z.number(),
+  loginFailed24h: z.number(),
+  successRate24h: z.number(),
+  otpUsage24h: z.number(),
+  passkeyUsage24h: z.number(),
+  databaseSize: z.number(),
+});
+
+export type DashboardMetricsResponse = z.infer<typeof DashboardMetricsResponseSchema>;

package/src/schemas/oauth/schema.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { RefreshSuccessResponseSchema } from '../auth/auth.schema.js';
+import { OAuthProviderIdSchema } from '../systemConfig/schema.js';
+
+export const OAuthProviderParamSchema = z.object({
+  providerId: OAuthProviderIdSchema,
+});
+
+export type OAuthProviderParam = z.infer<typeof OAuthProviderParamSchema>;
+
+/** A provider as an unauthenticated client may see it: no client or secret material. */
+export const PublicOAuthProviderSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  scopes: z.array(z.string()),
+});
+
+export type PublicOAuthProvider = z.infer<typeof PublicOAuthProviderSchema>;
+
+export const OAuthProvidersResponseSchema = z.object({
+  providers: z.array(PublicOAuthProviderSchema),
+});
+
+export type OAuthProvidersResponse = z.infer<typeof OAuthProvidersResponseSchema>;
+
+export const StartOAuthLoginRequestSchema = z.object({
+  redirectUri: z.url().optional(),
+  returnTo: z.url().optional(),
+});
+
+export type StartOAuthLoginRequest = z.infer<typeof StartOAuthLoginRequestSchema>;
+
+export const StartOAuthLoginResponseSchema = z.object({
+  provider: PublicOAuthProviderSchema,
+  state: z.string(),
+  authorizationUrl: z.url(),
+});
+
+export type StartOAuthLoginResponse = z.infer<typeof StartOAuthLoginResponseSchema>;
+
+export const FinishOAuthLoginRequestSchema = z.object({
+  code: z.string().trim().min(1),
+  state: z.string().trim().min(1),
+});
+
+export type FinishOAuthLoginRequest = z.infer<typeof FinishOAuthLoginRequestSchema>;
+
+export const OAuthLoginSuccessResponseSchema = RefreshSuccessResponseSchema.omit({
+  sessionId: true,
+});
+
+export type OAuthLoginSuccessResponse = z.infer<typeof OAuthLoginSuccessResponseSchema>;
+
+export const OAUTH_ERROR_CODES = [
+  'oauth_missing_email',
+  'oauth_email_not_verified',
+  'oauth_missing_subject',
+] as const;
+
+export const OAuthErrorCodeSchema = z.enum(OAUTH_ERROR_CODES);
+
+export type OAuthErrorCode = z.infer<typeof OAuthErrorCodeSchema>;
+
+export const OAuthLoginErrorResponseSchema = z.object({
+  message: z.string().optional(),
+  error: z.string(),
+  code: OAuthErrorCodeSchema.optional(),
+});
+
+export type OAuthLoginErrorResponse = z.infer<typeof OAuthLoginErrorResponseSchema>;

package/src/schemas/organization/schema.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+import { IsoDate } from '../../shared.js';
+import { MetadataSchema } from '../common/schema.js';
+
+export const OrganizationIdParamSchema = z.object({
+  organizationId: z.uuid(),
+});
+
+export type OrganizationIdParam = z.infer<typeof OrganizationIdParamSchema>;
+
+export const OrganizationMemberParamSchema = OrganizationIdParamSchema.extend({
+  userId: z.uuid(),
+});
+
+export type OrganizationMemberParam = z.infer<typeof OrganizationMemberParamSchema>;
+
+export const CreateOrganizationRequestSchema = z.object({
+  name: z.string().trim().min(1).max(120),
+  slug: z.string().trim().min(1).max(100).optional(),
+  metadata: MetadataSchema,
+});
+
+export type CreateOrganizationRequest = z.infer<typeof CreateOrganizationRequestSchema>;
+
+export const UpdateOrganizationRequestSchema = z.object({
+  name: z.string().trim().min(1).max(120).optional(),
+  slug: z.string().trim().min(1).max(100).optional(),
+  metadata: MetadataSchema,
+});
+
+export type UpdateOrganizationRequest = z.infer<typeof UpdateOrganizationRequestSchema>;
+
+const MembershipRoleSchema = z.string().trim().min(1).max(80);
+const MembershipScopeSchema = z.string().trim().min(1).max(120);
+
+export const AddOrganizationMemberRequestSchema = z
+  .object({
+    userId: z.uuid().optional(),
+    email: z.email().optional(),
+    roles: z.array(MembershipRoleSchema).optional(),
+    scopes: z.array(MembershipScopeSchema).optional(),
+  })
+  .refine((value) => Boolean(value.userId || value.email), {
+    message: 'userId or email is required',
+  });
+
+export type AddOrganizationMemberRequest = z.infer<typeof AddOrganizationMemberRequestSchema>;
+
+export const UpdateOrganizationMemberRequestSchema = z.object({
+  roles: z.array(MembershipRoleSchema).optional(),
+  scopes: z.array(MembershipScopeSchema).optional(),
+});
+
+export type UpdateOrganizationMemberRequest = z.infer<typeof UpdateOrganizationMemberRequestSchema>;
+
+const OrganizationMembershipUserSchema = z.object({
+  id: z.string(),
+  email: z.email(),
+  phone: z.string().nullable(),
+  roles: z.array(z.string()),
+});
+
+export const OrganizationMembershipSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  userId: z.string(),
+  roles: z.array(z.string()),
+  scopes: z.array(z.string()),
+  createdAt: IsoDate,
+  updatedAt: IsoDate,
+  user: OrganizationMembershipUserSchema.optional(),
+});
+
+export type OrganizationMembership = z.infer<typeof OrganizationMembershipSchema>;
+
+export const OrganizationSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  createdByUserId: z.string().nullable(),
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+  createdAt: IsoDate,
+  updatedAt: IsoDate,
+  membership: OrganizationMembershipSchema.optional(),
+  memberCount: z.number().int().nonnegative().optional(),
+});
+
+export type Organization = z.infer<typeof OrganizationSchema>;
+
+export const OrganizationEnvelopeResponseSchema = z.object({
+  organization: OrganizationSchema,
+});
+
+export type OrganizationEnvelopeResponse = z.infer<typeof OrganizationEnvelopeResponseSchema>;
+
+export const OrganizationListResponseSchema = z.object({
+  organizations: z.array(OrganizationSchema),
+  activeOrganizationId: z.string().nullable(),
+});
+
+export type OrganizationListResponse = z.infer<typeof OrganizationListResponseSchema>;
+
+export const AdminOrganizationListResponseSchema = z.object({
+  organizations: z.array(OrganizationSchema),
+  total: z.number().int().nonnegative(),
+});
+
+export type AdminOrganizationListResponse = z.infer<typeof AdminOrganizationListResponseSchema>;
+
+export const OrganizationMembersResponseSchema = z.object({
+  members: z.array(OrganizationMembershipSchema),
+  total: z.number().int().nonnegative(),
+});
+
+export type OrganizationMembersResponse = z.infer<typeof OrganizationMembersResponseSchema>;
+
+export const OrganizationMembershipEnvelopeResponseSchema = z.object({
+  membership: OrganizationMembershipSchema,
+});
+
+export type OrganizationMembershipEnvelopeResponse = z.infer<
+  typeof OrganizationMembershipEnvelopeResponseSchema
+>;
+
+export const OrganizationSwitchResponseSchema = z.object({
+  message: z.string(),
+  token: z.string(),
+  sub: z.string(),
+  sessionId: z.string(),
+  organizationId: z.string(),
+  organization: OrganizationSchema,
+  ttl: z.number(),
+});
+
+export type OrganizationSwitchResponse = z.infer<typeof OrganizationSwitchResponseSchema>;