nuxt-convex-module 0.0.0 → 0.0.1

package/dist/{module.js → module.mjs}

@@ -1,4 +1,4 @@
-import { useLogger, defineNuxtModule, createResolver, addPlugin, addPluginTemplate, addTypeTemplate, updateTemplates, addImports, addComponent, addServerImports, addServerHandler, extendRouteRules, addRouteMiddleware } from '@nuxt/kit';
+import { useLogger, defineNuxtModule, createResolver, addPlugin, hasNuxtModule, addServerPlugin, addPluginTemplate, addTypeTemplate, updateTemplates, addImports, addComponent, addServerImports, addServerHandler, extendRouteRules, addRouteMiddleware } from '@nuxt/kit';
 import { join, isAbsolute } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
@@ -49,14 +49,13 @@ const module$1 = defineNuxtModule({
     authRoute: "/api/auth",
     devtools: true
   },
-  // nuxt-security is an integral part of the integration: declaring it as a
-  // module dependency makes Nuxt's core loader install it (hoisting its types
-  // and deduping if you also register it yourself), and guarantees our setup
-  // runs *before* it — so the Convex-aware CSP defaults below land before
-  // nuxt-security reads its config. Configure it via the `security` key.
-  moduleDependencies: {
-    "nuxt-security": {}
-  },
+  // nuxt-security is optional. When the app has it installed (and hasn't
+  // switched it off), declare it as a module dependency so Nuxt's core loader
+  // registers it — deduping if it's already in `modules`, hoisting its types —
+  // with no extra entry on the consumer's side. The Convex-aware CSP is applied
+  // at runtime (see `registerSecurity`), so module order is irrelevant. Nothing
+  // is declared otherwise: kit fails the build resolving an absent package.
+  moduleDependencies: (nuxt) => resolveSecurityState(nuxt, readSecurityOption(nuxt)).enabled ? { "nuxt-security": {} } : {},
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
     nuxt.options.build.transpile.push(resolver.resolve("./runtime"));
@@ -79,7 +78,6 @@ const module$1 = defineNuxtModule({
     registerAuthComponents(resolver);
     registerServerImports(resolver);
     const integrations = registerIntegrations(resolver, nuxt, options);
-    applyConvexCsp(nuxt, url, siteUrl);
     watchConvexCodegen(nuxt);
     if (nuxt.options.dev && options.devtools !== false && isDevtoolsUiEnabled(nuxt)) {
       const { setupDevtools } = await import('./chunks/index.mjs');
@@ -106,6 +104,11 @@ function resolveIntegrationState(explicit, installed) {
   if (explicit === void 0) return { enabled: installed, missingPackage: false };
   return installed ? { enabled: true, missingPackage: false } : { enabled: false, missingPackage: true };
 }
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end--;
+  return value.slice(0, end);
+}
 function validateModuleOptions(input) {
   const errors = [];
   const warnings = [];
@@ -135,7 +138,7 @@ function validateModuleOptions(input) {
     );
   }
   if (authRoute.length > 1 && authRoute.endsWith("/")) {
-    authRoute = authRoute.replace(/\/+$/, "");
+    authRoute = stripTrailingSlashes(authRoute);
   }
   if (input.authClient && !authClientModuleExists(input.authClient, input.rootDir)) {
     errors.push(
@@ -166,19 +169,20 @@ function formatStartupSummary(url, functionsDir, integrations) {
     betterAuth: "better-auth",
     clerk: "clerk",
     auth0: "auth0",
-    polar: "polar"
+    polar: "polar",
+    security: "nuxt-security"
   };
   const enabled = Object.keys(names).filter((key) => integrations[key]).map((key) => names[key]);
   return `Convex ${url || "(no URL)"} \xB7 functions: ${functionsDir}/ \xB7 integrations: ${enabled.join(", ") || "none"}`;
 }
 function registerIntegrations(resolver, nuxt, options) {
-  const resolve = (key, pkg) => {
-    const state = resolveIntegrationState(options[key], isPackageInstalled(pkg, nuxt.options.rootDir));
+  const report = (key, pkg, state) => {
     if (state.missingPackage) {
       logger.error(`\`convex.${key}\` is enabled but \`${pkg}\` is not installed. Run \`npm install ${pkg}\` or remove the option.`);
     }
     return state.enabled;
   };
+  const resolve = (key, pkg) => report(key, pkg, resolveIntegrationState(options[key], isPackageInstalled(pkg, nuxt.options.rootDir)));
   const betterAuth = resolve("betterAuth", "@convex-dev/better-auth");
   if (betterAuth) {
     registerBetterAuth(resolver, options.authRoute || "/api/auth");
@@ -197,49 +201,59 @@ function registerIntegrations(resolver, nuxt, options) {
   if (polar) {
     registerPolarComponents(resolver);
   }
-  return { betterAuth, clerk, auth0, polar };
+  const security = report("security", "nuxt-security", resolveSecurityState(nuxt, options.security));
+  if (security) {
+    registerSecurity(resolver);
+  }
+  return { betterAuth, clerk, auth0, polar, security };
 }
-function applyConvexCsp(nuxt, url, siteUrl) {
+function readSecurityOption(nuxt) {
   const opts = nuxt.options;
-  if (!url || opts.security === false) return;
-  const security = opts.security ??= {};
-  applyConvexSecurityDefaults(
-    security,
-    nuxt.options.dev ? [] : convexConnectSrc(url, siteUrl),
-    convexResourceSrc(url)
-  );
+  return opts.convex?.security;
+}
+function resolveSecurityState(nuxt, explicit) {
+  const opts = nuxt.options;
+  if (opts.security === false) return { enabled: false, missingPackage: false };
+  const installed = hasNuxtModule("nuxt-security", nuxt) || isPackageInstalled("nuxt-security", nuxt.options.rootDir);
+  return resolveIntegrationState(explicit, installed);
+}
+function registerSecurity(resolver) {
+  addServerPlugin(resolver.resolve("./runtime/nuxt/security"));
 }
 function isPackageInstalled(id, rootDir) {
   for (const base of [join(rootDir, "package.json"), import.meta.url]) {
-    const require = createRequire(base);
-    for (const target of [id, `${id}/package.json`]) {
-      try {
-        require.resolve(target);
-        return true;
-      } catch {
-      }
-    }
+    const lookupPaths = createRequire(base).resolve.paths(id) ?? [];
+    if (lookupPaths.some((dir) => existsSync(join(dir, id, "package.json")))) return true;
   }
   return false;
 }
+function resolveDeploymentUrls(options, env) {
+  return {
+    url: options.url || env.NUXT_PUBLIC_CONVEX_URL || env.CONVEX_URL || "",
+    siteUrl: options.siteUrl || env.NUXT_PUBLIC_CONVEX_SITE_URL || env.CONVEX_SITE_URL || ""
+  };
+}
 function applyRuntimeConfig(nuxt, options) {
-  const url = nuxt.options._prepare ? void 0 : options.url || process.env.NUXT_PUBLIC_CONVEX_URL;
+  const resolved = resolveDeploymentUrls(options, process.env);
+  const url = nuxt.options._prepare ? "" : resolved.url;
   if (!url && !nuxt.options._prepare) {
     logger.warn(
-      "No Convex deployment URL configured. Set NUXT_PUBLIC_CONVEX_URL or `convex.url` in nuxt.config. Note: `npx convex dev` writes CONVEX_URL to .env.local, which Nuxt does not load."
+      "No Convex deployment URL configured. Set NUXT_PUBLIC_CONVEX_URL or `convex.url` in nuxt.config. Note: `npx convex dev` writes CONVEX_URL to .env.local, which Nuxt does not read without `nuxt dev --dotenv .env.local`."
     );
   }
-  const siteUrl = options.siteUrl || process.env.NUXT_PUBLIC_CONVEX_SITE_URL || "";
+  const siteUrl = resolved.siteUrl;
   const crossDomainCallbackRoute = typeof options.betterAuth === "object" && options.betterAuth.crossDomainCallbackRoute || "";
+  const loginPath = typeof options.betterAuth === "object" && options.betterAuth.loginPath || "/login";
   const runtimeConfig = nuxt.options.runtimeConfig;
   runtimeConfig.public.convex = {
     ...runtimeConfig.public.convex,
-    url: url || "",
+    url,
     siteUrl,
-    crossDomainCallbackRoute
+    crossDomainCallbackRoute,
+    loginPath
   };
   runtimeConfig.convex = { ...runtimeConfig.convex, siteUrl };
-  return { url: url || "", siteUrl };
+  return { url, siteUrl };
 }
 function getConvexAliases(rootDir) {
   const functionsDir = resolveFunctionsDir(rootDir);
@@ -395,12 +409,17 @@ function registerServerImports(resolver) {
   const serverUtils = ["fetchQuery", "fetchMutation", "fetchAction", "preloadQuery", "preloadedQueryResult"];
   addServerImports(serverUtils.map((name) => ({ name, from: fromNuxt })));
 }
+const AUTH_PROXY_SECURITY_RULES = {
+  xssValidator: false,
+  allowedMethodsRestricter: { methods: ["GET", "HEAD", "POST", "OPTIONS"] }
+};
 function registerBetterAuth(resolver, authRoute) {
   addPlugin(resolver.resolve("./runtime/better-auth/vue/plugin.client"));
   addPlugin(resolver.resolve("./runtime/better-auth/vue/plugin.server"));
   addImports([
     { name: "useAuth", from: resolver.resolve("./runtime/better-auth/vue/use-auth") },
-    { name: "usePreloadedAuthQuery", from: resolver.resolve("./runtime/better-auth/vue/hydration") }
+    { name: "usePreloadedAuthQuery", from: resolver.resolve("./runtime/better-auth/vue/hydration") },
+    { name: "resolveAuthRedirect", from: resolver.resolve("./runtime/better-auth/vue/redirect") }
   ]);
   addComponent({
     name: "AuthBoundary",
@@ -411,7 +430,11 @@ function registerBetterAuth(resolver, authRoute) {
     route: `${authRoute}/**`,
     handler: resolver.resolve("./runtime/better-auth/nuxt/proxy")
   });
-  extendRouteRules(`${authRoute}/**`, { cache: false, prerender: false });
+  extendRouteRules(`${authRoute}/**`, {
+    cache: false,
+    prerender: false,
+    security: AUTH_PROXY_SECURITY_RULES
+  });
   addRouteMiddleware({
     name: "auth",
     path: resolver.resolve("./runtime/better-auth/nuxt/middleware"),
@@ -441,49 +464,5 @@ function registerPolarComponents(resolver) {
     addComponent({ name, filePath: componentsFile, export: name });
   }
 }
-function toHttpOrigin(raw) {
-  if (!raw) return void 0;
-  try {
-    return new URL(raw).origin;
-  } catch {
-    return void 0;
-  }
-}
-function toWsOrigin(raw) {
-  if (!raw) return void 0;
-  try {
-    const u = new URL(raw);
-    return `${u.protocol === "https:" ? "wss:" : "ws:"}//${u.host}`;
-  } catch {
-    return void 0;
-  }
-}
-function uniq(values) {
-  return Array.from(new Set(values.filter((v) => Boolean(v))));
-}
-function convexConnectSrc(url, siteUrl) {
-  return uniq([toHttpOrigin(url), toWsOrigin(url), toHttpOrigin(siteUrl), toWsOrigin(siteUrl)]);
-}
-function convexResourceSrc(url) {
-  return uniq([toHttpOrigin(url)]);
-}
-function applyConvexSecurityDefaults(security, connectSrc, resourceSrc) {
-  if (security.headers === false) return;
-  if (typeof security.headers !== "object" || security.headers === null) security.headers = {};
-  const headers = security.headers;
-  if (headers.contentSecurityPolicy === false) return;
-  if (typeof headers.contentSecurityPolicy !== "object" || headers.contentSecurityPolicy === null) {
-    headers.contentSecurityPolicy = {};
-  }
-  const csp = headers.contentSecurityPolicy;
-  tightenDirective(csp, "connect-src", ["'self'"], connectSrc);
-  tightenDirective(csp, "img-src", ["'self'", "data:"], resourceSrc);
-  tightenDirective(csp, "media-src", ["'self'"], resourceSrc);
-}
-function tightenDirective(csp, name, baseline, additions) {
-  if (additions.length === 0) return;
-  const existing = Array.isArray(csp[name]) ? csp[name] : baseline;
-  csp[name] = uniq([...existing, ...additions]);
-}
 
-export { applyConvexSecurityDefaults, convexConnectSrc, convexResourceSrc, convexTypeFallbackContents, module$1 as default, formatStartupSummary, getConvexAliases, resolveIntegrationState, validateModuleOptions };
+export { convexTypeFallbackContents, module$1 as default, formatStartupSummary, getConvexAliases, resolveDeploymentUrls, resolveIntegrationState, validateModuleOptions };

package/dist/runtime/better-auth/nuxt/middleware.d.ts

@@ -1,6 +1,10 @@
 /**
  * Auth route middleware — protects pages from unauthenticated access.
  *
+ * Unauthenticated visitors are sent to the configured login route
+ * (`convex.betterAuth.loginPath`, default `/login`) with the original
+ * destination in a `?redirect=` query.
+ *
  * Usage in page:
  * ```vue
  * <script setup>
@@ -8,7 +12,11 @@
  * </script>
  * ```
  */
+interface GuardedRoute {
+    path: string;
+    fullPath: string;
+}
 /** Exported for unit tests — `import.meta.server` is compile-time. @internal */
-export declare function serverGuard(path: string): Promise<string | false | void | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric | import("vue-router").NavigationFailure>;
+export declare function serverGuard(to: GuardedRoute, loginPath: string): Promise<string | false | void | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric | import("vue-router").NavigationFailure>;
 declare const _default: import("nuxt/app").RouteMiddleware;
 export default _default;

package/dist/runtime/better-auth/nuxt/middleware.js

@@ -1,14 +1,17 @@
-import { defineNuxtRouteMiddleware, navigateTo, useNuxtApp, useRequestEvent } from "#app";
+import { defineNuxtRouteMiddleware, navigateTo, useNuxtApp, useRequestEvent, useRuntimeConfig } from "#app";
 import { watch } from "vue";
 import { useAuth } from "../vue/use-auth.js";
 import { convexAuth } from "./server.js";
-export async function serverGuard(path) {
+function loginTarget(to, loginPath) {
+  return { path: loginPath, query: { redirect: to.fullPath } };
+}
+export async function serverGuard(to, loginPath) {
   const event = useRequestEvent();
   if (!event) return;
   const nuxtApp = useNuxtApp();
   const authed = await convexAuth(event).isAuthenticated();
-  if (!authed && path !== "/login") {
-    return nuxtApp.runWithContext(() => navigateTo("/login"));
+  if (!authed && to.path !== loginPath) {
+    return nuxtApp.runWithContext(() => navigateTo(loginTarget(to, loginPath)));
   }
 }
 function waitForSession(isPending) {
@@ -26,14 +29,15 @@ function waitForSession(isPending) {
   });
 }
 export default defineNuxtRouteMiddleware(async (to) => {
+  const loginPath = useRuntimeConfig().public.convex.loginPath || "/login";
   if (import.meta.server) {
-    return serverGuard(to.path);
+    return serverGuard(to, loginPath);
   }
   const { session } = useAuth();
   if (session.value.isPending) {
     await waitForSession(() => session.value.isPending);
   }
-  if (!session.value.data && to.path !== "/login") {
-    return navigateTo("/login");
+  if (!session.value.data && to.path !== loginPath) {
+    return navigateTo(loginTarget(to, loginPath));
   }
 });

package/dist/runtime/better-auth/nuxt/server.js

@@ -11,6 +11,21 @@ const parseConvexSiteUrl = (url) => {
   if (url.endsWith(".convex.cloud")) {
     throw new Error(
       `NUXT_PUBLIC_CONVEX_SITE_URL should be set to your Convex Site URL, which ends in .convex.site.
+Currently set to ${url}.`
+    );
+  }
+  let protocol;
+  try {
+    protocol = new URL(url).protocol;
+  } catch {
+    throw new Error(
+      `NUXT_PUBLIC_CONVEX_SITE_URL must be an absolute URL, including the scheme.
+Currently set to ${url}.`
+    );
+  }
+  if (protocol !== "https:" && protocol !== "http:") {
+    throw new Error(
+      `NUXT_PUBLIC_CONVEX_SITE_URL must use http: or https:.
 Currently set to ${url}.`
     );
   }

package/dist/runtime/better-auth/vue/auth-boundary.d.ts

@@ -1,7 +1,7 @@
 import { type PropType, type VNode } from 'vue';
 import type { FunctionReference } from 'convex/server';
-import type { EmptyObject } from 'convex-helpers';
 import type { AuthClient } from '#convex/auth-client';
+type EmptyObject = Record<string, never>;
 /**
  * _Experimental_
  *
@@ -129,3 +129,4 @@ export declare const AuthBoundary: import("vue").DefineComponent<import("vue").E
 }>> & Readonly<{}>, {
     renderFallback: () => VNode | null;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export {};

package/dist/runtime/better-auth/vue/client.d.ts

@@ -172,7 +172,7 @@ export declare const authClient: import("better-auth/vue").VueAuthClient<{
                     metadata: {
                         isAction: false;
                     };
-                }, import("better-auth/plugins").OIDCMetadata>;
+                }, import("better-auth/plugins/oidc-provider").OIDCMetadata>;
                 getJwks: import("better-auth").StrictEndpoint<"/convex/jwks", {
                     method: "GET";
                     metadata: {

package/dist/runtime/better-auth/vue/cross-domain.d.ts

@@ -11,11 +11,10 @@ export interface ConsumeCrossDomainOneTimeTokenOptions {
      *
      * The cross-domain protocol cannot bind the token to the browser that
      * started the sign-in flow (magic-link flows legitimately finish in another
-     * browsing context), so without this restriction a crafted
-     * `/any-page?ott=…` link silently signs the visitor into the link author's
-     * session — login CSRF. Restricting consumption to the one route your
-     * sign-in `callbackURL`s point at shrinks that surface to a single
-     * predictable URL.
+     * browsing context), so without this restriction a token completes sign-in
+     * on whatever page receives it. Restricting consumption to the one route
+     * your sign-in `callbackURL`s point at keeps that to a single predictable
+     * URL.
      *
      * In Nuxt, set `convex.betterAuth.crossDomainCallbackRoute` instead — the
      * client plugin forwards it here.

package/dist/runtime/better-auth/vue/cross-domain.js

@@ -1,7 +1,9 @@
 import { authClient } from "#convex/auth-client";
 const normalizePathname = (path) => {
   const slashed = path.startsWith("/") ? path : `/${path}`;
-  const trimmed = slashed.replace(/\/+$/, "");
+  let end = slashed.length;
+  while (end > 0 && slashed[end - 1] === "/") end--;
+  const trimmed = slashed.slice(0, end);
   return trimmed === "" ? "/" : trimmed;
 };
 export async function consumeCrossDomainOneTimeToken(options = {}) {
@@ -36,7 +38,7 @@ export async function consumeCrossDomainOneTimeToken(options = {}) {
             }
           }
         });
-        authClientWithCrossDomain.updateSession();
+        await authClientWithCrossDomain.updateSession();
       }
     } catch (error) {
       console.warn("[nuxt-convex-module] failed to consume cross-domain one-time token", error);

package/dist/runtime/better-auth/vue/index.d.ts

@@ -8,5 +8,6 @@ export { useAuth, type UseAuthService, type AuthSession, type AuthUser } from '.
 export { authClient, type AuthClient } from '#convex/auth-client';
 export { usePreloadedAuthQuery } from './hydration.js';
 export { consumeCrossDomainOneTimeToken, type ConsumeCrossDomainOneTimeTokenOptions } from './cross-domain.js';
+export { resolveAuthRedirect } from './redirect.js';
 export { AuthBoundary } from './auth-boundary.js';
 export { convexClient, crossDomainClient } from '@convex-dev/better-auth/client/plugins';

package/dist/runtime/better-auth/vue/index.js

@@ -2,5 +2,6 @@ export { useAuth } from "./use-auth.js";
 export { authClient } from "#convex/auth-client";
 export { usePreloadedAuthQuery } from "./hydration.js";
 export { consumeCrossDomainOneTimeToken } from "./cross-domain.js";
+export { resolveAuthRedirect } from "./redirect.js";
 export { AuthBoundary } from "./auth-boundary.js";
 export { convexClient, crossDomainClient } from "@convex-dev/better-auth/client/plugins";

package/dist/runtime/better-auth/vue/redirect.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Safe handling of the `?redirect=` destination the `auth` route middleware
+ * attaches when it sends an unauthenticated visitor to the login page.
+ *
+ * The middleware only ever writes a router path there, but the query is part
+ * of a URL anyone can craft: a link to `/login?redirect=https://evil.example`
+ * turns a login page that navigates to `route.query.redirect` verbatim into an
+ * open redirect — a phishing primitive that borrows the app's own domain, and
+ * one that carries whatever the app appends to the destination.
+ *
+ * @module better-auth/redirect
+ */
+/**
+ * Validate a post-sign-in redirect destination, returning `fallback` unless it
+ * is a same-origin path.
+ *
+ * Use it wherever a login page consumes the `?redirect=` query the `auth`
+ * middleware sets — never navigate to that value directly.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * const route = useRoute()
+ * const { signIn } = useAuth()
+ *
+ * async function onSubmit() {
+ *   await signIn.email({ email, password })
+ *   // '/dashboard' survives; 'https://evil.example' becomes '/'.
+ *   await navigateTo(resolveAuthRedirect(route.query.redirect))
+ * }
+ * </script>
+ * ```
+ *
+ * @param value - Candidate destination, typically `route.query.redirect`. A
+ *   repeated query parameter arrives as an array and is rejected: which entry
+ *   the app meant is ambiguous, and an attacker chooses the other one.
+ * @param fallback - Where to send the visitor when `value` is not a safe
+ *   same-origin path. Defaults to `/`, and is returned as given — pass a path
+ *   you control, not user input.
+ *
+ * @returns The normalized `pathname + search + hash`, or `fallback`.
+ *
+ * @public
+ */
+export declare function resolveAuthRedirect(value: unknown, fallback?: string): string;

package/dist/runtime/better-auth/vue/redirect.js

@@ -0,0 +1,14 @@
+const SENTINEL_ORIGIN = "http://redirect.invalid";
+export function resolveAuthRedirect(value, fallback = "/") {
+  if (typeof value !== "string" || value === "") return fallback;
+  if (!value.startsWith("/")) return fallback;
+  try {
+    const url = new URL(value, SENTINEL_ORIGIN);
+    if (url.origin !== SENTINEL_ORIGIN) return fallback;
+    const path = `${url.pathname}${url.search}${url.hash}`;
+    if (new URL(path, SENTINEL_ORIGIN).origin !== SENTINEL_ORIGIN) return fallback;
+    return path;
+  } catch {
+    return fallback;
+  }
+}

package/dist/runtime/better-auth/vue/use-auth.js

@@ -55,6 +55,7 @@ export function useAuth(initialToken) {
   };
   return {
     isLoading: computed(() => session.value.isPending && !cachedToken.value),
+    // PARITY: D-03
     // Diverges from upstream's `Boolean(session?.session) || cachedToken !== null`:
     // a settled signed-out session must read unauthenticated immediately (Vue has
     // no re-render to run upstream's cache-clearing effect first), and Better Auth
@@ -63,7 +64,7 @@ export function useAuth(initialToken) {
       () => !!session.value.data || session.value.isPending && cachedToken.value !== null
     ),
     fetchAccessToken,
-    // Vue-only service extensions (documented in PARITY.md).
+    // PARITY: A-06 — Vue-only service extensions.
     client,
     session,
     user: computed(() => {

package/dist/runtime/devtools/bridge.js

@@ -17,7 +17,7 @@ function toPlainJson(value) {
   try {
     return convexToJson(value);
   } catch {
-    return String(value);
+    return typeof value === "object" && value !== null ? `[unserializable ${Array.isArray(value) ? "array" : "object"}]` : String(value);
   }
 }
 function renderLogArg(arg) {

package/dist/runtime/nuxt/csp.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure helpers behind the Convex-aware Content Security Policy the module
+ * applies when `nuxt-security` is present — shared by the Nitro plugin
+ * (`./security`) and the unit tests. Import-free so it runs anywhere.
+ */
+/**
+ * The slice of a nuxt-security rule set this module touches: the resolved
+ * options for one route (`rules['/**']` at runtime), where `headers` and
+ * `contentSecurityPolicy` may each be `false` when the app switched them off.
+ */
+export interface SecurityRules {
+    headers?: false | {
+        contentSecurityPolicy?: false | Record<string, unknown>;
+        [header: string]: unknown;
+    };
+    [option: string]: unknown;
+}
+/**
+ * CSP `connect-src` entries the browser needs to reach a Convex deployment: the
+ * deployment URL over both HTTPS and WebSocket (the realtime sync channel) and,
+ * when configured, the `.site` URL that serves Convex HTTP actions. Returns
+ * `[]` for empty or unparseable input.
+ */
+export declare function convexConnectSrc(url?: string, siteUrl?: string): string[];
+/**
+ * CSP sources for Convex-served resources (`img-src` / `media-src`): files
+ * uploaded through `useStorageUrl()` are served from the deployment origin,
+ * and files streamed by HTTP actions from the `.site` origin.
+ */
+export declare function convexResourceSrc(url?: string, siteUrl?: string): string[];
+/**
+ * Apply nuxt-convex-module's secure-by-default, Convex-aware CSP onto a
+ * nuxt-security rule set (mutated in place). This tightens the directives we
+ * can safely pre-fill — locking network egress and Convex-served media to
+ * same-origin plus the Convex deployment — while leaving every other directive
+ * (script/style/font, etc.) to nuxt-security's own defaults.
+ *
+ * For each directive we keep any value the user already set and *append* the
+ * Convex origins, so consumers extend (add their own third parties) rather than
+ * fight the defaults, and the Convex origins are always present. A user who sets
+ * `contentSecurityPolicy: false` (CSP disabled) is left untouched, as is a rule
+ * set with nothing to add (no Convex URL).
+ */
+export declare function applyConvexSecurityDefaults(rules: SecurityRules, connectSrc: string[], resourceSrc: string[]): void;

package/dist/runtime/nuxt/csp.js

@@ -0,0 +1,46 @@
+function toHttpOrigin(raw) {
+  if (!raw) return void 0;
+  try {
+    return new URL(raw).origin;
+  } catch {
+    return void 0;
+  }
+}
+function toWsOrigin(raw) {
+  if (!raw) return void 0;
+  try {
+    const u = new URL(raw);
+    return `${u.protocol === "https:" ? "wss:" : "ws:"}//${u.host}`;
+  } catch {
+    return void 0;
+  }
+}
+function uniq(values) {
+  return Array.from(new Set(values.filter((v) => Boolean(v))));
+}
+export function convexConnectSrc(url, siteUrl) {
+  return uniq([toHttpOrigin(url), toWsOrigin(url), toHttpOrigin(siteUrl), toWsOrigin(siteUrl)]);
+}
+export function convexResourceSrc(url, siteUrl) {
+  return uniq([toHttpOrigin(url), toHttpOrigin(siteUrl)]);
+}
+export function applyConvexSecurityDefaults(rules, connectSrc, resourceSrc) {
+  if (connectSrc.length === 0 && resourceSrc.length === 0) return;
+  if (rules.headers === false) return;
+  if (typeof rules.headers !== "object" || rules.headers === null) rules.headers = {};
+  const headers = rules.headers;
+  if (headers.contentSecurityPolicy === false) return;
+  if (typeof headers.contentSecurityPolicy !== "object" || headers.contentSecurityPolicy === null) {
+    headers.contentSecurityPolicy = {};
+  }
+  const csp = headers.contentSecurityPolicy;
+  tightenDirective(csp, "connect-src", ["'self'"], connectSrc);
+  tightenDirective(csp, "img-src", ["'self'", "data:"], resourceSrc);
+  tightenDirective(csp, "media-src", ["'self'"], resourceSrc);
+}
+function tightenDirective(csp, name, baseline, additions) {
+  if (additions.length === 0) return;
+  const current = csp[name];
+  const existing = Array.isArray(current) ? current : typeof current === "string" ? current.split(/\s+/).filter(Boolean) : baseline;
+  csp[name] = uniq([...existing, ...additions]);
+}

package/dist/runtime/nuxt/index.d.ts

@@ -8,9 +8,12 @@
  *
  * ## Usage
  *
- * All exported functions assume that a Convex deployment URL is set in the
- * `NUXT_PUBLIC_CONVEX_URL` environment variable. `npx convex dev` will
- * automatically set it during local development.
+ * All exported functions assume that a Convex deployment URL is configured —
+ * `convex.url` in `nuxt.config`, `NUXT_PUBLIC_CONVEX_URL`, or the `CONVEX_URL`
+ * that `npx convex dev` writes to `.env.local`. Unlike its Next counterpart,
+ * `npx convex dev` does *not* set the framework-prefixed name for Nuxt: the
+ * Convex CLI has no Nuxt case in its framework detection, so it writes the
+ * unprefixed `CONVEX_URL`, which the module reads too.
  *
  * ### Preloading data
  *

package/dist/runtime/nuxt/security.d.ts

@@ -0,0 +1,33 @@
+import { type SecurityRules } from './csp.js';
+/**
+ * The slice of the Nitro app this plugin touches, typed locally: the hook's
+ * real declaration lives in the types nuxt-security generates into the app,
+ * which only exist when the app has it installed — and this plugin is only
+ * registered then. Nitro itself is not imported, so the published types don't
+ * depend on how the app resolves `nitropack`.
+ */
+export interface SecurityNitroApp {
+    hooks: {
+        hook: (name: 'nuxt-security:routeRules', fn: (rules: Record<string, SecurityRules>) => void) => unknown;
+    };
+}
+/**
+ * Nitro plugin: extend nuxt-security's Content Security Policy with the Convex
+ * origins. Registered by the module only when the nuxt-security integration is
+ * on (see `registerSecurity` in `module.ts`).
+ *
+ * Listens for `nuxt-security:routeRules`, which nuxt-security fires once its
+ * global config and every route rule are merged into one table — so the
+ * origins are appended to whatever the app configured, whatever the order of
+ * `modules`. nuxt-security sorts its own Nitro plugins last, so this listener
+ * is in place before the hook fires. The deployment URL comes from runtime
+ * config, so it need not be known at build time.
+ *
+ * `connect-src` is tightened only in production: creating it in dev would
+ * block the Vite HMR and devtools WebSockets, which run on ports `'self'`
+ * doesn't cover, while nuxt-security's defaults leave the directive open.
+ * `img-src` / `media-src` are widened in dev too — nuxt-security enforces its
+ * default `img-src 'self' data:` during `nuxt dev` as well, which would block
+ * files served from Convex storage.
+ */
+export default function convexSecurityPlugin(nitroApp: SecurityNitroApp): void;