/+ - Name: SisuDoc Spine, Doc Reform [a part of] - Description: documents, structuring, processing, publishing, search - static content generator - Author: Ralph Amissah [ralph.amissah@gmail.com] - Copyright: (C) 2015 (continuously updated, current 2026) Ralph Amissah, All Rights Reserved. - License: AGPL 3 or later: Spine (SiSU), a framework for document structuring, publishing and search Copyright (C) Ralph Amissah This program is free software: you can redistribute it and/or modify it under the terms of the GNU AFERO General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see [https://www.gnu.org/licenses/]. If you have Internet connection, the latest version of the AGPL should be available at these locations: [https://www.fsf.org/licensing/licenses/agpl.html] [https://www.gnu.org/licenses/agpl.html] - Spine (by Doc Reform, related to SiSU) uses standard: - docReform markup syntax - standard SiSU markup syntax with modified headers and minor modifications - docReform object numbering - standard SiSU object citation numbering & system - Homepages: [https://www.sisudoc.org] [https://www.doc-reform.org] - Git [https://git.sisudoc.org/] +/ /++ module carried_names;
- validate the names of files carried inside an artefact, before any of them is written to disk
- one set of rules for a bare filename, one for a relative path, and a containment check for either +/ module sisudoc.ocda.io_in.carried_names; @safe: /+ ↓ how many members one pod archive may hold, for both writer and the reader . It was 500 set in the reader alone, determined when a pod held markup and images. A pod that carries translation catalogues has a different calculation, the count is driven by how many *files* a document is made of times the number of languages it has (rather than document size). Here are figures based on the document sample set: . entries ~= languages x (markup_files + po_files + 1) + pot_files + images + 2 . the_wealth_of_networks 213,405 words, 1 file per language 12 languages -> 49 entries live-manual 24,724 words, 20 files per language 12 languages -> 506 entries . (the big book is not what runs into this; the modular manual is. At 500 live-manual was two languages from producing an archive spine writes and then refuses to read). . 10,000 covers a hundred-insert manual in thirty languages, about 6,200 entries, with room. The number is deliberately well clear of any real document rather than snug above the largest one known, because the two errors are not comparable: too low refuses a legitimate document with a message that reads as corruption, while too high defers to a size cap a moment later. . This is the weakest of the three guards and is not what bounds resource use. MAX_ENTRY_SIZE bounds any one member and MAX_TOTAL_SIZE bounds the whole extraction, both checked before a byte is written. A count bounds metadata and per-file syscalls, which at this order of magnitude is nothing beside what the size caps already allow. +/ enum size_t MAX_POD_ENTRY_COUNT = 10_000; /+ ↓ names that arrive from outside, and decide where a file gets written . A pod zip and a .ocda.db both carry files by name, and both can arrive over https. A name read out of either is attacker-controlled: it can be absolute, it can climb with "..", and chainPath silently drops everything before an absolute segment, so "/etc/x" does not land under the directory it was joined to. read_zip_pod.d has guarded against this since the zip reader was written; the database reader did not, which is what this module is for. . Two rules, because the two roles differ: - an image is carried under a bare filename and belongs in one directory, so a directory part in the name is itself the error; - markup, conf and manifest are carried under their path inside the pod (media/text/de/about_manual.ssi), so the rule there is the zip reader's: relative, no climbing, bounded depth. . Both are followed by carriedPathIsWithin() at the point of writing. That is deliberate duplication: the name rules are the check, and containment is the check on the check. +/ template spineCarriedNames() { import std.algorithm : canFind; /+ ↓ imports stay narrow on purpose. This template is mixed in beside others, and a template-level import lands in the mixing scope: an "import std.array : split" here takes over the UFCS lookup for split(ctRegex) at every mixin site and breaks it. Nothing below needs split, and nothing below should acquire it. +/ import std.array : array; import std.conv : to; import std.path : asNormalizedPath, isAbsolute; import std.regex; import std.string : indexOf; /+ ↓ limits, the zip reader's where they overlap +/ enum size_t MAX_CARRIED_NAME_LENGTH = 255; /+ one path component +/ enum size_t MAX_CARRIED_PATH_LENGTH = 1024; /+ the whole path +/ enum size_t MAX_CARRIED_PATH_DEPTH = 10; /+ as read_zip_pod.d +/ /+ ↓ allowed characters: a filename has no separator, a path has "/". "~" is here because it is spine's own uid separator (InlineMarkup.uid_sep), which joins a pod name to a document name where the two differ, as in sisu-manual~sisu_markup.en.ssp. It cannot occur in either half, every filesystem of interest takes it, and it is unreserved in rfc 3986. +/ static auto rgx_safe_carried_name = ctRegex!(`^[a-zA-Z0-9._ ~-]+$`); static auto rgx_safe_carried_path = ctRegex!(`^[a-zA-Z0-9._/ ~-]+$`); /+ ↓ the checks both rules share, "" when the name is acceptable +/ private string _carriedNameCommon(string _name) { if (_name.length == 0) { return "empty carried name"; } if (_name.indexOf('\0') >= 0) { return "null byte in carried name"; } if (_name.canFind("\\")) { return "backslash in carried name: " ~ _name; } if (_name.canFind("..")) { return "path traversal in carried name: " ~ _name; } if (_name.isAbsolute || _name[0] == '/') { return "absolute path in carried name: " ~ _name; } return ""; } /+ ↓ a bare filename, as an image is carried: no directory part at all +/ string validateCarriedFileName(string _name) { string _common = _carriedNameCommon(_name); if (_common.length > 0) { return _common; } if (_name.length > MAX_CARRIED_NAME_LENGTH) { return "carried filename too long: " ~ _name; } if (_name.canFind("/")) { return "directory part in carried filename: " ~ _name; } if (_name[0] == '.') { return "carried filename begins with a dot: " ~ _name; } if (!(_name.matchFirst(rgx_safe_carried_name))) { return "disallowed characters in carried filename: " ~ _name; } return ""; } /+ ↓ a relative path inside a pod, as markup and conf are carried +/ string validateCarriedPath(string _name) { string _common = _carriedNameCommon(_name); if (_common.length > 0) { return _common; } if (_name.length > MAX_CARRIED_PATH_LENGTH) { return "carried path too long: " ~ _name; } if (_name[$-1] == '/') { return "carried path names a directory: " ~ _name; } size_t _depth = 0; foreach (_c; _name) { if (_c == '/') { _depth++; } } if (_depth > MAX_CARRIED_PATH_DEPTH) { return "carried path too deep: " ~ _name; } /+ ↓ each component in turn, walked rather than split, so that this module needs no import that would leak into a mixing scope +/ size_t _from = 0; foreach (_i; 0 .. _name.length + 1) { if (_i < _name.length && _name[_i] != '/') { continue; } string _component = _name[_from .. _i]; if (_component.length == 0) { return "empty component in carried path: " ~ _name; } if (_component.length > MAX_CARRIED_NAME_LENGTH) { return "component too long in carried path: " ~ _name; } if (_component[0] == '.') { return "component begins with a dot in carried path: " ~ _name; } _from = _i + 1; } if (!(_name.matchFirst(rgx_safe_carried_path))) { return "disallowed characters in carried path: " ~ _name; } return ""; } /+ ↓ does _path, normalised, still sit inside _root? the check on the check +/ bool carriedPathIsWithin(string _root, string _path) { auto _canonical_root = (_root.asNormalizedPath).array.to!string; auto _canonical_path = (_path.asNormalizedPath).array.to!string; if (_canonical_root.length == 0 || _canonical_path.length <= _canonical_root.length ) { return false; } if (_canonical_path[0.._canonical_root.length] != _canonical_root) { return false; } return (_canonical_path[_canonical_root.length] == '/'); } }