beacon v0: did:nostr social-graph indexer (profiles/follows/relays) on Mongo; same schema as nostr-beacon for regression

Author: melvincarvalho

.env.example

@@ -0,0 +1,10 @@
+MONGODB_URI=mongodb://localhost:27017
+MONGO_DB=nostr
+
+# Collection names default to the live nostr-beacon values (for regression)
+MONGO_COLLECTION=beacon
+MONGO_FOLLOWS_COLLECTION=follows
+MONGO_RELAYS_COLLECTION=relay_lists
+
+RELAYS=wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net
+PORT=3000

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.env
+data/

README.md

@@ -0,0 +1,45 @@
+# beacon
+
+A **did:nostr social-graph indexer** — it indexes Nostr **profiles** (kind 0), **follows** (kind 3, the social graph), and **relay lists** (kind 10002) for pubkeys into MongoDB, and serves them over a small read API.
+
+Useful as the identity substrate for **SSO**: "sign in with did:nostr", plus trust / discovery over the follow graph.
+
+This is a clean reimplementation of [nostr-labs/nostr-beacon](https://github.com/nostr-labs/nostr-beacon), keeping the **same Mongo schema to start** (for regression). Per the [RFC](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/572), DID-document *generation* will delegate to jss's `buildDidDocument` rather than maintaining a second, divergent generator (the source of the bugs in nostr-labs/nostr-beacon#3).
+
+## Schema (matches the live nostr-beacon)
+
+Each collection stores the **raw Nostr event**, keyed by `pubkey`, **latest-wins** by `created_at`:
+
+| data | kind | collection |
+|---|---|---|
+| profiles | 0 | `beacon` |
+| follows (social graph) | 3 | `follows` |
+| relay lists | 10002 | `relay_lists` |
+
+(Collection names are configurable via env so the same Mongo can be read/written interchangeably.)
+
+## Run
+
+```
+npm install
+cp .env.example .env        # set MONGODB_URI and relays
+npm start                   # indexer + read API
+# or run separately:
+npm run index               # indexer only
+npm run serve               # read API only
+```
+
+## Read API
+
+- `GET /api/profiles` — recent profiles
+- `GET /api/profile/:pubkey`
+- `GET /api/follows/:pubkey`
+- `GET /api/relays/:pubkey`
+
+## Status
+
+v0 — MVP: indexer + read API + the regression-compatible schema. DID-document resolution endpoint (`/.well-known/did/nostr/:pubkey.json` via jss's `buildDidDocument`) is the next step, per the RFC.
+
+## License
+
+MIT

index.js

@@ -0,0 +1,6 @@
+// Entry point: run the read API and the relay indexer in one process.
+import { startServer } from './src/server.js';
+import { runIndexer } from './src/indexer.js';
+
+await startServer();
+await runIndexer();

package.json

@@ -0,0 +1,19 @@
+{
+  "name": "beacon",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "did:nostr social-graph indexer (profiles + follows + relay lists) on MongoDB. Same schema as nostr-beacon for regression; DID-doc generation delegates to jss buildDidDocument per RFC.",
+  "bin": { "beacon": "index.js" },
+  "scripts": {
+    "start": "node index.js",
+    "index": "node -e \"import('./src/indexer.js').then(m => m.runIndexer())\"",
+    "serve": "node -e \"import('./src/server.js').then(m => m.startServer())\""
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "express": "^4.19.2",
+    "mongodb": "^6.8.0",
+    "nostr-tools": "^2.10.0"
+  },
+  "license": "MIT"
+}

src/db.js

@@ -0,0 +1,59 @@
+// MongoDB layer for the beacon.
+//
+// Schema matches nostr-beacon (for regression): each collection stores the
+// RAW Nostr event, keyed by `pubkey`, latest-wins by `created_at`.
+//   kind 0     -> profiles      (collection: beacon)
+//   kind 3     -> social graph  (collection: follows)
+//   kind 10002 -> relay lists   (collection: relay_lists)
+import { MongoClient } from 'mongodb';
+import 'dotenv/config';
+
+const uri = process.env.MONGODB_URI || process.env.MONGO_URL || 'mongodb://localhost:27017';
+const dbName = process.env.MONGO_DB || process.env.DB_NAME || 'nostr';
+
+// Collection names default to the live nostr-beacon values so the same Mongo
+// can be read/written interchangeably for regression.
+export const COLLECTIONS = {
+  0: process.env.MONGO_COLLECTION || 'beacon',
+  3: process.env.MONGO_FOLLOWS_COLLECTION || 'follows',
+  10002: process.env.MONGO_RELAYS_COLLECTION || 'relay_lists',
+};
+
+let db, client;
+
+export async function connect() {
+  if (db) return db;
+  client = new MongoClient(uri);
+  await client.connect();
+  db = client.db(dbName);
+  // non-unique index for query/dedupe perf — does not change the doc shape
+  for (const name of new Set(Object.values(COLLECTIONS))) {
+    await db.collection(name).createIndex({ pubkey: 1 });
+  }
+  return db;
+}
+
+export async function close() {
+  if (client) await client.close();
+  db = client = undefined;
+}
+
+/** Latest-wins upsert of a raw event into the collection for its kind. */
+export async function upsertEvent(event) {
+  const name = COLLECTIONS[event.kind];
+  if (!name || !event.pubkey) return false;
+  const col = (await connect()).collection(name);
+  const existing = await col.findOne({ pubkey: event.pubkey }, { projection: { created_at: 1 } });
+  if (existing && existing.created_at >= event.created_at) return false;
+  await col.updateOne({ pubkey: event.pubkey }, { $set: { ...event } }, { upsert: true });
+  return true;
+}
+
+const one = async (kind, pubkey) => (await connect()).collection(COLLECTIONS[kind]).findOne({ pubkey });
+export const getProfile = (pubkey) => one(0, pubkey);
+export const getFollows = (pubkey) => one(3, pubkey);
+export const getRelays = (pubkey) => one(10002, pubkey);
+
+export async function recentProfiles(limit = 10) {
+  return (await connect()).collection(COLLECTIONS[0]).find().sort({ created_at: -1 }).limit(limit).toArray();
+}

src/indexer.js

@@ -0,0 +1,34 @@
+// Relay indexer: subscribe to kind 0 (profile), 3 (follows / social graph),
+// and 10002 (relay list), and upsert each raw event into Mongo.
+import { SimplePool } from 'nostr-tools/pool';
+import { upsertEvent, connect } from './db.js';
+import 'dotenv/config';
+
+const RELAYS = (process.env.RELAYS || 'wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net')
+  .split(',').map((s) => s.trim()).filter(Boolean);
+
+const KINDS = [0, 3, 10002];
+
+export async function runIndexer() {
+  await connect();
+  const pool = new SimplePool();
+  console.log(`[beacon] indexing kinds ${KINDS.join(',')} from ${RELAYS.length} relays`);
+
+  const sub = pool.subscribeMany(RELAYS, [{ kinds: KINDS }], {
+    onevent: async (event) => {
+      try {
+        if (await upsertEvent(event)) {
+          console.log(`[beacon] kind ${event.kind}  ${event.pubkey.slice(0, 12)}…`);
+        }
+      } catch (e) {
+        console.error('[beacon] upsert error:', e.message);
+      }
+    },
+  });
+
+  const stop = () => { sub.close(); pool.close(RELAYS); };
+  process.on('SIGINT', () => { stop(); process.exit(0); });
+  return { pool, sub, stop };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) runIndexer();

src/server.js

@@ -0,0 +1,28 @@
+// Thin read API over the indexed social graph.
+import express from 'express';
+import { getProfile, getFollows, getRelays, recentProfiles, connect } from './db.js';
+import 'dotenv/config';
+
+export async function startServer(port = process.env.PORT || 3000) {
+  await connect();
+  const app = express();
+
+  app.get('/api/profiles', async (_req, res, next) => {
+    try { res.json(await recentProfiles(10)); } catch (e) { next(e); }
+  });
+  app.get('/api/profile/:pubkey', async (req, res, next) => {
+    try { res.json(await getProfile(req.params.pubkey)); } catch (e) { next(e); }
+  });
+  app.get('/api/follows/:pubkey', async (req, res, next) => {
+    try { res.json(await getFollows(req.params.pubkey)); } catch (e) { next(e); }
+  });
+  app.get('/api/relays/:pubkey', async (req, res, next) => {
+    try { res.json(await getRelays(req.params.pubkey)); } catch (e) { next(e); }
+  });
+
+  app.use((err, _req, res, _next) => res.status(500).json({ error: err.message }));
+  app.listen(port, () => console.log(`[beacon] read API on :${port}`));
+  return app;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) startServer();