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

package/dist/runtime/server/utils/token-exchange.js

@@ -0,0 +1,96 @@
+import { ConvexCallError } from "../../errors/index.js";
+import { filterBetterAuthCookies, getBetterAuthSessionToken } from "../../utils/shared-helpers.js";
+import { normalizeConvexSiteUrl } from "../../utils/site-url.js";
+import { fetchWithTimeout, MAX_SERVER_AUTH_RESPONSE_BODY_BYTES, readBoundedJson } from "./http.js";
+import {
+  assertConvexCredentialShape,
+  assertCredentialValueSafe,
+  ServerConvexValidationError
+} from "./server-convex-options.js";
+import { buildSignedClientIpHeaders } from "./signed-client-ip.js";
+const TOKEN_EXCHANGE_PATH = "/api/auth/convex/token";
+const DEFAULT_TOKEN_EXCHANGE_TIMEOUT_MS = 5e3;
+function readToken(body) {
+  if (body && typeof body === "object") {
+    const token = body.token;
+    if (typeof token === "string" && token.length > 0) return token;
+  }
+  return null;
+}
+function validateTokenExchangeCredential(credential) {
+  assertConvexCredentialShape(credential);
+  assertCredentialValueSafe(credential.value, "credential value");
+  const cookieHeader = filterBetterAuthCookies(credential.value);
+  const sessionToken = getBetterAuthSessionToken(cookieHeader);
+  if (!cookieHeader || !sessionToken) {
+    throw new ServerConvexValidationError(
+      "credential must contain a non-empty supported Better Auth session cookie"
+    );
+  }
+  return cookieHeader;
+}
+export function exchangeConvexToken(input) {
+  const cookieHeader = validateTokenExchangeCredential(input.credential);
+  return (async () => {
+    try {
+      const clientIpHeaders = await buildSignedClientIpHeaders(input.event, {
+        trustedClientIpHeader: input.trustedClientIpHeader
+      });
+      return await runTokenExchange(input, { ...clientIpHeaders, Cookie: cookieHeader });
+    } catch {
+      return tokenExchangeTransportFailure();
+    }
+  })();
+}
+function tokenExchangeTransportFailure() {
+  return {
+    token: null,
+    status: void 0,
+    error: new ConvexCallError({
+      kind: "transport",
+      message: "Convex token exchange could not complete"
+    })
+  };
+}
+async function runTokenExchange(input, headers) {
+  try {
+    const response = await fetchWithTimeout(
+      `${normalizeConvexSiteUrl(input.siteUrl)}${TOKEN_EXCHANGE_PATH}`,
+      {
+        method: "GET",
+        headers,
+        redirect: "error",
+        timeoutMs: input.timeoutMs ?? DEFAULT_TOKEN_EXCHANGE_TIMEOUT_MS
+      }
+    );
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => {
+      });
+      return {
+        token: null,
+        status: response.status,
+        error: new ConvexCallError({
+          kind: response.status === 401 || response.status === 403 ? "authentication" : "transport",
+          message: `Convex token exchange failed with HTTP ${response.status}`,
+          status: response.status
+        })
+      };
+    }
+    const parsed = await readBoundedJson(response, MAX_SERVER_AUTH_RESPONSE_BODY_BYTES);
+    const token = readToken(parsed);
+    if (!token) {
+      return {
+        token: null,
+        status: response.status,
+        error: new ConvexCallError({
+          kind: "transport",
+          message: "Convex token exchange response did not include a token",
+          status: response.status
+        })
+      };
+    }
+    return { token, status: response.status, error: null };
+  } catch {
+    return tokenExchangeTransportFailure();
+  }
+}

package/dist/runtime/shared/auth-cookie.d.ts

@@ -0,0 +1,4 @@
+/** The only cookie namespace supported by the Nuxt auth boundary. */
+export declare function isBetterAuthCookieName(name: string): boolean;
+/** Whether a request presents any supported Better Auth cookie name, even malformed. */
+export declare function hasBetterAuthCookie(cookieHeader: string | null | undefined): boolean;

package/dist/runtime/shared/auth-cookie.js

@@ -0,0 +1,25 @@
+const COOKIE_NAME_PATTERN = /^[!#$%&'*+\-.^`|~\w]+$/;
+function trimOptionalWhitespace(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && (value.charCodeAt(start) === 32 || value.charCodeAt(start) === 9)) {
+    start += 1;
+  }
+  while (end > start && (value.charCodeAt(end - 1) === 32 || value.charCodeAt(end - 1) === 9)) {
+    end -= 1;
+  }
+  return start === 0 && end === value.length ? value : value.slice(start, end);
+}
+export function isBetterAuthCookieName(name) {
+  if (!COOKIE_NAME_PATTERN.test(name)) return false;
+  const unprefixed = name.startsWith("__Secure-") ? name.slice("__Secure-".length) : name;
+  return unprefixed.startsWith("better-auth.") && unprefixed.length > "better-auth.".length;
+}
+export function hasBetterAuthCookie(cookieHeader) {
+  if (!cookieHeader) return false;
+  return cookieHeader.split(";").some((chunk) => {
+    const separator = chunk.indexOf("=");
+    const name = trimOptionalWhitespace(separator === -1 ? chunk : chunk.slice(0, separator));
+    return isBetterAuthCookieName(name);
+  });
+}

package/dist/runtime/shared/auth-origin.d.ts

@@ -0,0 +1,15 @@
+export type AuthOriginName = 'SITE_URL' | 'CONVEX_SITE_URL' | 'auth.origin' | 'convex.url' | 'convex.siteUrl';
+/**
+ * Return whether a URL parser hostname is one of the three exact development
+ * loopback forms supported by the auth boundary.
+ *
+ * This intentionally does not accept `*.localhost`, the rest of 127/8, IPv4
+ * aliases, or expanded/mapped IPv6 forms. Callers must first prove that the
+ * complete URL already uses its canonical serialization so the URL parser
+ * cannot turn an ambiguous spelling into one of these values.
+ */
+export declare function isExactLoopbackHost(hostname: string): boolean;
+/** Return one canonical, credential-free HTTP(S) origin or throw. */
+export declare function normalizeAuthOrigin(input: string, name: AuthOriginName): string;
+/** Read and validate a required auth origin from an environment-like object. */
+export declare function requireAuthOrigin(name: 'SITE_URL' | 'CONVEX_SITE_URL', env: Readonly<Record<string, string | undefined>>): string;

package/dist/runtime/shared/auth-origin.js

@@ -0,0 +1,42 @@
+export function isExactLoopbackHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+export function normalizeAuthOrigin(input, name) {
+  if (typeof input !== "string" || input.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string URL origin`);
+  }
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new TypeError(`${name} must be a valid URL origin`);
+  }
+  if (url.username || url.password) {
+    throw new TypeError(`${name} must not contain credentials`);
+  }
+  if (url.search || url.hash) {
+    throw new TypeError(`${name} must not contain a query string or fragment`);
+  }
+  if (url.pathname !== "/") {
+    throw new TypeError(`${name} must not contain a path`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new TypeError(`${name} must use http or https`);
+  }
+  if (url.hostname.endsWith(".")) {
+    throw new TypeError(`${name} must not use a trailing-dot hostname`);
+  }
+  const inputWithoutOneTrailingSlash = input.endsWith("/") ? input.slice(0, -1) : input;
+  if (inputWithoutOneTrailingSlash !== url.origin) {
+    throw new TypeError(`${name} must use its canonical URL serialization`);
+  }
+  if (url.protocol === "http:" && !isExactLoopbackHost(url.hostname)) {
+    throw new TypeError(`${name} must use https outside exact loopback development hosts`);
+  }
+  return url.origin;
+}
+export function requireAuthOrigin(name, env) {
+  const value = env[name];
+  if (!value) throw new TypeError(`${name} is required`);
+  return normalizeAuthOrigin(value, name);
+}

package/dist/runtime/shared/bounded-stream.d.ts

@@ -0,0 +1,2 @@
+export declare function bodyChunkBytes(chunk: unknown): Uint8Array;
+export declare function readStreamWithByteLimit(stream: ReadableStream<unknown> | null | undefined, maxBytes: number, createSizeError: (observedBytes: number, maxBytes: number) => unknown, signal?: AbortSignal): Promise<Uint8Array | undefined>;

package/dist/runtime/shared/bounded-stream.js

@@ -0,0 +1,50 @@
+export function bodyChunkBytes(chunk) {
+  if (chunk instanceof Uint8Array) return chunk;
+  if (chunk instanceof ArrayBuffer) return new Uint8Array(chunk);
+  if (typeof chunk === "string") return new TextEncoder().encode(chunk);
+  throw new TypeError("[better-convex-nuxt] Body stream yielded an unsupported chunk.");
+}
+async function readNextChunk(reader, signal) {
+  if (!signal) return await reader.read();
+  if (signal.aborted) throw signal.reason;
+  return await new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason ?? new Error("Body read was aborted"));
+    signal.addEventListener("abort", abort, { once: true });
+    reader.read().then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+function cancelReader(reader, reason) {
+  try {
+    void reader.cancel(reason).catch(() => {
+    });
+  } catch {
+  }
+}
+export async function readStreamWithByteLimit(stream, maxBytes, createSizeError, signal) {
+  if (!stream) return void 0;
+  const reader = stream.getReader();
+  const chunks = [];
+  let totalBytes = 0;
+  try {
+    while (true) {
+      const { done, value } = await readNextChunk(reader, signal);
+      if (done) break;
+      const chunk = bodyChunkBytes(value);
+      totalBytes += chunk.byteLength;
+      if (totalBytes > maxBytes) throw createSizeError(totalBytes, maxBytes);
+      chunks.push(chunk);
+    }
+  } catch (error) {
+    cancelReader(reader, error);
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+  const body = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}

package/dist/runtime/shared/client-ip.d.ts

@@ -0,0 +1,21 @@
+/** Reserved request headers used only between the Nuxt proxy and Convex. */
+export declare const CLIENT_IP_HEADER = "x-bcn-client-ip";
+export declare const CLIENT_IP_SIGNATURE_HEADER = "x-bcn-client-ip-signature";
+export declare const VERIFIED_CLIENT_IP_HEADER = "x-bcn-verified-client-ip";
+/**
+ * Parse one unambiguous IP literal and return its canonical text form.
+ * Forwarding chains, ports, zone identifiers, whitespace, and control bytes
+ * are deliberately outside this protocol.
+ */
+export declare function normalizeClientIp(value: string | null | undefined): string | null;
+/** Throw when the proxy IP secret cannot safely key HMAC-SHA-256. */
+export declare function requireProxyIpSecret(secret: string | null | undefined): string;
+/** Sign one canonical client IP for the private Nuxt-to-Convex hop. */
+export declare function signClientIp(clientIp: string, secret: string): Promise<string>;
+/**
+ * Verify a complete signed pair and return only a canonical authenticated IP.
+ * Invalid configuration and malformed attacker input are indistinguishable to
+ * callers. An absent pair permits direct Convex request metadata; once either
+ * reserved header is present, the component rejects an invalid pair.
+ */
+export declare function verifySignedClientIp(clientIp: string | null, signature: string | null, secret: string | null | undefined): Promise<string | null>;

package/dist/runtime/shared/client-ip.js

@@ -0,0 +1,123 @@
+const HMAC_ALGORITHM = "HMAC";
+const HMAC_HASH = "SHA-256";
+const SIGNATURE_PREFIX = "v1\n";
+const MAX_CLIENT_IP_INPUT_LENGTH = 45;
+const HMAC_SHA256_BYTE_LENGTH = 32;
+const HMAC_SHA256_BASE64URL_LENGTH = 43;
+const MIN_PROXY_IP_SECRET_BYTE_LENGTH = 32;
+const MAX_PROXY_IP_SECRET_BYTE_LENGTH = 1024;
+export const CLIENT_IP_HEADER = "x-bcn-client-ip";
+export const CLIENT_IP_SIGNATURE_HEADER = "x-bcn-client-ip-signature";
+export const VERIFIED_CLIENT_IP_HEADER = "x-bcn-verified-client-ip";
+function hasUnsafeHeaderCharacter(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 32 || code === 127) return true;
+  }
+  return false;
+}
+function normalizeIpv4(value) {
+  const parts = value.split(".");
+  if (parts.length !== 4) return null;
+  for (const part of parts) {
+    if (!/^(?:0|[1-9]\d{0,2})$/.test(part)) return null;
+    if (Number(part) > 255) return null;
+  }
+  return parts.join(".");
+}
+function normalizeIpv6(value) {
+  if (!value.includes(":") || value.includes("%") || value.includes("[") || value.includes("]")) {
+    return null;
+  }
+  try {
+    const hostname = new URL(`http://[${value}]/`).hostname;
+    if (!hostname.startsWith("[") || !hostname.endsWith("]")) return null;
+    return hostname.slice(1, -1).toLowerCase();
+  } catch {
+    return null;
+  }
+}
+export function normalizeClientIp(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_CLIENT_IP_INPUT_LENGTH || hasUnsafeHeaderCharacter(value) || value.includes(",")) {
+    return null;
+  }
+  return value.includes(":") ? normalizeIpv6(value) : normalizeIpv4(value);
+}
+function secretBytes(secret) {
+  if (typeof secret !== "string") return null;
+  const bytes = new TextEncoder().encode(secret);
+  if (bytes.byteLength < MIN_PROXY_IP_SECRET_BYTE_LENGTH || bytes.byteLength > MAX_PROXY_IP_SECRET_BYTE_LENGTH) {
+    return null;
+  }
+  return bytes;
+}
+function ownedArrayBuffer(bytes) {
+  const owned = new Uint8Array(bytes.byteLength);
+  owned.set(bytes);
+  return owned.buffer;
+}
+export function requireProxyIpSecret(secret) {
+  if (!secretBytes(secret)) {
+    throw new TypeError("BCN_AUTH_PROXY_IP_SECRET must contain 32 to 1024 UTF-8 bytes");
+  }
+  return secret;
+}
+function bytesToBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+function strictBase64UrlSignature(value) {
+  if (typeof value !== "string" || value.length !== HMAC_SHA256_BASE64URL_LENGTH || !/^[\w-]{43}$/.test(value)) {
+    return null;
+  }
+  try {
+    const base64 = `${value.replaceAll("-", "+").replaceAll("_", "/")}=`;
+    const binary = atob(base64);
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    if (bytes.byteLength !== HMAC_SHA256_BYTE_LENGTH) return null;
+    return bytesToBase64Url(bytes) === value ? bytes : null;
+  } catch {
+    return null;
+  }
+}
+async function importHmacKey(secret) {
+  return crypto.subtle.importKey(
+    "raw",
+    ownedArrayBuffer(secretBytes(secret)),
+    { name: HMAC_ALGORITHM, hash: HMAC_HASH },
+    false,
+    ["sign", "verify"]
+  );
+}
+function signatureInput(clientIp) {
+  return ownedArrayBuffer(new TextEncoder().encode(`${SIGNATURE_PREFIX}${clientIp}`));
+}
+export async function signClientIp(clientIp, secret) {
+  const normalized = normalizeClientIp(clientIp);
+  if (!normalized) throw new TypeError("Client IP must be one valid IP literal");
+  requireProxyIpSecret(secret);
+  const signature = await crypto.subtle.sign(
+    HMAC_ALGORITHM,
+    await importHmacKey(secret),
+    signatureInput(normalized)
+  );
+  return bytesToBase64Url(new Uint8Array(signature));
+}
+export async function verifySignedClientIp(clientIp, signature, secret) {
+  const normalized = normalizeClientIp(clientIp);
+  const signatureBytes = strictBase64UrlSignature(signature);
+  const keyBytes = secretBytes(secret);
+  if (!normalized || normalized !== clientIp || !signatureBytes || !keyBytes) return null;
+  try {
+    const verified = await crypto.subtle.verify(
+      HMAC_ALGORITHM,
+      await importHmacKey(secret),
+      ownedArrayBuffer(signatureBytes),
+      signatureInput(normalized)
+    );
+    return verified ? normalized : null;
+  } catch {
+    return null;
+  }
+}

package/dist/runtime/shared/release-fingerprint.d.ts

@@ -0,0 +1,5 @@
+export declare const PACKED_RUNTIME_FINGERPRINT_HEADER = "x-bcn-runtime-fingerprint";
+/** Undefined in ordinary source/dev builds; populated only in immutable release bytes. */
+export declare function getPackedRuntimeFingerprint(): string | undefined;
+/** Bind a package-owned Web Response to the immutable candidate that produced it. */
+export declare function bindPackedRuntimeFingerprint(response: Response): Response;

package/dist/runtime/shared/release-fingerprint.js

@@ -0,0 +1,17 @@
+const packedRuntimeFingerprint = "bcn-release-v1-9ddfb9636940ef0e3412c414c75947f5cbf3406fa22175219d58923c455bfd07";
+const packedRuntimeFingerprintPattern = /^bcn-release-v1-[0-9a-f]{64}$/u;
+export const PACKED_RUNTIME_FINGERPRINT_HEADER = "x-bcn-runtime-fingerprint";
+export function getPackedRuntimeFingerprint() {
+  return packedRuntimeFingerprintPattern.test(packedRuntimeFingerprint) ? packedRuntimeFingerprint : void 0;
+}
+export function bindPackedRuntimeFingerprint(response) {
+  const fingerprint = getPackedRuntimeFingerprint();
+  if (!fingerprint) return response;
+  const headers = new Headers(response.headers);
+  headers.set(PACKED_RUNTIME_FINGERPRINT_HEADER, fingerprint);
+  return new Response(response.body, {
+    headers,
+    status: response.status,
+    statusText: response.statusText
+  });
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,19 @@
+import type { ConvexRuntimeContext } from './runtime-context'
+
+// The public `$convex` and `$auth` Nuxt-app property augmentations are deleted
+// : consumers use the stable `useConvex()` handle and the auth
+// composables, never a raw replaceable client or generic Nuxt injection. The
+// augmentations below are INTERNAL inter-plugin seams (browser-only).
+declare module '#app' {
+  interface NuxtApp {
+    /**
+     * The per-Nuxt-app client owner (architecture invariant). Sole source of
+     * truth for the replaceable primary and lazy anonymous clients; `useConvex()`
+     * returns its stable handle and `useConvexConnectionState()` observes its
+     * connection store. Provided by the core client plugin (browser only).
+     */
+    $convexRuntime?: ConvexRuntimeContext
+  }
+}
+
+export {}

package/dist/runtime/utils/auth-config.d.ts

@@ -0,0 +1,24 @@
+/** Build-time authentication options. An object opts the application into auth. */
+export interface ConvexAuthOptions {
+    /** Exact public Nuxt application origin used by the same-origin auth proxy. */
+    origin: string;
+    /** Optional build-time Better Auth client definition. Never copied to runtime config. */
+    client?: string;
+    /** Trusted ingress-owned header containing exactly one client IP address. */
+    trustedClientIpHeader?: string;
+    /** Local route used when protected navigation needs authentication. */
+    redirectTo?: string;
+}
+/** Internal materialized auth policy. `false` exists only for a no-auth build. */
+export type NormalizedConvexAuthConfig = false | Readonly<{
+    origin: string;
+    trustedClientIpHeader: string;
+    redirectTo: string;
+}>;
+/**
+ * Normalize the build grammar. Omission is a genuine Convex-only build; an
+ * object opts into auth and must name its one exact public application origin.
+ * `false` remains a Nuxt-layer tombstone for removing inherited auth options.
+ */
+export declare function normalizeConvexAuthConfig(input: false | ConvexAuthOptions | undefined | unknown): NormalizedConvexAuthConfig;
+export declare function isConvexAuthEnabled(config: NormalizedConvexAuthConfig): config is Exclude<NormalizedConvexAuthConfig, false>;

package/dist/runtime/utils/auth-config.js

@@ -0,0 +1,45 @@
+import { isExactLoopbackHost, normalizeAuthOrigin } from "../shared/auth-origin.js";
+import { normalizeLocalRedirectPath } from "./auth-route-protection.js";
+const DEFAULT_AUTH_REDIRECT = "/auth/signin";
+function normalizeTrustedClientIpHeader(input) {
+  if (input === void 0) return "";
+  if (typeof input !== "string") {
+    throw new TypeError("auth.trustedClientIpHeader must be a valid HTTP header name");
+  }
+  const header = input.trim().toLowerCase();
+  if (!header) return "";
+  try {
+    new Headers().set(header, "validation");
+  } catch {
+    throw new TypeError("auth.trustedClientIpHeader must be a valid HTTP header name");
+  }
+  if (header.startsWith("x-bcn-")) {
+    throw new TypeError("auth.trustedClientIpHeader must not use the reserved x-bcn-* namespace");
+  }
+  return header;
+}
+export function normalizeConvexAuthConfig(input) {
+  if (input === void 0 || input === false) return false;
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new TypeError("auth must be false or an object with an origin");
+  }
+  const options = input;
+  if (typeof options.origin !== "string") {
+    throw new TypeError("auth.origin must be a non-empty string URL origin");
+  }
+  const origin = normalizeAuthOrigin(options.origin, "auth.origin");
+  const trustedClientIpHeader = normalizeTrustedClientIpHeader(options.trustedClientIpHeader);
+  if (!trustedClientIpHeader && !isExactLoopbackHost(new URL(origin).hostname)) {
+    throw new TypeError(
+      "auth.trustedClientIpHeader is required outside exact loopback development origins"
+    );
+  }
+  const redirectTo = normalizeLocalRedirectPath(options.redirectTo ?? DEFAULT_AUTH_REDIRECT);
+  if (!redirectTo) {
+    throw new TypeError("auth.redirectTo must be a safe local application path");
+  }
+  return Object.freeze({ origin, trustedClientIpHeader, redirectTo });
+}
+export function isConvexAuthEnabled(config) {
+  return config !== false;
+}

package/dist/runtime/utils/auth-contract.d.ts

@@ -0,0 +1,22 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { ConvexCallError } from '../errors/index.js';
+import type { ConvexAuthStatus } from './auth-status.js';
+import type { IntegratedAuthClient } from './integrated-auth-client.js';
+import type { ConvexUser } from './types.js';
+/**
+ * Convex authentication state plus the provider client accepted by the Nuxt
+ * runtime. The neutral default keeps the root declaration graph independent
+ * from any particular authentication package; `useConvexAuth()` specializes
+ * this with the registered Better Auth client inside auth-enabled builds.
+ */
+export interface UseConvexAuthReturn<Client extends object = object> {
+    readonly status: ComputedRef<ConvexAuthStatus>;
+    readonly isPending: ComputedRef<boolean>;
+    readonly user: Readonly<Ref<ConvexUser | null>>;
+    readonly error: Readonly<Ref<ConvexCallError | undefined>>;
+    /** Every PromiseLike client operation crosses canonical session reconciliation. */
+    readonly client: IntegratedAuthClient<Client> | null;
+    ready(options?: {
+        timeoutMs?: number;
+    }): Promise<ConvexAuthStatus>;
+}

package/dist/runtime/utils/auth-errors.d.ts

@@ -0,0 +1,5 @@
+export declare function buildMissingSiteUrlMessage(): string;
+export declare function buildMissingPublicOriginMessage(): string;
+export declare function buildBlockedOriginMessage(): string;
+export declare function buildAuthProxyUnreachableMessage(): string;
+export declare function buildAuthProxyUpstreamStatusMessage(status: number): string;

package/dist/runtime/utils/auth-errors.js

@@ -0,0 +1,22 @@
+const PREFIX = "NuxtConvexError";
+function prefix(message) {
+  return `${PREFIX}: ${message}`;
+}
+export function buildMissingSiteUrlMessage() {
+  return prefix("Auth proxy requires a configured Convex HTTP Actions host (`convex.siteUrl`).");
+}
+export function buildMissingPublicOriginMessage() {
+  return prefix("Auth proxy requires one canonical public Nuxt origin. Set `convex.auth.origin`.");
+}
+export function buildBlockedOriginMessage() {
+  return prefix("Cross-origin auth request blocked. Use the same-origin Nuxt auth proxy.");
+}
+export function buildAuthProxyUnreachableMessage() {
+  return prefix(
+    "Auth proxy could not reach the configured Convex auth server. Check `convex.siteUrl` and the deployed Convex HTTP routes."
+  );
+}
+export function buildAuthProxyUpstreamStatusMessage(status) {
+  const hint = status === 404 ? "This usually means Better Auth routes are not registered in `convex/http.ts` or `convex.siteUrl` points to the wrong host." : "Check your Convex deployment health and Better Auth setup.";
+  return prefix(`Auth proxy upstream returned HTTP ${status}. ${hint}`);
+}

package/dist/runtime/utils/auth-identity-state.d.ts

@@ -0,0 +1,4 @@
+import type { Ref } from 'vue';
+import { type AuthIdentity } from '../auth/auth-identity.js';
+/** The single SSR-hydrated identity value used by every runtime auth reader. */
+export declare function useConvexIdentityState(): Ref<AuthIdentity>;

package/dist/runtime/utils/auth-identity-state.js

@@ -0,0 +1,8 @@
+import { useState } from "#imports";
+import { ANONYMOUS_IDENTITY, LOADING_IDENTITY } from "../auth/auth-identity.js";
+export function useConvexIdentityState() {
+  return useState(
+    "convex:identity",
+    () => import.meta.client ? LOADING_IDENTITY : ANONYMOUS_IDENTITY
+  );
+}

package/dist/runtime/utils/auth-pending-state.d.ts

@@ -0,0 +1,13 @@
+import type { Ref } from 'vue';
+/**
+ * Single source for the `convex:pending` auth-readiness state.
+ *
+ * The client starts pending — auth is unknown until the client engine settles —
+ * while the server starts settled, because `plugin.server` writes the resolved
+ * auth state into the SSR payload before render. Every reader/writer of
+ * `convex:pending` must go through this helper so the initial value can never
+ * diverge by first-touch order.
+ *
+ * Internal only — not part of the public auto-import surface.
+ */
+export declare function useConvexAuthPendingState(): Ref<boolean>;

package/dist/runtime/utils/auth-pending-state.js

@@ -0,0 +1,4 @@
+import { useState } from "#imports";
+export function useConvexAuthPendingState() {
+  return useState("convex:pending", () => import.meta.client);
+}

package/dist/runtime/utils/auth-pending.d.ts

@@ -0,0 +1,10 @@
+import { type Ref } from 'vue';
+export interface WaitForPendingClearOptions {
+    timeoutMs?: number;
+    onTimeout?: () => void;
+}
+/**
+ * Wait for an auth pending ref to settle to false.
+ * Returns false on timeout, true when settled.
+ */
+export declare function waitForPendingClear(pending: Ref<boolean>, options?: WaitForPendingClearOptions): Promise<boolean>;

package/dist/runtime/utils/auth-pending.js

@@ -0,0 +1,30 @@
+import { watch } from "vue";
+export async function waitForPendingClear(pending, options = {}) {
+  if (!pending.value) {
+    return true;
+  }
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  return await new Promise((resolve) => {
+    let settled = false;
+    let stopWatch = null;
+    let timeoutId = null;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      stopWatch?.();
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      resolve(value);
+    };
+    stopWatch = watch(pending, (isPending) => {
+      if (!isPending) {
+        finish(true);
+      }
+    });
+    timeoutId = setTimeout(() => {
+      options.onTimeout?.();
+      finish(false);
+    }, timeoutMs);
+  });
+}

package/dist/runtime/utils/auth-route-protection.d.ts

@@ -0,0 +1,16 @@
+import type { RouteLocationRaw } from 'vue-router';
+export type ConvexAuthPageMeta = boolean | {
+    redirectTo?: RouteLocationRaw;
+};
+export interface RouteProtectionDecisionInput {
+    meta: ConvexAuthPageMeta | undefined;
+    defaultRedirectTo: string;
+    preserveReturnTo: boolean;
+    currentPath: string;
+    currentFullPath?: string;
+}
+export interface RouteProtectionDecision {
+    redirectTo: RouteLocationRaw;
+}
+export declare function normalizeLocalRedirectPath(value: string): string | null;
+export declare function resolveRouteProtectionDecision(input: RouteProtectionDecisionInput): RouteProtectionDecision | null;