|null $override
+ * @return array{ok:bool,to:string,error?:string}
+ */
+ public function test(?array $override, string $to, bool $updateSavedMeta = true, ?int $tenantId = null): array
+ {
+ $to = trim($to);
+ if ($to === '' || !filter_var($to, FILTER_VALIDATE_EMAIL)) {
+ return ['ok' => false, 'to' => $to, 'error' => 'Invalid test recipient'];
+ }
+ if ($tenantId && !$this->tenantHasCustomSmtp($tenantId)) {
+ return ['ok' => false, 'to' => $to, 'error' => 'Custom SMTP is not included in your plan'];
+ }
+
+ $saved = $tenantId ? $this->tenantRow($tenantId) : $this->platformRow();
+ $transport = $tenantId ? 'tenant' : 'platform';
+ try {
+ $cfg = $override && !empty($override['host'])
+ ? $this->normalizeInput($override, $saved)
+ : $this->rowToConfig($saved);
+ if ($cfg === null) {
+ return ['ok' => false, 'to' => $to, 'error' => 'Enter SMTP settings first'];
+ }
+ $cfg['transport'] = $transport;
+
+ $mail = $this->buildMailer($cfg);
+ $mail->smtpConnect();
+ $mail->smtpClose();
+
+ if (!self::isTestAddress($to)) {
+ $mail = $this->buildMailer($cfg);
+ $mail->setFrom($cfg['from_email'], $cfg['from_name'] ?: 'App');
+ $mail->addAddress($to);
+ $mail->Subject = 'SMTP test';
+ $scope = $tenantId ? 'workspace' : 'platform';
+ $mail->Body = 'SMTP test from App ' . $scope . ' gateway.
Server: '
+ . htmlspecialchars($cfg['host'] . ':' . $cfg['port']) . '
';
+ $mail->AltBody = 'SMTP test from App ' . $scope . ' gateway.';
+ $mail->send();
+ }
+
+ if ($updateSavedMeta && $saved && empty($override['host'])) {
+ $this->markTest((int) $saved['id'], true, null);
+ }
+ $this->writeLog($tenantId, $to, 'SMTP test', 'smtp_test', null, $transport, 'sent', null);
+ return ['ok' => true, 'to' => $to];
+ } catch (\Throwable $e) {
+ $err = mb_substr($e->getMessage(), 0, 500);
+ if ($tenantId) {
+ // Don't leak raw SMTP banners to tenant admins
+ $err = 'Connection or authentication failed. Check host, port, and credentials.';
+ }
+ if ($updateSavedMeta && $saved && empty($override['host'] ?? null)) {
+ $this->markTest((int) $saved['id'], false, $err);
+ }
+ $this->writeLog($tenantId, $to, 'SMTP test', 'smtp_test', null, $transport, 'failed', $err);
+ return ['ok' => false, 'to' => $to, 'error' => $err];
+ }
+ }
+
+ /** @return array|null public view */
+ public function getPublicPlatform(): ?array
+ {
+ $row = $this->platformRow();
+ return $row ? $this->toPublic($row) : null;
+ }
+
+ /** @param array $body */
+ public function savePlatform(array $body): array
+ {
+ $cur = $this->platformRow();
+ $v = $this->normalizeInput($body, $cur);
+ if ($cur) {
+ $stmt = $this->conn->prepare(
+ "UPDATE smtp_settings SET
+ host=:host, port=:port, secure=:secure, username=:username, password_enc=:password_enc,
+ from_email=:from_email, from_name=:from_name, reply_to=:reply_to, enabled=:enabled,
+ last_test_at=NULL, last_test_ok=NULL, last_error=NULL
+ WHERE id=:id AND tenant_id IS NULL"
+ );
+ $stmt->execute([
+ ':id' => $cur['id'],
+ ':host' => $v['host'],
+ ':port' => $v['port'],
+ ':secure' => $v['secure'],
+ ':username' => $v['username'],
+ ':password_enc' => $v['password_enc'],
+ ':from_email' => $v['from_email'],
+ ':from_name' => $v['from_name'],
+ ':reply_to' => $v['reply_to'],
+ ':enabled' => $v['enabled'],
+ ]);
+ } else {
+ $stmt = $this->conn->prepare(
+ "INSERT INTO smtp_settings
+ (tenant_id, host, port, secure, username, password_enc, from_email, from_name, reply_to, enabled)
+ VALUES
+ (NULL, :host, :port, :secure, :username, :password_enc, :from_email, :from_name, :reply_to, :enabled)"
+ );
+ $stmt->execute([
+ ':host' => $v['host'],
+ ':port' => $v['port'],
+ ':secure' => $v['secure'],
+ ':username' => $v['username'],
+ ':password_enc' => $v['password_enc'],
+ ':from_email' => $v['from_email'],
+ ':from_name' => $v['from_name'],
+ ':reply_to' => $v['reply_to'],
+ ':enabled' => $v['enabled'],
+ ]);
+ }
+ return $this->getPublicPlatform() ?? [];
+ }
+
+ public function deletePlatform(): bool
+ {
+ return $this->conn->exec('DELETE FROM smtp_settings WHERE tenant_id IS NULL') !== false;
+ }
+
+ public function getPublicTenant(int $tenantId): ?array
+ {
+ $row = $this->tenantRow($tenantId);
+ return $row ? $this->toPublic($row) : null;
+ }
+
+ public function saveTenant(int $tenantId, array $body): array
+ {
+ if (!$this->tenantHasCustomSmtp($tenantId)) {
+ throw new \InvalidArgumentException('Custom SMTP is not included in your plan');
+ }
+ $cur = $this->tenantRow($tenantId);
+ $v = $this->normalizeInput($body, $cur);
+ if ($cur) {
+ $stmt = $this->conn->prepare(
+ "UPDATE smtp_settings SET
+ host=:host, port=:port, secure=:secure, username=:username, password_enc=:password_enc,
+ from_email=:from_email, from_name=:from_name, reply_to=:reply_to, enabled=:enabled,
+ last_test_at=NULL, last_test_ok=NULL, last_error=NULL
+ WHERE id=:id AND tenant_id=:tid"
+ );
+ $stmt->execute([
+ ':id' => $cur['id'],
+ ':tid' => $tenantId,
+ ':host' => $v['host'],
+ ':port' => $v['port'],
+ ':secure' => $v['secure'],
+ ':username' => $v['username'],
+ ':password_enc' => $v['password_enc'],
+ ':from_email' => $v['from_email'],
+ ':from_name' => $v['from_name'],
+ ':reply_to' => $v['reply_to'],
+ ':enabled' => $v['enabled'],
+ ]);
+ } else {
+ $stmt = $this->conn->prepare(
+ "INSERT INTO smtp_settings
+ (tenant_id, host, port, secure, username, password_enc, from_email, from_name, reply_to, enabled)
+ VALUES
+ (:tid, :host, :port, :secure, :username, :password_enc, :from_email, :from_name, :reply_to, :enabled)"
+ );
+ $stmt->execute([
+ ':tid' => $tenantId,
+ ':host' => $v['host'],
+ ':port' => $v['port'],
+ ':secure' => $v['secure'],
+ ':username' => $v['username'],
+ ':password_enc' => $v['password_enc'],
+ ':from_email' => $v['from_email'],
+ ':from_name' => $v['from_name'],
+ ':reply_to' => $v['reply_to'],
+ ':enabled' => $v['enabled'],
+ ]);
+ }
+ return $this->getPublicTenant($tenantId) ?? [];
+ }
+
+ public function deleteTenant(int $tenantId): bool
+ {
+ $stmt = $this->conn->prepare('DELETE FROM smtp_settings WHERE tenant_id = :tid');
+ return $stmt->execute([':tid' => $tenantId]);
+ }
+
+ /** Tenant email page payload — network + optional custom SMTP. */
+ public function tenantEmailBundle(int $tenantId): array
+ {
+ $platform = $this->platformRow();
+ $emailsStmt = $this->conn->prepare(
+ "SELECT id, to_email, subject, template, transport, status, error, created_at
+ FROM email_log WHERE tenant_id = :tid
+ ORDER BY created_at DESC LIMIT 25"
+ );
+ $emailsStmt->execute([':tid' => $tenantId]);
+ $route = $this->describeRoute($tenantId);
+ $tenantSmtp = $this->getPublicTenant($tenantId);
+ // Hide stored custom SMTP from UI when plan does not allow it
+ if (!$route['allowed_custom']) {
+ $tenantSmtp = null;
+ }
+ return [
+ 'engine' => 'phpmailer',
+ 'route' => $route,
+ 'allowed' => $route['allowed_custom'],
+ 'smtp' => $tenantSmtp,
+ 'platform' => ($platform && (int) $platform['enabled'] === 1)
+ ? [
+ 'from_email' => $platform['from_email'],
+ 'from_name' => $platform['from_name'],
+ 'enabled' => true,
+ ]
+ : ($this->isNetworkConfigured()
+ ? ['from_email' => (string) Environment::get('MAIL_FROM_ADDRESS', ''), 'from_name' => (string) Environment::get('MAIL_FROM_NAME', 'App'), 'enabled' => true, 'via_env' => true]
+ : null),
+ 'emails' => $emailsStmt->fetchAll(\PDO::FETCH_ASSOC),
+ ];
+ }
+
+ public function tenantHasCustomSmtp(int $tenantId): bool
+ {
+ $stmt = $this->conn->prepare(
+ "SELECT t.features AS tenant_features, p.features AS plan_features
+ FROM tenants t
+ LEFT JOIN plans p ON p.id = t.plan_id
+ WHERE t.id = :tid AND t.deleted_at IS NULL LIMIT 1"
+ );
+ $stmt->execute([':tid' => $tenantId]);
+ $row = $stmt->fetch(\PDO::FETCH_ASSOC);
+ if (!$row) {
+ return false;
+ }
+ $tf = json_decode($row['tenant_features'] ?? '{}', true) ?: [];
+ $pf = json_decode($row['plan_features'] ?? '{}', true) ?: [];
+ if (array_key_exists('custom_smtp', $tf)) {
+ return !empty($tf['custom_smtp']);
+ }
+ return !empty($pf['custom_smtp']);
+ }
+
+ /** @return array{emails:list,summary:array} */
+ public function listLog(?string $status = 'all', int $limit = 100, ?int $tenantId = null): array
+ {
+ $limit = max(1, min(500, $limit));
+ $sql = "SELECT e.*, t.name AS tenant_name
+ FROM email_log e
+ LEFT JOIN tenants t ON t.id = e.tenant_id
+ WHERE 1=1";
+ $params = [];
+ if ($tenantId !== null) {
+ $sql .= ' AND e.tenant_id = :tid';
+ $params[':tid'] = $tenantId;
+ }
+ if ($status && $status !== 'all') {
+ $sql .= ' AND e.status = :st';
+ $params[':st'] = $status;
+ }
+ $sql .= " ORDER BY e.created_at DESC LIMIT {$limit}";
+ $stmt = $this->conn->prepare($sql);
+ $stmt->execute($params);
+ $emails = $stmt->fetchAll(\PDO::FETCH_ASSOC);
+
+ if ($tenantId !== null) {
+ $sumStmt = $this->conn->prepare(
+ "SELECT
+ SUM(status='sent') AS sent,
+ SUM(status='failed') AS failed,
+ SUM(status='skipped') AS skipped,
+ SUM(transport='platform') AS via_platform,
+ SUM(transport='tenant') AS via_tenant
+ FROM email_log
+ WHERE tenant_id = :tid AND created_at > DATE_SUB(NOW(), INTERVAL 30 DAY)"
+ );
+ $sumStmt->execute([':tid' => $tenantId]);
+ $sum = $sumStmt->fetch(\PDO::FETCH_ASSOC) ?: [];
+ } else {
+ $sum = $this->conn->query(
+ "SELECT
+ SUM(status='sent') AS sent,
+ SUM(status='failed') AS failed,
+ SUM(status='skipped') AS skipped,
+ SUM(transport='platform') AS via_platform,
+ SUM(transport='tenant') AS via_tenant
+ FROM email_log
+ WHERE created_at > DATE_SUB(NOW(), INTERVAL 30 DAY)"
+ )->fetch(\PDO::FETCH_ASSOC) ?: [];
+ }
+
+ return [
+ 'emails' => $emails,
+ 'summary' => [
+ 'sent' => (int) ($sum['sent'] ?? 0),
+ 'failed' => (int) ($sum['failed'] ?? 0),
+ 'skipped' => (int) ($sum['skipped'] ?? 0),
+ 'via_platform' => (int) ($sum['via_platform'] ?? 0),
+ 'via_tenant' => (int) ($sum['via_tenant'] ?? 0),
+ 'smtp_configured' => $this->isConfigured($tenantId),
+ ],
+ ];
+ }
+
+ /** @param array $body @param array|false|null $cur */
+ private function normalizeInput(array $body, $cur): array
+ {
+ $host = strtolower(trim((string) ($body['host'] ?? '')));
+ if ($host === '' || !preg_match('/^[a-z0-9.-]+$/', $host) || strlen($host) > 253) {
+ throw new \InvalidArgumentException('SMTP host is invalid');
+ }
+ $port = (int) ($body['port'] ?? 587);
+ if (!in_array($port, self::PORTS, true)) {
+ throw new \InvalidArgumentException('Port must be one of ' . implode(', ', self::PORTS));
+ }
+ $from = trim((string) ($body['from_email'] ?? $body['fromEmail'] ?? ''));
+ if ($from === '' || !filter_var($from, FILTER_VALIDATE_EMAIL)) {
+ throw new \InvalidArgumentException('From email is invalid');
+ }
+ $username = trim((string) ($body['username'] ?? ''));
+ $password = array_key_exists('password', $body) ? (string) $body['password'] : '';
+ $enc = $cur['password_enc'] ?? null;
+ if ($password !== '') {
+ if (strlen($password) > 500) {
+ throw new \InvalidArgumentException('Password is too long');
+ }
+ $enc = \BitsHost\UpmvcSaas\Security\SecretBox::seal($password);
+ } elseif ($username === '') {
+ $enc = null;
+ }
+ $reply = trim((string) ($body['reply_to'] ?? $body['replyTo'] ?? ''));
+ if ($reply !== '' && !filter_var($reply, FILTER_VALIDATE_EMAIL)) {
+ throw new \InvalidArgumentException('Reply-To is invalid');
+ }
+ $secure = array_key_exists('secure', $body)
+ ? (!empty($body['secure']) ? 1 : 0)
+ : ($port === 465 ? 1 : 0);
+
+ return [
+ 'host' => $host,
+ 'port' => $port,
+ 'secure' => $secure,
+ 'username' => $username !== '' ? $username : null,
+ 'password_enc' => $enc,
+ 'from_email' => $from,
+ 'from_name' => mb_substr(trim((string) ($body['from_name'] ?? $body['fromName'] ?? '')), 0, 120) ?: null,
+ 'reply_to' => $reply !== '' ? $reply : null,
+ 'enabled' => array_key_exists('enabled', $body) ? (!empty($body['enabled']) ? 1 : 0) : 1,
+ ];
+ }
+
+ private function platformRow(): array|false
+ {
+ return $this->conn->query(
+ 'SELECT * FROM smtp_settings WHERE tenant_id IS NULL LIMIT 1'
+ )->fetch(\PDO::FETCH_ASSOC);
+ }
+
+ private function tenantRow(int $tenantId): array|false
+ {
+ $stmt = $this->conn->prepare(
+ 'SELECT * FROM smtp_settings WHERE tenant_id = :tid LIMIT 1'
+ );
+ $stmt->execute([':tid' => $tenantId]);
+ return $stmt->fetch(\PDO::FETCH_ASSOC);
+ }
+
+ /**
+ * @param bool $allowTenantSmtp when false, skip tenant custom SMTP (network-only)
+ * @return array|null
+ */
+ private function resolveConfig(?int $tenantId = null, bool $allowTenantSmtp = true): ?array
+ {
+ // Custom SMTP only when plan includes custom_smtp and settings are enabled
+ if ($allowTenantSmtp && $tenantId && $this->tenantHasCustomSmtp($tenantId)) {
+ $t = $this->tenantRow($tenantId);
+ if ($t && (int) $t['enabled'] === 1) {
+ $cfg = $this->rowToConfig($t);
+ if ($cfg) {
+ $cfg['transport'] = 'tenant';
+ return $cfg;
+ }
+ }
+ }
+
+ // Network / platform gateway (shared for all tenants)
+ $row = $this->platformRow();
+ if ($row && (int) $row['enabled'] === 1) {
+ $cfg = $this->rowToConfig($row);
+ if ($cfg) {
+ $cfg['transport'] = 'platform';
+ return $cfg;
+ }
+ }
+
+ // .env fallback (still "network" for tenants)
+ $host = (string) Environment::get('MAIL_HOST', '');
+ if ($host === '') {
+ return null;
+ }
+ return [
+ 'host' => $host,
+ 'port' => (int) Environment::get('MAIL_PORT', 587),
+ 'secure' => strtolower((string) Environment::get('MAIL_ENCRYPTION', 'tls')) === 'ssl',
+ 'username' => (string) Environment::get('MAIL_USERNAME', ''),
+ 'password' => (string) Environment::get('MAIL_PASSWORD', ''),
+ 'from_email' => (string) Environment::get('MAIL_FROM_ADDRESS', 'noreply@example.com'),
+ 'from_name' => (string) Environment::get('MAIL_FROM_NAME', 'App'),
+ 'reply_to' => null,
+ 'transport' => 'platform',
+ 'from_env' => true,
+ 'encryption' => (string) Environment::get('MAIL_ENCRYPTION', 'tls'),
+ ];
+ }
+
+ /** @param array|false|null $row */
+ private function rowToConfig($row): ?array
+ {
+ if (!$row || empty($row['host'])) {
+ return null;
+ }
+ return [
+ 'host' => $row['host'],
+ 'port' => (int) $row['port'],
+ 'secure' => (int) $row['secure'] === 1,
+ 'username' => (string) ($row['username'] ?? ''),
+ 'password' => (string) (\BitsHost\UpmvcSaas\Security\SecretBox::unseal($row['password_enc'] ?? null) ?? ''),
+ 'from_email' => $row['from_email'],
+ 'from_name' => $row['from_name'] ?? '',
+ 'reply_to' => $row['reply_to'] ?? null,
+ 'encryption' => ((int) $row['secure'] === 1) ? 'ssl' : 'tls',
+ ];
+ }
+
+ /** @param array $row */
+ private function toPublic(array $row): array
+ {
+ return [
+ 'host' => $row['host'],
+ 'port' => (int) $row['port'],
+ 'secure' => (int) $row['secure'] === 1,
+ 'username' => $row['username'],
+ 'has_password' => !empty($row['password_enc']),
+ 'from_email' => $row['from_email'],
+ 'from_name' => $row['from_name'],
+ 'reply_to' => $row['reply_to'],
+ 'enabled' => (int) $row['enabled'] === 1,
+ 'last_test_at' => $row['last_test_at'],
+ 'last_test_ok' => $row['last_test_ok'] === null ? null : ((int) $row['last_test_ok'] === 1),
+ 'last_error' => $row['last_error'],
+ 'updated_at' => $row['updated_at'] ?? null,
+ ];
+ }
+
+ /** @param array $cfg */
+ private function buildMailer(array $cfg): PHPMailer
+ {
+ $mail = new PHPMailer(true);
+ $mail->CharSet = 'UTF-8';
+ $mail->isSMTP();
+ $mail->Host = $cfg['host'];
+ $mail->Port = (int) $cfg['port'];
+ $mail->SMTPAuth = ($cfg['username'] ?? '') !== '';
+ if ($mail->SMTPAuth) {
+ $mail->Username = $cfg['username'];
+ $mail->Password = $cfg['password'] ?? '';
+ }
+ $enc = $cfg['encryption'] ?? (!empty($cfg['secure']) ? 'ssl' : 'tls');
+ if ($enc === 'ssl' || !empty($cfg['secure'])) {
+ $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS;
+ } else {
+ $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
+ $mail->SMTPAutoTLS = true;
+ }
+ $mail->Timeout = 12;
+ $mail->isHTML(true);
+ return $mail;
+ }
+
+ private function markTest(int $id, bool $ok, ?string $error): void
+ {
+ $stmt = $this->conn->prepare(
+ 'UPDATE smtp_settings SET last_test_at=NOW(), last_test_ok=:ok, last_error=:err WHERE id=:id'
+ );
+ $stmt->execute([':ok' => $ok ? 1 : 0, ':err' => $error, ':id' => $id]);
+ }
+
+ /** @return array{status:string,transport?:string,error?:string} */
+ private function finish(
+ ?int $tenantId,
+ string $to,
+ string $subject,
+ string $template,
+ ?string $type,
+ string $transport,
+ string $status,
+ ?string $error
+ ): array {
+ $this->writeLog($tenantId, $to, $subject, $template, $type, $transport, $status, $error);
+ $out = ['status' => $status, 'transport' => $transport];
+ if ($error) {
+ $out['error'] = $error;
+ }
+ return $out;
+ }
+
+ private function writeLog(
+ ?int $tenantId,
+ string $to,
+ string $subject,
+ string $template,
+ ?string $type,
+ string $transport,
+ string $status,
+ ?string $error
+ ): void {
+ $stmt = $this->conn->prepare(
+ "INSERT INTO email_log (tenant_id, to_email, subject, template, transport, status, error, type)
+ VALUES (:tid, :to, :subj, :tpl, :tr, :st, :err, :type)"
+ );
+ $stmt->execute([
+ ':tid' => $tenantId,
+ ':to' => mb_substr($to, 0, 254),
+ ':subj' => mb_substr($subject, 0, 300),
+ ':tpl' => mb_substr($template, 0, 80),
+ ':tr' => $transport,
+ ':st' => $status,
+ ':err' => $error,
+ ':type' => $type,
+ ]);
+ }
+}
diff --git a/src/Saas/Notify/Notify.php b/src/Saas/Notify/Notify.php
new file mode 100644
index 0000000..c047f57
--- /dev/null
+++ b/src/Saas/Notify/Notify.php
@@ -0,0 +1,96 @@
+ $users
+ * @param callable $build fn(array $user): array{subject:string,html:string,text?:string}
+ * @return array{sent:int,skipped:int,reason?:string,error?:string}
+ */
+ public static function fire(
+ ?int $tenantId,
+ string $type,
+ array $users,
+ callable $build,
+ ?int $excludeUserId = null
+ ): array {
+ try {
+ if (!NotifyRegistry::isValid($type)) {
+ return ['sent' => 0, 'skipped' => 0, 'reason' => 'unknown_type'];
+ }
+ if (NotifyGate::isPaused($type)) {
+ return ['sent' => 0, 'skipped' => count($users), 'reason' => 'paused'];
+ }
+
+ $mail = new MailGateway();
+ $sent = 0;
+ $skipped = 0;
+ foreach ($users as $user) {
+ $uid = isset($user['id']) ? (int) $user['id'] : 0;
+ if ($excludeUserId && $uid === $excludeUserId) {
+ $skipped++;
+ continue;
+ }
+ if ($uid > 0 && self::isMuted($uid, $type)) {
+ $skipped++;
+ continue;
+ }
+ $email = trim((string) ($user['email'] ?? ''));
+ if ($email === '' || !filter_var($email, FILTER_VALIDATE_EMAIL)) {
+ $skipped++;
+ continue;
+ }
+ $payload = $build($user);
+ $subject = (string) ($payload['subject'] ?? '');
+ $html = (string) ($payload['html'] ?? '');
+ if ($subject === '' || $html === '') {
+ $skipped++;
+ continue;
+ }
+ $result = $mail->send(
+ $email,
+ $subject,
+ $html,
+ 'notify',
+ $tenantId,
+ $type,
+ isset($payload['text']) ? (string) $payload['text'] : null
+ );
+ if (($result['status'] ?? '') === 'sent') {
+ $sent++;
+ } else {
+ $skipped++;
+ }
+ }
+ return ['sent' => $sent, 'skipped' => $skipped];
+ } catch (\Throwable $e) {
+ error_log('[saas-notify] ' . $type . ' ' . $e->getMessage());
+ return ['sent' => 0, 'skipped' => 0, 'error' => $e->getMessage()];
+ }
+ }
+
+ public static function isMuted(int $userId, string $type): bool
+ {
+ try {
+ $pdo = (new Database())->getConnection();
+ $stmt = $pdo->prepare(
+ 'SELECT 1 FROM notification_mutes WHERE user_id = :u AND mute_key = :k LIMIT 1'
+ );
+ $stmt->execute([':u' => $userId, ':k' => $type]);
+ return (bool) $stmt->fetchColumn();
+ } catch (\Throwable) {
+ return false;
+ }
+ }
+}
diff --git a/src/Saas/Notify/NotifyGate.php b/src/Saas/Notify/NotifyGate.php
new file mode 100644
index 0000000..11aa44a
--- /dev/null
+++ b/src/Saas/Notify/NotifyGate.php
@@ -0,0 +1,46 @@
+getConnection();
+ $stmt = $pdo->prepare(
+ 'SELECT paused FROM notification_global WHERE type = :t LIMIT 1'
+ );
+ $stmt->execute([':t' => $type]);
+ $row = $stmt->fetch(\PDO::FETCH_ASSOC);
+ return $row && (int) $row['paused'] === 1;
+ } catch (\Throwable) {
+ return false;
+ }
+ }
+
+ public static function setPaused(string $type, bool $paused, ?string $reason = null, ?int $by = null): void
+ {
+ if (!NotifyRegistry::isValid($type)) {
+ throw new \InvalidArgumentException('Unknown notification type');
+ }
+ $pdo = (new Database())->getConnection();
+ $stmt = $pdo->prepare(
+ "INSERT INTO notification_global (type, paused, reason, updated_by)
+ VALUES (:t, :p, :r, :by)
+ ON DUPLICATE KEY UPDATE paused = VALUES(paused), reason = VALUES(reason), updated_by = VALUES(updated_by)"
+ );
+ $stmt->execute([
+ ':t' => $type,
+ ':p' => $paused ? 1 : 0,
+ ':r' => $reason,
+ ':by' => $by,
+ ]);
+ }
+}
diff --git a/src/Saas/Notify/NotifyRegistry.php b/src/Saas/Notify/NotifyRegistry.php
new file mode 100644
index 0000000..55b49b7
--- /dev/null
+++ b/src/Saas/Notify/NotifyRegistry.php
@@ -0,0 +1,77 @@
+ 'invoice_paid', 'zone' => 'tenant', 'kind' => 'instant',
+ * 'audience' => 'roles', 'roles' => ['tenant_owner'], 'enabled' => true,
+ * 'label' => '…', 'help' => '…', // prefer i18n keys in UI
+ * ]
+ */
+final class NotifyRegistry
+{
+ /** @var array> */
+ private static array $types = [];
+
+ /** @param array $type */
+ public static function register(array $type): void
+ {
+ $key = (string) ($type['key'] ?? '');
+ if ($key === '' || !preg_match('/^[a-z][a-z0-9_]{1,62}$/', $key)) {
+ throw new \InvalidArgumentException('Invalid notification type key');
+ }
+ $type['zone'] = $type['zone'] ?? 'tenant';
+ $type['kind'] = $type['kind'] ?? 'instant';
+ self::$types[$key] = $type;
+ }
+
+ /** @param list> $types */
+ public static function registerMany(array $types): void
+ {
+ foreach ($types as $t) {
+ self::register($t);
+ }
+ }
+
+ public static function clear(): void
+ {
+ self::$types = [];
+ }
+
+ public static function isValid(string $type): bool
+ {
+ return isset(self::$types[$type]);
+ }
+
+ /** @return array|null */
+ public static function get(string $type): ?array
+ {
+ return self::$types[$type] ?? null;
+ }
+
+ /** @return list> */
+ public static function all(): array
+ {
+ return array_values(self::$types);
+ }
+
+ /** @return list> */
+ public static function forZone(string $zone): array
+ {
+ return array_values(array_filter(
+ self::$types,
+ static fn(array $t): bool => ($t['zone'] ?? '') === $zone
+ ));
+ }
+
+ /** @return list */
+ public static function keys(): array
+ {
+ return array_keys(self::$types);
+ }
+}
diff --git a/src/Saas/Ops/Attention.php b/src/Saas/Ops/Attention.php
new file mode 100644
index 0000000..e2d180f
--- /dev/null
+++ b/src/Saas/Ops/Attention.php
@@ -0,0 +1,81 @@
+
+ */
+ public static function collect(): array
+ {
+ $items = [];
+
+ $mail = new MailGateway();
+ if (!$mail->isNetworkConfigured()) {
+ $items[] = [
+ 'tone' => 'bad',
+ 'key' => 'smtp',
+ 'tab' => 'email',
+ 'text' => 'Platform network SMTP is not configured — outbound mail will be skipped.',
+ ];
+ }
+
+ try {
+ $pdo = (new \App\Etc\Database())->getConnection();
+ $failed = (int) $pdo->query(
+ "SELECT COUNT(*) FROM email_log
+ WHERE status = 'failed' AND created_at > DATE_SUB(NOW(), INTERVAL 24 HOUR)"
+ )->fetchColumn();
+ if ($failed > 0) {
+ $items[] = [
+ 'tone' => 'bad',
+ 'key' => 'email_failed',
+ 'tab' => 'email',
+ 'meta' => ['count' => $failed],
+ 'text' => "{$failed} email(s) failed in the last 24 hours.",
+ ];
+ }
+ } catch (\Throwable) {
+ }
+
+ $sched = SchedulerHeartbeat::health();
+ if ($sched['stale']) {
+ $items[] = [
+ 'tone' => 'bad',
+ 'key' => 'scheduler',
+ 'tab' => 'ops',
+ 'meta' => ['last_run' => $sched['last_run']],
+ 'text' => $sched['last_run']
+ ? 'Scheduler heartbeat is stale — check cron.'
+ : 'No scheduler heartbeat yet — digests will not run until cron is configured.',
+ ];
+ }
+
+ $flags = PlatformSettings::flags();
+ if ($flags['maintenance_mode']) {
+ $items[] = [
+ 'tone' => 'warn',
+ 'key' => 'maintenance',
+ 'tab' => 'ops',
+ 'text' => 'Maintenance mode is ON.',
+ ];
+ }
+ if (!$flags['signup_enabled']) {
+ $items[] = [
+ 'tone' => 'signal',
+ 'key' => 'signup_off',
+ 'tab' => 'ops',
+ 'text' => 'Public signup is disabled.',
+ ];
+ }
+
+ return $items;
+ }
+}
diff --git a/src/Saas/Ops/PlatformSettings.php b/src/Saas/Ops/PlatformSettings.php
new file mode 100644
index 0000000..570c53c
--- /dev/null
+++ b/src/Saas/Ops/PlatformSettings.php
@@ -0,0 +1,55 @@
+getConnection();
+ $stmt = $pdo->prepare(
+ 'SELECT setting_value FROM platform_settings WHERE setting_key = :k LIMIT 1'
+ );
+ $stmt->execute([':k' => $key]);
+ $v = $stmt->fetchColumn();
+ return $v === false ? $default : (string) $v;
+ } catch (\Throwable) {
+ return $default;
+ }
+ }
+
+ public static function set(string $key, string $value): void
+ {
+ $pdo = (new Database())->getConnection();
+ $stmt = $pdo->prepare(
+ "INSERT INTO platform_settings (setting_key, setting_value)
+ VALUES (:k, :v)
+ ON DUPLICATE KEY UPDATE setting_value = VALUES(setting_value)"
+ );
+ $stmt->execute([':k' => $key, ':v' => $value]);
+ }
+
+ /** @return array{signup_enabled:bool,maintenance_mode:bool} */
+ public static function flags(): array
+ {
+ return [
+ 'signup_enabled' => self::get('signup_enabled', '1') !== '0',
+ 'maintenance_mode' => self::get('maintenance_mode', '0') === '1',
+ ];
+ }
+
+ /** @param array{signup_enabled?:bool,maintenance_mode?:bool} $flags */
+ public static function saveFlags(array $flags): array
+ {
+ if (array_key_exists('signup_enabled', $flags)) {
+ self::set('signup_enabled', !empty($flags['signup_enabled']) ? '1' : '0');
+ }
+ if (array_key_exists('maintenance_mode', $flags)) {
+ self::set('maintenance_mode', !empty($flags['maintenance_mode']) ? '1' : '0');
+ }
+ return self::flags();
+ }
+}
diff --git a/src/Saas/Ops/SchedulerHeartbeat.php b/src/Saas/Ops/SchedulerHeartbeat.php
new file mode 100644
index 0000000..b24ffcc
--- /dev/null
+++ b/src/Saas/Ops/SchedulerHeartbeat.php
@@ -0,0 +1,35 @@
+ null, 'stale' => true, 'age_seconds' => null];
+ }
+ $ts = strtotime($raw);
+ if ($ts === false) {
+ return ['last_run' => $raw, 'stale' => true, 'age_seconds' => null];
+ }
+ $age = time() - $ts;
+ return [
+ 'last_run' => $raw,
+ 'stale' => $age > $staleAfterSeconds,
+ 'age_seconds' => $age,
+ ];
+ }
+}
diff --git a/src/Saas/Security/SecretBox.php b/src/Saas/Security/SecretBox.php
new file mode 100644
index 0000000..252ab37
--- /dev/null
+++ b/src/Saas/Security/SecretBox.php
@@ -0,0 +1,80 @@
+
+ */
+ private static function keyCandidates(): array
+ {
+ $src = (string) (
+ getenv('APP_KEY')
+ ?: ($_ENV['APP_KEY'] ?? '')
+ ?: getenv('JWT_SECRET')
+ ?: ($_ENV['JWT_SECRET'] ?? '')
+ ?: Environment::get('APP_KEY', '')
+ ?: Environment::get('JWT_SECRET', '')
+ ?: 'upmvc-saas-dev-insecure-key-change-me'
+ );
+ $keys = [
+ hash('sha256', $src . '|saas-secret-v1', true),
+ hash('sha256', $src . '|smtp-password-v1', true), // myCMMS-PHP legacy
+ ];
+ // Also try insecure defaults if APP_KEY differed historically
+ $keys[] = hash('sha256', 'upmvc-saas-dev-insecure-key-change-me|saas-secret-v1', true);
+ $keys[] = hash('sha256', 'mycmms-dev-insecure-key-change-me|smtp-password-v1', true);
+ return array_values(array_unique($keys));
+ }
+}
diff --git a/src/Saas/Security/Totp.php b/src/Saas/Security/Totp.php
new file mode 100644
index 0000000..6265ab6
--- /dev/null
+++ b/src/Saas/Security/Totp.php
@@ -0,0 +1,156 @@
+ $secret,
+ 'issuer' => $issuer,
+ 'algorithm' => 'SHA1',
+ 'digits' => 6,
+ 'period' => self::PERIOD,
+ ], '', '&', PHP_QUERY_RFC3986);
+ return "otpauth://totp/{$label}?{$q}";
+ }
+
+ public static function stepAt(?int $ms = null): int
+ {
+ $ms ??= (int) floor(microtime(true) * 1000);
+ return (int) floor($ms / 1000 / self::PERIOD);
+ }
+
+ public static function codeAt(string $secret, ?int $ms = null): string
+ {
+ return self::hotp($secret, self::stepAt($ms));
+ }
+
+ /**
+ * @return int|null matched time-step, or null if invalid
+ */
+ public static function verify(string $secret, string $code, ?int $lastStep = null): ?int
+ {
+ $c = preg_replace('/\s+/', '', $code) ?? '';
+ if (!preg_match('/^\d{6}$/', $c)) {
+ return null;
+ }
+ $now = self::stepAt();
+ foreach ([$now - 1, $now, $now + 1] as $s) {
+ if ($lastStep !== null && $s <= $lastStep) {
+ continue;
+ }
+ $expect = self::hotp($secret, $s);
+ if (hash_equals($expect, $c)) {
+ return $s;
+ }
+ }
+ return null;
+ }
+
+ public static function seal(string $secret): string
+ {
+ $key = self::sealKey();
+ $iv = random_bytes(16);
+ $cipher = openssl_encrypt($secret, 'AES-256-CBC', $key, OPENSSL_RAW_DATA, $iv);
+ if ($cipher === false) {
+ throw new \RuntimeException('Failed to seal TOTP secret');
+ }
+ return self::SEAL_PREFIX . base64_encode($iv . $cipher);
+ }
+
+ public static function unseal(string $sealed): ?string
+ {
+ if (!str_starts_with($sealed, self::SEAL_PREFIX)) {
+ return null;
+ }
+ $raw = base64_decode(substr($sealed, strlen(self::SEAL_PREFIX)), true);
+ if ($raw === false || strlen($raw) < 17) {
+ return null;
+ }
+ $iv = substr($raw, 0, 16);
+ $cipher = substr($raw, 16);
+ foreach (self::sealKeyCandidates() as $key) {
+ $plain = openssl_decrypt($cipher, 'AES-256-CBC', $key, OPENSSL_RAW_DATA, $iv);
+ if ($plain !== false && $plain !== '') {
+ return $plain;
+ }
+ }
+ return null;
+ }
+
+ private static function sealKey(): string
+ {
+ return self::sealKeyCandidates()[0];
+ }
+
+ /** @return list */
+ private static function sealKeyCandidates(): array
+ {
+ // Prefer process env so unit tests / CLI do not force-load .env
+ $secret = (string) (getenv('JWT_SECRET') ?: ($_ENV['JWT_SECRET'] ?? '') ?: Environment::get('JWT_SECRET', ''));
+ if ($secret === '') {
+ throw new \RuntimeException('JWT_SECRET is required to seal TOTP secrets');
+ }
+ return [
+ hash('sha256', 'upmvc-saas-totp|' . $secret, true),
+ hash('sha256', 'mycmms-totp|' . $secret, true), // myCMMS-PHP legacy
+ ];
+ }
+
+ private static function hotp(string $secret, int $counter): string
+ {
+ $key = self::decodeBase32($secret);
+ // 8-byte big-endian counter (high 32 bits always 0 for practical steps)
+ $msg = pack('NN', ($counter >> 32) & 0xffffffff, $counter & 0xffffffff);
+ $h = hash_hmac('sha1', $msg, $key, true);
+ $o = ord($h[strlen($h) - 1]) & 0x0f;
+ $bin = unpack('N', substr($h, $o, 4));
+ $code = ($bin[1] & 0x7fffffff) % 1000000;
+ return str_pad((string) $code, 6, '0', STR_PAD_LEFT);
+ }
+
+ private static function decodeBase32(string $secret): string
+ {
+ $secret = strtoupper(rtrim($secret, '='));
+ $bits = '';
+ for ($i = 0, $n = strlen($secret); $i < $n; $i++) {
+ $idx = strpos(self::B32, $secret[$i]);
+ if ($idx === false) {
+ continue;
+ }
+ $bits .= str_pad(decbin($idx), 5, '0', STR_PAD_LEFT);
+ }
+ $bytes = '';
+ for ($i = 0; $i + 8 <= strlen($bits); $i += 8) {
+ $bytes .= chr(bindec(substr($bits, $i, 8)));
+ }
+ return $bytes;
+ }
+}
diff --git a/tests/Unit/HarvestKernelTest.php b/tests/Unit/HarvestKernelTest.php
new file mode 100644
index 0000000..206106d
--- /dev/null
+++ b/tests/Unit/HarvestKernelTest.php
@@ -0,0 +1,150 @@
+assertMatchesRegularExpression('/^[A-Z2-7]+$/', $secret);
+ $code = Totp::codeAt($secret);
+ $this->assertMatchesRegularExpression('/^\d{6}$/', $code);
+ $step = Totp::verify($secret, $code);
+ $this->assertNotNull($step);
+ $this->assertNull(Totp::verify($secret, '000000', $step));
+ }
+
+ public function testTotpSealRoundTrip(): void
+ {
+ // Seal needs JWT_SECRET — set a test value
+ $_ENV['JWT_SECRET'] = 'harvest-test-secret-not-for-prod';
+ putenv('JWT_SECRET=harvest-test-secret-not-for-prod');
+ $secret = Totp::newSecret();
+ $sealed = Totp::seal($secret);
+ $this->assertStringStartsWith('v1:', $sealed);
+ $this->assertSame($secret, Totp::unseal($sealed));
+ }
+
+ /** Pack unseal must still read myCMMS-era SMTP seals (`|smtp-password-v1`). */
+ public function testSecretBoxUnsealsLegacySmtpPepper(): void
+ {
+ $src = 'harvest-dual-unseal-app-key';
+ $_ENV['APP_KEY'] = $src;
+ putenv('APP_KEY=' . $src);
+ unset($_ENV['JWT_SECRET']);
+ putenv('JWT_SECRET');
+
+ $plain = 'smtp-password-legacy-proof';
+ $key = hash('sha256', $src . '|smtp-password-v1', true);
+ $iv = random_bytes(12);
+ $tag = '';
+ $ct = openssl_encrypt($plain, 'aes-256-gcm', $key, OPENSSL_RAW_DATA, $iv, $tag);
+ $this->assertNotFalse($ct);
+ $blob = 'v1:' . base64_encode($iv . $tag . $ct);
+
+ $this->assertSame($plain, SecretBox::unseal($blob));
+ // New writes use pack pepper only
+ $this->assertSame($plain, SecretBox::unseal(SecretBox::seal($plain)));
+ }
+
+ /** Pack unseal must still read myCMMS-era TOTP seals (`mycmms-totp|`). */
+ public function testTotpUnsealsLegacyMycmmsPepper(): void
+ {
+ $jwt = 'harvest-dual-unseal-jwt-secret';
+ $_ENV['JWT_SECRET'] = $jwt;
+ putenv('JWT_SECRET=' . $jwt);
+
+ $secret = Totp::newSecret();
+ $key = hash('sha256', 'mycmms-totp|' . $jwt, true);
+ $iv = random_bytes(16);
+ $cipher = openssl_encrypt($secret, 'AES-256-CBC', $key, OPENSSL_RAW_DATA, $iv);
+ $this->assertNotFalse($cipher);
+ $sealed = 'v1:' . base64_encode($iv . $cipher);
+
+ $this->assertSame($secret, Totp::unseal($sealed));
+ }
+
+ public function testNotifyRegistryRegisterAndZone(): void
+ {
+ NotifyRegistry::register([
+ 'key' => 'invoice_paid',
+ 'zone' => 'tenant',
+ 'kind' => 'instant',
+ ]);
+ NotifyRegistry::register([
+ 'key' => 'mail_failures',
+ 'zone' => 'platform',
+ 'kind' => 'digest',
+ ]);
+ $this->assertTrue(NotifyRegistry::isValid('invoice_paid'));
+ $this->assertCount(1, NotifyRegistry::forZone('tenant'));
+ $this->assertCount(1, NotifyRegistry::forZone('platform'));
+ $this->assertSame(['invoice_paid', 'mail_failures'], NotifyRegistry::keys());
+ }
+
+ public function testNotifyRegistryRejectsBadKey(): void
+ {
+ $this->expectException(\InvalidArgumentException::class);
+ NotifyRegistry::register(['key' => 'Bad-Key!']);
+ }
+
+ public function testAuditActorsFromUser(): void
+ {
+ $a = AuditLog::actorsFromUser([
+ 'sub' => 10,
+ 'impersonated' => true,
+ 'impersonator_id' => 2,
+ ]);
+ $this->assertSame(10, $a['userId']);
+ $this->assertSame(2, $a['impersonatorId']);
+ }
+
+ public function testCatalogApplyOverlays(): void
+ {
+ $base = [
+ 'common' => ['save' => 'Save', 'name' => 'Name'],
+ 'platform' => ['ops_tab' => 'Ops'],
+ ];
+ $out = Catalog::applyOverlays($base, [
+ 'common.save' => 'Salvează',
+ 'platform.ops_tab' => 'Operațiuni',
+ 'platform.new_key' => 'New',
+ ]);
+ $this->assertSame('Salvează', $out['common']['save']);
+ $this->assertSame('Name', $out['common']['name']);
+ $this->assertSame('Operațiuni', $out['platform']['ops_tab']);
+ $this->assertSame('New', $out['platform']['new_key']);
+ }
+
+ public function testCatalogLoadFromPackLang(): void
+ {
+ $dir = dirname(__DIR__, 2) . '/public/lang';
+ $loaded = Catalog::load('en', $dir, ['en', 'ro'], false);
+ $this->assertSame('en', $loaded['locale']);
+ $this->assertSame('file', $loaded['source']);
+ $this->assertIsArray($loaded['catalog']['common'] ?? null);
+ }
+
+ public function testMigration002ExistsAndMentionsOpsTables(): void
+ {
+ $sql = (string) file_get_contents(dirname(__DIR__, 2) . '/database/migrations/002_saas_ops_layer.sql');
+ foreach (['smtp_settings', 'email_log', 'audit_log', 'notification_global', 'i18n_overlays', 'totp_enabled'] as $needle) {
+ $this->assertStringContainsString($needle, $sql);
+ }
+ }
+}
diff --git a/tests/Unit/PackStructureTest.php b/tests/Unit/PackStructureTest.php
index faaf3c5..1f658c7 100644
--- a/tests/Unit/PackStructureTest.php
+++ b/tests/Unit/PackStructureTest.php
@@ -131,6 +131,15 @@ public function testMigrationsCreateTheSaasTables(): void
"Migrations must create the $table table"
);
}
+
+ // Harvest ops layer (002)
+ foreach (['platform_settings', 'smtp_settings', 'email_log', 'audit_log', 'i18n_overlays'] as $table) {
+ $this->assertMatchesRegularExpression(
+ '/CREATE TABLE (IF NOT EXISTS )?`?' . $table . '`?/i',
+ $sql,
+ "Ops migrations must create the $table table"
+ );
+ }
}
public function testSchemaAndSeedShipForNonMigrationInstalls(): void