@seamless-auth/types 0.3.0 → 0.4.1

package/src/schemas/stepUp/schema.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+export const StepUpMethodSchema = z.enum(['webauthn', 'totp']);
+
+export type StepUpMethod = z.infer<typeof StepUpMethodSchema>;
+
+/** Every field but `fresh` is null until the user has stepped up at least once. */
+export const StepUpStatusSchema = z.object({
+  fresh: z.boolean(),
+  method: StepUpMethodSchema.nullable(),
+  verifiedAt: z.string().nullable(),
+  expiresAt: z.string().nullable(),
+  maxAgeSeconds: z.number(),
+});
+
+export type StepUpStatus = z.infer<typeof StepUpStatusSchema>;
+
+export const StepUpSuccessSchema = z.object({
+  message: z.string(),
+  fresh: z.boolean(),
+  method: StepUpMethodSchema,
+  verifiedAt: z.string(),
+  expiresAt: z.string(),
+  maxAgeSeconds: z.number(),
+});
+
+export type StepUpSuccessResponse = z.infer<typeof StepUpSuccessSchema>;

package/src/schemas/systemConfig/schema.ts

@@ -0,0 +1,196 @@
+import { z } from 'zod';
+import { RoleNameSchema } from '../role/schema.js';
+
+export const LoginMethodSchema = z.enum([
+  'passkey',
+  'magic_link',
+  'email_otp',
+  'phone_otp',
+  'oauth',
+]);
+
+export type LoginMethod = z.infer<typeof LoginMethodSchema>;
+
+export const OAuthProviderIdSchema = z.string().regex(/^[a-z0-9-]{2,40}$/);
+
+export type OAuthProviderId = z.infer<typeof OAuthProviderIdSchema>;
+
+export const OAuthProviderConfigSchema = z.object({
+  id: OAuthProviderIdSchema,
+  name: z.string().trim().min(1).max(80),
+  enabled: z.boolean().default(true),
+  clientId: z.string().trim().min(1),
+  // The secret itself never lives in config; this names the environment
+  // variable the server reads it from.
+  clientSecretEnv: z.string().trim().min(1),
+  authorizationUrl: z.url(),
+  tokenUrl: z.url(),
+  userInfoUrl: z.url(),
+  scopes: z.array(z.string().trim().min(1)).default([]),
+  redirectUri: z.url().optional(),
+  redirectUris: z.array(z.url()).default([]),
+  subjectJsonPath: z.string().trim().min(1).default('sub'),
+  emailJsonPath: z.string().trim().min(1).default('email'),
+  emailVerifiedJsonPath: z.string().trim().min(1).default('email_verified'),
+  nameJsonPath: z.string().trim().min(1).optional(),
+  allowSignup: z.boolean().default(true),
+  accountLinking: z.enum(['email', 'disabled']).default('email'),
+  requireEmailVerified: z.boolean().default(false),
+  pkce: z.boolean().optional(),
+});
+
+export type OAuthProviderConfig = z.infer<typeof OAuthProviderConfigSchema>;
+
+export const LockoutPolicySchema = z.object({
+  enabled: z.boolean().default(true),
+  maxFailures: z.number().int().positive().default(10),
+  windowSeconds: z
+    .number()
+    .int()
+    .positive()
+    .default(15 * 60),
+  lockoutSeconds: z
+    .number()
+    .int()
+    .positive()
+    .default(15 * 60),
+});
+
+export type LockoutPolicy = z.infer<typeof LockoutPolicySchema>;
+
+export const DefaultLockoutPolicy = {
+  enabled: true,
+  maxFailures: 10,
+  windowSeconds: 15 * 60,
+  lockoutSeconds: 15 * 60,
+} as const;
+
+export const SystemConfigSchema = z.object({
+  app_name: z.string().min(3),
+  default_roles: z.array(RoleNameSchema).min(1),
+  available_roles: z.array(RoleNameSchema).min(1),
+  login_methods: z.array(LoginMethodSchema).min(1),
+  passkey_login_fallback_enabled: z.boolean(),
+  oauth_providers: z.array(OAuthProviderConfigSchema).default([]),
+  lockout_policy: LockoutPolicySchema.default(DefaultLockoutPolicy),
+
+  access_token_ttl: z.string().regex(/^\d+[smhd]$/),
+  refresh_token_ttl: z.string().regex(/^\d+[smhd]$/),
+
+  rate_limit: z.number().int().positive(),
+  delay_after: z.number().int().nonnegative(),
+
+  rpid: z.string().min(1),
+  origins: z.array(z.url()).min(1),
+
+  frontend_url: z.url().optional(),
+});
+
+export type SystemConfig = z.infer<typeof SystemConfigSchema>;
+
+export const SystemConfigPatchSchema = z
+  .object({
+    app_name: SystemConfigSchema.shape.app_name.optional(),
+    default_roles: SystemConfigSchema.shape.default_roles.optional(),
+    available_roles: SystemConfigSchema.shape.available_roles.optional(),
+    login_methods: SystemConfigSchema.shape.login_methods.optional(),
+    passkey_login_fallback_enabled:
+      SystemConfigSchema.shape.passkey_login_fallback_enabled.optional(),
+    oauth_providers: z.array(OAuthProviderConfigSchema).optional(),
+    lockout_policy: LockoutPolicySchema.optional(),
+    access_token_ttl: SystemConfigSchema.shape.access_token_ttl.optional(),
+    refresh_token_ttl: SystemConfigSchema.shape.refresh_token_ttl.optional(),
+    rate_limit: SystemConfigSchema.shape.rate_limit.optional(),
+    delay_after: SystemConfigSchema.shape.delay_after.optional(),
+    rpid: SystemConfigSchema.shape.rpid.optional(),
+    origins: SystemConfigSchema.shape.origins.optional(),
+  })
+  .strict();
+
+export type SystemConfigPatch = z.infer<typeof SystemConfigPatchSchema>;
+
+/**
+ * A patch schema bound to the config currently stored, so role edits can be
+ * checked against the merged result rather than the patch alone.
+ */
+export function createPatchSystemConfigSchema(existing: SystemConfig) {
+  return SystemConfigPatchSchema.superRefine((data, ctx) => {
+    const nextAvailable = data.available_roles ?? existing.available_roles;
+    const nextDefault = data.default_roles ?? existing.default_roles;
+
+    const removedDefaults =
+      data.available_roles !== undefined &&
+      existing.default_roles.some((role) => !data.available_roles?.includes(role));
+
+    if (removedDefaults) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['available_roles'],
+        message: 'Cannot remove roles currently set as default',
+      });
+    }
+
+    if (!nextDefault.every((role) => nextAvailable.includes(role))) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['default_roles'],
+        message: 'All default roles must exist in available_roles',
+      });
+    }
+  });
+}
+
+export const OAuthProviderCreateSchema = OAuthProviderConfigSchema;
+
+export type OAuthProviderCreate = z.infer<typeof OAuthProviderCreateSchema>;
+
+export const OAuthProviderIdParamSchema = z.object({
+  id: OAuthProviderIdSchema,
+});
+
+export type OAuthProviderIdParam = z.infer<typeof OAuthProviderIdParamSchema>;
+
+// The id is immutable and taken from the path, so it is omitted here. Every other
+// field is optional so callers can patch a single attribute without resending the
+// whole provider; the merged result is re-validated against the full schema.
+export const OAuthProviderUpdateSchema = OAuthProviderConfigSchema.omit({ id: true })
+  .partial()
+  .strict();
+
+export type OAuthProviderUpdate = z.infer<typeof OAuthProviderUpdateSchema>;
+
+export const OAuthProvidersListResponseSchema = z.object({
+  providers: z.array(OAuthProviderConfigSchema),
+});
+
+export type OAuthProvidersListResponse = z.infer<typeof OAuthProvidersListResponseSchema>;
+
+export const OAuthProviderResponseSchema = z.object({
+  provider: OAuthProviderConfigSchema,
+});
+
+export type OAuthProviderResponse = z.infer<typeof OAuthProviderResponseSchema>;
+
+export const OAuthProviderDeletedResponseSchema = z.object({
+  success: z.literal(true),
+  id: z.string(),
+});
+
+export type OAuthProviderDeletedResponse = z.infer<typeof OAuthProviderDeletedResponseSchema>;
+
+export const GetSystemConfigResponseSchema = SystemConfigSchema;
+
+export type GetSystemConfigResponse = z.infer<typeof GetSystemConfigResponseSchema>;
+
+export const UpdateSystemConfigResponseSchema = z.object({
+  success: z.boolean(),
+  updatedKeys: z.array(z.string()),
+});
+
+export type UpdateSystemConfigResponse = z.infer<typeof UpdateSystemConfigResponseSchema>;
+
+export const AvailableRolesResponseSchema = z.object({
+  roles: z.array(z.string()),
+});
+
+export type AvailableRolesResponse = z.infer<typeof AvailableRolesResponseSchema>;

package/src/schemas/totp/schema.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+
+export const TotpVerifyRequestSchema = z.object({
+  code: z.string().regex(/^\d{6}$/),
+});
+
+export type TotpVerifyRequest = z.infer<typeof TotpVerifyRequestSchema>;
+
+export const TotpStatusSchema = z.object({
+  enabled: z.boolean(),
+  verifiedAt: z.string().nullable(),
+  lastUsedAt: z.string().nullable(),
+});
+
+export type TotpStatus = z.infer<typeof TotpStatusSchema>;
+
+export const TotpEnrollmentStartSchema = z.object({
+  message: z.string(),
+  secret: z.string(),
+  otpauthUrl: z.string(),
+  issuer: z.string(),
+  accountName: z.string(),
+  algorithm: z.literal('SHA1'),
+  digits: z.number(),
+  period: z.number(),
+});
+
+export type TotpEnrollmentStartResponse = z.infer<typeof TotpEnrollmentStartSchema>;
+
+export const TotpVerifySuccessSchema = z.object({
+  message: z.string(),
+});
+
+export type TotpVerifySuccess = z.infer<typeof TotpVerifySuccessSchema>;

package/src/schemas/user/schema.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { IsoDate } from '../../shared.js';
+import { RoleNameSchema } from '../role/schema.js';
+
+export const UserSchema = z.object({
+  id: z.uuid(),
+  email: z.email(),
+  phone: z.string(),
+  roles: z.array(RoleNameSchema).default([]),
+  revoked: z.boolean().default(false),
+  emailVerified: z.boolean().default(false),
+  phoneVerified: z.boolean().default(false),
+  verified: z.boolean().default(false),
+  lastLogin: IsoDate.nullable().optional(),
+  createdAt: IsoDate,
+  updatedAt: IsoDate.nullable().optional(),
+});
+
+export type User = z.infer<typeof UserSchema>;
+
+/**
+ * The user as it crosses the wire. Looser than {@link UserSchema}: the id is an
+ * opaque string rather than a UUID, phone is nullable for email-only accounts,
+ * and the verification flags are absent on endpoints that do not expose them.
+ */
+export const ApiUserSchema = z
+  .object({
+    id: z.string(),
+    email: z.email(),
+    phone: z.string().nullable(),
+    roles: z.array(RoleNameSchema).default([]),
+    revoked: z.boolean().optional(),
+    emailVerified: z.boolean().optional(),
+    phoneVerified: z.boolean().optional(),
+    verified: z.boolean().optional(),
+    lastLogin: IsoDate.nullable().optional(),
+    createdAt: IsoDate.optional(),
+    updatedAt: IsoDate.optional(),
+  })
+  .strict();
+
+export type ApiUser = z.infer<typeof ApiUserSchema>;
+
+export const CreateUserSchema = z.object({
+  email: z.email(),
+  phone: z.string().min(5).nullish(),
+  roles: z.array(RoleNameSchema).min(1),
+});
+
+export type CreateUserRequest = z.infer<typeof CreateUserSchema>;
+
+export const UpdateUserSchema = z
+  .object({
+    email: z.email().optional(),
+    phone: z.string().min(5).nullish(),
+    emailVerified: z.boolean().optional(),
+    phoneVerified: z.boolean().optional(),
+    roles: z.array(RoleNameSchema).min(1).optional(),
+  })
+  .strict();
+
+export type UpdateUserRequest = z.infer<typeof UpdateUserSchema>;
+
+export const UserResponseSchema = z.object({
+  user: ApiUserSchema,
+});
+
+export type UserResponse = z.infer<typeof UserResponseSchema>;
+
+export const UsersListResponseSchema = z.object({
+  users: z.array(ApiUserSchema),
+  total: z.number(),
+});
+
+export type UsersListResponse = z.infer<typeof UsersListResponseSchema>;

package/src/schemas/webauthn/schema.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+
+const BooleanQuerySchema = z.preprocess((value) => {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  return value;
+}, z.boolean().optional());
+
+/**
+ * PRF salts are validated for length and encoding by the server, which owns the
+ * rule. This schema only asserts the wire shape so both sides agree on it.
+ */
+export const WebAuthnPrfRequestSchema = z.object({
+  salt: z.string(),
+  secondSalt: z.string().optional(),
+});
+
+export type WebAuthnPrfRequest = z.infer<typeof WebAuthnPrfRequestSchema>;
+
+export const WebAuthnRegisterStartQuerySchema = z.object({
+  requestPrf: BooleanQuerySchema,
+  requirePrf: BooleanQuerySchema,
+});
+
+export type WebAuthnRegisterStartQuery = z.infer<typeof WebAuthnRegisterStartQuerySchema>;
+
+export const WebAuthnAssertionStartSchema = z
+  .object({
+    credentialId: z.string().optional(),
+    prf: WebAuthnPrfRequestSchema.optional(),
+  })
+  .default({});
+
+export type WebAuthnAssertionStart = z.infer<typeof WebAuthnAssertionStartSchema>;
+
+export const WebAuthnCredentialMetadataSchema = z.object({
+  friendlyName: z.string().optional(),
+  platform: z.string().optional(),
+  browser: z.string().optional(),
+  deviceInfo: z.string().optional(),
+  prfCapable: z.boolean().optional(),
+});
+
+export type WebAuthnCredentialMetadata = z.infer<typeof WebAuthnCredentialMetadataSchema>;
+
+export const WebAuthnRegisterFinishSchema = z.object({
+  attestationResponse: z.record(z.string(), z.unknown()),
+  metadata: WebAuthnCredentialMetadataSchema.optional(),
+});
+
+export type WebAuthnRegisterFinish = z.infer<typeof WebAuthnRegisterFinishSchema>;
+
+export const WebAuthnLoginFinishSchema = z.object({
+  assertionResponse: z.record(z.string(), z.unknown()),
+});
+
+export type WebAuthnLoginFinish = z.infer<typeof WebAuthnLoginFinishSchema>;
+
+/**
+ * The credential creation and request options are passed through to the browser
+ * verbatim, so they are not narrowed here.
+ */
+export const WebAuthnChallengeSchema = z.record(z.string(), z.unknown());
+
+export type WebAuthnChallenge = z.infer<typeof WebAuthnChallengeSchema>;
+
+export const WebAuthnTokenSuccessSchema = z.object({
+  message: z.string(),
+  token: z.string().optional(),
+  refreshToken: z.string().optional(),
+  refreshTokenHash: z.string().optional(),
+
+  sub: z.string().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 WebAuthnTokenSuccessResponse = z.infer<typeof WebAuthnTokenSuccessSchema>;

package/src/shared.ts

@@ -0,0 +1,3 @@
+import z from 'zod';
+
+export const IsoDate = z.coerce.date().transform((d) => d.toISOString());