@mks2508/binary-cookies-parser 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MKS2508
+
+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,261 @@
+# binary-cookies-parser 🍪
+
+[![npm version](https://img.shields.io/npm/v/@mks2508/binary-cookies-parser.svg)](https://www.npmjs.com/package/@mks2508/binary-cookies-parser)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-1.0+-f472b6.svg)](https://bun.sh)
+
+A modern, TypeScript-native parser for macOS binary cookies files (`.binarycookies`). Parse Safari and macOS app cookies with full type safety and zero dependencies.
+
+## Features
+
+-  **Zero Dependencies** - Pure TypeScript implementation
+-  **Dual Package** - ESM and CommonJS support
+-  **Fast** - Built with Bun, works with Node.js
+- **macOS Native** - Handles Safari and native app cookies
+-  **Simple API** - One function to parse cookies
+
+## Installation
+
+```bash
+# npm
+npm install binary-cookies-parser
+
+# bun
+bun add binary-cookies-parser
+
+# yarn
+yarn add binary-cookies-parser
+
+# pnpm
+pnpm add binary-cookies-parser
+```
+
+## Usage
+
+### Basic Parsing
+
+```typescript
+import { parseBinaryCookies } from 'binary-cookies-parser';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// Parse Safari cookies
+const safariCookies = await parseBinaryCookies(
+  join(homedir(), 'Library/Cookies/Cookies.binarycookies')
+);
+
+// Each cookie has:
+// - name: string
+// - value: string
+// - url: string (domain)
+// - path: string
+// - flags: number (0=none, 1=secure, 4=httpOnly, 5=both)
+// - expiration: Date
+// - creation: Date
+```
+
+### Filtering Cookies
+
+```typescript
+// Filter by domain
+const googleCookies = cookies.filter(c => c.url.includes('google.com'));
+
+// Filter by secure flag
+const secureCookies = cookies.filter(c => c.flags & 1);
+
+// Filter by expiration
+const validCookies = cookies.filter(c => c.expiration > new Date());
+```
+
+### Converting to Playwright Format
+
+```typescript
+const playwrightCookies = cookies.map(c => ({
+  name: c.name,
+  value: c.value,
+  domain: c.url,
+  path: c.path,
+  expires: Math.floor(c.expiration.getTime() / 1000),
+  httpOnly: !!(c.flags & 4),
+  secure: !!(c.flags & 1),
+  sameSite: 'Lax' as const
+}));
+
+// Use with Playwright
+await context.addCookies(playwrightCookies);
+```
+
+### Using the Class API
+
+```typescript
+import { BinaryCookiesParser } from 'binary-cookies-parser';
+
+const parser = new BinaryCookiesParser();
+const cookies = await parser.parse('/path/to/Cookies.binarycookies');
+```
+
+## API Reference
+
+### `parseBinaryCookies(cookiePath: string): Promise<BinaryCookie[]>`
+
+Parses a binary cookies file and returns an array of cookies.
+
+**Parameters:**
+- `cookiePath` - Absolute path to the `.binarycookies` file
+
+**Returns:**
+- `Promise<BinaryCookie[]>` - Array of parsed cookies
+
+**Throws:**
+- `Error` if file doesn't exist
+- `Error` if file format is invalid
+
+### `BinaryCookie` Interface
+
+```typescript
+interface BinaryCookie {
+  name: string;        // Cookie name
+  value: string;       // Cookie value
+  url: string;         // Domain (e.g., ".apple.com")
+  path: string;        // Path (e.g., "/")
+  flags: number;       // Flags (0=none, 1=secure, 4=httpOnly, 5=both)
+  expiration: Date;    // Expiration date
+  creation: Date;      // Creation date
+}
+```
+
+### Cookie Flags
+
+| Flag | Meaning |
+|------|---------|
+| 0 | No flags |
+| 1 | Secure cookie |
+| 4 | HttpOnly cookie |
+| 5 | Secure + HttpOnly |
+
+## Common Use Cases
+
+### Extract Safari Cookies for Automation
+
+```typescript
+import { parseBinaryCookies } from 'binary-cookies-parser';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const cookies = await parseBinaryCookies(
+  join(homedir(), 'Library/Cookies/Cookies.binarycookies')
+);
+
+// Use with Puppeteer, Playwright, etc.
+```
+
+### Parse macOS App Cookies
+
+```typescript
+import { parseBinaryCookies } from 'binary-cookies-parser';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// Example: Amazon Prime Video app
+const primeCookies = await parseBinaryCookies(
+  join(
+    homedir(),
+    'Library/Containers/com.amazon.aiv.AIVApp/Data/Library/Cookies/Cookies.binarycookies'
+  )
+);
+```
+
+### Cookie Migration
+
+```typescript
+// Export cookies from Safari
+const cookies = await parseBinaryCookies('/path/to/safari/cookies');
+
+// Convert to JSON for backup
+await Bun.write('cookies-backup.json', JSON.stringify(cookies, null, 2));
+
+// Filter and import to another browser
+const importCookies = cookies.filter(c =>
+  c.url.includes('important-domain.com')
+);
+```
+
+## Platform Support
+
+- **macOS** - ✅ Full support (Safari, native apps)
+- **Linux** - ❌ Not applicable (no .binarycookies files)
+- **Windows** - ❌ Not applicable (no .binarycookies files)
+
+This library is specifically for parsing macOS binary cookies files. For cross-platform cookie management, consider using browser automation tools.
+
+## Examples
+
+See the [`examples/`](./examples) directory for complete working examples:
+
+- [`basic-usage.ts`](./examples/basic-usage.ts) - Parse Safari cookies and convert to Playwright format
+
+Run examples:
+
+```bash
+bun run examples/basic-usage.ts
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Build for npm
+bun run build
+
+# Generate types
+bun run types
+```
+
+## Technical Details
+
+### Binary Format
+
+The `.binarycookies` format is a proprietary Apple format used by Safari and macOS applications. This parser implements the complete specification:
+
+- File header validation (`cook` magic bytes)
+- Multi-page cookie storage
+- Mac epoch time conversion (978307200 offset)
+- Cookie flag parsing
+- Null-terminated string extraction
+
+### Performance
+
+- Zero external dependencies
+- Single-pass parsing
+- Efficient buffer operations
+- Minimal memory allocations
+
+## Credits
+
+Inspired by the original [node-binary-cookies](https://github.com/jlipps/node-binary-cookies) by Jonathan Lipps, but completely rewritten in modern TypeScript with:
+
+- Full type safety
+- Async/await API
+- Zero dependencies
+- Dual ESM/CJS support
+- Bun optimization
+
+## License
+
+MIT © 2025 MKS2508
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Links
+
+- [npm package](https://www.npmjs.com/package/@mks2508/binary-cookies-parser)
+- [GitHub repository](https://github.com/mks2508/binary-cookies-parser)
+- [Issue tracker](https://github.com/mks2508/binary-cookies-parser/issues)

package/dist/cjs/index.js

@@ -0,0 +1 @@
+var D=Object.create;var{getPrototypeOf:O,defineProperty:M,getOwnPropertyNames:Z,getOwnPropertyDescriptor:S}=Object,_=Object.prototype.hasOwnProperty;var B=(E,q,F)=>{F=E!=null?D(O(E)):{};let G=q||!E||!E.__esModule?M(F,"default",{value:E,enumerable:!0}):F;for(let L of Z(E))if(!_.call(G,L))M(G,L,{get:()=>E[L],enumerable:!0});return G},Y=new WeakMap,m=(E)=>{var q=Y.get(E),F;if(q)return q;if(q=M({},"__esModule",{value:!0}),E&&typeof E==="object"||typeof E==="function")Z(E).map((G)=>!_.call(q,G)&&M(q,G,{get:()=>E[G],enumerable:!(F=S(E,G))||F.enumerable}));return Y.set(E,q),q};var C=(E,q)=>{for(var F in q)M(E,F,{get:q[F],enumerable:!0,configurable:!0,set:(G)=>q[F]=()=>G})};var x={};C(x,{parseBinaryCookies:()=>I,BinaryCookiesParser:()=>U});module.exports=m(x);var $=B(require("node:fs/promises")),w=require("node:fs");class U{cookiePath=null;currentBufferPosition=0;data=null;numPages=0;bufferSize=0;pages=[];pageSizes=[];cookies=[];async parse(E){if(this.reset(),this.cookiePath=E,!w.existsSync(E))throw Error(`Cookie file not found: ${E}`);await this.openFile(),this.getNumPages(),this.getPageSizes(),this.getPages();for(let q=0;q<this.pages.length;q++){this.getNumCookies(q),this.getCookieOffsets(q),this.getCookieData(q);for(let F=0;F<this.pages[q].cookies.length;F++){let G=this.parseCookieData(q,F);this.cookies.push(G)}}return this.cookies}reset(){this.cookiePath=null,this.currentBufferPosition=0,this.data=null,this.numPages=0,this.bufferSize=0,this.pages=[],this.pageSizes=[],this.cookies=[]}async openFile(){if(!this.cookiePath)throw Error("Cookie path not set");let E=await $.default.readFile(this.cookiePath);if(this.data=E,this.bufferSize=E.length,this.readSlice(4).toString()!=="cook")throw Error('Invalid binary cookies file format (missing "cook" header)')}readSlice(E){if(!this.data)throw Error("No data loaded");let q=this.data.subarray(this.currentBufferPosition,this.currentBufferPosition+E);return this.currentBufferPosition+=E,q}readIntBE(){if(!this.data)throw Error("No data loaded");let E=this.data.readInt32BE(this.currentBufferPosition);return this.currentBufferPosition+=4,E}readIntLE(){if(!this.data)throw Error("No data loaded");let E=this.data.readInt32LE(this.currentBufferPosition);return this.currentBufferPosition+=4,E}getNumPages(){return this.numPages=this.readIntBE(),this.numPages}getPageSizes(){for(let E=0;E<this.numPages;E++)this.pageSizes.push(this.readIntBE());return this.pageSizes}getPages(){for(let E of this.pageSizes)this.pages.push({buffer:this.readSlice(E),bufferPosition:0,numCookies:0,cookieOffsets:[],cookies:[]});return this.pages}getNumCookies(E){let q=this.pages[E];q.bufferPosition=0;let F=q.buffer.readInt32BE(q.bufferPosition);if(q.bufferPosition+=4,F!==256)throw Error(`Invalid page header: expected 256, got ${F}`);return q.numCookies=q.buffer.readInt32LE(q.bufferPosition),q.bufferPosition+=4,q.numCookies}getCookieOffsets(E){let q=this.pages[E];q.cookieOffsets=[];for(let F=0;F<q.numCookies;F++)q.cookieOffsets.push(q.buffer.readInt32LE(q.bufferPosition)),q.bufferPosition+=4;return q.cookieOffsets}getCookieData(E){let q=this.pages[E];q.cookies=[];for(let F of q.cookieOffsets){let G=q.buffer.readInt32LE(F);try{q.cookies.push({buffer:q.buffer.subarray(F,F+G)})}catch{q.cookies.push({buffer:q.buffer.subarray(F)})}}return q.cookies}parseCookieData(E,q){let L=this.pages[E].cookies[q].buffer,y=978307200,J=0,l=L.readInt32LE(J);J+=4;let K=L.readInt32LE(J);J+=8;let d=L.readUInt32LE(J),V={},z=["url","name","path","value"];for(let N of z)J+=4,V[N]=L.readInt32LE(J);J+=4;let h=L.readUInt32LE(J);J+=8;let A=L.readDoubleLE(J)+978307200,H=new Date(A*1000);J+=8;let T=L.readDoubleLE(J)+978307200,j=new Date(T*1000),W={flags:K,expiration:H,creation:j};for(let[N,v]of Object.entries(V)){let X="",Q=v,R="";do R=L.toString("utf8",Q,Q+1),X+=R,Q++;while(R!=="\x00");W[N]=X.replace(/\u0000/g,"").trim()}return W}}async function I(E){return new U().parse(E)}

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import type { BinaryCookie } from './types';
+export type { BinaryCookie, CookiePage } from './types';
+/**
+ * Parser for macOS binary cookies files (.binarycookies)
+ *
+ * These files are used by Safari and other macOS applications to store cookies
+ * in a binary format that's more efficient than plain text.
+ *
+ * @example
+ * ```typescript
+ * import { BinaryCookiesParser } from 'binary-cookies-parser';
+ *
+ * const parser = new BinaryCookiesParser();
+ * const cookies = await parser.parse('/path/to/Cookies.binarycookies');
+ * console.log(cookies);
+ * ```
+ */
+export declare class BinaryCookiesParser {
+    private cookiePath;
+    private currentBufferPosition;
+    private data;
+    private numPages;
+    private bufferSize;
+    private pages;
+    private pageSizes;
+    private cookies;
+    /**
+     * Parse a binary cookies file and return an array of cookies
+     *
+     * @param cookiePath - Absolute path to the .binarycookies file
+     * @returns Array of parsed cookies
+     * @throws {Error} If file doesn't exist or has invalid format
+     *
+     * @example
+     * ```typescript
+     * const parser = new BinaryCookiesParser();
+     * const cookies = await parser.parse('/Users/user/Library/Cookies/Cookies.binarycookies');
+     * ```
+     */
+    parse(cookiePath: string): Promise<BinaryCookie[]>;
+    private reset;
+    private openFile;
+    private readSlice;
+    private readIntBE;
+    private readIntLE;
+    private getNumPages;
+    private getPageSizes;
+    private getPages;
+    private getNumCookies;
+    private getCookieOffsets;
+    private getCookieData;
+    private parseCookieData;
+}
+/**
+ * Convenience function to parse a binary cookies file
+ *
+ * @param cookiePath - Absolute path to the .binarycookies file
+ * @returns Array of parsed cookies
+ *
+ * @example
+ * ```typescript
+ * import { parseBinaryCookies } from 'binary-cookies-parser';
+ *
+ * const cookies = await parseBinaryCookies('/path/to/Cookies.binarycookies');
+ * console.log(cookies);
+ * ```
+ */
+export declare function parseBinaryCookies(cookiePath: string): Promise<BinaryCookie[]>;

package/dist/index.js

@@ -0,0 +1 @@
+import z from"node:fs/promises";import{existsSync as A}from"node:fs";class W{cookiePath=null;currentBufferPosition=0;data=null;numPages=0;bufferSize=0;pages=[];pageSizes=[];cookies=[];async parse(E){if(this.reset(),this.cookiePath=E,!A(E))throw Error(`Cookie file not found: ${E}`);await this.openFile(),this.getNumPages(),this.getPageSizes(),this.getPages();for(let q=0;q<this.pages.length;q++){this.getNumCookies(q),this.getCookieOffsets(q),this.getCookieData(q);for(let F=0;F<this.pages[q].cookies.length;F++){let L=this.parseCookieData(q,F);this.cookies.push(L)}}return this.cookies}reset(){this.cookiePath=null,this.currentBufferPosition=0,this.data=null,this.numPages=0,this.bufferSize=0,this.pages=[],this.pageSizes=[],this.cookies=[]}async openFile(){if(!this.cookiePath)throw Error("Cookie path not set");let E=await z.readFile(this.cookiePath);if(this.data=E,this.bufferSize=E.length,this.readSlice(4).toString()!=="cook")throw Error('Invalid binary cookies file format (missing "cook" header)')}readSlice(E){if(!this.data)throw Error("No data loaded");let q=this.data.subarray(this.currentBufferPosition,this.currentBufferPosition+E);return this.currentBufferPosition+=E,q}readIntBE(){if(!this.data)throw Error("No data loaded");let E=this.data.readInt32BE(this.currentBufferPosition);return this.currentBufferPosition+=4,E}readIntLE(){if(!this.data)throw Error("No data loaded");let E=this.data.readInt32LE(this.currentBufferPosition);return this.currentBufferPosition+=4,E}getNumPages(){return this.numPages=this.readIntBE(),this.numPages}getPageSizes(){for(let E=0;E<this.numPages;E++)this.pageSizes.push(this.readIntBE());return this.pageSizes}getPages(){for(let E of this.pageSizes)this.pages.push({buffer:this.readSlice(E),bufferPosition:0,numCookies:0,cookieOffsets:[],cookies:[]});return this.pages}getNumCookies(E){let q=this.pages[E];q.bufferPosition=0;let F=q.buffer.readInt32BE(q.bufferPosition);if(q.bufferPosition+=4,F!==256)throw Error(`Invalid page header: expected 256, got ${F}`);return q.numCookies=q.buffer.readInt32LE(q.bufferPosition),q.bufferPosition+=4,q.numCookies}getCookieOffsets(E){let q=this.pages[E];q.cookieOffsets=[];for(let F=0;F<q.numCookies;F++)q.cookieOffsets.push(q.buffer.readInt32LE(q.bufferPosition)),q.bufferPosition+=4;return q.cookieOffsets}getCookieData(E){let q=this.pages[E];q.cookies=[];for(let F of q.cookieOffsets){let L=q.buffer.readInt32LE(F);try{q.cookies.push({buffer:q.buffer.subarray(F,F+L)})}catch{q.cookies.push({buffer:q.buffer.subarray(F)})}}return q.cookies}parseCookieData(E,q){let J=this.pages[E].cookies[q].buffer,H=978307200,G=0,T=J.readInt32LE(G);G+=4;let X=J.readInt32LE(G);G+=8;let j=J.readUInt32LE(G),R={},Y=["url","name","path","value"];for(let M of Y)G+=4,R[M]=J.readInt32LE(G);G+=4;let v=J.readUInt32LE(G);G+=8;let Z=J.readDoubleLE(G)+978307200,_=new Date(Z*1000);G+=8;let $=J.readDoubleLE(G)+978307200,w=new Date($*1000),U={flags:X,expiration:_,creation:w};for(let[M,K]of Object.entries(R)){let V="",N=K,Q="";do Q=J.toString("utf8",N,N+1),V+=Q,N++;while(Q!=="\x00");U[M]=V.replace(/\u0000/g,"").trim()}return U}}async function S(E){return new W().parse(E)}export{S as parseBinaryCookies,W as BinaryCookiesParser};

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Represents a parsed binary cookie from macOS .binarycookies file
+ */
+export interface BinaryCookie {
+    /** Cookie name */
+    name: string;
+    /** Cookie value */
+    value: string;
+    /** Domain the cookie belongs to (e.g., ".apple.com") */
+    url: string;
+    /** Cookie path (e.g., "/") */
+    path: string;
+    /** Cookie flags (0=none, 1=secure, 4=httpOnly, 5=both) */
+    flags: number;
+    /** Cookie expiration date */
+    expiration: Date;
+    /** Cookie creation date */
+    creation: Date;
+}
+/**
+ * Internal representation of a cookie page
+ * @internal
+ */
+export interface CookiePage {
+    buffer: Buffer;
+    bufferPosition: number;
+    numCookies: number;
+    cookieOffsets: number[];
+    cookies: Array<{
+        buffer: Buffer;
+        data?: BinaryCookie;
+    }>;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@mks2508/binary-cookies-parser",
+  "version": "1.0.0",
+  "description": "Modern TypeScript parser for macOS binary cookies files (.binarycookies). Parse Safari and app cookies with zero dependencies.",
+  "author": "MKS2508",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cookies",
+    "binarycookies",
+    "safari",
+    "macos",
+    "parser",
+    "typescript",
+    "playwright",
+    "puppeteer",
+    "automation",
+    "binary",
+    "cookie-parser",
+    "apple"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mks2508/binary-cookies-parser.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mks2508/binary-cookies-parser/issues"
+  },
+  "homepage": "https://github.com/mks2508/binary-cookies-parser#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --format esm --target node --minify --external '*' && bun build ./src/index.ts --outdir ./dist/cjs --format cjs --target node --minify --external '*'",
+    "types": "tsc --project tsconfig.build.json",
+    "prepublishOnly": "bun run build && bun run types",
+    "test": "bun test",
+    "example": "bun run examples/basic-usage.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  }
+}