Merge branch 'master' into cursor/await-mode-change-restart

Author: ap0ught

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 🔒 Report a Critical Security Vulnerability (Private)
+    url: https://github.com/ap0ught/matrix/security/advisories/new
+    about: For sensitive or critical vulnerabilities, please use GitHub's private Security Advisory system instead of a public issue.

.github/ISSUE_TEMPLATE/security-vulnerability.yml

@@ -0,0 +1,113 @@
+name: 🔒 Security Vulnerability Report
+description: Report a security vulnerability or weakness in Matrix Digital Rain. For sensitive disclosures, please use GitHub Security Advisories instead.
+title: "[Security]: "
+labels: ["security", "vulnerability"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## ⚠️ Important: Responsible Disclosure
+
+        **For sensitive or critical vulnerabilities, please do NOT use this public issue form.**
+        Instead, use the [**GitHub Security Advisory**](https://github.com/ap0ught/matrix/security/advisories/new) (private disclosure).
+
+        This template is for:
+        - Low-severity security concerns or hardening suggestions
+        - Security-related questions or discussions
+        - Issues that do not expose sensitive user data or allow remote exploitation
+
+        See our [Security Policy](https://github.com/ap0ught/matrix/blob/master/SECURITY.md) for full guidance.
+
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity
+      description: How severe is this vulnerability?
+      options:
+        - High – exposes sensitive data or allows significant privilege escalation
+        - Medium – limited impact, requires user interaction or specific conditions
+        - Low – minor weakness, defense-in-depth improvement
+        - Informational – security suggestion or best practice
+    validations:
+      required: true
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Affected Component
+      description: Which part of the application is affected?
+      options:
+        - Spotify OAuth / Authentication
+        - URL parameter handling / Config parsing
+        - WebGL / WebGPU renderer
+        - Service Worker / PWA / Caching
+        - GitHub Actions / CI workflows
+        - Third-party dependencies (REGL, gl-matrix, etc.)
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Vulnerability Description
+      description: Describe the vulnerability clearly. Do NOT include proof-of-concept exploit code for critical issues — use Security Advisories for those.
+      placeholder: |
+        A clear and concise description of the security issue.
+        What is the weakness? What could an attacker do with it?
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can someone reproduce this issue?
+      placeholder: |
+        1. Open the application at http://localhost:8000
+        2. Navigate to ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: impact
+    attributes:
+      label: Potential Impact
+      description: What is the worst-case impact of this vulnerability if exploited?
+      placeholder: |
+        Describe the potential impact on users or the application.
+        e.g. "An attacker could steal a user's Spotify access token by..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggested-fix
+    attributes:
+      label: Suggested Fix (optional)
+      description: If you have a suggested fix or mitigation, please describe it here.
+      placeholder: |
+        e.g. "Validate the `state` parameter using a cryptographically random value..."
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Browser, OS, and application version where you observed this issue.
+      placeholder: |
+        - Browser: Chrome 120 / Firefox 121 / Safari 17
+        - OS: macOS 14 / Windows 11 / Ubuntu 22.04
+        - Renderer: WebGL / WebGPU
+        - Version: (see VERSION file or URL, e.g. 1.0.0)
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I have read the [Security Policy](https://github.com/ap0ught/matrix/blob/master/SECURITY.md)
+          required: true
+        - label: This is NOT a sensitive/critical vulnerability (those should be reported via [GitHub Security Advisories](https://github.com/ap0ught/matrix/security/advisories/new))
+          required: true
+        - label: I have searched existing issues to avoid duplicates
+          required: true

.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  # Keep npm dependencies up to date
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "security"
+
+  # Keep GitHub Actions up to date
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "security"

.github/workflows/master-branch-protection.yml

@@ -24,7 +24,7 @@ jobs:
         node-version: '18'
 
     - name: Setup Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.11'
 
@@ -158,15 +158,15 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Run Trivy vulnerability scanner
-      uses: aquasecurity/trivy-action@master
+      uses: aquasecurity/trivy-action@v0.35.0
       with:
         scan-type: 'fs'
         scan-ref: '.'
         format: 'sarif'
         output: 'trivy-results.sarif'
 
     - name: Upload Trivy scan results to GitHub Security tab
-      uses: github/codeql-action/upload-sarif@v2
+      uses: github/codeql-action/upload-sarif@v3
       if: always()
       with:
         sarif_file: 'trivy-results.sarif'

.github/workflows/release.yml

@@ -140,7 +140,7 @@ jobs:
         ls -lh "matrix-${{ steps.version.outputs.version }}.zip"
     
     - name: Create GitHub Release
-      uses: softprops/action-gh-release@v1
+      uses: softprops/action-gh-release@v2
       with:
         tag_name: ${{ steps.version.outputs.tag }}
         name: Matrix Digital Rain v${{ steps.version.outputs.version }}

SECURITY.md

@@ -0,0 +1,61 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| latest  | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in the Matrix Digital Rain project, please report it responsibly.
+
+**Please do not open a public GitHub issue for security vulnerabilities.**
+
+Instead, please report security vulnerabilities by:
+
+1. Opening a [GitHub Security Advisory](https://github.com/ap0ught/matrix/security/advisories/new) (preferred)
+2. Or emailing the repository maintainer directly
+
+Please include the following information in your report:
+
+- A description of the vulnerability and its potential impact
+- Steps to reproduce the issue
+- Any proof-of-concept code (if applicable)
+- Suggested fix (if you have one)
+
+## Security Considerations
+
+### Client-Side Application
+
+Matrix Digital Rain is a purely client-side web application with no server-side components. This means:
+
+- No user data is transmitted to any server (except optional Spotify API integration)
+- No authentication is required to use the application
+- All processing happens in the browser
+
+### Spotify Integration
+
+The optional Spotify integration uses the OAuth 2.0 Authorization Code flow:
+
+- Access tokens are stored in `localStorage` for persistence between sessions
+- The OAuth `state` parameter uses a cryptographically random value (via `crypto.getRandomValues`) to prevent CSRF attacks
+- No client secrets are stored in the codebase - the Spotify client ID is provided by the user
+
+### Content Security
+
+- The application uses WebGL/WebGPU for rendering, which is sandboxed by the browser
+- No user-provided content is rendered as HTML without sanitization
+- URL parameters are validated and parsed through a typed configuration system
+
+## Dependencies
+
+This project uses the following dependencies:
+
+| Dependency | Purpose | Location | GitHub | Activity |
+|---|---|---|---|---|
+| **REGL** | WebGL wrapper for rendering | Bundled locally in `/lib/` | [regl-project/regl](https://github.com/regl-project/regl) | Mature, widely used WebGL wrapper. Core feature development has largely stabilized, but it remains production-ready and receives occasional maintenance updates. |
+| **gl-matrix** | High-performance matrix and vector math | Bundled locally in `/lib/` | [toji/gl-matrix](https://github.com/toji/gl-matrix) | Actively maintained and widely adopted for WebGL/WebGPU math. Receives regular releases. The bundled version tracks a stable 3.x release of the library. |
+| **@playwright/test** | End-to-end browser testing (dev only) | npm `devDependency` — **not included in production builds** | [microsoft/playwright](https://github.com/microsoft/playwright) | Very actively maintained by Microsoft with frequent releases and an extensive user base. This project pins a recent stable major version in its devDependencies. |
+
+Dependencies are automatically monitored by [Dependabot](.github/dependabot.yml) for security updates.

js/spotify.js

@@ -39,6 +39,18 @@ export default class SpotifyIntegration {
 		// Check if we're returning from OAuth redirect
 		await this.handleOAuthCallback();
 	}
+	/**
+	 * Generate a cryptographically random state value for OAuth CSRF protection
+	 */
+	generateState() {
+		if (!window.crypto || !window.crypto.getRandomValues) {
+			throw new Error("Secure random generation not available - Spotify authentication requires a secure context (HTTPS or http://localhost)");
+		}
+		const array = new Uint8Array(16);
+		crypto.getRandomValues(array);
+		return Array.from(array, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	}
+
 	/**
 	 * Start the OAuth authentication flow
 	 */
@@ -48,12 +60,22 @@ export default class SpotifyIntegration {
 			return;
 		}
 
+		// Generate and store a random state value to prevent CSRF attacks
+		let state;
+		try {
+			state = this.generateState();
+		} catch (e) {
+			this.emit("error", e.message);
+			return;
+		}
+		sessionStorage.setItem("spotify_oauth_state", state);
+
 		const authUrl = new URL("https://accounts.spotify.com/authorize");
 		authUrl.searchParams.set("client_id", this.clientId);
 		authUrl.searchParams.set("response_type", "code");
 		authUrl.searchParams.set("redirect_uri", this.redirectUri);
 		authUrl.searchParams.set("scope", this.scopes);
-		authUrl.searchParams.set("state", "matrix-spotify-auth");
+		authUrl.searchParams.set("state", state);
 
 		// Use direct redirect instead of popup for better compatibility
 		window.location.href = authUrl.toString();
@@ -76,19 +98,33 @@ export default class SpotifyIntegration {
 			return;
 		}
 
-		if (code && state === "matrix-spotify-auth") {
+		if (code && state) {
+			// Clean up URL immediately to remove auth parameters from browser history
+			window.history.replaceState({}, document.title, window.location.pathname);
+
+			// Verify state parameter to prevent CSRF attacks
+			const expectedState = sessionStorage.getItem("spotify_oauth_state");
+			sessionStorage.removeItem("spotify_oauth_state");
+
+			if (!expectedState || state !== expectedState) {
+				this.emit("error", "Spotify OAuth state mismatch - possible CSRF attack");
+				return;
+			}
+
 			console.log("Processing Spotify OAuth callback with code:", code.substring(0, 20) + "...");
 			const result = await this.exchangeCodeForTokens(code);
 
-			// Clean up URL
-			window.history.replaceState({}, document.title, window.location.pathname);
-
 			if (result.error) {
 				console.error("Token exchange error:", result.error);
 				this.emit("error", "Failed to exchange code for tokens: " + result.error);
 			} else {
 				console.log("Spotify authentication successful");
 			}
+		} else if (code) {
+			// Code present but state is missing — reject and clean up to avoid auth code leaking in URL
+			window.history.replaceState({}, document.title, window.location.pathname);
+			sessionStorage.removeItem("spotify_oauth_state");
+			this.emit("error", "Spotify OAuth state parameter missing - possible CSRF attack");
 		}
 	}
 	/**

package.json

@@ -1,5 +1,5 @@
 {
   "devDependencies": {
-    "@playwright/test": "^1.56.1"
+    "@playwright/test": "^1.58.2"
   }
 }