lightspeed-retail-sdk 3.0.1 → 3.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 A JavaScript SDK for interacting with the Lightspeed Retail API. This SDK provides a convenient way to access Lightspeed Retail's functionalities, including customer, item, order management, and more.
 
-**Current Version: 3.0.0** - Updated with new OAuth system support and enhanced token management.
+**Current Version: 3.0.2** - Updated with new OAuth system support and enhanced token management.
 
 ## 🚨 Important Update - New OAuth System
 
@@ -104,6 +104,57 @@ const api = new LightspeedRetailSDK({
 export default api;
 ```
 
+#### Encrypted Storage (Recommended)
+
+You can now store your tokens **encrypted at rest** using the built-in `EncryptedTokenStorage` class. This works as a wrapper around any storage adapter (such as `FileTokenStorage`) and uses AES-256-GCM encryption with a key you provide.
+
+**Generate a key** (if you haven't already):
+
+```bash
+npm run generate-key
+```
+
+Add the generated key to your `.env` file:
+
+```env
+LIGHTSPEED_ENCRYPTION_KEY=your_64_char_hex_key_here
+```
+
+**Usage Example:**
+
+```javascript
+import LightspeedRetailSDK, { FileTokenStorage } from "lightspeed-retail-sdk";
+import { EncryptedTokenStorage } from "lightspeed-retail-sdk/src/storage/TokenStorage.mjs";
+import dotenv from "dotenv";
+dotenv.config();
+
+const fileStorage = new FileTokenStorage("./lightspeed-tokens.json");
+const encryptionKey = process.env.LIGHTSPEED_ENCRYPTION_KEY;
+
+const tokenStorage = encryptionKey
+  ? new EncryptedTokenStorage(fileStorage, encryptionKey)
+  : fileStorage;
+
+const api = new LightspeedRetailSDK({
+  accountID: "Your Account No.",
+  clientID: "Your client ID.",
+  clientSecret: "Your client secret.",
+  refreshToken: "Your initial refresh token.",
+  tokenStorage,
+});
+
+export default api;
+```
+
+- If `LIGHTSPEED_ENCRYPTION_KEY` is set, your tokens will be encrypted transparently.
+- If not, it falls back to plain file storage (backward compatible).
+- The encryption uses AES-256-GCM and is fully compatible with existing token files (it will auto-detect and migrate as needed).
+
+**Note:**  
+Keep your encryption key secure and never commit it to version control!
+
+---
+
 #### Database Storage (Built-in Base Class)
 
 The SDK provides a `DatabaseTokenStorage` base class that you can extend:

package/dist/src/storage/TokenStorage.cjs

@@ -12,6 +12,9 @@ _export(exports, {
     get DatabaseTokenStorage () {
         return DatabaseTokenStorage;
     },
+    get EncryptedTokenStorage () {
+        return EncryptedTokenStorage;
+    },
     get FileTokenStorage () {
         return FileTokenStorage;
     },
@@ -24,6 +27,7 @@ _export(exports, {
 });
 const _fs = require("fs");
 const _path = /*#__PURE__*/ _interop_require_default(require("path"));
+const _crypto = /*#__PURE__*/ _interop_require_default(require("crypto"));
 function _interop_require_default(obj) {
     return obj && obj.__esModule ? obj : {
         default: obj
@@ -37,6 +41,66 @@ class TokenStorage {
         throw new Error("setTokens() must be implemented by subclass");
     }
 }
+class EncryptedTokenStorage {
+    async getTokens() {
+        const encrypted = await this.adapter.getTokens();
+        // Backwards compatibility: if it's a plain object with access_token, return as-is
+        if (encrypted && typeof encrypted === "object" && encrypted.access_token) {
+            return encrypted;
+        }
+        // Otherwise, expect { iv, tag, data }
+        if (encrypted && typeof encrypted === "object" && encrypted.iv && encrypted.tag && encrypted.data) {
+            try {
+                const iv = Buffer.from(encrypted.iv, "hex");
+                const tag = Buffer.from(encrypted.tag, "hex");
+                const encryptedData = Buffer.from(encrypted.data, "hex");
+                const decipher = _crypto.default.createDecipheriv(this.algorithm, this.key, iv);
+                decipher.setAuthTag(tag);
+                let decrypted = decipher.update(encryptedData, undefined, "utf8");
+                decrypted += decipher.final("utf8");
+                return JSON.parse(decrypted);
+            } catch (err) {
+                throw new Error("Failed to decrypt tokens: " + err.message);
+            }
+        }
+        // If file is empty or not recognized, return empty object
+        return {};
+    }
+    async setTokens(tokens) {
+        // Backwards compatibility: if tokens are already encrypted, just store as-is
+        if (tokens && typeof tokens === "object" && tokens.iv && tokens.tag && tokens.data) {
+            return this.adapter.setTokens(tokens);
+        }
+        // Encrypt the tokens object
+        const iv = _crypto.default.randomBytes(12); // 96 bits for GCM
+        const cipher = _crypto.default.createCipheriv(this.algorithm, this.key, iv);
+        let encrypted = cipher.update(JSON.stringify(tokens), "utf8");
+        encrypted = Buffer.concat([
+            encrypted,
+            cipher.final()
+        ]);
+        const tag = cipher.getAuthTag();
+        const encryptedPayload = {
+            iv: iv.toString("hex"),
+            tag: tag.toString("hex"),
+            data: encrypted.toString("hex")
+        };
+        return this.adapter.setTokens(encryptedPayload);
+    }
+    constructor(storageAdapter, encryptionKey){
+        this.adapter = storageAdapter;
+        // Accept hex string or Buffer
+        if (typeof encryptionKey === "string") {
+            this.key = Buffer.from(encryptionKey, "hex");
+        } else {
+            this.key = encryptionKey;
+        }
+        if (this.key.length !== 32) {
+            throw new Error("Encryption key must be 32 bytes (256 bits)");
+        }
+        this.algorithm = "aes-256-gcm";
+    }
+}
 class InMemoryTokenStorage extends TokenStorage {
     async getTokens() {
         return this.tokens;

package/dist/src/storage/TokenStorage.mjs

@@ -1,5 +1,6 @@
 import { promises as fs } from "fs";
 import path from "path";
+import crypto from "crypto";
 
 // Base class for token storage
 export class TokenStorage {
@@ -12,6 +13,90 @@ export class TokenStorage {
   }
 }
 
+/**
+ * @param {TokenStorage} storageAdapter - Any TokenStorage instance (e.g., FileTokenStorage)
+ * @param {string} encryptionKey - 32-byte (256-bit) key as a hex string or Buffer
+ */
+export class EncryptedTokenStorage {
+  constructor(storageAdapter, encryptionKey) {
+    this.adapter = storageAdapter;
+    // Accept hex string or Buffer
+    if (typeof encryptionKey === "string") {
+      this.key = Buffer.from(encryptionKey, "hex");
+    } else {
+      this.key = encryptionKey;
+    }
+    if (this.key.length !== 32) {
+      throw new Error("Encryption key must be 32 bytes (256 bits)");
+    }
+    this.algorithm = "aes-256-gcm";
+  }
+
+  async getTokens() {
+    const encrypted = await this.adapter.getTokens();
+
+    // Backwards compatibility: if it's a plain object with access_token, return as-is
+    if (encrypted && typeof encrypted === "object" && encrypted.access_token) {
+      return encrypted;
+    }
+
+    // Otherwise, expect { iv, tag, data }
+    if (
+      encrypted &&
+      typeof encrypted === "object" &&
+      encrypted.iv &&
+      encrypted.tag &&
+      encrypted.data
+    ) {
+      try {
+        const iv = Buffer.from(encrypted.iv, "hex");
+        const tag = Buffer.from(encrypted.tag, "hex");
+        const encryptedData = Buffer.from(encrypted.data, "hex");
+
+        const decipher = crypto.createDecipheriv(this.algorithm, this.key, iv);
+        decipher.setAuthTag(tag);
+        let decrypted = decipher.update(encryptedData, undefined, "utf8");
+        decrypted += decipher.final("utf8");
+        return JSON.parse(decrypted);
+      } catch (err) {
+        throw new Error("Failed to decrypt tokens: " + err.message);
+      }
+    }
+
+    // If file is empty or not recognized, return empty object
+    return {};
+  }
+
+  async setTokens(tokens) {
+    // Backwards compatibility: if tokens are already encrypted, just store as-is
+    if (
+      tokens &&
+      typeof tokens === "object" &&
+      tokens.iv &&
+      tokens.tag &&
+      tokens.data
+    ) {
+      return this.adapter.setTokens(tokens);
+    }
+
+    // Encrypt the tokens object
+    const iv = crypto.randomBytes(12); // 96 bits for GCM
+    const cipher = crypto.createCipheriv(this.algorithm, this.key, iv);
+
+    let encrypted = cipher.update(JSON.stringify(tokens), "utf8");
+    encrypted = Buffer.concat([encrypted, cipher.final()]);
+    const tag = cipher.getAuthTag();
+
+    const encryptedPayload = {
+      iv: iv.toString("hex"),
+      tag: tag.toString("hex"),
+      data: encrypted.toString("hex"),
+    };
+
+    return this.adapter.setTokens(encryptedPayload);
+  }
+}
+
 // In-memory storage (fallback)
 export class InMemoryTokenStorage extends TokenStorage {
   constructor() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightspeed-retail-sdk",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Another unofficial Lightspeed Retail API SDK for Node.js",
   "type": "module",
   "main": "dist/index.cjs",
@@ -25,7 +25,9 @@
     "build:main": "swc index.mjs -o dist/index.cjs",
     "fix-paths": "find dist -name '*.cjs' -exec sed -i '' 's/\\.mjs/.cjs/g' {} +",
     "prebuild": "mkdir -p dist/src/core dist/src/storage",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "generate-key": "node scripts/generate-key.js",
+    "publish": "npm run build && npm publish"
   },
   "files": [
     "dist/",