0
# HTML Security
1

2
HTML escaping and sanitization utilities for preventing XSS attacks and ensuring safe rendering of user-provided content in templates and dynamic content.
3

4
## Capabilities
5

6
### HTML Content Escaping
7

8
Functions for escaping HTML special characters to prevent XSS attacks.
9

10
```typescript { .api }
11
/**
12
 * Escape HTML special characters in a string
13
 * Converts <, >, &, ", and ' to their HTML entity equivalents
14
 * @param string - String to escape (can be any type, will be converted to string)
15
 * @returns Escaped HTML string safe for rendering
16
 */
17
function escapeHtml(string: unknown): string;
18

19
/**
20
 * Escape HTML comment content to prevent comment breakout
21
 * Removes patterns that could terminate or malform HTML comments
22
 * @param src - Comment content to escape
23
 * @returns Sanitized comment content
24
 */
25
function escapeHtmlComment(src: string): string;
26
```
27

28
### CSS Variable Name Escaping
29

30
Functions for safely escaping CSS custom property names for use in various contexts.
31

32
```typescript { .api }
33
/**
34
 * Regular expression for CSS variable name characters that need escaping
35
 * Matches special characters that are invalid in CSS custom property names
36
 */
37
const cssVarNameEscapeSymbolsRE: RegExp;
38

39
/**
40
 * Escape CSS variable name for safe use in CSS
41
 * Handles both single and double escaping for different contexts
42
 * @param key - CSS variable name to escape
43
 * @param doubleEscape - Whether to use double escaping (for nested contexts)
44
 * @returns Escaped CSS variable name
45
 */
46
function getEscapedCssVarName(
47
  key: string, 
48
  doubleEscape: boolean
49
): string;
50
```
51

52
**Usage Examples:**
53

54
```typescript
55
import { 
56
  escapeHtml, 
57
  escapeHtmlComment, 
58
  getEscapedCssVarName,
59
  cssVarNameEscapeSymbolsRE 
60
} from "@vue/shared";
61

62
// HTML content escaping
63
const userInput = '<script>alert("XSS attack!")</script>';
64
const safeHtml = escapeHtml(userInput);
65
console.log(safeHtml); 
66
// "&lt;script&gt;alert(&quot;XSS attack!&quot;)&lt;/script&gt;"
67

68
// Escape various HTML characters
69
const mixed = 'Hello "world" & <friends>';
70
const escaped = escapeHtml(mixed);
71
console.log(escaped);
72
// "Hello &quot;world&quot; &amp; &lt;friends&gt;"
73

74
// Non-string input (converted to string first)
75
console.log(escapeHtml(123)); // "123"
76
console.log(escapeHtml(true)); // "true"
77
console.log(escapeHtml(null)); // "null"
78

79
// HTML comment escaping
80
const maliciousComment = "<!-- previous comment --><!-- inject -->";
81
const safeComment = escapeHtmlComment(maliciousComment);
82
console.log(safeComment); // " previous comment   inject "
83

84
// More comment attacks
85
const commentBreakout = "--><script>alert('xss')</script><!--";
86
const escapedBreakout = escapeHtmlComment(commentBreakout);
87
console.log(escapedBreakout); // "script>alert('xss')</script"
88

89
// CSS variable name escaping
90
const varName = "my var-name!";
91
const singleEscaped = getEscapedCssVarName(varName, false);
92
console.log(singleEscaped); // "my\\ var\\-name\\!"
93

94
const doubleEscaped = getEscapedCssVarName(varName, true);
95
console.log(doubleEscaped); // "my\\\\ var\\\\-name\\\\!"
96

97
// Special case: quotes in variable names
98
const quotedVar = 'my"var';
99
const quotesEscaped = getEscapedCssVarName(quotedVar, false);
100
console.log(quotesEscaped); // "my\\\"var"
101

102
const quotesDoubleEscaped = getEscapedCssVarName(quotedVar, true);
103
console.log(quotesDoubleEscaped); // "my\\\\\\\"var"
104

105
// CSS variable character detection
106
const needsEscaping = cssVarNameEscapeSymbolsRE.test("my var!"); // true
107
const isClean = cssVarNameEscapeSymbolsRE.test("myvar"); // false
108
```
109

110
### Character Escaping Details
111

112
**HTML Character Mappings:**
113
- `<` → `&lt;`
114
- `>` → `&gt;`
115
- `&` → `&amp;`
116
- `"` → `&quot;`
117
- `'` → `&#39;`
118

119
**HTML Comment Patterns Removed:**
120
- `<!-->` - Malformed comment start
121
- `<!--` - Comment start
122
- `-->` - Comment end
123
- `--!>` - Malformed comment end
124
- `<!-$` - Incomplete comment start
125

126
**CSS Variable Characters Requiring Escaping:**
127
- Space characters and special symbols: ` !"#$%&'()*+,./:;<=>?@[\\\]^\`{|}~`
128

129
### Security Context Usage
130

131
**Template Interpolation:**
132
```typescript
133
// Safe interpolation in templates
134
const userContent = '<img src="x" onerror="alert(1)">';
135
const safeContent = escapeHtml(userContent);
136
// Now safe to render: {{safeContent}}
137
```
138

139
**Dynamic HTML Comments:**
140
```typescript
141
// Safe comment generation
142
const userComment = "--><script>malicious()</script><!--";
143
const safeComment = escapeHtmlComment(userComment);
144
// Safe to use in: <!-- ${safeComment} -->
145
```
146

147
**CSS Custom Properties:**
148
```typescript
149
// Safe CSS variable names
150
const dynamicVarName = "user input!";
151
const safeName = getEscapedCssVarName(dynamicVarName, false);
152
// Safe to use in: var(--${safeName})
153
```
154

155
### Performance Characteristics
156

157
- **Early Exit**: `escapeHtml` returns original string if no special characters found
158
- **Optimized Scanning**: Uses `RegExp.exec()` to find first special character before processing
159
- **Minimal Processing**: Only processes characters that actually need escaping
160
- **String Building**: Efficiently builds output string only when escaping is needed
161

162
### Integration with Vue
163

164
These security utilities are used throughout Vue's rendering pipeline:
165

166
- **Template Compilation**: Automatic escaping of interpolated content
167
- **SSR**: Server-side rendering safely escapes dynamic content
168
- **Comment Rendering**: Dev tools and comment nodes use comment escaping
169
- **CSS Binding**: v-bind in `<style>` blocks uses CSS variable escaping