OpenSEO's entry point is src/server.ts, a Cloudflare Worker that routes fetch requests to OAuth (hosted mode) or the MCP endpoint (self-hosted), dispatches agent requests to Durable Objects with auth checks, and runs cron tasks for rank checks, audit reconciliation, and KV cleanup. Request handling flows through multiple auth and validation gates: organization customer setup before Durable Objects, per-connection and per-request auth checks before Durable Object dispatch, and middleware-enforced user and project context in server functions. A Durable Object is a Cloudflare Workers primitive that provides a single-threaded, stateful compute instance with its own isolated storage, guaranteeing serialized execution for a given entity.
src/server.ts is the Cloudflare Worker entry point, handling all incoming fetch requests and scheduled cron events for the OpenSEO application.[1] Two cron triggers are configured in wrangler.jsonc: "*/5 * * * *" (every 5 minutes, for rank checks and stale-audit reconciliation) and "17 3 * * *" (daily, for OAuth KV garbage collection).[2]
Hosted-mode requests (auth mode HOSTED) in src/server.ts are processed by the openSeoOAuthProvider (a Cloudflare OAuth provider), with the Autumn billing webhook at AUTUMN_WEBHOOK_PATH handled first before handing off to OAuth.[1] Self-hosted instances using cloudflare_access or local_noauth auth modes serve the MCP endpoint at MCP_ROUTE via handleSelfHostedOpenSeoMcpRequest in src/server.ts.[1]
Requests to /agents/* in src/server.ts are dispatched to the onboarding and SAM chat Durable Objects via routeAgentRequest, with per-connection and per-request auth checks applied before reaching the DO.[1] authorizeChatAgent in src/server.ts dispatches on lobby.className — "SAM_CHAT" routes to authorizeSamChat, "ONBOARDING_CHAT" to authorizeOnboardingChat, and any unrecognized class name returns 403 Forbidden (fail-closed).[1] Before a brand-new organization's first onboarding or SAM chat message, src/server.ts calls getOrCreateOrganizationCustomer (hosted mode only) to ensure the Autumn billing customer and its default credits exist before the Durable Object's credit-balance gate runs — preventing a false "out of credits" rejection.[1] OpenSEO uses Cloudflare Durable Objects to maintain per-chat session state, ensuring each onboarding or SAM chat conversation is isolated and consistent.
The scheduled cron handler in src/server.ts runs stale-audit reconciliation (reconcileStaleAudits) before rank checks so a slow watchdog tick cannot delay or starve the rank check loop; watchdog errors are held and re-thrown after rank checks complete so they do not suppress the rank run.[1] The MCP_OAUTH_PURGE_CRON scheduled job in src/server.ts runs at "17 3 * * *" (daily at 03:17) and purges expired OAuth KV data only in hosted mode; an incomplete sweep logs a warning that the KV keyspace outgrew the batch size.[1]
src/start.ts configures the TanStack Start instance with a CSRF middleware that applies only to serverFn handler types, and wires in globalServerFunctionMiddleware as function-level middleware.[3] src/serverFunctions/middleware.ts exports globalServerFunctionMiddleware, a tuple of [errorHandlingMiddleware, ensureUserMiddleware], as the base middleware stack applied to all server functions.[4] requireProjectContext middleware in src/serverFunctions/middleware.ts throws an AppError('INTERNAL_ERROR', ...) if authenticatedContext.project is absent, then forwards project, projectId, and the full authenticated context to the next handler.[4]
Sources