Almirah 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4a6b0c92714af081d54b235449ab825fa86842d61869f31cd331a44c702efdc
-  data.tar.gz: cf2074e5c3f500689359912872166c1f13c08e59bde29408c90ee7b34fbe18fe
+  metadata.gz: 5221af43605bcaab2815ac5c940d53188394a92f8f8fadbbd2def016d1d52328
+  data.tar.gz: dd1d271774fe527d93512134b70cca3471048ff2a0859327c813eb75ebd35b54
 SHA512:
-  metadata.gz: 21654dccede23f1828f02b4446f11f626d12ee5d7d3689b96636d6b1be0465de44fddbacd05606935326a27d4317bfaf0b5596813e907a38580ea6591bc430ca
-  data.tar.gz: d3821259aeb7e5ff6306c3d9ccec25720030e659e351cd2c32a7791a8520ddea0039e6cab7f083b0244c82095e7c219c14de465bcda55b326eca184d06ce3bc7
+  metadata.gz: 6cf6a8d5892855c7b8752a2a3d447fec79dcf89a6a796b931709b2207ceeaddaede5cf7ac262ce13ab8b47aa081ead25fd225f353fff3afb84bc01dfaf2dfbdd
+  data.tar.gz: 9c0c6cffe8a41a19fc6778bcb0a3210f5a0ca3402b058d6b5f011b0434805fd11035be76a9ec6a742485839fe7523480d043923e582a2f0367c4fadb93922473

data/lib/almirah/doc_fabric.rb

@@ -65,6 +65,7 @@ class DocFabric
     DocFabric.parse_document doc
     doc.extract_current_status
     doc.extract_start_date
+    doc.extract_target_date
     doc.extract_target_release_version
     doc
   end

data/lib/almirah/doc_items/code_block.rb

@@ -19,7 +19,7 @@ class CodeBlock < DocItem
         end
         s += "<code>"
         @code_lines.each do |l|
-            s += l + " </br>"
+            s += escape_text(l) + " </br>" # ADR-188/SRS-096: code content is inert text
         end
         s += "</code>\n"
         return s

data/lib/almirah/doc_items/heading.rb

@@ -57,8 +57,26 @@ class Heading < Paragraph
     end
   end
 
+  # As get_section_info but with the author-supplied text HTML-escaped for safe
+  # interpolation into rendered HTML (headings, TOC, traceability). ADR-188/SRS-096.
+  def get_section_info_html
+    if level.zero? # Doc Title
+      escape_text(@text)
+    else
+      "#{@section_number} #{escape_text(@text)}"
+    end
+  end
+
   def get_anchor_text
-    "#{@section_number}-#{getTextWithoutSpaces}"
+    "#{@section_number}-#{anchor_slug}"
+  end
+
+  # The anchor is a generated identifier emitted into name/href attributes, so it
+  # must not carry the HTML-significant characters that author heading text may
+  # contain (ADR-188). Stripping them keeps the anchor inert and self-consistent
+  # across the heading, its self-link, and the table of contents.
+  def anchor_slug
+    getTextWithoutSpaces.gsub(/[<>"'&]/, '')
   end
 
   def get_markdown_anchor_text
@@ -72,10 +90,10 @@ class Heading < Paragraph
       @@html_table_render_in_progress = false
     end
     heading_level = level.to_s
-    heading_text = get_section_info
+    heading_text = get_section_info_html
     if level.zero?
-      heading_level = 1.to_s # Render Doc Title as a regular h1
-      heading_text = @text    # Doc Title does not have a section number
+      heading_level = 1.to_s        # Render Doc Title as a regular h1
+      heading_text = escape_text(@text) # Doc Title does not have a section number
     end
     s += "<a name=\"#{@anchor_id}\"></a>\n"
     s += "<h#{heading_level}> #{heading_text} <a href=\"\##{@anchor_id}\" class=\"heading_anchor\">"

data/lib/almirah/doc_items/image.rb

@@ -21,7 +21,14 @@ class Image < DocItem
             @@html_table_render_in_progress = false
         end
 
-        s += "<p style=\"margin-top: 15px;\"><img src=\"#{@path}\" alt=\"#{@text}\" "
+        alt = escape_attr(@text)
+        src = safe_url(@path)
+        if src.nil? # disallowed scheme: render inert rather than emitting it (ADR-188, SRS-098)
+            s += "<p style=\"margin-top: 15px;\">[image: #{alt}]"
+            return s
+        end
+
+        s += "<p style=\"margin-top: 15px;\"><img src=\"#{escape_attr(src)}\" alt=\"#{alt}\" "
         s += "href=\"javascript:void(0)\" onclick=\"image_OnClick(this)\">"
         return s
     end

data/lib/almirah/doc_items/markdown_table.rb

@@ -65,7 +65,7 @@ class MarkdownTable < DocItem
     s += "\t<thead>"
 
     @column_names.each do |h|
-      s += " <th>#{h}</th>"
+      s += " <th>#{format_string(h.strip)}</th>"
     end
 
     s += " </thead>\n"

data/lib/almirah/doc_items/text_line.rb

@@ -1,6 +1,7 @@
 require 'cgi'
 require 'uri'
 require_relative '../relative_url'
+require_relative '../html_safe'
 
 class TextLineToken
   attr_accessor :value
@@ -217,6 +218,12 @@ class TextLineParser
 end
 
 class TextLineBuilderContext
+  # Literal (non-markup) text run. Subclasses encode it for the HTML context;
+  # the base context leaves it untouched for plain reconstruction/unit tests.
+  def literal_text(str)
+    str
+  end
+
   def italic(str)
     str
   end
@@ -363,7 +370,11 @@ class TextLineBuilder
           tii += 1
         end
         if is_found
-          result += @builder_context.link(restore(sub_list_url_text), restore(sub_list_url_address))
+          # URL is reconstructed raw (not via restore) so scheme classification
+          # and file-path resolution see the original characters; link() applies
+          # attribute escaping and the scheme allow-list (ADR-188).
+          raw_url = (sub_list_url_address || []).map(&:value).join
+          result += @builder_context.link(restore(sub_list_url_text), raw_url)
         else
           result += '['
           ti = ti_starting_position + 1
@@ -373,7 +384,7 @@ class TextLineBuilder
         result += @builder_context.inline_code(token_list[ti].value)
         ti += 1
       when 'TextLineToken', 'ParentheseLeft', 'ParentheseRight', 'SquareBracketRight', 'DoubleSquareBracketRight'
-        result += token_list[ti].value
+        result += @builder_context.literal_text(token_list[ti].value)
         ti += 1
       else
         ti += 1
@@ -384,6 +395,8 @@ class TextLineBuilder
 end
 
 class TextLine < TextLineBuilderContext
+  include HtmlSafe
+
   @@link_registry = nil # rubocop:disable Style/ClassVars
   @@broken_links = [] # rubocop:disable Style/ClassVars
 
@@ -423,6 +436,11 @@ class TextLine < TextLineBuilderContext
     tlb.restore(tlp.tokenize(str))
   end
 
+  # Literal text run, HTML-escaped for element content (ADR-188, SRS-096).
+  def literal_text(str)
+    escape_text(str)
+  end
+
   def italic(str)
     "<i>#{str}</i>"
   end
@@ -445,12 +463,15 @@ class TextLine < TextLineBuilderContext
     case kind
     when :internal
       href = RelativeUrl.between(owner_document.output_rel_path, target.output_rel_path, fragment: fragment)
-      "<a href=\"#{href}\" class=\"external\">#{link_text}</a>"
+      "<a href=\"#{escape_attr(href)}\" class=\"external\">#{link_text}</a>"
     when :broken
       TextLine.record_broken_link(owner_document, raw)
-      "<a href=\"#{raw}\" class=\"broken_link\" title=\"Unresolved cross-document link\">#{link_text}</a>"
+      "<a href=\"#{escape_attr(raw)}\" class=\"broken_link\" title=\"Unresolved cross-document link\">#{link_text}</a>"
     else
-      "<a target=\"_blank\" rel=\"noopener\" href=\"#{raw}\" class=\"external\">#{link_text}</a>"
+      url = safe_url(raw)
+      return link_text if url.nil? # disallowed scheme: render inert (ADR-188, SRS-098)
+
+      "<a target=\"_blank\" rel=\"noopener\" href=\"#{escape_attr(url)}\" class=\"external\">#{link_text}</a>"
     end
   end
 

data/lib/almirah/doc_types/decision.rb

@@ -7,7 +7,7 @@ require_relative '../doc_items/markdown_table'
 
 class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metrics/ClassLength
   attr_accessor :path, :sequence_number, :record_type, :html_rel_path, :root_prefix, :current_status,
-                :start_date, :target_release_version, :specifications_path, :wrong_links_hash
+                :start_date, :target_date, :target_release_version, :specifications_path, :wrong_links_hash
 
   def initialize(file_path)
     super
@@ -16,6 +16,7 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
     assign_id_parts(stem)
     @current_status = nil
     @start_date = nil
+    @target_date = nil
     @target_release_version = nil
     @wrong_links_hash = {}
   end
@@ -49,6 +50,11 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
     @start_date = dates.min
   end
 
+  def extract_target_date
+    dates = collect_dates('Status', 'Date') + collect_dates('Scope', 'Target Date')
+    @target_date = dates.max
+  end
+
   def extract_target_release_version
     @target_release_version = lookup_cell(
       section_name: 'Software Versions',

data/lib/almirah/doc_types/decisions_overview.rb

@@ -54,7 +54,8 @@ class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Met
       s += "\t\t<td class=\"item_text\" style='padding: 5px;'>#{title_html}</td>\n"
       start_date_html = doc.start_date ? doc.start_date.strftime('%d-%m-%Y') : ''
       s += "\t\t<td class=\"item_meta\">#{start_date_html}</td>\n"
-      s += "\t\t<td class=\"item_meta\"></td>\n"
+      target_date_html = doc.target_date ? doc.target_date.strftime('%d-%m-%Y') : ''
+      s += "\t\t<td class=\"item_meta\">#{target_date_html}</td>\n"
       s += "\t\t<td class=\"item_meta\">#{doc.target_release_version}</td>\n"
       s += "\t\t<td class=\"item_meta\"></td>\n"
       s += "</tr>\n"

data/lib/almirah/doc_types/traceability.rb

@@ -75,7 +75,7 @@ class Traceability < BaseDocument
                 top_item.down_links.each do |bottom_item|
                     id_color = "style='background-color: ##{bottom_item.parent_doc.color};'"
                     bottom_f_text = bottom_item.format_string( bottom_item.text )
-                    document_section = bottom_item.parent_heading.get_section_info
+                    document_section = bottom_item.parent_heading.get_section_info_html
                     s += "\t<tr>\n"
                     s += "\t\t<td class=\"item_id\"><a href=\"./../#{top_item.parent_doc.id}/#{top_item.parent_doc.id}.html##{top_item.id}\" class=\"external\">#{top_item.id}</a></td>\n"
                     s += "\t\t<td class=\"item_text\" style='width: 34%;'>#{top_f_text}</td>\n"
@@ -105,7 +105,7 @@ class Traceability < BaseDocument
                     if bottom_item.parent_doc.id == @bottom_doc.id
 
                         bottom_f_text = bottom_item.format_string( bottom_item.text )
-                        document_section = bottom_item.parent_heading.get_section_info
+                        document_section = bottom_item.parent_heading.get_section_info_html
 
                         s += "\t<tr>\n"
                         s += "\t\t<td class=\"item_id\" #{id_color}><a href=\"./../#{top_item.parent_doc.id}/#{top_item.parent_doc.id}.html##{top_item.id}\" class=\"external\">#{top_item.id}</a></td>\n"

data/lib/almirah/dom/doc_section.rb

@@ -11,7 +11,7 @@ class DocSection
     s = ''
     s += "\t<li onclick=\"nav_toggle_expand_list(this, event)\">" \
       '<span class="fa-li"><i class="fa fa-minus-square-o"> </i></span>'
-    s += "<a href=\"##{@heading.anchor_id}\">#{@heading.get_section_info}</a>\n"
+    s += "<a href=\"##{@heading.anchor_id}\">#{@heading.get_section_info_html}</a>\n"
     unless @sections.empty?
       s += "\t\t<ul class=\"fa-ul\">\n"
       @sections.each do |sub_section|

data/lib/almirah/dom/document.rb

@@ -64,7 +64,7 @@ class Document
 
   def section_tree_to_html
     s = ''
-    s += "<a href=\"##{@root_section.heading.anchor_id}\">#{@root_section.heading.get_section_info}</a>\n"
+    s += "<a href=\"##{@root_section.heading.anchor_id}\">#{@root_section.heading.get_section_info_html}</a>\n"
     unless @root_section.sections.empty?
       s += "\t<ul class=\"fa-ul\" style=\"margin-top: 2px;\">\n"
       @root_section.sections.each do |sub_section|

data/lib/almirah/html_safe.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+# Shared HTML output-encoding helpers (ADR-188, SRS-096/097/098).
+#
+# Author-written Markdown is untrusted text and must be encoded for its HTML
+# context at the point of output. These helpers are the single mechanism every
+# renderer routes through, so coverage cannot drift item-by-item the way it did
+# when only inline code and wiki-link text were escaped.
+module HtmlSafe
+  # URL schemes permitted in link/image targets. Anything else (notably
+  # javascript:, data:, vbscript:) is treated as unsafe and rendered inert.
+  ALLOWED_URL_SCHEMES = %w[http https mailto].freeze
+
+  # Escapes literal text rendered into element content (the five characters:
+  # & < > " '). Used for paragraph, heading, blockquote, table-cell and fenced
+  # code block text. SRS-096.
+  def escape_text(str)
+    CGI.escapeHTML(str.to_s)
+  end
+
+  # Escapes a value interpolated into a quoted HTML attribute so it cannot
+  # terminate the attribute or introduce new attributes/elements. SRS-097.
+  def escape_attr(str)
+    CGI.escapeHTML(str.to_s)
+  end
+
+  # Returns the URL when it is a relative/anchor reference or carries an allowed
+  # scheme; returns nil for any other scheme so the caller can render the
+  # link/image inert. SRS-098.
+  def safe_url(raw)
+    url = raw.to_s.strip
+    scheme = url[/\A([a-z][a-z0-9+.-]*):/i, 1]
+    return url if scheme.nil? # relative path or anchor reference
+
+    ALLOWED_URL_SCHEMES.include?(scheme.downcase) ? url : nil
+  end
+end

data/lib/almirah/link_registry.rb

@@ -17,14 +17,14 @@ class LinkRegistry
   # Each registered document is expected to already carry an output_rel_path
   # (its generated page, relative to the build root).
   def register(doc)
-    key = doc.id.to_s.downcase
-    if @by_id.key?(key) && !@by_id[key].equal?(doc)
-      @collisions << key
-    else
-      @by_id[key] = doc
-    end
+    register_id(doc.id.to_s.downcase, doc)
     return unless doc.respond_to?(:path) && doc.path
 
+    # Also index by the filename stem so a document resolves by filename, not
+    # only by id (SRS-090). For specs/protocols the stem equals the id; for
+    # decision records the id is the truncated <letters>-<digits> prefix, so the
+    # full stem (e.g. "adr-170-introduce-decision-records") is a distinct alias.
+    register_id(File.basename(doc.path, '.*').downcase, doc)
     @by_source[File.expand_path(doc.path)] = doc
   end
 
@@ -35,4 +35,19 @@ class LinkRegistry
   def find_by_source(source_path)
     @by_source[File.expand_path(source_path)]
   end
+
+  private
+
+  # Adds an id/stem key for a document, recording a collision only when the key
+  # already maps to a different document. Registering the same document under
+  # both its id and its filename stem is expected and not a collision.
+  def register_id(key, doc)
+    return if key.empty?
+
+    if @by_id.key?(key) && !@by_id[key].equal?(doc)
+      @collisions << key
+    else
+      @by_id[key] = doc
+    end
+  end
 end

data/lib/almirah/templates/css/main.css

@@ -1,3 +1,8 @@
+html {
+    /* Leave room for the fixed #top_nav so in-page anchor links
+       are not hidden behind it when navigating to them. */
+    scroll-padding-top: 40px;
+}
 body {
     font-family: Verdana, sans-serif;
     font-size: 12px;
@@ -224,7 +229,9 @@ img{
     background: #EEEEEE;
     border: 1px solid #ddd;
     position: fixed;
-    height: 100%;       /* 100% Full-height */
+    top: 0;             /* Anchor top and bottom so the pane spans exactly the   */
+    bottom: 0;          /* viewport; padding/border stay inside the border box so */
+                        /* overflow-y scroll can reach the last items.            */
     visibility: hidden;
     z-index: 1;
     overflow-y: auto;

data/lib/almirah/templates/scripts/main.js

@@ -74,7 +74,10 @@ function openNav() {
   
       modal.style.display = "block";
       modalImg.src = clicked.src;
-      captionText.innerHTML = clicked.alt;
+      // Author-supplied alt text: insert as plain text, never as HTML (ADR-188).
+      // Reading clicked.alt yields the decoded value, so innerHTML here would
+      // re-parse author markup as live DOM (DOM-based XSS).
+      captionText.textContent = clicked.alt;
   }
   
   function modal_close_OnClick(clicked){

data/lib/almirah/templates/scripts/orama_search.js

@@ -1,6 +1,18 @@
 // Do search only on the Index Page
 import { create, search, insert } from 'https://unpkg.com/@orama/orama@3.1.18/dist/browser/index.js'
 
+// Author-derived values are treated as untrusted (ADR-188). Every result field
+// is inserted with safe DOM interfaces (createTextNode / property assignment) and
+// never parsed as HTML, and any URL is admitted only if it is a relative reference
+// or uses an allowed scheme; otherwise the link is rendered inert.
+const ALLOWED_URL_SCHEMES = ['http', 'https', 'mailto'];
+function safeUrl(url) {
+    const s = (url == null ? '' : String(url)).trim();
+    const m = s.match(/^([a-z][a-z0-9+.-]*):/i);
+    if (!m) return s;                                  // relative path or anchor
+    return ALLOWED_URL_SCHEMES.includes(m[1].toLowerCase()) ? s : '#';
+}
+
 // Create DB
 const db = await create({
     schema: {
@@ -87,19 +99,20 @@ async function search_onKeyUp(){
             let cell = document.createElement("td");
             let i = document.createElement("i");
                 i.classList.add("fa","fa-file-text-o");
-                i.style.backgroundColor = "#" + doc_color;
+                if (/^[0-9a-fA-F]{3,8}$/.test(doc_color)) {
+                    i.style.backgroundColor = "#" + doc_color;
+                }
                 cell.appendChild(i);
             let textnode = document.createTextNode("\xa0" + doc_title);
             cell.appendChild(textnode);
             row.appendChild(cell)
             cell = document.createElement("td");
             
-            const a = document.createElement('a'); 
+            const a = document.createElement('a');
             const link = document.createTextNode(heading_text)
             a.appendChild(link);
             a.title = heading_text;
-            a.href = heading_url;
-            document.body.appendChild(a); 
+            a.href = safeUrl(heading_url);
 
             cell.appendChild(a);
             row.appendChild(cell)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: Almirah
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Oleksandr Ivanov
@@ -90,6 +90,7 @@ files:
 - lib/almirah/doc_types/traceability.rb
 - lib/almirah/dom/doc_section.rb
 - lib/almirah/dom/document.rb
+- lib/almirah/html_safe.rb
 - lib/almirah/link_registry.rb
 - lib/almirah/navigation_pane.rb
 - lib/almirah/project.rb