feat: Add middleware pattern with native per-request nonce support

[Enalmada]

Summary

This PR introduces a major update (v0.2) that adds native middleware support for TanStack Start with per-request nonce generation. This replaces the previous handler wrapper pattern with a more integrated and secure approach.

Key Changes:

• New createCspMiddleware() - Middleware factory for TanStack Start with per-request nonce generation
• New createNonceGetter() - Isomorphic nonce retrieval (works on server and client)
• New generateNonce() - Cryptographically secure random nonce generator
• New buildCspHeader() - Low-level CSP header building utility
• CSP Level 3 support with automatic granular directive copying (-elem, -attr)
• Strict nonce-based CSP for scripts (no 'unsafe-inline' in production)
• Integration with TanStack router's native ssr.nonce option
• Deprecated createSecureHandler (v0.1 API) - kept for backward compatibility

Security Improvements:

• Per-request nonce generation (previously static at startup)
• No 'unsafe-inline' fallback for scripts in production
• Support for 'strict-dynamic' CSP directive
• Automatic nonce application to all TanStack framework scripts

Breaking Changes:

• This is a major version because it introduces a new peer dependency: @tanstack/start-storage-context >= 1.0.0
• The recommended API has changed from handler wrapper to middleware pattern

Test plan

• All existing tests pass
• CSP headers correctly built with nonce
• Middleware integrates with TanStack Start context
• Nonce getter works isomorphically (server + client)
• Backward compatibility maintained for v0.1 API
• Documentation updated with migration guide

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 7a5cdaf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@enalmada/start-secure	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[gemini-code-assist]

Summary of Changes

Hello @Enalmada, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a significant update to the security header management library for TanStack Start applications. It refactors the core mechanism from a handler wrapper to a native middleware pattern, primarily to enable robust, per-request Content Security Policy (CSP) nonce generation. This change dramatically improves the application's security posture by ensuring that scripts are executed only if explicitly authorized by a unique, cryptographically secure token, thereby mitigating common cross-site scripting (XSS) vulnerabilities. The update also streamlines integration with the TanStack Router's built-in nonce capabilities and provides a clear migration path for existing users.

Highlights

• New Middleware Pattern: Introduces createCspMiddleware() for TanStack Start, replacing the previous handler wrapper with a more integrated approach for managing Content Security Policy (CSP) headers.
• Per-Request Nonce Generation: Adds native support for generating cryptographically secure, per-request nonces, significantly enhancing security by preventing replay attacks and ensuring unique script execution authorization for each request.
• Isomorphic Nonce Retrieval: Provides createNonceGetter() for seamless nonce retrieval on both the server (from middleware context) and client (from a meta tag), facilitating integration with TanStack Router's native ssr.nonce option.
• Enhanced CSP Security: Enforces strict nonce-based CSP for scripts, eliminating 'unsafe-inline' in production, supporting 'strict-dynamic', and automatically applying nonces to all TanStack framework scripts. It also includes CSP Level 3 support with granular directive copying.
• Deprecated v0.1 API: The createSecureHandler (v0.1 API) is now deprecated but maintained for backward compatibility, with a clear migration path to the new middleware pattern.
• New Peer Dependency: This major version (v0.2) introduces @tanstack/start-storage-context >= 1.0.0 as a new peer dependency.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-executed update to implement a middleware pattern with per-request nonce support, which is a great security improvement. The code is generally clean and the documentation updates are thorough. I've identified a few areas for improvement, mainly concerning a potential security issue in the documentation's example code, and some opportunities to enhance code robustness and maintainability in the new logic. My feedback focuses on correcting the documentation example and refactoring small parts of the code for better clarity and resilience.