docs(security): document HSTS_INCLUDE_SUBDOMAINS and the reach of includeSubDomains

[Lingikaushikreddy]

Description

Adds a note to docs/SECURITY.md naming HSTS_INCLUDE_SUBDOMAINS and what turning it on does, next to the existing notes on row 1.1.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• Test addition or update

Related Issue

Closes #867

Changes Made

• New 1.1, HSTS note: the header is always sent with a 180-day max-age (HSTS_MAX_AGE_SECONDS = 15 552 000), cannot be switched off, and is ignored over plain HTTP.
• Explains that includeSubDomains is opt-in via HSTS_INCLUDE_SUBDOMAINS=true (default false in readHstsIncludeSubDomains()) and that its reach depends on the hostname, with no server-side way to withdraw a cached pin.

Testing

• I have tested this locally
• I have added/updated tests
• All existing tests pass

Docs-only change. Ran bun run security:check (20 controls documented, 21 security tests accounted for), bun run format (no changes), and the unit and security tests that read the docs: security-check, env-documentation, agent-documentation, vulnerability-disclosure, credential-at-rest and related (232 pass).

Checklist

• My code follows the project's code style guidelines
• I have performed a self-review of my code
• I have updated the documentation accordingly
• My changes generate no new warnings

Additional Notes

One thing I'd like a second opinion on. The .env.example comment (and the readHstsIncludeSubDomains() JSDoc) say enabling it on studio.example.com would upgrade unrelated sibling hosts. Per RFC 6797, includeSubDomains covers subdomains of the host that sent the header, so from studio.example.com it reaches *.studio.example.com, not shop.example.com. Siblings are only affected when Studio is served from the parent domain itself. The note describes it that way. Happy to also correct the two comments in this PR, or reword the note if I've misread the intent.

[Lingikaushikreddy]

Thanks for assigning #867, @cevheri! The branch has no conflicts with main. Since this is my first contribution here, the CI workflows are waiting on maintainer approval before they run. Locally bun run security:check, bun run format and the doc-related unit tests all pass. Happy to change anything you'd like.

[cevheri]

One thing I'd like a second opinion on. The .env.example comment (and the readHstsIncludeSubDomains() JSDoc) say enabling it on studio.example.com would upgrade unrelated sibling hosts. Per RFC 6797, includeSubDomains covers subdomains of the host that sent the header, so from studio.example.com it reaches *.studio.example.com, not shop.example.com. Siblings are only affected when Studio is served from the parent domain itself. The note describes it that way. Happy to also correct the two comments in this PR, or reword the note if I've misread the intent.

[cevheri]

your website is great, love it :)

[Lingikaushikreddy]

Thanks @cevheri, and thanks for the kind words about the site :)

On the HSTS wording: since this PR is already approved, I'd rather not change its diff. I can open a small follow-up after it merges that corrects the .env.example comment and the readHstsIncludeSubDomains() JSDoc to say includeSubDomains reaches hosts under the one serving Studio, and only affects siblings when Studio is on the parent domain. Or if you'd prefer it in this PR, I'll push it here. Whichever is easier for you.

[cevheri]

Thanks @cevheri, and thanks for the kind words about the site :)

On the HSTS wording: since this PR is already approved, I'd rather not change its diff. I can open a small follow-up after it merges that corrects the .env.example comment and the readHstsIncludeSubDomains() JSDoc to say includeSubDomains reaches hosts under the one serving Studio, and only affects siblings when Studio is on the parent domain. Or if you'd prefer it in this PR, I'll push it here. Whichever is easier for you.

Your reading is right, and the note in this PR is the one that matches RFC 6797: includeSubDomains covers names under the host that sent the header, so from studio.example.com it reaches *.studio.example.com, and siblings like shop.example.com are only affected when Studio is served from the parent domain itself.

That means the doc you added is now correct and two places in the repo are not: the comment at .env.example:545-546 ("on studio.example.com it would also upgrade every unrelated sibling host") and the JSDoc above readHstsIncludeSubDomains() at src/lib/security/config.ts:65-66. The behaviour they describe is not what the code does on a dedicated host.

Let us keep this PR as it is and merge it, since the approval and the green run are on this diff. A separate follow-up
correcting those two comments would be very welcome, and it is a small one: same wording as the note you already
wrote, nothing else to change. Please open it against main.

Thanks for measuring this instead of copying the existing comment across.