@gtcx/protocol-geotag

Cryptographic location verification for commodity provenance.

Overview

GeoTag creates and verifies cryptographically-signed location claims for physical assets. It proves that a specific identity was at a specific location at a specific time, with anti-spoofing measures that validate authenticity. Location proofs can be bound to registered sites and anchored into Merkle trees for tamper-evident audit trails.

Key Concepts

• GeoTag Capture -- A signed location proof containing GPS coordinates, accuracy, altitude, timestamp, and anti-spoofing evidence.
• Anti-Spoofing -- Multi-layered detection including mock location APIs, cell tower correlation, movement analysis, and sensor fusion.
• Site Binding -- Captures can be bound to registered extraction sites via geofence checks.
• Proof Chain -- Sequential captures are hash-chained for integrity verification.
• OriginMark -- A certificate linking a commodity asset to its verified extraction location.
• Offline Queue -- Location proofs can be created offline and synced within a 24-hour window.
• Environmental Fingerprint -- Sensor-based fingerprints bind environmental context to a location claim.

Usage

import {
  createGeoTag,
  verifyGeoTag,
  detectSpoof,
  isWithinGeofence,
  SiteRegistry,
  createOriginMark,
} from '@gtcx/protocol-geotag';

// Create a cryptographic location proof
const tag = createGeoTag({ latitude: 6.68, longitude: -1.62, accuracy: 5 });

// Verify the proof
const valid = verifyGeoTag(tag);

// Check if location is within a licensed site
const inSite = isWithinGeofence(tag.location, siteBoundary);

API

Location Operations

• createGeoTag -- Create a new cryptographic location proof
• verifyGeoTag -- Verify a GeoTag's signature and integrity
• isGeoTagValid -- Check if a GeoTag is still within its validity window
• computeProofHash -- Compute the hash of a location proof

Distance and Geography

• calculateDistance -- Haversine distance between two coordinates
• isWithinBoundingBox / createBoundingBox -- Bounding box operations
• isWithinGeofence -- Check if coordinates fall within a geofence polygon
• classifyGeofenceZone -- Classify core/buffer/outside using a buffer radius

Anti-Spoofing and Fusion

• detectSpoof -- Run multi-source spoof detection on a capture
• combineSources -- Fuse GPS, cell tower, and sensor data
• createEnvironmentalFingerprint -- Generate a sensor-based fingerprint
• verifyEnvironmentalFingerprint -- Verify a fingerprint within tolerance

Site and Chain

• SiteRegistry -- Registry of licensed extraction sites with boundaries
• computeChainHash -- Build a hash chain across sequential proofs
• createOriginMark -- Issue an OriginMark certificate for a commodity

Offline

• createGeoTagOfflineQueue / enqueueGeoTagEvent / drainGeoTagQueue -- Offline queue for disconnected operation
• purgeExpiredGeoTagEvents -- Clean up stale offline events

Specification

See SPEC.md for the full protocol specification.

Persistence

• Postgres adapters: postgres-site-registry.ts, postgres-location-proof-store.ts
• Offline queue: offline-queue.ts — syncs location proofs when connectivity returns

Testing

pnpm vitest run protocols/geotag/

**Coverage summary**: 11 test files, ~270 tests

License

BSL 1.1 -- converts to Apache 2.0 on January 1, 2030.