create-restack-pattern 0.1.8 → 0.2.1

package/template/{backend → base/backend}/src/hono-app.ts

@@ -4,9 +4,9 @@ import { csrf } from "hono/csrf"
 import { logger as honoLogger } from "hono/logger"
 import { requestId } from "hono/request-id"
 import { env } from "./config/env.js"
-import { logger, type AppVariables } from "./utils/logger.js"
 import { authRoutes } from "./domains/auth/auth.routes.js"
 import { userRoutes } from "./domains/user/user.routes.js"
+import { type AppVariables, logger } from "./utils/logger.js"
 
 /**
  * Hono application instance — routes, middleware, everything except the transport.
@@ -16,9 +16,7 @@ import { userRoutes } from "./domains/user/user.routes.js"
  */
 export const app = new Hono<{ Variables: AppVariables }>()
 
-const allowedOrigins = env.FRONTEND_URL
-  .split(",")
-  .map((url) => url.trim())
+const allowedOrigins = env.FRONTEND_URL.split(",").map((url) => url.trim())
 
 // 1. Generate unique request IDs for all API calls
 app.use("/api/*", requestId())
@@ -43,7 +41,7 @@ app.use(
   "/api/*",
   honoLogger((...args) => {
     logger.info(args.join(" "))
-  })
+  }),
 )
 
 app.use(
@@ -51,21 +49,18 @@ app.use(
   cors({
     origin: allowedOrigins,
     credentials: true,
-  })
+  }),
 )
 
 app.use(
   "/api/*",
   csrf({
     origin: allowedOrigins,
-  })
+  }),
 )
 
-const routes = app
-  .route("/api/auth", authRoutes)
-  .route("/api/user", userRoutes)
+const routes = app.route("/api/auth", authRoutes).route("/api/user", userRoutes)
 
 app.get("/", (c) => c.json({ status: "ok" }))
 
 export type AppType = typeof routes
-

package/template/base/backend/src/infra/middlewares/require-auth.test.ts

@@ -0,0 +1,91 @@
+import { Hono } from "hono"
+import { SignJWT } from "jose"
+import { describe, expect, it } from "vitest"
+import { env } from "../../config/env.js"
+import type { AuthVariables } from "./require-auth.js"
+import { requireAuth } from "./require-auth.js"
+
+const secret = new TextEncoder().encode(env.JWT_SECRET)
+
+const signTestToken = (payload: Record<string, unknown>, expiresIn = "15m") =>
+  new SignJWT(payload)
+    .setProtectedHeader({ alg: "HS256" })
+    .setExpirationTime(expiresIn)
+    .sign(secret)
+
+function buildApp() {
+  const app = new Hono<{ Variables: AuthVariables }>()
+  app.use("/protected", requireAuth)
+  app.get("/protected", (c) => c.json({ user: c.get("user"), authMethod: c.get("authMethod") }))
+  return app
+}
+
+describe("requireAuth", () => {
+  it("returns 401 when no token is present in cookie or header", async () => {
+    const res = await buildApp().request("/protected")
+    expect(res.status).toBe(401)
+  })
+
+  it("returns 401 when the token is garbage", async () => {
+    const res = await buildApp().request("/protected", {
+      headers: { Cookie: "access_token=not-a-real-token" },
+    })
+    expect(res.status).toBe(401)
+  })
+
+  it("returns 401 when the token is expired", async () => {
+    const expired = await signTestToken({ sub: "user-1", email: "a@b.com", role: "user" }, "-1s")
+    const res = await buildApp().request("/protected", {
+      headers: { Cookie: `access_token=${expired}` },
+    })
+    expect(res.status).toBe(401)
+  })
+
+  it("calls next() and exposes payload with authMethod='cookie' when cookie token is valid", async () => {
+    const token = await signTestToken({ sub: "user-1", email: "a@b.com", role: "user" })
+    const res = await buildApp().request("/protected", {
+      headers: { Cookie: `access_token=${token}` },
+    })
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.user.sub).toBe("user-1")
+    expect(body.user.email).toBe("a@b.com")
+    expect(body.authMethod).toBe("cookie")
+  })
+
+  it("calls next() and exposes payload with authMethod='bearer' when Authorization header is valid", async () => {
+    const token = await signTestToken({ sub: "user-2", email: "b@b.com", role: "admin" })
+    const res = await buildApp().request("/protected", {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.user.sub).toBe("user-2")
+    expect(body.user.email).toBe("b@b.com")
+    expect(body.user.role).toBe("admin")
+    expect(body.authMethod).toBe("bearer")
+  })
+
+  it("prefers Bearer token over cookie when both are supplied", async () => {
+    const cookieToken = await signTestToken({
+      sub: "user-cookie",
+      email: "cookie@b.com",
+      role: "user",
+    })
+    const bearerToken = await signTestToken({
+      sub: "user-bearer",
+      email: "bearer@b.com",
+      role: "admin",
+    })
+    const res = await buildApp().request("/protected", {
+      headers: {
+        Cookie: `access_token=${cookieToken}`,
+        Authorization: `Bearer ${bearerToken}`,
+      },
+    })
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.user.sub).toBe("user-bearer")
+    expect(body.authMethod).toBe("bearer")
+  })
+})

package/template/base/backend/src/infra/middlewares/require-auth.ts

@@ -0,0 +1,63 @@
+import type { MiddlewareHandler } from "hono"
+import { getCookie } from "hono/cookie"
+import { authService } from "../../domains/auth/auth.service.js"
+import type { AppVariables } from "../../utils/logger.js"
+
+export type AuthMethod = "bearer" | "cookie"
+
+export interface AuthVariables extends AppVariables {
+  authMethod?: AuthMethod
+}
+
+/**
+ * Authentication guard middleware.
+ * Enforces the presence and validity of the short-lived JWT access token
+ * from Authorization: Bearer <token> header or request cookies (Hybrid Auth).
+ * Resolves the payload, binds it to Hono context variables (`c.get("user")`),
+ * and attaches the authenticated userId and authMethod to the request logger context.
+ *
+ * Usage:
+ * Apply to any endpoint requiring authentication (e.g. `userRoutes.get("/me", requireAuth, ...)`).
+ */
+export const requireAuth: MiddlewareHandler<{ Variables: AuthVariables }> = async (c, next) => {
+  let token: string | undefined
+  let authMethod: AuthMethod | undefined
+
+  // 1. Inspect Authorization header (Bearer token) first
+  const authHeader = c.req.header("Authorization") || c.req.header("authorization")
+  if (authHeader?.toLowerCase().startsWith("bearer ")) {
+    token = authHeader.slice(7).trim()
+    authMethod = "bearer"
+  }
+
+  // 2. Fall back to access_token cookie
+  if (!token) {
+    const cookieToken = getCookie(c, "access_token")
+    if (cookieToken) {
+      token = cookieToken
+      authMethod = "cookie"
+    }
+  }
+
+  if (!token || !authMethod) {
+    return c.json({ error: "Unauthorized" }, 401)
+  }
+
+  try {
+    // Decode and verify signature & expiration
+    const payload = await authService.verifyAccessToken(token)
+    c.set("user", payload)
+    c.set("authMethod", authMethod)
+
+    // Enrich the child logger with the user's ID and authMethod for all downstream actions
+    const reqLogger = c.get("logger")
+    if (reqLogger) {
+      c.set("logger", reqLogger.child({ userId: Number(payload.sub), authMethod }))
+    }
+  } catch {
+    // Return standard 401 response on invalid / expired signature
+    return c.json({ error: "Unauthorized" }, 401)
+  }
+
+  return await next()
+}

package/template/base/backend/src/infra/middlewares/require-role.test.ts

@@ -0,0 +1,66 @@
+import { Hono } from "hono"
+import { describe, expect, it } from "vitest"
+import type { AppVariables } from "../../utils/logger.js"
+import { requireRole } from "./require-role.js"
+
+function buildApp(
+  allowedRoles: string[],
+  initialUser?: { sub: string; email: string; role: string },
+) {
+  const app = new Hono<{ Variables: AppVariables }>()
+
+  if (initialUser) {
+    app.use("/admin/*", async (c, next) => {
+      c.set("user", initialUser)
+      await next()
+    })
+  }
+
+  app.use("/admin/dashboard", requireRole(...allowedRoles))
+  app.get("/admin/dashboard", (c) => c.json({ access: "granted", role: c.get("user")?.role }))
+
+  return app
+}
+
+describe("requireRole middleware", () => {
+  it("returns 401 when user is not authenticated in context", async () => {
+    const app = buildApp(["admin"])
+    const res = await app.request("/admin/dashboard")
+
+    expect(res.status).toBe(401)
+    const body = await res.json()
+    expect(body.error).toBe("Unauthorized")
+  })
+
+  it("returns 403 when user role does not match required role", async () => {
+    const app = buildApp(["admin"], { sub: "1", email: "user@test.com", role: "user" })
+    const res = await app.request("/admin/dashboard")
+
+    expect(res.status).toBe(403)
+    const body = await res.json()
+    expect(body.error).toBe("Forbidden: insufficient permissions")
+  })
+
+  it("returns 200 when user has the exact required role", async () => {
+    const app = buildApp(["admin"], { sub: "1", email: "admin@test.com", role: "admin" })
+    const res = await app.request("/admin/dashboard")
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.access).toBe("granted")
+    expect(body.role).toBe("admin")
+  })
+
+  it("returns 200 when user matches one of several permitted roles", async () => {
+    const app = buildApp(["editor", "admin", "superadmin"], {
+      sub: "2",
+      email: "editor@test.com",
+      role: "editor",
+    })
+    const res = await app.request("/admin/dashboard")
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.access).toBe("granted")
+  })
+})

package/template/base/backend/src/infra/middlewares/require-role.ts

@@ -0,0 +1,34 @@
+import type { MiddlewareHandler } from "hono"
+import type { AppVariables } from "../../utils/logger.js"
+
+/**
+ * Role-Based Access Control (RBAC) guard middleware.
+ * Verifies that the authenticated user possesses one of the allowed roles.
+ * Must be mounted AFTER `requireAuth` in the middleware chain.
+ *
+ * @param allowedRoles List of roles permitted to access the route (e.g. "admin", "moderator")
+ * @returns 401 if user is not authenticated, 403 if user lacks required role, otherwise calls next()
+ */
+export const requireRole = (
+  ...allowedRoles: string[]
+): MiddlewareHandler<{ Variables: AppVariables }> => {
+  return async (c, next) => {
+    const user = c.get("user")
+    if (!user) {
+      return c.json({ error: "Unauthorized" }, 401)
+    }
+
+    if (!allowedRoles.includes(user.role)) {
+      const reqLogger = c.get("logger")
+      if (reqLogger) {
+        reqLogger.warn(
+          { userId: user.sub, userRole: user.role, requiredRoles: allowedRoles },
+          "Access forbidden: insufficient role permissions",
+        )
+      }
+      return c.json({ error: "Forbidden: insufficient permissions" }, 403)
+    }
+
+    return await next()
+  }
+}

package/template/{backend → base/backend}/src/utils/logger.ts

@@ -14,23 +14,20 @@ if (env.LOG_FILE_PATH) {
   // If a log file path is provided, stream to both stdout (console) and the file
   const streams = [
     { stream: process.stdout },
-    { stream: pino.destination({ dest: env.LOG_FILE_PATH, sync: false }) }
+    { stream: pino.destination({ dest: env.LOG_FILE_PATH, sync: false }) },
   ]
   loggerInstance = pino({ level }, pino.multistream(streams))
 } else {
   // Otherwise default to standard stdout (with pretty formatting in local development)
-  loggerInstance = pino({
-    level,
-    transport:
-      env.NODE_ENV === "production"
-        ? undefined
-        : { target: "pino-pretty", options: { colorize: true } },
-  })
+  const options: pino.LoggerOptions = { level }
+  if (env.NODE_ENV !== "production") {
+    options.transport = { target: "pino-pretty", options: { colorize: true } }
+  }
+  loggerInstance = pino(options)
 }
 
 export const logger = loggerInstance
 
-
 import type { Logger } from "pino"
 import type { AuthTokenPayload } from "../domains/auth/auth.types.js"
 
@@ -38,5 +35,5 @@ export type AppVariables = {
   requestId: string
   logger: Logger
   user?: AuthTokenPayload
+  authMethod?: "bearer" | "cookie"
 }
-

package/template/base/backend/src/utils/uuid.test.ts

@@ -0,0 +1,37 @@
+import { isUuidv7, uuidv7 } from "@restack/shared"
+import { describe, expect, it } from "vitest"
+
+describe("uuidv7 generator", () => {
+  it("generates a valid UUIDv7 string", () => {
+    const id = uuidv7()
+    expect(isUuidv7(id)).toBe(true)
+  })
+
+  it("conforms to version 7 and RFC 9562 variant format", () => {
+    const id = uuidv7()
+    const parts = id.split("-")
+    expect(parts).toHaveLength(5)
+    // 3rd part starts with '7' (version 7)
+    expect(parts[2]?.charAt(0)).toBe("7")
+    // 4th part starts with 8, 9, a, or b (variant 1)
+    expect(["8", "9", "a", "b"]).toContain(parts[3]?.charAt(0).toLowerCase())
+  })
+
+  it("produces chronologically ordered identifiers", async () => {
+    const ids: string[] = []
+    for (let i = 0; i < 20; i++) {
+      ids.push(uuidv7())
+      // short delay to test monotonic sorting
+      await new Promise((r) => setTimeout(r, 2))
+    }
+
+    const sorted = [...ids].sort()
+    expect(ids).toEqual(sorted)
+  })
+
+  it("isUuidv7 rejects invalid UUID formats", () => {
+    expect(isUuidv7("not-a-uuid")).toBe(false)
+    // UUIDv4 (version nibble is 4, not 7)
+    expect(isUuidv7("550e8400-e29b-41d4-a716-446655440000")).toBe(false)
+  })
+})

package/template/{backend → base/backend}/tsconfig.json

@@ -3,6 +3,10 @@
     "target": "ESNext",
     "module": "NodeNext",
     "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
     "verbatimModuleSyntax": true,
     "skipLibCheck": true,
     "types": [

package/template/base/frontend/AGENTS.md

@@ -0,0 +1,11 @@
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+
+## Guardrails
+- **Typed Routes Active**: All internal links `<Link href="...">` are strictly checked at compile time. Never use untyped arbitrary string paths.
+- **Typed Environment**: Always import `env` from `@/env` (`@t3-oss/env-nextjs`). Never read raw `process.env`.
+- **Semi-DDD Boundary**: Keep `app/` strictly for routing/metadata only. Delegate all rendering to `domains/[feature]/components`.
+<!-- END:nextjs-agent-rules -->
+

package/template/{frontend → base/frontend}/app/(auth)/login/page.tsx

@@ -4,7 +4,7 @@ import logo from "@/public/logo.png"
 
 /**
  * Next.js Router Page: Login
- * 
+ *
  * Semi-DDD rules:
  * - Files in `frontend/app/` are strictly for layout, routing config, metadata, or entry gates.
  * - Do not implement custom JSX layouts, forms, state, or complex components here.

package/template/{frontend → base/frontend}/app/(auth)/register/page.tsx

@@ -4,7 +4,7 @@ import logo from "@/public/logo.png"
 
 /**
  * Next.js Router Page: Register
- * 
+ *
  * Semi-DDD rules:
  * - Files in `frontend/app/` are strictly for layout, routing config, metadata, or entry gates.
  * - Do not implement custom JSX layouts, forms, state, or complex components here.

package/template/{frontend → base/frontend}/app/globals.css

@@ -128,4 +128,4 @@
   html {
     @apply font-sans;
   }
-}
+}

package/template/{frontend → base/frontend}/app/layout.tsx

@@ -1,16 +1,16 @@
-import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
-import "./globals.css";
+import type { Metadata } from "next"
+import { Geist, Geist_Mono } from "next/font/google"
+import "./globals.css"
 
 const geistSans = Geist({
   variable: "--font-geist-sans",
   subsets: ["latin"],
-});
+})
 
 const geistMono = Geist_Mono({
   variable: "--font-geist-mono",
   subsets: ["latin"],
-});
+})
 
 export const metadata: Metadata = {
   title: "RestackPattern",
@@ -18,19 +18,16 @@ export const metadata: Metadata = {
   icons: {
     icon: "/favicon.ico",
   },
-};
+}
 
 export default function RootLayout({
   children,
 }: Readonly<{
-  children: React.ReactNode;
+  children: React.ReactNode
 }>) {
   return (
-    <html
-      lang="en"
-      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
-    >
+    <html lang="en" className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}>
       <body className="min-h-full flex flex-col">{children}</body>
     </html>
-  );
+  )
 }

package/template/{frontend → base/frontend}/app/page.tsx

@@ -1,11 +1,11 @@
-import Link from "next/link"
 import Image from "next/image"
+import Link from "next/link"
 import { Button } from "@/components/ui/button"
 import logo from "@/public/logo.png"
 
 /**
  * Next.js Router Page: Landing Page (root)
- * 
+ *
  * Semi-DDD rules:
  * - Files in `frontend/app/` are strictly for layout, routing config, metadata, or entry gates.
  * - Do not implement custom JSX layouts, forms, state, or complex components here.

package/template/{frontend → base/frontend}/app/profile/page.tsx

@@ -1,10 +1,10 @@
-import { Button } from "@/components/ui/button";
+import Link from "next/link"
+import { Button } from "@/components/ui/button"
 import { ProfileCard } from "@/domains/user/components/profile-card"
-import Link from "next/link";
 
 /**
  * Next.js Router Page: Profile
- * 
+ *
  * Semi-DDD rules:
  * - Files in `frontend/app/` are strictly for layout, routing config, metadata, or entry gates.
  * - Do not implement custom JSX layouts, forms, state, or complex components here.

package/template/{frontend → base/frontend}/components/ui/button.tsx

@@ -1,6 +1,6 @@
-import * as React from "react"
 import { cva, type VariantProps } from "class-variance-authority"
 import { Slot } from "radix-ui"
+import type * as React from "react"
 
 import { cn } from "@/lib/utils"
 
@@ -38,7 +38,7 @@ const buttonVariants = cva(
       variant: "default",
       size: "default",
     },
-  }
+  },
 )
 
 function Button({

package/template/{frontend → base/frontend}/components/ui/card.tsx

@@ -1,4 +1,4 @@
-import * as React from "react"
+import type * as React from "react"
 
 import { cn } from "@/lib/utils"
 
@@ -13,7 +13,7 @@ function Card({
       data-size={size}
       className={cn(
         "group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded-xl bg-card py-(--card-spacing) text-sm text-card-foreground ring-1 ring-foreground/10 [--card-spacing:--spacing(4)] has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(3)] data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
-        className
+        className,
       )}
       {...props}
     />
@@ -26,7 +26,7 @@ function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="card-header"
       className={cn(
         "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-(--card-spacing)",
-        className
+        className,
       )}
       {...props}
     />
@@ -39,7 +39,7 @@ function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="card-title"
       className={cn(
         "font-heading text-base leading-snug font-medium group-data-[size=sm]/card:text-sm",
-        className
+        className,
       )}
       {...props}
     />
@@ -60,10 +60,7 @@ function CardAction({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="card-action"
-      className={cn(
-        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
-        className
-      )}
+      className={cn("col-start-2 row-span-2 row-start-1 self-start justify-self-end", className)}
       {...props}
     />
   )
@@ -71,11 +68,7 @@ function CardAction({ className, ...props }: React.ComponentProps<"div">) {
 
 function CardContent({ className, ...props }: React.ComponentProps<"div">) {
   return (
-    <div
-      data-slot="card-content"
-      className={cn("px-(--card-spacing)", className)}
-      {...props}
-    />
+    <div data-slot="card-content" className={cn("px-(--card-spacing)", className)} {...props} />
   )
 }
 
@@ -85,19 +78,11 @@ function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="card-footer"
       className={cn(
         "flex items-center rounded-b-xl border-t bg-muted/50 p-(--card-spacing)",
-        className
+        className,
       )}
       {...props}
     />
   )
 }
 
-export {
-  Card,
-  CardHeader,
-  CardFooter,
-  CardTitle,
-  CardAction,
-  CardDescription,
-  CardContent,
-}
+export { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle }

package/template/{frontend → base/frontend}/components/ui/input.tsx

@@ -1,4 +1,4 @@
-import * as React from "react"
+import type * as React from "react"
 
 import { cn } from "@/lib/utils"
 
@@ -9,7 +9,7 @@ function Input({ className, type, ...props }: React.ComponentProps<"input">) {
       data-slot="input"
       className={cn(
         "h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
-        className
+        className,
       )}
       {...props}
     />

package/template/{frontend → base/frontend}/components/ui/label.tsx

@@ -1,20 +1,17 @@
 "use client"
 
-import * as React from "react"
 import { Label as LabelPrimitive } from "radix-ui"
+import type * as React from "react"
 
 import { cn } from "@/lib/utils"
 
-function Label({
-  className,
-  ...props
-}: React.ComponentProps<typeof LabelPrimitive.Root>) {
+function Label({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>) {
   return (
     <LabelPrimitive.Root
       data-slot="label"
       className={cn(
         "flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
-        className
+        className,
       )}
       {...props}
     />