From 5a072d8c91a04bca4f2c21748dbedf532fc1b1ad Mon Sep 17 00:00:00 2001
From: aminesbdev <aminedev9@gmail.com>
Date: Sun, 9 Aug 2026 13:18:58 +0200
Subject: [PATCH] docs: add security and sanitization reference to developer
 skill

---
 skills/dev-skills/angular-developer/SKILL.md  |   6 +
 .../angular-developer/references/security.md  | 115 ++++++++++++++++++
 2 files changed, 121 insertions(+)
 create mode 100644 skills/dev-skills/angular-developer/references/security.md

diff --git a/skills/dev-skills/angular-developer/SKILL.md b/skills/dev-skills/angular-developer/SKILL.md
index 6ab0e3d77009..f36be38cee9d 100644
--- a/skills/dev-skills/angular-developer/SKILL.md
+++ b/skills/dev-skills/angular-developer/SKILL.md
@@ -67,6 +67,12 @@ When communicating with backend services, use Angular HTTP APIs and consult the
 
 - **HTTP Client and Resources**: `provideHttpClient`, `HttpClient`, interceptors, and `httpResource`. Read [http-client.md](references/http-client.md)
 
+## Security
+
+When securing your application and rendering dynamic content safely, consult the following reference:
+
+- **Security and Sanitization**: Context-based sanitization, bypassing security with `DomSanitizer`, safe pipes, and Trusted Types. Read [security.md](references/security.md)
+
 ## Forms
 
 In most cases for new apps, **prefer signal forms**. When making a forms decision, analyze the project and consider the following guidelines:
diff --git a/skills/dev-skills/angular-developer/references/security.md b/skills/dev-skills/angular-developer/references/security.md
new file mode 100644
index 000000000000..ae9587f35fab
--- /dev/null
+++ b/skills/dev-skills/angular-developer/references/security.md
@@ -0,0 +1,115 @@
+# Security and Sanitization
+
+Angular provides built-in protection against Cross-Site Scripting (XSS) attacks. By default, Angular treats all values as untrusted and automatically sanitizes them before inserting them into the DOM.
+
+---
+
+## Context-Based Sanitization
+
+Angular automatically detects the context in which a value is bound and applies the appropriate sanitization:
+
+- **HTML**: Used when binding to innerHTML (`[innerHTML]="value"`). Angular strips unsafe elements (such as `<script>`, `<object>`, `<embed>`) and attributes (such as `onerror`, `onclick`).
+- **Style**: Used when binding to style properties (`[style.color]="value"` or `[style]="value"`). Angular ensures CSS values do not contain executable script code.
+- **URL**: Used when binding to links and media elements (`[href]="value"` or `[src]="value"`). Safe schemes like `http`, `https`, `mailto`, and `tel` are allowed; unsafe schemes like `javascript:` are prefixed with `unsafe:`.
+- **Resource URL**: Used when loading external code or frames (`[src]="value"` on an `<iframe>` or `<script>`). **Angular does not auto-sanitize Resource URLs.** You must explicitly mark them as trusted, otherwise Angular throws an error.
+
+---
+
+## Bypassing Security with `DomSanitizer`
+
+If you need to render trusted dynamic HTML, style, or URL content that would otherwise be sanitized or blocked, inject `DomSanitizer` from `@angular/platform-browser` to mark the value as safe.
+
+### Methods
+
+- `bypassSecurityTrustHtml(value)`
+- `bypassSecurityTrustStyle(value)`
+- `bypassSecurityTrustScript(value)`
+- `bypassSecurityTrustUrl(value)`
+- `bypassSecurityTrustResourceUrl(value)`
+
+### Example: Rendering an iframe
+
+```ts
+import {Component, computed, inject, input} from '@angular/core';
+import {DomSanitizer, SafeResourceUrl} from '@angular/platform-browser';
+
+@Component({
+  selector: 'app-video-player',
+  template: `
+    <iframe [src]="safeVideoUrl()" width="560" height="315"></iframe>
+  `,
+})
+export class VideoPlayer {
+  private readonly sanitizer = inject(DomSanitizer);
+  readonly videoId = input.required<string>();
+
+  // Use a computed signal to safely derive the resource URL
+  protected readonly safeVideoUrl = computed<SafeResourceUrl>(() => {
+    const rawUrl = `https://www.youtube.com/embed/${this.videoId()}`;
+    return this.sanitizer.bypassSecurityTrustResourceUrl(rawUrl);
+  });
+}
+```
+
+---
+
+## The Safe Pipe Pattern
+
+To avoid repeating `DomSanitizer` calls in TypeScript components, use a **standalone pipe** to bypass security directly within templates.
+
+```ts
+import {Pipe, PipeTransform, inject} from '@angular/core';
+import {DomSanitizer, SafeHtml} from '@angular/platform-browser';
+
+@Pipe({
+  name: 'safeHtml',
+  standalone: true,
+})
+export class SafeHtmlPipe implements PipeTransform {
+  private readonly sanitizer = inject(DomSanitizer);
+
+  transform(value: string): SafeHtml {
+    return this.sanitizer.bypassSecurityTrustHtml(value);
+  }
+}
+```
+
+Usage in a component:
+
+```ts
+import {Component, signal} from '@angular/core';
+import {SafeHtmlPipe} from './safe-html.pipe';
+
+@Component({
+  selector: 'app-rich-text',
+  imports: [SafeHtmlPipe],
+  template: `
+    <div [innerHTML]="rawHtml() | safeHtml"></div>
+  `,
+})
+export class RichText {
+  protected readonly rawHtml = signal('<p>This is <strong>safe</strong> content.</p>');
+}
+```
+
+---
+
+## Trusted Types
+
+Angular supports **Trusted Types**, a browser security feature that helps prevent DOM XSS. When configured, the browser restricts DOM APIs to only accept specialized objects (like `TrustedHTML`) instead of plain strings.
+
+To enable Trusted Types in Angular:
+1. Configure your web server to send the `Content-Security-Policy` header:
+   ```http
+   Content-Security-Policy: require-trusted-types-for 'script'; trusted-types angular;
+   ```
+2. Angular will automatically create and use a Trusted Types policy named `angular` to serialize and trust HTML, URLs, and scripts.
+
+---
+
+## Recommended Patterns
+
+- **Minimize Bypassing**: Only bypass sanitization as a last resort. Always sanitize, strip, or validate content on the backend before relying on `DomSanitizer`.
+- **Never Trust Direct User Input**: Never pass raw, unvalidated user input directly into any `bypassSecurityTrust...` method.
+- **Avoid Direct DOM Manipulation**: Do not use native DOM APIs like `Element.innerHTML` or `Element.setAttribute` directly. Use Angular template bindings (`[innerHTML]`, `[attr.href]`), which automatically apply sanitization.
+- **Use Computed Signals for Sanitization**: When using `DomSanitizer` in components, wrap the conversion inside a `computed` signal so it recalculates only when the input changes.