@molecule/api-middleware-cookie-parser

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Cookie parser middleware for molecule.dev.

Core interface — the actual implementation is provided via bonds. Install a cookie parser bond (e.g., @molecule/api-middleware-cookie-parser-express) to provide cookie parsing.

Quick Start

import express from 'express'
import { cookieParser, createCookieParserMiddleware } from '@molecule/api-middleware-cookie-parser'

const app = express()

// Default parser (unsigned cookies) — requires the bond to be wired,
// e.g. @molecule/api-middleware-cookie-parser-express.
app.use(cookieParser)

// Signed cookies: pass the server-side secret; verified values land on
// req.signedCookies with the Express bond.
const sessionSecret = process.env.SESSION_SECRET ?? ''
app.use(createCookieParserMiddleware(sessionSecret))

Type

middleware

Installation

npm install @molecule/api-middleware-cookie-parser @molecule/api-bond

API

Interfaces

CookieParseOptions

Options for cookie parsing.

interface CookieParseOptions {
  decode?: (value: string) => string
}

Types

CookieParserFactory

Factory function type for creating cookie parser middleware with secret and options.

type CookieParserFactory = (secret?: string | string[], options?: CookieParseOptions) => Middleware

Middleware

Generic middleware type — framework-agnostic.

type Middleware = (req: unknown, res: unknown, next: (err?: unknown) => void) => void

Functions

cookieParser(req, res, next)

Default cookie parser middleware that delegates to the bonded implementation. Parses the Cookie header and populates req.cookies.

function cookieParser(req: unknown, res: unknown, next: (err?: unknown) => void): void

• req — The incoming request object.
• res — The response object.
• next — The next middleware function.

Returns: The result of the bonded cookie parser invocation.

createCookieParserMiddleware(secret, options)

Creates cookie parser middleware with custom options via the bonded factory.

function createCookieParserMiddleware(
  secret?: string | string[],
  options?: CookieParseOptions,
): Middleware

• secret — Secret string(s) for signed cookie verification.
• options — Cookie parsing options (e.g., custom decode function).

Returns: A middleware function that parses cookies.

getCookieParser()

Gets the bonded cookie parser middleware.

function getCookieParser(): Middleware

Returns: The bonded cookie parser middleware function.

getCookieParserFactory()

Gets the bonded cookie parser factory.

function getCookieParserFactory(): CookieParserFactory | null

Returns: The factory function, or null if none has been bonded.

hasCookieParser()

Checks if a cookie parser middleware has been bonded.

function hasCookieParser(): boolean

Returns: true if a cookie parser is available.

setCookieParser(parser)

Bonds a cookie parser middleware implementation for use by getCookieParser() and cookieParser.

function setCookieParser(parser: Middleware): void

• parser — The middleware function that parses cookies.

setCookieParserFactory(factory)

Bonds a cookie parser factory for creating parsers with custom secrets and options.

function setCookieParserFactory(factory: CookieParserFactory): void

• factory — A function that creates cookie parser middleware from options.

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-bond ^1.0.1

Runtime Dependencies

• @molecule/api-bond

This parses INCOMING cookies onto req.cookies. When your app SETS an auth/session cookie, the flags are what matter:

• Auth/session cookies MUST be httpOnly + secure + sameSite. httpOnly stops JS (and therefore XSS) from reading the token; secure restricts it to HTTPS in production; sameSite: 'lax'|'strict' blocks CSRF. A readable session cookie is stealable.
• Never store a secret or raw token in a plain, non-httpOnly cookie — it's readable by the client and sent on every request. Sign cookies with a SERVER-side secret (SESSION_SECRET) when you need tamper detection, and keep the real state server-side keyed by the session.