@lupinum/better-convex-nuxt 0.8.0-beta.40

package/dist/runtime/server/utils/http.js

@@ -0,0 +1,133 @@
+import { CONVEX_MODULE_DEFAULTS } from "../../utils/config-defaults.js";
+export const DEFAULT_SERVER_FETCH_TIMEOUT_MS = 8e3;
+export const MAX_SERVER_AUTH_RESPONSE_BODY_BYTES = CONVEX_MODULE_DEFAULTS.authProxy.maxResponseBodyBytes;
+function createTimeoutSignal(timeoutMs, parentSignal) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort(new Error(`Request timed out after ${timeoutMs}ms`));
+  }, timeoutMs);
+  const abortFromParent = () => controller.abort(parentSignal?.reason);
+  if (parentSignal) {
+    if (parentSignal.aborted) {
+      abortFromParent();
+    } else {
+      parentSignal.addEventListener("abort", abortFromParent, { once: true });
+    }
+  }
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timeout);
+      if (parentSignal) {
+        parentSignal.removeEventListener("abort", abortFromParent);
+      }
+    }
+  };
+}
+export async function fetchWithTimeout(input, options = {}) {
+  const {
+    timeoutMs = DEFAULT_SERVER_FETCH_TIMEOUT_MS,
+    fetchImpl = fetch,
+    signal: parentSignal,
+    ...init
+  } = options;
+  const { signal, cleanup } = createTimeoutSignal(timeoutMs, parentSignal ?? void 0);
+  try {
+    const response = await fetchImpl(input, {
+      ...init,
+      signal
+    });
+    if (!response.body) {
+      cleanup();
+      return response;
+    }
+    const reader = response.body.getReader();
+    let bodyController;
+    let settled = false;
+    const finish = () => {
+      if (settled) return false;
+      settled = true;
+      signal.removeEventListener("abort", abortBody);
+      cleanup();
+      reader.releaseLock();
+      return true;
+    };
+    const cancelBody = (reason) => {
+      if (settled) return;
+      try {
+        void reader.cancel(reason).catch(() => {
+        });
+      } finally {
+        finish();
+      }
+    };
+    const abortBody = () => {
+      if (settled) return;
+      const reason = signal.reason ?? new Error("Request was aborted");
+      cancelBody(reason);
+      bodyController?.error(reason);
+    };
+    const body = new ReadableStream({
+      start(controller) {
+        bodyController = controller;
+        signal.addEventListener("abort", abortBody, { once: true });
+        if (signal.aborted) abortBody();
+      },
+      async pull(controller) {
+        if (settled) return;
+        try {
+          const next = await reader.read();
+          if (settled) return;
+          if (next.done) {
+            finish();
+            controller.close();
+          } else {
+            controller.enqueue(next.value);
+          }
+        } catch (error) {
+          if (finish()) controller.error(error);
+        }
+      },
+      cancel(reason) {
+        cancelBody(reason);
+      }
+    });
+    return new Response(body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}
+export async function readBoundedJson(response, maxBytes) {
+  const body = response.body;
+  if (!body) throw new SyntaxError("Response body is empty");
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel("Response body exceeded the size limit");
+        throw new Error("Response body exceeded the size limit");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const merged = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return JSON.parse(new TextDecoder().decode(merged));
+}

package/dist/runtime/server/utils/server-convex-caller.d.ts

@@ -0,0 +1,31 @@
+import type { FunctionReference, FunctionReturnType, OptionalRestArgs } from 'convex/server';
+import type { H3Event } from 'h3';
+import { type ServerConvexOptions } from './server-convex-options.js';
+export type { ServerConvexOptions };
+/**
+ * One request-scoped server caller ("Caller-owned token promise").
+ *
+ * A caller owns exactly one lazy authentication token promise and one lazy
+ * `ConvexHttpClient`; `setAuth` runs at most once, when a token exists. The
+ * operation methods use Convex's native optional-rest-args contract, so exact
+ * no-argument references omit the artificial `{}` argument while references
+ * with declared arguments remain required and inferred.
+ */
+export interface ServerConvexCaller {
+    getToken(): Promise<string | null>;
+    query<Query extends FunctionReference<'query'>>(query: Query, ...args: OptionalRestArgs<Query>): Promise<FunctionReturnType<Query>>;
+    mutation<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, ...args: OptionalRestArgs<Mutation>): Promise<FunctionReturnType<Mutation>>;
+    action<Action extends FunctionReference<'action'>>(action: Action, ...args: OptionalRestArgs<Action>): Promise<FunctionReturnType<Action>>;
+}
+/**
+ * Construct a request-scoped Convex server caller .
+ *
+ * The caller lazily resolves one authentication token and one
+ * `ConvexHttpClient` (built with `logger: false` so arbitrary Convex function
+ * log lines are not re-emitted, and the shared bounded fetch so abort, deadline,
+ * response-size, and transport classification remain request-scoped). A
+ * rejected token or client promise stays rejected for this caller; retrying
+ * requires a new caller. Neither promise is stored on the event nor keyed by
+ * option hash.
+ */
+export declare function serverConvex(event: H3Event, options?: ServerConvexOptions): ServerConvexCaller;

package/dist/runtime/server/utils/server-convex-caller.js

@@ -0,0 +1,151 @@
+import { ConvexHttpClient } from "convex/browser";
+import { ConvexCallError, normalizeConvexError } from "../../errors/index.js";
+import { createBoundedConvexFetch } from "../../utils/bounded-convex-fetch.js";
+import { normalizeConvexRuntimeConfig } from "../../utils/runtime-config-normalize.js";
+import { filterBetterAuthCookies, getBetterAuthSessionToken } from "../../utils/shared-helpers.js";
+import {
+  validateServerConvexOptions
+} from "./server-convex-options.js";
+import { exchangeConvexToken } from "./token-exchange.js";
+function readCallerConfig(event) {
+  const context = event.context;
+  const runtimeConfig = context.nitro?.runtimeConfig;
+  return normalizeConvexRuntimeConfig(runtimeConfig?.public?.convex);
+}
+function readRequiredConvexUrl(event) {
+  const url = readCallerConfig(event).url;
+  if (!url) {
+    throw new ConvexCallError({
+      kind: "unknown",
+      message: "Convex URL is not configured for serverConvex"
+    });
+  }
+  return url;
+}
+function readCookieHeader(event) {
+  const directHeader = event.headers;
+  if (directHeader?.get) {
+    return directHeader.get("cookie");
+  }
+  const nodeHeaders = event.node?.req?.headers;
+  const raw = nodeHeaders?.cookie;
+  if (Array.isArray(raw)) return raw.join("; ");
+  return typeof raw === "string" ? raw : null;
+}
+function authenticationRequiredError(status = 401) {
+  return new ConvexCallError({
+    kind: "authentication",
+    message: "Convex authentication is required for this server call",
+    status
+  });
+}
+function throwExchangeFailure(result) {
+  throw result.error ?? new ConvexCallError({
+    kind: "transport",
+    message: "Convex token exchange could not complete"
+  });
+}
+async function resolveServerToken(event, normalized) {
+  if (normalized.authToken) {
+    return normalized.authToken;
+  }
+  const config = readCallerConfig(event);
+  const required = normalized.auth === "required";
+  if (config.auth === false) {
+    if (normalized.credential || required) throw authenticationRequiredError();
+    return null;
+  }
+  if (normalized.credential) {
+    if (!config.siteUrl) throw authenticationRequiredError();
+    const result2 = await exchangeConvexToken({
+      event,
+      siteUrl: config.siteUrl,
+      credential: normalized.credential,
+      trustedClientIpHeader: config.auth.trustedClientIpHeader
+    });
+    if (result2.token) return result2.token;
+    throwExchangeFailure(result2);
+  }
+  if (normalized.auth === "none") return null;
+  const cookieHeader = readCookieHeader(event);
+  const sessionToken = getBetterAuthSessionToken(cookieHeader);
+  const authCookieHeader = filterBetterAuthCookies(cookieHeader);
+  if (!authCookieHeader || !sessionToken) {
+    if (required) throw authenticationRequiredError();
+    return null;
+  }
+  if (!config.siteUrl) {
+    if (required) throw authenticationRequiredError();
+    return null;
+  }
+  const result = await exchangeConvexToken({
+    event,
+    siteUrl: config.siteUrl,
+    credential: { type: "cookie", value: authCookieHeader },
+    trustedClientIpHeader: config.auth.trustedClientIpHeader
+  });
+  if (result.token) return result.token;
+  if (result.status === 401 || result.status === 403) {
+    if (required) throw authenticationRequiredError(result.status);
+    return null;
+  }
+  throwExchangeFailure(result);
+}
+export function serverConvex(event, options = {}) {
+  const normalized = validateServerConvexOptions(options);
+  const boundedFetch = createBoundedConvexFetch({
+    signal: event.web?.request?.signal
+  });
+  let tokenPromise = null;
+  let clientPromise = null;
+  const getToken = () => {
+    tokenPromise ??= resolveServerToken(event, normalized);
+    return tokenPromise;
+  };
+  const getClient = () => {
+    clientPromise ??= (async () => {
+      const client = new ConvexHttpClient(readRequiredConvexUrl(event), {
+        fetch: boundedFetch,
+        logger: false
+      });
+      const token = await getToken();
+      if (token) client.setAuth(token);
+      return client;
+    })();
+    return clientPromise;
+  };
+  const prepareClient = async () => {
+    const token = await getToken();
+    if (normalized.auth === "required" && !token) {
+      throw authenticationRequiredError();
+    }
+    return getClient();
+  };
+  return {
+    getToken,
+    async query(query, ...args) {
+      const client = await prepareClient();
+      try {
+        return await client.query(query, ...args);
+      } catch (error) {
+        throw normalizeConvexError(error);
+      }
+    },
+    async mutation(mutation, ...args) {
+      const client = await prepareClient();
+      try {
+        return await client.mutation(mutation, ...args);
+      } catch (error) {
+        throw normalizeConvexError(error);
+      }
+    },
+    async action(action, ...args) {
+      const client = await prepareClient();
+      try {
+        return await client.action(action, ...args);
+      } catch (error) {
+        throw normalizeConvexError(error);
+      }
+    }
+  };
+}

package/dist/runtime/server/utils/server-convex-options.d.ts

@@ -0,0 +1,83 @@
+import type { ConvexAuthMode } from '../../utils/auth-status.js';
+/**
+ * A low-level Better Auth cookie credential handed to `serverConvex` for an
+ * explicit principal. The value is a raw `Cookie` header string.
+ */
+export type ConvexCredential = {
+    type: 'cookie';
+    value: string;
+};
+/**
+ * Public per-caller options for `serverConvex`.
+ *
+ * Cookie policy, an explicit Convex token, and an explicit Better Auth cookie
+ * credential are three mutually exclusive call modes. An explicit principal
+ * always requires authentication, so those branches deliberately do not accept
+ * a redundant `auth: 'required'` field.
+ */
+export type ServerConvexOptions = {
+    auth?: ConvexAuthMode;
+    authToken?: never;
+    credential?: never;
+} | {
+    auth?: never;
+    authToken: string;
+    credential?: never;
+} | {
+    auth?: never;
+    authToken?: never;
+    credential: ConvexCredential;
+};
+/**
+ * The validated, resolved options a caller operates on. `auth` is always a
+ * concrete mode: cookie-based callers default to a fixed `optional`, while an
+ * explicit principal resolves to `required`.
+ */
+export type NormalizedServerConvexOptions = {
+    auth: ConvexAuthMode;
+    authToken?: never;
+    credential?: never;
+} | {
+    auth: 'required';
+    authToken: string;
+    credential?: never;
+} | {
+    auth: 'required';
+    authToken?: never;
+    credential: ConvexCredential;
+};
+/**
+ * Synchronous validation failure for server-call options and credential values
+ * . This is deliberately NOT a {@link ConvexCallError}: the public
+ * error contract  has no `validation` kind, and an option/credential
+ * contract violation is a caller programming error surfaced before any network
+ * access — not a classifiable Convex call outcome. Callers that construct a
+ * `serverConvex` caller receive this synchronously, before a request is ever
+ * made.
+ */
+export declare class ServerConvexValidationError extends Error {
+    constructor(message: string);
+}
+export declare function credentialHasControlChars(value: string): boolean;
+/**
+ * Reject an empty or control-character-bearing credential value synchronously,
+ * before any network access . Shared by option validation and by the
+ * exchange primitive so both refuse a smuggling-capable credential at the door.
+ */
+export declare function assertCredentialValueSafe(value: unknown, label: string): asserts value is string;
+export declare function assertConvexCredentialShape(credential: unknown): asserts credential is ConvexCredential;
+/**
+ * Validate and normalize {@link ServerConvexOptions} synchronously (public
+ * "Validation rules"). Throws {@link ServerConvexValidationError} — before any
+ * network access — for every invalid combination rather than silently
+ * downgrading a rejected explicit principal.
+ *
+ * Rules:
+ * - `authToken` and `credential` are mutually exclusive.
+ * - Providing either implies `required`; every explicit `auth` field is
+ *   rejected as redundant or contradictory.
+ * - An empty or control-character token/credential value is rejected.
+ * - With no explicit principal, cookie-based resolution defaults to a fixed
+ *   `optional`.
+ */
+export declare function validateServerConvexOptions(options?: ServerConvexOptions): NormalizedServerConvexOptions;

package/dist/runtime/server/utils/server-convex-options.js

@@ -0,0 +1,69 @@
+export class ServerConvexValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ServerConvexValidationError";
+  }
+}
+const ASCII_CONTROL_MAX = 31;
+const ASCII_DEL = 127;
+export function credentialHasControlChars(value) {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code <= ASCII_CONTROL_MAX || code === ASCII_DEL) return true;
+  }
+  return false;
+}
+export function assertCredentialValueSafe(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ServerConvexValidationError(`${label} must be a non-empty string`);
+  }
+  if (credentialHasControlChars(value)) {
+    throw new ServerConvexValidationError(`${label} must not contain control characters`);
+  }
+}
+export function assertConvexCredentialShape(credential) {
+  if (!credential || typeof credential !== "object") {
+    throw new ServerConvexValidationError("credential must be a cookie credential");
+  }
+  const type = credential.type;
+  if (type !== "cookie") {
+    throw new ServerConvexValidationError("credential must be a cookie credential");
+  }
+}
+function assertConvexAuthMode(auth) {
+  if (auth !== void 0 && auth !== "required" && auth !== "optional" && auth !== "none") {
+    throw new ServerConvexValidationError("auth must be one of 'required', 'optional', or 'none'");
+  }
+}
+export function validateServerConvexOptions(options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new ServerConvexValidationError("serverConvex options must be an object");
+  }
+  const { auth, authToken, credential } = options;
+  const hasToken = authToken !== void 0;
+  const hasCredential = credential !== void 0;
+  assertConvexAuthMode(auth);
+  if (hasToken && hasCredential) {
+    throw new ServerConvexValidationError(
+      "authToken and credential are mutually exclusive; provide at most one"
+    );
+  }
+  if (hasToken) {
+    assertCredentialValueSafe(authToken, "authToken");
+  }
+  if (hasCredential) {
+    assertConvexCredentialShape(credential);
+    assertCredentialValueSafe(credential.value, "credential value");
+  }
+  const hasExplicitPrincipal = hasToken || hasCredential;
+  if (hasExplicitPrincipal) {
+    if (auth !== void 0) {
+      throw new ServerConvexValidationError(
+        "auth must be omitted when authToken or credential is provided; an explicit principal already requires authentication"
+      );
+    }
+    if (hasToken) return { auth: "required", authToken };
+    if (hasCredential) return { auth: "required", credential };
+  }
+  return { auth: auth ?? "optional" };
+}

package/dist/runtime/server/utils/signed-client-ip.d.ts

@@ -0,0 +1,6 @@
+import type { H3Event } from 'h3';
+export interface SignedClientIpHeadersOptions {
+    trustedClientIpHeader?: string | null;
+}
+/** Build the complete authenticated client-IP pair for one Nuxt-to-Convex hop. */
+export declare function buildSignedClientIpHeaders(event: H3Event, options: SignedClientIpHeadersOptions): Promise<Record<string, string>>;

package/dist/runtime/server/utils/signed-client-ip.js

@@ -0,0 +1,29 @@
+import {
+  CLIENT_IP_HEADER,
+  CLIENT_IP_SIGNATURE_HEADER,
+  normalizeClientIp,
+  requireProxyIpSecret,
+  signClientIp
+} from "../../shared/client-ip.js";
+function readRequestHeader(event, name) {
+  const directHeaders = event.headers;
+  const direct = directHeaders?.get?.(name);
+  if (direct !== null && direct !== void 0) return direct;
+  const nodeHeaders = event.node?.req?.headers;
+  const value = nodeHeaders?.[name.toLowerCase()];
+  if (Array.isArray(value)) return value.join(",");
+  return typeof value === "string" ? value : null;
+}
+export async function buildSignedClientIpHeaders(event, options) {
+  const trustedHeader = options.trustedClientIpHeader;
+  if (!trustedHeader) return {};
+  const clientIp = normalizeClientIp(readRequestHeader(event, trustedHeader));
+  if (!clientIp) {
+    throw new TypeError("Trusted client IP header must contain exactly one valid IP address");
+  }
+  const secret = requireProxyIpSecret(process.env.BCN_AUTH_PROXY_IP_SECRET);
+  return {
+    [CLIENT_IP_HEADER]: clientIp,
+    [CLIENT_IP_SIGNATURE_HEADER]: await signClientIp(clientIp, secret)
+  };
+}

package/dist/runtime/server/utils/ssr-auth-headers.d.ts

@@ -0,0 +1,26 @@
+import { type H3Event } from 'h3';
+/**
+ * Merge `Cookie` into an existing `Vary` header value without dropping any
+ * caller-set field ("Vary/Cache-Control"). Existing tokens are
+ * preserved, whitespace is normalized, and `Cookie` is added exactly once
+ * (case-insensitively) so an auth-enabled SSR response always varies by cookie
+ * while a pre-existing `Vary: Accept-Encoding` survives. `Vary: *` already
+ * varies on every request property and must remain the sole field value.
+ */
+export declare function mergeVaryCookie(existing: string | number | string[] | undefined | null): string;
+/**
+ * Apply the SSR auth cache policy to the current response :
+ *
+ * - Every auth-enabled SSR response appends `Vary: Cookie`, preserving existing
+ *   `Vary` values so a shared cache keys per cookie.
+ * - A request carrying a recognized Better Auth cookie, or any response that
+ *   serializes a token, additionally gets `Cache-Control: private, no-store`.
+ *   Invalid/revoked sessions remain request-specific even when no token is
+ *   produced, and a per-user JWT is never cacheable without a cookie signal.
+ *   Shared-cache override headers already present on the response are removed;
+ *   an operator/CDN rule that rewrites headers after this point remains external.
+ */
+export declare function applyConvexAuthSsrHeaders(event: H3Event, options: {
+    hasBetterAuthCookie: boolean;
+    serializesToken: boolean;
+}): void;

package/dist/runtime/server/utils/ssr-auth-headers.js

@@ -0,0 +1,49 @@
+import {
+  getResponseHeader,
+  getResponseHeaders,
+  removeResponseHeader,
+  setResponseHeader
+} from "h3";
+const SHARED_CACHE_CONTROL_HEADERS = /* @__PURE__ */ new Set([
+  "cdn-cache-control",
+  "edge-control",
+  "surrogate-control",
+  "x-accel-expires"
+]);
+function removeSharedCacheOverrides(event) {
+  for (const name of Object.keys(getResponseHeaders(event))) {
+    const lower = name.toLowerCase();
+    if (SHARED_CACHE_CONTROL_HEADERS.has(lower) || lower.endsWith("-cdn-cache-control")) {
+      removeResponseHeader(event, name);
+    }
+  }
+}
+export function mergeVaryCookie(existing) {
+  const values = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (raw) => {
+    for (const part of raw.split(",")) {
+      const token = part.trim();
+      if (!token) continue;
+      const key = token.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      values.push(token);
+    }
+  };
+  if (Array.isArray(existing)) {
+    for (const entry of existing) push(String(entry));
+  } else if (existing !== void 0 && existing !== null) {
+    push(String(existing));
+  }
+  if (seen.has("*")) return "*";
+  if (!seen.has("cookie")) values.push("Cookie");
+  return values.join(", ");
+}
+export function applyConvexAuthSsrHeaders(event, options) {
+  setResponseHeader(event, "Vary", mergeVaryCookie(getResponseHeader(event, "Vary")));
+  if (options.hasBetterAuthCookie || options.serializesToken) {
+    removeSharedCacheOverrides(event);
+    setResponseHeader(event, "Cache-Control", "private, no-store");
+  }
+}

package/dist/runtime/server/utils/token-exchange.d.ts

@@ -0,0 +1,27 @@
+import type { H3Event } from 'h3';
+import { ConvexCallError } from '../../errors/index.js';
+import type { ConvexCredential } from './server-convex-options.js';
+/**
+ * The never-throwing result of a cookie -> Convex JWT exchange
+ * (architecture invariant).
+ *
+ * Success returns a non-null `token`, a 2xx `status`, and `error: null`.
+ * A network/HTTP failure returns `token: null`, exactly one `error`, and the
+ * upstream `status` when one exists. This is intentionally NOT an
+ * `ok`-discriminated union; the invariants above are pinned by tests.
+ */
+export interface ConvexTokenExchangeResult {
+    token: string | null;
+    status: number | undefined;
+    error: ConvexCallError | null;
+}
+interface RequestBoundTokenExchangeInput {
+    event: H3Event;
+    siteUrl: string;
+    credential: ConvexCredential;
+    trustedClientIpHeader: string;
+    timeoutMs?: number;
+}
+/** Request-aware exchange used by every shipped Nitro auth path. */
+export declare function exchangeConvexToken(input: RequestBoundTokenExchangeInput): Promise<ConvexTokenExchangeResult>;
+export {};