refactor: encapsulate geohash helpers and validate schemas

Author: kanishka0411

src/constants/base.ts

@@ -56,6 +56,8 @@ export enum EventTags {
   Invoice = 'bolt11',
   // NIP-03: target event kind on an OpenTimestamps attestation
   Kind = 'k',
+  // NIP-12: geohash tag for location-based queries
+  Geohash = 'g',
 }
 
 export const ALL_RELAYS = 'ALL_RELAYS'

src/repositories/event-repository.ts

@@ -40,7 +40,7 @@ import { DBEvent, Event } from '../@types/event'
 import { EventPurgeCounts, EventRetentionOptions, IEventRepository, IQueryResult } from '../@types/repositories'
 import { toBuffer, toJSON } from '../utils/transform'
 import { createLogger } from '../factories/logger-factory'
-import { isGenericTagQuery } from '../utils/filter'
+import { isGenericTagQuery, isGeohashPrefixCriterion, stripGeohashPrefixWildcard } from '../utils/filter'
 import { SubscriptionFilter } from '../@types/subscription'
 
 const even = pipe(modulo(__, 2), equals(0))
@@ -58,11 +58,6 @@ const groupByLengthSpec = groupBy<string, 'exact' | 'even' | 'odd'>(
 
 const logger = createLogger('event-repository')
 
-const isGeohashPrefixCriterion = (filterName: string, criterion: string): boolean =>
-  filterName === '#g' && criterion.endsWith('*')
-
-const stripGeohashPrefixWildcard = (criterion: string): string => criterion.slice(0, -1)
-
 export class EventRepository implements IEventRepository {
   public constructor(
     private readonly masterDbClient: DatabaseClient,

src/schemas/base-schema.ts

@@ -1,7 +1,13 @@
 import { z } from 'zod'
 
+import { GEOHASH_FILTER_PATTERN, GEOHASH_PATTERN } from '../utils/geohash'
+
 const lowerHexRegex = /^[0-9a-f]+$/
 
+// NIP-12 geohash schemas
+export const geohashSchema = z.string().regex(GEOHASH_PATTERN, 'Invalid geohash')
+export const geohashFilterValueSchema = z.string().regex(GEOHASH_FILTER_PATTERN, 'Invalid geohash filter')
+
 export const prefixSchema = z.string().regex(lowerHexRegex).min(4).max(64)
 
 export const idSchema = z.string().regex(lowerHexRegex).length(64)

src/schemas/event-schema.ts

@@ -1,7 +1,15 @@
 import { z } from 'zod'
 
 import { EventKinds, EventTags } from '../constants/base'
-import { createdAtSchema, idSchema, kindSchema, pubkeySchema, signatureSchema, tagSchema } from './base-schema'
+import {
+  createdAtSchema,
+  geohashSchema,
+  idSchema,
+  kindSchema,
+  pubkeySchema,
+  signatureSchema,
+  tagSchema,
+} from './base-schema'
 
 /**
  * {
@@ -42,4 +50,15 @@ export const eventSchema = z
         }
       })
     }
+
+    // Validate geohash tag values (NIP-12 #g)
+    event.tags.forEach((tag, index) => {
+      if (tag[0] === EventTags.Geohash && typeof tag[1] === 'string' && !geohashSchema.safeParse(tag[1]).success) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Invalid geohash',
+          path: ['tags', index, 1],
+        })
+      }
+    })
   })

src/schemas/filter-schema.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
 
-import { createdAtSchema, kindSchema, prefixSchema } from './base-schema'
-import { isGenericTagQuery } from '../utils/filter'
+import { createdAtSchema, geohashFilterValueSchema, kindSchema, prefixSchema } from './base-schema'
+import { isGenericTagQuery, isGeohashTagQuery } from '../utils/filter'
 
 const knownFilterKeys = new Set(['ids', 'authors', 'kinds', 'since', 'until', 'limit'])
 
@@ -16,13 +16,27 @@ export const filterSchema = z
   })
   .catchall(z.array(z.string().max(1024)))
   .superRefine((data, ctx) => {
-    for (const key of Object.keys(data)) {
+    for (const [key, value] of Object.entries(data)) {
       if (!knownFilterKeys.has(key) && !isGenericTagQuery(key)) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           message: `Unknown key: ${key}`,
           path: [key],
         })
+        continue
+      }
+
+      // Validate #g filter values: NIP-12 geohash with optional single trailing '*'
+      if (isGeohashTagQuery(key) && Array.isArray(value)) {
+        value.forEach((criterion, index) => {
+          if (typeof criterion === 'string' && !geohashFilterValueSchema.safeParse(criterion).success) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message: 'Invalid geohash filter',
+              path: [key, index],
+            })
+          }
+        })
       }
     }
   })

src/utils/event.ts

@@ -8,7 +8,7 @@ import { deriveFromSecret } from './secret'
 import { EventKindsRange } from '../@types/settings'
 import { fromBuffer } from './transform'
 import { getLeadingZeroBits } from './proof-of-work'
-import { isGenericTagQuery } from './filter'
+import { isGenericTagQuery, isGeohashPrefixCriterion, stripGeohashPrefixWildcard } from './filter'
 import { SubscriptionFilter } from '../@types/subscription'
 import { WebSocketServerAdapterEvent } from '../constants/adapter'
 
@@ -46,8 +46,8 @@ export const isEventMatchingFilter =
         return false
       }
 
-      if (key === '#g' && criterion.endsWith('*')) {
-        return tag[1].startsWith(criterion.slice(0, -1))
+      if (isGeohashPrefixCriterion(key, criterion)) {
+        return tag[1].startsWith(stripGeohashPrefixWildcard(criterion))
       }
 
       return tag[1] === criterion

src/utils/filter.ts

@@ -1 +1,13 @@
+import { EventTags } from '../constants/base'
+
 export const isGenericTagQuery = (key: string) => /^#[a-zA-Z]$/.test(key)
+
+// NIP-12 geohash filter helpers
+export const geohashTagQuery = `#${EventTags.Geohash}`
+
+export const isGeohashTagQuery = (key: string): boolean => key === geohashTagQuery
+
+export const isGeohashPrefixCriterion = (key: string, criterion: string): boolean =>
+  isGeohashTagQuery(key) && criterion.endsWith('*')
+
+export const stripGeohashPrefixWildcard = (criterion: string): string => criterion.slice(0, -1)

src/utils/geohash.ts

@@ -0,0 +1,9 @@
+// Geohash base32 alphabet (excludes 'a', 'i', 'l', 'o')
+export const GEOHASH_BASE32 = '0123456789bcdefghjkmnpqrstuvwxyz'
+
+// Matches a complete geohash (one or more base32 chars)
+export const GEOHASH_PATTERN = /^[0123456789bcdefghjkmnpqrstuvwxyz]+$/
+
+// Matches a geohash filter criterion: one or more base32 chars, with an
+// optional single trailing '*' wildcard (NIP-12 prefix matching)
+export const GEOHASH_FILTER_PATTERN = /^[0123456789bcdefghjkmnpqrstuvwxyz]+\*?$/

test/unit/schemas/event-schema.spec.ts

@@ -163,6 +163,42 @@ describe('NIP-65', () => {
   })
 })
 
+describe('NIP-12', () => {
+  const geohashBase: Event = {
+    id: 'fa4dd948576fe182f5d0e3120b9df42c83dffa1c884754d5e4d3b0a2f98a01c5',
+    pubkey: 'edfa27d49d2af37ee331e1225bb6ed1912c6d999281b36d8018ad99bc3573c29',
+    created_at: 1660306803,
+    kind: EventKinds.TEXT_NOTE,
+    tags: [],
+    content: '',
+    sig: '313a9b8cd68267a51da84e292c0937d1f3686c6757c4584f50fcedad2b13fad755e6226924f79880fb5aa9de95c04231a4823981513ac9e7092bad7488282a96',
+  }
+
+  it('accepts event with valid base32 geohash tag', () => {
+    const event = { ...geohashBase, tags: [[EventTags.Geohash, 'u4pruydqqvj']] }
+    const result = validateSchema(eventSchema)(event)
+    expect(result.error).to.be.undefined
+  })
+
+  it('rejects event with non-base32 geohash characters', () => {
+    const event = { ...geohashBase, tags: [[EventTags.Geohash, 'u4pruyda']] }
+    const result = validateSchema(eventSchema)(event)
+    expect(result.error).to.not.be.undefined
+  })
+
+  it('rejects event with empty geohash', () => {
+    const event = { ...geohashBase, tags: [[EventTags.Geohash, '']] }
+    const result = validateSchema(eventSchema)(event)
+    expect(result.error).to.not.be.undefined
+  })
+
+  it('rejects event with uppercase geohash', () => {
+    const event = { ...geohashBase, tags: [[EventTags.Geohash, 'U4PRUYDQQVJ']] }
+    const result = validateSchema(eventSchema)(event)
+    expect(result.error).to.not.be.undefined
+  })
+})
+
 describe('NIP-14', () => {
   it('accepts subject tag on text note events', () => {
     const event: Event = {

test/unit/schemas/filter-schema.spec.ts

@@ -141,3 +141,47 @@ describe('NIP-01', () => {
     }
   })
 })
+
+describe('NIP-12', () => {
+  describe('#g filter validation', () => {
+    it('accepts a valid base32 geohash', () => {
+      const result = validateSchema(filterSchema)({ '#g': ['u4pruydqqvj'] })
+      expect(result.error).to.be.undefined
+    })
+
+    it('accepts a valid geohash prefix with trailing wildcard', () => {
+      const result = validateSchema(filterSchema)({ '#g': ['u4pruyd*'] })
+      expect(result.error).to.be.undefined
+    })
+
+    it('rejects an empty criterion', () => {
+      const result = validateSchema(filterSchema)({ '#g': [''] })
+      expect(result.error).to.not.be.undefined
+    })
+
+    it('rejects a bare wildcard', () => {
+      const result = validateSchema(filterSchema)({ '#g': ['*'] })
+      expect(result.error).to.not.be.undefined
+    })
+
+    it('rejects non-base32 characters', () => {
+      const result = validateSchema(filterSchema)({ '#g': ['u4pruyda'] })
+      expect(result.error).to.not.be.undefined
+    })
+
+    it('rejects uppercase characters', () => {
+      const result = validateSchema(filterSchema)({ '#g': ['U4PRUYDQQVJ'] })
+      expect(result.error).to.not.be.undefined
+    })
+
+    it('rejects wildcard not at the end', () => {
+      const result = validateSchema(filterSchema)({ '#g': ['u4*pruyd'] })
+      expect(result.error).to.not.be.undefined
+    })
+
+    it('rejects multiple wildcards', () => {
+      const result = validateSchema(filterSchema)({ '#g': ['u4pruyd**'] })
+      expect(result.error).to.not.be.undefined
+    })
+  })
+})