@corgelabs/corge 0.0.1 → 1.0.1

package/src/auth/recovery.ts

@@ -0,0 +1,365 @@
+import { randomBytes, randomInt } from 'node:crypto'
+import type { UserRecord } from 'firebase-admin/auth'
+import type { EntryId } from '../db'
+import type { Core } from '../index'
+import {
+  completeAccountRecoveryBody,
+  forgotPasswordBody,
+  initiateAccountRecoveryBody,
+  resetPasswordBody,
+  setRecoveryEmailBody,
+  verifyEmailBody,
+  verifyRecoveryEmailBody,
+  type AuthEmailPurpose,
+  type AuthTokenPurpose,
+  type AuthUser,
+  type CompleteAccountRecoveryInput,
+  type ForgotPasswordInput,
+  type InitiateAccountRecoveryInput,
+  type ResetPasswordInput,
+  type SetRecoveryEmailInput,
+  type TransactionalEmailPayload,
+  type VerifyEmailInput,
+  type VerifyRecoveryEmailInput
+} from './schema'
+import type { AuthSessionEngine } from './session'
+import { hashToken, normalizeDate, safeEqualHex } from './utils'
+
+export class AuthRecoveryEngine {
+  readonly #core: Core
+  readonly #session: AuthSessionEngine
+
+  constructor(coreClient: Core, session: AuthSessionEngine) {
+    this.#core = coreClient
+    this.#session = session
+  }
+
+  getLastDevEmail = (to: string, purpose: AuthEmailPurpose): TransactionalEmailPayload | undefined =>
+    this.#core.internals.emails.getLastDevEmail(to, purpose)
+
+  #issueAuthToken = async (
+    userId: EntryId,
+    purpose: AuthTokenPurpose,
+    targetEmail: string,
+    expiresInMinutes = this.#core.config.emails.otpTtlMinutes
+  ): Promise<TransactionalEmailPayload> => {
+    const normalizedTarget = targetEmail.trim().toLowerCase()
+    const code = String(randomInt(100_000, 1_000_000))
+    const token = randomBytes(32).toString('base64url')
+    const tokenHash = hashToken(code)
+    const urlTokenHash = hashToken(token)
+    const now = new Date()
+    const expiresAt = new Date(now.getTime() + expiresInMinutes * 60_000)
+    const docId = `${userId}_${purpose}`
+
+    await this.#core.db
+      .firestore()
+      .collection('auth_tokens')
+      .doc(docId)
+      .set({
+        id: docId,
+        userId,
+        purpose,
+        targetEmail: normalizedTarget,
+        tokenHash,
+        urlTokenHash,
+        attempts: 0,
+        expiresAt,
+        consumedAt: null,
+        deleted: false,
+        createdAt: now,
+        updatedAt: now
+      })
+
+    const payload: TransactionalEmailPayload = {
+      to: normalizedTarget,
+      purpose,
+      code,
+      token,
+      expiresInMinutes,
+      userId
+    }
+    await this.#core.internals.emails.dispatchAuthEmail(payload)
+    return payload
+  }
+
+  #consumeAuthToken = async (
+    userId: EntryId,
+    purpose: AuthTokenPurpose,
+    expectedTargetEmail: string,
+    codeOrToken: string
+  ): Promise<void> => {
+    const db = this.#core.db.firestore()
+    const docRef = db.collection('auth_tokens').doc(`${userId}_${purpose}`)
+    const maxAttempts = this.#core.config.emails.maxVerifyAttempts
+    const normalizedExpected = expectedTargetEmail.trim().toLowerCase()
+    const candidateHash = hashToken(codeOrToken)
+
+    type ConsumeOutcome = 'valid' | 'missing_or_consumed' | 'expired' | 'max_attempts' | 'mismatch'
+
+    const outcome = await db.runTransaction<ConsumeOutcome>(async (tx) => {
+      const snap = await tx.get(docRef)
+      if (!snap.exists) return 'missing_or_consumed'
+      const data = snap.data() as Record<string, unknown> | undefined
+      if (!data || data.deleted === true || data.consumedAt != null) return 'missing_or_consumed'
+
+      const attempts = typeof data.attempts === 'number' ? data.attempts : 0
+      if (attempts >= maxAttempts) return 'max_attempts'
+
+      const now = new Date()
+      if (normalizeDate(data.expiresAt, new Date(0)).getTime() <= now.getTime()) {
+        tx.update(docRef, { deleted: true, updatedAt: now })
+        return 'expired'
+      }
+
+      const targetEmail = String(data.targetEmail ?? '').trim().toLowerCase()
+      const tokenHash = String(data.tokenHash ?? '')
+      const urlTokenHash = typeof data.urlTokenHash === 'string' ? data.urlTokenHash : ''
+      const matches =
+        targetEmail === normalizedExpected &&
+        (safeEqualHex(candidateHash, tokenHash) ||
+          (Boolean(urlTokenHash) && safeEqualHex(candidateHash, urlTokenHash)))
+
+      if (!matches) {
+        const nextAttempts = attempts + 1
+        const exhausted = nextAttempts >= maxAttempts
+        tx.update(docRef, {
+          attempts: nextAttempts,
+          ...(exhausted ? { deleted: true, consumedAt: now } : {}),
+          updatedAt: now
+        })
+        return exhausted ? 'max_attempts' : 'mismatch'
+      }
+
+      tx.update(docRef, { consumedAt: now, deleted: true, updatedAt: now })
+      return 'valid'
+    })
+
+    if (outcome === 'valid') return
+    if (outcome === 'expired') this.#core.errors.httpError(400, 'Verification token has expired', 'TOKEN_EXPIRED')
+    if (outcome === 'max_attempts') {
+      this.#core.errors.httpError(
+        400,
+        'Maximum verification attempts exceeded; token invalidated',
+        'TOKEN_MAX_ATTEMPTS_EXCEEDED'
+      )
+    }
+    this.#core.errors.httpError(400, 'Invalid or expired verification code', 'INVALID_TOKEN')
+  }
+
+  #requireUserByEmail = async (
+    email: string,
+    errMessage: string,
+    errCode: string,
+    rejectDisabled = false
+  ): Promise<{ user: UserRecord; normalizedEmail: string }> => {
+    const normalizedEmail = email.trim().toLowerCase()
+    const user = await this.#session
+      .getAuth()
+      .getUserByEmail(normalizedEmail)
+      .catch(() => undefined)
+    if (!user || !user.email || (rejectDisabled && user.disabled)) {
+      return this.#core.errors.httpError(400, errMessage, errCode)
+    }
+    return { user, normalizedEmail }
+  }
+
+  #revokeAllUserSessions = async (uid: EntryId): Promise<void> => {
+    this.#session.evictUserTokens(uid)
+    await Promise.all([
+      this.#session.recordRevocation(uid, this.#core.env.isDev),
+      this.#session
+        .getAuth()
+        .revokeRefreshTokens(uid)
+        .catch(() => {})
+    ])
+  }
+
+  sendVerificationEmail = async (
+    userId: EntryId = this.#core.userId
+  ): Promise<{ sent: true; expiresInMinutes: number }> => {
+    if (!userId) return this.#core.errors.httpError(401, 'Unauthorized', 'UNAUTHORIZED')
+    const user = await this.#session
+      .getAuth()
+      .getUser(userId)
+      .catch(() => undefined)
+    if (!user || !user.email) {
+      return this.#core.errors.httpError(400, 'User does not have a primary email address', 'MISSING_EMAIL')
+    }
+    const expiresInMinutes = this.#core.config.emails.otpTtlMinutes
+    await this.#issueAuthToken(user.uid, 'verify_email', user.email, expiresInMinutes)
+    return { sent: true, expiresInMinutes }
+  }
+
+  #consumeAndUpsertMeta = async (
+    uid: EntryId,
+    purpose: AuthTokenPurpose,
+    targetEmail: string,
+    codeOrToken: string,
+    metaPatch: Parameters<AuthSessionEngine['upsertUserAuthMeta']>[1]
+  ): Promise<void> => {
+    await this.#consumeAuthToken(uid, purpose, targetEmail, codeOrToken)
+    await this.#session.upsertUserAuthMeta(uid, metaPatch, this.#core.env.isDev)
+  }
+
+  verifyEmail = async (raw: VerifyEmailInput): Promise<{ verified: true; userId: string }> => {
+    const { email, codeOrToken } = verifyEmailBody.parse(raw)
+    const { user, normalizedEmail } = await this.#requireUserByEmail(
+      email,
+      'Invalid email or verification token',
+      'INVALID_TOKEN'
+    )
+    await this.#consumeAndUpsertMeta(user.uid, 'verify_email', user.email!, codeOrToken, {
+      email: normalizedEmail,
+      emailVerified: true
+    })
+    await this.#session.getAuth().updateUser(user.uid, { emailVerified: true })
+    this.#session.evictUserTokens(user.uid)
+    return { verified: true, userId: user.uid }
+  }
+
+  forgotPassword = async (raw: ForgotPasswordInput): Promise<{ sent: true }> => {
+    const { email } = forgotPasswordBody.parse(raw)
+    const normalizedEmail = email.trim().toLowerCase()
+    const user = await this.#session
+      .getAuth()
+      .getUserByEmail(normalizedEmail)
+      .catch(() => undefined)
+    if (user && user.email && !user.disabled) {
+      await this.#issueAuthToken(user.uid, 'reset_password', user.email, this.#core.config.emails.otpTtlMinutes)
+    }
+    return { sent: true }
+  }
+
+  resetPassword = async (raw: ResetPasswordInput): Promise<{ reset: true }> => {
+    const { email, codeOrToken, newPassword } = resetPasswordBody.parse(raw)
+    const { user } = await this.#requireUserByEmail(email, 'Invalid email or reset token', 'INVALID_TOKEN')
+    await this.#consumeAuthToken(user.uid, 'reset_password', user.email!, codeOrToken)
+    await this.#session.getAuth().updateUser(user.uid, { password: newPassword })
+    await this.#revokeAllUserSessions(user.uid)
+    return { reset: true }
+  }
+
+  setRecoveryEmail = async (
+    raw: SetRecoveryEmailInput,
+    userId: EntryId = this.#core.userId
+  ): Promise<{ recoveryEmail: string; recoveryEmailVerified: false; sent: true }> => {
+    if (!userId) return this.#core.errors.httpError(401, 'Unauthorized', 'UNAUTHORIZED')
+    const { recoveryEmail } = setRecoveryEmailBody.parse(raw)
+    const normalizedRecovery = recoveryEmail.trim().toLowerCase()
+    const user = await this.#session
+      .getAuth()
+      .getUser(userId)
+      .catch(() => undefined)
+    if (!user) return this.#core.errors.httpError(404, 'User not found', 'NOT_FOUND')
+
+    const primaryEmail = (user.email ?? '').trim().toLowerCase()
+    if (primaryEmail && normalizedRecovery === primaryEmail) {
+      return this.#core.errors.httpError(
+        400,
+        'Recovery email must be different from primary email',
+        'INVALID_RECOVERY_EMAIL'
+      )
+    }
+
+    await this.#session.upsertUserAuthMeta(
+      user.uid,
+      {
+        ...(primaryEmail ? { email: primaryEmail } : {}),
+        recoveryEmail: normalizedRecovery,
+        recoveryEmailVerified: false
+      },
+      this.#core.env.isDev
+    )
+    await this.#issueAuthToken(
+      user.uid,
+      'verify_recovery_email',
+      normalizedRecovery,
+      this.#core.config.emails.otpTtlMinutes
+    )
+    return { recoveryEmail: normalizedRecovery, recoveryEmailVerified: false, sent: true }
+  }
+
+  verifyRecoveryEmail = async (
+    raw: VerifyRecoveryEmailInput,
+    userId: EntryId = this.#core.userId
+  ): Promise<{ recoveryEmail: string; recoveryEmailVerified: true; verified: true }> => {
+    if (!userId) return this.#core.errors.httpError(401, 'Unauthorized', 'UNAUTHORIZED')
+    const { codeOrToken } = verifyRecoveryEmailBody.parse(raw)
+    const meta = await this.#session.getUserAuthMeta(userId, this.#core.env.isDev)
+    if (!meta?.recoveryEmail) {
+      return this.#core.errors.httpError(
+        400,
+        'No recovery email configured for this account',
+        'MISSING_RECOVERY_EMAIL'
+      )
+    }
+    await this.#consumeAndUpsertMeta(userId, 'verify_recovery_email', meta.recoveryEmail, codeOrToken, {
+      recoveryEmailVerified: true
+    })
+    return { recoveryEmail: meta.recoveryEmail, recoveryEmailVerified: true, verified: true }
+  }
+
+  initiateAccountRecovery = async (raw: InitiateAccountRecoveryInput): Promise<{ initiated: true }> => {
+    const { primaryEmail, recoveryEmail } = initiateAccountRecoveryBody.parse(raw)
+    const normPrimary = primaryEmail.trim().toLowerCase()
+    const normRecovery = recoveryEmail.trim().toLowerCase()
+    const user = await this.#session
+      .getAuth()
+      .getUserByEmail(normPrimary)
+      .catch(() => undefined)
+    if (user && !user.disabled && (user.email ?? '').trim().toLowerCase() === normPrimary) {
+      const meta = await this.#session.getUserAuthMeta(user.uid, this.#core.env.isDev)
+      if (meta?.recoveryEmail === normRecovery && meta.recoveryEmailVerified === true) {
+        await this.#issueAuthToken(
+          user.uid,
+          'account_recovery',
+          normRecovery,
+          this.#core.config.emails.recoveryOtpTtlMinutes
+        )
+      }
+    }
+    return { initiated: true }
+  }
+
+  completeAccountRecovery = async (
+    raw: CompleteAccountRecoveryInput
+  ): Promise<{ user: AuthUser; sessionCookie: string }> => {
+    const { primaryEmail, recoveryEmail, codeOrToken, newPrimaryEmail, newPassword } =
+      completeAccountRecoveryBody.parse(raw)
+    const normPrimary = primaryEmail.trim().toLowerCase()
+    const normRecovery = recoveryEmail.trim().toLowerCase()
+    const normNewPrimary = newPrimaryEmail.trim().toLowerCase()
+
+    const { user } = await this.#requireUserByEmail(
+      normPrimary,
+      'Invalid account recovery request or token',
+      'INVALID_RECOVERY_REQUEST',
+      true
+    )
+    if ((user.email ?? '').trim().toLowerCase() !== normPrimary) {
+      return this.#core.errors.httpError(400, 'Invalid account recovery request or token', 'INVALID_RECOVERY_REQUEST')
+    }
+
+    const meta = await this.#session.getUserAuthMeta(user.uid, this.#core.env.isDev)
+    if (!meta || meta.recoveryEmail !== normRecovery || meta.recoveryEmailVerified !== true) {
+      return this.#core.errors.httpError(400, 'Invalid account recovery request or token', 'INVALID_RECOVERY_REQUEST')
+    }
+
+    await this.#consumeAndUpsertMeta(user.uid, 'account_recovery', normRecovery, codeOrToken, {
+      email: normNewPrimary,
+      emailVerified: true
+    })
+    await this.#session.getAuth().updateUser(user.uid, {
+      email: normNewPrimary,
+      emailVerified: true,
+      ...(newPassword ? { password: newPassword } : {})
+    })
+    await this.#revokeAllUserSessions(user.uid)
+
+    return this.#session.mintSessionForUid(user.uid, {
+      email: normNewPrimary,
+      emailVerified: true
+    })
+  }
+}

package/src/auth/routes.ts

@@ -0,0 +1,142 @@
+import { deleteCookie, getCookie } from 'hono/cookie'
+import type { Context } from 'hono'
+import type { z } from 'zod'
+import { CORE_CONFIG, type AppEnv, type DbRole } from '../config'
+import type { EntryId } from '../db'
+import { core } from '../index'
+import type { StepRunner } from '../tasks'
+import {
+  blockUserBody,
+  completeAccountRecoveryBody,
+  customTokenBody,
+  emailSignInBody,
+  emailSignUpBody,
+  eraseUserInput,
+  eraseUserOutput,
+  forgotPasswordBody,
+  initiateAccountRecoveryBody,
+  resetPasswordBody,
+  sendVerificationEmailBody,
+  sessionBody,
+  setRecoveryEmailBody,
+  signOutBody,
+  socialSignInInput,
+  verifyEmailBody,
+  verifyRecoveryEmailBody,
+  type AuthUser,
+  type EraseUserInput
+} from './schema'
+
+const respondWithSession = async (
+  c: Context<AppEnv>,
+  p: Promise<{ user: AuthUser; sessionCookie: string }>
+): Promise<AuthUser> => {
+  const { user, sessionCookie } = await p
+  core.internals.auth.setSessionCookie(c, sessionCookie)
+  return user
+}
+
+export const coreAuthRoutes = {
+  'auth.custom-token': {
+    input: customTokenBody,
+    handler: async ({
+      input,
+      userId,
+      role
+    }: {
+      input: z.infer<typeof customTokenBody>
+      userId: EntryId
+      role: DbRole
+    }) => {
+      if (input.uid && role !== 'admin' && userId !== CORE_CONFIG.auth.adminUserId) {
+        return core.errors.httpError(403, 'Admin privileges required to mint token for specific UID', 'FORBIDDEN')
+      }
+      return core.internals.auth.mintCustomToken(input.uid)
+    }
+  },
+  'auth.session.create': {
+    input: sessionBody,
+    handler: async ({ c, input }: { c: Context<AppEnv>; input: z.infer<typeof sessionBody> }) =>
+      respondWithSession(c, core.internals.auth.createSession(input.idToken)).catch(() =>
+        core.errors.httpError(401, 'Invalid ID token', 'INVALID_ID_TOKEN')
+      )
+  },
+  'auth.session.get': {
+    handler: async ({ userId }: { userId: EntryId }) => ({ userId })
+  },
+  'auth.sign-up.email': {
+    input: emailSignUpBody,
+    handler: async ({ c, input }: { c: Context<AppEnv>; input: z.infer<typeof emailSignUpBody> }) =>
+      respondWithSession(c, core.internals.auth.signUpEmail(input.email, input.password, input.name))
+  },
+  'auth.sign-in.email': {
+    input: emailSignInBody,
+    handler: async ({ c, input }: { c: Context<AppEnv>; input: z.infer<typeof emailSignInBody> }) =>
+      respondWithSession(c, core.internals.auth.signInEmail(input.email, input.password))
+  },
+  'auth.sign-in.social': {
+    input: socialSignInInput,
+    handler: async ({ c, input }: { c: Context<AppEnv>; input: z.infer<typeof socialSignInInput> }) =>
+      respondWithSession(c, core.auth.signInSocial(input))
+  },
+  'auth.email.send-verification': {
+    input: sendVerificationEmailBody,
+    handler: async ({ userId }: { userId: EntryId }) => core.auth.sendVerificationEmail(userId)
+  },
+  'auth.email.verify': {
+    input: verifyEmailBody,
+    handler: async ({ input }: { input: z.infer<typeof verifyEmailBody> }) => core.auth.verifyEmail(input)
+  },
+  'auth.password.forgot': {
+    input: forgotPasswordBody,
+    handler: async ({ input }: { input: z.infer<typeof forgotPasswordBody> }) => core.auth.forgotPassword(input)
+  },
+  'auth.password.reset': {
+    input: resetPasswordBody,
+    handler: async ({ input }: { input: z.infer<typeof resetPasswordBody> }) => core.auth.resetPassword(input)
+  },
+  'auth.recovery-email.set': {
+    input: setRecoveryEmailBody,
+    handler: async ({ userId, input }: { userId: EntryId; input: z.infer<typeof setRecoveryEmailBody> }) =>
+      core.auth.setRecoveryEmail(input, userId)
+  },
+  'auth.recovery-email.verify': {
+    input: verifyRecoveryEmailBody,
+    handler: async ({ userId, input }: { userId: EntryId; input: z.infer<typeof verifyRecoveryEmailBody> }) =>
+      core.auth.verifyRecoveryEmail(input, userId)
+  },
+  'auth.account-recovery.initiate': {
+    input: initiateAccountRecoveryBody,
+    handler: async ({ input }: { input: z.infer<typeof initiateAccountRecoveryBody> }) =>
+      core.auth.initiateAccountRecovery(input)
+  },
+  'auth.account-recovery.complete': {
+    input: completeAccountRecoveryBody,
+    handler: async ({ c, input }: { c: Context<AppEnv>; input: z.infer<typeof completeAccountRecoveryBody> }) =>
+      respondWithSession(c, core.auth.completeAccountRecovery(input))
+  },
+  'auth.users.list': {
+    handler: async () => core.auth.listUsers()
+  },
+  'auth.users.block': {
+    input: blockUserBody,
+    handler: async ({ userId, input }: { userId: EntryId; input: z.infer<typeof blockUserBody> }) =>
+      core.auth.blockUser(input.userId ?? userId, input.blocked)
+  },
+  'auth.users.delete': {
+    mode: 'workflow' as const,
+    workflowName: 'erase-user',
+    input: eraseUserInput,
+    output: eraseUserOutput,
+    handler: async ({ input, step }: { input: EraseUserInput; step: StepRunner }) => core.auth.eraseUser(input, step)
+  },
+  'auth.sign-out': {
+    input: signOutBody,
+    handler: async ({ c, input }: { c: Context<AppEnv>; input: z.infer<typeof signOutBody> }) => {
+      const cookie = getCookie(c, CORE_CONFIG.auth.sessionCookie)
+      if (cookie) await core.internals.auth.revokeSession(cookie, Boolean(input.deleteUser)).catch(() => {})
+      deleteCookie(c, CORE_CONFIG.auth.sessionCookie, { path: '/' })
+      return { ok: true }
+    }
+  }
+}

package/src/auth/schema.ts

@@ -0,0 +1,181 @@
+import { z } from 'zod'
+import {
+  CORE_CONFIG,
+  type AuthEmailPurpose,
+  type AuthTokenPurpose,
+  type DbRole,
+  type TransactionalEmailPayload
+} from '../config'
+import { entryId, type BaseEntryFields, type EntryId } from '../db'
+
+export { type AuthEmailPurpose, type AuthTokenPurpose, type TransactionalEmailPayload }
+
+export const SESSION_COOKIE = CORE_CONFIG.auth.sessionCookie
+export const SESSION_EXPIRES_IN = CORE_CONFIG.auth.sessionExpiresInMs
+export const ADMIN_USER_ID: EntryId = CORE_CONFIG.auth.adminUserId
+
+export type OAuthProvider = 'google' | 'apple'
+
+export interface LinkedProvider {
+  provider: OAuthProvider
+  providerUserId: string
+  email?: string | null
+  linkedAt: Date
+}
+
+export interface CachedTokenEntry {
+  uid: EntryId
+  role: DbRole
+  exp: number
+  cachedAt: number
+  strictVerified: boolean
+  emailVerified?: boolean
+}
+
+export interface UserAuthMetaRecord {
+  email?: string | null
+  emailVerified?: boolean
+  name?: string | null
+  avatarUrl?: string | null
+  recoveryEmail?: string | null
+  recoveryEmailVerified?: boolean
+  linkedProviders?: LinkedProvider[]
+  providerKeys?: string[]
+  createdAt?: Date
+  updatedAt?: Date
+}
+
+export interface VerifiedOidcClaims {
+  sub: string
+  email: string | null
+  emailVerified: boolean
+  name?: string
+  picture?: string
+}
+
+export interface AuthUser {
+  id: EntryId
+  email: string | null
+  emailVerified: boolean
+  name: string | null
+  avatarUrl?: string | null
+  /** Secondary recovery email (stored normalized/lowercase) */
+  recoveryEmail?: string | null
+  /** True only after the user verifies ownership of `recoveryEmail` via OTP */
+  recoveryEmailVerified?: boolean
+  linkedProviders?: LinkedProvider[]
+  customClaims?: Record<string, unknown>
+  deleted: boolean
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface AuthTokenDoc extends BaseEntryFields {
+  userId: EntryId
+  purpose: AuthTokenPurpose
+  /** Target email address (primary email or recovery email) */
+  targetEmail: string
+  /** SHA-256 hex digest of the 6-digit OTP code or 32-byte URL token */
+  tokenHash: string
+  urlTokenHash?: string
+  /** Max 5 failed verification attempts before automatic invalidation */
+  attempts: number
+  expiresAt: Date
+  consumedAt?: Date | null
+}
+
+export const eraseUserInput = z.object({
+  userId: entryId,
+  backupBeforeErase: z.boolean().default(false)
+})
+export const eraseUserOutput = z.object({
+  userId: entryId,
+  backupOperation: z.string().optional(),
+  erasedFiles: z.number(),
+  erasedChats: z.number(),
+  erasedCollections: z.record(z.string(), z.number()).optional(),
+  erasedUser: z.boolean()
+})
+export type EraseUserInput = z.input<typeof eraseUserInput>
+export type EraseUserOutput = z.infer<typeof eraseUserOutput>
+
+export const customTokenBody = z
+  .object({ uid: entryId.refine((id) => id !== CORE_CONFIG.auth.adminUserId, 'Reserved UID').optional() })
+  .default({})
+export const sessionBody = z.object({ idToken: z.string().min(1) })
+export const emailSignUpBody = z.object({
+  email: z.string().email(),
+  password: z.string().min(8).max(128),
+  name: z.string().min(1).max(120).optional()
+})
+export const emailSignInBody = z.object({ email: z.string().email(), password: z.string().min(1).max(128) })
+
+export const socialSignInInput = z.object({
+  provider: z.enum(['google', 'apple']),
+  /** OIDC ID token returned by Apple Sign-In (iOS/Capacitor/Web) or Google Sign-In */
+  idToken: z.string().min(20),
+  /** Optional raw nonce for Apple Sign-In replay protection */
+  nonce: z.string().optional(),
+  /** Optional access token (Google) */
+  accessToken: z.string().optional(),
+  /**
+   * Apple iOS/Capacitor quirk: Apple ONLY sends the user's `name` on the VERY FIRST authorization.
+   * Accept optional first-time profile data from the client and persist it immediately.
+   */
+  profile: z
+    .object({
+      name: z.string().min(1).max(128).optional(),
+      avatarUrl: z.string().url().optional()
+    })
+    .optional()
+})
+export type SocialSignInInput = z.infer<typeof socialSignInInput>
+
+export const sendVerificationEmailBody = z.object({}).default({})
+export const verifyEmailBody = z.object({
+  email: z.string().email(),
+  codeOrToken: z.string().min(4).max(512)
+})
+export type VerifyEmailInput = z.infer<typeof verifyEmailBody>
+
+export const forgotPasswordBody = z.object({
+  email: z.string().email()
+})
+export type ForgotPasswordInput = z.infer<typeof forgotPasswordBody>
+
+export const resetPasswordBody = z.object({
+  email: z.string().email(),
+  codeOrToken: z.string().min(4).max(512),
+  newPassword: z.string().min(8).max(128)
+})
+export type ResetPasswordInput = z.infer<typeof resetPasswordBody>
+
+export const setRecoveryEmailBody = z.object({
+  recoveryEmail: z.string().email()
+})
+export type SetRecoveryEmailInput = z.infer<typeof setRecoveryEmailBody>
+
+export const verifyRecoveryEmailBody = z.object({
+  codeOrToken: z.string().min(4).max(512)
+})
+export type VerifyRecoveryEmailInput = z.infer<typeof verifyRecoveryEmailBody>
+
+export const initiateAccountRecoveryBody = z.object({
+  primaryEmail: z.string().email(),
+  recoveryEmail: z.string().email()
+})
+export type InitiateAccountRecoveryInput = z.infer<typeof initiateAccountRecoveryBody>
+
+export const completeAccountRecoveryBody = z.object({
+  primaryEmail: z.string().email(),
+  recoveryEmail: z.string().email(),
+  codeOrToken: z.string().min(4).max(512),
+  newPrimaryEmail: z.string().email(),
+  newPassword: z.string().min(8).max(128).optional()
+})
+export type CompleteAccountRecoveryInput = z.infer<typeof completeAccountRecoveryBody>
+
+export const blockUserBody = z
+  .object({ userId: entryId.optional(), blocked: z.boolean().default(true) })
+  .default({ blocked: true })
+export const signOutBody = z.object({ deleteUser: z.boolean().optional() }).default({})