@stravigor/bastion 0.2.0

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@stravigor/bastion",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Headless authentication flows for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": ["src/", "stubs/", "package.json", "tsconfig.json"],
+  "peerDependencies": {
+    "@stravigor/core": "0.3.3"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions.ts

@@ -0,0 +1,24 @@
+import type { BastionActions } from './types.ts'
+
+/**
+ * Type-safe identity function for defining Bastion actions.
+ * Zero runtime cost — just provides autocompletion and type checking.
+ *
+ * @example
+ * import { defineActions } from '@stravigor/bastion'
+ * import { User } from '../models/user'
+ *
+ * export default defineActions<User>({
+ *   createUser: async (data) => User.create({ ... }),
+ *   findByEmail: (email) => User.query().where('email', email).first(),
+ *   findById: (id) => User.find(id),
+ *   passwordHashOf: (user) => user.password,
+ *   emailOf: (user) => user.email,
+ *   updatePassword: async (user, pw) => { user.password = await encrypt.hash(pw); await user.save() },
+ * })
+ */
+export function defineActions<TUser = unknown>(
+  actions: BastionActions<TUser>
+): BastionActions<TUser> {
+  return actions
+}

package/src/bastion_manager.ts

@@ -0,0 +1,209 @@
+import { inject } from '@stravigor/core/core'
+import type Configuration from '@stravigor/core/config/configuration'
+import type Router from '@stravigor/core/http/router'
+import { compose } from '@stravigor/core/http/middleware'
+import type { Handler, Middleware } from '@stravigor/core/http/middleware'
+import { rateLimit } from '@stravigor/core/http/rate_limit'
+import { auth } from '@stravigor/core/auth/middleware/authenticate'
+import { guest } from '@stravigor/core/auth/middleware/guest'
+import { ConfigurationError } from '@stravigor/core/exceptions/errors'
+import { MissingActionError } from './errors.ts'
+import type { BastionActions, BastionConfig, Feature } from './types.ts'
+import { registerHandler } from './handlers/register.ts'
+import { loginHandler } from './handlers/login.ts'
+import { logoutHandler } from './handlers/logout.ts'
+import { forgotPasswordHandler } from './handlers/forgot_password.ts'
+import { resetPasswordHandler } from './handlers/reset_password.ts'
+import { sendVerificationHandler, verifyEmailHandler } from './handlers/verify_email.ts'
+import {
+  enableTwoFactorHandler,
+  confirmTwoFactorHandler,
+  disableTwoFactorHandler,
+  twoFactorChallengeHandler,
+} from './handlers/two_factor.ts'
+import { confirmPasswordHandler } from './handlers/confirm_password.ts'
+import { updatePasswordHandler } from './handlers/update_password.ts'
+import { updateProfileHandler } from './handlers/update_profile.ts'
+import { confirmed } from './middleware/confirmed.ts'
+
+// ---------------------------------------------------------------------------
+// Default config
+// ---------------------------------------------------------------------------
+
+const DEFAULTS: BastionConfig = {
+  features: ['registration', 'login', 'logout', 'password-reset'],
+  prefix: '',
+  mode: 'session',
+  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 },
+  },
+  passwords:     { expiration: 60 },
+  verification:  { expiration: 60 },
+  confirmation:  { timeout: 10_800 },
+  twoFactor:     { issuer: 'Strav', digits: 6, period: 30, recoveryCodes: 8 },
+}
+
+// ---------------------------------------------------------------------------
+// Manager
+// ---------------------------------------------------------------------------
+
+/** Wrap a handler with middleware via compose. */
+function withMiddleware(mw: Middleware[], handler: Handler): Handler {
+  return mw.length > 0 ? compose(mw, handler) : handler
+}
+
+@inject
+export default class BastionManager {
+  private static _config: BastionConfig
+  private static _actions: BastionActions
+
+  constructor(config: Configuration) {
+    const raw = config.get('bastion', {}) as Partial<BastionConfig>
+    BastionManager._config = { ...DEFAULTS, ...raw } as BastionConfig
+  }
+
+  // ── Accessors ────────────────────────────────────────────────────────
+
+  static get config(): BastionConfig {
+    if (!BastionManager._config) {
+      throw new ConfigurationError('BastionManager not configured. Resolve it through the container first.')
+    }
+    return BastionManager._config
+  }
+
+  static get actions(): BastionActions {
+    if (!BastionManager._actions) {
+      throw new ConfigurationError('Bastion actions not set. Pass actions to BastionProvider.')
+    }
+    return BastionManager._actions
+  }
+
+  /** Set the user-defined actions contract. */
+  static useActions(actions: BastionActions): void {
+    BastionManager._actions = actions
+  }
+
+  /** Check whether a feature is enabled. */
+  static hasFeature(feature: Feature): boolean {
+    return BastionManager._config.features.includes(feature)
+  }
+
+  // ── Validation ───────────────────────────────────────────────────────
+
+  /** Verify that all required actions are provided for enabled features. */
+  static validateActions(): void {
+    const a = BastionManager._actions
+    const has = (f: Feature) => BastionManager.hasFeature(f)
+
+    if (has('email-verification')) {
+      if (!a.isEmailVerified) throw new MissingActionError('isEmailVerified', 'email-verification')
+      if (!a.markEmailVerified) throw new MissingActionError('markEmailVerified', 'email-verification')
+    }
+
+    if (has('two-factor')) {
+      if (!a.twoFactorSecretOf) throw new MissingActionError('twoFactorSecretOf', 'two-factor')
+      if (!a.setTwoFactorSecret) throw new MissingActionError('setTwoFactorSecret', 'two-factor')
+      if (!a.recoveryCodesOf) throw new MissingActionError('recoveryCodesOf', 'two-factor')
+      if (!a.setRecoveryCodes) throw new MissingActionError('setRecoveryCodes', 'two-factor')
+    }
+
+    if (has('update-profile')) {
+      if (!a.updateProfile) throw new MissingActionError('updateProfile', 'update-profile')
+    }
+  }
+
+  // ── Route registration ───────────────────────────────────────────────
+
+  /** Build a rate limit middleware from a config key. */
+  private static rl(key: keyof BastionConfig['rateLimit']): Middleware {
+    const cfg = BastionManager._config.rateLimit[key]
+    return rateLimit({ max: cfg.max, window: cfg.window * 1000 })
+  }
+
+  /**
+   * Register all Bastion routes on the given router.
+   *
+   * @param router  - The router instance.
+   * @param options - `only` or `except` to selectively register routes.
+   */
+  static routes(
+    router: Router,
+    options?: { only?: Feature[]; except?: Feature[] }
+  ): void {
+    const enabled = (f: Feature): boolean => {
+      if (!BastionManager.hasFeature(f)) return false
+      if (options?.only) return options.only.includes(f)
+      if (options?.except) return !options.except.includes(f)
+      return true
+    }
+
+    const prefix = BastionManager._config.prefix
+
+    router.group({ prefix }, r => {
+      if (enabled('registration')) {
+        r.post('/register', withMiddleware(
+          [guest(), BastionManager.rl('register')], registerHandler
+        ))
+      }
+
+      if (enabled('login')) {
+        r.post('/login', withMiddleware(
+          [guest(), BastionManager.rl('login')], loginHandler
+        ))
+      }
+
+      if (enabled('logout')) {
+        r.post('/logout', withMiddleware([auth()], logoutHandler))
+      }
+
+      if (enabled('password-reset')) {
+        r.post('/forgot-password', withMiddleware(
+          [guest(), BastionManager.rl('forgotPassword')], forgotPasswordHandler
+        ))
+        r.post('/reset-password', withMiddleware([guest()], resetPasswordHandler))
+      }
+
+      if (enabled('email-verification')) {
+        r.post('/email/send', withMiddleware(
+          [auth(), BastionManager.rl('verifyEmail')], sendVerificationHandler
+        ))
+        r.get('/email/verify/:token', verifyEmailHandler)
+      }
+
+      if (enabled('two-factor')) {
+        r.post('/two-factor/enable', withMiddleware(
+          [auth(), confirmed()], enableTwoFactorHandler
+        ))
+        r.post('/two-factor/confirm', withMiddleware([auth()], confirmTwoFactorHandler))
+        r.delete('/two-factor', withMiddleware(
+          [auth(), confirmed()], disableTwoFactorHandler
+        ))
+        r.post('/two-factor/challenge', withMiddleware(
+          [BastionManager.rl('twoFactor')], twoFactorChallengeHandler
+        ))
+      }
+
+      if (enabled('password-confirmation')) {
+        r.post('/confirm-password', withMiddleware([auth()], confirmPasswordHandler))
+      }
+
+      if (enabled('update-password')) {
+        r.put('/password', withMiddleware([auth()], updatePasswordHandler))
+      }
+
+      if (enabled('update-profile')) {
+        r.put('/profile', withMiddleware([auth()], updateProfileHandler))
+      }
+    })
+  }
+
+  /** Clear all state. For testing. */
+  static reset(): void {
+    BastionManager._config = undefined as any
+    BastionManager._actions = undefined as any
+  }
+}

package/src/bastion_provider.ts

@@ -0,0 +1,25 @@
+import { ServiceProvider } from '@stravigor/core/core'
+import type { Application } from '@stravigor/core/core'
+import Router from '@stravigor/core/http/router'
+import BastionManager from './bastion_manager.ts'
+import type { BastionActions } from './types.ts'
+
+export default class BastionProvider extends ServiceProvider {
+  readonly name = 'bastion'
+  override readonly dependencies = ['auth', 'session', 'encryption', 'mail']
+
+  constructor(private actions: BastionActions) {
+    super()
+  }
+
+  override register(app: Application): void {
+    app.singleton(BastionManager)
+  }
+
+  override boot(app: Application): void {
+    app.resolve(BastionManager)
+    BastionManager.useActions(this.actions)
+    BastionManager.validateActions()
+    BastionManager.routes(app.resolve(Router))
+  }
+}

package/src/errors.ts

@@ -0,0 +1,21 @@
+import { StravError } from '@stravigor/core/exceptions/strav_error'
+
+/** Base error for all Bastion errors. */
+export class BastionError extends StravError {}
+
+/** Thrown when a required action is missing for an enabled feature. */
+export class MissingActionError extends BastionError {
+  constructor(action: string, feature: string) {
+    super(`Bastion action "${action}" is required when the "${feature}" feature is enabled.`)
+  }
+}
+
+/** Thrown when input validation fails. */
+export class ValidationError extends BastionError {
+  constructor(
+    message: string,
+    public readonly errors: Record<string, string> = {}
+  ) {
+    super(message)
+  }
+}

package/src/handlers/confirm_password.ts

@@ -0,0 +1,32 @@
+import type Context from '@stravigor/core/http/context'
+import type Session from '@stravigor/core/session/session'
+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 confirmPasswordHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{ password?: string }>()
+
+  if (!body.password) {
+    return ctx.json({ message: 'Password is required.' }, 422)
+  }
+
+  const user = ctx.get('user')
+  const hash = BastionManager.actions.passwordHashOf(user)
+  const valid = await encrypt.verify(body.password, hash)
+
+  if (!valid) {
+    return ctx.json({ message: 'Invalid password.' }, 422)
+  }
+
+  // Store confirmation timestamp in session
+  const session = ctx.get<Session>('session')
+  session.set('_bastion_confirmed_at', Date.now())
+
+  if (Emitter.listenerCount(BastionEvents.PASSWORD_CONFIRMED) > 0) {
+    Emitter.emit(BastionEvents.PASSWORD_CONFIRMED, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Password confirmed.' })
+}

package/src/handlers/forgot_password.ts

@@ -0,0 +1,36 @@
+import type Context from '@stravigor/core/http/context'
+import { mail } from '@stravigor/core/mail'
+import { extractUserId } from '@stravigor/core/helpers/identity'
+import BastionManager from '../bastion_manager.ts'
+import { createSignedToken } from '../tokens.ts'
+
+export async function forgotPasswordHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{ email?: string }>()
+
+  if (!body.email) {
+    return ctx.json({ message: 'Email is required.' }, 422)
+  }
+
+  // Always return success to prevent email enumeration
+  const user = await BastionManager.actions.findByEmail(body.email)
+
+  if (user) {
+    const config = BastionManager.config
+    const userId = extractUserId(user)
+    const email = BastionManager.actions.emailOf(user)
+
+    const token = createSignedToken(
+      { sub: userId, typ: 'password-reset', email },
+      config.passwords.expiration
+    )
+
+    const resetUrl = `${ctx.url.origin}${config.prefix}/reset-password?token=${encodeURIComponent(token)}`
+
+    await mail.to(email)
+      .subject('Reset Your Password')
+      .template('bastion.reset-password', { resetUrl, expiration: config.passwords.expiration })
+      .send()
+  }
+
+  return ctx.json({ message: 'If an account exists, a reset link has been sent.' })
+}

package/src/handlers/login.ts

@@ -0,0 +1,65 @@
+import type Context from '@stravigor/core/http/context'
+import type Session from '@stravigor/core/session/session'
+import AccessToken from '@stravigor/core/auth/access_token'
+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 loginHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{ email?: string; password?: string }>()
+  const { email, password } = body
+
+  // Validate
+  if (!email || !password) {
+    return ctx.json({ message: 'Email and password are required.' }, 422)
+  }
+
+  // Find user
+  const user = await BastionManager.actions.findByEmail(email)
+  if (!user) {
+    return ctx.json({ message: 'Invalid credentials.' }, 401)
+  }
+
+  // Verify password
+  const hash = BastionManager.actions.passwordHashOf(user)
+  const valid = await encrypt.verify(password, hash)
+  if (!valid) {
+    return ctx.json({ message: 'Invalid credentials.' }, 401)
+  }
+
+  // Two-factor challenge
+  if (BastionManager.hasFeature('two-factor') && BastionManager.actions.twoFactorSecretOf) {
+    const secret = BastionManager.actions.twoFactorSecretOf(user)
+    if (secret) {
+      // Store the user email in session for the challenge step
+      const session = ctx.get<Session>('session')
+      session.set('_bastion_2fa_email', email)
+      return ctx.json({ two_factor: true })
+    }
+  }
+
+  return completeLogin(ctx, user)
+}
+
+/** Finalize login — authenticate session or issue token. */
+export async function completeLogin(ctx: Context, user: unknown): Promise<Response> {
+  const config = BastionManager.config
+
+  if (config.mode === 'session') {
+    const session = ctx.get<Session>('session')
+    session.authenticate(user)
+    await session.regenerate()
+  }
+
+  if (Emitter.listenerCount(BastionEvents.LOGIN) > 0) {
+    Emitter.emit(BastionEvents.LOGIN, { user, ctx }).catch(() => {})
+  }
+
+  if (config.mode === 'token') {
+    const { token, accessToken } = await AccessToken.create(user, 'login')
+    return ctx.json({ user, token, accessToken })
+  }
+
+  return ctx.json({ user })
+}

package/src/handlers/logout.ts

@@ -0,0 +1,23 @@
+import type Context from '@stravigor/core/http/context'
+import Session from '@stravigor/core/session/session'
+import Emitter from '@stravigor/core/events/emitter'
+import BastionManager from '../bastion_manager.ts'
+import { BastionEvents } from '../types.ts'
+
+export async function logoutHandler(ctx: Context): Promise<Response> {
+  const user = ctx.get('user')
+
+  if (Emitter.listenerCount(BastionEvents.LOGOUT) > 0) {
+    Emitter.emit(BastionEvents.LOGOUT, { user, ctx }).catch(() => {})
+  }
+
+  if (BastionManager.config.mode === 'session') {
+    const response = ctx.json({ message: 'Logged out.' })
+    return Session.destroy(ctx, response)
+  }
+
+  // Token mode: the client should discard the token.
+  // Optionally we could revoke the token here, but the auth middleware
+  // already attaches the accessToken to the context.
+  return ctx.json({ message: 'Logged out.' })
+}

package/src/handlers/register.ts

@@ -0,0 +1,70 @@
+import type Context from '@stravigor/core/http/context'
+import type Session from '@stravigor/core/session/session'
+import AccessToken from '@stravigor/core/auth/access_token'
+import Emitter from '@stravigor/core/events/emitter'
+import BastionManager from '../bastion_manager.ts'
+import { ValidationError } from '../errors.ts'
+import { BastionEvents } from '../types.ts'
+import { sendVerificationEmail } from './verify_email.ts'
+
+export async function registerHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<Record<string, unknown>>()
+  const { name, email, password, password_confirmation } = body as {
+    name?: string
+    email?: string
+    password?: string
+    password_confirmation?: string
+  }
+
+  // Validate
+  const errors: Record<string, string> = {}
+  if (!name || typeof name !== 'string') errors.name = 'Name is required.'
+  if (!email || typeof email !== 'string') errors.email = 'Email is required.'
+  if (!password || typeof password !== 'string') errors.password = 'Password is required.'
+  else if (password.length < 8) errors.password = 'Password must be at least 8 characters.'
+  if (password !== password_confirmation) errors.password_confirmation = 'Passwords do not match.'
+
+  if (Object.keys(errors).length > 0) {
+    return ctx.json({ message: 'Validation failed.', errors }, 422)
+  }
+
+  // Check if email is already taken
+  const existing = await BastionManager.actions.findByEmail(email!)
+  if (existing) {
+    return ctx.json({ message: 'Validation failed.', errors: { email: 'Email already taken.' } }, 422)
+  }
+
+  // Create user
+  const user = await BastionManager.actions.createUser({
+    name: name!,
+    email: email!,
+    password: password!,
+    ...body,
+  })
+
+  const config = BastionManager.config
+
+  // Authenticate
+  if (config.mode === 'session') {
+    const session = ctx.get<Session>('session')
+    session.authenticate(user)
+    await session.regenerate()
+  }
+
+  // Emit
+  if (Emitter.listenerCount(BastionEvents.REGISTERED) > 0) {
+    Emitter.emit(BastionEvents.REGISTERED, { user, ctx }).catch(() => {})
+  }
+
+  // Auto-send verification email if feature enabled
+  if (BastionManager.hasFeature('email-verification')) {
+    sendVerificationEmail(user).catch(() => {})
+  }
+
+  if (config.mode === 'token') {
+    const { token, accessToken } = await AccessToken.create(user, 'registration')
+    return ctx.json({ user, token, accessToken }, 201)
+  }
+
+  return ctx.json({ user }, 201)
+}

package/src/handlers/reset_password.ts

@@ -0,0 +1,56 @@
+import type Context from '@stravigor/core/http/context'
+import Emitter from '@stravigor/core/events/emitter'
+import BastionManager from '../bastion_manager.ts'
+import { verifySignedToken } from '../tokens.ts'
+import { BastionEvents } from '../types.ts'
+
+export async function resetPasswordHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{
+    token?: string
+    password?: string
+    password_confirmation?: string
+  }>()
+
+  // Validate input
+  if (!body.token) {
+    return ctx.json({ message: 'Token is required.' }, 422)
+  }
+  if (!body.password || body.password.length < 8) {
+    return ctx.json({ message: 'Password must be at least 8 characters.' }, 422)
+  }
+  if (body.password !== body.password_confirmation) {
+    return ctx.json({ message: 'Passwords do not match.' }, 422)
+  }
+
+  // Verify token
+  let payload: { sub: string | number; typ: string; email: string }
+  try {
+    payload = verifySignedToken(body.token)
+  } catch {
+    return ctx.json({ message: 'Invalid or expired reset token.' }, 422)
+  }
+
+  if (payload.typ !== 'password-reset') {
+    return ctx.json({ message: 'Invalid token type.' }, 422)
+  }
+
+  // Find user
+  const user = await BastionManager.actions.findById(payload.sub)
+  if (!user) {
+    return ctx.json({ message: 'Invalid or expired reset token.' }, 422)
+  }
+
+  // Verify the email still matches (prevents token reuse after email change)
+  if (BastionManager.actions.emailOf(user) !== payload.email) {
+    return ctx.json({ message: 'Invalid or expired reset token.' }, 422)
+  }
+
+  // Update password
+  await BastionManager.actions.updatePassword(user, body.password)
+
+  if (Emitter.listenerCount(BastionEvents.PASSWORD_RESET) > 0) {
+    Emitter.emit(BastionEvents.PASSWORD_RESET, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Password has been reset.' })
+}