@strav/jina 0.1.0

package/src/handlers/verify_email.ts

@@ -0,0 +1,84 @@
+import { Emitter } from '@stravigor/kernel'
+import { mail } from '@stravigor/signal'
+import { extractUserId } from '@stravigor/database'
+import type { Context } from '@stravigor/http'
+import JinaManager from '../jina_manager.ts'
+import { createSignedToken, verifySignedToken } from '../tokens.ts'
+import { JinaEvents } from '../types.ts'
+
+/** Send a verification email for the given user. */
+export async function sendVerificationEmail(user: unknown): Promise<void> {
+  const config = JinaManager.config
+  const actions = JinaManager.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('jina.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 = JinaManager.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 JinaManager.actions.findById(payload.sub)
+  if (!user) {
+    return ctx.json({ message: 'Invalid verification link.' }, 422)
+  }
+
+  // Verify the email still matches
+  if (JinaManager.actions.emailOf(user) !== payload.email) {
+    return ctx.json({ message: 'Invalid verification link.' }, 422)
+  }
+
+  const actions = JinaManager.actions
+
+  if (actions.isEmailVerified!(user)) {
+    return ctx.json({ message: 'Email already verified.' })
+  }
+
+  await actions.markEmailVerified!(user)
+
+  if (Emitter.listenerCount(JinaEvents.EMAIL_VERIFIED) > 0) {
+    Emitter.emit(JinaEvents.EMAIL_VERIFIED, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Email verified.' })
+}

package/src/helpers.ts

@@ -0,0 +1,67 @@
+import JinaManager from './jina_manager.ts'
+import { createSignedToken, verifySignedToken } from './tokens.ts'
+import { generateSecret, totpUri, verifyTotp, base32Decode, generateRecoveryCodes } from './totp.ts'
+
+/**
+ * Jina helper — convenience API for auth flow utilities.
+ *
+ * @example
+ * import { jina } from '@stravigor/jina'
+ *
+ * const token = jina.signedToken({ sub: user.id, typ: 'custom' }, 60)
+ * const payload = jina.verifyToken(token)
+ *
+ * const { secret, qrUri } = jina.generateTwoFactorSecret(user)
+ * const valid = await jina.verifyTwoFactorCode(secret, code)
+ */
+export const jina = {
+  /** Check if a feature is enabled. */
+  hasFeature(feature: string): boolean {
+    return JinaManager.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 = JinaManager.config.twoFactor
+    const { base32 } = generateSecret()
+    const email = JinaManager.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 = JinaManager.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 ?? JinaManager.config.twoFactor.recoveryCodes)
+  },
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+// Manager & provider
+export { default, default as JinaManager } from './jina_manager.ts'
+export { default as JinaProvider } from './jina_provider.ts'
+
+// Helper
+export { jina } 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 { JinaError, MissingActionError, ValidationError } from './errors.ts'
+
+// Types
+export type {
+  Feature,
+  JinaActions,
+  JinaConfig,
+  JinaEvent,
+  RegistrationData,
+  RateLimitConfig,
+} from './types.ts'
+export { JinaEvents } 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/jina_manager.ts

@@ -0,0 +1,200 @@
+import { inject, Configuration, ConfigurationError } from '@stravigor/kernel'
+import { Router, compose, rateLimit, auth, guest, session } from '@stravigor/http'
+import type { Handler, Middleware } from '@stravigor/http'
+import { MissingActionError } from './errors.ts'
+import type { JinaActions, JinaConfig, 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: JinaConfig = {
+  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 JinaManager {
+  private static _config: JinaConfig
+  private static _actions: JinaActions
+
+  constructor(config: Configuration) {
+    const raw = config.get('jina', {}) as Partial<JinaConfig>
+    JinaManager._config = { ...DEFAULTS, ...raw } as JinaConfig
+  }
+
+  // ── Accessors ────────────────────────────────────────────────────────
+
+  static get config(): JinaConfig {
+    if (!JinaManager._config) {
+      throw new ConfigurationError(
+        'JinaManager not configured. Resolve it through the container first.'
+      )
+    }
+    return JinaManager._config
+  }
+
+  static get actions(): JinaActions {
+    if (!JinaManager._actions) {
+      throw new ConfigurationError('Jina actions not set. Pass actions to JinaProvider.')
+    }
+    return JinaManager._actions
+  }
+
+  /** Set the user-defined actions contract. */
+  static useActions(actions: JinaActions): void {
+    JinaManager._actions = actions
+  }
+
+  /** Check whether a feature is enabled. */
+  static hasFeature(feature: Feature): boolean {
+    return JinaManager._config.features.includes(feature)
+  }
+
+  // ── Validation ───────────────────────────────────────────────────────
+
+  /** Verify that all required actions are provided for enabled features. */
+  static validateActions(): void {
+    const a = JinaManager._actions
+    const has = (f: Feature) => JinaManager.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 JinaConfig['rateLimit']): Middleware {
+    const cfg = JinaManager._config.rateLimit[key]
+    return rateLimit({ max: cfg.max, window: cfg.window * 1000 })
+  }
+
+  /**
+   * Register all Jina 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 (!JinaManager.hasFeature(f)) return false
+      if (options?.only) return options.only.includes(f)
+      if (options?.except) return !options.except.includes(f)
+      return true
+    }
+
+    const prefix = JinaManager._config.prefix
+
+    const middleware = JinaManager._config.mode === 'session' ? [session()] : []
+
+    router.group({ prefix, middleware }, r => {
+      if (enabled('registration')) {
+        r.post('/register', withMiddleware([guest(), JinaManager.rl('register')], registerHandler))
+      }
+
+      if (enabled('login')) {
+        r.post('/login', withMiddleware([guest(), JinaManager.rl('login')], loginHandler))
+      }
+
+      if (enabled('logout')) {
+        r.post('/logout', withMiddleware([auth()], logoutHandler))
+      }
+
+      if (enabled('password-reset')) {
+        r.post(
+          '/forgot-password',
+          withMiddleware([guest(), JinaManager.rl('forgotPassword')], forgotPasswordHandler)
+        )
+        r.post('/reset-password', withMiddleware([guest()], resetPasswordHandler))
+      }
+
+      if (enabled('email-verification')) {
+        r.post(
+          '/email/send',
+          withMiddleware([auth(), JinaManager.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([JinaManager.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 {
+    JinaManager._config = undefined as any
+    JinaManager._actions = undefined as any
+  }
+}

package/src/jina_provider.ts

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

package/src/middleware/confirmed.ts

@@ -0,0 +1,27 @@
+import type { Session, Middleware } from '@stravigor/http'
+import JinaManager from '../jina_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>('_jina_confirmed_at')
+
+    if (!confirmedAt) {
+      return ctx.json({ message: 'Password confirmation required.' }, 423)
+    }
+
+    const timeout = JinaManager.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,31 @@
+import type { Session, Middleware } from '@stravigor/http'
+import JinaManager from '../jina_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 = JinaManager.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('_jina_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/http'
+import JinaManager from '../jina_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 = JinaManager.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/kernel'
+
+// ---------------------------------------------------------------------------
+// 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
+}