esp-nvs-utils 0.1.0

package/dist/esm/decoder-mrjRj6rx.js

@@ -0,0 +1,249 @@
+//#region src/crc.ts
+/**
+* Pure CRC-32 implementation compatible with zlib.crc32 (polynomial 0xEDB88320).
+* Browser-safe: no Node.js dependencies.
+*/
+const CRC32_TABLE = (() => {
+	const table = new Uint32Array(256);
+	for (let i = 0; i < 256; i++) {
+		let c = i;
+		for (let j = 0; j < 8; j++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+		table[i] = c;
+	}
+	return table;
+})();
+/**
+* Compute CRC-32 of data, matching Python's `zlib.crc32(data, seed)`.
+* The default seed of 0xFFFFFFFF matches the NVS usage pattern.
+*/
+function crc32(data, seed = 4294967295) {
+	let crc = seed >>> 0;
+	for (let i = 0; i < data.length; i++) crc = CRC32_TABLE[(crc ^ data[i]) & 255] ^ crc >>> 8;
+	return crc >>> 0;
+}
+//#endregion
+//#region src/constants.ts
+/** NVS page size in bytes. */
+const PAGE_SIZE = 4096;
+/** Page state: page is currently being written. */
+const PAGE_STATE_ACTIVE = 4294967294;
+/** Page state: page is full, no more entries can be written. */
+const PAGE_STATE_FULL = 4294967292;
+/** Map from NVS encoding string to type code. */
+const ENCODING_TO_TYPE_CODE = {
+	u8: 1,
+	i8: 17,
+	u16: 2,
+	i16: 18,
+	u32: 4,
+	i32: 20,
+	u64: 8,
+	i64: 24,
+	string: 33,
+	blob_data: 66
+};
+//#endregion
+//#region src/decoder.ts
+function readKey(entry) {
+	let end = 8;
+	while (end < 24 && entry[end] !== 0) end++;
+	return new TextDecoder().decode(entry.subarray(8, end));
+}
+function entryBitmapState(bitmap, idx) {
+	const bitNum = idx * 2;
+	const byteIdx = bitNum >> 3;
+	const bitOffset = bitNum & 7;
+	return bitmap[byteIdx] >> bitOffset & 3;
+}
+function parsePrimitive(typeCode, inlineData) {
+	const view = new DataView(inlineData.buffer, inlineData.byteOffset, inlineData.byteLength);
+	switch (typeCode) {
+		case 1: return view.getUint8(0);
+		case 17: return view.getInt8(0);
+		case 2: return view.getUint16(0, true);
+		case 18: return view.getInt16(0, true);
+		case 4: return view.getUint32(0, true);
+		case 20: return view.getInt32(0, true);
+		case 8: return view.getBigUint64(0, true);
+		case 24: return view.getBigInt64(0, true);
+		default: throw new Error(`Unknown primitive type code: 0x${typeCode.toString(16)}`);
+	}
+}
+const PRIMITIVE_TYPES = new Set([
+	1,
+	17,
+	2,
+	18,
+	4,
+	20,
+	8,
+	24
+]);
+const VARLEN_TYPES = new Set([
+	33,
+	65,
+	66,
+	72
+]);
+/**
+* Parse all valid written entries from a single 4096-byte page.
+* Returns entries in slot order, including namespace entries.
+*/
+function parsePage(pageData) {
+	const bitmap = pageData.subarray(32, 64);
+	const entries = [];
+	let i = 0;
+	while (i < 126) {
+		if (entryBitmapState(bitmap, i) !== 2) {
+			i++;
+			continue;
+		}
+		const entryOff = 64 + i * 32;
+		const entry = pageData.subarray(entryOff, entryOff + 32);
+		const nsIdx = entry[0];
+		const typeCode = entry[1];
+		let span = entry[2];
+		const chunkIndex = entry[3];
+		const safeSpan = span === 0 || span === 255 ? 1 : span;
+		const parsed = {
+			nsIdx,
+			typeCode,
+			span: safeSpan,
+			chunkIndex,
+			key: readKey(entry),
+			raw: entry,
+			inlineData: entry.subarray(24, 32),
+			entryIndex: i
+		};
+		if (VARLEN_TYPES.has(typeCode) && typeCode !== 72) {
+			const childCount = safeSpan - 1;
+			if (childCount > 0) {
+				const childStart = 64 + (i + 1) * 32;
+				const childEnd = childStart + childCount * 32;
+				parsed.childData = pageData.subarray(childStart, childEnd);
+			}
+		}
+		entries.push(parsed);
+		i += safeSpan;
+	}
+	return entries;
+}
+/**
+* Decode an NVS partition binary into structured namespaces.
+*
+* Handles V1 (single-page blobs) and V2 (multi-page blobs).
+* Does not support encrypted partitions.
+*/
+function decodeNVS(data) {
+	const buf = data instanceof Uint8Array ? data : new Uint8Array(data);
+	if (buf.length % 4096 !== 0) throw new Error(`Partition data length ${buf.length} is not aligned to page size ${PAGE_SIZE}`);
+	const allEntries = [];
+	for (let pageOff = 0; pageOff < buf.length; pageOff += PAGE_SIZE) {
+		const page = buf.subarray(pageOff, pageOff + PAGE_SIZE);
+		const pageStateRaw = (page[0] | page[1] << 8 | page[2] << 16 | page[3] << 24) >>> 0;
+		if (pageStateRaw === 4294967295 || pageStateRaw === 0) continue;
+		const version = page[8];
+		if (version !== 255 && version !== 254) continue;
+		allEntries.push(...parsePage(page));
+	}
+	const nsIdxToName = /* @__PURE__ */ new Map();
+	for (const e of allEntries) if (e.nsIdx === 0 && e.typeCode === 1) {
+		const assignedIdx = e.inlineData[0];
+		nsIdxToName.set(assignedIdx, e.key);
+	}
+	const blobDataChunks = /* @__PURE__ */ new Map();
+	const blobIndex = /* @__PURE__ */ new Map();
+	const v1Blobs = /* @__PURE__ */ new Map();
+	for (const e of allEntries) {
+		if (e.nsIdx === 0) continue;
+		const bk = `${e.nsIdx}:${e.key}`;
+		if (e.typeCode === 66) {
+			if (!blobDataChunks.has(bk)) blobDataChunks.set(bk, /* @__PURE__ */ new Map());
+			const payload = e.childData ?? new Uint8Array(0);
+			blobDataChunks.get(bk).set(e.chunkIndex, payload);
+		} else if (e.typeCode === 72) {
+			const view = new DataView(e.inlineData.buffer, e.inlineData.byteOffset, 8);
+			blobIndex.set(bk, {
+				totalSize: view.getUint32(0, true),
+				chunkCount: e.inlineData[4],
+				chunkStart: e.inlineData[5]
+			});
+		} else if (e.typeCode === 65) {
+			const size = new DataView(e.inlineData.buffer, e.inlineData.byteOffset, 8).getUint16(0, true);
+			const payload = e.childData ?? new Uint8Array(0);
+			v1Blobs.set(bk, {
+				size,
+				data: payload
+			});
+		}
+	}
+	const result = {};
+	for (const e of allEntries) {
+		if (e.nsIdx === 0) continue;
+		if (e.typeCode === 66 || e.typeCode === 72) continue;
+		const nsName = nsIdxToName.get(e.nsIdx);
+		if (nsName === void 0) continue;
+		if (!result[nsName]) result[nsName] = [];
+		const bk = `${e.nsIdx}:${e.key}`;
+		if (PRIMITIVE_TYPES.has(e.typeCode)) {
+			const val = parsePrimitive(e.typeCode, e.inlineData);
+			const enc = e.typeCode === 1 ? "u8" : e.typeCode === 17 ? "i8" : e.typeCode === 2 ? "u16" : e.typeCode === 18 ? "i16" : e.typeCode === 4 ? "u32" : e.typeCode === 20 ? "i32" : e.typeCode === 8 ? "u64" : "i64";
+			result[nsName].push({
+				name: e.key,
+				encoding: enc,
+				value: val
+			});
+		} else if (e.typeCode === 33) {
+			const size = new DataView(e.inlineData.buffer, e.inlineData.byteOffset, 8).getUint16(0, true);
+			const payload = e.childData ?? new Uint8Array(0);
+			payload.subarray(0, size).filter((_, idx) => {
+				const slice = payload.subarray(0, size);
+				let last = slice.length - 1;
+				while (last >= 0 && slice[last] === 0) last--;
+				return idx <= last;
+			});
+			const str = new TextDecoder().decode(payload.subarray(0, Math.max(0, size - 1)));
+			result[nsName].push({
+				name: e.key,
+				encoding: "string",
+				value: str
+			});
+		} else if (e.typeCode === 65) {
+			const v1 = v1Blobs.get(bk);
+			if (v1) {
+				const data = v1.data.subarray(0, v1.size);
+				result[nsName].push({
+					name: e.key,
+					encoding: "blob_data",
+					value: new Uint8Array(data)
+				});
+			}
+		}
+	}
+	for (const [bk, chunks] of blobDataChunks) {
+		const [nsIdxStr, ...keyParts] = bk.split(":");
+		const nsIdx = parseInt(nsIdxStr);
+		const key = keyParts.join(":");
+		const nsName = nsIdxToName.get(nsIdx);
+		if (nsName === void 0) continue;
+		const idx = blobIndex.get(bk);
+		const allChunkData = [...chunks.keys()].sort((a, b) => a - b).map((k) => chunks.get(k));
+		const totalRaw = allChunkData.reduce((acc, c) => acc + c.length, 0);
+		const assembled = new Uint8Array(totalRaw);
+		let off = 0;
+		for (const c of allChunkData) {
+			assembled.set(c, off);
+			off += c.length;
+		}
+		const trimmed = idx ? assembled.subarray(0, idx.totalSize) : assembled;
+		if (!result[nsName]) result[nsName] = [];
+		result[nsName].push({
+			name: key,
+			encoding: "blob_data",
+			value: new Uint8Array(trimmed)
+		});
+	}
+	return result;
+}
+//#endregion
+export { PAGE_STATE_FULL as a, PAGE_STATE_ACTIVE as i, ENCODING_TO_TYPE_CODE as n, crc32 as o, PAGE_SIZE as r, decodeNVS as t };

package/dist/esm/decoder.js

@@ -0,0 +1,219 @@
+//#region src/constants.ts
+/** NVS page size in bytes. */
+const PAGE_SIZE = 4096;
+/** Page state: page is currently being written. */
+const PAGE_STATE_ACTIVE = 4294967294;
+/** Page state: page is full, no more entries can be written. */
+const PAGE_STATE_FULL = 4294967292;
+/** Map from NVS encoding string to type code. */
+const ENCODING_TO_TYPE_CODE = {
+	u8: 1,
+	i8: 17,
+	u16: 2,
+	i16: 18,
+	u32: 4,
+	i32: 20,
+	u64: 8,
+	i64: 24,
+	string: 33,
+	blob_data: 66
+};
+//#endregion
+//#region src/decoder.ts
+function readKey(entry) {
+	let end = 8;
+	while (end < 24 && entry[end] !== 0) end++;
+	return new TextDecoder().decode(entry.subarray(8, end));
+}
+function entryBitmapState(bitmap, idx) {
+	const bitNum = idx * 2;
+	const byteIdx = bitNum >> 3;
+	const bitOffset = bitNum & 7;
+	return bitmap[byteIdx] >> bitOffset & 3;
+}
+function parsePrimitive(typeCode, inlineData) {
+	const view = new DataView(inlineData.buffer, inlineData.byteOffset, inlineData.byteLength);
+	switch (typeCode) {
+		case 1: return view.getUint8(0);
+		case 17: return view.getInt8(0);
+		case 2: return view.getUint16(0, true);
+		case 18: return view.getInt16(0, true);
+		case 4: return view.getUint32(0, true);
+		case 20: return view.getInt32(0, true);
+		case 8: return view.getBigUint64(0, true);
+		case 24: return view.getBigInt64(0, true);
+		default: throw new Error(`Unknown primitive type code: 0x${typeCode.toString(16)}`);
+	}
+}
+const PRIMITIVE_TYPES = new Set([
+	1,
+	17,
+	2,
+	18,
+	4,
+	20,
+	8,
+	24
+]);
+const VARLEN_TYPES = new Set([
+	33,
+	65,
+	66,
+	72
+]);
+/**
+* Parse all valid written entries from a single 4096-byte page.
+* Returns entries in slot order, including namespace entries.
+*/
+function parsePage(pageData) {
+	const bitmap = pageData.subarray(32, 64);
+	const entries = [];
+	let i = 0;
+	while (i < 126) {
+		if (entryBitmapState(bitmap, i) !== 2) {
+			i++;
+			continue;
+		}
+		const entryOff = 64 + i * 32;
+		const entry = pageData.subarray(entryOff, entryOff + 32);
+		const nsIdx = entry[0];
+		const typeCode = entry[1];
+		let span = entry[2];
+		const chunkIndex = entry[3];
+		const safeSpan = span === 0 || span === 255 ? 1 : span;
+		const parsed = {
+			nsIdx,
+			typeCode,
+			span: safeSpan,
+			chunkIndex,
+			key: readKey(entry),
+			raw: entry,
+			inlineData: entry.subarray(24, 32),
+			entryIndex: i
+		};
+		if (VARLEN_TYPES.has(typeCode) && typeCode !== 72) {
+			const childCount = safeSpan - 1;
+			if (childCount > 0) {
+				const childStart = 64 + (i + 1) * 32;
+				const childEnd = childStart + childCount * 32;
+				parsed.childData = pageData.subarray(childStart, childEnd);
+			}
+		}
+		entries.push(parsed);
+		i += safeSpan;
+	}
+	return entries;
+}
+/**
+* Decode an NVS partition binary into structured namespaces.
+*
+* Handles V1 (single-page blobs) and V2 (multi-page blobs).
+* Does not support encrypted partitions.
+*/
+function decodeNVS(data) {
+	const buf = data instanceof Uint8Array ? data : new Uint8Array(data);
+	if (buf.length % 4096 !== 0) throw new Error(`Partition data length ${buf.length} is not aligned to page size ${PAGE_SIZE}`);
+	const allEntries = [];
+	for (let pageOff = 0; pageOff < buf.length; pageOff += PAGE_SIZE) {
+		const page = buf.subarray(pageOff, pageOff + PAGE_SIZE);
+		const pageStateRaw = (page[0] | page[1] << 8 | page[2] << 16 | page[3] << 24) >>> 0;
+		if (pageStateRaw === 4294967295 || pageStateRaw === 0) continue;
+		const version = page[8];
+		if (version !== 255 && version !== 254) continue;
+		allEntries.push(...parsePage(page));
+	}
+	const nsIdxToName = /* @__PURE__ */ new Map();
+	for (const e of allEntries) if (e.nsIdx === 0 && e.typeCode === 1) {
+		const assignedIdx = e.inlineData[0];
+		nsIdxToName.set(assignedIdx, e.key);
+	}
+	const blobDataChunks = /* @__PURE__ */ new Map();
+	const blobIndex = /* @__PURE__ */ new Map();
+	const v1Blobs = /* @__PURE__ */ new Map();
+	for (const e of allEntries) {
+		if (e.nsIdx === 0) continue;
+		const bk = `${e.nsIdx}:${e.key}`;
+		if (e.typeCode === 66) {
+			if (!blobDataChunks.has(bk)) blobDataChunks.set(bk, /* @__PURE__ */ new Map());
+			const payload = e.childData ?? new Uint8Array(0);
+			blobDataChunks.get(bk).set(e.chunkIndex, payload);
+		} else if (e.typeCode === 72) {
+			const view = new DataView(e.inlineData.buffer, e.inlineData.byteOffset, 8);
+			blobIndex.set(bk, {
+				totalSize: view.getUint32(0, true),
+				chunkCount: e.inlineData[4],
+				chunkStart: e.inlineData[5]
+			});
+		} else if (e.typeCode === 65) {
+			const size = new DataView(e.inlineData.buffer, e.inlineData.byteOffset, 8).getUint16(0, true);
+			const payload = e.childData ?? new Uint8Array(0);
+			v1Blobs.set(bk, {
+				size,
+				data: payload
+			});
+		}
+	}
+	const result = {};
+	for (const e of allEntries) {
+		if (e.nsIdx === 0) continue;
+		if (e.typeCode === 66 || e.typeCode === 72) continue;
+		const nsName = nsIdxToName.get(e.nsIdx);
+		if (nsName === void 0) continue;
+		if (!result[nsName]) result[nsName] = [];
+		const bk = `${e.nsIdx}:${e.key}`;
+		if (PRIMITIVE_TYPES.has(e.typeCode)) {
+			const val = parsePrimitive(e.typeCode, e.inlineData);
+			const enc = e.typeCode === 1 ? "u8" : e.typeCode === 17 ? "i8" : e.typeCode === 2 ? "u16" : e.typeCode === 18 ? "i16" : e.typeCode === 4 ? "u32" : e.typeCode === 20 ? "i32" : e.typeCode === 8 ? "u64" : "i64";
+			result[nsName].push({
+				name: e.key,
+				encoding: enc,
+				value: val
+			});
+		} else if (e.typeCode === 33) {
+			const size = new DataView(e.inlineData.buffer, e.inlineData.byteOffset, 8).getUint16(0, true);
+			const payload = e.childData ?? new Uint8Array(0);
+			const str = new TextDecoder().decode(payload.subarray(0, Math.max(0, size - 1)));
+			result[nsName].push({
+				name: e.key,
+				encoding: "string",
+				value: str
+			});
+		} else if (e.typeCode === 65) {
+			const v1 = v1Blobs.get(bk);
+			if (v1) {
+				const data = v1.data.subarray(0, v1.size);
+				result[nsName].push({
+					name: e.key,
+					encoding: "blob_data",
+					value: new Uint8Array(data)
+				});
+			}
+		}
+	}
+	for (const [bk, chunks] of blobDataChunks) {
+		const [nsIdxStr, ...keyParts] = bk.split(":");
+		const nsIdx = parseInt(nsIdxStr);
+		const key = keyParts.join(":");
+		const nsName = nsIdxToName.get(nsIdx);
+		if (nsName === void 0) continue;
+		const idx = blobIndex.get(bk);
+		const allChunkData = [...chunks.keys()].sort((a, b) => a - b).map((k) => chunks.get(k));
+		const totalRaw = allChunkData.reduce((acc, c) => acc + c.length, 0);
+		const assembled = new Uint8Array(totalRaw);
+		let off = 0;
+		for (const c of allChunkData) {
+			assembled.set(c, off);
+			off += c.length;
+		}
+		const trimmed = idx ? assembled.subarray(0, idx.totalSize) : assembled;
+		if (!result[nsName]) result[nsName] = [];
+		result[nsName].push({
+			name: key,
+			encoding: "blob_data",
+			value: new Uint8Array(trimmed)
+		});
+	}
+	return result;
+}
+//#endregion
+export { PAGE_STATE_FULL as a, PAGE_STATE_ACTIVE as i, ENCODING_TO_TYPE_CODE as n, PAGE_SIZE as r, decodeNVS as t };

package/dist/esm/esp-nvs-decode.js

@@ -0,0 +1,31 @@
+import { t as decodeNVS } from "./decoder.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+//#region src/cli/esp-nvs-decode.ts
+function printUsage() {
+	console.error("Usage: esp-nvs-decode <partition.bin>");
+	console.error("       npm run decode -- <partition.bin>");
+}
+function toJsonFriendly(value) {
+	if (value instanceof Uint8Array) return Buffer.from(value).toString("base64");
+	if (typeof value === "bigint") return value.toString();
+	if (Array.isArray(value)) return value.map((item) => toJsonFriendly(item));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toJsonFriendly(item)]));
+	return value ?? null;
+}
+function main(args) {
+	const inputPath = args[0];
+	if (!inputPath || inputPath === "-h" || inputPath === "--help") {
+		printUsage();
+		process.exit(inputPath ? 0 : 1);
+	}
+	const absoluteInputPath = path.resolve(process.cwd(), inputPath);
+	if (!fs.existsSync(absoluteInputPath)) {
+		console.error(`Input file not found: ${absoluteInputPath}`);
+		process.exit(1);
+	}
+	const decoded = decodeNVS(fs.readFileSync(absoluteInputPath));
+	process.stdout.write(`${JSON.stringify(toJsonFriendly(decoded), null, 2)}\n`);
+}
+//#endregion
+export { main };