@nextera.one/tps-standard 0.5.33 → 0.6.0

package/src/types.ts

@@ -0,0 +1,131 @@
+/**
+ * TPS: Temporal Positioning System
+ * Shared types and interfaces.
+ */
+
+/**
+ * Calendar codes are plain strings to allow arbitrary user-defined
+ * calendars. The library still exports constants for the built-in values.
+ */
+export const DefaultCalendars = {
+  TPS: "tps",
+  GREG: "greg",
+  HIJ: "hij",
+  PER: "per",
+  JUL: "jul",
+  HOLO: "holo",
+  UNIX: "unix",
+  CHIN: "chin",
+} as const;
+
+/**
+ * Specifies the direction of the time-component hierarchy when serializing or
+ * deserializing a TPS string. The default is 'descending'.
+ */
+export enum TimeOrder {
+  DESC = "desc",
+  ASC = "asc",
+}
+
+export interface TPSComponents {
+  // --- TEMPORAL ---
+  calendar: string;
+  millennium: number;
+  century: number;
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+  millisecond: number;
+
+  // --- OPTIONAL UNIX BACKUP ---
+  unixSeconds?: number;
+
+  // --- SPATIAL: GPS Coordinates ---
+  latitude?: number;
+  longitude?: number;
+  altitude?: number;
+
+  // --- SPATIAL: Geospatial Cells ---
+  s2Cell?: string;
+  h3Cell?: string;
+  plusCode?: string;
+  what3words?: string;
+
+  // --- SPATIAL: Place layer (P:cc=JO,ci=AMM,...) ---
+  /** ISO 3166-1 alpha-2 country code, e.g. "JO"  →  P:cc=JO */
+  placeCountryCode?: string;
+  /** Full country name, e.g. "Jordan"             →  P:cn=Jordan */
+  placeCountryName?: string;
+  /** City IATA/ISO code, e.g. "AMM"               →  P:ci=AMM */
+  placeCityCode?: string;
+  /** Full city name, e.g. "Amman"                 →  P:ct=Amman */
+  placeCityName?: string;
+
+  // --- SPATIAL: Network / Digital Location ---
+  /** IPv4 address (net:ip4:x or NIP4:x) */
+  ipv4?: string;
+  /** IPv6 address (net:ip6:x or NIP6:x) */
+  ipv6?: string;
+  /** Logical node / host name (node:api-1 or NODE:api-1) */
+  nodeName?: string;
+
+  // --- SPATIAL: Structural Anchors ---
+  building?: string;
+  floor?: string;
+  room?: string;
+  door?: string;
+  zone?: string;
+
+  /** Raw pre-@ space anchor (generic/legacy/planet/adm) */
+  spaceAnchor?: string;
+
+  // --- SPATIAL: Privacy Markers ---
+  isUnknownLocation?: boolean;
+  isRedactedLocation?: boolean;
+  isHiddenLocation?: boolean;
+
+  // --- PROVENANCE ---
+  actor?: string;
+  signature?: string;
+
+  // --- EXTENSIONS (;KEY:val or ;key=val after T: tokens, before #) ---
+  extensions?: Record<string, string>;
+
+  // --- CONTEXT (#C:key=val;key=val in fragment) ---
+  /** Structured context key-value pairs from the #C: fragment block */
+  context?: Record<string, string>;
+
+  order?: TimeOrder;
+}
+
+/**
+ * Interface for Calendar Driver plugins.
+ */
+export interface CalendarDriver {
+  readonly code: string;
+  readonly name?: string;
+  getComponentsFromDate(date: Date): Partial<TPSComponents>;
+  getDateFromComponents(components: Partial<TPSComponents>): Date;
+  getFromDate(date: Date): string;
+  parseDate(input: string, format?: string): Partial<TPSComponents>;
+  format(components: Partial<TPSComponents>, format?: string): string;
+  validate(input: string | Partial<TPSComponents>): boolean;
+  getMetadata(): CalendarMetadata;
+}
+
+/**
+ * Metadata about a calendar system.
+ */
+export interface CalendarMetadata {
+  name: string;
+  monthNames?: string[];
+  monthNamesShort?: string[];
+  dayNames?: string[];
+  dayNamesShort?: string[];
+  isLunar?: boolean;
+  monthsPerYear?: number;
+  epochYear?: number;
+}

package/src/uid.ts

@@ -0,0 +1,308 @@
+/**
+ * TPS-UID v1 — Temporal Positioning System Identifier (Binary Reversible)
+ */
+
+import { TPS } from "./index";
+import { DefaultCalendars, TimeOrder } from "./types";
+import { Env } from "./utils/env";
+
+/**
+ * Decoded result from TPSUID7RB binary format.
+ */
+export type TPSUID7RBDecodeResult = {
+  version: "tpsuid7rb";
+  epochMs: number;
+  compressed: boolean;
+  nonce: number;
+  tps: string;
+};
+
+/**
+ * Encoding options for TPSUID7RB.
+ */
+export type TPSUID7RBEncodeOptions = {
+  compress?: boolean;
+  epochMs?: number;
+};
+
+export class TPSUID7RB {
+  private static readonly MAGIC = new Uint8Array([0x54, 0x50, 0x55, 0x37]);
+  private static readonly VER = 0x01;
+  private static readonly PREFIX = "tpsuid7rb_";
+  public static readonly REGEX = /^tpsuid7rb_[A-Za-z0-9_-]+$/;
+
+  static encodeBinary(
+    tps: string,
+    opts: TPSUID7RBEncodeOptions = {},
+  ): Uint8Array {
+    const compress = opts.compress ?? false;
+    const epochMs = opts.epochMs ?? this.epochMsFromTPSString(tps);
+
+    if (!Number.isInteger(epochMs) || epochMs < 0 || epochMs > 0xffffffffffff) {
+      throw new Error(
+        "TPSUID7RB: Invalid epochMs (must be 48-bit non-negative integer)",
+      );
+    }
+
+    const flags = compress ? 0x01 : 0x00;
+    const nonceBuf = Env.randomBytes(4);
+
+    const tpsUtf8 = new TextEncoder().encode(tps);
+    const payload = compress ? Env.deflate(tpsUtf8) : tpsUtf8;
+    const lenVar = this.uvarintEncode(payload.length);
+
+    const out = new Uint8Array(
+      4 + 1 + 1 + 6 + 4 + lenVar.length + payload.length,
+    );
+    let offset = 0;
+
+    out.set(this.MAGIC, offset);
+    offset += 4;
+    out[offset++] = this.VER;
+    out[offset++] = flags;
+    out.set(this.writeU48(epochMs), offset);
+    offset += 6;
+    out.set(nonceBuf, offset);
+    offset += 4;
+    out.set(lenVar, offset);
+    offset += lenVar.length;
+    out.set(payload, offset);
+
+    return out;
+  }
+
+  static decodeBinary(bytes: Uint8Array): TPSUID7RBDecodeResult {
+    if (bytes.length < 17) throw new Error("TPSUID7RB: too short");
+    if (
+      bytes[0] !== 0x54 ||
+      bytes[1] !== 0x50 ||
+      bytes[2] !== 0x55 ||
+      bytes[3] !== 0x37
+    ) {
+      throw new Error("TPSUID7RB: bad magic");
+    }
+
+    const ver = bytes[4];
+    if (ver !== this.VER)
+      throw new Error(`TPSUID7RB: unsupported version ${ver}`);
+
+    const flags = bytes[5];
+    const compressed = (flags & 0x01) === 0x01;
+    const epochMs = this.readU48(bytes, 6);
+    const nonce =
+      ((bytes[12] << 24) >>> 0) +
+      ((bytes[13] << 16) >>> 0) +
+      ((bytes[14] << 8) >>> 0) +
+      bytes[15];
+
+    let offset = 16;
+    const { value: tpsLen, bytesRead } = this.uvarintDecode(bytes, offset);
+    offset += bytesRead;
+
+    if (offset + tpsLen > bytes.length)
+      throw new Error("TPSUID7RB: length overflow");
+
+    const payload = bytes.slice(offset, offset + tpsLen);
+    const tpsUtf8 = compressed ? Env.inflate(payload) : payload;
+    const tps = new TextDecoder().decode(tpsUtf8);
+
+    return { version: "tpsuid7rb", epochMs, compressed, nonce, tps };
+  }
+
+  static encodeBinaryB64(tps: string, opts?: TPSUID7RBEncodeOptions): string {
+    const bytes = this.encodeBinary(tps, opts ?? {});
+    return `${this.PREFIX}${this.base64UrlEncode(bytes)}`;
+  }
+
+  static decodeBinaryB64(id: string): TPSUID7RBDecodeResult {
+    const s = id.trim();
+    if (!s.startsWith(this.PREFIX))
+      throw new Error("TPSUID7RB: missing prefix");
+    return this.decodeBinary(this.base64UrlDecode(s.slice(this.PREFIX.length)));
+  }
+
+  static validateBinaryB64(id: string): boolean {
+    return this.REGEX.test(id.trim());
+  }
+
+  static generate(opts?: {
+    latitude?: number;
+    longitude?: number;
+    altitude?: number;
+    compress?: boolean;
+    order?: TimeOrder;
+  }): string {
+    const now = new Date();
+    const time = TPS.fromDate(now, DefaultCalendars.TPS, {
+      order: opts?.order,
+    });
+    let space = "unknown";
+
+    if (opts?.latitude !== undefined && opts?.longitude !== undefined) {
+      space = `${opts.latitude},${opts.longitude}`;
+      if (opts.altitude !== undefined) space += `,${opts.altitude}m`;
+    }
+
+    const tps = `tps://${space}@${time}`;
+    return this.encodeBinaryB64(tps, {
+      compress: opts?.compress,
+      epochMs: now.getTime(),
+    });
+  }
+
+  static seal(
+    tps: string,
+    privateKey: any,
+    opts?: TPSUID7RBEncodeOptions,
+  ): Uint8Array {
+    const compress = opts?.compress ?? false;
+    const epochMs = opts?.epochMs ?? this.epochMsFromTPSString(tps);
+
+    if (!Number.isInteger(epochMs) || epochMs < 0 || epochMs > 0xffffffffffff) {
+      throw new Error("TPSUID7RB: Invalid epochMs");
+    }
+
+    const flags = (compress ? 0x01 : 0x00) | 0x02; // Set SEAL bit
+    const nonceBuf = Env.randomBytes(4);
+
+    const tpsUtf8 = new TextEncoder().encode(tps);
+    const payload = compress ? Env.deflate(tpsUtf8) : tpsUtf8;
+    const lenVar = this.uvarintEncode(payload.length);
+
+    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);
+
+    const signature = Env.signEd25519(content, privateKey);
+    const final = new Uint8Array(contentLen + 1 + signature.length);
+    final.set(content, 0);
+    final.set([0x01], contentLen); // Ed25519 type
+    final.set(signature, contentLen + 1);
+
+    return final;
+  }
+
+  static verifyAndDecode(
+    sealedBytes: Uint8Array,
+    publicKey: any,
+  ): TPSUID7RBDecodeResult {
+    if (sealedBytes.length < 18) throw new Error("TPSUID7RB: too short");
+    if (sealedBytes[5] & 0x02 ? false : true)
+      throw new Error("TPSUID7RB: not sealed");
+
+    let offset = 16;
+    const { value: tpsLen, bytesRead } = this.uvarintDecode(
+      sealedBytes,
+      offset,
+    );
+    const payloadEnd = offset + bytesRead + tpsLen;
+
+    const content = sealedBytes.slice(0, payloadEnd);
+    const signature = sealedBytes.slice(payloadEnd + 1);
+
+    if (!Env.verifyEd25519(content, signature, publicKey)) {
+      throw new Error("TPSUID7RB: verification failed");
+    }
+
+    return this.decodeBinary(content);
+  }
+
+  public static epochMsFromTPSString(tps: string): number {
+    const date = TPS.toDate(tps);
+    if (date) return date.getTime();
+    const stripped = tps.replace(/;[^?#]*/, "").replace(/[?#].*$/, "");
+    const retryDate = TPS.toDate(stripped);
+    if (!retryDate) throw new Error("TPS: unable to parse date for epoch");
+    return retryDate.getTime();
+  }
+
+  private static writeU48(epochMs: number): Uint8Array {
+    const b = new Uint8Array(6);
+    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;
+  }
+
+  private static readU48(bytes: Uint8Array, offset: number): number {
+    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]);
+    return Number(v);
+  }
+
+  private static uvarintEncode(n: number): Uint8Array {
+    const out: number[] = [];
+    let x = n >>> 0;
+    while (x >= 0x80) {
+      out.push((x & 0x7f) | 0x80);
+      x >>>= 7;
+    }
+    out.push(x);
+    return new Uint8Array(out);
+  }
+
+  private static uvarintDecode(
+    bytes: Uint8Array,
+    offset: number,
+  ): { value: number; bytesRead: number } {
+    let x = 0,
+      s = 0,
+      i = 0;
+    while (true) {
+      const b = bytes[offset + i];
+      if (b < 0x80) {
+        x |= b << s;
+        return { value: x >>> 0, bytesRead: i + 1 };
+      }
+      x |= (b & 0x7f) << s;
+      s += 7;
+      i++;
+    }
+  }
+
+  private static base64UrlEncode(bytes: Uint8Array): string {
+    if (typeof Buffer !== "undefined") {
+      return Buffer.from(bytes)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/g, "");
+    }
+    return btoa(String.fromCharCode(...bytes))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/g, "");
+  }
+
+  private static base64UrlDecode(b64url: string): Uint8Array {
+    const padLen = (4 - (b64url.length % 4)) % 4;
+    const b64 = (b64url + "=".repeat(padLen))
+      .replace(/-/g, "+")
+      .replace(/_/g, "/");
+    if (typeof Buffer !== "undefined")
+      return new Uint8Array(Buffer.from(b64, "base64"));
+    const binary = atob(b64);
+    return new Uint8Array(Array.from(binary).map((c) => c.charCodeAt(0)));
+  }
+}

package/src/utils/calendar.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared Calendar Math Utilities
+ */
+
+/**
+ * Gregorian -> Julian Day Number
+ */
+export function gregorianToJdn(gy: number, gm: number, gd: number): number {
+  const a = Math.floor((14 - gm) / 12);
+  const y = gy + 4800 - a;
+  const m = gm + 12 * a - 3;
+  return (
+    gd +
+    Math.floor((153 * m + 2) / 5) +
+    365 * y +
+    Math.floor(y / 4) -
+    Math.floor(y / 100) +
+    Math.floor(y / 400) -
+    32045
+  );
+}
+
+/**
+ * Julian Day Number -> Gregorian
+ */
+export function jdnToGregorian(jdn: number): {
+  gy: number;
+  gm: number;
+  gd: number;
+} {
+  const a = jdn + 32044;
+  const b = Math.floor((4 * a + 3) / 146097);
+  const c = a - Math.floor((146097 * b) / 4);
+  const d = Math.floor((4 * c + 3) / 1461);
+  const e = c - Math.floor((1461 * d) / 4);
+  const m = Math.floor((5 * e + 2) / 153);
+  const gd = e - Math.floor((153 * m + 2) / 5) + 1;
+  const gm = m + 3 - 12 * Math.floor(m / 10);
+  const gy = 100 * b + d - 4800 + Math.floor(m / 10);
+  return { gy, gm, gd };
+}
+
+/**
+ * Julian -> Julian Day Number
+ */
+export function julianToJdn(jy: number, jm: number, jd: number): number {
+  const a = Math.floor((14 - jm) / 12);
+  const y = jy + 4800 - a;
+  const m = jm + 12 * a - 3;
+  return (
+    jd + Math.floor((153 * m + 2) / 5) + 365 * y + Math.floor(y / 4) - 32083
+  );
+}
+
+/**
+ * Julian Day Number -> Julian
+ */
+export function jdnToJulian(jdn: number): {
+  jy: number;
+  jm: number;
+  jd: number;
+} {
+  const c = jdn + 32082;
+  const d = Math.floor((4 * c + 3) / 1461);
+  const e = c - Math.floor((1461 * d) / 4);
+  const m = Math.floor((5 * e + 2) / 153);
+  const jd = e - Math.floor((153 * m + 2) / 5) + 1;
+  const jm = m + 3 - 12 * Math.floor(m / 10);
+  const jy = d - 4800 + Math.floor(m / 10);
+  return { jy, jm, jd };
+}
+
+/**
+ * Persian -> Julian Day Number
+ */
+export function persianToJdn(jy: number, jm: number, jd: number): number {
+  const EPOCH = 1948320;
+  const epbase = jy - (jy >= 0 ? 474 : 473);
+  const epyear = 474 + (epbase % 2820);
+  return (
+    jd +
+    (jm <= 7 ? (jm - 1) * 31 : (jm - 1) * 30 + 6) +
+    Math.floor((epyear * 682 - 110) / 2816) +
+    (epyear - 1) * 365 +
+    Math.floor(epbase / 2820) * 1029983 +
+    EPOCH -
+    1
+  );
+}
+
+/**
+ * Julian Day Number -> Persian
+ */
+export function jdnToPersian(jdn: number): {
+  jy: number;
+  jm: number;
+  jd: number;
+} {
+  const depoch = jdn - persianToJdn(475, 1, 1);
+  const cycle = Math.floor(depoch / 1029983);
+  const cyear = depoch % 1029983;
+  let ycycle: number;
+  if (cyear === 1029982) {
+    ycycle = 2820;
+  } else {
+    const aux1 = Math.floor(cyear / 366);
+    const aux2 = cyear % 366;
+    ycycle =
+      Math.floor((2134 * aux1 + 2816 * aux2 + 2815) / 1028522) + aux1 + 1;
+  }
+  const jy = ycycle + 2820 * cycle + 474;
+  const yday = jdn - persianToJdn(jy, 1, 1) + 1;
+  const jm = yday <= 186 ? Math.ceil(yday / 31) : Math.ceil((yday - 6) / 30);
+  const jd = jdn - persianToJdn(jy, jm, 1) + 1;
+  return { jy: jy <= 0 ? jy - 1 : jy, jm, jd };
+}
+
+/**
+ * Convert Gregorian to Hijri (Tabular Islamic Calendar).
+ */
+export function gregorianToHijri(
+  gy: number,
+  gm: number,
+  gd: number,
+): { hy: number; hm: number; hd: number } {
+  const jdn = gregorianToJdn(gy, gm, gd);
+  const L = jdn - 1948440 + 10632;
+  const N = Math.floor((L - 1) / 10631);
+  const L2 = L - 10631 * N + 354;
+  const J =
+    Math.floor((10985 - L2) / 5316) * Math.floor((50 * L2) / 17719) +
+    Math.floor(L2 / 5670) * Math.floor((43 * L2) / 15238);
+  const L3 =
+    L2 -
+    Math.floor((30 - J) / 15) * Math.floor((17719 * J) / 50) -
+    Math.floor(J / 16) * Math.floor((15238 * J) / 43) +
+    29;
+  const hm = Math.floor((24 * L3) / 709);
+  const hd = L3 - Math.floor((709 * hm) / 24);
+  const hy = 30 * N + J - 30;
+  return { hy, hm, hd };
+}
+
+/**
+ * Convert Hijri to Gregorian.
+ */
+export function hijriToGregorian(
+  hy: number,
+  hm: number,
+  hd: number,
+): { gy: number; gm: number; gd: number } {
+  const jdn =
+    Math.floor((11 * hy + 3) / 30) +
+    354 * hy +
+    30 * hm -
+    Math.floor((hm - 1) / 2) +
+    hd +
+    1948440 -
+    385;
+  return jdnToGregorian(jdn);
+}

package/src/utils/env.ts

@@ -0,0 +1,88 @@
+/**
+ * Environment & Compatibility Layer
+ * Abstracts Node.js vs Browser differences.
+ */
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const isNode = typeof require !== "undefined";
+
+/**
+ * Node.js crypto module (conditional)
+ */
+const crypto = isNode ? require("crypto") : null;
+
+/**
+ * Node.js zlib module (conditional)
+ */
+const zlib = isNode ? require("zlib") : null;
+
+export const Env = {
+  isNode,
+
+  randomBytes(length: number): Uint8Array {
+    if (isNode && crypto) {
+      return new Uint8Array(crypto.randomBytes(length));
+    }
+    if (typeof window !== "undefined" && window.crypto) {
+      return window.crypto.getRandomValues(new Uint8Array(length));
+    }
+    throw new Error("TPS: randomBytes not available in this environment");
+  },
+
+  deflate(data: Uint8Array): Uint8Array {
+    if (isNode && zlib) {
+      return new Uint8Array(zlib.deflateRawSync(data));
+    }
+    throw new Error("TPS: deflate not available in this environment");
+  },
+
+  inflate(data: Uint8Array): Uint8Array {
+    if (isNode && zlib) {
+      return new Uint8Array(zlib.inflateRawSync(data));
+    }
+    throw new Error("TPS: inflate not available in this environment");
+  },
+
+  signEd25519(data: Uint8Array, privateKey: any): Uint8Array {
+    if (isNode && crypto) {
+      let key: any;
+      if (typeof privateKey === "string") {
+        if (privateKey.includes("PRIVATE KEY")) {
+          key = privateKey;
+        } else {
+          key = crypto.createPrivateKey({
+            key: Buffer.from(privateKey, "hex"),
+            format: "der",
+            type: "pkcs8",
+          });
+        }
+      } else if (
+        typeof privateKey === "object" &&
+        privateKey !== null &&
+        "asymmetricKeyType" in privateKey
+      ) {
+        key = privateKey;
+      } else {
+        key = crypto.createPrivateKey({
+          key: Buffer.from(privateKey),
+          format: "der",
+          type: "pkcs8",
+        });
+      }
+      return new Uint8Array(crypto.sign(null, data, key));
+    }
+    throw new Error("TPS: signEd25519 not available in this environment");
+  },
+
+  verifyEd25519(
+    data: Uint8Array,
+    signature: Uint8Array,
+    publicKey: any,
+  ): boolean {
+    if (isNode && crypto) {
+      return crypto.verify(null, data, publicKey, signature);
+    }
+    throw new Error("TPS: verifyEd25519 not available in this environment");
+  },
+};