@quazardous/qdadm 2.21.0 → 2.22.0

package/src/security/roleGrants.ts

@@ -0,0 +1,210 @@
+/**
+ * A role's composition, as RoleGrantsEditor draws it (#2313): which registered grants the role holds, and where
+ * each one comes from.
+ *
+ * Pure and judge-free. What inherited roles bring is given, never resolved here (the app's server may be the one
+ * that judges); wildcards are read with PermissionMatcher, `*` being one segment and `**` any number.
+ */
+import { PermissionMatcher } from './PermissionMatcher'
+
+/** A registry entry, or anything shaped like one (an app may pass its server's list). */
+export interface GrantDefinition {
+  key: string
+  namespace: string
+  action: string
+  label?: string
+  description?: string | null
+}
+
+/** A grant an inherited role brings, and the role that declares it. */
+export interface InheritedGrant {
+  permission: string
+  via: string
+}
+
+/** What RoleGrantsEditor edits: the role's own composition, never what it inherits. */
+export interface RoleComposition {
+  inherits: string[]
+  permissions: string[]
+}
+
+export interface InheritableRole {
+  name: string
+  label?: string
+  description?: string
+}
+
+export type GrantOrigin =
+  | { kind: 'none' }
+  | { kind: 'own' }
+  /** Covered by a wildcard the role holds. */
+  | { kind: 'wildcard'; via: string }
+  /** Brought by an inherited role. */
+  | { kind: 'inherited'; via: string }
+
+export interface GrantCell {
+  key: string
+  action: string
+  label: string
+  description: string | null
+  origin: GrantOrigin
+}
+
+/** One entity of the matrix: `entity:books`, or its ownership grants `entity-own:books`. */
+export interface GrantRow {
+  namespace: string
+  entity: string
+  ownRecords: boolean
+  /** `entity:books:*` */
+  wildcard: string
+  wildcardOrigin: GrantOrigin
+  /** By action; null where the entity registers no such grant. */
+  cells: Record<string, GrantCell | null>
+}
+
+/** Named grants of one namespace, as registered: `offers:debug:read` belongs to `offers:debug`, not `offers`. */
+export interface GrantGroup {
+  namespace: string
+  wildcard: string
+  wildcardOrigin: GrantOrigin
+  grants: GrantCell[]
+}
+
+/** A key of the role that is neither a registered grant nor a row or group wildcard. */
+export interface OtherGrant {
+  key: string
+  /** Registered grants it covers: 0 for a key the registry does not know. */
+  covers: number
+}
+
+export interface GrantsModel {
+  actions: string[]
+  rows: GrantRow[]
+  groups: GrantGroup[]
+  others: OtherGrant[]
+}
+
+const STANDARD_ACTIONS = ['read', 'list', 'create', 'update', 'delete']
+
+const isWildcard = (key: string) => key.includes('*')
+
+/** Where a grant comes from for the role: its own key first, then its wildcards, then what it inherits. */
+export function originOf(
+  key: string,
+  permissions: readonly string[],
+  inherited: readonly InheritedGrant[] = []
+): GrantOrigin {
+  if (permissions.includes(key)) return { kind: 'own' }
+  const wildcard = permissions.find((p) => isWildcard(p) && PermissionMatcher.matches(p, key))
+  if (wildcard) return { kind: 'wildcard', via: wildcard }
+  const brought = inherited.find((g) => PermissionMatcher.matches(g.permission, key))
+  if (brought) return { kind: 'inherited', via: brought.via }
+  return { kind: 'none' }
+}
+
+export function composeGrants(input: {
+  grants: readonly GrantDefinition[]
+  permissions: readonly string[]
+  inherited?: readonly InheritedGrant[]
+}): GrantsModel {
+  const { grants, permissions } = input
+  const inherited = input.inherited ?? []
+  const cellOf = (g: GrantDefinition): GrantCell => ({
+    key: g.key,
+    action: g.action,
+    label: g.label || g.key,
+    description: g.description ?? null,
+    origin: originOf(g.key, permissions, inherited),
+  })
+
+  const entityNamespaces = new Map<string, GrantDefinition[]>()
+  const namedNamespaces = new Map<string, GrantDefinition[]>()
+  for (const g of grants) {
+    const target = /^entity(-own)?:/.test(g.namespace) ? entityNamespaces : namedNamespaces
+    target.set(g.namespace, [...(target.get(g.namespace) ?? []), g])
+  }
+
+  const registeredActions = new Set<string>()
+  for (const list of entityNamespaces.values()) for (const g of list) registeredActions.add(g.action)
+  const actions = [
+    ...STANDARD_ACTIONS.filter((a) => registeredActions.has(a)),
+    ...[...registeredActions].filter((a) => !STANDARD_ACTIONS.includes(a)).sort(),
+  ]
+
+  const rows: GrantRow[] = [...entityNamespaces.entries()]
+    .map(([namespace, list]) => {
+      const cells: Record<string, GrantCell | null> = {}
+      for (const action of actions) {
+        const g = list.find((d) => d.action === action)
+        cells[action] = g ? cellOf(g) : null
+      }
+      const wildcard = `${namespace}:*`
+      return {
+        namespace,
+        entity: namespace.slice(namespace.indexOf(':') + 1),
+        ownRecords: namespace.startsWith('entity-own:'),
+        wildcard,
+        wildcardOrigin: originOf(wildcard, permissions, inherited),
+        cells,
+      }
+    })
+    .sort((a, b) => a.entity.localeCompare(b.entity) || Number(a.ownRecords) - Number(b.ownRecords))
+
+  const groups: GrantGroup[] = [...namedNamespaces.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([namespace, list]) => ({
+      namespace,
+      wildcard: `${namespace}:*`,
+      wildcardOrigin: originOf(`${namespace}:*`, permissions, inherited),
+      grants: list.map(cellOf),
+    }))
+
+  const registered = new Set(grants.map((g) => g.key))
+  const shown = new Set([...rows.map((r) => r.wildcard), ...groups.map((g) => g.wildcard)])
+  const keys = grants.map((g) => g.key)
+  const others = [...new Set(permissions)]
+    .filter((p) => !registered.has(p) && !shown.has(p))
+    .map((key) => ({ key, covers: isWildcard(key) ? PermissionMatcher.expand(key, keys).length : 0 }))
+
+  return { actions, rows, groups, others }
+}
+
+/** The role's own keys with one added or removed; the others keep their order. */
+export function setGrant(permissions: readonly string[], key: string, on: boolean): string[] {
+  if (on) return permissions.includes(key) ? [...permissions] : [...permissions, key]
+  return permissions.filter((p) => p !== key)
+}
+
+/** What inheritedGrants needs from a roles provider: qdadm's RoleProvider has it. */
+export interface RoleHierarchySource {
+  getPermissions(role: string): string[]
+  getHierarchy(): Record<string, string[]>
+}
+
+/**
+ * What a role inherits, for apps whose front knows the roles (qdadm's own RoleProvider): each grant with the role
+ * that declares it, the nearest one first across a chain. An app whose server judges sends this list instead.
+ */
+export function inheritedGrants(
+  provider: RoleHierarchySource | null | undefined,
+  inherits: readonly string[]
+): InheritedGrant[] {
+  if (!provider) return []
+  const hierarchy = provider.getHierarchy() ?? {}
+  const visited = new Set<string>()
+  const known = new Set<string>()
+  const out: InheritedGrant[] = []
+  const queue = [...inherits]
+  while (queue.length > 0) {
+    const role = queue.shift()!
+    if (visited.has(role)) continue
+    visited.add(role)
+    for (const permission of provider.getPermissions(role) ?? []) {
+      if (known.has(permission)) continue
+      known.add(permission)
+      out.push({ permission, via: role })
+    }
+    queue.push(...(hierarchy[role] ?? []))
+  }
+  return out
+}

package/src/styles/_forms.scss

@@ -82,18 +82,26 @@
     font-size: 0.85rem;
   }
 
-  // Force PrimeVue inputs to be full width
+  // Force PrimeVue inputs to be full width. Text-like native inputs only: a native checkbox, radio, range or
+  // colour keeps its own size (#2319). PrimeVue's Checkbox, RadioButton and ToggleSwitch size their hidden input
+  // themselves.
   .p-inputtext,
   .p-textarea,
   .p-select,
   .p-multiselect,
   .p-inputwrapper,
-  input,
+  input:not([type='checkbox']):not([type='radio']):not([type='range']):not([type='color']),
   textarea {
     width: 100% !important;
     box-sizing: border-box;
   }
 
+  // The field is a flex column: a native checkbox or radio placed directly in it would be stretched across the row.
+  > input[type='checkbox'],
+  > input[type='radio'] {
+    align-self: flex-start;
+  }
+
   .p-textarea,
   textarea {
     min-height: 100px;

package/src/styles/index.d.ts

@@ -1,5 +1,4 @@
-// Type companion for the `@quazardous/qdadm/styles` export (#1386).
-// The export resolves to a .scss file, which TypeScript cannot see through
-// the exports map — this empty module makes the side-effect import
-// `import '@quazardous/qdadm/styles'` typecheck in strict consumers.
+// Type companion for the `@quazardous/qdadm/styles` and `@quazardous/qdadm/styles/scss` exports (#1386, #2260).
+// They resolve to a stylesheet (compiled .css, or the raw .scss), which TypeScript cannot see through the
+// exports map — this empty module makes the side-effect imports typecheck in strict consumers.
 export {}

package/src/toast/ToastListener.vue

@@ -10,6 +10,7 @@
 import { onMounted, onUnmounted, inject } from 'vue'
 import { useToast } from 'primevue/usetoast'
 import type { SignalBus } from '../kernel/SignalBus'
+import { explainMissingToast } from '../kernel/vitePluginCheck'
 
 interface ToastEventData {
   summary?: string
@@ -17,7 +18,7 @@ interface ToastEventData {
   life?: number
 }
 
-const toast = useToast()
+const toast = explainMissingToast(useToast)
 const signals = inject<SignalBus | null>('qdadmSignals', null)
 
 let unsubscribe: (() => void) | null = null

package/src/types/index.ts

@@ -86,6 +86,16 @@ export interface FieldConfig {
   required?: boolean
   /** number fields: false → no locale digit grouping in displays (#1388) */
   useGrouping?: boolean
+  /**
+   * number fields: digits the form input takes after the decimal point (#2316) — `2` for always two, or
+   * `{ min, max }`. Without it the input takes whole numbers only.
+   */
+  fractionDigits?: number | { min?: number; max?: number }
+  /** number fields: bounds of the form input (#2316) */
+  min?: number
+  max?: number
+  /** number fields: increment of the form input (#2316) */
+  step?: number
   default?: unknown | (() => unknown)
   options?: Array<{ label: string; value: unknown }>
   reference?: {

package/src/vite/qdadmDebugPlugin.ts

@@ -8,10 +8,12 @@
  *   GET  /__qdadm/snapshot.json       — bridge.dump() (live state)
  *   POST /__qdadm/call                — body {collector, action, args?}
  *
- * Session selection: every browser tab that loads the app gets a fresh
- * session id (uuid in the injected client). All endpoints accept a
- * `?session=<id|latest>` query param. Default is `latest` (the most recently
- * active session).
+ * Session selection: every browser tab gets a session id (uuid in the
+ * injected client), kept in sessionStorage so a reload is the SAME session
+ * (#2231). A tab that says bye stays known through a short grace window: a
+ * request to it answers "reloading" instead of timing out. All endpoints
+ * accept a `?session=<id|latest>` query param. Default is `latest` (the most
+ * recently active connected session).
  *
  * Wire-up: the plugin injects a small ESM script via `transformIndexHtml`.
  * That inline script lives in Vite's HMR pipeline (so `import.meta.hot`
@@ -78,6 +80,8 @@ interface SessionState {
   describe: { data: unknown; at: number } | null
   snapshot: { data: unknown; at: number } | null
   meta: Record<string, unknown>
+  /** Set by bye; cleared by the next push from the same tab. */
+  disconnectedAt: number | null
 }
 
 /** Broker surface exposed to sibling plugins via `plugin.api` (#1398). */
@@ -95,6 +99,7 @@ export interface QdadmDebugPluginApi {
     ageMs: number
     hasDescribe: boolean
     hasSnapshot: boolean
+    connected: boolean
     meta: Record<string, unknown>
   }>
   prefix: string
@@ -107,12 +112,15 @@ export interface QdadmDebugPluginOptions {
   timeoutMs?: number
   /** Drop sessions inactive for this many ms (default 10 min) */
   sessionTtlMs?: number
+  /** Keep a tab that said bye this long, so its reload keeps it (default 30 s) */
+  reloadGraceMs?: number
 }
 
 export function qdadmDebugPlugin(options: QdadmDebugPluginOptions = {}): Plugin {
   const prefix = options.prefix ?? '/__qdadm'
   const timeoutMs = options.timeoutMs ?? 3000
   const sessionTtlMs = options.sessionTtlMs ?? 10 * 60 * 1000
+  const reloadGraceMs = options.reloadGraceMs ?? 30 * 1000
 
   const sessions = new Map<string, SessionState>()
   const pending = new Map<string, PendingRequest>()
@@ -120,18 +128,25 @@ export function qdadmDebugPlugin(options: QdadmDebugPluginOptions = {}): Plugin
   let nextId = 1
 
   function pruneStaleSessions(): void {
-    const cutoff = Date.now() - sessionTtlMs
+    const now = Date.now()
     for (const [id, s] of sessions) {
-      if (s.lastSeenAt < cutoff) sessions.delete(id)
+      if (s.lastSeenAt < now - sessionTtlMs) sessions.delete(id)
+      else if (s.disconnectedAt !== null && s.disconnectedAt < now - reloadGraceMs) sessions.delete(id)
     }
   }
 
   function pickSession(sessionParam: string | null): SessionState | null {
     pruneStaleSessions()
     if (!sessionParam || sessionParam === 'latest') {
+      // A connected tab wins; a reloading one only when nothing else is up,
+      // so the caller hears "reloading" rather than "no session".
       let best: SessionState | null = null
       for (const s of sessions.values()) {
-        if (!best || s.lastSeenAt > best.lastSeenAt) best = s
+        const better =
+          !best ||
+          (best.disconnectedAt !== null && s.disconnectedAt === null) ||
+          ((best.disconnectedAt === null) === (s.disconnectedAt === null) && s.lastSeenAt > best.lastSeenAt)
+        if (better) best = s
       }
       return best
     }
@@ -144,6 +159,15 @@ export function qdadmDebugPlugin(options: QdadmDebugPluginOptions = {}): Plugin
     sessionId?: string
   ): Promise<unknown> {
     if (!server) return Promise.reject(new Error('[qdadm-debug] vite server not ready'))
+    const target = sessionId ? sessions.get(sessionId) : undefined
+    if (target?.disconnectedAt) {
+      const away = Math.round((Date.now() - target.disconnectedAt) / 1000)
+      return Promise.reject(
+        new Error(
+          `[qdadm-debug] session ${target.id.slice(0, 8)} left ${away}s ago — the tab is most likely reloading; retry in a few seconds`
+        )
+      )
+    }
     const id = String(nextId++)
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
@@ -200,6 +224,7 @@ export function qdadmDebugPlugin(options: QdadmDebugPluginOptions = {}): Plugin
     ageMs: number
     hasDescribe: boolean
     hasSnapshot: boolean
+    connected: boolean
     meta: Record<string, unknown>
   }> {
     pruneStaleSessions()
@@ -213,6 +238,7 @@ export function qdadmDebugPlugin(options: QdadmDebugPluginOptions = {}): Plugin
         ageMs: now - s.lastSeenAt,
         hasDescribe: !!s.describe,
         hasSnapshot: !!s.snapshot,
+        connected: s.disconnectedAt === null,
         meta: s.meta,
       }))
   }
@@ -227,10 +253,12 @@ export function qdadmDebugPlugin(options: QdadmDebugPluginOptions = {}): Plugin
         describe: null,
         snapshot: null,
         meta: meta ?? {},
+        disconnectedAt: null,
       }
       sessions.set(id, s)
     } else {
       s.lastSeenAt = Date.now()
+      s.disconnectedAt = null
       if (meta) s.meta = { ...s.meta, ...meta }
     }
     return s
@@ -287,7 +315,7 @@ export function qdadmDebugPlugin(options: QdadmDebugPluginOptions = {}): Plugin
         } else if (msg.type === 'snapshot' && msg.data !== undefined) {
           session.snapshot = { data: msg.data, at }
         } else if (msg.type === 'bye') {
-          sessions.delete(msg.sessionId)
+          session.disconnectedAt = at
         }
       })
 
@@ -376,7 +404,8 @@ function readBody(req: IncomingMessage): Promise<string> {
  * Client-side bridge — injected verbatim into index.html as an ES module.
  * Lives in Vite's HMR pipeline (so `import.meta.hot` works here).
  *
- * Each tab gets its own session id (random uuid). Pushes describe + snapshot
+ * Each tab gets its own session id (random uuid, kept across reloads in
+ * sessionStorage — #2231). Pushes describe + snapshot
  * on every reactive tick of the bridge so the plugin's per-session cache
  * stays fresh. Listens for ad-hoc requests targeted at this session.
  */
@@ -413,7 +442,14 @@ const hot = import.meta.hot
 if (!hot) {
   console.warn('[qdadm-debug] import.meta.hot unavailable in injected script')
 } else {
-  const sessionId = crypto.randomUUID()
+  // Same tab, same session across reloads (#2231): an agent's target survives F5.
+  const sessionId = (() => {
+    try {
+      let v = sessionStorage.getItem('qdadm-debug:session')
+      if (!v) { v = crypto.randomUUID(); sessionStorage.setItem('qdadm-debug:session', v) }
+      return v
+    } catch (e) { return crypto.randomUUID() }
+  })()
   const meta = { userAgent: navigator.userAgent, location: location.pathname }
   let bridge = null
   let lastTick = -1

package/src/vite/qdadmPlugin.ts

@@ -118,6 +118,8 @@ export function qdadmVitePlugin(options: QdadmVitePluginOptions = {}): Plugin {
           exclude: [...widgetExcludes, ...themesExcludes, '@quazardous/qdadm'],
         },
         ...(fsAllow.length > 0 ? { server: { fs: { allow: fsAllow } } } : {}),
+        // The kernel checks it: an app without this plugin is told what to add (#2259).
+        define: { __QDADM_VITE_PLUGIN__: 'true' },
       }
     },
   }