tdsk-proxy

Documents the Auth Gateway proxy architecture covering JWT, API key, and session authentication.

Updated Jan 4, 2026

Search Tags:#typescript #authentication #jwt #express #api gateway #websocket #proxy

Ready to run

npx skills add https://github.com/threadedstack/threadedstack --skill tdsk-proxy-threadedstack

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: tdsk-proxy
Source: https://github.com/threadedstack/threadedstack/tree/main/.claude/skills/tdsk-proxy
Command: npx skills add https://github.com/threadedstack/threadedstack --skill tdsk-proxy-threadedstack

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers working on the Auth Gateway proxy repo need to understand its triple-auth model, dual-proxy forwarding, and middleware chain before making changes, and this knowledge base provides that context on demand. ## Core Features & Use Cases - Auth Flow Reference: Explains the four route classifications (public, session, deferred, standard) and how JWT via JWKS, `tdsk_*` API keys, and ephemeral session tokens are each enforced. - Architecture Documentation: Details the 11-middleware chain order, dual-proxy setup (sandbox subdomain forwarder plus backend proxy), and manual WebSocket upgrade dispatch. - Use Case: When adding a new endpoint to the proxy, consult this Skill to determine which route constant it belongs in, which auth middleware applies, and how it interacts with rate limiting and proxy forwarding. ## Quick Start Explain how authentication works for the /ai/ws WebSocket route in the proxy repo.

Frequently Asked Questions about tdsk-proxy

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How does the proxy authenticate requests with JWT and API keys?▼

The proxy uses triple-auth: JWT verified against a Neon Auth JWKS endpoint via jose, `tdsk_*` Bearer API keys validated against the database, and ephemeral session tokens for `/ai/ws`. Each route gets exactly one auth mechanism based on its classification.

How do I add a new public route to an Express auth gateway?▼

Add the path to the `PublicRoutes` constant in `src/constants/values.ts`. Public routes like `/health` and `/echo` skip all auth middleware, while deferred routes attempt auth without enforcing it.

How does WebSocket proxying work with http-proxy middleware?▼

Both proxies are created with `ws: false` to avoid conflicting upgrade listeners. A single manual `onUpgrade` handler on the HTTP server checks the hostname and dispatches sandbox hosts to the sandbox proxy and all others to the backend proxy.

Why does the sandbox proxy preserve the Host header?▼

The sandbox forwarder uses `changeOrigin: false` so the backend's sandboxProxy middleware can identify the target sandbox from the original subdomain matching `/^\d+--sb-/`. The backend proxy uses `changeOrigin: true` instead.

What rate limits apply to proxy routes?▼

Rate limiting uses express-rate-limit with draft-7 standard headers: `/auth` routes are limited to 20 requests per minute and `/_` routes to 1000 requests per minute. The setupRateLimit middleware runs third in the chain.