Design and Scope Proposal for Authenticated User Environment Isolation

[ladicodes]

Description

This issue proposes a scoped, reviewable design for authenticated user environment isolation in Visdom.
The intent is to align on architecture and rollout before implementation changes. This is not proposing a full multi-tenant access-control system in one step. It is proposing a minimal isolation boundary for authenticated mode so one user does not read or mutate another user’s environments by default.

Problem Statement

Visdom currently supports authentication, but environment state is still effectively global at runtime and on disk. In authenticated deployments, this can create user collision and accidental cross-user visibility.
From a product and platform perspective, this means:

• Authentication establishes identity, but not ownership boundaries.
• Environment names are not safely reusable across different users.
• Server state and persistence semantics are ambiguous in multi-user setups.

Why This Is Needed

For teams using a single shared Visdom server, user-level isolation is a foundational requirement before advanced capabilities such as roles, collaboration policies, or admin controls.

A minimal ownership boundary provides:

• Safer defaults
• Predictable environment semantics
• A clean path for future authorization features

Proposed Scope (Phase 1)

This issue is intentionally constrained to a backend isolation foundation.

Included:

• User-scoped environment identity in authenticated mode
• User-scoped environment listing and retrieval
• User-scoped environment write operations
• Backward compatibility for non-authenticated mode

Not included:

• RBAC or role management
• Shared environments between users
• Admin override tools
• Full migration tooling for historical mixed data sets

Design Proposal

1. Ownership model
   Each authenticated user has a private environment namespace. Environment names remain user-friendly externally, but are separated internally by owner context.

2. Runtime behavior
   In authenticated mode:

• List operations return only environments owned by the current user.
• Read and write operations resolve only within current user ownership.
• WebSocket and REST operations enforce the same ownership boundary.

In non-authenticated mode:

• Existing behavior remains unchanged.

3. Persistence behavior
   Environment persistence is user-scoped in authenticated mode, so two users can use the same environment name without collision.

4. API compatibility
   Client-facing behavior should remain stable where possible:

• Existing clients continue to send environment names normally.
• Server applies ownership scoping internally in authenticated mode.
• Expected Impact Areas
• Auth session handling and identity resolution
• Environment state management and indexing
• REST handlers for environment operations
• WebSocket command handling for environment operations
• Environment persistence and loading logic

Backward Compatibility

No breaking change for deployments without authentication enabled.
Authenticated mode behavior becomes stricter and safer by design.

Risks and Tradeoffs

Architectural surface area is broad (auth, API handlers, storage).
Existing authenticated deployments may currently rely on shared behavior.
Requires explicit communication in release notes to avoid surprise.

Acceptance Criteria

• Authenticated user cannot list another user’s environments.

• Authenticated user cannot read, update, save, fork, or delete another user’s environments.

• Two authenticated users can use the same environment name without collision.

• Non-authenticated behavior remains functionally equivalent to current behavior.

• REST and WebSocket behavior are consistent with each other.

• Rollout Plan

Phase 1: Private per-user isolation boundary (this issue)
Phase 2: Optional explicit sharing model (future issue)
Phase 3: Admin and policy controls (future issue)

Open Questions for Maintainers

• Should authenticated mode isolation be default-on, or behind a feature flag initially?
• Preferred persistence strategy: prefixed naming versus directory partitioning?
• Should a temporary compatibility switch be provided for existing shared authenticated deployments?
• Are there maintainers’ constraints on migration expectations for Phase 1?