@batalabs/virlow-crypto 3.97.0 → 3.98.0

package/dist/chunked.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The format for a file too large to hold as one ciphertext: v3.
+ *
+ * The file gets a random key of its own. That key, wrapped by the account's
+ * master key, is the header "v3:<ivB64>:<wrappedKeyB64>", which is all the
+ * row's encryptedData column holds. The content is cut into chunks of a fixed
+ * plaintext size and each is sealed on its own with AES-256-GCM, so a reader
+ * can fetch and check any chunk without the rest, and neither end ever holds
+ * the whole file in memory.
+ *
+ * A chunk is bound to its place: its nonce is its index, and its index and
+ * whether it is the last chunk are authenticated with it. A store that
+ * reorders chunks, drops some from the end or hands back one file's chunk as
+ * another's is caught by the tag. The index can be the whole nonce because
+ * the key is used for this one file and nothing else.
+ */
+/** AES-GCM appends its authentication tag to each chunk. */
+export declare const FILE_CHUNK_OVERHEAD = 16;
+export declare function isV3Attachment(encryptedData: string): boolean;
+/** A new file key and the header that carries it, wrapped by the master key. */
+export declare function createFileKey(masterKey: CryptoKey): Promise<{
+    header: string;
+    fileKey: CryptoKey;
+}>;
+/** The file key out of a header. Fails (OperationError) under the wrong master key. */
+export declare function openFileKey(masterKey: CryptoKey, header: string): Promise<CryptoKey>;
+/** Seals chunk `index` (0-based). The result is the chunk plus FILE_CHUNK_OVERHEAD bytes. */
+export declare function encryptFileChunk(fileKey: CryptoKey, index: number, isLast: boolean, plain: Uint8Array | ArrayBuffer): Promise<Uint8Array>;
+/** Opens chunk `index`. Fails if it is not that chunk of that file, or was cut short. */
+export declare function decryptFileChunk(fileKey: CryptoKey, index: number, isLast: boolean, sealed: Uint8Array | ArrayBuffer): Promise<Uint8Array>;
+/** How many chunks a file of `size` bytes is cut into. */
+export declare function fileChunkCount(size: number, chunkSize: number): number;
+/** Where sealed chunk `index` sits in the stored object: [start, end), in bytes. */
+export declare function sealedChunkRange(size: number, chunkSize: number, index: number): {
+    start: number;
+    end: number;
+};
+//# sourceMappingURL=chunked.d.ts.map

package/dist/chunked.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunked.d.ts","sourceRoot":"","sources":["../src/chunked.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAStC,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAE7D;AASD,gFAAgF;AAChF,wBAAsB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC,CAgBzG;AAED,uFAAuF;AACvF,wBAAsB,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAkB1F;AAeD,6FAA6F;AAC7F,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,SAAS,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,UAAU,GAAG,WAAW,GAC9B,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,yFAAyF;AACzF,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,SAAS,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,UAAU,GAAG,WAAW,GAC/B,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAKhC"}

package/dist/chunked.js

@@ -0,0 +1,100 @@
+import { base64ToBytes, bytesToBase64 } from './base64.js';
+import { ENCRYPTION_CONFIG } from './constants.js';
+/**
+ * The format for a file too large to hold as one ciphertext: v3.
+ *
+ * The file gets a random key of its own. That key, wrapped by the account's
+ * master key, is the header "v3:<ivB64>:<wrappedKeyB64>", which is all the
+ * row's encryptedData column holds. The content is cut into chunks of a fixed
+ * plaintext size and each is sealed on its own with AES-256-GCM, so a reader
+ * can fetch and check any chunk without the rest, and neither end ever holds
+ * the whole file in memory.
+ *
+ * A chunk is bound to its place: its nonce is its index, and its index and
+ * whether it is the last chunk are authenticated with it. A store that
+ * reorders chunks, drops some from the end or hands back one file's chunk as
+ * another's is caught by the tag. The index can be the whole nonce because
+ * the key is used for this one file and nothing else.
+ */
+/** AES-GCM appends its authentication tag to each chunk. */
+export const FILE_CHUNK_OVERHEAD = 16;
+/** The size GCM is specified for. Nothing random goes in it, so there is no
+ *  reason for the longer IV the rest of the formats use. */
+const CHUNK_NONCE_BYTES = 12;
+const HEADER_PREFIX = 'v3:';
+const FILE_KEY_BYTES = 32;
+const AAD_LABEL = new TextEncoder().encode('virlow-file-v3');
+export function isV3Attachment(encryptedData) {
+    return encryptedData.startsWith(HEADER_PREFIX);
+}
+async function importFileKey(raw) {
+    return crypto.subtle.importKey('raw', raw, { name: ENCRYPTION_CONFIG.ALGORITHM }, false, [
+        'encrypt',
+        'decrypt',
+    ]);
+}
+/** A new file key and the header that carries it, wrapped by the master key. */
+export async function createFileKey(masterKey) {
+    const raw = crypto.getRandomValues(new Uint8Array(FILE_KEY_BYTES));
+    const iv = crypto.getRandomValues(new Uint8Array(ENCRYPTION_CONFIG.IV_LENGTH));
+    try {
+        const wrapped = await crypto.subtle.encrypt({ name: ENCRYPTION_CONFIG.ALGORITHM, iv }, masterKey, raw);
+        return {
+            header: `${HEADER_PREFIX}${bytesToBase64(iv)}:${bytesToBase64(wrapped)}`,
+            fileKey: await importFileKey(raw),
+        };
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+/** The file key out of a header. Fails (OperationError) under the wrong master key. */
+export async function openFileKey(masterKey, header) {
+    if (!isV3Attachment(header))
+        throw new Error('Not a v3 attachment header');
+    const rest = header.slice(HEADER_PREFIX.length);
+    const sep = rest.indexOf(':');
+    if (sep === -1)
+        throw new Error('Malformed attachment header: missing the IV separator');
+    const raw = new Uint8Array(await crypto.subtle.decrypt({ name: ENCRYPTION_CONFIG.ALGORITHM, iv: base64ToBytes(rest.slice(0, sep)) }, masterKey, base64ToBytes(rest.slice(sep + 1))));
+    try {
+        if (raw.byteLength !== FILE_KEY_BYTES)
+            throw new Error('Malformed attachment header: wrong key length');
+        return await importFileKey(raw);
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+function chunkParams(index, isLast) {
+    if (!Number.isInteger(index) || index < 0 || index > 0xffffffff) {
+        throw new Error(`Chunk index out of range: ${index}`);
+    }
+    const iv = new Uint8Array(CHUNK_NONCE_BYTES);
+    new DataView(iv.buffer).setUint32(iv.byteLength - 4, index);
+    const aad = new Uint8Array(AAD_LABEL.byteLength + 5);
+    aad.set(AAD_LABEL);
+    new DataView(aad.buffer).setUint32(AAD_LABEL.byteLength, index);
+    aad[aad.byteLength - 1] = isLast ? 1 : 0;
+    return { name: ENCRYPTION_CONFIG.ALGORITHM, iv, additionalData: aad };
+}
+/** Seals chunk `index` (0-based). The result is the chunk plus FILE_CHUNK_OVERHEAD bytes. */
+export async function encryptFileChunk(fileKey, index, isLast, plain) {
+    return new Uint8Array(await crypto.subtle.encrypt(chunkParams(index, isLast), fileKey, plain));
+}
+/** Opens chunk `index`. Fails if it is not that chunk of that file, or was cut short. */
+export async function decryptFileChunk(fileKey, index, isLast, sealed) {
+    return new Uint8Array(await crypto.subtle.decrypt(chunkParams(index, isLast), fileKey, sealed));
+}
+/** How many chunks a file of `size` bytes is cut into. */
+export function fileChunkCount(size, chunkSize) {
+    return Math.max(1, Math.ceil(size / chunkSize));
+}
+/** Where sealed chunk `index` sits in the stored object: [start, end), in bytes. */
+export function sealedChunkRange(size, chunkSize, index) {
+    const count = fileChunkCount(size, chunkSize);
+    const plain = index < count - 1 ? chunkSize : size - chunkSize * (count - 1);
+    const start = index * (chunkSize + FILE_CHUNK_OVERHEAD);
+    return { start, end: start + plain + FILE_CHUNK_OVERHEAD };
+}
+//# sourceMappingURL=chunked.js.map

package/dist/chunked.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunked.js","sourceRoot":"","sources":["../src/chunked.ts"],"names":[],"mappings":"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"}

package/dist/cjs/chunked.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The format for a file too large to hold as one ciphertext: v3.
+ *
+ * The file gets a random key of its own. That key, wrapped by the account's
+ * master key, is the header "v3:<ivB64>:<wrappedKeyB64>", which is all the
+ * row's encryptedData column holds. The content is cut into chunks of a fixed
+ * plaintext size and each is sealed on its own with AES-256-GCM, so a reader
+ * can fetch and check any chunk without the rest, and neither end ever holds
+ * the whole file in memory.
+ *
+ * A chunk is bound to its place: its nonce is its index, and its index and
+ * whether it is the last chunk are authenticated with it. A store that
+ * reorders chunks, drops some from the end or hands back one file's chunk as
+ * another's is caught by the tag. The index can be the whole nonce because
+ * the key is used for this one file and nothing else.
+ */
+/** AES-GCM appends its authentication tag to each chunk. */
+export declare const FILE_CHUNK_OVERHEAD = 16;
+export declare function isV3Attachment(encryptedData: string): boolean;
+/** A new file key and the header that carries it, wrapped by the master key. */
+export declare function createFileKey(masterKey: CryptoKey): Promise<{
+    header: string;
+    fileKey: CryptoKey;
+}>;
+/** The file key out of a header. Fails (OperationError) under the wrong master key. */
+export declare function openFileKey(masterKey: CryptoKey, header: string): Promise<CryptoKey>;
+/** Seals chunk `index` (0-based). The result is the chunk plus FILE_CHUNK_OVERHEAD bytes. */
+export declare function encryptFileChunk(fileKey: CryptoKey, index: number, isLast: boolean, plain: Uint8Array | ArrayBuffer): Promise<Uint8Array>;
+/** Opens chunk `index`. Fails if it is not that chunk of that file, or was cut short. */
+export declare function decryptFileChunk(fileKey: CryptoKey, index: number, isLast: boolean, sealed: Uint8Array | ArrayBuffer): Promise<Uint8Array>;
+/** How many chunks a file of `size` bytes is cut into. */
+export declare function fileChunkCount(size: number, chunkSize: number): number;
+/** Where sealed chunk `index` sits in the stored object: [start, end), in bytes. */
+export declare function sealedChunkRange(size: number, chunkSize: number, index: number): {
+    start: number;
+    end: number;
+};

package/dist/cjs/chunked.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_CHUNK_OVERHEAD = void 0;
+exports.isV3Attachment = isV3Attachment;
+exports.createFileKey = createFileKey;
+exports.openFileKey = openFileKey;
+exports.encryptFileChunk = encryptFileChunk;
+exports.decryptFileChunk = decryptFileChunk;
+exports.fileChunkCount = fileChunkCount;
+exports.sealedChunkRange = sealedChunkRange;
+const base64_js_1 = require("./base64.js");
+const constants_js_1 = require("./constants.js");
+/**
+ * The format for a file too large to hold as one ciphertext: v3.
+ *
+ * The file gets a random key of its own. That key, wrapped by the account's
+ * master key, is the header "v3:<ivB64>:<wrappedKeyB64>", which is all the
+ * row's encryptedData column holds. The content is cut into chunks of a fixed
+ * plaintext size and each is sealed on its own with AES-256-GCM, so a reader
+ * can fetch and check any chunk without the rest, and neither end ever holds
+ * the whole file in memory.
+ *
+ * A chunk is bound to its place: its nonce is its index, and its index and
+ * whether it is the last chunk are authenticated with it. A store that
+ * reorders chunks, drops some from the end or hands back one file's chunk as
+ * another's is caught by the tag. The index can be the whole nonce because
+ * the key is used for this one file and nothing else.
+ */
+/** AES-GCM appends its authentication tag to each chunk. */
+exports.FILE_CHUNK_OVERHEAD = 16;
+/** The size GCM is specified for. Nothing random goes in it, so there is no
+ *  reason for the longer IV the rest of the formats use. */
+const CHUNK_NONCE_BYTES = 12;
+const HEADER_PREFIX = 'v3:';
+const FILE_KEY_BYTES = 32;
+const AAD_LABEL = new TextEncoder().encode('virlow-file-v3');
+function isV3Attachment(encryptedData) {
+    return encryptedData.startsWith(HEADER_PREFIX);
+}
+async function importFileKey(raw) {
+    return crypto.subtle.importKey('raw', raw, { name: constants_js_1.ENCRYPTION_CONFIG.ALGORITHM }, false, [
+        'encrypt',
+        'decrypt',
+    ]);
+}
+/** A new file key and the header that carries it, wrapped by the master key. */
+async function createFileKey(masterKey) {
+    const raw = crypto.getRandomValues(new Uint8Array(FILE_KEY_BYTES));
+    const iv = crypto.getRandomValues(new Uint8Array(constants_js_1.ENCRYPTION_CONFIG.IV_LENGTH));
+    try {
+        const wrapped = await crypto.subtle.encrypt({ name: constants_js_1.ENCRYPTION_CONFIG.ALGORITHM, iv }, masterKey, raw);
+        return {
+            header: `${HEADER_PREFIX}${(0, base64_js_1.bytesToBase64)(iv)}:${(0, base64_js_1.bytesToBase64)(wrapped)}`,
+            fileKey: await importFileKey(raw),
+        };
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+/** The file key out of a header. Fails (OperationError) under the wrong master key. */
+async function openFileKey(masterKey, header) {
+    if (!isV3Attachment(header))
+        throw new Error('Not a v3 attachment header');
+    const rest = header.slice(HEADER_PREFIX.length);
+    const sep = rest.indexOf(':');
+    if (sep === -1)
+        throw new Error('Malformed attachment header: missing the IV separator');
+    const raw = new Uint8Array(await crypto.subtle.decrypt({ name: constants_js_1.ENCRYPTION_CONFIG.ALGORITHM, iv: (0, base64_js_1.base64ToBytes)(rest.slice(0, sep)) }, masterKey, (0, base64_js_1.base64ToBytes)(rest.slice(sep + 1))));
+    try {
+        if (raw.byteLength !== FILE_KEY_BYTES)
+            throw new Error('Malformed attachment header: wrong key length');
+        return await importFileKey(raw);
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+function chunkParams(index, isLast) {
+    if (!Number.isInteger(index) || index < 0 || index > 0xffffffff) {
+        throw new Error(`Chunk index out of range: ${index}`);
+    }
+    const iv = new Uint8Array(CHUNK_NONCE_BYTES);
+    new DataView(iv.buffer).setUint32(iv.byteLength - 4, index);
+    const aad = new Uint8Array(AAD_LABEL.byteLength + 5);
+    aad.set(AAD_LABEL);
+    new DataView(aad.buffer).setUint32(AAD_LABEL.byteLength, index);
+    aad[aad.byteLength - 1] = isLast ? 1 : 0;
+    return { name: constants_js_1.ENCRYPTION_CONFIG.ALGORITHM, iv, additionalData: aad };
+}
+/** Seals chunk `index` (0-based). The result is the chunk plus FILE_CHUNK_OVERHEAD bytes. */
+async function encryptFileChunk(fileKey, index, isLast, plain) {
+    return new Uint8Array(await crypto.subtle.encrypt(chunkParams(index, isLast), fileKey, plain));
+}
+/** Opens chunk `index`. Fails if it is not that chunk of that file, or was cut short. */
+async function decryptFileChunk(fileKey, index, isLast, sealed) {
+    return new Uint8Array(await crypto.subtle.decrypt(chunkParams(index, isLast), fileKey, sealed));
+}
+/** How many chunks a file of `size` bytes is cut into. */
+function fileChunkCount(size, chunkSize) {
+    return Math.max(1, Math.ceil(size / chunkSize));
+}
+/** Where sealed chunk `index` sits in the stored object: [start, end), in bytes. */
+function sealedChunkRange(size, chunkSize, index) {
+    const count = fileChunkCount(size, chunkSize);
+    const plain = index < count - 1 ? chunkSize : size - chunkSize * (count - 1);
+    const start = index * (chunkSize + exports.FILE_CHUNK_OVERHEAD);
+    return { start, end: start + plain + exports.FILE_CHUNK_OVERHEAD };
+}

package/dist/cjs/index.d.ts

@@ -4,5 +4,6 @@ export { ENCRYPTION_CONFIG, VERIFIER_CONSTANT } from './constants.js';
 export { deriveMasterKey, importMasterKey } from './keys.js';
 export { decryptNoteFields, decryptTitleField, encryptNoteFields, type EncryptedNoteFields, } from './notes.js';
 export { LEGACY_ATTACHMENT_MESSAGE, LegacyAttachmentError, decryptAttachment, decryptAttachmentData, encryptAttachment, encryptAttachmentName, isV2Attachment, type EncryptedAttachment, } from './attachments.js';
+export { FILE_CHUNK_OVERHEAD, createFileKey, decryptFileChunk, encryptFileChunk, fileChunkCount, isV3Attachment, openFileKey, sealedChunkRange, } from './chunked.js';
 export { canDecryptWithKey, createVerifierBlob, verifyVerifierBlob, type VerifierBlob, } from './verifier.js';
 export declare const PACKAGE_NAME = "@batalabs/virlow-crypto";

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PACKAGE_NAME = exports.verifyVerifierBlob = exports.createVerifierBlob = exports.canDecryptWithKey = exports.isV2Attachment = exports.encryptAttachmentName = exports.encryptAttachment = exports.decryptAttachmentData = exports.decryptAttachment = exports.LegacyAttachmentError = exports.LEGACY_ATTACHMENT_MESSAGE = exports.encryptNoteFields = exports.decryptTitleField = exports.decryptNoteFields = exports.importMasterKey = exports.deriveMasterKey = exports.VERIFIER_CONSTANT = exports.ENCRYPTION_CONFIG = exports.encryptStringBlob = exports.encryptBytesBlob = exports.decryptStringBlob = exports.decryptBytesBlob = exports.bytesToBase64 = exports.base64ToBytes = exports.base64ToArrayBuffer = void 0;
+exports.PACKAGE_NAME = exports.verifyVerifierBlob = exports.createVerifierBlob = exports.canDecryptWithKey = exports.sealedChunkRange = exports.openFileKey = exports.isV3Attachment = exports.fileChunkCount = exports.encryptFileChunk = exports.decryptFileChunk = exports.createFileKey = exports.FILE_CHUNK_OVERHEAD = exports.isV2Attachment = exports.encryptAttachmentName = exports.encryptAttachment = exports.decryptAttachmentData = exports.decryptAttachment = exports.LegacyAttachmentError = exports.LEGACY_ATTACHMENT_MESSAGE = exports.encryptNoteFields = exports.decryptTitleField = exports.decryptNoteFields = exports.importMasterKey = exports.deriveMasterKey = exports.VERIFIER_CONSTANT = exports.ENCRYPTION_CONFIG = exports.encryptStringBlob = exports.encryptBytesBlob = exports.decryptStringBlob = exports.decryptBytesBlob = exports.bytesToBase64 = exports.base64ToBytes = exports.base64ToArrayBuffer = void 0;
 var base64_js_1 = require("./base64.js");
 Object.defineProperty(exports, "base64ToArrayBuffer", { enumerable: true, get: function () { return base64_js_1.base64ToArrayBuffer; } });
 Object.defineProperty(exports, "base64ToBytes", { enumerable: true, get: function () { return base64_js_1.base64ToBytes; } });
@@ -28,6 +28,15 @@ Object.defineProperty(exports, "decryptAttachmentData", { enumerable: true, get:
 Object.defineProperty(exports, "encryptAttachment", { enumerable: true, get: function () { return attachments_js_1.encryptAttachment; } });
 Object.defineProperty(exports, "encryptAttachmentName", { enumerable: true, get: function () { return attachments_js_1.encryptAttachmentName; } });
 Object.defineProperty(exports, "isV2Attachment", { enumerable: true, get: function () { return attachments_js_1.isV2Attachment; } });
+var chunked_js_1 = require("./chunked.js");
+Object.defineProperty(exports, "FILE_CHUNK_OVERHEAD", { enumerable: true, get: function () { return chunked_js_1.FILE_CHUNK_OVERHEAD; } });
+Object.defineProperty(exports, "createFileKey", { enumerable: true, get: function () { return chunked_js_1.createFileKey; } });
+Object.defineProperty(exports, "decryptFileChunk", { enumerable: true, get: function () { return chunked_js_1.decryptFileChunk; } });
+Object.defineProperty(exports, "encryptFileChunk", { enumerable: true, get: function () { return chunked_js_1.encryptFileChunk; } });
+Object.defineProperty(exports, "fileChunkCount", { enumerable: true, get: function () { return chunked_js_1.fileChunkCount; } });
+Object.defineProperty(exports, "isV3Attachment", { enumerable: true, get: function () { return chunked_js_1.isV3Attachment; } });
+Object.defineProperty(exports, "openFileKey", { enumerable: true, get: function () { return chunked_js_1.openFileKey; } });
+Object.defineProperty(exports, "sealedChunkRange", { enumerable: true, get: function () { return chunked_js_1.sealedChunkRange; } });
 var verifier_js_1 = require("./verifier.js");
 Object.defineProperty(exports, "canDecryptWithKey", { enumerable: true, get: function () { return verifier_js_1.canDecryptWithKey; } });
 Object.defineProperty(exports, "createVerifierBlob", { enumerable: true, get: function () { return verifier_js_1.createVerifierBlob; } });

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { ENCRYPTION_CONFIG, VERIFIER_CONSTANT } from './constants.js';
 export { deriveMasterKey, importMasterKey } from './keys.js';
 export { decryptNoteFields, decryptTitleField, encryptNoteFields, type EncryptedNoteFields, } from './notes.js';
 export { LEGACY_ATTACHMENT_MESSAGE, LegacyAttachmentError, decryptAttachment, decryptAttachmentData, encryptAttachment, encryptAttachmentName, isV2Attachment, type EncryptedAttachment, } from './attachments.js';
+export { FILE_CHUNK_OVERHEAD, createFileKey, decryptFileChunk, encryptFileChunk, fileChunkCount, isV3Attachment, openFileKey, sealedChunkRange, } from './chunked.js';
 export { canDecryptWithKey, createVerifierBlob, verifyVerifierBlob, type VerifierBlob, } from './verifier.js';
 export declare const PACKAGE_NAME = "@batalabs/virlow-crypto";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AACvB,eAAO,MAAM,YAAY,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,WAAW,EACX,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AACvB,eAAO,MAAM,YAAY,4BAA4B,CAAC"}

package/dist/index.js

@@ -4,6 +4,7 @@ export { ENCRYPTION_CONFIG, VERIFIER_CONSTANT } from './constants.js';
 export { deriveMasterKey, importMasterKey } from './keys.js';
 export { decryptNoteFields, decryptTitleField, encryptNoteFields, } from './notes.js';
 export { LEGACY_ATTACHMENT_MESSAGE, LegacyAttachmentError, decryptAttachment, decryptAttachmentData, encryptAttachment, encryptAttachmentName, isV2Attachment, } from './attachments.js';
+export { FILE_CHUNK_OVERHEAD, createFileKey, decryptFileChunk, encryptFileChunk, fileChunkCount, isV3Attachment, openFileKey, sealedChunkRange, } from './chunked.js';
 export { canDecryptWithKey, createVerifierBlob, verifyVerifierBlob, } from './verifier.js';
 export const PACKAGE_NAME = '@batalabs/virlow-crypto';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAElB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,GAEf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,GAEnB,MAAM,eAAe,CAAC;AACvB,MAAM,CAAC,MAAM,YAAY,GAAG,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAElB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,GAEf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,WAAW,EACX,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,GAEnB,MAAM,eAAe,CAAC;AACvB,MAAM,CAAC,MAAM,YAAY,GAAG,yBAAyB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batalabs/virlow-crypto",
-  "version": "3.97.0",
+  "version": "3.98.0",
   "type": "module",
   "description": "Virlow client-side encryption primitives (PBKDF2 + AES-256-GCM). Framework-free; browser and Node 20+.",
   "license": "UNLICENSED",