Walkthrough

This PR hardens v2 API security by adding a user_id foreign key to the interactive_sessions table (with a backward-compatible migration), introducing enforce_workspace_allowlist() to restrict workspace paths to per-user subdirectories, applying that enforcement to the session-create and workspace-init endpoints, and adding fail-closed session ownership checks in both WebSocket handlers.

Changes

Session ownership and workspace allowlist enforcement

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant create_session
    participant enforce_workspace_allowlist
    participant InteractiveSessionRepository

    rect rgba(100, 149, 237, 0.5)
        note over Client,InteractiveSessionRepository: Session Creation with Allowlist
        Client->>create_session: POST /api/v2/sessions (workspace_path, JWT)
        create_session->>create_session: require_auth → user_id
        create_session->>enforce_workspace_allowlist: Path(workspace_path), user_id
        alt path outside allowlist or missing WORKSPACE_ROOT/user_id
            enforce_workspace_allowlist-->>Client: HTTP 403 / 500
        else path accepted
            enforce_workspace_allowlist-->>create_session: resolved_path
            create_session->>InteractiveSessionRepository: repo.create(resolved_path, user_id=user_id)
            InteractiveSessionRepository-->>create_session: session record
            create_session-->>Client: 201 Created
        end
    end

sequenceDiagram
    participant WSClient
    participant session_chat_ws
    participant _authenticate_websocket
    participant interactive_sessions_repo

    rect rgba(144, 238, 144, 0.5)
        note over WSClient,interactive_sessions_repo: WebSocket Ownership Check
        WSClient->>session_chat_ws: WS connect (session_id)
        session_chat_ws->>_authenticate_websocket: authenticate
        _authenticate_websocket-->>session_chat_ws: authenticated=True, user_id=42
        session_chat_ws->>interactive_sessions_repo: get(session_id)
        interactive_sessions_repo-->>session_chat_ws: session (session_user_id=99)
        alt session_user_id missing or != user_id
            session_chat_ws-->>WSClient: close(1008, "Forbidden: session belongs to another user")
        else ownership confirmed
            session_chat_ws-->>WSClient: WS accepted, stream begins
        end
    end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related issues

• [P7.0.1] Workspace path allowlist — prevent authenticated cross-tenant RCE (M1) #655: This PR directly implements the security hardening described in issue #655, including workspace path allowlisting via enforce_workspace_allowlist(), binding sessions to authenticated users via user_id, enforcing auth on v2 endpoints, and adding fail-closed ownership checks in WebSocket handlers.

Possibly related PRs

• frankbria/codeframe#510: Both PRs modify the /api/v2/sessions creation flow; #510 originally introduced the router and session CRUD, while this PR adds auth, allowlist enforcement, and user_id persistence to the same create_session endpoint and repository insert.
• frankbria/codeframe#511: Both PRs modify session_chat_ws.py's WebSocket authentication flow; #511 introduced the auth scaffolding that this PR extends by capturing and enforcing user_id for session ownership.

Poem

🐰 Hop hop, the rabbit checks the gate,
No stray paths shall infiltrate!
Each user gets their cozy den,
Wrong owners? Close the socket—when!
The workspace roots are locked up tight,
user_id guards through day and night. 🔒

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Security Fix Review — Workspace Path Allowlist + Session Ownership (#655)

First review — no prior comments to reconcile.

This PR patches a genuine, high-severity vulnerability: an authenticated user could supply an arbitrary workspace_path and reach any host directory through REST endpoints and the terminal shell cwd. The core approach is sound.

What's Working Well

• Path resolution before containment: path.resolve() inside enforce_workspace_allowlist collapses ../ escapes before is_relative_to() — the right order of operations.
• Fail-closed in hosted mode: Raising 500 when WORKSPACE_ROOT is unset in hosted mode is the correct security posture.
• Per-user subdir confinement: Narrowing roots to <root>/<user_id> in hosted mode is a clean, stateless confinement strategy.
• Terminal ownership fix (terminal_ws.py): Changing session_user_id is not None and to session_user_id is None or correctly closes the gap where pre-[P7.0.1] Workspace path allowlist — prevent authenticated cross-tenant RCE (M1) #655 migrated sessions (NULL owner) could be hijacked by any authenticated user. This was dead code before — good catch.
• Schema migration: The idempotent ALTER TABLE is the right pattern for existing databases.
• Test coverage: Covers inside/outside/traversal, hosted mandatory-root, per-user confinement, session-create validation.

Issues

1. Circular import via local import (fragile)

is_hosted_mode is imported lazily on every call inside enforce_workspace_allowlist to avoid server.py -> dependencies.py -> server.py. The right fix is to extract is_hosted_mode into a standalone config helper (e.g. codeframe/lib/deployment.py or codeframe/ui/config.py) that simply reads CODEFRAME_DEPLOYMENT_MODE. A function that reads an env var does not need to live in the server module, and a lazy import will silently fail if the import graph ever changes.

2. Type inconsistency on the auth parameter

workspace_v2.py declares auth: dict while interactive_sessions_v2.py and dependencies.py use Dict[str, Any]. Should be consistent — use Dict[str, Any] or the modern dict[str, Any] everywhere.

3. WebSocket close codes are inconsistent

terminal_ws.py closes with 4003 (custom), session_chat_ws.py closes with 1008 (standard RFC 6455 policy violation). Same enforcement reason should use the same code. 1008 is the semantically appropriate choice for both.

4. test_chat_ws_ownership_mismatch_closes catches bare Exception

with pytest.raises(Exception):
    with client.websocket_connect("/ws/sessions/s1/chat?token=x"):
        pass

This passes if the server raises any exception including an unrelated internal error. Asserting the specific WebSocketDisconnect reason or close code would prevent false positives masking regressions.

Minor Notes

• # ponytail: annotation: Non-standard prefix inside enforce_workspace_allowlist. Future readers won't know what it means — rewrite as a plain TODO or inline comment.
• test_traversal_escape_rejected: The comment says "starts under it" — could be clearer that {base}/../proj resolves to a sibling of tmp_path, outside the allowed root.
• Known gap in [P7.0.2] Hosted multi-tenancy hardening: session REST owner-scoping + TOCTOU path isolation #704 (session REST list/get/delete not owner-scoped): Good call scoping it out — adding that here would expand blast radius without established test coverage.

Summary

The vulnerability fix is correct and well-structured. Issues 2–4 are minor polish; item 1 (circular import) is the only thing worth resolving before merge since lazy imports are silent failure modes in future refactors.

Verdict: Approve pending item 1.

Thanks @coderabbitai — addressed in 95c2a04:

• Assert specific WebSocketDisconnect(1008) (test_session_chat_ws.py): applied — now asserts the policy-violation close code instead of a broad Exception.
• SQLite ALTER TABLE ADD COLUMN doesn't enforce REFERENCES (schema_manager.py): acknowledged, no change. SQLite doesn't enforce FKs without PRAGMA foreign_keys=ON, and the column functions correctly regardless; the REFERENCES … ON DELETE SET NULL is declarative metadata consistent with the table's CREATE form. Hardening FK enforcement is out of scope for this security fix.

Broader hosted multi-tenancy hardening (session REST owner-scoping, TOCTOU symlink isolation) is tracked in #704.

@frankbria Thanks for the clear write-up!

• WebSocketDisconnect(1008) assertion — confirmed and appreciated; asserting the specific policy-violation close code makes the test intent explicit.
• SQLite FK metadata — that's a sound call. The REFERENCES … ON DELETE SET NULL clause is consistent with the CREATE TABLE form and the behavioral outcome (nullable column, application-side enforcement) is correct; strict FK enforcement via PRAGMA is a separate concern and rightly out of scope here.

The security-critical paths are well-guarded. Looking forward to seeing the session REST owner-scoping and TOCTOU symlink hardening land in #704. 🐇

Follow-up Review (95c2a04 update)

Checking items from my prior review.

Fixed

• Test assertion (my item 4): test_chat_ws_ownership_mismatch_closes now correctly asserts WebSocketDisconnect with code == 1008. Good.

Still Open

Item 1 - Circular import (was my stated blocker for merge)

The lazy import inside enforce_workspace_allowlist is still present:

def enforce_workspace_allowlist(path, user_id):
    # Local import avoids a circular import (server -> routers -> dependencies).
    from codeframe.ui.server import is_hosted_mode

This pattern is fragile: if the import graph changes, it fails silently at call time instead of at startup. is_hosted_mode is just a one-liner reading CODEFRAME_DEPLOYMENT_MODE. Moving it to codeframe/lib/deployment.py or inlining the env-var read directly in dependencies.py (no server import needed) would close this. This was my primary "resolve before merge" item.

Item 2 - Type inconsistency (minor)

workspace_v2.py still declares auth: dict, while interactive_sessions_v2.py and dependencies.py use Dict[str, Any]. One-line fix.

Item 3 - WebSocket close codes (minor)

terminal_ws.py still closes with code 4003, session_chat_ws.py uses 1008. Same policy violation, same enforcement path — 1008 is the semantically correct RFC 6455 code for both. The mismatch will confuse clients handling reconnect logic.

Item 5 - # ponytail: annotation (cosmetic)

Still present in enforce_workspace_allowlist. Not a blocker, but a non-standard prefix that future readers won't recognize. Rewrite as a plain # TODO: or inline note.

Path to merge: Fix the circular import (item 1) — that is the only structural concern I flagged. Items 2, 3, and 5 can follow in a cleanup PR or be addressed here if convenient.

Follow-up Review -- Workspace Allowlist + Session Ownership (#655)

Continuing from my prior review. The diff has not changed since that pass, so the three outstanding items remain open. A correction to my previous review is noted below.

Outstanding Item 1 -- Circular import (still open / blocker)

enforce_workspace_allowlist in dependencies.py still lazy-imports is_hosted_mode from server.py on every call. This works until anyone refactors the import graph, at which point it silently breaks at call-time rather than import-time. Extracting is_hosted_mode into codeframe/lib/deployment.py (a two-line function reading CODEFRAME_DEPLOYMENT_MODE) dissolves the cycle. This remains the only blocker.

Outstanding Item 2 -- Type annotation inconsistency (minor)

workspace_v2.py:229 declares auth: dict = Depends(require_auth) while interactive_sessions_v2.py and dependencies.py both use auth: Dict[str, Any]. Prefer dict[str, Any] consistently across all three sites.

Outstanding Item 3 -- Inconsistent WebSocket close codes (minor)

terminal_ws.py closes with 4003 (custom), session_chat_ws.py closes with 1008 (RFC 6455 Policy Violation) for the same enforcement reason. 1008 is semantically correct for both; terminal_ws.py should be aligned.

Correction to Item 4 from prior review

I previously said test_chat_ws_ownership_mismatch_closes catches bare Exception. That was wrong. The test uses pytest.raises(WebSocketDisconnect) and asserts exc.value.code == 1008 -- it correctly pins the disconnect type and close code. Apologies for the noise; that test was already right.

One new observation

The _create_session helper in test_session_chat_ws.py imports TestClient at module level and again inside the new test function body. Redundant local re-import -- not a correctness issue, just cleanup.

Summary: security logic is correct and well-tested. Item 1 (circular import) is the only blocker. Items 2 and 3 are minor polish. Item 4 from the prior review was already handled correctly.