/**
 * Server-Side Token Validation
 *
 * Secure JWT validation with JWKS caching for Cloudflare Workers and SvelteKit.
 * Uses KV for persistent caching across stateless Worker instances.
 *
 * Canon: Verification is invisible—the trusted identity simply emerges.
 *
 * @packageDocumentation
 */
import { type User, type KVLike, type AuthEnv } from './types.js';
export type { KVLike, AuthEnv };
/**
 * Extract access token from a Request object
 *
 * Checks cookies first, then Authorization header as fallback.
 * Prioritizes cookies for security (httpOnly, secure).
 *
 * @example
 * ```typescript
 * // In API route
 * export const GET: RequestHandler = async ({ request }) => {
 *   const token = getTokenFromRequest(request);
 *   if (!token) {
 *     return json({ error: 'Unauthorized' }, { status: 401 });
 *   }
 *   // ...
 * };
 * ```
 */
export declare function getTokenFromRequest(request: Request): string | null;
/**
 * Validate a JWT with cryptographic signature verification via JWKS
 *
 * Uses KV caching when env.AUTH_CACHE is provided for robust
 * cross-instance caching in Cloudflare Workers.
 *
 * @param token - The JWT access token to validate
 * @param env - Optional environment with AUTH_CACHE KV namespace
 * @returns User object if valid, null otherwise
 *
 * @example
 * ```typescript
 * // In SvelteKit +page.server.ts
 * import { validateToken, getTokenFromRequest } from '@create-something/components/auth/server';
 *
 * export const load: PageServerLoad = async ({ request, platform }) => {
 *   const token = getTokenFromRequest(request);
 *   const user = token
 *     ? await validateToken(token, platform?.env)
 *     : null;
 *   return { user };
 * };
 * ```
 *
 * @example
 * ```typescript
 * // In Cloudflare Worker
 * export default {
 *   async fetch(request: Request, env: Env) {
 *     const token = getTokenFromRequest(request);
 *     const user = await validateToken(token, env);
 *     if (!user) {
 *       return new Response('Unauthorized', { status: 401 });
 *     }
 *     // ...
 *   }
 * };
 * ```
 */
export declare function validateToken(token: string, env?: AuthEnv): Promise<User | null>;
/** Error thrown when authentication is required but not provided */
export declare class AuthenticationError extends Error {
    constructor(message?: string);
}
/**
 * Require authentication, throwing if not authenticated
 *
 * Use this when a route absolutely requires a valid user.
 * Throws AuthenticationError if token is missing or invalid.
 *
 * @param request - The incoming request
 * @param env - Optional environment with AUTH_CACHE KV namespace
 * @returns User object (never null - throws instead)
 * @throws AuthenticationError if not authenticated
 *
 * @example
 * ```typescript
 * // In SvelteKit +page.server.ts
 * import { requireAuth } from '@create-something/components/auth/server';
 * import { error } from '@sveltejs/kit';
 *
 * export const load: PageServerLoad = async ({ request, platform }) => {
 *   try {
 *     const user = await requireAuth(request, platform?.env);
 *     return { user };
 *   } catch (e) {
 *     throw error(401, 'Unauthorized');
 *   }
 * };
 * ```
 *
 * @example
 * ```typescript
 * // In Cloudflare Worker
 * import { requireAuth, AuthenticationError } from '@create-something/components/auth/server';
 *
 * export default {
 *   async fetch(request: Request, env: Env) {
 *     try {
 *       const user = await requireAuth(request, env);
 *       return new Response(`Hello, ${user.email}`);
 *     } catch (e) {
 *       if (e instanceof AuthenticationError) {
 *         return new Response('Unauthorized', { status: 401 });
 *       }
 *       throw e;
 *     }
 *   }
 * };
 * ```
 */
export declare function requireAuth(request: Request, env?: AuthEnv): Promise<User>;
/**
 * Get optional user from request (does not throw)
 *
 * Use this when authentication is optional but you want user info if available.
 *
 * @param request - The incoming request
 * @param env - Optional environment with AUTH_CACHE KV namespace
 * @returns User object if authenticated, null otherwise
 *
 * @example
 * ```typescript
 * // In SvelteKit +layout.server.ts
 * import { getOptionalUser } from '@create-something/components/auth/server';
 *
 * export const load: LayoutServerLoad = async ({ request, platform }) => {
 *   const user = await getOptionalUser(request, platform?.env);
 *   return { user }; // null if not authenticated
 * };
 * ```
 */
export declare function getOptionalUser(request: Request, env?: AuthEnv): Promise<User | null>;
/**
 * Clear JWKS cache (useful for testing or forced refresh)
 *
 * Clears both module-level cache and optionally KV cache.
 *
 * @param env - Optional environment with AUTH_CACHE KV namespace
 */
export declare function clearJWKSCache(env?: AuthEnv): Promise<void>;