odstranene podmienky na document root

This commit is contained in:
2026-11-06 10:25:29 +01:00
parent a9022e1fb2
commit b92aedb7d8
4 changed files with 49 additions and 31 deletions
+2 -2
View File
@@ -15,7 +15,7 @@ When a `.md` file is requested, `src/md2html.php` loads the Markdown, converts i
## Environment Assumptions ## Environment Assumptions
- NGINX supplies the original request URI and the site document root via FastCGI. - NGINX supplies the original request URI and the site document root via FastCGI.
- The project can live outside the document root. PHP embeds local CSS/JS into HTML; no static asset URLs are required. - The project can live outside the document root. PHP embeds local CSS/JS into HTML; no static asset URLs are required.
- An external symlink requires an explicitly configured URL prefix and target directory. See README.md. - External symlinks and junctions work without per-prefix configuration, subject to PHP filesystem access.
## Change Priorities ## Change Priorities
1. Keep output readable on desktop and mobile. 1. Keep output readable on desktop and mobile.
@@ -40,7 +40,7 @@ When a `.md` file is requested, `src/md2html.php` loads the Markdown, converts i
- Do not assign anonymous functions or closures to PHP variables; use named functions or class methods. - Do not assign anonymous functions or closures to PHP variables; use named functions or class methods.
- Output helpers should return rendered content for callers to consume. - Output helpers should return rendered content for callers to consume.
- Validate the decoded URL path, including the `.md` extension, before filesystem lookup. Query parameters must never select a file. - Validate the decoded URL path, including the `.md` extension, before filesystem lookup. Query parameters must never select a file.
- Require a regular Markdown file whose canonical path lies under the canonical document root or the explicitly permitted root for the requested URL prefix. - Require a regular Markdown file after canonical resolution; symlink and junction targets may lie outside the document root.
- Keep path handling compatible with Linux and Windows, including symlink and junction resolution. - Keep path handling compatible with Linux and Windows, including symlink and junction resolution.
- Keep Parsedown raw HTML rendering enabled. Serve Markdown from trusted sources. - Keep Parsedown raw HTML rendering enabled. Serve Markdown from trusted sources.
+38 -16
View File
@@ -20,42 +20,64 @@ Projekt môže byť mimo webového koreňa. Nasadzuj `src/` aj `vendor/`; autolo
- `src/markdown.css`: štýly, ktoré PHP vloží priamo do `<style>`. - `src/markdown.css`: štýly, ktoré PHP vloží priamo do `<style>`.
- `src/toc.js`: vlastný JavaScript, ktorý PHP vloží do `<script>` za dokumentom. - `src/toc.js`: vlastný JavaScript, ktorý PHP vloží do `<script>` za dokumentom.
CSS a JavaScript sú súčasťou každej HTML odpovede. Nie sú potrebné samostatné URL ani NGINX pravidlá pre statické súbory nástroja. Zdrojové CSS/JS zostávajú na serveri, ale klient ich samostatne nenačítava. Zmenený obsah sa vloží do ďalšej odpovede; verzovanie URL pomocou hashov odpadá. CSS a JavaScript sú súčasťou každej HTML odpovede. Nie sú potrebné samostatné URL ani NGINX pravidlá pre statické súbory nástroja. Zdrojové CSS/JS zostávajú na serveri, ale klient ich samostatne nenačítava. Zmenený obsah sa vloží do ďalšej odpovede.
## Konfigurácia NGINX ## Konfigurácia NGINX
V existujúcom bloku `server` nastav smerovanie Markdown požiadaviek, napríklad: Spoločný snippet [`nginx/md2html.conf`](nginx/md2html.conf) includuj do každého `server` bloku, kde chceš zobrazovať Markdown. Cestu k PHP súboru a PHP-FPM socket nastavíš v snippete iba raz:
```nginx ```nginx
root /storage/www;
location ~* \.md$ { location ~* \.md$ {
include fastcgi_params; include fastcgi_params;
fastcgi_param SCRIPT_FILENAME /storage/tpsoft.org/MD2HTML/src/md2html.php; fastcgi_param SCRIPT_FILENAME /storage/tpsoft.org/MD2HTML/src/md2html.php;
# Voliteľné povolenie pre existujúci symlink /storage/www/polyanalyzer
fastcgi_param MD2HTML_LINK_PREFIX /polyanalyzer/;
fastcgi_param MD2HTML_LINK_ROOT /storage/tpsoft.org/polymarket-analyzer/reports;
fastcgi_pass unix:/run/php/php8.4-fpm.sock; fastcgi_pass unix:/run/php/php8.4-fpm.sock;
} }
``` ```
Uprav cesty a socket podľa servera. `fastcgi_params` musí odovzdávať `REQUEST_URI $request_uri` a `DOCUMENT_ROOT $document_root`. Vo Windows použi napríklad `root D:/www;`, absolútnu cestu k `src/md2html.php` a `fastcgi_pass 127.0.0.1:9999;` podľa nastavenia PHP. Konfigurácia jednotlivých webov potom obsahuje iba ich vlastný koreň a spoločný include:
Staré pravidlá `location = /_md2html/markdown.css` a `location = /_md2html/toc.js` možno odstrániť po nasadení tejto verzie. Nové statické cesty nepridávaj. Produkčnú konfiguráciu tento projekt automaticky nemení. Po ručnej úprave over konfiguráciu cez `nginx -t` a načítaj ju cez `nginx -s reload`. ```nginx
server {
listen 80;
server_name example.com;
root /storage/www;
include /storage/tpsoft.org/MD2HTML/nginx/md2html.conf;
}
Ak externý symlink nepotrebuješ, vynechaj oba parametre `MD2HTML_LINK_*`. Pri použití musí výsledný súbor pod daným URL prefixom ležať v explicitne povolenom cieľovom adresári. PHP musí mať právo prejsť doň a čítať súbory. server {
listen 80;
server_name docs.example.com;
root /storage/docs;
include /storage/tpsoft.org/MD2HTML/nginx/md2html.conf;
}
```
Existujúce nastavenia domény, HTTPS a ostatných ciest ponechaj v príslušnom `server` bloku. Snippet používa jeho `root`, takže každý web číta dokumenty dostupné cez svoj koreň vrátane symlinkov. Includuj ho priamo do `server`, iba raz, pred prípadnými všeobecnejšími regulárnymi `location` pravidlami. Prefixové pravidlá s `^~` môžu spracovanie Markdownu v danom prefixe potlačiť.
Uprav cesty a socket podľa servera. `fastcgi_params` musí odovzdávať `REQUEST_URI $request_uri` a `DOCUMENT_ROOT $document_root` a nesmie pridávať inú hodnotu `SCRIPT_FILENAME`. Vo Windows použi napríklad `include D:/www/md2html/nginx/md2html.conf;`; v snippete nastav `fastcgi_param SCRIPT_FILENAME D:/www/md2html/src/md2html.php;` a `fastcgi_pass 127.0.0.1:9999;` podľa nastavenia PHP. Koreň každého webu zostáva v jeho `server` bloku.
Po úprave konfigurácie ju over cez `nginx -t` a načítaj cez `nginx -s reload`. Správanie `include` a výber `location` opisuje [oficiálna dokumentácia NGINX](https://nginx.org/en/docs/beginners_guide.html).
### Symlinky a junctiony
Ľubovoľný počet existujúcich symlinkov alebo Windows junctionov funguje cez ten istý snippet, aj keď ich ciele ležia mimo `DOCUMENT_ROOT`. Nie sú potrebné pravidlá ani povolenia pre jednotlivé prefixy. Napríklad pri `root /storage/www;`:
- `/storage/www/polyanalyzer` → `/storage/tpsoft.org/polymarket-analyzer/reports`: URL `/polyanalyzer/report.md`.
- `/storage/www/manualy` → `/storage/manualy`: URL `/manualy/navod.md`.
PHP vyhodnotí skutočný cieľ a načíta ho, ak ide o regulárny `.md` súbor a má k nemu prístup. Kontroluje sa prípona v URL aj prípona cieľového súboru. Cieľ nemusí ležať pod webovým koreňom. Prístup naďalej podlieha oprávneniam účtu PHP, prípadnému `open_basedir` a izolácii PHP-FPM.
URL sa stále mapuje cez koreň webu: absolútnu diskovú cestu ani parameter `file` nemožno použiť na výber súboru. Externé dokumenty sprístupni cez symlink alebo junction. Neplatné URL vrátane segmentov `..` zostávajú odmietnuté.
## Používanie a offline zobrazenie ## Používanie a offline zobrazenie
Pre súbor `/storage/www/docs/navod.md` otvor napríklad `https://example.com/docs/navod.md`. URL `https://example.com/docs/navod.md?view=print#instalacia` načíta ten istý súbor; query string ani parameter `file` nevyberajú dokument. Pri povolenom symlinku možno používať aj `https://example.com/polyanalyzer/report.md`. Pre súbor `/storage/www/docs/navod.md` otvor napríklad `https://example.com/docs/navod.md`. URL `https://example.com/docs/navod.md?view=print#instalacia` načíta ten istý súbor; query string ani parameter `file` nevyberajú dokument. Cez existujúci symlink možno používať aj `https://example.com/polyanalyzer/report.md`.
PHP prijíma iba regulárne `.md` súbory pod kanonickým webovým koreňom alebo explicitne povoleným cieľom symlinku. Neplatné a nenájdené cesty vracajú 404. PHP prijíma regulárne `.md` súbory dostupné cez URL cestu pod webovým koreňom vrátane symlinkov a junctionov smerujúcich mimo neho. Neplatné a nenájdené cesty vracajú 404.
HTML odpoveď možno uložiť ako `.html` a otvoriť bez internetu. Vlastný vzhľad ani ovládanie nástroja nepotrebujú sieť, externé fonty, obrázky, ikony ani JS knižnice. Používajú sa systémové fonty a textové symboly. Podporované sú nadpisy, odseky, zoznamy, tabuľky, citácie a bloky kódu; automatické syntax highlighting nie je implementované. Markdown obsah sa nevkladá do JavaScriptového kódu. Uzatváracie tagy skriptu v jeho zdroji sú escapované. HTML odpoveď možno uložiť ako `.html` a otvoriť bez internetu. Vlastný vzhľad ani ovládanie nástroja nepotrebujú sieť, externé fonty, obrázky, ikony ani JS knižnice. Používajú sa systémové fonty a textové symboly. Podporované sú nadpisy, odseky, zoznamy, tabuľky, citácie a bloky kódu; automatické syntax highlighting nie je implementované. Markdown obsah sa nevkladá do JavaScriptového kódu. Uzatváracie tagy skriptu v jeho zdroji sú escapované.
Odkazy, obrázky a surové HTML z Markdown dokumentu zostávajú zachované. Ich prípadné externé zdroje sa nebaľujú do HTML a môžu potrebovať sieť alebo pôvodné relatívne cesty. Offline záruka sa týka vlastných štýlov a ovládania nástroja. Parsedown aj naďalej povoľuje surové HTML, preto publikuj iba dôveryhodný Markdown. Webový koreň, povolené ciele symlinkov aj nadradené adresáre musia spravovať dôveryhodní používatelia. Vo Windows používaj lokálne cesty s písmenom jednotky; vyhni sa UNC cestám a bodom pripojenia zväzkov. Odkazy, obrázky a surové HTML z Markdown dokumentu zostávajú zachované. Ich prípadné externé zdroje sa nebaľujú do HTML a môžu potrebovať sieť alebo pôvodné relatívne cesty. Offline záruka sa týka vlastných štýlov a ovládania nástroja. Parsedown aj naďalej povoľuje surové HTML, preto publikuj iba dôveryhodný Markdown. Webový koreň, ciele symlinkov aj nadradené adresáre musia spravovať dôveryhodní používatelia. Vo Windows používaj lokálne cesty s písmenom jednotky; vyhni sa UNC cestám a bodom pripojenia zväzkov.
Ak server pridáva Content-Security-Policy, musí povoľovať tieto inline štýly a skripty; nástroj sám CSP hlavičku nenastavuje. Ak server pridáva Content-Security-Policy, musí povoľovať tieto inline štýly a skripty; nástroj sám CSP hlavičku nenastavuje.
@@ -76,6 +98,6 @@ node --check src/toc.js
git diff --check git diff --check
``` ```
Testy overujú skutočný výstup Parsedown, vložené CSS/JS bez externých odkazov, absenciu sieťového načítavania vo vlastných zdrojoch, escapovanie `</script>`, diakritiku, surové HTML, URL guard a obsah dokumentu pomocou DOM modelu. Spúšťajú JavaScript extrahovaný z generovanej HTML odpovede bez sieťových API. Nepoužívajú prehliadač ani ďalšie balíčky. Testy overujú skutočný výstup Parsedown, vložené CSS/JS bez externých odkazov, absenciu sieťového načítavania vo vlastných zdrojoch, escapovanie `</script>`, diakritiku, surové HTML, URL guard a obsah dokumentu pomocou DOM modelu. Overujú aj dva externé symlinky (vo Windows junctiony) mimo testovacieho webového koreňa a odmietnutie adresárov, chýbajúcich súborov a súborov bez prípony `.md`. Spúšťajú JavaScript extrahovaný z generovanej HTML odpovede bez sieťových API. Nepoužívajú prehliadač ani ďalšie balíčky.
Skutočné rozloženie, scrollovanie, offline otvorenie uloženého HTML a desktopové/mobilné ovládanie manuálne overuje Igor. Lokálna sada neoveruje bežiaci NGINX ani produkčné HTTP hlavičky. Skutočné rozloženie, scrollovanie, offline otvorenie uloženého HTML a desktopové/mobilné ovládanie manuálne overuje Igor. Lokálna sada neoveruje bežiaci NGINX ani produkčné HTTP hlavičky.
+7
View File
@@ -0,0 +1,7 @@
# Include inside each server that should render Markdown.
# Configure the shared MD2HTML path and PHP-FPM endpoint for this machine.
location ~* \.md$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME /storage/tpsoft.org/MD2HTML/src/md2html.php;
fastcgi_pass unix:/run/php/php8.4-fpm.sock;
}
+2 -13
View File
@@ -45,20 +45,9 @@ function requestedMarkdown(): string|false
return false; return false;
} }
$allowedRoot = $root; // Follow symlinks/junctions even when their target is outside DOCUMENT_ROOT.
$linkPrefix = $_SERVER['MD2HTML_LINK_PREFIX'] ?? '';
if ($linkPrefix !== '' && str_starts_with($path, rtrim($linkPrefix, '/') . '/')) {
$linkRoot = $_SERVER['MD2HTML_LINK_ROOT'] ?? '';
$allowedRoot = $linkRoot === '' ? false : canonicalPath($linkRoot);
if ($allowedRoot === false || !is_dir($allowedRoot)) {
return false;
}
}
$file = canonicalPath(rtrim($root, DIRECTORY_SEPARATOR) . str_replace('/', DIRECTORY_SEPARATOR, $path)); $file = canonicalPath(rtrim($root, DIRECTORY_SEPARATOR) . str_replace('/', DIRECTORY_SEPARATOR, $path));
$allowedPrefix = rtrim($allowedRoot, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR; if ($file === false || !str_ends_with(strtolower($file), '.md') || !is_file($file)) {
if ($file === false || !str_starts_with($file, $allowedPrefix)
|| !str_ends_with(strtolower($file), '.md') || !is_file($file)) {
return false; return false;
} }