@location-proofs/plugin-geoclue

GeoClue2 D-Bus location proof plugin for Astral Protocol.

Queries the GeoClue2 daemon over D-Bus for location. GeoClue2 aggregates WiFi, cell tower, and IP signals on Linux.

Requirements

• Node.js 18+
• Linux with geoclue-2.0 package installed
• D-Bus system bus access
• gdbus available on PATH

Install

npm install @location-proofs/plugin-geoclue @decentralized-geo/astral-sdk ethers

Usage

import { AstralSDK } from '@decentralized-geo/astral-sdk';
import { GeocluePlugin } from '@location-proofs/plugin-geoclue';

const sdk = new AstralSDK({ chainId: 11155111 });
sdk.plugins.register(new GeocluePlugin({ privateKey: '0x...' }));

const signals = await sdk.stamps.collect({ plugins: ['geoclue'] });

Standalone (without SDK)

import { collectGeoclue, createStampFromSignals, signStamp, verifyGeoclueStamp } from '@location-proofs/plugin-geoclue';
import { ethers } from 'ethers';

const signals = await collectGeoclue(8000);
const unsigned = createStampFromSignals(signals, '0.1.0', 60);
const wallet = new ethers.Wallet('0x...');
const stamp = await signStamp(unsigned, wallet);
const result = await verifyGeoclueStamp(stamp);

Options

Option	Default	Description
privateKey	random	Hex-encoded ECDSA private key for signing
timeoutMs	8000	Per-step D-Bus timeout in milliseconds
durationSeconds	60	Temporal footprint duration

Signals collected

Field	Description
source	Always 'geoclue2'
accuracyMeters	Reported accuracy from GeoClue2
altitudeMeters	Altitude if available
platform	Always 'linux'

Verification

The verify function checks:

1. Structure — lpVersion 0.2, plugin name, required fields
2. Signatures — ECDSA recovery matches declared signer, using canonical (sorted-key) serialization
3. Signals — coordinate bounds, accuracy > 0, platform is linux