fix: use CTI middleware for authentication

Main reasons for this change:
- the FreePBX REST api can have restricted access by source IP
- the same CTI API can be used both by Matrix2Acrobits and
  ctiapp-proxyauth

Author: gsanchietti

README.md

@@ -18,8 +18,8 @@ The proxy is configured via environment variables. Minimal required env:
 - `PROXY_PORT` (optional): port to listen on (default: `8080`)
 - `AS_USER_ID` (optional): the user ID of the Application Service bot (default: `@_acrobits_proxy:matrix.example`)
 - `PROXY_URL` (optional): public-facing URL of this proxy (e.g. `https://matrix.example.com`), if not specified, use the value of `MATRIX_HOMESERVER_URL`
- - `EXT_AUTH_URL` (optional): external HTTP endpoint used to validate extension+password for push token reports (eg: `https://voice.nethserver.org/freepbx/rest/testextauth`)
- - `EXT_AUTH_TIMEOUT_S` (optional): timeout in seconds for calls to `EXT_AUTH_URL` (default: `5`)
+- `EXT_AUTH_URL` (optional): base URL of the external authentication service (eg: `https://voice.nethserver.org/`). The proxy uses the CTI middleware to authentication, and automatically appends `/api/login` and `/api/chat?users=1` to this URL.
+- `EXT_AUTH_TIMEOUT_S` (optional): timeout in seconds for calls to `EXT_AUTH_URL` (default: `5`)
 - `LOGLEVEL` (optional): logging verbosity level - `DEBUG`, `INFO`, `WARNING`, `CRITICAL` (default: `INFO`)
 - `PUSH_TOKEN_DB_PATH` (optional): path to a database file for storing push tokens
 - `CACHE_TTL_SECONDS` (optional): time-to-live for in-memory cache entries (default: `3600` seconds)

docs/AUTHENTICATION.md

@@ -2,21 +2,36 @@
 
 All client API endpoints (`/api/client/fetch_messages`, `/api/client/send_message`, `/api/client/push_token_report`) require authentication via an external authentication service.
 
-The external authentication service is implemented inside NethVoice FreePBX container [REST APIs](https://github.com/nethesis/ns8-nethvoice/tree/main/freepbx/var/www/html/freepbx/rest).
+The external authentication service is provided by NethCTI Middleware, which manages user credentials, chat capabilities, and Matrix homeserver configuration.
 
-### External Auth Flow
+### External Auth Flow (2-Step Process)
 
-When a client sends a request, the proxy:
-1. Extracts the `username` (extension) and `password` from the request.
-2. Calls `EXT_AUTH_URL` with a POST request containing JSON: `{"extension":"<username>","secret":"<password>"}`.
-3. On successful auth (200), parses the response for `main_extension`, `sub_extensions`, and `user_name`, which are converted into a mapping and saved.
-4. On failure (401 or other error), returns an authentication error and does NOT save the push token or create a mapping.
-5. Auth responses are cached in-memory for `CACHE_TTL_SECONDS` seconds to reduce external service load.
+When a client sends a request with `username` and `password`, the proxy performs a 2-step authentication:
+
+**Step 1: Login (POST to `/api/login`)**
+1. Extract the username part from the `username` field (e.g., if `username` is `[email protected]`, extract `user`)
+2. POST to `{EXT_AUTH_URL}/api/login` with JSON payload: `{"username":"<user>","password":"<password>"}`
+3. On successful auth (200), parse the response to get the JWT `token` field
+4. Decode the JWT to extract claims (without signature verification)
+
+**Step 2: Verify Chat Capability & Fetch Configuration (GET from `/api/chat?users=1`)**
+5. Verify that the JWT contains the `nethvoice_cti.chat` claim set to `true`
+6. If the claim is missing or false, authentication fails
+7. GET from `{EXT_AUTH_URL}/api/chat?users=1` with Bearer token in Authorization header
+8. Parse the response to extract:
+   - Matrix homeserver configuration (`matrix.base_url`, `matrix.acrobits_url`)
+   - User mappings from the `users` array (`user_name`, `main_extension`, `sub_extensions`)
+9. Convert user data into `MappingRequest` objects and cache them
+
+**Error Handling**
+- On any failure (login error, missing claim, invalid JWT, chat endpoint error), returns authentication error
+- Does NOT save the push token or create a mapping on failure
+- Successful authentications are cached in-memory for `CACHE_TTL_SECONDS` seconds to reduce external service load
 
 If any request is missing a `password`, it fails with authentication error.
 
 ### Environment variables related to auth
 
-- `EXT_AUTH_URL`: external HTTP endpoint used to validate extension+password for push token reports (eg: `https://voice.nethserver.org/freepbx/rest/testextauth`)
+- `EXT_AUTH_URL`: Base URL of the external authentication service (eg: `https://cti.nethserver.org/`). The proxy automatically appends `/api/login` and `/api/chat?users=1` to this URL.
 - `EXT_AUTH_TIMEOUT_S`: timeout in seconds for calls to `EXT_AUTH_URL` (default: `5`)
 - `CACHE_TTL_SECONDS`: cache TTL for external auth responses (default: `3600` seconds)

docs/openapi.yaml

@@ -13,7 +13,9 @@ paths:
       operationId: fetchMessages
       description: |
         Checks for new incoming messages by performing a Matrix /sync on behalf of the user.
-        Authentication is handled by the Application Service backend; the `password` field is ignored.
+        Authentication is performed against an external authentication service (2-step flow):
+        1. POST /api/login with username and password to get JWT token
+        2. GET /api/chat?users=1 with Bearer token to fetch user mappings and verify chat capability
       requestBody:
         required: true
         content:
@@ -26,10 +28,10 @@ paths:
               properties:
                 username:
                   type: string
-                  description: The full Matrix ID (e.g., @user:server.com) of the user to impersonate.
+                  description: The extension/username (format can be user@domain), which is sent to the external auth service.
                 password:
                   type: string
-                  description: Password used to authenticate the extension/user via the external auth service.
+                  description: Password used to authenticate via the external auth service.
                 last_id:
                   type: string
                   description: The 'since' token from the last sync.
@@ -58,12 +60,14 @@ paths:
 
         The `from` field can be:
         - A full Matrix ID (e.g., @user:server.com) - used directly
-        - A phone number (e.g., +1234567890) - resolved to Matrix ID via -to-Matrix mapping if available
+        - A phone number (e.g., +1234567890) - resolved to Matrix ID via phone-to-Matrix mapping if available
 
         If a phone number is provided and a mapping exists, the message is sent on behalf of the mapped Matrix user.
         If a phone number is provided but no mapping exists, the phone number is used as the sender ID.
 
-        Authentication is handled by the Application Service backend; the `password` field is ignored.
+        Authentication is performed against an external authentication service (2-step flow):
+        1. POST /api/login with username and password to get JWT token
+        2. GET /api/chat?users=1 with Bearer token to fetch user mappings and verify chat capability
       requestBody:
         required: true
         content:
@@ -118,6 +122,10 @@ paths:
         Receives and stores device push tokens from Acrobits clients.
         The tokens are persisted in a SQLite database for later use in push notification delivery.
         This endpoint follows the Acrobits Push Token Reporter API specification for POST JSON requests.
+        
+        Authentication is performed against an external authentication service (2-step flow):
+        1. POST /api/login with username and password to get JWT token
+        2. GET /api/chat?users=1 with Bearer token to fetch user mappings and verify chat capability
       requestBody:
         required: true
         content:

go.mod

@@ -14,6 +14,7 @@ require (
 	filippo.io/edwards25519 v1.1.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/golang-jwt/jwt/v5 v5.3.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
 	github.com/labstack/gommon v0.4.2 // indirect

go.sum

@@ -6,6 +6,8 @@ github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
+github.com/golang-jwt/jwt/v5 v5.3.0 h1:pv4AsKCKKZuqlgs5sUmn4x8UlGa0kEVt/puTpKx9vvo=
+github.com/golang-jwt/jwt/v5 v5.3.0/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/google/pprof v0.0.0-20240409012703-83162a5b38cd h1:gbpYu9NMq8jhDVbvlGkMFWCjLFlqqEZjEmObmhUy6Vo=
 github.com/google/pprof v0.0.0-20240409012703-83162a5b38cd/go.mod h1:kf6iHlnVGwgKolg33glAes7Yg/8iWP8ukqeldJSO7jw=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=

main.go

@@ -60,13 +60,6 @@ func main() {
 	pushSvc := service.NewPushService(pushTokenDB)
 	api.RegisterRoutes(e, svc, pushSvc, cfg.MatrixAsToken, pushTokenDB)
 
-	// Load mappings from file if MAPPING_FILE env var is set
-	if cfg.MappingFile != "" {
-		if err := svc.LoadMappingsFromFile(cfg.MappingFile); err != nil {
-			logger.Error().Err(err).Str("file", cfg.MappingFile).Msg("failed to load mappings from file")
-		}
-	}
-
 	logger.Info().Str("port", cfg.ProxyPort).Msg("starting server")
 	if err := e.Start(":" + cfg.ProxyPort); err != nil {
 		logger.Fatal().Err(err).Msg("server stopped")