/**
 * Runtime — the customer-facing entry point for protecting an MCP server.
 *
 * TypeScript parity port of python/runtime/server.py and go-sdk's Runtime.
 *
 * Composes the HybridValidator + ScopeMatrixClient + manifest publisher into
 * a single facade with a single ``authorize(token, toolId)`` method.
 */
import { type Config, type ManifestToolInput } from './config.js';
import type { Principal } from './principal.js';
/** Denial codes mirror python/runtime — AI clients depend on cross-SDK parity. */
export type DenialCode = 'invalid_token' | 'invalid_audience' | 'scope_insufficient' | 'policy_unavailable';
export interface AuthorizeDenial {
    code: DenialCode;
    description: string;
    status: number;
    wwwAuthenticate: string;
    /** Set when denial code is ``scope_insufficient`` so the caller can echo it. */
    requiredScopes?: string[];
    /** Scopes the token actually carries. Lets the client SDK show
     *  "you have [a,b], you need [c]" instead of just "you need [c]". */
    grantedScopes?: string[];
    tool?: string;
    /** Stable, parseable subreason for 401s — `token_revoked`,
     *  `client_registration_revoked`, `token_expired`, `audience_mismatch`,
     *  `no_token`, `invalid_token`. Empty for non-401 denials. */
    reason?: string;
}
export type AuthorizeResult = {
    allowed: true;
    principal: Principal;
} | {
    allowed: false;
    denial: AuthorizeDenial;
};
/** Runtime that protects an MCP server. */
export declare class Runtime {
    readonly cfg: Config;
    private readonly validator;
    private readonly policyMode;
    private readonly scopeClient;
    private constructor();
    /**
     * Construct and initialize a Runtime. Performs the initial scope-matrix
     * fetch (mandatory under ``remote_required``) so that boot fails loudly on
     * misconfiguration.
     */
    static create(cfg: Config): Promise<Runtime>;
    /**
     * Run mandatory startup actions. Idempotent; safe to call once during
     * boot. Manifest publish is fire-and-forget.
     */
    startup(opts?: {
        tools?: ManifestToolInput[];
    }): Promise<void>;
    /**
     * Return the authoritative ``scopes_supported`` list for this RS, fetched
     * from AuthSec via the scope matrix (TTL-cached, refreshed in the
     * background). The PRM endpoint uses this so admin-side scope edits in the
     * AuthSec UI propagate to MCP clients within one refresh cycle (≤5 min) —
     * **no code change in the MCP server**.
     *
     * Returns ``null`` when:
     *  - the runtime has no scope matrix client (policyMode=local_only / open),
     *  - the cache has never been populated and there's no usable fallback,
     *  - the cache exceeded ``maxStaleAge`` with the last refresh in error.
     *
     * Callers (PRM builder) should fall back to ``cfg.supportedScopes`` when
     * this returns ``null`` so the server still serves a metadata document.
     */
    getAuthoritativeScopes(): Promise<string[] | null>;
    /** Pure token validation; throws ValidationError on failure. */
    validateToken(token: string): Promise<Principal>;
    /**
     * Top-level authorization: validate the bearer token AND check tool scope.
     * Returns a structured result with everything needed to build a 401/403/503.
     */
    authorize(token: string, toolId: string): Promise<AuthorizeResult>;
    /**
     * Authorize an already-validated principal for a specific MCP tool. This is
     * used by server middleware for tools/list filtering and by custom hosts
     * that validate tokens once per request.
     */
    authorizePrincipal(principal: Principal, toolId: string): Promise<AuthorizeResult>;
    private denyInvalidToken;
    private denyInvalidAudience;
    private denyScopeInsufficient;
    private denyPolicyUnavailable;
}
//# sourceMappingURL=runtime.d.ts.map