fix(auth): explain DPoP clock-skew failures

[juliusmarminge]

What Changed

Propagate detected DPoP clock skew through environment and relay authentication errors, while preserving existing wire-compatible error reasons. Clients now show actionable guidance to enable automatic date and time on the affected devices. Added focused coverage across shared DPoP verification, server and relay auth boundaries, client runtimes, web, mobile, and contracts, plus remote-access documentation.

Why

DPoP proofs are rejected when device clocks differ from the verifier clock, but the previous generic credential errors made the cause difficult to diagnose. Exposing the measured offset lets clients distinguish clock synchronization problems from other authentication failures and recover without relinking environments or regenerating credentials.

UI Changes

No layout or visual UI changes. Existing connection and environment-link error messages now provide clock-synchronization guidance when the server identifies DPoP clock skew.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Changes authentication error shapes and messaging across server, relay, and clients, but preserves existing error reasons and only adds optional fields; incorrect skew propagation could mislead users or leak timing detail.

Overview
When DPoP proof verification fails because the proof is outside the allowed time window, verifyDpopProof now returns a measured clockSkewSeconds offset (proof iat minus verifier time) alongside the existing failure reason.

That offset is carried through environment server and relay auth layers into EnvironmentAuthInvalidError and RelayAuthInvalidError as an optional field, while keeping the same wire reason values (invalid_credential / invalid_dpop) for compatibility. Web, mobile, and client-runtime connection error mapping now show clock-sync guidance when clockSkewSeconds is present, instead of generic DPoP or credential failures.

Docs add a Clock Sync Errors section for remote access; tests cover shared verification, server/relay boundaries, contracts, and client decoding.

^{Reviewed by Cursor Bugbot for commit 8e686c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add clockSkewSeconds to DPoP verification failures across stack

• verifyDpopProof in dpop.ts now computes clockSkewSeconds as iat - nowEpochSeconds and includes it in the failure result when the proof falls outside the allowed time window.
• The value propagates end-to-end: relay raises DpopProofClockSkewError, server includes clockSkewSeconds in ServerAuthInvalidCredentialError and 401 EnvironmentAuthInvalidError responses, and client-runtime/UI layers surface a clock-sync guidance message instead of the generic DPoP rejection text.
• Added a "Clock Sync Errors" section to remote-access.md instructing users to enable automatic date and time.
• Behavioral Change: DpopProofReplay.verifyAndConsume in DpopProofs.ts now fails with DpopProofClockSkewError instead of Unauthorized when a time-window violation carries clockSkewSeconds; callers relying on the Unauthorized error type for clock-skew cases should check for the new tagged error.

^{Macroscope summarized 8e686c7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c59d8fb5-c974-4164-9c2c-8a6a416bd6a6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.3 KiB	13.3 KiB	+19 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	+10 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+9 B (+0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	55.6 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	11	11	0 (0.0%)	21	✅
Claude	Total thread wire	13.4 KiB	13.3 KiB	−2 B (−0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−6 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.4 KiB	56.4 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	11	11	0 (0.0%)	21	✅

Baseline: a6797b3 · PR result: 8e686c7 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production DPoP authentication handling across the shared verifier, relay, server HTTP/WebSocket boundaries, wire contracts, and client messaging. Although the change is additive and focused on clearer clock-skew diagnostics, authentication-sensitive changes require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

Superseded by #8351, which now carries the typed DPoP failure categories, cautious legacy fallback, focused clock-skew integration coverage, and the shared web/mobile error presentation.

[juliusmarminge]

What Changed

Propagate detected DPoP clock skew through environment and relay authentication errors, while preserving existing wire-compatible error reasons. Clients now show actionable guidance to enable automatic date and time on the affected devices. Added focused coverage across shared DPoP verification, server and relay auth boundaries, client runtimes, web, mobile, and contracts, plus remote-access documentation.

Why

DPoP proofs are rejected when device clocks differ from the verifier clock, but the previous generic credential errors made the cause difficult to diagnose. Exposing the measured offset lets clients distinguish clock synchronization problems from other authentication failures and recover without relinking environments or regenerating credentials.

UI Changes

No layout or visual UI changes. Existing connection and environment-link error messages now provide clock-synchronization guidance when the server identifies DPoP clock skew.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Changes authentication error shapes and messaging across server, relay, and clients, but preserves existing error reasons and only adds optional fields; incorrect skew propagation could mislead users or leak timing detail.

Overview
When DPoP proof verification fails because the proof is outside the allowed time window, verifyDpopProof now returns a measured clockSkewSeconds offset (proof iat minus verifier time) alongside the existing failure reason.

That offset is carried through environment server and relay auth layers into EnvironmentAuthInvalidError and RelayAuthInvalidError as an optional field, while keeping the same wire reason values (invalid_credential / invalid_dpop) for compatibility. Web, mobile, and client-runtime connection error mapping now show clock-sync guidance when clockSkewSeconds is present, instead of generic DPoP or credential failures.

Docs add a Clock Sync Errors section for remote access; tests cover shared verification, server/relay boundaries, contracts, and client decoding.

^{Reviewed by Cursor Bugbot for commit 8e686c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add clockSkewSeconds to DPoP verification failures across stack

• verifyDpopProof in dpop.ts now computes clockSkewSeconds as iat - nowEpochSeconds and includes it in the failure result when the proof falls outside the allowed time window.
• The value propagates end-to-end: relay raises DpopProofClockSkewError, server includes clockSkewSeconds in ServerAuthInvalidCredentialError and 401 EnvironmentAuthInvalidError responses, and client-runtime/UI layers surface a clock-sync guidance message instead of the generic DPoP rejection text.
• Added a "Clock Sync Errors" section to remote-access.md instructing users to enable automatic date and time.
• Behavioral Change: DpopProofReplay.verifyAndConsume in DpopProofs.ts now fails with DpopProofClockSkewError instead of Unauthorized when a time-window violation carries clockSkewSeconds; callers relying on the Unauthorized error type for clock-skew cases should check for the new tagged error.

^{Macroscope summarized 8e686c7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c59d8fb5-c974-4164-9c2c-8a6a416bd6a6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.3 KiB	13.3 KiB	+19 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	+10 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+9 B (+0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	55.6 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	11	11	0 (0.0%)	21	✅
Claude	Total thread wire	13.4 KiB	13.3 KiB	−2 B (−0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−6 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.4 KiB	56.4 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	11	11	0 (0.0%)	21	✅

Baseline: a6797b3 · PR result: 8e686c7 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production DPoP authentication handling across the shared verifier, relay, server HTTP/WebSocket boundaries, wire contracts, and client messaging. Although the change is additive and focused on clearer clock-skew diagnostics, authentication-sensitive changes require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

Superseded by #8351, which now carries the typed DPoP failure categories, cautious legacy fallback, focused clock-skew integration coverage, and the shared web/mobile error presentation.

[juliusmarminge]

What Changed

Propagate detected DPoP clock skew through environment and relay authentication errors, while preserving existing wire-compatible error reasons. Clients now show actionable guidance to enable automatic date and time on the affected devices. Added focused coverage across shared DPoP verification, server and relay auth boundaries, client runtimes, web, mobile, and contracts, plus remote-access documentation.

Why

DPoP proofs are rejected when device clocks differ from the verifier clock, but the previous generic credential errors made the cause difficult to diagnose. Exposing the measured offset lets clients distinguish clock synchronization problems from other authentication failures and recover without relinking environments or regenerating credentials.

UI Changes

No layout or visual UI changes. Existing connection and environment-link error messages now provide clock-synchronization guidance when the server identifies DPoP clock skew.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Changes authentication error shapes and messaging across server, relay, and clients, but preserves existing error reasons and only adds optional fields; incorrect skew propagation could mislead users or leak timing detail.

Overview
When DPoP proof verification fails because the proof is outside the allowed time window, verifyDpopProof now returns a measured clockSkewSeconds offset (proof iat minus verifier time) alongside the existing failure reason.

That offset is carried through environment server and relay auth layers into EnvironmentAuthInvalidError and RelayAuthInvalidError as an optional field, while keeping the same wire reason values (invalid_credential / invalid_dpop) for compatibility. Web, mobile, and client-runtime connection error mapping now show clock-sync guidance when clockSkewSeconds is present, instead of generic DPoP or credential failures.

Docs add a Clock Sync Errors section for remote access; tests cover shared verification, server/relay boundaries, contracts, and client decoding.

^{Reviewed by Cursor Bugbot for commit 8e686c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add clockSkewSeconds to DPoP verification failures across stack

• verifyDpopProof in dpop.ts now computes clockSkewSeconds as iat - nowEpochSeconds and includes it in the failure result when the proof falls outside the allowed time window.
• The value propagates end-to-end: relay raises DpopProofClockSkewError, server includes clockSkewSeconds in ServerAuthInvalidCredentialError and 401 EnvironmentAuthInvalidError responses, and client-runtime/UI layers surface a clock-sync guidance message instead of the generic DPoP rejection text.
• Added a "Clock Sync Errors" section to remote-access.md instructing users to enable automatic date and time.
• Behavioral Change: DpopProofReplay.verifyAndConsume in DpopProofs.ts now fails with DpopProofClockSkewError instead of Unauthorized when a time-window violation carries clockSkewSeconds; callers relying on the Unauthorized error type for clock-skew cases should check for the new tagged error.

^{Macroscope summarized 8e686c7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c59d8fb5-c974-4164-9c2c-8a6a416bd6a6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.3 KiB	13.3 KiB	+19 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	+10 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+9 B (+0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	55.6 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	11	11	0 (0.0%)	21	✅
Claude	Total thread wire	13.4 KiB	13.3 KiB	−2 B (−0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−6 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.4 KiB	56.4 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	11	11	0 (0.0%)	21	✅

Baseline: a6797b3 · PR result: 8e686c7 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production DPoP authentication handling across the shared verifier, relay, server HTTP/WebSocket boundaries, wire contracts, and client messaging. Although the change is additive and focused on clearer clock-skew diagnostics, authentication-sensitive changes require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

Superseded by #8351, which now carries the typed DPoP failure categories, cautious legacy fallback, focused clock-skew integration coverage, and the shared web/mobile error presentation.

[juliusmarminge]

What Changed

Propagate detected DPoP clock skew through environment and relay authentication errors, while preserving existing wire-compatible error reasons. Clients now show actionable guidance to enable automatic date and time on the affected devices. Added focused coverage across shared DPoP verification, server and relay auth boundaries, client runtimes, web, mobile, and contracts, plus remote-access documentation.

Why

DPoP proofs are rejected when device clocks differ from the verifier clock, but the previous generic credential errors made the cause difficult to diagnose. Exposing the measured offset lets clients distinguish clock synchronization problems from other authentication failures and recover without relinking environments or regenerating credentials.

UI Changes

No layout or visual UI changes. Existing connection and environment-link error messages now provide clock-synchronization guidance when the server identifies DPoP clock skew.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Changes authentication error shapes and messaging across server, relay, and clients, but preserves existing error reasons and only adds optional fields; incorrect skew propagation could mislead users or leak timing detail.

Overview
When DPoP proof verification fails because the proof is outside the allowed time window, verifyDpopProof now returns a measured clockSkewSeconds offset (proof iat minus verifier time) alongside the existing failure reason.

That offset is carried through environment server and relay auth layers into EnvironmentAuthInvalidError and RelayAuthInvalidError as an optional field, while keeping the same wire reason values (invalid_credential / invalid_dpop) for compatibility. Web, mobile, and client-runtime connection error mapping now show clock-sync guidance when clockSkewSeconds is present, instead of generic DPoP or credential failures.

Docs add a Clock Sync Errors section for remote access; tests cover shared verification, server/relay boundaries, contracts, and client decoding.

^{Reviewed by Cursor Bugbot for commit 8e686c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add clockSkewSeconds to DPoP verification failures across stack

• verifyDpopProof in dpop.ts now computes clockSkewSeconds as iat - nowEpochSeconds and includes it in the failure result when the proof falls outside the allowed time window.
• The value propagates end-to-end: relay raises DpopProofClockSkewError, server includes clockSkewSeconds in ServerAuthInvalidCredentialError and 401 EnvironmentAuthInvalidError responses, and client-runtime/UI layers surface a clock-sync guidance message instead of the generic DPoP rejection text.
• Added a "Clock Sync Errors" section to remote-access.md instructing users to enable automatic date and time.
• Behavioral Change: DpopProofReplay.verifyAndConsume in DpopProofs.ts now fails with DpopProofClockSkewError instead of Unauthorized when a time-window violation carries clockSkewSeconds; callers relying on the Unauthorized error type for clock-skew cases should check for the new tagged error.

^{Macroscope summarized 8e686c7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c59d8fb5-c974-4164-9c2c-8a6a416bd6a6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.3 KiB	13.3 KiB	+19 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	+10 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+9 B (+0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	55.6 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	11	11	0 (0.0%)	21	✅
Claude	Total thread wire	13.4 KiB	13.3 KiB	−2 B (−0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−6 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.4 KiB	56.4 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	11	11	0 (0.0%)	21	✅

Baseline: a6797b3 · PR result: 8e686c7 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production DPoP authentication handling across the shared verifier, relay, server HTTP/WebSocket boundaries, wire contracts, and client messaging. Although the change is additive and focused on clearer clock-skew diagnostics, authentication-sensitive changes require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

Superseded by #8351, which now carries the typed DPoP failure categories, cautious legacy fallback, focused clock-skew integration coverage, and the shared web/mobile error presentation.

[juliusmarminge]

What Changed

Propagate detected DPoP clock skew through environment and relay authentication errors, while preserving existing wire-compatible error reasons. Clients now show actionable guidance to enable automatic date and time on the affected devices. Added focused coverage across shared DPoP verification, server and relay auth boundaries, client runtimes, web, mobile, and contracts, plus remote-access documentation.

Why

DPoP proofs are rejected when device clocks differ from the verifier clock, but the previous generic credential errors made the cause difficult to diagnose. Exposing the measured offset lets clients distinguish clock synchronization problems from other authentication failures and recover without relinking environments or regenerating credentials.

UI Changes

No layout or visual UI changes. Existing connection and environment-link error messages now provide clock-synchronization guidance when the server identifies DPoP clock skew.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Changes authentication error shapes and messaging across server, relay, and clients, but preserves existing error reasons and only adds optional fields; incorrect skew propagation could mislead users or leak timing detail.

Overview
When DPoP proof verification fails because the proof is outside the allowed time window, verifyDpopProof now returns a measured clockSkewSeconds offset (proof iat minus verifier time) alongside the existing failure reason.

That offset is carried through environment server and relay auth layers into EnvironmentAuthInvalidError and RelayAuthInvalidError as an optional field, while keeping the same wire reason values (invalid_credential / invalid_dpop) for compatibility. Web, mobile, and client-runtime connection error mapping now show clock-sync guidance when clockSkewSeconds is present, instead of generic DPoP or credential failures.

Docs add a Clock Sync Errors section for remote access; tests cover shared verification, server/relay boundaries, contracts, and client decoding.

^{Reviewed by Cursor Bugbot for commit 8e686c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add clockSkewSeconds to DPoP verification failures across stack

• verifyDpopProof in dpop.ts now computes clockSkewSeconds as iat - nowEpochSeconds and includes it in the failure result when the proof falls outside the allowed time window.
• The value propagates end-to-end: relay raises DpopProofClockSkewError, server includes clockSkewSeconds in ServerAuthInvalidCredentialError and 401 EnvironmentAuthInvalidError responses, and client-runtime/UI layers surface a clock-sync guidance message instead of the generic DPoP rejection text.
• Added a "Clock Sync Errors" section to remote-access.md instructing users to enable automatic date and time.
• Behavioral Change: DpopProofReplay.verifyAndConsume in DpopProofs.ts now fails with DpopProofClockSkewError instead of Unauthorized when a time-window violation carries clockSkewSeconds; callers relying on the Unauthorized error type for clock-skew cases should check for the new tagged error.

^{Macroscope summarized 8e686c7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c59d8fb5-c974-4164-9c2c-8a6a416bd6a6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.3 KiB	13.3 KiB	+19 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	+10 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+9 B (+0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	55.6 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	11	11	0 (0.0%)	21	✅
Claude	Total thread wire	13.4 KiB	13.3 KiB	−2 B (−0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−6 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.4 KiB	56.4 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	11	11	0 (0.0%)	21	✅

Baseline: a6797b3 · PR result: 8e686c7 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production DPoP authentication handling across the shared verifier, relay, server HTTP/WebSocket boundaries, wire contracts, and client messaging. Although the change is additive and focused on clearer clock-skew diagnostics, authentication-sensitive changes require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

Superseded by #8351, which now carries the typed DPoP failure categories, cautious legacy fallback, focused clock-skew integration coverage, and the shared web/mobile error presentation.

[juliusmarminge]

What Changed

Propagate detected DPoP clock skew through environment and relay authentication errors, while preserving existing wire-compatible error reasons. Clients now show actionable guidance to enable automatic date and time on the affected devices. Added focused coverage across shared DPoP verification, server and relay auth boundaries, client runtimes, web, mobile, and contracts, plus remote-access documentation.

Why

DPoP proofs are rejected when device clocks differ from the verifier clock, but the previous generic credential errors made the cause difficult to diagnose. Exposing the measured offset lets clients distinguish clock synchronization problems from other authentication failures and recover without relinking environments or regenerating credentials.

UI Changes

No layout or visual UI changes. Existing connection and environment-link error messages now provide clock-synchronization guidance when the server identifies DPoP clock skew.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Changes authentication error shapes and messaging across server, relay, and clients, but preserves existing error reasons and only adds optional fields; incorrect skew propagation could mislead users or leak timing detail.

Overview
When DPoP proof verification fails because the proof is outside the allowed time window, verifyDpopProof now returns a measured clockSkewSeconds offset (proof iat minus verifier time) alongside the existing failure reason.

That offset is carried through environment server and relay auth layers into EnvironmentAuthInvalidError and RelayAuthInvalidError as an optional field, while keeping the same wire reason values (invalid_credential / invalid_dpop) for compatibility. Web, mobile, and client-runtime connection error mapping now show clock-sync guidance when clockSkewSeconds is present, instead of generic DPoP or credential failures.

Docs add a Clock Sync Errors section for remote access; tests cover shared verification, server/relay boundaries, contracts, and client decoding.

^{Reviewed by Cursor Bugbot for commit 8e686c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add clockSkewSeconds to DPoP verification failures across stack

• verifyDpopProof in dpop.ts now computes clockSkewSeconds as iat - nowEpochSeconds and includes it in the failure result when the proof falls outside the allowed time window.
• The value propagates end-to-end: relay raises DpopProofClockSkewError, server includes clockSkewSeconds in ServerAuthInvalidCredentialError and 401 EnvironmentAuthInvalidError responses, and client-runtime/UI layers surface a clock-sync guidance message instead of the generic DPoP rejection text.
• Added a "Clock Sync Errors" section to remote-access.md instructing users to enable automatic date and time.
• Behavioral Change: DpopProofReplay.verifyAndConsume in DpopProofs.ts now fails with DpopProofClockSkewError instead of Unauthorized when a time-window violation carries clockSkewSeconds; callers relying on the Unauthorized error type for clock-skew cases should check for the new tagged error.

^{Macroscope summarized 8e686c7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c59d8fb5-c974-4164-9c2c-8a6a416bd6a6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.3 KiB	13.3 KiB	+19 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	+10 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+9 B (+0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	55.6 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	11	11	0 (0.0%)	21	✅
Claude	Total thread wire	13.4 KiB	13.3 KiB	−2 B (−0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−6 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.4 KiB	56.4 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	11	11	0 (0.0%)	21	✅

Baseline: a6797b3 · PR result: 8e686c7 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production DPoP authentication handling across the shared verifier, relay, server HTTP/WebSocket boundaries, wire contracts, and client messaging. Although the change is additive and focused on clearer clock-skew diagnostics, authentication-sensitive changes require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

Superseded by #8351, which now carries the typed DPoP failure categories, cautious legacy fallback, focused clock-skew integration coverage, and the shared web/mobile error presentation.

[juliusmarminge]

What Changed

Propagate detected DPoP clock skew through environment and relay authentication errors, while preserving existing wire-compatible error reasons. Clients now show actionable guidance to enable automatic date and time on the affected devices. Added focused coverage across shared DPoP verification, server and relay auth boundaries, client runtimes, web, mobile, and contracts, plus remote-access documentation.

Why

DPoP proofs are rejected when device clocks differ from the verifier clock, but the previous generic credential errors made the cause difficult to diagnose. Exposing the measured offset lets clients distinguish clock synchronization problems from other authentication failures and recover without relinking environments or regenerating credentials.

UI Changes

No layout or visual UI changes. Existing connection and environment-link error messages now provide clock-synchronization guidance when the server identifies DPoP clock skew.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Changes authentication error shapes and messaging across server, relay, and clients, but preserves existing error reasons and only adds optional fields; incorrect skew propagation could mislead users or leak timing detail.

Overview
When DPoP proof verification fails because the proof is outside the allowed time window, verifyDpopProof now returns a measured clockSkewSeconds offset (proof iat minus verifier time) alongside the existing failure reason.

That offset is carried through environment server and relay auth layers into EnvironmentAuthInvalidError and RelayAuthInvalidError as an optional field, while keeping the same wire reason values (invalid_credential / invalid_dpop) for compatibility. Web, mobile, and client-runtime connection error mapping now show clock-sync guidance when clockSkewSeconds is present, instead of generic DPoP or credential failures.

Docs add a Clock Sync Errors section for remote access; tests cover shared verification, server/relay boundaries, contracts, and client decoding.

^{Reviewed by Cursor Bugbot for commit 8e686c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add clockSkewSeconds to DPoP verification failures across stack

• verifyDpopProof in dpop.ts now computes clockSkewSeconds as iat - nowEpochSeconds and includes it in the failure result when the proof falls outside the allowed time window.
• The value propagates end-to-end: relay raises DpopProofClockSkewError, server includes clockSkewSeconds in ServerAuthInvalidCredentialError and 401 EnvironmentAuthInvalidError responses, and client-runtime/UI layers surface a clock-sync guidance message instead of the generic DPoP rejection text.
• Added a "Clock Sync Errors" section to remote-access.md instructing users to enable automatic date and time.
• Behavioral Change: DpopProofReplay.verifyAndConsume in DpopProofs.ts now fails with DpopProofClockSkewError instead of Unauthorized when a time-window violation carries clockSkewSeconds; callers relying on the Unauthorized error type for clock-skew cases should check for the new tagged error.

^{Macroscope summarized 8e686c7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c59d8fb5-c974-4164-9c2c-8a6a416bd6a6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.3 KiB	13.3 KiB	+19 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	+10 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+9 B (+0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	55.6 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	11	11	0 (0.0%)	21	✅
Claude	Total thread wire	13.4 KiB	13.3 KiB	−2 B (−0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−6 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.4 KiB	56.4 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	11	11	0 (0.0%)	21	✅

Baseline: a6797b3 · PR result: 8e686c7 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production DPoP authentication handling across the shared verifier, relay, server HTTP/WebSocket boundaries, wire contracts, and client messaging. Although the change is additive and focused on clearer clock-skew diagnostics, authentication-sensitive changes require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

Superseded by #8351, which now carries the typed DPoP failure categories, cautious legacy fallback, focused clock-skew integration coverage, and the shared web/mobile error presentation.

[juliusmarminge]

What Changed

Propagate detected DPoP clock skew through environment and relay authentication errors, while preserving existing wire-compatible error reasons. Clients now show actionable guidance to enable automatic date and time on the affected devices. Added focused coverage across shared DPoP verification, server and relay auth boundaries, client runtimes, web, mobile, and contracts, plus remote-access documentation.

Why

DPoP proofs are rejected when device clocks differ from the verifier clock, but the previous generic credential errors made the cause difficult to diagnose. Exposing the measured offset lets clients distinguish clock synchronization problems from other authentication failures and recover without relinking environments or regenerating credentials.

UI Changes

No layout or visual UI changes. Existing connection and environment-link error messages now provide clock-synchronization guidance when the server identifies DPoP clock skew.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Changes authentication error shapes and messaging across server, relay, and clients, but preserves existing error reasons and only adds optional fields; incorrect skew propagation could mislead users or leak timing detail.

Overview
When DPoP proof verification fails because the proof is outside the allowed time window, verifyDpopProof now returns a measured clockSkewSeconds offset (proof iat minus verifier time) alongside the existing failure reason.

That offset is carried through environment server and relay auth layers into EnvironmentAuthInvalidError and RelayAuthInvalidError as an optional field, while keeping the same wire reason values (invalid_credential / invalid_dpop) for compatibility. Web, mobile, and client-runtime connection error mapping now show clock-sync guidance when clockSkewSeconds is present, instead of generic DPoP or credential failures.

Docs add a Clock Sync Errors section for remote access; tests cover shared verification, server/relay boundaries, contracts, and client decoding.

^{Reviewed by Cursor Bugbot for commit 8e686c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add clockSkewSeconds to DPoP verification failures across stack

• verifyDpopProof in dpop.ts now computes clockSkewSeconds as iat - nowEpochSeconds and includes it in the failure result when the proof falls outside the allowed time window.
• The value propagates end-to-end: relay raises DpopProofClockSkewError, server includes clockSkewSeconds in ServerAuthInvalidCredentialError and 401 EnvironmentAuthInvalidError responses, and client-runtime/UI layers surface a clock-sync guidance message instead of the generic DPoP rejection text.
• Added a "Clock Sync Errors" section to remote-access.md instructing users to enable automatic date and time.
• Behavioral Change: DpopProofReplay.verifyAndConsume in DpopProofs.ts now fails with DpopProofClockSkewError instead of Unauthorized when a time-window violation carries clockSkewSeconds; callers relying on the Unauthorized error type for clock-skew cases should check for the new tagged error.

^{Macroscope summarized 8e686c7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c59d8fb5-c974-4164-9c2c-8a6a416bd6a6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.3 KiB	13.3 KiB	+19 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	+10 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+9 B (+0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	55.6 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	11	11	0 (0.0%)	21	✅
Claude	Total thread wire	13.4 KiB	13.3 KiB	−2 B (−0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−6 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.4 KiB	56.4 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	11	11	0 (0.0%)	21	✅

Baseline: a6797b3 · PR result: 8e686c7 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production DPoP authentication handling across the shared verifier, relay, server HTTP/WebSocket boundaries, wire contracts, and client messaging. Although the change is additive and focused on clearer clock-skew diagnostics, authentication-sensitive changes require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

Superseded by #8351, which now carries the typed DPoP failure categories, cautious legacy fallback, focused clock-skew integration coverage, and the shared web/mobile error presentation.