atheos-blog-lxc/docs/known-issues.md

Known Issues & Patches

Upstream Atheos is an actively-moving project with no releases, and its plugin market ships plugins that are ports from Codiad (Atheos's predecessor). Two of those plugins use APIs that Atheos has since removed or changed. This file records what we hit, what we changed, and why the fix is done the way it is.

Pinned Atheos commit: f90cd1806dbe0e25673a77e27390e8b1a240c3f6 (build 611).

---

1. 🔴 Deleting any file or folder was broken — GLOB_BRACE does not exist on musl

Symptom: removing the Terminal plugin from the market cycled forever in the UI (never completed, never errored). Deleting a file or folder in the editor was broken by the same cause.

Root cause — a glibc-only constant referenced on musl. traits/helpers.php::rDelete():

$files = glob($target . "{*,.[!.]*,..?*}", GLOB_BRACE|GLOB_MARK);

GLOB_BRACE is a glibc extension. Alpine uses musl, where the constant is undefined — and touching an undefined constant is a fatal error in PHP 8 (a warning in older versions):

PHP Fatal error: Uncaught Error: Undefined constant "GLOB_BRACE"
in /var/www/atheos/traits/helpers.php:138
#0 components/market/class.market.php(178): Common::rDelete()
#1 components/market/controller.php(46): Market->remove()

Because the fatal kills the request before Common::send(200), the front end never receives a settle response — so the UI spins indefinitely. A hang, not an error.

Blast radius — measured, two call sites:

Caller	What breaks
components/market/class.market.php:178	removing a plugin from the market
components/filetree/class.filetree.php:59	deleting any file or folder in the editor

The second is core editor functionality, so this is not a plugin bug — installing the Terminal plugin is merely what made it visible. Verified directly: with the original code, rDelete() fatals and the target is left on disk.

Fix applied (patches/helpers-rDelete-GLOB_BRACE.diff) — expand the brace pattern by hand when GLOB_BRACE is absent, keeping upstream's exact behaviour where it is defined:

if (defined("GLOB_BRACE")) {
    $files = glob($target . "{*,.[!.]*,..?*}", GLOB_BRACE | GLOB_MARK);
} else {
    $files = array_merge(
        glob($target . "/*",        GLOB_MARK) ?: [],
        glob($target . "/.[!.]*",   GLOB_MARK) ?: [],
        glob($target . "/..?*",     GLOB_MARK) ?: []
    );
}

The three patterns are precisely what the brace expansion produces (*, dotfiles, and ./..-like names), so the directory listing is equivalent.

Verified — php83 -l clean, then a real deletion of a tree containing nested dirs and two dotfiles:

entries before: 10
rDelete() returned: true
exists after: gone (OK)
single file: rDelete=true exists=gone (OK)

Upstream has NOT fixed this — the same line is still in main (checked directly), so it cannot be resolved by updating Atheos. Re-apply this patch after any update (scripts/update-atheos.sh).

Consequence for the platform choice: this is the real cost of Alpine. A glibc-based image (Debian/Ubuntu) would not have hit it. It is patchable in one place, so Alpine stays — but it is worth knowing that GLOB_BRACE is the kind of thing musl breaks.

---

2. 🔴 Plugin market: the Terminal plugin does not work as shipped

Symptom: installed the Terminal plugin from the market; it failed / did not function.

Root cause — a removed API. plugins/Terminal/terminal.php calls Common::execute(...), which no longer exists in Atheos (it was renamed):

plugin calls : Common::execute(...)      ->  MISSING
available    : Common::raw_execute(...)  ->  returns ["code" => int, "output" => array]
                Common::safe_execute(...)

The plugin's header says it is a port of Fluidbyte/Codiad-Terminal, so it targets the old API. Its return-shape assumption is also stale (the old execute() returned text; raw_execute() returns output as an array).

Fix applied (patches/Terminal-terminal.php.patched):

-  $output = Common::execute("pwd");
+  $output = Common::raw_execute("pwd");
-  $_SESSION["activeDir"] = array([$_SESSION["project"]] => $output["text"]);
+  $_SESSION["activeDir"] = array([$_SESSION["project"]] => implode("\n", (array)$output["output"]));

-  $output = Common::execute($cmd);
-  return $output["text"];
+  $output = Common::raw_execute($cmd);
+  return implode("\n", (array)$output["output"]);

Verified against the real method (php83 -l clean; both call patterns exercised):

Call	Result
raw_execute("pwd")	code=0, output=["/root",""]
raw_execute("echo ...")	code=0, returns the text
after chdir to the repo	returns /var/www/atheos/workspace/blog — so the terminal opens in the blog

Re-apply after an Atheos update — scripts/update-atheos.sh replaces the application files, so this patch is lost on update. Re-apply it, or drop the plugin.

Two further defects in the same plugin (NOT fixed — upstream, and mostly harmless)

1. terminal.php:95 — $blocked = explode(",", BLOCKED === true); passes a boolean to explode(). This evaluates to explode(",", false), so the intended block-list (define("BLOCKED","ssh,telnet")) never actually blocks anything. The plugin's own guard is dead code. Cosmetic in effect (the command would just fail on its own), but worth knowing rather than trusting.
2. terminal.php:124 — if (strtolower($command === "exit")) passes a boolean to strtolower(). Should be strtolower($command) === "exit". Result: typing exit does not clear term_auth; the session stays authenticated until the browser session ends.

Left as-is: they are upstream bugs, and fixing them changes the plugin's behaviour beyond the minimum needed to make it run. Recorded here so nobody "fixes" them by accident or trusts the block-list.

⚠️ Security note

This plugin gives a browser terminal that executes shell commands as the php-fpm user (atheos). Two things matter:

1. The plugin ships with a well-known, hardcoded gate constant. Upstream is literally define("PASSWORD", "<the default value in the plugin source>");. Anyone who can reach the page can read the source on GitHub and unlock it. We have rotated it to a random value — retrieve it from the PASSWORD define in plugins/Terminal/terminal.php on the guest. It is deliberately not recorded in this repo (see below).
2. It is a shell, so treat it as a privilege decision, not a convenience one. Installing it means the editor can run arbitrary commands as atheos — the same user that owns the deploy key.

Because of (1) and (2), the in-app password is treated as a secret:

• it is not written into this repo, the README, or the RUNBOOK
• to read it: ssh root@192.168.178.57 'grep PASSWORD /var/www/atheos/plugins/Terminal/terminal.php'
• it changes per install; scripts/provision.sh does not set one, so a rebuild returns to the upstream default — rotate it again after a rebuild

Outcome: the plugin has been REMOVED. Once the GLOB_BRACE fault (§1) was fixed, removal through the market succeeded — and that is the right end state: a browser shell is the single largest attack surface in the container, and Atheos macros already provide command execution, so it added little you did not already have. Removal was done by invoking the market's own remove() path, so the plugin list, the addons cache and the generated bundle all stayed consistent:

{"text":"Plugin successfully removed.","status":200}
plugins/ -> (only README.md remains)
addons cache references to Terminal: 0

The notes above are kept because they document what the plugin is and how it failed — and because the same stale-API pattern will recur with any other Codiad-era plugin. To reinstall, use the market: it will re-introduce the Common::execute fault, so patches/Terminal-terminal.php.patched was the fix — it has been deleted along with the plugin. If you ever reinstall, re-derive it: grep -rhoE 'Common::[a-zA-Z_]+' plugins/Terminal/ and expect Common::execute to be missing.

docs/security-notes.md §2 S-7 covers disabling exec/proc_open, which would neutralise both this plugin and the macros. That is the correct lever if you ever expose this container.

---

3. 🟠 The Macro dialog crashed when folder-scoped macros existed

Symptom: the Settings → Macro dialog returned HTTP 500.

Root cause — invalid data by Atheos's own design. components/macro/dialog.php:35 does:

implode(", ", $macro["fTypes"])     // requires an ARRAY

but components/macro/class.macro.php save() writes the string "N/A" for folder macros:

"fTypes" => $type === "file" ? explode(",", $fTypes) : "N/A",

So any folder-type macro makes that dialog fatal:

PHP Fatal error: Uncaught TypeError: implode(): Argument #2 ($array) must be of type ?array,
string given in /var/www/atheos/components/macro/dialog.php:35

Fix applied — correct the DATA, not Atheos's code. The stored fTypes for folder macros is now [] (an empty array) instead of "N/A":

sed -i 's/"fTypes": "N\/A"/"fTypes": []/g' /var/www/atheos/data/macros.db.php

Verified: implode() now succeeds for all 8 macros.

Why data rather than code: patching dialog.php would be overwritten by update-atheos.sh (and by any Atheos update), whereas valid data keeps working. The trade-off is that the UI's own "save" path could re-introduce "N/A" if a macro is edited in the UI — see the follow-up below.

Follow-up (not done): the real upstream fix is $type === "file" ? explode(",", $fTypes) : [] in class.macro.php::save(). Applying it would stop the UI re-introducing the bad value, at the cost of a patch that must be re-applied after updates. Worth doing if the dialog starts 500-ing again after editing a macro in the UI.

---

4. 🟠 The CodeGit panel looked like an empty black box

Symptom: the CodeGit dialog appeared as a mostly-empty black rectangle. Nothing was broken — it was unreadable, which reads as "broken".

⚠️ Superseded by §6. This section fixed a real layout bug, but it was NOT the cause of the empty CodeGit dialog. The actual cause was a relative project path making the request 403, which the modal silently swallowed. Both are fixed; if a dialog is ever blank again, read §6 first.

This was NOT a codegit bug in the JS sense. Verified exhaustively first:

all four panels return real content through the authenticated API:
  overview   200    940 bytes
  log        200  79596 bytes   (full commit history)
  transfer   200   1460 bytes
  config     200   1174 bytes
no JS errors in the browser console; all DOM helpers (replaceClass etc.) exist

Root cause — the generic panel rule hardcodes a height. theme/modules/common/_panel.scss (after minification, in theme/main.min.css):

panel { padding: 5px; width: calc(100% - 200px); overflow: auto; overflow-y: scroll;
        height: 500px; position: relative; border-left: var(--borderLight); }

Measured live, that produces:

Element	Height	Problem
#dialog	404px	clamped by max-height: 70vh + overflow-y: auto
#codegit panel	500px	forced, while its content is 119px
toolbar ("Branch: …")	top 620 vs dialog bottom 490	pushed OUTSIDE the modal

So ~380px of the dialog was empty dead space, and anything after the panel — including the Branch line — rendered below the modal, invisible. A generic panel { height: 500px } is exactly the kind of rule that looks like a void.

Fix applied:

panel { ... height: auto; max-height: 58vh; overflow-y: auto; ... }

Content-sized, capped so long content (the 79KB log) still scrolls. Verified live:

before: panel 500px  → toolbar top 620, dialog bottom 490   (outside)
after:  panel 136px  → toolbar top 256, dialog bottom 279   (inside)

theme/modules/common/_panel.scss is updated too, so the source does not contradict the shipped CSS (there is no Sass compiler on the guest, so main.min.css is edited directly).

---

5. 🟠 CSS/JS changes were invisible behind the browser cache

Symptom: a fix to the theme did not appear until a hard refresh — so the panel fix in §4 looked like it had not worked at all. Reported twice, the second time with "is it because I'm on Firefox?"

It was not Firefox. Verified in a real, scripted Firefox (155.0) against the live server with the fix applied:

assets Firefox requested:  theme/main.min.css?v=1790663824   <- versioned
applied panel rule:        height: auto; max-height: 58vh    <- the fix
dialog 193px | panel 138px | toolbar INSIDE | JS errors: none

The panel rendered correctly and the Branch toolbar sat inside the modal. Firefox behaves identically to Chromium here; it was simply still running the old cached stylesheet.

Root cause — stable asset URLs, with nothing to bust them. Atheos emits:

<link rel="stylesheet" href="theme/main.min.css">   <!-- no version -->
<script src="public/modules.min.js"></script>       <!-- no version -->

Same path before and after a change, and originally no cache headers at all. A browser therefore keeps its cached copy across an update, and never even asks the server. Changing the CSS on the server cannot fix that — the browser is not fetching it.

Fix (two parts):

1. nginx sends Cache-Control: no-cache, must-revalidate for *.css/*.js. This does not disable caching — it forces revalidation, so normal loads still get a cheap 304 while changes are picked up.
2. Versioned URLs. SourceManager::getTag() and the theme link in index.php now append the file's mtime (?v=<mtime>). A changed file gets a new URL so it is fetched immediately; an unchanged file keeps its URL and stays cached.

Part 2 is the one that actually mattered here: it works even against an already-poisoned cache, which part 1 alone cannot do. Once the page refreshes (it is served no-store), every asset URL it references is new, so the stale CSS is bypassed with no manual clearing.

If you ever see a stale UI again: force a reload (Ctrl/Cmd-Shift-R). If that fixes it, this section is why.

Forcing this one time: if a browser holds an old copy, any of these work — Ctrl/Cmd-Shift-R, about:blank then back, a private window, or rm -rf the profile's cache. Or just change the file's mtime (touch) and the URL changes by itself.

---

6. 🔴 Every dialog rendered EMPTY (CodeGit "just a black box")

Symptom: CodeGit — and, it turns out, the Macro / Market / Settings dialogs — opened as an empty black area. No error, no text, nothing. Reported as "codegit still no go just a black box", twice, and it survived the CSS fix in §4, because it was never a CSS problem.

This is the bug that actually mattered. §4 and §5 were real defects, but neither was the cause.

The chain

1. The installer stores a RELATIVE path. components/install/process.php keeps the folder name as given, so the project store held {"Blog": "blog"} — not an absolute path.

2. loadState() hands it to the UI unmodified and persists it (common.php):

   $projectPath = reset($projectList);          // "blog"
   ...
   SESSION("projectPath", $projectPath);        // stored -> the bad value STICKS across logins
   

3. The file tree puts it straight into the DOM (components/filetree/init.js):

   let path = atheos.current.projectPath;
   `<a id="project-root" data-type="root" data-path="${path}">`   // data-path="blog"
   

4. CodeGit then sends repo="blog", and getWorkspacePath("blog") fails its access check:

   traits/path.php:67   Common::send(403, "Client does not have access.");
   

5. modal.js silently discards the failure — this is what makes it look like a "black box" rather than an error:

   settled: function(reply, status) {
       if (status !== 200) return;      // no message, no toast, no console error
       content.html(reply);
   

So the request 403s, nothing is rendered, and nothing is reported. The dialog is left with an empty <section id="content">.

How it was pinned down

Not by reading CSS. By capturing the real request/response from a scripted browser:

POST /dialog.php   {"target":"codegit","action":"codegit","repo":"blog"}
-> 403  (and #content innerHTML length: 0)

A relative path was reproduced directly:

is_dir("blog") from the app root        -> NO
getWorkspacePath("blog")                -> 403 Client does not have access.
projects store                          -> {"Blog": "blog"}

Fix (scripts/fix-project-path.sh)

A relative value in the store is legitimate — Atheos's own project-creation code resolves relative → WORKSPACE/<name>. loadState() simply never does. Two changes, both required:

A. Resolve at load time, and re-store it — this heals sessions already holding the bad value:

if (!Common::isAbsPath($projectPath)) {
    $projectPath = Common::getWorkspacePath($projectPath, true);
    SESSION("projectPath", $projectPath);
}

B. Make the store absolute ({"Blog": "/var/www/atheos/workspace/blog"}) so that array_search($projectPath, $projectList), which loadState() uses to derive the project name for the tree label, keeps working. Fixing only (A) would silently break the label — the path would resolve but array_search would return false, so the tree would show an empty name.

Verified by starting from a deliberately poisoned session (projectPath="blog") and confirming it self-heals:

projectPath : /var/www/atheos/workspace/blog    <- healed from "blog"
data-path   : /var/www/atheos/workspace/blog
dialog.php  : 200 with content
#content    : 1758 chars
visible     : CodeGit Overview Log Transfer Configure Commit Amend ...

An existing browser session heals on its next page load — no hard refresh or re-login needed.

Worth remembering

A 403 from getWorkspacePath() presents as "the dialog is empty", with no error anywhere. If any Atheos dialog is ever blank again, check the project path first, then the response code — not the CSS.

---

7. Checking for plugin problems in future

The plugin's JS is bundled into public/plugins.min.js (built by classes/sourcemanager.php), and its rightbar button is rendered by components/sidebars/sb-right.php from plugin.json. Both were verified working:

plugins.min.js contains 'plugins/Terminal/init.js'   -> YES   (bundle is fine)
rightbar HTML                                        -> <a onclick="atheos.Terminal.open();">
                                                        <i class="fas fa-terminal"></i>Terminal</a>

So when a plugin misbehaves, check in this order:

# 1. did it install?
tail /var/www/atheos/data/log/market.log.php

# 2. is its JS in the served bundle?
grep -c "plugins/<Name>/init.js" /var/www/atheos/public/plugins.min.js

# 3. is it a stale-API port? (Codiad-era plugins are the risk)
grep -rhoE 'Common::[a-zA-Z_]+' /var/www/atheos/plugins/<Name>/ | sort -u
#    then check each exists:  grep -rn "function <name>" /var/www/atheos/common.php /var/www/atheos/traits/

# 4. is there a PHP fatal?
grep -E 'PHP Fatal' /var/log/nginx/atheos.error.log | tail

Rule of thumb: if a plugin was ported from Codiad, assume its Common:: calls are stale and verify them before trusting it.

---

8. Follow-ups not done (recorded so they are not forgotten)

These came out of review. They are operator decisions, not agent ones — several change what the editor can do.

8.0 Branch protection on master — ACCEPTED RISK

Deliberately not enabled while the editor is LAN-only (operator decision). Full reasoning and the "enable it before you expose this host" trigger are in docs/writer-branch-workflow.md §2.

The suite still probes for it on every run and reports ACCEPTED-RISK (not a failure) while it is off, so the recommendation self-cancels the moment it is enabled.

8.1 Remove the Terminal plugin — ✅ DONE

Removed through the market's own code path once §1 was fixed (see §2). A browser shell was the largest attack surface in the container and macros already cover command execution.

8.2 ❌ disable_functions cannot be "on by default" here — measured

Review asked for php.ini to disable exec, shell_exec, passthru, system by default. This would break the editor's core function. Evidence:

components/codegit/*      → Common::safe_execute  (31 call sites — every git operation)
components/macro/*        → Common::raw_execute   (1 call site)
common.php raw_execute    → function_exists("system") / function_exists("exec")

Every git commit, push, fetch and status from the editor goes through exec/system. Disabling them turns the editor into a text editor that cannot commit. So it stays a deliberate exposure lever (S-7 in docs/security-notes.md), to be applied only when the container is exposed — at which point you would also lose macros and git integration, which is why S-7 already says "test, do not blind-apply".

8.3 Rotate the terminal password automatically

If the plugin is kept, provision.sh should generate a random password rather than leaving the upstream default. Not implemented: it would hardcode a secret into a repo file, which is the same class of problem this file already documents.

8.4 Deploy key could be read-only

Review suggested making the deploy key read-only if writes are unnecessary. They are necessary — that is the whole point of the writer-branch workflow (macro 2 pushes). Not applicable.

8.5 The real upstream fix for §3

class.macro.php::save() should write [] instead of "N/A" for folder macros. See §4 — the fix is currently applied to the data, so it survives updates, at the cost of being reversible from the UI.