Skip to main content

Prepare your fleet for the 0.8.0 zero-trust default

At 0.8.0, rpc.auth.enabled flips to true by default whenever rpc-peers.yaml is present. Fleets with a peer that lacks an auth: block will fail boot with AUTH_REJECTED. The full migration plan is at docs/ZERO_TRUST_DEFAULT_MIGRATION.md — this recipe is the operational walkthrough.

Recommendation: run --strict in CI for 2–3 weeks before taking 0.8.0.

The pre-flight inspector​

declaragent fleet audit-rpc               # report only
declaragent fleet audit-rpc --suggest-enable   # report + copy-pasteable YAML diffs
declaragent fleet audit-rpc --strict           # exit 1 on any gap — wire into CI
declaragent fleet audit-rpc --json             # machine-readable, pipe to jq

Shipped at 0.7.3 (packages/cli/src/fleet-audit-rpc-cli.ts). Safe to run in any environment — no network IO, no state mutation.

Step 1 — Baseline audit​

From the fleet root:

declaragent fleet audit-rpc --json | jq '.agents[]'

The JSON envelope is { ok, allEnabled, agents: [...] }; each agent entry carries agentId, agentYamlPath, a state, and (when relevant) reason, peerAuthProvider, and a suggestion snippet. The state values:

  • enabled — rpc.auth.enabled: true today, no action needed.
  • disabled — explicitly false; will need a decision before 0.8.0.
  • absent — no rpc.auth block; this agent flips behavior at 0.8.0.
  • unreadable — agent.yaml couldn't be parsed; fix the file first.

Step 2 — Apply the suggested diff​

declaragent fleet audit-rpc --suggest-enable

The inspector emits one agent.yaml snippet per gap (the enable flag is per-agent; the peer's declared provider is echoed as a comment):

# agents/concierge/agent.yaml — suggested by --suggest-enable
rpc:
  auth:
    enabled: true    # peer "pr-reviewer" declares provider: hmac

Paste the rpc.auth.enabled block into each flagged agent.yaml. The how of authentication — the per-peer auth: block — lives in rpc-peers.yaml and is hand-authored. The supported providers:

ProviderWhen to useKey fields
hmacShared secret between trusted peerskeyId, secretRef (secret://…)
oidcPeers mediated by your IdP (bearer JWT)issuer, audience, optional jwksUri, scopes
oauth2-clientService-to-service client-credentials tokenstokenEndpoint, clientId, clientSecretRef, scopes

Step 3 — Validate​

declaragent fleet validate
declaragent fleet audit-rpc --strict        # must exit 0

Step 4 — Wire --strict into CI​

Add to .github/workflows/ci.yml (or your equivalent):

- name: Zero-trust RPC audit (will be required at 0.8.0)
  run: |
    bunx @declaragent/cli fleet audit-rpc --strict

Run this for at least 2–3 weeks before upgrading to 0.8.0. It catches PRs that add a peer without auth before they land.

Step 5 — Flip the default locally (dry-run)​

Before 0.8.0 ships, you can opt-in early — per agent, in each agent.yaml (fleet.yaml has no rpc.auth key; adding one fails schema validation):

# agents/<id>/agent.yaml
rpc:
  auth:
    enabled: true                  # opt-in to the 0.8.0 default today

Re-run your soak tests. If a peer still boots with AUTH_REJECTED, the inspector missed something — please open an issue with the --json output.

Step 6 — Upgrade to 0.8.0​

Once CI has been green on --strict for 2+ weeks:

bun add -D @declaragent/cli@^0.8
declaragent fleet validate
declaragent fleet run          # or `declaragent up -d` per agent host

Fleets that skipped the pre-flight will fail boot with AUTH_REJECTED naming the peer that lacks an auth: block. Remediation: run declaragent fleet audit-rpc --suggest-enable, paste the rpc.auth.enabled snippet into the flagged agent.yaml, and author the peer's auth: block in rpc-peers.yaml (Step 2).

Rollback​

If you need to delay the flip (e.g. mid-incident), opt back out temporarily — again per agent, in agent.yaml:

# agents/<id>/agent.yaml
rpc:
  auth:
    enabled: false                 # temporary — re-enable before end of sprint

This is a compatibility knob, not a supported long-term mode. Set a reminder; rpc.auth.enabled: false will be removed in a future minor.