Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Backend Middleware
Every file in backend/middleware/ does one piece of work that many requests need. backend/app.ts applies them in a fixed order; REQUEST_PIPELINE.md explains why the order matters.
Middleware Stack (in execution order)
Request arrives
1. apiCors app.use('*', apiCors) middleware/cors.ts
2. requestId app.use('*', requestId()) hono/request-id
requestContext app.use('*', requestContext) middleware/requestContext.ts
3. securityHeaders app.use('*', securityHeaders) middleware/securityHeaders.ts
4. injectClients app.use('*', injectClients) middleware/clients.ts
5. rateLimit(ip) app.use('/api/*' and '/mcp', rateLimit(RATE_LIMIT_RULES.ip, clientIp)) middleware/rateLimit.ts
MCP endpoint app.post('/mcp', requireMcpAuth, rateLimit(mcp), handleMcpMessage) middleware/mcpAuth.ts
GET and DELETE /mcp answer 405; /.well-known/oauth-protected-resource(/mcp) answer the metadata
public routes app.route('/api', publicRoutes) health check, OAuth callback (+ rateLimit(oauth)),
email hook (+ verifyAuthHook) middleware/authHook.ts
Instagram webhook POST (+ verifyMetaWebhook) middleware/metaWebhook.ts
6. requireAuth api.use('*', requireAuth) middleware/auth.ts <- protected routes only
7. rateLimit(user, quota, publish) middleware/rateLimit.ts <- protected routes only
8. route table api.route('/', protectedRoutes)
jsonBody / queryParams middleware/validate.ts <- per route
controller
Errors from any step -> errorHandler (app.onError), unknown routes -> notFoundHandler middleware/errorHandler.ts
1. CORS
Source: backend/middleware/cors.ts (wraps hono/cors)
Applied to: Every request, first, so a preflight is answered before any other work
Only the app's own origins may call the API from a browser:
FRONTEND_URL, and every origin in the optionalALLOWED_ORIGINSWorker variable (comma-separated). Each entry is reduced to its origin, and a malformed entry is skipped rather than allowing everything.- When the Worker itself is served from
localhostor127.0.0.1(a development instance), the Vite dev server originshttp://localhost:5173andhttp://127.0.0.1:5173are allowed too.
A request from any other origin gets no Access-Control-Allow-Origin header, so the browser blocks it. The list is built by corsOrigins() in lib/config.ts.
exposeHeaders lets the browser read RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After and X-Request-Id. Preflight results are cached for 10 minutes (maxAge: 600).
2. Request Id and Request Context
Source: hono/request-id, then backend/middleware/requestContext.ts
Applied to: Every request
requestId() sets requestId on the context and the X-Request-Id response header; an incoming X-Request-Id of safe characters is kept. requestContext then:
- Sets
signal, anAbortSignalthat aborts when the client disconnects or after the 30 second request deadline. Services pass it to every platformfetch. - Writes one access log line after the response, with the method, path, status and duration.
It also exports two helpers: requestLogger(c), a logger bound to the request id and user id, and requestContextOf(c), which builds the RequestContext (requestId, signal, log) that controllers hand to services.
3. Security Headers
Source: backend/middleware/securityHeaders.ts (wraps hono/secure-headers)
Applied to: Every response, errors included
The API only answers JSON and redirects, so nothing it returns may be framed, sniffed or run as a page: a deny-all Content-Security-Policy (default-src 'none'; frame-ancestors 'none'), X-Frame-Options: DENY, Referrer-Policy: no-referrer, X-Content-Type-Options: nosniff and Strict-Transport-Security.
4. Client Injection
Source: backend/middleware/clients.ts (injectClients)
Applied to: Every request
Creates per-request Supabase and Redis client instances and sets them on the Hono context. The clients are stateless HTTP clients, so creating them per request is cheap and safe. It first checks the core secrets with missingCoreSecrets(env) (lib/config.ts): when SUPABASE_URL (or a URL that is not a web address), SUPABASE_SERVICE_KEY or SUPABASE_ANON_KEY is missing, it throws NotConfiguredError naming them, so every request answers 503 with a message that says what to set instead of an internal error.
export async function injectClients(c: AppContext, next: Next): Promise<void> {
const missing = missingCoreSecrets(c.env);
if (missing.length > 0) throw new NotConfiguredError(coreSecretsMessage(missing));
c.set('supabase', getSupabase(c.env));
c.set('redis', getRedis(c.env));
c.set('rateLimitRedis', getRateLimitRedis(c.env));
await next();
}
getSupabase(env) (database/supabase.ts) - a Supabase client with the service-role key, used by every repository. Every query has a 15 second timeout (DB_TIMEOUT_MS).getRedis(env) (database/redis.ts) - an Upstash Redis client if UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are set, otherwise null. analyticsCacheRepository treats null as a cache that is always empty.getRateLimitRedis(env) (database/redis.ts) - a second Upstash client for the rate limiter, with retries off and a 1 second timeout, so a Redis outage cannot slow every request. null without credentials.
Controllers do not read these clients themselves; servicesFor(c) passes them to createServices() in container.ts. The keys and their types are declared in AppVariables in backend/types/app.ts, so c.set() rejects a value of the wrong type and c.get() needs no cast.
5. and 7. rateLimit
Source: backend/middleware/rateLimit.ts, rules and algorithms in backend/lib/rateLimit/
Applied to: every /api request (ip rule, before requireAuth), every protected request (user), quota-spending routes (quota), Instagram publishing routes (publish) and the public OAuth callback (oauth)
rateLimit(rule, identify, applies?) returns a middleware. identify(c) returns the key (clientIp or userKey); a request without one is not limited. applies(c) restricts a rule to some routes (matchesRoute(QUOTA_ROUTES, ...)). Allowed responses get RateLimit-* headers for the most restrictive rule. A request over a limit gets 429 with Retry-After and the standard error body plus retryAfter:
{ "success": false, "code": "RATE_LIMITED", "message": "...", "requestId": "3f2a...", "retryAfter": 42 }
The IP limit runs before authentication, so a flood of bad tokens never reaches Supabase Auth. See RATE_LIMITING.md for the rules, the algorithms and how failures are handled.
6. requireAuth
Source: backend/middleware/auth.ts
Applied to: All routes mounted under the api sub-application (every /api/* route except the two public ones)
export async function requireAuth(c: AppContext, next: Next): Promise<void> {
const token = c.req.header('Authorization')?.match(BEARER)?.[1];
if (!token) throw new UnauthorizedError('Sign in to use the API');
const { data: { user }, error } = await getSupabaseAuth(c.env).auth.getUser(token);
if (error || !user) throw new UnauthorizedError('Your session has expired - sign in again');
c.set('userId', user.id);
c.set('userEmail', user.email);
await next();
}
What it does:
- Reads the token from the
Authorization: Bearer <token>header - Creates a Supabase anon client (not service-role) to verify the JWT
- Calls
auth.getUser(token)- Supabase validates the token signature - Sets
userId(UUID) anduserEmail(string | undefined) on the Hono context - Throws
UnauthorizedErrorif the token is missing, invalid or expired; the error handler answers401with codeUNAUTHORIZED
Critical: userId from this middleware is the only trusted source of user identity. Controllers read it with c.get('userId') and pass it to services - never accept a user id from the request body or query parameters.
8. Validation
Source: backend/middleware/validate.ts
Applied to: Individual routes, as the first handler passed to controller.createHandlers(...)
jsonBody(parse) and queryParams(parse) wrap Hono's validator. Each parser in backend/validators/ reads fields with the helpers in validators/fields.ts and throws ValidationError (400). For a query, a repeated key keeps its first value. The controller reads the parsed result with c.req.valid('json') or c.req.valid('query').
export const addYouTubeAccount = controller.createHandlers(jsonBody(parseChannelInput), async c => {
const account = await servicesFor(c).accounts.addYouTube(c.get('userId'), c.req.valid('json').input);
return c.json({ success: true, account } satisfies YouTubeAccountAddResponse);
});
Error Handler
Source: backend/middleware/errorHandler.ts
Applied to: app.onError(errorHandler) and app.notFound(notFoundHandler)
Every error thrown by a middleware, controller, service or repository ends here. An AppError from lib/errors.ts is answered with the status for its code; Hono's own HTTPException (such as a malformed JSON body) is mapped by status; anything else is an INTERNAL_ERROR (500) with a message asking the user to quote the request id. Every failure gets the same body:
{ "success": false, "code": "VALIDATION_ERROR", "message": "Username is required", "requestId": "3f2a..." }
Failures with status 500 and above are logged at error level, 4xx failures at warn. notFoundHandler answers an unknown route with NOT_FOUND. The code to status table is in REQUEST_PIPELINE.md.
authHookErrorHandler does the same logging and status mapping but answers in the shape Supabase Auth reads from a hook, { "error": { "http_code": 429, "message": "..." } }. Only routes/authHookRoutes.ts sets it, with router.onError; Hono applies a route table's own error handler to that table's routes.
Auth Hook Signature
Source: backend/middleware/authHook.ts (verifyAuthHook), with lib/webhookSignature.ts
Applied to: POST /api/auth/email-hook only, before its validator
The hook route is public, so the signature is the only proof that a request came from this project's Supabase Auth. verifyAuthHook:
- Throws
NotConfiguredError(503) whenSEND_EMAIL_HOOK_SECRETis not set. - Reads the raw body with
c.req.text(). Hono caches it, so the JSON validator after it parses the same text. - Checks the Standard Webhooks headers: HMAC-SHA256 over
webhook-id.webhook-timestamp.bodywith the base64 key from thev1,whsec_<base64>secret, compared withcrypto.subtle.verify(constant time). Any onev1,entry inwebhook-signaturemay match. - Rejects a timestamp more than five minutes from now, so a captured request cannot be replayed later.
A failure throws UnauthorizedError (401).
Meta Webhook Signature
Source: backend/middleware/metaWebhook.ts (verifyMetaWebhook), with lib/metaWebhookSignature.ts
Applied to: POST /api/webhooks/instagram only, before its validator
The webhook route is public, so the signature is the only proof that a notification came from Meta. verifyMetaWebhook:
- Throws
NotConfiguredError(503) when neitherINSTAGRAM_APP_SECRETnorMETA_APP_SECRETis set. - Refuses a body over 1 MB with
ValidationError(400), by itsContent-Lengthheader and again by its size once read. - Reads the raw body with
c.req.arrayBuffer(). Hono caches it, so the JSON validator after it parses the same bytes. - Checks
X-Hub-Signature-256(sha256=<hex>): HMAC-SHA256 over the raw body with each configured secret, compared withcrypto.subtle.verify(constant time).
A failure throws UnauthorizedError (401). Meta's notifications carry no timestamp to check; a replayed notification is harmless, because each comment is stored once.
MCP Authentication
Source: backend/middleware/mcpAuth.ts (requireMcpAuth), with services/mcpAccessService.ts and lib/jwtClaims.ts
Applied to: POST /mcp only, after rateLimit(ip) and before rateLimit(mcp)
The MCP endpoint takes credentials a Claude client can hold, never the app's own session token:
- A request with an
Originother thanhttps://claude.ai,https://claude.comor the app's allowed origins is refused with403, so a web page cannot drive the endpoint from someone's browser. - A bearer token starting
twl_is a personal access token: its SHA-256 hash is looked up inmcp_access_tokens, and a revoked or expired one is refused. - Any other bearer token is checked with Supabase Auth (
auth.getUser). It must carry aclient_idclaim, which only tokens issued by Supabase's OAuth server have, and the person must have approved that client (mcp_client_grants); otherwise401or403. - On success it sets
userId(the same variablerequireAuthsets, so every repository scopes by it) andmcpPrincipal({ userId, permission, via }). The permission decides which tools the caller sees and may run.
A 401 carries WWW-Authenticate: Bearer realm="twiligent", and resource_metadata="<backend>/.well-known/oauth-protected-resource/mcp" when MCP_OAUTH_ENABLED is true, which starts sign-in in Claude's apps. Failures use a JSON-RPC error body, not the API's.
Adding New Middleware
Place new middleware files in backend/middleware/. Follow this pattern:
// backend/middleware/myMiddleware.ts
import type { Next } from 'hono';
import type { AppContext } from '../types/app.ts';
export async function myMiddleware(c: AppContext, next: Next): Promise<void> {
// to reject a request, throw a typed error from lib/errors.ts; the error handler formats it
await next();
}
- Reject a request by throwing a typed error (
UnauthorizedError,ValidationError, ...), never by building a JSON body by hand. - A middleware that sets a new context value needs the key added to
AppVariablesinbackend/types/app.tsfirst. Keep context values small and request-scoped. - Log through
requestLogger(c), notconsole.
Apply it in backend/app.ts at the step where it belongs, and add a comment with its place in the order:
app.use('*', myMiddleware); // every request
api.use('*', myMiddleware); // protected routes only, after requireAuth
Middleware for one route goes in the route's controller.createHandlers(...) call, before the handler. Update this file, REQUEST_PIPELINE.md and HONO.md when the stack changes.