feat: add scoped authorization visibility prefilter

[erichare]

Summary

• add a backward-compatible ResourceVisibilityScope authorization contract for concrete, workspace, project, and global grants
• apply owner-plus-visible predicates to flow, project, and deployment queries before pagination
• keep the existing concrete-ID plugin hook working while avoiding wildcard expansion to every resource UUID
• use the same deployment predicate for page rows and totals

Why

Enterprise scoped RBAC cannot represent a global, workspace, or project wildcard through list_visible_resource_ids() without loading every matching resource. This seam lets registered authorization plugins return compact scopes that OSS list routes translate directly into SQL.

The OSS pass-through behavior is unchanged: when no plugin supplies a prefilter, queries remain owner-scoped and retain the existing in-memory fallback.

Testing

• uv run --frozen pytest -q src/backend/tests/unit/services/authorization src/backend/tests/unit/api/v1/test_deployment_route_handlers.py — 306 passed
• uv run --frozen pytest -q src/backend/tests/unit/services/database/test_deployment_crud_authz_prefilter.py — 7 passed
• Enterprise compatibility typecheck and production Vite build against this branch

Refs LE-1826

Summary by CodeRabbit

• Improvements
  • Resource listings now apply visibility rules consistently across deployments, flows, and projects.
  • Pagination totals and displayed results remain aligned for shared, workspace-scoped, project-scoped, and globally visible resources.
  • Listing performance improves by applying visibility constraints during database queries where supported.
• Bug Fixes
  • Preserved compatibility with existing authorization providers while improving shared-resource access handling.
• Tests
  • Added coverage for visibility scopes, authorization fallbacks, and consistent deployment counts.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9bf17664-ace7-470b-9d87-0304dd1ca5a4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

Listing authorization now uses ResourceVisibilityScope for workspace, project, resource, and global visibility. Routes pass scopes into SQL pagination and count queries, select shared providers for cross-user access, and retain in-memory filtering when no scope is available.

Changes

Structured visibility scope

Layer / File(s)	Summary
Visibility scope contract and authorization helpers src/lfx/src/lfx/services/authorization/*, src/backend/base/langflow/services/authorization/*	Adds ResourceVisibilityScope, scope discovery, scope-based SQL predicates, loaded-resource checks, and public exports.
Deployment pagination and count scoping src/backend/base/langflow/services/database/models/deployment/crud.py, src/backend/base/langflow/api/v1/mappers/deployments/helpers.py	Threads visibility_scope through deployment page and total-count queries while retaining allowed_ids compatibility.
Route-level visibility integration src/backend/base/langflow/api/v1/{deployments,flows,projects}.py	Applies visibility scopes to route queries, shared provider selection, eager-loaded flows, and in-memory fallback filtering.
Visibility scope and route regression coverage src/backend/tests/unit/services/authorization/*, src/backend/tests/unit/services/database/*, src/backend/tests/unit/api/v1/*	Updates prefilter expectations and tests structured scope behavior across resource, workspace, project, and global visibility.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ListingRoute
  participant AuthorizationService
  participant DeploymentQuery
  participant Database
  ListingRoute->>AuthorizationService: resolve ResourceVisibilityScope
  AuthorizationService-->>ListingRoute: scope or None
  ListingRoute->>DeploymentQuery: pass visibility_scope
  DeploymentQuery->>Database: apply scope to page and count queries
  Database-->>ListingRoute: scoped results and total

Loading

Possibly related PRs

• langflow-ai/langflow#13371: Adds the visible-resource authorization hook adapted by the new structured scope flow.
• langflow-ai/langflow#13541: Wires visible-ID authorization into the same listing endpoints later updated to structured scopes.

Suggested labels: enhancement

Suggested reviewers: himavarshavs, ogabrielluiz

🚥 Pre-merge checks | ✅ 8 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (8 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a scoped authorization visibility prefilter.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Coverage For New Implementations	✅ Passed	The PR adds substantive tests for the new visibility-scope authz contract, deployment CRUD scoping, and route wiring; filenames follow project conventions.
Test Quality And Coverage	✅ Passed	Tests cover new authz scope behavior at helper, DB, and route levels, use pytest async patterns, and include both success/error cases for affected endpoints.
Test File Naming And Structure	✅ Passed	All added tests are in test_*.py unit paths, use pytest fixtures/markers, have descriptive names, and cover positive/negative cases with clear structure.
Excessive Mock Usage Warning	✅ Passed	Mocks are confined to route-boundary unit tests; the new authz and DB coverage uses real objects/SQL sessions, so mock use isn’t excessive.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (2)

src/backend/tests/unit/api/v1/test_deployment_route_handlers.py (2)

817-822: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider reducing reliance on mocks.

As per coding guidelines, backend unit tests should avoid excessive mocking and prefer real integrations. This test suite patches 6 different dependencies for a single route handler, which can obscure what is actually being tested and make the test brittle to internal refactors. Consider migrating these route handler tests to integration tests that use a real test database and the actual FastAPI router in the future.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/backend/tests/unit/api/v1/test_deployment_route_handlers.py` around lines
817 - 822, Reduce excessive mocking in the route handler tests around the
patched dependencies visible in the test setup, especially
list_deployments_synced, resolve_deployment_adapter, get_deployment_mapper, and
the provider-account helpers. Migrate these tests toward integration coverage
using the actual FastAPI router and a real test database, preserving assertions
for the route behavior while removing mocks that duplicate internal
implementation details.

Source: Coding guidelines

---

816-816: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Remove unnecessary @pytest.mark.asyncio decorators.

Based on learnings, pytest-asyncio is configured with asyncio_mode = 'auto' in pyproject.toml, making explicit @pytest.mark.asyncio decorators unnecessary for tests. Please remove them to follow the repository's convention.

• src/backend/tests/unit/api/v1/test_deployment_route_handlers.py#L816-L816: Remove the @pytest.mark.asyncio decorator.
• src/backend/tests/unit/api/v1/test_deployment_route_handlers.py#L886-L886: Remove the @pytest.mark.asyncio decorator.
• src/backend/tests/unit/api/v1/test_deployment_route_handlers.py#L931-L931: Remove the @pytest.mark.asyncio decorator.
• src/backend/tests/unit/services/database/test_deployment_crud_authz_prefilter.py#L167-L167: Remove the @pytest.mark.asyncio decorator.

♻️ Proposed fixes

For src/backend/tests/unit/api/v1/test_deployment_route_handlers.py:

-    `@pytest.mark.asyncio`
     `@patch`(f"{ROUTES_MODULE}.list_deployments_synced", new_callable=AsyncMock)

For src/backend/tests/unit/services/database/test_deployment_crud_authz_prefilter.py:

-@pytest.mark.asyncio
 `@pytest.mark.parametrize`("scope_kind", ["workspace", "project", "global"])

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/backend/tests/unit/api/v1/test_deployment_route_handlers.py` at line 816,
Remove the unnecessary `@pytest.mark.asyncio` decorators from the async tests at
src/backend/tests/unit/api/v1/test_deployment_route_handlers.py lines 816, 886,
and 931, and from
src/backend/tests/unit/services/database/test_deployment_crud_authz_prefilter.py
line 167. Rely on the repository’s asyncio_mode = 'auto' configuration and leave
the test implementations unchanged.

Source: Learnings

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/backend/tests/unit/api/v1/test_deployment_route_handlers.py`:
- Around line 817-822: Reduce excessive mocking in the route handler tests
around the patched dependencies visible in the test setup, especially
list_deployments_synced, resolve_deployment_adapter, get_deployment_mapper, and
the provider-account helpers. Migrate these tests toward integration coverage
using the actual FastAPI router and a real test database, preserving assertions
for the route behavior while removing mocks that duplicate internal
implementation details.
- Line 816: Remove the unnecessary `@pytest.mark.asyncio` decorators from the
async tests at src/backend/tests/unit/api/v1/test_deployment_route_handlers.py
lines 816, 886, and 931, and from
src/backend/tests/unit/services/database/test_deployment_crud_authz_prefilter.py
line 167. Rely on the repository’s asyncio_mode = 'auto' configuration and leave
the test implementations unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 32368d87-8d68-4275-a759-c5d7b06d74cf

📥 Commits

Reviewing files that changed from the base of the PR and between d89c8f8 and fae8109.

📒 Files selected for processing (13)

• src/backend/base/langflow/api/v1/deployments.py
• src/backend/base/langflow/api/v1/flows.py
• src/backend/base/langflow/api/v1/mappers/deployments/helpers.py
• src/backend/base/langflow/api/v1/projects.py
• src/backend/base/langflow/services/authorization/__init__.py
• src/backend/base/langflow/services/authorization/listing.py
• src/backend/base/langflow/services/database/models/deployment/crud.py
• src/backend/tests/unit/api/v1/test_deployment_route_handlers.py
• src/backend/tests/unit/services/authorization/test_route_guard_regressions.py
• src/backend/tests/unit/services/authorization/test_visibility_scope_prefilter.py
• src/backend/tests/unit/services/database/test_deployment_crud_authz_prefilter.py
• src/lfx/src/lfx/services/authorization/__init__.py
• src/lfx/src/lfx/services/authorization/base.py