Hovel Python SDK API

This reference is generated with Sphinx autodoc from the importable hovel_sdk package. The module-author guide explains lifecycle rules and operator-facing behavior; this page is the callable API surface.

Module Lifecycle

class hovel_sdk.HovelModule

Bases: ABC

name: str = ''

version: str = ''

summary: str = ''

module_type: str = ''

description: str = ''

tags: ClassVar[tuple[str, ...]] = ()

discovery_context: ClassVar[dict[str, Any]] = {}

global_config: ClassVar[tuple[Requirement, ...]] = ()

target_config: ClassVar[tuple[Requirement, ...]] = ()

outputs: ClassVar[dict[str, Any]] = {}

planning_context: ClassVar[dict[str, Any]] = {}

info() → dict[str, Any]

module_schema() → dict[str, Any]

describe_steps() → dict[str, Any]

prepare_step(request: dict[str, Any]) → dict[str, Any]

execute_step(request: dict[str, Any]) → dict[str, Any]

cleanup_step(request: dict[str, Any]) → dict[str, Any]

describe_mesh(_request: MeshDescribeRequest) → MeshDescriptor | Awaitable[MeshDescriptor]

mesh_topology(_request: MeshTopologyRequest) → MeshTopology | Awaitable[MeshTopology]

list_mesh_beacons(_request: MeshBeaconRequest) → list[MeshBeacon] | Awaitable[list[MeshBeacon]]

list_mesh_listeners(_request: MeshListenerListRequest) → list[MeshListener] | Awaitable[list[MeshListener]]

start_mesh_listener(_request: MeshListenerStartRequest) → MeshListener | Awaitable[MeshListener]

stop_mesh_listener(_request: MeshListenerStopRequest) → MeshListener | Awaitable[MeshListener]

run_mesh_task(_ctx: Context, _request: MeshTaskRequest) → MeshTaskResult | Awaitable[MeshTaskResult]

open_mesh_stream(_ctx: Context, _request: MeshStreamRequest) → SessionRef | Awaitable[SessionRef]

load_runtime_credential(_request: CredentialRuntimeRequest) → CredentialDeliveryReceipt | Awaitable[CredentialDeliveryReceipt]

describe_credential_delivery() → CredentialDeliveryDescriptor | Awaitable[CredentialDeliveryDescriptor]

load_credential_files(_request: CredentialFilesRequest) → CredentialDeliveryReceipt | Awaitable[CredentialDeliveryReceipt]

encode_credential_material(_request: CredentialEncodingRequest) → CredentialEncodingResult | Awaitable[CredentialEncodingResult]

stamp_credential(_request: CredentialStampExecutionRequest) → CredentialStampExecutionResult | Awaitable[CredentialStampExecutionResult]

abstractmethod run(ctx: Context) → Result | Awaitable[Result]

class hovel_sdk.Context(run_id: 'str', module_id: 'str', target: 'str', inputs: 'dict[str, Any]'=<factory>, chain_config: 'dict[str, Any]'=<factory>, target_config: 'dict[str, Any]'=<factory>, agent: 'AgentContext | None' = None, log: 'logging.Logger' = <factory>, sessions: 'SessionRegistry | None' = None)

Bases: object

run_id: str

module_id: str

target: str

inputs: dict[str, Any]

chain_config: dict[str, Any]

target_config: dict[str, Any]

agent: AgentContext | None = None

log: logging.Logger

sessions: SessionRegistry | None = None

input(key: str, default: Any = None) → Any

async open_session(session: Session, *, name: str = '', kind: str = 'shell', transport: str = 'stdio', capabilities: tuple[str, ...] = ('read', 'write', 'close')) → SessionRef

hovel_sdk.serve(module: HovelModule, stdin: BinaryIO | None = None, stdout: BinaryIO | None = None) → None

Configuration

class hovel_sdk.Requirement(key: 'str', type: 'str' = 'string', required: 'bool' = True, default: 'str' = '', description: 'str' = '', allowed: 'list[str]' = <factory>, secret: 'bool' = False)

Bases: object

key: str

type: str = 'string'

required: bool = True

default: str = ''

description: str = ''

allowed: list[str]

secret: bool = False

to_rpc() → dict[str, Any]

Results

class hovel_sdk.Result(status: 'str', summary: 'str', findings: 'list[Finding]' = <factory>, artifacts: 'list[Artifact]' = <factory>, outputs: 'dict[str, Any]'=<factory>, sessions: 'list[SessionRef]' = <factory>, installed_payloads: 'list[InstalledPayload | dict[str, Any]]'=<factory>, agent_hints: 'list[AgentHint | dict[str, Any]]'=<factory>)

Bases: object

status: str

summary: str

findings: list[Finding]

artifacts: list[Artifact]

outputs: dict[str, Any]

sessions: list[SessionRef]

installed_payloads: list[InstalledPayload | dict[str, Any]]

agent_hints: list[AgentHint | dict[str, Any]]

classmethod ok(outputs: dict[str, Any] | None = None, *, summary: str = 'module completed', findings: list[Finding] | None = None, artifacts: list[Artifact] | None = None, sessions: list[SessionRef] | None = None) → Result

classmethod failed(summary: str, *, findings: list[Finding] | None = None, artifacts: list[Artifact] | None = None, outputs: dict[str, Any] | None = None, sessions: list[SessionRef] | None = None) → Result

with_installed_payloads(*payloads: InstalledPayload | dict[str, Any]) → Result

with_agent_hints(*hints: AgentHint | dict[str, Any]) → Result

to_rpc(*, sessions: list[SessionRef] | None = None) → dict[str, Any]

class hovel_sdk.Finding(title: 'str', severity: 'str' = 'info', detail: 'str' = '')

Bases: object

title: str

severity: str = 'info'

detail: str = ''

to_rpc() → dict[str, Any]

class hovel_sdk.Artifact(name: 'str', kind: 'str', data: 'str' = '', path: 'str' = '')

Bases: object

name: str

kind: str

data: str = ''

path: str = ''

classmethod inline(name: str, kind: str, data: str | bytes) → Artifact

classmethod text(name: str, data: str | bytes) → Artifact

classmethod json(name: str, data: Any) → Artifact

classmethod file(path: str | Path, *, name: str | None = None, kind: str = 'application/octet-stream') → Artifact

to_rpc() → dict[str, Any]

class hovel_sdk.InstalledPayload(provider: 'str', payload_id: 'str', target: 'str', state: 'str', payload_version: 'str' = '', target_id: 'str' = '', transport: 'str' = '', endpoint: 'str' = '', instance_key: 'str' = '', stamp_id: 'str' = '', supports_reconnect: 'bool' = False, supports_multiple_sessions: 'bool' = False, reconnect: 'PayloadProviderRecord | None' = None, cleanup: 'PayloadProviderRecord | None' = None, metadata: 'dict[str, Any]'=<factory>)

Bases: object

provider: str

payload_id: str

target: str

state: str

payload_version: str = ''

target_id: str = ''

transport: str = ''

endpoint: str = ''

instance_key: str = ''

stamp_id: str = ''

supports_reconnect: bool = False

supports_multiple_sessions: bool = False

reconnect: PayloadProviderRecord | None = None

cleanup: PayloadProviderRecord | None = None

metadata: dict[str, Any]

to_rpc() → dict[str, Any]

class hovel_sdk.PayloadProviderRecord(schema: 'str' = '', descriptor: 'dict[str, Any]'=<factory>, provider_id: 'str' = '', schema_version: 'str' = '')

Bases: object

schema: str = ''

descriptor: dict[str, Any]

provider_id: str = ''

schema_version: str = ''

to_rpc() → dict[str, Any]

Sessions

class hovel_sdk.SessionRef(id: 'str', run_id: 'str', module_id: 'str', target: 'str', name: 'str' = '', kind: 'str' = 'shell', state: 'str' = 'active', transport: 'str' = 'stdio', capabilities: 'tuple[str, ...]' = ('read', 'write', 'close'))

Bases: object

id: str

run_id: str

module_id: str

target: str

name: str = ''

kind: str = 'shell'

state: str = 'active'

transport: str = 'stdio'

capabilities: tuple[str, ...] = ('read', 'write', 'close')

to_rpc() → dict[str, Any]

class hovel_sdk.LineShellSession(*, prompt: str = '$ ', echo: bool = False)

Bases: object

Small async shell base class for modules that can answer line commands.

property closed: bool

async open() → None

async write(data: bytes) → None

async read(wait: float | None = None) → bytes

async close(reason: str = 'closed') → None

async emit(data: str | bytes) → None

async handle_command(command: str) → str | bytes | None

Mesh

HovelModule supplies optional Mesh hooks; providers override only the operations advertised by their descriptor.

class hovel_sdk.MeshDescriptor(name: 'str' = '', version: 'str' = '', summary: 'str' = '', capabilities: 'list[str]' = <factory>, topology: 'MeshTopology | None' = None, tasks: 'list[MeshTaskSpec]' = <factory>, listener_types: 'list[MeshListenerSpec]' = <factory>, triggers: 'list[MeshTrigger]' = <factory>, credential_delivery: 'CredentialDeliveryDescriptor | None' = None, attributes: 'dict[str, Any]'=<factory>)

Bases: object

name: str = ''

version: str = ''

summary: str = ''

capabilities: list[str]

topology: MeshTopology | None = None

tasks: list[MeshTaskSpec]

listener_types: list[MeshListenerSpec]

triggers: list[MeshTrigger]

credential_delivery: CredentialDeliveryDescriptor | None = None

attributes: dict[str, Any]

to_rpc() → dict[str, Any]

class hovel_sdk.MeshDescribeRequest(agent: 'AgentContext | None' = None)

Bases: object

agent: AgentContext | None = None

classmethod from_rpc(value: dict[str, Any]) → MeshDescribeRequest

class hovel_sdk.MeshTopology(root: 'str' = '', nodes: 'list[MeshNode]' = <factory>, links: 'list[MeshLink]' = <factory>, routes: 'list[MeshRoute]' = <factory>, attributes: 'dict[str, Any]'=<factory>)

Bases: object

root: str = ''

nodes: list[MeshNode]

links: list[MeshLink]

routes: list[MeshRoute]

attributes: dict[str, Any]

to_rpc() → dict[str, Any]

class hovel_sdk.MeshTopologyRequest(root: 'str' = '', listener_id: 'str' = '', include_routes: 'bool' = False, agent: 'AgentContext | None' = None)

Bases: object

root: str = ''

listener_id: str = ''

include_routes: bool = False

agent: AgentContext | None = None

classmethod from_rpc(value: dict[str, Any]) → MeshTopologyRequest

class hovel_sdk.MeshNode(id: 'str', parent_id: 'str' = '', listener_id: 'str' = '', name: 'str' = '', kind: 'str' = '', state: 'str' = '', address: 'str' = '', platform: 'str' = '', os: 'str' = '', arch: 'str' = '', labels: 'dict[str, Any]'=<factory>, attributes: 'dict[str, Any]'=<factory>, capabilities: 'list[str]' = <factory>, last_seen: 'str' = '')

Bases: object

id: str

parent_id: str = ''

listener_id: str = ''

name: str = ''

kind: str = ''

state: str = ''

address: str = ''

platform: str = ''

os: str = ''

arch: str = ''

labels: dict[str, Any]

attributes: dict[str, Any]

capabilities: list[str]

last_seen: str = ''

to_rpc() → dict[str, Any]

class hovel_sdk.MeshLink(id: 'str', source: 'str', target: 'str', kind: 'str' = '', state: 'str' = '', transport: 'str' = '', cost: 'int' = 0, latency_ms: 'int' = 0, attributes: 'dict[str, Any]'=<factory>)

Bases: object

id: str

source: str

target: str

kind: str = ''

state: str = ''

transport: str = ''

cost: int = 0

latency_ms: int = 0

attributes: dict[str, Any]

to_rpc() → dict[str, Any]

class hovel_sdk.MeshRoute(nodes: 'list[str]', id: 'str' = '', links: 'list[str]' = <factory>, cost: 'int' = 0, attributes: 'dict[str, Any]'=<factory>)

Bases: object

nodes: list[str]

id: str = ''

links: list[str]

cost: int = 0

attributes: dict[str, Any]

classmethod from_rpc(value: Any) → MeshRoute | None

to_rpc() → dict[str, Any]

class hovel_sdk.MeshBeacon(id: 'str', node_id: 'str', listener_id: 'str' = '', time: 'str' = '', state: 'str' = '', transport: 'str' = '', remote_addr: 'str' = '', interval_seconds: 'int' = 0, fields: 'dict[str, Any]'=<factory>)

Bases: object

id: str

node_id: str

listener_id: str = ''

time: str = ''

state: str = ''

transport: str = ''

remote_addr: str = ''

interval_seconds: int = 0

fields: dict[str, Any]

to_rpc() → dict[str, Any]

class hovel_sdk.MeshBeaconRequest(node_id: 'str' = '', listener_id: 'str' = '', since: 'str' = '', limit: 'int' = 0, agent: 'AgentContext | None' = None)

Bases: object

node_id: str = ''

listener_id: str = ''

since: str = ''

limit: int = 0

agent: AgentContext | None = None

classmethod from_rpc(value: dict[str, Any]) → MeshBeaconRequest

class hovel_sdk.MeshListener(id: 'str', name: 'str' = '', kind: 'str' = '', state: 'str' = '', deployment: 'str' = '', management: 'str' = '', node_id: 'str' = '', addresses: 'list[str]' = <factory>, protocols: 'list[str]' = <factory>, capabilities: 'list[str]' = <factory>, labels: 'dict[str, Any]'=<factory>, attributes: 'dict[str, Any]'=<factory>, updated_at: 'str' = '')

Bases: object

id: str

name: str = ''

kind: str = ''

state: str = ''

deployment: str = ''

management: str = ''

node_id: str = ''

addresses: list[str]

protocols: list[str]

capabilities: list[str]

labels: dict[str, Any]

attributes: dict[str, Any]

updated_at: str = ''

to_rpc() → dict[str, Any]

class hovel_sdk.MeshListenerSpec(kind: 'str', summary: 'str' = '', deployments: 'list[str]' = <factory>, management_modes: 'list[str]' = <factory>, protocols: 'list[str]' = <factory>, config_schema: 'dict[str, Any]'=<factory>, capabilities: 'list[str]' = <factory>)

Bases: object

kind: str

summary: str = ''

deployments: list[str]

management_modes: list[str]

protocols: list[str]

config_schema: dict[str, Any]

capabilities: list[str]

to_rpc() → dict[str, Any]

class hovel_sdk.MeshListenerListRequest(listener_id: 'str' = '', state: 'str' = '', agent: 'AgentContext | None' = None)

Bases: object

listener_id: str = ''

state: str = ''

agent: AgentContext | None = None

classmethod from_rpc(value: dict[str, Any]) → MeshListenerListRequest

class hovel_sdk.MeshListenerStartRequest(listener_id: 'str', name: 'str' = '', kind: 'str' = '', deployment: 'str' = '', management: 'str' = '', config: 'dict[str, Any]'=<factory>, agent: 'AgentContext | None' = None)

Bases: object

listener_id: str

name: str = ''

kind: str = ''

deployment: str = ''

management: str = ''

config: dict[str, Any]

agent: AgentContext | None = None

classmethod from_rpc(value: dict[str, Any]) → MeshListenerStartRequest

class hovel_sdk.MeshListenerStopRequest(listener_id: 'str', agent: 'AgentContext | None' = None)

Bases: object

listener_id: str

agent: AgentContext | None = None

classmethod from_rpc(value: dict[str, Any]) → MeshListenerStopRequest

class hovel_sdk.MeshTaskSpec(kind: 'str', summary: 'str' = '', config_schema: 'dict[str, Any]'=<factory>, read_only: 'bool' = False, destructive: 'bool' = False, opens_stream: 'bool' = False, target_scopes: 'list[str]' = <factory>, capabilities: 'list[str]' = <factory>)

Bases: object

kind: str

summary: str = ''

config_schema: dict[str, Any]

read_only: bool = False

destructive: bool = False

opens_stream: bool = False

target_scopes: list[str]

capabilities: list[str]

to_rpc() → dict[str, Any]

class hovel_sdk.MeshTaskRequest(kind: 'str', run_id: 'str' = '', task_id: 'str' = '', node_id: 'str' = '', listener_id: 'str' = '', target: 'str' = '', route: 'MeshRoute | None' = None, destination_host: 'str' = '', destination_port: 'int' = 0, protocol: 'str' = '', config: 'dict[str, Any]'=<factory>, args: 'list[str]' = <factory>, input_data: 'str' = '', input_encoding: 'str' = '', agent: 'AgentContext | None' = None)

Bases: object

kind: str

run_id: str = ''

task_id: str = ''

node_id: str = ''

listener_id: str = ''

target: str = ''

route: MeshRoute | None = None

destination_host: str = ''

destination_port: int = 0

protocol: str = ''

config: dict[str, Any]

args: list[str]

input_data: str = ''

input_encoding: str = ''

agent: AgentContext | None = None

classmethod from_rpc(value: dict[str, Any]) → MeshTaskRequest

class hovel_sdk.MeshTaskResult(status: 'str' = 'succeeded', summary: 'str' = '', task_id: 'str' = '', node_id: 'str' = '', listener_id: 'str' = '', route: 'MeshRoute | None' = None, destination_host: 'str' = '', destination_port: 'int' = 0, protocol: 'str' = '', outputs: 'dict[str, Any]'=<factory>, findings: 'list[Finding]' = <factory>, artifacts: 'list[Artifact]' = <factory>, sessions: 'list[SessionRef]' = <factory>, beacons: 'list[MeshBeacon]' = <factory>, events: 'list[MeshEvent]' = <factory>, agent_hints: 'list[AgentHint | dict[str, Any]]'=<factory>)

Bases: object

status: str = 'succeeded'

summary: str = ''

task_id: str = ''

node_id: str = ''

listener_id: str = ''

route: MeshRoute | None = None

destination_host: str = ''

destination_port: int = 0

protocol: str = ''

outputs: dict[str, Any]

findings: list[Finding]

artifacts: list[Artifact]

sessions: list[SessionRef]

beacons: list[MeshBeacon]

events: list[MeshEvent]

agent_hints: list[AgentHint | dict[str, Any]]

classmethod succeeded(summary: str) → MeshTaskResult

to_rpc(*, sessions: list[SessionRef] | None = None) → dict[str, Any]

class hovel_sdk.MeshStreamRequest(run_id: 'str' = '', module_id: 'str' = '', target: 'str' = '', node_id: 'str' = '', listener_id: 'str' = '', route: 'MeshRoute | None' = None, destination_host: 'str' = '', destination_port: 'int' = 0, protocol: 'str' = '', config: 'dict[str, Any]'=<factory>, agent: 'AgentContext | None' = None)

Bases: object

run_id: str = ''

module_id: str = ''

target: str = ''

node_id: str = ''

listener_id: str = ''

route: MeshRoute | None = None

destination_host: str = ''

destination_port: int = 0

protocol: str = ''

config: dict[str, Any]

agent: AgentContext | None = None

classmethod from_rpc(value: dict[str, Any]) → MeshStreamRequest

class hovel_sdk.MeshEvent(kind: 'str', id: 'str' = '', node_id: 'str' = '', listener_id: 'str' = '', level: 'str' = '', message: 'str' = '', fields: 'dict[str, Any]'=<factory>)

Bases: object

kind: str

id: str = ''

node_id: str = ''

listener_id: str = ''

level: str = ''

message: str = ''

fields: dict[str, Any]

to_rpc() → dict[str, Any]

class hovel_sdk.MeshTrigger(id: 'str', name: 'str' = '', kind: 'str' = '', node_id: 'str' = '', listener_id: 'str' = '', state: 'str' = '', expression: 'str' = '', schedule: 'str' = '', action_kind: 'str' = '', config: 'dict[str, Any]'=<factory>, last_fired: 'str' = '')

Bases: object

id: str

name: str = ''

kind: str = ''

node_id: str = ''

listener_id: str = ''

state: str = ''

expression: str = ''

schedule: str = ''

action_kind: str = ''

config: dict[str, Any]

last_fired: str = ''

to_rpc() → dict[str, Any]

class hovel_sdk.MeshBridgeEndpoint(local_host: str, local_port: int, local_network: MeshBridgeNetwork, capability: MeshBridgeCapability)

Bases: object

Authenticated loopback endpoint returned by OpenMeshBridge.

capability is an ephemeral bearer secret. Keep it in memory and never log, persist, or cache it.

local_host: str

local_port: int

local_network: MeshBridgeNetwork

capability: MeshBridgeCapability

classmethod from_rpc(value: Mapping[str, Any]) → MeshBridgeEndpoint

Validate and wrap an OpenMeshBridge response.

class hovel_sdk.MeshBridgeNetwork(*values)

Bases: StrEnum

Daemon-owned local socket adapters supported by Mesh bridges.

TCP = 'tcp'

UDP = 'udp'

hovel_sdk.connect_mesh_bridge(endpoint: MeshBridgeEndpoint, *, timeout: float | None = None) → socket

Connect and authenticate, returning a normal TCP or UDP socket.

Hovel consumes the authentication preface before forwarding application bytes to the provider-owned Mesh stream. For UDP, every later send is one application datagram.

Credential Delivery Model

The discovery model describes strict credential slots and optional runtime, files, encoding, and stamping capabilities. HovelModule provides the describe_credential_delivery hook; Python has no separate CredentialDescriber protocol.

class hovel_sdk.CredentialDeliveryDescriptor(capabilities: 'list[CredentialDeliveryCapability]', slots: 'list[CredentialSlot]' = <factory>, stamp_target_kinds: 'list[CredentialStampTargetKind]' = <factory>, address_spaces: 'list[CredentialStampAddressSpace]' = <factory>, provider_target_schemas: 'list[CredentialProviderTargetSchema]' = <factory>, provider_encoding_schemas: 'list[CredentialProviderEncodingSchema]' = <factory>, schema_version: 'str' = 'hovel.pki.credential-delivery/v1')

Bases: object

capabilities: list[CredentialDeliveryCapability]

slots: list[CredentialSlot]

stamp_target_kinds: list[CredentialStampTargetKind]

address_spaces: list[CredentialStampAddressSpace]

provider_target_schemas: list[CredentialProviderTargetSchema]

provider_encoding_schemas: list[CredentialProviderEncodingSchema]

schema_version: str = 'hovel.pki.credential-delivery/v1'

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialDeliveryCapability(*values)

Bases: StrEnum

NONE = 'none'

RUNTIME = 'runtime'

FILES = 'files'

STAMP_STANDARD = 'stamp-standard'

STAMP_ADVANCED = 'stamp-advanced'

class hovel_sdk.CredentialSlot(name: 'str', purpose: 'CredentialPurpose', endpoint_role: 'CredentialEndpointRole', consumer_type: 'CredentialConsumerType', accepted_bundle_versions: 'list[str]', accepted_profiles: 'list[str]', accepted_compatibility_targets: 'list[str]', accepted_projections: 'list[CredentialProjection]', accepted_material_forms: 'list[CredentialMaterialForm]', maximum_encoded_bytes: 'int', remainder_policy: 'CredentialStampRemainderPolicy', private_material: 'CredentialPrivateMaterialPolicy')

Bases: object

name: str

purpose: CredentialPurpose

endpoint_role: CredentialEndpointRole

consumer_type: CredentialConsumerType

accepted_bundle_versions: list[str]

accepted_profiles: list[str]

accepted_compatibility_targets: list[str]

accepted_projections: list[CredentialProjection]

accepted_material_forms: list[CredentialMaterialForm]

maximum_encoded_bytes: int

remainder_policy: CredentialStampRemainderPolicy

private_material: CredentialPrivateMaterialPolicy

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialPurpose(*values)

Bases: StrEnum

TLS_SERVER = 'tls-server'

TLS_CLIENT = 'tls-client'

MTLS_SERVER = 'mtls-server'

MTLS_CLIENT = 'mtls-client'

DUAL_ROLE_MTLS = 'dual-role-mtls'

CODE_SIGNING = 'code-signing'

CUSTOM = 'custom'

class hovel_sdk.CredentialEndpointRole(*values)

Bases: StrEnum

SERVER = 'server'

CLIENT = 'client'

DUAL = 'dual'

NOT_APPLICABLE = 'not-applicable'

class hovel_sdk.CredentialConsumerType(*values)

Bases: StrEnum

MESH_PROVIDER = 'mesh-provider'

MESH_LISTENER = 'mesh-listener'

LISTENING_POST = 'listening-post'

MESH_NODE = 'mesh-node'

IMPLANT = 'implant'

STAGER = 'stager'

PAYLOAD = 'payload'

C2_SERVICE = 'c2-service'

SERVICE = 'service'

EXTERNAL = 'external'

class hovel_sdk.CredentialProjection(*values)

Bases: StrEnum

BUNDLE = 'bundle'

CERTIFICATE_DER = 'certificate-der'

PRIVATE_KEY_PKCS8 = 'private-key-pkcs8'

PUBLIC_KEY_SPKI = 'public-key-spki'

SIGNER_REFERENCE = 'signer-reference'

CHAIN_DER = 'chain-der'

TRUST_DER = 'trust-der'

CRL_DER = 'crl-der'

PROVIDER_ENCODING = 'provider-encoding'

LITERAL_REFERENCE = 'literal-reference'

class hovel_sdk.CredentialMaterialForm(*values)

Bases: StrEnum

PUBLIC = 'public'

PRIVATE_REFERENCE = 'private-reference'

PRIVATE_BYTES = 'private-bytes'

class hovel_sdk.CredentialPrivateMaterialPolicy(*values)

Bases: StrEnum

FORBIDDEN = 'forbidden'

ALLOWED = 'allowed'

REQUIRED = 'required'

class hovel_sdk.CredentialProviderTargetSchema(provider_id: 'str', schema_version: 'str', json_schema: 'dict[str, Any]')

Bases: object

provider_id: str

schema_version: str

json_schema: dict[str, Any]

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialProviderEncodingSchema(provider_id: 'str', schema_version: 'str', accepted_source_projections: 'list[CredentialProjection]', accepted_source_forms: 'list[CredentialMaterialForm]', output_forms: 'list[CredentialMaterialForm]')

Bases: object

provider_id: str

schema_version: str

accepted_source_projections: list[CredentialProjection]

accepted_source_forms: list[CredentialMaterialForm]

output_forms: list[CredentialMaterialForm]

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialStampTargetKind(*values)

Bases: StrEnum

NAMED_SLOT = 'named-slot'

FILE_OFFSET = 'file-offset'

VIRTUAL_ADDRESS = 'virtual-address'

SYMBOL = 'symbol'

MARKER = 'marker'

BYTE_PATTERN = 'byte-pattern'

PROVIDER_DEFINED = 'provider-defined'

class hovel_sdk.CredentialStampAddressSpace(*values)

Bases: StrEnum

FILE = 'file'

ELF_VIRTUAL_ADDRESS = 'elf-virtual-address'

PE_RVA = 'pe-rva'

MACHO_VM_ADDRESS = 'macho-vm-address'

class hovel_sdk.CredentialStampRemainderPolicy(*values)

Bases: StrEnum

PRESERVE = 'preserve'

ZERO_FILL = 'zero-fill'

REQUIRE_EXACT = 'require-exact'

class hovel_sdk.CredentialStampPreconditionKind(*values)

Bases: StrEnum

NONE = 'none'

BYTES = 'bytes'

SHA256 = 'sha256'

class hovel_sdk.CredentialStampPrecondition(kind: 'CredentialStampPreconditionKind', bytes_value: 'bytes' = b'', sha256: 'str' = '', length: 'str' = '')

Bases: object

kind: CredentialStampPreconditionKind

bytes_value: bytes = b''

sha256: str = ''

length: str = ''

validate() → None

Reject contradictory or out-of-bounds precondition variants.

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialNamedSlotTarget(name: 'str')

Bases: object

name: str

validate() → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialFileOffsetTarget(offset: 'str', maximum_length: 'str', alignment: 'str', remainder_policy: 'CredentialStampRemainderPolicy', precondition: 'CredentialStampPrecondition')

Bases: object

offset: str

maximum_length: str

alignment: str

remainder_policy: CredentialStampRemainderPolicy

precondition: CredentialStampPrecondition

validate() → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialVirtualAddressTarget(address: 'str', address_space: 'CredentialStampAddressSpace', maximum_length: 'str', alignment: 'str', remainder_policy: 'CredentialStampRemainderPolicy', precondition: 'CredentialStampPrecondition', image_base: 'str' = '')

Bases: object

address: str

address_space: CredentialStampAddressSpace

maximum_length: str

alignment: str

remainder_policy: CredentialStampRemainderPolicy

precondition: CredentialStampPrecondition

image_base: str = ''

validate() → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialSymbolTarget(name: 'str', maximum_length: 'str', remainder_policy: 'CredentialStampRemainderPolicy', precondition: 'CredentialStampPrecondition', section: 'str' = '')

Bases: object

name: str

maximum_length: str

remainder_policy: CredentialStampRemainderPolicy

precondition: CredentialStampPrecondition

section: str = ''

validate() → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialMarkerTarget(marker: 'bytes', occurrence: 'int' = 0, maximum_length: 'str' = '', remainder_policy: 'CredentialStampRemainderPolicy' = <CredentialStampRemainderPolicy.PRESERVE: 'preserve'>, precondition: 'CredentialStampPrecondition' = CredentialStampPrecondition(kind=<CredentialStampPreconditionKind.NONE: 'none'>, sha256='', length=''))

Bases: object

marker: bytes

occurrence: int = 0

maximum_length: str = ''

remainder_policy: CredentialStampRemainderPolicy = 'preserve'

precondition: CredentialStampPrecondition = CredentialStampPrecondition(kind=<CredentialStampPreconditionKind.NONE: 'none'>, sha256='', length='')

validate() → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialBytePatternTarget(pattern: 'bytes', mask: 'bytes', occurrence: 'int' = 0, maximum_length: 'str' = '', remainder_policy: 'CredentialStampRemainderPolicy' = <CredentialStampRemainderPolicy.PRESERVE: 'preserve'>, precondition: 'CredentialStampPrecondition' = CredentialStampPrecondition(kind=<CredentialStampPreconditionKind.NONE: 'none'>, sha256='', length=''))

Bases: object

pattern: bytes

mask: bytes

occurrence: int = 0

maximum_length: str = ''

remainder_policy: CredentialStampRemainderPolicy = 'preserve'

precondition: CredentialStampPrecondition = CredentialStampPrecondition(kind=<CredentialStampPreconditionKind.NONE: 'none'>, sha256='', length='')

validate() → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialProviderDefinedTarget(provider_id: 'str', schema_version: 'str', value: 'dict[str, Any]')

Bases: object

provider_id: str

schema_version: str

value: dict[str, Any]

validate() → None

to_rpc() → dict[str, Any]

hovel_sdk.CredentialStampTarget = CredentialStampTarget

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

class hovel_sdk.CredentialMaterialReference(projection: 'CredentialProjection', form: 'CredentialMaterialForm', bundle_id: 'str' = '', generation_id: 'str' = '', generation_ids: 'list[str]' = <factory>, trust_set_generation_id: 'str' = '', crl_generation_ids: 'list[str]' = <factory>)

Bases: object

projection: CredentialProjection

form: CredentialMaterialForm

bundle_id: str = ''

generation_id: str = ''

generation_ids: list[str]

trust_set_generation_id: str = ''

crl_generation_ids: list[str]

validate() → None

Reject contradictory reference variants and invalid projection forms.

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialReferencedStampMaterial(credential: 'CredentialMaterialReference')

Bases: object

credential: CredentialMaterialReference

validate() → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialProviderEncodingStampMaterial(provider_id: 'str', schema_version: 'str', form: 'CredentialMaterialForm', source: 'CredentialMaterialReference')

Bases: object

provider_id: str

schema_version: str

form: CredentialMaterialForm

source: CredentialMaterialReference

validate() → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialLiteralStampMaterial(reference: 'str', sha256: 'str', form: 'CredentialMaterialForm')

Bases: object

reference: str

sha256: str

form: CredentialMaterialForm

validate() → None

to_rpc() → dict[str, Any]

hovel_sdk.CredentialStampMaterial = CredentialStampMaterial

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

class hovel_sdk.ResolvedCredentialMetadata(bundle_version: 'str', purpose: 'CredentialPurpose', consumer_type: 'CredentialConsumerType', profile_id: 'str', compatibility_target_id: 'str')

Bases: object

bundle_version: str

purpose: CredentialPurpose

consumer_type: CredentialConsumerType

profile_id: str

compatibility_target_id: str

validate() → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialStampRequest(assignment_id: 'str', capability: 'CredentialDeliveryCapability', slot_name: 'str', target: 'CredentialStampTarget', material: 'CredentialStampMaterial', encoded_bytes: 'int', credential: 'ResolvedCredentialMetadata')

Bases: object

assignment_id: str

capability: CredentialDeliveryCapability

slot_name: str

target: CredentialStampTarget

material: CredentialStampMaterial

encoded_bytes: int

credential: ResolvedCredentialMetadata

validate() → None

Validate the complete typed stamp request before a protocol boundary.

to_rpc() → dict[str, Any]

Credential Provider Execution Model

These values cross the secret-bearing provider invocation boundary. Their representations are redacted, but explicit value access still reveals secrets. Do not log secret bytes, protected paths, or secret references, and do not put them in Hovel’s public execution ledger. A provider may copy material into its own protected runtime or installation only when the advertised capability and lifecycle require that retention; return only a non-secret receipt or digest.

class hovel_sdk.CredentialOperationScope(operation_id: 'str' = '', run_id: 'str' = '', chain_id: 'str' = '', throw_id: 'str' = '', target: 'str' = '', listener_id: 'str' = '', node_id: 'str' = '')

Bases: object

operation_id: str = ''

run_id: str = ''

chain_id: str = ''

throw_id: str = ''

target: str = ''

listener_id: str = ''

node_id: str = ''

validate() → None

classmethod from_rpc(value: dict[str, Any]) → CredentialOperationScope

class hovel_sdk.CredentialProviderTarget(module_id: 'str', provider_id: 'str', provider_version: 'str', descriptor_sha256: 'str')

Bases: object

module_id: str

provider_id: str

provider_version: str

descriptor_sha256: str

validate() → None

classmethod from_rpc(value: dict[str, Any]) → CredentialProviderTarget

class hovel_sdk.CredentialBytes(value: bytes)

Bases: object

property value: bytes

classmethod from_rpc(value: dict[str, Any], field_name: str) → CredentialBytes

to_rpc() → str

class hovel_sdk.CredentialProtectedPath(value: str)

Bases: object

property value: str

reveal() → str

Reveal the path for an explicit filesystem-boundary operation.

class hovel_sdk.CredentialSecretReference(value: str)

Bases: object

property value: str

class hovel_sdk.CredentialScopedReference(provider_id: 'str', reference: 'CredentialSecretReference', capabilities: 'list[str]' = <factory>)

Bases: object

provider_id: str

reference: CredentialSecretReference

capabilities: list[str]

validate() → None

classmethod from_rpc(value: dict[str, Any]) → CredentialScopedReference

class hovel_sdk.ResolvedCredentialMaterial(projection: 'CredentialProjection', form: 'CredentialMaterialForm', encoding: 'str', sha256: 'str', value: 'CredentialBytes | CredentialScopedReference')

Bases: object

projection: CredentialProjection

form: CredentialMaterialForm

encoding: str

sha256: str

value: CredentialBytes | CredentialScopedReference

validate() → None

classmethod from_rpc(value: dict[str, Any]) → ResolvedCredentialMaterial

class hovel_sdk.CredentialRuntimeRequest(request_id: 'str', provider: 'CredentialProviderTarget', assignment_id: 'str', slot_name: 'str', credential: 'ResolvedCredentialMetadata', material: 'ResolvedCredentialMaterial', scope: 'CredentialOperationScope', schema_version: 'str' = 'hovel.pki.provider-execution/v1')

Bases: object

request_id: str

provider: CredentialProviderTarget

assignment_id: str

slot_name: str

credential: ResolvedCredentialMetadata

material: ResolvedCredentialMaterial

scope: CredentialOperationScope

schema_version: str = 'hovel.pki.provider-execution/v1'

validate() → None

classmethod from_rpc(value: dict[str, Any]) → CredentialRuntimeRequest

class hovel_sdk.CredentialFile(projection: 'CredentialProjection', form: 'CredentialMaterialForm', encoding: 'str', media_type: 'str', path: 'CredentialProtectedPath', sha256: 'str' = '', size: 'int' = 0)

Bases: object

projection: CredentialProjection

form: CredentialMaterialForm

encoding: str

media_type: str

path: CredentialProtectedPath

sha256: str = ''

size: int = 0

validate() → None

classmethod from_rpc(value: dict[str, Any]) → CredentialFile

class hovel_sdk.CredentialFilesRequest(request_id: 'str', provider: 'CredentialProviderTarget', assignment_id: 'str', slot_name: 'str', credential: 'ResolvedCredentialMetadata', files: 'list[CredentialFile]', scope: 'CredentialOperationScope', schema_version: 'str' = 'hovel.pki.provider-execution/v1')

Bases: object

request_id: str

provider: CredentialProviderTarget

assignment_id: str

slot_name: str

credential: ResolvedCredentialMetadata

files: list[CredentialFile]

scope: CredentialOperationScope

schema_version: str = 'hovel.pki.provider-execution/v1'

validate() → None

classmethod from_rpc(value: dict[str, Any]) → CredentialFilesRequest

class hovel_sdk.CredentialDeliveryReceipt(request_id: 'str', provider_reference: 'str' = '', receipt_sha256: 'str' = '')

Bases: object

request_id: str

provider_reference: str = ''

receipt_sha256: str = ''

validate() → None

validate_for(request_id: str) → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialEncodingRequest(request_id: 'str', provider: 'CredentialProviderTarget', provider_id: 'str', provider_schema: 'str', output_form: 'CredentialMaterialForm', maximum_encoded_bytes: 'int', source: 'ResolvedCredentialMaterial', scope: 'CredentialOperationScope', schema_version: 'str' = 'hovel.pki.provider-execution/v1')

Bases: object

request_id: str

provider: CredentialProviderTarget

provider_id: str

provider_schema: str

output_form: CredentialMaterialForm

maximum_encoded_bytes: int

source: ResolvedCredentialMaterial

scope: CredentialOperationScope

schema_version: str = 'hovel.pki.provider-execution/v1'

validate() → None

classmethod from_rpc(value: dict[str, Any]) → CredentialEncodingRequest

class hovel_sdk.CredentialEncodingResult(request_id: 'str', form: 'CredentialMaterialForm', encoding: 'str', sha256: 'str', data: 'bytes')

Bases: object

request_id: str

form: CredentialMaterialForm

encoding: str

sha256: str

data: bytes

validate() → None

validate_for(request: CredentialEncodingRequest) → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialArtifactInput(artifact_id: 'str', sha256: 'str', encoding: 'str', content: 'CredentialBytes | CredentialProtectedPath')

Bases: object

artifact_id: str

sha256: str

encoding: str

content: CredentialBytes | CredentialProtectedPath

validate() → None

classmethod from_rpc(value: dict[str, Any]) → CredentialArtifactInput

class hovel_sdk.CredentialArtifactOutput(name: 'str', encoding: 'str', content: 'CredentialBytes | CredentialProtectedPath')

Bases: object

name: str

encoding: str

content: CredentialBytes | CredentialProtectedPath

validate() → None

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialDeploymentOutput(reference: 'str', receipt: 'bytes')

Bases: object

reference: str

receipt: bytes

validate() → None

to_rpc() → dict[str, Any]

hovel_sdk.CredentialStampOutput = CredentialStampOutput

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

class hovel_sdk.CredentialStampedMaterialDigest(projection: 'CredentialProjection', reference: 'str', sha256: 'str')

Bases: object

projection: CredentialProjection

reference: str

sha256: str

validate() → None

classmethod from_rpc(value: dict[str, Any]) → CredentialStampedMaterialDigest

to_rpc() → dict[str, Any]

class hovel_sdk.CredentialStampTargetResolution(*values)

Bases: StrEnum

UNCHANGED = 'unchanged'

TRANSLATED = 'translated'

class hovel_sdk.CredentialStampExecutionRequest(stamp_id: 'str', provider: 'CredentialProviderTarget', request: 'CredentialStampRequest', input: 'CredentialArtifactInput', material: 'ResolvedCredentialMaterial', expected_digests: 'list[CredentialStampedMaterialDigest]', scope: 'CredentialOperationScope', schema_version: 'str' = 'hovel.pki.provider-execution/v1')

Bases: object

stamp_id: str

provider: CredentialProviderTarget

request: CredentialStampRequest

input: CredentialArtifactInput

material: ResolvedCredentialMaterial

expected_digests: list[CredentialStampedMaterialDigest]

scope: CredentialOperationScope

schema_version: str = 'hovel.pki.provider-execution/v1'

validate() → None

classmethod from_rpc(value: dict[str, Any]) → CredentialStampExecutionRequest

class hovel_sdk.CredentialStampExecutionResult(stamp_id: 'str', output: 'CredentialStampOutput', target_resolution: 'CredentialStampTargetResolution', resolved_target: 'CredentialStampTarget', bytes_written: 'str', material_digests: 'list[CredentialStampedMaterialDigest]')

Bases: object

stamp_id: str

output: CredentialStampOutput

target_resolution: CredentialStampTargetResolution

resolved_target: CredentialStampTarget

bytes_written: str

material_digests: list[CredentialStampedMaterialDigest]

validate() → None

validate_for(request: CredentialStampExecutionRequest) → None

to_rpc() → dict[str, Any]

Testing

class hovel_sdk.ModuleRPC(module: HovelModule)

Bases: object

Drive a module through the real Content-Length framed JSON-RPC server.

call(method: str, params: dict[str, Any] | None = None) → dict[str, Any]

close() → None

class hovel_sdk.RPCError

Bases: RuntimeError

Raised when a test RPC call returns a JSON-RPC error response.

hovel_sdk.drive_module(module: HovelModule, script: Callable[[ModuleRPC], None]) → list[dict[str, Any]]

Run a concise RPC script and return notifications emitted during it.

Logging

hovel_sdk.setup_logging(emit: Callable[[dict[str, Any]], None] | None = None) → RPCLogHandler