TH1 docs questions and documentation suggestions

(1.3) By James Cook (falsifian) on 2024-09-10 23:55:35 edited from 1.2 [link] [source]

I recently figured out how to use the th1-docs option, and there are some places where the documentation could be improved and/or I have misunderstood something:

1. The instructions in this section on "TH1 Documents" didn't work for me. It seems to claim all I need to do is compile fossil with --with-th1-docs, and then th1 code between {} will be run in any doc page that gets rendered. However, I instead needed to do the following:

Compile with --with-th1-docs
Enable the th1-docs setting
Name a file with the .th1 extension.
Put the code between <th1> and </th1>.

I haven't found any context where surrounding code by {} has any effect. Am I missing something, or is the documentation out of date?

If I'm right, here's some suggested replacement text:

Fossil will substitute the value of TH1 expressions between <th1> </th1> tags in files into the output HTML

If you configure fossil with the --with-th1-docs option and then enable the th1-docs setting (both disabled by default), then any file whose name ends in .th1 will be rendered by executing code inside <th1>...</th1> tags. For example: `<th1>

<h1>List of tech notes:</h1>
<th1>query {select comment from event where type='e';} {html "<p>[htmlize $comment]</p>\n"}</th1>

(I made use of this forum post but I don't know where that person learned about the <th1> tag.)

2. It might help to link from this page on TH1 scripting to that section on TH1 docs, and maybe other places where TH1 can be used. Perhaps just add, after the very first sentence, "See (link), (link).". I found the page on TH1 really interesting but it took some digging for me to understand how it could actually be used.

3. A couple of questions about security:

At a glance, I don't see any TH1 commands that could affect anything outside the repository (e.g. delete a file on the host system), unless tcl integration is enabled. Was the set of commands deliberately designed to limit what TH1 code can do? (If so, it makes me feel slightly safer about enabling TH1 docs, though I understand it's a pretty big attack surface.)
Since /admin_th1 already allows any admin to run TH1 code, am I correct that compiling with --with-th1-docs doesn't give anyone additional power to do harm unless th1-docs is also enabled somewhere? (Keeping in mind one could be tricked into enabling the th1-docs setting, e.g. if someone emails me a .fossil file and asks me to serve it.)

(2) By Stephan Beal (stephan) on 2024-09-11 10:19:50 in reply to 1.3 [source]

However, I instead needed to do the following: ... or is the documentation out of date?

The docs are apparently out of date. i'm working on addressing your suggestions now, so check for updated docs in the next hour or so.

I found the page on TH1 really interesting but it took some digging for me to understand how it could actually be used.

We don't generally encourage (alternately: we generally discourage) the use of th1-docs.

Was the set of commands deliberately designed to limit what TH1 code can do?

Most definitely. It must not be able to access anything outside of the repository.

am I correct that compiling with --with-th1-docs doesn't give anyone additional power to do harm unless th1-docs is also enabled somewhere?

Correct, but if the th1-docs setting is enabled then anyone with check-in access can run th1 by committing to .th1 files.

(Keeping in mind one could be tricked into enabling the th1-docs setting, e.g. if someone emails me a .fossil file and asks me to serve it.)

Then the worst they could do is mess with the repo they sent you or potentially cause a Denial of Service attack by, e.g., writing an endless loop and hitting that page many times concurrently. However, they can't use th1 to directly affect other repositories nor exfiltrate unrelated data from your system.