@stratum-hq/create 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @stratum-hq/create
 
+## 0.5.0
+
+### Minor Changes
+
+- 4c1686a: Generated servers and Next.js middleware take the tenant from a verified JWT instead of the hostname (GHSA-p4wg-j8hh-9wh8).
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -30,7 +30,7 @@ npx @stratum-hq/create my-app [options]
 
 - **express** (default) — Express server with Stratum middleware, tenant-aware routes, and TypeScript config.
 - **fastify** — Fastify server with the Stratum plugin registered.
-- **nextjs** — Next.js project with edge middleware for tenant resolution and server-side helpers.
+- **nextjs** — Next.js project with edge middleware that resolves the tenant from a verified JWT.
 
 ## After Scaffolding
 
@@ -43,6 +43,10 @@ npm run dev            # run the app
 
 The generated starter code does not create a `Stratum` instance, so it does not create Stratum's tables. To create them, construct `Stratum` with `autoMigrate: true` and call `initialize()` once at startup.
 
+## Tenant resolution
+
+Generated servers (the Express, Fastify, Hono and NestJS presets) and the Next.js middleware take the tenant ID only from the `tenant_id` claim of a bearer token that verifies with `JWT_SECRET` (HS256, using `jose`, which the generated `package.json` lists). A token that does not verify, or has no `tenant_id` claim, is rejected with 401. The tenant is never taken from the hostname or from a client-supplied header such as `x-tenant-id`. In the Next.js middleware the subdomain is forwarded as `x-tenant-slug`, a display hint that does not identify the caller's tenant.
+
 ## Links
 
 - Documentation: https://docs.stratum-hq.org/packages/create/

package/dist/index.js

@@ -610,6 +610,114 @@ export { pool };
 }
 
 // src/generators/middleware.ts
+var VERIFIED_TENANT = `import { jwtVerify } from "jose";
+
+const jwtSecret = process.env.JWT_SECRET;
+if (!jwtSecret) {
+  throw new Error("JWT_SECRET must be set: the tenant is taken from a verified JWT.");
+}
+const jwtKey = new TextEncoder().encode(jwtSecret);
+
+/**
+ * The tenant for a request, from the tenant_id claim of a bearer token that
+ * verifies with JWT_SECRET. tenantId is null when there is no bearer token.
+ * invalid is true when a token was sent but does not verify or has no
+ * tenant_id claim. Never take the tenant from the hostname or from a header
+ * such as x-tenant-id: any caller can choose those.
+ */
+async function verifiedTenant(
+  authorization: string | undefined,
+): Promise<{ tenantId: string | null; invalid: boolean }> {
+  if (!authorization?.startsWith("Bearer ")) return { tenantId: null, invalid: false };
+  try {
+    const { payload } = await jwtVerify(authorization.slice("Bearer ".length), jwtKey, {
+      algorithms: ["HS256"],
+    });
+    if (typeof payload.tenant_id === "string") return { tenantId: payload.tenant_id, invalid: false };
+  } catch {
+    // Fall through: a token that does not verify is rejected, never ignored.
+  }
+  return { tenantId: null, invalid: true };
+}`;
+var INVALID_TOKEN = `{ error: "Bearer token is invalid or has no tenant_id claim" }`;
+var TENANT_REQUIRED = `{ error: "A bearer token with a tenant_id claim is required" }`;
+function nextjsTenantMiddleware() {
+  return `// middleware.ts (place in project root)
+// Next.js middleware for Stratum tenant resolution
+//
+// The tenant ID comes only from the tenant_id claim of a bearer token that
+// verifies with JWT_SECRET, and is forwarded as x-tenant-id. Any copy of the
+// tenant headers the client sent is removed first, so server code only ever
+// reads the values set here.
+//
+// The subdomain (acme.app.example.com) is forwarded as x-tenant-slug. It only
+// says which tenant's public pages to show. It does not prove the caller
+// belongs to that tenant, so never use it to read or write tenant data.
+
+import { NextRequest, NextResponse } from "next/server";
+import { jwtVerify } from "jose";
+
+const TENANT_ID_HEADER = "x-tenant-id";
+const TENANT_SLUG_HEADER = "x-tenant-slug";
+
+/**
+ * The tenant_id claim of a token that verifies with JWT_SECRET, or null when
+ * the token is invalid, expired, or has no string tenant_id claim.
+ */
+async function verifiedTenantId(token: string): Promise<string | null> {
+  const secret = process.env.JWT_SECRET;
+  if (!secret) {
+    throw new Error("JWT_SECRET must be set: the tenant is taken from a verified JWT.");
+  }
+  try {
+    const { payload } = await jwtVerify(token, new TextEncoder().encode(secret), {
+      algorithms: ["HS256"],
+    });
+    return typeof payload.tenant_id === "string" ? payload.tenant_id : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function middleware(request: NextRequest): Promise<NextResponse> {
+  // Only this middleware may set the tenant headers.
+  const requestHeaders = new Headers(request.headers);
+  requestHeaders.delete("x-tenant-id");
+  requestHeaders.delete(TENANT_SLUG_HEADER);
+
+  // A bearer token that does not verify is rejected, never ignored.
+  const authorization = request.headers.get("authorization");
+  if (authorization?.startsWith("Bearer ")) {
+    const tenantId = await verifiedTenantId(authorization.slice("Bearer ".length));
+    if (!tenantId) {
+      return NextResponse.json(
+        { error: { code: "INVALID_TOKEN", message: "Bearer token is invalid or has no tenant_id claim" } },
+        { status: 401 },
+      );
+    }
+    requestHeaders.set(TENANT_ID_HEADER, tenantId);
+  }
+
+  // Subdomain, e.g. "acme" from "acme.app.example.com": a slug, not an identity.
+  const hostname = (request.headers.get("host") ?? "").split(":")[0];
+  const rootDomain = process.env.ROOT_DOMAIN ?? "app.example.com";
+  if (hostname.endsWith(\`.\${rootDomain}\`)) {
+    const subdomain = hostname.slice(0, hostname.length - rootDomain.length - 1);
+    if (subdomain && subdomain !== "www") {
+      requestHeaders.set(TENANT_SLUG_HEADER, subdomain);
+    }
+  }
+
+  // With no verified tenant the request continues without x-tenant-id. Each
+  // route decides whether to require a tenant or serve a public page.
+  return NextResponse.next({ request: { headers: requestHeaders } });
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+`;
+}
 function generateMiddleware(projectName, preset) {
   switch (preset.framework) {
     case "express":
@@ -631,19 +739,21 @@ function generateExpressMiddleware(projectName) {
     {
       filename: "src/index.ts",
       content: `import express from "express";
+${VERIFIED_TENANT}
 
 const app = express();
 const port = Number(process.env.PORT) || 3000;
 
 app.use(express.json());
 
-// Tenant extraction middleware. The tenant comes from the subdomain the
-// request was routed to. Do not take it from a client-supplied header such as
-// x-tenant-id: any caller can set one and pick another tenant. Once you add
-// authentication, check that the signed-in user belongs to this tenant, or
-// derive the tenant from the verified session or JWT instead.
-app.use((req, _res, next) => {
-  const tenantId = req.hostname.split(".")[0];
+// Tenant resolution. The tenant comes only from a verified bearer token;
+// a token that does not verify is rejected with 401.
+app.use(async (req, res, next) => {
+  const { tenantId, invalid } = await verifiedTenant(req.headers.authorization);
+  if (invalid) {
+    res.status(401).json(${INVALID_TOKEN});
+    return;
+  }
   (req as any).tenantId = tenantId;
   next();
 });
@@ -654,6 +764,10 @@ app.get("/health", (_req, res) => {
 
 app.get("/tenants", async (req, res) => {
   const tenantId = (req as any).tenantId;
+  if (!tenantId) {
+    res.status(401).json(${TENANT_REQUIRED});
+    return;
+  }
   res.json({ tenantId, message: "Replace with your tenant queries" });
 });
 
@@ -669,18 +783,19 @@ function generateFastifyMiddleware(projectName) {
     {
       filename: "src/index.ts",
       content: `import Fastify from "fastify";
+${VERIFIED_TENANT}
 
 const fastify = Fastify({ logger: true });
 const port = Number(process.env.PORT) || 3000;
 
-// Tenant extraction hook. The tenant comes from the subdomain the
-// request was routed to. Do not take it from a client-supplied header such as
-// x-tenant-id: any caller can set one and pick another tenant. Once you add
-// authentication, check that the signed-in user belongs to this tenant, or
-// derive the tenant from the verified session or JWT instead.
-fastify.decorateRequest("tenantId", "");
-fastify.addHook("onRequest", async (request) => {
-  const tenantId = request.hostname?.split(".")[0] ?? "";
+// Tenant resolution. The tenant comes only from a verified bearer token;
+// a token that does not verify is rejected with 401.
+fastify.decorateRequest("tenantId", null);
+fastify.addHook("onRequest", async (request, reply) => {
+  const { tenantId, invalid } = await verifiedTenant(request.headers.authorization);
+  if (invalid) {
+    return reply.status(401).send(${INVALID_TOKEN});
+  }
   (request as any).tenantId = tenantId;
 });
 
@@ -688,8 +803,11 @@ fastify.get("/health", async () => {
   return { status: "ok", project: "${projectName}" };
 });
 
-fastify.get("/tenants", async (request) => {
+fastify.get("/tenants", async (request, reply) => {
   const tenantId = (request as any).tenantId;
+  if (!tenantId) {
+    return reply.status(401).send(${TENANT_REQUIRED});
+  }
   return { tenantId, message: "Replace with your tenant queries" };
 });
 
@@ -707,30 +825,7 @@ function generateNextjsMiddleware(projectName) {
   return [
     {
       filename: "middleware.ts",
-      content: `// Next.js edge middleware for tenant resolution
-import { NextRequest, NextResponse } from "next/server";
-
-export function middleware(request: NextRequest) {
-  // The tenant comes from the subdomain the request was routed to. Any
-  // x-tenant-id the client sent is removed first, so server code that reads
-  // x-tenant-id only ever sees the value set here. Once you add
-  // authentication, check that the signed-in user belongs to this tenant.
-  const hostname = request.headers.get("host") || "";
-  const tenantId = hostname.split(".")[0];
-
-  const requestHeaders = new Headers(request.headers);
-  requestHeaders.delete("x-tenant-id");
-  if (tenantId && tenantId !== "localhost" && tenantId !== "www") {
-    requestHeaders.set("x-tenant-id", tenantId);
-  }
-
-  return NextResponse.next({ request: { headers: requestHeaders } });
-}
-
-export const config = {
-  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
-};
-`
+      content: nextjsTenantMiddleware()
     },
     {
       filename: "src/app/page.tsx",
@@ -742,7 +837,7 @@ export default function Home() {
       <p>Multi-tenant app powered by Stratum.</p>
       <ul>
         <li>Configure tenants via the Stratum control plane</li>
-        <li>Tenant is resolved from the subdomain in <code>middleware.ts</code></li>
+        <li>The tenant comes from a verified JWT in <code>middleware.ts</code></li>
         <li>Use <code>@stratum-hq/lib</code> for tenant resolution</li>
       </ul>
     </main>
@@ -758,16 +853,17 @@ function generateHonoMiddleware(projectName) {
       filename: "src/index.ts",
       content: `import { Hono } from "hono";
 import { serve } from "@hono/node-server";
+${VERIFIED_TENANT}
 
-const app = new Hono();
+const app = new Hono<{ Variables: { tenantId: string | null } }>();
 
-// Tenant extraction middleware. The tenant comes from the subdomain the
-// request was routed to. Do not take it from a client-supplied header such as
-// x-tenant-id: any caller can set one and pick another tenant. Once you add
-// authentication, check that the signed-in user belongs to this tenant, or
-// derive the tenant from the verified session or JWT instead.
+// Tenant resolution. The tenant comes only from a verified bearer token;
+// a token that does not verify is rejected with 401.
 app.use("*", async (c, next) => {
-  const tenantId = new URL(c.req.url).hostname.split(".")[0];
+  const { tenantId, invalid } = await verifiedTenant(c.req.header("authorization"));
+  if (invalid) {
+    return c.json(${INVALID_TOKEN}, 401);
+  }
   c.set("tenantId", tenantId);
   await next();
 });
@@ -778,6 +874,9 @@ app.get("/health", (c) => {
 
 app.get("/tenants", (c) => {
   const tenantId = c.get("tenantId");
+  if (!tenantId) {
+    return c.json(${TENANT_REQUIRED}, 401);
+  }
   return c.json({ tenantId, message: "Replace with your tenant queries" });
 });
 
@@ -822,7 +921,7 @@ export class AppModule {}
     },
     {
       filename: "src/app.controller.ts",
-      content: `import { Controller, Get, Req } from "@nestjs/common";
+      content: `import { Controller, Get, Req, UnauthorizedException } from "@nestjs/common";
 
 @Controller()
 export class AppController {
@@ -833,6 +932,9 @@ export class AppController {
 
   @Get("tenants")
   tenants(@Req() req: any) {
+    if (!req.tenantId) {
+      throw new UnauthorizedException("A bearer token with a tenant_id claim is required");
+    }
     return { tenantId: req.tenantId, message: "Replace with your tenant queries" };
   }
 }
@@ -840,18 +942,22 @@ export class AppController {
     },
     {
       filename: "src/tenant.guard.ts",
-      content: `import { Injectable, CanActivate, ExecutionContext } from "@nestjs/common";
+      content: `import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from "@nestjs/common";
+${VERIFIED_TENANT}
 
+/**
+ * Sets request.tenantId from a verified bearer token, or null when there is
+ * no token. A token that does not verify is rejected with 401.
+ */
 @Injectable()
 export class TenantGuard implements CanActivate {
-  canActivate(context: ExecutionContext): boolean {
+  async canActivate(context: ExecutionContext): Promise<boolean> {
     const request = context.switchToHttp().getRequest();
-    // The tenant comes from the subdomain the request was routed to. Do not
-    // take it from a client-supplied header such as x-tenant-id: any caller
-    // can set one and pick another tenant. Once you add authentication, check
-    // that the signed-in user belongs to this tenant here.
-    const tenantId = request.hostname?.split(".")[0];
-    request.tenantId = tenantId || null;
+    const { tenantId, invalid } = await verifiedTenant(request.headers?.authorization);
+    if (invalid) {
+      throw new UnauthorizedException("Bearer token is invalid or has no tenant_id claim");
+    }
+    request.tenantId = tenantId;
     return true;
   }
 }
@@ -906,7 +1012,7 @@ function generateTsconfig(framework, extraSources = []) {
 // ../hono/package.json
 var package_default = {
   name: "@stratum-hq/hono",
-  version: "1.1.0",
+  version: "1.2.0",
   description: "Stratum Hono integration \u2014 tenant extraction middleware with ALS context",
   keywords: [
     "multi-tenancy",
@@ -1048,7 +1154,7 @@ var package_default2 = {
 // ../lib/package.json
 var package_default3 = {
   name: "@stratum-hq/lib",
-  version: "1.4.0",
+  version: "1.5.0",
   description: "Stratum tenant management library - framework-agnostic business logic",
   keywords: [
     "multi-tenancy",
@@ -1094,9 +1200,9 @@ var package_default3 = {
   },
   dependencies: {
     "@opentelemetry/api": "^1.9.0",
-    "@stratum-hq/core": "^1.4.0",
+    "@stratum-hq/core": "^1.5.0",
     "@stratum-hq/db-adapters": "^1.2.0",
-    "@stratum-hq/sdk": "^1.2.0",
+    "@stratum-hq/sdk": "^1.3.0",
     pg: "^8.11.0"
   },
   peerDependencies: {
@@ -1129,7 +1235,7 @@ var package_default3 = {
 // ../mongodb/package.json
 var package_default4 = {
   name: "@stratum-hq/mongodb",
-  version: "0.4.0",
+  version: "0.5.0",
   description: "MongoDB tenant isolation for Stratum \u2014 shared collection, collection-per-tenant, and database-per-tenant strategies",
   keywords: [
     "multi-tenancy",
@@ -1165,8 +1271,8 @@ var package_default4 = {
     clean: "rm -rf dist"
   },
   dependencies: {
-    "@stratum-hq/core": "^1.4.0",
-    "@stratum-hq/sdk": "^1.2.0"
+    "@stratum-hq/core": "^1.5.0",
+    "@stratum-hq/sdk": "^1.3.0"
   },
   peerDependencies: {
     mongodb: "^6.0.0 || ^7.0.0"
@@ -1203,7 +1309,7 @@ var package_default4 = {
 // ../mysql/package.json
 var package_default5 = {
   name: "@stratum-hq/mysql",
-  version: "0.4.0",
+  version: "0.5.0",
   description: "MySQL tenant isolation for Stratum \u2014 shared table, table-per-tenant, and database-per-tenant strategies",
   keywords: [
     "multi-tenancy",
@@ -1241,8 +1347,8 @@ var package_default5 = {
     clean: "rm -rf dist"
   },
   dependencies: {
-    "@stratum-hq/core": "^1.4.0",
-    "@stratum-hq/sdk": "^1.2.0"
+    "@stratum-hq/core": "^1.5.0",
+    "@stratum-hq/sdk": "^1.3.0"
   },
   peerDependencies: {
     mysql2: "^3.0.0",
@@ -1288,7 +1394,7 @@ var package_default5 = {
 // ../nestjs/package.json
 var package_default6 = {
   name: "@stratum-hq/nestjs",
-  version: "1.2.0",
+  version: "1.3.0",
   description: "Stratum NestJS integration \u2014 StratumGuard, @Tenant() decorator, and StratumModule",
   keywords: [
     "multi-tenancy",
@@ -1332,7 +1438,7 @@ var package_default6 = {
     "@nestjs/common": ">=10.0.0",
     "@nestjs/core": ">=10.0.0",
     "@stratum-hq/core": "^1.0.0",
-    "@stratum-hq/sdk": "^1.2.0",
+    "@stratum-hq/sdk": "^1.3.0",
     "reflect-metadata": ">=0.1.13"
   },
   devDependencies: {
@@ -1468,6 +1574,9 @@ function addOrmDeps(deps, devDeps, preset) {
   }
 }
 function addFrameworkDeps(deps, devDeps, preset) {
+  if (preset.framework !== "none") {
+    deps["jose"] = "^6.2.12";
+  }
   switch (preset.framework) {
     case "express":
       deps["express"] = "^4.18.0";
@@ -1819,7 +1928,9 @@ function generatePackageJson(projectName, template) {
       react: "^19.0.0",
       "react-dom": "^19.0.0",
       "@types/react": "^19.0.0",
-      "@types/react-dom": "^19.0.0"
+      "@types/react-dom": "^19.0.0",
+      // The middleware verifies the tenant JWT with jose.
+      jose: "^6.2.12"
     }
   };
   const deps = {
@@ -1990,7 +2101,7 @@ export default function Home() {
       <p>Multi-tenant app powered by Stratum.</p>
       <ul>
         <li>Configure tenants via the Stratum control plane</li>
-        <li>Tenant is resolved from the subdomain in <code>middleware.ts</code></li>
+        <li>The tenant comes from a verified JWT in <code>middleware.ts</code></li>
         <li>Use <code>@stratum-hq/lib</code> for tenant resolution</li>
       </ul>
     </main>
@@ -1998,32 +2109,6 @@ export default function Home() {
 }
 `;
 }
-function generateNextjsMiddleware2() {
-  return `// middleware.ts \u2014 tenant resolution via subdomain
-import { NextRequest, NextResponse } from "next/server";
-
-export function middleware(request: NextRequest) {
-  // The tenant comes from the subdomain the request was routed to. Any
-  // x-tenant-id the client sent is removed first, so server code that reads
-  // x-tenant-id only ever sees the value set here. Once you add
-  // authentication, check that the signed-in user belongs to this tenant.
-  const hostname = request.headers.get("host") || "";
-  const tenantId = hostname.split(".")[0];
-
-  const requestHeaders = new Headers(request.headers);
-  requestHeaders.delete("x-tenant-id");
-  if (tenantId && tenantId !== "localhost" && tenantId !== "www") {
-    requestHeaders.set("x-tenant-id", tenantId);
-  }
-
-  return NextResponse.next({ request: { headers: requestHeaders } });
-}
-
-export const config = {
-  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
-};
-`;
-}
 function generateReadme(projectName, template) {
   return `# ${projectName}
 
@@ -2071,7 +2156,7 @@ ${template === "nextjs" ? "" : "\u251C\u2500\u2500 tsconfig.json\n"}\u2514\u2500
 
 This project uses Stratum for hierarchical multi-tenancy:
 
-- **Tenant resolution** \u2014 via subdomain (see \`middleware.ts\`); bind it to the signed-in user once you add authentication
+- **Tenant resolution** \u2014 from the \`tenant_id\` claim of a bearer token verified with \`JWT_SECRET\` (see \`middleware.ts\`); the subdomain is only a display slug
 - **Config inheritance** \u2014 settings flow down the tenant tree with override support
 - **Permission ABAC** \u2014 role-based permissions with tenant-scoped enforcement
 
@@ -2097,7 +2182,7 @@ Creating ${projectName} with ${template} template...
     writeFile2(path2.join(targetDir, "tsconfig.json"), generateTsconfig(template));
   } else if (template === "nextjs") {
     writeFile2(path2.join(targetDir, "src", "app", "page.tsx"), generateNextjsPage(projectName));
-    writeFile2(path2.join(targetDir, "middleware.ts"), generateNextjsMiddleware2());
+    writeFile2(path2.join(targetDir, "middleware.ts"), nextjsTenantMiddleware());
   }
   writeFile2(path2.join(targetDir, "README.md"), generateReadme(projectName, template));
   if (!skipInstall) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stratum-hq/create",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Create a new Stratum multi-tenancy project",
   "keywords": [
     "multi-tenancy",

package/src/generators/middleware.ts

@@ -5,6 +5,128 @@ export interface MiddlewareFile {
   content: string;
 }
 
+/**
+ * Verifies the bearer token and returns its tenant_id claim. Inserted into
+ * every generated server so the project needs nothing but jose. The tenant
+ * never comes from the hostname or a header such as x-tenant-id: any caller
+ * can choose those.
+ */
+const VERIFIED_TENANT = `import { jwtVerify } from "jose";
+
+const jwtSecret = process.env.JWT_SECRET;
+if (!jwtSecret) {
+  throw new Error("JWT_SECRET must be set: the tenant is taken from a verified JWT.");
+}
+const jwtKey = new TextEncoder().encode(jwtSecret);
+
+/**
+ * The tenant for a request, from the tenant_id claim of a bearer token that
+ * verifies with JWT_SECRET. tenantId is null when there is no bearer token.
+ * invalid is true when a token was sent but does not verify or has no
+ * tenant_id claim. Never take the tenant from the hostname or from a header
+ * such as x-tenant-id: any caller can choose those.
+ */
+async function verifiedTenant(
+  authorization: string | undefined,
+): Promise<{ tenantId: string | null; invalid: boolean }> {
+  if (!authorization?.startsWith("Bearer ")) return { tenantId: null, invalid: false };
+  try {
+    const { payload } = await jwtVerify(authorization.slice("Bearer ".length), jwtKey, {
+      algorithms: ["HS256"],
+    });
+    if (typeof payload.tenant_id === "string") return { tenantId: payload.tenant_id, invalid: false };
+  } catch {
+    // Fall through: a token that does not verify is rejected, never ignored.
+  }
+  return { tenantId: null, invalid: true };
+}`;
+
+const INVALID_TOKEN = `{ error: "Bearer token is invalid or has no tenant_id claim" }`;
+const TENANT_REQUIRED = `{ error: "A bearer token with a tenant_id claim is required" }`;
+
+/**
+ * Next.js middleware, following examples/with-nextjs: the tenant ID comes only
+ * from the tenant_id claim of a verified bearer token and is forwarded as
+ * x-tenant-id. The subdomain is forwarded as x-tenant-slug, never as the ID.
+ */
+export function nextjsTenantMiddleware(): string {
+  return `// middleware.ts (place in project root)
+// Next.js middleware for Stratum tenant resolution
+//
+// The tenant ID comes only from the tenant_id claim of a bearer token that
+// verifies with JWT_SECRET, and is forwarded as x-tenant-id. Any copy of the
+// tenant headers the client sent is removed first, so server code only ever
+// reads the values set here.
+//
+// The subdomain (acme.app.example.com) is forwarded as x-tenant-slug. It only
+// says which tenant's public pages to show. It does not prove the caller
+// belongs to that tenant, so never use it to read or write tenant data.
+
+import { NextRequest, NextResponse } from "next/server";
+import { jwtVerify } from "jose";
+
+const TENANT_ID_HEADER = "x-tenant-id";
+const TENANT_SLUG_HEADER = "x-tenant-slug";
+
+/**
+ * The tenant_id claim of a token that verifies with JWT_SECRET, or null when
+ * the token is invalid, expired, or has no string tenant_id claim.
+ */
+async function verifiedTenantId(token: string): Promise<string | null> {
+  const secret = process.env.JWT_SECRET;
+  if (!secret) {
+    throw new Error("JWT_SECRET must be set: the tenant is taken from a verified JWT.");
+  }
+  try {
+    const { payload } = await jwtVerify(token, new TextEncoder().encode(secret), {
+      algorithms: ["HS256"],
+    });
+    return typeof payload.tenant_id === "string" ? payload.tenant_id : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function middleware(request: NextRequest): Promise<NextResponse> {
+  // Only this middleware may set the tenant headers.
+  const requestHeaders = new Headers(request.headers);
+  requestHeaders.delete("x-tenant-id");
+  requestHeaders.delete(TENANT_SLUG_HEADER);
+
+  // A bearer token that does not verify is rejected, never ignored.
+  const authorization = request.headers.get("authorization");
+  if (authorization?.startsWith("Bearer ")) {
+    const tenantId = await verifiedTenantId(authorization.slice("Bearer ".length));
+    if (!tenantId) {
+      return NextResponse.json(
+        { error: { code: "INVALID_TOKEN", message: "Bearer token is invalid or has no tenant_id claim" } },
+        { status: 401 },
+      );
+    }
+    requestHeaders.set(TENANT_ID_HEADER, tenantId);
+  }
+
+  // Subdomain, e.g. "acme" from "acme.app.example.com": a slug, not an identity.
+  const hostname = (request.headers.get("host") ?? "").split(":")[0];
+  const rootDomain = process.env.ROOT_DOMAIN ?? "app.example.com";
+  if (hostname.endsWith(\`.\${rootDomain}\`)) {
+    const subdomain = hostname.slice(0, hostname.length - rootDomain.length - 1);
+    if (subdomain && subdomain !== "www") {
+      requestHeaders.set(TENANT_SLUG_HEADER, subdomain);
+    }
+  }
+
+  // With no verified tenant the request continues without x-tenant-id. Each
+  // route decides whether to require a tenant or serve a public page.
+  return NextResponse.next({ request: { headers: requestHeaders } });
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+`;
+}
+
 export function generateMiddleware(projectName: string, preset: StackPreset): MiddlewareFile[] {
   switch (preset.framework) {
     case "express":
@@ -27,19 +149,21 @@ function generateExpressMiddleware(projectName: string): MiddlewareFile[] {
     {
       filename: "src/index.ts",
       content: `import express from "express";
+${VERIFIED_TENANT}
 
 const app = express();
 const port = Number(process.env.PORT) || 3000;
 
 app.use(express.json());
 
-// Tenant extraction middleware. The tenant comes from the subdomain the
-// request was routed to. Do not take it from a client-supplied header such as
-// x-tenant-id: any caller can set one and pick another tenant. Once you add
-// authentication, check that the signed-in user belongs to this tenant, or
-// derive the tenant from the verified session or JWT instead.
-app.use((req, _res, next) => {
-  const tenantId = req.hostname.split(".")[0];
+// Tenant resolution. The tenant comes only from a verified bearer token;
+// a token that does not verify is rejected with 401.
+app.use(async (req, res, next) => {
+  const { tenantId, invalid } = await verifiedTenant(req.headers.authorization);
+  if (invalid) {
+    res.status(401).json(${INVALID_TOKEN});
+    return;
+  }
   (req as any).tenantId = tenantId;
   next();
 });
@@ -50,6 +174,10 @@ app.get("/health", (_req, res) => {
 
 app.get("/tenants", async (req, res) => {
   const tenantId = (req as any).tenantId;
+  if (!tenantId) {
+    res.status(401).json(${TENANT_REQUIRED});
+    return;
+  }
   res.json({ tenantId, message: "Replace with your tenant queries" });
 });
 
@@ -66,18 +194,19 @@ function generateFastifyMiddleware(projectName: string): MiddlewareFile[] {
     {
       filename: "src/index.ts",
       content: `import Fastify from "fastify";
+${VERIFIED_TENANT}
 
 const fastify = Fastify({ logger: true });
 const port = Number(process.env.PORT) || 3000;
 
-// Tenant extraction hook. The tenant comes from the subdomain the
-// request was routed to. Do not take it from a client-supplied header such as
-// x-tenant-id: any caller can set one and pick another tenant. Once you add
-// authentication, check that the signed-in user belongs to this tenant, or
-// derive the tenant from the verified session or JWT instead.
-fastify.decorateRequest("tenantId", "");
-fastify.addHook("onRequest", async (request) => {
-  const tenantId = request.hostname?.split(".")[0] ?? "";
+// Tenant resolution. The tenant comes only from a verified bearer token;
+// a token that does not verify is rejected with 401.
+fastify.decorateRequest("tenantId", null);
+fastify.addHook("onRequest", async (request, reply) => {
+  const { tenantId, invalid } = await verifiedTenant(request.headers.authorization);
+  if (invalid) {
+    return reply.status(401).send(${INVALID_TOKEN});
+  }
   (request as any).tenantId = tenantId;
 });
 
@@ -85,8 +214,11 @@ fastify.get("/health", async () => {
   return { status: "ok", project: "${projectName}" };
 });
 
-fastify.get("/tenants", async (request) => {
+fastify.get("/tenants", async (request, reply) => {
   const tenantId = (request as any).tenantId;
+  if (!tenantId) {
+    return reply.status(401).send(${TENANT_REQUIRED});
+  }
   return { tenantId, message: "Replace with your tenant queries" };
 });
 
@@ -105,30 +237,7 @@ function generateNextjsMiddleware(projectName: string): MiddlewareFile[] {
   return [
     {
       filename: "middleware.ts",
-      content: `// Next.js edge middleware for tenant resolution
-import { NextRequest, NextResponse } from "next/server";
-
-export function middleware(request: NextRequest) {
-  // The tenant comes from the subdomain the request was routed to. Any
-  // x-tenant-id the client sent is removed first, so server code that reads
-  // x-tenant-id only ever sees the value set here. Once you add
-  // authentication, check that the signed-in user belongs to this tenant.
-  const hostname = request.headers.get("host") || "";
-  const tenantId = hostname.split(".")[0];
-
-  const requestHeaders = new Headers(request.headers);
-  requestHeaders.delete("x-tenant-id");
-  if (tenantId && tenantId !== "localhost" && tenantId !== "www") {
-    requestHeaders.set("x-tenant-id", tenantId);
-  }
-
-  return NextResponse.next({ request: { headers: requestHeaders } });
-}
-
-export const config = {
-  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
-};
-`,
+      content: nextjsTenantMiddleware(),
     },
     {
       filename: "src/app/page.tsx",
@@ -140,7 +249,7 @@ export default function Home() {
       <p>Multi-tenant app powered by Stratum.</p>
       <ul>
         <li>Configure tenants via the Stratum control plane</li>
-        <li>Tenant is resolved from the subdomain in <code>middleware.ts</code></li>
+        <li>The tenant comes from a verified JWT in <code>middleware.ts</code></li>
         <li>Use <code>@stratum-hq/lib</code> for tenant resolution</li>
       </ul>
     </main>
@@ -157,16 +266,17 @@ function generateHonoMiddleware(projectName: string): MiddlewareFile[] {
       filename: "src/index.ts",
       content: `import { Hono } from "hono";
 import { serve } from "@hono/node-server";
+${VERIFIED_TENANT}
 
-const app = new Hono();
+const app = new Hono<{ Variables: { tenantId: string | null } }>();
 
-// Tenant extraction middleware. The tenant comes from the subdomain the
-// request was routed to. Do not take it from a client-supplied header such as
-// x-tenant-id: any caller can set one and pick another tenant. Once you add
-// authentication, check that the signed-in user belongs to this tenant, or
-// derive the tenant from the verified session or JWT instead.
+// Tenant resolution. The tenant comes only from a verified bearer token;
+// a token that does not verify is rejected with 401.
 app.use("*", async (c, next) => {
-  const tenantId = new URL(c.req.url).hostname.split(".")[0];
+  const { tenantId, invalid } = await verifiedTenant(c.req.header("authorization"));
+  if (invalid) {
+    return c.json(${INVALID_TOKEN}, 401);
+  }
   c.set("tenantId", tenantId);
   await next();
 });
@@ -177,6 +287,9 @@ app.get("/health", (c) => {
 
 app.get("/tenants", (c) => {
   const tenantId = c.get("tenantId");
+  if (!tenantId) {
+    return c.json(${TENANT_REQUIRED}, 401);
+  }
   return c.json({ tenantId, message: "Replace with your tenant queries" });
 });
 
@@ -222,7 +335,7 @@ export class AppModule {}
     },
     {
       filename: "src/app.controller.ts",
-      content: `import { Controller, Get, Req } from "@nestjs/common";
+      content: `import { Controller, Get, Req, UnauthorizedException } from "@nestjs/common";
 
 @Controller()
 export class AppController {
@@ -233,6 +346,9 @@ export class AppController {
 
   @Get("tenants")
   tenants(@Req() req: any) {
+    if (!req.tenantId) {
+      throw new UnauthorizedException("A bearer token with a tenant_id claim is required");
+    }
     return { tenantId: req.tenantId, message: "Replace with your tenant queries" };
   }
 }
@@ -240,18 +356,22 @@ export class AppController {
     },
     {
       filename: "src/tenant.guard.ts",
-      content: `import { Injectable, CanActivate, ExecutionContext } from "@nestjs/common";
+      content: `import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from "@nestjs/common";
+${VERIFIED_TENANT}
 
+/**
+ * Sets request.tenantId from a verified bearer token, or null when there is
+ * no token. A token that does not verify is rejected with 401.
+ */
 @Injectable()
 export class TenantGuard implements CanActivate {
-  canActivate(context: ExecutionContext): boolean {
+  async canActivate(context: ExecutionContext): Promise<boolean> {
     const request = context.switchToHttp().getRequest();
-    // The tenant comes from the subdomain the request was routed to. Do not
-    // take it from a client-supplied header such as x-tenant-id: any caller
-    // can set one and pick another tenant. Once you add authentication, check
-    // that the signed-in user belongs to this tenant here.
-    const tenantId = request.hostname?.split(".")[0];
-    request.tenantId = tenantId || null;
+    const { tenantId, invalid } = await verifiedTenant(request.headers?.authorization);
+    if (invalid) {
+      throw new UnauthorizedException("Bearer token is invalid or has no tenant_id claim");
+    }
+    request.tenantId = tenantId;
     return true;
   }
 }

package/src/generators/package-json.ts

@@ -119,6 +119,10 @@ function addOrmDeps(deps: Record<string, string>, devDeps: Record<string, string
 }
 
 function addFrameworkDeps(deps: Record<string, string>, devDeps: Record<string, string>, preset: StackPreset): void {
+  // The generated tenant resolution verifies the tenant JWT with jose.
+  if (preset.framework !== "none") {
+    deps["jose"] = "^6.2.12";
+  }
   switch (preset.framework) {
     case "express":
       deps["express"] = "^4.18.0";

package/src/index.ts

@@ -7,6 +7,7 @@ import { createPresetProject } from "./preset-project.js";
 import { STRATUM_RANGES } from "./stratum-versions.js";
 import { postgresAppRole, postgresAppRoleSql, POSTGRES_APP_PASSWORD } from "./generators/init-sql.js";
 import { generateTsconfig } from "./generators/tsconfig.js";
+import { nextjsTenantMiddleware } from "./generators/middleware.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -122,6 +123,8 @@ function generatePackageJson(projectName: string, template: Template): string {
       "react-dom": "^19.0.0",
       "@types/react": "^19.0.0",
       "@types/react-dom": "^19.0.0",
+      // The middleware verifies the tenant JWT with jose.
+      jose: "^6.2.12",
     },
   };
 
@@ -301,7 +304,7 @@ export default function Home() {
       <p>Multi-tenant app powered by Stratum.</p>
       <ul>
         <li>Configure tenants via the Stratum control plane</li>
-        <li>Tenant is resolved from the subdomain in <code>middleware.ts</code></li>
+        <li>The tenant comes from a verified JWT in <code>middleware.ts</code></li>
         <li>Use <code>@stratum-hq/lib</code> for tenant resolution</li>
       </ul>
     </main>
@@ -310,33 +313,6 @@ export default function Home() {
 `;
 }
 
-function generateNextjsMiddleware(): string {
-  return `// middleware.ts — tenant resolution via subdomain
-import { NextRequest, NextResponse } from "next/server";
-
-export function middleware(request: NextRequest) {
-  // The tenant comes from the subdomain the request was routed to. Any
-  // x-tenant-id the client sent is removed first, so server code that reads
-  // x-tenant-id only ever sees the value set here. Once you add
-  // authentication, check that the signed-in user belongs to this tenant.
-  const hostname = request.headers.get("host") || "";
-  const tenantId = hostname.split(".")[0];
-
-  const requestHeaders = new Headers(request.headers);
-  requestHeaders.delete("x-tenant-id");
-  if (tenantId && tenantId !== "localhost" && tenantId !== "www") {
-    requestHeaders.set("x-tenant-id", tenantId);
-  }
-
-  return NextResponse.next({ request: { headers: requestHeaders } });
-}
-
-export const config = {
-  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
-};
-`;
-}
-
 function generateReadme(projectName: string, template: Template): string {
   return `# ${projectName}
 
@@ -384,7 +360,7 @@ ${template === "nextjs" ? "" : "├── tsconfig.json\n"}└── package.jso
 
 This project uses Stratum for hierarchical multi-tenancy:
 
-- **Tenant resolution** — via subdomain (see \`middleware.ts\`); bind it to the signed-in user once you add authentication
+- **Tenant resolution** — from the \`tenant_id\` claim of a bearer token verified with \`JWT_SECRET\` (see \`middleware.ts\`); the subdomain is only a display slug
 - **Config inheritance** — settings flow down the tenant tree with override support
 - **Permission ABAC** — role-based permissions with tenant-scoped enforcement
 
@@ -426,7 +402,7 @@ export function createProject(
     writeFile(path.join(targetDir, "tsconfig.json"), generateTsconfig(template));
   } else if (template === "nextjs") {
     writeFile(path.join(targetDir, "src", "app", "page.tsx"), generateNextjsPage(projectName));
-    writeFile(path.join(targetDir, "middleware.ts"), generateNextjsMiddleware());
+    writeFile(path.join(targetDir, "middleware.ts"), nextjsTenantMiddleware());
   }
 
   // README