Interface McpProtectionKeyringManager

@ThreadSafe
public interface McpProtectionKeyringManager

Thread-safe, server-owned control plane for the live MCP protection key ring.

Each server owns independent live state copied from its immutable McpProtectionConfig. Every successful mutation has one linearization point and validates against the live ring at that same point. Rejected mutations leave the ring unchanged.

A fleet rotation stages the identical key on every instance, compares the secret-free snapshots, activates the staged key everywhere, waits for the former key's maximum request-state lifetime and outstanding sealing reservations, and finally removes the former key from every instance.

A sealing reservation is Soklet's internal acquisition of one exact active key immediately before sealing. Activation may linearize while an earlier reservation finishes under the former key. Removal rejects a key until all of its reservations have drained.

Author:

Mark Allen

Method Summary

Modifier and Type	Method	Description
void	activateStagedKey(@NonNull String keyId)	Activates a staged key and atomically demotes the former active key.
@NonNull Optional<@NonNull McpProtectionKeyringSnapshot>	getKeyringSnapshot()	Captures active and verification IDs plus their configuration fingerprint at one linearization point.
@NonNull McpProtectionMode	getProtectionMode()
@NonNull Boolean	removeVerificationKey(@NonNull String keyId)	Removes a verification-only key.
void	rotateActiveKey(@NonNull McpProtectionKey activeKey)	Atomically stages and activates a key.
void	stageVerificationKey(@NonNull McpProtectionKey verificationKey)	Adds a verification-only key to the live production ring.

Method Details

getProtectionMode

@NonNull McpProtectionMode getProtectionMode()

Returns:

this server's effective protection mode

getKeyringSnapshot

@NonNull Optional<@NonNull McpProtectionKeyringSnapshot> getKeyringSnapshot()

Captures active and verification IDs plus their configuration fingerprint at one linearization point.

Returns:

secret-free snapshot, or empty when no production ring is active

stageVerificationKey

void stageVerificationKey(@NonNull McpProtectionKey verificationKey)

Adds a verification-only key to the live production ring.

Re-staging a byte-identical key under the same ID is an idempotent no-op, whether it is currently active or verification-only. The mutation rejects a duplicate ID with different material, material already present under a different ID, or material equal to the active trace-correlation key.

Parameters:

verificationKey - key to stage

Throws:

IllegalArgumentException - if the mutation is invalid

IllegalStateException - if this server has no production keyring

activateStagedKey

void activateStagedKey(@NonNull String keyId)

Activates a staged key and atomically demotes the former active key. Activating the already-active ID is an idempotent no-op.

Parameters:

keyId - staged verification-key ID

Throws:

IllegalArgumentException - if the ID is unknown

IllegalStateException - if this server has no production keyring

rotateActiveKey

void rotateActiveKey(@NonNull McpProtectionKey activeKey)

Atomically stages and activates a key.

This convenience is retry-safe for the byte-identical already-active key. Fleet deployments normally stage on every instance before activation.

Parameters:

activeKey - new active key

Throws:

IllegalArgumentException - if the mutation is invalid

IllegalStateException - if this server has no production keyring

removeVerificationKey

@NonNull Boolean removeVerificationKey(@NonNull String keyId)

Removes a verification-only key.

An absent ID returns false; removing the active ID is rejected. A key with an outstanding sealing reservation fails transiently with McpProtectionKeyInUseException.

Parameters:

keyId - verification-only key ID

Returns:

whether a key was removed

Throws:

IllegalArgumentException - if the ID names the active key

IllegalStateException - if this server has no production keyring

McpProtectionKeyInUseException - if the key is still used for sealing