import { IdentityProvider } from '@nanoesis/engine';

/**
 * Configuration for {@link trustedHeaderIdentity}. Every header name is overridable so
 * the same adapter handles standard reverse-proxy headers (oauth2-proxy, Authentik,
 * Keycloak, Traefik forwardAuth) and named-header gateways alike. Defaults to the
 * widely-used `X-Forwarded-User` / `X-Forwarded-Email` / `X-Forwarded-Roles`.
 *
 * For Easy Auth, point `userIdHeader` at `X-MS-Client-Principal-Name` (or `-Id`) and
 * either set `rolesHeader` to a header the gateway exposes, or front the app with
 * something that translates Easy Auth's base64 JSON principal into standard headers.
 * For Cloudflare Access, `Cf-Access-Authenticated-User-Email` works as either userId
 * or email, set the same header for both if you want.
 */
interface TrustedHeaderConfig {
    /** Header carrying the user identifier (also used as the display handle). Default: `X-Forwarded-User`. */
    readonly userIdHeader?: string;
    /**
     * Header carrying the roles as a comma-separated list (case-insensitive). Roles
     * outside the known set (`author`, `developer`, `admin`) are dropped, defence in
     * depth, the gateway is the authority on what counts as a real role. Default:
     * `X-Forwarded-Roles`.
     */
    readonly rolesHeader?: string;
}
/**
 * A trusted-header {@link IdentityProvider} (DESIGN §11, the recommended production
 * path). An upstream gateway (Easy Auth, Cloudflare Access, oauth2-proxy, Authentik,
 * Keycloak) does the actual authentication and forwards the result as request
 * headers; nanoesis trusts those headers **because the host is only reachable
 * through that gateway**.
 *
 * No login code, no session storage, no password handling, every one of those is the
 * gateway's job. A missing or empty userId header resolves to anonymous (null), at
 * which point the host's role policy denies the editing routes.
 *
 * **Operational guarantee:** if requests can reach the host without going through the
 * gateway, this provider is unsafe (a client can forge the headers). This is true of
 * every trusted-header scheme, not specific to this implementation.
 */
declare function trustedHeaderIdentity(config?: TrustedHeaderConfig): IdentityProvider;

export { type TrustedHeaderConfig, trustedHeaderIdentity };
