{"id":29943351,"url":"https://github.com/sourcefuse/arc-spa-csp","last_synced_at":"2026-05-09T06:02:42.146Z","repository":{"id":303622997,"uuid":"995384788","full_name":"sourcefuse/arc-spa-csp","owner":"sourcefuse","description":"Production-ready CSP injector for React, Angular \u0026 VITE projects. Smart auto-detection, environment variables, workspace support. Enterprise-grade SPA security.","archived":false,"fork":false,"pushed_at":"2025-07-10T12:42:23.000Z","size":162,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-05T01:36:16.084Z","etag":null,"topics":["angular","build-tool","content-security-policy","csp","react","security","single-page-application","spa","typescript","web-security","xss-protection"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sourcefuse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-03T11:59:03.000Z","updated_at":"2025-07-10T12:42:25.000Z","dependencies_parsed_at":"2025-07-08T15:56:36.222Z","dependency_job_id":null,"html_url":"https://github.com/sourcefuse/arc-spa-csp","commit_stats":null,"previous_names":["sourcefuse/arc-spa-csp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/sourcefuse/arc-spa-csp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Farc-spa-csp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Farc-spa-csp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Farc-spa-csp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Farc-spa-csp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sourcefuse","download_url":"https://codeload.github.com/sourcefuse/arc-spa-csp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Farc-spa-csp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32809147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","build-tool","content-security-policy","csp","react","security","single-page-application","spa","typescript","web-security","xss-protection"],"created_at":"2025-08-03T02:15:05.785Z","updated_at":"2026-05-09T06:02:42.127Z","avatar_url":"https://github.com/sourcefuse.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ arc-spa-csp\n\n\u003e Content Security Policy (CSP) injector for Single Page Applications (SPAs) - React, Angular, and VITE projects with comprehensive framework support\n\n[![npm version](https://badge.fury.io/js/arc-spa-csp.svg)](https://www.npmjs.com/package/arc-spa-csp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Coverage](https://img.shields.io/badge/Coverage-74%25-orange.svg)](https://github.com/sourcefuse/arc-spa-csp)\n[![Tests](https://img.shields.io/badge/Tests-109%20Passing-brightgreen.svg)](https://github.com/sourcefuse/arc-spa-csp)\n[![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)\n\n## ✨ Features\n\n- 🎯 **Smart Auto-detection**: Automatically finds HTML files for React, Angular, VITE, and workspace projects\n- 📦 **Zero Runtime Dependencies**: Pure TypeScript with minimal external dependencies\n- ⚙️ **Intelligent Defaults**: Works out-of-the-box with framework-specific CSP policies\n- 🔧 **Environment Aware**: Separate development and production configurations\n- 📄 **Maximum Flexibility**: Supports custom HTML and config file paths\n- 🔐 **Production Ready**: Secure CSP policies with cryptographic nonce support\n- 🌍 **Template Variables**: Dynamic interpolation with {{REACT_APP_*}}, {{VITE_*}}, and {{NG_*}}\n- 🚀 **Full VITE Support**: Complete VITE environment variable integration\n- 🏗️ **Angular Workspace**: Native support for Angular workspace projects with proper environment isolation\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\nnpm install -g arc-spa-csp\n# or\nnpx arc-spa-csp init  # Create default config\n```\n\n### Development Mode (No Build Required)\n\n#### React Projects\n\n```bash\n# Inject CSP into public/index.html (used by React dev server)\narc-spa-csp --dev\n```\n\n#### VITE Projects\n\n```bash\n# Inject CSP into index.html (used by VITE dev server)\narc-spa-csp --dev\n```\n\n#### Angular Projects\n\n```bash\n# Inject CSP into src/index.html (used by ng serve)\narc-spa-csp --dev\n```\n\n#### Angular Workspaces\n\n```bash\n# Auto-detects projects/*/src/index.html (e.g., projects/arc/src/index.html)\narc-spa-csp --dev\n\n# Or specify explicitly:\narc-spa-csp --dev --html projects/arc/src/index.html\n```\n\n### Production Mode (After Build)\n\n```bash\n# For React (after npm run build)\nnpm run build\narc-spa-csp\n\n# For VITE (after npm run build)\nnpm run build\narc-spa-csp\n\n# For Angular (after ng build)\nng build\narc-spa-csp\n\n# Custom HTML file\narc-spa-csp --html dist/my-app/index.html\n```\n\n## 🛠️ CLI Commands\n\n### Initialize Configuration\n\n```bash\n# Create default csp.config.json\narc-spa-csp init\n\n# Interactive configuration wizard (recommended)\narc-spa-csp init --interactive\n\n# Use with npx (no installation)\nnpx arc-spa-csp init --interactive\n```\n\n#### 🧙‍♂️ Interactive Configuration Wizard\n\nThe interactive mode guides you through creating the perfect CSP configuration for your project:\n\n```bash\narc-spa-csp init --interactive\n```\n\n#### Features\n\n- 🚀 Framework Detection: Choose from React CRA, VITE, Angular CLI, or Generic\n- ⚙️ Configuration Type: Development (permissive) or Production (strict)\n- 🔐 Security Options: Enable nonce support for enhanced security\n- 🌍 Environment Variables: Auto-include framework-specific variable templates\n- 📊 Report Mode: Option for report-only CSP (logs without blocking)\n\n#### Example Interactive Session\n\n```text\n🎉 Welcome to arc-spa-csp configuration wizard!\nLet's set up your Content Security Policy configuration.\n\n🚀 Which framework are you using?\n  1. React (Create React App) - Traditional React with Create React App\n  2. VITE (React/Vue/Vanilla) - Modern build tool with fast HMR\n  3. Angular CLI - Angular framework with CLI\n  4. Generic/Other - Other frameworks or custom setup\n\nSelect framework (1-4): 2\n✅ Selected: VITE (React/Vue/Vanilla)\n\n⚙️ Configuration type:\n  1. Development (permissive, good for testing)\n  2. Production (strict, secure for deployment)\n  3. Custom (configure directives manually)\n\nSelect type (1-3): 1\n✅ Configuration type: development\n\n🔐 Enable nonce for inline scripts/styles? (recommended for production) [y/N]: n\n\n❓ Use report-only mode? (logs violations without blocking) [y/N]: n\n\n🌍 Include VITE_* environment variable templates? [Y/n]: y\n\n⚙️ Configuration summary:\n  Framework: vite\n  Type: development\n  Nonce: disabled\n  Report-only: disabled\n  Environment variables: included\n\n⚙️ Created config file: csp.config.json\n```\n\n### Inject CSP\n\n```text\nUSAGE:\n  arc-spa-csp [options]\n\nCOMMANDS:\n  init                         Create default csp.config.json file\n  (no command)                 Inject CSP into HTML file\n\nOPTIONS:\n  --html, -h \u003cpath\u003e     Path to HTML file (auto-detected if not specified)\n  --config, -c \u003cpath\u003e   Path to config file (uses defaults if not specified)\n  --dev, -d            Development mode (injects into source files)\n  --dry-run            Show what would be done without making changes\n  --help               Show this help\n  --version, -v        Show version\n\nEXAMPLES:\n  arc-spa-csp                              # Auto-detect and inject CSP\n  arc-spa-csp --dev                        # Development mode (no build required)\n  arc-spa-csp --html build/index.html      # Specific HTML file\n  arc-spa-csp --config custom.json         # Custom config\n  arc-spa-csp --dry-run                    # Preview changes\n  arc-spa-csp init                         # Create default config file\n```\n\n## 🔄 Development Workflow\n\n### Working with Dev Servers\n\nThe `--dev` flag is designed for development workflows where you want to test CSP policies without building your project:\n\n#### React Development\n\n1. Run `arc-spa-csp --dev` - modifies `public/index.html`\n2. Start your dev server: `npm start` or `yarn start`\n3. The React dev server serves the modified HTML with CSP headers\n4. Test your application and iterate on CSP policies\n\n#### VITE Development\n\n1. Run `arc-spa-csp --dev` - modifies `index.html`\n2. Start VITE dev server: `npm run dev` or `yarn dev`\n3. The VITE dev server serves the modified HTML with CSP headers\n4. Test your application with real CSP policies\n\n#### Angular Development\n\n1. Run `arc-spa-csp --dev` - modifies `src/index.html`\n2. Start Angular dev server: `ng serve`\n3. The Angular dev server serves the modified HTML with CSP headers\n4. Test your application and iterate on CSP policies\n\n#### Key Benefits\n\n- ✅ No build required - Test CSP policies immediately\n- ✅ Hot reload friendly - CSP persists through dev server reloads\n- ✅ Source control safe - Changes are in source files\n- ✅ Environment aware - Automatic resolution of development env vars\n\n### Production Deployment\n\nFor production, run CSP injection after your build process:\n\n```bash\n# React\nnpm run build\narc-spa-csp\n\n# VITE\nnpm run build\narc-spa-csp\n\n# Angular\nng build\narc-spa-csp\n```\n\n## 📁 Framework Auto-Detection\n\n### ⚛️ React Projects\n\n#### React Development Mode (`--dev`)\n\n- ✅ `public/index.html` (Create React App default)\n\n#### React Production Mode (default)\n\n- ✅ `build/index.html` (Create React App build output)\n- ✅ `dist/index.html` (Vite, Webpack builds)\n\n### ⚡ VITE Projects\n\n#### VITE Development Mode (`--dev`)\n\n- ✅ `index.html` (VITE project root)\n\n#### VITE Production Mode (default)\n\n- ✅ `dist/index.html` (VITE build output)\n\n### 🅰️ Angular Projects\n\n#### Angular Development Mode (`--dev`)\n\n- ✅ `src/index.html` (Standard Angular project)\n- ✅ `projects/*/src/index.html` (Angular workspace projects)\n\n#### Angular Production Mode (default)\n\n- ✅ `dist/project-name/index.html` (Angular CLI default)\n- ✅ `dist/index.html` (Simple builds)\n- 🔍 Smart Detection: Reads `angular.json` to find exact build output path\n\n#### 🏗️ Angular Workspace Support\n\nFull support for Angular workspace projects with proper environment isolation.\n\n**How it works**:\n\n```bash\n# Workspace root - uses workspace environment\narc-spa-csp --dev --html src/index.html\n\n# Specific project - uses project-specific environment\narc-spa-csp --dev --html projects/my-app/src/index.html\n```\n\n**Environment Variable Loading**:\n\n- **Workspace Root**: `src/environments/environment.ts` → `NG_*` variables\n- **Workspace Project**: `projects/my-app/src/environments/environment.ts` → `NG_*` variables\n- **Automatic Detection**: Detects correct project root from HTML path\n- **Environment Isolation**: Each project can have different environment variables\n\n**Example Workspace Structure**:\n\n```\nmy-workspace/\n├── angular.json\n├── src/environments/environment.ts          # Workspace root env\n└── projects/\n    ├── app1/src/environments/environment.ts # App1 specific env\n    └── app2/src/environments/environment.ts # App2 specific env\n```\n\n**Usage Examples**:\n\n```bash\n# Target specific workspace project\narc-spa-csp --dev --html projects/app1/src/index.html\n\n# Auto-detection finds workspace projects\narc-spa-csp --dev  # Searches projects/*/src/index.html automatically\n\n# Different environments for different projects\n# app1 uses: NG_APIURL=https://app1-api.com\n# app2 uses: NG_APIURL=https://app2-api.com\n```\n\n### 🌐 Other Frameworks\n\nWhile optimized for React, VITE, and Angular, the tool can work with other frameworks that use similar HTML file structures:\n\n- ✅ **Ionic**: `www/index.html`\n- ✅ **Vue.js**: `dist/index.html`, `public/index.html` (generic HTML detection)\n- ✅ **Generic HTML**: `index.html` (root directory)\n\n_Note: Environment variable support ({{VARIABLE}}) is specific to React, VITE, and Angular projects._\n\n## ⚙️ Configuration\n\n### Quick Setup\n\n```bash\n# Create default configuration\narc-spa-csp init\n\n# This creates csp.config.json with sensible defaults\n```\n\n### Manual Configuration\n\nCreate a `csp.config.json` file in your project root:\n\n```json\n{\n  \"directives\": {\n    \"default-src\": [\"'self'\"],\n    \"script-src\": [\"'self'\", \"'unsafe-inline'\"],\n    \"style-src\": [\"'self'\", \"'unsafe-inline'\"],\n    \"img-src\": [\"'self'\", \"data:\", \"blob:\"],\n    \"font-src\": [\"'self'\", \"data:\"],\n    \"connect-src\": [\"'self'\"],\n    \"worker-src\": [\"'self'\", \"blob:\"],\n    \"manifest-src\": [\"'self'\"]\n  },\n  \"useNonce\": false,\n  \"reportOnly\": false\n}\n```\n\n### Environment Variable Support\n\nCreate dynamic configurations with template variables:\n\n```json\n{\n  \"directives\": {\n    \"script-src\": [\"'self'\", \"{{REACT_APP_API_URL}}\", \"{{VITE_API_URL}}\", \"{{NG_APIURL}}\"],\n    \"img-src\": [\"'self'\", \"data:\", \"{{REACT_APP_CDN_URL}}\", \"{{VITE_CDN_URL}}\"],\n    \"connect-src\": [\"'self'\", \"{{REACT_APP_API_URL}}\", \"{{VITE_API_URL}}\", \"{{NG_APIURL}}\"]\n  },\n  \"useNonce\": true\n}\n```\n\n#### React Environment Variables\n\n- ✅ `.env` files (all variants)\n- ✅ `REACT_APP_*` prefixed variables\n- ✅ Runtime environment variables\n\n#### VITE Environment Variables\n\n- ✅ `.env` files (all variants)\n- ✅ `VITE_*` prefixed variables\n- ✅ Mixed `REACT_APP_*` and `VITE_*` support in same project\n- ✅ Runtime environment variables\n\n#### Angular Environment Variables\n\n- ✅ `src/environments/environment.ts`\n- ✅ `src/environments/environment.prod.ts`\n- ✅ Automatic `NG_*` prefixed variables\n\n### Built-in Configurations\n\n#### Development (default)\n\n- Permissive CSP with `'unsafe-inline'`\n- No nonce required\n- Environment variable resolution\n\n#### Production (NODE_ENV=production)\n\n- Stricter CSP policies\n- Nonce support enabled\n- Enforced (blocking) mode\n\n## 🔧 API Usage\n\n```typescript\nimport { CSPInjector } from 'arc-spa-csp';\n\n// Simple injection with auto-detection\nconst result = CSPInjector.inject();\n\n// With custom options\nconst result = CSPInjector.inject({\n  htmlPath: 'dist/index.html',\n  configPath: 'custom-csp.json',\n  devMode: false,\n});\n\n// With custom config and environment variables\nconst result = CSPInjector.inject({\n  config: {\n    directives: {\n      'default-src': [\"'self'\"],\n      'script-src': [\"'self'\", \"'unsafe-inline'\"],\n    },\n    useNonce: true,\n  },\n  envVars: {\n    REACT_APP_API_URL: 'https://api.example.com',\n    VITE_API_URL: 'https://api.example.com',\n  },\n});\n\nconsole.log(`CSP injected into ${result.htmlPath}`);\nconsole.log(`Nonce: ${result.nonce}`);\n```\n\n## 🛠️ Build Integration\n\n### npm scripts\n\n```json\n{\n  \"scripts\": {\n    \"build\": \"vite build\",\n    \"build:csp\": \"npm run build \u0026\u0026 arc-spa-csp\",\n    \"dev:csp\": \"arc-spa-csp --dev\",\n    \"csp:init\": \"arc-spa-csp init --interactive\",\n    \"csp:preview\": \"arc-spa-csp --dry-run\"\n  }\n}\n```\n\n### CI/CD\n\n```yml\n- name: Build and inject CSP\n  run: |\n    npm run build\n    arc-spa-csp\n```\n\n## 🧪 Examples\n\n### Getting Started\n\n```bash\n# 1. Initialize configuration with interactive wizard (recommended)\narc-spa-csp init --interactive\n\n# 2. Follow the guided setup for your framework\n# 3. Test your configuration\narc-spa-csp --dry-run\n\n# 4. Apply CSP to your project\narc-spa-csp --dev  # for development\narc-spa-csp        # for production builds\n```\n\n#### Why use the interactive wizard?\n\n- ✅ Framework-Specific: Optimized configurations for React, VITE, Angular\n- ✅ Best Practices: Built-in security recommendations\n- ✅ Environment Ready: Auto-configures variable templates\n- ✅ No Guesswork: Guided setup with explanations\n\n### React with Create React App\n\n```bash\n# During development\nnpm start  # serves from public/\narc-spa-csp --dev  # injects CSP into public/index.html\n\n# For production\nnpm run build  # creates build/\narc-spa-csp  # injects CSP into build/index.html\n```\n\n### VITE Projects\n\n```bash\n# During development\nnpm run dev  # serves from root/index.html\narc-spa-csp --dev  # injects CSP into index.html\n\n# For production\nnpm run build  # creates dist/\narc-spa-csp  # injects CSP into dist/index.html\n```\n\n### Angular with CLI\n\n```bash\n# During development\nng serve  # serves from src/\narc-spa-csp --dev  # injects CSP into src/index.html\n\n# For production\nng build  # creates dist/my-app/\narc-spa-csp  # auto-detects and injects CSP\n```\n\n### Environment-Driven Configuration\n\n```bash\n# React project with environment variables\necho \"REACT_APP_API_URL=https://api.example.com\" \u003e .env.local\narc-spa-csp --config csp-template.json\n\n# VITE project with environment variables\necho \"VITE_API_URL=https://api.example.com\" \u003e .env.local\narc-spa-csp --config csp-template.json\n\n# Angular project with environment files\nNODE_ENV=production arc-spa-csp\n```\n\n## 🔧 Troubleshooting\n\n### HTML File Not Found\n\nIf auto-detection fails, specify the path explicitly:\n\n```bash\n# For React\narc-spa-csp --html build/index.html\n\n# For VITE\narc-spa-csp --html dist/index.html\n\n# For Angular\narc-spa-csp --html dist/my-project/index.html\n\n# For Angular workspace\narc-spa-csp --html projects/my-app/src/index.html\n```\n\n### Environment Variables Not Working\n\n1. **React**: Ensure variables have `REACT_APP_` prefix\n2. **VITE**: Ensure variables have `VITE_` prefix\n3. **Angular**: Check that `environment.ts` files exist in `src/environments/`\n4. **Templates**: Verify `{{VARIABLE_NAME}}` syntax in config files\n\n### Supported Environments\n\n- **Node.js**: 16.x, 18.x, 20.x, 21.x\n- **npm**: 8.x+\n- **Frameworks**: React, Angular, VITE\n\n### Development Setup\n\n```bash\ngit clone https://github.com/sourcefuse/arc-spa-csp.git\ncd arc-spa-csp\nnpm install\nnpm run build\nnpm test\n```\n\n## 📝 License\n\nMIT © [SourceFuse](https://github.com/sourcefuse)\n\n---\n\n## 🎯 About SPA (Single Page Applications)\n\n**SPA** stands for **Single Page Application** - a web application that loads a single HTML document and dynamically updates content as the user interacts with the app, without requiring full page reloads. SPAs are commonly built with frameworks like React, Angular, Vue.js, and built with tools like VITE.\n\nThis package specializes in securing SPAs by injecting Content Security Policy (CSP) headers that prevent common web vulnerabilities like XSS attacks, ensuring your single-page applications meet enterprise security standards.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcefuse%2Farc-spa-csp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsourcefuse%2Farc-spa-csp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcefuse%2Farc-spa-csp/lists"}