SPEC-RPC.md

spec: SPEC-RPC version: 1 status: stable-normative audience: integrators implementing an mkit external signer or mkit-server

SPEC-RPC — mkit cross-system wire protocol v1

mkit speaks to processes outside its address space — external signers running as subprocesses, and remote mkit-server instances reached over ssh(1) — using a single shared wire protocol.

The schemas live in rust/crates/mkit-rpc/proto/:

ssh.proto imports the CAS enum (RefExpectation) and the ref-listing type (RefEntry) from mkit/common/v1/refs.proto at the repo root — a vocabulary shared with mkit.repo.v1 (the apps/repo-worker multiplayer demo protocol), so the two wire protocols cannot desync on CAS semantics. See that file's header comment for its own versioning contract.

Protocol-version integer is 1 (PROTOCOL_VERSION_1) — the only value mkit currently speaks. Wire-breaking changes (renumbering or removing a field) are made by introducing a sibling signer2.proto / ssh2.proto package and bumping to a new ProtocolVersion value, never by silently reinterpreting PROTOCOL_VERSION_1's existing wire shape (see §2).

Distribution. These schemas are published as the buf.build/officialunofficial/mkit-rpc module on the Buf Schema Registry on every tagged release (the named module at rust/crates/mkit-rpc/proto in the repo-root buf.yaml workspace, pushed by the buf-push job in .github/workflows/crates-publish.yml; see docs/RELEASE.md). Integrators generate typed bindings in their own language with buf generate against a pinned module ref instead of vendoring this repo — the checked-in rust/crates/mkit-rpc/proto/buf.gen.yaml is the reference codegen recipe (Swift today; add other languages the same way).

1. Wire framing

Both protocols use the same length-prefixed framing:

+------------------+------------------------------------+
| u32 LE length    | N bytes protobuf-encoded Frame     |
+------------------+------------------------------------+

• Length prefix: 4 bytes, little-endian unsigned integer, encoded length of the protobuf body in bytes — does NOT include the prefix itself.
• Body: a single protobuf-encoded SignerFrame (signer protocol) or SshFrame (SSH protocol), per the oneof body { ... } definitions in the .proto files. The Rust reference implementations use the buffa runtime, but any protobuf 3/edition 2023 toolchain emitting the same wire bytes is conformant.
• Cap: MAX_FRAME_BYTES = 1 MiB (1024 * 1024, exported from mkit-rpc as a constant of the same name). Receivers MUST close the connection on a frame whose advertised length exceeds the cap, before reading the body. Senders MUST refuse to emit a frame whose body would exceed the cap. Bulk data flows that need more than 1 MiB use a streaming pattern (see PackChunk in ssh.proto).

Receivers MUST validate the length prefix against the cap before allocating buffers — there is no streaming decode of a single frame.

A truncated length prefix or body is a connection-fatal protocol error. There is no recovery; the receiving side MUST close the underlying stream.

2. Versioning

The single ProtocolVersion enum in common.proto carries the wire contract version. Every initiating frame (SignerFrame::Hello, SshFrame::Hello) MUST set protocol = PROTOCOL_VERSION_1.

Wire-compatible additions to the v1 schemas are allowed in v0.1.x patch releases:

• New enum values for Algorithm, KeyForm, ErrorCode (existing consumers see them as unknown variants and fall back to ERROR_CODE_UNSPECIFIED/a no-op).
• New optional fields on existing messages (Edition 2023 default semantics).
• New oneof variants on SignerFrame::body and SshFrame::body (existing consumers reject them with ERROR_CODE_INVALID_REQUEST).

Renumbering or removing a field is a wire break. Do that by introducing a sibling *2.proto with a new package and bumping ProtocolVersion.

3. Common types

3.1 Algorithm

Wire-load-bearing integers; do NOT renumber. New algorithms append at the next available number.

3.2 KeyForm

3.3 ErrorCode

Error.message is human-readable English, suitable for direct UI display. Producers SHOULD keep it under 1 KiB so receivers can render it inline; the framing layer does NOT enforce a per-field cap, only the MAX_FRAME_BYTES = 1 MiB whole-frame ceiling from §1. Error.details is opaque vendor-specific bytes (CTAP CBOR status, TPM TPM_RC, PKCS#11 CKR_*, etc.); programs MUST NOT pattern-match on its contents.

4. Conformance

A signer or server is mkit-rpc-compliant if and only if:

1. It speaks length-prefixed protobuf frames as in §1.
2. The first frame it sends or expects is Hello with protocol = PROTOCOL_VERSION_1.
3. It returns a HelloResponse with the same protocol value before processing any other request.
4. Every error response is an Error frame with a known non-zero ErrorCode and a non-empty message.
5. It enforces MAX_FRAME_BYTES on receive AND on send.

Reference implementations (all in this repository):

• contrib/signers/mkit-sign-file/ — KEY_FORM_RAW_BYTES, Ed25519/secp256k1/P-256.
• contrib/signers/mkit-sign-ctap/ — FIDO2/WebAuthn signer, P-256/Ed25519-WebAuthn.
• contrib/signers/mkit-sign-tpm/ — TPM 2.0 P-256 signer.
• rust/crates/mkit-cli/src/commands/serve/mod.rs — mkit serve SSH server (consumes ssh.proto).

The Swift contrib/signers/mkit-sign-se/ (Apple Secure Enclave) binary is a conforming v1 reference signer: it speaks the length-prefixed protobuf wire (its Package.swift depends on swift-protobuf, with generated common.pb.swift/signer.pb.swift), and is listed alongside the other reference signers in SPEC-EXTERNAL-SIGNER §8. It wires through the external signer selector like any other mkit-rpc signer.

5. Why protobuf, not JSON

mkit-rpc replaces an earlier line-JSON external-signer protocol and a hand-rolled OP_HELLO byte format on the SSH transport. The protobuf choice is deliberate:

• Forward-compatible by default. Edition 2023 fields are explicit-presence; adding optional fields or oneof variants is a wire-compatible patch-level change.
• Cross-language. mkit ships in Rust, but external signers may ship in any language with a protobuf 3/edition 2023 implementation. JSON parsing edge cases (number precision, escape handling, key ordering) are not in the contract.
• Bounded sizes by construction. Length-prefixed framing with a hard cap is simpler to reason about than JSON-line streams that may need arbitrary lookahead for } matching.
• Schema-as-source-of-truth. The .proto files are the contract; prose specs (this file, SPEC-EXTERNAL-SIGNER, SPEC-TRANSPORT) are derivative.

The Rust reference implementations currently generate their protobuf bindings with the buffa runtime — this is a reference-implementation detail, not a specification requirement, and this document does not pin a version (a version pinned in prose drifts silently from whatever the workspace actually builds against). Other languages, and other Rust implementations, can use any protobuf 3/edition 2023 toolchain that emits the wire bytes defined by the .proto files listed at the top of this document (§1); conformance is defined by those bytes, never by which codegen tool produced them.

6. Invariants

The conformance checklist in §4 is the normative test of these properties; the .proto files remain the source of truth (§5).