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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(workspace): scoping audit + per-scope matrix (plan 19)
Juan Denis782ea70c8bf8
diff --git a/backend/app/api/workspaces.py b/backend/app/api/workspaces.pyindex 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_requiredfrom app.services.workspace_service import WorkspaceServicefrom app.services.audit_service import AuditServicefrom 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_roleworkspaces_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.mdnew file mode 100644index 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.jsxindex 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 filediff --git a/frontend/src/components/workspaces/WorkspaceOverviewTab.jsx b/frontend/src/components/workspaces/WorkspaceOverviewTab.jsxindex 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>);