@jaypie/mcp 0.7.2 → 0.7.4

package/dist/suites/docs/index.js

@@ -9,7 +9,7 @@ import { gt } from 'semver';
 /**
  * Docs Suite - Documentation services (skill, version, release_notes)
  */
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.7.2#5d947297"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.7.4#9b2629b2"
     ;
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/constructs/1.2.26.md

@@ -0,0 +1,11 @@
+---
+version: 1.2.26
+date: 2025-01-30
+summary: Auto-set PROJECT_BASE_URL on Lambda handlers
+---
+
+## Changes
+
+- JaypieDistribution now automatically sets `PROJECT_BASE_URL` environment variable on Lambda handlers when host is resolved
+- JaypieApiGateway now automatically sets `PROJECT_BASE_URL` environment variable on Lambda handlers when host is resolved
+- This enables automatic CORS configuration when using the cors helper from `@jaypie/express`

package/release-notes/express/1.2.6.md

@@ -0,0 +1,17 @@
+---
+version: 1.2.6
+date: 2025-01-30
+summary: Improve CORS origin matching security with subdomain support
+---
+
+## Changes
+
+- Fixed CORS security issue: origin matching now uses proper hostname extraction instead of `.includes()`
+- Added subdomain matching: when `example.com` is allowed, subdomains like `app.example.com` are automatically allowed
+- Added `extractHostname()` and `isOriginAllowed()` helpers for secure origin validation
+- Origins in config can now be specified without protocol prefix (defaults to `https://`)
+
+## Security
+
+- Previously, allowing `example.com` would incorrectly allow `notexample.com` or `fakeexample.com` due to `.includes()` matching
+- Now uses proper hostname extraction and suffix matching with dot separator to prevent this issue

package/release-notes/express/1.2.7.md

@@ -0,0 +1,48 @@
+---
+version: 1.2.7
+date: 2025-01-30
+summary: Fix CORS OPTIONS preflight hanging with Lambda streaming
+---
+
+## Bug Fix
+
+Fixed an issue where CORS OPTIONS preflight requests would hang indefinitely when using `createLambdaStreamHandler` with the `cors` middleware.
+
+### Problem
+
+When using Lambda response streaming, browser CORS preflight (OPTIONS) requests would hang because:
+- The standard cors package's call to `res.end()` could get delayed by streaming's async behavior
+- The Lambda response stream would stay open waiting for streaming data that never comes
+- Browsers would timeout waiting for the preflight response
+
+### Solution
+
+The `cors` middleware now detects OPTIONS requests early and handles them synchronously:
+- Sets all required CORS headers directly (Access-Control-Allow-Origin, Access-Control-Allow-Methods, etc.)
+- Terminates the response immediately with a 204 No Content status
+- Ensures the response stream doesn't enter streaming mode for preflight requests
+
+### Usage
+
+No changes required. The fix is automatic when using `cors` with `createLambdaStreamHandler`:
+
+```typescript
+import express from "express";
+import { cors, createLambdaStreamHandler } from "@jaypie/express";
+
+const app = express();
+app.use(cors({ origin: "https://example.com" }));
+
+// Streaming endpoint works correctly with CORS
+app.post("/stream", (req, res) => {
+  res.setHeader("Content-Type", "text/event-stream");
+  res.write("data: hello\n\n");
+  res.end();
+});
+
+export const handler = createLambdaStreamHandler(app);
+```
+
+### Related
+
+- GitHub Issue: [#174](https://github.com/finlaysonstudio/jaypie/issues/174)

package/release-notes/mcp/0.7.3.md

@@ -0,0 +1,14 @@
+---
+version: 0.7.3
+date: 2025-01-30
+summary: Add CORS skill documentation comparing Jaypie cors helper with standard Express cors
+---
+
+## Changes
+
+- Add `skill("cors")` documentation covering:
+  - Jaypie `cors` helper from `@jaypie/express`
+  - Comparison with standard `express/cors` middleware
+  - Environment variable integration (`BASE_URL`, `PROJECT_BASE_URL`)
+  - Sandbox mode automatic localhost handling
+  - Configuration options and usage patterns

package/skills/cors.md

@@ -0,0 +1,354 @@
+---
+description: CORS configuration for Express.js using Jaypie's cors helper
+related: express, handlers, lambda
+---
+
+# CORS Configuration
+
+Jaypie's `@jaypie/express` package provides a `cors` helper that wraps the standard [express/cors](https://github.com/expressjs/cors) middleware with Jaypie-specific defaults and environment awareness.
+
+## Quick Start
+
+```typescript
+import express from "express";
+import { cors } from "jaypie";
+
+const app = express();
+
+// Basic usage - environment-aware defaults
+app.use(cors());
+
+// With specific origin
+app.use(cors({ origin: "https://example.com" }));
+
+// Multiple origins
+app.use(cors({ origin: ["https://a.com", "https://b.com"] }));
+
+// Allow all origins
+app.use(cors({ origin: "*" }));
+```
+
+## Default Behavior: `cors()`
+
+When called with no arguments, `cors()` allows origins based on environment variables only:
+
+| Condition | Allowed |
+|-----------|---------|
+| No `Origin` header (curl, mobile, server-to-server) | ✅ Always |
+| Origin matches `BASE_URL` env var | ✅ Yes |
+| Origin matches `PROJECT_BASE_URL` env var | ✅ Yes |
+| Origin is subdomain of allowed origin | ✅ Yes |
+| `PROJECT_ENV=sandbox` and origin is `localhost[:port]` | ✅ Yes |
+| Any other cross-origin request | ❌ Rejected |
+
+### Subdomain Matching
+
+When you allow a domain, all subdomains of that domain are also automatically allowed:
+
+```typescript
+// Allow example.com and all its subdomains
+app.use(cors({ origin: "example.com" }));
+// Allows: https://example.com, https://app.example.com, https://sub.app.example.com
+// Rejects: https://notexample.com, https://fakeexample.com
+
+// Protocol prefix is optional in config
+app.use(cors({ origin: "example.com" }));  // Same as https://example.com
+```
+
+This is secure because it uses proper hostname extraction and suffix matching with a dot separator—domains like `notexample.com` or `fakeexample.com` are correctly rejected.
+
+**Important:** With no environment variables set and not in sandbox mode, `cors()` rejects all cross-origin browser requests. This is secure by default—you must explicitly configure allowed origins.
+
+```typescript
+// Example: Production environment
+// BASE_URL=https://api.example.com
+// PROJECT_BASE_URL=https://example.com
+
+app.use(cors());
+// Allows: https://api.example.com, https://example.com
+// Rejects: all other origins
+
+// Example: Sandbox/development
+// PROJECT_ENV=sandbox
+
+app.use(cors());
+// Allows: http://localhost, http://localhost:3000, http://localhost:5173, etc.
+// Rejects: all other origins (unless BASE_URL/PROJECT_BASE_URL set)
+```
+
+## Jaypie vs Standard Express CORS
+
+### Key Differences
+
+| Feature | Standard `cors` | Jaypie `cors` |
+|---------|-----------------|---------------|
+| **Origin Validation** | Static or manual callback | Dynamic environment-aware callback |
+| **Subdomain Matching** | Manual implementation | Automatic (subdomains of allowed origins permitted) |
+| **Environment URLs** | Not supported | Reads `BASE_URL`, `PROJECT_BASE_URL` |
+| **Sandbox Mode** | Manual localhost config | Auto-allows localhost in sandbox |
+| **Error Response** | Generic CORS error | Returns `CorsError` with JSON body |
+| **No-Origin Requests** | Configurable | Always allowed (mobile apps, curl) |
+| **Protocol Prefix** | Required in config | Optional (defaults to `https://`) |
+
+### Jaypie-Specific Behavior
+
+1. **Environment Variable Integration**
+   - `BASE_URL` - Automatically added to allowed origins
+   - `PROJECT_BASE_URL` - Automatically added to allowed origins
+   - Protocol auto-added if missing (defaults to `https://`)
+
+2. **Sandbox Mode** (when `PROJECT_ENV=sandbox` or `PROJECT_SANDBOX_MODE=true`)
+   - `http://localhost` is automatically allowed
+   - `http://localhost:*` (any port) is automatically allowed
+
+3. **No-Origin Requests**
+   - Requests without an `Origin` header are always allowed
+   - Enables mobile apps, server-to-server calls, and curl testing
+
+4. **Error Handling**
+   - Invalid origins return a `CorsError` from `@jaypie/errors`
+   - Response includes JSON body with error details
+
+## Configuration Options
+
+### Jaypie `cors` Options
+
+```typescript
+interface CorsConfig {
+  origin?: string | string[];  // Additional allowed origins
+  overrides?: Record<string, unknown>;  // Pass-through to express/cors
+}
+```
+
+### Standard `cors` Options (via `overrides`)
+
+All standard `cors` options can be passed through the `overrides` parameter:
+
+```typescript
+import { cors } from "jaypie";
+
+app.use(cors({
+  origin: "https://example.com",
+  overrides: {
+    methods: ["GET", "POST", "PUT"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+    exposedHeaders: ["X-Request-Id"],
+    credentials: true,
+    maxAge: 86400,
+    optionsSuccessStatus: 200,
+    preflightContinue: false,
+  },
+}));
+```
+
+### Full Standard Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `methods` | `string \| string[]` | All methods | Allowed HTTP methods |
+| `allowedHeaders` | `string \| string[]` | Reflect request | Allowed request headers |
+| `exposedHeaders` | `string \| string[]` | None | Headers exposed to browser |
+| `credentials` | `boolean` | `false` | Allow credentials (cookies) |
+| `maxAge` | `number` | None | Preflight cache duration (seconds) |
+| `preflightContinue` | `boolean` | `false` | Pass OPTIONS to next handler |
+| `optionsSuccessStatus` | `number` | `204` | Status for successful OPTIONS |
+
+## Usage Patterns
+
+### API with Multiple Allowed Origins
+
+```typescript
+import { cors } from "jaypie";
+
+// Production + staging + local origins
+app.use(cors({
+  origin: [
+    "https://app.example.com",
+    "https://staging.example.com",
+  ],
+}));
+```
+
+### API with Credentials
+
+```typescript
+import { cors } from "jaypie";
+
+// Enable cookies for cross-origin requests
+app.use(cors({
+  origin: "https://app.example.com",
+  overrides: {
+    credentials: true,
+  },
+}));
+```
+
+### Public API (Allow All Origins)
+
+```typescript
+import { cors } from "jaypie";
+
+// Allow any origin
+app.use(cors({ origin: "*" }));
+```
+
+### Per-Route CORS
+
+```typescript
+import express from "express";
+import { cors } from "jaypie";
+
+const app = express();
+
+// Public endpoints - wide open
+app.use("/api/public", cors({ origin: "*" }));
+
+// Protected endpoints - restricted origins
+app.use("/api/admin", cors({
+  origin: "https://admin.example.com",
+  overrides: { credentials: true },
+}));
+```
+
+## How Origin Validation Works
+
+Jaypie's `cors` uses a dynamic origin callback that checks origins in this order:
+
+1. **Wildcard** - If `origin: "*"`, allow all origins
+2. **No Origin** - Allow requests without Origin header (mobile, curl, etc.)
+3. **Environment URLs** - Check `BASE_URL` and `PROJECT_BASE_URL`
+4. **Configured Origins** - Check origins passed to `cors({ origin: [...] })`
+5. **Sandbox Localhost** - In sandbox mode, allow localhost with any port
+
+For each allowed origin, the validation checks:
+- **Exact hostname match** - `example.com` matches `https://example.com`
+- **Subdomain match** - `example.com` matches `https://app.example.com`
+
+```typescript
+// Simplified origin validation logic
+const isAllowed =
+  origin === "*" ||
+  !requestOrigin ||
+  isOriginAllowed(requestOrigin, process.env.BASE_URL) ||
+  isOriginAllowed(requestOrigin, process.env.PROJECT_BASE_URL) ||
+  configuredOrigins.some(o => isOriginAllowed(requestOrigin, o)) ||
+  (isSandbox && requestOrigin.match(/^http:\/\/localhost(:\d+)?$/));
+
+// Where isOriginAllowed checks for exact match OR subdomain match
+// e.g., "app.example.com".endsWith(".example.com") → true
+```
+
+## Error Responses
+
+When an origin is not allowed, Jaypie returns a structured error response:
+
+```json
+{
+  "errors": [{
+    "title": "CorsError",
+    "status": 403,
+    "detail": "Cross-Origin Request Blocked"
+  }]
+}
+```
+
+## Comparison: Standard vs Jaypie CORS Setup
+
+### Standard Express CORS
+
+```typescript
+import express from "express";
+import cors from "cors";
+
+const app = express();
+
+// Manual origin validation
+app.use(cors({
+  origin: (origin, callback) => {
+    const allowedOrigins = [
+      process.env.BASE_URL,
+      process.env.PROJECT_BASE_URL,
+      "https://app.example.com",
+    ];
+
+    // Allow no-origin requests
+    if (!origin) {
+      return callback(null, true);
+    }
+
+    // Check allowed list
+    if (allowedOrigins.some(o => origin.includes(o))) {
+      return callback(null, true);
+    }
+
+    // Sandbox localhost
+    if (process.env.PROJECT_ENV === "sandbox" &&
+        origin.match(/^http:\/\/localhost(:\d+)?$/)) {
+      return callback(null, true);
+    }
+
+    callback(new Error("Not allowed by CORS"));
+  },
+  credentials: true,
+}));
+```
+
+### Jaypie CORS (Equivalent)
+
+```typescript
+import express from "express";
+import { cors } from "jaypie";
+
+const app = express();
+
+// Same behavior, less code
+app.use(cors({
+  origin: "https://app.example.com",
+  overrides: { credentials: true },
+}));
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `BASE_URL` | Automatically added to allowed origins |
+| `PROJECT_BASE_URL` | Automatically added to allowed origins |
+| `PROJECT_ENV` | Set to `sandbox` to enable localhost access |
+| `PROJECT_SANDBOX_MODE` | Set to `true` to enable localhost access |
+
+## Lambda Streaming Compatibility
+
+Jaypie's `cors` middleware is designed to work seamlessly with Lambda response streaming (`createLambdaStreamHandler`). Unlike the standard `cors` package, Jaypie's implementation handles OPTIONS preflight requests early and terminates them immediately, preventing the response stream from hanging.
+
+This is critical because:
+- Browser CORS preflight requests (OPTIONS) must complete quickly with a 204 response
+- Lambda streaming keeps the response stream open for streaming data
+- Without early termination, OPTIONS requests would hang waiting for streaming data that never comes
+
+No special configuration is needed—Jaypie's `cors` automatically detects OPTIONS requests and handles them appropriately.
+
+```typescript
+import express from "express";
+import { cors, createLambdaStreamHandler } from "@jaypie/express";
+
+const app = express();
+
+// CORS works automatically with streaming
+app.use(cors({ origin: "https://example.com" }));
+
+app.post("/stream", (req, res) => {
+  res.setHeader("Content-Type", "text/event-stream");
+  res.write("data: hello\n\n");
+  res.end();
+});
+
+// Deploy with Lambda streaming - CORS preflight works correctly
+export const handler = createLambdaStreamHandler(app);
+```
+
+## See Also
+
+- **`skill("express")`** - Express handler and Lambda adapter documentation
+- **`skill("handlers")`** - Jaypie handler lifecycle documentation
+- **`skill("lambda")`** - AWS Lambda deployment patterns

package/skills/express.md

@@ -1,6 +1,6 @@
 ---
 description: Express.js handler for AWS Lambda with API Gateway support
-related: aws, cdk, handlers, lambda, services, streaming
+related: aws, cdk, cors, handlers, lambda, services, streaming
 ---
 
 # Express Integration