Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(workspace): scoping audit + per-scope matrix (plan 19)

Juan Denis782ea70c8bf8
diff --git a/backend/app/api/workspaces.py b/backend/app/api/workspaces.py
index 88d42ef8..091c276e 100644
--- a/backend/app/api/workspaces.py
+++ b/backend/app/api/workspaces.py
@@ -3,6 +3,9 @@ from flask_jwt_extended import jwt_required
from app.services.workspace_service import WorkspaceService
from app.services.audit_service import AuditService
from app.models.audit_log import AuditLog
+# The workspace guards now live in middleware/rbac.py so any resource blueprint
+# can reuse them (plan 19 Decision 2). Re-exported here for existing callers.
+from app.middleware.rbac import require_workspace_access, require_workspace_role
workspaces_bp = Blueprint('workspaces', __name__)
@@ -13,27 +16,6 @@ def get_current_user():
return User.query.get(get_jwt_identity())
-def require_workspace_access(workspace_id, user):
- """Return 403 response tuple if user is not a workspace member or admin, else None."""
- if user.is_admin:
- return None
- role = WorkspaceService.get_user_role(workspace_id, user.id)
- if role is None:
- return jsonify({'error': 'Workspace access denied'}), 403
- return None
-
-
-def require_workspace_role(workspace_id, user, roles):
- """Return 403 response tuple if user is not an admin and their workspace
- membership role is not one of the allowed roles."""
- if user.is_admin:
- return None
- role = WorkspaceService.get_user_role(workspace_id, user.id)
- if role not in roles:
- return jsonify({'error': 'Insufficient permissions'}), 403
- return None
-
-
@workspaces_bp.route('/', methods=['GET'])
@jwt_required()
def list_workspaces():
diff --git a/docs/WORKSPACE_SCOPING.md b/docs/WORKSPACE_SCOPING.md
new file mode 100644
index 00000000..fec38745
--- /dev/null
+++ b/docs/WORKSPACE_SCOPING.md
@@ -0,0 +1,143 @@
+# Workspace Scoping — the one visibility & permission contract
+
+> Status: LIVE (plan 19). This is the single source of truth for "who can see and
+> do what to a resource that belongs to an app in a workspace." Plans 21/22/24/26
+> cite this document instead of re-deciding scoping per surface.
+
+ServerKit's tenancy chain is `Workspace → Project → Environment → Application`.
+Most resources (domains, env vars, volumes, deployments, managed DBs, WordPress
+sites, backups…) hang off an `application_id`. Workspaces landed after most
+features, so this contract retrofits ONE model over all of them.
+
+## 1. The three ideas
+
+1. **Derived scope, never duplicated.** A resource does not store its own
+ workspace. It references an `application_id` (or is app-derived) and the
+ workspace/project resolve *through* the app at read time. The only rows that
+ carry `workspace_id` directly are `Application`, `Server`, and the born-in-a-
+ workspace resources (vaults, webhook gateways).
+
+2. **Visibility = union(owned, granted, workspace-member).** A user sees a
+ resource if they own its app, have a `ResourceGrant` on its app, **or** are a
+ member of the app's workspace (any role). Membership grants **READ**.
+
+3. **Visibility ≠ permission.** Seeing a resource does not mean you can change
+ it. Mutation is gated by capability tier *and* by whether the action can reach
+ the host (see the write matrix below).
+
+## 2. Visibility (READ)
+
+Use one of two seams — never hand-roll a filter:
+
+- **A model that carries `workspace_id`** (i.e. `Application`): scope its list
+ with `WorkspaceService.scope_query(..., membership=True)`. This unions
+ `owner ∪ granted ∪ apps-in-my-workspaces`, then narrows to the active
+ workspace context if one is supplied.
+
+- **An app-derived model** (`domain.application_id`, `managed_database.
+ owner_application_id`, …): resolve the visible app-id set once with
+ `WorkspaceService.visible_application_ids(user, workspace_id)` and filter
+ `Model.<app_fk>.in_(ids)`. The helper returns `None` for a panel admin, the
+ sentinel for "no restriction":
+
+ ```python
+ ids = WorkspaceService.visible_application_ids(user, ws_id)
+ q = Model.query if ids is None else Model.query.filter(Model.application_id.in_(ids))
+ ```
+
+`visible_application_ids` runs a small fixed number of queries per request, so
+downstream lists apply a single `IN`-clause — no N+1.
+
+For a **single** resource, gate the route with `require_app_member(min_role)`
+(below) rather than re-deriving visibility.
+
+## 3. The app-scoped gate
+
+`app_access_tier(user, application)` folds every path to an app into ONE
+capability tier, highest wins:
+
+| Path to the app | Tier |
+|-------------------------------------|-----------|
+| panel admin, or the app's owner | `owner` |
+| `ResourceGrant` role `editor` | `member` |
+| `ResourceGrant` role `viewer` | `viewer` |
+| member of the app's workspace | that workspace role (`owner`/`admin`/`member`/`viewer`) |
+| none of the above | `None` (no access) |
+
+Tier order: `viewer < member < admin < owner`.
+
+`require_app_member(min_role='viewer', arg='app_id')` is the decorator: it
+resolves the app from the named view kwarg, **404s** a missing app (no info
+leak), **403s** an insufficient tier, and stashes the app on
+`g.current_application`. Read routes use `min_role='viewer'`; member-writes
+`'member'`; app-scoped destructive `'admin'`.
+
+## 4. The write matrix (by capability class, NOT per endpoint)
+
+| Capability class | Examples | Gate |
+|---|---|---|
+| **App-scoped, no host reach** | env vars, restart/redeploy own app, backup-policy schedule for own app | workspace **member+** (`require_app_member('member')` / `can_edit_app`) |
+| **App-scoped destructive** | delete app, delete domain, drop managed DB | workspace **admin/owner** (`require_app_member('admin')`) |
+| **Host-touching or global** | nginx/system config, system DB engines, Docker system ops, SSL issuance, FTP, firewall, fleet | **panel admin only** — a workspace role NEVER unlocks these (`@admin_required`) |
+
+A workspace role can never inflate into a host-touching power. When a member
+needs a host-adjacent effect, it goes through a **member action template**
+(Phase 5) — a curated, parameterized, audit-logged action — never through role
+inflation or free-text shell input.
+
+## 5. The System bucket
+
+Resources with **no** app association are "System": global DNS zones, the SSL
+store, FTP accounts, email domains, host Docker objects, unassociated cron. They
+are admin-only surfaces, labeled "System" in the UI, and are **never** mixed into
+a member's workspace views. Do not give a System surface a membership filter —
+gate it `@admin_required`.
+
+## 6. Onboarding a new surface — the checklist
+
+1. **Association.** Does the resource reference an `application_id` (or a model
+ that does)? If not, it is **System** → `@admin_required`, stop here.
+2. **List read.** App-derived list → filter on `visible_application_ids`. A model
+ with its own `workspace_id` → `scope_query(..., membership=True)`.
+3. **Single read.** Gate with `require_app_member('viewer')`.
+4. **Writes.** Classify each mutation into the write matrix and gate it:
+ member-write → `require_app_member('member')` / `can_edit_app`; destructive →
+ `require_app_member('admin')`; host-touching → `@admin_required`.
+5. **Bucket header.** Put a one-line comment at the top of the route file
+ stating its bucket (`# Bucket: app-scoped` / `# Bucket: System (admin-only)`)
+ so the grep audit (Phase 4 #16) can verify it.
+6. **Matrix test.** Add the surface's declaration on top of the shared
+ `scoping_rbac` fixture (`tests/conftest.py`) — see
+ `tests/test_workspace_scoping_matrix.py` for the reference apps+domains pair.
+
+## 7. Locked decisions (see plan 19)
+
+- `scope_query` is canonical and grew exactly one mode (`membership`).
+- The two gates live in `middleware/rbac.py` (`require_app_member`,
+ `require_workspace_role`); the `secrets_webhooks.py` duplicate is gone.
+- `ResourceGrant.role` widens visibility only; a per-resource role matrix is out
+ of scope (`editor` folds to `member`, `viewer` to `viewer`).
+- Project/environment are display groupings; visibility is decided at workspace
+ level.
+- Workspace admins get no host-adjacent powers — ever.
+
+## 8. Member action templates (Phase 5)
+
+A member's only write escape hatch beyond the matrix is a **member action
+template**: a curated, parameterized action a member may trigger for their own
+app. No free text ever reaches a shell. Each template declares
+`(id, label, param schema, executor, min_role)`, is audit-logged, and is
+feature-flagged. See `app/services/member_action_service.py`.
+
+**Enabling / disabling the surface (plan 29 #13).** Member actions are **ON by
+default** — the shipped templates are deliberately narrow (typed enums / bounded
+ints, no free text, vetted service calls only). The surface has two independent
+kill switches, and *both* must allow it:
+
+- the `MEMBER_ACTIONS_ENABLED` app config (deployment-level), and
+- the admin-visible **`security_member_actions_enabled`** system setting, exposed
+ as the *Member Actions* card in **Settings → System** security section.
+
+Turning either off disables the whole surface (the catalog goes empty and runs
+return 403). The default is unchanged; the plan-29 change only made the flag
+*visible* so an operator isn't relying on something silently on.
diff --git a/frontend/src/components/WorkspaceSwitcher.jsx b/frontend/src/components/WorkspaceSwitcher.jsx
index 06013757..7715991f 100644
--- a/frontend/src/components/WorkspaceSwitcher.jsx
+++ b/frontend/src/components/WorkspaceSwitcher.jsx
@@ -101,4 +101,5 @@ const WorkspaceSwitcher = () => {
);
};
-export default WorkspaceSwitcher;
+export default Workspa
+2026-07-07
\ No newline at end of file
diff --git a/frontend/src/components/workspaces/WorkspaceOverviewTab.jsx b/frontend/src/components/workspaces/WorkspaceOverviewTab.jsx
index ea3a4ed2..a8c27aae 100644
--- a/frontend/src/components/workspaces/WorkspaceOverviewTab.jsx
+++ b/frontend/src/components/workspaces/WorkspaceOverviewTab.jsx
@@ -1,4 +1,5 @@
-import { ServiceTile } from '@/components/ds';
+import { KpiBand, MetricCard } from '@/components/ds';
+import { Server, Boxes, Globe, Users } from 'lucide-react';
const WorkspaceOverviewTab = ({ ws, since, members, srvIn, services, sites }) => (
<div className="ws-detail__grid">
@@ -11,24 +12,12 @@ const WorkspaceOverviewTab = ({ ws, since, members, srvIn, services, sites }) =>
</section>
<section className="ws-detail__card">
<h3>Resources</h3>
- <div className="ws-resource-stats">
- <div className="ws-resource-stats__item">
- <div className="ws-resource-stats__value">{srvIn.length}</div>
- <div className="ws-resource-stats__label">Servers</div>
- </div>
- <div className="ws-resource-stats__item">
- <div className="ws-resource-stats__value">{services.length}</div>
- <div className="ws-resource-stats__label">Services</div>
- </div>
- <div className="ws-resource-stats__item">
- <div className="ws-resource-stats__value">{sites.length}</div>
- <div className="ws-resource-stats__label">Sites</div>
- </div>
- <div className="ws-resource-stats__item">
- <div className="ws-resource-stats__value">{members.length}</div>
- <div className="ws-resource-stats__label">Members</div>
- </div>
- </div>
+ <KpiBand>
+ <MetricCard icon={<Server size={16} />} tone="accent" value={srvIn.length} label="Servers" />
+ <MetricCard icon={<Boxes size={16} />} tone="accent" value={services.length} label="Services" />
+ <MetricCard icon={<Globe size={16} />} tone="accent" value={sites.length} label="Sites" />
+ <MetricCard icon={<Users size={16} />} tone="accent" value={members.length} label="Members" />
+ </KpiBand>
</section>
</div>
);