Merge pull request #14 from mnaimfaizy/security/dependency-supply-chain-hardening

chore: harden dependency supply chain

Author: mnaimfaizy

.github/CODEOWNERS

@@ -0,0 +1,13 @@
+# Default owner
+
+* @mnaimfaizy
+
+# Security-sensitive files and directories
+
+/.github/workflows/ @mnaimfaizy
+/.github/instructions/ @mnaimfaizy
+/package.json @mnaimfaizy
+/package-lock.json @mnaimfaizy
+/.npmrc @mnaimfaizy
+/SECURITY.md @mnaimfaizy
+/docs/SECURITY/ @mnaimfaizy

.github/copilot-instructions.md

@@ -15,6 +15,22 @@
 - **Build**: `npm run build` (TypeScript + Vite)
 - **Test**: `npm test` (watch mode) or `npm run test:run` (CI mode)
 
+## 🔐 Dependency and CI Security
+
+See `docs/SECURITY/Dependency-Supply-Chain-Security-Plan.md` for the current repository policy and remediation plan.
+
+- Treat all changes to `package.json`, `package-lock.json`, `.npmrc`, and `.github/workflows/**` as security-sensitive.
+- This repository is npm-only. Do not switch to Yarn or pnpm unless the repo is explicitly migrated and the security policy is updated.
+- Prefer existing platform APIs or already-approved packages before adding a new dependency.
+- Use exact versions for direct npm dependencies. Avoid `^` and `~`, and keep `.npmrc` configured with `save-exact=true`.
+- For existing lockfiles, use `npm ci`. For disposable review flows that only need metadata and audit signals, prefer `npm ci --ignore-scripts` first.
+- In CI, use only `npm ci` and verify that `package-lock.json` stays unchanged after install.
+- Review lockfile diffs for unexpected transitive packages and any new install-time script behavior before accepting dependency updates.
+- Keep `package-lock.json` committed and frozen in CI.
+- Do not recommend a blanket `ignore-scripts=true` change for normal local installs in this repo without a migration plan because the current toolchain depends on reviewed install-script packages such as `esbuild` and `@tailwindcss/oxide`.
+- Preserve the `package.json` overrides that block compromised Axios releases `1.14.1` and `0.30.4`.
+- For GitHub Actions, pin third-party actions to full commit SHAs, set explicit minimal `permissions`, and prefer OIDC over long-lived secrets whenever external systems are involved.
+
 ### **10 Learning Modules**
 
 1. JavaScript Engine - V8 internals and execution flow
@@ -549,14 +565,14 @@ analyticsService.trackEvent('feature_used', { feature: 'visualization' });
 import { env } from './core/config/env';
 
 // Available environment variables
-env.enableAnalytics      // boolean
-env.googleAnalyticsId    // string | undefined
-env.isDevelopment        // boolean
-env.isProduction         // boolean
+env.enableAnalytics; // boolean
+env.googleAnalyticsId; // string | undefined
+env.isDevelopment; // boolean
+env.isProduction; // boolean
 
 // Access in components
-import.meta.env.DEV      // Vite development mode
-import.meta.env.PROD     // Vite production mode
+import.meta.env.DEV; // Vite development mode
+import.meta.env.PROD; // Vite production mode
 ```
 
 ## 📚 Module-Specific Guidelines
@@ -638,6 +654,7 @@ The application includes these complete learning modules:
 ### **ESLint Configuration**
 
 The project uses:
+
 - `@typescript-eslint` for TypeScript-specific rules
 - `eslint-plugin-react` and `eslint-plugin-react-hooks` for React best practices
 - `eslint-plugin-import` for import organization
@@ -789,13 +806,15 @@ describe('useMyHook', () => {
 ```
 
 **Test File Organization:**
+
 - **Unit Tests**: Test utility functions and hooks
 - **Component Tests**: Verify rendering and interactions
 - **Integration Tests**: Test feature workflows
 - Place test files next to the code they test: `Component.test.tsx`
 - Use `src/test/` for shared test utilities and setup
 
 **Existing Test Examples:**
+
 - `src/shared/hooks/useDebounce.test.ts`
 - `src/shared/hooks/useThrottle.test.ts`
 - `src/shared/components/feedback/ErrorBoundary/ErrorBoundary.test.tsx`
@@ -808,12 +827,14 @@ describe('useMyHook', () => {
 Complete step-by-step guide:
 
 1. **Create Feature Directory Structure**:
+
 ```bash
 mkdir -p src/features/[module]/components/{sections,visualizations/2d}
 touch src/features/[module]/index.tsx
 ```
 
 2. **Add Type Definitions** (if needed):
+
 ```typescript
 // src/types/[module].ts
 export interface ModuleState {
@@ -822,6 +843,7 @@ export interface ModuleState {
 ```
 
 3. **Add Theme Colors**:
+
 ```typescript
 // src/utils/theme.ts - Add to colors object
 [module]: {
@@ -835,6 +857,7 @@ export interface ModuleState {
 ```
 
 4. **Create Main Page Component**:
+
 ```typescript
 // src/features/[module]/index.tsx
 import React from 'react';
@@ -854,6 +877,7 @@ export default ModulePage;
 ```
 
 5. **Add Lazy Route in App.tsx**:
+
 ```typescript
 // Import
 const NewModulePage = lazy(() => import('./features/newmodule'));
@@ -875,6 +899,7 @@ const NewModulePage = lazy(() => import('./features/newmodule'));
 ### **Creating Interactive Visualizations**
 
 1. **Start with SVG Structure**:
+
 ```typescript
 const MyViz: React.FC = () => {
   return (
@@ -888,23 +913,26 @@ const MyViz: React.FC = () => {
 ```
 
 2. **Add State Management**:
+
 ```typescript
 const [step, setStep] = useState(0);
 const [isPlaying, setIsPlaying] = useState(false);
 ```
 
 3. **Implement Animation Logic**:
+
 ```typescript
 useEffect(() => {
   if (!isPlaying) return;
   const interval = setInterval(() => {
-    setStep(prev => (prev + 1) % totalSteps);
+    setStep((prev) => (prev + 1) % totalSteps);
   }, 1000);
   return () => clearInterval(interval);
 }, [isPlaying]);
 ```
 
 4. **Add Demo Controls**:
+
 ```typescript
 <div className="flex gap-2 mt-4">
   <button onClick={() => setIsPlaying(!isPlaying)}>
@@ -915,6 +943,7 @@ useEffect(() => {
 ```
 
 5. **Include Educational Tooltips**:
+
 ```typescript
 <title>Explanation of what this element represents</title>
 ```

.github/dependabot.yml

@@ -0,0 +1,42 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: daily
+      time: '06:00'
+      timezone: UTC
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - security
+    commit-message:
+      prefix: deps
+    allow:
+      - dependency-type: direct
+      - dependency-type: indirect
+    groups:
+      npm-production:
+        dependency-type: production
+        update-types:
+          - minor
+          - patch
+      npm-development:
+        dependency-type: development
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      time: '06:30'
+      timezone: UTC
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - security
+      - github-actions
+    commit-message:
+      prefix: ci

.github/instructions/dependency-security.instructions.md

@@ -0,0 +1,30 @@
+---
+description: 'Use when changing npm dependencies, package-lock.json, .npmrc, or GitHub Actions workflows. Covers supply-chain security review, exact version pinning, install-script review, dependency incident response, and CI hardening for compromised packages such as Axios.'
+name: 'Dependency and Workflow Security'
+applyTo:
+  - package.json
+  - package-lock.json
+  - .npmrc
+  - .github/workflows/**
+  - .github/dependabot.yml
+  - docs/SECURITY/**
+---
+
+# Dependency and Workflow Security
+
+- Treat any dependency, lockfile, registry, or workflow change as security-sensitive.
+- This repository is npm-only. Do not introduce Yarn or pnpm for this repo unless the package manager migration is explicitly approved and the security policy is updated.
+- Prefer an existing dependency or a platform-native API before introducing a new package.
+- For this application repository, use exact versions for direct dependencies. Avoid `^` and `~` in `package.json`, and keep `.npmrc` configured with `save-exact=true`.
+- For existing lockfiles, use `npm ci`. For dependency review in disposable environments or dedicated CI security checks, prefer `npm ci --ignore-scripts` first.
+- Do not use `npm install`, `npm update`, or `npm audit fix` in CI. CI must use `npm ci` only and fail if `package-lock.json` changes.
+- If Yarn or pnpm are ever introduced elsewhere, require their immutable or frozen lockfile mode and disable lifecycle scripts unless an explicit allowlist process is in place.
+- Before adding or updating a package, check the current advisories, the latest patched version, maintainer health, recent publish activity, and whether the package adds install-time scripts, native binaries, or unusually large transitive churn.
+- Review `package-lock.json` diffs for unexpected new packages, registry changes, or install-time script packages.
+- Popularity is not a trust signal. Treat high-usage packages such as Axios as high-impact dependencies that still require full review.
+- Do not enable a blanket `ignore-scripts=true` policy for normal local installs in this repo without a migration plan because the current toolchain depends on reviewed install-script packages such as `esbuild` and `@tailwindcss/oxide`.
+- Keep `package-lock.json` committed. Prefer `npm ci` in CI and reproducible installs over ad hoc `npm install` in automation.
+- Keep Axios guardrails in `package.json` overrides so the compromised releases `1.14.1` and `0.30.4` cannot be selected if Axios is introduced directly or transitively.
+- When editing GitHub Actions workflows, pin third-party actions to full commit SHAs, set explicit minimal `permissions`, and prefer OIDC over long-lived secrets.
+- Require human review for workflow files, dependency manifests, and lockfiles.
+- If a package compromise is reported, immediately identify direct and transitive usage, block the affected versions, clear caches, rotate potentially exposed secrets, and record the outcome in `docs/SECURITY/Dependency-Supply-Chain-Security-Plan.md`.