@qelos/integrator-nuxt 4.0.0 → 4.0.1

package/README.md

@@ -1,14 +1,10 @@
 # @qelos/integrator-nuxt
 
-Nuxt 3 integrator for [Qelos](https://qelos.io). Adds a server middleware that
-identifies the current user and active workspace via the
-[`@qelos/sdk`](https://www.npmjs.com/package/@qelos/sdk) before your own
-Nitro/Nuxt route handlers run, and exposes them through the H3 event context.
-
-A token-refresh hook keeps the access token fresh: when the SDK detects an
-expired access token, it transparently refreshes it — either through the
-request's refresh token or, for cookie-only sessions, through the access
-cookie itself — and writes the rotated cookie pair back on the response.
+Nuxt 3 integrator for [Qelos](https://qelos.io). It plugs into a Nuxt app's
+Nitro server to make the Nuxt host act as a same-origin BFF for a managed
+Qelos app: requests under `/api/**` are proxied to Qelos, and every other
+request resolves the current user up front so your route handlers and Vue
+components can use them directly.
 
 ## Install
 
@@ -16,6 +12,10 @@ cookie itself — and writes the rotated cookie pair back on the response.
 pnpm add @qelos/integrator-nuxt
 ```
 
+> Requires Node 18+ — the middleware uses
+> [`Response.headers.getSetCookie()`](https://developer.mozilla.org/docs/Web/API/Headers/getSetCookie)
+> to pipe individual upstream `Set-Cookie` headers back to the client.
+
 ## Configure
 
 ```ts
@@ -25,8 +25,6 @@ export default defineNuxtConfig({
   qelos: {
     appUrl: 'https://your-qelos-app.com',
     // Optional — defaults shown:
-    accessTokenCookie: 'q_access_token',
-    refreshTokenCookie: 'q_refresh_token',
     requireAuth: false,
     skipPaths: ['/api/_auth', '/health'],
   },
@@ -36,6 +34,83 @@ export default defineNuxtConfig({
 You can also override any field at runtime via `NUXT_QELOS_*` env vars (Nuxt
 runtime-config conventions apply).
 
+## API proxy
+
+The module registers a catch-all `/api/**` Nitro server handler that
+transparently proxies any request the consuming Nuxt app does not handle
+itself to the configured Qelos managed-app origin. This lets the Nuxt app
+act as a same-origin BFF: `@qelos/sdk` calls from the browser, server, or
+the Qelos web SDK can all hit `/api/...` on the Nuxt host and reach Qelos
+without CORS or cross-site cookie pain.
+
+User-defined `server/api/*.ts` (and `server/routes/*.ts`) routes still
+take precedence — the proxy only catches requests no other handler matched.
+
+### Cookie domain rewrite
+
+The proxy forwards the incoming `Cookie` header as-is (the Qelos session
+cookie name is treated as opaque) and forwards upstream `Set-Cookie`
+headers back to the client, rewriting the `Domain=` attribute on every
+upstream cookie to the inbound request's own host. That way the session
+cookie set by Qelos is valid on the Nuxt app's domain regardless of which
+host Qelos issues cookies from.
+
+### Resolving the proxy target
+
+The managed Qelos app URL (`qelos.appUrl`) is the proxy target. Env vars are
+only dev-time overrides for when the configured `appUrl` isn't reachable from
+the local host:
+
+1. `NUXT_QELOS_PROXY_TARGET` env var.
+2. `QELOS_IP` env var (dev fallback).
+3. `QELOS_API_IP` env var (dev fallback).
+4. `qelos.appUrl`.
+
+If none of these are set, the handler responds with `503` so misconfiguration
+fails loudly.
+
+### Opting out
+
+Set `qelos.disableProxy: true` in `nuxt.config.ts` to skip registration of
+the proxy handler — useful when the Nuxt app implements every `/api/*`
+route itself or terminates the proxy elsewhere (CDN, reverse proxy, etc.).
+
+WebSocket upgrades are not proxied; route them explicitly if needed.
+
+## Middleware
+
+On every non-`/api/` request, the server middleware identifies the current
+user by calling the managed Qelos app directly:
+
+1. Resolve the upstream origin the same way the `/api/**` proxy does
+   (`NUXT_QELOS_PROXY_TARGET` → `QELOS_IP` → `QELOS_API_IP` →
+   `qelos.appUrl`).
+2. Issue `fetch('${upstream}/api/me')` with the incoming request's `Cookie`
+   header forwarded verbatim — the Qelos session cookie name is opaque to
+   the integrator, so the whole header is piped through unchanged. Any
+   incoming `Authorization` header is forwarded too.
+3. For every `Set-Cookie` header on the upstream response, rewrite the
+   `Domain=` attribute to the inbound request's `Host` (port stripped) and
+   append it to the outgoing response. This is how session rotations from
+   Qelos reach the browser when the managed app and the Nuxt host live on
+   different origins.
+4. On `2xx`, parse the JSON body and expose it as
+   `event.context.qelos.user`. On any other status (or a network error),
+   leave `user = null` — and respond with `401` if `qelos.requireAuth` is
+   set.
+
+The middleware is independent from the `/api/**` proxy: the proxy handles
+forwarding of API calls themselves, while the middleware identifies the
+user on every page/non-API request before your route handlers run. To
+avoid double-hitting Qelos for `/api/me` (once for proxying, once for user
+resolution), the module adds `/api/` to `skipPaths` automatically when the
+proxy is enabled.
+
+> The middleware does not attempt to strip the `Secure` attribute from
+> rotated cookies. In local dev over plain HTTP, browsers will drop
+> `Secure` cookies — configure the managed Qelos app to issue non-`Secure`
+> cookies in that environment, or run the Nuxt host over HTTPS.
+
 ## Use in server routes
 
 The recommended wrapper, `defineQelosEventHandler`, gives you a typed `qelos`
@@ -76,13 +151,16 @@ export default defineEventHandler((event) => {
 
 `event.context.qelos` is typed as `QelosRequestContext`:
 
-| field        | description                                                |
-|--------------|------------------------------------------------------------|
-| `user`       | `IUser` from `@qelos/sdk` or `null` when anonymous.         |
-| `workspace`  | The active `IWorkspace` for the request, or `null`.         |
-| `workspaces` | All workspaces the user has access to.                      |
-| `sdk`        | A request-scoped `QelosSDK` instance bound to the tokens.   |
-| `tokens`     | The current access/refresh token pair (mutated on refresh). |
+| field        | description                                                      |
+|--------------|------------------------------------------------------------------|
+| `user`       | The `IUser` body returned by `/api/me`, or `null` when anonymous. |
+| `workspace`  | The active `IWorkspace` for the request, or `null`.               |
+| `workspaces` | All workspaces the user has access to.                            |
+| `sdk`        | A request-scoped `QelosSDK` instance bound to the live cookies.   |
+
+The `sdk` reads cookies from the current `H3Event` on every call, so any
+session rotation piped through by the middleware is picked up automatically
+by subsequent SDK requests in the same handler.
 
 ## Use in components / pages
 
@@ -104,7 +182,7 @@ const { user, workspace, workspaces, isAuthenticated } = useQelos();
 ```
 
 For data calls from the browser, prefer hitting your own server routes (so
-refresh-token rotation stays on the server):
+session cookies stay on the server):
 
 ```vue
 <script setup lang="ts">
@@ -117,41 +195,18 @@ If you need direct browser access to the Qelos API, use
 server-side SDK in this package is bound to per-request cookies and isn't
 intended for client use.
 
-## Token refresh
-
-When the access token is rejected, the SDK tries to recover, in order:
+## Workspace resolution
 
-1. The **refresh token** (`q_refresh_token`) via
-   `sdk.authentication.refreshToken()` — issues a new access + refresh pair.
-2. The **cookie token** (the access token cookie itself) via
-   `sdk.authentication.refreshCookieToken()` — used for cookie-only sessions
-   that do not carry a separate refresh token (e.g. social-auth flows).
+`event.context.qelos.workspace` defaults to whatever the managed Qelos app
+reports on `user.workspace` from `/api/me`. That field is non-null only when
+the user has already activated a workspace on the Qelos side; when it is
+`null`, the frontend is expected to prompt the user to either activate an
+existing workspace or create a new one. The middleware deliberately does
+**not** auto-pick `workspaces[0]` — that would silently put the user into
+the wrong workspace.
 
-After a successful refresh the middleware fires the `onTokenRefresh` hook.
-The default implementation writes the new tokens back to the response cookies
-(`HttpOnly`, `SameSite=Lax`).
-
-### Manual cookie refresh
-
-Long-lived integrator-hosted sessions can also call the SDK directly to
-proactively refresh the cookie token, e.g. from a Nitro route handler:
-
-```ts
-// server/api/session/refresh.post.ts
-import { defineQelosEventHandler } from '@qelos/integrator-nuxt';
-
-export default defineQelosEventHandler(async ({ qelos }) => {
-  const result = await qelos.sdk.authentication.refreshCookieToken();
-  // result.headers['set-cookie'] — fresh cookie value to forward
-  return { user: result.payload.user };
-});
-```
-
-## Custom workspace resolution / refresh hook
-
-If the default behavior (first workspace from `sdk.workspaces.getList()` and a
-cookie-based refresh writeback) doesn't fit your app, register your own
-middleware instead of (or in addition to) the module's default handler:
+To override the default (e.g. force a particular workspace per request),
+register your own middleware:
 
 ```ts
 // server/middleware/qelos.ts
@@ -160,12 +215,9 @@ import { createQelosMiddleware } from '@qelos/integrator-nuxt';
 export default createQelosMiddleware({
   config: useRuntimeConfig().qelos,
   resolveWorkspace: ({ user, workspaces }) =>
-    workspaces.find(w => w._id === user.metadata?.activeWorkspace) || workspaces[0] || null,
-  onTokenRefresh: async ({ event, newTokens }) => {
-    // your own persistence — DB, signed cookie, KV, etc.
-    setCookie(event, 'q_access_token', newTokens.accessToken, { httpOnly: true });
-    setCookie(event, 'q_refresh_token', newTokens.refreshToken, { httpOnly: true });
-  },
+    workspaces.find(w => w._id === user.metadata?.activeWorkspace)
+      || user.workspace
+      || null,
 });
 ```
 
@@ -175,7 +227,8 @@ in `nuxt.config.ts`.
 ## API token mode
 
 For service-to-service deployments where every request shares one Qelos API
-token, set `apiToken` and the middleware will skip the cookie/refresh flow:
+token, set `apiToken` and the middleware will skip the cookie flow entirely
+and build an SDK that authenticates with the static token:
 
 ```ts
 qelos: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qelos/integrator-nuxt",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "type": "module",
   "description": "Nuxt integrator for Qelos: server middleware/module that identifies the user and workspace from the Qelos SDK before your handlers run.",
   "main": "./dist/module.js",

package/src/cookies.test.ts

@@ -0,0 +1,112 @@
+// Run with: `tsx --test integrators/nuxt/src/cookies.test.ts`
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { rewriteSetCookieDomain, rewriteSetCookieDomains } from './cookies';
+
+describe('rewriteSetCookieDomain', () => {
+  it('replaces a leading-dot Domain value', () => {
+    const input = 'sid=abc; Path=/; Domain=.qelos.app; HttpOnly; Secure';
+    assert.equal(
+      rewriteSetCookieDomain(input, 'example.com'),
+      'sid=abc; Path=/; Domain=example.com; HttpOnly; Secure',
+    );
+  });
+
+  it('replaces a wildcard Domain value', () => {
+    const input = 'sid=abc; Path=/; Domain=*.qelos.app; HttpOnly';
+    assert.equal(
+      rewriteSetCookieDomain(input, 'example.com'),
+      'sid=abc; Path=/; Domain=example.com; HttpOnly',
+    );
+  });
+
+  it('returns the cookie unchanged when no Domain attribute is present', () => {
+    const input = 'sid=abc; Path=/; HttpOnly; Secure; SameSite=Lax';
+    assert.equal(rewriteSetCookieDomain(input, 'example.com'), input);
+  });
+
+  it('strips the port from a host:port newDomain before substitution', () => {
+    const input = 'sid=abc; Domain=.qelos.app; Path=/';
+    assert.equal(
+      rewriteSetCookieDomain(input, 'localhost:3000'),
+      'sid=abc; Domain=localhost; Path=/',
+    );
+  });
+
+  it('preserves attribute order and other attributes across replacement', () => {
+    const input =
+      'sid=abc; Path=/; Domain=.qelos.app; HttpOnly; Secure; SameSite=Lax; Max-Age=3600';
+    assert.equal(
+      rewriteSetCookieDomain(input, 'example.com'),
+      'sid=abc; Path=/; Domain=example.com; HttpOnly; Secure; SameSite=Lax; Max-Age=3600',
+    );
+  });
+
+  it('preserves an Expires attribute (which contains commas) across replacement', () => {
+    const input =
+      'sid=abc; Domain=.qelos.app; Expires=Wed, 21 Oct 2026 07:28:00 GMT; Path=/';
+    assert.equal(
+      rewriteSetCookieDomain(input, 'example.com'),
+      'sid=abc; Domain=example.com; Expires=Wed, 21 Oct 2026 07:28:00 GMT; Path=/',
+    );
+  });
+
+  it('matches the Domain attribute name case-insensitively and preserves its casing', () => {
+    const input = 'sid=abc; domain=.qelos.app; Path=/';
+    assert.equal(
+      rewriteSetCookieDomain(input, 'example.com'),
+      'sid=abc; domain=example.com; Path=/',
+    );
+  });
+
+  it('strips the entire Domain segment when newDomain is undefined', () => {
+    const input =
+      'sid=abc; Path=/; Domain=.qelos.app; HttpOnly; Secure; SameSite=Lax';
+    assert.equal(
+      rewriteSetCookieDomain(input, undefined),
+      'sid=abc; Path=/; HttpOnly; Secure; SameSite=Lax',
+    );
+  });
+
+  it('strips the entire Domain segment when newDomain is an empty string', () => {
+    const input = 'sid=abc; Domain=.qelos.app; Path=/';
+    assert.equal(
+      rewriteSetCookieDomain(input, ''),
+      'sid=abc; Path=/',
+    );
+  });
+
+  it('removes the Domain segment when it is the last attribute', () => {
+    const input = 'sid=abc; Path=/; Domain=.qelos.app';
+    assert.equal(
+      rewriteSetCookieDomain(input, undefined),
+      'sid=abc; Path=/',
+    );
+  });
+});
+
+describe('rewriteSetCookieDomains', () => {
+  it('applies the rewrite to each entry of an array', () => {
+    const values = [
+      'a=1; Domain=.qelos.app; Path=/',
+      'b=2; Path=/; HttpOnly',
+      'c=3; Domain=*.qelos.app; Secure',
+    ];
+    assert.deepEqual(rewriteSetCookieDomains(values, 'example.com'), [
+      'a=1; Domain=example.com; Path=/',
+      'b=2; Path=/; HttpOnly',
+      'c=3; Domain=example.com; Secure',
+    ]);
+  });
+
+  it('strips the Domain segment from each entry when newDomain is undefined', () => {
+    const values = [
+      'a=1; Domain=.qelos.app; Path=/',
+      'b=2; Domain=*.qelos.app; HttpOnly',
+    ];
+    assert.deepEqual(rewriteSetCookieDomains(values, undefined), [
+      'a=1; Path=/',
+      'b=2; HttpOnly',
+    ]);
+  });
+});

package/src/cookies.ts

@@ -0,0 +1,49 @@
+/**
+ * Rewrite the `Domain=` attribute of a single `Set-Cookie` header value.
+ *
+ * - If the cookie contains a `Domain=<value>` attribute (case-insensitive), its
+ *   value is replaced with `newDomain`, with any trailing `:port` suffix
+ *   stripped first (cookie `Domain` attributes do not include a port).
+ * - If `newDomain` is `undefined` (or empty), the entire `; Domain=<value>`
+ *   segment is removed so the browser scopes the cookie to the current host.
+ * - If no `Domain=` attribute is present, the input is returned unchanged.
+ *
+ * All other attributes, their casing/order and the original cookie name/value
+ * bytes are preserved.
+ */
+export function rewriteSetCookieDomain(
+  setCookie: string,
+  newDomain: string | undefined,
+): string {
+  const domainSegment = /;\s*Domain\s*=\s*[^;]+/i;
+  if (!domainSegment.test(setCookie)) return setCookie;
+
+  const stripped = newDomain ? stripPort(newDomain) : '';
+  if (!stripped) {
+    return setCookie.replace(domainSegment, '');
+  }
+  return setCookie.replace(
+    /(;\s*Domain\s*=\s*)[^;]+/i,
+    `$1${stripped}`,
+  );
+}
+
+/**
+ * Apply {@link rewriteSetCookieDomain} to each entry of a `Set-Cookie` array
+ * (e.g. the result of `Headers.getSetCookie()`).
+ */
+export function rewriteSetCookieDomains(
+  values: string[],
+  newDomain: string | undefined,
+): string[] {
+  return values.map((value) => rewriteSetCookieDomain(value, newDomain));
+}
+
+function stripPort(host: string): string {
+  if (host.startsWith('[')) {
+    const end = host.indexOf(']');
+    return end === -1 ? host : host.slice(1, end);
+  }
+  const colon = host.indexOf(':');
+  return colon === -1 ? host : host.slice(0, colon);
+}

package/src/middleware.ts

@@ -1,34 +1,23 @@
 import {
+  appendResponseHeader,
+  createError,
   defineEventHandler,
-  getCookie,
   getRequestHeader,
-  setCookie,
-  createError,
   type H3Event,
 } from 'h3';
 import type { IUser } from '@qelos/sdk/dist/authentication';
 import type { IWorkspace } from '@qelos/sdk/workspaces';
+import { rewriteSetCookieDomain } from './cookies';
+import { resolveQelosProxyTarget } from './proxy-target';
 import { createRequestSdk } from './sdk-factory';
-import type {
-  QelosNuxtRuntimeConfig,
-  QelosRequestContext,
-  QelosTokenPair,
-  TokenRefreshHook,
-} from './types';
-
-const DEFAULT_ACCESS_COOKIE = 'q_access_token';
-const DEFAULT_REFRESH_COOKIE = 'q_refresh_token';
+import type { QelosNuxtRuntimeConfig, QelosRequestContext } from './types';
 
 export interface CreateMiddlewareOptions {
   config: QelosNuxtRuntimeConfig;
   /**
-   * Hook invoked after a successful token refresh. The default implementation
-   * writes the new tokens back to the response cookies.
-   */
-  onTokenRefresh?: TokenRefreshHook;
-  /**
-   * Resolve the active workspace for a request. Defaults to picking the first
-   * workspace returned from `sdk.workspaces.getList()`.
+   * Resolve the active workspace for a request. Defaults to whatever
+   * `/api/me` reports on `user.workspace` (the user's currently activated
+   * workspace, or `null` when none is active).
    */
   resolveWorkspace?: (params: {
     event: H3Event;
@@ -37,43 +26,6 @@ export interface CreateMiddlewareOptions {
   }) => IWorkspace | null | Promise<IWorkspace | null>;
 }
 
-function readTokens(event: H3Event, config: QelosNuxtRuntimeConfig): QelosTokenPair {
-  const accessCookie = config.accessTokenCookie || DEFAULT_ACCESS_COOKIE;
-  const refreshCookie = config.refreshTokenCookie || DEFAULT_REFRESH_COOKIE;
-
-  const cookieAccess = getCookie(event, accessCookie);
-  const cookieRefresh = getCookie(event, refreshCookie);
-
-  const authHeader = getRequestHeader(event, 'authorization');
-  const headerAccess = authHeader && authHeader.toLowerCase().startsWith('bearer ')
-    ? authHeader.slice(7).trim()
-    : undefined;
-
-  return {
-    accessToken: headerAccess || cookieAccess || undefined,
-    refreshToken: cookieRefresh || undefined,
-  };
-}
-
-function writeTokensToCookies(
-  event: H3Event,
-  config: QelosNuxtRuntimeConfig,
-  tokens: { accessToken: string; refreshToken?: string },
-) {
-  const accessCookie = config.accessTokenCookie || DEFAULT_ACCESS_COOKIE;
-  const refreshCookie = config.refreshTokenCookie || DEFAULT_REFRESH_COOKIE;
-  const cookieOptions = {
-    httpOnly: true,
-    secure: true,
-    sameSite: 'lax' as const,
-    path: '/',
-  };
-  setCookie(event, accessCookie, tokens.accessToken, cookieOptions);
-  if (tokens.refreshToken) {
-    setCookie(event, refreshCookie, tokens.refreshToken, cookieOptions);
-  }
-}
-
 function shouldSkip(event: H3Event, config: QelosNuxtRuntimeConfig): boolean {
   if (!config.skipPaths?.length) {
     return false;
@@ -82,41 +34,74 @@ function shouldSkip(event: H3Event, config: QelosNuxtRuntimeConfig): boolean {
   return config.skipPaths.some((prefix) => path.startsWith(prefix));
 }
 
+function buildMeUrl(base: string): string {
+  return `${base.replace(/\/+$/, '')}/api/me`;
+}
+
 export function createQelosMiddleware(options: CreateMiddlewareOptions) {
   const { config, resolveWorkspace } = options;
-  const onTokenRefresh: TokenRefreshHook = options.onTokenRefresh
-    || (async ({ event, newTokens }) => {
-      writeTokensToCookies(event, config, newTokens);
-    });
 
   return defineEventHandler(async (event) => {
     if (shouldSkip(event, config)) {
       return;
     }
 
-    const tokens = readTokens(event, config);
-    const sdk = createRequestSdk({ config, tokens, event, onTokenRefresh });
+    const sdk = createRequestSdk({ config, event });
 
     const ctx: QelosRequestContext = {
       user: null,
       workspace: null,
       workspaces: [],
       sdk,
-      tokens,
     };
     event.context.qelos = ctx;
 
-    const hasAuthMaterial = Boolean(config.apiToken || tokens.accessToken || tokens.refreshToken);
-    if (!hasAuthMaterial) {
+    const base = resolveQelosProxyTarget(config);
+    if (!base && !config.apiToken) {
       if (config.requireAuth) {
         throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
       }
       return;
     }
 
-    try {
-      ctx.user = await sdk.authentication.getLoggedInUser();
-    } catch (err) {
+    if (base) {
+      const headers: Record<string, string> = {};
+      const cookieHeader = getRequestHeader(event, 'cookie');
+      if (cookieHeader) headers.cookie = cookieHeader;
+      const authHeader = getRequestHeader(event, 'authorization');
+      if (authHeader) headers.authorization = authHeader;
+
+      const originalHost = getRequestHeader(event, 'host');
+
+      let response: Response | undefined;
+      try {
+        response = await fetch(buildMeUrl(base), {
+          method: 'GET',
+          headers,
+          redirect: 'manual',
+        });
+      } catch {
+        if (config.requireAuth) {
+          throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
+        }
+        return;
+      }
+
+      const setCookieValues = response.headers.getSetCookie?.() ?? [];
+      for (const value of setCookieValues) {
+        appendResponseHeader(event, 'set-cookie', rewriteSetCookieDomain(value, originalHost));
+      }
+
+      if (response.ok) {
+        try {
+          ctx.user = (await response.json()) as IUser;
+        } catch {
+          ctx.user = null;
+        }
+      }
+    }
+
+    if (!ctx.user) {
       if (config.requireAuth) {
         throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
       }
@@ -129,16 +114,18 @@ export function createQelosMiddleware(options: CreateMiddlewareOptions) {
       ctx.workspaces = [];
     }
 
-    if (ctx.user && ctx.workspaces.length) {
-      if (resolveWorkspace) {
-        ctx.workspace = await resolveWorkspace({
-          event,
-          user: ctx.user,
-          workspaces: ctx.workspaces,
-        }) || null;
-      } else {
-        ctx.workspace = ctx.workspaces[0] || null;
-      }
+    if (resolveWorkspace) {
+      ctx.workspace = (await resolveWorkspace({
+        event,
+        user: ctx.user,
+        workspaces: ctx.workspaces,
+      })) || null;
+    } else {
+      // `/api/me` carries `user.workspace` (`{ _id, name, roles }`) only when
+      // the user has activated a workspace. Null means the frontend must
+      // prompt to activate/create one — don't silently pick workspaces[0].
+      ctx.workspace =
+        (ctx.user as unknown as { workspace?: IWorkspace | null }).workspace || null;
     }
   });
 }

package/src/module.ts

@@ -13,6 +13,11 @@ export interface QelosNuxtModuleOptions extends QelosNuxtRuntimeConfig {
    * want to call `createQelosMiddleware` yourself from your own server route.
    */
   disableMiddleware?: boolean;
+  /**
+   * Disable registration of the catch-all `/api/**` proxy server handler.
+   * Defaults to `false`.
+   */
+  disableProxy?: boolean;
 }
 
 export default defineNuxtModule<QelosNuxtModuleOptions>({
@@ -33,7 +38,22 @@ export default defineNuxtModule<QelosNuxtModuleOptions>({
 
     const { resolve } = createResolver(import.meta.url);
 
-    const { disableMiddleware, ...runtimeConfig } = options;
+    const { disableMiddleware, disableProxy, ...runtimeConfig } = options;
+
+    if (!disableProxy) {
+      // When the catch-all `/api/**` proxy is enabled, the user-resolution
+      // middleware MUST skip `/api/` requests. The middleware itself calls
+      // `${appUrl}/api/me` to identify the user, so without this skip
+      // every inbound `/api/me` would be both proxied AND used as the
+      // identification probe — a duplicate upstream hit and a potential
+      // cookie-rewrite loop. Users can extend `skipPaths` further but
+      // `/api/` must remain covered whenever `disableProxy` is false.
+      const existingSkipPaths = runtimeConfig.skipPaths ?? [];
+      const alreadyCovered = existingSkipPaths.some((prefix) => '/api/'.startsWith(prefix));
+      if (!alreadyCovered) {
+        runtimeConfig.skipPaths = ['/api/', ...existingSkipPaths];
+      }
+    }
 
     nuxt.options.runtimeConfig.qelos = {
       ...(nuxt.options.runtimeConfig.qelos as Record<string, unknown> | undefined),
@@ -47,6 +67,13 @@ export default defineNuxtModule<QelosNuxtModuleOptions>({
       });
     }
 
+    if (!disableProxy) {
+      addServerHandler({
+        route: '/api/**',
+        handler: resolve('./runtime/api-proxy'),
+      });
+    }
+
     addImportsDir(resolve('./runtime/composables'));
 
     addTypeTemplate({
@@ -77,8 +104,4 @@ export type {
 export type {
   QelosNuxtRuntimeConfig,
   QelosRequestContext,
-  QelosTokenPair,
-  ResolvedTokens,
-  TokenRefreshContext,
-  TokenRefreshHook,
 } from './types';

package/src/proxy-target.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveQelosProxyTarget } from './proxy-target';
+import type { QelosNuxtRuntimeConfig } from './types';
+
+const PROXY_ENV_KEYS = [
+  'NUXT_QELOS_PROXY_TARGET',
+  'QELOS_IP',
+  'QELOS_API_IP',
+] as const;
+
+function clearProxyEnv(): void {
+  for (const key of PROXY_ENV_KEYS) {
+    delete process.env[key];
+  }
+}
+
+describe('resolveQelosProxyTarget', () => {
+  const savedEnv: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    for (const key of PROXY_ENV_KEYS) {
+      savedEnv[key] = process.env[key];
+    }
+    clearProxyEnv();
+  });
+
+  afterEach(() => {
+    for (const key of PROXY_ENV_KEYS) {
+      if (savedEnv[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = savedEnv[key];
+      }
+    }
+  });
+
+  it('uses NUXT_QELOS_PROXY_TARGET when set, even if other env vars and appUrl exist', () => {
+    process.env.NUXT_QELOS_PROXY_TARGET = 'https://from-nuxt-env.example';
+    process.env.QELOS_IP = 'https://from-qelos-ip.example';
+    process.env.QELOS_API_IP = 'https://from-qelos-api-ip.example';
+    const config: QelosNuxtRuntimeConfig = {
+      appUrl: 'https://from-app-url.example',
+    };
+    assert.equal(
+      resolveQelosProxyTarget(config),
+      'https://from-nuxt-env.example',
+    );
+  });
+
+  it('falls back to QELOS_IP when NUXT_QELOS_PROXY_TARGET is unset', () => {
+    process.env.QELOS_IP = 'https://from-qelos-ip.example';
+    process.env.QELOS_API_IP = 'https://from-qelos-api-ip.example';
+    const config: QelosNuxtRuntimeConfig = {
+      appUrl: 'https://from-app-url.example',
+    };
+    assert.equal(
+      resolveQelosProxyTarget(config),
+      'https://from-qelos-ip.example',
+    );
+  });
+
+  it('falls back to QELOS_API_IP when higher-priority env vars are unset', () => {
+    process.env.QELOS_API_IP = 'https://from-qelos-api-ip.example';
+    const config: QelosNuxtRuntimeConfig = {
+      appUrl: 'https://from-app-url.example',
+    };
+    assert.equal(
+      resolveQelosProxyTarget(config),
+      'https://from-qelos-api-ip.example',
+    );
+  });
+
+  it('falls back to config.appUrl when no env var is set', () => {
+    const config: QelosNuxtRuntimeConfig = {
+      appUrl: 'https://from-app-url.example',
+    };
+    assert.equal(
+      resolveQelosProxyTarget(config),
+      'https://from-app-url.example',
+    );
+  });
+
+  it('returns undefined when nothing is configured', () => {
+    const config: QelosNuxtRuntimeConfig = { appUrl: '' };
+    assert.equal(resolveQelosProxyTarget(config), undefined);
+  });
+
+  it('treats whitespace-only values as unset', () => {
+    process.env.NUXT_QELOS_PROXY_TARGET = '   ';
+    process.env.QELOS_IP = '\t';
+    const config: QelosNuxtRuntimeConfig = {
+      appUrl: 'https://from-app-url.example',
+    };
+    assert.equal(
+      resolveQelosProxyTarget(config),
+      'https://from-app-url.example',
+    );
+  });
+
+  it('trims surrounding whitespace from resolved values', () => {
+    const config: QelosNuxtRuntimeConfig = {
+      appUrl: '  https://trimmed.example  ',
+    };
+    assert.equal(
+      resolveQelosProxyTarget(config),
+      'https://trimmed.example',
+    );
+  });
+});

package/src/proxy-target.ts

@@ -0,0 +1,30 @@
+import type { QelosNuxtRuntimeConfig } from './types';
+
+/**
+ * Resolve the origin to which `/api/**` requests are proxied. The managed
+ * Qelos app URL (`config.appUrl`) is the proxy target — env vars are only
+ * dev-time overrides when the configured `appUrl` is not reachable from
+ * the local host.
+ *
+ * Priority (highest first):
+ *   1. `process.env.NUXT_QELOS_PROXY_TARGET`
+ *   2. `process.env.QELOS_IP`
+ *   3. `process.env.QELOS_API_IP`
+ *   4. `config.appUrl`
+ *
+ * Empty / whitespace-only values are skipped, and `undefined` is returned when
+ * nothing is configured so the caller can surface a clear error.
+ */
+export function resolveQelosProxyTarget(
+  config: QelosNuxtRuntimeConfig,
+): string | undefined {
+  const env = process.env;
+  const fromEnv =
+    env.NUXT_QELOS_PROXY_TARGET?.trim() ||
+    env.QELOS_IP?.trim() ||
+    env.QELOS_API_IP?.trim();
+  if (fromEnv) return fromEnv;
+
+  const fromAppUrl = config.appUrl?.trim();
+  return fromAppUrl || undefined;
+}

package/src/runtime/api-proxy.ts

@@ -0,0 +1,36 @@
+// This file is registered as a Nuxt server handler by `module.ts`. It is
+// bundled by Nitro, so `#imports` resolves at the consuming-app build time
+// (not at this package's `tsc` build).
+// @ts-ignore - resolved by Nitro
+import { useRuntimeConfig } from '#imports';
+import {
+  createError,
+  defineEventHandler,
+  getRequestHeader,
+  proxyRequest,
+} from 'h3';
+// @ts-ignore - resolved by Nitro (transitive dep of Nuxt)
+import { joinURL } from 'ufo';
+import { resolveQelosProxyTarget } from '../proxy-target';
+import type { QelosNuxtRuntimeConfig } from '../types';
+
+export default defineEventHandler((event) => {
+  const config = (useRuntimeConfig().qelos || {}) as QelosNuxtRuntimeConfig;
+  const base = resolveQelosProxyTarget(config);
+  if (!base) {
+    throw createError({
+      statusCode: 503,
+      statusMessage:
+        '[@qelos/integrator-nuxt] Qelos API proxy is not configured. Set qelos.appUrl (or NUXT_QELOS_PROXY_TARGET / QELOS_IP / QELOS_API_IP in development).',
+    });
+  }
+
+  const originalHost = getRequestHeader(event, 'host');
+  const path = event.path.split('?')[0] ?? event.path;
+  const target = joinURL(base, path);
+
+  return proxyRequest(event, target, {
+    fetch: globalThis.fetch,
+    cookieDomainRewrite: { '*': originalHost ?? '' },
+  });
+});

package/src/sdk-factory.ts

@@ -1,111 +1,39 @@
 import QelosSDK from '@qelos/sdk';
 import type { QelosSDKOptions, FetchLike } from '@qelos/sdk/types';
-import type {
-  QelosNuxtRuntimeConfig,
-  QelosTokenPair,
-  ResolvedTokens,
-  TokenRefreshHook,
-} from './types';
-import type { H3Event } from 'h3';
+import { getRequestHeader, type H3Event } from 'h3';
+import type { QelosNuxtRuntimeConfig } from './types';
 
 export interface CreateSdkParams {
   config: QelosNuxtRuntimeConfig;
-  /**
-   * Tokens for the current request. The factory mutates this object in
-   * place when a token refresh occurs, so callers can read the latest pair
-   * after the SDK has been used.
-   */
-  tokens: QelosTokenPair;
   event: H3Event;
-  onTokenRefresh?: TokenRefreshHook;
 }
 
-const NO_AUTH_URLS = new Set([
-  '/api/token/refresh',
-  '/api/cookie/refresh',
-  '/api/signin',
-  '/api/signup',
-]);
-
-export function createRequestSdk({ config, tokens, event, onTokenRefresh }: CreateSdkParams): QelosSDK {
-  let sdk: QelosSDK;
-  let refreshInFlight: Promise<void> | null = null;
-
+export function createRequestSdk({ config, event }: CreateSdkParams): QelosSDK {
   const baseOptions: Partial<QelosSDKOptions> = config.sdkOptions || {};
 
-  async function performRefresh(): Promise<void> {
-    if (!tokens.refreshToken && !tokens.accessToken) {
-      throw new Error('no refresh token available');
-    }
-    const previous: QelosTokenPair = {
-      accessToken: tokens.accessToken,
-      refreshToken: tokens.refreshToken,
-    };
-    let refreshed: ResolvedTokens;
-    if (tokens.refreshToken) {
-      const result = await sdk.authentication.refreshToken(tokens.refreshToken);
-      refreshed = {
-        accessToken: result.payload.token,
-        refreshToken: result.payload.refreshToken,
-      };
-    } else {
-      const result = await sdk.authentication.refreshCookieToken(tokens.accessToken);
-      refreshed = {
-        accessToken: result.payload.cookieToken,
-      };
-    }
-    tokens.accessToken = refreshed.accessToken;
-    tokens.refreshToken = refreshed.refreshToken;
-    if (onTokenRefresh) {
-      await onTokenRefresh({ event, oldTokens: previous, newTokens: refreshed, sdk });
-    }
-  }
-
-  function ensureRefresh(): Promise<void> {
-    if (!refreshInFlight) {
-      refreshInFlight = performRefresh().finally(() => {
-        refreshInFlight = null;
-      });
-    }
-    return refreshInFlight;
-  }
-
   const options: QelosSDKOptions = {
     appUrl: config.appUrl,
     fetch: (globalThis.fetch as unknown as FetchLike),
-    forceRefresh: !config.apiToken,
     ...baseOptions,
   };
 
   if (config.apiToken) {
     options.apiToken = config.apiToken;
-  } else {
-    if (tokens.accessToken) {
-      options.accessToken = tokens.accessToken;
+    return new QelosSDK(options);
+  }
+
+  options.extraHeaders = async () => {
+    const headers: Record<string, string> = {};
+    const cookieHeader = getRequestHeader(event, 'cookie');
+    if (cookieHeader) {
+      headers.cookie = cookieHeader;
     }
-    if (tokens.refreshToken) {
-      options.refreshToken = tokens.refreshToken;
+    const authHeader = getRequestHeader(event, 'authorization');
+    if (authHeader) {
+      headers.authorization = authHeader;
     }
+    return headers;
+  };
 
-    options.extraHeaders = async (relativeUrl: string, forceRefresh?: boolean) => {
-      if (NO_AUTH_URLS.has(relativeUrl)) {
-        return {};
-      }
-      if (forceRefresh && tokens.refreshToken) {
-        await ensureRefresh();
-      }
-      const token = sdk?.authentication?.accessToken || tokens.accessToken;
-      if (token) {
-        return { authorization: 'Bearer ' + token };
-      }
-      return {};
-    };
-
-    options.onFailedRefreshToken = async () => {
-      await ensureRefresh();
-    };
-  }
-
-  sdk = new QelosSDK(options);
-  return sdk;
+  return new QelosSDK(options);
 }

package/src/types.ts

@@ -3,11 +3,6 @@ import type { IUser } from '@qelos/sdk/dist/authentication';
 import type { IWorkspace } from '@qelos/sdk/workspaces';
 import type { QelosSDKOptions } from '@qelos/sdk/types';
 
-export interface QelosTokenPair {
-  accessToken?: string;
-  refreshToken?: string;
-}
-
 export interface QelosNuxtRuntimeConfig {
   /**
    * Base URL of the Qelos backend (e.g. https://yourdomain.com).
@@ -15,17 +10,9 @@ export interface QelosNuxtRuntimeConfig {
   appUrl: string;
   /**
    * Static API token used for service-to-service calls. When provided, no
-   * cookie/refresh-token handling is performed.
+   * cookie-based authentication is performed.
    */
   apiToken?: string;
-  /**
-   * Cookie name carrying the Qelos access token. Defaults to `q_access_token`.
-   */
-  accessTokenCookie?: string;
-  /**
-   * Cookie name carrying the Qelos refresh token. Defaults to `q_refresh_token`.
-   */
-  refreshTokenCookie?: string;
   /**
    * Path to mount the server middleware on. Defaults to `''` (every request).
    */
@@ -44,22 +31,13 @@ export interface QelosNuxtRuntimeConfig {
    * Optional extra options merged into the per-request SDK instance.
    */
   sdkOptions?: Partial<QelosSDKOptions>;
+  /**
+   * If true, the catch-all `/api/**` proxy handler is not registered.
+   * Defaults to `false`.
+   */
+  disableProxy?: boolean;
 }
 
-export interface ResolvedTokens {
-  accessToken: string;
-  refreshToken?: string;
-}
-
-export interface TokenRefreshContext {
-  event: import('h3').H3Event;
-  oldTokens: QelosTokenPair;
-  newTokens: ResolvedTokens;
-  sdk: QelosSDK;
-}
-
-export type TokenRefreshHook = (ctx: TokenRefreshContext) => void | Promise<void>;
-
 export interface QelosRequestContext {
   /**
    * The authenticated user, or `null` when anonymous.
@@ -75,13 +53,11 @@ export interface QelosRequestContext {
    */
   workspaces: IWorkspace[];
   /**
-   * SDK instance bound to the current request's tokens.
+   * SDK instance bound to the current request's cookies. `extraHeaders`
+   * re-reads cookies live on each call, so cookie rotations applied by the
+   * middleware are picked up automatically.
    */
   sdk: QelosSDK;
-  /**
-   * Tokens read from the request. Mutated when a refresh occurs.
-   */
-  tokens: QelosTokenPair;
 }
 
 declare module 'h3' {