@qelos/integrator-nest 4.0.0 → 4.0.1

package/README.md

@@ -1,22 +1,18 @@
 # @qelos/integrator-nest
 
-NestJS module that calls the Qelos SDK to identify the current user and their
-active workspace before your route handler runs, exposing them on
-`request.qelos.user` / `request.qelos.workspace`.
+NestJS module for [Qelos](https://qelos.io). It wires global middleware so your Nest host acts as a same-origin BFF for a managed Qelos app: requests under `/api/**` are proxied to Qelos (unless you opt out), and every other request resolves the current user up front so controllers and request-scoped providers can use `request.qelos` and the `Qelos*` decorators.
 
-This is the NestJS implementation of the Qelos integrator contract — the same
-shape exposed by `@qelos/integrator-express`, `@qelos/integrator-fastify`,
-`@qelos/integrator-nuxt`, `@qelos/plugin-netlify-api`, etc. It works with
-both Nest's Express adapter and its Fastify adapter.
+Works with Nest’s **Express** and **Fastify** HTTP adapters — request/response objects are handled generically.
 
 ## Install
 
 ```sh
-npm install @qelos/integrator-nest @qelos/sdk
-# Nest is a peer dependency
-npm install @nestjs/common @nestjs/core
+pnpm add @qelos/integrator-nest @qelos/sdk
+pnpm add @nestjs/common @nestjs/core
 ```
 
+Requires **Node 18+**. The user-resolution middleware uses [`Response.headers.getSetCookie()`](https://developer.mozilla.org/docs/Web/API/Headers/getSetCookie) when probing `/api/me` so each upstream `Set-Cookie` can be forwarded individually.
+
 ## Quick start
 
 ```ts
@@ -28,7 +24,7 @@ import { QelosModule } from '@qelos/integrator-nest';
   imports: [
     QelosModule.forRoot({
       config: {
-        appUrl: process.env.QELOS_APP_URL!, // e.g. https://yourdomain.com
+        appUrl: process.env.QELOS_APP_URL!, // managed Qelos app origin
       },
     }),
   ],
@@ -36,31 +32,50 @@ import { QelosModule } from '@qelos/integrator-nest';
 export class AppModule {}
 ```
 
-`forRoot` registers `QelosMiddleware` on every route by default. To restrict
-its scope, import the module without `forRoot` and apply the middleware
-yourself in `configure`:
+`forRoot` registers:
 
-```ts
-import {
-  QelosMiddleware,
-  QelosModule,
-  type QelosModuleOptions,
-} from '@qelos/integrator-nest';
-import { type MiddlewareConsumer, Module, type NestModule } from '@nestjs/common';
+1. **`QelosMiddleware`** on `*` — resolves `request.qelos` via `/api/me` cookie pass-through (unless the path is skipped).
+2. **`QelosProxyMiddleware`** on `api/*splat` — reverse-proxies `/api/**` to the same resolved origin, unless `disableProxy: true`.
 
-const options: QelosModuleOptions = {
-  config: { appUrl: process.env.QELOS_APP_URL! },
-};
+User-defined controllers and routes still take precedence for paths they own; the proxy only handles `/api/**` traffic that reaches the middleware stack.
 
-@Module({
-  imports: [QelosModule.forRoot(options)],
-})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    consumer.apply(QelosMiddleware).forRoutes('api/*');
-  }
-}
-```
+To narrow where the **resolver** runs, import the module and apply `QelosMiddleware` yourself (see Nest docs on `MiddlewareConsumer`). You still need `QELOS_MODULE_OPTIONS` and `QelosProxyMiddleware` provided if you split registration.
+
+## API proxy
+
+The proxy forwards the inbound request (method, URL path + query, body stream, and headers except hop-by-hop) to `<proxyTarget>` + the same path. Upstream `Set-Cookie` headers are rewritten so `Domain=` matches the inbound `Host` (port stripped), making Qelos session cookies first-party on your Nest host.
+
+### Resolving the proxy target
+
+The managed app URL (`config.appUrl`) is the default target. Env vars are dev-time overrides when `appUrl` is not reachable from localhost:
+
+1. `QELOS_PROXY_TARGET`
+2. `QELOS_IP`
+3. `QELOS_API_IP`
+4. `config.appUrl`
+
+Whitespace-only env values are ignored. If nothing resolves, the proxy responds with **503**. The user resolver uses the same chain; without a target and without `apiToken`, anonymous requests are allowed unless `requireAuth` is set.
+
+### Opting out
+
+Set `disableProxy: true` in config to skip registering `QelosProxyMiddleware` — for example when you implement every `/api/*` route in Nest or terminate the proxy elsewhere.
+
+WebSocket upgrades are **not** proxied.
+
+## User-resolution middleware
+
+On non-skipped paths, the middleware:
+
+1. Builds a per-request SDK (`createRequestSdk`) — with `apiToken`, static auth; otherwise `extraHeaders` forwards the live `Cookie` and `Authorization` headers on every SDK call.
+2. Resolves the proxy target (same priority as above).
+3. If there is no target and no `apiToken`, returns anonymous context (or **401** when `requireAuth` is true).
+4. If there is a target, `GET ${target}/api/me` with cookies and authorization forwarded. Each upstream `Set-Cookie` is appended to the outgoing response with `Domain=` rewritten to the inbound host.
+5. On success, loads workspaces via `sdk.workspaces.getList()` (errors → empty list).
+6. Sets **active workspace** to `resolveWorkspace()` if provided, else `user.workspace` from `/api/me` — **not** `workspaces[0]`.
+
+When `disableProxy !== true`, `/api/` is **prepended** to `skipPaths` automatically so proxied `/api/**` traffic is not double-handled by this `/api/me` probe.
+
+> Rotated cookies may include `Secure`. Over plain HTTP, browsers may drop them — use HTTPS locally or configure Qelos for non-Secure cookies in dev.
 
 ## Use in controllers
 
@@ -79,7 +94,6 @@ import type { IWorkspace } from '@qelos/sdk/workspaces';
 @Controller()
 export class AppController {
   @Get('me')
-  // user/workspace are null when the request is anonymous
   me(
     @QelosUser() user: IUser | null,
     @QelosWorkspace() workspace: IWorkspace | null,
@@ -87,7 +101,6 @@ export class AppController {
     return { user, workspace };
   }
 
-  // Short-circuit with 401 when there is no authenticated user.
   @Get('private')
   @UseGuards(QelosAuthGuard)
   private(@QelosCtx() ctx: QelosRequestContext) {
@@ -96,71 +109,22 @@ export class AppController {
 }
 ```
 
-## What the middleware does
-
-1. Reads the access token from `Authorization: Bearer ...` or the
-   `q_access_token` cookie, and the refresh token from `q_refresh_token`.
-2. Builds a per-request Qelos SDK instance bound to those tokens.
-3. Calls `sdk.authentication.getLoggedInUser()` and
-   `sdk.workspaces.getList()`.
-4. Picks the active workspace (first by default — override with
-   `resolveWorkspace`).
-5. Attaches everything to `request.qelos`.
-
-The middleware never throws for anonymous requests by default — it just
-leaves `request.qelos.user` and `request.qelos.workspace` as `null`. Pass
-`requireAuth: true` to short-circuit anonymous requests with `401`, or use
-the per-route `QelosAuthGuard` for finer-grained control.
-
-## Token refresh
-
-When the access token is rejected, the SDK tries to recover, in order:
-
-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).
+`QelosRequestContext`:
 
-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`, `Secure` whenever `appUrl` is `https://...`).
+| field        | description |
+|--------------|-------------|
+| `user`       | `IUser` from `/api/me`, or `null`. |
+| `workspace`  | Active workspace or `null`. |
+| `workspaces` | Workspaces from `getList()`. |
+| `sdk`        | Request-scoped `QelosSDK` forwarding cookies live. |
 
-You can supply your own — for example, to mint your own session cookie or
-push the new tokens into a session store:
+## API token mode
 
-```ts
-QelosModule.forRoot({
-  config: { appUrl: process.env.QELOS_APP_URL! },
-  onTokenRefresh: async ({ request, response, newTokens }) => {
-    await sessionStore.rotate(request.session.id, newTokens);
-  },
-});
-```
-
-The hook receives `{ request, response, oldTokens, newTokens, sdk }`. The
-`request` and `response` types are intentionally generic since Nest can run
-on either Express or Fastify.
-
-### Manual cookie refresh
-
-Long-lived integrator-hosted sessions can also call the SDK directly to
-proactively refresh the cookie token:
-
-```ts
-@Get('refresh-session')
-async refresh(@QelosCtx() ctx: QelosRequestContext) {
-  const result = await ctx.sdk.authentication.refreshCookieToken();
-  // result.headers['set-cookie'] — fresh cookie value to forward
-  return { user: result.payload.user };
-}
-```
+For service-to-service traffic, set `apiToken` — the middleware skips the `/api/me` cookie flow for identity (you still get an SDK with the static token). Pair with `requireAuth` / `QelosGuard` as needed.
 
 ## Async configuration
 
 ```ts
-import { ConfigModule, ConfigService } from '@nestjs/config';
-
 QelosModule.forRootAsync({
   imports: [ConfigModule],
   inject: [ConfigService],
@@ -173,39 +137,33 @@ QelosModule.forRootAsync({
 });
 ```
 
-## Configuration
+## Configuration reference
 
 ```ts
 QelosModule.forRoot({
   config: {
-    appUrl: 'https://yourdomain.com', // required
+    appUrl: 'https://your-managed-app.com',
 
-    // Service-to-service: use a static API token instead of cookies/refresh.
     apiToken: process.env.QELOS_API_TOKEN,
 
-    // Cookie names. Defaults shown.
-    accessTokenCookie: 'q_access_token',
-    refreshTokenCookie: 'q_refresh_token',
-
-    // Reject anonymous requests with 401. Defaults to false.
     requireAuth: false,
 
-    // Skip the middleware entirely for these path prefixes.
     skipPaths: ['/health', '/metrics'],
 
-    // Anything you want passed through to the per-request SDK.
+    disableProxy: false,
+
     sdkOptions: {},
   },
 
-  // Override workspace selection. Defaults to `workspaces[0]`.
   resolveWorkspace: ({ request, user, workspaces }) => {
     const headerId = request.headers['x-qelos-workspace'];
-    return workspaces.find((w) => w._id === headerId) || workspaces[0] || null;
+    const raw = Array.isArray(headerId) ? headerId[0] : headerId;
+    return workspaces.find((w) => w._id === raw) || user.workspace || null;
   },
 });
 ```
 
 ## Requirements
 
-- Node.js >= 18 (uses the global `fetch`).
-- NestJS 9, 10, or 11.
+- Node.js >= 18  
+- NestJS 9, 10, or 11  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qelos/integrator-nest",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "NestJS module that identifies the Qelos user and active workspace before your route handlers run",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -61,7 +61,7 @@
     }
   },
   "dependencies": {
-    "@qelos/sdk": "^4.0.0"
+    "@qelos/sdk": "4.0.0"
   },
   "devDependencies": {
     "@nestjs/common": "^10.4.5",
@@ -75,6 +75,6 @@
     "type-check": "tsc --noEmit",
     "build": "tsc",
     "pre-build": "tsc",
-    "test": "node --import tsx --test test/**/*.test.ts"
+    "test": "node --import tsx --test test/**/*.test.ts src/**/*.test.ts"
   }
 }