@just-be/wildcard 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# @just-be/wildcard
+
+Portable wildcard subdomain routing library with pluggable storage backends. Route subdomains to static files, redirects, or proxied URLs with dependency injection for maximum flexibility.
+
+## Features
+
+- 🔌 **Pluggable storage backends** - Use any file storage (R2, S3, filesystem, etc.)
+- 🔒 **Security built-in** - SSRF protection, path traversal prevention, safe header filtering
+- 📦 **Three routing modes**:
+  - **Static** - Serve files from any storage backend with SPA mode and custom 404s
+  - **Redirect** - 301/302 redirects to external URLs
+  - **Rewrite** - Proxy requests to external services
+- 🏗️ **Framework-agnostic** - Works with Cloudflare Workers, Node.js, Deno, Bun, etc.
+- ✅ **Type-safe** - Full TypeScript support with Zod validation
+
+## Installation
+
+```bash
+bun add @just-be/wildcard zod
+```
+
+## Quick Start
+
+### 1. Implement Storage Adapters
+
+```ts
+import type { FileLoader, RouteConfigLoader } from "@just-be/wildcard";
+
+// Implement your file loader (example with filesystem)
+const fileLoader: FileLoader = {
+  async loadFile(path: string) {
+    try {
+      const content = await fs.readFile(path);
+      return {
+        body: content,
+        etag: generateEtag(content),
+        headers: new Headers(),
+      };
+    } catch {
+      return null;
+    }
+  },
+};
+
+// Implement your route config loader (example with JSON file)
+const routeConfigLoader: RouteConfigLoader = {
+  async loadRouteConfig(subdomain: string) {
+    try {
+      const config = await fs.readFile(`./config/${subdomain}.json`, "utf-8");
+      return config;
+    } catch {
+      return null;
+    }
+  },
+};
+```
+
+### 2. Use the Handlers
+
+```ts
+import { handleStatic, handleRedirect, handleRewrite, StaticConfigSchema } from "@just-be/wildcard";
+
+// Load and validate config
+const configJson = await routeConfigLoader.loadRouteConfig("myapp");
+const config = StaticConfigSchema.parse(JSON.parse(configJson));
+
+// Handle the request - pass dependencies after config
+const response = await handleStatic(request, config, fileLoader);
+
+// Handlers without dependencies don't need extra args
+const redirectResponse = await handleRedirect(request, redirectConfig);
+```
+
+## Configuration Schemas
+
+### Static File Serving
+
+```ts
+import { StaticConfigSchema } from "@just-be/wildcard";
+
+const config = {
+  type: "static",
+  path: "apps/myapp", // Base path in storage
+  spa: true, // Optional: SPA mode (all routes serve index.html)
+  fallback: "404.html", // Optional: Custom 404 (only in non-SPA mode)
+};
+```
+
+### Redirect
+
+```ts
+import { RedirectConfigSchema } from "@just-be/wildcard";
+
+const config = {
+  type: "redirect",
+  url: "https://example.com",
+  permanent: false, // Optional: 301 vs 302
+};
+```
+
+### Rewrite (Proxy)
+
+```ts
+import { RewriteConfigSchema } from "@just-be/wildcard";
+
+const config = {
+  type: "rewrite",
+  url: "https://api.example.com",
+  allowedMethods: ["GET", "POST"], // Optional: defaults to ["GET", "HEAD", "OPTIONS"]
+};
+```
+
+## Dependency Injection
+
+The library uses dependency injection to decouple from specific storage backends:
+
+```ts
+interface FileLoader {
+  loadFile(path: string): Promise<FileObject | null>;
+}
+
+interface RouteConfigLoader {
+  loadRouteConfig(subdomain: string): Promise<string | null>;
+}
+
+interface FileObject {
+  body: ReadableStream<Uint8Array> | ArrayBuffer | null;
+  headers?: Headers;
+  etag?: string;
+  size?: number;
+}
+```
+
+## Security Features
+
+- **SSRF Protection** - Blocks requests to private IPs and localhost
+- **Path Traversal Prevention** - Sanitizes all file paths
+- **Header Filtering** - Only forwards safe headers in proxy mode
+- **Content Type Detection** - Sets correct MIME types
+- **Security Headers** - Adds CSP, X-Frame-Options, etc.
+
+## Example: Cloudflare Workers
+
+See the `services/wildcard` directory for a complete Cloudflare Workers implementation using R2 and KV.
+
+## API Reference
+
+### Handlers
+
+- `handleStatic(request, config, fileLoader)` - Serve static files from storage
+- `handleRedirect(request, config)` - Handle URL redirects (301/302)
+- `handleRewrite(request, config)` - Proxy requests to external services
+
+### Schemas
+
+- `StaticConfigSchema` - Validates static file config
+- `RedirectConfigSchema` - Validates redirect config
+- `RewriteConfigSchema` - Validates rewrite config
+- `RouteConfigSchema` - Discriminated union of all configs
+- `R2ConfigSchema` - (Deprecated) Alias for StaticConfigSchema
+
+### Utilities
+
+- `sanitizePath(path)` - Sanitize file paths
+- `isSafeURL(url)` - Validate URLs for SSRF
+- `getContentType(path)` - Detect MIME types
+- `filterSafeHeaders(headers)` - Filter request headers
+- `isValidSubdomain(subdomain)` - Validate subdomain format
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@just-be/wildcard",
+  "version": "0.1.0",
+  "description": "Portable wildcard subdomain routing with pluggable storage backends",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./schemas": "./src/schemas.ts",
+    "./handlers": "./src/handlers/index.ts",
+    "./types": "./src/types.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "wildcard",
+    "subdomain",
+    "routing",
+    "static-site",
+    "redirect",
+    "proxy"
+  ],
+  "author": "Justin Bennett",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/justbejyk/just-be.dev.git",
+    "directory": "packages/wildcard"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  }
+}

package/src/handlers/index.ts

@@ -0,0 +1,3 @@
+export { handleStatic } from "./static";
+export { handleRedirect } from "./redirect";
+export { handleRewrite } from "./rewrite";

package/src/handlers/redirect.ts

@@ -0,0 +1,7 @@
+import type { Handler } from "../types";
+import type { RedirectConfig } from "../schemas";
+
+export const handleRedirect: Handler<RedirectConfig> = async (_request, config) => {
+  const status = config.permanent ? 301 : 302;
+  return Response.redirect(config.url, status);
+};

package/src/handlers/rewrite.ts

@@ -0,0 +1,64 @@
+import type { Handler } from "../types";
+import type { RewriteConfig } from "../schemas";
+import { filterSafeHeaders } from "../utils";
+
+const FETCH_TIMEOUT_MS = 5_000;
+
+export const handleRewrite: Handler<RewriteConfig> = async (request, config) => {
+  const originalUrl = new URL(request.url);
+  const { url: targetUrl, allowedMethods } = config;
+
+  if (!(allowedMethods as string[]).includes(request.method)) {
+    return new Response("Method not allowed", {
+      status: 405,
+      headers: {
+        Allow: allowedMethods.join(", "),
+      },
+    });
+  }
+
+  // Construct the target URL with the original path and query
+  const url = new URL(targetUrl);
+  url.pathname = originalUrl.pathname;
+  url.search = originalUrl.search;
+
+  // Filter headers to only include safe ones (prevents header injection)
+  const safeHeaders = filterSafeHeaders(request.headers);
+
+  // Create a new request with the target URL and filtered headers
+  const modifiedRequest = new Request(url.toString(), {
+    method: request.method,
+    headers: safeHeaders,
+    body: request.method !== "GET" && request.method !== "HEAD" ? request.body : undefined,
+  });
+
+  // Create abort controller for timeout
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    const response = await fetch(modifiedRequest, {
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    // Create a new response with the same body but potentially modified headers
+    const newResponse = new Response(response.body, response);
+
+    // Remove content-encoding header because the response body is already decoded
+    // by the fetch API, and if we forward this header, the browser will try to
+    // decode it again, causing corruption
+    newResponse.headers.delete("content-encoding");
+
+    return newResponse;
+  } catch (error) {
+    clearTimeout(timeoutId);
+
+    if (error instanceof Error && error.name === "AbortError") {
+      return new Response("Request timeout", { status: 504 });
+    }
+
+    return new Response("Bad gateway", { status: 502 });
+  }
+};

package/src/handlers/static.ts

@@ -0,0 +1,119 @@
+import type { Handler, FileLoader, FileObject } from "../types";
+import type { StaticConfig } from "../schemas";
+import { getContentType, sanitizePath } from "../utils";
+
+export const handleStatic: Handler<StaticConfig, { fileLoader: FileLoader }> = async (
+  request,
+  config,
+  { fileLoader }
+) => {
+  const url = new URL(request.url);
+  const { path: basePath, spa, fallback } = config;
+
+  return spa
+    ? handleSpaMode(fileLoader, basePath)
+    : handleStaticMode(fileLoader, basePath, url.pathname, fallback);
+};
+
+async function handleSpaMode(fileLoader: FileLoader, basePath: string): Promise<Response> {
+  // Sanitize base path to prevent directory traversal
+  const sanitizedBase = sanitizePath(basePath);
+  if (!sanitizedBase) {
+    return new Response("Invalid path", { status: 400 });
+  }
+
+  const key = sanitizedBase.endsWith("index.html")
+    ? sanitizedBase
+    : sanitizedBase.endsWith("/")
+      ? `${sanitizedBase}index.html`
+      : `${sanitizedBase}/index.html`;
+
+  const fileObject = await fileLoader.loadFile(key);
+
+  if (!fileObject) {
+    return new Response("File not found", { status: 404 });
+  }
+
+  return buildFileResponse(fileObject, key);
+}
+
+async function handleStaticMode(
+  fileLoader: FileLoader,
+  basePath: string,
+  pathname: string,
+  fallback?: string
+): Promise<Response> {
+  // Sanitize paths to prevent directory traversal
+  const sanitizedBase = sanitizePath(basePath);
+  const sanitizedPathname = sanitizePath(pathname);
+
+  if (!sanitizedBase || !sanitizedPathname) {
+    return new Response("Invalid path", { status: 400 });
+  }
+
+  // Standard mode: serve the requested file
+  const fullPath = pathname === "/" ? sanitizedBase : `${sanitizedBase}/${sanitizedPathname}`;
+  let key = fullPath.replace(/\/+/g, "/"); // Normalize double slashes
+
+  // Append index.html for directories or extensionless paths
+  if (key.endsWith("/") || !key.includes(".")) {
+    key = key.endsWith("/") ? `${key}index.html` : `${key}/index.html`;
+  }
+
+  const fileObject = await fileLoader.loadFile(key);
+
+  if (fileObject) {
+    return buildFileResponse(fileObject, key);
+  }
+
+  // Try fallback if configured
+  if (fallback) {
+    const sanitizedFallback = sanitizePath(fallback);
+    if (!sanitizedFallback) {
+      return new Response("File not found", { status: 404 });
+    }
+
+    const fallbackKey = `${sanitizedBase}/${sanitizedFallback}`;
+    const fallbackObject = await fileLoader.loadFile(fallbackKey);
+
+    if (fallbackObject) {
+      return buildFileResponse(fallbackObject, fallbackKey);
+    }
+  }
+
+  return new Response("File not found", { status: 404 });
+}
+
+function buildFileResponse(fileObject: FileObject, key: string): Response {
+  const headers = new Headers(fileObject.headers);
+
+  if (fileObject.etag) {
+    headers.set("etag", fileObject.etag);
+  }
+
+  if (!headers.has("Content-Type")) {
+    const contentType = getContentType(key);
+    if (contentType) {
+      headers.set("Content-Type", contentType);
+    }
+  }
+
+  // Security headers
+  headers.set("X-Content-Type-Options", "nosniff");
+  headers.set("X-Frame-Options", "SAMEORIGIN");
+  headers.set("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+
+  // Content Security Policy - restrictive default, can be overridden by metadata
+  if (!headers.has("Content-Security-Policy")) {
+    headers.set(
+      "Content-Security-Policy",
+      "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';"
+    );
+  }
+
+  // Cache control with Vary header for cache poisoning prevention
+  headers.set("Cache-Control", "public, max-age=3600");
+  headers.set("Vary", "Accept-Encoding");
+
+  return new Response(fileObject.body, { headers });
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// Re-export everything from submodules
+export * from "./schemas";
+export * from "./types";
+export * from "./handlers";
+export * from "./utils";

package/src/schemas.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+/**
+ * Validates that a URL is safe (http/https only, no private IPs)
+ *
+ * This is a simplified version that checks basic URL structure.
+ * For full SSRF protection, use the complete isSafeURL implementation
+ * from the wildcard service.
+ */
+function isBasicSafeURL(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/** Validates that a URL is safe (http/https only, no private IPs) */
+const safeUrl = () =>
+  z.string().url().refine(isBasicSafeURL, {
+    message: "URL must use http/https and cannot target private/internal addresses",
+  });
+
+// Zod schemas for validation
+export const StaticConfigSchema = z
+  .object({
+    type: z.literal("static"),
+    path: z.string().min(1),
+    spa: z.boolean().optional(),
+    fallback: z.string().optional(), // Fallback file path for non-SPA mode (e.g., "404.html")
+  })
+  .refine((data) => (data.spa && data.fallback ? false : true), {
+    message: "fallback cannot be used with spa mode (spa: true)",
+  });
+
+export const RedirectConfigSchema = z.object({
+  type: z.literal("redirect"),
+  url: safeUrl(),
+  permanent: z.boolean().optional(),
+});
+
+const HttpMethod = z.enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]);
+
+export const RewriteConfigSchema = z.object({
+  type: z.literal("rewrite"),
+  url: safeUrl(),
+  allowedMethods: z.array(HttpMethod).optional().default(["GET", "HEAD", "OPTIONS"]),
+});
+
+export const RouteConfigSchema = z.discriminatedUnion("type", [
+  StaticConfigSchema,
+  RedirectConfigSchema,
+  RewriteConfigSchema,
+]);
+
+/** @deprecated Use StaticConfigSchema instead */
+export const R2ConfigSchema = StaticConfigSchema;
+
+/**
+ * JSON codec for parsing and validating JSON strings
+ */
+const json = <T extends z.ZodType>(schema: T) =>
+  z.codec(z.string(), schema, {
+    decode: (jsonString, ctx) => {
+      try {
+        return JSON.parse(jsonString);
+      } catch (err: any) {
+        ctx.issues.push({
+          code: "invalid_format",
+          format: "json",
+          input: jsonString,
+          message: err.message,
+        });
+        return z.NEVER;
+      }
+    },
+    encode: (value) => JSON.stringify(value),
+  });
+
+/**
+ * Codec for decoding JSON strings into validated RouteConfig objects
+ */
+export const RouteConfigCodec = json(RouteConfigSchema);
+
+export type StaticConfig = z.infer<typeof StaticConfigSchema>;
+export type RedirectConfig = z.infer<typeof RedirectConfigSchema>;
+export type RewriteConfig = z.infer<typeof RewriteConfigSchema>;
+export type SubdomainConfig = z.infer<typeof RouteConfigSchema>;

package/src/types.ts

@@ -0,0 +1,51 @@
+import type { StaticConfig, RedirectConfig, RewriteConfig } from "./schemas";
+
+/**
+ * Represents a file object from any storage backend
+ */
+export interface FileObject {
+  /** File body as a ReadableStream or ArrayBuffer */
+  body: ReadableStream<Uint8Array> | ArrayBuffer | null;
+  /** HTTP headers associated with the file */
+  headers?: Headers;
+  /** ETag for cache validation */
+  etag?: string;
+  /** Size of the file in bytes */
+  size?: number;
+}
+
+/**
+ * Interface for loading files from a storage backend
+ */
+export interface FileLoader {
+  /**
+   * Load a file from storage by its path
+   * @param path - The path to the file
+   * @returns The file object, or null if not found
+   */
+  loadFile(path: string): Promise<FileObject | null>;
+}
+
+/**
+ * Interface for loading route configurations
+ */
+export interface RouteConfigLoader {
+  /**
+   * Load route configuration for a subdomain
+   * @param subdomain - The subdomain name
+   * @returns The configuration as a JSON string, or null if not found
+   */
+  loadRouteConfig(subdomain: string): Promise<string | null>;
+}
+
+/**
+ * Handler function type with dependency injection
+ * @template T - The config type (StaticConfig, RedirectConfig, or RewriteConfig)
+ * @template D - Optional dependency object (e.g., { fileLoader: FileLoader })
+ */
+export type Handler<
+  T extends StaticConfig | RedirectConfig | RewriteConfig,
+  D extends Record<string, unknown> = never,
+> = [D] extends [never]
+  ? (request: Request, config: T) => Promise<Response>
+  : (request: Request, config: T, dependency: D) => Promise<Response>;

package/src/utils.ts

@@ -0,0 +1,198 @@
+/**
+ * Content type detection and security utilities
+ */
+
+export function getContentType(path: string): string | null {
+  const ext = path.split(".").pop()?.toLowerCase();
+  const types: Record<string, string> = {
+    html: "text/html",
+    htm: "text/html",
+    css: "text/css",
+    js: "application/javascript",
+    json: "application/json",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    svg: "image/svg+xml",
+    webp: "image/webp",
+    ico: "image/x-icon",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    ttf: "font/ttf",
+    xml: "application/xml",
+    txt: "text/plain",
+  };
+  return types[ext || ""] || null;
+}
+
+/**
+ * Security utilities for validating URLs and preventing SSRF attacks
+ */
+
+/**
+ * Checks if an IP address is in a private range
+ */
+function isPrivateIP(ip: string): boolean {
+  // IPv4 private ranges
+  const privateRanges = [
+    /^10\./, // 10.0.0.0/8
+    /^172\.(1[6-9]|2\d|3[01])\./, // 172.16.0.0/12
+    /^192\.168\./, // 192.168.0.0/16
+    /^127\./, // 127.0.0.0/8 (localhost)
+    /^169\.254\./, // 169.254.0.0/16 (link-local, includes cloud metadata)
+    /^0\./, // 0.0.0.0/8
+    /^::1$/, // IPv6 localhost
+    /^fe80:/i, // IPv6 link-local
+    /^fc00:/i, // IPv6 unique local
+    /^fd00:/i, // IPv6 unique local
+  ];
+
+  return privateRanges.some((range) => range.test(ip));
+}
+
+/**
+ * Checks if a hostname resolves to localhost or private IPs
+ */
+function isSuspiciousHostname(hostname: string): boolean {
+  const lowerHostname = hostname.toLowerCase();
+
+  // Block localhost variants
+  if (lowerHostname === "localhost" || lowerHostname === "localhost.localdomain") {
+    return true;
+  }
+
+  // Block if hostname is an IP address and it's private
+  // IPv4 check
+  if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
+    return isPrivateIP(hostname);
+  }
+
+  // IPv6 check - URL parser keeps square brackets in hostname
+  // Remove brackets for validation
+  if (hostname.startsWith("[") && hostname.endsWith("]")) {
+    const ipv6 = hostname.slice(1, -1);
+    return isPrivateIP(ipv6);
+  }
+
+  return false;
+}
+
+/**
+ * Validates a URL to prevent SSRF attacks
+ * @param url - The URL to validate
+ * @returns true if URL is safe, false otherwise
+ */
+export function isSafeURL(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+
+    // Only allow http and https protocols
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return false;
+    }
+
+    if (isSuspiciousHostname(parsed.hostname)) {
+      return false;
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sanitizes a file path to prevent directory traversal attacks
+ * @param path - The path to sanitize
+ * @returns Sanitized path or null if path is invalid
+ */
+export function sanitizePath(path: string): string | null {
+  // Remove leading slashes
+  let normalized = path.replace(/^\/+/, "");
+
+  // Split into segments
+  const segments = normalized.split("/");
+
+  // Check each segment
+  for (const segment of segments) {
+    // Reject if segment is .. or . or empty (double slashes)
+    if (segment === ".." || segment === "." || segment === "") {
+      return null;
+    }
+
+    // Reject if segment contains null bytes or other suspicious characters
+    if (segment.includes("\0") || segment.includes("\x00")) {
+      return null;
+    }
+  }
+
+  // Rebuild the path from clean segments
+  return segments.join("/");
+}
+
+/**
+ * List of safe headers that can be forwarded in proxy requests
+ */
+export const SAFE_REQUEST_HEADERS = [
+  "accept",
+  "accept-language",
+  "accept-encoding",
+  "cache-control",
+  "content-type",
+  "user-agent",
+  "referer",
+  "origin",
+] as const;
+
+/**
+ * Filters request headers to only include safe headers
+ *
+ * @param headers - Original headers
+ */
+export function filterSafeHeaders(headers: Headers): Headers {
+  const filtered = new Headers();
+
+  for (const header of SAFE_REQUEST_HEADERS) {
+    const value = headers.get(header);
+    if (value) {
+      filtered.set(header, value);
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Validates subdomain name format and length
+ * @param subdomain - The subdomain to validate
+ * @returns true if subdomain is valid
+ */
+export function isValidSubdomain(subdomain: string): boolean {
+  // DNS label max length is 63 characters
+  if (subdomain.length === 0 || subdomain.length > 63) {
+    return false;
+  }
+
+  // Must start and end with alphanumeric
+  if (!/^[a-z0-9].*[a-z0-9]$/i.test(subdomain) && subdomain.length > 1) {
+    return false;
+  }
+
+  // Single character must be alphanumeric
+  if (subdomain.length === 1 && !/^[a-z0-9]$/i.test(subdomain)) {
+    return false;
+  }
+
+  // Can only contain alphanumeric and hyphens
+  if (!/^[a-z0-9-]+$/i.test(subdomain)) {
+    return false;
+  }
+
+  // Cannot have consecutive hyphens
+  if (subdomain.includes("--")) {
+    return false;
+  }
+
+  return true;
+}