@strav/jina 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @stravigor/jina
+
+Headless authentication flows for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Registration, login, logout, password reset, email verification, two-factor authentication (TOTP), password confirmation, and profile updates — all as JSON API endpoints.
+
+## Install
+
+```bash
+bun add @stravigor/jina
+bun strav install jina
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Setup
+
+```ts
+import { defineActions } from '@stravigor/jina'
+import User from './models/user'
+
+const actions = defineActions<User>({
+  async createUser(data) { return User.create(data) },
+  async findByEmail(email) { return User.query().where('email', email).first() },
+  async findById(id) { return User.find(id) },
+  passwordHashOf(user) { return user.password },
+  emailOf(user) { return user.email },
+  async updatePassword(user, pw) { user.password = pw; await user.save() },
+})
+```
+
+```ts
+import { JinaProvider } from '@stravigor/jina'
+
+app.use(new JinaProvider(actions))
+```
+
+## Routes
+
+Routes are registered automatically:
+
+| Method | Path | Feature |
+|--------|------|---------|
+| POST | `/register` | registration |
+| POST | `/login` | login |
+| POST | `/logout` | logout |
+| POST | `/forgot-password` | password-reset |
+| POST | `/reset-password` | password-reset |
+| POST | `/email/send` | email-verification |
+| GET | `/email/verify/:token` | email-verification |
+| POST | `/two-factor/enable` | two-factor |
+| POST | `/two-factor/confirm` | two-factor |
+| DELETE | `/two-factor` | two-factor |
+| POST | `/two-factor/challenge` | two-factor |
+| POST | `/confirm-password` | password-confirmation |
+| PUT | `/password` | update-password |
+| PUT | `/profile` | update-profile |
+
+## Middleware
+
+```ts
+import { verified, confirmed, twoFactorChallenge } from '@stravigor/jina'
+
+router.group({ middleware: [auth(), verified()] }, r => {
+  r.delete('/account', compose([confirmed()], deleteAccountHandler))
+})
+```
+
+## Documentation
+
+See the full [Jina guide](../../guides/jina.md).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@strav/jina",
+  "version": "0.1.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": {
+    "@strav/kernel": "0.1.0",
+    "@strav/http": "0.1.0",
+    "@strav/signal": "0.1.0",
+    "@strav/database": "0.1.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions.ts

@@ -0,0 +1,22 @@
+import type { JinaActions } from './types.ts'
+
+/**
+ * Type-safe identity function for defining Jina actions.
+ * Zero runtime cost — just provides autocompletion and type checking.
+ *
+ * @example
+ * import { defineActions } from '@stravigor/jina'
+ * 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: JinaActions<TUser>): JinaActions<TUser> {
+  return actions
+}

package/src/errors.ts

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

package/src/handlers/confirm_password.ts

@@ -0,0 +1,30 @@
+import { encrypt, Emitter } from '@stravigor/kernel'
+import type { Context, Session } from '@stravigor/http'
+import JinaManager from '../jina_manager.ts'
+import { JinaEvents } 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 = JinaManager.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('_jina_confirmed_at', Date.now())
+
+  if (Emitter.listenerCount(JinaEvents.PASSWORD_CONFIRMED) > 0) {
+    Emitter.emit(JinaEvents.PASSWORD_CONFIRMED, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Password confirmed.' })
+}

package/src/handlers/forgot_password.ts

@@ -0,0 +1,37 @@
+import { mail } from '@stravigor/signal'
+import { extractUserId } from '@stravigor/database'
+import type { Context } from '@stravigor/http'
+import JinaManager from '../jina_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 JinaManager.actions.findByEmail(body.email)
+
+  if (user) {
+    const config = JinaManager.config
+    const userId = extractUserId(user)
+    const email = JinaManager.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('jina.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,63 @@
+import { encrypt, Emitter } from '@stravigor/kernel'
+import { AccessToken } from '@stravigor/http'
+import type { Context, Session } from '@stravigor/http'
+import JinaManager from '../jina_manager.ts'
+import { JinaEvents } 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 JinaManager.actions.findByEmail(email)
+  if (!user) {
+    return ctx.json({ message: 'Invalid credentials.' }, 401)
+  }
+
+  // Verify password
+  const hash = JinaManager.actions.passwordHashOf(user)
+  const valid = await encrypt.verify(password, hash)
+  if (!valid) {
+    return ctx.json({ message: 'Invalid credentials.' }, 401)
+  }
+
+  // Two-factor challenge
+  if (JinaManager.hasFeature('two-factor') && JinaManager.actions.twoFactorSecretOf) {
+    const secret = JinaManager.actions.twoFactorSecretOf(user)
+    if (secret) {
+      // Store the user email in session for the challenge step
+      const session = ctx.get<Session>('session')
+      session.set('_jina_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 = JinaManager.config
+
+  if (config.mode === 'session') {
+    const session = ctx.get<Session>('session')
+    session.authenticate(user)
+    await session.regenerate()
+  }
+
+  if (Emitter.listenerCount(JinaEvents.LOGIN) > 0) {
+    Emitter.emit(JinaEvents.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 { Emitter } from '@stravigor/kernel'
+import { Session } from '@stravigor/http'
+import type { Context } from '@stravigor/http'
+import JinaManager from '../jina_manager.ts'
+import { JinaEvents } from '../types.ts'
+
+export async function logoutHandler(ctx: Context): Promise<Response> {
+  const user = ctx.get('user')
+
+  if (Emitter.listenerCount(JinaEvents.LOGOUT) > 0) {
+    Emitter.emit(JinaEvents.LOGOUT, { user, ctx }).catch(() => {})
+  }
+
+  if (JinaManager.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,72 @@
+import { Emitter } from '@stravigor/kernel'
+import { AccessToken } from '@stravigor/http'
+import type { Context, Session } from '@stravigor/http'
+import JinaManager from '../jina_manager.ts'
+import { ValidationError } from '../errors.ts'
+import { JinaEvents } 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 JinaManager.actions.findByEmail(email!)
+  if (existing) {
+    return ctx.json(
+      { message: 'Validation failed.', errors: { email: 'Email already taken.' } },
+      422
+    )
+  }
+
+  // Create user
+  const user = await JinaManager.actions.createUser({
+    name: name!,
+    email: email!,
+    password: password!,
+    ...body,
+  })
+
+  const config = JinaManager.config
+
+  // Authenticate
+  if (config.mode === 'session') {
+    const session = ctx.get<Session>('session')
+    session.authenticate(user)
+    await session.regenerate()
+  }
+
+  // Emit
+  if (Emitter.listenerCount(JinaEvents.REGISTERED) > 0) {
+    Emitter.emit(JinaEvents.REGISTERED, { user, ctx }).catch(() => {})
+  }
+
+  // Auto-send verification email if feature enabled
+  if (JinaManager.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 { Emitter } from '@stravigor/kernel'
+import type { Context } from '@stravigor/http'
+import JinaManager from '../jina_manager.ts'
+import { verifySignedToken } from '../tokens.ts'
+import { JinaEvents } 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 JinaManager.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 (JinaManager.actions.emailOf(user) !== payload.email) {
+    return ctx.json({ message: 'Invalid or expired reset token.' }, 422)
+  }
+
+  // Update password
+  await JinaManager.actions.updatePassword(user, body.password)
+
+  if (Emitter.listenerCount(JinaEvents.PASSWORD_RESET) > 0) {
+    Emitter.emit(JinaEvents.PASSWORD_RESET, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Password has been reset.' })
+}

package/src/handlers/two_factor.ts

@@ -0,0 +1,171 @@
+import { Emitter } from '@stravigor/kernel'
+import type { Context, Session } from '@stravigor/http'
+import JinaManager from '../jina_manager.ts'
+import { JinaEvents } 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 = JinaManager.actions
+  const config = JinaManager.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('_jina_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 = JinaManager.actions
+  const config = JinaManager.config.twoFactor
+
+  const session = ctx.get<Session>('session')
+  const pendingSecret = session.get<string>('_jina_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('_jina_2fa_secret')
+
+  if (Emitter.listenerCount(JinaEvents.TWO_FACTOR_ENABLED) > 0) {
+    Emitter.emit(JinaEvents.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 = JinaManager.actions
+
+  await actions.setTwoFactorSecret!(user, null)
+  await actions.setRecoveryCodes!(user, [])
+
+  if (Emitter.listenerCount(JinaEvents.TWO_FACTOR_DISABLED) > 0) {
+    Emitter.emit(JinaEvents.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 = JinaManager.actions
+  const config = JinaManager.config.twoFactor
+
+  // Retrieve the pending login email from the session
+  const pendingEmail = session.get<string>('_jina_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('_jina_2fa_email')
+
+  // Complete the login
+  return completeLogin(ctx, user)
+}

package/src/handlers/update_password.ts

@@ -0,0 +1,39 @@
+import { encrypt, Emitter } from '@stravigor/kernel'
+import type { Context } from '@stravigor/http'
+import JinaManager from '../jina_manager.ts'
+import { JinaEvents } 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 = JinaManager.actions.passwordHashOf(user)
+  const valid = await encrypt.verify(body.current_password, hash)
+
+  if (!valid) {
+    return ctx.json({ message: 'Current password is incorrect.' }, 422)
+  }
+
+  await JinaManager.actions.updatePassword(user, body.password)
+
+  if (Emitter.listenerCount(JinaEvents.PASSWORD_UPDATED) > 0) {
+    Emitter.emit(JinaEvents.PASSWORD_UPDATED, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Password updated.' })
+}

package/src/handlers/update_profile.ts

@@ -0,0 +1,17 @@
+import { Emitter } from '@stravigor/kernel'
+import type { Context } from '@stravigor/http'
+import JinaManager from '../jina_manager.ts'
+import { JinaEvents } 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 JinaManager.actions.updateProfile!(user, data)
+
+  if (Emitter.listenerCount(JinaEvents.PROFILE_UPDATED) > 0) {
+    Emitter.emit(JinaEvents.PROFILE_UPDATED, { user, ctx }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Profile updated.' })
+}