Add whoami function (#231)

### Description

Add a whoami() function to proxy.mjs. It can be used to access the
claims from the user's identity token.

### Type of change

* [x] New feature
* [ ] Feature improvement
* [ ] Bug fix
* [x] Documentation
* [ ] Cleanup / refactoring
* [ ] Other (please explain)

### How is this change tested ?

* [ ] Unit tests
* [x] Manual tests (explain)
* [ ] Tests are not needed

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: rthellend

proxy/backend-sso.go

@@ -27,6 +27,7 @@ import (
 	"crypto/sha256"
 	_ "embed"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"html/template"
 	"net/http"
@@ -183,6 +184,28 @@ func (be *Backend) serveSSOProxyMJS(w http.ResponseWriter, req *http.Request) {
 
 func (be *Backend) serveSSOStatus(w http.ResponseWriter, req *http.Request) {
 	claims := fromctx.Claims(req.Context())
+
+	if req.Method == http.MethodPost {
+		w.Header().Set("content-type", "application/json")
+		if claims == nil {
+			w.Write([]byte("null\n"))
+			return
+		}
+		out := struct {
+			Name   string         `json:"name,omitempty"`
+			Email  string         `json:"email,omitempty"`
+			Claims map[string]any `json:"claims,omitempty"`
+		}{
+			Claims: claims,
+		}
+		out.Name, _ = claims["name"].(string)
+		out.Email, _ = claims["email"].(string)
+
+		enc := json.NewEncoder(w)
+		enc.SetIndent("", "  ")
+		enc.Encode(out)
+		return
+	}
 	var keys []string
 	for k := range claims {
 		keys = append(keys, k)

proxy/proxy.mjs

@@ -21,11 +21,20 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+/**
+ * Extracts the session ID from the '__tlsproxySid' cookie.
+ * @returns {string} The session ID, or an empty string if not found.
+ */
 function sessionId() {
   const m = document.cookie.match(/__tlsproxySid=([^;]*)(;|$)/);
   return m ? m[1] : '';
 }
 
+/**
+ * @summary Wraps the global fetch() function to automatically add an
+ * x-csrf-token header to all requests.
+ * @description This is a security measure to prevent Cross-Site Request Forgery (CSRF) attacks.
+ */
 const ofetch = window.fetch;
 window.fetch = function(res, opt) {
   if (!opt) {
@@ -38,16 +47,46 @@ window.fetch = function(res, opt) {
   return ofetch(res, opt);
 };
 
+/**
+ * @summary Logs the user out.
+ * @description Sends a POST request to the logout endpoint and then redirects the
+ * browser to the same URL to complete the process.
+ * @returns {Promise<void>}
+ */
 export function logout() {
   return fetch('/.sso/logout', {
     method: 'POST',
   })
   .then(() => window.location = '/.sso/logout');
 }
 
+/**
+ * @summary Fetches information about the currently authenticated user.
+ * @returns {Promise<Object>} A promise that resolves to a JSON object
+ * containing user information.
+ */
+export function whoami() {
+  return fetch('/.sso/', {
+    method: 'POST',
+  }).then(r => {
+    if (!r.ok) {
+      throw new Error(`HTTP error, status: ${r.status}`);
+    }
+    return r.json();
+  });
+}
+
+/** @type {string} The currently active language code (e.g., 'en', 'fr-CA'). */
 let currentLang = 'en';
+/** @type {Object<string, string>} A map of translation keys to their string values for the current language. */
 let langData = {};
 
+/**
+ * @summary Translates a given key into the current language.
+ * @param {string} key The translation key to look up.
+ * @returns {string} The translated string, or a placeholder '###key###' if the
+ * key is not found.
+ */
 export function translate(key) {
   const value = langData[key];
   if (!value) {
@@ -56,6 +95,15 @@ export function translate(key) {
   return value;
 }
 
+/**
+ * @summary Sets the active language by fetching translation data from the server.
+ * @description It takes a list of preferred languages (e.g., from navigator.languages),
+ * expands it to include variants (e.g., 'en-US' -> 'en'), and requests the
+ * best matching translation file from the server. If no match is found, it
+ * defaults to 'en'.
+ * @param {string[]} langs An array of language codes.
+ * @returns {Promise<void>}
+ */
 function setLanguage(langs) {
   let opts = [];
   for (let lang of langs) {
@@ -87,9 +135,23 @@ function setLanguage(langs) {
     });
 }
 
+/**
+ * @summary Applies translations to the current document.
+ * @description This async function performs several steps:
+ * 1. Fetches the appropriate language data by calling setLanguage().
+ * 2. Scans the DOM for all elements with a `tkey` attribute.
+ * 3. Replaces the textContent (or placeholder) of each element with its translation.
+ * 4. Sets the `lang` and `dir` (text direction) attributes on the <html> element.
+ * 5. If any translations were applied and a language selector doesn't exist,
+ *    it dynamically creates and adds a `<select>` element to the page to
+ *    allow users to switch languages.
+ * @param {string} [lang] - An optional language code to force a specific language.
+ * If not provided, it defaults to the browser's `navigator.languages`.
+ */
 async function applyTranslations(lang) {
   await setLanguage(lang?[lang]:navigator.languages);
   let changed = false;
+  // Find all elements with a `tkey` attribute and replace their content.
   document.querySelectorAll('[tkey]').forEach(e => {
     const value = translate(e.getAttribute('tkey'));
     if (e.tagName === 'INPUT' && e.hasAttribute('placeholder')) {
@@ -99,11 +161,13 @@ async function applyTranslations(lang) {
     }
     changed = true;
   });
+  // If translations were applied, update the document's lang and dir.
   if (changed) {
     const html = document.querySelector('HTML');
     html.setAttribute('lang', currentLang);
     html.setAttribute('dir', translate('DIR') === 'rtl' ? 'rtl' : 'ltr');
   }
+  // If translations were applied and no language selector exists, create one.
   if (changed && !document.getElementById('lang-selector')) {
     const b = document.createElement('select');
     b.id = 'lang-selector';
@@ -121,6 +185,7 @@ async function applyTranslations(lang) {
     b.style.zIndex = 10;
     b.style.backgroundColor = 'white';
     document.body.appendChild(b);
+    // Populate the selector with available languages from the server.
     return fetch('/.sso/languages.json').then(r => r.json()).then(r => {
       for (let key in r) {
         const o = document.createElement('option');
@@ -134,4 +199,8 @@ async function applyTranslations(lang) {
   }
 }
 
+/**
+ * Kicks off the translation process once the initial HTML document has been
+ * completely loaded and parsed.
+ */
 document.addEventListener('DOMContentLoaded', () => applyTranslations());

proxy/proxy.mjs.md

@@ -0,0 +1,69 @@
+# `proxy.mjs` - Client-Side Proxy Helper
+
+This JavaScript module provides client-side functionality for HTML pages served by `tlsproxy`. It handles CSRF protection, session management, and internationalization (i18n) dynamically in the user's browser.
+
+## Features
+
+### 1. Automatic CSRF Protection
+
+The script automatically protects against Cross-Site Request Forgery (CSRF) attacks.
+
+- It wraps the standard `window.fetch` function.
+- Before any `fetch` request is sent, it reads the session ID from the `__tlsproxySid` cookie.
+- It then adds the session ID to the request headers as `x-csrf-token`.
+
+This process is automatic. Any page that includes this module will have its `fetch` requests protected.
+
+### 2. Session Management
+
+The module exports functions to manage the user's authentication session.
+
+- **`logout()`**:
+  - Sends a `POST` request to the `/.sso/logout` endpoint to terminate the session on the backend.
+  - Upon success, it redirects the user to the logout page.
+
+- **`whoami()`**:
+  - Sends a `POST` request to the `/.sso/` endpoint.
+  - Returns a promise that resolves with a JSON object containing information about the currently authenticated user.
+
+### 3. Internationalization (i18n)
+
+The script provides dynamic, client-side translation of web pages.
+
+- **Language Detection**: On page load, it detects the user's preferred languages from `navigator.languages`.
+- **Translation Loading**: It fetches the appropriate language file from `/.sso/languages.json` based on the detected language. It has a fallback mechanism to find the best-matching language or default to English (`en`).
+- **Dynamic Translation**:
+  - It scans the document for any HTML elements that have a `tkey` attribute.
+  - It replaces the content (or placeholder text for inputs) of these elements with the translated string corresponding to the `tkey` value.
+  - It sets the `lang` and `dir` (text direction, e.g., `ltr` or `rtl`) attributes on the `<html>` tag.
+- **Language Selector**:
+  - If a language selector element (with `id="lang-selector"`) does not already exist on the page, the script dynamically creates and appends one.
+  - This `<select>` element allows the user to switch languages on the fly. It is populated with all available languages from the backend.
+
+## Usage
+
+This script is intended to be included as a module in HTML pages served by `tlsproxy`, such as the login, logout, or SSO status pages.
+
+```html
+<script type="module">
+  import { logout, whoami } from '/.sso/proxy.mjs';
+
+  // Example: Add a logout button
+  const logoutButton = document.getElementById('logout-btn');
+  logoutButton.addEventListener('click', () => {
+    logout();
+  });
+
+  // Example: Display user's name
+  whoami().then(user => {
+    if (user) {
+      document.getElementById('user-name').textContent = user.name;
+    }
+  }).catch(error => {
+    console.error('Failed to get user info:', error);
+  });
+</script>
+
+<!-- Example of an element that will be translated -->
+<h1 tkey="logout-button">Logout</h1>
+```