Guides image + draft gating, audit retention, ADR-015 gate, backup credential redaction

plugins/guides/frontend/components/GuideBlocks.vue

@@ -72,8 +72,27 @@
         <pre :ref="el => registerCode(block.id, el)"><code>{{ block.text }}</code></pre>
       </div>
 
+      <!--
+        The image is fetched by script, not by the browser.
+
+        An <img src> is a plain browser request: it carries no Authorization
+        header, and this app keeps its JWT in one. So a direct src against the
+        authenticated image route is a 401 and a broken-image icon for every
+        reader - which is exactly how this shipped. Fetching through the api
+        client sends the token, and it resolves against the client's baseURL, so
+        it also survives a subpath mount that a stored '/api/...' string does
+        not.
+
+        A failure says so in words. A guide whose screenshot is missing must not
+        look like a guide that never had one.
+      -->
       <figure v-else-if="block.type === 'image'" class="gb-figure">
-        <img :src="block.url" :alt="block.alt || ''" loading="lazy">
+        <img v-if="imageState(block).src" :src="imageState(block).src"
+             :alt="block.alt || ''">
+        <p v-else-if="imageState(block).failed" class="gb-imagefailed">
+          Image unavailable{{ block.alt ? ': ' + block.alt : '' }}
+        </p>
+        <p v-else class="gb-imageloading">Loading image...</p>
         <figcaption v-if="block.caption">{{ block.caption }}</figcaption>
       </figure>
 
@@ -97,8 +116,9 @@
 </template>
 
 <script setup>
-import { ref, computed } from 'vue'
+import { ref, computed, toRef } from 'vue'
 import { renderInline } from '../utils/inline.js'
+import { useGuideImages } from '../utils/images.js'
 
 const props = defineProps({
   blocks: { type: Array, default: () => [] },
@@ -112,6 +132,9 @@ const selected = ref('')
 const codeNodes = {}
 function registerCode (id, el) { if (el) codeNodes[id] = el }
 
+// Images are fetched by script, not by <img src>; see utils/images.js.
+const { state: imageState } = useGuideImages(toRef(props, 'blocks'))
+
 function inline (text) {
   return renderInline(text)
 }
@@ -226,6 +249,12 @@ function select (block) {
 
 .gb-figure { margin: 0 0 1.2rem; }
 .gb-figure img { max-width: 100%; height: auto; border: 1px solid var(--border); border-radius: 4px; }
+.gb-imageloading, .gb-imagefailed {
+  margin: 0; padding: 0.75rem 1rem; border: 1px dashed var(--border);
+  border-radius: 4px; font-size: 0.9rem;
+}
+.gb-imageloading { color: var(--textmuted); }
+.gb-imagefailed { color: var(--danger, #b3261e); }
 .gb-figure figcaption { font-size: 0.8rem; color: var(--text-light); margin-top: 0.35rem; }
 
 .gb-tablewrap { overflow-x: auto; margin: 0 0 1.2rem; }

plugins/guides/frontend/utils/images.js

@@ -0,0 +1,77 @@
+/**
+ * Resolving guide images.
+ *
+ * A guide image lives behind an authenticated route, and an <img src> is a
+ * plain browser request that carries no Authorization header - this app keeps
+ * its JWT in one. Pointing src at the image route therefore yields 401 and a
+ * broken-image icon for every reader, which is how guides first shipped.
+ *
+ * So the bytes are fetched through the api client, which attaches the token and
+ * resolves against its own baseURL - the latter also fixing a stored
+ * '/api/guides/images/N' string under a subpath mount, where the API is not at
+ * /api at all.
+ *
+ * Used by the renderer AND the editor: an author needs to see the screenshot
+ * they just pasted as much as a reader does.
+ */
+import { reactive, watch, onBeforeUnmount } from 'vue'
+import api from '@/api'
+
+/** The image id a block refers to, whichever way it was written.
+ *
+ * Blocks store imageid (written since this was fixed) or a url string (written
+ * before it). The url is never used as a src, only read for its id.
+ */
+export function imageIdOf (block) {
+  if (!block) return ''
+  if (block.imageid) return String(block.imageid)
+  const match = /\/guides\/images\/(\d+)/.exec(block.url || '')
+  return match ? match[1] : ''
+}
+
+/**
+ * Keeps object URLs for the image blocks in `blocksRef`, fetching each id once
+ * however many blocks use it, and revoking them as blocks go away.
+ *
+ * Returns `state(block)` -> { src, failed }.
+ */
+export function useGuideImages (blocksRef) {
+  const images = reactive({})
+
+  async function load (id) {
+    if (images[id]) return
+    images[id] = { src: '', failed: false }
+    try {
+      const response = await api.get(`/guides/images/${id}`, { responseType: 'blob' })
+      images[id].src = URL.createObjectURL(response.data)
+    } catch (err) {
+      images[id].failed = true
+    }
+  }
+
+  function release (id) {
+    if (images[id] && images[id].src) URL.revokeObjectURL(images[id].src)
+    delete images[id]
+  }
+
+  function state (block) {
+    const id = imageIdOf(block)
+    if (!id) return { src: '', failed: true }
+    return images[id] || { src: '', failed: false }
+  }
+
+  // Editing replaces the block list on every keystroke, so resolve only ids
+  // that are new and keep the ones already held. Without that, every keystroke
+  // would refetch every image in the guide.
+  watch(blocksRef, blocks => {
+    const wanted = new Set(
+      (blocks || []).filter(b => b && b.type === 'image')
+        .map(imageIdOf).filter(Boolean))
+    wanted.forEach(load)
+    Object.keys(images).forEach(id => { if (!wanted.has(id)) release(id) })
+  }, { immediate: true, deep: true })
+
+  onBeforeUnmount(() => { Object.keys(images).forEach(release) })
+
+  return { state }
+}

plugins/guides/frontend/utils/inline.js

@@ -27,12 +27,29 @@ function escapeHtml (text) {
     .replace(/'/g, ''')
 }
 
+// The text was HTML-escaped before any pattern ran, so a captured URL arrives
+// carrying entities: a real query string like ?a=1&b=2 reaches here as
+// ?a=1&b=2. Escaping that again for the attribute produced & and a
+// link that opened the wrong record - the ServiceNow and SharePoint links that
+// carry several parameters were all broken this way. Decode first, then let the
+// single escape on output put back exactly one level.
+function decodeEntities (text) {
+  return String(text)
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&')   // last, so &amp;lt; does not become <
+}
+
 // Only http(s) and mailto. A javascript: or data: URL in a link is the one way
 // an author could otherwise smuggle script past the escaping above.
 function safeHref (url) {
   const trimmed = String(url || '').trim()
   if (/^(https?:|mailto:)/i.test(trimmed)) return trimmed
-  if (trimmed.startsWith('/')) return trimmed   // in-app link
+  // In-app link. NOT '//host', which looks like a path and is read by the
+  // browser as protocol-relative - an off-site link wearing a local costume.
+  if (trimmed.startsWith('/') && !trimmed.startsWith('//')) return trimmed
   return null
 }
 
@@ -50,13 +67,18 @@ export function renderInline (text) {
   // [label](url). The URL pattern allows ONE level of balanced parentheses so
   // real links survive - Wikipedia-style /wiki/Foo_(bar) is the common case,
   // and a naive [^)]+ silently truncates it into a broken link.
+  // Finished links are stashed like code spans, so the emphasis passes below
+  // cannot reach inside an href. Without that, a URL containing *characters*
+  // has <em> injected into the middle of the attribute and the link breaks.
+  const links = []
   html = html.replace(/\[([^\]]+)\]\(((?:[^()\s]|\([^()\s]*\))+)\)/g, (match, label, url) => {
-    const href = safeHref(url)
+    const href = safeHref(decodeEntities(url))
     if (!href) return label
     const external = /^https?:/i.test(href)
-    return '<a href="' + escapeHtml(href) + '"' +
+    links.push('<a href="' + escapeHtml(href) + '"' +
       (external ? ' target="_blank" rel="noopener noreferrer"' : '') +
-      '>' + label + '</a>'
+      '>' + label + '</a>')
+    return '\u0000LINK' + (links.length - 1) + '\u0000'
   })
 
   // **bold** then *italic*, longest marker first so **x** is not read as
@@ -66,6 +88,8 @@ export function renderInline (text) {
 
   html = html.replace(/\n/g, '<br>')
 
+  html = html.replace(/\u0000LINK(\d+)\u0000/g, (match, index) => links[Number(index)])
+
   html = html.replace(/\u0000CODE(\d+)\u0000/g, (match, index) =>
     '<code>' + codeSpans[Number(index)] + '</code>')
 

plugins/guides/frontend/utils/inline.spec.js

@@ -0,0 +1,50 @@
+/**
+ * Inline rendering: the security model and the link bugs it hid.
+ *
+ * Escape-then-format is the whole defence, and it has one awkward consequence
+ * that produced real broken links: by the time a URL is captured it is already
+ * escaped, so it has to be decoded before it can be escaped again exactly once.
+ */
+import { describe, it, expect } from 'vitest'
+import { renderInline } from './inline.js'
+
+describe('renderInline', () => {
+  it('escapes markup an author pasted', () => {
+    expect(renderInline('<img src=x onerror=alert(1)>'))
+      .toBe('&lt;img src=x onerror=alert(1)&gt;')
+  })
+
+  it('keeps a multi-parameter URL intact', () => {
+    // Double-escaped, this became &amp;amp; and the link opened the wrong
+    // record. Every ServiceNow and SharePoint link carries several parameters.
+    const html = renderInline('[ticket](https://x.example/nav?a=1&b=2&c=3)')
+    expect(html).toContain('href="https://x.example/nav?a=1&amp;b=2&amp;c=3"')
+    expect(html).not.toContain('&amp;amp;')
+  })
+
+  it('does not let emphasis reach inside an href', () => {
+    const html = renderInline('[t](https://x.example/a*b*c)')
+    expect(html).toContain('href="https://x.example/a*b*c"')
+    expect(html).not.toContain('<em>')
+  })
+
+  it('refuses a protocol-relative URL dressed as an in-app path', () => {
+    // '//evil.example' starts with '/' but the browser reads it as off-site.
+    expect(renderInline('[evil](//evil.example/x)')).toBe('evil')
+  })
+
+  it('refuses javascript: and keeps the label', () => {
+    expect(renderInline('[bad](javascript:alert(1))')).toBe('bad')
+  })
+
+  it('allows an in-app link', () => {
+    expect(renderInline('[map](/map)')).toBe('<a href="/map">map</a>')
+  })
+
+  it('still renders bold, italic and code', () => {
+    expect(renderInline('**b**')).toBe('<strong>b</strong>')
+    expect(renderInline('*i*')).toBe('<em>i</em>')
+    expect(renderInline('`C:\\**temp**`'))
+      .toBe('<code>C:\\**temp**</code>')
+  })
+})

plugins/guides/frontend/views/GuideEditor.vue

@@ -142,7 +142,12 @@
           </div>
 
           <div v-if="block.type === 'image'" class="ge-image">
-            <img v-if="block.url" :src="block.url" alt="">
+            <!-- Same authenticated fetch as the reader's view: an author must
+                 see the screenshot they just pasted. -->
+            <img v-if="imageState(block).src" :src="imageState(block).src" alt="">
+            <p v-else-if="imageState(block).failed" class="ge-imagefailed">
+              Image unavailable - it may have been removed
+            </p>
             <input v-model="block.caption" placeholder="Caption (optional)">
             <input v-model="block.alt" placeholder="Alt text, for anyone who cannot see it">
           </div>
@@ -203,6 +208,7 @@ import { useAuthStore } from '@/stores/auth'
 import GuideBlocks from '../components/GuideBlocks.vue'
 import { templates } from '../utils/templates.js'
 import { proof, applyFix } from '../utils/proof.js'
+import { useGuideImages } from '../utils/images.js'
 
 const route = useRoute()
 const router = useRouter()
@@ -382,7 +388,10 @@ async function insertImage (file) {
   status.value = 'Uploading image...'
   try {
     const image = await uploadImage(file)
-    const block = { id: newid(), type: 'image', url: image.url, caption: '', alt: '' }
+    // imageid is what the renderer resolves; url stays for older readers and
+    // for anything that still treats a block as a plain document.
+    const block = { id: newid(), type: 'image', imageid: image.guideimageid,
+                    url: image.url, caption: '', alt: '' }
     blocks.value.splice(insertIndex(), 0, block)
     focused.value = block.id
     status.value = ''
@@ -413,15 +422,21 @@ function onFilePick (event) {
   event.target.value = ''
 }
 
+// Editor thumbnails resolve the same way the reader's do; see utils/images.js.
+const { state: imageState } = useGuideImages(blocks)
+
 function payload () {
   return { title: guide.title, summary: guide.summary || '',
            tags: guide.tags || '', blocks: blocks.value }
 }
 
+// Returns whether the save actually reached the server. publish() depends on
+// that answer: a publish that runs after a failed save promotes the LAST
+// revision the server accepted, which is not what is on the author's screen.
 async function save (quiet) {
   if (!guide.title.trim()) {
     if (!quiet) error.value = 'A guide needs a title before it can be saved'
-    return
+    return false
   }
   saving.value = true
   error.value = ''
@@ -439,9 +454,11 @@ async function save (quiet) {
     dirty.value = false
     status.value = 'Saved ' + new Date().toLocaleTimeString()
     await loadRevisions()
+    return true
   } catch (err) {
     error.value = apiError(err, 'Could not save this guide')
     status.value = 'Not saved'
+    return false
   } finally {
     saving.value = false
   }
@@ -476,7 +493,14 @@ async function publish () {
       + 'anything flagged in a command. Publish anyway?')
     if (!ok) return
   }
-  await save(true)
+  // Publishing promotes the newest SAVED revision, so an unsaved edit is not
+  // in what readers get. Reporting "Published version 4" over a failed save
+  // tells the author their words went out when the old ones did.
+  if (!await save(true)) {
+    error.value = error.value
+      || 'Could not save this guide, so it was not published'
+    return
+  }
   try {
     const response = await api.post('/guides/' + guide.guideid + '/publish')
     guide.ispublished = true
@@ -637,6 +661,8 @@ onMounted(async () => {
   background: transparent; color: var(--text-light); border-radius: 3px;
   cursor: pointer; justify-self: start;
 }
+.ge-imagefailed { margin: 0 0 0.35rem; padding: 0.5rem 0.7rem; font-size: 0.85rem;
+  color: var(--danger, #b3261e); border: 1px dashed var(--border); border-radius: 4px; }
 .ge-image img { max-width: 18rem; display: block; margin-bottom: 0.35rem;
                 border: 1px solid var(--border); border-radius: 4px; }
 .ge-image input { width: 100%; margin-bottom: 0.25rem; padding: 0.3rem 0.45rem;