diff --git a/AGENTS.md b/AGENTS.md index 068115d..03b3f09 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,35 +100,77 @@ site-identity string that shows up in a shared template (as opposed to a per-page override) should become a `config.php` key the same way, not stay hardcoded in the template. -`config['admin_username']` / `config['admin_password_hash']` (username -defaults to `'admin'`, password hash defaults to `''`) gate every -`/admin/*` route behind HTTP Basic Auth — this replaced the old -`docs_enabled` flag entirely (removed); a single gate over all of -`/admin/*` (docs included) made a docs-only toggle redundant. Unlike the -Twig-global pattern above, the gate itself is enforced in `bootstrap.php`, -before rendering: `AdminAuth::requireLogin(...)` -(`novaconium/src/AdminAuth.php`) is called once for any resolved route -whose path is `admin` or starts with `admin/`. **Any new admin page -dropped under `App/pages/admin/` or `novaconium/pages/admin/` is -automatically protected — no per-page wiring needed.** `bootstrap.php` -also special-cases the literal path `/admin/logout` *before* router -resolution — no page exists there — to call `AdminAuth::logout()`, which -always issues a fresh 401 so the browser drops its cached credentials -(there's no server-side session to invalidate). `Renderer` separately -exposes an `admin_auth_enabled` Twig global (true when a password hash is -set) so `admin/index.twig` can conditionally show the "Logout" link — this -is a derived display flag, not the enforcement mechanism itself, which -never depends on Twig. `novaconium/pages/admin/password-hash/` is a -built-in `password_hash()` form (no CLI needed) for generating -`admin_password_hash` — a normal admin page, so it's covered by the same -gate: reachable while no password is set yet (to generate the first -one), then protected like everything else under `/admin/*` afterward. It -computes and displays the hash per-request only; nothing is persisted or -logged. This is a single-user HTTP Basic Auth stopgap, not -the full multi-user system tracked in `novaconium/ISSUES.md` ("Admin login & user -management"); don't extend this class toward multi-user/session-based -auth — that's a separate, larger feature that -will replace it. +`config['admin_auth_enabled']` (default `false`) gates every `/admin/*` +route behind a session login against the `users` table on `Lib\Db`'s +default connection (`novaconium/migrations/0002_create_users.sql`) — the +multi-user system from `novaconium/ISSUES.md`'s "Admin login & user +management" entry, which **replaced** the old single-user HTTP Basic Auth +stopgap (the `admin_username`/`admin_password_hash` config keys and the +`/admin/password-hash` page are gone; that stopgap had itself replaced +the even older `docs_enabled` flag). Same off-by-default posture as +`content_index_enabled`, for the same reason: it depends on SQLite, so +when the flag is false, `/admin/*` is wide open, the three auth routes +(`/admin/login`, `/admin/logout`, `/admin/users`) 404 as if they didn't +exist, their sidecars check the flag (via the same self-loaded two-step +config read `/search` uses) *before* touching `Lib\Db`, and no +`data/novaconium.sqlite` is ever created by this feature — verified +end-to-end. **Two roles** (`users.role`): the **first user ever created +is `'admin'`; everyone created after is `'registered'`**, each with an +optional single group (`users.user_group`, a plain text label — no +groups table). Admins run the site: `/admin/*`, drafts, and every +`Lib\Access` rule passes for them. Registered users log in at the same +`/admin/login` and see whatever content `Lib\Access` (below) grants +their account or group — but `/admin/*` renders a plain 404 for them +(they're authenticated; what they lack is the role, so bouncing them to +the login form would be wrong). Unlike the Twig-global pattern above, +the gate itself is enforced in `bootstrap.php`, before rendering, in two +steps: `AdminAuth::requireLogin($config['admin_auth_enabled'])` +(`novaconium/src/AdminAuth.php`) redirects anyone not logged in, then +`AdminAuth::isAdmin(...)` 404s logged-in non-admins — for any resolved +route whose path is `admin` or starts with `admin/`, **except +`admin/login` itself, which must stay reachable logged-out or the +redirect to it would loop.** **Any new admin page dropped under +`App/pages/admin/` or `novaconium/pages/admin/` is automatically +protected — no per-page wiring needed.** Bootstrapping the first user: +while the `users` table is empty, the gate deliberately returns open +access so the first user (the admin) can be created at `/admin/users` +(which auto-logs its creator in, closing the gate), mirroring the old +"wide open until a password is configured" posture; +`novaconium/bin/create-admin-user.php` creates an admin from the CLI +instead (password via stdin), which lets a deploy create the user +*before* flipping the flag so the open window never exists — it's also +the lockout-recovery path (usage: ` `, password via +stdin). Every account has a **unique email address** (`users.email`), +stored normalized via `Lib\Validate::isEmail()` (trim + lowercase) so +the planned email-verification feature (see `novaconium/ISSUES.md` +Backlog) can match case-insensitively — not used for login (username) +or any mail yet. `/admin/users` is the management UI (create — always +`'registered'` except the first / disable / enable / delete / change +group / promote-demote / change email / change password); a disabled +**or deleted** user fails login and any existing session dies on its +next request (`currentUser()` re-checks the row per request), and +disabling, demoting, *or deleting* the last **active admin** is refused +— the empty-table setup window doesn't reopen once users exist, so that +would be a permanent lockout. Delete is a hard delete (username/email +become reusable); disable is the keep-but-shut-out option. `/admin/login` accepts a +`?return=` path (how `Lib\Access` sends someone back to the gated page +after login), validated to a local path (must start `/`, not `//`, no +`\`) so a crafted login link can't bounce a fresh login to another +site; with no return path, admins land on `/admin`, registered users on +`/`. Login +regenerates the session id (`Lib\Session::regenerate()`, added for this) +against session fixation; logout is a real page now — the pre-router +`/admin/logout` special case in `bootstrap.php` is gone — and it is +**POST-only with a GET confirm form** (same shape as +`/admin/clear-cache`), not logout-on-GET: the content-index crawl runs +every page's sidecar as a GET, so a GET side effect there would end the +crawling admin's own session mid-reindex. Passwords are read from `$_POST` directly, not +`Lib\Input` (the documented exact-value exception — see `Lib\Input`'s +doc-comment, which now points at the login/users sidecars). `Renderer` +still exposes the `admin_auth_enabled` Twig global (now mirroring the +config flag) so `admin/index.twig` can conditionally show the +"Admin users"/"Logout" links — a derived display flag, not the +enforcement mechanism itself, which never depends on Twig. `Lib\Db` (`novaconium/lib/Db.php`) is the SQLite/MySQL groundwork tracked in `novaconium/ISSUES.md` — a thin, no-ORM PDO wrapper, `Lib\` (not `App\`) @@ -256,19 +298,45 @@ check (paywall content is the next one on the roadmap likely to hit this) needs to make the same check here, not just at the point where the request is first authorized. -`AdminAuth::isAuthenticated(string $username, string $passwordHash): bool` -(`novaconium/src/AdminAuth.php`) is the credential check on its own, with -no response side effects, extracted out of `requireLogin()` (which still -does the same check, then issues the `401` challenge on failure) so a -different caller can react to failure differently. The draft-page gate in -`bootstrap.php` is the first such caller: on failure it renders a plain -404 via the same path an unmatched route takes, not a login prompt — -prompting for credentials at a draft URL would itself reveal that -something is gated there, which defeats the point of hiding it. Returns -`true` (open access) when `$passwordHash` is empty, mirroring -`requireLogin()`'s existing no-op-when-unset posture, so a draft behaves -consistently with the rest of `/admin/*`: wide open until a password is -configured, gated once one is. +`AdminAuth::isAdmin(bool $enabled): bool` / `::isLoggedIn(bool +$enabled): bool` (`novaconium/src/AdminAuth.php`) are the access checks +on their own, with no response side effects — `requireLogin()` is +`isLoggedIn()` plus a 303 redirect to `/admin/login` on failure, and a +different caller can react to failure differently. The draft-page gate +in `bootstrap.php` is the first such caller, and it uses `isAdmin()` +(drafts are admin-only — a logged-in registered user gets the same 404 +as an anonymous visitor): on failure it renders a plain 404 via the same +path an unmatched route takes, not a login redirect — bouncing to a +login at a draft URL would itself reveal that something is gated there, +which defeats the point of hiding it. Both return `true` (open access) +when `$enabled` is false or while the `users` table is empty, mirroring +`requireLogin()`'s posture, so a draft behaves consistently with the +rest of `/admin/*`: wide open until the feature is enabled and a first +user exists, gated after that. + +`Lib\Access` (`novaconium/lib/Access.php`) is the sidecar-level content +gate — how a page (or a section, one line per page; a shared +`_access.php` in the section directory is the documented pattern, since +non-`index.*` files are invisible to the router) is assigned to a user +or group: `Access::require('group:members', 'user:bob')` returns `null` +(allowed — no rules at all means any logged-in user, and **admins pass +every rule**) or a `Response` the sidecar returns as-is (anonymous → 303 +to `/admin/login?return=`; logged-in-but-not-allowed → plain-text +404, same hide-don't-tease posture as drafts). See +`/admin/docs/access-control`. **Public is the default, and static pages +are always public**: a page with no sidecar can't call `Access` — and +that's load-bearing, since only sidecar-less pages are written to the +static HTML cache; a gated page necessarily has a sidecar, so it can +never leak through the cache — the caching/auth standing rule below is +satisfied by construction, with no bootstrap exclusion needed. Same +open-until-configured / zero-DB-footprint posture as the rest of admin +auth when the flag is off or no users exist. Deliberately **no side +effects on deny** (the return path travels in the redirect URL, not the +session): the content-index crawl runs every sidecar as an anonymous +GET, so gated pages drop out of `/search`/`/sitemap.xml` automatically +(the crawler discards `Response`s) and a crawl must never scribble on +the visiting user's session — the same reasoning that made +`/admin/logout` POST-only. `App\ContentIndexer` (`novaconium/src/ContentIndexer.php`) is the shared crawler behind `/sitemap.xml`, `/search`, and blog tag browsing (see @@ -442,13 +510,15 @@ site behavior for the next person. query — use PDO prepared statements once a database layer exists); don't add an `sqlSafe()`-style method to `Input`. One documented exception: a field needing an exact, unmodified value (e.g. a password about to be - hashed) should read `$_POST` directly instead — see - `novaconium/pages/admin/password-hash/index.php`. `Lib\Csrf` + hashed or verified) should read `$_POST` directly instead — see the + password fields in `novaconium/pages/admin/users/index.php` and + `novaconium/pages/admin/login/index.php`. `Lib\Csrf` (`novaconium/lib/Csrf.php`) is standalone session-token CSRF protection, not wired into `FormValidator` — a sidecar calls `Csrf::verify()` directly. - It's the first thing in the framework to start a native PHP session (only - lazily, when a form actually calls it), which is otherwise unrelated to - `AdminAuth`'s own session-free Basic Auth. + It was the first thing in the framework to start a native PHP session + (only lazily, when a form actually calls it); `Lib\Session` and + `AdminAuth`'s session login now share that same native session, safely + in any order. - Don't use Twig's `|slice` filter on a **string** (as opposed to an array) — it unconditionally calls PHP's `mb_substr()` with no fallback (`novaconium/vendor/twig/src/Extension/CoreExtension.php`), which diff --git a/App/config.php b/App/config.php index d6c7113..1d9ff8b 100644 --- a/App/config.php +++ b/App/config.php @@ -15,11 +15,11 @@ return [ // 'matomo_url' => 'https://matomo.example.com/', // 'matomo_site_id' => '1', - // Docs: /admin/docs/admin-auth — generate a hash with: - // php -r "echo password_hash('yourpassword', PASSWORD_DEFAULT), PHP_EOL;" - // or use the built-in /admin/password-hash form. - // 'admin_username' => 'admin', - // 'admin_password_hash' => '$2y$10$...', + // Docs: /admin/docs/admin-auth — session login for /admin/* against + // the SQLite-backed users table. After enabling, create the first user + // at /admin/users, or beforehand (safer) with: + // php novaconium/bin/create-admin-user.php + // 'admin_auth_enabled' => true, // Docs: /admin/docs/database — adds (or overrides) named Lib\Db // connections. This merges into db_connections by name rather than @@ -38,9 +38,9 @@ return [ // ], // ], - // Docs: /admin/docs/drafts — requires admin_password_hash above to be - // set to actually gate anything; open access otherwise, same as the - // rest of /admin/*. + // Docs: /admin/docs/drafts — requires admin_auth_enabled above (and at + // least one user) to actually gate anything; open access otherwise, + // same as the rest of /admin/*. // 'draft_routes' => ['blog/upcoming-post'], // Docs: /admin/docs/content-index — powers /sitemap.xml, /search, and diff --git a/App/pages/about/index.twig b/App/pages/about/index.twig index 4f488f9..6125b4c 100644 --- a/App/pages/about/index.twig +++ b/App/pages/about/index.twig @@ -31,7 +31,7 @@

Everything the framework itself ships — default pages, default library classes, the root layout — lives under novaconium/, and can be overridden by placing a same-named file under App/, the only directory a site author is expected to touch. The same override mechanism covers configuration, too: any key in novaconium/config.php can be replaced piecemeal from App/config.php.

-

Beyond routing and templating, Novaconium ships with SEO meta tags (canonical links, Open Graph, Twitter Card), optional Matomo analytics with automatic 404 tracking, and an HTTP Basic Auth gate reusable across every /admin/* page — all off or sensible by default, and all documented at {{ icons.book() }}/admin/docs, rendered live from this same running instance rather than a separate website.

+

Beyond routing and templating, Novaconium ships with SEO meta tags (canonical links, Open Graph, Twitter Card), optional Matomo analytics with automatic 404 tracking, and a multi-user admin login (with browser-based user management) covering every /admin/* page — all off or sensible by default, and all documented at {{ icons.book() }}/admin/docs, rendered live from this same running instance rather than a separate website.

It's a good fit for small marketing sites, blogs, and internal tools where a full framework would be overkill but a flat-file site generator alone falls short of real server-side logic. The source is on Git if you want to see how it's put together: {{ icons.git() }}git.4lt.ca/4lt/novaconium.

diff --git a/App/pages/index.twig b/App/pages/index.twig index 19b3e36..6df0d33 100644 --- a/App/pages/index.twig +++ b/App/pages/index.twig @@ -57,7 +57,7 @@

Matomo & admin auth

-

Built-in analytics tracking and an HTTP Basic Auth gate for /admin/* — both off until you turn them on in App/config.php.

+

Built-in analytics tracking and a multi-user session login for /admin/* — both off until you turn them on in App/config.php.

Override anything

diff --git a/README.md b/README.md index 5d228e7..c23d614 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,12 @@ A tiny, Hugo-flavored PHP micro-framework. Routes are directories on disk, pages - **Layout inheritance** — `_layout/layout.twig` directories are resolved by walking upward from the matched page, so you can override the layout for a whole subtree. - **SEO boilerplate out of the box** — the default layout ships meta description, canonical link, robots, Open Graph, and Twitter Card tags, all overridable per-page via Twig blocks. - **Built-in Matomo analytics** — set `matomo_url` and `matomo_site_id` in `App/config.php` to enable tracking site-wide, including automatic 404 tracking. Off by default. -- **Admin authentication** — gate every `/admin/*` route behind HTTP Basic Auth by setting `admin_username`/`admin_password_hash` in `App/config.php`; reusable for any admin page a project adds later, with a `/admin/logout` link to clear cached credentials and a built-in `/admin/password-hash` form so generating the hash doesn't require the CLI. Off by default. +- **Admin authentication** — gate every `/admin/*` route behind a session login with multi-user management: a SQLite-backed `users` table, `/admin/login`/`/admin/logout`, and an `/admin/users` page to create, disable, delete, group, promote/demote, and change the email or password of accounts (plus a `novaconium/bin/create-admin-user.php` CLI for the first user or deploy scripts). Two roles: the first user created is the admin; everyone after is a registered user with an optional group. Every account has a unique, normalized email address — groundwork for email verification later. Enabled with a single `admin_auth_enabled` flag in `App/config.php`; off by default, and reusable for any admin page a project adds later. +- **Access control** — assign a page (or a section, one line per page) to a user or group from its sidecar: `Access::require('group:members')` returns `null` or a ready-made `Response` (login redirect with a return path, or a 404 for the wrong account). Public is the default — a sidecar that never calls it is untouched, and static (sidecar-less, cached) pages are always public by construction. Gated pages stay out of `/search` and `/sitemap.xml` automatically. - **Draft pages** — list a route under `draft_routes` in `App/config.php` to make it visible only to an authenticated admin; anyone else gets a plain 404, not a login prompt. Reuses the admin auth check directly, and is excluded from static caching so a cached copy can't leak the draft to the public. See `/admin/docs/drafts`. - **Dark/light theme toggle** — a nav button flips a `data-theme` attribute (persisted to `localStorage`) that swaps every color via CSS custom properties; both palettes live in `App/sass/_colors.sass`, same override mechanism as everything else. - **Self-hosted spam prevention & form validation** — `Lib\SpamGuard`, a reusable class for any form: a CSS-hidden honeypot field plus a submission-timing check, no external CAPTCHA service, site key, or outbound API call. Pairs with `Lib\FormValidator` (accumulating required-field/email/length checks) and `Lib\Validate` (the underlying validation primitives — email, length, phone, postal/zip, spam-word checks). All three ship in `novaconium/lib/`, demonstrated on the contact form. -- **Form security by default** — `Lib\Input`, a cleaning accessor for `$_POST`/`$_GET` (defense-in-depth against HTML/script injection, not a substitute for parameterized queries), and `Lib\Csrf`, standalone session-token CSRF protection called directly from a sidecar. Both ship in `novaconium/lib/`, wired into the contact form, `/admin/clear-cache`, and `/admin/password-hash`. +- **Form security by default** — `Lib\Input`, a cleaning accessor for `$_POST`/`$_GET` (defense-in-depth against HTML/script injection, not a substitute for parameterized queries), and `Lib\Csrf`, standalone session-token CSRF protection called directly from a sidecar. Both ship in `novaconium/lib/`, wired into the contact form, `/admin/clear-cache`, `/admin/login`, and `/admin/users`. - **SQLite/MySQL database, zero setup** — `Lib\Db`, a thin PDO wrapper (no ORM) supporting multiple named connections open at once — e.g. this site's own SQLite data plus a MySQL connection to a legacy database, usable in the same sidecar — each with its own plain-SQL migration convention, applied automatically on first use or via `php novaconium/bin/migrate.php`. SQLite data lives in a project-owned top-level `data/` directory, outside both `public/` and `novaconium/`. See `/admin/docs/database`. - **Sessions with flash data** — `Lib\Session`, a thin wrapper around native PHP sessions with CodeIgniter-style flash values (set now, readable on exactly the next request) for post/redirect/GET flows without a query-string flag. Lazy-start, same mechanism `Lib\Csrf` already uses. See `/admin/docs/session`. - **Content index: sitemap, search, tags** — `/sitemap.xml`, full-text `/search` (SQLite FTS5), and blog tag browsing all share one crawler that renders every page and harvests `keywords`/`tags`/`changefreq`/`priority` Twig blocks via Twig's own `renderBlock()` — no front-matter, no separate metadata files. Off by default (depends on SQLite); reindexes lazily on demand or via `php novaconium/bin/index-content.php`. See `/admin/docs/content-index`. @@ -98,6 +99,7 @@ The full framework documentation — routing, sidecars, libraries, database, ses - [SEO](http://127.0.0.1:8000/admin/docs/seo) - [Matomo](http://127.0.0.1:8000/admin/docs/matomo) - [Admin authentication](http://127.0.0.1:8000/admin/docs/admin-auth) +- [Access control](http://127.0.0.1:8000/admin/docs/access-control) - [Draft pages](http://127.0.0.1:8000/admin/docs/drafts) - [Styling](http://127.0.0.1:8000/admin/docs/styling) - [Project layout](http://127.0.0.1:8000/admin/docs/project-layout) diff --git a/novaconium/ISSUES.md b/novaconium/ISSUES.md index 0971bb9..2d1e98f 100644 --- a/novaconium/ISSUES.md +++ b/novaconium/ISSUES.md @@ -51,19 +51,17 @@ expected vs. actual behavior. For features, include the motivating use case.> ## Backlog -Suggested build order (foundations first, since admin login builds on -three of the others): +Suggested build order (foundations first): -1. **Media/file manager** — no hard dependency; usable standalone, though - best gated behind admin login once that exists. -2. **Admin login & user management** — SQLite groundwork and session - handling it needed are both done; ready to build. -3. **In-house comments** — needs admin login & user management (comments - are tied to real user accounts, not anonymous); build right after it. -4. **Ecommerce functionality** — needs admin login & user management - (order/product admin, and customer accounts); SQLite groundwork and - session handling (cart) it needed are both done. -5. **Paywall functionality** — needs everything Ecommerce needs, plus +1. **Media/file manager** — no hard dependency; usable standalone, and + already gated behind admin login the moment it exists under `/admin/*`. +2. **In-house comments** — admin login & user management (Done + 2026-07-14) unblocked this; comments are tied to real user accounts, + not anonymous. +3. **Ecommerce functionality** — its dependencies (SQLite groundwork, + session handling for the cart, admin login for order/product admin) + are all done now. +4. **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" @@ -74,10 +72,30 @@ three of the others): MySQL support, Session handling (with flash sessions), Draft pages (admin-only preview), Blog tags/categories + Internal search + XML sitemap (shipped together as one content index — see Done), Blog RSS -feed, and Syntax highlighting on code blocks all shipped 2026-07-14. +feed, Syntax highlighting on code blocks, and Admin login & user +management all shipped 2026-07-14. See **Won't Do** below for 404 tracking, dropped in favor of Matomo. +### Email verification for user accounts + +- **Type:** Feature +- **Status:** Backlog +- **Priority:** Medium +- **Depends on:** Admin login & user management (Done) +- **Added:** 2026-07-14 + +Verify a user's email address by sending a confirmation link — the +groundwork is already in place: every account has a required, unique, +normalized email (`users.email`, added the same day as user deletion — +see User deletion & email addresses under Done). Needs a `verified_at` +(or token) column, a token-generation/expiry scheme, a send path +(`Lib\Mailer` is currently a log-to-file stand-in — this feature is +probably what forces it to grow a real mail transport), and a decision +on what an unverified account may do (log in but fail `Lib\Access` +rules? not log in at all?). Also the natural home for password-reset- +by-email later, which shares all the same plumbing. + ### Media/file manager - **Type:** Feature @@ -97,31 +115,12 @@ wanted later, in which case that part could ride on SQLite groundwork). Needs basic safety handling: extension allowlist, filename sanitization, and a max upload size, since this is a file-write surface. -### Admin login & user management - -- **Type:** Feature -- **Status:** Backlog -- **Priority:** Medium -- **Depends on:** SQLite groundwork (Done), Session handling (with flash sessions) (Done) -- **Added:** 2026-07-12 - -A single-user HTTP Basic Auth stopgap now gates `/admin/*` -(`novaconium/src/AdminAuth.php`, `admin_username`/`admin_password_hash` in -`App/config.php` — see `/admin/docs/admin-auth`), so `/admin` is no longer -wide open by default choice. This entry is the real, larger replacement: -multiple accounts, a user store (the SQLite groundwork above — a `users` -table with hashed passwords via `password_hash()`/`password_verify()`, no -external auth library), proper sessions instead of Basic Auth (rides on -session handling above), and basic user management (create/disable a -user, change password). Ship this by replacing `AdminAuth::requireLogin()` -with the new mechanism, not layering on top of it. - ### In-house comments - **Type:** Feature - **Status:** Backlog - **Priority:** Medium -- **Depends on:** Admin login & user management, SQLite groundwork (Done) +- **Depends on:** Admin login & user management (Done), SQLite groundwork (Done) - **Added:** 2026-07-14 A self-hosted comments library — no third-party service (Disqus, @@ -149,7 +148,7 @@ the same way the contact form does). - **Type:** Feature - **Status:** Backlog - **Priority:** Low -- **Depends on:** SQLite groundwork (Done), Session handling (with flash sessions) (Done), Admin login & user management +- **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` / @@ -169,14 +168,18 @@ planning it all up front here. - **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 +- **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, similar to -how admin login gates `/admin/*`). Reuses Ecommerce's payment-gateway +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` @@ -192,6 +195,133 @@ _Nothing yet._ ## Done +### 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 + +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 ` `). 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 `
` 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 + +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 + +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). + ### Syntax highlighting on code blocks - **Type:** Feature diff --git a/novaconium/bin/create-admin-user.php b/novaconium/bin/create-admin-user.php new file mode 100644 index 0000000..308b84c --- /dev/null +++ b/novaconium/bin/create-admin-user.php @@ -0,0 +1,75 @@ + +// +// The password is read from stdin — typed at the prompt (echo suppressed +// where the terminal supports it), or piped: +// +// echo 'the-password' | php novaconium/bin/create-admin-user.php admin admin@example.com +// +// Deliberately not gated on admin_auth_enabled: creating the row is +// harmless while the gate is off, and doing it first is the safer order. + +$username = trim((string) ($argv[1] ?? '')); +$email = Validate::isEmail((string) ($argv[2] ?? '')); +if ($username === '' || strlen($username) > 64 || $email === false) { + fwrite(STDERR, "Usage: php novaconium/bin/create-admin-user.php \n"); + exit(1); +} + +// Db::connection() runs pending migrations on first touch, so the users +// table exists after this even on a fresh clone. +$exists = (bool) Db::query('SELECT EXISTS(SELECT 1 FROM users WHERE username = ?)', [$username])->fetchColumn(); +if ($exists) { + fwrite(STDERR, "A user named '{$username}' already exists.\n"); + exit(1); +} + +$emailExists = (bool) Db::query('SELECT EXISTS(SELECT 1 FROM users WHERE email = ?)', [$email])->fetchColumn(); +if ($emailExists) { + fwrite(STDERR, "A user with the email '{$email}' already exists.\n"); + exit(1); +} + +$interactive = stream_isatty(STDIN); +if ($interactive) { + fwrite(STDOUT, "Password for '{$username}': "); + // Suppress echo while the password is typed; restore afterwards. + // shell_exec() may be unavailable/no-op on some setups — then the + // password just echoes, same as any basic CLI prompt. + shell_exec('stty -echo 2> /dev/null'); +} + +$password = rtrim((string) fgets(STDIN), "\r\n"); + +if ($interactive) { + shell_exec('stty echo 2> /dev/null'); + fwrite(STDOUT, "\n"); +} + +if (strlen($password) < 8) { + fwrite(STDERR, "Use a password of at least 8 characters.\n"); + exit(1); +} + +// Always role 'admin', as the script name says — /admin/users is the +// place to create registered users; this exists for first-user setup and +// lockout recovery, both of which need an admin. +Db::query( + "INSERT INTO users (username, email, password_hash, role, user_group, is_disabled, created_at) VALUES (?, ?, ?, 'admin', '', 0, ?)", + [$username, $email, password_hash($password, PASSWORD_DEFAULT), gmdate('Y-m-d\TH:i:s\Z')] +); + +echo "User '{$username}' created.\n"; +echo "If admin auth isn't enabled yet, set 'admin_auth_enabled' => true in App/config.php.\n"; diff --git a/novaconium/bootstrap.php b/novaconium/bootstrap.php index 97b0db4..4bca977 100644 --- a/novaconium/bootstrap.php +++ b/novaconium/bootstrap.php @@ -4,11 +4,9 @@ * Front-controller wiring. Every request — via public/index.php (Apache) or * public/router.php (php -S) — ends up require'ing this one file, which: * 1. loads config (framework defaults + optional App/ override) - * 2. handles the one hardcoded route (/admin/logout) that exists outside - * the normal page tree - * 3. resolves the URL to a page directory (Router) - * 4. gates /admin/* behind Basic Auth, if configured (AdminAuth) - * 5. renders the matched page, or a 404 (Renderer) + * 2. resolves the URL to a page directory (Router) + * 3. gates /admin/* behind session login, if enabled (AdminAuth) + * 4. renders the matched page, or a 404 (Renderer) * There's no framework "kernel" class doing this — it's just a plain * top-to-bottom script, deliberately, so a dev can read the whole * request lifecycle in one file without chasing an abstraction. @@ -37,20 +35,7 @@ if ($config['debug']) { ini_set('display_errors', '1'); } -// Trim the query string and any trailing slash so /admin/logout/ and -// /admin/logout?x=1 both match the check below the same way $router does -// internally for real page routes. $requestUri = $_SERVER['REQUEST_URI'] ?? '/'; -$requestPath = rtrim(parse_url($requestUri, PHP_URL_PATH) ?: '/', '/'); - -// /admin/logout isn't a real page under App/pages/ or novaconium/pages/ — -// there's nothing to route to, so it's special-cased here before the -// router even runs. AdminAuth::logout() always sends a fresh 401 challenge -// (the standard trick for "logging out" of HTTP Basic Auth, which has no -// real server-side session to invalidate) and exits immediately. -if ($requestPath === '/admin/logout') { - AdminAuth::logout(); -} // Router::resolve() only answers "does a page exist at this URL, and if // so which directory / what params?" — it never touches Twig, sidecars, or @@ -58,36 +43,49 @@ if ($requestPath === '/admin/logout') { $router = new Router($config['pages_dirs']); $route = $router->resolve($requestUri); -// Every route under /admin/* — clear-cache, docs, password-hash, and any -// admin page a project adds later — is gated here, once, rather than in -// each page individually. A new admin page is automatically protected the -// moment it exists; nothing to remember to wire up. No-op (open access) -// when admin_password_hash is empty, which is the default. See -// novaconium/src/AdminAuth.php and /admin/docs/admin-auth. -$isAdminRoute = $route->found && ($route->dir === 'admin' || str_starts_with((string) $route->dir, 'admin/')); -if ($isAdminRoute) { - AdminAuth::requireLogin($config['admin_username'], $config['admin_password_hash']); -} - // Both of these are derived, request-independent config values that get // handed to the Renderer so it can expose them to every Twig template as // globals (matomo_url/matomo_site_id/admin_auth_enabled) — see // Renderer::__construct(). Normalizing the trailing slash here means every // template can safely do `matomo_url + 'matomo.php'` without checking. $matomoUrl = $config['matomo_url'] !== '' ? rtrim($config['matomo_url'], '/') . '/' : ''; -$adminAuthEnabled = $config['admin_password_hash'] !== ''; +$adminAuthEnabled = (bool) $config['admin_auth_enabled']; $cache = new Cache($config['cache_dir']); $renderer = new Renderer($config['pages_dirs'], $cache, $adminAuthEnabled, $matomoUrl, $config['matomo_site_id'], $config['site_name'], $config['content_index_enabled']); -// A route listed in draft_routes is only visible to an authenticated admin -// — anyone else gets treated exactly like a route that doesn't exist at -// all (a plain 404, not a login prompt), so a draft's existence isn't -// revealed to anyone poking at the URL. See /admin/docs/drafts. Reuses the -// same credential check /admin/* uses (AdminAuth::isAuthenticated()) — -// in practice an admin authenticates by visiting /admin once first; the -// browser then resends those same Basic Auth credentials to draft URLs -// too, since they share the same origin/realm. +// Every route under /admin/* — clear-cache, docs, users, and any admin +// page a project adds later — is gated here, once, rather than in each +// page individually. A new admin page is automatically protected the +// moment it exists; nothing to remember to wire up. Two steps: nobody +// logged in → redirect to the login form (requireLogin() exits); logged +// in but not an admin (a 'registered' user — see /admin/docs/admin-auth) +// → the same plain 404 an unmatched route gets, since bouncing an +// already-authenticated user back to the login form would be a lie (what +// they lack is the admin role, not a session). The one exemption is the +// login form itself, which has to stay reachable logged-out or +// requireLogin()'s redirect to it would loop forever. No-op (open access) +// when admin_auth_enabled is false (the default), or while no users exist +// yet (so the first user can be created at /admin/users). See +// novaconium/src/AdminAuth.php and /admin/docs/admin-auth. +$isAdminRoute = $route->found && ($route->dir === 'admin' || str_starts_with((string) $route->dir, 'admin/')); +if ($isAdminRoute && $route->dir !== 'admin/login') { + AdminAuth::requireLogin($config['admin_auth_enabled']); + + if (!AdminAuth::isAdmin($config['admin_auth_enabled'])) { + $renderer->renderNotFound($requestUri); + return; + } +} + +// A route listed in draft_routes is only visible to a logged-in admin — +// anyone else (including logged-in registered users) gets treated exactly +// like a route that doesn't exist at all (a plain 404, not a login +// prompt), so a draft's existence isn't revealed to anyone poking at the +// URL. See /admin/docs/drafts. Reuses the same access check /admin/* uses +// (AdminAuth::isAdmin()) — an admin logs in once at /admin/login, and the +// session cookie covers draft URLs too, since it's scoped to the whole +// origin. $isDraftRoute = $route->found && in_array($route->dir, $config['draft_routes'], true); // $route->found is false for anything Router couldn't match to a real page @@ -103,7 +101,7 @@ $isDraftRoute = $route->found && in_array($route->dir, $config['draft_routes'], // therefore AdminAuth::requireLogin()) ever runs again — permanently // serving the admin panel to anyone, unauthenticated, straight from the // static cache. See novaconium/src/Renderer.php. -if (!$route->found || ($isDraftRoute && !AdminAuth::isAuthenticated($config['admin_username'], $config['admin_password_hash']))) { +if (!$route->found || ($isDraftRoute && !AdminAuth::isAdmin($config['admin_auth_enabled']))) { $renderer->renderNotFound($requestUri); return; } diff --git a/novaconium/config.php b/novaconium/config.php index ce7d8d2..e41af59 100644 --- a/novaconium/config.php +++ b/novaconium/config.php @@ -28,16 +28,21 @@ return [ 'matomo_url' => '', 'matomo_site_id' => '', - // Gates every /admin/* route (clear-cache, docs, and any future admin - // page) behind HTTP Basic Auth. Leave admin_password_hash empty (the - // default) to disable the gate entirely — matches this project's - // existing wide-open behavior until a project opts in. Generate a hash - // with: php -r "echo password_hash('yourpassword', PASSWORD_DEFAULT), PHP_EOL;" - // and set both via App/config.php, e.g.: - // 'admin_username' => 'admin', - // 'admin_password_hash' => '$2y$10$...', - 'admin_username' => 'admin', - 'admin_password_hash' => '', + // Gates every /admin/* route (clear-cache, docs, users, and any future + // admin page) behind a session login against the `users` table on + // Lib\Db's default connection — see /admin/docs/admin-auth. The first + // user created is the admin; users after that are 'registered', each + // with an optional group, and see whatever content sidecars grant via + // Lib\Access (see /admin/docs/access-control) — /admin/* itself 404s + // for them. Off by default because it depends on SQLite (same + // reasoning as content_index_enabled below): when false, /admin/* is + // wide open, /admin/login, /admin/logout, and /admin/users 404, + // Access::require() allows everything, and nothing ever touches + // Lib\Db because of this feature. After enabling it via + // App/config.php, create the first user at /admin/users (open access + // until at least one user exists) or with: + // php novaconium/bin/create-admin-user.php + 'admin_auth_enabled' => false, // Lib\Db (see /admin/docs/database) — named, simultaneously-usable // connections, keyed by name; 'default' is the only one required. A diff --git a/novaconium/lib/Access.php b/novaconium/lib/Access.php new file mode 100644 index 0000000..9ce3391 --- /dev/null +++ b/novaconium/lib/Access.php @@ -0,0 +1,105 @@ +' (the user's users.user_group matches), or + * 'user:' (that exact account); several rules mean "any of + * these". No rules at all means any logged-in user. Admins always pass + * every rule. Returns null when the request may proceed, or a Response + * for the sidecar to return: a 303 to /admin/login (with a ?return= path + * back here) when nobody is logged in, or a plain 404 when someone *is* + * logged in but isn't allowed — same hide-don't-tease posture as draft + * pages, and the same plain-text 404 /search returns when disabled. + * + * Public is the default, twice over: a sidecar that never calls this is + * untouched, and a page with no sidecar at all *can't* call it — static + * (cached) pages are always public. That's load-bearing, not incidental: + * only sidecar-less pages are ever written to the static HTML cache + * (which .htaccess serves before PHP runs — see /admin/docs/caching), so + * a gated page, necessarily having a sidecar, is never cached. This + * satisfies the caching/auth standing rule in AGENTS.md by construction + * rather than by a bootstrap.php exclusion like drafts/admin need. + * + * Same open-until-configured posture as the rest of admin auth: with + * admin_auth_enabled off, or while no users exist yet, require() allows + * everything (there'd be nothing to log in as) — and never touches + * Lib\Db, so a site that never opted in never gets a database file. + * + * The content-index crawl runs every sidecar as an anonymous GET, so a + * gated page's sidecar short-circuits to the login redirect during a + * crawl — Renderer::renderForIndex() discards Responses, meaning gated + * pages are automatically absent from /search and /sitemap.xml, with no + * extra wiring. require() has no side effects on deny (the return path + * travels in the redirect URL, not the session) for the same reason: a + * crawl must not scribble on the visitor's session. + */ +final class Access +{ + private static ?bool $enabled = null; + + public static function require(string ...$rules): ?Response + { + if (!self::enabled() || !AdminAuth::hasUsers()) { + return null; + } + + $user = AdminAuth::currentUser(); + + if ($user === null) { + $path = (string) (parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH) ?: '/'); + + return Response::redirect('/admin/login?return=' . rawurlencode($path), 303); + } + + if ($user['role'] === 'admin' || $rules === []) { + return null; + } + + foreach ($rules as $rule) { + if (str_starts_with($rule, 'user:') && substr($rule, 5) === $user['username']) { + return null; + } + + if (str_starts_with($rule, 'group:') && $user['user_group'] !== '' && substr($rule, 6) === $user['user_group']) { + return null; + } + } + + return Response::html('404 Not Found', 404); + } + + /** + * Same two-step config load bootstrap.php/bin scripts and the + * /search sidecar use — Lib\ classes aren't handed $config, so this + * loads its own copy to read admin_auth_enabled (memoized per + * request; static state never survives across requests). + */ + private static function enabled(): bool + { + if (self::$enabled === null) { + $config = require __DIR__ . '/../config.php'; + + $appConfigFile = __DIR__ . '/../../App/config.php'; + if (is_file($appConfigFile)) { + $config = array_merge($config, require $appConfigFile); + } + + self::$enabled = (bool) $config['admin_auth_enabled']; + } + + return self::$enabled; + } +} diff --git a/novaconium/lib/Csrf.php b/novaconium/lib/Csrf.php index 6ccd876..b4035c0 100644 --- a/novaconium/lib/Csrf.php +++ b/novaconium/lib/Csrf.php @@ -15,11 +15,12 @@ namespace Lib; * * * - * This is the first thing in the framework that starts a native PHP session + * This was the first thing in the framework to start a native PHP session * — but only lazily, the moment token()/verify() is actually called. A page - * that never touches Csrf never gets a session cookie. This is unrelated to - * Lib\AdminAuth, which stays fully stateless (HTTP Basic Auth, no sessions - * for login state) — see novaconium/src/AdminAuth.php. + * that never touches Csrf never gets a session cookie. Lib\Session and + * App\AdminAuth (session-based admin login) now touch the same native + * session the same lazy way — safe in any order, since ensureSession() + * no-ops when a session is already active. */ final class Csrf { diff --git a/novaconium/lib/Db.php b/novaconium/lib/Db.php index 3032489..26190a6 100644 --- a/novaconium/lib/Db.php +++ b/novaconium/lib/Db.php @@ -89,6 +89,9 @@ final class Db */ private static function connectSqlite(array $config): PDO { + self::requireDriver('sqlite', 'pdo_sqlite', + 'bundled with PHP but sometimes not enabled — Debian/Ubuntu: `apt install php-sqlite3`; Arch: uncomment `extension=pdo_sqlite` in php.ini'); + $path = $config['path']; $dir = dirname($path); if (!is_dir($dir)) { @@ -109,6 +112,9 @@ final class Db */ private static function connectMysql(array $config): PDO { + self::requireDriver('mysql', 'pdo_mysql', + 'Debian/Ubuntu: `apt install php-mysql`; Arch: uncomment `extension=pdo_mysql` in php.ini'); + $charset = $config['charset'] ?? 'utf8mb4'; $dsn = "mysql:host={$config['host']};port={$config['port']};dbname={$config['database']};charset={$charset}"; @@ -118,6 +124,23 @@ final class Db ]); } + /** + * A missing PDO driver otherwise surfaces as a bare PDOException + * ("could not find driver") from deep inside a connect call — hit for + * real the first time this ran on a PHP install without pdo_sqlite + * enabled. Checking PDO::getAvailableDrivers() up front turns that + * into an error that names the extension and how to install it. + */ + private static function requireDriver(string $driver, string $extension, string $installHint): void + { + if (!in_array($driver, PDO::getAvailableDrivers(), true)) { + throw new RuntimeException( + "PHP is missing the {$extension} extension, which this connection's '{$driver}' driver needs ({$installHint}). " . + 'Verify with `php -m`, and restart PHP after enabling it. See /admin/docs/database.' + ); + } + } + /** * Applies any *.sql file under $migrationsDirs not yet recorded in this * connection's own schema_migrations table. $migrationsDirs is an diff --git a/novaconium/lib/Input.php b/novaconium/lib/Input.php index af7f287..4b9db62 100644 --- a/novaconium/lib/Input.php +++ b/novaconium/lib/Input.php @@ -22,11 +22,13 @@ namespace Lib; * dangerous. * * One documented exception: a field that needs an exact, unmodified value - * (e.g. a password about to be hashed) should read $_POST directly instead — - * cleaning would silently strip characters like < and > before hashing, - * producing a hash that doesn't match what the user actually typed. See - * novaconium/pages/admin/password-hash/index.php for the one place this - * framework does that on purpose. + * (e.g. a password about to be hashed or verified) should read $_POST + * directly instead — cleaning would silently strip characters like < and > + * before hashing, producing a hash that doesn't match what the user + * actually typed (or failing a login whose password actually matches). See + * the password fields in novaconium/pages/admin/users/index.php and + * novaconium/pages/admin/login/index.php for the places this framework + * does that on purpose. */ final class Input { diff --git a/novaconium/lib/Session.php b/novaconium/lib/Session.php index fafeee2..13523a6 100644 --- a/novaconium/lib/Session.php +++ b/novaconium/lib/Session.php @@ -61,6 +61,20 @@ final class Session unset($_SESSION[$key]); } + /** + * Swaps the session id for a fresh one, keeping the session's data. + * Call on any privilege change — after a successful login, and on + * logout — so a session id an attacker planted or observed before the + * change is worthless after it (session fixation). App\AdminAuth does + * exactly this. + */ + public static function regenerate(): void + { + self::ensureSession(); + + session_regenerate_id(true); + } + /** * Stores $value so it's readable via getFlash($key) on the next * request only, then gone — regardless of whether getFlash() was diff --git a/novaconium/migrations/0002_create_users.sql b/novaconium/migrations/0002_create_users.sql new file mode 100644 index 0000000..e24be32 --- /dev/null +++ b/novaconium/migrations/0002_create_users.sql @@ -0,0 +1,10 @@ +CREATE TABLE IF NOT EXISTS users ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + username TEXT NOT NULL UNIQUE, + email TEXT NOT NULL UNIQUE, + password_hash TEXT NOT NULL, + role TEXT NOT NULL DEFAULT 'registered', + user_group TEXT NOT NULL DEFAULT '', + is_disabled INTEGER NOT NULL DEFAULT 0, + created_at TEXT NOT NULL +); diff --git a/novaconium/pages/_layout/icons.twig b/novaconium/pages/_layout/icons.twig index 8761aa7..833807d 100644 --- a/novaconium/pages/_layout/icons.twig +++ b/novaconium/pages/_layout/icons.twig @@ -92,6 +92,15 @@ {% endmacro %} +{% macro users(class) %} + +{% endmacro %} + {% macro trash(class) %}
  • {{ icons.sitemap() }}XML sitemap
  • {{ icons.rss() }}RSS feeds
  • {{ icons.lock() }}Admin authentication
    • +
  • {{ icons.lock() }}Access control
  • {{ icons.lock() }}Draft pages
  • {{ icons.book() }}Layouts
  • {{ icons.book() }}Static caching
    • diff --git a/novaconium/pages/admin/docs/access-control/index.twig b/novaconium/pages/admin/docs/access-control/index.twig new file mode 100644 index 0000000..df406ad --- /dev/null +++ b/novaconium/pages/admin/docs/access-control/index.twig @@ -0,0 +1,70 @@ +{% extends 'admin/docs/_layout/layout.twig' %} + +{% import '_layout/icons.twig' as icons %} + +{% block title %}Access control{% endblock %} + +{% block description %}Assign a page or section to a user or group from its sidecar with Lib\Access — public by default, static pages always public.{% endblock %} + +{% block robots %}noindex, nofollow{% endblock %} + +{% block docs_content %} +

    Access control

    + +

    Lib\Access (novaconium/lib/Access.php) assigns a page to a user, a group, or just "anyone logged in" — from the page's own sidecar, using the accounts {{ icons.lock() }}Admin authentication manages at /admin/users. One call at the top of index.php:

    + + 
    <?php
+
+use Lib\Access;
+
+if ($denied = Access::require('group:members')) {
+    return $denied;
+}
+
+return [
+    // ...normal sidecar context...
+];
    + +

    Access::require() returns null when the request may proceed, or a Response the sidecar returns as-is: nobody logged in → a 303 to /admin/login carrying a ?return= path so a successful login lands right back on the page they wanted; logged in but not allowed → a plain 404, the same hide-don't-tease posture as {{ icons.lock() }}draft pages.

    + +

    Rules

    + +
      +
    • Access::require() — no rules: any logged-in user (admin or registered).
      • +
    • Access::require('group:members') — users whose group (assigned at /admin/users) is members. Each user has at most one group; a group is just a text label, matched exactly — there's no groups table to manage.
      • +
    • Access::require('user:bob') — exactly that account.
      • +
    • Access::require('group:members', 'user:bob') — several rules mean any of them grants access.
      • +
    + +

    Admins always pass every rule — the admin role exists to run the site, so there's no way to write a rule that locks an admin out of content.

    + +

    Public is the default — and static pages are always public

    + +

    A sidecar that never calls Access::require() is completely untouched by all of this, and a page with no sidecar at all can't call it — so sidecar-less pages are always public. That's load-bearing rather than incidental: only sidecar-less pages are ever written to the {{ icons.book() }}static HTML cache, which Apache serves before PHP (and therefore any access check) runs. Because a gated page necessarily has a sidecar, it's never statically cached, so there's no way to leak a gated page through the cache — the caching/auth rule that drafts and /admin/* need explicit cache exclusions for is satisfied here by construction.

    + +

    Gating a section

    + +

    There's no per-directory config for this — a "section" is gated by giving each page in it a sidecar with the same check, which stays visible and greppable at the page level. To keep the rule itself in one place, put a _access.php file in the section directory (any file that isn't index.php/index.twig is invisible to the router) and require it from each sidecar — a PHP file can return a value, so it composes exactly like a direct call:

    + + 
    <?php
+// App/pages/members/_access.php — the section's one shared rule
+use Lib\Access;
+
+return Access::require('group:members');
    + + 
    <?php
+// App/pages/members/anything/index.php — each page in the section
+if ($denied = require dirname(__DIR__) . '/_access.php') {
+    return $denied;
+}
+
+return [];
    + +

    Interactions worth knowing

    + +
      +
    • Off means open. With admin_auth_enabled off (or while no users exist yet), Access::require() allows everything — there'd be nothing to log in as. Same open-until-configured posture as the rest of admin auth, and the same zero-footprint guarantee: it never touches Lib\Db in that state.
      • +
    • Gated pages stay out of {{ icons.search() }}search and the sitemap automatically. The content-index crawl runs every sidecar as an anonymous GET, so a gated sidecar short-circuits to the login redirect and the crawler skips the page — nothing to configure, verified for real. require() also has no side effects on deny (the return path travels in the redirect URL, not the session), so a crawl can't scribble on the visiting user's session.
      • +
    • Who's logged in? A sidecar that wants to greet the user (or vary content by account) can read App\AdminAuth::currentUser() — id/username/email/role/user_group, or null — and pass what it needs into its template context.
      • +
    +{% endblock %} diff --git a/novaconium/pages/admin/docs/admin-auth/index.twig b/novaconium/pages/admin/docs/admin-auth/index.twig index 7e15484..5f40952 100644 --- a/novaconium/pages/admin/docs/admin-auth/index.twig +++ b/novaconium/pages/admin/docs/admin-auth/index.twig @@ -4,49 +4,67 @@ {% block title %}Admin authentication{% endblock %} -{% block description %}Gating /admin/* behind HTTP Basic Auth, reusable for any future admin page.{% endblock %} +{% block description %}Session-based login with admin/registered roles, groups, and user management, gating /admin/* and draft pages.{% endblock %} {% block robots %}noindex, nofollow{% endblock %} {% block docs_content %}

    Admin authentication

    -

    Every route under /admin/* — /admin, /admin/clear-cache, the docs section, and any admin page a project adds later — can be gated behind HTTP Basic Auth with two App/config.php keys. It's off by default (same posture as Matomo): an empty admin_password_hash means no gate at all, matching this project's original wide-open behavior.

    +

    Every route under /admin/* — /admin, /admin/clear-cache, the docs section, and any admin page a project adds later — can be gated behind a session-based login against a users table in the {{ icons.book() }}database's default connection. It's off by default (same posture as the {{ icons.search() }}content index, and for the same reason: it depends on SQLite, a real dependency plenty of sites won't want): with admin_auth_enabled left false, /admin/* is wide open, /admin/login, /admin/logout, and /admin/users all 404 as if they didn't exist, and nothing ever touches Lib\Db because of this feature — no data/novaconium.sqlite gets created just because the code exists.

    -

    This replaced the old docs_enabled config flag, which only hid the docs section specifically. Since this gate covers all of /admin/* — including docs — there's no need for a separate docs-only toggle anymore; set a password and the whole admin area (docs included) requires login.

    +

    This replaced the original single-user HTTP Basic Auth stopgap (an admin_username/admin_password_hash config pair — both keys, and the /admin/password-hash hash-generator page, are gone). Same call sites in bootstrap.php, new mechanism: multiple accounts, real server-side login state (riding on {{ icons.book() }}Lib\Session), and user management in the browser.

    + +

    Two roles: admin and registered

    + +

    The first user ever created is the admin; every user created after that is registered. An admin runs the site: full /admin/* access, sees {{ icons.lock() }}draft pages, and passes every {{ icons.lock() }}Lib\Access rule. A registered user can log in at the same /admin/login and sees whatever content Lib\Access assigns to their account or their group — but /admin/* returns a plain 404 for them, not a login prompt (they are logged in; what they lack is the role). Each registered user can be assigned at most one group — a plain text label (e.g. members) that Access::require('group:members') matches exactly; there's no groups table to manage.

    Enabling it

    -

    Generate a password hash once — either on the command line:

    - - 
    php -r "echo password_hash('yourpassword', PASSWORD_DEFAULT), PHP_EOL;"
    - -

    ...or, if you'd rather not touch a terminal, at {{ icons.lock() }}/admin/password-hash — a small built-in form that does the same password_hash() call and hands back a ready-to-paste config snippet. Nothing typed there is stored or logged. Since it lives under /admin/* like everything else here, it's automatically covered by this same gate once a password is set — reachable while admin_password_hash is still empty (so you can generate your first one), then protected like any other admin page afterward.

    - -

    Then set both keys in App/config.php:

    +

    Turn it on in App/config.php:

    <?php
 // App/config.php
 return [
-    'admin_username'      => 'admin',
-    'admin_password_hash' => '$2y$10$...',
+    'admin_auth_enabled' => true,
 ];
    -

    Every request into /admin/* now requires that username/password via the browser's built-in Basic Auth prompt; anything outside /admin is unaffected.

    +

    Since this is the first SQLite-backed feature most sites turn on, make sure PHP has the pdo_sqlite extension enabled first (php -m | grep -i sqlite) — it's bundled with PHP but not always enabled; Debian/Ubuntu package it as php-sqlite3. Without it, the first request into /admin/* fails naming the missing extension. See Overview's requirements list.

    + +

    Enabling the flag alone protects nothing yet — while zero users exist, the whole admin area stays open, precisely so the first user (the admin) can be created. Do that either in the browser at /admin/users (you're logged in as the first user automatically the moment it's created, and the gate closes), or from the command line:

    + + 
    php novaconium/bin/create-admin-user.php admin admin@example.com
    + +

    The CLI reads the password from stdin (echo suppressed at an interactive prompt, and pipeable from a deploy script), and always creates an admin — it exists for first-user setup and lockout recovery, both of which need one; registered users are created at /admin/users. Running it before flipping admin_auth_enabled on is the safer order — the open setup window then never exists at all.

    + +

    The users table ships as a framework migration (novaconium/migrations/0002_create_users.sql) and is created automatically the first time anything touches the default connection — no manual schema step. Passwords are stored as password_hash() hashes and checked with password_verify(); no plaintext, and nothing here ever selects the hash back out except to verify a login. Every account also has a unique email address, stored normalized (trimmed, lowercased, via Lib\Validate::isEmail()) — not used for login (that's the username) or for any mail yet, but required up front so the planned email-verification flow (see novaconium/ISSUES.md) has an address for every account that already exists by then.

    + +

    Managing users

    + +

    /admin/users lists every account and handles the rest: create a user (registered, with an email address and an optional group — only the very first is the admin), disable/enable one, assign or change a group, promote/demote between admin and registered, change an email address, change a password, and delete an account outright. Behaviors worth knowing:

    + +
      +
    • Disabling is immediate. A disabled user can't log in, and any session they already had is re-checked against the table on its next request — there's no "still logged in until the session expires" window. The same immediate re-check applies to a role or group change.
      • +
    • The last active admin can't be disabled, demoted, or deleted. Any of the three would lock everyone out of /admin/* permanently (the zero-users setup window doesn't reopen — the table isn't empty), leaving only the CLI or hand-editing the database as recovery. The form refuses instead. Registered users carry no such guard.
      • +
    • Delete is a hard delete — the row is gone, the username and email become reusable, and any live session dies on its next request, same as disabling. Disable is the right tool for "shut this account out but keep it"; delete is for accounts that shouldn't exist at all.
      • +
    • More admins are allowed — "first user is the admin" is the default, not a cap; promote a registered user any time.
      • +

    How it's wired

    -

    novaconium/src/AdminAuth.php is a single reusable check — AdminAuth::requireLogin($username, $passwordHash) — called once from novaconium/bootstrap.php for any resolved route whose path is admin or starts with admin/, and only for routes that actually resolved (no login prompt on an unrelated 404). Because the check lives in bootstrap.php rather than on each page, a new admin page needs zero extra wiring to be protected — dropping a new directory under App/pages/admin/ or novaconium/pages/admin/ is automatically gated the moment it exists.

    +

    novaconium/src/AdminAuth.php is a pair of reusable checks called once from novaconium/bootstrap.php for any resolved route whose path is admin or starts with admin/, and only for routes that actually resolved (no redirect on an unrelated 404): AdminAuth::requireLogin($enabled) redirects anyone not logged in to the login form, then AdminAuth::isAdmin($enabled) 404s anyone who is logged in but isn't an admin — a registered user is authenticated, so bouncing them back to the login form would be a lie. Because the checks live in bootstrap.php rather than on each page, a new admin page needs zero extra wiring to be protected — dropping a new directory under App/pages/admin/ or novaconium/pages/admin/ is automatically gated the moment it exists. The one exemption is admin/login itself, which has to stay reachable logged-out or the redirect to it would loop.

    -

    The credential check itself is a separate method, AdminAuth::isAuthenticated($username, $passwordHash) — requireLogin() is just that check plus the 401-challenge response on failure. {{ icons.lock() }}Draft pages reuse isAuthenticated() directly with a different failure response (a plain 404, not a login prompt), rather than duplicating the credential logic.

    +

    The login form is a normal page with a normal form: CSRF-protected like every other form here (see {{ icons.email() }}Forms), reading the username via Lib\Input and the password straight from $_POST (the documented exact-value exception — cleaning would strip characters like </> and fail a login whose password actually matches). A successful login regenerates the session id (Session::regenerate()) before storing the user id, so a session id planted or observed pre-login never becomes an authenticated one — then lands on ?return= (how Lib\Access sends someone back to the gated page they wanted; validated to be a local path, never another site), or, with no return path, on /admin for admins and the homepage for registered users.

    + +

    {{ icons.lock() }}Draft pages reuse isAdmin() directly with a different failure response (a plain 404 for everyone unauthorized, never a login redirect), rather than duplicating the logic. The session cookie is scoped to the whole origin, so logging in once at /admin/login covers draft URLs and Lib\Access-gated pages too.

    + +

    Templates can read the admin_auth_enabled Twig global (it mirrors the config flag) — admin/index.twig uses it to show the "Admin users" and "Logout" links only when the feature is on. It's a display flag only; enforcement never depends on Twig.

    Logging out

    -

    HTTP Basic Auth has no real server-side logout — the browser just keeps resending the same cached credentials on every request to that realm. Visiting /admin/logout works around this: AdminAuth::logout() always issues a fresh 401 challenge, regardless of what credentials were sent, which makes the browser discard what it had cached and prompt again the next time /admin is visited. Credentials themselves aren't invalidated server-side (there's nothing to invalidate — it's just a password check on every request), so this is a client-side-only logout, same as any Basic Auth site. The "Logout" link only appears on /admin when admin_auth_enabled is true (i.e. a password is actually set).

    +

    /admin/logout is a real server-side logout now (its Basic Auth predecessor could only trick the browser into forgetting cached credentials with a fresh 401): a POST — with a small GET confirm form, same shape as /admin/clear-cache — that drops the logged-in user id from the session, regenerates the session id, and redirects to the login form. It's deliberately not logout-on-GET: sidecars must stay side-effect-free on GET, both as ordinary HTTP hygiene and because the {{ icons.search() }}content index's crawl invokes every page's sidecar the way a real GET would — a logout-on-GET would end the crawling admin's own session the moment a lazy reindex rendered this page.

    What this is (and isn't)

    -

    This is HTTP Basic Auth against a single username/password pair in config — no sessions, no user table, no password reset, no multiple accounts. It's a deliberate stopgap: see novaconium/ISSUES.md's "Admin login & user management" entry for the planned real multi-user system (backed by SQLite, with proper sessions). That feature will replace this mechanism, not layer on top of it. Until then, this is enough to keep the general public out of /admin on a production site.

    - -

    Basic Auth credentials are sent base64-encoded on every request (not encrypted) — always serve /admin over HTTPS in production, same as any password-protected page.

    +

    This is authentication plus a deliberately small authorization model: two roles and one group label per user, matched by {{ icons.lock() }}Lib\Access rules in sidecars — no permissions matrix, no role hierarchy, no per-admin capability flags. Registration is admin-driven only; there's no self-serve sign-up form. Sessions are PHP's native ones via Lib\Session, with the same cookie hardening it always applies (httponly, SameSite=Lax, secure on HTTPS). As with any password form, serve /admin over HTTPS in production.

    {% endblock %} diff --git a/novaconium/pages/admin/docs/caching/index.twig b/novaconium/pages/admin/docs/caching/index.twig index 365df3a..a5ae2f8 100644 --- a/novaconium/pages/admin/docs/caching/index.twig +++ b/novaconium/pages/admin/docs/caching/index.twig @@ -13,13 +13,13 @@

    If a page has no sidecar, its rendered HTML is written to public/cache/<path>/index.html after the first request. .htaccess checks for that file before PHP ever runs, so repeat visits are served straight by Apache with zero PHP/Twig overhead. Pages with a sidecar are never cached this way, since their output can vary per request.

    -

    Two kinds of route are excluded from the cache unconditionally, regardless of whether they have a sidecar: every {{ icons.lock() }}draft page and every /admin/* route. Both are gated by {{ icons.lock() }}HTTP Basic Auth, and a cached copy would bypass that check entirely — .htaccess serves a cached file before PHP (and therefore any auth check) ever runs, so a cached admin or draft page would be served to anyone, unauthenticated, forever after the first authenticated view. See {{ icons.lock() }}Draft pages for the full write-up.

    +

    Two kinds of route are excluded from the cache unconditionally, regardless of whether they have a sidecar: every {{ icons.lock() }}draft page and every /admin/* route. Both are gated by the {{ icons.lock() }}admin login, and a cached copy would bypass that check entirely — .htaccess serves a cached file before PHP (and therefore any auth check) ever runs, so a cached admin or draft page would be served to anyone, unauthenticated, forever after the first authenticated view. See {{ icons.lock() }}Draft pages for the full write-up.

    To force a single page to re-render, delete its file under public/cache/. To clear everything at once, there are two equivalent options:

    • CLI: php novaconium/bin/clear-cache.php — a standalone script for deploys, cron jobs, or anywhere you'd rather not go through a browser. Prints Cache cleared. and exits.
      • -
    • Web: /admin/clear-cache — a POST form under /admin, covered by the same HTTP Basic Auth gate as the rest of /admin/* once a password is set.
      • +
    • Web: /admin/clear-cache — a POST form under /admin, covered by the same admin login gate as the rest of /admin/* once admin auth is enabled.

    Both end up calling the same underlying Cache::clear() — see /admin/docs/config's "For developers: using Cache.php directly" section for how each entry point constructs it. Clearing the cache only deletes the generated static HTML; it doesn't affect App/pages/ or any other source. Any project change that should show up on an already-cached page — a new site_name, a new Sass color, a new admin toggle — needs a cache clear before it's visible, since the old index.html would otherwise keep being served as-is.

    diff --git a/novaconium/pages/admin/docs/config/index.twig b/novaconium/pages/admin/docs/config/index.twig index 7f3c7a2..f655415 100644 --- a/novaconium/pages/admin/docs/config/index.twig +++ b/novaconium/pages/admin/docs/config/index.twig @@ -9,7 +9,7 @@ {% block docs_content %}

    Configuration

    -

    novaconium/config.php holds the framework defaults — pages_dirs, cache_dir, debug, site_name, matomo_url, matomo_site_id, admin_username, admin_password_hash, db_connections, draft_routes — and is not meant to be edited per-project, same as everything else under novaconium/.

    +

    novaconium/config.php holds the framework defaults — pages_dirs, cache_dir, debug, site_name, matomo_url, matomo_site_id, admin_auth_enabled, db_connections, draft_routes — and is not meant to be edited per-project, same as everything else under novaconium/.

    App/config.php ships with the skeleton as an empty, commented placeholder — uncomment (or add) whichever keys you want to change, returning an array of just those:

    @@ -37,11 +37,11 @@ return [

    Admin authentication

    -

    admin_username / admin_password_hash gate every /admin/* route behind HTTP Basic Auth — see Admin authentication for the full write-up. Both are set via App/config.php; leaving admin_password_hash empty (the default) disables the gate.

    +

    admin_auth_enabled (default false) gates every /admin/* route behind a session login against the users table — see Admin authentication for the full write-up, including roles (the first user is the admin; the rest are registered) and how the first user gets created. The same flag powers Access control (Lib\Access) for member/group-gated content. When left off, /admin/* is open, the login/users routes 404, and Access::require() allows everything.

    Draft pages

    -

    draft_routes (default []) is a list of routes only an authenticated admin can see — everyone else gets a plain 404. Requires admin_password_hash above to be set to actually gate anything. See Draft pages for the full write-up, including why a cached draft page would be a security problem and how that's avoided.

    +

    draft_routes (default []) is a list of routes only an authenticated admin can see — everyone else gets a plain 404. Requires admin_auth_enabled above (and at least one user) to actually gate anything. See Draft pages for the full write-up, including why a cached draft page would be a security problem and how that's avoided.

    For developers: using Cache.php directly

    diff --git a/novaconium/pages/admin/docs/drafts/index.twig b/novaconium/pages/admin/docs/drafts/index.twig index 27b398f..4b083d1 100644 --- a/novaconium/pages/admin/docs/drafts/index.twig +++ b/novaconium/pages/admin/docs/drafts/index.twig @@ -16,18 +16,17 @@ 
    <?php
 // App/config.php
 return [
-    'admin_username'      => 'admin',
-    'admin_password_hash' => '$2y$10$...',
-    'draft_routes'        => ['blog/upcoming-post'],
+    'admin_auth_enabled' => true,
+    'draft_routes'       => ['blog/upcoming-post'],
 ];

    Each entry matches the same path format {{ icons.link() }}Routing resolves internally — no leading slash, directory segments joined with / (e.g. App/pages/blog/upcoming-post/ is listed as 'blog/upcoming-post').

    Not a login prompt

    -

    An unauthenticated visitor to a draft route gets the site's normal 404 page — not a 401 Basic Auth challenge like /admin/* gives. This is deliberate: prompting for a login would itself reveal that something is gated at that URL. A draft is indistinguishable from a URL that was never routable in the first place.

    +

    An unauthenticated visitor to a draft route gets the site's normal 404 page — not a redirect to the login form like /admin/* gives. This is deliberate: bouncing to a login would itself reveal that something is gated at that URL. A draft is indistinguishable from a URL that was never routable in the first place.

    -

    There's no separate login flow for drafts, and none is needed — AdminAuth::isAuthenticated() (the same credential check {{ icons.lock() }}Admin authentication's requireLogin() uses) is reused directly. In practice, an admin authenticates once by visiting /admin and entering credentials there; HTTP Basic Auth credentials are scoped to the whole origin/realm, not a single path, so the browser then resends those same credentials automatically on later requests to a draft URL too, without a second prompt.

    +

    There's no separate login flow for drafts, and none is needed — AdminAuth::isAdmin() (the same check {{ icons.lock() }}Admin authentication's admin gate uses) is reused directly, so drafts are admin-only: a logged-in registered user gets the same 404 as everyone else (previewing unpublished work is a site-running privilege, not a membership perk — use {{ icons.lock() }}Lib\Access for members-only content). In practice, an admin logs in once at /admin/login; the session cookie is scoped to the whole origin, not a single path, so it covers later requests to a draft URL too. With admin_auth_enabled left off (or while no users exist yet), drafts are open to everyone, consistent with the rest of /admin/*.

    The caching interaction

    diff --git a/novaconium/pages/admin/docs/getting-started/index.twig b/novaconium/pages/admin/docs/getting-started/index.twig index 0fe505c..938df8f 100644 --- a/novaconium/pages/admin/docs/getting-started/index.twig +++ b/novaconium/pages/admin/docs/getting-started/index.twig @@ -9,7 +9,7 @@ {% block docs_content %}

    Getting started

    -

    Requirements: PHP 8.1+ (uses readonly constructor-promoted properties) and, for production, Apache with mod_rewrite and AllowOverride All. The Database/Content index features are optional and off by default — see Overview for the extensions they need (pdo_sqlite, optionally pdo_mysql/FTS5) if you turn them on.

    +

    Requirements: PHP 8.1+ (uses readonly constructor-promoted properties) and, for production, Apache with mod_rewrite and AllowOverride All. The Database/Content index/Admin authentication features are optional and off by default — see Overview for the extensions they need (pdo_sqlite, optionally pdo_mysql/FTS5) if you turn them on.

    Run it locally (no Apache needed)

    diff --git a/novaconium/pages/admin/docs/index.twig b/novaconium/pages/admin/docs/index.twig index b01e51d..cda329a 100644 --- a/novaconium/pages/admin/docs/index.twig +++ b/novaconium/pages/admin/docs/index.twig @@ -38,7 +38,8 @@
  • {{ icons.search() }}Content index — the shared crawler behind /sitemap.xml, /search, and blog tag browsing. Off by default.
  • {{ icons.sitemap() }}XML sitemap — per-page changefreq/priority, what's included, and submitting it to search engines.
  • {{ icons.rss() }}RSS feeds — Lib\Rss, building one feed or several for any content collection.
    • -
  • {{ icons.lock() }}Admin authentication — gate /admin/* behind HTTP Basic Auth, reusable for any future admin page.
    • +
  • {{ icons.lock() }}Admin authentication — gate /admin/* behind a session login, with admin/registered roles, groups, and user management.
    • +
  • {{ icons.lock() }}Access control — assign a page or section to a user or group from its sidecar with Lib\Access; public by default, static pages always public.
  • {{ icons.lock() }}Draft pages — let an admin preview a page before the public can see it, reusing the same auth check.
  • {{ icons.book() }}Layouts — pages and layouts are overridable, just like Lib\.
  • {{ icons.book() }}Static caching — how sidecar-less pages get served as static HTML.
    • diff --git a/novaconium/pages/admin/docs/libraries/index.twig b/novaconium/pages/admin/docs/libraries/index.twig index 501b94d..1399db4 100644 --- a/novaconium/pages/admin/docs/libraries/index.twig +++ b/novaconium/pages/admin/docs/libraries/index.twig @@ -26,5 +26,9 @@
  • Lib\Validate — the lower-level validation primitives FormValidator calls into (isEmail(), minLength()/maxLength(), isMatch(), isPhone(), isPostalCode()/isZipCode()) — call these directly from a sidecar when you just need a validated/normalized value back rather than an accumulated field-error. See Sidecars' "Spam prevention" section.
  • Lib\Input — a cleaning accessor for $_POST/$_GET (Input::post()/Input::get()), used by every sidecar instead of the superglobals directly. Defense-in-depth against HTML/script injection, not a defense against SQL injection — see Sidecars' "Form security" section for the full caveat.
  • Lib\Csrf — standalone session-token CSRF protection (Csrf::token()/::verify()), called directly from a sidecar rather than through FormValidator. See Sidecars' "Form security" section.
    • +
  • Lib\Db — the thin no-ORM PDO wrapper behind everything database-backed here. See Database.
    • +
  • Lib\Session — native PHP sessions with a consistent get/set/flash API. See Session.
    • +
  • Lib\Access — sidecar-level access control: assign a page to a user or group (Access::require('group:members')). See Access control.
    • +
  • Lib\Rss — a generic RSS 2.0 envelope builder. See RSS feeds.
    • {% endblock %} diff --git a/novaconium/pages/admin/docs/project-layout/index.twig b/novaconium/pages/admin/docs/project-layout/index.twig index d8d6f8f..e471670 100644 --- a/novaconium/pages/admin/docs/project-layout/index.twig +++ b/novaconium/pages/admin/docs/project-layout/index.twig @@ -44,9 +44,8 @@ novaconium/ the framework itself — boilerplate, not meant to be edite
    1. Requires novaconium/autoload.php, registering the Twig\/App\/Lib\ class autoloader (see Libraries) before anything below tries to instantiate a class.
    2. Requires novaconium/config.php, then shallow-merges App/config.php over it if that file exists — see Configuration.
      3. -
    3. Special-cases /admin/logout directly against the request path — see Admin authentication — since it isn't a real page for the router to find.
    4. Constructs a Router (novaconium/src/Router.php) and calls resolve() to turn the URL into a Route (novaconium/src/Route.php) — see Routing.
      5. -
    5. If the resolved route is under admin/admin/*, calls AdminAuth::requireLogin() (novaconium/src/AdminAuth.php), reading that same Route.
      6. +
    6. If the resolved route is under admin/admin/* (except admin/login itself), calls AdminAuth::requireLogin() (novaconium/src/AdminAuth.php), reading that same Route.
    7. Constructs a Cache (novaconium/src/Cache.php) and a Renderer (novaconium/src/Renderer.php), then calls renderNotFound() or render($route, ...) depending on $route->found — see Sidecars for what happens inside Renderer itself (running the matched directory's index.php, if any; resolving the nearest layout; rendering index.twig; writing the static cache for sidecar-less pages).
    diff --git a/novaconium/pages/admin/docs/routing/index.twig b/novaconium/pages/admin/docs/routing/index.twig index 78b759f..83ef350 100644 --- a/novaconium/pages/admin/docs/routing/index.twig +++ b/novaconium/pages/admin/docs/routing/index.twig @@ -37,9 +37,8 @@
    1. Config loads (framework defaults + optional App/config.php override).
      2. -
    2. /admin/logout is special-cased directly against the raw request path, before routing even runs — it isn't a real page, so there'd be no Route for it anyway.
    3. Router::resolve() runs and returns a Route — this is the only place a Route gets created.
      4. -
    4. If $route->dir is under admin/admin/*, AdminAuth::requireLogin() gates it — reading $route->dir directly off the value object Router handed back.
      5. +
    5. If $route->dir is under admin/admin/* (except admin/login, which must stay reachable logged-out), AdminAuth::requireLogin() gates it — reading $route->dir directly off the value object Router handed back.
    6. Renderer takes over, also just reading the same Route: renderNotFound() if $route->found is false, otherwise render($route, ...) — using $route->dir to find the sidecar/layout/template and $route->params as template context.
    diff --git a/novaconium/pages/admin/docs/session/index.twig b/novaconium/pages/admin/docs/session/index.twig index ab72fa9..cc1dd2f 100644 --- a/novaconium/pages/admin/docs/session/index.twig +++ b/novaconium/pages/admin/docs/session/index.twig @@ -24,6 +24,8 @@ Session::remove('user_id');

    The session is started lazily — nothing calls session_start() until the first real call to any Session method, so a page that never touches Session never gets a session cookie. {{ icons.book() }}Lib\Csrf uses the exact same lazy-start mechanism to run its own session-token CSRF protection — both classes can touch the same native session in the same request without conflict, since session_start() is only ever actually called once (PHP no-ops a second call).

    +

    Session::regenerate() swaps the session id for a fresh one while keeping the session's data — call it on any privilege change, so a session id an attacker planted or observed before the change is worthless after it (session fixation). {{ icons.lock() }}Admin authentication does exactly this on login and logout.

    +

    Flash data

    A flashed value is readable on exactly the next request, then gone — useful for post/redirect/GET flows (a "message sent" banner after a redirect) without a query-string flag like ?sent=1:

    diff --git a/novaconium/pages/admin/docs/sidecars/index.twig b/novaconium/pages/admin/docs/sidecars/index.twig index 88a373f..ad9988a 100644 --- a/novaconium/pages/admin/docs/sidecars/index.twig +++ b/novaconium/pages/admin/docs/sidecars/index.twig @@ -65,7 +65,9 @@ $all = Input::post(); // the whole cleaned $_POST array<

    This is not SQL-injection protection. The cleaning Input does (trim + strip tags, via Lib\Validate::clean(), plus null-byte stripping) is defense-in-depth against HTML/script injection in output contexts — Twig already autoescapes {{ '{{ }}' }} output by default (see novaconium/src/Renderer.php), so this is a second layer, not the only one. No string transform makes arbitrary input safe to concatenate into a SQL query; the real defense is parameterized queries. Lib\Db's query() method uses PDO prepared statements exclusively for exactly this reason. Input deliberately has no sqlSafe()-style method, since a method implying "cleaned = safe to interpolate into SQL" would be actively dangerous.

    -

    One documented exception: a field that needs an exact, unmodified value — a password about to be hashed, say — should read $_POST directly instead of going through Input::post(). Cleaning would silently strip characters like </> before hashing, producing a hash that doesn't match what's actually typed later. See novaconium/pages/admin/password-hash/index.php for the one place this framework does that on purpose.

    +

    One documented exception: a field that needs an exact, unmodified value — a password about to be hashed or verified, say — should read $_POST directly instead of going through Input::post(). Cleaning would silently strip characters like </> before hashing, producing a hash that doesn't match what's actually typed later (or failing a login whose password actually matches). See the password fields in novaconium/pages/admin/users/index.php and novaconium/pages/admin/login/index.php for the places this framework does that on purpose.

    + +

    A sidecar is also where a page gets assigned to a user or group: one Lib\Access call at the top, returning its Response when access is denied — see Access control.

    CSRF protection

    @@ -140,7 +142,7 @@ $phone = Validate::isPhone($old['phone']); // '5551234567' or falseAll three classes live under novaconium/lib/ as framework defaults — like any other Lib\ class, a project can override any of them by dropping a same-named file in App/lib/ (see Libraries).

    -

    Copy-paste starter: a sidecar, three ways

    +

    Copy-paste starter: a sidecar, four ways

    Drop this in as App/pages/example/index.php (next to an App/pages/example/index.twig using the SEO starter template) and delete whichever example you don't need:

    @@ -166,9 +168,26 @@ return [ // // ob_start(); // phpinfo(); -// return Response::html(ob_get_clean());{% endverbatim %} +// return Response::html(ob_get_clean()); -

    Only one of the three returns in a real sidecar ever runs, obviously — pick one, or branch between them with an if. The IP example works with or without a sidecar-only page (no index.twig); the phpinfo() example needs no index.twig at all, since Response::html() bypasses Twig — see the JSON-only example above for another sidecar-only page.

    +// 4. Require a login — gate the page to a group, a user, or any +// logged-in account before doing anything else. Access::require() +// returns null when the visitor may proceed, or a ready-made Response +// (a login redirect that comes back here afterwards, or a 404 for the +// wrong account) for you to return as-is. Needs admin_auth_enabled and +// at least one user — see /admin/docs/access-control for the rules and +// /admin/docs/admin-auth for accounts and groups. +// use Lib\Access; +// +// if ($denied = Access::require('group:members')) { +// return $denied; +// } +// +// return [ +// 'message' => 'Hello, member!', +// ];{% endverbatim %} + +

    Only one of the numbered returns in a real sidecar ever runs, obviously — pick one, or branch between them with an if. The IP example works with or without a sidecar-only page (no index.twig); the phpinfo() example needs no index.twig at all, since Response::html() bypasses Twig — see the JSON-only example above for another sidecar-only page. The login gate in example 4 isn't really an alternative to the other three — it's a first line that composes with any of them: gate first, then return whatever the page normally would. Swap the rule for Access::require('user:bob'), several rules (any one grants access), or no rules at all for "anyone logged in"; admins always pass.

    Never ship phpinfo() to production — it dumps environment variables, file paths, loaded extensions, and configuration values that are useful to an attacker mapping your server. Delete the page after you're done with it, or at minimum gate it behind admin authentication the same way /admin/* already is, so it's never reachable by the public.

    diff --git a/novaconium/pages/admin/index.twig b/novaconium/pages/admin/index.twig index 002a59e..54f2ee5 100644 --- a/novaconium/pages/admin/index.twig +++ b/novaconium/pages/admin/index.twig @@ -14,7 +14,7 @@
    diff --git a/novaconium/pages/admin/login/index.php b/novaconium/pages/admin/login/index.php new file mode 100644 index 0000000..83c8d0d --- /dev/null +++ b/novaconium/pages/admin/login/index.php @@ -0,0 +1,108 @@ + before password_verify(), + // failing a login the password actually matches. Same documented + // exception /admin/users makes when hashing — see + // /admin/docs/sidecars' "Form security" section. + $ok = AdminAuth::attempt( + (string) Input::post('username', ''), + (string) ($_POST['password'] ?? '') + ); + + if ($ok) { + return Response::redirect($return ?? $defaultTarget(), 303); + } + + Session::flash('login_error', 'Wrong username or password.'); + + return Response::redirect($failureUrl, 303); +} + +// Already logged in (or the gate is open because no users exist yet) — +// the form is pointless, move along. +if (AdminAuth::isLoggedIn(true)) { + return Response::redirect($defaultTarget(), 303); +} + +return [ + 'return' => $sanitizeReturn(Input::get('return')), + 'error' => Session::getFlash('login_error'), + 'notice' => Session::getFlash('admin_notice'), + 'csrfField' => Csrf::fieldName(), + 'csrfToken' => Csrf::token(), +]; diff --git a/novaconium/pages/admin/login/index.twig b/novaconium/pages/admin/login/index.twig new file mode 100644 index 0000000..75cbed7 --- /dev/null +++ b/novaconium/pages/admin/login/index.twig @@ -0,0 +1,37 @@ +{% extends layout %} + +{% import '_layout/icons.twig' as icons %} + +{% block title %}Log in{% endblock %} + +{% block description %}Log in to your account.{% endblock %} + +{% block robots %}noindex, nofollow{% endblock %} + +{% block content %} +
    +

    {{ icons.lock() }}Log in

    + + {% if notice %} +

    {{ notice }}

    + {% endif %} + + {% if error %} +

    {{ error }}

    + {% endif %} + +
    + + {% if return %}{% endif %} +

    +
    + +

    +

    +
    + +

    + +
    +
    +{% endblock %} diff --git a/novaconium/pages/admin/logout/index.php b/novaconium/pages/admin/logout/index.php new file mode 100644 index 0000000..ac98bfe --- /dev/null +++ b/novaconium/pages/admin/logout/index.php @@ -0,0 +1,49 @@ + Input::get('error') === 'security', + 'csrfField' => Csrf::fieldName(), + 'csrfToken' => Csrf::token(), +]; diff --git a/novaconium/pages/admin/logout/index.twig b/novaconium/pages/admin/logout/index.twig new file mode 100644 index 0000000..56702fc --- /dev/null +++ b/novaconium/pages/admin/logout/index.twig @@ -0,0 +1,23 @@ +{% extends layout %} + +{% import '_layout/icons.twig' as icons %} + +{% block title %}Log out{% endblock %} + +{% block description %}Log out of the admin area.{% endblock %} + +{% block robots %}noindex, nofollow{% endblock %} + +{% block content %} +
    +

    {{ icons.external_link() }}Log out

    +

    Ends your admin session on the server — you'll need to log in again at /admin/login to get back in.

    + {% if securityError %} +

    Your session expired before submitting — please try again.

    + {% endif %} +
    + + +
    +
    +{% endblock %} diff --git a/novaconium/pages/admin/password-hash/index.php b/novaconium/pages/admin/password-hash/index.php deleted file mode 100644 index eba1337..0000000 --- a/novaconium/pages/admin/password-hash/index.php +++ /dev/null @@ -1,38 +0,0 @@ - before hashing, producing a hash that - // doesn't match what's actually typed later at the Basic Auth prompt - // (which does zero sanitization). - $password = $_POST['password'] ?? ''; - - if ($password === '') { - $error = 'Enter a password to hash.'; - } elseif (strlen($password) < 8) { - $error = 'Use at least 8 characters.'; - } else { - // Computed once per request and never stored/logged — the page - // that renders this is the only place it's ever seen. - $hash = password_hash($password, PASSWORD_DEFAULT); - } -} - -return [ - 'hash' => $hash, - 'error' => $error, - 'securityError' => Input::get('error') === 'security', - 'csrfField' => Csrf::fieldName(), - 'csrfToken' => Csrf::token(), -]; diff --git a/novaconium/pages/admin/password-hash/index.twig b/novaconium/pages/admin/password-hash/index.twig deleted file mode 100644 index 1fdb801..0000000 --- a/novaconium/pages/admin/password-hash/index.twig +++ /dev/null @@ -1,42 +0,0 @@ -{% extends layout %} - -{% import '_layout/icons.twig' as icons %} - -{% block title %}Generate admin password hash{% endblock %} -{% block description %}Generate a password_hash() value for admin_password_hash without using the CLI.{% endblock %} -{% block robots %}noindex, nofollow{% endblock %} - -{% block content %} -
    -

    {{ icons.lock() }}Generate admin password hash

    - -

    A browser-based alternative to php -r "echo password_hash('yourpassword', PASSWORD_DEFAULT);". Enter a password, get back the hash App/config.php expects for admin_password_hash — see {{ icons.book() }}Admin authentication. Nothing typed here is stored, logged, or sent anywhere except computed once for this response.

    - -
    - -

    -
    - -

    - -
    - - {% if securityError %} -

    Your session expired before submitting — please try again.

    - {% endif %} - - {% if error %} -

    {{ error }}

    - {% endif %} - - {% if hash %} -

    Add this to App/config.php:

    - 
    <?php
-// App/config.php
-return [
-    'admin_username'      => 'admin',
-    'admin_password_hash' => '{{ hash }}',
-];
    - {% endif %} -
    -{% endblock %} diff --git a/novaconium/pages/admin/users/index.php b/novaconium/pages/admin/users/index.php new file mode 100644 index 0000000..d77e21a --- /dev/null +++ b/novaconium/pages/admin/users/index.php @@ -0,0 +1,201 @@ + (int) Db::query( + "SELECT COUNT(*) FROM users WHERE is_disabled = 0 AND role = 'admin'" +)->fetchColumn(); + +if ($_SERVER['REQUEST_METHOD'] === 'POST') { + if (!Csrf::verify(Input::post('csrf_token'))) { + Session::flash('users_error', 'Your session expired before submitting — please try again.'); + + return Response::redirect('/admin/users', 303); + } + + $action = Input::post('action', ''); + + if ($action === 'create') { + $username = trim((string) Input::post('username', '')); + // Validate::isEmail() returns the normalized (trimmed, lowercased) + // address, or false — stored normalized so the future + // email-verification flow (see novaconium/ISSUES.md) can match + // addresses case-insensitively for free. + $email = Validate::isEmail((string) Input::post('email', '')); + $group = trim((string) Input::post('group', '')); + // Passwords read directly, not via Input::post() — cleaning would + // silently strip characters like < and > before hashing, producing + // a hash that doesn't match what's actually typed at /admin/login + // later. See /admin/docs/sidecars' "Form security" section. + $password = (string) ($_POST['password'] ?? ''); + + $exists = $username !== '' + && (bool) Db::query('SELECT EXISTS(SELECT 1 FROM users WHERE username = ?)', [$username])->fetchColumn(); + $emailExists = $email !== false + && (bool) Db::query('SELECT EXISTS(SELECT 1 FROM users WHERE email = ?)', [$email])->fetchColumn(); + + if ($username === '' || strlen($username) > 64) { + Session::flash('users_error', 'Enter a username (64 characters max).'); + } elseif ($email === false) { + Session::flash('users_error', 'Enter a valid email address.'); + } elseif ($emailExists) { + Session::flash('users_error', 'That email address is already in use.'); + } elseif (strlen($group) > 64) { + Session::flash('users_error', 'Group names are 64 characters max.'); + } elseif ($exists) { + Session::flash('users_error', 'That username is already taken.'); + } elseif (strlen($password) < 8) { + Session::flash('users_error', 'Use a password of at least 8 characters.'); + } else { + // The first user ever created is the admin; everyone after is + // a registered user (optionally in a group) — Lib\Access rules + // decide what content they can see, and /admin/* 404s for + // them. See /admin/docs/admin-auth and + // /admin/docs/access-control. + $wasFirstUser = !AdminAuth::hasUsers(); + $role = $wasFirstUser ? 'admin' : 'registered'; + + Db::query( + 'INSERT INTO users (username, email, password_hash, role, user_group, is_disabled, created_at) VALUES (?, ?, ?, ?, ?, 0, ?)', + [$username, $email, password_hash($password, PASSWORD_DEFAULT), $role, $group, gmdate('Y-m-d\TH:i:s\Z')] + ); + + // Creating the first user is what closes the open setup gate — + // log its creator in as it, or their very next request would + // bounce them to the login form they were just typing into. + if ($wasFirstUser) { + AdminAuth::attempt($username, $password); + } + + Session::flash('users_notice', "User \u{201C}{$username}\u{201D} created."); + } + } elseif ($action === 'disable' || $action === 'enable') { + $id = (int) Input::post('id', '0'); + $target = Db::query('SELECT id, username, role, is_disabled FROM users WHERE id = ?', [$id])->fetch(PDO::FETCH_ASSOC); + + if ($target === false) { + Session::flash('users_error', 'No such user.'); + } elseif ($action === 'disable' && (int) $target['is_disabled'] === 0 && $target['role'] === 'admin' && $activeAdminCount() <= 1) { + Session::flash('users_error', 'Cannot disable the last active admin — that would lock everyone out of /admin.'); + } else { + Db::query('UPDATE users SET is_disabled = ? WHERE id = ?', [$action === 'disable' ? 1 : 0, $id]); + Session::flash('users_notice', sprintf("User \u{201C}%s\u{201D} %sd.", $target['username'], $action)); + } + } elseif ($action === 'role') { + $id = (int) Input::post('id', '0'); + $role = Input::post('role', ''); + $target = Db::query('SELECT id, username, role, is_disabled FROM users WHERE id = ?', [$id])->fetch(PDO::FETCH_ASSOC); + + if ($target === false) { + Session::flash('users_error', 'No such user.'); + } elseif (!in_array($role, ['admin', 'registered'], true)) { + Session::flash('users_error', 'No such role.'); + } elseif ($role === 'registered' && $target['role'] === 'admin' && (int) $target['is_disabled'] === 0 && $activeAdminCount() <= 1) { + Session::flash('users_error', 'Cannot demote the last active admin — that would lock everyone out of /admin.'); + } else { + Db::query('UPDATE users SET role = ? WHERE id = ?', [$role, $id]); + Session::flash('users_notice', "User \u{201C}{$target['username']}\u{201D} is now {$role}."); + } + } elseif ($action === 'delete') { + $id = (int) Input::post('id', '0'); + $target = Db::query('SELECT id, username, role, is_disabled FROM users WHERE id = ?', [$id])->fetch(PDO::FETCH_ASSOC); + + if ($target === false) { + Session::flash('users_error', 'No such user.'); + } elseif ((int) $target['is_disabled'] === 0 && $target['role'] === 'admin' && $activeAdminCount() <= 1) { + Session::flash('users_error', 'Cannot delete the last active admin — that would lock everyone out of /admin.'); + } else { + // A hard delete, not a soft one — is_disabled already covers + // "keep the account but shut it out", so delete is for + // accounts that shouldn't exist at all. Any live session dies + // on its next request (currentUser() re-checks the row). + Db::query('DELETE FROM users WHERE id = ?', [$id]); + Session::flash('users_notice', "User \u{201C}{$target['username']}\u{201D} deleted."); + } + } elseif ($action === 'email') { + $id = (int) Input::post('id', '0'); + $email = Validate::isEmail((string) Input::post('email', '')); + $target = Db::query('SELECT id, username FROM users WHERE id = ?', [$id])->fetch(PDO::FETCH_ASSOC); + $emailExists = $email !== false + && (bool) Db::query('SELECT EXISTS(SELECT 1 FROM users WHERE email = ? AND id != ?)', [$email, $id])->fetchColumn(); + + if ($target === false) { + Session::flash('users_error', 'No such user.'); + } elseif ($email === false) { + Session::flash('users_error', 'Enter a valid email address.'); + } elseif ($emailExists) { + Session::flash('users_error', 'That email address is already in use.'); + } else { + Db::query('UPDATE users SET email = ? WHERE id = ?', [$email, $id]); + Session::flash('users_notice', "Email changed for \u{201C}{$target['username']}\u{201D}."); + } + } elseif ($action === 'group') { + $id = (int) Input::post('id', '0'); + $group = trim((string) Input::post('group', '')); + $target = Db::query('SELECT id, username FROM users WHERE id = ?', [$id])->fetch(PDO::FETCH_ASSOC); + + if ($target === false) { + Session::flash('users_error', 'No such user.'); + } elseif (strlen($group) > 64) { + Session::flash('users_error', 'Group names are 64 characters max.'); + } else { + Db::query('UPDATE users SET user_group = ? WHERE id = ?', [$group, $id]); + Session::flash('users_notice', $group === '' + ? "User \u{201C}{$target['username']}\u{201D} removed from their group." + : "User \u{201C}{$target['username']}\u{201D} assigned to group \u{201C}{$group}\u{201D}."); + } + } elseif ($action === 'password') { + $id = (int) Input::post('id', '0'); + $password = (string) ($_POST['password'] ?? ''); + $target = Db::query('SELECT id, username FROM users WHERE id = ?', [$id])->fetch(PDO::FETCH_ASSOC); + + if ($target === false) { + Session::flash('users_error', 'No such user.'); + } elseif (strlen($password) < 8) { + Session::flash('users_error', 'Use a password of at least 8 characters.'); + } else { + Db::query('UPDATE users SET password_hash = ? WHERE id = ?', [password_hash($password, PASSWORD_DEFAULT), $id]); + Session::flash('users_notice', "Password changed for \u{201C}{$target['username']}\u{201D}."); + } + } + + return Response::redirect('/admin/users', 303); +} + +return [ + 'users' => Db::query('SELECT id, username, email, role, user_group, is_disabled, created_at FROM users ORDER BY username')->fetchAll(PDO::FETCH_ASSOC), + 'currentUserId' => AdminAuth::currentUser()['id'] ?? null, + 'notice' => Session::getFlash('users_notice'), + 'error' => Session::getFlash('users_error'), + 'csrfField' => Csrf::fieldName(), + 'csrfToken' => Csrf::token(), +]; diff --git a/novaconium/pages/admin/users/index.twig b/novaconium/pages/admin/users/index.twig new file mode 100644 index 0000000..0597e3b --- /dev/null +++ b/novaconium/pages/admin/users/index.twig @@ -0,0 +1,145 @@ +{% extends layout %} + +{% import '_layout/icons.twig' as icons %} + +{% block title %}Users{% endblock %} + +{% block description %}Create, disable, and manage user accounts, roles, and groups.{% endblock %} + +{% block robots %}noindex, nofollow{% endblock %} + +{% block content %} +
    +

    {{ icons.users() }}Users

    + +

    Accounts that can log in at /admin/login. The first user created is the admin; everyone after is registered — able to log in and see whatever pages Lib\Access assigns to their account or group (see {{ icons.lock() }}Access control), but not the admin area. A disabled user can't log in, and any session they already had is locked out on its next request.

    + + {% if notice %} +

    {{ notice }}

    + {% endif %} + + {% if error %} +

    {{ error }}

    + {% endif %} + + {% if users is empty %} +

    No users exist yet, so the admin area is open to anyone who can reach it. Create the first user below to close the gate — it becomes the admin account, and you'll be logged in as it automatically.

    + {% else %} + + + + + + + + + + + + + + {% for user in users %} + + + + + + + + + + {% endfor %} + +
    UsernameEmailRoleGroupCreatedStatusActions
    {{ user.username }}{% if user.id == currentUserId %} (you){% endif %}{{ user.email }}{{ user.role == 'admin' ? 'Admin' : 'Registered' }}{{ user.user_group ?: '—' }}{{ user.created_at }}{{ user.is_disabled ? 'Disabled' : 'Active' }} +
    + + + + +
    +
    + + + + + +
    +
    + Change email +
    + + + +

    +
    + +

    + +
    +
    +
    + Change group +
    + + + +

    +
    + +

    + +
    +
    +
    + Change password +
    + + + +

    +
    + +

    + +
    +
    +
    + Delete +
    + + + +

    Permanently removes {{ user.username }} — there's no undo. To shut an account out but keep it, use Disable instead.

    + +
    +
    +
    + {% endif %} + +

    Create a user

    + +
    + + +

    +
    + +

    +

    +
    + +

    +

    +
    + +

    + {% if users is not empty %} +

    +
    + +

    + {% endif %} + +
    +
    +{% endblock %} diff --git a/novaconium/src/AdminAuth.php b/novaconium/src/AdminAuth.php index 54ebf8d..0194149 100644 --- a/novaconium/src/AdminAuth.php +++ b/novaconium/src/AdminAuth.php @@ -2,76 +2,195 @@ namespace App; +use Lib\Db; +use Lib\Session; +use PDO; + /** - * Reusable HTTP Basic Auth gate for /admin/*. A single check, called once - * from bootstrap.php for any route under admin/, so protecting a new admin - * page (clear-cache today, anything future) needs no per-page wiring. + * Session-based login backed by the `users` table + * (novaconium/migrations/0002_create_users.sql) on Lib\Db's default + * connection. This replaced the single-user HTTP Basic Auth stopgap that + * originally shipped under this same class name — same call sites + * (bootstrap.php's admin gate and draft gate), new mechanism, per the + * "replace it, don't layer on top of it" plan in novaconium/ISSUES.md. * - * Deliberately not a full user system — no sessions, no user table, no - * password reset. It's a stopgap until proper multi-user admin login - * (see novaconium/ISSUES.md) lands; that feature will replace this, not extend it. + * Two roles: 'admin' (full /admin/* access, sees drafts, passes every + * Lib\Access rule) and 'registered' (can log in, and sees whatever + * content Lib\Access grants their account or their group — see + * /admin/docs/access-control — but /admin/* 404s for them). The first + * user ever created is the admin; users created after that are + * registered, each optionally assigned one group (users.user_group, a + * plain text label — no groups table). * - * Note: Lib\Csrf (unrelated to login state here) does start a native PHP - * session when a form calls it — so "no sessions" above is specifically - * about this class's own login check, not a framework-wide guarantee. + * Gated by config['admin_auth_enabled'] (default false — same off-by- + * default posture as the content index, and for the same reason: this + * depends on SQLite, a real dependency plenty of sites won't want). + * Every method that touches Lib\Db is only reachable when the flag is + * true, so a site that never enables it never gets a data/ database file + * created just because this class exists. + * + * Bootstrap posture while enabled but with zero users yet: open access, + * so the first user can be created at /admin/users (or with + * `php novaconium/bin/create-admin-user.php`) — the same window the old + * Basic Auth had between deciding to enable it and pasting a hash into + * App/config.php. Enabling the flag alone protects nothing; creating the + * first user is what closes the gate. */ final class AdminAuth { + private const SESSION_KEY = '_admin_user_id'; + /** - * Exits with a 401 challenge if the request isn't authenticated. - * A no-op (auth disabled) when $passwordHash is empty. + * Per-request memo for currentUser() — static state never survives + * across requests (same guarantee Lib\Session's flash swap relies on), + * so this only saves repeat lookups within one request. + * + * @var array|null */ - public static function requireLogin(string $username, string $passwordHash): void + private static ?array $currentUser = null; + + private static bool $currentUserLoaded = false; + + /** + * Redirects to /admin/login and exits if nobody is logged in. A no-op + * (open access) when $enabled is false, or while no users exist yet + * (see the class docblock). bootstrap.php calls this for every + * /admin/* route except admin/login itself — which must stay + * reachable logged-out, or the redirect would loop — and then + * separately 404s admin routes for logged-in non-admins (a registered + * user is *authenticated*, so bouncing them back to the login form + * would be a lie; what they lack is the admin role). + */ + public static function requireLogin(bool $enabled): void { - if (self::isAuthenticated($username, $passwordHash)) { + if (self::isLoggedIn($enabled)) { return; } - header('WWW-Authenticate: Basic realm="Admin"'); - http_response_code(401); - header('Content-Type: text/plain; charset=utf-8'); - echo "401 Unauthorized\n"; + http_response_code(303); + header('Location: /admin/login'); exit; } /** - * The credential check on its own, with no response side effects — - * reused by requireLogin() above (401 challenge on failure) and by - * novaconium/bootstrap.php's draft-page gate (see /admin/docs/drafts), - * which needs a *different* response on failure: a plain 404, not a - * login prompt, so an unauthenticated visitor can't tell a draft - * exists at all. Returns true (open access) when $passwordHash is - * empty, matching requireLogin()'s existing no-op-when-unset posture — - * a draft behaves like the rest of /admin/*: wide open until a - * password is configured, gated once one is. + * Whether the request has any logged-in user at all, admin or + * registered. Returns true (open access) when $enabled is false or no + * users exist yet. */ - public static function isAuthenticated(string $username, string $passwordHash): bool + public static function isLoggedIn(bool $enabled): bool { - if ($passwordHash === '') { + if (!$enabled || !self::hasUsers()) { return true; } - $providedUser = $_SERVER['PHP_AUTH_USER'] ?? null; - $providedPass = $_SERVER['PHP_AUTH_PW'] ?? null; - - return $providedUser === $username - && $providedPass !== null - && password_verify($providedPass, $passwordHash); + return self::currentUser() !== null; } /** - * HTTP Basic Auth has no real server-side "log out" — the browser just - * keeps resending the cached credentials. The standard workaround: always - * issue a fresh 401 challenge here regardless of what was sent, which - * makes the browser discard the credentials it had cached for this realm - * and prompt again next time /admin is visited. + * Whether the request is by a logged-in admin, with no response side + * effects — the check behind /admin/* and the draft-page gate in + * novaconium/bootstrap.php (see /admin/docs/drafts), which reacts to + * failure with a plain 404, not a login redirect, so an + * unauthenticated visitor can't tell a draft exists at all. Returns + * true (open access) when $enabled is false or no users exist yet, so + * a draft behaves consistently with the rest of /admin/*: wide open + * until the feature is enabled and a first user exists, gated after + * that. + */ + public static function isAdmin(bool $enabled): bool + { + if (!$enabled || !self::hasUsers()) { + return true; + } + + $user = self::currentUser(); + + return $user !== null && $user['role'] === 'admin'; + } + + /** + * Verifies a username/password against the users table and, on + * success, logs the session in. Disabled users fail exactly like a + * wrong password — the response never distinguishes "no such user", + * "disabled", and "bad password". + */ + public static function attempt(string $username, string $password): bool + { + if ($username === '' || $password === '') { + return false; + } + + $user = Db::query( + 'SELECT id, username, email, password_hash, role, user_group, is_disabled FROM users WHERE username = ?', + [$username] + )->fetch(PDO::FETCH_ASSOC); + + if ($user === false || (int) $user['is_disabled'] === 1 || !password_verify($password, $user['password_hash'])) { + return false; + } + + // Fresh session id on login so a pre-login session id (which an + // attacker could have planted or observed) never becomes an + // authenticated one — see Session::regenerate(). + Session::regenerate(); + Session::set(self::SESSION_KEY, (int) $user['id']); + + unset($user['password_hash']); + self::$currentUser = $user; + self::$currentUserLoaded = true; + + return true; + } + + /** + * A real server-side logout (unlike the Basic Auth predecessor's + * 401-challenge trick): drop the logged-in user id from the session + * and regenerate the session id. */ public static function logout(): void { - header('WWW-Authenticate: Basic realm="Admin"'); - http_response_code(401); - header('Content-Type: text/html; charset=utf-8'); - echo '

    You have been logged out. Return home.

    '; - exit; + Session::remove(self::SESSION_KEY); + Session::regenerate(); + + self::$currentUser = null; + self::$currentUserLoaded = true; + } + + /** + * The logged-in user's row (id/username/email/role/user_group/ + * is_disabled — never the password hash), or null. Re-checked against + * the users table on every request, not just at login, so disabling + * or deleting a user locks their existing session out on their very + * next request — no "still logged in until the session expires" + * window. + * + * @return array|null + */ + public static function currentUser(): ?array + { + if (self::$currentUserLoaded) { + return self::$currentUser; + } + + self::$currentUserLoaded = true; + + $userId = Session::get(self::SESSION_KEY); + if (!is_int($userId)) { + return null; + } + + $user = Db::query( + 'SELECT id, username, email, role, user_group, is_disabled FROM users WHERE id = ? AND is_disabled = 0', + [$userId] + )->fetch(PDO::FETCH_ASSOC); + + self::$currentUser = $user === false ? null : $user; + + return self::$currentUser; + } + + public static function hasUsers(): bool + { + return (bool) Db::query('SELECT EXISTS(SELECT 1 FROM users)')->fetchColumn(); } }