@close-by/clay 0.2.22 → 0.2.24

package/docs/api.md

@@ -99,6 +99,7 @@ ui.run({
 | `sessionAbsoluteMs` | `number` | | Optional: clear auth + redirect after this time since hello |
 | `sessionExpiredPath` | `string` | `'/'` | SPA path after idle/absolute expiry |
 | `resolveUserId` | `(ctx) => …` | cookie helper when `authSecret` set | Trusted identity on WebSocket hello |
+| `getRoles` | `() => string \| string[] \| null` | | Current user's roles. Enables `ui.forRoles`, `ui.hasRole`, `.roles()`, and default filtering in `ui.navFromPages()` / `requireRole` — see [Production — role-based content](./production.md#role-based-content) |
 | `routes` | `Record<path, (req, ctx) => Response>` | | Extra HTTP routes, exact path, any method. `ctx.signIn(userId, location)` / `ctx.signOut(location)` redirect and set/clear the auth cookie. Used for OAuth callbacks — see [Production — single sign-on](./production.md#single-sign-on-oidc) |
 
 #### Auth cookie recipe
@@ -1816,6 +1817,8 @@ onClick: async () => {
 | `ui.updateUrlSearch(patch, opts?)` | `void` | Merge query keys; `null`/`''` deletes |
 | `ui.urlState(defaults, opts?)` | reactive object | `ui.state` + hydrate/sync query string (prefer this) |
 | `ui.openExternal(url)` | `void` | `window.open` in a new tab (`noopener`) |
+| `ui.forRoles(roles, build, fallback?)` | `void` | Run `build` only for users with one of `roles`, else `fallback`; skipped content never reaches the browser |
+| `ui.hasRole(roles)` | `boolean` | Current user has one of `roles` |
 | `ui.redirect(url)` | `void` | Full-page navigation in the current tab (`location.assign`) — for sign-in routes / external pages; use `ui.navigate` for app pages |
 | `ui.theme.set(mode)` | `void` | Push `light` \| `dark` \| `system` to this client |
 | `ui.theme.get()` | `ThemeMode \| null` | Last value set on this session |
@@ -2057,6 +2060,7 @@ Returned by every `ui.*` factory.
 | Method | Description |
 |--------|-------------|
 | `.classes(...names)` | Append Tailwind/utility classes; patches `className` |
+| `.roles(list)` | Keep only for users with one of the roles (`ui.run({ getRoles })`); otherwise removed before it reaches the client. Call while building |
 | `.style(string \| Record)` | Set inline style string / object |
 | `.on(event, handler)` | Register additional event handler |
 | `.setText(text)` | Set `props.text` and patch |

package/docs/production.md

@@ -65,6 +65,35 @@ ui.page('/admin', () => {
 
 Nav filtering is not authorization. Always guard pages that must not leak data.
 
+### Role-based content
+
+Tell Clay how to read the current user's roles once, then show or hide parts of a page by role:
+
+```ts
+ui.run({
+  authSecret,
+  getRoles: () => getSessionUser()?.roles ?? [], // string, string[] or null
+});
+
+ui.page('/projects', () => {
+  if (!requireAuth()) return;
+
+  ui.forRoles(['admin', 'manager'], () => {
+    ui.button('Delete project', { onClick: deleteProject });
+    ui.dataTable(auditRows);
+  }, () => ui.label('Ask an admin for access')); // optional fallback
+
+  ui.button('Approve', { onClick: approve }).roles(['admin']);
+  if (ui.hasRole('admin')) { /* plain check */ }
+});
+```
+
+- Checks run on the server while the page builds. Hidden content is never sent to the browser, and its handlers don't exist, so they can't be triggered.
+- With `getRoles` set, `ui.navFromPages()` (no arguments) and `requireRole(...)` use the same roles — no need to pass them separately.
+- Roles are read when the page builds. Signing in or out reconnects and rebuilds, so the UI follows. A role changed while someone is signed in applies on their next page load.
+- Without `getRoles`, role checks treat the user as having no roles (fail closed) and log a warning once.
+- Still check the role inside handlers that change data — cheap protection against mistakes elsewhere.
+
 ## Single sign-on (OIDC)
 
 `@close-by/clay-auth` signs users in with any OpenID Connect provider (authorization code + PKCE). The provider is only used to sign in: once its ID token is verified, Clay sets its usual signed auth cookie, so everything above (`resolveUserId`, guards, idle expiry) works unchanged and there are no provider tokens to refresh.
@@ -95,6 +124,8 @@ ui.button('Sign in', { onClick: () => ui.redirect('/auth/login?returnTo=/reports
 ui.button('Sign out', { onClick: () => ui.redirect('/auth/logout') });
 ```
 
+All options are plain values — `process.env` above is just one source. Pass strings from a config file, a secrets manager, or literals; the library reads no environment variables itself. Keep `clientSecret` and `authSecret` out of source control.
+
 Routes: `GET /auth/login` (accepts `?returnTo=/path`, same-origin paths only) → provider → `GET /auth/callback` → cookie set → `returnTo`. `GET /auth/logout` clears the cookie and goes to the provider's sign-out. Failures land on `errorPath?auth_error=<state|expired|invalid_token|denied|provider|…>`.
 
 What is checked: `state` (one-shot HttpOnly cookie scoped to the callback path, 10 min), PKCE `S256`, ID token RS256 signature against the provider's JWKS (re-fetched on unknown `kid`), `iss`, `aud`, `exp`/`iat` (60 s skew), and `nonce`.
@@ -105,7 +136,7 @@ What is checked: `state` (one-shot HttpOnly cookie scoped to the callback path,
 
 **Behind an authenticating proxy:** if a reverse proxy or load balancer already signs users in and forwards a signed identity header, skip the routes and read (and verify) that header in `resolveUserId`.
 
-The demo enables a "Sign in with SSO" button on `/examples/auth/login` when `OIDC_ISSUER` and `OIDC_CLIENT_ID` are set (see `apps/demo/src/examples/_oidc.ts` for the optional variables).
+The demo (which, unlike the library, reads env variables for convenience) enables a "Sign in with SSO" button on `/examples/auth/login` when `OIDC_ISSUER` and `OIDC_CLIENT_ID` are set (see `apps/demo/src/examples/_oidc.ts` for the optional variables).
 
 ## Rate limits & abuse
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "NiceGUI-like ui.* facade for Clay apps",
   "license": "MIT",
   "type": "module",
@@ -37,10 +37,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@close-by/clay-compiler": "0.2.22",
-    "@close-by/clay-core": "0.2.22",
-    "@close-by/clay-components": "0.2.22",
-    "@close-by/clay-server": "0.2.22",
+    "@close-by/clay-compiler": "0.2.24",
+    "@close-by/clay-core": "0.2.24",
+    "@close-by/clay-components": "0.2.24",
+    "@close-by/clay-server": "0.2.24",
     "@tailwindcss/cli": "^4.3.3",
     "tailwindcss": "^4.3.3"
   }

package/src/index.ts

@@ -465,6 +465,10 @@ import {
   updateUrlSearch as updateUrlSearchCore,
   openExternal as openExternalCore,
   redirect as redirectCore,
+  setRoleResolver,
+  hasRole as hasRoleCore,
+  forRoles as forRolesCore,
+  type RoleResolver,
   scroll as scrollCore,
   timer as timerCore,
   storage as storageCore,
@@ -1690,6 +1694,30 @@ export function redirect(url: string): void {
   redirectCore(url);
 }
 
+/** True when the current user has at least one of `roles` (needs `ui.run({ getRoles })`). */
+export function hasRole(roles: string | readonly string[]): boolean {
+  return hasRoleCore(roles);
+}
+
+/**
+ * Build `content` only for users with one of `roles`, else `fallback`.
+ * Skipped content is never sent to the browser. Needs `ui.run({ getRoles })`.
+ *
+ * @example
+ * ```ts
+ * ui.forRoles(['admin', 'manager'], () => {
+ *   ui.button('Delete project', { onClick: remove });
+ * }, () => ui.label('Ask an admin for access'));
+ * ```
+ */
+export function forRoles(
+  roles: string | readonly string[],
+  content: () => void,
+  fallback?: () => void,
+): void {
+  forRolesCore(roles, content, fallback);
+}
+
 /** Open a URL in a new tab. Prefer over `runJavaScript('window.open…')`. */
 export function openExternal(url: string): void {
   openExternalCore(url);
@@ -1789,6 +1817,12 @@ export function page(path: string, fn: () => void, options?: PageOptions): void
  * Extends {@link ClayServerConfig} (port, auth, storage, uploads, session timeouts).
  */
 export type RunConfig = ClayServerConfig & {
+  /**
+   * Current user's role(s), read while pages build. Enables `ui.forRoles`,
+   * `element.roles([...])`, `ui.hasRole`, and default role filtering in
+   * `ui.navFromPages()` / `requireRole`. Return `null` / `[]` when signed out.
+   */
+  getRoles?: RoleResolver;
   /** Global dashboard shell; wraps every page unless `ui.page(..., { shell: false })`. */
   app?: AppProps;
   /**
@@ -1887,7 +1921,8 @@ export function run(rootOrConfig: PageFn | RunConfig = {}, config: RunConfig = {
 
   cfg = applyClayTailwind(cfg);
 
-  const { app: appProps, tailwind: _tailwind, ...serverConfig } = cfg;
+  const { app: appProps, tailwind: _tailwind, getRoles, ...serverConfig } = cfg;
+  setRoleResolver(getRoles ?? null);
   if (appProps) {
     setPageWrapper((pageFn) => app(appProps, pageFn));
   } else {
@@ -2035,6 +2070,8 @@ export const ui = {
   updateUrlSearch,
   openExternal,
   redirect,
+  forRoles,
+  hasRole,
   runJavaScript,
   scroll,
   timer,

package/src/pages.ts

@@ -1,3 +1,4 @@
+import { currentRoles, hasRoleResolver } from '@close-by/clay-core';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { join } from 'path';
 import { readFile } from 'fs/promises';
@@ -249,6 +250,10 @@ export function navFromPages(opts?: NavFromPagesOptions): AppNavItem[] {
   if (opts?.roles) {
     for (const r of opts.roles) viewer.add(r);
   }
+  // No explicit role given → use ui.run({ getRoles }) when configured.
+  if (opts?.role === undefined && opts?.roles === undefined && hasRoleResolver()) {
+    for (const r of currentRoles()) viewer.add(r);
+  }
 
   const paths = getRegisteredPaths();
   const ranked: RankedNavPage[] = paths