@verbeth/sdk 0.1.16 → 0.2.0

package/dist/esm/src/ratchet/decrypt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decrypt.d.ts","sourceRoot":"","sources":["../../../../src/ratchet/decrypt.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,cAAc,EACd,aAAa,EACb,aAAa,EAKd,MAAM,YAAY,CAAC;AAGpB;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,UAAU,GACrB,aAAa,GAAG,IAAI,CA4EtB;AAgKD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,MAA4B,GACrC,cAAc,CAyBhB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,KAAK,MAAM,EAAE,GACnB,SAAS,GAAG,UAAU,GAAG,IAAI,CAY/B"}
+{"version":3,"file":"decrypt.d.ts","sourceRoot":"","sources":["../../../../src/ratchet/decrypt.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,cAAc,EACd,aAAa,EACb,aAAa,EAKd,MAAM,YAAY,CAAC;AAIpB;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,UAAU,GACrB,aAAa,GAAG,IAAI,CAkFtB;AAqKD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,MAA4B,GACrC,cAAc,CAyBhB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,KAAK,MAAM,EAAE,GACnB,SAAS,GAAG,UAAU,GAAG,IAAI,CAY/B"}

package/dist/esm/src/ratchet/decrypt.js

@@ -12,6 +12,7 @@ import nacl from 'tweetnacl';
 import { hexlify } from 'ethers';
 import { MAX_SKIP_PER_MESSAGE, MAX_STORED_SKIPPED_KEYS, TOPIC_TRANSITION_WINDOW_MS, } from './types.js';
 import { kdfRootKey, kdfChainKey, dh, generateDHKeyPair, deriveTopic } from './kdf.js';
+import { unpadPlaintext } from './padding.js';
 /**
  * Decrypt a message using the ratchet.
  *
@@ -69,7 +70,12 @@ export function ratchetDecrypt(session, header, ciphertext) {
     if (!plaintext) {
         return null;
     }
-    // 8. Update session state
+    // 8. Unpad plaintext
+    const unpadded = unpadPlaintext(plaintext);
+    if (!unpadded) {
+        return null;
+    }
+    // 9. Update session state
     newSession = {
         ...newSession,
         receivingChainKey: newReceivingChainKey,
@@ -78,7 +84,7 @@ export function ratchetDecrypt(session, header, ciphertext) {
     };
     return {
         session: newSession,
-        plaintext,
+        plaintext: unpadded,
     };
 }
 /**
@@ -173,6 +179,10 @@ function trySkippedKeys(session, dhPubHex, msgNumber, ciphertext) {
     if (!plaintext) {
         return null;
     }
+    const unpadded = unpadPlaintext(plaintext);
+    if (!unpadded) {
+        return null;
+    }
     const newSkippedKeys = [...session.skippedKeys];
     newSkippedKeys.splice(idx, 1);
     // Wipe the key
@@ -187,7 +197,7 @@ function trySkippedKeys(session, dhPubHex, msgNumber, ciphertext) {
             skippedKeys: newSkippedKeys,
             updatedAt: Date.now(),
         },
-        plaintext,
+        plaintext: unpadded,
     };
 }
 /**

package/dist/esm/src/ratchet/encrypt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../../../../src/ratchet/encrypt.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG1E;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAM9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,UAAU,EACrB,gBAAgB,EAAE,UAAU,GAC3B,aAAa,CAqDf"}
+{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../../../../src/ratchet/encrypt.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI1E;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAM9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,UAAU,EACrB,gBAAgB,EAAE,UAAU,GAC3B,aAAa,CAwDf"}

package/dist/esm/src/ratchet/encrypt.js

@@ -10,6 +10,7 @@
  */
 import nacl from 'tweetnacl';
 import { kdfChainKey } from './kdf.js';
+import { padPlaintext } from './padding.js';
 /**
  * Encode message header as 40 bytes for signing.
  * Format: dh (32) + pn (4, BE) + n (4, BE)
@@ -42,9 +43,15 @@ export function ratchetEncrypt(session, plaintext, signingSecretKey) {
         pn: session.previousChainLength,
         n: session.sendingMsgNumber,
     };
-    // 3. Encrypt with message key using XSalsa20-Poly1305
+    // 3. Pad plaintext and encrypt with message key using XSalsa20-Poly1305
+    const padded = padPlaintext(plaintext);
     const nonce = nacl.randomBytes(nacl.secretbox.nonceLength); // 24 bytes
-    const ciphertext = nacl.secretbox(plaintext, nonce, messageKey);
+    const ciphertext = nacl.secretbox(padded, nonce, messageKey);
+    // Wipe padded buffer after encryption
+    try {
+        padded.fill(0);
+    }
+    catch { }
     // 4. Combine nonce + ciphertext
     const encryptedPayload = new Uint8Array(nonce.length + ciphertext.length);
     encryptedPayload.set(nonce, 0);

package/dist/esm/src/ratchet/padding.d.ts

@@ -0,0 +1,23 @@
+export declare const PADDING_MARKER = 0;
+export declare const LENGTH_PREFIX_SIZE = 4;
+export declare const FRAMING_SIZE: number;
+export declare const MIN_BUCKET = 64;
+export declare const MAX_EXPONENTIAL_BUCKET = 16384;
+export declare const LINEAR_STEP = 4096;
+export declare const JITTER_FRACTION = 8;
+/**
+ * Generate a uniform random integer in [0, max) using rejection sampling
+ */
+export declare function secureRandomInt(max: number): number;
+/**
+ * Pad plaintext into a fixed-size envelope before encryption.
+ *
+ * Format: [0x00 marker] [plaintext_length (4 bytes BE)] [plaintext] [random padding]
+ */
+export declare function padPlaintext(plaintext: Uint8Array): Uint8Array;
+/**
+ * Remove padding from a decrypted envelope. Strict validation —
+ * returns null on any malformed envelope.
+ */
+export declare function unpadPlaintext(decrypted: Uint8Array): Uint8Array | null;
+//# sourceMappingURL=padding.d.ts.map

package/dist/esm/src/ratchet/padding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"padding.d.ts","sourceRoot":"","sources":["../../../../src/ratchet/padding.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,cAAc,IAAO,CAAC;AACnC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,YAAY,QAAyB,CAAC;AACnD,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAC5C,eAAO,MAAM,WAAW,OAAO,CAAC;AAChC,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA0BnD;AAgCD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CA0B9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAqBvE"}

package/dist/esm/src/ratchet/padding.js

@@ -0,0 +1,119 @@
+// packages/sdk/src/ratchet/padding.ts
+/**
+ * Ciphertext padding for metadata leak reduction.
+ *
+ * Bucket-pads plaintext before encryption so on-chain ciphertext lengths
+ * reveal only O(log n) bits of plaintext length (power-of-2 buckets with
+ * additive jitter). Internal to the ratchet module, not exported publicly.
+ */
+import nacl from 'tweetnacl';
+export const PADDING_MARKER = 0x00;
+export const LENGTH_PREFIX_SIZE = 4;
+export const FRAMING_SIZE = 1 + LENGTH_PREFIX_SIZE;
+export const MIN_BUCKET = 64;
+export const MAX_EXPONENTIAL_BUCKET = 16384;
+export const LINEAR_STEP = 4096;
+export const JITTER_FRACTION = 8;
+/**
+ * Generate a uniform random integer in [0, max) using rejection sampling
+ */
+export function secureRandomInt(max) {
+    if (max <= 0)
+        return 0;
+    if (max === 1)
+        return 0;
+    // Find smallest power of 2 >= max
+    let ceiling = 1;
+    while (ceiling < max) {
+        ceiling <<= 1;
+    }
+    const mask = ceiling - 1;
+    // Determine how many bytes we need
+    const bytesNeeded = Math.ceil(Math.log2(ceiling) / 8) || 1;
+    // Rejection sampling
+    for (;;) {
+        const bytes = nacl.randomBytes(bytesNeeded);
+        let value = 0;
+        for (let i = 0; i < bytesNeeded; i++) {
+            value = (value << 8) | bytes[i];
+        }
+        value &= mask;
+        if (value < max) {
+            return value;
+        }
+    }
+}
+/**
+ * Compute the next power of 2 >= n.
+ */
+function nextPowerOf2(n) {
+    if (n <= 1)
+        return 1;
+    let v = n - 1;
+    v |= v >> 1;
+    v |= v >> 2;
+    v |= v >> 4;
+    v |= v >> 8;
+    v |= v >> 16;
+    return v + 1;
+}
+/**
+ * Select the bucket size for a given framed plaintext size.
+ */
+function selectBucket(framedSize) {
+    if (framedSize <= MIN_BUCKET) {
+        return MIN_BUCKET;
+    }
+    if (framedSize <= MAX_EXPONENTIAL_BUCKET) {
+        return nextPowerOf2(framedSize);
+    }
+    // Above MAX_EXPONENTIAL_BUCKET: linear steps of LINEAR_STEP
+    return Math.ceil(framedSize / LINEAR_STEP) * LINEAR_STEP;
+}
+/**
+ * Pad plaintext into a fixed-size envelope before encryption.
+ *
+ * Format: [0x00 marker] [plaintext_length (4 bytes BE)] [plaintext] [random padding]
+ */
+export function padPlaintext(plaintext) {
+    const framedSize = FRAMING_SIZE + plaintext.length;
+    const bucket = selectBucket(framedSize);
+    const jitterMax = Math.floor(bucket / JITTER_FRACTION);
+    const jitter = jitterMax > 0 ? secureRandomInt(jitterMax) : 0;
+    const paddedSize = bucket + jitter;
+    const result = new Uint8Array(paddedSize);
+    // Marker
+    result[0] = PADDING_MARKER;
+    // Plaintext length as 4 bytes big-endian
+    const view = new DataView(result.buffer, result.byteOffset, result.byteLength);
+    view.setUint32(1, plaintext.length, false);
+    result.set(plaintext, FRAMING_SIZE);
+    // Random padding fill (indistinguishable from ciphertext after encryption)
+    const paddingLength = paddedSize - framedSize;
+    if (paddingLength > 0) {
+        const randomPadding = nacl.randomBytes(paddingLength);
+        result.set(randomPadding, framedSize);
+    }
+    return result;
+}
+/**
+ * Remove padding from a decrypted envelope. Strict validation —
+ * returns null on any malformed envelope.
+ */
+export function unpadPlaintext(decrypted) {
+    if (decrypted.length < FRAMING_SIZE) {
+        return null;
+    }
+    if (decrypted[0] !== PADDING_MARKER) {
+        return null;
+    }
+    const view = new DataView(decrypted.buffer, decrypted.byteOffset, decrypted.byteLength);
+    const len = view.getUint32(1, false);
+    if (FRAMING_SIZE + len > decrypted.length) {
+        return null;
+    }
+    // Extract plaintext before wiping
+    const plaintext = decrypted.slice(FRAMING_SIZE, FRAMING_SIZE + len);
+    decrypted.fill(0);
+    return plaintext;
+}

package/dist/src/ratchet/decrypt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decrypt.d.ts","sourceRoot":"","sources":["../../../src/ratchet/decrypt.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,cAAc,EACd,aAAa,EACb,aAAa,EAKd,MAAM,YAAY,CAAC;AAGpB;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,UAAU,GACrB,aAAa,GAAG,IAAI,CA4EtB;AAgKD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,MAA4B,GACrC,cAAc,CAyBhB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,KAAK,MAAM,EAAE,GACnB,SAAS,GAAG,UAAU,GAAG,IAAI,CAY/B"}
+{"version":3,"file":"decrypt.d.ts","sourceRoot":"","sources":["../../../src/ratchet/decrypt.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,cAAc,EACd,aAAa,EACb,aAAa,EAKd,MAAM,YAAY,CAAC;AAIpB;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,UAAU,GACrB,aAAa,GAAG,IAAI,CAkFtB;AAqKD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,MAA4B,GACrC,cAAc,CAyBhB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,KAAK,MAAM,EAAE,GACnB,SAAS,GAAG,UAAU,GAAG,IAAI,CAY/B"}

package/dist/src/ratchet/decrypt.js

@@ -12,6 +12,7 @@ import nacl from 'tweetnacl';
 import { hexlify } from 'ethers';
 import { MAX_SKIP_PER_MESSAGE, MAX_STORED_SKIPPED_KEYS, TOPIC_TRANSITION_WINDOW_MS, } from './types.js';
 import { kdfRootKey, kdfChainKey, dh, generateDHKeyPair, deriveTopic } from './kdf.js';
+import { unpadPlaintext } from './padding.js';
 /**
  * Decrypt a message using the ratchet.
  *
@@ -69,7 +70,12 @@ export function ratchetDecrypt(session, header, ciphertext) {
     if (!plaintext) {
         return null;
     }
-    // 8. Update session state
+    // 8. Unpad plaintext
+    const unpadded = unpadPlaintext(plaintext);
+    if (!unpadded) {
+        return null;
+    }
+    // 9. Update session state
     newSession = {
         ...newSession,
         receivingChainKey: newReceivingChainKey,
@@ -78,7 +84,7 @@ export function ratchetDecrypt(session, header, ciphertext) {
     };
     return {
         session: newSession,
-        plaintext,
+        plaintext: unpadded,
     };
 }
 /**
@@ -173,6 +179,10 @@ function trySkippedKeys(session, dhPubHex, msgNumber, ciphertext) {
     if (!plaintext) {
         return null;
     }
+    const unpadded = unpadPlaintext(plaintext);
+    if (!unpadded) {
+        return null;
+    }
     const newSkippedKeys = [...session.skippedKeys];
     newSkippedKeys.splice(idx, 1);
     // Wipe the key
@@ -187,7 +197,7 @@ function trySkippedKeys(session, dhPubHex, msgNumber, ciphertext) {
             skippedKeys: newSkippedKeys,
             updatedAt: Date.now(),
         },
-        plaintext,
+        plaintext: unpadded,
     };
 }
 /**

package/dist/src/ratchet/encrypt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../../../src/ratchet/encrypt.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG1E;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAM9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,UAAU,EACrB,gBAAgB,EAAE,UAAU,GAC3B,aAAa,CAqDf"}
+{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../../../src/ratchet/encrypt.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI1E;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAM9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,UAAU,EACrB,gBAAgB,EAAE,UAAU,GAC3B,aAAa,CAwDf"}

package/dist/src/ratchet/encrypt.js

@@ -10,6 +10,7 @@
  */
 import nacl from 'tweetnacl';
 import { kdfChainKey } from './kdf.js';
+import { padPlaintext } from './padding.js';
 /**
  * Encode message header as 40 bytes for signing.
  * Format: dh (32) + pn (4, BE) + n (4, BE)
@@ -42,9 +43,15 @@ export function ratchetEncrypt(session, plaintext, signingSecretKey) {
         pn: session.previousChainLength,
         n: session.sendingMsgNumber,
     };
-    // 3. Encrypt with message key using XSalsa20-Poly1305
+    // 3. Pad plaintext and encrypt with message key using XSalsa20-Poly1305
+    const padded = padPlaintext(plaintext);
     const nonce = nacl.randomBytes(nacl.secretbox.nonceLength); // 24 bytes
-    const ciphertext = nacl.secretbox(plaintext, nonce, messageKey);
+    const ciphertext = nacl.secretbox(padded, nonce, messageKey);
+    // Wipe padded buffer after encryption
+    try {
+        padded.fill(0);
+    }
+    catch { }
     // 4. Combine nonce + ciphertext
     const encryptedPayload = new Uint8Array(nonce.length + ciphertext.length);
     encryptedPayload.set(nonce, 0);

package/dist/src/ratchet/padding.d.ts

@@ -0,0 +1,23 @@
+export declare const PADDING_MARKER = 0;
+export declare const LENGTH_PREFIX_SIZE = 4;
+export declare const FRAMING_SIZE: number;
+export declare const MIN_BUCKET = 64;
+export declare const MAX_EXPONENTIAL_BUCKET = 16384;
+export declare const LINEAR_STEP = 4096;
+export declare const JITTER_FRACTION = 8;
+/**
+ * Generate a uniform random integer in [0, max) using rejection sampling
+ */
+export declare function secureRandomInt(max: number): number;
+/**
+ * Pad plaintext into a fixed-size envelope before encryption.
+ *
+ * Format: [0x00 marker] [plaintext_length (4 bytes BE)] [plaintext] [random padding]
+ */
+export declare function padPlaintext(plaintext: Uint8Array): Uint8Array;
+/**
+ * Remove padding from a decrypted envelope. Strict validation —
+ * returns null on any malformed envelope.
+ */
+export declare function unpadPlaintext(decrypted: Uint8Array): Uint8Array | null;
+//# sourceMappingURL=padding.d.ts.map

package/dist/src/ratchet/padding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"padding.d.ts","sourceRoot":"","sources":["../../../src/ratchet/padding.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,cAAc,IAAO,CAAC;AACnC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,YAAY,QAAyB,CAAC;AACnD,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAC5C,eAAO,MAAM,WAAW,OAAO,CAAC;AAChC,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA0BnD;AAgCD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CA0B9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAqBvE"}

package/dist/src/ratchet/padding.js

@@ -0,0 +1,119 @@
+// packages/sdk/src/ratchet/padding.ts
+/**
+ * Ciphertext padding for metadata leak reduction.
+ *
+ * Bucket-pads plaintext before encryption so on-chain ciphertext lengths
+ * reveal only O(log n) bits of plaintext length (power-of-2 buckets with
+ * additive jitter). Internal to the ratchet module, not exported publicly.
+ */
+import nacl from 'tweetnacl';
+export const PADDING_MARKER = 0x00;
+export const LENGTH_PREFIX_SIZE = 4;
+export const FRAMING_SIZE = 1 + LENGTH_PREFIX_SIZE;
+export const MIN_BUCKET = 64;
+export const MAX_EXPONENTIAL_BUCKET = 16384;
+export const LINEAR_STEP = 4096;
+export const JITTER_FRACTION = 8;
+/**
+ * Generate a uniform random integer in [0, max) using rejection sampling
+ */
+export function secureRandomInt(max) {
+    if (max <= 0)
+        return 0;
+    if (max === 1)
+        return 0;
+    // Find smallest power of 2 >= max
+    let ceiling = 1;
+    while (ceiling < max) {
+        ceiling <<= 1;
+    }
+    const mask = ceiling - 1;
+    // Determine how many bytes we need
+    const bytesNeeded = Math.ceil(Math.log2(ceiling) / 8) || 1;
+    // Rejection sampling
+    for (;;) {
+        const bytes = nacl.randomBytes(bytesNeeded);
+        let value = 0;
+        for (let i = 0; i < bytesNeeded; i++) {
+            value = (value << 8) | bytes[i];
+        }
+        value &= mask;
+        if (value < max) {
+            return value;
+        }
+    }
+}
+/**
+ * Compute the next power of 2 >= n.
+ */
+function nextPowerOf2(n) {
+    if (n <= 1)
+        return 1;
+    let v = n - 1;
+    v |= v >> 1;
+    v |= v >> 2;
+    v |= v >> 4;
+    v |= v >> 8;
+    v |= v >> 16;
+    return v + 1;
+}
+/**
+ * Select the bucket size for a given framed plaintext size.
+ */
+function selectBucket(framedSize) {
+    if (framedSize <= MIN_BUCKET) {
+        return MIN_BUCKET;
+    }
+    if (framedSize <= MAX_EXPONENTIAL_BUCKET) {
+        return nextPowerOf2(framedSize);
+    }
+    // Above MAX_EXPONENTIAL_BUCKET: linear steps of LINEAR_STEP
+    return Math.ceil(framedSize / LINEAR_STEP) * LINEAR_STEP;
+}
+/**
+ * Pad plaintext into a fixed-size envelope before encryption.
+ *
+ * Format: [0x00 marker] [plaintext_length (4 bytes BE)] [plaintext] [random padding]
+ */
+export function padPlaintext(plaintext) {
+    const framedSize = FRAMING_SIZE + plaintext.length;
+    const bucket = selectBucket(framedSize);
+    const jitterMax = Math.floor(bucket / JITTER_FRACTION);
+    const jitter = jitterMax > 0 ? secureRandomInt(jitterMax) : 0;
+    const paddedSize = bucket + jitter;
+    const result = new Uint8Array(paddedSize);
+    // Marker
+    result[0] = PADDING_MARKER;
+    // Plaintext length as 4 bytes big-endian
+    const view = new DataView(result.buffer, result.byteOffset, result.byteLength);
+    view.setUint32(1, plaintext.length, false);
+    result.set(plaintext, FRAMING_SIZE);
+    // Random padding fill (indistinguishable from ciphertext after encryption)
+    const paddingLength = paddedSize - framedSize;
+    if (paddingLength > 0) {
+        const randomPadding = nacl.randomBytes(paddingLength);
+        result.set(randomPadding, framedSize);
+    }
+    return result;
+}
+/**
+ * Remove padding from a decrypted envelope. Strict validation —
+ * returns null on any malformed envelope.
+ */
+export function unpadPlaintext(decrypted) {
+    if (decrypted.length < FRAMING_SIZE) {
+        return null;
+    }
+    if (decrypted[0] !== PADDING_MARKER) {
+        return null;
+    }
+    const view = new DataView(decrypted.buffer, decrypted.byteOffset, decrypted.byteLength);
+    const len = view.getUint32(1, false);
+    if (FRAMING_SIZE + len > decrypted.length) {
+        return null;
+    }
+    // Extract plaintext before wiping
+    const plaintext = decrypted.slice(FRAMING_SIZE, FRAMING_SIZE + len);
+    decrypted.fill(0);
+    return plaintext;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verbeth/sdk",
-  "version": "0.1.16",
+  "version": "0.2.0",
   "private": false,
   "main": "dist/src/index.js",
   "module": "dist/esm/src/index.js",