import { type IdentityPlugin } from "@nifrajs/core/server";
type MaybePromise<T> = T | Promise<T>;
/**
 * A token-auth plugin (`bearer` / `apiKey`). Apply it with `app.use(auth)` - it rejects unauthorized
 * requests to **routes defined after it** with `401` (unless `optional`). Read the verified principal
 * inside a handler/loader via {@link AuthPlugin.principal} (nullable) or
 * {@link AuthPlugin.requirePrincipal} (throws `401` when absent). The principal is verified once per
 * request and cached, so reading it is free.
 *
 * `beforeHandle` is **order-scoped**: place `app.use(auth)` before the routes it should guard. Hold the
 * returned instance to read the principal (mirrors `@nifrajs/auth`'s `sessions.get(c)` and
 * `@nifrajs/better-auth`'s `getSession(auth, req)`):
 *
 * ```ts
 * const auth = bearer({ verify: (t) => lookupUser(t) }) // P = User (inferred)
 * const app = server().use(auth).get("/me", (c) => auth.requirePrincipal(c.req))
 * ```
 */
export type AuthPlugin<P> = IdentityPlugin & {
    /** The verified principal for this request, or `null` (no/invalid token in `optional` mode). */
    principal(request: Request): P | null;
    /** The verified principal, or **throws a `401` `Response`** when absent. */
    requirePrincipal(request: Request): P;
};
export interface BearerOptions<P> {
    /** Verify a bearer token → a principal (truthy) or `null`/`undefined` (rejected). May be async
     * (DB/JWT lookup). For a constant-secret comparison, use a constant-time compare - never `===`. */
    readonly verify: (token: string) => MaybePromise<P | null | undefined>;
    /** When `true`, requests without a valid token pass through (`principal` is `null`) instead of `401`. */
    readonly optional?: boolean;
    /** `realm` for the `WWW-Authenticate: Bearer` header on `401`. Default `"api"`. */
    readonly realm?: string;
}
/**
 * `Authorization: Bearer <token>` authentication. Parses the header, runs `verify`, and rejects with
 * `401` (+ `WWW-Authenticate: Bearer`) when the token is missing/invalid (unless `optional`). The
 * verified principal is read via the returned instance - see {@link AuthPlugin}.
 */
export declare function bearer<P>(options: BearerOptions<P>): AuthPlugin<P>;
export interface ApiKeyVerifyOptions<P> {
    /** Verify an API key → a principal or `null`/`undefined` (rejected). May be async. */
    readonly verify: (key: string) => MaybePromise<P | null | undefined>;
    /** Header carrying the key. Default `"x-api-key"`. */
    readonly header?: string;
    readonly optional?: boolean;
}
export interface ApiKeyStaticOptions {
    /** A fixed set of valid keys. Compared in **constant time** (see below); the matched key becomes the
     * principal. Use `verify` instead for DB-backed / per-tenant keys. */
    readonly keys: readonly string[];
    readonly header?: string;
    readonly optional?: boolean;
}
/**
 * API-key authentication via a header (default `x-api-key`). Two forms:
 * - `apiKey({ keys })` - a fixed key set, compared in **constant time**; the matched key is the principal.
 * - `apiKey({ verify })` - custom (e.g. DB-backed) verification returning a typed principal.
 *
 * Rejects missing/invalid keys with `401` (unless `optional`). Read the principal via the returned
 * instance - see {@link AuthPlugin}.
 */
export declare function apiKey(options: ApiKeyStaticOptions): AuthPlugin<string>;
export declare function apiKey<P>(options: ApiKeyVerifyOptions<P>): AuthPlugin<P>;
export {};
//# sourceMappingURL=token-auth.d.ts.map