/**
 * ScopeMatrixClient — fetches the tool→scope mapping from AuthSec, caches
 * with TTL.
 *
 * TypeScript parity port of python/runtime/scope_matrix.py.
 *
 * Endpoint: ``GET {authorizationServer}/authsec/resource-servers/{id}/sdk-policy``.
 *
 * Behaviour:
 *
 *  - On success with ``policy_complete=true`` → cache the map, clear errors.
 *  - On ``policy_complete=false`` → enforce deny-all by clearing the cached
 *    map; record the lifecycle reason for observability. Never serve stale
 *    data in this case.
 *  - On transport / decode failure → leave the previously-cached map intact
 *    and serve it until ``maxStaleAgeSeconds``; after that, refuse with the
 *    cached error.
 *  - Background refresh on TTL expiry with a guard so only one refresh runs
 *    at a time.
 */
import type { Config } from './config.js';
import { type ToolPolicyResult, type ToolScopeMap } from './policy.js';
/**
 * Returned when the backend signals ``policy_complete=false``. Callers must
 * treat this as deny-all and must NOT fall back to a stale local cache for
 * tool authorization.
 */
export declare class PolicyIncompleteError extends Error {
    readonly state: string;
    readonly reason: string;
    constructor(state: string, reason: string);
}
/** Snapshot of the current cache state — useful for observability. */
export interface CacheStatus {
    hasData: boolean;
    fetchedAt: Date | null;
    staleAgeMs: number;
    lastErr: Error | null;
    lastErrAt: Date | null;
    policyState: string;
    policyComplete: boolean;
    generation: number;
}
interface RawPolicyResponse {
    state?: string;
    policy_complete?: boolean;
    reason?: string;
    generation?: number;
    scopes_supported?: string[];
    tool_policy?: Array<{
        name?: string;
        is_public?: boolean;
        required_scopes?: string[];
    }>;
    tools?: Record<string, string[]>;
}
export declare class ScopeMatrixClient {
    readonly endpoint: string;
    private readonly clientId;
    private readonly clientSecret;
    private readonly ttlMs;
    private readonly maxStaleAgeMs;
    private readonly retryBackoffMs;
    private readonly requestTimeoutMs;
    private state;
    private refreshing;
    constructor(cfg: Config);
    /**
     * One-shot fetch. Does NOT touch the cache. Throws
     * ``PolicyIncompleteError`` when the backend signals
     * ``policy_complete=false``; throws Error on transport/decode failures.
     */
    fetch(): Promise<{
        toolMap: ToolScopeMap;
        payload: RawPolicyResponse;
    }>;
    /**
     * Fetch and update the cache. On policy_complete=false, clears the cache
     * (deny-all) and records the reason. On transport failure, leaves the
     * cache intact so previously-good policy keeps serving until
     * ``maxStaleAge``.
     */
    fetchAndCache(): Promise<void>;
    /**
     * Return the cached ``scopes_supported`` list (authoritative from AuthSec).
     * Triggers a background refresh on TTL expiry, same as ``getCached()``.
     * Returns ``null`` when the cache has never been populated successfully —
     * callers (like the PRM builder) should fall back to local ``cfg.supportedScopes``
     * in that case so the server still serves a metadata document at boot.
     */
    getScopesSupported(): Promise<string[] | null>;
    /**
     * Return the cached map. Triggers a background refresh on TTL expiry.
     * Throws if the cache was never populated successfully OR exceeded
     * ``maxStaleAge`` with the last refresh in error.
     */
    getCached(): Promise<ToolScopeMap | null>;
    /** Convenience: look up a single tool through the cached map. */
    lookupTool(toolId: string): Promise<ToolPolicyResult>;
    cacheStatus(): CacheStatus;
    private backgroundRefresh;
}
export {};
//# sourceMappingURL=scopeMatrix.d.ts.map