@remix-run/cookie 0.3.0 → 0.4.1

package/README.md

@@ -8,8 +8,6 @@ HTTP cookies are essential for web applications, from session management and use
 
 - **Secure Cookie Signing:** Built-in cryptographic signing using HMAC-SHA256 to prevent cookie tampering, with support for secret rotation without breaking existing cookies.
 - **Secret Rotation Support:** Seamlessly rotate signing secrets while maintaining backward compatibility with existing cookies.
-- **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).
 
 ## Installation
@@ -21,9 +19,18 @@ npm install @remix-run/cookie
 ## Usage
 
 ```tsx
-import { Cookie } from '@remix-run/cookie'
+import { createCookie } from '@remix-run/cookie'
+
+let sessionCookie = createCookie('session', {
+  httpOnly: true,
+  secrets: ['s3cret1'],
+  secure: true,
+})
 
-let sessionCookie = new Cookie('session')
+cookie.name // "session"
+cookie.httpOnly // true
+cookie.secure // true
+cookie.signed // true
 
 // Get the value of the "session" cookie from the request's `Cookie` header
 let value = await sessionCookie.parse(request.headers.get('Cookie'))
@@ -46,7 +53,7 @@ Secret rotation is also supported, so you can easily rotate in new secrets witho
 import { Cookie } from '@remix-run/cookie'
 
 // Start with a single secret
-let sessionCookie = new Cookie('session', {
+let sessionCookie = createCookie('session', {
   secrets: ['secret1'],
 })
 
@@ -62,12 +69,19 @@ let response = new Response('Hello, world!', {
 All cookies sent in this scenario will be signed with the secret `secret1`. Later, when it's time to rotate secrets, add a new secret to the beginning of the array and all existing cookies will still be able to be parsed.
 
 ```tsx
-let sessionCookie = new Cookie('session', {
+let sessionCookie = createCookie('session', {
   secrets: ['secret2', 'secret1'],
 })
 
-// This will still work for cookies signed with the old secret
+// This works for cookies signed with either secret
 let value = await sessionCookie.parse(request.headers.get('Cookie'))
+
+// Newly serialized cookies will be signed with the new secret
+let response = new Response('Hello, world!', {
+  headers: {
+    'Set-Cookie': await sessionCookie.serialize(value),
+  },
+})
 ```
 
 ### Custom Encoding
@@ -75,7 +89,7 @@ let value = await sessionCookie.parse(request.headers.get('Cookie'))
 By default, the library will use `encodeURIComponent` and `decodeURIComponent` to encode and decode the cookie value. This is suitable for most use cases, but you can provide your own functions to customize the encoding and decoding of the cookie value.
 
 ```tsx
-let sessionCookie = new Cookie('session', {
+let sessionCookie = createCookie('session', {
   encode: (value) => value,
   decode: (value) => value,
 })

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createCookie, type CookieOptions, Cookie } from './lib/cookie.ts';
+export { type Cookie, type CookieOptions, createCookie } from './lib/cookie.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -1 +1 @@
-export { createCookie, Cookie } from "./lib/cookie.js";
+export { createCookie } from "./lib/cookie.js";

package/dist/lib/{crypto.d.ts → cookie-signing.d.ts}

@@ -1,3 +1,3 @@
 export declare function sign(value: string, secret: string): Promise<string>;
 export declare function unsign(cookie: string, secret: string): Promise<string | false>;
-//# sourceMappingURL=crypto.d.ts.map
+//# sourceMappingURL=cookie-signing.d.ts.map

package/dist/lib/cookie-signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-signing.d.ts","sourceRoot":"","sources":["../../src/lib/cookie-signing.ts"],"names":[],"mappings":"AAEA,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOzE;AAED,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,CAuBpF"}

package/dist/lib/{crypto.js → cookie-signing.js}

@@ -8,12 +8,15 @@ export async function sign(value, secret) {
 }
 export async function unsign(cookie, secret) {
     let index = cookie.lastIndexOf('.');
+    if (index === -1) {
+        return false;
+    }
     let value = cookie.slice(0, index);
     let hash = cookie.slice(index + 1);
     let data = encoder.encode(value);
     let key = await createKey(secret, ['verify']);
     try {
-        let signature = byteStringToUint8Array(atob(hash));
+        let signature = byteStringToArray(atob(hash));
         let valid = await crypto.subtle.verify('HMAC', key, signature, data);
         return valid ? value : false;
     }
@@ -27,7 +30,7 @@ export async function unsign(cookie, secret) {
 async function createKey(secret, usages) {
     return crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, usages);
 }
-function byteStringToUint8Array(byteString) {
+function byteStringToArray(byteString) {
     let array = new Uint8Array(byteString.length);
     for (let i = 0; i < byteString.length; i++) {
         array[i] = byteString.charCodeAt(i);

package/dist/lib/cookie.d.ts

@@ -1,11 +1,86 @@
 import { type CookieProperties } from '@remix-run/headers';
+type SameSiteValue = 'Strict' | 'Lax' | 'None';
 /**
- * Creates a new `Cookie` object.
- * @param name The name of the cookie
- * @param options The options for the cookie
- * @returns A new cookie instance
+ * Represents a HTTP cookie.
+ *
+ * Supports parsing and serializing the cookie to/from `Cookie` and `Set-Cookie` headers.
+ *
+ * Also supports cryptographic signing of the cookie value to ensure it's not tampered with, and
+ * secret rotation to easily rotate secrets without breaking existing cookies.
  */
-export declare function createCookie(name: string, options?: CookieOptions): Cookie;
+export interface Cookie {
+    /**
+     * The domain of the cookie.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#domaindomain-value)
+     */
+    readonly domain: string | undefined;
+    /**
+     * The expiration date of the cookie.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#expiresdate)
+     */
+    readonly expires: Date | undefined;
+    /**
+     * True if the cookie is HTTP-only.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#httponly)
+     */
+    readonly httpOnly: boolean;
+    /**
+     * The maximum age of the cookie in seconds.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#max-agenumber)
+     */
+    readonly maxAge: number | undefined;
+    /**
+     * The name of the cookie.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#cookie-namecookie-value)
+     */
+    readonly name: string;
+    /**
+     * Extracts the value of this cookie from a `Cookie` header value.
+     * @param headerValue The `Cookie` header to parse
+     * @returns The value of this cookie, or `null` if it's not present
+     */
+    parse(headerValue: string | null): Promise<string | null>;
+    /**
+     * True if the cookie is partitioned.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#partitioned)
+     */
+    readonly partitioned: boolean;
+    /**
+     * The path of the cookie. Defaults to `/`.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#pathpath-value)
+     */
+    readonly path: string;
+    /**
+     * The `SameSite` attribute of the cookie. Defaults to `Lax`.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value)
+     */
+    readonly sameSite: SameSiteValue;
+    /**
+     * True if the cookie is secure (only sent over HTTPS).
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#secure)
+     */
+    readonly secure: boolean;
+    /**
+     * Returns the value to use in a `Set-Cookie` header for this cookie.
+     * @param value The value to serialize
+     * @param props (optional) Additional properties to use when serializing the cookie
+     * @returns The `Set-Cookie` header for this cookie
+     */
+    serialize(value: string, props?: CookieProperties): Promise<string>;
+    /**
+     * True if this cookie uses one or more secrets for verification.
+     */
+    readonly signed: boolean;
+}
 export interface CookieOptions extends CookieProperties {
     /**
      * A function that decodes the cookie value.
@@ -36,32 +111,11 @@ export interface CookieOptions extends CookieProperties {
     secrets?: string[];
 }
 /**
- * A container for metadata about a HTTP cookie; its name and secrets that may be used
- * to sign/unsign the value of the cookie to ensure it's not tampered with.
+ * Creates a new cookie object.
+ * @param name The name of the cookie
+ * @param options (optional) Additional options for the cookie
+ * @returns A cookie object
  */
-export declare class Cookie {
-    #private;
-    constructor(name: string, options?: CookieOptions);
-    /**
-     * The name of the cookie.
-     */
-    readonly name: string;
-    /**
-     * True if this cookie uses one or more secrets for verification.
-     */
-    get signed(): boolean;
-    /**
-     * Extracts the value of this cookie from a `Cookie` header value.
-     * @param headerValue The value of the `Cookie` header to parse
-     * @returns The value of this cookie, or `null` if it's not present
-     */
-    parse(headerValue: string | null): Promise<string | null>;
-    /**
-     * Returns the value to use in a `Set-Cookie` header for this cookie.
-     * @param value The value to serialize
-     * @param props (optional) Additional properties to use when serializing the cookie
-     * @returns The value to use in a `Set-Cookie` header for this cookie
-     */
-    serialize(value: string, props?: CookieProperties): Promise<string>;
-}
+export declare function createCookie(name: string, options?: CookieOptions): Cookie;
+export {};
 //# sourceMappingURL=cookie.d.ts.map

package/dist/lib/cookie.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../src/lib/cookie.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAA;AAI3B;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAE1E;AAED,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;GAGG;AACH,qBAAa,MAAM;;gBACL,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa;IAejD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAOrB;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;OAIG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa/D;;;;;OAKG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;CAa1E"}
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../src/lib/cookie.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAA;AAI3B,KAAK,aAAa,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;AAE9C;;;;;;;GAOG;AACH,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,SAAS,CAAA;IAClC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACzD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAkF1E"}

package/dist/lib/cookie.js

@@ -1,76 +1,78 @@
 import { Cookie as CookieHeader, SetCookie as SetCookieHeader, } from '@remix-run/headers';
-import { sign, unsign } from "./crypto.js";
+import { sign, unsign } from "./cookie-signing.js";
 /**
- * Creates a new `Cookie` object.
+ * Creates a new cookie object.
  * @param name The name of the cookie
- * @param options The options for the cookie
- * @returns A new cookie instance
+ * @param options (optional) Additional options for the cookie
+ * @returns A cookie object
  */
 export function createCookie(name, options) {
-    return new Cookie(name, options);
-}
-/**
- * A container for metadata about a HTTP cookie; its name and secrets that may be used
- * to sign/unsign the value of the cookie to ensure it's not tampered with.
- */
-export class Cookie {
-    constructor(name, options) {
-        let { decode = decodeURIComponent, encode = encodeURIComponent, secrets = [], ...props } = options ?? {};
-        this.name = name;
-        this.#decode = decode;
-        this.#encode = encode;
-        this.#secrets = secrets;
-        this.#props = props;
-    }
-    /**
-     * The name of the cookie.
-     */
-    name;
-    #decode;
-    #encode;
-    #secrets;
-    #props;
-    /**
-     * True if this cookie uses one or more secrets for verification.
-     */
-    get signed() {
-        return this.#secrets.length > 0;
-    }
-    /**
-     * Extracts the value of this cookie from a `Cookie` header value.
-     * @param headerValue The value of the `Cookie` header to parse
-     * @returns The value of this cookie, or `null` if it's not present
-     */
-    async parse(headerValue) {
-        if (!headerValue)
-            return null;
-        let header = new CookieHeader(headerValue);
-        if (!header.has(this.name))
-            return null;
-        let value = header.get(this.name);
-        if (value === '')
-            return '';
-        let decoded = await decodeCookieValue(value, this.#secrets, this.#decode);
-        return decoded;
-    }
-    /**
-     * Returns the value to use in a `Set-Cookie` header for this cookie.
-     * @param value The value to serialize
-     * @param props (optional) Additional properties to use when serializing the cookie
-     * @returns The value to use in a `Set-Cookie` header for this cookie
-     */
-    async serialize(value, props) {
-        let header = new SetCookieHeader({
-            name: this.name,
-            value: value === '' ? '' : await encodeCookieValue(value, this.#secrets, this.#encode),
-            // sane defaults
-            path: '/',
-            sameSite: 'Lax',
-            ...this.#props,
-            ...props,
-        });
-        return header.toString();
+    let { decode = decodeURIComponent, encode = encodeURIComponent, secrets = [], domain, expires, httpOnly, maxAge, path = '/', partitioned, secure, sameSite = 'Lax', } = options ?? {};
+    if (partitioned === true) {
+        // Partitioned cookies must be set with Secure
+        // See https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies
+        secure = true;
     }
+    return {
+        get domain() {
+            return domain;
+        },
+        get expires() {
+            return expires;
+        },
+        get httpOnly() {
+            return httpOnly ?? false;
+        },
+        get maxAge() {
+            return maxAge;
+        },
+        get name() {
+            return name;
+        },
+        async parse(headerValue) {
+            if (!headerValue)
+                return null;
+            let header = new CookieHeader(headerValue);
+            if (!header.has(name))
+                return null;
+            let value = header.get(name);
+            if (value === '')
+                return '';
+            let decoded = await decodeCookieValue(value, secrets, decode);
+            return decoded;
+        },
+        get partitioned() {
+            return partitioned ?? false;
+        },
+        get path() {
+            return path;
+        },
+        get sameSite() {
+            return sameSite;
+        },
+        get secure() {
+            return secure ?? false;
+        },
+        async serialize(value, props) {
+            let header = new SetCookieHeader({
+                name: name,
+                value: value === '' ? '' : await encodeCookieValue(value, secrets, encode),
+                domain,
+                expires,
+                httpOnly,
+                maxAge,
+                partitioned,
+                path,
+                sameSite,
+                secure,
+                ...props,
+            });
+            return header.toString();
+        },
+        get signed() {
+            return secrets.length > 0;
+        },
+    };
 }
 async function decodeCookieValue(value, secrets, decode) {
     if (secrets.length > 0) {
@@ -123,9 +125,8 @@ function hex(code, length) {
 }
 async function encodeCookieValue(value, secrets, encode) {
     let encoded = encodeValue(value, encode);
-    if (secrets.length > 0) {
+    if (secrets.length > 0)
         encoded = await sign(encoded, secrets[0]);
-    }
     return encoded;
 }
 function encodeValue(value, encode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remix-run/cookie",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "A toolkit for working with cookies in JavaScript",
   "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
@@ -29,7 +29,7 @@
     "@types/node": "^24.6.0"
   },
   "peerDependencies": {
-    "@remix-run/headers": "^0.16.0"
+    "@remix-run/headers": "^0.17.0"
   },
   "keywords": [
     "http",

package/src/index.ts

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

package/src/lib/{crypto.ts → cookie-signing.ts}

@@ -11,14 +11,18 @@ export async function sign(value: string, secret: string): Promise<string> {
 
 export async function unsign(cookie: string, secret: string): Promise<string | false> {
   let index = cookie.lastIndexOf('.')
+
+  if (index === -1) {
+    return false
+  }
+
   let value = cookie.slice(0, index)
   let hash = cookie.slice(index + 1)
-
   let data = encoder.encode(value)
-
   let key = await createKey(secret, ['verify'])
+
   try {
-    let signature = byteStringToUint8Array(atob(hash))
+    let signature = byteStringToArray(atob(hash))
     let valid = await crypto.subtle.verify('HMAC', key, signature, data)
 
     return valid ? value : false
@@ -40,7 +44,7 @@ async function createKey(secret: string, usages: CryptoKey['usages']): Promise<C
   )
 }
 
-function byteStringToUint8Array(byteString: string): Uint8Array<ArrayBuffer> {
+function byteStringToArray(byteString: string): Uint8Array<ArrayBuffer> {
   let array = new Uint8Array(byteString.length)
 
   for (let i = 0; i < byteString.length; i++) {

package/src/lib/cookie.ts

@@ -4,16 +4,90 @@ import {
   type CookieProperties,
 } from '@remix-run/headers'
 
-import { sign, unsign } from './crypto.ts'
+import { sign, unsign } from './cookie-signing.ts'
+
+type SameSiteValue = 'Strict' | 'Lax' | 'None'
 
 /**
- * Creates a new `Cookie` object.
- * @param name The name of the cookie
- * @param options The options for the cookie
- * @returns A new cookie instance
+ * Represents a HTTP cookie.
+ *
+ * Supports parsing and serializing the cookie to/from `Cookie` and `Set-Cookie` headers.
+ *
+ * Also supports cryptographic signing of the cookie value to ensure it's not tampered with, and
+ * secret rotation to easily rotate secrets without breaking existing cookies.
  */
-export function createCookie(name: string, options?: CookieOptions): Cookie {
-  return new Cookie(name, options)
+export interface Cookie {
+  /**
+   * The domain of the cookie.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#domaindomain-value)
+   */
+  readonly domain: string | undefined
+  /**
+   * The expiration date of the cookie.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#expiresdate)
+   */
+  readonly expires: Date | undefined
+  /**
+   * True if the cookie is HTTP-only.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#httponly)
+   */
+  readonly httpOnly: boolean
+  /**
+   * The maximum age of the cookie in seconds.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#max-agenumber)
+   */
+  readonly maxAge: number | undefined
+  /**
+   * The name of the cookie.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#cookie-namecookie-value)
+   */
+  readonly name: string
+  /**
+   * Extracts the value of this cookie from a `Cookie` header value.
+   * @param headerValue The `Cookie` header to parse
+   * @returns The value of this cookie, or `null` if it's not present
+   */
+  parse(headerValue: string | null): Promise<string | null>
+  /**
+   * True if the cookie is partitioned.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#partitioned)
+   */
+  readonly partitioned: boolean
+  /**
+   * The path of the cookie. Defaults to `/`.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#pathpath-value)
+   */
+  readonly path: string
+  /**
+   * The `SameSite` attribute of the cookie. Defaults to `Lax`.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value)
+   */
+  readonly sameSite: SameSiteValue
+  /**
+   * True if the cookie is secure (only sent over HTTPS).
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#secure)
+   */
+  readonly secure: boolean
+  /**
+   * Returns the value to use in a `Set-Cookie` header for this cookie.
+   * @param value The value to serialize
+   * @param props (optional) Additional properties to use when serializing the cookie
+   * @returns The `Set-Cookie` header for this cookie
+   */
+  serialize(value: string, props?: CookieProperties): Promise<string>
+  /**
+   * True if this cookie uses one or more secrets for verification.
+   */
+  readonly signed: boolean
 }
 
 export interface CookieOptions extends CookieProperties {
@@ -47,85 +121,101 @@ export interface CookieOptions extends CookieProperties {
 }
 
 /**
- * A container for metadata about a HTTP cookie; its name and secrets that may be used
- * to sign/unsign the value of the cookie to ensure it's not tampered with.
+ * Creates a new cookie object.
+ * @param name The name of the cookie
+ * @param options (optional) Additional options for the cookie
+ * @returns A cookie object
  */
-export class Cookie {
-  constructor(name: string, options?: CookieOptions) {
-    let {
-      decode = decodeURIComponent,
-      encode = encodeURIComponent,
-      secrets = [],
-      ...props
-    } = options ?? {}
-
-    this.name = name
-    this.#decode = decode
-    this.#encode = encode
-    this.#secrets = secrets
-    this.#props = props
-  }
-
-  /**
-   * The name of the cookie.
-   */
-  readonly name: string
-
-  readonly #decode: (value: string) => string
-  readonly #encode: (value: string) => string
-  readonly #secrets: string[]
-  readonly #props: CookieProperties
+export function createCookie(name: string, options?: CookieOptions): Cookie {
+  let {
+    decode = decodeURIComponent,
+    encode = encodeURIComponent,
+    secrets = [],
+    domain,
+    expires,
+    httpOnly,
+    maxAge,
+    path = '/',
+    partitioned,
+    secure,
+    sameSite = 'Lax',
+  } = options ?? {}
 
-  /**
-   * True if this cookie uses one or more secrets for verification.
-   */
-  get signed(): boolean {
-    return this.#secrets.length > 0
+  if (partitioned === true) {
+    // Partitioned cookies must be set with Secure
+    // See https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies
+    secure = true
   }
 
-  /**
-   * Extracts the value of this cookie from a `Cookie` header value.
-   * @param headerValue The value of the `Cookie` header to parse
-   * @returns The value of this cookie, or `null` if it's not present
-   */
-  async parse(headerValue: string | null): Promise<string | null> {
-    if (!headerValue) return null
+  return {
+    get domain() {
+      return domain
+    },
+    get expires() {
+      return expires
+    },
+    get httpOnly() {
+      return httpOnly ?? false
+    },
+    get maxAge() {
+      return maxAge
+    },
+    get name() {
+      return name
+    },
+    async parse(headerValue: string | null): Promise<string | null> {
+      if (!headerValue) return null
 
-    let header = new CookieHeader(headerValue)
-    if (!header.has(this.name)) return null
+      let header = new CookieHeader(headerValue)
+      if (!header.has(name)) return null
 
-    let value = header.get(this.name)!
-    if (value === '') return ''
+      let value = header.get(name)!
+      if (value === '') return ''
 
-    let decoded = await decodeCookieValue(value, this.#secrets, this.#decode)
-    return decoded
-  }
+      let decoded = await decodeCookieValue(value, secrets, decode)
+      return decoded
+    },
+    get partitioned() {
+      return partitioned ?? false
+    },
+    get path() {
+      return path
+    },
+    get sameSite() {
+      return sameSite
+    },
+    get secure() {
+      return secure ?? false
+    },
+    async serialize(value: string, props?: CookieProperties): Promise<string> {
+      let header = new SetCookieHeader({
+        name: name,
+        value: value === '' ? '' : await encodeCookieValue(value, secrets, encode),
+        domain,
+        expires,
+        httpOnly,
+        maxAge,
+        partitioned,
+        path,
+        sameSite,
+        secure,
+        ...props,
+      })
 
-  /**
-   * Returns the value to use in a `Set-Cookie` header for this cookie.
-   * @param value The value to serialize
-   * @param props (optional) Additional properties to use when serializing the cookie
-   * @returns The value to use in a `Set-Cookie` header for this cookie
-   */
-  async serialize(value: string, props?: CookieProperties): Promise<string> {
-    let header = new SetCookieHeader({
-      name: this.name,
-      value: value === '' ? '' : await encodeCookieValue(value, this.#secrets, this.#encode),
-      // sane defaults
-      path: '/',
-      sameSite: 'Lax',
-      ...this.#props,
-      ...props,
-    })
-
-    return header.toString()
+      return header.toString()
+    },
+    get signed() {
+      return secrets.length > 0
+    },
   }
 }
 
+type Coder = (value: string) => string
+
 async function decodeCookieValue(
   value: string,
   secrets: string[],
-  decode: (value: string) => string,
+  decode: Coder,
 ): Promise<string | null> {
   if (secrets.length > 0) {
     for (let secret of secrets) {
@@ -141,7 +231,7 @@ async function decodeCookieValue(
   return decodeValue(value, decode)
 }
 
-function decodeValue(value: string, decode: (value: string) => string): string | null {
+function decodeValue(value: string, decode: Coder): string | null {
   try {
     return decode(myEscape(atob(value)))
   } catch {
@@ -177,21 +267,13 @@ function hex(code: number, length: number): string {
   return result
 }
 
-async function encodeCookieValue(
-  value: string,
-  secrets: string[],
-  encode: (value: string) => string,
-): Promise<string> {
+async function encodeCookieValue(value: string, secrets: string[], encode: Coder): Promise<string> {
   let encoded = encodeValue(value, encode)
-
-  if (secrets.length > 0) {
-    encoded = await sign(encoded, secrets[0])
-  }
-
+  if (secrets.length > 0) encoded = await sign(encoded, secrets[0])
   return encoded
 }
 
-function encodeValue(value: string, encode: (value: string) => string): string {
+function encodeValue(value: string, encode: Coder): string {
   return btoa(myUnescape(encode(value)))
 }
 

package/dist/lib/crypto.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/lib/crypto.ts"],"names":[],"mappings":"AAEA,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOzE;AAED,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,CAmBpF"}