@quazardous/qdadm 2.22.1 → 2.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.22.1",
+  "version": "2.24.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/auth/index.ts

@@ -15,6 +15,9 @@ export {
 } from './SessionAuthAdapter'
 
 export {
+  OAuthCodeAdapter,
+  createOAuthCodeAdapter,
+  type OAuthCodeAdapterOptions,
   GoogleOAuthAdapter,
   createGoogleOAuthAdapter,
   createPkceChallenge,

package/src/auth/oauth/GoogleOAuthAdapter.ts

@@ -1,23 +1,10 @@
 /**
  * Google sign-in for qdadm, authorization-code + PKCE (#1775).
  *
- * ## The one rule this class exists to enforce
- *
- * qdadm **never** validates a Google credential in the browser. Decoding a JWT
- * client-side proves nothing: anyone can mint one. The authorization code is
- * therefore useless to the front — it is posted to *your* backend, which
- * exchanges it with Google using the client secret, verifies the identity, and
- * issues **its own** session. That session token is the only thing this adapter
- * ever stores.
- *
- * There is deliberately no code path that turns a Google response into a
- * session without your backend. That is a structural constraint, not advice.
- *
- * ## The backend contract is open
- *
- * `exchangeUrl` receives a POST and returns `{ token, user }`. Nothing about it
- * is JavaScript: implement it in Python, Go, PHP, anything. Because the
- * contract is open, configuration is enough for the common case —
+ * `OAuthCodeAdapter` with Google's defaults: its authorization endpoint, a
+ * `/auth/google/callback` redirect, and `offlineAccess` for a refresh token.
+ * The rule and the backend contract are the generic adapter's: the browser
+ * never validates a Google credential, your backend redeems the code.
  *
  * ```ts
  * new GoogleOAuthAdapter({
@@ -26,205 +13,47 @@
  * })
  * ```
  *
- * — and an app with a Python backend writes no adapter code at all. Override
- * `exchange()` only when your endpoint cannot match the documented shape.
- *
  * See docs/auth-google.md for the wire contract and a reference backend.
  *
  * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
  */
 
-import { LocalStorageSessionAuthAdapter, type AuthUser, type SessionData } from '../SessionAuthAdapter'
-import { createPkceChallenge, storeAttempt, takeAttempt, type StoredAttempt } from './pkce'
-
-/** What the front sends your backend. */
-export interface OAuthExchangePayload {
-  /** The authorization code the provider handed back. */
-  code: string
-  /** The PKCE verifier that proves this code belongs to this browser. */
-  codeVerifier: string
-  /** Echoed so the backend can pin the exchange to the same redirect. */
-  redirectUri: string
-}
+import type { AuthUser } from '../SessionAuthAdapter'
+import { OAuthCodeAdapter, type OAuthCodeAdapterOptions } from './OAuthCodeAdapter'
 
-export interface GoogleOAuthAdapterOptions {
-  /** OAuth client id. Not a secret — the client SECRET stays on your backend. */
-  clientId: string
-  /**
-   * Your endpoint that trades the code for a session. POSTed
-   * `OAuthExchangePayload`, expected to answer `{ token, user }`.
-   */
-  exchangeUrl?: string
-  /**
-   * Where the provider redirects back. Must match a URI registered in the
-   * provider console **exactly** — that is the single most common setup
-   * failure. Defaults to `/auth/google/callback` on the current origin.
-   */
-  redirectUri?: string
-  /** Scopes requested. Defaults to identity only. */
-  scopes?: string[]
+export interface GoogleOAuthAdapterOptions extends Omit<OAuthCodeAdapterOptions, 'authorizeEndpoint'> {
   /**
    * Ask for a refresh token. Requires `prompt: 'consent'` on Google to be
    * issued reliably, and the token stays with your backend — the front never
    * sees it.
    */
   offlineAccess?: boolean
-  /** localStorage key for the session (see ADR 0008 on shared origins). */
-  storageKey?: string
-  /** Authorization endpoint. Overridable for tests and for other providers. */
+  /** Authorization endpoint. Defaults to Google's; overridable for tests. */
   authorizeEndpoint?: string
 }
 
 const GOOGLE_AUTHORIZE = 'https://accounts.google.com/o/oauth2/v2/auth'
 
 export class GoogleOAuthAdapter<TUser extends AuthUser = AuthUser>
-  extends LocalStorageSessionAuthAdapter<TUser> {
-  protected _clientId: string
-  protected _exchangeUrl: string | null
-  protected _redirectUri: string
-  protected _scopes: string[]
+  extends OAuthCodeAdapter<TUser> {
+  static override readonly label: string = 'GoogleOAuthAdapter'
+  static override readonly defaultRedirectPath: string = '/auth/google/callback'
+
   protected _offlineAccess: boolean
-  protected _authorizeEndpoint: string
 
   constructor(options: GoogleOAuthAdapterOptions) {
-    super({ storageKey: options.storageKey ?? 'qdadm_auth' })
-
-    if (!options?.clientId) {
-      throw new Error('[GoogleOAuthAdapter] clientId is required')
-    }
-
-    this._clientId = options.clientId
-    this._exchangeUrl = options.exchangeUrl ?? null
-    this._redirectUri =
-      options.redirectUri ??
-      (typeof window !== 'undefined'
-        ? `${window.location.origin}/auth/google/callback`
-        : '/auth/google/callback')
-    this._scopes = options.scopes ?? ['openid', 'email', 'profile']
+    super({ ...options, authorizeEndpoint: options?.authorizeEndpoint ?? GOOGLE_AUTHORIZE })
     this._offlineAccess = options.offlineAccess ?? false
-    this._authorizeEndpoint = options.authorizeEndpoint ?? GOOGLE_AUTHORIZE
   }
 
-  /** The redirect URI this adapter will use — handy for error messages. */
-  get redirectUri(): string {
-    return this._redirectUri
-  }
-
-  /**
-   * Build the authorization URL for a fresh attempt.
-   *
-   * Stashes the PKCE verifier, the CSRF state and where the user was heading,
-   * so the callback can finish what this started.
-   */
-  async buildAuthorizeUrl(redirectTo = '/'): Promise<string> {
-    const { verifier, challenge, state } = await createPkceChallenge()
-    storeAttempt({ verifier, state, redirectTo })
-
-    const url = new URL(this._authorizeEndpoint)
-    url.searchParams.set('client_id', this._clientId)
-    url.searchParams.set('redirect_uri', this._redirectUri)
-    url.searchParams.set('response_type', 'code')
-    url.searchParams.set('scope', this._scopes.join(' '))
-    url.searchParams.set('state', state)
-    url.searchParams.set('code_challenge', challenge)
-    url.searchParams.set('code_challenge_method', 'S256')
+  protected override extraAuthorizeParams(): Record<string, string> {
+    const params = super.extraAuthorizeParams()
     if (this._offlineAccess) {
-      url.searchParams.set('access_type', 'offline')
+      params.access_type = 'offline'
       // Google only re-issues a refresh token when consent is asked again.
-      url.searchParams.set('prompt', 'consent')
-    }
-
-    return url.toString()
-  }
-
-  /** Send the browser to the provider. */
-  async beginLogin(redirectTo = '/'): Promise<void> {
-    window.location.assign(await this.buildAuthorizeUrl(redirectTo))
-  }
-
-  /**
-   * Trade the code for a session **on your backend**.
-   *
-   * Override this when your endpoint's shape differs. Whatever you do, the
-   * exchange must happen server-side: the browser has no client secret and
-   * cannot verify anything Google says.
-   */
-  async exchange(payload: OAuthExchangePayload): Promise<SessionData<TUser>> {
-    if (!this._exchangeUrl) {
-      throw new Error(
-        '[GoogleOAuthAdapter] no exchangeUrl configured, and exchange() was not overridden. ' +
-          'The authorization code must be redeemed by your backend — the browser cannot do it.'
-      )
-    }
-
-    const response = await fetch(this._exchangeUrl, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      credentials: 'same-origin',
-      body: JSON.stringify(payload),
-    })
-
-    if (!response.ok) {
-      const detail = await response.text().catch(() => '')
-      throw new Error(
-        `[GoogleOAuthAdapter] exchange failed (${response.status})${detail ? `: ${detail.slice(0, 200)}` : ''}`
-      )
-    }
-
-    const data = (await response.json()) as SessionData<TUser>
-    if (!data?.token || !data?.user) {
-      throw new Error(
-        '[GoogleOAuthAdapter] exchange endpoint must return { token, user } — see docs/auth-google.md'
-      )
-    }
-    return data
-  }
-
-  /**
-   * Finish the login from the callback route's query string.
-   *
-   * @returns the session plus where to send the user next.
-   * @throws when the provider reported an error, when no attempt is pending,
-   *   or when `state` does not match — each of which is a reason to refuse.
-   */
-  async completeLogin(
-    query: URLSearchParams | Record<string, string | undefined>
-  ): Promise<SessionData<TUser> & { redirectTo: string }> {
-    const read = (key: string): string | undefined =>
-      query instanceof URLSearchParams ? (query.get(key) ?? undefined) : query[key]
-
-    const providerError = read('error')
-    if (providerError) {
-      throw new Error(`[GoogleOAuthAdapter] provider refused the login: ${providerError}`)
-    }
-
-    const attempt: StoredAttempt | null = takeAttempt()
-    if (!attempt) {
-      // No pending attempt: a replayed or bookmarked callback URL. Refusing is
-      // the point — the attempt is consumed on read.
-      throw new Error('[GoogleOAuthAdapter] no login attempt pending for this callback')
-    }
-
-    const state = read('state')
-    if (!state || state !== attempt.state) {
-      throw new Error('[GoogleOAuthAdapter] state mismatch — refusing the callback')
-    }
-
-    const code = read('code')
-    if (!code) {
-      throw new Error('[GoogleOAuthAdapter] callback carried no authorization code')
+      params.prompt = 'consent'
     }
-
-    const session = await this.exchange({
-      code,
-      codeVerifier: attempt.verifier,
-      redirectUri: this._redirectUri,
-    })
-
-    this.setSession(session.token, session.user)
-    this.persist()
-
-    return { ...session, redirectTo: attempt.redirectTo || '/' }
+    return params
   }
 }
 

package/src/auth/oauth/OAuthCodeAdapter.ts

@@ -0,0 +1,268 @@
+/**
+ * Sign-in with any OAuth 2 / OIDC provider, authorization-code + PKCE (#2264).
+ *
+ * ## The one rule this class exists to enforce
+ *
+ * qdadm **never** validates a provider credential in the browser. Decoding a
+ * JWT client-side proves nothing: anyone can mint one. The authorization code
+ * is therefore useless to the front — it is posted to *your* backend, which
+ * exchanges it with the provider using the client secret, verifies the
+ * identity, and issues **its own** session. That session token is the only
+ * thing this adapter ever stores.
+ *
+ * There is deliberately no code path that turns a provider response into a
+ * session without your backend. That is a structural constraint, not advice.
+ *
+ * ## The backend contract is open
+ *
+ * `exchangeUrl` receives a POST and returns `{ token, user }`. Nothing about it
+ * is JavaScript: implement it in Python, Go, PHP, anything. Keycloak, Auth0,
+ * Okta or Entra ID only change the authorization endpoint the browser goes to:
+ *
+ * ```ts
+ * new OAuthCodeAdapter({
+ *   clientId: 'my-admin',
+ *   authorizeEndpoint: 'https://sso.example.com/realms/acme/protocol/openid-connect/auth',
+ *   exchangeUrl: '/auth/oidc/exchange',
+ * })
+ * ```
+ *
+ * Override `exchange()` only when your endpoint cannot match the documented
+ * shape. See docs/auth-oidc.md for the wire contract and provider examples.
+ *
+ * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
+ */
+
+import { LocalStorageSessionAuthAdapter, type AuthUser, type SessionData } from '../SessionAuthAdapter'
+import { createPkceChallenge, storeAttempt, takeAttempt, type StoredAttempt } from './pkce'
+
+/** What the front sends your backend. */
+export interface OAuthExchangePayload {
+  /** The authorization code the provider handed back. */
+  code: string
+  /** The PKCE verifier that proves this code belongs to this browser. */
+  codeVerifier: string
+  /** Echoed so the backend can pin the exchange to the same redirect. */
+  redirectUri: string
+}
+
+export interface OAuthCodeAdapterOptions {
+  /** OAuth client id. Not a secret — the client SECRET stays on your backend. */
+  clientId: string
+  /** The provider's authorization endpoint, where the browser is sent to sign in. */
+  authorizeEndpoint: string
+  /**
+   * Your endpoint that trades the code for a session. POSTed
+   * `OAuthExchangePayload`, expected to answer `{ token, user }`.
+   */
+  exchangeUrl?: string
+  /**
+   * Where the provider redirects back. Must match a URI registered with the
+   * provider **exactly** — that is the single most common setup failure.
+   * Defaults to `/auth/callback` on the current origin.
+   */
+  redirectUri?: string
+  /** Scopes requested. Defaults to identity only. */
+  scopes?: string[]
+  /**
+   * Extra query parameters for the authorization URL: `audience` (Auth0),
+   * `kc_idp_hint` (Keycloak), `prompt`, `login_hint`… The parameters the flow
+   * itself sets (client id, redirect, scope, state, PKCE) cannot be overridden.
+   */
+  authorizeParams?: Record<string, string>
+  /** localStorage key for the session (see ADR 0008 on shared origins). */
+  storageKey?: string
+}
+
+/** Parameters the flow owns: letting a caller set them would break PKCE or CSRF protection. */
+const FLOW_PARAMS = [
+  'client_id',
+  'redirect_uri',
+  'response_type',
+  'scope',
+  'state',
+  'code_challenge',
+  'code_challenge_method',
+]
+
+export class OAuthCodeAdapter<TUser extends AuthUser = AuthUser>
+  extends LocalStorageSessionAuthAdapter<TUser> {
+  /** Prefix of this adapter's error messages. Subclasses name themselves. */
+  static readonly label: string = 'OAuthCodeAdapter'
+  /** Redirect path on the current origin when `redirectUri` is not given. */
+  static readonly defaultRedirectPath: string = '/auth/callback'
+
+  protected _clientId: string
+  protected _authorizeEndpoint: string
+  protected _exchangeUrl: string | null
+  protected _redirectUri: string
+  protected _scopes: string[]
+  protected _authorizeParams: Record<string, string>
+
+  constructor(options: OAuthCodeAdapterOptions) {
+    super({ storageKey: options?.storageKey ?? 'qdadm_auth' })
+
+    if (!options?.clientId) {
+      throw new Error(`${this.errorPrefix} clientId is required`)
+    }
+    if (!options.authorizeEndpoint) {
+      throw new Error(`${this.errorPrefix} authorizeEndpoint is required: the provider's authorization URL`)
+    }
+
+    this._clientId = options.clientId
+    this._authorizeEndpoint = options.authorizeEndpoint
+    this._exchangeUrl = options.exchangeUrl ?? null
+    const redirectPath = (this.constructor as typeof OAuthCodeAdapter).defaultRedirectPath
+    this._redirectUri =
+      options.redirectUri ??
+      (typeof window !== 'undefined' ? `${window.location.origin}${redirectPath}` : redirectPath)
+    this._scopes = options.scopes ?? ['openid', 'email', 'profile']
+    this._authorizeParams = { ...(options.authorizeParams ?? {}) }
+  }
+
+  /** The redirect URI this adapter will use — handy for error messages. */
+  get redirectUri(): string {
+    return this._redirectUri
+  }
+
+  protected get errorPrefix(): string {
+    return `[${(this.constructor as typeof OAuthCodeAdapter).label}]`
+  }
+
+  /**
+   * Provider-specific query parameters for the authorization URL. Subclasses
+   * add their own here (Google's `access_type`, for instance).
+   */
+  protected extraAuthorizeParams(): Record<string, string> {
+    return { ...this._authorizeParams }
+  }
+
+  /**
+   * Build the authorization URL for a fresh attempt.
+   *
+   * Stashes the PKCE verifier, the CSRF state and where the user was heading,
+   * so the callback can finish what this started.
+   */
+  async buildAuthorizeUrl(redirectTo = '/'): Promise<string> {
+    const extra = this.extraAuthorizeParams()
+    const overridden = Object.keys(extra).filter((key) => FLOW_PARAMS.includes(key))
+    if (overridden.length > 0) {
+      throw new Error(
+        `${this.errorPrefix} authorizeParams cannot set ${overridden.join(', ')}: the flow sets them itself`
+      )
+    }
+
+    const { verifier, challenge, state } = await createPkceChallenge()
+    storeAttempt({ verifier, state, redirectTo })
+
+    const url = new URL(this._authorizeEndpoint)
+    url.searchParams.set('client_id', this._clientId)
+    url.searchParams.set('redirect_uri', this._redirectUri)
+    url.searchParams.set('response_type', 'code')
+    url.searchParams.set('scope', this._scopes.join(' '))
+    url.searchParams.set('state', state)
+    url.searchParams.set('code_challenge', challenge)
+    url.searchParams.set('code_challenge_method', 'S256')
+    for (const [key, value] of Object.entries(extra)) {
+      url.searchParams.set(key, value)
+    }
+
+    return url.toString()
+  }
+
+  /** Send the browser to the provider. */
+  async beginLogin(redirectTo = '/'): Promise<void> {
+    window.location.assign(await this.buildAuthorizeUrl(redirectTo))
+  }
+
+  /**
+   * Trade the code for a session **on your backend**.
+   *
+   * Override this when your endpoint's shape differs. Whatever you do, the
+   * exchange must happen server-side: the browser has no client secret and
+   * cannot verify anything the provider says.
+   */
+  async exchange(payload: OAuthExchangePayload): Promise<SessionData<TUser>> {
+    if (!this._exchangeUrl) {
+      throw new Error(
+        `${this.errorPrefix} no exchangeUrl configured, and exchange() was not overridden. ` +
+          'The authorization code must be redeemed by your backend — the browser cannot do it.'
+      )
+    }
+
+    const response = await fetch(this._exchangeUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      credentials: 'same-origin',
+      body: JSON.stringify(payload),
+    })
+
+    if (!response.ok) {
+      const detail = await response.text().catch(() => '')
+      throw new Error(
+        `${this.errorPrefix} exchange failed (${response.status})${detail ? `: ${detail.slice(0, 200)}` : ''}`
+      )
+    }
+
+    const data = (await response.json()) as SessionData<TUser>
+    if (!data?.token || !data?.user) {
+      throw new Error(
+        `${this.errorPrefix} exchange endpoint must return { token, user } — see docs/auth-oidc.md`
+      )
+    }
+    return data
+  }
+
+  /**
+   * Finish the login from the callback route's query string.
+   *
+   * @returns the session plus where to send the user next.
+   * @throws when the provider reported an error, when no attempt is pending,
+   *   or when `state` does not match — each of which is a reason to refuse.
+   */
+  async completeLogin(
+    query: URLSearchParams | Record<string, string | undefined>
+  ): Promise<SessionData<TUser> & { redirectTo: string }> {
+    const read = (key: string): string | undefined =>
+      query instanceof URLSearchParams ? (query.get(key) ?? undefined) : query[key]
+
+    const providerError = read('error')
+    if (providerError) {
+      throw new Error(`${this.errorPrefix} provider refused the login: ${providerError}`)
+    }
+
+    const attempt: StoredAttempt | null = takeAttempt()
+    if (!attempt) {
+      // No pending attempt: a replayed or bookmarked callback URL. Refusing is
+      // the point — the attempt is consumed on read.
+      throw new Error(`${this.errorPrefix} no login attempt pending for this callback`)
+    }
+
+    const state = read('state')
+    if (!state || state !== attempt.state) {
+      throw new Error(`${this.errorPrefix} state mismatch — refusing the callback`)
+    }
+
+    const code = read('code')
+    if (!code) {
+      throw new Error(`${this.errorPrefix} callback carried no authorization code`)
+    }
+
+    const session = await this.exchange({
+      code,
+      codeVerifier: attempt.verifier,
+      redirectUri: this._redirectUri,
+    })
+
+    this.setSession(session.token, session.user)
+    this.persist()
+
+    return { ...session, redirectTo: attempt.redirectTo || '/' }
+  }
+}
+
+export function createOAuthCodeAdapter<TUser extends AuthUser = AuthUser>(
+  options: OAuthCodeAdapterOptions
+): OAuthCodeAdapter<TUser> {
+  return new OAuthCodeAdapter<TUser>(options)
+}

package/src/auth/oauth/index.ts

@@ -6,11 +6,17 @@
  * @module auth/oauth
  */
 
+export {
+  OAuthCodeAdapter,
+  createOAuthCodeAdapter,
+  type OAuthCodeAdapterOptions,
+  type OAuthExchangePayload,
+} from './OAuthCodeAdapter'
+
 export {
   GoogleOAuthAdapter,
   createGoogleOAuthAdapter,
   type GoogleOAuthAdapterOptions,
-  type OAuthExchangePayload,
 } from './GoogleOAuthAdapter'
 
 export {

package/src/components/layout/Zone.vue

@@ -155,19 +155,23 @@ function getWrappedComponent(block: BlockConfig): Component | undefined {
   <div :data-zone="name" class="qdadm-zone">
     <template v-if="hasBlocks">
       <template v-for="block in blocks" :key="block.id || block.weight">
-        <!-- Render wrapped blocks using memoized component -->
-        <component
-          v-if="block.wrappers"
-          :is="getWrappedComponent(block)"
-        />
-        <!-- Render simple blocks directly, passing Zone's slot content -->
-        <component
-          v-else
-          :is="block.component"
-          v-bind="{ ...blockProps, ...block.props }"
-        >
-          <slot />
-        </component>
+        <!-- Each block in its own marker (#2363): no box (display: contents), so the layout is unchanged, and the
+             page tools can tell which block rendered what — blocks with several root elements included. -->
+        <div :data-zone-block="block.id ?? ''" style="display: contents">
+          <!-- Render wrapped blocks using memoized component -->
+          <component
+            v-if="block.wrappers"
+            :is="getWrappedComponent(block)"
+          />
+          <!-- Render simple blocks directly, passing Zone's slot content -->
+          <component
+            v-else
+            :is="block.component"
+            v-bind="{ ...blockProps, ...block.props }"
+          >
+            <slot />
+          </component>
+        </div>
       </template>
     </template>
     <component

package/src/composables/useEntityItemFormPage.ts

@@ -36,6 +36,7 @@ import {
   type CreateContext,
 } from './useEntityItemPage'
 import { registerGuardDialog, unregisterGuardDialog } from './useGuardStore'
+import { registerPageState } from './usePageState'
 import { deepClone } from '../utils/transformers'
 import { getSiblingRoutes } from '../module/moduleRegistry'
 import {
@@ -227,6 +228,19 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
     onUnmounted(() => unregisterGuardDialog(guardDialog!))
   }
 
+  // What this form is doing, for the debug tools and the MCP (#2363)
+  onUnmounted(
+    registerPageState(() => ({
+      kind: 'form',
+      entity: String((manager as { name?: unknown }).name ?? ''),
+      mode: mode.value,
+      dirtyFields: [...dirtyFields.value],
+      errors: { ...errors.value },
+      saving: saving.value,
+      loading: loading.value,
+    }))
+  )
+
   // ============ BREADCRUMB ============
 
   const { breadcrumbItems } = useBreadcrumb({ entity: data })

package/src/composables/useEntityItemShowPage.ts

@@ -33,7 +33,8 @@
  * <ShowPage v-bind="show.props.value" v-on="show.events" />
  * ```
  */
-import { ref, computed, type Ref, type ComputedRef } from 'vue'
+import { ref, computed, onUnmounted, type Ref, type ComputedRef } from 'vue'
+import { registerPageState } from './usePageState'
 import { useRouter, type Router } from 'vue-router'
 import { useConfirm } from 'primevue/useconfirm'
 import { requireDeleteConfirmation } from './confirmDelete'
@@ -310,6 +311,17 @@ export function useEntityItemShowPage<T = Record<string, unknown>>(
 
   const { manager, orchestrator: baseOrchestrator, data, loading, error, entityId, entityLabel, isLoaded, hydrator } = base
 
+  // What this show page is doing, for the debug tools and the MCP (#2363)
+  onUnmounted(
+    registerPageState(() => ({
+      kind: 'show',
+      entity: String((manager as { name?: unknown }).name ?? ''),
+      loaded: isLoaded.value,
+      loading: loading.value,
+      error: error.value,
+    }))
+  )
+
   // Reload when THIS record changed outside the session (#1888 lot D).
   // Scoped by id: an event about another record must not reload every open
   // detail page. An event carrying no id concerns the whole entity and applies.

package/src/composables/useListPage.ts

@@ -37,6 +37,7 @@ import {
 } from '../routeState'
 import { useConfirm } from 'primevue/useconfirm'
 import { requireDeleteConfirmation } from './confirmDelete'
+import { registerPageState, activeFilters } from './usePageState'
 import { useHooks } from './useHooks.js'
 import { useEntityItemPage, type ParentConfig, type UseEntityItemPageReturn } from './useEntityItemPage.js'
 import { useActiveStack } from '../chain/useActiveStack.js'
@@ -1184,6 +1185,23 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     window.removeEventListener('resize', handleResize)
   })
 
+  // What this list is doing, for the debug tools and the MCP (#2363): counts and names, never row contents
+  onUnmounted(
+    registerPageState(() => ({
+      kind: 'list',
+      entity: String(entity),
+      rows: displayItems.value.length,
+      total: totalRecords.value,
+      page: page.value,
+      pageSize: pageSize.value,
+      sort: sortField.value ? { field: sortField.value, order: sortOrder.value < 0 ? 'desc' : 'asc' } : null,
+      search: searchQuery.value,
+      filters: activeFilters(filterValues.value as Record<string, unknown>),
+      selected: selected.value.length,
+      loading: loading.value,
+    }))
+  )
+
   // Reload when this entity changed outside the session (#1888 lot D).
   //
   // Only fires for entities the app declared in sse.entities, so an app with

package/src/composables/usePageState.ts

@@ -0,0 +1,76 @@
+/**
+ * What the page on screen is doing (#2363), for the debug tools and the MCP's `page_snapshot`.
+ *
+ * The list, form and show composables register a getter while their page lives. Pages can nest (a list of loans
+ * inside a book's show page), so the store is a stack: the innermost page answers, and the outer one answers again
+ * once the inner one is gone. Counts and names only — never row contents.
+ */
+
+export interface ListPageState {
+  kind: 'list'
+  entity: string
+  rows: number
+  total: number
+  page: number
+  pageSize: number
+  sort: { field: string; order: 'asc' | 'desc' } | null
+  search: string
+  /** Active filters only: empty values are left out. */
+  filters: Record<string, unknown>
+  selected: number
+  loading: boolean
+}
+
+export interface FormPageState {
+  kind: 'form'
+  entity: string
+  mode: 'create' | 'edit'
+  dirtyFields: string[]
+  errors: Record<string, string>
+  saving: boolean
+  loading: boolean
+}
+
+export interface ShowPageState {
+  kind: 'show'
+  entity: string
+  loaded: boolean
+  loading: boolean
+  error: string | null
+}
+
+export type PageState = ListPageState | FormPageState | ShowPageState
+export type PageStateGetter = () => PageState
+
+const stack: PageStateGetter[] = []
+
+/** Register the page's state; call the returned function when the page goes away. */
+export function registerPageState(getter: PageStateGetter): () => void {
+  stack.push(getter)
+  return () => {
+    const at = stack.lastIndexOf(getter)
+    if (at >= 0) stack.splice(at, 1)
+  }
+}
+
+/** The innermost page's state, or null when no qdadm page is on screen. */
+export function currentPageState(): PageState | null {
+  const getter = stack[stack.length - 1]
+  if (!getter) return null
+  try {
+    return getter()
+  } catch {
+    return null
+  }
+}
+
+/** Active filter values: what a user set, not the empty defaults. */
+export function activeFilters(values: Record<string, unknown> | null | undefined): Record<string, unknown> {
+  const active: Record<string, unknown> = {}
+  for (const [name, value] of Object.entries(values ?? {})) {
+    if (value === null || value === undefined || value === '') continue
+    if (Array.isArray(value) && value.length === 0) continue
+    active[name] = value
+  }
+  return active
+}

package/src/entity/EntityManager.ts

@@ -654,7 +654,8 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   }
 
   /**
-   * Check if entity is system-provided (roles, users)
+   * Whether this entity is one the framework provides (roles, users). Owned
+   * by qdadm — see `EntityManagerOptions.system`.
    */
   get system(): boolean {
     return this._system

package/src/entity/EntityManager.types.ts

@@ -271,6 +271,15 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
    * drop the stale cache but leave the screen alone until the user asks.
    */
   live?: LiveEntityPolicy
+  /**
+   * Marks an entity the framework provides (`roles`, `users`). Owned by
+   * qdadm: set by its system managers (`RolesManager`, `UsersManager`), not
+   * by applications. Behaviour may be attached to it in any release.
+   *
+   * To keep a system entity on your own storage, use its manager with your
+   * storage — `new RolesManager({ storage })` — rather than setting the flag
+   * on a plain entity.
+   */
   system?: boolean
   scopeWhitelist?: string[] | null
   isOwn?: ((record: T, user: AuthUser) => boolean) | null

package/src/entity/auth/SecurityChecker.ts

@@ -26,8 +26,8 @@ export interface GrantJudgeContext {
    *
    * `install` runs while the Kernel is still being built, before modules
    * register their entities, so `getKeys()` called here returns only the
-   * framework's own namespaces. Read the keys when you pre-warm (after login,
-   * before mount), not in `install`.
+   * framework's own namespaces. Read the keys when you fetch (on `kernel:ready`
+   * or `auth:login`), not in `install`.
    */
   permissionRegistry?: { getKeys(): string[] }
 }
@@ -44,12 +44,29 @@ export interface GrantJudgeContext {
  *   built-in judgement, which stays the default.
  * - A judge that THROWS denies — see `SecurityChecker._judge`.
  *
- * `isGranted` is called synchronously on every check, so answer from memory.
- * Fetch in bulk beforehand and emit `security:changed` when answers change.
+ * `isGranted` is called synchronously on every check, so answer from memory,
+ * and emit `security:changed` when answers change.
+ *
+ * A judge whose answers come from a request cannot have them before the first
+ * navigation: it starts inside `createApp()`. Such a judge implements `ready()`
+ * (#2412), and the route guard waits for it instead of deciding early.
  */
 export interface GrantJudge {
   isGranted(attribute: string, subject: unknown, user: AuthUser): boolean | undefined
   install?(ctx: GrantJudgeContext): void
+  /**
+   * Settles once the answers for the current user are loaded (#2412).
+   *
+   * Return the promise of the load in progress — the one started on
+   * `kernel:ready`, or the new one after `auth:login` — so the route guard
+   * waits for this user's answers, not an earlier user's. A resolved promise
+   * means "decide now". A rejection, or no settling within
+   * `security.readyTimeoutMs`, denies the navigation: the unknown is never
+   * allowed, only no longer decided before the answers can exist.
+   *
+   * Optional: a judge that answers from memory from the start needs none.
+   */
+  ready?(): Promise<void>
 }
 
 /**

package/src/index.ts

@@ -164,8 +164,9 @@ export * from './entity/auth'
 // SESSION AUTH (user authentication)
 // ════════════════════════════════════════════════════════════════════════════
 export { LocalStorageSessionAuthAdapter } from './auth'
-export { GoogleOAuthAdapter, createGoogleOAuthAdapter, createPkceChallenge } from './auth'
+export { OAuthCodeAdapter, createOAuthCodeAdapter, GoogleOAuthAdapter, createGoogleOAuthAdapter, createPkceChallenge } from './auth'
 export type {
+  OAuthCodeAdapterOptions,
   GoogleOAuthAdapterOptions,
   OAuthExchangePayload,
   PkceChallenge,

package/src/kernel/Kernel.registries.ts

@@ -406,13 +406,14 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
     this._warnUnknownKeys(
       'security.',
       security,
-      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider', 'grant']),
+      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider', 'grant', 'readyTimeoutMs']),
       {
         role_hierarchy: 'roles will not inherit from one another',
         role_permissions: 'no role will carry any permission',
         entity_permissions: 'per-entity permissions will not be generated',
         rolesProvider: "the current user's roles will not be resolved",
         grant: "the application's judgement will not be consulted — the role matrix decides alone",
+        readyTimeoutMs: 'the route guard waits the default 10 s for grant.ready()',
       }
     )
   }

package/src/kernel/Kernel.routing.ts

@@ -15,6 +15,28 @@ type Self = Kernel
 /**
  * Patch Kernel prototype with routing-related methods.
  */
+/**
+ * `judge.ready()`, bounded (#2412): a judge that never settles must not hold a
+ * navigation forever. A synchronous throw from `ready()` counts as a rejection.
+ */
+function waitForJudge(judge: { ready(): Promise<void> }, timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`no answer within ${timeoutMs} ms`)), timeoutMs)
+    Promise.resolve()
+      .then(() => judge.ready())
+      .then(
+        () => {
+          clearTimeout(timer)
+          resolve()
+        },
+        (e: unknown) => {
+          clearTimeout(timer)
+          reject(e instanceof Error ? e : new Error(String(e)))
+        }
+      )
+  })
+}
+
 export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
   const proto = KernelClass.prototype
 
@@ -230,14 +252,17 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
       // declared before its manager loads) — allow. This is the ONLY
       // allowed pass-through; a failing access check must fail CLOSED,
       // not silently allow (#1190).
-      if (entity && this.orchestrator && this.orchestrator.isRegistered(entity)) {
+      const orchestrator = this.orchestrator
+      if (!entity || !orchestrator || !orchestrator.isRegistered(entity)) return
+
+      const checkEntity = (): { path: string } | undefined => {
         try {
-          const manager = this.orchestrator.get(entity)
+          const manager = orchestrator.get(entity)
           if (manager && !manager.canRead()) {
             console.warn(
               `[qdadm] Access denied to ${to.path} (entity: ${entity})`
             )
-            this.orchestrator.toast.error(
+            orchestrator.toast.error(
               'Access Denied',
               `You don't have permission to access ${manager.labelPlural || entity}`,
               'Kernel'
@@ -256,7 +281,23 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
           )
           return { path: '/' }
         }
+        return undefined
       }
+
+      // A judge whose answers come from a request cannot have them yet on the
+      // first navigation, which starts inside createApp() (#2412). Its cache
+      // miss would fall through to an empty role matrix and read as a refusal:
+      // wait for its answers instead of deciding early. Still fail closed — a
+      // judge that rejects or never settles denies.
+      const judge = this.securityChecker?.grant
+      if (typeof judge?.ready !== 'function') return checkEntity()
+      const timeoutMs = this.options.security?.readyTimeoutMs ?? 10_000
+      return waitForJudge(judge as { ready(): Promise<void> }, timeoutMs).then(checkEntity, (reason: Error) => {
+        console.error(
+          `[qdadm] security.grant never became ready for ${to.path} (entity: ${entity}): ${reason.message} — denying navigation`
+        )
+        return { path: '/' }
+      })
     })
   }
 

package/src/kernel/Kernel.types.ts

@@ -105,6 +105,11 @@ export interface SecurityConfig {
    * throws denies. See docs/security.md.
    */
   grant?: GrantJudge
+  /**
+   * How long the route guard waits for `grant.ready()` before denying (#2412).
+   * Default 10000 ms. Only used when the judge implements `ready()`.
+   */
+  readyTimeoutMs?: number
 }
 
 /**

package/src/kernel/Kernel.vue.ts

@@ -18,6 +18,8 @@ import { createQdadm } from '../plugin.js'
 import { createNotificationStore, NOTIFICATION_KEY } from '../notifications/NotificationStore'
 import { I18N_INJECTION_KEY } from '../i18n/useI18n'
 import { warnWithoutQdadmVitePlugin } from './vitePluginCheck'
+import { currentPageState } from '../composables/usePageState'
+import { explainGrant } from '../security/explainGrant'
 import type { Kernel } from './Kernel'
 // #1196 Phase B — this-typing against the real Kernel shape (was Self = any)
 type Self = Kernel
@@ -301,6 +303,12 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
         hooks: this.hookRegistry,
         zones: this.zoneRegistry,
         activeStack: this.activeStack,
+        // What the page on screen is doing — list, form or show (#2363)
+        pageState: { current: currentPageState },
+        // Why a permission is granted or denied, told the way isGranted decides it (#2363)
+        security: this.securityChecker
+          ? { explain: (attribute: string, subject: unknown = null) => explainGrant(this.securityChecker!, attribute, subject) }
+          : null,
         stackHydrator: this.stackHydrator,
         deferred: this.deferred,
         router: this.router,

package/src/security/RolesManager.ts

@@ -40,6 +40,22 @@ interface EntityManagerInstance {
   }
 }
 
+/**
+ * The `roles` system entity.
+ *
+ * It is a system entity because this manager makes it one — apps do not set
+ * `system` themselves. To keep roles behind your own API, give it your
+ * storage; it stays a system entity:
+ *
+ * ```ts
+ * ctx.entity('roles', new RolesManager({ storage: myApiStorage }))
+ * ```
+ *
+ * Two things change compared with a plain entity, and both are deliberate:
+ * every `can*` goes through ONE permission (`adminPermission`), and `fields`
+ * / `idField` assume qdadm's shape (`name`, `label`, `permissions`,
+ * `inherits`) — override them when your API serves another one.
+ */
 export class RolesManager extends EntityManager<RoleRecord> {
   private _rolesProvider: RoleProvider | null
   private _permissionRegistry: PermissionRegistry | null
@@ -128,8 +144,12 @@ export class RolesManager extends EntityManager<RoleRecord> {
   canDelete(item?: RoleRecord | null): boolean {
     if (!this._isAdmin()) return false
     if (item) {
-      // Protected system roles cannot be deleted
-      return !RolesManager.PROTECTED_ROLES.includes(item.name)
+      // Protected system roles cannot be deleted. The role code is `name` in qdadm's shape, but an
+      // app whose API keys roles differently overrides `idField` (#2406): read both, or the guard
+      // silently stops matching.
+      const record = item as unknown as Record<string, unknown>
+      const codes = [record.name, record[this.idField]]
+      return !codes.some((code) => typeof code === 'string' && RolesManager.PROTECTED_ROLES.includes(code))
     }
     return true
   }

package/src/security/explainGrant.ts

@@ -0,0 +1,55 @@
+/**
+ * Why a permission is granted or denied (#2363) — the same path as `SecurityChecker.isGranted`, told instead of
+ * answered: the app's own judge first, the role hierarchy for a `ROLE_*` attribute, then the nearest role whose
+ * grant covers the key (its exact key before a wildcard), then the user's own permissions.
+ *
+ * For the debug tools and the MCP's `page_snapshot`; it grants nothing and never changes a verdict.
+ */
+import { PermissionMatcher } from './PermissionMatcher'
+import type { SecurityChecker } from '../entity/auth/SecurityChecker'
+
+export type GrantExplanation =
+  /** No current user: everything is denied. */
+  | { granted: false; decidedBy: 'no-user' }
+  /** The app's `security.grant` function answered (a judge that throws denies). */
+  | { granted: boolean; decidedBy: 'app' }
+  /** A `ROLE_*` attribute, answered by the role hierarchy. */
+  | { granted: boolean; decidedBy: 'role-hierarchy'; roles: string[] }
+  /** A grant covers the key: `role` holds `grant` (null: the user's own permissions). */
+  | { granted: true; decidedBy: 'grant'; role: string | null; grant: string; roles: string[] }
+  /** No grant of the user's roles, nor of the user, covers the key. */
+  | { granted: false; decidedBy: 'grant'; roles: string[] }
+
+const covering = (grants: readonly string[], attribute: string): string | undefined =>
+  grants.includes(attribute) ? attribute : grants.find((g) => PermissionMatcher.matches(g, attribute))
+
+export function explainGrant(checker: SecurityChecker, attribute: string, subject: unknown = null): GrantExplanation {
+  const user = checker.getCurrentUser()
+  if (!user) return { granted: false, decidedBy: 'no-user' }
+
+  const judge = checker.grant
+  if (judge) {
+    try {
+      const answer: unknown = judge.isGranted(attribute, subject, user)
+      if (typeof answer === 'boolean') return { granted: answer, decidedBy: 'app' }
+    } catch {
+      return { granted: false, decidedBy: 'app' }
+    }
+  }
+
+  const roles = (user.roles || [user.role || '']).filter((role): role is string => Boolean(role))
+  if (attribute.startsWith('ROLE_')) {
+    return { granted: checker.roleHierarchy.isGrantedRole(roles, attribute), decidedBy: 'role-hierarchy', roles }
+  }
+
+  for (const role of roles) {
+    for (const reachable of checker.roleHierarchy.getReachableRoles(role)) {
+      const grant = covering(checker.rolesProvider.getPermissions(reachable) ?? [], attribute)
+      if (grant) return { granted: true, decidedBy: 'grant', role: reachable, grant, roles }
+    }
+  }
+  const own = covering(Array.isArray(user.permissions) ? (user.permissions as string[]) : [], attribute)
+  if (own) return { granted: true, decidedBy: 'grant', role: null, grant: own, roles }
+
+  return { granted: false, decidedBy: 'grant', roles }
+}

package/src/security/index.ts

@@ -25,6 +25,7 @@
  */
 
 export { PermissionMatcher } from './PermissionMatcher'
+export { explainGrant, type GrantExplanation } from './explainGrant'
 export {
   PermissionRegistry,
   type PermissionDefinition,