/**
 * ASI-07 (OWASP Agentic Top 10 2026) — Inter-Agent Communication signing.
 *
 * Microsoft AGT parity: per-message authenticity for agent↔agent messages.
 * A sending agent signs an {@link AgentMessageEnvelope} over the canonical
 * JSON of its authenticated fields ({agentId, nonce, payload, timestamp})
 * with its Ed25519 private key. A receiving agent verifies the signature,
 * rejects replays (nonce already seen), and rejects messages outside a
 * bounded clock-skew window BEFORE acting on the message.
 *
 * Why per-message (not just handshake): handshake-only identity binding lets
 * a compromised relay or man-in-the-middle inject/forge messages mid-session.
 * Signing every message closes the inter-agent injection class (ASI-07).
 *
 * Locked Architectural Invariants honored:
 *   - I-2 (advisory, never authoritative) / I-3 (graceful degradation):
 *     {@link verifyAgentMessage} NEVER throws. Every failure mode returns a
 *     structured {valid:false, status} result. A malformed or hostile message
 *     can never crash the agent's execution path — the receiving org's policy
 *     decides what to do with a non-`valid` result (WARN / BLOCK / drop).
 *   - I-10 (push-receive only): signing/verification are pure in-process
 *     crypto. No network call, no outbound dependency, no platform contact.
 *
 * Crypto: Node built-in `crypto` Ed25519 (`crypto.sign(null, ...)` /
 * `crypto.verify(null, ...)`), mirroring the established
 * `packages/compliance-agent-runtime/src/signing.ts` passport-signing
 * primitive. Self-contained here (no cross-package import) so the orchestrator
 * adapters in `src/orchestrator-adapters/*` can depend on it without reaching
 * into another workspace package.
 *
 * @connexum/ai-governance
 */
/** An Ed25519 keypair for an agent's inter-agent message signing. */
export interface AgentMessageKeyPair {
    /** PEM-encoded PKCS8 Ed25519 private key (sensitive — never logged/persisted in cleartext). */
    privateKeyPem: string;
    /** PEM-encoded SPKI Ed25519 public key (non-secret — distributed to peers/registry). */
    publicKeyPem: string;
}
/**
 * A signed inter-agent message. The signature covers the canonical JSON of
 * the AUTHENTICATED fields only: `{agentId, nonce, payload, timestamp}`.
 * `signature` and `algorithm` are NOT part of the signed body.
 */
export interface AgentMessageEnvelope<T = unknown> {
    /** Application message body. Any JSON-serializable value. */
    payload: T;
    /** Sender agent id (used to resolve the verifying public key). */
    agentId: string;
    /** ISO-8601 timestamp the message was signed (skew-checked at verify). */
    timestamp: string;
    /** Unique per-message value for replay protection. */
    nonce: string;
    /** Base64url-encoded Ed25519 signature over canonical {agentId,nonce,payload,timestamp}. */
    signature: string;
    /** Signing algorithm + canonicalization format. */
    algorithm: 'ed25519/canonical-json';
}
export type AgentMessageVerifyStatus = 'valid' | 'bad-signature' | 'replay' | 'expired' | 'unknown-sender' | 'malformed';
/** Structured result of {@link verifyAgentMessage}. Never thrown — always returned. */
export interface AgentMessageVerifyResult {
    /** True iff signature valid AND not a replay AND within skew window AND sender known. */
    valid: boolean;
    /** Machine-readable outcome. `'valid'` iff `valid === true`. */
    status: AgentMessageVerifyStatus;
    /** Sender agent id when extractable, else null. */
    agentId: string | null;
    /** Human-readable explanation (for audit/log; safe to surface to operators). */
    reason: string;
}
export interface SignAgentMessageInput<T = unknown> {
    payload: T;
    agentId: string;
    privateKeyPem: string;
    /** Override the nonce (default: a fresh random 128-bit base64url value). */
    nonce?: string;
    /** Override the signing timestamp ISO string (default: now). */
    timestamp?: string;
}
export interface VerifyAgentMessageOptions {
    /**
     * Resolve the sender's published public key (PEM SPKI) by agentId.
     * Return `null`/`undefined` for an unknown sender → status `'unknown-sender'`.
     */
    resolvePublicKey: (agentId: string) => string | null | undefined;
    /**
     * Replay predicate: return true if this nonce was already consumed.
     * Optional — when omitted, replay protection is skipped (signature + skew
     * still enforced). Inject a {@link NonceStore}-backed or in-memory predicate.
     */
    nonceSeen?: (nonce: string) => boolean;
    /**
     * Record a nonce as consumed. Called ONLY when the message is otherwise
     * valid (good signature, in-window, known sender) so an invalid/forged
     * message can never burn a legitimate future nonce.
     */
    recordNonce?: (nonce: string) => void;
    /** Max allowed |now - timestamp| in ms before `'expired'`. Default 300_000 (5 min). */
    maxClockSkewMs?: number;
    /** Injectable clock (ms epoch) for deterministic tests. Default Date.now(). */
    now?: number;
}
/**
 * Canonical JSON encoding: object keys sorted lexicographically at every
 * nesting level, no insignificant whitespace, UTF-8. Same value → same bytes
 * regardless of source key order. Mirrors the compliance-agent-runtime
 * passport signer's canonical form (internal-interop subset, not RFC 8785).
 */
export declare function canonicalJsonStringify(value: unknown): string;
/** Generate a fresh Ed25519 keypair for inter-agent message signing. */
export declare function generateAgentMessageKeyPair(): AgentMessageKeyPair;
/**
 * Sign an inter-agent message. Returns a fully-formed envelope ready to send.
 * A fresh random nonce + current timestamp are generated unless overridden.
 */
export declare function signAgentMessage<T = unknown>(input: SignAgentMessageInput<T>): AgentMessageEnvelope<T>;
/**
 * Verify a signed inter-agent message. NEVER throws — returns a structured
 * result for every input, including hostile/garbage envelopes.
 *
 * Order of checks (cheap structural rejection first; nonce burned LAST so a
 * forged message can't consume a legitimate future nonce):
 *   1. structural well-formedness + algorithm  → `malformed`
 *   2. clock-skew window                        → `expired`
 *   3. sender public key resolvable             → `unknown-sender`
 *   4. Ed25519 signature over canonical body    → `bad-signature`
 *   5. replay (nonce already seen)              → `replay`
 *   6. all pass → record nonce, return `valid`
 */
export declare function verifyAgentMessage<T = unknown>(envelope: AgentMessageEnvelope<T>, opts: VerifyAgentMessageOptions): AgentMessageVerifyResult;
//# sourceMappingURL=agent-message-envelope.d.ts.map