feat(core): unified router context

[vejja]

Types of changes

• Bug fix (a non-breaking change which fixes an issue)
• New feature (a non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Description

This PR is a significant rewrite of the core engine of Nuxt Security, motivated primarily by the introduction of runtime hooks in PR #298 by @huang-julien and comments thereon by @harlan-zw.

Background

The background for this PR is further detailed in discussion #346 (Refactoring Headers) and in RFC #300 (Move out everything from readonly runtimeConfig).

Currently, Nuxt-Security accepts route-level security definitions via the routeRules option. Also, Nuxt-Security accepts runtime modification of security definitions via runtime hooks.

This has resulted in two parallel code paths, with sometimes different behaviours (e.g. in whether definitions are merged or overwritten). The historic code path used the native getRouteRules function, while the hooks code path used a custom event.context object.

This PR unifies these two code paths by moving all security definitions to the new event.context object introduced by the runtime hooks, making it the unique source of truth. Instead of using the getRouteRules function, we now use a resolveSecurityRules function everywhere.

Benefits

With this PR, we introduce several benefits to Nuxt-Security

1. All security options can now be modified via runtime hooks
   It is now possible to modify any of the Nuxt Security options, and not solely the headers : any other option such as hidePoweredBy, rateLimiter, is now taken into consideration and applied at route level.

2. Route rules are now consistently merged
   The router merging strategy is now the same irrespective of the way the security options are set (inline, global, routeRules, and runtime hooks). Previously, it was a mix of defu, defuReplaceArray, and plain overwriting - leading to confusion on how nested rules would apply (see CSP not working for specific routes? (Google Maps) #430 for instance). We now apply the defuReplaceArray strategy across the board.

3. Clear scoping of security headers to HTML pages, SWR support
   We now make a clearer distinction between the scope of Nitro plugins (modifying HTML pages and their headers) and the scope of Server middlewares (functions that apply to all routes). This avoids to overwrite headers of non-HTML assets with irrelevant options, and as a result we are able to support SWR natively.

4. Route-level support of RateLimiter
   Thanks to the ability to resolveSecurityRoutes at runtime, we are now able to support route-based definitions for the Rate Limiter. This solves the issue of getting 429 denials for routes where we want to have a higher rate limit. We also take this opportunity to solve the issue of getting 429s when pre-rendering.

New runtime hook

This PR introduces a new runtime hook : nuxt-security:routeRules, that allows to modify any security rule on any route. With this hook, the user is now able to apply any strategy for the rule (merge, overwrite, append, etc.).

The syntax for this new hook is simpler than the nuxt-security:headers syntax.

We can write

nitroApp.hooks.hook('nuxt-security:routeRules', async routeRules => {
  // any kind of modification of routeRules here, such as :
  routeRules['/my-route'] = ...
 })

Instead of

nitroApp.hooks.hook(`nuxt-security:ready, async() => {
 // define headers for one route
 // cannot modify other security options
 // modification is always by overwrite, no merging is possible
 nitroApp.hooks.callHook('nuxt-security:headers', {
   route: '/my-route'
   headers: ...
 }
})

The former nuxt-security:ready & nuxt-security:headers hooks are still supported but we are soft-depecrating them by removing them from the documentation.

Issues closed by this PR

• Closes Rate Limiter stops building a project due to tokensPerInterval #269 : Rate Limiter is now disabled when building with SSG
• Closes Rate limiting API routes doesn't work or is very inconsistent #281 : Rate Limiter now records requests at the route level
• Closes Move out everything from readonly runtimeConfig and allow hooks for user modification #300: All security options are now configurable via the new runtime hook
• Closes Mention about expected behavior of security config declared globally vs via defineRouteRules #385 : All security options are now resolved with the same merging strategy
• Closes Support for enabling middlewares for api endpoints #392 : Rate Limiter now supports any endpoint, including /api routes
• Closes Support SWR #428 : SWR is now natively supported
• Closes CSP not working for specific routes? (Google Maps) #430 : There is no need to use string syntax anymore to overwrite higher-level rules
• Closes CSP violation when directive set to false #432 : The function insertNonceInCsp now correctly handles boolean value for CSP directives

Other notes

This PR also soft-deprecates the substitution merging via string syntax feature. This is now rendered unnecessary because the defuReplaceArray strategy is applied consistently everywhere.

We are removing corresponding mentions in the documentation, which were confusing (it only applied to headers, and it only applied in the router merging step but not in the definition step). The feature still exists to maintain backwards compatibility.

Please note that some security options can only be applied globally (removeLoggers, csrf and basicAuth) because they depend on third-party modules. The TypeScript definitions have been updated to remove these 3 options from the properties that can be set at route-level.

Checklist:

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes (if not applicable, please state why)

Added tests for

• new runtime hook
• rate limiter by route

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
nuxt-security	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 25, 2024 4:01pm

[vejja]

@Baroshem @huang-julien @harlan-zw happy to get your feedback on this

[Baroshem]

Few comments but overall this is a great piece of work you did there @vejja

I have tested it and it seems that it is working correctly. After you answer or fix the comments, I think we could merge it to main and test once again there and release it as a new version :)

[vejja]

@Baroshem : do you want me to squash commits for clarity ?

[Baroshem]

No need @vejja

We can keep them as history :)

I will merge this PR in a few hours do that we can tesg once again on main and release a new version 🚀