novaconium/novaconium/ISSUES.md

Backlog & Roadmap

Official issue tracker: https://git.4lt.ca/4lt/novaconium/issues — bug reports and feature requests are filed and discussed there, not here.

This file is the roadmap that sits above the tracker: a curated, lower-noise list of what's planned, in progress, or decided against, used to triage and clean up the tracker (grouping related issues, deciding priority/sequencing, deciding what's not going to happen) rather than to replace it. An entry here should generally reference the tracker issue(s) it corresponds to once one exists; an entry can also exist here before any tracker issue is filed, for things that are still just an idea.

How to use this file

• Add new items to Backlog using the template below. Don't build anything the moment it's added — Backlog is "known, not yet started."
• Link the tracker issue once one is filed (Issue: line). Not every Backlog entry needs one yet — file the tracker issue when it's ready to be actionable/discussed, not necessarily when the idea is first written down here.
• When work begins, move the item to In Progress.
• When shipped, move it to Done and add a Shipped: line with the date and, once committed, the commit/PR reference. Keep a Done entry only as long as it's referenced by (a Depends on:, or otherwise relevant context for) something still in Backlog/In Progress — once nothing active points back to it, delete it rather than letting this file grow without bound. This is a change from the file's earlier "never delete" policy; if a stale Done entry's history is ever needed again, it's in git history / the linked tracker issue.
• If something is decided against, move it to Won't Do with a Reason: line rather than deleting it — the "why not" is worth keeping. Close the corresponding tracker issue with a link back to that entry.
• Keep entries terse. This file is a map, not a design doc — link out to /admin/docs/design-notes, the tracker issue, or a future docs/ note for anything long enough to need one.

Entry template

### <Short title>

- **Type:** Feature | Bug
- **Status:** Backlog | In Progress | Done | Won't Do
- **Priority:** Low | Medium | High
- **Added:** YYYY-MM-DD
- **Depends on:** <other entry title(s)> — omit if none
- **Issue:** https://git.4lt.ca/4lt/novaconium/issues/N — once filed
- **Shipped:** YYYY-MM-DD (commit/PR ref) — only once Done

<1-3 sentence description: what and why. For bugs, include repro steps and
expected vs. actual behavior. For features, include the motivating use case.>

---

Backlog

Suggested build order (foundations first):

1. In-house comments — admin login & user management (Done 2026-07-14) unblocked this; comments are tied to real user accounts, not anonymous.
2. Ecommerce functionality — its dependencies (SQLite groundwork, session handling for the cart, admin login for order/product admin) are all done now.
3. Paywall functionality — needs everything Ecommerce needs, plus Ecommerce itself for the recurring-billing/payment-gateway plumbing; build after it rather than in parallel — also now has a concrete precedent to follow for the "gated content must skip the static cache" part of its design (see Draft pages (admin-only preview) in Done, and the caching/auth standing rule in AGENTS.md), which was still an open question when this entry was originally written.

Session handling (with flash sessions), Draft pages (admin-only preview), Admin login & user management, and Media/file manager all shipped (see Done) — 2026-07-14 for the first three, 2026-07-15 for Media/file manager.

See Won't Do below for 404 tracking, dropped in favor of Matomo.

In-house comments

• Type: Feature
• Status: Backlog
• Priority: Medium
• Depends on: Admin login & user management (Done), SQLite groundwork (Done)
• Added: 2026-07-14

A self-hosted comments library — no third-party service (Disqus, Commento, etc.) — a Lib\ class any sidecar can call to attach comments to any page, not just blog posts, the same way Lib\SpamGuard/ Lib\FormValidator are reusable across any form rather than hardcoded to the contact page. Comments tied to a real user account rather than anonymous name/email fields, which is why this rides on Admin login & user management rather than SQLite groundwork alone — needs that feature's user store to exist first. Likely a comments table (route/user/body/created_at/approved or similar — a migration under App/migrations/, following the two-root convention documented in /admin/docs/database) plus a small set of sidecar-callable methods (list comments for a route, submit one, moderate one). Needs a decision on moderation model (auto-approve vs. admin-approval queue, reusing the /admin/* auth gate for the moderation UI) and on spam handling (reuse Lib\SpamGuard's honeypot/timing approach rather than inventing a second mechanism, consistent with how CSRF protection already works — see /admin/docs/sidecars's "Form security" section for the existing input-cleaning/CSRF/spam-prevention layers a comment form should compose the same way the contact form does).

Ecommerce functionality

• Type: Feature
• Status: Backlog
• Priority: Low
• Depends on: SQLite groundwork (Done), Session handling (with flash sessions) (Done), Admin login & user management (Done)
• Added: 2026-07-12

Product catalog, cart, checkout, and order storage — a products / orders table in SQLite, a session-based cart (rides on the flash-session work above), and a payment gateway integration for actually taking money. Given the project's no-Composer/no-vendored-SDK philosophy, prefer calling a payment provider's HTTP API directly (e.g. Stripe's REST API via cURL) over vendoring a full SDK, same reasoning as vendoring only Twig's src/ rather than pulling in a package manager. Needs a decision on which provider(s) to support first. Order/product management rides on admin login above. Large feature — likely worth its own sub-breakdown (catalog, cart, checkout, order admin) once it's actually picked up rather than planning it all up front here.

Paywall functionality

• Type: Feature
• Status: Backlog
• Priority: Low
• Depends on: Ecommerce functionality (recurring billing/payment plumbing), SQLite groundwork (Done), Session handling (with flash sessions) (Done), Admin login & user management (Done)
• Added: 2026-07-12

Subscription/membership content gating, similar to OnlyFans/Patreon: recurring billing tied to a user account, content (posts, pages, media) marked as gated behind an active subscription, and access checks in sidecars ($_SESSION's logged-in user + subscription status) — the access-check half of this now has a shipped foundation to build on: Lib\Access (see User roles, groups & page access control in Done) already handles login-gated/group-gated sidecar content; a paywall mostly adds "does this account have an active subscription" as a rule source on top of it. Reuses Ecommerce's payment-gateway plumbing for the recurring-charge side rather than integrating a payment provider a second time — build after Ecommerce rather than in parallel. Also needs a decision on how gated content is authored (a gated: true flag in a sidecar's returned context vs. a separate content root) and what happens to cached pages once caching only applies to sidecar-less pages — gated pages will need a sidecar to check access, so they're never statically cached, which is consistent with the existing caching model but worth being explicit about up front.

In Progress

Nothing yet.

Done

Email verification for user accounts

• Type: Feature
• Status: Done
• Priority: Medium
• Depends on: Admin login & user management (Done)
• Added: 2026-07-14
• Shipped: 2026-07-15

Every user created after the first must click a 24-hour link (bin2hex(random_bytes(32)), same pattern as Lib\Csrf::token()) emailed to their address before AdminAuth::attempt() lets them log in at all — folded into the same generic pass/fail as a disabled account or a wrong password, no oracle revealing which. Two exemptions, both following the last-active-admin guard's reasoning that a safety mechanism can't depend on something that might not be configured: the very first user (auto-verified at creation, since there's no other admin to vouch for them, and they're auto-logged-in the same instant) and every row that predates this migration (novaconium/migrations/0003_add_users_verification.sql backfills verified_at from created_at). create-admin-user.php also auto- verifies, since lockout recovery can't depend on a working mail transport either.

/verify-email follows /admin/logout's GET-confirms/POST-mutates shape (the content-index crawl forces a GET on every route, and mail-security scanners prefetch links — either would burn a GET-mutates token); an invalid/expired/already-used token never touches the database either way. Changing an account's email at /admin/users resets verification and re-sends to the new address; /admin/users also grew a per-row Resend verification button, visible only when unverified.

Lib\Mailer grew a second method, sendMail(), for this and future transactional mail (password-reset-by-email later, per the original spec) — separate from send(), which the contact form keeps using unchanged. sendMail() is driver-dispatched via a new mail_driver config key: 'log' (default) reuses the same contact-log.txt fallback so a fresh checkout can create and verify accounts with zero external dependency; 'mailjet' sends through MailJet's Send API v3.1 (mailjet_api_key/ mailjet_api_secret/mail_from_email/mail_from_name in App/config.php — not gitignored, same as every other config key, per the user's decision that deployer-owned secrets are acceptable here). Adding another provider later means one more match case in sendMail() — callers never change. Documented in /admin/docs/admin-auth's new "Email verification" section.

Media/file manager

• Type: Feature
• Status: Done
• Priority: Medium
• Added: 2026-07-12
• Shipped: 2026-07-15

An upload/browse/delete UI for media (images, PDFs, etc.) at /admin/media so sidecars and Twig templates have a consistent place to reference uploaded files from — e.g. a blog post's header image — instead of authors manually copying files into public/. Covered by the existing /admin/* auth gate the moment the page was added, no extra wiring needed — as planned, there's no separate *_enabled flag (unlike admin auth/content index) since it has no SQLite dependency to gate. Backed by a plain directory, public/uploads/ (gitignored per-file with a tracked .gitkeep, same convention as data/), rather than a database — no metadata store (alt text, captions) yet; that's flagged as a natural SQLite fit if wanted later, not built now. Also removed the top-level images/ scaffolding directory/volume (reserved for a future image-upload feature, per the prior AGENTS.md wording): nothing had ever consumed it, and public/uploads/ now covers the use case it was held open for. Safety handling: an extension allowlist and max upload size, both configurable (media_upload_extensions/media_upload_max_bytes in App/config.php), plus filename sanitization (basename() + safe-charset reduction, collision-safe via a -1/-2/... suffix) and a realpath() re-check on delete to confirm the resolved path still lands inside public/uploads/ before unlinking. Documented at /admin/docs/media-manager (new topic, linked from the docs nav/index and the admin dashboard), with a matching README feature/docs-index entry.

User deletion & email addresses

• Type: Feature
• Status: Done
• Priority: Medium
• Depends on: Admin login & user management (Done)
• Added: 2026-07-14
• Shipped: 2026-07-14 (b882c30)

Second same-day follow-up to Admin login & user management (below), also pre-commit — so the email column went into the existing 0002_create_users.sql like the roles change before it. /admin/users gained a hard-delete action (username/email become reusable; any live session dies on its next request via the same per-request row re-check disabling uses; the last-active-admin guard covers delete as well as disable/demote) and a change-email action. Every account now requires a unique email address — validated and normalized (trim + lowercase) via the existing Lib\Validate::isEmail(), so uniqueness is case-insensitive by construction (verified: BOB@example.com collides with bob@example.com) — on the create form, the change-email action, and bin/create-admin-user.php (now <username> <email>). Not used for login or any mail yet; it exists so the planned email-verification flow (new Backlog entry above) has an address for every account that predates it. Delete stays deliberately distinct from disable in the UI (inside a confirm-style <details> with a warning): disable is keep-but-shut-out, delete is gone-for-good.

User roles, groups & page access control

• Type: Feature
• Status: Done
• Priority: Medium
• Depends on: Admin login & user management (Done)
• Added: 2026-07-14
• Shipped: 2026-07-14 (b882c30)

Follow-up to Admin login & user management (below), shipped the same day before any of it was committed — so the users schema change went into the existing 0002_create_users.sql rather than a third migration. Two roles (users.role): the first user created is 'admin', everyone after is 'registered' with an optional single group (users.user_group, a plain text label matched exactly — deliberately no groups table). /admin/* and draft preview are admin-only now — a logged-in registered user gets a plain 404 there (not a login redirect; they're authenticated, what they lack is the role) — and the last-active-user lockout guard became a last-active-admin guard, applied to both the disable and the new demote action (/admin/users also grew group-assignment and promote/demote).

Lib\Access (novaconium/lib/Access.php) is the sidecar-level content gate, per the "assign a page/section to a user or group" spec: Access::require('group:members', 'user:bob') at the top of a sidecar returns null or a ready-made Response (anonymous → login redirect carrying a ?return= path, validated against open redirects; wrong-account → 404, drafts' hide-don't-tease posture). No rules = any logged-in user; admins pass everything. Public is the default twice over: sidecars that never call it are untouched, and static (sidecar-less) pages can't call it — always public, which also means a gated page necessarily has a sidecar and is therefore never written to the static HTML cache: the caching/auth standing rule satisfied by construction, no bootstrap exclusion needed. Sections are gated by composition (a shared _access.php file require'd by each sidecar in the section), not per-directory config. Access::require() has no side effects on deny, so the content-index crawl (anonymous GET per sidecar) both drops gated pages from /search//sitemap.xml automatically and can't touch the visiting user's session. Verified end-to-end with three real accounts (admin / registered-with-group / registered-without) and a cookie jar each: rule matrix, return-path round trip, //evil.com-style return rejection, registered-user 404s on /admin/* and drafts, promote/demote + guards, group reassignment taking effect immediately, crawl exclusion, and flag-off zero-footprint posture. Documented at /admin/docs/access-control (new topic, linked from the docs nav/index), with supporting updates to admin-auth, drafts, sidecars, config, and libraries.

Admin login & user management

• Type: Feature
• Status: Done
• Priority: Medium
• Depends on: SQLite groundwork (Done), Session handling (with flash sessions) (Done)
• Added: 2026-07-12
• Shipped: 2026-07-14 (b882c30)

Shipped as specified: the single-user HTTP Basic Auth stopgap that gated /admin/* was replaced, not layered on — AdminAuth keeps its name and call sites (bootstrap.php's admin gate and draft gate) but is now a session login (Lib\Session, with a new Session::regenerate() against session fixation) against a users table (novaconium/migrations/0002_create_users.sql, the second framework-shipped migration) with password_hash()/password_verify() and no external auth library. The admin_username/admin_password_hash config keys and the /admin/password-hash page are gone, superseded by a single admin_auth_enabled flag (default false) plus new /admin/login, /admin/logout (a real page now — the pre-router special case in bootstrap.php is gone too — and POST-only with a GET confirm form, because the content-index crawl runs every sidecar as a GET and a logout-on-GET would have ended the crawling admin's own session the first time a lazy reindex rendered it), and /admin/users (create/disable/enable/change-password) pages, and a novaconium/bin/create-admin-user.php CLI (password via stdin, for deploy scripts and lockout recovery). Documented at /admin/docs/admin-auth.

Decisions worth recording: same zero-footprint posture as the content index (flag off → the three auth routes 404 and Lib\Db is never touched, so no data/novaconium.sqlite appears — the route sidecars self-load config the same way /search does); first-user bootstrap keeps the gate open only while the users table is empty (creating the first user at /admin/users auto-logs you in as it and closes the gate — running the CLI before enabling the flag avoids the window entirely); admin/login is the one /admin/* route exempted from requireLogin(), or its redirect would loop; disabling a user kills any live session on its next request (currentUser() re-checks the row per request), and disabling the last active user is refused since the empty-table window never reopens — that would be a permanent lockout. Login/user passwords read $_POST directly, extending the documented Lib\Input exact-value exception (verified with a password containing <> end-to-end). Verified route-by-route with real HTTP requests and a cookie jar: flag off (404s, no DB file), setup window, first-user auto-login, fresh-client redirect, wrong/right password, logout, enable/disable/change-password, live-session lockout on disable, last-user guard, CSRF failure paths, CLI creation, and draft gating via the session cookie (including confirming a pre-existing static-cache copy of a page still serves after the page is marked a draft until the cache is cleared — the documented cache-clear step, not a new bug).

Draft pages (admin-only preview)

• Type: Feature
• Status: Done
• Priority: Medium
• Added: 2026-07-13
• Shipped: 2026-07-14

Let a page under App/pages/ be written and previewed by an admin without being visible to the public — a config-driven list, draft_routes in App/config.php (Route::$dir-format entries, e.g. 'blog/upcoming-post'), checked in novaconium/bootstrap.php right alongside the existing /admin/* gate. Reuses AdminAuth::isAuthenticated() (a new method, extracted out of requireLogin() so the credential check could be reused with a different failure response) rather than a second auth mechanism: not authenticated → the same plain 404 an unmatched route gets (not a login prompt, so a draft's existence isn't revealed to anyone poking at the URL), authenticated → renders normally. No separate login flow needed — an admin authenticates once at /admin, and the browser then resends those same Basic Auth credentials to draft URLs automatically, since they're scoped to the whole origin/realm.

The gotcha flagged when this entry was written was designed around correctly: sidecar-less pages get written to the static HTML cache and served by .htaccess before PHP ever runs, so a draft without its own sidecar needed an explicit exclusion, not just the auth gate — Renderer::render() gained an $excludeFromCache param for this. A second, real instance of the same bug was found while testing this feature, pre-dating it entirely: /admin itself (novaconium/pages/admin/index.twig) has no sidecar, so it was already being written to the static cache — meaning once any admin visited /admin once, the admin panel was served to every subsequent visitor, unauthenticated, straight from public/cache/admin/, completely bypassing AdminAuth. Fixed in the same change by passing $excludeFromCache = true for every /admin/* route too, not just drafts. Documented as a standing rule in AGENTS.md (next to the mb_substr/|slice and |escape('js') notes) and at /admin/docs/drafts//admin/docs/caching: any future mechanism that conditionally hides page content from the public has to make the same check, not just gate the initial request.

Session handling (with flash sessions)

• Type: Feature
• Status: Done
• Priority: High
• Added: 2026-07-12
• Shipped: 2026-07-14

A Lib\ wrapper around PHP's native session handling (session_start(), $_SESSION, not a custom session store) — Lib\Session (novaconium/lib/Session.php), all-static and lazy-start, same shape as the already-shipped Lib\Csrf (which also touches the native session; the two coexist in the same request without conflict). Ships get()/set()/has()/remove() plus CodeIgniter-style flash data (flash()/getFlash()) — a value set now that's readable on exactly the next request, then gone, for post/redirect/GET flows like App/pages/contact/index.php's hand-rolled ?sent=1 (not refactored to use it in this change — cited in the original spec as the motivating example, not a mandate to touch working demo code). The flash mechanism is a single per-request swap (snapshot last request's flash bucket into an in-memory static on first touch, then clear the stored bucket so this request's flash() calls fill a fresh one for the request after), not a separate expiry/sweep pass — verified end-to-end across three real, separate HTTP requests sharing a cookie jar (not three calls in one PHP process), confirming a flashed value appears on exactly the next request and is gone on the one after. Foundational alongside SQLite groundwork — admin login (next up) depends on it for logged-in state. Documented at /admin/docs/session and in AGENTS.md next to the Lib\Csrf/Lib\Db sections.

SQLite groundwork

• Type: Feature
• Status: Done
• Priority: High
• Added: 2026-07-12
• Shipped: 2026-07-14

Laid the groundwork for optional SQLite storage: Lib\Db (novaconium/lib/Db.php) is a thin, no-ORM PDO wrapper (prepared statements only, no string-interpolation helper ever, per Lib\Input's existing documented security stance) so features that need persistence — 404 tracking (see Won't Do; superseded by Matomo before this shipped), admin login, blog tags, internal search, and anything future — have a common place to store data instead of ad hoc flat files. Data lives in a new top-level data/ directory — deliberately outside both public/ (would be web-accessible) and novaconium/ (gets wholesale-replaced by the "Updating the framework" workflow documented at /admin/docs/getting-started, so anything persisted there would be destroyed by the next update) — gitignored per-file, with a tracked .gitkeep. Designed driver-agnostic (no SQLite-only SQL in the mechanism itself) specifically so MySQL support wouldn't need a retrofit — see that entry below (shipped 2026-07-14) for the connection/config/migration API, which superseded the single-connection shape (db_driver/db_path/ db_migrations_dir config keys) this entry originally shipped with.

Won't Do

404 tracking

• Type: Feature
• Status: Won't Do
• Priority: Medium
• Added: 2026-07-12
• Reason: Matomo (see /admin/docs/matomo) already tracks 404 hits — Renderer::renderNotFound() sets is_404 => true and the tracking snippet tags the document title as 404/URL = <path>/From = <referrer> before trackPageView, so 404s are already filterable in Matomo under Behaviour → Page URLs. A separate in-app SQLite-backed 404 log would just duplicate what Matomo already captures, for no real benefit.

Originally proposed as: log requests that hit the 404 page (path, timestamp, referrer, user agent) into SQLite, similar to Joomla's 404 log, with an /admin page to view them.