Demonstration Mode Guide

Common

Demonstration Mode is an application-wide write-admission policy for shared demonstration deployments. It is provided by the first-party a-demo suite and uses a global Vona Guard to prevent ordinary visitors from changing demo data.

It is disabled by default. When enabled, it protects selected HTTP write methods while leaving the rest of the application's authentication and authorization policies in force.

What Demonstration Mode does—and does not do

Demonstration Mode is a safety rail for demo data. It is not a replacement for:

• Passport authentication
• RBAC or domain-specific authorization
• validation and business rules
• WAF, reverse-proxy, or network controls
• database and other data-access safeguards

Approval by this Guard only lets the request continue to the normal request pipeline; it does not grant the caller any additional permission.

The policy applies to HTTP requests only. It does not protect side-effecting GET handlers, background jobs, scheduled work, queues, CLI execution, or other non-HTTP code. Model state-changing HTTP APIs with the protected write methods and retain their ordinary authorization rules.

Enable Demonstration Mode

Configure the backend environment and restart Vona:

DEMONSTRATION_ENABLED=true
DEMONSTRATION_USERNAME_WHITELIST=admin,demo-editor

DEMONSTRATION_ENABLED enables the Guard only when its value is the exact lowercase string true. An unset value, an empty value, TRUE, True, and 1 all leave Demonstration Mode disabled.

Use Runtime and Flavors to select the active environment files and understand precedence. In a local backend setup, an uncommitted vona/env/.env.local is a typical place for local overrides. Deployment-injected environment values may also take precedence. For the broader configuration model, see the Config Guide.

Environment values are evaluated while the backend initializes. Restart Vona after changing either Demonstration Mode variable.

Configure exempt writers

DEMONSTRATION_USERNAME_WHITELIST is a comma-separated list of usernames that may perform protected writes:

DEMONSTRATION_USERNAME_WHITELIST=admin, demo-editor, content-manager

The list is normalized as follows:

• surrounding whitespace is removed from each entry
• empty entries are discarded
• repeated entries are deduplicated
• usernames match entries exactly and case-sensitively

Whitelist membership is necessary but not sufficient. A protected write is admitted only when the current user is all of the following:

• authenticated
• account-active
• non-anonymous
• present in the username whitelist

If the whitelist is absent or empty while Demonstration Mode is enabled, no user qualifies for protected writes.

Request behavior

The Guard protects these HTTP methods:

• POST
• PATCH
• DELETE
• PUT

Other methods pass through this Guard unchanged. A protected request is allowed only for an eligible whitelisted user. All other protected requests are rejected with:

Field	Value
HTTP status	403 Forbidden
Application error code	demo-demonstration:1001
Meaning	The operation is forbidden in demonstration mode.

The Guard depends on Passport-resolved account state, so it makes this decision only after the current account information is available. Passing the Demonstration Mode check does not bypass later Passport, RBAC, or business-policy checks.

Exempt authentication routes

Demonstration Mode deliberately does not apply to the standard authentication and OAuth routes below. This keeps sign-in, sign-out, registration, account association and migration, OAuth callbacks, and token flows available while the write policy is active.

/home/user/passport/logout
/home/user/passport/register
/home/user/passport/login
/home/user/passport/login/:module/:providerName/:clientName?
/home/user/passport/associate/:module/:providerName/:clientName?
/home/user/passport/migrate/:module/:providerName/:clientName?
/home/user/passport/refreshAuthToken
/home/user/passport/createPassportJwtFromOauthCode
/home/user/passport/createTempAuthToken
/auth/passport/callback

These are route templates used by the built-in authentication flows. They are not a general mechanism for bypassing Demonstration Mode on arbitrary URLs.

Deploy with the a-demo suite

The demo-demonstration module is included in the current project's a-demo suite; no separate package installation is required.

If an operator intentionally excludes the whole suite:

PROJECT_DISABLED_SUITES=a-demo

then demo-demonstration and its Guard are not loaded, regardless of DEMONSTRATION_ENABLED or the whitelist. This is expected when a deployment does not include demo capabilities.

For ordinary policy changes, use DEMONSTRATION_ENABLED rather than disabling the suite. Reserve PROJECT_DISABLED_SUITES=a-demo for deployments that intentionally exclude all a-demo functionality.

Troubleshooting

Symptom	Check
The policy appears inactive	Confirm DEMONSTRATION_ENABLED=true uses exact lowercase spelling, then restart Vona and check active environment-file and deployment-variable precedence.
An intended demo editor receives 403	Confirm that the user is authenticated, active, non-anonymous, and that their username exactly matches a whitelist entry, including case.
A request is unexpectedly allowed	Confirm whether it uses a method other than POST, PATCH, DELETE, or PUT, or whether it belongs to an exempt built-in authentication route.
The policy never loads	Confirm that a-demo is not listed in PROJECT_DISABLED_SUITES.
A non-HTTP mutation still runs	Demonstration Mode only guards applicable HTTP requests; add the appropriate authorization and execution controls to the relevant job, queue, CLI, or service path.

Related guides

• Runtime and Flavors
• Config Guide
• Controller AOP Guide
• Auth Guide
• User Access Guide