@hivedev/hivesdk 1.0.35 → 1.0.37

package/README.md

@@ -35,13 +35,13 @@ Every service in the Hive ecosystem (NoteHive, and any future service) is built
 
 ## 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.
+**HivePortal** is the central hub. It owns all user accounts, sessions, permissions, and the 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.
+2. A HivePortal administrator approves 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.
+**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`. 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.
 
@@ -55,19 +55,9 @@ 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-server.cjs` — CJS 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
@@ -77,6 +67,7 @@ import { initClient, login } from "@hivedev/hivesdk/client";
 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
+// ESM
 import { initServer } from "@hivedev/hivesdk/server";
 
 await initServer({
@@ -87,6 +78,18 @@ await initServer({
 });
 ```
 
+```js
+// CJS
+const { initServer } = require("@hivedev/hivesdk/server");
+
+await initServer({
+    serviceName: "NoteHive",
+    servicePort: 49161,
+    remoteUrl: "",
+    serverPassword: ""
+});
+```
+
 **Password resolution order:**
 
 1. The `serverPassword` argument, if provided.
@@ -104,17 +107,25 @@ The password is used as the encryption key for all `.dat` configuration files. L
 After `initServer`, call `registerService` to announce this service to HivePortal and receive configuration.
 
 ```js
+// ESM
 import { registerService } from "@hivedev/hivesdk/server";
 
 await registerService();
 ```
 
+```js
+// CJS
+const { registerService } = require("@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`.
+3. If HivePortal accepts the request, begins polling HivePortal's `/Configuration` endpoint every 2 seconds.
+4. Once an 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:
 
@@ -128,13 +139,41 @@ 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.
+Once registered and approved, subsequent startups load configuration from disk directly via `loadConfiguration` and do not need to poll again, unless credentials change in HivePortal.
 
-> 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.
+> In a clustered setup, call `registerService` only from the primary process, after a short delay to allow workers to start up first.
 
 ```js
+// ESM
 import cluster from "cluster";
 import os from "os";
+import { initServer, registerService } from "@hivedev/hivesdk/server";
+
+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
+}
+```
+
+```js
+// CJS
+const cluster = require("cluster");
+const os = require("os");
+const { initServer, registerService } = require("@hivedev/hivesdk/server");
 
 if (cluster.isPrimary)
 {
@@ -163,7 +202,9 @@ else
 `handleHiveRequests` is an Express-compatible middleware that intercepts all Hive-related routes. Mount it before your own route handlers.
 
 ```js
+// ESM
 import express from "express";
+import cookieParser from "cookie-parser";
 import { handleHiveRequests } from "@hivedev/hivesdk/server";
 
 const app = express();
@@ -172,7 +213,21 @@ 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) => { ... });
+```
+
+```js
+// CJS
+const express = require("express");
+const cookieParser = require("cookie-parser");
+const { handleHiveRequests } = require("@hivedev/hivesdk/server");
+
+const app = express();
+
+app.use(express.json());
+app.use(cookieParser());
+app.use(handleHiveRequests);
+
 app.get("/my-route", (request, response) => { ... });
 ```
 
@@ -184,12 +239,12 @@ app.get("/my-route", (request, response) => { ... });
 | `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` | `/IsLoggedInWithPermission` | Checks session validity and a specific named 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 |
+| `GET` | `/hive-client.js` | Serves the built client-side SDK bundle (see [Client SDK](#client-sdk)) |
 
-You do not need to implement any of these routes yourself. All of them are handled and proxied to HivePortal automatically.
+You do not need to implement any of these routes yourself.
 
 ---
 
@@ -198,12 +253,20 @@ You do not need to implement any of these routes yourself. All of them are handl
 On startup (after `initServer`), call `loadConfiguration` to decrypt and load credentials from disk into `process.env`.
 
 ```js
+// ESM
 import { loadConfiguration } from "@hivedev/hivesdk/server";
 
 await loadConfiguration();
 ```
 
-This populates the following environment variables (only those with saved `.dat` files are loaded):
+```js
+// CJS
+const { loadConfiguration } = require("@hivedev/hivesdk/server");
+
+await loadConfiguration();
+```
+
+This populates the following environment variables (only those with saved `.dat` files on disk are loaded):
 
 | Variable | Contents |
 |----------|----------|
@@ -211,22 +274,23 @@ This populates the following environment variables (only those with saved `.dat`
 | `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` |
+| `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.
+If a `.dat` file does not exist yet (e.g. first run before registration is approved), that credential is silently 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.
+> Call `loadConfiguration` before `registerService`. On first run the files won't exist yet and it will skip gracefully. Once `registerService` completes and the administrator approves it, files are written to disk and will be fully loaded on the next startup.
 
 ---
 
 ### 5. Connecting to the Database
 
-The SDK includes a MongoDB connector. After `loadConfiguration`, call `DatabaseConnector.connect()` to establish the connection.
+After `loadConfiguration`, use `DatabaseConnector` to establish a MongoDB connection.
 
 ```js
-import DatabaseConnector from "@hivedev/hivesdk/server";
+// ESM — import directly from the SDK's built file
+import DatabaseConnector from "./node_modules/@hivedev/hivesdk/DatabaseConnector.js";
 
 const connected = await DatabaseConnector.connect();
 
@@ -236,11 +300,26 @@ if (!connected)
     process.exit(1);
 }
 
-// DatabaseConnector.databaseObject is now a live Mongo db instance
+// DatabaseConnector.databaseObject is now a live MongoDB 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.
+```js
+// CJS
+const DatabaseConnector = require("./node_modules/@hivedev/hivesdk/DatabaseConnector.js");
+
+const connected = await DatabaseConnector.connect();
+
+if (!connected)
+{
+    console.error("Failed to connect to database.");
+    process.exit(1);
+}
+
+const collection = DatabaseConnector.databaseObject.collection("my_collection");
+```
+
+If `loadConfiguration` was not called first, `DatabaseConnector.connect()` will attempt to call it automatically.
 
 **Disconnecting:**
 
@@ -252,15 +331,18 @@ 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.
+Use `isLoggedIn` and `isLoggedInWithPermission` to protect your own route handlers. Both accept the request and response objects and a `bSendResponse` boolean.
 
-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 `false`, the function returns a boolean and leaves the response untouched — use this to guard logic inside your own handlers.
 
-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.
+When `bSendResponse` is `true`, the function writes the result directly to the response — used internally by `handleHiveRequests` for the `/IsLoggedIn` and `/IsLoggedInWithPermission` endpoints.
+
+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.
 
-**Guarding a route with login check:**
+**Guarding a route with a login check:**
 
 ```js
+// ESM
 import { isLoggedIn } from "@hivedev/hivesdk/server";
 
 app.get("/my-protected-route", async (request, response) =>
@@ -278,11 +360,31 @@ app.get("/my-protected-route", async (request, response) =>
 });
 ```
 
+```js
+// CJS
+const { isLoggedIn } = require("@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
+// ESM
 import { isLoggedInWithPermission } from "@hivedev/hivesdk/server";
 
 app.post("/admin-action", async (request, response) =>
@@ -302,13 +404,33 @@ app.post("/admin-action", async (request, response) =>
 });
 ```
 
-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.
+```js
+// CJS
+const { isLoggedInWithPermission } = require("@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.");
+});
+```
 
 ---
 
 ### 7. Sending Mail
 
 ```js
+// ESM
 import { sendMail } from "@hivedev/hivesdk/server";
 
 await sendMail(
@@ -319,7 +441,19 @@ await sendMail(
 );
 ```
 
-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.
+```js
+// CJS
+const { sendMail } = require("@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` — edit it there if needed.
 
 ---
 
@@ -332,83 +466,141 @@ All utilities are exported from `@hivedev/hivesdk/server`.
 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
+// ESM
 import { getAppDataDirectory } from "@hivedev/hivesdk/server";
-
 const dataDir = getAppDataDirectory();
 // e.g. "/home/user/.config/NoteHive"
 ```
 
+```js
+// CJS
+const { getAppDataDirectory } = require("@hivedev/hivesdk/server");
+const dataDir = getAppDataDirectory();
+```
+
 **`getHostIp()`**
 
-Returns the first non-loopback IPv4 address of the host machine. Used internally by `registerService` to build the local service URL.
+Returns the first non-loopback IPv4 address of the host machine.
 
 ```js
+// ESM
 import { getHostIp } from "@hivedev/hivesdk/server";
-
 const ip = getHostIp(); // e.g. "192.168.1.42"
 ```
 
+```js
+// CJS
+const { getHostIp } = require("@hivedev/hivesdk/server");
+const ip = getHostIp();
+```
+
 **`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.
+Discovers another Hive service on the LAN via UDP to port 49153. Returns `{ name, urls: { local, remote } }` or `null` if not found within 3 seconds. Requires `HIVE_PORTAL_LAN_IP` environment variable to be set.
 
 ```js
+// ESM
 import { findService } from "@hivedev/hivesdk/server";
 
 const service = await findService("NoteHive");
 
 if (service)
 {
-    console.log(service.urls.local);  // "http://192.168.1.42:49161"
+    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.
+```js
+// CJS
+const { findService } = require("@hivedev/hivesdk/server");
+
+const service = await findService("NoteHive");
+
+if (service)
+{
+    console.log(service.urls.local);
+}
+```
 
 **`extractConfigurationForService()`**
 
 Parses `process.env` and returns the configuration as structured objects, extracting the correct database credentials for the current service name.
 
 ```js
+// ESM
 import { extractConfigurationForService } from "@hivedev/hivesdk/server";
 
 const { firebaseAdminCredentials, databaseCredentials, permissions, smtpCredentials } = extractConfigurationForService();
 ```
 
+```js
+// CJS
+const { extractConfigurationForService } = require("@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.
+Encrypts a string or Buffer with AES-256-CBC and writes it to disk. Creates the directory if it doesn't exist.
 
 ```js
+// ESM
 import { encryptAndStoreFile } from "@hivedev/hivesdk/server";
 
 await encryptAndStoreFile("my secret data", "/path/to/file.dat", process.env.SERVER_PASSWORD);
 ```
 
+```js
+// CJS
+const { encryptAndStoreFile } = require("@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
+// ESM
 import { decryptFileWithPassword } from "@hivedev/hivesdk/server";
 
 const contents = await decryptFileWithPassword("/path/to/file.dat", process.env.SERVER_PASSWORD);
 ```
 
+```js
+// CJS
+const { decryptFileWithPassword } = require("@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.
+Normally called automatically by `registerService` and during startup respectively. Available for manual use if needed. `saveConfiguration` only writes keys that are present in the object — missing keys do not overwrite existing files.
 
 ```js
+// ESM
 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();
+```
+
+```js
+// CJS
+const { saveConfiguration, loadConfiguration } = require("@hivedev/hivesdk/server");
+
+await saveConfiguration({
+    databaseCredentials: { NoteHive: { host: "127.0.0.1", username: "admin", password: "pass", name: "notehive" } },
+    smtpCredentials: { password: "smtp-password" }
+});
+
 await loadConfiguration();
 ```
 
@@ -419,6 +611,7 @@ await loadConfiguration();
 This is the recommended startup sequence for any Hive microservice.
 
 ```js
+// ESM
 import express from "express";
 import cookieParser from "cookie-parser";
 import cluster from "cluster";
@@ -435,7 +628,6 @@ 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)
@@ -448,7 +640,6 @@ if (cluster.isPrimary)
 
     await loadConfiguration();
 
-    // Delay slightly so workers are ready before registration begins
     setTimeout(async () =>
     {
         await registerService();
@@ -476,33 +667,109 @@ else
 }
 ```
 
+```js
+// CJS
+const express = require("express");
+const cookieParser = require("cookie-parser");
+const cluster = require("cluster");
+const os = require("os");
+const { handleHiveRequests, initServer, registerService, loadConfiguration } = require("@hivedev/hivesdk/server");
+const DatabaseConnector = require("./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);
+
+app.get("/", (request, response) => response.redirect("/Client/Pages/HomePage.html"));
+
+(async () =>
+{
+    if (cluster.isPrimary)
+    {
+        await initServer({
+            serviceName: SERVICE_NAME,
+            servicePort: SERVICE_PORT,
+            remoteUrl: process.env.REMOTE_URL || ""
+        });
+
+        await loadConfiguration();
+
+        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.
+The client SDK is a browser-only ESM bundle (`hive-client.js`). There is no CJS variant — it runs exclusively in the browser.
 
 ### 1. Loading the Client Bundle
 
-Include the script in your HTML pages:
+The `handleHiveRequests` middleware automatically serves the client bundle at `/hive-client.js` by reading it from `node_modules/@hivedev/hivesdk/hive-client.js`. **This works as long as your service's Node.js process is started from the root of the package** (i.e. the directory that contains `node_modules`), which is the recommended setup.
 
-```html
-<script type="module">
-    import { initClient, login } from "/hive-client.js";
-</script>
+If your service is started from a different working directory, the automatic route will fail to locate the file. In that case, serve it yourself:
+
+```js
+import path from "path";
+import { createReadStream } from "fs";
+
+app.get("/hive-client.js", (request, response) =>
+{
+    const filePath = path.join("/absolute/path/to/node_modules/@hivedev/hivesdk/hive-client.js");
+    response.setHeader("Content-Type", "application/javascript");
+    createReadStream(filePath).pipe(response);
+});
 ```
 
-Or via a module script tag:
+Include it in your HTML pages as a module script:
 
 ```html
 <script type="module" src="/hive-client.js"></script>
 ```
 
+Or import from it in another module script on the page:
+
+```html
+<script type="module">
+    import { login } from "/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.
+Call `initClient` once on page load. It sets up in-app WebView detection, signals cookie support to the server, and starts the periodic login state checker.
 
 ```js
 import { initClient } from "/hive-client.js";
@@ -516,54 +783,45 @@ await initClient({});
 |-----------|------|---------|-------------|
 | `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.
+Call `login()` to open the HivePortal login page. The SDK handles the entire flow — the popup opens, the user enters their credentials, and on success the page reloads at `/`.
 
 ```js
 import { login } from "/hive-client.js";
 
-document.getElementById("login-button").addEventListener("click", async () =>
-{
-    await login();
-});
+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`.
+You can wire it to any element:
 
-On success, the page redirects to `/`. On failure, the login page itself displays the error.
+```js
+import { login } from "/hive-client.js";
+
+document.getElementById("login-button").addEventListener("click", login);
+```
+
+When running inside the native mobile app (detected automatically), the login popup is rendered as a full-screen iframe overlay instead of a real popup window, since WebViews block `window.open`.
 
 ---
 
 ### 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:
+`initClient` automatically starts a periodic login check (every 30 seconds, clamped between 10 and 60 seconds). Each check fires a `login-state-changed` custom event on `window`.
 
 ```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";
-    }
+    document.getElementById("login-prompt").style.display = isLoggedIn ? "none" : "block";
+    document.getElementById("dashboard").style.display = isLoggedIn ? "block" : "none";
 });
 ```
 
-The current login state is also available synchronously at any time via `window.IS_LOGGED_IN`.
+The current login state is also available synchronously at any time:
 
 ```js
 if (window.IS_LOGGED_IN)
@@ -576,8 +834,6 @@ if (window.IS_LOGGED_IN)
 
 ### Full Client Bootstrap Example
 
-A typical HTML page in a Hive service would look like this:
-
 ```html
 <!DOCTYPE html>
 <html lang="en">
@@ -598,10 +854,8 @@ A typical HTML page in a Hive service would look like this:
 <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;
@@ -609,11 +863,7 @@ A typical HTML page in a Hive service would look like this:
         document.getElementById("dashboard").style.display = isLoggedIn ? "block" : "none";
     });
 
-    // Wire up the login button
-    document.getElementById("login-button").addEventListener("click", async () =>
-    {
-        await login();
-    });
+    document.getElementById("login-button").addEventListener("click", login);
 </script>
 
 </body>
@@ -624,7 +874,7 @@ A typical HTML page in a Hive service would look like this:
 
 ## Enumerations
 
-The SDK exports several enumerations from the client bundle. These are shared constants used throughout the Hive ecosystem.
+The SDK exports several enumerations used throughout the Hive ecosystem.
 
 **`userPrivileges`** — Numeric privilege levels assigned to users.
 
@@ -677,17 +927,15 @@ The SDK exports several enumerations from the client bundle. These are shared co
 
 ## 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 |
+| `HIVE_PORTAL_LAN_IP` | External | LAN IP 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 |
+| `DATABASE_CREDENTIALS` | `loadConfiguration` | JSON string of DB 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 |
@@ -711,29 +959,29 @@ These variables are either expected to be set externally or are populated by the
               ┌────────────────────┼────────────────────┐
               │                    │                     │
    ┌──────────▼──────────┐         │         ┌──────────▼──────────┐
-   │       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.
+   │       NoteHive       │        ...        │    FutureService    │
+   │   (port 49161)       │                   │    (port 49162)     │
+   │                      │                   │                     │
+   │  uses @hivedev/      │                   │  uses @hivedev/     │
+   │  hivesdk             │                   │  hivesdk            │
+   └──────────────────────┘                   └─────────────────────┘
+
+   Each service:
+     1. initServer()          — establish identity and password
+     2. loadConfiguration()   — decrypt credentials from disk
+     3. registerService()     — announce to HivePortal, receive config
+     4. handleHiveRequests    — mount middleware
+     5. Own domain logic      — notes, files, etc.
+```
+
+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 and serve their own domain data.
 
 ---
 
 ## 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.
+- **`ScheduleServiceUrlUpdate`** — This function is currently a stub and does nothing. It is intended for future use to periodically re-broadcast service URLs to HivePortal if the host IP changes.
+- **`loginTokenStorageMethod`** — The `LOCAL_STORAGE` and `SESSION_STORAGE` options in the `sessionStorageMethod` enum are defined but not yet implemented. Only `HTTP_ONLY_COOKIE` (with the `x-session-token` header fallback for native app clients) is fully functional.
+- **SMTP sender address** — The sender Gmail address in `SendMail.js` is hardcoded. Edit it in the SDK source if your service needs a different address.
+- **MongoDB only** — `DatabaseConnector` is built for MongoDB. There is no support for other databases.
+- **MongoDB port hardcoded** — The MongoDB port is hardcoded to `27017`. The host is configurable via credentials but the port is not.

package/hive-server.cjs

@@ -619,7 +619,7 @@ async function initServer({ serviceName, servicePort, remoteUrl, serverPassword
   if (!serverPassword) {
     serverPassword = process.env.SERVER_PASSWORD;
     if (!serverPassword) {
-      serverPassword = await HiveServerGlobals_default.setupPassword();
+      throw new Error("Server password is not provided. Please set the SERVER_PASSWORD environment variable.");
     }
   }
   HiveServerGlobals_default.initialize({ serviceName, servicePort, remoteUrl });

package/hive-server.js

@@ -592,7 +592,7 @@ async function initServer({ serviceName, servicePort, remoteUrl, serverPassword
   if (!serverPassword) {
     serverPassword = process.env.SERVER_PASSWORD;
     if (!serverPassword) {
-      serverPassword = await HiveServerGlobals_default.setupPassword();
+      throw new Error("Server password is not provided. Please set the SERVER_PASSWORD environment variable.");
     }
   }
   HiveServerGlobals_default.initialize({ serviceName, servicePort, remoteUrl });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hivedev/hivesdk",
   "type": "module",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "scripts": {