Daemon RPC Contract

The RPC boundary between hoveld and Hovel front ends is a stable v1 contract. It is used by interactive cli, one-shot chain-file execution, hovel mcp, daemon management code, and future TUI or REST adapters that need the same daemon-owned workspace state.

This contract is separate from the module wire protocol. Module processes speak JSON-RPC over stdio; front ends speak the daemon RPC over the local daemon listener.

Machine-Readable Contract

The source-backed interface description is reference/daemon-rpc.openapi.json. It uses the OpenAPI Specification because the daemon RPC is HTTP with JSON request and response bodies, and OpenAPI gives Hovel a standard artifact that can feed client generation, schema inspection, and contract checks.

The OpenAPI document declares openapi: 3.1.0, x-hovel-stability: stable, and x-hovel-service: hovel.daemon.v1.DaemonService. The paths in that file are checked against core/internal/adapters/daemonrpc/daemonrpc.go so method additions cannot drift away from the documented contract silently.

Stability Policy

1. The service prefix /hovel.daemon.v1.DaemonService/ is the version boundary. Breaking request or response changes require a new versioned prefix or an explicit compatibility path.
2. Method names and JSON field names are stable within v1. Some older daemon structs intentionally expose PascalCase JSON keys such as Operation and SessionID; newer entity and payload shapes use lower-camel keys such as operation and moduleId.
3. Additive response fields are allowed. Clients must ignore fields they do not understand.
4. Required field removals, type changes, enum meaning changes, and path moves are breaking changes.
5. Typed application failures use the versioned RPCError JSON envelope. Its code and optional rolloverReason are stable within v1; message remains diagnostic. Invalid transport requests and unclassified internal failures remain plain text and must not be parsed.

Transport

The daemon RPC is HTTP POST with JSON bodies over the daemon endpoint. Local managed mode prefers a Unix domain socket named hoveld.sock under the workspace. Explicit daemon serving can also bind TCP, normally to a loopback address such as tcp://127.0.0.1:9090.

Endpoint forms accepted by the client are:

/path/to/workspace/hoveld.sock
unix:/path/to/workspace/hoveld.sock
unix:///path/to/workspace/hoveld.sock
tcp://127.0.0.1:9090
http://127.0.0.1:9090
127.0.0.1:9090

https:// endpoints are rejected. The owner-controlled Unix socket is the privileged control plane. Loopback TCP exists for development and integration, but loopback is not caller authentication: it exposes only explicitly non-sensitive read projections and returns typed 403 permission-denied for every privileged route. Sensitive Mesh topology, beacon, listener, and operation bookkeeping reads and PKI inventory or assignment reads are privileged even though they do not mutate state. An external web, Elixir, or remote control plane must connect through an authenticated owner-side proxy rather than treating the TCP listener as a public API. A future Windows implementation should provide the equivalent boundary with an owner-controlled named pipe.

HTTP Shape

Every method is a unary POST at /hovel.daemon.v1.DaemonService/{Method}. Requests and successful responses use application/json. Empty request and response types are the empty JSON object {}. Session bytes are encoded as base64 strings by Go JSON because the fields are []byte.

POST /hovel.daemon.v1.DaemonService/Snapshot
Content-Type: application/json

{"Operation":"redteam-lab","Chain":"mock-exploit"}

Every route reads its JSON body through the same inclusive 64 MiB (67,108,864-byte) limit. The daemon enforces the cap while decoding; it does not reject a request from Content-Length alone. If decoding attempts to read beyond the limit, the handler returns plain-text 413. Malformed JSON, an unknown field, or trailing input rejected before the decoder crosses the cap can still return plain-text 400. A non-POST request returns 405 with text.

Responses with status 200 are JSON. Privileged routes called over read-only TCP return typed 403 permission-denied; a private-key export policy denial returns typed 403 private-key-export-denied. Typed not-found failures return 404; a locked authority signer returns 423; revision, idempotency, in-progress, duplicate-acknowledgement, and rollover-precondition failures return 409. Those typed responses use application/json with stable version, code, and message fields, plus a required rolloverReason and optional exact rolloverDetail for rollover preconditions. Size, syntax, method, and unclassified handler failures are plain text; unclassified failures return 500. The Go client reconstructs every published PKI sentinel and rollover-precondition error so callers can use errors.Is and errors.As rather than parsing messages.

The contract is unary. Logs and session output are polled through PollLogs, ActiveLogs, ReadSession, and TailSession rather than streamed over a long-lived HTTP response.

Daemon-Owned State

hoveld owns operation, chain, target, config, log, session, launch-key, payload, Mesh bookkeeping, and live entity state for a workspace. Front ends may keep local active selections for ergonomics, but authoritative mutation goes through daemon methods. The default operation name is default when callers omit an operation where the server accepts that fallback.

Mesh listener lifecycle, task, stream, and bridge calls are recorded in daemon memory with the relevant listener, route, node, destination, session, state, and timestamps. Listener lifecycle records carry the start or stop action and provider-reported state. Bridge records additionally carry the daemon-owned local address; raw task and stream requests cannot supply that audit field. Privileged front ends can inspect the audit surface with ListMeshOperations over the owner Unix transport instead of guessing which listening post, local bridge, or session belongs to a routed Mesh operation.

Listening-post configuration is write-only. StartMeshListener accepts provider-specific config, but Hovel does not copy it into listener responses or Mesh operation records. Providers must also avoid including configuration or credentials in their own errors and logs. Callers select the stable listenerId, which makes lifecycle retries idempotent. Listener IDs are scoped to a provider Mesh, so external clients use moduleId plus listenerId as the durable daemon-wide correlation key.

Active Mesh mutations can carry an optional credentials array of non-secret assignment, slot, projection, and form selectors. When present, credentialContext is also required and must set approveCredentialUse to true. The daemon derives the permitted provider, listener, and node consumers; validates the active assignment and current provider descriptor; and delivers material only to the same process that performs the Mesh call. Keep the selector requestId, credential-context operationId, and operation inputs stable for retries. The current external selector path supports direct runtime certificate DER, public-key SPKI, and private-key PKCS #8 projections; it never returns resolved bytes. See the worked provider and front-end example.

Workspace PKI follows the same rule. The daemon owns custody, certificate inventory, signing leases, and audit identity; front ends call the typed PKI methods instead of opening the SQLite database or master-key files. Mutating requests carry an explicit context with actor, operation, and correlation identifiers. Signing unlock and private-key export require separate approval booleans, so possession of the local API alone does not imply approval for a secret-bearing operation.

Assignments are stable consumer slots for Mesh providers, listeners, listening posts, nodes, implants, stagers, payloads, C2 services, ordinary services, and external integrations. A client binds a pending assignment, stages an immutable certificate generation, performs any required delivery outside the current lifecycle API, and then activates it. The previous active generation remains authoritative until activation. Every stage, activate, and unbind request carries expectedRevision; a stale revision fails instead of silently replacing another operator's rollout.

Trust sets use the same staged model. A logical trust-set id points to immutable generations containing ordered anchors, intermediates, and optional signed CRL generations. Old and new roots can overlap during CA rollover. CRLs must be fresh when a trust generation is staged or resolved, and each CRL issuer must be present in that trust generation. Assignments pin the exact trust generation staged with their certificate, so activating a newer logical trust generation changes the default for later assignment stages without silently changing existing consumers. InspectPKIAssignment resolves the pinned credential and trust pointers for a web, Elixir, CLI, or other front end without returning private-key material.

Every synchronous assignment and trust mutation accepts idempotencyKey. Explicit keys are scoped to the authenticated actor and operation kind, so two principals cannot claim each other's retries. When a key is omitted, the application derives one from the actor, operation, correlation, and canonical request digest; callers must preserve the correlation identifier when retrying the same API call. The daemon stores the public result in the same transaction as the state change and audit event. Repeating the same scoped key and request returns that recorded result; reusing the key for a different request fails.

Certificate lifecycle uses the same durable issuance journal. RenewPKICertificate creates the next immutable generation while reusing and independently revalidating the source key; it does not duplicate the encrypted key envelope. RotatePKICertificate creates the next generation with a distinct key and may select another installed backend. Both preserve the certificate lineage and current active assignments. Operators stage the returned generation on each intended assignment and activate it only after delivery succeeds, so a failed renewal or rotation cannot silently replace a served credential.

RevokePKICertificate is a synchronous, idempotent safety transition for a non-root certificate generation. In one transaction the daemon records an immutable RFC 5280 reason, marks the generation revoked, degrades assignments actively serving it, clears it from staged-only assignments, writes the audit event, and stores the exact retry result. A self-signed root is removed through a later distrust or trust-rollover workflow rather than revoked by its own key. Use InspectPKIRevocation for a known revocation id, InspectPKIGenerationRevocation when starting from a generation id, and ListPKIRevocations to build an authority-scoped operator view.

POST /hovel.daemon.v1.DaemonService/RevokePKICertificate
Content-Type: application/json

{
  "context": {
    "actorId": "operator-7",
    "operationId": "credential-response",
    "correlationId": "incident-2026-0712"
  },
  "request": {
    "idempotencyKey": "incident-2026-0712:revoke-listener",
    "generationId": "certgen-listener-42",
    "reason": "key-compromise"
  }
}

Omit effectiveAt to use daemon time. If supplied, it must be an RFC 3339 timestamp no later than the recording time and no earlier than the certificate validity window. The success body contains the typed revocation, the resulting revoked generation, and every changed assignment in stable id order; callers do not need to reconstruct assignment impact from logs.

Publishing and consuming CRLs

PublishPKICRL creates a durable publication plan before it invokes a signing provider. The plan commits the authority, exact issuer generation, monotonically reserved CRL number, effective revocation IDs, validity window, concrete signature algorithm, and backend capability identity. Its typed phase advances from planned to signing and then signed. The daemon renews the ownership lease during provider and validation calls. Immediately after provider success it atomically records a public signed checkpoint containing the DER, SHA-256 fingerprint, concrete algorithm, optional provider operation reference, and confirmed key-use audit. The independent validator never receives signing key material. It parses and verifies a separate DER copy, checks the strict extension set, and atomically stores the immutable generation with the publication audit. A retry with the same idempotency key returns the stored generation; a concurrent retry receives an in-progress error instead of invoking the signer twice.

POST /hovel.daemon.v1.DaemonService/PublishPKICRL
Content-Type: application/json

{
  "context": {
    "actorId": "operator-7",
    "operationId": "credential-response",
    "correlationId": "incident-2026-0712"
  },
  "request": {
    "idempotencyKey": "incident-2026-0712:publish-crl",
    "authorityId": "authority-edge-root",
    "validitySeconds": 43200,
    "signatureAlgorithm": "ecdsa-sha256"
  }
}

Omit signatureAlgorithm to select a deterministic concrete algorithm from the issuer key. Omit validitySeconds for 24 hours; non-zero values must be between five minutes and seven days. The success body contains both publication bookkeeping and generation, including base64 DER, SHA-256 fingerprint, issuer generation, signature algorithm, CRL number, and exact revocation IDs.

Use InspectPKICRL for one immutable generation and ListPKICRLs for an authority-ordered generation inventory. Use InspectPKICRLPublication or ListPKICRLPublications for daemon bookkeeping, including pending, completed, and failed plans with their typed phase, owner revision, lease, and signed checkpoint when present. External web, Elixir, or other clients should retain stable publication and generation IDs rather than treating a mutable file path as identity. Trust-set generations reference CRL generation IDs and re-check freshness whenever they are resolved.

A daemon crash can leave a publication plan pending. Hovel deliberately does not repeat an ambiguous signing call. An authorized operator uses ReconcilePKICRL, or bounded ReconcilePKICRLs for a batch, after the ownership lease and requested stale age have elapsed. Reconciliation atomically claims the stale plan. A signed plan is independently revalidated from its durable checkpoint and completed without invoking the signer; a planned or ambiguous signing plan is failed with an audit. The request context must set approveCrlPublicationReconciliation; normal API access does not grant this authority.

POST /hovel.daemon.v1.DaemonService/ReconcilePKICRL
Content-Type: application/json

{
  "context": {
    "actorId": "operator-7",
    "operationId": "pki-recovery",
    "correlationId": "reconcile-2026-0712",
    "approveCrlPublicationReconciliation": true
  },
  "request": {
    "publicationId": "crl-publication-018f6e2f",
    "staleAfterSeconds": 300
  }
}

Rolling an authority without a trust gap

An authority rollover is a durable operation rather than a sequence a front end reconstructs locally. The operation pins previousAuthorityGenerationId and replacementAuthorityGenerationId, so changing either authority's active key invalidates the operation instead of silently changing its meaning. Root authorities must place both generations in the overlap generation's anchor list. Subordinate authorities must place both generations in the intermediate list and retain the ancestor chain needed to reach an anchor. Final trust retains only the replacement generation in the role-appropriate collection.

Choose consumer tracking when starting the operation:

• all-tracked atomically snapshots every eligible active or degraded peer-trust assignment bound to the trust set.
• explicit requires a non-empty, duplicate-free requiredAssignmentIds list of eligible peer-trust assignments.
• none is for a trust set with no Hovel-tracked consumers and does not accept assignment acknowledgements.

A live rollover durably reserves its trust set and required assignments. Ordinary trust activation, assignment binding or removal, and unrelated assignment changes fail with the typed resource-reserved reason. The narrow exceptions are deliberate: while the operation is awaiting leaf rotation, a required assignment may stage and activate only a leaf issued by the recorded replacement authority generation with overlap trust, and the trust set may stage only material that already satisfies the final rollover layout. The dedicated rollover methods remain the only way to activate overlap or final trust.

The lifecycle is deliberately explicit:

1. Stage an overlap trust generation, then call StartPKIAuthorityRollover.
2. Each required consumer calls AcknowledgePKIAuthorityRollover for the overlap generation. Use InspectPKIOperation to read durable acknowledgements and missingAssignmentIds.
3. Call ActivatePKIAuthorityRollover with both expectedRevision and expectedTrustSetRevision. The previous authority begins retiring and overlap trust becomes active atomically.
4. Issue replacement-authority leaves, stage and activate them on every required assignment, and stage final trust.
5. Call BeginPKIAuthorityRolloverFinalTrust with the staged final generation and both revision fences. Consumers then acknowledge that final trust generation.
6. Call CompletePKIAuthorityRollover with fresh revisions. The final trust generation activates and the previous authority retires atomically.

ListPKIOperations is the bookkeeping surface for CLI, web, Elixir, and other front ends. Every mutation carries the normal authenticated PKI request context and accepts an idempotencyKey. A retry with the same scoped key and request returns the recorded inspection; a stale operation or trust-set revision is rejected instead of applying to a newer state.

Credential delivery has two separate, secret-free bookkeeping views. ListPKICredentialStamps and InspectPKICredentialStamp expose immutable stamp plans and verified terminal evidence for build-time or deployment-time mutation. ListPKICredentialExecutions and InspectPKICredentialExecution expose runtime delivery, protected-file delivery, and provider-encoding invocations. Execution records contain exact provider, assignment, slot, scope, material digest, size, encoding, schema, and output-bound metadata, but never credential bytes, protected paths, scoped secret references, encoded output bytes, or raw provider-owned references. Provider references are represented only by SHA-256 digests.

The daemon writes a pending credential execution before invoking the provider and then records a succeeded or failed terminal transition. Provider errors are returned to the caller but are not copied into durable state; the persisted failure reason is a bounded, stable category so module stderr or secret-bearing diagnostics cannot become ledger data. Terminal bookkeeping survives caller cancellation under a short independent timeout, preventing timed-out provider calls from remaining pending indefinitely.

CancelPKIAuthorityRollover is the audited recovery path before overlap activation. It is revision-fenced and releases the operation's reservations while the previous authority and active trust remain unchanged. Once overlap activation starts retirement and changes active trust, cancellation is rejected; finish the fenced workflow rather than leaving a partially applied rollover.

POST /hovel.daemon.v1.DaemonService/StartPKIAuthorityRollover
Content-Type: application/json

{
  "context": {
    "actorId": "operator-7",
    "operationId": "edge-ca-rollover",
    "correlationId": "edge-ca-rollover-2026-07"
  },
  "request": {
    "idempotencyKey": "edge-ca-rollover:start",
    "previousAuthorityId": "authority-edge-root-v1",
    "replacementAuthorityId": "authority-edge-root-v2",
    "trustSetId": "trust-edge",
    "overlapTrustGenerationId": "trustgen-edge-overlap",
    "consumerTracking": "all-tracked"
  }
}

ExportPKIBundle is the only current daemon response that can contain private key bytes. The daemon refuses private export on non-confidential transports, requires approvePrivateKeyExport, audits the attempt, and marks both successful and rejected responses Cache-Control: no-store. Inventory and inspect methods never return private-key material.

CLI, one-shot execution, MCP, and future front ends must not create parallel persistence or confirmation paths. A throw still needs a persisted plan and a recorded confirmation before execution, and dangerous modules still require the explicit dangerous-module allowance.

This rule is fail-closed at the current direct Mesh task boundary. RunMeshTask accepts survey; command, upload, execute, upload_execute, load, stream-setup, and provider-defined task kinds return typed permission-denied before the provider hook runs. Those contracts remain available to Mesh provider SDKs so a future persisted-plan orchestrator can dispatch them without redesigning the provider API. Until that binding exists, clients must not attempt to recreate it with an in-memory approval flag or a second execution endpoint.

Front-End Use

Method Surface

Compatibility Checks

The docs test suite verifies that every method registered by the unary, privileged-unary, or privileged-no-store helpers in daemonrpc.go has an OpenAPI path, a JSON request body, a JSON success response, the shared 413 response, a 403 response exactly when the route is privileged, and a mention in this page. That test is a drift guard; it does not replace behavior tests for authorization, launch-key semantics, persistence, session I/O, PKI custody, or module execution.

When adding or changing daemon RPC, update the Go server and client together, edit the single canonical docs/site/spec/reference/daemon-rpc.openapi.json source, update this page, and add behavior tests at the adapter or command layer that prove the intended front-end workflow still crosses the daemon boundary. Bazel publishes that source at the stable site URL; do not edit a second copy under public/.