Notes about CSP decorators design.

(This summary has been written with the assistance of AI to ensure all POVs are included and phrased with as much clarity as possible.)

There have been ongoing conversations about whether to use combined or separate decorators for CSP enforcement and report_only overrides. Rob shared his perspective, which I carefully considered, and also consulted with Sarah to gather a Fellows-wide perspective. The summary of that discussion and conclusions is detailed below.

Rob pointed out that disabling CSP entirely on a view likely involves both enforced and report_only headers, so a single decorator simplifies that use case. For overriding policies, he feels that since view and template contexts usually share the same needs for both headers, a single decorator is often more practical. However, he acknowledged that the headers are separate concerns, which supports having distinct decorators in alignment with having two separated settings.

After discussing with Sarah, we considered the trade-offs between having a single csp_override decorator with boolean flags for enforced and report_only, versus separate decorators for enforced and report_only overrides.

Pros of the unified decorator:

• Fewer decorators to remember or import.
• Single decorator call can override both headers when they share the same config.

Cons/concerns:

• The default behavior considering both booleans being True means a simple call might unintentionally override both enforced and report_only policies, which could lead to subtle security or debugging issues if the user only intended to override one.
• When a user wants to override only the report_only policy (which is common for testing new policies or policy changes), they must explicitly set enforced=False to avoid overriding the enforced header, adding some cognitive overhead.
• Since enforced and report_only policies are configured independently in settings, having separate decorators better reflects this separation and reduces the chance of user error.

Other points:

We intentionally do not validate CSP directives in middleware or decorators. An invalid report_only config, like missing report-uri, won't error in Django but may cause browser issues or defeat the purpose of the report_only CSP. Similarly, using the same config for both headers can also add report_only-only directives (e.g., report-uri) to the enforced header, potentially causing problems or unexpected results.

This makes it important to keep overrides clear and explicit by using separate decorators for enforced and report_only policies, avoiding misconfiguration.

Using two decorators can still allows for simpler and safer usage in typical cases, e.g.:

@csp_override(config1)
@csp_override_report_only(config2)
def my_view(request):
    ...

even if the config is the same:

my_policy = {...}

@csp_override(my_policy)
@csp_override_report_only({**my_policy, "report-uri": "/csp-report-endpoint/"})
def my_view(request):
    ...

Because of the above, the suggestion is to split csp_override into two decorators: one for enforced and one for report_only overrides, for clarity, reduced chance of accidental overrides, and better alignment with the independent settings and typical usage patterns. The boolean flags approach is workable but has subtle usability risks.

Thanks again for your work on this! Happy to discuss further or help with refactoring if desired.

After some further though I now wonder if we should remove the _disabled variants of the decorator... people needing to disable CSP for a view would now do:

@csp_override(None)
@csp_report_only_override(None)

(any falsey value would do, empty dict, False, etc)

After some further though I now wonder if we should remove the _disabled variants of the decorator... people needing to disable CSP for a view would now do:

@csp_override(None)
@csp_report_only_override(None)

My only concern with this is that the intention is a bit less clear. Seeing @csp_disabled is pretty clear and self documenting what is intended. @csp_override(None) seems less so - it almost reads as "I'm not overriding anything". Due to that I'd vote a -0.

My only concern with this is that the intention is a bit less clear. Seeing @csp_disabled is pretty clear and self documenting what is intended. @csp_override(None) seems less so - it almost reads as "I'm not overriding anything". Due to that I'd vote a -0.

Thanks @robhudson, that's a valid point and it makes sense.

With that in mind, other option could be to make the decorator stricter and only accept dicts for the config. In that case, passing an empty dict ({}) would mean CSP is disabled, which would line up with the SECURE_CSP/SECURE_CSP_REPORT_ONLY settings default. That might make the intent clearer than allowing any falsey value, and it would avoid the somewhat ambiguous None.

With that in mind, other option could be to make the decorator stricter and only accept dicts for the config. In that case, passing an empty dict ({}) would mean CSP is disabled, which would line up with the SECURE_CSP/SECURE_CSP_REPORT_ONLY settings default. That might make the intent clearer than allowing any falsey value, and it would avoid the somewhat ambiguous None.

Yes, I agree that would help make the intention more clear if the preference is leaning towards a single decorator -- basically, override with an empty policy, meaning, no policy. 👍

Yep, I think that's really clear.