@open-mercato/shared 0.6.5-develop.5382.1.f542de69af → 0.6.5

package/src/lib/encryption/kms.ts

@@ -5,6 +5,7 @@ import { parseBooleanToken } from '../boolean'
 import { fetchWithTimeout, resolveTimeoutMs } from '../http/fetchWithTimeout'
 
 const DEFAULT_VAULT_REQUEST_TIMEOUT_MS = 1_000
+const DEFAULT_VAULT_RECOVERY_COOLDOWN_MS = 30_000
 
 function resolveVaultRequestTimeoutMs(): number {
   const raw = process.env.VAULT_REQUEST_TIMEOUT_MS
@@ -12,6 +13,12 @@ function resolveVaultRequestTimeoutMs(): number {
   return resolveTimeoutMs(parsed, DEFAULT_VAULT_REQUEST_TIMEOUT_MS)
 }
 
+function resolveVaultRecoveryCooldownMs(): number {
+  const raw = process.env.VAULT_RECOVERY_COOLDOWN_MS
+  const parsed = raw ? Number.parseInt(raw, 10) : undefined
+  return resolveTimeoutMs(parsed, DEFAULT_VAULT_RECOVERY_COOLDOWN_MS)
+}
+
 export type TenantDek = {
   tenantId: string
   key: string // base64
@@ -90,6 +97,7 @@ type VaultClientOpts = {
   mountPath?: string
   ttlMs?: number
   requestTimeoutMs?: number
+  recoveryCooldownMs?: number
 }
 
 type VaultReadResponse = {
@@ -166,7 +174,16 @@ export class HashicorpVaultKmsService implements KmsService {
   private readonly mountPath: string
   private readonly ttlMs: number
   private readonly requestTimeoutMs: number
+  private readonly recoveryCooldownMs: number
   private healthy = true
+  // Sticky terminal failure (missing VAULT_ADDR/VAULT_TOKEN): no amount of
+  // re-probing fixes a misconfiguration, so this never self-heals — only a
+  // restart with corrected config does.
+  private misconfigured = false
+  // Timestamp of the last transient failure (timeout / network blip / 5xx).
+  // Drives the half-open circuit breaker in isHealthy(): after the cooldown the
+  // instance reports healthy again so the next call re-probes Vault.
+  private lastTransientFailureAt: number | null = null
   private readonly debugEnabled: boolean
   private static loggedInit = false
 
@@ -176,9 +193,11 @@ export class HashicorpVaultKmsService implements KmsService {
     this.mountPath = (opts.mountPath || process.env.VAULT_KV_PATH || 'secret/data').replace(/\/+$/, '')
     this.ttlMs = opts.ttlMs ?? 15 * 60 * 1000
     this.requestTimeoutMs = resolveTimeoutMs(opts.requestTimeoutMs, resolveVaultRequestTimeoutMs())
+    this.recoveryCooldownMs = resolveTimeoutMs(opts.recoveryCooldownMs, resolveVaultRecoveryCooldownMs())
     this.debugEnabled = isEncryptionDebugEnabled()
     if (!this.vaultAddr || !this.vaultToken) {
       this.healthy = false
+      this.misconfigured = true
       if (this.debugEnabled) {
         console.warn('⚠️ [encryption][kms] Vault misconfigured (missing VAULT_ADDR or VAULT_TOKEN)')
       }
@@ -192,13 +211,34 @@ export class HashicorpVaultKmsService implements KmsService {
   }
 
   isHealthy(): boolean {
-    return this.healthy
+    // A missing-config failure is terminal — never report healthy again.
+    if (this.misconfigured) return false
+    if (this.healthy) return true
+    // Half-open circuit breaker: once the cooldown since the last transient
+    // failure has elapsed, report healthy so the next read/write re-probes
+    // Vault. A successful probe flips `healthy` back on; a failing one records a
+    // fresh failure timestamp and re-opens the breaker for another cooldown.
+    if (this.lastTransientFailureAt === null) return false
+    return this.now() - this.lastTransientFailureAt >= this.recoveryCooldownMs
   }
 
   private now(): number {
     return Date.now()
   }
 
+  // Vault responded successfully (or is provably reachable): close the breaker.
+  private markHealthy(): void {
+    this.healthy = true
+    this.lastTransientFailureAt = null
+  }
+
+  // Transient infra failure (timeout / network blip / 5xx): open the breaker and
+  // start the recovery cooldown so a later call can re-probe and self-heal.
+  private markTransientFailure(): void {
+    this.healthy = false
+    this.lastTransientFailureAt = this.now()
+  }
+
   private cacheHit(tenantId: string): TenantDek | null {
     const entry = this.cache.get(tenantId)
     if (!entry) return null
@@ -212,6 +252,7 @@ export class HashicorpVaultKmsService implements KmsService {
   private async readVault(path: string): Promise<VaultReadResponse | null> {
     if (!this.vaultAddr || !this.vaultToken) {
       this.healthy = false
+      this.misconfigured = true
       return null
     }
     try {
@@ -221,16 +262,21 @@ export class HashicorpVaultKmsService implements KmsService {
         timeoutMs: this.requestTimeoutMs,
       })
       if (!res.ok) {
-        this.healthy = res.status < 500
+        // 5xx = Vault down/erroring (transient). <500 (auth/not-found/etc.) means
+        // Vault is reachable and answered, so keep it healthy — a 404 for a
+        // not-yet-created tenant DEK is the normal read-before-write path.
+        if (res.status >= 500) this.markTransientFailure()
+        else this.markHealthy()
         console.warn('⚠️ [encryption][kms] Vault read failed', { path, status: res.status })
         return null
       }
+      this.markHealthy()
       if (this.debugEnabled) {
         console.info('🔍 [encryption][kms] Vault read ok', { path })
       }
       return (await res.json()) as VaultReadResponse
     } catch (err) {
-      this.healthy = false
+      this.markTransientFailure()
       console.warn('⚠️ [encryption][kms] Vault read error', {
         path,
         error: (err as Error)?.message || String(err),
@@ -243,6 +289,7 @@ export class HashicorpVaultKmsService implements KmsService {
   private async writeVault(path: string, key: string, opts?: { cas?: number }): Promise<VaultWriteOutcome> {
     if (!this.vaultAddr || !this.vaultToken) {
       this.healthy = false
+      this.misconfigured = true
       return 'error'
     }
     const body: { data: { key: string }; options?: { cas: number } } = { data: { key } }
@@ -258,21 +305,22 @@ export class HashicorpVaultKmsService implements KmsService {
         timeoutMs: this.requestTimeoutMs,
       })
       if (res.ok) {
-        this.healthy = true
+        this.markHealthy()
         return 'ok'
       }
       // KV v2 returns 400 when a check-and-set write loses to a concurrent
       // writer (path already at a newer version). That is a normal race outcome,
-      // not an unhealthy Vault — don't flip `healthy`.
+      // not an unhealthy Vault — Vault is reachable, so close the breaker.
       if (typeof opts?.cas === 'number' && res.status === 400) {
+        this.markHealthy()
         console.warn('⚠️ [encryption][kms] Vault write CAS conflict (concurrent DEK create)', { path, status: res.status })
         return 'conflict'
       }
-      this.healthy = false
+      this.markTransientFailure()
       console.warn('⚠️ [encryption][kms] Vault write failed', { path, status: res.status })
       return 'error'
     } catch (err) {
-      this.healthy = false
+      this.markTransientFailure()
       console.warn('⚠️ [encryption][kms] Vault write error', {
         path,
         error: (err as Error)?.message || String(err),

package/src/lib/query/types.ts

@@ -125,6 +125,16 @@ export type QueryOptions = {
   // Used by the search indexing pipeline to prevent feedback loops where indexing triggers
   // re-indexing indefinitely.
   skipAutoReindex?: boolean
+  /**
+   * Force routing this query to custom-entity doc storage (`custom_entities_storage`)
+   * instead of classifying the entity automatically. Automatic classification routes
+   * ids backed by a registered ORM table to that base table, so surfaces that manage
+   * doc records for ids that are ALSO table-backed (e.g. the entities records browser
+   * reading a module-declared custom entity such as `example:todo`) must set this flag.
+   * Honored by the hybrid query engine only; `BasicQueryEngine` has no doc-storage
+   * reader and ignores it.
+   */
+  forceCustomEntityStorage?: boolean
   // Optional UMES query extensions context. When provided, the engine will
   // emit sync lifecycle events and apply query-level enrichers.
   extensions?: QueryExtensionsConfig

package/src/modules/navigation/backendChrome.ts

@@ -39,6 +39,14 @@ export type BackendChromeSectionGroup = {
   order?: number
 }
 
+export type BackendChromeBrand = {
+  name?: string
+  logo?: {
+    src: string
+    alt?: string
+  } | null
+}
+
 export type BackendChromePayload = {
   groups: BackendChromeNavGroup[]
   settingsSections: BackendChromeSectionGroup[]
@@ -47,4 +55,5 @@ export type BackendChromePayload = {
   profilePathPrefixes: string[]
   grantedFeatures: string[]
   roles: string[]
+  brand?: BackendChromeBrand | null
 }