SessionManager

SessionManager es el gestor de sesiones de una aplicación de Meeko. Guarda las sesiones en un SessionStore y las identifica con una cookie opaca (__Host-meeko.sid por defecto) HttpOnly, host-only, Secure y SameSite=Lax. En cada petición, load lee la cookie y devuelve el SessionHandle que llega a páginas, API, RPC y Socket como context.session; en las mutaciones con cookie, assertMutationAllowed comprueba Origin y el token x-meeko-csrf.

Se declara en sessions de server/runtime.ts. Desde 1.2 es opcional: sin él, Meeko crea uno en memoria en desarrollo y en Redis con MEEKO_REDIS_URL en producción (véase Sesiones sin configuración). Un SessionManager propio siempre gana.

Uso#

// server/runtime.ts
import { createClient } from "redis";
import { defineServerRuntime, RedisSessionStore, SessionManager } from "@meekojs/meeko/server";

export default defineServerRuntime(async ({ env, production, prerendering }) => {
  const redis = createClient({ url: env.MEEKO_REDIS_URL });
  await redis.connect();
  return {
    sessions: new SessionManager({
      store: new RedisSessionStore(redis, { prefix: "tienda:prod:session:" }),
      production: production && !prerendering,
    }),
    close: async () => { await redis.quit(); },
  };
});

production && !prerendering: durante el prerender de meeko build la fábrica también se ejecuta, sin tráfico de clientes, y ahí no hace falta un store persistente.

Tipo#

class SessionManager<T = unknown> {
  readonly store: SessionStore<T>;
  readonly ttlMs: number;
  readonly cookieName: string;
  readonly allowedOrigins: readonly string[];
  constructor(options: SessionOptions<T>);
  serializeCookie(value: string, ttlMs: number): string;
  load(request: Request): Promise<SessionHandle<T>>;
  rateLimit(key: string, windowMs: number): Promise<RateLimitHit>;
  close(): Promise<void>;
  assertMutationAllowed(
    request: Request,
    session: SessionHandle<T>,
    mutating?: boolean,
  ): void;
}

interface SessionOptions<T> {
	store: SessionStore<T>
	production?: boolean
	ttlMs?: number
	secure?: boolean
	sameSite?: 'Lax' | 'Strict' | 'None'
	cookieName?: string
	allowedOrigins?: readonly string[]
}

interface SessionStore<T = unknown> {
  readonly persistent?: boolean;
  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>;
  subscribeRevocations?(
    listener: (familyId: string) => void,
  ): Unsubscribe | Promise<Unsubscribe>;
  rateLimit?(key: string, windowMs: number): Promise<RateLimitHit>;
  close?(): Promise<void>;
}

interface SessionRecord<T = unknown> {
	id: string
	familyId?: string
	csrfToken: string
	data: T
	createdAt: number
	expiresAt: number
	ttlMs?: number
}

Parámetros#

new SessionManager(options) recibe un objeto SessionOptions<T>:

Valor devuelto#

Una instancia con estos miembros:

Con las opciones por defecto, la cookie es __Host-meeko.sid=<id>; Path=/; HttpOnly; SameSite=Lax; Max-Age=604800; Secure.

Ejemplos#

Sesiones en SQL con duración y orígenes propios#

// server/runtime.ts
import { defineServerRuntime, SessionManager, SqlSessionStore } from "@meekojs/meeko/server";
import { createPool, sessionDriver } from "./utils/database";

export default defineServerRuntime(async ({ env, production, prerendering }) => {
  const pool = await createPool(env.DATABASE_URL);
  return {
    sessions: new SessionManager({
      store: new SqlSessionStore(sessionDriver(pool)),
      production: production && !prerendering,
      ttlMs: 12 * 60 * 60 * 1000,                  // 12 horas
      sameSite: "Strict",
      allowedOrigins: ["https://admin.example.com"], // el panel, en otro subdominio
    }),
    close: () => pool.end(),
  };
});

Un tipo de sesión para toda la aplicación#

SessionManager<T> acepta los datos de la sesión como parámetro de tipo, pero context.session sigue a MeekoSession. Declárela una vez y los datos quedan tipados en páginas, API, RPC y Socket:

// server/types/session.d.ts
import type {} from "@meekojs/meeko/server";
declare module "@meekojs/meeko/server" {
  interface MeekoSession { userId: string; role: "owner" | "staff" }
}

Comprobar Origin y CSRF en un host propio#

createServerApp ya hace esto en API y RPC. Un host que atiende sus propias rutas con la sesión de Meeko lo hace a mano:

import { MemorySessionStore, SessionManager, SessionSecurityError } from "@meekojs/meeko/server";

const sessions = new SessionManager({ store: new MemorySessionStore(), secure: false });

export async function handle(request: Request): Promise<Response> {
  const session = await sessions.load(request);
  try {
    sessions.assertMutationAllowed(request, session);
  } catch (error) {
    if (error instanceof SessionSecurityError) return Response.json({ code: error.code }, { status: 403 });
    throw error;
  }
  const headers = new Headers();
  if (session.cookieHeader) headers.append("set-cookie", session.cookieHeader);
  return new Response(session.current ? "con sesión" : "anónimo", { headers });
}

Despliegue tras un proxy HTTPS#

MEEKO_PUBLIC_ORIGIN=https://tienda.example.com   # el origen que ve el navegador
MEEKO_REDIS_URL=rediss://default:…@redis.example.com:6380
MEEKO_TRUST_PROXY=1                              # Traefik, Caddy o nginx delante
# MEEKO_TRUST_PROXY=cloudflare                   # desde 1.8, tras Cloudflare Tunnel: CF-Connecting-IP

El navegador envía Origin: https://tienda.example.com; createServerApp construye la URL de la petición con MEEKO_PUBLIC_ORIGIN, así que assertMutationAllowed la acepta aunque el proxy hable HTTP con la aplicación.

Errores comunes#

Un store en memoria en producción#

new SessionManager({ store: new MemorySessionStore(), production: true });

El constructor lanza Error: Persistent session storage with atomic rotation and family revocation is required in production y la aplicación no arranca. Un store en memoria pierde las sesiones al reiniciar y no se comparte entre instancias.

new SessionManager({ store: new RedisSessionStore(redis, { prefix: "app:prod:session:" }), production: production && !prerendering });

Producción sin sessions ni MEEKO_REDIS_URL#

server/runtime.ts sin sessions, y el servidor arranca sin MEEKO_REDIS_URL

meeko start (y cada adaptador) se detiene con Production requires a persistent session store: set MEEKO_REDIS_URL (with the redis package installed), or return { sessions } with a persistent SessionStore from server/runtime.ts. En Workers, MEEKO_REDIS_URL tampoco vale: MEEKO_REDIS_URL needs TCP connections, which Cloudflare Workers do not offer….

MEEKO_REDIS_URL=rediss://…  y  npm install redis

SameSite=None o __Host- sin Secure#

new SessionManager({ store, sameSite: "None", secure: false });

El constructor lanza Error: SameSite=None requires Secure. Con cookieName: "__Host-sid" y secure: false, Error: __Host- cookies require Secure. Los navegadores rechazan esas cookies.

new SessionManager({ store, sameSite: "None", secure: true });

Una duración que no es un entero#

new SessionManager({ store, ttlMs: 1.5 * 24 * 60 * 60 * 1000 + 0.5 });

RangeError: Invalid session TTL. Use un entero positivo de milisegundos.

new SessionManager({ store, ttlMs: 36 * 60 * 60 * 1000 });

Notas#

• Sólo servidor. Se importa de @meekojs/meeko/server y vive en server/runtime.ts; la cookie es HttpOnly, así que el navegador nunca ve el ID. El token CSRF llega por la meta meeko-csrf-token y la cabecera x-meeko-csrf-token, y los clientes api.* y rpc.* lo envían solos.
• CSRF y Origin. Las mutaciones (POST, PUT, PATCH, DELETE) con cookie exigen un Origin permitido y x-meeko-csrf; un fallo responde 403 INVALID_ORIGIN o 403 INVALID_CSRF. Sin sesión no hay token que comprobar, pero desde 1.8 toda mutación exige igualmente un Origin permitido, salvo una ruta con origin: "none"; session.create() ya rechazaba un Origin ajeno desde 1.2.
• Proxies. El origen propio sale de publicOrigin o MEEKO_PUBLIC_ORIGIN, nunca de la cabecera Host. Si no lo configura tras un proxy que termina TLS, las mutaciones de un navegador fallan con INVALID_ORIGIN.
• Variables de entorno. MEEKO_SESSION_TTL y MEEKO_SESSION_SAMESITE sólo ajustan las sesiones que Meeko crea sin configuración; con un SessionManager propio no se aplican y Meeko lo avisa una vez.
• Revocación entre instancias. Con un store que implementa subscribeRevocations (RedisSessionStore con subscriber), revocar una familia aborta las peticiones y cierra los sockets de esa familia en todas las instancias. SqlSessionStore y D1 no notifican: las demás instancias lo detectan al releer la sesión.
• Cierre. close() libera el store, no el cliente Redis que creó la aplicación: ciérrelo en close de server/runtime.ts, que se ejecuta después.

Relacionado#

• SessionHandleLa sesión de una petición, en context.session, para leerla, crearla, rotarla, revocarla y verificarla antes de un efecto irreversible.
• MemorySessionStoreStore de sesiones en la memoria del proceso, sólo para desarrollo, pruebas y el prerender: no es persistente y SessionManager lo rechaza en producción.
• RedisSessionStoreStore de sesiones persistente en Redis, con caducidad de Redis, rotación y revocación atómicas, revocación entre instancias y contadores de rateLimit compartidos.
• SqlSessionStoreStore de sesiones persistente sobre cualquier base de datos SQL, con las sentencias de un driver de la aplicación y, desde 1.7, contadores de rateLimit en la base de datos.
• SessionSecurityErrorUna mutación no superó la comprobación de Origin o de CSRF de la sesión, con el código INVALID_ORIGIN o INVALID_CSRF; las respuestas de API y RPC la convierten en 403.
• defineServerRuntimeDeclara en server/runtime.ts las sesiones, los servicios, la política de Socket y el cierre de la aplicación, creados una vez por proceso.
• Sesiones y seguridadMeeko como framework full-stack
• Sesiones sin configuraciónMeeko como framework full-stack
• AutenticaciónMeeko como framework full-stack