import "server-only";
import type { AuthResult, NextgenMiddlewareOptions } from "./types.js";
/**
 * Options for {@link auth}.
 *
 * These mirror the token-verification subset of the middleware options. When
 * the middleware runs with custom verification settings (a non-default
 * `audience`, `allowedAlgorithms`, …), pass the same values here — otherwise
 * a token the middleware accepted can fail re-verification in `auth()` and
 * render as signed out.
 */
export type AuthOptions = Pick<NextgenMiddlewareOptions, "url" | "projectId" | "allowedAlgorithms" | "clockSkewMs" | "audience" | "allowedTokenTypes" | "jwksTimeoutMs" | "opaqueTokenTimeoutMs">;
/**
 * Reads the auth state in a React Server Component or Next.js Route Handler.
 *
 * The session token arrives on the `x-nextgen-auth-token` request header,
 * tunnelled there by the middleware — and `auth()` **verifies it before
 * trusting it**:
 *
 * - **JWT tokens** are verified cryptographically (signature via JWKS,
 *   issuer, expiry, algorithm and type allow-lists) using the same rules and
 *   defaults as the middleware. The JWKS is cached in-process, so this does
 *   not add a backend round-trip after the first call.
 * - **Opaque encrypted tokens** are validated against the backend's
 *   `GET /sessions/me`, which also supplies the user's identity (`userId`,
 *   `identifier`, `identifierProperty`, `display`). The lookup is deduplicated
 *   per render pass via React `cache()`.
 *
 * The header alone is never proof of anything, so `auth()` verifies every
 * value it reads. Off a protected route the middleware hands an opaque token
 * on unchecked, so that a page that never reads the session costs no call to
 * the backend: there `auth()` is the one check. On routes the middleware
 * `matcher` does not cover, the middleware cannot refuse a forged
 * client-supplied header. A header value that fails verification is treated
 * as signed out.
 *
 * Either way a session counts only in the app's own project: `projectId`,
 * else `ZITADEL_PROJECT_ID`, else `NEXT_PUBLIC_ZITADEL_PROJECT_ID`, else the
 * project of `configureZitadel()` when it has run in this server runtime. A
 * JWT must name it in `aud`; an opaque token must be a session of that
 * project. With no project, nobody is signed in. A middleware built with
 * `createProxy(config)` holds sessions to `config.projectId`: pass the same
 * project here unless it comes from one of those variables.
 *
 * A backend that answers with an unexpected status, or not at all, reads as
 * signed out and is logged, so a broken proxy or an unreachable backend is
 * distinguishable from a missing session.
 *
 * **Matcher precondition (read this):** the middleware only tunnels the
 * session token on routes covered by its `matcher`. On uncovered routes the
 * cookie never reaches `auth()`, so `auth()` reports signed out even when a
 * live session exists. Either extend the `matcher` to every route that calls
 * `auth()`, or — for app chrome like headers and account menus — read the
 * session client-side with `getSession()` from `@zitadel/sdk-next/session`,
 * which works on any page.
 *
 * The backend URL comes from `options.url`, falling back to the same
 * `ZITADEL_URL` environment variable the middleware uses. If the middleware
 * runs with custom verification options (`audience`, `allowedAlgorithms`, …),
 * pass the same values here; see {@link AuthOptions}.
 *
 * This module is server-only: importing it (or the package root) from a
 * client component fails at build time. Client components read auth state
 * from `@zitadel/sdk-next/react` (`useAuth()`) or
 * `@zitadel/sdk-next/session` (`getSession()`).
 *
 * ```ts
 * import { auth } from "@zitadel/sdk-next/server";
 *
 * export default async function Page() {
 *   const session = await auth();
 *   if (!session.isAuthenticated) return <p>Not signed in</p>;
 *   return <p>Hello {session.session.userId}</p>;
 * }
 * ```
 *
 * @param options - Optional verification settings; see {@link AuthOptions}.
 * @returns The current {@link AuthResult}. `session.token` is the raw session
 *   token for calling upstream APIs server-side — never forward it into
 *   client components (the `NextgenProvider` strips it for you).
 */
export declare function auth(options?: AuthOptions): Promise<AuthResult>;