akanealw/Charon
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

choret: enforce discord-only provider type across notifications API and UI

Browse Source 
- Added validation to reject non-discord provider types in create, update, test, and preview operations.
- Updated the notifications form to automatically normalize non-discord types to discord.
- Modified UI to display explicit messaging for deprecated and non-dispatch statuses for non-discord providers.
- Enhanced tests to cover new validation logic and UI changes for provider types.
This commit is contained in:
GitHub Actions
2026-02-21 14:28:06 +00:00
parent 718358314f
commit 9094d3b99b
17 changed files with 1221 additions and 664 deletions
Download Patch File Download Diff File Expand all files Collapse all files

728
docs/plans/current_spec.md
View File

@@ -1,384 +1,520 @@
---
post_title: "Current Spec: Governance Update — DoD GORM Scan + Gotify Token Hygiene"
post_title: "Current Spec: Discord Notify-Only Dispatch (No Legacy Fallback)"
categories:
- actions
- testing
- security
- governance
tags:
- dod
- gorm
- gotify
- documentation
- planning
summary: "Governance-only plan to explicitly enforce conditional GORM scanner execution in DoD and add policy/operational controls that prevent Gotify token exposure while preserving token validation workflows."
post_date: 2026-02-20
- discord
- notifications
- notify-rollout
- migration
- e2e
summary: "Authoritative implementation plan for Discord Notify-only dispatch with explicit retirement of legacy fallback ambiguity, deterministic migration behavior, and proof-oriented testing."
post_date: 2026-02-21
---
## Active Plan: Governance Update — DoD GORM Scan + Gotify Token Hygiene
## Active Plan: Discord Notify-Only Dispatch (No Legacy Fallback)
Date: 2026-02-20
Date: 2026-02-21
Status: Active and authoritative
Scope Type: Documentation/Governance only (no product feature refactor)
Scope Type: Product implementation plan (frontend + backend + migration + verification)
## 1) Introduction
This plan defines the implementation to satisfy the updated requirement direction:
- Do not rely on legacy fallback engine for Discord dispatch.
- Discord payloads saved in DB must be sent by Notify engine directly.
- Remove ambiguity where delivery success could still come through legacy path.
- Keep rollout scope focused on Discord-only cutover without unrelated refactors.
This plan is intentionally scoped to Discord-only dispatch/runtime behavior, fallback retirement, and auditable proof that no hidden legacy path remains.
## 2) Research Findings
### 2.1 Frontend provider-type control points (exact files)
- `frontend/src/pages/Notifications.tsx`
- Provider type is normalized to Discord (`DISCORD_PROVIDER_TYPE`) before submit/test/preview.
- Provider dropdown currently renders Discord-only option, and request payloads are forced to Discord.
- `frontend/src/api/notifications.ts`
- `withDiscordType(...)` normalizes outbound payload type to Discord.
- Interface remains `type: string`, requiring backend to remain authoritative for no-fallback invariants.
- `frontend/src/pages/__tests__/Notifications.test.tsx`
- Must verify Discord-only create/edit/test behavior and avoid implying fallback rescue semantics.
- `tests/settings/notifications.spec.ts`
- Includes coverage for Discord behavior and deprecated non-Discord rendering semantics.
### 2.2 Backend/provider type validation/default/control points (exact files)
- `backend/internal/api/handlers/notification_provider_handler.go`
- Enforces Discord-only on create/update and blocks enabling deprecated non-Discord providers.
- `backend/internal/services/notification_service.go`
- Enforces Discord-only for provider lifecycle/test and skips non-Discord dispatch.
- Contains explicit legacy-fallback-disabled sentinel/error path that must stay fail-closed.
- Includes `EnsureNotifyOnlyProviderMigration(...)` for deterministic cutover state.
- `backend/internal/services/enhanced_security_notification_service.go`
- `SendViaProviders(...)` dispatches only to Discord providers in current rollout stage.
- `dispatchToProvider(...)` still has non-Discord branches and is a key ambiguity-removal target.
- `backend/internal/models/notification_provider.go`
- `Type` comment still lists non-Discord types.
- `Engine` and URL comments still include retired legacy-notifier URL semantics.
- `backend/internal/notifications/engine.go`
- Defines a retired legacy notification engine constant.
- `backend/internal/notifications/router.go`
- Legacy engine branch remains.
- `backend/internal/notifications/feature_flags.go`
- Retired fallback flag key remains in feature-flag wiring.
- `backend/internal/api/handlers/feature_flags_handler.go`
- Still exposes a retired legacy fallback key in defaults and update path guards.
- `backend/internal/api/routes/routes.go`
- Notification services are wired via both `NotificationService` and
`EnhancedSecurityNotificationService`; migration path still references transitional behavior.
### 2.3 Exact backend/frontend files impacted by fallback removal
Backend files:
### 1) Introduction
- `backend/internal/notifications/engine.go`
- `backend/internal/notifications/router.go`
- `backend/internal/notifications/feature_flags.go`
- `backend/internal/api/handlers/feature_flags_handler.go`
- `backend/internal/services/notification_service.go`
- `backend/internal/services/enhanced_security_notification_service.go`
- `backend/internal/api/handlers/notification_provider_handler.go`
- `backend/internal/api/routes/routes.go`
- `backend/internal/models/notification_provider.go`
This plan defines a documentation-only governance update for Charon. It focuses on two outcomes:
Frontend files:
1. Confirm and enforce that local Definition of Done (DoD) explicitly requires GORM security scan execution when backend model/database-related changes occur.
2. Establish explicit policy and operational guidance to prevent Gotify token exposure while preserving secure token validation.
- `frontend/src/pages/Notifications.tsx`
- `frontend/src/api/notifications.ts`
This plan intentionally excludes application feature refactors, endpoint behavior changes, and data model changes.
### 2.4 Dependency/runtime current state (legacy notifier)
### 2) Scope and Assumptions
- `backend/go.mod`: no active legacy notifier dependency.
- `backend/go.sum`: no active legacy notifier entry found.
- Direct import/call in backend source currently not present.
- Legacy strings/constants/tests remain in runtime code paths and tests.
- Historical artifacts and cached module content may contain legacy notifier references but are not
production dependencies.
#### In Scope
### 2.5 Firefox failing specs context
- Update governance markdown under `.github/instructions/**`.
- Update operating-agent markdown under `.github/agents/**` where DoD/security verification behavior is defined.
- Update security governance docs outside `.github` only where required to keep policy alignment and operator guidance clear.
- Provide explicit wording for:
- Conditional GORM scan gate in DoD.
- Gotify token secrecy controls (no echo, no logs, no API response exposure).
- Practical hardening recommendations.
- Artifact `playwright-output/manual-dns-targeted/.last-run.json` contains 16 failed test IDs only; suite attribution must come from Playwright report/traces, not this file alone.
- Separate summary `FIREFOX_E2E_FIXES_SUMMARY.md` references prior Firefox remediation work.
- User-reported “5 failing Firefox specs” is treated as active triage input and must be
classified at execution time into in-scope vs out-of-scope suites (defined below).
#### Out of Scope
## 3) Requirements (EARS)
- Backend/frontend feature implementation.
- API contract/code changes.
- DB schema/migration changes.
- Test-suite refactors beyond documentation references.
- R1: WHEN opening notification provider create/edit UI, THE SYSTEM SHALL offer only `discord`
in provider type selection for this rollout.
- R2: WHEN create/update/test notification provider API endpoints receive a non-Discord type,
THE SYSTEM SHALL reject with deterministic validation error.
- R3: WHILE legacy non-Discord providers exist in DB, THE SYSTEM SHALL handle them per explicit
compatibility policy without enabling dispatch.
- R4: WHEN verifying runtime and dependency state, THE SYSTEM SHALL produce auditable evidence
that the retired legacy notifier is not installed, linked, or used by active runtime code paths.
- R5: IF additional services are introduced in future, THEN THE SYSTEM SHALL enable them
behind explicit validation gates and staged rollout controls.
- R6: WHEN Discord notifications are delivered successfully, THE SYSTEM SHALL provide evidence that Notify path handled dispatch and not a legacy fallback path.
- R7: IF rollback is required, THEN THE SYSTEM SHALL use explicit rollback controls without reintroducing hidden legacy fallback behavior.
#### Assumptions
## 4) Technical Specification
- Existing GORM scanner exists and is runnable (`Lint: GORM Security Scan`, `pre-commit ... gorm-security-scan`, `scripts/scan-gorm-security.sh`).
- DoD governance is currently distributed across instruction and agent files and must remain consistent.
- Gotify continues to be supported in notification docs and needs explicit secret-handling rules documented.
### 4.1 Discord-only enforcement strategy (defense in depth)
### 3) Research Findings
#### Layer A: UI/input restriction
#### Current DoD/GORM Position
- `frontend/src/pages/Notifications.tsx`
- Replace provider type dropdown options with a single option: `discord`.
- Keep visible label semantics intact for accessibility.
- Prevent stale-form values from preserving non-Discord types in edit mode.
- `testing.instructions.md` already includes a GORM Security Validation section and states scanner pass as DoD requirement.
- `copilot-instructions.md` DoD section is comprehensive but does not currently elevate the GORM scan as an explicit conditional DoD step tied to backend model/database touchpoints.
- Agent-level DoD ownership exists in `Management.agent.md`; however, explicit conditional GORM gate language is incomplete and should be made unambiguous.
#### Layer B: Frontend request contract hardening
#### Current Gotify/Token Guidance Position
- `frontend/src/api/notifications.ts`
- Frontend request contract SHALL submit `type` as `discord` only; client must reject or normalize any stale non-discord value before submit.
- Notification/security documentation includes Gotify payload examples but does not centrally enforce a strict token non-exposure policy with explicit “never echo/log/return” phrasing.
- Security instruction files contain generic secret guidance but lack Gotify-specific operational controls and validation-safe masking patterns.
#### Layer C: API handler validation (authoritative gate)
#### Governance Surfaces Identified for Update
- `backend/internal/api/handlers/notification_provider_handler.go`
- Enforce `req.Type == "discord"` for all create/update paths (not only security-event cases).
- Return stable error code/message for non-Discord type attempts.
##### Primary (`.github/instructions/**`)
#### Layer D: Service-layer invariant
1. `.github/instructions/copilot-instructions.md`
2. `.github/instructions/testing.instructions.md`
3. `.github/instructions/security-and-owasp.instructions.md`
- `backend/internal/services/notification_service.go`
- Add service-level type guard for create/update/test/send paths to reject non-Discord.
- Keep this guard even if handler validation exists (defense in depth).
##### Primary (`.github/agents/**`)
#### Layer E: Dispatch/runtime invariant
4. `.github/agents/Management.agent.md`
5. `.github/agents/Backend_Dev.agent.md`
6. `.github/agents/QA_Security.agent.md`
- `backend/internal/services/enhanced_security_notification_service.go`
- Maintain dispatch as Discord-only.
- Remove non-Discord dispatch branches from active runtime logic for this phase.
##### Additional governance docs required for policy coherence
### 4.2 Feature-flag policy change for legacy fallback
7. `SECURITY.md`
8. `docs/security.md`
9. `docs/features/notifications.md`
Policy for `feature.notifications.legacy.fallback_enabled`:
### 4) Requirements (EARS)
- Deprecate now.
- Force false in reads and writes.
- Immutable false: never true at runtime.
- Reject `true` update attempts with deterministic API error.
- Keep compatibility aliases read-only and forced false during transition.
- Remove `feature.notifications.legacy.fallback_enabled` from all public/default flag responses in PR-3 of this plan, and remove all retired env aliases in the same PR. No compatibility-window extension is allowed without a new approved spec revision.
- R1: WHEN a change touches `backend/internal/models/**` or backend database interaction paths, THE SYSTEM SHALL require execution of the GORM security scanner as a local DoD gate before task completion.
- R2: IF the GORM scanner reports CRITICAL or HIGH findings, THEN THE SYSTEM SHALL require remediation before DoD can be considered complete.
- R3: WHEN documenting or operating Gotify provider configuration, THE SYSTEM SHALL prohibit token echoing, token logging, and token inclusion in API responses.
- R4: IF token validation is needed for connectivity or health checks, THEN THE SYSTEM SHALL validate tokens without revealing raw token values and SHALL use masking/redaction in all human-visible outputs.
- R5: WHILE governance documentation is updated, THE SYSTEM SHALL keep language consistent across instruction files, agent files, and operator-facing security docs.
Migration implications:
### 5) Technical Specification (Documentation Contract)
- Existing settings row for legacy fallback is normalized to false if present.
- Transition period allows key visibility as false-only for compatibility.
- Final state keeps this key out of runtime dispatch decisions; there is no fallback runtime path.
This is a policy contract update, not an API/DB contract change.
Legacy fallback control surface policy: any API write attempting to set legacy fallback true SHALL return `400` with code `LEGACY_FALLBACK_REMOVED`; any legacy fallback read endpoint/field retained temporarily SHALL return hard-false only and SHALL be removed in PR-3. No hidden route or config path may alter dispatch away from Notify, and Notify failures SHALL NOT reroute to a fallback engine.
#### 5.1 Policy Contract: Conditional GORM Scan Gate
### 4.3 Runtime dispatch contract (Discord-only Notify path)
Define a single, repeated clause across governance docs:
Contract:
- Trigger: backend model/database-related changes.
- Required actions:
- Run scanner via one approved command path.
- Treat scanner as DoD process-blocking gate even when automation stage is manual (soft launch).
- Use `--check` mode for gate decisions and pass/fail outcomes.
- Block completion on unresolved CRITICAL/HIGH findings.
- Discord dispatch source of truth is Notify engine path (`notify_v1`) only.
- `NotificationService.SendExternal(...)` and `EnhancedSecurityNotificationService.SendViaProviders(...)` must fail closed for non-Discord delivery attempts.
- No implicit retry/reroute to legacy engine on Notify failure.
- Any successful Discord delivery during rollout must be attributable to Notify path execution.
Approved command references remain:
#### Layer F: Optional DB invariant (recommended)
- `Lint: GORM Security Scan` (must execute scanner in check/gating mode)
- `pre-commit run --hook-stage manual gorm-security-scan --all-files` (gating decision maps to check semantics)
- `./scripts/scan-gorm-security.sh --check` (canonical gate command)
- Add migration with DB-level check constraint for notification provider type to `discord`
for newly created/updated rows in this rollout.
- If DB constraint is deferred, service/API guards remain mandatory.
#### 5.1.1 Conditional Trigger Matrix (Include/Exclude)
### 4.4 Data migration and compatibility policy for existing non-Discord providers
| Change Type | Trigger GORM Gate? | Rule |
| --- | --- | --- |
| `backend/internal/models/**` | Yes | Include |
| Backend services/repositories with GORM query logic | Yes | Include |
| DB migrations/seeding that change persistence behavior | Yes | Include |
| Docs-only changes (`**/*.md`, governance docs) | No | Exclude |
| Frontend-only changes (`frontend/**`) | No | Exclude |
Policy decision for this rollout: **Deprecate + read-only visibility + non-dispatch**.
Gate decision rule:
- Existing non-Discord rows are preserved for audit/history but cannot be newly created
or converted back to active dispatch in this phase.
- Compatibility behavior:
- `enabled` forced false for non-Discord providers during migration reconciliation.
- `migration_state` remains failed/deprecated for non-supported providers.
- UI list behavior: render non-Discord rows as deprecated read-only rows with a clear non-dispatch badge.
- API contract: non-Discord existing rows are always non-dispatch, non-enable, deletable, and return deterministic validation error on enable/type mutation attempts.
- Explicitly block enable and type mutation attempts for non-Discord rows via API with deterministic validation errors.
- Allow deletion of deprecated rows.
- IF any Include row matches, THEN scanner execution in check mode is mandatory DoD gate.
- IF only Exclude rows match, THEN GORM gate is not required for that change set.
Migration safety requirements:
#### 5.2 Policy Contract: Gotify Token Non-Exposure
- Migration SHALL be idempotent.
- Migration SHALL execute within an explicit transaction boundary.
- Migration SHALL require a pre-migration backup before mutating provider rows.
- Migration SHALL define and document a rollback procedure.
- Migration SHALL persist audit log fields for every mutated provider row (including provider identifier, previous values, new values, mutation timestamp, and operation identifier).
Define explicit non-negotiables:
Migration implementation candidates:
- Never print token to terminal output.
- Never write token to application logs, debug logs, test output, screenshots, or reports.
- Never include token in API response bodies, errors, or serialized DTOs.
- Never expose tokenized endpoint query strings (for example `...?token=...`) in docs, diagnostics, examples, or logs.
- Always redact URL query parameters in diagnostics/examples/log output before display or storage.
- Validation operations must be non-revealing:
- Use token length/prefix-independent masking in UX and diagnostics.
- Store and process token as secret only.
- Return generic validation outcomes (`valid`/`invalid` + reason category without token value).
- `backend/internal/services/notification_service.go` (`EnsureNotifyOnlyProviderMigration`)
- `backend/internal/services/enhanced_security_notification_service.go`
- new migration file under backend migration path if schema/data migration is introduced.
#### 5.3 Cross-Document Precedence and Canonical Language
### 4.5 Legacy notifier retirement/removal scope
To prevent policy drift, define precedence and reconciliation behavior:
Targets to remove from active runtime/config surface:
1. Canonical governance source: `.github/instructions/testing.instructions.md` and `.github/instructions/security-and-owasp.instructions.md`
2. Agent execution source: `.github/agents/**`
3. Operator-facing/security guidance: `SECURITY.md`, `docs/security.md`, `docs/features/notifications.md`
- `backend/internal/notifications/engine.go` legacy engine constant
- `backend/internal/notifications/router.go` legacy engine branch
- `backend/internal/notifications/feature_flags.go` legacy flag constant
- `backend/internal/api/handlers/feature_flags_handler.go` retired legacy flag exposure
- `backend/internal/models/notification_provider.go` retired legacy notifier comments/engine semantics
- `backend/internal/services/notification_service.go` legacy naming/comments/hooks
- `backend/internal/services/enhanced_security_notification_service.go` non-Discord dispatch branches in `dispatchToProvider`
- `frontend/src/pages/Notifications.tsx` and `frontend/src/api/notifications.ts` to keep Discord-only UX/request contract aligned with backend fallback retirement
Reconciliation behavior:
Out of scope for blocking completion:
- IF lower-precedence text conflicts with higher-precedence canonical language, THEN lower-precedence text must be updated to match canonical wording in the same PR.
- Canonical terms must be reused verbatim for gate semantics:
- “DoD process-blocking even in manual soft launch”
- “check mode (`--check`) decides pass/fail gate”
- “no tokenized URL/query exposure; redact query parameters in all diagnostics/examples/logs”
- Archived docs/history artifacts under `docs/plans/archive/**` and similar archive/report folders.
#### 5.4 Operational Hardening Recommendations
## 5) Dependency and Runtime Audit Plan (verify Discord-only runtime)
Document practical recommendations:
Run and record all commands in implementation evidence.
- Use secret storage source (env var or secret manager), not plaintext docs/snippets.
- Apply structured log redaction for keys containing `token`, `apikey`, `authorization`.
- Use one-way visibility in UI forms (write-only fields, masked placeholders).
- Rotate Gotify tokens on suspected exposure.
- Validate over HTTPS only and avoid proxy/debug middleware that logs headers/bodies with secrets.
Task-aligned proof gates (mandatory):
### 6) Exact Files and Sections to Change + Precise Wording Recommendations
- Run task `Security: Verify SBOM` and capture output evidence.
- Run task `Security: Scan Docker Image (Local)` and capture output evidence.
- Store reproducibility evidence under `test-results/notify-rollout-audit/` (task outputs, command transcripts, and generated reports).
#### 6.1 `.github/instructions/copilot-instructions.md`
### 5.1 Dependency manifests
Section: `## ✅ Task Completion Protocol (Definition of Done)`
- `cd /projects/Charon/backend && go mod graph | grep -i "legacy_shoutrrr|feature.notifications.legacy.fallback_enabled|EngineLegacy|legacySendFunc|shoutrrr" || true`
- `grep -i "legacy_shoutrrr|feature.notifications.legacy.fallback_enabled|EngineLegacy|legacySendFunc|shoutrrr" /projects/Charon/backend/go.mod /projects/Charon/backend/go.sum || true`
- `grep -i "legacy_shoutrrr|feature.notifications.legacy.fallback_enabled|EngineLegacy|legacySendFunc|shoutrrr" /projects/Charon/package-lock.json /projects/Charon/frontend/package-lock.json 2>/dev/null || true`
Recommended insertion (new dedicated step after security scans or adjacent to testing gates):
### 5.2 Source/runtime references (non-archive)
- **GORM Security Scan (Conditional, BLOCKING)**:
- Trigger this step when changes include backend models or database interaction logic (for example: `backend/internal/models/**`, GORM query/service layers, migrations).
- Run one of:
- `Lint: GORM Security Scan`
- `pre-commit run --hook-stage manual gorm-security-scan --all-files`
- `./scripts/scan-gorm-security.sh --check`
- DoD is blocked until scanner reports zero CRITICAL/HIGH findings.
- `grep -RIn --exclude-dir=.git --exclude-dir=.cache --exclude-dir=docs --exclude-dir=playwright-output --exclude-dir=test-results "legacy_shoutrrr|feature.notifications.legacy.fallback_enabled|EngineLegacy|legacySendFunc|shoutrrr" /projects/Charon/backend /projects/Charon/frontend || true`
#### 6.2 `.github/instructions/testing.instructions.md`
### 5.3 Built artifact/container runtime checks
Section: `## 4. GORM Security Validation (Manual Stage)`
- Build image: `docker build -t charon:discord-only-audit /projects/Charon`
- Module metadata in binary:
- `docker run --rm charon:discord-only-audit sh -lc 'go version -m /app/charon 2>/dev/null | grep -i "legacy_shoutrrr|feature.notifications.legacy.fallback_enabled|EngineLegacy|legacySendFunc|shoutrrr" || true'`
- Runtime filesystem/strings scan:
- `docker run --rm charon:discord-only-audit sh -lc 'find /app /usr/local/bin -maxdepth 4 -type f | xargs grep -Iin "legacy_shoutrrr|feature.notifications.legacy.fallback_enabled|EngineLegacy|legacySendFunc|shoutrrr" 2>/dev/null || true'`
Recommended wording tighten (replace opening requirement sentence):
### 5.4 Documentation references (active docs only)
- **Requirement:** For any change that touches backend models or database-related logic, the GORM Security Scanner is a mandatory local DoD gate and must pass with zero CRITICAL/HIGH findings.
- `grep -RIn "legacy_shoutrrr|feature.notifications.legacy.fallback_enabled|EngineLegacy|legacySendFunc|shoutrrr" /projects/Charon/README.md /projects/Charon/ARCHITECTURE.md /projects/Charon/docs/features /projects/Charon/docs/security* || true`
Policy-vs-automation reconciliation clause (explicitly add under manual stage text):
Audit pass criteria:
- “Manual stage” describes execution mechanism only; policy enforcement remains process-blocking for DoD. Gate decisions must use check semantics (`./scripts/scan-gorm-security.sh --check` or equivalent task wiring).
- No active dependency references.
- No active runtime/path references.
- No active user-facing docs claiming retired multi-service notifier behavior for this rollout.
Recommended addition under “When to Run”:
## 6) Implementation Plan (phased)
- **Mandatory Trigger Paths:**
- `backend/internal/models/**`
- Database interaction/services using GORM queries
- Migration/seeding logic affecting model persistence behavior
- **Explicit Exclusions:**
- Docs-only changes
- Frontend-only changes
### Phase 1: Docker E2E rebuild decision and environment prep
#### 6.3 `.github/instructions/security-and-owasp.instructions.md`
- Apply repo testing-rule decision for E2E container rebuild based on changed paths.
- Rebuild/start E2E environment when required before any test execution.
Section: add new subsection under “General Guidelines”:
### Phase 2: E2E first and failing-spec triage baseline
- **Gotify Token Protection (Explicit):**
- Treat Gotify application tokens as secrets.
- Do not echo tokens in CLI output.
- Do not log tokens (application logs, debug logs, test logs).
- Do not return tokens in API responses or error payloads.
- For token validation, return only non-sensitive status and redact/mask any token-derived diagnostics.
- Capture exact Firefox failures for current branch:
- `cd /projects/Charon && npx playwright test --project=firefox`
- Classify failing specs:
- **In-scope**: notification provider tests (`tests/settings/notifications.spec.ts` and related).
- **Out-of-scope**: manual DNS provider suites unless directly regressed by this change.
- If user-reported 5 failing specs are not notifications, create/attach separate tracking item and
do not block Discord-only implementation on unrelated suite failures.
#### 6.4 `.github/agents/Management.agent.md`
### Phase 3: Local Patch Report preflight (mandatory before unit/coverage)
Section: `## DEFINITION OF DONE ##`
- Run local patch coverage preflight and generate required artifacts:
- `test-results/local-patch-report.md`
- `test-results/local-patch-report.json`
Recommended insertion as explicit checklist item:
### Phase 4: Backend hard gate (authoritative)
- **GORM Security Scan (Conditional Gate):**
- If implementation touched backend models or database-interaction paths, confirm `QA_Security` (or responsible subagent) ran the GORM scanner and resolved all CRITICAL/HIGH findings before accepting completion.
- Implement Discord-only validation in API handlers and service layer.
- Remove/retire active legacy engine and flag exposure from runtime path.
- Apply migration policy for existing non-Discord rows.
#### 6.5 `.github/agents/Backend_Dev.agent.md`
### Phase 5: Conditional GORM security check gate
Section: `3. **Verification (Definition of Done)**`
- Run GORM security scanner in check mode when backend model/database trigger paths are modified.
- Gate completion on zero CRITICAL/HIGH findings for triggered changes.
Recommended insertion:
### Phase 6: Frontend Discord-only UX
- **Conditional GORM Gate:** If task changes include model/database-related files or GORM query logic, run `pre-commit run --hook-stage manual gorm-security-scan --all-files` (or `./scripts/scan-gorm-security.sh --check`) and treat CRITICAL/HIGH findings as blocking.
- Restrict dropdown/options to Discord only.
- Align frontend type contract and submission behavior.
- Ensure edit/create forms cannot persist stale non-Discord values.
#### 6.6 `.github/agents/QA_Security.agent.md`
### Phase 7: Legacy notifier retirement cleanup + audit evidence
Sections: `<workflow>` Step 4 (Security Scanning) and reporting expectations
- Remove active runtime legacy references listed in Section 4.5.
- Execute dependency/runtime/doc audit commands in Section 5 and save evidence.
Recommended insertion:
### Phase 8: Validation and release readiness
- Add explicit conditional check:
- When backend model/database-related changes are in scope, run GORM scanner and report pass/fail as DoD gate.
- Add Gotify token review check:
- Verify no token appears in logs, test artifacts, screenshots, API examples, report output, or tokenized URL query strings.
- Verify URL query parameters are redacted in diagnostics/examples/log artifacts.
- Run validation sequence in required order (Section 7).
- Confirm rollout note: additional providers remain disabled pending per-provider validation PRs.
#### 6.7 `SECURITY.md`
## 7) Targeted Testing Strategy
Section candidate: under “Security Best Practices” or “Notification/Webhook Security” area
Mandatory repo QA/test order for this plan:
Recommended addition:
1. Docker E2E rebuild decision and required rebuild/start.
2. E2E first (Firefox baseline + targeted notification suite).
3. Local Patch Report preflight artifact generation.
4. Conditional GORM security check gate (`--check` semantics when trigger paths change).
5. CodeQL CI-aligned scans (Go and JS).
6. Coverage gates (backend/frontend coverage thresholds and patch coverage review).
7. Frontend type-check and backend/frontend build verification.
- **Gotify Token Hygiene:**
- Gotify tokens are secrets and must never be echoed, logged, or returned by API responses.
- Validation endpoints and troubleshooting guidance must use masked outputs only.
- Rotate token immediately if exposure is suspected.
### 7.1 Backend tests (in scope)
#### 6.8 `docs/security.md`
Section candidate: existing “Security Notifications” / “Gotify JSON Payload Example” area
Recommended addition:
- Add operational note block:
- “Use write-only token input. Do not paste raw tokens into logs, screenshots, tickets, or chat.”
- “Validation should confirm connectivity without exposing token value.”
#### 6.9 `docs/features/notifications.md`
Section candidate: “Gotify Webhooks” / setup + troubleshooting sections
Recommended addition:
- Add concise “Token Safety” subsection:
- Never expose token in templates, payload examples, or troubleshooting snippets.
- Use masked token representation in examples (e.g., `gtf_********`).
- Prefer token rotation and re-test when compromise is suspected.
### 7) Implementation Plan (Phased)
#### Phase 1: Governance Baseline Diff (Documentation Research Validation)
- Validate each target file and section exists.
- Map exact insertion points.
- Confirm no overlap with archived docs to avoid scope creep.
Complexity: Low
#### Phase 2: DoD Enforcement Text Updates
- Apply conditional GORM scan language to instruction + agent DoD surfaces.
- Ensure wording consistency between `.github/instructions/**` and `.github/agents/**`.
Complexity: Medium
#### Phase 3: Gotify Token Exposure Policy Updates
- Add explicit no echo/no log/no API exposure policy text.
- Add practical validation-safe and hardening guidance.
Complexity: Medium
#### Phase 4: Governance Consistency Pass
- Verify terminology consistency:
- “conditional gate”, “CRITICAL/HIGH blocking”, “masked/redacted output”.
- Check that all cross-doc references remain valid.
Complexity: Low
#### Phase 5: Validation and Handoff
- Perform markdown lint/readability pass.
- Confirm plan scope is governance-only (no implementation drift).
- Prepare for Supervisor review.
Complexity: Low
### 8) Acceptance Criteria
1. `docs/plans/current_spec.md` is fully replaced with this governance-only plan.
2. Plan lists exact target files under `.github/instructions/**` and `.github/agents/**` plus required additional governance docs.
3. Plan includes explicit, precise wording recommendations per file/section.
4. Plan defines conditional DoD enforcement for GORM scan tied to backend model/database-related changes.
5. Plan defines explicit Gotify token non-exposure rules (no echo, no logging, no API response exposure) and validation-safe behavior.
6. Plan includes practical hardening recommendations.
7. Plan includes PR slicing strategy with explicit single-PR decision rationale.
8. Plan excludes code-feature refactors and remains tightly scoped to governance/documentation updates.
9. Plan explicitly defines policy-vs-automation behavior: manual scanner stage does not weaken DoD gate enforcement; check mode semantics are mandatory for gate decisions.
10. Plan includes include/exclude matrix for conditional GORM scanner triggering.
11. Plan includes explicit reconciliation edits for `testing.instructions` manual-soft-launch wording and `QA_Security.agent.md` Gotify token artifact checks.
### 9) PR Slicing Strategy
Decision: **Single PR**
#### Rationale
- Scope is text-only governance alignment across related markdown files.
- Changes are logically cohesive (DoD gate clarity + token secrecy policy).
- Splitting would increase review overhead and risk inconsistent policy wording.
#### Single-PR Scope
- All files in Section 6.
- No code changes.
- One validation pass for consistency.
#### Validation Gates (within the PR)
- Markdown renders cleanly.
- Wording consistency across instruction/agent/operator docs.
- No contradiction between DoD policies.
#### Rollback/Contingency
- If wording introduces confusion, rollback via single revert commit of doc-only changes.
- If partial disagreement occurs, retain DoD gate updates and isolate Gotify wording revisions in follow-up doc PR.
### 10) Risks and Mitigations
- **Risk 1: Policy drift between instruction and agent docs**
Mitigation: Use shared wording patterns and perform explicit consistency pass in Phase 4.
- **Risk 2: Overly broad wording accidentally implies code changes**
Mitigation: Keep language explicitly “documentation governance only” and avoid implementation directives beyond policy.
- **Risk 3: Sensitive token examples accidentally remain in docs**
Mitigation: Add explicit masked-example rule and require post-edit grep check for token-like literals.
- **Risk 4: Reviewer ambiguity on conditional trigger**
Mitigation: Define concrete trigger paths (`backend/internal/models/**`, GORM DB logic, migrations).
### 11) Supervisor Handoff Notes
This plan is ready for Supervisor review as a governance-only documentation update. Review focus should verify:
- Clarity of conditional DoD gate for GORM scanner.
- Sufficiency and practicality of Gotify token non-exposure policy, including token-in-URL query redaction requirements.
- Cross-file wording consistency and absence of scope creep.
- `backend/internal/api/handlers/notification_provider_blocker3_test.go`
- Expand from security-event-only gating to global Discord-only gating.
- `backend/internal/services/notification_service_test.go`
- Ensure non-Discord create/update/test/send rejection.
- `backend/internal/notifications/router_test.go`
- Prove legacy fallback decision remains disabled and cannot be toggled into active use.
- `backend/internal/services/notification_service_discord_only_test.go`
- Prove Discord-only dispatch behavior and no successful fallback path.
- `backend/internal/services/security_notification_service_test.go`
- Prove security notifications route through Discord-only provider dispatch in rollout mode.
- Add/adjust tests for migration policy behavior on existing non-Discord rows.
### 7.1.1 Notify-vs-fallback evidence points (required)
- Unit proof SHALL assert legacy dispatch hook call-count is exactly 0 for all Discord-success and Discord-failure scenarios.
- Unit/integration proof SHALL assert Notify dispatch hook/request path is called for Discord deliveries (including `Content-Type: application/json` and deterministic provider-type guard behavior).
- Negative proof SHALL assert non-Discord create/update/test attempts fail with stable error codes and cannot produce a successful delivery event.
- CI gate SHALL fail if any test demonstrates delivery success through a legacy fallback path.
### 7.2 Frontend unit tests (in scope)
- `frontend/src/pages/__tests__/Notifications.test.tsx`
- Assert only Discord option exists in provider-type select.
- Remove/adjust non-Discord create assumptions.
### 7.3 E2E tests (in scope)
- `tests/settings/notifications.spec.ts`
- Keep Discord create/edit/test flows.
- Replace or retire non-Discord CRUD expectations for this phase.
### 7.4 Firefox failing specs handling (required context)
- If the current failing 5 specs are notification-related, they are in scope and must be fixed
within this PR.
- If they are unrelated (for example manual-dns-provider failures), track separately and avoid
scope creep; do not mark as fixed under this provider-type change.
### 7.5 Suggested verification command set
- `cd /projects/Charon && npx playwright test --project=firefox tests/settings/notifications.spec.ts`
- `cd /projects/Charon && npx playwright test --project=firefox --grep "Notification Providers"`
- `cd /projects/Charon && bash scripts/local-patch-report.sh`
- `cd /projects/Charon && ./scripts/scan-gorm-security.sh --check` (conditional on trigger paths)
- `cd /projects/Charon && pre-commit run codeql-go-scan --all-files`
- `cd /projects/Charon && pre-commit run codeql-js-scan --all-files`
- `cd /projects/Charon && go test ./backend/internal/api/handlers -run Blocker3 -v`
- `cd /projects/Charon && go test ./backend/internal/services -run Notification -v`
- `cd /projects/Charon && scripts/go-test-coverage.sh`
- `cd /projects/Charon/frontend && npm test -- Notifications`
- `cd /projects/Charon && scripts/frontend-test-coverage.sh`
- `cd /projects/Charon/frontend && npm run type-check && npm run build`
- `cd /projects/Charon/backend && go build ./...`
## 8) Review of `.gitignore`, `.dockerignore`, `codecov.yml`, `Dockerfile`
### Findings and required updates decision
- `.gitignore`
- No mandatory change required for feature behavior.
- Optional: ensure any new audit evidence artifacts (if added) are either committed intentionally
or ignored consistently.
- `.dockerignore`
- No mandatory change required for Discord-only behavior.
- If adding migration/audit helper scripts needed at build time, ensure they are not excluded.
- `codecov.yml`
- No mandatory change required.
- If new test files are added, verify they are not accidentally ignored by broad patterns.
- `Dockerfile`
- No direct package-level retired notifier dependency is declared.
- No mandatory Dockerfile change for Discord-only behavior unless runtime audit shows residual
retired notifier-linked binaries or references.
## 9) PR Slicing Strategy
Decision: **Multiple PRs (3 slices)** for safer rollout and easier rollback.
### PR-1: Backend guardrails + migration policy
- Scope:
- API/service Discord-only validation.
- Existing non-Discord compatibility policy implementation.
- Legacy flag/engine runtime retirement in backend.
- Primary files:
- `backend/internal/api/handlers/notification_provider_handler.go`
- `backend/internal/services/notification_service.go`
- `backend/internal/services/enhanced_security_notification_service.go`
- `backend/internal/notifications/engine.go`
- `backend/internal/notifications/router.go`
- `backend/internal/notifications/feature_flags.go`
- `backend/internal/api/handlers/feature_flags_handler.go`
- `backend/internal/models/notification_provider.go`
- Gate:
- Backend tests pass, API rejects non-Discord, migration behavior verified.
- Rollback:
- Revert PR-1 if existing-provider compatibility regresses.
- Do not reintroduce fallback by setting legacy fallback flag true or restoring legacy dispatch routing as a hotfix.
### PR-2: Frontend Discord-only UX and tests
- Scope:
- Dropdown/UI restriction to Discord only.
- Frontend test updates for new provider-type policy.
- Primary files:
- `frontend/src/pages/Notifications.tsx`
- `frontend/src/api/notifications.ts`
- `frontend/src/pages/__tests__/Notifications.test.tsx`
- `tests/settings/notifications.spec.ts`
- Gate:
- Dependency: PR-2 entry is blocked until PR-1 is merged.
- Firefox notifications E2E targeted suite passes.
- Exit: frontend request contract submits `type=discord` only and backend rejects non-Discord mutations.
- Rollback:
- Revert PR-2 without reverting backend safeguards.
- No rollback action may re-enable hidden fallback behavior.
### PR-3: Legacy notifier retirement evidence + docs alignment
- Scope:
- Execute audit commands, capture evidence, update active docs if needed.
- Primary files:
- `README.md`, `ARCHITECTURE.md`, relevant `docs/features/**` and `docs/security*` files (only if active references remain).
- Gate:
- Dependency: PR-3 entry is blocked until PR-2 is merged.
- Entry blocker: runtime/dependency audit must pass before PR-3 can proceed.
- Dependency/runtime/doc audit pass criteria met.
- Exit: docs must reflect final backend/frontend state after PR-1 and PR-2 behavior.
- Rollback:
- Revert docs-only evidence changes without impacting runtime behavior.
- Preserve explicit no-fallback runtime guarantees from earlier slices.
## 10) Rollback Strategy (No Hidden Fallback Ambiguity)
Allowed rollback mechanisms:
1. Revert entire rollout slice(s) to previous known-good commit/tag.
2. Pause notifications by disabling delivery globally while keeping legacy fallback permanently disabled (`feature.notifications.legacy.fallback_enabled=false`, immutable). Rollback SHALL revert to a prior release tag/DB snapshot only; it SHALL NOT re-enable or simulate legacy fallback.
3. Restore DB snapshot if migration state must be reverted.
Disallowed rollback mechanisms:
- Re-enable `feature.notifications.legacy.fallback_enabled` for runtime dispatch.
- Reintroduce runtime `EngineLegacy` or implicit fallback retry paths.
- Apply emergency patches that create dual-path ambiguity for Discord success attribution.
## 11) Risks and Mitigations
- Risk: Existing non-Discord providers silently break user expectations.
- Mitigation: explicit deprecated/read-only policy and clear API errors.
- Risk: Hidden runtime legacy paths remain while UI appears Discord-only.
- Mitigation: backend-first enforcement and runtime audit commands.
- Risk: Scope creep from unrelated Firefox failures.
- Mitigation: strict in-scope/out-of-scope classification in Phase 1.
- Risk: Future provider rollout pressure bypasses validation discipline.
- Mitigation: staged enablement policy with per-provider validation gate.
## 12) Acceptance Criteria
1. Provider type dropdown in notifications UI exposes only Discord.
2. API create/update/test rejects any non-Discord provider type with deterministic error.
3. Service/runtime dispatch is Discord-only for this rollout and attributable to Notify path.
4. Existing non-Discord DB rows follow explicit compatibility policy (deprecated read-only and non-dispatch).
5. Retired notifier references are absent from active dependency manifests (`go.mod`, `go.sum`, package lock files).
6. Runtime audit confirms no active retired-notifier install/link/reference in executable/runtime paths.
7. Active docs no longer claim multi-service notifier behavior for the current rollout.
8. Firefox failing-spec triage clearly distinguishes in-scope notification failures from separately tracked suites.
9. `.gitignore`, `.dockerignore`, `codecov.yml`, and `Dockerfile` are reviewed and updated only if required by actual implementation deltas.
10. Additional provider services remain disabled pending one-by-one validated rollout PRs.
11. Legacy fallback feature-flag behavior is force-false and non-revivable through standard API operations.
12. Rollback procedures preserve no-fallback ambiguity constraints.
## 13) Handoff to Supervisor
This spec is ready for Supervisor review and implementation assignment.
Review focus:
- Verify defense-in-depth layering is complete (UI + API + service + runtime).
- Confirm migration policy is explicit and reversible.
- Confirm audit command set is sufficient to prove legacy notifier retirement.
- Confirm PR slicing minimizes risk and isolates rollback paths.