[Benoît Cortier (CBenoit)]

Tightens how the Devolutions Agent handles what an Agent Identity authority sends it, how often it renews, and the state it keeps on disk, and records each rule in the intent files and the contract.

• Channel closures are classified by the exact pair of gRPC status and error-code the contract defines; any other pair is a transient outage, and only UNAUTHENTICATED with clock_skew carries a clock offset.
• A clock_skew retry, for signed HTTP requests and for channel openings, applies the authority's time only when it is within one day of the agent's clock, so that a signed request is never dated far from the agent's own time.
• Authority text in logs (a closing status message, the reason of RenewRequested and Reconnect) is escaped and cut to 256 characters, and an error-code that isn't a valid code is logged as invalid without its text.
• Base URLs, the token's u and agent_channel_url, refuse white space, control characters and non-ASCII, so that each URL means exactly its text; a malformed agent_channel_url is treated as absent.
• A renewal starts no sooner than ten minutes after the previous confirmed renewal of the run, however it is triggered, so that an authority cannot keep the agent renewing in a tight loop. A pending-key recovery that starts again before any confirm succeeds waits a growing backoff capped at ten minutes, which keeps it within the renewal grace of a leaf of at least 15 minutes; the contract now requires that minimum. The test-only __debug__.identity.min_renewal_interval_secs replaces the wait.
• identity enroll reads the token only from standard input (identity enroll -), so that a token never appears in a process listing or shell history; a token argument is refused without being echoed.
• An identity directory owned by another account is refused rather than repaired, because a handle its creator opened survives an owner reset; a directory the agent owns with wrong permissions is still repaired. private-fs gains Existing::RepairAccess for this.
• The intent now states that the agent's own write replaces a rejection marker or in-progress record it ignores as untrusted, which is what it already does.
• The conformance suite submits tokens on standard input, lets its multi-renewal case remove the renewal wait, and on Windows creates the pending directory it prepares owned by the current user.
  A new mock case shortens the wait to 15 seconds and checks that a renewal requested during it starts no sooner than the wait and still starts once it ends.
  Its README takes the short leaves of the DVLS expiry-boundary test from DVLS's test-only lifetime, since the certificate lifetime setting is at least 15 minutes.

Issue: DGW-478
Security: yes
Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com

🤖 Generated with Claude Code

[Benoît Cortier (CBenoit)]

Acceptance evidence (head 8de90d7d2)

Lines changed:

• Rust under crates/ and devolutions-agent/ (production code with its inline unit tests): +1011 / −94.
• Conformance suite and testsuite: +396 / −62.
• Intent, contract and README: +13 / −6.

Windows (unelevated, fresh TEMP):

• cargo +nightly fmt --check clean.
• cargo clippy -D warnings clean on private-fs, agent-identity, agent-channel-client, devolutions-agent, agent-identity-conformance and testsuite.
• Unit tests: agent-channel-client 140, agent-identity 227, agent-identity-conformance 60 (+1 ignored), devolutions-agent 196+6+25.
• testsuite private_fs: 49.
• ci/check-oracle-markers.ps1 -Base origin/master exits 0.

Linux (WSL Ubuntu):

• clippy clean.
• Unit tests: agent-channel-client 140, agent-identity 210, devolutions-agent 130+6+14.
• testsuite private_fs: 39.
• Conformance suite (agent_identity::conformance, file backend): PASS 192, FAIL 0, SKIP 0, N/A 2. Both N/A cases are Windows-only.
• Three agent-identity-conformance unit tests fail locally with "mode 777, expected 0600". They write under the workspace target/ on a Windows drive mounted in WSL, which ignores chmod, and they fail the same way without this change. CI runs them on a native file system.

Not run locally: the elevated Windows paths (the conformance suite with the Windows software provider, and the elevated_only_* tests). CI runs them.

Approved intent and contract text: each sentence was compared byte for byte against its approved wording.

Reviews

• Two routine review rounds, then a final whole-delta review: approved, no blocking findings.
• Each conformance-suite change was written blind to the implementation and reviewed separately.
• An intent-drift audit of the governed paths found no violation. Its one partial is listed under open questions.

Conformance-suite changes (each approved before it was written)

• Tokens are submitted with identity enroll - on standard input.
• a_renew_transient_failures_retry_without_state_change sets __debug__.identity.min_renewal_interval_secs: 0, because it requests three renewals in one run.
• On Windows, write_pending creates any missing directory owned by the current user, with the suite's protected DACL. Under UAC elevation a new directory is owned by Administrators, which the agent now refuses.

Deviation decided inside the brief

A pending-key recovery that starts again before any confirm succeeds now waits a backoff. The backoff grows until a confirm succeeds, capped at 10 minutes, or at backoff_max_secs when that is lower. The first recovery still starts at once.

• Basis: contract §8.1 "retry with backoff", and the stated purpose of the 10-minute wait in crates/agent-identity/INTENT.md §Schedules.
• Why 10 minutes: it keeps the recovery within the renewal grace of a leaf of at least 15 minutes.
• No intent sentence states this backoff yet.

UNTESTED properties

• devolutions-agent/src/identity/runner.rs:274: a successful confirm records last_renewal, and every new renewal starts through renewal_start.
• devolutions-agent/src/identity/runner.rs:440: each recovery waits the backoff of recoveries. Only a successful confirm resets it; a successful renew leaves it alone.
• crates/private-fs/src/unix.rs:201: a repair of access only reports a directory it can't open that is owned by an account the rule doesn't allow. It does not change that directory.
• crates/agent-identity-conformance/src/windows.rs:284: a directory created concurrently, such as by the agent provisioning at start-up, is left as it is.

Open questions for a human

1. Foreign-owned directory mid-run. crates/agent-identity/INTENT.md §Local state says a foreign-owned identity directory "stops all identity processing until it is fixed". At start-up it does. Mid-run, an owner change by an administrator makes every state change fail, but live runners and their streams keep running. Either the pending poll treats this refusal like an untrusted stored identity, or the sentence is scoped to start-up.
2. Wording. The intent's test setting "shortens" the wait in crates/agent-identity/INTENT.md §Schedules, but "replaces" it in devolutions-agent/src/identity/INTENT.md §Configuration. The code replaces it.
3. DVLS leaf lifetime. crates/agent-identity-conformance/README.md asks for a DVLS leaf lifetime of roughly 10–30 seconds, which contract §4 now rules out (at least 15 minutes).
4. Short leaf at the end of a root's life. Contract §4 caps a leaf's lifetime at the issuing root's notAfter. A leaf issued close to that date can be shorter than the 10-minute wait, and then its renewal would fall beyond grace.
5. Coverage of the default wait. No conformance case covers the default 10-minute wait between renewals. Only renewal_start unit tests and the UNTESTED wiring above do.

Non-blocking review findings left as they are

• OwnerChange is declared once in each private-fs backend.
• The HTTP and gRPC clients each carry their own copy of the error-code filter and the one-day offset constant. They are kept in step by tests on both sides.
• Two closure test cases (digit_first, underscore_first) and the exact escape spelling in the loggable tests check the client's own rule, not a contract statement.
• ForeignIdentityDirectory's message has two clauses.

Note

LLM-assisted content (no human feedback).

[Benoît Cortier (CBenoit)]

Update (head 2cc351d2b)

Open questions, as answered

1. Foreign-owned directory mid-run: to be fixed in a separate pull request stacked on this one, so that a mid-run owner change stops identity processing as at start-up; nothing changes here.
2. "Shortens" vs "replaces": the wording stays as it is.
3. DVLS leaf lifetime in the conformance README: fixed. The README now takes the 10–30 second leaves of the expiry-boundary test from DVLS's test-only lifetime in its unsafe test mode, and says the certificate lifetime setting stays at least 15 minutes.
4. Short leaf at the end of a root's life: accepted as a known gap. A leaf issued close to its root's notAfter can be shorter than the 10-minute wait, so its renewal can fall beyond grace.
5. Coverage of the wait between renewals: a new conformance case covers it with the wait shortened through the test-only setting (below).

New conformance case a_renewal_waits_between_renewals

• Mock only. It sets __debug__.identity.min_renewal_interval_secs to 15, leaves renewal_after_secs unset, lets one requested renewal complete, and once the agent holds one stream, requests another renewal at least 4 seconds before the wait ends.
• The next renew must come no sooner than the wait after the first renewal completed, measured from a point no later than the arrival of its confirm, and within the wait plus 10 seconds after the request.
• In the mock's event order, no stream opens or authenticates and no check-in arrives before that renew, so only the request pushed during the wait can have triggered it.
• The agent must acknowledge the pushed request within the suite's usual 20-second wait after the renewal settles; the contract sets no deadline for the acknowledgment, so the case does not require it before the wait ends.
• Written without reading the implementation and reviewed in four rounds, the last by a fresh reviewer, which approved it.
• poll! now evaluates its wait once, so that a wait computed from the clock is not shortened on every attempt.

Not checked: the default 10-minute wait itself, the wait for a scheduled renewal or after a certificate_expired refusal, and the exemption of renewal_after_secs.

Verification at this head

Windows (unelevated, fresh TEMP):

• cargo +nightly fmt --check clean; cargo clippy -D warnings clean on the same crates as before.
• Unit tests: agent-channel-client 140, agent-identity 227, agent-identity-conformance 60 (+1 ignored), devolutions-agent 196+6, private-fs 25.
• testsuite private_fs: 49.
• ci/check-oracle-markers.ps1 -Base origin/master exits 0.

Linux (WSL Ubuntu):

• clippy clean.
• Unit tests: agent-channel-client 140, agent-identity 210, devolutions-agent 130+6, private-fs 14.
• testsuite private_fs: 39.
• Conformance suite (file backend): PASS 193, FAIL 0, SKIP 0, N/A 2. Both N/A cases are Windows-only. The new case took 28 seconds.
• The same three agent-identity-conformance unit tests as before fail only on the Windows drive mounted in WSL, which ignores chmod.

CI at the previous head passed every job; there, the conformance suite took about 8 minutes on Linux, 11 on Windows and 10.5 on macOS, within its 14.5-minute limit.

UNTESTED properties, changed

• devolutions-agent/src/identity/runner.rs:274 now says the conformance suite checks the wait for a renewal requested on the channel; the wiring for a scheduled renewal stays untested.

Known limits of the new case

• An unforced transport reconnect during the wait would fail the event-order check, since the new stream's Welcome re-sends the request.
• It fails when settling the first renewal and requesting the second takes more than 11 seconds; on a loaded runner, a longer wait would widen that budget.

Note

LLM-assisted content (no human feedback).