/**
 * Protected entity types — write-side guard.
 *
 * Some entity types are governance state (e.g. `agent_grant`) and must not
 * be writable by every agent that can otherwise pass attribution policy.
 * The Stronger AAuth Admission plan introduces this guard so agents can
 * self-manage grants only when an explicit grant capability authorises
 * it, while user-authenticated callers (Bearer / OAuth / local-dev /
 * sandbox-user) keep working without ceremony.
 *
 * Rules enforced by {@link assertCanWriteProtected}:
 *
 *   1. If `entity_type` is not in {@link PROTECTED_ENTITY_TYPES}, return
 *      immediately — the type is unprotected.
 *   2. If the request is admitted via AAuth grants (`admission.admitted`),
 *      the resolved grant must include a capability covering `op` for
 *      `entity_type` (or `*`). Missing → `AgentCapabilityError`.
 *   3. If the request is NOT admitted but carries an AAuth identity (any
 *      of `sub` / `thumbprint` / `clientName`), it is treated as an
 *      unrecognised agent and rejected. This catches the
 *      "AAuth-verified-but-unknown" and "self-reported clientInfo" cases
 *      that should never mutate governance state.
 *   4. Otherwise (no agent identity at all) the caller is plain
 *      user-authenticated; allow.
 *
 * The guard is invoked at the structured-store entry points (HTTP
 * `storeStructuredForApi`, MCP `storeStructuredInternal`) AND deeply at
 * the {@link createObservation} / {@link createCorrection} insertion
 * sites so an alternative write path cannot leak by skipping the upper
 * gate.
 */
import { type AgentCapabilityEntry, type AgentCapabilityOp } from "./agent_capabilities.js";
import type { AgentIdentity } from "../crypto/agent_identity.js";
/**
 * Diagnostic record describing how the current request was admitted via
 * AAuth grants. Threaded through the request context so the deep guard
 * can inspect it without coupling to Express. `null` when this request
 * did not pass through the admission service.
 */
export interface AAuthAdmissionContext {
    admitted: boolean;
    /** Reason the admission service produced when `admitted === false`. */
    reason?: AAuthAdmissionReason;
    /** Owner user id of the matched grant. */
    user_id?: string;
    /** Stable id of the matched grant entity. */
    grant_id?: string;
    /** Human-readable grant label (mirrors the grant's `label` field). */
    agent_label?: string;
    /**
     * Capabilities array sourced verbatim from the grant entity. Empty
     * array when admitted but the grant declared no capabilities (the
     * caller can sign requests but can't store anything).
     */
    capabilities?: AgentCapabilityEntry[];
}
export type AAuthAdmissionReason = "admitted" | "no_grants_for_user" | "no_match" | "grant_revoked" | "grant_suspended" | "strict_rejected" | "aauth_disabled" | "not_signed";
/** Returns true when writes to `entity_type` are gated by this guard. */
export declare function isProtected(entity_type: string): boolean;
/** Snapshot of the current protected-entity-types list. */
export declare function getProtectedEntityTypes(): string[];
interface AssertCanWriteProtectedParams {
    entity_type: string;
    op: AgentCapabilityOp;
    identity: AgentIdentity | null;
    admission: AAuthAdmissionContext | null;
}
/**
 * Throws {@link AgentCapabilityError} when the active caller is not
 * permitted to mutate a protected entity type. Returns silently for
 * unprotected types and for user-authenticated callers.
 */
export declare function assertCanWriteProtected(params: AssertCanWriteProtectedParams): void;
/**
 * Convenience wrapper: enforces the guard for a batch of entity types.
 * No-ops the empty case so upper layers can call it unconditionally.
 */
export declare function assertCanWriteProtectedBatch(params: {
    entity_types: string[];
    op: AgentCapabilityOp;
    identity: AgentIdentity | null;
    admission: AAuthAdmissionContext | null;
}): void;
export {};
//# sourceMappingURL=protected_entity_types.d.ts.map