@puzzle-ui/session 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# @puzzle-ui/session
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Secure, database-independent session management for Puzzle Auth.
+
+## Features
+
+- Cryptographically secure opaque session tokens.
+- SHA-256 token hashing.
+- Anonymous and authenticated sessions.
+- Idle and absolute expiration.
+- Session rotation and revocation.
+- Session listing and device metadata.
+- Maximum active session policy.
+- Namespaced session data with TTL.
+- Allowlisted anonymous session migration.
+- Secure cookie serialization.
+- Origin validation and CSRF protection.
+
+## Requirements
+
+The storage adapter must support:
+
+- Unique constraints.
+- Conditional writes.
+- Atomic batches.
+
+Session management fails closed when these capabilities are unavailable.
+
+## Installation
+
+```sh
+bun add @puzzle-ui/session
+```
+
+## Initialization
+
+```ts
+import {
+  StorageSessionManager,
+  initializeSessionStorage,
+} from "@puzzle-ui/session";
+
+const sessions = new StorageSessionManager(storage, {
+  lifetime: {
+    idleTimeoutSeconds: 60 * 60 * 24 * 7,
+    absoluteLifetimeSeconds: 60 * 60 * 24 * 30,
+  },
+  maximumSessionsPerUser: 10,
+});
+
+await initializeSessionStorage(storage);
+await sessions.initialize();
+```
+
+## Create an anonymous session
+
+```ts
+const result = await sessions.create({
+  kind: "anonymous",
+  userId: null,
+});
+
+console.log(result.session.id);
+console.log(result.token);
+```
+
+The token must only be delivered through a secure HttpOnly cookie.
+
+## Create an authenticated session
+
+```ts
+const result = await sessions.create({
+  kind: "authenticated",
+  userId: user.id,
+  metadata: {
+    userAgent: request.headers.get("user-agent"),
+  },
+});
+```
+
+## Validate a session
+
+```ts
+const session = await sessions.validate(token);
+
+if (!session) {
+  // Unauthenticated request.
+}
+```
+
+## Rotate a session
+
+```ts
+const rotated = await sessions.rotate({
+  sessionId: session.id,
+});
+```
+
+The old session is revoked as part of the atomic rotation.
+
+## Revoke sessions
+
+```ts
+await sessions.revoke(session.id);
+await sessions.revokeAll(user.id);
+```
+
+## List devices
+
+```ts
+const devices = await sessions.list(user.id, session.id);
+```
+
+## Session data
+
+```ts
+const data = new SessionDataManager(storage, {
+  allowedNamespaces: ["cart", "checkout"],
+});
+
+await data.initialize();
+
+await data.set(
+  session.id,
+  "cart",
+  "items",
+  [{ productId: "product-1", quantity: 2 }],
+  60 * 60,
+);
+
+const cart = await data.get(session.id, "cart", "items");
+```
+
+## Security
+
+- Raw tokens are never persisted.
+- Session validation always checks durable storage.
+- Session expiration is enforced server-side.
+- Anonymous sessions cannot be converted by changing their user ID.
+- Migration creates a new identity-bound session.
+- Session data namespaces must be explicitly allowlisted.
+- Cookie configuration does not expose session tokens to JavaScript.
+- Security-critical operations require atomic storage support.
+  In-memory storage is intended exclusively for development and tests.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sjoerd van Den Berg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/errors/session.errors.cjs

@@ -0,0 +1,47 @@
+// src/errors/session.errors.ts
+var SessionError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "SessionError";
+	}
+};
+var SessionNotFoundError = class extends SessionError {
+	constructor() {
+		super("Session not found or no longer active.", "SESSION_NOT_FOUND");
+		this.name = "SessionNotFoundError";
+	}
+};
+var SessionExpiredError = class extends SessionError {
+	constructor() {
+		super("Session has expired.", "SESSION_EXPIRED");
+		this.name = "SessionExpiredError";
+	}
+};
+var SessionRevokedError = class extends SessionError {
+	constructor() {
+		super("Session has been revoked.", "SESSION_REVOKED");
+		this.name = "SessionRevokedError";
+	}
+};
+var SessionSecurityError = class extends SessionError {
+	constructor(message) {
+		super(message, "SESSION_SECURITY_ERROR");
+		this.name = "SessionSecurityError";
+	}
+};
+var SessionConfigurationError = class extends SessionError {
+	constructor(message) {
+		super(message, "SESSION_CONFIGURATION_ERROR");
+		this.name = "SessionConfigurationError";
+	}
+};
+exports.SessionConfigurationError = SessionConfigurationError;
+exports.SessionError = SessionError;
+exports.SessionExpiredError = SessionExpiredError;
+exports.SessionNotFoundError = SessionNotFoundError;
+exports.SessionRevokedError = SessionRevokedError;
+exports.SessionSecurityError = SessionSecurityError;
+
+//# sourceMappingURL=session.errors.cjs.map

package/dist/errors/session.errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.errors.cjs","names":[],"sources":["../../src/errors/session.errors.ts"],"sourcesContent":["export class SessionError extends Error {\n  constructor(\n    message: string,\n    readonly code: string,\n  ) {\n    super(message);\n    this.name = \"SessionError\";\n  }\n}\n\nexport class SessionNotFoundError extends SessionError {\n  constructor() {\n    super(\"Session not found or no longer active.\", \"SESSION_NOT_FOUND\");\n    this.name = \"SessionNotFoundError\";\n  }\n}\n\nexport class SessionExpiredError extends SessionError {\n  constructor() {\n    super(\"Session has expired.\", \"SESSION_EXPIRED\");\n    this.name = \"SessionExpiredError\";\n  }\n}\n\nexport class SessionRevokedError extends SessionError {\n  constructor() {\n    super(\"Session has been revoked.\", \"SESSION_REVOKED\");\n    this.name = \"SessionRevokedError\";\n  }\n}\n\nexport class SessionSecurityError extends SessionError {\n  constructor(message: string) {\n    super(message, \"SESSION_SECURITY_ERROR\");\n    this.name = \"SessionSecurityError\";\n  }\n}\n\nexport class SessionConfigurationError extends SessionError {\n  constructor(message: string) {\n    super(message, \"SESSION_CONFIGURATION_ERROR\");\n    this.name = \"SessionConfigurationError\";\n  }\n}\n"],"mappings":";AAAA,IAAa,eAAb,cAAkC,MAAM;CAG3B;CAFX,YACE,SACA,MACA;EACA,MAAM,OAAO;EAFJ,KAAA,OAAA;EAGT,KAAK,OAAO;CACd;AACF;AAEA,IAAa,uBAAb,cAA0C,aAAa;CACrD,cAAc;EACZ,MAAM,0CAA0C,mBAAmB;EACnE,KAAK,OAAO;CACd;AACF;AAEA,IAAa,sBAAb,cAAyC,aAAa;CACpD,cAAc;EACZ,MAAM,wBAAwB,iBAAiB;EAC/C,KAAK,OAAO;CACd;AACF;AAEA,IAAa,sBAAb,cAAyC,aAAa;CACpD,cAAc;EACZ,MAAM,6BAA6B,iBAAiB;EACpD,KAAK,OAAO;CACd;AACF;AAEA,IAAa,uBAAb,cAA0C,aAAa;CACrD,YAAY,SAAiB;EAC3B,MAAM,SAAS,wBAAwB;EACvC,KAAK,OAAO;CACd;AACF;AAEA,IAAa,4BAAb,cAA+C,aAAa;CAC1D,YAAY,SAAiB;EAC3B,MAAM,SAAS,6BAA6B;EAC5C,KAAK,OAAO;CACd;AACF"}

package/dist/errors/session.errors.d.cts

@@ -0,0 +1,19 @@
+export declare class SessionError extends Error {
+  readonly code: string;
+  constructor(message: string, code: string);
+}
+export declare class SessionNotFoundError extends SessionError {
+  constructor();
+}
+export declare class SessionExpiredError extends SessionError {
+  constructor();
+}
+export declare class SessionRevokedError extends SessionError {
+  constructor();
+}
+export declare class SessionSecurityError extends SessionError {
+  constructor(message: string);
+}
+export declare class SessionConfigurationError extends SessionError {
+  constructor(message: string);
+}

package/dist/errors/session.errors.d.ts

@@ -0,0 +1,19 @@
+export declare class SessionError extends Error {
+  readonly code: string;
+  constructor(message: string, code: string);
+}
+export declare class SessionNotFoundError extends SessionError {
+  constructor();
+}
+export declare class SessionExpiredError extends SessionError {
+  constructor();
+}
+export declare class SessionRevokedError extends SessionError {
+  constructor();
+}
+export declare class SessionSecurityError extends SessionError {
+  constructor(message: string);
+}
+export declare class SessionConfigurationError extends SessionError {
+  constructor(message: string);
+}

package/dist/errors/session.errors.js

@@ -0,0 +1,42 @@
+// src/errors/session.errors.ts
+var SessionError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "SessionError";
+	}
+};
+var SessionNotFoundError = class extends SessionError {
+	constructor() {
+		super("Session not found or no longer active.", "SESSION_NOT_FOUND");
+		this.name = "SessionNotFoundError";
+	}
+};
+var SessionExpiredError = class extends SessionError {
+	constructor() {
+		super("Session has expired.", "SESSION_EXPIRED");
+		this.name = "SessionExpiredError";
+	}
+};
+var SessionRevokedError = class extends SessionError {
+	constructor() {
+		super("Session has been revoked.", "SESSION_REVOKED");
+		this.name = "SessionRevokedError";
+	}
+};
+var SessionSecurityError = class extends SessionError {
+	constructor(message) {
+		super(message, "SESSION_SECURITY_ERROR");
+		this.name = "SessionSecurityError";
+	}
+};
+var SessionConfigurationError = class extends SessionError {
+	constructor(message) {
+		super(message, "SESSION_CONFIGURATION_ERROR");
+		this.name = "SessionConfigurationError";
+	}
+};
+export { SessionConfigurationError, SessionError, SessionExpiredError, SessionNotFoundError, SessionRevokedError, SessionSecurityError };
+
+//# sourceMappingURL=session.errors.js.map

package/dist/errors/session.errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.errors.js","names":[],"sources":["../../src/errors/session.errors.ts"],"sourcesContent":["export class SessionError extends Error {\n  constructor(\n    message: string,\n    readonly code: string,\n  ) {\n    super(message);\n    this.name = \"SessionError\";\n  }\n}\n\nexport class SessionNotFoundError extends SessionError {\n  constructor() {\n    super(\"Session not found or no longer active.\", \"SESSION_NOT_FOUND\");\n    this.name = \"SessionNotFoundError\";\n  }\n}\n\nexport class SessionExpiredError extends SessionError {\n  constructor() {\n    super(\"Session has expired.\", \"SESSION_EXPIRED\");\n    this.name = \"SessionExpiredError\";\n  }\n}\n\nexport class SessionRevokedError extends SessionError {\n  constructor() {\n    super(\"Session has been revoked.\", \"SESSION_REVOKED\");\n    this.name = \"SessionRevokedError\";\n  }\n}\n\nexport class SessionSecurityError extends SessionError {\n  constructor(message: string) {\n    super(message, \"SESSION_SECURITY_ERROR\");\n    this.name = \"SessionSecurityError\";\n  }\n}\n\nexport class SessionConfigurationError extends SessionError {\n  constructor(message: string) {\n    super(message, \"SESSION_CONFIGURATION_ERROR\");\n    this.name = \"SessionConfigurationError\";\n  }\n}\n"],"mappings":";AAAA,IAAa,eAAb,cAAkC,MAAM;CAG3B;CAFX,YACE,SACA,MACA;EACA,MAAM,OAAO;EAFJ,KAAA,OAAA;EAGT,KAAK,OAAO;CACd;AACF;AAEA,IAAa,uBAAb,cAA0C,aAAa;CACrD,cAAc;EACZ,MAAM,0CAA0C,mBAAmB;EACnE,KAAK,OAAO;CACd;AACF;AAEA,IAAa,sBAAb,cAAyC,aAAa;CACpD,cAAc;EACZ,MAAM,wBAAwB,iBAAiB;EAC/C,KAAK,OAAO;CACd;AACF;AAEA,IAAa,sBAAb,cAAyC,aAAa;CACpD,cAAc;EACZ,MAAM,6BAA6B,iBAAiB;EACpD,KAAK,OAAO;CACd;AACF;AAEA,IAAa,uBAAb,cAA0C,aAAa;CACrD,YAAY,SAAiB;EAC3B,MAAM,SAAS,wBAAwB;EACvC,KAAK,OAAO;CACd;AACF;AAEA,IAAa,4BAAb,cAA+C,aAAa;CAC1D,YAAY,SAAiB;EAC3B,MAAM,SAAS,6BAA6B;EAC5C,KAAK,OAAO;CACd;AACF"}

package/dist/index.cjs

@@ -0,0 +1,32 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_session_manager = require("./session.manager.cjs");
+const require_session_data_manager = require("./session-data.manager.cjs");
+const require_session_migration = require("./session.migration.cjs");
+const require_session_cookies = require("./session.cookies.cjs");
+const require_session_csrf = require("./session.csrf.cjs");
+const require_session_crypto = require("./utils/session-crypto.cjs");
+const require_session_storage = require("./session.storage.cjs");
+const require_session_errors = require("./errors/session.errors.cjs");
+exports.SESSION_COLLECTION = require_session_storage.SESSION_COLLECTION;
+exports.SESSION_DATA_COLLECTION = require_session_storage.SESSION_DATA_COLLECTION;
+exports.SessionConfigurationError = require_session_errors.SessionConfigurationError;
+exports.SessionDataManager = require_session_data_manager.SessionDataManager;
+exports.SessionError = require_session_errors.SessionError;
+exports.SessionExpiredError = require_session_errors.SessionExpiredError;
+exports.SessionMigrationManager = require_session_migration.SessionMigrationManager;
+exports.SessionNotFoundError = require_session_errors.SessionNotFoundError;
+exports.SessionRevokedError = require_session_errors.SessionRevokedError;
+exports.SessionSecurityError = require_session_errors.SessionSecurityError;
+exports.StorageSessionManager = require_session_manager.StorageSessionManager;
+exports.createSessionCookieOptions = require_session_cookies.createSessionCookieOptions;
+exports.generateSessionId = require_session_crypto.generateSessionId;
+exports.generateSessionToken = require_session_crypto.generateSessionToken;
+exports.hashSessionToken = require_session_crypto.hashSessionToken;
+exports.initializeSessionStorage = require_session_storage.initializeSessionStorage;
+exports.protectStateChangingRequest = require_session_csrf.protectStateChangingRequest;
+exports.readSessionCookie = require_session_cookies.readSessionCookie;
+exports.serializeClearedSessionCookie = require_session_cookies.serializeClearedSessionCookie;
+exports.serializeSessionCookie = require_session_cookies.serializeSessionCookie;
+exports.sessionCollection = require_session_storage.sessionCollection;
+exports.sessionDataCollection = require_session_storage.sessionDataCollection;
+exports.validateRequestOrigin = require_session_csrf.validateRequestOrigin;

package/dist/index.d.cts

@@ -0,0 +1,12 @@
+import { StorageSessionManager } from "./session.manager.cjs";
+import { SessionDataManager, SessionDataOptions } from "./session-data.manager.cjs";
+import { AnonymousMigrationOptions, AnonymousMigrationResult, SessionMigrationContext, SessionMigrationEntry, SessionMigrationManager } from "./session.migration.cjs";
+import { SessionCookieEnvironment, createSessionCookieOptions, readSessionCookie, serializeClearedSessionCookie, serializeSessionCookie } from "./session.cookies.cjs";
+import { CsrfOptions, protectStateChangingRequest, validateRequestOrigin } from "./session.csrf.cjs";
+import { generateSessionId, generateSessionToken, hashSessionToken } from "./utils/session-crypto.cjs";
+import { SESSION_COLLECTION, SESSION_DATA_COLLECTION, initializeSessionStorage, sessionCollection, sessionDataCollection } from "./session.storage.cjs";
+import { SessionConfigurationError, SessionError, SessionExpiredError, SessionNotFoundError, SessionRevokedError, SessionSecurityError } from "./errors/session.errors.cjs";
+import { SessionCookieOptions, SessionDataRecord, SessionDevice, SessionKind, SessionLifetime, SessionRecord, SessionStorageRecord } from "./types/session.types.cjs";
+import { CreateSessionInput, CreatedSession, RotateSessionInput, SessionManager, SessionManagerOptions, ValidateSessionOptions } from "./types/session-manager.types.cjs";
+import { SessionUserLockRecord } from "./types/session-lock.types.cjs";
+export { type AnonymousMigrationOptions, type AnonymousMigrationResult, type CreateSessionInput, type CreatedSession, type CsrfOptions, type RotateSessionInput, SESSION_COLLECTION, SESSION_DATA_COLLECTION, SessionConfigurationError, type SessionCookieEnvironment, type SessionCookieOptions, SessionDataManager, type SessionDataOptions, type SessionDataRecord, type SessionDevice, SessionError, SessionExpiredError, type SessionKind, type SessionLifetime, type SessionManager, type SessionManagerOptions, type SessionMigrationContext, type SessionMigrationEntry, SessionMigrationManager, SessionNotFoundError, type SessionRecord, SessionRevokedError, SessionSecurityError, type SessionStorageRecord, type SessionUserLockRecord, StorageSessionManager, type ValidateSessionOptions, createSessionCookieOptions, generateSessionId, generateSessionToken, hashSessionToken, initializeSessionStorage, protectStateChangingRequest, readSessionCookie, serializeClearedSessionCookie, serializeSessionCookie, sessionCollection, sessionDataCollection, validateRequestOrigin };

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { StorageSessionManager } from "./session.manager.js";
+import { SessionDataManager, SessionDataOptions } from "./session-data.manager.js";
+import { AnonymousMigrationOptions, AnonymousMigrationResult, SessionMigrationContext, SessionMigrationEntry, SessionMigrationManager } from "./session.migration.js";
+import { SessionCookieEnvironment, createSessionCookieOptions, readSessionCookie, serializeClearedSessionCookie, serializeSessionCookie } from "./session.cookies.js";
+import { CsrfOptions, protectStateChangingRequest, validateRequestOrigin } from "./session.csrf.js";
+import { generateSessionId, generateSessionToken, hashSessionToken } from "./utils/session-crypto.js";
+import { SESSION_COLLECTION, SESSION_DATA_COLLECTION, initializeSessionStorage, sessionCollection, sessionDataCollection } from "./session.storage.js";
+import { SessionConfigurationError, SessionError, SessionExpiredError, SessionNotFoundError, SessionRevokedError, SessionSecurityError } from "./errors/session.errors.js";
+import { SessionCookieOptions, SessionDataRecord, SessionDevice, SessionKind, SessionLifetime, SessionRecord, SessionStorageRecord } from "./types/session.types.js";
+import { CreateSessionInput, CreatedSession, RotateSessionInput, SessionManager, SessionManagerOptions, ValidateSessionOptions } from "./types/session-manager.types.js";
+import { SessionUserLockRecord } from "./types/session-lock.types.js";
+export { type AnonymousMigrationOptions, type AnonymousMigrationResult, type CreateSessionInput, type CreatedSession, type CsrfOptions, type RotateSessionInput, SESSION_COLLECTION, SESSION_DATA_COLLECTION, SessionConfigurationError, type SessionCookieEnvironment, type SessionCookieOptions, SessionDataManager, type SessionDataOptions, type SessionDataRecord, type SessionDevice, SessionError, SessionExpiredError, type SessionKind, type SessionLifetime, type SessionManager, type SessionManagerOptions, type SessionMigrationContext, type SessionMigrationEntry, SessionMigrationManager, SessionNotFoundError, type SessionRecord, SessionRevokedError, SessionSecurityError, type SessionStorageRecord, type SessionUserLockRecord, StorageSessionManager, type ValidateSessionOptions, createSessionCookieOptions, generateSessionId, generateSessionToken, hashSessionToken, initializeSessionStorage, protectStateChangingRequest, readSessionCookie, serializeClearedSessionCookie, serializeSessionCookie, sessionCollection, sessionDataCollection, validateRequestOrigin };

package/dist/index.js

@@ -0,0 +1,9 @@
+import { StorageSessionManager } from "./session.manager.js";
+import { SessionDataManager } from "./session-data.manager.js";
+import { SessionMigrationManager } from "./session.migration.js";
+import { createSessionCookieOptions, readSessionCookie, serializeClearedSessionCookie, serializeSessionCookie } from "./session.cookies.js";
+import { protectStateChangingRequest, validateRequestOrigin } from "./session.csrf.js";
+import { generateSessionId, generateSessionToken, hashSessionToken } from "./utils/session-crypto.js";
+import { SESSION_COLLECTION, SESSION_DATA_COLLECTION, initializeSessionStorage, sessionCollection, sessionDataCollection } from "./session.storage.js";
+import { SessionConfigurationError, SessionError, SessionExpiredError, SessionNotFoundError, SessionRevokedError, SessionSecurityError } from "./errors/session.errors.js";
+export { SESSION_COLLECTION, SESSION_DATA_COLLECTION, SessionConfigurationError, SessionDataManager, SessionError, SessionExpiredError, SessionMigrationManager, SessionNotFoundError, SessionRevokedError, SessionSecurityError, StorageSessionManager, createSessionCookieOptions, generateSessionId, generateSessionToken, hashSessionToken, initializeSessionStorage, protectStateChangingRequest, readSessionCookie, serializeClearedSessionCookie, serializeSessionCookie, sessionCollection, sessionDataCollection, validateRequestOrigin };

package/dist/session-data.manager.cjs

@@ -0,0 +1,141 @@
+const require_session_storage = require("./session.storage.cjs");
+const require_session_crypto = require("./utils/session-crypto.cjs");
+let _puzzle_ui_storage = require("@puzzle-ui/storage");
+// src/session-data.manager.ts
+var SessionDataManager = class {
+	storage;
+	options;
+	clock;
+	maximumValueBytes;
+	maximumRetries;
+	constructor(storage, options) {
+		this.storage = storage;
+		this.options = options;
+		this.clock = options.clock ?? (() => /* @__PURE__ */ new Date());
+		this.maximumValueBytes = options.maximumValueBytes ?? 16384;
+		this.maximumRetries = options.maximumRetries ?? 5;
+		if (!options.allowedNamespaces.length) throw new Error("At least one session data namespace is required.");
+		if (!Number.isInteger(this.maximumValueBytes) || this.maximumValueBytes < 1) throw new Error("maximumValueBytes must be a positive integer.");
+		if (!Number.isInteger(this.maximumRetries) || this.maximumRetries < 1) throw new Error("maximumRetries must be a positive integer.");
+		if (options.defaultTtlSeconds !== void 0 && (!Number.isFinite(options.defaultTtlSeconds) || options.defaultTtlSeconds <= 0)) throw new Error("defaultTtlSeconds must be a positive number.");
+	}
+	async initialize() {
+		if (!this.storage.capabilities.uniqueConstraints) throw new Error("Session data requires unique storage constraints.");
+		await this.storage.registerCollection(require_session_storage.sessionDataCollection);
+	}
+	assertOwner(ownerId) {
+		if (!ownerId.trim()) throw new Error("A valid session owner ID is required.");
+	}
+	assertNamespace(namespace) {
+		if (!this.options.allowedNamespaces.includes(namespace)) throw new Error(`Session data namespace is not allowed: ${namespace}`);
+	}
+	assertKey(key) {
+		if (!key.trim()) throw new Error("A valid session data key is required.");
+	}
+	assertValue(value) {
+		let serialized;
+		try {
+			serialized = JSON.stringify(value);
+		} catch {
+			throw new Error("Session data must be JSON serializable.");
+		}
+		if (serialized === void 0) throw new Error("Session data must be JSON serializable.");
+		if (new TextEncoder().encode(serialized).byteLength > this.maximumValueBytes) throw new Error("Session data exceeds the maximum allowed size.");
+	}
+	query(ownerId, namespace, key) {
+		return { where: {
+			ownerId: {
+				operator: "eq",
+				value: ownerId
+			},
+			namespace: {
+				operator: "eq",
+				value: namespace
+			},
+			key: {
+				operator: "eq",
+				value: key
+			}
+		} };
+	}
+	async set(ownerId, namespace, key, value, ttlSeconds = this.options.defaultTtlSeconds) {
+		this.assertOwner(ownerId);
+		this.assertNamespace(namespace);
+		this.assertKey(key);
+		this.assertValue(value);
+		if (ttlSeconds !== void 0 && (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)) throw new Error("TTL must be a positive number.");
+		for (let attempt = 0; attempt < this.maximumRetries; attempt++) {
+			const now = this.clock();
+			const expiresAt = ttlSeconds === void 0 ? null : new Date(now.getTime() + ttlSeconds * 1e3);
+			const existing = await this.storage.findOne(require_session_storage.SESSION_DATA_COLLECTION, this.query(ownerId, namespace, key));
+			if (existing) {
+				try {
+					if (await this.storage.update("session_data", existing.id, {
+						value,
+						expiresAt
+					}, { expectedRevision: existing.revision })) return;
+				} catch (error) {
+					if (!(error instanceof _puzzle_ui_storage.StorageConflictError)) throw error;
+				}
+				continue;
+			}
+			try {
+				await this.storage.insert(require_session_storage.SESSION_DATA_COLLECTION, {
+					id: require_session_crypto.generateSessionId(),
+					ownerId,
+					namespace,
+					key,
+					value,
+					expiresAt,
+					createdAt: now,
+					updatedAt: now,
+					revision: 1
+				});
+				return;
+			} catch (error) {
+				if (error instanceof _puzzle_ui_storage.StorageDuplicateError || error instanceof _puzzle_ui_storage.StorageConflictError) continue;
+				throw error;
+			}
+		}
+		throw new _puzzle_ui_storage.StorageConflictError("Could not write session data after repeated concurrent modifications.");
+	}
+	async get(ownerId, namespace, key) {
+		this.assertOwner(ownerId);
+		this.assertNamespace(namespace);
+		this.assertKey(key);
+		const record = await this.storage.findOne(require_session_storage.SESSION_DATA_COLLECTION, this.query(ownerId, namespace, key));
+		if (!record) return null;
+		if (record.expiresAt && record.expiresAt.getTime() <= this.clock().getTime()) {
+			await this.storage.delete(require_session_storage.SESSION_DATA_COLLECTION, record.id, { expectedRevision: record.revision }).catch((error) => {
+				if (!(error instanceof _puzzle_ui_storage.StorageConflictError)) throw error;
+			});
+			return null;
+		}
+		return record.value;
+	}
+	async remove(ownerId, namespace, key) {
+		this.assertOwner(ownerId);
+		this.assertNamespace(namespace);
+		this.assertKey(key);
+		for (let attempt = 0; attempt < this.maximumRetries; attempt++) {
+			const record = await this.storage.findOne(require_session_storage.SESSION_DATA_COLLECTION, this.query(ownerId, namespace, key));
+			if (!record) return;
+			try {
+				if (await this.storage.delete("session_data", record.id, { expectedRevision: record.revision })) return;
+			} catch (error) {
+				if (!(error instanceof _puzzle_ui_storage.StorageConflictError)) throw error;
+			}
+		}
+		throw new _puzzle_ui_storage.StorageConflictError("Could not remove session data after repeated concurrent modifications.");
+	}
+	async removeExpired() {
+		const now = this.clock();
+		return this.storage.deleteMany(require_session_storage.SESSION_DATA_COLLECTION, { where: { expiresAt: {
+			operator: "lte",
+			value: now
+		} } });
+	}
+};
+exports.SessionDataManager = SessionDataManager;
+
+//# sourceMappingURL=session-data.manager.cjs.map

package/dist/session-data.manager.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-data.manager.cjs","names":["sessionDataCollection","SESSION_DATA_COLLECTION","StorageConflictError","generateSessionId","StorageDuplicateError"],"sources":["../src/session-data.manager.ts"],"sourcesContent":["import {\n  StorageConflictError,\n  StorageDuplicateError,\n  type StorageAdapter,\n} from \"@puzzle-ui/storage\";\n\nimport {\n  SESSION_DATA_COLLECTION,\n  sessionDataCollection,\n} from \"./session.storage\";\n\nimport type { SessionDataRecord } from \"./types/session.types\";\n\nimport { generateSessionId } from \"./utils/session-crypto\";\n\nexport type SessionDataOptions = {\n  readonly allowedNamespaces: readonly string[];\n  readonly defaultTtlSeconds?: number;\n  readonly maximumValueBytes?: number;\n  readonly maximumRetries?: number;\n  readonly clock?: () => Date;\n};\n\nexport class SessionDataManager {\n  private readonly clock: () => Date;\n  private readonly maximumValueBytes: number;\n  private readonly maximumRetries: number;\n\n  constructor(\n    private readonly storage: StorageAdapter,\n    private readonly options: SessionDataOptions,\n  ) {\n    this.clock = options.clock ?? (() => new Date());\n    this.maximumValueBytes = options.maximumValueBytes ?? 16_384;\n    this.maximumRetries = options.maximumRetries ?? 5;\n\n    if (!options.allowedNamespaces.length) {\n      throw new Error(\"At least one session data namespace is required.\");\n    }\n\n    if (\n      !Number.isInteger(this.maximumValueBytes) ||\n      this.maximumValueBytes < 1\n    ) {\n      throw new Error(\"maximumValueBytes must be a positive integer.\");\n    }\n\n    if (!Number.isInteger(this.maximumRetries) || this.maximumRetries < 1) {\n      throw new Error(\"maximumRetries must be a positive integer.\");\n    }\n\n    if (\n      options.defaultTtlSeconds !== undefined &&\n      (!Number.isFinite(options.defaultTtlSeconds) ||\n        options.defaultTtlSeconds <= 0)\n    ) {\n      throw new Error(\"defaultTtlSeconds must be a positive number.\");\n    }\n  }\n\n  async initialize(): Promise<void> {\n    if (!this.storage.capabilities.uniqueConstraints) {\n      throw new Error(\"Session data requires unique storage constraints.\");\n    }\n\n    await this.storage.registerCollection(sessionDataCollection);\n  }\n\n  private assertOwner(ownerId: string): void {\n    if (!ownerId.trim()) {\n      throw new Error(\"A valid session owner ID is required.\");\n    }\n  }\n\n  private assertNamespace(namespace: string): void {\n    if (!this.options.allowedNamespaces.includes(namespace)) {\n      throw new Error(`Session data namespace is not allowed: ${namespace}`);\n    }\n  }\n\n  private assertKey(key: string): void {\n    if (!key.trim()) {\n      throw new Error(\"A valid session data key is required.\");\n    }\n  }\n\n  private assertValue(value: unknown): void {\n    let serialized: string;\n\n    try {\n      serialized = JSON.stringify(value);\n    } catch {\n      throw new Error(\"Session data must be JSON serializable.\");\n    }\n\n    if (serialized === undefined) {\n      throw new Error(\"Session data must be JSON serializable.\");\n    }\n\n    const size = new TextEncoder().encode(serialized).byteLength;\n\n    if (size > this.maximumValueBytes) {\n      throw new Error(\"Session data exceeds the maximum allowed size.\");\n    }\n  }\n\n  private query(ownerId: string, namespace: string, key: string) {\n    return {\n      where: {\n        ownerId: { operator: \"eq\" as const, value: ownerId },\n        namespace: { operator: \"eq\" as const, value: namespace },\n        key: { operator: \"eq\" as const, value: key },\n      },\n    };\n  }\n\n  async set(\n    ownerId: string,\n    namespace: string,\n    key: string,\n    value: unknown,\n    ttlSeconds = this.options.defaultTtlSeconds,\n  ): Promise<void> {\n    this.assertOwner(ownerId);\n    this.assertNamespace(namespace);\n    this.assertKey(key);\n    this.assertValue(value);\n\n    if (\n      ttlSeconds !== undefined &&\n      (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)\n    ) {\n      throw new Error(\"TTL must be a positive number.\");\n    }\n\n    for (let attempt = 0; attempt < this.maximumRetries; attempt++) {\n      const now = this.clock();\n\n      const expiresAt =\n        ttlSeconds === undefined\n          ? null\n          : new Date(now.getTime() + ttlSeconds * 1000);\n\n      const existing = await this.storage.findOne<SessionDataRecord>(\n        SESSION_DATA_COLLECTION,\n        this.query(ownerId, namespace, key),\n      );\n\n      if (existing) {\n        try {\n          const updated = await this.storage.update<SessionDataRecord>(\n            SESSION_DATA_COLLECTION,\n            existing.id,\n            {\n              value,\n              expiresAt,\n            },\n            {\n              expectedRevision: existing.revision,\n            },\n          );\n\n          if (updated) return;\n        } catch (error) {\n          if (!(error instanceof StorageConflictError)) {\n            throw error;\n          }\n        }\n\n        continue;\n      }\n\n      try {\n        await this.storage.insert<SessionDataRecord>(SESSION_DATA_COLLECTION, {\n          id: generateSessionId(),\n          ownerId,\n          namespace,\n          key,\n          value,\n          expiresAt,\n          createdAt: now,\n          updatedAt: now,\n          revision: 1,\n        });\n\n        return;\n      } catch (error) {\n        if (\n          error instanceof StorageDuplicateError ||\n          error instanceof StorageConflictError\n        ) {\n          continue;\n        }\n\n        throw error;\n      }\n    }\n\n    throw new StorageConflictError(\n      \"Could not write session data after repeated concurrent modifications.\",\n    );\n  }\n\n  async get<T = unknown>(\n    ownerId: string,\n    namespace: string,\n    key: string,\n  ): Promise<T | null> {\n    this.assertOwner(ownerId);\n    this.assertNamespace(namespace);\n    this.assertKey(key);\n\n    const record = await this.storage.findOne<SessionDataRecord>(\n      SESSION_DATA_COLLECTION,\n      this.query(ownerId, namespace, key),\n    );\n\n    if (!record) return null;\n\n    if (\n      record.expiresAt &&\n      record.expiresAt.getTime() <= this.clock().getTime()\n    ) {\n      await this.storage\n        .delete(SESSION_DATA_COLLECTION, record.id, {\n          expectedRevision: record.revision,\n        })\n        .catch((error) => {\n          if (!(error instanceof StorageConflictError)) {\n            throw error;\n          }\n        });\n\n      return null;\n    }\n\n    return record.value as T;\n  }\n\n  async remove(ownerId: string, namespace: string, key: string): Promise<void> {\n    this.assertOwner(ownerId);\n    this.assertNamespace(namespace);\n    this.assertKey(key);\n\n    for (let attempt = 0; attempt < this.maximumRetries; attempt++) {\n      const record = await this.storage.findOne<SessionDataRecord>(\n        SESSION_DATA_COLLECTION,\n        this.query(ownerId, namespace, key),\n      );\n\n      if (!record) return;\n\n      try {\n        const deleted = await this.storage.delete(\n          SESSION_DATA_COLLECTION,\n          record.id,\n          {\n            expectedRevision: record.revision,\n          },\n        );\n\n        if (deleted) return;\n      } catch (error) {\n        if (!(error instanceof StorageConflictError)) {\n          throw error;\n        }\n      }\n    }\n\n    throw new StorageConflictError(\n      \"Could not remove session data after repeated concurrent modifications.\",\n    );\n  }\n\n  async removeExpired(): Promise<number> {\n    const now = this.clock();\n\n    return this.storage.deleteMany<SessionDataRecord>(SESSION_DATA_COLLECTION, {\n      where: {\n        expiresAt: {\n          operator: \"lte\",\n          value: now,\n        },\n      },\n    });\n  }\n}\n"],"mappings":"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"}

package/dist/session-data.manager.d.cts

@@ -0,0 +1,26 @@
+import { StorageAdapter } from "@puzzle-ui/storage";
+export type SessionDataOptions = {
+  readonly allowedNamespaces: readonly string[];
+  readonly defaultTtlSeconds?: number;
+  readonly maximumValueBytes?: number;
+  readonly maximumRetries?: number;
+  readonly clock?: () => Date;
+};
+export declare class SessionDataManager {
+  private readonly storage;
+  private readonly options;
+  private readonly clock;
+  private readonly maximumValueBytes;
+  private readonly maximumRetries;
+  constructor(storage: StorageAdapter, options: SessionDataOptions);
+  initialize(): Promise<void>;
+  private assertOwner;
+  private assertNamespace;
+  private assertKey;
+  private assertValue;
+  private query;
+  set(ownerId: string, namespace: string, key: string, value: unknown, ttlSeconds?: number | undefined): Promise<void>;
+  get<T = unknown>(ownerId: string, namespace: string, key: string): Promise<T | null>;
+  remove(ownerId: string, namespace: string, key: string): Promise<void>;
+  removeExpired(): Promise<number>;
+}

package/dist/session-data.manager.d.ts

@@ -0,0 +1,26 @@
+import { StorageAdapter } from "@puzzle-ui/storage";
+export type SessionDataOptions = {
+  readonly allowedNamespaces: readonly string[];
+  readonly defaultTtlSeconds?: number;
+  readonly maximumValueBytes?: number;
+  readonly maximumRetries?: number;
+  readonly clock?: () => Date;
+};
+export declare class SessionDataManager {
+  private readonly storage;
+  private readonly options;
+  private readonly clock;
+  private readonly maximumValueBytes;
+  private readonly maximumRetries;
+  constructor(storage: StorageAdapter, options: SessionDataOptions);
+  initialize(): Promise<void>;
+  private assertOwner;
+  private assertNamespace;
+  private assertKey;
+  private assertValue;
+  private query;
+  set(ownerId: string, namespace: string, key: string, value: unknown, ttlSeconds?: number | undefined): Promise<void>;
+  get<T = unknown>(ownerId: string, namespace: string, key: string): Promise<T | null>;
+  remove(ownerId: string, namespace: string, key: string): Promise<void>;
+  removeExpired(): Promise<number>;
+}