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(workspaces): workspace_id scoping foundation + safe backfill (#33)

Juan Denis299a004cdf80
diff --git a/backend/app/api/apps.py b/backend/app/api/apps.py
index cc45b7a7..1db7ed53 100644
--- a/backend/app/api/apps.py
+++ b/backend/app/api/apps.py
@@ -311,10 +311,16 @@ def get_apps():
environment_filter = request.args.get('environment')
include_linked = request.args.get('include_linked', 'false').lower() == 'true'
- if user.role == 'admin':
- query = Application.query
- else:
- query = Application.query.filter_by(user_id=current_user_id)
+ # Workspace-aware scoping (#33). With no workspace context this is exactly the
+ # prior behavior (admin -> all, else -> own); with ?workspace_id / X-Workspace-Id
+ # it filters to that workspace (membership-checked).
+ from app.services.workspace_service import WorkspaceService
+ ws_id, werr = WorkspaceService.resolve_workspace_id(
+ user, request.headers.get('X-Workspace-Id') or request.args.get('workspace_id'))
+ if werr:
+ return jsonify({'error': werr[0]}), werr[1]
+ query = WorkspaceService.scope_query(Application.query, Application, user,
+ workspace_id=ws_id, owner_attr='user_id')
if environment_filter:
query = query.filter_by(environment_type=environment_filter)
@@ -530,6 +536,16 @@ def create_app():
if app_type not in valid_types:
return jsonify({'error': f'Invalid app_type. Must be one of: {", ".join(valid_types)}'}), 400
+ # Stamp the workspace (#33): the requested one (membership-checked) or the default.
+ from app.services.workspace_service import WorkspaceService
+ user = User.query.get(current_user_id)
+ ws_id, werr = WorkspaceService.resolve_workspace_id(
+ user, request.headers.get('X-Workspace-Id') or request.args.get('workspace_id'))
+ if werr:
+ return jsonify({'error': werr[0]}), werr[1]
+ if ws_id is None:
+ ws_id = WorkspaceService.ensure_default_workspace().id
+
app = Application(
name=name,
app_type=app_type,
@@ -539,7 +555,8 @@ def create_app():
port=data.get('port'),
root_path=data.get('root_path'),
docker_image=data.get('docker_image'),
- user_id=current_user_id
+ user_id=current_user_id,
+ workspace_id=ws_id
)
db.session.add(app)
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.py
index 24078413..efc411f0 100644
--- a/backend/app/api/servers.py
+++ b/backend/app/api/servers.py
@@ -252,7 +252,17 @@ def list_servers():
status = request.args.get('status')
tag = request.args.get('tag')
- query = Server.query
+ # Workspace-aware scoping (#33). Servers are global today, so with no workspace
+ # context this stays unfiltered; with a workspace context it filters to it.
+ from app.models import User
+ from app.services.workspace_service import WorkspaceService
+ user = User.query.get(get_jwt_identity())
+ ws_id, werr = WorkspaceService.resolve_workspace_id(
+ user, request.headers.get('X-Workspace-Id') or request.args.get('workspace_id'))
+ if werr:
+ return jsonify({'error': werr[0]}), werr[1]
+ query = WorkspaceService.scope_query(Server.query, Server, user,
+ workspace_id=ws_id, owner_attr=None)
if group_id:
query = query.filter_by(group_id=group_id)
@@ -310,6 +320,17 @@ def create_server():
expires_at = _resolve_token_expiry(data.get('expires_in'))
+ # Stamp the workspace (#33): the requested one (membership-checked) or the default.
+ from app.models import User
+ from app.services.workspace_service import WorkspaceService
+ user = User.query.get(user_id)
+ ws_id, werr = WorkspaceService.resolve_workspace_id(
+ user, request.headers.get('X-Workspace-Id') or request.args.get('workspace_id'))
+ if werr:
+ return jsonify({'error': werr[0]}), werr[1]
+ if ws_id is None:
+ ws_id = WorkspaceService.ensure_default_workspace().id
+
server = Server(
# Temporary name — replaced with the agent's hostname when the
# agent calls /register. _is_placeholder_name() in the register
@@ -322,6 +343,7 @@ def create_server():
permissions=permissions,
allowed_ips=data.get('allowed_ips', []),
registered_by=user_id,
+ workspace_id=ws_id,
registration_token_expires=expires_at,
)
server.set_registration_token(registration_token)
diff --git a/backend/app/models/application.py b/backend/app/models/application.py
index 8b35630c..d8d2dded 100644
--- a/backend/app/models/application.py
+++ b/backend/app/models/application.py
@@ -37,6 +37,9 @@ class Application(db.Model):
# Foreign keys
user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=False)
server_id = db.Column(db.String(36), db.ForeignKey('servers.id'), nullable=True, index=True)
+ # Workspace scoping (#33). Nullable: existing rows are backfilled to a default
+ # workspace by migration 015; new rows are stamped on create.
+ workspace_id = db.Column(db.Integer, db.ForeignKey('workspaces.id'), nullable=True, index=True)
# Relationships
# Use 'subquery' to eagerly load domains in a single query, avoiding N+1
@@ -68,6 +71,7 @@ class Application(db.Model):
'last_deployed_at': self.last_deployed_at.isoformat() if self.last_deployed_at else None,
'user_id': self.user_id,
'server_id': self.server_id,
+ 'workspace_id': self.workspace_id,
'server_name': self.server.name if self.server else 'Local server',
'domains': [d.to_dict() for d in self.domains]
}
diff --git a/backend/app/models/server.py b/backend/app/models/server.py
index 25995cf1..3dd05b88 100644
--- a/backend/app/models/server.py
+++ b/backend/app/models/server.py
@@ -85,6 +85,9 @@ class Server(db.Model):
# Organization
group_id = db.Column(db.String(36), db.ForeignKey('server_groups.id'), nullable=True, index=True)
+ # Workspace scoping (#33). Nullable: existing rows are backfilled to a default
+ # workspace by migration 015; new rows are stamped on create.
+ workspace_id = db.Column(db.Integer, db.ForeignKey('workspaces.id'), nullable=True, index=True)
tags = db.Column(db.JSON, default=list) # ["production", "us-east", "docker"]
# Status
@@ -398,6 +401,7 @@ class Server(db.Model):
'ip_address': self.ip_address,
'group_id': self.group_id,
'group_name': self.group.name if self.group else None,
+ 'workspace_id': self.workspace_id,
'tags': self.tags or [],
'status': self.status,
'last_seen': self.last_seen.isoformat() if self.last_seen else None,
diff --git a/backend/app/services/workspace_service.py b/backend/app/services/workspace_service.py
index 3be852c1..23059dca 100644
--- a/backend/app/services/workspace_service.py
+++ b/backend/app/services/workspace_service.py
@@ -13,11 +13,87 @@ logger = logging.getLogger(__name__)
class WorkspaceService:
"""Service for multi-tenancy workspace management."""
+ DEFAULT_WORKSPACE_SLUG = 'default'
+
@staticmethod
def _slugify(name):
slug = re.sub(r'[^a-z0-9]+', '-', name.lower()).strip('-')
return slug or 'workspace'
+ # --- Scoping (#33 foundation) ---
+ #
+ # These three helpers centralize resource scoping so the admin-vs-owner-vs-
+ # workspace branch isn't re-implemented per route. Scoping is OPT-IN: a
+ # request only filters by workspace when it carries a workspace context
+ # (X-Workspace-Id header or ?workspace_id=). With no context, scope_query
+ # preserves each resource's existing ownership behavior exactly, so this
+ # foundation changes nothing until a caller activates a workspace.
+
+ @staticmethod
+ def ensure_default_workspace():
+ """Find-or-create the Default workspace (idempotent). Used to stamp newly
+ created resources when no workspace context is supplied, and to give
+ existing resources a home (mirrors migration 015's backfill)."""
+ ws = Workspace.query.filter_by(slug=WorkspaceService.DEFAULT_WORKSPACE_SLUG).first()
+ if ws is None:
+ ws = Workspace(
+ name='Default',
+ slug=WorkspaceService.DEFAULT_WORKSPACE_SLUG,
+ description='Default workspace (auto-created for existing resources).',
+ )
+ db.session.add(ws)
+ db.session.commit()
+ return ws
+
+ @staticmethod
+ def resolve_workspace_id(user, requested):
+ """Validate an optionally-requested workspace context.
+
+ Returns (workspace_id|None, error|None) where error is a (message, status)
+ tuple. A None workspace_id means "no active context" — callers then keep
+ their existing non-workspace behavior. A truthy error means the request
+ named a workspace the user may not use; callers should surface it.
+ """
+ if requested in (None, '', 'all'):
+ return None, None
+ # A deactivated account must not drive workspace resolution (the admin
+ # bypass / membership check below key off this token-loaded user). Gated
+ # only on the workspace path so the no-context behavior is unchanged.
+ if not getattr(user, 'is_active', True):
+ return None, ('Account is deactivated', 403)
+ try:
+ ws_id = int(requested)
+ except (ValueError, TypeError):
+ return None, ('Invalid workspace id', 400)
+ ws = Workspace.query.get(ws_id)
+ if not ws:
+ return None, ('Workspace not found', 404)
+ if not user.is_admin and WorkspaceService.get_user_role(ws_id, user.id) is None:
+ return None, ('Workspace access denied', 403)
+ return ws_id, None
+
+ @staticmethod
+ def scope_query(query, model, user, workspace_id=None, owner_attr=None):
+ """Apply scoping to a resource list query. Critically, this can only ever
+ NARROW what a user sees — it never broadens access — so activating a
+ workspace can't reveal another user's resources.
+
+ - non-admin + owner_attr -> always restricted to the user's own rows
+ (preserves the existing per-user ownership model, e.g. applications).
+ A workspace context then narrows *within* those rows.
+ - admin, or a global resource (owner_attr=None, e.g. servers) -> no owner
+ filter; today's behavior (admin sees all; servers are global).
+ - workspace context active -> additionally filter to that workspace.
+
+ Broader "every member sees every resource in the workspace" visibility is
+ deliberately NOT done here — that needs the workspace-role/ACL step.
+ """
+ if owner_attr and not user.is_admin:
+ query = query.filter(getattr(model, owner_attr) == user.id)
+ if workspace_id is not None:
+ query = query.filter(model.workspace_id == workspace_id)
+ return query
+
@staticmethod
def list_workspaces(user_id=None, include_archived=False):
query = Workspace.query
diff --git a/backend/migrations/versions/015_workspace_scope.py b/backend/migrations/versions/015_workspace_scope.py
new file mode 100644
index 00000000..a0cd24ee
--- /dev/null
+++ b/backend/migrations/versions/015_workspace_scope.py
@@ -0,0 +1,124 @@
+"""Workspace scoping foundation (#33 — agency-scale core).
+
+Adds:
+- applications.workspace_id (nullable FK -> workspaces.id)
+- servers.workspace_id (nullable FK -> workspaces.id)
+
+Backfill (idempotent, raw SQL like 006_default_full_permissions):
+- ensure a "Default" workspace exists,
+- attach every workspace-less application/server to it,
+- make every existing user a member of it, so nobody loses visibility once
+ workspace scoping is activated.
+
+Scoping itself is opt-in (a request only filters by workspace when it carries a
+workspace context), so this migration changes no behavior on its own — it only
+gives every resource a workspace home.
+
+Idempotent: MigrationService._fix_missing_columns runs db.create_all() on boot
+before Alembic (creating the workspaces tables + adding the columns), so guard
+on the live schema exactly like 009..014.
+
+Revision ID: 015_workspace_scope
+Revises: 014_wordpress_reports
+Create Date: 2026-06-01
+"""
+from datetime import datetime
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = '015_workspace_scope'
+down_revision = '014_wordpress_reports'
+branch_labels = None
+depends_on = None
+
+
+def _has_col(inspector, table, col):
+ if table not in inspector.get_table_names():
+ return False
+ return col in {c['name'] for c in inspector.get_columns(table)}
+
+
+def _ensure_index(inspector, name, table, col):
+ """Create an index idempotently (matches SQLAlchemy's ix_<table>_<col> name,
+ so a fresh create_all install — which already has it — isn't duplicated)."""
+ if not _has_col(inspector, table, col):
+ return
+ if name not in {ix['name'] for ix in inspector.get_indexes(table)}:
+ op.create_index(name, table, [col])
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = set(inspector.get_table_names())
+
+ # The FK target (workspaces) is created by db.create_all() on boot, not by any
+ # migration — guard on it so a standalone `alembic upgrade` (e.g. Postgres,
+ # workspaces absent) doesn't fail adding a FK to a missing table.
+ if 'workspaces' in tables:
+ if 'applications' in tables and not _has_col(inspector, 'applications', 'workspace_id'):
+ with op.batch_alter_table('applications') as batch_op:
+ batch_op.add_column(sa.Column('workspace_id', sa.Integer(),
+ sa.ForeignKey('workspaces.id'), nullable=True))
+ if 'servers' in tables and not _has_col(inspector, 'servers', 'workspace_id'):
+ with op.batch_alter_table('servers') as batch_op:
+ batch_op.add_column(sa.Column('workspace_id', sa.Integer(),
+ sa.ForeignKey('workspaces.id'), nullable=True))
+
+ # Indexes: the models declare index=True, but neither _fix_missing_columns' raw
+ # ADD COLUMN nor batch add_column creates an index — so upgraded installs would
+ # silently lack it. Create idempotently (re-inspect to see the just-added column).
+ inspector = sa.inspect(conn)
+ _ensure_index(inspector, 'ix_applications_workspace_id', 'applications', 'workspace_id')
+ _ensure_index(inspector, 'ix_servers_workspace_id', 'servers', 'workspace_id')
+
+ # Backfill needs the workspace tables (normally created by db.create_all on boot).
+ if 'workspaces' in tables and 'workspace_members' in tables:
+ _backfill(conn)
+
+
+def _backfill(conn):
+ now = datetime.utcnow()
+
+ # 1. Find-or-create the Default workspace (quota columns set to 0 so the
+ # model's int math — e.g. `ws.max_users > 0` — never sees NULL).
+ row = conn.execute(sa.text(
+ "SELECT id FROM workspaces WHERE slug = :slug"), {'slug': 'default'}).fetchone()
+ if row:
+ ws_id = row[0]
+ else:
+ conn.execute(sa.text(
+ "INSERT INTO workspaces "
+ "(name, slug, description, status, max_servers, max_users, max_api_calls, created_at, updated_at) "
+ "VALUES ('Default', 'default', :descr, 'active', 0, 0, 0, :now, :now)"),
+ {'descr': 'Default workspace (auto-created for existing resources).', 'now': now})
+ ws_id = conn.execute(sa.text(
+ "SELECT id FROM workspaces WHERE slug = :slug"), {'slug': 'default'}).fetchone()[0]
+
+ # 2. Attach workspace-less resources to the default workspace.
+ for table in ('applications', 'servers'):
+ conn.execute(sa.text(
+ f"UPDATE {table} SET workspace_id = :ws WHERE workspace_id IS NULL"), {'ws': ws_id})
+
+ # 3. Make every existing user a member of the default workspace (idempotent).
+ if 'users' in set(sa.inspect(conn).get_table_names()):
+ conn.execute(sa.text(
+ "INSERT INTO workspace_members (workspace_id, user_id, role, joined_at) "
+ "SELECT :ws, u.id, 'member', :now FROM users u "
+ "WHERE NOT EXISTS ("
+ " SELECT 1 FROM workspace_members m WHERE m.workspace_id = :ws AND m.user_id = u.id)"),
+ {'ws': ws_id, 'now': now})
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ for name, table in (('ix_servers_workspace_id', 'servers'),
+ ('ix_applications_workspace_id', 'applications')):
+ if table in inspector.get_table_names() and name in {ix['name'] for ix in inspector.get_indexes(table)}:
+ op.drop_index(name, table_name=table)
+ for table in ('servers', 'applications'):
+ if _has_col(inspector, table, 'workspace_id'):
+ with op.batch_alter_table(table) as batch_op:
+ batch_op.drop_column('workspace_id')
diff --git a/backend/tests/test_workspace_scope.py b/backend/tests/test_workspace_scope.py
new file mode 100644
index 00000000..12968f63
--- /dev/null
+++ b/backend/tests/test_workspace_scope.py
@@ -0,0 +1,261 @@
+"""Tests for the workspace scoping foundation (#33 core)."""
+import pytest
+
+
+def _mk_user(db, username, role='admin'):
+ from app.models import User
+ from werkzeug.security import generate_password_hash
+ u = User(email=f'{username}@t.local', username=username,
+ password_hash=generate_password_hash('x'), role=role, is_active=True)
+ db.session.add(u)
+ db.session.commit()
+ return u
+
+
+def _token(user_id):
+ from flask_jwt_extended import create_access_token
+ return {'Authorization': f'Bearer {create_access_token(identity=user_id)}'}
+
+
+# ---- ensure_default_workspace --------------------------------------------
+
+def test_ensure_default_workspace_idempotent(app):
+ from app.services.workspace_service import WorkspaceService
+ from app.models.workspace import Workspace
+ ws1 = WorkspaceService.ensure_default_workspace()
+ ws2 = WorkspaceService.ensure_default_workspace()
+ assert ws1.id == ws2.id
+ assert Workspace.query.filter_by(slug='default').count() == 1
+ # Quota columns must be concrete ints (0), never NULL — the model does int math on them.
+ assert ws1.max_users == 0
+
+
+# ---- resolve_workspace_id -------------------------------------------------
+
+def test_resolve_workspace_id_branches(app):
+ from app import db
+ from app.services.workspace_service import WorkspaceService
+
+ admin = _mk_user(db, 'r_admin', 'admin')
+ owner = _mk_user(db, 'r_owner', 'developer')
+ outsider = _mk_user(db, 'r_outsider', 'developer')
+
+ # No active context.
+ assert WorkspaceService.resolve_workspace_id(outsider, None) == (None, None)
+ assert WorkspaceService.resolve_workspace_id(outsider, '') == (None, None)
+ assert WorkspaceService.resolve_workspace_id(outsider, 'all') == (None, None)
+
+ # Malformed / missing.
+ wsid, err = WorkspaceService.resolve_workspace_id(outsider, 'abc')
+ assert wsid is None and err[1] == 400
+ wsid, err = WorkspaceService.resolve_workspace_id(outsider, 99999)
+ assert wsid is None and err[1] == 404
+
+ # A workspace owned by `owner` (creator becomes owner-member).
+ ws = WorkspaceService.create_workspace({'name': 'Acme'}, owner.id)
+
+ # A non-member non-admin is denied.
+ wsid, err = WorkspaceService.resolve_workspace_id(outsider, ws.id)
+ assert wsid is None and err[1] == 403
+
+ # An admin who is NOT a member is allowed (admin bypass).
+ wsid, err = WorkspaceService.resolve_workspace_id(admin, ws.id)
+ assert wsid == ws.id and err is None
+
+ # A member is allowed.
+ WorkspaceService.add_member(ws.id, outsider.id, 'member')
+ wsid, err = WorkspaceService.resolve_workspace_id(outsider, ws.id)
+ assert wsid == ws.id and err is None
+
+
+def test_resolve_rejects_deactivated_user_on_workspace_path(app):
+ from app import db
+ from app.services.workspace_service import WorkspaceService
+
+ admin = _mk_user(db, 'd_admin', 'admin')
+ ws = WorkspaceService.create_workspace({'name': 'DW'}, admin.id)
+ member = _mk_user(db, 'd_member', 'developer')
+ WorkspaceService.add_member(ws.id, member.id, 'member')
+ member.is_active = False
+ db.session.commit()
+
+ # Requesting a workspace as a deactivated account is rejected...
+ wsid, err = WorkspaceService.resolve_workspace_id(member, ws.id)
+ assert wsid is None and err[1] == 403
+ # ...but the no-context path is unchanged (no new behavior there).
+ assert WorkspaceService.resolve_workspace_id(member, None) == (None, None)
+
+
+# ---- scope_query ----------------------------------------------------------
+
+def test_scope_query_branches(app):
+ from app import db
+ from app.services.workspace_service import WorkspaceService
+ from app.models import Application
+
+ admin = _mk_user(db, 'q_admin', 'admin')
+ dev = _mk_user(db, 'q_dev', 'developer')
+ a1 = Application(name='a1', app_type='php', user_id=dev.id, workspace_id=1)
+ a2 = Application(name='a2', app_type='php', user_id=admin.id, workspace_id=2)
+ db.session.add_all([a1, a2])
+ db.session.commit()
+
+ def names(q):
+ return {a.name for a in q.all()}
+
+ # Active workspace context -> filter by workspace_id.
+ q = WorkspaceService.scope_query(Application.query, Application, dev, workspace_id=1, owner_attr='user_id')
+ assert names(q) == {'a1'}
+
+ # No context, non-admin, owner_attr -> own rows only (prior behavior).
+ q = WorkspaceService.scope_query(Application.query, Application, dev, workspace_id=None, owner_attr='user_id')
+ assert names(q) == {'a1'}
+
+ # No context, admin -> everything (prior behavior).
+ q = WorkspaceService.scope_query(Application.query, Application, admin, workspace_id=None, owner_attr='user_id')
+ assert names(q) == {'a1', 'a2'}
+
+ # No context, owner_attr=None (a global resource like servers) -> everything, even for a non-admin.
+ q = WorkspaceService.scope_query(Application.query, Application, dev, workspace_id=None, owner_attr=None)
+ assert names(q) == {'a1', 'a2'}
+
+
+# ---- API: applications ----------------------------------------------------
+
+def test_get_apps_scoping_api(app, client):
+ from app import db
+ from app.services.workspace_service import WorkspaceService
+ from app.models import Application
+
+ admin = _mk_user(db, 'api_admin', 'admin')
+ dev = _mk_user(db, 'api_dev', 'developer')
+ ws = WorkspaceService.create_workspace({'name': 'WS1'}, admin.id)
+ other = WorkspaceService.create_workspace({'name': 'WS2'}, admin.id)
+ db.session.add_all([
+ Application(name='in-ws', app_type='php', user_id=dev.id, workspace_id=ws.id),
+ Application(name='other-ws', app_type='php', user_id=dev.id, workspace_id=other.id),
+ ])
+ db.session.commit()
+
+ # No context: dev sees its own apps regardless of workspace (prior behavior preserved).
+ r = client.get('/api/v1/apps', headers=_token(dev.id))
+ assert r.status_code == 200
+ assert {a['name'] for a in r.get_json()['apps']} == {'in-ws', 'other-ws'}
+
+ # Requesting a workspace the dev isn't a member of -> 403.
+ r = client.get('/api/v1/apps', headers={**_token(dev.id), 'X-Workspace-Id': str(ws.id)})
+ assert r.status_code == 403
+
+ # Once a member, the list is filtered to that workspace.
+ WorkspaceService.add_member(ws.id, dev.id, 'member')
+ r = client.get('/api/v1/apps', headers={**_token(dev.id), 'X-Workspace-Id': str(ws.id)})
+ assert r.status_code == 200
+ assert {a['name'] for a in r.get_json()['apps']} == {'in-ws'}
+
+
+def test_workspace_context_never_broadens_access(app, client):
+ """A member activating a workspace must NOT see another user's app that lives
+ in the same workspace — scoping only narrows within the user's own rows."""
+ from app import db
+ from app.services.workspace_service import WorkspaceService
+ from app.models import Application
+
+ admin = _mk_user(db, 'esc_admin', 'admin')
+ me = _mk_user(db, 'esc_me', 'developer')
+ other = _mk_user(db, 'esc_other', 'developer')
+ ws = WorkspaceService.create_workspace({'name': 'Shared'}, admin.id)
+ WorkspaceService.add_member(ws.id, me.id, 'member')
+ db.session.add_all([
+ Application(name='mine', app_type='php', user_id=me.id, workspace_id=ws.id),
+ Application(name='theirs', app_type='php', user_id=other.id, workspace_id=ws.id),
+ ])
+ db.session.commit()
+
+ # `me` is a member of the shared workspace but must still only see its own app.
+ r = client.get('/api/v1/apps', headers={**_token(me.id), 'X-Workspace-Id': str(ws.id)})
+ assert r.status_code == 200
+ assert {a['name'] for a in r.get_json()['apps']} == {'mine'}
+
+ # An admin, by contrast, sees everything in the workspace.
+ r = client.get('/api/v1/apps', headers={**_token(admin.id), 'X-Workspace-Id': str(ws.id)})
+ assert {a['name'] for a in r.get_json()['apps']} == {'mine', 'theirs'}
+
+
+def test_create_app_stamps_workspace(app, client):
+ from app.services.workspace_service import WorkspaceService
+ from app import db
+
+ dev = _mk_user(db, 'cre_dev', 'developer')
+
+ # No context -> stamped with the default workspace.
+ r = client.post('/api/v1/apps', headers=_token(dev.id), json={'name': 'newapp', 'app_type': 'php'})
+ assert r.status_code == 201
+ assert r.get_json()['app']['workspace_id'] == WorkspaceService.ensure_default_workspace().id
+
+ # With a workspace context (member) -> stamped with that workspace.
+ admin = _mk_user(db, 'cre_admin', 'admin')
+ ws = WorkspaceService.create_workspace({'name': 'CreWS'}, admin.id)
+ WorkspaceService.add_member(ws.id, dev.id, 'member')
+ r = client.post('/api/v1/apps', headers={**_token(dev.id), 'X-Workspace-Id': str(ws.id)},
+ json={'name': 'wsapp', 'app_type': 'php'})
+ assert r.status_code == 201
+ assert r.get_json()['app']['workspace_id'] == ws.id
+
+
+# ---- migration backfill (raw SQL, run against real SQLite) ----------------
+
+def test_migration_backfill_attaches_resources_and_members(app):
+ import importlib.util
+ import os
+ from app import db
+ from app.models import Application, Server
+ from app.models.workspace import Workspace, WorkspaceMember
+
+ u1 = _mk_user(db, 'bf_u1', 'admin')
+ u2 = _mk_user(db, 'bf_u2', 'developer')
+ db.session.add_all([
+ Application(name='bf-app', app_type='php', user_id=u1.id),
+ Server(name='bf-srv', registered_by=u1.id),
+ ])
+ db.session.commit()
+
+ # Load the migration module by path (its name starts with a digit) and run
+ # the backfill against the live connection — exercising the actual raw SQL.
+ path = os.path.join(os.path.dirname(os.path.dirname(__file__)),
+ 'migrations', 'versions', '015_workspace_scope.py')
+ spec = importlib.util.spec_from_file_location('mig015', path)
+ mig = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mig)
+
+ mig._backfill(db.session.connection())
+ db.session.commit()
+
+ default = Workspace.query.filter_by(slug='default').first()
+ assert default is not None
+ assert Application.query.filter_by(name='bf-app').first().workspace_id == default.id
+ assert Server.query.filter_by(name='bf-srv').first().workspace_id == default.id
+ assert WorkspaceMember.query.filter_by(workspace_id=default.id, user_id=u1.id).first() is not None
+ assert WorkspaceMember.query.filter_by(workspace_id=default.id, user_id=u2.id).first() is not None
+
+ # Idempotent: a second run creates no duplicate members and doesn't error.
+ mig._backfill(db.session.connection())
+ db.session.commit()
+ assert WorkspaceMember.query.filter_by(workspace_id=default.id, user_id=u1.id).count() == 1
+ assert Workspace.query.filter_by(slug='default').count() == 1
+
+
+# ---- API: servers ---------------------------------------------------------
+
+def test_servers_list_global_without_context(app, client):
+ from app import db
+ from app.models import Server
+
+ admin = _mk_user(db, 'srv_admin', 'admin')
+ dev = _mk_user(db, 'srv_dev', 'developer')
+ db.session.add(Server(name='srv-a', registered_by=admin.id))
+ db.session.commit()
+
+ # Servers are global today: a non-admin with no workspace context still sees them.
+ r = client.get('/api/v1/servers', headers=_token(dev.id))
+ assert r.status_code == 200
+ assert any(s['name'] == 'srv-a' for s in r.get_json())
diff --git a/docs/WORDPRESS_ROADMAP.md b/docs/WORDPRESS_ROADMAP.md
index 96bbbfd6..f266a323 100644
--- a/docs/WORDPRESS_ROADMAP.md
+++ b/docs/WORDPRESS_ROADMAP.md
@@ -291,13 +291,14 @@ Highest-effort, broadest surface — but by now the `WordPressSite` is a first-c
- **Done when:** Each site exposes scoped SFTP credentials.
- **Assessment / why deferred:** The roadmap's host-sshd-chroot approach doesn't fit the Docker model — a managed site's files live in the `wordpress_html` **named volume**, not a host path, so a host-level chroot would target the wrong place. The **Docker-correct** design is a per-site **SFTP sidecar container** (e.g. `atmoz/sftp`) mounting `wordpress_html`, injected into the compose stack exactly like #23's redis (`_ensure_*_in_stack` + additive `compose up -d`), with a generated credential surfaced once and a new mapped port (via the template's port-allocation). That is genuinely implementable on the proven pattern — but it (a) opens a **publicly-exposed, security-sensitive file-access surface** that should be firewalled and that I cannot runtime-verify from the dev host, and (b) consumes a port + a container per site. Shipping security-sensitive infra blind violates the quality bar, so this is deferred for a focused pass on a real Docker host (where the sidecar, chroot perms, and firewall can be exercised). No code shipped.
-### #33 — Agency scale (workspaces, RBAC, white-label, reports) `[XL]` 🟡 — 🟡 In progress (reports slice ✅ shipped; `workspace_id` FKs + per-site ACL + server-side branding still deferred as a milestone)
+### #33 — Agency scale (workspaces, RBAC, white-label, reports) `[XL]` 🟡 — 🟡 In progress (reports slice ✅ + `workspace_id` scoping foundation ✅ shipped; broad route adoption + per-site ACL + workspace↔User role reconciliation + server-side branding + frontend workspace selector still deferred)
- **Today:** No `workspace_id` FK on `Application`/`WordPressSite`/`Server`; permissions are global with no per-site ACL; white-label lives in `localStorage` and never reads `Workspace.logo_url`/`primary_color`.
- **Do:** Add `workspace_id` FKs + per-site ACL rows + environment-tier RBAC in promote/sync/bulk endpoints; server-side branding scoped to workspace; monthly client reports aggregating uptime/updates/backups/security.
- **Reuse:** `workspace_service`, `permission_service`, `audit_service`.
- **Done when:** A site/environment can be scoped to a workspace with per-site roles and branded reports.
- **Assessment / why deferred:** A genuine **`XL`** multi-day epic (the roadmap's own guidance is "split before starting"), and it cuts across the whole system rather than the WordPress object: (1) `workspace_id` FK migrations on `Application`/`WordPressSite`/`Server` + backfill + scoping *every* list/query; (2) a per-site **ACL** model + enforcement woven through promote/sync/bulk endpoints; (3) moving white-label from `localStorage` to server-rendered, workspace-scoped branding; (4) a monthly **reports** generator aggregating the now-existing uptime (#26) / updates (#29) / backups / security (#28/#30) signals. Each sub-part is its own feature; done together they're a milestone, not a single change — and the cross-cutting FK + RBAC rework is high-blast-radius. **Foundation now in place from this session:** the report's data sources (per-site uptime/incidents #26, update history #29, vuln findings #28) all exist, so the reports sub-feature is the most self-contained slice to start with. Deferred to a dedicated milestone.
- **Landed (reports slice):** the self-contained **monthly client reports** sub-feature shipped — the milestone's first slice, deliberately built *without* the high-blast-radius `workspace_id` rework. New `WpReportsService` aggregates a calendar month's signals into a single persisted, printable report: **uptime % + a daily series + incidents** re-aggregated from the bound status component's `HealthCheck` samples for the exact month (#26), **update runs** (counts + components-updated, #29), **DatabaseSnapshot backups** (count + bytes), and the **current vulnerability posture** (#28) + health/disk — each section honestly labelled PERSISTED-history vs point-in-time (vulns are snapshot-replaced each scan, so they're captured *as-of* generation; traffic/on-demand security scans are noted as excluded). **Why persisted, not live:** generation snapshots the point-in-time sources so a report regenerated months later still shows the right month's posture; the true-historical sources are re-queried per month. Generation is **synchronous** (pure DB aggregation — no WP-CLI/HTTP, so no background thread), and **upserts** per `(site, YYYY-MM)` so regenerating replaces. Client grouping is derived from the **`client-*` / `client:*` tag** (#20) — *no* `workspace_id` FK needed. New `WordPressReport` model (Alembic **014**, chains off `013_ai_assistant`; defined in `wordpress_site.py` + imported lazily in the service so the concurrent AI agent's `models/__init__.py` is never touched), routes `GET /sites/<id>/reports`, `POST …/reports/generate` (`@admin_required`), `DELETE …/reports/<rid>`, client `getReports`/`generateReport`/`deleteReport`, and a new **Reports tab** (month picker → generate, per-month selector, a recharts daily-uptime chart, summary stat cards, incident/update/backup/vuln sections) with a **Print → Save-as-PDF** path (scoped `@media print` isolation, no PDF dependency) and a **Download JSON** export. Verified: backend `py_compile`, **9 new pytest tests** (helpers, bound + unbound aggregation, upsert, future-month guard, API round-trip, + 2 regression tests for review fixes), frontend lint-clean + production build, and a 3-lens adversarial review (5 findings; 4 fixed — daily-series future-day off-by-one, ongoing-incident duration clamped to the in-month window, dead error branch, robust print-cleanup; the 5th — admin-only buttons shown to non-admin owners — left for parity with #28/#29/#30 which do the same). *(Still deferred for the dedicated milestone: cross-cutting `workspace_id` FKs + per-site ACL + server-side workspace-scoped branding. The report already inherits the operator's existing client-side white-label in-app; server-side branding upgrades cleanly later by feeding the same `{name, logo, color}` triplet into the print view.)* Not runtime-exercised on a real Docker host (Windows dev).
+- **Landed (workspace foundation slice):** the cross-cutting backbone the rest of #33 needs — a **nullable `workspace_id` FK** on `applications` + `servers` (Alembic **015**, chains off `014`, with an idempotent raw-SQL backfill that creates a **Default** workspace, attaches every workspace-less row, and makes every existing user a member so nobody loses visibility) + a **centralized scope helper** in `WorkspaceService` (`ensure_default_workspace`, `resolve_workspace_id`, `scope_query`). The design rule is **opt-in + narrow-only**: a request only filters by workspace when it carries an `X-Workspace-Id` header / `?workspace_id=`, and `scope_query` *intersects* the workspace filter with the existing per-user ownership filter so it can only ever **narrow** visibility, never broaden it — with no workspace context the behavior is byte-identical to before (admin→all, owner→own apps, servers global). Wired into `apps.py` (list + create) and `servers.py` (list + create), replacing the duplicated `if admin … else filter_by(user_id)` branch and **stamping** new resources with the active-or-default workspace. **Deliberately *not* a 36-route rewrite:** this lands the mechanism + the two core resource surfaces as the proven pattern; broad route adoption, per-site ACL, the workspace↔User role reconciliation, server-side branding, and a frontend active-workspace selector are the follow-on slices. Verified: backend `py_compile`, **10 new pytest tests** (helper branches, scope-narrowing, an explicit *can't-broaden-access* regression, deactivated-user gate, default-stamping, the raw-SQL backfill run against real SQLite + idempotency), full suite **120 passed**, a real end-to-end `alembic upgrade` to `015` on a fresh DB (columns + both indexes created), and a 2-lens adversarial review (3 findings, all fixed — `is_active` gate on the workspace path, FK-add guarded on the `workspaces` table existing, and the missing `workspace_id` indexes for upgraded installs). The earlier draft's biggest risk — that the backfill (everything→Default, everyone→member) plus a workspace filter would let a non-admin enumerate *all* resources via the default workspace — was caught and fixed pre-review by making `scope_query` intersect with ownership.
### #34 — Horizontal scaling `[XL]` ❌ — ⏸️ Deferred (XL + blocked on the same per-site reverse-proxy/upstream layer as #21)
- **Today:** `nginx_advanced_service` has load-balancing primitives (round-robin/least-conn/IP-hash) but WP containers are stateful (local uploads, no shared object cache).