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.

fix(recovery): rebuild authz-R2 policy + notification digests/chat webhooks

Juan Denisb29fa773130a
diff --git a/backend/app/api/notifications.py b/backend/app/api/notifications.py
index 1fe0640d..989ea103 100644
--- a/backend/app/api/notifications.py
+++ b/backend/app/api/notifications.py
@@ -296,7 +296,11 @@ def get_inbox():
limit = min(request.args.get('limit', 20, type=int), 100)
offset = request.args.get('offset', 0, type=int)
unread_only = request.args.get('unread', '').lower() in ('1', 'true', 'yes')
- items = NotificationBusService.inbox(user_id, limit=limit, offset=offset, unread_only=unread_only)
+ category = request.args.get('category') or None
+ severity = request.args.get('severity') or None
+ items = NotificationBusService.inbox(user_id, limit=limit, offset=offset,
+ unread_only=unread_only,
+ category=category, severity=severity)
return jsonify({
'items': items,
'unread_count': NotificationBusService.unread_count(user_id),
@@ -324,10 +328,17 @@ def mark_inbox_read(delivery_id):
@notifications_bp.route('/inbox/read-all', methods=['POST'])
@jwt_required()
def mark_inbox_all_read():
- """Mark all of the current user's in-app notifications as read."""
+ """Mark all of the current user's in-app notifications as read.
+
+ Optional ``category`` / ``severity`` query params mark only that group.
+ """
user_id = int(get_jwt_identity())
- updated = NotificationBusService.mark_all_read(user_id)
- return jsonify({'success': True, 'updated': updated, 'unread_count': 0}), 200
+ category = request.args.get('category') or None
+ severity = request.args.get('severity') or None
+ updated = NotificationBusService.mark_all_read(user_id, category=category,
+ severity=severity)
+ return jsonify({'success': True, 'updated': updated,
+ 'unread_count': NotificationBusService.unread_count(user_id)}), 200
# ==========================================
@@ -361,6 +372,49 @@ def admin_retry_delivery(delivery_id):
return jsonify({'success': True, 'delivery': result}), 200
+# ==========================================
+# ORG CHAT / WEBHOOK CONNECTIONS (admin)
+# ==========================================
+
+@notifications_bp.route('/admin/chat-connections', methods=['GET'])
+@jwt_required()
+@admin_required
+def list_chat_connections():
+ """List org chat/webhook connections + the catalog of supported kinds."""
+ from app.services.chat_webhook_service import ChatWebhookService
+ from app.models.chat_webhook import ChatWebhookConnection
+ return jsonify({
+ 'connections': [c.to_dict() for c in ChatWebhookService.list_all()],
+ 'kinds': list(ChatWebhookConnection.KINDS),
+ }), 200
+
+
+@notifications_bp.route('/admin/chat-connections', methods=['POST'])
+@jwt_required()
+@admin_required
+def add_chat_connection():
+ """Create a chat/webhook connection (destination + secret encrypted)."""
+ from app.services.chat_webhook_service import ChatWebhookService
+ data = request.get_json() or {}
+ data['created_by'] = int(get_jwt_identity())
+ try:
+ conn = ChatWebhookService.add(data)
+ except ValueError as exc:
+ return jsonify({'error': str(exc)}), 400
+ return jsonify({'connection': conn.to_dict()}), 201
+
+
+@notifications_bp.route('/admin/chat-connections/<int:conn_id>', methods=['DELETE'])
+@jwt_required()
+@admin_required
+def delete_chat_connection(conn_id):
+ """Delete a chat/webhook connection (promotes a new per-kind default)."""
+ from app.services.chat_webhook_service import ChatWebhookService
+ if not ChatWebhookService.delete(conn_id):
+ return jsonify({'error': 'Connection not found'}), 404
+ return jsonify({'success': True}), 200
+
+
# ==========================================
# EMAIL PROVIDER INTEGRATIONS (admin)
# ==========================================
diff --git a/backend/app/models/notification_preferences.py b/backend/app/models/notification_preferences.py
index 6efb7473..ee7295f7 100644
--- a/backend/app/models/notification_preferences.py
+++ b/backend/app/models/notification_preferences.py
@@ -39,6 +39,13 @@ class NotificationPreferences(db.Model):
# JSON object with category: boolean
categories = db.Column(db.Text, default='{"system": true, "security": true, "backups": true, "apps": true}')
+ # Digest rollup cadence (plan 24 Phase 3): 'off' | 'daily' | 'weekly'.
+ # Default 'off' preserves immediate-send back-compat (digests are opt-in).
+ # Backed by migration 060; the digest job (app/notifications/digest.py)
+ # batches this user's `queued_digest` deliveries into one branded email.
+ digest_cadence = db.Column(db.String(12), default='off')
+ digest_last_sent_at = db.Column(db.DateTime, nullable=True)
+
# Quiet hours (don't send non-critical notifications during these hours)
quiet_hours_enabled = db.Column(db.Boolean, default=False)
quiet_hours_start = db.Column(db.String(5), default='22:00') # HH:MM format
@@ -100,6 +107,8 @@ class NotificationPreferences(db.Model):
'discord_webhook': self.discord_webhook[:30] + '...' if self.discord_webhook and len(self.discord_webhook) > 30 else self.discord_webhook,
'telegram_chat_id': self.telegram_chat_id,
'categories': self.get_categories(),
+ 'digest_cadence': self.digest_cadence or 'off',
+ 'digest_last_sent_at': self.digest_last_sent_at.isoformat() if self.digest_last_sent_at else None,
'quiet_hours': {
'enabled': self.quiet_hours_enabled,
'start': self.quiet_hours_start,
diff --git a/backend/app/notifications/catalog.py b/backend/app/notifications/catalog.py
index c0827721..4fab0ad8 100644
--- a/backend/app/notifications/catalog.py
+++ b/backend/app/notifications/catalog.py
@@ -67,6 +67,14 @@ _CATALOG = {
'severity': 'warning',
'category': 'system',
},
+ # Daily doctor sweep found managed site domains that no longer resolve
+ # (see app/services/doctor_service.py:_dns_checks).
+ 'dns.unresolved': {
+ 'title': 'Site domains no longer resolve ({count})',
+ 'template': 'generic',
+ 'severity': 'warning',
+ 'category': 'system',
+ },
# Daily registry check found newer versions of installed extensions (#50).
'extensions.updates_available': {
'title': 'Extension updates available ({count})',
@@ -139,6 +147,65 @@ DEFAULT_ENTRY = {
}
+# --------------------------------------------------------------------------- #
+# Deep links (plan 24 Phase 5)
+#
+# Maps an ``event_key`` to the relative in-app path its notification should link
+# to. Resolved at send time and PERSISTED on the notification row (see
+# NotificationBusService.send) so a later route move never breaks old rows.
+# Producers may override per-send via ``action_path`` / ``action_label``.
+# --------------------------------------------------------------------------- #
+_LINKS = {
+ # backups / restores
+ 'backup.completed': '/backups',
+ 'backup.failed': '/backups',
+ 'restore.completed': '/backups',
+ 'restore.failed': '/backups',
+ # security
+ 'security.alert': '/security',
+ # apps / deploys
+ 'app.deployed': '/services',
+ # system / monitoring
+ 'system.alert': '/monitoring',
+ 'monitoring.alert': '/monitoring',
+ 'drift.detected': '/monitoring/doctor',
+ 'dns.sync_failed': '/domains',
+ 'dns.unresolved': '/domains',
+ 'cron.job_failed': '/cron',
+ 'extensions.updates_available': '/marketplace',
+ 'setup.incomplete': '/setup',
+ # account
+ 'user.welcome': '/dashboard',
+ 'user.invitation': '/dashboard',
+}
+
+# Button label for the deep link, keyed by destination path.
+_LINK_LABELS = {
+ '/backups': 'View backups',
+ '/security': 'View security',
+ '/services': 'View services',
+ '/monitoring': 'Open monitoring',
+ '/monitoring/doctor': 'Open doctor',
+ '/domains': 'View domains',
+ '/cron': 'View scheduled tasks',
+ '/marketplace': 'Open marketplace',
+ '/setup': 'Finish setup',
+ '/dashboard': 'Open dashboard',
+}
+
+_DEFAULT_LINK_LABEL = 'View details'
+
+
+def link_for(event_key, data=None):
+ """Return ``(action_path, action_label)`` for an event, or ``(None, None)``
+ when the event has no known deep link. ``data`` is accepted for future
+ per-event parameterization; the map is static today."""
+ path = _LINKS.get(event_key)
+ if not path:
+ return None, None
+ return path, _LINK_LABELS.get(path, _DEFAULT_LINK_LABEL)
+
+
def register(event_key, title, template='generic', severity='info', category='system'):
"""Register (or override) a catalog event. Safe to call at import time."""
_CATALOG[event_key] = {
diff --git a/backend/app/notifications/channels/chat.py b/backend/app/notifications/channels/chat.py
index 9e91844e..7a7c241e 100644
--- a/backend/app/notifications/channels/chat.py
+++ b/backend/app/notifications/channels/chat.py
@@ -38,6 +38,12 @@ class ChatAdapter(ChannelAdapter):
def deliver(self, delivery, notification):
target = (delivery.target or '').strip()
+ # Org-level chat/webhook connections (plan 24 Phase 4) address their
+ # destination as ``conn:<id>`` — resolve + deliver via the connection
+ # service (encrypted creds, HMAC signing, per-connection category).
+ if target.startswith('conn:'):
+ from app.services.chat_webhook_service import ChatWebhookService
+ return ChatWebhookService.deliver(delivery, notification)
if not target:
return DeliveryResult.skipped(f'no {self.key} target')
diff --git a/backend/app/notifications/digest.py b/backend/app/notifications/digest.py
new file mode 100644
index 00000000..f8fde66e
--- /dev/null
+++ b/backend/app/notifications/digest.py
@@ -0,0 +1,256 @@
+"""Notification digest rollups — per-user cadence (plan 24 Phase 3).
+
+Instead of one email per event, a user can opt into a *digest*: the bus routes
+digestable deliveries (and quiet-hours catch-ups) onto the
+``notification_deliveries`` table with status ``queued_digest`` (never enqueued),
+and this job periodically groups a user's held deliveries into ONE branded email,
+sends it, and flips those rows to ``sent`` with the digest's message id.
+
+Cadence lives on ``NotificationPreferences.digest_cadence`` ('off'|'daily'|
+'weekly'); ``digest_last_sent_at`` records the last send so the hourly tick only
+mails a user once their window has elapsed.
+
+Guards (Decision 3 / #9): an empty digest never sends (and never stamps the
+clock, so nothing is silently swallowed); a one-item digest borrows that item's
+own subject line rather than shaming the reader with a "1 update" email.
+
+Entry points:
+ - ``run_due(now=None)`` — the hourly tick; mails every user whose window
+ elapsed. This is what the ScheduledJob calls.
+ - ``send_user_digest(uid)`` — build + send one user's digest now.
+ - ``run_digest_job(work_unit=None)`` — job-handler-shaped wrapper for run_due.
+"""
+import logging
+from collections import OrderedDict
+from datetime import datetime, timedelta
+
+from app import db
+from app.models.notification_preferences import NotificationPreferences
+from app.models.user import User
+from app.notifications import rendering
+from app.notifications.models import Notification, NotificationDelivery
+
+logger = logging.getLogger(__name__)
+
+# How long between digests for each cadence.
+_CADENCE_DELTA = {
+ 'daily': timedelta(days=1),
+ 'weekly': timedelta(days=7),
+}
+
+# Preference categories -> human labels for the digest section headers.
+_CATEGORY_LABELS = {
+ 'system': 'System',
+ 'security': 'Security',
+ 'backups': 'Backups',
+ 'apps': 'Apps',
+}
+# Deterministic section order (unknown categories append, alpha).
+_CATEGORY_ORDER = ['security', 'backups', 'apps', 'system']
+
+
+# --------------------------------------------------------------------------- #
+# Selection
+# --------------------------------------------------------------------------- #
+
+def pending_for_user(user_id):
+ """This user's held (``queued_digest``) email deliveries, oldest first."""
+ return (NotificationDelivery.query
+ .filter_by(recipient_user_id=user_id,
+ channel=NotificationDelivery.CHANNEL_EMAIL,
+ status=NotificationDelivery.STATUS_QUEUED_DIGEST)
+ .order_by(NotificationDelivery.created_at.asc())
+ .all())
+
+
+def _cadence_delta(cadence):
+ return _CADENCE_DELTA.get((cadence or 'off').strip().lower())
+
+
+def is_due(prefs, now=None):
+ """Whether ``prefs``' digest window has elapsed (or never sent)."""
+ delta = _cadence_delta(prefs.digest_cadence)
+ if delta is None: # 'off' or unknown -> never due
+ return False
+ if prefs.digest_last_sent_at is None:
+ return True
+ return (now or datetime.utcnow()) - prefs.digest_last_sent_at >= delta
+
+
+# --------------------------------------------------------------------------- #
+# Build + render
+# --------------------------------------------------------------------------- #
+
+def build_digest(user, deliveries):
+ """Group ``deliveries`` (with their notifications) into digest sections.
+
+ Returns ``{'subject', 'groups', 'total', 'user'}`` or None if nothing to
+ say (all deliveries orphaned of their notification)."""
+ buckets = OrderedDict()
+ total = 0
+ first_title = None
+ for delivery in deliveries:
+ notification = delivery.notification
+ if notification is None:
+ continue
+ total += 1
+ if first_title is None:
+ first_title = notification.title
+ category = notification.category or 'system'
+ buckets.setdefault(category, []).append({
+ 'severity': notification.severity or 'info',
+ 'title': notification.title,
+ 'when': notification.created_at.strftime('%b %d, %H:%M') if notification.created_at else None,
+ 'action_url': notification.action_path or None,
+ })
+
+ if total == 0:
+ return None
+
+ ordered = sorted(
+ buckets.items(),
+ key=lambda kv: (_CATEGORY_ORDER.index(kv[0]) if kv[0] in _CATEGORY_ORDER
+ else len(_CATEGORY_ORDER), kv[0]),
+ )
+ groups = [{'label': _CATEGORY_LABELS.get(cat, cat.replace('_', ' ').title()),
+ 'category': cat, 'items': items}
+ for cat, items in ordered]
+
+ # Single-item digests borrow the item's own subject (#9 — no "1 update" mail).
+ if total == 1:
+ subject = first_title
+ else:
+ subject = f'ServerKit digest — {total} updates'
+
+ return {'subject': subject, 'groups': groups, 'total': total, 'user': user}
+
+
+def render_digest(digest, manage_url=None):
+ """Render a built digest to ``{'subject', 'html', 'text'}``."""
+ user = digest['user']
+ recipient = {'name': (user.username or user.email) if user else None,
+ 'email': user.email if user else None}
+ ctx = rendering._build_context(
+ subject=digest['subject'], severity='info', data={},
+ recipient=recipient, urls={'manage': manage_url}, hostname=None,
+ )
+ ctx['groups'] = digest['groups']
+ ctx['total'] = digest['total']
+ try:
+ html = rendering.env().get_template('email/digest.html').render(**ctx)
+ except Exception as exc: # never let a template bug swallow the digest
+ logger.warning('Digest template failed (%s); using generic body', exc)
+ html = rendering.env().get_template('email/generic.html').render(**ctx)
+ return {'subject': digest['subject'], 'html': html, 'text': _text_twin(digest)}
+
+
+def _text_twin(digest):
+ """Programmatic plain-text alternative (like rendering's fallback)."""
+ lines = [digest['subject'], '=' * min(len(digest['subject']), 60), '']
+ for group in digest['groups']:
+ lines.append(group['label'].upper())
+ for item in group['items']:
+ when = f" ({item['when']})" if item.get('when') else ''
+ lines.append(f" - [{item['severity']}] {item['title']}{when}")
+ lines.append('')
+ lines.append('-' * 40)
+ lines.append('Manage your digest cadence in ServerKit → Settings → Notifications.')
+ return '\n'.join(lines)
+
+
+# --------------------------------------------------------------------------- #
+# Transport (seam — tests override this)
+# --------------------------------------------------------------------------- #
+
+def _transmit(to_addr, rendered):
+ """Send the digest email. Returns ``(success, message_id, error)``.
+
+ Prefers a configured EmailProviderConnection; otherwise falls back to the
+ legacy notifications.json SMTP path (reusing the email channel adapter)."""
+ from app.notifications.providers import EmailProviderService
+ try:
+ provider = EmailProviderService.default_provider()
+ except Exception:
+ provider = None
+ if provider is not None:
+ result = EmailProviderService.send(
+ provider, to_addr, rendered['subject'], rendered['html'], rendered['text'])
+ return bool(result.get('success')), result.get('message_id'), result.get('error')
+
+ from app.notifications.channels.email import EmailAdapter
+ res = EmailAdapter()._send_legacy_smtp(to_addr, rendered)
+ return res.ok, res.message_id, res.error
+
+
+# --------------------------------------------------------------------------- #
+# Send
+# --------------------------------------------------------------------------- #
+
+def _digest_address(user, prefs):
+ return (prefs.email if prefs else None) or (user.email if user else None)
+
+
+def send_user_digest(user_id, now=None, stamp_clock=True):
+ """Build + send one user's digest. Returns a result dict.
+
+ On success: the digested deliveries flip to ``sent`` (carrying the digest's
+ message id) and ``digest_last_sent_at`` is stamped. An empty digest is a
+ no-op that neither sends nor stamps the clock."""
+ now = now or datetime.utcnow()
+ user = User.query.get(user_id)
+ if user is None:
+ return {'sent': False, 'reason': 'no user', 'count': 0}
+
+ deliveries = pending_for_user(user_id)
+ if not deliveries:
+ return {'sent': False, 'reason': 'empty', 'count': 0}
+
+ prefs = NotificationPreferences.get_or_create(user_id)
+ to_addr = _digest_address(user, prefs)
+ if not to_addr:
+ return {'sent': False, 'reason': 'no email address', 'count': len(deliveries)}
+
+ digest = build_digest(user, deliveries)
+ if digest is None: # deliveries all orphaned of notifications
+ return {'sent': False, 'reason': 'empty', 'count': 0}
+
+ rendered = render_digest(digest)
+ success, message_id, error = _transmit(to_addr, rendered)
+ if not success:
+ return {'sent': False, 'reason': error or 'send failed',
+ 'count': len(deliveries)}
+
+ sent_at = datetime.utcnow()
+ for delivery in deliveries:
+ delivery.status = NotificationDelivery.STATUS_SENT
+ delivery.sent_at = sent_at
+ delivery.provider_message_id = message_id
+ delivery.error = None
+ if stamp_clock:
+ prefs.digest_last_sent_at = now
+ db.session.commit()
+ return {'sent': True, 'count': len(deliveries), 'subject': digest['subject'],
+ 'message_id': message_id}
+
+
+def run_due(now=None):
+ """Hourly tick: send a digest to every user whose cadence window elapsed."""
+ now = now or datetime.utcnow()
+ rows = (NotificationPreferences.query
+ .filter(NotificationPreferences.digest_cadence.in_(tuple(_CADENCE_DELTA)))
+ .all())
+ sent = skipped = 0
+ for prefs in rows:
+ if not is_due(prefs, now=now):
+ continue
+ result = send_user_digest(prefs.user_id, now=now)
+ if result.get('sent'):
+ sent += 1
+ else:
+ skipped += 1
+ return {'sent': sent, 'skipped': skipped, 'candidates': len(rows)}
+
+
+def run_digest_job(work_unit=None):
+ """ScheduledJob handler shape (kind ``notifications.digest.run``)."""
+ return run_due()
diff --git a/backend/app/notifications/service.py b/backend/app/notifications/service.py
index 8aeb4f8d..e76a2177 100644
--- a/backend/app/notifications/service.py
+++ b/backend/app/notifications/service.py
@@ -32,7 +32,8 @@ class NotificationBusService:
# Public API
# ------------------------------------------------------------------
@classmethod
- def send(cls, event, to, data=None, channels=None, severity=None, title=None, category=None):
+ def send(cls, event, to, data=None, channels=None, severity=None, title=None,
+ category=None, action_path=None, action_label=None):
"""Emit a notification.
event — catalog key, e.g. 'backup.completed' (unknown keys render
@@ -45,6 +46,11 @@ class NotificationBusService:
severity — override the catalog default.
title — override the computed title/subject.
category — override the catalog category (system/security/backups/apps).
+ action_path — deep link (relative path) for this notification; when
+ omitted, resolved from the catalog link builder. Persisted
+ on the row so a later route move never breaks old rows.
+ action_label — button label for the deep link (falls back to the
+ catalog default when a path is resolved).
Returns {'notification_id', 'deliveries'} immediately.
"""
@@ -53,6 +59,12 @@ class NotificationBusService:
severity = meta['severity']
category = category or meta['category']
+ # Compute + persist the deep link at send time (producer override wins).
+ if action_path is None:
+ action_path, link_label = catalog.link_for(event, data)
+ if action_label is None:
+ action_label = link_label
+
notification = Notification(
event_key=event,
category=category,
@@ -60,6 +72,8 @@ class NotificationBusService:
title=meta['title'],
body=data.get('summary') or data.get('message'),
audience=cls._describe(to),
+ action_path=action_path,
+ action_label=action_label,
correlation_id=generate_correlation_id(),
)
notification.set_data(data)
@@ -111,6 +125,29 @@ class NotificationBusService:
to_enqueue.append(delivery)
db.session.add(delivery)
+ # Org-level chat/webhook connections (plan 24 Phase 4). A preference-
+ # driven notification (channels is None) fans out ONCE per active,
+ # category-matched connection as an org-level delivery (no recipient
+ # user). Directed transactional sends (explicit channels) are
+ # per-recipient only and never trigger org chat.
+ if channels is None:
+ from app.services.chat_webhook_service import ChatWebhookService
+ for conn in ChatWebhookService.active_for_category(category):
+ target = f'conn:{conn.id}'
+ key = (None, conn.kind, target)
+ if key in seen:
+ continue
+ seen.add(key)
+ delivery = NotificationDelivery(
+ notification_id=notification.id,
+ recipient_user_id=None,
+ channel=conn.kind,
+ target=target,
+ status=NotificationDelivery.STATUS_PENDING,
+ )
+ to_enqueue.append(delivery)
+ db.session.add(delivery)
+
db.session.commit()
priority = 10 if severity == 'critical' else 0
@@ -365,11 +402,17 @@ class NotificationBusService:
)
@classmethod
- def inbox(cls, user_id, limit=20, offset=0, unread_only=False):
- """Return the current user's in-app notifications, newest first."""
+ def inbox(cls, user_id, limit=20, offset=0, unread_only=False,
+ category=None, severity=None):
+ """Return the current user's in-app notifications, newest first.
+
+ Optional ``category`` / ``severity`` filters narrow the history to one
+ notification bucket (joined against the parent :class:`Notification`).
+ """
query = cls._inbox_query(user_id)
if unread_only:
query = query.filter(NotificationDelivery.read_at.is_(None))
+ query = cls._apply_notification_filters(query, category, severity)
rows = (query.order_by(NotificationDelivery.created_at.desc())
.limit(limit).offset(offset).all())
items = []
@@ -403,16 +446,42 @@ class NotificationBusService:
return True
@classmethod
- def mark_all_read(cls, user_id):
- """Mark every unread in-app notification read. Returns the count."""
+ def mark_all_read(cls, user_id, category=None, severity=None):
+ """Mark every unread in-app notification read. With ``category`` /
+ ``severity``, only that group is touched. Returns the count."""
now = datetime.utcnow()
- updated = (cls._inbox_query(user_id)
- .filter(NotificationDelivery.read_at.is_(None))
- .update({NotificationDelivery.read_at: now},
- synchronize_session=False))
+ query = (cls._inbox_query(user_id)
+ .filter(NotificationDelivery.read_at.is_(None)))
+ if category or severity:
+ # A join is needed to filter on the parent notification, and a bulk
+ # UPDATE with a join isn't portable — resolve ids, then update those.
+ query = cls._apply_notification_filters(query, category, severity)
+ ids = [row.id for row in query.with_entities(NotificationDelivery.id).all()]
+ if not ids:
+ return 0
+ NotificationDelivery.query.filter(NotificationDelivery.id.in_(ids)).update(
+ {NotificationDelivery.read_at: now}, synchronize_session=False)
+ db.session.commit()
+ return len(ids)
+ updated = query.update({NotificationDelivery.read_at: now},
+ synchronize_session=False)
db.session.commit()
return updated
+ @staticmethod
+ def _apply_notification_filters(query, category=None, severity=None):
+ """Join the parent :class:`Notification` and filter by category/severity
+ when either is given."""
+ if not category and not severity:
+ return query
+ query = query.join(
+ Notification, NotificationDelivery.notification_id == Notification.id)
+ if category:
+ query = query.filter(Notification.category == category)
+ if severity:
+ query = query.filter(Notification.severity == severity)
+ return query
+
# ------------------------------------------------------------------
# Delivery log / ops (admin)
# ------------------------------------------------------------------
diff --git a/backend/app/services/chat_webhook_service.py b/backend/app/services/chat_webhook_service.py
new file mode 100644
index 00000000..0e5757f4
--- /dev/null
+++ b/backend/app/services/chat_webhook_service.py
@@ -0,0 +1,310 @@
+"""Organization-level chat / webhook connections (plan 24 Phase 4).
+
+The write + delivery half of :class:`app.models.chat_webhook.ChatWebhookConnection`
+— a shared Discord/Slack/Telegram room or a generic signed webhook that receives
+every notification matching its category filter. This replaces the legacy global
+``notifications.json`` chat config (which a one-time :meth:`import_legacy` folds
+into connections).
+
+Credentials are Fernet-encrypted per field before they touch the DB and only
+decrypted at send/test time. The Notification Bus fans a preference-driven
+notification out to every active, category-matched connection as a
+``recipient_user_id IS NULL`` (org-level) NotificationDelivery whose target is
+``conn:<id>``; the chat channel adapter routes those back here for delivery.
+"""
+import hashlib
+import hmac
+import json
+import logging
+from datetime import datetime
+
+import requests
+
+from app import db
+from app.models.chat_webhook import ChatWebhookConnection
+from app.utils.crypto import encrypt_secret
+
+logger = logging.getLogger(__name__)
+
+# The single header the generic webhook signs its body with (HMAC-SHA256).
+SIGNATURE_HEADER = 'X-ServerKit-Signature'
+_REQUEST_TIMEOUT = 15
+
+# Legacy notifications.json section -> (connection kind, destination key in the
+# saved config). telegram maps to chat_id; the chat flavors carry a webhook_url.
+_LEGACY_MAP = [
+ ('discord', 'discord', 'webhook_url'),
+ ('slack', 'slack', 'webhook_url'),
+ ('generic_webhook', 'webhook', 'url'),
+ ('telegram', 'telegram', 'chat_id'),
+]
+
+
+class ChatWebhookService:
+ """Stateless CRUD + routing + delivery for chat/webhook connections."""
+
+ # ------------------------------------------------------------------
+ # CRUD
+ # ------------------------------------------------------------------
+ @classmethod
+ def add(cls, data):
+ """Create a connection, encrypting its destination + secret at rest.
+
+ Requires a destination (url for discord/slack/webhook, chat_id for
+ telegram) — raises ValueError otherwise. The first connection of a kind
+ becomes that kind's default. Commits and returns the row.
+ """
+ kind = (data.get('kind') or '').strip().lower()
+ if kind not in ChatWebhookConnection.KINDS:
+ raise ValueError(f'Unknown chat connection kind: {kind!r}')
+
+ name = (data.get('name') or '').strip()
+ if not name:
+ raise ValueError('name is required')
+
+ credentials = cls._build_credentials(kind, data) # raises if no destination
+
+ categories = data.get('categories') or []
+ if not isinstance(categories, list):
+ raise ValueError('categories must be a list')
+ categories = [c for c in categories if c]
+
+ is_first = ChatWebhookConnection.query.filter_by(kind=kind).count() == 0
+ conn = ChatWebhookConnection(
+ kind=kind,
+ name=name,
+ credentials_json=json.dumps(credentials),
+ categories_json=json.dumps(categories) if categories else None,
+ is_active=data.get('is_active', True),
+ is_default=bool(is_first),
+ imported=bool(data.get('imported', False)),
+ created_by=data.get('created_by'),
+ )
+ db.session.add(conn)
+ db.session.commit()
+ return conn
+
+ @classmethod
+ def delete(cls, conn_id):
+ """Delete a connection. If it was its kind's default, promote the oldest
+ remaining connection of that kind. Returns True if a row was removed."""
+ conn = ChatWebhookConnection.query.get(conn_id)
+ if conn is None:
+ return False
+ was_default = conn.is_default
+ kind = conn.kind
+ db.session.delete(conn)
+ db.session.commit()
+ if was_default:
+ replacement = (ChatWebhookConnection.query
+ .filter_by(kind=kind)
+ .order_by(ChatWebhookConnection.created_at.asc(),
+ ChatWebhookConnection.id.asc())
+ .first())
+ if replacement is not None:
+ replacement.is_default = True
+ db.session.commit()
+ return True
+
+ @staticmethod
+ def list_all():
+ """Every connection, oldest first (admin list)."""
+ return ChatWebhookConnection.query.order_by(
+ ChatWebhookConnection.id.asc()).all()
+
+ @staticmethod
+ def _build_credentials(kind, data):
+ """Encrypt the per-kind credential map. Raises ValueError with no dest."""
+ creds = {}
+ if kind == 'telegram':
+ chat_id = data.get('chat_id')
+ if not chat_id:
+ raise ValueError('telegram connection requires a chat_id')
+ creds['chat_id'] = encrypt_secret(str(chat_id))
+ if data.get('bot_token'):
+ creds['bot_token'] = encrypt_secret(str(data['bot_token']))
+ else:
+ url = data.get('url') or data.get('webhook_url')
+ if not url:
+ raise ValueError(f'{kind} connection requires a url')
+ creds['url'] = encrypt_secret(str(url))
+ if data.get('secret'):
+ creds['secret'] = encrypt_secret(str(data['secret']))
+ return creds
+
+ # ------------------------------------------------------------------
+ # Category routing (used by the bus fan-out)
+ # ------------------------------------------------------------------
+ @staticmethod
+ def active_for_category(category):
+ """Active connections that accept ``category`` (a catch-all with no
+ category filter matches everything). Oldest first, deterministic."""
+ conns = (ChatWebhookConnection.query
+ .filter_by(is_active=True)
+ .order_by(ChatWebhookConnection.id.asc())
+ .all())
+ return [c for c in conns if c.matches_category(category)]
+
+ # ------------------------------------------------------------------
+ # Delivery (called by the chat channel adapter for ``conn:<id>`` targets)
+ # ------------------------------------------------------------------
+ @classmethod
+ def deliver(cls, delivery, notification):
+ """Deliver one org-connection NotificationDelivery. Returns a
+ DeliveryResult (sent/failed/skipped) the consumer maps onto the row."""
+ from app.notifications.channels.base import DeliveryResult
+ conn = cls._connection_from_target(delivery.target)
+ if conn is None:
+ return DeliveryResult.skipped('chat connection not found')
+ if not conn.is_active:
+ return DeliveryResult.skipped('chat connection inactive')
+
+ creds = conn.credentials()
+ if conn.kind == 'webhook':
+ return cls._deliver_webhook(conn, creds, notification)
+ return cls._deliver_chat(conn, creds, notification)
+
+ @staticmethod
+ def _connection_from_target(target):
+ target = (target or '').strip()
+ if not target.startswith('conn:'):
+ return None
+ try:
+ conn_id = int(target.split(':', 1)[1])
+ except (ValueError, IndexError):
+ return None
+ return ChatWebhookConnection.query.get(conn_id)
+
+ @staticmethod
+ def _payload(notification):
+ """The documented, brand-neutral generic webhook payload."""
+ created = notification.created_at or datetime.utcnow()
+ return {
+ 'event': notification.event_key,
+ 'category': notification.category,
+ 'severity': notification.severity,
+ 'title': notification.title,
+ 'body': notification.body,
+ 'url': notification.action_path,
+ 'ts': created.isoformat(),
+ 'notification_id': notification.id,
+ 'data': notification.get_data(),
+ }
+
+ @classmethod
+ def _deliver_webhook(cls, conn, creds, notification):
+ from app.notifications.channels.base import DeliveryResult
+ url = creds.get('url')
+ if not url:
+ return DeliveryResult.skipped('no webhook url')
+
+ body = json.dumps(cls._payload(notification), sort_keys=True,
+ separators=(',', ':')).encode('utf-8')
+ headers = {
+ 'Content-Type': 'application/json',
+ 'User-Agent': 'ServerKit-Notifications/1.0',
+ }
+ secret = creds.get('secret')
+ if secret:
+ signature = hmac.new(secret.encode('utf-8'), body,
+ hashlib.sha256).hexdigest()
+ headers[SIGNATURE_HEADER] = 'sha256=' + signature
+
+ try:
+ resp = requests.post(url, data=body, headers=headers,
+ timeout=_REQUEST_TIMEOUT)
+ except Exception as exc: # network error -> retryable failure
+ return DeliveryResult.failed(str(exc))
+
+ ok = getattr(resp, 'ok', None)
+ if ok is None:
+ status = getattr(resp, 'status_code', 0)
+ ok = 200 <= status < 300
+ if ok:
+ return DeliveryResult.sent()
+ return DeliveryResult.failed(
+ f'webhook returned {getattr(resp, "status_code", "?")}')
+
+ @classmethod
+ def _deliver_chat(cls, conn, creds, notification):
+ """Discord/Slack/Telegram reuse the working NotificationService
+ formatters — we only swap in the connection's own destination."""
+ from app.notifications.channels.base import DeliveryResult
+ from app.services.notification_service import NotificationService
+
+ data = notification.get_data()
+ severity = notification.severity or 'info'
+ alerts = data.get('alerts')
+ if not (isinstance(alerts, list) and alerts):
+ alerts = [{
+ 'severity': severity,
+ 'type': notification.event_key,
+ 'message': data.get('message') or notification.body or notification.title,
+ }]
+ # Gating already happened in the bus; let every alert through.
+ notify_on = sorted({a.get('severity', severity) for a in alerts} | {severity})
+ saved = NotificationService.get_config()
+
+ if conn.kind == 'discord':
+ cfg = {**saved.get('discord', {}), 'enabled': True,
+ 'webhook_url': creds.get('url'), 'notify_on': notify_on}
+ result = NotificationService.send_discord(alerts, cfg)
+ elif conn.kind == 'slack':
+ cfg = {**saved.get('slack', {}), 'enabled': True,
+ 'webhook_url': creds.get('url'), 'notify_on': notify_on}
+ result = NotificationService.send_slack(alerts, cfg)
+ elif conn.kind == 'telegram':
+ cfg = {**saved.get('telegram', {}), 'enabled': True,
+ 'chat_id': creds.get('chat_id'), 'notify_on': notify_on}
+ if creds.get('bot_token'):
+ cfg['bot_token'] = creds['bot_token']
+ result = NotificationService.send_telegram(alerts, cfg)
+ else: # pragma: no cover - defensive
+ return DeliveryResult.skipped(f'unsupported chat kind {conn.kind}')
+
+ if result.get('success'):
+ return DeliveryResult.sent()
+ return DeliveryResult.failed(result.get('error') or 'send failed')
+
+ # ------------------------------------------------------------------
+ # One-time legacy import
+ # ------------------------------------------------------------------
+ @classmethod
+ def import_legacy(cls):
+ """Fold the global ``notifications.json`` chat config into connections.
+
+ Idempotent: a kind that already has an imported connection is skipped, so
+ re-running is a no-op. Per-user personal webhook fields are intentionally
+ NOT imported (a personal DM webhook is not an org room). Returns the count
+ of connections created this run.
+ """
+ from app.services.notification_service import NotificationService
+ config = NotificationService.get_config() or {}
+
+ created = 0
+ for cfg_key, kind, dest_key in _LEGACY_MAP:
+ section = config.get(cfg_key) or {}
+ destination = section.get(dest_key)
+ if not destination:
+ continue
+ already = ChatWebhookConnection.query.filter_by(
+ kind=kind, imported=True).first()
+ if already is not None:
+ continue
+
+ payload = {'kind': kind, 'name': f'Imported {kind.title()}',
+ 'imported': True}
+ if kind == 'telegram':
+ payload['chat_id'] = destination
+ if section.get('bot_token'):
+ payload['bot_token'] = section['bot_token']
+ else:
+ payload['url'] = destination
+ if section.get('secret'):
+ payload['secret'] = section['secret']
+ try:
+ cls.add(payload)
+ created += 1
+ except ValueError as exc: # pragma: no cover - defensive
+ logger.warning('Skipped legacy %s import: %s', kind, exc)
+ return created
diff --git a/backend/app/services/resource_grant_service.py b/backend/app/services/resource_grant_service.py
index a163d7d3..a48d6f1f 100644
--- a/backend/app/services/resource_grant_service.py
+++ b/backend/app/services/resource_grant_service.py
@@ -57,6 +57,24 @@ class ResourceGrantService:
return True
return ResourceGrantService.grant_role(user.id, 'application', app.id) == 'editor'
+ @staticmethod
+ def can_operate_app(user, app):
+ """Operate (member+) access to an application. Folds every path to the
+ app into one capability tier (see rbac.app_access_tier) and admits
+ anyone at 'member' or above: owner, panel admin, an editor grant, or a
+ workspace member/admin/owner. The member-write seam (plan 19 Phase 4)."""
+ from app.middleware.rbac import app_access_tier, _APP_ROLE_RANK
+ tier = app_access_tier(user, app)
+ return tier is not None and _APP_ROLE_RANK[tier] >= _APP_ROLE_RANK['member']
+
+ @staticmethod
+ def can_admin_app(user, app):
+ """Administer (admin+) access to an application: panel admin, the app
+ owner, or a workspace admin/owner. Grants never confer admin."""
+ from app.middleware.rbac import app_access_tier, _APP_ROLE_RANK
+ tier = app_access_tier(user, app)
+ return tier is not None and _APP_ROLE_RANK[tier] >= _APP_ROLE_RANK['admin']
+
@staticmethod
def list_for_resource(resource_type, resource_id):
from app.models.workspace import ResourceGrant
diff --git a/backend/app/services/security_policy_service.py b/backend/app/services/security_policy_service.py
new file mode 100644
index 00000000..2635f9d5
--- /dev/null
+++ b/backend/app/services/security_policy_service.py
@@ -0,0 +1,152 @@
+"""Panel security policy — the require-2FA enrollment policy (plan 29 Phase 2).
+
+Evaluates, per user, whether the panel's *require two-factor* policy is satisfied,
+still within its grace window, or must be enforced now. The three outcomes are:
+
+ 'ok' — no action needed (policy off, user already has 2FA, or SSO-exempt)
+ 'nudge' — policy on, no 2FA yet, but still inside the grace window
+ 'enforce' — policy on, no 2FA, grace window elapsed → gate the session
+
+The grace window is anchored on ``max(user.created_at, policy_enabled_at)`` so
+flipping the policy ON never insta-locks a veteran account (plan 29 Decision 4).
+``policy_enabled_at`` is stamped the moment the policy transitions off→on and
+lives in the same SettingsService map as the toggle itself — no new table.
+
+SSO accounts (``auth_provider`` other than ``local``) are exempt: their identity
+provider owns the second factor (plan 29, security_policy_service ok/nudge/enforce
++ SSO-exempt).
+"""
+from datetime import datetime, timedelta
+
+from app.services.settings_service import SettingsService
+
+# Setting keys (plain SettingsService map — no dedicated model).
+SETTING_REQUIRE_2FA = 'security_require_2fa'
+SETTING_ENABLED_AT = 'security_require_2fa_enabled_at'
+
+
+class SecurityPolicyService:
+ """Stateless evaluation of the require-2FA policy."""
+
+ OK = 'ok'
+ NUDGE = 'nudge'
+ ENFORCE = 'enforce'
+
+ # How long a user has to enroll once the policy applies to them.
+ GRACE_PERIOD_DAYS = 7
+
+ # ------------------------------------------------------------------
+ # Policy state (SettingsService-backed)
+ # ------------------------------------------------------------------
+ @staticmethod
+ def _as_bool(value):
+ if isinstance(value, bool):
+ return value
+ if value is None:
+ return False
+ return str(value).strip().lower() in ('1', 'true', 'yes', 'on')
+
+ @classmethod
+ def require_2fa_enabled(cls):
+ """Whether the admin has turned the require-2FA policy on."""
+ return cls._as_bool(SettingsService.get(SETTING_REQUIRE_2FA, False))
+
+ @classmethod
+ def policy_enabled_at(cls):
+ """When the policy last transitioned off→on, or None if never / off."""
+ raw = SettingsService.get(SETTING_ENABLED_AT, None)
+ if not raw:
+ return None
+ if isinstance(raw, datetime):
+ return raw
+ try:
+ return datetime.fromisoformat(str(raw))
+ except (ValueError, TypeError):
+ return None
+
+ @classmethod
+ def set_require_2fa(cls, enabled, user_id=None):
+ """Set the require-2FA toggle. Stamps ``policy_enabled_at`` on an off→on
+ transition (and only then) so the grace clock starts at activation."""
+ enabled = bool(enabled)
+ was_enabled = cls.require_2fa_enabled()
+ SettingsService.set(SETTING_REQUIRE_2FA, 'true' if enabled else 'false', user_id)
+ if enabled and not was_enabled:
+ SettingsService.set(SETTING_ENABLED_AT, datetime.utcnow().isoformat(), user_id)
+ return enabled
+
+ # ------------------------------------------------------------------
+ # Per-user grace window
+ # ------------------------------------------------------------------
+ @classmethod
+ def grace_anchor(cls, user):
+ """The later of the account's creation and the policy's activation.
+
+ Anchoring on the max means a long-lived account still gets the FULL grace
+ window when the policy is first switched on (plan 29 Decision 4)."""
+ anchor = getattr(user, 'created_at', None) or datetime.utcnow()
+ enabled_at = cls.policy_enabled_at()
+ if enabled_at and enabled_at > anchor:
+ anchor = enabled_at
+ return anchor
+
+ @classmethod
+ def grace_deadline(cls, user):
+ """When enforcement kicks in for ``user``."""
+ return cls.grace_anchor(user) + timedelta(days=cls.GRACE_PERIOD_DAYS)
+
+ @classmethod
+ def in_grace(cls, user, now=None):
+ now = now or datetime.utcnow()
+ return now < cls.grace_deadline(user)
+
+ # ------------------------------------------------------------------
+ # User attributes
+ # ------------------------------------------------------------------
+ @staticmethod
+ def is_sso_user(user):
+ """SSO accounts delegate the second factor to their IdP → policy-exempt."""
+ provider = (getattr(user, 'auth_provider', None) or 'local').lower()
+ return provider != 'local'
+
+ @staticmethod
+ def user_has_2fa(user):
+ """True if the user has ANY second factor enrolled (TOTP or a passkey)."""
+ if getattr(user, 'totp_enabled', False):
+ return True
+ try:
+ return user.passkeys.filter_by(is_active=True).count() > 0
+ except Exception:
+ return False
+
+ # ------------------------------------------------------------------
+ # Evaluation
+ # ------------------------------------------------------------------
+ @classmethod
+ def evaluate(cls, user, now=None):
+ """Return 'ok' | 'nudge' | 'enforce' for ``user`` under the current policy."""
+ if user is None:
+ return cls.OK
+ if not cls.require_2fa_enabled():
+ return cls.OK
+ if cls.user_has_2fa(user):
+ return cls.OK
+ if cls.is_sso_user(user):
+ return cls.OK
+ if cls.in_grace(user, now=now):
+ return cls.NUDGE
+ return cls.ENFORCE
+
+ @classmethod
+ def status(cls, user, now=None):
+ """A JSON-friendly policy snapshot for the current user."""
+ result = cls.evaluate(user, now=now)
+ required = cls.require_2fa_enabled()
+ deadline = cls.grace_deadline(user) if (required and user is not None) else None
+ return {
+ 'result': result,
+ 'required': required,
+ 'has_2fa': cls.user_has_2fa(user) if user is not None else False,
+ 'exempt': cls.is_sso_user(user) if user is not None else False,
+ 'grace_deadline': deadline.isoformat() if deadline else None,
+ }
diff --git a/backend/tests/test_member_actions.py b/backend/tests/test_member_actions.py
new file mode 100644
index 00000000..6e066667
--- /dev/null
+++ b/backend/tests/test_member_actions.py
@@ -0,0 +1,109 @@
+"""Proving tests for the member-action escape hatch (plan 19 Phase 5 / plan 29
+#13). Exercises the feature flag, the tier authorization (via the reconstructed
+can_operate_app/can_admin_app helpers), and the validate→authorize→execute→audit
+pipeline of member_action_service.
+"""
+from werkzeug.security import generate_password_hash
+
+from app import db
+from app.models import Application, User
+from app.services import member_action_service as ma
+from app.services.resource_grant_service import ResourceGrantService as RGS
+
+
+def _user(username, role='developer'):
+ 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 _app(owner, name):
+ a = Application(name=name, app_type='php', user_id=owner.id)
+ db.session.add(a)
+ db.session.commit()
+ return a
+
+
+def test_enabled_by_default_and_lists_template(app):
+ assert ma.is_enabled() is True
+ actions = ma.list_actions()
+ ids = {a['id'] for a in actions}
+ assert 'set-backup-frequency' in ids
+ # Client-safe view never leaks the executor callable.
+ assert all('executor' not in a for a in actions)
+
+
+def test_two_kill_switches_disable_the_surface(app):
+ from app.models.system_settings import SystemSettings
+ from app import db as _db
+ owner = _user('ma_off_owner')
+ a = _app(owner, 'ma-off-app')
+
+ # System-setting switch off (admin-stored boolean).
+ SystemSettings.set('security_member_actions_enabled', False, value_type='boolean')
+ _db.session.commit()
+ assert ma.is_enabled() is False
+ assert ma.list_actions() == []
+ result, err = ma.run(owner, a, 'set-backup-frequency', {'frequency': 'daily'})
+ assert result is None and err == ('Member actions are disabled', 403)
+
+ # Back on via the system setting, off via the deployment config flag.
+ SystemSettings.set('security_member_actions_enabled', True, value_type='boolean')
+ _db.session.commit()
+ assert ma.is_enabled() is True
+ app.config['MEMBER_ACTIONS_ENABLED'] = False
+ try:
+ assert ma.is_enabled() is False
+ finally:
+ app.config['MEMBER_ACTIONS_ENABLED'] = True
+
+
+def test_unknown_action_is_404(app):
+ owner = _user('ma_unk_owner')
+ a = _app(owner, 'ma-unk-app')
+ result, err = ma.run(owner, a, 'no-such-action', {})
+ assert result is None and err == ('Unknown action', 404)
+
+
+def test_stranger_is_denied(app):
+ owner = _user('ma_str_owner')
+ stranger = _user('ma_stranger')
+ a = _app(owner, 'ma-str-app')
+ result, err = ma.run(stranger, a, 'set-backup-frequency', {'frequency': 'daily'})
+ assert result is None and err == ('Access denied', 403)
+
+
+def test_viewer_grant_cannot_run_member_action(app):
+ owner = _user('ma_v_owner')
+ viewer = _user('ma_viewer')
+ a = _app(owner, 'ma-v-app')
+ RGS.grant(viewer.id, 'application', a.id, granted_by=owner.id, role='viewer')
+ # A viewer is below the 'member' min_role of the template.
+ assert not RGS.can_operate_app(viewer, a)
+ result, err = ma.run(viewer, a, 'set-backup-frequency', {'frequency': 'daily'})
+ assert result is None and err == ('Access denied', 403)
+
+
+def test_bad_params_are_rejected(app):
+ owner = _user('ma_bad_owner')
+ a = _app(owner, 'ma-bad-app')
+ # Enum violation -> 400 (never reaches the executor).
+ result, err = ma.run(owner, a, 'set-backup-frequency', {'frequency': 'hourly'})
+ assert result is None
+ assert err[1] == 400
+
+
+def test_editor_runs_action_end_to_end(app):
+ owner = _user('ma_e_owner')
+ editor = _user('ma_editor')
+ a = _app(owner, 'ma-e-app')
+ RGS.grant(editor.id, 'application', a.id, granted_by=owner.id, role='editor')
+ assert RGS.can_operate_app(editor, a)
+
+ result, err = ma.run(editor, a, 'set-backup-frequency', {'frequency': 'weekly'})
+ assert err is None
+ assert result['action'] == 'set-backup-frequency'
+ assert result['result']['frequency'] == 'weekly'
+ assert result['result']['enabled'] is True
diff --git a/backend/tests/test_notification_digest.py b/backend/tests/test_notification_digest.py
new file mode 100644
index 00000000..c52d0f81
--- /dev/null
+++ b/backend/tests/test_notification_digest.py
@@ -0,0 +1,191 @@
+"""Proving tests for notification digest rollups (plan 24 Phase 3).
+
+Reconstructed alongside the lost ``app/notifications/digest.py``; no surviving
+test, so this file is the executable contract for cadence windows, grouping,
+the empty/single-item guards, and the queued_digest -> sent flip.
+"""
+from datetime import datetime, timedelta
+
+import pytest
+from werkzeug.security import generate_password_hash
+
+from app import db
+from app.models import User
+from app.models.notification_preferences import NotificationPreferences
+from app.notifications import digest
+from app.notifications.models import Notification, NotificationDelivery
+
+
[email protected](autouse=True)
+def _capture_transmit(monkeypatch):
+ """Capture the outgoing digest email instead of hitting a real transport."""
+ sent = {}
+
+ def fake_transmit(to_addr, rendered):
+ sent['to'] = to_addr
+ sent['rendered'] = rendered
+ return True, 'digest-msg-1', None
+
+ monkeypatch.setattr(digest, '_transmit', fake_transmit)
+ return sent
+
+
+def _user(username='dg', cadence='daily', last_sent=None):
+ u = User(email=f'{username}@t.local', username=username,
+ password_hash=generate_password_hash('x'), role='developer', is_active=True)
+ db.session.add(u)
+ db.session.commit()
+ prefs = NotificationPreferences.get_or_create(u.id)
+ prefs.digest_cadence = cadence
+ prefs.digest_last_sent_at = last_sent
+ db.session.commit()
+ return u
+
+
+def _queue(user, event='backup.completed', category='backups', severity='success',
+ title='Backup completed: blog', when=None):
+ """Create a notification + a queued_digest email delivery for the user."""
+ n = Notification(event_key=event, category=category, severity=severity, title=title)
+ n.set_data({'message': title})
+ if when is not None:
+ n.created_at = when
+ db.session.add(n)
+ db.session.flush()
+ d = NotificationDelivery(
+ notification_id=n.id, recipient_user_id=user.id,
+ channel=NotificationDelivery.CHANNEL_EMAIL, target=user.email,
+ status=NotificationDelivery.STATUS_QUEUED_DIGEST,
+ )
+ db.session.add(d)
+ db.session.commit()
+ return d
+
+
+# --------------------------------------------------------------------------- #
+# Cadence windows
+# --------------------------------------------------------------------------- #
+
+def test_is_due_windows(app):
+ off = _user('off_u', cadence='off')
+ assert digest.is_due(NotificationPreferences.get_or_create(off.id)) is False
+
+ fresh = _user('fresh_u', cadence='daily', last_sent=None)
+ assert digest.is_due(NotificationPreferences.get_or_create(fresh.id)) is True
+
+ recent = _user('recent_u', cadence='daily',
+ last_sent=datetime.utcnow() - timedelta(hours=1))
+ assert digest.is_due(NotificationPreferences.get_or_create(recent.id)) is False
+
+ stale = _user('stale_u', cadence='daily',
+ last_sent=datetime.utcnow() - timedelta(days=2))
+ assert digest.is_due(NotificationPreferences.get_or_create(stale.id)) is True
+
+ weekly_mid = _user('weekly_u', cadence='weekly',
+ last_sent=datetime.utcnow() - timedelta(days=3))
+ assert digest.is_due(NotificationPreferences.get_or_create(weekly_mid.id)) is False
+
+
+# --------------------------------------------------------------------------- #
+# Send + flip
+# --------------------------------------------------------------------------- #
+
+def test_send_groups_flips_and_stamps(app, _capture_transmit):
+ u = _user('grp')
+ d1 = _queue(u, category='backups', severity='success', title='Backup completed: blog')
+ d2 = _queue(u, event='security.alert', category='security', severity='critical',
+ title='Security alert: brute force')
+ d3 = _queue(u, event='app.deployed', category='apps', severity='success',
+ title='Deployed: api')
+
+ result = digest.send_user_digest(u.id)
+ assert result['sent'] is True
+ assert result['count'] == 3
+ assert '3 updates' in result['subject']
+ assert result['message_id'] == 'digest-msg-1'
+
+ # All held deliveries flipped to sent with the digest's message id.
+ for d in (d1, d2, d3):
+ db.session.refresh(d)
+ assert d.status == NotificationDelivery.STATUS_SENT
+ assert d.provider_message_id == 'digest-msg-1'
+ assert d.sent_at is not None
+
+ # Clock stamped so the next tick won't re-send.
+ prefs = NotificationPreferences.get_or_create(u.id)
+ assert prefs.digest_last_sent_at is not None
+
+ # Rendered HTML actually grouped by category (real template render).
+ html = _capture_transmit['rendered']['html']
+ assert 'Security' in html and 'Backups' in html and 'Apps' in html
+ assert 'Security alert: brute force' in html
+ assert _capture_transmit['to'] == u.email
+
+
+def test_empty_digest_never_sends(app, _capture_transmit):
+ u = _user('empty')
+ result = digest.send_user_digest(u.id)
+ assert result['sent'] is False
+ assert result['reason'] == 'empty'
+ # No transport call, no clock stamp.
+ assert 'to' not in _capture_transmit
+ prefs = NotificationPreferences.get_or_create(u.id)
+ assert prefs.digest_last_sent_at is None
+
+
+def test_single_item_uses_its_own_subject(app, _capture_transmit):
+ u = _user('single')
+ _queue(u, category='backups', title='Backup completed: solo-site')
+ result = digest.send_user_digest(u.id)
+ assert result['sent'] is True
+ assert result['count'] == 1
+ assert result['subject'] == 'Backup completed: solo-site' # no "1 update" shame
+
+
+def test_transient_send_failure_leaves_deliveries_queued(app, monkeypatch):
+ u = _user('fail')
+ d = _queue(u)
+ monkeypatch.setattr(digest, '_transmit',
+ lambda to, rendered: (False, None, 'smtp down'))
+ result = digest.send_user_digest(u.id)
+ assert result['sent'] is False
+ db.session.refresh(d)
+ # Still queued for the next attempt — not marked sent.
+ assert d.status == NotificationDelivery.STATUS_QUEUED_DIGEST
+ prefs = NotificationPreferences.get_or_create(u.id)
+ assert prefs.digest_last_sent_at is None
+
+
+# --------------------------------------------------------------------------- #
+# The hourly tick
+# --------------------------------------------------------------------------- #
+
+def test_run_due_only_mails_elapsed_users(app):
+ due = _user('due_u', cadence='daily', last_sent=None)
+ _queue(due)
+
+ not_due = _user('notdue_u', cadence='daily',
+ last_sent=datetime.utcnow() - timedelta(minutes=5))
+ _queue(not_due)
+
+ off = _user('off2_u', cadence='off')
+ _queue(off)
+
+ summary = digest.run_due()
+ assert summary['sent'] == 1 # only the elapsed daily user
+
+ # The due user's delivery is sent; the others remain queued.
+ due_deliveries = digest.pending_for_user(due.id)
+ assert due_deliveries == [] # flipped out of queued_digest
+ assert len(digest.pending_for_user(not_due.id)) == 1
+ assert len(digest.pending_for_user(off.id)) == 1
+
+
+def test_run_due_skips_users_with_no_pending(app):
+ """A user whose window elapsed but has nothing queued is skipped (empty
+ never sends) and their clock is NOT stamped."""
+ u = _user('nopending', cadence='daily', last_sent=None)
+ summary = digest.run_due()
+ assert summary['sent'] == 0
+ assert summary['skipped'] >= 1
+ prefs = NotificationPreferences.get_or_create(u.id)
+ assert prefs.digest_last_sent_at is None
diff --git a/backend/tests/test_per_app_read_scoping.py b/backend/tests/test_per_app_read_scoping.py
new file mode 100644
index 00000000..d63746ba
--- /dev/null
+++ b/backend/tests/test_per_app_read_scoping.py
@@ -0,0 +1,137 @@
+"""Proving matrix for the per-app capability tiers (plan 29 / plan 19).
+
+Locks the four-rung access family down against the single tier seam in
+``rbac.app_access_tier`` ('viewer' < 'member' < 'admin' < 'owner'):
+
+ can_access_app — read (owner/admin/any grant)
+ can_operate_app — member+ (owner, panel admin, editor grant, ws member+)
+ can_edit_app — editor grant (or owner/admin)
+ can_admin_app — admin+ (owner, panel admin, ws admin/owner)
+
+``can_operate_app`` / ``can_admin_app`` were lost in the recovery and are
+reconstructed here (a surviving caller, member_action_service, depends on them).
+"""
+from werkzeug.security import generate_password_hash
+
+from app import db
+from app.models import Application, User
+from app.models.workspace import Workspace, WorkspaceMember
+from app.middleware.rbac import app_access_tier, _APP_ROLE_RANK
+from app.services.resource_grant_service import ResourceGrantService as RGS
+
+
+def _user(username, role='developer'):
+ 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 _app(owner, name, workspace_id=None):
+ a = Application(name=name, app_type='php', user_id=owner.id, workspace_id=workspace_id)
+ db.session.add(a)
+ db.session.commit()
+ return a
+
+
+def _workspace(slug):
+ ws = Workspace(name=slug, slug=slug)
+ db.session.add(ws)
+ db.session.commit()
+ return ws
+
+
+def _member(ws, user, role):
+ db.session.add(WorkspaceMember(workspace_id=ws.id, user_id=user.id, role=role))
+ db.session.commit()
+
+
+# --------------------------------------------------------------------------- #
+# Grant-based personas
+# --------------------------------------------------------------------------- #
+
+def test_owner_reaches_every_tier(app):
+ owner = _user('s_owner')
+ a = _app(owner, 's-owner-app')
+ assert app_access_tier(owner, a) == 'owner'
+ assert RGS.can_access_app(owner, a)
+ assert RGS.can_operate_app(owner, a)
+ assert RGS.can_edit_app(owner, a)
+ assert RGS.can_admin_app(owner, a)
+
+
+def test_panel_admin_reaches_every_tier(app):
+ owner = _user('s_o2')
+ admin = _user('s_admin', role='admin')
+ a = _app(owner, 's-admin-app')
+ assert admin.is_admin
+ assert app_access_tier(admin, a) == 'owner'
+ assert RGS.can_operate_app(admin, a)
+ assert RGS.can_admin_app(admin, a)
+
+
+def test_editor_grant_operates_but_not_admins(app):
+ owner = _user('s_o3')
+ editor = _user('s_editor')
+ a = _app(owner, 's-editor-app')
+ RGS.grant(editor.id, 'application', a.id, granted_by=owner.id, role='editor')
+ assert app_access_tier(editor, a) == 'member'
+ assert RGS.can_access_app(editor, a)
+ assert RGS.can_operate_app(editor, a)
+ assert RGS.can_edit_app(editor, a)
+ assert not RGS.can_admin_app(editor, a)
+
+
+def test_viewer_grant_is_read_only(app):
+ owner = _user('s_o4')
+ viewer = _user('s_viewer')
+ a = _app(owner, 's-viewer-app')
+ RGS.grant(viewer.id, 'application', a.id, granted_by=owner.id, role='viewer')
+ assert app_access_tier(viewer, a) == 'viewer'
+ assert RGS.can_access_app(viewer, a)
+ assert not RGS.can_operate_app(viewer, a)
+ assert not RGS.can_edit_app(viewer, a)
+ assert not RGS.can_admin_app(viewer, a)
+
+
+def test_stranger_reaches_nothing(app):
+ owner = _user('s_o5')
+ stranger = _user('s_stranger')
+ a = _app(owner, 's-stranger-app')
+ assert app_access_tier(stranger, a) is None
+ assert not RGS.can_access_app(stranger, a)
+ assert not RGS.can_operate_app(stranger, a)
+ assert not RGS.can_edit_app(stranger, a)
+ assert not RGS.can_admin_app(stranger, a)
+
+
+# --------------------------------------------------------------------------- #
+# Workspace-membership personas (widen operate/admin, not grants)
+# --------------------------------------------------------------------------- #
+
+def test_workspace_member_can_operate_not_admin(app):
+ owner = _user('w_owner')
+ ws = _workspace('ws-ops')
+ member = _user('w_member')
+ _member(ws, member, WorkspaceMember.ROLE_MEMBER)
+ a = _app(owner, 'w-ops-app', workspace_id=ws.id)
+ assert app_access_tier(member, a) == 'member'
+ assert RGS.can_operate_app(member, a)
+ assert not RGS.can_admin_app(member, a)
+
+
+def test_workspace_admin_can_admin(app):
+ owner = _user('w_owner2')
+ ws = _workspace('ws-adm')
+ wsadmin = _user('w_admin')
+ _member(ws, wsadmin, WorkspaceMember.ROLE_ADMIN)
+ a = _app(owner, 'w-adm-app', workspace_id=ws.id)
+ assert app_access_tier(wsadmin, a) == 'admin'
+ assert RGS.can_operate_app(wsadmin, a)
+ assert RGS.can_admin_app(wsadmin, a)
+
+
+def test_tier_rank_ordering_is_consistent(app):
+ assert (_APP_ROLE_RANK['viewer'] < _APP_ROLE_RANK['member']
+ < _APP_ROLE_RANK['admin'] < _APP_ROLE_RANK['owner'])
diff --git a/backend/tests/test_security_policy.py b/backend/tests/test_security_policy.py
new file mode 100644
index 00000000..cee64aec
--- /dev/null
+++ b/backend/tests/test_security_policy.py
@@ -0,0 +1,118 @@
+"""Proving tests for SecurityPolicyService — the require-2FA enrollment policy
+(plan 29 Phase 2: ok/nudge/enforce, SSO-exempt, activation-anchored grace).
+
+Reconstructed alongside the lost service; there was no surviving test, so this
+file is the executable contract.
+"""
+from datetime import datetime, timedelta
+
+from werkzeug.security import generate_password_hash
+
+from app import db
+from app.models import User
+from app.services.security_policy_service import (
+ SecurityPolicyService as SPS,
+ SETTING_ENABLED_AT,
+ SETTING_REQUIRE_2FA,
+)
+
+
+def _user(username='u', *, provider='local', totp=False, created_days_ago=1):
+ u = User(
+ email=f'{username}@t.local', username=username,
+ password_hash=generate_password_hash('x'), role='developer',
+ is_active=True, auth_provider=provider, totp_enabled=totp,
+ created_at=datetime.utcnow() - timedelta(days=created_days_ago),
+ )
+ db.session.add(u)
+ db.session.commit()
+ return u
+
+
+def test_policy_off_is_always_ok(app):
+ u = _user('off')
+ assert SPS.require_2fa_enabled() is False
+ assert SPS.evaluate(u) == SPS.OK
+
+
+def test_enabling_stamps_activation_once(app):
+ from app.services.settings_service import SettingsService
+ assert SettingsService.get(SETTING_ENABLED_AT) in (None, '')
+ SPS.set_require_2fa(True)
+ first = SettingsService.get(SETTING_ENABLED_AT)
+ assert first # stamped on off->on
+ # Re-affirming ON does not move the anchor.
+ SPS.set_require_2fa(True)
+ assert SettingsService.get(SETTING_ENABLED_AT) == first
+ assert SPS.require_2fa_enabled() is True
+
+
+def test_veteran_gets_full_grace_on_flip(app):
+ """A 100-day-old account without 2FA is only NUDGEd right after the policy
+ flips on — the grace clock starts at activation, not account age."""
+ u = _user('vet', created_days_ago=100)
+ SPS.set_require_2fa(True)
+ assert SPS.evaluate(u) == SPS.NUDGE
+ # ...and enforcement only bites once the window from activation elapses.
+ past_window = datetime.utcnow() + timedelta(days=SPS.GRACE_PERIOD_DAYS + 1)
+ assert SPS.evaluate(u, now=past_window) == SPS.ENFORCE
+
+
+def test_enforced_after_grace(app):
+ # Old account so the anchor is the (backdated) activation, not created_at.
+ u = _user('late', created_days_ago=100)
+ SPS.set_require_2fa(True)
+ # Backdate the activation so the grace window is already gone.
+ from app.services.settings_service import SettingsService
+ SettingsService.set(
+ SETTING_ENABLED_AT,
+ (datetime.utcnow() - timedelta(days=SPS.GRACE_PERIOD_DAYS + 3)).isoformat(),
+ )
+ assert SPS.evaluate(u) == SPS.ENFORCE
+
+
+def test_user_with_2fa_is_ok(app):
+ u = _user('has2fa', totp=True)
+ SPS.set_require_2fa(True)
+ from app.services.settings_service import SettingsService
+ SettingsService.set(
+ SETTING_ENABLED_AT,
+ (datetime.utcnow() - timedelta(days=99)).isoformat(),
+ )
+ # Even past the grace window, an enrolled user is fine.
+ assert SPS.evaluate(u) == SPS.OK
+ assert SPS.user_has_2fa(u) is True
+
+
+def test_sso_user_is_exempt(app):
+ u = _user('sso', provider='google')
+ SPS.set_require_2fa(True)
+ from app.services.settings_service import SettingsService
+ SettingsService.set(
+ SETTING_ENABLED_AT,
+ (datetime.utcnow() - timedelta(days=99)).isoformat(),
+ )
+ assert SPS.is_sso_user(u) is True
+ assert SPS.evaluate(u) == SPS.OK
+
+
+def test_grace_anchor_is_max_of_created_and_activation(app):
+ # Account younger than the policy activation -> anchor on the account.
+ young = _user('young', created_days_ago=0)
+ SPS.set_require_2fa(True)
+ from app.services.settings_service import SettingsService
+ activation = datetime.utcnow() - timedelta(days=30)
+ SettingsService.set(SETTING_ENABLED_AT, activation.isoformat())
+ anchor = SPS.grace_anchor(young)
+ # young.created_at (now-ish) is later than the 30-day-old activation.
+ assert anchor >= young.created_at - timedelta(seconds=2)
+
+
+def test_status_snapshot_shape(app):
+ u = _user('snap')
+ SPS.set_require_2fa(True)
+ snap = SPS.status(u)
+ assert snap['required'] is True
+ assert snap['result'] in (SPS.NUDGE, SPS.ENFORCE)
+ assert snap['has_2fa'] is False
+ assert snap['grace_deadline'] is not None