skills-ws
Version:
87 agent skills for AI coding assistants — marketing, growth, web3, dev, design & operations. Built for OpenClaw, Claude Code, Cursor, and Codex.
337 lines (283 loc) • 15.6 kB
Markdown
## Contents
- 6. Three-Tier Authentication
- Tier Overview
- Auth Middleware Implementation
- Applying Auth to the Streamable HTTP Server
- 6b. OAuth 2.1 / OIDC Resource-Server Auth (bearer tokens)
## 6. Three-Tier Authentication
The core monetization architecture: free → API key → x402 micropayments.
### Tier Overview
| Tier | Auth | Rate Limit | Cost | Use Case |
|------|------|-----------|------|----------|
| **Free** | IP-based | 10 req/min, 100/day | $0 | Try before you buy |
| **Pro** | API key header | 100 req/min, 10k/day | $9/mo (Stripe) | Regular users |
| **Pay-per-use** | x402 payment | Unlimited | $0.005/call | AI agents, burst usage |
### Auth Middleware Implementation
```typescript
// src/auth/middleware.ts
import crypto from "crypto";
import type express from "express";
// --- Rate limiter (in-memory, use Redis in production) ---
interface RateEntry { count: number; resetAt: number; daily: number; dailyResetAt: number; }
const ipLimits = new Map<string, RateEntry>();
const keyLimits = new Map<string, RateEntry>();
function checkRateLimit(
store: Map<string, RateEntry>,
key: string,
perMinute: number,
perDay: number
): { allowed: boolean; retryAfter?: number } {
const now = Date.now();
let entry = store.get(key);
if (!entry || now > entry.resetAt) {
entry = { count: 0, resetAt: now + 60_000, daily: entry?.daily ?? 0, dailyResetAt: entry?.dailyResetAt ?? now + 86_400_000 };
}
if (now > entry.dailyResetAt) {
entry.daily = 0;
entry.dailyResetAt = now + 86_400_000;
}
if (entry.count >= perMinute) return { allowed: false, retryAfter: Math.ceil((entry.resetAt - now) / 1000) };
if (entry.daily >= perDay) return { allowed: false, retryAfter: Math.ceil((entry.dailyResetAt - now) / 1000) };
entry.count++;
entry.daily++;
store.set(key, entry);
return { allowed: true };
}
// --- Constant-time comparison (HMAC-based to avoid length leaks) ---
function secureCompare(a: string, b: string): boolean {
// HMAC both inputs with a random key — normalizes to fixed-length hashes,
// so timingSafeEqual works without an early-return length check.
const key = crypto.randomBytes(32);
const hmacA = crypto.createHmac("sha256", key).update(a).digest();
const hmacB = crypto.createHmac("sha256", key).update(b).digest();
return crypto.timingSafeEqual(hmacA, hmacB);
}
// --- API key store (use DB in production) ---
const API_KEYS = new Map<string, { userId: string; tier: string }>();
export function loadApiKeysFromEnv() {
const keys = process.env.API_KEYS; // Format: "key1:user1,key2:user2"
if (keys) {
for (const pair of keys.split(",")) {
const [key, userId] = pair.split(":");
if (key && userId) API_KEYS.set(key, { userId, tier: "pro" });
}
}
}
// --- Main auth middleware ---
// x402 v2 lives in §7 (PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE, base64 JSON,
// facilitator verify+settle). For a real deployment prefer the official `x402-express`
// middleware (§7) over hand-rolling header parsing. The hook below shows where the x402
// tier slots into the three-tier flow; `settleX402` is defined in §7.
export interface AuthResult {
tier: "free" | "pro" | "x402";
userId?: string;
// settlement headers to echo on the 200 response (PAYMENT-RESPONSE), set by the x402 path
responseHeaders?: Record<string, string>;
}
export async function authenticate(req: express.Request): Promise<{ auth: AuthResult } | { error: string; status: number; headers?: Record<string, string> }> {
// 1. x402 v2: client presents a signed payload in PAYMENT-SIGNATURE (base64 JSON).
const paymentSig = req.headers["payment-signature"] as string | undefined;
if (paymentSig) {
const { settled, paymentResponse, error } = await settleX402(paymentSig, req); // see §7
if (settled) return { auth: { tier: "x402", responseHeaders: { "PAYMENT-RESPONSE": paymentResponse! } } };
// Settlement failed → re-challenge with fresh requirements.
return { error: error || "Payment settlement failed", status: 402, headers: { "PAYMENT-REQUIRED": buildPaymentRequired(req) } };
}
// No signature yet → challenge with 402 + PAYMENT-REQUIRED (base64 JSON array of requirements).
if ((req.headers["accept-payment"] as string) === "x402") {
return { error: "Payment required", status: 402, headers: { "PAYMENT-REQUIRED": buildPaymentRequired(req) } };
}
// 2. Check for API key
const apiKey = req.headers["x-api-key"] as string || req.headers["authorization"]?.replace("Bearer ", "");
if (apiKey) {
let foundUser: { userId: string; tier: string } | undefined;
for (const [storedKey, user] of API_KEYS) {
if (secureCompare(apiKey, storedKey)) {
foundUser = user;
break;
}
}
if (!foundUser) return { error: "Invalid API key", status: 401 };
const limit = checkRateLimit(keyLimits, foundUser.userId, 100, 10_000);
if (!limit.allowed) return { error: "Rate limit exceeded", status: 429, headers: { "Retry-After": String(limit.retryAfter) } };
return { auth: { tier: "pro", userId: foundUser.userId } };
}
// 3. Fall back to free tier (IP rate limit)
const ip = req.headers["x-forwarded-for"]?.toString().split(",")[0]?.trim() || req.socket.remoteAddress || "unknown";
const limit = checkRateLimit(ipLimits, ip, 10, 100);
if (!limit.allowed) {
return {
error: "Rate limit exceeded. Get an API key at https://your-server.com/pricing or pay per use with x402.",
status: 429,
headers: { "Retry-After": String(limit.retryAfter) },
};
}
return { auth: { tier: "free" } };
}
```
### Applying Auth to the Streamable HTTP Server
```typescript
// src/http-server-authed.ts
import express from "express";
import cors from "cors";
import crypto from "crypto";
import { randomUUID } from "node:crypto";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
import { authenticate, loadApiKeysFromEnv, secureCompare, type AuthResult } from "./auth/middleware.js";
const app = express();
// MUST come before express.json() for webhook signature verification (see §8).
app.use("/webhooks/stripe", express.raw({ type: "application/json" }));
app.use(express.json());
// CORS: explicit origins, fail closed (never "*" — esp. with credentials). Expose the session header.
const allowedOrigins = (process.env.ALLOWED_ORIGINS || "").split(",").map(s => s.trim()).filter(Boolean);
app.use(cors({
origin: allowedOrigins.length ? allowedOrigins : false,
methods: ["GET", "POST", "DELETE"],
allowedHeaders: ["Content-Type", "Mcp-Session-Id", "Last-Event-ID", "Authorization", "X-API-Key", "PAYMENT-SIGNATURE", "Accept-Payment"],
exposedHeaders: ["Mcp-Session-Id", "PAYMENT-REQUIRED", "PAYMENT-RESPONSE"],
}));
loadApiKeysFromEnv();
// Health + admin endpoints
app.get("/health", (_req, res) => res.json({ status: "ok", uptime: process.uptime() }));
app.get("/admin/stats", (req, res) => {
const adminKey = req.headers["x-admin-key"] as string | undefined;
// Constant-time compare — never use !== on a secret (timing leak). Mirror the secureCompare in §9.
if (!adminKey || !process.env.ADMIN_KEY || !secureCompare(adminKey, process.env.ADMIN_KEY)) {
return res.status(401).json({ error: "Unauthorized" });
}
res.json({
activeSessions: Object.keys(transports).length,
uptime: process.uptime(),
memory: process.memoryUsage(),
});
});
// --- Stripe Webhook for subscription management ---
// Use stripe.webhooks.constructEvent instead of manual HMAC verification.
// It handles timestamp tolerance (rejects events older than 5 minutes) and
// proper signature comparison.
app.post("/webhooks/stripe", async (req, res) => {
const sig = req.headers["stripe-signature"] as string;
if (!sig || !process.env.STRIPE_WEBHOOK_SECRET) return res.status(400).send("Missing signature");
let event;
try {
event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET);
} catch (err: any) {
return res.status(400).send(`Webhook error: ${err.message}`);
}
switch (event.type) {
case "checkout.session.completed":
console.log("New subscription:", event.data.object.customer_email);
// Provision API key for customer
break;
case "customer.subscription.deleted":
console.log("Subscription cancelled:", event.data.object.id);
// Revoke API key
break;
}
res.json({ received: true });
});
// --- Pricing endpoint ---
app.get("/pricing", (_req, res) => {
res.json({
tiers: [
{ name: "Free", price: "$0", limits: "10 req/min, 100/day", features: ["All tools", "IP rate limited"] },
{ name: "Pro", price: "$9/mo", limits: "100 req/min, 10k/day", features: ["All tools", "API key", "Priority support"], stripeLink: process.env.STRIPE_CHECKOUT_LINK },
{ name: "Pay-per-use", price: "$0.005/call", limits: "Unlimited", features: ["All tools", "x402 micropayments", "No subscription needed"] },
],
});
});
// --- MCP Streamable HTTP with three-tier auth ---
// Authenticate on the `initialize` POST (the start of a session); the tier is then bound
// to that session's McpServer. GET/DELETE just resume/terminate an already-authed session.
const transports: Record<string, StreamableHTTPServerTransport> = {};
app.post("/mcp", async (req, res) => {
const sessionId = req.headers["mcp-session-id"] as string | undefined;
// Existing session → trust the prior auth, reuse the transport.
if (sessionId && transports[sessionId]) {
return transports[sessionId].handleRequest(req, res, req.body);
}
if (sessionId || !isInitializeRequest(req.body)) {
return res.status(400).json({ jsonrpc: "2.0", error: { code: -32000, message: "Bad Request: no valid session id" }, id: null });
}
// New session: run the tiered auth gate.
const authResult = await authenticate(req);
if ("error" in authResult) {
if (authResult.headers) for (const [k, v] of Object.entries(authResult.headers)) res.setHeader(k, v);
return res.status(authResult.status).json({ error: authResult.error });
}
const { auth } = authResult;
// x402 settlement receipt (PAYMENT-RESPONSE) rides back on the 200.
if (auth.responseHeaders) for (const [k, v] of Object.entries(auth.responseHeaders)) res.setHeader(k, v);
console.log(`New session: tier=${auth.tier}, userId=${auth.userId || "anonymous"}`);
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => randomUUID(),
onsessioninitialized: (sid) => { transports[sid] = transport; },
});
transport.onclose = () => { const sid = transport.sessionId; if (sid) delete transports[sid]; };
await createMcpServer(auth).connect(transport);
await transport.handleRequest(req, res, req.body);
});
const sessionRequest = async (req: express.Request, res: express.Response) => {
const sessionId = req.headers["mcp-session-id"] as string | undefined;
if (!sessionId || !transports[sessionId]) return res.status(400).send("Invalid or missing session id");
await transports[sessionId].handleRequest(req, res);
};
app.get("/mcp", sessionRequest);
app.delete("/mcp", sessionRequest);
function createMcpServer(_auth: AuthResult): McpServer {
const server = new McpServer({ name: "my-mcp-server", version: "1.0.0" });
// Register tools here — all tiers get all tools; rate limiting / payment gate access.
return server;
}
const PORT = parseInt(process.env.PORT || "3100");
app.listen(PORT, () => console.log(`MCP server running on http://localhost:${PORT}/mcp`));
```
### 6b. OAuth 2.1 / OIDC Resource-Server Auth (bearer tokens)
For enterprise / hosted MCP servers, validate **OAuth 2.1 bearer tokens** instead of (or alongside) API keys. The MCP server is an OAuth **resource server**: it verifies the access token a client got from your IdP (Auth0, Okta, Entra ID, Keycloak, Cognito…), checks the **audience** and **scopes**, and advertises its metadata so clients can discover where to authorize.
The SDK ships `requireBearerAuth({ verifier, requiredScopes, resourceMetadataUrl })`, which returns `401` with a proper `WWW-Authenticate` header (including `resource_metadata` for MCP's authorization flow) when a token is missing/invalid/under-scoped. You supply an `OAuthTokenVerifier` — typically a JWT validator backed by your IdP's JWKS:
```typescript
// src/auth/oauth.ts
import { createRemoteJWKSet, jwtVerify } from "jose";
import type { OAuthTokenVerifier } from "@modelcontextprotocol/sdk/server/auth/provider.js";
import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
// JWKS is fetched once and cached/rotated by jose — do NOT re-create per request.
const ISSUER = process.env.OAUTH_ISSUER!; // e.g. https://tenant.us.auth0.com/
const AUDIENCE = process.env.OAUTH_AUDIENCE!; // this MCP server's resource id / API identifier
const jwks = createRemoteJWKSet(new URL(`${ISSUER}.well-known/jwks.json`));
export const verifier: OAuthTokenVerifier = {
async verifyAccessToken(token: string): Promise<AuthInfo> {
const { payload } = await jwtVerify(token, jwks, {
issuer: ISSUER,
audience: AUDIENCE, // reject tokens minted for a different resource
});
const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
// `expiresAt` lets the SDK reject expired tokens; clientId aids logging/rate-limiting.
return { token, clientId: String(payload.azp ?? payload.client_id ?? ""), scopes, expiresAt: payload.exp };
},
};
```
```typescript
// src/http-server-oauth.ts — wire it onto /mcp
import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
import { mcpAuthMetadataRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
import { verifier } from "./auth/oauth.js";
const mcpServerUrl = new URL(process.env.MCP_PUBLIC_URL || "https://mcp.yourdomain.com/mcp");
const resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(mcpServerUrl);
// Publishes /.well-known/oauth-protected-resource so MCP clients can discover the IdP + scopes.
app.use(mcpAuthMetadataRouter({
oauthMetadata: { issuer: process.env.OAUTH_ISSUER!, authorization_endpoint: `${process.env.OAUTH_ISSUER}authorize`, token_endpoint: `${process.env.OAUTH_ISSUER}oauth/token`, response_types_supported: ["code"] },
resourceServerUrl: mcpServerUrl,
scopesSupported: ["mcp:tools:read", "mcp:tools:write"],
resourceName: "my-mcp-server",
}));
// Require a valid bearer token (and a scope) on the MCP endpoint. On failure the SDK emits
// 401 + WWW-Authenticate: Bearer ..., resource_metadata="<resourceMetadataUrl>".
const bearer = requireBearerAuth({ verifier, requiredScopes: ["mcp:tools:read"], resourceMetadataUrl });
app.post("/mcp", bearer, /* mcpPostHandler from §6 — req.auth now holds the AuthInfo */);
app.get("/mcp", bearer, sessionRequest);
app.delete("/mcp", bearer, sessionRequest);
```
> **Per-tool scopes.** Coarse gate at the middleware (`mcp:tools:read`); enforce write scopes inside the handler: read `req.auth.scopes` (or `extra.authInfo` in newer SDKs) and reject a mutating tool if the caller lacks `mcp:tools:write`. **Always check `aud`** — a token minted for another service must not be replayable against your MCP server.
---