Cookie Helpers

Cookie helpers provide utilities for setting and reading HTTP cookies from fetch headers.

Basic Usage

import { function deleteCookie(headers: Headers | undefined, name: string, options?: Omit<SetCookieOptions, "maxAge">): voidDeletes a cookie by marking it expired.
@see{@link https://orpc.dev/docs/helpers/cookie Cookie Helpers}deleteCookie, function getCookie(headers: Headers | undefined, name: string, options?: GetCookieOptions): string | undefinedGets a cookie value from request headers

Returns `undefined` if the cookie is not found or headers are `undefined`.
@example```ts
const headers = new Headers({ 'Cookie': 'sessionId=abc123; theme=dark' })

const sessionId = getCookie(headers, 'sessionId')

expect(sessionId).toEqual('abc123')
```@see{@link https://orpc.dev/docs/helpers/cookie Cookie Helpers}getCookie, function setCookie(headers: Headers | undefined, name: string, value: string, options?: SetCookieOptions): voidSets a cookie in the response headers.

Does nothing if `headers` is `undefined`.
@example```ts
const headers = new Headers()

setCookie(headers, 'sessionId', 'abc123', { httpOnly: true, maxAge: 3600 })

expect(headers.get('Set-Cookie')).toBe('sessionId=abc123; Max-Age=3600; Path=/; HttpOnly')
```@see{@link https://orpc.dev/docs/helpers/cookie Cookie Helpers}setCookie } from '@orpc/server/helpers'

const const reqHeaders: HeadersreqHeaders = new var Headers: new (init?: HeadersInit) => HeadersThe **`Headers`** interface of the Fetch API allows you to perform various actions on HTTP request and response headers. These actions include retrieving, setting, adding to, and removing headers from the list of the request's headers.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers)Headers()
const const resHeaders: HeadersresHeaders = new var Headers: new (init?: HeadersInit) => HeadersThe **`Headers`** interface of the Fetch API allows you to perform various actions on HTTP request and response headers. These actions include retrieving, setting, adding to, and removing headers from the list of the request's headers.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers)Headers()

function setCookie(headers: Headers | undefined, name: string, value: string, options?: SetCookieOptions): voidSets a cookie in the response headers.

Does nothing if `headers` is `undefined`.
@example```ts
const headers = new Headers()

setCookie(headers, 'sessionId', 'abc123', { httpOnly: true, maxAge: 3600 })

expect(headers.get('Set-Cookie')).toBe('sessionId=abc123; Max-Age=3600; Path=/; HttpOnly')
```@see{@link https://orpc.dev/docs/helpers/cookie Cookie Helpers}setCookie(const resHeaders: HeadersresHeaders, 'sessionId', 'abc123', {
  secure?: boolean | undefinedEnables 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 an HTTPS connection.secure: true,
  maxAge?: number | undefinedSpecifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2).

The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and
`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
so if both are set, they should point to the same date and time.maxAge: 3600
})

function deleteCookie(headers: Headers | undefined, name: string, options?: Omit<SetCookieOptions, "maxAge">): voidDeletes a cookie by marking it expired.
@see{@link https://orpc.dev/docs/helpers/cookie Cookie Helpers}deleteCookie(const resHeaders: HeadersresHeaders, 'sessionId')

const const sessionId: string | undefinedsessionId = function getCookie(headers: Headers | undefined, name: string, options?: GetCookieOptions): string | undefinedGets a cookie value from request headers

Returns `undefined` if the cookie is not found or headers are `undefined`.
@example```ts
const headers = new Headers({ 'Cookie': 'sessionId=abc123; theme=dark' })

const sessionId = getCookie(headers, 'sessionId')

expect(sessionId).toEqual('abc123')
```@see{@link https://orpc.dev/docs/helpers/cookie Cookie Helpers}getCookie(const reqHeaders: HeadersreqHeaders, 'sessionId')

Security with Signing and Encryption

Combine cookies with signing or encryption for enhanced security:

import { function getCookie(headers: Headers | undefined, name: string, options?: GetCookieOptions): string | undefinedGets a cookie value from request headers

Returns `undefined` if the cookie is not found or headers are `undefined`.
@example```ts
const headers = new Headers({ 'Cookie': 'sessionId=abc123; theme=dark' })

const sessionId = getCookie(headers, 'sessionId')

expect(sessionId).toEqual('abc123')
```@see{@link https://orpc.dev/docs/helpers/cookie Cookie Helpers}getCookie, function setCookie(headers: Headers | undefined, name: string, value: string, options?: SetCookieOptions): voidSets a cookie in the response headers.

Does nothing if `headers` is `undefined`.
@example```ts
const headers = new Headers()

setCookie(headers, 'sessionId', 'abc123', { httpOnly: true, maxAge: 3600 })

expect(headers.get('Set-Cookie')).toBe('sessionId=abc123; Max-Age=3600; Path=/; HttpOnly')
```@see{@link https://orpc.dev/docs/helpers/cookie Cookie Helpers}setCookie, function sign(value: string, secret: string): Promise<string>Signs a string value using HMAC-SHA256 with a secret key.

This function creates a cryptographic signature that can be used to verify
the integrity and authenticity of the data. The signature is appended to
the original value, separated by a dot, using base64url encoding (no padding).
@example```ts
const signedValue = await sign("user123", "my-secret-key")
expect(signedValue).toEqual("user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA")
```@see{@link https://orpc.dev/docs/helpers/signing Signing Helpers}sign, function unsign(signedValue: string | undefined | null, secret: string): Promise<string | undefined>Verifies and extracts the original value from a signed string.

This function validates the signature of a previously signed value using the same
secret key. If the signature is valid, it returns the original value. If the
signature is invalid or the format is incorrect, it returns undefined.
@example```ts
const signedValue = "user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA"
const originalValue = await unsign(signedValue, "my-secret-key")
expect(originalValue).toEqual("user123")
```@see{@link https://orpc.dev/docs/helpers/signing Signing Helpers}unsign } from '@orpc/server/helpers'

const const secret: "your-secret-key"secret = 'your-secret-key'

const const reqHeaders: HeadersreqHeaders = new var Headers: new (init?: HeadersInit) => HeadersThe **`Headers`** interface of the Fetch API allows you to perform various actions on HTTP request and response headers. These actions include retrieving, setting, adding to, and removing headers from the list of the request's headers.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers)Headers()
const const resHeaders: HeadersresHeaders = new var Headers: new (init?: HeadersInit) => HeadersThe **`Headers`** interface of the Fetch API allows you to perform various actions on HTTP request and response headers. These actions include retrieving, setting, adding to, and removing headers from the list of the request's headers.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers)Headers()

function setCookie(headers: Headers | undefined, name: string, value: string, options?: SetCookieOptions): voidSets a cookie in the response headers.

Does nothing if `headers` is `undefined`.
@example```ts
const headers = new Headers()

setCookie(headers, 'sessionId', 'abc123', { httpOnly: true, maxAge: 3600 })

expect(headers.get('Set-Cookie')).toBe('sessionId=abc123; Max-Age=3600; Path=/; HttpOnly')
```@see{@link https://orpc.dev/docs/helpers/cookie Cookie Helpers}setCookie(const resHeaders: HeadersresHeaders, 'sessionId', await function sign(value: string, secret: string): Promise<string>Signs a string value using HMAC-SHA256 with a secret key.

This function creates a cryptographic signature that can be used to verify
the integrity and authenticity of the data. The signature is appended to
the original value, separated by a dot, using base64url encoding (no padding).
@example```ts
const signedValue = await sign("user123", "my-secret-key")
expect(signedValue).toEqual("user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA")
```@see{@link https://orpc.dev/docs/helpers/signing Signing Helpers}sign('abc123', const secret: "your-secret-key"secret), {
  httpOnly?: boolean | undefinedEnables 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: true,
  secure?: boolean | undefinedEnables 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 an HTTPS connection.secure: true,
  maxAge?: number | undefinedSpecifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2).

The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and
`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
so if both are set, they should point to the same date and time.maxAge: 3600
})

const const signedSessionId: string | undefinedsignedSessionId = await function unsign(signedValue: string | undefined | null, secret: string): Promise<string | undefined>Verifies and extracts the original value from a signed string.

This function validates the signature of a previously signed value using the same
secret key. If the signature is valid, it returns the original value. If the
signature is invalid or the format is incorrect, it returns undefined.
@example```ts
const signedValue = "user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA"
const originalValue = await unsign(signedValue, "my-secret-key")
expect(originalValue).toEqual("user123")
```@see{@link https://orpc.dev/docs/helpers/signing Signing Helpers}unsign(function getCookie(headers: Headers | undefined, name: string, options?: GetCookieOptions): string | undefinedGets a cookie value from request headers

Returns `undefined` if the cookie is not found or headers are `undefined`.
@example```ts
const headers = new Headers({ 'Cookie': 'sessionId=abc123; theme=dark' })

const sessionId = getCookie(headers, 'sessionId')

expect(sessionId).toEqual('abc123')
```@see{@link https://orpc.dev/docs/helpers/cookie Cookie Helpers}getCookie(const reqHeaders: HeadersreqHeaders, 'sessionId'), const secret: "your-secret-key"secret)