Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Markdown): decode link destinations and close link text at an unescaped bracket (#7054)

Cindy Zhangd210fd35e909
diff --git a/.changeset/markdown-link-destinations.md b/.changeset/markdown-link-destinations.md
new file mode 100644
index 0000000000..71cf948d2b
--- /dev/null
+++ b/.changeset/markdown-link-destinations.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Markdown: decode character references and backslash escapes in link destinations, and close link text at an unescaped bracket
+@cixzhang
+
+A link or image destination now reads as CommonMark specifies: `[x](https://a.com/?a=1&b=2)` links to `https://a.com/?a=1&b=2`, `[x](a\)b)` links to `a)b`, and reference definitions decode the same way. The URL safety check runs on the decoded destination, so an encoded unsafe scheme such as `javascript:` is refused like the plain one. Link text and image alternative text close at the first unescaped `]`, so `[a\]b](u)` is a link with the text `a]b`.
diff --git a/packages/core/src/Markdown/linkDestinations.test.tsx b/packages/core/src/Markdown/linkDestinations.test.tsx
new file mode 100644
index 0000000000..56999b1d65
--- /dev/null
+++ b/packages/core/src/Markdown/linkDestinations.test.tsx
@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {render} from '@testing-library/react';
+import {Markdown} from './Markdown';
+import {parseMarkdownAst} from './parser';
+
+type Json = {
+ readonly type: string;
+ readonly url?: string;
+ readonly value?: string;
+ readonly alt?: string;
+ readonly children?: ReadonlyArray<Json>;
+};
+
+/** Every link and image in `markdown`: kind, destination, and text. */
+function targets(markdown: string): [string, string, string][] {
+ const found: [string, string, string][] = [];
+ const text = (node: Json): string =>
+ node.type === 'text'
+ ? (node.value ?? '')
+ : (node.children ?? []).map(text).join('');
+ const visit = (node: Json) => {
+ if (node.type === 'link') {
+ found.push(['link', node.url ?? '', text(node)]);
+ } else if (node.type === 'image') {
+ found.push(['image', node.url ?? '', node.alt ?? '']);
+ }
+ (node.children ?? []).forEach(visit);
+ };
+ (
+ parseMarkdownAst(markdown).children as unknown as ReadonlyArray<Json>
+ ).forEach(visit);
+ return found;
+}
+
+describe('link destinations (CommonMark 0.31 §6.3, spec:AST-061 FR7)', () => {
+ it.each([
+ ['[x](https://a.com/?a=1&amp;b=2)', 'https://a.com/?a=1&b=2'],
+ ['[x](https://a.com/&#106;s)', 'https://a.com/js'],
+ ['[x](a\\)b)', 'a)b'],
+ ['[x](a\\(b)', 'a(b'],
+ ['[x](https://e.com/\\(bar\\))', 'https://e.com/(bar)'],
+ ['[x](https://e.com/foo(bar))', 'https://e.com/foo(bar)'],
+ ['[x](https://e.com/\\&amp;)', 'https://e.com/&amp;'],
+ ['[x](C:\\Users\\ada)', 'C:\\Users\\ada'],
+ ['[x](https://e.com/a_b "Title &amp; more")', 'https://e.com/a_b'],
+ ])('reads %j as a link to %j', (markdown, url) => {
+ expect(targets(markdown)).toEqual([['link', url, 'x']]);
+ });
+
+ it('decodes reference definitions and image sources the same way', () => {
+ expect(
+ targets(
+ '[x][r] and ![pic](b&amp;c)\n\n[r]: https://a.com/?a=1&amp;b=2\n',
+ ),
+ ).toEqual([
+ ['link', 'https://a.com/?a=1&b=2', 'x'],
+ ['image', 'b&c', 'pic'],
+ ]);
+ });
+
+ it('closes link text at an unescaped bracket', () => {
+ expect(targets('[a\\]b](u)')).toEqual([['link', 'u', 'a]b']]);
+ expect(targets('![a\\]b](u)')).toEqual([['image', 'u', 'a]b']]);
+ });
+});
+
+describe('decoded destinations stay safe', () => {
+ it.each([
+ '[x](&#106;avascript:alert(1))',
+ '[x](&#x6A;avascript:alert(1))',
+ '[x](java&#115;cript:alert(1))',
+ '[x](javascript&colon;alert(1))',
+ '[x](&#106;avascript&#58;alert&#40;1&#41;)',
+ ])('refuses %j, whose decoded scheme is javascript:', markdown => {
+ expect(targets(markdown)).toEqual([]);
+ const {container} = render(<Markdown>{markdown}</Markdown>);
+ expect(container.querySelector('a')).toBeNull();
+ });
+
+ it('refuses an encoded unsafe scheme in a reference definition or image', () => {
+ expect(targets('[x][r]\n\n[r]: &#106;avascript:alert(1)\n')).toEqual([]);
+ expect(targets('![pic](&#106;avascript:alert(1))')).toEqual([]);
+ });
+});
diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.ts
index 0ad6ffd222..b4846b1641 100644
--- a/packages/core/src/Markdown/parser.ts
+++ b/packages/core/src/Markdown/parser.ts
@@ -806,7 +806,11 @@ function matchLinkDefinition(
if (label === '' || destination == null) {
return null;
}
- return {label, destination, hasTitle: match[4] != null};
+ return {
+ label,
+ destination: decodeLinkDestination(destination),
+ hasTitle: match[4] != null,
+ };
}
/**
@@ -959,14 +963,14 @@ function matchReferenceLink(
node: MarkdownAstPhrasingContent<RuntimeExtensionNode>;
end: number;
} | null {
- const textClose = text.indexOf(']', start + 1);
+ const textClose = closingBracket(text, start + 1);
if (textClose === -1) {
return null;
}
const linkText = text.slice(start + 1, textClose);
// Full `[text][label]` / collapsed `[text][]` — a matching definition wins.
if (text[textClose + 1] === '[') {
- const labelClose = text.indexOf(']', textClose + 2);
+ const labelClose = closingBracket(text, textClose + 2);
if (labelClose !== -1) {
const rawLabel = text.slice(textClose + 2, labelClose);
// Only truly-empty brackets are the collapsed form; a whitespace-only
@@ -1023,13 +1027,13 @@ function matchReferenceImage(
node: MarkdownAstPhrasingContent<RuntimeExtensionNode>;
end: number;
} | null {
- const altClose = text.indexOf(']', start + 2);
+ const altClose = closingBracket(text, start + 2);
if (altClose === -1) {
return null;
}
const alt = text.slice(start + 2, altClose);
if (text[altClose + 1] === '[') {
- const labelClose = text.indexOf(']', altClose + 2);
+ const labelClose = closingBracket(text, altClose + 2);
if (labelClose !== -1) {
const rawLabel = text.slice(altClose + 2, labelClose);
const label = rawLabel === '' ? alt : rawLabel;
@@ -1076,9 +1080,65 @@ function inlineDestination(content: string): string {
return match == null ? content : (match[1] ?? match[2] ?? content);
}
+/**
+ * A link or image destination with its backslash escapes and character
+ * references decoded, as CommonMark 0.31 §6.3 reads it: `\)` is `)`,
+ * `&amp;` is `&`, and an escaped `\&` stays literal. Every URL safety check
+ * runs on this decoded value, so an encoded scheme such as `&#106;avascript:`
+ * is refused like the plain one.
+ */
+function decodeLinkDestination(raw: string): string {
+ if (!raw.includes('\\') && !raw.includes('&')) {
+ return raw;
+ }
+ let decoded = '';
+ let index = 0;
+ while (index < raw.length) {
+ const character = raw[index];
+ if (character === '\\' && isAsciiPunctuation(raw[index + 1])) {
+ decoded += raw[index + 1];
+ index += 2;
+ continue;
+ }
+ if (character === '&') {
+ const reference = matchCharacterReference(raw, index);
+ if (reference != null) {
+ decoded += reference.value;
+ index = reference.end;
+ continue;
+ }
+ }
+ decoded += character;
+ index++;
+ }
+ return decoded;
+}
+
+/**
+ * The `]` that closes link text, an image's alternative text, or a reference
+ * label opened before `from`; an escaped `\]` does not close it.
+ */
+function closingBracket(text: string, from: number): number {
+ for (let index = from; index < text.length; index++) {
+ if (text[index] === '\\') {
+ index++;
+ continue;
+ }
+ if (text[index] === ']') {
+ return index;
+ }
+ }
+ return -1;
+}
+
function findClosingParen(text: string, start: number): number {
let depth = 1;
for (let index = start; index < text.length; index++) {
+ // An escaped parenthesis is part of the destination, not its end.
+ if (text[index] === '\\') {
+ index++;
+ continue;
+ }
if (text[index] === '(') {
depth++;
} else if (text[index] === ')') {
@@ -1558,11 +1618,13 @@ function parseInlineImpl(
// --- Image ![alt](src) ---
if (text[i] === '!' && text[i + 1] === '[') {
- const altClose = text.indexOf(']', i + 2);
+ const altClose = closingBracket(text, i + 2);
if (altClose !== -1 && text[altClose + 1] === '(') {
const srcClose = findClosingParen(text, altClose + 2);
if (srcClose !== -1) {
- const src = inlineDestination(text.slice(altClose + 2, srcClose));
+ const src = decodeLinkDestination(
+ inlineDestination(text.slice(altClose + 2, srcClose)),
+ );
if (!isSafeMarkdownParserUrl(src)) {
// Dangerous scheme — emit as plain text.
nodes.push({type: 'text', value: text.slice(i, srcClose + 1)});
@@ -1601,11 +1663,13 @@ function parseInlineImpl(
// --- Link [text](url) ---
if (text[i] === '[') {
- const textClose = text.indexOf(']', i + 1);
+ const textClose = closingBracket(text, i + 1);
if (textClose !== -1 && text[textClose + 1] === '(') {
const urlClose = findClosingParen(text, textClose + 2);
if (urlClose !== -1) {
- const href = inlineDestination(text.slice(textClose + 2, urlClose));
+ const href = decodeLinkDestination(
+ inlineDestination(text.slice(textClose + 2, urlClose)),
+ );
if (!isSafeMarkdownParserUrl(href)) {
// Dangerous scheme — emit as plain text instead of a link.
nodes.push({type: 'text', value: text.slice(i, urlClose + 1)});
@@ -2785,7 +2849,9 @@ function parseMarkdownImpl(
// An unsafe src falls through to the paragraph path and renders as
// literal text, the same rule the inline image path applies.
const imageMatch = line.match(/^!\[([^\]]*)\]\(([^)]+)\)/);
- const imageSrc = imageMatch ? inlineDestination(imageMatch[2]) : '';
+ const imageSrc = imageMatch
+ ? decodeLinkDestination(inlineDestination(imageMatch[2]))
+ : '';
if (
imageMatch &&
line.trim() === imageMatch[0] &&