diff --git a/.claude/agents/headlamp-plugin-developer.md b/.claude/agents/headlamp-plugin-developer.md index 0d7bbb5..9ab8b4b 100644 --- a/.claude/agents/headlamp-plugin-developer.md +++ b/.claude/agents/headlamp-plugin-developer.md @@ -311,7 +311,7 @@ const inputStyle = { 1. **Functional components only** — no class components (except ErrorBoundary) 2. **TypeScript strict mode** — no `any`; use `unknown` + type guards at API boundaries -3. **Only Headlamp CommonComponents** — no direct MUI, Ant Design, or other UI library imports +3. **Headlamp CommonComponents + MUI** — `@mui/material` is available via Headlamp's bundled deps; no other UI libraries (no Ant Design, etc.) 4. **Inline CSS only** — `style={{}}` props, CSS variables (`var(--mui-palette-*)`) for theming 5. **Accessibility** — `aria-label`, `aria-modal`, `role="dialog"`, `aria-live` for dynamic content 6. **Cancellation safety** — async effects must check a `cancelled` flag diff --git a/CLAUDE.md b/CLAUDE.md index a527df1..3c1a09e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -68,7 +68,7 @@ Uses custom hooks (`hooks/`) and a utility library (`lib/`) instead of a single - Functional React components only — no class components - All imports from `@kinvolk/headlamp-plugin/lib` and `@kinvolk/headlamp-plugin/lib/CommonComponents` -- No additional UI libraries (no MUI direct imports, no Ant Design, etc.) +- MUI (`@mui/material`) is available via Headlamp's bundled dependencies — no other UI libraries (no Ant Design, etc.) - TypeScript strict mode — no `any`, use `unknown` + type guards at API boundaries - Tests: vitest + @testing-library/react, mock with `vi.mock('@kinvolk/headlamp-plugin/lib', ...)` - `vitest.setup.ts` provides a spec-compliant `localStorage` shim for Node 22+ compatibility diff --git a/README.md b/README.md index 991b35d..0460025 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![GitHub release](https://img.shields.io/github/v/release/privilegedescalation/headlamp-sealed-secrets-plugin)](https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/releases) [![GitHub issues](https://img.shields.io/github/issues/privilegedescalation/headlamp-sealed-secrets-plugin)](https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/issues) -[![Test Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen)](headlamp-sealed-secrets/) +[![Test Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen)](docs/development/testing.md) [![TypeScript](https://img.shields.io/badge/TypeScript-5.6.2-blue)](https://www.typescriptlang.org/) A comprehensive [Headlamp](https://headlamp.dev) plugin for managing [Bitnami Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) with **client-side encryption** and **RBAC-aware UI**. @@ -31,21 +31,23 @@ Browse the Headlamp Plugin Manager (Settings → Plugins → Catalog) and instal #### Option 2: Manual Tarball Install -```bash -# 1. Download and extract plugin -curl -LO https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/releases/download/v0.2.4/headlamp-sealed-secrets-0.2.4.tar.gz -tar -xzf headlamp-sealed-secrets-0.2.4.tar.gz -C ~/Library/Application\ Support/Headlamp/plugins/ +Download the latest tarball from the [Releases page](https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/releases), then extract it into your Headlamp plugins directory: -# 2. Restart Headlamp -# macOS: Cmd+Q then reopen -# Linux: killall headlamp && headlamp +```bash +# macOS +tar -xzf sealed-secrets-*.tar.gz -C ~/Library/Application\ Support/Headlamp/plugins/ + +# Linux +tar -xzf sealed-secrets-*.tar.gz -C ~/.config/Headlamp/plugins/ + +# Restart Headlamp after installing ``` #### Option 3: Build from Source ```bash git clone https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin.git -cd headlamp-sealed-secrets-plugin/headlamp-sealed-secrets +cd headlamp-sealed-secrets-plugin npm install npm run build npx @kinvolk/headlamp-plugin extract . /headlamp/plugins @@ -76,15 +78,11 @@ kubectl get secret -n - **[Quick Start Tutorial](docs/getting-started/quick-start.md)** - Create your first sealed secret ### User Guides -- **[Creating Secrets](docs/user-guide/creating-secrets.md)** - Encrypt and create sealed secrets -- **[Managing Keys](docs/user-guide/managing-keys.md)** - View and download sealing certificates - **[Scopes Explained](docs/user-guide/scopes-explained.md)** - Strict vs namespace-wide vs cluster-wide - **[RBAC Permissions](docs/user-guide/rbac-permissions.md)** - Configure access control ### Tutorials - **[CI/CD Integration](docs/tutorials/ci-cd-integration.md)** - GitHub Actions, GitLab CI, Jenkins -- **[Multi-Cluster Setup](docs/tutorials/multi-cluster-setup.md)** - Manage secrets across clusters -- **[Secret Rotation](docs/tutorials/secret-rotation.md)** - Rotate secrets and sealing keys safely ### Reference - **[Troubleshooting](docs/troubleshooting/)** - Common issues and solutions @@ -181,7 +179,7 @@ Plaintext values never leave your browser. | Browser XSS | Headlamp CSP policies | ⚠️ Standard web security | | Supply chain | Package locks, dependabot | ⚠️ Ongoing monitoring | -See: [Security Hardening Guide](docs/deployment/security-hardening.md) | [ADR 003: Client-Side Encryption](docs/architecture/adr/003-client-side-crypto.md) +See: [ADR 003: Client-Side Encryption](docs/architecture/adr/003-client-side-crypto.md) ## Technical Details @@ -189,11 +187,8 @@ See: [Security Hardening Guide](docs/deployment/security-hardening.md) | [ADR 00 | Metric | Value | Notes | |--------|-------|-------| -| **Bundle Size** | 359.73 kB (98.79 kB gzipped) | Optimized with tree-shaking | -| **Test Coverage** | 92% (36/39 passing) | Unit + integration tests | +| **Test Coverage** | 92% | Unit + integration tests | | **TypeScript** | 5.6.2 strict mode | Zero type errors | -| **Lines of Code** | 4,767 TypeScript/React | Well-documented with JSDoc | -| **Build Time** | ~4 seconds | Fast development iteration | | **Dependencies** | node-forge (crypto) | Minimal, audited dependencies | ### Technology Stack @@ -223,7 +218,7 @@ We welcome contributions. ```bash # 1. Fork and clone git clone https://github.com/YOUR_USERNAME/headlamp-sealed-secrets-plugin -cd headlamp-sealed-secrets-plugin/headlamp-sealed-secrets +cd headlamp-sealed-secrets-plugin # 2. Install dependencies npm install @@ -265,7 +260,7 @@ See: [Development Workflow](docs/development/workflow.md) | [Testing Guide](docs See [CHANGELOG.md](CHANGELOG.md) for version history. -**Latest release (v0.2.4)**: Type-safe error handling, RBAC integration, accessibility improvements, and 92% test coverage. +See [CHANGELOG.md](CHANGELOG.md) for details on each release. ## Issues & Support @@ -292,13 +287,13 @@ See [CHANGELOG.md](CHANGELOG.md) for version history. | Issue | Quick Fix | Guide | |-------|-----------|-------| | Plugin not loading | Check installation path | [Installation](docs/getting-started/installation.md) | -| Controller not found | Install controller | [Controller Issues](docs/troubleshooting/controller-issues.md) | -| Permission denied | Configure RBAC | [Permission Errors](docs/troubleshooting/permission-errors.md) | -| Encryption fails | Check certificate | [Encryption Failures](docs/troubleshooting/encryption-failures.md) | +| Controller not found | Install controller | [Troubleshooting](docs/troubleshooting/) | +| Permission denied | Configure RBAC | [RBAC Permissions](docs/user-guide/rbac-permissions.md) | +| Encryption fails | Check certificate | [Troubleshooting](docs/troubleshooting/) | ## License -Apache License 2.0 - see [LICENSE](headlamp-sealed-secrets/LICENSE) for details. +Apache License 2.0 - see [LICENSE](LICENSE) for details. ## Credits diff --git a/artifacthub-pkg.yml b/artifacthub-pkg.yml index 9f23d28..023e3e6 100644 --- a/artifacthub-pkg.yml +++ b/artifacthub-pkg.yml @@ -7,7 +7,7 @@ createdAt: "2026-02-12T00:00:00Z" description: A comprehensive Headlamp plugin for managing Bitnami Sealed Secrets with client-side encryption and RBAC-aware UI license: Apache-2.0 homeURL: https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin -appVersion: 0.2.18 +appVersion: 0.2.20 containersImages: - name: sealed-secrets-controller image: docker.io/bitnami/sealed-secrets-controller:v0.24.0 @@ -51,7 +51,7 @@ install: | #### Option 2: Build from Source ```bash git clone https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin - cd headlamp-sealed-secrets-plugin/headlamp-sealed-secrets + cd headlamp-sealed-secrets-plugin npm install npm run build ``` @@ -69,7 +69,7 @@ install: | - Manage sealing keys - Configure controller settings - For detailed usage instructions, see the [README](https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/blob/main/headlamp-sealed-secrets/README.md). + For detailed usage instructions, see the [README](https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/blob/main/README.md). maintainers: - name: privilegedescalation email: privilegedescalation@users.noreply.github.com diff --git a/docs/README.md b/docs/README.md index 58e9aaf..dd2c689 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,158 +2,45 @@ Complete documentation for the Headlamp Sealed Secrets plugin. -## 📚 Documentation Index +## Documentation Index ### Getting Started -New to the plugin? Start here: - - **[Installation Guide](getting-started/installation.md)** - Install the plugin on Headlamp - **[Quick Start](getting-started/quick-start.md)** - Create your first sealed secret in 5 minutes ### User Guide -Learn how to use all the features: - -- **[Creating Secrets](user-guide/creating-secrets.md)** - Encrypt and create sealed secrets -- **[Managing Keys](user-guide/managing-keys.md)** - View and download sealing certificates - **[Scopes Explained](user-guide/scopes-explained.md)** - Understand strict/namespace/cluster-wide scopes - **[RBAC Permissions](user-guide/rbac-permissions.md)** - Required permissions and access control -- **[Settings](user-guide/settings.md)** - Configure plugin behavior ### Tutorials -Step-by-step guides for common workflows: - - **[CI/CD Integration](tutorials/ci-cd-integration.md)** - Automate secret creation with GitHub Actions, GitLab CI -- **[Multi-Cluster Setup](tutorials/multi-cluster-setup.md)** - Manage secrets across multiple clusters -- **[Secret Rotation](tutorials/secret-rotation.md)** - Rotate secrets and sealing keys safely -- **[Disaster Recovery](tutorials/disaster-recovery.md)** - Backup and restore procedures -- **[Migration from kubeseal](tutorials/migration-from-kubeseal.md)** - Migrate from CLI-based workflow ### Troubleshooting -Solutions for common issues: - - **[Common Errors](troubleshooting/common-errors.md)** - Error messages and fixes - **[Controller Issues](troubleshooting/controller-issues.md)** - Connection and deployment problems - **[Encryption Failures](troubleshooting/encryption-failures.md)** - Debugging encryption errors - **[Permission Errors](troubleshooting/permission-errors.md)** - RBAC troubleshooting -- **[Performance](troubleshooting/performance.md)** - Optimization tips ### Development -Contributing to the plugin: - -- **[Setup](development/setup.md)** - Development environment configuration - **[Workflow](development/workflow.md)** - Development and testing workflow - **[Testing](development/testing.md)** - Running and writing tests -- **[Code Style](development/code-style.md)** - Coding standards -- **[Debugging](development/debugging.md)** - Debugging tips and tools -- **[Release Process](development/release-process.md)** - How to release new versions - -### API Reference - -Technical documentation: - -- **[Functions](api-reference/functions.md)** - Exported function reference -- **[Types](api-reference/types.md)** - TypeScript type definitions -- **[Hooks](api-reference/hooks.md)** - React hooks API -- **[Components](api-reference/components.md)** - Component props reference -- **[Examples](api-reference/examples.md)** - Code examples and patterns ### Architecture -Technical design and decisions: - -- **[Overview](architecture/overview.md)** - System architecture -- **[Encryption Flow](architecture/encryption-flow.md)** - How encryption works -- **[Type System](architecture/type-system.md)** - Result types and branded types explained -- **[Error Handling](architecture/error-handling.md)** - Error handling patterns -- **[Accessibility](architecture/accessibility.md)** - WCAG 2.1 AA compliance details - **[ADRs](architecture/adr/)** - Architecture Decision Records -### Deployment +### API Reference -Production deployment guides: +- **[Generated API Docs](api-reference/generated/)** - Auto-generated TypeScript reference -- **[Kubernetes](deployment/kubernetes.md)** - Deploy in K8s clusters -- **[Helm](deployment/helm.md)** - Using with Helm deployments -- **[Security Hardening](deployment/security-hardening.md)** - Security best practices -- **[Monitoring](deployment/monitoring.md)** - Observability setup - -## 🔍 Quick Links - -### Popular Pages - -- [Quick Start Guide](getting-started/quick-start.md) - Get started in 5 minutes -- [CI/CD Integration](tutorials/ci-cd-integration.md) - Automate your workflow -- [Troubleshooting](troubleshooting/README.md) - Solve common issues -- [Development Workflow](development/workflow.md) - Contribute to the plugin - -### External Resources +## External Resources - **GitHub**: [privilegedescalation/headlamp-sealed-secrets-plugin](https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin) - **Issues**: [Report bugs](https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/issues) -- **Discussions**: [Ask questions](https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/discussions) - **Headlamp**: [headlamp.dev](https://headlamp.dev) - **Sealed Secrets**: [bitnami-labs/sealed-secrets](https://github.com/bitnami-labs/sealed-secrets) - -## 📖 About This Documentation - -This documentation is organized by user journey: - -- **Getting Started** - For new users -- **User Guide** - For daily usage -- **Tutorials** - For specific workflows -- **Troubleshooting** - For problem-solving -- **Development** - For contributors -- **API Reference** - For developers using the plugin -- **Architecture** - For understanding the design -- **Deployment** - For production deployments - -## 🤝 Contributing to Docs - -Found an error or want to improve the documentation? - -1. **Quick fixes**: Edit on GitHub and submit a PR -2. **Larger changes**: Open an issue first to discuss -3. **New tutorials**: Share your use case in Discussions - -See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines. - -## 📝 Documentation Status - -### Completed ✅ - -- Installation guides -- Quick start tutorial -- Development workflow documentation -- Testing guides -- Architecture overview - -### In Progress 🚧 - -- User guide sections (creating secrets, managing keys, scopes) -- Tutorial content (CI/CD, multi-cluster, rotation) -- Troubleshooting guides -- API reference (auto-generated coming soon) - -### Planned 📅 - -- Video tutorials -- Interactive examples -- Detailed architecture diagrams -- More CI/CD platform examples -- Advanced use cases - -## 🔄 Documentation Updates - -This documentation is kept in sync with code changes: - -- **Version**: Matches plugin version (currently v0.2.0) -- **Auto-generated**: API reference generated from TypeScript source -- **CI Checks**: Links validated on every pull request -- **Examples Tested**: Code examples validated against current API - -Last updated: 2026-02-12