docs: clarify difference and relationship between httpOnly and secure flags

[renhyl]

clarifies difference and relationship of httpOnly and secure flags.

The httpOnly and secure flags are independent but complementary security features for cookies. They protect against different types of vulnerabilities.
httpOnly vs secure:
httpOnly - Controls WHO can access the cookie:
- true: Only server can access (blocks client-side JavaScript)
- false: Both server and client-side JavaScript can access

secure - Controls HOW the cookie is transmitted:
- true: Only sent over HTTPS connections
- false: Sent over both HTTP and HTTPS

---

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• [n/a] It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• This message body should clearly illustrate what problems it solves.
• [n/a] Ideally, include a test that fails without this PR but passes with it.

Tests

• [n/a] Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

• [n/a] If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

Edits

• [ok] Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed.

[changeset-bot]

⚠️ No Changeset found

Latest commit: a8b756d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[svelte-docs-bot]

Preview: https://svelte-dev-git-preview-kit-13875-svelte.vercel.app/

[renhyl]

looks like prettier/lint are broken, can't get past it, pnpm run check passes, pnpm run lint fails, i did pnpm run format and i am still stuck on linter error.

[Conduitry]

IMO we should, if anything, just be linking to MDN. We shouldn't take it upon ourselves to describe general web platform features.

[benmccann]

Those fields are documented as part of import('cookie').CookieSerializeOptions:

    /**
     * Enables the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6).
     * When enabled, clients will not allow client-side JavaScript to see the cookie in `document.cookie`.
     */
    httpOnly?: boolean;
    /**
     * Enables the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5).
     * When enabled, clients will only send the cookie back if the browser has a HTTPS connection.
     */
    secure?: boolean;

That seems to cover it pretty well. If some additional clarification is needed, I think it should be done there - i.e. in the cookie package

[renhyl]

Sorry guys, @benmccann @Conduitry I want to push back on this a little bit, imho that is not good enough, I don't know what to do here but I will try my best to explain and I hope this makes sense to you and others..

Long story short, myself as well as number of people looked at the documentation of relevant httpOnly and secure flags that is: https://svelte.dev/docs/kit/@sveltejs-kit#Cookies
and reading through it it is unclear what these flags do exactly. I truly believe it is not just "me" problem. When it boils down to semantics the SvelteKit documentation does not describe what each flag does that is certain.

Currently SvelteKit docs:

The httpOnly and secure options are true by default (except on http://localhost/, where secure is false), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP. The sameSite option defaults to lax.

That is all I can find/read about these flags in docs.

@benmccann as you pointed out these fields are documented import('cookie').CookieSerializeOptions but as I user of SvelteKit:
a) I had no idea on the surface that there is another package involved that has documentation for these flags
b) I am using SvelteKit and I expect documentation to be descriptive in regards to features/tools it offers (what is under the hood) is not much of my concern as end user and I don't believe I should be expected to digest through every dark corner of the codebase or every single library/package the SvelteKit uses to just be able to understand as set a thing such as setting/flag.

@Conduitry if as per your suggestion we should be linking to MDN let's do that, would you be kind enough to update that?

@Conduitry @benmccann , at the end of the day I would love for any user reading through the documentation not to face same dilemma and confusion as me and my colleagues and I truly believe making a documentation a bit more explicit or less vague can't be that wrong?

Thank you for the help and support but most of all for understanding.

Those fields are documented as part of import('cookie').CookieSerializeOptions:

    /**
     * Enables the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6).
     * When enabled, clients will not allow client-side JavaScript to see the cookie in `document.cookie`.
     */
    httpOnly?: boolean;
    /**
     * Enables the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5).
     * When enabled, clients will only send the cookie back if the browser has a HTTPS connection.
     */
    secure?: boolean;

That seems to cover it pretty well. If some additional clarification is needed, I think it should be done there - i.e. in the cookie package

[benmccann]

I think the correct fix for this would be to update the docs generation to better handle types from external packages