memorio 5.0.0 → 5.1.0

package/markdown/TYPED.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/USEOBSERVER.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/modules/redux.cjs

@@ -201,6 +201,241 @@ var init_message = __esm({
   }
 });
 
+// functions/encryption/index.ts
+function _hasWebCrypto() {
+  const g2 = globalThis;
+  return typeof g2.crypto !== "undefined" && typeof g2.crypto.subtle !== "undefined" && typeof g2.crypto.subtle.encrypt === "function";
+}
+function _b64encode(buf) {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  if (typeof btoa === "function") {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+  }
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  return "";
+}
+function _b64decode(b64) {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(b64, "base64"));
+  }
+  if (typeof atob === "function") {
+    const binary = atob(b64);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+    return out;
+  }
+  throw new Error("memorio encryption: no base64 decoder available");
+}
+function _isEncrypted(value) {
+  return typeof value === "object" && value !== null && value.__memorio_encrypted === true && typeof value.alg === "string";
+}
+var AES_GCM, PBKDF2_ITERATIONS, encryption;
+var init_encryption = __esm({
+  "functions/encryption/index.ts"() {
+    init_cjs_shims();
+    init_env();
+    init_message();
+    __name(_hasWebCrypto, "_hasWebCrypto");
+    __name(_b64encode, "_b64encode");
+    __name(_b64decode, "_b64decode");
+    __name(_isEncrypted, "_isEncrypted");
+    AES_GCM = { name: "AES-GCM", length: 256 };
+    PBKDF2_ITERATIONS = 6e5;
+    encryption = {
+      ///
+      // Capability detection
+      ///
+      isAvailable() {
+        return _hasWebCrypto();
+      },
+      ///
+      // Derive a CryptoKey from a password using PBKDF2.
+      //
+      // @param password The password string.
+      // @param salt     Salt (string or Uint8Array). Defaults to a static value.
+      // @param alg      'AES-GCM' (default) or 'AES-CBC'.
+      // @returns        A Promise<CryptoKey>.
+      ///
+      async deriveKey(password, salt, alg = "AES-GCM", iterations = PBKDF2_ITERATIONS) {
+        if (!_hasWebCrypto()) {
+          throw new Error("memorio encryption: Web Crypto API is not available in this environment");
+        }
+        const enc = new TextEncoder();
+        const saltBytes = typeof salt === "string" ? enc.encode(salt) : salt ?? enc.encode("memorio:salt");
+        const keyMaterial = await globalThis.crypto.subtle.importKey(
+          "raw",
+          enc.encode(password),
+          { name: "PBKDF2" },
+          false,
+          ["deriveKey"]
+        );
+        return globalThis.crypto.subtle.deriveKey(
+          { name: "PBKDF2", salt: saltBytes, iterations, hash: "SHA-256" },
+          keyMaterial,
+          { name: alg, length: 256 },
+          false,
+          ["encrypt", "decrypt"]
+        );
+      },
+      ///
+      // Generate a fresh random CryptoKey (AES-GCM, 256-bit).
+      ///
+      async generateKey(alg = "AES-GCM") {
+        if (!_hasWebCrypto()) {
+          throw new Error("memorio encryption: Web Crypto API is not available in this environment");
+        }
+        return globalThis.crypto.subtle.generateKey(
+          { name: alg, length: 256 },
+          true,
+          ["encrypt", "decrypt"]
+        );
+      },
+      ///
+      // Generate a random salt for PBKDF2 key derivation.
+      ///
+      generateSalt(bytes = 16) {
+        const arr = new Uint8Array(bytes);
+        globalThis.crypto?.getRandomValues?.(arr);
+        return _b64encode(arr);
+      },
+      ///
+      // Export a CryptoKey to portable base64 strings so it can be stored
+      // (e.g. in an httpOnly cookie) and re-imported later with importKey().
+      //
+      // @param cryptoKey A raw CryptoKey (not a password string).
+      // @returns         { key: string, iv: string } base64-encoded.
+      ///
+      async exportKey(cryptoKey) {
+        if (!_hasWebCrypto()) {
+          throw new Error("memorio encryption: Web Crypto API is not available in this environment");
+        }
+        const exported = await globalThis.crypto.subtle.exportKey("raw", cryptoKey);
+        return {
+          key: _b64encode(exported),
+          iv: ""
+        };
+      },
+      ///
+      // Import a CryptoKey from base64 strings produced by exportKey().
+      //
+      // @param keyData Base64-encoded raw key bytes.
+      // @param _ivData Ignored (kept for API compatibility with exportKey return).
+      // @returns       A Promise<CryptoKey>.
+      ///
+      async importKey(keyData, _ivData) {
+        if (!_hasWebCrypto()) {
+          throw new Error("memorio encryption: Web Crypto API is not available in this environment");
+        }
+        const keyBytes = _b64decode(keyData);
+        if (keyBytes.length !== 32) {
+          throw new Error(`memorio encryption: AES-256 key must be exactly 32 bytes, got ${keyBytes.length}`);
+        }
+        return globalThis.crypto.subtle.importKey(
+          "raw",
+          keyBytes,
+          AES_GCM,
+          true,
+          ["encrypt", "decrypt"]
+        );
+      },
+      ///
+      // Encrypt a JavaScript value.
+      //
+      // @param value The value to encrypt (any JSON-serializable object).
+      // @param key   A CryptoKey or a password string (password is derived via PBKDF2).
+      // @param keyId Optional label, stored in the envelope for key rotation.
+      // @returns     An EncryptedEnvelope object.
+      ///
+      async encrypt(value, key, keyId) {
+        const cryptoKey = typeof key === "string" ? await this.deriveKey(key, void 0, "AES-GCM") : key;
+        const data = new TextEncoder().encode(JSON.stringify(value));
+        const iv = new Uint8Array(12);
+        globalThis.crypto.getRandomValues(iv);
+        const ciphertext = await globalThis.crypto.subtle.encrypt(
+          { name: "AES-GCM", iv },
+          cryptoKey,
+          data
+        );
+        const envelope = {
+          __memorio_encrypted: true,
+          v: 1,
+          alg: "AES-GCM",
+          iv: _b64encode(iv),
+          data: _b64encode(ciphertext)
+        };
+        if (keyId) envelope.keyId = keyId;
+        if (DEV) message_default(`encryption: encrypted value (alg=${envelope.alg})`);
+        return envelope;
+      },
+      ///
+      // Decrypt an EncryptedEnvelope.
+      //
+      // @param envelope The envelope object returned by encrypt().
+      // @param key      A CryptoKey or a password string.
+      // @returns        The original value (parsed from JSON).
+      ///
+      async decrypt(envelope, key) {
+        if (!_isEncrypted(envelope)) {
+          throw new Error("memorio encryption: value is not a valid encrypted envelope");
+        }
+        const cryptoKey = typeof key === "string" ? await this.deriveKey(key, void 0, "AES-GCM") : key;
+        const iv = _b64decode(envelope.iv);
+        const data = _b64decode(envelope.data);
+        const decrypted = await globalThis.crypto.subtle.decrypt(
+          { name: "AES-GCM", iv },
+          cryptoKey,
+          data
+        );
+        return JSON.parse(new TextDecoder().decode(new Uint8Array(decrypted)));
+      },
+      ///
+      // Convenience: encrypt with a password (derives the key internally).
+      // Returns a JSON string you can store anywhere.
+      ///
+      async encryptWithPassword(value, password, salt, keyId) {
+        const env = await this.encrypt(value, password, keyId);
+        return JSON.stringify(env);
+      },
+      ///
+      // Convenience: decrypt a JSON envelope string with a password.
+      ///
+      async decryptWithPassword(envelopeJson, password, _salt) {
+        const envelope = JSON.parse(envelopeJson);
+        return this.decrypt(envelope, password);
+      },
+      ///
+      // Type guard: check whether a value is an encrypted envelope.
+      ///
+      isEncrypted(value) {
+        return _isEncrypted(value);
+      },
+      ///
+      // Configure a default encryption key for auto-encrypt mode.
+      // When set on `store` or `session`, all writes are encrypted and all
+      // reads attempt decryption automatically.
+      ///
+      config(opts) {
+        if (opts.key !== void 0) this._defaultKey = opts.key;
+        if (opts.keyId !== void 0) this._defaultKeyId = opts.keyId;
+        return this;
+      },
+      ///
+      // Internal: resolve the configured default key.
+      ///
+      get _key() {
+        return this._defaultKey ?? null;
+      },
+      get _keyId() {
+        return this._defaultKeyId;
+      }
+    };
+  }
+});
+
 // core/platform.ts
 function getSessionStorage() {
   try {
@@ -237,6 +472,7 @@ var init_platform = __esm({
   "core/platform.ts"() {
     init_cjs_shims();
     init_internal();
+    init_encryption();
     __name(getSessionStorage, "getSessionStorage");
     __name(getLocalStorage, "getLocalStorage");
     __name(hasIndexedDB, "hasIndexedDB");
@@ -967,6 +1203,7 @@ init_cjs_shims();
 init_platform();
 init_internal();
 init_message();
+init_encryption();
 var _localStorage = getLocalStorage();
 var _fallbackStorageByContext = /* @__PURE__ */ new Map();
 function _getFallbackStorage() {
@@ -979,6 +1216,14 @@ function _getFallbackStorage() {
 }
 __name(_getFallbackStorage, "_getFallbackStorage");
 var _hasStorage = _localStorage !== null;
+var _encryptionKey = null;
+var _onError = null;
+var _maxObjectSize = 0;
+var _maxTotalSize = 0;
+function _isEncryptedEnvelope(value) {
+  return encryption.isEncrypted(value);
+}
+__name(_isEncryptedEnvelope, "_isEncryptedEnvelope");
 function _getPrefix() {
   const contextName = internal_default.currentContext || "";
   return contextName ? `${contextName}-` : `memorio_store_`;
@@ -1032,16 +1277,24 @@ if (globalThis[STORE_INSTANCE_KEY]) {
       /**
        * Gets a value from storage.
        * @param name The key to retrieve.
-       * @returns The parsed value or null if not found.
+       * @param opts Optional { decrypt: key } to decrypt an encrypted envelope.
+       *              When no key is passed, encrypted envelopes are returned as-is.
+       *              If a default key was configured via store.config(), it is used automatically.
+       * @returns The parsed value, a Promise<parsed value> when decrypting, or null if not found.
        */
       get: {
-        value: /* @__PURE__ */ __name((name) => {
+        value: /* @__PURE__ */ __name((name, opts) => {
           if (!name) {
             console.warn("[memorio store] store.get() called with empty or null key - returning null");
             return null;
           }
           try {
-            return _read(_prefixKey(name));
+            const raw = _read(_prefixKey(name));
+            const key = opts?.decrypt ?? _encryptionKey;
+            if (key && _isEncryptedEnvelope(raw)) {
+              return encryption.decrypt(raw, key);
+            }
+            return raw;
           } catch (err) {
             message(`Error parsing store item '${name}': ${err}`);
           }
@@ -1066,10 +1319,13 @@ if (globalThis[STORE_INSTANCE_KEY]) {
        * Sets a value in storage.
        * @param name The key to set.
        * @param value The value to store (objects, arrays, primitives).
-       * @returns true if written, false if the key was rejected.
+       * @param opts Optional { encrypt: key } to encrypt the value before storage.
+       *              If a default key was configured via store.config(), it is used automatically.
+       *              When encryption is used, returns a Promise<boolean>.
+       * @returns true if written, false if rejected or error.
        */
       set: {
-        value: /* @__PURE__ */ __name((name, value) => {
+        value: /* @__PURE__ */ __name((name, value, opts) => {
           if (!name) {
             console.warn("[memorio store] store.set() called with empty or null key - write aborted");
             return false;
@@ -1081,15 +1337,66 @@ if (globalThis[STORE_INSTANCE_KEY]) {
             message("Storing functions is not secure and is blocked for safety.");
             return false;
           }
+          if (_maxObjectSize > 0 || _maxTotalSize > 0) {
+            let serializedSize = 0;
+            try {
+              serializedSize = new TextEncoder().encode(JSON.stringify(value)).length;
+            } catch {
+              serializedSize = 0;
+            }
+            if (_maxObjectSize > 0 && serializedSize > _maxObjectSize) {
+              const err = new Error(`Object size (${serializedSize} bytes) exceeds maxObjectSize (${_maxObjectSize} bytes)`);
+              _onError?.(err, { operation: "set" });
+              return false;
+            }
+            if (_maxTotalSize > 0) {
+              const currentTotal = store.size() * 1024;
+              const existingItemSize = _hasStorage ? _localStorage.getItem(prefixedName)?.length ?? 0 : _getFallbackStorage().get(prefixedName)?.length ?? 0;
+              const projected = currentTotal * 1024 - existingItemSize + serializedSize;
+              if (projected > _maxTotalSize) {
+                const err = new Error(`Total store size (${projected} bytes) exceeds maxTotalSize (${_maxTotalSize} bytes)`);
+                _onError?.(err, { operation: "set" });
+                return false;
+              }
+            }
+          }
+          const key = opts?.encrypt ?? _encryptionKey;
+          if (key) {
+            return encryption.encrypt(value, key).then((env) => {
+              _write(prefixedName, env);
+              return true;
+            }).catch((err) => {
+              message(`Error encrypting store item '${name}': ${err}`);
+              _onError?.(err, { operation: "set" });
+              return false;
+            });
+          }
           try {
             _write(prefixedName, value);
           } catch (err) {
             message(`Error setting store item '${name}': ${err}`);
+            _onError?.(err, { operation: "set" });
             return false;
           }
           return true;
         }, "value")
       },
+      /**
+       * Configure store-wide behavior.
+       * @param opts Optional { encryptionKey } to enable automatic encryption
+       *              for all set/get operations. When set, values are encrypted
+       *              on write and decrypted on read (if the value is an envelope).
+       * @returns The store instance for chaining.
+       */
+      config: {
+        value: /* @__PURE__ */ __name((opts) => {
+          if (opts.encryptionKey !== void 0) _encryptionKey = opts.encryptionKey;
+          if (opts.onError !== void 0) _onError = opts.onError;
+          if (opts.maxObjectSize !== void 0) _maxObjectSize = opts.maxObjectSize;
+          if (opts.maxTotalSize !== void 0) _maxTotalSize = opts.maxTotalSize;
+          return store;
+        }, "value")
+      },
       /**
        * Removes a value from storage.
        * @param name The key to remove.
@@ -1761,6 +2068,7 @@ init_cjs_shims();
 init_platform();
 init_internal();
 init_message();
+init_encryption();
 var _sessionStorage = getSessionStorage();
 var _fallbackStorageByContext2 = /* @__PURE__ */ new Map();
 function _getFallbackStorage2() {
@@ -1773,6 +2081,14 @@ function _getFallbackStorage2() {
 }
 __name(_getFallbackStorage2, "_getFallbackStorage");
 var _hasStorage2 = _sessionStorage !== null;
+var _encryptionKey2 = null;
+var _onError2 = null;
+var _maxObjectSize2 = 0;
+var _maxTotalSize2 = 0;
+function _isEncryptedEnvelope2(value) {
+  return encryption.isEncrypted(value);
+}
+__name(_isEncryptedEnvelope2, "_isEncryptedEnvelope");
 function _getPrefix2() {
   const contextName = internal_default.currentContext || "";
   return contextName ? `${contextName}-` : `memorio_session_`;
@@ -1826,16 +2142,22 @@ if (globalThis[SESSION_INSTANCE_KEY]) {
       /**
        * Gets a value from storage.
        * @param name The key to retrieve.
-       * @returns The parsed value or null if not found.
+       * @param opts Optional { decrypt: key } to decrypt an encrypted envelope.
+       * @returns The parsed value, a Promise when decrypting, or null if not found.
        */
       get: {
-        value: /* @__PURE__ */ __name((name) => {
+        value: /* @__PURE__ */ __name((name, opts) => {
           if (!name) {
             console.warn("[memorio session] session.get() called with empty or null key - returning null");
             return null;
           }
           try {
-            return _read2(_prefixKey2(name));
+            const raw = _read2(_prefixKey2(name));
+            const key = opts?.decrypt ?? _encryptionKey2;
+            if (key && _isEncryptedEnvelope2(raw)) {
+              return encryption.decrypt(raw, key);
+            }
+            return raw;
           } catch (err) {
             message(`Error parsing session item '${name}':${err}`);
           }
@@ -1846,10 +2168,11 @@ if (globalThis[SESSION_INSTANCE_KEY]) {
        * Sets a value in storage.
        * @param name The key to set.
        * @param value The value to store.
-       * @returns true if written, false if the key was rejected.
+       * @param opts Optional { encrypt: key } to encrypt before storage.
+       * @returns true if written, false if rejected. Returns a Promise when encrypting.
        */
       set: {
-        value: /* @__PURE__ */ __name((name, value) => {
+        value: /* @__PURE__ */ __name((name, value, opts) => {
           if (!name) {
             console.warn("[memorio session] session.set() called with empty or null key - write aborted");
             return false;
@@ -1861,15 +2184,63 @@ if (globalThis[SESSION_INSTANCE_KEY]) {
             message("It's not secure to session functions.");
             return false;
           }
+          if (_maxObjectSize2 > 0 || _maxTotalSize2 > 0) {
+            let serializedSize = 0;
+            try {
+              serializedSize = new TextEncoder().encode(JSON.stringify(value)).length;
+            } catch {
+              serializedSize = 0;
+            }
+            if (_maxObjectSize2 > 0 && serializedSize > _maxObjectSize2) {
+              const err = new Error(`Object size (${serializedSize} bytes) exceeds maxObjectSize (${_maxObjectSize2} bytes)`);
+              _onError2?.(err, { operation: "set" });
+              return false;
+            }
+            if (_maxTotalSize2 > 0) {
+              const currentTotal = session.size() * 1024;
+              const existingItemSize = _sessionStorage ? _sessionStorage.getItem(prefixedName)?.length ?? 0 : _getFallbackStorage2().get(prefixedName)?.length ?? 0;
+              const projected = currentTotal - existingItemSize + serializedSize;
+              if (projected > _maxTotalSize2) {
+                const err = new Error(`Total session size (${projected} bytes) exceeds maxTotalSize (${_maxTotalSize2} bytes)`);
+                _onError2?.(err, { operation: "set" });
+                return false;
+              }
+            }
+          }
+          const key = opts?.encrypt ?? _encryptionKey2;
+          if (key) {
+            return encryption.encrypt(value, key).then((env) => {
+              _write2(prefixedName, env);
+              return true;
+            }).catch((err) => {
+              message(`Error encrypting session item '${name}': ${err}`);
+              _onError2?.(err, { operation: "set" });
+              return false;
+            });
+          }
           try {
             _write2(prefixedName, value);
           } catch (err) {
             message(`Error setting session item '${name}': ${err}`);
+            _onError2?.(err, { operation: "set" });
             return false;
           }
           return true;
         }, "value")
       },
+      /**
+       * Configure session-wide behavior.
+       * @param opts { encryptionKey, onError, maxObjectSize, maxTotalSize }
+       */
+      config: {
+        value: /* @__PURE__ */ __name((opts) => {
+          if (opts.encryptionKey !== void 0) _encryptionKey2 = opts.encryptionKey;
+          if (opts.onError !== void 0) _onError2 = opts.onError;
+          if (opts.maxObjectSize !== void 0) _maxObjectSize2 = opts.maxObjectSize;
+          if (opts.maxTotalSize !== void 0) _maxTotalSize2 = opts.maxTotalSize;
+          return session;
+        }, "value")
+      },
       /**
        * Removes a value from storage.
        * @param name The key to remove.