bytepeel 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pinta365
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# bytepeel (WebAssembly)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Peel layers of encoding off binary data, and edit it in place, from
+JavaScript: hex, xxd/hexdump dumps, base64, PEM (incl. bundles), JWT,
+gzip/zlib/zstd, DER/ASN.1, CBOR, MessagePack and schemaless protobuf.
+
+One `bytepeel.wasm` with no imports and no JS dependencies; runs in Node
+(≥18), Deno, Bun and browsers.
+
+```sh
+npm install bytepeel              # npm (Node, Bun, bundlers)
+deno add jsr:@pinta365/bytepeel   # JSR (Deno; also npx jsr add for Node)
+```
+
+The JSR package imports from `"@pinta365/bytepeel"` and has the same API.
+
+```js
+import { load, raw, BytepeelError } from "bytepeel";
+
+const bp = await load();
+
+bp.peel("ChRTR1ZzYkc4c0lIZHZjbXhrSVNFPRAq");   // the decoded tree (object)
+bp.tree("1a03089601");                          // the text outline
+bp.get(pem, "0.0.5.2.0.1").value;               // "ISRG Root X2"
+bp.getRaw("1a03089601", "3.1");                 // Uint8Array [0x96, 0x01]
+
+// Edits return the data in its original outer format (hex stays hex, PEM
+// stays PEM, ...), with every other byte preserved. Each edit is verified.
+const out = bp.edit("08 96 01 12 03 66 6f 6f", [
+  { add: "3", value: 42 },
+  { del: "2" },
+]);
+new TextDecoder().decode(out);                  // "08 96 01 18 2a"
+```
+
+- **Options** (all methods): `{ in: "auto"|"hex"|"base64"|"raw", as:
+  "protobuf"|"der"|"cbor"|"msgpack"|"text"|"bytes", depth, alts, max_items }`.
+- **Input:** a string (UTF-8) or `Uint8Array`/`ArrayBuffer`/typed array.
+- **Values** are typed: a string is text (never parsed, so `"42"` is the
+  text `42`); an integer `number` or a `bigint` is an integer; other numbers
+  are floats; `true`/`false`/`null`; a `Uint8Array` is bytes. Use
+  `raw("sint:-2")`, `raw("float:1")` for the CLI value syntax.
+- **64-bit integers are JSON strings** in `peel`/`get` output, so they never
+  lose precision.
+- **Errors** throw `BytepeelError` with the CLI's stable `code` (e.g.
+  `PATH_NOT_FOUND`) and `offset`.
+- **Loading:** from npm, `load()` reads `bytepeel.wasm` next to `index.js`
+  (a file read in Node/Deno/Bun, `fetch` over HTTP). The JSR package embeds
+  the module, so `load()` needs no file or network access (no Deno
+  permissions). Pass the bytes, a URL, a `Response`, or a compiled
+  `WebAssembly.Module` to load it yourself.
+
+The JSON schema, paths and edit rules are in
+[docs/DESIGN.md](https://github.com/pinta365/bytepeel/blob/main/docs/DESIGN.md).
+
+## Building
+
+```sh
+rustup target add wasm32-unknown-unknown
+npm run build      # cargo build --profile wasm ...; copies bytepeel.wasm here and
+                   # writes bytepeel_wasm.js (the module as base64, for JSR)
+npm test           # node --test; also: deno test --allow-read test/, bun test test/
+```

package/index.d.ts

@@ -0,0 +1,48 @@
+export interface Options {
+  /** How to read the top-level input (default "auto"). */
+  in?: "auto" | "hex" | "base64" | "raw";
+  /** Force the interpretation of the first decoded byte layer. */
+  as?: "protobuf" | "der" | "cbor" | "msgpack" | "text" | "bytes";
+  /** Max nesting of layers and messages (default 16). */
+  depth?: number;
+  /** Max interpretations kept per protobuf LEN field (default 3). */
+  alts?: number;
+  /** Max protobuf fields, CBOR/MessagePack values and DER elements in total (default 1000000). */
+  max_items?: number;
+}
+
+/**
+ * A value for an edit. Strings are text (never parsed); numbers that are
+ * integers are integers, other numbers are floats; Uint8Array is bytes.
+ * Use raw("sint:-2"), raw("float:1") etc. for the CLI value syntax.
+ */
+export type Value = string | number | bigint | boolean | null | Uint8Array | { syntax: string };
+
+export type Edit =
+  | { set: string; value: Value }
+  | { add: string; value: Value }
+  | { del: string };
+
+/** The decoded tree. See docs/DESIGN.md for the full schema. */
+export type Node = { codec: string; range: [number, number]; confidence: number; [key: string]: unknown };
+
+export interface Bytepeel {
+  peel(input: string | Uint8Array | ArrayBuffer | ArrayBufferView, opts?: Options): Node;
+  tree(input: string | Uint8Array | ArrayBuffer | ArrayBufferView, opts?: Options): string;
+  get(input: string | Uint8Array | ArrayBuffer | ArrayBufferView, path: string, opts?: Options): Record<string, unknown>;
+  getRaw(input: string | Uint8Array | ArrayBuffer | ArrayBufferView, path: string, opts?: Options): Uint8Array;
+  edit(input: string | Uint8Array | ArrayBuffer | ArrayBufferView, edits: Edit[], opts?: Options): Uint8Array;
+}
+
+export class BytepeelError extends Error {
+  /** Stable SCREAMING_SNAKE identifier, e.g. "PATH_NOT_FOUND". */
+  readonly code: string;
+  /** Byte offset into the buffer being decoded, or null. */
+  readonly offset: number | null;
+  readonly detail: string;
+}
+
+/** Pass a value in the CLI value syntax verbatim. */
+export function raw(syntax: string): { syntax: string };
+
+export function load(source?: BufferSource | URL | string | Response | WebAssembly.Module): Promise<Bytepeel>;

package/index.js

@@ -0,0 +1,186 @@
+// @ts-self-types="./index.d.ts"
+// bytepeel for JavaScript: a thin wrapper over bytepeel.wasm (Node, Deno,
+// Bun, browsers). See README.md. The JSON schema is docs/DESIGN.md.
+
+const OP_PEEL = 0;
+const OP_TREE = 1;
+const OP_GET = 2;
+const OP_GET_RAW = 3;
+const OP_EDIT = 4;
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+/** An error from bytepeel, with the same stable `code` the CLI prints. */
+export class BytepeelError extends Error {
+  constructor({ code, message, offset }) {
+    super(`${code}: ${message}`);
+    this.name = "BytepeelError";
+    /** Stable SCREAMING_SNAKE identifier, e.g. "PATH_NOT_FOUND". */
+    this.code = code;
+    /** Byte offset into the buffer being decoded, or null. */
+    this.offset = offset;
+    this.detail = message;
+  }
+}
+
+/** Pass a value in the CLI value syntax verbatim, e.g. raw("sint:-2"). */
+export function raw(syntax) {
+  return { syntax: String(syntax) };
+}
+
+function toBytes(input) {
+  if (typeof input === "string") return enc.encode(input);
+  if (input instanceof Uint8Array) return input;
+  if (input instanceof ArrayBuffer) return new Uint8Array(input);
+  if (ArrayBuffer.isView(input)) {
+    return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+  }
+  throw new TypeError("input must be a string, Uint8Array, ArrayBuffer or typed array");
+}
+
+function optsString(opts = {}) {
+  const lines = [];
+  for (const [k, v] of Object.entries(opts)) {
+    if (v === undefined) continue;
+    if (!["in", "as", "depth", "alts", "max_items"].includes(k)) {
+      throw new TypeError(`unknown option '${k}' (in, as, depth, alts, max_items)`);
+    }
+    lines.push(`${k}=${v}`);
+  }
+  return lines.join("\n");
+}
+
+const HEX = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+
+/** A JS value to the CLI value syntax. Strings are text, never parsed. */
+function valueSyntax(v) {
+  if (v !== null && typeof v === "object" && "syntax" in v) return v.syntax;
+  if (v === null) return "null";
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (typeof v === "bigint") return v.toString();
+  if (typeof v === "number") {
+    if (Number.isInteger(v)) {
+      if (!Number.isSafeInteger(v)) {
+        throw new RangeError(`${v} is not a safe integer; pass a BigInt`);
+      }
+      return String(v);
+    }
+    if (Number.isNaN(v)) return "float:NaN";
+    if (v === Infinity) return "float:Infinity";
+    if (v === -Infinity) return "float:-Infinity";
+    return `float:${v}`;
+  }
+  if (typeof v === "string") return `str:${v}`;
+  if (v instanceof Uint8Array || ArrayBuffer.isView(v) || v instanceof ArrayBuffer) {
+    const b = toBytes(v);
+    let s = "hex:";
+    for (const x of b) s += HEX[x];
+    return s;
+  }
+  throw new TypeError(`unsupported value type: ${typeof v}`);
+}
+
+function editsString(edits) {
+  if (!Array.isArray(edits) || edits.length === 0) {
+    throw new TypeError("edits must be a non-empty array");
+  }
+  const parts = [];
+  for (const e of edits) {
+    if ("set" in e) parts.push("set", e.set, valueSyntax(e.value));
+    else if ("add" in e) parts.push("add", e.add, valueSyntax(e.value));
+    else if ("del" in e) parts.push("del", e.del, "");
+    else throw new TypeError("each edit is {set, value}, {add, value} or {del}");
+  }
+  for (const p of parts) {
+    if (p.includes("\0")) throw new TypeError("paths and values cannot contain NUL");
+  }
+  return parts.join("\0");
+}
+
+function wrap(instance) {
+  const { memory, bp_alloc, bp_free, bp_call } = instance.exports;
+
+  function put(bytes) {
+    const ptr = bp_alloc(bytes.length);
+    new Uint8Array(memory.buffer, ptr, bytes.length).set(bytes);
+    return [ptr, bytes.length];
+  }
+
+  function call(op, input, arg, opts) {
+    const bufs = [put(toBytes(input)), put(enc.encode(arg)), put(enc.encode(opts))];
+    try {
+      const res = bp_call(op, ...bufs[0], ...bufs[1], ...bufs[2]);
+      // Re-read the buffer: memory may have grown during the call.
+      const view = new DataView(memory.buffer);
+      const status = view.getUint8(res);
+      const len = view.getUint32(res + 1, true);
+      const body = new Uint8Array(memory.buffer, res + 5, len).slice();
+      bp_free(res, 5 + len);
+      if (status !== 0) throw new BytepeelError(JSON.parse(dec.decode(body)).error);
+      return body;
+    } finally {
+      for (const [p, n] of bufs) bp_free(p, n);
+    }
+  }
+
+  return {
+    /** Decode `input` into the node tree (DESIGN.md schema). */
+    peel(input, opts) {
+      return JSON.parse(dec.decode(call(OP_PEEL, input, "", optsString(opts))));
+    },
+    /** The human-readable outline (`--format tree`). */
+    tree(input, opts) {
+      return dec.decode(call(OP_TREE, input, "", optsString(opts)));
+    },
+    /** One protobuf field, DER element or CBOR/MessagePack value by path. */
+    get(input, path, opts) {
+      return JSON.parse(dec.decode(call(OP_GET, input, String(path), optsString(opts))));
+    },
+    /** The payload bytes at `path` (`--get PATH --format raw`). */
+    getRaw(input, path, opts) {
+      return call(OP_GET_RAW, input, String(path), optsString(opts));
+    },
+    /**
+     * Apply edits in order and return the re-encoded data, in the input's
+     * original outer format. Each edit is verified.
+     */
+    edit(input, edits, opts) {
+      return call(OP_EDIT, input, editsString(edits), optsString(opts));
+    },
+  };
+}
+
+async function readDefault() {
+  const url = new URL("./bytepeel.wasm", import.meta.url);
+  if (url.protocol === "file:") {
+    const { readFile } = await import("node:fs/promises");
+    return readFile(url);
+  }
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`failed to fetch ${url}: ${res.status}`);
+  return res.arrayBuffer();
+}
+
+/**
+ * Load bytepeel. `source` is optional: the wasm bytes, a URL, a Response,
+ * or a compiled WebAssembly.Module. By default bytepeel.wasm next to this
+ * file is used.
+ */
+export async function load(source) {
+  let module;
+  if (source instanceof WebAssembly.Module) {
+    module = source;
+  } else {
+    let bytes = source;
+    if (source === undefined) bytes = await readDefault();
+    else if (source instanceof URL || typeof source === "string") {
+      bytes = await (await fetch(source)).arrayBuffer();
+    } else if (typeof Response !== "undefined" && source instanceof Response) {
+      bytes = await source.arrayBuffer();
+    }
+    module = await WebAssembly.compile(bytes);
+  }
+  const instance = await WebAssembly.instantiate(module, {});
+  return wrap(instance);
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "bytepeel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Peel layers of encoding off binary data (hex, base64, PEM, JWT, gzip, zstd, protobuf, DER/ASN.1, CBOR, MessagePack) and edit it in place. WebAssembly, no dependencies.",
+  "license": "MIT",
+  "author": "Pinta365",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pinta365/bytepeel.git",
+    "directory": "npm"
+  },
+  "homepage": "https://github.com/pinta365/bytepeel#readme",
+  "bugs": "https://github.com/pinta365/bytepeel/issues",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./bytepeel.wasm": "./bytepeel.wasm"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "bytepeel.wasm",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "sh build.sh",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "protobuf",
+    "asn1",
+    "der",
+    "cbor",
+    "msgpack",
+    "base64",
+    "jwt",
+    "decoder",
+    "wasm"
+  ]
+}