wcz-layout 8.0.2 → 8.0.3

package/skills/auth/SKILL.md

@@ -1,268 +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.
+---
+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.

package/dist/FileMeta-D9HyhrGi.js

@@ -1,42 +0,0 @@
-import * as z$2 from "zod";
-import z$1 from "zod";
-//#region src/models/approval/ApprovalStatus.ts
-const ApprovalStatus = z$1.enum([
-	"WaitingForApproval",
-	"Approved",
-	"PartiallyApproved",
-	"Rejected",
-	"Withdrawn",
-	"Cancelled"
-]);
-//#endregion
-//#region src/models/approval/ApprovalStepResult.ts
-const ApprovalStepResult = z$1.enum([
-	"NotAvailable",
-	"FutureApproval",
-	"WaitingForApproval",
-	"Approved",
-	"Rejected",
-	"Skipped",
-	"Withdrawn",
-	"Cancelled"
-]);
-//#endregion
-//#region src/models/file/FileMeta.ts
-const FileMetaSchema = z$2.object({
-	id: z$2.uuid(),
-	subId: z$2.uuid(),
-	appName: z$2.string().trim().min(1).max(255),
-	fileName: z$2.string().trim().min(1).max(255),
-	fileExtension: z$2.string().trim().min(1).max(255),
-	fileSize: z$2.number().min(0),
-	mediaSubType: z$2.string().trim().min(1).max(255),
-	mediaType: z$2.string().trim().min(1).max(255),
-	mimeType: z$2.string().trim().min(1).max(255),
-	createdBy: z$2.string().trim().min(1).max(255),
-	createdDate: z$2.date()
-});
-//#endregion
-export { ApprovalStepResult as n, ApprovalStatus as r, FileMetaSchema as t };
-
-//# sourceMappingURL=FileMeta-D9HyhrGi.js.map

package/dist/FileMeta-D9HyhrGi.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"FileMeta-D9HyhrGi.js","names":["z","ApprovalStatus","enum","z","ApprovalStepResult","enum","z","FileMetaSchema","object","id","uuid","subId","appName","string","trim","min","max","fileName","fileExtension","fileSize","number","mediaSubType","mediaType","mimeType","createdBy","createdDate","date","FileMeta","infer"],"sources":["../src/models/approval/ApprovalStatus.ts","../src/models/approval/ApprovalStepResult.ts","../src/models/file/FileMeta.ts"],"sourcesContent":["import z from \"zod\";\n\nexport const ApprovalStatus = z.enum([\n  \"WaitingForApproval\",\n  \"Approved\",\n  \"PartiallyApproved\",\n  \"Rejected\",\n  \"Withdrawn\",\n  \"Cancelled\",\n]);\n","import z from \"zod\";\n\nexport const ApprovalStepResult = z.enum([\n  \"NotAvailable\",\n  \"FutureApproval\",\n  \"WaitingForApproval\",\n  \"Approved\",\n  \"Rejected\",\n  \"Skipped\",\n  \"Withdrawn\",\n  \"Cancelled\",\n]);\n","import * as z from \"zod\";\n\nexport const FileMetaSchema = z.object({\n  id: z.uuid(),\n  subId: z.uuid(),\n  appName: z.string().trim().min(1).max(255),\n  fileName: z.string().trim().min(1).max(255),\n  fileExtension: z.string().trim().min(1).max(255),\n  fileSize: z.number().min(0),\n  mediaSubType: z.string().trim().min(1).max(255),\n  mediaType: z.string().trim().min(1).max(255),\n  mimeType: z.string().trim().min(1).max(255),\n  createdBy: z.string().trim().min(1).max(255),\n  createdDate: z.date(),\n});\n\nexport type FileMeta = z.infer<typeof FileMetaSchema>;\n"],"mappings":";;;AAEA,MAAaC,iBAAiBD,IAAEE,KAAK;CACnC;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;ACPF,MAAaE,qBAAqBD,IAAEE,KAAK;CACvC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;ACTF,MAAaE,iBAAiBD,IAAEE,OAAO;CACrCC,IAAIH,IAAEI,MAAM;CACZC,OAAOL,IAAEI,MAAM;CACfE,SAASN,IAAEO,QAAQ,CAACC,MAAM,CAACC,IAAI,EAAE,CAACC,IAAI,IAAI;CAC1CC,UAAUX,IAAEO,QAAQ,CAACC,MAAM,CAACC,IAAI,EAAE,CAACC,IAAI,IAAI;CAC3CE,eAAeZ,IAAEO,QAAQ,CAACC,MAAM,CAACC,IAAI,EAAE,CAACC,IAAI,IAAI;CAChDG,UAAUb,IAAEc,QAAQ,CAACL,IAAI,EAAE;CAC3BM,cAAcf,IAAEO,QAAQ,CAACC,MAAM,CAACC,IAAI,EAAE,CAACC,IAAI,IAAI;CAC/CM,WAAWhB,IAAEO,QAAQ,CAACC,MAAM,CAACC,IAAI,EAAE,CAACC,IAAI,IAAI;CAC5CO,UAAUjB,IAAEO,QAAQ,CAACC,MAAM,CAACC,IAAI,EAAE,CAACC,IAAI,IAAI;CAC3CQ,WAAWlB,IAAEO,QAAQ,CAACC,MAAM,CAACC,IAAI,EAAE,CAACC,IAAI,IAAI;CAC5CS,aAAanB,IAAEoB,MAAK;CACrB,CAAC"}