@quazardous/qdadm 2.17.1 → 2.17.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.17.1",
+  "version": "2.17.3",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -54,7 +54,7 @@
     "dist/node"
   ],
   "dependencies": {
-    "@quazardous/qdcore": "^1.1.1",
+    "@quazardous/qdcore": "^1.1.2",
     "@quazardous/qddebug": "^1.1.0",
     "@quazardous/quarkernel": "^2.1.0",
     "yaml": "^2.8.4"

package/src/entity/EntityManager.ts

@@ -357,6 +357,61 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     return { storage: this.storage }
   }
 
+  /**
+   * Announce an expired session, whatever the transport (#1905 lot A).
+   *
+   * `auth:expired` used to be emitted only by the kernel's axios response
+   * interceptor. But `SdkStorage` exists so a consumer can bring their own
+   * transport, and one that did — a fetch-based SDK — never triggered expiry
+   * detection at all: the screen kept requesting with a dead token and stacked
+   * one error toast per attempt, indefinitely.
+   *
+   * Watching here rather than in a storage adapter is deliberate. Storages
+   * have no access to the signal bus, and every call passes through this
+   * manager whichever adapter is underneath — so this covers ApiStorage,
+   * MockApiStorage, SdkStorage and whatever someone writes next.
+   *
+   * 401 only, never 403: a 403 says the session is valid and this door is
+   * closed. Logging the user out would send them to sign in again for a
+   * permission they will not have afterwards — a loop, not an error.
+   */
+  protected _watchStorageAuth(storage: IStorage<T> | null): IStorage<T> | null {
+    if (!storage || !this._signals) return storage
+
+    const emitExpired = (error: unknown): void => {
+      const status = (error as { status?: number })?.status
+      if (status !== 401) return
+      this._signals?.emit('auth:expired', { status, entity: this.name })
+    }
+
+    return new Proxy(storage as IStorage<T> & object, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver)
+        if (typeof value !== 'function') return value
+
+        return function (this: unknown, ...args: unknown[]) {
+          try {
+            const result = (value as (...a: unknown[]) => unknown).apply(
+              this === receiver ? target : this,
+              args
+            )
+            // Storage methods are async; a rejection is the normal error path.
+            if (result instanceof Promise) {
+              return result.catch((error: unknown) => {
+                emitExpired(error)
+                throw error
+              })
+            }
+            return result
+          } catch (error) {
+            emitExpired(error)
+            throw error
+          }
+        }
+      },
+    })
+  }
+
   /**
    * Normalize resolveStorage() return value to standard format
    */
@@ -367,7 +422,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     // Function = dynamic endpoint builder
     if (typeof result === 'function') {
       return {
-        storage: this.storage,
+        storage: this._watchStorageAuth(this.storage),
         endpoint: result(context),
         isDynamic: true,
       }
@@ -375,18 +430,18 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
 
     // String = endpoint with primary storage
     if (typeof result === 'string') {
-      return { storage: this.storage, endpoint: result }
+      return { storage: this._watchStorageAuth(this.storage), endpoint: result }
     }
 
     // Null/undefined = primary storage
     if (!result) {
-      return { storage: this.storage }
+      return { storage: this._watchStorageAuth(this.storage) }
     }
 
     // Object with endpoint function = dynamic endpoint builder
     if (typeof result.endpoint === 'function') {
       return {
-        storage: result.storage || this.storage,
+        storage: this._watchStorageAuth(result.storage || this.storage),
         endpoint: result.endpoint(context),
         params: result.params,
         isDynamic: true,
@@ -396,14 +451,14 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     // Object without storage = use primary storage
     if (!result.storage) {
       return {
-        storage: this.storage,
+        storage: this._watchStorageAuth(this.storage),
         endpoint: result.endpoint as string | undefined,
         params: result.params,
       }
     }
 
     return {
-      storage: result.storage,
+      storage: this._watchStorageAuth(result.storage ?? this.storage),
       endpoint: result.endpoint as string | undefined,
       params: result.params,
     }

package/src/kernel/Kernel.api.ts

@@ -46,7 +46,14 @@ export function applyApiMethods(KernelClass: { prototype: Kernel }): void {
           error: axiosError,
         })
 
-        if (status === 401 || status === 403) {
+        // 401 only, never 403 (#1905 lot F).
+        //
+        // A 403 says the session is valid and this door is closed. Logging the
+        // user out sends them to sign in again for a permission they will not
+        // have any more afterwards — a loop, not an error. The 403 still
+        // travels as api:error above, which is where a permission refusal
+        // belongs.
+        if (status === 401) {
           if (debug) {
             console.warn(
               `[Kernel] API ${status} error on ${url}, emitting auth:expired`

package/src/kernel/Kernel.auth.ts

@@ -51,8 +51,34 @@ export function applyAuthMethods(KernelClass: { prototype: Kernel }): void {
     const { authAdapter, onAuthExpired } = this.options
     if (!authAdapter) return
 
+    // A new session re-arms the guard below. Registered before the handler so
+    // the ordering is obvious to whoever reads this next.
+    this.signals!.on('auth:login', () => {
+      this._expiredHandled = false
+    })
+
     this.signals!.on('auth:expired', async (payload: { data: unknown }) => {
       const debug = this.options.debug ?? false
+
+      // One expiry per session (#1905 lot E).
+      //
+      // The handler logs out, emits auth:logout — which _setupAuthInvalidation
+      // turns into a full invalidateApp() — and redirects. Without this guard
+      // a page firing four requests that all 401 remounts the app four times
+      // while navigating to the login screen.
+      //
+      // Guarded on OUR OWN state, deliberately: an earlier draft tested
+      // `authAdapter.isAuthenticated()`, which would have skipped the very
+      // first signal for any consumer that clears its auth state before
+      // emitting — turning this fix into the silent no-op it exists to remove.
+      if (this._expiredHandled) {
+        if (debug) {
+          console.debug('[Kernel] auth:expired already handled for this session, ignoring')
+        }
+        return
+      }
+      this._expiredHandled = true
+
       if (debug) {
         console.warn('[Kernel] auth:expired received:', payload)
       }

package/src/kernel/Kernel.registries.ts

@@ -15,6 +15,7 @@ import { StackHydrator } from '../chain/StackHydrator.js'
 import { Orchestrator } from '../orchestrator/Orchestrator'
 import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { Kernel } from './Kernel'
+import type { SSEConfig } from './Kernel.types'
 // #1196 Phase B — this-typing against the real Kernel shape (was Self = any)
 type Self = Kernel
 
@@ -33,6 +34,12 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * mounted on the same Vue app.
    */
   proto._createSignalBus = function (this: Self): void {
+    // Idempotent (#1905 lot B): the constructor builds the bus so consumers can
+    // wire it immediately. Replacing it here would orphan every listener
+    // registered between construction and createApp() — silently, which is
+    // exactly the failure mode this lot exists to remove.
+    if (this.signals) return
+
     if (this.options.existingSignals) {
       this.signals = this.options.existingSignals
       return
@@ -217,12 +224,72 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
   /**
    * Create SSEBridge for Server-Sent Events to SignalBus integration
    */
+  /**
+   * Warn about unrecognised `sse` keys (#1898 lot A).
+   *
+   * A consumer configured `sse.getToken` against a version that predated it.
+   * It was not rejected — it was ignored, and the bridge fell back to the
+   * session's DURABLE token, which then travelled in the query string of every
+   * `/events` request and into logs that outlive the session by months. No
+   * error, no warning, and a stream that worked perfectly.
+   *
+   * The warning therefore names what happens INSTEAD, not merely that the key
+   * was ignored: "ignored" reads as "no effect", not as "falls back to a more
+   * sensitive secret". That reading is what made the failure invisible.
+   */
+  proto._validateSseConfig = function (this: Self, sse: SSEConfig): void {
+    const known = new Set([
+      'url',
+      'reconnectDelay',
+      'signalPrefix',
+      'autoConnect',
+      'withCredentials',
+      'tokenParam',
+      'events',
+      'entities',
+      'getToken',
+      'connectOnSignal',
+      'disconnectOnSignal',
+    ])
+
+    const unknown = Object.keys(sse).filter((key) => !known.has(key))
+    if (!unknown.length) return
+
+    // What the app loses by having the key ignored, wherever we can say it.
+    const consequences: Record<string, string> = {
+      getToken:
+        'the session auth token will be sent in the stream URL instead — ' +
+        'and query strings reach access logs',
+      entities: 'no entity cache will be invalidated from the stream',
+      tokenParam: 'the token will be sent under the default name "token"',
+    }
+
+    for (const key of unknown) {
+      const near = [...known].find(
+        (k) => k.toLowerCase() === key.toLowerCase() || k.startsWith(key) || key.startsWith(k)
+      )
+      // Look the consequence up under the NEAREST KNOWN key: a typo like
+      // `getTokens` means `getToken` is absent, and it is that absence whose
+      // effect the reader needs to hear.
+      const consequence = consequences[key] ?? (near ? consequences[near] : undefined)
+      const because = consequence ? ` — ${consequence}` : ''
+      const suggestion = near ? ` Did you mean "${near}"?` : ''
+      console.warn(
+        `[Kernel] sse.${key} is not a recognised option and is IGNORED${because}.` +
+          `${suggestion} This usually means the installed qdadm predates the option ` +
+          `— check the version before assuming the key has no effect.`
+      )
+    }
+  }
+
   proto._createSSEBridge = function (this: Self): void {
     const { sse, authAdapter } = this.options
     if (!sse?.url) return
 
     const debug = this.options.debug ?? false
 
+    this._validateSseConfig(sse)
+
     // An explicit sse.getToken wins — including an explicit null, which means
     // "send no token" and must not fall back to the auth adapter.
     const getToken =
@@ -259,6 +326,29 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       })
     }
 
+    // A restored session must connect the stream too (#1898 lot C).
+    //
+    // The bridge waits for `auth:login`, which is emitted by the LOGIN PAGE —
+    // by the interface, not by the authentication state. So reloading a page
+    // with a valid session, or revalidating one without going through our
+    // login form, left the stream permanently disconnected.
+    //
+    // Deliberately NOT fixed by emitting `auth:login` at boot: the kernel
+    // listens to it in _setupAuthInvalidation and remounts the whole app, so
+    // announcing a restored session that way would remount on every reload.
+    // Connecting the bridge directly says the same thing without the blast
+    // radius.
+    // `in`, not `??`: an EXPLICIT null means "I drive the connection myself",
+    // and `??` would treat it as absent and override the opt-out.
+    const connectsOnSignal =
+      ('connectOnSignal' in sse ? sse.connectOnSignal : 'auth:login') !== null
+    if (!sse.autoConnect && connectsOnSignal && authAdapter?.isAuthenticated?.()) {
+      if (debug) {
+        console.debug('[Kernel] session already authenticated → connecting SSE')
+      }
+      void this.sseBridge.connect()
+    }
+
     if (sse.entities) {
       this.liveEntityRouter = createLiveEntityRouter({
         signals: this.signals!,

package/src/kernel/Kernel.ts

@@ -51,6 +51,7 @@ import type {
   KernelOptions,
   InternalLayoutComponents,
   AxiosLikeClient,
+  SSEConfig as SSEConfigType,
 } from './Kernel.types'
 
 // Re-export public types
@@ -83,6 +84,15 @@ export class Kernel {
   options: KernelOptions
   vueApp: App | null = null
   router: Router | null = null
+  /**
+   * Available from construction, not from createApp() (#1905 lot B).
+   *
+   * It used to be null until createApp(), so wiring `kernel.signals` right
+   * after `new Kernel()` — the natural place — silently did nothing:
+   * `null?.emit?.()` does not throw. The bus has no dependencies, so the
+   * window existed for no reason. Removing it beats warning about it
+   * (ADR 0011).
+   */
   signals: SignalBus | null = null
   orchestrator: Orchestrator | null = null
   zoneRegistry: ZoneRegistry | null = null
@@ -99,6 +109,8 @@ export class Kernel {
   activeStack: ActiveStack | null = null
   stackHydrator: StackHydrator | null = null
   notificationStore: NotificationStore | null = null
+  /** One auth:expired per session — see Kernel.auth.ts (#1905). */
+  _expiredHandled = false
   i18nInstance: I18n | null = null
 
   /** Pending provides from modules (applied after vueApp creation) */
@@ -148,6 +160,12 @@ export class Kernel {
     }
 
     this.options = options
+
+    // The bus exists from here on (#1905 lot B). It has no dependencies, and
+    // the natural place to wire it is right after `new Kernel()` — so it must
+    // be usable there. _createSignalBus() is idempotent, so the later call in
+    // createApp() keeps this instance rather than orphaning its listeners.
+    this._createSignalBus()
   }
 
   /**
@@ -440,6 +458,7 @@ export interface Kernel {
   _createStackHydrator(): void
   _createDeferredRegistry(): void
   _createEventRouter(): void
+  _validateSseConfig(sse: SSEConfigType): void
   _createSSEBridge(): void
 
   // Vue (Kernel.vue.ts)