joshlei-servercookies 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Lei
+
+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.

package/README.md

@@ -0,0 +1,76 @@
+# JoshLei ServerCookies
+
+Tiny helper to encrypt, decrypt, set, and remove HTTP cookies using AES-256-GCM. Designed to work with Express-style `res.cookie` or any Node.js response object that supports `setHeader`.
+
+## Install
+
+```sh
+npm install joshlei-servercookies
+```
+
+## Usage
+
+### With ES modules
+
+```js
+import { setEncryptedCookie, getDecryptedCookie, removeCookie } from 'joshlei-servercookies';
+
+const secret = process.env.COOKIE_SECRET;
+
+// Set an encrypted cookie
+setEncryptedCookie({
+  res, // Express response object
+  name: 'session',
+  data: { userId: '123' },
+  secret,
+  options: {
+    maxAge: 7 * 24 * 60 * 60 * 1000, // optional, defaults to 7 days
+    sameSite: 'none', // defaults to 'none'
+    secure: true,     // defaults to true
+    httpOnly: true    // defaults to true
+  }
+});
+
+// Read and decrypt
+const session = getDecryptedCookie({ req, name: 'session', secret });
+
+// Remove
+removeCookie({ res, name: 'session', options: { sameSite: 'none', secure: true } });
+```
+
+### With CommonJS
+
+```js
+const { setEncryptedCookie, getDecryptedCookie, removeCookie } = require('joshlei-servercookies');
+```
+
+## API
+
+### `setEncryptedCookie({ res, name, data, secret, options })`
+- `res`: Express-like response. If `res.cookie` exists it is used; otherwise `Set-Cookie` header is written.
+- `name`: Cookie name (required).
+- `data`: Any JSON-serializable value (required).
+- `secret`: String used to derive a 256-bit key (required).
+- `options` (all optional):
+  - `maxAge` (ms) default 7 days
+  - `domain`, `path` default `/`
+  - `httpOnly` default `true`
+  - `secure` default `true`
+  - `sameSite` default `'none'`
+
+### `getDecryptedCookie({ req, name, secret })`
+- `req.headers.cookie` is parsed to find `name`.
+- Returns parsed JSON value or `null` when missing/invalid/decryption fails.
+
+### `removeCookie({ res, name, options })`
+- Sets the cookie with `maxAge: 0` using the same option defaults as `setEncryptedCookie`.
+
+## Security notes
+- Use a strong, random secret stored outside source control (env var).
+- Cookies are authenticated and encrypted with AES-256-GCM; tampering returns `null` on read.
+- Ensure `secure: true` and `sameSite` are configured for your deployment needs.
+
+## Release
+1. Update `version` in package.json if needed.
+2. `npm login` (once per machine).
+3. `npm publish --access public` from the project root.

package/index.js

@@ -0,0 +1,97 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'crypto';
+
+const deriveKey = (secret) => {
+  if (!secret || typeof secret !== 'string') {
+    throw new Error('Secret must be a non-empty string');
+  }
+  return createHash('sha256').update(secret, 'utf8').digest();
+};
+
+const encrypt = (plaintext, secret) => {
+  const key = deriveKey(secret);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `${iv.toString('hex')}:${tag.toString('hex')}:${encrypted.toString('hex')}`;
+};
+
+const decrypt = (payload, secret) => {
+  const key = deriveKey(secret);
+  const [ivHex, tagHex, dataHex] = (payload || '').split(':');
+  if (!ivHex || !tagHex || !dataHex) throw new Error('Invalid encrypted payload format');
+  const iv = Buffer.from(ivHex, 'hex');
+  const tag = Buffer.from(tagHex, 'hex');
+  const encrypted = Buffer.from(dataHex, 'hex');
+  const decipher = createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(tag);
+  const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+  return decrypted.toString('utf8');
+};
+
+const serializeCookie = (name, value, options = {}) => {
+  const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
+  if (options.maxAge) parts.push(`Max-Age=${Math.floor(options.maxAge / 1000)}`);
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  if (options.path) parts.push(`Path=${options.path}`);
+  if (options.httpOnly) parts.push('HttpOnly');
+  if (options.secure) parts.push('Secure');
+  if (options.sameSite) parts.push(`SameSite=${options.sameSite}`);
+  return parts.join('; ');
+};
+
+export const setEncryptedCookie = ({ res, name, data, secret, options = {} }) => {
+  if (!res) throw new Error('Response object is required');
+  if (!name) throw new Error('Cookie name is required');
+  if (data === undefined || data === null) throw new Error('Cookie data cannot be null');
+  const payload = encrypt(JSON.stringify(data), secret);
+
+  const cookieOptions = {
+    httpOnly: options.httpOnly !== false,
+    secure: options.secure !== false,
+    sameSite: options.sameSite || 'none',
+    domain: options.domain,
+    path: options.path || '/',
+    maxAge: options.maxAge || 7 * 24 * 60 * 60 * 1000,
+  };
+
+  if (typeof res.cookie === 'function') {
+    res.cookie(name, payload, cookieOptions);
+  } else {
+    const serialized = serializeCookie(name, payload, cookieOptions);
+    res.setHeader('Set-Cookie', serialized);
+  }
+};
+
+export const getDecryptedCookie = ({ req, name, secret }) => {
+  if (!req || !req.headers) return null;
+  const raw = req.headers.cookie || '';
+  const pairs = raw.split(';').map(part => part.trim()).filter(Boolean);
+  const target = pairs.find(p => p.startsWith(`${encodeURIComponent(name)}=`));
+  if (!target) return null;
+  const value = decodeURIComponent(target.split('=').slice(1).join('='));
+  try {
+    const decrypted = decrypt(value, secret);
+    return JSON.parse(decrypted);
+  } catch (e) {
+    return null;
+  }
+};
+
+export const removeCookie = ({ res, name, options = {} }) => {
+  if (!res) throw new Error('Response object is required');
+  const cookieOptions = {
+    httpOnly: options.httpOnly !== false,
+    secure: options.secure !== false,
+    sameSite: options.sameSite || 'none',
+    domain: options.domain,
+    path: options.path || '/',
+    maxAge: 0,
+  };
+  if (typeof res.cookie === 'function') {
+    res.cookie(name, '', cookieOptions);
+  } else {
+    const serialized = serializeCookie(name, '', cookieOptions);
+    res.setHeader('Set-Cookie', serialized);
+  }
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "joshlei-servercookies",
+  "version": "1.0.0",
+  "description": "Tiny helper to encrypt, decrypt, set, and remove HTTP cookies with AES-256-GCM.",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "keywords": [
+    "cookie",
+    "cookies",
+    "http",
+    "express",
+    "encryption",
+    "aes",
+    "gcm"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "author": "Josh Lei",
+  "license": "MIT"
+}