@close-by/clay 0.2.21 → 0.2.22

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 |
+| `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
 
@@ -118,7 +119,7 @@ ui.establishAuthSession(userId, { path: '/account' });
 ui.clearAuthSession({ path: '/login' });
 ```
 
-Password hashing, login rate limits, and `requireAuth` / `requireRole` live in optional `@close-by/clay-auth`. See `/examples/auth`.
+Password hashing, login rate limits, OIDC single sign-on (`createOidcLogin`), and `requireAuth` / `requireRole` live in optional `@close-by/clay-auth`. See `/examples/auth` and [Production — single sign-on](./production.md#single-sign-on-oidc).
 
 Returns `ClayServer` with `.start()` / `.stop()` / `.port` (`.start()` is already called by `ui.run`).
 
@@ -1815,6 +1816,7 @@ 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.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 |
 | `ui.theme.palette(name)` | `void` | Switch colour palette for this client (`kiln`, `cobalt`, `ocean`, `forest`, `orchid`, `citrus`, `graphite`, `neon`, `sky`, `navy`, `indigo`, `denim`, `midnight`, or a custom one); remembered across reloads |

package/docs/production.md

@@ -65,6 +65,48 @@ ui.page('/admin', () => {
 
 Nav filtering is not authorization. Always guard pages that must not leak data.
 
+## 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.
+
+```ts
+import { createOidcLogin } from '@close-by/clay-auth';
+
+const sso = createOidcLogin({
+  issuer: process.env.OIDC_ISSUER!, // discovery: ${issuer}/.well-known/openid-configuration
+  clientId: process.env.OIDC_CLIENT_ID!,
+  clientSecret: process.env.OIDC_CLIENT_SECRET, // only for confidential clients
+  redirectUri: 'https://hub.example.com/auth/callback',
+  async onSignIn(claims) {
+    // Upsert your user; return the Clay user id, or null to refuse.
+    await users.upsert(claims.sub, { email: claims.email });
+    return claims.sub;
+  },
+});
+
+ui.run({
+  authSecret: process.env.CLAY_AUTH_SECRET!,
+  routes: sso.routes({ afterLogin: '/', afterLogout: '/login', errorPath: '/login' }),
+});
+
+// Sign-in button (full page load — the route redirects to the provider):
+ui.button('Sign in', { onClick: () => ui.redirect('/auth/login?returnTo=/reports') });
+// Sign-out (clears the cookie, then signs out at the provider):
+ui.button('Sign out', { onClick: () => ui.redirect('/auth/logout') });
+```
+
+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`.
+
+**Provider setup:** register an app/client that allows the authorization code flow with scopes `openid email profile`, callback URL `https://<host>/auth/callback`, and sign-out return URL `https://<host><afterLogout>`. Map roles from whatever claim your provider puts groups in, inside `onSignIn`.
+
+**Sign-out:** uses the discovery `end_session_endpoint` when the provider has one. Otherwise pass `logoutUrl: (returnTo) => '…'` with the provider's sign-out URL; without either, sign-out only clears Clay's cookie.
+
+**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).
+
 ## Rate limits & abuse
 
 Clay does not ship a global rate limiter. For handlers that trigger expensive work (ClickHouse queries, re-dispatch, file export):

package/docs/protocol.md

@@ -180,6 +180,14 @@ Client sets `location.hash` via `history.replaceState` (`hash` has no leading `#
 
 Client sets `location.search` via `history.replaceState` or `pushState` (`mode`, default `replace`). `search` has no leading `?`; empty string clears. Pathname and hash are preserved. Hydrated the other way on `hello.search` and re-synced in place on `urlchange`. Prefer `ui.setUrlSearch` / `ui.updateUrlSearch` / `ui.getUrlSearch`. See [URL search](./url-search.md).
 
+### `redirect`
+
+```json
+{ "op": "redirect", "url": "/auth/login?returnTo=/reports" }
+```
+
+Client runs `window.location.assign(url)` — a full page load that leaves the SPA. Prefer `ui.redirect`.
+
 ### `openExternal`
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "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.21",
-    "@close-by/clay-core": "0.2.21",
-    "@close-by/clay-components": "0.2.21",
-    "@close-by/clay-server": "0.2.21",
+    "@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",
     "@tailwindcss/cli": "^4.3.3",
     "tailwindcss": "^4.3.3"
   }

package/src/index.ts

@@ -464,6 +464,7 @@ import {
   setUrlSearch as setUrlSearchCore,
   updateUrlSearch as updateUrlSearchCore,
   openExternal as openExternalCore,
+  redirect as redirectCore,
   scroll as scrollCore,
   timer as timerCore,
   storage as storageCore,
@@ -1681,6 +1682,14 @@ export function updateUrlSearch(
   updateUrlSearchCore(patch, opts);
 }
 
+/**
+ * Full-page navigation in the current tab — for external sign-in pages or
+ * server routes (`/auth/login`). Use `ui.navigate` for app pages.
+ */
+export function redirect(url: string): void {
+  redirectCore(url);
+}
+
 /** Open a URL in a new tab. Prefer over `runJavaScript('window.open…')`. */
 export function openExternal(url: string): void {
   openExternalCore(url);
@@ -2025,6 +2034,7 @@ export const ui = {
   setUrlSearch,
   updateUrlSearch,
   openExternal,
+  redirect,
   runJavaScript,
   scroll,
   timer,