@spfn/core 0.2.0-beta.8 → 0.3.0-beta.1

package/dist/middleware/index.js

@@ -1,10 +1,90 @@
+import { randomBytes, createHmac, createHash, timingSafeEqual } from 'crypto';
 import { SerializableError } from '@spfn/core/errors';
 import { logger } from '@spfn/core/logger';
 import { env } from '@spfn/core/config';
-import { randomBytes } from 'crypto';
+import { format } from 'util';
 
 // src/middleware/error-handler.ts
 var errorLogger = logger.child("@spfn/core:error-handler");
+function withEnvelope(body, c) {
+  return {
+    ...body,
+    error: {
+      code: body.__type,
+      message: body.message,
+      requestId: resolveRequestId(c)
+    }
+  };
+}
+function resolveRequestId(c) {
+  const existing = c.get("requestId");
+  return existing ?? randomBytes(16).toString("hex");
+}
+function extractCauseMessage(err) {
+  const cause = err.cause;
+  if (!cause) {
+    return void 0;
+  }
+  if (cause instanceof Error) {
+    return cause.message;
+  }
+  if (typeof cause === "string") {
+    return cause;
+  }
+  return String(cause);
+}
+var SENSITIVE_HEADERS = /* @__PURE__ */ new Set(["authorization", "cookie", "x-api-key", "x-auth-token"]);
+function extractHeaders(c) {
+  const headers = {};
+  c.req.raw.headers.forEach((value, key) => {
+    headers[key] = SENSITIVE_HEADERS.has(key.toLowerCase()) ? "***" : value;
+  });
+  return headers;
+}
+var SENSITIVE_QUERY_PARAMS = /* @__PURE__ */ new Set([
+  "token",
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "code",
+  "secret",
+  "client_secret",
+  "password",
+  "passwd",
+  "pwd",
+  "api_key",
+  "apikey",
+  "key",
+  "signature",
+  "sig",
+  "session",
+  "sessionid",
+  "auth",
+  "authorization"
+]);
+function extractQuery(c) {
+  const query = c.req.query();
+  const masked = {};
+  for (const [key, value] of Object.entries(query)) {
+    masked[key] = SENSITIVE_QUERY_PARAMS.has(key.toLowerCase()) ? "***" : value;
+  }
+  return masked;
+}
+function buildOnErrorContext(c, statusCode) {
+  const auth = c.get("auth");
+  return {
+    statusCode,
+    path: c.req.path,
+    method: c.req.method,
+    requestId: c.get("requestId"),
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    userId: auth?.userId,
+    request: {
+      headers: extractHeaders(c),
+      query: extractQuery(c)
+    }
+  };
+}
 function logError(err, logData, includeStack) {
   const logLevel = logData.statusCode >= 500 ? "error" : "warn";
   if (includeStack) {
@@ -19,25 +99,48 @@ function isSerializableError(err) {
 function ErrorHandler(options = {}) {
   const {
     includeStack = env.NODE_ENV !== "production",
-    enableLogging = true
+    enableLogging = true,
+    errorEnvelope = true,
+    onError
   } = options;
+  const respond = (c, body, statusCode) => {
+    return c.json(
+      errorEnvelope ? withEnvelope(body, c) : body,
+      statusCode
+    );
+  };
   return (err, c) => {
+    const path = c.req.path;
+    const method = c.req.method;
+    const causeMessage = extractCauseMessage(err);
     if (isSerializableError(err)) {
       const { statusCode: statusCode2 } = err;
       if (enableLogging) {
         logError(err, {
           type: err.constructor.name,
           message: err.message,
+          cause: causeMessage,
           statusCode: statusCode2,
-          path: c.req.path,
-          method: c.req.method
+          path,
+          method
         }, includeStack);
       }
+      if (onError) {
+        const ctx = buildOnErrorContext(c, statusCode2);
+        Promise.resolve(onError(err, ctx)).catch((e) => errorLogger.warn("onError callback failed", e));
+      }
+      if (err.internal === true && !includeStack) {
+        return respond(
+          c,
+          { __type: err.constructor.name, message: "Internal server error" },
+          statusCode2
+        );
+      }
       const serialized = err.toJSON();
       if (includeStack && err.stack) {
         serialized.stack = err.stack;
       }
-      return c.json(serialized, statusCode2);
+      return respond(c, serialized, statusCode2);
     }
     const errorWithCode = err;
     const statusCode = errorWithCode.statusCode || 500;
@@ -45,21 +148,1183 @@ function ErrorHandler(options = {}) {
       logError(err, {
         type: err.name || "Error",
         message: err.message,
+        cause: causeMessage,
         statusCode,
-        path: c.req.path,
-        method: c.req.method
+        path,
+        method
       }, includeStack);
     }
+    if (onError) {
+      const ctx = buildOnErrorContext(c, statusCode);
+      Promise.resolve(onError(err, ctx)).catch((e) => errorLogger.warn("onError callback failed", e));
+    }
     const response = {
       __type: "Error",
-      message: err.message || "Internal Server Error"
+      message: includeStack ? err.message || "Internal Server Error" : "Internal Server Error"
     };
+    if (causeMessage && includeStack) {
+      response.cause = causeMessage;
+    }
     if (includeStack && err.stack) {
       response.stack = err.stack;
     }
-    return c.json(response, statusCode);
+    return respond(c, response, statusCode);
+  };
+}
+var PROXY_SIGNATURE_HEADER = "x-spfn-proxy-signature";
+var PROXY_TIMESTAMP_HEADER = "x-spfn-proxy-timestamp";
+var PROXY_NONCE_HEADER = "x-spfn-proxy-nonce";
+var PROXY_KEY_ID_HEADER = "x-spfn-proxy-key-id";
+var PROXY_CLIENT_IP_HEADER = "x-spfn-proxy-client-ip";
+var DEFAULT_KEY_ID = "default";
+function parseProxyKey(raw) {
+  const idx = raw.indexOf(":");
+  if (idx === -1) {
+    return { keyId: DEFAULT_KEY_ID, secret: raw };
+  }
+  return { keyId: raw.slice(0, idx) || DEFAULT_KEY_ID, secret: raw.slice(idx + 1) };
+}
+function parseProxyKeySet(raws) {
+  const keys = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of raws) {
+    if (!raw) {
+      continue;
+    }
+    for (const part of raw.split(",")) {
+      const trimmed = part.trim();
+      if (!trimmed) {
+        continue;
+      }
+      const key = parseProxyKey(trimmed);
+      if (!key.secret || seen.has(key.keyId)) {
+        continue;
+      }
+      seen.add(key.keyId);
+      keys.push(key);
+    }
+  }
+  return keys;
+}
+function buildCanonicalString(parts) {
+  return [parts.method.toUpperCase(), parts.path, parts.query, parts.timestamp, parts.nonce, parts.bodyHash].join("\n");
+}
+function hashBody(body) {
+  if (!body || body.length === 0) {
+    return "";
+  }
+  return typeof body === "string" ? createHash("sha256").update(body, "utf8").digest("hex") : createHash("sha256").update(body).digest("hex");
+}
+function computeSignature(secret, parts) {
+  return createHmac("sha256", secret).update(buildCanonicalString(parts)).digest("hex");
+}
+function safeEqualHex(a, b) {
+  const bufA = Buffer.from(a, "hex");
+  const bufB = Buffer.from(b, "hex");
+  if (bufA.length === 0 || bufA.length !== bufB.length) {
+    return false;
+  }
+  return timingSafeEqual(bufA, bufB);
+}
+function verifyProxyRequest(input) {
+  const { signature, timestamp, nonce, keyId } = input;
+  if (!signature || !timestamp || !nonce || !keyId) {
+    return { valid: false, reason: "missing-headers" };
+  }
+  const ts = Number(timestamp);
+  if (!Number.isFinite(ts)) {
+    return { valid: false, reason: "bad-timestamp" };
+  }
+  const now = input.now ?? Date.now();
+  const windowMs = input.windowMs ?? 3e4;
+  if (Math.abs(now - ts) > windowMs) {
+    return { valid: false, reason: "stale-timestamp" };
+  }
+  const key = input.keys.find((k) => k.keyId === keyId);
+  if (!key) {
+    return { valid: false, reason: "unknown-key" };
+  }
+  const expected = computeSignature(key.secret, {
+    method: input.method,
+    path: input.path,
+    query: input.query ?? "",
+    timestamp,
+    nonce,
+    bodyHash: hashBody(input.body)
+  });
+  if (!safeEqualHex(signature, expected)) {
+    return { valid: false, reason: "signature-mismatch" };
+  }
+  return { valid: true, nonce, keyId };
+}
+
+// src/route/define-middleware.ts
+function defineMiddleware(name, handlerOrFactory, options) {
+  const skips = options?.skips;
+  if (typeof handlerOrFactory === "function") {
+    const paramCount = handlerOrFactory.length;
+    if (paramCount === 2) {
+      return {
+        name,
+        handler: handlerOrFactory,
+        _name: name,
+        ...skips
+      };
+    } else {
+      const factory = handlerOrFactory;
+      const wrapper = (...args) => factory(...args);
+      Object.defineProperty(wrapper, "name", {
+        value: name,
+        writable: false,
+        enumerable: false,
+        configurable: true
+      });
+      Object.defineProperty(wrapper, "_name", {
+        value: name,
+        writable: false,
+        enumerable: false,
+        configurable: true
+      });
+      return wrapper;
+    }
+  }
+  return {
+    name,
+    handler: handlerOrFactory,
+    _name: name,
+    ...skips
+  };
+}
+function defineMiddlewareFactory(name, factory) {
+  const wrapper = (...args) => factory(...args);
+  Object.defineProperty(wrapper, "name", {
+    value: name,
+    writable: false,
+    enumerable: false,
+    configurable: true
+  });
+  Object.defineProperty(wrapper, "_name", {
+    value: name,
+    writable: false,
+    enumerable: false,
+    configurable: true
+  });
+  return wrapper;
+}
+logger.child("@spfn/core:cache");
+logger.child("@spfn/core:cache");
+var CACHE_KEY = Symbol.for("@spfn/core:cache");
+var state = globalThis[CACHE_KEY] ??= {
+  write: void 0,
+  read: void 0,
+  disabled: false
+};
+function getCache() {
+  return state.write;
+}
+function isCacheDisabled() {
+  return state.disabled;
+}
+
+// src/errors/error-registry.ts
+var ErrorRegistry = class _ErrorRegistry {
+  errors = /* @__PURE__ */ new Map();
+  constructor(initialErrors) {
+    if (initialErrors) {
+      for (const input of initialErrors) {
+        if (input instanceof _ErrorRegistry) {
+          this.concat(input);
+        } else if (Array.isArray(input)) {
+          this.append(input);
+        } else {
+          this.append(input);
+        }
+      }
+    }
+  }
+  /**
+   * Append error class(es) to the registry
+   *
+   * @param input - Error constructor or array of constructors
+   * @returns This registry for chaining
+   */
+  append(input) {
+    if (Array.isArray(input)) {
+      for (const ErrorClass of input) {
+        this.errors.set(ErrorClass.name, ErrorClass);
+      }
+    } else {
+      this.errors.set(input.name, input);
+    }
+    return this;
+  }
+  /**
+   * Concatenate another ErrorRegistry into this one
+   *
+   * @param registry - Another ErrorRegistry to merge
+   * @returns This registry for chaining
+   */
+  concat(registry) {
+    for (const [name, ErrorClass] of registry.errors) {
+      this.errors.set(name, ErrorClass);
+    }
+    return this;
+  }
+  /**
+   * Check if error type is registered
+   *
+   * @param name - Error class name
+   */
+  has(name) {
+    return this.errors.has(name);
+  }
+  /**
+   * Deserialize error from JSON data
+   *
+   * @param data - Serialized error data with __type field
+   * @returns Deserialized error instance
+   * @throws Error if error type is not registered
+   */
+  deserialize(data) {
+    const ErrorClass = this.errors.get(data.__type);
+    if (!ErrorClass) {
+      throw new Error(`Unknown error type: ${data.__type}`);
+    }
+    const { __type: _type, error: _envelope, ...fields } = data;
+    return new ErrorClass(fields);
+  }
+  /**
+   * Try to deserialize error, return null if type unknown
+   *
+   * @param data - Serialized error data
+   * @returns Deserialized error or null
+   */
+  tryDeserialize(data) {
+    if (!data.__type || !this.has(data.__type)) {
+      return null;
+    }
+    try {
+      return this.deserialize(data);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get all registered error types
+   */
+  getRegisteredTypes() {
+    return Array.from(this.errors.keys());
+  }
+};
+
+// src/logger/types.ts
+var LOG_LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4
+};
+
+// src/logger/formatters.ts
+var SENSITIVE_KEYS = [
+  "password",
+  "passwd",
+  "pwd",
+  "secret",
+  "token",
+  "apikey",
+  "api_key",
+  "accesstoken",
+  "access_token",
+  "refreshtoken",
+  "refresh_token",
+  "authorization",
+  "auth",
+  "cookie",
+  "session",
+  "sessionid",
+  "session_id",
+  "privatekey",
+  "private_key",
+  "creditcard",
+  "credit_card",
+  "cardnumber",
+  "card_number",
+  "cvv",
+  "ssn",
+  "pin"
+];
+var MASKED_VALUE = "***MASKED***";
+function isSensitiveKey(key) {
+  const lowerKey = key.toLowerCase();
+  return SENSITIVE_KEYS.some((sensitive) => lowerKey.includes(sensitive));
+}
+function maskSensitiveData(data, seen = /* @__PURE__ */ new WeakSet()) {
+  if (data === null || data === void 0) {
+    return data;
+  }
+  if (typeof data !== "object") {
+    return data;
+  }
+  if (seen.has(data)) {
+    return "[Circular]";
+  }
+  seen.add(data);
+  if (Array.isArray(data)) {
+    return data.map((item) => maskSensitiveData(item, seen));
+  }
+  const masked = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (isSensitiveKey(key)) {
+      masked[key] = MASKED_VALUE;
+    } else if (typeof value === "object" && value !== null) {
+      masked[key] = maskSensitiveData(value, seen);
+    } else {
+      masked[key] = value;
+    }
+  }
+  return masked;
+}
+var COLORS = {
+  reset: "\x1B[0m",
+  bright: "\x1B[1m",
+  dim: "\x1B[2m",
+  // 로그 레벨 컬러
+  debug: "\x1B[36m",
+  // cyan
+  info: "\x1B[32m",
+  // green
+  warn: "\x1B[33m",
+  // yellow
+  error: "\x1B[31m",
+  // red
+  fatal: "\x1B[35m",
+  // magenta
+  // 추가 컬러
+  gray: "\x1B[90m"
+};
+function formatTimestampHuman(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  const seconds = String(date.getSeconds()).padStart(2, "0");
+  const ms = String(date.getMilliseconds()).padStart(3, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${ms}`;
+}
+function formatError(error) {
+  const lines = [];
+  lines.push(`${error.name}: ${error.message}`);
+  if (error.stack) {
+    const stackLines = error.stack.split("\n").slice(1);
+    lines.push(...stackLines);
+  }
+  if (error.cause instanceof Error) {
+    lines.push(`Caused by: ${formatError(error.cause)}`);
+  } else if (error.cause !== void 0) {
+    lines.push(`Caused by: ${String(error.cause)}`);
+  }
+  return lines.join("\n");
+}
+function formatConsole(metadata, colorize = true) {
+  const parts = [];
+  const timestamp = formatTimestampHuman(metadata.timestamp);
+  if (colorize) {
+    parts.push(`${COLORS.gray}[${timestamp}]${COLORS.reset}`);
+  } else {
+    parts.push(`[${timestamp}]`);
+  }
+  const pid = process.pid;
+  if (colorize) {
+    parts.push(`${COLORS.dim}[pid=${pid}]${COLORS.reset}`);
+  } else {
+    parts.push(`[pid=${pid}]`);
+  }
+  if (metadata.module) {
+    if (colorize) {
+      parts.push(`${COLORS.dim}[module=${metadata.module}]${COLORS.reset}`);
+    } else {
+      parts.push(`[module=${metadata.module}]`);
+    }
+  }
+  if (metadata.context && Object.keys(metadata.context).length > 0) {
+    Object.entries(metadata.context).forEach(([key, value]) => {
+      let valueStr;
+      if (typeof value === "string") {
+        valueStr = value;
+      } else if (typeof value === "object" && value !== null) {
+        try {
+          valueStr = JSON.stringify(value);
+        } catch (error) {
+          valueStr = "[circular]";
+        }
+      } else {
+        valueStr = String(value);
+      }
+      if (colorize) {
+        parts.push(`${COLORS.dim}[${key}=${valueStr}]${COLORS.reset}`);
+      } else {
+        parts.push(`[${key}=${valueStr}]`);
+      }
+    });
+  }
+  const levelStr = metadata.level.toUpperCase();
+  if (colorize) {
+    const color = COLORS[metadata.level];
+    parts.push(`${color}(${levelStr})${COLORS.reset}:`);
+  } else {
+    parts.push(`(${levelStr}):`);
+  }
+  if (colorize) {
+    parts.push(`${COLORS.bright}${metadata.message}${COLORS.reset}`);
+  } else {
+    parts.push(metadata.message);
+  }
+  let output = parts.join(" ");
+  if (metadata.error) {
+    output += "\n" + formatError(metadata.error);
+  }
+  return output;
+}
+
+// src/logger/logger.ts
+var FORMAT_PATTERN = /%[sdifjoOc%]/;
+var Logger = class _Logger {
+  config;
+  module;
+  constructor(config) {
+    this.config = config;
+    this.module = config.module;
+  }
+  /**
+   * Convert unknown error to Error object
+   */
+  toError(error) {
+    if (error instanceof Error) return error;
+    if (typeof error === "string") return new Error(error);
+    if (typeof error === "object" && error !== null) {
+      return new Error(JSON.stringify(error));
+    }
+    return new Error(String(error));
+  }
+  /**
+   * Check if value is a context object (not an error)
+   */
+  isContext(value) {
+    if (typeof value !== "object" || value === null) return false;
+    if (value instanceof Error) return false;
+    const hasStack = "stack" in value && typeof value.stack === "string";
+    if (hasStack) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Get current log level
+   */
+  get level() {
+    return this.config.level;
+  }
+  /**
+   * Create child logger (per module)
+   */
+  child(module) {
+    return new _Logger({
+      ...this.config,
+      module
+    });
+  }
+  /**
+   * Common log method with error/context detection
+   */
+  logWithLevel(level, message, errorOrContext, context) {
+    if (errorOrContext !== void 0 && FORMAT_PATTERN.test(message)) {
+      this.log(level, format(message, errorOrContext), void 0, context);
+      return;
+    }
+    if (errorOrContext instanceof Error) {
+      this.log(level, message, errorOrContext, context);
+    } else if (errorOrContext !== void 0 && typeof errorOrContext === "object" && !this.isContext(errorOrContext)) {
+      this.log(level, message, this.toError(errorOrContext), context);
+    } else if (typeof errorOrContext === "string" || typeof errorOrContext === "number" || typeof errorOrContext === "boolean") {
+      this.log(level, message, this.toError(errorOrContext), context);
+    } else {
+      this.log(level, message, void 0, errorOrContext);
+    }
+  }
+  debug(message, errorOrContext, context) {
+    this.logWithLevel("debug", message, errorOrContext, context);
+  }
+  info(message, errorOrContext, context) {
+    this.logWithLevel("info", message, errorOrContext, context);
+  }
+  warn(message, errorOrContext, context) {
+    this.logWithLevel("warn", message, errorOrContext, context);
+  }
+  error(message, errorOrContext, context) {
+    this.logWithLevel("error", message, errorOrContext, context);
+  }
+  fatal(message, errorOrContext, context) {
+    this.logWithLevel("fatal", message, errorOrContext, context);
+  }
+  /**
+   * Log processing (internal)
+   */
+  log(level, message, error, context) {
+    if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[this.config.level]) {
+      return;
+    }
+    const metadata = {
+      timestamp: /* @__PURE__ */ new Date(),
+      level,
+      message,
+      module: this.module,
+      error,
+      // Mask sensitive information in context to prevent credential leaks
+      context: context ? maskSensitiveData(context) : void 0
+    };
+    this.processTransports(metadata);
+  }
+  /**
+   * Process Transports
+   */
+  processTransports(metadata) {
+    const promises = this.config.transports.filter((transport) => transport.enabled).map((transport) => this.safeTransportLog(transport, metadata));
+    Promise.all(promises).catch((error) => {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`[Logger] Transport error: ${errorMessage}
+`);
+    });
+  }
+  /**
+   * Transport log (error-safe)
+   */
+  async safeTransportLog(transport, metadata) {
+    try {
+      await transport.log(metadata);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`[Logger] Transport "${transport.name}" failed: ${errorMessage}
+`);
+    }
+  }
+  /**
+   * Close all Transports
+   */
+  async close() {
+    const closePromises = this.config.transports.filter((transport) => transport.close).map((transport) => transport.close());
+    await Promise.all(closePromises);
+  }
+};
+
+// src/logger/transports/console.ts
+var ConsoleTransport = class {
+  name = "console";
+  level;
+  enabled;
+  colorize;
+  constructor(config) {
+    this.level = config.level;
+    this.enabled = config.enabled;
+    this.colorize = config.colorize ?? true;
+  }
+  async log(metadata) {
+    if (!this.enabled) {
+      return;
+    }
+    if (LOG_LEVEL_PRIORITY[metadata.level] < LOG_LEVEL_PRIORITY[this.level]) {
+      return;
+    }
+    const message = formatConsole(metadata, this.colorize);
+    if (metadata.level === "warn" || metadata.level === "error" || metadata.level === "fatal") {
+      console.error(message);
+    } else {
+      console.log(message);
+    }
+  }
+};
+
+// src/logger/config.ts
+function getConsoleConfig() {
+  const isProduction = process.env.NODE_ENV === "production";
+  return {
+    level: "debug",
+    enabled: true,
+    colorize: !isProduction
+    // Dev: colored output, Production: plain text
+  };
+}
+function validateEnvironment() {
+  const nodeEnv = process.env.NODE_ENV;
+  if (!nodeEnv) {
+    process.stderr.write(
+      "[Logger] Warning: NODE_ENV is not set. Defaulting to test environment.\n"
+    );
+  }
+}
+function validateConfig() {
+  validateEnvironment();
+}
+
+// src/logger/factory.ts
+function initializeTransports() {
+  const transports = [];
+  const consoleConfig = getConsoleConfig();
+  transports.push(new ConsoleTransport(consoleConfig));
+  return transports;
+}
+function getLogLevel() {
+  const envLevel = process.env.SPFN_LOG_LEVEL || process.env.NEXT_PUBLIC_SPFN_LOG_LEVEL || "info";
+  if (envLevel in LOG_LEVEL_PRIORITY) {
+    return envLevel;
+  }
+  process.stderr.write(
+    `[Logger] Invalid log level "${envLevel}", defaulting to "info"
+`
+  );
+  return "info";
+}
+function initializeLogger() {
+  validateConfig();
+  return new Logger({
+    level: getLogLevel(),
+    transports: initializeTransports()
+  });
+}
+var logger4 = initializeLogger();
+
+// src/errors/serializable-error.ts
+var RESERVED_RESPONSE_KEYS = /* @__PURE__ */ new Set(["__type", "message", "error"]);
+var AUTHORING_ENVIRONMENTS = /* @__PURE__ */ new Set(["local", "development", "test"]);
+function refuseReservedKey(className, key) {
+  const detail = `${className} declares the reserved field "${key}". Reserved response keys: ${[...RESERVED_RESPONSE_KEYS].join(", ")}. Rename the field.`;
+  if (AUTHORING_ENVIRONMENTS.has(process.env.NODE_ENV ?? "local")) {
+    throw new Error(detail);
+  }
+  logger4.error(`[SerializableError] ${detail} The field is omitted from the response.`);
+}
+var SerializableError2 = class extends Error {
+  /**
+   * Serialize error to JSON-compatible object
+   *
+   * Automatically includes:
+   * - __type: Constructor name for deserialization
+   * - message: Error message
+   * - All public instance properties (except name, stack)
+   */
+  toJSON() {
+    const json = {
+      __type: this.constructor.name,
+      message: this.message
+    };
+    for (const key of Object.keys(this)) {
+      if (key === "name" || key === "stack" || key === "statusCode") {
+        continue;
+      }
+      if (RESERVED_RESPONSE_KEYS.has(key)) {
+        refuseReservedKey(this.constructor.name, key);
+        continue;
+      }
+      json[key] = this[key];
+    }
+    return json;
+  }
+};
+
+// src/errors/http-errors.ts
+var HttpError = class extends SerializableError2 {
+  statusCode;
+  details;
+  constructor(data) {
+    super(data.message);
+    this.name = "HttpError";
+    this.statusCode = data.statusCode;
+    if (data.details) {
+      this.details = data.details;
+    }
+    Error.captureStackTrace(this, this.constructor);
+  }
+};
+var BadRequestError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Bad request",
+      statusCode: 400,
+      details: data.details
+    });
+    this.name = "BadRequestError";
+  }
+};
+var ValidationError = class extends HttpError {
+  fields;
+  constructor(data) {
+    super({
+      message: data.message,
+      statusCode: 400,
+      details: data.details
+    });
+    this.name = "ValidationError";
+    if (data.fields) {
+      this.fields = data.fields;
+    }
+  }
+};
+var UnauthorizedError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Authentication required",
+      statusCode: 401,
+      details: data.details
+    });
+    this.name = "UnauthorizedError";
+  }
+};
+var ForbiddenError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Access forbidden",
+      statusCode: 403,
+      details: data.details
+    });
+    this.name = "ForbiddenError";
+  }
+};
+var NotFoundError = class extends HttpError {
+  resource;
+  constructor(data = {}) {
+    super({
+      message: data.message || "Resource not found",
+      statusCode: 404,
+      details: data.details
+    });
+    this.name = "NotFoundError";
+    if (data.resource) {
+      this.resource = data.resource;
+    }
+  }
+};
+var ConflictError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Resource conflict",
+      statusCode: 409,
+      details: data.details
+    });
+    this.name = "ConflictError";
+  }
+};
+var GoneError = class extends HttpError {
+  resource;
+  constructor(data = {}) {
+    super({
+      message: data.message || "Resource permanently deleted",
+      statusCode: 410,
+      details: data.details
+    });
+    this.name = "GoneError";
+    if (data.resource) {
+      this.resource = data.resource;
+    }
+  }
+};
+var TooManyRequestsError = class extends HttpError {
+  retryAfter;
+  constructor(data = {}) {
+    super({
+      message: data.message || "Too many requests",
+      statusCode: 429,
+      details: data.details
+    });
+    this.name = "TooManyRequestsError";
+    if (data.retryAfter) {
+      this.retryAfter = data.retryAfter;
+    }
+  }
+};
+var InternalServerError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Internal server error",
+      statusCode: 500,
+      details: data.details
+    });
+    this.name = "InternalServerError";
+  }
+};
+var UnsupportedMediaTypeError = class extends HttpError {
+  mediaType;
+  supportedTypes;
+  constructor(data = {}) {
+    super({
+      message: data.message || "Unsupported media type",
+      statusCode: 415,
+      details: data.details
+    });
+    this.name = "UnsupportedMediaTypeError";
+    if (data.mediaType) {
+      this.mediaType = data.mediaType;
+    }
+    if (data.supportedTypes) {
+      this.supportedTypes = data.supportedTypes;
+    }
+  }
+};
+var UnprocessableEntityError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Unprocessable entity",
+      statusCode: 422,
+      details: data.details
+    });
+    this.name = "UnprocessableEntityError";
+  }
+};
+var ServiceUnavailableError = class extends HttpError {
+  retryAfter;
+  constructor(data = {}) {
+    super({
+      message: data.message || "Service unavailable",
+      statusCode: 503,
+      details: data.details
+    });
+    this.name = "ServiceUnavailableError";
+    if (data.retryAfter) {
+      this.retryAfter = data.retryAfter;
+    }
+  }
+};
+
+// src/errors/database-errors.ts
+var DatabaseError = class extends SerializableError2 {
+  statusCode;
+  details;
+  constructor(data) {
+    super(data.message);
+    this.name = "DatabaseError";
+    this.statusCode = data.statusCode ?? 500;
+    this.details = data.details;
+    Error.captureStackTrace(this, this.constructor);
+  }
+  /**
+   * Whether this error's message/details are derived from the raw database
+   * driver (SQL text, table/column/constraint names, parameter values) and
+   * therefore must NOT be exposed to clients in production. Defined as a
+   * prototype getter so it is never serialized into the response by toJSON().
+   * Subclasses with a safe, constructed message override this to `false`.
+   */
+  get internal() {
+    return true;
+  }
+};
+var ConnectionError = class extends DatabaseError {
+  constructor(data) {
+    super({ message: data.message, statusCode: 503, details: data.details });
+    this.name = "ConnectionError";
+  }
+};
+var QueryError = class extends DatabaseError {
+  constructor(data) {
+    super({
+      message: data.message,
+      statusCode: data.statusCode ?? 500,
+      details: data.details
+    });
+    this.name = "QueryError";
+  }
+};
+var EntityNotFoundError = class extends QueryError {
+  resource;
+  id;
+  constructor(data) {
+    super({
+      message: `${data.resource} with id ${data.id} not found`,
+      statusCode: 404,
+      details: { resource: data.resource, id: data.id }
+    });
+    this.name = "EntityNotFoundError";
+    this.resource = data.resource;
+    this.id = data.id;
+  }
+  // Message/details are constructed from the resource + id, not driver text
+  get internal() {
+    return false;
+  }
+};
+var ConstraintViolationError = class extends QueryError {
+  constructor(data) {
+    super({ message: data.message, statusCode: 400, details: data.details });
+    this.name = "ConstraintViolationError";
+  }
+};
+var TransactionError = class extends DatabaseError {
+  constructor(data) {
+    super({
+      message: data.message,
+      statusCode: data.statusCode ?? 500,
+      details: data.details
+    });
+    this.name = "TransactionError";
+  }
+};
+var DeadlockError = class extends TransactionError {
+  constructor(data) {
+    super({ message: data.message, statusCode: 409, details: data.details });
+    this.name = "DeadlockError";
+  }
+};
+var DuplicateEntryError = class extends QueryError {
+  field;
+  value;
+  constructor(data) {
+    super({
+      message: `${data.field} already exists`,
+      statusCode: 409,
+      details: { field: data.field }
+    });
+    this.name = "DuplicateEntryError";
+    this.field = data.field;
+    this.value = data.value;
+  }
+  // Field-only message/details — safe to surface to the client (not internal)
+  get internal() {
+    return false;
+  }
+};
+
+// src/errors/index.ts
+var errorRegistry = new ErrorRegistry();
+errorRegistry.append([
+  HttpError,
+  BadRequestError,
+  ValidationError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  GoneError,
+  TooManyRequestsError,
+  UnsupportedMediaTypeError,
+  UnprocessableEntityError,
+  InternalServerError,
+  ServiceUnavailableError
+]);
+errorRegistry.append([
+  DatabaseError,
+  ConnectionError,
+  QueryError,
+  EntityNotFoundError,
+  ConstraintViolationError,
+  TransactionError,
+  DeadlockError,
+  DuplicateEntryError
+]);
+
+// src/middleware/rate-limit-store.ts
+var FIXED_WINDOW_LUA = `
+local count = redis.call('INCR', KEYS[1])
+if count == 1 then
+    redis.call('PEXPIRE', KEYS[1], ARGV[1])
+end
+return { count, redis.call('PTTL', KEYS[1]) }
+`;
+var CacheRateLimitStore = class {
+  constructor(cache) {
+    this.cache = cache;
+  }
+  async hit(key, windowMs) {
+    const [count, pttl] = await this.cache.eval(
+      FIXED_WINDOW_LUA,
+      1,
+      key,
+      String(windowMs)
+    );
+    return { count, pttl };
+  }
+};
+var MemoryRateLimitStore = class {
+  constructor(maxKeys = 1e4) {
+    this.maxKeys = maxKeys;
+  }
+  windows = /* @__PURE__ */ new Map();
+  /** How many live windows were dropped to stay under `maxKeys`. */
+  evicted = 0;
+  async hit(key, windowMs) {
+    const now = Date.now();
+    const existing = this.windows.get(key);
+    if (existing !== void 0 && existing.expiresAt > now) {
+      existing.count += 1;
+      return { count: existing.count, pttl: existing.expiresAt - now };
+    }
+    if (this.windows.size >= this.maxKeys) {
+      this.makeRoom(now);
+    }
+    this.windows.set(key, { count: 1, expiresAt: now + windowMs });
+    return { count: 1, pttl: windowMs };
+  }
+  /** Drops every window that has already reset. */
+  prune(nowMillis) {
+    for (const [key, window] of this.windows) {
+      if (window.expiresAt <= nowMillis) {
+        this.windows.delete(key);
+      }
+    }
+  }
+  /**
+   * Frees a slot for a new key.
+   *
+   * Expired windows go first. If every window is still live the oldest one is
+   * dropped, because a hard bound is the only thing standing between a
+   * per-IP limiter and unbounded memory. A dropped window loses its count,
+   * so a caller who can mint `maxKeys` distinct identities can push another
+   * one out — which is why `evictionCount` is worth watching: it says this
+   * process is past what an in-memory limiter should be asked to hold, and
+   * the deployment wants a real cache.
+   */
+  makeRoom(nowMillis) {
+    this.prune(nowMillis);
+    if (this.windows.size < this.maxKeys) {
+      return;
+    }
+    const oldest = this.windows.keys().next();
+    if (!oldest.done) {
+      this.windows.delete(oldest.value);
+      this.evicted += 1;
+    }
+  }
+  get size() {
+    return this.windows.size;
+  }
+  /** Live windows dropped for capacity — nonzero means the bound is binding. */
+  get evictionCount() {
+    return this.evicted;
+  }
+  clear() {
+    this.windows.clear();
+    this.evicted = 0;
+  }
+};
+
+// src/middleware/rate-limit.ts
+var rateLimitLogger = logger4.child("@spfn/core:rate-limit");
+var memoryStore = new MemoryRateLimitStore();
+function resetMemoryRateLimitStore() {
+  memoryStore.clear();
+}
+function getClientIp(c) {
+  const clientType = c.get("clientType");
+  if (clientType && clientType !== "untrusted") {
+    const forwarded = c.req.header(PROXY_CLIENT_IP_HEADER);
+    if (forwarded) {
+      return forwarded;
+    }
+  }
+  const forwardedFor = c.req.header("x-forwarded-for");
+  return forwardedFor?.split(",")[0]?.trim() || c.req.header("x-real-ip") || socketRemoteAddress(c) || "unknown";
+}
+function socketRemoteAddress(c) {
+  const env4 = c.env;
+  const bindings = env4?.server ?? env4;
+  return bindings?.incoming?.socket?.remoteAddress;
+}
+function selectStore(failClosed, message, path) {
+  const cache = getCache();
+  if (cache && !isCacheDisabled()) {
+    return new CacheRateLimitStore(cache);
+  }
+  if (failClosed) {
+    throw new TooManyRequestsError({ message: message || "Rate limiter unavailable" });
+  }
+  rateLimitLogger.debug("No cache \u2014 counting rate limits in this process", { path });
+  return memoryStore;
+}
+async function hitWithFallback(store, key, windowMs, failClosed, message, path) {
+  try {
+    return await store.hit(key, windowMs);
+  } catch (error) {
+    if (failClosed) {
+      throw new TooManyRequestsError({ message: message || "Rate limiter unavailable" });
+    }
+    rateLimitLogger.warn("Cache failed \u2014 counting this rate limit in the process instead", {
+      path,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return memoryStore.hit(key, windowMs);
+  }
+}
+var rateLimit = defineMiddlewareFactory(
+  "rateLimit",
+  (options) => {
+    const { limit, windowMs, scope, by, failClosed = false, message } = options;
+    return async (c, next) => {
+      const store = selectStore(failClosed, message, c.req.path);
+      const dimensions = (by ? await by(c) : [getClientIp(c)]).filter((d) => Boolean(d));
+      const ns = scope || `${c.req.method} ${c.req.routePath || c.req.path}`;
+      for (const dimension of dimensions) {
+        const key = typeof dimension === "string" ? dimension : dimension.key;
+        if (!key) {
+          continue;
+        }
+        const dimLimit = typeof dimension === "string" ? limit : dimension.limit ?? limit;
+        const { count, pttl } = await hitWithFallback(
+          store,
+          `ratelimit:${ns}:${key}`,
+          windowMs,
+          failClosed,
+          message,
+          c.req.path
+        );
+        if (count > dimLimit) {
+          const retryAfter = Math.max(1, Math.ceil((pttl > 0 ? pttl : windowMs) / 1e3));
+          c.header("Retry-After", String(retryAfter));
+          throw new TooManyRequestsError({
+            message: message || "Too many requests, please try again later",
+            retryAfter
+          });
+        }
+      }
+      return next();
+    };
+  }
+);
+var policyRegistry = /* @__PURE__ */ new Map();
+var policyFailClosedDefault = false;
+function setRateLimitFailClosedDefault(failClosed) {
+  policyFailClosedDefault = failClosed;
+}
+function setRateLimitPolicies(policies) {
+  policyRegistry.clear();
+  if (!policies) {
+    return;
+  }
+  for (const [name, options] of Object.entries(policies)) {
+    policyRegistry.set(name, options);
+  }
+}
+function getRateLimitPolicy(name) {
+  return policyRegistry.get(name);
+}
+function rateLimitPolicy(name, fallback) {
+  let resolved;
+  const handler = (c, next) => {
+    if (!resolved) {
+      const configured = getRateLimitPolicy(name);
+      const merged = configured ? { ...fallback, ...configured } : { ...fallback };
+      if (merged.scope === void 0) {
+        merged.scope = name;
+      }
+      if (merged.failClosed === void 0) {
+        merged.failClosed = policyFailClosedDefault;
+      }
+      resolved = rateLimit(merged);
+    }
+    return resolved(c, next);
   };
+  return defineMiddleware(`rateLimit:${name}`, handler);
 }
+
+// src/middleware/request-logger.ts
 var DEFAULT_CONFIG = {
   excludePaths: ["/health", "/ping", "/favicon.ico"],
   sensitiveFields: ["password", "token", "apiKey", "secret", "authorization"],
@@ -70,7 +1335,7 @@ function generateRequestId() {
   const randomPart = randomBytes(6).toString("hex");
   return `req_${timestamp}_${randomPart}`;
 }
-function maskSensitiveData(obj, sensitiveFields, seen = /* @__PURE__ */ new WeakSet()) {
+function maskSensitiveData2(obj, sensitiveFields, seen = /* @__PURE__ */ new WeakSet()) {
   if (!obj || typeof obj !== "object") return obj;
   if (seen.has(obj)) return "[Circular]";
   seen.add(obj);
@@ -81,7 +1346,7 @@ function maskSensitiveData(obj, sensitiveFields, seen = /* @__PURE__ */ new Weak
     if (lowerFields.some((field) => lowerKey.includes(field))) {
       masked[key] = "***MASKED***";
     } else if (typeof masked[key] === "object" && masked[key] !== null) {
-      masked[key] = maskSensitiveData(masked[key], sensitiveFields, seen);
+      masked[key] = maskSensitiveData2(masked[key], sensitiveFields, seen);
     }
   }
   return masked;
@@ -101,8 +1366,7 @@ function RequestLogger(options) {
     c.set("requestId", requestId);
     const method = c.req.method;
     const userAgent = c.req.header("user-agent");
-    const forwardedFor = c.req.header("x-forwarded-for");
-    const ip = forwardedFor?.split(",")[0]?.trim() || c.req.header("x-real-ip") || "unknown";
+    const ip = getClientIp(c);
     const startTime = Date.now();
     apiLogger.info("Request received", {
       requestId,
@@ -134,7 +1398,7 @@ function RequestLogger(options) {
         if (["POST", "PUT", "PATCH"].includes(method)) {
           try {
             const requestBody = await c.req.json();
-            logData.request = maskSensitiveData(requestBody, cfg.sensitiveFields);
+            logData.request = maskSensitiveData2(requestBody, cfg.sensitiveFields);
           } catch {
           }
         }
@@ -153,7 +1417,190 @@ function RequestLogger(options) {
     }
   };
 }
+var guardLogger = logger.child("@spfn/core:proxy-guard");
+var BODY_OVERSIZE = Symbol("proxy-guard:body-oversize");
+var BODY_READ_ERROR = Symbol("proxy-guard:body-read-error");
+async function readRawBody(c, maxBytes) {
+  const method = c.req.method;
+  if (method === "GET" || method === "HEAD") {
+    return void 0;
+  }
+  const contentType = c.req.header("content-type") || "";
+  if (contentType.includes("multipart/form-data")) {
+    return void 0;
+  }
+  const stream = c.req.raw.clone().body;
+  if (!stream) {
+    return void 0;
+  }
+  const reader = stream.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      total += value.byteLength;
+      if (maxBytes !== void 0 && total > maxBytes) {
+        void reader.cancel().catch(() => void 0);
+        return BODY_OVERSIZE;
+      }
+      chunks.push(value);
+    }
+  } catch {
+    guardLogger.debug("Request body read failed (client abort?)");
+    return BODY_READ_ERROR;
+  }
+  return Buffer.concat(chunks);
+}
+function isOriginAllowed(c, allowedOrigins) {
+  if (!allowedOrigins || allowedOrigins.length === 0) {
+    return true;
+  }
+  const origin = c.req.header("origin");
+  if (!origin) {
+    return true;
+  }
+  return allowedOrigins.includes(origin);
+}
+function createProxyGuard(config = {}) {
+  const mode = config.mode ?? "off";
+  const windowMs = config.windowMs ?? 3e4;
+  const allowedOrigins = config.allowedOrigins;
+  const nonceStore = config.nonceStore;
+  const nonceFailClosed = config.nonceFailClosed ?? false;
+  const skipPaths = new Set(config.skipPaths ?? []);
+  const maxBodyBytes = config.maxBodyBytes;
+  const activeRaw = config.secret ?? env.SPFN_PROXY_SECRET;
+  const previousRaw = config.previousSecrets ?? env.SPFN_PROXY_SECRET_PREVIOUS;
+  const keys = parseProxyKeySet([activeRaw, previousRaw]);
+  if (mode === "strict" && keys.length === 0) {
+    throw new Error(
+      '[proxy-guard] mode "strict" requires a proxy key but none is configured (SPFN_PROXY_SECRET is empty/unset). Refusing to start with the guard open \u2014 set the secret, or use mode "tag" / "off".'
+    );
+  }
+  if (activeRaw && previousRaw) {
+    const activeId = parseProxyKey(activeRaw).keyId;
+    const collides = previousRaw.split(",").some((p) => p.trim() && parseProxyKey(p.trim()).keyId === activeId);
+    if (collides) {
+      guardLogger.warn(
+        'Previous proxy key shares keyId with the active key (likely bare secrets without a "keyId:" prefix) \u2014 grace key ignored, rotation will drop in-flight requests. Use "<keyId>:<secret>" on both keys.',
+        { keyId: activeId }
+      );
+    }
+  }
+  return async (c, next) => {
+    if (mode === "off" || skipPaths.has(c.req.path)) {
+      return next();
+    }
+    if (c.req.method === "OPTIONS" && c.req.header("access-control-request-method")) {
+      c.set("clientType", "untrusted");
+      return next();
+    }
+    if (!isOriginAllowed(c, allowedOrigins)) {
+      return reject(c, mode, next, "origin-not-allowed");
+    }
+    if (keys.length === 0) {
+      c.set("clientType", "untrusted");
+      return next();
+    }
+    const signature = c.req.header(PROXY_SIGNATURE_HEADER);
+    const timestamp = c.req.header(PROXY_TIMESTAMP_HEADER);
+    const nonce = c.req.header(PROXY_NONCE_HEADER);
+    const keyId = c.req.header(PROXY_KEY_ID_HEADER);
+    if (!signature || !timestamp || !nonce || !keyId) {
+      return reject(c, mode, next, "missing-headers");
+    }
+    const body = await readRawBody(c, maxBodyBytes);
+    if (body === BODY_OVERSIZE) {
+      if (mode === "strict") {
+        return c.json({ error: "Payload Too Large" }, 413);
+      }
+      c.set("clientType", "untrusted");
+      return next();
+    }
+    if (body === BODY_READ_ERROR) {
+      return reject(c, mode, next, "body-read-error");
+    }
+    const url = new URL(c.req.url);
+    const result = verifyProxyRequest({
+      keys,
+      method: c.req.method,
+      path: url.pathname,
+      query: url.search,
+      body,
+      signature,
+      timestamp,
+      nonce,
+      keyId,
+      windowMs
+    });
+    if (!result.valid) {
+      return reject(c, mode, next, result.reason);
+    }
+    if (nonceStore && result.nonce) {
+      try {
+        const fresh = await nonceStore.checkAndSet(result.nonce, windowMs * 2);
+        if (!fresh) {
+          return reject(c, mode, next, "nonce-replay");
+        }
+      } catch (err) {
+        if (nonceFailClosed) {
+          guardLogger.warn("Nonce store unavailable \u2014 rejecting (fail-closed)", {
+            error: err.message
+          });
+          return reject(c, mode, next, "nonce-store-unavailable");
+        }
+        guardLogger.warn("Nonce store unavailable \u2014 falling back to timestamp window", {
+          error: err.message
+        });
+      }
+    }
+    c.set("clientType", "web");
+    return next();
+  };
+}
+function createCacheNonceStore(cache, prefix = "spfn:proxy-nonce:") {
+  return {
+    async checkAndSet(nonce, ttlMs) {
+      const res = await cache.set(`${prefix}${nonce}`, "1", "PX", Math.ceil(ttlMs), "NX");
+      return res === "OK";
+    }
+  };
+}
+function createInMemoryNonceStore() {
+  const seen = /* @__PURE__ */ new Map();
+  let lastSweep = 0;
+  return {
+    async checkAndSet(nonce, ttlMs) {
+      const now = Date.now();
+      if (now - lastSweep > 6e4) {
+        for (const [n, exp] of seen) {
+          if (exp <= now) seen.delete(n);
+        }
+        lastSweep = now;
+      }
+      const existing = seen.get(nonce);
+      if (existing !== void 0 && existing > now) {
+        return false;
+      }
+      seen.set(nonce, now + ttlMs);
+      return true;
+    }
+  };
+}
+function reject(c, mode, next, reason) {
+  if (mode === "strict") {
+    guardLogger.warn("Rejected unverified request", { reason, path: c.req.path, method: c.req.method });
+    return c.json({ error: "Forbidden", message: "Request origin could not be verified" }, 403);
+  }
+  guardLogger.debug("Unverified request (would reject in strict mode)", { reason, path: c.req.path });
+  c.set("clientType", "untrusted");
+  return next();
+}
 
-export { ErrorHandler, RequestLogger, maskSensitiveData };
+export { CacheRateLimitStore, ErrorHandler, MemoryRateLimitStore, RequestLogger, createCacheNonceStore, createInMemoryNonceStore, createProxyGuard, getClientIp, getRateLimitPolicy, maskSensitiveData2 as maskSensitiveData, rateLimit, rateLimitPolicy, resetMemoryRateLimitStore, setRateLimitFailClosedDefault, setRateLimitPolicies };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map