feat(observability): admin-gated per-request Server-Timing via X-OS-Debug-Timing (#2408)

Adds the per-request gating from the perf-tuning design so an operator can pull
a single request's `Server-Timing` breakdown on a live environment without
turning the header on for every user.

Until now perf-tuning was global-only (`serverTiming` option / `OS_SERVER_TIMING`),
which discloses internal phase durations — a mild backend-fingerprinting surface
— to every caller. This wires up the second gating path the issue describes:

- **Disclosure gate** (`@objectstack/observability`): a request-scoped
  `AsyncLocalStorage` gate, separate from the pure `PerfTiming` collector so the
  collector keeps its "only measures, never decides to emit" invariant. Pinned
  to a `Symbol.for` registry key like the collector store so the middleware
  (which seeds it) and the dispatcher (which opens it) share one store across
  ESM/CJS module copies.
- **Hono middleware**: always registered unless `serverTiming: false`. Runs the
  collector when timing is global OR the request carries `X-OS-Debug-Timing: 1`;
  emits the header only when the gate is open. Zero collector overhead (one
  header read) when neither applies.
- **Dispatcher**: after resolving the execution context, opens the gate for
  admin/service/system principals (`isSystem`, `principalKind` service/system,
  posture PLATFORM_ADMIN/TENANT_ADMIN). Ordinary callers get no header even if
  they send the debug header.
- **Env alias**: `OS_PERF_TIMING=1` now also enables global mode, matching the
  issue's naming; `OS_SERVER_TIMING=true` still works.

Tests cover the gate primitive, the middleware's per-request/global/hard-off
paths, and the admin predicate. Existing global-mode behavior is unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011upHdyr5AnNc6dWAu63qxD

Author: claude

packages/observability/src/index.ts

@@ -52,5 +52,9 @@ export {
     startServerTiming,
     measureServerTiming,
     countServerTiming,
+    runWithPerfDisclosure,
+    allowPerfDisclosure,
+    isPerfDisclosureAllowed,
     type ServerTimingMark,
+    type PerfDisclosureGate,
 } from './perf-timing.js';

packages/observability/src/perf-timing.test.ts

@@ -10,6 +10,10 @@ import {
     startServerTiming,
     measureServerTiming,
     countServerTiming,
+    runWithPerfDisclosure,
+    allowPerfDisclosure,
+    isPerfDisclosureAllowed,
+    type PerfDisclosureGate,
 } from './perf-timing.js';
 
 describe('formatServerTiming', () => {
@@ -208,3 +212,61 @@ describe('ambient collector', () => {
         expect(t.marks().map((m) => m.name)).toContain('after-await');
     });
 });
+
+describe('disclosure gate', () => {
+    it('isPerfDisclosureAllowed() is false with no active gate', () => {
+        expect(isPerfDisclosureAllowed()).toBe(false);
+    });
+
+    it('allowPerfDisclosure() is a no-op with no active gate (does not throw)', () => {
+        allowPerfDisclosure();
+        expect(isPerfDisclosureAllowed()).toBe(false);
+    });
+
+    it('reflects the seeded state inside runWithPerfDisclosure', () => {
+        const closed: PerfDisclosureGate = { allowed: false };
+        runWithPerfDisclosure(closed, () => {
+            expect(isPerfDisclosureAllowed()).toBe(false);
+        });
+        const open: PerfDisclosureGate = { allowed: true };
+        runWithPerfDisclosure(open, () => {
+            expect(isPerfDisclosureAllowed()).toBe(true);
+        });
+    });
+
+    it('allowPerfDisclosure() opens a closed gate the caller still holds', async () => {
+        const gate: PerfDisclosureGate = { allowed: false };
+        await runWithPerfDisclosure(gate, async () => {
+            await new Promise((r) => setTimeout(r, 1));
+            allowPerfDisclosure(); // after an await — same ALS scope
+        });
+        // The caller reads its own reference once the scope settles.
+        expect(gate.allowed).toBe(true);
+    });
+
+    it('leaves the gate closed when disclosure is never granted', async () => {
+        const gate: PerfDisclosureGate = { allowed: false };
+        await runWithPerfDisclosure(gate, async () => {
+            await new Promise((r) => setTimeout(r, 1));
+        });
+        expect(gate.allowed).toBe(false);
+    });
+
+    it('pins the gate store to a global-registry symbol (shared across module copies)', () => {
+        const key = Symbol.for('@objectstack/observability:perf-disclosure-gate');
+        expect((globalThis as Record<symbol, unknown>)[key]).toBeDefined();
+    });
+
+    it('is independent of the timing collector scope', () => {
+        // A collector can be active without a gate, and vice versa.
+        const t = new PerfTiming();
+        runWithPerfTiming(t, () => {
+            expect(isPerfDisclosureAllowed()).toBe(false);
+        });
+        const gate: PerfDisclosureGate = { allowed: true };
+        runWithPerfDisclosure(gate, () => {
+            expect(currentPerfTiming()).toBeUndefined();
+            expect(isPerfDisclosureAllowed()).toBe(true);
+        });
+    });
+});

packages/observability/src/perf-timing.ts

@@ -283,3 +283,64 @@ export async function measureServerTiming<T>(
 export function countServerTiming(name: string, dur: number, unit?: string): void {
     store.getStore()?.count(name, dur, unit);
 }
+
+// --- Disclosure gate (WHO may see the timing) -------------------------
+
+/**
+ * Per-request disclosure gate — the policy counterpart to the collector.
+ *
+ * The {@link PerfTiming} collector only MEASURES; whether the measured
+ * `Server-Timing` header is returned to the client is a separate decision. When
+ * perf-tuning is turned on GLOBALLY (env flag / plugin option) the operator has
+ * opted the whole environment in, so the gate opens up front and every response
+ * carries the header. When it is turned on PER-REQUEST — the caller sends an
+ * `X-OS-Debug-Timing` header — the header must stay withheld until the request
+ * proves an admin/service identity: phase durations are a mild
+ * backend-fingerprinting surface, so an ordinary user must never be able to pull
+ * them just by sending a header. The request path flips the gate open with
+ * {@link allowPerfDisclosure} once it has resolved a privileged principal.
+ *
+ * Keeping this out of {@link PerfTiming} preserves the collector's invariant
+ * ("it only measures, it never decides whether to emit").
+ */
+export interface PerfDisclosureGate {
+    /** Whether the collected timing may be disclosed to the client. */
+    allowed: boolean;
+}
+
+/**
+ * The disclosure gate lives in its OWN global-registry-pinned
+ * `AsyncLocalStorage`, for the same cross-module-copy reason as the collector
+ * store above: the middleware seeds the gate and the dispatcher (a different
+ * package, possibly a different module copy) flips it open — both must see the
+ * one store.
+ */
+const GATE_KEY = Symbol.for('@objectstack/observability:perf-disclosure-gate');
+const globalGate = globalThis as unknown as Record<symbol, AsyncLocalStorage<PerfDisclosureGate> | undefined>;
+const gateStore: AsyncLocalStorage<PerfDisclosureGate> =
+    globalGate[GATE_KEY] ?? (globalGate[GATE_KEY] = new AsyncLocalStorage<PerfDisclosureGate>());
+
+/**
+ * Run `fn` with `gate` as the ambient disclosure gate for the async call chain.
+ * The caller keeps its reference to `gate` and reads `gate.allowed` after `fn`
+ * settles to decide whether to emit the header.
+ */
+export function runWithPerfDisclosure<T>(gate: PerfDisclosureGate, fn: () => T): T {
+    return gateStore.run(gate, fn);
+}
+
+/**
+ * Open the ambient disclosure gate — the request has proven it may see its own
+ * `Server-Timing` header (admin/service identity). A no-op when no gate is
+ * active (perf-tuning off, or already-global mode with no gate to flip), so the
+ * call site stays branch-free.
+ */
+export function allowPerfDisclosure(): void {
+    const g = gateStore.getStore();
+    if (g) g.allowed = true;
+}
+
+/** Whether the ambient disclosure gate is open. `false` when none is active. */
+export function isPerfDisclosureAllowed(): boolean {
+    return gateStore.getStore()?.allowed ?? false;
+}

packages/plugins/plugin-hono-server/src/hono-plugin.test.ts

@@ -210,36 +210,40 @@ describe('HonoServerPlugin', () => {
         });
 
         it('should disable CORS when cors option is false', async () => {
+            corsConfigCapture.last = undefined;
+
             const plugin = new HonoServerPlugin({
                 cors: false
             });
 
             await plugin.init(context as PluginContext);
 
-            const serverInstance = (HonoHttpServer as any).mock.instances[0];
-            const rawApp = serverInstance.getRawApp();
-
-            // CORS middleware should NOT be registered
-            expect(rawApp.use).not.toHaveBeenCalled();
+            // CORS middleware must NOT be configured. (Assert on the CORS config,
+            // not the raw `use` count: the perf-timing middleware registers its
+            // own `use('*')` by default to catch the `X-OS-Debug-Timing` header.)
+            expect(corsConfigCapture.last).toBeUndefined();
         });
 
         it('should disable CORS when CORS_ENABLED env is false', async () => {
             const originalEnv = process.env.OS_CORS_ENABLED;
             process.env.OS_CORS_ENABLED = 'false';
+            corsConfigCapture.last = undefined;
 
-            const plugin = new HonoServerPlugin();
-            await plugin.init(context as PluginContext);
-
-            const serverInstance = (HonoHttpServer as any).mock.instances[0];
-            const rawApp = serverInstance.getRawApp();
-
-            expect(rawApp.use).not.toHaveBeenCalled();
-
-            // Restore environment
-            if (originalEnv !== undefined) {
-                process.env.OS_CORS_ENABLED = originalEnv;
-            } else {
-                delete process.env.OS_CORS_ENABLED;
+            try {
+                const plugin = new HonoServerPlugin();
+                await plugin.init(context as PluginContext);
+
+                // CORS not configured — see the note above re: the perf-timing
+                // middleware's own `use('*')`.
+                expect(corsConfigCapture.last).toBeUndefined();
+            } finally {
+                // Restore environment even if the assertion fails, so a leaked
+                // `OS_CORS_ENABLED=false` can't disable CORS in later tests.
+                if (originalEnv !== undefined) {
+                    process.env.OS_CORS_ENABLED = originalEnv;
+                } else {
+                    delete process.env.OS_CORS_ENABLED;
+                }
             }
         });
 

packages/plugins/plugin-hono-server/src/hono-plugin.ts

@@ -14,7 +14,12 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { createOriginMatcher, hasWildcardPattern, isLocalhostOrigin } from './pattern-matcher';
 import { readEnvWithDeprecation } from '@objectstack/types';
-import { PerfTiming, runWithPerfTiming } from '@objectstack/observability';
+import {
+    PerfTiming,
+    runWithPerfTiming,
+    runWithPerfDisclosure,
+    type PerfDisclosureGate,
+} from '@objectstack/observability';
 
 export interface StaticMount {
     root: string;
@@ -63,13 +68,23 @@ export interface HonoPluginOptions {
     cors?: HonoCorsOptions | false;
 
     /**
-     * Enable per-request performance timing via the `Server-Timing` response
-     * header ("perf-tuning mode"). OFF by default — the header discloses
-     * internal phase durations (total / body-parse / handler), which is handy
-     * for profiling but is also a backend-fingerprinting surface, so it is
-     * opt-in. Can also be enabled with the `OS_SERVER_TIMING=true` environment
-     * variable.
-     * @default false
+     * Per-request performance timing via the `Server-Timing` response header
+     * ("perf-tuning mode"). The header discloses internal phase durations
+     * (total / auth / db / hooks / serialize), which is handy for profiling but
+     * is also a mild backend-fingerprinting surface, so disclosure is gated:
+     *
+     *  - **GLOBAL** — `serverTiming: true`, or `OS_SERVER_TIMING=true` /
+     *    `OS_PERF_TIMING=1`: every response carries the header (an environment
+     *    under active investigation).
+     *  - **PER-REQUEST** — always available unless hard-disabled: a caller sends
+     *    `X-OS-Debug-Timing: 1` and the header is returned ONLY after the request
+     *    resolves an admin/service identity (the dispatcher opens the disclosure
+     *    gate). Ordinary users can never pull timings just by sending the header.
+     *  - `serverTiming: false` hard-disables BOTH paths (no middleware).
+     *
+     * `undefined` (the default) leaves global mode off but keeps the
+     * admin-gated per-request path available.
+     * @default undefined
      */
     serverTiming?: boolean;
 }
@@ -123,6 +138,16 @@ export function foldWildcardSuperUser(objects: Record<string, any>): void {
     }
 }
 
+/**
+ * Whether a request opted into per-request perf timing via `X-OS-Debug-Timing`.
+ * Accepts the common truthy spellings; anything else (including absent) is off.
+ */
+export function isDebugTimingRequested(value: string | undefined | null): boolean {
+    if (!value) return false;
+    const v = value.trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+
 /** Minimal schema shape the managed-write clamp needs. */
 export interface ManagedSchemaLike {
     managedBy?: string;
@@ -217,20 +242,45 @@ export class HonoServerPlugin implements Plugin {
         ctx.logger.debug('HTTP server service registered', { serviceName: 'http.server' });
 
         // ─── Server-Timing (perf-tuning mode) ─────────────────────────────────
-        // Opt-in per-request performance timing exposed via the `Server-Timing`
+        // Per-request performance timing exposed via the `Server-Timing`
         // response header. Registered FIRST (before CORS) so the `total` mark
         // brackets the whole request and the ambient timing collector is
         // established — via AsyncLocalStorage — for every downstream layer
-        // (CORS, route handler, body parse) to record sub-phases into.
-        const serverTimingEnabled =
-            this.options.serverTiming ?? (process.env.OS_SERVER_TIMING === 'true');
-        if (serverTimingEnabled) {
+        // (CORS, route handler, body parse, SQL driver, hooks) to record
+        // sub-phases into.
+        //
+        // Two ways to turn it on (see the `serverTiming` option JSDoc):
+        //   • GLOBAL   — `serverTiming: true` / `OS_SERVER_TIMING=true` /
+        //                `OS_PERF_TIMING=1`: the header is returned to EVERY
+        //                caller. The disclosure gate opens up front.
+        //   • PER-REQUEST — the caller sends `X-OS-Debug-Timing: 1`; the header
+        //                is returned ONLY after the dispatcher resolves an
+        //                admin/service identity and opens the gate, so an
+        //                ordinary user can never fingerprint the backend by
+        //                sending the header alone.
+        // `serverTiming: false` hard-disables both paths (no middleware).
+        if (this.options.serverTiming !== false) {
+            const globalTiming =
+                this.options.serverTiming === true ||
+                process.env.OS_SERVER_TIMING === 'true' ||
+                process.env.OS_PERF_TIMING === '1' ||
+                process.env.OS_PERF_TIMING === 'true';
             const rawApp = this.server.getRawApp();
             rawApp.use('*', async (c, next) => {
+                const perRequest = isDebugTimingRequested(c.req.header('X-OS-Debug-Timing'));
+                // Nothing asked for timing on this request — a single header
+                // read, then straight through. Zero collector overhead.
+                if (!globalTiming && !perRequest) return next();
+
                 const timing = new PerfTiming();
+                // Global mode opens the gate for everyone; the per-request path
+                // starts closed and is opened only if an admin/service identity
+                // is proven during dispatch (`allowPerfDisclosure`).
+                const gate: PerfDisclosureGate = { allowed: globalTiming };
                 const endTotal = timing.start('total', 'Total server time');
-                await runWithPerfTiming(timing, () => next());
+                await runWithPerfTiming(timing, () => runWithPerfDisclosure(gate, () => next()));
                 endTotal();
+                if (!gate.allowed) return; // per-request, unverified caller — withhold
                 const header = timing.toHeader();
                 // `append` (not `set`) so we coexist with any upstream proxy
                 // that already added a Server-Timing entry.