@stravigor/bastion 0.2.0

package/src/totp.ts

@@ -0,0 +1,174 @@
+/**
+ * TOTP (Time-Based One-Time Password) implementation — RFC 6238.
+ * Pure Bun crypto, zero external dependencies.
+ */
+
+import { timingSafeEqual as nodeTimingSafeEqual } from 'node:crypto'
+
+// ---------------------------------------------------------------------------
+// Base32 encoding/decoding (RFC 4648)
+// ---------------------------------------------------------------------------
+
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+
+export function base32Encode(buffer: Uint8Array): string {
+  let result = ''
+  let bits = 0
+  let value = 0
+
+  for (const byte of buffer) {
+    value = (value << 8) | byte
+    bits += 8
+    while (bits >= 5) {
+      bits -= 5
+      result += BASE32_ALPHABET[(value >>> bits) & 0x1f]!
+    }
+  }
+
+  if (bits > 0) {
+    result += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f]!
+  }
+
+  return result
+}
+
+export function base32Decode(encoded: string): Uint8Array {
+  const cleaned = encoded.replace(/=+$/, '').toUpperCase()
+  const bytes: number[] = []
+  let bits = 0
+  let value = 0
+
+  for (const char of cleaned) {
+    const index = BASE32_ALPHABET.indexOf(char)
+    if (index === -1) continue
+    value = (value << 5) | index
+    bits += 5
+    if (bits >= 8) {
+      bits -= 8
+      bytes.push((value >>> bits) & 0xff)
+    }
+  }
+
+  return new Uint8Array(bytes)
+}
+
+// ---------------------------------------------------------------------------
+// HOTP — RFC 4226
+// ---------------------------------------------------------------------------
+
+async function hotp(secret: Uint8Array, counter: bigint, digits: number): Promise<string> {
+  // Counter as 8-byte big-endian buffer
+  const counterBuffer = new ArrayBuffer(8)
+  const view = new DataView(counterBuffer)
+  view.setBigUint64(0, counter)
+
+  // HMAC-SHA1
+  const key = await crypto.subtle.importKey('raw', secret, { name: 'HMAC', hash: 'SHA-1' }, false, [
+    'sign',
+  ])
+  const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, counterBuffer))
+
+  // Dynamic truncation
+  const offset = mac[19]! & 0x0f
+  const code =
+    ((mac[offset]! & 0x7f) << 24) |
+    ((mac[offset + 1]! & 0xff) << 16) |
+    ((mac[offset + 2]! & 0xff) << 8) |
+    (mac[offset + 3]! & 0xff)
+
+  return String(code % 10 ** digits).padStart(digits, '0')
+}
+
+// ---------------------------------------------------------------------------
+// TOTP — RFC 6238
+// ---------------------------------------------------------------------------
+
+export interface TotpOptions {
+  digits?: number
+  period?: number
+  /** Number of time steps to check before/after current (handles clock drift). */
+  window?: number
+}
+
+/** Generate a TOTP code for the given secret at the current time. */
+export async function generateTotp(
+  secret: Uint8Array,
+  options: TotpOptions = {}
+): Promise<string> {
+  const { digits = 6, period = 30 } = options
+  const counter = BigInt(Math.floor(Date.now() / 1000 / period))
+  return hotp(secret, counter, digits)
+}
+
+/** Verify a TOTP code, allowing for clock drift within the window. */
+export async function verifyTotp(
+  secret: Uint8Array,
+  code: string,
+  options: TotpOptions = {}
+): Promise<boolean> {
+  const { digits = 6, period = 30, window = 1 } = options
+  const now = BigInt(Math.floor(Date.now() / 1000 / period))
+
+  for (let i = -window; i <= window; i++) {
+    const expected = await hotp(secret, now + BigInt(i), digits)
+    if (timingSafeEqual(code, expected)) return true
+  }
+
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// Secret generation
+// ---------------------------------------------------------------------------
+
+/** Generate a random TOTP secret (20 bytes, returned as base32). */
+export function generateSecret(): { raw: Uint8Array; base32: string } {
+  const raw = crypto.getRandomValues(new Uint8Array(20))
+  return { raw, base32: base32Encode(raw) }
+}
+
+/**
+ * Build an `otpauth://` URI for QR code generation.
+ * Compatible with Google Authenticator, Authy, 1Password, etc.
+ */
+export function totpUri(options: {
+  secret: string // base32
+  issuer: string
+  account: string
+  digits?: number
+  period?: number
+}): string {
+  const { secret, issuer, account, digits = 6, period = 30 } = options
+  const label = `${encodeURIComponent(issuer)}:${encodeURIComponent(account)}`
+  const params = new URLSearchParams({
+    secret,
+    issuer,
+    algorithm: 'SHA1',
+    digits: String(digits),
+    period: String(period),
+  })
+  return `otpauth://totp/${label}?${params}`
+}
+
+// ---------------------------------------------------------------------------
+// Recovery codes
+// ---------------------------------------------------------------------------
+
+/** Generate a set of single-use recovery codes (8-char hex each). */
+export function generateRecoveryCodes(count: number): string[] {
+  const codes: string[] = []
+  for (let i = 0; i < count; i++) {
+    const bytes = crypto.getRandomValues(new Uint8Array(4))
+    codes.push(Array.from(bytes, b => b.toString(16).padStart(2, '0')).join(''))
+  }
+  return codes
+}
+
+// ---------------------------------------------------------------------------
+// Timing-safe string comparison
+// ---------------------------------------------------------------------------
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  return nodeTimingSafeEqual(Buffer.from(a), Buffer.from(b))
+}

package/src/types.ts

@@ -0,0 +1,135 @@
+import type Context from '@stravigor/core/http/context'
+
+// ---------------------------------------------------------------------------
+// Feature flags
+// ---------------------------------------------------------------------------
+
+export type Feature =
+  | 'registration'
+  | 'login'
+  | 'logout'
+  | 'password-reset'
+  | 'email-verification'
+  | 'two-factor'
+  | 'password-confirmation'
+  | 'update-password'
+  | 'update-profile'
+
+// ---------------------------------------------------------------------------
+// Actions — the user-provided contract
+// ---------------------------------------------------------------------------
+
+export interface RegistrationData {
+  name: string
+  email: string
+  password: string
+  [key: string]: unknown
+}
+
+export interface BastionActions<TUser = unknown> {
+  /** Create and persist a new user. Password is raw — hash it yourself. */
+  createUser(data: RegistrationData): Promise<TUser>
+
+  /** Find a user by email address. Return null if not found. */
+  findByEmail(email: string): Promise<TUser | null>
+
+  /** Find a user by primary key. Return null if not found. */
+  findById(id: string | number): Promise<TUser | null>
+
+  /** Return the stored password hash for verification. */
+  passwordHashOf(user: TUser): string
+
+  /** Return the user's email address. */
+  emailOf(user: TUser): string
+
+  /** Persist a new password. Password is raw — hash it yourself. */
+  updatePassword(user: TUser, newPassword: string): Promise<void>
+
+  // ─── Email verification (required when feature is enabled) ───────────
+
+  /** Whether the user has verified their email. */
+  isEmailVerified?(user: TUser): boolean
+
+  /** Mark the user's email as verified. */
+  markEmailVerified?(user: TUser): Promise<void>
+
+  // ─── Two-factor authentication (required when feature is enabled) ────
+
+  /** Return the TOTP secret, or null if 2FA is not enabled. */
+  twoFactorSecretOf?(user: TUser): string | null
+
+  /** Persist the TOTP secret (null to clear). */
+  setTwoFactorSecret?(user: TUser, secret: string | null): Promise<void>
+
+  /** Return the user's recovery codes. */
+  recoveryCodesOf?(user: TUser): string[]
+
+  /** Persist new recovery codes. */
+  setRecoveryCodes?(user: TUser, codes: string[]): Promise<void>
+
+  // ─── Profile update (required when feature is enabled) ───────────────
+
+  /** Update the user's profile fields. */
+  updateProfile?(user: TUser, data: Record<string, unknown>): Promise<void>
+}
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface RateLimitConfig {
+  /** Maximum requests in the window. */
+  max: number
+  /** Window duration in seconds. */
+  window: number
+}
+
+export interface BastionConfig {
+  features: Feature[]
+  prefix: string
+  mode: 'session' | 'token'
+  rateLimit: {
+    login: RateLimitConfig
+    register: RateLimitConfig
+    forgotPassword: RateLimitConfig
+    verifyEmail: RateLimitConfig
+    twoFactor: RateLimitConfig
+  }
+  passwords: {
+    expiration: number // minutes
+  }
+  verification: {
+    expiration: number // minutes
+  }
+  confirmation: {
+    timeout: number // seconds
+  }
+  twoFactor: {
+    issuer: string
+    digits: number
+    period: number
+    recoveryCodes: number
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+
+export interface BastionEvent<TUser = unknown> {
+  user: TUser
+  ctx: Context
+}
+
+export const BastionEvents = {
+  REGISTERED:           'bastion:registered',
+  LOGIN:                'bastion:login',
+  LOGOUT:               'bastion:logout',
+  PASSWORD_RESET:       'bastion:password-reset',
+  EMAIL_VERIFIED:       'bastion:email-verified',
+  TWO_FACTOR_ENABLED:   'bastion:two-factor-enabled',
+  TWO_FACTOR_DISABLED:  'bastion:two-factor-disabled',
+  PASSWORD_CONFIRMED:   'bastion:password-confirmed',
+  PASSWORD_UPDATED:     'bastion:password-updated',
+  PROFILE_UPDATED:      'bastion:profile-updated',
+} as const

package/stubs/actions/bastion.ts

@@ -0,0 +1,83 @@
+import { defineActions } from '@stravigor/bastion'
+import { encrypt } from '@stravigor/core/encryption'
+// import { User } from '../models/user'
+
+/**
+ * Bastion actions — tell Bastion how your User model works.
+ *
+ * These are the only functions you need to implement. Bastion handles
+ * the routing, token generation, rate limiting, and event emission.
+ */
+export default defineActions({
+  // ── Core (required) ──────────────────────────────────────────────────
+
+  async createUser(data) {
+    // return await User.create({
+    //   name: data.name,
+    //   email: data.email,
+    //   password: await encrypt.hash(data.password),
+    // })
+    throw new Error('Implement createUser in actions/bastion.ts')
+  },
+
+  async findByEmail(email) {
+    // return await User.query().where('email', email).first()
+    throw new Error('Implement findByEmail in actions/bastion.ts')
+  },
+
+  async findById(id) {
+    // return await User.find(id)
+    throw new Error('Implement findById in actions/bastion.ts')
+  },
+
+  passwordHashOf(user: any) {
+    return user.password
+  },
+
+  emailOf(user: any) {
+    return user.email
+  },
+
+  async updatePassword(user: any, newPassword) {
+    user.password = await encrypt.hash(newPassword)
+    await user.save()
+  },
+
+  // ── Email verification (uncomment when feature is enabled) ───────────
+
+  // isEmailVerified(user: any) {
+  //   return user.emailVerifiedAt !== null
+  // },
+
+  // async markEmailVerified(user: any) {
+  //   user.emailVerifiedAt = new Date()
+  //   await user.save()
+  // },
+
+  // ── Two-factor authentication (uncomment when feature is enabled) ────
+
+  // twoFactorSecretOf(user: any) {
+  //   return user.twoFactorSecret ?? null
+  // },
+
+  // async setTwoFactorSecret(user: any, secret) {
+  //   user.twoFactorSecret = secret
+  //   await user.save()
+  // },
+
+  // recoveryCodesOf(user: any) {
+  //   return user.recoveryCodes ?? []
+  // },
+
+  // async setRecoveryCodes(user: any, codes) {
+  //   user.recoveryCodes = codes
+  //   await user.save()
+  // },
+
+  // ── Profile update (uncomment when feature is enabled) ───────────────
+
+  // async updateProfile(user: any, data) {
+  //   Object.assign(user, data)
+  //   await user.save()
+  // },
+})

package/stubs/config/bastion.ts

@@ -0,0 +1,55 @@
+import { env } from '@stravigor/core/helpers'
+
+export default {
+  // Toggle features on/off. Uncomment to enable.
+  features: [
+    'registration',
+    'login',
+    'logout',
+    'password-reset',
+    // 'email-verification',
+    // 'two-factor',
+    // 'password-confirmation',
+    // 'update-password',
+    // 'update-profile',
+  ],
+
+  // Route prefix — '' means routes live at /login, /register, etc.
+  prefix: '',
+
+  // Auth mode: 'session' (cookie-based) or 'token' (access tokens)
+  mode: 'session',
+
+  // Rate limiting per flow (max attempts per window in seconds)
+  rateLimit: {
+    login:          { max: 5, window: 60 },
+    register:       { max: 3, window: 60 },
+    forgotPassword: { max: 3, window: 60 },
+    verifyEmail:    { max: 3, window: 60 },
+    twoFactor:      { max: 5, window: 60 },
+  },
+
+  // Password reset link lifetime (minutes)
+  passwords: {
+    expiration: 60,
+  },
+
+  // Email verification link lifetime (minutes)
+  verification: {
+    expiration: 60,
+  },
+
+  // Password confirmation timeout (seconds) — how long before the user
+  // must re-enter their password for sensitive operations
+  confirmation: {
+    timeout: 10_800, // 3 hours
+  },
+
+  // Two-factor authentication (TOTP)
+  twoFactor: {
+    issuer: env('APP_NAME', 'Strav'),
+    digits: 6,
+    period: 30,
+    recoveryCodes: 8,
+  },
+}

package/stubs/emails/reset-password.strav

@@ -0,0 +1,26 @@
+{{-- Password Reset Email --}}
+
+<div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 600px; margin: 0 auto; padding: 40px 20px;">
+  <h2 style="color: #1a1a1a; margin-bottom: 24px;">Reset Your Password</h2>
+
+  <p style="color: #4a4a4a; line-height: 1.6;">
+    You requested a password reset. Click the button below to choose a new password.
+  </p>
+
+  <div style="text-align: center; margin: 32px 0;">
+    <a href="{{ resetUrl }}" style="display: inline-block; background-color: #2563eb; color: #ffffff; text-decoration: none; padding: 12px 32px; border-radius: 6px; font-weight: 600;">
+      Reset Password
+    </a>
+  </div>
+
+  <p style="color: #6b7280; font-size: 14px; line-height: 1.6;">
+    This link will expire in {{ expiration }} minutes. If you didn't request a password reset, you can safely ignore this email.
+  </p>
+
+  <hr style="border: none; border-top: 1px solid #e5e7eb; margin: 32px 0;" />
+
+  <p style="color: #9ca3af; font-size: 12px;">
+    If the button doesn't work, copy and paste this URL into your browser:<br />
+    <span style="color: #6b7280;">{{ resetUrl }}</span>
+  </p>
+</div>

package/stubs/emails/verify-email.strav

@@ -0,0 +1,26 @@
+{{-- Email Verification --}}
+
+<div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 600px; margin: 0 auto; padding: 40px 20px;">
+  <h2 style="color: #1a1a1a; margin-bottom: 24px;">Verify Your Email</h2>
+
+  <p style="color: #4a4a4a; line-height: 1.6;">
+    Thanks for signing up! Please verify your email address by clicking the button below.
+  </p>
+
+  <div style="text-align: center; margin: 32px 0;">
+    <a href="{{ verifyUrl }}" style="display: inline-block; background-color: #2563eb; color: #ffffff; text-decoration: none; padding: 12px 32px; border-radius: 6px; font-weight: 600;">
+      Verify Email
+    </a>
+  </div>
+
+  <p style="color: #6b7280; font-size: 14px; line-height: 1.6;">
+    This link will expire in {{ expiration }} minutes. If you didn't create an account, you can safely ignore this email.
+  </p>
+
+  <hr style="border: none; border-top: 1px solid #e5e7eb; margin: 32px 0;" />
+
+  <p style="color: #9ca3af; font-size: 12px;">
+    If the button doesn't work, copy and paste this URL into your browser:<br />
+    <span style="color: #6b7280;">{{ verifyUrl }}</span>
+  </p>
+</div>

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"]
+}