Bring over RR cookies code into @remix-run/cookie package (#10796)

Co-authored-by: Michael Jackson <[email protected]>

Author: brophdawg11

packages/cookie/CHANGELOG.md

@@ -0,0 +1,5 @@
+# `@remix-run/cookie` CHANGELOG
+
+This is the changelog for [`@remix-run/cookie`](https://github.com/remix-run/remix/tree/main/packages/cookie). It follows [semantic versioning](https://semver.org/).
+
+## Unreleased

packages/cookie/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Michael Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/cookie/README.md

@@ -0,0 +1,201 @@
+# @remix-run/cookie
+
+Simplify HTTP cookie management in JavaScript with type-safe, secure cookie handling. `@remix-run/cookie` provides a clean, intuitive API for creating, parsing, and serializing HTTP cookies with built-in support for signing, secret rotation, and comprehensive cookie attribute management.
+
+HTTP cookies are essential for web applications—from session management and user preferences to authentication tokens and tracking. While the standard cookie parsing libraries provide basic functionality, they often leave complex scenarios like secure signing, secret rotation, and type-safe value handling up to you.
+
+`@remix-run/cookie` solves this by offering:
+
+- **Secure Cookie Signing:** Built-in cryptographic signing using HMAC-SHA256 to prevent cookie tampering, with support for secret rotation without breaking existing cookies.
+- **Type-Safe Value Handling:** Automatically serializes and deserializes JavaScript values (strings, objects, booleans, numbers) to/from cookie-safe formats.
+- **Comprehensive Cookie Attributes:** Full support for all standard cookie attributes including `Path`, `Domain`, `Secure`, `HttpOnly`, `SameSite`, `Max-Age`, and `Expires`.
+- **Reusable Cookie Containers:** Create logical cookie containers that can be used to parse and serialize multiple values over time.
+- **Web Standards Compliant:** Built on Web Crypto API and standard cookie parsing, making it runtime-agnostic (Node.js, Bun, Deno, Cloudflare Workers).
+- **Secret Rotation Support:** Seamlessly rotate signing secrets while maintaining backward compatibility with existing cookies.
+
+Perfect for building secure, maintainable cookie management in your JavaScript and TypeScript applications!
+
+## Installation
+
+```sh
+npm install @remix-run/cookie
+```
+
+## Overview
+
+The following should give you a sense of what kinds of things you can do with this library:
+
+```ts
+import { Cookie } from '@remix-run/cookie'
+
+// Create a basic cookie
+let sessionCookie = new Cookie('session')
+
+// Serialize a value to a Set-Cookie header
+let setCookieHeader = await sessionCookie.serialize({
+  userId: '12345',
+  theme: 'dark',
+})
+console.log(setCookieHeader)
+// session=eyJ1c2VySWQiOiIxMjM0NSIsInRoZW1lIjoiZGFyayJ9; Path=/; SameSite=Lax
+
+// Parse a Cookie header to get the value back
+let cookieHeader = 'session=eyJ1c2VySWQiOiIxMjM0NSIsInRoZW1lIjoiZGFyayJ9'
+let sessionData = await sessionCookie.parse(cookieHeader)
+console.log(sessionData) // { userId: '12345', theme: 'dark' }
+
+// Create a signed cookie for security
+let secureCookie = new Cookie('secure-session', {
+  secrets: ['Secr3t'], // Array to support secret rotation
+  httpOnly: true,
+  secure: true,
+  sameSite: 'strict',
+  maxAge: 60 * 60 * 24 * 7, // 7 days
+})
+
+// Signed cookies prevent tampering
+let signedValue = await secureCookie.serialize({ admin: true })
+console.log(signedValue)
+// secure-session=eyJhZG1pbiI6dHJ1ZX0.signature; Path=/; Max-Age=604800; HttpOnly; Secure; SameSite=Strict
+
+let parsedValue = await secureCookie.parse('secure-session=eyJhZG1pbiI6dHJ1ZX0.signature')
+console.log(parsedValue) // { admin: true }
+
+// Tampered cookies return null
+let tamperedValue = await secureCookie.parse('secure-session=eyJhZG1pbiI6ZmFsc2V9.badsignature')
+console.log(tamperedValue) // null
+
+// Cookie properties
+console.log(secureCookie.name) // 'secure-session'
+console.log(secureCookie.isSigned) // true
+console.log(secureCookie.expires) // Date object (calculated from maxAge)
+
+// Handle different data types
+let preferencesCookie = new Cookie('preferences')
+
+// Strings
+await preferencesCookie.serialize('light-mode')
+
+// Objects
+await preferencesCookie.serialize({
+  theme: 'dark',
+  language: 'en-US',
+  notifications: true,
+})
+
+// Booleans
+await preferencesCookie.serialize(false)
+
+// Numbers
+await preferencesCookie.serialize(42)
+```
+
+## Cookie Configuration
+
+Cookies can be configured with comprehensive options:
+
+```ts
+import { Cookie } from '@remix-run/cookie'
+
+let cookie = new Cookie('my-cookie', {
+  // Security options
+  secrets: ['secret1', 'secret2'], // For signing (first used for new cookies)
+  httpOnly: true, // Prevent JavaScript access
+  secure: true, // Require HTTPS
+
+  // Scope options
+  domain: '.example.com', // Cookie domain
+  path: '/admin', // Cookie path
+
+  // Expiration options
+  maxAge: 60 * 60 * 24, // Max age in seconds
+  expires: new Date('2025-12-31'), // Absolute expiration date
+
+  // SameSite options
+  sameSite: 'strict', // 'strict' | 'lax' | 'none'
+
+  // Encoding options (from 'cookie' package)
+  encode: (value) => encodeURIComponent(value),
+  decode: (value) => decodeURIComponent(value),
+})
+```
+
+## Secret Rotation
+
+One of the key features is seamless secret rotation for signed cookies:
+
+```ts
+// Start with an initial secret
+let cookie = new Cookie('session', {
+  secrets: ['secret-v1'],
+})
+
+let setCookie1 = await cookie.serialize({ user: 'alice' })
+
+// Later, rotate to a new secret while keeping the old one
+cookie = new Cookie('session', {
+  secrets: ['secret-v2', 'secret-v1'], // New secret first, old ones after
+})
+
+// New cookies use the new secret
+let setCookie2 = await cookie.serialize({ user: 'bob' })
+
+// But old cookies still work
+let oldValue = await cookie.parse(setCookie1.split(';')[0])
+console.log(oldValue) // { user: 'alice' } - still works!
+
+let newValue = await cookie.parse(setCookie2.split(';')[0])
+console.log(newValue) // { user: 'bob' }
+```
+
+## Advanced Usage
+
+### Custom Serialization Options
+
+You can override cookie options when serializing:
+
+```ts
+let cookie = new Cookie('flexible', {
+  maxAge: 60 * 60, // Default 1 hour
+})
+
+// Override for a specific use case
+let longLivedCookie = await cookie.serialize('remember-me', {
+  maxAge: 60 * 60 * 24 * 365, // 1 year
+})
+
+let sessionCookie = await cookie.serialize('temp-data', {
+  maxAge: undefined, // Session cookie (no expiration)
+  secure: false, // Maybe for development
+})
+```
+
+### Error Handling
+
+The library handles various error scenarios gracefully:
+
+```ts
+let cookie = new Cookie('test')
+
+// Missing or malformed cookie headers return null
+await cookie.parse(null) // null
+await cookie.parse('') // null
+await cookie.parse('other=value') // null
+
+// Malformed cookie values return empty object or null
+await cookie.parse('test=invalid-base64@#$') // {}
+
+// Signed cookies with bad signatures return null
+let signedCookie = new Cookie('signed', { secrets: ['secret'] })
+await signedCookie.parse('signed=value.badsignature') // null
+```
+
+## Related Packages
+
+- [`headers`](https://github.com/remix-run/remix/tree/main/packages/headers) - Type-safe HTTP header manipulation
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Build HTTP routers using the web fetch API
+- [`node-fetch-server`](https://github.com/remix-run/remix/tree/main/packages/node-fetch-server) - Build HTTP servers on Node.js using the web fetch API
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

packages/cookie/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@remix-run/cookie",
+  "version": "0.1.0",
+  "description": "A toolkit for working with cookies in JavaScript",
+  "author": "Michael Jackson <[email protected]>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/remix-run/remix.git",
+    "directory": "packages/cookie"
+  },
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/cookie#readme",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0"
+  },
+  "peerDependencies": {
+    "@remix-run/headers": "workspace:*"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "git clean -fdX",
+    "prepublishOnly": "pnpm run build",
+    "test": "node --disable-warning=ExperimentalWarning --test './src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "http",
+    "cookie",
+    "cookies",
+    "http-cookies",
+    "set-cookie"
+  ]
+}

packages/cookie/src/index.ts

@@ -0,0 +1 @@
+export { type CookieOptions, Cookie } from './lib/cookie.ts'