/** @platform-modules/auth core — zero runtime dependency seam. */
type Principal = {
    userId: string;
    sessionId: string;
    roles: string[];
    capabilities?: string[];
    tenantId?: string;
};
type Session = {
    id: string;
    userId: string;
    expiresAt: Date;
};
type SignInCredentials = {
    email: string;
    password: string;
};
type SignInResult = {
    principal: Principal;
    accessToken: string;
    refreshToken: string;
};
type RefreshResult = {
    principal: Principal;
    accessToken: string;
    refreshToken?: string;
};
type CreateUserInput = {
    email: string;
    password: string;
    roles?: string[];
};
type AuthEngine = {
    signIn(credentials: SignInCredentials): Promise<SignInResult>;
    signOut(sessionId: string, refreshToken?: string): Promise<void>;
    verifySession(token: string): Promise<Principal | null>;
    refresh(refreshToken: string): Promise<RefreshResult | null>;
    createUser(input: CreateUserInput): Promise<{
        userId: string;
    }>;
    setPassword(userId: string, password: string): Promise<void>;
    verifyPassword(password: string, storedHash: string): Promise<boolean>;
};
interface UserAdminEngine {
    listUsers(opts?: {
        limit?: number;
        offset?: number;
    }): Promise<{
        users: {
            id: string;
            email: string;
            roles: string[];
            status: 'active' | 'disabled';
            createdAt: string;
        }[];
        total: number;
    }>;
    setUserRoles(userId: string, roles: string[]): Promise<void>;
    disableUser(userId: string): Promise<void>;
}
declare class AuthError extends Error {
}
declare class InvalidSessionError extends AuthError {
    readonly reason?: string | undefined;
    readonly name = "InvalidSessionError";
    constructor(message: string, reason?: string | undefined);
}
declare class RevokedSessionError extends AuthError {
    readonly userId?: string | undefined;
    readonly name = "RevokedSessionError";
    constructor(message: string, userId?: string | undefined);
}
declare class RateLimitedError extends AuthError {
    readonly scope?: string | undefined;
    readonly name = "RateLimitedError";
    constructor(message: string, scope?: string | undefined);
}
declare class EngineMismatchError extends AuthError {
    readonly name = "EngineMismatchError";
    constructor(message: string);
}
declare class PermissionDeniedError extends AuthError {
    readonly permission: string;
    readonly principal: Principal | null;
    readonly name = "PermissionDeniedError";
    constructor(message: string, permission: string, principal: Principal | null);
}
declare class RoleDeniedError extends AuthError {
    readonly role: string;
    readonly principal: Principal | null;
    readonly name = "RoleDeniedError";
    constructor(message: string, role: string, principal: Principal | null);
}
declare class UserNotFoundError extends AuthError {
    readonly userId: string;
    readonly name = "UserNotFoundError";
    constructor(message: string, userId: string);
}
type GetSessionOptions = {
    accessCookieName?: string;
};
declare function getSession(headers: HeadersInit, engine: AuthEngine, opts?: GetSessionOptions): Promise<Principal | null>;
declare function createAuth(engine: AuthEngine): {
    getSession: (headers: HeadersInit, opts?: GetSessionOptions) => Promise<Principal | null>;
    signIn: (credentials: SignInCredentials) => Promise<SignInResult>;
    signOut: (sessionId: string, refreshToken?: string) => Promise<void>;
    refresh: (refreshToken: string) => Promise<RefreshResult | null>;
};
declare function hasPermission(principal: Principal, permission: string): boolean;
declare function isAtLeastRole(principal: Principal, role: string, hierarchy: readonly string[]): boolean;
declare function requirePermission(permission: string): (principal: Principal | null) => Principal;
/**
 * Role gate — the role-based twin of `requirePermission`. Returns a resolver:
 *   - `principal == null`              → throws `InvalidSessionError`
 *   - `!isAtLeastRole(p, role, hier)`  → throws `RoleDeniedError`
 *   - else                             → returns the principal
 *
 * Use with engines that populate `Principal.roles` (the custom engine does; `requirePermission`
 * is capability-based and inert there). Host admin guard:
 * `requireRole('admin', HIERARCHY)(await getSession(headers, engine))`.
 */
declare function requireRole(role: string, hierarchy: readonly string[]): (principal: Principal | null) => Principal;

export { type AuthEngine, AuthError, type CreateUserInput, EngineMismatchError, type GetSessionOptions, InvalidSessionError, PermissionDeniedError, type Principal, RateLimitedError, type RefreshResult, RevokedSessionError, RoleDeniedError, type Session, type SignInCredentials, type SignInResult, type UserAdminEngine, UserNotFoundError, createAuth, getSession, hasPermission, isAtLeastRole, requirePermission, requireRole };