Mosta Net

@mostajs/net — Octonet

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).

[Octonet Logo]

[npm] [License] [mcp.so]

Author : Dr Hamid MADANI <[email protected]> Homepage : octonet.amia.fr · mcp.amia.fr

[Octonet stack as electrical sockets: @mostajs/orm plugs into 13 databases, @mostajs/net (Octonet) re-exposes them over 11 transports, Data-Plug bridges them, and NetClient fans out to 18 language clients consumed by any external app.]

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.

Table of Contents

1. What is Octonet
2. Try in 2 clicks (T1 sandbox)
3. 3-tier onboarding model
4. 11 transports
5. 13 databases
6. Multi-tenant authentication
7. Generic scope registry
8. Multi-project support
9. Quick start (self-host)
10. Configuration (.env)
11. API endpoints reference
12. Architecture
13. Boot sequence
14. 14 polyglot NetClients
15. Production deploy (amia.fr)
16. License

What is Octonet

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.

The same User entity is reachable as :

curl https://octonet.amia.fr/api/v1/User              # RESTcurl https://octonet.amia.fr/graphql -d '{"query":...}'  # GraphQLwscat -c wss://octonet.amia.fr/ws                     # WebSocketcurl -N https://octonet.amia.fr/mcp                   # MCP (Claude Desktop)# … 7 more

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)
• #3 — NetClients polyglottes : 14 native client libraries (Java, .NET, Python, Go, Swift, Kotlin, Dart, Rust, PHP, Ruby, Elixir, Lua, Delphi, Unity)

Try in 2 clicks (T1 sandbox)

The fastest way to test Octonet from any of the 14 runtimes :

1. Open https://octonet.amia.fr/try
2. Pick an alias (e.g. alice-42)
3. Get an apikey scoped to your sandbox

curl -X POST https://octonet.amia.fr/try \  -H "Content-Type: application/json" \  -d '{"alias":"alice-42"}'
# Response:{  "status": "ok",  "data": {    "alias": "alice-42",    "projectSlug": "sandbox-alice-42",    "apiKey": "sk_test_…(64 chars, shown ONCE)",    "permissions": { "projects":["sandbox-alice-42"], "operations":["read","write"], "transports":["rest","mcp"] },    "expiresAt": "2026-05-02T18:38:19.920Z",    "quota": { "reqPerDay": 500 },    "exampleCurl": "curl https://octonet.amia.fr/api/v1/sandbox-alice-42/User -H \"X-API-Key: sk_test_…\"",    "mcpUrl": "https://octonet.amia.fr/mcp"  }}

Your sandbox is :

• A private SQLite file (isolated from other aliases)
• Pre-seeded with User, Product, Order entities
• Read+write CRUD via REST and MCP
• 500 requests/day quota
• TTL 7 days (auto-deleted if idle)
• Free, no email required, anti-abuse rate-limited (10 sandboxes/h/IP)

Use the apikey in any of the 14 NetClients :

# Java / .NET / Python / Go / etc.export MOSTAJS_NET_URL=https://octonet.amia.frexport MOSTAJS_NET_API_KEY=sk_test_…

3-tier onboarding model

11 transports

Auto-generated from your registered schemas. Toggle each via env var (default : all enabled).

Le même schéma, 11 portes d'entrée différentes, 0 codegen.

13 databases

Persistence dialects fournis par @mostajs/orm :

Switch dialect = changer 1 ligne d'env :

DB_DIALECT=postgres → DB_DIALECT=mongodbSGBD_URI=postgresql://… → SGBD_URI=mongodb://…

Multi-tenant authentication

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.

Flux d'auth d'une requête

HTTP Request  │  ▼authGuard (Fastify adapter)  │  ▼checkRequest (@mostajs/auth — framework-agnostic)  │  ├─ extract X-API-Key from header / Bearer token / ?apikey=  ├─ resolveApiKey (@mostajs/api-keys) — DB lookup + bcrypt verify  ├─ isScopeAuthorized (@mostajs/api-keys) — check scope.values  │     for each (scope, value) pair :  │       checks: [{scope:'projects', value:slug},  │                {scope:'operations', value:'read'|'write'|'admin'},  │                {scope:'transports', value:'rest'|'mcp'|...}]  ├─ touchApiKey — fire-and-forget : lastUsedAt, usageCount, lastIp  │  ▼ormHandler (entité CRUD) ─→ sanitizer (strip password/hash/tokens)  │  ▼HTTP Response

Scope-based permissions (generic, extensible)

Une apikey a la shape :

{  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).

HTTP status mapping

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) :

-- Auto-créées au boot via @mostajs/api-keysCREATE TABLE api_key_scopes (  id, name, label, description, icon, cardinality,  valuesSource ('static' | 'dynamic'), dynamicSourceRef);
CREATE TABLE api_key_scope_values (  id, scopeName, value, label, sortOrder, metadata);

Chaque module enregistre ses scopes au boot :

import { registerScope } from '@mostajs/api-keys/server'
// Dans mosta-net/src/server.ts (boot)await registerScope(dialect, {  name: 'transports', label: 'Network transports',  cardinality: 'low', valuesSource: 'static',  staticValues: [    {value:'rest', sortOrder:1},    {value:'graphql', sortOrder:2},    // … 9 more  ],})
await registerScope(dialect, {  name: 'projects', label: 'Projects',  cardinality: 'high', valuesSource: 'dynamic',  dynamicSourceRef: 'Project.slug',  // queried at runtime})

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"

Ajouter un projet à l'exécution

curl -X POST http://localhost:4488/api/projects \  -H "X-API-Key: <admin-key>" \  -d '{    "name": "analytics",    "dialect": "mongodb",    "uri": "mongodb://localhost:27017/analytics",    "schemas": [{"name":"Event", "fields":{"type":"string","ts":"date"}}]  }'

Persisté dans projects-tree.json (chemin : MOSTA_PROJECTS env var).

Quick start (self-host)

Install

npm install @mostajs/net @mostajs/orm @mostajs/mproject \            @mostajs/rbac @mostajs/auth @mostajs/api-keys \            @mostajs/config better-sqlite3

Run with SQLite (zero infra)

DB_DIALECT=sqlite \SGBD_URI=./data/octonet.db \DB_SCHEMA_STRATEGY=update \[email protected] \OCTONET_ADMIN_PASSWORD=ChangeMe123! \npx mostajs-net serve

Console output :

Loaded 3 schemas from schemas.json[DAL:SQLite] INIT_SCHEMA strategy=update {"entities":["User","Product","Order"]}✓ Apikey scopes registered (projects, operations, transports)✓ RBAC ready — [email protected] trial=…  public=…⚠ public demo apikey emitted ONCE → sk_live_xxxxxxxx…  (save it!)✓ Sanitizer middleware on rest, graphql, ws, sse, trpc, mcp, odata, jsonrpc✓ ApiKey middleware on rest, graphql, ws, sse, trpc, mcp, odata, jsonrpc✓ Protected ormHandler ready (sanitizer + apikey global wrapper)✓ T1 sandbox endpoint /try ready (rate-limited 10/h/IP, TTL 7d)
  @mostajs/net  v2.6.x  ─────────────────────────────────────────────────  Dialect:    sqlite (./data/octonet.db)  Entities:   User, Product, Order  (3)  Port:       4488  Strategy:   update  Transports: rest, graphql, ws, sse, trpc, mcp, odata, jsonrpc  (8)  Ready.  3 entities × 8 transports = 24 endpoints

Test

# Sans apikey → 401curl 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 dialectsSGBD_URI=postgresql://user:pass@localhost:5432/dbDB_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 dialectsMOSTA_SYSTEM_URI=postgresql://user:pass@localhost:5432/octonet_system

Voir section System dialect ci-dessous pour la motivation et les how-to.

Server

MOSTA_NET_PORT=4488MOSTA_PROJECTS=./projects-tree.json                # path to multi-project configSCHEMAS_PATH=./schemas                              # directory scanning fallback

Transports (toggle each)

MOSTA_NET_REST_ENABLED=trueMOSTA_NET_GRAPHQL_ENABLED=trueMOSTA_NET_WS_ENABLED=trueMOSTA_NET_SSE_ENABLED=trueMOSTA_NET_JSONRPC_ENABLED=trueMOSTA_NET_MCP_ENABLED=trueMOSTA_NET_TRPC_ENABLED=trueMOSTA_NET_ODATA_ENABLED=trueMOSTA_NET_GRPC_ENABLED=falseMOSTA_NET_NATS_ENABLED=falseMOSTA_NET_ARROW_ENABLED=false
MOSTA_NET_CORS_ORIGIN=*MOSTA_RATE_LIMIT_CLIENT=1000

RBAC bootstrap (lus via @mostajs/config — supports profile cascade MOSTA_ENV=DEV)

[email protected]               # 1er boot only ; ignored afterOCTONET_ADMIN_PASSWORD=secret-12345OCTONET_ADMIN_FIRSTNAME=Admin                       # optionalOCTONET_ADMIN_LASTNAME=Octonet                      # optionalOCTONET_BOOTSTRAP_VERBOSE=false                     # detailed bootstrap logsOCTONET_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 DBPORTAL_DB_URI=postgresql://user:pass@localhost:5432/octonet_cloud     # legacy octocloud DB

API endpoints reference

Public

Project / entity CRUD (requires apikey)

Schema management (requires admin apikey)

Auth & API keys (requires admin)

Transports natifs

Multi-project management

Observability

Architecture

                                 ┌──────────────────────────────────┐                                 │       Fastify (port 4488)        │                                 └────────────────┬─────────────────┘                                                  │       ┌─────────────────────────────────────────┴──────────────────────────────┐       │                                                                        │       ▼                                                                        ▼┌────────────────────────┐                                       ┌────────────────────────┐│  Transports (11)       │                                       │  Direct Fastify routes ││  - REST                │                                       │  - /try                ││  - GraphQL (mercurius) │                                       │  - /api/projects/*     ││  - WS                  │                                       │  - /api/api-keys/*     ││  - SSE                 │                                       │  - /health, /metrics   ││  - JSON-RPC            │                                       └────────────────────────┘│  - MCP (SDK Anthropic) ││  - gRPC                │              ┌─────────────────────────────────────┐│  - tRPC                │              │  Auth pipeline                      ││  - OData               │              │  ┌──────────────┐                   ││  - NATS                │              │  │ extractAuth  │ ←  HTTP request   ││  - Arrow               ├──────────────┤  │ Context      │                   │└────────────────────────┘              │  └──────┬───────┘                   │                                        │         ▼                           │                                        │  ┌──────────────┐                   │                                        │  │ checkRequest │ ←  scope-checks   │                                        │  │ (mosta-auth) │                   │                                        │  └──────┬───────┘                   │                                        │         ▼                           │                                        │  ┌──────────────┐                   │                                        │  │ checkApiKey  │ ←  resolve+verify │                                        │  │ (api-keys)   │                   │                                        │  └──────┬───────┘                   │                                        └─────────┼───────────────────────────┘                                                  ▼                                        ┌────────────────────────┐                                        │ Sanitizer middleware   │                                        │ strips password/hash/  │                                        │ tokens before response │                                        └────────┬───────────────┘                                                 ▼                                        ┌────────────────────────┐                                        │ ormHandler             │                                        │ → ProjectManager.resolve│                                        │ → EntityService.execute │                                        └────────┬───────────────┘                                                 ▼                                        ┌────────────────────────┐                                        │ @mostajs/orm dialect   │                                        │ (13 SGBD)              │                                        └────────────────────────┘

Modules de l'écosystème consommés

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.

Configuration recommandée (prod multi-base)

# Métier — peut bouger via /api/change-dialectDB_DIALECT=postgresSGBD_URI=postgresql://hmd:***@127.0.0.1:5432/octonet_business
# Système — stable, jamais touché par les routes adminMOSTA_SYSTEM_DIALECT=postgresMOSTA_SYSTEM_URI=postgresql://hmd:***@127.0.0.1:5432/octonet_system

Configuration mono-base (dev / déploiement simple)

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 actuellepg_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 .envecho 'MOSTA_SYSTEM_DIALECT=postgres' >> .env.localecho 'MOSTA_SYSTEM_URI=postgresql://hmd:***@127.0.0.1:5432/octonet_system' >> .env.local
# 4. Restart Octonet — le bootstrap RBAC + scopes seed sur octonet_systempm2 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 fonctionnercurl -H "X-API-Key: sk_live_…" http://localhost:4488/api/auth/verify# → 200 OK
# Bouger le dialect métier vers SQLitecurl -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 :

Le dialect métier (dialect) reste utilisé légitimement pour :

• Bootstrap initial du singleton métier (L98) + pm.setDefault('default', dialect, …) (L126, L240)
• Routes admin /api/reconnect, /api/change-dialect, /api/reload-config, /api/test-connection, /api/truncate-tables, /api/drop-tables — toutes opérations explicitement métier
• EntityService qui sert les entités userland (opérations CRUD via les transports protégés)

Étapes du chantier (historique)

Boot sequence

1. Load .env via @mostajs/config (profile cascade MOSTA_ENV)
2. Connect main dialect (SGBD_URI)
3. Load schemas (priority : getAllSchemas() registry → schemas.json → SCHEMAS_PATH directory scan)
4. dialect.initSchema(schemas) with strategy update/create
5. Bootstrap RBAC (octonet-rbac-bootstrap.ts) :
   • register UserSchema/RoleSchema/PermissionSchema/PermissionCategorySchema/AccountSchema/ApiKeySchema
   • seedRBAC(OCTONET_RBAC_SEED) — 6 categories, 25 permissions, 4 roles (admin/subscriber/trial/public)
   • createAdmin() from OCTONET_ADMIN_EMAIL/PASSWORD
   • create Account trial-playground (type='trial')
   • create User public-demo (role=public)
   • create Account public-system (type='system')
   • generate ApiKey public-default scoped to default project (read-only, REST + MCP) — emitted ONCE in clear
6. Register canonical scopes : projects (dynamic, Project.slug), operations (static : read/write/admin), transports (static : 11 values)
7. Push default project to projects-tree.json (ownerId=admin, visibility=public)
8. Load additional projects from projects-tree.json
9. Wrap ormHandler with composeMiddleware([sanitizer, apikey], ormHandler) → protectedOrmHandler
10. Start each enabled transport :
    • transport.use(loggingMiddleware)
    • transport.use(sanitizerMiddleware)
    • transport.use(apiKeyMiddleware)
    • transport.setHandler(ormHandler)
    • transport.start(config)
11. Register Fastify routes :
    • registerDynamicRestRoutes(app, protectedOrmHandler, pm) — /api/v1/...
    • registerProjectRoutes(app, pm, protectedOrmHandler) — /:project/*
    • registerTryRoutes(app, {dialect, pm}) — /try POST
    • registerTryPage(app) — /try GET (HTML)
    • startTrialCleanupJob({dialect, pm}) — cron horaire TTL 7j
12. Listen on port (MOSTA_NET_PORT)

14 polyglot NetClients

Octonet est consommable depuis 14 runtimes natifs, avec la même apikey, la même URL :

Monorepo : github.com/apolocine/mosta-net-clients

Chaque NetClient suit le même contrat d'API :

NetClient.create()  .url(...)  .apiKey(...)  .build()  .findAll(entity, filter, options)  .findById(entity, id)  .create(entity, data)  .update(entity, id, data)  .delete(entity, id)  .uploadSchemasJson(schemas)  .health()

Production deploy (amia.fr)

Le déploiement de référence tourne sur octonet.amia.fr + mcp.amia.fr (alias compat) en backend PostgreSQL :

Le kit de déploiement complet est dans Entreprise/octonet-mcp/ :

• apache/mcp.amia.fr.conf — vhost Apache2 (proxy SSE, WS upgrade, certs Let's Encrypt SAN)
• ecosystem.config.cjs — config PM2
• deploy.sh / install.sh / update.sh — scripts d'orchestration
• tests/smoke-all.sh — suite de smoke tests (DNS, TLS, /health, SSE MCP, REST, /try, NetClient Java)

CLI

npx mostajs-net serve                      # Start servernpx mostajs-net mcp                        # MCP-only modenpx mostajs-net generate-apikey <label>    # Émettre une apikey via CLInpx mostajs-net hash-password <password>   # Hash bcryptnpx 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.

— (c) 2026 Dr Hamid MADANI <[email protected]>