tempest-express-sdk 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -5,6 +5,9 @@ var zodToOpenapi = require('@asteasolutions/zod-to-openapi');
 var zod = require('zod');
 var tempestDbJs = require('tempest-db-js');
 var crypto = require('crypto');
+var os = require('os');
+var promises = require('fs/promises');
+var path = require('path');
 var express2 = require('express');
 var swaggerUiDist = require('swagger-ui-dist');
 
@@ -6753,6 +6756,1279 @@ var AttemptThrottle = class {
   }
 };
 
+// src/utils/clientIp.ts
+var UNKNOWN = "unknown";
+function getClientIp(req, options = {}) {
+  if (options.trustedHeader) {
+    const value = req.header(options.trustedHeader);
+    if (value) return value.trim();
+  }
+  return req.socket?.remoteAddress ?? req.ip ?? UNKNOWN;
+}
+var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+function base32Encode(bytes) {
+  let bits = 0;
+  let value = 0;
+  let out = "";
+  for (const byte of bytes) {
+    value = value << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += BASE32_ALPHABET[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += BASE32_ALPHABET[value << 5 - bits & 31];
+  return out;
+}
+function base32Decode(secret) {
+  const clean = secret.toUpperCase().replace(/=+$/, "").replace(/\s/g, "");
+  let bits = 0;
+  let value = 0;
+  const out = [];
+  for (const char of clean) {
+    const index = BASE32_ALPHABET.indexOf(char);
+    if (index === -1) continue;
+    value = value << 5 | index;
+    bits += 5;
+    if (bits >= 8) {
+      out.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(out);
+}
+function hotp(secret, counter, digits) {
+  const buffer = Buffer.alloc(8);
+  buffer.writeUInt32BE(Math.floor(counter / 2 ** 32), 0);
+  buffer.writeUInt32BE(counter >>> 0, 4);
+  const digest = crypto.createHmac("sha1", secret).update(buffer).digest();
+  const offset = digest[digest.length - 1] & 15;
+  const binary = (digest[offset] & 127) << 24 | (digest[offset + 1] & 255) << 16 | (digest[offset + 2] & 255) << 8 | digest[offset + 3] & 255;
+  return (binary % 10 ** digits).toString().padStart(digits, "0");
+}
+var TOTPHelper = class {
+  issuer;
+  step;
+  digits;
+  /**
+   * @param options - Issuer label, time step and digit count.
+   */
+  constructor(options) {
+    this.issuer = options.issuer;
+    this.step = options.step ?? 30;
+    this.digits = options.digits ?? 6;
+  }
+  /**
+   * Generate a fresh base32 secret (80 bits).
+   *
+   * @returns A base32-encoded TOTP secret to persist on the user row.
+   */
+  generateSecret() {
+    return base32Encode(crypto.randomBytes(10));
+  }
+  /**
+   * Build the `otpauth://` provisioning URI (render as a QR code).
+   *
+   * @param secret - The base32 secret.
+   * @param accountName - Identifier shown next to the issuer (e.g. the email).
+   * @returns The `otpauth://totp/...` URI.
+   */
+  provisioningUri(secret, accountName) {
+    const label = encodeURIComponent(`${this.issuer}:${accountName}`);
+    const params = new URLSearchParams({
+      secret,
+      issuer: this.issuer,
+      algorithm: "SHA1",
+      digits: String(this.digits),
+      period: String(this.step)
+    });
+    return `otpauth://totp/${label}?${params.toString()}`;
+  }
+  /**
+   * Verify a code against the secret for the current time window.
+   *
+   * @param secret - The base32 secret.
+   * @param code - The submitted code.
+   * @param window - Tolerance in steps (±). Default 1 (previous/current/next).
+   * @returns `true` when the code matches within the window.
+   */
+  verify(secret, code, window = 1) {
+    const cleaned = code.trim().replace(/[\s-]/g, "");
+    if (!/^\d+$/.test(cleaned) || cleaned.length !== this.digits) return false;
+    const key = base32Decode(secret);
+    const counter = Math.floor(Date.now() / 1e3 / this.step);
+    for (let offset = -window; offset <= window; offset++) {
+      if (hotp(key, counter + offset, this.digits) === cleaned) return true;
+    }
+    return false;
+  }
+};
+
+// src/utils/httpClient.ts
+var CircuitOpenError = class extends Error {
+  constructor(host) {
+    super(`Circuit breaker is open for host ${host}`);
+    this.host = host;
+    this.name = "CircuitOpenError";
+  }
+  host;
+};
+var RetryPolicy = class {
+  /**
+   * @param maxRetries - Additional attempts after the first. Default 2.
+   * @param baseDelayMs - Base backoff in ms (doubles each attempt). Default 100.
+   * @param retryOn - HTTP status codes that trigger a retry. Default 5xx + 429.
+   */
+  constructor(maxRetries = 2, baseDelayMs = 100, retryOn = [429, 500, 502, 503, 504]) {
+    this.maxRetries = maxRetries;
+    this.baseDelayMs = baseDelayMs;
+    this.retryOn = retryOn;
+  }
+  maxRetries;
+  baseDelayMs;
+  retryOn;
+  /** Backoff delay in ms before `attempt` (0-indexed). */
+  sleepFor(attempt) {
+    return this.baseDelayMs * 2 ** attempt;
+  }
+};
+var HTTPClient = class {
+  baseUrl;
+  defaultHeaders;
+  timeoutMs;
+  retryPolicy;
+  breakerThreshold;
+  breakerCooldownMs;
+  breakers = /* @__PURE__ */ new Map();
+  /**
+   * @param options - Base URL, headers, timeout, retry and breaker settings.
+   */
+  constructor(options = {}) {
+    this.baseUrl = options.baseUrl ?? "";
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.retryPolicy = options.retryPolicy ?? new RetryPolicy();
+    this.breakerThreshold = options.breakerThreshold ?? 5;
+    this.breakerCooldownMs = options.breakerCooldownMs ?? 3e4;
+  }
+  resolve(url) {
+    return this.baseUrl && !/^https?:\/\//.test(url) ? `${this.baseUrl}${url}` : url;
+  }
+  hostOf(url) {
+    try {
+      return new URL(url).host;
+    } catch {
+      return url;
+    }
+  }
+  breakerCheck(host) {
+    const state = this.breakers.get(host);
+    if (state && state.openUntil > Date.now()) throw new CircuitOpenError(host);
+  }
+  breakerRecord(host, failed) {
+    const state = this.breakers.get(host) ?? { failures: 0, openUntil: 0 };
+    if (failed) {
+      state.failures += 1;
+      if (state.failures >= this.breakerThreshold) {
+        state.openUntil = Date.now() + this.breakerCooldownMs;
+        state.failures = 0;
+      }
+    } else {
+      state.failures = 0;
+      state.openUntil = 0;
+    }
+    this.breakers.set(host, state);
+  }
+  /**
+   * Perform a request with retries and breaker protection.
+   *
+   * @param method - HTTP method.
+   * @param url - Absolute URL or a path resolved against `baseUrl`.
+   * @param init - Extra `fetch` init (headers, body, …).
+   * @returns The `Response`.
+   * @throws {CircuitOpenError} When the per-host breaker is open.
+   */
+  async request(method, url, init = {}) {
+    const target = this.resolve(url);
+    const host = this.hostOf(target);
+    this.breakerCheck(host);
+    let lastError;
+    for (let attempt = 0; attempt <= this.retryPolicy.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      try {
+        const response = await fetch(target, {
+          ...init,
+          method,
+          headers: { ...this.defaultHeaders, ...init.headers ?? {} },
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        if (this.retryPolicy.retryOn.includes(response.status)) {
+          this.breakerRecord(host, true);
+          if (attempt < this.retryPolicy.maxRetries) {
+            await this.sleep(this.retryPolicy.sleepFor(attempt));
+            continue;
+          }
+          return response;
+        }
+        this.breakerRecord(host, false);
+        return response;
+      } catch (error) {
+        clearTimeout(timer);
+        lastError = error;
+        this.breakerRecord(host, true);
+        if (attempt < this.retryPolicy.maxRetries) {
+          await this.sleep(this.retryPolicy.sleepFor(attempt));
+          continue;
+        }
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error("Request failed");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /** GET request. */
+  get(url, init) {
+    return this.request("GET", url, init);
+  }
+  /** POST request. */
+  post(url, init) {
+    return this.request("POST", url, init);
+  }
+  /** PUT request. */
+  put(url, init) {
+    return this.request("PUT", url, init);
+  }
+  /** PATCH request. */
+  patch(url, init) {
+    return this.request("PATCH", url, init);
+  }
+  /** DELETE request. */
+  delete(url, init) {
+    return this.request("DELETE", url, init);
+  }
+};
+function readCpu() {
+  const cores = os.cpus().length;
+  const load1 = os.loadavg()[0] ?? 0;
+  return {
+    cores,
+    load1,
+    loadPercent: cores > 0 ? load1 / cores * 100 : 0
+  };
+}
+function readMemory() {
+  const total = os.totalmem();
+  const free = os.freemem();
+  const used = total - free;
+  return {
+    total,
+    free,
+    used,
+    usedPercent: total > 0 ? used / total * 100 : 0,
+    processRss: process.memoryUsage().rss
+  };
+}
+function readSystem() {
+  return {
+    cpu: readCpu(),
+    memory: readMemory(),
+    uptimeSeconds: process.uptime()
+  };
+}
+function toPrometheus(snapshot = readSystem()) {
+  const lines = [
+    "# HELP process_cpu_load_percent 1-minute load average as percent of cores",
+    "# TYPE process_cpu_load_percent gauge",
+    `process_cpu_load_percent ${snapshot.cpu.loadPercent}`,
+    "# HELP process_memory_used_percent System memory used percent",
+    "# TYPE process_memory_used_percent gauge",
+    `process_memory_used_percent ${snapshot.memory.usedPercent}`,
+    "# HELP process_memory_rss_bytes Resident set size of the process",
+    "# TYPE process_memory_rss_bytes gauge",
+    `process_memory_rss_bytes ${snapshot.memory.processRss}`,
+    "# HELP process_uptime_seconds Process uptime in seconds",
+    "# TYPE process_uptime_seconds counter",
+    `process_uptime_seconds ${snapshot.uptimeSeconds}`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+var MetricsUtils = {
+  cpu: readCpu,
+  memory: readMemory,
+  system: readSystem,
+  toPrometheus
+};
+
+// src/utils/email.ts
+var EmailUtils = class {
+  /**
+   * @param options - SMTP connection and default sender.
+   */
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  transport = null;
+  async ready() {
+    if (this.transport) return this.transport;
+    let nodemailer;
+    try {
+      const mod = await import('nodemailer');
+      nodemailer = mod.default ?? mod;
+    } catch (cause) {
+      throw new Error(
+        "EmailUtils requires the 'nodemailer' peer dependency. Install with `npm i nodemailer`.",
+        { cause }
+      );
+    }
+    this.transport = nodemailer.createTransport({
+      host: this.options.host,
+      port: this.options.port ?? 587,
+      secure: this.options.secure ?? false,
+      ...this.options.user ? { auth: { user: this.options.user, pass: this.options.password ?? "" } } : {}
+    });
+    return this.transport;
+  }
+  /**
+   * Send an email message.
+   *
+   * @param message - The message (recipients, subject, body).
+   */
+  async send(message) {
+    const transport = await this.ready();
+    await transport.sendMail({
+      from: message.from ?? this.options.from,
+      to: message.to,
+      subject: message.subject,
+      ...message.text !== void 0 ? { text: message.text } : {},
+      ...message.html !== void 0 ? { html: message.html } : {}
+    });
+  }
+};
+
+// src/cache/manager.ts
+var MemoryCacheManager = class {
+  store = /* @__PURE__ */ new Map();
+  live(key) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry;
+  }
+  async get(key) {
+    const entry = this.live(key);
+    return entry ? JSON.parse(entry.value) : null;
+  }
+  async set(key, value, ttlSeconds) {
+    this.store.set(key, {
+      value: JSON.stringify(value),
+      expiresAt: ttlSeconds !== void 0 ? Date.now() + ttlSeconds * 1e3 : null
+    });
+  }
+  async delete(key) {
+    this.store.delete(key);
+  }
+  async has(key) {
+    return this.live(key) !== null;
+  }
+  async clear() {
+    this.store.clear();
+  }
+};
+var RedisCacheManager = class {
+  /**
+   * @param client - A connected `redis` (node-redis v4) client or compatible.
+   * @param prefix - Optional key prefix applied to every operation.
+   */
+  constructor(client, prefix = "") {
+    this.client = client;
+    this.prefix = prefix;
+  }
+  client;
+  prefix;
+  key(key) {
+    return this.prefix ? `${this.prefix}${key}` : key;
+  }
+  async get(key) {
+    const raw = await this.client.get(this.key(key));
+    return raw === null ? null : JSON.parse(raw);
+  }
+  async set(key, value, ttlSeconds) {
+    const payload = JSON.stringify(value);
+    await this.client.set(
+      this.key(key),
+      payload,
+      ttlSeconds !== void 0 ? { EX: ttlSeconds } : void 0
+    );
+  }
+  async delete(key) {
+    await this.client.del(this.key(key));
+  }
+  async has(key) {
+    return await this.client.exists(this.key(key)) > 0;
+  }
+  async clear() {
+    await this.client.flushDb();
+  }
+};
+
+// src/cache/cached.ts
+function cached3(fn, options) {
+  return async (...args) => {
+    const key = options.key(...args);
+    const hit = await options.manager.get(key);
+    if (hit !== null) return hit;
+    const result = await fn(...args);
+    await options.manager.set(key, result, options.ttlSeconds);
+    return result;
+  };
+}
+
+// src/sessions/store.ts
+var MemorySessionStore = class {
+  byHash = /* @__PURE__ */ new Map();
+  live(session, idHash) {
+    if (!session) return null;
+    if (session.expiresAt <= Date.now()) {
+      this.byHash.delete(idHash);
+      return null;
+    }
+    return session;
+  }
+  async get(idHash) {
+    return this.live(this.byHash.get(idHash), idHash);
+  }
+  async set(session) {
+    this.byHash.set(session.idHash, session);
+  }
+  async delete(idHash) {
+    this.byHash.delete(idHash);
+  }
+  async deleteByUser(userId) {
+    let count = 0;
+    for (const [hash, session] of this.byHash) {
+      if (session.userId === userId) {
+        this.byHash.delete(hash);
+        count += 1;
+      }
+    }
+    return count;
+  }
+  async listByUser(userId) {
+    const now = Date.now();
+    return [...this.byHash.values()].filter((s) => s.userId === userId && s.expiresAt > now).sort((a, b) => a.createdAt - b.createdAt);
+  }
+};
+
+// src/sessions/service.ts
+var SessionService = class {
+  store;
+  ttlSeconds;
+  /**
+   * @param options - Store and default TTL.
+   */
+  constructor(options) {
+    this.store = options.store;
+    this.ttlSeconds = options.ttlSeconds ?? 60 * 60 * 24 * 7;
+  }
+  /**
+   * Create a session for `userId` and return its one-time cookie value.
+   *
+   * @param userId - The owning user id.
+   * @param data - Arbitrary session payload.
+   * @param ttlSeconds - Override the default lifetime.
+   * @returns The plaintext token (set as a cookie) and the stored session.
+   */
+  async create(userId, data = {}, ttlSeconds) {
+    const { plaintext, tokenHash } = generateOpaqueToken();
+    const now = Date.now();
+    const session = {
+      idHash: tokenHash,
+      userId,
+      data,
+      createdAt: now,
+      expiresAt: now + (ttlSeconds ?? this.ttlSeconds) * 1e3
+    };
+    await this.store.set(session);
+    return { token: plaintext, session };
+  }
+  /**
+   * Resolve an opaque cookie value to its live session.
+   *
+   * @param token - The plaintext cookie value.
+   * @returns The session, or `null` when missing/expired.
+   */
+  async resolve(token) {
+    return this.store.get(hashOpaqueToken(token));
+  }
+  /**
+   * Revoke a single session by its cookie value.
+   *
+   * @param token - The plaintext cookie value.
+   */
+  async destroy(token) {
+    await this.store.delete(hashOpaqueToken(token));
+  }
+  /**
+   * Revoke every session a user owns (global logout).
+   *
+   * @param userId - The user id.
+   * @returns The number of sessions removed.
+   */
+  async destroyByUser(userId) {
+    return this.store.deleteByUser(userId);
+  }
+  /**
+   * List a user's live sessions (e.g. an "active devices" view).
+   *
+   * @param userId - The user id.
+   * @returns The user's sessions, oldest first.
+   */
+  async listByUser(userId) {
+    return this.store.listByUser(userId);
+  }
+};
+
+// src/sessions/middleware.ts
+function parseCookies(header) {
+  const out = {};
+  if (!header) return out;
+  for (const part of header.split(";")) {
+    const index = part.indexOf("=");
+    if (index < 0) continue;
+    const name = part.slice(0, index).trim();
+    const value = part.slice(index + 1).trim();
+    if (name) out[name] = decodeURIComponent(value);
+  }
+  return out;
+}
+function sessionCookie(req, cookieName) {
+  return parseCookies(req.header("cookie") ?? void 0)[cookieName] ?? null;
+}
+function makeSessionMiddleware(service, options = {}) {
+  const cookieName = options.cookieName ?? "sid";
+  return (req, _res, next) => {
+    const token = sessionCookie(req, cookieName);
+    if (!token) {
+      req.session = null;
+      next();
+      return;
+    }
+    service.resolve(token).then((session) => {
+      req.session = session;
+      next();
+    }).catch(next);
+  };
+}
+
+// src/sse/eventStream.ts
+var ServerSentEvent = class {
+  constructor(init) {
+    this.init = init;
+  }
+  init;
+  /**
+   * Encode to the SSE wire format (terminated by a blank line).
+   *
+   * @returns The encoded event block.
+   */
+  encode() {
+    const lines = [];
+    if (this.init.event) lines.push(`event: ${this.init.event}`);
+    if (this.init.id) lines.push(`id: ${this.init.id}`);
+    if (this.init.retry !== void 0) lines.push(`retry: ${this.init.retry}`);
+    for (const line of this.init.data.split("\n")) lines.push(`data: ${line}`);
+    return `${lines.join("\n")}
+
+`;
+  }
+};
+function deferred() {
+  let resolve;
+  const promise = new Promise((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+var EventStream = class {
+  queue = [];
+  waiter = null;
+  closed = false;
+  heartbeatSeconds;
+  /**
+   * @param options - Heartbeat configuration.
+   */
+  constructor(options = {}) {
+    this.heartbeatSeconds = options.heartbeatSeconds ?? 15;
+  }
+  /** Enqueue raw SSE-encoded text and wake the iterator. */
+  push(raw) {
+    if (this.closed) return;
+    this.queue.push(raw);
+    this.waiter?.resolve();
+    this.waiter = null;
+  }
+  /**
+   * Publish a data payload as an SSE event.
+   *
+   * @param data - The payload; objects are JSON-encoded.
+   * @param event - Optional event name.
+   */
+  publish(data, event) {
+    const payload = typeof data === "string" ? data : JSON.stringify(data);
+    this.push(
+      new ServerSentEvent({ data: payload, ...event ? { event } : {} }).encode()
+    );
+  }
+  /** Publish a pre-built {@link ServerSentEvent}. */
+  publishEvent(event) {
+    this.push(event.encode());
+  }
+  /** Close the stream; the iterator finishes after draining. */
+  close() {
+    this.closed = true;
+    this.waiter?.resolve();
+    this.waiter = null;
+  }
+  /**
+   * Async iterator yielding encoded SSE chunks, with periodic heartbeats.
+   *
+   * @returns An async iterator of encoded event strings.
+   */
+  async *stream() {
+    const heartbeatMs = this.heartbeatSeconds !== null ? this.heartbeatSeconds * 1e3 : null;
+    while (!this.closed || this.queue.length > 0) {
+      if (this.queue.length > 0) {
+        yield this.queue.shift();
+        continue;
+      }
+      if (this.closed) break;
+      this.waiter = deferred();
+      if (heartbeatMs === null) {
+        await this.waiter.promise;
+      } else {
+        let timer;
+        const heartbeat = new Promise((resolve) => {
+          timer = setTimeout(resolve, heartbeatMs);
+        });
+        await Promise.race([this.waiter.promise, heartbeat]);
+        if (timer) clearTimeout(timer);
+        if (this.queue.length === 0 && !this.closed) yield ": ping\n\n";
+      }
+    }
+  }
+};
+async function sseResponse(req, res, stream) {
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.flushHeaders?.();
+  req.on("close", () => stream.close());
+  for await (const chunk of stream.stream()) {
+    if (res.writableEnded) break;
+    res.write(chunk);
+  }
+  res.end();
+}
+
+// src/sse/broker.ts
+var SSEBroker = class {
+  /**
+   * @param streamOptions - Options applied to every {@link EventStream} created
+   *   by {@link register} (e.g. heartbeat interval).
+   */
+  constructor(streamOptions = {}) {
+    this.streamOptions = streamOptions;
+  }
+  streamOptions;
+  channels = /* @__PURE__ */ new Map();
+  /**
+   * Register a new subscriber stream on `channel`.
+   *
+   * @param channel - The channel name.
+   * @returns A fresh {@link EventStream} to serve to the subscriber.
+   */
+  register(channel) {
+    const stream = new EventStream(this.streamOptions);
+    const set = this.channels.get(channel) ?? /* @__PURE__ */ new Set();
+    set.add(stream);
+    this.channels.set(channel, set);
+    return stream;
+  }
+  /**
+   * Remove a subscriber stream from `channel` and close it.
+   *
+   * @param channel - The channel name.
+   * @param stream - The stream to remove.
+   */
+  unregister(channel, stream) {
+    const set = this.channels.get(channel);
+    if (!set) return;
+    set.delete(stream);
+    stream.close();
+    if (set.size === 0) this.channels.delete(channel);
+  }
+  /**
+   * Number of live subscribers on `channel`.
+   *
+   * @param channel - The channel name.
+   * @returns The subscriber count.
+   */
+  localSubscribers(channel) {
+    return this.channels.get(channel)?.size ?? 0;
+  }
+  /**
+   * Publish an event to every subscriber on `channel`.
+   *
+   * @param channel - The channel name.
+   * @param data - The payload (objects are JSON-encoded).
+   * @param event - Optional event name.
+   * @returns The number of subscribers the event was delivered to.
+   */
+  publish(channel, data, event) {
+    const set = this.channels.get(channel);
+    if (!set) return 0;
+    for (const stream of set) stream.publish(data, event);
+    return set.size;
+  }
+};
+
+// src/websockets/schemas.ts
+var wsEnvelopeSchema = zod.z.object({
+  type: zod.z.string().openapi({ description: "Message type discriminator." }),
+  data: zod.z.unknown().optional().openapi({ description: "Arbitrary payload." })
+}).openapi("WSEnvelope");
+var WebSocketHub = class {
+  byId = /* @__PURE__ */ new Map();
+  byUser = /* @__PURE__ */ new Map();
+  maxPerUser;
+  /**
+   * @param options - Per-user connection cap.
+   */
+  constructor(options = {}) {
+    this.maxPerUser = options.maxPerUser ?? 5;
+  }
+  /**
+   * Register a new connection for `userId`, evicting the oldest if over cap.
+   *
+   * @param userId - The owning user id.
+   * @param ws - The socket to register.
+   * @returns The created connection record.
+   */
+  register(userId, ws) {
+    const connection = {
+      id: crypto.randomUUID(),
+      userId,
+      ws,
+      topics: /* @__PURE__ */ new Set()
+    };
+    this.byId.set(connection.id, connection);
+    const ids = this.byUser.get(userId) ?? /* @__PURE__ */ new Set();
+    ids.add(connection.id);
+    this.byUser.set(userId, ids);
+    if (ids.size > this.maxPerUser) {
+      const oldest = ids.values().next().value;
+      if (oldest) this.unregister(oldest, 1008);
+    }
+    return connection;
+  }
+  /**
+   * Remove a connection and close its socket.
+   *
+   * @param connectionId - The connection id.
+   * @param code - Optional WebSocket close code.
+   */
+  unregister(connectionId, code) {
+    const connection = this.byId.get(connectionId);
+    if (!connection) return;
+    this.byId.delete(connectionId);
+    const ids = this.byUser.get(connection.userId);
+    if (ids) {
+      ids.delete(connectionId);
+      if (ids.size === 0) this.byUser.delete(connection.userId);
+    }
+    try {
+      connection.ws.close(code);
+    } catch {
+    }
+  }
+  /** Subscribe a connection to a topic. */
+  subscribe(connectionId, topic) {
+    this.byId.get(connectionId)?.topics.add(topic);
+  }
+  /** Unsubscribe a connection from a topic. */
+  unsubscribe(connectionId, topic) {
+    this.byId.get(connectionId)?.topics.delete(topic);
+  }
+  /** Serialize and send an envelope to a single connection. */
+  deliver(connection, payload) {
+    try {
+      connection.ws.send(payload);
+      return true;
+    } catch {
+      this.unregister(connection.id);
+      return false;
+    }
+  }
+  /**
+   * Send an envelope to every connection of `userId`.
+   *
+   * @param userId - The target user.
+   * @param envelope - The message envelope.
+   * @returns The number of connections delivered to.
+   */
+  sendTo(userId, envelope) {
+    const ids = this.byUser.get(userId);
+    if (!ids) return 0;
+    const payload = JSON.stringify(envelope);
+    let count = 0;
+    for (const id of [...ids]) {
+      const connection = this.byId.get(id);
+      if (connection && this.deliver(connection, payload)) count += 1;
+    }
+    return count;
+  }
+  /**
+   * Broadcast an envelope to all connections, or only a topic's subscribers.
+   *
+   * @param envelope - The message envelope.
+   * @param topic - Optional topic to scope the broadcast.
+   * @returns The number of connections delivered to.
+   */
+  broadcast(envelope, topic) {
+    const payload = JSON.stringify(envelope);
+    let count = 0;
+    for (const connection of [...this.byId.values()]) {
+      if (topic && !connection.topics.has(topic)) continue;
+      if (this.deliver(connection, payload)) count += 1;
+    }
+    return count;
+  }
+  /** The set of users with at least one live connection. */
+  onlineUsers() {
+    return new Set(this.byUser.keys());
+  }
+  /** Total live connection count. */
+  connectionCount() {
+    return this.byId.size;
+  }
+  /** Number of connections subscribed to `topic`. */
+  topicCount(topic) {
+    let count = 0;
+    for (const connection of this.byId.values()) {
+      if (connection.topics.has(topic)) count += 1;
+    }
+    return count;
+  }
+};
+
+// src/websockets/attach.ts
+function tokenFromUrl(url) {
+  const query = url.includes("?") ? url.slice(url.indexOf("?") + 1) : "";
+  return new URLSearchParams(query).get("token");
+}
+async function attachWebSocketHub(server, hub, options = {}) {
+  let ws;
+  try {
+    ws = await import('ws');
+  } catch (cause) {
+    throw new Error(
+      "attachWebSocketHub requires the 'ws' peer dependency. Install with `npm i ws`.",
+      { cause }
+    );
+  }
+  const path = options.path ?? "/ws";
+  const heartbeatMs = (options.heartbeatSeconds ?? 30) * 1e3;
+  const authenticate = options.authenticate ?? (() => "anonymous");
+  const wss = new ws.WebSocketServer({ server, path });
+  wss.on("connection", (socket, req) => {
+    void (async () => {
+      const userId = await authenticate({
+        url: req.url ?? "",
+        headers: req.headers
+      });
+      if (userId === null) {
+        socket.close(1008);
+        return;
+      }
+      const connection = hub.register(userId, socket);
+      let alive = true;
+      socket.on("pong", () => {
+        alive = true;
+      });
+      socket.on("message", (data) => {
+        options.onMessage?.(connection, String(data));
+      });
+      socket.on("close", () => {
+        alive = false;
+        hub.unregister(connection.id);
+      });
+      if (heartbeatMs > 0) {
+        const timer = setInterval(() => {
+          if (!alive) {
+            clearInterval(timer);
+            hub.unregister(connection.id);
+            return;
+          }
+          alive = false;
+          socket.ping();
+        }, heartbeatMs);
+        socket.on("close", () => clearInterval(timer));
+      }
+    })();
+  });
+  return wss;
+}
+
+// src/queue/broker.ts
+var MemoryBroker = class {
+  handlers = /* @__PURE__ */ new Map();
+  async publish(queue, message) {
+    const set = this.handlers.get(queue);
+    if (!set) return;
+    const payload = JSON.parse(JSON.stringify(message));
+    for (const handler of [...set]) await handler(payload);
+  }
+  async subscribe(queue, handler) {
+    const set = this.handlers.get(queue) ?? /* @__PURE__ */ new Set();
+    set.add(handler);
+    this.handlers.set(queue, set);
+    return async () => {
+      set.delete(handler);
+      if (set.size === 0) this.handlers.delete(queue);
+    };
+  }
+  async close() {
+    this.handlers.clear();
+  }
+};
+var RabbitBroker = class {
+  /**
+   * @param options - Connection URL and queue durability.
+   */
+  constructor(options) {
+    this.options = options;
+    this.durable = options.durable ?? true;
+  }
+  options;
+  connection = null;
+  channel = null;
+  durable;
+  /** Lazily connect and open a channel. */
+  async ready() {
+    if (this.channel) return this.channel;
+    let amqp;
+    try {
+      amqp = await import('amqplib');
+    } catch (cause) {
+      throw new Error(
+        "RabbitBroker requires the 'amqplib' peer dependency. Install with `npm i amqplib`.",
+        { cause }
+      );
+    }
+    this.connection = await amqp.connect(this.options.url);
+    this.channel = await this.connection.createChannel();
+    return this.channel;
+  }
+  async publish(queue, message) {
+    const channel = await this.ready();
+    await channel.assertQueue(queue, { durable: this.durable });
+    channel.sendToQueue(queue, Buffer.from(JSON.stringify(message)), {
+      persistent: this.durable
+    });
+  }
+  async subscribe(queue, handler) {
+    const channel = await this.ready();
+    await channel.assertQueue(queue, { durable: this.durable });
+    const { consumerTag } = await channel.consume(queue, (msg) => {
+      if (!msg) return;
+      void Promise.resolve(handler(JSON.parse(msg.content.toString()))).then(() => channel.ack(msg)).catch(() => channel.nack(msg, false, false));
+    });
+    return async () => {
+      await channel.cancel(consumerTag);
+    };
+  }
+  async close() {
+    await this.channel?.close();
+    await this.connection?.close();
+    this.channel = null;
+    this.connection = null;
+  }
+};
+
+// src/tasks/manager.ts
+var logger = new JSONLogger("tempest_express_sdk.tasks");
+var TaskManager = class {
+  broker;
+  queue;
+  handlers = /* @__PURE__ */ new Map();
+  unsubscribe = null;
+  /**
+   * @param options - Broker and queue name.
+   */
+  constructor(options = {}) {
+    this.broker = options.broker ?? new MemoryBroker();
+    this.queue = options.queue ?? "tasks";
+  }
+  /**
+   * Register a handler for a named task.
+   *
+   * @param name - The task name.
+   * @param handler - The handler invoked with the task payload.
+   */
+  register(name, handler) {
+    this.handlers.set(name, handler);
+  }
+  /**
+   * Enqueue a task by name.
+   *
+   * @param name - The registered task name.
+   * @param payload - The JSON-serializable payload.
+   */
+  async enqueue(name, payload = {}) {
+    const envelope = { name, payload };
+    await this.broker.publish(this.queue, envelope);
+  }
+  /**
+   * Start the worker: subscribe to the task queue and dispatch to handlers.
+   * A task with no registered handler is logged and skipped.
+   */
+  async start() {
+    if (this.unsubscribe) return;
+    this.unsubscribe = await this.broker.subscribe(this.queue, async (message) => {
+      const { name, payload } = message;
+      const handler = this.handlers.get(name);
+      if (!handler) {
+        logger.warning("No handler for task", { task: name });
+        return;
+      }
+      await handler(payload);
+    });
+  }
+  /** Stop the worker (stops consuming; does not close the broker). */
+  async stop() {
+    await this.unsubscribe?.();
+    this.unsubscribe = null;
+  }
+};
+
+// src/flags/backends.ts
+function coerceFlag(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") {
+    return ["1", "true", "on", "yes", "enabled"].includes(value.trim().toLowerCase());
+  }
+  return false;
+}
+var MemoryFeatureFlagBackend = class {
+  flags = /* @__PURE__ */ new Map();
+  /**
+   * @param initial - Initial flag → enabled map.
+   */
+  constructor(initial = {}) {
+    for (const [flag, enabled] of Object.entries(initial)) this.flags.set(flag, enabled);
+  }
+  /** Set or override a flag. */
+  set(flag, enabled) {
+    this.flags.set(flag, enabled);
+  }
+  resolve(flag) {
+    return this.flags.has(flag) ? this.flags.get(flag) : null;
+  }
+};
+var EnvFeatureFlagBackend = class {
+  /**
+   * @param env - Environment source (defaults to `process.env`).
+   * @param prefix - Env var prefix. Default `FLAG_`.
+   */
+  constructor(env = process.env, prefix = "FLAG_") {
+    this.env = env;
+    this.prefix = prefix;
+  }
+  env;
+  prefix;
+  key(flag) {
+    return this.prefix + flag.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+  }
+  resolve(flag) {
+    const raw = this.env[this.key(flag)];
+    return raw === void 0 ? null : coerceFlag(raw);
+  }
+};
+var CompositeFeatureFlagBackend = class {
+  /**
+   * @param backends - Backends in priority order.
+   */
+  constructor(backends) {
+    this.backends = backends;
+  }
+  backends;
+  async resolve(flag, context) {
+    for (const backend of this.backends) {
+      const answer = await backend.resolve(flag, context);
+      if (answer !== null) return answer;
+    }
+    return null;
+  }
+};
+
+// src/flags/service.ts
+var FeatureFlags = class {
+  /**
+   * @param backend - The resolving backend.
+   * @param defaultEnabled - Value used when the backend returns `null`.
+   */
+  constructor(backend, defaultEnabled = false) {
+    this.backend = backend;
+    this.defaultEnabled = defaultEnabled;
+  }
+  backend;
+  defaultEnabled;
+  /**
+   * Whether `flag` is enabled for the given context.
+   *
+   * @param flag - The flag name.
+   * @param context - Optional evaluation context.
+   * @returns `true` when enabled (or default when the backend is undecided).
+   */
+  async isEnabled(flag, context) {
+    const answer = await this.backend.resolve(flag, context);
+    return answer ?? this.defaultEnabled;
+  }
+};
+function makeFlagGuard(flags, flag) {
+  return (_req, _res, next) => {
+    flags.isEnabled(flag).then((enabled) => {
+      if (enabled) next();
+      else next(new NotFoundException({ message: "Not found", details: { flag } }));
+    }).catch(next);
+  };
+}
+var LocalUploadStorage = class {
+  root;
+  baseUrl;
+  /**
+   * @param options - Filesystem root and public base URL.
+   */
+  constructor(options) {
+    this.root = options.root;
+    this.baseUrl = options.baseUrl ?? "";
+  }
+  async save(key, data, options = {}) {
+    const target = path.join(this.root, key);
+    await promises.mkdir(path.dirname(target), { recursive: true });
+    await promises.writeFile(target, data);
+    return {
+      key,
+      url: this.url(key),
+      size: data.byteLength,
+      ...options.contentType !== void 0 ? { contentType: options.contentType } : {}
+    };
+  }
+  async read(key) {
+    return promises.readFile(path.join(this.root, key));
+  }
+  async delete(key) {
+    await promises.rm(path.join(this.root, key), { force: true });
+  }
+  url(key) {
+    const base = this.baseUrl.replace(/\/$/, "");
+    return base ? `${base}/${key}` : `/${key}`;
+  }
+};
+function buildContentDisposition(filename, inline = false) {
+  const disposition = inline ? "inline" : "attachment";
+  const encoded = encodeURIComponent(filename);
+  return `${disposition}; filename*=UTF-8''${encoded}`;
+}
+
+// src/webpush/schemas.ts
+var webPushKeysSchema = zod.z.object({
+  p256dh: zod.z.string().openapi({ description: "Client public key (base64url)." }),
+  auth: zod.z.string().openapi({ description: "Client auth secret (base64url)." })
+}).openapi("WebPushKeys");
+var webPushSubscriptionSchema = zod.z.object({
+  endpoint: zod.z.string().url().openapi({ description: "Push service endpoint URL." }),
+  keys: webPushKeysSchema
+}).openapi("WebPushSubscription");
+var webPushPayloadSchema = zod.z.object({
+  title: zod.z.string().openapi({ description: "Notification title." }),
+  body: zod.z.string().optional().openapi({ description: "Notification body." }),
+  url: zod.z.string().optional().openapi({ description: "URL opened on click." }),
+  data: zod.z.record(zod.z.unknown()).optional().openapi({ description: "Extra data." })
+}).openapi("WebPushPayload");
+
+// src/webpush/dispatcher.ts
+var WebPushError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "WebPushError";
+  }
+  statusCode;
+};
+var WebPushGoneError = class extends WebPushError {
+  constructor(statusCode) {
+    super("Push subscription is gone", statusCode);
+    this.name = "WebPushGoneError";
+  }
+};
+var cached4 = null;
+async function loadWebPush() {
+  if (cached4) return cached4;
+  try {
+    const mod = await import('web-push');
+    cached4 = mod.default ?? mod;
+  } catch (cause) {
+    throw new Error(
+      "WebPushDispatcher requires the 'web-push' peer dependency. Install with `npm i web-push`.",
+      { cause }
+    );
+  }
+  return cached4;
+}
+var WebPushDispatcher = class {
+  /**
+   * @param options - VAPID keys and subject.
+   */
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  /**
+   * Send a payload to a single subscription.
+   *
+   * @param subscription - The browser push subscription.
+   * @param payload - The notification payload.
+   * @throws {WebPushGoneError} When the subscription is expired (410/404).
+   * @throws {WebPushError} On any other delivery failure.
+   */
+  async send(subscription, payload) {
+    const webpush = await loadWebPush();
+    webpush.setVapidDetails(
+      this.options.subject,
+      this.options.publicKey,
+      this.options.privateKey
+    );
+    try {
+      await webpush.sendNotification(subscription, JSON.stringify(payload));
+    } catch (error) {
+      const status = error.statusCode;
+      if (status === 404 || status === 410) throw new WebPushGoneError(status);
+      throw new WebPushError(error.message, status);
+    }
+  }
+};
+
 // src/auth/schemas.ts
 var signupSchema = zod.z.object({
   email: zod.z.string().email().openapi({ description: "Login identifier (email)." }),
@@ -6999,7 +8275,7 @@ function makeAuthRouter(options) {
   });
   return router;
 }
-var logger = new JSONLogger("tempest_express_sdk.api.handlers");
+var logger2 = new JSONLogger("tempest_express_sdk.api.handlers");
 var REQUEST_ID_HEADER = "X-Request-ID";
 function requestIdMiddleware() {
   return (req, res, next) => {
@@ -7040,7 +8316,7 @@ function makeAppExceptionHandler(options = {}) {
       return;
     }
     const isServerError = exc.statusCode >= 500;
-    logger.log(isServerError ? serverErrorLevel : "info", "AppException handled", {
+    logger2.log(isServerError ? serverErrorLevel : "info", "AppException handled", {
       path: req.path,
       method: req.method,
       statusCode: exc.statusCode,
@@ -7064,7 +8340,7 @@ function makeUnhandledExceptionHandler(options = {}) {
   const { includeStack = false, logLevel = "error" } = options;
   return (err, req, res, _next) => {
     const error = err instanceof Error ? err : new Error(String(err));
-    logger.log(logLevel, "Unhandled exception", {
+    logger2.log(logLevel, "Unhandled exception", {
       path: req.path,
       method: req.method,
       [HTTP_500_MARKER]: true,
@@ -7199,7 +8475,7 @@ function makeHealthRouter(options = {}) {
   });
   return router;
 }
-var logger2 = new JSONLogger("tempest_express_sdk.api.server");
+var logger3 = new JSONLogger("tempest_express_sdk.api.server");
 function corsMiddleware(origins) {
   const allowAll = origins === "*";
   const allowList = new Set(Array.isArray(origins) ? origins : [origins]);
@@ -7258,14 +8534,14 @@ function runServer(app, options = {}) {
   const port = options.port ?? 8e3;
   return new Promise((resolve) => {
     const server = app.listen(port, host, () => {
-      logger2.info("Server listening", { host, port });
+      logger3.info("Server listening", { host, port });
       resolve(server);
     });
   });
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.3.0";
 
 Object.defineProperty(exports, "OpenAPIRegistry", {
   enumerable: true,
@@ -7427,35 +8703,64 @@ exports.BaseService = BaseService;
 exports.CEP_PATTERN = CEP_PATTERN;
 exports.CNPJ_PATTERN = CNPJ_PATTERN;
 exports.CPF_PATTERN = CPF_PATTERN;
+exports.CircuitOpenError = CircuitOpenError;
+exports.CompositeFeatureFlagBackend = CompositeFeatureFlagBackend;
 exports.ConflictException = ConflictException;
 exports.DEFAULT_LOCALE = DEFAULT_LOCALE;
+exports.EmailUtils = EmailUtils;
+exports.EnvFeatureFlagBackend = EnvFeatureFlagBackend;
+exports.EventStream = EventStream;
 exports.ExpiredTokenException = ExpiredTokenException;
+exports.FeatureFlags = FeatureFlags;
 exports.ForbiddenException = ForbiddenException;
+exports.HTTPClient = HTTPClient;
 exports.HTTP_500_MARKER = HTTP_500_MARKER;
 exports.InvalidTokenException = InvalidTokenException;
 exports.JSONLogger = JSONLogger;
 exports.JWTUtils = JWTUtils;
+exports.LocalUploadStorage = LocalUploadStorage;
+exports.MemoryBroker = MemoryBroker;
+exports.MemoryCacheManager = MemoryCacheManager;
+exports.MemoryFeatureFlagBackend = MemoryFeatureFlagBackend;
+exports.MemorySessionStore = MemorySessionStore;
 exports.MemoryThrottleBackend = MemoryThrottleBackend;
 exports.MessageCatalog = MessageCatalog;
+exports.MetricsUtils = MetricsUtils;
 exports.NotFoundException = NotFoundException;
 exports.PHONE_BR_PATTERN = PHONE_BR_PATTERN;
 exports.PasswordUtils = PasswordUtils;
 exports.REQUEST_ID_HEADER = REQUEST_ID_HEADER;
+exports.RabbitBroker = RabbitBroker;
+exports.RedisCacheManager = RedisCacheManager;
 exports.Region = Region;
+exports.RetryPolicy = RetryPolicy;
+exports.SSEBroker = SSEBroker;
+exports.ServerSentEvent = ServerSentEvent;
+exports.SessionService = SessionService;
+exports.TOTPHelper = TOTPHelper;
+exports.TaskManager = TaskManager;
 exports.TooManyRequestsException = TooManyRequestsException;
 exports.UF = UF;
 exports.UnauthorizedException = UnauthorizedException;
 exports.UserAuthService = UserAuthService;
 exports.VERSION = VERSION;
 exports.ValidationException = ValidationException;
+exports.WebPushDispatcher = WebPushDispatcher;
+exports.WebPushError = WebPushError;
+exports.WebPushGoneError = WebPushGoneError;
+exports.WebSocketHub = WebSocketHub;
+exports.attachWebSocketHub = attachWebSocketHub;
 exports.authResponseSchema = authResponseSchema;
 exports.baseAppSettingsSchema = baseAppSettingsSchema;
 exports.baseAppSettingsShape = baseAppSettingsShape;
 exports.baseResponseSchema = baseResponseSchema;
 exports.bearerToken = bearerToken;
+exports.buildContentDisposition = buildContentDisposition;
+exports.cached = cached3;
 exports.cepField = cepField;
 exports.citiesByUf = citiesByUf;
 exports.cnpjField = cnpjField;
+exports.coerceFlag = coerceFlag;
 exports.configureLogging = configureLogging;
 exports.corsSettingsShape = corsSettingsShape;
 exports.cpfField = cpfField;
@@ -7474,6 +8779,7 @@ exports.encodeCursor = encodeCursor;
 exports.generateOpaqueToken = generateOpaqueToken;
 exports.generateOpenApiDocument = generateOpenApiDocument;
 exports.getAuth = getAuth;
+exports.getClientIp = getClientIp;
 exports.getConditions = getConditions;
 exports.getPaginationConditions = getPaginationConditions;
 exports.getRequestId = getRequestId;
@@ -7491,8 +8797,10 @@ exports.loadSettings = loadSettings;
 exports.loginSchema = loginSchema;
 exports.makeAppExceptionHandler = makeAppExceptionHandler;
 exports.makeAuthRouter = makeAuthRouter;
+exports.makeFlagGuard = makeFlagGuard;
 exports.makeHealthRouter = makeHealthRouter;
 exports.makeJwtAuthMiddleware = makeJwtAuthMiddleware;
+exports.makeSessionMiddleware = makeSessionMiddleware;
 exports.makeUnhandledExceptionHandler = makeUnhandledExceptionHandler;
 exports.modifyDict = modifyDict;
 exports.mountOpenApiJson = mountOpenApiJson;
@@ -7509,6 +8817,7 @@ exports.onlyDigits = onlyDigits;
 exports.paginationFilterSchema = paginationFilterSchema;
 exports.paginationSchema = paginationSchema;
 exports.parseAcceptLanguage = parseAcceptLanguage;
+exports.parseCookies = parseCookies;
 exports.phoneBrField = phoneBrField;
 exports.refreshSchema = refreshSchema;
 exports.registerExceptionHandlers = registerExceptionHandlers;
@@ -7517,17 +8826,24 @@ exports.requireRoles = requireRoles;
 exports.runServer = runServer;
 exports.runWithRequestContext = runWithRequestContext;
 exports.serverSettingsShape = serverSettingsShape;
+exports.sessionCookie = sessionCookie;
 exports.setRequestId = setRequestId;
 exports.signupSchema = signupSchema;
+exports.sseResponse = sseResponse;
 exports.statesByRegion = statesByRegion;
 exports.tableNameFor = tableNameFor;
 exports.toDict = toDict;
 exports.toUtc = toUtc;
+exports.tokenFromUrl = tokenFromUrl;
 exports.tokenPairSchema = tokenPairSchema;
 exports.ufField = ufField;
 exports.updatedByColumn = updatedByColumn;
 exports.userPublicSchema = userPublicSchema;
 exports.utcnow = utcnow;
 exports.verifyOpaqueToken = verifyOpaqueToken;
+exports.webPushKeysSchema = webPushKeysSchema;
+exports.webPushPayloadSchema = webPushPayloadSchema;
+exports.webPushSubscriptionSchema = webPushSubscriptionSchema;
+exports.wsEnvelopeSchema = wsEnvelopeSchema;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map