/**
 * Agent capability enforcement — grant-driven authorization.
 *
 * This layer sits **above** {@link enforceAttributionPolicy} (which gates
 * by {@link AttributionTier}) and **below** ordinary user auth. Where
 * the attribution policy asks "is this write attributable at all?",
 * capability enforcement asks "is *this* specific agent allowed to
 * touch *this* specific entity_type via *this* operation?".
 *
 * Source of truth (Stronger AAuth Admission plan):
 *   - Capabilities live on `agent_grant` entities, scoped per
 *     `user_id`, managed in the Inspector or via the standard
 *     entity-store toolkit when the caller has the bootstrap grant.
 *   - The admission service ({@link ./aauth_admission.js}) resolves
 *     a verified AAuth identity to the matching grant and stamps the
 *     resolved `capabilities` onto `req.aauthAdmission` /
 *     {@link RequestContext.aauthAdmission} before any handler runs.
 *   - {@link enforceAgentCapability} reads those capabilities directly.
 *
 * The legacy environment-variable registry (`NEOTOMA_AGENT_CAPABILITIES_*`)
 * is REMOVED in this release. {@link assertNoLegacyCapabilityEnv} runs
 * during boot and fails fast with a structured pointer to the
 * `neotoma agents grants import` migration command.
 */
import type { AttributionTier, AgentIdentity } from "../crypto/agent_identity.js";
/**
 * Canonical operation identifier. Mirrors the top-level MCP/REST entry
 * points that touch durable Neotoma state.
 */
export type AgentCapabilityOp = "store" | "store_structured" | "create_relationship" | "correct" | "retrieve";
export interface AgentCapabilityEntry {
    op: AgentCapabilityOp;
    /** Allowed entity types for this op. `"*"` widens to any entity_type. */
    entity_types: string[];
}
/** Identity match shape (still used by import / Inspector serialisation). */
export interface AgentCapabilityMatch {
    /** Match by AAuth `sub` claim. */
    sub?: string;
    /** Optional AAuth `iss` claim — when set, both `sub` AND `iss` must match. */
    iss?: string;
    /** Match by RFC 7638 JWK thumbprint. */
    thumbprint?: string;
}
/** Legacy registry shape — used only by the env-config import command. */
export interface AgentCapabilityAgent {
    match: AgentCapabilityMatch;
    capabilities: AgentCapabilityEntry[];
}
/**
 * Acting agent on the current request. Built from the resolved
 * {@link AgentIdentity}, possibly enriched by the admission service.
 *
 * `capabilities` is non-null only when the request was admitted via an
 * `agent_grant` — otherwise the registry has no information about
 * this caller and {@link enforceAgentCapability} relies on
 * `default_deny` to decide.
 */
export interface AgentCapabilityContext {
    sub?: string;
    iss?: string;
    thumbprint?: string;
    tier: AttributionTier;
    capabilities: AgentCapabilityEntry[] | null;
    agentLabel: string;
    admitted: boolean;
}
/** Structured denial. HTTP handlers surface this as 403 `capability_denied`. */
export declare class AgentCapabilityError extends Error {
    readonly code: "capability_denied";
    readonly statusCode = 403;
    readonly op: AgentCapabilityOp;
    readonly entityType: string;
    readonly agentLabel: string;
    readonly hint: string;
    constructor(params: {
        op: AgentCapabilityOp;
        entityType: string;
        agentLabel: string;
        hint: string;
    });
    toErrorEnvelope(): {
        code: string;
        message: string;
        op: AgentCapabilityOp;
        entity_type: string;
        agent_label: string;
        hint: string;
    };
}
export declare class LegacyAgentCapabilityEnvError extends Error {
    readonly code: "legacy_agent_capabilities_env";
    readonly variables: string[];
    readonly migrationCommand = "neotoma agents grants import --owner-user-id <user_id>";
    constructor(variables: string[]);
}
/**
 * Throws {@link LegacyAgentCapabilityEnvError} when any of the legacy
 * `NEOTOMA_AGENT_CAPABILITIES_*` variables are still set. Call once
 * during server boot (see {@link assertCapabilityEnvOnBoot} for the
 * Express-friendly wrapper used in `src/server.ts`).
 */
export declare function assertNoLegacyCapabilityEnv(env?: NodeJS.ProcessEnv): void;
/** ---------- Default-deny configuration ---------- */
/**
 * Whether to deny otherwise-unrecognised AAuth-verified agents. Mirrors
 * the legacy `default_deny` registry flag: an admitted agent always
 * follows its grant capabilities; an UN-admitted but signature-verified
 * agent is denied iff this flag is true and its tier is sufficient.
 */
export declare function isAgentDefaultDenyEnabled(): boolean;
/**
 * Assemble an {@link AgentCapabilityContext} for the current request.
 *
 * Returns `null` when the request has no agent identity at all — pure
 * user-authenticated traffic (Bearer / OAuth / local / Inspector)
 * should not flow through capability enforcement.
 *
 * Admission context is read from {@link getCurrentAAuthAdmission}
 * (lazy-imported to break a module cycle): when an `admitted` grant is
 * resolved, its capabilities and label are surfaced; otherwise the
 * caller is treated as an unrecognised agent.
 */
export declare function contextFromAgentIdentity(identity: AgentIdentity | null | undefined): AgentCapabilityContext | null;
/**
 * Enforce capability-based authorization. Behaviour:
 *
 *   1. `entityTypes` empty → no-op.
 *   2. Admitted agent → every `(op, entity_type)` pair must be covered
 *      by the grant's capabilities. Mismatch → throw.
 *   3. Unadmitted but signature-verified agent (`tier in {hardware,
 *      software, operator_attested}`) AND
 *      {@link isAgentDefaultDenyEnabled} → throw.
 *   4. Otherwise → allow (preserves legacy behaviour for unknown
 *      agents during rollout).
 *
 * Throws {@link AgentCapabilityError} on denial.
 */
export declare function enforceAgentCapability(op: AgentCapabilityOp, entityTypes: string[], ctx: AgentCapabilityContext): void;
/** ---------- Test/diagnostic helpers ---------- */
export declare function getAgentCapabilitiesSource(): string;
//# sourceMappingURL=agent_capabilities.d.ts.map