shokupan 0.6.0 → 0.6.1

package/README.md

@@ -7,6 +7,8 @@ Shokupan is designed to make building APIs delightful again. With zero-config de
 
 ### Note: Shokupan is still in alpha and is not guaranteed to be stable. Please use with caution. We will be adding more features and APIs in the future. Please file an issue if you find any bugs or have suggestions for improvement.
 
+📚 **[Full documentation available at https://shokupan.dev](https://shokupan.dev)**
+
 ## ✨ Features
 
 - 🎯 **TypeScript First** - End-to-end type safety with decorators and generics. No manual types needed.

package/dist/context.d.ts

@@ -18,12 +18,73 @@ export interface DebugCollector {
     setNode(id: string): void;
     getCurrentNode(): string | undefined;
 }
-export declare class ShokupanContext<State extends Record<string, any> = Record<string, any>> {
+/**
+ * Shokupan Request Context
+ *
+ * The context object passed to all middleware and route handlers.
+ * Provides access to request data, response helpers, and typed state management.
+ *
+ * @template State - The shape of `ctx.state` for type-safe state access across middleware.
+ * @template Params - The shape of `ctx.params` based on the route path pattern.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * app.get('/hello', (ctx) => {
+ *   return ctx.json({ message: 'Hello' });
+ * });
+ * ```
+ *
+ * @example Typed State
+ * ```typescript
+ * interface AppState {
+ *   userId: string;
+ *   requestId: string;
+ * }
+ *
+ * const app = new Shokupan<AppState>();
+ *
+ * app.use((ctx, next) => {
+ *   ctx.state.requestId = crypto.randomUUID(); // ✓ Type-safe
+ *   return next();
+ * });
+ * ```
+ *
+ * @example Typed Path Parameters
+ * ```typescript
+ * app.get('/users/:userId/posts/:postId', (ctx) => {
+ *   // ctx.params is automatically typed as { userId: string; postId: string }
+ *   const { userId, postId } = ctx.params;
+ *   return ctx.json({ userId, postId });
+ * });
+ * ```
+ *
+ * @example Full Type Safety (State + Params)
+ * ```typescript
+ * interface RequestState {
+ *   userId: string;
+ *   permissions: string[];
+ * }
+ *
+ * const app = new Shokupan<RequestState>();
+ *
+ * app.get('/admin/users/:userId', (ctx) => {
+ *   // Both typed!
+ *   const { userId } = ctx.params;        // ✓ From path
+ *   const { permissions } = ctx.state;     // ✓ From state
+ *
+ *   if (!permissions.includes('admin')) {
+ *     return ctx.json({ error: 'Forbidden' }, 403);
+ *   }
+ *   return ctx.json({ userId });
+ * });
+ * ```
+ */
+export declare class ShokupanContext<State extends Record<string, any> = Record<string, any>, Params extends Record<string, string> = Record<string, string>> {
     readonly request: ShokupanRequest<any>;
     readonly server?: Server;
     readonly app?: Shokupan;
     readonly signal?: AbortSignal;
-    params: Record<string, string>;
+    params: Params;
     state: State;
     handlerStack: HandlerStackItem[];
     readonly response: ShokupanResponse;

package/dist/index.cjs

@@ -119,6 +119,15 @@ class ShokupanResponse {
     return this._headers !== null;
   }
 }
+function isValidCookieDomain(domain, currentHost) {
+  const hostWithoutPort = currentHost.split(":")[0];
+  if (domain === hostWithoutPort) return true;
+  if (domain.startsWith(".")) {
+    const domainWithoutDot = domain.slice(1);
+    return hostWithoutPort.endsWith(domainWithoutDot);
+  }
+  return false;
+}
 const VALID_HTTP_STATUSES = /* @__PURE__ */ new Set([
   100,
   101,
@@ -278,16 +287,20 @@ class ShokupanContext {
    */
   get query() {
     if (this._cachedQuery) return this._cachedQuery;
-    const q = {};
+    const q = /* @__PURE__ */ Object.create(null);
+    const blocklist = ["__proto__", "constructor", "prototype"];
     const entries = Object.entries(this.url.searchParams);
     for (let i = 0; i < entries.length; i++) {
       const [key, value] = entries[i];
-      if (q[key] === void 0) {
-        q[key] = value;
-      } else if (Array.isArray(q[key])) {
-        q[key].push(value);
+      if (blocklist.includes(key)) continue;
+      if (Object.prototype.hasOwnProperty.call(q, key)) {
+        if (Array.isArray(q[key])) {
+          q[key].push(value);
+        } else {
+          q[key] = [q[key], value];
+        }
       } else {
-        q[key] = [q[key], value];
+        q[key] = value;
       }
     }
     this._cachedQuery = q;
@@ -364,6 +377,12 @@ class ShokupanContext {
    * @param options Cookie options
    */
   setCookie(name, value, options = {}) {
+    if (options.domain) {
+      const currentHost = this.hostname;
+      if (!isValidCookieDomain(options.domain, currentHost)) {
+        throw new Error(`Invalid cookie domain: ${options.domain} for host ${currentHost}`);
+      }
+    }
     let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
     if (options.maxAge) cookie += `; Max-Age=${Math.floor(options.maxAge)}`;
     if (options.domain) cookie += `; Domain=${options.domain}`;
@@ -657,11 +676,24 @@ function RateLimitMiddleware(options = {}) {
   const statusCode = options.statusCode || 429;
   const headers = options.headers !== false;
   const mode = options.mode || "user";
+  const trustedProxies = options.trustedProxies || [];
   const keyGenerator = options.keyGenerator || ((ctx) => {
     if (mode === "absolute") {
       return "global";
     }
-    return ctx.headers.get("x-forwarded-for") || ctx.request.headers.get("x-forwarded-for") || ctx.server?.requestIP?.(ctx.request)?.address || "unknown";
+    const xForwardedFor = ctx.headers.get("x-forwarded-for");
+    if (xForwardedFor && trustedProxies.length > 0) {
+      const ips = xForwardedFor.split(",").map((ip) => ip.trim());
+      for (let i = ips.length - 1; i >= 0; i--) {
+        const ip = ips[i];
+        if (!trustedProxies.includes(ip)) {
+          if (/^[\d.:a-fA-F]+$/.test(ip)) {
+            return ip;
+          }
+        }
+      }
+    }
+    return ctx.server?.requestIP?.(ctx.request)?.address || "unknown";
   });
   const skip = options.skip || (() => false);
   const hits = /* @__PURE__ */ new Map();
@@ -1337,12 +1369,23 @@ function serveStatic(config, prefix) {
     let relative = ctx.path.slice(normalizedPrefix.length);
     if (!relative.startsWith("/") && relative.length > 0) relative = "/" + relative;
     if (relative.length === 0) relative = "/";
-    relative = decodeURIComponent(relative);
-    const requestPath = path.join(rootPath, relative);
-    if (!requestPath.startsWith(rootPath)) {
+    if (relative.includes("\0")) {
+      return ctx.json({ error: "Forbidden" }, 403);
+    }
+    try {
+      relative = decodeURIComponent(relative);
+    } catch (e) {
+      return ctx.json({ error: "Bad Request" }, 400);
+    }
+    if (relative.includes("\0")) {
+      return ctx.json({ error: "Forbidden" }, 403);
+    }
+    if (relative.includes("../") || relative.includes("..\\")) {
       return ctx.json({ error: "Forbidden" }, 403);
     }
-    if (requestPath.includes("\0")) {
+    const requestPath = path.resolve(path.join(rootPath, relative));
+    const normalizedRoot = path.resolve(rootPath);
+    if (!requestPath.startsWith(normalizedRoot + path.sep) && requestPath !== normalizedRoot) {
       return ctx.json({ error: "Forbidden" }, 403);
     }
     if (config.hooks?.onRequest) {
@@ -2191,10 +2234,13 @@ class ShokupanRouter {
   }
   parsePath(path2) {
     const keys = [];
+    if (path2.length > 2048) {
+      throw new Error("Path too long");
+    }
     const pattern = path2.replace(/:([a-zA-Z0-9_]+)/g, (_, key) => {
       keys.push(key);
-      return "([^/]+)";
-    }).replace(/\*\*/g, ".*").replace(/\*/g, "[^/]+");
+      return "([^/]{1,255})";
+    }).replace(/\*\*/g, ".{0,1000}").replace(/\*/g, "[^/]{1,255}");
     return {
       regex: new RegExp(`^${pattern}$`),
       keys
@@ -2982,9 +3028,10 @@ class AuthPlugin extends ShokupanRouter {
         } else {
           return ctx.text("Provider config error", 500);
         }
-        ctx.res.headers.set("Set-Cookie", `oauth_state=${state}; Path=/; HttpOnly; Max-Age=600`);
+        const isSecure = ctx.secure;
+        ctx.res.headers.set("Set-Cookie", `oauth_state=${state}; Path=/; HttpOnly; SameSite=Lax${isSecure ? "; Secure" : ""}; Max-Age=600`);
         if (codeVerifier) {
-          ctx.res.headers.append("Set-Cookie", `oauth_verifier=${codeVerifier}; Path=/; HttpOnly; Max-Age=600`);
+          ctx.res.headers.append("Set-Cookie", `oauth_verifier=${codeVerifier}; Path=/; HttpOnly; SameSite=Lax${isSecure ? "; Secure" : ""}; Max-Age=600`);
         }
         return ctx.redirect(url.toString());
       });
@@ -3025,7 +3072,7 @@ class AuthPlugin extends ShokupanRouter {
           return ctx.json({ token: jwt, user });
         } catch (e) {
           console.error("Auth Error", e);
-          return ctx.text("Authentication failed: " + e.message + "\n" + e.stack, 500);
+          return ctx.text("Authentication failed. Please try again.", 500);
         }
       });
     }
@@ -3236,14 +3283,21 @@ function Cors(options = {}) {
     const origin = ctx.headers.get("origin");
     const set = (k, v) => headers.set(k, v);
     const append = (k, v) => headers.append(k, v);
+    if (origin === "null" && opts.origin !== "null") {
+      return next();
+    }
     if (opts.origin === "*") {
       set("Access-Control-Allow-Origin", "*");
     } else if (typeof opts.origin === "string") {
       set("Access-Control-Allow-Origin", opts.origin);
     } else if (Array.isArray(opts.origin)) {
-      if (origin && opts.origin.includes(origin)) {
-        set("Access-Control-Allow-Origin", origin);
-        append("Vary", "Origin");
+      if (origin) {
+        const normalizedOrigin = origin.toLowerCase();
+        const normalizedAllowed = opts.origin.map((o) => o.toLowerCase());
+        if (normalizedAllowed.includes(normalizedOrigin)) {
+          set("Access-Control-Allow-Origin", origin);
+          append("Vary", "Origin");
+        }
       }
     } else if (typeof opts.origin === "function") {
       const allowed = opts.origin(ctx);
@@ -3930,11 +3984,17 @@ function unsign(input, secret) {
   if (typeof secret !== "string") throw new TypeError("Secret string must be provided.");
   const tentValue = input.slice(0, input.lastIndexOf("."));
   const expectedInput = sign(tentValue, secret);
-  const expectedBuffer = Buffer.from(expectedInput);
-  const inputBuffer = Buffer.from(input);
-  if (expectedBuffer.length !== inputBuffer.length) return false;
-  const valid = require("crypto").timingSafeEqual(expectedBuffer, inputBuffer);
-  return valid ? tentValue : false;
+  const maxLength = Math.max(expectedInput.length, input.length);
+  const paddedExpected = Buffer.alloc(maxLength);
+  const paddedInput = Buffer.alloc(maxLength);
+  Buffer.from(expectedInput).copy(paddedExpected);
+  Buffer.from(input).copy(paddedInput);
+  try {
+    const valid = require("crypto").timingSafeEqual(paddedExpected, paddedInput);
+    return valid ? tentValue : false;
+  } catch {
+    return false;
+  }
 }
 function Session(options) {
   const store = options.store || new MemoryStore();