tenseleyflow/shithub / be5f355

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package extensions

+

+// emojiMap is a small curated set of emoji shortcodes mapped to

+// their unicode rune sequences. Sourced from the gemoji project's

+// stable subset; we deliberately avoid trending/political shortcodes.

+//

+// Adding a shortcode: append below + bump `markdown.Version`. Bytes

+// are direct UTF-8 (no escape sequences) so the file's bytes are

+// the rendered output.

+var emojiMap = map[string]string{

+	// Common reactions

+	"+1":              "👍",

+	"-1":              "👎",

+	"thumbsup":        "👍",

+	"thumbsdown":      "👎",

+	"smile":           "😄",

+	"laughing":        "😆",

+	"joy":             "😂",

+	"heart":           "❤️",

+	"heart_eyes":      "😍",

+	"tada":            "🎉",

+	"rocket":          "🚀",

+	"fire":            "🔥",

+	"sparkles":        "✨",

+	"eyes":            "👀",

+	"thinking":        "🤔",

+	"thinking_face":   "🤔",

+	"wave":            "👋",

+	"clap":            "👏",

+	"pray":            "🙏",

+	"100":             "💯",

+	"check":           "✅",

+	"x":               "❌",

+	"warning":         "⚠️",

+	"bug":             "🐛",

+	"sparkle":         "✨",

+	"star":            "⭐",

+	"hammer":          "🔨",

+	"wrench":          "🔧",

+	"package":         "📦",

+	"books":           "📚",

+	"book":            "📖",

+	"memo":            "📝",

+	"pencil":          "✏️",

+	"shipit":          "🚢",

+	"ship":            "🚢",

+	"lock":            "🔒",

+	"unlock":          "🔓",

+	"key":             "🔑",

+	"link":            "🔗",

+	"speech_balloon":  "💬",

+	"thought_balloon": "💭",

+	"computer":        "💻",

+	"keyboard":        "⌨️",

+	"floppy_disk":     "💾",

+	"cd":              "💿",

+	"dvd":             "📀",

+	"clipboard":       "📋",

+	"chart":           "📈",

+	"bar_chart":       "📊",

+	"calendar":        "📅",

+	"date":            "📆",

+	"hourglass":       "⌛",

+	"alarm_clock":     "⏰",

+	"clock1":          "🕐",

+	"bell":            "🔔",

+	"no_bell":         "🔕",

+	"loudspeaker":     "📢",

+	"mega":            "📣",

+	"mailbox":         "📫",

+	"envelope":        "✉️",

+	"postbox":         "📮",

+	"package_2":       "📮",

+	"mag":             "🔍",

+	"telescope":       "🔭",

+	"microscope":      "🔬",

+	"hammer_and_wrench": "🛠️",

+	"gear":              "⚙️",

+	"toolbox":           "🧰",

+	"nut_and_bolt":      "🔩",

+	"satellite":         "📡",

+	"globe":             "🌍",

+	"earth_americas":    "🌎",

+	"earth_asia":        "🌏",

+	"new":               "🆕",

+	"free":              "🆓",

+	"abc":               "🔤",

+	"abcd":              "🔡",

+	"capital_abcd":      "🔠",

+	"information_source": "ℹ️",

+	"interrobang":        "⁉️",

+	"question":           "❓",

+	"grey_question":      "❔",

+	"exclamation":        "❗",

+	"grey_exclamation":   "❕",

+	"o":                  "⭕",

+	"x_circle":           "❌",

+	"white_check_mark":   "✅",

+	"ballot_box_with_check": "☑️",

+	"heavy_check_mark":      "✔️",

+	"heavy_multiplication_x": "✖️",

+	"heavy_plus_sign":        "➕",

+	"heavy_minus_sign":       "➖",

+	"heavy_division_sign":    "➗",

+	"recycle":                "♻️",

+	"infinity":               "♾️",

+	"trophy":                 "🏆",

+	"medal":                  "🏅",

+	"first_place":            "🥇",

+	"second_place":           "🥈",

+	"third_place":            "🥉",

+	"crown":                  "👑",

+	"gem":                    "💎",

+	"art":                    "🎨",

+	"musical_note":           "🎵",

+	"musical_score":           "🎼",

+	"sound":                  "🔊",

+	"mute":                   "🔇",

+	"video_camera":           "📹",

+	"camera":                 "📷",

+	"camera_flash":           "📸",

+	"film_strip":             "🎞️",

+	"clapper":                "🎬",

+	"microphone":             "🎤",

+	"headphones":             "🎧",

+	"radio":                  "📻",

+	"tv":                     "📺",

+	"phone":                  "📞",

+	"telephone":              "☎️",

+	"iphone":                 "📱",

+	"calling":                "📲",

+	"battery":                "🔋",

+	"electric_plug":          "🔌",

+	"bulb":                   "💡",

+	"flashlight":             "🔦",

+	"candle":                 "🕯️",

+	"sun":                    "☀️",

+	"sunny":                  "☀️",

+	"moon":                   "🌙",

+	"star_2":                 "🌟",

+	"stars":                  "🌠",

+	"cloud":                  "☁️",

+	"snowflake":              "❄️",

+	"zap":                    "⚡",

+	"umbrella":               "☂️",

+	"rainbow":                "🌈",

+	"droplet":                "💧",

+	"ocean":                  "🌊",

+	"snowman":                "☃️",

+	"comet":                  "☄️",

+	"v":                      "✌️",

+	"point_up":               "☝️",

+	"point_down":             "👇",

+	"point_left":             "👈",

+	"point_right":            "👉",

+	"raised_hand":            "✋",

+	"open_hands":             "👐",

+	"muscle":                 "💪",

+	"writing_hand":           "✍️",

+	"selfie":                 "🤳",

+	"facepunch":              "👊",

+	"fist":                   "✊",

+	"poo":                    "💩",

+	"hankey":                 "💩",

+	"shit":                   "💩",

+}

+

+// lookupEmoji returns the unicode replacement for a shortcode,

+// or ("", false) if the code isn't in our curated set.

+func lookupEmoji(name string) (string, bool) {

+	v, ok := emojiMap[name]

+	return v, ok

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+// Package extensions hosts the AST transformer that adds shithub-

+// specific inline patterns (`@user`, `#N`, `owner/repo#N`, commit

+// SHAs, emoji shortcodes) to Goldmark's parsed text without ever

+// touching the contents of code blocks or inline code.

+//

+// Approach: a single `parser.ASTTransformer` walks the document

+// after parsing, visiting only `*ast.Text` nodes whose ancestors

+// are NOT code/codespan/autolink/link nodes. Each visited text node

+// is run through one combined regex; matches are replaced with

+// `*ast.Link` (mention/ref/commit) or `*ast.String` (emoji) nodes,

+// with the surrounding text preserved as `*ast.String` segments.

+//

+// Why an ASTTransformer instead of inline parsers: inline parsers

+// run during the main parse pass and need a `Trigger()` byte set

+// plus careful interaction with Goldmark's existing inline

+// disambiguation. The transformer approach is simpler, well-trodden

+// in other Go markdown stacks, and produces equivalent output for

+// every input we care about.

+package extensions

+

+import (

+	"bytes"

+	"context"

+	"regexp"

+	"strconv"

+	"strings"

+

+	"github.com/yuin/goldmark"

+	"github.com/yuin/goldmark/ast"

+	"github.com/yuin/goldmark/parser"

+	"github.com/yuin/goldmark/text"

+	"github.com/yuin/goldmark/util"

+)

+

+// Resolvers wires the transformer against the runtime. The fields

+// are independent so the parent package can decide which flavors

+// to enable. nil-resolver means "render this kind as plain text"

+// (no link, no error).

+//

+// All resolvers MUST be visibility-aware. The transformer does not

+// re-check visibility — it trusts the resolver's `ok` to gate

+// existence.

+type Resolvers struct {

+	User func(ctx context.Context, username string) (href string, ok bool)

+	// Issue covers both same-repo (#N when ownerHint == "") and

+	// cross-repo (owner/repo#N).

+	Issue func(ctx context.Context, ownerHint, repoHint string, number int64, viewerUserID int64) (href string, ok bool)

+	// Commit is invoked only when RepoOwner+RepoName are both set

+	// (a same-repo render) and the matched token is a 7-40 char

+	// lowercase hex string at a word boundary.

+	Commit func(ctx context.Context, repoOwner, repoName, shaPrefix string) (href, fullSHA string, ok bool)

+}

+

+// Options is the per-render config consumed by the transformer.

+type Options struct {

+	Ctx          context.Context

+	RepoOwner    string

+	RepoName     string

+	ViewerUserID int64

+	Resolvers    Resolvers

+	// Refs and Mentions accumulate resolved references for the caller.

+	// Pointers so the transformer can append.

+	Refs     *[]Ref

+	Mentions *[]Mention

+}

+

+// Ref / Mention mirror the parent-package types; we redeclare to

+// avoid an import cycle.

+type Ref struct {

+	Kind    string

+	Owner   string

+	Repo    string

+	Number  int64

+	FullSHA string

+	Href    string

+}

+

+type Mention struct {

+	Username string

+	Href     string

+}

+

+// reCombined matches every pattern in one pass. Order in the

+// alternation is by how they appear in source after parsing — left

+// to right. Capture groups:

+//

+//	(?:^|[^\w/])     leading boundary (consumed but reattached as text)

+//	#1               cross-repo: owner / repo / number

+//	#4               same-repo: number

+//	#5               mention: username

+//	#6               commit prefix

+//	#7               emoji name

+var reCombined = regexp.MustCompile(`` +

+	// cross-repo: alice/proj#3

+	`([A-Za-z0-9][A-Za-z0-9._-]*)/([A-Za-z0-9][A-Za-z0-9._-]*)#([0-9]{1,9})\b` +

+	// or same-repo: #3 — must have non-word non-/ boundary on the left

+	`|(?:^|[^\w/])#([0-9]{1,9})\b` +

+	// or mention: @alice — must have non-word boundary on the left

+	`|(?:^|[^\w])@([A-Za-z0-9][A-Za-z0-9_-]{0,38})\b` +

+	// or commit SHA: 7–40 lowercase hex, word-boundary on both sides

+	`|(?:^|[^\w/])([0-9a-f]{7,40})\b` +

+	// or emoji shortcode: :smile:

+	`|:([a-z0-9_+\-]+):`,

+)

+

+// Extension is a goldmark.Extender that registers the AST transformer.

+type Extension struct{ Opts *Options }

+

+// New constructs the extender with the given options.

+func New(opts *Options) goldmark.Extender { return &Extension{Opts: opts} }

+

+// Extend implements goldmark.Extender.

+func (e *Extension) Extend(m goldmark.Markdown) {

+	m.Parser().AddOptions(parser.WithASTTransformers(

+		util.Prioritized(&transformer{opts: e.Opts}, 999),

+	))

+}

+

+type transformer struct{ opts *Options }

+

+// Transform walks the document and replaces matched text segments.

+func (t *transformer) Transform(doc *ast.Document, reader text.Reader, _ parser.Context) {

+	if t.opts == nil {

+		return

+	}

+	source := reader.Source()

+	_ = ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {

+		if !entering {

+			return ast.WalkContinue, nil

+		}

+		// Skip subtrees that should never be linkified.

+		switch n.(type) {

+		case *ast.CodeSpan, *ast.AutoLink, *ast.Link, *ast.Image,

+			*ast.FencedCodeBlock, *ast.CodeBlock, *ast.RawHTML, *ast.HTMLBlock:

+			return ast.WalkSkipChildren, nil

+		}

+		txt, ok := n.(*ast.Text)

+		if !ok {

+			return ast.WalkContinue, nil

+		}

+		t.replaceText(txt, source)

+		return ast.WalkContinue, nil

+	})

+}

+

+// replaceText finds matches in the segment of `txt` and inserts

+// new sibling nodes (string runs + links) before the original text;

+// the original text is removed once everything's stitched in.

+func (t *transformer) replaceText(txt *ast.Text, source []byte) {

+	body := txt.Segment.Value(source)

+	matches := reCombined.FindAllSubmatchIndex(body, -1)

+	if len(matches) == 0 {

+		return

+	}

+	parent := txt.Parent()

+	if parent == nil {

+		return

+	}

+

+	cursor := 0

+	for _, m := range matches {

+		matchStart, matchEnd := m[0], m[1]

+

+		// Determine which alternation captured + where the visible

+		// content starts (excluding the regex-consumed boundary

+		// char, if any).

+		var (

+			isCrossRepo = m[2] >= 0

+			isSameRepo  = m[8] >= 0

+			isMention   = m[10] >= 0

+			isCommit    = m[12] >= 0

+			isEmoji     = m[14] >= 0

+		)

+		var contentStart int

+		switch {

+		case isCrossRepo:

+			contentStart = m[2]

+		case isSameRepo:

+			contentStart = m[8] - 1 // include `#`

+		case isMention:

+			contentStart = m[10] - 1 // include `@`

+		case isCommit:

+			contentStart = m[12]

+		case isEmoji:

+			contentStart = m[14] - 1 // include leading `:`

+		}

+

+		// Emit (a) any text between the previous cursor and the

+		// match start, then (b) the consumed-but-not-content

+		// boundary char (when contentStart > matchStart). Both into

+		// the parent before the original text node.

+		if matchStart > cursor {

+			t.insertText(parent, txt, body[cursor:matchStart])

+		}

+		if contentStart > matchStart {

+			t.insertText(parent, txt, body[matchStart:contentStart])

+		}

+

+		// Now emit the resolved (or fallback-plain) match content.

+		display := body[contentStart:matchEnd]

+		switch {

+		case isCrossRepo:

+			owner := string(body[m[2]:m[3]])

+			repo := string(body[m[4]:m[5]])

+			numStr := string(body[m[6]:m[7]])

+			if !t.appendIssueLink(parent, txt, owner, repo, numStr, display) {

+				t.insertText(parent, txt, display)

+			}

+		case isSameRepo:

+			numStr := string(body[m[8]:m[9]])

+			if !t.appendIssueLink(parent, txt, "", "", numStr, display) {

+				t.insertText(parent, txt, display)

+			}

+		case isMention:

+			name := string(body[m[10]:m[11]])

+			if !t.appendMentionLink(parent, txt, name, display) {

+				t.insertText(parent, txt, display)

+			}

+		case isCommit:

+			sha := string(body[m[12]:m[13]])

+			if !t.appendCommitLink(parent, txt, sha, display) {

+				t.insertText(parent, txt, display)

+			}

+		case isEmoji:

+			name := string(body[m[14]:m[15]])

+			if uni, ok := lookupEmoji(name); ok {

+				t.insertText(parent, txt, []byte(uni))

+			} else {

+				t.insertText(parent, txt, display)

+			}

+		}

+		cursor = matchEnd

+	}

+	// Trailing text after the last match.

+	if cursor < len(body) {

+		t.insertText(parent, txt, body[cursor:])

+	}

+	parent.RemoveChild(parent, txt)

+}

+

+// insertText appends a string node before the original text node

+// (which is removed at the end of replaceText).

+func (t *transformer) insertText(parent, before ast.Node, b []byte) {

+	if len(b) == 0 {

+		return

+	}

+	s := ast.NewString(append([]byte(nil), b...))

+	parent.InsertBefore(parent, before, s)

+}

+

+// appendIssueLink resolves an issue/PR ref and inserts a Link node.

+// `display` is the visible text the user typed (e.g. "#42" or

+// "alice/proj#5"). Returns false when the resolver declines (in

+// which case the caller renders the display text as plain text —

+// no link, no existence leak).

+func (t *transformer) appendIssueLink(parent, before ast.Node, owner, repo, numStr string, display []byte) bool {

+	if t.opts.Resolvers.Issue == nil {

+		return false

+	}

+	num, err := strconv.ParseInt(numStr, 10, 64)

+	if err != nil {

+		return false

+	}

+	href, ok := t.opts.Resolvers.Issue(t.opts.Ctx, owner, repo, num, t.opts.ViewerUserID)

+	if !ok {

+		return false

+	}

+	link := ast.NewLink()

+	link.Destination = []byte(href)

+	link.AppendChild(link, ast.NewString(append([]byte(nil), display...)))

+	parent.InsertBefore(parent, before, link)

+

+	if t.opts.Refs != nil {

+		*t.opts.Refs = append(*t.opts.Refs, Ref{

+			Kind:   "issue",

+			Owner:  owner,

+			Repo:   repo,

+			Number: num,

+			Href:   href,

+		})

+	}

+	return true

+}

+

+// appendMentionLink resolves a @username and inserts a Link node.

+func (t *transformer) appendMentionLink(parent, before ast.Node, username string, display []byte) bool {

+	if t.opts.Resolvers.User == nil {

+		return false

+	}

+	href, ok := t.opts.Resolvers.User(t.opts.Ctx, username)

+	if !ok {

+		return false

+	}

+	link := ast.NewLink()

+	link.Destination = []byte(href)

+	link.AppendChild(link, ast.NewString(append([]byte(nil), display...)))

+	parent.InsertBefore(parent, before, link)

+	if t.opts.Mentions != nil {

+		*t.opts.Mentions = append(*t.opts.Mentions, Mention{

+			Username: username,

+			Href:     href,

+		})

+	}

+	return true

+}

+

+// appendCommitLink resolves a commit SHA prefix in the current repo.

+func (t *transformer) appendCommitLink(parent, before ast.Node, shaPrefix string, display []byte) bool {

+	if t.opts.Resolvers.Commit == nil || t.opts.RepoOwner == "" || t.opts.RepoName == "" {

+		return false

+	}

+	href, full, ok := t.opts.Resolvers.Commit(t.opts.Ctx, t.opts.RepoOwner, t.opts.RepoName, shaPrefix)

+	if !ok {

+		return false

+	}

+	link := ast.NewLink()

+	link.Destination = []byte(href)

+	// Display the SHA as <code>; preserve the user's typed length.

+	codeText := append([]byte(nil), display...)

+	codeText = bytes.TrimSpace(codeText)

+	link.AppendChild(link, ast.NewCodeSpan())

+	cs := link.LastChild().(*ast.CodeSpan)

+	cs.AppendChild(cs, ast.NewString(codeText))

+	parent.InsertBefore(parent, before, link)

+

+	if t.opts.Refs != nil {

+		*t.opts.Refs = append(*t.opts.Refs, Ref{

+			Kind:    "commit",

+			FullSHA: full,

+			Href:    href,

+		})

+	}

+	return true

+}

+

+// trimLeadingNonWord drops the leading boundary char(s) — used when

+// a same-repo or mention token is rendered as plain text fallback.

+func trimLeadingNonWord(b []byte) []byte {

+	for len(b) > 0 && !isWordByte(b[0]) {

+		b = b[1:]

+	}

+	return b

+}

+

+func isWordByte(c byte) bool {

+	return c == '_' || (c >= '0' && c <= '9') || (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')

+}

+

+// silence unused-import warnings in a stripped build.

+var (

+	_ = strings.Builder{}

+	_ = trimLeadingNonWord

+)

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+// Package markdown is shithub's canonical markdown rendering pipeline.

+//

+// One entry point: `Render(ctx, source, opts) (html, refs, mentions)`.

+// Every comment, issue/PR body, README, and any future surface that

+// takes user-authored markdown flows through here. No other code in

+// the tree imports goldmark or bluemonday directly; a lint guard at

+// `scripts/lint-markdown-boundary.sh` enforces that boundary.

+//

+// What's supported (CommonMark + a curated GFM set):

+//

+//   - Headings, paragraphs, lists, blockquotes, code blocks (fenced + indented).

+//   - GFM tables, strikethrough, autolinks, task lists.

+//   - `@username` mentions — resolved via Options.Resolvers.User.

+//   - `#N` and `owner/repo#N` references — resolved via

+//     Options.Resolvers.Issue, gated by viewer visibility.

+//   - Emoji shortcodes (`:smile:`) — curated set in `emoji/`.

+//   - `<details>` / `<summary>`, `<kbd>`, `<sup>`, `<sub>`,

+//     task-list checkboxes (output by Goldmark with `disabled`).

+//   - Code-block class allowlist: `language-*` (Chroma uses these).

+//

+// What's deliberately not supported:

+//

+//   - Raw HTML beyond the strict allowlist (we do NOT match GitHub's

+//     loose HTML acceptance — we err safer).

+//   - `data:` URIs (any flavor; documented in docs/markdown.md).

+//   - `javascript:` / `vbscript:` URLs (rejected by sanitizer).

+//   - GFM Footnotes (deferred).

+//   - Math (KaTeX), Mermaid, embedded media (post-MVP).

+//

+// Pipeline-version contract:

+//

+//   - `Version` (in version.go) stamps every render.

+//   - Callers store the version alongside cached HTML.

+//   - On read, callers compare the stored version to `Version`; if

+//     they differ, the cache is stale and the caller re-renders. We

+//     never run a one-shot "re-render every comment" job — lazy.

+//

+// Performance budget:

+//

+//   - 50 KiB body, full extensions: <30 ms p99 on MVP hardware.

+//   - Inputs above MaxRenderInputBytes are rejected up-front; callers

+//     enforce the matching cap at the API layer.

+package markdown

+

+// MaxRenderInputBytes caps the input body. Comments / bodies are

+// rejected at the API layer at 64 KiB or 256 KiB depending on

+// surface; this is the renderer's defensive fallback.

+const MaxRenderInputBytes = 1 << 20 // 1 MiB

+

+// Ref is one resolved reference produced during rendering. The

+// caller uses these for downstream notification fan-out (S29) and

+// for the issue_references index (S21).

+type Ref struct {

+	// Kind is "issue" or "commit" for now.

+	Kind string

+	// Same-repo refs leave Owner/Repo empty.

+	Owner string

+	Repo  string

+	// Number is set for issue refs; FullSHA for commit refs.

+	Number  int64

+	FullSHA string

+	// Href is the resolved URL the renderer wrote into the document.

+	Href string

+}

+

+// Mention is one resolved @username mention. S29's fan-out consumes

+// the deduplicated list returned by Render.

+type Mention struct {

+	Username string

+	Href     string

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package markdown

+

+import (

+	"context"

+	"strings"

+	"testing"

+)

+

+// TestRender_HostileInputs is the XSS-vector cheatsheet. Every

+// fixture is a markdown body that *attempts* to inject executable

+// JS through a different vector. The pass condition: the rendered

+// HTML contains no `<script` tag, no `javascript:` URL, no event

+// handler attribute (`on*`), and no `data:` URI.

+//

+// Add new vectors here when a CVE / advisory lands in goldmark or

+// bluemonday — they're cheap to keep.

+func TestRender_HostileInputs(t *testing.T) {

+	t.Parallel()

+	vectors := []string{

+		// Direct script tag.

+		`<script>alert(1)</script>`,

+		`<SCRIPT>alert(1)</SCRIPT>`,

+		`<script src="//evil.com/x.js"></script>`,

+		// Inline event handlers.

+		`<img src="x" onerror="alert(1)">`,

+		`<img src=x onerror=alert(1)>`,

+		`<a onmouseover="alert(1)">x</a>`,

+		`<body onload="alert(1)">`,

+		// Style with expressions.

+		`<style>body{background:url("javascript:alert(1)")}</style>`,

+		`<div style="background:url(javascript:alert(1))">x</div>`,

+		// javascript: links.

+		`[click](javascript:alert(1))`,

+		`<a href="javascript:alert(1)">x</a>`,

+		`<a href="JaVaScRiPt:alert(1)">x</a>`,

+		`[click](JAVASCRIPT:alert(1))`,

+		// data: URIs (we disallow even data:image).

+		`<img src="data:image/svg+xml;base64,PHN2Zz4=">`,

+		`[x](data:text/html,<script>alert(1)</script>)`,

+		// vbscript:.

+		`<a href="vbscript:msgbox(1)">x</a>`,

+		// SVG-embedded scripts.

+		`<svg><script>alert(1)</script></svg>`,

+		`<svg onload="alert(1)"></svg>`,

+		// iframes.

+		`<iframe src="//evil.com"></iframe>`,

+		`<iframe srcdoc="<script>alert(1)</script>"></iframe>`,

+		// HTML in markdown link text doesn't escape sanitizer.

+		`[<script>alert(1)</script>](https://example.com)`,

+		// Mutation XSS via mismatched quotes.

+		`<a href="x"onmouseover="alert(1)">x</a>`,

+		// Encoded payloads.

+		`<a href="&#x6A;avascript:alert(1)">x</a>`,

+		`<a href="&#106;avascript:alert(1)">x</a>`,

+		// Backticked code-like content shouldn't escape.

+		"`<script>alert(1)</script>`",

+		// Embedded in autolinks.

+		`<javascript:alert(1)>`,

+		// Object/embed.

+		`<object data="x.swf"></object>`,

+		`<embed src="x.swf">`,

+		// Form/button with formaction.

+		`<form><button formaction="javascript:alert(1)">x</button></form>`,

+		// Meta refresh.

+		`<meta http-equiv="refresh" content="0; url=javascript:alert(1)">`,

+		// Base href hijack.

+		`<base href="javascript:">`,

+		// MathML / annotation.

+		`<math><annotation-xml encoding="text/html"><script>alert(1)</script></annotation-xml></math>`,

+		// CSS expression (legacy IE).

+		`<div style="width: expression(alert(1))">x</div>`,

+		// Nested fenced code with a script.

+		"```\n<script>alert(1)</script>\n```",

+		// Markdown link href with newlines.

+		"[x](\njavascript:alert(1))",

+		// Image with javascript:.

+		`![x](javascript:alert(1))`,

+		// HTML entities in URI.

+		`[x](javascript:alert(1))`,

+		// Hex / decimal entities in href attribute.

+		`<a href="javasc&#x72;ipt:alert(1)">x</a>`,

+		// Tab/newline obfuscation.

+		"<a href=\"java\tscript:alert(1)\">x</a>",

+		"<a href=\"java\nscript:alert(1)\">x</a>",

+		// Polyglot HTML+SVG.

+		`<svg/onload=alert(1)>`,

+		// Anchor with target=_blank but no rel (we want rel auto-set).

+		`<a href="https://evil.com" target="_blank">x</a>`,

+	}

+	for i, src := range vectors {

+		out, _, _, err := Render(context.Background(), []byte(src), Options{})

+		if err != nil {

+			t.Fatalf("vector %d render error: %v", i, err)

+		}

+		// Lower-case for case-insensitive substring search. We

+		// distinguish "executable surface" from "harmless text".

+		// Plain-text "javascript:" in prose is safe; "javascript:"

+		// inside href/src is an XSS — guard the latter shape only.

+		s := strings.ToLower(string(out))

+		for _, bad := range []string{

+			"<script", "</script>",

+			`href="javascript:`, `href='javascript:`,

+			`src="javascript:`, `src='javascript:`,

+			`href="vbscript:`, `src="vbscript:`,

+			`href="data:`, `src="data:text`, `src="data:image`,

+			" onerror=", " onload=", " onclick=", " onmouseover=",

+			"<iframe", "<object", "<embed",

+			"<style", "<base ", "<meta ",

+			"<annotation-xml", "expression(",

+		} {

+			if strings.Contains(s, bad) {

+				t.Errorf("vector %d (%q): rendered HTML contains %q\nout=%q", i, src, bad, out)

+			}

+		}

+	}

+}

+

+// TestRender_AllowsSafeHTML ensures the strict policy doesn't strip

+// `<details>`, `<summary>`, `<kbd>`, `<sup>`, `<sub>`, task-list

+// checkboxes, language-* class on code blocks, or auto-heading IDs.

+func TestRender_AllowsSafeHTML(t *testing.T) {

+	t.Parallel()

+	cases := []struct {

+		name      string

+		src       string

+		mustContain []string

+	}{

+		{

+			"details + summary",

+			"<details><summary>click</summary>secret</details>",

+			[]string{"<details>", "<summary>", "click", "secret"},

+		},

+		{

+			"kbd",

+			"press <kbd>Ctrl</kbd>+<kbd>C</kbd>",

+			[]string{"<kbd>Ctrl</kbd>", "<kbd>C</kbd>"},

+		},

+		{

+			"sup/sub",

+			"x<sup>2</sup> + y<sub>i</sub>",

+			[]string{"<sup>2</sup>", "<sub>i</sub>"},

+		},

+		{

+			"task list",

+			"- [x] done\n- [ ] not yet\n",

+			[]string{"<input", "checkbox", "disabled"},

+		},

+		{

+			"fenced code with language",

+			"```go\nfmt.Println(\"hi\")\n```",

+			[]string{`class="language-go"`},

+		},

+		{

+			"heading anchor id",

+			"# Hello world",

+			[]string{`id="hello-world"`},

+		},

+		{

+			"GFM table",

+			"| a | b |\n|---|---|\n| 1 | 2 |\n",

+			[]string{"<table>", "<th>a</th>", "<td>1</td>"},

+		},

+		{

+			"strikethrough",

+			"~~obsolete~~",

+			[]string{"<del>obsolete</del>"},

+		},

+		{

+			"autolink",

+			"https://example.com",

+			[]string{`href="https://example.com"`},

+		},

+	}

+	for _, c := range cases {

+		c := c

+		t.Run(c.name, func(t *testing.T) {

+			t.Parallel()

+			out, _, _, err := Render(context.Background(), []byte(c.src), Options{})

+			if err != nil {

+				t.Fatalf("render: %v", err)

+			}

+			s := string(out)

+			for _, want := range c.mustContain {

+				if !strings.Contains(s, want) {

+					t.Errorf("expected %q in output, got %q", want, s)

+				}

+			}

+		})

+	}

+}

+

+// TestRender_MentionResolution checks that @user resolves when the

+// resolver returns ok and stays plain text otherwise.

+func TestRender_MentionResolution(t *testing.T) {

+	t.Parallel()

+	resolver := func(_ context.Context, name string) (string, bool) {

+		if name == "alice" {

+			return "/alice", true

+		}

+		return "", false

+	}

+	out, _, mentions, err := Render(context.Background(), []byte("hi @alice and @bob"), Options{

+		Resolvers: Resolvers{User: resolver},

+	})

+	if err != nil {

+		t.Fatalf("render: %v", err)

+	}

+	s := string(out)

+	if !strings.Contains(s, `href="/alice"`) {

+		t.Errorf("expected @alice link, got %q", s)

+	}

+	if strings.Contains(s, `href="/bob"`) {

+		t.Errorf("@bob should not link, got %q", s)

+	}

+	if len(mentions) != 1 || mentions[0].Username != "alice" {

+		t.Errorf("expected 1 mention (alice), got %v", mentions)

+	}

+}

+

+// TestRender_IssueRefResolution checks both same-repo and cross-repo

+// refs, and that an unresolvable ref renders as plain text (no link).

+func TestRender_IssueRefResolution(t *testing.T) {

+	t.Parallel()

+	resolver := func(_ context.Context, owner, name string, num int64, _ int64) (string, bool) {

+		// Same-repo refs leave owner+name empty.

+		if owner == "" && name == "" && num == 7 {

+			return "/o/r/issues/7", true

+		}

+		if owner == "alice" && name == "proj" && num == 3 {

+			return "/alice/proj/issues/3", true

+		}

+		return "", false

+	}

+	out, refs, _, err := Render(context.Background(), []byte("see #7 and alice/proj#3, but not bob/x#9"), Options{

+		Resolvers: Resolvers{Issue: resolver},

+	})

+	if err != nil {

+		t.Fatalf("render: %v", err)

+	}

+	s := string(out)

+	if !strings.Contains(s, `href="/o/r/issues/7"`) {

+		t.Errorf("expected #7 link, got %q", s)

+	}

+	if !strings.Contains(s, `href="/alice/proj/issues/3"`) {

+		t.Errorf("expected alice/proj#3 link, got %q", s)

+	}

+	if strings.Contains(s, `href="/bob/x/issues/9"`) {

+		t.Errorf("bob/x#9 should not link, got %q", s)

+	}

+	if len(refs) != 2 {

+		t.Errorf("expected 2 refs, got %v", refs)

+	}

+}

+

+// TestRender_RefsInsideCodeAreInert confirms that #N inside inline

+// code or fenced code stays as text.

+func TestRender_RefsInsideCodeAreInert(t *testing.T) {

+	t.Parallel()

+	resolver := func(_ context.Context, owner, name string, num int64, _ int64) (string, bool) {

+		return "/should/not/appear", true

+	}

+	src := "Inline `#7` and:\n\n```\nblock #7 here\n```"

+	out, refs, _, err := Render(context.Background(), []byte(src), Options{

+		Resolvers: Resolvers{Issue: resolver},

+	})

+	if err != nil {

+		t.Fatalf("render: %v", err)

+	}

+	if strings.Contains(string(out), "/should/not/appear") {

+		t.Errorf("ref leaked into code block: %q", out)

+	}

+	if len(refs) != 0 {

+		t.Errorf("expected 0 refs inside code, got %v", refs)

+	}

+}

+

+// TestRender_EmojiShortcodes checks the curated set works.

+func TestRender_EmojiShortcodes(t *testing.T) {

+	t.Parallel()

+	out, _, _, err := Render(context.Background(), []byte("ship it :rocket: :+1: :notrealemoji:"), Options{})

+	if err != nil {

+		t.Fatalf("render: %v", err)

+	}

+	s := string(out)

+	if !strings.Contains(s, "🚀") {

+		t.Errorf("expected rocket emoji in output, got %q", s)

+	}

+	if !strings.Contains(s, "👍") {

+		t.Errorf("expected +1 emoji in output, got %q", s)

+	}

+	if !strings.Contains(s, ":notrealemoji:") {

+		t.Errorf("unknown shortcode should pass through, got %q", s)

+	}

+}

+

+// TestRender_InputTooLarge enforces the renderer's defensive cap.

+func TestRender_InputTooLarge(t *testing.T) {

+	t.Parallel()

+	big := make([]byte, MaxRenderInputBytes+1)

+	for i := range big {

+		big[i] = 'x'

+	}

+	if _, _, _, err := Render(context.Background(), big, Options{}); err == nil {

+		t.Errorf("expected ErrInputTooLarge")

+	}

+}

+

+// TestRender_SoftBreakAsBR controls the comment-vs-readme newline

+// handling.

+func TestRender_SoftBreakAsBR(t *testing.T) {

+	t.Parallel()

+	src := "line one\nline two\n"

+	br, _, _, _ := Render(context.Background(), []byte(src), Options{SoftBreakAsBR: true})

+	noBR, _, _, _ := Render(context.Background(), []byte(src), Options{SoftBreakAsBR: false})

+	if !strings.Contains(string(br), "<br") {

+		t.Errorf("SoftBreakAsBR=true: expected <br>, got %q", br)

+	}

+	if strings.Contains(string(noBR), "<br") {

+		t.Errorf("SoftBreakAsBR=false: should not contain <br>, got %q", noBR)

+	}

+}

+

+// TestRender_BackCompatRenderHTML keeps the old shim working so the

+// interim S17/S21/S22 callers don't need rewrite during S25.

+func TestRender_BackCompatRenderHTML(t *testing.T) {

+	t.Parallel()

+	html, err := RenderHTML([]byte("**bold** text"))

+	if err != nil {

+		t.Fatalf("RenderHTML: %v", err)

+	}

+	if !strings.Contains(html, "<strong>bold</strong>") {

+		t.Errorf("expected bold, got %q", html)

+	}

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package markdown

+

+import "context"

+

+// RepoContext is the optional repo binding for `#N` reference

+// resolution. When nil, `#N` renders as plain text (matches

+// "repo-context-less rendering" in the spec).

+type RepoContext struct {

+	OwnerUsername string

+	RepoName      string

+	RepoID        int64

+}

+

+// Resolvers wire the package against the rest of the runtime without

+// importing usersdb / issuesdb directly (avoids a cycle with packages

+// that themselves render markdown). Each resolver is optional; a nil

+// resolver means "render as plain text" for that flavor of reference.

+//

+// All resolvers MUST be visibility-aware: they receive the viewer

+// (Options.ViewerUserID) and return ok=false when the resource isn't

+// visible. Returning a link to a hidden resource leaks existence.

+type Resolvers struct {

+	// User: @username → "/username" if the user exists, isn't

+	// suspended, and (post-S30) is org-team-visible to the viewer.

+	User func(ctx context.Context, username string) (href string, ok bool)

+	// Issue: (repoOwner, repoName, number) → "/owner/repo/issues/N".

+	// Returns ok=false when the repo isn't visible to viewer or the

+	// number wasn't allocated yet.

+	Issue func(ctx context.Context, owner, name string, number int64, viewerUserID int64) (href string, ok bool)

+	// Commit: short-or-full SHA inside the current repo context →

+	// "/owner/repo/commit/<full_sha>". Only invoked when

+	// Opts.Repo != nil.

+	Commit func(ctx context.Context, repoOwner, repoName, shaPrefix string) (href, fullSHA string, ok bool)

+}

+

+// Options tunes a single Render call. Zero-value Options is valid

+// and yields a safe, generic render with no reference resolution.

+type Options struct {

+	// Repo is the binding for same-repo `#N` resolution. nil means

+	// "no repo context"; `#N` renders as plain text.

+	Repo *RepoContext

+

+	// ViewerUserID gates cross-repo `#N` and `@user` resolution.

+	// 0 = anonymous viewer.

+	ViewerUserID int64

+

+	// SoftBreakAsBR controls newline-as-<br> rendering:

+	//   true  — comment / issue / PR body shape (matches GitHub UI)

+	//   false — README / structured-doc shape (preserve markdown semantics)

+	SoftBreakAsBR bool

+

+	// LinkTargetBlank, when true, sets target="_blank" rel="noopener

+	// noreferrer" on autolinks + reference links. Default off; READMEs

+	// keep links in-page so the user doesn't lose context.

+	LinkTargetBlank bool

+

+	// Resolvers wires reference resolution. nil resolvers in the

+	// struct mean "render that flavor as plain text".

+	Resolvers Resolvers

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package markdown

+

+import (

+	"bytes"

+	"context"

+	"errors"

+

+	"github.com/yuin/goldmark"

+	"github.com/yuin/goldmark/extension"

+	"github.com/yuin/goldmark/parser"

+	"github.com/yuin/goldmark/renderer"

+	gmhtml "github.com/yuin/goldmark/renderer/html"

+

+	"github.com/tenseleyFlow/shithub/internal/markdown/extensions"

+)

+

+// ErrInputTooLarge is returned when source exceeds MaxRenderInputBytes.

+// Callers should reject the input at the API layer before reaching

+// Render; this is the renderer's defensive fallback.

+var ErrInputTooLarge = errors.New("markdown: source exceeds MaxRenderInputBytes")

+

+// Render is the canonical markdown entry point. The output bytes

+// have already been Goldmark-rendered AND bluemonday-sanitized;

+// callers can wrap them as `template.HTML` and inject into a

+// template directly.

+//

+// `refs` and `mentions` carry the resolved cross-reference/mention

+// state for downstream consumers (S29 notification fan-out, S21

+// issue_references index). The order matches first-occurrence in

+// source.

+//

+// A nil ctx is fine; resolvers receive context.Background() in

+// that case.

+func Render(ctx context.Context, src []byte, opts Options) (rendered []byte, refs []Ref, mentions []Mention, err error) {

+	if len(src) == 0 {

+		return nil, nil, nil, nil

+	}

+	if len(src) > MaxRenderInputBytes {

+		return nil, nil, nil, ErrInputTooLarge

+	}

+	if ctx == nil {

+		ctx = context.Background()

+	}

+

+	// Build a fresh Goldmark for each render so the per-call

+	// extension Options can plug in without races. The build is

+	// cheap (~µs) and removes any cross-render contamination of

+	// the AST transformer state.

+	xRefs := []extensions.Ref{}

+	xMentions := []extensions.Mention{}

+	xOpts := &extensions.Options{

+		Ctx:          ctx,

+		ViewerUserID: opts.ViewerUserID,

+		Refs:         &xRefs,

+		Mentions:     &xMentions,

+		Resolvers: extensions.Resolvers{

+			User:   opts.Resolvers.User,

+			Issue:  opts.Resolvers.Issue,

+			Commit: opts.Resolvers.Commit,

+		},

+	}

+	if opts.Repo != nil {

+		xOpts.RepoOwner = opts.Repo.OwnerUsername

+		xOpts.RepoName = opts.Repo.RepoName

+	}

+

+	// gmhtml.WithUnsafe lets raw HTML through the parser → bluemonday

+	// scrubs at the sanitizer pass. Without this, every <details>,

+	// <kbd>, <sup>, etc. that users type would be HTML-escaped before

+	// the sanitizer ever sees them. The strict policy in sanitize.go

+	// is the security boundary.

+	htmlOpts := []renderer.Option{gmhtml.WithXHTML(), gmhtml.WithUnsafe()}

+	if opts.SoftBreakAsBR {

+		htmlOpts = append(htmlOpts, gmhtml.WithHardWraps())

+	}

+

+	gm := goldmark.New(

+		goldmark.WithExtensions(

+			extension.GFM, // tables, strikethrough, autolinks, task list

+			extensions.New(xOpts),

+		),

+		goldmark.WithParserOptions(parser.WithAutoHeadingID()),

+		goldmark.WithRendererOptions(htmlOpts...),

+	)

+

+	var buf bytes.Buffer

+	if err := gm.Convert(src, &buf); err != nil {

+		return nil, nil, nil, err

+	}

+	clean := sanitizeBytes(buf.Bytes())

+

+	// Convert extension-local types into the public types.

+	if len(xRefs) > 0 {

+		refs = make([]Ref, len(xRefs))

+		for i, r := range xRefs {

+			refs[i] = Ref{

+				Kind:    r.Kind,

+				Owner:   r.Owner,

+				Repo:    r.Repo,

+				Number:  r.Number,

+				FullSHA: r.FullSHA,

+				Href:    r.Href,

+			}

+		}

+	}

+	if len(xMentions) > 0 {

+		mentions = make([]Mention, len(xMentions))

+		for i, m := range xMentions {

+			mentions[i] = Mention{Username: m.Username, Href: m.Href}

+		}

+	}

+	return clean, refs, mentions, nil

+}

+

+// RenderHTML is the back-compat shim for callers that don't need

+// resolved refs/mentions. SoftBreakAsBR defaults to true (matches

+// the comment-style legacy behavior of the S17 helper this replaces).

+//

+// The signature matches `internal/repos/markdown.RenderHTML` so

+// existing callers can swap the import path without code changes.

+// New callers should prefer Render directly.

+func RenderHTML(src []byte) (string, error) {

+	out, _, _, err := Render(context.Background(), src, Options{SoftBreakAsBR: true})

+	if err != nil {

+		return "", err

+	}

+	return string(out), nil

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package markdown

+

+import (

+	"regexp"

+	"sync"

+

+	"github.com/microcosm-cc/bluemonday"

+)

+

+// sanitizer is the package-private bluemonday policy. Built once;

+// safe for concurrent use.

+//

+// Threat model:

+//

+//   - Goldmark with HTML rendering off escapes user-injected raw

+//     HTML at parse time, so the sanitizer is *defense in depth* —

+//     anything that reaches it should already be Goldmark-emitted

+//     HTML or our own AST-extension output.

+//   - The strict scheme allowlist (`http`, `https`, `mailto`) blocks

+//     `javascript:`, `data:`, `vbscript:` URIs entirely.

+//   - We diverge from GitHub by *not* allowing `data:image/...`. If

+//     a user wants an inline image, repo-relative paths work via

+//     /raw/. Documented in docs/markdown.md.

+var sanitizer = func() *bluemonday.Policy {

+	p := bluemonday.UGCPolicy()

+

+	// Headings keep their auto-generated id so anchor links work.

+	p.AllowAttrs("id").OnElements("h1", "h2", "h3", "h4", "h5", "h6")

+

+	// Code-block class allowlist for Chroma (`language-foo`). The

+	// SpaceSeparatedTokens matcher is bluemonday-built-in; we

+	// further constrain via the regex below so only `language-*` and

+	// chroma's own ancillary classes pass.

+	p.AllowAttrs("class").Matching(reCodeClass).OnElements("code", "pre", "span")

+

+	// GFM task lists: Goldmark emits `<input checked="" disabled=""

+	// type="checkbox" />` inside `<li>`. UGCPolicy doesn't allow

+	// input by default; whitelist the disabled-checkbox shape only.

+	// `type` is matched against "checkbox"; `disabled` and `checked`

+	// are HTML boolean attrs (value commonly empty), so we don't

+	// constrain the value — presence is the signal.

+	p.AllowAttrs("type").Matching(regexp.MustCompile(`^checkbox$`)).OnElements("input")

+	p.AllowAttrs("disabled", "checked").OnElements("input")

+

+	// Folded sections + keyboard markers. Common in READMEs.

+	p.AllowElements("details", "summary", "kbd", "sup", "sub")

+

+	// Mention / ref / commit anchors emitted by our extensions carry

+	// these classes for styling. The base UGC policy already allows

+	// <a> with href + rel; we just need the class allowlist above to

+	// cover `shithub-mention`, `shithub-ref`, `shithub-commit`.

+

+	// Hard-restrict URL schemes. UGCPolicy already restricts schemes

+	// on <a>, but we tighten further: drop ftp, drop data:, leave

+	// only http(s) + mailto.

+	p.AllowURLSchemes("http", "https", "mailto")

+	// Image schemes — UGC allows http/https only by default; we keep

+	// that. No data: anywhere.

+	p.AllowImages()

+

+	// rel="noopener noreferrer" auto-added when target="_blank" is

+	// set. We only set target via opts on autolinks; let bluemonday

+	// keep its default rel-handling.

+	p.RequireNoFollowOnLinks(true)

+	return p

+}()

+

+var reCodeClass = regexp.MustCompile(`^(?:language-[A-Za-z0-9_+\-]+|chroma|chroma-[a-zA-Z]+|nl|ln|line|hl)(?:\s+(?:language-[A-Za-z0-9_+\-]+|chroma|chroma-[a-zA-Z]+|nl|ln|line|hl))*$`)

+

+// sanitizeBytes is the hot-path entry the Render pipeline uses. The

+// bluemonday Policy is itself goroutine-safe; the once.Do here keeps

+// the regex compilation cost off the first request path.

+var sanitizerOnce sync.Once

+

+func sanitizeBytes(in []byte) []byte {

+	sanitizerOnce.Do(func() {

+		// Touch the package-level sanitizer to ensure it's built.

+		_ = sanitizer

+	})

+	return sanitizer.SanitizeBytes(in)

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package markdown

+

+// Version is the canonical pipeline-version stamp written to

+// `body_html_cached`-style columns whenever a comment / issue body /

+// PR body is rendered. Bumping this constant invalidates cached HTML

+// lazily on read: callers compare the stored `md_pipeline_version` to

+// `Version` and re-render when they don't match.

+//

+// Bump rules:

+//   - Sanitizer policy change (allow/disallow tag, attribute, scheme).

+//   - New AST extension or rendering output change.

+//   - Goldmark / bluemonday major-version upgrade with output drift.

+//

+// Don't bump for:

+//   - Bug fixes that don't change rendered HTML for any input.

+//   - Performance-only changes.

+const Version int32 = 1