@molecule/api-middleware-cookie-parser

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.

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.

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. Read it with NO fallback — a
// literal (or an empty-string) default ships in the source, so every
// deployment that does not set the variable signs cookies anyone can forge.
const sessionSecret = process.env.SESSION_SECRET
if (!sessionSecret) throw new Error('SESSION_SECRET must be set')
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

Middleware

Generic middleware type — framework-agnostic.

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

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

CookieParserFactory

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

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

Functions

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.

getCookieParser()

Gets the bonded cookie parser middleware.

function getCookieParser(): Middleware

Returns: The bonded cookie parser middleware function.

hasCookieParser()

Checks if a cookie parser middleware has been bonded.

function hasCookieParser(): boolean

Returns: true if a cookie parser is available.

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.

getCookieParserFactory()

Gets the bonded cookie parser factory.

function getCookieParserFactory(): CookieParserFactory | null

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

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.

Available Providers

Provider	Package
Cookie Parser (Express)	@molecule/api-middleware-cookie-parser-express

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.
• Never give that secret a default. process.env.SESSION_SECRET ?? 'dev-secret' (or ?? '') puts the signing key in the source: the deployed app puts it in production, and anyone who can read the code or the repo can mint a cookie the parser accepts. Read the variable and fail at boot when it is missing.