zuplo 6.67.32 → 6.68.0

package/docs/programmable-api/jwt-service-plugin.mdx

@@ -0,0 +1,420 @@
+---
+title: JWT Service Plugin
+---
+
+<EnterpriseFeature name="JWT Service Plugin" />
+
+The JWT Service Plugin allows you to create and issue short-lived JSON Web
+Tokens (JWTs) within your Zuplo API. This plugin is useful for scenarios where
+you need to issue tokens for authentication, authorization, or other purposes.
+
+The plugin essentially turns your Zuplo API into its own identity provider that
+can issue JWTs. Your Zuplo API will also serve the standard
+`/.well-known/openid-configuration` endpoint and associated JWKS endpoint which
+can be used by clients to discover the public keys used to verify the JWTs
+issued by your API.
+
+:::note{title="Beta Feature"}
+
+This plugin is in Beta - please use with care and provide feedback to the team
+if you encounter any issues.
+
+:::
+
+## JWT Token
+
+This service currently issues JWTs using the EdDSA algorithm. This is the
+recommended algorithm for new applications due to its strong security properties
+and performance characteristics. However, it's important to note that not every
+library supports EdDSA, so you should ensure that your
+[client library](https://jwt.io/libraries) can handle this algorithm.
+
+## Use Cases
+
+Some of the common use cases for the JWT service plugin include:
+
+- Securing downstream APIs by issuing JWTs that can be used to verify that the
+  request is coming from your Zuplo API
+- Securing requests to other Zuplo API gateways (for example, when using the
+  [Federated Gateway](../dedicated/federated-gateways.mdx) capability on Zuplo
+  managed dedicated deployments.)
+- Calling third-party APIs that can be configured with federated identity such
+  as AWS, Azure, or Google Cloud.
+- Issuing short lived tokens for client side applications
+
+## Setup
+
+To set up the JWT Service Plugin, you need to register it in your
+`zuplo.runtime.ts` file.
+
+```ts title="modules/zuplo.runtime.ts"
+import { RuntimeExtensions, JwtServicePlugin } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  // Default configuration (no options)
+  const jwtService = new JwtServicePlugin();
+  runtime.addPlugin(jwtService);
+}
+```
+
+### Configuration Options
+
+The JWT Service Plugin accepts optional configuration to customize its behavior.
+You can pass a configuration object to the constructor:
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  RuntimeExtensions,
+  JwtServicePlugin,
+  JwtServicePluginOptions,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  // Example 1: Custom configuration with both options
+  const options: JwtServicePluginOptions = {
+    // Custom base path for the issuer endpoint (default: "/__zuplo/issuer")
+    basePath: "/custom",
+
+    // Token expiration time (default: 300 seconds)
+    // Can be a number (seconds) or a time span string
+    tokenExpiration: "5m", // or 300 for seconds
+  };
+
+  const jwtService = new JwtServicePlugin(options);
+  runtime.addPlugin(jwtService);
+}
+```
+
+#### Available Options
+
+- **`basePath`** (optional): The base path for the JWT issuer endpoint. Default
+  is `"/__zuplo/issuer"`. This affects the issuer URL and OIDC configuration
+  endpoints.
+
+- **`tokenExpiration`** (optional): Sets the default expiration time for JWTs.
+  Can be either:
+  - A **number**: Direct value in seconds (for example, `300` for 5 minutes)
+  - A **string**: Time span format (for example, `"5 minutes"`, `"1 hour"`,
+    `"7 days"`)
+
+  Valid time units include:
+  - Seconds: `"sec"`, `"secs"`, `"second"`, `"seconds"`, `"s"`
+  - Minutes: `"minute"`, `"minutes"`, `"min"`, `"mins"`, `"m"`
+  - Hours: `"hour"`, `"hours"`, `"hr"`, `"hrs"`, `"h"`
+  - Days: `"day"`, `"days"`, `"d"`
+  - Weeks: `"week"`, `"weeks"`, `"w"`
+  - Years: `"year"`, `"years"`, `"yr"`, `"yrs"`, `"y"` (365.25 days)
+
+  Examples:
+
+  ```ts
+  tokenExpiration: 300; // 300 seconds
+  tokenExpiration: "5 minutes"; // 5 minutes
+  tokenExpiration: "2 hours"; // 2 hours
+  tokenExpiration: "7 days"; // 7 days
+  tokenExpiration: "30 mins"; // 30 minutes
+  ```
+
+  Note: Individual JWT creation can override this default by specifying
+  `expiresIn` in the `signJwt` method.
+
+## Usage
+
+Once the plugin is registered, you can use it to issue JWTs in custom handlers
+or policies.
+
+```ts title="modules/handlers/jwt-issue.ts"
+import { ZuploRequest, ZuploContext, JwtServicePlugin } from "@zuplo/runtime";
+
+export async function getJwt(request: ZuploRequest, context: ZuploContext) {
+  const jwt = await JwtServicePlugin.signJwt({
+    subject: "test-subject",
+  });
+  return new Response(jwt, {
+    headers: { "content-type": "text/plain" },
+  });
+}
+```
+
+### JWT Issuer and OIDC Configuration
+
+When the JWT Service Plugin is enabled, your Zuplo API acts as an identity
+provider with the following endpoints:
+
+- **Issuer URL**: `https://{deploymentName}.zuplo.com/__zuplo/issuer` (or your
+  custom domain if configured)
+- **OIDC Configuration**:
+  `https://{deploymentName}.zuplo.com/__zuplo/issuer/.well-known/openid-configuration`
+- **JWKS Endpoint**:
+  `https://{deploymentName}.zuplo.com/__zuplo/issuer/.well-known/jwks.json`
+
+The OIDC configuration endpoint returns a standard OpenID Connect discovery
+document that includes the JWKS URI for retrieving the public keys used to
+verify JWTs.
+
+### Creating a JWT Authorization Policy
+
+A common pattern is to create a custom policy that automatically adds JWT tokens
+to outbound requests. This is useful when calling downstream APIs that require
+authentication.
+
+Here's an example of a [custom policy](../policies/custom-code-inbound.mdx) that
+adds a JWT to the Authorization header of outbound requests:
+
+```ts title="modules/policies/jwt-auth-upstream.ts"
+import {
+  ZuploRequest,
+  ZuploContext,
+  RequestHandlerPlugin,
+  JwtServicePlugin,
+} from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  // Generate a JWT with the configured options
+  const jwt = await JwtServicePlugin.signJwt({
+    subject: request.user?.sub || "api-gateway",
+    audience: request.url,
+  });
+
+  // Add the JWT to the Authorization header of the request
+  const headers = new Headers(request.headers);
+  headers.set("Authorization", `Bearer ${jwt}`);
+
+  return new ZuploRequest(request, { headers });
+}
+```
+
+## Validating JWTs in Upstream Services
+
+Upstream services can validate the JWTs issued by your Zuplo API by verifying
+the signature and claims. Here's an example of how to validate JWTs in different
+environments:
+
+### Node.js/Express Example
+
+```js title="validate-jwt.js"
+const jwt = require("jsonwebtoken");
+const jwksClient = require("jwks-rsa");
+
+// Replace with your actual Zuplo deployment name or custom domain
+const ISSUER = "https://my-api.zuplo.com/__zuplo/issuer";
+
+// Create a JWKS client to fetch public keys
+const client = jwksClient({
+  jwksUri: `${ISSUER}/.well-known/jwks.json`,
+  cache: true,
+  cacheMaxAge: 600000, // 10 minutes
+});
+
+// Function to get the signing key
+function getKey(header, callback) {
+  client.getSigningKey(header.kid, function (err, key) {
+    if (err) {
+      return callback(err);
+    }
+    const signingKey = key.getPublicKey();
+    callback(null, signingKey);
+  });
+}
+
+// Middleware to validate JWT
+function validateJwt(req, res, next) {
+  const token = req.headers.authorization?.replace("Bearer ", "");
+
+  if (!token) {
+    return res.status(401).json({ error: "No token provided" });
+  }
+
+  jwt.verify(
+    token,
+    getKey,
+    {
+      issuer: ISSUER,
+      algorithms: ["RS256"],
+    },
+    (err, decoded) => {
+      if (err) {
+        return res
+          .status(401)
+          .json({ error: "Invalid token", details: err.message });
+      }
+      req.user = decoded;
+      next();
+    },
+  );
+}
+
+// Example usage
+app.get("/protected", validateJwt, (req, res) => {
+  res.json({
+    message: "Access granted",
+    user: req.user,
+  });
+});
+```
+
+### Python/FastAPI Example
+
+```python title="validate_jwt.py"
+from fastapi import FastAPI, Depends, HTTPException, Security
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+import jwt
+from jwt import PyJWKClient
+import requests
+
+app = FastAPI()
+security = HTTPBearer()
+
+# Replace with your actual Zuplo deployment name or custom domain
+ISSUER = "https://my-api.zuplo.com/__zuplo/issuer"
+JWKS_URL = f"{ISSUER}/.well-known/jwks.json"
+
+# Initialize JWKS client
+jwks_client = PyJWKClient(JWKS_URL)
+
+async def validate_token(credentials: HTTPAuthorizationCredentials = Security(security)):
+    token = credentials.credentials
+
+    try:
+        # Get the signing key from JWKS
+        signing_key = jwks_client.get_signing_key_from_jwt(token)
+
+        # Verify and decode the token
+        payload = jwt.decode(
+            token,
+            signing_key.key,
+            algorithms=["RS256"],
+            issuer=ISSUER,
+            options={"verify_exp": True}
+        )
+
+        return payload
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(status_code=401, detail="Token has expired")
+    except jwt.InvalidTokenError as e:
+        raise HTTPException(status_code=401, detail=f"Invalid token: {str(e)}")
+
+@app.get("/protected")
+async def protected_route(token_data: dict = Depends(validate_token)):
+    return {
+        "message": "Access granted",
+        "user": token_data
+    }
+```
+
+### Dynamic OIDC Discovery
+
+For more flexible JWT validation, you can use a library to dynamically discover
+the OIDC configuration based on the issuer claim in the JWT. This example uses
+the [`oauth4webapi`](https://github.com/panva/oauth4webapi) library.
+
+:::warning{title="Security Warning"}
+
+This approach is particularly useful when you have multiple Zuplo APIs with
+different issuers or when the issuer URL might change (for example, between
+environments). It's CRITICAL that you validate the issuer claim in the JWT to
+ensure you are only allowing tokens from trusted issuers.
+
+:::
+
+```js title="validate-jwt-dynamic.js"
+import * as oauth from "oauth4webapi";
+
+const ALLOWED_ISSUERS = [
+  "https://my-api.zuplo.com/__zuplo/issuer",
+  "https://another-api.zuplo.com/__zuplo/issuer",
+  // Add more allowed issuers as needed
+];
+
+async function validateJwtDynamic(token) {
+  try {
+    // Decode the JWT header and payload without verification first
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      throw new Error("Invalid JWT format");
+    }
+
+    const payload = JSON.parse(
+      atob(parts[1].replace(/-/g, "+").replace(/_/g, "/")),
+    );
+
+    // Extract the issuer from the token
+    const issuer = payload.iss;
+    if (!issuer) {
+      throw new Error("No issuer claim in token");
+    }
+
+    // Validate the issuer against allowed issuers
+    if (!ALLOWED_ISSUERS.includes(issuer)) {
+      throw new Error(`Issuer ${issuer} isn't allowed`);
+    }
+
+    // Discover the OIDC configuration
+    const issuerUrl = new URL(issuer);
+    const as = await oauth
+      .discoveryRequest(issuerUrl)
+      .then((response) => oauth.processDiscoveryResponse(issuerUrl, response));
+
+    // Get the JWKS
+    const jwks = await oauth
+      .jwksRequest(as)
+      .then((response) => oauth.processJwksResponse(response));
+
+    // Import the JWT and validate it
+    const { payload: verifiedPayload, protectedHeader } =
+      await oauth.validateJwt(token, jwks, {
+        issuer: issuer,
+        audience: payload.aud, // Optional: validate audience
+      });
+
+    return verifiedPayload;
+  } catch (error) {
+    throw new Error(`JWT validation failed: ${error.message}`);
+  }
+}
+
+// Express middleware example
+function validateJwtMiddleware(req, res, next) {
+  const token = req.headers.authorization?.replace("Bearer ", "");
+
+  if (!token) {
+    return res.status(401).json({ error: "No token provided" });
+  }
+
+  validateJwtDynamic(token)
+    .then((payload) => {
+      req.user = payload;
+      next();
+    })
+    .catch((error) => {
+      res.status(401).json({ error: error.message });
+    });
+}
+
+// Usage
+app.get("/protected", validateJwtMiddleware, (req, res) => {
+  res.json({
+    message: "Access granted",
+    user: req.user,
+  });
+});
+```
+
+This approach is particularly useful when:
+
+- You need to validate JWTs from multiple Zuplo APIs with different issuers
+- The issuer URL might change (for example, between environments)
+- You want to leverage automatic OIDC discovery for configuration updates
+
+### Important Validation Steps
+
+When validating JWTs from Zuplo:
+
+1. **Verify the signature** using the public keys from the JWKS endpoint
+2. **Check the issuer** matches your Zuplo API's issuer URL
+3. **Validate expiration** to ensure the token hasn't expired
+4. **Verify audience** if your tokens include audience claims
+5. **Check any custom claims** required by your application
+
+The JWT Service Plugin handles key rotation automatically, so always fetch the
+current public keys from the JWKS endpoint rather than hard coding them.

package/docs/programmable-api/logger.mdx

@@ -0,0 +1,223 @@
+---
+title: Logger
+---
+
+The `Logger` interface provides structured logging capabilities throughout your
+Zuplo API gateway. The logger is accessible via the `context.log` property and
+supports multiple log levels.
+
+## Interface
+
+```ts
+interface Logger {
+  debug(...messages: unknown[]): void;
+  info(...messages: unknown[]): void;
+  warn(...messages: unknown[]): void;
+  error(...messages: unknown[]): void;
+  log(...messages: unknown[]): void;
+}
+```
+
+## Log Levels
+
+The logger supports the following levels (from least to most severe):
+
+- `debug` - Detailed information for debugging
+- `info` - General informational messages
+- `warn` - Warning messages for potentially problematic situations
+- `error` - Error messages for failures and exceptions
+- `log` - Alias for `info` level
+
+## Usage
+
+The logger is available on the [ZuploContext](./zuplo-context.mdx) object:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  // Log at different levels
+  context.log.debug("Detailed debug information");
+  context.log.info("Request received", { path: request.url });
+  context.log.warn("Deprecated endpoint accessed");
+  context.log.error("Failed to process request", { error: "Invalid input" });
+
+  return new Response("OK");
+}
+```
+
+## Structured Logging
+
+The logger accepts multiple arguments and automatically serializes objects:
+
+```ts
+// Log simple strings
+context.log.info("User authenticated");
+
+// Log objects
+context.log.info({
+  userId: "user-123",
+  action: "login",
+  timestamp: Date.now(),
+});
+
+// Log multiple arguments
+context.log.info(
+  "Processing request",
+  {
+    method: request.method,
+    path: request.url,
+  },
+  "additional info",
+);
+
+// Log arrays
+context.log.debug(["step1", "step2", "step3"]);
+
+// Log errors
+try {
+  await riskyOperation();
+} catch (error) {
+  context.log.error("Operation failed", {
+    error: error.message,
+    stack: error.stack,
+  });
+}
+```
+
+## Automatic Request ID
+
+The logger automatically includes the request ID with every log entry:
+
+```ts
+context.log.info("Processing payment");
+// Output includes: { "message": "Processing payment", "requestId": "req_abc123..." }
+```
+
+## Environment Configuration
+
+Log levels vary by environment:
+
+- **Development/Preview**: Typically set to `debug` or `info` level
+- **Production**: Typically set to `error` level only
+
+## Best Practices
+
+### 1. Use Appropriate Log Levels
+
+```ts
+// Debug - detailed information for troubleshooting
+context.log.debug("Cache lookup", { key: cacheKey, ttl: 300 });
+
+// Info - general application flow
+context.log.info("Order created", { orderId: "order-123", total: 99.99 });
+
+// Warn - concerning but not critical
+context.log.warn("Rate limit approaching", { current: 95, limit: 100 });
+
+// Error - failures and exceptions
+context.log.error("Payment failed", {
+  orderId: "order-123",
+  errorCode: "INSUFFICIENT_FUNDS",
+});
+```
+
+### 2. Include Contextual Information
+
+```ts
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const startTime = Date.now();
+  const userId = request.user?.sub;
+
+  context.log.info("Request started", {
+    userId,
+    method: request.method,
+    path: new URL(request.url).pathname,
+    userAgent: request.headers.get("user-agent"),
+  });
+
+  try {
+    const result = await processRequest(request);
+
+    context.log.info("Request completed", {
+      userId,
+      duration: Date.now() - startTime,
+      status: "success",
+    });
+
+    return new Response(JSON.stringify(result));
+  } catch (error) {
+    context.log.error("Request failed", {
+      userId,
+      duration: Date.now() - startTime,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    throw error;
+  }
+}
+```
+
+### 3. Avoid Logging Sensitive Data
+
+```ts
+// DON'T log sensitive information
+context.log.info("User login", {
+  email: user.email,
+  password: user.password, // Never log passwords!
+});
+
+// DO log safe identifiers
+context.log.info("User login", {
+  userId: user.id,
+  email: user.email.replace(/(.{2}).*(@.*)/, "$1***$2"), // Partially masked
+});
+```
+
+### 4. Use Structured Data for Better Querying
+
+```ts
+// Good - structured data that can be queried
+context.log.info("API call completed", {
+  service: "payment-processor",
+  operation: "charge",
+  duration: 1234,
+  status: "success",
+  amount: 99.99,
+  currency: "USD",
+});
+
+// Less useful - unstructured string
+context.log.info(`Payment of $99.99 USD processed in 1234ms`);
+```
+
+## Integration with Log Management
+
+Logs are automatically forwarded to your configured log management solution
+(Datadog, Loki, etc.). The structured format makes it easy to:
+
+- Search and filter logs
+- Create alerts based on log patterns
+- Generate metrics from log data
+- Trace requests across services
+
+## Performance Considerations
+
+- Logging has minimal performance impact
+- Logs are processed asynchronously
+- In production, use `error` level to reduce log volume
+- Avoid logging large objects or sensitive data
+
+## See Also
+
+- [ZuploContext](./zuplo-context.mdx) - The context object that provides the
+  logger
+- [Logging](../articles/logging.mdx) - General logging documentation
+- [Log Export](../articles/logging.mdx) - Exporting logs to external services