@maestro-js/session 1.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+import { Crypt } from '@maestro-js/crypt';
+
+declare function cookieSessionDriver({ crypt, cookie }: {
+    crypt: Crypt.CryptService;
+    cookie?: Session.Provider.CookieOptions;
+}): Session.Driver;
+
+interface StoreBackend {
+    get(sessionId: string): Promise<string | null>;
+    set(sessionId: string, data: string, ttl: number | null): Promise<void>;
+    del(sessionId: string): Promise<void>;
+}
+declare function storeSessionDriver({ store, crypt, cookie }: {
+    store: StoreBackend;
+    crypt: Crypt.CryptService;
+    cookie?: Session.Provider.CookieOptions;
+}): Session.Driver;
+
+declare function create({ driver }: Session.Provider.SessionServiceConfig): Session.SessionService;
+declare function createScope<Data extends Session.SessionData>(scopeKey: string): (session: Session) => Session.Scope<Data>;
+declare function provider(key: Session.Provider.Key): {
+    getSession: (cookieHeader: string | null | undefined) => Promise<Session.Session>;
+};
+type SessionType = Session;
+type KeysWithFallback = keyof Session.Provider.Keys extends never ? {
+    default: unknown;
+} : Session.Provider.Keys;
+declare const Session: {
+    provider: typeof provider;
+    createScope: typeof createScope;
+    drivers: {
+        cookie: typeof cookieSessionDriver;
+        store: typeof storeSessionDriver;
+    };
+    getSession: (cookieHeader: string | null | undefined) => Promise<Session.Session>;
+    Provider: {
+        create: typeof create;
+        register: (name: Session.Provider.Key, item: Session.SessionService) => void;
+    };
+};
+type Session = {
+    has(key: string): boolean;
+    get(key: string): unknown | null;
+    getCsrfToken(): string;
+    all(): Session.SessionData;
+    set(key: string, value: any): void;
+    del(key: string): void;
+    flash(key: string, value: any): void;
+    reflash(): void;
+    flush(): void;
+    regenerate(): void;
+    invalidate(): void;
+    commit(): Promise<string>;
+};
+declare namespace Session {
+    interface SessionData {
+        [name: string]: unknown;
+    }
+    type Session = SessionType;
+    interface SessionService {
+        getSession(cookieHeader: string | null | undefined): Promise<Session>;
+    }
+    interface Scope<Data extends SessionData> {
+        has(name: keyof Data & string): boolean;
+        get<Key extends keyof Data & string>(name: Key): (Key extends keyof Data ? Data[Key] : undefined) | undefined;
+        all(): Data;
+        set<Key extends keyof Data & string>(name: Key, value: Data[Key]): void;
+        del(name: keyof Data & string): void;
+        flush(): void;
+    }
+    interface Driver {
+        read(cookieHeader: string): Promise<{
+            sessionId: string;
+            data: string;
+        } | null>;
+        write(sessionId: string, data: string): Promise<string>;
+        del(sessionId: string): Promise<void>;
+    }
+    namespace Provider {
+        interface SessionServiceConfig {
+            driver: Driver;
+        }
+        interface CookieOptions {
+            name?: string;
+            secure?: boolean;
+            httpOnly?: boolean;
+            sameSite?: 'Strict' | 'Lax' | 'None';
+            path?: string;
+            domain?: string;
+            maxAge?: number;
+        }
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+    }
+}
+
+export { Session };

package/dist/index.js

@@ -0,0 +1,267 @@
+// src/index.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { ServiceRegistry } from "@maestro-js/service-registry";
+
+// src/cookie-session-driver.ts
+import { randomUUID } from "crypto";
+
+// src/cookie-utils.ts
+function parseCookies(cookieHeader) {
+  const cookies = {};
+  for (const pair of cookieHeader.split(";")) {
+    const index = pair.indexOf("=");
+    if (index === -1) continue;
+    const name = pair.slice(0, index).trim();
+    const value = pair.slice(index + 1).trim();
+    if (name) cookies[name] = decodeURIComponent(value);
+  }
+  return cookies;
+}
+function buildSetCookieHeader(name, value, options) {
+  const parts = [`${name}=${encodeURIComponent(value)}`];
+  parts.push(`Path=${options.path}`);
+  if (options.maxAge !== void 0) parts.push(`Max-Age=${options.maxAge}`);
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  if (options.httpOnly) parts.push("HttpOnly");
+  if (options.secure) parts.push("Secure");
+  parts.push(`SameSite=${options.sameSite}`);
+  return parts.join("; ");
+}
+
+// src/cookie-session-driver.ts
+var MAX_COOKIE_BYTES = 4096;
+function cookieSessionDriver({
+  crypt,
+  cookie
+}) {
+  const cookieOptions = resolveCookieOptions(cookie);
+  return {
+    async read(cookieHeader) {
+      const cookies = parseCookies(cookieHeader);
+      const raw = cookies[cookieOptions.name];
+      if (!raw) return null;
+      try {
+        const data = crypt.decryptString(raw);
+        return { sessionId: randomUUID(), data };
+      } catch {
+        return null;
+      }
+    },
+    async write(_sessionId, data) {
+      const encrypted = crypt.encryptString(data);
+      const byteLength = new TextEncoder().encode(encrypted).byteLength;
+      if (byteLength > MAX_COOKIE_BYTES) {
+        throw new Error(
+          `Cookie session data is ${byteLength} bytes, which exceeds the ${MAX_COOKIE_BYTES}-byte cookie limit. Reduce the amount of data stored in the session or switch to a server-side session driver.`
+        );
+      }
+      return buildSetCookieHeader(cookieOptions.name, encrypted, cookieOptions);
+    },
+    async del() {
+    }
+  };
+}
+function resolveCookieOptions(cookie) {
+  return {
+    name: cookie?.name ?? "__session",
+    secure: cookie?.secure ?? true,
+    httpOnly: cookie?.httpOnly ?? true,
+    sameSite: cookie?.sameSite ?? "Lax",
+    path: cookie?.path ?? "/",
+    domain: cookie?.domain,
+    maxAge: cookie?.maxAge
+  };
+}
+
+// src/store-session-driver.ts
+function storeSessionDriver({
+  store,
+  crypt,
+  cookie
+}) {
+  const cookieOptions = resolveCookieOptions2(cookie);
+  return {
+    async read(cookieHeader) {
+      const cookies = parseCookies(cookieHeader);
+      const raw = cookies[cookieOptions.name];
+      if (!raw) return null;
+      try {
+        const sessionId = crypt.decryptString(raw);
+        const data = await store.get(sessionId);
+        if (!data) return null;
+        return { sessionId, data };
+      } catch {
+        return null;
+      }
+    },
+    async write(sessionId, data) {
+      await store.set(sessionId, data, cookieOptions.maxAge ?? null);
+      const cookieValue = crypt.encryptString(sessionId);
+      return buildSetCookieHeader(cookieOptions.name, cookieValue, cookieOptions);
+    },
+    async del(sessionId) {
+      await store.del(sessionId);
+    }
+  };
+}
+function resolveCookieOptions2(cookie) {
+  return {
+    name: cookie?.name ?? "__session",
+    secure: cookie?.secure ?? true,
+    httpOnly: cookie?.httpOnly ?? true,
+    sameSite: cookie?.sameSite ?? "Lax",
+    path: cookie?.path ?? "/",
+    domain: cookie?.domain,
+    maxAge: cookie?.maxAge
+  };
+}
+
+// src/index.ts
+function create({ driver }) {
+  const flashKey = `__flash`;
+  const crossSiteRequestForgeryTokenKey = `__csrf_token`;
+  async function getSession(cookieHeader) {
+    let sessionId = randomUUID2();
+    let rawData = {};
+    if (cookieHeader) {
+      try {
+        const result = await driver.read(cookieHeader);
+        if (result) {
+          sessionId = result.sessionId;
+          rawData = JSON.parse(result.data);
+        }
+      } catch {
+        sessionId = randomUUID2();
+        rawData = {};
+      }
+    }
+    const oldFlashKeys = new Set(Array.isArray(rawData[flashKey]) ? rawData[flashKey] : []);
+    const newFlashKeys = /* @__PURE__ */ new Set();
+    const csrfToken = rawData[crossSiteRequestForgeryTokenKey] || randomUUID2();
+    delete rawData[flashKey];
+    delete rawData[crossSiteRequestForgeryTokenKey];
+    const meta = { sessionId, data: rawData, oldFlashKeys, newFlashKeys, regenerate: false, csrfToken };
+    function has(key) {
+      return key in meta.data;
+    }
+    function get(key) {
+      return meta.data[key];
+    }
+    function all() {
+      return { ...meta.data };
+    }
+    function set(key, value) {
+      meta.data[key] = value;
+    }
+    function flash(key, value) {
+      meta.data[key] = value;
+      meta.newFlashKeys.add(key);
+    }
+    function reflash() {
+      for (const key of meta.oldFlashKeys) {
+        meta.newFlashKeys.add(key);
+      }
+    }
+    function del(key) {
+      delete meta.data[key];
+      meta.oldFlashKeys.delete(key);
+      meta.newFlashKeys.delete(key);
+    }
+    function flush() {
+      meta.data = {};
+      meta.oldFlashKeys.clear();
+      meta.newFlashKeys.clear();
+    }
+    function regenerate() {
+      meta.regenerate = true;
+    }
+    function invalidate() {
+      meta.regenerate = true;
+      flush();
+    }
+    function getCsrfToken() {
+      return csrfToken;
+    }
+    async function commit() {
+      const nextSessionId = meta.regenerate ? randomUUID2() : meta.sessionId;
+      const nextCsrfToken = meta.regenerate ? randomUUID2() : meta.csrfToken;
+      for (const key of meta.oldFlashKeys) {
+        if (!meta.newFlashKeys.has(key)) {
+          delete meta.data[key];
+        }
+      }
+      if (meta.newFlashKeys.size > 0) {
+        meta.data[flashKey] = Array.from(meta.newFlashKeys);
+      }
+      meta.data[crossSiteRequestForgeryTokenKey] = nextCsrfToken;
+      if (meta.regenerate) {
+        await driver.del(meta.sessionId);
+      }
+      return driver.write(nextSessionId, JSON.stringify(meta.data));
+    }
+    const session = { get, has, all, getCsrfToken, set, flash, reflash, del, flush, regenerate, invalidate, commit };
+    return session;
+  }
+  return { getSession };
+}
+function createScope(scopeKey) {
+  return (session) => {
+    function all() {
+      const rawData = session.get(scopeKey);
+      const data = rawData && typeof rawData === "object" ? rawData : {};
+      return { ...data };
+    }
+    return {
+      has(key) {
+        const rawData = session.get(scopeKey);
+        const data = rawData && typeof rawData === "object" ? rawData : {};
+        return key in data;
+      },
+      get(key) {
+        const rawData = session.get(scopeKey);
+        const data = rawData && typeof rawData === "object" ? rawData : {};
+        return data[key];
+      },
+      all,
+      set(key, value) {
+        const data = all();
+        data[key] = value;
+        session.set(scopeKey, data);
+      },
+      del(key) {
+        const data = all();
+        delete data[key];
+        session.set(scopeKey, data);
+      },
+      flush() {
+        session.del(scopeKey);
+      }
+    };
+  };
+}
+var registry = ServiceRegistry.createRegistry(
+  ServiceRegistry.proxyFunctionsForObject
+);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    getSession: service.getSession
+  };
+}
+var Session = {
+  Provider,
+  ...provider("default"),
+  provider,
+  createScope,
+  drivers: {
+    cookie: cookieSessionDriver,
+    store: storeSessionDriver
+  }
+};
+export {
+  Session
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@maestro-js/session",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@maestro-js/crypt": "1.0.0-alpha.0",
+    "@maestro-js/service-registry": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/",
+    "lint": "prettier --check src/"
+  }
+}