s-m-r-t

@happyvertical/smrt-gnode

Federation library for building federated local knowledge bases (gnodes) with P2P discovery and cross-gnode communication.

v0.19.0FederationWebFingerP2P

Overview

smrt-gnode enables federated local knowledge bases that transform government documents into accessible, multi-modal knowledge. Provides P2P discovery, peer exchange, and ActivityPub-inspired protocols.

Installation

bash 
npm install @happyvertical/smrt-gnode

Quick Start

typescript 
import { Federation, WebFingerProtocol } from '@happyvertical/smrt-gnode';

// Configure federation
const federation = new Federation({
  enabled: true,
  discoverability: 'public',
  peers: ['https://example.gnode'],
  autodiscovery: true,
  peerExchange: true
});

// Discover peers
const peers = await federation.discoverPeers();

// Use WebFinger for discovery
const gnodeInfo = await WebFingerProtocol.discover('example.com');
// Returns: {
//   subject: 'acct:gnode@example.com',
//   links: [{ rel: 'self', href: 'https://example.com/.well-known/gnode' }]
// }

Federation Concepts

Gnode (Local Knowledge Base)

A gnode is a federated local knowledge base that:

  • Stores and indexes government documents
  • Provides multi-modal access (web, API, voice)
  • Discovers and communicates with peer gnodes
  • Shares knowledge while maintaining local autonomy

Discovery Methods

typescript 
// WebFinger discovery
const info = await WebFingerProtocol.discover('city.gov');

// DNS-based discovery
const dnsRecords = await federation.discoverViaDNS('city.gov');

// Peer exchange
const morePeers = await federation.exchangePeersWithGnode('https://peer.gnode');

Cross-Gnode Queries

typescript 
// Query remote gnode
const results = await federation.queryGnode('https://peer.gnode', {
  type: 'Meeting',
  filters: { date: { gte: '2025-01-01' } },
  limit: 10
});

// Aggregate from multiple gnodes
const allResults = await federation.queryMultiple(
  ['https://peer1.gnode', 'https://peer2.gnode'],
  { type: 'Resolution', status: 'passed' }
);

Federation Protocols

WebFinger

RFC 7033 WebFinger protocol for resource discovery:

json 
GET /.well-known/webfinger?resource=acct:gnode@example.com

Response:
{
  "subject": "acct:gnode@example.com",
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://example.com/.well-known/gnode"
    }
  ]
}

Peer Exchange Protocol

typescript 
// Exchange peer lists
const exchange = await federation.peerExchange({
  myPeers: federation.getPeerList(),
  requestPeers: true
});

console.log(`Learned about ${exchange.newPeers.length} new gnodes`);

Use Cases

Municipal Government Networks

Connect city councils, county boards, and regional authorities for shared meeting minutes, resolutions, and public records.

Regional News Aggregation

Federate local news sources to provide comprehensive regional coverage while maintaining editorial independence.

Public Records Networks

Enable citizens to search across multiple jurisdictions for permits, planning documents, and public notices.

Best Practices

DOs

  • Use WebFinger for standard-compliant discovery
  • Enable peer exchange to grow the network
  • Cache peer lists to reduce discovery overhead
  • Implement rate limiting for cross-gnode queries
  • Document your gnode's API endpoints

DON'Ts

  • Don't expose private data through federation
  • Don't trust peer data without validation
  • Don't implement custom protocols (use standards)
  • Don't query peers excessively (implement caching)
  • Don't ignore security headers and HTTPS

Related Modules