Skip to content

Commit 59b8a11

Browse files
authored
feat(openclaw-id): add the tunnel transport, OpenClaw ID sign-in and relayed-device Gateway auth (#192345)
* feat(openclaw-id): add the tunnel transport, OpenClaw ID sign-in and relayed-device Gateway auth * fix(openclaw-id): an HTTP request from a removed tunnel device does nothing more A relayed HTTP request kept the role it was admitted with, so a POST /tools/invoke waiting in a before-tool-call hook still ran its tool after the device was removed. Every authority check on a relayed HTTP request now asks the membership authority whether the device is still admitted with the same kind, account and role; a removal, a role change or OpenClaw ID turning off fails the next check, including the last one before the tool runs. * fix(openclaw-id): keep durable work bound to the device that authorized it Scheduled jobs, condition scripts, script payloads, shell commands, stream watchers and HTTP execution created over the tunnel now keep the original device's authority (claw, root, listing seq, owner device) with the job. Every run, restart and recovery rechecks it against the local membership record and cancels the work when the device is removed, re-approved, its role changes or the switch turns off. Recovery waits only for the local record. - WebSocket and run authority follow current membership; HTTP and WebSocket members use the canonical OpenClaw ID profile. - Stream watchers keep the process grant apart from the payload grant. - Another operator's timing edits keep the original requester; they never promote a member's job to the editor. - Restored Control UI continuations are owner-only only under admin scope. - A stopped Gateway ends local authority even during a cold first load. * test(openclaw-id): bound the ingress test WebSocket server payload * fix(openclaw-id): keep a device's scheduled grant when another device edits its timing * fix(openclaw-id): publish the token-binding writer before the tunnel admits devices * fix(gateway): keep the tunnel principal on plugin HTTP route clients * fix(gateway): never auto-approve a tunnel node by its synthetic address * test(openclaw-id): check the tunnel child exits on its own * fix(openclaw-id): keep the long-path ingress socket under the OpenClaw temp root * refactor(cron): break the stream operator source import cycle * refactor(openclaw-id): break the sign-out type cycle with the service * refactor(gateway): give the stream job scope key its own export name * fix(scripts): narrow operator source variants in the cron context replay * chore(test): allocate the OpenClaw ID tunnel regression test lines * test(gateway): give the deferred profile fixture a real auth result * test(gateway): keep real SSH verify exports in the tunnel node mock * fix(openclaw-id): let the tunnel child exit without forcing it The child now records its exit status, closes the ingress server and iroh endpoint, and releases the IPC channel so Node exits on its own, as the no-forced-process-exit guard requires (nodejs/node#64274). It relies on the iroh binding ending HomeRelayWatcher.next() when the endpoint closes (#193995). * fix(openclaw-id): require the iroh relay watcher so the tunnel child can exit A binding without HomeRelayWatcher made the child fall back to endpoint.online(), which iroh leaves pending after the endpoint closes. That pending native call kept a stopped child alive, so after the Gateway died it could hold its endpoint key indefinitely. The loader now refuses such a binding as unavailable. * fix(openclaw-id): zero the endpoint key when binding the endpoint fails * test(openclaw-id): mock node:module without spreading its class export * chore(test): allocate the OpenClaw ID tunnel test lines CI measures * fix(openclaw-id): keep the inactivity window helper private to the owner lifecycle service.ts no longer imports inactivityWindows after the owner-expiry timer moved into owner-lifecycle.ts, so the export had no consumer and failed the unused-export scan.
1 parent 53068bc commit 59b8a11

162 files changed

Lines changed: 10071 additions & 689 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎config/knip.config.ts‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1203,15 +1203,14 @@ const config = {
12031203
"src/agents/model-auth-runtime.ts": ["nsExports"],
12041204
"src/agents/model-auth-runtime-shared.ts": ["nsExports"],
12051205
"src/agents/prepared-model-runtime.ts": ["nsExports"],
1206-
// OpenClaw ID focused tests drive retry timers, mailbox handling and connection custody
1207-
// through these exports; the full-tree scan still audits those tests.
1206+
// OpenClaw ID focused tests drive retry timers, mailbox handling, connection custody and
1207+
// tunnel supervision through these exports; the full-tree scan still audits those tests.
12081208
"src/gateway/openclaw-id/mailbox-reader.ts": ["exports"],
12091209
"src/gateway/openclaw-id/publication-retry.ts": ["exports"],
12101210
"src/gateway/openclaw-id/tunnel-connections.ts": ["exports"],
1211-
// The stacked OpenClaw ID tunnel change is the first production importer of these
1212-
// exports, which focused tests cover now; drop each entry with that importer.
1213-
"src/gateway/openclaw-id/device-token-binding.ts": ["exports"],
1214-
"src/gateway/openclaw-id/tunnel-child/keyfile.ts": ["exports"],
1211+
"src/gateway/openclaw-id/tunnel-principal.ts": ["types"],
1212+
"src/gateway/openclaw-id/tunnel-runtime.ts": ["exports"],
1213+
"src/gateway/openclaw-id/tunnel-supervisor.ts": ["exports", "types"],
12151214
},
12161215
workspaces: {
12171216
".": {
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# OpenClaw ID tunnel and sign-in: new tests for the tunnel child, supervisor, ingress listener,
2+
# tunnel API, OIDC sign-in and the Gateway auth boundary for relayed devices, including saved
3+
# token bindings refused on HTTP after a start with the switch off, and HTTP requests that lose
4+
# authority when their device is removed or its role changes. No existing tests replaced.
5+
# Includes canonical OCID HTTP/WS profile, live admission/run-role and ambient-origin regressions.
6+
# Includes peer-bound restart, native/sandbox streams, HTTP roles, real condition effects and script-source retention.
7+
# Includes native-command source, Gateway-stop lifetime, cross-operator control and standing-ceiling regressions.
8+
# Includes same-profile device timing edits, binding-writer start order, plugin-route principal, child exit, tunnel node-pairing and binding-loader regressions.
9+
5167

‎docs/gateway/remote.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,37 @@ the Gateway port does not forward portals. Use [managed private Serve or wildcar
3232
portal ingress](/gateway/portals#remote-access); the browser and application must
3333
use the service's returned portal URLs without replacing their host or port.
3434

35+
## OpenClaw ID alongside existing access
36+
37+
OpenClaw ID remote access is an additional entrance, not a replacement for
38+
Tailscale, Cloudflare Access, or the Gateway's token/password. Each entrance
39+
keeps its own authentication and permissions:
40+
41+
- OpenClaw ID tunnel requests use the admitted device's owner, operator, or
42+
viewer role. Proxy identity headers and other Gateway credentials cannot
43+
widen that role. Viewers remain read-only; members cannot manage People.
44+
- Tailscale Serve and Cloudflare Access users keep their existing Gateway
45+
permissions. Arriving through a proxy on `127.0.0.1` does not make them the
46+
local machine owner. A direct tailnet connection is remote too.
47+
- Turning on remote access requires an authenticated direct-loopback
48+
connection without proxy or identity headers. People, owner
49+
devices, and invites are available to that local operator or an active
50+
OpenClaw ID owner device, not merely to any proxy-authenticated administrator.
51+
Recovery-kit secrets are generated and exported in the browser, not downloaded
52+
from the Gateway.
53+
54+
**Removing someone in People revokes their OpenClaw ID access only.** It closes
55+
their OpenClaw ID connections, cancels their active or queued runs from those
56+
connections, and revokes the associated device tokens. It does not remove them
57+
from your tailnet or Cloudflare Access policy, or rotate a shared Gateway token
58+
or password. Revoke those independent permissions separately if they must lose
59+
all access. Likewise, someone independently given a stronger credential can
60+
still use its permissions through its own entrance.
61+
62+
A headerless SSH port forward is indistinguishable from a local process to the
63+
Gateway. Treat SSH access to the host as local-machine authority; do not expose
64+
an unmarked TCP forward to untrusted users.
65+
3566
## Command flow (what runs where)
3667

3768
One Gateway owns state and channels; nodes are peripherals. Example (Telegram message routed to a node tool):

‎docs/gateway/trusted-proxy-auth.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,14 @@ read_when:
9999

100100
**Forwarded-header evidence overrides loopback locality for local-direct fallback.** If a request arrives on loopback but carries a `Forwarded`, any `X-Forwarded-*`, or `X-Real-IP` header, that evidence disqualifies it from local-direct password fallback and device-identity gating, even though it still fails trusted-proxy auth as loopback.
101101

102+
The same restriction always applies to Tailscale identity headers. While OpenClaw ID
103+
is on (`gateway.openclawId.enabled`), it also applies to Cloudflare Access identity
104+
headers, `Remote-User`, `X-Remote-User`, and the configured `userHeader` or
105+
`requiredHeaders`: an identity-only request without a usable forwarded client
106+
address is rejected, not treated as the local operator. This protects OpenClaw
107+
ID's local-only linking; see [access coexistence](/gateway/remote#openclaw-id-alongside-existing-access).
108+
With OpenClaw ID off, those headers do not change loopback locality.
109+
102110
`allowLoopback` trusts local processes on the Gateway host to the same degree as the reverse proxy. Enable it only when the Gateway is still firewalled from direct remote access and the local proxy strips or overwrites client-supplied identity headers.
103111

104112
Internal Gateway clients that do not travel through the reverse proxy should use `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, not trusted-proxy identity headers. `openclaw gateway status` selects this local password automatically when no `--url` override is supplied, including with `--json`. For browser access, omit `gateway.controlUi.allowedOrigins` to use `gateway.publicOrigin` as the default, or configure an explicit list that overrides it.

‎scripts/dev/cron-context-replay.mts‎

Lines changed: 59 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -226,49 +226,75 @@ function anonymizeOperatorSource(
226226
return { source: { version: 1 }, executionRevision: "execution-1" } as never;
227227
}
228228
const { snapshot } = source;
229+
const principal = snapshot.openclawIdPrincipal;
229230
const fixtureBase = {
230231
profileId: "profile-1",
232+
// The builder reads the device kind and member role; identities are replaced.
233+
...(principal
234+
? {
235+
openclawIdPrincipal: {
236+
...(principal.kind === "member"
237+
? { kind: principal.kind, accountId: "account-1", role: principal.role }
238+
: { kind: principal.kind }),
239+
peerKey: `iroh:${"00".repeat(32)}`,
240+
authority: {
241+
clawId: "claw-1",
242+
rootPub: "root-1",
243+
listedSeq: 1,
244+
...(principal.authority.ownerDevice ? { ownerDevice: "owner-device-1" } : {}),
245+
},
246+
},
247+
}
248+
: {}),
231249
scopes: [...snapshot.scopes],
232250
assignedRole: snapshot.assignedRole === null ? null : "role",
233251
githubLogin: null,
234252
grant: null,
235253
aliasBindingIds: [],
236254
};
255+
const fixtureSnapshot =
256+
snapshot.sourceIngress === "principal"
257+
? {
258+
...fixtureBase,
259+
sourceIngress: "principal" as const,
260+
ingress: {
261+
pluginId: "plugin-1",
262+
audienceId: "audience-1",
263+
recoveryId: "issuance-1",
264+
},
265+
controlUiAdmin: false as const,
266+
localOperator: false as const,
267+
}
268+
: {
269+
...fixtureBase,
270+
authPolicy: {
271+
generation: "" as const,
272+
grantGeneration: "generation",
273+
role: "operator" as const,
274+
authMethod: snapshot.authPolicy.authMethod,
275+
},
276+
controlUiAdmin: snapshot.controlUiAdmin,
277+
localOperator: snapshot.localOperator,
278+
sourceIngress: snapshot.sourceIngress,
279+
};
280+
const shared = {
281+
version: 1 as const,
282+
agentId: source.agentId === agentId ? "main" : "other",
283+
sourceRunId: "source-run",
284+
snapshot: fixtureSnapshot,
285+
};
237286
return {
238287
executionRevision: "execution-1",
239-
source: {
240-
version: 1,
241-
agentId: source.agentId === agentId ? "main" : "other",
242-
sessionKey: key(source.sessionKey),
243-
sessionId: "parent-session",
244-
...(source.lifecycleRevision ? { lifecycleRevision: "rev-1" } : {}),
245-
sourceRunId: "source-run",
246-
snapshot:
247-
snapshot.sourceIngress === "principal"
248-
? {
249-
...fixtureBase,
250-
sourceIngress: "principal",
251-
ingress: {
252-
pluginId: "plugin-1",
253-
audienceId: "audience-1",
254-
recoveryId: "issuance-1",
255-
},
256-
controlUiAdmin: false,
257-
localOperator: false,
258-
}
259-
: {
260-
...fixtureBase,
261-
authPolicy: {
262-
generation: "",
263-
grantGeneration: "generation",
264-
role: "operator",
265-
authMethod: snapshot.authPolicy.authMethod,
266-
},
267-
controlUiAdmin: snapshot.controlUiAdmin,
268-
localOperator: snapshot.localOperator,
269-
sourceIngress: snapshot.sourceIngress,
270-
},
271-
},
288+
// A device-bound source has no parent conversation to relate.
289+
source:
290+
source.kind === "gateway"
291+
? { ...shared, kind: "gateway" }
292+
: {
293+
...shared,
294+
sessionKey: key(source.sessionKey),
295+
sessionId: "parent-session",
296+
...(source.lifecycleRevision ? { lifecycleRevision: "rev-1" } : {}),
297+
},
272298
};
273299
}
274300

‎src/agents/admitted-run-context.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,9 @@ export function createAdmittedRunOperatorAuthority(
8282
const readRoleFacts = source.readCurrentRoleFacts;
8383
const authority = Object.freeze({
8484
profileId: source.profileId,
85+
openclawIdPrincipal: source.openclawIdPrincipal
86+
? freezeJsonSnapshot(structuredClone(source.openclawIdPrincipal))
87+
: undefined,
8588
recoverySnapshot: source.recoverySnapshot
8689
? freezeJsonSnapshot(structuredClone(source.recoverySnapshot))
8790
: undefined,

‎src/agents/admitted-run-operator-authority.types.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ import type { PreparedOperatorModelPolicy } from "./operator-model-policy.types.
55

66
export type AdmittedRunOperatorAuthority = Readonly<{
77
profileId: string;
8+
/** Original OCID device and listing; profile attribution never replaces this source. */
9+
openclawIdPrincipal?: import("../gateway/openclaw-id/tunnel-principal.js").OpenClawIdTunnelPrincipal;
810
/** Host-captured original input; claim/occurrence owners revalidate it for continuations. */
911
recoverySnapshot?: import("../gateway/operator-run-recovery-source.codec.js").OperatorRunRecoverySnapshot;
1012
/** Existing immutable policy and link; accepted-input owners may retain them for recovery. */
@@ -27,6 +29,8 @@ export type AdmittedRunOperatorAuthority = Readonly<{
2729
readCurrentRoleFacts?: (this: void) => Readonly<{
2830
assignedRole: string | null;
2931
githubLogin?: string | null;
32+
/** Non-named source policy, checked by the original authority before each read. */
33+
policy?: GatewayOperatorRoleDefinition;
3034
}>;
3135
/** Prepared role permissions; source-policy changes revoke the owning authority. */
3236
rolePolicy?: Readonly<{

‎src/agents/operator-run-recovery-source.ts‎

Lines changed: 54 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -15,51 +15,75 @@ import {
1515

1616
type ScheduledOperatorSourceParams = {
1717
authority?: AdmittedRunOperatorAuthority;
18-
entry: InternalSessionEntry;
18+
entry?: InternalSessionEntry;
1919
agentId: string;
20-
sessionKey: string;
20+
sessionKey?: string;
2121
sourceRunId: string;
22+
/** A direct human reauthorizing an already source-bound job supplies a real Gateway snapshot. */
23+
independent?: boolean;
2224
};
2325

24-
/** Cron occurrences retain the creator turn's authenticated grant for later revalidation. */
26+
/** Retains authenticated permission independently of where the automation will execute. */
2527
export function captureScheduledOperatorSource(
2628
params: ScheduledOperatorSourceParams,
2729
): RestartRecoveryOperatorSource | undefined {
2830
const { authority, entry, sessionKey } = params;
29-
if (
30-
!authority ||
31-
entry.incognito ||
32-
entry.acp ||
33-
entry.pluginOwnerId ||
34-
entry.cronRunContinuation ||
35-
isIncognitoSessionKey(sessionKey) ||
36-
isCronSessionKey(sessionKey) ||
37-
isAcpSessionKey(sessionKey) ||
38-
isAgentHarnessSessionKey(sessionKey)
39-
) {
31+
if (!authority) {
4032
return undefined;
4133
}
4234
assertAdmittedRunOperatorAuthority(authority);
4335
authority.assertCurrent();
36+
const independent = Boolean(authority.openclawIdPrincipal || params.independent);
37+
const unavailable = () => {
38+
if (independent) {
39+
throw new Error(
40+
"The original authenticated authority could not be retained for this automation.",
41+
);
42+
}
43+
return undefined;
44+
};
4445
const snapshot = authority.recoverySnapshot;
4546
if (!snapshot) {
46-
return undefined;
47+
return unavailable();
48+
}
49+
let source: RestartRecoveryOperatorSource;
50+
if (independent) {
51+
// No conversation IDs or contents are needed to retain the authenticated device grant.
52+
source = {
53+
version: 1,
54+
kind: "gateway",
55+
agentId: params.agentId,
56+
sourceRunId: params.sourceRunId,
57+
snapshot: { ...snapshot, scopes: intersectOperatorScopes(snapshot.scopes, authority.scopes) },
58+
};
59+
} else {
60+
if (
61+
!entry ||
62+
!sessionKey ||
63+
entry.incognito ||
64+
entry.acp ||
65+
entry.pluginOwnerId ||
66+
entry.cronRunContinuation ||
67+
isIncognitoSessionKey(sessionKey) ||
68+
isCronSessionKey(sessionKey) ||
69+
isAcpSessionKey(sessionKey) ||
70+
isAgentHarnessSessionKey(sessionKey)
71+
) {
72+
return undefined;
73+
}
74+
source = {
75+
version: 1,
76+
agentId: params.agentId,
77+
sessionKey,
78+
sessionId: entry.sessionId,
79+
...(entry.lifecycleRevision !== undefined
80+
? { lifecycleRevision: entry.lifecycleRevision }
81+
: {}),
82+
sourceRunId: params.sourceRunId,
83+
snapshot: { ...snapshot, scopes: intersectOperatorScopes(snapshot.scopes, authority.scopes) },
84+
};
4785
}
48-
const source: RestartRecoveryOperatorSource = {
49-
version: 1,
50-
agentId: params.agentId,
51-
sessionKey,
52-
sessionId: entry.sessionId,
53-
...(entry.lifecycleRevision !== undefined
54-
? { lifecycleRevision: entry.lifecycleRevision }
55-
: {}),
56-
sourceRunId: params.sourceRunId,
57-
snapshot: {
58-
...snapshot,
59-
scopes: intersectOperatorScopes(snapshot.scopes, authority.scopes),
60-
},
61-
};
6286
return Buffer.byteLength(JSON.stringify(source), "utf8") <= 65_536
6387
? freezeJsonSnapshot(source)
64-
: undefined;
88+
: unavailable();
6589
}

‎src/agents/sandbox/stream-context.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,14 @@ export function captureCronStreamSandboxTarget(params: {
5555
throw new Error("This sandbox's original access cannot be resumed for a persistent stream.");
5656
}
5757
const roleFacts = authority.readCurrentRoleFacts();
58+
if (authority.openclawIdPrincipal && !authority.openclawIdPrincipal.authority) {
59+
throw new Error("This source's original OpenClaw ID listing is unavailable.");
60+
}
5861
return {
5962
profileId: authority.profileId,
63+
...(authority.openclawIdPrincipal
64+
? { openclawIdPrincipal: authority.openclawIdPrincipal }
65+
: {}),
6066
scopes: [...authority.scopes],
6167
assignedRole: roleFacts.assignedRole,
6268
githubLogin: roleFacts.githubLogin ?? null,

‎src/cron/execution-context-admission.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -289,7 +289,7 @@ describe("admitScheduledOccurrence", () => {
289289
const runSessionKey = PARENT_KEY;
290290
expect(occurrence.mint({ ...RUN, runSessionKey }).result).toMatchObject({
291291
status: "ready",
292-
facts: { authority: { owner: false, basis: "none" } },
292+
facts: { authority: { owner: false, basis: "operator-source" } },
293293
});
294294
expect(
295295
occurrence.mint({ ...RUN, runSessionKey, operatorAuthority: RESTORED_OPERATOR }).result,

0 commit comments

Comments
 (0)