@effing/serde 0.1.0

package/LICENSE

@@ -0,0 +1,11 @@
+O'Saasy License
+
+Copyright © 2026, Trackuity BV.
+
+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:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+2. No licensee or downstream recipient may use the Software (including any modified or derivative versions) to directly compete with the original Licensor by offering it to third parties as a hosted, managed, or Software-as-a-Service (SaaS) product or cloud service where the primary value of the service is the functionality of the Software itself.
+
+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,142 @@
+# @effing/serde
+
+**URL-safe serialization with compression and HMAC signing.**
+
+> Part of the [**Effing**](../../README.md) family — programmatic video creation with TypeScript.
+
+Serialize JSON data into URL-safe strings with automatic compression and cryptographic signing. Compatible with Python's [itsdangerous](https://itsdangerous.palletsprojects.com/).
+
+## Installation
+
+```bash
+npm install @effing/serde
+```
+
+## Quick Start
+
+```typescript
+import { serialize, deserialize } from "@effing/serde";
+
+const secret = process.env.SECRET_KEY!;
+const data = { userId: 123, action: "view" };
+
+// Signed (and sometimes compressed) URL segment
+const segment = await serialize(data, secret);
+
+// Verify signature (and decompress if needed)
+const restored = await deserialize<typeof data>(segment, secret);
+```
+
+## Concepts
+
+### URL-Safe Base64
+
+Standard Base64 uses `+` and `/` which have special meaning in URLs. This package uses URL-safe Base64:
+
+- `+` → `-`
+- `/` → `_`
+- No padding (`=`)
+
+### Signed Serialization
+
+Serialization is signed with HMAC (default: `sha1`) so the result can safely be used in a URL without being tampered with:
+
+```typescript
+// Server: create signed URL segment
+const segment = await serialize(data, secret);
+
+// Client: passes segment in URL
+// Server: verify and deserialize
+const data = await deserialize(segment, secret);
+// Throws if signature is invalid.
+```
+
+### Compression
+
+Payloads are gzip-compressed when it saves space. Compressed payloads are prefixed with a leading `"."` (matching `itsdangerous`).
+
+## API Overview
+
+#### `serialize(obj, secretKey, options?)`
+
+Serialize a value to a URL-safe string.
+
+```typescript
+function serialize(
+  obj: object,
+  secretKey: string,
+  options?: {
+    /** Salt for key derivation (default: "itsdangerous") */
+    salt?: string;
+    /** Hash algorithm for HMAC (default: "sha1") */
+    algorithm?: string;
+  },
+): Promise<string>;
+```
+
+#### `deserialize(segment, secretKey, options?)`
+
+Deserialize a URL segment back to a value.
+
+```typescript
+function deserialize<T = Record<string, unknown>>(
+  segment: string,
+  secretKey: string,
+  options?: {
+    /** Salt for key derivation (default: "itsdangerous") */
+    salt?: string;
+    /** Hash algorithm for HMAC (default: "sha1") */
+    algorithm?: string;
+    /** Convert snake_case keys to camelCase (default: true) */
+    convertKeysToCamel?: boolean;
+  },
+): Promise<T>;
+```
+
+**Throws:**
+
+- `Error` — If signature verification fails
+
+## Examples
+
+### Passing Props in URLs
+
+```typescript
+import { serialize, deserialize } from "@effing/serde";
+
+// Create URL with serialized props
+const secret = process.env.SECRET_KEY!;
+const props = { imageUrl: "https://example.com/image.png", duration: 5 };
+const segment = await serialize(props, secret);
+const url = `/render/${segment}`;
+
+// In route handler
+async function loader({ params }) {
+  const props = await deserialize(params.segment, secret);
+  // props = { imageUrl: "https://example.com/image.png", duration: 5 }
+}
+```
+
+> **Note:** The `convertKeysToCamel` deserialization option (which is `true` by default) is useful when URLs are built in Python (with itsdangerous) and then consumed by Effing. Python typically uses `snake_case` keys, while TypeScript prefers `camelCase`.
+
+### Secure Tokens
+
+```typescript
+const SECRET = process.env.TOKEN_SECRET!;
+
+// Create signed token
+async function createToken(userId: number, expiresAt: number) {
+  return serialize({ userId, expiresAt }, SECRET);
+}
+
+// Verify token
+async function verifyToken(token: string) {
+  try {
+    const { userId, expiresAt } = await deserialize(token, SECRET);
+    if (Date.now() > expiresAt) throw new Error("Token expired");
+    return userId;
+  } catch (e) {
+    throw new Error("Invalid token");
+  }
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+interface SerializeOptions {
+    /** Salt for key derivation (default: "itsdangerous") */
+    salt?: string;
+    /** Hash algorithm for HMAC (default: "sha1") */
+    algorithm?: string;
+}
+/**
+ * Serialize an object to a URL-safe segment with optional compression and HMAC signature.
+ *
+ * The format is compatible with Python's itsdangerous library.
+ * - If compression saves space, the payload is prefixed with "."
+ * - The signature is appended after a "." separator
+ */
+declare function serialize(obj: object, secretKey: string, options?: SerializeOptions): Promise<string>;
+interface DeserializeOptions extends SerializeOptions {
+    /** Whether to convert snake_case keys to camelCase (default: true) */
+    convertKeysToCamel?: boolean;
+}
+/**
+ * Deserialize a URL segment, verify its signature, and decompress if needed.
+ *
+ * Throws an error if the signature is invalid.
+ */
+declare function deserialize<T = Record<string, unknown>>(segment: string, secretKey: string, options?: DeserializeOptions): Promise<T>;
+
+export { type DeserializeOptions, type SerializeOptions, deserialize, serialize };

package/dist/index.js

@@ -0,0 +1,83 @@
+// src/itsdangerous.ts
+import zlib from "zlib";
+import { promisify } from "util";
+import { createHash, createHmac } from "crypto";
+var zip = promisify(zlib.gzip);
+var unzip = promisify(zlib.unzip);
+function urlsafeBase64Encode(data, unsafeCharsMapping = { "+": "-", "/": "_" }) {
+  return Buffer.from(data).toString("base64").replace(/[+/]/g, (m) => unsafeCharsMapping[m]);
+}
+function urlsafeBase64Decode(encoded, unsafeCharsMapping = { "-": "+", _: "/" }) {
+  return Buffer.from(
+    encoded.replace(/[-_]/g, (m) => unsafeCharsMapping[m]),
+    "base64"
+  );
+}
+function deriveSigningKey(secretKey, salt, algorithm) {
+  return createHash(algorithm).update(`${salt}signer${secretKey}`).digest();
+}
+function keysToCamel(obj) {
+  const newObj = {};
+  Object.keys(obj).forEach((key) => {
+    const camelKey = key.replace(
+      /(_[a-z])/gi,
+      (s) => s.toUpperCase().replace("_", "")
+    );
+    newObj[camelKey] = obj[key];
+  });
+  return newObj;
+}
+async function serialize(obj, secretKey, options = {}) {
+  const { salt = "itsdangerous", algorithm = "sha1" } = options;
+  let json = Buffer.from(JSON.stringify(obj));
+  const compressed = await zip(json);
+  let isCompressed = false;
+  if (compressed.length < json.length - 1) {
+    json = compressed;
+    isCompressed = true;
+  }
+  let encoded = urlsafeBase64Encode(json);
+  if (isCompressed) {
+    encoded = `.${encoded}`;
+  }
+  const derivedKey = deriveSigningKey(secretKey, salt, algorithm);
+  const hmac = createHmac(algorithm, derivedKey).update(encoded).digest();
+  return `${encoded}.${urlsafeBase64Encode(hmac)}`;
+}
+async function deserialize(segment, secretKey, options = {}) {
+  const {
+    salt = "itsdangerous",
+    algorithm = "sha1",
+    convertKeysToCamel = true
+  } = options;
+  const parts = segment.split(".");
+  const signature = parts.at(-1);
+  let payload = parts.slice(0, -1).join(".");
+  const derivedKey = deriveSigningKey(secretKey, salt, algorithm);
+  const hmac = createHmac(algorithm, derivedKey).update(payload).digest();
+  if (Buffer.compare(urlsafeBase64Decode(signature), hmac) !== 0) {
+    throw new Error("invalid url segment signature");
+  }
+  let decompress = false;
+  if (payload.startsWith(".")) {
+    decompress = true;
+    payload = payload.slice(1);
+  }
+  const decoded = urlsafeBase64Decode(payload);
+  let parsed;
+  if (decompress) {
+    const decompressed = await unzip(decoded);
+    parsed = JSON.parse(decompressed.toString());
+  } else {
+    parsed = JSON.parse(decoded.toString());
+  }
+  if (convertKeysToCamel) {
+    return keysToCamel(parsed);
+  }
+  return parsed;
+}
+export {
+  deserialize,
+  serialize
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/itsdangerous.ts"],"sourcesContent":["/**\n * TypeScript implementation of itsdangerous serialization logic.\n * @see https://github.com/pallets/itsdangerous/\n */\n\nimport zlib from \"node:zlib\";\nimport { promisify } from \"node:util\";\nimport { createHash, createHmac } from \"node:crypto\";\n\nconst zip = promisify(zlib.gzip);\nconst unzip = promisify(zlib.unzip);\n\n/**\n * Encode data as URL-safe base64.\n * Replaces + with - and / with _ by default.\n */\nexport function urlsafeBase64Encode(\n  data: string | Buffer,\n  unsafeCharsMapping: Record<string, string> = { \"+\": \"-\", \"/\": \"_\" },\n): string {\n  return Buffer.from(data)\n    .toString(\"base64\")\n    .replace(/[+/]/g, (m) => unsafeCharsMapping[m]);\n}\n\n/**\n * Decode URL-safe base64 data.\n * Replaces - with + and _ with / by default.\n */\nexport function urlsafeBase64Decode(\n  encoded: string,\n  unsafeCharsMapping: Record<string, string> = { \"-\": \"+\", _: \"/\" },\n): Buffer {\n  return Buffer.from(\n    encoded.replace(/[-_]/g, (m) => unsafeCharsMapping[m]),\n    \"base64\",\n  );\n}\n\n/**\n * Derive an HMAC signing key using the itsdangerous-compatible format.\n */\nfunction deriveSigningKey(\n  secretKey: string,\n  salt: string,\n  algorithm: string,\n): Buffer {\n  return createHash(algorithm).update(`${salt}signer${secretKey}`).digest();\n}\n\n/**\n * Convert snake_case keys to camelCase.\n */\nfunction keysToCamel<T extends Record<string, unknown>>(\n  obj: T,\n): Record<string, unknown> {\n  const newObj: Record<string, unknown> = {};\n  Object.keys(obj).forEach((key) => {\n    const camelKey = key.replace(/(_[a-z])/gi, (s) =>\n      s.toUpperCase().replace(\"_\", \"\"),\n    );\n    newObj[camelKey] = obj[key];\n  });\n  return newObj;\n}\n\nexport interface SerializeOptions {\n  /** Salt for key derivation (default: \"itsdangerous\") */\n  salt?: string;\n  /** Hash algorithm for HMAC (default: \"sha1\") */\n  algorithm?: string;\n}\n\n/**\n * Serialize an object to a URL-safe segment with optional compression and HMAC signature.\n *\n * The format is compatible with Python's itsdangerous library.\n * - If compression saves space, the payload is prefixed with \".\"\n * - The signature is appended after a \".\" separator\n */\nexport async function serialize(\n  obj: object,\n  secretKey: string,\n  options: SerializeOptions = {},\n): Promise<string> {\n  const { salt = \"itsdangerous\", algorithm = \"sha1\" } = options;\n\n  let json = Buffer.from(JSON.stringify(obj));\n  const compressed = await zip(json);\n\n  let isCompressed = false;\n  if (compressed.length < json.length - 1) {\n    json = compressed;\n    isCompressed = true;\n  }\n\n  let encoded = urlsafeBase64Encode(json);\n  if (isCompressed) {\n    encoded = `.${encoded}`;\n  }\n\n  const derivedKey = deriveSigningKey(secretKey, salt, algorithm);\n  const hmac = createHmac(algorithm, derivedKey).update(encoded).digest();\n  return `${encoded}.${urlsafeBase64Encode(hmac)}`;\n}\n\nexport interface DeserializeOptions extends SerializeOptions {\n  /** Whether to convert snake_case keys to camelCase (default: true) */\n  convertKeysToCamel?: boolean;\n}\n\n/**\n * Deserialize a URL segment, verify its signature, and decompress if needed.\n *\n * Throws an error if the signature is invalid.\n */\nexport async function deserialize<T = Record<string, unknown>>(\n  segment: string,\n  secretKey: string,\n  options: DeserializeOptions = {},\n): Promise<T> {\n  const {\n    salt = \"itsdangerous\",\n    algorithm = \"sha1\",\n    convertKeysToCamel = true,\n  } = options;\n\n  const parts = segment.split(\".\");\n  const signature = parts.at(-1);\n  let payload = parts.slice(0, -1).join(\".\");\n\n  const derivedKey = deriveSigningKey(secretKey, salt, algorithm);\n  const hmac = createHmac(algorithm, derivedKey).update(payload).digest();\n  if (Buffer.compare(urlsafeBase64Decode(signature!), hmac) !== 0) {\n    throw new Error(\"invalid url segment signature\");\n  }\n\n  let decompress = false;\n  if (payload.startsWith(\".\")) {\n    decompress = true;\n    payload = payload.slice(1);\n  }\n\n  const decoded = urlsafeBase64Decode(payload);\n  let parsed: Record<string, unknown>;\n\n  if (decompress) {\n    const decompressed = await unzip(decoded);\n    parsed = JSON.parse(decompressed.toString()) as Record<string, unknown>;\n  } else {\n    parsed = JSON.parse(decoded.toString()) as Record<string, unknown>;\n  }\n\n  if (convertKeysToCamel) {\n    return keysToCamel(parsed) as T;\n  }\n  return parsed as T;\n}\n"],"mappings":";AAKA,OAAO,UAAU;AACjB,SAAS,iBAAiB;AAC1B,SAAS,YAAY,kBAAkB;AAEvC,IAAM,MAAM,UAAU,KAAK,IAAI;AAC/B,IAAM,QAAQ,UAAU,KAAK,KAAK;AAM3B,SAAS,oBACd,MACA,qBAA6C,EAAE,KAAK,KAAK,KAAK,IAAI,GAC1D;AACR,SAAO,OAAO,KAAK,IAAI,EACpB,SAAS,QAAQ,EACjB,QAAQ,SAAS,CAAC,MAAM,mBAAmB,CAAC,CAAC;AAClD;AAMO,SAAS,oBACd,SACA,qBAA6C,EAAE,KAAK,KAAK,GAAG,IAAI,GACxD;AACR,SAAO,OAAO;AAAA,IACZ,QAAQ,QAAQ,SAAS,CAAC,MAAM,mBAAmB,CAAC,CAAC;AAAA,IACrD;AAAA,EACF;AACF;AAKA,SAAS,iBACP,WACA,MACA,WACQ;AACR,SAAO,WAAW,SAAS,EAAE,OAAO,GAAG,IAAI,SAAS,SAAS,EAAE,EAAE,OAAO;AAC1E;AAKA,SAAS,YACP,KACyB;AACzB,QAAM,SAAkC,CAAC;AACzC,SAAO,KAAK,GAAG,EAAE,QAAQ,CAAC,QAAQ;AAChC,UAAM,WAAW,IAAI;AAAA,MAAQ;AAAA,MAAc,CAAC,MAC1C,EAAE,YAAY,EAAE,QAAQ,KAAK,EAAE;AAAA,IACjC;AACA,WAAO,QAAQ,IAAI,IAAI,GAAG;AAAA,EAC5B,CAAC;AACD,SAAO;AACT;AAgBA,eAAsB,UACpB,KACA,WACA,UAA4B,CAAC,GACZ;AACjB,QAAM,EAAE,OAAO,gBAAgB,YAAY,OAAO,IAAI;AAEtD,MAAI,OAAO,OAAO,KAAK,KAAK,UAAU,GAAG,CAAC;AAC1C,QAAM,aAAa,MAAM,IAAI,IAAI;AAEjC,MAAI,eAAe;AACnB,MAAI,WAAW,SAAS,KAAK,SAAS,GAAG;AACvC,WAAO;AACP,mBAAe;AAAA,EACjB;AAEA,MAAI,UAAU,oBAAoB,IAAI;AACtC,MAAI,cAAc;AAChB,cAAU,IAAI,OAAO;AAAA,EACvB;AAEA,QAAM,aAAa,iBAAiB,WAAW,MAAM,SAAS;AAC9D,QAAM,OAAO,WAAW,WAAW,UAAU,EAAE,OAAO,OAAO,EAAE,OAAO;AACtE,SAAO,GAAG,OAAO,IAAI,oBAAoB,IAAI,CAAC;AAChD;AAYA,eAAsB,YACpB,SACA,WACA,UAA8B,CAAC,GACnB;AACZ,QAAM;AAAA,IACJ,OAAO;AAAA,IACP,YAAY;AAAA,IACZ,qBAAqB;AAAA,EACvB,IAAI;AAEJ,QAAM,QAAQ,QAAQ,MAAM,GAAG;AAC/B,QAAM,YAAY,MAAM,GAAG,EAAE;AAC7B,MAAI,UAAU,MAAM,MAAM,GAAG,EAAE,EAAE,KAAK,GAAG;AAEzC,QAAM,aAAa,iBAAiB,WAAW,MAAM,SAAS;AAC9D,QAAM,OAAO,WAAW,WAAW,UAAU,EAAE,OAAO,OAAO,EAAE,OAAO;AACtE,MAAI,OAAO,QAAQ,oBAAoB,SAAU,GAAG,IAAI,MAAM,GAAG;AAC/D,UAAM,IAAI,MAAM,+BAA+B;AAAA,EACjD;AAEA,MAAI,aAAa;AACjB,MAAI,QAAQ,WAAW,GAAG,GAAG;AAC3B,iBAAa;AACb,cAAU,QAAQ,MAAM,CAAC;AAAA,EAC3B;AAEA,QAAM,UAAU,oBAAoB,OAAO;AAC3C,MAAI;AAEJ,MAAI,YAAY;AACd,UAAM,eAAe,MAAM,MAAM,OAAO;AACxC,aAAS,KAAK,MAAM,aAAa,SAAS,CAAC;AAAA,EAC7C,OAAO;AACL,aAAS,KAAK,MAAM,QAAQ,SAAS,CAAC;AAAA,EACxC;AAEA,MAAI,oBAAoB;AACtB,WAAO,YAAY,MAAM;AAAA,EAC3B;AACA,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@effing/serde",
+  "version": "0.1.0",
+  "description": "URL-safe serialization with compression and HMAC signing",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "serialization",
+    "base64",
+    "hmac",
+    "url-safe"
+  ],
+  "license": "O'Saasy",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}