Refactoring headers

[vejja]

Outline

This module modifies the HTTP headers, most importantly the Content-Security-Policy header.
This discussion is a forum to think about a potential refactoring of the way we modify headers.

Challenges

We have 3 main challenges today

1. Headers can be defined in 2 different locations, leading to potential conflicts
2. Headers must support 2 different syntaxes
3. Headers should be modified only for certain types of assets, not all

1. About potential conflicts

Headers can be defined in 2 locations:

• in routeRules.headers: this is a standard feature of Nuxt (aka in my language, the Standard Headers)
• in routeRules.security.headers: this is a custom feature of Nuxt-Security (aka the Security Headers)

2. About syntax

The syntax is not the same:

• "Content-Security-Policy": "script-src: self;" for Nuxt (aka the HeaderName syntax)
• contentSecurityPolicy: { "script-src": ['self'] } for Nuxt-Security (aka the OptionKey syntax)

3. About asset types

Nuxt-Security modifies the headers only for HTML ressources (i.e. all *.vue pages which are rendered to the user).
It does not modify the headers for server routes (/api/...) or for static assets (all *.js scripts, all css files, images, etc.)

Current architecture

1. How we resolve the potential conflicts

A basic example of conflict is when the user defines a Content-Security-Policy in both places.
This is easy to resolve because we apply a simple principle: Nuxt Security has priority

But the potential conflicts between Nuxt headers and Nuxt-Security headers can be much more complex.
This is because routeRules are the rules for a router, which can contain wildcards and sub-routes.
So if there are conflicts for /** and conflicts for /special, the resolution of conflicts will not be the same if the request is for /foobar or for /special.
In short, because route pattern possibilities are infinite, it is not possible to resolve all conflicts in advance at build time.

The way we solve this is by letting Nuxt resolve the conflict at runtime until the last moment, i.e. when the request arrives.

This is why we use the formula { security } = getRouteRules() everywhere.

What happens under the hood are the following steps :
1- When the request is processed, Nuxt has already calculated the Standard Headers in the event.headers
2- We extract the Security Headers via { security } = getRouteRules(event)
3- We apply the principle that Nuxt Security has priority by overwriting event.headers
4- We let the Nuxt process continue with the modified event.headers

With this approach, we have correct conflict resolution for both /foobar and /special.

You should note that we rely on the fact that getRouteRules() is able to match the route for the { security } object, which is a custom Nuxt-Security addition to the router.
The reason why it works is that under the hood, the getRouteRules()method invokes the standard h3 router, which is itself provided by unjs/radix3 which is versatile enough. It works, but it is not an officially supported h3 method.

2. On the syntax differences

This is not a huge problem. We have a set of utilities in /src/utils/headers that convert one syntax to the other.

3. On the type of assets

The Nuxt-Security headers are only applied to HTML resources because we use a Nitro plugin that hooks into render:html.
If we were using a Nuxt Server Middleware plugin, it would be applied to all requests.

So what happens here is that

• If the request is to a server /api route or to a static asset (.js, .css, etc...), our Nitro plugin is not invoked. In that case, only the Standard Headers defined in routeRules are delivered to the user
• If the request is to a page, our Nitro plugin is invoked. In that case, the conflict resolution of point 1. above enters into action and the correct mix of Standard Headers and Security Headers is delivered to the user

Potential for improvement

PR #298 introduces the ability to configure headers at runtime.

The way it is implemented is by doing 2 things

• Introducing an event.context.security object
• Create a specific router instance

We end up in a situation where we have 2 unjs/radix3 router instances.

1. The standard router, that we use for conflict resolution as explained above
2. The new router, that is used only for resolving routes of headers configured at runtime

My intuition is that using the new router created by PR #298 is better than using the standard router.
A potential refactoring would be

• to stop adding a custom { security } object to the standard Nuxt router (we don't know whether this will be supported in the future)
• instead, to only use the new router instance to record the Security Headers rules
• to stop resolving conflicts via getRouteRules() in the standard Nuxt router
• instead, to solve all conflicts in the new router and record the result in the event.context.security object

Next Steps

This is basically an architecture discussion.
I would be happy to get the feedback of @huang-julien and @Baroshem on whether they think this is feasible

Cheers !

[dargmuesli]

Great explanation!

[huang-julien]

I'm cool with that.

I guess you'd probably need to state that as a big breaking change ?

Btw #300 is about moving all config to the new radix router

[vejja]

Would that necessarily be a breaking change?

[huang-julien]

I don't knwo how much users are relying on { security } = getRouteRules(event) but if we're going to refactor this, it can be considered as a breaking change

[vejja]

I don't think users should be relying on { security } = getRouteRules(event)
The security object is purely a Nuxt-Security internal implementation detail, it is not a public API.
We never documented that or advised users to use it, as we may well change this anytime

[dargmuesli]

Hmm, isn't csp#per-route-configuration documentation on the feature nuxt-security then reads in using getRouteRules(event) or am I misunderstanding something?

[Baroshem]

Thanks @vejja for a great write up.

I will take a look at it next week as I want to give you a good comments and I didn't have much time this week :(

[dargmuesli]

Another thing that comes to my mind is co-existence of header configuration via module options and via nitro plugin route rules. A Nuxt layer might set headers via module options and your project via a nitro plugin, just to give an example.

In my testing of #298 only the module options are kept, the route rules are not merged in. But maybe that's by design already?

cc @Baroshem

[huang-julien]

I don't think that's intended...

[vejja]

Sorry @dargmuesli I’m not sure I fully understand
Do you mean that if you set route rules via module options and also via runtime hook, runtime hook rules are ignored ?

[vejja]

In the implementation before PR #298, the 2 /** route rules would be merged with the principle that Security Headers have priority over Standard Headers

To be crystal clear, the following definition :

defineNuxtConfig({
  routeRules: {
    '/foo': {
      headers: {
        "Content-Security-Policy": "script-src: 'self';"
      },
      
      security: {
        headers: {
          contentSecurityPolicy: {
            "script-src": ['unsafe-inline']
            }
        }
      }
    }
  }
})

will generate a CSP policy for route /foo of script-src: 'unsafe-inline';

[dargmuesli]

Ok, and what's supposed to happen after PR #298? Imagine a Nuxt layer setting a route rule '/**' to "script-src": ['unsafe-inline'] and the Nuxt project building upon that layer having a route rule '/**' too, but with content "script-src": ['self'], both through nuxt-security.

I'd imagine the final Nuxt project to have script-src 'unsafe-inline' 'self' when accessing /, right? Or will only one of those two /** rules be applied?

[vejja]

Hmmm that's a good question and I don't know the answer TBH
Because the route rules are registered in the radix router, it all depends on the merging strategy of routeRules implemented by Nitro
I guess they probably defu the routeRules but I don't know. If that's the case though, because "script-src" is an array and defu merges arrays additively, yes you would be right it should be script-src 'unsafe-inline' 'self'

[dargmuesli]

We may need to use a route matcher instead of the current route lookup it appears 💡

[huang-julien]

Currently with the new runtime hooks, new values are overwritting the ones set within the runtimeConfig. If you want to go back to the values from the runtime config, you'd need to set the value ofthe header you want to revert to false. The merging strategy hasn't been implemented

[dargmuesli]

I'm currently thinking about the object structure of event.context.security: Currently, the headers in this object are already written in the HeaderName syntax by the nuxt-security:headers hook. This makes it hard to merge these values in following steps, e.g. when some modification can only be made once a request comes in. Think of modifications being done depending on the request's host headers or similar.

I'd thus vote to keep the OptionKey syntax for the event.context.security and move the HeaderName syntax resolution from the nuxt-security:headers to the headers middleware.

[dargmuesli]

In general, I'd vote to keep the header configuration in OptionKey syntax for as long as possible and only resolve it shortly before the response is sent.

[dargmuesli]

Also, some nitro plugins like the csp ssr nonce plugin do not work with headers set via the nuxt-security:headers right now I think as those headers live on event.context.security.headers and not security.headers.contentSecurityPolicy which they are currently sourced from.

[Baroshem]

Hey guys,

I finally had some time to take a look at this discussion.

First of all, thanks for the great comments! 🚀

I will share my thougts below but in general, I think such change can occur no earlier than for 2.0.0 release due to potential breaking changes that I prefer to avoid as much as possible (especially because we recently released a stable 1.0.0). Are you ok with that?

[huang-julien]

I makes sense to me. The fact that current implementation requires a feature flag to enable it is good as it is experimental.

However we can aim to merge the runtime hooks within the different plugins for performance optimization so we don't rewrite headers/configuration that was already set by another security plugin.

[vejja]

Hi @huang-julien
I'm making good progress on this currently, and I'm planning to include #300 as part of it.

I've got one question for you, which relates to the tests you added into tests/runtime-hooks.
The first test checks the /api/runtime-hook route, but I struggle to understand that test, because security headers are not supposed (in my mind) to be added to api routes. I would think that these headers only make sense in the context of the browser rendering an HTML page.
I might be mistaken though, can you let me know if you had a specific scenario in mind where headers would need to be added to an API route ?

BTW if you want to check the WIP implementation you can have a look at the feat/unified-runtime-context branch

[huang-julien]

Hey 👋

Tests for /api/runtime are made for only tests purpose. we can also render html within it or with the routes directory even if it's quite unconventionnal on Nuxt. The only scenario for me would be the CORS related headers
You can move it to the app if you wish.

I'll check the branch later when I have some times thank you :)

[vejja]

Ok then I will modify the test to simulate fetching dynamic configuration of headers from a server request, but the headers won't apply to the /api route anymore
I will also include an example on how to apply headers in a dynamic route that renders html