@meekojs/meeko 0.0.3 → 0.1.0

package/dist/framework-server/session-stores.js

@@ -0,0 +1,122 @@
+import { serializeJson } from "../server.js";
+function decodeRecord(value, id) {
+    let record;
+    try {
+        record = JSON.parse(value);
+    }
+    catch {
+        throw new Error("Corrupt session record");
+    }
+    if (!record || typeof record !== "object")
+        throw new Error("Corrupt session record");
+    const candidate = record;
+    if (candidate.id !== id || typeof candidate.csrfToken !== "string" || !Object.hasOwn(candidate, "data") ||
+        typeof candidate.createdAt !== "number" || typeof candidate.expiresAt !== "number" ||
+        !Number.isFinite(candidate.createdAt) || !Number.isFinite(candidate.expiresAt) ||
+        (candidate.familyId !== undefined && (typeof candidate.familyId !== "string" || candidate.familyId.length === 0))) {
+        throw new Error("Corrupt session record");
+    }
+    return candidate;
+}
+/** Persistent store with Redis-managed expiration and explicit connection ownership. */
+export class RedisSessionStore {
+    client;
+    options;
+    persistent = true;
+    constructor(client, options) {
+        this.client = client;
+        this.options = options;
+        if (!options.prefix || !options.prefix.endsWith(":") || /\s/.test(options.prefix))
+            throw new TypeError("Session Redis prefix must be nonempty, contain no whitespace, and end with ':'");
+    }
+    key(id) { return `${this.options.prefix}${id}`; }
+    familyKey(id) { return `${this.options.prefix}family:${id}`; }
+    async get(id) {
+        const value = await this.client.get(this.key(id));
+        if (value === null)
+            return undefined;
+        const record = decodeRecord(value, id);
+        if (record.expiresAt > Date.now()) {
+            // Older records without a family id are migrated by the first rotation.
+            if (!record.familyId || await this.client.get(this.familyKey(record.familyId)) === id)
+                return record;
+            await this.delete(id);
+            return undefined;
+        }
+        await this.delete(id);
+        return undefined;
+    }
+    async set(record) {
+        const ttlMs = record.expiresAt - Date.now();
+        if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0)
+            throw new RangeError("Session must have a future expiration");
+        const familyId = record.familyId ?? record.id;
+        const result = await this.client.eval("-- meeko:session:set\nlocal prior = redis.call('GET', KEYS[1]) if prior then local old = cjson.decode(prior) if (old.familyId or old.id) ~= ARGV[4] then return 0 end end local active = redis.call('GET', KEYS[2]) if active and active ~= ARGV[2] then return 0 end redis.call('SET', KEYS[1], ARGV[1], 'PX', ARGV[3]) redis.call('SET', KEYS[2], ARGV[2], 'PX', ARGV[3]) return 1", { keys: [this.key(record.id), this.familyKey(familyId)], arguments: [serializeJson({ ...record, familyId }), record.id, String(ttlMs), familyId] });
+        if (result !== 1)
+            throw new Error("Session family already has an active id");
+    }
+    async delete(id) {
+        const value = await this.client.get(this.key(id));
+        if (value === null)
+            return;
+        const record = decodeRecord(value, id);
+        await this.client.eval("-- meeko:session:delete\nlocal raw = redis.call('GET', KEYS[1]) if not raw then return 0 end local active = redis.call('GET', KEYS[2]) redis.call('DEL', KEYS[1]) if active == ARGV[1] then redis.call('DEL', KEYS[2]) end return 1", { keys: [this.key(id), this.familyKey(record.familyId ?? id)], arguments: [id] });
+    }
+    async replace(previousId, record) {
+        const ttlMs = record.expiresAt - Date.now();
+        if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0)
+            throw new RangeError("Session must have a future expiration");
+        if (!record.familyId)
+            throw new Error("Rotated session requires a family id");
+        const result = await this.client.eval("-- meeko:session:replace\nlocal raw = redis.call('GET', KEYS[1]) if not raw then return 0 end local previous = cjson.decode(raw) local family = previous.familyId or previous.id if family ~= ARGV[3] or previous.expiresAt <= tonumber(ARGV[4]) then return 0 end local active = redis.call('GET', KEYS[3]) if active and active ~= ARGV[2] then return 0 end redis.call('SET', KEYS[2], ARGV[1], 'PX', ARGV[5]) redis.call('SET', KEYS[3], ARGV[6], 'PX', ARGV[5]) redis.call('DEL', KEYS[1]) return 1", { keys: [this.key(previousId), this.key(record.id), this.familyKey(record.familyId)], arguments: [serializeJson(record), previousId, record.familyId, String(Date.now()), String(ttlMs), record.id] });
+        if (result !== 0 && result !== 1)
+            throw new Error("Unexpected Redis rotation result");
+        return result === 1;
+    }
+    async revokeFamily(familyId) {
+        await this.client.eval("-- meeko:session:revoke-family\nlocal active = redis.call('GET', KEYS[1]) if active then redis.call('DEL', ARGV[1] .. active) redis.call('DEL', KEYS[1]) else redis.call('DEL', ARGV[1] .. ARGV[2]) end return 1", { keys: [this.familyKey(familyId)], arguments: [this.options.prefix, familyId] });
+    }
+    async close() { if (this.options.closeClient)
+        await this.client.quit?.(); }
+}
+/** Generic SQL store. The application supplies SQL statements through its driver. */
+export class SqlSessionStore {
+    driver;
+    options;
+    persistent = true;
+    constructor(driver, options = {}) {
+        this.driver = driver;
+        this.options = options;
+        if (typeof driver.replace !== "function" || typeof driver.revokeFamily !== "function")
+            throw new TypeError("SQL session driver requires atomic replace and family revocation");
+    }
+    async get(id) {
+        const row = await this.driver.read(id);
+        if (!row)
+            return undefined;
+        if (row.id !== id || typeof row.dataJson !== "string" || typeof row.familyId !== "string" || !row.familyId)
+            throw new Error("Session SQL schema requires a nonempty family_id column");
+        const record = decodeRecord(serializeJson({ id: row.id, familyId: row.familyId, csrfToken: row.csrfToken, data: JSON.parse(row.dataJson), createdAt: row.createdAt, expiresAt: row.expiresAt }), id);
+        if (record.expiresAt > Date.now())
+            return record;
+        await this.delete(id);
+        return undefined;
+    }
+    async set(record) {
+        if (!Number.isSafeInteger(record.expiresAt) || record.expiresAt <= Date.now())
+            throw new RangeError("Session must have a future expiration");
+        await this.driver.write({ id: record.id, familyId: record.familyId ?? record.id, csrfToken: record.csrfToken, dataJson: serializeJson(record.data), createdAt: record.createdAt, expiresAt: record.expiresAt });
+    }
+    async delete(id) { await this.driver.remove(id); }
+    async replace(previousId, record) {
+        if (!Number.isSafeInteger(record.expiresAt) || record.expiresAt <= Date.now())
+            throw new RangeError("Session must have a future expiration");
+        if (!record.familyId)
+            throw new Error("Rotated session requires a family id");
+        return this.driver.replace(previousId, { id: record.id, familyId: record.familyId, csrfToken: record.csrfToken, dataJson: serializeJson(record.data), createdAt: record.createdAt, expiresAt: record.expiresAt }, Date.now());
+    }
+    async revokeFamily(familyId) { await this.driver.revokeFamily(familyId); }
+    async close() { if (this.options.closeDriver)
+        await this.driver.close?.(); }
+}
+//# sourceMappingURL=session-stores.js.map

package/dist/framework-server/session-stores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-stores.js","sourceRoot":"","sources":["../../src/framework-server/session-stores.ts"],"names":[],"mappings":"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","sourcesContent":["import { serializeJson } from \"../server.js\";\nimport type { SessionRecord, SessionStore } from \"./sessions.js\";\n\n/** Small interface compatible with Redis clients that support SET PX. */\nexport interface RedisSessionClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, options: { PX: number }): Promise<unknown>;\n  del(key: string): Promise<unknown>;\n  eval(script: string, options: { keys: string[]; arguments: string[] }): Promise<unknown>;\n  quit?(): Promise<unknown>;\n}\n\nexport interface RedisSessionStoreOptions {\n  /** Use a unique prefix for each application and environment. */\n  prefix: string;\n  /** Close the Redis client when this store owns its connection. */\n  closeClient?: boolean;\n}\n\nfunction decodeRecord<T>(value: string, id: string): SessionRecord<T> {\n  let record: unknown;\n  try { record = JSON.parse(value) as unknown; }\n  catch { throw new Error(\"Corrupt session record\"); }\n  if (!record || typeof record !== \"object\") throw new Error(\"Corrupt session record\");\n  const candidate = record as Partial<SessionRecord<T>>;\n  if (candidate.id !== id || typeof candidate.csrfToken !== \"string\" || !Object.hasOwn(candidate, \"data\") ||\n      typeof candidate.createdAt !== \"number\" || typeof candidate.expiresAt !== \"number\" ||\n      !Number.isFinite(candidate.createdAt) || !Number.isFinite(candidate.expiresAt) ||\n      (candidate.familyId !== undefined && (typeof candidate.familyId !== \"string\" || candidate.familyId.length === 0))) {\n    throw new Error(\"Corrupt session record\");\n  }\n  return candidate as SessionRecord<T>;\n}\n\n/** Persistent store with Redis-managed expiration and explicit connection ownership. */\nexport class RedisSessionStore<T = unknown> implements SessionStore<T> {\n  readonly persistent = true;\n  constructor(private readonly client: RedisSessionClient, private readonly options: RedisSessionStoreOptions) {\n    if (!options.prefix || !options.prefix.endsWith(\":\") || /\\s/.test(options.prefix)) throw new TypeError(\"Session Redis prefix must be nonempty, contain no whitespace, and end with ':'\");\n  }\n  private key(id: string): string { return `${this.options.prefix}${id}`; }\n  private familyKey(id: string): string { return `${this.options.prefix}family:${id}`; }\n  async get(id: string): Promise<SessionRecord<T> | undefined> {\n    const value = await this.client.get(this.key(id));\n    if (value === null) return undefined;\n    const record = decodeRecord<T>(value, id);\n    if (record.expiresAt > Date.now()) {\n      // Older records without a family id are migrated by the first rotation.\n      if (!record.familyId || await this.client.get(this.familyKey(record.familyId)) === id) return record;\n      await this.delete(id);\n      return undefined;\n    }\n    await this.delete(id);\n    return undefined;\n  }\n  async set(record: SessionRecord<T>): Promise<void> {\n    const ttlMs = record.expiresAt - Date.now();\n    if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) throw new RangeError(\"Session must have a future expiration\");\n    const familyId = record.familyId ?? record.id;\n    const result = await this.client.eval(\n      \"-- meeko:session:set\\nlocal prior = redis.call('GET', KEYS[1]) if prior then local old = cjson.decode(prior) if (old.familyId or old.id) ~= ARGV[4] then return 0 end end local active = redis.call('GET', KEYS[2]) if active and active ~= ARGV[2] then return 0 end redis.call('SET', KEYS[1], ARGV[1], 'PX', ARGV[3]) redis.call('SET', KEYS[2], ARGV[2], 'PX', ARGV[3]) return 1\",\n      { keys: [this.key(record.id), this.familyKey(familyId)], arguments: [serializeJson({ ...record, familyId }), record.id, String(ttlMs), familyId] },\n    );\n    if (result !== 1) throw new Error(\"Session family already has an active id\");\n  }\n  async delete(id: string): Promise<void> {\n    const value = await this.client.get(this.key(id));\n    if (value === null) return;\n    const record = decodeRecord<T>(value, id);\n    await this.client.eval(\n      \"-- meeko:session:delete\\nlocal raw = redis.call('GET', KEYS[1]) if not raw then return 0 end local active = redis.call('GET', KEYS[2]) redis.call('DEL', KEYS[1]) if active == ARGV[1] then redis.call('DEL', KEYS[2]) end return 1\",\n      { keys: [this.key(id), this.familyKey(record.familyId ?? id)], arguments: [id] },\n    );\n  }\n  async replace(previousId: string, record: SessionRecord<T>): Promise<boolean> {\n    const ttlMs = record.expiresAt - Date.now();\n    if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) throw new RangeError(\"Session must have a future expiration\");\n    if (!record.familyId) throw new Error(\"Rotated session requires a family id\");\n    const result = await this.client.eval(\n      \"-- meeko:session:replace\\nlocal raw = redis.call('GET', KEYS[1]) if not raw then return 0 end local previous = cjson.decode(raw) local family = previous.familyId or previous.id if family ~= ARGV[3] or previous.expiresAt <= tonumber(ARGV[4]) then return 0 end local active = redis.call('GET', KEYS[3]) if active and active ~= ARGV[2] then return 0 end redis.call('SET', KEYS[2], ARGV[1], 'PX', ARGV[5]) redis.call('SET', KEYS[3], ARGV[6], 'PX', ARGV[5]) redis.call('DEL', KEYS[1]) return 1\",\n      { keys: [this.key(previousId), this.key(record.id), this.familyKey(record.familyId)], arguments: [serializeJson(record), previousId, record.familyId, String(Date.now()), String(ttlMs), record.id] },\n    );\n    if (result !== 0 && result !== 1) throw new Error(\"Unexpected Redis rotation result\");\n    return result === 1;\n  }\n  async revokeFamily(familyId: string): Promise<void> {\n    await this.client.eval(\n      \"-- meeko:session:revoke-family\\nlocal active = redis.call('GET', KEYS[1]) if active then redis.call('DEL', ARGV[1] .. active) redis.call('DEL', KEYS[1]) else redis.call('DEL', ARGV[1] .. ARGV[2]) end return 1\",\n      { keys: [this.familyKey(familyId)], arguments: [this.options.prefix, familyId] },\n    );\n  }\n  async close(): Promise<void> { if (this.options.closeClient) await this.client.quit?.(); }\n}\n\n/** A driver can implement these operations using any SQL client and dialect. */\nexport interface SqlSessionRow {\n  id: string;\n  /** Migrate existing rows by setting family_id = id before deploying this driver. */\n  familyId: string;\n  csrfToken: string;\n  dataJson: string;\n  createdAt: number;\n  expiresAt: number;\n}\n\nexport interface SqlSessionDriver {\n  read(id: string): Promise<SqlSessionRow | undefined>;\n  /** Insert or update one row, keyed by its opaque id; enforce one active id per family. */\n  write(row: SqlSessionRow): Promise<void>;\n  remove(id: string): Promise<void>;\n  /** Atomically replace an unexpired row of the same family in one transaction. */\n  replace(previousId: string, row: SqlSessionRow, now: number): Promise<boolean>;\n  /** Delete the active row for this family in one atomic operation, including stale-handle logout. */\n  revokeFamily(familyId: string): Promise<void>;\n  close?(): Promise<void>;\n}\n\nexport interface SqlSessionStoreOptions {\n  /** Close the SQL driver when this store owns its connection. */\n  closeDriver?: boolean;\n}\n\n/** Generic SQL store. The application supplies SQL statements through its driver. */\nexport class SqlSessionStore<T = unknown> implements SessionStore<T> {\n  readonly persistent = true;\n  constructor(private readonly driver: SqlSessionDriver, private readonly options: SqlSessionStoreOptions = {}) {\n    if (typeof driver.replace !== \"function\" || typeof driver.revokeFamily !== \"function\") throw new TypeError(\"SQL session driver requires atomic replace and family revocation\");\n  }\n  async get(id: string): Promise<SessionRecord<T> | undefined> {\n    const row = await this.driver.read(id);\n    if (!row) return undefined;\n    if (row.id !== id || typeof row.dataJson !== \"string\" || typeof row.familyId !== \"string\" || !row.familyId) throw new Error(\"Session SQL schema requires a nonempty family_id column\");\n    const record = decodeRecord<T>(serializeJson({ id: row.id, familyId: row.familyId, csrfToken: row.csrfToken, data: JSON.parse(row.dataJson) as unknown, createdAt: row.createdAt, expiresAt: row.expiresAt }), id);\n    if (record.expiresAt > Date.now()) return record;\n    await this.delete(id);\n    return undefined;\n  }\n  async set(record: SessionRecord<T>): Promise<void> {\n    if (!Number.isSafeInteger(record.expiresAt) || record.expiresAt <= Date.now()) throw new RangeError(\"Session must have a future expiration\");\n    await this.driver.write({ id: record.id, familyId: record.familyId ?? record.id, csrfToken: record.csrfToken, dataJson: serializeJson(record.data), createdAt: record.createdAt, expiresAt: record.expiresAt });\n  }\n  async delete(id: string): Promise<void> { await this.driver.remove(id); }\n  async replace(previousId: string, record: SessionRecord<T>): Promise<boolean> {\n    if (!Number.isSafeInteger(record.expiresAt) || record.expiresAt <= Date.now()) throw new RangeError(\"Session must have a future expiration\");\n    if (!record.familyId) throw new Error(\"Rotated session requires a family id\");\n    return this.driver.replace(previousId, { id: record.id, familyId: record.familyId, csrfToken: record.csrfToken, dataJson: serializeJson(record.data), createdAt: record.createdAt, expiresAt: record.expiresAt }, Date.now());\n  }\n  async revokeFamily(familyId: string): Promise<void> { await this.driver.revokeFamily(familyId); }\n  async close(): Promise<void> { if (this.options.closeDriver) await this.driver.close?.(); }\n}\n"]}

package/dist/framework-server/sessions.d.ts

@@ -0,0 +1,70 @@
+export interface SessionRecord<T = unknown> {
+    id: string;
+    /** Stable opaque lineage for atomic revocation after one or more rotations. */
+    familyId?: string;
+    csrfToken: string;
+    data: T;
+    createdAt: number;
+    expiresAt: number;
+}
+export interface SessionStore<T = unknown> {
+    /** Explicitly acknowledge that records survive application process restarts. */
+    readonly persistent?: boolean;
+    get(id: string): Promise<SessionRecord<T> | undefined>;
+    set(record: SessionRecord<T>): Promise<void>;
+    delete(id: string): Promise<void>;
+    /** Atomically replace an existing id; false means it no longer exists. */
+    replace?(previousId: string, record: SessionRecord<T>): Promise<boolean>;
+    /** Atomically revoke the currently active id in this family, even from a stale handle. */
+    revokeFamily?(familyId: string): Promise<void>;
+    close?(): Promise<void>;
+}
+export declare class MemorySessionStore<T = unknown> implements SessionStore<T> {
+    readonly developmentOnly = true;
+    readonly persistent = false;
+    private readonly records;
+    private readonly families;
+    get(id: string): Promise<SessionRecord<T> | undefined>;
+    set(record: SessionRecord<T>): Promise<void>;
+    delete(id: string): Promise<void>;
+    replace(previousId: string, record: SessionRecord<T>): Promise<boolean>;
+    revokeFamily(familyId: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface SessionOptions<T> {
+    store: SessionStore<T>;
+    production?: boolean;
+    ttlMs?: number;
+    secure?: boolean;
+    sameSite?: "Lax" | "Strict" | "None";
+    cookieName?: string;
+    allowedOrigins?: readonly string[];
+}
+export declare class SessionHandle<T = unknown> {
+    private readonly manager;
+    current?: SessionRecord<T> | undefined;
+    private pendingCookie?;
+    constructor(manager: SessionManager<T>, current?: SessionRecord<T> | undefined);
+    get cookieHeader(): string | undefined;
+    create(data: T): Promise<SessionRecord<T>>;
+    rotate(): Promise<SessionRecord<T>>;
+    revoke(): Promise<void>;
+}
+export declare class SessionManager<T = unknown> {
+    readonly store: SessionStore<T>;
+    readonly ttlMs: number;
+    readonly cookieName: string;
+    readonly allowedOrigins: readonly string[];
+    private readonly secure;
+    private readonly sameSite;
+    constructor(options: SessionOptions<T>);
+    serializeCookie(value: string, ttlMs: number): string;
+    load(request: Request): Promise<SessionHandle<T>>;
+    close(): Promise<void>;
+    /** Apply both Origin and token checks to authenticated cookie mutations. */
+    assertMutationAllowed(request: Request, session: SessionHandle<T>, mutating?: boolean): void;
+}
+export declare class SessionSecurityError extends Error {
+    readonly code: "INVALID_ORIGIN" | "INVALID_CSRF";
+    constructor(code: "INVALID_ORIGIN" | "INVALID_CSRF");
+}

package/dist/framework-server/sessions.js

@@ -0,0 +1,167 @@
+import { randomBytes } from "node:crypto";
+export class MemorySessionStore {
+    developmentOnly = true;
+    persistent = false;
+    records = new Map();
+    families = new Map();
+    async get(id) {
+        const record = this.records.get(id);
+        if (record && record.expiresAt <= Date.now()) {
+            await this.delete(id);
+            return undefined;
+        }
+        if (record && this.families.get(record.familyId ?? record.id) !== id)
+            return undefined;
+        return record;
+    }
+    async set(record) {
+        const familyId = record.familyId ?? record.id;
+        const existing = this.records.get(record.id);
+        if (existing && (existing.familyId ?? existing.id) !== familyId)
+            throw new Error("Session id cannot change family");
+        const active = this.families.get(familyId);
+        if (active && active !== record.id)
+            throw new Error("Session family already has an active id");
+        this.records.set(record.id, { ...record, familyId });
+        this.families.set(familyId, record.id);
+    }
+    async delete(id) {
+        const record = this.records.get(id);
+        this.records.delete(id);
+        if (record && this.families.get(record.familyId ?? record.id) === id)
+            this.families.delete(record.familyId ?? record.id);
+    }
+    async replace(previousId, record) {
+        const previous = this.records.get(previousId);
+        if (!previous || previous.expiresAt <= Date.now()) {
+            await this.delete(previousId);
+            return false;
+        }
+        const familyId = previous.familyId ?? previous.id;
+        if (record.familyId !== familyId || this.families.get(familyId) !== previousId)
+            return false;
+        this.records.set(record.id, record);
+        this.families.set(familyId, record.id);
+        this.records.delete(previousId);
+        return true;
+    }
+    async revokeFamily(familyId) {
+        const active = this.families.get(familyId);
+        if (active)
+            this.records.delete(active);
+        this.families.delete(familyId);
+    }
+    async close() { this.records.clear(); this.families.clear(); }
+}
+function token() { return randomBytes(32).toString("base64url"); }
+function cookieValue(header, name) {
+    for (const cookie of (header ?? "").split(";")) {
+        const separator = cookie.indexOf("=");
+        if (separator < 0 || cookie.slice(0, separator).trim() !== name)
+            continue;
+        const value = cookie.slice(separator + 1).trim();
+        return /^[A-Za-z0-9_-]{43}$/.test(value) ? value : undefined;
+    }
+    return undefined;
+}
+export class SessionHandle {
+    manager;
+    current;
+    pendingCookie;
+    constructor(manager, current) {
+        this.manager = manager;
+        this.current = current;
+    }
+    get cookieHeader() { return this.pendingCookie; }
+    async create(data) {
+        const previous = this.current;
+        const now = Date.now();
+        const record = { id: token(), familyId: previous?.familyId ?? previous?.id ?? token(), csrfToken: token(), data, createdAt: now, expiresAt: now + this.manager.ttlMs };
+        if (previous) {
+            if (!this.manager.store.replace)
+                throw new Error("Session storage does not support atomic rotation");
+            if (!(await this.manager.store.replace(previous.id, record)))
+                throw new Error("Session has expired or been revoked");
+        }
+        else
+            await this.manager.store.set(record);
+        this.current = record;
+        this.pendingCookie = this.manager.serializeCookie(record.id, this.manager.ttlMs);
+        return record;
+    }
+    async rotate() {
+        if (!this.current)
+            throw new Error("No active session to rotate");
+        return this.create(this.current.data);
+    }
+    async revoke() {
+        if (this.current) {
+            if (!this.manager.store.revokeFamily)
+                throw new Error("Session storage does not support atomic family revocation");
+            await this.manager.store.revokeFamily(this.current.familyId ?? this.current.id);
+        }
+        this.current = undefined;
+        this.pendingCookie = this.manager.serializeCookie("", 0);
+    }
+}
+export class SessionManager {
+    store;
+    ttlMs;
+    cookieName;
+    allowedOrigins;
+    secure;
+    sameSite;
+    constructor(options) {
+        if (options.production && (options.store.persistent !== true || !options.store.replace || !options.store.revokeFamily))
+            throw new Error("Persistent session storage with atomic rotation and family revocation is required in production");
+        this.store = options.store;
+        this.ttlMs = options.ttlMs ?? 7 * 24 * 60 * 60 * 1000;
+        if (!Number.isSafeInteger(this.ttlMs) || this.ttlMs <= 0)
+            throw new RangeError("Invalid session TTL");
+        this.secure = options.secure ?? true;
+        this.sameSite = options.sameSite ?? "Lax";
+        if (this.sameSite === "None" && !this.secure)
+            throw new Error("SameSite=None requires Secure");
+        this.cookieName = options.cookieName ?? (this.secure ? "__Host-meeko.sid" : "meeko.sid");
+        if (!/^[A-Za-z0-9_.-]+$/.test(this.cookieName))
+            throw new TypeError("Invalid cookie name");
+        if (this.cookieName.startsWith("__Host-") && !this.secure)
+            throw new Error("__Host- cookies require Secure");
+        this.allowedOrigins = options.allowedOrigins ?? [];
+    }
+    serializeCookie(value, ttlMs) {
+        const parts = [`${this.cookieName}=${value}`, "Path=/", "HttpOnly", `SameSite=${this.sameSite}`, `Max-Age=${Math.floor(ttlMs / 1000)}`];
+        if (this.secure)
+            parts.push("Secure");
+        return parts.join("; ");
+    }
+    async load(request) {
+        const id = cookieValue(request.headers.get("cookie"), this.cookieName);
+        const record = id ? await this.store.get(id) : undefined;
+        if (record && record.expiresAt <= Date.now()) {
+            await this.store.delete(record.id);
+            return new SessionHandle(this);
+        }
+        return new SessionHandle(this, record);
+    }
+    async close() { await this.store.close?.(); }
+    /** Apply both Origin and token checks to authenticated cookie mutations. */
+    assertMutationAllowed(request, session, mutating = !["GET", "HEAD", "OPTIONS"].includes(request.method)) {
+        if (!session.current || !mutating)
+            return;
+        const origin = request.headers.get("origin");
+        const expected = new URL(request.url).origin;
+        if (!origin || (origin !== expected && !this.allowedOrigins.includes(origin)))
+            throw new SessionSecurityError("INVALID_ORIGIN");
+        if (request.headers.get("x-meeko-csrf") !== session.current.csrfToken)
+            throw new SessionSecurityError("INVALID_CSRF");
+    }
+}
+export class SessionSecurityError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/framework-server/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../src/framework-server/sessions.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomBytes } from \"node:crypto\";\n\nexport interface SessionRecord<T = unknown> {\n  id: string;\n  /** Stable opaque lineage for atomic revocation after one or more rotations. */\n  familyId?: string;\n  csrfToken: string;\n  data: T;\n  createdAt: number;\n  expiresAt: number;\n}\n\nexport interface SessionStore<T = unknown> {\n  /** Explicitly acknowledge that records survive application process restarts. */\n  readonly persistent?: boolean;\n  get(id: string): Promise<SessionRecord<T> | undefined>;\n  set(record: SessionRecord<T>): Promise<void>;\n  delete(id: string): Promise<void>;\n  /** Atomically replace an existing id; false means it no longer exists. */\n  replace?(previousId: string, record: SessionRecord<T>): Promise<boolean>;\n  /** Atomically revoke the currently active id in this family, even from a stale handle. */\n  revokeFamily?(familyId: string): Promise<void>;\n  close?(): Promise<void>;\n}\n\nexport class MemorySessionStore<T = unknown> implements SessionStore<T> {\n  readonly developmentOnly = true;\n  readonly persistent = false;\n  private readonly records = new Map<string, SessionRecord<T>>();\n  private readonly families = new Map<string, string>();\n  async get(id: string): Promise<SessionRecord<T> | undefined> {\n    const record = this.records.get(id);\n    if (record && record.expiresAt <= Date.now()) {\n      await this.delete(id);\n      return undefined;\n    }\n    if (record && this.families.get(record.familyId ?? record.id) !== id) return undefined;\n    return record;\n  }\n  async set(record: SessionRecord<T>): Promise<void> {\n    const familyId = record.familyId ?? record.id;\n    const existing = this.records.get(record.id);\n    if (existing && (existing.familyId ?? existing.id) !== familyId) throw new Error(\"Session id cannot change family\");\n    const active = this.families.get(familyId);\n    if (active && active !== record.id) throw new Error(\"Session family already has an active id\");\n    this.records.set(record.id, { ...record, familyId });\n    this.families.set(familyId, record.id);\n  }\n  async delete(id: string): Promise<void> {\n    const record = this.records.get(id);\n    this.records.delete(id);\n    if (record && this.families.get(record.familyId ?? record.id) === id) this.families.delete(record.familyId ?? record.id);\n  }\n  async replace(previousId: string, record: SessionRecord<T>): Promise<boolean> {\n    const previous = this.records.get(previousId);\n    if (!previous || previous.expiresAt <= Date.now()) {\n      await this.delete(previousId);\n      return false;\n    }\n    const familyId = previous.familyId ?? previous.id;\n    if (record.familyId !== familyId || this.families.get(familyId) !== previousId) return false;\n    this.records.set(record.id, record);\n    this.families.set(familyId, record.id);\n    this.records.delete(previousId);\n    return true;\n  }\n  async revokeFamily(familyId: string): Promise<void> {\n    const active = this.families.get(familyId);\n    if (active) this.records.delete(active);\n    this.families.delete(familyId);\n  }\n  async close(): Promise<void> { this.records.clear(); this.families.clear(); }\n}\n\nexport interface SessionOptions<T> {\n  store: SessionStore<T>;\n  production?: boolean;\n  ttlMs?: number;\n  secure?: boolean;\n  sameSite?: \"Lax\" | \"Strict\" | \"None\";\n  cookieName?: string;\n  allowedOrigins?: readonly string[];\n}\n\nfunction token(): string { return randomBytes(32).toString(\"base64url\"); }\n\nfunction cookieValue(header: string | null, name: string): string | undefined {\n  for (const cookie of (header ?? \"\").split(\";\")) {\n    const separator = cookie.indexOf(\"=\");\n    if (separator < 0 || cookie.slice(0, separator).trim() !== name) continue;\n    const value = cookie.slice(separator + 1).trim();\n    return /^[A-Za-z0-9_-]{43}$/.test(value) ? value : undefined;\n  }\n  return undefined;\n}\n\nexport class SessionHandle<T = unknown> {\n  private pendingCookie?: string;\n  constructor(private readonly manager: SessionManager<T>, public current?: SessionRecord<T>) {}\n  get cookieHeader(): string | undefined { return this.pendingCookie; }\n  async create(data: T): Promise<SessionRecord<T>> {\n    const previous = this.current;\n    const now = Date.now();\n    const record = { id: token(), familyId: previous?.familyId ?? previous?.id ?? token(), csrfToken: token(), data, createdAt: now, expiresAt: now + this.manager.ttlMs };\n    if (previous) {\n      if (!this.manager.store.replace) throw new Error(\"Session storage does not support atomic rotation\");\n      if (!(await this.manager.store.replace(previous.id, record))) throw new Error(\"Session has expired or been revoked\");\n    } else await this.manager.store.set(record);\n    this.current = record;\n    this.pendingCookie = this.manager.serializeCookie(record.id, this.manager.ttlMs);\n    return record;\n  }\n  async rotate(): Promise<SessionRecord<T>> {\n    if (!this.current) throw new Error(\"No active session to rotate\");\n    return this.create(this.current.data);\n  }\n  async revoke(): Promise<void> {\n    if (this.current) {\n      if (!this.manager.store.revokeFamily) throw new Error(\"Session storage does not support atomic family revocation\");\n      await this.manager.store.revokeFamily(this.current.familyId ?? this.current.id);\n    }\n    this.current = undefined;\n    this.pendingCookie = this.manager.serializeCookie(\"\", 0);\n  }\n}\n\nexport class SessionManager<T = unknown> {\n  readonly store: SessionStore<T>;\n  readonly ttlMs: number;\n  readonly cookieName: string;\n  readonly allowedOrigins: readonly string[];\n  private readonly secure: boolean;\n  private readonly sameSite: \"Lax\" | \"Strict\" | \"None\";\n  constructor(options: SessionOptions<T>) {\n    if (options.production && (options.store.persistent !== true || !options.store.replace || !options.store.revokeFamily)) throw new Error(\"Persistent session storage with atomic rotation and family revocation is required in production\");\n    this.store = options.store;\n    this.ttlMs = options.ttlMs ?? 7 * 24 * 60 * 60 * 1000;\n    if (!Number.isSafeInteger(this.ttlMs) || this.ttlMs <= 0) throw new RangeError(\"Invalid session TTL\");\n    this.secure = options.secure ?? true;\n    this.sameSite = options.sameSite ?? \"Lax\";\n    if (this.sameSite === \"None\" && !this.secure) throw new Error(\"SameSite=None requires Secure\");\n    this.cookieName = options.cookieName ?? (this.secure ? \"__Host-meeko.sid\" : \"meeko.sid\");\n    if (!/^[A-Za-z0-9_.-]+$/.test(this.cookieName)) throw new TypeError(\"Invalid cookie name\");\n    if (this.cookieName.startsWith(\"__Host-\") && !this.secure) throw new Error(\"__Host- cookies require Secure\");\n    this.allowedOrigins = options.allowedOrigins ?? [];\n  }\n  serializeCookie(value: string, ttlMs: number): string {\n    const parts = [`${this.cookieName}=${value}`, \"Path=/\", \"HttpOnly\", `SameSite=${this.sameSite}`, `Max-Age=${Math.floor(ttlMs / 1000)}`];\n    if (this.secure) parts.push(\"Secure\");\n    return parts.join(\"; \");\n  }\n  async load(request: Request): Promise<SessionHandle<T>> {\n    const id = cookieValue(request.headers.get(\"cookie\"), this.cookieName);\n    const record = id ? await this.store.get(id) : undefined;\n    if (record && record.expiresAt <= Date.now()) {\n      await this.store.delete(record.id);\n      return new SessionHandle(this);\n    }\n    return new SessionHandle(this, record);\n  }\n  async close(): Promise<void> { await this.store.close?.(); }\n  /** Apply both Origin and token checks to authenticated cookie mutations. */\n  assertMutationAllowed(request: Request, session: SessionHandle<T>, mutating = ![\"GET\", \"HEAD\", \"OPTIONS\"].includes(request.method)): void {\n    if (!session.current || !mutating) return;\n    const origin = request.headers.get(\"origin\");\n    const expected = new URL(request.url).origin;\n    if (!origin || (origin !== expected && !this.allowedOrigins.includes(origin))) throw new SessionSecurityError(\"INVALID_ORIGIN\");\n    if (request.headers.get(\"x-meeko-csrf\") !== session.current.csrfToken) throw new SessionSecurityError(\"INVALID_CSRF\");\n  }\n}\n\nexport class SessionSecurityError extends Error {\n  constructor(public readonly code: \"INVALID_ORIGIN\" | \"INVALID_CSRF\") { super(code); }\n}\n"]}

package/dist/framework-server/socket.d.ts

@@ -0,0 +1,83 @@
+import { type RequestContext } from "./context.js";
+import { type Schema } from "./contracts.js";
+import type { SessionManager } from "./sessions.js";
+type Output<S> = S extends Schema<unknown, infer O> ? O : never;
+type SchemaMap = Readonly<Record<string, Schema>>;
+export interface SocketPeer {
+    send(message: string): void | Promise<void>;
+    close(code?: number, reason?: string): void;
+    readonly bufferedAmount?: number;
+}
+export interface SocketChannelDefinition<C extends SchemaMap, S extends SchemaMap, TServices = unknown> {
+    clientToServer: C;
+    serverToClient: S;
+    auth?: "required" | "optional";
+    authorize?: (args: {
+        context: RequestContext<TServices>;
+        roomId?: string;
+    }) => boolean | Promise<boolean>;
+    authorizeEvent?: (args: {
+        event: keyof C & string;
+        payload: unknown;
+        context: RequestContext<TServices>;
+        roomId?: string;
+    }) => boolean | Promise<boolean>;
+    authorizeSend?: (args: {
+        event: keyof S & string;
+        payload: unknown;
+        context: RequestContext<TServices>;
+        roomId?: string;
+    }) => boolean | Promise<boolean>;
+    handlers?: {
+        [K in keyof C]?: (args: {
+            payload: Output<C[K]>;
+            context: RequestContext<TServices>;
+            roomId?: string;
+            emit: <E extends keyof S & string>(event: E, payload: Output<S[E]>) => Promise<void>;
+        }) => void | Promise<void>;
+    };
+}
+export declare function defineSocketChannel<C extends SchemaMap, S extends SchemaMap, TServices = unknown>(definition: SocketChannelDefinition<C, S, TServices>): SocketChannelDefinition<C, S, TServices>;
+export interface SocketPubSub {
+    publish(channel: string, room: string, message: {
+        event: string;
+        payload: unknown;
+    }): Promise<void>;
+    subscribe(channel: string, room: string, listener: (message: {
+        event: string;
+        payload: unknown;
+    }) => void | Promise<void>): () => void;
+}
+export declare class LocalSocketPubSub implements SocketPubSub {
+    private readonly listeners;
+    publish(channel: string, room: string, message: {
+        event: string;
+        payload: unknown;
+    }): Promise<void>;
+    subscribe(channel: string, room: string, listener: (message: {
+        event: string;
+        payload: unknown;
+    }) => void | Promise<void>): () => void;
+}
+export interface SocketConnection {
+    receive(message: string | Uint8Array): Promise<void>;
+    emit(event: string, payload: unknown): Promise<void>;
+    close(code?: number, reason?: string): void;
+}
+export interface SocketHubOptions<TServices = unknown> {
+    channels: Readonly<Record<string, unknown>>;
+    sessions: SessionManager;
+    services: TServices | ((request: Request) => TServices | Promise<TServices>);
+    allowedOrigins?: readonly string[];
+    maxMessageBytes?: number;
+    maxBufferBytes?: number;
+    pubsub?: SocketPubSub;
+}
+export interface SocketHub {
+    preflight(name: string, request: Request, roomId?: string): Promise<void>;
+    accept(name: string, request: Request, peer: SocketPeer, roomId?: string): Promise<SocketConnection>;
+    broadcast(name: string, roomId: string, event: string, payload: unknown): Promise<void>;
+}
+/** The host performs the HTTP upgrade, then passes its connected peer here. */
+export declare function createSocketHub<TServices>(options: SocketHubOptions<TServices>): SocketHub;
+export {};