@nextera.one/tps-standard 0.4.3 → 0.5.1

package/dist/test/src/index.js

@@ -0,0 +1,963 @@
+/**
+ * TPS: Temporal Positioning System
+ * The Universal Protocol for Space-Time Coordinates.
+ * @packageDocumentation
+ * @version 0.4.2
+ * @license Apache-2.0
+ * @copyright 2026 TPS Standards Working Group
+ */
+export class TPS {
+  /**
+   * Registers a calendar driver plugin.
+   * @param driver - The driver instance to register.
+   */
+  static registerDriver(driver) {
+    this.drivers.set(driver.code, driver);
+  }
+  /**
+   * Gets a registered calendar driver.
+   * @param code - The calendar code.
+   * @returns The driver or undefined.
+   */
+  static getDriver(code) {
+    return this.drivers.get(code);
+  }
+  // --- CORE METHODS ---
+  static validate(input) {
+    if (input.startsWith("tps://")) return this.REGEX_URI.test(input);
+    return this.REGEX_TIME.test(input);
+  }
+  static parse(input) {
+    if (input.startsWith("tps://")) {
+      const match = this.REGEX_URI.exec(input);
+      if (!match || !match.groups) return null;
+      return this._mapGroupsToComponents(match.groups);
+    }
+    const match = this.REGEX_TIME.exec(input);
+    if (!match || !match.groups) return null;
+    return this._mapGroupsToComponents(match.groups);
+  }
+  /**
+   * SERIALIZER: Converts a components object into a full TPS URI.
+   * @param comp - The TPS components.
+   * @returns Full URI string (e.g. "tps://...").
+   */
+  static toURI(comp) {
+    // 1. Build Space Part
+    let spacePart = "unknown"; // Default safe fallback
+    if (comp.isHiddenLocation) {
+      spacePart = "hidden";
+    } else if (comp.isRedactedLocation) {
+      spacePart = "redacted";
+    } else if (comp.isUnknownLocation) {
+      spacePart = "unknown";
+    } else if (comp.latitude !== undefined && comp.longitude !== undefined) {
+      spacePart = `${comp.latitude},${comp.longitude}`;
+      if (comp.altitude !== undefined) {
+        spacePart += `,${comp.altitude}m`;
+      }
+    }
+    // 2. Build Time Part
+    let timePart = `T:${comp.calendar}`;
+    if (comp.calendar === "unix" && comp.unixSeconds !== undefined) {
+      timePart += `.s${comp.unixSeconds}`;
+    } else {
+      if (comp.millennium !== undefined) timePart += `.m${comp.millennium}`;
+      if (comp.century !== undefined) timePart += `.c${comp.century}`;
+      if (comp.year !== undefined) timePart += `.y${comp.year}`;
+      if (comp.month !== undefined) timePart += `.M${this.pad(comp.month)}`;
+      if (comp.day !== undefined) timePart += `.d${this.pad(comp.day)}`;
+      if (comp.hour !== undefined) timePart += `.h${this.pad(comp.hour)}`;
+      if (comp.minute !== undefined) timePart += `.n${this.pad(comp.minute)}`;
+      if (comp.second !== undefined) timePart += `.s${this.pad(comp.second)}`;
+    }
+    // 3. Build Extensions
+    let extPart = "";
+    if (comp.extensions && Object.keys(comp.extensions).length > 0) {
+      const extStrings = Object.entries(comp.extensions).map(
+        ([k, v]) => `${k}${v}`
+      );
+      extPart = `;${extStrings.join(".")}`;
+    }
+    return `tps://${spacePart}@${timePart}${extPart}`;
+  }
+  /**
+   * CONVERTER: Creates a TPS Time Object string from a JavaScript Date.
+   * Supports plugin drivers for non-Gregorian calendars.
+   * @param date - The JS Date object (defaults to Now).
+   * @param calendar - The target calendar driver (default 'greg').
+   * @returns Canonical string (e.g., "T:greg.m3.c1.y26...").
+   */
+  static fromDate(date = new Date(), calendar = "greg") {
+    // Check for registered driver first
+    const driver = this.drivers.get(calendar);
+    if (driver) {
+      return driver.fromDate(date);
+    }
+    // Built-in handlers
+    if (calendar === "unix") {
+      const s = (date.getTime() / 1000).toFixed(3);
+      return `T:unix.s${s}`;
+    }
+    if (calendar === "greg") {
+      const fullYear = date.getUTCFullYear();
+      const m = Math.floor(fullYear / 1000) + 1;
+      const c = Math.floor((fullYear % 1000) / 100) + 1;
+      const y = fullYear % 100;
+      const M = date.getUTCMonth() + 1;
+      const d = date.getUTCDate();
+      const h = date.getUTCHours();
+      const n = date.getUTCMinutes();
+      const s = date.getUTCSeconds();
+      return `T:greg.m${m}.c${c}.y${y}.M${this.pad(M)}.d${this.pad(
+        d
+      )}.h${this.pad(h)}.n${this.pad(n)}.s${this.pad(s)}`;
+    }
+    throw new Error(
+      `Calendar driver '${calendar}' not implemented. Register a driver.`
+    );
+  }
+  /**
+   * CONVERTER: Converts a TPS string to a Date in a target calendar format.
+   * Uses plugin drivers for cross-calendar conversion.
+   * @param tpsString - The source TPS string (any calendar).
+   * @param targetCalendar - The target calendar code (e.g., 'hij').
+   * @returns A TPS string in the target calendar, or null if invalid.
+   */
+  static to(targetCalendar, tpsString) {
+    // 1. Parse to components and convert to Gregorian Date
+    const gregDate = this.toDate(tpsString);
+    if (!gregDate) return null;
+    // 2. Convert Gregorian to target calendar using driver
+    return this.fromDate(gregDate, targetCalendar);
+  }
+  /**
+   * CONVERTER: Reconstructs a JavaScript Date object from a TPS string.
+   * Supports plugin drivers for non-Gregorian calendars.
+   * @param tpsString - The TPS string.
+   * @returns JS Date object or `null` if invalid.
+   */
+  static toDate(tpsString) {
+    const p = this.parse(tpsString);
+    if (!p) return null;
+    // Check for registered driver first
+    const driver = this.drivers.get(p.calendar);
+    if (driver) {
+      return driver.toGregorian(p);
+    }
+    // Built-in handlers
+    if (p.calendar === "unix" && p.unixSeconds !== undefined) {
+      return new Date(p.unixSeconds * 1000);
+    }
+    if (p.calendar === "greg") {
+      const m = p.millennium || 0;
+      const c = p.century || 1;
+      const y = p.year || 0;
+      const fullYear = (m - 1) * 1000 + (c - 1) * 100 + y;
+      return new Date(
+        Date.UTC(
+          fullYear,
+          (p.month || 1) - 1,
+          p.day || 1,
+          p.hour || 0,
+          p.minute || 0,
+          Math.floor(p.second || 0)
+        )
+      );
+    }
+    return null;
+  }
+  // --- DRIVER CONVENIENCE METHODS ---
+  /**
+   * Parse a calendar-specific date string into TPS components.
+   * Requires the driver to implement the optional `parseDate` method.
+   *
+   * @param calendar - The calendar code (e.g., 'hij')
+   * @param dateString - Date string in calendar-native format (e.g., '1447-07-21')
+   * @param format - Optional format string (driver-specific)
+   * @returns TPS components or null if parsing fails
+   *
+   * @example
+   * ```ts
+   * const components = TPS.parseCalendarDate('hij', '1447-07-21');
+   * // { calendar: 'hij', year: 1447, month: 7, day: 21 }
+   *
+   * const uri = TPS.toURI({ ...components, latitude: 31.95, longitude: 35.91 });
+   * // "tps://31.95,35.91@T:hij.y1447.M07.d21"
+   * ```
+   */
+  static parseCalendarDate(calendar, dateString, format) {
+    const driver = this.drivers.get(calendar);
+    if (!driver) {
+      throw new Error(
+        `Calendar driver '${calendar}' not found. Register a driver first.`
+      );
+    }
+    if (!driver.parseDate) {
+      throw new Error(
+        `Driver '${calendar}' does not implement parseDate(). Use fromGregorian() instead.`
+      );
+    }
+    return driver.parseDate(dateString, format);
+  }
+  /**
+   * Convert a calendar-specific date string directly to a TPS URI.
+   * This is a convenience method that combines parseDate + toURI.
+   *
+   * @param calendar - The calendar code (e.g., 'hij')
+   * @param dateString - Date string in calendar-native format
+   * @param location - Optional location (lat/lon/alt or privacy flag)
+   * @returns Full TPS URI string
+   *
+   * @example
+   * ```ts
+   * // With coordinates
+   * TPS.fromCalendarDate('hij', '1447-07-21', { latitude: 31.95, longitude: 35.91 });
+   * // "tps://31.95,35.91@T:hij.y1447.M07.d21"
+   *
+   * // With privacy flag
+   * TPS.fromCalendarDate('hij', '1447-07-21', { isHiddenLocation: true });
+   * // "tps://hidden@T:hij.y1447.M07.d21"
+   *
+   * // Without location
+   * TPS.fromCalendarDate('hij', '1447-07-21');
+   * // "tps://unknown@T:hij.y1447.M07.d21"
+   * ```
+   */
+  static fromCalendarDate(calendar, dateString, location) {
+    const components = this.parseCalendarDate(calendar, dateString);
+    if (!components) {
+      throw new Error(`Failed to parse date string: ${dateString}`);
+    }
+    // Merge with location
+    const fullComponents = {
+      calendar,
+      ...components,
+      ...location,
+    };
+    return this.toURI(fullComponents);
+  }
+  /**
+   * Format TPS components to a calendar-specific date string.
+   * Requires the driver to implement the optional `format` method.
+   *
+   * @param calendar - The calendar code
+   * @param components - TPS components to format
+   * @param format - Optional format string (driver-specific)
+   * @returns Formatted date string in calendar-native format
+   *
+   * @example
+   * ```ts
+   * const tps = TPS.parse('tps://unknown@T:hij.y1447.M07.d21');
+   * const formatted = TPS.formatCalendarDate('hij', tps);
+   * // "1447-07-21"
+   * ```
+   */
+  static formatCalendarDate(calendar, components, format) {
+    const driver = this.drivers.get(calendar);
+    if (!driver) {
+      throw new Error(`Calendar driver '${calendar}' not found.`);
+    }
+    if (!driver.format) {
+      throw new Error(`Driver '${calendar}' does not implement format().`);
+    }
+    return driver.format(components, format);
+  }
+  // --- INTERNAL HELPERS ---
+  static _mapGroupsToComponents(g) {
+    const components = {};
+    components.calendar = g.calendar;
+    // Time Mapping
+    if (components.calendar === "unix" && g.unix) {
+      components.unixSeconds = parseFloat(g.unix.substring(1));
+    } else {
+      if (g.millennium) components.millennium = parseInt(g.millennium, 10);
+      if (g.century) components.century = parseInt(g.century, 10);
+      if (g.year) components.year = parseInt(g.year, 10);
+      if (g.month) components.month = parseInt(g.month, 10);
+      if (g.day) components.day = parseInt(g.day, 10);
+      if (g.hour) components.hour = parseInt(g.hour, 10);
+      if (g.minute) components.minute = parseInt(g.minute, 10);
+      if (g.second) components.second = parseFloat(g.second);
+    }
+    // Space Mapping
+    if (g.space) {
+      if (g.space === "unknown") components.isUnknownLocation = true;
+      else if (g.space === "redacted") components.isRedactedLocation = true;
+      else if (g.space === "hidden") components.isHiddenLocation = true;
+      else {
+        if (g.lat) components.latitude = parseFloat(g.lat);
+        if (g.lon) components.longitude = parseFloat(g.lon);
+        if (g.alt) components.altitude = parseFloat(g.alt);
+      }
+    }
+    // Extensions Mapping
+    if (g.extensions) {
+      const extObj = {};
+      const parts = g.extensions.split(".");
+      parts.forEach((p) => {
+        const key = p.charAt(0);
+        const val = p.substring(1);
+        if (key && val) extObj[key] = val;
+      });
+      components.extensions = extObj;
+    }
+    return components;
+  }
+  static pad(n) {
+    const s = n.toString();
+    return s.length < 2 ? "0" + s : s;
+  }
+}
+// --- PLUGIN REGISTRY ---
+TPS.drivers = new Map();
+// --- REGEX ---
+TPS.REGEX_URI = new RegExp(
+  "^tps://(?<space>unknown|redacted|hidden|(?<lat>-?\\d+(?:\\.\\d+)?),(?<lon>-?\\d+(?:\\.\\d+)?)(?:,(?<alt>-?\\d+(?:\\.\\d+)?)m?)?)@T:(?<calendar>[a-z]{3,4})\\.(?:(?<unix>s\\d+(?:\\.\\d+)?)|m(?<millennium>-?\\d+)(?:\\.c(?<century>\\d+)(?:\\.y(?<year>\\d+)(?:\\.M(?<month>\\d{1,2})(?:\\.d(?<day>\\d{1,2})(?:\\.h(?<hour>\\d{1,2})(?:\\.n(?<minute>\\d{1,2})(?:\\.s(?<second>\\d{1,2}(?:\\.\\d+)?))?)?)?)?)?)?)?)?(?:;(?<extensions>[a-z0-9\\.\\-\\_]+))?$"
+);
+TPS.REGEX_TIME = new RegExp(
+  "^T:(?<calendar>[a-z]{3,4})\\.(?:(?<unix>s\\d+(?:\\.\\d+)?)|m(?<millennium>-?\\d+)(?:\\.c(?<century>\\d+)(?:\\.y(?<year>\\d+)(?:\\.M(?<month>\\d{1,2})(?:\\.d(?<day>\\d{1,2})(?:\\.h(?<hour>\\d{1,2})(?:\\.n(?<minute>\\d{1,2})(?:\\.s(?<second>\\d{1,2}(?:\\.\\d+)?))?)?)?)?)?)?)?)?$"
+);
+/**
+ * TPS-UID v1 — Temporal Positioning System Identifier (Binary Reversible)
+ *
+ * A time-first, reversible identifier that binds an event to a TPS coordinate.
+ * Unlike UUIDs, TPS-UID identifies events in spacetime and allows exact
+ * reconstruction of the original TPS string.
+ *
+ * Binary Schema (all integers big-endian):
+ * ```
+ * MAGIC   4 bytes   "TPU7"
+ * VER     1 byte    0x01
+ * FLAGS   1 byte    bit0 = compression flag
+ * TIME    6 bytes   epoch_ms (48-bit unsigned)
+ * NONCE   4 bytes   32-bit random
+ * LEN     varint    length of TPS payload
+ * TPS     bytes     UTF-8 TPS string (raw or zlib-compressed)
+ * ```
+ *
+ * @example
+ * ```ts
+ * const tps = 'tps://31.95,35.91@T:greg.m3.c1.y26.M01.d09';
+ *
+ * // Encode to binary
+ * const bytes = TPSUID7RB.encodeBinary(tps);
+ *
+ * // Encode to base64url string
+ * const id = TPSUID7RB.encodeBinaryB64(tps);
+ * // → "tpsuid7rb_AFRQV..."
+ *
+ * // Decode back to original TPS
+ * const decoded = TPSUID7RB.decodeBinaryB64(id);
+ * console.log(decoded.tps); // exact original TPS
+ * ```
+ */
+export class TPSUID7RB {
+  // ---------------------------
+  // Public API
+  // ---------------------------
+  /**
+   * Encode TPS string to binary bytes (Uint8Array).
+   * This is the canonical form for hashing, signing, and storage.
+   *
+   * @param tps - The TPS string to encode
+   * @param opts - Encoding options (compress, epochMs override)
+   * @returns Binary TPS-UID as Uint8Array
+   */
+  static encodeBinary(tps, opts) {
+    const compress = opts?.compress ?? false;
+    const epochMs = opts?.epochMs ?? this.epochMsFromTPSString(tps);
+    if (!Number.isInteger(epochMs) || epochMs < 0) {
+      throw new Error("epochMs must be a non-negative integer");
+    }
+    if (epochMs > 0xffffffffffff) {
+      throw new Error("epochMs exceeds 48-bit range");
+    }
+    const flags = compress ? 0x01 : 0x00;
+    // Generate 32-bit nonce
+    const nonceBuf = this.randomBytes(4);
+    const nonce =
+      ((nonceBuf[0] << 24) >>> 0) +
+      ((nonceBuf[1] << 16) >>> 0) +
+      ((nonceBuf[2] << 8) >>> 0) +
+      nonceBuf[3];
+    // Encode TPS to UTF-8
+    const tpsUtf8 = new TextEncoder().encode(tps);
+    // Optionally compress
+    const payload = compress ? this.deflateRaw(tpsUtf8) : tpsUtf8;
+    // Encode length as varint
+    const lenVar = this.uvarintEncode(payload.length);
+    // Construct binary structure
+    const out = new Uint8Array(
+      4 + 1 + 1 + 6 + 4 + lenVar.length + payload.length
+    );
+    let offset = 0;
+    // MAGIC
+    out.set(this.MAGIC, offset);
+    offset += 4;
+    // VER
+    out[offset++] = this.VER;
+    // FLAGS
+    out[offset++] = flags;
+    // TIME (48-bit big-endian)
+    const timeBytes = this.writeU48(epochMs);
+    out.set(timeBytes, offset);
+    offset += 6;
+    // NONCE (32-bit big-endian)
+    out.set(nonceBuf, offset);
+    offset += 4;
+    // LEN (varint)
+    out.set(lenVar, offset);
+    offset += lenVar.length;
+    // TPS payload
+    out.set(payload, offset);
+    return out;
+  }
+  /**
+   * Decode binary bytes back to original TPS string.
+   *
+   * @param bytes - Binary TPS-UID
+   * @returns Decoded result with original TPS string
+   */
+  static decodeBinary(bytes) {
+    // Header min size: 4+1+1+6+4 + 1 (at least 1 byte varint) = 17
+    if (bytes.length < 17) {
+      throw new Error("TPSUID7RB: too short");
+    }
+    // MAGIC
+    if (
+      bytes[0] !== 0x54 ||
+      bytes[1] !== 0x50 ||
+      bytes[2] !== 0x55 ||
+      bytes[3] !== 0x37
+    ) {
+      throw new Error("TPSUID7RB: bad magic");
+    }
+    // VERSION
+    const ver = bytes[4];
+    if (ver !== this.VER) {
+      throw new Error(`TPSUID7RB: unsupported version ${ver}`);
+    }
+    // FLAGS
+    const flags = bytes[5];
+    const compressed = (flags & 0x01) === 0x01;
+    // TIME (48-bit big-endian)
+    const epochMs = this.readU48(bytes, 6);
+    // NONCE (32-bit big-endian)
+    const nonce =
+      ((bytes[12] << 24) >>> 0) +
+      ((bytes[13] << 16) >>> 0) +
+      ((bytes[14] << 8) >>> 0) +
+      bytes[15];
+    // LEN (varint at offset 16)
+    let offset = 16;
+    const { value: tpsLen, bytesRead } = this.uvarintDecode(bytes, offset);
+    offset += bytesRead;
+    if (offset + tpsLen > bytes.length) {
+      throw new Error("TPSUID7RB: length overflow");
+    }
+    // TPS payload
+    const payload = bytes.slice(offset, offset + tpsLen);
+    const tpsUtf8 = compressed ? this.inflateRaw(payload) : payload;
+    const tps = new TextDecoder().decode(tpsUtf8);
+    return { version: "tpsuid7rb", epochMs, compressed, nonce, tps };
+  }
+  /**
+   * Encode TPS to base64url string with prefix.
+   * This is the transport/storage form.
+   *
+   * @param tps - The TPS string to encode
+   * @param opts - Encoding options
+   * @returns Base64url encoded TPS-UID with prefix
+   */
+  static encodeBinaryB64(tps, opts) {
+    const bytes = this.encodeBinary(tps, opts);
+    return `${this.PREFIX}${this.base64UrlEncode(bytes)}`;
+  }
+  /**
+   * Decode base64url string back to original TPS string.
+   *
+   * @param id - Base64url encoded TPS-UID with prefix
+   * @returns Decoded result with original TPS string
+   */
+  static decodeBinaryB64(id) {
+    const s = id.trim();
+    if (!s.startsWith(this.PREFIX)) {
+      throw new Error("TPSUID7RB: missing prefix");
+    }
+    const b64 = s.slice(this.PREFIX.length);
+    const bytes = this.base64UrlDecode(b64);
+    return this.decodeBinary(bytes);
+  }
+  /**
+   * Validate base64url encoded TPS-UID format.
+   * Note: This validates shape only; binary decode is authoritative.
+   *
+   * @param id - String to validate
+   * @returns true if format is valid
+   */
+  static validateBinaryB64(id) {
+    return this.REGEX.test(id.trim());
+  }
+  /**
+   * Generate a TPS-UID from the current time and optional location.
+   *
+   * @param opts - Generation options
+   * @returns Base64url encoded TPS-UID
+   */
+  static generate(opts) {
+    const now = new Date();
+    const tps = this.generateTPSString(now, opts);
+    return this.encodeBinaryB64(tps, {
+      compress: opts?.compress,
+      epochMs: now.getTime(),
+    });
+  }
+  // ---------------------------
+  // TPS String Helpers
+  // ---------------------------
+  /**
+   * Generate a TPS string from a Date and optional location.
+   */
+  static generateTPSString(date, opts) {
+    const fullYear = date.getUTCFullYear();
+    const m = Math.floor(fullYear / 1000) + 1;
+    const c = Math.floor((fullYear % 1000) / 100) + 1;
+    const y = fullYear % 100;
+    const M = date.getUTCMonth() + 1;
+    const d = date.getUTCDate();
+    const h = date.getUTCHours();
+    const n = date.getUTCMinutes();
+    const s = date.getUTCSeconds();
+    const pad = (num) => num.toString().padStart(2, "0");
+    const timePart = `T:greg.m${m}.c${c}.y${y}.M${pad(M)}.d${pad(d)}.h${pad(
+      h
+    )}.n${pad(n)}.s${pad(s)}`;
+    let spacePart = "unknown";
+    if (opts?.latitude !== undefined && opts?.longitude !== undefined) {
+      spacePart = `${opts.latitude},${opts.longitude}`;
+      if (opts.altitude !== undefined) {
+        spacePart += `,${opts.altitude}m`;
+      }
+    }
+    return `tps://${spacePart}@${timePart}`;
+  }
+  /**
+   * Parse epoch milliseconds from a TPS string.
+   * Supports both URI format (tps://...) and time-only format (T:greg...)
+   */
+  static epochMsFromTPSString(tps) {
+    let time;
+    if (tps.includes("@")) {
+      // URI format: tps://...@T:greg...
+      const at = tps.indexOf("@");
+      time = tps.slice(at + 1).trim();
+    } else if (tps.startsWith("T:")) {
+      // Time-only format
+      time = tps;
+    } else {
+      throw new Error("TPS: unrecognized format");
+    }
+    if (!time.startsWith("T:greg.")) {
+      throw new Error("TPS: only T:greg.* parsing is supported");
+    }
+    // Extract m (millennium), c (century), y (year)
+    const mMatch = time.match(/\.m(-?\d+)/);
+    const cMatch = time.match(/\.c(\d+)/);
+    const yMatch = time.match(/\.y(\d{1,4})/);
+    const MMatch = time.match(/\.M(\d{1,2})/);
+    const dMatch = time.match(/\.d(\d{1,2})/);
+    const hMatch = time.match(/\.h(\d{1,2})/);
+    const nMatch = time.match(/\.n(\d{1,2})/);
+    const sMatch = time.match(/\.s(\d{1,2})/);
+    // Calculate full year from millennium, century, year
+    let fullYear;
+    if (mMatch && cMatch && yMatch) {
+      const millennium = parseInt(mMatch[1], 10);
+      const century = parseInt(cMatch[1], 10);
+      const year = parseInt(yMatch[1], 10);
+      fullYear = (millennium - 1) * 1000 + (century - 1) * 100 + year;
+    } else if (yMatch) {
+      // Fallback: interpret y as 2-digit year
+      let year = parseInt(yMatch[1], 10);
+      if (year < 100) {
+        year = year <= 69 ? 2000 + year : 1900 + year;
+      }
+      fullYear = year;
+    } else {
+      throw new Error("TPS: missing year component");
+    }
+    const month = MMatch ? parseInt(MMatch[1], 10) : 1;
+    const day = dMatch ? parseInt(dMatch[1], 10) : 1;
+    const hour = hMatch ? parseInt(hMatch[1], 10) : 0;
+    const minute = nMatch ? parseInt(nMatch[1], 10) : 0;
+    const second = sMatch ? parseInt(sMatch[1], 10) : 0;
+    const epoch = Date.UTC(fullYear, month - 1, day, hour, minute, second);
+    if (!Number.isFinite(epoch)) {
+      throw new Error("TPS: failed to compute epochMs");
+    }
+    return epoch;
+  }
+  // ---------------------------
+  // Binary Helpers
+  // ---------------------------
+  /** Write 48-bit unsigned integer (big-endian) */
+  static writeU48(epochMs) {
+    const b = new Uint8Array(6);
+    // Use BigInt for proper 48-bit handling
+    const v = BigInt(epochMs);
+    b[0] = Number((v >> 40n) & 0xffn);
+    b[1] = Number((v >> 32n) & 0xffn);
+    b[2] = Number((v >> 24n) & 0xffn);
+    b[3] = Number((v >> 16n) & 0xffn);
+    b[4] = Number((v >> 8n) & 0xffn);
+    b[5] = Number(v & 0xffn);
+    return b;
+  }
+  /** Read 48-bit unsigned integer (big-endian) */
+  static readU48(bytes, offset) {
+    const v =
+      (BigInt(bytes[offset]) << 40n) +
+      (BigInt(bytes[offset + 1]) << 32n) +
+      (BigInt(bytes[offset + 2]) << 24n) +
+      (BigInt(bytes[offset + 3]) << 16n) +
+      (BigInt(bytes[offset + 4]) << 8n) +
+      BigInt(bytes[offset + 5]);
+    const n = Number(v);
+    if (!Number.isSafeInteger(n)) {
+      throw new Error("TPSUID7RB: u48 not safe integer");
+    }
+    return n;
+  }
+  /** Encode unsigned integer as LEB128 varint */
+  static uvarintEncode(n) {
+    if (!Number.isInteger(n) || n < 0) {
+      throw new Error("uvarint must be non-negative int");
+    }
+    const out = [];
+    let x = n >>> 0;
+    while (x >= 0x80) {
+      out.push((x & 0x7f) | 0x80);
+      x >>>= 7;
+    }
+    out.push(x);
+    return new Uint8Array(out);
+  }
+  /** Decode LEB128 varint */
+  static uvarintDecode(bytes, offset) {
+    let x = 0;
+    let s = 0;
+    let i = 0;
+    while (true) {
+      if (offset + i >= bytes.length) {
+        throw new Error("uvarint overflow");
+      }
+      const b = bytes[offset + i];
+      if (b < 0x80) {
+        if (i > 9 || (i === 9 && b > 1)) {
+          throw new Error("uvarint too large");
+        }
+        x |= b << s;
+        return { value: x >>> 0, bytesRead: i + 1 };
+      }
+      x |= (b & 0x7f) << s;
+      s += 7;
+      i++;
+      if (i > 10) {
+        throw new Error("uvarint too long");
+      }
+    }
+  }
+  // ---------------------------
+  // Base64url Helpers
+  // ---------------------------
+  /** Encode bytes to base64url (no padding) */
+  static base64UrlEncode(bytes) {
+    // Node.js environment
+    if (typeof Buffer !== "undefined") {
+      return Buffer.from(bytes)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/g, "");
+    }
+    // Browser environment
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary)
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/g, "");
+  }
+  /** Decode base64url to bytes */
+  static base64UrlDecode(b64url) {
+    // Add padding
+    const padLen = (4 - (b64url.length % 4)) % 4;
+    const b64 = (b64url + "=".repeat(padLen))
+      .replace(/-/g, "+")
+      .replace(/_/g, "/");
+    // Node.js environment
+    if (typeof Buffer !== "undefined") {
+      return new Uint8Array(Buffer.from(b64, "base64"));
+    }
+    // Browser environment
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+  // ---------------------------
+  // Compression Helpers
+  // ---------------------------
+  /** Compress using zlib deflate raw */
+  static deflateRaw(data) {
+    // Node.js environment
+    if (typeof require !== "undefined") {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const zlib = require("zlib");
+        return new Uint8Array(zlib.deflateRawSync(Buffer.from(data)));
+      } catch {
+        throw new Error("TPSUID7RB: compression not available");
+      }
+    }
+    // Browser: would need pako or similar library
+    throw new Error("TPSUID7RB: compression not available in browser");
+  }
+  /** Decompress using zlib inflate raw */
+  static inflateRaw(data) {
+    // Node.js environment
+    if (typeof require !== "undefined") {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const zlib = require("zlib");
+        return new Uint8Array(zlib.inflateRawSync(Buffer.from(data)));
+      } catch {
+        throw new Error("TPSUID7RB: decompression failed");
+      }
+    }
+    // Browser: would need pako or similar library
+    throw new Error("TPSUID7RB: decompression not available in browser");
+  }
+  // ---------------------------
+  // Cryptographic Sealing (Ed25519)
+  // ---------------------------
+  /**
+   * Seal (sign) a TPS string to create a cryptographically verifiable TPS-UID.
+   * This appends an Ed25519 signature to the binary form.
+   *
+   * @param tps - The TPS string to seal
+   * @param privateKey - Ed25519 private key (hex or buffer)
+   * @param opts - Encoding options
+   * @returns Sealed binary TPS-UID
+   */
+  static seal(tps, privateKey, opts) {
+    // 1. Create standard binary (unsealed first)
+    // We force the SEAL flag (bit 1) to be 0 initially for the "content to sign"
+    // But wait, we want the signature to cover the header too.
+    // Strategy: Construct the full binary with SEAL flag OFF, sign it, then set SEAL flag ON and append sig.
+    // Actually, the standard way is:
+    // Content = MAGIC + VER + FLAGS(with seal bit set) + TIME + NONCE + LEN + PAYLOAD
+    // Signature = Sign(Content)
+    // Final = Content + SEAL_TYPE + SIGNATURE
+    const compress = opts?.compress ?? false;
+    const epochMs = opts?.epochMs ?? this.epochMsFromTPSString(tps);
+    // Validate epoch
+    if (!Number.isInteger(epochMs) || epochMs < 0 || epochMs > 0xffffffffffff) {
+      throw new Error("epochMs must be a valid 48-bit non-negative integer");
+    }
+    // Flags: Bit 0 = compress, Bit 1 = sealed
+    const flags = (compress ? 0x01 : 0x00) | 0x02; // Set SEAL bit
+    // Generate Nonce
+    const nonceBuf = this.randomBytes(4);
+    // Encode Payload
+    const tpsUtf8 = new TextEncoder().encode(tps);
+    const payload = compress ? this.deflateRaw(tpsUtf8) : tpsUtf8;
+    const lenVar = this.uvarintEncode(payload.length);
+    // Construct Content (Header + Payload)
+    const contentLen = 4 + 1 + 1 + 6 + 4 + lenVar.length + payload.length;
+    const content = new Uint8Array(contentLen);
+    let offset = 0;
+    content.set(this.MAGIC, offset);
+    offset += 4;
+    content[offset++] = this.VER;
+    content[offset++] = flags;
+    content.set(this.writeU48(epochMs), offset);
+    offset += 6;
+    content.set(nonceBuf, offset);
+    offset += 4;
+    content.set(lenVar, offset);
+    offset += lenVar.length;
+    content.set(payload, offset);
+    // Sign the content
+    const signature = this.signEd25519(content, privateKey);
+    const sealType = 0x01; // Ed25519
+    // Final Output: Content + SealType (1) + Signature (64)
+    const final = new Uint8Array(contentLen + 1 + signature.length);
+    final.set(content, 0);
+    final.set([sealType], contentLen);
+    final.set(signature, contentLen + 1);
+    return final;
+  }
+  /**
+   * Verify a sealed TPS-UID and decode it.
+   * Throws if signature is invalid or not sealed.
+   *
+   * @param sealedBytes - The binary sealed TPS-UID
+   * @param publicKey - Ed25519 public key (hex or buffer) to verify against
+   * @returns Decoded result
+   */
+  static verifyAndDecode(sealedBytes, publicKey) {
+    if (sealedBytes.length < 18) throw new Error("TPSUID7RB: too short");
+    // Check Magic
+    if (
+      sealedBytes[0] !== 0x54 ||
+      sealedBytes[1] !== 0x50 ||
+      sealedBytes[2] !== 0x55 ||
+      sealedBytes[3] !== 0x37
+    ) {
+      throw new Error("TPSUID7RB: bad magic");
+    }
+    // Check Flags for Sealed Bit (bit 1)
+    const flags = sealedBytes[5];
+    if ((flags & 0x02) === 0) {
+      throw new Error("TPSUID7RB: not a sealed UID");
+    }
+    // 1. Parse the structure to find where content ends
+    // We need to parse LEN and Payload to find the split point
+    let offset = 16; // Start of LEN
+    // Decode LEN
+    const { value: tpsLen, bytesRead } = this.uvarintDecode(
+      sealedBytes,
+      offset
+    );
+    offset += bytesRead;
+    const payloadEnd = offset + tpsLen;
+    if (payloadEnd > sealedBytes.length) {
+      throw new Error("TPSUID7RB: length overflow (truncated)");
+    }
+    // The Content to verify matches exactly [0 ... payloadEnd]
+    const content = sealedBytes.slice(0, payloadEnd);
+    // After content: SealType (1 byte) + Signature
+    if (sealedBytes.length <= payloadEnd + 1) {
+      throw new Error("TPSUID7RB: missing signature data");
+    }
+    const sealType = sealedBytes[payloadEnd];
+    if (sealType !== 0x01) {
+      throw new Error(
+        `TPSUID7RB: unsupported seal type 0x${sealType.toString(16)}`
+      );
+    }
+    const signature = sealedBytes.slice(payloadEnd + 1);
+    if (signature.length !== 64) {
+      throw new Error(
+        `TPSUID7RB: invalid Ed25519 signature length ${signature.length}`
+      );
+    }
+    // Verify
+    const isValid = this.verifyEd25519(content, signature, publicKey);
+    if (!isValid) {
+      throw new Error("TPSUID7RB: signature verification failed");
+    }
+    // Decode (reuse standard logic, but ignoring the extra bytes at end is fine?)
+    // Actually standard logic doesn't expect trailing bytes unless we tell it to.
+    // But since we verified, we can just slice the content and decode that as a strict binary
+    // EXCEPT standard decodeBinary checks strict length.
+    // So we manually decode the components here to be safe and efficient.
+    return this.decodeBinary(content); // Reuse strict decoder on the content part
+  }
+  // --- Crypto Implementation (Ed25519) ---
+  static signEd25519(data, privateKey) {
+    if (typeof require !== "undefined") {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const crypto = require("crypto");
+        // Node's crypto.sign uses PEM or KeyObject, but for raw Ed25519 keys we might need 'crypto.sign(null, data, key)'
+        // or ensure key is properly formatted.
+        // For simplicity in Node 20+, crypto.sign(null, data, privateKey) works if key is KeyObject.
+        // If raw bytes: establish KeyObject.
+        let keyObj;
+        if (Buffer.isBuffer(privateKey) || privateKey instanceof Uint8Array) {
+          // Assuming raw 64-byte private key (or 32-byte seed properly expanded by crypto)
+          // Node < 16 is tricky with raw keys.
+          // Let's assume standard Ed25519 standard implementation pattern logic:
+          keyObj = crypto.createPrivateKey({
+            key: Buffer.from(privateKey),
+            format: "der", // or 'pem' - strict.
+            type: "pkcs8",
+          });
+          // Actually, simpler: construct key object from raw bytes if possible?
+          // Node's crypto is strict. Let's try the simplest:
+          // If hex string provided, convert to buffer.
+        }
+        // Simpler fallback: If user passed a PEM string, great.
+        // If they passed raw bytes, we might need 'ed25519' key type.
+        // For this implementation, let's target Node's high-level sign/verify
+        // and assume the user provides a VALID key object or compatible format (PEM/DER).
+        // Handling RAW Ed25519 keys in Node requires specific 'crypto.createPrivateKey' with 'raw' format (Node 11.6+).
+        const key =
+          typeof privateKey === "string" && !privateKey.includes("PRIVATE KEY")
+            ? crypto.createPrivateKey({
+                key: Buffer.from(privateKey, "hex"),
+                format: "pem",
+                type: "pkcs8",
+              }) // Fallback guess
+            : privateKey;
+        // Note: Raw Ed25519 key support in Node.js 'crypto' acts via 'generateKeyPair' or KeyObject.
+        // Direct raw signing is via crypto.sign(null, data, key).
+        return new Uint8Array(crypto.sign(null, data, key));
+      } catch (e) {
+        // If standard crypto fails (e.g. key format issue), throw
+        throw new Error("TPSUID7RB: signing failed (check key format)");
+      }
+    }
+    throw new Error("TPSUID7RB: signing not available in browser");
+  }
+  static verifyEd25519(data, signature, publicKey) {
+    if (typeof require !== "undefined") {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const crypto = require("crypto");
+        return crypto.verify(null, data, publicKey, signature);
+      } catch {
+        return false;
+      }
+    }
+    throw new Error("TPSUID7RB: verification not available in browser");
+  }
+  // ---------------------------
+  // Random Bytes
+  // ---------------------------
+  /** Generate cryptographically secure random bytes */
+  static randomBytes(length) {
+    // Node.js environment
+    if (typeof require !== "undefined") {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const crypto = require("crypto");
+        return new Uint8Array(crypto.randomBytes(length));
+      } catch {
+        // Fallback to crypto.getRandomValues
+      }
+    }
+    // Browser or fallback
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+      const bytes = new Uint8Array(length);
+      crypto.getRandomValues(bytes);
+      return bytes;
+    }
+    throw new Error("TPSUID7RB: no crypto available");
+  }
+}
+/** Magic bytes: "TPU7" */
+TPSUID7RB.MAGIC = new Uint8Array([0x54, 0x50, 0x55, 0x37]);
+/** Version 1 */
+TPSUID7RB.VER = 0x01;
+/** String prefix for base64url encoded form */
+TPSUID7RB.PREFIX = "tpsuid7rb_";
+/** Regex for validating base64url encoded form */
+TPSUID7RB.REGEX = /^tpsuid7rb_[A-Za-z0-9_-]+$/;