first commit

rus/facematch/README.md

@@ -0,0 +1,101 @@
+# facematch
+
+Node.js/Express micro-app for the **Ricerca Facciale** feature on [regalamiunsorriso.it](https://www.regalamiunsorriso.it).
+
+It shares authentication with the main Java/Tomcat app by forwarding the browser's `JSESSIONID` cookie to a lightweight JSP validation endpoint (`/admin/pg/checkSession.jsp`).
+
+---
+
+## How authentication works
+
+```
+Browser                  Nginx                  Node app (this)        Tomcat (Java app)
+  │                         │                         │                       │
+  │── GET /face_match ──────►│                         │                       │
+  │   Cookie: JSESSIONID=X  │── proxy_pass ──────────►│                       │
+  │                         │                         │── GET /admin/pg/      │
+  │                         │                         │   checkSession.jsp ──►│
+  │                         │                         │   Cookie: JSESSIONID=X│
+  │                         │                         │◄── 200 {userId:42} ───│
+  │◄── 200 face-match page ─┤◄────────────────────────│                       │
+```
+
+- The Java app stores sessions server-side; the browser carries only the `JSESSIONID` cookie.
+- Because both apps are under the same public domain, the browser sends `JSESSIONID` to the Node app too.
+- The Node app validates the cookie via a back-channel HTTP call (Tomcat ↔ Node, same host, loopback).
+- If the session is invalid/absent, the user is redirected to the main app login page.
+
+---
+
+## Project structure
+
+```
+facematch/
+├── server.js          – Express entry point
+├── views/
+│   └── index.ejs      – Protected face-match page
+├── .env.example       – Environment variable template
+├── package.json
+└── README.md
+```
+
+The complementary JSP file lives in the main app:
+
+```
+admin/pg/checkSession.jsp   – Returns {"authenticated":true,"userId":N} or 401
+```
+
+---
+
+## Setup
+
+```bash
+cd facematch
+npm install
+cp .env.example .env
+# edit .env as needed
+npm start
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `3001` | Port this app listens on |
+| `PUBLIC_BASE` | `/face_match` | URL prefix in the reverse proxy |
+| `JAVA_APP_INTERNAL_URL` | `http://localhost:8080` | Internal URL of the Tomcat app |
+| `LOGIN_URL` | `https://www.regalamiunsorriso.it/admin/menu/Menu4.abl` | Login redirect target |
+
+---
+
+## Nginx configuration snippet
+
+Add inside your existing `server {}` block:
+
+```nginx
+# Node facematch app
+location /face_match {
+    proxy_pass         http://127.0.0.1:3001;
+    proxy_http_version 1.1;
+    proxy_set_header   Upgrade $http_upgrade;
+    proxy_set_header   Connection 'upgrade';
+    proxy_set_header   Host $host;
+    proxy_set_header   X-Real-IP $remote_addr;
+    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header   X-Forwarded-Proto $scheme;
+    proxy_cache_bypass $http_upgrade;
+}
+
+# Protect the session validation endpoint – block external access
+location = /admin/pg/checkSession.jsp {
+    allow 127.0.0.1;
+    deny  all;
+    # continue to Tomcat proxy as normal
+    proxy_pass http://127.0.0.1:8080;
+}
+```
+
+> **Important**: the `deny all` rule for `checkSession.jsp` ensures only the Node app
+> (running on the same host) can call the session validation endpoint.