@nextera.one/tps-standard 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextera.one/tps-standard",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "The Universal Protocol for Space-Time Coordinates. A standard URI scheme (tps://) combining WGS84 spatial data with hierarchical, multi-calendar temporal coordinates. Includes TPS-UID: time-first, reversible event identifiers.",
   "keywords": [
     "tps",
@@ -24,7 +24,7 @@
     "type": "git",
     "url": "git+https://github.com/nextera-one/tps.git"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "author": "Mohammed Ayesh",
   "types": "dist/index.d.ts",
   "main": "dist/index.js",

package/src/index.ts

@@ -2,9 +2,15 @@
  * TPS: Temporal Positioning System
  * The Universal Protocol for Space-Time Coordinates.
  * @packageDocumentation
- * @version 0.4.2
- * @license MIT
+ * @version 0.5.0
+ * @license Apache-2.0
  * @copyright 2026 TPS Standards Working Group
+ *
+ * v0.5.0 Changes:
+ * - Added Actor anchor (A:) for provenance tracking
+ * - Added Signature (!) for cryptographic verification
+ * - Added structural anchors (bldg, floor, room, zone)
+ * - Added geospatial cell systems (S2, H3, Plus Code, what3words)
  */
 
 export type CalendarCode = 'greg' | 'hij' | 'jul' | 'holo' | 'unix';
@@ -22,11 +28,32 @@ export interface TPSComponents {
   second?: number;
   unixSeconds?: number;
 
-  // --- SPATIAL ---
+  // --- SPATIAL: GPS Coordinates ---
   latitude?: number;
   longitude?: number;
   altitude?: number;
 
+  // --- SPATIAL: Geospatial Cells ---
+  /** Google S2 cell ID (hierarchical, prefix-searchable) */
+  s2Cell?: string;
+  /** Uber H3 cell ID (hexagonal grid) */
+  h3Cell?: string;
+  /** Open Location Code / Plus Code */
+  plusCode?: string;
+  /** what3words address (e.g. "filled.count.soap") */
+  what3words?: string;
+
+  // --- SPATIAL: Structural Anchors ---
+  /** Physical building identifier */
+  building?: string;
+  /** Vertical division (level) */
+  floor?: string;
+  /** Enclosed space identifier */
+  room?: string;
+  /** Logical area within building */
+  zone?: string;
+
+  // --- SPATIAL: Privacy Markers ---
   /** Technical missing data (e.g. server log without GPS) */
   isUnknownLocation?: boolean;
   /** Removed for legal/security reasons (e.g. GDPR) */
@@ -34,6 +61,12 @@ export interface TPSComponents {
   /** Masked by user preference (e.g. "Don't show my location") */
   isHiddenLocation?: boolean;
 
+  // --- PROVENANCE ---
+  /** Actor anchor - identifies observer/witness (e.g. "did:web:sensor.example.com", "node:gateway-01") */
+  actor?: string;
+  /** Verification hash appended to time (e.g. "sha256:8f3e2a...") */
+  signature?: string;
+
   // --- CONTEXT ---
   extensions?: Record<string, string>;
 }
@@ -229,12 +262,40 @@ export class TPS {
   }
 
   // --- REGEX ---
+  // Updated for v0.5.0: supports L: anchors, A: actor, ! signature, structural & geospatial anchors
+  // Note: Complex regex - carefully balanced parentheses
   private static readonly 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://' +
+      // Location part (L: prefix optional for backward compat)
+      '(?:L:)?(?<space>' +
+      '~|-|unknown|redacted|hidden|' + // Privacy markers
+      's2=(?<s2>[a-fA-F0-9]+)|' + // S2 cell
+      'h3=(?<h3>[a-fA-F0-9]+)|' + // H3 cell
+      'plus=(?<plus>[A-Z0-9+]+)|' + // Plus Code
+      'w3w=(?<w3w>[a-z]+\\.[a-z]+\\.[a-z]+)|' + // what3words
+      'bldg=(?<bldg>[\\w-]+)(?:\\.floor=(?<floor>[\\w-]+))?(?:\\.room=(?<room>[\\w-]+))?(?:\\.zone=(?<zone>[\\w-]+))?|' + // Structural
+      '(?<lat>-?\\d+(?:\\.\\d+)?),(?<lon>-?\\d+(?:\\.\\d+)?)(?:,(?<alt>-?\\d+(?:\\.\\d+)?)m?)?' + // GPS
+      ')' +
+      // Optional Actor anchor
+      '(?:/A:(?<actor>[^/@]+))?' +
+      // Time part separator
+      '[/@]T:(?<calendar>[a-z]{3,4})\\.' +
+      // Time components
+      '(?:(?<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+)?))?)?)?)?)?)?)?)' +
+      // Optional signature
+      '(?:!(?<signature>[^;?#]+))?' +
+      // Optional extensions
+      '(?:;(?<extensions>[a-z0-9.\\-_=]+))?' +
+      // Optional query params
+      '(?:\\?(?<params>[^#]+))?' +
+      // Optional context
+      '(?:#(?<context>.+))?$',
   );
 
   private static readonly 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+)?))?)?)?)?)?)?)?)?$',
+    '^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+)?))?)?)?)?)?)?)?)' +
+      '(?:!(?<signature>[^;?#]+))?$',
   );
 
   // --- CORE METHODS ---
@@ -261,23 +322,42 @@ export class TPS {
    * @returns Full URI string (e.g. "tps://...").
    */
   static toURI(comp: TPSComponents): string {
-    // 1. Build Space Part
-    let spacePart = 'unknown'; // Default safe fallback
+    // 1. Build Space Part (L: anchor)
+    let spacePart = 'L:-'; // Default: unknown
 
     if (comp.isHiddenLocation) {
-      spacePart = 'hidden';
+      spacePart = 'L:~';
     } else if (comp.isRedactedLocation) {
-      spacePart = 'redacted';
+      spacePart = 'L:redacted';
     } else if (comp.isUnknownLocation) {
-      spacePart = 'unknown';
+      spacePart = 'L:-';
+    } else if (comp.s2Cell) {
+      spacePart = `L:s2=${comp.s2Cell}`;
+    } else if (comp.h3Cell) {
+      spacePart = `L:h3=${comp.h3Cell}`;
+    } else if (comp.plusCode) {
+      spacePart = `L:plus=${comp.plusCode}`;
+    } else if (comp.what3words) {
+      spacePart = `L:w3w=${comp.what3words}`;
+    } else if (comp.building) {
+      spacePart = `L:bldg=${comp.building}`;
+      if (comp.floor) spacePart += `.floor=${comp.floor}`;
+      if (comp.room) spacePart += `.room=${comp.room}`;
+      if (comp.zone) spacePart += `.zone=${comp.zone}`;
     } else if (comp.latitude !== undefined && comp.longitude !== undefined) {
-      spacePart = `${comp.latitude},${comp.longitude}`;
+      spacePart = `L:${comp.latitude},${comp.longitude}`;
       if (comp.altitude !== undefined) {
         spacePart += `,${comp.altitude}m`;
       }
     }
 
-    // 2. Build Time Part
+    // 2. Build Actor Part (A: anchor) - optional
+    let actorPart = '';
+    if (comp.actor) {
+      actorPart = `/A:${comp.actor}`;
+    }
+
+    // 3. Build Time Part
     let timePart = `T:${comp.calendar}`;
 
     if (comp.calendar === 'unix' && comp.unixSeconds !== undefined) {
@@ -293,16 +373,21 @@ export class TPS {
       if (comp.second !== undefined) timePart += `.s${this.pad(comp.second)}`;
     }
 
-    // 3. Build Extensions
+    // 4. Add Signature (!) - optional
+    if (comp.signature) {
+      timePart += `!${comp.signature}`;
+    }
+
+    // 5. Build Extensions
     let extPart = '';
     if (comp.extensions && Object.keys(comp.extensions).length > 0) {
       const extStrings = Object.entries(comp.extensions).map(
-        ([k, v]) => `${k}${v}`,
+        ([k, v]) => `${k}=${v}`,
       );
       extPart = `;${extStrings.join('.')}`;
     }
 
-    return `tps://${spacePart}@${timePart}${extPart}`;
+    return `tps://${spacePart}${actorPart}/${timePart}${extPart}`;
   }
 
   /**
@@ -339,7 +424,9 @@ export class TPS {
       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)}`;
+      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(
@@ -547,11 +634,44 @@ export class TPS {
       if (g.second) components.second = parseFloat(g.second);
     }
 
+    // Signature Mapping
+    if (g.signature) {
+      components.signature = g.signature;
+    }
+
+    // Actor Mapping
+    if (g.actor) {
+      components.actor = g.actor;
+    }
+
     // 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;
+      // Privacy markers
+      if (g.space === 'unknown' || g.space === '-') {
+        components.isUnknownLocation = true;
+      } else if (g.space === 'redacted') {
+        components.isRedactedLocation = true;
+      } else if (g.space === 'hidden' || g.space === '~') {
+        components.isHiddenLocation = true;
+      }
+      // Geospatial cells
+      else if (g.s2) {
+        components.s2Cell = g.s2;
+      } else if (g.h3) {
+        components.h3Cell = g.h3;
+      } else if (g.plus) {
+        components.plusCode = g.plus;
+      } else if (g.w3w) {
+        components.what3words = g.w3w;
+      }
+      // Structural anchors
+      else if (g.bldg) {
+        components.building = g.bldg;
+        if (g.floor) components.floor = g.floor;
+        if (g.room) components.room = g.room;
+        if (g.zone) components.zone = g.zone;
+      }
+      // GPS coordinates
       else {
         if (g.lat) components.latitude = parseFloat(g.lat);
         if (g.lon) components.longitude = parseFloat(g.lon);
@@ -564,9 +684,17 @@ export class TPS {
       const extObj: any = {};
       const parts = g.extensions.split('.');
       parts.forEach((p: string) => {
-        const key = p.charAt(0);
-        const val = p.substring(1);
-        if (key && val) extObj[key] = val;
+        const eqIdx = p.indexOf('=');
+        if (eqIdx > 0) {
+          const key = p.substring(0, eqIdx);
+          const val = p.substring(eqIdx + 1);
+          if (key && val) extObj[key] = val;
+        } else {
+          // Legacy format: first char is key
+          const key = p.charAt(0);
+          const val = p.substring(1);
+          if (key && val) extObj[key] = val;
+        }
       });
       components.extensions = extObj;
     }
@@ -871,7 +999,9 @@ export class TPSUID7RB {
 
     const pad = (num: number) => 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)}`;
+    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) {
@@ -1160,12 +1290,16 @@ export class TPSUID7RB {
     const content = new Uint8Array(contentLen);
     let offset = 0;
 
-    content.set(this.MAGIC, offset); offset += 4;
+    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(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
@@ -1215,7 +1349,10 @@ export class TPSUID7RB {
     // 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);
+    const { value: tpsLen, bytesRead } = this.uvarintDecode(
+      sealedBytes,
+      offset,
+    );
     offset += bytesRead;
     const payloadEnd = offset + tpsLen;
 
@@ -1233,12 +1370,16 @@ export class TPSUID7RB {
 
     const sealType = sealedBytes[payloadEnd];
     if (sealType !== 0x01) {
-      throw new Error(`TPSUID7RB: unsupported seal type 0x${sealType.toString(16)}`);
+      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}`);
+      throw new Error(
+        `TPSUID7RB: invalid Ed25519 signature length ${signature.length}`,
+      );
     }
 
     // Verify
@@ -1270,20 +1411,20 @@ export class TPSUID7RB {
         // 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.
+          // 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.
@@ -1292,14 +1433,18 @@ export class TPSUID7RB {
         // 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;
+        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)');
@@ -1350,4 +1495,3 @@ export class TPSUID7RB {
     throw new Error('TPSUID7RB: no crypto available');
   }
 }
-