ephem 1.0.2 → 1.0.3

package/README.md

@@ -23,8 +23,6 @@ In modern infrastructure, TLS (Transport Layer Security) often terminates at the
 
 Ephem is also suitable for **Server-to-Server** communication for high-security microservices that need to pass secrets over untrusted internal pipes.
 
-Ephem is also suitable for **Server-to-Server** communication for high-security microservices that need to pass secrets over untrusted internal pipes.
-
 **Transport Agnostic:** Since Ephem operates at the application layer, it works independently of the transport protocol. You can send capsules over HTTP, WebSockets, FTP, email, or even sneakernet.
 
 **Horizontal Scaling:** Ephem supports high-availability clusters. By using `inMemory: false` and implementing persistence hooks (backed by Redis, Postgres, etc.), any server in your fleet can open a capsule, regardless of which server issued it. State is shared, not siloed.
@@ -369,8 +367,6 @@ Attempts to decrypt a sealed payload.
     *   The capsule has exceeded its `maxOpens` count.
     *   The decryption fails (wrong key, tampering detected).
 
-    *   The decryption fails (wrong key, tampering detected).
-
 ---
 
 ### `ephem.getAnalytics()`
@@ -496,6 +492,35 @@ const ephem = new Ephem({
 });
 ```
 
+### Cleanup Responsibilities (Persistent Mode)
+
+When `inMemory: false`, Ephem's internal `capsuleCleanUp` loop is **disabled**. You are responsible for removing expired capsules from your storage backend.
+
+If you are using **Redis**, simpler is better: use the `EXPIRE` command (TTL) when setting the key, as shown in the example above. Redis will automatically remove the key when it expires.
+
+If you are using a **SQL Database** (Postgres, MySQL), you should run a periodic cleanup job (CRON).
+
+#### Example: SQL Cleanup Cron
+
+```typescript
+// run-cleanup.ts
+import db from './my-db';
+
+async function cleanup() {
+  const now = Date.now();
+  
+  // Delete expired capsules
+  await db.query('DELETE FROM capsules WHERE expires_at < $1', [now]);
+  
+  // Optional: Delete exhausted capsules if your logic allows
+  // (Usually handled in real-time by onCapsuleOpen, but good for safety)
+  await db.query('DELETE FROM capsules WHERE open_count >= max_opens AND max_opens > 0');
+}
+
+// Run every minute
+setInterval(cleanup, 60 * 1000);
+```
+
 ## Contributing
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
 

package/dist/client/index.d.mts

@@ -1,3 +1,12 @@
+/**
+ * Encrypts (seals) a plaintext message into an ephemeral capsule format.
+ *
+ * @param text The plaintext message to encrypt.
+ * @param publicKeyPem The recipient's Public Key (PEM format).
+ * @param cid The Capsule ID (provided by the server).
+ * @param allowInsecureFallback If true, allows "secure" operations in non-secure contexts (DEV ONLY).
+ * @returns The sealed ciphertext string in the format: `cid.iv.ciphertext.encryptedKey`
+ */
 declare function seal(text: string, publicKeyPem: string, cid: string, allowInsecureFallback?: boolean): Promise<string>;
 
 export { seal };

package/dist/client/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Encrypts (seals) a plaintext message into an ephemeral capsule format.
+ *
+ * @param text The plaintext message to encrypt.
+ * @param publicKeyPem The recipient's Public Key (PEM format).
+ * @param cid The Capsule ID (provided by the server).
+ * @param allowInsecureFallback If true, allows "secure" operations in non-secure contexts (DEV ONLY).
+ * @returns The sealed ciphertext string in the format: `cid.iv.ciphertext.encryptedKey`
+ */
 declare function seal(text: string, publicKeyPem: string, cid: string, allowInsecureFallback?: boolean): Promise<string>;
 
 export { seal };

package/dist/index.d.mts

@@ -1,51 +1,111 @@
+/**
+ * Represents a key used in the system.
+ */
 type Key = string;
+/**
+ * Represents an individual ephemeral capsule.
+ */
 interface Capsule {
+    /** The private key associated with this capsule */
     privateKey: Key;
+    /** Maximum number of times this capsule can be opened */
     maxOpens: number;
+    /** Current number of times this capsule has been opened */
     openCount: number;
+    /** Timestamp (ms) when this capsule expires */
     expiresAt: number;
 }
+/**
+ * Callback function triggered when a capsule is created (persistent mode).
+ * Should return true if storage was successful, false otherwise.
+ */
 type OnCreationFunction = (cid: string, privateKey: string, openCount: number, maxOpens: number, expiresAt: number) => Promise<boolean>;
+/**
+ * Callback function triggered when a capsule is opened (persistent mode).
+ * Used to update the open count in external storage.
+ */
 type OnOpenFunction = (cid: string, openCount: number) => Promise<boolean>;
+/**
+ * Callback function to retrieve a capsule by its ID from external storage.
+ */
 type OnGetByCIDFunction = (cid: string) => Promise<{
     privateKey: unknown;
     maxOpens: unknown;
     openCount: unknown;
     expiresAt: unknown;
 } | null>;
+/**
+ * Reason for capsule deletion.
+ */
 type CapsuleDeletionReason = 'expired' | 'max_opened';
+/**
+ * Callback function triggered when a capsule is deleted (persistent mode).
+ */
 type OnDeletionFuntion = (cid: string, deleteReason: CapsuleDeletionReason) => Promise<void>;
+/**
+ * Configuration for running Ephem in-memory.
+ */
 interface EphemConfigInMemory {
+    /** Set to true for in-memory operation */
     inMemory?: true;
+    /** Maximum number of concurrent capsules allowed in memory */
     maxConcurrentCapsules?: number;
+    /** Default lifetime for a capsule in milliseconds */
     defaultCaptsuleLifetimeMS?: number;
+    /** Interval for the cleanup loop in milliseconds */
     capsuleCleanupIntervalMS?: number;
     onCapsuleCreation?: OnCreationFunction;
     onCapsuleOpen?: OnOpenFunction;
     OnGetCapsuleByCID?: OnGetByCIDFunction;
     onCapsuleDelete?: OnDeletionFuntion;
+    /** Enable logging */
     logging?: boolean;
 }
+/**
+ * Configuration for running Ephem with persistent storage.
+ */
 interface EphemConfigPersistent {
+    /** Set to false for persistent operation */
     inMemory: false;
     maxConcurrentCapsules?: number;
     defaultCaptsuleLifetimeMS?: number;
     capsuleCleanupIntervalMS?: number;
+    /** Required: Callback to store a new capsule */
     onCapsuleCreation: OnCreationFunction;
+    /** Required: Callback to update a capsule's open count */
     onCapsuleOpen: OnOpenFunction;
+    /** Required: Callback to retrieve a capsule */
     OnGetCapsuleByCID: OnGetByCIDFunction;
+    /** Required: Callback to delete a capsule */
     onCapsuleDelete: OnDeletionFuntion;
+    /** Enable logging */
     logging?: boolean;
 }
+/**
+ * Union type for Ephem configuration.
+ */
 type EphemConfig = EphemConfigInMemory | EphemConfigPersistent;
+/**
+ * Object returned when a capsule is successfully created.
+ */
 interface CreateCapsuleReturnObj {
+    /** The Capsule ID */
     cid: string;
+    /** The Public Key (PEM) associated with the capsule */
     publicKey: string;
 }
+/**
+ * Configuration options for creating a single capsule.
+ */
 interface CreateCapsuleConfig {
+    /** Maximum number of times the capsule can be opened */
     maxOpens?: number;
+    /** Lifetime of the capsule in milliseconds */
     lifetimeDurationMS?: number;
 }
+/**
+ * Callback for the createCapsule method.
+ */
 type CreateCapsuleCallback = (res: CreateCapsuleReturnObj | null) => void | Promise<void>;
 /**
  * Keeps track of ephem's analytics since initialization.
@@ -56,18 +116,35 @@ declare class Analytics {
     totalExpiredCapsules: number;
     constructor();
 }
+/**
+ * Ephem: Robust, Ephemeral End-to-End Encryption for the Application Layer.
+ */
 declare class Ephem {
     private readonly config;
     private genUUID;
     private slug;
     private capsules;
     private analytics;
+    /**
+     * Internal logging method.
+     */
     private log;
+    /**
+     * Initializes a new instance of Ephem.
+     * @param config Configuration object for Ephem.
+     */
     constructor(config?: EphemConfig);
     /**
-     * Alias Handshake
+     * Creates a new ephemeral capsule.
+     * @param callback Callback function receiving the result (Capsule ID and Public Key) or null on failure.
+     * @param config Optional configuration for this specific capsule.
      */
     createCapsule(callback: CreateCapsuleCallback, config?: CreateCapsuleConfig): Promise<void>;
+    /**
+     * Promise-based wrapper for createCapsule.
+     * @param config Optional configuration for this specific capsule.
+     * @returns Promise resolving to the capsule details.
+     */
     createCapsulePromise(config?: CreateCapsuleConfig): Promise<CreateCapsuleReturnObj | null>;
     /**
      * Handles periodic cleanup of in-memory capsules.
@@ -75,13 +152,27 @@ declare class Ephem {
      * Else, user should implement their own cleanup elsewhere
      */
     private capsuleCleanUp;
+    /**
+     * Retrieves a capsule by its ID (CID).
+     * @param cid Capsule ID.
+     */
     getCapsule(cid: string): Promise<Capsule | null>;
+    /**
+     * Removes a single capsule.
+     * @param cid Capsule ID.
+     * @param reason Reason for deletion.
+     */
     removeIndividualCapsule(cid: string, reason: CapsuleDeletionReason): void;
     /**
-     * Decrypts encrypted data.
+     * Decrypts an encrypted payload (cipher string).
+     * @param cipher The dot-separated cipher string [cid.iv.ciphertext.encryptedKey].
+     * @returns The decrypted plaintext or null if decryption fails or capsule is invalid.
      */
     open(cipher: string): Promise<string | null>;
+    /**
+     * Returns a snapshot of current analytics.
+     */
     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 };
+export { Analytics, 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

@@ -1,51 +1,111 @@
+/**
+ * Represents a key used in the system.
+ */
 type Key = string;
+/**
+ * Represents an individual ephemeral capsule.
+ */
 interface Capsule {
+    /** The private key associated with this capsule */
     privateKey: Key;
+    /** Maximum number of times this capsule can be opened */
     maxOpens: number;
+    /** Current number of times this capsule has been opened */
     openCount: number;
+    /** Timestamp (ms) when this capsule expires */
     expiresAt: number;
 }
+/**
+ * Callback function triggered when a capsule is created (persistent mode).
+ * Should return true if storage was successful, false otherwise.
+ */
 type OnCreationFunction = (cid: string, privateKey: string, openCount: number, maxOpens: number, expiresAt: number) => Promise<boolean>;
+/**
+ * Callback function triggered when a capsule is opened (persistent mode).
+ * Used to update the open count in external storage.
+ */
 type OnOpenFunction = (cid: string, openCount: number) => Promise<boolean>;
+/**
+ * Callback function to retrieve a capsule by its ID from external storage.
+ */
 type OnGetByCIDFunction = (cid: string) => Promise<{
     privateKey: unknown;
     maxOpens: unknown;
     openCount: unknown;
     expiresAt: unknown;
 } | null>;
+/**
+ * Reason for capsule deletion.
+ */
 type CapsuleDeletionReason = 'expired' | 'max_opened';
+/**
+ * Callback function triggered when a capsule is deleted (persistent mode).
+ */
 type OnDeletionFuntion = (cid: string, deleteReason: CapsuleDeletionReason) => Promise<void>;
+/**
+ * Configuration for running Ephem in-memory.
+ */
 interface EphemConfigInMemory {
+    /** Set to true for in-memory operation */
     inMemory?: true;
+    /** Maximum number of concurrent capsules allowed in memory */
     maxConcurrentCapsules?: number;
+    /** Default lifetime for a capsule in milliseconds */
     defaultCaptsuleLifetimeMS?: number;
+    /** Interval for the cleanup loop in milliseconds */
     capsuleCleanupIntervalMS?: number;
     onCapsuleCreation?: OnCreationFunction;
     onCapsuleOpen?: OnOpenFunction;
     OnGetCapsuleByCID?: OnGetByCIDFunction;
     onCapsuleDelete?: OnDeletionFuntion;
+    /** Enable logging */
     logging?: boolean;
 }
+/**
+ * Configuration for running Ephem with persistent storage.
+ */
 interface EphemConfigPersistent {
+    /** Set to false for persistent operation */
     inMemory: false;
     maxConcurrentCapsules?: number;
     defaultCaptsuleLifetimeMS?: number;
     capsuleCleanupIntervalMS?: number;
+    /** Required: Callback to store a new capsule */
     onCapsuleCreation: OnCreationFunction;
+    /** Required: Callback to update a capsule's open count */
     onCapsuleOpen: OnOpenFunction;
+    /** Required: Callback to retrieve a capsule */
     OnGetCapsuleByCID: OnGetByCIDFunction;
+    /** Required: Callback to delete a capsule */
     onCapsuleDelete: OnDeletionFuntion;
+    /** Enable logging */
     logging?: boolean;
 }
+/**
+ * Union type for Ephem configuration.
+ */
 type EphemConfig = EphemConfigInMemory | EphemConfigPersistent;
+/**
+ * Object returned when a capsule is successfully created.
+ */
 interface CreateCapsuleReturnObj {
+    /** The Capsule ID */
     cid: string;
+    /** The Public Key (PEM) associated with the capsule */
     publicKey: string;
 }
+/**
+ * Configuration options for creating a single capsule.
+ */
 interface CreateCapsuleConfig {
+    /** Maximum number of times the capsule can be opened */
     maxOpens?: number;
+    /** Lifetime of the capsule in milliseconds */
     lifetimeDurationMS?: number;
 }
+/**
+ * Callback for the createCapsule method.
+ */
 type CreateCapsuleCallback = (res: CreateCapsuleReturnObj | null) => void | Promise<void>;
 /**
  * Keeps track of ephem's analytics since initialization.
@@ -56,18 +116,35 @@ declare class Analytics {
     totalExpiredCapsules: number;
     constructor();
 }
+/**
+ * Ephem: Robust, Ephemeral End-to-End Encryption for the Application Layer.
+ */
 declare class Ephem {
     private readonly config;
     private genUUID;
     private slug;
     private capsules;
     private analytics;
+    /**
+     * Internal logging method.
+     */
     private log;
+    /**
+     * Initializes a new instance of Ephem.
+     * @param config Configuration object for Ephem.
+     */
     constructor(config?: EphemConfig);
     /**
-     * Alias Handshake
+     * Creates a new ephemeral capsule.
+     * @param callback Callback function receiving the result (Capsule ID and Public Key) or null on failure.
+     * @param config Optional configuration for this specific capsule.
      */
     createCapsule(callback: CreateCapsuleCallback, config?: CreateCapsuleConfig): Promise<void>;
+    /**
+     * Promise-based wrapper for createCapsule.
+     * @param config Optional configuration for this specific capsule.
+     * @returns Promise resolving to the capsule details.
+     */
     createCapsulePromise(config?: CreateCapsuleConfig): Promise<CreateCapsuleReturnObj | null>;
     /**
      * Handles periodic cleanup of in-memory capsules.
@@ -75,15 +152,29 @@ declare class Ephem {
      * Else, user should implement their own cleanup elsewhere
      */
     private capsuleCleanUp;
+    /**
+     * Retrieves a capsule by its ID (CID).
+     * @param cid Capsule ID.
+     */
     getCapsule(cid: string): Promise<Capsule | null>;
+    /**
+     * Removes a single capsule.
+     * @param cid Capsule ID.
+     * @param reason Reason for deletion.
+     */
     removeIndividualCapsule(cid: string, reason: CapsuleDeletionReason): void;
     /**
-     * Decrypts encrypted data.
+     * Decrypts an encrypted payload (cipher string).
+     * @param cipher The dot-separated cipher string [cid.iv.ciphertext.encryptedKey].
+     * @returns The decrypted plaintext or null if decryption fails or capsule is invalid.
      */
     open(cipher: string): Promise<string | null>;
+    /**
+     * Returns a snapshot of current analytics.
+     */
     getAnalytics(): Readonly<Analytics>;
 }
 
 // @ts-ignore
 export = Ephem;
-export type { Capsule, CapsuleDeletionReason, CreateCapsuleCallback, CreateCapsuleConfig, CreateCapsuleReturnObj, EphemConfig, EphemConfigInMemory, EphemConfigPersistent, Key, OnCreationFunction, OnDeletionFuntion, OnGetByCIDFunction, OnOpenFunction };
+export { Analytics, 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 };

package/dist/index.js

@@ -86,11 +86,18 @@ var Ephem = class {
   slug = `Ephem`;
   capsules;
   analytics;
+  /**
+   * Internal logging method.
+   */
   log(...message) {
     if (this.config.logging) {
       console.log(`${this.slug} =>`, ...message);
     }
   }
+  /**
+   * Initializes a new instance of Ephem.
+   * @param config Configuration object for Ephem.
+   */
   constructor(config) {
     this.analytics = new Analytics();
     this.config = normalizeConfig(config);
@@ -103,7 +110,9 @@ var Ephem = class {
     }
   }
   /**
-   * Alias Handshake
+   * Creates a new ephemeral capsule.
+   * @param callback Callback function receiving the result (Capsule ID and Public Key) or null on failure.
+   * @param config Optional configuration for this specific capsule.
    */
   async createCapsule(callback, config = {}) {
     try {
@@ -150,6 +159,11 @@ var Ephem = class {
       callback(null);
     }
   }
+  /**
+   * Promise-based wrapper for createCapsule.
+   * @param config Optional configuration for this specific capsule.
+   * @returns Promise resolving to the capsule details.
+   */
   createCapsulePromise(config = {}) {
     return new Promise(async (resolve, reject) => {
       this.createCapsule((r) => {
@@ -195,6 +209,10 @@ var Ephem = class {
     }
     this.log(`cleanup ended.`);
   }
+  /**
+   * Retrieves a capsule by its ID (CID).
+   * @param cid Capsule ID.
+   */
   async getCapsule(cid) {
     if (this.config.inMemory) {
       if (this.capsules.has(cid)) {
@@ -223,6 +241,11 @@ var Ephem = class {
       }
     }
   }
+  /**
+   * Removes a single capsule.
+   * @param cid Capsule ID.
+   * @param reason Reason for deletion.
+   */
   removeIndividualCapsule(cid, reason) {
     if (this.config.inMemory) {
       if (this.capsules.has(cid)) {
@@ -238,7 +261,9 @@ var Ephem = class {
     }
   }
   /**
-   * Decrypts encrypted data.
+   * Decrypts an encrypted payload (cipher string).
+   * @param cipher The dot-separated cipher string [cid.iv.ciphertext.encryptedKey].
+   * @returns The decrypted plaintext or null if decryption fails or capsule is invalid.
    */
   async open(cipher) {
     if (cipher.startsWith("##INSECURE##")) {
@@ -300,6 +325,9 @@ var Ephem = class {
       return null;
     }
   }
+  /**
+   * Returns a snapshot of current analytics.
+   */
   getAnalytics() {
     const snap = { ...this.analytics };
     return snap;

package/dist/index.mjs

@@ -66,11 +66,18 @@ var Ephem = class {
   slug = `Ephem`;
   capsules;
   analytics;
+  /**
+   * Internal logging method.
+   */
   log(...message) {
     if (this.config.logging) {
       console.log(`${this.slug} =>`, ...message);
     }
   }
+  /**
+   * Initializes a new instance of Ephem.
+   * @param config Configuration object for Ephem.
+   */
   constructor(config) {
     this.analytics = new Analytics();
     this.config = normalizeConfig(config);
@@ -83,7 +90,9 @@ var Ephem = class {
     }
   }
   /**
-   * Alias Handshake
+   * Creates a new ephemeral capsule.
+   * @param callback Callback function receiving the result (Capsule ID and Public Key) or null on failure.
+   * @param config Optional configuration for this specific capsule.
    */
   async createCapsule(callback, config = {}) {
     try {
@@ -130,6 +139,11 @@ var Ephem = class {
       callback(null);
     }
   }
+  /**
+   * Promise-based wrapper for createCapsule.
+   * @param config Optional configuration for this specific capsule.
+   * @returns Promise resolving to the capsule details.
+   */
   createCapsulePromise(config = {}) {
     return new Promise(async (resolve, reject) => {
       this.createCapsule((r) => {
@@ -175,6 +189,10 @@ var Ephem = class {
     }
     this.log(`cleanup ended.`);
   }
+  /**
+   * Retrieves a capsule by its ID (CID).
+   * @param cid Capsule ID.
+   */
   async getCapsule(cid) {
     if (this.config.inMemory) {
       if (this.capsules.has(cid)) {
@@ -203,6 +221,11 @@ var Ephem = class {
       }
     }
   }
+  /**
+   * Removes a single capsule.
+   * @param cid Capsule ID.
+   * @param reason Reason for deletion.
+   */
   removeIndividualCapsule(cid, reason) {
     if (this.config.inMemory) {
       if (this.capsules.has(cid)) {
@@ -218,7 +241,9 @@ var Ephem = class {
     }
   }
   /**
-   * Decrypts encrypted data.
+   * Decrypts an encrypted payload (cipher string).
+   * @param cipher The dot-separated cipher string [cid.iv.ciphertext.encryptedKey].
+   * @returns The decrypted plaintext or null if decryption fails or capsule is invalid.
    */
   async open(cipher) {
     if (cipher.startsWith("##INSECURE##")) {
@@ -280,6 +305,9 @@ var Ephem = class {
       return null;
     }
   }
+  /**
+   * Returns a snapshot of current analytics.
+   */
   getAnalytics() {
     const snap = { ...this.analytics };
     return snap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ephem",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Robust, Ephemeral End-to-End Encryption for the Application Layer. Secure data-in-transit with disposable capsules.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",