import { JwtClaims, Config } from './types.js';

/**
 * Framework-agnostic server-side session helper for Hanzo IAM.
 *
 * One way to answer "who is calling?" on the server: read the bearer
 * token (`Authorization: Bearer …`) or the session cookie, verify it
 * against IAM's JWKS via {@link validateToken}, and return the identity.
 *
 * Works with any request that exposes headers — the Web Fetch `Request`
 * (Next.js App Router route handlers / middleware, Hono, Remix) and the
 * Node `IncomingMessage` (Next.js Pages API routes, Express, raw http).
 *
 * @example Next.js App Router route handler
 * ```ts
 * import { getServerSession } from "@hanzo/iam/server";
 *
 * const iam = { serverUrl: process.env.IAM_ENDPOINT!, clientId: process.env.IAM_CLIENT_ID! };
 *
 * export async function GET(req: Request) {
 *   const session = await getServerSession(req, iam);
 *   if (!session) return new Response("unauthorized", { status: 401 });
 *   // session.userId, session.owner, session.email, session.claims
 *   return Response.json({ user: session.userId, org: session.owner });
 * }
 * ```
 *
 * @example Guarded route handler
 * ```ts
 * import { withSession } from "@hanzo/iam/server";
 *
 * export const GET = withSession(iam, (req, session) =>
 *   Response.json({ org: session.owner }),
 * );
 * ```
 *
 * @packageDocumentation
 */

/** Canonical cookie name carrying the IAM access token for SSR. */
declare const SESSION_COOKIE = "hanzo_iam_access_token";
/** The authenticated identity resolved from a verified IAM token. */
interface ServerSession {
    /** Subject — IAM user id, format "org/username". */
    userId: string;
    /** Owning organization (the `owner` claim or the `sub` org prefix). */
    owner: string;
    /** User email, when present in the token. */
    email?: string;
    /** All verified JWT claims. */
    claims: JwtClaims;
}
/** Options for session resolution. */
interface ServerSessionOptions {
    /** Cookie name to read the token from. Default {@link SESSION_COOKIE}. */
    cookieName?: string;
}
/**
 * Minimal request shape: either a Web `Request` (with `headers.get`) or a
 * Node `IncomingMessage` (with a `headers` record). Both are accepted.
 */
interface HeaderCarrier {
    headers: {
        get(name: string): string | null;
    } | Record<string, string | string[] | undefined>;
}
/**
 * Extract the IAM access token from a request: the `Authorization:
 * Bearer …` header takes precedence, falling back to the session cookie.
 * Returns undefined when neither is present.
 */
declare function getBearerToken(req: HeaderCarrier, options?: ServerSessionOptions): string | undefined;
/**
 * Resolve the server session for a request. Reads the bearer token or
 * session cookie, verifies it against IAM, and returns the identity —
 * or `null` when no valid token is present.
 */
declare function getServerSession(req: HeaderCarrier, config: Config, options?: ServerSessionOptions): Promise<ServerSession | null>;
/**
 * Wrap a route handler so it only runs with a valid session. Unauthorized
 * requests get a `401` (Web `Response`) before the handler is called.
 * The handler receives the original request plus the resolved session.
 *
 * Framework-agnostic over the Web Fetch `Request`/`Response` model used
 * by Next.js App Router, Hono, and Remix.
 */
declare function withSession<Req extends HeaderCarrier, Res>(config: Config, handler: (req: Req, session: ServerSession) => Res | Promise<Res>, options?: ServerSessionOptions): (req: Req) => Promise<Res | Response>;

export { type HeaderCarrier, SESSION_COOKIE, type ServerSession, type ServerSessionOptions, getBearerToken, getServerSession, withSession };