One schema, 11 transports, 13 databases, multi-tenant auth — out of the box.
Schema-driven multi-protocol API server for the @mostajs ecosystem. Built with TypeScript on Fastify, designed for polyglot consumption (14 native NetClients).
1 MCP server, 13 databases, zero config. Multi-protocol transport with Auth + RBAC.
The socket board.@mostajs/orm connects to 13 databases; Octonet
(@mostajs/net) re-exposes the same entities over 11 transports (REST,
WebSocket, gRPC, MQTT, AMQP…); NetClient then fans out to 18 language
clients — so any external app plugs into your data, in any runtime.
Octonet (@mostajs/net) is a Node.js multi-transport server that exposes a single @mostajs/orm schema as 11 different network protocols simultaneously : REST, GraphQL, WebSocket, SSE, JSON-RPC, MCP, gRPC, tRPC, OData, NATS, Arrow Flight.
Backed by @mostajs/orm (13 SGBD dialects). Backed by @mostajs/rbac + @mostajs/auth + @mostajs/api-keys for multi-tenant identity. Backed by @mostajs/mproject for multi-project routing.
Octonet is the second cerebral lobe of the @mostajs trilogy :
#1 — @mostajs/orm : data persistence (13 databases)
#2 — Octonet : multi-protocol transport (11 wire protocols)
Octonet utilise un middleware d'authentification basé sur API keys avec scopes (orienté machine-to-machine) + RBAC pour la gestion humaine. L'orchestrateur agnostique vit dans @mostajs/auth/lib/check-request.ts.
{
permissions: {
scopes: {
projects: ['my-project','demo'] | '*', // declared by @mostajs/mproject
operations: ['read','write','admin'] | '*', // declared by @mostajs/orm
transports: ['rest','graphql','mcp'] | '*', // declared by @mostajs/net
// anything: any module can register a new scope
},
rateLimit: 500,
}
}
@mostajs/api-keys ne connaît PAS les noms projects/operations/transports — c'est volontaire. Chaque module enregistre ses scopes au boot via registerScope(dialect, {name, label, …}). Le check est générique : isScopeAuthorized(perms, scope, value).
{error: {code:'UNAUTHORIZED', message:'Invalid or revoked API key'}}
Apikey valide hors scope
403
{error: {code:'FORBIDDEN', message:'API key not authorized for X="Y"'}}
Apikey OK
200/201
{status:'ok', data: …} (sanitized — no password/hash)
MCP fallback (compat mcp.so)
L'endpoint /mcp autorise un fallback automatique sur l'apikey labelée public-default quand aucune clé n'est présentée — préserve la compat avec mcp.so / Claude Desktop. La clé publique est read-only sur le projet default uniquement → écritures bloquées.
Sanitizer
Les champs password, hash, verifyToken, resetToken, apiKeyHash, secret, privateKey sont automatiquement strippés de toutes les réponses JSON par un middleware global. Aucun risque de leak à travers /api/v1/User?limit=1.
Generic scope registry
Le catalogue des scopes vit en base de données du projet accueillant (pas de fichier JSON, pas de constantes hardcodées) :
L'admin UI charge le catalogue dynamique via GET /api/api-keys/scopes et rend une matrice (composant React ApiKeyScopeMatrix dans @mostajs/api-keys/components/).
Multi-project support
Via @mostajs/mproject — N bases de données isolées sur le même serveur.
Routes path-prefix
# Default project (DB_DIALECT + SGBD_URI au boot)
curl http://localhost:4488/api/v1/User
# Project nommé 'analytics'
curl http://localhost:4488/api/v1/analytics/events
# Ou via header (équivalent)
curl http://localhost:4488/api/v1/events -H "X-Project: analytics"
# Sans apikey → 401
curl http://localhost:4488/api/v1/User
# {"error":{"code":"UNAUTHORIZED","message":"API key required…"}}
# Avec apikey publique (depuis les logs ↑)
curl http://localhost:4488/api/v1/User -H "X-API-Key: sk_live_…"
# {"status":"ok","data":[{"id":"…","email":"[email protected]",…}]} ← password absent
Configuration (.env)
Database (mandatory)
DB_DIALECT=postgres # any of 13 dialects
SGBD_URI=postgresql://user:pass@localhost:5432/db
DB_SCHEMA_STRATEGY=update # 'update' (recommandé prod) | 'create' (drop+recreate, dev only)
DB_SHOW_SQL=false
System dialect (recommandé prod, optionnel) — v2.7.5+
Sépare la base système(apikeys, RBAC users, audit, plans, payments, project-life metadata) du dialect métier mutable. Sans ces variables, alias transparent vers le singleton métier (rétro-compat mono-base).
MOSTA_SYSTEM_DIALECT=postgres # any of 13 dialects
MOSTA_SYSTEM_URI=postgresql://user:pass@localhost:5432/octonet_system
Voir section System dialect ci-dessous pour la motivation et les how-to.
RBAC bootstrap (lus via @mostajs/config — supports profile cascade MOSTA_ENV=DEV)
[email protected] # 1er boot only ; ignored after
OCTONET_ADMIN_PASSWORD=secret-12345
OCTONET_ADMIN_FIRSTNAME=Admin # optional
OCTONET_ADMIN_LASTNAME=Octonet # optional
OCTONET_BOOTSTRAP_VERBOSE=false # detailed bootstrap logs
OCTONET_OPEN_MODE=false # dev only — passe sans apikey
T1 sandbox (optional)
OCTONET_TRIAL_DATA_DIR=./data/trials # SQLite files per alias
Cloud middleware (optional, futur — partage DB méta avec Octocloud)
OCTONET_META_URI=postgresql://user:pass@localhost:5432/octonet_meta # shared meta DB
PORTAL_DB_URI=postgresql://user:pass@localhost:5432/octonet_cloud # legacy octocloud DB
API endpoints reference
Public
Endpoint
Méthode
Auth
Description
/health
GET
open
server status + transports + entities
/try
GET
open
T1 sandbox provisioning HTML form
/try
POST
open (rate-limit 10/h/IP)
crée sandbox + retourne apikey one-shot
/api/v1/health
GET
open
health under api-versioned path
Project / entity CRUD (requires apikey)
Endpoint
Méthode
Op
Description
/api/v1/{Entity}
GET
findAll
list entities of default project
/api/v1/{Entity}/:id
GET
findById
get one
/api/v1/{Entity}/count
GET
count
count
/api/v1/{Entity}/one
GET
findOne
first match
/api/v1/{Entity}/search
GET
search
text search
/api/v1/{Entity}
POST
create
insert
/api/v1/{Entity}/:id
PUT
update
replace
/api/v1/{Entity}/:id
DELETE
delete
remove
/api/v1/{Entity}/:id/addToSet
POST
addToSet
add to array
/api/v1/{Entity}/:id/pull
POST
pull
remove from array
/api/v1/{Entity}/:id/increment
POST
increment
numeric add
/api/v1/{Entity}/upsert
POST
upsert
insert or update
/api/v1/{Entity}/aggregate
POST
aggregate
pipeline
/api/v1/{Entity}/updateMany
POST
updateMany
bulk update
/api/v1/{Entity}/deleteMany
POST
deleteMany
bulk delete
/api/v1/{project}/{Entity}/…
*
*
same routes scoped to a project
Schema management (requires admin apikey)
Endpoint
Méthode
Description
/api/upload-schemas-json
POST
push schemas at runtime (triggers reload)
/api/apply-schema
POST
apply schema diff
/api/compare-schema
POST
dry-run schema diff
/api/schemas-config
GET
current registered schemas
Auth & API keys (requires admin)
Endpoint
Méthode
Description
/api/api-keys
GET / POST
list / issue keys
/api/api-keys/:id
PUT / DELETE
update / revoke
/api/api-keys/scopes
GET
list registered scopes + values (for admin matrix UI)
quota / abonnement (optionnel — actif si Octocloud connecté)
@mostajs/replicator
CQRS multi-replica (optionnel)
@mostajs/project-life
persistence schemas Project (optionnel — si stockage SGBD vs JSON)
System dialect (séparé du singleton métier)
Disponible depuis v2.7.5 — résout le bug « apikeys introuvables après /api/change-dialect » observé en prod.
Pourquoi deux dialects distincts ?
Octonet expose des routes admin qui mutent la connexion DB au runtime (/api/change-dialect, /api/reload-config, /api/reconnect) — légitime côté métier(les entités userland du projet courant peuvent migrer postgres → sqlite → mongodb selon les besoins de l'admin).
Mais les modules système(apikeys, RBAC users, audit, plans de souscription, payments, project-life metadata) doivent vivre dans une base stable qui ne suit pas ces mutations. Sinon : un changement de dialect métier rend les apikeys introuvables, l'admin se trouve verrouillé hors de l'IHM.
# Métier — peut bouger via /api/change-dialect
DB_DIALECT=postgres
SGBD_URI=postgresql://hmd:***@127.0.0.1:5432/octonet_business
# Système — stable, jamais touché par les routes admin
MOSTA_SYSTEM_DIALECT=postgres
MOSTA_SYSTEM_URI=postgresql://hmd:***@127.0.0.1:5432/octonet_system
Laisser MOSTA_SYSTEM_* vides → alias automatique vers le singleton métier (rétro-compat 100 %, comportement identique au pré-v2.7.5).
How-to
1. Migrer un déploiement existant vers le mode multi-base
# 1. Sauvegarder la base actuelle
pg_dump octonet_business > backup-pre-split.sql
# 2. Créer la base système (vide — RBAC seed re-exécute au boot)
createdb octonet_system
# 3. Ajouter MOSTA_SYSTEM_* dans .env
echo 'MOSTA_SYSTEM_DIALECT=postgres' >> .env.local
echo 'MOSTA_SYSTEM_URI=postgresql://hmd:***@127.0.0.1:5432/octonet_system' >> .env.local
# 4. Restart Octonet — le bootstrap RBAC + scopes seed sur octonet_system
pm2 restart octonet-mcp
# 5. Restaurer les apikeys et RBAC users de l'ancienne base
# (à scripter selon convention métier — typiquement export/import des
# tables api_keys, users, roles, permissions, scopes, scope_values)
2. Vérifier que le système est bien isolé du métier
# Avant /api/change-dialect : apikey doit fonctionner
curl -H "X-API-Key: sk_live_…" http://localhost:4488/api/auth/verify
# → 200 OK
# Bouger le dialect métier vers SQLite
curl -X POST -H "Content-Type: application/json" \
-d '{"dialect":"sqlite","uri":":memory:","connect":true}' \
http://localhost:4488/api/change-dialect
# → "Dialecte changé et connecté : sqlite"
# Re-tester l'apikey — DOIT toujours fonctionner (système intact)
curl -H "X-API-Key: sk_live_…" http://localhost:4488/api/auth/verify
# → 200 OK (bug résolu en v2.7.5)
Avant v2.7.5, le 2ᵉ curl retournait 503 metadata DB unavailable ou 401 PostgreSQL not connected. Call connect() first.
3. Lire le system dialect depuis du code applicatif
import { getSystemDialect } from '@mostajs/data-plug'
const sysDialect = await getSystemDialect()
// Utiliser comme un dialect normal pour requêter les tables système
// (apikeys, users, roles, audit_log, plans, etc.)
4. Inspecter le bootstrap au démarrage
Au boot d'octonet-mcp, deux logs apparaissent :
✓ DB connectée: postgres ← métier
✓ System dialect: postgres (octonet_system) ← système (si MOSTA_SYSTEM_* défini)
✓ RBAC ready — admin=… trial=… public=… ← seed côté système
✓ ApiKey middleware on REST/SSE/GraphQL/... ← câblé sur système
Sites système dans src/server.ts(pour référence)
18 callers tirent désormais leur dialect via getSystemDialect() au lieu du singleton métier :
tests/smoke-all.sh — suite de smoke tests (DNS, TLS, /health, SSE MCP, REST, /try, NetClient Java)
CLI
npx mostajs-net serve # Start server
npx mostajs-net mcp # MCP-only mode
npx mostajs-net generate-apikey <label> # Émettre une apikey via CLI
npx mostajs-net hash-password <password> # Hash bcrypt
npx mostajs-net info # JSON config dump
npx octonet-mcp --dialect=X --uri=Y # Standalone MCP server (process séparé)
License
AGPL-3.0-or-later — usage libre tant que le code dérivé reste open-source.
Licence commerciale disponible : [email protected]. Pricing par projet, pas par seat.