@hivedev/hivesdk 1.0.33 → 1.0.35

package/README.md

@@ -1 +1,739 @@
-Test
+# @hivedev/hivesdk
+
+Software development kit for microservices that integrate with the **Hive** system — a hub-and-spoke platform for educational institutions.
+
+Every service in the Hive ecosystem (NoteHive, and any future service) is built around this SDK. It handles authentication, configuration management, service registration, database connectivity, push notifications, and client-side session management — so each service only has to implement its own domain logic.
+
+---
+
+## Table of Contents
+
+- [Concepts](#concepts)
+- [Installation](#installation)
+- [Server SDK](#server-sdk)
+  - [1. Initialising the Server](#1-initialising-the-server)
+  - [2. Registering the Service](#2-registering-the-service)
+  - [3. Mounting the Middleware](#3-mounting-the-middleware)
+  - [4. Loading Configuration](#4-loading-configuration)
+  - [5. Connecting to the Database](#5-connecting-to-the-database)
+  - [6. Guarding Routes](#6-guarding-routes)
+  - [7. Sending Mail](#7-sending-mail)
+  - [8. Utility Functions](#8-utility-functions)
+  - [Full Server Bootstrap Example](#full-server-bootstrap-example)
+- [Client SDK](#client-sdk)
+  - [1. Loading the Client Bundle](#1-loading-the-client-bundle)
+  - [2. Initialising the Client](#2-initialising-the-client)
+  - [3. Login](#3-login)
+  - [4. Checking Login State](#4-checking-login-state)
+  - [Full Client Bootstrap Example](#full-client-bootstrap-example)
+- [Enumerations](#enumerations)
+- [Environment Variables Reference](#environment-variables-reference)
+- [How HivePortal Fits In](#how-hiveportal-fits-in)
+- [Known Limitations](#known-limitations)
+
+---
+
+## Concepts
+
+**HivePortal** is the central hub. It owns all user accounts, sessions, permissions, and service registry. Every microservice is a spoke — it delegates all authentication and configuration to HivePortal via this SDK.
+
+**Service registration** is a two-step process:
+1. The service announces itself to HivePortal with its name and local/remote URLs.
+2. HivePortal administrators approve it. Once approved, HivePortal sends back an encrypted configuration payload containing database credentials, Firebase credentials, permissions, and SMTP credentials.
+
+**Configuration** is stored encrypted on disk (AES-256-CBC, key derived via scrypt from `SERVER_PASSWORD`). It is decrypted at startup and cached in `process.env`. This means credentials never sit on disk in plaintext.
+
+**Authentication** is always proxied. A service never validates a session token itself — it forwards the check to HivePortal and acts on the response.
+
+---
+
+## Installation
+
+```bash
+npm install @hivedev/hivesdk
+```
+
+The SDK ships three pre-built files:
+- `hive-server.js` — ESM bundle for Node.js backends
+- `hive-server.cjs` — CommonJS bundle for Node.js backends
+- `hive-client.js` — ESM bundle for browser frontends
+
+Import paths:
+
+```js
+// Server-side (ESM)
+import { initServer, registerService } from "@hivedev/hivesdk/server";
+
+// Client-side (browser, via a script tag or bundler)
+import { initClient, login } from "@hivedev/hivesdk/client";
+```
+
+---
+
+## Server SDK
+
+### 1. Initialising the Server
+
+Call `initServer` once at the very start of your service, before anything else. It sets the service's identity and resolves the server password.
+
+```js
+import { initServer } from "@hivedev/hivesdk/server";
+
+await initServer({
+    serviceName: "NoteHive",       // Must match the name registered in HivePortal
+    servicePort: 49161,            // The port this service listens on
+    remoteUrl: "",                 // Public-facing URL if accessible from outside LAN, empty string if LAN-only
+    serverPassword: ""             // Optional — see password resolution below
+});
+```
+
+**Password resolution order:**
+
+1. The `serverPassword` argument, if provided.
+2. The `SERVER_PASSWORD` environment variable, if set.
+3. An interactive terminal prompt, if neither of the above is available — it will ask the user to create a password on first run, or enter their existing password on subsequent runs.
+
+The password is used as the encryption key for all `.dat` configuration files. Losing it means losing access to the stored configuration.
+
+> **Important:** `initServer` must only be called once. Calling it a second time is a no-op with a console warning. In a clustered setup, call it only from the primary process.
+
+---
+
+### 2. Registering the Service
+
+After `initServer`, call `registerService` to announce this service to HivePortal and receive configuration.
+
+```js
+import { registerService } from "@hivedev/hivesdk/server";
+
+await registerService();
+```
+
+What this does internally:
+
+1. Sets the service's local URL (`http://<hostIp>:<servicePort>`) and remote URL in the internal registry.
+2. POSTs to HivePortal's `/RegisterService` endpoint.
+3. If HivePortal accepts the registration request, begins polling HivePortal's `/Configuration` endpoint every 2 seconds.
+4. Once a Hive administrator approves the service in HivePortal, the configuration payload is received, decrypted, and saved to disk via `saveConfiguration`.
+
+**On first run**, the terminal will show:
+
+```
+Registering service...
+Service registration hasn't been approved yet. Please contact administrators!
+Service registration hasn't been approved yet. Please contact administrators!
+...
+Configuration received.
+Saving configuration...
+Service registered.
+```
+
+Once registered and approved, subsequent startups will load configuration from disk directly via `loadConfiguration` and will not need to go through this polling process again, unless credentials change.
+
+> In a clustered setup (e.g. Node.js `cluster` module), call `registerService` only from the primary process, after a short delay to allow workers to start up first.
+
+```js
+import cluster from "cluster";
+import os from "os";
+
+if (cluster.isPrimary)
+{
+    await initServer({ serviceName: "NoteHive", servicePort: 49161, remoteUrl: "" });
+
+    setTimeout(async () =>
+    {
+        await registerService();
+    }, 3000);
+
+    for (let i = 0; i < os.cpus().length; i++)
+    {
+        cluster.fork({ ...process.env });
+    }
+}
+else
+{
+    // Start your HTTP server in workers
+}
+```
+
+---
+
+### 3. Mounting the Middleware
+
+`handleHiveRequests` is an Express-compatible middleware that intercepts all Hive-related routes. Mount it before your own route handlers.
+
+```js
+import express from "express";
+import { handleHiveRequests } from "@hivedev/hivesdk/server";
+
+const app = express();
+
+app.use(express.json());
+app.use(cookieParser());
+app.use(handleHiveRequests);   // Must come before your own routes
+
+// Your own routes go here
+app.get("/my-route", (request, response) => { ... });
+```
+
+**Routes handled automatically by this middleware:**
+
+| Method | Route | What it does |
+|--------|-------|--------------|
+| `POST` | `/Login` | Proxies login credentials to HivePortal, sets session cookie and/or `x-session-token` header |
+| `POST` | `/Logout` | Proxies logout to HivePortal, clears session |
+| `GET` | `/ServiceUrls` | Returns local or remote URL for a named service |
+| `POST` | `/IsLoggedIn` | Checks if the current session is valid with HivePortal |
+| `POST` | `/IsLoggedInWithPermission` | Checks session validity and a specific permission |
+| `POST` | `/SaveUserFilter` | Saves a user-defined data filter (requires `FILTER_OPERATIONS` permission) |
+| `POST` | `/PushNotificationToken` | Registers a push notification token for the current device |
+| `GET` | `/hive-client.js` | Serves the built client-side SDK bundle |
+
+You do not need to implement any of these routes yourself. All of them are handled and proxied to HivePortal automatically.
+
+---
+
+### 4. Loading Configuration
+
+On startup (after `initServer`), call `loadConfiguration` to decrypt and load credentials from disk into `process.env`.
+
+```js
+import { loadConfiguration } from "@hivedev/hivesdk/server";
+
+await loadConfiguration();
+```
+
+This populates the following environment variables (only those with saved `.dat` files are loaded):
+
+| Variable | Contents |
+|----------|----------|
+| `FIREBASE_ADMIN_CREDENTIALS` | JSON string of Firebase Admin SDK credentials |
+| `DATABASE_CREDENTIALS` | JSON string of database credentials, keyed by service name |
+| `PERMISSIONS` | JSON string of permission definitions |
+| `SMTP_CREDENTIALS` | JSON string of SMTP credentials |
+| `SMTP_PASSWORD` | Extracted SMTP password, ready for use in `nodemailer` |
+
+It also calls `DatabaseConnector.setCredentials` internally using the credentials stored under your service's name, so the database is ready to connect after this call.
+
+If a `.dat` file does not exist yet (e.g. first run before registration), that credential is simply skipped.
+
+> You should call `loadConfiguration` before `registerService`. If no configuration files exist yet, it will silently skip them. Once `registerService` completes, the files will be written to disk, and `loadConfiguration` will populate everything on the next startup.
+
+---
+
+### 5. Connecting to the Database
+
+The SDK includes a MongoDB connector. After `loadConfiguration`, call `DatabaseConnector.connect()` to establish the connection.
+
+```js
+import DatabaseConnector from "@hivedev/hivesdk/server";
+
+const connected = await DatabaseConnector.connect();
+
+if (!connected)
+{
+    console.error("Failed to connect to database.");
+    process.exit(1);
+}
+
+// DatabaseConnector.databaseObject is now a live Mongo db instance
+const collection = DatabaseConnector.databaseObject.collection("my_collection");
+```
+
+`DatabaseConnector` is not exported from `server.js` directly — you access it from its own path within the SDK. If you do not call `loadConfiguration` first, `DatabaseConnector.connect()` will attempt to call it automatically.
+
+**Disconnecting:**
+
+```js
+await DatabaseConnector.disconnect();
+```
+
+---
+
+### 6. Guarding Routes
+
+Use `isLoggedIn` and `isLoggedInWithPermission` to protect your own route handlers. Both functions accept the request and response objects and a boolean `bSendResponse` flag.
+
+When `bSendResponse` is `false`, the functions return a boolean and leave the response untouched — use this when you need to guard logic inside a handler.
+
+When `bSendResponse` is `true`, the functions write the result directly to the response — this is used internally by `handleHiveRequests` for the `/IsLoggedIn` and `/IsLoggedInWithPermission` endpoints.
+
+**Guarding a route with login check:**
+
+```js
+import { isLoggedIn } from "@hivedev/hivesdk/server";
+
+app.get("/my-protected-route", async (request, response) =>
+{
+    const loggedIn = await isLoggedIn(request, response, false);
+
+    if (!loggedIn)
+    {
+        response.statusCode = 401;
+        response.end("Unauthorized");
+        return;
+    }
+
+    response.end("Here is your protected data.");
+});
+```
+
+**Guarding a route with a permission check:**
+
+The permission name must be set on `request.body.permissionName` before calling `isLoggedInWithPermission`.
+
+```js
+import { isLoggedInWithPermission } from "@hivedev/hivesdk/server";
+
+app.post("/admin-action", async (request, response) =>
+{
+    request.body.permissionName = "ADMIN_OPERATIONS";
+
+    const permitted = await isLoggedInWithPermission(request, response, false);
+
+    if (!permitted)
+    {
+        response.statusCode = 403;
+        response.end("Forbidden");
+        return;
+    }
+
+    response.end("Admin action performed.");
+});
+```
+
+Both functions handle **session refresh transparently** — if HivePortal signals that the session token should be refreshed, a new cookie and/or `x-session-token` header is set automatically before your handler continues.
+
+---
+
+### 7. Sending Mail
+
+```js
+import { sendMail } from "@hivedev/hivesdk/server";
+
+await sendMail(
+    "sender@yourdomain.com",
+    "recipient@example.com",
+    "Subject line here",
+    "<p>HTML body here</p>"
+);
+```
+
+Uses Gmail SMTP via nodemailer. The SMTP password is read from `process.env.SMTP_PASSWORD`, which is populated automatically by `loadConfiguration`. The sender Gmail address is currently hardcoded in `SendMail.js` — change it there if needed.
+
+---
+
+### 8. Utility Functions
+
+All utilities are exported from `@hivedev/hivesdk/server`.
+
+**`getAppDataDirectory()`**
+
+Returns the platform-appropriate data directory for your service, creating it if it doesn't exist. On Windows this is `%APPDATA%\<ServiceName>`, on macOS `~/Library/Application Support/<ServiceName>`, on Linux `~/.config/<ServiceName>`.
+
+```js
+import { getAppDataDirectory } from "@hivedev/hivesdk/server";
+
+const dataDir = getAppDataDirectory();
+// e.g. "/home/user/.config/NoteHive"
+```
+
+**`getHostIp()`**
+
+Returns the first non-loopback IPv4 address of the host machine. Used internally by `registerService` to build the local service URL.
+
+```js
+import { getHostIp } from "@hivedev/hivesdk/server";
+
+const ip = getHostIp(); // e.g. "192.168.1.42"
+```
+
+**`findService(serviceName)`**
+
+Discovers another Hive service on the LAN via UDP broadcast to port 49153. Returns an object with `{ name, urls: { local, remote } }` or `null` if not found.
+
+```js
+import { findService } from "@hivedev/hivesdk/server";
+
+const service = await findService("NoteHive");
+
+if (service)
+{
+    console.log(service.urls.local);  // "http://192.168.1.42:49161"
+}
+```
+
+Requires `HIVE_PORTAL_LAN_IP` environment variable to be set. If not set, returns a default localhost URL.
+
+**`extractConfigurationForService()`**
+
+Parses `process.env` and returns the configuration as structured objects, extracting the correct database credentials for the current service name.
+
+```js
+import { extractConfigurationForService } from "@hivedev/hivesdk/server";
+
+const { firebaseAdminCredentials, databaseCredentials, permissions, smtpCredentials } = extractConfigurationForService();
+```
+
+**`encryptAndStoreFile(data, fullPath, password)`**
+
+Encrypts a string or Buffer with AES-256-CBC and writes it to disk.
+
+```js
+import { encryptAndStoreFile } from "@hivedev/hivesdk/server";
+
+await encryptAndStoreFile("my secret data", "/path/to/file.dat", process.env.SERVER_PASSWORD);
+```
+
+**`decryptFileWithPassword(fullPath, password)`**
+
+Reads and decrypts an encrypted `.dat` file. Returns the decrypted string, or `null` on failure.
+
+```js
+import { decryptFileWithPassword } from "@hivedev/hivesdk/server";
+
+const contents = await decryptFileWithPassword("/path/to/file.dat", process.env.SERVER_PASSWORD);
+```
+
+**`saveConfiguration(configurationObject)` / `loadConfiguration()`**
+
+Normally called automatically by `registerService` and during startup respectively. Available for manual use if needed.
+
+```js
+import { saveConfiguration, loadConfiguration } from "@hivedev/hivesdk/server";
+
+// Save a configuration object (any subset of keys is valid — only present keys are written)
+await saveConfiguration({
+    databaseCredentials: { NoteHive: { host: "127.0.0.1", username: "admin", password: "pass", name: "notehive" } },
+    smtpCredentials: { password: "smtp-password" }
+});
+
+// Load configuration from disk into process.env
+await loadConfiguration();
+```
+
+---
+
+### Full Server Bootstrap Example
+
+This is the recommended startup sequence for any Hive microservice.
+
+```js
+import express from "express";
+import cookieParser from "cookie-parser";
+import cluster from "cluster";
+import os from "os";
+import { handleHiveRequests, initServer, registerService, loadConfiguration } from "@hivedev/hivesdk/server";
+import DatabaseConnector from "./node_modules/@hivedev/hivesdk/DatabaseConnector.js";
+
+const SERVICE_NAME = "NoteHive";
+const SERVICE_PORT = 49161;
+
+const app = express();
+
+app.use(express.json());
+app.use(cookieParser());
+app.use(handleHiveRequests);
+
+// Your own routes
+app.get("/", (request, response) => response.redirect("/Client/Pages/HomePage.html"));
+
+if (cluster.isPrimary)
+{
+    await initServer({
+        serviceName: SERVICE_NAME,
+        servicePort: SERVICE_PORT,
+        remoteUrl: process.env.REMOTE_URL || ""
+    });
+
+    await loadConfiguration();
+
+    // Delay slightly so workers are ready before registration begins
+    setTimeout(async () =>
+    {
+        await registerService();
+    }, 3000);
+
+    for (let i = 0; i < os.cpus().length; i++)
+    {
+        cluster.fork({ ...process.env });
+    }
+
+    cluster.on("exit", (worker) =>
+    {
+        console.log(`Worker ${worker.process.pid} died. Restarting...`);
+        cluster.fork();
+    });
+}
+else
+{
+    await DatabaseConnector.connect();
+
+    app.listen(SERVICE_PORT, () =>
+    {
+        console.log(`Worker ${process.pid} listening on port ${SERVICE_PORT}`);
+    });
+}
+```
+
+---
+
+## Client SDK
+
+The client SDK is a browser bundle. It is automatically served at `/hive-client.js` by the `handleHiveRequests` middleware — you do not need to copy or host the file yourself.
+
+### 1. Loading the Client Bundle
+
+Include the script in your HTML pages:
+
+```html
+<script type="module">
+    import { initClient, login } from "/hive-client.js";
+</script>
+```
+
+Or via a module script tag:
+
+```html
+<script type="module" src="/hive-client.js"></script>
+```
+
+---
+
+### 2. Initialising the Client
+
+Call `initClient` once on page load. It sets up app detection, cookie signalling, and the periodic login state checker.
+
+```js
+import { initClient } from "/hive-client.js";
+
+await initClient({});
+```
+
+`initClient` accepts one optional parameter:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `loginTokenStorageMethod` | `sessionStorageMethod` enum | `HTTP_ONLY_COOKIE` | How session tokens are stored on the client |
+
+In practice, the SDK currently implements the `HTTP_ONLY_COOKIE` path fully. The token is stored in an `httpOnly` cookie set by the server. On native app clients (WebView), it is also sent via the `x-session-token` header since cookies may not be reliable across WebView boundaries.
+
+---
+
+### 3. Login
+
+Call `login()` to open the HivePortal login popup. The SDK handles the entire flow — opening the window, receiving credentials via `postMessage`, posting to `/Login`, and redirecting on success.
+
+```js
+import { login } from "/hive-client.js";
+
+document.getElementById("login-button").addEventListener("click", async () =>
+{
+    await login();
+});
+```
+
+When running inside the native mobile app (detected automatically via `isInApp()`), the login popup is rendered as an inline full-screen iframe overlay instead of a real popup window, since WebViews block `window.open`.
+
+On success, the page redirects to `/`. On failure, the login page itself displays the error.
+
+---
+
+### 4. Checking Login State
+
+`initClient` automatically starts a periodic login check (every 30 seconds by default, clamped between 10 and 60 seconds). Each check fires a `login-state-changed` custom event on the `window` object.
+
+Listen for this event to reactively show or hide UI based on login state:
+
+```js
+window.addEventListener("login-state-changed", (event) =>
+{
+    const isLoggedIn = event.detail;
+
+    if (isLoggedIn)
+    {
+        document.getElementById("dashboard").style.display = "block";
+        document.getElementById("login-prompt").style.display = "none";
+    }
+    else
+    {
+        document.getElementById("dashboard").style.display = "none";
+        document.getElementById("login-prompt").style.display = "block";
+    }
+});
+```
+
+The current login state is also available synchronously at any time via `window.IS_LOGGED_IN`.
+
+```js
+if (window.IS_LOGGED_IN)
+{
+    // Safe to load user-specific content
+}
+```
+
+---
+
+### Full Client Bootstrap Example
+
+A typical HTML page in a Hive service would look like this:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>NoteHive</title>
+</head>
+<body>
+
+<div id="login-prompt">
+    <button id="login-button">Sign In</button>
+</div>
+
+<div id="dashboard" style="display: none;">
+    <h1>Welcome to NoteHive</h1>
+</div>
+
+<script type="module">
+    import { initClient, login } from "/hive-client.js";
+
+    // Initialise the SDK — sets up app detection, cookies, and login polling
+    await initClient({});
+
+    // React to login state changes
+    window.addEventListener("login-state-changed", (event) =>
+    {
+        const isLoggedIn = event.detail;
+        document.getElementById("login-prompt").style.display = isLoggedIn ? "none" : "block";
+        document.getElementById("dashboard").style.display = isLoggedIn ? "block" : "none";
+    });
+
+    // Wire up the login button
+    document.getElementById("login-button").addEventListener("click", async () =>
+    {
+        await login();
+    });
+</script>
+
+</body>
+</html>
+```
+
+---
+
+## Enumerations
+
+The SDK exports several enumerations from the client bundle. These are shared constants used throughout the Hive ecosystem.
+
+**`userPrivileges`** — Numeric privilege levels assigned to users.
+
+| Key | Value |
+|-----|-------|
+| `STUDENT` | 0 |
+| `CLASS_REPRESENTATIVE` | 10 |
+| `STUDENT_COORDINATOR` | 20 |
+| `ASSISTANT` | 30 |
+| `TEACHER` | 40 |
+| `COURSE_COORDINATOR` | 50 |
+| `HEAD_OF_DEPARTMENT` | 70 |
+| `MANAGEMENT` | 80 |
+| `SUPER_USER` | 100 |
+
+**`sessionStorageMethod`** — How session tokens are stored on the client.
+
+| Key | Value |
+|-----|-------|
+| `HTTP_ONLY_COOKIE` | 0 |
+| `LOCAL_STORAGE` | 1 |
+| `SESSION_STORAGE` | 2 |
+
+**`clientConnectionTypeFlags`** — Bitmask flags describing how a client is connected.
+
+| Key | Value |
+|-----|-------|
+| `LAN` | 1 |
+| `REMOTE` | 2 |
+| `SAME_SYSTEM` | 4 |
+| `UNKNOWN` | 8 |
+
+**`appWebViewInteractions`** — Message types exchanged between the web page and the native app WebView layer.
+
+| Key | Value |
+|-----|-------|
+| `REQUEST_NOTIFICATION_TOKEN` | 0 |
+| `BACK_PRESSED` | 1 |
+
+**`approvalTypes`** — Types of approval requests sent to HivePortal administrators.
+
+| Key | Value |
+|-----|-------|
+| `USER_REGISTERATION` | 0 |
+| `SERVICE_REGISTERATION` | 1 |
+
+**`filterTypes`**, **`filterOperators`**, **`userDataFetchFilterComparision`**, **`userFieldTypes`**, **`userFieldFormats`**, **`fileTreeNodeTypes`** — Domain-specific enumerations used for data querying, user field definitions, and file tree structures. Refer to their respective source files for values.
+
+---
+
+## Environment Variables Reference
+
+These variables are either expected to be set externally or are populated by the SDK itself.
+
+| Variable | Set by | Description |
+|----------|--------|-------------|
+| `SERVER_PASSWORD` | External / `setupPassword()` | Master password for encrypting/decrypting config files |
+| `SERVICE_NAME` | `initServer` | Name of this service as registered with HivePortal |
+| `SERVICE_PORT` | `initServer` | Port this service listens on |
+| `REMOTE_URL` | `initServer` | Public-facing URL of this service (empty if LAN-only) |
+| `HIVE_PORTAL_LAN_IP` | External | LAN IP address of HivePortal, used by `findService` for UDP discovery |
+| `FIREBASE_ADMIN_CREDENTIALS` | `loadConfiguration` | JSON string of Firebase Admin credentials |
+| `DATABASE_CREDENTIALS` | `loadConfiguration` | JSON string of database credentials keyed by service name |
+| `PERMISSIONS` | `loadConfiguration` | JSON string of permission definitions |
+| `SMTP_CREDENTIALS` | `loadConfiguration` | JSON string of SMTP credentials |
+| `SMTP_PASSWORD` | `loadConfiguration` | Extracted SMTP password, ready for nodemailer |
+
+---
+
+## How HivePortal Fits In
+
+```
+                          ┌─────────────────────┐
+                          │      HivePortal      │
+                          │  (hub — port 49152)  │
+                          │                      │
+                          │  - User accounts     │
+                          │  - Sessions          │
+                          │  - Permissions       │
+                          │  - Service registry  │
+                          │  - Configuration     │
+                          └────────┬─────────────┘
+                                   │
+              ┌────────────────────┼────────────────────┐
+              │                    │                     │
+   ┌──────────▼──────────┐         │         ┌──────────▼──────────┐
+   │       NoteHive       │         │         │     FutureService   │
+   │   (port 49161)       │   ...   │         │    (port 49162)     │
+   │                      │         │         │                     │
+   │  uses @hivedev/      │         │         │  uses @hivedev/     │
+   │  hivesdk             │         │         │  hivesdk            │
+   └──────────────────────┘         │         └─────────────────────┘
+                                    │
+                         Each service:
+                         1. Calls initServer()
+                         2. Calls loadConfiguration()
+                         3. Calls registerService()
+                         4. Mounts handleHiveRequests
+                         5. Implements own domain logic
+```
+
+Every authentication check a service performs is a proxied call to HivePortal. HivePortal is the single source of truth for all session and permission data. Services only store their own domain data (notes, files, etc.) — nothing related to users or sessions.
+
+---
+
+## Known Limitations
+
+- **`ScheduleServiceUrlUpdate`** — This function is currently a stub and does nothing. It is intended for future use to periodically re-broadcast service URLs to HivePortal (e.g. if the host IP changes).
+- **`loginTokenStorageMethod`** — The `LOCAL_STORAGE` and `SESSION_STORAGE` options in the `sessionStorageMethod` enum are defined but not yet implemented in the client SDK. Only `HTTP_ONLY_COOKIE` (with the `x-session-token` header fallback for app clients) is fully functional.
+- **SMTP sender address** — The sender Gmail address in `SendMail.js` is hardcoded. If your service needs to send mail from a different address, edit `SendMail.js` in the SDK directly.
+- **MongoDB only** — `DatabaseConnector` is built specifically for MongoDB. There is no support for other databases.
+- **Port 27017 only** — The MongoDB port is hardcoded to 27017 in `DatabaseConnector`. Host is configurable via credentials but the port is not.