@open-mercato/shared 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/src/lib/webhooks/__tests__/body.test.ts

@@ -0,0 +1,95 @@
+/** @jest-environment node */
+import {
+  DEFAULT_WEBHOOK_BODY_LIMIT_BYTES,
+  readBoundedRequestBody,
+  resolveWebhookBodyLimitBytes,
+  WebhookBodyTooLargeError,
+} from '../body'
+
+function makeStreamingRequest(chunks: Uint8Array[], headers?: HeadersInit) {
+  let index = 0
+  const cancel = jest.fn()
+  const body = new ReadableStream<Uint8Array>({
+    pull(controller) {
+      const chunk = chunks[index]
+      index += 1
+      if (chunk) controller.enqueue(chunk)
+      else controller.close()
+    },
+    cancel,
+  })
+  const request = new Request('http://localhost/webhook', {
+    method: 'POST',
+    headers,
+    body,
+    duplex: 'half',
+  } as RequestInit & { duplex: 'half' })
+  return { request, cancel }
+}
+
+describe('readBoundedRequestBody', () => {
+  const encoder = new TextEncoder()
+
+  it('rejects an oversized declared length before reading the body', async () => {
+    const request = new Request('http://localhost/webhook', {
+      method: 'POST',
+      headers: { 'content-length': '6' },
+      body: 'ok',
+    })
+
+    await expect(readBoundedRequestBody(request, { maxBytes: 5 })).rejects.toEqual(
+      expect.objectContaining<WebhookBodyTooLargeError>({ limitBytes: 5 }),
+    )
+  })
+
+  it('stops a chunked body when its actual byte count crosses the limit', async () => {
+    const { request, cancel } = makeStreamingRequest([
+      encoder.encode('abc'),
+      encoder.encode('def'),
+      encoder.encode('never-read'),
+    ])
+
+    await expect(readBoundedRequestBody(request, { maxBytes: 5 })).rejects.toBeInstanceOf(
+      WebhookBodyTooLargeError,
+    )
+    expect(cancel).toHaveBeenCalled()
+  })
+
+  it.each([
+    ['invalid', 'not-a-number'],
+    ['lying', '3'],
+  ])('does not let a %s Content-Length bypass the streamed cap', async (_case, contentLength) => {
+    const { request } = makeStreamingRequest(
+      [encoder.encode('abc'), encoder.encode('def')],
+      { 'content-length': contentLength },
+    )
+
+    await expect(readBoundedRequestBody(request, { maxBytes: 5 })).rejects.toBeInstanceOf(
+      WebhookBodyTooLargeError,
+    )
+  })
+
+  it('preserves the exact decoded body at the byte boundary', async () => {
+    const bytes = encoder.encode('a€')
+    const { request } = makeStreamingRequest([bytes.slice(0, 2), bytes.slice(2)])
+
+    await expect(readBoundedRequestBody(request, { maxBytes: bytes.byteLength })).resolves.toBe('a€')
+  })
+})
+
+describe('resolveWebhookBodyLimitBytes', () => {
+  it('uses the documented default for missing or invalid configuration', () => {
+    expect(resolveWebhookBodyLimitBytes(undefined)).toBe(DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)
+    expect(resolveWebhookBodyLimitBytes('invalid')).toBe(DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)
+    expect(resolveWebhookBodyLimitBytes('0')).toBe(DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)
+  })
+
+  it('accepts a positive safe integer override', () => {
+    expect(resolveWebhookBodyLimitBytes('2097152')).toBe(2 * 1024 * 1024)
+  })
+
+  it('supports a source-specific fallback without weakening validation', () => {
+    expect(resolveWebhookBodyLimitBytes(undefined, 2 * 1024 * 1024)).toBe(2 * 1024 * 1024)
+    expect(resolveWebhookBodyLimitBytes('invalid', 2 * 1024 * 1024)).toBe(2 * 1024 * 1024)
+  })
+})

package/src/lib/webhooks/__tests__/verify.test.ts

@@ -1,7 +1,26 @@
 import { signWebhookPayload } from '../sign'
-import { verifyWebhookSignature } from '../verify'
+import { isWebhookTimestampWithinTolerance, verifyWebhookSignature } from '../verify'
 import { generateWebhookSecret } from '../secrets'
 
+describe('isWebhookTimestampWithinTolerance', () => {
+  it('accepts timestamps inside the configured tolerance', () => {
+    expect(isWebhookTimestampWithinTolerance('1700000000', 300, 1700000299)).toBe(true)
+  })
+
+  it('rejects stale timestamps outside the configured tolerance', () => {
+    expect(isWebhookTimestampWithinTolerance('1700000000', 300, 1700000301)).toBe(false)
+  })
+
+  it('rejects timestamps too far in the future', () => {
+    expect(isWebhookTimestampWithinTolerance('1700000601', 300, 1700000000)).toBe(false)
+  })
+
+  it('rejects malformed timestamps', () => {
+    expect(isWebhookTimestampWithinTolerance('not-a-timestamp', 300, 1700000000)).toBe(false)
+    expect(isWebhookTimestampWithinTolerance('1700000000abc', 300, 1700000000)).toBe(false)
+  })
+})
+
 describe('verifyWebhookSignature', () => {
   const msgId = 'msg_test123'
   const body = '{"type":"test.event","data":{}}'

package/src/lib/webhooks/body.ts

@@ -0,0 +1,70 @@
+import { parseNumberWithDefault } from '../number'
+
+export const DEFAULT_WEBHOOK_BODY_LIMIT_BYTES = 1024 * 1024
+
+export class WebhookBodyTooLargeError extends Error {
+  readonly limitBytes: number
+
+  constructor(limitBytes: number) {
+    super(`Webhook body exceeds the ${limitBytes}-byte limit`)
+    this.name = 'WebhookBodyTooLargeError'
+    this.limitBytes = limitBytes
+  }
+}
+
+export function resolveWebhookBodyLimitBytes(
+  raw = typeof process === 'undefined' ? undefined : process.env.OM_WEBHOOK_MAX_BODY_BYTES,
+  fallbackBytes = DEFAULT_WEBHOOK_BODY_LIMIT_BYTES,
+): number {
+  const fallback = Number.isSafeInteger(fallbackBytes) && fallbackBytes > 0
+    ? fallbackBytes
+    : DEFAULT_WEBHOOK_BODY_LIMIT_BYTES
+  const parsed = parseNumberWithDefault(raw, fallback, { min: 1 })
+  return Number.isSafeInteger(parsed) ? parsed : fallback
+}
+
+export async function readBoundedRequestBody(
+  request: Request,
+  options?: { maxBytes?: number },
+): Promise<string> {
+  const configuredLimit = options?.maxBytes ?? resolveWebhookBodyLimitBytes()
+  const maxBytes = Number.isSafeInteger(configuredLimit) && configuredLimit > 0
+    ? configuredLimit
+    : DEFAULT_WEBHOOK_BODY_LIMIT_BYTES
+  const declaredLength = request.headers.get('content-length')?.trim()
+  if (declaredLength && /^\d+$/.test(declaredLength)) {
+    const declaredBytes = Number(declaredLength)
+    if (!Number.isSafeInteger(declaredBytes) || declaredBytes > maxBytes) {
+      throw new WebhookBodyTooLargeError(maxBytes)
+    }
+  }
+
+  if (!request.body) return ''
+
+  const reader = request.body.getReader()
+  const chunks: Uint8Array[] = []
+  let totalBytes = 0
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      totalBytes += value.byteLength
+      if (totalBytes > maxBytes) {
+        await reader.cancel().catch(() => undefined)
+        throw new WebhookBodyTooLargeError(maxBytes)
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+
+  const body = new Uint8Array(totalBytes)
+  let offset = 0
+  for (const chunk of chunks) {
+    body.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder().decode(body)
+}

package/src/lib/webhooks/inbound-types.ts

@@ -0,0 +1,125 @@
+/**
+ * Inbound webhook handler types (SPEC: 2026-03-23-inbound-webhook-handlers).
+ *
+ * These mirror the event-subscriber DX: a module exports `webhook-sources.ts`
+ * (one or more `WebhookSourceConfig`) and `webhook-handlers/*.ts` files that each
+ * export `metadata: WebhookHandlerMeta` plus a default handler function.
+ */
+
+/** Raw inbound request passed to a source verifier. */
+export interface InboundWebhookRequest {
+  /** Raw request body, required for signature verification. */
+  body: string
+  /** Lower-cased request headers. */
+  headers: Record<string, string>
+  /** Parsed request body (best-effort JSON). */
+  parsedBody: Record<string, unknown>
+}
+
+/** Optional descriptor of the credential fields a source needs (drives the admin UI). */
+export interface WebhookSourceCredentialField {
+  key: string
+  label: string
+  secret?: boolean
+  required?: boolean
+}
+
+/**
+ * Configuration for an external webhook source (e.g. `stripe`, `resend`).
+ * Declared in a module's `webhook-sources.ts` via the `webhookSources` export.
+ */
+export interface WebhookSourceConfig {
+  /** Unique source identifier, e.g. `stripe`. Also the inbound path segment. */
+  key: string
+  /** Human-readable label. */
+  label: string
+  /**
+   * Verify the authenticity of an inbound webhook.
+   * Return true if valid, false to reject with 401. Throwing rejects with 400/500.
+   */
+  verifier: (
+    request: InboundWebhookRequest,
+    credentials: Record<string, string>,
+  ) => Promise<boolean>
+  /** Extract the event type from the parsed body/headers. */
+  eventTypeExtractor: (
+    body: Record<string, unknown>,
+    headers: Record<string, string>,
+  ) => string
+  /** Extract a unique message id for deduplication. Return undefined if unavailable. */
+  messageIdExtractor?: (
+    body: Record<string, unknown>,
+    headers: Record<string, string>,
+  ) => string | undefined
+  /** Optionally derive tenant scope from the payload/headers. */
+  scopeExtractor?: (
+    body: Record<string, unknown>,
+    headers: Record<string, string>,
+  ) => { tenantId?: string; organizationId?: string }
+  /** Credential fields this source needs; used by the source-credential admin UI. */
+  credentialFields?: WebhookSourceCredentialField[]
+}
+
+/** Metadata exported by every `webhook-handlers/*.ts` file. */
+export interface WebhookHandlerMeta {
+  /** Source key this handler listens to, e.g. `stripe`. */
+  source: string
+  /** Event-type pattern (supports wildcards: `*`, `payment_intent.*`). */
+  event: string
+  /** Unique handler id, e.g. `payments:stripe-payment-succeeded`. */
+  id: string
+  /** If true (default), handler runs via the queue-backed dispatcher. */
+  persistent?: boolean
+}
+
+/** Payload handed to a webhook handler. */
+export interface WebhookHandlerPayload {
+  /** Parsed webhook body. */
+  data: Record<string, unknown>
+  /** Extracted event type. */
+  eventType: string
+  /** Source key. */
+  sourceKey: string
+  /** Selected request headers. */
+  headers: Record<string, string>
+  /** WebhookIngestion record id. */
+  ingestionId: string
+  /** Tenant scope. */
+  tenantId: string
+  organizationId: string
+}
+
+/** DI accessor handed to a webhook handler. */
+export interface WebhookHandlerContext {
+  resolve: <T>(name: string) => T
+}
+
+/** A webhook handler function (default export of a `webhook-handlers/*.ts` file). */
+export type WebhookHandler = (
+  payload: WebhookHandlerPayload,
+  ctx: WebhookHandlerContext,
+) => Promise<void>
+
+/** A generated registry entry binding handler metadata to a lazy module loader. */
+export interface WebhookHandlerRegistryEntry {
+  meta: WebhookHandlerMeta
+  handler: () => Promise<{ default: WebhookHandler }>
+}
+
+/** Per-handler execution detail recorded on a WebhookIngestion. */
+export interface WebhookHandlerResult {
+  handlerId: string
+  module: string
+  status: 'success' | 'failed'
+  errorMessage?: string
+  durationMs: number
+  startedAt: string
+}
+
+/** Lifecycle status of an inbound webhook ingestion. */
+export type WebhookIngestionStatus =
+  | 'received'
+  | 'processing'
+  | 'processed'
+  | 'failed'
+  | 'duplicate'

package/src/lib/webhooks/index.ts

@@ -1,4 +1,22 @@
 export { signWebhookPayload, buildWebhookHeaders, generateMessageId } from './sign'
-export { verifyWebhookSignature } from './verify'
+export { WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, isWebhookTimestampWithinTolerance, verifyWebhookSignature } from './verify'
 export { generateWebhookSecret, parseWebhookSecret, isValidWebhookSecret } from './secrets'
+export {
+  DEFAULT_WEBHOOK_BODY_LIMIT_BYTES,
+  readBoundedRequestBody,
+  resolveWebhookBodyLimitBytes,
+  WebhookBodyTooLargeError,
+} from './body'
 export type { StandardWebhookHeaders, WebhookSigningKey, WebhookVerificationResult, StandardWebhookPayload } from './types'
+export type {
+  InboundWebhookRequest,
+  WebhookSourceCredentialField,
+  WebhookSourceConfig,
+  WebhookHandlerMeta,
+  WebhookHandlerPayload,
+  WebhookHandlerContext,
+  WebhookHandler,
+  WebhookHandlerRegistryEntry,
+  WebhookHandlerResult,
+  WebhookIngestionStatus,
+} from './inbound-types'

package/src/lib/webhooks/verify.ts

@@ -2,7 +2,21 @@ import { timingSafeEqual, createHmac } from 'node:crypto'
 import { parseWebhookSecret } from './secrets'
 import type { WebhookVerificationResult } from './types'
 
-const TOLERANCE_SECONDS = 5 * 60 // 5 minutes
+export const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 5 * 60 // 5 minutes
+
+export function isWebhookTimestampWithinTolerance(
+  timestamp: string,
+  toleranceSeconds: number = WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+  nowSeconds: number = Math.floor(Date.now() / 1000),
+): boolean {
+  const normalizedTimestamp = timestamp.trim()
+  if (!/^\d+$/.test(normalizedTimestamp)) {
+    return false
+  }
+
+  const timestampNum = Number.parseInt(normalizedTimestamp, 10)
+  return Math.abs(nowSeconds - timestampNum) <= toleranceSeconds
+}
 
 /**
  * Verify a Standard Webhooks signature against one or more secrets.
@@ -14,15 +28,9 @@ export function verifyWebhookSignature(
   body: string,
   signatureHeader: string,
   secrets: string[],
-  toleranceSeconds: number = TOLERANCE_SECONDS,
+  toleranceSeconds: number = WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
 ): WebhookVerificationResult {
-  const timestampNum = parseInt(timestamp, 10)
-  if (isNaN(timestampNum)) {
-    return { valid: false }
-  }
-
-  const now = Math.floor(Date.now() / 1000)
-  if (Math.abs(now - timestampNum) > toleranceSeconds) {
+  if (!isWebhookTimestampWithinTolerance(timestamp, toleranceSeconds)) {
     return { valid: false }
   }
 

package/src/modules/__tests__/nav-group-order-override.test.ts

@@ -0,0 +1,183 @@
+/** @jest-environment node */
+
+// `defaultGroupOrder` in `auth/lib/backendChrome.tsx` ranks any group it lists ahead of any group it
+// does not, regardless of an app's own page `priority`/`order` — so a downstream app could not place its
+// own primary module above the shipped groups by any documented means. `overrides.nav.groupOrder` wires
+// that as a real override domain, which `BACKWARD_COMPATIBILITY.md` §2 explicitly reserves for additive
+// wiring.
+
+const mockLoggerWarn = jest.fn()
+
+jest.mock('../../lib/logger', () => ({
+  createLogger: () => {
+    const child = { warn: (...args: unknown[]) => mockLoggerWarn(...args), error: jest.fn(), info: jest.fn(), debug: jest.fn() }
+    return { child: () => child, warn: child.warn, error: child.error, info: child.info, debug: child.debug }
+  },
+}))
+
+import {
+  applyModuleOverridesFromEnabledModules,
+  applyNavGroupOrderOverrides,
+  getNavGroupOrderOverride,
+  resetModuleContractOverridesForTests,
+  resetModuleOverrideAppliersForTests,
+} from '../overrides'
+
+function reset() {
+  resetModuleOverrideAppliersForTests()
+  resetModuleContractOverridesForTests()
+  mockLoggerWarn.mockClear()
+}
+
+beforeEach(reset)
+afterEach(reset)
+
+const collisionWarnings = () =>
+  mockLoggerWarn.mock.calls.filter((call) => String(call[0]).includes('nav.groupOrder declared by more than one'))
+
+describe('nav.groupOrder override domain', () => {
+  it('is unset when no module declares it', () => {
+    applyModuleOverridesFromEnabledModules([{ id: 'catalog' }, { id: 'sales', overrides: {} }])
+
+    expect(getNavGroupOrderOverride()).toBeNull()
+  })
+
+  it('captures the ids a module declares, in order — proving the domain is wired', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['app.nav.group', 'catalog.nav.group'] } } },
+    ])
+
+    expect(getNavGroupOrderOverride()).toEqual(['app.nav.group', 'catalog.nav.group'])
+    // An unwired domain would be dropped with a "not yet wired" warning instead of being captured.
+    expect(mockLoggerWarn.mock.calls.filter((call) => String(call[0]).includes('not yet wired'))).toEqual([])
+  })
+
+  it('ignores an empty list, leaving the shipped ordering in charge', () => {
+    applyModuleOverridesFromEnabledModules([{ id: 'app', overrides: { nav: { groupOrder: [] } } }])
+
+    expect(getNavGroupOrderOverride()).toBeNull()
+  })
+
+  it('drops blank entries and de-duplicates while preserving first position', () => {
+    applyModuleOverridesFromEnabledModules([
+      {
+        id: 'app',
+        overrides: { nav: { groupOrder: ['  app.nav.group  ', '', '   ', 'app.nav.group', 'catalog.nav.group'] } },
+      },
+    ])
+
+    expect(getNavGroupOrderOverride()).toEqual(['app.nav.group', 'catalog.nav.group'])
+  })
+
+  it('ignores a non-array value rather than throwing', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: 'app.nav.group' as never } } },
+    ])
+
+    expect(getNavGroupOrderOverride()).toBeNull()
+  })
+
+  it('lets the later module win when two declare an order, and says so', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'first', overrides: { nav: { groupOrder: ['first.nav.group'] } } },
+      { id: 'second', overrides: { nav: { groupOrder: ['second.nav.group'] } } },
+    ])
+
+    expect(getNavGroupOrderOverride()).toEqual(['second.nav.group'])
+    expect(collisionWarnings()).toHaveLength(1)
+  })
+
+  it('does not warn when the same module declares it twice', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['a.nav.group'] } } },
+      { id: 'app', overrides: { nav: { groupOrder: ['b.nav.group'] } } },
+    ])
+
+    expect(getNavGroupOrderOverride()).toEqual(['b.nav.group'])
+    expect(collisionWarnings()).toEqual([])
+  })
+
+  it('is cleared by the store reset hook so suites cannot leak into each other', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['app.nav.group'] } } },
+    ])
+    expect(getNavGroupOrderOverride()).not.toBeNull()
+
+    resetModuleContractOverridesForTests()
+
+    expect(getNavGroupOrderOverride()).toBeNull()
+  })
+})
+
+describe('nav.groupOrder programmatic tier', () => {
+  it('takes precedence over the modules.ts declaration', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['from-modules.nav.group'] } } },
+    ])
+    applyNavGroupOrderOverrides(['from-code.nav.group'])
+
+    expect(getNavGroupOrderOverride()).toEqual(['from-code.nav.group'])
+  })
+
+  it('falls back to the modules.ts declaration when cleared with null', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['from-modules.nav.group'] } } },
+    ])
+    applyNavGroupOrderOverrides(['from-code.nav.group'])
+    applyNavGroupOrderOverrides(null)
+
+    expect(getNavGroupOrderOverride()).toEqual(['from-modules.nav.group'])
+  })
+
+  it('applies the same normalisation as the modules.ts tier', () => {
+    applyNavGroupOrderOverrides(['  a.nav.group  ', '', 'a.nav.group', 'b.nav.group'])
+
+    expect(getNavGroupOrderOverride()).toEqual(['a.nav.group', 'b.nav.group'])
+  })
+
+  it('treats an all-blank list as no override', () => {
+    applyNavGroupOrderOverrides(['   ', ''])
+
+    expect(getNavGroupOrderOverride()).toBeNull()
+  })
+
+  it('works before any module override has been dispatched', () => {
+    applyNavGroupOrderOverrides(['standalone.nav.group'])
+
+    expect(getNavGroupOrderOverride()).toEqual(['standalone.nav.group'])
+  })
+})
+
+describe('nav.groupOrder survives module duplication', () => {
+  // Regression for `.ai/lessons.md`, "Global registries in publishable packages must use
+  // `globalThis`". This domain's writer (app bootstrap) and reader (`@open-mercato/core`'s backend
+  // chrome) sit in different packages, and standalone builds can evaluate `@open-mercato/shared`
+  // through more than one module instance. `jest.isolateModules` reproduces that: a second, freshly
+  // loaded copy of the module must still observe what the first copy stored.
+  it('a separately loaded module instance sees the value written by bootstrap', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['bootstrap.nav.group'] } } },
+    ])
+
+    let observedFromSecondInstance: readonly string[] | null | undefined
+    jest.isolateModules(() => {
+      const freshModule = require('../overrides') as typeof import('../overrides')
+      observedFromSecondInstance = freshModule.getNavGroupOrderOverride()
+    })
+
+    // A module-local variable would leave this second instance blind to the bootstrap value.
+    expect(observedFromSecondInstance).toEqual(['bootstrap.nav.group'])
+  })
+
+  it('a programmatic override is visible to a separately loaded instance too', () => {
+    applyNavGroupOrderOverrides(['programmatic.nav.group'])
+
+    let observed: readonly string[] | null | undefined
+    jest.isolateModules(() => {
+      const freshModule = require('../overrides') as typeof import('../overrides')
+      observed = freshModule.getNavGroupOrderOverride()
+    })
+
+    expect(observed).toEqual(['programmatic.nav.group'])
+  })
+})

package/src/modules/__tests__/registry.test.ts

@@ -94,7 +94,11 @@ describe('CLI Modules Registry', () => {
         {
           id: 'auth',
           defaultEncryptionMaps: [
-            { entityId: 'auth:user', fields: [{ field: 'email', hashField: 'email_hash' }] },
+            {
+              entityId: 'auth:user',
+              keyScope: 'system',
+              fields: [{ field: 'email', hashField: 'email_hash' }],
+            },
           ],
         },
         {
@@ -106,7 +110,11 @@ describe('CLI Modules Registry', () => {
       ])
 
       expect(maps).toEqual([
-        { entityId: 'auth:user', fields: [{ field: 'email', hashField: 'email_hash' }] },
+        {
+          entityId: 'auth:user',
+          keyScope: 'system',
+          fields: [{ field: 'email', hashField: 'email_hash' }],
+        },
         { entityId: 'customers:customer_comment', fields: [{ field: 'body', hashField: null }] },
       ])
     })

package/src/modules/analytics.ts

@@ -13,6 +13,13 @@ export type AnalyticsEntityTypeConfig = {
   schema?: string
   dateField: string
   defaultScopeFields: string[]
+  /**
+   * Field name (a key of `fieldMappings`) holding the per-row currency of monetary
+   * columns. Declaring it lets analytics consumers verify that the rows they aggregate
+   * all carry one currency before labelling the result with it (#4676). Omit it for
+   * entities whose amounts are not per-row denominated.
+   */
+  currencyField?: string
 }
 
 export type AnalyticsFieldMapping = {

package/src/modules/customer-auth.ts

@@ -20,6 +20,7 @@ export interface CustomerAuthContext {
   customerEntityId?: string | null
   personEntityId?: string | null
   resolvedFeatures: string[]
+  isPortalAdmin?: boolean
 }
 
 export type CustomerUser = {

package/src/modules/encryption.ts

@@ -3,7 +3,10 @@ export type ModuleEncryptionFieldRule = {
   hashField?: string | null
 }
 
+export type EncryptionKeyScope = 'tenant' | 'system'
+
 export type ModuleEncryptionMap = {
   entityId: string
+  keyScope?: EncryptionKeyScope
   fields: ModuleEncryptionFieldRule[]
 }

package/src/modules/navigation/backendChrome.ts

@@ -44,9 +44,23 @@ export type BackendChromeBrand = {
   logo?: {
     src: string
     alt?: string
+    preserveAspectRatio?: boolean
   } | null
 }
 
+/**
+ * The organization the current request is scoped to, resolved server-side.
+ *
+ * Distinct from `brand`, which is a *branding* channel and only populates when the organization has a
+ * logo configured. This is always present when a single organization is in scope, so UI can label
+ * "you are viewing: <name>" without a second round trip. `null` under an all-organizations selection,
+ * when no organization is in scope, or when the lookup fails.
+ */
+export type BackendChromeCurrentOrganization = {
+  id: string
+  name: string
+}
+
 export type BackendChromePayload = {
   groups: BackendChromeNavGroup[]
   settingsSections: BackendChromeSectionGroup[]
@@ -56,4 +70,5 @@ export type BackendChromePayload = {
   grantedFeatures: string[]
   roles: string[]
   brand?: BackendChromeBrand | null
+  currentOrganization?: BackendChromeCurrentOrganization | null
 }