Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

Add per-workspace data retention and a GDPR design note (CHOO-3047)

Petr Bauchc584aa97ccac
diff --git a/CLAUDE.md b/CLAUDE.md
index 3c008a09b..b6efb7feb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -221,6 +221,10 @@ Tests live in `core/tests/switch_core/` mirroring the module structure. Uses pyt
- `docs/old/key-rotation.md` — the server's keys (`SECRET_KEYS`): what each
derived key protects, moving a deployment off `JWT_SECRET_KEY`, and the
rotation runbook
+- `docs/design/data-retention.md` — what Switch deletes: the per-workspace
+ message-retention window, the orphaned-file sweep, the leftover records
+ pruned after a grace period, and a GDPR design note for what is not built
+ (erasing a person, export, workspace deletion, audit-log horizon)
- `docs/old/rds-migration.md` — moving a deployment's Postgres to RDS: the
proposal and the cutover runbook
diff --git a/core/switch_core/accounts/deletion.py b/core/switch_core/accounts/deletion.py
index 0d1e263be..95f13fcd7 100644
--- a/core/switch_core/accounts/deletion.py
+++ b/core/switch_core/accounts/deletion.py
@@ -160,6 +160,7 @@ USER_REFERENCES: dict[tuple[str, str], Handling] = {
("clients", "user_id"): "database clears",
("organization_app_credentials", "updated_by"): "database clears",
("organization_service_settings", "updated_by"): "database clears",
+ ("tenant_retention_policies", "updated_by_user_id"): "database clears",
}
diff --git a/core/switch_core/accounts/workspace_deletion.py b/core/switch_core/accounts/workspace_deletion.py
index 6c223fab4..7b2893724 100644
--- a/core/switch_core/accounts/workspace_deletion.py
+++ b/core/switch_core/accounts/workspace_deletion.py
@@ -142,6 +142,7 @@ WORKSPACE_TABLES: dict[str, Handling] = {
"template_installs": "deleted",
"tenant_data_moves": "deleted",
"tenant_join_domains": "deleted",
+ "tenant_retention_policies": "deleted",
"tenant_usage": "deleted",
"usage_budgets": "deleted",
"workspace_service_settings": "deleted",
diff --git a/core/switch_core/db/audit.py b/core/switch_core/db/audit.py
index 5f9de0ff0..a9ea04679 100644
--- a/core/switch_core/db/audit.py
+++ b/core/switch_core/db/audit.py
@@ -74,6 +74,8 @@ class AuditAction(StrEnum):
WORKSPACE_SERVICE_DISABLED = "workspace_service.disabled"
WORKSPACE_SERVICE_CLEARED = "workspace_service.cleared"
OWNERSHIP_TRANSFERRED = "ownership.transferred"
+ RETENTION_POLICY_SET = "retention_policy.set"
+ RETENTION_POLICY_CLEARED = "retention_policy.cleared"
class OrganizationAuditAction(StrEnum):
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index e017b32ba..3fc22a574 100644
--- a/core/switch_core/db/models.py
+++ b/core/switch_core/db/models.py
@@ -1214,6 +1214,12 @@ class Room(TenantScoped, Base):
archived_at: Mapped[str | None] = mapped_column(
DateTime(timezone=True), nullable=True
)
+ # The highest live `seq` retention has deleted from this room. Numbering
+ # continues above it, so a room emptied by retention never hands out a
+ # position a cursor has already passed. See `MessageStore._next_seq`.
+ seq_floor: Mapped[int] = mapped_column(
+ BigInteger, nullable=False, server_default=text("0")
+ )
# ── Room Groups ─────────────────────────────────────────────────────────────────
@@ -4053,6 +4059,45 @@ class UsageBudget(TenantScoped, Base):
)
+# ── Data retention ────────────────────────────────────────────────────────────
+
+#: The longest message-retention window a workspace may set, ten years.
+MAX_MESSAGE_RETENTION_DAYS = 3650
+
+
+class TenantRetentionPolicy(TenantScoped, Base):
+ """How long a workspace keeps its room messages.
+
+ At most one row per tenant. No row means messages are kept forever, which
+ is every workspace's starting point: deletion is something an owner or
+ admin turns on, never something a deployment does to them by default.
+
+ With a row, messages older than `message_retention_days` are deleted from
+ every room in the workspace, archived rooms included, along with their
+ attachments (`retention/service.py`).
+ """
+
+ __tablename__ = "tenant_retention_policies"
+ __table_args__ = (
+ PrimaryKeyConstraint("tenant_id"),
+ CheckConstraint(
+ f"message_retention_days >= 1 AND message_retention_days <= {MAX_MESSAGE_RETENTION_DAYS}",
+ name="ck_tenant_retention_policies_days",
+ ),
+ )
+
+ message_retention_days: Mapped[int] = mapped_column(Integer, nullable=False)
+ updated_by_user_id: Mapped[str | None] = mapped_column(
+ Text, ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+ )
+ updated_at: Mapped[datetime] = mapped_column(
+ DateTime(timezone=True),
+ server_default=func.now(),
+ onupdate=func.now(),
+ nullable=False,
+ )
+
+
# ── Agent management ──────────────────────────────────────────────────────────
# `api_keys.type` values that hold a hash and nothing else. Nothing may decrypt
diff --git a/core/switch_core/db/stores/message_store.py b/core/switch_core/db/stores/message_store.py
index 935fc5d84..73fd7489e 100644
--- a/core/switch_core/db/stores/message_store.py
+++ b/core/switch_core/db/stores/message_store.py
@@ -4,15 +4,17 @@ from datetime import datetime
from sqlalchemy import (
ColumnElement,
bindparam,
+ delete,
func,
or_,
select,
text,
+ update,
)
from sqlalchemy.ext.asyncio import AsyncSession
from switch_core.db.id_lists import any_of
-from switch_core.db.models import Message, MessageAttachment
+from switch_core.db.models import Message, MessageAttachment, Room, require_tenant_id
from switch_core.db.notify_ddl import SET_WRITER_ANNOUNCES
from switch_core.db.raw import RawStatement
@@ -195,13 +197,58 @@ class MessageStore:
so an empty live log answers 0 whatever has been backfilled into it.
With `types`, the position of the last row of those types.
"""
- query = select(func.coalesce(func.max(Message.seq), 0)).where(
- Message.room_id == room_id
- )
if types is not None:
- query = query.where(Message.event_type.in_(list(types)))
- result = await session.execute(query)
- return max(int(result.scalar_one()), 0)
+ result = await session.execute(
+ select(func.coalesce(func.max(Message.seq), 0)).where(
+ Message.room_id == room_id,
+ Message.event_type.in_(list(types)),
+ )
+ )
+ return max(int(result.scalar_one()), 0)
+ head = await _ROOM_HEAD.all(session, {"room_id": room_id})
+ return max(int(head[0].head), 0)
+
+ async def delete_sent_before(
+ self, session: AsyncSession, cutoff: datetime, *, limit: int
+ ) -> list[str]:
+ """Delete up to `limit` of the bound tenant's oldest messages sent before
+ `cutoff`, with their attachments. Returns their transport event ids.
+
+ Each room's `seq_floor` is raised to the highest live position deleted
+ from it, in the same transaction, so `_next_seq` never reissues one.
+ The bytes behind the attachments are not touched: a blob may be quoted
+ by a message that is kept, so `MediaStore.delete_unreferenced` finds
+ the ones nothing points at any more.
+ """
+ rows = (
+ await session.execute(
+ select(
+ Message.id, Message.room_id, Message.seq, Message.transport_event_id
+ )
+ .where(
+ Message.tenant_id == require_tenant_id(),
+ Message.sent_at < cutoff,
+ )
+ .order_by(Message.sent_at)
+ .limit(limit)
+ )
+ ).all()
+ if not rows:
+ return []
+ floors: dict[str, int] = {}
+ for row in rows:
+ floors[row.room_id] = max(floors.get(row.room_id, 0), row.seq)
+ for room_id, seq in floors.items():
+ if seq > 0:
+ await session.execute(
+ update(Room)
+ .where(Room.id == room_id)
+ .values(seq_floor=func.greatest(Room.seq_floor, seq))
+ )
+ await session.execute(
+ delete(Message).where(Message.id.in_([r.id for r in rows]))
+ )
+ return [row.transport_event_id for row in rows]
async def head_seqs(
self,
@@ -225,6 +272,14 @@ class MessageStore:
query = query.where(Message.event_type.in_(list(types)))
result = await session.execute(query.group_by(Message.room_id))
heads = {room_id: max(int(seq or 0), 0) for room_id, seq in result.all()}
+ if types is None:
+ floors = await session.execute(
+ select(Room.id, Room.seq_floor).where(
+ any_of(Room.id, room_ids), Room.seq_floor > 0
+ )
+ )
+ for room_id, floor in floors.all():
+ heads[room_id] = max(heads.get(room_id, 0), int(floor))
return {room_id: heads.get(room_id, 0) for room_id in room_ids}
async def rooms_past(
@@ -440,9 +495,21 @@ _LOCK_ROOM = RawStatement(text("SELECT pg_advisory_xact_lock(hashtext(:room_id))
_LOCK_ROOM_ANNOUNCED_BY_WRITER = RawStatement(
text(f"SELECT pg_advisory_xact_lock(hashtext(:room_id)), {SET_WRITER_ANNOUNCES}")
)
+# The highest position the room has ever used: usually its newest row, but
+# retention may have deleted that row while a cursor that read it is still
+# past it. `rooms.seq_floor` remembers the highest live position retention
+# removed; both are read in one statement, so a deletion committing between
+# them cannot be half-seen.
_ROOM_HEAD = RawStatement(
- select(func.coalesce(func.max(Message.seq), 0).label("head")).where(
- Message.room_id == bindparam("room_id")
+ select(
+ func.greatest(
+ select(func.coalesce(func.max(Message.seq), 0))
+ .where(Message.room_id == bindparam("room_id"))
+ .scalar_subquery(),
+ select(func.coalesce(func.max(Room.seq_floor), 0))
+ .where(Room.id == bindparam("room_id"))
+ .scalar_subquery(),
+ ).label("head")
)
)
diff --git a/core/switch_core/db/stores/retention_store.py b/core/switch_core/db/stores/retention_store.py
new file mode 100644
index 000000000..3909aae52
--- /dev/null
+++ b/core/switch_core/db/stores/retention_store.py
@@ -0,0 +1,198 @@
+"""What data retention reads and deletes, for the bound tenant.
+
+The workspace's policy lives here, and so does every deletion retention makes
+apart from messages themselves, which `MessageStore.delete_sent_before` owns
+because deleting them has to keep the room's numbering intact.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from datetime import datetime
+from typing import Any, cast
+
+from sqlalchemy import CursorResult, Result, delete, func, select, text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from switch_core.db.models import (
+ ApprovalRequest,
+ BridgeMessageMap,
+ Invitation,
+ Message,
+ MessagingInstallState,
+ TenantRetentionPolicy,
+ require_tenant_id,
+)
+
+# A blob is written before the message that carries it, in a separate
+# transaction, and a hosted cutover may hold one for an import it has not
+# queued yet. Both are referenced by something other than an attachment row,
+# so a blob is only a candidate once it has had time to gain one, and is
+# never one while a live import names it.
+_UNREFERENCED_BLOBS = """
+ SELECT b.id FROM media_blobs b
+ WHERE b.tenant_id = :tenant_id
+ AND b.created_at < :created_before
+ AND NOT EXISTS (
+ SELECT 1 FROM message_attachments a
+ WHERE a.tenant_id = b.tenant_id AND a.uri = b.uri)
+ AND NOT EXISTS (
+ SELECT 1 FROM hosted_cutover_items i
+ JOIN hosted_launches l ON l.tenant_id = i.tenant_id AND l.id = i.launch_id
+ AND l.state NOT IN ('deleting', 'deleted')
+ CROSS JOIN LATERAL jsonb_array_elements(
+ COALESCE(i.payload->'payload'->'attachments', '[]'::jsonb)) f
+ WHERE i.tenant_id = b.tenant_id AND i.disposition = 'import'
+ AND f->>'mxc' = b.uri)
+ ORDER BY b.created_at
+ LIMIT :limit
+"""
+
+
+def _rowcount(result: Result[Any]) -> int:
+ return cast("CursorResult[Any]", result).rowcount
+
+
+class RetentionStore:
+ async def get_policy(self, session: AsyncSession) -> TenantRetentionPolicy | None:
+ return await session.get(TenantRetentionPolicy, require_tenant_id())
+
+ async def set_policy(
+ self, session: AsyncSession, *, message_retention_days: int, user_id: str
+ ) -> TenantRetentionPolicy:
+ policy = await self.get_policy(session)
+ if policy is None:
+ policy = TenantRetentionPolicy(
+ tenant_id=require_tenant_id(),
+ message_retention_days=message_retention_days,
+ updated_by_user_id=user_id,
+ )
+ session.add(policy)
+ else:
+ policy.message_retention_days = message_retention_days
+ policy.updated_by_user_id = user_id
+ await session.flush()
+ await session.refresh(policy)
+ return policy
+
+ async def clear_policy(self, session: AsyncSession) -> bool:
+ """Remove the policy, so messages are kept forever. Whether there was one."""
+ result = await session.execute(
+ delete(TenantRetentionPolicy).where(
+ TenantRetentionPolicy.tenant_id == require_tenant_id()
+ )
+ )
+ return _rowcount(result) > 0
+
+ async def count_messages_before(
+ self, session: AsyncSession, cutoff: datetime
+ ) -> int:
+ """How many of the bound tenant's messages a cutoff would delete."""
+ result = await session.execute(
+ select(func.count())
+ .select_from(Message)
+ .where(Message.tenant_id == require_tenant_id(), Message.sent_at < cutoff)
+ )
+ return int(result.scalar_one())
+
+ async def delete_bridge_mappings(
+ self, session: AsyncSession, transport_event_ids: Collection[str]
+ ) -> int:
+ """Forget which platform posts carried these (deleted) messages."""
+ if not transport_event_ids:
+ return 0
+ result = await session.execute(
+ delete(BridgeMessageMap).where(
+ BridgeMessageMap.tenant_id == require_tenant_id(),
+ BridgeMessageMap.transport_event_id.in_(list(transport_event_ids)),
+ )
+ )
+ return _rowcount(result)
+
+ async def delete_unreferenced_media(
+ self, session: AsyncSession, *, created_before: datetime, limit: int
+ ) -> int:
+ """Delete up to `limit` stored files nothing refers to any more."""
+ ids = list(
+ (
+ await session.execute(
+ text(_UNREFERENCED_BLOBS),
+ {
+ "tenant_id": require_tenant_id(),
+ "created_before": created_before,
+ "limit": limit,
+ },
+ )
+ ).scalars()
+ )
+ if not ids:
+ return 0
+ await session.execute(
+ text("DELETE FROM media_blobs WHERE id = ANY(:ids)"), {"ids": ids}
+ )
+ return len(ids)
+
+ async def delete_settled_approvals(
+ self, session: AsyncSession, before: datetime
+ ) -> int:
+ """Delete approval requests that were settled before `before`.
+
+ Settled means nothing still waits on the row: closed, or answered or
+ expired and already delivered to the agent. An answer still owed to an
+ agent is kept however old it is.
+ """
+ result = await session.execute(
+ delete(ApprovalRequest).where(
+ ApprovalRequest.tenant_id == require_tenant_id(),
+ ApprovalRequest.updated_at < before,
+ (ApprovalRequest.state == "closed")
+ | (
+ ApprovalRequest.state.in_(("answered", "expired"))
+ & ApprovalRequest.delivered_at.is_not(None)
+ ),
+ )
+ )
+ await session.execute(
+ text(
+ """
+ DELETE FROM approval_request_posts p
+ WHERE p.tenant_id = :tenant_id AND p.created_at < :before
+ AND NOT EXISTS (
+ SELECT 1 FROM approval_requests r
+ WHERE r.tenant_id = p.tenant_id AND r.agent_id = p.agent_id
+ AND r.session_id = p.session_id
+ AND r.request_id = p.request_id)
+ """
+ ),
+ {"tenant_id": require_tenant_id(), "before": before},
+ )
+ return _rowcount(result)
+
+ async def delete_lapsed_invitations(
+ self, session: AsyncSession, before: datetime
+ ) -> int:
+ """Delete invitations that expired or were revoked before `before`."""
+ result = await session.execute(
+ delete(Invitation).where(
+ Invitation.tenant_id == require_tenant_id(),
+ (Invitation.expires_at < before) | (Invitation.revoked_at < before),
+ )
+ )
+ return _rowcount(result)
+
+ async def delete_expired_install_states(
+ self, session: AsyncSession, before: datetime
+ ) -> int:
+ """Delete messaging install states that expired before `before`.
+
+ A state is single-use evidence only while its signed token could still
+ be presented; once it has expired a replay is refused whether or not
+ the row is there.
+ """
+ result = await session.execute(
+ delete(MessagingInstallState).where(
+ MessagingInstallState.tenant_id == require_tenant_id(),
+ MessagingInstallState.expires_at < before,
+ )
+ )
+ return _rowcount(result)
diff --git a/core/switch_core/gateway/dependencies.py b/core/switch_core/gateway/dependencies.py
index 0f3b90d00..d8d31b2bc 100644
--- a/core/switch_core/gateway/dependencies.py
+++ b/core/switch_core/gateway/dependencies.py
@@ -25,6 +25,7 @@ from switch_core.db.stores.invitation_store import InvitationStore
from switch_core.db.stores.join_domain_store import JoinDomainStore
from switch_core.db.stores.messaging_install_store import MessagingInstallStore
from switch_core.db.stores.organization_store import OrganizationStore
+from switch_core.db.stores.retention_store import RetentionStore
from switch_core.db.stores.room_group_store import RoomGroupStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.template_store import TemplateStore
@@ -229,6 +230,10 @@ def get_budget_store() -> BudgetStore:
return _state["budget_store"] # type: ignore[no-any-return]
+def get_retention_store() -> RetentionStore:
+ return RetentionStore()
+
+
def get_template_store() -> TemplateStore:
return _state["template_store"] # type: ignore[no-any-return]
diff --git a/core/switch_core/gateway/schemas.py b/core/switch_core/gateway/schemas.py
index 5d053bbe9..628f2f3a4 100644
--- a/core/switch_core/gateway/schemas.py
+++ b/core/switch_core/gateway/schemas.py
@@ -24,6 +24,7 @@ from switch_core.db.audit import OrganizationIssueKind
from switch_core.db.models import (
MAX_BUDGET_AMOUNT,
MAX_BUDGET_PERIOD_HOURS,
+ MAX_MESSAGE_RETENTION_DAYS,
UsageMetric,
)
@@ -2022,3 +2023,26 @@ class SlackTokensChecked(BaseModel):
workspace_id: str
workspace_name: str
bot_name: str
+
+
+# ── Data retention ──────────────────────────────────────────────────────────
+
+
+class RetentionPolicyRequest(BaseModel):
+ message_retention_days: int = Field(ge=1, le=MAX_MESSAGE_RETENTION_DAYS)
+
+
+class RetentionPolicyResponse(BaseModel):
+ """The workspace's retention policy. `message_retention_days` null means
+ messages are kept forever."""
+
+ message_retention_days: int | None
+ updated_at: datetime | None
+ updated_by_user_id: str | None
+
+
+class RetentionPreviewResponse(BaseModel):
+ """What a window would delete if it applied now."""
+
+ message_retention_days: int
+ messages_to_delete: int
diff --git a/core/switch_core/gateway/tenants.py b/core/switch_core/gateway/tenants.py
index ee2ed06e9..4faa17adc 100644
--- a/core/switch_core/gateway/tenants.py
+++ b/core/switch_core/gateway/tenants.py
@@ -37,6 +37,7 @@ from switch_core.db.audit import (
record_audit_event,
)
from switch_core.db.models import (
+ MAX_MESSAGE_RETENTION_DAYS,
Invitation,
Organization,
OrganizationMember,
@@ -64,6 +65,7 @@ from switch_core.db.stores.join_domain_store import (
JoinDomainStore,
)
from switch_core.db.stores.organization_store import OrganizationStore
+from switch_core.db.stores.retention_store import RetentionStore
from switch_core.db.stores.usage_store import UsageStore
from switch_core.db.stores.user_store import UserStore
from switch_core.gateway.auth import (
@@ -96,6 +98,7 @@ from switch_core.gateway.dependencies import (
get_organization_directory,
get_organization_store,
get_protocol,
+ get_retention_store,
get_session,
get_session_factory,
get_system_session,
@@ -128,6 +131,9 @@ from switch_core.gateway.schemas import (
MemberDetail,
MemberUpdateRequest,
OperatorWorkspaceResponse,
+ RetentionPolicyRequest,
+ RetentionPolicyResponse,
+ RetentionPreviewResponse,
SessionUserResponse,
TenantCreateRequest,
TenantDeleteRequest,
@@ -783,6 +789,119 @@ async def delete_budget(
return Response(status_code=204)
+def _retention_response(
+ days: int | None, updated_at: datetime | None, updated_by: str | None
+) -> RetentionPolicyResponse:
+ return RetentionPolicyResponse(
+ message_retention_days=days,
+ updated_at=updated_at,
+ updated_by_user_id=updated_by,
+ )
+
+
[email protected]("/tenants/{tenant_id}/retention")
+async def get_retention_policy(
+ tenant_id: str,
+ session: Annotated[AsyncSession, Depends(get_session)],
+ retention_store: Annotated[RetentionStore, Depends(get_retention_store)],
+ _user: Annotated[User, Depends(require_tenant_admin)],
+) -> RetentionPolicyResponse:
+ """How long the bound tenant keeps room messages. Admins only."""
+ _require_bound_tenant(tenant_id)
+ policy = await retention_store.get_policy(session)
+ if policy is None:
+ return _retention_response(None, None, None)
+ return _retention_response(
+ policy.message_retention_days, policy.updated_at, policy.updated_by_user_id
+ )
+
+
[email protected]("/tenants/{tenant_id}/retention/preview")
+async def preview_retention_policy(
+ tenant_id: str,
+ session: Annotated[AsyncSession, Depends(get_session)],
+ retention_store: Annotated[RetentionStore, Depends(get_retention_store)],
+ _user: Annotated[User, Depends(require_tenant_admin)],
+ days: Annotated[int, Query(ge=1, le=MAX_MESSAGE_RETENTION_DAYS)],
+) -> RetentionPreviewResponse:
+ """How many messages a window of `days` would delete if it applied now,
+ so the change can be confirmed before it is made. Admins only."""
+ _require_bound_tenant(tenant_id)
+ count = await retention_store.count_messages_before(
+ session, datetime.now(UTC) - timedelta(days=days)
+ )
+ return RetentionPreviewResponse(
+ message_retention_days=days, messages_to_delete=count
+ )
+
+
[email protected]("/tenants/{tenant_id}/retention")
+async def set_retention_policy(
+ tenant_id: str,
+ body: RetentionPolicyRequest,
+ session: Annotated[AsyncSession, Depends(get_session)],
+ retention_store: Annotated[RetentionStore, Depends(get_retention_store)],
+ user: Annotated[User, Depends(require_tenant_admin)],
+) -> RetentionPolicyResponse:
+ """Delete the bound tenant's room messages once they are older than
+ `message_retention_days`. Admins only.
+
+ Takes effect at the next hourly retention pass, not in this request.
+ """
+ _require_bound_tenant(tenant_id)
+ previous = await retention_store.get_policy(session)
+ previous_days = None if previous is None else previous.message_retention_days
+ policy = await retention_store.set_policy(
+ session, message_retention_days=body.message_retention_days, user_id=user.id
+ )
+ await record_audit_event(
+ session,
+ tenant_id=tenant_id,
+ actor_user_id=user.id,
+ action=AuditAction.RETENTION_POLICY_SET,
+ target_type="tenant",
+ target_id=tenant_id,
+ details={
+ "message_retention_days": body.message_retention_days,
+ "previous_message_retention_days": previous_days,
+ },
+ )
+ await session.commit()
+ return _retention_response(
+ policy.message_retention_days, policy.updated_at, policy.updated_by_user_id
+ )
+
+
[email protected]("/tenants/{tenant_id}/retention")
+async def clear_retention_policy(
+ tenant_id: str,
+ session: Annotated[AsyncSession, Depends(get_session)],
+ retention_store: Annotated[RetentionStore, Depends(get_retention_store)],
+ user: Annotated[User, Depends(require_tenant_admin)],
+) -> RetentionPolicyResponse:
+ """Keep the bound tenant's messages forever. Admins only.
+
+ Messages already deleted stay deleted. Clearing a policy that is not set
+ succeeds and records nothing.
+ """
+ _require_bound_tenant(tenant_id)
+ previous = await retention_store.get_policy(session)
+ if previous is not None:
+ previous_days = previous.message_retention_days
+ await retention_store.clear_policy(session)
+ await record_audit_event(
+ session,
+ tenant_id=tenant_id,
+ actor_user_id=user.id,
+ action=AuditAction.RETENTION_POLICY_CLEARED,
+ target_type="tenant",
+ target_id=tenant_id,
+ details={"previous_message_retention_days": previous_days},
+ )
+ await session.commit()
+ return _retention_response(None, None, None)
+
+
@router.get("/tenants/{tenant_id}/invitations")
async def list_invitations(
tenant_id: str,
diff --git a/core/switch_core/migrations/versions/d8a4e2c61f07_data_retention.py b/core/switch_core/migrations/versions/d8a4e2c61f07_data_retention.py
new file mode 100644
index 000000000..9e9451a42
--- /dev/null
+++ b/core/switch_core/migrations/versions/d8a4e2c61f07_data_retention.py
@@ -0,0 +1,81 @@
+"""data retention: a per-workspace message window, and a seq floor per room
+
+``tenant_retention_policies`` holds at most one row per tenant: how many days
+of room messages that workspace keeps. No row means messages are kept forever,
+so nothing changes for existing tenants when this runs.
+
+``rooms.seq_floor`` records the highest live ``seq`` retention has deleted
+from a room, so numbering continues above it when a room's newest messages
+are among those deleted. It starts at 0, which changes nothing for a room
+retention has never touched.
+
+The row-level-security DDL is a verbatim copy of ``switch_core/db/rls_ddl.py``
+as it stood when this migration was written, copied rather than imported for
+the reason ``265ed188ad6f`` gives.
+
+Revision ID: d8a4e2c61f07
+Revises: a3d9f6c2b871
+Create Date: 2026-10-06 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "d8a4e2c61f07"
+down_revision: str | None = "a3d9f6c2b871"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+REQUIRE_TENANT_FUNCTION_NAME = "require_tenant_id"
+POLICY_NAME = "tenant_isolation"
+
+_PREDICATE = f'"tenant_id" = (SELECT {REQUIRE_TENANT_FUNCTION_NAME}())'
+_CREATE_POLICY = (
+ f'CREATE POLICY {POLICY_NAME} ON "tenant_retention_policies"\n'
+ f" FOR ALL\n"
+ f" USING ({_PREDICATE})\n"
+ f" WITH CHECK ({_PREDICATE})"
+)
+
+
+def upgrade() -> None:
+ op.add_column(
+ "rooms",
+ sa.Column(
+ "seq_floor", sa.BigInteger(), server_default=sa.text("0"), nullable=False
+ ),
+ )
+ op.create_table(
+ "tenant_retention_policies",
+ sa.Column("tenant_id", sa.Text(), nullable=False),
+ sa.Column("message_retention_days", sa.Integer(), nullable=False),
+ sa.Column("updated_by_user_id", sa.Text(), nullable=True),
+ sa.Column(
+ "updated_at",
+ sa.DateTime(timezone=True),
+ server_default=sa.text("now()"),
+ nullable=False,
+ ),
+ sa.ForeignKeyConstraint(
+ ["tenant_id"], ["tenants.id"], name="fk_tenant_retention_policies_tenant"
+ ),
+ sa.ForeignKeyConstraint(
+ ["updated_by_user_id"], ["users.id"], ondelete="SET NULL"
+ ),
+ sa.CheckConstraint(
+ "message_retention_days >= 1 AND message_retention_days <= 3650",
+ name="ck_tenant_retention_policies_days",
+ ),
+ sa.PrimaryKeyConstraint("tenant_id"),
+ )
+ op.execute('ALTER TABLE "tenant_retention_policies" ENABLE ROW LEVEL SECURITY')
+ op.execute(_CREATE_POLICY)
+
+
+def downgrade() -> None:
+ op.execute(f'DROP POLICY IF EXISTS {POLICY_NAME} ON "tenant_retention_policies"')
+ op.drop_table("tenant_retention_policies")
+ op.drop_column("rooms", "seq_floor")
diff --git a/core/switch_core/retention/__init__.py b/core/switch_core/retention/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/core/switch_core/retention/service.py b/core/switch_core/retention/service.py
new file mode 100644
index 000000000..eba84211b
--- /dev/null
+++ b/core/switch_core/retention/service.py
@@ -0,0 +1,136 @@
+"""Data retention: deleting what a workspace no longer keeps.
+
+One pass over the bound tenant does three things, each in its own short
+transactions so a large backlog never holds a long lock:
+
+1. If the workspace has a retention policy, deletes room messages older than
+ its window, from every room, archived ones included. Their attachment rows
+ go with them, and the record of which platform post carried each.
+2. Deletes stored files nothing refers to any more, whether their messages
+ were deleted by step 1 or by deleting a room. This runs whatever the
+ policy: an orphaned file is not something any workspace chose to keep.
+3. Deletes settled approval requests, lapsed invitations and expired install
+ links once `SETTLED_GRACE` has passed.
+
+The audit log and usage records are never touched; `docs/design/data-retention.md`
+says why, and what retention does not yet cover.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import require_tenant_id
+from switch_core.db.session_scope import tenant_session
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.db.stores.retention_store import RetentionStore
+
+logger = logging.getLogger(__name__)
+
+#: How long a settled approval, lapsed invitation or expired install link is
+#: kept, so an operator asking what happened to one can still see it.
+SETTLED_GRACE = timedelta(days=30)
+#: How old an unreferenced file must be before it is deleted; see
+#: `retention_store._UNREFERENCED_BLOBS`.
+MEDIA_GRACE = timedelta(days=1)
+MESSAGE_BATCH = 1000
+MEDIA_BATCH = 100
+#: Batches of each kind per pass. A backlog larger than this (the first pass
+#: after a short window is set on a long-lived workspace) is finished by the
+#: passes after it rather than by one that runs for an hour.
+MAX_BATCHES = 50
+
+
+@dataclass(frozen=True)
+class RetentionPass:
+ messages: int
+ media: int
+ approvals: int
+ invitations: int
+ install_states: int
+ backlog: bool
+
+
+class RetentionService:
+ def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
+ self._sessions = session_factory
+ self._messages = MessageStore()
+ self._retention = RetentionStore()
+
+ async def apply(self, now: datetime) -> RetentionPass:
+ """One retention pass over the bound tenant."""
+ tenant_id = require_tenant_id()
+ async with tenant_session(self._sessions, tenant_id) as db:
+ policy = await self._retention.get_policy(db)
+ days = None if policy is None else policy.message_retention_days
+
+ messages, message_backlog = (
+ (0, False)
+ if days is None
+ else await self._delete_messages(tenant_id, now - timedelta(days=days))
+ )
+ media, media_backlog = await self._delete_media(tenant_id, now - MEDIA_GRACE)
+
+ settled_before = now - SETTLED_GRACE
+ async with tenant_session(self._sessions, tenant_id) as db, db.begin():
+ approvals = await self._retention.delete_settled_approvals(
+ db, settled_before
+ )
+ invitations = await self._retention.delete_lapsed_invitations(
+ db, settled_before
+ )
+ install_states = await self._retention.delete_expired_install_states(
+ db, settled_before
+ )
+
+ result = RetentionPass(
+ messages=messages,
+ media=media,
+ approvals=approvals,
+ invitations=invitations,
+ install_states=install_states,
+ backlog=message_backlog or media_backlog,
+ )
+ if result.backlog:
+ logger.warning(
+ "Retention in tenant %s stopped at its per-pass limit with more "
+ "to delete; the next pass continues (%s)",
+ tenant_id,
+ result,
+ )
+ elif messages or media or approvals or invitations or install_states:
+ logger.info("Retention in tenant %s: %s", tenant_id, result)
+ return result
+
+ async def _delete_messages(
+ self, tenant_id: str, cutoff: datetime
+ ) -> tuple[int, bool]:
+ deleted = 0
+ for _ in range(MAX_BATCHES):
+ async with tenant_session(self._sessions, tenant_id) as db, db.begin():
+ event_ids = await self._messages.delete_sent_before(
+ db, cutoff, limit=MESSAGE_BATCH
+ )
+ await self._retention.delete_bridge_mappings(db, event_ids)
+ deleted += len(event_ids)
+ if len(event_ids) < MESSAGE_BATCH:
+ return deleted, False
+ return deleted, True
+
+ async def _delete_media(
+ self, tenant_id: str, created_before: datetime
+ ) -> tuple[int, bool]:
+ deleted = 0
+ for _ in range(MAX_BATCHES):
+ async with tenant_session(self._sessions, tenant_id) as db, db.begin():
+ count = await self._retention.delete_unreferenced_media(
+ db, created_before=created_before, limit=MEDIA_BATCH
+ )
+ deleted += count
+ if count < MEDIA_BATCH:
+ return deleted, False
+ return deleted, True
diff --git a/core/switch_core/session_activity/maintenance.py b/core/switch_core/session_activity/maintenance.py
index 1a62bbaf3..bf920729d 100644
--- a/core/switch_core/session_activity/maintenance.py
+++ b/core/switch_core/session_activity/maintenance.py
@@ -3,7 +3,8 @@
Expiry is what unblocks a session nobody answers, so it runs often; each
expired request is announced like any other change and pushed to the agent.
Activity lines exist for platforms to show what is happening now, so they are
-kept for a bounded window and pruned rarely.
+kept for a bounded window and pruned rarely. Data retention
+(`retention/service.py`) rides the same hourly prune.
Tenants are worked through one at a time, each bound before it is touched,
like every other background task that spans them.
@@ -14,12 +15,13 @@ from __future__ import annotations
import asyncio
import contextlib
import logging
-from datetime import timedelta
+from datetime import UTC, datetime, timedelta
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from switch_core.db.tenant_lookup import all_tenant_ids
from switch_core.ownership import Fence, OwnedKind, Ownership
+from switch_core.retention.service import RetentionService
from switch_core.session_activity.service import AgentSessionActivityService
from switch_core.tenant_context import no_tenant, tenant_scope
@@ -34,10 +36,18 @@ ACTIVITY_RETENTION = timedelta(days=7)
async def maintain_once(
session_factory: async_sessionmaker[AsyncSession], *, prune: bool
) -> None:
- """One pass over every tenant: expire overdue requests, and prune if asked."""
+ """One pass over every tenant: expire overdue requests, and if asked, prune
+ activity and apply data retention."""
service = AgentSessionActivityService(session_factory)
+ retention = RetentionService(session_factory)
for tenant_id in await all_tenant_ids(session_factory):
with tenant_scope(tenant_id):
+ if prune:
+ try:
+ await retention.apply(datetime.now(UTC))
+ except Exception:
+ # Retention failing must not stop this tenant's requests expiring.
+ logger.exception("Data retention failed for tenant %s", tenant_id)
try:
expired = await service.expire_due()
if expired:
diff --git a/core/tests/switch_core/gateway/test_tenant_api_routes.py b/core/tests/switch_core/gateway/test_tenant_api_routes.py
index 8001af0be..d44ddba04 100644
--- a/core/tests/switch_core/gateway/test_tenant_api_routes.py
+++ b/core/tests/switch_core/gateway/test_tenant_api_routes.py
@@ -41,10 +41,14 @@ from switch_core.connections.sign_in_flows import SignInFlows
from switch_core.db.models import (
Agent,
ApiKey,
+ AuditEvent,
Client,
Invitation,
+ Message,
Organization,
OrganizationMember,
+ ProviderConnection,
+ Room,
ServiceTokenIssuance,
SignInFlow,
Tenant,
@@ -58,7 +62,9 @@ from switch_core.db.stores.api_key_store import ApiKeyStore
from switch_core.db.stores.budget_store import BudgetStore
from switch_core.db.stores.invitation_store import InvitationStore
from switch_core.db.stores.join_domain_store import JoinDomainStore
+from switch_core.db.stores.message_store import MessageStore
from switch_core.db.stores.organization_store import OrganizationStore
+from switch_core.db.stores.retention_store import RetentionStore
from switch_core.db.stores.service_connection_store import ServiceConnectionStore
from switch_core.db.stores.tenant_store import TenantStore
from switch_core.db.stores.usage_store import UsageStore
@@ -171,6 +177,7 @@ def _app(
)
app.dependency_overrides[gw_deps.get_usage_store] = lambda: UsageStore()
app.dependency_overrides[gw_deps.get_budget_store] = lambda: BudgetStore()
+ app.dependency_overrides[gw_deps.get_retention_store] = lambda: RetentionStore()
app.dependency_overrides[gw_deps.get_protocol] = lambda: _fake_protocol()
app.dependency_overrides[gw_deps.get_invite_mailer] = lambda: mailer
app.dependency_overrides[gw_deps.get_client_lifecycle] = lambda: (
@@ -2678,3 +2685,157 @@ class TestJoiningByDomain:
assert missing.status_code == 404
assert offered.json() == []
assert joined.status_code == 404
+
+
+class TestRetentionRoutes:
+ async def _member(
+ self,
+ session_factory: async_sessionmaker[AsyncSession],
+ name: str,
+ role: str,
+ ) -> tuple[str, str]:
+ await _make_tenant(session_factory, TENANT_A)
+ user_id = await _make_member(
+ session_factory, name=name, tenant_id=TENANT_A, role=role
+ )
+ return user_id, _token(user_id, f"{name}@example.invalid", TENANT_A)
+
+ async def _audit_actions(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> list[tuple[str, dict | None]]:
+ async with tenant_session(session_factory, TENANT_A) as session:
+ rows = await session.execute(
+ select(AuditEvent.action, AuditEvent.details)
+ .where(AuditEvent.tenant_id == TENANT_A)
+ .order_by(AuditEvent.occurred_at)
+ )
+ return [(action, details) for action, details in rows.all()]
+
+ async def test_a_new_workspace_keeps_messages_forever(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ _, token = await self._member(session_factory, "keep-forever", "admin")
+
+ async with _client(_app(session_factory), token) as client:
+ response = await client.get(f"/tenants/{TENANT_A}/retention")
+
+ assert response.status_code == 200
+ assert response.json()["message_retention_days"] is None
+
+ async def test_an_admin_sets_changes_and_clears_the_window_and_each_is_audited(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ user_id, token = await self._member(session_factory, "retention-admin", "admin")
+
+ async with _client(_app(session_factory), token) as client:
+ first = await client.put(
+ f"/tenants/{TENANT_A}/retention", json={"message_retention_days": 90}
+ )
+ second = await client.put(
+ f"/tenants/{TENANT_A}/retention", json={"message_retention_days": 30}
+ )
+ read = await client.get(f"/tenants/{TENANT_A}/retention")
+ cleared = await client.delete(f"/tenants/{TENANT_A}/retention")
+ cleared_again = await client.delete(f"/tenants/{TENANT_A}/retention")
+
+ assert first.status_code == 200
+ assert first.json()["message_retention_days"] == 90
+ assert read.json()["message_retention_days"] == 30
+ assert read.json()["updated_by_user_id"] == user_id
+ assert (
+ second.status_code
+ == cleared.status_code
+ == cleared_again.status_code
+ == 200
+ )
+ assert cleared.json()["message_retention_days"] is None
+ assert await self._audit_actions(session_factory) == [
+ (
+ "retention_policy.set",
+ {"message_retention_days": 90, "previous_message_retention_days": None},
+ ),
+ (
+ "retention_policy.set",
+ {"message_retention_days": 30, "previous_message_retention_days": 90},
+ ),
+ ("retention_policy.cleared", {"previous_message_retention_days": 30}),
+ ]
+
+ async def test_a_member_can_neither_read_nor_change_it(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ _, token = await self._member(session_factory, "retention-member", "member")
+
+ async with _client(_app(session_factory), token) as client:
+ read = await client.get(f"/tenants/{TENANT_A}/retention")
+ written = await client.put(
+ f"/tenants/{TENANT_A}/retention", json={"message_retention_days": 30}
+ )
+
+ assert read.status_code == 403
+ assert written.status_code == 403
+
+ @pytest.mark.parametrize("days", [0, 3651])
+ async def test_a_window_out_of_range_is_refused(
+ self, session_factory: async_sessionmaker[AsyncSession], days: int
+ ) -> None:
+ _, token = await self._member(
+ session_factory, f"retention-range-{days}", "owner"
+ )
+
+ async with _client(_app(session_factory), token) as client:
+ response = await client.put(
+ f"/tenants/{TENANT_A}/retention", json={"message_retention_days": days}
+ )
+
+ assert response.status_code == 422
+
+ async def test_another_workspace_in_the_path_is_refused(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ _, token = await self._member(session_factory, "retention-cross", "owner")
+ await _make_tenant(session_factory, TENANT_B)
+
+ async with _client(_app(session_factory), token) as client:
+ response = await client.put(
+ f"/tenants/{TENANT_B}/retention", json={"message_retention_days": 30}
+ )
+
+ assert response.status_code == 403
+
+ async def test_the_preview_counts_only_messages_older_than_the_window(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ _, token = await self._member(session_factory, "retention-preview", "admin")
+ now = datetime.now(UTC)
+ async with tenant_session(session_factory, TENANT_A) as session:
+ room = Room(
+ transport_room_id=f"!preview-{uuid.uuid4().hex[:8]}:test",
+ name="preview",
+ description="preview",
+ )
+ session.add(room)
+ await session.flush()
+ for index, age in enumerate((100, 40, 1)):
+ await MessageStore().create(
+ session,
+ Message(
+ room_id=room.id,
+ transport_event_id=f"$preview-{index}",
+ sender_id="@sender:test",
+ event_type="m.room.message",
+ msgtype="m.text",
+ body="hello",
+ content={"msgtype": "m.text", "body": "hello"},
+ sent_at=now - timedelta(days=age),
+ ),
+ [],
+ )
+ await session.commit()
+
+ async with _client(_app(session_factory), token) as client:
+ ninety = await client.get(f"/tenants/{TENANT_A}/retention/preview?days=90")
+ thirty = await client.get(f"/tenants/{TENANT_A}/retention/preview?days=30")
+
+ assert ninety.json() == {"message_retention_days": 90, "messages_to_delete": 1}
+ assert thirty.json() == {"message_retention_days": 30, "messages_to_delete": 2}
diff --git a/core/tests/switch_core/retention/__init__.py b/core/tests/switch_core/retention/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/core/tests/switch_core/retention/test_service.py b/core/tests/switch_core/retention/test_service.py
new file mode 100644
index 000000000..aaed49ea0
--- /dev/null
+++ b/core/tests/switch_core/retention/test_service.py
@@ -0,0 +1,451 @@
+"""Data retention against real Postgres.
+
+What a mock could not show: that deleting a message takes its attachment rows
+with it by cascade, that a room emptied by retention keeps numbering above
+what it had, that a stored file still quoted by a kept message survives, and
+that one workspace's window never reaches another's rows.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import (
+ TENANT_ZERO_ID,
+ Agent,
+ ApiKey,
+ ApprovalRequest,
+ BridgeMessageMap,
+ Client,
+ CollaborationBridge,
+ Invitation,
+ MediaBlob,
+ Message,
+ MessageAttachment,
+ MessagingInstallState,
+ Room,
+ Tenant,
+ User,
+)
+from switch_core.db.session_scope import tenant_session
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.db.stores.retention_store import RetentionStore
+from switch_core.retention.service import RetentionService
+from switch_core.tenant_context import tenant_scope
+
+NOW = datetime(2026, 10, 6, 12, 0, tzinfo=UTC)
+OTHER_TENANT = "retention-other-tenant"
+
+
+async def _user(session: AsyncSession, name: str) -> User:
+ user = User(name=name, email=f"{name}@example.invalid", role="user")
+ session.add(user)
+ await session.flush()
+ return user
+
+
+async def _room(session: AsyncSession, name: str, *, archived: bool = False) -> Room:
+ room = Room(
+ transport_room_id=f"!{name}-{uuid.uuid4().hex[:8]}:test",
+ name=name,
+ description=name,
+ archived_at=NOW - timedelta(days=500) if archived else None,
+ )
+ session.add(room)
+ await session.flush()
+ return room
+
+
+async def _message(
+ session: AsyncSession,
+ room: Room,
+ event_id: str,
+ *,
+ age_days: float,
+ attachment_uri: str | None = None,
+) -> Message:
+ attachments = (
+ []
+ if attachment_uri is None
+ else [
+ MessageAttachment(
+ uri=attachment_uri,
+ filename="f.txt",
+ mimetype="text/plain",
+ size=1,
+ )
+ ]
+ )
+ return await MessageStore().create(
+ session,
+ Message(
+ room_id=room.id,
+ transport_event_id=event_id,
+ sender_id="@sender:test",
+ event_type="m.room.message",
+ msgtype="m.text",
+ body=event_id,
+ content={"msgtype": "m.text", "body": event_id},
+ sent_at=NOW - timedelta(days=age_days),
+ ),
+ attachments,
+ )
+
+
+async def _blob(session: AsyncSession, uri: str, *, age_days: float) -> None:
+ session.add(
+ MediaBlob(
+ uri=uri,
+ content_type="text/plain",
+ filename="f.txt",
+ size=1,
+ data=b"x",
+ created_at=NOW - timedelta(days=age_days),
+ )
+ )
+ await session.flush()
+
+
+async def _event_ids(session: AsyncSession) -> set[str]:
+ return set((await session.execute(select(Message.transport_event_id))).scalars())
+
+
+async def _set_policy(
+ session_factory: async_sessionmaker[AsyncSession], days: int, tenant_id: str
+) -> None:
+ async with tenant_session(session_factory, tenant_id) as session:
+ user = await _user(session, f"policy-{uuid.uuid4().hex[:6]}")
+ await RetentionStore().set_policy(
+ session, message_retention_days=days, user_id=user.id
+ )
+ await session.commit()
+
+
+class TestMessages:
+ async def test_without_a_policy_nothing_is_deleted(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room = await _room(session, "forever")
+ await _message(session, room, "$ancient", age_days=3000)
+ await session.commit()
+
+ result = await RetentionService(session_factory).apply(NOW)
+
+ async with session_factory() as session:
+ assert await _event_ids(session) == {"$ancient"}
+ assert result.messages == 0
+
+ async def test_messages_older_than_the_window_go_in_every_room_archived_too(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ active = await _room(session, "active")
+ archived = await _room(session, "archived", archived=True)
+ await _message(session, active, "$old-active", age_days=31)
+ await _message(session, active, "$new-active", age_days=29)
+ await _message(session, archived, "$old-archived", age_days=400)
+ await session.commit()
+ await _set_policy(session_factory, 30, TENANT_ZERO_ID)
+
+ result = await RetentionService(session_factory).apply(NOW)
+
+ async with session_factory() as session:
+ assert await _event_ids(session) == {"$new-active"}
+ assert result.messages == 2
+ assert not result.backlog
+
+ async def test_attachments_and_bridge_mappings_go_with_their_message(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room = await _room(session, "files")
+ await _message(
+ session, room, "$old", age_days=60, attachment_uri="switch-media://old"
+ )
+ client = Client(
+ transport_user_id=f"@bridge-{uuid.uuid4().hex[:8]}:test",
+ display_name="bridge",
+ type="bridge",
+ )
+ session.add(client)
+ await session.flush()
+ bridge = CollaborationBridge(
+ type="mattermost",
+ display_name="MM",
+ client_id=client.id,
+ status="active",
+ )
+ session.add(bridge)
+ await session.flush()
+ for event_id in ("$old", "$unrelated"):
+ session.add(
+ BridgeMessageMap(
+ bridge_id=bridge.id,
+ external_channel_id="chan",
+ transport_event_id=event_id,
+ external_post_id=f"post{event_id}",
+ )
+ )
+ await session.commit()
+ await _set_policy(session_factory, 30, TENANT_ZERO_ID)
+
+ await RetentionService(session_factory).apply(NOW)
+
+ async with session_factory() as session:
+ attachments = await session.scalar(
+ select(func.count()).select_from(MessageAttachment)
+ )
+ mapped = set(
+ (
+ await session.execute(select(BridgeMessageMap.transport_event_id))
+ ).scalars()
+ )
+ assert attachments == 0
+ assert mapped == {"$unrelated"}
+
+ async def test_another_workspaces_window_does_not_reach_this_one(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ session.add(Tenant(id=OTHER_TENANT, slug=OTHER_TENANT, name=OTHER_TENANT))
+ await session.commit()
+ async with session_factory() as session:
+ room = await _room(session, "tenant-zero")
+ await _message(session, room, "$zero-old", age_days=60)
+ await session.commit()
+ async with tenant_session(session_factory, OTHER_TENANT) as session:
+ room = await _room(session, "other")
+ await _message(session, room, "$other-old", age_days=60)
+ await session.commit()
+ await _set_policy(session_factory, 30, OTHER_TENANT)
+
+ with tenant_scope(OTHER_TENANT):
+ await RetentionService(session_factory).apply(NOW)
+ with tenant_scope(TENANT_ZERO_ID):
+ await RetentionService(session_factory).apply(NOW)
+
+ async with session_factory() as session:
+ assert await _event_ids(session) == {"$zero-old"}
+
+
+class TestNumbering:
+ async def test_a_room_emptied_by_retention_keeps_numbering_above_what_it_had(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _room(session, "emptied")
+ for index in range(3):
+ await _message(session, room, f"$old{index}", age_days=60)
+ await session.commit()
+ head_before = await store.head_seq(session, room.id)
+ await _set_policy(session_factory, 30, TENANT_ZERO_ID)
+
+ await RetentionService(session_factory).apply(NOW)
+
+ async with session_factory() as session:
+ head_after = await store.head_seq(session, room.id)
+ fresh = await _message(session, room, "$fresh", age_days=0)
+ await session.commit()
+ assert head_before == head_after == 3
+ assert fresh.seq == 4
+
+ async def test_reconstructed_history_does_not_lower_the_floor(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _room(session, "backfilled")
+ await store.create_historical(
+ session,
+ Message(
+ room_id=room.id,
+ transport_event_id="$history",
+ sender_id="@sender:test",
+ event_type="m.room.message",
+ msgtype="m.text",
+ body="history",
+ content={"msgtype": "m.text", "body": "history"},
+ sent_at=NOW - timedelta(days=90),
+ ),
+ [],
+ )
+ await session.commit()
+ await _set_policy(session_factory, 30, TENANT_ZERO_ID)
+
+ await RetentionService(session_factory).apply(NOW)
+
+ async with session_factory() as session:
+ refreshed = await session.get(Room, room.id)
+ assert refreshed is not None
+ assert refreshed.seq_floor == 0
+ assert await store.head_seq(session, room.id) == 0
+
+
+class TestMedia:
+ async def test_only_old_files_nothing_refers_to_are_deleted(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room = await _room(session, "media")
+ await _blob(session, "switch-media://quoted", age_days=10)
+ await _message(
+ session,
+ room,
+ "$kept",
+ age_days=1,
+ attachment_uri="switch-media://quoted",
+ )
+ await _blob(session, "switch-media://orphan", age_days=10)
+ await _blob(session, "switch-media://just-uploaded", age_days=0.1)
+ await session.commit()
+
+ result = await RetentionService(session_factory).apply(NOW)
+
+ async with session_factory() as session:
+ uris = set((await session.execute(select(MediaBlob.uri))).scalars())
+ assert uris == {"switch-media://quoted", "switch-media://just-uploaded"}
+ assert result.media == 1
+
+ async def test_a_file_goes_once_the_last_message_quoting_it_is_deleted(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room = await _room(session, "media-expiry")
+ await _blob(session, "switch-media://shared", age_days=90)
+ await _message(
+ session, room, "$a", age_days=60, attachment_uri="switch-media://shared"
+ )
+ await _message(
+ session, room, "$b", age_days=10, attachment_uri="switch-media://shared"
+ )
+ await session.commit()
+ await _set_policy(session_factory, 30, TENANT_ZERO_ID)
+
+ await RetentionService(session_factory).apply(NOW)
+ async with session_factory() as session:
+ assert (
+ await session.scalar(select(func.count()).select_from(MediaBlob)) == 1
+ )
+
+ await RetentionService(session_factory).apply(NOW + timedelta(days=21))
+ async with session_factory() as session:
+ assert (
+ await session.scalar(select(func.count()).select_from(MediaBlob)) == 0
+ )
+
+
+async def _agent(session: AsyncSession) -> Agent:
+ name = f"agent-{uuid.uuid4().hex[:6]}"
+ user = await _user(session, name)
+ api_key = ApiKey(
+ user_id=user.id,
+ key_hash=f"hash-{name}",
+ encrypted_key="enc",
+ label=name,
+ type="agent",
+ )
+ client = Client(transport_user_id=f"@{name}:test", display_name=name, type="agent")
+ session.add_all([api_key, client])
+ await session.flush()
+ agent = Agent(
+ name=name,
+ description=name,
+ agent_type="always_on",
+ connector_type="claude_code",
+ integration_profile={"connection_model": "always_on"},
+ client_id=client.id,
+ api_key_id=api_key.id,
+ )
+ session.add(agent)
+ await session.flush()
+ return agent
+
+
+class TestLeftovers:
+ async def test_settled_approvals_go_after_the_grace_and_owed_answers_stay(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ old = NOW - timedelta(days=31)
+ async with session_factory() as session:
+ agent = await _agent(session)
+ for request_id, state, delivered, updated in (
+ ("closed-old", "closed", None, old),
+ ("delivered-old", "answered", old, old),
+ ("owed-old", "answered", None, old),
+ ("open-old", "open", None, old),
+ ("closed-recent", "closed", None, NOW - timedelta(days=1)),
+ ):
+ session.add(
+ ApprovalRequest(
+ agent_id=agent.id,
+ session_id="s1",
+ request_id=request_id,
+ turn_id="t1",
+ kind="approval",
+ title=request_id,
+ options=[],
+ questions=[],
+ state=state,
+ delivered_at=delivered,
+ updated_at=updated,
+ )
+ )
+ await session.commit()
+
+ result = await RetentionService(session_factory).apply(NOW)
+
+ async with session_factory() as session:
+ left = set(
+ (await session.execute(select(ApprovalRequest.request_id))).scalars()
+ )
+ assert left == {"owed-old", "open-old", "closed-recent"}
+ assert result.approvals == 2
+
+ async def test_lapsed_invitations_and_expired_install_links_go_after_the_grace(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ user = await _user(session, "inviter")
+ for label, expires, revoked in (
+ ("expired-old", NOW - timedelta(days=31), None),
+ ("revoked-old", NOW + timedelta(days=1), NOW - timedelta(days=31)),
+ ("expired-recent", NOW - timedelta(days=1), None),
+ ("live", NOW + timedelta(days=1), None),
+ ):
+ session.add(
+ Invitation(
+ role="member",
+ email=f"{label}@example.invalid",
+ token_hash=label,
+ expires_at=expires,
+ uses_remaining=1,
+ revoked_at=revoked,
+ created_by=user.id,
+ )
+ )
+ for expires in (NOW - timedelta(days=31), NOW - timedelta(days=1)):
+ session.add(
+ MessagingInstallState(
+ platform="slack", created_by_user_id=user.id, expires_at=expires
+ )
+ )
+ await session.commit()
+
+ result = await RetentionService(session_factory).apply(NOW)
+
+ async with session_factory() as session:
+ hashes = set(
+ (await session.execute(select(Invitation.token_hash))).scalars()
+ )
+ states = await session.scalar(
+ select(func.count()).select_from(MessagingInstallState)
+ )
+ assert hashes == {"expired-recent", "live"}
+ assert states == 1
+ assert (result.invitations, result.install_states) == (2, 1)
diff --git a/docs/design/data-retention.md b/docs/design/data-retention.md
new file mode 100644
index 000000000..5703ba4a6
--- /dev/null
+++ b/docs/design/data-retention.md
@@ -0,0 +1,179 @@
+# Data retention
+
+What Switch deletes on its own, what a workspace can ask it to delete, and how
+that relates to the GDPR. The first half describes what is built. The second
+half is a design note for what is not built yet, so later work starts from a
+shared picture and not from scratch.
+
+## What is built
+
+### A message-retention window per workspace
+
+Each workspace keeps room messages forever until an owner or admin sets a
+window on the Workspace page ("Data retention"). With a window of N days, room
+messages older than N days are deleted from every room in the workspace,
+archived rooms included. Their attachments go with them, as does the record of
+which chat-platform post carried each message.
+
+- **Storage.** `tenant_retention_policies` holds one row per workspace that has
+ a window. No row means keep forever, so turning retention on is always the
+ workspace's choice and never a deployment default.
+- **API.** `GET`, `PUT` and `DELETE /tenants/{id}/retention` read, set and clear
+ the window. `GET /tenants/{id}/retention/preview?days=N` counts what a window
+ would delete now, which the page shows before anything is saved. All four are
+ limited to owners and admins.
+- **Audit.** Setting and clearing the window are recorded as
+ `retention_policy.set` and `retention_policy.cleared`, with the previous and
+ new values.
+- **Enforcement.** A pass runs hourly per workspace, inside the
+ session-activity maintenance loop (`session_activity/maintenance.py` calls
+ `retention/service.py`). A change therefore takes effect within the hour, not
+ in the request that made it. Deletion runs in batches of 1000 messages, each
+ in its own transaction, and stops at 50 batches per pass. A larger backlog,
+ such as the first pass after a short window is set on an old workspace, is
+ finished by the passes after it. Hitting the limit logs a warning.
+
+### Message numbering survives deletion
+
+Messages are numbered per room (`messages.seq`), and every delivery cursor is a
+position in that sequence. New numbers came from "highest existing + 1", so a
+room whose messages had all been deleted would have started again at 1. Every
+cursor already past that point would then have silently skipped the new
+messages. `rooms.seq_floor` records the highest live position retention has
+deleted, and numbering continues above whichever is higher. Reconstructed
+history (negative `seq`) never moves the floor.
+
+Other effects of deleting old messages, all already handled:
+
+- `read_context` reads by time window and reports `truncated` correctly.
+- A reply whose thread root has been deleted shows the root as elided.
+- Unread counts come from an in-memory buffer, not from the table.
+- Posting a new reply into a thread whose root was deleted is refused with
+ "thread_id not found". That is a visible failure, not a silent one.
+
+### Orphaned files are swept
+
+Attachment bytes live in `media_blobs`, which deliberately has no foreign key to
+the attachments that use it: two messages may quote the same file. Every hourly
+pass deletes blobs that no attachment row refers to, whatever the workspace's
+policy, because an orphaned file is not something anyone chose to keep. That
+covers files left behind by retention and also those left behind when a room is
+deleted, which nothing cleaned up before.
+
+A blob is only a candidate once it is a day old. A file is uploaded before the
+message that carries it, in a separate transaction. A blob named by a pending
+hosted-cutover import is never a candidate.
+
+### Leftover operational records
+
+After a 30-day grace period, every pass also deletes:
+
+- approval requests that are settled: closed, or answered or expired and
+ already delivered. An answer still owed to an agent is kept, however old.
+ Their platform posts are deleted with them.
+- invitations that expired or were revoked
+- messaging install links that expired. Once expired, a replayed link is
+ refused whether or not the row exists.
+
+### What is deliberately not touched
+
+- **The audit log** (`audit_events`). It is append-only by design, and the
+ runtime database role cannot delete from it. See below.
+- **Usage records** (`tenant_usage`). They are billing and quota data, hold no
+ message content, and are aggregated per hour.
+- **Copies on chat platforms.** A message bridged to Slack, Mattermost, Discord,
+ Teams or Telegram is also stored by that platform under the customer's own
+ retention settings. Switch does not delete it there, and the Workspace page
+ says so.
+
+## Design note: GDPR
+
+The relevant obligations are storage limitation (Art. 5(1)(e)), erasure
+(Art. 17), access and portability (Art. 15 and 20), and accountability. The
+retention window covers storage limitation for message content. The rest is
+below, in the order it is likely to be needed.
+
+### Where personal data lives
+
+| Data | Where | Personal data |
+|---|---|---|
+| Message content and attachments | `messages`, `message_attachments`, `media_blobs` | Anything people write. Sender ids. |
+| Switch accounts | `users`, `oidc_identities`, `tenant_members` | Name, email, IdP subject |
+| Chat-platform identities | `external_users`, `external_user_claims` | Platform user id and username |
+| Invitations | `invitations` | Invitee email |
+| Audit log | `audit_events` | Actor user id, target ids, details |
+| Session activity | `session_activity_items`, `approval_requests` | Who answered what. Prompt and tool text. Already pruned after 7 days (activity) or 30 days once settled (approvals). |
+| Logs and backups | outside the database | Whatever the deployment's log and backup policy keeps |
+
+### Erase a person (not built)
+
+An owner action that removes one person's data from one workspace:
+
+1. Resolve the person to their identities in the workspace: their Switch user
+ (if a member) and every `external_users` row claimed by them or named by the
+ request.
+2. Delete every message whose sender is one of those identities, with its
+ attachments, using the same machinery as retention:
+ `MessageStore.delete_sent_before` generalised to a sender filter, keeping
+ the `seq_floor` update. The hourly sweep then removes orphaned files.
+3. Delete the `external_users` rows and their claims. A person who later writes
+ again from the same platform account is recorded afresh.
+4. Remove the membership, if any. Deleting the Switch account itself is a
+ deployment-level action, because one account may belong to several
+ workspaces.
+5. Record `person.erased` in the audit log, naming who was erased and who
+ asked, but not what was deleted.
+
+Open questions:
+
+- **Quotes and mentions in other people's messages.** Erasing them would rewrite
+ other people's records. The usual reading of Art. 17 does not require it, and
+ this design leaves them alone.
+- **Agents' copies.** An agent may have the person's messages in its own
+ transcript or memory, on a machine Switch does not control. The action can
+ tell connected agents, but it cannot guarantee anything for them.
+- **Bridged platforms.** As with retention, the platform's copy is the
+ customer's to erase in that platform.
+
+### Data export (not built)
+
+An owner or admin export of everything held about one person in the workspace,
+as machine-readable JSON: account fields, platform identities, and messages
+they sent, with attachments. The same identity resolution as erasure applies.
+This is a natural next step after erasure, since it needs the same lookup.
+
+### Deleting a workspace (not built)
+
+`tenants` has no `deleted_at` today. Deleting a workspace needs an ordered
+teardown across every tenant-scoped table, because the tenant foreign keys do
+not cascade. It also needs a grace period and an audit record kept outside the
+tenant. This is a multi-tenancy-phase concern, noted here because it is the
+largest remaining erasure path.
+
+### The audit log
+
+The audit log cannot be pruned by the application on purpose: the runtime role
+has `UPDATE` and `DELETE` revoked, so a compromised process cannot erase its
+tracks. Bounding it needs a separate, privileged job, for example a
+`SECURITY DEFINER` function owned by the migration role that deletes events
+older than a fixed horizon. The horizon should be a deployment setting, not a
+workspace one, because the log protects the operator as well as the customer.
+Audit entries hold ids and small details, not message content, so keeping them
+longer than messages is defensible under the accountability principle.
+
+### Backups and logs
+
+Deleted rows remain in database backups until those backups expire. A
+deployment's backup retention should be documented alongside its message
+retention, and restoring a backup should be followed by a retention pass, which
+happens on its own within the hour. Application logs do not include message
+bodies by default. Any change that starts logging them should be treated as
+personal-data processing.
+
+### Not covered yet
+
+- `bridge_message_map` rows orphaned by deleting a whole room. Retention
+ removes the rows for the messages it deletes, but not these.
+- Expired controller enrolment codes. Each is tied to an `api_keys` row that
+ needs to go with it.
+- `tasks`, `hosted_operations` and agent-controller operation history.
diff --git a/gateway/src/data/api.ts b/gateway/src/data/api.ts
index c52ea6c7e..1082a458a 100644
--- a/gateway/src/data/api.ts
+++ b/gateway/src/data/api.ts
@@ -1475,6 +1475,57 @@ export interface CreateInvitationInput {
uses_remaining: number;
}
+// ── Data retention ─────────────────────────────────────────────────────────
+
+export const MAX_MESSAGE_RETENTION_DAYS = 3650;
+
+export interface RetentionPolicy {
+ // Null means messages are kept forever.
+ message_retention_days: number | null;
+ updated_at: string | null;
+ updated_by_user_id: string | null;
+}
+
+export interface RetentionPreview {
+ message_retention_days: number;
+ messages_to_delete: number;
+}
+
+export async function fetchRetentionPolicy(tenantId: string): Promise<RetentionPolicy> {
+ return jsonRequest<RetentionPolicy>(
+ `/tenants/${encodeURIComponent(tenantId)}/retention`,
+ "GET",
+ );
+}
+
+export async function previewRetentionPolicy(
+ tenantId: string,
+ days: number,
+): Promise<RetentionPreview> {
+ return jsonRequest<RetentionPreview>(
+ `/tenants/${encodeURIComponent(tenantId)}/retention/preview?days=${days}`,
+ "GET",
+ );
+}
+
+export async function setRetentionPolicy(
+ tenantId: string,
+ days: number,
+): Promise<RetentionPolicy> {
+ return jsonRequest<RetentionPolicy>(
+ `/tenants/${encodeURIComponent(tenantId)}/retention`,
+ "PUT",
+ { message_retention_days: days },
+ );
+}
+
+export async function clearRetentionPolicy(tenantId: string): Promise<RetentionPolicy> {
+ return jsonRequest<RetentionPolicy>(
+ `/tenants/${encodeURIComponent(tenantId)}/retention`,
+ "DELETE",
+ );
+}
+
export async function fetchInvitations(tenantId: string): Promise<Invitation[]> {
return jsonRequest<Invitation[]>(
`/tenants/${encodeURIComponent(tenantId)}/invitations`,
diff --git a/gateway/src/pages/workspace/RetentionSection.test.tsx b/gateway/src/pages/workspace/RetentionSection.test.tsx
new file mode 100644
index 000000000..90dd5adda
--- /dev/null
+++ b/gateway/src/pages/workspace/RetentionSection.test.tsx
@@ -0,0 +1,92 @@
+import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import RetentionSection, { describeRetention } from "./RetentionSection";
+
+type Call = { url: string; method: string; body: unknown };
+
+function serve(initialDays: number | null, toDelete = 0) {
+ let days = initialDays;
+ const calls: Call[] = [];
+ const policy = () => ({
+ message_retention_days: days,
+ updated_at: null,
+ updated_by_user_id: null,
+ });
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async (url: string, init?: RequestInit) => {
+ const method = init?.method ?? "GET";
+ const body = init?.body ? JSON.parse(String(init.body)) : undefined;
+ calls.push({ url, method, body });
+ if (url.includes("/retention/preview")) {
+ const asked = Number(new URL(url, "http://x").searchParams.get("days"));
+ return new Response(
+ JSON.stringify({ message_retention_days: asked, messages_to_delete: toDelete }),
+ );
+ }
+ if (method === "PUT") days = (body as { message_retention_days: number }).message_retention_days;
+ if (method === "DELETE") days = null;
+ return new Response(JSON.stringify(policy()));
+ }),
+ );
+ return calls;
+}
+
+describe("describeRetention", () => {
+ it("says what the policy does in plain words", () => {
+ expect(describeRetention(null)).toBe("Messages are kept forever.");
+ expect(describeRetention(1)).toBe("Messages older than 1 day are deleted.");
+ expect(describeRetention(90)).toBe("Messages older than 90 days are deleted.");
+ });
+});
+
+describe("RetentionSection", () => {
+ afterEach(() => {
+ cleanup();
+ vi.unstubAllGlobals();
+ });
+
+ it("asks for confirmation with the number of messages before turning retention on", async () => {
+ const calls = serve(null, 1234);
+ render(<RetentionSection tenantId="t1" />);
+ await screen.findByText(/Messages are kept forever/);
+
+ fireEvent.click(screen.getByLabelText("Delete messages older than"));
+ fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+ const dialog = await screen.findByRole("dialog");
+ expect(within(dialog).getByText(/1,234 messages/)).toBeTruthy();
+ expect(calls.some((c) => c.method === "PUT")).toBe(false);
+
+ fireEvent.click(within(dialog).getByRole("button", { name: "Turn on retention" }));
+ await screen.findByText(/Messages older than 90 days are deleted/);
+ expect(calls.find((c) => c.method === "PUT")?.body).toEqual({ message_retention_days: 90 });
+ });
+
+ it("goes back to keeping forever without a confirmation", async () => {
+ const calls = serve(30);
+ render(<RetentionSection tenantId="t1" />);
+ await screen.findByText(/Messages older than 30 days are deleted/);
+
+ fireEvent.click(screen.getByLabelText("Keep forever"));
+ fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+ await screen.findByText(/Messages are kept forever/);
+ expect(calls.some((c) => c.method === "DELETE")).toBe(true);
+ expect(screen.queryByRole("dialog")).toBeNull();
+ });
+
+ it("does not save a custom window out of range", async () => {
+ serve(45);
+ render(<RetentionSection tenantId="t1" />);
+ await screen.findByText(/Messages older than 45 days are deleted/);
+
+ const days = screen.getByLabelText("Days");
+ expect((days as HTMLInputElement).value).toBe("45");
+ fireEvent.change(days, { target: { value: "5000" } });
+
+ await waitFor(() =>
+ expect(screen.getByRole("button", { name: "Save" }).hasAttribute("disabled")).toBe(true),
+ );
+ });
+});
diff --git a/gateway/src/pages/workspace/RetentionSection.tsx b/gateway/src/pages/workspace/RetentionSection.tsx
new file mode 100644
index 000000000..90db0c865
--- /dev/null
+++ b/gateway/src/pages/workspace/RetentionSection.tsx
@@ -0,0 +1,213 @@
+import {
+ Alert,
+ Button,
+ CircularProgress,
+ Dialog,
+ DialogActions,
+ DialogContent,
+ DialogContentText,
+ DialogTitle,
+ FormControlLabel,
+ MenuItem,
+ Paper,
+ Radio,
+ RadioGroup,
+ Stack,
+ TextField,
+ Typography,
+} from "@mui/material";
+import { useCallback, useEffect, useState } from "react";
+import {
+ MAX_MESSAGE_RETENTION_DAYS,
+ clearRetentionPolicy,
+ fetchRetentionPolicy,
+ previewRetentionPolicy,
+ setRetentionPolicy,
+} from "../../data/api";
+import { parseBound } from "../usage/usageFormat";
+import { useLoad } from "./useLoad";
+
+const PRESET_DAYS = [30, 90, 365];
+const CUSTOM = "custom";
+
+type Mode = "forever" | "window";
+
+export function describeRetention(days: number | null): string {
+ if (days === null) return "Messages are kept forever.";
+ return `Messages older than ${days} ${days === 1 ? "day" : "days"} are deleted.`;
+}
+
+export default function RetentionSection({ tenantId }: { tenantId: string }) {
+ const load = useCallback(() => fetchRetentionPolicy(tenantId), [tenantId]);
+ const { data: policy, error, loading, refetch } = useLoad(load);
+ const current = policy?.message_retention_days ?? null;
+
+ const [mode, setMode] = useState<Mode>("forever");
+ const [preset, setPreset] = useState<string>("90");
+ const [customDays, setCustomDays] = useState("");
+ const [saving, setSaving] = useState(false);
+ const [actionError, setActionError] = useState<string | null>(null);
+ const [confirm, setConfirm] = useState<{ days: number; count: number } | null>(null);
+
+ const resetToCurrent = useCallback(() => {
+ if (current === null) {
+ setMode("forever");
+ setPreset("90");
+ setCustomDays("");
+ } else {
+ setMode("window");
+ const isPreset = PRESET_DAYS.includes(current);
+ setPreset(isPreset ? String(current) : CUSTOM);
+ setCustomDays(isPreset ? "" : String(current));
+ }
+ }, [current]);
+
+ useEffect(() => {
+ resetToCurrent();
+ }, [resetToCurrent]);
+
+ const chosenDays =
+ mode === "forever"
+ ? null
+ : preset === CUSTOM
+ ? parseBound(customDays, MAX_MESSAGE_RETENTION_DAYS)
+ : Number(preset);
+ const invalid = mode === "window" && chosenDays === null;
+ const unchanged = !invalid && chosenDays === current;
+
+ const save = async () => {
+ setActionError(null);
+ setSaving(true);
+ try {
+ if (chosenDays === null) {
+ await clearRetentionPolicy(tenantId);
+ await refetch();
+ } else {
+ const preview = await previewRetentionPolicy(tenantId, chosenDays);
+ setConfirm({ days: chosenDays, count: preview.messages_to_delete });
+ }
+ } catch (err) {
+ setActionError(err instanceof Error ? err.message : "Could not save the retention policy");
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ const applyConfirmed = async () => {
+ if (!confirm) return;
+ setActionError(null);
+ setSaving(true);
+ try {
+ await setRetentionPolicy(tenantId, confirm.days);
+ setConfirm(null);
+ await refetch();
+ } catch (err) {
+ setConfirm(null);
+ setActionError(err instanceof Error ? err.message : "Could not save the retention policy");
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ return (
+ <Stack spacing={1.5}>
+ <Typography variant="h6">Data retention</Typography>
+ {error && <Alert severity="error">{error}</Alert>}
+ {actionError && (
+ <Alert severity="error" onClose={() => setActionError(null)}>
+ {actionError}
+ </Alert>
+ )}
+ {loading ? (
+ <CircularProgress />
+ ) : (
+ <Paper variant="outlined" sx={{ p: 2 }}>
+ <Stack spacing={2}>
+ <Typography variant="body2" sx={{ color: "text.secondary" }}>
+ {describeRetention(current)} This applies to every room in the workspace,
+ archived rooms included. Attachments are deleted with their messages. Copies
+ already posted to Slack or other connected chat apps are not affected.
+ </Typography>
+ <RadioGroup
+ value={mode}
+ onChange={(event) => setMode(event.target.value as Mode)}
+ >
+ <FormControlLabel value="forever" control={<Radio />} label="Keep forever" />
+ <Stack direction="row" alignItems="center" spacing={1.5} flexWrap="wrap">
+ <FormControlLabel
+ value="window"
+ control={<Radio />}
+ label="Delete messages older than"
+ sx={{ mr: 0 }}
+ />
+ <TextField
+ select
+ size="small"
+ value={preset}
+ disabled={mode !== "window"}
+ onChange={(event) => setPreset(event.target.value)}
+ sx={{ minWidth: 140 }}
+ inputProps={{ "aria-label": "Retention window" }}
+ >
+ {PRESET_DAYS.map((days) => (
+ <MenuItem key={days} value={String(days)}>
+ {days} days
+ </MenuItem>
+ ))}
+ <MenuItem value={CUSTOM}>Custom…</MenuItem>
+ </TextField>
+ {preset === CUSTOM && (
+ <TextField
+ size="small"
+ label="Days"
+ value={customDays}
+ disabled={mode !== "window"}
+ onChange={(event) => setCustomDays(event.target.value)}
+ error={mode === "window" && invalid && customDays !== ""}
+ helperText={`1 to ${MAX_MESSAGE_RETENTION_DAYS}`}
+ sx={{ width: 120 }}
+ />
+ )}
+ </Stack>
+ </RadioGroup>
+ <Stack direction="row" spacing={1} justifyContent="flex-end">
+ <Button disabled={unchanged || saving} onClick={resetToCurrent}>
+ Cancel
+ </Button>
+ <Button
+ variant="contained"
+ disabled={unchanged || invalid || saving}
+ onClick={() => void save()}
+ >
+ Save
+ </Button>
+ </Stack>
+ </Stack>
+ </Paper>
+ )}
+ <Dialog open={confirm !== null} onClose={() => setConfirm(null)}>
+ <DialogTitle>Delete messages older than {confirm?.days} days?</DialogTitle>
+ <DialogContent>
+ <DialogContentText>
+ {confirm?.count === 0
+ ? "No messages are old enough to be deleted yet."
+ : `${confirm?.count.toLocaleString()} ${confirm?.count === 1 ? "message" : "messages"} and their attachments will be permanently deleted within the next hour.`}{" "}
+ From then on, messages are deleted as they pass {confirm?.days} days old. Deleted
+ messages cannot be recovered.
+ </DialogContentText>
+ </DialogContent>
+ <DialogActions>
+ <Button onClick={() => setConfirm(null)}>Cancel</Button>
+ <Button
+ color="error"
+ variant="contained"
+ disabled={saving}
+ onClick={() => void applyConfirmed()}
+ >
+ Turn on retention
+ </Button>
+ </DialogActions>
+ </Dialog>
+ </Stack>
+ );
+}
diff --git a/gateway/src/pages/workspace/WorkspacePage.tsx b/gateway/src/pages/workspace/WorkspacePage.tsx
index adb82f880..dead67464 100644
--- a/gateway/src/pages/workspace/WorkspacePage.tsx
+++ b/gateway/src/pages/workspace/WorkspacePage.tsx
@@ -3,6 +3,7 @@ import { useAuth } from "../../data/AuthContext";
import DeleteWorkspaceSection from "./DeleteWorkspaceSection";
import InvitationsSection from "./InvitationsSection";
import MembersSection from "./MembersSection";
+import RetentionSection from "./RetentionSection";
export default function WorkspacePage() {
const { session, canAdminTenant } = useAuth();
@@ -34,6 +35,7 @@ export default function WorkspacePage() {
Ask a workspace admin to invite someone.
</Alert>
)}
+ {canAdminTenant && <RetentionSection tenantId={tenant.id} />}
{/* An admin membership, not the operator's bypass: the server checks the same. */}
{tenant.role === "admin" && (
<DeleteWorkspaceSection tenantId={tenant.id} tenantName={tenant.name} />