@nextera.one/tps-standard 0.4.3 → 0.5.1

package/dist/src/index.js

@@ -0,0 +1,681 @@
+/**
+ * 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;
+  }
+  // --- 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");
+  }
+  // ---------------------------
+  // 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_-]+$/;