@dotrino/geo 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seyacat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @dotrino/geo
+
+Índice de **descubrimiento georreferenciado** del ecosistema Dotrino:
+`geo.dotrino.com`. Una identidad publica un **pin firmado** (lat/lng + payload)
+con TTL corto; cualquiera consulta los pins dentro de un **radio** (PostGIS hace
+la query espacial). Pensado para casos tipo "Uber", delivery, "cerca de mí",
+marketplace local, eventos.
+
+Es el **cuarto pilar** del ecosistema, complementario a los tres existentes:
+
+| Pilar | Paquete | Rol |
+|-------|---------|-----|
+| Identidad | `dotrino-identity` | clave del vault, firma |
+| Transporte | `dotrino-proxy-client` | mensajería, canales, WebRTC |
+| Almacenamiento | `dotrino-store` | datos del usuario en el navegador |
+| **Descubrimiento geo** | **`dotrino-geo`** | **encontrar identidades cercanas** |
+
+## El pin es un anuncio efímero, no almacenamiento
+
+Una publicación geo **no es persistente**: es un **anuncio** que apunta a otro
+servicio (el messenger) donde ocurre la transacción real. El pin lleva el
+**pubkey** de la identidad, que es el handle con el que se la contacta por el
+proxy. El dato durable de la transacción vive en el messenger, no acá.
+
+Por eso el **techo de vida de un pin es 24 h**, alineado con la ventana de
+**mensajes offline del proxy**: sin que la identidad lo *hidrate* (republicar),
+un anuncio no debe sobrevivir más que un mensaje offline. Apps que necesiten
+presencia "ahora mismo" usan TTL cortos (default 10 min); anuncios tipo
+clasificado pueden llegar al cap de 24 h. El server purga los expirados.
+
+## Principio de diseño: descubrir acá, hablar por el proxy
+
+Este índice es **SOLO descubrimiento**. El flujo correcto es:
+
+1. **Publicás** un pin firmado con `publishPin()` (opt-in, TTL corto).
+2. Otra identidad te **encuentra** con `queryRadius()`.
+3. A partir de ahí, **todo el contacto en vivo va por el proxy**
+   (`@dotrino/proxy-client`): el "pedido de viaje", el handshake
+   y el **streaming de ubicación en tiempo real** se hacen con `sendByPubkey` /
+   canal / WebRTC. **No** hagas streaming de posición a alta frecuencia contra
+   este índice — eso es transporte y ya está resuelto.
+
+Cada pin (y cada query) trae el **pubkey JWK** de la identidad: ese es el handle
+con el que el proxy enruta (`sendByPubkey`). Identidad de descubrimiento e
+identidad de transporte coinciden, como manda el ecosistema.
+
+## Identidad: el vault es la única fuente
+
+El cliente **no genera ni guarda claves**. Le inyectás `signData` y
+`getPublicKeyJwk` desde `@dotrino/identity` (el vault
+`id.dotrino.com`). Mismo sobre firmado `{data, signature}` y misma
+serialización canónica que el proxy-client.
+
+## Instalación
+
+```bash
+npm i @dotrino/geo
+```
+
+## Uso (cliente)
+
+```js
+import { createGeoClient } from '@dotrino/geo'
+import identity from '@dotrino/identity' // el vault
+
+const geo = createGeoClient({
+  signData: identity.signData,
+  getPublicKeyJwk: identity.getPublicKeyJwk,
+  // baseUrl: 'https://geo.dotrino.com'  // default
+})
+
+// 1) Publicar mi pin (opt-in). Se reemplaza el anterior; no hay historial.
+await geo.publishPin({
+  lat: -2.1709, lng: -79.9224,
+  payload: { role: 'driver', seats: 4 },
+  tags: ['comida', 'vegano'],  // etiquetas de búsqueda (se normalizan)
+  ttlMs: 10 * 60 * 1000        // 10 min (el server lo capa a 1h)
+})
+
+// 2) Buscar cerca, por radio + tags (overlap: alguna de las etiquetas) y/o filter
+const { pins } = await geo.queryRadius({
+  lat: -2.1700, lng: -79.9200,
+  radiusMeters: 3000,
+  tags: ['comida', 'bici'],    // pins con ALGUNA de estas etiquetas
+  filter: { role: 'driver' }   // containment JSONB sobre payload (opcional)
+})
+// pins: [{ publickey, lat, lng, geohash, payload, tags, distanceMeters, expiresAt }, ...]
+
+// 3) Contactar al más cercano POR EL PROXY (no por este índice)
+//    proxyClient.sendByPubkey([pins[0].publickey], { type: 'ride-request', ... })
+
+// 4) Retirar mi pin antes de tiempo
+await geo.removePin()
+```
+
+### Privacidad (no rompe la filosofía Dotrino)
+
+Un índice de ubicación consultable es lo más sensible del ecosistema. Por eso:
+
+- **Un pin por identidad, con overwrite** — no se guarda historial de ubicaciones.
+- **TTL corto** por diseño (default 10 min, cap del server 1 h). Un job purga
+  expirados cada minuto.
+- **Opt-in** siempre: publicar es una acción explícita; `removePin()` lo retira.
+- **Geohash grueso** para descubrimiento (default 7 chars ≈ 76 m; bajalo con
+  `geohashPrecision` para exponer menos). La recomendación es descubrir por
+  bucket y **negociar las coords exactas P2P por el proxy** tras consentimiento.
+- **Sólo metadata de app en `payload`** — nunca datos personales del usuario.
+
+## API del servicio (HTTP/JSON)
+
+| Método | Ruta | Auth | Descripción |
+|--------|------|------|-------------|
+| `PUT` | `/pins` | sobre firmado | publica/reemplaza el pin de la identidad |
+| `DELETE` | `/pins` | sobre firmado | retira el pin (tombstone) |
+| `GET` | `/pins?lat&lng&r&limit&filter` | pública | pins dentro del radio, por distancia |
+| `GET` | `/health` | — | liveness |
+
+El servidor verifica la firma ECDSA P-256 (JWK del vault) sobre el `data`
+canónico, chequea frescura (`issuedAt` dentro de ±5 min, anti-replay) y capa el
+TTL. Ver [`server/`](./server) y [`DEPLOY.md`](./DEPLOY.md).
+
+## Estructura
+
+```
+src/            cliente npm (@dotrino/geo)
+  index.js      createGeoClient: publishPin / queryRadius / removePin
+  geohash.js    encode base32 (compartido)
+  canonical.js  serialización canónica (igual que el resto del ecosistema)
+server/         servicio geo.dotrino.com
+  server.js     HTTP/JSON nativo
+  db.js         capa PostGIS (pg)
+  schema.sql    tabla pins (geography + GiST)
+  signature.js  verificación de sobres firmados
+```
+
+## Licencia
+
+MIT

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@dotrino/geo",
+  "version": "0.2.0",
+  "description": "Cliente del índice geo de Dotrino (geo.dotrino.com): pins georreferenciados firmados con el vault, consulta por radio (PostGIS)",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "geolocation",
+    "geospatial",
+    "postgis",
+    "geohash",
+    "dotrino",
+    "discovery",
+    "p2p"
+  ],
+  "author": "seyacat",
+  "license": "MIT",
+  "dependencies": {
+    "@dotrino/identity": "^0.10.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imdotrino/dotrino-geo.git"
+  }
+}

package/src/canonical.js

@@ -0,0 +1,16 @@
+/**
+ * Serialización JSON canónica (claves ordenadas recursivamente).
+ * Necesaria para que las firmas coincidan entre cliente y servidor.
+ * Idéntica a la del proxy-client / proxy-server del ecosistema.
+ */
+export function canonicalStringify (value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value)
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalStringify).join(',') + ']'
+  }
+  const keys = Object.keys(value).sort()
+  const parts = keys.map(k => JSON.stringify(k) + ':' + canonicalStringify(value[k]))
+  return '{' + parts.join(',') + '}'
+}

package/src/geohash.js

@@ -0,0 +1,36 @@
+/**
+ * Geohash encode (base32, Gustavo Niemeyer). Se usa para descubrimiento por
+ * "bucket" grueso sin exponer coordenadas exactas: publicás un geohash de
+ * precisión baja (p.ej. 6 chars ≈ 1.2 km) y las coords finas se intercambian
+ * P2P por el proxy recién tras consentimiento mutuo.
+ *
+ * Precisión aproximada por longitud:
+ *   5 → ±2.4 km   6 → ±0.61 km   7 → ±0.076 km   8 → ±0.019 km
+ */
+const BASE32 = '0123456789bcdefghjkmnpqrstuvwxyz'
+
+export function encodeGeohash (lat, lng, precision = 7) {
+  let idx = 0
+  let bit = 0
+  let evenBit = true
+  let geohash = ''
+  let latMin = -90, latMax = 90
+  let lngMin = -180, lngMax = 180
+
+  while (geohash.length < precision) {
+    if (evenBit) {
+      const mid = (lngMin + lngMax) / 2
+      if (lng >= mid) { idx = (idx << 1) + 1; lngMin = mid } else { idx = idx << 1; lngMax = mid }
+    } else {
+      const mid = (latMin + latMax) / 2
+      if (lat >= mid) { idx = (idx << 1) + 1; latMin = mid } else { idx = idx << 1; latMax = mid }
+    }
+    evenBit = !evenBit
+    if (++bit === 5) {
+      geohash += BASE32[idx]
+      bit = 0
+      idx = 0
+    }
+  }
+  return geohash
+}

package/src/index.d.ts

@@ -0,0 +1,63 @@
+export interface GeoClientOptions {
+  /** Firma canónica → base64. Inyectada desde el vault (`id.signData`). */
+  signData: (data: object) => Promise<string>
+  /** Pubkey JWK string. Inyectada desde el vault. */
+  getPublicKeyJwk: () => Promise<string>
+  /** Default https://geo.dotrino.com */
+  baseUrl?: string
+  /** fetch inyectable para tests/SSR */
+  fetch?: typeof fetch
+}
+
+export interface PublishPinInput {
+  lat: number
+  lng: number
+  payload?: Record<string, unknown>
+  /** Etiquetas para búsqueda (máx 10, slug ≤32, se normalizan). */
+  tags?: string[]
+  ttlMs?: number
+  geohashPrecision?: number
+  now?: number
+}
+
+export interface PublishPinResult {
+  ok: true
+  expiresAt: number
+  geohash: string
+}
+
+export interface QueryRadiusInput {
+  lat: number
+  lng: number
+  radiusMeters: number
+  limit?: number
+  filter?: string | Record<string, unknown>
+  /** Buscar pins que tengan ALGUNA de estas etiquetas (overlap). */
+  tags?: string[]
+}
+
+export interface Pin {
+  publickey: string
+  lat: number
+  lng: number
+  geohash: string
+  payload: Record<string, unknown>
+  tags: string[]
+  distanceMeters: number
+  expiresAt: number
+}
+
+export interface QueryRadiusResult {
+  pins: Pin[]
+}
+
+export interface GeoClient {
+  publishPin (input: PublishPinInput): Promise<PublishPinResult>
+  queryRadius (input: QueryRadiusInput): Promise<QueryRadiusResult>
+  removePin (input?: { now?: number }): Promise<{ ok: true }>
+}
+
+export function createGeoClient (opts: GeoClientOptions): GeoClient
+export function encodeGeohash (lat: number, lng: number, precision?: number): string
+export function normalizeTags (tags: string[]): string[]
+export function canonicalStringify (value: unknown): string

package/src/index.js

@@ -0,0 +1,164 @@
+/**
+ * @dotrino/geo — cliente del índice geo `geo.dotrino.com`.
+ *
+ * Cuarto pilar del ecosistema: DESCUBRIMIENTO georreferenciado. Una identidad
+ * publica un pin firmado (lat/lng + payload) con TTL corto; cualquiera puede
+ * consultar pins dentro de un radio. PostGIS hace la query espacial.
+ *
+ * REGLAS DEL ECOSISTEMA QUE RESPETA:
+ *  - Identidad = el vault (`id.dotrino.com`). Este cliente NO genera ni guarda
+ *    claves: recibe `signData` y `getPublicKeyJwk` inyectados desde
+ *    `@dotrino/identity` (única fuente de identidad). Mismo
+ *    patrón de sobre firmado `{data, signature}` que el proxy-client.
+ *  - Transporte = el proxy. Este índice es SOLO descubrimiento. Una vez que
+ *    encontrás al peer cercano, el handshake y la ubicación en vivo van por
+ *    `@dotrino/proxy-client` (sendByPubkey / canal / WebRTC).
+ *    NO hagas streaming de posición a alta frecuencia contra este índice.
+ *  - Privacidad: un pin por identidad (upsert: overwrite, sin historial), TTL
+ *    corto, y geohash grueso para descubrimiento. Publicar es siempre opt-in.
+ */
+
+import { canonicalStringify } from './canonical.js'
+import { encodeGeohash } from './geohash.js'
+
+export { encodeGeohash } from './geohash.js'
+
+const DEFAULT_BASE = 'https://geo.dotrino.com'
+const DEFAULT_TTL_MS = 10 * 60 * 1000 // 10 min: pins efímeros por diseño
+
+/**
+ * Crea un cliente del índice geo.
+ *
+ * @param {object} opts
+ * @param {(data:object)=>Promise<string>} opts.signData   firma canónica → base64 (del vault)
+ * @param {()=>Promise<string>} opts.getPublicKeyJwk        pubkey JWK string (del vault)
+ * @param {string} [opts.baseUrl]                           default https://geo.dotrino.com
+ * @param {typeof fetch} [opts.fetch]                       fetch inyectable (tests/SSR)
+ */
+export function createGeoClient ({ signData, getPublicKeyJwk, baseUrl = DEFAULT_BASE, fetch: f } = {}) {
+  if (typeof signData !== 'function' || typeof getPublicKeyJwk !== 'function') {
+    throw new Error('dotrino-geo: signData y getPublicKeyJwk son requeridos (inyectalos desde el vault de identidad)')
+  }
+  const doFetch = f || (typeof fetch !== 'undefined' ? fetch.bind(globalThis) : null)
+  if (!doFetch) throw new Error('dotrino-geo: no hay fetch disponible; inyectalo en opts.fetch')
+  const base = baseUrl.replace(/\/+$/, '')
+
+  /**
+   * Publica (o reemplaza) el pin de esta identidad.
+   * Upsert por pubkey: SIEMPRE pisa el pin anterior — no se guarda historial.
+   *
+   * @param {object} p
+   * @param {number} p.lat
+   * @param {number} p.lng
+   * @param {object} [p.payload]          datos de app (rol, capacidad, etc). Mantenelo chico.
+   * @param {string[]} [p.tags]           etiquetas para búsqueda (máx 10, slug ≤32). Se buscan por overlap.
+   * @param {number} [p.ttlMs]            vida del pin (default 10 min)
+   * @param {number} [p.geohashPrecision] precisión del geohash público (default 7)
+   * @returns {Promise<{ok:true, expiresAt:number, geohash:string}>}
+   */
+  async function publishPin ({ lat, lng, payload = {}, tags, ttlMs = DEFAULT_TTL_MS, geohashPrecision = 7, now } = {}) {
+    assertLatLng(lat, lng)
+    const publickey = await getPublicKeyJwk()
+    const ts = now ?? Date.now()
+    const data = {
+      publickey,
+      lat: round(lat, 6),
+      lng: round(lng, 6),
+      geohash: encodeGeohash(lat, lng, geohashPrecision),
+      payload,
+      issuedAt: ts,
+      expiresAt: ts + ttlMs
+    }
+    const cleanTags = normalizeTags(tags)
+    if (cleanTags.length) data.tags = cleanTags
+    const signature = await signData(data)
+    const res = await doFetch(`${base}/pins`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ data, signature })
+    })
+    return handle(res)
+  }
+
+  /**
+   * Consulta pins dentro de un radio. NO requiere firma (lectura pública).
+   *
+   * @param {object} q
+   * @param {number} q.lat
+   * @param {number} q.lng
+   * @param {number} q.radiusMeters
+   * @param {number} [q.limit]   default 50, máx 200
+   * @param {string} [q.filter]  JSON string opcional para filtrar por payload (igualdad exacta de claves)
+   * @param {string[]} [q.tags]  buscar pins que tengan ALGUNA de estas etiquetas (overlap)
+   * @returns {Promise<{pins:Array<{publickey,lat,lng,geohash,payload,tags,distanceMeters,expiresAt}>}>}
+   */
+  async function queryRadius ({ lat, lng, radiusMeters, limit = 50, filter, tags } = {}) {
+    assertLatLng(lat, lng)
+    if (!(radiusMeters > 0)) throw new Error('dotrino-geo: radiusMeters debe ser > 0')
+    const params = new URLSearchParams({
+      lat: String(lat), lng: String(lng), r: String(radiusMeters), limit: String(limit)
+    })
+    if (filter) params.set('filter', typeof filter === 'string' ? filter : JSON.stringify(filter))
+    const cleanTags = normalizeTags(tags)
+    if (cleanTags.length) params.set('tags', cleanTags.join(','))
+    const res = await doFetch(`${base}/pins?${params.toString()}`)
+    return handle(res)
+  }
+
+  /**
+   * Retira el pin de esta identidad antes de que expire (firma un tombstone).
+   * @returns {Promise<{ok:true}>}
+   */
+  async function removePin ({ now } = {}) {
+    const publickey = await getPublicKeyJwk()
+    const data = { publickey, action: 'remove', issuedAt: now ?? Date.now() }
+    const signature = await signData(data)
+    const res = await doFetch(`${base}/pins`, {
+      method: 'DELETE',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ data, signature })
+    })
+    return handle(res)
+  }
+
+  return { publishPin, queryRadius, removePin }
+}
+
+// ----- helpers -----------------------------------------------------------
+
+function assertLatLng (lat, lng) {
+  if (typeof lat !== 'number' || lat < -90 || lat > 90) throw new Error('dotrino-geo: lat inválida')
+  if (typeof lng !== 'number' || lng < -180 || lng > 180) throw new Error('dotrino-geo: lng inválida')
+}
+
+function round (n, decimals) {
+  const f = Math.pow(10, decimals)
+  return Math.round(n * f) / f
+}
+
+// Normaliza etiquetas: lowercase, trim, slug unicode (letras/números/_/-), ≤32
+// chars, dedup, máx 10. Descarta las inválidas en silencio.
+export function normalizeTags (tags) {
+  if (!Array.isArray(tags)) return []
+  const out = []
+  for (const t of tags) {
+    if (typeof t !== 'string') continue
+    const s = t.trim().toLowerCase()
+    if (!/^[\p{L}\p{N}_-]{1,32}$/u.test(s)) continue
+    if (!out.includes(s)) out.push(s)
+    if (out.length >= 10) break
+  }
+  return out
+}
+
+async function handle (res) {
+  let body = null
+  try { body = await res.json() } catch (_) {}
+  if (!res.ok) {
+    const msg = (body && body.error) || `HTTP ${res.status}`
+    throw new Error(`dotrino-geo: ${msg}`)
+  }
+  return body
+}
+
+export { canonicalStringify }