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

Author : Dr Hamid MADANI \ Homepage : octonet.amia.fr · mcp.amia.fr

---

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              # REST

curl https://octonet.amia.fr/graphql -d '{"query":...}' # GraphQL wscat -c wss://octonet.amia.fr/ws # WebSocket curl -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.fr export 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=mongodb

SGBD_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-keys

CREATE 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: " \ -d '{ "name": "analytics", "dialect": "mongodb", "uri": "mongodb://localhost:27017/analytics",