kreftjs 0.0.0-stage → 0.0.2-beta

package/server.js

@@ -0,0 +1,8 @@
+/*
+ * Kreft on the server: routes, controllers, models, migrations, seeders, middleware and namespaces.
+ *
+ *   const { Route, Model, DB, Seeder, abort, response, use, namespace } = require('kreftjs/server')
+ *
+ * `kreftjs dev` and `kreftjs serve` load routes/api.js and answer /api/... with it.
+ */
+module.exports = require('./bin/backend/index.js');

package/templates/app/README.md

@@ -0,0 +1,127 @@
+# My Kreft Application
+
+Welcome to your **Kreft** full-stack application.
+
+## Quick Commands
+
+```bash
+npm run dev       # Start dev server with hot-reload + backend API (http://localhost:8000)
+npm run build     # Compile minified production assets into dist/
+npm run serve     # Run the production server (serves dist/ + backend/ API)
+npm test          # Run backend & frontend test suites
+```
+
+> **Demo Credentials:** Sign in with **test@example.com** and password **password**, or register a new account. Outgoing emails (verification, password reset) are printed in the terminal until `MAIL_URL` is configured in `.env`.
+
+---
+
+## Project Architecture
+
+Your project cleanly isolates client-side UI (`frontend/`) from server-side business logic (`backend/`):
+
+```text
+├── frontend/                  # Public client application (the only folder served to browsers)
+│   ├── index.html             # HTML entry, auth store, router & app bootstrap
+│   ├── App.kreftjs              # Root reactive shell
+│   ├── routes/web.kreftjs       # Client-side routes (Dashboard, Users, Profile, Auth)
+│   ├── layouts/               # app.kreftjs (authenticated shell) & guest.kreftjs (auth pages)
+│   ├── pages/                 # Route views (Home, Dashboard, Users, Profile, auth/*)
+│   ├── components/            # Reusable widgets (Field.kreftjs, StatCard.kreftjs, profile/*)
+│   ├── errors/                # Custom HTTP error views (404.kreftjs, 500.kreftjs, ErrorMonitor.kreftjs)
+│   ├── docs/                  # Built-in documentation (accessible at /docs)
+│   └── ui.css                 # Design system tokens & component styles
+│
+├── backend/                   # Private server engine (never exposed or built into dist/)
+│   ├── config/                # Centralized config (app, auth, database, redis, session)
+│   ├── routes/                # api.js (REST API), auth.js (Auth endpoints), console.js (Cron)
+│   ├── app/
+│   │   ├── Http/Controllers/  # Request handlers & validation
+│   │   ├── Http/Middleware/   # Auth, CheckAbilities, EnsureIsAdmin, security headers
+│   │   └── Models/            # Active Record models (User.js, PersonalAccessToken.js, etc.)
+│   └── database/              # migrations/, seeders/, factories/, and SQLite app.db
+│
+└── .env                       # Environment secrets (APP_KEY, DB_*, REDIS_*, SESSION_*)
+```
+
+---
+
+## Scaffolding & CLI Generators
+
+Generate full-stack features from the terminal:
+
+```bash
+# Generate Model + Migration + Factory + Seeder + Controller + .kreftjs Page + Route:
+kreftjs make:model Post --all
+
+# Or pick specific layers (-m migration, -f factory, -s seeder, -c controller, -p page, -r route):
+kreftjs make:model Post -mfscpr --route=api --auth
+
+# Individual generators:
+kreftjs make:controller OrderController --api
+kreftjs make:request StorePostRequest --model Post
+kreftjs make:resource PostResource
+kreftjs make:rule StrongPassword
+kreftjs make:observer PostObserver --model Post
+kreftjs make:middleware EnsureSubscribed
+kreftjs make:job ProcessWebhook
+kreftjs make:mail InvoiceReady
+kreftjs make:routes billing        # Creates frontend/routes/billing.kreftjs & backend/routes/billing.js
+
+# Database & inspection tools:
+kreftjs db:migrate                 # Run pending migrations
+kreftjs db:seed                    # Run database seeders
+kreftjs route:list                 # List all registered backend API routes
+kreftjs redis:ping                 # Verify Redis connectivity
+kreftjs tinker                     # Interactive REPL with your Models, DB, Cache & Redis preloaded
+```
+
+---
+
+## Writing `.kreftjs` Components
+
+Every `.kreftjs` file combines reactive state, actions, `<view>`, and optional `<style scoped>`:
+
+```html
+<!-- frontend/pages/Posts.kreftjs -->
+state title = ''
+load posts = api.get('/api/posts')
+
+action create() {
+  await api.post('/api/posts', { title })
+  title = ''
+  posts.reload()
+}
+
+<view>
+  <h1>Posts</h1>
+  <form @submit.prevent={create} class="row">
+    <input k-model="title" placeholder="Post title" required>
+    <button class="primary">Publish</button>
+  </form>
+
+  <ul k-if="posts.data">
+    {for post in posts.data key post.id}
+      <li>{post.title}</li>
+    {/for}
+  </ul>
+</view>
+```
+
+---
+
+## Installing & Updating Packages
+
+Use `kreftjs add` to install npm packages safely (blocks untrusted lifecycle scripts, checks for typosquatting, and skips redundant packages already built into Kreft):
+
+```bash
+kreftjs add dayjs nanoid
+kreftjs add -D esbuild             # Bundles browser packages into import-mapped modules
+```
+
+Keep dependencies and your embedded Kreft runtime up to date:
+
+```bash
+kreftjs update                     # Update npm dependencies & refresh kreftjs.js / kreftjs.d.ts
+kreftjs update --check             # Check for outdated packages without modifying files
+kreftjs update --core              # Refresh only Kreft runtime & TypeScript definitions
+```

package/templates/app/_env.example

@@ -0,0 +1,64 @@
+# Settings for this app. Copy this file to .env and fill it in.
+# .env is never sent to the browser, never copied by kreftjs build, and not committed (see .gitignore).
+# Server code (routes/, app/, database/) reads it as process.env.NAME.
+APP_NAME="My app"
+
+# Signs the links in emails. kreftjs new makes one; keep it secret, and keep it the same once users have links.
+APP_KEY=
+# Where the app runs: links in emails start with this
+APP_URL=http://localhost:8000
+
+# Only values that start with PUBLIC_ also reach the browser: {env.PUBLIC_APP_NAME} in any .kreftjs file.
+# Never put a password or a secret key in a PUBLIC_ value.
+PUBLIC_APP_NAME="${APP_NAME}"
+
+# The database: sqlite:file.db, mysql://user:password@host:3306/name or postgres://user:password@host:5432/name
+DATABASE_URL=sqlite:backend/database/app.db
+
+# Background work: queued jobs, mail and notifications (redis, database: the jobs table, run by kreftjs dev / kreftjs queue:work; sync: at once)
+QUEUE_CONNECTION=database
+# Cache.put / Cache.remember: redis, database, file or memory
+CACHE_STORE=database
+# Storage.put: local (backend/storage/app, private) or public (served at /storage)
+FILESYSTEM_DISK=local
+
+# Redis (for Cache, Queue, and pub/sub): redis://default:secret@127.0.0.1:6379/0 or host/port
+# REDIS_URL=redis://127.0.0.1:6379/0
+# REDIS_HOST=127.0.0.1
+# REDIS_PORT=6379
+# REDIS_PASSWORD=
+# REDIS_DB=0
+# REDIS_PREFIX=som:
+# Environment & Debugging:
+# - local: plain HTTP allowed on localhost, interactive bug diagnostics & stack traces shown
+# - production: plain HTTP disallowed for security (enforces HTTPS & HSTS), bug details & stack traces hidden
+APP_ENV=local
+APP_DEBUG=true
+
+# Force all traffic over secure HTTPS in production (auto-redirects HTTP -> HTTPS with HSTS)
+FORCE_HTTPS=false
+SESSION_SECURE_COOKIE=false
+
+# Security & Sessions
+# A login token nobody used for this many days stops working
+AUTH_TOKEN_DAYS=30
+# wrong passwords allowed per account (in LOGIN_WINDOW_SECONDS) before logins for it are refused, and wrong two-factor codes
+LOGIN_MAX_FAILURES=10
+LOGIN_WINDOW_SECONDS=900
+TWO_FACTOR_MAX_FAILURES=8
+# Session lifetime in minutes (backend inactivity timeout)
+SESSION_LIFETIME=120
+SESSION_EXPIRE_ON_CLOSE=false
+SESSION_DRIVER=file
+
+# Frontend Inactivity Timer in minutes (auto-redirect to /login after inactivity)
+# Values starting with PUBLIC_ are sent to the browser and readable as {env.PUBLIC_...} in .kreftjs files
+PUBLIC_SESSION_TIMEOUT=15
+PUBLIC_SESSION_WARNING=2
+
+# Behind a proxy or load balancer (nginx, Cloudflare…), its address, so the visitor's real IP is used: 10.0.0.1 or *
+# TRUSTED_PROXIES=
+
+# Email. Without MAIL_URL, emails (verify email, reset password) are printed in the terminal.
+# MAIL_URL=smtp://user:password@smtp.example.com:587   (and: npm i nodemailer)
+# MAIL_FROM="My app <hello@example.com>"

package/templates/app/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+backend/database/*.db*
+backend/storage/

package/templates/app/_vscode/settings.json

@@ -0,0 +1,9 @@
+{
+  "files.associations": {
+    "*.kreftjs": "kreft"
+  },
+  "[kreft]": {
+    "editor.defaultFormatter": "kreft.kreftjs",
+    "editor.formatOnSave": true
+  }
+}

package/templates/app/backend/app/Auth/Session.js

@@ -0,0 +1,177 @@
+// Signing a browser in and out via secure SPA session cookies.
+//
+// A browser gets its login in an HttpOnly cookie (kreft_session): page scripts can't read it, so a
+// script injected into a page can't steal it. Changes (POST, PUT, DELETE…) also need the X-XSRF-TOKEN
+// header to match the XSRF-TOKEN cookie, which only your own pages can read (Kreftjs.api sends it by itself).
+//
+// An app or script that sends `device_name` when it logs in gets an API token in the answer instead:
+// Authorization: Bearer 5|k3J9…
+const { response, Str, Crypt, cookieSecure } = require('kreftjs/server')
+const PersonalAccessToken = require('../Models/PersonalAccessToken')
+
+const SESSION = 'kreft_session'
+const XSRF = 'XSRF-TOKEN'
+const days = () => Number(process.env.AUTH_TOKEN_DAYS || 30)
+
+const resolveSecure = () => typeof cookieSecure === 'function' ? cookieSecure() : (process.env.SESSION_SECURE_COOKIE ? process.env.SESSION_SECURE_COOKIE === 'true' : (process.env.APP_ENV === 'production' || /^https:/i.test(process.env.APP_URL || '')))
+const resolveSameSite = () => process.env.SESSION_SAME_SITE || 'Lax'
+
+// the answer to a successful login or register
+async function signIn(req, user, { remember = false, status = 200 } = {}) {
+  const deviceName = req.input('device_name')
+  if (deviceName) { // an app or a script: a Bearer token
+    const { plainTextToken } = await user.createToken(deviceName, { type: 'api', ip: req.ip(), userAgent: req.header('user-agent') })
+    return response({ user, token: plainTextToken }, status)
+  }
+
+  // Session fixation prevention: invalidate any previous session in this browser
+  const fromCookie = req.cookie(SESSION)
+  if (fromCookie) {
+    try {
+      const oldPayload = Crypt.decryptString(fromCookie)
+      const [oldId] = String(oldPayload || '').split('|')
+      if (oldId) {
+        await PersonalAccessToken.where('id', oldId).delete()
+      }
+    } catch (_) {
+      // ignore invalid / rotated old session tokens
+    }
+  }
+
+  // Generate a completely new session identifier and token
+  const { plainTextToken } = await user.createToken(browserName(req.header('user-agent', '')), {
+    type: 'session', ip: req.ip(), userAgent: req.header('user-agent'), remember,
+  })
+  const res = response({ user }, status)
+  // "Remember me": the cookie stays for AUTH_TOKEN_DAYS; otherwise it goes when the browser closes
+  // Cryptographically seal session token with APP_KEY (AES-256-GCM with fresh 12-byte random IV).
+  // If APP_KEY is changed or rotated, existing session cookies fail authentication and are destroyed.
+  const encryptedSession = Crypt.encryptString(plainTextToken)
+  const isSecure = resolveSecure()
+  const sameSite = resolveSameSite()
+
+  res.cookie(SESSION, encryptedSession, {
+    httpOnly: true,
+    secure: isSecure,
+    sameSite,
+    path: '/',
+    maxAge: remember ? days() * 86400 : undefined,
+  })
+  res.cookie(XSRF, Str.random(40), {
+    httpOnly: false,
+    secure: isSecure,
+    sameSite,
+    path: '/',
+    maxAge: remember ? days() * 86400 : undefined,
+  })
+  return res
+}
+
+// Regenerates the session token (Session Fixation Prevention on privilege change)
+async function regenerate(req, res, user = null) {
+  const targetUser = user || req.user
+  if (!targetUser) return res
+
+  if (req.accessToken) {
+    await req.accessToken.delete()
+  } else if (req.cookie(SESSION)) {
+    try {
+      const oldPayload = Crypt.decryptString(req.cookie(SESSION))
+      const [oldId] = String(oldPayload || '').split('|')
+      if (oldId) await PersonalAccessToken.where('id', oldId).delete()
+    } catch (_) {}
+  }
+
+  const { accessToken, plainTextToken } = await targetUser.createToken(browserName(req.header('user-agent', '')), {
+    type: 'session', ip: req.ip(), userAgent: req.header('user-agent'), remember: req.accessToken ? req.accessToken.remember : false,
+  })
+  req.accessToken = accessToken
+
+  const encryptedSession = Crypt.encryptString(plainTextToken)
+  const isSecure = resolveSecure()
+  const sameSite = resolveSameSite()
+  const remember = accessToken.remember
+
+  res.cookie(SESSION, encryptedSession, {
+    httpOnly: true,
+    secure: isSecure,
+    sameSite,
+    path: '/',
+    maxAge: remember ? days() * 86400 : undefined,
+  })
+  res.cookie(XSRF, Str.random(40), {
+    httpOnly: false,
+    secure: isSecure,
+    sameSite,
+    path: '/',
+    maxAge: remember ? days() * 86400 : undefined,
+  })
+  return res
+}
+
+function signOut(res) {
+  return res.withoutCookie(SESSION).withoutCookie(XSRF)
+}
+
+// two-factor: after the password, the login waits (5 minutes) for the code in an encrypted cookie
+const usedTwoFactorTickets = new Map()
+const twoFactorAttempts = new Map()
+setInterval(() => {
+  const now = Date.now()
+  for (const [k, exp] of usedTwoFactorTickets) if (exp < now) usedTwoFactorTickets.delete(k)
+  for (const [k, v] of twoFactorAttempts) if (v.exp < now) twoFactorAttempts.delete(k)
+}, 60000).unref()
+
+function pendingTwoFactor(req, user, remember) {
+  const nonce = Str.random(24)
+  const exp = Date.now() + 5 * 60000
+  const ticket = Crypt.encrypt({ id: user.id, remember: Boolean(remember), nonce, exp })
+  if (req.input('device_name')) return response({ two_factor: true, challenge: ticket })
+  return response({ two_factor: true }).cookie('kreft_2fa', ticket, { maxAge: 300 })
+}
+function readPendingTwoFactor(req) {
+  const ticket = req.input('challenge') || req.cookie('kreft_2fa')
+  if (!ticket) return null
+  try {
+    const t = Crypt.decrypt(ticket)
+    if (!t || !(t.exp > Date.now())) return null
+    if (t.nonce && usedTwoFactorTickets.has(t.nonce)) return null
+    if (t.nonce) {
+      const state = twoFactorAttempts.get(t.nonce) || { count: 0, exp: t.exp }
+      if (state.count >= 5) {
+        if (usedTwoFactorTickets.size >= 10000) usedTwoFactorTickets.delete(usedTwoFactorTickets.keys().next().value)
+        usedTwoFactorTickets.set(t.nonce, t.exp)
+        return null
+      }
+    }
+    return t
+  } catch (_) { return null }
+}
+function recordTwoFactorFailure(pending) {
+  if (!pending || !pending.nonce) return
+  const state = twoFactorAttempts.get(pending.nonce) || { count: 0, exp: pending.exp }
+  state.count++
+  if (!twoFactorAttempts.has(pending.nonce) && twoFactorAttempts.size >= 10000) {
+    twoFactorAttempts.delete(twoFactorAttempts.keys().next().value)
+  }
+  twoFactorAttempts.set(pending.nonce, state)
+  if (state.count >= 5) {
+    if (usedTwoFactorTickets.size >= 10000) usedTwoFactorTickets.delete(usedTwoFactorTickets.keys().next().value)
+    usedTwoFactorTickets.set(pending.nonce, pending.exp)
+  }
+}
+function consumeTwoFactorTicket(pending) {
+  if (!pending || !pending.nonce) return
+  if (usedTwoFactorTickets.size >= 10000) usedTwoFactorTickets.delete(usedTwoFactorTickets.keys().next().value)
+  usedTwoFactorTickets.set(pending.nonce, pending.exp)
+  twoFactorAttempts.delete(pending.nonce)
+}
+
+// "Chrome on macOS", for the list of devices
+function browserName(ua) {
+  const b = /Edg\//.test(ua) ? 'Edge' : /OPR\//.test(ua) ? 'Opera' : /Firefox\//.test(ua) ? 'Firefox' : /Chrome\//.test(ua) ? 'Chrome' : /Safari\//.test(ua) ? 'Safari' : /curl|node|axios|python/i.test(ua) ? 'Script' : 'Browser'
+  const os = /iPhone|iPad/.test(ua) ? 'iOS' : /Android/.test(ua) ? 'Android' : /Mac OS X/.test(ua) ? 'macOS' : /Windows/.test(ua) ? 'Windows' : /Linux/.test(ua) ? 'Linux' : ''
+  return os ? `${b} on ${os}` : b
+}
+
+module.exports = { signIn, signOut, regenerate, pendingTwoFactor, readPendingTwoFactor, recordTwoFactorFailure, consumeTwoFactorTicket, browserName, SESSION, XSRF }

package/templates/app/backend/app/Auth/Throttle.js

@@ -0,0 +1,29 @@
+// Failed-attempt counters kept per account (not per address), in the Cache so every process shares them.
+// The 'throttle:6,1' route limit counts per address; this one stops a guesser who changes address:
+//   const wait = await Throttle.wait('login', email, 10)    // seconds to wait, 0 when allowed
+//   if (wait) abort(429, …)   …   await Throttle.hit('login', email, 900)   …   await Throttle.clear('login', email)
+const { Cache, Hash } = require('kreftjs/server')
+
+const key = (scope, id) => `throttle:${scope}:${Hash.sha256(String(id).trim().toLowerCase())}`
+
+// seconds until this account may try again, or 0
+async function wait(scope, id, max) {
+  const s = await Cache.get(key(scope, id))
+  if (!s || !(s.resetAt > Date.now()) || s.count < max) return 0
+  return Math.max(1, Math.ceil((s.resetAt - Date.now()) / 1000))
+}
+
+// one more failure, counted for `windowSeconds` from the first one
+async function hit(scope, id, windowSeconds = 900) {
+  const k = key(scope, id)
+  const s = await Cache.get(k)
+  const cur = s && s.resetAt > Date.now() ? s : { count: 0, resetAt: Date.now() + windowSeconds * 1000 }
+  cur.count++
+  await Cache.put(k, cur, Math.max(1, Math.ceil((cur.resetAt - Date.now()) / 1000)))
+}
+
+async function clear(scope, id) {
+  await Cache.forget(key(scope, id))
+}
+
+module.exports = { wait, hit, clear }

package/templates/app/backend/app/Http/Controllers/Admin/DashboardController.js

@@ -0,0 +1,34 @@
+const User = require('../../../Models/User')
+const PersonalAccessToken = require('../../../Models/PersonalAccessToken')
+
+// GET /api/admin/stats   (frontend/pages/Dashboard.kreftjs)
+class DashboardController {
+  async index(req) {
+    if (!req.user || !req.user.is_admin) {
+      return {
+        users: 1,
+        admins: 0,
+        unverified: req.user && !req.user.email_verified_at ? 1 : 0,
+        newThisWeek: 0,
+        signedIn: req.user ? await PersonalAccessToken.where('user_id', req.user.id).count() : 0,
+        latest: req.user ? [req.user] : [],
+      }
+    }
+    const weekAgo = new Date(Date.now() - 7 * 86400000).toISOString().slice(0, 19).replace('T', ' ')
+    return {
+      users: await User.count(),
+      admins: await User.where('is_admin', true).count(),
+      unverified: await User.query().whereNull('email_verified_at').count(),
+      newThisWeek: await User.where('created_at', '>=', weekAgo).count(),
+      signedIn: await PersonalAccessToken.count(),
+      latest: await User.latest('id').limit(5).get(),
+    }
+  }
+
+  // GET /api/admin/me   (frontend/pages/Profile.kreftjs)
+  async me(req) {
+    return { user: req.user, devices: await PersonalAccessToken.where('user_id', req.user.id).count() }
+  }
+}
+
+module.exports = DashboardController

package/templates/app/backend/app/Http/Controllers/Admin/UserController.js

@@ -0,0 +1,53 @@
+const { abort, noContent } = require('kreftjs/server')
+const User = require('../../../Models/User')
+const PersonalAccessToken = require('../../../Models/PersonalAccessToken')
+
+// the roles a user can have ('role:editor' in the routes); add your own
+const ROLES = ['user', 'editor']
+
+// /api/admin/users   (frontend/pages/Users.kreftjs)
+class UserController {
+  // GET /api/admin/users?q=ali&page=2
+  async index(req) {
+    if (!req.user || !req.user.is_admin) abort(403, 'Only admins can view user accounts.')
+    const q = req.string('q').trim()
+    const safeQ = q.replace(/[%_]/g, '')
+    return User.query()
+      .when(safeQ, (query) => query.where((w) => w.whereLike('name', `%${safeQ}%`).orWhere('email', 'like', `%${safeQ.toLowerCase()}%`)))
+      .orderByDesc('id')
+      .paginate(15, req.integer('page', 1))
+  }
+
+  // PATCH /api/admin/users/{id}  { is_admin } and/or { role }
+  async update(req, id) {
+    if (!req.user || !req.user.is_admin) abort(403, 'Only admins can modify user roles or permissions.')
+    const user = await User.findOrFail(id)
+    const data = await req.validate({ is_admin: 'sometimes|boolean', role: `sometimes|in:${ROLES.join(',')}` })
+    if (data.is_admin !== undefined) {
+      const on = data.is_admin === true || data.is_admin === 1 || data.is_admin === '1' || data.is_admin === 'true'
+      const currentId = req.user ? req.user.id : null
+      if (currentId && user.id === currentId && !on) abort(422, "You can't take away your own admin rights.")
+      user.is_admin = on
+    }
+    if (data.role !== undefined) user.role = data.role
+    await user.save()
+    // Session Fixation & Privilege Protection: invalidate previous sessions when privileges change
+    if (data.is_admin !== undefined || data.role !== undefined) {
+      await PersonalAccessToken.where('user_id', user.id).where('type', 'session').delete()
+    }
+    return user
+  }
+
+  // DELETE /api/admin/users/{id}
+  async destroy(req, id) {
+    if (!req.user || !req.user.is_admin) abort(403, 'Only admins can delete user accounts.')
+    const user = await User.findOrFail(id)
+    const currentId = req.user ? req.user.id : null
+    if (currentId && user.id === currentId) abort(422, "You can't delete yourself here. Use your profile page.")
+    await PersonalAccessToken.where('user_id', user.id).delete()
+    await user.delete()
+    return noContent()
+  }
+}
+
+module.exports = UserController

package/templates/app/backend/app/Http/Controllers/Auth/ApiTokenController.js

@@ -0,0 +1,47 @@
+const { noContent, abort, response } = require('kreftjs/server')
+const PersonalAccessToken = require('../../../Models/PersonalAccessToken')
+
+// What an API token may do: change this list for your app. 'abilities:posts:write' in a route checks it.
+const ABILITIES = ['read', 'create', 'update', 'delete']
+
+// API tokens for scripts and other apps (pages/Profile.kreftjs → API tokens), like Jetstream / Sanctum
+class ApiTokenController {
+  // GET /api/user/tokens
+  async index(req) {
+    if (req.accessToken && req.accessToken.type !== 'session' && !req.accessToken.can('*')) abort(403, 'Only browser sessions may manage API tokens.')
+    const rows = await PersonalAccessToken.where('user_id', req.user.id).where('type', 'api').orderByDesc('id').get()
+    return { abilities: ABILITIES, tokens: rows.map((t) => ({ id: t.id, name: t.name, abilities: t.abilities || ['*'], last_used_at: t.last_used_at, created_at: t.created_at })) }
+  }
+
+  // POST /api/user/tokens  { name, abilities: ['read'] } → the token, shown this one time only
+  async store(req) {
+    if (req.accessToken && req.accessToken.type !== 'session' && !req.accessToken.can('*')) abort(403, 'Only browser sessions may create API tokens.')
+    const data = await req.validate({ name: 'required|string|max:100', abilities: 'sometimes|array' })
+    const abilities = (data.abilities || ['read']).filter((a) => ABILITIES.includes(a))
+    if (!abilities.length) abort(422, 'Choose at least one permission.')
+    const { accessToken, plainTextToken } = await req.user.createToken(data.name, { type: 'api', abilities })
+    return response({ id: accessToken.id, name: accessToken.name, abilities, token: plainTextToken }, 201)
+  }
+
+  // PUT /api/user/tokens/{id}  { abilities }
+  async update(req, id) {
+    if (req.accessToken && req.accessToken.type !== 'session' && !req.accessToken.can('*')) abort(403, 'Only browser sessions may update API tokens.')
+    const token = await PersonalAccessToken.where('user_id', req.user.id).where('type', 'api').find(id)
+    if (!token) abort(404, 'No such token.')
+    const { abilities } = await req.validate({ abilities: 'required|array' })
+    token.abilities = abilities.filter((a) => ABILITIES.includes(a))
+    await token.save()
+    return { id: token.id, abilities: token.abilities }
+  }
+
+  // DELETE /api/user/tokens/{id}
+  async destroy(req, id) {
+    if (req.accessToken && req.accessToken.type !== 'session' && !req.accessToken.can('*')) abort(403, 'Only browser sessions may delete API tokens.')
+    const token = await PersonalAccessToken.where('user_id', req.user.id).where('type', 'api').find(id)
+    if (!token) abort(404, 'No such token.')
+    await token.delete()
+    return noContent()
+  }
+}
+
+module.exports = ApiTokenController

package/templates/app/backend/app/Http/Controllers/Auth/AuthenticatedSessionController.js

@@ -0,0 +1,41 @@
+const { Hash, ValidationError, noContent, abort } = require('kreftjs/server')
+const User = require('../../../Models/User')
+const Throttle = require('../../../Auth/Throttle')
+
+const MAX_FAILURES = Number(process.env.LOGIN_MAX_FAILURES || 10) // wrong passwords per account ...
+const WINDOW_SECONDS = Number(process.env.LOGIN_WINDOW_SECONDS || 900) // ... in this many seconds
+const LoginRequest = require('../../Requests/Auth/LoginRequest')
+const { signIn, signOut, pendingTwoFactor } = require('../../../Auth/Session')
+
+class AuthenticatedSessionController {
+  // POST /api/login  { email, password, remember }   (pages/auth/Login.kreftjs)
+  // with two-factor on, the answer is { two_factor: true } and the code goes to /api/two-factor-challenge
+  async store(req) {
+    const data = await LoginRequest.validate(req)
+    const email = data.email.toLowerCase()
+    // per account, whatever the address: guessing from many addresses at once stops here (known or not, same count)
+    const locked = await Throttle.wait('login', email, MAX_FAILURES)
+    if (locked) abort(429, 'Too many failed attempts. Try again later.', { headers: { 'Retry-After': String(locked) } })
+    const user = await User.where('email', email).first()
+    if (!user) {
+      Hash.dummyCheck(data.password)
+      await Throttle.hit('login', email, WINDOW_SECONDS)
+      throw new ValidationError({ email: ['These credentials do not match our records.'] })
+    }
+    if (!Hash.check(data.password, user.password)) {
+      await Throttle.hit('login', email, WINDOW_SECONDS)
+      throw new ValidationError({ email: ['These credentials do not match our records.'] })
+    }
+    await Throttle.clear('login', email)
+    if (user.hasTwoFactor()) return pendingTwoFactor(req, user, req.boolean('remember'))
+    return signIn(req, user, { remember: req.boolean('remember') })
+  }
+
+  // POST /api/logout: this device's login stops working
+  async destroy(req) {
+    await req.accessToken.delete()
+    return signOut(noContent())
+  }
+}
+
+module.exports = AuthenticatedSessionController

package/templates/app/backend/app/Http/Controllers/Auth/ConfirmablePasswordController.js

@@ -0,0 +1,14 @@
+const { Hash, ValidationError } = require('kreftjs/server')
+
+class ConfirmablePasswordController {
+  // POST /api/confirm-password   (pages/auth/ConfirmPassword.kreftjs): opens 'password.confirm' routes for 3 hours
+  async store(req) {
+    const { password } = await req.validate({ password: 'required' })
+    if (!Hash.check(password, req.user.password)) throw new ValidationError({ password: ['The password is incorrect.'] })
+    req.accessToken.password_confirmed_at = new Date()
+    await req.accessToken.save()
+    return { confirmed: true }
+  }
+}
+
+module.exports = ConfirmablePasswordController

package/templates/app/backend/app/Http/Controllers/Auth/EmailVerificationController.js

@@ -0,0 +1,23 @@
+const { Hash, Url, abort, same } = require('kreftjs/server')
+const User = require('../../../Models/User')
+
+class EmailVerificationController {
+  // POST /api/email/verification-notification: send the link again (pages/auth/VerifyEmail.kreftjs)
+  async send(req) {
+    if (req.user.hasVerifiedEmail()) return { message: 'Your email address is already verified.' }
+    await req.user.sendEmailVerificationNotification()
+    return { message: 'A new verification link has been sent to your email address.' }
+  }
+
+  // POST /api/email/verify  { id, hash, expires, signature }: the link from the email was opened
+  async verify(req) {
+    const { id, hash, expires, signature } = req.all()
+    if (!Url.check(`/verify-email/${id}/${hash}`, { expires, signature })) abort(403, 'This link is not valid any more. Ask for a new one.')
+    const user = await User.findOrFail(id)
+    if (!same(String(hash || ''), Hash.sha256(user.email))) abort(403, 'This link is not valid any more. Ask for a new one.')
+    if (!user.hasVerifiedEmail()) await user.markEmailAsVerified()
+    return { message: 'Your email address is verified.', user: { id: user.id, email_verified_at: user.email_verified_at } }
+  }
+}
+
+module.exports = EmailVerificationController