Feature/multiuser remote access

.gitignore

@@ -27,6 +27,7 @@ yarn-error.log*
 
 # local env files
 .env*.local
+.env
 
 # vercel
 .vercel

README.md

@@ -45,10 +45,10 @@ It is currently built for active development and lab use. It includes a simple p
 
 ## Compatibility Targets
 
-This dashboard is validated against the current NVIDIA NemoClaw repo and the OpenShell version range declared in NemoClaw's `nemoclaw-blueprint/blueprint.yaml`, not the older April 2026 point releases. Current NemoClaw `main` pins OpenShell exactly to `0.0.71`, so the bundled refresh helper defaults to:
+This dashboard is validated against the current NVIDIA NemoClaw repo and the OpenShell version range declared in NemoClaw's `nemoclaw-blueprint/blueprint.yaml`, not the older April 2026 point releases. NemoClaw `v0.0.71` pins OpenShell exactly to `0.0.71` (native gateway mTLS), so the bundled refresh helper defaults to:
 
 - OpenShell installer release: `v0.0.71` (`OPENSHELL_VERSION=v0.0.71`)
-- NemoClaw source ref: `main` (`NEMOCLAW_INSTALL_REF=main`)
+- NemoClaw source ref: `v0.0.71` (`NEMOCLAW_INSTALL_REF=v0.0.71`) — keeps the Hermes v0.17.0 base (v0.0.69 was the first to bundle it)
 - OpenClaw base-image build target: `2026.5.27` (`OPENCLAW_VERSION=2026.5.27`) unless overridden
 
 Runtime/toolchain versions used during development:
@@ -98,7 +98,7 @@ Install or refresh the locked OpenShell/NemoClaw pair first:
 ./install_versioned_nemoclaw_openshell.sh
 ```
 
-That helper defaults to `OPENSHELL_VERSION=v0.0.71`, `NEMOCLAW_INSTALL_REF=main`, and `OPENCLAW_VERSION=2026.5.27`.
+That helper defaults to `OPENSHELL_VERSION=v0.0.71`, `NEMOCLAW_INSTALL_REF=v0.0.71`, and `OPENCLAW_VERSION=2026.5.27`.
 
 Then install the dashboard from the repository root:
 
@@ -426,6 +426,40 @@ Before exposing this outside a trusted lab network, replace auth with a real ide
 
 ## Troubleshooting
 
+### Gateway down — `openshell sandbox list` returns "Connection refused"
+
+The OpenShell Docker-driver gateway is a background process managed by NemoClaw. If it crashes or is killed, every `openshell sandbox` command fails with:
+
+```
+Error: × transport error
+  ╰─▶ Connection refused (os error 111)
+```
+
+All sandbox containers are also stopped when the gateway shuts down.
+
+**Recovery — one command:**
+
+```bash
+PATH=/root/.nvm/versions/node/v22.22.3/bin:/root/.local/bin:$PATH \
+HOME=/root \
+OPENSHELL_GATEWAY=nemoclaw \
+nemoclaw <any-sandbox-name> recover
+```
+
+Replace `<any-sandbox-name>` with any name from `nemoclaw list` (e.g. `my-first-hermes`). The `recover` sub-command restarts the host gateway as a side-effect. Once it prints `✓ Docker-driver gateway is healthy`, `openshell sandbox list` works again and the sandboxes are back to Ready.
+
+`HOME` must be set — NemoClaw needs it to locate `~/.local/state/nemoclaw/`. It is always set correctly inside the controller's systemd unit, but bare SSH sessions may lack it.
+
+After the gateway is back, individual sandbox Hermes/OpenClaw gateways may need their own recovery if the inner gateway process also died:
+
+```bash
+# repeat for each sandbox that shows degraded health
+PATH=/root/.nvm/versions/node/v22.22.3/bin:/root/.local/bin:$PATH \
+HOME=/root \
+OPENSHELL_GATEWAY=nemoclaw \
+nemoclaw <sandbox-name> recover
+```
+
 Check OpenShell:
 
 ```bash

SANDBOX_ACCESS_CONTROL.md

@@ -0,0 +1,164 @@
+# Per-Sandbox Access Control via OAuth/IDP
+
+Allows enterprise users to authenticate via the internal IDP (OAuth/IDP) and access
+only the sandboxes assigned to them, without needing the operator password.
+
+## Architecture
+
+```
+User browser
+    │
+    ▼
+openshell-controller.ag-*.nemoclaw.dpdns.org  (Traefik, no badger@http)
+    │
+    ▼
+Next.js middleware.ts
+    ├── Operator session cookie → full access (all sandboxes, can create/delete)
+    └── `oauth_session` JWT cookie → read-only, own sandboxes only
+```
+
+The key insight: OAuth/IDP sets a `oauth_session` JWT cookie scoped to
+`.ag-*.nemoclaw.dpdns.org`. Once a user logs into the IDP at
+`idp.ag-*.nemoclaw.dpdns.org`, that cookie is automatically sent to the
+openshell controller on the same domain. The controller validates the JWT
+locally (no network call to OAuth/IDP) and gates per-sandbox access.
+
+## What Was Changed
+
+### 1. Traefik on VPS (`/etc/komodo/stacks/support-799109_setup-stack/config/traefik/rules/resource-overrides.yml`)
+
+Removed `badger@http` from the openshell controller router so Pangolin no longer
+gates the controller. The controller handles all auth itself.
+
+**Before:**
+```yaml
+8-openshell-controller-router-auth:
+    middlewares:
+        - badger@http
+    rule: "Host(`openshell-controller.ag-*.nemoclaw.dpdns.org`)"
+    service: "8-openshell-controller-service@http"
+```
+
+**After:**
+```yaml
+8-openshell-controller-router-auth:
+    rule: "Host(`openshell-controller.ag-*.nemoclaw.dpdns.org`)"
+    service: "8-openshell-controller-service@http"
+```
+
+### 2. `.env.local` — New env vars
+
+```env
+# OAuth IDP Configuration for Enterprise Sandbox Access
+OAUTH_JWT_SECRET=my-secret-key                              # must match the IDP's JWT signing secret
+SANDBOX_ACCESS_USERS=sandbox-name:user@example.com,other-sandbox:other@example.com
+OAUTH_LOGIN_URL=https://idp.ag-*.nemoclaw.dpdns.org/internal/login
+OAUTH_CLIENT_ID=<oauth-client-id>
+OAUTH_CLIENT_SECRET=<oauth-client-secret>
+OAUTH_CALLBACK_URL=https://openshell-controller.ag-*.nemoclaw.dpdns.org/api/auth/callback
+```
+
+> The historical `MCPAUTH_*` and `CF_AUTH_JWT_SECRET` env var names are still
+> read as fallbacks; existing deployments don't need to rename anything to
+> upgrade. Note that `SANDBOX_ACCESS_USERS` is now optional — the access
+> list is preferentially read from `data/sandbox-access.json`, edited via
+> the Security page.
+
+`SANDBOX_ACCESS_USERS` is a comma-separated list of `sandboxName:email` pairs.
+Use the sandbox **name** (not the UUID) — e.g. `my-first-claw:alice@company.com`.
+The name is what appears in the dashboard URL and the instance ID format `sandbox-{port}-{name}`.
+A sandbox can have at most one assigned user. Operator (password login) bypasses
+this check and sees all sandboxes.
+
+### 3. `middleware.ts` — oauth_session validation
+
+Added to the existing Next.js middleware:
+
+- Reads `oauth_session` cookie on every request (falls back to the legacy
+  `CF_Authorization` cookie name for sessions issued by an older controller)
+- Validates the JWT signature (HS256, `OAUTH_JWT_SECRET`)
+- Extracts `email` claim
+- If valid email found:
+  - GET `/api/sandbox/create` → allowed (template list is read-only)
+  - POST `/api/sandbox/create`, POST `/api/sandbox/delete` → 403 (operator only)
+  - Any `/api/sandbox/[sandboxId]/...` or `/api/telemetry/sandbox/[sandboxId]/...` → allowed only if `isUserAuthorizedForSandbox(email, sandboxId)` returns true
+  - Sets `x-forwarded-user` header for downstream handlers
+
+### 4. `app/lib/auth/` — Shared auth library
+
+**`verifyOAuthJWT(token, secret)`** (in `edge.ts` / `node.mjs`) — validates HMAC
+HS256 JWT, returns `{ email, sub, exp, … }` or null.
+
+**`isUserAuthorizedForSandbox(email, sandboxId)`** (in `controlAuth.ts`) —
+consults the file-backed `SandboxAccessStore` and returns true if the email is
+assigned to that sandbox. Sandbox matching is by sandbox name (not ID — the
+sandbox ID from the URL is used as the sandbox name in this context).
+
+The store is `data/sandbox-access.json`; the legacy `SANDBOX_ACCESS_USERS` CSV
+env var is read as a fallback if the file is absent.
+
+## User Flows
+
+### Enterprise user (Alice)
+1. Alice navigates to `https://idp.ag-*.nemoclaw.dpdns.org`
+2. Logs in with email/password via the internal IDP
+3. OAuth/IDP sets `oauth_session` JWT cookie (24h TTL, domain `.ag-*.nemoclaw.dpdns.org`)
+4. Alice navigates to `https://openshell-controller.ag-*.nemoclaw.dpdns.org`
+5. Controller middleware validates cookie → extracts `alice@company.com`
+6. Only sandboxes assigned to `alice@company.com` in `SANDBOX_ACCESS_USERS` are visible/accessible
+7. Create/delete operations return 403
+
+### Operator
+1. Navigates to `https://openshell-controller.ag-*.nemoclaw.dpdns.org`
+2. Logs in with `OPENSHELL_CONTROL_PASSWORD` at `/login`
+3. Gets `openshell_control_session` cookie
+4. Full access — all sandboxes, create/delete enabled
+5. Unaffected by `SANDBOX_ACCESS_USERS`
+
+## Assigning a Sandbox to a User
+
+Use the Security page (operator login required) at
+`https://openshell-controller.ag-*.nemoclaw.dpdns.org/setup-account` to add
+or remove rows. Changes are persisted to `data/sandbox-access.json` and
+take effect immediately — no controller restart needed.
+
+The sandbox name is the short identifier (e.g. `my-first-claw`), not the UUID.
+Find it with `openshell sandbox list` or from the sandbox URL in the dashboard.
+
+For headless / first-run setup the legacy `SANDBOX_ACCESS_USERS` CSV env var
+in `.env.local` is still read as a fallback when the JSON file is absent:
+
+```env
+SANDBOX_ACCESS_USERS=alice-sandbox:alice@company.com,bob-sandbox:bob@company.com
+```
+
+To create a user in the IDP, use the IDP's own admin surface (e.g. the
+Pangolin admin panel at `https://pangolin.ag-*.nemoclaw.dpdns.org`).
+
+## JWT Secret
+
+The OAuth `oauth_session` cookie is signed with HMAC HS256 using a shared
+secret that must match the IDP's signing secret. The controller reads it
+from `OAUTH_JWT_SECRET`, falling back to `MCPAUTH_JWT_SECRET` /
+`CF_AUTH_JWT_SECRET` for backwards compatibility.
+
+If the IDP defaults to a hardcoded development secret (e.g. `"my-secret-key"`),
+override it for production and keep `OAUTH_JWT_SECRET` in sync.
+
+## Future Enhancements
+
+- **Dynamic sandbox assignment**: Add an "Assign to user" field in the sandbox
+  creation wizard (WizardPanel.tsx) that writes to a JSON config file instead of
+  requiring manual `.env.local` edits.
+
+- **User creation in controller**: Add an operator-only UI to create/invite OAuth/IDP
+  users without needing to use the Pangolin admin panel.
+
+- **Stronger JWT secret**: Move OAuth/IDP's `jwtSecret` to an env var and generate
+  a cryptographically random value on first run.
+
+- **Per-sandbox URL**: If direct per-sandbox links are needed (e.g., to email
+  Alice a link directly to her sandbox), add a `/sandbox/[sandboxId]` route that
+  skips the full dashboard and proxies directly to the OpenClaw dashboard for that
+  sandbox. This requires the browser-redirect flow in OAuth/IDP (a new
+  `/auth/browser` endpoint that redirects to login instead of returning 401).

app/api/auth/callback/route.ts

@@ -0,0 +1,114 @@
+import { NextRequest, NextResponse } from "next/server"
+import { mintOAuthSessionJWT, sessionCookieOptionsForRequest } from "@/app/lib/controlAuth"
+import { OAUTH_COOKIE_NAME } from "@/app/lib/auth/policy.mjs"
+
+function base64UrlDecode(value: string) {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=")
+  return Buffer.from(padded, "base64").toString("utf-8")
+}
+
+// Generic OAuth2 / OIDC callback handler. Reads IDP coordinates from the
+// OAUTH_* env vars, falling back to the legacy MCPAUTH_* names so existing
+// deployments don't need to rename anything.
+function getIdpEnv(name: string) {
+  const upper = name.toUpperCase()
+  return (
+    process.env[`OAUTH_${upper}`]
+    || process.env[`MCPAUTH_${upper}`]
+    || ""
+  )
+}
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = request.nextUrl
+  const code = searchParams.get("code")
+  const state = searchParams.get("state") || "/"
+
+  if (!code) {
+    return NextResponse.json({ ok: false, error: "Missing authorization code" }, { status: 400 })
+  }
+
+  const loginUrl = getIdpEnv("LOGIN_URL")
+  const tokenUrl = `${loginUrl ? loginUrl.replace("/authorize", "") : "http://localhost:11000"}/token`
+  const clientId = getIdpEnv("CLIENT_ID")
+  const redirectUri = getIdpEnv("CALLBACK_URL")
+
+  try {
+    // Exchange authorization code for token
+    const formData = new URLSearchParams()
+    formData.append("grant_type", "authorization_code")
+    formData.append("code", code)
+    formData.append("redirect_uri", redirectUri)
+    formData.append("client_id", clientId)
+
+    const response = await fetch(tokenUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: formData.toString(),
+    })
+
+    const data = await response.json()
+    if (!response.ok) {
+      return NextResponse.json({ ok: false, error: data.error_description || "Token exchange failed" }, { status: response.status })
+    }
+
+    // Standard OIDC: extract email from the id_token JWT payload
+    const idToken = data.id_token as string | undefined
+    const accessToken = data.access_token as string | undefined
+
+    let userEmail: string | null = null
+    let scopes: string[] = []
+
+    if (idToken) {
+      try {
+        const parts = idToken.split(".")
+        if (parts.length >= 2) {
+          const payload = JSON.parse(base64UrlDecode(parts[1]))
+          userEmail = payload.email || payload.sub || null
+        }
+      } catch {
+        // fall through to access token parsing
+      }
+    }
+
+    // Fallback: parse scopes from access token payload
+    if (accessToken) {
+      try {
+        const parts = accessToken.split(".")
+        if (parts.length >= 2) {
+          const payload = JSON.parse(base64UrlDecode(parts[1]))
+          if (!userEmail && payload.email) userEmail = payload.email
+          if (Array.isArray(payload.scopes)) scopes = payload.scopes
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    if (!userEmail) {
+      return NextResponse.json({ ok: false, error: "User identity could not be retrieved from provider" }, { status: 500 })
+    }
+
+    // Mint the OAuth session JWT cookie using our shared secret.
+    const oauthToken = await mintOAuthSessionJWT(userEmail, scopes)
+
+    // Reconstruct target URL using the incoming Host header to ensure we
+    // redirect to the correct domain/port (e.g. localhost:3000 instead of
+    // 0.0.0.0:3000).
+    const host = request.headers.get("host") || "localhost:3000"
+    const protocol = request.headers.get("x-forwarded-proto") || request.nextUrl.protocol || "http"
+    const cleanProtocol = protocol.endsWith(":") ? protocol.slice(0, -1) : protocol
+    const baseUrl = `${cleanProtocol}://${host}`
+    const targetUrl = new URL(state.startsWith("/") ? state : "/", baseUrl)
+    const redirectResponse = NextResponse.redirect(targetUrl)
+    redirectResponse.cookies.set(OAUTH_COOKIE_NAME, oauthToken, sessionCookieOptionsForRequest(request))
+
+    return redirectResponse
+  } catch (error) {
+    console.error("OAuth callback error:", error)
+    return NextResponse.json(
+      { ok: false, error: error instanceof Error ? error.message : "Internal server error during callback processing" },
+      { status: 500 },
+    )
+  }
+}

app/api/auth/login/route.ts

@@ -37,3 +37,36 @@ export async function POST(request: NextRequest) {
   response.cookies.set(settings.cookieName, await createSessionCookieValue(), sessionCookieOptionsForRequest(request))
   return response
 }
+
+// Read IDP coordinates from OAUTH_* env vars, falling back to the legacy
+// MCPAUTH_* names so existing .env.local files keep working.
+function idpEnv(name: string) {
+  const upper = name.toUpperCase()
+  return process.env[`OAUTH_${upper}`] || process.env[`MCPAUTH_${upper}`] || ""
+}
+
+export async function GET() {
+  const loginBase = idpEnv("LOGIN_URL")
+  const clientId = idpEnv("CLIENT_ID")
+  const redirectUri = idpEnv("CALLBACK_URL")
+
+  let oauthLoginUrl: string | null = null
+  if (loginBase && clientId && redirectUri) {
+    const params = new URLSearchParams({
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      response_type: "code",
+      scope: "openid email",
+    })
+    oauthLoginUrl = `${loginBase}?${params.toString()}`
+  }
+
+  // Returns the URL under both names for one release: the new `oauthLoginUrl`
+  // and the historical `mcpAuthLoginUrl`, so a stale cached login page from
+  // a previous deploy keeps working.
+  return NextResponse.json({
+    oauthLoginUrl,
+    mcpAuthLoginUrl: oauthLoginUrl,
+  })
+}
+