wcz-layout 7.6.1 → 7.6.2

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "wcz-layout",
-  "version": "7.6.1",
+  "version": "7.6.2",
   "private": false,
+  "keywords": [
+    "tanstack-intent"
+  ],
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "!skills/_artifacts"
   ],
   "type": "module",
   "sideEffects": false,
@@ -87,6 +92,7 @@
   },
   "devDependencies": {
     "@rolldown/plugin-babel": "^0.2.2",
+    "@tanstack/intent": "^0.0.23",
     "@types/file-saver": "^2.0.7",
     "@types/node": "^25.3.5",
     "@types/react": "^19.2.14",

package/skills/api-routes/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: api-routes
+description: >
+  Create TanStack Start file-based API routes with createFileRoute or
+  createServerFn. Wire authorizationMiddleware(permissionKey) and
+  validationMiddleware(schema) in server.middleware. Use createHandlers
+  for CRUD with Drizzle queries. Response.json patterns. Covers the
+  { middleware, handler } object shape for handlers needing validation.
+  Activate when creating or modifying API endpoints or server functions.
+type: core
+library: wcz-layout
+library_version: "7.6.1"
+requires:
+  - database-schema
+sources:
+  - "wcz-layout:src/middleware/authMiddleware.ts"
+  - "wcz-layout:src/middleware/validationMiddleware.ts"
+  - "wcz-layout:src/routes/api/"
+---
+
+# API Routes & Server Functions
+
+## Setup
+
+API routes live under `src/routes/api/` and follow TanStack Router file-based conventions:
+
+```
+src/routes/api/
+├── health.ts           # GET /api/health
+└── todos/
+    ├── index.ts        # GET /api/todos, POST /api/todos
+    └── $id.ts          # GET /api/todos/:id, PUT /api/todos/:id, DELETE /api/todos/:id
+```
+
+## Core Patterns
+
+### Basic CRUD API route
+
+```typescript
+// src/routes/api/todos/index.ts
+import { createFileRoute } from "@tanstack/react-router";
+import { createHandlers } from "@tanstack/start/api";
+import { authorizationMiddleware, validationMiddleware } from "wcz-layout/middleware";
+import { todoTable } from "~/lib/db/schemas/todo";
+import { TodoInsertSchema } from "~/schemas/todo";
+
+export const Route = createFileRoute("/api/todos")({
+  server: {
+    middleware: [authorizationMiddleware("all")],
+    handlers: createHandlers({
+      GET: async ({ context }) => {
+        const items = await context.db.select().from(todoTable);
+        return Response.json(items);
+      },
+      POST: {
+        middleware: [validationMiddleware(TodoInsertSchema)],
+        handler: async ({ context }) => {
+          const [item] = await context.db.insert(todoTable).values(context.data).returning();
+          return Response.json(item, { status: 201 });
+        },
+      },
+    }),
+  },
+});
+```
+
+### Route with path parameters
+
+```typescript
+// src/routes/api/todos/$id.ts
+import { createFileRoute } from "@tanstack/react-router";
+import { createHandlers } from "@tanstack/start/api";
+import { eq } from "drizzle-orm";
+import { authorizationMiddleware, validationMiddleware } from "wcz-layout/middleware";
+import { todoTable } from "~/lib/db/schemas/todo";
+import { TodoSchema } from "~/schemas/todo";
+
+export const Route = createFileRoute("/api/todos/$id")({
+  server: {
+    middleware: [authorizationMiddleware("all")],
+    handlers: createHandlers({
+      GET: async ({ context, params }) => {
+        const [item] = await context.db.select().from(todoTable).where(eq(todoTable.id, params.id));
+        if (!item) return new Response(null, { status: 404 });
+        return Response.json(item);
+      },
+      PUT: {
+        middleware: [validationMiddleware(TodoSchema)],
+        handler: async ({ context, params }) => {
+          const [item] = await context.db
+            .update(todoTable)
+            .set(context.data)
+            .where(eq(todoTable.id, params.id))
+            .returning();
+          return Response.json(item);
+        },
+      },
+      DELETE: async ({ context, params }) => {
+        await context.db.delete(todoTable).where(eq(todoTable.id, params.id));
+        return new Response(null, { status: 204 });
+      },
+    }),
+  },
+});
+```
+
+### Server functions (RPC-style)
+
+```typescript
+import { createServerFn } from "@tanstack/start";
+
+const getTodos = createServerFn({ method: "GET" })
+  .middleware([authorizationMiddleware("all")])
+  .handler(async ({ context }) => {
+    return context.db.select().from(todoTable);
+  });
+```
+
+Server functions are typed end-to-end. Use them for operations that don't need REST semantics.
+
+### Middleware composition
+
+`authorizationMiddleware(permissionKey)` already includes `authenticationMiddleware` internally. It verifies the JWT token and injects `context.user` with a `User` object that has `hasPermission()`. If the user lacks the permission, it returns 403.
+
+`validationMiddleware(schema)` parses `request.json()` against the Zod schema and injects `context.data` with the typed result. On failure, returns 400 with the first field error.
+
+## Common Mistakes
+
+### HIGH Chaining authenticationMiddleware then authorizationMiddleware
+
+Wrong:
+
+```typescript
+middleware: [authenticationMiddleware(), authorizationMiddleware("admin")],
+```
+
+Correct:
+
+```typescript
+middleware: [authorizationMiddleware("admin")],
+```
+
+`authorizationMiddleware` already composes `authenticationMiddleware` internally. Chaining both duplicates JWT verification.
+
+Source: maintainer interview
+
+Cross-skill: See also skills/auth/SKILL.md § Common Mistakes
+
+### HIGH Forgetting validationMiddleware for mutations
+
+Wrong:
+
+```typescript
+POST: async ({ request, context }) => {
+  const data = await request.json();
+  await context.db.insert(todoTable).values(data).returning();
+},
+```
+
+Correct:
+
+```typescript
+POST: {
+  middleware: [validationMiddleware(TodoInsertSchema)],
+  handler: async ({ context }) => {
+    const [item] = await context.db
+      .insert(todoTable)
+      .values(context.data)
+      .returning();
+    return Response.json(item, { status: 201 });
+  },
+},
+```
+
+POST/PUT handlers without `validationMiddleware` accept unvalidated JSON. The middleware parses `request.json()` with Zod and injects typed `context.data`.
+
+Source: wcz-layout:src/middleware/validationMiddleware.ts
+
+### HIGH Returning data without Response.json wrapper
+
+Wrong:
+
+```typescript
+GET: async ({ context }) => {
+  return await context.db.select().from(todoTable);
+},
+```
+
+Correct:
+
+```typescript
+GET: async ({ context }) => {
+  const items = await context.db.select().from(todoTable);
+  return Response.json(items);
+},
+```
+
+TanStack Start API route handlers must return `Response` objects. Returning raw objects doesn't set content-type headers correctly.
+
+Source: consumer project example
+
+### MEDIUM Using plain function for POST instead of middleware object
+
+Wrong:
+
+```typescript
+POST: async ({ request, context }) => {
+  // no way to attach validationMiddleware
+},
+```
+
+Correct:
+
+```typescript
+POST: {
+  middleware: [validationMiddleware(TodoInsertSchema)],
+  handler: async ({ context }) => {
+    // context.data is typed from schema
+  },
+},
+```
+
+When a handler needs per-method middleware (like validation), it must use the `{ middleware, handler }` object shape, not a plain async function.
+
+Source: consumer project example
+
+### MEDIUM Using invalid permission key string
+
+`authorizationMiddleware(permissionKey)` is typed to `keyof typeof permissions` from your app's `permissions.ts`. Using a string not defined there causes a compile error.
+
+Source: wcz-layout:src/middleware/authMiddleware.ts
+
+### HIGH Tension: Simplicity vs. full-stack rigor
+
+Quick prototypes may skip middleware to move fast. Always include `authorizationMiddleware` and `validationMiddleware` from the start — retrofitting security later is error-prone.
+
+See also: skills/project-initialization/SKILL.md § Common Mistakes
+
+### HIGH Tension: Client-side first vs. server-side data
+
+`defaultSsr: false` means pages render on the client. Do not use SSR data fetching patterns (loader + dehydrate). API routes serve data to TanStack DB collections which manage client-side state.
+
+See also: skills/tanstack-db-collections/SKILL.md § Core Patterns
+
+---
+
+See also:
+
+- skills/tanstack-db-collections/SKILL.md — Collections consume these API routes via axios.
+- skills/auth/SKILL.md — Every API route uses authorizationMiddleware.
+- skills/database-schema/SKILL.md — Schemas feed into validationMiddleware.

package/skills/auth/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: auth
+description: >
+  MSAL/Entra ID authentication and AD-group authorization. Use
+  authorizationMiddleware(permissionKey) which includes authentication.
+  Configure permissions.ts and scopes.ts for type-safe keys via
+  virtual:wcz-layout. Client: getAccessToken(scopeKey). Server:
+  getAppToken(scopeKey), getTokenOnBehalfOf(userToken, scopeKey).
+  Route guards with requirePermission. Public routes via LayoutOptions.
+  serverFnAccessTokenMiddleware in start.ts. Activate when configuring
+  authentication, authorization, or token acquisition.
+type: core
+library: wcz-layout
+library_version: "7.6.1"
+sources:
+  - "wcz-layout:src/middleware/authMiddleware.ts"
+  - "wcz-layout:src/lib/auth/msalClient.ts"
+  - "wcz-layout:src/lib/auth/msalServer.ts"
+  - "wcz-layout:src/lib/auth/permissions.ts"
+  - "wcz-layout:src/lib/auth/scopes.ts"
+---
+
+# Authentication & Authorization
+
+## Setup
+
+Two configuration files define the app's security surface. Both are consumed by the `viteWczLayout()` plugin via `virtual:wcz-layout` to generate TypeScript types:
+
+```typescript
+// src/lib/auth/permissions.ts
+export const permissions = {
+  admin: ["wcz-developers"],
+  all: ["wcz-all-employees", "wscz-all-employees"],
+} as const;
+// keyof typeof permissions → "admin" | "all"
+```
+
+```typescript
+// src/lib/auth/scopes.ts
+export const scopes = {
+  graph: ["User.Read"],
+  api: ["api://wistron.com/your-app/access_as_user"],
+} as const;
+// keyof typeof scopes → "graph" | "api"
+```
+
+Permission keys map to AD group names. A user has a permission if their JWT `groups` claim contains at least one group from the array.
+
+## Core Patterns
+
+### API route authorization
+
+```typescript
+import { authorizationMiddleware } from "wcz-layout/middleware";
+
+export const Route = createFileRoute("/api/todos")({
+  server: {
+    middleware: [authorizationMiddleware("all")],
+    handlers: createHandlers({
+      GET: async ({ context }) => {
+        // context.user is typed as User with hasPermission()
+        return Response.json(await context.db.select().from(todoTable));
+      },
+    }),
+  },
+});
+```
+
+`authorizationMiddleware(permissionKey)`:
+
+1. Verifies the JWT Bearer token (includes `authenticationMiddleware` internally)
+2. Builds a `User` object with `hasPermission(key)` method
+3. Returns 401 if token is invalid, 403 if user lacks the specified permission
+4. Injects `context.user: User`
+
+### Public (authentication-only) route
+
+For routes that need authentication but no specific permission:
+
+```typescript
+import { authenticationMiddleware } from "wcz-layout/middleware";
+
+export const Route = createFileRoute("/api/profile")({
+  server: {
+    middleware: [authenticationMiddleware()],
+    handlers: createHandlers({
+      GET: async ({ context }) => {
+        // context.user — any authenticated user
+        return Response.json(context.user);
+      },
+    }),
+  },
+});
+```
+
+For optional authentication (public endpoints that may have user context):
+
+```typescript
+middleware: [authenticationMiddleware({ optional: true })],
+// context.user is User | null
+```
+
+### Route-level permission guard
+
+```typescript
+import { requirePermission } from "wcz-layout/utils";
+
+export const Route = createFileRoute("/admin/")({
+  beforeLoad: requirePermission("admin"),
+  component: AdminPage,
+});
+```
+
+`requirePermission` runs in `beforeLoad` and redirects unauthorized users.
+
+### Client-side token acquisition
+
+```typescript
+import { getAccessToken } from "wcz-layout/utils";
+
+// In an axios interceptor or client-side code
+const token = await getAccessToken("api");
+```
+
+`getAccessToken` is a client-only function (uses MSAL `PublicClientApplication`). It acquires tokens silently and triggers interaction listeners on `InteractionRequiredAuthError`.
+
+### Server-side token acquisition
+
+```typescript
+import { getAppToken, getTokenOnBehalfOf } from "wcz-layout/utils";
+
+// App-only token (client credentials flow — no user context)
+const appToken = await getAppToken("graph");
+
+// On-behalf-of flow (exchange user token for downstream API token)
+const oboToken = await getTokenOnBehalfOf(userBearerToken, "graph");
+```
+
+Both are server-only functions using MSAL `ConfidentialClientApplication`.
+
+### Global server function middleware
+
+```typescript
+// src/start.ts
+import { serverFnAccessTokenMiddleware } from "wcz-layout/middleware";
+
+export const startInstance = createStart(() => ({
+  defaultSsr: false,
+  functionMiddleware: [serverFnAccessTokenMiddleware("api")],
+}));
+```
+
+`serverFnAccessTokenMiddleware` attaches the Bearer token to all server function calls globally. Without it, server functions won't include authorization headers.
+
+### Getting the current user
+
+```typescript
+import { getUser } from "wcz-layout/utils";
+
+// Isomorphic — works on client (returns User | null) and server (returns null)
+const user = getUser();
+```
+
+On the client, `getUser` reads the active MSAL account's ID token claims.
+
+## Common Mistakes
+
+### HIGH Chaining authenticationMiddleware before authorizationMiddleware
+
+Wrong:
+
+```typescript
+middleware: [authenticationMiddleware(), authorizationMiddleware("admin")],
+```
+
+Correct:
+
+```typescript
+middleware: [authorizationMiddleware("admin")],
+```
+
+`authorizationMiddleware` already composes `authenticationMiddleware` internally. Chaining both duplicates JWT verification.
+
+Source: maintainer interview
+
+Cross-skill: See also skills/api-routes/SKILL.md § Common Mistakes
+
+### CRITICAL Calling getAccessToken on the server
+
+Wrong:
+
+```typescript
+// In a server handler or serverFn
+const token = await getAccessToken("api");
+```
+
+Correct:
+
+```typescript
+// Server-side — use app token or OBO
+const token = await getAppToken("api");
+// or
+const token = await getTokenOnBehalfOf(userToken, "api");
+```
+
+`getAccessToken` is `createClientOnlyFn` — it uses MSAL `PublicClientApplication` which only exists in the browser. Calling it on the server throws.
+
+Source: wcz-layout:src/lib/auth/msalClient.ts
+
+### HIGH Forgetting serverFnAccessTokenMiddleware in start.ts
+
+Wrong:
+
+```typescript
+// src/start.ts
+export const startInstance = createStart(() => ({
+  defaultSsr: false,
+  // Missing functionMiddleware
+}));
+```
+
+Correct:
+
+```typescript
+// src/start.ts
+export const startInstance = createStart(() => ({
+  defaultSsr: false,
+  functionMiddleware: [serverFnAccessTokenMiddleware("api")],
+}));
+```
+
+Without `serverFnAccessTokenMiddleware`, server function calls won't include the Authorization header, causing 401 errors.
+
+Source: wcz-layout:src/start.ts
+
+### MEDIUM Using string literals for permission/scope keys
+
+Wrong:
+
+```typescript
+authorizationMiddleware("superadmin"); // not in permissions.ts → compile error
+getAccessToken("custom-api"); // not in scopes.ts → compile error
+```
+
+Correct:
+
+```typescript
+// First add to permissions.ts / scopes.ts, then use the typed key
+authorizationMiddleware("admin");
+getAccessToken("api");
+```
+
+Permission and scope keys are typed from the `as const` exports via `virtual:wcz-layout`. Using arbitrary strings causes TypeScript compile errors.
+
+Source: wcz-layout:src/types/wcz-layout.d.ts
+
+### HIGH Missing Entra redirect URI configuration
+
+The MSAL `redirectUri` defaults to `"/"`. The Entra app registration must include this exact redirect URI, or the authentication flow fails silently with a redirect error.
+
+Source: wcz-layout:src/routes/runbook/entra-id.tsx
+
+---
+
+See also:
+
+- skills/api-routes/SKILL.md — Every API route uses authorizationMiddleware.
+- skills/layout-navigation/SKILL.md — publicRoutes bypass auth; permission guards need auth context.