adonisjs-server-stats 1.15.0 → 1.16.1

package/dist/src/dashboard/sensitive_patterns.js

@@ -0,0 +1,118 @@
+/**
+ * Shared server-side rules for recognising credentials.
+ *
+ * Both the config inspector and the SQL-binding writer need to answer "does
+ * this look like a secret?", and they used to answer it differently — config
+ * values were redacted against a real word list while query bindings were only
+ * truncated by length. One list, used by both, so the same secret cannot be
+ * masked in one view and printed in full in another.
+ */
+// Custom word boundaries: `\b` does not match between `CLIENT` and `SECRET` in
+// `GOOGLE_CLIENT_SECRET`, because `_` is a word character. These treat `_`,
+// `.`, and `-` as separators, and also match a bare token on its own.
+const B = '(?:^|[_.\\-])'; // boundary before
+const A = '(?:$|[_.\\-])'; // boundary after
+/**
+ * Names that identify a credential — applies to env vars, config keys, and SQL
+ * identifiers alike.
+ */
+export const SECRET_NAME_PATTERNS = [
+    new RegExp(`${B}password${A}`, 'i'),
+    new RegExp(`${B}secret${A}`, 'i'),
+    new RegExp(`${B}token${A}`, 'i'),
+    new RegExp(`${B}credential${A}`, 'i'),
+    new RegExp(`${B}private${A}`, 'i'),
+    new RegExp(`${B}auth${A}`, 'i'),
+    // API keys: `api_key`, `apiKey`, `API_KEY`
+    /api[_-]?key/i,
+    // `_KEY` at end or `_KEY_` in middle (AWS_ACCESS_KEY_ID, ENCRYPTION_KEY, etc.)
+    /[_-]key([_-]|$)/i,
+    // ACCESS_KEY pattern (AWS credentials)
+    /access[_-]?key/i,
+    // Exact match for just "key" (standalone)
+    /^key$/i,
+    // Connection strings and DSNs
+    new RegExp(`${B}dsn${A}`, 'i'),
+    /connection[_-]?string/i,
+    // Webhook secrets
+    /webhook[_-]?secret/i,
+    // Signing / encryption
+    new RegExp(`${B}signing${A}`, 'i'),
+    new RegExp(`${B}encryption${A}`, 'i'),
+    // App key / app secret
+    /app[_-]key/i,
+    // One-time codes
+    new RegExp(`${B}otp${A}`, 'i'),
+];
+/**
+ * Names that matter for env vars and config keys but NOT for SQL identifiers.
+ *
+ * An `email` env var is usually an SMTP account; an `email` *column* is ordinary
+ * application data, and redacting every binding of every query that touches it
+ * would make the query pane useless for debugging auth. Same for the service
+ * URLs, which are env-shaped names rather than column names.
+ */
+export const CONFIG_ONLY_NAME_PATTERNS = [
+    new RegExp(`${B}email${A}`, 'i'),
+    new RegExp(`${B}smtp${A}`, 'i'),
+    /database[_-]?url/i,
+    /redis[_-]?url/i,
+];
+/** Whether a name identifies a credential. */
+export function isSecretName(name) {
+    return SECRET_NAME_PATTERNS.some((pattern) => pattern.test(name));
+}
+/** Whether a name is sensitive in a config/env context (credentials plus contact/service names). */
+export function isSensitiveConfigName(name) {
+    return isSecretName(name) || CONFIG_ONLY_NAME_PATTERNS.some((pattern) => pattern.test(name));
+}
+/** Identifier-ish tokens in a SQL statement: table names, column names, aliases. */
+const SQL_IDENTIFIER_RE = /[A-Za-z_][A-Za-z0-9_$]*/g;
+/**
+ * Whether a SQL statement mentions a credential-shaped identifier.
+ *
+ * Tokenised first: the name patterns above use `_`/`.`/`-` boundaries, so
+ * running them across raw SQL would miss `password` sitting between spaces.
+ *
+ * Positional bindings cannot be mapped back to specific columns reliably, so a
+ * hit means every binding for that statement is redacted. Coarse on purpose —
+ * over-redacting one statement's parameters beats storing a password.
+ */
+export function sqlMentionsSecret(sql) {
+    for (const match of sql.matchAll(SQL_IDENTIFIER_RE)) {
+        if (isSecretName(match[0]))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether a value looks like a credential from its shape alone, independent of
+ * any name.
+ *
+ * Deliberately excludes bare email addresses: they are sensitive as *config*
+ * (see {@link CONFIG_ONLY_NAME_PATTERNS}) but are ordinary query parameters.
+ */
+const CREDENTIAL_VALUE_PATTERNS = [
+    // URL with userinfo — credentials embedded in the URL
+    /^[a-z][a-z0-9+.-]*:\/\/[^/]*:[^/]*@/i,
+    // bcrypt / argon2 / scrypt password hashes
+    /^\$(?:2[aby]|argon2[a-z]*|scrypt|s?crypt)\$/i,
+    // JWT
+    /^ey[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\./,
+    // Well-known provider key prefixes. Underscores allowed in the tail so
+    // `sk_live_…` / `pk_test_…` match (Stripe, GitHub, Slack, AWS).
+    /^(?:sk|pk|rk|whsec)_[A-Za-z0-9_]{8,}/,
+    /^gh[pousr]_[A-Za-z0-9]{8,}/,
+    /^xox[baprs]-[A-Za-z0-9-]{8,}/,
+    /^(?:AKIA|ASIA)[A-Z0-9]{12,}$/,
+    // Long hex digests — session ids, reset tokens, sha hashes
+    /^[0-9a-f]{32,}$/i,
+];
+/** Minimum length before a base64url-shaped blob is treated as high-entropy. */
+const MIN_BLOB_LEN = 40;
+export function looksLikeCredentialValue(value) {
+    // Long high-entropy base64url blobs — length-gated, so kept out of the table.
+    if (value.length >= MIN_BLOB_LEN && /^[A-Za-z0-9_-]+={0,2}$/.test(value))
+        return true;
+    return CREDENTIAL_VALUE_PATTERNS.some((pattern) => pattern.test(value));
+}

package/dist/src/dashboard/write_queue.d.ts

@@ -21,13 +21,26 @@ export declare function markWarned(path: string): void;
  */
 export declare function normalizeSql(sql: string): string;
 /**
- * Redact/truncate SQL bindings before persistence so secret-looking values
- * (long tokens, hashes, keys) are not stored in cleartext.
+ * Redact and truncate SQL bindings before persistence.
  *
- * Conservative: only long strings are truncated; short values (ids, flags,
- * emails, ordinary params) pass through so normal capture is unaffected.
+ * Two independent rules, because neither catches everything on its own:
+ *
+ * 1. **By statement.** If the SQL mentions a credential-shaped identifier
+ *    (`password`, `remember_token`, `otp`, ...), every binding for that
+ *    statement is redacted. Positional bindings cannot be mapped back to
+ *    columns reliably, so this is all-or-nothing per statement — coarse, but
+ *    it is the only thing that catches a short secret like a 6-digit OTP.
+ * 2. **By value shape.** Hashes, JWTs, provider key prefixes, long hex
+ *    digests, and URLs with embedded credentials are redacted wherever they
+ *    appear, regardless of the statement.
+ *
+ * Anything that survives both is truncated at {@link MAX_BINDING_LEN} so an
+ * oversized payload cannot bloat the row.
+ *
+ * Ordinary parameters — ids, flags, emails, timestamps — still pass through, so
+ * the query pane stays useful for debugging.
  */
-export declare function sanitizeBindings(bindings: unknown): unknown;
+export declare function sanitizeBindings(bindings: unknown, sqlText?: string): unknown;
 export interface PreparedQuery {
     sql_text: string;
     sql_normalized: string;
@@ -51,6 +64,7 @@ export interface PreparedRequest {
     input: PersistRequestInput;
     filteredQueries: PreparedQuery[];
     traceRow: PreparedTraceRow | null;
+    eventRows: EventRow[];
 }
 export interface PreparedLog {
     [key: string]: unknown;
@@ -75,7 +89,6 @@ export interface EmailRow {
 }
 export interface EventRow {
     [key: string]: unknown;
-    request_id: null;
     event_name: string;
     data: string | null;
 }
@@ -96,19 +109,18 @@ export declare function buildEmailRow(record: EmailRecord): EmailRow;
 /**
  * Transform EventRecords into SQLite-ready row objects.
  */
+/**
+ * Build event rows. `request_id` is attached at insert time, once the owning
+ * request row has an id — leaving it null here (as this did previously) meant
+ * retention never reclaimed them, since events are only pruned via the
+ * `server_stats_requests` foreign-key cascade.
+ */
 export declare function buildEventRows(events: EventRecord[]): EventRow[];
 /**
  * Insert rows into a table in batches of 50.
  */
 export declare function batchInsert(trx: Knex.Transaction, table: string, rows: Record<string, unknown>[]): Promise<void>;
 export declare function flushRequests(trx: Knex.Transaction, preparedRequests: PreparedRequest[]): Promise<void>;
-/**
- * Flush pending events into the database.
- */
-export declare function flushEvents(trx: Knex.Transaction, events: {
-    requestIndex: number;
-    events: EventRecord[];
-}[]): Promise<void>;
 /**
  * Flush pending emails into the database.
  */

package/dist/src/dashboard/write_queue.js

@@ -6,6 +6,7 @@
  * be tested in isolation.
  */
 import { round } from '../utils/math_helpers.js';
+import { isSecretName, looksLikeCredentialValue, sqlMentionsSecret } from './sensitive_patterns.js';
 // ---------------------------------------------------------------------------
 // Warn-once tracking for write-path catch blocks
 // ---------------------------------------------------------------------------
@@ -40,27 +41,60 @@ export function normalizeSql(sql) {
 // ---------------------------------------------------------------------------
 /** Max length for a persisted string binding before it is truncated. */
 const MAX_BINDING_LEN = 256;
+/** Placeholder stored in place of a binding that looks like a credential. */
+const REDACTED_BINDING = '[redacted]';
 /**
- * Redact/truncate SQL bindings before persistence so secret-looking values
- * (long tokens, hashes, keys) are not stored in cleartext.
+ * Redact and truncate SQL bindings before persistence.
  *
- * Conservative: only long strings are truncated; short values (ids, flags,
- * emails, ordinary params) pass through so normal capture is unaffected.
+ * Two independent rules, because neither catches everything on its own:
+ *
+ * 1. **By statement.** If the SQL mentions a credential-shaped identifier
+ *    (`password`, `remember_token`, `otp`, ...), every binding for that
+ *    statement is redacted. Positional bindings cannot be mapped back to
+ *    columns reliably, so this is all-or-nothing per statement — coarse, but
+ *    it is the only thing that catches a short secret like a 6-digit OTP.
+ * 2. **By value shape.** Hashes, JWTs, provider key prefixes, long hex
+ *    digests, and URLs with embedded credentials are redacted wherever they
+ *    appear, regardless of the statement.
+ *
+ * Anything that survives both is truncated at {@link MAX_BINDING_LEN} so an
+ * oversized payload cannot bloat the row.
+ *
+ * Ordinary parameters — ids, flags, emails, timestamps — still pass through, so
+ * the query pane stays useful for debugging.
  */
-export function sanitizeBindings(bindings) {
-    if (Array.isArray(bindings))
-        return bindings.map(sanitizeBindings);
-    if (typeof bindings === 'string' && bindings.length > MAX_BINDING_LEN) {
-        return bindings.slice(0, MAX_BINDING_LEN) + `…[truncated ${bindings.length} chars]`;
+export function sanitizeBindings(bindings, sqlText) {
+    const redactAll = sqlText !== undefined && sqlMentionsSecret(sqlText);
+    return sanitizeBindingValue(bindings, redactAll);
+}
+function sanitizeBindingValue(value, redactAll) {
+    if (Array.isArray(value))
+        return value.map((v) => sanitizeBindingValue(v, redactAll));
+    if (value !== null && typeof value === 'object')
+        return sanitizeNamedBindings(value, redactAll);
+    if (typeof value === 'string')
+        return sanitizeStringBinding(value, redactAll);
+    // A statement touching a secret column may bind it as a non-string — a numeric
+    // OTP, for instance — so redact those too rather than only masking strings.
+    // Booleans and null carry nothing worth hiding.
+    const redactable = value !== null && value !== undefined && typeof value !== 'boolean';
+    return redactAll && redactable ? REDACTED_BINDING : value;
+}
+/** Named bindings carry their own key, so use it when it is telling. */
+function sanitizeNamedBindings(value, redactAll) {
+    const out = {};
+    for (const [key, nested] of Object.entries(value)) {
+        out[key] = sanitizeBindingValue(nested, redactAll || isSecretName(key));
     }
-    if (bindings && typeof bindings === 'object') {
-        const out = {};
-        for (const [k, v] of Object.entries(bindings)) {
-            out[k] = sanitizeBindings(v);
-        }
-        return out;
+    return out;
+}
+function sanitizeStringBinding(value, redactAll) {
+    if (redactAll || looksLikeCredentialValue(value))
+        return REDACTED_BINDING;
+    if (value.length > MAX_BINDING_LEN) {
+        return value.slice(0, MAX_BINDING_LEN) + `…[truncated ${value.length} chars]`;
     }
-    return bindings;
+    return value;
 }
 // ---------------------------------------------------------------------------
 // Pure data-prep functions
@@ -78,13 +112,14 @@ export function prepareRequestRows(requests) {
             .map((q) => ({
             sql_text: q.sql,
             sql_normalized: normalizeSql(q.sql),
-            bindings: q.bindings ? JSON.stringify(sanitizeBindings(q.bindings)) : null,
+            bindings: q.bindings ? JSON.stringify(sanitizeBindings(q.bindings, q.sql)) : null,
             duration: round(q.duration),
             method: q.method,
             model: q.model,
             connection: q.connection,
             in_transaction: q.inTransaction ? 1 : 0,
         })),
+        eventRows: buildEventRows(input.events ?? []),
         traceRow: input.trace
             ? {
                 method: input.trace.method,
@@ -135,9 +170,14 @@ export function buildEmailRow(record) {
 /**
  * Transform EventRecords into SQLite-ready row objects.
  */
+/**
+ * Build event rows. `request_id` is attached at insert time, once the owning
+ * request row has an id — leaving it null here (as this did previously) meant
+ * retention never reclaimed them, since events are only pruned via the
+ * `server_stats_requests` foreign-key cascade.
+ */
 export function buildEventRows(events) {
     return events.map((e) => ({
-        request_id: null,
         event_name: e.event,
         data: e.data,
     }));
@@ -176,7 +216,7 @@ function buildRequestRow(input) {
 }
 /** Insert a single prepared request with its queries and trace. */
 async function insertOneRequest(trx, prepared) {
-    const { input, filteredQueries, traceRow } = prepared;
+    const { input, filteredQueries, traceRow, eventRows } = prepared;
     const row = buildRequestRow(input);
     const [requestId] = await trx('server_stats_requests').insert(row);
     const hasId = requestId !== null && requestId !== undefined;
@@ -184,6 +224,10 @@ async function insertOneRequest(trx, prepared) {
         const rows = filteredQueries.map((q) => ({ ...q, request_id: requestId }));
         await batchInsert(trx, 'server_stats_queries', rows);
     }
+    if (hasId && eventRows.length > 0) {
+        const rows = eventRows.map((e) => ({ ...e, request_id: requestId }));
+        await batchInsert(trx, 'server_stats_events', rows);
+    }
     if (hasId && traceRow) {
         await trx('server_stats_traces').insert({ ...traceRow, request_id: requestId });
     }
@@ -202,24 +246,6 @@ export async function flushRequests(trx, preparedRequests) {
         }
     }
 }
-/**
- * Flush pending events into the database.
- */
-export async function flushEvents(trx, events) {
-    for (const { events: evts } of events) {
-        try {
-            const rows = buildEventRows(evts);
-            await batchInsert(trx, 'server_stats_events', rows);
-        }
-        catch (err) {
-            if (!hasWarned('recordEvents')) {
-                markWarned('recordEvents');
-                const { log } = await import('../utils/logger.js');
-                log.warn(`dashboard: recordEvents failed — ${err?.message}`);
-            }
-        }
-    }
-}
 /**
  * Flush pending emails into the database.
  */

package/dist/src/debug/debug_store.d.ts

@@ -3,7 +3,7 @@ import { EventCollector } from './event_collector.js';
 import { QueryCollector } from './query_collector.js';
 import { RouteInspector } from './route_inspector.js';
 import { TraceCollector } from './trace_collector.js';
-import type { DevToolbarConfig } from './types.js';
+import type { DevToolbarConfig, ResolvedCapture } from './types.js';
 /**
  * Singleton store holding all debug data collectors.
  * Bound to the AdonisJS container as `debug.store`.
@@ -14,6 +14,8 @@ export declare class DebugStore {
     readonly emails: EmailCollector;
     readonly routes: RouteInspector;
     readonly traces: TraceCollector | null;
+    /** Which collectors are allowed to subscribe in {@link start}. */
+    readonly capture: ResolvedCapture;
     constructor(config: DevToolbarConfig);
     /**
      * Register a callback that fires whenever any collector records a new item.
@@ -39,6 +41,18 @@ export declare class DebugStore {
             max: number;
         };
     };
+    /**
+     * Subscribe the enabled collectors.
+     *
+     * A disabled collector is left constructed but never subscribed, so its
+     * dashboard pane renders empty instead of erroring, and it costs nothing at
+     * runtime. This also keeps two process-wide side effects off in production:
+     * the event collector patches the emitter's `emit()`, and the trace collector
+     * patches `console.warn`.
+     *
+     * Route inspection is not gated — it reads the router table once at boot and
+     * captures no request data.
+     */
     start(emitter: unknown, router: unknown): Promise<void>;
     stop(): void;
     /** Serialize all collector data to a JSON file (atomic write). */

package/dist/src/debug/debug_store.js

@@ -48,12 +48,24 @@ export class DebugStore {
     emails;
     routes;
     traces;
+    /** Which collectors are allowed to subscribe in {@link start}. */
+    capture;
     constructor(config) {
         this.queries = new QueryCollector(config.maxQueries, config.slowQueryThresholdMs);
         this.events = new EventCollector(config.maxEvents);
         this.emails = new EmailCollector(config.maxEmails);
         this.routes = new RouteInspector();
         this.traces = config.tracing ? new TraceCollector(config.maxTraces) : null;
+        // Default to capturing everything when unset. `DebugStore` is a public
+        // export (`adonisjs-server-stats/debug`), so a config built before `capture`
+        // existed must keep behaving exactly as it did.
+        this.capture = config.capture ?? {
+            queries: true,
+            events: true,
+            emails: true,
+            traces: true,
+            logs: true,
+        };
     }
     /**
      * Register a callback that fires whenever any collector records a new item.
@@ -74,17 +86,33 @@ export class DebugStore {
             traces: this.traces?.getBufferInfo() ?? { current: 0, max: 0 },
         };
     }
+    /**
+     * Subscribe the enabled collectors.
+     *
+     * A disabled collector is left constructed but never subscribed, so its
+     * dashboard pane renders empty instead of erroring, and it costs nothing at
+     * runtime. This also keeps two process-wide side effects off in production:
+     * the event collector patches the emitter's `emit()`, and the trace collector
+     * patches `console.warn`.
+     *
+     * Route inspection is not gated — it reads the router table once at boot and
+     * captures no request data.
+     */
     async start(emitter, router) {
         // Runtime-check the emitter before passing to collectors.
         // The container returns `unknown`; collectors guard internally too.
         const e = emitter;
-        await this.queries.start(e);
-        this.events.start(e);
-        await this.emails.start(e);
+        if (this.capture.queries)
+            await this.queries.start(e);
+        if (this.capture.events)
+            this.events.start(e);
+        if (this.capture.emails)
+            await this.emails.start(e);
         if (router && typeof router.toJSON === 'function') {
             this.routes.inspect(router);
         }
-        this.traces?.start(e);
+        if (this.capture.traces)
+            this.traces?.start(e);
     }
     stop() {
         this.queries.stop();

package/dist/src/debug/event_collector.d.ts

@@ -12,6 +12,14 @@ export declare class EventCollector {
     private circulars;
     private summarizeData;
     getEvents(): EventRecord[];
+    /**
+     * Events recorded after `lastId`, oldest first.
+     *
+     * Mirrors `QueryCollector.getQueriesSince` and drives the dashboard's
+     * request pipe, which persists whatever accumulated since the previous
+     * request completed.
+     */
+    getEventsSince(lastId: number): EventRecord[];
     getLatest(n?: number): EventRecord[];
     getTotalCount(): number;
     getBufferInfo(): {

package/dist/src/debug/event_collector.js

@@ -135,6 +135,18 @@ export class EventCollector {
     getEvents() {
         return this.buffer.toArray().reverse();
     }
+    /**
+     * Events recorded after `lastId`, oldest first.
+     *
+     * Mirrors `QueryCollector.getQueriesSince` and drives the dashboard's
+     * request pipe, which persists whatever accumulated since the previous
+     * request completed.
+     */
+    getEventsSince(lastId) {
+        if (lastId <= 0)
+            return this.buffer.toArray();
+        return this.buffer.collectFromEnd((e) => e.id > lastId);
+    }
     getLatest(n = 100) {
         return this.buffer.latest(n);
     }

package/dist/src/debug/types.d.ts

@@ -288,6 +288,20 @@ export interface DevToolbarConfig {
     dbPath: string;
     /** Base path for the debug toolbar API endpoints. */
     debugEndpoint: string;
+    /**
+     * Which capture subsystems are subscribed. Fully resolved — every field is
+     * present. All true outside production; all false in production unless the
+     * user opted in via `production.capture`.
+     */
+    capture: ResolvedCapture;
+}
+/** Fully-resolved capture flags. See {@link CaptureConfig} for the user-facing shape. */
+export interface ResolvedCapture {
+    queries: boolean;
+    events: boolean;
+    emails: boolean;
+    traces: boolean;
+    logs: boolean;
 }
 /**
  * Color names available for the `badge` column format.

package/dist/src/define_config.js

@@ -126,6 +126,27 @@ function resolveDevToolbar(config) {
 function first(primary, fallback, defaultVal) {
     return primary ?? fallback ?? defaultVal;
 }
+/**
+ * Warn about a production block that cannot do what it looks like it does.
+ *
+ * Both mistakes here are silent at runtime — the dashboard simply isn't there,
+ * or is there with nothing in it — so they're worth naming at config time.
+ */
+function warnAboutProduction(config) {
+    const production = config.production;
+    if (!production?.enabled)
+        return;
+    if (!config.authorize && !config.shouldShow) {
+        log.warn('server-stats: `production.enabled` is set but no `authorize` guard is configured — ' +
+            'the routes will NOT be registered in production. `unsafeAllowNoAuth` is deliberately ' +
+            'ignored there: an unauthenticated dashboard in production is never correct.');
+    }
+    const dashboardOn = config.dashboard !== undefined && config.dashboard !== false;
+    if (!dashboardOn && !config.toolbar) {
+        log.warn('server-stats: `production.enabled` is set but neither `dashboard` nor `toolbar` is ' +
+            'enabled, so there is nothing to expose. Set `dashboard: true` to serve the dashboard.');
+    }
+}
 /**
  * Warn about `domain` values that AdonisJS will never match.
  *
@@ -154,6 +175,7 @@ export function defineConfig(config) {
     logDeprecationWarnings(config);
     if (config.domain)
         warnAboutDomain(config.domain);
+    warnAboutProduction(config);
     return {
         intervalMs: first(config.pollInterval, config.intervalMs, 3000),
         transport: resolveTransport(config),
@@ -167,5 +189,6 @@ export function defineConfig(config) {
         unsafeAllowNoAuth: config.unsafeAllowNoAuth,
         verbose,
         domain: config.domain,
+        production: config.production,
     };
 }

package/dist/src/middleware/request_tracking_middleware.d.ts

@@ -1,10 +1,11 @@
 import type { TraceCollector } from '../debug/trace_collector.js';
 import type { TraceRecord } from '../debug/types.js';
+import type { AccessGuard } from '../types.js';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { NextFn } from '@adonisjs/core/types/http';
 /** Returns true if the current async context is inside an excluded request. */
 export declare function isExcludedRequest(): boolean;
-export declare function setShouldShow(fn: ((ctx: HttpContext) => boolean) | null): void;
+export declare function setShouldShow(fn: AccessGuard | null): void;
 export declare function setTraceCollector(collector: TraceCollector | null): void;
 export declare function setDashboardPath(path: string | null): void;
 export declare function setExcludedPrefixes(prefixes: string[]): void;

package/dist/src/middleware/request_tracking_middleware.js

@@ -9,6 +9,8 @@ export function isExcludedRequest() {
 }
 let warnedShouldShow = false;
 let shouldShowFn = null;
+/** One-time latch for the async-guard-with-Edge-toolbar warning. */
+let warnedAsyncShouldShow = false;
 export function setShouldShow(fn) {
     shouldShowFn = fn;
 }
@@ -36,7 +38,20 @@ function shareShouldShowWithEdge(ctx) {
     ctxView.share({
         __ssShowFn: () => {
             try {
-                return shouldShowFn(ctx);
+                const visible = shouldShowFn(ctx);
+                // Edge evaluates this inside a compiled template statement, so it has to
+                // be synchronous. An async guard hands back a promise, which is truthy —
+                // showing the bar to everyone. Hide it instead and say why once.
+                if (typeof visible?.then === 'function') {
+                    if (!warnedAsyncShouldShow) {
+                        warnedAsyncShouldShow = true;
+                        log.warn('the `authorize` guard is async, which the @serverStats() toolbar cannot await — ' +
+                            'the stats bar stays hidden. Routes are still guarded correctly. Use a ' +
+                            'synchronous guard if you want the bar to render.');
+                    }
+                    return false;
+                }
+                return visible;
             }
             catch (err) {
                 if (!warnedShouldShow) {

package/dist/src/provider/boot_helpers.d.ts

@@ -26,5 +26,14 @@ export declare function warnAboutAuthMiddleware(config: ResolvedServerStatsConfi
  * say it out loud at boot.
  */
 export declare function warnAboutDomainWithToolbar(config: ResolvedServerStatsConfig): void;
+/**
+ * Announce that the dashboard is live in production.
+ *
+ * Deliberately `log.warn` rather than the `log.block` its neighbours use:
+ * `log.block` is suppressed unless `verbose` is on, and this is the one message
+ * that must reach every operator who enables production mode. It only fires
+ * after routes were really registered, so it never over-promises.
+ */
+export declare function announceProductionMode(config: ResolvedServerStatsConfig, paths: string[]): void;
 export declare function warnAboutSessionMiddleware(makePath: (dir: string, file: string) => string): void;
 export declare function logDashboardError(category: 'missing-dep' | 'timeout' | 'unknown', err: unknown): void;

package/dist/src/provider/boot_helpers.js

@@ -75,6 +75,37 @@ export function warnAboutDomainWithToolbar(config) {
         dim(`served from ${config.domain}. On any other host the bar will stay empty.`),
     ]);
 }
+/** Human-readable list of the capture subsystems that are switched on. */
+function describeCapture(config) {
+    const requested = config.production?.capture;
+    if (!requested)
+        return 'nothing (request metadata only)';
+    const on = ['queries', 'events', 'emails', 'traces', 'logs'].filter((key) => requested[key] === true);
+    return on.length > 0 ? on.join(', ') : 'nothing (request metadata only)';
+}
+/**
+ * Announce that the dashboard is live in production.
+ *
+ * Deliberately `log.warn` rather than the `log.block` its neighbours use:
+ * `log.block` is suppressed unless `verbose` is on, and this is the one message
+ * that must reach every operator who enables production mode. It only fires
+ * after routes were really registered, so it never over-promises.
+ */
+export function announceProductionMode(config, paths) {
+    if (!config.production?.enabled)
+        return;
+    const retention = config.production.retentionDays ?? 3;
+    const dbPath = config.devToolbar?.dbPath ?? '.adonisjs/server-stats/dashboard.sqlite3';
+    const lines = [
+        `  reachable at:  ${paths.join(', ')}`,
+        `  guard:         ${config.shouldShow ? 'authorize() configured' : 'NONE'}`,
+        `  capturing:     ${describeCapture(config)}`,
+    ];
+    if (config.devToolbar?.dashboard) {
+        lines.push(`  data at:       ${dbPath} (retention: ${retention} days)`);
+    }
+    log.warn('DASHBOARD IS LIVE IN PRODUCTION\n' + lines.join('\n'));
+}
 export function warnAboutSessionMiddleware(makePath) {
     const found = detectGlobalSessionMiddleware(makePath);
     if (found.length === 0)