@jaypie/mcp 0.7.1 → 0.7.3

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.1#82d19d8a"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.7.3#f9c2b3fe"
     ;
 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.1",
+  "version": "0.7.3",
   "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/mcp/0.7.2.md

@@ -0,0 +1,18 @@
+---
+version: 0.7.2
+date: 2026-01-30
+summary: Document JaypieNextJs streaming configuration requirements
+---
+
+## Documentation
+
+- Added JaypieNextJs streaming documentation to `streaming.md` skill
+- Added JaypieNextJs construct to `cdk.md` skill
+- Clarified that `streaming: true` requires `open-next.config.ts` with `aws-lambda-streaming` wrapper
+
+## Context
+
+Issue #171 reported that `JaypieNextJs` with `streaming: true` returns a JSON envelope instead of streamed HTML. This is expected behavior - Lambda response streaming requires both:
+
+1. CDK: `streaming: true` (configures `InvokeMode: RESPONSE_STREAM`)
+2. Next.js: `open-next.config.ts` with `wrapper: "aws-lambda-streaming"`

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/cdk.md

@@ -139,7 +139,24 @@ const handler = new JaypieLambda(this, "Handler", {
 });
 ```
 
+## JaypieNextJs
+
+Deploy Next.js applications:
+
+```typescript
+import { JaypieNextJs } from "@jaypie/constructs";
+
+new JaypieNextJs(this, "App", {
+  nextjsPath: "../nextjs",
+  domainName: "app.example.com",
+  hostedZone: "example.com",
+  streaming: true,  // Optional: enables response streaming
+});
+```
+
+**Streaming Note:** When `streaming: true`, also create `open-next.config.ts` in your Next.js app with `wrapper: "aws-lambda-streaming"`. See `skill("streaming")` for details.
+
 ## See Also
 
-- **`skill("streaming")`** - JaypieDistribution with `streaming: true` for response streaming
+- **`skill("streaming")`** - JaypieDistribution and JaypieNextJs streaming configuration
 - **`skill("websockets")`** - JaypieWebSocket and JaypieWebSocketTable constructs

package/skills/cors.md

@@ -0,0 +1,324 @@
+---
+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 |
+
+## 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

package/skills/streaming.md

@@ -76,6 +76,8 @@ export const handler = lambdaStreamHandler(async (event, context) => {
 
 ## CDK Configuration
 
+### JaypieDistribution
+
 ```typescript
 import { JaypieLambda, JaypieDistribution } from "@jaypie/constructs";
 
@@ -90,6 +92,40 @@ new JaypieDistribution(this, "Api", {
 });
 ```
 
+### JaypieNextJs Streaming
+
+For Next.js applications with `JaypieNextJs`, streaming requires **two** configurations:
+
+1. **CDK** - Set `streaming: true` in the construct
+2. **Next.js App** - Create `open-next.config.ts` with the streaming wrapper
+
+```typescript
+// CDK Stack
+import { JaypieNextJs } from "@jaypie/constructs";
+
+new JaypieNextJs(this, "App", {
+  nextjsPath: "../nextjs",
+  streaming: true,
+});
+```
+
+```typescript
+// nextjs/open-next.config.ts (required for streaming)
+import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js";
+
+const config = {
+  default: {
+    override: {
+      wrapper: "aws-lambda-streaming",
+    },
+  },
+} satisfies OpenNextConfig;
+
+export default config;
+```
+
+**Important:** Without `open-next.config.ts`, the Lambda returns a JSON envelope `{ statusCode, headers, body }` instead of streaming HTML. This is because `cdk-nextjs-standalone` configures the Lambda Function URL with `RESPONSE_STREAM` invoke mode, but OpenNext also needs to be configured to use the streaming wrapper.
+
 ## Error Handling
 
 Errors are written to the stream in the configured format: