@jskit-ai/agent-docs 0.1.239 → 0.1.240

package/skills/jskit/references/patterns/auth/accounts-hub/PATTERN.md

@@ -0,0 +1,97 @@
+---
+id: auth/accounts-hub
+title: Accounts hub
+summary: Run one OpenID Connect sign-in for all of an owner's apps as its own JSKIT project, with production apps approved by the owner.
+keywords: auth, authentication, oidc, openid connect, issuer, single sign-on, sso, accounts hub, master login
+requires: @jskit-ai/oidc-issuer-core
+---
+
+# Accounts hub
+
+## Use when
+
+Use this pattern when one person or company owns several apps and wants one
+account to sign in to all of them. The hub is its own project, deployed on a
+domain of its own. Apps sign in through it with
+`@jskit-ai/auth-provider-oidc-core` (pattern `auth/oidc-sign-in`).
+
+## Do not use when
+
+Do not use it inside an app that has its own users only: use local accounts.
+Do not add it to an existing app as a second purpose; the hub's cookies and
+pages belong on their own origin.
+
+## Product decisions
+
+- The hub's address (`APP_PUBLIC_URL`), on a domain no app shares.
+- The owner (`OIDC_HUB_OWNER_EMAIL`): only this verified account opens Apps,
+  People and Setup.
+- The email sender (`OIDC_HUB_EMAIL_FROM` with `RESEND_API_KEY` or `SMTP_URL`).
+- Optional "Continue with Google" with the owner's own Google OAuth client
+  (`OIDC_HUB_GOOGLE_CLIENT_ID`, `OIDC_HUB_GOOGLE_CLIENT_SECRET`), redirect URI
+  `{APP_PUBLIC_URL}/hub/google/callback`.
+- Development addresses approved automatically
+  (`OIDC_HUB_DEV_ORIGIN_PATTERNS`, comma-separated `https://` globs where `*`
+  stays inside one DNS label). Loopback is always included.
+
+## Invariants
+
+- Secrets (`OIDC_HUB_SECRET`, `OIDC_HUB_REGISTRATION_TOKEN`, sender keys,
+  Google secret) live in the host's secret store, never in source.
+- Every production app address waits for one owner click in Apps. Names are
+  self-asserted; the full address is what the owner approves.
+- Apps receive the authorization code flow with PKCE only, no refresh tokens,
+  exact redirect URIs, and the same `sub` everywhere.
+- The issuer and `/hub` paths are never framed; in production no hub page is.
+  (Development lets an editor's preview pane show the hub's own pages.) The
+  hub's own sign-in is first-party: apps never see passwords.
+- Passwords use the JSKIT local-account scrypt v1 format, so local accounts
+  import unchanged.
+
+## Framework APIs
+
+Install `@jskit-ai/oidc-issuer-core` with a database driver
+(`@jskit-ai/database-runtime-mysql`). Its provider mounts on the app's Fastify
+server:
+
+- `/.well-known/openid-configuration` and `/oidc/*`: the issuer, built on
+  `oidc-provider` with a persistent Knex adapter;
+- `/oidc/reg`: protected self-registration (RFC 7591/7592) with the
+  registration token as the initial access token;
+- `/hub/interaction/:uid`, `/hub/google/*`, `/hub/api/*`: the hub's sign-in,
+  account and admin API that the app's own pages call.
+
+Add `HUB_GLOBAL_PATHS` from `@jskit-ai/oidc-issuer-core/server` to the
+server's global UI paths so a surface-filtered server still serves them.
+Pages send `x-hub-request: 1` on every state-changing call.
+
+Commands (`jskit-oidc-issuer`): `keys rotate`, `import-accounts --in <file>
+[--apply]` (dry run by default), `preview-identity`.
+
+## Example files
+
+`example/package.json` declares the hub runtime. `example/.env.example` names
+every variable without values. `example/server/hubPaths.js` shows the one
+server change.
+
+## Variation points
+
+Page design, wording and branding are the app's. Development origin patterns,
+the email sender and Google are configuration. The registration policy,
+security headers and token rules are not variation points.
+
+## Verification
+
+- Start with a missing variable and read the one-sentence error.
+- Register a loopback app: it is approved automatically and signs in.
+- Register an https app on another domain: it waits until Approve.
+- Rotate the signing key: old ID tokens verify for two hours, then fail.
+- Import exported local accounts with a dry run first; an imported account
+  signs in with its old password.
+
+## Avoid
+
+- running the hub on a domain an app shares
+- approving an app by its name without reading its address
+- copying secrets into source or into the hub's Env defaults
+- turning on development interactions or refresh tokens for apps

package/skills/jskit/references/patterns/auth/accounts-hub/example/.env.example

@@ -0,0 +1,10 @@
+APP_PUBLIC_URL=https://accounts.example.com
+OIDC_HUB_SECRET=
+OIDC_HUB_REGISTRATION_TOKEN=
+OIDC_HUB_OWNER_EMAIL=
+OIDC_HUB_DEV_ORIGIN_PATTERNS=
+OIDC_HUB_EMAIL_FROM=
+RESEND_API_KEY=
+SMTP_URL=
+OIDC_HUB_GOOGLE_CLIENT_ID=
+OIDC_HUB_GOOGLE_CLIENT_SECRET=

package/skills/jskit/references/patterns/auth/accounts-hub/example/package.json

@@ -0,0 +1,8 @@
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@jskit-ai/database-runtime-mysql": "0.1.243",
+    "@jskit-ai/oidc-issuer-core": "0.1.0"
+  }
+}

package/skills/jskit/references/patterns/auth/accounts-hub/example/server/hubPaths.js

@@ -0,0 +1,7 @@
+import { HUB_GLOBAL_PATHS } from "@jskit-ai/oidc-issuer-core/server";
+
+// Pass these to registerSurfaceRequestConstraint({ globalUiPaths }) next to
+// the runtime's own global paths, so every surface server serves the hub.
+export function hubGlobalUiPaths(runtimeGlobalUiPaths = []) {
+  return [...new Set([...runtimeGlobalUiPaths, ...HUB_GLOBAL_PATHS])];
+}

package/skills/jskit/references/patterns/auth/auth-surface/PATTERN.md

@@ -30,16 +30,33 @@ Use the views, auth guard, HTTP client integration, sign-out runtime, providers,
 and Playwright auth helper exported by `@jskit-ai/auth-web`. Use auth policies
 from `@jskit-ai/auth-core` for server authorization.
 
-For a managed preview, copy the app-owned `tools/preview-identity` executable
-and declare it under `#### Preview identity` in the project's web-presented
-Vibe64 `Outputs` target with protocol `vibe64.preview-identity.command.v1`.
-Declare `AUTH_DEV_BYPASS_ENABLED` as its Enabled environment and
-`AUTH_DEV_BYPASS_SECRET` as its Secret environment so the preview host supplies
-fresh output-run-scoped values; users do not set those values by hand. JSKIT
-owns this executable/library pattern, Vibe64 owns the `Outputs` grammar and
-runtime behavior, and Genesis only composes that consumer-owned section as
-opaque text. The executable calls the exported managed-preview identity library
-directly; it does not require a JSKIT CLI.
+Every application with accounts includes the managed-preview login. It is
+standard, not optional: adding this pattern adds it, so a managed host's
+preview can sign its browser in as an existing account without anyone asking
+for it. Copy the app-owned `tools/preview-identity` executable (keep it
+executable) and declare it under `#### Preview identity` in the project's
+web-presented Vibe64 `Outputs` target, exactly:
+
+```markdown
+#### Preview identity
+
+- Command: `tools/preview-identity`
+- Protocol: `vibe64.preview-identity.command.v1`
+- Identity types: `email` `user-id`
+- Enabled environment: `AUTH_DEV_BYPASS_ENABLED`
+- Secret environment: `AUTH_DEV_BYPASS_SECRET`
+- Runtimes: `nodejs`
+```
+
+The preview host supplies fresh output-run-scoped values for both environment
+names; users do not set them by hand, and the exchange stays disabled without
+them. The person using the host chooses which existing accounts the preview may
+sign in as; the application never creates users for it. JSKIT owns this
+executable/library pattern, Vibe64 owns the `Outputs` grammar and runtime
+behavior, and Genesis only composes that consumer-owned section as opaque text.
+The executable calls the exported managed-preview identity library directly; it
+does not require a JSKIT CLI. A project without Genesis or a managed host keeps
+the executable; it is inert unless both environment values are present.
 
 Choose local-auth storage through the installed capability provider. A
 database-backed application installs `@jskit-ai/auth-provider-local-db-core`,
@@ -52,6 +69,8 @@ a user as a side effect.
 ## Invariants
 
 - Credentials and provider secrets come from environment values.
+- An application with accounts ships the executable `tools/preview-identity`
+  and declares it under `#### Preview identity` in its web `Outputs` target.
 - Auth backend selection comes from the installed provider graph, not an
   `AUTH_LOCAL_BACKEND` environment value.
 - The selected auth backend and the storage containing the application's users
@@ -72,7 +91,8 @@ a user as a side effect.
 
 `example/` contains concrete route wrappers, editable view wrappers, and the
 client runtime helpers needed by an authentication surface. It also contains
-the optional app-owned managed-preview identity executable. Compose their
+the standard app-owned managed-preview identity executable,
+`tools/preview-identity`. Compose their
 surface and placement declarations into the application's ordinary config and
 placement files.
 
@@ -87,6 +107,8 @@ Exercise failed and successful login, sign-out, reset, protected navigation,
 keyboard interaction, warm-cache return navigation, and browser refresh.
 Open the login route with an existing authenticated session and confirm it
 returns to the requested screen; repeat signed out and confirm the form remains.
+Confirm `tools/preview-identity` is committed as executable and the web
+`Outputs` target declares the `#### Preview identity` block above.
 
 ## Avoid
 

package/skills/jskit/references/patterns/auth/oidc-sign-in/PATTERN.md

@@ -0,0 +1,87 @@
+---
+id: auth/oidc-sign-in
+title: Sign in through an OIDC issuer
+summary: Let people sign in with the accounts they already have in an accounts hub or another OpenID Connect issuer, instead of app-local passwords.
+keywords: auth, authentication, oidc, openid connect, single sign-on, sso, accounts hub, master login, issuer, back-channel logout, dynamic client registration
+requires: @jskit-ai/auth-provider-oidc-core, @jskit-ai/auth-web
+---
+
+# Sign in through an OIDC issuer
+
+## Use when
+
+Several apps should share one set of accounts: people sign in once at an
+accounts hub (see `auth/accounts-hub`) or at an organisation's OpenID Connect
+issuer, and every app signs them in from there. The app keeps its own `users`
+rows and its own session; the issuer only proves who the person is.
+
+## Do not use when
+
+The app needs its own passwords (use `auth-provider-local-core`), or the product
+has deliberately chosen Supabase (`auth/supabase-auth`). Install exactly one
+`auth.service` provider.
+
+## Product decisions
+
+- Which issuer. A hub gives each app a registration token; other issuers
+  (Google Workspace, Okta) give a fixed client id and secret instead.
+- The button label people see.
+- The production address, and who approves the app in the hub.
+- Whether existing local accounts move to the hub (one-time commands below) or
+  the app starts fresh.
+
+## Invariants
+
+- One client per app address. With a registration token the app registers
+  itself the first time it is used from a new address (or at start when
+  `APP_PUBLIC_URL` is set) and stores the client in `auth_oidc_clients`.
+- The redirect URI is auth-web's login route, `AUTH_OIDC_REDIRECT_PATH`
+  (`/auth/login`). Where to go afterwards travels in a sealed, ten-minute,
+  single-use attempt cookie, never in the redirect URI.
+- Every sign-in uses PKCE, `state`, `nonce` and the RFC 9207 `iss` check; ID
+  tokens must name this issuer and this client.
+- The app session is the app's own cookie (30 days), backed by
+  `auth_oidc_sessions`. Signing out of the app does not sign out of the issuer
+  unless the person asks for it.
+- Secrets stay in Env, never in source.
+
+## Framework APIs
+
+- `@jskit-ai/auth-provider-oidc-core` provides `auth.service`, its migration and
+  the `jskit-oidc-sign-in` command.
+- `@jskit-ai/auth-provider-oidc-core/shared` exports `AUTH_OIDC_PROVIDER_ID`,
+  `AUTH_OIDC_REDIRECT_PATH`, `AUTH_OIDC_LOGOUT_PATH` and
+  `AUTH_OIDC_BACKCHANNEL_LOGOUT_PATH`.
+- auth-web's login page shows the one button. Inside a frame (an editor
+  Preview) it opens the issuer in a pop-up window and reloads signed in.
+
+## Example files
+
+`example/package.json` declares the provider and the login surface.
+`example/.env.example` names every Env value without credentials.
+
+## Variation points
+
+- Static client (`AUTH_OIDC_CLIENT_ID`/`AUTH_OIDC_CLIENT_SECRET`) instead of
+  the registration token; never both.
+- `AUTH_OIDC_LABEL` for the button.
+- A sign-out-everywhere link: `/api/auth/oidc/logout?everywhere=1` also ends the
+  issuer session through its end-session endpoint.
+
+## Verification
+
+- Missing `AUTH_OIDC_ISSUER` shows "Sign-in is not set up yet" instead of a
+  crash.
+- Sign in unframed and inside the Preview frame; refresh stays signed in.
+- A production address the hub has not approved yet reaches the hub's waiting
+  page; a blocked one reads "Your accounts hub has blocked this app's address."
+- Disabling the account in the hub ends the app session (back-channel logout).
+- Preview identity (`tools/preview-identity`) still signs in as an existing
+  `users` row.
+
+## Avoid
+
+- keeping the local provider installed alongside this one
+- putting the return path or any secret in the redirect URI
+- sharing one registered client between addresses
+- running the account move commands without the person's explicit yes

package/skills/jskit/references/patterns/auth/oidc-sign-in/example/.env.example

@@ -0,0 +1,13 @@
+# The accounts hub (or any OpenID Connect issuer). Discovery is used.
+AUTH_OIDC_ISSUER=https://accounts.example.com/oidc
+# Preferred: the app registers itself, once per address, with this token.
+AUTH_OIDC_REGISTRATION_TOKEN=replace-me
+# Instead of the token, for issuers without self-registration:
+# AUTH_OIDC_CLIENT_ID=replace-me
+# AUTH_OIDC_CLIENT_SECRET=replace-me
+# Optional button label.
+# AUTH_OIDC_LABEL=Continue with your account
+# Required in production, at least 32 characters. Generated in development.
+# AUTH_OIDC_SESSION_SECRET=replace-me
+# The address people use. Registers at start; required behind a non-loopback proxy.
+APP_PUBLIC_URL=http://localhost:5173

package/skills/jskit/references/patterns/auth/oidc-sign-in/example/package.json

@@ -0,0 +1,8 @@
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@jskit-ai/auth-provider-oidc-core": "0.1.0",
+    "@jskit-ai/auth-web": "0.1.246"
+  }
+}

package/skills/jskit/references/patterns/auth/supabase-auth/example/package.json

@@ -2,6 +2,6 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/auth-provider-supabase-core": "0.1.241"
+    "@jskit-ai/auth-provider-supabase-core": "0.1.242"
   }
 }

package/skills/jskit/references/patterns/connectors/calendar-cli/example/package.json

@@ -7,10 +7,10 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/connectors-core": "0.1.61",
-    "@jskit-ai/connector-google-calendar": "0.1.61",
-    "@jskit-ai/database-runtime": "0.1.244",
-    "@jskit-ai/database-runtime-mysql": "0.1.242",
+    "@jskit-ai/connectors-core": "0.1.62",
+    "@jskit-ai/connector-google-calendar": "0.1.62",
+    "@jskit-ai/database-runtime": "0.1.245",
+    "@jskit-ai/database-runtime-mysql": "0.1.243",
     "knex": "^3.1.0"
   }
 }

package/skills/jskit/references/patterns/connectors/oauth-connection/PATTERN.md

@@ -181,6 +181,31 @@ comma-separated permissions. Oura handles reduced callback scopes and rotated
 refresh tokens. Some providers do not return a refresh token; expired access
 then needs consent again. Provider PKCE enforcement needs provider evidence.
 
+## Shared connection from an Env refresh token
+
+When the application's host already holds a long-lived grant for the shared
+account (the owner connected it once with the same OAuth client), skip consent
+in the app: add `refreshTokenRef` to a `shared` oauth2 integration whose
+registration uses the authorization-code flow.
+
+```json
+"authentication": {
+  "method": "oauth2",
+  "registrationRef": "google",
+  "refreshTokenRef": "env:GOOGLE_REFRESH_TOKEN"
+}
+```
+
+The Env value is a seed. On first use, and whenever the value or the OAuth
+client changes, the runtime replaces the shared connection with one built from
+that refresh token. From then on it refreshes and stores rotated tokens in the
+application's own store as usual. `status()` reports `source: "env"` (show it as
+"Connected from Env"). `beginAuthorization()` and `disconnect()` refuse with
+`connector_env_managed`: "This connection comes from an Env value; unlink or
+replace that value instead." A revoked token fails with "The refresh token in
+Env no longer works; replace that Env value." The refresh token must come from
+the same client as `registrationRef`; non-JSKIT apps read the variable directly.
+
 ## Twitch composition
 
 Use `twitchProvider` from `@jskit-ai/connectors-catalog/server/twitch` in the

package/skills/jskit/references/patterns/crud/json-api-resource-package/example/packages/books/package.json

@@ -8,8 +8,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.255",
-    "@jskit-ai/resource-crud-core": "0.1.186"
+    "@jskit-ai/crud-core": "0.1.256",
+    "@jskit-ai/resource-crud-core": "0.1.187"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/patterns/database/mysql-application/example/package.json

@@ -8,6 +8,6 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-mysql": "0.1.242"
+    "@jskit-ai/database-runtime-mysql": "0.1.243"
   }
 }

package/skills/jskit/references/patterns/database/postgres-application/example/package.json

@@ -8,6 +8,6 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-postgres": "0.1.241"
+    "@jskit-ai/database-runtime-postgres": "0.1.242"
   }
 }

package/skills/jskit/references/patterns/realtime/realtime-application/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/realtime": "0.1.242",
-    "@jskit-ai/shell-web": "0.1.249"
+    "@jskit-ai/realtime": "0.1.243",
+    "@jskit-ai/shell-web": "0.1.250"
   }
 }

package/skills/jskit/references/patterns/server/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.244",
+    "@jskit-ai/kernel": "0.1.245",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/skills/jskit/references/patterns/shell/application-shell/PATTERN.md

@@ -38,6 +38,15 @@ placement registry, topology, and adaptive smoke helper exported by
 - Cached route/resource state hydrates writable UI state synchronously or with
   immediate watchers.
 - Loading uses stable skeletons, not spinners or shifting status banners.
+- `ShellErrorHost` stays directly inside `v-app`. Its banners float below a top
+  app bar; on a surface without one (such as sign-in) they join the page flow
+  above the content so they never cover it. A full-viewport fixed screen on
+  such a surface starts at `var(--shell-error-banners-inline-height, 0px)`, as
+  `@jskit-ai/auth-web`'s login and reset views do.
+- Restyle shell chrome through its `--shell-chrome-*`, `--shell-app-bar-*`,
+  `--shell-navigation-*` and `--shell-bottom-navigation-*` custom properties,
+  not by overriding Vuetify internals; a Material 3 restyle removes the dividers
+  and separates surfaces tonally.
 - The adaptive browser check closes navigation through its public close control.
 
 ## Example files

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/package.json

@@ -9,8 +9,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.255",
-    "@jskit-ai/resource-crud-core": "0.1.186"
+    "@jskit-ai/crud-core": "0.1.256",
+    "@jskit-ai/resource-crud-core": "0.1.187"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/package.json

@@ -9,9 +9,9 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.255",
-    "@jskit-ai/resource-crud-core": "0.1.186",
-    "@jskit-ai/workspaces-core": "0.1.222"
+    "@jskit-ai/crud-core": "0.1.256",
+    "@jskit-ai/resource-crud-core": "0.1.187",
+    "@jskit-ai/workspaces-core": "0.1.223"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/ui-operations.md

@@ -50,6 +50,17 @@ shared-screen controls; avoid duplicates, drawer-only access, or adding a page
 heading just to house it. Keep its meaning and accessible name clear at every
 supported width.
 
+### Scroll position
+
+`createShellRouter()` from `@jskit-ai/kernel/client` installs
+`shellScrollBehavior` by default: a new screen opens at the top (or at its
+hash target), Back/Forward restore the saved position, and query, hash, tab or
+sub-view changes within the same page keep the current position. A tab or
+sub-view counts as the same page when both locations share a parent page record
+below the surface root. Pass `scrollBehavior` to `createShellRouter()` to
+replace it with your own Vue Router function, or `scrollBehavior: false` to
+disable it. Do not wrap the router or reset scroll in page components.
+
 ## Application-owned files
 
 Pattern source is ordinary customizable application source. When replacing a
@@ -88,6 +99,19 @@ icon/label and label/end gaps. The normal 80px rail centres 48px targets;
 `railWidth` and `drawerWidth` are public density/width controls. Do not override
 the shell's private implementation CSS.
 
+The app bar, drawer/rail and compact bottom navigation follow the Vuetify theme
+and expose restyling tokens instead of hard-coded chrome: `--shell-chrome-border-width`
+and `--shell-chrome-border-color` for the shared dividers,
+`--shell-app-bar-border-width`, `--shell-navigation-border-width` and
+`--shell-bottom-navigation-border-width` per edge, and
+`--shell-app-bar-background`, `--shell-navigation-background` and
+`--shell-bottom-navigation-background` for the surfaces. The defaults keep one
+thin divider on each separating edge, because Vuetify's default themes define
+no Material 3 surface-container roles to separate surfaces tonally. A Material 3
+restyle sets the border widths to `0` and gives navigation a tonal surface, for
+example `--shell-navigation-background: rgb(var(--v-theme-surface-container-low))`
+when the theme defines that role.
+
 ## Browser verification
 
 Exercise user-facing changes with Playwright at compact, medium, and expanded