tempest-express-sdk 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -5,6 +5,7 @@ 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');
@@ -6755,6 +6756,361 @@ 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();
@@ -7595,6 +7951,84 @@ function buildContentDisposition(filename, inline = false) {
   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)." }),
@@ -8107,7 +8541,7 @@ function runServer(app, options = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 
 Object.defineProperty(exports, "OpenAPIRegistry", {
   enumerable: true,
@@ -8269,14 +8703,17 @@ 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;
@@ -8288,6 +8725,7 @@ 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;
@@ -8295,9 +8733,11 @@ 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;
@@ -8305,6 +8745,9 @@ 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;
@@ -8336,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;
@@ -8397,6 +8841,9 @@ 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