DARBAR दरबार

Why DARBAR?

Before DARBAR, yakmesh had ~195 routes scattered across three API layers with inconsistent auth patterns: some checked JWT manually, others verified peer signatures inline, many had no auth at all. DARBAR replaces all of this with a single declarative pattern:

Six Auth Levels

DARBAR defines a strict hierarchy of six authentication levels. Each level includes all the checks of the levels below it:

import { AuthLevel } from 'yakmesh/server/darbar';

// Auth hierarchy (lowest to highest):
// PUBLIC < LOCAL < PEER < USER < ADMIN < HOST

// PEER auth verifies ML-DSA-65 signatures:
// Headers: x-node-id, x-node-signature, x-node-timestamp
// Timestamp drift tolerance: 10 seconds
// Public keys resolved from peer registry (never from the request)

Domain-Based Routing

Routes are grouped into domains — logical units that share a URL prefix and are mounted as isolated Express Routers. If a domain’s routes throw, other domains continue serving:

import { createDarbar, AuthLevel } from 'yakmesh/server/darbar';

const darbar = createDarbar({
  verifyToken:      jwt.verify,
  resolveIdentity:  identityStore.resolve,
  hostPersistentId: () => nodeIdentity.persistentId,
  isDelegate:       (pid) => delegateSet.has(pid),
  resolvePeerKey:   (nodeId) => peerRegistry.getPublicKey(nodeId),
  verifySignature:  crypto.verifyMLDSA65,
});

// Mount domains
darbar.mount(app, [
  {
    domain: 'lighthouse',
    prefix: '/api/lighthouse',
    routes: [
      { method: 'GET',  path: '/',          auth: AuthLevel.PUBLIC,  handler: listServers },
      { method: 'POST', path: '/heartbeat', auth: AuthLevel.USER,    handler: heartbeat },
      { method: 'POST', path: '/register',  auth: AuthLevel.USER,    handler: registerServer },
    ],
  },
  {
    domain: 'governance',
    prefix: '/api/governance',
    routes: [
      { method: 'GET',  path: '/scores',    auth: AuthLevel.PUBLIC,  handler: getScores },
      { method: 'POST', path: '/vote',      auth: AuthLevel.USER,    handler: castVote },
      { method: 'POST', path: '/ban',       auth: AuthLevel.ADMIN,   handler: banPlayer },
    ],
  },
]);

// Error handler (after all routes)
app.use(darbar.errorHandler());

DarbarError & Error Codes

Handlers throw DarbarError to produce standardised JSON error responses. The global error handler maps each error code to the correct HTTP status:

import { DarbarError, ErrorCode } from 'yakmesh/server/darbar';

async function registerServer(req, res) {
  const { name, port } = req.body;
  if (!name) throw new DarbarError('Server name required', ErrorCode.VALIDATION_ERROR);
  if (port < 1024) throw new DarbarError('Port must be >= 1024', ErrorCode.VALIDATION_ERROR);

  const server = await serverDirectory.register({ name, port, owner: req.user.userId });
  res.json({ ok: true, serverId: server.id });
}

// Error response shape (automatic):
// { "error": "Server name required", "code": "VALIDATION_ERROR" }

DarbarConfig Interface

Each project provides a DarbarConfig object that plugs project-specific auth backends into the framework:

Cross-Project Usage

DARBAR is shared across all yakmesh sub-projects. Each project provides its own DarbarConfig and domain descriptors:

API Reference

Version History