@stravigor/bastion 0.2.0

package/src/handlers/two_factor.ts

@@ -0,0 +1,172 @@
+import type Context from '@stravigor/core/http/context'
+import type Session from '@stravigor/core/session/session'
+import Emitter from '@stravigor/core/events/emitter'
+import BastionManager from '../bastion_manager.ts'
+import { BastionEvents } from '../types.ts'
+import {
+  generateSecret,
+  totpUri,
+  verifyTotp,
+  base32Decode,
+  generateRecoveryCodes,
+} from '../totp.ts'
+import { completeLogin } from './login.ts'
+
+// ---------------------------------------------------------------------------
+// POST /two-factor/enable — generate a TOTP secret
+// ---------------------------------------------------------------------------
+
+export async function enableTwoFactorHandler(ctx: Context): Promise<Response> {
+  const user = ctx.get('user')
+  const actions = BastionManager.actions
+  const config = BastionManager.config.twoFactor
+
+  // Don't allow re-enabling if already confirmed
+  const existingSecret = actions.twoFactorSecretOf!(user)
+  if (existingSecret) {
+    return ctx.json({ message: 'Two-factor authentication is already enabled.' }, 409)
+  }
+
+  const { base32 } = generateSecret()
+  const email = actions.emailOf(user)
+
+  const uri = totpUri({
+    secret: base32,
+    issuer: config.issuer,
+    account: email,
+    digits: config.digits,
+    period: config.period,
+  })
+
+  // Store the unconfirmed secret in the session (not persisted to user yet)
+  const session = ctx.get<Session>('session')
+  session.set('_bastion_2fa_secret', base32)
+
+  return ctx.json({ secret: base32, qr_uri: uri })
+}
+
+// ---------------------------------------------------------------------------
+// POST /two-factor/confirm — confirm 2FA setup with a valid code
+// ---------------------------------------------------------------------------
+
+export async function confirmTwoFactorHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{ code?: string }>()
+  if (!body.code) {
+    return ctx.json({ message: 'Verification code is required.' }, 422)
+  }
+
+  const user = ctx.get('user')
+  const actions = BastionManager.actions
+  const config = BastionManager.config.twoFactor
+
+  const session = ctx.get<Session>('session')
+  const pendingSecret = session.get<string>('_bastion_2fa_secret')
+  if (!pendingSecret) {
+    return ctx.json({ message: 'No pending two-factor setup. Call enable first.' }, 422)
+  }
+
+  // Verify the code against the pending secret
+  const secretBytes = base32Decode(pendingSecret)
+  const valid = await verifyTotp(secretBytes, body.code, {
+    digits: config.digits,
+    period: config.period,
+  })
+
+  if (!valid) {
+    return ctx.json({ message: 'Invalid verification code.' }, 422)
+  }
+
+  // Persist the secret to the user
+  await actions.setTwoFactorSecret!(user, pendingSecret)
+
+  // Generate recovery codes
+  const codes = generateRecoveryCodes(config.recoveryCodes)
+  await actions.setRecoveryCodes!(user, codes)
+
+  // Clean up session
+  session.forget('_bastion_2fa_secret')
+
+  if (Emitter.listenerCount(BastionEvents.TWO_FACTOR_ENABLED) > 0) {
+    Emitter.emit(BastionEvents.TWO_FACTOR_ENABLED, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Two-factor authentication enabled.', recovery_codes: codes })
+}
+
+// ---------------------------------------------------------------------------
+// DELETE /two-factor — disable 2FA
+// ---------------------------------------------------------------------------
+
+export async function disableTwoFactorHandler(ctx: Context): Promise<Response> {
+  const user = ctx.get('user')
+  const actions = BastionManager.actions
+
+  await actions.setTwoFactorSecret!(user, null)
+  await actions.setRecoveryCodes!(user, [])
+
+  if (Emitter.listenerCount(BastionEvents.TWO_FACTOR_DISABLED) > 0) {
+    Emitter.emit(BastionEvents.TWO_FACTOR_DISABLED, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Two-factor authentication disabled.' })
+}
+
+// ---------------------------------------------------------------------------
+// POST /two-factor/challenge — verify TOTP code during login
+// ---------------------------------------------------------------------------
+
+export async function twoFactorChallengeHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{ code?: string; recovery_code?: string }>()
+  const session = ctx.get<Session>('session')
+  const actions = BastionManager.actions
+  const config = BastionManager.config.twoFactor
+
+  // Retrieve the pending login email from the session
+  const pendingEmail = session.get<string>('_bastion_2fa_email')
+  if (!pendingEmail) {
+    return ctx.json({ message: 'No pending two-factor challenge.' }, 422)
+  }
+
+  const user = await actions.findByEmail(pendingEmail)
+  if (!user) {
+    return ctx.json({ message: 'Invalid challenge.' }, 422)
+  }
+
+  const secret = actions.twoFactorSecretOf!(user)
+  if (!secret) {
+    return ctx.json({ message: 'Two-factor authentication is not enabled.' }, 422)
+  }
+
+  // Try TOTP code first
+  if (body.code) {
+    const secretBytes = base32Decode(secret)
+    const valid = await verifyTotp(secretBytes, body.code, {
+      digits: config.digits,
+      period: config.period,
+    })
+
+    if (!valid) {
+      return ctx.json({ message: 'Invalid two-factor code.' }, 422)
+    }
+  }
+  // Try recovery code
+  else if (body.recovery_code) {
+    const codes = actions.recoveryCodesOf!(user)
+    const index = codes.indexOf(body.recovery_code)
+    if (index === -1) {
+      return ctx.json({ message: 'Invalid recovery code.' }, 422)
+    }
+
+    // Remove the used recovery code
+    codes.splice(index, 1)
+    await actions.setRecoveryCodes!(user, codes)
+  } else {
+    return ctx.json({ message: 'A two-factor code or recovery code is required.' }, 422)
+  }
+
+  // Clean up pending state
+  session.forget('_bastion_2fa_email')
+
+  // Complete the login
+  return completeLogin(ctx, user)
+}

package/src/handlers/update_password.ts

@@ -0,0 +1,40 @@
+import type Context from '@stravigor/core/http/context'
+import { encrypt } from '@stravigor/core/encryption'
+import Emitter from '@stravigor/core/events/emitter'
+import BastionManager from '../bastion_manager.ts'
+import { BastionEvents } from '../types.ts'
+
+export async function updatePasswordHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{
+    current_password?: string
+    password?: string
+    password_confirmation?: string
+  }>()
+
+  // Validate
+  if (!body.current_password) {
+    return ctx.json({ message: 'Current password is required.' }, 422)
+  }
+  if (!body.password || body.password.length < 8) {
+    return ctx.json({ message: 'New password must be at least 8 characters.' }, 422)
+  }
+  if (body.password !== body.password_confirmation) {
+    return ctx.json({ message: 'Passwords do not match.' }, 422)
+  }
+
+  const user = ctx.get('user')
+  const hash = BastionManager.actions.passwordHashOf(user)
+  const valid = await encrypt.verify(body.current_password, hash)
+
+  if (!valid) {
+    return ctx.json({ message: 'Current password is incorrect.' }, 422)
+  }
+
+  await BastionManager.actions.updatePassword(user, body.password)
+
+  if (Emitter.listenerCount(BastionEvents.PASSWORD_UPDATED) > 0) {
+    Emitter.emit(BastionEvents.PASSWORD_UPDATED, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Password updated.' })
+}

package/src/handlers/update_profile.ts

@@ -0,0 +1,17 @@
+import type Context from '@stravigor/core/http/context'
+import Emitter from '@stravigor/core/events/emitter'
+import BastionManager from '../bastion_manager.ts'
+import { BastionEvents } from '../types.ts'
+
+export async function updateProfileHandler(ctx: Context): Promise<Response> {
+  const data = await ctx.body<Record<string, unknown>>()
+  const user = ctx.get('user')
+
+  await BastionManager.actions.updateProfile!(user, data)
+
+  if (Emitter.listenerCount(BastionEvents.PROFILE_UPDATED) > 0) {
+    Emitter.emit(BastionEvents.PROFILE_UPDATED, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Profile updated.' })
+}

package/src/handlers/verify_email.ts

@@ -0,0 +1,83 @@
+import type Context from '@stravigor/core/http/context'
+import { mail } from '@stravigor/core/mail'
+import { extractUserId } from '@stravigor/core/helpers/identity'
+import Emitter from '@stravigor/core/events/emitter'
+import BastionManager from '../bastion_manager.ts'
+import { createSignedToken, verifySignedToken } from '../tokens.ts'
+import { BastionEvents } from '../types.ts'
+
+/** Send a verification email for the given user. */
+export async function sendVerificationEmail(user: unknown): Promise<void> {
+  const config = BastionManager.config
+  const actions = BastionManager.actions
+  const userId = extractUserId(user)
+  const email = actions.emailOf(user)
+
+  const token = createSignedToken(
+    { sub: userId, typ: 'email-verify', email },
+    config.verification.expiration
+  )
+
+  const verifyUrl = `${config.prefix}/email/verify/${encodeURIComponent(token)}`
+
+  await mail.to(email)
+    .subject('Verify Your Email')
+    .template('bastion.verify-email', { verifyUrl, expiration: config.verification.expiration })
+    .send()
+}
+
+/** POST /email/send — resend verification email. */
+export async function sendVerificationHandler(ctx: Context): Promise<Response> {
+  const user = ctx.get('user')
+  const actions = BastionManager.actions
+
+  if (actions.isEmailVerified!(user)) {
+    return ctx.json({ message: 'Email already verified.' })
+  }
+
+  await sendVerificationEmail(user)
+  return ctx.json({ message: 'Verification email sent.' })
+}
+
+/** GET /email/verify/:token — verify the email. */
+export async function verifyEmailHandler(ctx: Context): Promise<Response> {
+  const token = ctx.params.token as string | undefined
+  if (!token) {
+    return ctx.json({ message: 'Invalid verification link.' }, 422)
+  }
+
+  let payload: { sub: string | number; typ: string; email: string }
+  try {
+    payload = verifySignedToken(token)
+  } catch {
+    return ctx.json({ message: 'Invalid or expired verification link.' }, 422)
+  }
+
+  if (payload.typ !== 'email-verify') {
+    return ctx.json({ message: 'Invalid token type.' }, 422)
+  }
+
+  const user = await BastionManager.actions.findById(payload.sub)
+  if (!user) {
+    return ctx.json({ message: 'Invalid verification link.' }, 422)
+  }
+
+  // Verify the email still matches
+  if (BastionManager.actions.emailOf(user) !== payload.email) {
+    return ctx.json({ message: 'Invalid verification link.' }, 422)
+  }
+
+  const actions = BastionManager.actions
+
+  if (actions.isEmailVerified!(user)) {
+    return ctx.json({ message: 'Email already verified.' })
+  }
+
+  await actions.markEmailVerified!(user)
+
+  if (Emitter.listenerCount(BastionEvents.EMAIL_VERIFIED) > 0) {
+    Emitter.emit(BastionEvents.EMAIL_VERIFIED, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Email verified.' })
+}

package/src/helpers.ts

@@ -0,0 +1,70 @@
+import BastionManager from './bastion_manager.ts'
+import { createSignedToken, verifySignedToken } from './tokens.ts'
+import {
+  generateSecret,
+  totpUri,
+  verifyTotp,
+  base32Decode,
+  generateRecoveryCodes,
+} from './totp.ts'
+
+/**
+ * Bastion helper — convenience API for auth flow utilities.
+ *
+ * @example
+ * import { bastion } from '@stravigor/bastion'
+ *
+ * const token = bastion.signedToken({ sub: user.id, typ: 'custom' }, 60)
+ * const payload = bastion.verifyToken(token)
+ *
+ * const { secret, qrUri } = bastion.generateTwoFactorSecret(user)
+ * const valid = await bastion.verifyTwoFactorCode(secret, code)
+ */
+export const bastion = {
+  /** Check if a feature is enabled. */
+  hasFeature(feature: string): boolean {
+    return BastionManager.hasFeature(feature as any)
+  },
+
+  /** Create a signed, encrypted token with an expiration. */
+  signedToken(data: { sub: string | number; typ: string; [key: string]: unknown }, expiresInMinutes: number): string {
+    return createSignedToken(data, expiresInMinutes)
+  },
+
+  /** Verify and decode a signed token. Throws if expired or tampered. */
+  verifyToken<T extends Record<string, unknown> = Record<string, unknown>>(token: string): T {
+    return verifySignedToken<T>(token)
+  },
+
+  /** Generate a TOTP secret and QR URI for the given user. */
+  generateTwoFactorSecret(user: unknown): { secret: string; qrUri: string } {
+    const config = BastionManager.config.twoFactor
+    const { base32 } = generateSecret()
+    const email = BastionManager.actions.emailOf(user)
+
+    const uri = totpUri({
+      secret: base32,
+      issuer: config.issuer,
+      account: email,
+      digits: config.digits,
+      period: config.period,
+    })
+
+    return { secret: base32, qrUri: uri }
+  },
+
+  /** Verify a TOTP code against a base32 secret. */
+  async verifyTwoFactorCode(base32Secret: string, code: string): Promise<boolean> {
+    const config = BastionManager.config.twoFactor
+    const secretBytes = base32Decode(base32Secret)
+    return verifyTotp(secretBytes, code, {
+      digits: config.digits,
+      period: config.period,
+    })
+  },
+
+  /** Generate a set of single-use recovery codes. */
+  generateRecoveryCodes(count?: number): string[] {
+    return generateRecoveryCodes(count ?? BastionManager.config.twoFactor.recoveryCodes)
+  },
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+// Manager & provider
+export { default, default as BastionManager } from './bastion_manager.ts'
+export { default as BastionProvider } from './bastion_provider.ts'
+
+// Helper
+export { bastion } from './helpers.ts'
+
+// Actions
+export { defineActions } from './actions.ts'
+
+// Middleware
+export { verified } from './middleware/verified.ts'
+export { confirmed } from './middleware/confirmed.ts'
+export { twoFactorChallenge } from './middleware/two_factor_challenge.ts'
+
+// Handlers (for manual route registration)
+export { registerHandler } from './handlers/register.ts'
+export { loginHandler } from './handlers/login.ts'
+export { logoutHandler } from './handlers/logout.ts'
+export { forgotPasswordHandler } from './handlers/forgot_password.ts'
+export { resetPasswordHandler } from './handlers/reset_password.ts'
+export { sendVerificationHandler, verifyEmailHandler } from './handlers/verify_email.ts'
+export {
+  enableTwoFactorHandler,
+  confirmTwoFactorHandler,
+  disableTwoFactorHandler,
+  twoFactorChallengeHandler,
+} from './handlers/two_factor.ts'
+export { confirmPasswordHandler } from './handlers/confirm_password.ts'
+export { updatePasswordHandler } from './handlers/update_password.ts'
+export { updateProfileHandler } from './handlers/update_profile.ts'
+
+// Errors
+export { BastionError, MissingActionError, ValidationError } from './errors.ts'
+
+// Types
+export type {
+  Feature,
+  BastionActions,
+  BastionConfig,
+  BastionEvent,
+  RegistrationData,
+  RateLimitConfig,
+} from './types.ts'
+export { BastionEvents } from './types.ts'
+
+// TOTP utilities
+export { generateSecret, totpUri, verifyTotp, generateRecoveryCodes, base32Encode, base32Decode } from './totp.ts'
+
+// Token utilities
+export { createSignedToken, verifySignedToken } from './tokens.ts'

package/src/middleware/confirmed.ts

@@ -0,0 +1,28 @@
+import type Session from '@stravigor/core/session/session'
+import type { Middleware } from '@stravigor/core/http/middleware'
+import BastionManager from '../bastion_manager.ts'
+
+/**
+ * Require the user to have confirmed their password recently.
+ * Returns 423 (Locked) if the confirmation has expired.
+ *
+ * @example
+ * router.delete('/account', auth(), confirmed(), deleteAccountHandler)
+ */
+export function confirmed(): Middleware {
+  return (ctx, next) => {
+    const session = ctx.get<Session>('session')
+    const confirmedAt = session.get<number>('_bastion_confirmed_at')
+
+    if (!confirmedAt) {
+      return ctx.json({ message: 'Password confirmation required.' }, 423)
+    }
+
+    const timeout = BastionManager.config.confirmation.timeout * 1000
+    if (Date.now() - confirmedAt > timeout) {
+      return ctx.json({ message: 'Password confirmation has expired.' }, 423)
+    }
+
+    return next()
+  }
+}

package/src/middleware/two_factor_challenge.ts

@@ -0,0 +1,32 @@
+import type Session from '@stravigor/core/session/session'
+import type { Middleware } from '@stravigor/core/http/middleware'
+import BastionManager from '../bastion_manager.ts'
+
+/**
+ * Require a completed two-factor challenge for the current session.
+ * Returns 403 if the user has 2FA enabled but hasn't completed the challenge.
+ *
+ * Useful for protecting sensitive routes beyond the initial login.
+ *
+ * @example
+ * router.post('/transfer', auth(), twoFactorChallenge(), transferHandler)
+ */
+export function twoFactorChallenge(): Middleware {
+  return (ctx, next) => {
+    const user = ctx.get('user')
+    const actions = BastionManager.actions
+
+    // If 2FA is not enabled for this user, let them through
+    if (!actions.twoFactorSecretOf) return next()
+    const secret = actions.twoFactorSecretOf(user)
+    if (!secret) return next()
+
+    // Check if there's still a pending 2FA challenge in the session
+    const session = ctx.get<Session>('session')
+    if (session.has('_bastion_2fa_email')) {
+      return ctx.json({ message: 'Two-factor authentication required.' }, 403)
+    }
+
+    return next()
+  }
+}

package/src/middleware/verified.ts

@@ -0,0 +1,24 @@
+import type { Middleware } from '@stravigor/core/http/middleware'
+import BastionManager from '../bastion_manager.ts'
+
+/**
+ * Require the authenticated user to have a verified email address.
+ * Returns 403 if the email is not verified.
+ *
+ * @example
+ * router.group({ middleware: [auth(), verified()] }, r => {
+ *   r.get('/dashboard', dashboardHandler)
+ * })
+ */
+export function verified(): Middleware {
+  return (ctx, next) => {
+    const user = ctx.get('user')
+    const actions = BastionManager.actions
+
+    if (!actions.isEmailVerified!(user)) {
+      return ctx.json({ message: 'Email not verified.' }, 403)
+    }
+
+    return next()
+  }
+}

package/src/tokens.ts

@@ -0,0 +1,60 @@
+import { encrypt } from '@stravigor/core/encryption'
+
+// ---------------------------------------------------------------------------
+// Signed token payloads
+// ---------------------------------------------------------------------------
+
+export interface TokenPayload {
+  /** User identifier. */
+  sub: string | number
+  /** Token purpose. */
+  typ: string
+  /** Issued at (unix ms). */
+  iat: number
+  /** Expiration (minutes from iat). */
+  exp: number
+  /** Extra data. */
+  [key: string]: unknown
+}
+
+/**
+ * Create a signed, encrypted token using `encrypt.seal()`.
+ * Tamper-proof and opaque — the user cannot read or modify the payload.
+ *
+ * @param data  - The payload to sign.
+ * @param expiresInMinutes - Token lifetime in minutes.
+ */
+export function createSignedToken(
+  data: { sub: string | number; typ: string; [key: string]: unknown },
+  expiresInMinutes: number
+): string {
+  const payload: TokenPayload = {
+    ...data,
+    iat: Date.now(),
+    exp: expiresInMinutes,
+  }
+  return encrypt.seal(payload)
+}
+
+/**
+ * Verify and decode a signed token. Throws if expired or tampered.
+ *
+ * @returns The original payload.
+ * @throws  If the token is invalid, expired, or tampered.
+ */
+export function verifySignedToken<T = TokenPayload>(token: string): T {
+  const payload = encrypt.unseal<TokenPayload>(token)
+
+  if (!payload || typeof payload !== 'object' || !payload.iat) {
+    throw new Error('Invalid token payload.')
+  }
+
+  if (payload.exp) {
+    const expiresAt = payload.iat + payload.exp * 60_000
+    if (Date.now() > expiresAt) {
+      throw new Error('Token has expired.')
+    }
+  }
+
+  return payload as unknown as T
+}