What Kind of Input Does the TREK Server Expect?

The TREK server expects HTTP requests with specific content types—multipart/form-data for file uploads, application/json for REST API and OAuth token exchanges, and URL-encoded query parameters for authorization flows—routed through Express middleware that enforces CORS, security headers, and authentication validation.

The mauriceboe/TREK backend is built on Express wrapped by NestJS, exposing a RESTful interface that handles everything from image uploads to OAuth 2.0 flows. Understanding the exact input format is critical for client integration, as the server strictly validates content types, authentication tokens, and request bodies before routing to controllers.

Input Categories and Expected Formats

The server organizes input handling into four distinct categories, each with strict requirements for HTTP method, path, and payload format.

Static File Uploads and Retrieval

Upload endpoints accept binary data via POST requests with multipart/form-data encoding. These routes are defined in server/src/nest/platform/platform.routes.ts and include:

• /uploads/avatars – User avatar images
• /uploads/covers – Cover images
• /uploads/journey – Journey-related files

Static file retrieval uses GET requests to /uploads/photos/:filename, but requires authentication via either a valid JWT or a share-token that authorizes access to the specific trip.

Health Checks and Discovery Metadata

Metadata endpoints use simple GET requests with no request body:

• /api/health – Returns { status: "ok" } to verify server availability
• /.well-known/openid-configuration – Exposes OAuth discovery data for OpenID Connect clients
• /.well-known/oauth-protected-resource – Provides OAuth resource indicators

OAuth 2.0 and MCP Protocol Flows

The OAuth implementation expects different input formats depending on the endpoint:

• Authorization requests (GET /oauth/authorize) require URL-encoded query parameters including response_type, client_id, redirect_uri, scope, code_challenge, and code_challenge_method
• Token exchange (POST /oauth/token) expects an application/json body containing grant_type, code, redirect_uri, and code_verifier
• Registration and consent (POST /oauth/register, POST /oauth/consent) accept JSON payloads
• UserInfo (GET /oauth/userinfo) requires a valid Bearer token in the Authorization header

The server also supports Model-Context-Protocol (MCP) specific metadata routes via the MCP SDK.

RESTful Application API

Domain-specific resources under /api/* (such as /api/trips, /api/places, /api/reservations) accept standard REST methods:

• GET – For retrieval (query parameters for filtering)
• POST, PUT, PATCH – For creation and updates with application/json bodies
• DELETE – For resource removal

All application endpoints consume and return JSON, with validation handled by NestJS controllers.

Global Request Processing Pipeline

Before reaching any route handler, every request passes through global middleware defined in server/src/middleware/globalMiddleware.ts. This pipeline configures the Express app to expect:

• CORS enabled for cross-origin requests (app.use(cors({ origin, credentials: true })))
• Security headers via Helmet
• JSON bodies parsed with express.json({ limit: '100kb' })
• URL-encoded bodies parsed with express.urlencoded({ extended: true })
• Cookies parsed via cookieParser()
• Global MFA enforcement via the enforceGlobalMfaPolicy function

If a request violates these expectations—such as exceeding the 100kb JSON limit, missing required headers, or failing authentication—the server responds with standard HTTP status codes (400, 401, 403, or 404) before reaching controller logic.

Required Headers and Authentication

Successful requests must include appropriate headers:

• Content-Type: multipart/form-data for uploads, application/json for API endpoints, or application/x-www-form-urlencoded where specified
• Authorization: Bearer <token> for protected routes, or a valid share-token as a query parameter for photo access
• Accept: application/json for API responses

The authentication schema is defined in shared/src/auth/auth.schema.ts, which validates JWT payloads and password-version gates for protected endpoints.

Code Examples

The following examples demonstrate the exact input format expected by the TREK server.

Health check requires no authentication or body:

GET /api/health HTTP/1.1
Host: trek.example.com

Avatar upload uses multipart encoding:

POST /uploads/avatars HTTP/1.1
Host: trek.example.com
Content-Type: multipart/form-data; boundary=----WebKitBoundary

------WebKitBoundary
Content-Disposition: form-data; name="file"; filename="avatar.png"
Content-Type: image/png

<binary data>
------WebKitBoundary--

OAuth authorization requests use query parameters:

GET /oauth/authorize?response_type=code&client_id=trek-client&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=read%20write&code_challenge=xyz&code_challenge_method=S256 HTTP/1.1
Host: trek.example.com

Token exchange requires JSON:

POST /oauth/token HTTP/1.1
Host: trek.example.com
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "SplxlOBeZQQYbYS6WxSbIA",
  "redirect_uri": "https://app.example.com/callback",
  "code_verifier": "xyz"
}

Summary

• TREK is an Express/NestJS server that strictly validates incoming HTTP requests through global middleware before routing to controllers.
• File uploads to /uploads/* require multipart/form-data POST requests, while photo retrieval requires JWT or share-token authentication.
• OAuth flows expect URL-encoded query parameters for authorization and JSON bodies for token exchanges.
• Application APIs under /api/* consume application/json with a 100kb size limit enforced by express.json() in server/src/middleware/globalMiddleware.ts.
• Key files controlling input expectations include server/src/nest/platform/platform.routes.ts for route definitions and shared/src/auth/auth.schema.ts for authentication validation.

Frequently Asked Questions

What Content-Type should I use for file uploads to TREK?

Upload endpoints such as /uploads/avatars and /uploads/covers expect multipart/form-data with the file included as a form field. The server parses these using standard Express middleware before storing the binary data.

How do I authenticate requests to retrieve photos from the server?

Requests to /uploads/photos/:filename must include either a valid JWT in the Authorization header (Bearer <token>) or a share-token as a query parameter that authorizes access to the specific trip. Without one of these, the server returns a 401 or 403 response.

Is there a request body size limit for JSON payloads?

Yes. According to the middleware configuration in server/src/middleware/globalMiddleware.ts, the server limits JSON bodies to 100kb via express.json({ limit: '100kb' }). Requests exceeding this limit receive a 413 Payload Too Large error.

Does TREK support form-urlencoded request bodies?

Yes. The server explicitly configures express.urlencoded({ extended: true }) in the global middleware to parse URL-encoded bodies. This is primarily used for OAuth endpoints and traditional form submissions, while the REST API prefers application/json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}