Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -1305,6 +1305,7 @@ leading and trailing pipe. Columns, in order:
| dashboard-browser-fixture-guard | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | handing a Dashboard URL straight to Windows even when the app runs under the gateway fixture | DashboardBrowser | App supplies the Windows launch and logger delegates | outside fixture mode the exact URL goes to Windows; under OPENCLAW_GATEWAY_FIXTURE the launch is suppressed and only the redacted target is logged; a one-shot dashboard-browser-failure.once marker simulates one browser failure; an invalid fixture context fails closed | DashboardBrowserTests.FixtureRun_NeverReachesWindowsAndLogsOnlyTheRedactedUrl | behavioral | - |
| setup-session-captured-authority | authoritative | src/OpenClaw.SetupEngine/SetupGatewaySession.cs | deriving client authority from a later active registry record | SetupGatewaySessionBinding | session reloads registry only to validate captured identity at admission, handshake, reconnect and request boundaries | a socket opened for Gateway A cannot be reported as Gateway B; same-ID endpoint and SSH changes fail while connection timestamps remain valid | SetupGatewaySessionBindingTests.ChangedRegistryDuringConnect_CannotRelabelAlreadyCreatedClient | behavioral | - |
| setup-dashboard-pending-proof | authoritative | src/OpenClaw.Tray.WinUI/Services/SetupDashboardHandoff.cs | accepting external serialized completion JSON as verified proof | SetupDashboardHandoffStore + SetupNativeHandoffLauncher | activation parser admits only an opaque native handle; WindowManager rechecks current observations with SetupDashboardLiveFacts | a short-lived local pending record is exclusively leased, consumed on successful native presentation and retained only for explicit failed-launch retry; unknown, expired, forged, consumed and in-flight replay fail visibly; old generation numbers are not live authority | SetupDashboardHandoffStoreTests.ForgedShapeAndUnknownHandle_AreNotVerificationAuthority | behavioral | - |
| saved-personal-dashboard-owner | authoritative | src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs | saved-row personal Dashboard browser and shared-token handoff | GatewayDashboardLauncher + WindowManager | page passes the requested Gateway through IAppCommands; App composes native admission and preserves that target on retry; shared rows retain their existing endpoint provenance path | a Personal row never exports saved credentials; missing or changed current lease refuses admission before a window effect, including after old-window retirement | AppRefactorContractTests.SavedPersonalDashboard_CarriesRequestedGatewayThroughAdmissionAndRetry | source-shape | when mounted saved-row Dashboard coverage proves requested-target admission and lease replacement during window retirement |
<!-- LEDGER:END -->

## Deferred test builders
Expand Down
30 changes: 29 additions & 1 deletion docs/CONNECTION_ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -895,7 +895,7 @@ the existing `SetupGatewaySession` reads credentials from the active registry.
No browser-profile credentials are accepted by this port, and it does not change
Node mode, local MCP, capability settings, or install WSL.

Credential resolution order is intentionally strict:
Credential resolution order for the default Gateway credential mode is intentionally strict:

1. **Stored device token** in the per-gateway identity directory.
2. **`GatewayRecord.SharedGatewayToken`** - shared token for HTTP/chat surfaces.
Expand All @@ -922,6 +922,34 @@ URLs; remote HTTPS gateways retain proxy support. It accepts the original
200-399 response without following redirects, so a readiness check never
contacts a `Location` destination. Browser navigation remains a separate step.

## Personal Tailscale operator identity

The direct Gateway form offers **Personal Tailscale identity** as an explicit
operator authentication mode. It requires a credential-free `wss://` address
under `.ts.net`, without SSH forwarding. The hostname admits the route; it does
not prove the caller's identity. The Gateway must support personal Tailscale
authentication and a canonical `users.self` profile.

`CredentialResolver` returns an empty personal credential without reading saved
operator tokens. The client signs an interactive `gateway-client` / `ui` connect
with empty `auth`. A current-socket hello must report `auth.method=tailscale`
and a nonempty `recoveryScope`. Application readiness follows a successful
`users.self` read on that same transport epoch. Node credential resolution and
saved shared credentials remain unchanged. Personal failures do not activate
shared-token or bootstrap recovery.

The personal Dashboard opens in a native WebView. Each challenge rechecks
`users.self` and the exact current lease before returning a signed credentialless
response bound to the method and recovery scope. The shared Control UI must
support this native response contract. Navigation, reconnect, profile changes
and lease retirement prevent an old document from receiving a new proof.

Each window uses its own named InPrivate browser profile. Closing or retiring
that window calls the browser's profile deletion API and closes the control.
WebView2 deletes the marked profile at browser-process exit and retries after
later starts if another process holds its files. This does not assert immediate
disk erasure.

## Self-recovery and automatic local-gateway repair

Two orthogonal self-healing behaviors keep the connection reliable without dead-ending the user:
Expand Down
7 changes: 7 additions & 0 deletions docs/OPERATOR_NODE_CONCEPTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,13 @@ tokens can help the app connect for the first time, but a paired device token
takes precedence after approval. This keeps long-lived operator and node
identity scoped to the gateway record that issued it.

An existing Tailscale Gateway can instead use the explicit personal operator
mode. The Gateway verifies the Tailscale user, and Companion checks the current
personal profile before exposing the operator connection. This does not turn the
Windows node identity into a person or change node pairing. See
[personal Tailscale operator identity](CONNECTION_ARCHITECTURE.md#personal-tailscale-operator-identity)
for the connection and Dashboard requirements.

Some trust decisions are intentionally not automatic. Node command trust and
capability reapproval stay pending until an operator explicitly approves them,
so a new or changed node capability is visible before the gateway can use it.
Expand Down
5 changes: 3 additions & 2 deletions src/OpenClaw.Connection/BootstrapTokenLifecycle.cs
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,8 @@ internal OperatorCredentialSelection SelectOperatorCredential(
var selected = resolved;
lock (_stateLock)
{
if (_forceBootstrapForGatewayRecordId == record.Id &&
if (record.OperatorAuthentication == OperatorAuthenticationMode.GatewayCredential &&
_forceBootstrapForGatewayRecordId == record.Id &&
!string.IsNullOrWhiteSpace(record.BootstrapToken))
{
var credential = new GatewayCredential(
Expand Down Expand Up @@ -390,7 +391,7 @@ attempt.GatewayRecordId is null ||
}

var record = _registry.GetById(attempt.GatewayRecordId);
if (record is null)
if (record is null || record.OperatorAuthentication == OperatorAuthenticationMode.PersonalTailscale)
return false;

var hasSharedToken = !string.IsNullOrWhiteSpace(record.SharedGatewayToken);
Expand Down
16 changes: 16 additions & 0 deletions src/OpenClaw.Connection/CredentialResolver.cs
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,22 @@ public GatewayCredentialResolution ResolveOperatorDetailed(GatewayRecord record,
{
ArgumentNullException.ThrowIfNull(record);

if (record.OperatorAuthentication == OperatorAuthenticationMode.PersonalTailscale)
{
if (record.SshTunnel is not null ||
!GatewayPersonalAuthenticationPolicy.TryNormalizeGatewayUrl(record.Url, out _, out var error))
return new(null, GatewayCredentialResolutionStatus.Missing,
Detail: "Personal authentication requires a direct credential-free wss:// host.ts.net route.");
return GatewayCredentialResolution.FromLegacy(new GatewayCredential(
string.Empty, false, GatewayPersonalAuthenticationPolicy.CredentialSource)
{
OperatorAuthentication = OperatorAuthenticationMode.PersonalTailscale
});
}
if (record.OperatorAuthentication != OperatorAuthenticationMode.GatewayCredential)
return new(null, GatewayCredentialResolutionStatus.Corrupt,
Detail: "The saved operator authentication mode is unsupported.");

return ResolveRole(
_identityReader.ReadStoredDeviceToken(identityPath),
SourceDeviceToken,
Expand Down
3 changes: 2 additions & 1 deletion src/OpenClaw.Connection/GatewayClientFactory.cs
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ public IGatewayClientLifecycle Create(
bootstrapPairAsNode: false,
identityPath: identityPath,
ignoreStoredDeviceToken: credential.IsBootstrapToken,
assistantMediaAuthToken: credential.InteractiveHttpToken)
assistantMediaAuthToken: credential.InteractiveHttpToken,
operatorAuthentication: credential.OperatorAuthentication)
{
SupportsExecApprovals = SupportsExecApprovals,
ClientIdentity = ClientIdentity,
Expand Down
139 changes: 139 additions & 0 deletions src/OpenClaw.Connection/GatewayConnectionManager.PersonalIdentity.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
using System.Text.Json;
using OpenClaw.Shared;

namespace OpenClaw.Connection;

public sealed partial class GatewayConnectionManager
{
private enum PersonalVerification { NotRequired, Verified, Stale, Rejected }
private PersonalOperatorLease? _personalOperatorLease;

public PersonalOperatorLease? CurrentPersonalOperatorLease
{
get
{
var lease = Volatile.Read(ref _personalOperatorLease);
var client = _activeLifecycle?.DataClient;
if (lease is null || client is not { IsPersonalTailscaleAuthentication: true } ||
lease.Generation != Interlocked.Read(ref _generation) ||
client.SessionMutationConnectionEpoch != lease.TransportEpoch ||
client.AuthenticatedSigningDeviceId != lease.DeviceId ||
client.PersonalRecoveryScope != lease.RecoveryScope ||
_registry.ActiveGatewayId != lease.GatewayId ||
_registry.GetById(lease.GatewayId) is not { OperatorAuthentication: OperatorAuthenticationMode.PersonalTailscale } record ||
record.SshTunnel is not null ||
!GatewayPersonalAuthenticationPolicy.TryNormalizeGatewayUrl(record.Url, out var route, out _) ||
!GatewayPersonalAuthenticationPolicy.TryNormalizeGatewayUrl(client.CurrentGatewayUrl, out var connected, out _) ||
!GatewayPersonalAuthenticationPolicy.TryNormalizeGatewayUrl(lease.GatewayUrl, out var leased, out _) ||
route != connected || route != leased)
return null;
return lease;
}
}

private async Task<(PersonalVerification Disposition, PersonalOperatorLease? Lease)> VerifyPersonalOperatorAsync(long generation)
{
var client = _activeLifecycle?.DataClient;
var record = _activeGatewayRecordId is null ? null : _registry.GetById(_activeGatewayRecordId);
if (record?.OperatorAuthentication != OperatorAuthenticationMode.PersonalTailscale)
{
return (PersonalVerification.NotRequired, null);
}

if (client is not { IsPersonalTailscaleAuthentication: true } ||
client.PersonalHandshakeConnectionEpoch is not { } epoch ||
client.PersonalRecoveryScope is not { } scope ||
record.SshTunnel is not null ||
!GatewayPersonalAuthenticationPolicy.TryNormalizeGatewayUrl(record.Url, out var route, out _) ||
!GatewayPersonalAuthenticationPolicy.TryNormalizeGatewayUrl(client.CurrentGatewayUrl, out var connected, out _) ||
route != connected)
return (PersonalVerification.Rejected, null);

try
{
var self = await client.ReadPersonalIdentityAsync(epoch).ConfigureAwait(false);
if (!IsCurrent()) return (PersonalVerification.Stale, null);
if (!GatewayPersonalAuthenticationPolicy.TryGetCanonicalProfileId(self, out var profile))
return (PersonalVerification.Rejected, null);
client.VerifyPersonalIdentity(profile, epoch);
if (!IsCurrent() || client.SessionMutationConnectionEpoch != epoch ||
client.AuthenticatedSigningDeviceId is not { Length: > 0 } deviceId)
return (PersonalVerification.Stale, null);
var lease = new PersonalOperatorLease(record.Id, route, profile, scope, deviceId, generation, epoch);
return (PersonalVerification.Verified, lease);
}
catch (Exception ex) when (ex is InvalidOperationException or TimeoutException or
OperationCanceledException or JsonException)
{
if (!IsCurrent()) return (PersonalVerification.Stale, null);
_diagnostics.Record("identity", "Personal profile verification unavailable", ex.GetType().Name);
return (PersonalVerification.Rejected, null);
}

bool IsCurrent() =>
generation == Interlocked.Read(ref _generation) &&
ReferenceEquals(client, _activeLifecycle?.DataClient) &&
client.PersonalHandshakeConnectionEpoch == epoch &&
client.PersonalRecoveryScope == scope &&
_registry.ActiveGatewayId == record.Id &&
_registry.GetById(record.Id) is { OperatorAuthentication: OperatorAuthenticationMode.PersonalTailscale } current &&
current.SshTunnel is null &&
GatewayPersonalAuthenticationPolicy.TryNormalizeGatewayUrl(current.Url, out var currentRoute, out _) &&
currentRoute == route;
}

public async Task<string?> CreatePersonalBrowserAuthResponseAsync(
string nonce, long signedAt, CancellationToken cancellationToken = default)
{
if (string.IsNullOrWhiteSpace(nonce) || System.Text.Encoding.UTF8.GetByteCount(nonce) > 512 || nonce.Contains('|') ||
nonce.Any(character => char.IsControl(character) || character == '\uFEFF') ||
signedAt <= 0 || Math.Abs((double)new DateTimeOffset(_clock.UtcNow).ToUnixTimeMilliseconds() - signedAt) > 300_000)
return null;

var lease = CurrentPersonalOperatorLease;
var client = _activeLifecycle?.DataClient;
if (lease is null || client is null) return null;
try
{
var self = await client.ReadPersonalIdentityAsync(lease.TransportEpoch).ConfigureAwait(false);
if (cancellationToken.IsCancellationRequested ||
!ReferenceEquals(lease, CurrentPersonalOperatorLease) ||
!ReferenceEquals(client, _activeLifecycle?.DataClient))
return null;
if (!GatewayPersonalAuthenticationPolicy.TryGetCanonicalProfileId(self, out var profile) ||
profile != lease.IdentityProfileId)
{
await RevokePersonalOperatorAsync(lease).ConfigureAwait(false);
return null;
}
var response = client.CreatePersonalBrowserAuthResponse(nonce, signedAt, lease.TransportEpoch);
return ReferenceEquals(lease, CurrentPersonalOperatorLease)
? JsonSerializer.Serialize(response) : null;
}
catch (Exception ex) when (ex is InvalidOperationException or TimeoutException or
OperationCanceledException or JsonException)
{
await RevokePersonalOperatorAsync(lease).ConfigureAwait(false);
return null;
}
}

private async Task RevokePersonalOperatorAsync(PersonalOperatorLease expected)
{
await _transitionSemaphore.WaitAsync().ConfigureAwait(false);
try
{
if (!ReferenceEquals(expected, CurrentPersonalOperatorLease)) return;
_stateMachine.SetOperatorErrorKind(GatewayErrorKind.PersonalIdentityReverificationRequired);
_stateMachine.TryTransition(ConnectionTrigger.WebSocketError,
"Personal identity changed. Reconnect this Gateway.");
_stateMachine.Current = _stateMachine.Current with { PersonalIdentityProfileId = null };
await DisposeActiveClientAsync().ConfigureAwait(false);
EmitStateChanged();
}
finally
{
_transitionSemaphore.Release();
}
}
}
Loading
Loading