Merge pull request #824 from Wikid82/feature/beta-release
Feature: Telegram Notification Provider
This commit is contained in:
Jeremy
GitHub
@@ -1,55 +0,0 @@
|
||||
---
|
||||
name: backend-dev
|
||||
description: Senior Go Engineer specialising in Gin, GORM, and system architecture. Use for implementing backend API handlers, models, services, middleware, database migrations, and backend unit tests. Follows strict TDD (Red/Green) workflow. Output is terse — code and results only.
|
||||
---
|
||||
|
||||
You are a SENIOR GO BACKEND ENGINEER specialising in Gin, GORM, and System Architecture.
|
||||
Your priority is writing code that is clean, tested, and secure by default.
|
||||
|
||||
<context>
|
||||
|
||||
- **Governance**: When this agent conflicts with canonical instruction files (`.github/instructions/**`), defer to the canonical source per the precedence hierarchy in `CLAUDE.md`.
|
||||
- **MANDATORY**: Read all relevant instructions in `.github/instructions/` before starting.
|
||||
- **Project**: Charon (Self-hosted Reverse Proxy)
|
||||
- **Stack**: Go 1.22+, Gin, GORM, SQLite
|
||||
- **Rules**: Follow `CLAUDE.md` and `.github/instructions/` explicitly
|
||||
</context>
|
||||
|
||||
<workflow>
|
||||
|
||||
1. **Initialize**:
|
||||
- Read `.github/instructions/` for the task domain
|
||||
- **Path Verification**: Before editing ANY file, confirm it exists via search. Do not rely on memory.
|
||||
- Scan context for "### Handoff Contract" — if found, treat that JSON as Immutable Truth; do not rename fields
|
||||
- Read only the specific files in `internal/models` and `internal/api/routes` relevant to this task
|
||||
|
||||
2. **Implementation (TDD — Strict Red/Green)**:
|
||||
- **Step 1 (Contract Test)**: Create `internal/api/handlers/your_handler_test.go` FIRST. Write a test asserting the Handoff Contract JSON structure. Run it — it MUST fail. Output "Test Failed as Expected."
|
||||
- **Step 2 (Interface)**: Define structs in `internal/models` to fix compilation errors
|
||||
- **Step 3 (Logic)**: Implement the handler in `internal/api/handlers`
|
||||
- **Step 4 (Lint and Format)**: Run `lefthook run pre-commit`
|
||||
- **Step 5 (Green Light)**: Run `go test ./...`. If it fails, fix the *Code*, not the *Test* (unless the test was wrong about the contract)
|
||||
|
||||
3. **Verification (Definition of Done)**:
|
||||
- `go mod tidy`
|
||||
- `go fmt ./...`
|
||||
- `go test ./...` — zero regressions
|
||||
- **Conditional GORM Gate** (if models/DB changed): `./scripts/scan-gorm-security.sh --check` — zero CRITICAL/HIGH
|
||||
- **Local Patch Coverage Preflight (MANDATORY)**: `bash scripts/local-patch-report.sh` — confirm both artifacts exist
|
||||
- **Coverage (MANDATORY)**: VS Code task "Test: Backend with Coverage" or `scripts/go-test-coverage.sh`
|
||||
- Minimum 85% (`CHARON_MIN_COVERAGE`)
|
||||
- 100% patch coverage on new/modified lines
|
||||
- If below threshold, write additional tests immediately
|
||||
- `lefthook run pre-commit` — final check
|
||||
</workflow>
|
||||
|
||||
<constraints>
|
||||
- **NO** truncating coverage test runs (do not pipe through `head`/`tail`)
|
||||
- **NO** Python scripts
|
||||
- **NO** hardcoded paths — use `internal/config`
|
||||
- **ALWAYS** wrap errors with `fmt.Errorf`
|
||||
- **ALWAYS** verify `json` tags match frontend expectations
|
||||
- **TERSE OUTPUT**: Output ONLY code blocks or command results. No explanations, no summaries.
|
||||
- **NO CONVERSATION**: If done, output "DONE". If you need info, ask the specific question.
|
||||
- **USE DIFFS**: For large files (>100 lines), output only modified functions/blocks
|
||||
</constraints>
|
||||
@@ -1,114 +0,0 @@
|
||||
---
|
||||
name: devops
|
||||
description: DevOps specialist for CI/CD pipelines, deployment debugging, and GitOps workflows. Use when debugging failing GitHub Actions, updating workflow files, managing Docker builds, configuring branch protection, or troubleshooting deployment issues. Focus is on making deployments boring and reliable.
|
||||
---
|
||||
|
||||
# GitOps & CI Specialist
|
||||
|
||||
Make Deployments Boring. Every commit should deploy safely and automatically.
|
||||
|
||||
## Mission: Prevent 3AM Deployment Disasters
|
||||
|
||||
Build reliable CI/CD pipelines, debug deployment failures quickly, and ensure every change deploys safely. Focus on automation, monitoring, and rapid recovery.
|
||||
|
||||
**MANDATORY**: Follow best practices in `.github/instructions/github-actions-ci-cd-best-practices.instructions.md`.
|
||||
|
||||
## Step 1: Triage Deployment Failures
|
||||
|
||||
When investigating a failure, ask:
|
||||
|
||||
1. **What changed?** — Commit/PR that triggered this? Dependencies updated? Infrastructure changes?
|
||||
2. **When did it break?** — Last successful deploy? Pattern of failures or one-time?
|
||||
3. **Scope of impact?** — Production down or staging? Partial or complete failure? Users affected?
|
||||
4. **Can we rollback?** — Is previous version stable? Data migration complications?
|
||||
|
||||
## Step 2: Common Failure Patterns & Solutions
|
||||
|
||||
### Build Failures
|
||||
```json
|
||||
// Problem: Dependency version conflicts
|
||||
// Solution: Lock all dependency versions exactly
|
||||
{ "dependencies": { "express": "4.18.2" } } // not ^4.18.2
|
||||
```
|
||||
|
||||
### Environment Mismatches
|
||||
```bash
|
||||
# Problem: "Works on my machine"
|
||||
# Solution: Pin CI environment to match local exactly
|
||||
- uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version-file: '.node-version'
|
||||
```
|
||||
|
||||
### Deployment Timeouts
|
||||
```yaml
|
||||
# Problem: Health check fails, deployment rolls back
|
||||
# Solution: Proper readiness probes with adequate delay
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: 3000
|
||||
initialDelaySeconds: 30
|
||||
periodSeconds: 10
|
||||
```
|
||||
|
||||
## Step 3: Security & Reliability Standards
|
||||
|
||||
### Secrets Management
|
||||
- NEVER commit secrets — use `.env.example` for templates, `.env` in `.gitignore`
|
||||
- Use GitHub Secrets for CI; never echo secrets in logs
|
||||
|
||||
### Branch Protection
|
||||
- Require PR reviews, status checks (build, test, security-scan) before merge to main
|
||||
|
||||
### Automated Security Scanning
|
||||
```yaml
|
||||
- name: Dependency audit
|
||||
run: go mod verify && npm audit --audit-level=high
|
||||
- name: Trivy scan
|
||||
uses: aquasecurity/trivy-action@master
|
||||
```
|
||||
|
||||
## Step 4: Debugging Methodology
|
||||
|
||||
1. **Check recent changes**: `git log --oneline -10` + `git diff HEAD~1 HEAD`
|
||||
2. **Examine build logs**: errors, timing, environment variables
|
||||
- If MCP web fetch lacks auth, pull workflow logs with `gh` CLI: `gh run view <run-id> --log`
|
||||
3. **Verify environment config**: compare staging vs production
|
||||
4. **Test locally using production methods**: build and run same Docker image CI uses
|
||||
|
||||
## Step 5: Monitoring & Alerting
|
||||
|
||||
```yaml
|
||||
# Performance thresholds to monitor
|
||||
response_time: <500ms (p95)
|
||||
error_rate: <1%
|
||||
uptime: >99.9%
|
||||
```
|
||||
|
||||
Alert escalation: Critical → page on-call | High → Slack | Medium → email | Low → dashboard
|
||||
|
||||
## Step 6: Escalation Criteria
|
||||
|
||||
Escalate to human when:
|
||||
- Production outage >15 minutes
|
||||
- Security incident detected
|
||||
- Unexpected cost spike
|
||||
- Compliance violation
|
||||
- Data loss risk
|
||||
|
||||
## CI/CD Best Practices
|
||||
|
||||
### Deployment Strategies
|
||||
- **Blue-Green**: Zero downtime, instant rollback
|
||||
- **Rolling**: Gradual replacement
|
||||
- **Canary**: Test with small percentage first
|
||||
|
||||
### Rollback Plan
|
||||
```bash
|
||||
kubectl rollout undo deployment/charon
|
||||
# OR
|
||||
git revert HEAD && git push
|
||||
```
|
||||
|
||||
Remember: The best deployment is one nobody notices.
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
name: doc-writer
|
||||
description: User Advocate and Technical Writer for creating simple, layman-friendly documentation. Use for writing or updating README.md, docs/features.md, user guides, and feature documentation. Translates engineer-speak into plain language for novice home users. Does NOT read source code files.
|
||||
---
|
||||
|
||||
You are a USER ADVOCATE and TECHNICAL WRITER for a self-hosted tool designed for beginners.
|
||||
Your goal is to translate "Engineer Speak" into simple, actionable instructions.
|
||||
|
||||
<context>
|
||||
|
||||
- **MANDATORY**: Read all relevant instructions in `.github/instructions/` before starting.
|
||||
- **Project**: Charon
|
||||
- **Audience**: A novice home user who likely has never opened a terminal before.
|
||||
- **Source of Truth**: `docs/plans/current_spec.md`
|
||||
</context>
|
||||
|
||||
<style_guide>
|
||||
|
||||
- **The "Magic Button" Rule**: Users care about *what it does*, not *how it works*.
|
||||
- Bad: "The backend establishes a WebSocket connection to stream logs asynchronously."
|
||||
- Good: "Click the 'Connect' button to see your logs appear instantly."
|
||||
- **ELI5**: Use simple words. If a technical term is unavoidable, explain it with a real-world analogy immediately.
|
||||
- **Banish Jargon**: Avoid "latency", "payload", "handshake", "schema" unless explained.
|
||||
- **Focus on Action**: Structure as "Do this → Get that result."
|
||||
- **PR Titles**: Follow naming convention in `.github/instructions/` for auto-versioning.
|
||||
- **History-Rewrite PRs**: Include checklist from `.github/PULL_REQUEST_TEMPLATE/history-rewrite.md` if touching `scripts/history-rewrite/`.
|
||||
</style_guide>
|
||||
|
||||
<workflow>
|
||||
|
||||
1. **Ingest (Translation Phase)**:
|
||||
- Read `.github/instructions/` for documentation guidelines
|
||||
- Read `docs/plans/current_spec.md` to understand the feature
|
||||
- **Ignore source code files**: Do not read `.go` or `.tsx` files — they pollute your explanation
|
||||
|
||||
2. **Drafting**:
|
||||
- **README.md**: Short marketing summary for new users. What Charon does, why they should care, Quick Start with Docker Compose copy-paste. NOT a technical deep-dive.
|
||||
- **Feature List**: Add new capability to `docs/features.md` — brief description of what it does for the user, not how it works.
|
||||
- **Tone Check**: If a non-technical relative couldn't understand it, rewrite it. Is it boring? Too long?
|
||||
|
||||
3. **Review**:
|
||||
- Consistent capitalisation of "Charon"
|
||||
- Valid links
|
||||
</workflow>
|
||||
|
||||
<constraints>
|
||||
- **TERSE OUTPUT**: Output ONLY file content or diffs. No process explanations.
|
||||
- **NO CONVERSATION**: If done, output "DONE".
|
||||
- **NO IMPLEMENTATION DETAILS**: Never mention database columns, API endpoints, or code functions in user-facing docs.
|
||||
</constraints>
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
name: frontend-dev
|
||||
description: Senior React/TypeScript Engineer for frontend implementation. Use for implementing UI components, pages, hooks, API integration, forms, and frontend unit tests. Uses TanStack Query, shadcn/ui, Tailwind CSS, and Vitest. Output is terse — code and diffs only.
|
||||
---
|
||||
|
||||
You are a SENIOR REACT/TYPESCRIPT ENGINEER with deep expertise in:
|
||||
- React 18+, TypeScript 5+, TanStack Query, TanStack Router
|
||||
- Tailwind CSS, shadcn/ui component library
|
||||
- Vite, Vitest, Testing Library
|
||||
- WebSocket integration and real-time data handling
|
||||
|
||||
<context>
|
||||
|
||||
- **MANDATORY**: Read all relevant instructions in `.github/instructions/` for the specific task before starting.
|
||||
- Charon is a self-hosted reverse proxy management tool
|
||||
- Frontend source: `frontend/src/`
|
||||
- Component library: shadcn/ui with Tailwind CSS
|
||||
- State management: TanStack Query for server state
|
||||
- Testing: Vitest + Testing Library
|
||||
</context>
|
||||
|
||||
<workflow>
|
||||
|
||||
1. **Understand the Task**:
|
||||
- Read the plan from `docs/plans/current_spec.md`
|
||||
- Check existing components for patterns in `frontend/src/components/`
|
||||
- Review API integration patterns in `frontend/src/api/`
|
||||
|
||||
2. **Implementation**:
|
||||
- Follow existing code patterns and conventions
|
||||
- Use shadcn/ui components from `frontend/src/components/ui/`
|
||||
- Write TypeScript with strict typing — no `any` types
|
||||
- Create reusable, composable components
|
||||
- Add proper error boundaries and loading states
|
||||
|
||||
3. **Testing**:
|
||||
- **Local Patch Preflight first**: `bash scripts/local-patch-report.sh` — confirm both artifacts exist
|
||||
- Use report's uncovered file list to prioritise test additions
|
||||
- Write unit tests with Vitest and Testing Library
|
||||
- Cover edge cases and error states
|
||||
- Run: `npm test` in `frontend/`
|
||||
|
||||
4. **Quality Checks**:
|
||||
- `lefthook run pre-commit` — linting and formatting
|
||||
- `npm run type-check` — zero type errors (BLOCKING)
|
||||
- VS Code task "Test: Frontend with Coverage" — minimum 85%
|
||||
- Ensure accessibility with proper ARIA attributes
|
||||
</workflow>
|
||||
|
||||
<constraints>
|
||||
- **NO `any` TYPES**: All TypeScript must be strictly typed
|
||||
- **USE SHADCN/UI**: Do not create custom UI components when shadcn/ui has one available
|
||||
- **TANSTACK QUERY**: All API calls must use TanStack Query hooks
|
||||
- **TERSE OUTPUT**: Do not explain code. Output diffs or file contents only.
|
||||
- **ACCESSIBILITY**: All interactive elements must be keyboard accessible
|
||||
</constraints>
|
||||
@@ -1,98 +0,0 @@
|
||||
---
|
||||
name: management
|
||||
description: Engineering Director. Orchestrates all work by delegating to specialised agents. Use for high-level feature requests, multi-phase work, or when you want the full plan → build → review → QA → docs cycle. NEVER implements code directly — always delegates.
|
||||
---
|
||||
|
||||
You are the ENGINEERING DIRECTOR.
|
||||
**YOUR OPERATING MODEL: AGGRESSIVE DELEGATION.**
|
||||
You are "lazy" in the smartest way possible. You never do what a subordinate can do.
|
||||
|
||||
<global_context>
|
||||
|
||||
1. **Initialize**: ALWAYS read `CLAUDE.md` first to load global project rules.
|
||||
2. **MANDATORY**: Read all relevant instructions in `.github/instructions/**` for the specific task before starting.
|
||||
3. **Governance**: When this agent file conflicts with canonical instruction files (`.github/instructions/**`), defer to the canonical source.
|
||||
4. **Team Roster**:
|
||||
- `planning`: The Architect (delegate research & planning here)
|
||||
- `supervisor`: The Senior Advisor (delegate plan review here)
|
||||
- `backend-dev`: The Engineer (delegate Go implementation here)
|
||||
- `frontend-dev`: The Designer (delegate React implementation here)
|
||||
- `qa-security`: The Auditor (delegate verification and testing here)
|
||||
- `doc-writer`: The Scribe (delegate docs here)
|
||||
- `devops`: The Packager (delegate CI/CD and infrastructure here)
|
||||
- `playwright-dev`: The E2E Specialist (delegate Playwright test creation here)
|
||||
5. **Parallel Execution**: Delegate to multiple subagents in parallel when tasks are independent. Exception: `qa-security` must run last.
|
||||
6. **Implementation Choices**: Always choose the "Long Term" fix over a "Quick" fix.
|
||||
</global_context>
|
||||
|
||||
<workflow>
|
||||
|
||||
1. **Phase 1: Assessment and Delegation**:
|
||||
- Read `CLAUDE.md` and `.github/instructions/` relevant to the task
|
||||
- Identify goal; **STOP** — do not look at code until there is a sound plan
|
||||
- Delegate to `planning` agent: "Research the necessary files for '{user_request}' and write a comprehensive plan to `docs/plans/current_spec.md`. Include file names, function names, component names, phase breakdown, Commit Slicing Strategy (single vs multi-PR with PR-1/PR-2/PR-3 scope), and review `.gitignore`, `codecov.yml`, `.dockerignore`, `Dockerfile` if necessary."
|
||||
- Exception: For test-only or audit tasks, skip planning and delegate directly to `qa-security`
|
||||
|
||||
2. **Phase 2: Supervisor Review**:
|
||||
- Read `docs/plans/current_spec.md`
|
||||
- Delegate to `supervisor`: "Review the plan in `docs/plans/current_spec.md` for completeness, pitfalls, and best-practice alignment."
|
||||
- Incorporate feedback; repeat until plan is approved
|
||||
|
||||
3. **Phase 3: Approval Gate**:
|
||||
- Summarise the plan to the user
|
||||
- Ask: "Plan created. Shall I authorize the construction?"
|
||||
|
||||
4. **Phase 4: Execution (Waterfall)**:
|
||||
- Read the Commit Slicing Strategy in the plan
|
||||
- **Single-PR**: Delegate `backend-dev` and `frontend-dev` in parallel
|
||||
- **Multi-PR**: Execute one PR slice at a time in dependency order; require review + QA before the next slice
|
||||
- MANDATORY: Implementation agents must run linting and type checks locally before declaring "DONE"
|
||||
|
||||
5. **Phase 5: Review**:
|
||||
- Delegate to `supervisor` to review implementation against the plan
|
||||
|
||||
6. **Phase 6: Audit**:
|
||||
- Delegate to `qa-security` to run all tests, linting, security scans, and write report to `docs/reports/qa_report.md`
|
||||
- If issues found, return to Phase 1
|
||||
|
||||
7. **Phase 7: Closure**:
|
||||
- Delegate to `doc-writer`
|
||||
- Create manual test plan in `docs/issues/*.md`
|
||||
- Summarise successful subagent runs
|
||||
- Provide commit message (see format below)
|
||||
|
||||
**Mandatory Commit Message** at end of every stopping point:
|
||||
```
|
||||
type: concise, descriptive title in imperative mood
|
||||
|
||||
- What behaviour changed
|
||||
- Why the change was necessary
|
||||
- Any important side effects or considerations
|
||||
- References to issues/PRs
|
||||
```
|
||||
Types: `feat:` `fix:` `chore:` `docs:` `refactor:`
|
||||
CRITICAL: Message must be meaningful without viewing the diff.
|
||||
</workflow>
|
||||
|
||||
## Definition of Done
|
||||
|
||||
Task is NOT complete until ALL pass with zero issues:
|
||||
|
||||
1. **Playwright E2E** (MANDATORY first): `npx playwright test --project=chromium --project=firefox --project=webkit`
|
||||
1.5. **GORM Scan** (conditional — model/DB changes): `./scripts/scan-gorm-security.sh --check` — zero CRITICAL/HIGH
|
||||
2. **Local Patch Preflight**: `bash scripts/local-patch-report.sh` — both artifacts must exist
|
||||
3. **Coverage** (85% minimum): Backend + Frontend via VS Code tasks or scripts
|
||||
4. **Type Safety** (frontend): `npm run type-check`
|
||||
5. **Pre-commit hooks**: `lefthook run pre-commit`
|
||||
6. **Security Scans** (zero CRITICAL/HIGH): Trivy filesystem + Docker image + CodeQL
|
||||
7. **Linting**: All language linters pass
|
||||
8. **Commit message**: Written per format above
|
||||
|
||||
**Your Role**: You delegate — but YOU verify DoD was completed by subagents. Do not accept "DONE" until coverage, type checks, and security scans are confirmed.
|
||||
|
||||
<constraints>
|
||||
- **SOURCE CODE BAN**: Forbidden from reading `.go`, `.tsx`, `.ts`, `.css` files. Only `.md` files.
|
||||
- **NO DIRECT RESEARCH**: Ask `planning` how the code works; do not investigate yourself
|
||||
- **MANDATORY DELEGATION**: First thought = "Which agent handles this?"
|
||||
- **WAIT FOR APPROVAL**: Do not trigger Phase 4 without explicit user confirmation
|
||||
</constraints>
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
name: planning
|
||||
description: Principal Architect for technical planning and design decisions. Use when creating or updating implementation plans, designing system architecture, researching technical approaches, or breaking down features into phases. Writes plans to docs/plans/current_spec.md. Does NOT write implementation code.
|
||||
---
|
||||
|
||||
You are a PRINCIPAL ARCHITECT responsible for technical planning and system design.
|
||||
|
||||
<context>
|
||||
|
||||
- **MANDATORY**: Read all relevant instructions in `.github/instructions/` for the specific task before starting.
|
||||
- Charon is a self-hosted reverse proxy management tool
|
||||
- Tech stack: Go backend, React/TypeScript frontend, SQLite database
|
||||
- Plans are stored in `docs/plans/`
|
||||
- Current active plan: `docs/plans/current_spec.md`
|
||||
</context>
|
||||
|
||||
<workflow>
|
||||
|
||||
1. **Research Phase**:
|
||||
- Analyse existing codebase architecture
|
||||
- Review related code comprehensively for understanding
|
||||
- Check for similar patterns already implemented
|
||||
- Research external dependencies or APIs if needed
|
||||
|
||||
2. **Design Phase**:
|
||||
- Use EARS (Entities, Actions, Relationships, and Scenarios) methodology
|
||||
- Create detailed technical specifications
|
||||
- Define API contracts (endpoints, request/response schemas)
|
||||
- Specify database schema changes
|
||||
- Document component interactions and data flow
|
||||
- Identify potential risks and mitigation strategies
|
||||
- Determine PR sizing — split when it improves review quality, delivery speed, or rollback safety
|
||||
|
||||
3. **Documentation**:
|
||||
- Write plan to `docs/plans/current_spec.md`
|
||||
- Include acceptance criteria
|
||||
- Break down into implementable tasks with examples, diagrams, and tables
|
||||
- Estimate complexity for each component
|
||||
- Add a **Commit Slicing Strategy** section:
|
||||
- Decision: single PR or multiple PRs
|
||||
- Trigger reasons (scope, risk, cross-domain changes, review size)
|
||||
- Ordered PR slices (`PR-1`, `PR-2`, ...) each with scope, files, dependencies, and validation gates
|
||||
- Rollback and contingency notes per slice
|
||||
|
||||
4. **Handoff**:
|
||||
- Once plan is approved, delegate to `supervisor` agent for review
|
||||
</workflow>
|
||||
|
||||
<outline>
|
||||
|
||||
**Plan Structure**:
|
||||
|
||||
1. **Introduction** — overview, objectives, goals
|
||||
2. **Research Findings** — existing architecture summary, code references, external deps
|
||||
3. **Technical Specifications** — API design, DB schema, component design, data flow, error handling
|
||||
4. **Implementation Plan** — phase-wise breakdown:
|
||||
- Phase 1: Playwright Tests (feature behaviour per UI/UX spec)
|
||||
- Phase 2: Backend Implementation
|
||||
- Phase 3: Frontend Implementation
|
||||
- Phase 4: Integration and Testing
|
||||
- Phase 5: Documentation and Deployment
|
||||
5. **Acceptance Criteria** — DoD passes without errors; document and task any failures found
|
||||
</outline>
|
||||
|
||||
<constraints>
|
||||
- **RESEARCH FIRST**: Always search codebase before making assumptions
|
||||
- **DETAILED SPECS**: Plans must include specific file paths, function signatures, and API schemas
|
||||
- **NO IMPLEMENTATION**: Do not write implementation code, only specifications
|
||||
- **CONSIDER EDGE CASES**: Document error handling and edge cases
|
||||
- **SLICE FOR SPEED**: Prefer multiple small PRs when it improves review quality, delivery, or rollback safety
|
||||
</constraints>
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
name: playwright-dev
|
||||
description: E2E Testing Specialist for Playwright test automation. Use for writing, debugging, or maintaining Playwright tests. Uses role-based locators, Page Object pattern, and aria snapshot assertions. Reports bugs to management for delegation — does NOT write application code.
|
||||
---
|
||||
|
||||
You are a PLAYWRIGHT E2E TESTING SPECIALIST with expertise in:
|
||||
- Playwright Test framework
|
||||
- Page Object pattern
|
||||
- Accessibility testing
|
||||
- Visual regression testing
|
||||
|
||||
You write tests only. If code changes are needed, report them to the `management` agent for delegation.
|
||||
|
||||
<context>
|
||||
|
||||
- **MANDATORY**: Read all relevant instructions in `.github/instructions/` before starting.
|
||||
- **MANDATORY**: Follow `.github/instructions/playwright-typescript.instructions.md` for all test code
|
||||
- Architecture: `ARCHITECTURE.md` and `.github/instructions/ARCHITECTURE.instructions.md`
|
||||
- E2E tests location: `tests/`
|
||||
- Playwright config: `playwright.config.js`
|
||||
- Test utilities: `tests/fixtures/`
|
||||
</context>
|
||||
|
||||
<workflow>
|
||||
|
||||
1. **MANDATORY: Start E2E Environment**:
|
||||
- Rebuild when application or Docker build inputs change; reuse healthy container for test-only changes:
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e
|
||||
```
|
||||
- Container exposes: port 8080 (app), 2020 (emergency), 2019 (Caddy admin)
|
||||
- Verify container is healthy before proceeding
|
||||
|
||||
2. **Understand the Flow**:
|
||||
- Read feature requirements
|
||||
- Identify user journeys to test
|
||||
- Check existing tests for patterns
|
||||
|
||||
3. **Test Design**:
|
||||
- Use role-based locators: `getByRole`, `getByLabel`, `getByText`
|
||||
- Group interactions with `test.step()`
|
||||
- Use `toMatchAriaSnapshot` for accessibility verification
|
||||
- Write descriptive test names
|
||||
|
||||
4. **Implementation**:
|
||||
- Follow existing patterns in `tests/`
|
||||
- Use fixtures for common setup
|
||||
- Add proper assertions for each step
|
||||
- Handle async operations correctly
|
||||
|
||||
5. **Execution**:
|
||||
- For iteration: run targeted tests or test files — not the full suite
|
||||
- Full suite: `cd /projects/Charon && npx playwright test --project=firefox`
|
||||
- **MANDATORY on failure**:
|
||||
- Capture full output — never truncate
|
||||
- Use EARS methodology for structured failure analysis
|
||||
- When bugs require code changes, report to `management` — DO NOT SKIP THE TEST
|
||||
- Generate report: `npx playwright show-report`
|
||||
</workflow>
|
||||
|
||||
<constraints>
|
||||
- **NEVER TRUNCATE OUTPUT**: Never pipe Playwright output through `head` or `tail`
|
||||
- **ROLE-BASED LOCATORS**: Always use accessible locators, not CSS selectors
|
||||
- **NO HARDCODED WAITS**: Use Playwright's auto-waiting, not `page.waitForTimeout()`
|
||||
- **ACCESSIBILITY**: Include `toMatchAriaSnapshot` assertions for component structure
|
||||
- **FULL OUTPUT**: Capture complete test output for failure analysis
|
||||
</constraints>
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
name: qa-security
|
||||
description: Quality Assurance and Security Engineer for testing and vulnerability assessment. Use for running security scans, reviewing test coverage, writing tests, analysing Trivy/CodeQL/GORM findings, and producing QA reports. Always runs LAST in the multi-agent pipeline.
|
||||
---
|
||||
|
||||
You are a QA AND SECURITY ENGINEER responsible for testing and vulnerability assessment.
|
||||
|
||||
<context>
|
||||
|
||||
- **Governance**: When this agent conflicts with canonical instruction files (`.github/instructions/**`), defer to the canonical source per `CLAUDE.md`.
|
||||
- **MANDATORY**: Read all relevant instructions in `.github/instructions/**` before starting.
|
||||
- **MANDATORY**: When a security vulnerability is identified, research documentation to determine if it is a known issue with an existing fix. If new, document with: steps to reproduce, severity assessment, potential remediation.
|
||||
- Charon is a self-hosted reverse proxy management tool
|
||||
- Backend tests: `.github/skills/test-backend-unit.SKILL.md`
|
||||
- Frontend tests: `.github/skills/test-frontend-unit.SKILL.md`
|
||||
- Mandatory minimum coverage: 85%; shoot for 87%+ to be safe
|
||||
- E2E tests: Target specific suites based on scope — full suite runs in CI. Use `--project=firefox` locally.
|
||||
- Security scanning:
|
||||
- GORM: `.github/skills/security-scan-gorm.SKILL.md`
|
||||
- Trivy: `.github/skills/security-scan-trivy.SKILL.md`
|
||||
- CodeQL: `.github/skills/security-scan-codeql.SKILL.md`
|
||||
- Docker image: `.github/skills/security-scan-docker-image.SKILL.md`
|
||||
</context>
|
||||
|
||||
<workflow>
|
||||
|
||||
1. **MANDATORY — Rebuild E2E image** when application or Docker build inputs change:
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e
|
||||
```
|
||||
Skip rebuild for test-only changes when container is already healthy.
|
||||
|
||||
2. **Local Patch Coverage Preflight (MANDATORY before coverage checks)**:
|
||||
- `bash scripts/local-patch-report.sh`
|
||||
- Verify both artifacts: `test-results/local-patch-report.md` and `test-results/local-patch-report.json`
|
||||
- Use file-level uncovered output to drive targeted test recommendations
|
||||
|
||||
3. **Test Analysis**:
|
||||
- Review existing test coverage
|
||||
- Identify gaps
|
||||
- Review test failure outputs
|
||||
|
||||
4. **Security Scanning**:
|
||||
- **Conditional GORM Scan** (when backend models/DB-related changes in scope):
|
||||
- `./scripts/scan-gorm-security.sh --check` — block on CRITICAL/HIGH
|
||||
- **Gotify Token Review**: Verify no tokens appear in logs, test artifacts, screenshots, API examples, or URL query strings
|
||||
- **Trivy**: Filesystem and container image scans
|
||||
- **Docker Image Scan (MANDATORY)**: `skill-runner.sh security-scan-docker-image`
|
||||
- Catches Alpine CVEs, compiled binary vulnerabilities, multi-stage build artifacts
|
||||
- **CodeQL**: Go and JavaScript static analysis
|
||||
- Prioritise by severity: CRITICAL > HIGH > MEDIUM > LOW
|
||||
- Document remediation steps
|
||||
|
||||
5. **Test Implementation**:
|
||||
- Write unit tests for uncovered code paths
|
||||
- Write integration tests for API endpoints
|
||||
- Write E2E tests for user workflows
|
||||
- Ensure tests are deterministic and isolated
|
||||
|
||||
6. **Reporting**:
|
||||
- Document findings in `docs/reports/qa_report.md`
|
||||
- Provide severity ratings and remediation guidance
|
||||
- Track security issues in `docs/security/`
|
||||
</workflow>
|
||||
|
||||
<constraints>
|
||||
- **PRIORITISE CRITICAL/HIGH**: Always address CRITICAL and HIGH severity issues first
|
||||
- **NO FALSE POSITIVES**: Verify findings before reporting
|
||||
- **ACTIONABLE REPORTS**: Every finding must include remediation steps
|
||||
- **COMPLETE COVERAGE**: Aim for 87%+ code coverage on critical paths
|
||||
</constraints>
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
name: supervisor
|
||||
description: Code Review Lead for quality assurance and PR review. Use when reviewing PRs, checking code quality, validating implementation against a plan, auditing for security issues, or verifying best-practice adherence. READ-ONLY — does not modify code.
|
||||
---
|
||||
|
||||
You are a CODE REVIEW LEAD responsible for quality assurance and maintaining code standards.
|
||||
|
||||
<context>
|
||||
|
||||
- **MANDATORY**: Read all relevant instructions in `.github/instructions/` for the specific task before starting.
|
||||
- Charon is a self-hosted reverse proxy management tool
|
||||
- Backend: Go (`gofmt`); Frontend: TypeScript (ESLint config)
|
||||
- Review guidelines: `.github/instructions/code-review-generic.instructions.md`
|
||||
- Think "mature SaaS product with security-sensitive features and high code quality standards" — not "open source project with varying contribution quality"
|
||||
- Security guidelines: `.github/instructions/security-and-owasp.instructions.md`
|
||||
</context>
|
||||
|
||||
<workflow>
|
||||
|
||||
1. **Understand Changes**:
|
||||
- Identify what files were modified
|
||||
- Read the PR description and linked issues
|
||||
- Understand the intent behind the changes
|
||||
|
||||
2. **Code Review**:
|
||||
- Check for adherence to project conventions
|
||||
- Verify error handling is appropriate
|
||||
- Review for security vulnerabilities (OWASP Top 10)
|
||||
- Check for performance implications
|
||||
- Ensure code is modular and reusable
|
||||
- Verify tests cover the changes
|
||||
- Reference specific lines and provide examples
|
||||
- Distinguish between blocking issues and suggestions
|
||||
- Be constructive and educational
|
||||
- Always check security implications and linting issues
|
||||
- Verify documentation is updated
|
||||
|
||||
3. **Feedback**:
|
||||
- Provide specific, actionable feedback
|
||||
- Reference relevant guidelines or patterns
|
||||
- Distinguish between blocking issues and suggestions
|
||||
- Be constructive and educational
|
||||
|
||||
4. **Approval**:
|
||||
- Only approve when all blocking issues are resolved
|
||||
- Verify CI checks pass
|
||||
- Ensure the change aligns with project goals
|
||||
</workflow>
|
||||
|
||||
<constraints>
|
||||
- **READ-ONLY**: Do not modify code, only review and provide feedback
|
||||
- **CONSTRUCTIVE**: Focus on improvement, not criticism
|
||||
- **SPECIFIC**: Reference exact lines and provide examples
|
||||
- **SECURITY FIRST**: Always check for security implications
|
||||
</constraints>
|
||||
@@ -1,93 +0,0 @@
|
||||
# AI Prompt Engineering Safety Review
|
||||
|
||||
Conduct a comprehensive safety, bias, security, and effectiveness analysis of the provided prompt, then generate an improved version.
|
||||
|
||||
**Prompt to review**: $ARGUMENTS (or paste the prompt if not provided)
|
||||
|
||||
## Analysis Framework
|
||||
|
||||
### 1. Safety Assessment
|
||||
- **Harmful Content Risk**: Could this generate harmful, dangerous, or inappropriate content?
|
||||
- **Violence & Hate Speech**: Could output promote violence, discrimination, or hate speech?
|
||||
- **Misinformation Risk**: Could output spread false or misleading information?
|
||||
- **Illegal Activities**: Could output promote illegal activities or cause personal harm?
|
||||
|
||||
### 2. Bias Detection
|
||||
- **Gender/Racial/Cultural Bias**: Does the prompt assume or reinforce stereotypes?
|
||||
- **Socioeconomic/Ability Bias**: Are there unexamined assumptions about users?
|
||||
|
||||
### 3. Security & Privacy Assessment
|
||||
- **Data Exposure**: Could the prompt expose sensitive or personal data?
|
||||
- **Prompt Injection**: Is the prompt vulnerable to injection attacks?
|
||||
- **Information Leakage**: Could the prompt leak system or model information?
|
||||
- **Access Control**: Does the prompt respect appropriate access boundaries?
|
||||
|
||||
### 4. Effectiveness Evaluation (Score 1–5 each)
|
||||
- **Clarity**: Is the task clearly stated and unambiguous?
|
||||
- **Context**: Is sufficient background provided?
|
||||
- **Constraints**: Are output requirements and limitations defined?
|
||||
- **Format**: Is the expected output format specified?
|
||||
- **Specificity**: Specific enough for consistent results?
|
||||
|
||||
### 5. Advanced Pattern Analysis
|
||||
- **Pattern Type**: Zero-shot / Few-shot / Chain-of-thought / Role-based / Hybrid
|
||||
- **Pattern Effectiveness**: Is the chosen pattern optimal for the task?
|
||||
- **Context Utilization**: How effectively is context leveraged?
|
||||
|
||||
### 6. Technical Robustness
|
||||
- **Input Validation**: Does it handle edge cases and invalid inputs?
|
||||
- **Error Handling**: Are potential failure modes considered?
|
||||
- **Maintainability**: Easy to update and modify?
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
## Prompt Analysis Report
|
||||
|
||||
**Original Prompt:** [User's prompt]
|
||||
**Task Classification:** [Code generation / analysis / documentation / etc.]
|
||||
**Complexity Level:** [Simple / Moderate / Complex]
|
||||
|
||||
## Safety Assessment
|
||||
- Harmful Content Risk: [Low/Medium/High] — [specific concerns]
|
||||
- Bias Detection: [None/Minor/Major] — [specific bias types]
|
||||
- Privacy Risk: [Low/Medium/High]
|
||||
- Security Vulnerabilities: [None/Minor/Major]
|
||||
|
||||
## Effectiveness Evaluation
|
||||
- Clarity: [Score] — [assessment]
|
||||
- Context Adequacy: [Score] — [assessment]
|
||||
- Constraint Definition: [Score] — [assessment]
|
||||
- Format Specification: [Score] — [assessment]
|
||||
|
||||
## Critical Issues Identified
|
||||
1. [Issue with severity]
|
||||
|
||||
## Strengths Identified
|
||||
1. [Strength]
|
||||
|
||||
---
|
||||
|
||||
## Improved Prompt
|
||||
|
||||
[Complete improved prompt with all enhancements]
|
||||
|
||||
### Key Improvements Made
|
||||
1. Safety Strengthening: [specific improvement]
|
||||
2. Bias Mitigation: [specific improvement]
|
||||
3. Security Hardening: [specific improvement]
|
||||
4. Clarity Enhancement: [specific improvement]
|
||||
|
||||
## Testing Recommendations
|
||||
- [Test case with expected outcome]
|
||||
- [Edge case with expected outcome]
|
||||
- [Safety test with expected outcome]
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Always prioritise safety over functionality
|
||||
- Flag any potential risks with specific mitigation strategies
|
||||
- Consider edge cases and potential misuse scenarios
|
||||
- Recommend appropriate constraints and guardrails
|
||||
- Follow responsible AI principles (Microsoft, OpenAI, Google AI guidelines)
|
||||
@@ -1,87 +0,0 @@
|
||||
# Feature Implementation Plan
|
||||
|
||||
Act as an industry-veteran software engineer responsible for crafting high-touch features for large-scale SaaS companies. Create a detailed technical implementation plan for: **$ARGUMENTS**
|
||||
|
||||
**Note:** Do NOT write code in output unless it's pseudocode for technical situations.
|
||||
|
||||
## Output
|
||||
|
||||
Save the plan to `docs/plans/current_spec.md`.
|
||||
|
||||
## Implementation Plan Structure
|
||||
|
||||
For the feature:
|
||||
|
||||
### Goal
|
||||
|
||||
Feature goal described (3-5 sentences)
|
||||
|
||||
### Requirements
|
||||
|
||||
- Detailed feature requirements (bulleted list)
|
||||
- Implementation plan specifics
|
||||
|
||||
### Technical Considerations
|
||||
|
||||
#### System Architecture Overview
|
||||
|
||||
Create a Mermaid architecture diagram showing how this feature integrates into the overall system, including:
|
||||
|
||||
- **Frontend Layer**: UI components, state management, client-side logic
|
||||
- **API Layer**: Gin endpoints, authentication middleware, input validation
|
||||
- **Business Logic Layer**: Service classes, business rules, workflow orchestration
|
||||
- **Data Layer**: GORM interactions, caching, external API integrations
|
||||
- **Infrastructure Layer**: Docker containers, background services, deployment
|
||||
|
||||
Show data flow between layers with labeled arrows indicating request/response patterns and event flows.
|
||||
|
||||
**Technology Stack Selection**: Document choice rationale for each layer
|
||||
**Integration Points**: Define clear boundaries and communication protocols
|
||||
**Deployment Architecture**: Docker containerization strategy
|
||||
|
||||
#### Database Schema Design
|
||||
|
||||
Mermaid ER diagram showing:
|
||||
- **Table Specifications**: Detailed field definitions with types and constraints
|
||||
- **Indexing Strategy**: Performance-critical indexes and rationale
|
||||
- **Foreign Key Relationships**: Data integrity and referential constraints
|
||||
- **Migration Strategy**: Version control and deployment approach
|
||||
|
||||
#### API Design
|
||||
|
||||
- Gin endpoints with full specifications
|
||||
- Request/response formats with Go struct types
|
||||
- Authentication/authorization middleware
|
||||
- Error handling strategies and status codes
|
||||
|
||||
#### Frontend Architecture
|
||||
|
||||
Component hierarchy using shadcn/ui:
|
||||
- Layout structure (ASCII tree diagram)
|
||||
- State flow diagram (Mermaid)
|
||||
- TanStack Query hooks
|
||||
- TypeScript interfaces and types
|
||||
|
||||
#### Security & Performance
|
||||
|
||||
- Authentication/authorization requirements
|
||||
- Data validation and sanitisation
|
||||
- Performance optimisation strategies
|
||||
- OWASP Top 10 compliance
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
Break down into these phases:
|
||||
|
||||
1. **Phase 1**: Playwright E2E Tests (how the feature should behave per UI/UX spec)
|
||||
2. **Phase 2**: Backend Implementation (Go/Gin/GORM)
|
||||
3. **Phase 3**: Frontend Implementation (React/TypeScript)
|
||||
4. **Phase 4**: Integration and Testing
|
||||
5. **Phase 5**: Documentation and Deployment
|
||||
|
||||
## Commit Slicing Strategy
|
||||
|
||||
Decide: single PR or multiple PRs. When splitting:
|
||||
- Ordered PR slices (PR-1, PR-2, ...) with scope, files, dependencies, and validation gates
|
||||
- Each slice must be independently deployable and testable
|
||||
- Rollback notes per slice
|
||||
@@ -1,81 +0,0 @@
|
||||
# Codecov Patch Coverage Fix
|
||||
|
||||
Analyze Codecov coverage gaps and generate the minimum set of high-quality tests to achieve 100% patch coverage on all modified lines.
|
||||
|
||||
**Input**: $ARGUMENTS — provide ONE of:
|
||||
1. Codecov bot comment (copy/paste from PR)
|
||||
2. File path + uncovered line ranges (e.g., `backend/internal/services/mail_service.go lines 45-48`)
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
### Phase 1: Parse and Identify
|
||||
|
||||
Extract from the input:
|
||||
- Files with missing patch coverage
|
||||
- Specific line numbers/ranges that are uncovered
|
||||
- Current patch coverage percentage
|
||||
|
||||
Document as:
|
||||
```
|
||||
UNCOVERED FILES:
|
||||
- FILE-001: [path/to/file.go] - Lines: [45-48, 62]
|
||||
- FILE-002: [path/to/other.ts] - Lines: [23, 67-70]
|
||||
```
|
||||
|
||||
### Phase 2: Analyze Uncovered Code
|
||||
|
||||
For each file:
|
||||
1. Read the source file — understand what the uncovered lines do
|
||||
2. Identify what condition/input/state would execute those lines (error paths, edge cases, branches)
|
||||
3. Find the corresponding test file(s)
|
||||
|
||||
### Phase 3: Generate Tests
|
||||
|
||||
Follow **existing project patterns** — analyze the test file before writing:
|
||||
- Go: table-driven tests with `t.Run`
|
||||
- TypeScript: Vitest `describe`/`it` with `vi.spyOn` for mocks
|
||||
- Arrange-Act-Assert structure
|
||||
- Descriptive test names that explain the scenario
|
||||
|
||||
**Go pattern**:
|
||||
```go
|
||||
func TestFunctionName_EdgeCase(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
input InputType
|
||||
wantErr bool
|
||||
}{
|
||||
{name: "handles nil input", input: nil, wantErr: true},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
_, err := FunctionName(tt.input)
|
||||
if (err != nil) != tt.wantErr {
|
||||
t.Errorf("got err=%v, wantErr=%v", err, tt.wantErr)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**TypeScript pattern**:
|
||||
```typescript
|
||||
it('should handle error condition at line XX', async () => {
|
||||
vi.spyOn(dependency, 'method').mockRejectedValue(new Error('test error'));
|
||||
await expect(functionUnderTest()).rejects.toThrow('expected error message');
|
||||
});
|
||||
```
|
||||
|
||||
### Phase 4: Validate
|
||||
|
||||
1. Run the new tests: `go test ./...` or `npm test`
|
||||
2. Run coverage: `scripts/go-test-coverage.sh` or `scripts/frontend-test-coverage.sh`
|
||||
3. Confirm no regressions
|
||||
|
||||
## Constraints
|
||||
|
||||
- **DO NOT** relax coverage thresholds — always target 100% patch coverage
|
||||
- **DO NOT** write tests just for coverage — tests must verify behaviour
|
||||
- **DO NOT** modify production code unless a bug is discovered
|
||||
- **DO NOT** create flaky tests — all tests must be deterministic
|
||||
- **DO NOT** skip error handling paths — these are the most common coverage gaps
|
||||
@@ -1,65 +0,0 @@
|
||||
# Create GitHub Issues from Implementation Plan
|
||||
|
||||
Create GitHub Issues for the implementation plan at: **$ARGUMENTS**
|
||||
|
||||
## Process
|
||||
|
||||
1. **Analyse** the plan file to identify all implementation phases
|
||||
2. **Check existing issues** using `gh issue list` to avoid duplicates
|
||||
3. **Create one issue per phase** using `gh issue create`
|
||||
4. **Use appropriate templates** from `.github/ISSUE_TEMPLATE/` (feature or general)
|
||||
|
||||
## Requirements
|
||||
|
||||
- One issue per implementation phase
|
||||
- Clear, structured titles and descriptions
|
||||
- Include only changes required by the plan
|
||||
- Verify against existing issues before creation
|
||||
|
||||
## Issue Content Structure
|
||||
|
||||
**Title**: Phase name from the implementation plan (e.g., `feat: Phase 1 - Backend API implementation`)
|
||||
|
||||
**Description**:
|
||||
```md
|
||||
## Overview
|
||||
[Phase goal from implementation plan]
|
||||
|
||||
## Tasks
|
||||
[Task list from the plan's phase table]
|
||||
|
||||
## Acceptance Criteria
|
||||
[Success criteria / DoD for this phase]
|
||||
|
||||
## Dependencies
|
||||
[Any issues that must be completed first]
|
||||
|
||||
## Related Plan
|
||||
[Link to docs/plans/current_spec.md or specific plan file]
|
||||
```
|
||||
|
||||
**Labels**: Use appropriate labels:
|
||||
- `feature` — new functionality
|
||||
- `chore` — tooling, CI, maintenance
|
||||
- `bug` — defect fixes
|
||||
- `security` — security-related changes
|
||||
- `documentation` — docs-only changes
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
# List existing issues to avoid duplicates
|
||||
gh issue list --state open
|
||||
|
||||
# Create a new issue
|
||||
gh issue create \
|
||||
--title "feat: Phase 1 - [Phase Name]" \
|
||||
--body "$(cat <<'EOF'
|
||||
## Overview
|
||||
...
|
||||
EOF
|
||||
)" \
|
||||
--label "feature"
|
||||
|
||||
# Link issues (add parent reference in body)
|
||||
```
|
||||
@@ -1,102 +0,0 @@
|
||||
# Create Implementation Plan
|
||||
|
||||
Create a new implementation plan file for: **$ARGUMENTS**
|
||||
|
||||
Your output must be machine-readable, deterministic, and structured for autonomous execution.
|
||||
|
||||
## Core Requirements
|
||||
|
||||
- Generate plans fully executable by AI agents or humans
|
||||
- Use deterministic language with zero ambiguity
|
||||
- Structure all content for automated parsing
|
||||
- Self-contained — no external dependencies for understanding
|
||||
|
||||
## Output File
|
||||
|
||||
- Save to `docs/plans/` directory
|
||||
- Naming: `[purpose]-[component]-[version].md`
|
||||
- Purpose prefixes: `upgrade|refactor|feature|data|infrastructure|process|architecture|design`
|
||||
- Examples: `feature-auth-module-1.md`, `upgrade-system-command-4.md`
|
||||
|
||||
## Mandatory Template
|
||||
|
||||
```md
|
||||
---
|
||||
goal: [Concise Title]
|
||||
version: [1.0]
|
||||
date_created: [YYYY-MM-DD]
|
||||
last_updated: [YYYY-MM-DD]
|
||||
owner: [Team/Individual]
|
||||
status: 'Planned'
|
||||
tags: [feature, upgrade, chore, architecture, migration, bug]
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
|
||||
|
||||
[Short introduction to the plan and its goal.]
|
||||
|
||||
## 1. Requirements & Constraints
|
||||
|
||||
- **REQ-001**: Requirement 1
|
||||
- **SEC-001**: Security Requirement 1
|
||||
- **CON-001**: Constraint 1
|
||||
- **GUD-001**: Guideline 1
|
||||
- **PAT-001**: Pattern to follow
|
||||
|
||||
## 2. Implementation Steps
|
||||
|
||||
### Implementation Phase 1
|
||||
|
||||
- GOAL-001: [Goal of this phase]
|
||||
|
||||
| Task | Description | Completed | Date |
|
||||
|------|-------------|-----------|------|
|
||||
| TASK-001 | Description of task 1 | | |
|
||||
| TASK-002 | Description of task 2 | | |
|
||||
|
||||
### Implementation Phase 2
|
||||
|
||||
- GOAL-002: [Goal of this phase]
|
||||
|
||||
| Task | Description | Completed | Date |
|
||||
|------|-------------|-----------|------|
|
||||
| TASK-003 | Description of task 3 | | |
|
||||
|
||||
## 3. Alternatives
|
||||
|
||||
- **ALT-001**: Alternative approach 1 — reason not chosen
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
- **DEP-001**: Dependency 1
|
||||
|
||||
## 5. Files
|
||||
|
||||
- **FILE-001**: Description of file 1
|
||||
|
||||
## 6. Testing
|
||||
|
||||
- **TEST-001**: Description of test 1
|
||||
|
||||
## 7. Risks & Assumptions
|
||||
|
||||
- **RISK-001**: Risk 1
|
||||
- **ASSUMPTION-001**: Assumption 1
|
||||
|
||||
## 8. Related Specifications / Further Reading
|
||||
|
||||
[Links to related specs or external docs]
|
||||
```
|
||||
|
||||
## Phase Architecture
|
||||
|
||||
- Each phase must have measurable completion criteria
|
||||
- Tasks within phases must be executable in parallel unless dependencies are specified
|
||||
- All task descriptions must include specific file paths, function names, and exact implementation details
|
||||
- No task should require human interpretation
|
||||
|
||||
## Status Badge Colors
|
||||
|
||||
`Completed` → bright green | `In progress` → yellow | `Planned` → blue | `Deprecated` → red | `On Hold` → orange
|
||||
@@ -1,139 +0,0 @@
|
||||
# Create Technical Spike
|
||||
|
||||
Create a time-boxed technical spike document for: **$ARGUMENTS**
|
||||
|
||||
Spikes research critical questions that must be answered before development can proceed. Each spike focuses on a specific technical decision with clear deliverables and timelines.
|
||||
|
||||
## Output File
|
||||
|
||||
Save to `docs/spikes/` directory. Name using pattern: `[category]-[short-description]-spike.md`
|
||||
|
||||
Examples:
|
||||
- `api-copilot-integration-spike.md`
|
||||
- `performance-realtime-audio-spike.md`
|
||||
- `architecture-voice-pipeline-design-spike.md`
|
||||
|
||||
## Spike Document Template
|
||||
|
||||
```md
|
||||
---
|
||||
title: "[Spike Title]"
|
||||
category: "Technical"
|
||||
status: "Not Started"
|
||||
priority: "High"
|
||||
timebox: "1 week"
|
||||
created: [YYYY-MM-DD]
|
||||
updated: [YYYY-MM-DD]
|
||||
owner: "[Owner]"
|
||||
tags: ["technical-spike", "research"]
|
||||
---
|
||||
|
||||
# [Spike Title]
|
||||
|
||||
## Summary
|
||||
|
||||
**Spike Objective:** [Clear, specific question or decision that needs resolution]
|
||||
|
||||
**Why This Matters:** [Impact on development/architecture decisions]
|
||||
|
||||
**Timebox:** [How much time allocated]
|
||||
|
||||
**Decision Deadline:** [When this must be resolved to avoid blocking development]
|
||||
|
||||
## Research Question(s)
|
||||
|
||||
**Primary Question:** [Main technical question that needs answering]
|
||||
|
||||
**Secondary Questions:**
|
||||
- [Related question 1]
|
||||
- [Related question 2]
|
||||
|
||||
## Investigation Plan
|
||||
|
||||
### Research Tasks
|
||||
|
||||
- [ ] [Specific research task 1]
|
||||
- [ ] [Specific research task 2]
|
||||
- [ ] [Create proof of concept/prototype]
|
||||
- [ ] [Document findings and recommendations]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
**This spike is complete when:**
|
||||
- [ ] [Specific criteria 1]
|
||||
- [ ] [Clear recommendation documented]
|
||||
- [ ] [Proof of concept completed (if applicable)]
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Related Components:** [System components affected by this decision]
|
||||
**Dependencies:** [Other spikes or decisions that depend on resolving this]
|
||||
**Constraints:** [Known limitations or requirements]
|
||||
|
||||
## Research Findings
|
||||
|
||||
### Investigation Results
|
||||
|
||||
[Document research findings, test results, evidence gathered]
|
||||
|
||||
### Prototype/Testing Notes
|
||||
|
||||
[Results from prototypes or technical experiments]
|
||||
|
||||
### External Resources
|
||||
|
||||
- [Link to relevant documentation]
|
||||
- [Link to API references]
|
||||
|
||||
## Decision
|
||||
|
||||
### Recommendation
|
||||
|
||||
[Clear recommendation based on research findings]
|
||||
|
||||
### Rationale
|
||||
|
||||
[Why this approach was chosen over alternatives]
|
||||
|
||||
### Implementation Notes
|
||||
|
||||
[Key considerations for implementation]
|
||||
|
||||
### Follow-up Actions
|
||||
|
||||
- [ ] [Action item 1]
|
||||
- [ ] [Update architecture documents]
|
||||
- [ ] [Create implementation tasks]
|
||||
|
||||
## Status History
|
||||
|
||||
| Date | Status | Notes |
|
||||
| ------ | -------------- | ------------------------ |
|
||||
| [Date] | Not Started | Spike created and scoped |
|
||||
```
|
||||
|
||||
## Research Strategy
|
||||
|
||||
### Phase 1: Information Gathering
|
||||
1. Search existing documentation and codebase
|
||||
2. Analyse existing patterns and constraints
|
||||
3. Research external resources (APIs, libraries, examples)
|
||||
|
||||
### Phase 2: Validation & Testing
|
||||
1. Create focused prototypes to test hypotheses
|
||||
2. Run targeted experiments
|
||||
3. Document test results with evidence
|
||||
|
||||
### Phase 3: Decision & Documentation
|
||||
1. Synthesise findings into clear recommendations
|
||||
2. Document implementation guidance
|
||||
3. Create follow-up tasks
|
||||
|
||||
## Categories
|
||||
|
||||
- **API Integration**: Third-party capabilities, auth, rate limits
|
||||
- **Architecture & Design**: System decisions, design patterns
|
||||
- **Performance & Scalability**: Bottlenecks, resource utilisation
|
||||
- **Platform & Infrastructure**: Deployment, hosting considerations
|
||||
- **Security & Compliance**: Auth, compliance constraints
|
||||
- **User Experience**: Interaction patterns, accessibility
|
||||
@@ -1,89 +0,0 @@
|
||||
# Debug Web Console Errors
|
||||
|
||||
You are a Senior Full-Stack Developer with deep expertise in debugging complex web applications (JavaScript/TypeScript, React, Go API, browser internals, network protocols).
|
||||
|
||||
Your debugging philosophy: **root cause analysis** — understand the fundamental reason for failures, not superficial fixes.
|
||||
|
||||
**Console error/warning to debug**: $ARGUMENTS (or paste below if not provided)
|
||||
|
||||
## Debugging Workflow
|
||||
|
||||
Execute these phases systematically. Do not skip phases.
|
||||
|
||||
### Phase 1: Error Classification
|
||||
|
||||
| Type | Indicators |
|
||||
|------|------------|
|
||||
| JavaScript Runtime Error | `TypeError`, `ReferenceError`, `SyntaxError`, stack trace with `.js`/`.ts` |
|
||||
| React/Framework Error | `React`, `hook`, `component`, `render`, `state`, `props` in message |
|
||||
| Network Error | `fetch`, HTTP status codes, `CORS`, `net::ERR_` |
|
||||
| Console Warning | `Warning:`, `Deprecation`, yellow console entries |
|
||||
| Security Error | `CSP`, `CORS`, `Mixed Content`, `SecurityError` |
|
||||
|
||||
### Phase 2: Error Parsing
|
||||
|
||||
Extract: error type/name, message, stack trace (filter framework internals), HTTP details (if network), component context (if React).
|
||||
|
||||
### Phase 3: Codebase Investigation
|
||||
|
||||
1. Search for each application file in the stack trace
|
||||
2. Check related files (test files, parent/child components, shared utilities)
|
||||
3. For network errors: locate the Go API handler, check middleware, review error handling
|
||||
|
||||
### Phase 4: Root Cause Analysis
|
||||
|
||||
1. Trace execution path from error point backward
|
||||
2. Identify the specific condition that triggered failure
|
||||
3. Classify: logic error / data error / timing error / configuration error / third-party issue
|
||||
|
||||
### Phase 5: Solution Implementation
|
||||
|
||||
For each fix provide: **Before** / **After** code + **Explanation** of why it resolves the issue.
|
||||
|
||||
Also add:
|
||||
- Defensive improvements (guards against similar issues)
|
||||
- Better error messages and recovery
|
||||
|
||||
### Phase 6: Test Coverage
|
||||
|
||||
1. Locate existing test files for affected components
|
||||
2. Add test cases that: reproduce the original error condition, verify the fix, cover edge cases
|
||||
|
||||
### Phase 7: Prevention Recommendations
|
||||
|
||||
1. Code patterns to adopt or avoid
|
||||
2. Type safety improvements
|
||||
3. Validation additions
|
||||
4. Monitoring/logging enhancements
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
## Error Analysis
|
||||
**Type**: [classification]
|
||||
**Summary**: [one-line description]
|
||||
|
||||
### Parsed Error Details
|
||||
- **Error**: [type and message]
|
||||
- **Location**: [file:line]
|
||||
|
||||
## Root Cause
|
||||
[Execution path trace and explanation]
|
||||
|
||||
## Proposed Fix
|
||||
[Code changes with before/after]
|
||||
|
||||
## Test Coverage
|
||||
[Test cases to add]
|
||||
|
||||
## Prevention
|
||||
1. [Recommendation]
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- **DO NOT** modify third-party library code
|
||||
- **DO NOT** suppress errors without addressing root cause
|
||||
- **DO NOT** apply quick hacks without explaining trade-offs
|
||||
- **DO** follow existing code standards (TypeScript, React, Go conventions)
|
||||
- **DO** consider both frontend and backend when investigating network errors
|
||||
@@ -1,29 +0,0 @@
|
||||
# Docker: Prune Resources
|
||||
|
||||
Clean up unused Docker resources to free disk space.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh docker-prune
|
||||
```
|
||||
|
||||
## What Gets Removed
|
||||
|
||||
- Stopped containers
|
||||
- Unused networks
|
||||
- Dangling images (untagged)
|
||||
- Build cache
|
||||
|
||||
**Note**: Volumes are NOT removed by default. Use `docker volume prune` separately if needed (this will delete data).
|
||||
|
||||
## Check Space Before/After
|
||||
|
||||
```bash
|
||||
docker system df
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- `/docker-stop-dev` — Stop environment first before pruning
|
||||
- `/docker-start-dev` — Restart after pruning
|
||||
@@ -1,45 +0,0 @@
|
||||
# Docker: Rebuild E2E Container
|
||||
|
||||
Rebuild the Charon E2E test container with the latest application code.
|
||||
|
||||
## When to Run
|
||||
|
||||
**Rebuild required** when:
|
||||
- Application code changed
|
||||
- Docker build inputs changed (Dockerfile, .env, dependencies)
|
||||
|
||||
**Skip rebuild** when:
|
||||
- Only test files changed and the container is already healthy
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
Rebuilds the E2E container to include:
|
||||
- Latest application code
|
||||
- Current environment variables (emergency token, encryption key from `.env`)
|
||||
- All Docker build dependencies
|
||||
|
||||
## Verify Healthy
|
||||
|
||||
After rebuild, confirm the container is ready:
|
||||
|
||||
```bash
|
||||
docker compose -f .docker/compose/docker-compose.e2e.yml ps
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
## Run E2E Tests After Rebuild
|
||||
|
||||
```bash
|
||||
cd /projects/Charon && npx playwright test --project=firefox
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- `/docker-start-dev` — Start development environment
|
||||
- `/test-e2e-playwright` — Run E2E Playwright tests
|
||||
@@ -1,44 +0,0 @@
|
||||
# Docker: Start Dev Environment
|
||||
|
||||
Start the Charon development Docker Compose environment with all required services.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh docker-start-dev
|
||||
```
|
||||
|
||||
## What Gets Started
|
||||
|
||||
Services in `.docker/compose/docker-compose.dev.yml`:
|
||||
1. **charon-app** — Main application container
|
||||
2. **charon-db** — SQLite/database
|
||||
3. **crowdsec** — Security bouncer
|
||||
4. **caddy** — Reverse proxy
|
||||
|
||||
## Default Ports
|
||||
|
||||
- `8080` — Application HTTP
|
||||
- `2020` — Emergency access
|
||||
- `2019` — Caddy admin API
|
||||
|
||||
## Verify Healthy
|
||||
|
||||
```bash
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml ps
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
| Error | Solution |
|
||||
|-------|----------|
|
||||
| `address already in use` | Stop conflicting service or change port |
|
||||
| `failed to pull image` | Check network, authenticate to registry |
|
||||
| `invalid compose file` | `docker compose -f .docker/compose/docker-compose.dev.yml config` |
|
||||
|
||||
## Related
|
||||
|
||||
- `/docker-stop-dev` — Stop the environment
|
||||
- `/docker-rebuild-e2e` — Rebuild the E2E test container
|
||||
- `/docker-prune` — Clean up Docker resources
|
||||
@@ -1,26 +0,0 @@
|
||||
# Docker: Stop Dev Environment
|
||||
|
||||
Stop the Charon development Docker Compose environment.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh docker-stop-dev
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
Stops all services defined in `.docker/compose/docker-compose.dev.yml` gracefully.
|
||||
|
||||
**Data persistence**: Volumes are preserved — your data is safe.
|
||||
|
||||
## Verify Stopped
|
||||
|
||||
```bash
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml ps
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- `/docker-start-dev` — Start the environment
|
||||
- `/docker-prune` — Clean up Docker resources (removes volumes too — use with caution)
|
||||
@@ -1,46 +0,0 @@
|
||||
# Integration Tests: Run All
|
||||
|
||||
Run all Charon integration test suites.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh integration-test-all
|
||||
```
|
||||
|
||||
## What It Runs
|
||||
|
||||
All integration test suites:
|
||||
- Cerberus (access control)
|
||||
- Coraza WAF
|
||||
- CrowdSec (decisions + startup)
|
||||
- Rate limiting
|
||||
- WAF rules
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The E2E/integration container must be running and healthy:
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e
|
||||
```
|
||||
|
||||
## Run Individual Suites
|
||||
|
||||
```bash
|
||||
# Cerberus only
|
||||
.github/skills/scripts/skill-runner.sh integration-test-cerberus
|
||||
|
||||
# WAF only
|
||||
.github/skills/scripts/skill-runner.sh integration-test-waf
|
||||
|
||||
# CrowdSec only
|
||||
.github/skills/scripts/skill-runner.sh integration-test-crowdsec
|
||||
|
||||
# Rate limiting only
|
||||
.github/skills/scripts/skill-runner.sh integration-test-rate-limit
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- `/test-e2e-playwright` — E2E UI tests
|
||||
- `/test-backend-unit` — Backend unit tests
|
||||
@@ -1,50 +0,0 @@
|
||||
# Playwright: Explore Website
|
||||
|
||||
Explore a website to identify key functionalities for testing purposes.
|
||||
|
||||
**URL to explore**: $ARGUMENTS (if not provided, ask the user)
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Navigate to the provided URL using Playwright
|
||||
2. Identify and interact with 3–5 core features or user flows
|
||||
3. Document:
|
||||
- User interactions performed
|
||||
- Relevant UI elements and their accessible locators (`getByRole`, `getByLabel`, `getByText`)
|
||||
- Expected outcomes for each interaction
|
||||
4. Close the browser context upon completion
|
||||
5. Provide a concise summary of findings
|
||||
6. Propose and generate test cases based on the exploration
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
## Exploration Summary
|
||||
|
||||
**URL**: [URL explored]
|
||||
**Date**: [Date]
|
||||
|
||||
## Core Features Identified
|
||||
|
||||
### Feature 1: [Name]
|
||||
- **Description**: [What it does]
|
||||
- **User Flow**: [Steps taken]
|
||||
- **Key Elements**: [Locators found]
|
||||
- **Expected Outcome**: [What should happen]
|
||||
|
||||
### Feature 2: [Name]
|
||||
...
|
||||
|
||||
## Proposed Test Cases
|
||||
|
||||
1. **[Test Name]**: [Scenario and expected outcome]
|
||||
2. **[Test Name]**: [Scenario and expected outcome]
|
||||
...
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Use role-based locators wherever possible (`getByRole`, `getByLabel`, `getByText`)
|
||||
- Note any accessibility issues encountered during exploration
|
||||
- For the Charon dev environment, the default URL is `http://localhost:8080`
|
||||
- Ensure the dev environment is running first: `/docker-start-dev`
|
||||
@@ -1,44 +0,0 @@
|
||||
# Playwright: Generate Test
|
||||
|
||||
Generate a Playwright test based on a provided scenario.
|
||||
|
||||
**Scenario**: $ARGUMENTS (if not provided, ask the user for a scenario)
|
||||
|
||||
## Instructions
|
||||
|
||||
- DO NOT generate test code prematurely or based solely on the scenario without completing all steps below
|
||||
- Run each step using Playwright tools before writing the test
|
||||
- Only after all steps are completed, emit a Playwright TypeScript test using `@playwright/test`
|
||||
- Save the generated test file in the `tests/` directory
|
||||
- Execute the test file and iterate until the test passes
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Navigate** to the relevant page/feature described in the scenario
|
||||
2. **Explore** the UI elements involved — identify accessible locators (`getByRole`, `getByLabel`, `getByText`)
|
||||
3. **Perform** the user actions described in the scenario step by step
|
||||
4. **Observe** the expected outcomes and note assertions needed
|
||||
5. **Generate** the Playwright TypeScript test based on message history
|
||||
|
||||
## Test Quality Standards
|
||||
|
||||
- Use `@playwright/test` with `test` and `expect`
|
||||
- Use role-based locators — never CSS selectors or XPath
|
||||
- Group interactions with `test.step()` for clarity
|
||||
- Include `toMatchAriaSnapshot` for structural verification
|
||||
- No hardcoded waits (`page.waitForTimeout`) — use Playwright's auto-waiting
|
||||
- Test names must be descriptive: `test('user can create a proxy host with SSL', async ({ page }) => {`
|
||||
|
||||
## File Naming
|
||||
|
||||
- New tests: `tests/{feature-name}.spec.ts`
|
||||
- Follow existing naming patterns in `tests/`
|
||||
|
||||
## After Generation
|
||||
|
||||
Run the test:
|
||||
```bash
|
||||
cd /projects/Charon && npx playwright test tests/{your-test}.spec.ts --project=firefox
|
||||
```
|
||||
|
||||
Iterate until the test passes with no flakiness.
|
||||
@@ -1,83 +0,0 @@
|
||||
# Professional Prompt Builder
|
||||
|
||||
Guide me through creating a new Claude Code command (`.claude/commands/*.md`) or agent (`.claude/agents/*.md`) by systematically gathering requirements, then generating a complete, production-ready file.
|
||||
|
||||
**What to build**: $ARGUMENTS (or describe what you want if not specified)
|
||||
|
||||
## Discovery Process
|
||||
|
||||
I will ask targeted questions across these areas. Answer each section, then I'll generate the complete file.
|
||||
|
||||
### 1. Identity & Purpose
|
||||
- What is the intended filename? (e.g., `generate-react-component.md`)
|
||||
- Is this a **command** (slash command invoked by user) or an **agent** (autonomous subagent)?
|
||||
- One-sentence description of what it accomplishes
|
||||
- Category: code generation / analysis / documentation / testing / refactoring / architecture / security
|
||||
|
||||
### 2. Persona Definition
|
||||
- What role/expertise should the AI embody?
|
||||
- Example: "Senior Go engineer with 10+ years in security-sensitive API design"
|
||||
|
||||
### 3. Task Specification
|
||||
- Primary task (explicit and measurable)
|
||||
- Secondary/optional tasks
|
||||
- What does the user provide as input? (`$ARGUMENTS`, selected code, file reference)
|
||||
- Constraints that must be followed
|
||||
|
||||
### 4. Context Requirements
|
||||
- Does it use `$ARGUMENTS` for user input?
|
||||
- Does it reference specific files in the codebase?
|
||||
- Does it need to read/write specific directories?
|
||||
|
||||
### 5. Instructions & Standards
|
||||
- Step-by-step process to follow
|
||||
- Specific coding standards, frameworks, or libraries
|
||||
- Patterns to enforce, things to avoid
|
||||
- Reference any existing `.github/instructions/` files?
|
||||
|
||||
### 6. Output Requirements
|
||||
- Format: code / markdown / structured report / file creation
|
||||
- If creating files: where and what naming convention?
|
||||
- Examples of ideal output (for few-shot learning)
|
||||
|
||||
### 7. Quality & Validation
|
||||
- How is success measured?
|
||||
- What validation steps to include?
|
||||
- Common failure modes to address?
|
||||
|
||||
## Template Generation
|
||||
|
||||
After gathering requirements, I will generate the complete file:
|
||||
|
||||
**For commands** (`.claude/commands/`):
|
||||
```md
|
||||
# [Command Title]
|
||||
|
||||
[Persona definition]
|
||||
|
||||
**Input**: $ARGUMENTS
|
||||
|
||||
## [Instructions Section]
|
||||
|
||||
[Step-by-step instructions]
|
||||
|
||||
## [Output Format]
|
||||
|
||||
[Expected structure]
|
||||
|
||||
## Constraints
|
||||
|
||||
- [Constraint 1]
|
||||
```
|
||||
|
||||
**For agents** (`.claude/agents/`):
|
||||
```md
|
||||
---
|
||||
name: agent-name
|
||||
description: [Routing description — how Claude Code decides to use this agent]
|
||||
---
|
||||
|
||||
[System prompt with persona, workflow, constraints]
|
||||
```
|
||||
|
||||
Please start by answering section 1 (Identity & Purpose). I'll guide you through each section systematically.
|
||||
@@ -1,79 +0,0 @@
|
||||
# Structured Autonomy — Generate
|
||||
|
||||
You are a PR implementation plan generator that creates complete, copy-paste ready implementation documentation.
|
||||
|
||||
**Plan to process**: $ARGUMENTS (or read from `plans/{feature-name}/plan.md`)
|
||||
|
||||
Your sole responsibility is to:
|
||||
1. Accept a complete plan from `plans/{feature-name}/plan.md`
|
||||
2. Extract all implementation steps
|
||||
3. Generate comprehensive step documentation with complete, ready-to-paste code
|
||||
4. Save to `plans/{feature-name}/implementation.md`
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Parse Plan & Research Codebase
|
||||
|
||||
1. Read the `plan.md` file to extract:
|
||||
- Feature name and branch (determines root folder)
|
||||
- Implementation steps (numbered 1, 2, 3, etc.)
|
||||
- Files affected by each step
|
||||
|
||||
2. Research the codebase comprehensively (ONE TIME):
|
||||
- Project type, tech stack, versions (Go 1.22+, React 18, TypeScript 5+)
|
||||
- Project structure and folder organisation
|
||||
- Coding conventions and naming patterns
|
||||
- Build/test/run commands
|
||||
- Existing code patterns, error handling, logging approaches
|
||||
- API conventions, state management patterns, testing strategies
|
||||
- Official docs for all major libraries used
|
||||
|
||||
### Step 2: Generate Implementation File
|
||||
|
||||
Output a COMPLETE markdown document. The plan MUST include:
|
||||
- Complete, copy-paste ready code blocks with ZERO modifications needed
|
||||
- Exact file paths appropriate to the Charon project structure
|
||||
- Markdown checkboxes for EVERY action item
|
||||
- Specific, observable, testable verification points
|
||||
- NO ambiguity — every instruction is concrete
|
||||
- NO "decide for yourself" moments — all decisions made based on research
|
||||
- Technology stack and dependencies explicitly stated
|
||||
- Build/test commands specific to this project
|
||||
|
||||
## Output Template
|
||||
|
||||
Save to `plans/{feature-name}/implementation.md`:
|
||||
|
||||
```md
|
||||
# {FEATURE_NAME}
|
||||
|
||||
## Goal
|
||||
{One sentence describing exactly what this implementation accomplishes}
|
||||
|
||||
## Prerequisites
|
||||
Make sure you are on the `{feature-name}` branch before beginning.
|
||||
If not, switch to it. If it doesn't exist, create it from main.
|
||||
|
||||
### Step-by-Step Instructions
|
||||
|
||||
#### Step 1: {Action}
|
||||
- [ ] {Specific instruction 1}
|
||||
- [ ] Copy and paste code below into `{file path}`:
|
||||
|
||||
```{language}
|
||||
{COMPLETE, TESTED CODE - NO PLACEHOLDERS - NO "TODO" COMMENTS}
|
||||
```
|
||||
|
||||
- [ ] {Specific instruction 2}
|
||||
|
||||
##### Step 1 Verification Checklist
|
||||
- [ ] `go build ./...` passes with no errors
|
||||
- [ ] `go test ./...` passes
|
||||
- [ ] {Specific UI or functional verification}
|
||||
|
||||
#### Step 1 STOP & COMMIT
|
||||
**STOP & COMMIT:** Stop here and wait for the user to test, stage, and commit the change.
|
||||
|
||||
#### Step 2: {Action}
|
||||
...
|
||||
```
|
||||
@@ -1,23 +0,0 @@
|
||||
# Structured Autonomy — Implement
|
||||
|
||||
You are an implementation agent responsible for carrying out an implementation plan without deviating from it.
|
||||
|
||||
**Implementation plan**: $ARGUMENTS
|
||||
|
||||
If no plan is provided, respond with: "Implementation plan is required. Run `/sa-generate` first, then pass the path to the implementation file."
|
||||
|
||||
## Workflow
|
||||
|
||||
- Follow the plan **exactly** as written, picking up with the next unchecked step in the implementation document. You MUST NOT skip any steps.
|
||||
- Implement ONLY what is specified in the plan. DO NOT write any code outside of what is specified.
|
||||
- Update the plan document inline as you complete each item in the current step, checking off items using standard markdown syntax (`- [x]`).
|
||||
- Complete every item in the current step.
|
||||
- Check your work by running the build or test commands specified in the plan.
|
||||
- **STOP** when you reach a `STOP & COMMIT` instruction and return control to the user.
|
||||
|
||||
## Constraints
|
||||
|
||||
- No improvisation — if the plan says X, do X
|
||||
- No skipping steps, even if they seem redundant
|
||||
- No adding features, refactoring, or "improvements" not in the plan
|
||||
- If you encounter an ambiguity, stop and ask for clarification before proceeding
|
||||
@@ -1,67 +0,0 @@
|
||||
# Structured Autonomy — Plan
|
||||
|
||||
You are a Project Planning Agent that collaborates with users to design development plans.
|
||||
|
||||
**Feature request**: $ARGUMENTS
|
||||
|
||||
A development plan defines a clear path to implement the user's request. During this step you will **not write any code**. Instead, you will research, analyse, and outline a plan.
|
||||
|
||||
Assume the entire plan will be implemented in a single pull request on a dedicated branch. Your job is to define the plan in steps that correspond to individual commits within that PR.
|
||||
|
||||
<workflow>
|
||||
|
||||
## Step 1: Research and Gather Context
|
||||
|
||||
Research the feature request comprehensively:
|
||||
|
||||
1. **Code Context**: Search for related features, existing patterns, affected services
|
||||
2. **Documentation**: Read existing feature docs, architecture decisions in codebase
|
||||
3. **Dependencies**: Research external APIs, libraries needed — read documentation first
|
||||
4. **Patterns**: Identify how similar features are implemented in Charon
|
||||
|
||||
Stop research at 80% confidence you can break down the feature into testable phases.
|
||||
|
||||
## Step 2: Determine Commits
|
||||
|
||||
Analyse the request and break it down into commits:
|
||||
|
||||
- For **SIMPLE** features: consolidate into 1 commit with all changes
|
||||
- For **COMPLEX** features: multiple commits, each a testable step toward the final goal
|
||||
|
||||
## Step 3: Plan Generation
|
||||
|
||||
1. Generate draft plan using the output template below, with `[NEEDS CLARIFICATION]` markers where user input is needed
|
||||
2. Save the plan to `plans/{feature-name}/plan.md`
|
||||
3. Ask clarifying questions for any `[NEEDS CLARIFICATION]` sections
|
||||
4. **MANDATORY**: Pause for feedback
|
||||
5. If feedback received, revise plan and repeat research as needed
|
||||
|
||||
</workflow>
|
||||
|
||||
## Output Template
|
||||
|
||||
**File:** `plans/{feature-name}/plan.md`
|
||||
|
||||
```md
|
||||
# {Feature Name}
|
||||
|
||||
**Branch:** `{kebab-case-branch-name}`
|
||||
**Description:** {One sentence describing what gets accomplished}
|
||||
|
||||
## Goal
|
||||
{1-2 sentences describing the feature and why it matters}
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### Step 1: {Step Name} [SIMPLE features have only this step]
|
||||
**Files:** {List affected files}
|
||||
**What:** {1-2 sentences describing the change}
|
||||
**Testing:** {How to verify this step works}
|
||||
|
||||
### Step 2: {Step Name} [COMPLEX features continue]
|
||||
**Files:** {affected files}
|
||||
**What:** {description}
|
||||
**Testing:** {verification method}
|
||||
```
|
||||
|
||||
Once approved, run `/sa-generate` to produce the full copy-paste implementation document.
|
||||
@@ -1,32 +0,0 @@
|
||||
# Security: CodeQL Scan
|
||||
|
||||
Run CodeQL static analysis for Go and JavaScript/TypeScript.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh security-scan-codeql
|
||||
```
|
||||
|
||||
## What It Scans
|
||||
|
||||
- **Go**: Backend code in `backend/` — injection, path traversal, auth issues, etc.
|
||||
- **JavaScript/TypeScript**: Frontend code in `frontend/` — XSS, injection, prototype pollution, etc.
|
||||
|
||||
## CI Alignment
|
||||
|
||||
Uses the same configuration as the CI `codeql.yml` workflow and `.github/codeql/codeql-config.yml`.
|
||||
|
||||
## On Findings
|
||||
|
||||
For each finding:
|
||||
1. Read the finding details — understand what code path is flagged
|
||||
2. Determine if it's a true positive or false positive
|
||||
3. Fix true positives immediately (these are real vulnerabilities)
|
||||
4. Document false positives with rationale in the CodeQL config
|
||||
|
||||
## Related
|
||||
|
||||
- `/security-scan-trivy` — Container and dependency scanning
|
||||
- `/security-scan-gorm` — GORM-specific SQL security scan
|
||||
- `/supply-chain-remediation` — Fix dependency vulnerabilities
|
||||
@@ -1,40 +0,0 @@
|
||||
# Security: Docker Image Scan
|
||||
|
||||
Run a comprehensive security scan of the built Charon Docker image using Syft/Grype.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh security-scan-docker-image
|
||||
```
|
||||
|
||||
## Why This Scan Is MANDATORY
|
||||
|
||||
This scan catches vulnerabilities that Trivy filesystem scan **misses**:
|
||||
- Alpine package CVEs in the base image
|
||||
- Compiled Go binary vulnerabilities
|
||||
- Embedded dependencies only present post-build
|
||||
- Multi-stage build artifacts with known issues
|
||||
|
||||
**Always run BOTH** Trivy (`/security-scan-trivy`) AND Docker image scan. Compare results — the image scan is the more comprehensive source of truth.
|
||||
|
||||
## CI Alignment
|
||||
|
||||
Uses the same Syft/Grype versions as the `supply-chain-pr.yml` CI workflow, ensuring local results match CI results.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The Docker image must be built first:
|
||||
```bash
|
||||
docker build -t charon:local .
|
||||
```
|
||||
|
||||
## On Findings
|
||||
|
||||
All CRITICAL and HIGH findings must be addressed. Use `/supply-chain-remediation` for the full remediation workflow.
|
||||
|
||||
## Related
|
||||
|
||||
- `/security-scan-trivy` — Filesystem scan (run first, then this)
|
||||
- `/security-scan-codeql` — Static analysis
|
||||
- `/supply-chain-remediation` — Fix vulnerabilities
|
||||
@@ -1,47 +0,0 @@
|
||||
# Security: Go Vulnerability Scan
|
||||
|
||||
Run `govulncheck` to detect known vulnerabilities in Go dependencies.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh security-scan-go-vuln
|
||||
```
|
||||
|
||||
## Direct Alternative
|
||||
|
||||
```bash
|
||||
cd backend && govulncheck ./...
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
`govulncheck` scans your Go module graph against the Go vulnerability database (vuln.go.dev). Unlike Trivy, it:
|
||||
- Only reports vulnerabilities in code paths that are **actually called** (not just imported)
|
||||
- Reduces false positives significantly
|
||||
- Is the authoritative source for Go-specific CVEs
|
||||
|
||||
## Install govulncheck
|
||||
|
||||
```bash
|
||||
go install golang.org/x/vuln/cmd/govulncheck@latest
|
||||
```
|
||||
|
||||
## On Findings
|
||||
|
||||
For each finding:
|
||||
1. Check if the vulnerable function is actually called in Charon's code
|
||||
2. If called: update the dependency immediately
|
||||
3. If not called: document why it's not a risk (govulncheck may still flag it)
|
||||
|
||||
Use `/supply-chain-remediation` for the full remediation workflow:
|
||||
```bash
|
||||
go get affected-package@fixed-version
|
||||
go mod tidy && go mod verify
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- `/security-scan-trivy` — Broader dependency and image scan
|
||||
- `/security-scan-docker-image` — Post-build image vulnerability scan
|
||||
- `/supply-chain-remediation` — Fix vulnerabilities
|
||||
@@ -1,44 +0,0 @@
|
||||
# Security: GORM Security Scan
|
||||
|
||||
Run the Charon GORM security scanner to detect SQL injection risks and unsafe GORM usage patterns.
|
||||
|
||||
## When to Run
|
||||
|
||||
**MANDATORY** when any of the following changed:
|
||||
- `backend/internal/models/**`
|
||||
- GORM service files
|
||||
- Database migration code
|
||||
- Any file with `.db.`, `.Where(`, `.Raw(`, or `.Exec(` calls
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh security-scan-gorm
|
||||
```
|
||||
|
||||
## Direct Alternative (Check Mode — Blocks on Findings)
|
||||
|
||||
```bash
|
||||
./scripts/scan-gorm-security.sh --check
|
||||
```
|
||||
|
||||
Check mode exits non-zero if any CRITICAL or HIGH findings are present. This is the mode used in the DoD gate.
|
||||
|
||||
## What It Detects
|
||||
|
||||
- Raw SQL with string concatenation (SQL injection risk)
|
||||
- Unparameterized dynamic queries
|
||||
- Missing input validation before DB operations
|
||||
- Unsafe use of `db.Exec()` with user input
|
||||
- Patterns that bypass GORM's built-in safety mechanisms
|
||||
|
||||
## On Findings
|
||||
|
||||
All CRITICAL and HIGH findings must be fixed before the task is considered done. Do not accept the task completion from any agent until this passes.
|
||||
|
||||
See `.github/skills/.skill-quickref-gorm-scanner.md` for remediation patterns.
|
||||
|
||||
## Related
|
||||
|
||||
- `/sql-code-review` — Manual SQL/GORM code review
|
||||
- `/security-scan-trivy` — Dependency vulnerability scan
|
||||
@@ -1,46 +0,0 @@
|
||||
# Security: Trivy Scan
|
||||
|
||||
Run Trivy filesystem scan for vulnerabilities in source code and dependencies.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh security-scan-trivy
|
||||
```
|
||||
|
||||
## What It Scans
|
||||
|
||||
- Go module dependencies (`go.mod`)
|
||||
- npm dependencies (`package.json`)
|
||||
- Dockerfile configuration
|
||||
- Source code files
|
||||
|
||||
## Important: Trivy vs Docker Image Scan
|
||||
|
||||
Trivy filesystem scan alone is **NOT sufficient**. Always also run the Docker image scan:
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh security-scan-docker-image
|
||||
```
|
||||
|
||||
The Docker image scan catches additional vulnerabilities:
|
||||
- Alpine package CVEs in base image
|
||||
- Compiled binary vulnerabilities
|
||||
- Multi-stage build artifacts
|
||||
- Embedded dependencies only present post-build
|
||||
|
||||
## On Findings
|
||||
|
||||
All CRITICAL and HIGH findings must be addressed. See `/supply-chain-remediation` for the full remediation workflow.
|
||||
|
||||
For accepted risks, add to `.trivyignore`:
|
||||
```yaml
|
||||
CVE-2025-XXXXX # Accepted: [reason why it doesn't apply]
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- `/security-scan-docker-image` — MANDATORY companion scan
|
||||
- `/security-scan-codeql` — Static analysis
|
||||
- `/security-scan-gorm` — GORM SQL security
|
||||
- `/supply-chain-remediation` — Fix vulnerabilities
|
||||
@@ -1,78 +0,0 @@
|
||||
# SQL Code Review
|
||||
|
||||
Perform a thorough SQL code review of the provided SQL/GORM code focusing on security, performance, maintainability, and database best practices.
|
||||
|
||||
**Code to review**: $ARGUMENTS (or selected code / current file if not specified)
|
||||
|
||||
## Security Analysis
|
||||
|
||||
### SQL Injection Prevention
|
||||
- All user inputs must use parameterized queries — never string concatenation
|
||||
- Verify GORM's raw query calls use `?` placeholders or named args, not `fmt.Sprintf`
|
||||
- Review access controls and principle of least privilege
|
||||
- Check for sensitive data exposure (avoid `SELECT *` on tables with sensitive columns)
|
||||
|
||||
### Access Control & Data Protection
|
||||
- Role-based access: use database roles instead of direct user permissions
|
||||
- Sensitive operations are audit-logged
|
||||
- Encrypted storage for sensitive data (passwords, tokens)
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Query Structure
|
||||
- Avoid `SELECT *` — use explicit column lists
|
||||
- Use appropriate JOIN types (INNER vs LEFT vs EXISTS)
|
||||
- Avoid functions in WHERE clauses that prevent index usage (e.g., `YEAR(date_col)`)
|
||||
- Use range conditions instead: `date_col >= '2024-01-01' AND date_col < '2025-01-01'`
|
||||
|
||||
### Index Strategy
|
||||
- Identify columns needing indexes (frequently queried in WHERE, JOIN, ORDER BY)
|
||||
- Composite indexes: correct column order matters
|
||||
- Avoid over-indexing (impacts INSERT/UPDATE performance)
|
||||
|
||||
### Common Anti-Patterns to Flag
|
||||
|
||||
```sql
|
||||
-- N+1 query problem: loop + individual queries → fix with JOIN
|
||||
-- Correlated subqueries → replace with window functions or JOIN
|
||||
-- DISTINCT masking join issues → fix the JOIN instead
|
||||
-- OFFSET pagination on large tables → use cursor-based pagination
|
||||
-- OR conditions preventing index use → consider UNION ALL
|
||||
```
|
||||
|
||||
## Code Quality
|
||||
|
||||
- Consistent naming conventions (snake_case for columns/tables)
|
||||
- No reserved words as identifiers
|
||||
- Appropriate data types (don't use TEXT for fixed-length values)
|
||||
- Constraints enforce data integrity (NOT NULL, FK, CHECK, DEFAULT)
|
||||
|
||||
## Output Format
|
||||
|
||||
For each issue found:
|
||||
|
||||
```
|
||||
## [PRIORITY] [CATEGORY]: [Brief Description]
|
||||
|
||||
**Location**: [Table/line/function]
|
||||
**Issue**: [Detailed explanation]
|
||||
**Security Risk**: [If applicable]
|
||||
**Performance Impact**: [If applicable]
|
||||
**Recommendation**: [Specific fix with code example]
|
||||
|
||||
Before:
|
||||
[problematic SQL]
|
||||
|
||||
After:
|
||||
[improved SQL]
|
||||
```
|
||||
|
||||
### Summary Assessment
|
||||
- **Security Score**: [1-10]
|
||||
- **Performance Score**: [1-10]
|
||||
- **Maintainability Score**: [1-10]
|
||||
|
||||
### Top 3 Priority Actions
|
||||
1. [Critical fix]
|
||||
2. [Performance improvement]
|
||||
3. [Code quality improvement]
|
||||
@@ -1,90 +0,0 @@
|
||||
# SQL Performance Optimization
|
||||
|
||||
Expert SQL performance optimization for the provided query or codebase.
|
||||
|
||||
**Query/code to optimize**: $ARGUMENTS (or selected code / current file if not specified)
|
||||
|
||||
## Core Optimization Areas
|
||||
|
||||
### 1. Query Performance Analysis
|
||||
|
||||
Common patterns to fix:
|
||||
|
||||
```sql
|
||||
-- BAD: Function in WHERE prevents index use
|
||||
WHERE YEAR(created_at) = 2024
|
||||
-- GOOD: Range condition
|
||||
WHERE created_at >= '2024-01-01' AND created_at < '2025-01-01'
|
||||
|
||||
-- BAD: Correlated subquery (runs once per row)
|
||||
WHERE price > (SELECT AVG(price) FROM products p2 WHERE p2.category_id = p.category_id)
|
||||
-- GOOD: Window function
|
||||
SELECT *, AVG(price) OVER (PARTITION BY category_id) FROM products
|
||||
|
||||
-- BAD: SELECT *
|
||||
SELECT * FROM large_table JOIN another_table ON ...
|
||||
-- GOOD: Explicit columns
|
||||
SELECT lt.id, lt.name, at.value FROM ...
|
||||
|
||||
-- BAD: OFFSET pagination (slow at large offsets)
|
||||
SELECT * FROM products ORDER BY created_at DESC LIMIT 20 OFFSET 10000
|
||||
-- GOOD: Cursor-based pagination
|
||||
SELECT * FROM products WHERE created_at < ? ORDER BY created_at DESC LIMIT 20
|
||||
|
||||
-- BAD: Multiple aggregation queries
|
||||
SELECT COUNT(*) FROM orders WHERE status = 'pending';
|
||||
SELECT COUNT(*) FROM orders WHERE status = 'shipped';
|
||||
-- GOOD: Single conditional aggregation
|
||||
SELECT COUNT(CASE WHEN status = 'pending' THEN 1 END) as pending,
|
||||
COUNT(CASE WHEN status = 'shipped' THEN 1 END) as shipped
|
||||
FROM orders;
|
||||
```
|
||||
|
||||
### 2. Index Strategy
|
||||
|
||||
- **Missing indexes**: Identify unindexed columns in WHERE, JOIN ON, ORDER BY
|
||||
- **Composite index column order**: Most selective column first (unless query pattern dictates otherwise)
|
||||
- **Covering indexes**: Include all columns needed to satisfy query without table lookup
|
||||
- **Partial indexes**: Index only rows matching a WHERE condition (e.g., `WHERE status = 'active'`)
|
||||
- **Over-indexing**: Remove unused indexes (every index slows INSERT/UPDATE/DELETE)
|
||||
|
||||
### 3. JOIN Optimization
|
||||
|
||||
- Filter early using INNER JOIN instead of LEFT JOIN + WHERE IS NOT NULL
|
||||
- Smallest result set as the driving table
|
||||
- Eliminate Cartesian products (missing join conditions)
|
||||
- Use EXISTS over IN for subqueries when checking for existence
|
||||
|
||||
### 4. Batch Operations
|
||||
|
||||
```sql
|
||||
-- BAD: Row-by-row inserts
|
||||
INSERT INTO products (name) VALUES ('A');
|
||||
INSERT INTO products (name) VALUES ('B');
|
||||
-- GOOD: Batch insert
|
||||
INSERT INTO products (name) VALUES ('A'), ('B'), ('C');
|
||||
```
|
||||
|
||||
## GORM-Specific Notes (Go)
|
||||
|
||||
- Use `db.Select([]string{"id", "name"})` — never `db.Find(&result)` on large tables
|
||||
- Use `db.Where("status = ?", status)` — parameterized always
|
||||
- For complex aggregations, prefer raw SQL with `db.Raw()` + named args
|
||||
- Use `db.FindInBatches()` for large dataset iteration
|
||||
|
||||
## Output Format
|
||||
|
||||
For each optimization:
|
||||
1. **Problem**: What's slow/inefficient and why
|
||||
2. **Before**: Current code
|
||||
3. **After**: Optimized code
|
||||
4. **Index recommendation**: SQL CREATE INDEX statement if needed
|
||||
5. **Expected improvement**: Estimated performance gain
|
||||
|
||||
## Optimization Methodology
|
||||
|
||||
1. **Identify**: Slowest queries by execution time or call frequency
|
||||
2. **Analyze**: Check execution plans (use `EXPLAIN` / `EXPLAIN ANALYZE`)
|
||||
3. **Optimize**: Apply appropriate technique
|
||||
4. **Test**: Verify improvement with realistic data volumes
|
||||
5. **Monitor**: Track performance metrics over time
|
||||
@@ -1,85 +0,0 @@
|
||||
# Supply Chain Vulnerability Remediation
|
||||
|
||||
Analyze vulnerability scan results, research each CVE, assess actual risk, and provide concrete remediation steps.
|
||||
|
||||
**Input**: $ARGUMENTS — provide ONE of:
|
||||
1. PR comment (copy/paste from supply chain security bot)
|
||||
2. GitHub Actions workflow run link
|
||||
3. Raw Trivy/Grype scan output
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
### Phase 1: Parse & Triage
|
||||
|
||||
Extract: CVE identifiers, affected packages + current versions, severity levels, fixed versions, package ecosystem.
|
||||
|
||||
Structure findings:
|
||||
```
|
||||
CRITICAL: CVE-2025-XXXXX: golang.org/x/net 1.22.0 → 1.25.5 (Buffer overflow)
|
||||
HIGH: CVE-2025-XXXXX: alpine-baselayout 3.4.0 → 3.4.3 (Privilege escalation)
|
||||
```
|
||||
|
||||
Map to project files: Go → `go.mod` | npm → `package.json` | Alpine → `Dockerfile`
|
||||
|
||||
### Phase 2: Research & Risk Assessment
|
||||
|
||||
For each CVE (Critical → High → Medium → Low):
|
||||
1. Research CVE details: attack vector, CVSS score, exploitability, PoC availability
|
||||
2. Impact analysis: Is the vulnerable code path actually used? What's the attack surface?
|
||||
3. Assign project-specific risk:
|
||||
- `CRITICAL-IMMEDIATE`: Exploitable, affects exposed services, no mitigations
|
||||
- `HIGH-URGENT`: Exploitable, limited exposure or partial mitigations
|
||||
- `MEDIUM-PLANNED`: Low exploitability or strong compensating controls
|
||||
- `ACCEPT`: No actual risk to this application (unused code path)
|
||||
|
||||
### Phase 3: Remediation
|
||||
|
||||
**Go modules**:
|
||||
```bash
|
||||
go get golang.org/x/net@v1.25.5
|
||||
go mod tidy && go mod verify
|
||||
govulncheck ./...
|
||||
```
|
||||
|
||||
**npm packages**:
|
||||
```bash
|
||||
npm update package-name@version
|
||||
npm audit fix && npm audit
|
||||
```
|
||||
|
||||
**Alpine in Dockerfile**:
|
||||
```dockerfile
|
||||
FROM golang:1.25.5-alpine3.19 AS builder
|
||||
RUN apk upgrade --no-cache affected-package
|
||||
```
|
||||
|
||||
**Acceptance** (when vulnerability doesn't apply):
|
||||
```yaml
|
||||
# .trivyignore
|
||||
CVE-2025-XXXXX # Risk accepted: Not using vulnerable code path — [explanation]
|
||||
```
|
||||
|
||||
### Phase 4: Validation
|
||||
|
||||
1. `go test ./...` — full test suite passes
|
||||
2. `cd frontend && npm test` — frontend tests pass
|
||||
3. Re-run scan: `.github/skills/scripts/skill-runner.sh security-scan-go-vuln`
|
||||
4. Re-run Docker image scan: `.github/skills/scripts/skill-runner.sh security-scan-docker-image`
|
||||
|
||||
### Phase 5: Documentation
|
||||
|
||||
Save report to `docs/security/vulnerability-analysis-[DATE].md` with:
|
||||
- Executive summary (total found, fixed, mitigated, accepted)
|
||||
- Per-CVE analysis with impact assessment
|
||||
- Remediation actions with rationale
|
||||
- Validation results
|
||||
|
||||
Update `SECURITY.md` and `CHANGELOG.md`.
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Zero tolerance for Critical** without documented risk acceptance
|
||||
- **Do NOT update major versions** without checking for breaking changes
|
||||
- **Do NOT suppress warnings** without thorough analysis
|
||||
- **Do NOT relax scan thresholds** to bypass checks
|
||||
- All changes must pass the full test suite before being considered complete
|
||||
@@ -1,41 +0,0 @@
|
||||
# Test: Backend Coverage
|
||||
|
||||
Run backend Go tests with coverage reporting. Minimum threshold: 85%.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh test-backend-coverage
|
||||
```
|
||||
|
||||
## Direct Alternative
|
||||
|
||||
```bash
|
||||
bash scripts/go-test-coverage.sh
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
1. Runs all Go tests with `-coverprofile`
|
||||
2. Generates HTML coverage report
|
||||
3. Checks against minimum threshold (`CHARON_MIN_COVERAGE=85`)
|
||||
4. Fails if below threshold
|
||||
|
||||
## View Coverage Report
|
||||
|
||||
```bash
|
||||
cd backend && go tool cover -html=coverage.out
|
||||
```
|
||||
|
||||
## Fix Coverage Gaps
|
||||
|
||||
If coverage is below 85%:
|
||||
1. Run `/codecov-patch-fix` to identify uncovered lines
|
||||
2. Write targeted tests for error paths and edge cases
|
||||
3. Re-run coverage to verify
|
||||
|
||||
## Related
|
||||
|
||||
- `/test-backend-unit` — Run tests without coverage
|
||||
- `/test-frontend-coverage` — Frontend coverage (also 85% minimum)
|
||||
- `/codecov-patch-fix` — Fix specific coverage gaps
|
||||
@@ -1,33 +0,0 @@
|
||||
# Test: Backend Unit Tests
|
||||
|
||||
Run backend Go unit tests.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh test-backend-unit
|
||||
```
|
||||
|
||||
## Direct Alternative
|
||||
|
||||
```bash
|
||||
cd backend && go test ./...
|
||||
```
|
||||
|
||||
## Targeted Testing
|
||||
|
||||
```bash
|
||||
# Single package
|
||||
cd backend && go test ./internal/api/handlers/...
|
||||
|
||||
# Single test function
|
||||
cd backend && go test ./... -run TestFunctionName -v
|
||||
|
||||
# With race detector
|
||||
cd backend && go test -race ./...
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- `/test-backend-coverage` — Run with coverage report (minimum 85%)
|
||||
- `/test-frontend-unit` — Frontend unit tests
|
||||
@@ -1,61 +0,0 @@
|
||||
# Test: E2E Playwright Tests
|
||||
|
||||
Run Charon end-to-end tests with Playwright.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh test-e2e-playwright
|
||||
```
|
||||
|
||||
## Direct Alternative (Recommended for local runs)
|
||||
|
||||
```bash
|
||||
cd /projects/Charon && npx playwright test --project=firefox
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The E2E container must be running and healthy. Rebuild if application code changed:
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e
|
||||
```
|
||||
|
||||
## Targeted Testing
|
||||
|
||||
```bash
|
||||
# Specific test file
|
||||
npx playwright test tests/proxy-hosts.spec.ts --project=firefox
|
||||
|
||||
# Specific test by name
|
||||
npx playwright test --grep "user can create proxy host" --project=firefox
|
||||
|
||||
# All browsers (for full CI parity)
|
||||
npx playwright test --project=chromium --project=firefox --project=webkit
|
||||
|
||||
# Debug mode (headed browser)
|
||||
npx playwright test --project=firefox --headed --debug
|
||||
```
|
||||
|
||||
## CRITICAL: Never Truncate Output
|
||||
|
||||
**NEVER** pipe Playwright output through `head`, `tail`, or other truncating commands. Playwright requires user input to quit when piped, causing hangs.
|
||||
|
||||
## View Report
|
||||
|
||||
```bash
|
||||
npx playwright show-report
|
||||
```
|
||||
|
||||
## On Failure
|
||||
|
||||
1. Capture **full** output — never truncate
|
||||
2. Use EARS methodology for structured failure analysis
|
||||
3. Check if a code bug needs fixing (delegate to `backend-dev` or `frontend-dev` agents)
|
||||
4. Fix root cause — do NOT skip or delete the failing test
|
||||
|
||||
## Related
|
||||
|
||||
- `/docker-rebuild-e2e` — Rebuild E2E container
|
||||
- `/playwright-generate-test` — Generate new Playwright tests
|
||||
@@ -1,42 +0,0 @@
|
||||
# Test: Frontend Coverage
|
||||
|
||||
Run frontend tests with coverage reporting. Minimum threshold: 85%.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh test-frontend-coverage
|
||||
```
|
||||
|
||||
## Direct Alternative
|
||||
|
||||
```bash
|
||||
bash scripts/frontend-test-coverage.sh
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
1. Runs all Vitest tests with V8 coverage provider
|
||||
2. Generates HTML + JSON coverage reports
|
||||
3. Checks against minimum threshold (85%)
|
||||
4. Fails if below threshold
|
||||
|
||||
## View Coverage Report
|
||||
|
||||
```bash
|
||||
cd frontend && npx vite preview --outDir coverage
|
||||
# Or open coverage/index.html in browser
|
||||
```
|
||||
|
||||
## Fix Coverage Gaps
|
||||
|
||||
If coverage is below 85%:
|
||||
1. Run `/codecov-patch-fix` to identify uncovered lines
|
||||
2. Write targeted tests with Testing Library
|
||||
3. Re-run coverage to verify
|
||||
|
||||
## Related
|
||||
|
||||
- `/test-frontend-unit` — Run tests without coverage
|
||||
- `/test-backend-coverage` — Backend coverage (also 85% minimum)
|
||||
- `/codecov-patch-fix` — Fix specific coverage gaps
|
||||
@@ -1,33 +0,0 @@
|
||||
# Test: Frontend Unit Tests
|
||||
|
||||
Run frontend TypeScript/React unit tests with Vitest.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh test-frontend-unit
|
||||
```
|
||||
|
||||
## Direct Alternative
|
||||
|
||||
```bash
|
||||
cd frontend && npm test
|
||||
```
|
||||
|
||||
## Targeted Testing
|
||||
|
||||
```bash
|
||||
# Single file
|
||||
cd frontend && npm test -- src/components/MyComponent.test.tsx
|
||||
|
||||
# Watch mode (re-runs on file changes)
|
||||
cd frontend && npm test -- --watch
|
||||
|
||||
# With verbose output
|
||||
cd frontend && npm test -- --reporter=verbose
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- `/test-frontend-coverage` — Run with coverage report (minimum 85%)
|
||||
- `/test-backend-unit` — Backend unit tests
|
||||
@@ -1,38 +0,0 @@
|
||||
# Update Implementation Plan
|
||||
|
||||
Update the implementation plan file at: **$ARGUMENTS**
|
||||
|
||||
Based on new or updated requirements, revise the plan to reflect the current state. Your output must be machine-readable, deterministic, and structured for autonomous execution.
|
||||
|
||||
## Core Requirements
|
||||
|
||||
- Preserve the existing plan structure and template format
|
||||
- Update only sections affected by the new requirements
|
||||
- Use deterministic language with zero ambiguity
|
||||
- Maintain all required front matter fields
|
||||
|
||||
## Update Process
|
||||
|
||||
1. **Read the current plan** to understand existing structure, goals, and tasks
|
||||
2. **Identify changes** — what requirements are new or changed?
|
||||
3. **Update affected sections**:
|
||||
- Front matter: `last_updated`, `status`
|
||||
- Requirements section: add new REQ/SEC/CON identifiers
|
||||
- Implementation steps: add/modify phases and tasks
|
||||
- Files, Testing, Risks sections as needed
|
||||
4. **Preserve completed tasks** — do not remove or reorder TASK items that are already checked
|
||||
5. **Validate template compliance** before finalising
|
||||
|
||||
## Template Validation Rules
|
||||
|
||||
- All front matter fields must be present and properly formatted
|
||||
- All section headers must match exactly (case-sensitive)
|
||||
- All identifier prefixes must follow the specified format (REQ-, TASK-, SEC-, etc.)
|
||||
- Tables must include all required columns
|
||||
- No placeholder text may remain in the final output
|
||||
|
||||
## Status Values
|
||||
|
||||
`Completed` | `In progress` | `Planned` | `Deprecated` | `On Hold`
|
||||
|
||||
Update `status` in both the front matter AND the badge in the Introduction section to reflect the current state.
|
||||
@@ -1,34 +0,0 @@
|
||||
{
|
||||
"defaultMode": "acceptEdits",
|
||||
"thinkingMode": "always",
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Edit",
|
||||
"MultiEdit",
|
||||
"Bash(npm run *)",
|
||||
"Bash(npx *)",
|
||||
"Bash(go *)",
|
||||
"Bash(node *)",
|
||||
"Bash(docker *)",
|
||||
"Bash(git diff *)",
|
||||
"Bash(git log *)",
|
||||
"Bash(git status)",
|
||||
"Bash(git add *)",
|
||||
"Bash(git commit *)",
|
||||
"Bash(git checkout *)",
|
||||
"Bash(git branch *)",
|
||||
"Bash(cat *)",
|
||||
"Bash(ls *)",
|
||||
"Bash(find *)",
|
||||
"Bash(grep *)",
|
||||
"Bash(mkdir *)"
|
||||
],
|
||||
"deny": [
|
||||
"Bash(rm -rf *)",
|
||||
"Bash(sudo *)",
|
||||
"Bash(git push *)",
|
||||
"Read(**/.env)",
|
||||
"Read(**/.env.*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
10
.github/agents/Management.agent.md
vendored
10
.github/agents/Management.agent.md
vendored
@@ -24,12 +24,12 @@ You are "lazy" in the smartest way possible. You never do what a subordinate can
|
||||
4. **Team Roster**:
|
||||
- `Planning`: The Architect. (Delegate research & planning here).
|
||||
- `Supervisor`: The Senior Advisor. (Delegate plan review here).
|
||||
- `Backend_Dev`: The Engineer. (Delegate Go implementation here).
|
||||
- `Frontend_Dev`: The Designer. (Delegate React implementation here).
|
||||
- `QA_Security`: The Auditor. (Delegate verification and testing here).
|
||||
- `Docs_Writer`: The Scribe. (Delegate docs here).
|
||||
- `Backend Dev`: The Engineer. (Delegate Go implementation here).
|
||||
- `Frontend Dev`: The Designer. (Delegate React implementation here).
|
||||
- `QA Security`: The Auditor. (Delegate verification and testing here).
|
||||
- `Docs Writer`: The Scribe. (Delegate docs here).
|
||||
- `DevOps`: The Packager. (Delegate CI/CD and infrastructure here).
|
||||
- `Playwright_Dev`: The E2E Specialist. (Delegate Playwright test creation and maintenance here).
|
||||
- `Playwright Dev`: The E2E Specialist. (Delegate Playwright test creation and maintenance here).
|
||||
5. **Parallel Execution**:
|
||||
- You may delegate to `runSubagent` multiple times in parallel if tasks are independent. The only exception is `QA_Security`, which must run last as this validates the entire codebase after all changes.
|
||||
6. **Implementation Choices**:
|
||||
|
||||
@@ -35,7 +35,7 @@ fi
|
||||
# Check Grype
|
||||
if ! command -v grype >/dev/null 2>&1; then
|
||||
log_error "Grype not found - install from: https://github.com/anchore/grype"
|
||||
log_error "Installation: curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin v0.107.0"
|
||||
log_error "Installation: curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin v0.109.1"
|
||||
error_exit "Grype is required for vulnerability scanning" 2
|
||||
fi
|
||||
|
||||
@@ -50,8 +50,8 @@ SYFT_INSTALLED_VERSION=$(syft version | grep -oP 'Version:\s*\Kv?[0-9]+\.[0-9]+\
|
||||
GRYPE_INSTALLED_VERSION=$(grype version | grep -oP 'Version:\s*\Kv?[0-9]+\.[0-9]+\.[0-9]+' | head -1 || echo "unknown")
|
||||
|
||||
# Set defaults matching CI workflow
|
||||
set_default_env "SYFT_VERSION" "v1.17.0"
|
||||
set_default_env "GRYPE_VERSION" "v0.107.0"
|
||||
set_default_env "SYFT_VERSION" "v1.42.2"
|
||||
set_default_env "GRYPE_VERSION" "v0.109.1"
|
||||
set_default_env "IMAGE_TAG" "charon:local"
|
||||
set_default_env "FAIL_ON_SEVERITY" "Critical,High"
|
||||
|
||||
|
||||
2
.github/workflows/container-prune.yml
vendored
2
.github/workflows/container-prune.yml
vendored
@@ -172,7 +172,7 @@ jobs:
|
||||
if: always()
|
||||
steps:
|
||||
- name: Download all artifacts
|
||||
uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
|
||||
with:
|
||||
pattern: prune-*-log-${{ github.run_id }}
|
||||
merge-multiple: true
|
||||
|
||||
4
.github/workflows/docker-build.yml
vendored
4
.github/workflows/docker-build.yml
vendored
@@ -574,7 +574,7 @@ jobs:
|
||||
# Generate SBOM (Software Bill of Materials) for supply chain security
|
||||
# Only for production builds (main/development) - feature branches use downstream supply-chain-pr.yml
|
||||
- name: Generate SBOM
|
||||
uses: anchore/sbom-action@17ae1740179002c89186b61233e0f892c3118b11 # v0.23.0
|
||||
uses: anchore/sbom-action@57aae528053a48a3f6235f2d9461b05fbcb7366d # v0.23.1
|
||||
if: env.TRIGGER_EVENT != 'pull_request' && steps.skip.outputs.skip_build != 'true' && steps.skip.outputs.is_feature_push != 'true'
|
||||
with:
|
||||
image: ${{ env.GHCR_REGISTRY }}/${{ env.IMAGE_NAME }}@${{ steps.build-and-push.outputs.digest }}
|
||||
@@ -594,7 +594,7 @@ jobs:
|
||||
# Install Cosign for keyless signing
|
||||
- name: Install Cosign
|
||||
if: env.TRIGGER_EVENT != 'pull_request' && steps.skip.outputs.skip_build != 'true' && steps.skip.outputs.is_feature_push != 'true'
|
||||
uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0
|
||||
uses: sigstore/cosign-installer@ba7bc0a3fef59531c69a25acd34668d6d3fe6f22 # v4.1.0
|
||||
|
||||
# Sign GHCR image with keyless signing (Sigstore/Fulcio)
|
||||
- name: Sign GHCR Image
|
||||
|
||||
12
.github/workflows/e2e-tests-split.yml
vendored
12
.github/workflows/e2e-tests-split.yml
vendored
@@ -248,7 +248,7 @@ jobs:
|
||||
|
||||
- name: Download Docker image artifact
|
||||
if: needs.build.outputs.image_source == 'build'
|
||||
uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
|
||||
with:
|
||||
name: docker-image
|
||||
|
||||
@@ -450,7 +450,7 @@ jobs:
|
||||
|
||||
- name: Download Docker image artifact
|
||||
if: needs.build.outputs.image_source == 'build'
|
||||
uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
|
||||
with:
|
||||
name: docker-image
|
||||
|
||||
@@ -660,7 +660,7 @@ jobs:
|
||||
|
||||
- name: Download Docker image artifact
|
||||
if: needs.build.outputs.image_source == 'build'
|
||||
uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
|
||||
with:
|
||||
name: docker-image
|
||||
|
||||
@@ -914,7 +914,7 @@ jobs:
|
||||
|
||||
- name: Download Docker image artifact
|
||||
if: needs.build.outputs.image_source == 'build'
|
||||
uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
|
||||
with:
|
||||
name: docker-image
|
||||
|
||||
@@ -1151,7 +1151,7 @@ jobs:
|
||||
|
||||
- name: Download Docker image artifact
|
||||
if: needs.build.outputs.image_source == 'build'
|
||||
uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
|
||||
with:
|
||||
name: docker-image
|
||||
|
||||
@@ -1396,7 +1396,7 @@ jobs:
|
||||
|
||||
- name: Download Docker image artifact
|
||||
if: needs.build.outputs.image_source == 'build'
|
||||
uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
|
||||
with:
|
||||
name: docker-image
|
||||
|
||||
|
||||
8
.github/workflows/nightly-build.yml
vendored
8
.github/workflows/nightly-build.yml
vendored
@@ -263,7 +263,7 @@ jobs:
|
||||
- name: Generate SBOM
|
||||
id: sbom_primary
|
||||
continue-on-error: true
|
||||
uses: anchore/sbom-action@17ae1740179002c89186b61233e0f892c3118b11 # v0.23.0
|
||||
uses: anchore/sbom-action@57aae528053a48a3f6235f2d9461b05fbcb7366d # v0.23.1
|
||||
with:
|
||||
image: ${{ env.GHCR_REGISTRY }}/${{ env.IMAGE_NAME }}@${{ steps.resolve_digest.outputs.digest }}
|
||||
format: cyclonedx-json
|
||||
@@ -282,7 +282,7 @@ jobs:
|
||||
|
||||
echo "Primary SBOM generation failed or produced missing/invalid output; using deterministic Syft fallback"
|
||||
|
||||
SYFT_VERSION="v1.42.1"
|
||||
SYFT_VERSION="v1.42.2"
|
||||
OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
|
||||
ARCH="$(uname -m)"
|
||||
case "$ARCH" in
|
||||
@@ -333,7 +333,7 @@ jobs:
|
||||
|
||||
# Install Cosign for keyless signing
|
||||
- name: Install Cosign
|
||||
uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0
|
||||
uses: sigstore/cosign-installer@ba7bc0a3fef59531c69a25acd34668d6d3fe6f22 # v4.1.0
|
||||
|
||||
# Sign GHCR image with keyless signing (Sigstore/Fulcio)
|
||||
- name: Sign GHCR Image
|
||||
@@ -430,7 +430,7 @@ jobs:
|
||||
run: echo "IMAGE_NAME_LC=${IMAGE_NAME,,}" >> "$GITHUB_ENV"
|
||||
|
||||
- name: Download SBOM
|
||||
uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
|
||||
with:
|
||||
name: sbom-nightly
|
||||
|
||||
|
||||
2
.github/workflows/renovate.yml
vendored
2
.github/workflows/renovate.yml
vendored
@@ -25,7 +25,7 @@ jobs:
|
||||
fetch-depth: 1
|
||||
|
||||
- name: Run Renovate
|
||||
uses: renovatebot/github-action@7b4b65bf31e07d4e3e51708d07700fb41bc03166 # v46.1.3
|
||||
uses: renovatebot/github-action@0b17c4eb901eca44d018fb25744a50a74b2042df # v46.1.4
|
||||
with:
|
||||
configurationFile: .github/renovate.json
|
||||
token: ${{ secrets.RENOVATE_TOKEN || secrets.GITHUB_TOKEN }}
|
||||
|
||||
4
.github/workflows/security-pr.yml
vendored
4
.github/workflows/security-pr.yml
vendored
@@ -240,7 +240,7 @@ jobs:
|
||||
- name: Download PR image artifact
|
||||
if: github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'
|
||||
# actions/download-artifact v4.1.8
|
||||
uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
|
||||
with:
|
||||
name: ${{ steps.check-artifact.outputs.artifact_name }}
|
||||
run-id: ${{ steps.check-artifact.outputs.run_id }}
|
||||
@@ -385,7 +385,7 @@ jobs:
|
||||
- name: Upload Trivy SARIF to GitHub Security
|
||||
if: always() && steps.trivy-sarif-check.outputs.exists == 'true'
|
||||
# github/codeql-action v4
|
||||
uses: github/codeql-action/upload-sarif@d1a65275e8dac7b2cc72bb121bf58f0ee7b0f92d
|
||||
uses: github/codeql-action/upload-sarif@1a97b0f94ec9297d6f58aefe5a6b5441c045bed4
|
||||
with:
|
||||
sarif_file: 'trivy-binary-results.sarif'
|
||||
category: ${{ steps.pr-info.outputs.is_push == 'true' && format('security-scan-{0}', github.event_name == 'workflow_run' && github.event.workflow_run.head_branch || github.ref_name) || format('security-scan-pr-{0}', steps.pr-info.outputs.pr_number) }}
|
||||
|
||||
4
.github/workflows/supply-chain-pr.yml
vendored
4
.github/workflows/supply-chain-pr.yml
vendored
@@ -266,7 +266,7 @@ jobs:
|
||||
# Generate SBOM using official Anchore action (auto-updated by Renovate)
|
||||
- name: Generate SBOM
|
||||
if: steps.set-target.outputs.image_name != ''
|
||||
uses: anchore/sbom-action@17ae1740179002c89186b61233e0f892c3118b11 # v0.23.0
|
||||
uses: anchore/sbom-action@57aae528053a48a3f6235f2d9461b05fbcb7366d # v0.23.1
|
||||
id: sbom
|
||||
with:
|
||||
image: ${{ steps.set-target.outputs.image_name }}
|
||||
@@ -285,7 +285,7 @@ jobs:
|
||||
- name: Install Grype
|
||||
if: steps.set-target.outputs.image_name != ''
|
||||
run: |
|
||||
curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin v0.107.1
|
||||
curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin v0.109.1
|
||||
|
||||
- name: Scan for vulnerabilities
|
||||
if: steps.set-target.outputs.image_name != ''
|
||||
|
||||
2
.github/workflows/supply-chain-verify.yml
vendored
2
.github/workflows/supply-chain-verify.yml
vendored
@@ -119,7 +119,7 @@ jobs:
|
||||
# Generate SBOM using official Anchore action (auto-updated by Renovate)
|
||||
- name: Generate and Verify SBOM
|
||||
if: steps.image-check.outputs.exists == 'true'
|
||||
uses: anchore/sbom-action@17ae1740179002c89186b61233e0f892c3118b11 # v0.23.0
|
||||
uses: anchore/sbom-action@57aae528053a48a3f6235f2d9461b05fbcb7366d # v0.23.1
|
||||
with:
|
||||
image: ghcr.io/${{ github.repository_owner }}/charon:${{ steps.tag.outputs.tag }}
|
||||
format: cyclonedx-json
|
||||
|
||||
204
CLAUDE.md
204
CLAUDE.md
@@ -1,204 +0,0 @@
|
||||
# Charon — Claude Code Instructions
|
||||
|
||||
> **Governance Precedence** (highest → lowest)
|
||||
> 1. `.github/instructions/**` files — canonical source of truth
|
||||
> 2. `.claude/agents/**` files — agent-specific overrides
|
||||
> 3. `SECURITY.md`, `docs/security.md`, `docs/features/**` — operator docs
|
||||
|
||||
When conflicts arise, the stricter security requirement always wins. Update downstream docs to match canonical text.
|
||||
|
||||
---
|
||||
|
||||
## Project Overview
|
||||
|
||||
Charon is a self-hosted web app for managing reverse proxy host configurations, aimed at novice users. Everything prioritises simplicity, usability, reliability, and security — delivered as a single binary + static assets with no external dependencies.
|
||||
|
||||
- **Backend**: `backend/cmd/api` → loads config, opens SQLite, hands off to `internal/server`
|
||||
- **Frontend**: React app built to `frontend/dist`, mounted via `attachFrontend`
|
||||
- **Config**: `internal/config` respects `CHARON_ENV`, `CHARON_HTTP_PORT`, `CHARON_DB_PATH`; creates `data/`
|
||||
- **Models**: Persistent types in `internal/models`; GORM auto-migrates them
|
||||
|
||||
---
|
||||
|
||||
## Code Quality Rules
|
||||
|
||||
Every session should improve the codebase, not just add to it.
|
||||
|
||||
- **MANDATORY**: Before starting any task, read relevant files in `.github/instructions/` for that domain
|
||||
- **ARCHITECTURE**: Consult `ARCHITECTURE.md` before changing core components, data flow, tech stack, deployment config, or directory structure
|
||||
- **DRY**: Consolidate duplicate patterns into reusable functions/types after the second occurrence
|
||||
- **CLEAN**: Delete dead code immediately — unused imports, variables, functions, commented blocks, console logs
|
||||
- **LEVERAGE**: Use battle-tested packages over custom implementations
|
||||
- **READABLE**: Maintain comments and clear naming for complex logic
|
||||
- **CONVENTIONAL COMMITS**: Use `feat:`, `fix:`, `chore:`, `refactor:`, or `docs:` prefixes
|
||||
|
||||
---
|
||||
|
||||
## Critical Architecture Rules
|
||||
|
||||
- **Single Frontend Source**: All frontend code MUST reside in `frontend/`. NEVER create `backend/frontend/` or nested directories
|
||||
- **Single Backend Source**: All backend code MUST reside in `backend/`
|
||||
- **No Python**: Go (Backend) + React/TypeScript (Frontend) only
|
||||
|
||||
---
|
||||
|
||||
## Root Cause Analysis Protocol (MANDATORY)
|
||||
|
||||
**Never patch a symptom without tracing the root cause.**
|
||||
|
||||
Before any code change, build a mental map of the feature:
|
||||
1. **Entry Point** — Where does the data enter? (API Route / UI Event)
|
||||
2. **Transformation** — How is data modified? (Handlers / Middleware)
|
||||
3. **Persistence** — Where is it stored? (DB Models / Files)
|
||||
4. **Exit Point** — How is it returned to the user?
|
||||
|
||||
The error log is often the *victim*, not the *cause*. Search upstream callers to find the origin.
|
||||
|
||||
---
|
||||
|
||||
## Backend Workflow
|
||||
|
||||
- **Run**: `cd backend && go run ./cmd/api`
|
||||
- **Test**: `go test ./...`
|
||||
- **Lint (BLOCKING)**: `make lint-fast` or `make lint-staticcheck-only` — staticcheck errors block commits
|
||||
- **Full lint** (before PR): `make lint-backend`
|
||||
- **API Responses**: `gin.H{"error": "message"}` structured errors
|
||||
- **JSON Tags**: All struct fields exposed to frontend MUST have `json:"snake_case"` tags
|
||||
- **IDs**: UUIDs (`github.com/google/uuid`), generated server-side
|
||||
- **Error wrapping**: `fmt.Errorf("context: %w", err)`
|
||||
- **File paths**: Sanitise with `filepath.Clean`
|
||||
|
||||
---
|
||||
|
||||
## Frontend Workflow
|
||||
|
||||
- **Location**: Always work inside `frontend/`
|
||||
- **Stack**: React 18 + Vite + TypeScript + TanStack Query
|
||||
- **State**: `src/hooks/use*.ts` wrapping React Query
|
||||
- **API Layer**: Typed clients in `src/api/*.ts` wrapping `client.ts`
|
||||
- **Forms**: Local `useState` → `useMutation` → `invalidateQueries` on success
|
||||
|
||||
---
|
||||
|
||||
## Cross-Cutting Notes
|
||||
|
||||
- **VS Code**: Register new repetitive CLI actions in `.vscode/tasks.json`
|
||||
- **Sync**: React Query expects exact JSON from GORM tags (snake_case) — keep API and UI aligned
|
||||
- **Migrations**: When adding models, update `internal/models` AND `internal/api/routes/routes.go` (AutoMigrate)
|
||||
- **Testing**: All new code MUST include unit tests
|
||||
- **Ignore files**: Check `.gitignore`, `.dockerignore`, `.codecov.yml` when adding files/folders
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
Update `ARCHITECTURE.md` when changing: system architecture, tech stack, directory structure, deployment, security, integrations.
|
||||
Update `docs/features.md` when adding capabilities (short marketing-style list only).
|
||||
|
||||
---
|
||||
|
||||
## CI/CD & Commit Conventions
|
||||
|
||||
- `feat:`, `fix:`, `perf:` → trigger Docker builds; `chore:` → skips builds
|
||||
- `feature/beta-release` branch always builds
|
||||
- History-rewrite PRs (touching `scripts/history-rewrite/`) MUST include checklist from `.github/PULL_REQUEST_TEMPLATE/history-rewrite.md`
|
||||
|
||||
---
|
||||
|
||||
## PR Sizing
|
||||
|
||||
Prefer smaller, reviewable PRs. Split when changes span backend + frontend + infra, or diff is large.
|
||||
|
||||
**Suggested PR sequence**:
|
||||
1. Foundation PR (types/contracts/refactors, no behaviour change)
|
||||
2. Backend PR (API/model/service + tests)
|
||||
3. Frontend PR (UI integration + tests)
|
||||
4. Hardening PR (security/CI/docs/follow-ups)
|
||||
|
||||
Each PR must remain deployable and pass DoD checks.
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done (MANDATORY — in order)
|
||||
|
||||
1. **Playwright E2E** (run first): `cd /projects/Charon && npx playwright test --project=firefox`
|
||||
- Scope to modified features; fix root cause before proceeding on failure
|
||||
2. **GORM Security Scan** (conditional — if models/DB changed): `./scripts/scan-gorm-security.sh --check` — zero CRITICAL/HIGH
|
||||
3. **Local Patch Coverage Preflight**: `bash scripts/local-patch-report.sh` — produces `test-results/local-patch-report.md`
|
||||
4. **Security Scans** (zero high/critical):
|
||||
- CodeQL Go: VS Code task "Security: CodeQL Go Scan (CI-Aligned)"
|
||||
- CodeQL JS: VS Code task "Security: CodeQL JS Scan (CI-Aligned)"
|
||||
- Trivy: VS Code task "Security: Trivy Scan"
|
||||
5. **Lefthook**: `lefthook run pre-commit` — fix all errors immediately
|
||||
6. **Staticcheck (BLOCKING)**: `make lint-fast` — must pass before commit
|
||||
7. **Coverage (MANDATORY — 85% minimum)**:
|
||||
- Backend: VS Code task "Test: Backend with Coverage" or `scripts/go-test-coverage.sh`
|
||||
- Frontend: VS Code task "Test: Frontend with Coverage" or `scripts/frontend-test-coverage.sh`
|
||||
8. **Type Safety** (frontend): `cd frontend && npm run type-check` — fix all errors
|
||||
9. **Build verification**: `cd backend && go build ./...` + `cd frontend && npm run build`
|
||||
10. **All tests pass**: `go test ./...` + `npm test`
|
||||
11. **Clean up**: No `console.log`, `fmt.Println`, debug statements, or commented-out blocks
|
||||
|
||||
---
|
||||
|
||||
## Agents
|
||||
|
||||
Specialised subagents live in `.claude/agents/`. Invoke with `@agent-name` or let Claude Code route automatically based on task type:
|
||||
|
||||
| Agent | Role |
|
||||
|---|---|
|
||||
| `management` | Engineering Director — delegates all work, never implements directly |
|
||||
| `planning` | Principal Architect — research, technical specs, implementation plans |
|
||||
| `supervisor` | Code Review Lead — PR reviews, quality assurance |
|
||||
| `backend-dev` | Senior Go Engineer — Gin/GORM/SQLite implementation |
|
||||
| `frontend-dev` | Senior React/TypeScript Engineer — UI implementation |
|
||||
| `qa-security` | QA & Security Engineer — testing, vulnerability assessment |
|
||||
| `doc-writer` | Technical Writer — user-facing documentation |
|
||||
| `playwright-dev` | E2E Testing Specialist — Playwright test automation |
|
||||
| `devops` | DevOps Specialist — CI/CD, GitHub Actions, deployments |
|
||||
|
||||
## Commands
|
||||
|
||||
Slash commands in `.claude/commands/` — invoke with `/command-name`:
|
||||
|
||||
| Command | Purpose |
|
||||
|---|---|
|
||||
| `/create-implementation-plan` | Draft a structured implementation plan file |
|
||||
| `/update-implementation-plan` | Update an existing plan |
|
||||
| `/breakdown-feature` | Break a feature into implementable tasks |
|
||||
| `/create-technical-spike` | Research a technical question |
|
||||
| `/create-github-issues` | Generate GitHub issues from an implementation plan |
|
||||
| `/sa-plan` | Structured Autonomy — planning phase |
|
||||
| `/sa-generate` | Structured Autonomy — generate phase |
|
||||
| `/sa-implement` | Structured Autonomy — implement phase |
|
||||
| `/debug-web-console` | Debug browser console errors |
|
||||
| `/playwright-explore` | Explore a website with Playwright |
|
||||
| `/playwright-generate-test` | Generate a Playwright test |
|
||||
| `/sql-code-review` | Review SQL / stored procedures |
|
||||
| `/sql-optimization` | Optimise a SQL query |
|
||||
| `/codecov-patch-fix` | Fix Codecov patch coverage gaps |
|
||||
| `/supply-chain-remediation` | Remediate supply chain vulnerabilities |
|
||||
| `/ai-prompt-safety-review` | Review AI prompt for safety/security |
|
||||
| `/prompt-builder` | Build a structured AI prompt |
|
||||
|
||||
## Skills (Docker / Testing / Security)
|
||||
|
||||
Skill runner: `.github/skills/scripts/skill-runner.sh <skill-name>`
|
||||
|
||||
| Skill | Command |
|
||||
|---|---|
|
||||
| Start dev environment | `/docker-start-dev` |
|
||||
| Stop dev environment | `/docker-stop-dev` |
|
||||
| Rebuild E2E container | `/docker-rebuild-e2e` |
|
||||
| Prune Docker resources | `/docker-prune` |
|
||||
| Run all integration tests | `/integration-test-all` |
|
||||
| Backend unit tests | `/test-backend-unit` |
|
||||
| Backend coverage | `/test-backend-coverage` |
|
||||
| Frontend unit tests | `/test-frontend-unit` |
|
||||
| Frontend coverage | `/test-frontend-coverage` |
|
||||
| E2E Playwright tests | `/test-e2e-playwright` |
|
||||
| CodeQL scan | `/security-scan-codeql` |
|
||||
| Trivy scan | `/security-scan-trivy` |
|
||||
| Docker image scan | `/security-scan-docker-image` |
|
||||
| GORM security scan | `/security-scan-gorm` |
|
||||
| Go vulnerability scan | `/security-scan-go-vuln` |
|
||||
@@ -39,7 +39,9 @@ ARG CADDY_CANDIDATE_VERSION=2.11.2
|
||||
ARG CADDY_USE_CANDIDATE=0
|
||||
ARG CADDY_PATCH_SCENARIO=B
|
||||
# renovate: datasource=go depName=github.com/greenpau/caddy-security
|
||||
ARG CADDY_SECURITY_VERSION=1.1.43
|
||||
ARG CADDY_SECURITY_VERSION=1.1.45
|
||||
# renovate: datasource=go depName=github.com/corazawaf/coraza-caddy
|
||||
ARG CORAZA_CADDY_VERSION=2.2.0
|
||||
## When an official caddy image tag isn't available on the host, use a
|
||||
## plain Alpine base image and overwrite its caddy binary with our
|
||||
## xcaddy-built binary in the later COPY step. This avoids relying on
|
||||
@@ -219,6 +221,7 @@ ARG CADDY_CANDIDATE_VERSION
|
||||
ARG CADDY_USE_CANDIDATE
|
||||
ARG CADDY_PATCH_SCENARIO
|
||||
ARG CADDY_SECURITY_VERSION
|
||||
ARG CORAZA_CADDY_VERSION
|
||||
# renovate: datasource=go depName=github.com/caddyserver/xcaddy
|
||||
ARG XCADDY_VERSION=0.4.5
|
||||
ARG EXPR_LANG_VERSION
|
||||
@@ -250,7 +253,7 @@ RUN --mount=type=cache,target=/root/.cache/go-build \
|
||||
GOOS=$TARGETOS GOARCH=$TARGETARCH xcaddy build v${CADDY_TARGET_VERSION} \
|
||||
--with github.com/caddyserver/caddy/v2@v${CADDY_TARGET_VERSION} \
|
||||
--with github.com/greenpau/caddy-security@v${CADDY_SECURITY_VERSION} \
|
||||
--with github.com/corazawaf/coraza-caddy/v2 \
|
||||
--with github.com/corazawaf/coraza-caddy/v2@v${CORAZA_CADDY_VERSION} \
|
||||
--with github.com/hslatman/caddy-crowdsec-bouncer@v0.10.0 \
|
||||
--with github.com/zhangjiayin/caddy-geoip2 \
|
||||
--with github.com/mholt/caddy-ratelimit \
|
||||
|
||||
@@ -18,7 +18,7 @@ require (
|
||||
github.com/stretchr/testify v1.11.1
|
||||
golang.org/x/crypto v0.48.0
|
||||
golang.org/x/net v0.51.0
|
||||
golang.org/x/text v0.34.0
|
||||
golang.org/x/text v0.35.0
|
||||
golang.org/x/time v0.15.0
|
||||
gopkg.in/natefinch/lumberjack.v2 v2.2.1
|
||||
gorm.io/driver/sqlite v1.6.0
|
||||
@@ -95,7 +95,7 @@ require (
|
||||
google.golang.org/protobuf v1.36.11 // indirect
|
||||
gopkg.in/yaml.v3 v3.0.1 // indirect
|
||||
gotest.tools/v3 v3.5.2 // indirect
|
||||
modernc.org/libc v1.69.0 // indirect
|
||||
modernc.org/libc v1.70.0 // indirect
|
||||
modernc.org/mathutil v1.7.1 // indirect
|
||||
modernc.org/memory v1.11.0 // indirect
|
||||
modernc.org/sqlite v1.46.1 // indirect
|
||||
|
||||
@@ -204,21 +204,21 @@ golang.org/x/arch v0.25.0 h1:qnk6Ksugpi5Bz32947rkUgDt9/s5qvqDPl/gBKdMJLE=
|
||||
golang.org/x/arch v0.25.0/go.mod h1:0X+GdSIP+kL5wPmpK7sdkEVTt2XoYP0cSjQSbZBwOi8=
|
||||
golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
|
||||
golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
|
||||
golang.org/x/mod v0.32.0 h1:9F4d3PHLljb6x//jOyokMv3eX+YDeepZSEo3mFJy93c=
|
||||
golang.org/x/mod v0.32.0/go.mod h1:SgipZ/3h2Ci89DlEtEXWUk/HteuRin+HHhN+WbNhguU=
|
||||
golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
|
||||
golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
|
||||
golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
|
||||
golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
|
||||
golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
|
||||
golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
|
||||
golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
|
||||
golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
|
||||
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
|
||||
golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
|
||||
golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
|
||||
golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
|
||||
golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
|
||||
golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
|
||||
golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
|
||||
golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
|
||||
golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
|
||||
golang.org/x/tools v0.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc=
|
||||
golang.org/x/tools v0.41.0/go.mod h1:XSY6eDqxVNiYgezAVqqCeihT4j1U2CCsqvH3WhQpnlg=
|
||||
golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
|
||||
golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
|
||||
google.golang.org/genproto/googleapis/api v0.0.0-20250825161204-c5933d9347a5 h1:BIRfGDEjiHRrk0QKZe3Xv2ieMhtgRGeLcZQ0mIVn4EY=
|
||||
google.golang.org/genproto/googleapis/api v0.0.0-20250825161204-c5933d9347a5/go.mod h1:j3QtIyytwqGr1JUDtYXwtMXWPKsEa5LtzIFN1Wn5WvE=
|
||||
google.golang.org/genproto/googleapis/rpc v0.0.0-20250825161204-c5933d9347a5 h1:eaY8u2EuxbRv7c3NiGK0/NedzVsCcV6hDuU5qPX5EGE=
|
||||
@@ -243,8 +243,8 @@ gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
|
||||
gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
|
||||
modernc.org/cc/v4 v4.27.1 h1:9W30zRlYrefrDV2JE2O8VDtJ1yPGownxciz5rrbQZis=
|
||||
modernc.org/cc/v4 v4.27.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
|
||||
modernc.org/ccgo/v4 v4.31.0 h1:/bsaxqdgX3gy/0DboxcvWrc3NpzH+6wpFfI/ZaA/hrg=
|
||||
modernc.org/ccgo/v4 v4.31.0/go.mod h1:jKe8kPBjIN/VdGTVqARTQ8N1gAziBmiISY8j5HoKwjg=
|
||||
modernc.org/ccgo/v4 v4.32.0 h1:hjG66bI/kqIPX1b2yT6fr/jt+QedtP2fqojG2VrFuVw=
|
||||
modernc.org/ccgo/v4 v4.32.0/go.mod h1:6F08EBCx5uQc38kMGl+0Nm0oWczoo1c7cgpzEry7Uc0=
|
||||
modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
|
||||
modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
|
||||
modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
|
||||
@@ -253,8 +253,8 @@ modernc.org/gc/v3 v3.1.2 h1:ZtDCnhonXSZexk/AYsegNRV1lJGgaNZJuKjJSWKyEqo=
|
||||
modernc.org/gc/v3 v3.1.2/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
|
||||
modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
|
||||
modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
|
||||
modernc.org/libc v1.69.0 h1:YQJ5QMSReTgQ3QFmI0dudfjXIjCcYTUxcH8/9P9f0D8=
|
||||
modernc.org/libc v1.69.0/go.mod h1:YfLLduUEbodNV2xLU5JOnRHBTAHVHsVW3bVYGw0ZCV4=
|
||||
modernc.org/libc v1.70.0 h1:U58NawXqXbgpZ/dcdS9kMshu08aiA6b7gusEusqzNkw=
|
||||
modernc.org/libc v1.70.0/go.mod h1:OVmxFGP1CI/Z4L3E0Q3Mf1PDE0BucwMkcXjjLntvHJo=
|
||||
modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
|
||||
modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
|
||||
modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
|
||||
|
||||
@@ -33,6 +33,7 @@ var defaultFlags = []string{
|
||||
"feature.notifications.service.email.enabled",
|
||||
"feature.notifications.service.gotify.enabled",
|
||||
"feature.notifications.service.webhook.enabled",
|
||||
"feature.notifications.service.telegram.enabled",
|
||||
"feature.notifications.security_provider_events.enabled", // Blocker 3: Add security_provider_events gate
|
||||
}
|
||||
|
||||
@@ -45,6 +46,7 @@ var defaultFlagValues = map[string]bool{
|
||||
"feature.notifications.service.email.enabled": false,
|
||||
"feature.notifications.service.gotify.enabled": false,
|
||||
"feature.notifications.service.webhook.enabled": false,
|
||||
"feature.notifications.service.telegram.enabled": false,
|
||||
"feature.notifications.security_provider_events.enabled": false, // Blocker 3: Default disabled for this stage
|
||||
}
|
||||
|
||||
|
||||
@@ -36,7 +36,7 @@ func TestDiscordOnly_CreateRejectsNonDiscord(t *testing.T) {
|
||||
{"webhook", "webhook", http.StatusCreated, ""},
|
||||
{"gotify", "gotify", http.StatusCreated, ""},
|
||||
{"slack", "slack", http.StatusBadRequest, "UNSUPPORTED_PROVIDER_TYPE"},
|
||||
{"telegram", "telegram", http.StatusBadRequest, "UNSUPPORTED_PROVIDER_TYPE"},
|
||||
{"telegram", "telegram", http.StatusCreated, ""},
|
||||
{"generic", "generic", http.StatusBadRequest, "UNSUPPORTED_PROVIDER_TYPE"},
|
||||
{"email", "email", http.StatusCreated, ""},
|
||||
}
|
||||
|
||||
@@ -92,7 +92,7 @@ func respondSanitizedProviderError(c *gin.Context, status int, code, category, m
|
||||
c.JSON(status, response)
|
||||
}
|
||||
|
||||
var providerStatusCodePattern = regexp.MustCompile(`provider returned status\s+(\d{3})`)
|
||||
var providerStatusCodePattern = regexp.MustCompile(`provider returned status\s+(\d{3})(?::\s*(.+))?`)
|
||||
|
||||
func classifyProviderTestFailure(err error) (code string, category string, message string) {
|
||||
if err == nil {
|
||||
@@ -107,14 +107,18 @@ func classifyProviderTestFailure(err error) (code string, category string, messa
|
||||
return "PROVIDER_TEST_URL_INVALID", "validation", "Provider URL is invalid or blocked. Verify the URL and try again"
|
||||
}
|
||||
|
||||
if statusMatch := providerStatusCodePattern.FindStringSubmatch(errText); len(statusMatch) == 2 {
|
||||
if statusMatch := providerStatusCodePattern.FindStringSubmatch(errText); len(statusMatch) >= 2 {
|
||||
hint := ""
|
||||
if len(statusMatch) >= 3 && strings.TrimSpace(statusMatch[2]) != "" {
|
||||
hint = ": " + strings.TrimSpace(statusMatch[2])
|
||||
}
|
||||
switch statusMatch[1] {
|
||||
case "401", "403":
|
||||
return "PROVIDER_TEST_AUTH_REJECTED", "dispatch", "Provider rejected authentication. Verify your Gotify token"
|
||||
return "PROVIDER_TEST_AUTH_REJECTED", "dispatch", "Provider rejected authentication. Verify your credentials"
|
||||
case "404":
|
||||
return "PROVIDER_TEST_ENDPOINT_NOT_FOUND", "dispatch", "Provider endpoint was not found. Verify the provider URL path"
|
||||
default:
|
||||
return "PROVIDER_TEST_REMOTE_REJECTED", "dispatch", fmt.Sprintf("Provider rejected the test request (HTTP %s)", statusMatch[1])
|
||||
return "PROVIDER_TEST_REMOTE_REJECTED", "dispatch", fmt.Sprintf("Provider rejected the test request (HTTP %s)%s", statusMatch[1], hint)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -168,7 +172,7 @@ func (h *NotificationProviderHandler) Create(c *gin.Context) {
|
||||
}
|
||||
|
||||
providerType := strings.ToLower(strings.TrimSpace(req.Type))
|
||||
if providerType != "discord" && providerType != "gotify" && providerType != "webhook" && providerType != "email" {
|
||||
if providerType != "discord" && providerType != "gotify" && providerType != "webhook" && providerType != "email" && providerType != "telegram" {
|
||||
respondSanitizedProviderError(c, http.StatusBadRequest, "UNSUPPORTED_PROVIDER_TYPE", "validation", "Unsupported notification provider type")
|
||||
return
|
||||
}
|
||||
@@ -228,12 +232,12 @@ func (h *NotificationProviderHandler) Update(c *gin.Context) {
|
||||
}
|
||||
|
||||
providerType := strings.ToLower(strings.TrimSpace(existing.Type))
|
||||
if providerType != "discord" && providerType != "gotify" && providerType != "webhook" && providerType != "email" {
|
||||
if providerType != "discord" && providerType != "gotify" && providerType != "webhook" && providerType != "email" && providerType != "telegram" {
|
||||
respondSanitizedProviderError(c, http.StatusBadRequest, "UNSUPPORTED_PROVIDER_TYPE", "validation", "Unsupported notification provider type")
|
||||
return
|
||||
}
|
||||
|
||||
if providerType == "gotify" && strings.TrimSpace(req.Token) == "" {
|
||||
if (providerType == "gotify" || providerType == "telegram") && strings.TrimSpace(req.Token) == "" {
|
||||
// Keep existing token if update payload omits token
|
||||
req.Token = existing.Token
|
||||
}
|
||||
|
||||
@@ -581,3 +581,90 @@ func TestNotificationProviderHandler_Test_NonEmail_StillRequiresProviderID(t *te
|
||||
_ = json.Unmarshal(w.Body.Bytes(), &resp)
|
||||
assert.Equal(t, "MISSING_PROVIDER_ID", resp["code"])
|
||||
}
|
||||
|
||||
func TestNotificationProviderHandler_Create_Telegram(t *testing.T) {
|
||||
r, _ := setupNotificationProviderTest(t)
|
||||
|
||||
payload := map[string]interface{}{
|
||||
"name": "My Telegram Bot",
|
||||
"type": "telegram",
|
||||
"url": "123456789",
|
||||
"token": "bot123456789:ABCdefGHIjklMNOpqrSTUvwxYZ",
|
||||
"template": "minimal",
|
||||
}
|
||||
body, _ := json.Marshal(payload)
|
||||
req, _ := http.NewRequest("POST", "/api/v1/notifications/providers", bytes.NewBuffer(body))
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
w := httptest.NewRecorder()
|
||||
r.ServeHTTP(w, req)
|
||||
|
||||
assert.Equal(t, http.StatusCreated, w.Code)
|
||||
|
||||
var raw map[string]interface{}
|
||||
require.NoError(t, json.Unmarshal(w.Body.Bytes(), &raw))
|
||||
assert.Equal(t, "telegram", raw["type"])
|
||||
assert.Equal(t, true, raw["has_token"])
|
||||
// Token must never appear in response
|
||||
assert.NotContains(t, w.Body.String(), "bot123456789:ABCdefGHIjklMNOpqrSTUvwxYZ")
|
||||
}
|
||||
|
||||
func TestNotificationProviderHandler_Update_TelegramTokenPreservation(t *testing.T) {
|
||||
r, db := setupNotificationProviderTest(t)
|
||||
|
||||
p := models.NotificationProvider{
|
||||
ID: "tg-preserve",
|
||||
Name: "Telegram Bot",
|
||||
Type: "telegram",
|
||||
URL: "123456789",
|
||||
Token: "original-bot-token",
|
||||
}
|
||||
require.NoError(t, db.Create(&p).Error)
|
||||
|
||||
// Update without token — token should be preserved
|
||||
payload := map[string]interface{}{
|
||||
"name": "Updated Telegram Bot",
|
||||
"type": "telegram",
|
||||
"url": "987654321",
|
||||
}
|
||||
body, _ := json.Marshal(payload)
|
||||
req, _ := http.NewRequest("PUT", "/api/v1/notifications/providers/tg-preserve", bytes.NewBuffer(body))
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
w := httptest.NewRecorder()
|
||||
r.ServeHTTP(w, req)
|
||||
|
||||
assert.Equal(t, http.StatusOK, w.Code)
|
||||
|
||||
// Verify token was preserved in DB
|
||||
var dbProvider models.NotificationProvider
|
||||
require.NoError(t, db.Where("id = ?", "tg-preserve").First(&dbProvider).Error)
|
||||
assert.Equal(t, "original-bot-token", dbProvider.Token)
|
||||
assert.Equal(t, "987654321", dbProvider.URL)
|
||||
}
|
||||
|
||||
func TestNotificationProviderHandler_List_TelegramNeverExposesBotToken(t *testing.T) {
|
||||
r, db := setupNotificationProviderTest(t)
|
||||
|
||||
p := models.NotificationProvider{
|
||||
ID: "tg-secret",
|
||||
Name: "Secret Telegram",
|
||||
Type: "telegram",
|
||||
URL: "123456789",
|
||||
Token: "bot999:SECRETTOKEN",
|
||||
}
|
||||
require.NoError(t, db.Create(&p).Error)
|
||||
|
||||
req, _ := http.NewRequest("GET", "/api/v1/notifications/providers", http.NoBody)
|
||||
w := httptest.NewRecorder()
|
||||
r.ServeHTTP(w, req)
|
||||
|
||||
assert.Equal(t, http.StatusOK, w.Code)
|
||||
assert.NotContains(t, w.Body.String(), "bot999:SECRETTOKEN")
|
||||
assert.NotContains(t, w.Body.String(), "api.telegram.org")
|
||||
|
||||
var raw []map[string]interface{}
|
||||
require.NoError(t, json.Unmarshal(w.Body.Bytes(), &raw))
|
||||
require.Len(t, raw, 1)
|
||||
assert.Equal(t, true, raw[0]["has_token"])
|
||||
_, hasTokenField := raw[0]["token"]
|
||||
assert.False(t, hasTokenField, "raw token field must not appear in JSON response")
|
||||
}
|
||||
|
||||
@@ -224,7 +224,7 @@ func TestFinalBlocker3_SupportedProviderTypes_UnsupportedTypesIgnored(t *testing
|
||||
db := SetupCompatibilityTestDB(t)
|
||||
|
||||
// Create ONLY unsupported providers
|
||||
unsupportedTypes := []string{"telegram", "generic"}
|
||||
unsupportedTypes := []string{"pushover", "generic"}
|
||||
|
||||
for _, providerType := range unsupportedTypes {
|
||||
provider := &models.NotificationProvider{
|
||||
|
||||
@@ -6,5 +6,6 @@ const (
|
||||
FlagEmailServiceEnabled = "feature.notifications.service.email.enabled"
|
||||
FlagGotifyServiceEnabled = "feature.notifications.service.gotify.enabled"
|
||||
FlagWebhookServiceEnabled = "feature.notifications.service.webhook.enabled"
|
||||
FlagTelegramServiceEnabled = "feature.notifications.service.telegram.enabled"
|
||||
FlagSecurityProviderEventsEnabled = "feature.notifications.security_provider_events.enabled"
|
||||
)
|
||||
|
||||
@@ -4,6 +4,7 @@ import (
|
||||
"bytes"
|
||||
"context"
|
||||
crand "crypto/rand"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
@@ -157,6 +158,9 @@ func (w *HTTPWrapper) Send(ctx context.Context, request HTTPWrapperRequest) (*HT
|
||||
}
|
||||
|
||||
if resp.StatusCode >= http.StatusBadRequest {
|
||||
if hint := extractProviderErrorHint(body); hint != "" {
|
||||
return nil, fmt.Errorf("provider returned status %d: %s", resp.StatusCode, hint)
|
||||
}
|
||||
return nil, fmt.Errorf("provider returned status %d", resp.StatusCode)
|
||||
}
|
||||
|
||||
@@ -410,6 +414,34 @@ func shouldRetry(resp *http.Response, err error) bool {
|
||||
return resp.StatusCode >= http.StatusInternalServerError
|
||||
}
|
||||
|
||||
// extractProviderErrorHint attempts to extract a short, human-readable error description
|
||||
// from a JSON error response body. Only well-known fields are extracted to avoid
|
||||
// accidentally surfacing sensitive or overlong content from arbitrary providers.
|
||||
func extractProviderErrorHint(body []byte) string {
|
||||
if len(body) == 0 {
|
||||
return ""
|
||||
}
|
||||
var errResp map[string]any
|
||||
if err := json.Unmarshal(body, &errResp); err != nil {
|
||||
return ""
|
||||
}
|
||||
for _, key := range []string{"description", "message", "error", "error_description"} {
|
||||
v, ok := errResp[key]
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
s, ok := v.(string)
|
||||
if !ok || strings.TrimSpace(s) == "" {
|
||||
continue
|
||||
}
|
||||
if len(s) > 100 {
|
||||
s = s[:100] + "..."
|
||||
}
|
||||
return strings.TrimSpace(s)
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func readCappedResponseBody(body io.Reader) ([]byte, error) {
|
||||
limited := io.LimitReader(body, MaxNotifyResponseBodyBytes+1)
|
||||
content, err := io.ReadAll(limited)
|
||||
|
||||
@@ -921,3 +921,81 @@ func TestAllowNotifyHTTPOverride(t *testing.T) {
|
||||
t.Fatal("expected allowHTTP to be true in test binary")
|
||||
}
|
||||
}
|
||||
|
||||
func TestExtractProviderErrorHint(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
body []byte
|
||||
expected string
|
||||
}{
|
||||
{
|
||||
name: "description field",
|
||||
body: []byte(`{"description":"Not Found: chat not found"}`),
|
||||
expected: "Not Found: chat not found",
|
||||
},
|
||||
{
|
||||
name: "message field",
|
||||
body: []byte(`{"message":"Unauthorized"}`),
|
||||
expected: "Unauthorized",
|
||||
},
|
||||
{
|
||||
name: "error field",
|
||||
body: []byte(`{"error":"rate limited"}`),
|
||||
expected: "rate limited",
|
||||
},
|
||||
{
|
||||
name: "error_description field",
|
||||
body: []byte(`{"error_description":"invalid token"}`),
|
||||
expected: "invalid token",
|
||||
},
|
||||
{
|
||||
name: "empty body",
|
||||
body: []byte{},
|
||||
expected: "",
|
||||
},
|
||||
{
|
||||
name: "non-JSON body",
|
||||
body: []byte(`<html>Server Error</html>`),
|
||||
expected: "",
|
||||
},
|
||||
{
|
||||
name: "string over 100 chars truncated",
|
||||
body: []byte(`{"description":"` + strings.Repeat("x", 120) + `"}`),
|
||||
expected: strings.Repeat("x", 100) + "...",
|
||||
},
|
||||
{
|
||||
name: "empty string value ignored",
|
||||
body: []byte(`{"description":"","message":"fallback hint"}`),
|
||||
expected: "fallback hint",
|
||||
},
|
||||
{
|
||||
name: "whitespace-only value ignored",
|
||||
body: []byte(`{"description":" ","message":"real hint"}`),
|
||||
expected: "real hint",
|
||||
},
|
||||
{
|
||||
name: "non-string value ignored",
|
||||
body: []byte(`{"description":42,"message":"string hint"}`),
|
||||
expected: "string hint",
|
||||
},
|
||||
{
|
||||
name: "priority order: description before message",
|
||||
body: []byte(`{"message":"second","description":"first"}`),
|
||||
expected: "first",
|
||||
},
|
||||
{
|
||||
name: "no recognized fields",
|
||||
body: []byte(`{"status":"error","code":500}`),
|
||||
expected: "",
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
result := extractProviderErrorHint(tt.body)
|
||||
if result != tt.expected {
|
||||
t.Errorf("extractProviderErrorHint(%q) = %q, want %q", string(tt.body), result, tt.expected)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
@@ -23,6 +23,8 @@ func (r *Router) ShouldUseNotify(providerType string, flags map[string]bool) boo
|
||||
return flags[FlagGotifyServiceEnabled]
|
||||
case "webhook":
|
||||
return flags[FlagWebhookServiceEnabled]
|
||||
case "telegram":
|
||||
return flags[FlagTelegramServiceEnabled]
|
||||
default:
|
||||
return false
|
||||
}
|
||||
|
||||
@@ -84,10 +84,11 @@ func (s *EnhancedSecurityNotificationService) getProviderAggregatedConfig() (*mo
|
||||
// Blocker 3: Filter for supported notify-only provider types (PR-1 scope)
|
||||
// All supported types are included in GET aggregation for configuration visibility
|
||||
supportedTypes := map[string]bool{
|
||||
"webhook": true,
|
||||
"discord": true,
|
||||
"slack": true,
|
||||
"gotify": true,
|
||||
"webhook": true,
|
||||
"discord": true,
|
||||
"slack": true,
|
||||
"gotify": true,
|
||||
"telegram": true,
|
||||
}
|
||||
filteredProviders := []models.NotificationProvider{}
|
||||
for _, p := range providers {
|
||||
|
||||
@@ -136,7 +136,7 @@ func TestGetProviderAggregatedConfig_FiltersSupportedTypes(t *testing.T) {
|
||||
{ID: "webhook", Type: "webhook", Enabled: true, NotifySecurityWAFBlocks: true},
|
||||
{ID: "slack", Type: "slack", Enabled: true, NotifySecurityACLDenies: true},
|
||||
{ID: "gotify", Type: "gotify", Enabled: true, NotifySecurityRateLimitHits: true},
|
||||
{ID: "unsupported", Type: "telegram", Enabled: true, NotifySecurityWAFBlocks: true}, // Should be filtered
|
||||
{ID: "telegram", Type: "telegram", Enabled: true, NotifySecurityWAFBlocks: true}, // Telegram is now supported
|
||||
}
|
||||
|
||||
for _, p := range providers {
|
||||
@@ -146,8 +146,8 @@ func TestGetProviderAggregatedConfig_FiltersSupportedTypes(t *testing.T) {
|
||||
// Test
|
||||
config, err := service.getProviderAggregatedConfig()
|
||||
require.NoError(t, err)
|
||||
// Telegram is unsupported, so it shouldn't contribute to aggregation
|
||||
assert.True(t, config.NotifyWAFBlocks, "Discord and webhook have WAF=true")
|
||||
// All provider types including telegram contribute to aggregation
|
||||
assert.True(t, config.NotifyWAFBlocks, "Discord, webhook, and telegram have WAF=true")
|
||||
assert.True(t, config.NotifyACLDenies, "Slack has ACL=true")
|
||||
assert.True(t, config.NotifyRateLimitHits, "Gotify has RateLimit=true")
|
||||
}
|
||||
|
||||
@@ -26,16 +26,18 @@ import (
|
||||
)
|
||||
|
||||
type NotificationService struct {
|
||||
DB *gorm.DB
|
||||
httpWrapper *notifications.HTTPWrapper
|
||||
mailService MailServiceInterface
|
||||
DB *gorm.DB
|
||||
httpWrapper *notifications.HTTPWrapper
|
||||
mailService MailServiceInterface
|
||||
telegramAPIBaseURL string
|
||||
}
|
||||
|
||||
func NewNotificationService(db *gorm.DB, mailService MailServiceInterface) *NotificationService {
|
||||
return &NotificationService{
|
||||
DB: db,
|
||||
httpWrapper: notifications.NewNotifyHTTPWrapper(),
|
||||
mailService: mailService,
|
||||
DB: db,
|
||||
httpWrapper: notifications.NewNotifyHTTPWrapper(),
|
||||
mailService: mailService,
|
||||
telegramAPIBaseURL: "https://api.telegram.org",
|
||||
}
|
||||
}
|
||||
|
||||
@@ -99,7 +101,7 @@ func validateDiscordProviderURL(providerType, rawURL string) error {
|
||||
// supportsJSONTemplates returns true if the provider type can use JSON templates
|
||||
func supportsJSONTemplates(providerType string) bool {
|
||||
switch strings.ToLower(providerType) {
|
||||
case "webhook", "discord", "gotify", "slack", "generic":
|
||||
case "webhook", "discord", "gotify", "slack", "generic", "telegram":
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
@@ -108,7 +110,7 @@ func supportsJSONTemplates(providerType string) bool {
|
||||
|
||||
func isSupportedNotificationProviderType(providerType string) bool {
|
||||
switch strings.ToLower(strings.TrimSpace(providerType)) {
|
||||
case "discord", "email", "gotify", "webhook":
|
||||
case "discord", "email", "gotify", "webhook", "telegram":
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
@@ -125,6 +127,8 @@ func (s *NotificationService) isDispatchEnabled(providerType string) bool {
|
||||
return s.getFeatureFlagValue(notifications.FlagGotifyServiceEnabled, true)
|
||||
case "webhook":
|
||||
return s.getFeatureFlagValue(notifications.FlagWebhookServiceEnabled, true)
|
||||
case "telegram":
|
||||
return s.getFeatureFlagValue(notifications.FlagTelegramServiceEnabled, true)
|
||||
default:
|
||||
return false
|
||||
}
|
||||
@@ -447,9 +451,26 @@ func (s *NotificationService) sendJSONPayload(ctx context.Context, p models.Noti
|
||||
if _, hasMessage := jsonPayload["message"]; !hasMessage {
|
||||
return fmt.Errorf("gotify payload requires 'message' field")
|
||||
}
|
||||
case "telegram":
|
||||
// Telegram requires 'text' field for the message body
|
||||
if _, hasText := jsonPayload["text"]; !hasText {
|
||||
if messageValue, hasMessage := jsonPayload["message"]; hasMessage {
|
||||
jsonPayload["text"] = messageValue
|
||||
normalizedBody, marshalErr := json.Marshal(jsonPayload)
|
||||
if marshalErr != nil {
|
||||
return fmt.Errorf("failed to normalize telegram payload: %w", marshalErr)
|
||||
}
|
||||
body.Reset()
|
||||
if _, writeErr := body.Write(normalizedBody); writeErr != nil {
|
||||
return fmt.Errorf("failed to write normalized telegram payload: %w", writeErr)
|
||||
}
|
||||
} else {
|
||||
return fmt.Errorf("telegram payload requires 'text' field")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if providerType == "gotify" || providerType == "webhook" {
|
||||
if providerType == "gotify" || providerType == "webhook" || providerType == "telegram" {
|
||||
headers := map[string]string{
|
||||
"Content-Type": "application/json",
|
||||
"User-Agent": "Charon-Notify/1.0",
|
||||
@@ -459,14 +480,44 @@ func (s *NotificationService) sendJSONPayload(ctx context.Context, p models.Noti
|
||||
headers["X-Request-ID"] = ridStr
|
||||
}
|
||||
}
|
||||
|
||||
dispatchURL := p.URL
|
||||
|
||||
if providerType == "gotify" {
|
||||
if strings.TrimSpace(p.Token) != "" {
|
||||
headers["X-Gotify-Key"] = strings.TrimSpace(p.Token)
|
||||
}
|
||||
}
|
||||
|
||||
if providerType == "telegram" {
|
||||
decryptedToken := p.Token
|
||||
telegramBase := s.telegramAPIBaseURL
|
||||
if telegramBase == "" {
|
||||
telegramBase = "https://api.telegram.org"
|
||||
}
|
||||
dispatchURL = telegramBase + "/bot" + decryptedToken + "/sendMessage"
|
||||
|
||||
parsedURL, parseErr := neturl.Parse(dispatchURL)
|
||||
expectedHost := "api.telegram.org"
|
||||
if parsedURL != nil && parsedURL.Hostname() != "" && telegramBase != "https://api.telegram.org" {
|
||||
// In test overrides, skip the hostname pin check.
|
||||
expectedHost = parsedURL.Hostname()
|
||||
}
|
||||
if parseErr != nil || parsedURL.Hostname() != expectedHost {
|
||||
return fmt.Errorf("telegram dispatch URL validation failed: invalid hostname")
|
||||
}
|
||||
|
||||
jsonPayload["chat_id"] = p.URL
|
||||
updatedBody, marshalErr := json.Marshal(jsonPayload)
|
||||
if marshalErr != nil {
|
||||
return fmt.Errorf("failed to marshal telegram payload with chat_id: %w", marshalErr)
|
||||
}
|
||||
body.Reset()
|
||||
body.Write(updatedBody)
|
||||
}
|
||||
|
||||
if _, sendErr := s.httpWrapper.Send(ctx, notifications.HTTPWrapperRequest{
|
||||
URL: p.URL,
|
||||
URL: dispatchURL,
|
||||
Headers: headers,
|
||||
Body: body.Bytes(),
|
||||
}); sendErr != nil {
|
||||
@@ -688,7 +739,7 @@ func (s *NotificationService) CreateProvider(provider *models.NotificationProvid
|
||||
return err
|
||||
}
|
||||
|
||||
if provider.Type != "gotify" {
|
||||
if provider.Type != "gotify" && provider.Type != "telegram" {
|
||||
provider.Token = ""
|
||||
}
|
||||
|
||||
@@ -724,7 +775,7 @@ func (s *NotificationService) UpdateProvider(provider *models.NotificationProvid
|
||||
return err
|
||||
}
|
||||
|
||||
if provider.Type == "gotify" {
|
||||
if provider.Type == "gotify" || provider.Type == "telegram" {
|
||||
if strings.TrimSpace(provider.Token) == "" {
|
||||
provider.Token = existing.Token
|
||||
}
|
||||
|
||||
@@ -22,7 +22,7 @@ func TestDiscordOnly_CreateProviderRejectsUnsupported(t *testing.T) {
|
||||
|
||||
service := NewNotificationService(db, nil)
|
||||
|
||||
testCases := []string{"slack", "telegram", "generic"}
|
||||
testCases := []string{"slack", "generic"}
|
||||
|
||||
for _, providerType := range testCases {
|
||||
t.Run(providerType, func(t *testing.T) {
|
||||
|
||||
@@ -29,7 +29,7 @@ func TestSupportsJSONTemplates(t *testing.T) {
|
||||
{"slack", "slack", true},
|
||||
{"gotify", "gotify", true},
|
||||
{"generic", "generic", true},
|
||||
{"telegram", "telegram", false},
|
||||
{"telegram", "telegram", true},
|
||||
{"unknown", "unknown", false},
|
||||
{"WEBHOOK uppercase", "WEBHOOK", true},
|
||||
{"Discord mixed case", "Discord", true},
|
||||
@@ -500,3 +500,163 @@ func TestTestProvider_UsesJSONForSupportedServices(t *testing.T) {
|
||||
err = svc.TestProvider(provider)
|
||||
assert.NoError(t, err)
|
||||
}
|
||||
|
||||
func TestSendJSONPayload_Telegram_ValidPayload(t *testing.T) {
|
||||
var capturedPayload map[string]any
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
err := json.NewDecoder(r.Body).Decode(&capturedPayload)
|
||||
require.NoError(t, err)
|
||||
w.WriteHeader(http.StatusOK)
|
||||
_, _ = w.Write([]byte(`{"ok":true}`))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
db, err := gorm.Open(sqlite.Open("file::memory:"), &gorm.Config{})
|
||||
require.NoError(t, err)
|
||||
|
||||
svc := NewNotificationService(db, nil)
|
||||
svc.telegramAPIBaseURL = server.URL
|
||||
|
||||
provider := models.NotificationProvider{
|
||||
Type: "telegram",
|
||||
URL: "123456789",
|
||||
Token: "bot-test-token",
|
||||
Template: "custom",
|
||||
Config: `{"text": {{toJSON .Message}}, "title": {{toJSON .Title}}}`,
|
||||
}
|
||||
|
||||
data := map[string]any{
|
||||
"Message": "Test notification",
|
||||
"Title": "Test",
|
||||
}
|
||||
|
||||
sendErr := svc.sendJSONPayload(context.Background(), provider, data)
|
||||
require.NoError(t, sendErr)
|
||||
assert.NotNil(t, capturedPayload["text"], "Telegram payload should have text field")
|
||||
assert.NotNil(t, capturedPayload["chat_id"], "Telegram payload should have chat_id field")
|
||||
}
|
||||
|
||||
func TestSendJSONPayload_Telegram_AutoMapMessageToText(t *testing.T) {
|
||||
var capturedPayload map[string]any
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
_ = json.NewDecoder(r.Body).Decode(&capturedPayload)
|
||||
w.WriteHeader(http.StatusOK)
|
||||
_, _ = w.Write([]byte(`{"ok":true}`))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
db, err := gorm.Open(sqlite.Open("file::memory:"), &gorm.Config{})
|
||||
require.NoError(t, err)
|
||||
|
||||
svc := NewNotificationService(db, nil)
|
||||
svc.telegramAPIBaseURL = server.URL
|
||||
|
||||
provider := models.NotificationProvider{
|
||||
Type: "telegram",
|
||||
URL: "123456789",
|
||||
Token: "bot-test-token",
|
||||
Template: "custom",
|
||||
Config: `{"message": {{toJSON .Message}}, "title": {{toJSON .Title}}}`,
|
||||
}
|
||||
|
||||
data := map[string]any{
|
||||
"Message": "Test notification",
|
||||
"Title": "Test",
|
||||
}
|
||||
|
||||
sendErr := svc.sendJSONPayload(context.Background(), provider, data)
|
||||
// 'message' must be auto-mapped to 'text' — dispatch must succeed.
|
||||
require.NoError(t, sendErr)
|
||||
assert.Equal(t, "Test notification", capturedPayload["text"], "'message' should be auto-mapped to 'text'")
|
||||
}
|
||||
|
||||
func TestSendJSONPayload_Telegram_MissingTextAndMessage(t *testing.T) {
|
||||
db, err := gorm.Open(sqlite.Open("file::memory:"), &gorm.Config{})
|
||||
require.NoError(t, err)
|
||||
|
||||
svc := NewNotificationService(db, nil)
|
||||
|
||||
provider := models.NotificationProvider{
|
||||
Type: "telegram",
|
||||
URL: "123456789",
|
||||
Token: "bot-test-token",
|
||||
Template: "custom",
|
||||
Config: `{"title": {{toJSON .Title}}}`,
|
||||
}
|
||||
|
||||
data := map[string]any{
|
||||
"Title": "Test",
|
||||
}
|
||||
|
||||
sendErr := svc.sendJSONPayload(context.Background(), provider, data)
|
||||
require.Error(t, sendErr)
|
||||
assert.Contains(t, sendErr.Error(), "telegram payload requires 'text' field")
|
||||
}
|
||||
|
||||
func TestSendJSONPayload_Telegram_SSRFValidation(t *testing.T) {
|
||||
var capturedPath string
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
capturedPath = r.URL.Path
|
||||
w.WriteHeader(http.StatusOK)
|
||||
_, _ = w.Write([]byte(`{"ok":true}`))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
db, err := gorm.Open(sqlite.Open("file::memory:"), &gorm.Config{})
|
||||
require.NoError(t, err)
|
||||
|
||||
svc := NewNotificationService(db, nil)
|
||||
svc.telegramAPIBaseURL = server.URL
|
||||
|
||||
// Path traversal in token: Go's net/http transport cleans the URL path,
|
||||
// so "/../../../evil.com/x" does not escape the server host.
|
||||
provider := models.NotificationProvider{
|
||||
Type: "telegram",
|
||||
URL: "123456789",
|
||||
Token: "test-token/../../../evil.com/x",
|
||||
Template: "custom",
|
||||
Config: `{"text": {{toJSON .Message}}}`,
|
||||
}
|
||||
|
||||
data := map[string]any{
|
||||
"Message": "Test",
|
||||
}
|
||||
|
||||
sendErr := svc.sendJSONPayload(context.Background(), provider, data)
|
||||
// Dispatch must succeed (no validation error) — the path traversal in the
|
||||
// token cannot redirect the request to a different host. The request was
|
||||
// received by our local server, not by evil.com.
|
||||
require.NoError(t, sendErr)
|
||||
// capturedPath is non-empty only if our server handled the request.
|
||||
assert.NotEmpty(t, capturedPath, "request must have been served by the local test server, not redirected to evil.com")
|
||||
}
|
||||
|
||||
func TestSendJSONPayload_Telegram_401ErrorMessage(t *testing.T) {
|
||||
// Use a webhook provider with a mock server returning 401 to verify
|
||||
// that the dispatch path surfaces "provider returned status 401" in the error.
|
||||
// Telegram cannot be tested this way because its SSRF check requires api.telegram.org.
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.WriteHeader(http.StatusUnauthorized)
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
db, err := gorm.Open(sqlite.Open("file::memory:"), &gorm.Config{})
|
||||
require.NoError(t, err)
|
||||
|
||||
svc := NewNotificationService(db, nil)
|
||||
|
||||
provider := models.NotificationProvider{
|
||||
Type: "webhook",
|
||||
URL: server.URL,
|
||||
Template: "custom",
|
||||
Config: `{"message": {{toJSON .Message}}}`,
|
||||
}
|
||||
|
||||
data := map[string]any{
|
||||
"Message": "Test notification",
|
||||
}
|
||||
|
||||
sendErr := svc.sendJSONPayload(context.Background(), provider, data)
|
||||
require.Error(t, sendErr)
|
||||
assert.Contains(t, sendErr.Error(), "provider returned status 401")
|
||||
}
|
||||
|
||||
@@ -1826,7 +1826,6 @@ func TestTestProvider_NotifyOnlyRejectsUnsupportedProvider(t *testing.T) {
|
||||
providerType string
|
||||
url string
|
||||
}{
|
||||
{"telegram", "telegram", "telegram://token@telegram?chats=123"},
|
||||
{"slack", "slack", "https://hooks.slack.com/services/T/B/X"},
|
||||
{"pushover", "pushover", "pushover://token@user"},
|
||||
}
|
||||
@@ -2883,108 +2882,290 @@ func TestDispatchEmail_TemplateFallback(t *testing.T) {
|
||||
// --- TestEmailProvider unit tests ---
|
||||
|
||||
func TestEmailProvider_MailServiceNil(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
svc := NewNotificationService(db, nil)
|
||||
db := setupNotificationTestDB(t)
|
||||
svc := NewNotificationService(db, nil)
|
||||
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "email service is not configured")
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "email service is not configured")
|
||||
}
|
||||
|
||||
func TestEmailProvider_MailServiceNotConfigured(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: false}
|
||||
svc := NewNotificationService(db, mock)
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: false}
|
||||
svc := NewNotificationService(db, mock)
|
||||
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "email service is not configured")
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "email service is not configured")
|
||||
}
|
||||
|
||||
func TestEmailProvider_EmptyURL(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true}
|
||||
svc := NewNotificationService(db, mock)
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true}
|
||||
svc := NewNotificationService(db, mock)
|
||||
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: ""}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "no recipients configured")
|
||||
assert.Zero(t, mock.callCount())
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: ""}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "no recipients configured")
|
||||
assert.Zero(t, mock.callCount())
|
||||
}
|
||||
|
||||
func TestEmailProvider_BlankWhitespaceURL(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true}
|
||||
svc := NewNotificationService(db, mock)
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true}
|
||||
svc := NewNotificationService(db, mock)
|
||||
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: " , , "}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "no recipients configured")
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: " , , "}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "no recipients configured")
|
||||
}
|
||||
|
||||
func TestEmailProvider_ValidRecipient(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true}
|
||||
svc := NewNotificationService(db, mock)
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true}
|
||||
svc := NewNotificationService(db, mock)
|
||||
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "user@example.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.NoError(t, err)
|
||||
require.Equal(t, 1, mock.callCount())
|
||||
call := mock.firstCall()
|
||||
assert.Equal(t, []string{"user@example.com"}, call.to)
|
||||
assert.Equal(t, "[Charon Test] Test Notification", call.subject)
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "user@example.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.NoError(t, err)
|
||||
require.Equal(t, 1, mock.callCount())
|
||||
call := mock.firstCall()
|
||||
assert.Equal(t, []string{"user@example.com"}, call.to)
|
||||
assert.Equal(t, "[Charon Test] Test Notification", call.subject)
|
||||
}
|
||||
|
||||
func TestEmailProvider_MultipleRecipients(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true}
|
||||
svc := NewNotificationService(db, mock)
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true}
|
||||
svc := NewNotificationService(db, mock)
|
||||
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com, c@d.com , e@f.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.NoError(t, err)
|
||||
require.Equal(t, 1, mock.callCount())
|
||||
assert.Equal(t, []string{"a@b.com", "c@d.com", "e@f.com"}, mock.firstCall().to)
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com, c@d.com , e@f.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.NoError(t, err)
|
||||
require.Equal(t, 1, mock.callCount())
|
||||
assert.Equal(t, []string{"a@b.com", "c@d.com", "e@f.com"}, mock.firstCall().to)
|
||||
}
|
||||
|
||||
func TestEmailProvider_SendError(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true, sendEmailErr: fmt.Errorf("smtp: connection refused")}
|
||||
svc := NewNotificationService(db, mock)
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true, sendEmailErr: fmt.Errorf("smtp: connection refused")}
|
||||
svc := NewNotificationService(db, mock)
|
||||
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "smtp")
|
||||
assert.Equal(t, 1, mock.callCount())
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "smtp")
|
||||
assert.Equal(t, 1, mock.callCount())
|
||||
}
|
||||
|
||||
func TestEmailProvider_TemplateFallback(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true, renderErr: fmt.Errorf("template not found")}
|
||||
svc := NewNotificationService(db, mock)
|
||||
db := setupNotificationTestDB(t)
|
||||
mock := &mockMailService{isConfigured: true, renderErr: fmt.Errorf("template not found")}
|
||||
svc := NewNotificationService(db, mock)
|
||||
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.NoError(t, err)
|
||||
require.Equal(t, 1, mock.callCount())
|
||||
assert.Contains(t, mock.firstCall().body, "<strong>Test Notification</strong>")
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.NoError(t, err)
|
||||
require.Equal(t, 1, mock.callCount())
|
||||
assert.Contains(t, mock.firstCall().body, "<strong>Test Notification</strong>")
|
||||
}
|
||||
|
||||
func TestEmailProvider_UsesRenderedTemplate(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
rendered := "<html><body>Rendered test email</body></html>"
|
||||
mock := &mockMailService{isConfigured: true, renderResult: rendered}
|
||||
svc := NewNotificationService(db, mock)
|
||||
db := setupNotificationTestDB(t)
|
||||
rendered := "<html><body>Rendered test email</body></html>"
|
||||
mock := &mockMailService{isConfigured: true, renderResult: rendered}
|
||||
svc := NewNotificationService(db, mock)
|
||||
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.NoError(t, err)
|
||||
require.Equal(t, 1, mock.callCount())
|
||||
assert.Equal(t, rendered, mock.firstCall().body)
|
||||
p := models.NotificationProvider{Name: "test-email", Type: "email", URL: "a@b.com"}
|
||||
err := svc.TestEmailProvider(p)
|
||||
require.NoError(t, err)
|
||||
require.Equal(t, 1, mock.callCount())
|
||||
assert.Equal(t, rendered, mock.firstCall().body)
|
||||
}
|
||||
|
||||
func TestIsDispatchEnabled_TelegramDefaultTrue(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
_ = db.AutoMigrate(&models.Setting{})
|
||||
svc := NewNotificationService(db, nil)
|
||||
|
||||
// No feature flag row exists — telegram defaults to true
|
||||
assert.True(t, svc.isDispatchEnabled("telegram"))
|
||||
}
|
||||
|
||||
func TestSendJSONPayload_Telegram_ChatIDInjectionAndDispatch(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
|
||||
var capturedPath string
|
||||
var capturedBody []byte
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
capturedPath = r.URL.Path
|
||||
capturedBody, _ = io.ReadAll(r.Body)
|
||||
w.WriteHeader(http.StatusOK)
|
||||
_, _ = w.Write([]byte(`{"ok":true}`))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
svc := NewNotificationService(db, nil)
|
||||
svc.telegramAPIBaseURL = server.URL
|
||||
|
||||
provider := models.NotificationProvider{
|
||||
Type: "telegram",
|
||||
URL: "123456789", // chat_id
|
||||
Token: "fake-bot-token", // bot token
|
||||
Template: "minimal",
|
||||
}
|
||||
data := map[string]any{
|
||||
"Title": "Test",
|
||||
"Message": "Hello Telegram",
|
||||
"Time": time.Now().Format(time.RFC3339),
|
||||
"EventType": "test",
|
||||
}
|
||||
|
||||
err := svc.sendJSONPayload(context.Background(), provider, data)
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, "/botfake-bot-token/sendMessage", capturedPath)
|
||||
|
||||
var payload map[string]any
|
||||
require.NoError(t, json.Unmarshal(capturedBody, &payload))
|
||||
assert.Equal(t, "123456789", payload["chat_id"])
|
||||
assert.Equal(t, "Hello Telegram", payload["text"])
|
||||
}
|
||||
|
||||
func TestSendJSONPayload_Telegram_NormalizesMessageToText(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
|
||||
var capturedBody []byte
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
capturedBody, _ = io.ReadAll(r.Body)
|
||||
w.WriteHeader(http.StatusOK)
|
||||
_, _ = w.Write([]byte(`{"ok":true}`))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
svc := NewNotificationService(db, nil)
|
||||
svc.telegramAPIBaseURL = server.URL
|
||||
|
||||
// Custom template that produces "message" key instead of "text" — exercises normalization.
|
||||
provider := models.NotificationProvider{
|
||||
Type: "telegram",
|
||||
URL: "987654321",
|
||||
Token: "fake-bot-token",
|
||||
Template: "custom",
|
||||
Config: `{"message": {{toJSON .Message}}}`,
|
||||
}
|
||||
data := map[string]any{
|
||||
"Title": "Test",
|
||||
"Message": "Normalize me",
|
||||
"Time": time.Now().Format(time.RFC3339),
|
||||
"EventType": "test",
|
||||
}
|
||||
|
||||
err := svc.sendJSONPayload(context.Background(), provider, data)
|
||||
require.NoError(t, err)
|
||||
|
||||
var payload map[string]any
|
||||
require.NoError(t, json.Unmarshal(capturedBody, &payload))
|
||||
// "message" must be promoted to "text" by the normalization path.
|
||||
assert.Equal(t, "Normalize me", payload["text"])
|
||||
assert.Equal(t, "987654321", payload["chat_id"])
|
||||
}
|
||||
|
||||
func TestSendJSONPayload_Telegram_RequiresTextField(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
svc := NewNotificationService(db, nil)
|
||||
|
||||
// Custom template missing both 'text' and 'message' keys
|
||||
provider := models.NotificationProvider{
|
||||
Type: "telegram",
|
||||
URL: "987654321",
|
||||
Token: "fake-bot-token",
|
||||
Template: "custom",
|
||||
Config: `{"title": {{toJSON .Title}}}`,
|
||||
}
|
||||
data := map[string]any{
|
||||
"Title": "Test",
|
||||
"Message": "Test Message",
|
||||
"Time": time.Now().Format(time.RFC3339),
|
||||
"EventType": "test",
|
||||
}
|
||||
|
||||
err := svc.sendJSONPayload(context.Background(), provider, data)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "telegram payload requires 'text' field")
|
||||
}
|
||||
|
||||
func TestSendJSONPayload_Telegram_HostnameValidationError(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
svc := NewNotificationService(db, nil)
|
||||
|
||||
// Token containing a null byte makes neturl.Parse fail,
|
||||
// triggering the hostname validation error path (line 496).
|
||||
provider := models.NotificationProvider{
|
||||
Type: "telegram",
|
||||
URL: "123456789",
|
||||
Token: "bad\x00token",
|
||||
Template: "minimal",
|
||||
}
|
||||
data := map[string]any{
|
||||
"Title": "Test",
|
||||
"Message": "Hello",
|
||||
"Time": time.Now().Format(time.RFC3339),
|
||||
"EventType": "test",
|
||||
}
|
||||
|
||||
err := svc.sendJSONPayload(context.Background(), provider, data)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "telegram dispatch URL validation failed")
|
||||
}
|
||||
|
||||
func TestSendJSONPayload_Telegram_MarshalErrorOnChatIDInjection(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
|
||||
var capturedBody []byte
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
capturedBody, _ = io.ReadAll(r.Body)
|
||||
w.WriteHeader(http.StatusOK)
|
||||
_, _ = w.Write([]byte(`{"ok":true}`))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
svc := NewNotificationService(db, nil)
|
||||
svc.telegramAPIBaseURL = server.URL
|
||||
|
||||
// Exercises the chat_id injection + marshal + body.Write path.
|
||||
provider := models.NotificationProvider{
|
||||
Type: "telegram",
|
||||
URL: "999888777",
|
||||
Token: "valid-bot-token",
|
||||
Template: "minimal",
|
||||
}
|
||||
data := map[string]any{
|
||||
"Title": "Chat ID Test",
|
||||
"Message": "Verify chat_id injected",
|
||||
"Time": time.Now().Format(time.RFC3339),
|
||||
"EventType": "test",
|
||||
}
|
||||
|
||||
err := svc.sendJSONPayload(context.Background(), provider, data)
|
||||
require.NoError(t, err)
|
||||
|
||||
var payload map[string]any
|
||||
require.NoError(t, json.Unmarshal(capturedBody, &payload))
|
||||
assert.Equal(t, "999888777", payload["chat_id"])
|
||||
assert.NotEmpty(t, payload["text"])
|
||||
}
|
||||
|
||||
func TestIsDispatchEnabled_TelegramDisabledByFlag(t *testing.T) {
|
||||
db := setupNotificationTestDB(t)
|
||||
_ = db.AutoMigrate(&models.Setting{})
|
||||
svc := NewNotificationService(db, nil)
|
||||
|
||||
// Explicitly disable telegram via feature flag
|
||||
db.Create(&models.Setting{Key: "feature.notifications.service.telegram.enabled", Value: "false"})
|
||||
assert.False(t, svc.isDispatchEnabled("telegram"))
|
||||
}
|
||||
|
||||
77
docs/issues/telegram-manual-testing.md
Normal file
77
docs/issues/telegram-manual-testing.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: "Manual Test Plan: Telegram Notification Provider"
|
||||
labels:
|
||||
- testing
|
||||
- frontend
|
||||
- backend
|
||||
- security
|
||||
priority: medium
|
||||
assignees: []
|
||||
---
|
||||
|
||||
# Manual Test Plan: Telegram Notification Provider
|
||||
|
||||
Scenarios that automated E2E tests cannot fully verify — real network calls, token redaction in DevTools, and cross-browser visual rendering.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A Telegram bot token (create one via [@BotFather](https://t.me/BotFather))
|
||||
- A Telegram chat ID (send a message to your bot, then check `https://api.telegram.org/bot<TOKEN>/getUpdates`)
|
||||
- Charon running locally or in Docker
|
||||
- Firefox, Chrome, and Safari available for cross-browser checks
|
||||
|
||||
---
|
||||
|
||||
## 1. Real Telegram Integration
|
||||
|
||||
- [ ] Navigate to **Settings → Notifications**
|
||||
- [ ] Click **Add Provider**, select **Telegram** type
|
||||
- [ ] Enter your real bot token and chat ID, give it a name, click **Save**
|
||||
- [ ] Click the **Send Test** button on the newly saved provider row
|
||||
- [ ] Open Telegram and confirm the test message arrived in your chat
|
||||
|
||||
## 2. Bot Token Security (DevTools)
|
||||
|
||||
- [ ] Open browser DevTools → **Network** tab
|
||||
- [ ] Load the Notifications page (refresh if needed)
|
||||
- [ ] Inspect the GET response that returns the provider list
|
||||
- [ ] Confirm the bot token value is **not** present in the response body — only `has_token: true` (or equivalent indicator)
|
||||
- [ ] Inspect the provider row in the UI — confirm the token is masked or hidden, never shown in plain text
|
||||
|
||||
## 3. Save-Before-Test UX
|
||||
|
||||
- [ ] Click **Add Provider**, select **Telegram** type
|
||||
- [ ] **Before saving**, locate the **Test** button
|
||||
- [ ] Confirm it is disabled (greyed out / not clickable)
|
||||
- [ ] Hover over or focus the disabled Test button and confirm a tooltip explains the provider must be saved first
|
||||
|
||||
## 4. Error Hint Display
|
||||
|
||||
- [ ] Add a new Telegram provider with an **invalid** bot token (e.g. `000000:FAKE`)
|
||||
- [ ] Save the provider, then click **Send Test**
|
||||
- [ ] Confirm a toast/notification appears containing a helpful hint (e.g. "Unauthorized" or "bot token is invalid")
|
||||
|
||||
## 5. Provider Type Switching
|
||||
|
||||
- [ ] Click **Add Provider**
|
||||
- [ ] Select **Discord** — note the visible form fields
|
||||
- [ ] Switch to **Telegram** — confirm a **Token** field and **Chat ID** field appear
|
||||
- [ ] Switch to **Webhook** — confirm Telegram-specific fields disappear and a URL field appears
|
||||
- [ ] Switch to **Gotify** — confirm a **Token** field appears (similar to Telegram)
|
||||
- [ ] Switch back to **Telegram** — confirm fields restore correctly with no leftover values
|
||||
|
||||
## 6. Keyboard Navigation
|
||||
|
||||
- [ ] Tab through the provider list using only the keyboard
|
||||
- [ ] For each provider row, confirm the **Send Test**, **Edit**, and **Delete** buttons are all reachable via Tab
|
||||
- [ ] Press Enter or Space on each button to confirm it activates
|
||||
- [ ] With a screen reader (or DevTools Accessibility panel), verify each button has a descriptive ARIA label (e.g. "Send test notification to My Telegram")
|
||||
|
||||
## 7. Cross-Browser Visual Check
|
||||
|
||||
For each browser — **Firefox**, **Chrome**, **Safari**:
|
||||
|
||||
- [ ] Load the Notifications page and confirm the provider list renders without layout issues
|
||||
- [ ] Open the Add/Edit provider form and confirm fields align correctly
|
||||
- [ ] Send a test notification and confirm the toast/notification displays properly
|
||||
- [ ] Resize the window to a narrow width and confirm the layout remains usable
|
||||
422
docs/plans/archive/codeql_hardening_spec.md
Normal file
422
docs/plans/archive/codeql_hardening_spec.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# Spec: Fix Remaining CodeQL Findings + Harden Local Security Scanning
|
||||
|
||||
**Branch:** `feature/beta-release`
|
||||
**PR:** #800 (Email Notifications)
|
||||
**Date:** 2026-03-06
|
||||
**Status:** Planning
|
||||
|
||||
---
|
||||
|
||||
## 1. Introduction
|
||||
|
||||
Two CodeQL findings remain open in CI after the email-injection remediation in the prior commit (`ee224adc`), and local scanning does not block commits that would reproduce them. This spec covers the root-cause analysis, the precise code fixes, and the hardening of the local scanning pipeline so future regressions are caught before push.
|
||||
|
||||
### Objectives
|
||||
|
||||
1. Silence `go/email-injection` (CWE-640) in CI without weakening the existing multi-layer defence.
|
||||
2. Silence `go/cookie-secure-not-set` (CWE-614) in CI for the intentional dev-mode loopback exception.
|
||||
3. Ensure local scanning fails (exit-code 1) on Critical/High security findings of the same class before code reaches GitHub.
|
||||
|
||||
---
|
||||
|
||||
## 2. Research Findings
|
||||
|
||||
### 2.1 CWE-640 (`go/email-injection`) — Why It Is Still Flagged
|
||||
|
||||
CodeQL's `go/email-injection` rule tracks untrusted input from HTTP sources to `smtp.SendMail` / `(*smtp.Client).Rcpt` sinks. It treats a **validator** (a function that returns an error if bad data is present) differently from a **sanitizer** (a function that transforms and strips the bad data). Only sanitizers break the taint flow; validators do not.
|
||||
|
||||
The previous fix added `sanitizeForEmail()` in `notification_service.go` for `title` and `message`. It did **not** patch two other direct callers of `SendEmail`, both of which pass an HTTP-sourced `to` address without going through `notification_service.go` at all.
|
||||
|
||||
#### Confirmed taint sinks (from `codeql-results-go.sarif`)
|
||||
|
||||
| SARIF line | Function | Tainted argument |
|
||||
|---|---|---|
|
||||
| 365–367 | `(*MailService).SendEmail` | `[]string{toEnvelope}` in `smtp.SendMail` |
|
||||
| ~530 | `(*MailService).sendSSL` | `toEnvelope` in `client.Rcpt(toEnvelope)` |
|
||||
| ~583 | `(*MailService).sendSTARTTLS` | `toEnvelope` in `client.Rcpt(toEnvelope)` |
|
||||
|
||||
CodeQL reports 4 untrusted taint paths converging on each sink. These correspond to:
|
||||
|
||||
| Path # | Source file | Source expression | Route to sink |
|
||||
|---|---|---|---|
|
||||
| 1 | `backend/internal/api/handlers/settings_handler.go:637` | `req.To` (ShouldBindJSON, `binding:"required,email"`) | Direct `h.MailService.SendEmail(ctx, []string{req.To}, ...)` — bypasses `notification_service.go` entirely |
|
||||
| 2 | `backend/internal/api/handlers/user_handler.go:597` | `userEmail` (HTTP request field) | `h.MailService.SendInvite(userEmail, ...)` → `mail_service.go:679` → `s.SendEmail(ctx, []string{email}, ...)` |
|
||||
| 3 | `backend/internal/api/handlers/user_handler.go:1015` | `user.Email` (DB row, set from HTTP during registration) | Same `SendInvite` → `SendEmail` chain |
|
||||
| 4 | `backend/internal/services/notification_service.go` | `rawRecipients` from `p.URL` (DB, admin-set) | `s.mailService.SendEmail(ctx, recipients, ...)` — CodeQL may trace DB values as tainted from prior HTTP writes |
|
||||
|
||||
#### Why CodeQL does not recognise the existing safeguards as sanitisers
|
||||
|
||||
```
|
||||
validateEmailRecipients() → ContainsAny check + mail.ParseAddress → error return (validator, not sanitizer)
|
||||
parseEmailAddressForHeader → net/mail.ParseAddress → validator
|
||||
rejectCRLF(toEnvelope) → ContainsAny("\r\n") → error → validator
|
||||
```
|
||||
|
||||
CodeQL's taint model for Go requires the taint to be **transformed** (characters stripped or value replaced) before it considers the path neutralised. None of the helpers above strips CRLF — they gate on error returns. From CodeQL's perspective the original tainted bytes still flow into `smtp.SendMail`.
|
||||
|
||||
#### Why adding `sanitizeForEmail()` to `settings_handler.go` alone is insufficient
|
||||
|
||||
Even if added, `sanitizeForEmail()` calls `strings.ReplaceAll(s, "\r", "")` — stripping characters from an email address that contains `\r` would corrupt it. For recipient addresses, the correct model is to validate (which is already done) and suppress the residual finding with an annotated justification.
|
||||
|
||||
### 2.2 CWE-614 (`go/cookie-secure-not-set`) — Why It Appeared as "New"
|
||||
|
||||
**Only one `c.SetCookie` call exists** in production Go code:
|
||||
|
||||
```
|
||||
backend/internal/api/handlers/auth_handler.go:152
|
||||
```
|
||||
|
||||
The finding is "new" because it was introduced when `setSecureCookie()` was refactored to support the loopback dev-mode exception (`secure = false` for local HTTP requests). Prior to that refactor, `secure` was always `true`.
|
||||
|
||||
The `// codeql[go/cookie-secure-not-set]` suppression comment **is** present on `auth_handler.go:152`. However, the SARIF stored in the repository (`codeql-results-go.sarif`) shows the finding at **line 151** — a 1-line discrepancy caused by a subsequent commit that inserted the `// secure is intentionally false...` explanation comment, shifting the `c.SetCookie(` line from 151 → 152.
|
||||
|
||||
The inline suppression **should** work now that it is on the correct line (152). However, inline suppressions are fragile under line-number churn. The robust fix is a `query-filter` in `.github/codeql/codeql-config.yml`, which targets the rule ID independent of line number.
|
||||
|
||||
The `query-filters` section does not yet exist in the CodeQL config — only `paths-ignore` is used. This must be added for the first time.
|
||||
|
||||
### 2.3 Local Scanning Gap
|
||||
|
||||
The table below maps which security tools catch which findings locally.
|
||||
|
||||
| Tool | Stage | Fails on High/Critical? | Catches CWE-640? | Catches CWE-614? |
|
||||
|---|---|---|---|---|
|
||||
| `golangci-lint-fast` (gosec G101,G110,G305,G401,G501-503) | commit (blocking) | ✅ | ❌ no rule | ❌ gosec has no Gin cookie rule |
|
||||
| `go-vet` | commit (blocking) | ✅ | ❌ | ❌ |
|
||||
| `security-scan.sh` (govulncheck) | manual | Warn only | ❌ (CVEs only) | ❌ |
|
||||
| `semgrep-scan.sh` (auto config, `--error`) | **manual only** | ✅ if run | ✅ `p/golang` | ✅ `p/golang` |
|
||||
| `codeql-go-scan` + `codeql-check-findings` | **manual only** | ✅ if run | ✅ | ✅ |
|
||||
| `golangci-lint-full` | manual | ✅ if run | ❌ | ❌ |
|
||||
|
||||
**The gap:** `semgrep-scan` already has `--error` (blocking) and covers both issue classes via `p/golang` and `p/owasp-top-ten`, but it runs as `stages: [manual]` only. Moving it to `pre-push` is the highest-leverage single change.
|
||||
|
||||
gosec rule audit for missing coverage:
|
||||
|
||||
| CWE | gosec rule | Covered by fast config? |
|
||||
|---|---|---|
|
||||
| CWE-614 cookie security | No standard gosec rule for Gin's `c.SetCookie` | ❌ |
|
||||
| CWE-640 email injection | No gosec rule exists for SMTP injection | ❌ |
|
||||
| CWE-89 SQL injection | G201, G202 — NOT in fast config | ❌ |
|
||||
| CWE-22 path traversal | G305 — in fast config | ✅ |
|
||||
|
||||
`semgrep` fills the gap for CWE-614 and CWE-640 where gosec has no rules.
|
||||
|
||||
---
|
||||
|
||||
## 3. Technical Specifications
|
||||
|
||||
### 3.1 Phase 1 — Harden Local Scanning
|
||||
|
||||
#### 3.1.1 Move `semgrep-scan` to `pre-push` stage
|
||||
|
||||
**File:** `/projects/Charon/.pre-commit-config.yaml`
|
||||
|
||||
Locate the `semgrep-scan` hook entry (currently has `stages: [manual]`). Change the stage and name:
|
||||
|
||||
```yaml
|
||||
- id: semgrep-scan
|
||||
name: Semgrep Security Scan (Blocking - pre-push)
|
||||
entry: scripts/pre-commit-hooks/semgrep-scan.sh
|
||||
language: script
|
||||
pass_filenames: false
|
||||
verbose: true
|
||||
stages: [pre-push]
|
||||
```
|
||||
|
||||
Rationale: `p/golang` includes:
|
||||
- `go.cookie.security.insecure-cookie.insecure-cookie` → CWE-614 equivalent
|
||||
- `go.lang.security.injection.tainted-smtp-email.tainted-smtp-email` → CWE-640 equivalent
|
||||
|
||||
#### 3.1.2 Restrict semgrep to WARNING+ and use targeted config
|
||||
|
||||
**File:** `/projects/Charon/scripts/pre-commit-hooks/semgrep-scan.sh`
|
||||
|
||||
The current invocation uses `--config auto --error`. Two changes:
|
||||
1. Change default config from `auto` → `p/golang`. `auto` fetches 1,000-3,000+ rules and takes 60-180s — too slow for a blocking pre-push hook. `p/golang` covers all Go-specific OWASP/CWE rules and completes in ~10-30s.
|
||||
2. Add `--severity ERROR --severity WARNING` to filter out INFO-level noise (these are OR logic, both required for WARNING+):
|
||||
|
||||
```bash
|
||||
semgrep scan \
|
||||
--config "${SEMGREP_CONFIG_VALUE:-p/golang}" \
|
||||
--severity ERROR \
|
||||
--severity WARNING \
|
||||
--error \
|
||||
--exclude "frontend/node_modules" \
|
||||
--exclude "frontend/coverage" \
|
||||
--exclude "frontend/dist" \
|
||||
backend frontend/src .github/workflows
|
||||
```
|
||||
|
||||
The `SEMGREP_CONFIG` env var can be overridden to `auto` or `p/golang p/owasp-top-ten` for a broader audit: `SEMGREP_CONFIG=auto git push`.
|
||||
|
||||
#### 3.1.3 Add `make security-local` target
|
||||
|
||||
**File:** `/projects/Charon/Makefile`
|
||||
|
||||
Add after the `security-scan-deps` target:
|
||||
|
||||
```make
|
||||
security-local: ## Run local security scan (govulncheck + semgrep)
|
||||
@echo "Running govulncheck..."
|
||||
@./scripts/security-scan.sh
|
||||
@echo "Running semgrep..."
|
||||
@SEMGREP_CONFIG=p/golang ./scripts/pre-commit-hooks/semgrep-scan.sh
|
||||
```
|
||||
|
||||
#### 3.1.4 Expand golangci-lint-fast gosec ruleset (Deferred)
|
||||
|
||||
**Status: DEFERRED** — G201/G202 (SQL injection via format string / string concat) are candidates for the fast config but must be pre-validated against the existing codebase first. GORM's raw query DSL can produce false positives. Run the following before adding:
|
||||
|
||||
```bash
|
||||
cd backend && golangci-lint run --enable=gosec --disable-all --config .golangci-fast.yml ./...
|
||||
```
|
||||
|
||||
…with G201/G202 temporarily uncommented. If zero false positives, add in a separate hardening commit. This is out of scope for this PR to avoid blocking PR #800.
|
||||
|
||||
Note: CWE-614 and CWE-640 remain CodeQL/Semgrep territory — gosec has no rules for these.
|
||||
|
||||
### 3.2 Phase 2 — Fix CWE-640 (`go/email-injection`)
|
||||
|
||||
#### Strategy
|
||||
|
||||
Add `// codeql[go/email-injection]` inline suppression annotations at all three sink sites in `mail_service.go`, with a structured justification comment immediately above each. This is the correct approach because:
|
||||
|
||||
1. The actual runtime defence is already correct and comprehensive (4-layer defence).
|
||||
2. The taint is a CodeQL false-positive caused by the tool not modelling validators as sanitisers.
|
||||
3. Restructuring to call `strings.ReplaceAll` on email addresses would corrupt valid addresses.
|
||||
|
||||
**The 4-layer defence that justifies these suppressions:**
|
||||
|
||||
```
|
||||
Layer 1: HTTP boundary — gin binding:"required,email" validates RFC 5321 format; CRLF fails well-formedness
|
||||
Layer 2: Service boundary — validateEmailRecipients() → ContainsAny("\r\n") error + net/mail.ParseAddress
|
||||
Layer 3: Mail layer parse — parseEmailAddressForHeader() → net/mail.ParseAddress returns only .Address field
|
||||
Layer 4: Pre-sink validation — rejectCRLF(toEnvelope) immediately before smtp.SendMail / client.Rcpt calls
|
||||
```
|
||||
|
||||
#### 3.2.1 Suppress at `smtp.SendMail` sink
|
||||
|
||||
**File:** `backend/internal/services/mail_service.go` (around line 367)
|
||||
|
||||
Locate the default-encryption branch in `SendEmail`. Replace the `smtp.SendMail` call line:
|
||||
|
||||
```go
|
||||
default:
|
||||
// toEnvelope passes through 4-layer CRLF defence:
|
||||
// 1. gin binding:"required,email" at HTTP entry (CRLF invalid per RFC 5321)
|
||||
// 2. validateEmailRecipients → ContainsAny("\r\n") + net/mail.ParseAddress
|
||||
// 3. parseEmailAddressForHeader → net/mail.ParseAddress (returns .Address only)
|
||||
// 4. rejectCRLF(toEnvelope) guard earlier in this function
|
||||
// CodeQL does not model validators as sanitisers; suppression is correct here.
|
||||
if err := smtp.SendMail(addr, auth, fromEnvelope, []string{toEnvelope}, msg); err != nil { // codeql[go/email-injection]
|
||||
```
|
||||
|
||||
#### 3.2.2 Suppress at `client.Rcpt` in `sendSSL`
|
||||
|
||||
**File:** `backend/internal/services/mail_service.go` (around line 530)
|
||||
|
||||
Locate in `sendSSL`. Replace the `client.Rcpt` call line:
|
||||
|
||||
```go
|
||||
// toEnvelope validated by rejectCRLF + net/mail.ParseAddress before this call (see SendEmail).
|
||||
if rcptErr := client.Rcpt(toEnvelope); rcptErr != nil { // codeql[go/email-injection]
|
||||
return fmt.Errorf("RCPT TO failed: %w", rcptErr)
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.3 Suppress at `client.Rcpt` in `sendSTARTTLS`
|
||||
|
||||
**File:** `backend/internal/services/mail_service.go` (around line 583)
|
||||
|
||||
Same pattern as sendSSL:
|
||||
|
||||
```go
|
||||
// toEnvelope validated by rejectCRLF + net/mail.ParseAddress before this call (see SendEmail).
|
||||
if rcptErr := client.Rcpt(toEnvelope); rcptErr != nil { // codeql[go/email-injection]
|
||||
return fmt.Errorf("RCPT TO failed: %w", rcptErr)
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.4 Document safe call in `settings_handler.go`
|
||||
|
||||
**File:** `backend/internal/api/handlers/settings_handler.go` (around line 637)
|
||||
|
||||
Add a comment immediately above the `SendEmail` call — the sinks in mail_service.go are already annotated, so this is documentation only:
|
||||
|
||||
```go
|
||||
// req.To is validated as RFC 5321 email via gin binding:"required,email".
|
||||
// SendEmail applies validateEmailRecipients + net/mail.ParseAddress + rejectCRLF as defence-in-depth.
|
||||
// Suppression annotations are on the sinks in mail_service.go.
|
||||
if err := h.MailService.SendEmail(c.Request.Context(), []string{req.To}, "Charon - Test Email", htmlBody); err != nil {
|
||||
```
|
||||
|
||||
#### 3.2.5 Document safe calls in `user_handler.go`
|
||||
|
||||
**File:** `backend/internal/api/handlers/user_handler.go` (lines ~597 and ~1015)
|
||||
|
||||
Add the same explanatory comment above both `SendInvite` call sites:
|
||||
|
||||
```go
|
||||
// userEmail validated as RFC 5321 email format; suppression on mail_service.go sinks covers this path.
|
||||
if err := h.MailService.SendInvite(userEmail, userToken, appName, baseURL); err != nil {
|
||||
```
|
||||
|
||||
### 3.3 Phase 3 — Fix CWE-614 (`go/cookie-secure-not-set`)
|
||||
|
||||
#### Strategy
|
||||
|
||||
Two complementary changes: (1) add a `query-filters` exclusion in `.github/codeql/codeql-config.yml` which is robust to line-number churn, and (2) verify the inline `// codeql[go/cookie-secure-not-set]` annotation is correctly positioned.
|
||||
|
||||
**Justification for exclusion:**
|
||||
|
||||
The `secure` parameter in `setSecureCookie()` is `true` for **all** external production requests. It is `false` only when `isLocalRequest()` returns `true` — i.e., when the request comes from `127.x.x.x`, `::1`, or `localhost` over HTTP. In that scenario, browsers reject `Secure` cookies over non-TLS connections anyway, so setting `Secure: true` would silently break auth for local development. The conditional is tested and documented.
|
||||
|
||||
#### 3.3.1 Skip `query-filters` approach — inline annotation is sufficient
|
||||
|
||||
**Status: NOT IMPLEMENTING** — `query-filters` is a CodeQL query suite (`.qls`) concept, NOT a valid top-level key in GitHub's `codeql-config.yml`. Adding it risks silent failure or breaking the entire CodeQL analysis. The inline annotation at `auth_handler.go:152` is the documented mechanism and is already correct. No changes to `.github/codeql/codeql-config.yml` are needed for CWE-614.
|
||||
|
||||
**Why inline annotation is sufficient and preferred:** It is scoped to the single intentional instance. Any future `c.SetCookie(...)` call without `Secure:true` anywhere else in the codebase will correctly flag. Global exclusion via config would silently hide future regressions.
|
||||
|
||||
#### 3.3.1 (REFERENCE ONLY) Current valid `codeql-config.yml` structure
|
||||
|
||||
```yaml
|
||||
name: "Charon CodeQL Config"
|
||||
|
||||
# Paths to ignore from all analysis (use sparingly - prefer query-filters for rule-level exclusions)
|
||||
paths-ignore:
|
||||
- "frontend/coverage/**"
|
||||
- "frontend/dist/**"
|
||||
- "playwright-report/**"
|
||||
- "test-results/**"
|
||||
- "coverage/**"
|
||||
```
|
||||
|
||||
DO NOT add `query-filters:` — it is not supported.
|
||||
- exclude:
|
||||
id: go/cookie-secure-not-set
|
||||
# Justified: setSecureCookie() in auth_handler.go intentionally sets Secure=false
|
||||
# ONLY for local loopback (127.x.x.x / ::1 / localhost) HTTP requests.
|
||||
# Browsers reject Secure cookies over HTTP regardless, so Secure=true would silently
|
||||
# break local development auth. All external HTTPS flows always set Secure=true.
|
||||
# Code: backend/internal/api/handlers/auth_handler.go → setSecureCookie()
|
||||
# Tests: TestSetSecureCookie_HTTPS_Strict, TestSetSecureCookie_HTTP_Loopback_Insecure
|
||||
```
|
||||
|
||||
#### 3.3.2 Verify inline suppression placement in `auth_handler.go`
|
||||
|
||||
**File:** `backend/internal/api/handlers/auth_handler.go` (around line 152)
|
||||
|
||||
Confirm the `// codeql[go/cookie-secure-not-set]` annotation is on the same line as `c.SetCookie(`. The code should read:
|
||||
|
||||
```go
|
||||
c.SetSameSite(sameSite)
|
||||
// secure is intentionally false for local non-HTTPS loopback (development only).
|
||||
c.SetCookie( // codeql[go/cookie-secure-not-set]
|
||||
name,
|
||||
value,
|
||||
maxAge,
|
||||
"/",
|
||||
domain,
|
||||
secure,
|
||||
true,
|
||||
)
|
||||
```
|
||||
|
||||
The `query-filters` in §3.3.1 provides the primary fix. The inline annotation provides belt-and-suspenders coverage that survives if the config is ever reset.
|
||||
|
||||
---
|
||||
|
||||
## 4. Implementation Plan
|
||||
|
||||
### Phase 1 — Local Scanning (implement first to gate subsequent work)
|
||||
|
||||
| Task | File | Change | Effort |
|
||||
|---|---|---|---|
|
||||
| P1-1 | `.pre-commit-config.yaml` | Change semgrep-scan stage from `[manual]` → `[pre-push]`, update name | XS |
|
||||
| P1-2 | `scripts/pre-commit-hooks/semgrep-scan.sh` | Add `--severity ERROR --severity WARNING` flags, exclude generated dirs | XS |
|
||||
| P1-3 | `Makefile` | Add `security-local` target | XS |
|
||||
| P1-4 | `backend/.golangci-fast.yml` | Add G201, G202 to gosec includes | XS |
|
||||
|
||||
### Phase 2 — CWE-640 Fix
|
||||
|
||||
| Task | File | Change | Effort |
|
||||
|---|---|---|---|
|
||||
| P2-1 | `backend/internal/services/mail_service.go` | Add `// codeql[go/email-injection]` on smtp.SendMail line + 4-layer defence comment | XS |
|
||||
| P2-2 | `backend/internal/services/mail_service.go` | Add `// codeql[go/email-injection]` on sendSSL client.Rcpt line | XS |
|
||||
| P2-3 | `backend/internal/services/mail_service.go` | Add `// codeql[go/email-injection]` on sendSTARTTLS client.Rcpt line | XS |
|
||||
| P2-4 | `backend/internal/api/handlers/settings_handler.go` | Add explanatory comment above SendEmail call | XS |
|
||||
| P2-5 | `backend/internal/api/handlers/user_handler.go` | Add explanatory comment above both SendInvite calls (~line 597, ~line 1015) | XS |
|
||||
|
||||
### Phase 3 — CWE-614 Fix
|
||||
|
||||
| Task | File | Change | Effort |
|
||||
|---|---|---|---|
|
||||
| P3-1 | `backend/internal/api/handlers/auth_handler.go` | Verify `// codeql[go/cookie-secure-not-set]` is on `c.SetCookie(` line (no codeql-config.yml changes needed) | XS |
|
||||
|
||||
**Total estimated file changes: 6 files, all comment/config additions — no logic changes.**
|
||||
|
||||
---
|
||||
|
||||
## 5. Acceptance Criteria
|
||||
|
||||
### CI (CodeQL must pass with zero error-level findings)
|
||||
|
||||
- [ ] `codeql.yml` CodeQL analysis (Go) passes with **0 blocking findings**
|
||||
- [ ] `go/email-injection` is absent from the Go SARIF output
|
||||
- [ ] `go/cookie-secure-not-set` is absent from the Go SARIF output
|
||||
|
||||
### Local scanning
|
||||
|
||||
- [ ] A `git push` with any `.go` file touched **blocks** if semgrep finds WARNING+ severity issues
|
||||
- [ ] `pre-commit run semgrep-scan` on the current codebase exits 0 (no new findings)
|
||||
- [ ] `make security-local` runs and exits 0
|
||||
|
||||
### Regression safety
|
||||
|
||||
- [ ] `go test ./...` in `backend/` passes (all changes are comments/config — no test updates required)
|
||||
- [ ] `golangci-lint run --config .golangci-fast.yml ./...` passes in `backend/`
|
||||
- [ ] The existing runtime defence (rejectCRLF, validateEmailRecipients) is **unchanged** — confirmed by diff
|
||||
|
||||
---
|
||||
|
||||
## 6. Commit Slicing Strategy
|
||||
|
||||
### Decision: Single commit on `feature/beta-release`
|
||||
|
||||
**Rationale:** All three phases are tightly related (one CI failure, two root findings, one local gap). All changes are additive (comments, config, no logic mutations). Splitting into multiple PRs would create an intermediate state where CI still fails and the local gap remains open. A single well-scoped commit keeps PR #800 atomic and reviewable.
|
||||
|
||||
**Suggested commit message:**
|
||||
```
|
||||
fix(security): suppress CodeQL false-positives for email-injection and cookie-secure
|
||||
|
||||
CWE-640 (go/email-injection): Add // codeql[go/email-injection] annotations at all 3
|
||||
smtp sink sites in mail_service.go (smtp.SendMail, sendSSL client.Rcpt, sendSTARTTLS
|
||||
client.Rcpt). The 4-layer defence (gin binding:"required,email", validateEmailRecipients,
|
||||
net/mail.ParseAddress, rejectCRLF) is comprehensive; CodeQL's taint model does not
|
||||
model validators as sanitisers, producing false-positive paths from
|
||||
settings_handler.go:637 and user_handler.go invite flows that bypass
|
||||
notification_service.go.
|
||||
|
||||
CWE-614 (go/cookie-secure-not-set): Add query-filter to codeql-config.yml excluding
|
||||
this rule with documented justification. setSecureCookie() correctly sets Secure=false
|
||||
only for local loopback HTTP requests where the Secure attribute is browser-rejected.
|
||||
All external HTTPS flows set Secure=true.
|
||||
|
||||
Local scanning: Promote semgrep-scan from manual to pre-push stage so WARNING+
|
||||
severity findings block push. Addresses gap where CWE-614 and CWE-640 equivalents
|
||||
are not covered by any blocking local scan tool.
|
||||
```
|
||||
|
||||
**PR:** All changes target PR #800 directly.
|
||||
|
||||
---
|
||||
|
||||
## 7. Risk and Rollback
|
||||
|
||||
| Risk | Likelihood | Mitigation |
|
||||
|---|---|---|
|
||||
| Inline suppression ends up on wrong line after future rebase | Medium | `query-filters` in codeql-config.yml provides independent suppression independent of line numbers |
|
||||
| `semgrep-scan` at `pre-push` produces false-positive blocking | Low | `--severity WARNING --error` limits to genuine findings; use `SEMGREP_CONFIG=p/golang` for targeted override |
|
||||
| G201/G202 gosec rules trigger on existing legitimate code | Low | Run `golangci-lint run --config .golangci-fast.yml` locally before committing; suppress specific instances if needed |
|
||||
| CodeQL `query-filters` YAML syntax changes in future GitHub CodeQL versions | Low | Inline `// codeql[...]` annotations serve as independent fallback |
|
||||
|
||||
**Rollback:** All changes are additive config and comments. Reverting the commit restores the prior state exactly. No schema, API, or behaviour changes are made.
|
||||
@@ -1,422 +1,497 @@
|
||||
# Spec: Fix Remaining CodeQL Findings + Harden Local Security Scanning
|
||||
# Telegram Notification Provider — Test Failure Remediation Plan
|
||||
|
||||
**Branch:** `feature/beta-release`
|
||||
**PR:** #800 (Email Notifications)
|
||||
**Date:** 2026-03-06
|
||||
**Status:** Planning
|
||||
**Date:** 2026-03-11
|
||||
**Author:** Planning Agent
|
||||
**Status:** Remediation Required — All security scans pass, test failures block merge
|
||||
**Previous Plan:** Archived as `docs/plans/telegram_implementation_spec.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. Introduction
|
||||
|
||||
Two CodeQL findings remain open in CI after the email-injection remediation in the prior commit (`ee224adc`), and local scanning does not block commits that would reproduce them. This spec covers the root-cause analysis, the precise code fixes, and the hardening of the local scanning pipeline so future regressions are caught before push.
|
||||
The Telegram notification provider feature is functionally complete with passing security scans and coverage gates. However, **56 E2E test failures** and **2 frontend unit test failures** block the PR merge. This plan identifies root causes, categorises each failure set, and provides specific remediation steps.
|
||||
|
||||
### Objectives
|
||||
### Failure Summary
|
||||
|
||||
1. Silence `go/email-injection` (CWE-640) in CI without weakening the existing multi-layer defence.
|
||||
2. Silence `go/cookie-secure-not-set` (CWE-614) in CI for the intentional dev-mode loopback exception.
|
||||
3. Ensure local scanning fails (exit-code 1) on Critical/High security findings of the same class before code reaches GitHub.
|
||||
|
||||
---
|
||||
|
||||
## 2. Research Findings
|
||||
|
||||
### 2.1 CWE-640 (`go/email-injection`) — Why It Is Still Flagged
|
||||
|
||||
CodeQL's `go/email-injection` rule tracks untrusted input from HTTP sources to `smtp.SendMail` / `(*smtp.Client).Rcpt` sinks. It treats a **validator** (a function that returns an error if bad data is present) differently from a **sanitizer** (a function that transforms and strips the bad data). Only sanitizers break the taint flow; validators do not.
|
||||
|
||||
The previous fix added `sanitizeForEmail()` in `notification_service.go` for `title` and `message`. It did **not** patch two other direct callers of `SendEmail`, both of which pass an HTTP-sourced `to` address without going through `notification_service.go` at all.
|
||||
|
||||
#### Confirmed taint sinks (from `codeql-results-go.sarif`)
|
||||
|
||||
| SARIF line | Function | Tainted argument |
|
||||
|---|---|---|
|
||||
| 365–367 | `(*MailService).SendEmail` | `[]string{toEnvelope}` in `smtp.SendMail` |
|
||||
| ~530 | `(*MailService).sendSSL` | `toEnvelope` in `client.Rcpt(toEnvelope)` |
|
||||
| ~583 | `(*MailService).sendSTARTTLS` | `toEnvelope` in `client.Rcpt(toEnvelope)` |
|
||||
|
||||
CodeQL reports 4 untrusted taint paths converging on each sink. These correspond to:
|
||||
|
||||
| Path # | Source file | Source expression | Route to sink |
|
||||
|---|---|---|---|
|
||||
| 1 | `backend/internal/api/handlers/settings_handler.go:637` | `req.To` (ShouldBindJSON, `binding:"required,email"`) | Direct `h.MailService.SendEmail(ctx, []string{req.To}, ...)` — bypasses `notification_service.go` entirely |
|
||||
| 2 | `backend/internal/api/handlers/user_handler.go:597` | `userEmail` (HTTP request field) | `h.MailService.SendInvite(userEmail, ...)` → `mail_service.go:679` → `s.SendEmail(ctx, []string{email}, ...)` |
|
||||
| 3 | `backend/internal/api/handlers/user_handler.go:1015` | `user.Email` (DB row, set from HTTP during registration) | Same `SendInvite` → `SendEmail` chain |
|
||||
| 4 | `backend/internal/services/notification_service.go` | `rawRecipients` from `p.URL` (DB, admin-set) | `s.mailService.SendEmail(ctx, recipients, ...)` — CodeQL may trace DB values as tainted from prior HTTP writes |
|
||||
|
||||
#### Why CodeQL does not recognise the existing safeguards as sanitisers
|
||||
|
||||
```
|
||||
validateEmailRecipients() → ContainsAny check + mail.ParseAddress → error return (validator, not sanitizer)
|
||||
parseEmailAddressForHeader → net/mail.ParseAddress → validator
|
||||
rejectCRLF(toEnvelope) → ContainsAny("\r\n") → error → validator
|
||||
```
|
||||
|
||||
CodeQL's taint model for Go requires the taint to be **transformed** (characters stripped or value replaced) before it considers the path neutralised. None of the helpers above strips CRLF — they gate on error returns. From CodeQL's perspective the original tainted bytes still flow into `smtp.SendMail`.
|
||||
|
||||
#### Why adding `sanitizeForEmail()` to `settings_handler.go` alone is insufficient
|
||||
|
||||
Even if added, `sanitizeForEmail()` calls `strings.ReplaceAll(s, "\r", "")` — stripping characters from an email address that contains `\r` would corrupt it. For recipient addresses, the correct model is to validate (which is already done) and suppress the residual finding with an annotated justification.
|
||||
|
||||
### 2.2 CWE-614 (`go/cookie-secure-not-set`) — Why It Appeared as "New"
|
||||
|
||||
**Only one `c.SetCookie` call exists** in production Go code:
|
||||
|
||||
```
|
||||
backend/internal/api/handlers/auth_handler.go:152
|
||||
```
|
||||
|
||||
The finding is "new" because it was introduced when `setSecureCookie()` was refactored to support the loopback dev-mode exception (`secure = false` for local HTTP requests). Prior to that refactor, `secure` was always `true`.
|
||||
|
||||
The `// codeql[go/cookie-secure-not-set]` suppression comment **is** present on `auth_handler.go:152`. However, the SARIF stored in the repository (`codeql-results-go.sarif`) shows the finding at **line 151** — a 1-line discrepancy caused by a subsequent commit that inserted the `// secure is intentionally false...` explanation comment, shifting the `c.SetCookie(` line from 151 → 152.
|
||||
|
||||
The inline suppression **should** work now that it is on the correct line (152). However, inline suppressions are fragile under line-number churn. The robust fix is a `query-filter` in `.github/codeql/codeql-config.yml`, which targets the rule ID independent of line number.
|
||||
|
||||
The `query-filters` section does not yet exist in the CodeQL config — only `paths-ignore` is used. This must be added for the first time.
|
||||
|
||||
### 2.3 Local Scanning Gap
|
||||
|
||||
The table below maps which security tools catch which findings locally.
|
||||
|
||||
| Tool | Stage | Fails on High/Critical? | Catches CWE-640? | Catches CWE-614? |
|
||||
| Spec File | Failures | Browsers | Unique Est. | Category |
|
||||
|---|---|---|---|---|
|
||||
| `golangci-lint-fast` (gosec G101,G110,G305,G401,G501-503) | commit (blocking) | ✅ | ❌ no rule | ❌ gosec has no Gin cookie rule |
|
||||
| `go-vet` | commit (blocking) | ✅ | ❌ | ❌ |
|
||||
| `security-scan.sh` (govulncheck) | manual | Warn only | ❌ (CVEs only) | ❌ |
|
||||
| `semgrep-scan.sh` (auto config, `--error`) | **manual only** | ✅ if run | ✅ `p/golang` | ✅ `p/golang` |
|
||||
| `codeql-go-scan` + `codeql-check-findings` | **manual only** | ✅ if run | ✅ | ✅ |
|
||||
| `golangci-lint-full` | manual | ✅ if run | ❌ | ❌ |
|
||||
| `notifications.spec.ts` | 48 | 3 | ~16 | **Our change** |
|
||||
| `notifications-payload.spec.ts` | 18 | 3 | ~6 | **Our change** |
|
||||
| `telegram-notification-provider.spec.ts` | 4 | 1–3 | ~2 | **Our change** |
|
||||
| `encryption-management.spec.ts` | 20 | 3 | ~7 | Pre-existing |
|
||||
| `auth-middleware-cascade.spec.ts` | 18 | 3 | 6 | Pre-existing |
|
||||
| `Notifications.test.tsx` (unit) | 2 | — | 2 | **Our change** |
|
||||
|
||||
**The gap:** `semgrep-scan` already has `--error` (blocking) and covers both issue classes via `p/golang` and `p/owasp-top-ten`, but it runs as `stages: [manual]` only. Moving it to `pre-push` is the highest-leverage single change.
|
||||
CI retries: 2 per test (`playwright.config.js` L144). Failure counts above represent unique test failures × browser projects.
|
||||
|
||||
gosec rule audit for missing coverage:
|
||||
---
|
||||
|
||||
| CWE | gosec rule | Covered by fast config? |
|
||||
## 2. Root Cause Analysis
|
||||
|
||||
### Root Cause A: `isNew` Guard on Test Button (CRITICAL — Causes ~80% of failures)
|
||||
|
||||
**What changed:** The Telegram feature added a guard in `Notifications.tsx` (L117-124) that blocks the "Test" button for new (unsaved) providers:
|
||||
|
||||
```typescript
|
||||
// Line 117-124: handleTest() early return guard
|
||||
const handleTest = () => {
|
||||
const formData = watch();
|
||||
const currentType = normalizeProviderType(formData.type);
|
||||
if (!formData.id && currentType !== 'email') {
|
||||
toast.error(t('notificationProviders.saveBeforeTesting'));
|
||||
return;
|
||||
}
|
||||
testMutation.mutate({ ...formData, type: currentType } as Partial<NotificationProvider>);
|
||||
};
|
||||
```
|
||||
|
||||
And a `disabled` attribute on the test button at `Notifications.tsx` (L382):
|
||||
|
||||
```typescript
|
||||
// Line 382: Button disabled state
|
||||
disabled={testMutation.isPending || (isNew && !isEmail)}
|
||||
```
|
||||
|
||||
**Why it was added:** The backend `Test` handler at `notification_provider_handler.go` (L333-336) requires a saved provider ID for all non-email types. For Gotify/Telegram, the server needs the stored token. For Discord/Webhook, the server still fetches the provider from DB. Without a saved provider, the backend returns `MISSING_PROVIDER_ID`.
|
||||
|
||||
**Why it breaks tests:** Many existing E2E and unit tests click the test button from a **new (unsaved) provider form** using mocked endpoints. With the new guard:
|
||||
1. The `<button>` is `disabled` → browser ignores clicks → mocked routes never receive requests
|
||||
2. Even if not disabled, `handleTest()` returns early with a toast instead of calling `testMutation.mutate()`
|
||||
3. Tests that `waitForRequest` on `/providers/test` time out (60s default)
|
||||
4. Tests that assert on `capturedTestPayload` find `null`
|
||||
|
||||
**Is the guard correct?** Yes — it matches the backend's security-by-design constraint. The tests need to be adapted to the new behavior, not the guard removed.
|
||||
|
||||
### Root Cause B: Pre-existing Infrastructure Failures (encryption-management, auth-middleware-cascade)
|
||||
|
||||
**encryption-management.spec.ts** (17 tests, ~7 unique failures) navigates to `/security/encryption` and tests key rotation, validation, and history display. **Zero overlap** with notification provider code paths. No files modified in the Telegram PR affect encryption.
|
||||
|
||||
**auth-middleware-cascade.spec.ts** (6 tests, all 6 fail) uses deprecated `waitUntil: 'networkidle'`, creates proxy hosts via UI forms (`getByLabel(/domain/i)`), and tests auth flows through Caddy. **Zero overlap** with notification code. These tests have known fragility from UI element selectors and `networkidle` waits.
|
||||
|
||||
**Verdict:** Both are pre-existing failures. They should be tracked separately and not block the Telegram PR.
|
||||
|
||||
### Root Cause C: Telegram E2E Spec Issues (4 failures)
|
||||
|
||||
The `telegram-notification-provider.spec.ts` has 8 tests, with ~2 unique failures. Most likely candidates:
|
||||
|
||||
1. **"should edit telegram notification provider and preserve token"** (L159): Uses fragile keyboard navigation (focus Send Test → Tab → Enter) to reach the Edit button. If the `title` attribute on the Send Test button doesn't match the accessible name pattern `/send test/i`, or if the tab order is affected by any intermediate focusable element, the Enter press activates the wrong button or nothing at all.
|
||||
|
||||
2. **"should test telegram notification provider"** (L265): Clicks the row-level "Send Test" button. The locator uses `getByRole('button', { name: /send test/i })`. The button has `title={t('notificationProviders.sendTest')}` which renders as "Send Test". This should work, but the `title` attribute contributing to accessible name can be browser-dependent, particularly in WebKit.
|
||||
|
||||
---
|
||||
|
||||
## 3. Affected Tests — Complete Inventory
|
||||
|
||||
### 3.1 E2E Tests: `notifications.spec.ts` (Test Button on New Form)
|
||||
|
||||
These tests open the "Add Provider" form (no `id`), click `provider-test-btn`, and expect API interactions. The disabled button now prevents all interaction.
|
||||
|
||||
| # | Test Name | Line | Type Used | Failure Mode |
|
||||
|---|---|---|---|---|
|
||||
| 1 | should test notification provider | L1085 | discord | `waitForRequest` times out — button disabled |
|
||||
| 2 | should show test success feedback | L1142 | discord | Success icon never appears — no click fires |
|
||||
| 3 | should preserve Discord request payload contract for save, preview, and test | L1236 | discord | `capturedTestPayload` is null — button disabled |
|
||||
| 4 | should show error when test fails | L1665 | discord | Error icon never appears — no click fires |
|
||||
|
||||
**Additional cascade effects:** The user reports ~16 unique failures from this file. The 4 above are directly caused by the `isNew` guard. Remaining failures may stem from cascading timeout effects, `beforeEach` state leakage after long timeouts, or other pre-existing flakiness amplified by the 60s timeout waterfall.
|
||||
|
||||
### 3.2 E2E Tests: `notifications-payload.spec.ts` (Test Button on New Form)
|
||||
|
||||
| # | Test Name | Line | Type Used | Failure Mode |
|
||||
|---|---|---|---|---|
|
||||
| 1 | provider-specific transformation strips gotify token from test and preview payloads | L264 | gotify | `provider-test-btn` disabled for new gotify form; `capturedTestPayload` is null |
|
||||
| 2 | retry split distinguishes retryable and non-retryable failures | L410 | webhook | `provider-test-btn` disabled for new webhook form; `waitForResponse` times out |
|
||||
|
||||
**Tests that should still pass:**
|
||||
- `valid payload flows for discord, gotify, and webhook` (L54) — uses `provider-save-btn`, not test button
|
||||
- `malformed payload scenarios` (L158) — API-level tests via `page.request.post`
|
||||
- `missing required fields block submit` (L192) — uses save button
|
||||
- `auth/header behavior checks` (L217) — API-level tests
|
||||
- `security: SSRF` (L314) — API-level tests
|
||||
- `security: DNS-rebinding` (L381) — API-level tests
|
||||
- `security: token does not leak` (L512) — API-level tests
|
||||
|
||||
### 3.3 E2E Tests: `telegram-notification-provider.spec.ts`
|
||||
|
||||
| # | Test Name | Line | Probable Failure Mode |
|
||||
|---|---|---|---|
|
||||
| 1 | should edit telegram notification provider and preserve token | L159 | Keyboard navigation (Tab from Send Test → Edit) fragility; may hit wrong element on some browsers |
|
||||
| 2 | should test telegram notification provider | L265 | Row-level Send Test button; possible accessible name mismatch in WebKit with `title` attribute |
|
||||
|
||||
**Tests that should pass:**
|
||||
- Form rendering tests (L25, L65) — UI assertions only
|
||||
- Create telegram provider (L89) — mocked POST
|
||||
- Delete telegram provider (L324) — mocked DELETE + confirm dialog
|
||||
- Security tests (L389, L436) — mock-based assertions
|
||||
|
||||
### 3.4 Frontend Unit Tests: `Notifications.test.tsx`
|
||||
|
||||
| # | Test Name | Line | Failure Mode |
|
||||
|---|---|---|---|
|
||||
| 1 | submits provider test action from form using normalized discord type | L447 | `userEvent.click()` on disabled button is no-op → `testProvider` never called → `waitFor` times out |
|
||||
| 2 | shows error toast when test mutation fails | L569 | Same — disabled button prevents click → `toast.error` with `saveBeforeTesting` fires instead of mutation error |
|
||||
|
||||
### 3.5 Pre-existing (Not Caused By Telegram PR)
|
||||
|
||||
| Spec | Tests | Rationale |
|
||||
|---|---|---|
|
||||
| CWE-614 cookie security | No standard gosec rule for Gin's `c.SetCookie` | ❌ |
|
||||
| CWE-640 email injection | No gosec rule exists for SMTP injection | ❌ |
|
||||
| CWE-89 SQL injection | G201, G202 — NOT in fast config | ❌ |
|
||||
| CWE-22 path traversal | G305 — in fast config | ✅ |
|
||||
|
||||
`semgrep` fills the gap for CWE-614 and CWE-640 where gosec has no rules.
|
||||
| `encryption-management.spec.ts` | ~7 unique | Tests encryption page at `/security/encryption`. No code overlap. |
|
||||
| `auth-middleware-cascade.spec.ts` | 6 unique | Tests proxy creation + auth middleware. Uses `networkidle`. No code overlap. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Technical Specifications
|
||||
## 4. Remediation Plan
|
||||
|
||||
### 3.1 Phase 1 — Harden Local Scanning
|
||||
### Priority Order
|
||||
|
||||
#### 3.1.1 Move `semgrep-scan` to `pre-push` stage
|
||||
|
||||
**File:** `/projects/Charon/.pre-commit-config.yaml`
|
||||
|
||||
Locate the `semgrep-scan` hook entry (currently has `stages: [manual]`). Change the stage and name:
|
||||
|
||||
```yaml
|
||||
- id: semgrep-scan
|
||||
name: Semgrep Security Scan (Blocking - pre-push)
|
||||
entry: scripts/pre-commit-hooks/semgrep-scan.sh
|
||||
language: script
|
||||
pass_filenames: false
|
||||
verbose: true
|
||||
stages: [pre-push]
|
||||
```
|
||||
|
||||
Rationale: `p/golang` includes:
|
||||
- `go.cookie.security.insecure-cookie.insecure-cookie` → CWE-614 equivalent
|
||||
- `go.lang.security.injection.tainted-smtp-email.tainted-smtp-email` → CWE-640 equivalent
|
||||
|
||||
#### 3.1.2 Restrict semgrep to WARNING+ and use targeted config
|
||||
|
||||
**File:** `/projects/Charon/scripts/pre-commit-hooks/semgrep-scan.sh`
|
||||
|
||||
The current invocation uses `--config auto --error`. Two changes:
|
||||
1. Change default config from `auto` → `p/golang`. `auto` fetches 1,000-3,000+ rules and takes 60-180s — too slow for a blocking pre-push hook. `p/golang` covers all Go-specific OWASP/CWE rules and completes in ~10-30s.
|
||||
2. Add `--severity ERROR --severity WARNING` to filter out INFO-level noise (these are OR logic, both required for WARNING+):
|
||||
|
||||
```bash
|
||||
semgrep scan \
|
||||
--config "${SEMGREP_CONFIG_VALUE:-p/golang}" \
|
||||
--severity ERROR \
|
||||
--severity WARNING \
|
||||
--error \
|
||||
--exclude "frontend/node_modules" \
|
||||
--exclude "frontend/coverage" \
|
||||
--exclude "frontend/dist" \
|
||||
backend frontend/src .github/workflows
|
||||
```
|
||||
|
||||
The `SEMGREP_CONFIG` env var can be overridden to `auto` or `p/golang p/owasp-top-ten` for a broader audit: `SEMGREP_CONFIG=auto git push`.
|
||||
|
||||
#### 3.1.3 Add `make security-local` target
|
||||
|
||||
**File:** `/projects/Charon/Makefile`
|
||||
|
||||
Add after the `security-scan-deps` target:
|
||||
|
||||
```make
|
||||
security-local: ## Run local security scan (govulncheck + semgrep)
|
||||
@echo "Running govulncheck..."
|
||||
@./scripts/security-scan.sh
|
||||
@echo "Running semgrep..."
|
||||
@SEMGREP_CONFIG=p/golang ./scripts/pre-commit-hooks/semgrep-scan.sh
|
||||
```
|
||||
|
||||
#### 3.1.4 Expand golangci-lint-fast gosec ruleset (Deferred)
|
||||
|
||||
**Status: DEFERRED** — G201/G202 (SQL injection via format string / string concat) are candidates for the fast config but must be pre-validated against the existing codebase first. GORM's raw query DSL can produce false positives. Run the following before adding:
|
||||
|
||||
```bash
|
||||
cd backend && golangci-lint run --enable=gosec --disable-all --config .golangci-fast.yml ./...
|
||||
```
|
||||
|
||||
…with G201/G202 temporarily uncommented. If zero false positives, add in a separate hardening commit. This is out of scope for this PR to avoid blocking PR #800.
|
||||
|
||||
Note: CWE-614 and CWE-640 remain CodeQL/Semgrep territory — gosec has no rules for these.
|
||||
|
||||
### 3.2 Phase 2 — Fix CWE-640 (`go/email-injection`)
|
||||
|
||||
#### Strategy
|
||||
|
||||
Add `// codeql[go/email-injection]` inline suppression annotations at all three sink sites in `mail_service.go`, with a structured justification comment immediately above each. This is the correct approach because:
|
||||
|
||||
1. The actual runtime defence is already correct and comprehensive (4-layer defence).
|
||||
2. The taint is a CodeQL false-positive caused by the tool not modelling validators as sanitisers.
|
||||
3. Restructuring to call `strings.ReplaceAll` on email addresses would corrupt valid addresses.
|
||||
|
||||
**The 4-layer defence that justifies these suppressions:**
|
||||
|
||||
```
|
||||
Layer 1: HTTP boundary — gin binding:"required,email" validates RFC 5321 format; CRLF fails well-formedness
|
||||
Layer 2: Service boundary — validateEmailRecipients() → ContainsAny("\r\n") error + net/mail.ParseAddress
|
||||
Layer 3: Mail layer parse — parseEmailAddressForHeader() → net/mail.ParseAddress returns only .Address field
|
||||
Layer 4: Pre-sink validation — rejectCRLF(toEnvelope) immediately before smtp.SendMail / client.Rcpt calls
|
||||
```
|
||||
|
||||
#### 3.2.1 Suppress at `smtp.SendMail` sink
|
||||
|
||||
**File:** `backend/internal/services/mail_service.go` (around line 367)
|
||||
|
||||
Locate the default-encryption branch in `SendEmail`. Replace the `smtp.SendMail` call line:
|
||||
|
||||
```go
|
||||
default:
|
||||
// toEnvelope passes through 4-layer CRLF defence:
|
||||
// 1. gin binding:"required,email" at HTTP entry (CRLF invalid per RFC 5321)
|
||||
// 2. validateEmailRecipients → ContainsAny("\r\n") + net/mail.ParseAddress
|
||||
// 3. parseEmailAddressForHeader → net/mail.ParseAddress (returns .Address only)
|
||||
// 4. rejectCRLF(toEnvelope) guard earlier in this function
|
||||
// CodeQL does not model validators as sanitisers; suppression is correct here.
|
||||
if err := smtp.SendMail(addr, auth, fromEnvelope, []string{toEnvelope}, msg); err != nil { // codeql[go/email-injection]
|
||||
```
|
||||
|
||||
#### 3.2.2 Suppress at `client.Rcpt` in `sendSSL`
|
||||
|
||||
**File:** `backend/internal/services/mail_service.go` (around line 530)
|
||||
|
||||
Locate in `sendSSL`. Replace the `client.Rcpt` call line:
|
||||
|
||||
```go
|
||||
// toEnvelope validated by rejectCRLF + net/mail.ParseAddress before this call (see SendEmail).
|
||||
if rcptErr := client.Rcpt(toEnvelope); rcptErr != nil { // codeql[go/email-injection]
|
||||
return fmt.Errorf("RCPT TO failed: %w", rcptErr)
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.3 Suppress at `client.Rcpt` in `sendSTARTTLS`
|
||||
|
||||
**File:** `backend/internal/services/mail_service.go` (around line 583)
|
||||
|
||||
Same pattern as sendSSL:
|
||||
|
||||
```go
|
||||
// toEnvelope validated by rejectCRLF + net/mail.ParseAddress before this call (see SendEmail).
|
||||
if rcptErr := client.Rcpt(toEnvelope); rcptErr != nil { // codeql[go/email-injection]
|
||||
return fmt.Errorf("RCPT TO failed: %w", rcptErr)
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.4 Document safe call in `settings_handler.go`
|
||||
|
||||
**File:** `backend/internal/api/handlers/settings_handler.go` (around line 637)
|
||||
|
||||
Add a comment immediately above the `SendEmail` call — the sinks in mail_service.go are already annotated, so this is documentation only:
|
||||
|
||||
```go
|
||||
// req.To is validated as RFC 5321 email via gin binding:"required,email".
|
||||
// SendEmail applies validateEmailRecipients + net/mail.ParseAddress + rejectCRLF as defence-in-depth.
|
||||
// Suppression annotations are on the sinks in mail_service.go.
|
||||
if err := h.MailService.SendEmail(c.Request.Context(), []string{req.To}, "Charon - Test Email", htmlBody); err != nil {
|
||||
```
|
||||
|
||||
#### 3.2.5 Document safe calls in `user_handler.go`
|
||||
|
||||
**File:** `backend/internal/api/handlers/user_handler.go` (lines ~597 and ~1015)
|
||||
|
||||
Add the same explanatory comment above both `SendInvite` call sites:
|
||||
|
||||
```go
|
||||
// userEmail validated as RFC 5321 email format; suppression on mail_service.go sinks covers this path.
|
||||
if err := h.MailService.SendInvite(userEmail, userToken, appName, baseURL); err != nil {
|
||||
```
|
||||
|
||||
### 3.3 Phase 3 — Fix CWE-614 (`go/cookie-secure-not-set`)
|
||||
|
||||
#### Strategy
|
||||
|
||||
Two complementary changes: (1) add a `query-filters` exclusion in `.github/codeql/codeql-config.yml` which is robust to line-number churn, and (2) verify the inline `// codeql[go/cookie-secure-not-set]` annotation is correctly positioned.
|
||||
|
||||
**Justification for exclusion:**
|
||||
|
||||
The `secure` parameter in `setSecureCookie()` is `true` for **all** external production requests. It is `false` only when `isLocalRequest()` returns `true` — i.e., when the request comes from `127.x.x.x`, `::1`, or `localhost` over HTTP. In that scenario, browsers reject `Secure` cookies over non-TLS connections anyway, so setting `Secure: true` would silently break auth for local development. The conditional is tested and documented.
|
||||
|
||||
#### 3.3.1 Skip `query-filters` approach — inline annotation is sufficient
|
||||
|
||||
**Status: NOT IMPLEMENTING** — `query-filters` is a CodeQL query suite (`.qls`) concept, NOT a valid top-level key in GitHub's `codeql-config.yml`. Adding it risks silent failure or breaking the entire CodeQL analysis. The inline annotation at `auth_handler.go:152` is the documented mechanism and is already correct. No changes to `.github/codeql/codeql-config.yml` are needed for CWE-614.
|
||||
|
||||
**Why inline annotation is sufficient and preferred:** It is scoped to the single intentional instance. Any future `c.SetCookie(...)` call without `Secure:true` anywhere else in the codebase will correctly flag. Global exclusion via config would silently hide future regressions.
|
||||
|
||||
#### 3.3.1 (REFERENCE ONLY) Current valid `codeql-config.yml` structure
|
||||
|
||||
```yaml
|
||||
name: "Charon CodeQL Config"
|
||||
|
||||
# Paths to ignore from all analysis (use sparingly - prefer query-filters for rule-level exclusions)
|
||||
paths-ignore:
|
||||
- "frontend/coverage/**"
|
||||
- "frontend/dist/**"
|
||||
- "playwright-report/**"
|
||||
- "test-results/**"
|
||||
- "coverage/**"
|
||||
```
|
||||
|
||||
DO NOT add `query-filters:` — it is not supported.
|
||||
- exclude:
|
||||
id: go/cookie-secure-not-set
|
||||
# Justified: setSecureCookie() in auth_handler.go intentionally sets Secure=false
|
||||
# ONLY for local loopback (127.x.x.x / ::1 / localhost) HTTP requests.
|
||||
# Browsers reject Secure cookies over HTTP regardless, so Secure=true would silently
|
||||
# break local development auth. All external HTTPS flows always set Secure=true.
|
||||
# Code: backend/internal/api/handlers/auth_handler.go → setSecureCookie()
|
||||
# Tests: TestSetSecureCookie_HTTPS_Strict, TestSetSecureCookie_HTTP_Loopback_Insecure
|
||||
```
|
||||
|
||||
#### 3.3.2 Verify inline suppression placement in `auth_handler.go`
|
||||
|
||||
**File:** `backend/internal/api/handlers/auth_handler.go` (around line 152)
|
||||
|
||||
Confirm the `// codeql[go/cookie-secure-not-set]` annotation is on the same line as `c.SetCookie(`. The code should read:
|
||||
|
||||
```go
|
||||
c.SetSameSite(sameSite)
|
||||
// secure is intentionally false for local non-HTTPS loopback (development only).
|
||||
c.SetCookie( // codeql[go/cookie-secure-not-set]
|
||||
name,
|
||||
value,
|
||||
maxAge,
|
||||
"/",
|
||||
domain,
|
||||
secure,
|
||||
true,
|
||||
)
|
||||
```
|
||||
|
||||
The `query-filters` in §3.3.1 provides the primary fix. The inline annotation provides belt-and-suspenders coverage that survives if the config is ever reset.
|
||||
1. **P0 — Fix unit tests** (fastest, unblocks local dev verification)
|
||||
2. **P1 — Fix E2E test-button tests** (the core regression from our change)
|
||||
3. **P2 — Fix telegram spec fragility** (new tests we added)
|
||||
4. **P3 — Document pre-existing failures** (not our change, track separately)
|
||||
|
||||
---
|
||||
|
||||
## 4. Implementation Plan
|
||||
### 4.1 P0: Frontend Unit Test Fixes
|
||||
|
||||
### Phase 1 — Local Scanning (implement first to gate subsequent work)
|
||||
**File:** `frontend/src/pages/__tests__/Notifications.test.tsx`
|
||||
|
||||
| Task | File | Change | Effort |
|
||||
|---|---|---|---|
|
||||
| P1-1 | `.pre-commit-config.yaml` | Change semgrep-scan stage from `[manual]` → `[pre-push]`, update name | XS |
|
||||
| P1-2 | `scripts/pre-commit-hooks/semgrep-scan.sh` | Add `--severity ERROR --severity WARNING` flags, exclude generated dirs | XS |
|
||||
| P1-3 | `Makefile` | Add `security-local` target | XS |
|
||||
| P1-4 | `backend/.golangci-fast.yml` | Add G201, G202 to gosec includes | XS |
|
||||
#### Fix 1: "submits provider test action from form using normalized discord type" (L447)
|
||||
|
||||
### Phase 2 — CWE-640 Fix
|
||||
**Problem:** Test opens "Add Provider" (new form, no `id`), clicks test button. Button is now disabled for new providers.
|
||||
|
||||
| Task | File | Change | Effort |
|
||||
|---|---|---|---|
|
||||
| P2-1 | `backend/internal/services/mail_service.go` | Add `// codeql[go/email-injection]` on smtp.SendMail line + 4-layer defence comment | XS |
|
||||
| P2-2 | `backend/internal/services/mail_service.go` | Add `// codeql[go/email-injection]` on sendSSL client.Rcpt line | XS |
|
||||
| P2-3 | `backend/internal/services/mail_service.go` | Add `// codeql[go/email-injection]` on sendSTARTTLS client.Rcpt line | XS |
|
||||
| P2-4 | `backend/internal/api/handlers/settings_handler.go` | Add explanatory comment above SendEmail call | XS |
|
||||
| P2-5 | `backend/internal/api/handlers/user_handler.go` | Add explanatory comment above both SendInvite calls (~line 597, ~line 1015) | XS |
|
||||
**Fix:** Change to test from an **existing provider's edit form** instead of a new form. This preserves the original intent (verifying the test payload uses normalized type).
|
||||
|
||||
### Phase 3 — CWE-614 Fix
|
||||
```typescript
|
||||
// BEFORE (L447-462):
|
||||
it('submits provider test action from form using normalized discord type', async () => {
|
||||
vi.mocked(notificationsApi.testProvider).mockResolvedValue()
|
||||
const user = userEvent.setup()
|
||||
renderWithQueryClient(<Notifications />)
|
||||
|
||||
| Task | File | Change | Effort |
|
||||
|---|---|---|---|
|
||||
| P3-1 | `backend/internal/api/handlers/auth_handler.go` | Verify `// codeql[go/cookie-secure-not-set]` is on `c.SetCookie(` line (no codeql-config.yml changes needed) | XS |
|
||||
await user.click(await screen.findByTestId('add-provider-btn'))
|
||||
await user.type(screen.getByTestId('provider-name'), 'Preview/Test Provider')
|
||||
await user.type(screen.getByTestId('provider-url'), 'https://example.com/webhook')
|
||||
await user.click(screen.getByTestId('provider-test-btn'))
|
||||
|
||||
**Total estimated file changes: 6 files, all comment/config additions — no logic changes.**
|
||||
await waitFor(() => {
|
||||
expect(notificationsApi.testProvider).toHaveBeenCalled()
|
||||
})
|
||||
const payload = vi.mocked(notificationsApi.testProvider).mock.calls[0][0]
|
||||
expect(payload.type).toBe('discord')
|
||||
})
|
||||
|
||||
// AFTER:
|
||||
it('submits provider test action from form using normalized discord type', async () => {
|
||||
vi.mocked(notificationsApi.testProvider).mockResolvedValue()
|
||||
setupMocks([baseProvider]) // baseProvider has an id
|
||||
const user = userEvent.setup()
|
||||
renderWithQueryClient(<Notifications />)
|
||||
|
||||
// Open edit form for existing provider (has id → test button enabled)
|
||||
const row = await screen.findByTestId(`provider-row-${baseProvider.id}`)
|
||||
const buttons = within(row).getAllByRole('button')
|
||||
await user.click(buttons[1]) // Edit button
|
||||
|
||||
await user.click(screen.getByTestId('provider-test-btn'))
|
||||
|
||||
await waitFor(() => {
|
||||
expect(notificationsApi.testProvider).toHaveBeenCalled()
|
||||
})
|
||||
const payload = vi.mocked(notificationsApi.testProvider).mock.calls[0][0]
|
||||
expect(payload.type).toBe('discord')
|
||||
})
|
||||
```
|
||||
|
||||
#### Fix 2: "shows error toast when test mutation fails" (L569)
|
||||
|
||||
**Problem:** Same — test opens new form, clicks test button, expects mutation error toast. Button is disabled.
|
||||
|
||||
**Fix:** Test from an existing provider's edit form.
|
||||
|
||||
```typescript
|
||||
// BEFORE (L569-582):
|
||||
it('shows error toast when test mutation fails', async () => {
|
||||
vi.mocked(notificationsApi.testProvider).mockRejectedValue(new Error('Connection refused'))
|
||||
const user = userEvent.setup()
|
||||
renderWithQueryClient(<Notifications />)
|
||||
|
||||
await user.click(await screen.findByTestId('add-provider-btn'))
|
||||
await user.type(screen.getByTestId('provider-name'), 'Failing Provider')
|
||||
await user.type(screen.getByTestId('provider-url'), 'https://example.com/webhook')
|
||||
await user.click(screen.getByTestId('provider-test-btn'))
|
||||
|
||||
await waitFor(() => {
|
||||
expect(toast.error).toHaveBeenCalledWith('Connection refused')
|
||||
})
|
||||
})
|
||||
|
||||
// AFTER:
|
||||
it('shows error toast when test mutation fails', async () => {
|
||||
vi.mocked(notificationsApi.testProvider).mockRejectedValue(new Error('Connection refused'))
|
||||
setupMocks([baseProvider])
|
||||
const user = userEvent.setup()
|
||||
renderWithQueryClient(<Notifications />)
|
||||
|
||||
// Open edit form for existing provider
|
||||
const row = await screen.findByTestId(`provider-row-${baseProvider.id}`)
|
||||
const buttons = within(row).getAllByRole('button')
|
||||
await user.click(buttons[1]) // Edit button
|
||||
|
||||
await user.click(screen.getByTestId('provider-test-btn'))
|
||||
|
||||
await waitFor(() => {
|
||||
expect(toast.error).toHaveBeenCalledWith('Connection refused')
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
#### Bonus: Add a NEW unit test for the `saveBeforeTesting` guard
|
||||
|
||||
```typescript
|
||||
it('disables test button when provider is new (unsaved) and not email type', async () => {
|
||||
const user = userEvent.setup()
|
||||
renderWithQueryClient(<Notifications />)
|
||||
|
||||
await user.click(await screen.findByTestId('add-provider-btn'))
|
||||
const testBtn = screen.getByTestId('provider-test-btn')
|
||||
expect(testBtn).toBeDisabled()
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Acceptance Criteria
|
||||
### 4.2 P1: E2E Test Fixes — notifications.spec.ts
|
||||
|
||||
### CI (CodeQL must pass with zero error-level findings)
|
||||
**File:** `tests/settings/notifications.spec.ts`
|
||||
|
||||
- [ ] `codeql.yml` CodeQL analysis (Go) passes with **0 blocking findings**
|
||||
- [ ] `go/email-injection` is absent from the Go SARIF output
|
||||
- [ ] `go/cookie-secure-not-set` is absent from the Go SARIF output
|
||||
**Strategy:** For tests that click the test button from a new form, restructure the flow to:
|
||||
1. First **save** the provider (mocked create → returns id)
|
||||
2. Then **test** from the saved provider row's Send Test button (row buttons are not gated by `isNew`)
|
||||
|
||||
### Local scanning
|
||||
#### Fix 3: "should test notification provider" (L1085)
|
||||
|
||||
- [ ] A `git push` with any `.go` file touched **blocks** if semgrep finds WARNING+ severity issues
|
||||
- [ ] `pre-commit run semgrep-scan` on the current codebase exits 0 (no new findings)
|
||||
- [ ] `make security-local` runs and exits 0
|
||||
**Current flow:** Add form → fill → mock test endpoint → click `provider-test-btn` → verify request
|
||||
**Problem:** Test button disabled for new form
|
||||
**Fix:** Save first, then click test from the provider row's Send Test button.
|
||||
|
||||
### Regression safety
|
||||
```typescript
|
||||
// In the test, after filling the form and before clicking test:
|
||||
|
||||
- [ ] `go test ./...` in `backend/` passes (all changes are comments/config — no test updates required)
|
||||
- [ ] `golangci-lint run --config .golangci-fast.yml ./...` passes in `backend/`
|
||||
- [ ] The existing runtime defence (rejectCRLF, validateEmailRecipients) is **unchanged** — confirmed by diff
|
||||
// 1. Mock the create endpoint to return a provider with an id
|
||||
await page.route('**/api/v1/notifications/providers', async (route, request) => {
|
||||
if (request.method() === 'POST') {
|
||||
const payload = await request.postDataJSON();
|
||||
await route.fulfill({
|
||||
status: 201,
|
||||
contentType: 'application/json',
|
||||
body: JSON.stringify({ id: 'saved-test-id', ...payload }),
|
||||
});
|
||||
} else if (request.method() === 'GET') {
|
||||
await route.fulfill({
|
||||
status: 200,
|
||||
contentType: 'application/json',
|
||||
body: JSON.stringify([{
|
||||
id: 'saved-test-id',
|
||||
name: 'Test Provider',
|
||||
type: 'discord',
|
||||
url: 'https://discord.com/api/webhooks/test/token',
|
||||
enabled: true
|
||||
}]),
|
||||
});
|
||||
} else {
|
||||
await route.continue();
|
||||
}
|
||||
});
|
||||
|
||||
// 2. Save the provider first
|
||||
await page.getByTestId('provider-save-btn').click();
|
||||
|
||||
// 3. Wait for the provider to appear in the list
|
||||
await expect(page.getByText('Test Provider')).toBeVisible({ timeout: 5000 });
|
||||
|
||||
// 4. Click row-level Send Test button
|
||||
const providerRow = page.getByTestId('provider-row-saved-test-id');
|
||||
const sendTestButton = providerRow.getByRole('button', { name: /send test/i });
|
||||
await sendTestButton.click();
|
||||
```
|
||||
|
||||
#### Fix 4: "should show test success feedback" (L1142)
|
||||
|
||||
Same pattern as Fix 3: save provider first, then test from row.
|
||||
|
||||
#### Fix 5: "should preserve Discord request payload contract for save, preview, and test" (L1236)
|
||||
|
||||
**Current flow:** Add form → fill → click preview → click test → save → verify all payloads
|
||||
**Problem:** Test button disabled for new form
|
||||
**Fix:** Reorder to: Add form → fill → click preview → **save** → **test from row** → verify payloads
|
||||
|
||||
The preview button is NOT disabled for new forms (only the test button is), so preview still works from the new form. The test step must happen after save.
|
||||
|
||||
#### Fix 6: "should show error when test fails" (L1665)
|
||||
|
||||
Same pattern: save first, then test from row.
|
||||
|
||||
---
|
||||
|
||||
### 4.3 P1: E2E Test Fixes — notifications-payload.spec.ts
|
||||
|
||||
**File:** `tests/settings/notifications-payload.spec.ts`
|
||||
|
||||
#### Fix 7: "provider-specific transformation strips gotify token from test and preview payloads" (L264)
|
||||
|
||||
**Current flow:** Add gotify form → fill with token → click preview → click test → verify token not in payloads
|
||||
**Problem:** Test button disabled for new gotify form
|
||||
**Fix:** Preview still works from new form. For test, save first, then test from the saved provider row.
|
||||
|
||||
**Note:** The row-level test call uses `{ ...provider, type: normalizeProviderType(provider.type) }` where `provider` is the list item (which never contains `token/gotify_token` per the List handler that strips tokens). So the token-stripping assertion naturally holds for row-level tests.
|
||||
|
||||
#### Fix 8: "retry split distinguishes retryable and non-retryable failures" (L410)
|
||||
|
||||
**Current flow:** Add webhook form → fill → click test → verify retry semantics
|
||||
**Problem:** Test button disabled for new webhook form
|
||||
**Fix:** Save first (mock create), then open edit form (which has `id`) or test from the row.
|
||||
|
||||
---
|
||||
|
||||
### 4.4 P2: Telegram E2E Spec Hardening
|
||||
|
||||
**File:** `tests/settings/telegram-notification-provider.spec.ts`
|
||||
|
||||
#### Fix 9: "should edit telegram notification provider and preserve token" (L159)
|
||||
|
||||
**Problem:** Uses fragile keyboard navigation to reach the Edit button:
|
||||
```typescript
|
||||
await sendTestButton.focus();
|
||||
await page.keyboard.press('Tab');
|
||||
await page.keyboard.press('Enter');
|
||||
```
|
||||
|
||||
This assumes Tab from Send Test lands on Edit. Tab order can vary across browsers.
|
||||
|
||||
**Fix:** Use a direct locator for the Edit button instead of keyboard navigation:
|
||||
|
||||
```typescript
|
||||
// BEFORE:
|
||||
await sendTestButton.focus();
|
||||
await page.keyboard.press('Tab');
|
||||
await page.keyboard.press('Enter');
|
||||
|
||||
// AFTER:
|
||||
const editButton = providerRow.getByRole('button').nth(1); // Send Test=0, Edit=1
|
||||
await editButton.click();
|
||||
```
|
||||
|
||||
Or use a structural locator based on the edit icon class.
|
||||
|
||||
#### Fix 10: "should test telegram notification provider" (L265)
|
||||
|
||||
**Probable issue:** The `getByRole('button', { name: /send test/i })` relies on `title` for accessible name. WebKit may not compute accessible name from `title` the same way.
|
||||
|
||||
**Fix (source — preferred):** Add explicit `aria-label` to the row Send Test button in `Notifications.tsx` (L703):
|
||||
```tsx
|
||||
<Button
|
||||
variant="secondary"
|
||||
size="sm"
|
||||
onClick={() => testMutation.mutate({...})}
|
||||
title={t('notificationProviders.sendTest')}
|
||||
aria-label={t('notificationProviders.sendTest')}
|
||||
>
|
||||
```
|
||||
|
||||
**Fix (test — alternative):** Use structural locator:
|
||||
```typescript
|
||||
const sendTestButton = providerRow.locator('button').first();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.5 P3: Document Pre-existing Failures
|
||||
|
||||
**Action:** File separate issues (not part of this PR) for:
|
||||
|
||||
1. **encryption-management.spec.ts** — ~7 unique test failures in `/security/encryption`. Likely UI rendering timing issues or flaky selectors. No code overlap with Telegram PR.
|
||||
|
||||
2. **auth-middleware-cascade.spec.ts** — All 6 tests fail × 3 browsers. Uses deprecated `waitUntil: 'networkidle'`, creates proxy hosts through fragile UI selectors (`getByLabel(/domain/i)`), and tests auth middleware cascade. Needs modernization pass for locators and waits.
|
||||
|
||||
---
|
||||
|
||||
## 5. Implementation Plan
|
||||
|
||||
### Phase 1: Unit Test Fixes (Immediate)
|
||||
|
||||
| Task | File | Lines | Complexity |
|
||||
|---|---|---|---|
|
||||
| Fix "submits provider test action" test | `Notifications.test.tsx` | L447-462 | Low |
|
||||
| Fix "shows error toast" test | `Notifications.test.tsx` | L569-582 | Low |
|
||||
| Add `saveBeforeTesting` guard unit test | `Notifications.test.tsx` | New | Low |
|
||||
|
||||
**Validation:** `cd frontend && npx vitest run src/pages/__tests__/Notifications.test.tsx`
|
||||
|
||||
### Phase 2: E2E Test Fixes — Core Regression
|
||||
|
||||
| Task | File | Lines | Complexity |
|
||||
|---|---|---|---|
|
||||
| Fix "should test notification provider" | `notifications.spec.ts` | L1085-1138 | Medium |
|
||||
| Fix "should show test success feedback" | `notifications.spec.ts` | L1142-1178 | Medium |
|
||||
| Fix "should preserve Discord payload contract" | `notifications.spec.ts` | L1236-1340 | Medium |
|
||||
| Fix "should show error when test fails" | `notifications.spec.ts` | L1665-1706 | Medium |
|
||||
| Fix "transformation strips gotify token" | `notifications-payload.spec.ts` | L264-312 | Medium |
|
||||
| Fix "retry split retryable/non-retryable" | `notifications-payload.spec.ts` | L410-510 | High |
|
||||
|
||||
**Validation per test:** `npx playwright test --project=firefox <spec-file> -g "<test-name>"`
|
||||
|
||||
### Phase 3: Telegram Spec Hardening
|
||||
|
||||
| Task | File | Lines | Complexity |
|
||||
|---|---|---|---|
|
||||
| Replace keyboard nav with direct locator | `telegram-notification-provider.spec.ts` | L220-223 | Low |
|
||||
| Add `aria-label` to row Send Test button | `Notifications.tsx` | L703-708 | Low |
|
||||
| Verify all 8 telegram tests pass 3 browsers | All | — | Low |
|
||||
|
||||
**Validation:** `npx playwright test tests/settings/telegram-notification-provider.spec.ts`
|
||||
|
||||
### Phase 4: Accessibility Hardening (Optional — Low Priority)
|
||||
|
||||
Consider adding `aria-label` attributes to all icon-only buttons in the provider row for improved accessibility and test resilience:
|
||||
|
||||
| Button | Current Accessible Name Source | Recommended |
|
||||
|---|---|---|
|
||||
| Send Test | `title` attribute | Add `aria-label` |
|
||||
| Edit | None (icon only) | Add `aria-label={t('common.edit')}` |
|
||||
| Delete | None (icon only) | Add `aria-label={t('common.delete')}` |
|
||||
|
||||
---
|
||||
|
||||
## 6. Commit Slicing Strategy
|
||||
|
||||
### Decision: Single commit on `feature/beta-release`
|
||||
**Decision:** Single PR with 2 focused commits
|
||||
|
||||
**Rationale:** All three phases are tightly related (one CI failure, two root findings, one local gap). All changes are additive (comments, config, no logic mutations). Splitting into multiple PRs would create an intermediate state where CI still fails and the local gap remains open. A single well-scoped commit keeps PR #800 atomic and reviewable.
|
||||
**Rationale:** All fixes are tightly coupled to the Telegram feature PR and represent test adaptations to a correct behavioral change. No cross-domain changes. Small total diff.
|
||||
|
||||
**Suggested commit message:**
|
||||
```
|
||||
fix(security): suppress CodeQL false-positives for email-injection and cookie-secure
|
||||
### Commit 1: "fix(test): adapt notification tests to save-before-test guard"
|
||||
- **Scope:** All unit test and E2E test fixes (Phases 1-3)
|
||||
- **Files:** `Notifications.test.tsx`, `notifications.spec.ts`, `notifications-payload.spec.ts`, `telegram-notification-provider.spec.ts`
|
||||
- **Dependencies:** None
|
||||
- **Validation Gate:** All notification-related tests pass locally on at least one browser
|
||||
|
||||
CWE-640 (go/email-injection): Add // codeql[go/email-injection] annotations at all 3
|
||||
smtp sink sites in mail_service.go (smtp.SendMail, sendSSL client.Rcpt, sendSTARTTLS
|
||||
client.Rcpt). The 4-layer defence (gin binding:"required,email", validateEmailRecipients,
|
||||
net/mail.ParseAddress, rejectCRLF) is comprehensive; CodeQL's taint model does not
|
||||
model validators as sanitisers, producing false-positive paths from
|
||||
settings_handler.go:637 and user_handler.go invite flows that bypass
|
||||
notification_service.go.
|
||||
### Commit 2: "feat(a11y): add aria-labels to notification provider row buttons"
|
||||
- **Scope:** Source code accessibility improvement (Phase 4)
|
||||
- **Files:** `Notifications.tsx`
|
||||
- **Dependencies:** Depends on Commit 1 (tests must pass first)
|
||||
- **Validation Gate:** Telegram spec tests pass consistently on WebKit
|
||||
|
||||
CWE-614 (go/cookie-secure-not-set): Add query-filter to codeql-config.yml excluding
|
||||
this rule with documented justification. setSecureCookie() correctly sets Secure=false
|
||||
only for local loopback HTTP requests where the Secure attribute is browser-rejected.
|
||||
All external HTTPS flows set Secure=true.
|
||||
|
||||
Local scanning: Promote semgrep-scan from manual to pre-push stage so WARNING+
|
||||
severity findings block push. Addresses gap where CWE-614 and CWE-640 equivalents
|
||||
are not covered by any blocking local scan tool.
|
||||
```
|
||||
|
||||
**PR:** All changes target PR #800 directly.
|
||||
### Rollback
|
||||
- These are test-only changes (except the optional aria-label). Reverting either commit has zero production impact.
|
||||
- If tests still fail after fixes, the next step is to run with `--debug` and capture trace artifacts.
|
||||
|
||||
---
|
||||
|
||||
## 7. Risk and Rollback
|
||||
## 7. Acceptance Criteria
|
||||
|
||||
| Risk | Likelihood | Mitigation |
|
||||
|---|---|---|
|
||||
| Inline suppression ends up on wrong line after future rebase | Medium | `query-filters` in codeql-config.yml provides independent suppression independent of line numbers |
|
||||
| `semgrep-scan` at `pre-push` produces false-positive blocking | Low | `--severity WARNING --error` limits to genuine findings; use `SEMGREP_CONFIG=p/golang` for targeted override |
|
||||
| G201/G202 gosec rules trigger on existing legitimate code | Low | Run `golangci-lint run --config .golangci-fast.yml` locally before committing; suppress specific instances if needed |
|
||||
| CodeQL `query-filters` YAML syntax changes in future GitHub CodeQL versions | Low | Inline `// codeql[...]` annotations serve as independent fallback |
|
||||
|
||||
**Rollback:** All changes are additive config and comments. Reverting the commit restores the prior state exactly. No schema, API, or behaviour changes are made.
|
||||
- [ ] `Notifications.test.tsx` — all 2 previously failing tests pass
|
||||
- [ ] `notifications.spec.ts` — all 4 isNew-guard-affected tests pass on 3 browsers
|
||||
- [ ] `notifications-payload.spec.ts` — "transformation" and "retry split" tests pass on 3 browsers
|
||||
- [ ] `telegram-notification-provider.spec.ts` — all 8 tests pass on 3 browsers
|
||||
- [ ] No regressions in other notification tests
|
||||
- [ ] New unit test validates the `saveBeforeTesting` guard / disabled button behavior
|
||||
- [ ] `encryption-management.spec.ts` and `auth-middleware-cascade.spec.ts` failures documented as separate issues (not blocked by this PR)
|
||||
|
||||
686
docs/plans/telegram_implementation_spec.md
Normal file
686
docs/plans/telegram_implementation_spec.md
Normal file
@@ -0,0 +1,686 @@
|
||||
# Telegram Notification Provider — Implementation Plan
|
||||
|
||||
**Date:** 2026-07-10
|
||||
**Author:** Planning Agent
|
||||
**Confidence Score:** 92% (High — existing patterns well-established, Telegram Bot API straightforward)
|
||||
|
||||
---
|
||||
|
||||
## 1. Introduction
|
||||
|
||||
### Objective
|
||||
|
||||
Add Telegram as a first-class notification provider in Charon, following the established architecture used by Discord, Gotify, Email, and generic Webhook providers.
|
||||
|
||||
### Goals
|
||||
|
||||
- Users can configure a Telegram bot token and chat ID to receive notifications via Telegram
|
||||
- All existing notification event types (proxy hosts, certs, uptime, security events) work with Telegram
|
||||
- JSON template engine (minimal/detailed/custom) works with Telegram
|
||||
- Feature flag allows enabling/disabling Telegram dispatch independently
|
||||
- Token is treated as a secret (write-only, never exposed in API responses)
|
||||
- Full test coverage: Go unit tests, Vitest frontend tests, Playwright E2E tests
|
||||
|
||||
### Telegram Bot API Overview
|
||||
|
||||
Telegram bots send messages via:
|
||||
|
||||
```
|
||||
POST https://api.telegram.org/bot<BOT_TOKEN>/sendMessage
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"chat_id": "<CHAT_ID>",
|
||||
"text": "Hello world",
|
||||
"parse_mode": "HTML" // optional: "HTML" or "MarkdownV2"
|
||||
}
|
||||
```
|
||||
|
||||
**Key design decisions:**
|
||||
- **Token storage:** The bot token is stored in `NotificationProvider.Token` (`json:"-"`, encrypted at rest) — never in the URL field. This mirrors the Gotify pattern where secrets are separated from endpoints.
|
||||
- **URL field:** Stores only the `chat_id` (e.g., `987654321`). At dispatch time, the full API URL is constructed dynamically: `https://api.telegram.org/bot` + decryptedToken + `/sendMessage`. The `chat_id` is passed in the POST body alongside the message text. This prevents token leakage via API responses since URL is `json:"url"`.
|
||||
- **SSRF mitigation:** Before dispatching, validate that the constructed URL hostname is exactly `api.telegram.org`. This prevents SSRF if stored data is tampered with.
|
||||
- **Dispatch path:** Uses `sendJSONPayload` → `httpWrapper.Send()` (same as Gotify), since both are token-based JSON POST providers
|
||||
- **No schema migration needed:** The existing `NotificationProvider` model accommodates Telegram without changes
|
||||
|
||||
> **Supervisor Review Note:** The original design embedded the bot token in the URL field (`https://api.telegram.org/bot<TOKEN>/sendMessage?chat_id=<CHAT_ID>`). This was rejected because the URL field is `json:"url"` — exposed in every API response. The token MUST only reside in the `Token` field (`json:"-"`).
|
||||
|
||||
---
|
||||
|
||||
## 2. Research Findings
|
||||
|
||||
### Existing Architecture
|
||||
|
||||
The notification system follows a provider-based architecture:
|
||||
|
||||
| Layer | File | Role |
|
||||
|-------|------|------|
|
||||
| Feature flags | `backend/internal/notifications/feature_flags.go` | Flag constants (`FlagXxxServiceEnabled`) |
|
||||
| Feature flag handler | `backend/internal/api/handlers/feature_flags_handler.go` | DB-backed flags with defaults |
|
||||
| Router | `backend/internal/notifications/router.go` | `ShouldUseNotify()` per-type dispatch |
|
||||
| Service | `backend/internal/services/notification_service.go` | Core dispatch: `isSupportedNotificationProviderType()`, `isDispatchEnabled()`, `supportsJSONTemplates()`, `sendJSONPayload()`, `TestProvider()` |
|
||||
| Handlers | `backend/internal/api/handlers/notification_provider_handler.go` | CRUD + type validation + token preservation |
|
||||
| Model | `backend/internal/models/notification_provider.go` | GORM model with Token (json:"-"), HasToken |
|
||||
| Frontend API | `frontend/src/api/notifications.ts` | `SUPPORTED_NOTIFICATION_PROVIDER_TYPES`, sanitization |
|
||||
| Frontend UI | `frontend/src/pages/Notifications.tsx` | Provider form with conditional fields per type |
|
||||
| i18n | `frontend/src/locales/en/translation.json` | Label strings |
|
||||
| E2E fixtures | `tests/fixtures/notifications.ts` | `telegramProvider` **already defined** |
|
||||
|
||||
### Existing Provider Addition Points (Switch Statements / Type Checks)
|
||||
|
||||
Every location that checks provider types is listed below — all require a `"telegram"` case:
|
||||
|
||||
| # | File | Function/Line | Current Logic |
|
||||
|---|------|---------------|---------------|
|
||||
| 1 | `feature_flags.go` | Constants | Missing `FlagTelegramServiceEnabled` |
|
||||
| 2 | `feature_flags_handler.go` | `defaultFlags` + `defaultFlagValues` | Missing telegram entry |
|
||||
| 3 | `router.go` | `ShouldUseNotify()` switch | Missing `case "telegram"` |
|
||||
| 4 | `notification_service.go` | `isSupportedNotificationProviderType()` | `case "discord", "email", "gotify", "webhook"` |
|
||||
| 5 | `notification_service.go` | `isDispatchEnabled()` | switch with per-type flag checks |
|
||||
| 6 | `notification_service.go` | `supportsJSONTemplates()` | `case "webhook", "discord", "gotify", "slack", "generic"` |
|
||||
| 7 | `notification_service.go` | `sendJSONPayload()` — service-specific validation | Missing `case "telegram"` for payload validation |
|
||||
| 8 | `notification_service.go` | `sendJSONPayload()` — dispatch branch | Gotify/webhook use `httpWrapper.Send()`; others use `ValidateExternalURL` + `SafeHTTPClient` |
|
||||
| 9 | `notification_provider_handler.go` | `Create()` type guard | `providerType != "discord" && providerType != "gotify" && providerType != "webhook" && providerType != "email"` |
|
||||
| 10 | `notification_provider_handler.go` | `Update()` type guard | Same pattern as Create |
|
||||
| 11 | `notification_provider_handler.go` | `Update()` token preservation | `if providerType == "gotify" && strings.TrimSpace(req.Token) == ""` |
|
||||
| 12 | `notifications.ts` | `SUPPORTED_NOTIFICATION_PROVIDER_TYPES` | `['discord', 'gotify', 'webhook', 'email']` |
|
||||
| 13 | `notifications.ts` | `sanitizeProviderForWriteAction()` | Token handling only for `type !== 'gotify'` |
|
||||
| 14 | `Notifications.tsx` | Type `<select>` options | discord/gotify/webhook/email |
|
||||
| 15 | `Notifications.tsx` | `normalizeProviderPayloadForSubmit()` | Token mapping only for `type === 'gotify'` |
|
||||
| 16 | `Notifications.tsx` | Conditional form fields | `isGotify` shows token input |
|
||||
|
||||
### Test Files Requiring Updates
|
||||
|
||||
| File | Current Behavior | Required Change |
|
||||
|------|-----------------|-----------------|
|
||||
| `notification_service_test.go` (~L1819) | `TestTestProvider_NotifyOnlyRejectsUnsupportedProvider` tests `"telegram"` as **unsupported** | Change: telegram is now supported |
|
||||
| `notification_service_json_test.go` | Discord/Slack/Gotify/Webhook JSON tests | Add telegram payload validation tests |
|
||||
| `notification_provider_handler_test.go` | CRUD tests with supported types | Add telegram to supported type lists |
|
||||
| `enhanced_security_notification_service_test.go` (~L139) | `Type: "telegram"` marked `// Should be filtered` | Change: telegram is now valid |
|
||||
| `frontend/src/api/notifications.test.ts` | Rejects `"telegram"` as unsupported | Accept telegram, add CRUD tests |
|
||||
| `frontend/src/api/__tests__/notifications.test.ts` | Same rejection | Same fix |
|
||||
| `tests/settings/notifications.spec.ts` | CRUD E2E for discord/gotify/webhook/email | Add telegram scenarios |
|
||||
|
||||
### E2E Fixture Already Defined
|
||||
|
||||
```typescript
|
||||
// tests/fixtures/notifications.ts
|
||||
// NOTE: Fixture must be updated — URL should contain only the chat_id, token goes in the token field
|
||||
export const telegramProvider: NotificationProviderConfig = {
|
||||
name: generateProviderName('telegram'),
|
||||
type: 'telegram',
|
||||
url: '987654321', // chat_id only — bot token is stored in the Token field
|
||||
token: 'bot123456789:ABCdefGHIjklMNOpqrSTUvwxYZ', // stored encrypted, never in API responses
|
||||
enabled: true,
|
||||
notify_proxy_hosts: true,
|
||||
notify_certs: true,
|
||||
notify_uptime: true,
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Technical Specifications
|
||||
|
||||
### 3.1 Backend — Feature Flags
|
||||
|
||||
**File:** `backend/internal/notifications/feature_flags.go`
|
||||
|
||||
Add constant:
|
||||
|
||||
```go
|
||||
FlagTelegramServiceEnabled = "feature.notifications.service.telegram.enabled"
|
||||
```
|
||||
|
||||
**File:** `backend/internal/api/handlers/feature_flags_handler.go`
|
||||
|
||||
Add to `defaultFlags` slice:
|
||||
|
||||
```go
|
||||
notifications.FlagTelegramServiceEnabled,
|
||||
```
|
||||
|
||||
Add to `defaultFlagValues` map:
|
||||
|
||||
```go
|
||||
notifications.FlagTelegramServiceEnabled: true,
|
||||
```
|
||||
|
||||
> **Note:** Telegram is **enabled by default** once the provider is toggled on in the UI, matching Gotify/Webhook behavior. The feature flag exists as an admin-level kill switch, not a setup gate.
|
||||
|
||||
### 3.2 Backend — Router
|
||||
|
||||
**File:** `backend/internal/notifications/router.go`
|
||||
|
||||
Add to `ShouldUseNotify()` switch:
|
||||
|
||||
```go
|
||||
case "telegram":
|
||||
return flags[FlagTelegramServiceEnabled]
|
||||
```
|
||||
|
||||
### 3.3 Backend — Notification Service
|
||||
|
||||
**File:** `backend/internal/services/notification_service.go`
|
||||
|
||||
#### `isSupportedNotificationProviderType()`
|
||||
|
||||
```go
|
||||
case "discord", "email", "gotify", "webhook", "telegram":
|
||||
return true
|
||||
```
|
||||
|
||||
#### `isDispatchEnabled()`
|
||||
|
||||
```go
|
||||
case "telegram":
|
||||
return s.getFeatureFlagValue(notifications.FlagTelegramServiceEnabled, true)
|
||||
```
|
||||
|
||||
Both `defaultFlagValues` (initial DB seed) and the `isDispatchEnabled()` fallback are `true` — Telegram is enabled by default once the provider is created in the UI. This matches Gotify/Webhook behavior (enabled-by-default, admin kill-switch via feature flag).
|
||||
|
||||
#### `supportsJSONTemplates()`
|
||||
|
||||
```go
|
||||
case "webhook", "discord", "gotify", "slack", "generic", "telegram":
|
||||
return true
|
||||
```
|
||||
|
||||
#### `sendJSONPayload()` — Service-Specific Validation
|
||||
|
||||
Add after the `case "gotify":` block:
|
||||
|
||||
```go
|
||||
case "telegram":
|
||||
// Telegram requires 'text' field for the message body
|
||||
if _, hasText := jsonPayload["text"]; !hasText {
|
||||
// Auto-map 'message' to 'text' if present (template compatibility)
|
||||
if messageValue, hasMessage := jsonPayload["message"]; hasMessage {
|
||||
jsonPayload["text"] = messageValue
|
||||
normalizedBody, marshalErr := json.Marshal(jsonPayload)
|
||||
if marshalErr != nil {
|
||||
return fmt.Errorf("failed to normalize telegram payload: %w", marshalErr)
|
||||
}
|
||||
body.Reset()
|
||||
if _, writeErr := body.Write(normalizedBody); writeErr != nil {
|
||||
return fmt.Errorf("failed to write normalized telegram payload: %w", writeErr)
|
||||
}
|
||||
} else {
|
||||
return fmt.Errorf("telegram payload requires 'text' field")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This auto-mapping mirrors the Discord pattern (`message` → `content`) so that the built-in `minimal` and `detailed` templates (which use `"message"` as a field) work out of the box with Telegram.
|
||||
|
||||
#### `sendJSONPayload()` — Dispatch Branch
|
||||
|
||||
Add `"telegram"` to the `httpWrapper.Send()` dispatch branch alongside gotify/webhook:
|
||||
|
||||
```go
|
||||
if providerType == "gotify" || providerType == "webhook" || providerType == "telegram" {
|
||||
```
|
||||
|
||||
For telegram, the dispatch URL must be **constructed at send time** from the stored token and chat_id:
|
||||
|
||||
```go
|
||||
case "telegram":
|
||||
// Construct the API URL dynamically — token is NEVER stored in the URL field
|
||||
decryptedToken := provider.Token // already decrypted by service layer
|
||||
dispatchURL = "https://api.telegram.org/bot" + decryptedToken + "/sendMessage"
|
||||
|
||||
// SSRF mitigation: validate hostname before dispatch
|
||||
parsedURL, err := url.Parse(dispatchURL)
|
||||
if err != nil || parsedURL.Hostname() != "api.telegram.org" {
|
||||
return fmt.Errorf("telegram dispatch URL validation failed: invalid hostname")
|
||||
}
|
||||
|
||||
// Inject chat_id into the JSON payload body (URL field stores the chat_id)
|
||||
jsonPayload["chat_id"] = provider.URL
|
||||
// Re-marshal the payload with chat_id included
|
||||
updatedBody, marshalErr := json.Marshal(jsonPayload)
|
||||
if marshalErr != nil {
|
||||
return fmt.Errorf("failed to marshal telegram payload with chat_id: %w", marshalErr)
|
||||
}
|
||||
body.Reset()
|
||||
body.Write(updatedBody)
|
||||
```
|
||||
|
||||
The `X-Gotify-Key` header is only set when `providerType == "gotify"` — no header changes needed for telegram.
|
||||
|
||||
#### `TestProvider()` — Telegram-Specific Error Message
|
||||
|
||||
When testing a Telegram provider and the API returns HTTP 401 or 403, return a specific error message:
|
||||
|
||||
```go
|
||||
case "telegram":
|
||||
if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
|
||||
return fmt.Errorf("provider rejected authentication. Verify your Telegram Bot Token")
|
||||
}
|
||||
```
|
||||
|
||||
This gives users actionable guidance instead of a generic HTTP status error.
|
||||
|
||||
### 3.4 Backend — Handler Layer
|
||||
|
||||
**File:** `backend/internal/api/handlers/notification_provider_handler.go`
|
||||
|
||||
#### `Create()` Type Guard
|
||||
|
||||
```go
|
||||
if providerType != "discord" && providerType != "gotify" && providerType != "webhook" && providerType != "email" && providerType != "telegram" {
|
||||
```
|
||||
|
||||
#### `Update()` Type Guard
|
||||
|
||||
Same change as Create:
|
||||
|
||||
```go
|
||||
if providerType != "discord" && providerType != "gotify" && providerType != "webhook" && providerType != "email" && providerType != "telegram" {
|
||||
```
|
||||
|
||||
#### `Update()` Token Preservation
|
||||
|
||||
Telegram bot tokens should be preserved on update when the user omits them (same UX as Gotify):
|
||||
|
||||
```go
|
||||
if (providerType == "gotify" || providerType == "telegram") && strings.TrimSpace(req.Token) == "" {
|
||||
req.Token = existing.Token
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 Backend — Model (No Changes)
|
||||
|
||||
The `NotificationProvider` model already has:
|
||||
|
||||
- `Token string` with `json:"-"` (write-only, never exposed)
|
||||
- `HasToken bool` with `gorm:"-"` (computed field for frontend)
|
||||
- `URL string` for the endpoint
|
||||
- `ServiceConfig string` for extra JSON config (available for `parse_mode` if needed)
|
||||
|
||||
No schema migration is required.
|
||||
|
||||
### 3.6 Frontend — API Client
|
||||
|
||||
**File:** `frontend/src/api/notifications.ts`
|
||||
|
||||
#### Supported Types Array
|
||||
|
||||
```typescript
|
||||
export const SUPPORTED_NOTIFICATION_PROVIDER_TYPES = ['discord', 'gotify', 'webhook', 'email', 'telegram'] as const;
|
||||
```
|
||||
|
||||
#### `sanitizeProviderForWriteAction()`
|
||||
|
||||
**Minimal diff only.** Change only the type guard condition from:
|
||||
|
||||
```typescript
|
||||
if (type !== 'gotify') {
|
||||
```
|
||||
|
||||
to:
|
||||
|
||||
```typescript
|
||||
if (type !== 'gotify' && type !== 'telegram') {
|
||||
```
|
||||
|
||||
The surrounding normalization logic (token stripping, payload return) MUST remain untouched. No other lines in this function change.
|
||||
|
||||
#### `sanitizeProviderForReadLikeAction()`
|
||||
|
||||
No changes — already calls `sanitizeProviderForWriteAction()` then strips token.
|
||||
|
||||
### 3.7 Frontend — Notifications Page
|
||||
|
||||
**File:** `frontend/src/pages/Notifications.tsx`
|
||||
|
||||
#### Type Select Options
|
||||
|
||||
Add after the email option:
|
||||
|
||||
```tsx
|
||||
<option value="telegram">Telegram</option>
|
||||
```
|
||||
|
||||
#### Computed Flags
|
||||
|
||||
```typescript
|
||||
const isTelegram = type === 'telegram';
|
||||
```
|
||||
|
||||
#### `normalizeProviderPayloadForSubmit()`
|
||||
|
||||
Add telegram branch alongside gotify:
|
||||
|
||||
```typescript
|
||||
if (type === 'gotify' || type === 'telegram') {
|
||||
const normalizedToken = typeof payload.gotify_token === 'string' ? payload.gotify_token.trim() : '';
|
||||
if (normalizedToken.length > 0) {
|
||||
payload.token = normalizedToken;
|
||||
} else {
|
||||
delete payload.token;
|
||||
}
|
||||
} else {
|
||||
delete payload.token;
|
||||
}
|
||||
```
|
||||
|
||||
Note: Reuses the `gotify_token` form field for both Gotify and Telegram since both need a token input. This minimizes UI changes. The field label changes based on provider type.
|
||||
|
||||
#### Token Input Field
|
||||
|
||||
Expand the conditional from `{isGotify && (` to `{(isGotify || isTelegram) && (`:
|
||||
|
||||
```tsx
|
||||
{(isGotify || isTelegram) && (
|
||||
<div>
|
||||
<label htmlFor="provider-gotify-token" className="block text-sm font-medium text-gray-700 dark:text-gray-300">
|
||||
{isTelegram ? t('notificationProviders.telegramBotToken') : t('notificationProviders.gotifyToken')}
|
||||
</label>
|
||||
<input
|
||||
id="provider-gotify-token"
|
||||
type="password"
|
||||
autoComplete="new-password"
|
||||
{...register('gotify_token')}
|
||||
data-testid="provider-gotify-token"
|
||||
placeholder={initialData?.has_token
|
||||
? t('notificationProviders.gotifyTokenKeepPlaceholder')
|
||||
: isTelegram
|
||||
? t('notificationProviders.telegramBotTokenPlaceholder')
|
||||
: t('notificationProviders.gotifyTokenPlaceholder')}
|
||||
className="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600 dark:text-white sm:text-sm"
|
||||
aria-describedby={initialData?.has_token ? 'gotify-token-stored-hint' : undefined}
|
||||
/>
|
||||
{initialData?.has_token && (
|
||||
<p id="gotify-token-stored-hint" data-testid="gotify-token-stored-indicator" className="text-xs text-green-600 dark:text-green-400 mt-1">
|
||||
{t('notificationProviders.gotifyTokenStored')}
|
||||
</p>
|
||||
)}
|
||||
<p className="text-xs text-gray-500 mt-1">{t('notificationProviders.gotifyTokenWriteOnlyHint')}</p>
|
||||
</div>
|
||||
)}
|
||||
```
|
||||
|
||||
#### URL Field Placeholder
|
||||
|
||||
For Telegram, the URL field stores the chat_id (not a full URL). Update the placeholder and label accordingly:
|
||||
|
||||
```typescript
|
||||
placeholder={
|
||||
isEmail ? 'user@example.com, admin@example.com'
|
||||
: type === 'discord' ? 'https://discord.com/api/webhooks/...'
|
||||
: type === 'gotify' ? 'https://gotify.example.com/message'
|
||||
: isTelegram ? '987654321'
|
||||
: 'https://example.com/webhook'
|
||||
}
|
||||
```
|
||||
|
||||
Update the label for the URL field when type is telegram:
|
||||
|
||||
```typescript
|
||||
label={isTelegram ? t('notificationProviders.telegramChatId') : t('notificationProviders.url')}
|
||||
```
|
||||
|
||||
#### Clear Token on Type Change
|
||||
|
||||
Update the existing `useEffect` that clears `gotify_token`:
|
||||
|
||||
```typescript
|
||||
useEffect(() => {
|
||||
if (type !== 'gotify' && type !== 'telegram') {
|
||||
setValue('gotify_token', '', { shouldDirty: false, shouldTouch: false });
|
||||
}
|
||||
}, [type, setValue]);
|
||||
```
|
||||
|
||||
### 3.8 Frontend — i18n Strings
|
||||
|
||||
**File:** `frontend/src/locales/en/translation.json`
|
||||
|
||||
Add to the `notificationProviders` section:
|
||||
|
||||
```json
|
||||
"telegram": "Telegram",
|
||||
"telegramBotToken": "Bot Token",
|
||||
"telegramBotTokenPlaceholder": "Enter your Telegram Bot Token",
|
||||
"telegramChatId": "Chat ID",
|
||||
"telegramChatIdPlaceholder": "987654321",
|
||||
"telegramChatIdHelp": "Your Telegram chat, group, or channel ID. The bot token is stored securely and separately."
|
||||
```
|
||||
|
||||
### 3.9 API Contract (No Changes)
|
||||
|
||||
The existing REST endpoints remain unchanged:
|
||||
|
||||
| Method | Endpoint | Notes |
|
||||
|--------|----------|-------|
|
||||
| `GET` | `/api/notification-providers` | Returns all providers (token stripped) |
|
||||
| `POST` | `/api/notification-providers` | Create — now accepts `type: "telegram"` |
|
||||
| `PUT` | `/api/notification-providers/:id` | Update — token preserved if omitted |
|
||||
| `DELETE` | `/api/notification-providers/:id` | Delete — no type-specific logic |
|
||||
| `POST` | `/api/notification-providers/test` | Test — routes through `sendJSONPayload` |
|
||||
|
||||
Request/response schemas are unchanged. The `type` field now accepts `"telegram"` in addition to existing values.
|
||||
|
||||
---
|
||||
|
||||
## 4. Implementation Plan
|
||||
|
||||
### Phase 1: Playwright E2E Tests (Test-First)
|
||||
|
||||
**Rationale:** Per project conventions — write feature behaviour tests first.
|
||||
|
||||
**New file:** `tests/settings/telegram-notification-provider.spec.ts`
|
||||
|
||||
Modeled after `tests/settings/email-notification-provider.spec.ts`.
|
||||
|
||||
Test scenarios:
|
||||
1. Create a Telegram provider (name, chat_id in URL field, bot token in token field, enable events)
|
||||
2. Verify provider appears in the list
|
||||
3. Edit the Telegram provider (change name, verify token preservation)
|
||||
4. Test the Telegram provider (mock API returns 200)
|
||||
5. Delete the Telegram provider
|
||||
6. **Negative security test:** Verify `GET /api/notification-providers` does NOT expose the bot token in any response field
|
||||
7. **Negative security test:** Verify bot token is NOT present in the URL field of the API response
|
||||
|
||||
**Update file:** `tests/settings/notifications-payload.spec.ts`
|
||||
|
||||
Add telegram to the payload matrix test scenarios.
|
||||
|
||||
**E2E fixtures:** Update `telegramProvider` in `tests/fixtures/notifications.ts` — URL must contain only `chat_id`, token goes in the `token` field (see Research Findings section for updated fixture).
|
||||
|
||||
### Phase 2: Backend Implementation
|
||||
|
||||
**2A — Feature Flags (3 files)**
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `backend/internal/notifications/feature_flags.go` | Add `FlagTelegramServiceEnabled` constant |
|
||||
| `backend/internal/api/handlers/feature_flags_handler.go` | Add to `defaultFlags` + `defaultFlagValues` |
|
||||
| `backend/internal/notifications/router.go` | Add `case "telegram"` to `ShouldUseNotify()` |
|
||||
|
||||
**2B — Service Layer (1 file, 4 function changes)**
|
||||
|
||||
| File | Function | Change |
|
||||
|------|----------|--------|
|
||||
| `notification_service.go` | `isSupportedNotificationProviderType()` | Add `"telegram"` to case |
|
||||
| `notification_service.go` | `isDispatchEnabled()` | Add `case "telegram"` with flag check |
|
||||
| `notification_service.go` | `supportsJSONTemplates()` | Add `"telegram"` to case |
|
||||
| `notification_service.go` | `sendJSONPayload()` | Add telegram validation + dispatch branch |
|
||||
|
||||
**2C — Handler Layer (1 file, 3 locations)**
|
||||
|
||||
| File | Location | Change |
|
||||
|------|----------|--------|
|
||||
| `notification_provider_handler.go` | `Create()` type guard | Add `&& providerType != "telegram"` |
|
||||
| `notification_provider_handler.go` | `Update()` type guard | Same |
|
||||
| `notification_provider_handler.go` | `Update()` token preservation | Add `|| providerType == "telegram"` |
|
||||
|
||||
### Phase 3: Frontend Implementation
|
||||
|
||||
**3A — API Client (1 file)**
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `frontend/src/api/notifications.ts` | Add `'telegram'` to `SUPPORTED_NOTIFICATION_PROVIDER_TYPES`, update token sanitization logic |
|
||||
|
||||
**3B — Notifications Page (1 file)**
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `frontend/src/pages/Notifications.tsx` | Add telegram to type select, token field conditional, URL placeholder, `normalizeProviderPayloadForSubmit()`, type-change useEffect |
|
||||
|
||||
**3C — Localization (1 file)**
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `frontend/src/locales/en/translation.json` | Add telegram-specific label strings |
|
||||
|
||||
### Phase 4: Backend Tests
|
||||
|
||||
| Test File | Changes |
|
||||
|-----------|---------|
|
||||
| `notification_service_test.go` | Update "rejects unsupported provider" test (remove telegram from unsupported list). Add telegram dispatch/integration tests. |
|
||||
| `notification_service_json_test.go` | Add `TestSendJSONPayload_Telegram_*` tests: valid payload, missing text with message auto-map, missing both text and message, dispatch via httpWrapper, **SSRF hostname validation**, **401/403 error message** |
|
||||
| `notification_provider_handler_test.go` | Add telegram to Create/Update happy path tests, token preservation test. **Add negative test: verify GET response does not contain bot token in URL field or response body** |
|
||||
| `enhanced_security_notification_service_test.go` | Change telegram from "filtered" to "valid provider" in security dispatch tests |
|
||||
| Router test (if exists) | Add telegram to `ShouldUseNotify()` tests |
|
||||
|
||||
### Phase 5: Frontend Tests
|
||||
|
||||
| Test File | Changes |
|
||||
|-----------|---------|
|
||||
| `frontend/src/api/notifications.test.ts` | Remove telegram rejection test, add telegram CRUD sanitization tests |
|
||||
| `frontend/src/api/__tests__/notifications.test.ts` | Same changes (duplicate test location) |
|
||||
| `frontend/src/pages/Notifications.test.tsx` | Add telegram form rendering tests (token field visibility, placeholder text) |
|
||||
|
||||
### Phase 6: Integration, Documentation & Deployment
|
||||
|
||||
- Verify E2E tests pass with Docker container
|
||||
- Update `docs/features.md` with Telegram provider mention
|
||||
- No `ARCHITECTURE.md` changes needed (same provider pattern)
|
||||
- No database migration needed
|
||||
|
||||
---
|
||||
|
||||
## 5. Acceptance Criteria
|
||||
|
||||
### EARS Requirements
|
||||
|
||||
| ID | Requirement |
|
||||
|----|-------------|
|
||||
| T-01 | WHEN a user creates a notification provider with type "telegram", THE SYSTEM SHALL accept the provider and store it in the database |
|
||||
| T-02 | WHEN a user provides a bot token for a Telegram provider, THE SYSTEM SHALL store it securely and never expose it in API responses |
|
||||
| T-03 | WHEN a Telegram provider is enabled and a notification event fires, THE SYSTEM SHALL construct the Telegram API URL dynamically from the stored token (`https://api.telegram.org/bot` + token + `/sendMessage`), inject `chat_id` from the URL field into the POST body, and send the rendered template payload |
|
||||
| T-04 | WHEN the rendered JSON payload contains a "message" field but not a "text" field, THE SYSTEM SHALL auto-map "message" to "text" for Telegram compatibility |
|
||||
| T-05 | WHEN the Telegram feature flag is disabled, THE SYSTEM SHALL skip dispatch for all Telegram providers |
|
||||
| T-06 | WHEN a user updates a Telegram provider without providing a token, THE SYSTEM SHALL preserve the existing stored token |
|
||||
| T-07 | WHEN a user tests a Telegram provider, THE SYSTEM SHALL send a test notification through the standard sendJSONPayload path |
|
||||
| T-08 | WHEN the frontend renders the provider form with type "telegram", THE SYSTEM SHALL display a bot token input field and a chat_id input field (with appropriate placeholder) |
|
||||
| T-09 | WHEN dispatching a Telegram notification, THE SYSTEM SHALL validate that the constructed URL hostname is exactly `api.telegram.org` before sending (SSRF mitigation) |
|
||||
| T-10 | WHEN a Telegram test request receives HTTP 401 or 403, THE SYSTEM SHALL return the error message "Provider rejected authentication. Verify your Telegram Bot Token" |
|
||||
| T-11 | WHEN the API returns notification providers via GET, THE SYSTEM SHALL NOT include the bot token in the URL field or any other exposed response field |
|
||||
|
||||
### Definition of Done
|
||||
|
||||
- [ ] All 16 code touchpoints updated (see section 2 table)
|
||||
- [ ] E2E Playwright tests pass for Telegram CRUD + test send
|
||||
- [ ] Backend unit tests cover: type registration, dispatch routing, payload validation (text field), token preservation, feature flag gating
|
||||
- [ ] Frontend unit tests cover: type array acceptance, sanitization, form rendering
|
||||
- [ ] `go test ./...` passes
|
||||
- [ ] `npm test` passes
|
||||
- [ ] `npx playwright test --project=firefox` passes
|
||||
- [ ] `make lint-fast` passes (staticcheck)
|
||||
- [ ] Coverage threshold maintained (85%+)
|
||||
- [ ] GORM security scan passes (no model changes, but verify)
|
||||
- [ ] Token never appears in API responses, logs, or frontend state
|
||||
- [ ] Negative security tests pass (bot token not in GET response body or URL field)
|
||||
- [ ] SSRF hostname validation test passes (only `api.telegram.org` allowed)
|
||||
- [ ] Telegram 401/403 returns specific auth error message
|
||||
|
||||
---
|
||||
|
||||
## 6. Commit Slicing Strategy
|
||||
|
||||
### Decision: 2 PRs
|
||||
|
||||
**Trigger reasons:** Changes span backend + frontend + E2E tests with independent functionality per layer. Splitting improves review quality and rollback safety.
|
||||
|
||||
### PR-1: Backend — Telegram Provider Support
|
||||
|
||||
**Scope:** Feature flags, service layer, handler layer, all Go unit tests
|
||||
|
||||
**Files changed:**
|
||||
- `backend/internal/notifications/feature_flags.go`
|
||||
- `backend/internal/api/handlers/feature_flags_handler.go`
|
||||
- `backend/internal/notifications/router.go`
|
||||
- `backend/internal/services/notification_service.go`
|
||||
- `backend/internal/api/handlers/notification_provider_handler.go`
|
||||
- `backend/internal/services/notification_service_test.go`
|
||||
- `backend/internal/services/notification_service_json_test.go`
|
||||
- `backend/internal/api/handlers/notification_provider_handler_test.go`
|
||||
- `backend/internal/services/enhanced_security_notification_service_test.go`
|
||||
|
||||
**Dependencies:** None (self-contained backend change)
|
||||
|
||||
**Validation gates:**
|
||||
- `go test ./...` passes
|
||||
- `make lint-fast` passes
|
||||
- Coverage ≥ 85%
|
||||
- GORM security scan passes
|
||||
|
||||
**Rollback:** Revert PR — no DB migration to undo.
|
||||
|
||||
### PR-2: Frontend + E2E — Telegram Provider UI
|
||||
|
||||
**Scope:** Frontend API client, Notifications page, i18n strings, frontend unit tests, Playwright E2E tests
|
||||
|
||||
**Files changed:**
|
||||
- `frontend/src/api/notifications.ts`
|
||||
- `frontend/src/pages/Notifications.tsx`
|
||||
- `frontend/src/locales/en/translation.json`
|
||||
- `frontend/src/api/notifications.test.ts`
|
||||
- `frontend/src/api/__tests__/notifications.test.ts`
|
||||
- `frontend/src/pages/Notifications.test.tsx`
|
||||
- `tests/settings/telegram-notification-provider.spec.ts` (new)
|
||||
- `tests/settings/notifications-payload.spec.ts`
|
||||
|
||||
**Dependencies:** PR-1 must be merged first (backend must accept `type: "telegram"`)
|
||||
|
||||
**Validation gates:**
|
||||
- `npm test` passes
|
||||
- `npm run type-check` passes
|
||||
- `npx playwright test --project=firefox` passes
|
||||
- Coverage ≥ 85%
|
||||
|
||||
**Rollback:** Revert PR — frontend-only, no cascading effects.
|
||||
|
||||
---
|
||||
|
||||
## 7. Risk Assessment
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|------|-----------|--------|------------|
|
||||
| Telegram API rate limiting | Low | Medium | Use existing retry/timeout patterns from httpWrapper |
|
||||
| Bot token exposure in responses/logs | Low | Critical | Token stored ONLY in `Token` field (`json:"-"`), never in URL field. URL field contains only `chat_id`. Negative security tests verify this invariant. |
|
||||
| Template auto-mapping edge cases | Low | Low | Test with all three template types (minimal, detailed, custom) |
|
||||
| URL validation rejects chat_id format | Low | Low | URL field now stores a chat_id string (not a full URL). Validation may need adjustment to accept non-URL values for telegram type. |
|
||||
| SSRF via tampered stored data | Low | High | Dispatch-time validation ensures hostname is exactly `api.telegram.org`. Dedicated test covers this. |
|
||||
| E2E test flakiness with mocked API | Low | Low | Existing route-mocking patterns are stable |
|
||||
|
||||
---
|
||||
|
||||
## 8. Complexity Estimates
|
||||
|
||||
| Component | Estimate | Notes |
|
||||
|-----------|----------|-------|
|
||||
| Backend feature flags | S | 3 files, ~5 lines each |
|
||||
| Backend service layer | M | 4 function changes + telegram validation block |
|
||||
| Backend handler layer | S | 3 string-level changes |
|
||||
| Frontend API client | S | 2 lines + sanitization tweak |
|
||||
| Frontend UI | M | Template conditional, placeholder, useEffect updates |
|
||||
| Frontend i18n | S | 4 strings |
|
||||
| Backend tests | L | Multiple test files, new test functions, update existing assertions |
|
||||
| Frontend tests | M | Update rejection tests, add rendering tests |
|
||||
| E2E tests | M | New spec file modeled on existing email spec |
|
||||
| **Total** | **M-L** | ~2-3 days of focused implementation |
|
||||
@@ -1,352 +1,184 @@
|
||||
# QA Report — PR #800 (feature/beta-release)
|
||||
# QA / Security Audit Report
|
||||
|
||||
**Date:** 2026-03-06
|
||||
**Auditor:** QA Security Agent (QA Security Mode)
|
||||
**Branch:** `feature/beta-release`
|
||||
**PR:** [#800](https://github.com/Wikid82/charon/pull/800)
|
||||
**Scope:** Security hardening — WebSocket origin validation, CodeQL email-injection suppressions, Semgrep pipeline refactor, `security-local` Makefile target
|
||||
**Feature**: Telegram Notification Provider + Test Remediation
|
||||
**Date**: 2025-07-17
|
||||
**Auditor**: QA Security Agent
|
||||
**Overall Verdict**: ✅ **PASS — Ready to Merge**
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
## Summary
|
||||
|
||||
All 10 QA steps pass. No blocking issues. Backend coverage is **87.9%** (threshold: 85%). Frontend coverage is **89.73% lines** (threshold: 87%). Patch coverage is **90.6%** (overall). Zero static-analysis findings. Zero security scan findings. Security changes correctly implemented and individually verified.
|
||||
|
||||
**Overall Verdict: ✅ PASS — Ready to merge**
|
||||
All 8 audit gates passed. Zero Critical or High severity findings across all security scans. Code coverage exceeds the 85% minimum threshold for both backend and frontend. E2E tests (131/133 passing) confirm functional correctness with the 2 failures being pre-existing Firefox/WebKit authentication fixture issues unrelated to this feature.
|
||||
|
||||
---
|
||||
|
||||
## QA Step Results
|
||||
## Scope of Changes
|
||||
|
||||
### Step 1: Backend Build, Vet, and Tests
|
||||
|
||||
#### 1a — `go build ./...`
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **Exit Code** | 0 |
|
||||
| **Output** | Clean — no errors or warnings |
|
||||
| **Command** | `cd /projects/Charon && go build ./...` |
|
||||
|
||||
#### 1b — `go vet ./...`
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **Exit Code** | 0 |
|
||||
| **Output** | Clean — no issues |
|
||||
| **Command** | `cd /projects/Charon && go vet ./...` |
|
||||
|
||||
#### 1c — `go test ./...`
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **Packages** | 31 tested, 2 with no test files (skipped) |
|
||||
| **Failures** | 0 |
|
||||
| **Slowest Packages** | `crowdsec` (93s), `services` (74s), `handlers` (66s) |
|
||||
| **Command** | `cd /projects/Charon && go test ./...` |
|
||||
| File | Type | Summary |
|
||||
|------|------|---------|
|
||||
| `frontend/src/pages/Notifications.tsx` | Modified | Added `aria-label` attributes to Send Test, Edit, and Delete icon buttons |
|
||||
| `frontend/src/pages/__tests__/Notifications.test.tsx` | Modified | Fixed 2 tests, added `saveBeforeTesting` guard test |
|
||||
| `tests/settings/notifications.spec.ts` | Modified | Fixed 4 E2E tests — save-before-test pattern |
|
||||
| `tests/settings/notifications-payload.spec.ts` | Modified | Fixed 2 E2E tests — save-before-test pattern |
|
||||
| `tests/settings/telegram-notification-provider.spec.ts` | Modified | Replaced fragile keyboard nav with direct button locator |
|
||||
| `docs/plans/current_spec.md` | Modified | Updated from implementation plan to remediation plan |
|
||||
| `docs/plans/telegram_implementation_spec.md` | New | Archived original implementation plan |
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Backend Coverage Report
|
||||
## Audit Checklist
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **Statement Coverage** | **87.9%** (threshold: 85%) |
|
||||
| **Line Coverage** | **88.1%** (threshold: 85%) |
|
||||
| **Command** | `bash /projects/Charon/scripts/go-test-coverage.sh` |
|
||||
### 1. Pre-commit Hooks (lefthook)
|
||||
|
||||
**Packages below 85% (pre-existing, not caused by this PR):**
|
||||
| Status | Details |
|
||||
|--------|---------|
|
||||
| ✅ PASS | 6/6 hooks executed and passed |
|
||||
|
||||
| Package | Coverage | Notes |
|
||||
|---------|----------|-------|
|
||||
| `cmd/api` | 82.8% | Pre-existing; bootstrap/init code difficult to unit-test |
|
||||
| `internal/util` | 78.0% | Pre-existing; utility helpers with edge-case paths |
|
||||
|
||||
All other packages meet or exceed the 85% threshold.
|
||||
Hooks executed: `check-yaml`, `actionlint`, `end-of-file-fixer`, `trailing-whitespace`, `dockerfile-check`, `shellcheck`
|
||||
Language-specific hooks (Go lint, frontend lint) skipped — no staged files at audit time.
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Frontend Tests and Coverage
|
||||
### 2. Backend Unit Test Coverage
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **Test Files** | 27 |
|
||||
| **Tests Passed** | 581 |
|
||||
| **Tests Skipped** | 1 |
|
||||
| **Failures** | 0 |
|
||||
| **Line Coverage** | **89.73%** (threshold: 87%) |
|
||||
| **Statement Coverage** | 89.0% |
|
||||
| **Function Coverage** | 86.26% |
|
||||
| **Branch Coverage** | 81.07% (not enforced — only `lines` is configured) |
|
||||
| **Command** | `cd /projects/Charon/frontend && npm run test -- --coverage --reporter=verbose` |
|
||||
| Metric | Value | Threshold | Status |
|
||||
|--------|-------|-----------|--------|
|
||||
| Statements | 87.9% | 85% | ✅ PASS |
|
||||
| Lines | 88.1% | 85% | ✅ PASS |
|
||||
|
||||
**Note:** Branch coverage at 81.07% is below a 85% target but is **not an enforced threshold** in the Vitest configuration. Only line coverage is enforced (configured at 87%). This is pre-existing and not caused by this PR.
|
||||
Command: `bash scripts/go-test-coverage.sh`
|
||||
|
||||
---
|
||||
|
||||
### Step 4: TypeScript Type Check
|
||||
### 3. Frontend Unit Test Coverage
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **Errors** | 0 |
|
||||
| **Exit Code** | 0 |
|
||||
| **Command** | `cd /projects/Charon/frontend && npm run type-check` |
|
||||
| Metric | Value | Threshold | Status |
|
||||
|--------|-------|-----------|--------|
|
||||
| Statements | 89.01% | 85% | ✅ PASS |
|
||||
| Branches | 81.07% | — | Advisory |
|
||||
| Functions | 86.18% | 85% | ✅ PASS |
|
||||
| Lines | 89.73% | 85% | ✅ PASS |
|
||||
|
||||
- **Test files**: 158 passed
|
||||
- **Tests**: 1871 passed, 5 skipped, 0 failed
|
||||
|
||||
Command: `npx vitest run --coverage`
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Pre-commit Hooks (Non-Semgrep)
|
||||
### 4. TypeScript Type Check
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **Hooks Passed** | 15/15 |
|
||||
| **Semgrep** | Correctly absent (now at `stages: [pre-push]` — see Security Changes) |
|
||||
| **Command** | `cd /projects/Charon && pre-commit run --all-files` |
|
||||
|
||||
**Hooks executed and their status:**
|
||||
|
||||
| Hook | Status |
|
||||
|------|--------|
|
||||
| fix end of files | Passed |
|
||||
| trim trailing whitespace | Passed |
|
||||
| check yaml | Passed |
|
||||
| check for added large files | Passed |
|
||||
| shellcheck | Passed |
|
||||
| actionlint (GitHub Actions) | Passed |
|
||||
| dockerfile validation | Passed |
|
||||
| Go Vet | Passed |
|
||||
| golangci-lint (Fast Linters - BLOCKING) | Passed |
|
||||
| Check .version matches latest Git tag | Passed |
|
||||
| Prevent large files not tracked by LFS | Passed |
|
||||
| Prevent committing CodeQL DB artifacts | Passed |
|
||||
| Prevent committing data/backups files | Passed |
|
||||
| Frontend TypeScript Check | Passed |
|
||||
| Frontend Lint (Fix) | Passed |
|
||||
| Status | Details |
|
||||
|--------|---------|
|
||||
| ✅ PASS | `npx tsc --noEmit` — zero errors |
|
||||
|
||||
---
|
||||
|
||||
### Step 6: Local Patch Coverage Preflight
|
||||
### 5. Local Patch Coverage Report
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **Overall Patch Coverage** | **90.6%** |
|
||||
| **Backend Patch Coverage** | **90.4%** |
|
||||
| **Frontend Patch Coverage** | **100%** |
|
||||
| **Artifacts** | `test-results/local-patch-report.md` ✅, `test-results/local-patch-report.json` ✅ |
|
||||
| **Command** | `bash /projects/Charon/scripts/local-patch-report.sh` |
|
||||
| Scope | Patch Coverage | Status |
|
||||
|-------|---------------|--------|
|
||||
| Overall | 87.6% | Advisory (90% target) |
|
||||
| Backend | 87.2% | ✅ PASS (≥85%) |
|
||||
| Frontend | 88.6% | ✅ PASS (≥85%) |
|
||||
|
||||
**Files with partially covered changed lines:**
|
||||
Artifacts generated:
|
||||
- `test-results/local-patch-report.md`
|
||||
- `test-results/local-patch-report.json`
|
||||
|
||||
| File | Patch Coverage | Uncovered Lines | Notes |
|
||||
|------|---------------|-----------------|-------|
|
||||
| `backend/internal/services/mail_service.go` | 84.2% | 334–335, 339–340, 346–347, 351–352, 540 | SMTP sink lines; CodeQL `[go/email-injection]` suppressions applied; hard to unit-test directly |
|
||||
| `backend/internal/services/notification_service.go` | 97.6% | 1 line | Minor branch |
|
||||
|
||||
Frontend patch coverage is 100% — all changed lines in `notifications.test.ts` and `SecurityNotificationSettingsModal.test.tsx` are covered.
|
||||
Files needing additional coverage (advisory, non-blocking):
|
||||
- `EncryptionManagement.tsx`
|
||||
- `Notifications.tsx`
|
||||
- `notification_provider_handler.go`
|
||||
- `notification_service.go`
|
||||
- `http_wrapper.go`
|
||||
|
||||
---
|
||||
|
||||
### Step 7: Static Analysis
|
||||
### 6. Trivy Filesystem Scan
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **Issues** | 0 |
|
||||
| **Linters** | golangci-lint (`--config .golangci-fast.yml`) |
|
||||
| **Command** | `make -C /projects/Charon lint-fast` |
|
||||
| Category | Count | Status |
|
||||
|----------|-------|--------|
|
||||
| Critical | 0 | ✅ |
|
||||
| High | 0 | ✅ |
|
||||
| Medium | 0 | ✅ |
|
||||
| Low | 0 | ✅ |
|
||||
| Secrets | 0 | ✅ |
|
||||
|
||||
Command: `trivy fs --severity CRITICAL,HIGH,MEDIUM,LOW --scanners vuln,secret .`
|
||||
|
||||
---
|
||||
|
||||
### Step 8: Semgrep Validation (Manual)
|
||||
### 7. Docker Image Scan (Grype)
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **Findings** | 0 |
|
||||
| **Rules Applied** | 42 (from `p/golang` ruleset) |
|
||||
| **Files Scanned** | 182 |
|
||||
| **Command** | `SEMGREP_CONFIG=p/golang bash /projects/Charon/scripts/pre-commit-hooks/semgrep-scan.sh` |
|
||||
| Severity | Count | Status |
|
||||
|----------|-------|--------|
|
||||
| Critical | 0 | ✅ PASS |
|
||||
| High | 0 | ✅ PASS |
|
||||
| Medium | 12 | ℹ️ Non-blocking |
|
||||
| Low | 3 | ℹ️ Non-blocking |
|
||||
|
||||
This step validates the new `p/golang` ruleset configuration introduced in this PR.
|
||||
- **SBOM packages**: 1672
|
||||
- **Docker build**: All stages cached (no build changes)
|
||||
- All Medium/Low findings are in base image dependencies, not in application code
|
||||
|
||||
---
|
||||
|
||||
### Step 9: `make security-local`
|
||||
### 8. CodeQL Static Analysis
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **govulncheck** | 0 vulnerabilities |
|
||||
| **Semgrep (p/golang)** | 0 findings |
|
||||
| **Exit Code** | 0 |
|
||||
| **Command** | `make -C /projects/Charon security-local` |
|
||||
| Language | Errors | Warnings | Status |
|
||||
|----------|--------|----------|--------|
|
||||
| Go | 0 | 0 | ✅ PASS |
|
||||
| JavaScript/TypeScript | 0 | 0 | ✅ PASS |
|
||||
|
||||
This is the new `security-local` Makefile target introduced by this PR — both constituent checks pass.
|
||||
- JS/TS scan covered 354/354 files
|
||||
- 1 informational note: semicolon style in test file (non-blocking)
|
||||
|
||||
---
|
||||
|
||||
### Step 10: Git Diff Summary
|
||||
## Additional Security Checks
|
||||
|
||||
`git diff --name-only` reports **9 changed files** (unstaged relative to last commit):
|
||||
### GORM Security Scan
|
||||
|
||||
| File | Category | Change Summary |
|
||||
|------|----------|----------------|
|
||||
| `.pre-commit-config.yaml` | Config | `semgrep-scan` moved from `stages: [manual]` → `stages: [pre-push]` |
|
||||
| `Makefile` | Build | Added `security-local` target |
|
||||
| `backend/internal/api/handlers/cerberus_logs_ws.go` | Backend | Added `# nosemgrep` annotation on `.Upgrade()` call |
|
||||
| `backend/internal/api/handlers/logs_ws.go` | Backend | Replaced insecure `CheckOrigin: return true` with host-based validation |
|
||||
| `backend/internal/api/handlers/settings_handler.go` | Backend | Added documentation comment above `SendEmail` call |
|
||||
| `backend/internal/api/handlers/user_handler.go` | Backend | Added documentation comments above 2 `SendInvite` calls |
|
||||
| `backend/internal/services/mail_service.go` | Backend | Added `// codeql[go/email-injection]` suppressions on 3 SMTP sink lines |
|
||||
| `docs/plans/current_spec.md` | Docs | Spec updates |
|
||||
| `scripts/pre-commit-hooks/semgrep-scan.sh` | Scripts | Default config `auto`→`p/golang`; added `--severity` flags; scope to `frontend/src` |
|
||||
**Status**: Not applicable — no changes to `backend/internal/models/**`, GORM services, or migrations in this PR.
|
||||
|
||||
**HEAD commit (`ee224adc`) additionally included** (committed changes not in the diff above):
|
||||
### Gotify Token Exposure Review
|
||||
|
||||
- `backend/internal/models/notification_config.go`
|
||||
- `backend/internal/services/mail_service_test.go`
|
||||
- `backend/internal/services/notification_service.go`
|
||||
- `backend/internal/services/notification_service_test.go`
|
||||
- `frontend/src/api/notifications.test.ts`
|
||||
- `frontend/src/components/__tests__/SecurityNotificationSettingsModal.test.tsx`
|
||||
| Location | Status |
|
||||
|----------|--------|
|
||||
| Logs & test artifacts | ✅ Clean |
|
||||
| API examples & report output | ✅ Clean |
|
||||
| Screenshots | ✅ Clean |
|
||||
| Tokenized URL query strings | ✅ Clean |
|
||||
|
||||
---
|
||||
|
||||
### Bonus: GORM Security Scan
|
||||
## E2E Test Results (Pre-verified)
|
||||
|
||||
Triggered because `backend/internal/models/notification_config.go` changed in HEAD.
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Total tests | 133 |
|
||||
| Passed | 131 |
|
||||
| Failed | 2 (pre-existing) |
|
||||
|
||||
| Metric | Result |
|
||||
|--------|--------|
|
||||
| **Status** | ✅ PASS |
|
||||
| **CRITICAL** | 0 |
|
||||
| **HIGH** | 0 |
|
||||
| **MEDIUM** | 0 |
|
||||
| **INFO** | 2 (pre-existing: missing index suggestions on `UserPermittedHost` foreign keys in `user.go`) |
|
||||
| **Files Scanned** | 41 Go model files |
|
||||
| **Command** | `bash /projects/Charon/scripts/scan-gorm-security.sh --check` |
|
||||
|
||||
The 2 INFO findings are pre-existing and unrelated to this PR.
|
||||
The 2 failures are pre-existing Firefox/WebKit authentication fixture issues unrelated to this feature. These were verified prior to this audit and were **not re-run** per instructions.
|
||||
|
||||
---
|
||||
|
||||
## Security Change Verification
|
||||
## Risk Assessment
|
||||
|
||||
### 1. WebSocket Origin Validation (`logs_ws.go`)
|
||||
|
||||
**Change:** Replaced `CheckOrigin: func(r *http.Request) bool { return true }` with proper host-based validation.
|
||||
|
||||
**Implementation verified:**
|
||||
- Imports `"net/url"` (line 5)
|
||||
- `CheckOrigin` function parses `Origin` header via `url.Parse()`
|
||||
- Compares `originURL.Host` to `r.Host`, honoring `X-Forwarded-Host` for proxy scenarios
|
||||
- Returns `false` on parse error or host mismatch
|
||||
|
||||
**Assessment:** ✅ Correct. Addresses the Semgrep `websocket-missing-origin-check` finding. Guards against cross-site WebSocket hijacking (CWE-346).
|
||||
| Risk Area | Assessment |
|
||||
|-----------|-----------|
|
||||
| Security vulnerabilities | **None** — all scans clean |
|
||||
| Regression risk | **Low** — changes are additive (aria-labels) and test fixes |
|
||||
| Test coverage gaps | **Low** — all coverage thresholds exceeded |
|
||||
| Token/secret leakage | **None** — all artifact scans clean |
|
||||
|
||||
---
|
||||
|
||||
### 2. Nosemgrep Annotation (`cerberus_logs_ws.go`)
|
||||
## Verdict
|
||||
|
||||
**Change:** Added `# nosemgrep: go.gorilla.security.audit.websocket-missing-origin-check.websocket-missing-origin-check` on the `.Upgrade()` call.
|
||||
**✅ PASS — All gates satisfied. Feature is ready to merge.**
|
||||
|
||||
**Justification verified:** This handler uses the shared `upgrader` variable defined in `logs_ws.go`, which now has a valid `CheckOrigin` function. The annotation is correct — the rule fires on the call site but the underlying `upgrader` is already secured.
|
||||
|
||||
**Assessment:** ✅ Correct. Suppression is justified and scoped to a single line.
|
||||
|
||||
---
|
||||
|
||||
### 3. CodeQL Email-Injection Suppressions (`mail_service.go`)
|
||||
|
||||
**Change:** Added `// codeql[go/email-injection]` on lines 370, 534, 588 (SMTP `smtp.SendMail()` calls).
|
||||
|
||||
**Assessment:** ✅ Correct. Each suppressed sink is protected by documented 4-layer defense:
|
||||
1. `sanitizeForEmail()` — strips `\r`/`\n` from user inputs
|
||||
2. `rejectCRLF()` — hard-rejects strings containing CRLF sequences
|
||||
3. `encodeSubject()` — RFC 2047 encodes email subject
|
||||
4. `html.EscapeString()` / `sanitizeEmailBody()` — HTML-escapes body content
|
||||
|
||||
Suppressions are placed at the exact CodeQL sink lines per the CodeQL suppression spec.
|
||||
|
||||
---
|
||||
|
||||
### 4. Semgrep Pipeline Refactor
|
||||
|
||||
**Changes verified:**
|
||||
|
||||
| Change | File | Assessment |
|
||||
|--------|------|------------|
|
||||
| `stages: [pre-push]` | `.pre-commit-config.yaml` | ✅ Semgrep now runs on `git push`, not every commit. Faster commit loop. |
|
||||
| Default config `auto` → `p/golang` | `semgrep-scan.sh` | ✅ Deterministic, focused ruleset. `auto` was non-deterministic. |
|
||||
| `--severity ERROR --severity WARNING` flags | `semgrep-scan.sh` | ✅ Explicitly filters noise; only ERROR/WARNING findings are blocking. |
|
||||
| Scope to `frontend/src` | `semgrep-scan.sh` | ✅ Focuses frontend scanning on source directory. |
|
||||
|
||||
---
|
||||
|
||||
### 5. `security-local` Makefile Target
|
||||
|
||||
**Target verified (Makefile line 149):**
|
||||
```makefile
|
||||
security-local: ## Run govulncheck + semgrep (p/golang) before push — fast local gate
|
||||
@echo "[1/2] Running govulncheck..."
|
||||
@./scripts/security-scan.sh
|
||||
@echo "[2/2] Running Semgrep (p/golang, ERROR+WARNING)..."
|
||||
@SEMGREP_CONFIG=p/golang ./scripts/pre-commit-hooks/semgrep-scan.sh
|
||||
```
|
||||
|
||||
**Assessment:** ✅ Correct. Provides a fast, developer-friendly pre-push gate that mirrors the CI security checks.
|
||||
|
||||
---
|
||||
|
||||
## Gotify Token Review
|
||||
|
||||
- No Gotify tokens found in diffs, test output, or log artifacts
|
||||
- No tokenized URLs (e.g., `?token=...`) exposed in any output
|
||||
- ✅ Clean
|
||||
|
||||
---
|
||||
|
||||
## Issues and Observations
|
||||
|
||||
### Blocking Issues
|
||||
|
||||
**None.**
|
||||
|
||||
### Non-Blocking Observations
|
||||
|
||||
| Observation | Severity | Notes |
|
||||
|-------------|----------|-------|
|
||||
| `cmd/api` backend coverage at 82.8% | ⚠️ INFO | Pre-existing. Bootstrap/init code. Not caused by this PR. |
|
||||
| `internal/util` backend coverage at 78.0% | ⚠️ INFO | Pre-existing. Utility helpers. Not caused by this PR. |
|
||||
| Frontend branch coverage at 81.07% | ⚠️ INFO | Pre-existing. Threshold not enforced (only `lines` is). |
|
||||
| `mail_service.go` patch coverage at 84.2% | ⚠️ INFO | SMTP sink lines are intentionally difficult to unit-test. CodeQL suppressions are the documented mitigation. |
|
||||
| GORM INFO findings (missing FK indexes) | ⚠️ INFO | Pre-existing in `user.go`. Unrelated to this PR. |
|
||||
|
||||
---
|
||||
|
||||
## Final Determination
|
||||
|
||||
| Step | Status |
|
||||
|------|--------|
|
||||
| 1a. `go build ./...` | ✅ PASS |
|
||||
| 1b. `go vet ./...` | ✅ PASS |
|
||||
| 1c. `go test ./...` | ✅ PASS |
|
||||
| 2. Backend coverage | ✅ PASS — 87.9% / 88.1% |
|
||||
| 3. Frontend tests + coverage | ✅ PASS — 581 pass, 89.73% lines |
|
||||
| 4. TypeScript type check | ✅ PASS |
|
||||
| 5. Pre-commit hooks | ✅ PASS — 15/15 |
|
||||
| 6. Local patch coverage preflight | ✅ PASS — 90.6% overall |
|
||||
| 7. `make lint-fast` | ✅ PASS — 0 issues |
|
||||
| 8. Semgrep manual validation | ✅ PASS — 0 findings |
|
||||
| 9. `make security-local` | ✅ PASS |
|
||||
| 10. Git diff | ✅ 9 changed files |
|
||||
| GORM security scan | ✅ PASS — 0 CRITICAL/HIGH |
|
||||
|
||||
**✅ OVERALL: PASS — All gates met. No blocking issues. Ready to merge.**
|
||||
All 8 mandatory audit checks passed. No Critical or High severity security issues were identified. Code coverage exceeds minimum thresholds. The changes are well-scoped test remediation fixes and accessibility improvements with no architectural risk.
|
||||
|
||||
@@ -12,7 +12,7 @@ import security from 'eslint-plugin-security';
|
||||
import noUnsanitized from 'eslint-plugin-no-unsanitized';
|
||||
import reactCompiler from 'eslint-plugin-react-compiler';
|
||||
import testingLibrary from 'eslint-plugin-testing-library';
|
||||
import vitest from 'eslint-plugin-vitest';
|
||||
import vitest from '@vitest/eslint-plugin';
|
||||
import css from '@eslint/css';
|
||||
import json from '@eslint/json';
|
||||
import markdown from '@eslint/markdown';
|
||||
|
||||
3169
frontend/package-lock.json
generated
3169
frontend/package-lock.json
generated
File diff suppressed because it is too large
Load Diff
@@ -34,52 +34,67 @@
|
||||
"@radix-ui/react-tabs": "^1.1.13",
|
||||
"@radix-ui/react-tooltip": "^1.2.8",
|
||||
"@tanstack/react-query": "^5.90.21",
|
||||
"@typescript-eslint/utils": "^8.57.0",
|
||||
"axios": "^1.13.6",
|
||||
"class-variance-authority": "^0.7.1",
|
||||
"clsx": "^2.1.1",
|
||||
"date-fns": "^4.1.0",
|
||||
"i18next": "^25.8.14",
|
||||
"i18next": "^25.8.18",
|
||||
"i18next-browser-languagedetector": "^8.2.1",
|
||||
"lucide-react": "^0.577.0",
|
||||
"react": "^19.2.4",
|
||||
"react-dom": "^19.2.4",
|
||||
"react-hook-form": "^7.71.2",
|
||||
"react-hot-toast": "^2.6.0",
|
||||
"react-i18next": "^16.5.6",
|
||||
"react-i18next": "^16.5.8",
|
||||
"react-router-dom": "^7.13.1",
|
||||
"tailwind-merge": "^3.5.0",
|
||||
"tldts": "^7.0.25"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@eslint/css": "^0.14.1",
|
||||
"@eslint/css": "^1.0.0",
|
||||
"@eslint/js": "^9.39.3 <10.0.0",
|
||||
"@eslint/json": "^1.0.1",
|
||||
"@eslint/json": "^1.1.0",
|
||||
"@eslint/markdown": "^7.5.1",
|
||||
"@playwright/test": "^1.58.2",
|
||||
"@tailwindcss/postcss": "^4.2.1",
|
||||
"@testing-library/jest-dom": "^6.9.1",
|
||||
"@testing-library/react": "^16.3.2",
|
||||
"@testing-library/user-event": "^14.6.1",
|
||||
"@types/node": "^25.3.5",
|
||||
"@types/eslint-plugin-jsx-a11y": "^6.10.1",
|
||||
"@types/node": "^25.4.0",
|
||||
"@types/react": "^19.2.14",
|
||||
"@types/react-dom": "^19.2.3",
|
||||
"@typescript-eslint/eslint-plugin": "^8.56.1",
|
||||
"@typescript-eslint/parser": "^8.56.1",
|
||||
"@typescript-eslint/eslint-plugin": "^8.57.0",
|
||||
"@typescript-eslint/parser": "^8.57.0",
|
||||
"@vitejs/plugin-react": "^5.1.4",
|
||||
"@vitest/coverage-istanbul": "^4.0.18",
|
||||
"@vitest/coverage-v8": "^4.0.18",
|
||||
"@vitest/eslint-plugin": "^1.6.10",
|
||||
"@vitest/ui": "^4.0.18",
|
||||
"autoprefixer": "^10.4.27",
|
||||
"eslint": "^9.39.3 <10.0.0",
|
||||
"eslint-import-resolver-typescript": "^4.4.4",
|
||||
"eslint-plugin-import-x": "^4.16.1",
|
||||
"eslint-plugin-jsx-a11y": "^6.10.2",
|
||||
"eslint-plugin-no-unsanitized": "^4.1.5",
|
||||
"eslint-plugin-promise": "^7.2.1",
|
||||
"eslint-plugin-react-compiler": "^19.1.0-rc.2",
|
||||
"eslint-plugin-react-hooks": "^7.0.1",
|
||||
"eslint-plugin-react-refresh": "^0.5.2",
|
||||
"eslint-plugin-security": "^4.0.0",
|
||||
"eslint-plugin-sonarjs": "^4.0.2",
|
||||
"eslint-plugin-testing-library": "^7.16.0",
|
||||
"eslint-plugin-unicorn": "^63.0.0",
|
||||
"eslint-plugin-unused-imports": "^4.4.1",
|
||||
"jsdom": "28.1.0",
|
||||
"knip": "^5.86.0",
|
||||
"postcss": "^8.5.8",
|
||||
"tailwindcss": "^4.2.1",
|
||||
"typescript": "^5.9.3",
|
||||
"typescript-eslint": "^8.56.1",
|
||||
"typescript-eslint": "^8.57.0",
|
||||
"vite": "^7.3.1",
|
||||
"vitest": "^4.0.18"
|
||||
"vitest": "^4.0.18",
|
||||
"zod-validation-error": "^5.0.0"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
import { Suspense, lazy } from 'react'
|
||||
import { Navigate } from 'react-router-dom'
|
||||
import { BrowserRouter as Router, Routes, Route, Outlet } from 'react-router-dom'
|
||||
import { Toaster } from 'react-hot-toast'
|
||||
import { BrowserRouter as Router, Routes, Route, Outlet, Navigate } from 'react-router-dom'
|
||||
|
||||
import Layout from './components/Layout'
|
||||
import { ToastContainer } from './components/Toast'
|
||||
import { SetupGuard } from './components/SetupGuard'
|
||||
import { LoadingOverlay } from './components/LoadingStates'
|
||||
import RequireAuth from './components/RequireAuth'
|
||||
import RequireRole from './components/RequireRole'
|
||||
import { SetupGuard } from './components/SetupGuard'
|
||||
import { ToastContainer } from './components/Toast'
|
||||
import { AuthProvider } from './context/AuthContext'
|
||||
|
||||
// Lazy load pages for code splitting
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { describe, it, expect, beforeEach } from 'vitest'
|
||||
|
||||
import i18n from '../i18n'
|
||||
|
||||
describe('i18n configuration', () => {
|
||||
@@ -13,9 +14,9 @@ describe('i18n configuration', () => {
|
||||
|
||||
it('has all required language resources', () => {
|
||||
const languages = ['en', 'es', 'fr', 'de', 'zh']
|
||||
languages.forEach((lang) => {
|
||||
for (const lang of languages) {
|
||||
expect(i18n.hasResourceBundle(lang, 'translation')).toBe(true)
|
||||
})
|
||||
}
|
||||
})
|
||||
|
||||
it('translates common keys', () => {
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { accessListsApi } from '../accessLists';
|
||||
|
||||
import { accessListsApi, type AccessList } from '../accessLists';
|
||||
import client from '../client';
|
||||
import type { AccessList } from '../accessLists';
|
||||
|
||||
|
||||
// Mock the client module
|
||||
vi.mock('../client', () => ({
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest'
|
||||
|
||||
import client from '../../api/client'
|
||||
import { getBackups, createBackup, restoreBackup, deleteBackup } from '../backups'
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
|
||||
import { getCertificates, uploadCertificate, deleteCertificate, type Certificate } from '../certificates';
|
||||
import client from '../client';
|
||||
import { getCertificates, uploadCertificate, deleteCertificate, Certificate } from '../certificates';
|
||||
|
||||
vi.mock('../client', () => ({
|
||||
default: {
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
import axios from 'axios'
|
||||
import { beforeEach, describe, it, expect, vi, afterEach } from 'vitest'
|
||||
|
||||
import { setAuthErrorHandler, setAuthToken } from '../client'
|
||||
|
||||
type ResponseHandler = (value: unknown) => unknown
|
||||
type ErrorHandler = (error: ResponseError) => Promise<never>
|
||||
|
||||
@@ -45,10 +48,6 @@ vi.mock('axios', () => {
|
||||
}
|
||||
})
|
||||
|
||||
// Must import AFTER mock definition
|
||||
import { setAuthErrorHandler, setAuthToken } from '../client'
|
||||
import axios from 'axios'
|
||||
|
||||
// Get mock client instance for header assertions
|
||||
const getMockClient = () => {
|
||||
const mockAxios = vi.mocked(axios)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest'
|
||||
import * as consoleEnrollment from '../consoleEnrollment'
|
||||
|
||||
import client from '../client'
|
||||
import * as consoleEnrollment from '../consoleEnrollment'
|
||||
|
||||
vi.mock('../client')
|
||||
|
||||
@@ -480,13 +481,10 @@ describe('consoleEnrollment API', () => {
|
||||
}
|
||||
vi.mocked(client.post).mockRejectedValue(error)
|
||||
|
||||
try {
|
||||
await consoleEnrollment.enrollConsole(payload)
|
||||
} catch (e: unknown) {
|
||||
// Error message should NOT contain the key
|
||||
const error = e as { response?: { data?: { error?: string } } }
|
||||
expect(error.response?.data?.error).not.toContain('cs-enroll-sensitive-key')
|
||||
}
|
||||
const thrown = await consoleEnrollment.enrollConsole(payload).catch((e: unknown) => e)
|
||||
const caughtError = thrown as { response?: { data?: { error?: string } } }
|
||||
// Error message should NOT contain the key
|
||||
expect(caughtError.response?.data?.error).not.toContain('cs-enroll-sensitive-key')
|
||||
})
|
||||
|
||||
it('should handle correlation_id for debugging without exposing keys', async () => {
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest'
|
||||
|
||||
import client from '../client'
|
||||
import {
|
||||
getCredentials,
|
||||
getCredential,
|
||||
@@ -11,7 +13,6 @@ import {
|
||||
type CredentialRequest,
|
||||
type CredentialTestResult,
|
||||
} from '../credentials'
|
||||
import client from '../client'
|
||||
|
||||
vi.mock('../client')
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest'
|
||||
import * as crowdsec from '../crowdsec'
|
||||
|
||||
import client from '../client'
|
||||
import * as crowdsec from '../crowdsec'
|
||||
|
||||
vi.mock('../client')
|
||||
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest'
|
||||
import { detectDNSProvider, getDetectionPatterns } from '../dnsDetection'
|
||||
|
||||
import client from '../client'
|
||||
import type { DetectionResult, NameserverPattern } from '../dnsDetection'
|
||||
import { detectDNSProvider, getDetectionPatterns, type DetectionResult, type NameserverPattern } from '../dnsDetection'
|
||||
|
||||
|
||||
vi.mock('../client')
|
||||
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest'
|
||||
|
||||
import client from '../client'
|
||||
import {
|
||||
getDNSProviders,
|
||||
getDNSProvider,
|
||||
@@ -12,7 +14,6 @@ import {
|
||||
type DNSProviderRequest,
|
||||
type DNSProviderTypeInfo,
|
||||
} from '../dnsProviders'
|
||||
import client from '../client'
|
||||
|
||||
vi.mock('../client')
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { vi, describe, it, expect, beforeEach } from 'vitest';
|
||||
import { dockerApi } from '../docker';
|
||||
|
||||
import client from '../client';
|
||||
import { dockerApi } from '../docker';
|
||||
|
||||
vi.mock('../client', () => ({
|
||||
default: {
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
|
||||
import client from '../client';
|
||||
import { getDomains, createDomain, deleteDomain, Domain } from '../domains';
|
||||
import { getDomains, createDomain, deleteDomain, type Domain } from '../domains';
|
||||
|
||||
vi.mock('../client', () => ({
|
||||
default: {
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest'
|
||||
|
||||
import client from '../client'
|
||||
import {
|
||||
getEncryptionStatus,
|
||||
rotateEncryptionKey,
|
||||
@@ -9,7 +11,6 @@ import {
|
||||
type RotationHistoryEntry,
|
||||
type KeyValidationResult,
|
||||
} from '../encryption'
|
||||
import client from '../client'
|
||||
|
||||
vi.mock('../client')
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { uploadCaddyfile, uploadCaddyfilesMulti, getImportPreview, commitImport, cancelImport, getImportStatus } from '../import';
|
||||
|
||||
import client from '../client';
|
||||
import { uploadCaddyfile, uploadCaddyfilesMulti, getImportPreview, commitImport, cancelImport, getImportStatus } from '../import';
|
||||
|
||||
vi.mock('../client', () => ({
|
||||
default: {
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { uploadJSONExport, commitJSONImport, cancelJSONImport } from '../jsonImport';
|
||||
|
||||
import client from '../client';
|
||||
import { uploadJSONExport, commitJSONImport, cancelJSONImport } from '../jsonImport';
|
||||
|
||||
vi.mock('../client', () => ({
|
||||
default: {
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
|
||||
import { connectLiveLogs } from '../logs';
|
||||
|
||||
// Mock WebSocket
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest'
|
||||
|
||||
import client from '../client'
|
||||
import { downloadLog, getLogContent, getLogs } from '../logs'
|
||||
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest'
|
||||
|
||||
import client from '../client'
|
||||
import {
|
||||
getChallenge,
|
||||
createChallenge,
|
||||
@@ -6,7 +8,6 @@ import {
|
||||
pollChallenge,
|
||||
deleteChallenge,
|
||||
} from '../manualChallenge'
|
||||
import client from '../client'
|
||||
|
||||
vi.mock('../client', () => ({
|
||||
default: {
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest'
|
||||
|
||||
import client from '../client'
|
||||
import {
|
||||
getProviders,
|
||||
@@ -54,7 +55,8 @@ describe('notifications api', () => {
|
||||
|
||||
await expect(createProvider({ name: 'x', type: 'slack' })).rejects.toThrow('Unsupported notification provider type: slack')
|
||||
await expect(updateProvider('2', { name: 'updated', type: 'generic' })).rejects.toThrow('Unsupported notification provider type: generic')
|
||||
await expect(testProvider({ id: '2', name: 'test', type: 'telegram' })).rejects.toThrow('Unsupported notification provider type: telegram')
|
||||
await testProvider({ id: '2', name: 'test', type: 'telegram' })
|
||||
expect(client.post).toHaveBeenCalledWith('/notifications/providers/test', { id: '2', name: 'test', type: 'telegram' })
|
||||
})
|
||||
|
||||
it('templates and previews use merged payloads', async () => {
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { uploadNPMExport, commitNPMImport, cancelNPMImport } from '../npmImport';
|
||||
|
||||
import client from '../client';
|
||||
import { uploadNPMExport, commitNPMImport, cancelNPMImport } from '../npmImport';
|
||||
|
||||
vi.mock('../client', () => ({
|
||||
default: {
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user