@glinr/create-theauth-app 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheAuth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @glinr/create-theauth-app
+
+Scaffold a TheAuth app in one command.
+
+```bash
+npm create theauth-app@latest
+# or
+pnpm create theauth-app
+# or
+yarn create theauth-app
+# or
+bunx @glinr/create-theauth-app
+```
+
+You'll be asked for a project directory, a template, and a database driver. The CLI then writes the project, installs deps, and prints the next commands to run.
+
+## Templates
+
+| Template | Status | Stack |
+| --- | --- | --- |
+| `next-saas` | available | Next.js App Router · Drizzle · TheAuth auth |
+| `hono-mcp` | available | Hono server · MCP OAuth 2.1 |
+| `expo-mobile` | coming soon | Expo Router · React Native |
+
+## Database drivers
+
+- `better-sqlite3` (default): local SQLite, zero setup
+- `pg`: Postgres (you provide the connection string)
+
+## What you get
+
+A working Next.js app with:
+
+- `createKavach` already wired in `lib/auth.ts`
+- Drizzle schema and migrations for the auth tables
+- Sign-in / sign-up routes using the prebuilt React components
+- `.env.example` with the secrets you need to fill in
+
+## Next steps
+
+```bash
+cd my-theauth-app
+pnpm install
+cp .env.example .env       # then set THEAUTH_SECRET
+pnpm db:push
+pnpm dev
+```
+
+## Links
+
+- TheAuth repo: <https://github.com/glincker/theauth>
+- Docs: <https://docs.theauth.com>
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+import {
+  main
+} from "./chunk-Z6TQPZQK.js";
+
+// src/bin.ts
+main().catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/dist/chunk-Z6TQPZQK.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { basename, resolve } from "path";
+import { exit } from "process";
+import * as p from "@clack/prompts";
+import { bold, green, yellow } from "kolorist";
+
+// src/scaffold.ts
+import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var DB_PACKAGE_VERSION = {
+  "better-sqlite3": "^11.0.0",
+  pg: "^8.13.0"
+};
+function replacePlaceholders(content, appName, dbDriver, dbUrl) {
+  const dbPkgVersion = DB_PACKAGE_VERSION[dbDriver] ?? "*";
+  return content.replaceAll("__APP_NAME__", appName).replaceAll("__DB_DRIVER__", dbDriver).replaceAll("__DB_DRIVER_VERSION__", dbPkgVersion).replaceAll("__DB_URL__", dbUrl);
+}
+function mapFilename(name) {
+  if (name === "_gitignore") return ".gitignore";
+  return name;
+}
+async function copyDir(src, dest, appName, dbDriver, dbUrl) {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destName = mapFilename(replacePlaceholders(entry.name, appName, dbDriver, dbUrl));
+    const destPath = join(dest, destName);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath, appName, dbDriver, dbUrl);
+    } else {
+      const raw = await readFile(srcPath, "utf-8");
+      const processed = replacePlaceholders(raw, appName, dbDriver, dbUrl);
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, processed, "utf-8");
+    }
+  }
+}
+async function scaffold(opts) {
+  const templatesDir = join(__dirname, "..", "templates");
+  const templateSrc = join(templatesDir, opts.template);
+  const templateStat = await stat(templateSrc).catch(() => null);
+  if (!templateStat?.isDirectory()) {
+    throw new Error(`Template "${opts.template}" not found at ${templateSrc}`);
+  }
+  await copyDir(templateSrc, opts.targetDir, opts.appName, opts.dbDriver, opts.dbUrl);
+}
+
+// src/index.ts
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent ?? "";
+  if (ua.startsWith("pnpm")) return "pnpm";
+  if (ua.startsWith("yarn")) return "yarn";
+  if (ua.startsWith("bun")) return "bun";
+  return "npm";
+}
+function defaultDbUrl(driver) {
+  if (driver === "better-sqlite3") return "file:./kavach.db";
+  return "";
+}
+function printBanner() {
+  p.intro(`${bold(green("TheAuth"))} ${green("\xB7")} Auth OS for AI agents`);
+}
+function printNextSteps(targetDir, pm, template) {
+  const rel = targetDir.startsWith(process.cwd()) ? targetDir.slice(process.cwd().length + 1) : targetDir;
+  const runCmd = pm === "npm" ? "npm run" : pm;
+  const steps = [
+    `cd ${rel}`,
+    `${pm} install`,
+    `cp .env.example .env   # then fill in THEAUTH_SECRET`
+  ];
+  if (template === "next-saas") {
+    steps.push(`${runCmd} db:push`);
+  }
+  steps.push(`${runCmd} dev`);
+  p.note(steps.join("\n"), "Next steps");
+  p.outro(`${bold(green("Done."))} Happy building.`);
+}
+async function main() {
+  printBanner();
+  const answers = await p.group(
+    {
+      targetDir: () => p.text({
+        message: "Project directory",
+        placeholder: "./my-theauth-app",
+        defaultValue: "./my-theauth-app",
+        validate(value) {
+          if (!value || value.trim() === "") return "Directory is required";
+          return void 0;
+        }
+      }),
+      template: () => p.select({
+        message: "Template",
+        options: [
+          {
+            value: "next-saas",
+            label: "Next.js SaaS",
+            hint: "App Router \xB7 Drizzle \xB7 TheAuth auth"
+          },
+          {
+            value: "hono-mcp",
+            label: "Hono MCP",
+            hint: "Hono server \xB7 MCP OAuth 2.1"
+          },
+          {
+            value: "expo-mobile",
+            label: `Expo mobile  ${yellow("(coming soon)")}`,
+            hint: "React Native \xB7 Expo Router"
+          }
+        ]
+      }),
+      packageManager: () => p.select({
+        message: "Package manager",
+        initialValue: detectPackageManager(),
+        options: [
+          { value: "pnpm", label: "pnpm" },
+          { value: "npm", label: "npm" },
+          { value: "yarn", label: "yarn" },
+          { value: "bun", label: "bun" }
+        ]
+      }),
+      dbDriver: () => p.select({
+        message: "Database",
+        options: [
+          { value: "better-sqlite3", label: "SQLite", hint: "local \xB7 zero config" },
+          { value: "pg", label: "Postgres", hint: "pg driver \xB7 set DATABASE_URL" }
+        ]
+      })
+    },
+    {
+      onCancel() {
+        p.cancel("Cancelled.");
+        exit(0);
+      }
+    }
+  );
+  const template = answers.template;
+  if (template === "expo-mobile") {
+    p.note(
+      `The ${bold(template)} template is not ready yet.
+Pick ${bold("next-saas")} or ${bold("hono-mcp")} for now and stay tuned.`,
+      yellow("Coming soon")
+    );
+    exit(0);
+  }
+  const targetDir = resolve(answers.targetDir);
+  const appName = basename(targetDir);
+  const dbDriver = answers.dbDriver;
+  const dbUrl = defaultDbUrl(dbDriver);
+  const pm = answers.packageManager;
+  const spinner2 = p.spinner();
+  spinner2.start("Scaffolding project");
+  try {
+    await scaffold({ targetDir, template, appName, dbDriver, dbUrl });
+    spinner2.stop("Project created");
+  } catch (err) {
+    spinner2.stop("Scaffold failed");
+    p.log.error(err instanceof Error ? err.message : String(err));
+    exit(1);
+  }
+  printNextSteps(targetDir, pm, template);
+}
+
+export {
+  main
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+declare function main(): Promise<void>;
+
+export { main };

package/dist/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import {
+  main
+} from "./chunk-Z6TQPZQK.js";
+export {
+  main
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@glinr/create-theauth-app",
+  "version": "0.2.0",
+  "description": "Scaffold a TheAuth-powered app in seconds",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/glincker/theauth.git",
+    "directory": "packages/create-theauth-app"
+  },
+  "homepage": "https://theauth.com",
+  "keywords": [
+    "theauth",
+    "auth",
+    "agent",
+    "mcp",
+    "scaffold",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-theauth-app": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "kolorist": "^1.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^6.0.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/bin.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/bin.ts --format esm --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/templates/hono-mcp/.env.example

@@ -0,0 +1,21 @@
+# Long random string used to sign sessions and access tokens. Generate one with:
+#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+THEAUTH_SECRET=
+
+# Signing secret for MCP JWT access tokens. Must be at least 32 chars.
+MCP_SIGNING_SECRET=change-me-to-a-real-secret-at-least-32-chars
+
+# Database driver. Set to "postgres" to use Postgres instead of local SQLite.
+DB_PROVIDER=sqlite
+
+# Database URL. Defaults match DB_PROVIDER.
+# SQLite:   file:./kavach.db
+# Postgres: postgres://user:pass@host:5432/dbname
+DATABASE_URL=__DB_URL__
+
+# Base URL the server is reachable at. Appears in .well-known documents and
+# access-token claims. Change to your public URL before deploying.
+BASE_URL=http://localhost:3001
+
+# Port to listen on.
+PORT=3001

package/templates/hono-mcp/README.md

@@ -0,0 +1,76 @@
+# __APP_NAME__
+
+A Hono server scaffolded with [TheAuth](https://theauth.com). Runs as an MCP OAuth 2.1 authorization server and a resource server in one process.
+
+## What's included
+
+- **Hono 4** on Node.js
+- **TheAuth** for agent identity, session management, and the MCP OAuth 2.1 stack
+- **Drizzle ORM** with __DB_DRIVER__ backing the auth schema
+- `GET /tools/list` and `POST /tools/call/:name` protected with `withMcpAuth`
+- `.well-known` discovery documents for MCP clients, served at the root
+
+## Getting started
+
+```bash
+cp .env.example .env
+# Edit .env: set THEAUTH_SECRET to a 32+ byte random hex string
+
+pnpm install
+pnpm run dev
+```
+
+TheAuth creates the auth tables on first boot, no separate migration step for SQLite or Postgres.
+
+The server listens on `http://localhost:3001`. Visit the root URL to see the MCP discovery links and the list of tools.
+
+## Smoke test without an MCP client
+
+```bash
+# 1. Create an agent with scoped MCP permissions
+curl -X POST http://localhost:3001/api/agents \
+  -H "Content-Type: application/json" \
+  -d '{
+    "ownerId": "user-1",
+    "name": "demo-agent",
+    "type": "autonomous",
+    "permissions": [
+      { "resource": "mcp:*", "actions": ["read", "execute"] }
+    ]
+  }'
+
+# Copy the kv_... token from the response, then call the protected route:
+curl http://localhost:3001/tools/list \
+  -H "Authorization: Bearer kv_YOUR_TOKEN"
+```
+
+## Environment variables
+
+| Variable          | Required | Notes                                                                      |
+|-------------------|----------|----------------------------------------------------------------------------|
+| `THEAUTH_SECRET` | Yes      | Long random string. Signs sessions and access tokens.                      |
+| `DATABASE_URL`    | Yes      | SQLite: `file:./kavach.db`. Postgres: `postgres://user:pass@host:5432/db`. |
+| `BASE_URL`        | No       | Public URL this server is reachable at. Defaults to `http://localhost:3001`. Set it before deploying so the `.well-known` documents and access-token audience match what clients use. |
+| `PORT`            | No       | Port to bind. Defaults to `3001`.                                           |
+
+## Project structure
+
+```
+src/
+  server.ts            Hono app, MCP mount, protected tool routes
+  tools.ts             Example MCP tool list
+  lib/
+    kavach.ts          Lazy createKavach singleton
+```
+
+## Deploying
+
+Any Node runtime works. Set `BASE_URL` to your public URL before boot so MCP clients find the right endpoints, and set a real `THEAUTH_SECRET` out of band.
+
+If you switch to Postgres, set `DB_PROVIDER=postgres` and point `DATABASE_URL` at your connection string. TheAuth creates the tables on boot.
+
+## Next
+
+- Replace the example tools in `src/tools.ts` with real implementations.
+- Add per-tool permission constraints to the agents you create (rate limits, approval gates, IP allowlists) so agents cannot over-reach.
+- Drop a frontend alongside this API, or consume it from any MCP-aware client.

package/templates/hono-mcp/_gitignore

@@ -0,0 +1,8 @@
+node_modules
+.env
+*.db
+*.db-shm
+*.db-wal
+.turbo
+dist
+drizzle

package/templates/hono-mcp/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "start": "tsx src/server.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.0",
+    "@glinr/theauth-hono": "^3.0.0",
+    "__DB_DRIVER__": "__DB_DRIVER_VERSION__",
+    "hono": "^4.12.0",
+    "@glinr/theauth": "^0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/hono-mcp/src/lib/kavach.ts

@@ -0,0 +1,27 @@
+import { createKavach } from "@glinr/theauth";
+
+// Lazy singleton so imports do not open a DB connection before config is
+// loaded. createKavach auto-creates the auth tables on first boot, no
+// migration step required for development.
+let instance: Awaited<ReturnType<typeof createKavach>> | null = null;
+
+export async function getKavach() {
+	if (!instance) {
+		const provider = process.env["DB_PROVIDER"] === "postgres" ? "postgres" : "sqlite";
+		instance = await createKavach({
+			database: {
+				provider,
+				url: process.env["DATABASE_URL"] ?? "file:./kavach.db",
+			},
+			secret: process.env["THEAUTH_SECRET"] ?? "dev-secret-change-me-in-prod",
+			agents: {
+				enabled: true,
+				maxPerUser: 50,
+				defaultPermissions: [],
+				auditAll: true,
+				tokenExpiry: "24h",
+			},
+		});
+	}
+	return instance;
+}

package/templates/hono-mcp/src/server.ts

@@ -0,0 +1,192 @@
+// __APP_NAME__
+//
+// A Hono server that runs as an MCP OAuth 2.1 authorization server and a
+// resource server protecting your tools behind agent bearer tokens.
+//
+// Dev:    pnpm dev
+// Start:  pnpm start
+//
+// Smoke test with a kv_ agent token (no full OAuth flow needed):
+//   curl -X POST http://localhost:3001/api/agents \
+//     -H "Content-Type: application/json" \
+//     -d '{"ownerId":"user-1","name":"demo","type":"autonomous",
+//          "permissions":[{"resource":"mcp:*","actions":["read","execute"]}]}'
+//
+//   # Use the returned kv_ token to call the protected endpoint:
+//   curl http://localhost:3001/tools/list -H "Authorization: Bearer kv_..."
+
+import { serve } from "@hono/node-server";
+import { kavachHono } from "@glinr/theauth-hono";
+import { Hono } from "hono";
+import { users } from "@glinr/theauth";
+import type { McpAccessToken, McpAuthModule, McpAuthorizationCode, McpClient } from "@glinr/theauth/mcp";
+import { createMcpModule } from "@glinr/theauth/mcp";
+
+import { getKavach } from "./lib/kavach.js";
+import { MCP_TOOLS } from "./tools.js";
+
+const PORT = Number(process.env["PORT"] ?? 3001);
+const BASE_URL = process.env["BASE_URL"] ?? `http://localhost:${PORT}`;
+const SIGNING_SECRET =
+	process.env["MCP_SIGNING_SECRET"] ?? "dev-mcp-signing-secret-at-least-32-chars-ok";
+
+// In-memory MCP stores. In production, back these with your database or a
+// cache layer. These are here so the scaffolded template boots without extra
+// setup.
+const clients = new Map<string, McpClient>();
+const authCodes = new Map<string, McpAuthorizationCode>();
+const tokens = new Map<string, McpAccessToken>();
+const refreshTokenIndex = new Map<string, string>();
+
+async function main(): Promise<void> {
+	const kavach = await getKavach();
+
+	// Seed a demo user so the /api/agents call in the smoke test has an owner.
+	try {
+		kavach.db
+			.insert(users)
+			.values({
+				id: "user-1",
+				email: "demo@__APP_NAME__.local",
+				name: "Demo User",
+				createdAt: new Date(),
+				updatedAt: new Date(),
+			})
+			.run();
+	} catch {
+		// Ignore on restart when the row already exists.
+	}
+
+	const mcp: McpAuthModule = createMcpModule({
+		config: {
+			enabled: true,
+			issuer: BASE_URL,
+			baseUrl: `${BASE_URL}/api`,
+			signingSecret: SIGNING_SECRET,
+			scopes: ["mcp:read", "mcp:execute", "mcp:write"],
+			accessTokenTtl: 3600,
+			refreshTokenTtl: 86400,
+		},
+		storeClient: async (client) => {
+			clients.set(client.clientId, client);
+		},
+		findClient: async (clientId) => clients.get(clientId) ?? null,
+		storeAuthorizationCode: async (code) => {
+			authCodes.set(code.code, code);
+		},
+		consumeAuthorizationCode: async (code) => {
+			const found = authCodes.get(code) ?? null;
+			if (found) authCodes.delete(code);
+			return found;
+		},
+		storeToken: async (token) => {
+			tokens.set(token.accessToken, token);
+			if (token.refreshToken) {
+				refreshTokenIndex.set(token.refreshToken, token.accessToken);
+			}
+		},
+		findTokenByRefreshToken: async (refreshToken) => {
+			const at = refreshTokenIndex.get(refreshToken);
+			return at ? (tokens.get(at) ?? null) : null;
+		},
+		revokeToken: async (accessToken) => {
+			const token = tokens.get(accessToken);
+			if (token?.refreshToken) refreshTokenIndex.delete(token.refreshToken);
+			tokens.delete(accessToken);
+		},
+		// Replace this with a real session lookup in production.
+		resolveUserId: async () => "user-1",
+	});
+
+	const app = new Hono();
+
+	// Mount the full TheAuth API (agents, audit, delegation) plus the MCP
+	// OAuth endpoints (.well-known, /mcp/register, /mcp/authorize, /mcp/token).
+	app.route("/api", kavachHono(kavach, { mcp }));
+
+	// Protected tool list. Accepts either a kv_ agent token or an MCP JWT.
+	app.get("/tools/list", async (c) => {
+		const token = c.req.header("authorization")?.replace("Bearer ", "");
+		if (!token) return c.json({ error: "Missing Authorization header" }, 401);
+
+		if (token.startsWith("kv_")) {
+			const result = await kavach.authorizeByToken(token, {
+				action: "read",
+				resource: "mcp:tools:list",
+			});
+			if (!result.allowed) {
+				return c.json({ error: "Forbidden", reason: result.reason }, 403);
+			}
+		} else {
+			const result = await mcp.validateToken(token, ["mcp:read"]);
+			if (!result.success) return c.json({ error: result.error.message }, 401);
+		}
+
+		return c.json({ tools: MCP_TOOLS });
+	});
+
+	// Protected tool call.
+	app.post("/tools/call", async (c) => {
+		const token = c.req.header("authorization")?.replace("Bearer ", "");
+		if (!token) return c.json({ error: "Missing Authorization header" }, 401);
+
+		let body: { name?: string; arguments?: Record<string, unknown> };
+		try {
+			body = await c.req.json();
+		} catch {
+			return c.json({ error: "Invalid JSON body" }, 400);
+		}
+
+		const toolName = body.name;
+		if (!toolName) return c.json({ error: "Missing tool name" }, 400);
+		const tool = MCP_TOOLS.find((t) => t.name === toolName);
+		if (!tool) return c.json({ error: `Unknown tool: ${toolName}` }, 404);
+
+		if (token.startsWith("kv_")) {
+			const result = await kavach.authorizeByToken(token, {
+				action: "execute",
+				resource: `mcp:tools:${toolName}`,
+				arguments: body.arguments,
+			});
+			if (!result.allowed) {
+				return c.json({ error: "Forbidden", reason: result.reason }, 403);
+			}
+		} else {
+			const result = await mcp.validateToken(token, ["mcp:execute"]);
+			if (!result.success) return c.json({ error: result.error.message }, 401);
+		}
+
+		// Plug the real tool implementation in here.
+		return c.json({
+			content: [
+				{
+					type: "text",
+					text: `[simulated] ${toolName} called with args: ${JSON.stringify(body.arguments ?? {})}`,
+				},
+			],
+		});
+	});
+
+	app.get("/", (c) =>
+		c.json({
+			name: "__APP_NAME__",
+			mcp: {
+				authorization_server: `${BASE_URL}/.well-known/oauth-authorization-server`,
+				protected_resource: `${BASE_URL}/.well-known/oauth-protected-resource`,
+				register: `${BASE_URL}/api/mcp/register`,
+				authorize: `${BASE_URL}/api/mcp/authorize`,
+				token: `${BASE_URL}/api/mcp/token`,
+			},
+			tools: MCP_TOOLS.map((t) => t.name),
+		}),
+	);
+
+	serve({ fetch: app.fetch, port: PORT }, (info) => {
+		console.log(`__APP_NAME__ listening on http://localhost:${info.port}`);
+	});
+}
+
+main().catch((err: unknown) => {
+	console.error("Fatal error:", err);
+	process.exit(1);
+});

package/templates/hono-mcp/src/tools.ts

@@ -0,0 +1,35 @@
+// Example MCP tool definitions. Replace with the tools your server
+// actually wants to expose to AI agents. Each tool's name becomes the
+// last segment of the permission resource, for example `mcp:file:read`
+// maps to the `file:read` tool here.
+
+export interface Tool {
+	name: string;
+	description: string;
+	inputSchema: Record<string, unknown>;
+}
+
+export const MCP_TOOLS: Tool[] = [
+	{
+		name: "list_files",
+		description: "List files in a directory",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: { type: "string", description: "Directory path" },
+			},
+			required: ["path"],
+		},
+	},
+	{
+		name: "read_file",
+		description: "Read the contents of a file",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: { type: "string", description: "File path" },
+			},
+			required: ["path"],
+		},
+	},
+];

package/templates/hono-mcp/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/templates/next-saas/.env.example

@@ -0,0 +1,2 @@
+THEAUTH_SECRET=change-me-to-a-long-random-string
+DATABASE_URL=__DB_URL__

package/templates/next-saas/README.md

@@ -0,0 +1,50 @@
+# __APP_NAME__
+
+A Next.js SaaS starter with [TheAuth](https://theauth.com) auth built in.
+
+## What's included
+
+- **Next.js 15** with App Router and TypeScript
+- **TheAuth** for agent identity, session management, and auth
+- **Drizzle ORM** with **__DB_DRIVER__**: schema-first, type-safe
+- Sign-in / sign-out flow wired to `/api/auth/[...kavach]`
+- An agents list page at `/agents`
+
+## Getting started
+
+```bash
+cp .env.example .env
+# Edit .env: set THEAUTH_SECRET and DATABASE_URL
+
+pnpm install
+pnpm run db:push
+pnpm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Environment variables
+
+| Variable | Required | Notes |
+|---|---|---|
+| `THEAUTH_SECRET` | Yes | Long random string, used to sign sessions |
+| `DATABASE_URL` | Yes | SQLite: `file:./kavach.db` · Postgres: connection string |
+
+## Project structure
+
+```
+src/
+  app/
+    api/auth/[...kavach]/route.ts  : TheAuth HTTP handler
+    agents/page.tsx                : agent list UI
+    layout.tsx                     : KavachProvider wrapper
+    page.tsx                       : home / landing
+  lib/
+    kavach.ts                      : singleton TheAuth instance
+```
+
+## Deploying
+
+Any Node.js host works. For Vercel, add `THEAUTH_SECRET` and `DATABASE_URL` in project settings, then push.
+
+If you switch to Postgres, update `DATABASE_URL` and run `pnpm run db:push` to apply migrations.

package/templates/next-saas/_gitignore

@@ -0,0 +1,6 @@
+node_modules
+.next
+.env
+*.db
+.turbo
+dist

package/templates/next-saas/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+	dialect: "__DB_DRIVER__" === "pg" ? "postgresql" : "sqlite",
+	schema: "./src/lib/schema.ts",
+	out: "./drizzle",
+	dbCredentials: {
+		url: process.env["DATABASE_URL"] ?? "file:./kavach.db",
+	},
+});

package/templates/next-saas/next.config.mjs

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+	reactStrictMode: true,
+};
+
+export default nextConfig;

package/templates/next-saas/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "db:push": "drizzle-kit push"
+  },
+  "dependencies": {
+    "@glinr/theauth-nextjs": "^2.0.0",
+    "@glinr/theauth-react": "^0.2.0",
+    "__DB_DRIVER__": "__DB_DRIVER_VERSION__",
+    "drizzle-orm": "^0.40.0",
+    "@glinr/theauth": "^0.3.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "drizzle-kit": "^0.30.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/next-saas/src/app/agents/page.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import { useSession } from "@glinr/theauth-react";
+import Link from "next/link";
+import { useEffect, useState } from "react";
+
+interface Agent {
+	id: string;
+	name: string;
+	type: string;
+	createdAt: string;
+}
+
+export default function AgentsPage() {
+	const { session } = useSession();
+	const [agents, setAgents] = useState<Agent[]>([]);
+	const [loading, setLoading] = useState(true);
+
+	useEffect(() => {
+		if (!session?.user) {
+			setLoading(false);
+			return;
+		}
+
+		fetch("/api/agents")
+			.then((r) => r.json())
+			.then((data: { agents: Agent[] }) => setAgents(data.agents ?? []))
+			.catch(() => setAgents([]))
+			.finally(() => setLoading(false));
+	}, [session]);
+
+	if (!session?.user) {
+		return (
+			<main style={pageStyle}>
+				<p>
+					<Link href="/api/auth/sign-in">Sign in</Link> to manage your agents.
+				</p>
+			</main>
+		);
+	}
+
+	return (
+		<main style={pageStyle}>
+			<h1 style={{ fontSize: "1.75rem", fontWeight: 700 }}>Your agents</h1>
+
+			{loading ? (
+				<p style={{ color: "#888" }}>Loading&hellip;</p>
+			) : agents.length === 0 ? (
+				<div style={{ textAlign: "center", color: "#888", marginTop: "4rem" }}>
+					<p style={{ fontSize: "1.1rem" }}>No agents yet.</p>
+					<Link
+						href="/agents/new"
+						style={{
+							display: "inline-block",
+							marginTop: "1rem",
+							padding: "0.6rem 1.4rem",
+							borderRadius: "0.5rem",
+							background: "#C9A84C",
+							color: "#0a0a0a",
+							fontWeight: 600,
+							textDecoration: "none",
+						}}
+					>
+						Create first agent
+					</Link>
+				</div>
+			) : (
+				<ul style={{ listStyle: "none", padding: 0, margin: 0, width: "100%", maxWidth: "40rem" }}>
+					{agents.map((agent) => (
+						<li
+							key={agent.id}
+							style={{
+								padding: "1rem",
+								borderRadius: "0.5rem",
+								background: "#111",
+								marginBottom: "0.75rem",
+								display: "flex",
+								justifyContent: "space-between",
+								alignItems: "center",
+							}}
+						>
+							<div>
+								<strong>{agent.name}</strong>
+								<span style={{ marginLeft: "0.5rem", color: "#888", fontSize: "0.85rem" }}>
+									{agent.type}
+								</span>
+							</div>
+							<span style={{ color: "#555", fontSize: "0.8rem" }}>
+								{new Date(agent.createdAt).toLocaleDateString()}
+							</span>
+						</li>
+					))}
+				</ul>
+			)}
+		</main>
+	);
+}
+
+const pageStyle: React.CSSProperties = {
+	minHeight: "100vh",
+	display: "flex",
+	flexDirection: "column",
+	alignItems: "center",
+	padding: "4rem 2rem",
+	gap: "1.5rem",
+};

package/templates/next-saas/src/app/api/auth/[...kavach]/route.ts

@@ -0,0 +1,6 @@
+import { kavachNextjs } from "@glinr/theauth-nextjs";
+import { getKavach } from "@/lib/kavach";
+
+const { GET, POST } = kavachNextjs(getKavach);
+
+export { GET, POST };

package/templates/next-saas/src/app/globals.css

@@ -0,0 +1,12 @@
+*,
+*::before,
+*::after {
+	box-sizing: border-box;
+}
+
+body {
+	margin: 0;
+	font-family: system-ui, -apple-system, sans-serif;
+	background: #0a0a0a;
+	color: #ededed;
+}

package/templates/next-saas/src/app/layout.tsx

@@ -0,0 +1,18 @@
+import { KavachProvider } from "@glinr/theauth-react";
+import type { ReactNode } from "react";
+import "./globals.css";
+
+export const metadata = {
+	title: "__APP_NAME__",
+	description: "Powered by TheAuth",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+	return (
+		<html lang="en">
+			<body>
+				<KavachProvider basePath="/api/auth">{children}</KavachProvider>
+			</body>
+		</html>
+	);
+}

package/templates/next-saas/src/app/page.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { useSession } from "@glinr/theauth-react";
+import Link from "next/link";
+
+export default function HomePage() {
+	const { session, isLoading } = useSession();
+	const user = session?.user ?? null;
+
+	return (
+		<main
+			style={{
+				minHeight: "100vh",
+				display: "flex",
+				flexDirection: "column",
+				alignItems: "center",
+				justifyContent: "center",
+				gap: "1.5rem",
+				padding: "2rem",
+				textAlign: "center",
+			}}
+		>
+			<h1 style={{ fontSize: "2.5rem", fontWeight: 700, margin: 0 }}>__APP_NAME__</h1>
+			<p style={{ color: "#888", margin: 0, maxWidth: "40ch" }}>
+				Built on TheAuth &mdash; agent-first auth for the modern web.
+			</p>
+
+			<div style={{ display: "flex", gap: "1rem", flexWrap: "wrap", justifyContent: "center" }}>
+				{isLoading ? null : user ? (
+					<>
+						<span style={{ color: "#888" }}>Signed in as {user.email}</span>
+						<Link href="/api/auth/sign-out" style={ctaStyle("#333", "#ededed")}>
+							Sign out
+						</Link>
+					</>
+				) : (
+					<Link href="/api/auth/sign-in" style={ctaStyle("#C9A84C", "#0a0a0a")}>
+						Sign in
+					</Link>
+				)}
+
+				<Link
+					href={user ? "/agents" : "#"}
+					aria-disabled={!user}
+					style={ctaStyle(user ? "#C9A84C" : "#333", user ? "#0a0a0a" : "#666")}
+					onClick={!user ? (e) => e.preventDefault() : undefined}
+				>
+					{user ? "My agents" : "Sign in to spawn an agent"}
+				</Link>
+			</div>
+		</main>
+	);
+}
+
+function ctaStyle(bg: string, color: string): React.CSSProperties {
+	return {
+		display: "inline-block",
+		padding: "0.6rem 1.4rem",
+		borderRadius: "0.5rem",
+		background: bg,
+		color,
+		fontWeight: 600,
+		textDecoration: "none",
+		fontSize: "0.95rem",
+	};
+}

package/templates/next-saas/src/lib/kavach.ts

@@ -0,0 +1,18 @@
+import { createKavach } from "@glinr/theauth";
+
+// Initialised lazily so Next.js doesn't try to open a DB connection at build
+// time. Import `getKavach()` from your server components or route handlers.
+let instance: Awaited<ReturnType<typeof createKavach>> | null = null;
+
+export async function getKavach() {
+	if (!instance) {
+		instance = await createKavach({
+			database: {
+				provider: "__DB_DRIVER__" === "pg" ? "postgres" : "sqlite",
+				url: process.env["DATABASE_URL"] ?? "file:./kavach.db",
+			},
+			secret: process.env["THEAUTH_SECRET"] ?? "dev-secret-change-me",
+		});
+	}
+	return instance;
+}

package/templates/next-saas/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}