@jamesaphoenix/tx-api-server 0.1.1

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,iCAAiC;AACjC,OAAO,EACL,KAAK,EACL,QAAQ,EACR,UAAU,EACV,aAAa,EACb,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,UAAU,EACV,cAAc,EACd,SAAS,EACT,SAAS,GACV,MAAM,UAAU,CAAA;AAEjB,uBAAuB;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,uBAAuB;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/middleware/auth.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Authentication Middleware
+ *
+ * Provides optional API key authentication for securing endpoints.
+ * Authentication is disabled by default; enable by setting TX_API_KEY env var.
+ */
+import { HttpServerRequest, HttpServerResponse } from "@effect/platform";
+import { Effect } from "effect";
+/**
+ * Check if authentication is enabled.
+ */
+export declare const isAuthEnabled: () => boolean;
+/**
+ * Extract API key from request headers.
+ * Supports both Authorization header (Bearer token) and X-Api-Key header.
+ * @internal Exported for testing.
+ */
+export declare const extractApiKey: (headers: Record<string, string | undefined>) => string | null;
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ * Uses Node.js crypto.timingSafeEqual for proper constant-time comparison.
+ * @internal Exported for testing.
+ */
+export declare const timingSafeEqual: (provided: string, expected: string) => boolean;
+/**
+ * Effect HTTP authentication middleware.
+ * Only validates if TX_API_KEY environment variable is set.
+ * If not set, all requests pass through.
+ */
+export declare const authMiddleware: <E, R>(httpApp: import("@effect/platform/HttpApp").Default<E, R>) => Effect.Effect<HttpServerResponse.HttpServerResponse, E, R | HttpServerRequest.HttpServerRequest>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/middleware/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAkB,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;GAEG;AACH,eAAO,MAAM,aAAa,QAAO,OAAmC,CAAA;AAEpE;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAG,MAAM,GAAG,IAQpF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,UAAU,MAAM,KAAG,OAQpE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,uKA+B1B,CAAA"}

package/dist/middleware/auth.js

@@ -0,0 +1,65 @@
+/**
+ * Authentication Middleware
+ *
+ * Provides optional API key authentication for securing endpoints.
+ * Authentication is disabled by default; enable by setting TX_API_KEY env var.
+ */
+import { timingSafeEqual as cryptoTimingSafeEqual, createHash } from "node:crypto";
+import { HttpMiddleware, HttpServerRequest, HttpServerResponse } from "@effect/platform";
+import { Effect } from "effect";
+/**
+ * Check if authentication is enabled.
+ */
+export const isAuthEnabled = () => !!process.env.TX_API_KEY;
+/**
+ * Extract API key from request headers.
+ * Supports both Authorization header (Bearer token) and X-Api-Key header.
+ * @internal Exported for testing.
+ */
+export const extractApiKey = (headers) => {
+    const xApiKey = headers["x-api-key"];
+    if (xApiKey)
+        return xApiKey;
+    const authHeader = headers["authorization"];
+    if (authHeader?.startsWith("Bearer "))
+        return authHeader.slice(7);
+    return null;
+};
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ * Uses Node.js crypto.timingSafeEqual for proper constant-time comparison.
+ * @internal Exported for testing.
+ */
+export const timingSafeEqual = (provided, expected) => {
+    // Hash both inputs to fixed-length buffers to prevent leaking length information.
+    // This avoids the timing difference between the length-mismatch path
+    // (comparing expectedBuf against itself) and the normal comparison path.
+    const providedHash = createHash("sha256").update(provided).digest();
+    const expectedHash = createHash("sha256").update(expected).digest();
+    return cryptoTimingSafeEqual(providedHash, expectedHash);
+};
+/**
+ * Effect HTTP authentication middleware.
+ * Only validates if TX_API_KEY environment variable is set.
+ * If not set, all requests pass through.
+ */
+export const authMiddleware = HttpMiddleware.make((httpApp) => Effect.gen(function* () {
+    const requiredKey = process.env.TX_API_KEY;
+    // Skip auth if no API key is configured
+    if (!requiredKey)
+        return yield* httpApp;
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const url = request.url;
+    // Only require auth for /api routes
+    if (!url.startsWith("/api"))
+        return yield* httpApp;
+    const providedKey = extractApiKey(request.headers);
+    if (!providedKey) {
+        return yield* HttpServerResponse.json({ error: { code: "UNAUTHORIZED", message: "Missing API key. Provide via X-Api-Key header or Authorization: Bearer <key>" } }, { status: 401 }).pipe(Effect.orDie);
+    }
+    if (!timingSafeEqual(providedKey, requiredKey)) {
+        return yield* HttpServerResponse.json({ error: { code: "FORBIDDEN", message: "Invalid API key" } }, { status: 403 }).pipe(Effect.orDie);
+    }
+    return yield* httpApp;
+}));
+//# sourceMappingURL=auth.js.map

package/dist/middleware/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,IAAI,qBAAqB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAClF,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAY,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAA;AAEpE;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAA2C,EAAiB,EAAE;IAC1F,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IACpC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAA;IAE3B,MAAM,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAC3C,IAAI,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAEjE,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAAgB,EAAE,QAAgB,EAAW,EAAE;IAC7E,kFAAkF;IAClF,qEAAqE;IACrE,yEAAyE;IACzE,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAA;IACnE,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAA;IAEnE,OAAO,qBAAqB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAA;AAC1D,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAC5D,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAA;IAE1C,wCAAwC;IACxC,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC,CAAC,OAAO,CAAA;IAEvC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,iBAAiB,CAAC,iBAAiB,CAAA;IAC1D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAA;IAEvB,oCAAoC;IACpC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,OAAO,CAAA;IAElD,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC,OAAwD,CAAC,CAAA;IAEnG,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,KAAK,CAAC,CAAC,kBAAkB,CAAC,IAAI,CACnC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,8EAA8E,EAAE,EAAE,EAC5H,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;IAED,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC,CAAC,kBAAkB,CAAC,IAAI,CACnC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAAE,EAC5D,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;IAED,OAAO,KAAK,CAAC,CAAC,OAAO,CAAA;AACvB,CAAC,CAAC,CACH,CAAA"}

package/dist/middleware/body-limit.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Body Size Limit Middleware
+ *
+ * Prevents DoS via memory exhaustion by enforcing request body size limits.
+ * - 1MB for standard API endpoints (tasks, learnings, runs)
+ * - 10MB for sync endpoints (bulk data import/export)
+ *
+ * Uses two mechanisms:
+ * 1. Content-Length header check for early rejection (fast path)
+ * 2. MaxBodySize context for safety during body parsing (handles chunked encoding)
+ */
+import { HttpServerRequest, HttpServerResponse } from "@effect/platform";
+import { Effect } from "effect";
+/** Default body size limit: 1MB */
+export declare const DEFAULT_MAX_BYTES: number;
+/** Sync endpoint body size limit: 10MB */
+export declare const SYNC_MAX_BYTES: number;
+/**
+ * Get the max body size limit based on the request path.
+ * Sync endpoints get a higher limit (10MB) since they handle bulk data.
+ * All other endpoints get 1MB.
+ * @internal Exported for testing.
+ */
+export declare const getMaxBytes: (url: string) => number;
+/**
+ * Body size limit middleware.
+ *
+ * Rejects requests with Content-Length exceeding the limit with 413 Payload Too Large.
+ * Also sets MaxBodySize context as a safety net during body parsing
+ * (handles chunked transfer encoding where Content-Length is absent).
+ */
+export declare const bodyLimitMiddleware: <E, R>(httpApp: import("@effect/platform/HttpApp").Default<E, R>) => Effect.Effect<HttpServerResponse.HttpServerResponse, E, HttpServerRequest.HttpServerRequest | R>;
+//# sourceMappingURL=body-limit.d.ts.map

package/dist/middleware/body-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-limit.d.ts","sourceRoot":"","sources":["../../src/middleware/body-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAkB,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAExF,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAA;AAEvC,mCAAmC;AACnC,eAAO,MAAM,iBAAiB,QAAkB,CAAA;AAEhD,0CAA0C;AAC1C,eAAO,MAAM,cAAc,QAAmB,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAGzC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,uKAmB/B,CAAA"}

package/dist/middleware/body-limit.js

@@ -0,0 +1,50 @@
+/**
+ * Body Size Limit Middleware
+ *
+ * Prevents DoS via memory exhaustion by enforcing request body size limits.
+ * - 1MB for standard API endpoints (tasks, learnings, runs)
+ * - 10MB for sync endpoints (bulk data import/export)
+ *
+ * Uses two mechanisms:
+ * 1. Content-Length header check for early rejection (fast path)
+ * 2. MaxBodySize context for safety during body parsing (handles chunked encoding)
+ */
+import { HttpMiddleware, HttpServerRequest, HttpServerResponse } from "@effect/platform";
+import * as IncomingMessage from "@effect/platform/HttpIncomingMessage";
+import { Effect, Option } from "effect";
+/** Default body size limit: 1MB */
+export const DEFAULT_MAX_BYTES = 1 * 1024 * 1024;
+/** Sync endpoint body size limit: 10MB */
+export const SYNC_MAX_BYTES = 10 * 1024 * 1024;
+/**
+ * Get the max body size limit based on the request path.
+ * Sync endpoints get a higher limit (10MB) since they handle bulk data.
+ * All other endpoints get 1MB.
+ * @internal Exported for testing.
+ */
+export const getMaxBytes = (url) => {
+    if (url.startsWith("/api/sync"))
+        return SYNC_MAX_BYTES;
+    return DEFAULT_MAX_BYTES;
+};
+/**
+ * Body size limit middleware.
+ *
+ * Rejects requests with Content-Length exceeding the limit with 413 Payload Too Large.
+ * Also sets MaxBodySize context as a safety net during body parsing
+ * (handles chunked transfer encoding where Content-Length is absent).
+ */
+export const bodyLimitMiddleware = HttpMiddleware.make((httpApp) => Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const maxBytes = getMaxBytes(request.url);
+    const contentLength = request.headers["content-length"];
+    if (contentLength) {
+        const size = parseInt(contentLength, 10);
+        if (!isNaN(size) && size > maxBytes) {
+            return yield* HttpServerResponse.json({ error: { code: "PAYLOAD_TOO_LARGE", message: `Request body exceeds maximum size of ${maxBytes} bytes` } }, { status: 413 }).pipe(Effect.orDie);
+        }
+    }
+    // Set MaxBodySize for safety during body parsing (handles chunked transfer encoding)
+    return yield* IncomingMessage.withMaxBodySize(httpApp, Option.some(maxBytes));
+}));
+//# sourceMappingURL=body-limit.js.map

package/dist/middleware/body-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-limit.js","sourceRoot":"","sources":["../../src/middleware/body-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,KAAK,eAAe,MAAM,sCAAsC,CAAA;AACvE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEvC,mCAAmC;AACnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAA;AAEhD,0CAA0C;AAC1C,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAW,EAAU,EAAE;IACjD,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,cAAc,CAAA;IACtD,OAAO,iBAAiB,CAAA;AAC1B,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CACjE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,iBAAiB,CAAC,iBAAiB,CAAA;IAC1D,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAEzC,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACvD,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,EAAE,EAAE,CAAC,CAAA;QACxC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,QAAQ,EAAE,CAAC;YACpC,OAAO,KAAK,CAAC,CAAC,kBAAkB,CAAC,IAAI,CACnC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,wCAAwC,QAAQ,QAAQ,EAAE,EAAE,EAC3G,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtB,CAAC;IACH,CAAC;IAED,qFAAqF;IACrF,OAAO,KAAK,CAAC,CAAC,eAAe,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAA;AAC/E,CAAC,CAAC,CACH,CAAA"}

package/dist/middleware/cors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CORS Configuration
+ *
+ * Provides CORS configuration for the API server.
+ * Default: localhost-only origins. Set TX_API_CORS_ORIGIN="*" for wildcard (not recommended in production).
+ */
+export declare const getCorsConfig: () => {
+    allowedOrigins: string[];
+    allowedMethods: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+    allowedHeaders: string[];
+    exposedHeaders: string[];
+    maxAge: number;
+    credentials: boolean;
+};
+//# sourceMappingURL=cors.d.ts.map

package/dist/middleware/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../src/middleware/cors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,eAAO,MAAM,aAAa;;;;;;;CAczB,CAAA"}

package/dist/middleware/cors.js

@@ -0,0 +1,31 @@
+/**
+ * CORS Configuration
+ *
+ * Provides CORS configuration for the API server.
+ * Default: localhost-only origins. Set TX_API_CORS_ORIGIN="*" for wildcard (not recommended in production).
+ */
+/** Default CORS origins: localhost on common dev ports. Never wildcard by default. */
+const DEFAULT_CORS_ORIGINS = [
+    "http://localhost:3000",
+    "http://localhost:3001",
+    "http://localhost:5173",
+    "http://127.0.0.1:3000",
+    "http://127.0.0.1:3001",
+    "http://127.0.0.1:5173",
+];
+export const getCorsConfig = () => {
+    const originEnv = process.env.TX_API_CORS_ORIGIN;
+    return {
+        allowedOrigins: originEnv
+            ? originEnv === "*"
+                ? ["*"]
+                : originEnv.split(",").map((o) => o.trim())
+            : DEFAULT_CORS_ORIGINS,
+        allowedMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+        allowedHeaders: ["Content-Type", "Authorization", "X-Api-Key"],
+        exposedHeaders: ["X-Total-Count", "X-Next-Cursor"],
+        maxAge: 86400,
+        credentials: process.env.TX_API_CORS_CREDENTIALS === "true",
+    };
+};
+//# sourceMappingURL=cors.js.map

package/dist/middleware/cors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.js","sourceRoot":"","sources":["../../src/middleware/cors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sFAAsF;AACtF,MAAM,oBAAoB,GAAG;IAC3B,uBAAuB;IACvB,uBAAuB;IACvB,uBAAuB;IACvB,uBAAuB;IACvB,uBAAuB;IACvB,uBAAuB;CACxB,CAAA;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,EAAE;IAChC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAA;IAChD,OAAO;QACL,cAAc,EAAE,SAAS;YACvB,CAAC,CAAC,SAAS,KAAK,GAAG;gBACjB,CAAC,CAAC,CAAC,GAAY,CAAC;gBAChB,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC7C,CAAC,CAAC,oBAAoB;QACxB,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAU;QAC7E,cAAc,EAAE,CAAC,cAAc,EAAE,eAAe,EAAE,WAAW,CAAC;QAC9D,cAAc,EAAE,CAAC,eAAe,EAAE,eAAe,CAAC;QAClD,MAAM,EAAE,KAAK;QACb,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,MAAM;KAC5D,CAAA;AACH,CAAC,CAAA"}

package/dist/middleware/error.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Error Handling Middleware
+ *
+ * Provides consistent error responses across all API endpoints.
+ */
+import type { Context, Next } from "hono";
+/**
+ * Standard API error response format.
+ */
+export interface ApiError {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * Global error handling middleware.
+ * Catches all errors and returns consistent JSON responses.
+ */
+export declare const errorHandler: (c: Context, next: Next) => Promise<Response>;
+/**
+ * Not found handler for undefined routes.
+ */
+export declare const notFoundHandler: (c: Context) => Response;
+//# sourceMappingURL=error.d.ts.map

package/dist/middleware/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/middleware/error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAIzC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,CAAC,EAAE,OAAO,CAAA;KAClB,CAAA;CACF;AA6CD;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAU,GAAG,OAAO,EAAE,MAAM,IAAI,KAAG,OAAO,CAAC,QAAQ,CAyB3E,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,KAAG,QAU5C,CAAA"}

package/dist/middleware/error.js

@@ -0,0 +1,84 @@
+/**
+ * Error Handling Middleware
+ *
+ * Provides consistent error responses across all API endpoints.
+ */
+import { HTTPException } from "hono/http-exception";
+/**
+ * Map error types to HTTP status codes.
+ */
+const getStatusCode = (error) => {
+    if (error instanceof HTTPException) {
+        return error.status;
+    }
+    // Handle tx-core errors by name
+    if (error && typeof error === "object" && "_tag" in error) {
+        const tag = error._tag;
+        switch (tag) {
+            case "TaskNotFoundError":
+            case "LearningNotFoundError":
+            case "FileLearningNotFoundError":
+            case "AttemptNotFoundError":
+                return 404;
+            case "ValidationError":
+            case "CircularDependencyError":
+                return 400;
+            case "DatabaseError":
+                return 500;
+            case "EmbeddingUnavailableError":
+                return 503;
+        }
+    }
+    return 500;
+};
+/**
+ * Extract error code from various error types.
+ */
+const getErrorCode = (error) => {
+    if (error && typeof error === "object" && "_tag" in error) {
+        return error._tag;
+    }
+    if (error instanceof HTTPException) {
+        return `HTTP_${error.status}`;
+    }
+    return "INTERNAL_ERROR";
+};
+/**
+ * Global error handling middleware.
+ * Catches all errors and returns consistent JSON responses.
+ */
+export const errorHandler = async (c, next) => {
+    try {
+        await next();
+    }
+    catch (error) {
+        const status = getStatusCode(error);
+        const code = getErrorCode(error);
+        const message = error instanceof Error ? error.message : String(error);
+        const body = {
+            error: {
+                code,
+                message
+            }
+        };
+        // Include details for validation errors
+        if (error && typeof error === "object" && "details" in error) {
+            body.error.details = error.details;
+        }
+        return c.json(body, status);
+    }
+    // If no response was set by handler, return the response from context
+    return c.res;
+};
+/**
+ * Not found handler for undefined routes.
+ */
+export const notFoundHandler = (c) => {
+    return c.json({
+        error: {
+            code: "NOT_FOUND",
+            message: `Route ${c.req.method} ${c.req.path} not found`
+        }
+    }, 404);
+};
+//# sourceMappingURL=error.js.map

package/dist/middleware/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/middleware/error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAanD;;GAEG;AACH,MAAM,aAAa,GAAG,CAAC,KAAc,EAAwB,EAAE;IAC7D,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC,MAA8B,CAAA;IAC7C,CAAC;IAED,gCAAgC;IAChC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QAC1D,MAAM,GAAG,GAAI,KAA0B,CAAC,IAAI,CAAA;QAC5C,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,mBAAmB,CAAC;YACzB,KAAK,uBAAuB,CAAC;YAC7B,KAAK,2BAA2B,CAAC;YACjC,KAAK,sBAAsB;gBACzB,OAAO,GAAG,CAAA;YACZ,KAAK,iBAAiB,CAAC;YACvB,KAAK,yBAAyB;gBAC5B,OAAO,GAAG,CAAA;YACZ,KAAK,eAAe;gBAClB,OAAO,GAAG,CAAA;YACZ,KAAK,2BAA2B;gBAC9B,OAAO,GAAG,CAAA;QACd,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,YAAY,GAAG,CAAC,KAAc,EAAU,EAAE;IAC9C,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QAC1D,OAAQ,KAA0B,CAAC,IAAI,CAAA;IACzC,CAAC;IACD,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACnC,OAAO,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAA;IAC/B,CAAC;IACD,OAAO,gBAAgB,CAAA;AACzB,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAAE,CAAU,EAAE,IAAU,EAAqB,EAAE;IAC9E,IAAI,CAAC;QACH,MAAM,IAAI,EAAE,CAAA;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAA;QACnC,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAA;QAChC,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAEtE,MAAM,IAAI,GAAa;YACrB,KAAK,EAAE;gBACL,IAAI;gBACJ,OAAO;aACR;SACF,CAAA;QAED,wCAAwC;QACxC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;YAC7D,IAAI,CAAC,KAAK,CAAC,OAAO,GAAI,KAA8B,CAAC,OAAO,CAAA;QAC9D,CAAC;QAED,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAC7B,CAAC;IAED,sEAAsE;IACtE,OAAO,CAAC,CAAC,GAAG,CAAA;AACd,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAU,EAAY,EAAE;IACtD,OAAO,CAAC,CAAC,IAAI,CACX;QACE,KAAK,EAAE;YACL,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,YAAY;SACzD;KACiB,EACpB,GAAG,CACJ,CAAA;AACH,CAAC,CAAA"}

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Rate Limiting Middleware
+ *
+ * Provides configurable rate limiting to protect the API from abuse.
+ * Uses a sliding window algorithm with in-memory storage.
+ *
+ * Rate limiting is disabled by default; enable by setting TX_API_RATE_LIMIT env var.
+ *
+ * SECURITY NOTE: By default, proxy headers (X-Forwarded-For, X-Real-IP) are NOT trusted.
+ * Set TX_API_TRUST_PROXY=true ONLY when running behind a trusted reverse proxy.
+ * Otherwise, attackers can bypass rate limiting by spoofing these headers.
+ */
+import type { Context, Next } from "hono";
+/**
+ * Rate limit configuration options.
+ */
+export interface RateLimitConfig {
+    /** Maximum requests per window (default: 100) */
+    max: number;
+    /** Window size in seconds (default: 60) */
+    windowSec: number;
+    /** Message to return when rate limited */
+    message: string;
+    /** Whether to skip rate limiting for health endpoints */
+    skipHealthEndpoints: boolean;
+    /** Whether to trust proxy headers like X-Forwarded-For (default: false for security) */
+    trustProxy: boolean;
+}
+/**
+ * Check if rate limiting is enabled.
+ */
+export declare const isRateLimitEnabled: () => boolean;
+/**
+ * Check if proxy headers should be trusted.
+ * Only enable this when running behind a trusted reverse proxy.
+ */
+export declare const isTrustProxyEnabled: () => boolean;
+/**
+ * Rate limiting middleware.
+ * Only applies rate limiting if TX_API_RATE_LIMIT environment variable is set.
+ * If not set, all requests are allowed through.
+ */
+export declare const rateLimitMiddleware: (c: Context, next: Next) => Promise<void | Response>;
+/**
+ * Create rate limit middleware with custom configuration.
+ * Useful for applying different limits to specific routes.
+ */
+export declare const createRateLimitMiddleware: (customConfig: Partial<RateLimitConfig>) => (c: Context, next: Next) => Promise<void | Response>;
+/**
+ * Reset rate limit for a specific client.
+ * Useful for testing or administrative purposes.
+ */
+export declare const resetRateLimit: (clientId: string) => void;
+/**
+ * Clear all rate limit entries.
+ * Useful for testing.
+ */
+export declare const clearAllRateLimits: () => void;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAIzC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAA;IACX,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,mBAAmB,EAAE,OAAO,CAAA;IAC5B,wFAAwF;IACxF,UAAU,EAAE,OAAO,CAAA;CACpB;AA6DD;;GAEG;AACH,eAAO,MAAM,kBAAkB,QAAO,OAErC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAO,OAEtC,CAAA;AA0JD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAU,GAAG,OAAO,EAAE,MAAM,IAAI,KAAG,OAAO,CAAC,IAAI,GAAG,QAAQ,CA2CzF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,OAAO,CAAC,eAAe,CAAC,MAGhE,GAAG,OAAO,EAAE,MAAM,IAAI,KAAG,OAAO,CAAC,IAAI,GAAG,QAAQ,CAqD/D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,KAAG,IAEjD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAO,IAErC,CAAA"}