adonisjs-server-stats 1.15.0 → 1.16.1

package/README.md

@@ -182,6 +182,7 @@ All fields are optional. `defineConfig({})` works with zero configuration.
 | `authorize`     | `(ctx) => boolean`                | --                          | Per-request visibility guard                                     |
 | `unsafeAllowNoAuth` | `boolean`                     | `false`                     | Register the dashboard/debug/stats routes even with **no** `authorize` guard. Off by default (routes fail closed). Local dev only — exposes secrets, email bodies, and SQL. |
 | `domain`        | `string`                          | --                          | Restrict every route to one host, e.g. `'admin.example.com'`. See [Custom domain](#custom-domain) |
+| `production`    | `ProductionConfig`                | --                          | Opt in to running in production. Off by default -- see [Production](#production) |
 | `onStats`       | `(stats) => void`                 | --                          | Callback after each collection tick                              |
 | `toolbar`       | `boolean \| ToolbarConfig`        | --                          | `true` to enable with defaults, or pass a `ToolbarConfig` object |
 | `dashboard`     | `boolean \| DashboardConfig`      | --                          | `true` to enable at `/__stats`, or pass a `DashboardConfig`      |
@@ -205,6 +206,16 @@ All fields are optional. `defineConfig({})` works with zero configuration.
 | `path`          | `string` | `'/__stats'` | URL path for the dashboard page        |
 | `retentionDays` | `number` | `7`          | Days to keep historical data in SQLite |
 
+### `ProductionConfig`
+
+| Option          | Type            | Default | Description                                                            |
+| --------------- | --------------- | ------- | ---------------------------------------------------------------------- |
+| `enabled`       | `boolean`       | `false` | Register routes and build the dashboard when `NODE_ENV=production`      |
+| `capture`       | `CaptureConfig` | all off | Which capture subsystems to switch on -- opt in one at a time           |
+| `retentionDays` | `number`        | `3`     | SQLite history to keep in production (the usual default is 7)           |
+
+`CaptureConfig` fields, each `boolean` and each defaulting to `false` in production: `queries`, `events`, `emails`, `traces`, `logs`.
+
 ### `AdvancedConfig`
 
 | Option          | Type                | Default                                      | Description                                     |
@@ -384,6 +395,81 @@ export default defineConfig({
 
 ---
 
+## Production
+
+By default this package does **nothing** when `NODE_ENV=production` -- no routes are registered and neither the debug nor the dashboard store is built. The metrics engine still runs, so `onStats`, Prometheus, and Transmit broadcasting keep working; there is simply no HTTP surface.
+
+Set `production.enabled` to lift that:
+
+```ts
+export default defineConfig({
+  authorize: async (ctx) => (await ctx.auth.check()) && ctx.auth.user?.isAdmin === true,
+  dashboard: true,
+
+  production: {
+    enabled: true,
+    capture: { queries: true }, // everything else stays off
+    retentionDays: 3,
+  },
+})
+```
+
+### An `authorize` guard is mandatory
+
+`unsafeAllowNoAuth` is **ignored** in production. Without a guard the routes are not registered and a warning explains why -- an unauthenticated dashboard on a production host is never correct.
+
+When production mode is active you get an unmissable startup banner, so nobody enables this and forgets:
+
+```
+[ server-stats ] DASHBOARD IS LIVE IN PRODUCTION
+  reachable at:  /admin/api/server-stats, /admin/api/debug/*, /__stats/*
+  guard:         authorize() configured
+  capturing:     queries
+  data at:       .adonisjs/server-stats/dashboard.sqlite3 (retention: 3 days)
+```
+
+### Capture is off unless you ask for it
+
+Each capture subsystem hooks something global and stores something sensitive, so in production every one starts **off** and is enabled by name:
+
+| `capture` flag | What it records                     | Why it's off by default                          |
+| -------------- | ----------------------------------- | ------------------------------------------------ |
+| `queries`      | SQL text, bindings, timings         | Bindings can hold values you would not log       |
+| `events`       | Application events (memory only)    | Patches the emitter's `emit()` process-wide      |
+| `emails`       | Sent mail incl. subject and body    | Highest-sensitivity payload in the package       |
+| `traces`       | Per-request spans                   | Wraps every request in `AsyncLocalStorage`       |
+| `logs`         | Log lines into SQLite               | Highest write volume, and logs quote payloads    |
+
+**With no capture flags at all you still get the useful core:** the request list, the overview, and the charts. Those come from request rows and 1-minute metric buckets, at a small fraction of full dev-mode write volume. Turn capture on when you are actually debugging something.
+
+A disabled subsystem is never subscribed, so it costs nothing -- its dashboard pane simply stays empty.
+
+> [!NOTE]
+> `toolbar: { tracing: false }` still overrides `capture.traces`. It is the older kill switch and keeps winning.
+
+### Disk
+
+Retention prunes rows older than `retentionDays` on boot and hourly. It does **not** run `VACUUM`, so the `.sqlite3` file reuses freed pages rather than shrinking -- expect the file to plateau, not shrink. Watch real numbers in the dashboard's storage panel (`GET {dashboardPath}/api/storage`), which reports file size, WAL size, and per-table row counts.
+
+There is no sampling and no hard size cap. On a high-traffic app, enable capture deliberately and keep `retentionDays` short.
+
+### Async guards and the toolbar
+
+An `authorize` callback may be sync or async -- the route guard awaits it, so `async (ctx) => { await ctx.auth.authenticate(); ... }` is safe.
+
+> [!WARNING]
+> The `@serverStats()` Edge toolbar evaluates the guard **synchronously** while rendering, so it cannot await. With an async guard the stats bar hides itself rather than risk showing when it shouldn't, and logs a warning once. The HTTP routes are guarded correctly either way -- only the cosmetic bar is affected. Use a synchronous guard if you want the bar in production.
+
+### What this does not give you
+
+Worth knowing before you expose it, even behind an admin guard:
+
+- **One guard, no tiers.** Anyone who passes `authorize` can also `DELETE /api/cache/:key` and `POST /api/jobs/:id/retry`. Scope cache access with `SERVER_STATS_CACHE_KEY_PREFIX` -- unset means unrestricted.
+- **No audit log and no rate limiting** on those mutating endpoints.
+- **SQL bindings are truncated at 256 characters but not redacted by key name.** A short secret passed as a bound parameter is stored as-is. Config and env values *are* redacted; query bindings are not.
+
+---
+
 ## Auto-Registered Routes
 
 All API routes are registered automatically by the package during `boot()` -- no manual controllers or route definitions needed. Each route group is gated by the `authorize` callback if configured.
@@ -466,7 +552,7 @@ Pass a bare host. A protocol, path, or port (`https://admin.example.com`, `admin
 
 > **The toolbar follows the domain.** The `@serverStats()` Edge tag and the React/Vue components request **relative** URLs, so they only work on pages served from the configured domain. Render the toolbar on `example.com` while `domain` points at `admin.example.com` and the bar will sit empty -- its polls 404 against the wrong host. Either serve the toolbar from the same domain, or leave `domain` unset and rely on `authorize` alone.
 
-> **Reminder:** routes are never registered in production regardless of this setting (`app.inProduction` short-circuits registration), so `domain` applies to your dev and staging environments.
+> **Reminder:** routes are not registered in production unless you opt in via [`production.enabled`](#production). Without that, `domain` applies to your dev and staging environments only.
 
 ### Global middleware note
 
@@ -653,7 +739,7 @@ Found a bug? Have feedback? [Open an issue](https://github.com/simulieren/adonis
 
 ## Dev Toolbar
 
-Adds a debug panel with SQL query inspection, event tracking, email capture with HTML preview, route table, live logs, and per-request tracing. Only active in non-production environments.
+Adds a debug panel with SQL query inspection, event tracking, email capture with HTML preview, route table, live logs, and per-request tracing. Active in non-production environments by default; see [Production](#production) to opt in there.
 
 ```ts
 export default defineConfig({

package/dist/core/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/core/types.d.ts

@@ -435,6 +435,94 @@ export interface DashboardConfig {
      */
     retentionDays?: number;
 }
+/**
+ * Access-control callback signature.
+ *
+ * May be sync or async — the route guard awaits it. An async guard is the usual
+ * shape once the check has to consult `ctx.auth` or the database.
+ *
+ * One caveat: the `@serverStats()` Edge tag evaluates the guard synchronously
+ * while rendering the template, so with an **async** guard the toolbar hides
+ * itself rather than risk showing when it shouldn't. The HTTP routes await it
+ * properly either way — only the cosmetic bar is affected.
+ */
+export type AccessGuard = (ctx: import('@adonisjs/core/http').HttpContext) => boolean | Promise<boolean>;
+/**
+ * Which capture subsystems are active.
+ *
+ * Each one hooks a global: queries and events subscribe to the Lucid/app
+ * emitter, emails subscribe to the mail events, traces wrap every request in
+ * `AsyncLocalStorage`. Turning one off means its collector is never subscribed,
+ * so it costs nothing — its dashboard pane simply stays empty.
+ *
+ * Outside production every field defaults to `true`. In production every field
+ * defaults to **`false`** and must be opted into individually.
+ */
+export interface CaptureConfig {
+    /** SQL text, bindings, and timings for every query. */
+    queries?: boolean;
+    /** Application events (in-memory only — never persisted to SQLite). */
+    events?: boolean;
+    /** Sent mail, including subject and body. */
+    emails?: boolean;
+    /** Per-request spans and the request timeline. */
+    traces?: boolean;
+    /** Log lines written into the dashboard's SQLite store. */
+    logs?: boolean;
+}
+/**
+ * Opt in to running the dashboard in production.
+ *
+ * By default this package registers **no routes** when `NODE_ENV=production`
+ * and never builds the debug or dashboard stores. Setting `enabled: true` lifts
+ * that, but only with an {@link ServerStatsConfig.authorize} guard in place —
+ * `unsafeAllowNoAuth` is ignored in production.
+ *
+ * Data capture stays **off** unless you ask for it. Without any `capture`
+ * flags you still get the request list, the overview, and the charts (those
+ * come from request rows and 1-minute metric buckets), at a small fraction of
+ * the write volume of a full dev-mode capture.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   authorize: async (ctx) => (await ctx.auth.check()) && ctx.auth.user?.isAdmin === true,
+ *   dashboard: true,
+ *   production: {
+ *     enabled: true,
+ *     capture: { queries: true },
+ *     retentionDays: 3,
+ *   },
+ * })
+ * ```
+ */
+export interface ProductionConfig {
+    /**
+     * Register routes and build the dashboard when `NODE_ENV=production`.
+     *
+     * Requires an `authorize` guard — without one the routes are still not
+     * registered, and a warning explains why.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Which capture subsystems to switch on. Every field defaults to `false` in
+     * production, so capture is opt-in one subsystem at a time.
+     *
+     * @see {@link CaptureConfig}
+     */
+    capture?: CaptureConfig;
+    /**
+     * How many days of history to keep in SQLite, overriding the usual default
+     * of 7. Retention deletes rows hourly but never runs `VACUUM`, so the
+     * database file reuses pages rather than shrinking — watch actual size via
+     * the dashboard's storage panel.
+     *
+     * @default 3
+     */
+    retentionDays?: number;
+}
 /**
  * Advanced options that most users never need to touch.
  *
@@ -699,7 +787,7 @@ export interface ServerStatsConfig {
      *
      * @deprecated Use {@link authorize} instead. Will be removed in the next major version.
      */
-    shouldShow?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    shouldShow?: AccessGuard;
     /**
      * How often (in **milliseconds**) to run all collectors and
      * broadcast updated stats.
@@ -750,7 +838,7 @@ export interface ServerStatsConfig {
      * authorize: () => process.env.NODE_ENV === 'development'
      * ```
      */
-    authorize?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    authorize?: AccessGuard;
     /**
      * Register the sensitive dashboard/debug/stats routes WITHOUT any access
      * guard when no {@link authorize} callback is provided.
@@ -833,6 +921,21 @@ export interface ServerStatsConfig {
      * ```
      */
     domain?: string;
+    /**
+     * Opt in to running in production, where this package otherwise registers
+     * nothing at all.
+     *
+     * Requires an {@link authorize} guard, and leaves data capture off unless you
+     * enable it per subsystem.
+     *
+     * @see {@link ProductionConfig}
+     *
+     * @example
+     * ```ts
+     * production: { enabled: true, capture: { queries: true } }
+     * ```
+     */
+    production?: ProductionConfig;
     /**
      * Advanced options for fine-tuning internal behavior.
      *
@@ -878,7 +981,7 @@ export interface ResolvedServerStatsConfig {
     /** Optional dev toolbar configuration. */
     devToolbar?: DevToolbarOptions;
     /** Optional access-control callback. */
-    shouldShow?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    shouldShow?: AccessGuard;
     /** Collection interval in milliseconds (new name for {@link intervalMs}). */
     pollInterval?: number;
     /** Whether real-time (SSE) broadcasting is enabled (new name for {@link transport}). */
@@ -886,7 +989,7 @@ export interface ResolvedServerStatsConfig {
     /** HTTP endpoint path or `false` to disable (new name for {@link endpoint}). */
     statsEndpoint?: string | false;
     /** Access-control callback (new name for {@link shouldShow}). */
-    authorize?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    authorize?: AccessGuard;
     /**
      * Escape hatch to register sensitive routes without an access guard.
      * Exposes the dashboard without auth — local development only.
@@ -902,4 +1005,6 @@ export interface ResolvedServerStatsConfig {
     verbose: boolean;
     /** Optional domain restriction for all routes. */
     domain?: string;
+    /** Opt-in production behavior. Absent means this package is inert in production. */
+    production?: ProductionConfig;
 }

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

@@ -26,6 +26,13 @@ export default class DashboardController {
     createSavedFilter(ctx: HttpContext): Promise<void>;
     deleteSavedFilter(ctx: HttpContext): Promise<void>;
     private withDb;
+    /**
+     * Re-check the access guard for the dashboard page itself.
+     *
+     * Awaited: an async guard would otherwise return a truthy promise and let
+     * everyone through. The route middleware already applies the same guard, so
+     * this is defense in depth for the HTML page.
+     */
     private checkAccess;
     private getDashboardPath;
 }

package/dist/src/dashboard/dashboard_controller.js

@@ -23,7 +23,7 @@ export default class DashboardController {
         this.pageAssets = new DashboardPageAssets();
     }
     async page(ctx) {
-        if (!this.checkAccess(ctx))
+        if (!(await this.checkAccess(ctx)))
             return ctx.response.forbidden({ error: 'Access denied' });
         const config = this.app.config.get('server_stats');
         const tc = config?.devToolbar ?? {};
@@ -163,12 +163,19 @@ export default class DashboardController {
             return response.json(emptyValue);
         }
     }
-    checkAccess(ctx) {
+    /**
+     * Re-check the access guard for the dashboard page itself.
+     *
+     * Awaited: an async guard would otherwise return a truthy promise and let
+     * everyone through. The route middleware already applies the same guard, so
+     * this is defense in depth for the HTML page.
+     */
+    async checkAccess(ctx) {
         const config = this.app.config.get('server_stats');
         if (!config?.shouldShow)
             return true;
         try {
-            return config.shouldShow(ctx);
+            return await config.shouldShow(ctx);
         }
         catch {
             return false;

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

@@ -1,4 +1,4 @@
-import type { DevToolbarConfig, EventRecord, EmailRecord } from '../debug/types.js';
+import type { DevToolbarConfig, EmailRecord } from '../debug/types.js';
 import type { StorageStatsResult } from './storage_stats.js';
 import type { Knex } from 'knex';
 export type { RequestInput, PersistRequestInput, RequestFilters, QueryFilters, EventFilters, EmailFilters, LogFilters, TraceFilters, PaginatedResult, PaginateOptions, } from './dashboard_types.js';
@@ -26,7 +26,6 @@ export declare class DashboardStore {
     isReady(): boolean;
     getStorageStats(): Promise<StorageStatsResult>;
     persistRequest(input: PersistRequestInput): Promise<number | null>;
-    queueEvents(requestIndex: number, events: EventRecord[]): void;
     recordLog(entry: Record<string, unknown>): void;
     recordEmail(record: EmailRecord): void;
     flushWriteQueue(): Promise<void>;

package/dist/src/dashboard/dashboard_store.js

@@ -139,9 +139,6 @@ export class DashboardStore {
         this.flushMgr.persistRequest(input, this.dashboardPath);
         return Promise.resolve(null);
     }
-    queueEvents(requestIndex, events) {
-        this.flushMgr.queueEvents(requestIndex, events);
-    }
     recordLog(entry) {
         this.flushMgr.recordLog(entry);
     }

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

@@ -16,6 +16,8 @@ export interface RequestInput {
 }
 export interface PersistRequestInput extends RequestInput {
     queries: import('../debug/types.js').QueryRecord[];
+    /** Events emitted since the previous request completed. */
+    events?: import('../debug/types.js').EventRecord[];
     trace: import('../debug/types.js').TraceRecord | null;
     httpRequestId?: string | null;
 }

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

@@ -1,12 +1,8 @@
-import type { EventRecord, EmailRecord } from '../debug/types.js';
+import type { EmailRecord } from '../debug/types.js';
 import type { PersistRequestInput } from './dashboard_types.js';
 import type { Knex } from 'knex';
 export declare class FlushManager {
     writeQueue: PersistRequestInput[];
-    pendingEvents: {
-        requestIndex: number;
-        events: EventRecord[];
-    }[];
     pendingLogs: Record<string, unknown>[];
     pendingEmails: EmailRecord[];
     private flushTimer;
@@ -15,7 +11,6 @@ export declare class FlushManager {
     private db;
     constructor(getDb: () => Knex | null);
     persistRequest(input: PersistRequestInput, dashboardPath: string): void;
-    queueEvents(requestIndex: number, events: EventRecord[]): void;
     recordLog(entry: Record<string, unknown>): void;
     recordEmail(record: EmailRecord): void;
     stop(): Promise<void>;

package/dist/src/dashboard/flush_manager.js

@@ -1,10 +1,9 @@
 import { log } from '../utils/logger.js';
-import { prepareRequestRows, prepareLogRows, flushRequests, flushEvents, flushEmails, flushLogs, hasWarned, markWarned, } from './write_queue.js';
+import { prepareRequestRows, prepareLogRows, flushRequests, flushEmails, flushLogs, hasWarned, markWarned, } from './write_queue.js';
 const FLUSH_MS = 500;
 const MAX_Q = 200;
 export class FlushManager {
     writeQueue = [];
-    pendingEvents = [];
     pendingLogs = [];
     pendingEmails = [];
     flushTimer = null;
@@ -21,10 +20,6 @@ export class FlushManager {
         this.writeQueue.push(input);
         this.scheduleFlush();
     }
-    queueEvents(requestIndex, events) {
-        if (events.length > 0)
-            this.pendingEvents.push({ requestIndex, events });
-    }
     recordLog(entry) {
         if (!this.db())
             return;
@@ -94,7 +89,6 @@ export class FlushManager {
             const pl = prepareLogRows(snap.logs);
             await db.transaction(async (trx) => {
                 await flushRequests(trx, pr);
-                await flushEvents(trx, snap.events);
                 await flushEmails(trx, snap.emails);
                 await flushLogs(trx, pl);
             });
@@ -115,10 +109,9 @@ export class FlushManager {
     takeSnapshot() {
         const requests = this.writeQueue.splice(0);
         const logs = this.pendingLogs.splice(0);
-        const events = this.pendingEvents.splice(0);
         const emails = this.pendingEmails.splice(0);
-        if (requests.length === 0 && logs.length === 0 && events.length === 0 && emails.length === 0)
+        if (requests.length === 0 && logs.length === 0 && emails.length === 0)
             return null;
-        return { requests, logs, events, emails };
+        return { requests, logs, emails };
     }
 }

package/dist/src/dashboard/integrations/config_inspector.js

@@ -1,48 +1,9 @@
+import { isSensitiveConfigName, looksLikeCredentialValue } from '../sensitive_patterns.js';
 // ---------------------------------------------------------------------------
-// Sensitive key patterns
+// Sensitive key detection
 // ---------------------------------------------------------------------------
-/**
- * Patterns matched against key names (case-insensitive) to detect secrets.
- *
- * Uses `(?:^|[_.-])` and `(?:$|[_.-])` as boundaries instead of `\b`
- * because env vars use `_` as separators and `_` is a word character
- * in regex, so `\b` won't match between `CLIENT` and `SECRET` in
- * `GOOGLE_CLIENT_SECRET`.
- */
-const B = '(?:^|[_.\\-])'; // boundary before
-const A = '(?:$|[_.\\-])'; // boundary after
-const SENSITIVE_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,
-    // Email addresses in env var names
-    new RegExp(`${B}email${A}`, 'i'),
-    new RegExp(`${B}smtp${A}`, 'i'),
-    // Database/service URLs (often contain embedded credentials)
-    /database[_-]?url/i,
-    /redis[_-]?url/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,
-];
+// The name patterns live in `../sensitive_patterns.js` so the config inspector
+// and the SQL-binding writer share one definition of "looks like a secret".
 const REDACTED_DISPLAY = '••••••••';
 function redact(_value) {
     // Never include the plaintext value: the redacted object is serialized
@@ -121,20 +82,19 @@ export class ConfigInspector {
  * Check if a key name matches any sensitive pattern.
  */
 function isSensitiveKey(key) {
-    return SENSITIVE_PATTERNS.some((pattern) => pattern.test(key));
+    return isSensitiveConfigName(key);
 }
 /**
  * Check if a value looks sensitive based on its content.
  * Catches email addresses and URLs with embedded credentials.
  */
 function isSensitiveValue(value) {
-    // Email addresses
+    // Email addresses are config-sensitive (SMTP accounts) even though they are
+    // ordinary data as a query binding — hence the check lives here, not in the
+    // shared shape helper.
     if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
         return true;
-    // URLs with userinfo (credentials embedded in URL)
-    if (/^[a-z][a-z0-9+.-]*:\/\/[^/]*:[^/]*@/i.test(value))
-        return true;
-    return false;
+    return looksLikeCredentialValue(value);
 }
 /** Sanitize a single key-value pair, redacting sensitive strings. */
 function sanitizeValue(key, value, seen) {

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

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+/**
+ * Names that identify a credential — applies to env vars, config keys, and SQL
+ * identifiers alike.
+ */
+export declare const SECRET_NAME_PATTERNS: RegExp[];
+/**
+ * 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 declare const CONFIG_ONLY_NAME_PATTERNS: RegExp[];
+/** Whether a name identifies a credential. */
+export declare function isSecretName(name: string): boolean;
+/** Whether a name is sensitive in a config/env context (credentials plus contact/service names). */
+export declare function isSensitiveConfigName(name: string): boolean;
+/**
+ * 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 declare function sqlMentionsSecret(sql: string): boolean;
+export declare function looksLikeCredentialValue(value: string): boolean;