API write-auth: decide a global default-deny model for all /api/* mutating endpoints #43

Closed
opened 2026-06-27 15:43:53 +02:00 by timothy · 2 comments
Owner

Surfaced by the adversarial review of #34 (#2a). Deferred from #2a with reason.

#2a added ApiKeyAuthorizationFilter (Api:WriteKey + X-Api-Key) applied at the ChannelController class level — so all channel writes (incl. ResetPlayout) are covered. But the control is opt-in per controller, not global. So when Api:WriteKey is set, every other pre-existing mutating /api/* endpoint remains open:

  • MaintenanceController (empty_trash, clean_artwork)
  • FFmpegProfileController (create/update/delete)
  • SmartCollectionController (CRUD)
  • LibrariesController (scan, scan-show)
  • SessionController (DELETE session)
  • ScriptedScheduleController (~30 POSTs)

Decision needed: move to a default-deny global model (e.g. a global MVC filter, or [Authorize]-style convention) covering ALL /api/* mutations, with a designed exemption for ScannerController (internal guid-scoped callbacks — the scanner process does not send X-Api-Key) and any other legitimately-internal endpoints.

Why deferred from #2a: a naive global filter would break the scanner callbacks and reaches into controllers owned by later slices. Better to decide the model deliberately. As each slice (#35 Collections, #37 Playouts) retrofits its controller it will adopt the class-level filter in the meantime; this issue tracks converting to global default-deny.

Relates to #2 (tracker) and #38 (#2e standardization). Reference: docs/rest-api.md §3.5.

Surfaced by the adversarial review of #34 (#2a). **Deferred from #2a with reason.** #2a added `ApiKeyAuthorizationFilter` (`Api:WriteKey` + `X-Api-Key`) applied at the **ChannelController class level** — so all channel writes (incl. `ResetPlayout`) are covered. But the control is **opt-in per controller**, not global. So when `Api:WriteKey` is set, every *other* pre-existing mutating `/api/*` endpoint remains **open**: - `MaintenanceController` (empty_trash, clean_artwork) - `FFmpegProfileController` (create/update/delete) - `SmartCollectionController` (CRUD) - `LibrariesController` (scan, scan-show) - `SessionController` (DELETE session) - `ScriptedScheduleController` (~30 POSTs) **Decision needed:** move to a **default-deny global model** (e.g. a global MVC filter, or `[Authorize]`-style convention) covering ALL `/api/*` mutations, **with a designed exemption** for `ScannerController` (internal guid-scoped callbacks — the scanner process does not send `X-Api-Key`) and any other legitimately-internal endpoints. Why deferred from #2a: a naive global filter would break the scanner callbacks and reaches into controllers owned by later slices. Better to decide the model deliberately. As each slice (#35 Collections, #37 Playouts) retrofits its controller it will adopt the class-level filter in the meantime; this issue tracks converting to global default-deny. Relates to #2 (tracker) and #38 (#2e standardization). Reference: `docs/rest-api.md` §3.5.
Author
Owner

Starting implementation in isolated worktree /private/tmp/ersatztv-issue43 on branch feature/43-api-write-auth-default-deny.

Approach: convert write auth from opt-in controller attributes to a global MVC authorization filter for mutating /api/* requests when Api:WriteKey is configured. Reads remain open, no-key configured preserves current LAN-open behavior, and scanner callbacks under /api/scan/{scanId} remain explicitly exempt because the scanner process does not send X-Api-Key. I’ll add failing security coverage first, then implement the filter/registration cleanup.

Starting implementation in isolated worktree `/private/tmp/ersatztv-issue43` on branch `feature/43-api-write-auth-default-deny`. Approach: convert write auth from opt-in controller attributes to a global MVC authorization filter for mutating `/api/*` requests when `Api:WriteKey` is configured. Reads remain open, no-key configured preserves current LAN-open behavior, and scanner callbacks under `/api/scan/{scanId}` remain explicitly exempt because the scanner process does not send `X-Api-Key`. I’ll add failing security coverage first, then implement the filter/registration cleanup.
Author
Owner

Done

What was done: Implemented the global default-deny write-auth model for mutating /api/* endpoints. ApiKeyAuthorizationFilter is now registered globally in MVC, enforces Api:WriteKey / X-Api-Key only for mutating /api/* requests, leaves reads/non-API routes/unset-key LAN behavior open, and supports explicit exemptions. ScannerController is marked with [SkipApiKeyAuthorization] for internal scanner callbacks. Redundant per-controller [ServiceFilter(typeof(ApiKeyAuthorizationFilter))] attributes were removed and security coverage was consolidated into global filter/controller tests.

Root cause: The previous API-key control was introduced incrementally as opt-in controller attributes during REST API slices. That left any existing or future mutating /api/* controller open unless its author remembered to add the filter, and a naive global filter was deferred because scanner callbacks needed a deliberate exemption.

Files changed: ErsatzTV/Filters/ApiKeyAuthorizationFilter.cs, ErsatzTV/Filters/SkipApiKeyAuthorizationAttribute.cs, ErsatzTV/Startup.cs, API controllers under ErsatzTV/Controllers/Api/, controller/filter tests under ErsatzTV.Tests/, and docs/rest-api.md.

Verification: Red confirmed via missing SkipApiKeyAuthorizationAttribute compile failure. C# LSP diagnostics clean on changed filter/security files. Focused controller/filter tests passed: 85/85. Full local solution test passed: TZ=UTC dotnet test ErsatzTV.sln -v normal => 254/254, with only known Scriban.Signed NU1903 warnings. PR CI passed build/test and EF migration integrity; PR-only image push skipped as expected.

Deferred: CORS tightening remains the existing backlog item if write APIs are exposed beyond LAN.

Follow-up issues: None.

Docs updated: docs/rest-api.md §3.5 now documents global API-key write auth and the explicit scanner exemption.

Merged in PR #54: #54

## Done **What was done**: Implemented the global default-deny write-auth model for mutating `/api/*` endpoints. `ApiKeyAuthorizationFilter` is now registered globally in MVC, enforces `Api:WriteKey` / `X-Api-Key` only for mutating `/api/*` requests, leaves reads/non-API routes/unset-key LAN behavior open, and supports explicit exemptions. `ScannerController` is marked with `[SkipApiKeyAuthorization]` for internal scanner callbacks. Redundant per-controller `[ServiceFilter(typeof(ApiKeyAuthorizationFilter))]` attributes were removed and security coverage was consolidated into global filter/controller tests. **Root cause**: The previous API-key control was introduced incrementally as opt-in controller attributes during REST API slices. That left any existing or future mutating `/api/*` controller open unless its author remembered to add the filter, and a naive global filter was deferred because scanner callbacks needed a deliberate exemption. **Files changed**: `ErsatzTV/Filters/ApiKeyAuthorizationFilter.cs`, `ErsatzTV/Filters/SkipApiKeyAuthorizationAttribute.cs`, `ErsatzTV/Startup.cs`, API controllers under `ErsatzTV/Controllers/Api/`, controller/filter tests under `ErsatzTV.Tests/`, and `docs/rest-api.md`. **Verification**: Red confirmed via missing `SkipApiKeyAuthorizationAttribute` compile failure. C# LSP diagnostics clean on changed filter/security files. Focused controller/filter tests passed: 85/85. Full local solution test passed: `TZ=UTC dotnet test ErsatzTV.sln -v normal` => 254/254, with only known `Scriban.Signed` NU1903 warnings. PR CI passed build/test and EF migration integrity; PR-only image push skipped as expected. **Deferred**: CORS tightening remains the existing backlog item if write APIs are exposed beyond LAN. **Follow-up issues**: None. **Docs updated**: `docs/rest-api.md` §3.5 now documents global API-key write auth and the explicit scanner exemption. Merged in PR #54: https://gitea.tblindustries.be/timothy/ersatztv/pulls/54
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#43