Migration and Hotfix

Migration: opt-in and opt-out

Before the default flip — opt in

While admin.enabled defaults to false, the admin is off unless you turn it on. To enable it, set both an enable flag and a token (and run a Standard- or Pro-edition binary):

admin:
  enabled: true
  token: "your-secret-admin-token-min-32-bytes"

After the default flip — opt out

A later release flips the default for admin.enabled to true once the full accessibility and polish pass lands. After that, on a Standard/Pro binary the admin mounts by default. To keep it off, set the flag explicitly:

admin:
  enabled: false

With admin.enabled: false, /_admin/* routes are never mounted regardless of license.

Upgrading from a pre-admin binary

When you upgrade from a binary that predates the admin shell:

  • The /_admin/* routes now exist on Standard/Pro builds. Whether they respond depends on the three gates from the admin overview (admin feature compiled in, a Core+/Standard/Pro license loaded, and admin.enabled).
  • You must set an admin token (via admin.token or ACCENT_ADMIN_TOKEN) before anyone can sign in. Without a token there is no way through the login flow.
  • No content changes happen as a result of upgrading. The admin reads through the same content surface as the public site; nothing is rewritten until an operator signs in and actually edits, moves, deletes, or uploads. Until then the shell is purely a viewer.

Hotfix overlay for baked-in assets

The admin shell loads Alpine.js and HTMX from copies baked into the binary. When an upstream security advisory lands for one of them, you do not have to wait for a new Accent release or rebuild from source: point Accent at a hotfix overlay directory and drop the patched file in.

hotfix:
  overlay_dir: ./hotfix     # relative to config.yaml; absent = no overrides (default)
  on_unknown: warn          # warn (default) | reject -- policy for stray overlay files

Lay the overlay out to mirror the embedded asset tree, and only the allowlisted third-party libraries are overridable (never Accent’s own admin code):

hotfix/
└── _admin/static/vendor/
    ├── alpine.min.js     # overrides the embedded Alpine.js
    └── htmx.min.js       # overrides the embedded HTMX

A file placed there is served in place of the embedded copy on the next request — no restart. Overlay responses carry a content ETag and Cache-Control: no-cache, so a swapped file reaches returning browsers immediately rather than after the embedded path’s day-long cache expires.

Inspect, apply, and revert overlays with the CLI:

accent hotfix list      # overridable assets, embedded version, active/blocked overlay
accent hotfix verify    # re-run the boot checks; non-zero exit on a reject-class problem (CI-friendly)

# Apply a patched upstream file (the version marker is verified before it is installed)
accent hotfix apply alpine.min.js ./alpine-3.15.13.min.js --advisory https://github.com/alpinejs/alpine/security/advisories/GHSA-...

# Revert to the embedded copy
accent hotfix remove alpine.min.js

apply refuses a file with no version:"x.y.z" marker or a path that is not on the allowlist, copies it into the overlay tree, and records provenance in hotfix.yaml (see below). After apply/remove, send SIGHUP (pkill -HUP accent) or restart so the boot audit line and the admin chip refresh.

Provenance manifest (hotfix.yaml)

apply maintains an optional hotfix.yaml at the overlay root that records why each override exists and the SHA-256 Accent verifies on boot:

overrides:
  - asset: _admin/static/vendor/alpine.min.js
    version: "3.15.13"
    sha256: "ab12cd..."        # verified against the file on every boot/reload
    advisory: "https://github.com/alpinejs/alpine/security/advisories/GHSA-..."
    applied: "2026-06-06"
    note: "Bridge until Accent re-vendors."

If a file’s bytes do not match its declared sha256 — a partial write or tampering — Accent refuses to serve it (falling through to the trusted embedded copy) and logs a WARN; accent hotfix list shows it as BLOCKED. The manifest is optional, but writing one (or letting apply write it) gives you integrity verification and an audit trail.

On startup (and on SIGHUP/reload) Accent logs one WARN line per active override, detects an overlay that is byte-identical to the embedded copy (so you know the binary has caught up and the overlay can be removed), and warns if the overlay files are group/world-writable. While any override is active, the admin top bar shows a “Hotfix active” chip so the unusual state is visible on every screen, not just in the logs.

Security: overriding the JavaScript the admin loads is, by design, arbitrary code execution in the admin origin. Treat write access to overlay_dir as the same trust level as the accent binary itself: keep it owned by the server user, 0755/0644, and never inside a content directory an untrusted author can write to. The overlay is a temporary bridge until an Accent release re-vendors the patched library — remove it afterwards.