Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Added a doc section about CSRF/HTTP Referrer. Other minor doc/message cleanups. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | fileedit-ajaxify |
Files: | files | file ages | folders |
SHA3-256: |
6de7e480214ca6a034bceb1e6852e665 |
User & Date: | stephan 2020-05-21 06:32:09.504 |
Context
2020-05-26
| ||
06:43 | Merged in trunk. ... (check-in: 559807ba user: stephan tags: fileedit-ajaxify) | |
2020-05-21
| ||
06:32 | Added a doc section about CSRF/HTTP Referrer. Other minor doc/message cleanups. ... (check-in: 6de7e480 user: stephan tags: fileedit-ajaxify) | |
2020-05-18
| ||
06:05 | Internal commentary on the validity of the global UI enable/disable approach to XHR handling. ... (check-in: 7a95a0f1 user: stephan tags: fileedit-ajaxify) | |
Changes
Changes to src/fileedit.c.
︙ | ︙ | |||
1079 1080 1081 1082 1083 1084 1085 | */ static int fileedit_ajax_boostrap(int requirePost){ login_check_credentials(); if( !g.perm.Write ){ fileedit_ajax_error(403,"Write permissions required."); return 0; }else if(0==cgi_csrf_safe(requirePost)){ | | > > > | 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 | */ static int fileedit_ajax_boostrap(int requirePost){ login_check_credentials(); if( !g.perm.Write ){ fileedit_ajax_error(403,"Write permissions required."); return 0; }else if(0==cgi_csrf_safe(requirePost)){ fileedit_ajax_error(403, "CSRF violation (make sure sending of HTTP " "Referer headers is enabled for XHR " "connections)."); return 0; } return 1; } /* ** Returns true if the current user is allowed to edit the given ** filename, as determined by fileedit_is_editable(), else false, |
︙ | ︙ |
Changes to www/fileedit-page.md.
1 2 | # The fileedit Page | | | | | | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 | # The fileedit Page This document describes the limitations of, caveats for, and disclaimers for the [](/fileedit) page, which provides users with [checkin privileges](./caps/index.md) basic editing features for files via the web interface. # Important Caveats and Disclaimers Predictably, the ability to edit files in a repository from a web browser halfway around the world comes with several obligatory caveats and disclaimers... ## `/fileedit` Does *Nothing* by Default. In order to "activate" it, a user with [the "setup" permission](./caps/index.md) must set the [fileedit-glob](/help?cmd=fileedit-glob) repository setting to a comma- or newline-delimited list of globs representing a whitelist of files which may be edited online. Any user with commit access may then edit files matching one of those globs. Certain pages within the UI get an "edit" link added to them when the current user's permissions and the whitelist both permit editing of that file. ## CSRF & HTTP Referrer Headers In order to protect against [Cross-site Request Forgery (CSRF)][csrf] attacks, Fossil UI features which write to the database require that the browser send the so-called [HTTP `Referer` header][referer] (noting that the misspelling of "referrer" is a historical accident which has long-since been standardized!). Modern browsers, by default, include such information automatically for *interactive* actions which lead to a request, e.g. clicking on a link back to the same server. However, `/fileedit` uses asynchronous ["XHR"][xhr] connections, which browsers *may* treat differently than strictly interactive elements. - **Firefox**: configuration option `network.http.sendRefererHeader` specifies whether the `Referer` header is sent. It must have a value of 2 (which is the default) for XHR requests to get the `Referer` header. Purely interactive Fossil features, in which users directly activate links or forms, work with a level of 1 or higher. - **Chrome**: apparently requires an add-on in order to change this policy, so Chrome without such an add-on will not suppress this header. - **Safari**: ??? - **Other browsers**: ??? If `/filepage` shows an error message saying "CSRF violation," the problem is that the browser is not sending a `Referer` header to XHR connections. Fossil does not offer a way to disable its CSRF protections. [referer]: https://en.wikipedia.org/wiki/HTTP_referer [csrf]: https://en.wikipedia.org/wiki/Cross-site_request_forgery [xhr]: https://en.wikipedia.org/wiki/XMLHttpRequest ## `/fileedit` **Works by Creating Commits** Thus any edits made via that page become a normal part of the repository's blockchain. ## `/fileedit` is *Intended* for use with Embedded Docs ... and similar text files, and is most certainly **not intended for editing code**. Editing files with unusual syntax requirements, e.g. hard tabs in makefiles, may break them. *You Have Been Warned.* Similarly, though every effort is made to retain the end-of-line style used by being-edited files, the round-trip through an HTML textarea element may change the EOLs. The Commit section of the page offers three different options for how to treat newlines when saving changes. **Files with mixed EOL styles** *will be normalized to a single EOL style* when modified using `/fileedit`. When "inheriting" the EOL style from a previous version which has mixed styles, the first EOL style detected in the previous version of the file is used. ## `/fileedit` **is Not a Replacement for a Checkout** A full-featured checkout allows far more possibilities than this basic online editor permits, and the feature scope of `/fileedit` is intentionally kept small, implementing only the bare necessities needed for performing basic edits online. It *is not, and will never be, a replacement for a checkout.* |
︙ | ︙ | |||
62 63 64 65 66 67 68 | - The ability to edit/manipulate files which are in a local checkout. (If you have a checkout, use your local editor, not `/fileedit`.) - Editing of non-text files, e.g. images. Use a checkout and your preferred graphics editor. - Support for syncing/pulling/pushing of a repository before and/or after edits. Those features cannot be *reliably* provided via a web | | < < | | | | > | > | | > > > > > | > > | | 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | - The ability to edit/manipulate files which are in a local checkout. (If you have a checkout, use your local editor, not `/fileedit`.) - Editing of non-text files, e.g. images. Use a checkout and your preferred graphics editor. - Support for syncing/pulling/pushing of a repository before and/or after edits. Those features cannot be *reliably* provided via a web interface for several reasons. Similarly, some *potential* features have significant downsides, abuses, and/or implementation hurdles which make the decision of whether or not to implement them subject to notable contributor debate. e.g. the ability to add new files or remove/rename older files. ## `/fileedit` **Stores Only Limited Local Edits While Working** When changes are made to a given checkin/file combination, `/fileedit` will, if possible, store them in [`window.localStorage` or `window.sessionStorage`][html5storage], if available, but... - Which storage is used is unspecified and may differ across environments. - If neither of those is available, the storage is transient and will not survive a page reload. In this case, the UI issues a clear warning in the editor tab. - It stores only the most recent checkin/file combinations which have been modified (exactly how many may differ - the number will be noted somewhere in the UI). Note that changing the "executable bit" is counted as a modification, but the checkin *comment* is *not* and is reset after a commit. - If its internal limit on the number of modified files is exceeded, it silently discards the oldest edits to keep the list at its limit. Edits are saved whenever the editor component fires its "change" event, which essentially means as soon as it loses input focus. Thus to force the browser to save any pending changes, simply click somwhere on the page outside of the editor. Exactly how long `localStorage` will survive, and how much it or `sessionStorage` can hold, is environment-dependent. `sessionStorage` will survive until the current browser tab is closed, but it survives across reloads of the same tab. If `/filepage` determines that no peristent storage is available a warning is displayed on the editor page. [html5storage]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API ## The Power is Yours, but... > "With great power comes great responsibility." **Use this feature judiciously, *if at all*.** Now, with those warnings and caveats out of the way... |
︙ | ︙ | |||
130 131 132 133 134 135 136 | such events... ## Integrating Syntax Highlighting Assuming a repository has integrated a 3rd-party syntax highlighting solution, it can probably (depending on its API) be told how to highlight `/fileedit`'s wiki/markdown-format previews. Here are | | | 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | such events... ## Integrating Syntax Highlighting Assuming a repository has integrated a 3rd-party syntax highlighting solution, it can probably (depending on its API) be told how to highlight `/fileedit`'s wiki/markdown-format previews. Here are instructions for doing so with [highlightjs](https://highlightjs.org/): At the very bottom of the [site skin's footer](customskin.md), add a script tag similar to the following: ```javascript <script nonce="$<nonce>"> if(window.fossil && fossil.page && fossil.page.name==='fileedit'){ |
︙ | ︙ |