@seamless-auth/types 0.4.0 → 0.4.1

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

package/src/schemas/role/matching.ts

@@ -0,0 +1,76 @@
+/**
+ * Role matching logic, deliberately free of any Zod import. Consumers on the
+ * authorization hot path can reach this through the `./role/matching` subpath
+ * export without pulling Zod into their dependency tree.
+ */
+
+/**
+ * Roles are colon-scoped (`billing:invoices:read`). Underscores, slashes, and
+ * whitespace are excluded so a role name is always safe to embed in a JWT claim,
+ * a URL path segment, and a config file without escaping.
+ */
+export const ROLE_NAME_PATTERN = /^(?!.*[_/\\\s])(?=.{1,80}$)[A-Za-z0-9-]+(?::[A-Za-z0-9-]+)*$/;
+
+function normalizeRole(value: string) {
+  return value.trim();
+}
+
+function samePrefix(left: string[], right: string[]) {
+  return left.length === right.length && left.every((part, index) => part === right[index]);
+}
+
+/**
+ * Whether a granted role satisfies a required role. A `:*` suffix grants every
+ * role under that prefix, an unscoped role grants every role beneath it, and a
+ * `:write` role implies the matching `:read` role.
+ */
+export function roleGrantsAccess(grantedRole: string, requiredRole: string): boolean {
+  const granted = normalizeRole(grantedRole);
+  const required = normalizeRole(requiredRole);
+
+  if (!granted || !required) {
+    return false;
+  }
+
+  if (granted === required) {
+    return true;
+  }
+
+  if (granted.endsWith(':*')) {
+    const prefix = granted.slice(0, -2);
+    return required === prefix || required.startsWith(`${prefix}:`);
+  }
+
+  if (!required.includes(':')) {
+    return false;
+  }
+
+  if (!granted.includes(':')) {
+    return required.startsWith(`${granted}:`);
+  }
+
+  const grantedParts = granted.split(':');
+  const requiredParts = required.split(':');
+  const grantedAction = grantedParts[grantedParts.length - 1];
+  const requiredAction = requiredParts[requiredParts.length - 1];
+
+  return (
+    grantedAction === 'write' &&
+    requiredAction === 'read' &&
+    samePrefix(grantedParts.slice(0, -1), requiredParts.slice(0, -1))
+  );
+}
+
+/** Whether any granted role satisfies at least one of the required roles. */
+export function hasScopedRole(grantedRoles: unknown, requiredRoles: string | string[]): boolean {
+  if (!Array.isArray(grantedRoles)) {
+    return false;
+  }
+
+  const required = Array.isArray(requiredRoles) ? requiredRoles : [requiredRoles];
+  const granted = grantedRoles.filter((role): role is string => typeof role === 'string');
+
+  return required.some((requiredRole) =>
+    granted.some((grantedRole) => roleGrantsAccess(grantedRole, requiredRole)),
+  );
+}

package/src/schemas/role/schema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+import { ROLE_NAME_PATTERN } from './matching.js';
+
+export * from './matching.js';
+
+export const RoleNameSchema = z.string().trim().regex(ROLE_NAME_PATTERN);
+
+export type RoleName = z.infer<typeof RoleNameSchema>;
+
+/** @deprecated Use {@link RoleNameSchema}. */
+export const RoleSchema = RoleNameSchema;
+
+/** @deprecated Use {@link RoleName}. */
+export type Role = z.infer<typeof RoleSchema>;

package/src/schemas/session/schema.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+export const SessionSchema = z.object({
+  id: z.string(),
+  deviceName: z.string().nullable().optional(),
+  ipAddress: z.string().nullable().optional(),
+  userAgent: z.string().nullable().optional(),
+  lastUsedAt: z.string(),
+  expiresAt: z.string(),
+  current: z.boolean(),
+});
+
+export type Session = z.infer<typeof SessionSchema>;
+
+export const SessionIdParamsSchema = z.object({
+  id: z.string(),
+});
+
+export type SessionIdParams = z.infer<typeof SessionIdParamsSchema>;
+
+export const SessionListResponseSchema = z.object({
+  sessions: z.array(SessionSchema),
+  total: z.number(),
+});
+
+export type SessionListResponse = z.infer<typeof SessionListResponseSchema>;