ephem 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,87 @@
+type Key = string;
+interface Capsule {
+    privateKey: Key;
+    maxOpens: number;
+    openCount: number;
+    expiresAt: number;
+}
+type OnCreationFunction = (cid: string, privateKey: string, openCount: number, maxOpens: number, expiresAt: number) => Promise<boolean>;
+type OnOpenFunction = (cid: string, openCount: number) => Promise<boolean>;
+type OnGetByCIDFunction = (cid: string) => Promise<{
+    privateKey: unknown;
+    maxOpens: unknown;
+    openCount: unknown;
+    expiresAt: unknown;
+} | null>;
+type CapsuleDeletionReason = 'expired' | 'max_opened';
+type OnDeletionFuntion = (cid: string, deleteReason: CapsuleDeletionReason) => Promise<void>;
+interface EphemConfigInMemory {
+    inMemory?: true;
+    maxConcurrentCapsules?: number;
+    defaultCaptsuleLifetimeMS?: number;
+    capsuleCleanupIntervalMS?: number;
+    onCapsuleCreation?: OnCreationFunction;
+    onCapsuleOpen?: OnOpenFunction;
+    OnGetCapsuleByCID?: OnGetByCIDFunction;
+    onCapsuleDelete?: OnDeletionFuntion;
+    logging?: boolean;
+}
+interface EphemConfigPersistent {
+    inMemory: false;
+    maxConcurrentCapsules?: number;
+    defaultCaptsuleLifetimeMS?: number;
+    capsuleCleanupIntervalMS?: number;
+    onCapsuleCreation: OnCreationFunction;
+    onCapsuleOpen: OnOpenFunction;
+    OnGetCapsuleByCID: OnGetByCIDFunction;
+    onCapsuleDelete: OnDeletionFuntion;
+    logging?: boolean;
+}
+type EphemConfig = EphemConfigInMemory | EphemConfigPersistent;
+interface CreateCapsuleReturnObj {
+    cid: string;
+    publicKey: string;
+}
+interface CreateCapsuleConfig {
+    maxOpens?: number;
+    lifetimeDurationMS?: number;
+}
+type CreateCapsuleCallback = (res: CreateCapsuleReturnObj | null) => void | Promise<void>;
+/**
+ * Keeps track of ephem's analytics since initialization.
+ */
+declare class Analytics {
+    totalCreatedCapsules: number;
+    totalUsedCapsules: number;
+    totalExpiredCapsules: number;
+    constructor();
+}
+declare class Ephem {
+    private readonly config;
+    private genUUID;
+    private slug;
+    private capsules;
+    private analytics;
+    private log;
+    constructor(config?: EphemConfig);
+    /**
+     * Alias Handshake
+     */
+    createCapsule(callback: CreateCapsuleCallback, config?: CreateCapsuleConfig): Promise<void>;
+    createCapsulePromise(config?: CreateCapsuleConfig): Promise<CreateCapsuleReturnObj | null>;
+    /**
+     * Handles periodic cleanup of in-memory capsules.
+     * Works only if capsules are in memory.
+     * Else, user should implement their own cleanup elsewhere
+     */
+    private capsuleCleanUp;
+    getCapsule(cid: string): Promise<Capsule | null>;
+    removeIndividualCapsule(cid: string, reason: CapsuleDeletionReason): void;
+    /**
+     * Decrypts encrypted data.
+     */
+    open(cipher: string): Promise<string | null>;
+    getAnalytics(): Readonly<Analytics>;
+}
+
+export { type Capsule, type CapsuleDeletionReason, type CreateCapsuleCallback, type CreateCapsuleConfig, type CreateCapsuleReturnObj, type EphemConfig, type EphemConfigInMemory, type EphemConfigPersistent, type Key, type OnCreationFunction, type OnDeletionFuntion, type OnGetByCIDFunction, type OnOpenFunction, Ephem as default };

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+type Key = string;
+interface Capsule {
+    privateKey: Key;
+    maxOpens: number;
+    openCount: number;
+    expiresAt: number;
+}
+type OnCreationFunction = (cid: string, privateKey: string, openCount: number, maxOpens: number, expiresAt: number) => Promise<boolean>;
+type OnOpenFunction = (cid: string, openCount: number) => Promise<boolean>;
+type OnGetByCIDFunction = (cid: string) => Promise<{
+    privateKey: unknown;
+    maxOpens: unknown;
+    openCount: unknown;
+    expiresAt: unknown;
+} | null>;
+type CapsuleDeletionReason = 'expired' | 'max_opened';
+type OnDeletionFuntion = (cid: string, deleteReason: CapsuleDeletionReason) => Promise<void>;
+interface EphemConfigInMemory {
+    inMemory?: true;
+    maxConcurrentCapsules?: number;
+    defaultCaptsuleLifetimeMS?: number;
+    capsuleCleanupIntervalMS?: number;
+    onCapsuleCreation?: OnCreationFunction;
+    onCapsuleOpen?: OnOpenFunction;
+    OnGetCapsuleByCID?: OnGetByCIDFunction;
+    onCapsuleDelete?: OnDeletionFuntion;
+    logging?: boolean;
+}
+interface EphemConfigPersistent {
+    inMemory: false;
+    maxConcurrentCapsules?: number;
+    defaultCaptsuleLifetimeMS?: number;
+    capsuleCleanupIntervalMS?: number;
+    onCapsuleCreation: OnCreationFunction;
+    onCapsuleOpen: OnOpenFunction;
+    OnGetCapsuleByCID: OnGetByCIDFunction;
+    onCapsuleDelete: OnDeletionFuntion;
+    logging?: boolean;
+}
+type EphemConfig = EphemConfigInMemory | EphemConfigPersistent;
+interface CreateCapsuleReturnObj {
+    cid: string;
+    publicKey: string;
+}
+interface CreateCapsuleConfig {
+    maxOpens?: number;
+    lifetimeDurationMS?: number;
+}
+type CreateCapsuleCallback = (res: CreateCapsuleReturnObj | null) => void | Promise<void>;
+/**
+ * Keeps track of ephem's analytics since initialization.
+ */
+declare class Analytics {
+    totalCreatedCapsules: number;
+    totalUsedCapsules: number;
+    totalExpiredCapsules: number;
+    constructor();
+}
+declare class Ephem {
+    private readonly config;
+    private genUUID;
+    private slug;
+    private capsules;
+    private analytics;
+    private log;
+    constructor(config?: EphemConfig);
+    /**
+     * Alias Handshake
+     */
+    createCapsule(callback: CreateCapsuleCallback, config?: CreateCapsuleConfig): Promise<void>;
+    createCapsulePromise(config?: CreateCapsuleConfig): Promise<CreateCapsuleReturnObj | null>;
+    /**
+     * Handles periodic cleanup of in-memory capsules.
+     * Works only if capsules are in memory.
+     * Else, user should implement their own cleanup elsewhere
+     */
+    private capsuleCleanUp;
+    getCapsule(cid: string): Promise<Capsule | null>;
+    removeIndividualCapsule(cid: string, reason: CapsuleDeletionReason): void;
+    /**
+     * Decrypts encrypted data.
+     */
+    open(cipher: string): Promise<string | null>;
+    getAnalytics(): Readonly<Analytics>;
+}
+
+// @ts-ignore
+export = Ephem;
+export type { Capsule, CapsuleDeletionReason, CreateCapsuleCallback, CreateCapsuleConfig, CreateCapsuleReturnObj, EphemConfig, EphemConfigInMemory, EphemConfigPersistent, Key, OnCreationFunction, OnDeletionFuntion, OnGetByCIDFunction, OnOpenFunction };

package/dist/index.js

@@ -0,0 +1,308 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => Ephem
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("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) => {
+    (0, import_node_crypto.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 = () => (0, import_node_crypto.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 = (0, import_node_crypto2.privateDecrypt)(
+        {
+          key: privateKey,
+          padding: import_node_crypto2.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 = (0, import_node_crypto2.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;
+  }
+};
+if (module.exports.default) { module.exports = module.exports.default; }