byte-packet

Overview

A BytePacket is a data structure designed to encapsulate and manage binary data (bytes) in a compact and secure format. It is used in situations where you need to handle and transmit small pieces of data, ensuring that the integrity of the data is maintained through checksum validation. byte-packet is a lightweight utility module designed for generating, manipulating, and validating BytePacket objects in Node.js or the browser. Emphasis on performance, minimalism, and ease of integration.

The name byte-packet comes from this library's use of byte arrays (Uint8Array)as the central store of data. Uint8Array's are memory efficient, highly compatible, and interoperable.

Features

• Cryptographically Secure Random Payloads: Generate secure random data with randomness that meets cryptographic standards.
• Checksum Calculation and Validation: Each BytePacket includes a checksum to ensure data integrity. Corruption to the data will result in an invalid payload/checksum pair.
• Flexible Byte Packet Management: Split, combine, and manage byte arrays packets with custom metadata flags, payload sizes, and checksum sizes.
• Encoding/Decoding: Encode and decode data using Base58 for compact representation.
• Header Flags: The flag field in the header can be used to store meta data about the packet.

Installation

npm install byte-packet

Help Improve – Your Feedback Matters! 🚀

I'm committed to making this npm package the best it can be, and need your input to do it! If this package was useful, met your expectations, or even if it fell short in some way, I'd love to hear from you. Your feedback will help me understand what's working and what features are in demand.

👉 Click here or scan the QR code to give feedback in less than 60 seconds – your insights will directly influence future updates and features. Thank you for your insights! 🙌

Usage

Generating a BytePacket

const BytePacket = require('byte-packet');

// Example payload
const payload = new Uint8Array([1, 2, 3, 4]);

// Generate a packet
const packet = BytePacket.generatePacket(payload);

console.log(packet); 
/**
 * Output:
 * BytePacket: {packet: Uint8Array(7) [ 32, 0, 1, 2, 3, 4, 8 ] }
 * 
 * Explanation of Output:
 * [32] is the header; 32 = 0b00100000 where 0b001_____ is the 3 bit checksumSize (defaults = 1) and 0b___00000 is the 5-bit flag (default = 0).
 * [0, 1, 2, 3, 4] is the payload, i.e., the data.
 * [8] is the checksum = first n bytes of sha256(payload) where n is the   * checksumSize.
 */

Generating a Random Packet

const BytePacket = require('byte-packet');

// Generate a random packet with a 10-byte payload, 2-byte checksum, and flag value of 1
const randomPacket = BytePacket.generateRandomPacket(10, 2, 1);

console.log(randomPacket);

Validating a Packet

const BytePacket = require('byte-packet');

// Example payload
const payload = new Uint8Array([0x01, 0x02, 0x03]);

// Generate a packet
const packet = BytePacket.generatePacket(payload);

// Check if the packet is valid
console.log(packet.isValid); // true

Getting the flag value of a packet

const BytePacket = require('byte-packet');

// Example payload
const payload = new Uint8Array([0x01, 0x02, 0x03]);

// Generate a packet with a flag value of 5
const packet = BytePacket.generatePacket(payload, 1, 5);

console.log(packet.flag); // 5

Encoding wth Base58

const BytePacket = require('byte-packet');

// Example payload
const payload = new Uint8Array([0x01, 0x02, 0x03]);

// Generate a packet
const packet = BytePacket.generatePacket(payload);

// Get the Base58 encoded string
const encoded = packet.encodeBase58();

console.log(encoded); // Base58 string representation of the packet

Decoding a BytePacket from Base58

const BytePacket = require('byte-packet');

// Example Base58 string
const encoded = '3vQB7B6MrGQZaxCuFg4oh';

// Decode the Base58 string back into a BytePacket
try {
    const decodedPacket = BytePacket.decodeBase58(encoded);
    console.log(decodedPacket.packet); // Uint8Array of the decoded packet
} catch (error) {
    console.error(error.message);
}

API: class BytePacket

Constructor

new BytePacket(packet)

• Description: Creates a BytePacket instance from the specified Uint8Array packet data.
• Parameters:
  • packet (Uint8Array): The binary data to be encapsulated in the BytePacket.
• Returns: A new BytePacket instance.

Properties

packet

• Description: The entire Uint8Array representing the BytePacket, including the header, payload, and checksum.
• Type: Uint8Array
• Access: Read-only

header

• Description: Retrieves the header component of the BytePacket.
• Returns: Uint8Array - A Uint8Array containing the header.

checksumSize

• Description: Retrieves the size of the checksum based on the information in the header.
• Returns: number - The size of the checksum in bytes.

length

• Description: Retrieves the total length of the BytePacket, including the header, payload, and checksum.
• Returns: number - The length of the BytePacket in bytes.

payloadSize

• Description: Retrieves the size of the payload portion of the BytePacket.
• Returns: number - The size of the payload in bytes.

payload

• Description: Retrieves the payload component of the BytePacket.
• Returns: Uint8Array - A Uint8Array containing the payload.

checksum

• Description: Retrieves the checksum component of the BytePacket.
• Returns: Uint8Array - A Uint8Array containing the checksum.

flag

• Description: Retrieves the flag value stored in the header.
• Returns: number - The 5-bit flag value.

isValid

• Description: Checks whether the BytePacket is valid by verifying the checksum against its payload.
• Returns: boolean - True if the packet is valid; otherwise, False.

encodeBase58

• Description: Encodes the BytePacket into a Base58 string.
• Returns: string - The Base58-encoded string representing the BytePacket.

Methods

slice(start=0, end=this.packet.length)

• Description: Extracts a slice of the BytePacket.
• Parameters:
  • start (number): The zero-based index at which to begin extraction. Default is 0.
  • end (number): The zero-based index before which to end extraction. Default is the length of the packet.
• Returns: Uint8Array - A Uint8Array slice of the BytePacket.

Static Methods

static calculateChecksum(payload, size)

• Description: Calculates a checksum for the given payload.
• Parameters:
  • payload (Uint8Array): The data for which the checksum is to be calculated.
  • size (number): The size of the checksum to generate.
• Returns: Uint8Array - A Uint8Array containing the calculated checksum.

static generateHeader(checksumSize, flag)

• Description: Generates a 1-byte header based on the checksum size and flag.
• Parameters:
  • checksumSize (number): A 3-bit value (0-7) representing the checksum size.
  • flag (number): A 5-bit value (0-31) representing additional flags.
• Returns: Uint8Array - A Uint8Array containing the 1-byte header.

static generateRandomPayload(size)

• Description: Generates a random Uint8Array payload of the specified size.
• Parameters:
  • size (number): The size of the payload to generate.
• Returns: Uint8Array - A Uint8Array filled with random values.

static Uint8ArraysEqual(arr1, arr2)

• Description: Compares two Uint8Array objects for equality in both length and content.
• Parameters:
  • arr1 (Uint8Array): The first Uint8Array to compare.
  • arr2 (Uint8Array): The second Uint8Array to compare.
• Returns: boolean - True if the arrays are equal; otherwise, False.

static checkPair(payload, checksum)

• Description: Validates a payload against its checksum.
• Parameters:
  • payload (Uint8Array): The data to be validated.
  • checksum (Uint8Array): The checksum to validate against.
• Returns: boolean - True if the checksum is valid; otherwise, False.

static combineUint8Arrays(arrays)

• Description: Combines multiple Uint8Array objects into a single Uint8Array.
• Parameters:
  • arrays (Uint8Array[]): An array of Uint8Array instances to combine.
• Returns: Uint8Array - A single Uint8Array containing the concatenated data.

static generatePacket(payload, checksumSize=1, flag=0)

• Description: Generates a BytePacket from a payload, checksum size, and flag.
• Parameters:
  • payload (Uint8Array): The data to be included in the packet.
  • checksumSize (number, optional): The size of the checksum in bytes. Default is 1 byte.
  • flag (number, optional): The flag to include in the header. Default is 0.
• Returns: BytePacket - The generated BytePacket.

static generateRandomPacket(payloadSize, checksumSize, flag)

• Description: Generates a random BytePacket with a specified payload size, checksum size, and header flag.
• Parameters:
  • payloadSize (number): The size of the payload to generate.
  • checksumSize (number): The size of the checksum to generate.
  • flag (number): The flag value to include in the header.
• Returns: BytePacket - The generated BytePacket.

static decodeBase58(base58)

• Description: Decodes a Base58-encoded string into a BytePacket.
• Parameters:
  • base58 (string): The Base58-encoded string to decode.
• Returns: BytePacket - The decoded BytePacket.
• Throws: Error - If the decoded packet is not valid.

Contributing

I’d love to welcome contributions to the byte-packet module. Whether it’s bug fixes, new features, or improvements to the existing codebase, feedback and input is highly valued.

How to Contribute

Fork the Repository: Start by forking the repo to your own GitHub account. Clone the Repo: Clone your fork locally to work on it.

git clone https://github.com/your-username/byte-packet.git
cd byte-packet

Create a Branch: Create a new branch to work on your changes.

git checkout -b my-new-feature

Make Changes: Implement your changes or additions. Run Tests: If you add new features or fix bugs, please run the tests to ensure the code remains stable. Write new tests for new features.

npm install --save-dev jest
npm run test

Lint your changes: Lint your changes with the eslint.config.js file for consistency accross the library.

npm install --save-dev eslint
npm run lint

#Or if you want eslint to fix:

npm run lint:fix

Commit and Push: Commit your changes and push them to your forked repository.

git add .
git commit -m "Description of your changes"
git push origin my-new-feature

Create a Pull Request: Once your changes are ready, create a pull request to the main repository. You can do this by visiting this link Pull Requests.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

Adam Ballinger - GitHub

I'm excited about Node.js and npm. My focus is on writing code that works seamlessly in both Node.js and the browser, with a strong emphasis on creating small, lightweight packages. My goal is to ensure that everything I write is easy to understand, even for beginners, quick to implement, and adheres to best practices and conventions.

I believe in the importance of writing code as human-friendly as possible. I am an amateur with much to learn, I am dedicated to improving my skills and would appreciate any feedback or guidance from the community.

To-Do

1. Configurable Checksum Algorithms

• Current Limitation: The module currently uses single SHA-256 for checksum calculation.
• Suggested Improvement: Allow users to choose from different cryptographic hash functions (e.g., SHA-1, SHA-512, HMAC) or even provide their custom checksum algorithms. This flexibility could cater to a broader range of security requirements.

2. Support for Variable-Length Headers

• Current Limitation: The module uses a fixed-size 1-byte header, which may limit the amount of metadata that can be stored.
• Suggested Improvement: Implement variable-length headers that can store more information, such as versioning, timestamps, or additional flags.

3. Encryption/Decryption of Payloads

• Current Limitation: The module focuses on packet generation and validation but does not provide encryption capabilities.
• Suggested Improvement: Add functionality to encrypt and decrypt the payloads using symmetric or asymmetric encryption, which would further secure the data packets during transmission.

4. Serialization/Deserialization Support

• Current Limitation: The module does not provide methods to serialize or deserialize packet objects for storage or transmission in different formats (e.g., JSON, binary).
• Suggested Improvement: Add methods to convert packets to and from serialized formats, making it easier to store and transmit them over various protocols.

5. Packet Integrity and Authenticity Verification

• Current Limitation: The module verifies the integrity of the packet via checksum but does not handle authenticity.
• Suggested Improvement: Introduce digital signature functionality to verify the authenticity of the packets, ensuring that they have not been tampered with and are from a trusted source.

6. Extensive Unit Testing and Benchmarking

• Current Limitation: The module is not extensively tested.
• Suggested Improvement: Develop a comprehensive suite of unit tests covering edge cases, as well as performance benchmarks to give users confidence in the module’s reliability and efficiency.

7. Support for Different Encoding Schemes

• Current Limitation: The module currently supports Base58 encoding/decoding.
• Suggested Improvement: Add support for other encoding schemes like Base32, Base64, or Bech32 to make the module more versatile in different application scenarios.

8. Cross-Platform Compatibility

• Current Limitation: While intended to be compatible with Node.js or the browser, the module has not been tested in the browser.
• Suggested Improvement: Ensure that the module is fully compatible with both Node.js and browser environments.

9. Error Correction

• Current Limitation: Packets can be checked for validity but the data can not be recovered if there is any loss
• Suggested Improvement: Introduce optional error correction methods such as Reed-Soloman.

10. QR Code Generation

• Suggested Improvement: Add methods to generate QR codes.