# hk2/csp

> Magento 2 module to manage CSP whitelisted URLs

`composer require hk2/csp`

Canonical URL: https://packagento.com/hk2/csp

## At a glance

- **Vendor**: hk2 (https://packagento.com/hk2.md)
- **Latest version**: v2.1.0 — released 2026-07-16
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/hk2/csp and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require hk2/csp:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Magento 2 module to manage CSP whitelisted URLs

## README

![Version](https://img.shields.io/badge/version-3.0.0-blue?style=flat-square)
![License](https://img.shields.io/badge/license-OSL--3.0-green?style=flat-square)
![Magento](https://img.shields.io/badge/Magento-2.4.4--2.4.9-f97316?style=flat-square&logo=magento&logoColor=white)
![PHP](https://img.shields.io/badge/PHP-8.1%20%7C%7C%208.2%20%7C%7C%208.3%20%7C%7C%208.4-7c3aed?style=flat-square&logo=php&logoColor=white)
[![Downloads](https://img.shields.io/packagist/dt/hk2/csp?style=flat-square)](https://packagist.org/packages/hk2/csp)

### Overview

HK2 CSP is a Magento 2 extension that enables administrators to manage Content Security Policy (CSP) whitelists dynamically. In addition to a robust set of pre-configured whitelist hosts for third-party scripts, styles, fonts, images, frames, and connections, it provides an admin interface to add custom domains without touching configuration files.

### 🎯 Use Cases

- **Third-Party Integrations**: Safe whitelisting for Google Analytics, Stripe, Facebook, and other standard services.
- **Admin Management**: Direct, safe administrative management of CSP hosts dynamically.

### 🚀 Features

- 🛡 Declares standard CSP policy parameters in `etc/csp.xml`.
- 📦 Out-of-the-box whitelists for popular services (Google, Facebook, Stripe, Hotjar, Sentry, etc.).
- ⚙️ Dynamic admin configurations for directive hosts (`script-src`, `style-src`, `img-src`, `connect-src`, `font-src`, `frame-src`).
- 🔌 Backend validation plugin preventing invalid hosts or header injections.
- 🔄 One-click dynamic "Reset CSP to Defaults" button via Ajax backend redirect.

### 🏗 Architecture

- **Plugin**: `HK2\Csp\Plugin\PolicyListPlugin` intercepts `Magento\Csp\Model\Policy\PolicyList::getAllPolicies` to dynamically merge administrative hosts.
- **Controller**: `HK2\Csp\Controller\Adminhtml\Reset\ResetConfig` handles configuration wipe operations.

### 🧩 Magento Components

#### Blocks

- `HK2\Csp\Block\Adminhtml\System\Config\ResetButton`

#### Plugins

- `HK2\Csp\Plugin\PolicyListPlugin` on `Magento\Csp\Model\Policy\PolicyList`

#### Controllers

- `HK2\Csp\Controller\Adminhtml\Reset\ResetConfig`

### 📦 Requirements

- **Magento version**: 2.4.4 - 2.4.9
- **PHP requirements**: 8.1 || 8.2 || 8.3 || 8.4
- **Required Extension**: `HK2_Core`

### ⚙️ Installation

1. `composer require hk2/csp`
2. `bin/magento module:enable HK2_Csp`
3. `bin/magento setup:upgrade`
4. `bin/magento setup:di:compile`
5. `bin/magento cache:flush`

### 🔧 Configuration

Configure settings under **Stores > Configuration > HK2 > CSP Whitelisting**:

| Field | Description |
|-------|-------------|
| **Script Src URLs** | Comma-separated list of script host domains (e.g. `*.example.com`). |
| **Style Src URLs** | Comma-separated list of style host domains. |
| **Image Src URLs** | Comma-separated list of image host domains. |
| **Connect Src URLs** | Comma-separated list of connect/API host domains. |
| **Font Src URLs** | Comma-separated list of font host domains. |
| **Frame Src URLs** | Comma-separated list of frame/iframe host domains. |
| **Reset CSP** | Button to clear all scopes and restore default whitelists. |

### Usage

Navigate to **Stores > Configuration > HK2 > CSP Whitelisting**, populate domains matching your external integrations, and save. Run `bin/magento cache:flush` to apply.

### 🗄 Database Changes

Not Applicable

### 📂 Module Structure

```text
Block/
└── Adminhtml/
    └── System/
        └── Config/
            └── ResetButton.php
Controller/
└── Adminhtml/
    └── Reset/
        └── ResetConfig.php
Plugin/
└── PolicyListPlugin.php
etc/
├── adminhtml/
│   ├── menu.xml
│   ├── routes.xml
│   └── system.xml
├── acl.xml
├── config.xml
├── csp.xml
├── csp_whitelist.xml
├── di.xml
└── module.xml
view/
└── adminhtml/
    └── templates/
        └── system/
            └── config/
                └── reset_button.phtml
```

### 📈 Performance Considerations

The policies list is cached inside Magento's standard configuration cache, preventing database queries or regex calculations on standard page loads.

### 🔐 Security Considerations

- **Input Validation**: `isValidCspHost` prevents semicolons, commas, and white spaces in custom values, protecting the headers against header splitting or policy injection attacks.

### Compatibility

Reference: [docs/compatibility.md](docs/compatibility.md)

| Platform | Supported Versions |
|----------|-------------------|
| Magento  | 2.4.4 - 2.4.9     |
| PHP      | 8.1, 8.2, 8.3, 8.4 |

### 🛠 Troubleshooting

#### Dynamic values not appearing in CSP header

Verify you have flushed the configuration cache after making changes: `bin/magento cache:flush`.

### 🤝 Contributing

Contributions are welcome! If you'd like to improve the installer:

- ⭐ **Star this repository** (Helps others find it!)
- 🍴 Fork the project
- 🐛 Report bugs
- 💡 Suggest new features
- 🤝 Contribute improvements

Every ⭐ helps increase the visibility of the project and motivates further development.

### ⚖️ Disclaimer

The author provides this installation script "as is" without any warranties. Users are responsible for ensuring that running this script complies with their internal security and software requirements.

### 🤝 Support

For bug reports, feature requests, and general support:

- **Author**: Basant Mandal
- **Email**: <support@basantmandal.in>
- **Website**: <https://www.basantmandal.in>

### License

This project is licensed under the OSL 3.0 License. See the [LICENSE.txt](LICENSE.txt) file for details.

---

## Changelog

#### ✨ Features

* update placeholder version in bug report template ([a7c10b9](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/a7c10b95cc32d0d4942374d342d1ffa736abd65d))

### 1.0.0 (2026-07-16)

#### ⚠ BREAKING CHANGES

* Implement CSP Whitelisting Module

#### ✨ Features

* add contributing guide, bug report template, and pull request template for improved collaboration ([85d915d](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/85d915dda5b4b2e081176813d776f23c606cbd91))
* add localization files for English, Hindi, and Russian languages ([3f71f73](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/3f71f732e94a6539143d781613d329b5563a3fd1))
* add semantic release configuration for automated versioning and changelog generation ([a90c684](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/a90c6844a491338c429de116565a7f1c342d57b8))
* addition of Installation Guide ([060225b](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/060225b9b502399c06ddae6157b802086b7faa50))
* Implement CSP Whitelisting Module ([b23e35f](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/b23e35f6746a0eeefb10430b28b071716acefdf4))

#### 📝 Documentation

* update README.md to enhance clarity and structure, including use cases and features ([ca79814](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/ca7981497cd9695db28961ba73637394e25efcf2))

### 1.0.0 (2026-07-16)

#### ⚠ BREAKING CHANGES

* Implement CSP Whitelisting Module

#### ✨ Features

* add contributing guide, bug report template, and pull request template for improved collaboration ([85d915d](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/85d915dda5b4b2e081176813d776f23c606cbd91))
* add localization files for English, Hindi, and Russian languages ([3f71f73](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/3f71f732e94a6539143d781613d329b5563a3fd1))
* add semantic release configuration for automated versioning and changelog generation ([a90c684](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/a90c6844a491338c429de116565a7f1c342d57b8))
* Implement CSP Whitelisting Module ([b23e35f](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/b23e35f6746a0eeefb10430b28b071716acefdf4))

#### 📝 Documentation

* update README.md to enhance clarity and structure, including use cases and features ([ca79814](https://github.com/basantmandal/magento2-csp-whitelisting-module/commit/ca7981497cd9695db28961ba73637394e25efcf2))

## Recent Versions

| Version | Released |
|---|---|
| v2.1.0 | 2026-07-16 |
| v2.0.0 | 2026-07-16 |
| 1.0.3 | 2024-12-25 |
| 1.0.2 | 2023-07-15 |
| 1.0.0 | 2022-06-16 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| hk2/core | ^1.0 |
| magento/framework | ^103.0.0 |
| magento/module-csp | ^100.4 |
| php | ^8.1 \|\| ^8.2 \|\| ^8.3 \|\| ^8.4 |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["hk2/csp"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

hk2 is a Magento 2 vendor on Packagento. See https://packagento.com/hk2.md for their full catalogue.