CookieTransport

WIP

The session id in an HttpOnly, __Host- prefixed cookie with a CSRF companion cookie, the default for browser apps

The default transport. The session id rides in an HttpOnly cookie the page's JavaScript cannot read, and a second, readable cookie carries the CSRF token.

import { cookieTransport } from '@gentleduck/auth/core/transport'

createAuth({
  // ...
  transport: cookieTransport(),
})

Without a transport, createAuth uses cookieTransport({ name: 'duck-sid' }): the same cookie under a name without the __Host- prefix.

Option	Default	Notes
`name`	`__Host-duck-sid`, or `duck-sid` with a `domain`	The `__Host-` prefix makes browsers insist on Secure, `Path=/` and no Domain.
`secure`	`true`	Set `false` only for plain-http local development; `strict()` refuses it in production.
`sameSite`	`'lax'`	`'none'` requires `secure`.
`path`	`/`	The `__Host-` prefix requires `/`.
`domain`	none	Shares the cookie across subdomains; forbidden with a `__Host-` name.
`maxAgeSec`	the session's absolute deadline	Ends the cookie earlier than the session.

A contradiction, such as a __Host- name with a domain, throws AUTH_MISCONFIGURED at construction.

Every sign-in also sets __Host-duck-csrf (or duck-csrf when the settings rule out the prefix) with the session's CSRF token. It is not HttpOnly: your page reads it and echoes it in the x-csrf-token header on every state-changing request. The adapters' CSRF guards check it; a mismatch answers 403 AUTH_CSRF.

transport.csrfCookieName answers the name in use, for the page to read it by.

Local development

Browsers drop a Secure cookie over plain http on anything but localhost, and a __Host- name requires Secure. For http development pass a plain name:

cookieTransport({ name: 'sid', secure: false })

The CSRF cookie follows, becoming duck-csrf.