mirror of
https://github.com/angular/angular.git
synced 2026-09-14 13:54:52 +08:00
docs: add NG05200 error reference page for SANITIZATION_UNSAFE_SCRIPT
Adds a reference page for `NG05200`, thrown by `DomSanitizer` when a value is bound to a `<script>` element without being marked trusted via `bypassSecurityTrustScript`. Covers why Angular rejects script content outright, how to reproduce the error, the escape hatch, and the XSS caveat.
This commit is contained in:
@@ -0,0 +1,53 @@
|
||||
# Unsafe value used in a resource URL context
|
||||
|
||||
Angular throws this error when you bind a value to an attribute that loads an external resource — like `<iframe src>`, or `<link href>` — and that value hasn't been explicitly marked as trusted.
|
||||
|
||||
Resource URLs are treated differently from regular URLs. Angular can sanitize a plain URL (stripping `javascript:` schemes and so on), but it can't make an arbitrary resource URL safe because these attributes cause the browser to fetch and execute external content. So Angular rejects untrusted values rather than trying to sanitize them.
|
||||
|
||||
The attributes that trigger this check are:
|
||||
|
||||
| Element | Attribute(s) |
|
||||
| ---------- | ------------------ |
|
||||
| `<base>` | `href` |
|
||||
| `<embed>` | `src` |
|
||||
| `<frame>` | `src` |
|
||||
| `<iframe>` | `src` |
|
||||
| `<link>` | `href` |
|
||||
| `<object>` | `codebase`, `data` |
|
||||
|
||||
## Debugging the error
|
||||
|
||||
This error can also be thrown when calling `DomSanitizer.sanitize()` directly with `SecurityContext.RESOURCE_URL` and a plain string:
|
||||
|
||||
```typescript
|
||||
inject(DomSanitizer).sanitize(SecurityContext.RESOURCE_URL, 'https://example.com'); // throws NG05201
|
||||
```
|
||||
|
||||
`sanitize()` cannot make an arbitrary string safe in a resource URL context. Either use `bypassSecurityTrustResourceUrl` if the value is fully under your control, or bind the value to a regular URL attribute that Angular can sanitize.
|
||||
|
||||
Look for a binding to one of the attributes above or a direct `sanitize()` call:
|
||||
|
||||
```html
|
||||
<iframe [src]="userUrl"></iframe>
|
||||
```
|
||||
|
||||
If the URL comes from a trusted, controlled source, mark it safe using `DomSanitizer.bypassSecurityTrustResourceUrl`:
|
||||
|
||||
```typescript
|
||||
import {DomSanitizer, SafeResourceUrl} from '@angular/platform-browser';
|
||||
|
||||
@Component({
|
||||
selector: 'my-app',
|
||||
})
|
||||
export class App {
|
||||
safeUrl: SafeResourceUrl = inject(DomSanitizer).bypassSecurityTrustResourceUrl(
|
||||
'https://example.com/embed',
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
```html
|
||||
<iframe [src]="safeUrl"></iframe>
|
||||
```
|
||||
|
||||
`bypassSecurityTrustResourceUrl` is an escape hatch, not a sanitizer. Never pass user-supplied URLs through it — that would allow an attacker to load arbitrary content, including malicious scripts. Only use it when the value is fully under your control.
|
||||
@@ -19,7 +19,7 @@ export const enum RuntimeErrorCode {
|
||||
// (undocumented)
|
||||
SANITIZATION_UNEXPECTED_CTX = 5202,
|
||||
// (undocumented)
|
||||
SANITIZATION_UNSAFE_RESOURCE_URL = 5201,
|
||||
SANITIZATION_UNSAFE_RESOURCE_URL = -5201,
|
||||
// (undocumented)
|
||||
SANITIZATION_UNSAFE_SCRIPT = 5200,
|
||||
// (undocumented)
|
||||
|
||||
@@ -24,7 +24,7 @@ export const enum RuntimeErrorCode {
|
||||
|
||||
// Sanitization-related errors (5200-5300 range)
|
||||
SANITIZATION_UNSAFE_SCRIPT = 5200,
|
||||
SANITIZATION_UNSAFE_RESOURCE_URL = 5201,
|
||||
SANITIZATION_UNSAFE_RESOURCE_URL = -5201,
|
||||
SANITIZATION_UNEXPECTED_CTX = 5202,
|
||||
|
||||
// Animations related errors (5300-5400 range)
|
||||
|
||||
Reference in New Issue
Block a user