ephem 0.1.0

package/dist/index.mjs

@@ -0,0 +1,291 @@
+// src/index.ts
+import { randomUUID, generateKeyPair } from "crypto";
+import {
+  privateDecrypt,
+  createDecipheriv,
+  constants
+} from "crypto";
+var Analytics = class {
+  totalCreatedCapsules;
+  totalUsedCapsules;
+  totalExpiredCapsules;
+  constructor() {
+    this.totalCreatedCapsules = 0;
+    this.totalExpiredCapsules = 0;
+    this.totalUsedCapsules = 0;
+  }
+};
+var DEFAULT_IN_MEMORY_CONFIG = {
+  inMemory: true,
+  maxConcurrentCapsules: Infinity,
+  defaultCaptsuleLifetimeMS: Infinity,
+  capsuleCleanupIntervalMS: 6e4
+};
+function normalizeConfig(config) {
+  if (config?.inMemory === false) {
+    return {
+      ...DEFAULT_IN_MEMORY_CONFIG,
+      ...config,
+      inMemory: false
+    };
+  }
+  return {
+    ...DEFAULT_IN_MEMORY_CONFIG,
+    ...config,
+    inMemory: true
+  };
+}
+function generateCapsuleKeyPair() {
+  return new Promise((resolve, reject) => {
+    generateKeyPair(
+      "rsa",
+      {
+        modulusLength: 2048,
+        publicKeyEncoding: {
+          type: "spki",
+          format: "pem"
+        },
+        privateKeyEncoding: {
+          type: "pkcs8",
+          format: "pem"
+        }
+      },
+      (err, publicKey, privateKey) => {
+        if (err) return reject(err);
+        resolve({ publicKey, privateKey });
+      }
+    );
+  });
+}
+function base64ToBuffer(b64) {
+  return Buffer.from(b64, "base64");
+}
+var Ephem = class {
+  config;
+  genUUID = () => randomUUID();
+  slug = `Ephem`;
+  capsules;
+  analytics;
+  log(...message) {
+    if (this.config.logging) {
+      console.log(`${this.slug} =>`, ...message);
+    }
+  }
+  constructor(config) {
+    this.analytics = new Analytics();
+    this.config = normalizeConfig(config);
+    this.capsules = /* @__PURE__ */ new Map();
+    this.log(`initialized with ${this.config.inMemory ? `in-memory` : `persistent`} mode.`);
+    if (this.config.inMemory) {
+      setTimeout(() => {
+        this.capsuleCleanUp();
+      }, this.config.capsuleCleanupIntervalMS || 6e4);
+    }
+  }
+  /**
+   * Alias Handshake
+   */
+  async createCapsule(callback, config = {}) {
+    try {
+      if (this.config.inMemory && this.capsules.size >= (this.config.maxConcurrentCapsules || Infinity)) {
+        callback(null);
+      } else {
+        const { privateKey, publicKey } = await generateCapsuleKeyPair();
+        const cid = this.genUUID();
+        const lifetime = config.lifetimeDurationMS === void 0 ? this.config.defaultCaptsuleLifetimeMS ? Math.max(1, this.config.defaultCaptsuleLifetimeMS) : Infinity : Math.max(1, config.lifetimeDurationMS);
+        const expiresAt = lifetime === Infinity ? Infinity : Date.now() + lifetime;
+        const maxOpens = Math.max(1, config.maxOpens || 0);
+        const cbData = {
+          publicKey,
+          cid
+        };
+        if (this.config.inMemory) {
+          const capsule = {
+            expiresAt: expiresAt === Infinity ? 0 : expiresAt,
+            maxOpens: maxOpens === Infinity ? 0 : maxOpens,
+            openCount: 0,
+            privateKey
+          };
+          this.capsules.set(cid, capsule);
+          this.analytics.totalCreatedCapsules++;
+          this.log(`new capsul with id ${cid}`);
+          callback(cbData);
+        } else if (this.config.onCapsuleCreation) {
+          const res = await this.config.onCapsuleCreation(cid, privateKey, 0, maxOpens === Infinity ? 0 : maxOpens, expiresAt === Infinity ? 0 : expiresAt);
+          if (res) {
+            this.analytics.totalCreatedCapsules++;
+            this.log(`new capsul with id ${cid}`);
+            callback(cbData);
+          } else {
+            this.log(`Error encountered during capsule creation:`, `onCapsuleCreation returned false.`);
+            callback(null);
+          }
+        } else {
+          this.log(`Error encountered during capsule creation:`, `onCapsuleCreation not defined in persistent mode.`);
+          callback(null);
+        }
+      }
+    } catch (error) {
+      this.log(`Error encountered during capsule creation:`, error);
+      callback(null);
+    }
+  }
+  createCapsulePromise(config = {}) {
+    return new Promise(async (resolve, reject) => {
+      this.createCapsule((r) => {
+        if (r === null) {
+          reject(r);
+        } else {
+          resolve(r);
+        }
+      }, config);
+    });
+  }
+  /**
+   * Handles periodic cleanup of in-memory capsules.
+   * Works only if capsules are in memory.
+   * Else, user should implement their own cleanup elsewhere
+   */
+  capsuleCleanUp() {
+    this.log(`cleanup initialized.`);
+    const start = Date.now();
+    let n = 0;
+    for (const [cid, capsule] of this.capsules) {
+      if (capsule.expiresAt <= Date.now()) {
+        this.analytics.totalExpiredCapsules++;
+        this.capsules.delete(cid);
+        n++;
+      } else if (capsule.openCount >= capsule.maxOpens && capsule.maxOpens != 0) {
+        this.analytics.totalUsedCapsules++;
+        this.capsules.delete(cid);
+        n++;
+      }
+    }
+    if (n) {
+      this.log(`${n} capsule${n == 1 ? "" : "s"} deleted due to expiry or max usage.`);
+    } else {
+      this.log(`no capsule deleted.`);
+    }
+    const duration = this.config.capsuleCleanupIntervalMS || 6e4;
+    const elapsed = Date.now() - start;
+    if (elapsed >= duration) {
+      this.capsuleCleanUp();
+    } else {
+      setTimeout(() => this.capsuleCleanUp(), Math.max(0, duration - elapsed));
+    }
+    this.log(`cleanup ended.`);
+  }
+  async getCapsule(cid) {
+    if (this.config.inMemory) {
+      if (this.capsules.has(cid)) {
+        return this.capsules.get(cid);
+      } else {
+        return null;
+      }
+    } else {
+      if (this.config.OnGetCapsuleByCID) {
+        const r = await this.config.OnGetCapsuleByCID(cid);
+        if (r) {
+          const capsule = {
+            expiresAt: Math.max(Number(r.expiresAt) || 0, 0),
+            maxOpens: Math.max(Number(r.maxOpens) || 0, 1),
+            openCount: Math.max(Number(r.openCount) || 0, 0),
+            privateKey: String(r.privateKey) || ""
+          };
+          return capsule;
+        } else {
+          this.log(`Get capsule error: OnGetCapsuleByCID did not return a capsule.`);
+          return null;
+        }
+      } else {
+        this.log(`Get capsule error: OnGetCapsuleByCID not supplied.`);
+        return null;
+      }
+    }
+  }
+  removeIndividualCapsule(cid, reason) {
+    if (this.config.inMemory) {
+      if (this.capsules.has(cid)) {
+        this.capsules.delete(cid);
+        this.log(`${cid} removed due to '${reason}'.`);
+      }
+    } else {
+      if (this.config.onCapsuleDelete) {
+        this.config.onCapsuleDelete(cid, reason);
+      } else {
+        this.log(`warn: onCapsuleDelete was just required, but not implemented.`);
+      }
+    }
+  }
+  /**
+   * Decrypts encrypted data.
+   */
+  async open(cipher) {
+    if (cipher.startsWith("##INSECURE##")) {
+      const plainText = cipher.slice("##INSECURE##".length);
+      this.log(`WARN: Insecure dev-mode capsule opened.`);
+      return plainText;
+    }
+    const parts = cipher.split(".");
+    if (parts.length !== 4) return null;
+    let [cid, ivB64, cipherTextB64, encKeyB64] = parts;
+    cid = cid || "InvalidPlaceHolder";
+    const capsule = await this.getCapsule(cid);
+    if (!capsule) return null;
+    const { expiresAt, maxOpens, openCount, privateKey } = capsule;
+    if (expiresAt !== 0 && Date.now() >= expiresAt) {
+      this.removeIndividualCapsule(cid, "expired");
+      this.analytics.totalExpiredCapsules++;
+      return null;
+    }
+    if (maxOpens !== 0 && openCount >= maxOpens) {
+      this.removeIndividualCapsule(cid, "max_opened");
+      this.analytics.totalUsedCapsules++;
+      return null;
+    }
+    try {
+      const aesKey = privateDecrypt(
+        {
+          key: privateKey,
+          padding: constants.RSA_PKCS1_OAEP_PADDING,
+          oaepHash: "sha256"
+        },
+        base64ToBuffer(encKeyB64 || "")
+      );
+      const iv = base64ToBuffer(ivB64 || "");
+      const cipherBuf = base64ToBuffer(cipherTextB64 || "");
+      const authTag = cipherBuf.subarray(cipherBuf.length - 16);
+      const encrypted = cipherBuf.subarray(0, cipherBuf.length - 16);
+      const decipher = createDecipheriv("aes-256-gcm", aesKey, iv);
+      decipher.setAuthTag(authTag);
+      decipher.setAAD(Buffer.from(cid));
+      const decrypted = decipher.update(encrypted) + decipher.final("utf8");
+      capsule.openCount++;
+      if (this.config.inMemory) {
+        this.capsules.set(cid, capsule);
+      } else if (this.config.onCapsuleOpen) {
+        await this.config.onCapsuleOpen(cid, capsule.openCount);
+      }
+      if (capsule.expiresAt !== 0 && Date.now() >= capsule.expiresAt) {
+        this.removeIndividualCapsule(cid, "expired");
+        this.analytics.totalExpiredCapsules++;
+      }
+      if (capsule.maxOpens !== 0 && capsule.openCount >= capsule.maxOpens) {
+        this.removeIndividualCapsule(cid, "max_opened");
+        this.analytics.totalUsedCapsules++;
+      }
+      return decrypted;
+    } catch (err) {
+      this.log("open() failed:", err);
+      return null;
+    }
+  }
+  getAnalytics() {
+    const snap = { ...this.analytics };
+    return snap;
+  }
+};
+export {
+  Ephem as default
+};
+if (module.exports.default) { module.exports = module.exports.default; }

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "ephem",
+  "version": "0.1.0",
+  "description": "Ephemeral client-side encryption capsules for secure data-in-transit",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "client": [
+        "dist/client/index.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    },
+    "./client": {
+      "require": "./dist/client/index.js",
+      "import": "./dist/client/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:cdn": "tsup src/client/index.ts --format iife --global-name EphemClient --minify",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "encryption",
+    "ephemeral",
+    "client-side",
+    "security"
+  ],
+  "author": "Gbiang Benedict Mashingil <gbiangb@gmail.com> (https://gbm.name.ng)",
+  "license": "ISC",
+  "type": "commonjs",
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}