Support function-based customisation in reply.helmet options

[Tam]

Added support for passing a function to reply.helmet, allowing dynamic modification of Helmet options. Updated type definitions and included tests to validate this functionality. The aim is to make updating the existing options easier, without needing to overwrite the entire object (i.e. when modifying a specific CSP value).

await reply.helmet(opts => {
  opts.contentSecurityPolicy.directives['script-src'].push('nonce-123')
  return opts
})

Checklist

• run npm run test and npm run benchmark
• tests and/or benchmarks are included
• documentation is changed or added
• commit message and code follows the Developer's Certification of Origin
  and the Code of conduct

[jean-michelet]

As I'm not familiar with this plugin, I'd rather not comment on the usefulness of this feature.

[jean-michelet]

Can you plz document why this is necessary, we should have very good reasons to ignore code coverage.
I see this package has a few ignore comments without any explanation, so it's not a feedback specific to you.

[Tam]

@jean-michelet For whatever reason this condition isn't covered by the existing tests. I added the ignore as a work-around because I saw it was used elsewhere in the code (and it was the only way I could commit without --force). I've tried adding a test to cover it but was unsuccessful, so any help or advice is appreciated!

[is2ei]

FYI: I’ve opened a PR to add comments:
#292

[jean-michelet]

Instead, can you share an example that is only achievable with a callback rather than an object?
It would help users to understand why it is a helpful feature.

[Tam]

@jean-michelet I've updated the readme with a clearer example, let me know if that's better. 06d709b

[Fdawgs]

Thanks for the PR @Tam, i'm interested what your use case is for this?

[Tam]

Thanks for the PR @Tam, i'm interested what your use case is for this?

I'm adding some js tags to the twig.js templating library for a side-project and wanted to automatically add integrity hashes and nonces to the CSP header.

[climba03003]

I'm adding some js tags to the twig.js templating library for a side-project and wanted to automatically add integrity hashes and nonces to the CSP header.

Then, why not using the enableCSPNonces or helmet function generate the nonce?
You can pass the generated nonce to the template library.

https://github.com/fastify/fastify-helmet?tab=readme-ov-file#content-security-policy-nonce

[Tam]

I'm adding some js tags to the twig.js templating library for a side-project and wanted to automatically add integrity hashes and nonces to the CSP header.

Then, why not using the enableCSPNonces or helmet function generate the nonce? You can pass the generated nonce to the template library.

https://github.com/fastify/fastify-helmet?tab=readme-ov-file#content-security-policy-nonce

That would work for inline scripts, but not for external ones. For example, if I were to add a tag like this:

{% js 'https://unpkg.com/htmx.org@2.0.4' with {
    integrity: 'sha256-4gndpcgjVHnzFm3vx3UOHbzVpcGAi3eS/C5nM3aPtEc=',
    crossorigin: 'anonymous',
} %}

I'd want it to automatically add the domain and integrity hash to the CSP header. It's mainly a developer QoL thing.

[mcollina]

Can you please add a test for the type? We use tsd.

[Copilot]

Pull Request Overview

This PR adds support for passing a function to the reply.helmet() decorator, allowing users to modify existing helmet configuration options programmatically rather than replacing them entirely.

Key changes:

• Enhanced the reply.helmet() decorator to accept a function that receives current options and returns modified options
• Added comprehensive test coverage for the new function-based API
• Updated TypeScript type definitions to reflect the new signature

Reviewed Changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.

File	Description
index.js	Updated reply.helmet to handle function parameters and added c8 ignore comment for error path
types/index.d.ts	Extended helmet decorator type signature to accept function parameter
test/global.test.js	Added test case verifying function-based options work correctly
README.md	Added documentation example showing how to use function-based options

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

When opts is a function, the configuration is passed directly without creating a new object via Object.create(null). This inconsistency means the function could mutate the original configuration object. Consider passing a copy: helmetConfiguration = opts(Object.assign(Object.create(null), configuration))

Suggested change

	helmetConfiguration = opts(helmetConfiguration)
	helmetConfiguration = opts(Object.assign(Object.create(null), configuration))

[Copilot]

The example assumes opts.contentSecurityPolicy and its nested properties exist, but users may receive configuration where these are undefined. Consider adding a comment noting that this is a simplified example and proper validation should be performed in production code.