PKI

Wendy uses mutual TLS (mTLS) to authenticate both devices and CLI clients against the agent's gRPC server. Certificates are issued by a CA managed by either Wendy Cloud or a self-hosted pki-core instance.

Certificate roles

The device's mTLS CA pool is built from the chainPem field in provisioning.json. CLI clients must present a certificate whose chain terminates at that same CA. If chainPem is absent or empty, the agent refuses to build a TLS configuration and returns an error indicating that the device may need to be re-provisioned.

CA key rollover

The trust bundle may contain multiple CA certificates sharing the same subject DN. This is normal during a CA key rollover, where an old CA and a new CA temporarily coexist in the bundle. The agent's ML-DSA client certificate verifier (verifyMLDSAClientCert) tries every CA whose subject DN matches the client certificate's issuer DN. Verification succeeds as soon as any matching CA validates the certificate. If all matching CAs fail, the error from the last attempted CA is returned. If no CA in the pool has a matching subject DN, the verifier returns a "client certificate issuer not found in trusted CA pool" error.

Local development with pki-core

pki-core is the self-hosted Wendy PKI engine. Run it locally to provision real devices without a cloud deployment.

Prerequisites

1. Start the engine and admin API:

   pkicore serve all --dev

2. Create a CA and configure the Wendy frontend (frontend.wendy.device_ca_id in config.yaml).

3. Start the Wendy gRPC frontend:

   pkicore serve wendy --config config.yaml

   This exposes wendycloud.v1.CertificateService on the configured listen address (default :50051).

Provision a device

Find your machine's LAN IP (the address the device can reach):

ifconfig | grep "inet " | grep -v 127.0.0.1

Then provision the target device:

wendy device provision \
  --cloud <your-lan-ip>:50051 \
  --api-key <key-from-config.yaml> \
  --name my-device

Authenticate the CLI

Issue a client certificate from the same pki-core so the CLI can connect over mTLS:

wendy auth login-local \
  --cloud <your-lan-ip>:50051 \
  --api-key <key-from-config.yaml>

After this, wendy device version, wendy run, and other device commands automatically use the mTLS port (plaintext port + 1) when the device's Avahi advertisement includes tls=true.

Avahi advertisement

After provisioning, wendy-agent updates /etc/avahi/services/wendyos-mdns.service to set the _wendyos._udp service block's port to the mTLS port and adds a tls=true TXT record. The CLI reads this record during device discovery to select the mTLS connection path.