@kduma-oss/pcf 0.0.1

package/src/entry.ts

@@ -0,0 +1,152 @@
+/**
+ * The fixed 141-byte partition entry (spec section 5.2).
+ */
+
+import {
+  ENTRY_SIZE,
+  HASH_FIELD_SIZE,
+  LABEL_SIZE,
+  NIL_UID,
+  TYPE_RESERVED,
+} from "./consts.js";
+import { PcfError } from "./errors.js";
+import { HashAlgo, hashAlgoFromId, hashAlgoId } from "./hash.js";
+
+/** One partition's metadata. */
+export interface PartitionEntry {
+  /** Application-defined type (`0` and `0xFFFFFFFF` are reserved). */
+  partitionType: number;
+  /** 16-byte unique identifier. */
+  uid: Uint8Array;
+  /** 32-byte ASCII label, NUL-padded. */
+  label: Uint8Array;
+  /** Absolute offset of the partition's data region. */
+  startOffset: bigint;
+  /** Bytes reserved for the partition. */
+  maxLength: bigint;
+  /** Bytes currently used (a contiguous prefix of the reservation). */
+  usedBytes: bigint;
+  /** Algorithm used for `dataHash`. */
+  dataHashAlgo: HashAlgo;
+  /** 64-byte data hash field. */
+  dataHash: Uint8Array;
+}
+
+/** Serialise an entry to its on-disk 141-byte layout. */
+export function entryToBytes(e: PartitionEntry): Uint8Array {
+  const b = new Uint8Array(ENTRY_SIZE);
+  const view = new DataView(b.buffer);
+  view.setUint32(0, e.partitionType >>> 0, true);
+  b.set(e.uid, 4);
+  b.set(e.label, 20);
+  view.setBigUint64(52, e.startOffset, true);
+  view.setBigUint64(60, e.maxLength, true);
+  view.setBigUint64(68, e.usedBytes, true);
+  b[76] = hashAlgoId(e.dataHashAlgo);
+  b.set(e.dataHash, 77);
+  return b;
+}
+
+/** Parse an entry from its on-disk 141-byte layout. */
+export function entryFromBytes(b: Uint8Array): PartitionEntry {
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  const partitionType = view.getUint32(0, true);
+  const uid = b.slice(4, 20);
+  const label = b.slice(20, 52);
+  const startOffset = view.getBigUint64(52, true);
+  const maxLength = view.getBigUint64(60, true);
+  const usedBytes = view.getBigUint64(68, true);
+  const dataHashAlgo = hashAlgoFromId(b[76]!);
+  const dataHash = b.slice(77, 77 + HASH_FIELD_SIZE);
+  return {
+    partitionType,
+    uid,
+    label,
+    startOffset,
+    maxLength,
+    usedBytes,
+    dataHashAlgo,
+    dataHash,
+  };
+}
+
+/**
+ * Apply the conformance checks a reader must run on a live entry
+ * (spec C5, C6, C7).
+ */
+export function validateEntry(e: PartitionEntry): void {
+  if (e.partitionType === TYPE_RESERVED) {
+    throw PcfError.reservedType();
+  }
+  if (bytesEqual(e.uid, NIL_UID)) {
+    throw PcfError.nilUid();
+  }
+  if (e.usedBytes > e.maxLength) {
+    throw PcfError.usedExceedsMax();
+  }
+  decodeLabel(e.label); // validates label bytes
+}
+
+/** Free bytes remaining in a partition (`max_length - used_bytes`). */
+export function freeBytes(e: PartitionEntry): bigint {
+  return e.usedBytes > e.maxLength ? 0n : e.maxLength - e.usedBytes;
+}
+
+/** Decode an entry's label as a string (reads up to the first NUL). */
+export function entryLabelString(e: PartitionEntry): string {
+  return decodeLabel(e.label);
+}
+
+/** Build a 32-byte label field from a string (spec section 10). */
+export function encodeLabel(s: string): Uint8Array {
+  // Labels are ASCII (0x01..0x7F); reject anything that is not.
+  const out = new Uint8Array(LABEL_SIZE);
+  let n = 0;
+  for (const ch of s) {
+    const code = ch.codePointAt(0)!;
+    if (code === 0 || code >= 0x80) {
+      throw PcfError.invalidLabel();
+    }
+    if (n >= LABEL_SIZE) {
+      throw PcfError.invalidLabel();
+    }
+    out[n] = code;
+    n++;
+  }
+  return out;
+}
+
+/**
+ * Decode a 32-byte label field: read until the first NUL or 32 bytes,
+ * rejecting any byte >= 0x80 (spec section 10).
+ */
+export function decodeLabel(label: Uint8Array): string {
+  let end = LABEL_SIZE;
+  for (let i = 0; i < LABEL_SIZE; i++) {
+    const c = label[i]!;
+    if (c === 0) {
+      end = i;
+      break;
+    }
+    if (c >= 0x80) {
+      throw PcfError.invalidLabel();
+    }
+  }
+  let s = "";
+  for (let i = 0; i < end; i++) {
+    s += String.fromCharCode(label[i]!);
+  }
+  return s;
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/errors.ts

@@ -0,0 +1,124 @@
+/**
+ * Error type shared across the library (mirrors the reference `Error` enum).
+ */
+
+/** Discriminant identifying which kind of {@link PcfError} occurred. */
+export enum PcfErrorKind {
+  /** Underlying I/O failure. */
+  Io = "Io",
+  /** The file does not begin with the PCF magic. */
+  BadMagic = "BadMagic",
+  /** The file's major version is not implemented by this library. */
+  UnsupportedMajor = "UnsupportedMajor",
+  /** A hash-algorithm identifier is not in the registry. */
+  UnknownHashAlgo = "UnknownHashAlgo",
+  /** A live entry used the reserved type `0x00000000`. */
+  ReservedType = "ReservedType",
+  /** A live entry used the NIL UID. */
+  NilUid = "NilUid",
+  /** `used_bytes` exceeded `max_length` for an entry. */
+  UsedExceedsMax = "UsedExceedsMax",
+  /** A label byte was outside the permitted range (>= 0x80), or too long. */
+  InvalidLabel = "InvalidLabel",
+  /** A table block failed hash verification. */
+  TableHashMismatch = "TableHashMismatch",
+  /** A partition's data failed hash verification. */
+  DataHashMismatch = "DataHashMismatch",
+  /** An in-place update supplied more data than the partition's reservation. */
+  DataTooLarge = "DataTooLarge",
+  /** No partition with the requested UID exists. */
+  NotFound = "NotFound",
+  /** An attempt was made to add a partition whose UID already exists. */
+  DuplicateUid = "DuplicateUid",
+}
+
+/** All ways a PCF operation can fail. */
+export class PcfError extends Error {
+  /** The kind of failure. */
+  readonly kind: PcfErrorKind;
+  /**
+   * Optional numeric detail (e.g. the unsupported major version or the unknown
+   * hash-algorithm id), preserved for the variants that carry one.
+   */
+  readonly value?: number;
+
+  constructor(kind: PcfErrorKind, message: string, value?: number) {
+    super(message);
+    this.name = "PcfError";
+    this.kind = kind;
+    this.value = value;
+    // Restore the prototype chain when targeting older runtimes.
+    Object.setPrototypeOf(this, PcfError.prototype);
+  }
+
+  static badMagic(): PcfError {
+    return new PcfError(PcfErrorKind.BadMagic, "bad magic: not a PCF file");
+  }
+
+  static unsupportedMajor(v: number): PcfError {
+    return new PcfError(
+      PcfErrorKind.UnsupportedMajor,
+      `unsupported major version ${v}`,
+      v,
+    );
+  }
+
+  static unknownHashAlgo(id: number): PcfError {
+    return new PcfError(
+      PcfErrorKind.UnknownHashAlgo,
+      `unknown hash algorithm id ${id}`,
+      id,
+    );
+  }
+
+  static reservedType(): PcfError {
+    return new PcfError(
+      PcfErrorKind.ReservedType,
+      "reserved partition type used for a live entry",
+    );
+  }
+
+  static nilUid(): PcfError {
+    return new PcfError(PcfErrorKind.NilUid, "NIL UID used for a live entry");
+  }
+
+  static usedExceedsMax(): PcfError {
+    return new PcfError(
+      PcfErrorKind.UsedExceedsMax,
+      "used_bytes exceeds max_length",
+    );
+  }
+
+  static invalidLabel(): PcfError {
+    return new PcfError(PcfErrorKind.InvalidLabel, "invalid label");
+  }
+
+  static tableHashMismatch(): PcfError {
+    return new PcfError(
+      PcfErrorKind.TableHashMismatch,
+      "table block hash mismatch",
+    );
+  }
+
+  static dataHashMismatch(): PcfError {
+    return new PcfError(
+      PcfErrorKind.DataHashMismatch,
+      "partition data hash mismatch",
+    );
+  }
+
+  static dataTooLarge(): PcfError {
+    return new PcfError(
+      PcfErrorKind.DataTooLarge,
+      "data larger than partition reservation",
+    );
+  }
+
+  static notFound(): PcfError {
+    return new PcfError(PcfErrorKind.NotFound, "partition not found");
+  }
+
+  static duplicateUid(): PcfError {
+    return new PcfError(PcfErrorKind.DuplicateUid, "duplicate UID");
+  }
+}

package/src/hash.ts

@@ -0,0 +1,165 @@
+/**
+ * Hash-algorithm registry (spec section 8).
+ *
+ * Each hash field in the format is a fixed 64-byte field accompanied by a
+ * `u8` algorithm identifier. Digests are stored left-aligned and zero-padded;
+ * CRC values are stored as little-endian integers, left-aligned and
+ * zero-padded (spec section 8.2).
+ *
+ * Digests are provided by the audited `@noble/hashes` package; the CRC variants
+ * are implemented locally in {@link "./crc"}.
+ */
+
+import { sha256, sha512 } from "@noble/hashes/sha2";
+import { md5, sha1 } from "@noble/hashes/legacy";
+import { blake3 } from "@noble/hashes/blake3";
+
+import { HASH_FIELD_SIZE } from "./consts.js";
+import { crc32, crc32c, crc64 } from "./crc.js";
+import { PcfError } from "./errors.js";
+
+/**
+ * A hash algorithm from the PCF registry (spec section 8.1).
+ *
+ * The numeric value of each member is exactly its on-disk registry id, so
+ * `algo as number` yields the id byte.
+ */
+export enum HashAlgo {
+  /** `0` — no verification. */
+  None = 0,
+  /** `1` — CRC-32/ISO-HDLC. */
+  Crc32 = 1,
+  /** `2` — CRC-32C (Castagnoli). */
+  Crc32c = 2,
+  /** `3` — CRC-64/XZ. */
+  Crc64 = 3,
+  /** `4` — MD5 (checksum use only). */
+  Md5 = 4,
+  /** `5` — SHA-1 (checksum use only). */
+  Sha1 = 5,
+  /** `16` — SHA-256 (default). */
+  Sha256 = 16,
+  /** `17` — SHA-512. */
+  Sha512 = 17,
+  /** `18` — BLAKE3. */
+  Blake3 = 18,
+}
+
+const KNOWN_IDS: ReadonlySet<number> = new Set([0, 1, 2, 3, 4, 5, 16, 17, 18]);
+
+/** Map a registry id byte to an algorithm (spec section 8.1). */
+export function hashAlgoFromId(id: number): HashAlgo {
+  if (!KNOWN_IDS.has(id)) {
+    throw PcfError.unknownHashAlgo(id);
+  }
+  return id as HashAlgo;
+}
+
+/** The registry id byte for an algorithm. */
+export function hashAlgoId(algo: HashAlgo): number {
+  return algo;
+}
+
+/** Number of significant bytes an algorithm writes into a hash field. */
+export function digestLen(algo: HashAlgo): number {
+  switch (algo) {
+    case HashAlgo.None:
+      return 0;
+    case HashAlgo.Crc32:
+    case HashAlgo.Crc32c:
+      return 4;
+    case HashAlgo.Crc64:
+      return 8;
+    case HashAlgo.Md5:
+      return 16;
+    case HashAlgo.Sha1:
+      return 20;
+    case HashAlgo.Sha256:
+    case HashAlgo.Blake3:
+      return 32;
+    case HashAlgo.Sha512:
+      return 64;
+  }
+}
+
+/** Whether an algorithm performs any verification (everything but `None`). */
+export function verifies(algo: HashAlgo): boolean {
+  return algo !== HashAlgo.None;
+}
+
+function writeU32Le(field: Uint8Array, value: number): void {
+  field[0] = value & 0xff;
+  field[1] = (value >>> 8) & 0xff;
+  field[2] = (value >>> 16) & 0xff;
+  field[3] = (value >>> 24) & 0xff;
+}
+
+function writeU64Le(field: Uint8Array, value: bigint): void {
+  let v = value;
+  for (let i = 0; i < 8; i++) {
+    field[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+}
+
+/**
+ * Compute the full 64-byte hash field for `data` per spec section 8.2.
+ *
+ * Digest-producing algorithms write their digest starting at byte 0; CRCs write
+ * a little-endian integer of their width; all remaining bytes are 0x00.
+ * Algorithm `None` yields an all-zero field.
+ */
+export function computeHashField(algo: HashAlgo, data: Uint8Array): Uint8Array {
+  const field = new Uint8Array(HASH_FIELD_SIZE);
+  switch (algo) {
+    case HashAlgo.None:
+      break;
+    case HashAlgo.Crc32:
+      writeU32Le(field, crc32(data));
+      break;
+    case HashAlgo.Crc32c:
+      writeU32Le(field, crc32c(data));
+      break;
+    case HashAlgo.Crc64:
+      writeU64Le(field, crc64(data));
+      break;
+    case HashAlgo.Md5:
+      field.set(md5(data), 0);
+      break;
+    case HashAlgo.Sha1:
+      field.set(sha1(data), 0);
+      break;
+    case HashAlgo.Sha256:
+      field.set(sha256(data), 0);
+      break;
+    case HashAlgo.Sha512:
+      field.set(sha512(data), 0);
+      break;
+    case HashAlgo.Blake3:
+      field.set(blake3(data), 0);
+      break;
+  }
+  return field;
+}
+
+/**
+ * Verify `data` against a stored 64-byte hash field. `None` always succeeds
+ * (no verification). Only the significant prefix is compared, per spec 8.2.
+ */
+export function verifyHashField(
+  algo: HashAlgo,
+  data: Uint8Array,
+  stored: Uint8Array,
+): boolean {
+  if (!verifies(algo)) {
+    return true;
+  }
+  const computed = computeHashField(algo, data);
+  const n = digestLen(algo);
+  for (let i = 0; i < n; i++) {
+    if (computed[i] !== stored[i]) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/header.ts

@@ -0,0 +1,50 @@
+/**
+ * The fixed 20-byte file header (spec section 4).
+ */
+
+import { HEADER_SIZE, MAGIC, VERSION_MAJOR } from "./consts.js";
+import { PcfError } from "./errors.js";
+
+/** Parsed file header. */
+export interface FileHeader {
+  /** Major format version. */
+  versionMajor: number;
+  /** Minor format version. */
+  versionMinor: number;
+  /** Absolute offset of the first table block. */
+  partitionTableOffset: bigint;
+}
+
+/** Serialise a header to its on-disk 20-byte layout. */
+export function headerToBytes(h: FileHeader): Uint8Array {
+  const b = new Uint8Array(HEADER_SIZE);
+  b.set(MAGIC, 0);
+  const view = new DataView(b.buffer);
+  view.setUint16(8, h.versionMajor, true);
+  view.setUint16(10, h.versionMinor, true);
+  view.setBigUint64(12, h.partitionTableOffset, true);
+  return b;
+}
+
+/**
+ * Parse a header from its on-disk 20-byte layout, validating magic and major
+ * version (spec conformance checks C1, C2).
+ */
+export function headerFromBytes(b: Uint8Array): FileHeader {
+  if (b.length < HEADER_SIZE) {
+    throw PcfError.badMagic();
+  }
+  for (let i = 0; i < MAGIC.length; i++) {
+    if (b[i] !== MAGIC[i]) {
+      throw PcfError.badMagic();
+    }
+  }
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  const versionMajor = view.getUint16(8, true);
+  if (versionMajor !== VERSION_MAJOR) {
+    throw PcfError.unsupportedMajor(versionMajor);
+  }
+  const versionMinor = view.getUint16(10, true);
+  const partitionTableOffset = view.getBigUint64(12, true);
+  return { versionMajor, versionMinor, partitionTableOffset };
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * # `pcf` — Partitioned Container Format (TypeScript implementation)
+ *
+ * A language-agnostic binary container that stores multiple independent regions
+ * of bytes ("partitions") in a single file. This package mirrors the written
+ * specification (`PCF-spec-v1.0.txt`) and the Rust reference implementation
+ * field-for-field and favours auditability over performance.
+ *
+ * ## Layout at a glance
+ *
+ * ```text
+ * [ 20-byte header ] [ table block(s) ] [ partition data regions ]
+ * ```
+ *
+ * All integers are little-endian. Free space is derived as
+ * `maxLength - usedBytes`.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Container, HashAlgo } from "pcf";
+ *
+ * const c = Container.create();
+ * const uid = new Uint8Array(16).fill(1);
+ * c.addPartition(0x10, uid, "notes", new TextEncoder().encode("hello world"), 64, HashAlgo.Sha256);
+ *
+ * c.verify();
+ * const entries = c.entries();
+ * console.log(new TextDecoder().decode(c.readPartitionData(entries[0]))); // "hello world"
+ * ```
+ */
+
+export * from "./consts.js";
+export { PcfError, PcfErrorKind } from "./errors.js";
+export {
+  HashAlgo,
+  hashAlgoFromId,
+  hashAlgoId,
+  digestLen,
+  verifies,
+  computeHashField,
+  verifyHashField,
+} from "./hash.js";
+export { crc32, crc32c, crc64 } from "./crc.js";
+export {
+  type FileHeader,
+  headerToBytes,
+  headerFromBytes,
+} from "./header.js";
+export {
+  type PartitionEntry,
+  entryToBytes,
+  entryFromBytes,
+  validateEntry,
+  freeBytes,
+  entryLabelString,
+  encodeLabel,
+  decodeLabel,
+} from "./entry.js";
+export {
+  type TableBlockHeader,
+  tableHeaderToBytes,
+  tableHeaderFromBytes,
+  computeTableHash,
+} from "./table.js";
+export { type Storage, MemoryStorage } from "./storage.js";
+export { NodeFileStorage } from "./node-storage.js";
+export { Container, type BlockView } from "./container.js";

package/src/node-storage.ts

@@ -0,0 +1,75 @@
+/**
+ * A {@link Storage} implementation backed by a Node file descriptor, the
+ * analogue of using `std::fs::File` with the reference implementation.
+ *
+ * This module imports `node:fs` and is therefore Node-only; the rest of the
+ * library is runtime-agnostic.
+ */
+
+import {
+  closeSync,
+  fstatSync,
+  openSync,
+  readSync,
+  writeSync,
+} from "node:fs";
+
+import type { Storage } from "./storage.js";
+
+/** File-descriptor backed random-access storage. */
+export class NodeFileStorage implements Storage {
+  private fd: number;
+
+  private constructor(fd: number) {
+    this.fd = fd;
+  }
+
+  /**
+   * Open `path` for reading and writing, creating it if necessary (mode
+   * `"r+"`-like with creation). Use `truncate` to start from an empty file.
+   */
+  static open(path: string, truncate = false): NodeFileStorage {
+    // "w+" truncates+creates for read/write; "a+"/"r+" otherwise.
+    const flags = truncate ? "w+" : "a+";
+    const fd = openSync(path, flags);
+    return new NodeFileStorage(fd);
+  }
+
+  readAt(offset: number, length: number): Uint8Array {
+    const buf = new Uint8Array(length);
+    let read = 0;
+    while (read < length) {
+      const n = readSync(this.fd, buf, read, length - read, offset + read);
+      if (n === 0) {
+        throw new Error(
+          `unexpected EOF: wanted ${length} bytes at offset ${offset}`,
+        );
+      }
+      read += n;
+    }
+    return buf;
+  }
+
+  writeAt(offset: number, data: Uint8Array): void {
+    let written = 0;
+    while (written < data.length) {
+      const n = writeSync(
+        this.fd,
+        data,
+        written,
+        data.length - written,
+        offset + written,
+      );
+      written += n;
+    }
+  }
+
+  size(): number {
+    return fstatSync(this.fd).size;
+  }
+
+  /** Close the underlying file descriptor. */
+  close(): void {
+    closeSync(this.fd);
+  }
+}