@shaferllc/keel 0.81.2 → 0.83.0

package/llms.txt

@@ -46,9 +46,11 @@ Userland imports everything from `@shaferllc/keel/core`.
 - [Models](https://github.com/shaferllc/keel/blob/main/docs/models.md): Model is a tiny active-record layer over the query builder.
 - [Notifications](https://github.com/shaferllc/keel/blob/main/docs/notifications.md): Send a message to a recipient over one or more channels — mail, database, or your own — inline or through the queue.
 - [OpenAPI](https://github.com/shaferllc/keel/blob/main/docs/openapi.md): Keel OpenAPI generates an OpenAPI 3 spec from your routes and serves Swagger UI to explore it.
+- [ORM](https://github.com/shaferllc/keel/blob/main/docs/orm.md): Keel's ORM is a compact active record over the query builder: a model is a class pointed at a table, and its rows come back as typed objects with methods.
 - [Packages](https://github.com/shaferllc/keel/blob/main/docs/packages.md): A package is a redistributable slice of a Keel app — routes, a UI, config, migrations, console commands — that installs with a single app.register(...).
 - [Pages](https://github.com/shaferllc/keel/blob/main/docs/pages.md): Page-based routing — a file is a route.
 - [Service Providers](https://github.com/shaferllc/keel/blob/main/docs/providers.md): Service providers are the central place to configure your application.
+- [Query Builder](https://github.com/shaferllc/keel/blob/main/docs/query-builder.md): Keel's driver-agnostic query builder — build and run SQL by chaining methods off db(table).
 - [Queues & Jobs](https://github.com/shaferllc/keel/blob/main/docs/queues.md): Move slow work — sending mail, calling an API, processing an upload — off the request path.
 - [Rate Limiting](https://github.com/shaferllc/keel/blob/main/docs/rate-limiting.md): rateLimiter() is a middleware that caps how many requests a client can make in a window.
 - [Redis](https://github.com/shaferllc/keel/blob/main/docs/redis.md): A Redis integration built on a small pluggable driver — like the database and mail layers, the core imports no client, so it runs on Node and on the edge.
@@ -58,6 +60,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 - [Securing SSR apps](https://github.com/shaferllc/keel/blob/main/docs/security.md): Two middlewares harden server-rendered apps: securityHeaders() sets the defensive HTTP headers browsers act on, and csrf() blocks cross-site form submissions.
 - [Sessions](https://github.com/shaferllc/keel/blob/main/docs/sessions.md): Keel ships a cookie-backed session store. There's no external service to run, so it works the same on Node and on the edge. Session data lives in an HTTP-only cookie: the middleware reads it before your handler runs and writes it back afterward.
 - [Social authentication](https://github.com/shaferllc/keel/blob/main/docs/social-auth.md): "Sign in with GitHub / Google / Discord" — OAuth 2.0, without an SDK.
+- [Starter kits](https://github.com/shaferllc/keel/blob/main/docs/starter-kits.md)
 - [Static Files](https://github.com/shaferllc/keel/blob/main/docs/static-files.md): serveStatic() serves files from a directory (default public/) before your routes run.
 - [Storage](https://github.com/shaferllc/keel/blob/main/docs/storage.md): File storage over a pluggable disk — like the database and mail layers, the core imports no filesystem or SDK, so it runs on Node and the edge.
 - [Teams](https://github.com/shaferllc/keel/blob/main/docs/teams.md): Multi-tenancy, membership, roles, and invitations — where a row belongs to a team, and one team can never see another's.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.81.2",
+  "version": "0.83.0",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",
@@ -37,6 +37,10 @@
       "types": "./dist/db/d1.d.ts",
       "import": "./dist/db/d1.js"
     },
+    "./db/d1-http": {
+      "types": "./dist/db/d1-http.d.ts",
+      "import": "./dist/db/d1-http.js"
+    },
     "./db/pg": {
       "types": "./dist/db/pg.d.ts",
       "import": "./dist/db/pg.js"
@@ -88,7 +92,8 @@
     "docs",
     "AGENTS.md",
     "llms.txt",
-    "llms-full.txt"
+    "llms-full.txt",
+    "templates"
   ],
   "publishConfig": {
     "access": "public"

package/templates/api/.env.example

@@ -0,0 +1,12 @@
+APP_NAME="Keel API"
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=http://localhost:3000
+APP_PORT=3000
+
+# Signs tokens and encrypted payloads. Generate one: keel key:generate
+APP_KEY=
+
+# A file is enough to start; point this at Postgres when you outgrow it.
+DB_CONNECTION=sqlite
+DB_URL=file:./database.sqlite

package/templates/api/app/Controllers/PostController.ts

@@ -0,0 +1,37 @@
+import type { Ctx } from "@shaferllc/keel/core";
+import { validate } from "@shaferllc/keel/core";
+import { z } from "zod";
+
+import { Post } from "../Models/Post.js";
+
+/** Keel doesn't ship a validator — anything with `safeParse` works. */
+const NewPost = z.object({
+  title: z.string().min(1),
+  body: z.string().default(""),
+});
+
+export class PostController {
+  async index(c: Ctx) {
+    return c.json(await Post.all());
+  }
+
+  async show(c: Ctx) {
+    // Throws a 404 on its own, so there's no null check to forget.
+    const post = await Post.findOrFail(Number(c.req.param("post")));
+    return c.json(post);
+  }
+
+  async store(c: Ctx) {
+    // A failed validation is a 422 with the field errors — you don't handle it here.
+    const data = await validate(NewPost, await c.req.json());
+
+    return c.json(await Post.create(data), 201);
+  }
+
+  async destroy(c: Ctx) {
+    const post = await Post.findOrFail(Number(c.req.param("post")));
+    await post.delete();
+
+    return c.body(null, 204);
+  }
+}

package/templates/api/app/Http/Kernel.ts

@@ -0,0 +1,13 @@
+import { HttpKernel } from "@shaferllc/keel/core";
+import type { Application } from "@shaferllc/keel/core";
+
+import { requestLogger } from "./Middleware/requestLogger.js";
+
+/** Global middleware — runs on every request, in order. */
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+
+    this.use(requestLogger);
+  }
+}

package/templates/api/app/Http/Middleware/requestLogger.ts

@@ -0,0 +1,8 @@
+import type { Ctx } from "@shaferllc/keel/core";
+
+/** Log every request with its status and how long it took. */
+export async function requestLogger(c: Ctx, next: () => Promise<void>): Promise<void> {
+  const started = Date.now();
+  await next();
+  console.log(`${c.req.method} ${c.req.path} ${c.res.status} ${Date.now() - started}ms`);
+}

package/templates/api/app/Models/Post.ts

@@ -0,0 +1,12 @@
+import { Model } from "@shaferllc/keel/core";
+
+export class Post extends Model {
+  static override table = "posts";
+  // An allowlist, so a request body can't set columns you didn't intend.
+  static override fillable = ["title", "body"];
+  static override timestamps = true;
+
+  declare id: number;
+  declare title: string;
+  declare body: string;
+}

package/templates/api/app/Providers/AppServiceProvider.ts

@@ -0,0 +1,8 @@
+import { ServiceProvider } from "@shaferllc/keel/core";
+
+/** Bind your own services here. */
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {}
+
+  boot(): void {}
+}

package/templates/api/app/Providers/DatabaseServiceProvider.ts

@@ -0,0 +1,52 @@
+import { ServiceProvider, config, setConnection } from "@shaferllc/keel/core";
+
+/**
+ * Opens the connection every model and query builder reads through — on **Node**.
+ * (In the Worker, worker.ts binds D1 directly and this provider isn't loaded.)
+ *
+ * Switching database is `DB_CONNECTION` and nothing else: no model or query changes,
+ * because they all talk to a `Connection` rather than to a driver.
+ *
+ * `d1` here means the HTTP API rather than the binding — which is what lets
+ * `keel migrate` reach your real D1 database from your laptop and from CI, where no
+ * binding exists.
+ */
+export class DatabaseServiceProvider extends ServiceProvider {
+  async register(): Promise<void> {
+    const name = config<string>("database.default", "sqlite");
+
+    if (name === "d1") {
+      const { d1HttpConnection } = await import("@shaferllc/keel/db/d1-http");
+
+      setConnection(
+        d1HttpConnection({
+          accountId: config<string>("database.connections.d1.accountId", ""),
+          databaseId: config<string>("database.connections.d1.databaseId", ""),
+          apiToken: config<string>("database.connections.d1.apiToken", ""),
+        }),
+        "sqlite",
+      );
+      return;
+    }
+
+    if (name === "postgres") {
+      const { pgConnection } = await import("@shaferllc/keel/db/pg");
+      const { Pool } = await import("pg");
+
+      setConnection(
+        pgConnection(new Pool({ connectionString: config<string>("database.connections.postgres.url", "") })),
+        "postgres",
+      );
+      return;
+    }
+
+    // sqlite (a local file) or turso (libSQL over the network) — same driver.
+    const { libsqlConnection } = await import("@shaferllc/keel/db/libsql");
+    const { createClient } = await import("@libsql/client");
+
+    const url = config<string>(`database.connections.${name}.url`, "file:./database.sqlite");
+    const authToken = config<string>(`database.connections.${name}.authToken`, "");
+
+    setConnection(libsqlConnection(createClient(authToken ? { url, authToken } : { url })), "sqlite");
+  }
+}

package/templates/api/bin/keel.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env tsx
+/**
+ * The application console. `npm run keel <command>`.
+ *
+ * The commands — serve, routes, repl, migrate:*, every make:* — come from the
+ * framework. This file only says how to build *your* application.
+ */
+import { run } from "@shaferllc/keel/cli";
+
+import { createApplication } from "../bootstrap/app.js";
+
+run(process.argv, { createApplication }).catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/templates/api/bootstrap/app.ts

@@ -0,0 +1,24 @@
+/**
+ * Application bootstrap. Creates the container, boots providers, loads routes.
+ * The server, the console, and the Worker all enter through here.
+ */
+
+import { Application, Router, HttpKernel, type ProviderClass } from "@shaferllc/keel/core";
+
+import { providers as nodeProviders } from "./providers.js";
+import { Kernel } from "../app/Http/Kernel.js";
+import registerWebRoutes from "../routes/web.js";
+
+export async function createApplication(providers: ProviderClass[] = nodeProviders): Promise<Application> {
+  const app = new Application(process.cwd());
+
+  // Binding our Kernel under HttpKernel is what makes `keel serve` use it. Without
+  // this the console falls back to a bare HttpKernel and the global middleware
+  // quietly vanishes.
+  app.singleton(HttpKernel, (container) => new Kernel(container as Application));
+
+  await app.boot(providers);
+  registerWebRoutes(app.make(Router));
+
+  return app;
+}

package/templates/api/bootstrap/providers.edge.ts

@@ -0,0 +1,14 @@
+import type { ProviderClass } from "@shaferllc/keel/core";
+
+import { AppServiceProvider } from "../app/Providers/AppServiceProvider.js";
+
+/**
+ * Providers for the Worker.
+ *
+ * `DatabaseServiceProvider` is deliberately absent, and that's not an optimization —
+ * it's what keeps the build working. It reaches for `pg` and `@libsql/client`, which
+ * need `net`/`tls`; if the Worker's import graph touched it, wrangler would try to
+ * bundle a TCP driver for the edge and fail. The D1 binding is wired in worker.ts
+ * before boot, so nothing here needs to open a connection.
+ */
+export const edgeProviders: ProviderClass[] = [AppServiceProvider];

package/templates/api/bootstrap/providers.ts

@@ -0,0 +1,7 @@
+import type { ProviderClass } from "@shaferllc/keel/core";
+
+import { AppServiceProvider } from "../app/Providers/AppServiceProvider.js";
+import { DatabaseServiceProvider } from "../app/Providers/DatabaseServiceProvider.js";
+
+/** Providers for the Node runtime (`keel serve`, the console, migrations). */
+export const providers: ProviderClass[] = [DatabaseServiceProvider, AppServiceProvider];

package/templates/api/config/app.ts

@@ -0,0 +1,10 @@
+import { env } from "@shaferllc/keel/core";
+
+export default {
+  name: env("APP_NAME", "Keel App"),
+  env: env("APP_ENV", "local"),
+  debug: env("APP_DEBUG", true),
+  url: env("APP_URL", "http://localhost:3000"),
+  port: env("APP_PORT", 3000),
+  key: env("APP_KEY", ""),
+};

package/templates/api/config/database.ts

@@ -0,0 +1,42 @@
+import { env } from "@shaferllc/keel/core";
+
+/**
+ * Every driver, out of the box. `DB_CONNECTION` picks one.
+ *
+ * The default is `d1` in production — Cloudflare is where this is meant to run —
+ * and `sqlite` locally, so `npm run dev` needs no wrangler and no account. Both are
+ * SQLite, so one schema and one set of migrations serve both.
+ */
+export default {
+  default: env("DB_CONNECTION", "sqlite"),
+
+  connections: {
+    // Cloudflare D1. Inside the Worker the binding (env.DB) is used directly;
+    // migrations and scripts reach the same database over the HTTP API.
+    d1: {
+      driver: "d1",
+      binding: "DB",
+      accountId: env("CLOUDFLARE_ACCOUNT_ID", ""),
+      databaseId: env("D1_DATABASE_ID", ""),
+      apiToken: env("CLOUDFLARE_API_TOKEN", ""),
+    },
+
+    // A local file. Zero setup — this is what `npm run dev` uses.
+    sqlite: {
+      driver: "libsql",
+      url: env("DB_URL", "file:./database.sqlite"),
+    },
+
+    // libSQL over the network (Turso).
+    turso: {
+      driver: "libsql",
+      url: env("TURSO_URL", ""),
+      authToken: env("TURSO_AUTH_TOKEN", ""),
+    },
+
+    postgres: {
+      driver: "pg",
+      url: env("DATABASE_URL", ""),
+    },
+  },
+};

package/templates/api/database/migrations/0001_create_posts.ts

@@ -0,0 +1,20 @@
+import type { Migration } from "@shaferllc/keel/core";
+
+const migration: Migration = {
+  name: "0001_create_posts",
+
+  async up(schema) {
+    await schema.createTable("posts", (t) => {
+      t.id();
+      t.string("title");
+      t.text("body");
+      t.timestamps();
+    });
+  },
+
+  async down(schema) {
+    await schema.dropTable("posts");
+  },
+};
+
+export default migration;

package/templates/api/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "keel": "tsx bin/keel.ts",
+    "dev": "tsx watch bin/keel.ts serve",
+    "serve": "tsx bin/keel.ts serve",
+    "migrate": "tsx bin/keel.ts migrate",
+    "test": "tsx --test --test-concurrency=1 tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "dev:edge": "wrangler dev",
+    "deploy": "wrangler deploy"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.7",
+    "@libsql/client": "^0.14.0",
+    "@shaferllc/keel": "__KEEL_VERSION__",
+    "hono": "^4.6.14",
+    "zod": "^3.24.1",
+    "pg": "^8.13.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "wrangler": "^4.0.0",
+    "@types/pg": "^8.11.10"
+  }
+}

package/templates/api/routes/web.ts

@@ -0,0 +1,12 @@
+import type { Router, Ctx } from "@shaferllc/keel/core";
+
+import { PostController } from "../app/Controllers/PostController.js";
+
+export default function routes(router: Router): void {
+  router.get("/health", (c: Ctx) => c.json({ ok: true }));
+
+  router.get("/posts", [PostController, "index"]).name("posts.index");
+  router.post("/posts", [PostController, "store"]).name("posts.store");
+  router.get("/posts/:post", [PostController, "show"]).name("posts.show");
+  router.delete("/posts/:post", [PostController, "destroy"]).name("posts.destroy");
+}

package/templates/api/tests/posts.test.ts

@@ -0,0 +1,30 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { testClient } from "@shaferllc/keel/core";
+import { HttpKernel } from "@shaferllc/keel/core";
+
+import { createApplication } from "../bootstrap/app.js";
+
+/**
+ * A starter that ships no tests teaches that tests are optional. This one hits the
+ * real routes through the real kernel — no mocks, no server, no port.
+ */
+test("the API lists, creates, and fetches posts", async () => {
+  const app = await createApplication();
+  const client = testClient(app.make(HttpKernel));
+
+  (await client.get("/health")).assertOk().assertJson({ ok: true });
+
+  const created = await client.post("/posts", { title: "Hello", body: "First." });
+  created.assertCreated();
+
+  (await client.get("/posts")).assertOk();
+});
+
+test("a post that doesn't exist is a 404", async () => {
+  const app = await createApplication();
+  const client = testClient(app.make(HttpKernel));
+
+  (await client.get("/posts/999999")).assertNotFound();
+});

package/templates/api/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true
+  },
+  "include": ["app", "bootstrap", "config", "routes", "database", "bin", "tests"]
+}

package/templates/api/worker.ts

@@ -0,0 +1,33 @@
+/**
+ * The Cloudflare Workers entry. `wrangler dev` / `wrangler deploy` use this.
+ *
+ * D1's binding only exists inside a request, so the connection is wired here, before
+ * the app boots — and the app is built once, then reused.
+ *
+ * Note the provider list: `edgeProviders`, not the Node one. See providers.edge.ts.
+ */
+
+import { setConnection, HttpKernel } from "@shaferllc/keel/core";
+import { d1Connection, type D1Like } from "@shaferllc/keel/db/d1";
+
+import { createApplication } from "./bootstrap/app.js";
+import { edgeProviders } from "./bootstrap/providers.edge.js";
+
+interface Env {
+  DB: D1Like;
+}
+
+let handler: { fetch: (request: Request, env: unknown) => Response | Promise<Response> } | undefined;
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (!handler) {
+      setConnection(d1Connection(env.DB), "sqlite");
+
+      const app = await createApplication(edgeProviders);
+      handler = app.make(HttpKernel).build();
+    }
+
+    return handler.fetch(request, env);
+  },
+};

package/templates/api/wrangler.jsonc

@@ -0,0 +1,22 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "__APP_NAME__",
+  "main": "worker.ts",
+  "compatibility_date": "2025-01-01",
+  // AsyncLocalStorage — Keel carries the request, the open transaction, and the
+  // current team in it. Without this flag they have nowhere to live.
+  "compatibility_flags": ["nodejs_compat"],
+
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "__APP_NAME__",
+      // Create one: wrangler d1 create __APP_NAME__ — then paste the id here.
+      "database_id": ""
+    }
+  ],
+
+  "vars": {
+    "DB_CONNECTION": "d1"
+  }
+}

package/templates/app/.env.example

@@ -0,0 +1,12 @@
+APP_NAME="Keel API"
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=http://localhost:3000
+APP_PORT=3000
+
+# Signs tokens and encrypted payloads. Generate one: keel key:generate
+APP_KEY=
+
+# A file is enough to start; point this at Postgres when you outgrow it.
+DB_CONNECTION=sqlite
+DB_URL=file:./database.sqlite

package/templates/app/app/Controllers/AuthController.ts

@@ -0,0 +1,117 @@
+import type { Ctx } from "@shaferllc/keel/core";
+import { auth, hash, session, validate, view } from "@shaferllc/keel/core";
+import { attempt, completeTwoFactor, requestPasswordReset, resetPassword } from "@shaferllc/keel/accounts";
+import { z } from "zod";
+
+import { User } from "../Models/User.js";
+import Login from "../../resources/views/auth/login.js";
+import Register from "../../resources/views/auth/register.js";
+import TwoFactor from "../../resources/views/auth/two-factor.js";
+import Forgot from "../../resources/views/auth/forgot.js";
+
+const Credentials = z.object({
+  email: z.string().email(),
+  password: z.string().min(1),
+});
+
+const NewUser = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+export class AuthController {
+  async showLogin(c: Ctx) {
+    return c.html(await view(Login, { error: null }));
+  }
+
+  async login(c: Ctx) {
+    const { email, password } = await validate(Credentials, await c.req.parseBody());
+
+    const result = await attempt(email, password);
+
+    if (result.status === "failed") {
+      // One message for a wrong email and a wrong password — anything more specific
+      // tells a stranger which addresses have accounts here.
+      return c.html(await view(Login, { error: "Those credentials don't match." }), 401);
+    }
+
+    if (result.status === "two-factor") {
+      // NOT a session. Nothing is logged in until the code checks out.
+      session().put("2fa_challenge", result.challenge);
+      return c.redirect("/two-factor");
+    }
+
+    auth().login(result.user.id);
+    return c.redirect("/dashboard");
+  }
+
+  async showTwoFactor(c: Ctx) {
+    return c.html(await view(TwoFactor, { error: null }));
+  }
+
+  async twoFactor(c: Ctx) {
+    const body = await c.req.parseBody();
+    const challenge = session().get("2fa_challenge") as string | undefined;
+
+    if (!challenge) return c.redirect("/login");
+
+    const user = await completeTwoFactor(challenge, String(body.code ?? ""));
+
+    if (!user) {
+      return c.html(await view(TwoFactor, { error: "That code isn't valid." }), 401);
+    }
+
+    session().forget("2fa_challenge");
+    auth().login(user.id);
+
+    return c.redirect("/dashboard");
+  }
+
+  async showRegister(c: Ctx) {
+    return c.html(await view(Register, { error: null }));
+  }
+
+  async register(c: Ctx) {
+    const data = await validate(NewUser, await c.req.parseBody());
+
+    if (await User.query().where("email", data.email.toLowerCase()).first()) {
+      return c.html(await view(Register, { error: "That email is already registered." }), 422);
+    }
+
+    const user = await User.create({
+      name: data.name,
+      email: data.email.toLowerCase(),
+      password: await hash.make(data.password),
+    });
+
+    auth().login(user.id);
+    return c.redirect("/dashboard");
+  }
+
+  logout(c: Ctx) {
+    auth().logout();
+    return c.redirect("/");
+  }
+
+  async showForgot(c: Ctx) {
+    return c.html(await view(Forgot, { sent: false }));
+  }
+
+  async forgot(c: Ctx) {
+    const body = await c.req.parseBody();
+    await requestPasswordReset(String(body.email ?? ""));
+
+    // The same answer whether or not that address has an account.
+    return c.html(await view(Forgot, { sent: true }));
+  }
+
+  async reset(c: Ctx) {
+    const body = await c.req.parseBody();
+
+    const ok = await resetPassword(String(body.token ?? ""), String(body.password ?? ""));
+    if (!ok) return c.text("That reset link is invalid or has expired.", 422);
+
+    return c.redirect("/login");
+  }
+}

package/templates/app/app/Controllers/DashboardController.ts

@@ -0,0 +1,37 @@
+import type { Ctx } from "@shaferllc/keel/core";
+import { auth, view } from "@shaferllc/keel/core";
+import { enableTwoFactor, hasTwoFactor } from "@shaferllc/keel/accounts";
+
+import type { User } from "../Models/User.js";
+import Dashboard from "../../resources/views/dashboard.js";
+
+export class DashboardController {
+  async index(c: Ctx) {
+    const user = await auth().user<User>();
+    if (!user) return c.redirect("/login");
+
+    return c.html(
+      await view(Dashboard, {
+        name: user.name,
+        twoFactor: hasTwoFactor(user as never),
+      }),
+    );
+  }
+
+  /** Step one of turning 2FA on: a secret and recovery codes. It is NOT on yet. */
+  async startTwoFactor(c: Ctx) {
+    const user = await auth().user<User>();
+    if (!user) return c.redirect("/login");
+
+    const setup = await enableTwoFactor(user as never, { issuer: "Keel App" });
+
+    // Render setup.uri to a QR code locally — it contains the shared secret, so it
+    // must never be sent to a third-party QR service.
+    return c.json({
+      uri: setup.uri,
+      secret: setup.secret,
+      recoveryCodes: setup.recoveryCodes,
+      next: "POST /two-factor/confirm with a code from your authenticator to turn it on.",
+    });
+  }
+}