Advanced

Auth Middleware

The SSE endpoint is transport-agnostic — add authentication at the API route level using whatever strategy your app already uses.

Why No Built-in Auth?

Authentication strategies vary widely — session cookies, JWT tokens, API keys, OAuth. Rather than baking in one approach, query-tags lets you wrap the API handler with whatever auth middleware your app already uses.

Protecting the SSE Endpoint

Unprotected (default)

// routes/api.invalidator.$.ts
const handler = tagInvalidation.createAPIHandler({
  basePath: DEFAULT_INVALIDATOR_BASE_PATH,
});

async function handle({ request }: { request: Request }) {
  return handler(request);
}

export const Route = createFileRoute("/api/invalidator/$")({
  server: {
    handlers: {
      GET: handle,
      POST: handle,
    },
  },
});

With Auth Middleware

// routes/api.invalidator.$.ts
const handler = tagInvalidation.createAPIHandler({
  basePath: DEFAULT_INVALIDATOR_BASE_PATH,
});

async function handle({ request }: { request: Request }) {
  const session = await getSession(request);
  if (!session) {
    return new Response("Unauthorized", { status: 401 });
  }
  return handler(request);
}

export const Route = createFileRoute("/api/invalidator/$")({
  server: {
    handlers: {
      GET: handle,
      POST: handle,
    },
  },
});

Token-Based Auth

For APIs using Bearer tokens, validate the token before forwarding to the handler.

async function handle({ request }: { request: Request }) {
  const token = request.headers.get("Authorization")?.replace("Bearer ", "");
  if (!token || !await verifyToken(token)) {
    return new Response("Unauthorized", { status: 401 });
  }
  return handler(request);
}

Scope-Based Isolation

Combine auth with scoping for defense-in-depth. Each authenticated user subscribes to their own scope, ensuring they only receive invalidation events for their data.

const tagInvalidation = createTagInvalidationSystem({
  resolveScope: (ctx) => ({
    kind: "user",
    id: ctx.userId,  // Each user gets isolated events
  }),
});

Control Endpoint Protection

The control endpoints (/pause, /resume, /tags/disable) modify system behavior. In production, restrict these to admin users or internal services.

async function handle({ request }: { request: Request }) {
  const session = await getSession(request);
  if (!session?.isAdmin) {
    return new Response("Forbidden", { status: 403 });
  }
  return handler(request);
}