Skip to content

docs(session): note secure cookie limitation over local HTTP#1409

Open
Aimee1608 wants to merge 1 commit into
h3js:mainfrom
Aimee1608:docs/session-secure-cookie-local-http
Open

docs(session): note secure cookie limitation over local HTTP#1409
Aimee1608 wants to merge 1 commit into
h3js:mainfrom
Aimee1608:docs/session-secure-cookie-local-http

Conversation

@Aimee1608

@Aimee1608 Aimee1608 commented Jun 5, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown

Summary

The session example in docs/4.examples/handle-session.md configures the cookie with secure: true, but the docs don't mention that this silently breaks sessions during local HTTP development: compliant browsers (notably Safari/iOS, and Chrome on some local domains) drop secure cookies sent over plain HTTP, so the session never persists.

This adds a short note after the Options section explaining the behavior and the cookie: { secure: false } workaround for local development.

As suggested by @pi0 in #977:

Overriding is fairly easy with session config { cookie: { secure: false } }, i think we can make the documentation more clear about this.

Changes

  • docs/4.examples/handle-session.md: add a > [!NOTE] after the Options example documenting the secure cookie limitation over local HTTP and the workaround.

Docs-only change, no behavior change. It intentionally does not add NODE_ENV-based auto-switching of secure, since that would be a behavior change that hasn't been agreed on in the issue.

Closes #977

AI-assisted; I reviewed and verified this change before submitting.

Summary by CodeRabbit

  • Documentation
    • Updated session handling documentation with enhanced guidance on secure cookie configuration. Clarifies how strict HTTPS-only settings may affect session persistence in local HTTP development and provides practical recommendations for configuring cookies appropriately across different development and production scenarios.

@Aimee1608
docs(session): note secure cookie limitation over local HTTP
90b92cb 
The session example sets cookie.secure to true but does not mention that
compliant browsers silently drop secure cookies over plain HTTP, breaking
sessions during local development. Document the secure: false workaround.

Closes h3js#977
@Aimee1608 Aimee1608 requested a review from pi0 as a code owner June 5, 2026 03:14
@coderabbitai

coderabbitai Bot commented Jun 5, 2026 •
edited
Loading

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b716b336-ade5-478d-a6eb-b3d240e12020

📥 Commits

Reviewing files that changed from the base of the PR and between 7eb018e and 90b92cb.

📒 Files selected for processing (1)
  • docs/4.examples/handle-session.md
📝 Walkthrough

Walkthrough

Adds a documentation note explaining that the default cookie: { secure: true } setting prevents session cookie persistence over HTTP in local development environments, particularly affecting Safari and iOS, with guidance to use secure: false locally.

Changes

Session Documentation Clarification

Layer / File(s) Summary
Secure flag local development note
docs/4.examples/handle-session.md		 A NOTE is added to the Options section documenting that cookie: { secure: true } restricts cookies to HTTPS connections and prevents session persistence in local HTTP development, with the recommended workaround of setting cookie: { secure: false } during local testing.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐰 A cookie so secure, yet lost in dev's night,
Safari won't hold it, despite all its might,
"Set secure to false!" cries our cottontail friend,
"In localhost's realm, let HTTPS suspend!"
🍪✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely summarizes the main change: documenting the secure cookie limitation when using local HTTP development.
Linked Issues check ✅ Passed The PR successfully addresses all key coding-related requirements from issue #977: documents DEFAULT_COOKIE.secure behavior, explains browsers drop secure cookies over plain HTTP, and provides the workaround to set cookie: { secure: false } for local development.
Out of Scope Changes check ✅ Passed The change is narrowly scoped to documentation only, adding a NOTE explaining secure cookie behavior and the local development workaround, with no runtime changes or behavioral modifications outside issue #977's scope.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pi0 pi0 Awaiting requested review from pi0 pi0 is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs about insecure session cookies

1 participant

@Aimee1608