README

This module contains the Paradise CSP Learning Hub - an interactive educational experience teaching developers how to migrate code to strict Content Security Policy (CSP) compliance.

Module Name

HyvaParadise_Frontend

Installation

Install via the metapackage:

composer require friends-of-hyva/magento2-paradise-csp-workshop-meta

Or install directly:

composer require friends-of-hyva/magento2-paradise-csp-workshop-frontend
bin/magento setup:upgrade --keep-generated

If the package isn't on Packagist yet

If composer require can't find the package, add the GitHub repository manually to your project's composer.json.

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/friends-of-hyva/magento2-paradise-csp-workshop-frontend"
        }
    ]
}

Then run:

composer require friends-of-hyva/magento2-paradise-csp-workshop-frontend
bin/magento setup:upgrade --keep-generated

Paradise CSP Learning Hub

A learning experience that teaches CSP migration through interactive fixing:

URL: /paradise/
Status: Contains intentionally unsafe code that students fix using the hyva-csp-helper.php tool
Learning Method: As students apply migrations, features unlock (interactive feedback loop)

The Concept

The learning hub starts with broken code demonstrating all 8 CSP anti-patterns:

Inline expressions in @click
Alpine negation operators
x-model directives
Method arguments in attributes
Conditional class objects
Complex template expressions
Inline script registration
Alpine component registration

Students run the migration tool, which auto-fixes most patterns. As they do, the page becomes more interactive - creating a powerful learning experience.

Features

1. Pattern Gallery

8 CSP migration patterns with before/after code examples
Toggle between unsafe and CSP-compliant versions
Explanation of why each pattern matters

2. Interactive Quiz

15 questions covering CSP concepts and the Hyvä Developers Paradise event
Multiple difficulty levels (easy, medium)
Instant feedback on answers
Progress bar tracking current question
Auto-advance after correct answers with pause/resume control
Wrong answer review on completion
Quiz restart functionality

3. Resources Section

Links to Hyva CSP documentation
Migration tool guide
PCI-DSS 4.0 information

How to Use (For Students)

Step 1: Visit the Learning Hub

https://yoursite.local/paradise/

Step 2: Notice the Broken UI

Some buttons don't work
Dropdowns aren't interactive
Quiz might not function properly
This is intentional!

Step 3: Run the Migration Tool

php tools/hyva-csp-helper.php

Step 4: Refresh and See Features Unlock

Navigation buttons now work
Dropdowns become interactive
Quiz becomes fully functional
Visual feedback appears

Step 5: Learn and Understand

Each fixed pattern teaches a CSP migration technique you'll use in real code.

Directory Structure

magento2-paradise-frontend/
├── Api/
│   ├── PatternDataInterface.php         # Pattern data contract
│   └── QuestionDataInterface.php        # Question data contract
├── Controller/
│   └── Index/
│       └── Index.php                    # Route handler for /paradise/
├── Model/
│   ├── PatternData.php                  # 8 CSP patterns with code examples
│   └── QuestionData.php                 # 15 quiz questions
├── ViewModel/
│   ├── PatternData.php                  # View model wrapper for patterns
│   └── QuestionData.php                 # View model wrapper for questions
├── etc/
│   ├── module.xml
│   └── frontend/
│       ├── di.xml                       # Dependency injection
│       └── routes.xml                   # /paradise/ route
├── view/frontend/
│   ├── layout/
│   │   ├── paradise_index_index.xml     # Page layout for /paradise/
│   │   └── cms_index_index.xml          # Homepage link injection
│   ├── templates/
│   │   ├── learning-hub.phtml           # Main template
│   │   ├── homepage-link.phtml          # CMS homepage banner
│   │   └── sections/
│   │       ├── broken-notice.phtml      # Initially visible warning banner
│   │       ├── patterns.phtml           # Pattern gallery (8 patterns)
│   │       ├── quiz.phtml               # Interactive quiz (15 questions)
│   │       └── learn-more.phtml         # Resources section
│   └── web/
│       └── images/
│           └── hero-paradise-csp.svg    # Hero image
├── composer.json
├── registration.php
├── COPYING.txt
├── LICENSE.txt
└── SECURITY.md

Technical Details

Patterns Included

#	Pattern	Initial Problem	After Migration
1	Inline expressions in @click	Code in event handlers blocked	Navigation works
2	Negation operator	`!open` not supported in Alpine CSP	Toggles work
3	x-model directive	Not available in Alpine CSP build	Dropdowns interactive
4	Method arguments in @click	Arguments evaluated as expressions	Data passed via `data-*`
5	Conditional class objects	Inline object literals not allowed	Classes from methods
6	Complex template expressions	Dynamic array access unsafe	Expressions in methods
7	Inline script registration	Scripts blocked without nonce/hash	`registerInlineScript()` added
8	Alpine component registration	Components not registered via `alpine:init`	Proper registration pattern

Data Models

PatternData (Model/PatternData.php):

8 patterns with unsafe/safe code examples
Explanations and difficulty levels per pattern

QuestionData (Model/QuestionData.php):

15 quiz questions (10 CSP technical + 5 Hyvä Developers Paradise)
Multiple choice options with correct answer tracking
Learning explanations per question
Difficulty assignments (easy/medium)

Alpine Components

paradisePatterns() (sections/patterns.phtml):

Renders all 8 patterns in a 2-column grid
Toggles between unsafe and safe code per pattern
Data injected server-side via json_encode()

paradiseQuiz() (sections/quiz.phtml):

Shuffles questions on init
Tracks current question index and score
Auto-advances after correct answers (with pause/resume)
Shows wrong answer review on completion
Supports full quiz restart

Both components are registered via window.addEventListener('alpine:init', ...) and $hyvaCsp->registerInlineScript() - demonstrating patterns 7 and 8 directly in the module's own code.

CSP Compliance

The learning hub itself demonstrates CSP compliance:

No unsafe-eval
All inline scripts registered with $hyvaCsp->registerInlineScript()
Alpine CSP-compatible patterns throughout
Data passed via json_encode() and data-* attributes
Components registered via alpine:init

PCI-DSS 4.0 Context

This module addresses PCI-DSS 4.0 compliance requirements (effective April 1, 2025):

Requires strict CSP on payment pages
Eliminates unsafe-eval vulnerability
Makes payment processing secure

Dependencies

Magento Framework 102.0+ or 103.0+
Hyva Theme Module 1.2.28+
Alpine.js (CSP build, provided by Hyva theme)

License

Open Software License ("OSL") v. 3.0

Support

Hyva Documentation: https://docs.hyva.io/
Paradise Event: https://www.hyvadevparadise.com/
Community: Hyva Slack & Discord

friends-of-hyva / magento2-paradise-csp-workshop-frontend

Maintainers

Package info

Statistics

Security