Security Module (XEMS)

XEMS Configuration Reference

Hardware-bound, cryptographically encrypted persistent session vault for XyPriss applications.

Field Revision Notice — XyPriss 9.12.60 (XEMS Core 1.1.22)

This major architectural revision reflects extensive real-world testing and production feedback. Available starting from XyPriss 9.12.60 (powered by XEMS Core v1.1.22).

Unified Configuration (server.xems)

XEMS operates as a unified, hardware-bound vault store. All configuration options are specified directly under the server.xems object in your server definition or xypriss.config.ts.

typescript

import { createServer } from "xypriss";

const app = createServer({
    server: {
        xems: {
            enable: true,
            path: __sys__.path.resolve("vault.xems"), // Native __sys__.path API
            secret: process.env.XEMS_SECRET!,         // Mandatory (min 32 bytes)
            ttl: "7d",                                // Max 7 days retention
            autoRotation: "1m",                       // "1m", "5m", "10s", or false
            gracePeriod: 15000,                       // 15 seconds grace window
            cookieName: "xems_token",
            cookieOptions: {
                httpOnly: true,
                secure: process.env.NODE_ENV === "production",
                sameSite: "Strict",
            },
        },
    },
});

Recommended: Native __sys__.path API

Prefer XyPriss's built-in __sys__.path API over Node.js import path from "path" for cross-platform, zero-dependency path resolutions.

Configuration Parameters

Parameter	Type	Required	Default	Description
enable	boolean	No	true	Enables or disables the native XEMS sidecar and session middleware.
path	string	Yes	—	Absolute path to the encrypted vault file (must end with `.xems`).
secret	string	Yes	—	32-byte (256-bit) master encryption secret.
sandbox	string	No	"xypriss.internal.session.xems"	Default namespace partition for isolated session storage.
ttl	string	No	"7d"	Default Time-To-Live duration (e.g. `"15m"`, `"1h"`, `"7d"`). Max 7 days.
autoRotation	boolean \| string	No	false	Session token sliding rotation window (`false`, `"1m"`, `"5m"`, `"10s"`).
gracePeriod	number	No	15000	Milliseconds (ms) previous token remains valid for concurrent read access during rotation. Max 55000ms.
cookieName	string	No	"xems_token"	Name of the `HttpOnly` cookie issued to the browser.
headerName	string	No	"x-xypriss-token"	Name of the HTTP request/response header for API clients.
attachTo	string	No	"session"	Property on `req` where decrypted session payload is stored (accessible via `req.session`).
cookieOptions	CookieOptions	No	Strict HttpOnly	Standard RFC 6265 cookie attributes (`httpOnly`, `secure`, `sameSite`).
resources	{ cacheSize?: number }	No	{ cacheSize: 64 }	RAM buffer allocation in megabytes (MB) for fast in-memory vault indexing.

Cryptographic Security Architecture

The native Go sidecar enforces Dual Hardware + Filesystem Path Binding. The master encryption key is computed at runtime via:

MasterKey = SHA-256(HWID ∥ Secret ∥ AbsoluteVaultPath)

Hardware & Path Binding Notice

The .xems vault is mathematically tied to both the physical machine hardware (CPU/Motherboard UUID) and its exact absolute path. Copying the file to another server or renaming/moving its parent directory renders the vault permanently unreadable.

High-Concurrency Rotation (SPA Protection)

In Single-Page Applications (React, Vue, Svelte), page refreshes trigger multiple simultaneous API requests carrying the same session cookie.

1. Sliding Window Rotation

Set autoRotation: "1m" or "5m" to rotate session tokens safely across sliding intervals.

2. Grace Period Overlap

With gracePeriod: 15000 (15 seconds), incoming parallel requests using the previous token remain valid and automatically receive the newly rotated session token.

XEMS Tutorial

Learn how to implement high-security authentication flows with XEMS.