[devSejung]

What Problem This Solves

PlatformClaw needs employee-authenticated browser users to share one OpenClaw Gateway without exposing operator credentials or allowing access across personal agents and sessions. The browser ingress must remain outside OpenClaw core so downstream behavior can continue tracking upstream.

Why This Change Was Made

This adds one PlatformClaw BFF runtime containing one shared BrowserGatewayProxy, one private Gateway client, and one HTTP/WebSocket listener. Browser connections carry only opaque session tokens; the shared policy layer resolves user, personal-agent, and session access for each request and filters results and events before returning them.

The listener uses the upstream Gateway protocol and public gateway-client package, applies exact-origin checks, bounded login and request queues, closes browser sockets when the private Gateway disconnects, and projects a browser-safe hello without private operator metadata. A full-profile local employee-auth mock and deployment documentation are included.

This is a stacked PR based on feature/web-gateway-proxy (#9). After #9 merges, this PR must be rebased or retargeted to main before merge.

User Impact

Employee browser users can authenticate through the PlatformClaw control plane and connect to their automatically provisioned personal agent through the existing Control UI Gateway protocol. Users cannot select or observe another user's agent or sessions. Deployment wiring, reverse-proxy configuration, and the Control UI login bootstrap remain follow-up work.

AI-assisted: implementation and review were performed with Codex; the author understands the resulting architecture and policy boundaries.

Evidence

• oxlint packages/platformclaw-control-plane/src: passed.
• Control-plane test suite: 91 passed, 1 skipped.
• Focused Web ingress lifecycle tests cover origin rejection, session revocation, queue bounds, disconnect resynchronization, and subscription cleanup.
• tsdown package build with declarations: passed.
• Max-lines suppression ratchet and git diff --check: passed.
• Autoreview findings for WebSocket error handling, connect/close races, request queue bounds, private Gateway disconnects, and state-version projection were accepted and fixed.
• Local package tsgo is blocked only by three existing packages/net-policy/src/ip.ts dependency-type errors in this linked worktree; the same feat(platformclaw): proxy browser gateway access #9 control-plane package typecheck passed before the ingress rebase.

Agent Transcript

Redacted Codex session transcript

[user]
Implement the next feature using the repository rules and a plan. Keep upstream updates in mind, use commit-sized changes, and push completed work.

[assistant]
Selected the existing public Gateway client/protocol seams. Planned one PlatformClaw BFF runtime outside OpenClaw core: employee auth, persistent browser sessions, one shared policy proxy, one private Gateway client, and an HTTP/WebSocket listener.

[user]
Clarified that the approved topology is a single BFF, a single BrowserGatewayProxy policy layer, and a single Gateway client. Users differ only by browser connection and session/agent access context.

[assistant]
Verified the implementation constructs each shared object once. Corrected documentation wording and added an explicit process-wide singleton invariant. Per-request access is resolved from the opaque browser session token.

[tool summary]
Focused tests, package-wide lint, max-lines ratchet, declaration build, mock-auth compile, and diff checks were run. A stacked branch was rebased onto the latest #9 branch.

[assistant]
Autoreview findings were accepted and fixed: WebSocket error handling, connect/close subscription cleanup, bounded inbound request queues, cancellation after disconnect, downstream resynchronization on private Gateway disconnect, and synthetic browser-safe state versions.

[tool summary]
Final control-plane proof: 91 tests passed, 1 skipped; package-wide oxlint and package build passed.

[github-actions]

Dependency Guard

This PR changes dependency-related files. Maintainers should confirm these changes are intentional.

Changed files:

• packages/platformclaw-control-plane/package.json
• pnpm-lock.yaml

Maintainer follow-up:

• Review whether the dependency changes are intentional.
• Inspect resolved package deltas when lockfile, shrinkwrap, or workspace dependency policy changes are present.
• Treat package-lock.json and npm-shrinkwrap.json diffs as security-review surfaces.
• Run pnpm deps:changes:report -- --base-ref origin/main --markdown /tmp/dependency-changes.md --json /tmp/dependency-changes.json locally for detailed release-style evidence.

[github-actions]

Dependency graph changes noted

This PR includes dependency graph changes. The dependency guard is informational because the PR author is a repository admin or a member of @openclaw/openclaw-secops.

• Current SHA: cc784e1b7b2ff1c4ccb8ebc57a33296065ca3b76
• Trusted actor: @devSejung
• Trusted role: pull request author; repository admin

Security review is still recommended before merge when the dependency graph change is intentional.