@quazardous/qdadm 2.22.0 → 2.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.22.0",
+  "version": "2.23.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/edit/FormPage.vue

@@ -32,7 +32,8 @@
  * - #error: Custom error display
  * - #loading: Custom loading display
  */
-import { computed, type PropType } from 'vue'
+import { computed, inject, type PropType } from 'vue'
+import { GUARD_DIALOG_HOST } from '../../composables/useGuardStore'
 import PageHeader from '../layout/PageHeader.vue'
 import FormActions from './FormActions.vue'
 import UnsavedChangesDialog from '../dialogs/UnsavedChangesDialog.vue'
@@ -122,6 +123,10 @@ const headerActions = computed<ResolvedAction[]>(() =>
 // Get error message from fetchError
 const fetchErrorMessage = computed<string | null>(() => formatFetchError(props.fetchError))
 
+// A qdadm layout (AppLayout, BaseLayout) renders the registered guard dialog: rendering it here too
+// stacked two identical dialogs (#2267). Without such a layout, this page renders it.
+const layoutRendersGuardDialog = inject(GUARD_DIALOG_HOST, false)
+
 // Guard dialog handlers
 function onGuardSaveAndLeave(): void {
   if (props.guardDialog?.onSaveAndLeave) {
@@ -225,7 +230,7 @@ function onGuardStay(): void {
 
     <!-- Unsaved Changes Dialog -->
     <UnsavedChangesDialog
-      v-if="guardDialog"
+      v-if="guardDialog && !layoutRendersGuardDialog"
       :visible="guardDialog.visible.value"
       :saving="saving"
       :hasOnSave="guardDialog.hasOnSave"

package/src/components/layout/AppLayout.vue

@@ -19,7 +19,7 @@ import { useNavigation, type NavSection } from '../../composables/useNavigation'
 import { prettifyRole } from '../../utils/formatters'
 import { useApp } from '../../composables/useApp'
 import { useAuth } from '../../composables/useAuth'
-import { useGuardDialog } from '../../composables/useGuardStore'
+import { useGuardDialog, GUARD_DIALOG_HOST } from '../../composables/useGuardStore'
 import { useNavContext, type BreadcrumbItem, type NavLinkItem } from '../../composables/useNavContext'
 import QdButton from '../base/QdButton.vue'
 import Breadcrumb from 'primevue/breadcrumb'
@@ -56,6 +56,8 @@ const homeRoute = inject<string>('qdadmHomeRoute', 'home')
 
 // Guard dialog from shared store (registered by useBareForm/useEntityItemFormPage when a form is active)
 const guardDialog = useGuardDialog()
+// This layout renders it: pages below do not render their own (#2267)
+provide(GUARD_DIALOG_HOST, true)
 
 const router = useRouter()
 const route = useRoute()

package/src/components/layout/BaseLayout.vue

@@ -35,7 +35,7 @@ import { RouterView } from 'vue-router'
 import ConfirmDialog from 'primevue/confirmdialog'
 import Zone from './Zone.vue'
 import { LAYOUT_ZONES } from '../../zones/zones'
-import { useGuardDialog } from '../../composables/useGuardStore'
+import { useGuardDialog, GUARD_DIALOG_HOST } from '../../composables/useGuardStore'
 import UnsavedChangesDialog from '../dialogs/UnsavedChangesDialog.vue'
 import type { BreadcrumbItem, NavLinkItem } from '../../composables/useNavContext'
 
@@ -52,6 +52,8 @@ const hasMainSlot: boolean = !!slots.main
 
 // Guard dialog from shared store (registered by useBareForm/useEntityItemFormPage when a form is active)
 const guardDialog = useGuardDialog()
+// This layout renders it: pages below do not render their own (#2267)
+provide(GUARD_DIALOG_HOST, true)
 
 // Provide breadcrumb/navlinks override mechanism for child pages
 const breadcrumbOverride = ref<BreadcrumbItem[] | null>(null)

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/useGuardStore.ts

@@ -5,7 +5,13 @@
  * and parent components (AppLayout) to render it.
  */
 
-import { shallowRef, type ShallowRef, type Ref } from 'vue'
+import { shallowRef, type InjectionKey, type ShallowRef, type Ref } from 'vue'
+
+/**
+ * Provided by a layout that renders the registered guard dialog (#2267). FormPage renders its own dialog only
+ * without one above it, so a dirty form never shows the dialog twice.
+ */
+export const GUARD_DIALOG_HOST: InjectionKey<boolean> = Symbol('qdadm.guardDialogHost')
 
 /**
  * Guard dialog interface

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/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.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/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,