@qelos/integrator-nuxt 4.0.0

package/dist/sdk-factory.js

@@ -0,0 +1,84 @@
+import QelosSDK from '@qelos/sdk';
+const NO_AUTH_URLS = new Set([
+    '/api/token/refresh',
+    '/api/cookie/refresh',
+    '/api/signin',
+    '/api/signup',
+]);
+export function createRequestSdk({ config, tokens, event, onTokenRefresh }) {
+    let sdk;
+    let refreshInFlight = null;
+    const baseOptions = config.sdkOptions || {};
+    async function performRefresh() {
+        if (!tokens.refreshToken && !tokens.accessToken) {
+            throw new Error('no refresh token available');
+        }
+        const previous = {
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+        };
+        let refreshed;
+        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() {
+        if (!refreshInFlight) {
+            refreshInFlight = performRefresh().finally(() => {
+                refreshInFlight = null;
+            });
+        }
+        return refreshInFlight;
+    }
+    const options = {
+        appUrl: config.appUrl,
+        fetch: globalThis.fetch,
+        forceRefresh: !config.apiToken,
+        ...baseOptions,
+    };
+    if (config.apiToken) {
+        options.apiToken = config.apiToken;
+    }
+    else {
+        if (tokens.accessToken) {
+            options.accessToken = tokens.accessToken;
+        }
+        if (tokens.refreshToken) {
+            options.refreshToken = tokens.refreshToken;
+        }
+        options.extraHeaders = async (relativeUrl, forceRefresh) => {
+            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;
+}
+//# sourceMappingURL=sdk-factory.js.map

package/dist/sdk-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-factory.js","sourceRoot":"","sources":["../src/sdk-factory.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+import type QelosSDK from '@qelos/sdk';
+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).
+     */
+    appUrl: string;
+    /**
+     * Static API token used for service-to-service calls. When provided, no
+     * cookie/refresh-token handling 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).
+     */
+    middlewarePath?: string;
+    /**
+     * If true, the request is rejected (401) when the user cannot be resolved.
+     * Defaults to `false` — anonymous requests pass through with `event.context.qelos.user = null`.
+     */
+    requireAuth?: boolean;
+    /**
+     * Skip the middleware entirely for requests matching any of these path
+     * prefixes. Useful for `/api/_auth`, `/health`, etc.
+     */
+    skipPaths?: string[];
+    /**
+     * Optional extra options merged into the per-request SDK instance.
+     */
+    sdkOptions?: Partial<QelosSDKOptions>;
+}
+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.
+     */
+    user: IUser | null;
+    /**
+     * The active workspace for the request, or `null` when none is active /
+     * the user is anonymous.
+     */
+    workspace: IWorkspace | null;
+    /**
+     * The full list of workspaces the user has access to.
+     */
+    workspaces: IWorkspace[];
+    /**
+     * SDK instance bound to the current request's tokens.
+     */
+    sdk: QelosSDK;
+    /**
+     * Tokens read from the request. Mutated when a refresh occurs.
+     */
+    tokens: QelosTokenPair;
+}
+declare module 'h3' {
+    interface H3EventContext {
+        qelos?: QelosRequestContext;
+    }
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@qelos/integrator-nuxt",
+  "version": "4.0.0",
+  "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",
+  "types": "./dist/module.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js",
+      "require": "./dist/module.js",
+      "default": "./dist/module.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js",
+      "require": "./dist/middleware.js",
+      "default": "./dist/middleware.js"
+    },
+    "./event-handler": {
+      "types": "./dist/event-handler.d.ts",
+      "import": "./dist/event-handler.js",
+      "require": "./dist/event-handler.js",
+      "default": "./dist/event-handler.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "require": "./dist/types.js",
+      "default": "./dist/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "qelos",
+    "nuxt",
+    "nuxt-module",
+    "middleware",
+    "auth",
+    "sdk"
+  ],
+  "author": "David Meir-Levy <davidmeirlevy@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "h3": "^1.0.0",
+    "nuxt": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "nuxt": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@qelos/sdk": "4.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/kit": "^3.13.0",
+    "@nuxt/schema": "^3.13.0",
+    "h3": "^1.13.0",
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "build": "npm run type-check && tsc",
+    "pre-build": "pnpm run type-check && tsc"
+  }
+}

package/src/event-handler.ts

@@ -0,0 +1,66 @@
+import {
+  defineEventHandler,
+  createError,
+  type EventHandlerRequest,
+  type EventHandlerResponse,
+  type H3Event,
+} from 'h3';
+import type { QelosRequestContext } from './types';
+
+export interface QelosEventContext<T extends EventHandlerRequest = EventHandlerRequest> {
+  event: H3Event<T>;
+  qelos: QelosRequestContext;
+}
+
+export interface DefineQelosEventHandlerOptions {
+  /**
+   * Reject the request with `401 Unauthorized` when no authenticated user is
+   * resolved on `event.context.qelos`. Defaults to `false`, mirroring the
+   * module-level `qelos.requireAuth` behavior.
+   */
+  requireAuth?: boolean;
+}
+
+export type QelosEventHandler<
+  Request extends EventHandlerRequest = EventHandlerRequest,
+  Response extends EventHandlerResponse = EventHandlerResponse,
+> = (ctx: QelosEventContext<Request>) => Response;
+
+/**
+ * Wrap a Nitro/H3 event handler so that the Qelos request context (user,
+ * workspace, workspaces, sdk, tokens) is available as a second argument and
+ * already typed. Requires the `@qelos/integrator-nuxt` module to be enabled
+ * (or `createQelosMiddleware` to be registered manually) so that
+ * `event.context.qelos` is populated.
+ *
+ * ```ts
+ * // server/api/products.ts
+ * import { defineQelosEventHandler } from '@qelos/integrator-nuxt';
+ *
+ * export default defineQelosEventHandler(async ({ qelos }) => {
+ *   return qelos.sdk.entities('products').getList();
+ * });
+ * ```
+ */
+export function defineQelosEventHandler<
+  Request extends EventHandlerRequest = EventHandlerRequest,
+  Response extends EventHandlerResponse = EventHandlerResponse,
+>(
+  handler: QelosEventHandler<Request, Response>,
+  options: DefineQelosEventHandlerOptions = {},
+) {
+  return defineEventHandler<Request>(async (event) => {
+    const qelos = event.context.qelos;
+    if (!qelos) {
+      throw createError({
+        statusCode: 500,
+        statusMessage:
+          '[@qelos/integrator-nuxt] event.context.qelos is missing. Add the module to nuxt.config or register createQelosMiddleware manually.',
+      });
+    }
+    if (options.requireAuth && !qelos.user) {
+      throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
+    }
+    return handler({ event, qelos }) as Response;
+  });
+}

package/src/middleware.ts

@@ -0,0 +1,146 @@
+import {
+  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 { 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';
+
+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()`.
+   */
+  resolveWorkspace?: (params: {
+    event: H3Event;
+    user: IUser;
+    workspaces: IWorkspace[];
+  }) => 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;
+  }
+  const path = event.path || event.node?.req?.url || '';
+  return config.skipPaths.some((prefix) => path.startsWith(prefix));
+}
+
+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 ctx: QelosRequestContext = {
+      user: null,
+      workspace: null,
+      workspaces: [],
+      sdk,
+      tokens,
+    };
+    event.context.qelos = ctx;
+
+    const hasAuthMaterial = Boolean(config.apiToken || tokens.accessToken || tokens.refreshToken);
+    if (!hasAuthMaterial) {
+      if (config.requireAuth) {
+        throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
+      }
+      return;
+    }
+
+    try {
+      ctx.user = await sdk.authentication.getLoggedInUser();
+    } catch (err) {
+      if (config.requireAuth) {
+        throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
+      }
+      return;
+    }
+
+    try {
+      ctx.workspaces = await sdk.workspaces.getList();
+    } catch {
+      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;
+      }
+    }
+  });
+}
+
+export type QelosMiddleware = ReturnType<typeof createQelosMiddleware>;

package/src/module.ts

@@ -0,0 +1,84 @@
+import {
+  defineNuxtModule,
+  addServerHandler,
+  addImportsDir,
+  createResolver,
+  addTypeTemplate,
+} from '@nuxt/kit';
+import type { QelosNuxtRuntimeConfig } from './types';
+
+export interface QelosNuxtModuleOptions extends QelosNuxtRuntimeConfig {
+  /**
+   * Disable registration of the default server middleware. Use this if you
+   * want to call `createQelosMiddleware` yourself from your own server route.
+   */
+  disableMiddleware?: boolean;
+}
+
+export default defineNuxtModule<QelosNuxtModuleOptions>({
+  meta: {
+    name: '@qelos/integrator-nuxt',
+    configKey: 'qelos',
+    compatibility: {
+      nuxt: '^3.0.0',
+    },
+  },
+  defaults: {
+    appUrl: '',
+  },
+  setup(options, nuxt) {
+    if (!options.appUrl) {
+      throw new Error('[@qelos/integrator-nuxt] `qelos.appUrl` must be set in nuxt.config');
+    }
+
+    const { resolve } = createResolver(import.meta.url);
+
+    const { disableMiddleware, ...runtimeConfig } = options;
+
+    nuxt.options.runtimeConfig.qelos = {
+      ...(nuxt.options.runtimeConfig.qelos as Record<string, unknown> | undefined),
+      ...runtimeConfig,
+    };
+
+    if (!disableMiddleware) {
+      addServerHandler({
+        handler: resolve('./runtime/server-handler'),
+        middleware: true,
+      });
+    }
+
+    addImportsDir(resolve('./runtime/composables'));
+
+    addTypeTemplate({
+      filename: 'types/qelos-nuxt.d.ts',
+      getContents: () => `
+import type { QelosRequestContext } from '@qelos/integrator-nuxt/types';
+
+declare module 'h3' {
+  interface H3EventContext {
+    qelos?: QelosRequestContext;
+  }
+}
+
+export {};
+`,
+    });
+  },
+});
+
+export { createQelosMiddleware } from './middleware';
+export { createRequestSdk } from './sdk-factory';
+export { defineQelosEventHandler } from './event-handler';
+export type {
+  DefineQelosEventHandlerOptions,
+  QelosEventContext,
+  QelosEventHandler,
+} from './event-handler';
+export type {
+  QelosNuxtRuntimeConfig,
+  QelosRequestContext,
+  QelosTokenPair,
+  ResolvedTokens,
+  TokenRefreshContext,
+  TokenRefreshHook,
+} from './types';

package/src/runtime/composables/useQelos.ts

@@ -0,0 +1,60 @@
+// Auto-imported as `useQelos` by the @qelos/integrator-nuxt module. This file
+// is bundled by Nuxt/Nitro in the consuming app, so `#imports` resolves at
+// the consumer's build time.
+// @ts-ignore - resolved by Nuxt
+import { useState, useRequestEvent } from '#imports';
+import type { IUser } from '@qelos/sdk/dist/authentication';
+import type { IWorkspace } from '@qelos/sdk/workspaces';
+import type { QelosRequestContext } from '../../types';
+
+// Minimal local Ref type — structurally matches `vue`'s Ref for the consumer.
+// We don't take a `vue` dep at this package's `tsc` build time.
+interface Ref<T> {
+  value: T;
+}
+
+export interface UseQelosReturn {
+  /** The authenticated user (or `null` when anonymous). Hydrated from SSR. */
+  user: Ref<IUser | null>;
+  /** The active workspace for the user (or `null`). Hydrated from SSR. */
+  workspace: Ref<IWorkspace | null>;
+  /** All workspaces the user has access to. Hydrated from SSR. */
+  workspaces: Ref<IWorkspace[]>;
+  /** Convenience: `true` when `user` is set. */
+  isAuthenticated: Ref<boolean>;
+}
+
+function getServerContext(): QelosRequestContext | null {
+  if (typeof window !== 'undefined') return null;
+  try {
+    const event = useRequestEvent();
+    return (event && event.context && event.context.qelos) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the current Qelos identity (user / workspace / workspaces) on the
+ * client. Values are seeded on the server by the Qelos server middleware and
+ * sent to the client via Nuxt's payload. SDK calls from the browser should go
+ * through your own server routes (use `defineQelosEventHandler`) rather than
+ * directly, so refresh-token rotation stays server-side.
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * const { user, workspace, isAuthenticated } = useQelos();
+ * </script>
+ * ```
+ */
+export function useQelos(): UseQelosReturn {
+  const ctx = getServerContext();
+  const user = useState<IUser | null>('qelos:user', () => ctx?.user ?? null);
+  const workspace = useState<IWorkspace | null>('qelos:workspace', () => ctx?.workspace ?? null);
+  const workspaces = useState<IWorkspace[]>('qelos:workspaces', () => ctx?.workspaces ?? []);
+  const isAuthenticated = useState<boolean>(
+    'qelos:isAuthenticated',
+    () => Boolean(ctx?.user),
+  );
+  return { user, workspace, workspaces, isAuthenticated };
+}

package/src/runtime/server-handler.ts

@@ -0,0 +1,12 @@
+// This file is registered as a Nuxt server middleware 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 { createQelosMiddleware } from '../middleware';
+import type { QelosNuxtRuntimeConfig } from '../types';
+
+const runtimeConfig = useRuntimeConfig();
+const config = (runtimeConfig.qelos || {}) as QelosNuxtRuntimeConfig;
+
+export default createQelosMiddleware({ config });