@estifanos-sh/convex-auth 0.0.1-preview.0

package/dist/server/preload.d.ts

@@ -0,0 +1,249 @@
+import { ConvexHttpClient } from "convex/browser";
+import { FunctionArgs, FunctionReference } from "convex/server";
+import { Preloaded } from "convex/react";
+
+//#region src/server/preload.d.ts
+/** Cookie lifetime configuration for auth tokens. */
+type AuthCookieConfig = {
+  /** Maximum age in seconds, or `null` for session cookies. */maxAge: number | null;
+};
+/** Raw cookie values extracted from a request. */
+type AuthCookies = {
+  /** The JWT access token, or `null` when absent. */token: string | null; /** The refresh token, or `null` when absent. */
+  refreshToken: string | null; /** The OAuth PKCE verifier, or `null` when absent. */
+  verifier: string | null;
+};
+/** A structured cookie ready to be set via any framework's cookie API. */
+type AuthCookie = {
+  name: string;
+  value: string;
+  options: {
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax" | "strict" | "none";
+    maxAge?: number;
+    expires?: Date;
+  };
+};
+/**
+ * Options for the SSR auth helper returned by {@link server}.
+ */
+type ServerOptions = {
+  /** Convex deployment API URL (e.g. `https://your-app.convex.cloud`). */url: string;
+  /**
+   * Accepted JWT issuers for `refresh()` and `verify()`.
+   *
+   * By default, this is derived from `url`. If `url` ends with
+   * `.convex.cloud`, the matching `.convex.site` issuer is also accepted.
+   */
+  acceptedIssuers?: string[];
+  /**
+   * Path the client POSTs auth actions to. Defaults to `"/api/auth"`.
+   * Must match the `proxyPath` option on the client.
+   *
+   * @defaultValue "/api/auth"
+   */
+  apiRoute?: string; /** Cookie `maxAge` in seconds, or `null` for session cookies. */
+  cookieMaxAge?: number | null; /** Enable verbose debug logging for token refresh and cookie operations. */
+  verbose?: boolean;
+  /**
+   * Optional namespace for auth cookie names.
+   *
+   * Use this to isolate auth cookies between multiple local apps on the same host.
+   * If omitted, a deterministic deployment-scoped namespace is derived from `url`.
+   */
+  cookieNamespace?: string;
+  /**
+   * Control whether `refresh()` handles OAuth `?code=` query parameters.
+   *
+   * - `true` (default): always exchange the code on GET requests with `text/html` accept.
+   * - `false`: never exchange — useful when only the client handles codes.
+   * - A function: called with the `Request` for per-request decisions.
+   *
+   * @defaultValue true
+   */
+  shouldHandleCode?: ((request: Request) => boolean | Promise<boolean>) | boolean;
+};
+/**
+ * Result returned from `server().preload()`.
+ *
+ * Covers both normal SSR token refreshes and OAuth code-exchange redirects.
+ */
+type PreloadResult = {
+  /** Code exchange occurred — return the pre-built redirect `Response`. */redirect: true; /** 302 redirect with Set-Cookie headers already serialized. */
+  response: Response;
+} | {
+  /** No redirect — apply cookies and read the token. */redirect: false; /** Structured cookies to set on the response. */
+  cookies: AuthCookie[]; /** JWT for SSR hydration, or `null` if not authenticated. */
+  token: string | null;
+  /**
+   * Pre-authenticated `ConvexHttpClient` wired with the refreshed token,
+   * ready for one-shot SSR queries. `null` when not authenticated.
+   */
+  convex: ConvexHttpClient | null;
+  /**
+   * Run a query against Convex with the refreshed token and return a
+   * `Preloaded<Query>` payload that pairs with `usePreloadedQuery` from
+   * `convex/react` for flash-free SSR hydration.
+   *
+   * Returns `null` for the value when not authenticated; the
+   * `Preloaded` payload is still typed against the query.
+   */
+  preloadQuery: <Query extends FunctionReference<"query">>(query: Query, ...args: PreloadQueryArgs<Query>) => Promise<Preloaded<Query>>;
+};
+type PreloadQueryArgs<Query extends FunctionReference<"query">> = FunctionArgs<Query> extends Record<string, never> ? [args?: FunctionArgs<Query>] : [args: FunctionArgs<Query>];
+/**
+ * Derive the cookie names used for auth tokens.
+ *
+ * On localhost the names are unprefixed; on production hosts they
+ * use the `__Host-` prefix for tighter security.
+ *
+ * @param host - The `Host` header value. Omit to use unprefixed names.
+ * @param cookieNamespace - Optional namespace suffix for cookie isolation.
+ * @returns An object with `token`, `refreshToken`, and `verifier` cookie names.
+ */
+declare function authCookieNames(host?: string, cookieNamespace?: string | null): {
+  token: string;
+  refreshToken: string;
+  verifier: string;
+};
+/**
+ * Parse auth cookie values from a raw `Cookie` header string.
+ *
+ * @param cookieHeader - The raw `Cookie` header, or `null`/`undefined`.
+ * @param host - The `Host` header, used to determine cookie name prefixes.
+ * @param cookieNamespace - Optional namespace suffix for cookie isolation.
+ * @returns Parsed {@link AuthCookies} with `token`, `refreshToken`, and `verifier`.
+ */
+declare function parseAuthCookies(cookieHeader: string | null | undefined, host?: string, cookieNamespace?: string | null): AuthCookies;
+/**
+ * Serialize auth cookies into `Set-Cookie` header strings.
+ *
+ * Nulled-out values produce deletion cookies (maxAge 0, expired date).
+ *
+ * @param cookies - The auth cookie values to serialize.
+ * @param host - The `Host` header, used for cookie name prefixes and `Secure` flag.
+ * @param config - Cookie lifetime config. Defaults to session cookies.
+ * @param cookieNamespace - Optional namespace suffix for cookie isolation.
+ * @returns An array of three `Set-Cookie` header strings.
+ */
+declare function serializeAuthCookies(cookies: AuthCookies, host?: string, config?: AuthCookieConfig, cookieNamespace?: string | null): string[];
+/**
+ * Build structured cookie objects for any SSR framework.
+ *
+ * Use with SvelteKit's `event.cookies.set()`, TanStack Start's `setCookie()`,
+ * Next.js's `cookies().set()`, or any other framework cookie API.
+ *
+ * @param cookies - The auth cookie values to convert.
+ * @param host - The `Host` header, used for cookie name prefixes and `Secure`.
+ * @param config - Cookie lifetime config. Defaults to session cookies.
+ * @param cookieNamespace - Optional namespace suffix for cookie isolation.
+ * @returns Structured cookie descriptors ready for framework cookie APIs.
+ */
+declare function structuredAuthCookies(cookies: AuthCookies, host?: string, config?: AuthCookieConfig, cookieNamespace?: string | null): AuthCookie[];
+/**
+ * Check whether a request pathname matches the auth proxy route.
+ *
+ * Handles trailing-slash ambiguity: both `/api/auth` and `/api/auth/`
+ * match regardless of how `apiRoute` is configured.
+ *
+ * @param pathname - The request URL pathname.
+ * @param apiRoute - The configured proxy route (e.g. `"/api/auth"`).
+ * @returns `true` when the pathname matches the proxy route.
+ *
+ * @see {@link server}
+ */
+declare function shouldProxyAuthAction(pathname: string, apiRoute: string): boolean;
+/**
+ * Create an SSR auth helper for server-side frameworks.
+ *
+ * Handles cookie-based token management, OAuth code exchange,
+ * and automatic JWT refresh on page loads. Works with any
+ * framework that gives you a `Request` object — SvelteKit,
+ * TanStack Start, Remix, Next.js, etc.
+ *
+ * @param options - SSR configuration (Convex API URL, issuer rules, proxy route, cookie lifetime).
+ * @returns An object with `token`, `verify`, `proxy`, and `preload` methods.
+ *
+ * @example SvelteKit hooks
+ * ```ts
+ * // src/hooks.server.ts
+ * import { server } from '@estifanos-sh/convex-auth/server';
+ *
+ * const auth = server({ url: CONVEX_URL });
+ *
+ * export const handle = async ({ event, resolve }) => {
+ *   const result = await auth.preload(event.request);
+ *   if (result.redirect) return result.response;
+ *   for (const c of result.cookies) event.cookies.set(c.name, c.value, c.options);
+ *   event.locals.token = result.token;
+ *   return resolve(event);
+ * };
+ * ```
+ *
+ * @example Generic proxy endpoint
+ * ```ts
+ * if (shouldProxyAuthAction(url.pathname, '/api/auth')) {
+ *   return auth.proxy(request);
+ * }
+ * ```
+ *
+ * @param options - Server-side auth configuration including Convex URL,
+ *   accepted issuers, proxy route, and cookie behavior.
+ * @returns SSR helpers for reading tokens, refreshing cookies, and proxying
+ *   auth actions through an httpOnly-cookie layer.
+ *
+ * @see {@link shouldProxyAuthAction}
+ */
+declare function server(options: ServerOptions): {
+  /**
+   * Read the JWT from the request cookies without any validation.
+   *
+   * @param request - The incoming HTTP request.
+   * @returns The raw JWT string, or `null` when no token cookie exists.
+   */
+  token(request: Request): string | null;
+  /**
+   * Check whether the request carries a non-expired JWT.
+   *
+   * Performs local expiration checking only (no network call).
+   * Use for lightweight auth guards in middleware.
+   *
+   * @param request - The incoming HTTP request.
+   * @returns `true` when a valid, non-expired JWT exists in the cookies.
+   */
+  verify(request: Request): Promise<boolean>;
+  /**
+   * Handle a proxied `signIn` or `signOut` POST from the client.
+   *
+   * Validates the route, method, and origin, then forwards the
+   * action to Convex and returns a `Response` with updated
+   * `Set-Cookie` headers. The client never sees the real
+   * refresh token — it stays in httpOnly cookies.
+   *
+   * @param request - The incoming POST request from the client.
+   * @returns A JSON `Response` with auth result and cookie headers.
+   */
+  proxy(request: Request): Promise<Response>;
+  /**
+   * Preload SSR auth state on every page load.
+   *
+   * Call in server hooks/middleware on every request. Handles three scenarios:
+   *
+   * 1. **OAuth code exchange** — exchanges a `?code=` query param for tokens and returns a redirect URL.
+   * 2. **Token refresh** — refreshes the JWT if it's close to expiry.
+   * 3. **No-op** — returns the existing token when no refresh is needed.
+   *
+   * The non-redirect result includes `preloadQuery(query, args)` for producing
+   * `Preloaded<Query>` payloads that pair with `usePreloadedQuery` from
+   * `convex/react`.
+   *
+   * @param request - The incoming HTTP request.
+   * @returns Structured cookies to set on the response, an optional redirect URL, the current JWT, and a typed `preloadQuery` helper.
+   */
+  preload(request: Request): Promise<PreloadResult>;
+};
+//#endregion
+export { AuthCookie, AuthCookieConfig, AuthCookies, PreloadResult, ServerOptions, authCookieNames, parseAuthCookies, serializeAuthCookies, server, shouldProxyAuthAction, structuredAuthCookies };
+//# sourceMappingURL=preload.d.ts.map