From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001 From: cashmere Date: Fri, 4 Sep 2026 09:05:24 +0200 Subject: initial commit --- www/caps/impl.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 www/caps/impl.md (limited to 'www/caps/impl.md') diff --git a/www/caps/impl.md b/www/caps/impl.md new file mode 100644 index 0000000..1f9b5a4 --- /dev/null +++ b/www/caps/impl.md @@ -0,0 +1,111 @@ +# Implementation Details of User Capabilities + +## Capability Letter Choices + +We [assigned][ref] user capability characters using only lowercase ASCII +letters at first, so those are the most important within Fossil: they +control the functions most core to Fossil’s operation. Once we used up +most of the lowercase letters, we started using uppercase, and then +during the development of the [forum feature][for] we assigned most of +the decimal numerals. All of the lowercase ASCII letters are now +assigned. Eventually, we might have to start using ASCII +punctuation and symbols. We expect to run out of reasons to define new caps before +we’re forced to switch to Unicode, though the possibilities for [mnemonic][mn] +assignments with emoji are intriguing. 😉 + +The existing caps are usually mnemonic, especially among the +earliest and therefore most central assignments, made when we still had +lots of letters to choose from. There is still hope for good future +mnemonic assignments among the uppercase letters, which are mostly still +unused. + + +## Why Not Bitfields? + +Some may question the use of ASCII character strings for [capability +sets][ucap] instead of bitfields, which are more efficient, both in +terms of storage and processing time. + +Fossil handles these character strings in one of two ways. For most HTTP +hits, Fossil [expands][sexp] the string into a [`struct` full of +flags][sff] so that later code can just do simple Boolean tests. In a +minority of cases, where Fossil only needs to check for the presence of +a single flag, it just does a [`strchr()` call][sc] on the string +instead. + +Both methods are slower than bit testing in a bitfield, but keep the +execution context in mind: at the front end of an HTTP request handler, +where the nanosecond differences in such implementation details are +completely swamped by the millisecond scale ping time of that repo’s +network connection, followed by the required I/O to satisfy the request. +Either method is plenty fast in that context. + +In exchange for this immeasurable cost per hit, we get human-readable +capability sets. + + +## Why Doesn’t Fossil Filter “Bad” Artifacts on Sync? + +Fossil is more trusting about the content it receives from a remote +clone during sync than you might expect. Common manifestations of this +design choice are: + +1. A user may be able to impersonate other users. This can be + [accidental](./index.md#defuser) as well as purposeful. + +2. If your local system clock is out-of-sync with absolute time, + artifacts committed to that repo will appear with the “wrong” time + when sync’d. If the time sync error is big enough, it can make + check-ins appear to go back in time and other bad effects. + +3. You can purposely overwrite good timestamps with bad ones and push + those changes up to the remote with no interference, even though + Fossil tries to make that a Setup-only operation. + +All of this falls out of two of Fossil’s design choices: sync is +all-or-nothing, and [the Fossil hash tree][bc] is immutable. Fossil +would have to violate one or both of these principles to filter such +problems out of incoming syncs. + +We have considered auto-[shunning][shun] “bad” content on sync, but this +is [difficult][asd] due to [the design of the sync protocol][dsp]. This +is not an impossible set of circumstances, but implementing a robust +filter on this input path would be roughly as difficult as writing a +basic [inter-frame video codec][ifvc]: do-able, but still a lot of +work. Patches to do this will be thoughtfully considered. + +We can’t simply change content as it arrives. Such manipulations would +change the artifact manifests, which would change the hashes, which +would require rewriting all parts of the block chain from that point out +to the tips of those branches. The local Fossil repo must then go +through the same process as the remote one on subsequent syncs in order +to build up a sync sequence that the remote can understand. Even if +you’re willing to accept all of that, this would break all references to +the old artifact IDs in forum posts, wiki articles, check-in comments, +tickets, etc. + +The bottom line here is that [**Clone**](./ref.html#g) and +[**Write**](./ref.html#i) are a potent combination of user capabilities. +Be careful who you give that pair to! + + +----- + +*[Back to Administering User Capabilities](./)* + + +
+ +[asd]: https://fossil-scm.org/forum/forumpost/ce4a3b5f3e +[bc]: ../blockchain.md +[dsp]: https://fossil-scm.org/fossil/doc/trunk/www/sync.wiki +[for]: ./forum.wiki +[ifvc]: https://en.wikipedia.org/wiki/Inter_frame +[mn]: https://en.wikipedia.org/wiki/Mnemonic +[ref]: ./ref.html +[sexp]: /artifact?ln=1223-1298&name=889d6724 +[sff]: /artifact?ln=80-117&name=52d2860f +[sc]: https://en.cppreference.com/w/c/string/byte/strchr +[shun]: ../shunning.wiki +[ucap]: ./index.md#ucap -- cgit v1.3.1