ephem 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,481 @@
+# Ephem
+
+**Robust, Ephemeral End-to-End Encryption for the Application Layer.**
+
+> [!IMPORTANT]
+> **Not a TLS replacement.** Ephem is a defense-in-depth security layer designed to protect high-value sensitive data (passwords, PII, financial info) even if TLS is terminated, inspected, or compromised.
+
+Ephem allows your server to issue disposable "Capsules": short-lived, single-use cryptographic containers. Clients seal data into these capsules using hybrid encryption (RSA + AES). Only the server that issued the capsule can open it, and only within the defined restrictions (expiration time, maximum open count).
+
+Once a capsule is used or expires, its private key is destroyed forever.
+
+---
+
+## Why Ephem? (Intent)
+
+Ephem is designed for **Application-Layer Encryption**.
+
+In modern infrastructure, TLS (Transport Layer Security) often terminates at the perimeter, at your Load Balancer (AWS ALB, Nginx, Cloudflare). From that point onward, traffic often travels unencrypted across your internal network (VPC) to reach your application server.
+
+**The Risk:** If an attacker compromises your internal network, a proxy, or your logging infrastructure, they can see sensitive data in plain text.
+
+**The Solution:** Ephem ensures that sensitive fields (like Credit Card numbers, SSNs, Password changes) are encrypted **at the source** (the user's browser) and remain encrypted until they reach your **application logic**. Even if the TLS termination point is compromised, the attacker only sees Ephem capsules, which they cannot open.
+
+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.
+
+## Features
+
+-   **Zero-Trust Architecture**: Key material never leaves the server (private keys) or client (ephemeral symmetric keys) inappropriately.
+-   **Transport Agnostic**: Works over any protocol (HTTP, FTP, WebSockets, etc.) as the encryption happens before transmission.
+-   **Forward Secrecy**: Each request uses a unique, disposable key pair. Past captures of traffic cannot be decrypted even if the server is later compromised.
+-   **Hybrid Encryption**: Combines the convenience of RSA-2048 (for key exchange) with the speed of AES-256-GCM (for payload encryption).
+-   **Strict Lifecycle Management**: Capsules have hard expiration times and maximum usage counts.
+-   **Persistence Ready**: hooks for Redis, SQL, or other storage engines to support horizontal scaling.
+-   **Zero-Dependency Client**: The client library is extremely lightweight and uses the native WebCrypto API.
+-   **Typescript First**: Written in TypeScript with full type definitions.
+
+---
+
+## Installation
+
+```bash
+npm install ephem
+```
+
+---
+
+## Quick Start
+
+### 1. Server Setup (Node.js)
+
+Initialize Ephem and create an endpoint to issue capsules, and another to receive sealed data.
+
+```typescript
+import Ephem from "ephem";
+
+// Initialize with default in-memory storage
+const ephem = new Ephem({
+  inMemory: true,
+  logging: true,
+});
+
+// --- In your framework (Express, Fastify, etc.) ---
+
+// GET /api/capsule
+app.get('/api/capsule', async (req, res) => {
+  // Create a capsule that lives for 1 minute and can be opened once
+  const capsule = await ephem.createCapsulePromise({
+    maxOpens: 1,
+    lifetimeDurationMS: 60 * 1000
+  });
+
+  if (!capsule) return res.status(500).send("Failed to create capsule");
+  
+  // Send the PUBLIC key and Capsule ID (CID) to the client
+  res.json({
+    cid: capsule.cid,
+    publicKey: capsule.publicKey
+  });
+});
+
+// POST /api/submit
+app.post('/api/submit', async (req, res) => {
+  const { sealedPayload } = req.body;
+
+  // Attempt to open the capsule
+  const decryptedData = await ephem.open(sealedPayload);
+
+  if (!decryptedData) {
+    return res.status(400).send("Invalid, expired, or exhausted capsule.");
+  }
+
+  console.log("Received sensitive data:", decryptedData);
+  res.send("Data received securely.");
+});
+```
+
+### 1a. Server Setup (CommonJS)
+
+If you are using `require()` instead of `import`:
+
+```javascript
+const Ephem = require("ephem");
+
+// Initialize
+const ephem = new Ephem({
+  inMemory: true,
+  logging: true
+});
+
+// ... (Rest of usage is identical)
+```
+
+### 2. Client Setup (Browser)
+
+The client fetches a capsule and uses it to "seal" data before sending it.
+
+```typescript
+import { seal } from "ephem/client";
+
+async function submitSensitiveData(secretData: string) {
+  // 1. Get a fresh capsule from the server
+  const response = await fetch('/api/capsule');
+  const { cid, publicKey } = await response.json();
+
+  // 2. Seal the data locally (Browser WebCrypto)
+  // This generates an AES key, encrypts data, then wraps the AES key with the RSA public key
+  const sealedPayload = await seal(secretData, publicKey, cid);
+
+  // 3. Send securely
+  await fetch('/api/submit', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sealedPayload })
+  });
+}
+```
+
+### 3. Browser Usage (via CDN)
+
+For projects without a bundler, you can use the pre-built unpkg/CDN version. This exposes the global `EphemClient` object.
+
+```html
+<!-- Load Ephem client from CDN -->
+<script src="https://unpkg.com/ephem/dist/client/index.global.js"></script>
+
+<script>
+    "use strict";
+    // Example usage
+    async function runDemo() {
+        try {
+            // In a real app, fetch these from your server
+            const cid = "5a6d4d70-620a-472d-9edc-c9490ff77c2b"; 
+            const PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+-----END PUBLIC KEY-----`;
+
+            const message = "Hello from browser 👋";
+
+            // Encrypt using the global EphemClient
+            const cipher = await EphemClient.seal(
+                message,
+                PUBLIC_KEY_PEM,
+                cid,
+                // allowInsecureFallback: Set to true ONLY for local dev over HTTP
+                // In production (HTTPS), this should be false or omitted.
+                true, 
+            );
+
+            console.log("Cipher:", cipher);
+        } catch (err) {
+            console.error(err);
+        }
+    };
+</script>
+```
+
+---
+
+## How it Works
+
+Ephem uses a **Hybrid Encryption** scheme encapsulated in a "Capsule" paradigm.
+
+### Flow Diagram
+
+1.  **Handshake**:
+    *   **Server** generates an RSA-2048 KeyPair.
+    *   **Server** stores `PrivateKey` + `UsageLimits` (expiresAt, maxOpens) mapped to a `CID` (Capsule ID).
+    *   **Server** sends `PublicKey` + `CID` to Client.
+2.  **Sealing (Client)**:
+    *   **Client** generates a random AES-256-GCM key (`SymKey`).
+    *   **Client** encrypts the payload with `SymKey`.
+    *   **Client** encrypts `SymKey` with the Server's `PublicKey` (RSA-OAEP).
+    *   **Client** bundles `CID` + `IV` + `EncryptedPayload` + `EncryptedSymKey` into a single string.
+3.  **Opening (Server)**:
+    *   **Server** looks up internal state using `CID`.
+    *   **Server** checks: Is it expired? Has it been used too many times?
+    *   **Server** decrypts `SymKey` using `PrivateKey`.
+    *   **Server** decrypts payload using `SymKey`.
+    *   **Server** increments usage count / destroys capsule if exhausted.
+
+---
+
+
+
+## Use Cases
+
+### 1. Secure Form Submission (Standard)
+
+*   **Scenario:** User changes their password.
+*   **Flow:**
+    1.  Client fetches a capsule (`maxOpens: 1`).
+    2.  Client seals the new password.
+    3.  Client sends `sealedPassword` to server.
+    4.  Server opens it, hashes the password, and updates DB.
+
+### 2. Multi-Field Forms (Advanced)
+
+*   **Scenario:** A Checkout Form with `CreditCard`, `CVV`, and `SSN`.
+*   **Problem:** Requesting 3 separate capsules is slow.
+*   **Solution:** Request **one** capsule with `maxOpens: 3`.
+
+```typescript
+// Server: Issue a multi-use capsule
+const capsule = await ephem.createCapsulePromise({ maxOpens: 3, lifetimeDurationMS: 60000 });
+```
+
+```typescript
+// Client: Seal each field with the SAME capsule details
+const sealedCC  = await seal(ccNumber, pubKey, cid);
+const sealedCVV = await seal(cvv,      pubKey, cid);
+const sealedSSN = await seal(ssn,      pubKey, cid);
+
+// Send all three
+await fetch('/checkout', { body: JSON.stringify({ sealedCC, sealedCVV, sealedSSN }) });
+```
+
+> [!CAUTION]
+> **Concurrency Warning: Serial Unsealing**
+>
+> When opening multiple payloads from the same capsule, **you must unseal them serially** (one by one), especially if using a database like Redis for persistence.
+>
+> If you `Promise.all([open(a), open(b), open(c)])`, the parallel requests might race against the database's `openCount` check. One of them might read the "old" count before another has written the "new" count, causing you to accidentally exceed the limit or fail unpredictably.
+>
+> **Correct:**
+> ```typescript
+> // Server Code
+> const cc  = await ephem.open(req.body.sealedCC); // count becomes 1
+> const cvv = await ephem.open(req.body.sealedCVV); // count becomes 2
+> const ssn = await ephem.open(req.body.sealedSSN); // count becomes 3
+> ```
+
+---
+
+## Strengths & Weaknesses
+
+| Feature | Ephem Strength | Limitation / Weakness |
+| :--- | :--- | :--- |
+| **Security Model** | **Perfect Forward Secrecy.** Every request has a unique key. Compromising the server now does not compromise past traffic. | **Not a TLS Replacement.** Does not verify server identity (no Certificates). Vulnerable to active Man-in-the-Middle if TLS is missing. |
+| **Architecture** | **Zero-Trust.** Keys never leave their respective environments. | **Stateful.** Requires the server to "remember" the capsule (RAM or DB). Harder to scale than stateless JWTs. |
+| **Performance** | **Hybrid Encryption.** Fast AES-256 for payloads. | **RSA Overhead.** Generating 2048-bit RSA keys is CPU intensive. Not suitable for high-frequency "chat" messages. |
+| **Usability** | **Strict Types.** Full TypeScript support. Simple `seal()` / `open()` API. | **Payload Size.** Sealed strings are larger than plaintext due to base64 encoding and key wrapping. |
+| **Compliance** | **Auditable.** You define exactly where and when decryption happens. | **Key Management.** You are responsible for the persistence layer if scaling beyond one server. |
+| **Data Suitability** | **Optimized for Secrets.** Perfect for PII, API Keys, CC numbers, and passwords. | **Small Payloads Only.** Do **not** use for database dumps or file uploads. For >1MB files, use a streaming encryption library. |
+
+---
+
+## Threat Model
+
+### What Ephem PROTECTS Against
+
+*   **Compromised TLS Termination**: If your load balancer or CDN terminates TLS and passes unencrypted traffic to your backend, that traffic is vulnerable to internal snoopers. Ephem keeps it encrypted until it reaches your application logic.
+*   **Man-in-the-Middle (MITM)**: If a corporate proxy or malicious actor intercepts the request (even with a trusted root CA), they cannot read the payload because they lack the ephemeral private key, which never leaves your app server's memory.
+*   **Replay Attacks**: Because capsules have `maxOpens` (default: 1), a captured valid request cannot be replayed to trigger a second action (e.g., duplicate payment).
+*   **Accidental Logging**: If you accidentally log the raw request body, you are only logging ciphertext.
+
+### What Ephem Does NOT Protect Against
+
+*   **XSS (Cross-Site Scripting)**: If an attacker can run JS on your page, they can hook the `seal()` function or read the input before it is sealed.
+*   **Compromised Server**: If the attacker controls your server, they can access the memory where private keys are stored (temporarily).
+*   **Compromised Client Device**: Keyloggers or malware on the user's machine.
+
+---
+
+## API Reference
+
+### `new Ephem(config)`
+
+Creates a new Ephem instance.
+
+```typescript
+const ephem = new Ephem({
+  inMemory: true,
+  maxConcurrentCapsules: 1000,
+  logging: true
+});
+```
+
+**Configuration Options:**
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| **`inMemory`** | `boolean` | `true` | If `true`, store capsules in a JS Map. If `false`, you **must** provide the persistence hooks. |
+| **`maxConcurrentCapsules`** | `number` | `Infinity` | **DoS Protection.** Limits the maximum number of active capsules in memory. If creating a new capsule would exceed this, `createCapsule` returns `null`. |
+| **`defaultCaptsuleLifetimeMS`** | `number` | `Infinity` | Default duration before a capsule expires. Prevents stale keys from lingering forever. |
+| **`capsuleCleanupIntervalMS`** | `number` | `60_000` | How often the internal "reaper" runs to delete expired/exhausted capsules from memory. |
+| **`logging`** | `boolean` | `false` | Enable verbose internal logs. Useful for debugging but spammy in production. |
+| **`onCapsuleCreation`** | `Function` | `undefined` | **Persistence Hook.** Called when a capsule is created. Signature: `(cid, privateKey, openCount, maxOpens, expiresAt)`. Return `true` to confirm storage. |
+| **`onCapsuleOpen`** | `Function` | `undefined` | **Persistence Hook.** Called after a successful decryption. Signature: `(cid, openCount)`. Return `true` on success. |
+| **`OnGetCapsuleByCID`** | `Function` | `undefined` | **Persistence Hook.** Retrieve capsule. Signature: `(cid)`. Returns `{ privateKey, maxOpens, openCount, expiresAt }` or `null`. |
+| **`onCapsuleDelete`** | `Function` | `undefined` | **Persistence Hook.** Called to delete/expire. Signature: `(cid, reason)`. Reason is `'expired'` or `'max_opened'`. |
+
+---
+
+### `ephem.createCapsulePromise(config)`
+
+Creates a new capsule and returns a Promise resolving to the public details.
+
+**Parameters:**
+*   `config.maxOpens` (number, default `0`): The number of times this capsule can be decrypted. `0` usually means infinite (depending on your logic), but `1` is recommended for strict one-time use.
+*   `config.lifetimeDurationMS` (number): Milliseconds until the capsule expires.
+
+**Returns:**
+*   `Promise<{ cid: string, publicKey: string } | null>`
+*   Returns `null` if the capsule could not be created (e.g., `maxConcurrentCapsules` limit reached or storage failure).
+
+---
+
+### `ephem.open(sealedPayload)`
+
+Attempts to decrypt a sealed payload.
+
+**Parameters:**
+*   `sealedPayload` (string): The dot-separated string generated by the client.
+
+**Returns:**
+*   `Promise<string | null>`
+*   Returns the **decrypted plaintext** string if successful.
+*   Returns `null` if:
+    *   The capsule ID (CID) is not found.
+    *   The capsule has expired.
+    *   The capsule has exceeded its `maxOpens` count.
+    *   The decryption fails (wrong key, tampering detected).
+
+    *   The decryption fails (wrong key, tampering detected).
+
+---
+
+### `ephem.getAnalytics()`
+
+Returns a snapshot of the usage stats since the instance started.
+
+**Returns:**
+*   `{ totalCreatedCapsules: number, totalUsedCapsules: number, totalExpiredCapsules: number }`
+
+---
+
+### `seal(text, publicKey, cid, allowInsecureFallback)` (Client)
+
+The core client-side encryption function. Available in `ephem/client` (Node/Bundlers) or `EphemClient.seal` (CDN).
+
+**Parameters:**
+*   **`text`** (string): The sensitive data to encrypt.
+*   **`publicKey`** (string): The PEM-formatted public key string received from the server.
+*   **`cid`** (string): The Capsule ID to attach to this payload.
+*   **`allowInsecureFallback`** (boolean, default `false`):
+    *   **Crucial for Development.** WebCrypto is **only** available in Secure Contexts (HTTPS or `localhost`).
+    *   If you are testing on HTTP (e.g., a local network IP `http://192.168.x.x`), WebCrypto will throw an error and the client will crash.
+    *   **Effect:** Setting this to `true` causes the client to bypass encryption entirely. It sends the plaintext data prefixed with `##INSECURE##`.
+    *   **SECURITY WARNING:** **Data is NOT encrypted in this mode.** This is strictly for debugging connectivity in non-HTTPS development environments. **NEVER** enable this in production.
+
+---
+
+### Full Redis Implementation
+
+To scale Ephem across multiple server instances, you must use an external store like Redis.
+
+You must implement **all 4 hooks**.
+
+```typescript
+import Ephem from "ephem";
+import Redis from "ioredis";
+
+const redis = new Redis();
+const getKey = (cid: string) => `ephem:capsule:${cid}`;
+
+const ephem = new Ephem({
+  inMemory: false,
+
+  /**
+   * Hook 1: Creation
+   * Store the new capsule, including the PRIVATE KEY.
+   */
+  onCapsuleCreation: async (cid, privateKey, openCount, maxOpens, expiresAt) => {
+    try {
+      await redis.hset(getKey(cid), {
+        privateKey, // <--- CRITICAL: Store this securely!
+        openCount,
+        maxOpens,
+        expiresAt
+      });
+
+      // Set Redis TTL so it auto-deletes roughly when the capsule expires
+      if (expiresAt !== Infinity) {
+        const ttlSeconds = Math.ceil((expiresAt - Date.now()) / 1000);
+        if (ttlSeconds > 0) {
+          await redis.expire(getKey(cid), ttlSeconds);
+        }
+      }
+      return true;
+    } catch (err) {
+      console.error("Redis error on creation:", err);
+      return false; // Returning false will cause createCapsule to return null
+    }
+  },
+
+  /**
+   * Hook 2: Retrieval
+   * Fetch the capsule state so Ephem can decrypt the payload.
+   */
+  OnGetCapsuleByCID: async (cid) => {
+    try {
+      const data = await redis.hgetall(getKey(cid));
+      
+      // If empty or missing private key, return null
+      if (!data || !data.privateKey) return null;
+
+      return {
+        privateKey: data.privateKey,
+        maxOpens: Number(data.maxOpens),
+        openCount: Number(data.openCount),
+        expiresAt: Number(data.expiresAt)
+      };
+    } catch (err) {
+      console.error("Redis error on get:", err);
+      return null;
+    }
+  },
+
+  /**
+   * Hook 3: Open (Usage Update)
+   * Called AFTER a successful decryption. We must increment the usage count in DB.
+   */
+  onCapsuleOpen: async (cid, openCount) => {
+    try {
+      // Ephem tracks the new 'openCount' in memory and passes it here.
+      // We just need to persist it.
+      await redis.hset(getKey(cid), "openCount", openCount);
+      return true;
+    } catch (err) {
+      console.error("Redis error on update:", err);
+      return false;
+    }
+  },
+
+  /**
+   * Hook 4: Deletion
+   * Explicit cleanup (e.g., if maxOpens reached).
+   */
+  onCapsuleDelete: async (cid, reason) => {
+    // Reason is 'expired' or 'max_opened'
+    try {
+      await redis.del(getKey(cid));
+      console.log(`Deleted capsule ${cid} due to ${reason}`);
+    } catch (err) {
+      console.error("Redis error on delete:", err);
+    }
+  }
+});
+```
+
+## Contributing
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+[ISC](/LICENSE)

package/dist/client/index.d.mts

@@ -0,0 +1,3 @@
+declare function seal(text: string, publicKeyPem: string, cid: string, allowInsecureFallback?: boolean): Promise<string>;
+
+export { seal };

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+declare function seal(text: string, publicKeyPem: string, cid: string, allowInsecureFallback?: boolean): Promise<string>;
+
+export { seal };

package/dist/client/index.js

@@ -0,0 +1,88 @@
+"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/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  seal: () => seal
+});
+module.exports = __toCommonJS(client_exports);
+function pemToArrayBuffer(pem) {
+  const b64 = pem.replace(/-----BEGIN PUBLIC KEY-----/, "").replace(/-----END PUBLIC KEY-----/, "").replace(/\s+/g, "");
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+function base64Encode(data) {
+  const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i] || 0);
+  }
+  return btoa(binary);
+}
+async function seal(text, publicKeyPem, cid, allowInsecureFallback = false) {
+  if (!globalThis.crypto?.subtle) {
+    if (allowInsecureFallback) {
+      return `##INSECURE##${text}`;
+    } else {
+      throw new Error("EphemClient requires a secure context (HTTPS or localhost).");
+    }
+  }
+  const subtle = globalThis.crypto.subtle;
+  const enc = new TextEncoder();
+  const symKey = await subtle.generateKey(
+    { name: "AES-GCM", length: 256 },
+    true,
+    ["encrypt"]
+  );
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: enc.encode(cid) },
+    symKey,
+    enc.encode(text)
+  );
+  const publicKey = await subtle.importKey(
+    "spki",
+    pemToArrayBuffer(publicKeyPem),
+    { name: "RSA-OAEP", hash: "SHA-256" },
+    false,
+    ["encrypt"]
+  );
+  const rawSymKey = await subtle.exportKey("raw", symKey);
+  const encryptedSymKey = await subtle.encrypt(
+    { name: "RSA-OAEP" },
+    publicKey,
+    rawSymKey
+  );
+  return [
+    cid,
+    base64Encode(iv),
+    base64Encode(ciphertext),
+    base64Encode(encryptedSymKey)
+  ].join(".");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  seal
+});
+if (module.exports.default) { module.exports = module.exports.default; }

package/dist/client/index.mjs

@@ -0,0 +1,63 @@
+// src/client/index.ts
+function pemToArrayBuffer(pem) {
+  const b64 = pem.replace(/-----BEGIN PUBLIC KEY-----/, "").replace(/-----END PUBLIC KEY-----/, "").replace(/\s+/g, "");
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+function base64Encode(data) {
+  const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i] || 0);
+  }
+  return btoa(binary);
+}
+async function seal(text, publicKeyPem, cid, allowInsecureFallback = false) {
+  if (!globalThis.crypto?.subtle) {
+    if (allowInsecureFallback) {
+      return `##INSECURE##${text}`;
+    } else {
+      throw new Error("EphemClient requires a secure context (HTTPS or localhost).");
+    }
+  }
+  const subtle = globalThis.crypto.subtle;
+  const enc = new TextEncoder();
+  const symKey = await subtle.generateKey(
+    { name: "AES-GCM", length: 256 },
+    true,
+    ["encrypt"]
+  );
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: enc.encode(cid) },
+    symKey,
+    enc.encode(text)
+  );
+  const publicKey = await subtle.importKey(
+    "spki",
+    pemToArrayBuffer(publicKeyPem),
+    { name: "RSA-OAEP", hash: "SHA-256" },
+    false,
+    ["encrypt"]
+  );
+  const rawSymKey = await subtle.exportKey("raw", symKey);
+  const encryptedSymKey = await subtle.encrypt(
+    { name: "RSA-OAEP" },
+    publicKey,
+    rawSymKey
+  );
+  return [
+    cid,
+    base64Encode(iv),
+    base64Encode(ciphertext),
+    base64Encode(encryptedSymKey)
+  ].join(".");
+}
+export {
+  seal
+};
+if (module.exports.default) { module.exports = module.exports.default; }