velocious 1.0.600 → 1.0.601

package/README.md

@@ -775,22 +775,20 @@ Use `await FrontendModelBase.waitForIdle()` when a test harness or app lifecycle
 
 Frontend-model HTTP requests always use `credentials: "include"` so shared custom commands can set session cookies without app-level transport overrides.
 
-Unexpected frontend-model endpoint failures return their original message by default with `errorType: "internal_error"` and a server-generated `correlationId` shared with the matching framework-error report. Set `secureFrontendModelErrors: true` to return only explicitly safe messages and otherwise `errorMessage: "Request failed."`. Expected application failures can use `VelociousError.safe(message, {errorType, details, code})`; generated frontend-model callers preserve the server's safe error fields. See [docs/frontend-models.md](docs/frontend-models.md#error-payloads).
+Unexpected frontend-model endpoint failures return their original message and full stack trace by default in every environment, including production. Responses use `errorType: "internal_error"`, a server-generated `correlationId` shared with the matching framework-error report, and the established `debugErrorClass`, `debugErrorMessage`, and `debugBacktrace` fields. Expected application failures can use `VelociousError.safe(message, {errorType, details, code})`; generated frontend-model callers preserve the server's safe error fields without adding irrelevant debug fields. See [docs/frontend-models.md](docs/frontend-models.md#error-payloads).
 Invalid client query descriptors, such as unknown `select`, `where`, `search`, `joins`, `preload`, `group`, `sort`, `pluck`, or Ransack attributes, return the specific frontend-model query error message with `velocious.code: "frontend-model-query-error"` and are not emitted as framework errors.
 Invalid frontend-model write attributes and attachment names, including attributes rejected by `permittedParams()`, return the specific safe error message with `velocious.code: "frontend-model-attribute-error"` and are not emitted as framework errors.
-In `development` and `test`, Velocious also includes `debugErrorClass`, `debugErrorMessage`, and `debugBacktrace` fields so browser/system-test failures are easier to diagnose without exposing those details in production.
-Other non-production environments, such as `staging`, keep the same client-safe default unless you explicitly opt in with `exposeInternalErrorsToClients: true`:
+To mask unexpected internal details, explicitly opt out for the application configuration:
 
 ```js
 const configuration = new Configuration({
-  environment: "staging",
-  exposeInternalErrorsToClients: true
+  exposeInternalErrorsToClients: false
 })
 ```
 
-This opt-in is ignored in `production`; production frontend-model responses never include internal exception details.
+With this opt-out, built-in commands, custom commands, and sync replay failures return `errorMessage: "Request failed."` and omit the debug message and stack fields in every environment. `secureFrontendModelErrors: true` remains a deprecated compatibility alias when `exposeInternalErrorsToClients` is omitted; an explicit `exposeInternalErrorsToClients` value always wins.
 
-Backends can append client-safe metadata to frontend-model error responses with `configuration.addClientErrorPayloadReporter(...)`. Reporters receive the caught `error`, the current `request`, a safe `requestDetails` snapshot, and a small `context` object, and should only return fields that are safe for clients to see. Frontend-model endpoint failures include `context.frontendModelEndpoint`, `action`, `commandType`, `model`, `requestId`, and `expectedError`. This is useful for attaching an error-reporting URL while keeping the normal production error message generic:
+Backends can append client-safe metadata to frontend-model error responses with `configuration.addClientErrorPayloadReporter(...)`. Reporters receive the caught `error`, the current `request`, a safe `requestDetails` snapshot, and a small `context` object, and should only return fields that are safe for clients to see. Frontend-model endpoint failures include `context.frontendModelEndpoint`, `action`, `commandType`, `model`, `requestId`, and `expectedError`. When exposure is disabled, Velocious strips the established debug fields even if a reporter supplies them. This is useful for attaching an error-reporting URL while keeping an opted-out error message generic:
 
 ```js
 configuration.addClientErrorPayloadReporter(async ({error, requestDetails, context}) => {
@@ -1919,7 +1917,7 @@ configuration.getErrorEvents().on("all-error", ({error, errorType}) => {
 })
 ```
 
-Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return an `internal_error` response with the original message by default (or `Request failed.` when `secureFrontendModelErrors` is enabled) and a correlation ID, then emits them as `framework-error`/`all-error` with the same correlation ID and `context.frontendModelEndpoint === true`. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`), invalid client query descriptors are returned as frontend-model query errors, and `error.velocious`-annotated / `safeToExpose` errors keep their expected-error status. A raw `errorType` property alone is not considered safe and does not suppress reporting.
+Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return an `internal_error` response with the original message and stack trace by default (or `Request failed.` without debug fields when `exposeInternalErrorsToClients: false`) and a correlation ID, then emits them as `framework-error`/`all-error` with the same correlation ID and `context.frontendModelEndpoint === true`. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`), invalid client query descriptors are returned as frontend-model query errors, and `error.velocious`-annotated / `safeToExpose` errors keep their expected-error status without irrelevant debug fields. A raw `errorType` property alone is not considered safe and does not suppress reporting.
 
 Unexpected inbound decoded WebSocket dispatch failures emit one `framework-error` and one matching `all-error`. Established expected client-flow errors remain excluded from both events.
 

package/build/configuration-types.js

@@ -697,9 +697,9 @@
  * @property {boolean} [enforceTenantDatabaseScopes] - Require tenant-switched model queries to resolve a tenant database identifier. Defaults to true.
  * @property {string} [environment] - Current environment name.
  * @property {import("./environment-handlers/base.js").default} environmentHandler - Environment handler instance.
- * @property {boolean} [exposeInternalErrorsToClients] - Return unexpected internal error details in client API payloads outside production. Defaults to false.
+ * @property {boolean} [exposeInternalErrorsToClients] - Return unexpected internal error messages and stack traces in frontend-model client payloads in every environment. Defaults to true.
  * @property {{maxOpenHandles?: number}} [frontendTenantSqlite] - Bounded frontend tenant SQLite lifecycle configuration.
- * @property {boolean} [secureFrontendModelErrors] - Return only explicitly safe frontend-model error messages to clients. Defaults to false.
+ * @property {boolean} [secureFrontendModelErrors] - Deprecated compatibility alias for `exposeInternalErrorsToClients: false` when the authoritative option is omitted.
  * @property {HttpServerConfiguration} [httpServer] - Default HTTP server configuration for applications started from this configuration.
  * @property {LoggingConfiguration} [logging] - Logging configuration.
  * @property {BackgroundJobsConfiguration} [backgroundJobs] - Background jobs configuration.

package/build/configuration.js

@@ -236,7 +236,7 @@ export default class VelociousConfiguration {
    * Runs constructor.
    * @param {import("./configuration-types.js").ConfigurationArgsType} args - Configuration arguments.
    */
-  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients = false, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors = false, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
+  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
@@ -283,8 +283,9 @@ export default class VelociousConfiguration {
     this._environment = environment || globalThis.process?.env.VELOCIOUS_ENV || globalThis.process?.env.NODE_ENV || "development"
     this._environmentHandler = environmentHandler
     this._enforceTenantDatabaseScopes = enforceTenantDatabaseScopes
-    this._exposeInternalErrorsToClients = exposeInternalErrorsToClients
-    this._secureFrontendModelErrors = secureFrontendModelErrors
+    this._exposeInternalErrorsToClients = exposeInternalErrorsToClients === undefined
+      ? secureFrontendModelErrors !== true
+      : exposeInternalErrorsToClients
     this._directory = directory
     this._initializeModels = initializeModels
     /** @type {VelociousPackage[]} */
@@ -461,9 +462,10 @@ export default class VelociousConfiguration {
 
   /**
    * Returns whether frontend-model errors expose only explicitly safe messages.
-   * @returns {boolean} Whether frontend-model errors expose only explicitly safe messages.
+   * @deprecated Use `getExposeInternalErrorsToClients()`.
+   * @returns {boolean} Whether frontend-model internal error exposure is disabled.
    */
-  getSecureFrontendModelErrors() { return this._secureFrontendModelErrors === true }
+  getSecureFrontendModelErrors() { return !this.getExposeInternalErrorsToClients() }
 
   /**
    * Runs get debug endpoint.

package/build/frontend-model-controller.js

@@ -175,7 +175,6 @@ const frontendModelJoinedPathsSymbol = Symbol("frontendModelJoinedPaths")
 const frontendModelGroupedColumnsSymbol = Symbol("frontendModelGroupedColumns")
 const frontendModelWhereNoMatchSymbol = Symbol("frontendModelWhereNoMatch")
 const frontendModelClientSafeErrorMessage = "Request failed."
-const frontendModelDebugErrorEnvironments = new Set(["development", "test"])
 
 /**
  * Builds a client-safe sync replay validation error.
@@ -277,10 +276,10 @@ function frontendModelVelociousMetadataForError(error) {
 /**
  * Runs frontend model client message for error.
  * @param {unknown} error - Caught error.
- * @param {boolean} forwardUnexpectedErrorMessage - Whether unexpected error messages may be exposed.
+ * @param {boolean} exposeInternalErrorsToClients - Whether unexpected error messages may be exposed.
  * @returns {string} - Message safe to return to API clients.
  */
-function frontendModelClientMessageForError(error, forwardUnexpectedErrorMessage) {
+function frontendModelClientMessageForError(error, exposeInternalErrorsToClients) {
   if (error instanceof RecordNotFoundError) {
     return "Record not found."
   }
@@ -301,7 +300,7 @@ function frontendModelClientMessageForError(error, forwardUnexpectedErrorMessage
     return error.message
   }
 
-  if (forwardUnexpectedErrorMessage && error instanceof Error) return error.message
+  if (exposeInternalErrorsToClients && error instanceof Error) return error.message
 
   return frontendModelClientSafeErrorMessage
 }
@@ -310,14 +309,11 @@ function frontendModelClientMessageForError(error, forwardUnexpectedErrorMessage
  * Runs frontend model debug payload for error.
  * @param {object} args - Arguments.
  * @param {import("./configuration.js").default} args.configuration - Current configuration.
- * @param {string} args.environment - Current environment.
  * @param {unknown} args.error - Caught error.
- * @returns {import("./configuration-types.js").ClientErrorPayloadReporterPayload} - Optional debug payload for non-production environments.
+ * @returns {import("./configuration-types.js").ClientErrorPayloadReporterPayload} - Optional internal error details when client exposure is enabled.
  */
-function frontendModelDebugPayloadForError({configuration, environment, error}) {
-  const debugAllowed = frontendModelDebugErrorEnvironments.has(environment) || environment !== "production" && configuration.getExposeInternalErrorsToClients()
-
-  if (!debugAllowed) {
+function frontendModelDebugPayloadForError({configuration, error}) {
+  if (!configuration.getExposeInternalErrorsToClients()) {
     return {}
   }
 
@@ -3259,10 +3255,9 @@ export default class FrontendModelController extends Controller {
    * Runs frontend model client error payload for error.
    * @param {unknown} error - Caught error.
    * @param {FrontendModelEndpointErrorContext | undefined} [endpointErrorContext] - Frontend-model endpoint error context.
-   * @param {{forwardUnexpectedErrorMessage?: boolean}} [options] - Client error rendering options.
    * @returns {Promise<import("./configuration-types.js").ClientErrorPayloadReporterPayload>} - Client payload for the current environment.
    */
-  async frontendModelClientErrorPayloadForError(error, endpointErrorContext, {forwardUnexpectedErrorMessage = false} = {}) {
+  async frontendModelClientErrorPayloadForError(error, endpointErrorContext) {
     const velociousMetadata = frontendModelVelociousMetadataForError(error)
     const normalizedError = error instanceof Error ? error : new Error(String(error))
     /** @type {import("./configuration-types.js").ClientErrorPayloadReporterPayload} */
@@ -3312,15 +3307,20 @@ export default class FrontendModelController extends Controller {
       request: this.getRequest()
     })
 
+    if (!this.getConfiguration().getExposeInternalErrorsToClients()) {
+      delete reporterPayload.debugBacktrace
+      delete reporterPayload.debugErrorClass
+      delete reporterPayload.debugErrorMessage
+    }
+
     return {
       ...reporterPayload,
       ...this.frontendModelErrorPayload(frontendModelClientMessageForError(
         error,
-        forwardUnexpectedErrorMessage && !this.getConfiguration().getSecureFrontendModelErrors()
+        this.getConfiguration().getExposeInternalErrorsToClients()
       )),
       ...frontendModelDebugPayloadForError({
         configuration: this.getConfiguration(),
-        environment: this.getConfiguration().getEnvironment(),
         error
       }),
       ...(velociousMetadata ? {velocious: velociousMetadata} : {}),
@@ -4397,9 +4397,7 @@ export default class FrontendModelController extends Controller {
 
         responses.push({
           requestId,
-          response: await this.frontendModelClientErrorPayloadForError(error, errorContext, {
-            forwardUnexpectedErrorMessage: !isBuiltInCommand
-          })
+          response: await this.frontendModelClientErrorPayloadForError(error, errorContext)
         })
       }
     }
@@ -4623,9 +4621,7 @@ export default class FrontendModelController extends Controller {
       await this.frontendModelLogEndpointError({error, errorContext})
 
       await this.render({
-        json: /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (serializeFrontendModelTransportValue(await this.frontendModelClientErrorPayloadForError(error, errorContext, {
-          forwardUnexpectedErrorMessage: true
-        }), this.transportSerializationOptions()))
+        json: /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (serializeFrontendModelTransportValue(await this.frontendModelClientErrorPayloadForError(error, errorContext), this.transportSerializationOptions()))
       })
     }
   }

package/build/src/configuration-types.d.ts

@@ -1512,7 +1512,7 @@ export type ConfigurationArgsType = {
      */
     environmentHandler: import("./environment-handlers/base.js").default;
     /**
-     * - Return unexpected internal error details in client API payloads outside production. Defaults to false.
+     * - Return unexpected internal error messages and stack traces in frontend-model client payloads in every environment. Defaults to true.
      */
     exposeInternalErrorsToClients?: boolean;
     /**
@@ -1522,7 +1522,7 @@ export type ConfigurationArgsType = {
         maxOpenHandles?: number;
     };
     /**
-     * - Return only explicitly safe frontend-model error messages to clients. Defaults to false.
+     * - Deprecated compatibility alias for `exposeInternalErrorsToClients: false` when the authoritative option is omitted.
      */
     secureFrontendModelErrors?: boolean;
     /**
@@ -2247,9 +2247,9 @@ export type ConfigurationArgsType = {
  * @property {boolean} [enforceTenantDatabaseScopes] - Require tenant-switched model queries to resolve a tenant database identifier. Defaults to true.
  * @property {string} [environment] - Current environment name.
  * @property {import("./environment-handlers/base.js").default} environmentHandler - Environment handler instance.
- * @property {boolean} [exposeInternalErrorsToClients] - Return unexpected internal error details in client API payloads outside production. Defaults to false.
+ * @property {boolean} [exposeInternalErrorsToClients] - Return unexpected internal error messages and stack traces in frontend-model client payloads in every environment. Defaults to true.
  * @property {{maxOpenHandles?: number}} [frontendTenantSqlite] - Bounded frontend tenant SQLite lifecycle configuration.
- * @property {boolean} [secureFrontendModelErrors] - Return only explicitly safe frontend-model error messages to clients. Defaults to false.
+ * @property {boolean} [secureFrontendModelErrors] - Deprecated compatibility alias for `exposeInternalErrorsToClients: false` when the authoritative option is omitted.
  * @property {HttpServerConfiguration} [httpServer] - Default HTTP server configuration for applications started from this configuration.
  * @property {LoggingConfiguration} [logging] - Logging configuration.
  * @property {BackgroundJobsConfiguration} [backgroundJobs] - Background jobs configuration.