diff --git a/config/env.php b/config/env.php index a768fdf..fbf4512 100644 --- a/config/env.php +++ b/config/env.php @@ -44,31 +44,16 @@ function env(string $key, $default = null) { return $v === false ? $default : $v; } -// IP do visitante. Em produção o Apache só vê o Nginx Proxy Manager -// (REMOTE_ADDR = 172.18.0.2 para toda a gente), e o throttle do login contava -// tudo contra esse IP — cinco falhas de qualquer pessoa bloqueavam todos. -// -// Só se confia no proxy quando TRUSTED_PROXY=true E o pedido vem mesmo de uma -// rede privada. Nesse caso: -// - X-Real-IP primeiro: o NPM escreve-o com o $remote_addr que viu, por cima -// de qualquer valor que o cliente tenha mandado; -// - senão o ÚLTIMO valor do X-Forwarded-For, que é o que o proxy acrescentou. -// O primeiro é escrito pelo cliente (o NPM acrescenta, não substitui) e -// serve para forjar identidades — o platform_client_ip() partilhado ainda -// o usa. +// IP do visitante — a regra vive no platform-tools (platform_client_ip(): +// X-Real-IP, senão o último X-Forwarded-For, e só vindo do proxy com +// TRUSTED_PROXY). Em produção o Apache só vê o Nginx Proxy Manager +// (REMOTE_ADDR = 172.18.0.2 para toda a gente); o throttle do login contava +// tudo contra esse IP. A correção nasceu aqui e foi promovida ao partilhado +// (platform-tools 12f26fd), para throttle, audit e IP ban usarem a mesma. +require_once __DIR__ . '/../shared/platform-tools/functions_client_ip.php'; + function client_ip(): string { - $remote = (string) ($_SERVER['REMOTE_ADDR'] ?? ''); - $trusted = filter_var(env('TRUSTED_PROXY', 'false'), FILTER_VALIDATE_BOOLEAN); - $fromProxy = $remote !== '' && filter_var($remote, FILTER_VALIDATE_IP) - && !filter_var($remote, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE); - if ($trusted && $fromProxy) { - $real = trim((string) ($_SERVER['HTTP_X_REAL_IP'] ?? '')); - if (filter_var($real, FILTER_VALIDATE_IP)) return $real; - $xff = array_map('trim', explode(',', (string) ($_SERVER['HTTP_X_FORWARDED_FOR'] ?? ''))); - $last = end($xff); - if ($last !== false && filter_var($last, FILTER_VALIDATE_IP)) return $last; - } - return $remote !== '' ? $remote : '0.0.0.0'; + return platform_client_ip() ?? '0.0.0.0'; } // True when the current request is HTTPS — including when TLS terminates at a diff --git a/config/functions.php b/config/functions.php index c6b7843..4d4742b 100644 --- a/config/functions.php +++ b/config/functions.php @@ -13,6 +13,7 @@ require_once __DIR__ . '/config.php'; // APP_ENV + hub notify URL + require_once __DIR__ . '/functions_settings.php'; // setting() + system_settings cache require_once __DIR__ . '/functions_secrets.php'; // setting_or_env()/setting_secret() + AES-GCM at rest require_once __DIR__ . '/functions_db.php'; // generic DB helpers +require_once __DIR__ . '/functions_audit.php'; // registo de auditoria (platform-tools) + audit() require_once __DIR__ . '/functions_trash.php'; // lixeira: soft delete + eliminação só após 30 dias require_once __DIR__ . '/functions_user.php'; // auth_login/register, password reset, user creators require_once __DIR__ . '/auth.php'; // require_login/admin/staff/sysadmin(), role helpers diff --git a/config/functions_audit.php b/config/functions_audit.php new file mode 100644 index 0000000..b7d36b8 --- /dev/null +++ b/config/functions_audit.php @@ -0,0 +1,25 @@ +. +// (team.update, trash.purge, auth.login_failed, export.membership_leads…). + +require_once __DIR__ . '/../shared/platform-tools/functions_audit.php'; + +function audit(string $action, array $d = []): void { + platform_audit($GLOBALS['pdo'] ?? null, $action, $d); +} + +// Email mascarado para registos de falhas: permite ver padrões (o mesmo +// endereço atacado muitas vezes) sem guardar o endereço de quem se enganou. +function audit_mask_email(string $email): string { + $email = strtolower(trim($email)); + if (!str_contains($email, '@')) return $email === '' ? '' : mb_substr($email, 0, 1) . '…'; + [$u, $d] = explode('@', $email, 2); + return mb_substr($u, 0, 1) . '…@' . $d; +} diff --git a/config/functions_settings.php b/config/functions_settings.php index 6763c5d..fac775c 100644 --- a/config/functions_settings.php +++ b/config/functions_settings.php @@ -80,6 +80,16 @@ function setting(string $key, $default = null) { } function db_update_setting(PDO $pdo, string $key, string $value, ?int $userId = null): void { + // Valor anterior para o audit (os segredos são ocultados pelo módulo, pelo + // nome da chave: *password*, *token*, *key*, *secret*). + $old = null; + try { + $o = $pdo->prepare("SELECT setting_value FROM system_settings WHERE setting_key = ?"); + $o->execute([$key]); + $old = $o->fetchColumn(); + $old = $old === false ? null : (string) $old; + } catch (Throwable $e) {} + $s = $pdo->prepare( "INSERT INTO system_settings (setting_key, setting_value, updated_by) VALUES (?, ?, ?) @@ -88,4 +98,10 @@ function db_update_setting(PDO $pdo, string $key, string $value, ?int $userId = ); $s->execute([$key, $value, $userId]); settings_cache_clear(); + if ($old !== $value && function_exists('platform_audit')) { + platform_audit($pdo, 'settings.update', [ + 'target_type' => 'setting', 'target_id' => $key, 'target_label' => $key, + 'changes' => [$key => ['antes' => $old, 'depois' => $value]], + ]); + } } diff --git a/config/functions_trash.php b/config/functions_trash.php index d2d961a..17fbb1b 100644 --- a/config/functions_trash.php +++ b/config/functions_trash.php @@ -88,7 +88,10 @@ function trash_delete(PDO $pdo, string $type, int $id): bool { $stmt = $pdo->prepare("UPDATE `{$t['table']}` SET deleted_at = NOW(), deleted_by = ? WHERE `{$t['pk']}` = ? AND deleted_at IS NULL"); $stmt->execute([_trash_user_id(), $id]); $ok = $stmt->rowCount() > 0; - if ($ok) _trash_after($pdo, $type, $id, 'delete'); + if ($ok) { + _trash_after($pdo, $type, $id, 'delete'); + _trash_audit($pdo, 'trash.delete', $type, $id, 'Enviado para a lixeira'); + } return $ok; } @@ -97,7 +100,10 @@ function trash_restore(PDO $pdo, string $type, int $id): bool { $stmt = $pdo->prepare("UPDATE `{$t['table']}` SET deleted_at = NULL, deleted_by = NULL WHERE `{$t['pk']}` = ? AND deleted_at IS NOT NULL"); $stmt->execute([$id]); $ok = $stmt->rowCount() > 0; - if ($ok) _trash_after($pdo, $type, $id, 'restore'); + if ($ok) { + _trash_after($pdo, $type, $id, 'restore'); + _trash_audit($pdo, 'trash.restore', $type, $id, 'Restaurado da lixeira'); + } return $ok; } @@ -128,6 +134,7 @@ function trash_purge(PDO $pdo, string $type, int $id): bool { $stmt->execute([$id]); $ok = $stmt->rowCount() > 0; $ok ? $pdo->commit() : $pdo->rollBack(); + if ($ok) _trash_audit($pdo, 'trash.purge', $type, $id, 'Eliminado de vez', (string) $row['title']); return $ok; } catch (Throwable $e) { $pdo->rollBack(); @@ -181,6 +188,29 @@ function trash_count(PDO $pdo): int { return count(trash_list($pdo)); } +// Cada passo da lixeira fica no audit_log, com o nome do registo (na +// eliminação definitiva é a única coisa que resta dele). +function _trash_audit(PDO $pdo, string $action, string $type, int $id, string $summary, ?string $label = null): void { + if (!function_exists('platform_audit')) return; + if ($label === null) { + $row = trash_get($pdo, $type, $id); + if ($row === null) { + // Restaurado: já não está na lixeira; o nome vem do próprio registo. + $t = trash_type($type); + try { + $st = $pdo->prepare("SELECT {$t['title']} FROM `{$t['table']}` t WHERE t.`{$t['pk']}` = ?"); + $st->execute([$id]); + $label = (string) $st->fetchColumn(); + } catch (Throwable $e) { $label = ''; } + } else { + $label = (string) $row['title']; + } + } + platform_audit($pdo, $action, [ + 'target_type' => $type, 'target_id' => $id, 'target_label' => $label, 'summary' => $summary, + ]); +} + // ─── Efeitos em ficheiros ──────────────────────────────────────────────────── // O site público lista as fotos da galeria com glob() na pasta, não pela BD. // Por isso uma imagem apagada tem de sair da pasta: vai para .trash/ (o diff --git a/config/functions_user.php b/config/functions_user.php index 39cec4f..baa3e33 100644 --- a/config/functions_user.php +++ b/config/functions_user.php @@ -75,6 +75,11 @@ function auth_login(PDO $pdo, string $email, string $password): ?array { function auth_set_password(PDO $pdo, int $userId, string $password): void { $pdo->prepare("UPDATE users SET password_hash = ? WHERE id = ?") ->execute([password_hash($password, PASSWORD_DEFAULT), $userId]); + $self = (int) ($_SESSION['user_id'] ?? 0) === $userId; + audit($self ? 'auth.password_change' : 'user.password_set', [ + 'target_type' => 'user', 'target_id' => $userId, + 'summary' => $self ? 'O próprio alterou a palavra-passe' : 'Palavra-passe definida por outra pessoa ou por link de recuperação', + ]); // Best-effort: the password itself is already saved, so a missing // `password_resets` table (migration not applied yet) must not turn a @@ -116,6 +121,8 @@ function auth_register_client(PDO $pdo, array $data): array { $pdo->prepare( "UPDATE users SET name = ?, phone = COALESCE(?, phone), password_hash = ?, is_active = 1 WHERE id = ?" )->execute([$name, $phone, password_hash($data['password'], PASSWORD_DEFAULT), $row['id']]); + audit('user.register', ['target_type' => 'user', 'target_id' => (int) $row['id'], 'target_label' => $name, + 'summary' => 'Registo que reclamou uma conta de cliente sem palavra-passe', 'actor' => null]); return ['id' => (int) $row['id']]; } @@ -136,7 +143,10 @@ function auth_register_client(PDO $pdo, array $data): array { if ((int) ($e->errorInfo[1] ?? 0) === 1062) return ['error' => 'email_taken']; throw $e; } - return ['id' => (int) $pdo->lastInsertId()]; + $newId = (int) $pdo->lastInsertId(); + audit('user.register', ['target_type' => 'user', 'target_id' => $newId, 'target_label' => $name, + 'summary' => 'Novo cliente registado no site', 'actor' => null]); + return ['id' => $newId]; } // ─── Backoffice user creation ──────────────────────────────────────────────── @@ -153,7 +163,10 @@ function auth_create_sysadmin(PDO $pdo, string $name, string $email, string $pas strtolower(trim($email)), password_hash($password, PASSWORD_DEFAULT), ]); - return (int) $pdo->lastInsertId(); + $id = (int) $pdo->lastInsertId(); + audit('user.create', ['target_type' => 'user', 'target_id' => $id, 'target_label' => $name, + 'summary' => 'Sysadmin criado pelo setup inicial', 'actor' => null]); + return $id; } // Returns ['id' => int] on success, or ['error' => 'email_taken']. @@ -184,7 +197,10 @@ function _create_backoffice_user(PDO $pdo, string $role, string $name, string $e if ((int) ($e->errorInfo[1] ?? 0) === 1062) return ['error' => 'email_taken']; throw $e; } - return ['id' => (int) $pdo->lastInsertId()]; + $id = (int) $pdo->lastInsertId(); + audit('user.create', ['target_type' => 'user', 'target_id' => $id, 'target_label' => $name, + 'changes' => ['role' => ['antes' => null, 'depois' => $role]]]); + return ['id' => $id]; } // ─── Password reset ────────────────────────────────────────────────────────── @@ -257,6 +273,7 @@ function send_password_reset_email(string $name, string $email, string $resetUrl // same mechanism, different copy. function send_password_invite_email(PDO $pdo, array $user): bool { if (empty($user['email'])) return false; + audit('user.invite', ['target_type' => 'user', 'target_id' => (int) $user['id'], 'target_label' => (string) ($user['name'] ?? '')]); $token = auth_create_reset_token($pdo, (int) $user['id']); $url = base_url('views/auth/reset_password.php?token=' . $token); $name = (string) ($user['name'] ?? ''); diff --git a/includes/header.php b/includes/header.php index d0bf3f1..b507b82 100644 --- a/includes/header.php +++ b/includes/header.php @@ -178,6 +178,10 @@ $app_name = defined('APP_NAME') ? APP_NAME : 'FitMe 3070'; Mensagens +
  • + Auditoria +
  • Comunicações diff --git a/shared/platform-tools/PHILOSOPHY.md b/shared/platform-tools/PHILOSOPHY.md index 7b934a3..8f8e4ee 100644 --- a/shared/platform-tools/PHILOSOPHY.md +++ b/shared/platform-tools/PHILOSOPHY.md @@ -72,6 +72,22 @@ The corollary: **a site must not reimplement something this submodule provides.* If the shared version is wrong for one site, fix it here with a parameter, or say plainly in the site's own docs why it deviates. +**The site declares; the shared code does not guess.** Each site's +`config/db.php` makes one `platform_connect()` call that states its PDO, base +URL, environment, column map, roles, session and sysadmin guard. Before it, +every tool probed for variants — a global `$pdo` or `App\Database`, a +`base_url()` or a `getBaseUrl()` — and each new tool had to remember them all. +The same call runs `platform_conformance()`: the database is compared with what +the shared code expects, and a missing column that would switch a defence off +without an error fails loudly in development and turns the hub card yellow in +production (§7). + +**New tools reach every site without a file on the site.** The shared pages are +served by one front controller (`public/platform.php?tool=…`) and the shared +endpoints by another (`public/api/platform.php?endpoint=…`), both from closed +route tables here. A per-page stub on each of seven sites was seven chances to +forget one. + Submodules have one sharp edge worth stating: `git pull` in a site advances the submodule *pointer* but leaves its working tree on the old commit, silently and with no error. Every deploy script therefore runs `git submodule update @@ -127,7 +143,8 @@ Two things stay per-site, deliberately: - **The users table.** The columns genuinely differ — fotografia's users carry CalDAV credentials, silver's carry a guardian. The shared code adapts through - `auth_schema()` rather than demanding one shape, because renaming a column + the `schema` given to `platform_connect()` (`auth_schema()` underneath), + declaring only the columns that differ, rather than demanding one shape, because renaming a column with 147 references is a migration and adapting is a function call. The same map covers *what you sign in with*. Six sites match on `email`; @@ -189,7 +206,9 @@ sized to its workload rather than copied between sites. Application code sits outside the document root: the web root is `public/`, and `shared/`, `config/` and `src/` are not reachable over HTTP. Anything that -genuinely must be callable is a thin, explicit stub in `public/api/`. +genuinely must be callable goes through the two front controllers or a thin, +explicit stub in `public/api/` — and the front controllers only dispatch names +from a closed list; they never include a path taken from the request. ## 9. Migrations are append-only diff --git a/shared/platform-tools/README.md b/shared/platform-tools/README.md index cab78ca..2b77439 100644 --- a/shared/platform-tools/README.md +++ b/shared/platform-tools/README.md @@ -8,16 +8,22 @@ The goal: edit one file, every platform gets the update. | File | Purpose | |---|---| -| `index.php` | Sysadmin hub — single landing page with cards linking to the other tools. Extensible via `$sysadmin_tools` array in the stub. Loaded by each platform's `views/sysadmin/index.php` stub. | -| `platform_update.php` | Shared sysadmin page. A status header (version, branch, commit, state pills, the update button) over four tabs: **Atualizar** (restore point, git, submodules), **Automação** (auto-update webhook, pre-update backups), **Base de dados** (migrations, schema export), **Servidor** (OPcache, composer, error log, pre-requisites). Loaded by each platform's `views/sysadmin/platform_update.php` stub. | +| `index.php` | Sysadmin hub — single landing page with cards linking to the other tools. Lists every routed tool by default; a site adds its own cards with the `sysadmin_tools` connector option. Served by the router at `platform.php?tool=index`. | +| `platform_update.php` | Shared sysadmin page. A status header (version, branch, commit, state pills, the update button) over four tabs: **Atualizar** (restore point, git, submodules), **Automação** (auto-update webhook, pre-update backups), **Base de dados** (migrations, schema export), **Servidor** (OPcache, composer, error log, pre-requisites). Served by the router at `platform.php?tool=platform_update`. | | `functions_git.php` | `git_run(array $args, string $repo)` — runs git via `proc_open` array form, bypasses `safe.directory`, supports `GIT_HTTP_USERNAME` / `GIT_HTTP_TOKEN` for non-interactive HTTPS pulls. | | `functions_migrations.php` | `db_ensure_migrations_table()`, `migrations_list_files()`, `migrations_status()`, `migrations_apply_file()`, `migrations_mark_all_applied()`, `migrations_split_sql()` — quote/comment-aware SQL splitter, tracks state in `applied_migrations`. | | `functions_schema.php` | `schema_dump_path()`, `schema_build(PDO)`, `schema_dump_to_file(PDO)` — deterministic, structure-only dump of the host DB to `database/schema.sql` over PDO (`SHOW CREATE TABLE/VIEW`, no mysqldump). Strips timestamps, `AUTO_INCREMENT`, and view `DEFINER`s, sorts objects — so a git diff on `schema.sql` is a real changelog. Surfaced as the "Exportar esquema" button in the Migrations card. | -| `backups.php` | Shared sysadmin page — lists existing backups, buttons to trigger files-ZIP / DB-dump backups, download link per row. Loaded by each platform's `views/sysadmin/backups.php` stub. | +| `backups.php` | Shared sysadmin page — lists existing backups, buttons to trigger files-ZIP / DB-dump backups, download link per row. Served by the router at `platform.php?tool=backups`. | | `functions_backup.php` | `backup_dir()`, `backup_dir_protect()`, `backup_list()`, `backup_trigger($type)`, `backup_filename_is_safe()`, label/badge helpers. | | `functions_csrf.php` | Shared CSRF token over the host session — `platform_csrf_token()`, `platform_csrf_field()`, `platform_csrf_ok()`. Every POST form rendered by `platform_update.php` / `backups.php` carries the token; the handlers reject POSTs without it. | -| `functions_settings.php` | DB-backed settings and secret storage — `platform_settings_get/set/all()`, `platform_settings_is_secret()`, `platform_secret_encrypt/decrypt/mask()`, `platform_smtp_config(PDO)`. The single implementation of secret encryption for the whole estate; see [Settings and secrets](#settings-and-secrets). | +| `functions_settings.php` | DB-backed settings and secret storage — `platform_settings_get/set/all()`, `platform_settings_is_secret()`, `platform_secret_encrypt/decrypt/mask()`, `platform_smtp_config(PDO)`, `platform_derived_key($purpose, ?PDO)`. The single implementation of secret encryption for the whole estate; see [Settings and secrets](#settings-and-secrets). | +| `functions_captcha.php` | A written challenge for any public form — `platform_captcha_field()`, `platform_captcha_verify()`, plus the appeal flow (`platform_captcha_appeal_offer/claim()`) that gives a refused submission a second chance instead of a silent drop. Self-hosted, stateless (HMAC-signed token), no JavaScript, no images, no third-party service. See [Captcha](#captcha) and [The appeal](#the-appeal--a-second-chance-after-a-refusal). | +| `router.php` + `functions_routes.php` | Front controller for the shared sysadmin pages: one site stub `public/platform.php`, every page at `platform.php?tool=`, from a closed route table. See [Front controller](#front-controller). | +| `api/router.php` | The same for the shared endpoints: one site stub `public/api/platform.php`, every endpoint at `api/platform.php?endpoint=` (`platform_api_routes()`). Only dispatches — each endpoint keeps its own auth. | +| `functions_connector.php` | `platform_connect($pdo, [...])` — one bootstrap call that wires shared auth, "manter sessão", the IP guard and security events, and records what the other tools need (PDO, base URL, env, guard, layout). `platform_conformance()` checks the database against what the shared code expects; reported as `checks.conformance` in the health endpoint, fatal in dev. See [Connecting a site](#connecting-a-site). | | `functions_auth.php` | Shared authentication mechanics — `auth_session_start()` (HttpOnly/SameSite/Secure/strict mode), `auth_attempt()` (lookup + verify + transparent rehash + timing defence), `auth_login()`, `auth_schema()`, the ranked role registry, the guards, and a proxy-aware login throttle. See [Authentication](#authentication). | +| `functions_remember.php` | "Manter sessão iniciada" — `auth_remember_issue()`, `auth_remember_resume()`, `auth_remember_clear()`, `auth_remember_forget_user()`, `auth_remember_active()`. Login persistente em `auth_remember_tokens`, selector/validator com o validator guardado em SHA-256 e rodado a cada utilização — um cookie roubado vale até a próxima visita do dono, e a discrepância que isso gera revoga a conta inteira. Extensão de `functions_auth.php`, que carrega por si. `auth_remember_resume($pdo, $opts)` aceita dois ganchos opcionais — `'allow'` (regra extra do site sobre quem pode entrar) e `'login'` (quem abre a sessão, quando o site guarda mais do que o `auth_login()`) — e o nome do cookie pode vir de uma constante `AUTH_REMEMBER_COOKIE`, que ganha ao `.env`. | +| `functions_login_ui.php` | The two pieces every fleet login form has: `platform_password_field()` (the password with the eye to show it — inline SVG, no icon font, one script per page, hidden again on submit) and `platform_remember_field()` («Manter sessão iniciada», with the real number of days). Each site keeps its own login page (brand, layout); these two stop varying. | | `functions_ip_ban.php` | IP banning with memory — `platform_ip_guard()`, `platform_ip_record_offence()`, `platform_ip_ban/unban()`. The estate's three per-IP defences all forget within the hour; this is the piece that remembers. See [IP banning](#ip-banning). | | `ip_bans.php` | Shared sysadmin page for the above — active bans, addresses climbing toward one, and a manual ban form. | | `functions_mail_rate.php` | Send ceiling — `platform_mail_rate_blocked()`, `platform_mail_rate_record()`. Two windows (per minute, per hour), enforced inside `platform_mail_send()` when a PDO is passed. Fails **closed**. | @@ -25,24 +31,31 @@ The goal: edit one file, every platform gets the update. | `functions_tracking.php` | Visit-source analytics — `platform_track_visit()`, `platform_track_conversion()`, the report helpers. Records where a visitor came from (URL/campaign/referrer), on what device, and from which country. Came from fotografia; see [Visit tracking](#visit-tracking). | | `tracking.php` | Shared sysadmin page for the above — sources with conversion rate, conversions per form, and breakdowns by country, device, OS, browser and referrer. | | `bin/geo-build-index.php` | Compiles the all-countries IP→country index used by the analytics. Not versioned (~5 MB); regenerate from cron. | -| `functions_geo.php` | Country gating — `geo_mode()`, `geo_block_reason()`, `geo_form_block_reason()`, `geo_guard_site()`, `geo_ip_in_country()`. Refuses public form POSTs (or the whole site) from outside an allow-list of countries. See [Country gating](#country-gating). | -| `geo.php` | Shared sysadmin page — mode, country list, fail-closed toggle, data-file status, a "refresh lists" button and an IP probe. Loaded by each platform's `views/sysadmin/geo.php` stub. | +| `functions_geo.php` | Country gating — `geo_mode()`, `geo_block_reason()`, `geo_form_block_reason()`, `geo_guard_site()`, `geo_ip_in_country()`, plus the two escape valves: `geo_ip_allowlisted()` (addresses that always pass) and `geo_relay_serves()` (iCloud Private Relay, scored by the country each egress actually serves). Refuses public form POSTs (or the whole site) from outside an allow-list of countries. See [Country gating](#country-gating). | +| `geo.php` | Shared sysadmin page — a one-line statement of what the gate is doing right now, mode, countries as grouped checkboxes (with a JS filter and a "no lists" badge on any country whose data is missing), the Private Relay toggle, the always-pass address list, fail-closed, data-file status, a "refresh lists" button and an IP probe. Served by the router at `platform.php?tool=geo`. | | `bin/geo-update.sh` | Refreshes the per-country CIDR lists in `data/geo/` from ipdeny.com. Validates before overwriting, so a bad download keeps the previous file. | -| `data/geo/.v4`, `.v6` | Committed CIDR allocations per country, read by `functions_geo.php`. Committed so a deploy never depends on ipdeny being reachable. | +| `bin/geo-relay-update.sh` | Refreshes `data/geo/relay-.v4|.v6` from Apple's published iCloud Private Relay egress ranges, **filtered to the countries you ask for** — the full list is 42k IPv4 and 246k IPv6 ranges. Same validate-before-overwrite posture. | +| `data/countries-pt.php` | The 72 countries the geo page offers as checkboxes, grouped and named in pt-PT. Deliberately not all 249: a page with 249 boxes is as unusable as a text field, and the page keeps a free-text escape hatch for the rest. | +| `data/geo/.v4`, `.v6` | Committed CIDR allocations per country, read by `functions_geo.php`. Committed so a deploy never depends on ipdeny being reachable. `relay-.*` are the same thing for Private Relay egresses, from Apple. | | `functions_password_reset.php` | Password recovery over the shared SMTP transport — `password_reset_request/validate/consume/prune()`. Stores only the SHA-256 of the token. | | `compat_secrets.php` | Re-exports the short names (`secret_encrypt`, `secret_decrypt`, `secret_is_encrypted`, `secret_mask`, `secrets_available` / `secrets_key_available`, `SECRET_PREFIX`) that existing site call sites use. A site includes this instead of writing its own cipher. | | `bin/encrypt_secrets.php` | CLI — encrypts any secret-valued row still stored in plaintext. Idempotent, safe to call from `deploy.sh`, refuses to run unless connected to the schema `DB_NAME` names. | | `api/backup_trigger.php` | Self-bootstrapping POST handler — auth + token + curl-fire-and-forget to the worker. Per-platform stub at `/api/backup_trigger.php` is a 1-line require. | | `api/backup_download.php` | Self-bootstrapping download handler — auth + filename validation + `readfile()`. Per-platform stub same shape. | -| `backups/config.php` | Loads host's `.env`, defines `BACKUP_TOKEN`, `BACKUP_KEEP_DAYS`, `BACKUP_FILES_DIR`, DB constants, `cleanOldBackups()`. | +| `backups/config.php` | Loads host's `.env`, defines `BACKUP_TOKEN`, `BACKUP_KEEP_DAYS` / `_WEEKS` / `_MONTHS`, `BACKUP_FILES_DIR`, DB constants, `backup_prune_report()`. | +| `bin/backup-prune.php` | CLI — applies the grandfather-father-son retention without taking a backup. `--dry-run` lists what would go. See [Retention](#retention). | +| `functions_audit.php` + `audit.php` | Audit log — `platform_audit()`, `platform_audit_diff()`, `platform_audit_query()`; writes into each site's existing `audit_log` through a column map, and the routed page `platform.php?tool=audit`. See [Audit log](#audit-log). | +| `functions_security_events.php` | Fleet security log — `platform_security_event()`, `hub_security_sync()`, `hub_security_apply_fleet()`, `hub_security_check()`. Local outbox, batched POST to the hub's `api/security_events.php`, and the fleet's IP bans applied locally as `source='fleet'`. See [Fleet bans and the security log](#fleet-bans-and-the-security-log). | +| `bin/hub-security-sync.php` | CLI — empties the outbox and pulls the fleet bans. Run from cron every 5 minutes. | | `backups/backup_maker.php` | Files ZIP worker — archives ONLY `/uploads/` (the one folder with external data; code is reconstructible from git). Source folder overridable via `BACKUP_FILES_DIR` in `.env`. Writes to `/backups/.zip` and rotates old ZIPs. | | `backups/db_backup.php` | DB dump worker. Writes to `/backups/db_backup_.zip`, **AES-256 encrypted** when `APP_SECRET_KEY` is set. See [Backup encryption](#backup-encryption). | | `functions_agent.php` | Remote-ops agent helpers — `agent_verify_or_die($secret)` (HMAC over method+path+sha256(body)+date, ±5 min), `agent_status(PDO, $repo_root)` (git/migrations/schema-drift/last-backup/php/disk, all `function_exists()`-guarded), `agent_json()`. | -| `api/agent.php` | Self-bootstrapping remote-ops endpoint for the **id.andmore.pt fleet control plane**. Verifies the HMAC, dispatches an action allowlist (Fase 0: `status`). Per-platform stub at `/api/agent.php` is a 1-line require. | +| `api/agent.php` | Self-bootstrapping remote-ops endpoint for the **hub's fleet control plane** (formerly id.andmore.pt's). Verifies the HMAC, dispatches an action allowlist (Fase 0: `status`). Per-platform stub at `/api/agent.php` is a 1-line require. | | `functions_auto_update.php` | Deploy-on-push — `auto_update_run(PDO, $repo_root, ?$ref)` (optional pre-update backup + pull + pending migrations + cache invalidation, behind a per-repo lock), `platform_pre_update_backup()` (triggers and *waits for* the configured backups; a failure aborts the update), `platform_respond_and_continue()`, `auto_update_verify()` (HMAC-SHA256 of the raw body, accepts `X-Gitea-Signature` and `X-Hub-Signature-256`), the on/off settings, and the recorded last-run state. Also `platform_status_summary()` / `platform_status_strip()` — the git-free, one-line platform state a host dashboard can render. See [Auto-update](#auto-update). | | `api/auto_update.php` | Self-bootstrapping deploy webhook. Point a Gitea push webhook at `/api/auto_update.php`; per-platform stub is a 1-line require. Secret in `.env` as `AUTO_UPDATE_SECRET`. Replies `202` immediately and updates with the connection closed — Gitea's delivery timeout is 5 s. | | `functions_hub.php` | The hub client — API/ops keys (generated here, stored AES-encrypted, `.env` wins), the health/ops/pair endpoint auth, the pairing announce, and `hub_ticket_create()` / `hub_ticket_ready()`, which post to the hub's `/api/tickets.php`. Portable across stacks: every host helper is reached through `hub_env()`/`hub_setting()`/`hub_base_url()`. | -| `hub_integration.php` | Shared sysadmin page for the above — hub URL, key rotation, pairing state. Loaded by each platform's `views/sysadmin/hub_integration.php` stub. | +| `hub_integration.php` | Shared sysadmin page for the above — hub URL, key rotation, pairing state. Served by the router at `platform.php?tool=hub_integration`. | +| `api/hub_ops.php` | The hub's remote actions on this platform, behind the **operations** key (not the health key), POST JSON `{"action": …}`. `backup.list` / `backup.trigger`; `update.run` (the full deploy path — pre-update backup, safe pull, migrations, caches — answering 202 before it works) / `update.status`; `git.status` / `git.pull` (code only); `migrations.list` / `migrations.apply_pending`; `ip_bans.list` / `ip_bans.ban` / `ip_bans.unban` (a ban made here gets `source='hub'` and reaches the fleet like any other); `tracking.summary` (aggregates only). Advertised by `hub_ops_actions()` in the health check, so the hub only shows what the platform can do. Per-platform stub is a 1-line require. | | `functions_feedback.php` | Feedback from the people who run the platform — reads the account from any of the fleet's three session shapes (`current_user()`, `$_SESSION['user']`, or loose `user_id`/`username`/`role` keys), the ticket categories, the context block (page, version, commit, account, browser) and `platform_feedback_submit()`. See [Feedback bubble](#feedback-bubble-fleet--hub-tickets). | | `feedback_widget.php` | The bubble itself, bottom-right. Included from the host's backoffice footer; renders nothing for anyone who isn't an admin. Zero dependencies — no Bootstrap, no icon font, no jQuery. | | `feedback_footer_link.php` | The same widget as a footer link instead of a floating bubble — for the public site, where the bottom-right corner is already taken (WhatsApp). A file rather than a flag so the host include stays one bare line either way. | @@ -355,15 +368,216 @@ and a send failure. A transport error is reported separately in `delivery_error`, for an operator only: folding it into `ok` would let the form enumerate accounts whenever SMTP is down. -## Bootstrap contract — what the shared file expects +## Connecting a site -`platform_update.php` is a **view fragment** that expects the calling stub to have already: +Every site's bootstrap is `config/db.php`: it loads `.env`, opens a global +`$pdo` and then makes one call. + +```php +require_once dirname(__DIR__) . '/shared/platform-tools/functions_connector.php'; +platform_connect($pdo, [ + 'base_url' => APP_BASE_URL, + 'schema' => ['name' => 'full_name'], // only what differs from the standard + 'roles' => ['staff' => 40, 'client' => 20], + 'remember' => true, // "manter sessão iniciada" + 'contact_email' => 'geral@example.pt', // shown on the 403 of a banned IP + 'guard' => 'require_sysadmin', // for the shared sysadmin pages +]); +``` + +That wires the hardened session, the shared auth with the site's column map, +the IP guard (and with it the fleet bans and the security sync), and records the +PDO, base URL and environment so no tool has to guess them again — `hub_pdo()` +and `hub_base_url()` read the declared values first. A site with its own login +code passes `'auth' => 'own'`; one with no database passes `null` as the PDO. + +**Conformance.** `platform_conformance($pdo)` reads `information_schema` once +and compares the tables the shared code writes — `users` (through the site's +`auth_schema()` map), `auth_attempts`, `auth_remember_tokens`, `ip_bans`, +`ip_offences`, `system_settings` — against what it expects. It looks only for +**silent** breakage: a missing column the shared code queries, or an old +`NOT NULL` column without a default that makes its `INSERT` fail. Both end the +same way — the defence fails open and nothing says so. Every issue carries the +fix (MariaDB `ADD COLUMN IF NOT EXISTS`, or the `auth_schema()` mapping). + +- **Development** (`APP_ENV` in dev/development/local/staging/test): + `platform_connect()` throws `PlatformConformanceError` with the list — except + under `/api/`, `/sysadmin/`, `/setup.php` and `/platform.php`, where the migration runner that + fixes it lives, and in CLI. +- **Production**: never throws. The health endpoint reports + `checks.conformance`, and the hub card turns yellow. +- **No `APP_ENV`** is treated as production — the side where nothing breaks on + purpose — and reported as a warning. +- Tables that don't exist yet are fine: the shared code creates them on first + use, already in the right shape. Mapped differences (`full_name`, `username`, + surf's `password`) are reported as notes, so sites can converge one at a time. + +## Front controller + +One stub per site instead of one per page: + +```php + true` in the site's `platform_connect()`. Every shared page +(`index`, `platform_update`, `backups`, `restore`, `ip_bans`, `geo`, `tracking`, +`hub_integration`, `smtp_status`) then opens at `platform.php?tool=`, and +`platform_admin_url()` returns those URLs, so the shared pages' own links and +redirects follow without changes. A tool added to `functions_routes.php` +reaches every router site on the next submodule update — including its card on +the index, which lists every routed tool by default. + +What the per-page stubs used to set by hand is declared once in +`platform_connect()`: + +| Option | For | +|---|---| +| `guard` | who may enter (required: without it the router refuses — fails closed) | +| `guards` | per-tool guard, e.g. `['tracking' => 'require_admin']` | +| `replaced_tools` | a site page instead of a shared one, e.g. `['smtp_status' => 'views/sysadmin/comms.php']` | +| `layout` | `['header' => …, 'navbar' => …, 'footer' => …]` | +| `dashboard_url`, `migrations_dir` | the pages' "Voltar" (a string, or per tool: `['index' => 'views/admin/users.php']`, the rest going back to the index), and a non-default migrations folder | +| `sysadmin_tools`, `hide_tools` | the index's own cards (array or callable), and default cards to hide | +| `page_vars` | extra `platform_*` variables a page reads | + +Query string rather than `/platform/backups`: pretty URLs need rewrite rules, +and the fleet runs Docker Apache, cPanel and possibly nginx. The old +`views/sysadmin/.php` stubs become one-line 302 redirects (not 301, so a +rollback isn't stuck in browser caches). + +**The API has its own router.** `public/api/platform.php` is a one-line stub +too: + +```php +` +(`health`, `hub_ops`, `hub_pair`, `feedback`, `agent`, `auto_update`, +`backup_trigger`, `backup_download` — `platform_api_routes()`). The router only +dispatches: each endpoint still checks its own key, HMAC or session + CSRF. A +site with its own version of an endpoint declares it with +`'api_files' => ['backup_trigger' => ]`. **A new endpoint goes +into `platform_api_routes()` and reaches every site with no stub.** The old +`api/.php` stubs stay: Gitea webhooks and the per-platform paths stored in +the hub call them. + +**Clean URLs.** With `'clean_urls' => true` the router links come out without +`.php` (`platform?tool=backups`, `api/platform?endpoint=health`). The site's +`.htaccess` needs the rule that serves an extensionless request from the +matching `.php` — without it those URLs 404: + +```apache +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d +RewriteCond %{REQUEST_FILENAME}\.php -f +RewriteRule ^(.*)$ $1.php [L] +``` + +The health endpoint announces `tools` (tool → URL) and `api` (endpoint → URL) +for router sites, so the hub can link to the local page. + +## Wiring up a new platform + +Every site in the fleet is wired the same way since 2026-09. For a new one: + +**1. The submodule** (inside the platform repo): + +```bash +git submodule add ../platform-tools.git shared/platform-tools +git config -f .gitmodules submodule.shared/platform-tools.branch main +``` + +Clones then need `--recurse-submodules` (or `git submodule update --init`). The +"Atualizar" button keeps the submodule in step after every pull, including one +freshly added upstream, so this is only by hand on the very first checkout. + +**2. The bootstrap.** `config/db.php` loads `.env`, opens a global `$pdo` and +calls `platform_connect()` — see [Connecting a site](#connecting-a-site) for +the auth options. For the sysadmin pages add: + +```php + 'router' => true, + 'clean_urls' => true, // only with the .htaccess rule in step 4 + 'guard' => 'require_sysadmin', +``` + +plus whatever the site needs from the [front controller](#front-controller) +table (layout, "Voltar", migrations folder, its own cards, replaced tools). +`config/functions.php` provides `env()` and `base_url()`. + +**3. Two one-line front controllers**, under the docroot: + +```php +`) and every shared endpoint +(`/api/platform?endpoint=`). Point the navbar's "Sistema" link at +`platform_admin_url()`. + +**4. Clean URLs** (optional — with it, step 2's `clean_urls`): the rule in the +site's `.htaccess` that serves `/x` from `x.php`, shown under +[Front controller](#front-controller). + +**5. The URLs other systems call.** These stay one-line stubs under +`public/api/`, because something outside the site holds their path: + +| Stub | Called by | +|---|---| +| `health.php` (→ `api/hub_health.php`), `hub_ops.php`, `hub_pair.php` | the hub — the paths go out with the pairing announce (`health_path`, `ops_path`, `pair_path` in `functions_hub.php`) and are stored per platform | +| `auto_update.php` | the Gitea push webhook | +| `agent.php` | the hub's HMAC agent | +| `backup_trigger.php`, `backup_download.php` | the shared backups page's own forms and links | +| `db_backup.php`, `backup_maker.php` | the site itself (the backup self-call; see below) | +| `feedback.php` | the feedback bubble | + +A stub is `.php';`. +Any of them can be pointed at the router instead — a webhook URL of +`…/api/platform?endpoint=auto_update` works the same. The stubs exist because +those URLs were configured before the router did. + +**6. `.env`**: `APP_ENV`, `APP_BASE_URL`, `DB_*`, `APP_SECRET_KEY`, +`BACKUP_TOKEN` (+ `BACKUP_TRIGGER_URL_PREFIX=api/` under a `public/` docroot), +`AUTO_UPDATE_SECRET` for deploy-on-push, `HUB_URL` for the hub. Everything else +has a default or lives in `system_settings`. + +**7. Pair with the hub** from *Sistema → Integração com o hub*, and add the +cron lines: `bin/hub-security-sync.php` every 5 minutes, the backup cron nightly. + +**Bumping the shared version** (dev, push, then "Atualizar" on each host): + +```bash +git submodule update --remote shared/platform-tools +git add shared/platform-tools && git commit -m "Bump platform-tools" && git push +``` + +quack sets `ignore = all` on the submodule and follows the branch tip instead; +`git_sync_submodules()` updates it with `--remote`. + +### Per-page stubs (a site without the router) + +Before the router every page had its own stub, and a site that does not declare +`'router' => true` still works that way. The shared page is a **view fragment** +that expects the stub to have already: 1. Bootstrapped the host's DB so a global `$pdo` PDO is in scope. 2. Run the sysadmin auth guard (so the request only reaches this point if authorized). 3. Set `$repo_root` to the absolute path of the host repo (the directory containing `.git`). -Optionally, the stub may set any of these BEFORE the `require`: +```php +.php` files are 302 redirects to it. -This applies to **dsa**, **fotografia**, **moremio**, **tickets** — they share the same convention (`config/db.php` opens `$pdo`, `config/functions.php` loads helpers + `require_sysadmin()`). +## Wiring up the backups feature -**1. Add as a submodule** (run inside the platform repo): - -```bash -git submodule add ssh://git@//platform-tools.git shared/platform-tools -git commit -m "Add platform-tools submodule" -git push -``` - -**2. Replace [views/sysadmin/platform_update.php](views/sysadmin/platform_update.php):** - -```php - Since the "Atualizar (git pull)" button in `platform_update.php` now runs -> `git submodule update --init --recursive` itself after the pull, the second -> command is only needed for the **very first** checkout of a host whose -> `platform_update.php` page can't load yet (because the submodule it lives in -> isn't populated). Once the page loads once, the UI "Atualizar" keeps the -> submodule in sync — including pulling in a submodule freshly added upstream. - -**6. To bump to a newer shared version** (run on dev, push, then `git pull` on prod): - -```bash -git submodule update --remote shared/platform-tools -git add shared/platform-tools -git commit -m "Bump platform-tools" -git push -``` - -## Wiring up the sysadmin hub (`views/sysadmin/index.php`) - -The hub is the single entry point — point the platform navbar at `views/sysadmin/index.php` and every other sysadmin tool is reachable from there. Cards link to the platform's own stubs (`base_url('views/sysadmin/platform_update.php')`, etc.), so the URLs stay stable even if you move the submodule. - -**1. Create [views/sysadmin/index.php](views/sysadmin/index.php):** - -```php -">Sistema -``` - -**3. Adding more tools later** — set `$sysadmin_tools` in the stub before the `require`: - -```php -$sysadmin_tools = [ - [ - 'title' => 'Mensagens', - 'description' => 'Fila de email/SMS, retries, cancelamentos.', - 'icon' => 'bi-envelope-paper', - 'url' => base_url('views/sysadmin/messages.php'), - 'color' => 'info', - 'badge' => '3 falhadas', // optional - ], -]; -require $repo_root . '/shared/platform-tools/index.php'; -``` - -The entry is appended to the default two cards (Atualizar plataforma + Backups). - -## Wiring up the backups feature (standard `config/`-based stack) - -The backups feature has a wider surface than `platform_update.php` — it needs a view, helpers, two API endpoints, and three worker scripts that run in separate HTTP requests (curl-triggered, token-protected). The submodule contains all of these; the platform just needs 4 thin stubs plus a writable `/backups/` directory. +The pages come with the router (`?tool=backups`, `?tool=restore`); what a site +adds is the storage, the endpoints and the self-call. The workers run in +separate HTTP requests (curl-triggered, token-protected). **Prerequisites:** -- `/.env` defines `BACKUP_TOKEN=` (used to authenticate the worker URLs). Optionally `BACKUP_KEEP_DAYS=7` and `BACKUP_FILES_DIR=uploads` (folder the files backup archives, relative to the host root — only uploads hold external data; everything else is reconstructible from git). +- `/.env` defines `BACKUP_TOKEN=` (used to authenticate the worker URLs). Optionally `BACKUP_KEEP_DAYS=7`, `BACKUP_KEEP_WEEKS=4`, `BACKUP_KEEP_MONTHS=1` (see [Retention](#retention)) and `BACKUP_FILES_DIR=uploads` (the folder the files backup archives, relative to the host root — `public/uploads` under a `public/` docroot; only uploads hold external data, everything else is reconstructible from git). - `/backups/` exists and is writable by PHP-FPM. The workers will `mkdir` it if missing but the parent must be writable. - Add `backups/*.zip` to `.gitignore` (the workers write ZIP files into it). -- `/config/env.php` defines `env_load()` + `env()` (already present on dsa, fotografia, moremio, tickets). +- `/config/env.php` defines `env_load()` + `env()`. +- `config/functions_backup.php` requires the shared `functions_backup.php`. It is also where a site defines `BACKUP_TRIGGER_URL_PREFIX` when the `.env` doesn't, which is why the router and the hub-triggered backup load it first (`hub_load_backup_helpers()`). +- The endpoint stubs `api/backup_trigger.php` and `api/backup_download.php` (step 5 above). > **Under a `public/` docroot, the two worker wrappers are mandatory.** The > workers live in `shared/platform-tools/backups/`, which is *not* reachable @@ -503,43 +624,41 @@ The backups feature has a wider surface than `platform_update.php` — it needs > — which arrives with `curl_errno = 0` and therefore looks like a successful > request. It produced no backups at all for as long as it ran. -**1. Replace [views/sysadmin/backups.php](views/sysadmin/backups.php):** - -```php -/shared/platform-tools/backups/`. They're reached via HTTP at `base_url('shared/platform-tools/backups/backup_maker.php?token=…')` — the URL prefix is hardcoded in `functions_backup.php` but can be overridden by defining `BACKUP_TRIGGER_URL_PREFIX` before the file loads. +Without `BACKUP_TRIGGER_URL_PREFIX` the workers are reached at +`base_url('shared/platform-tools/backups/.php?token=…')`, which only +works where the repo root is the docroot. **.htaccess hardening (automatic)**: the ZIPs contain the full host tree including `.env`, so `/backups/` must never be directly web-readable. `backup_dir()` and both workers write a deny-all `/backups/.htaccess` automatically on first use (Apache 2.2 and 2.4 syntax). On nginx, add the equivalent `location ^~ /backups/ { deny all; }` yourself. Backup filenames also carry seconds + a random suffix (`backup_DD_MM_YYYY_HH_MM_SS_xxxxxx.zip`), so they can't be guessed even if the deny rule is missing; ZIPs are served exclusively through `api/backup_download.php`, which sets an attachment header. Files backups exclude `.git/`, `node_modules/`, `backups/` and `*.zip`. +### Retention + +Grandfather-father-son, per type (DB and files are counted separately), applied +by `backup_prune()` at the end of every **successful** worker run — a failed +backup never prunes, because that is exactly when the old copies are the only +ones left. Kept: + +- everything from the last 24 hours (the restore points of an update); +- the newest of each of the last `BACKUP_KEEP_DAYS` days that have a backup (7); +- the newest of each of the `BACKUP_KEEP_WEEKS` weeks before the oldest daily (4); +- the newest of each of the `BACKUP_KEEP_MONTHS` months before the oldest weekly (1); +- the newest backup of each type, always. + +With the defaults that is 12 copies per type spanning about two months. Each +tier starts where the previous one ends — otherwise "1 monthly" is simply this +month's newest copy, which the daily tier already holds, and nothing older than +three weeks survives. Days are counted as *days with a backup*, not calendar +days, so a site whose backups stopped keeps its last ones instead of pruning to +nothing. + +The date comes from the filename, not the mtime, so a copy moved between disks +keeps its age. `bin/backup-prune.php --dry-run` shows what a change to the +`BACKUP_KEEP_*` values would delete before you make it. + +This keeps *more* history than the previous rule (delete everything older than +`BACKUP_KEEP_DAYS`) but far fewer files per week: several same-day copies — +nightly, pre-update, hub-triggered — collapse to one once they leave the 24-hour +window. + ## Wiring up the remote-ops agent (hub fleet control plane) Lets the hub read this platform's status and (later phases) pull git, apply @@ -552,7 +671,7 @@ HMAC-authenticated with a **dedicated** secret (never the content/notify ones). > `HUB_OPS_SECRET` are unchanged; only the operator moved. Older comments in > this file and in the sites may still say "id". -**1. Submodule:** same as above (already present if backups/platform_update are wired). +**1. Submodule:** see [Wiring up a new platform](#wiring-up-a-new-platform). **2. Create [api/agent.php](api/agent.php)** (1-line stub): @@ -567,9 +686,8 @@ require __DIR__ . '/../shared/platform-tools/api/agent.php'; HUB_OPS_SECRET= ``` -Generate the value on `id.andmore.pt` → **Plataformas → → "Gerar segredo de -operações"**, paste it here, then flip **"Ativar operações remotas"** on the same -screen. Empty secret → the agent answers `503` (disabled). +Generate the value on the hub (the platform's page → "Gerar segredo de +operações"), paste it here, then turn remote operations on in the same place. Empty secret → the agent answers `503` (disabled). The agent derives nothing from config beyond `$repo_root = dirname(__DIR__, 3)`; it reuses the same `functions_git/migrations/schema/backup` already in the @@ -606,8 +724,8 @@ require __DIR__ . '/../../shared/platform-tools/api/feedback.php'; ``` The endpoint is cookie-authenticated rather than key-authenticated, so it needs -the host's session — `hub_bootstrap.php` opens it, and knows both fleet stacks -(`config/db.php`, or `src/config.php` + `App\Database`). +the host's session — `hub_bootstrap.php` opens it through the site's +`config/db.php`. **2. The bubble** — one include at the end of the backoffice footer (`includes/footer.php`), just before ``. It guards itself: not an admin, @@ -632,10 +750,9 @@ host: both entry points are one bare include, and the day the decision changes it changes for the whole fleet at once. Two footers in one response render one widget, not two (`$GLOBALS` one-shot -flag). If the sysadmin hub page doesn't live at -`/views/sysadmin/hub_integration.php` on this platform, set -`$GLOBALS['platform_feedback_hub_url']` before the include — that's the only -link the widget emits. +flag). The widget's one link — to *Integração com o hub* — is the router URL +on a router site, else `/views/sysadmin/hub_integration.php`; set +`$GLOBALS['platform_feedback_hub_url']` before the include to override it. **Checks after wiring:** open any backoffice page as an admin → bubble bottom right; send one → green line with the ticket ref and a tracking link, and the @@ -651,39 +768,277 @@ account from `current_user()`, from `$_SESSION['user']`, or from loose database round-trip (for the e-mail, which the ticket desk requires and that shape doesn't carry) and it is cached in the session. -## Wiring up surf (different stack — `src/` + `Database::getInstance()`) +## Surf (silver) -Surf uses `src/` instead of `config/`, has no `require_sysadmin()`, no `setting()`, no settings cache. The shared page handles this gracefully (all those integrations are guarded with `function_exists()`), but the stub needs to adapt. +Surf used to be a second stack — `src/config.php` + `App\Database`, no global +`$pdo`, `getBaseUrl()` instead of `base_url()` — and every tool here carried a +branch for it. Since 2026-09 it follows the same contract as the others: +`config/db.php` opens `$pdo` and calls `platform_connect()`, and +`config/functions.php` has `env()` and `base_url()`. `src/` is still its code +library (`App\Database` returns the same connection as `$pdo`). -**1. Submodule:** same as above (`git submodule add … shared/platform-tools`). +What stays its own is declared in its `platform_connect()` rather than here: -**2. Replace [views/sysadmin/platform_update.php](views/sysadmin/platform_update.php):** +- the guard is a closure on the session role (`guard`); +- the layout partials live in `views/partials/` (`layout`); +- migrations live directly in `database/` (`migrations_dir`, which the page + router and the API router both pass on as `$GLOBALS['MIGRATIONS_DIR']`); +- its own `api/backup_trigger.php` and `api/backup_download.php`, since it has no + `config/functions_backup.php` (`api_files`). + +## Captcha + +A question the visitor reads and answers. Two lines to add it, and it can be +added to as many forms as a platform has. + +It is used two ways, and the second is the one that matters most here: **as a +gate**, on a form the invisible defences have nothing to score (registration, +password recovery); and **as an appeal** — the submission is refused as usual, +and instead of a silent drop the person gets a question that releases it. The +appeal is what recovers the people the country gate blocks by mistake, and it is +documented first for that reason. ```php -: +echo platform_captcha_field('registo', $pdo); + +// in the handler, after the CSRF check: +if (($erro = platform_captcha_verify('registo', $pdo)) !== null) { + $error = $erro; // already pt-PT, ready to show } - -$pdo = App\Database::getConnection(); - -$repo_root = dirname(__DIR__, 2); -$platform_layout_header = $repo_root . '/views/partials/head.php'; -$platform_layout_navbar = $repo_root . '/views/partials/navbar.php'; -$platform_layout_footer = $repo_root . '/views/partials/footer.php'; -$platform_dashboard_url = '/views/admin/dashboard.php'; - -require $repo_root . '/shared/platform-tools/platform_update.php'; ``` -That's it. Surf has no `migration_*.sql` files (its schema is `database/install/ssc_school.sql`), so the migrations card will show empty. If surf later introduces migrations under `database/`, the card lights up automatically. To point at a non-default migrations directory, set `$GLOBALS['MIGRATIONS_DIR']` in the stub before the `require`. +The first argument is the **scope**. It goes into the signature, so a challenge +picked up on the contact form does not validate on the registration form, and +two forms on the same page are independent. Anything stable works as a scope — +use the form's own name. -The surf admin dashboard already links to `platform_update.php` from `views/admin/sysadmin.php` and `views/partials/navbar.php`, so no nav changes are needed. +### The appeal — a second chance after a refusal + +This is what the module is actually for. The country gate refuses submissions +from outside Portugal, and that catches two kinds of person who are not spam at +all: **iCloud Private Relay users**, whose traffic leaves through Apple egress +addresses that the ipdeny lists attribute to another country, and **emigrants**. +Both got the thank-you page and then waited for a reply that was never coming, +because the submission had been dropped in silence. + +Silence is still right for a bot. What was wrong was that a person had no way +back. So: the refused submission is held, the person is asked a question, and a +correct answer releases it. + +```php +// ─── handler ──────────────────────────────────────────────────────────────── +$appeal = null; + +// 1. a submission already held, coming back with an answer +if (($libertada = platform_captcha_appeal_claim($pdo, 'contacto', $erroCaptcha)) !== null) { + processar_contacto($libertada); // exactly as if it had passed first time + $sucesso = true; +} elseif ($erroCaptcha !== null) { + $appeal = platform_captcha_appeal_token(); // wrong answer: same screen again + $error = $erroCaptcha; +} else { + // 2. a normal submission + if (($reason = platform_antispam_check($pdo, 'contacto', 'mensagens', $campos)) !== null) { + $appeal = platform_captcha_appeal_offer($pdo, 'contacto', $reason); + if ($appeal === null) { + $sucesso = true; // no appeal for this one: thank-you page, as always + } + } else { + processar_contacto($_POST); + $sucesso = true; + } +} + +// ─── view ─────────────────────────────────────────────────────────────────── + +

    Não conseguimos confirmar o envio automaticamente. Responda à pergunta + abaixo e a sua mensagem segue tal como a escreveu.

    + + +``` + +`platform_captcha_appeal_claim()` has three outcomes, and the caller needs all +three: an array is the released submission (the original `$_POST`, minus the +mechanism fields); `null` with an error means the answer was wrong and the +screen should be printed again; `null` with no error means there was no appeal +in play and the normal flow continues. + +Note what the site keeps: **this module never decides what a form means.** It +hands back the payload and the site creates the lead, opens the ticket, sends +the mail — exactly as it would have done on the first pass. + +#### Four decisions worth not undoing by accident + +**Not every refusal gets an appeal.** `honeypot` and `carimbo inválido` are +excluded by default (`appeal_never`): a hidden field nobody can see, and a +signature only our own form produces, have no innocent reading. Offering those a +second screen is explaining to a bot what caught it. Everything else — country, +per-IP ceiling, content score, expired stamp — has real false positives, and +those are what this is for. + +**The submission stays on the server.** The second screen carries only the +answer. Re-posting the content in a hidden field would let it be edited after +being scored: a clean message on the first pass, the real text on the second. + +**The appeal is not bound to the IP.** That would be the reflex, and it would +break the exact case this exists to fix — Private Relay changes the egress +address between requests, so the person comes back from a different IP than the +one they were refused on. What binds the appeal is the HMAC. + +**A released appeal deletes the offences that refusal produced**, scoped to that +form, that address, and that moment. Without it the appeal is a trap: every +attempt to make contact adds an offence, and [the ladder](#ip-banning) bans at +three in 24 h — the third time a Private Relay user tried to reach us they would +lose the site entirely, right after we had confirmed they were human. + +It does **not** lift an existing ban, and that one is a choice rather than a +consequence: a captcha that undoes a ban is an oracle — solve a puzzle, regain +access — and that is a far more attractive target than a contact form. Someone +already banned talks to a person, through the address on the 403 screen. + +#### Storage and limits + +The queue is its own table, `captcha_appeals`, created with `CREATE TABLE IF NOT +EXISTS` on first use exactly like the [IP ban](#ip-banning) tables — a site +should not need a migration to be able to undo a mistake. It is deliberately not +`blocked_submissions`: that table has a different shape per site, and it is a +record, not a work queue. + +| Key | Default | Notes | +|---|---|---| +| `appeal_table` | `captcha_appeals` | Validated as an identifier before interpolation | +| `appeal_ttl` | `7200` | Two hours to answer. This is a person looking at a screen — and the shorter it is, the less time a refused submission sits stored | +| `appeal_tries` | `6` | Answers per held submission, then the appeal closes | +| `appeal_max_ip` | `5` | Appeals opened per IP per hour, so the queue cannot become a spam dump | +| `appeal_never` | `['honeypot', 'carimbo inválido']` | Substrings of the refusal reason that get no second chance | + +Rows are pruned opportunistically whenever an appeal is opened, so there is no +extra cron to forget to install. `claimed_at` tells you how many false positives +the flow actually recovered — worth looking at after a week, because that number +is the argument for or against the country gate's current settings. + +#### The other half of the iCloud Relay problem + +The appeal recovers the person, but it still asks them to do something. The root +cause is an attribution error and is fixable on its own: Apple publishes the +Private Relay egress ranges, with the country and region each one serves, so a +relay user in Aveiro can be attributed to PT instead of being refused. Feeding +that list into `functions_geo.php` alongside the ipdeny data would remove most +of these refusals before they happen. **Not implemented** — the appeal flow does +not depend on it, and the two are worth doing in either order. + +### Which of the three anti-spam modules to reach for + +| | Refuses | Use it for | +|---|---|---| +| `functions_antispam.php` | silently | honeypot, blocklist, 24 h ceiling per e-mail and IP | +| `functions_antispam_forms.php` | silently | forms with free text worth scoring — contact, enquiry | +| `functions_captcha.php` | **out loud** | forms with nothing to score — registration, password recovery, a comment box | + +The first two are invisible on purpose: a bot must not learn what caught it, and +a lead refused by mistake has to be recoverable from the log. That only works +when there is content to score and when the refusal can be silent. A password +recovery form has neither property — refusing it in silence leaves a real person +pressing the button forever — so it gets the captcha instead. + +Using a captcha *and* the traps together is the normal case and is not +redundant: the traps catch the script that never looks at the page, the captcha +catches the one that does. + +### What it is, and what it is not + +Self-hosted, and deliberately not reCAPTCHA/hCaptcha/Turnstile. Three reasons, +none of them taste: [ASSETS.md](ASSETS.md) settled on 2026-09-01 that no +front-end asset leaves the network in production, and a third-party captcha is a +form that does not open when someone else's service is down; it runs third-party +JavaScript in the page, including — in the backoffice — in the session of +whoever is signed in as an admin; and it ships every visitor's IP and behaviour +to a third party, which on a European site is a GDPR decision nobody took. + +The price is accepted: **this stops scripts, not a human paid to solve +challenges.** That was equally true of reCAPTCHA. + +The challenge is either a small sum ("Quanto é sete mais 4?") or a letter of a +word ("Escreva a terceira letra da palavra CADEIRA"), picked per challenge. One +operand is spelled out and the other is in digits, which breaks the three-line +`/(\d+)\s*\+\s*(\d+)/` solver. Answers are accepted in digits or in words, upper +or lower case, with or without accents, and the Brazilian spellings +(`quatorze`, `dezesseis`, `dezenove`) count as right because whoever writes them +answered correctly. + +**No JavaScript and no images**, per rule 10 of [PHILOSOPHY.md](PHILOSOPHY.md) — +and because a screen reader reads a written question and cannot read a distorted +image. + +### No server state, and the one thing that costs + +The challenge travels in an HMAC-signed token: timestamp, random nonce, +signature. The question *and its answer* are derived from the nonce with the +site's key, so the answer never leaves the server and there is nothing to store +between requests. No table, no required session, and it works behind any cache. + +The cost is replay. **One question is one attempt** — the nonce is marked used +as soon as it is verified, right or wrong — but that mark lives in the session, +and `platform_captcha_verify()` will not start a session of its own: on a public +page that would set a cookie on everyone who walks past a form, which changes +the site's cookie policy and defeats any cache in front. With no active session +the defence degrades to "reusable within the window", which is why the default +ttl is 15 minutes rather than an hour. + +So: on a page that already has a session (anything behind a login, and most +registration flows), single use is real. On a fully anonymous page, treat the +ttl as the limit and leave `offence_forged` on. + +### Failure posture: closed + +Unlike the country gate, a missing token is a refusal. A captcha whose absence +lets the request through is not a captcha — it would be enough not to send the +field. A site that forgets to print `platform_captcha_field()` therefore sees +its form refused on the first test, instead of shipping a defence that is +quietly switched off. + +### Configuration + +Call once, before the first field is rendered. Everything has a working default; +the table is what is worth changing. + +```php +platform_captcha_config([ + 'type' => 'mixed', // 'math' | 'letter' | 'mixed' + 'ttl' => 900, // seconds the challenge stays valid + 'help' => '', // '' removes the help line under the field + 'class_wrap' => '', // empty strings for a site without Bootstrap 5 +]); +``` + +| Key | Default | Notes | +|---|---|---| +| `type` | `mixed` | `mixed` alternates sums and letters, so an automated solver has to handle two formats | +| `ttl` | `900` | Also the replay window when there is no session | +| `field_answer` / `field_token` | `captcha_answer` / `captcha_token` | Rename if the site already POSTs a field by that name | +| `class_wrap` / `class_label` / `class_input` / `class_help` | Bootstrap 5 classes | Empty string drops the attribute entirely | +| `help` | a one-line hint | `''` renders nothing | +| `single_use` | `true` | Only has an effect where a session is active | +| `offence_forged` | `true` | A forged or missing token counts toward [IP banning](#ip-banning) | +| `offence_wrong` | `false` | A wrong answer does **not**. The ladder bans at 3 offences in 24 h, and someone who mistypes "catorze" twice is not a bot — that would be banning people for failing a question we asked them | +| `words` | 16 accent-free pt-PT nouns | The pool for the letter challenge | + +For a form that needs its own markup — a grid, a modal, a step in a wizard — +`platform_captcha_issue($scope, $pdo)` returns `question`, `token`, the two +field names and a unique `id`, and you write the HTML. + +### The key + +Challenges are signed with `platform_derived_key('captcha', $pdo)`, from +`functions_settings.php`: `APP_SECRET_KEY` where there is one, otherwise a +random value stored in `system_settings`, otherwise derived from the install's +own configuration. It is domain-separated, so an anti-spam stamp can never +validate here and vice versa. Pass the `$pdo` at every call site — a site that +passes it in the form and omits it in the handler would sign with one key and +verify with another on an install that has no `APP_SECRET_KEY`. ## Country gating @@ -706,6 +1061,8 @@ Two levers, because they carry very different risk: GEO_MODE=forms GEO_ALLOW_COUNTRIES=PT # ISO 3166-1 alpha-2, comma or space separated GEO_FAIL_CLOSED=false # see below +GEO_ALLOW_IPS= # addresses that always pass, see below +GEO_TRUST_RELAY=true # score iCloud Private Relay by the country it serves ``` Settings resolve **database first, then `.env`, then the default**, so the @@ -715,16 +1072,8 @@ as before. An empty stored row counts as "unset" and falls through to `.env`; that is deliberate, because `platform_settings_get()` lets an empty row silently outrank a populated `.env`, and that has cost this estate real debugging time. -Wire the page up with a stub at `views/sysadmin/geo.php`: - -```php -/shared/platform-tools/bin/geo-relay-update.sh pt +``` + +That writes `data/geo/relay-pt.v4` and `.v6` — the same format as the ipdeny +lists, read by the same code, and 611 ranges rather than the 288k in Apple's +full file. **It is not a Relay whitelist**, and the per-country filtering is what +makes that true: a range serving France is never written, so a French relay user +is refused by the normal path like any other foreign address. Opening every +Relay range would let in any iCloud+ subscriber on earth, which is precisely +what the gate exists to prevent. + +`GEO_TRUST_RELAY=false` turns it off. With no lists downloaded the module is +inert either way, so wiring it in ahead of the data is safe. + +**Everyone else: `GEO_ALLOW_IPS`.** A list of addresses or CIDRs that always +pass — the client whose office VPN lands abroad, a monitoring service, the one +person who called today. It is checked *before* everything else, including the +fail-closed branch, because it is the only defence that still works when the +country lists are missing. + +```ini +GEO_ALLOW_IPS=203.0.113.7, 198.51.100.0/24, 2001:db8::/32 +``` + +Both are editable from the geo page, which also has a one-click "add my own +address" for the case where the person locked out is the operator. + +**Order of decision**, and none of it runs when `GEO_MODE=off`: + +1. private/loopback → pass (the container's own cron and health checks) +2. `GEO_ALLOW_IPS` → pass +3. a Private Relay egress serving an allowed country → pass +4. no usable country data → fail-open (or refuse under `GEO_FAIL_CLOSED`) +5. the address is in an allowed country → pass +6. otherwise → refused, with the reason the caller logs + +A refusal at step 6 is exactly where the [captcha appeal](#the-appeal--a-second-chance-after-a-refusal) +picks up: these two features are the same problem solved at two ends, and both +are worth having. The relay lists remove most of the wrong refusals before they +happen; the appeal recovers the ones that still get through. + ### The data Per-country CIDR lists from ipdeny.com, one file per family, committed to the @@ -772,7 +1181,12 @@ Allocations move slowly, so monthly is plenty: The script refuses to overwrite a good file with a short list, a non-CIDR body, or an HTML error page served with 200 — any of which would otherwise mean "no visitor is in Portugal", and with `GEO_FAIL_CLOSED` would lock the country out -of its own site. +of its own site. `geo-relay-update.sh` has the same posture, and the two run +independently: Apple being unreachable must not stop the country lists +refreshing, or the other way round. + +The geo page's "Actualizar listas" button runs both scripts, and reports a +partial failure as a partial failure rather than as success. Lookup packs the address with `inet_pton()` and binary-searches sorted ranges, comparing the raw bytes. The same code path serves IPv4 and IPv6, and it steps @@ -807,8 +1221,8 @@ Call `platform_track_conversion()` **after** the submission is accepted, never before. A request the antispam or the country gate refused is not a conversion, and counting it would make a campaign look better for attracting bots. -Wire the page up with a stub at `views/sysadmin/tracking.php`, same shape as the -other shared pages. +The page is `platform.php?tool=tracking` on a router site; fotografia +lets admins in, not only sysadmins, with `'guards' => ['tracking' => 'require_admin']`. ### Country attribution @@ -846,7 +1260,7 @@ and the country gate judges origin rather than behaviour. An address that comes back every night at 3am looked like a new visitor to all three. ```php -platform_ip_guard($pdo, 'info@example.pt'); // once, early in the bootstrap +platform_ip_guard($pdo, 'info@example.pt'); // once, early — platform_connect() does it ('contact_email') platform_ip_record_offence($pdo, 'antispam:contact'); // from each existing defence ``` @@ -877,6 +1291,110 @@ Lifting a ban does **not** clear the offence history. If it did, the address would drop back to rung zero and the ladder would restart, which would make every administrator's mistake an invitation to try again. +## Audit log + +`functions_audit.php` — who did what, to what, when and from where, in each +site's `audit_log`, written by one function: + +```php +platform_audit($pdo, 'user.delete', [ + 'target_type' => 'user', + 'target_id' => 42, + 'target_label' => 'Maria Silva', + 'summary' => 'Sent to the recycle bin', + 'changes' => platform_audit_diff($before, $after), // {field: {from, to}} +]); +``` + +The fleet had three incompatible audit logs (hub, dance, quack — different +columns, different functions) and five sites with none. + +- **Existing tables are not renamed.** The writer reads the site table's columns + once per request and writes each canonical field into the column the site maps + it to — `platform_connect(['audit' => ['map' => ['actor_id' => 'user_id', …]]])`, + like the auth `schema`. A field with no column is dropped, a NOT NULL column is + never sent a NULL, text is cut to the column size, a non-numeric id is not + forced into an INT column. The site migrations add the missing columns so + nothing is lost from then on. A site with no table gets the canonical one on + first use. +- **Never breaks the action**: a failed write goes to the error log. +- **Secrets never enter**: any `changes` key that looks like one (password, + token, secret, api/ops key, hash, cookie, csrf, validator, pairing code) is + replaced by «(oculto)» at any depth, keeping the `{from, to}` shape. +- **The actor comes from the session** in any of the fleet's shapes, the IP is + the real one; callers pass `'actor'` when they know better (the hub acting + through ops, the deploy webhook, dance's attendance PIN). +- **Pruned** after `keep_days` (730 by default), opportunistically. + +What the shared code records by itself, on every site: `auth.login` / +`auth.logout` (shared auth), every action of *Atualizar plataforma* +(`platform.`, reads excluded), `platform.auto_update`, `backup.delete`, +`backup.restore`, `ip.ban` / `ip.unban`, `hub.` from *Integração com o +hub* (keys never recorded), `settings.smtp`, `settings.geo`, and every mutating +`api/hub_ops.php` action with the hub as the actor. + +The page is `platform.php?tool=audit` (`audit.php`): filters by who, action +prefix, type, text and dates, the before/after of each change, CSV export. +## Fleet bans and the security log + +Once a platform is paired with the hub, what its defences refuse also goes to +the hub, and the hub's list of banned IPs comes back and is enforced here. An +address banned on dance is turned away at fotografia's door. + +Nothing to wire beyond what already exists: `platform_ip_guard()` schedules the +sync, and the defences report through the functions they already call. Add the +cron line so a site with no traffic still receives the other sites' bans: + +``` +*/5 * * * * php /var/www/html/shared/platform-tools/bin/hub-security-sync.php +``` + +**What is reported.** `ip_ban`, `ip_unban`, `offence` (everything that reaches +`platform_ip_record_offence()`: antispam, captcha, country gate), +`login_failed` / `login_throttled`, `csrf_failed` (`platform_csrf_ok()`) and +`mail_rate_limited`. Login events come from `auth_throttle_hit()` / +`auth_throttle_check()`; a site with its own login code reports from its login +page instead: + +```php +platform_security_event($pdo, 'login_failed', hub_security_mask_identifier($email)); +hub_security_maybe_sync($pdo); // only needed if the site doesn't call platform_ip_guard() +``` + +Every email address in an event's detail is masked (`a***@example.pt`) before +it leaves the site — offence details often carry the submitter's address. + +`platform_security_event_sink($callable)` replaces the outbox with a direct +call. The hub uses it: it is the fleet's record, so its own events are written +straight to its tables instead of being sent to itself. + +**How it travels.** Events go into a local outbox (`hub_security_outbox`) and +leave in batches: at the end of any request, at most every 30 s while there are +events and every 5 min when there are none, after the response is sent where +the SAPI allows it (`fastcgi_finish_request()`); and from the cron script. One +request per event would put every attacker request behind a network call and +turn an attack on one site into an attack on the hub. The request carries the +same key the hub probes this platform with, so an unpaired site records +nothing — otherwise the outbox would grow forever. With the hub down, events +wait (capped at 5000, bans never dropped) and local banning works exactly as +before. `checks.security` in the health endpoint goes `false` when events have +been stuck for over an hour. + +**The fleet's bans, locally.** They land in `ip_bans` with `source='fleet'` +and show as *frota* on the IP-ban page. The rules: + +- A local active ban always wins over a copy — it was decided here, with this + site's reason. +- Copies are never sent back to the hub (`platform_ip_ban()` skips + `source='fleet'`), otherwise they would echo. +- **Lifting a ban anywhere lifts it fleet-wide.** Unbanning here sends + `ip_unban`; the hub lifts the fleet ban and the copies disappear from every + site on the next sync. Without that, a local unban of a copy would be undone + five minutes later. The site where the ban started keeps its own until it + expires or is lifted there. +- Copies that stop arriving are deleted — but only when the hub says the list + is complete. A truncated list says nothing about what it left out. + ## Backup encryption A database dump sitting in the clear is the most sensitive file one of these @@ -909,29 +1427,22 @@ made before this change still restore without special handling. ## Verification after wiring (per platform) ```bash -# 1. Syntax — platform_update stubs -php -l views/sysadmin/platform_update.php config/functions_git.php config/functions_migrations.php +# 1. Syntax — the bootstrap and the two front controllers +php -l config/db.php public/platform.php public/api/platform.php -# 2. Syntax — backups stubs (if wired) -php -l views/sysadmin/backups.php config/functions_backup.php api/backup_trigger.php api/backup_download.php +# 2. Submodule populated and on the expected commit +git -C shared/platform-tools log --oneline -1 -# 3. Submodule populated -ls shared/platform-tools/ # expect: platform_update.php, functions_git.php, functions_migrations.php, functions_schema.php, backups.php, functions_backup.php, api/, backups/, README.md +# 3. Over HTTP (no session needed) +curl -s "https:///api/platform?endpoint=bogus" # {"ok":false,"error":"endpoint desconhecido"} — an HTML 404 means the push never deployed +curl -s "https:///api/platform?endpoint=health" # 401/503 JSON — the endpoint's own auth answering +curl -sI "https:///platform?tool=index" # 302 to the login page +curl -sI "https:///views/sysadmin/backups.php" # 302 to platform.php?tool=backups (sites that had the old stubs) -# 4. End-to-end platform_update (in browser, as sysadmin) -# - Open /views/sysadmin/platform_update.php -# - Confirm git state panel shows branch + SHA + commit history -# - Click "Verificar atualizações (fetch)" — see fetch output -# - Click "Aplicar" on an idempotent test migration — confirm applied_migrations row appears -# - Click "Exportar esquema" — success flash with table count; /database/schema.sql created/updated -# - Re-click "Exportar esquema" without schema changes — `git diff database/schema.sql` shows NO change (determinism check) - -# 5. End-to-end backups (in browser, as sysadmin) -# - Open /views/sysadmin/backups.php -# - Click "Backup de uploads" — page reloads with success flash and polls until /backups/backup_DD_MM_YYYY_HH_MM_SS_xxxxxx.zip appears (ZIP contains only uploads/) -# - Click "Backup da base de dados" — same; db_backup_*.zip appears -# - Click the download icon on a row — browser downloads the ZIP -# - On the upstream platform-tools repo: edit a comment, push -# - On the platform: `git submodule update --remote && git -C shared/platform-tools log -1` -# → confirm new commit + visible on the page +# 4. In the browser, as sysadmin +# - Sistema lists every routed tool plus the site's own cards +# - Atualizar plataforma: git state (branch, SHA, history), "Verificar atualizações", pending migrations, +# "Exportar esquema" twice → `git diff database/schema.sql` shows no change the second time (determinism) +# - Backups: "Backup da base de dados" → db_backup_*.zip appears; the download icon downloads it +# - Integração com o hub: paired, and the hub card shows the checks (incl. security and conformance) ``` diff --git a/shared/platform-tools/VENDORED.md b/shared/platform-tools/VENDORED.md index 17ab67f..861e345 100644 --- a/shared/platform-tools/VENDORED.md +++ b/shared/platform-tools/VENDORED.md @@ -4,9 +4,13 @@ This directory used to be a git submodule pointing at `git.andmore.pt/andre/platform-tools`. On the `main` branch it is a plain directory of tracked files. -**Frozen at:** `ea3616abae30106df283e73a3e2f9e5bb0e6ae90` -(`feat: o feedback passa a servir os três stacks da frota` — the same commit -`fotografia.andmore.pt` pins.) +**Frozen at:** `12f26fd1cba8ce3229c598ac2f2e9a788cd7cf75` (`fix(client_ip): X-Real-IP / último X-Forwarded-For, nunca o primeiro`) +— refreshed on 2026-09-25 from `ea3616a`, 27 commits later. It is the fleet +pin (`f761d99`, audit module) plus `a8c681b` (login form pieces, remember +options) and the client-IP fix found in this app's audit. + +History: `ea3616a` (2026-09-13, same pin as fotografia at the time) → +`12f26fd` (2026-09-25). ## Why diff --git a/shared/platform-tools/api/agent.php b/shared/platform-tools/api/agent.php index ed81a58..d75944e 100644 --- a/shared/platform-tools/api/agent.php +++ b/shared/platform-tools/api/agent.php @@ -6,9 +6,8 @@ // dirname(__DIR__, 3) === // The per-platform stub at /api/agent.php is a one-line require of this file. // -// Hosts on a different stack (surf: src/ + App\Database) write their own thin -// stub that bootstraps their way and calls agent_dispatch() directly — the -// action set lives in functions_agent.php so both paths share it. +// The action set lives in functions_agent.php, so a host that needs its own +// stub (surf sets MIGRATIONS_DIR first) still shares it. $repo_root = dirname(__DIR__, 3); require_once $repo_root . '/config/db.php'; // opens $pdo, starts the session diff --git a/shared/platform-tools/api/feedback.php b/shared/platform-tools/api/feedback.php index bad3f81..b98cb98 100644 --- a/shared/platform-tools/api/feedback.php +++ b/shared/platform-tools/api/feedback.php @@ -8,9 +8,8 @@ // Ao contrário dos outros endpoints desta pasta, este NÃO se autentica por // chave: quem chama é o browser de um administrador com sessão aberta neste // site. Precisa por isso da sessão e dos helpers de autenticação do site — e -// obtém-nos do mesmo hub_bootstrap.php que os outros, que é quem sabe distinguir -// os dois stacks da frota (config/db.php ou src/config.php + App\Database) e -// deixa em cima da mesa a sessão aberta, o $pdo e o functions_hub. +// obtém-nos do mesmo hub_bootstrap.php que os outros, que abre o config/db.php +// do site e deixa em cima da mesa a sessão aberta, o $pdo e o functions_hub. // // Assim o stub de cada site é uma linha, igual à dos restantes endpoints. // diff --git a/shared/platform-tools/api/hub_health.php b/shared/platform-tools/api/hub_health.php index 61f6852..482b17c 100644 --- a/shared/platform-tools/api/hub_health.php +++ b/shared/platform-tools/api/hub_health.php @@ -126,6 +126,22 @@ if ($git) $checks['git'] = $git; $backup = $hub_has_db_layer ? $health_check(fn() => hub_backup_check()) : []; if ($backup) $checks['backup'] = $backup; +// Envio de eventos de segurança ao hub. [] numa plataforma por emparelhar ou +// sem base de dados — não reportado, como os outros. +$security = !($pdo instanceof PDO) ? [] : $health_check(function () use ($pdo) { + require_once __DIR__ . '/../functions_security_events.php'; + return hub_security_check($pdo); +}); +if ($security) $checks['security'] = $security; + +// A base de dados tem a forma que o código partilhado espera? Reporta as avarias +// silenciosas (uma coluna em falta que desliga o throttle sem erro nenhum) — +// ver functions_connector.php. Só leitura, uma consulta ao information_schema. +if ($pdo instanceof PDO) $checks['conformance'] = $health_check(function () use ($pdo) { + require_once __DIR__ . '/../functions_connector.php'; + return platform_conformance_check($pdo); +}); + hub_json([ // Só a base de dados: ver a nota no topo sobre o que significa `ok`. Numa // plataforma estática não há base de dados que decida nada -- o que torna a @@ -156,4 +172,9 @@ hub_json([ 'enabled' => true, 'auth' => 'X-Hub-Key: ', ], + // As páginas de sistema deste site, para o hub ligar para a página local + // (o recurso quando o hub não chega). Só com router: ver functions_routes.php. + 'tools' => function_exists('platform_routes_announced') ? platform_routes_announced() : [], + // E os endpoints pelo router da API — o caminho para endpoints novos. + 'api' => function_exists('platform_api_routes_announced') ? platform_api_routes_announced() : [], ]); diff --git a/shared/platform-tools/api/hub_ops.php b/shared/platform-tools/api/hub_ops.php index f1e9ae4..4c0299a 100644 --- a/shared/platform-tools/api/hub_ops.php +++ b/shared/platform-tools/api/hub_ops.php @@ -34,10 +34,20 @@ $root = $repo_root; // vez de deixar as ações chamarem métodos sobre um $pdo a null — um erro de PHP // apareceria no hub como plataforma avariada, que é uma coisa diferente. if (!$pdo instanceof PDO - && in_array($action, ['migrations.list', 'migrations.apply_pending'], true)) { + && in_array($action, ['migrations.list', 'migrations.apply_pending', 'update.run', 'update.status', + 'ip_bans.list', 'ip_bans.ban', 'ip_bans.unban', 'tracking.summary'], true)) { hub_json(['ok' => false, 'error' => 'plataforma sem base de dados — não há migrações a aplicar'], 400); } +// Auditoria: o que o hub mandou fazer aqui fica escrito, com o hub como autor. +// Só as ações que mudam alguma coisa; as leituras (list, status) não. +if ($pdo instanceof PDO && function_exists('platform_audit') + && in_array($action, ['backup.trigger', 'update.run', 'git.pull', 'migrations.apply_pending', 'ip_bans.ban', 'ip_bans.unban'], true)) { + $params = is_array($req) ? $req : $_POST; unset($params['action']); + platform_audit($pdo, 'hub.' . $action, ['actor' => ['id' => null, 'name' => 'hub', 'role' => 'hub'], + 'target_type' => 'platform', 'changes' => $params ?: null]); +} + switch ($action) { // ── Cópias de segurança ────────────────────────────────────────────────── @@ -91,9 +101,10 @@ switch ($action) { $output = $pull['output'] !== '' ? $pull['output'] : '(sem saída)'; if ($pull['ok']) { // O ff-only recusa-se a fundir; um repositório divergente falha aqui - // em vez de inventar um merge que ninguém pediu. - $sub = git_run(['submodule', 'update', '--init', '--recursive'], $root); - if (trim($sub['output']) !== '') $output .= "\n\n[submodules]\n" . $sub['output']; + // em vez de inventar um merge que ninguém pediu. Os submódulos vão + // pelo git_sync_submodules(), que respeita os que seguem o branch. + $sub = git_sync_submodules($root); + $output .= "\n\n[submodules]\n" . implode("\n", $sub['log']); if (function_exists('opcache_reset')) @opcache_reset(); if (function_exists('settings_cache_clear')) settings_cache_clear(); if (function_exists('platform_settings_cache_clear')) platform_settings_cache_clear(); @@ -101,6 +112,80 @@ switch ($action) { } hub_json(['ok' => $pull['ok'], 'output' => $output]); + // ── Atualização completa ───────────────────────────────────────────────── + // O mesmo caminho do webhook de deploy (auto_update_run): cópia antes de + // atualizar se estiver ligada, pull que pára em trabalho local, migrações + // pendentes e caches. É o que o botão do hub deve fazer — o git.pull acima + // fica para quem quer só o código. + // + // Responde já e trabalha depois de fechar a ligação: a cópia prévia pode + // demorar minutos e o hub só espera MONITOR_OPS_TIMEOUT_SECONDS. O + // resultado lê-se a seguir com update.status. + case 'update.run': + require_once __DIR__ . '/../functions_auto_update.php'; + hub_load_backup_helpers(); + if (!function_exists('git_run') || !is_dir($root . '/.git')) { + hub_json(['ok' => false, 'error' => 'esta instalação não é um repositório git (típico em cPanel) — as cópias continuam a funcionar'], 503); + } + @session_write_close(); + platform_respond_and_continue(202, [ + 'ok' => true, + 'status' => 'accepted', + 'note' => 'Atualização iniciada. O resultado fica em update.status daqui a instantes.', + ]); + auto_update_run($pdo, $root, null); + exit; + + case 'update.status': + require_once __DIR__ . '/../functions_auto_update.php'; + hub_json(['ok' => true, 'last' => auto_update_last($pdo)]); + + // ── Bloqueio de IP ─────────────────────────────────────────────────────── + // A mesma lista e as mesmas acções da página ip_bans.php deste site, para o + // hub mostrar numa aba. Um banimento feito daqui fica com source='hub' e, + // como qualquer outro, segue para a frota. + case 'ip_bans.list': + require_once __DIR__ . '/../functions_ip_ban.php'; + hub_json(['ok' => true, 'bans' => platform_ip_ban_list($pdo, 200), + 'offenders' => platform_ip_offenders($pdo, 7, 30)]); + + case 'ip_bans.ban': + case 'ip_bans.unban': + require_once __DIR__ . '/../functions_ip_ban.php'; + $ip = trim((string) (is_array($req) ? ($req['ip'] ?? '') : '')); + if (!filter_var($ip, FILTER_VALIDATE_IP)) { + hub_json(['ok' => false, 'error' => 'endereço IP inválido'], 400); + } + if ($action === 'ip_bans.unban') { + hub_json(['ok' => platform_ip_unban($pdo, $ip), 'ip' => $ip]); + } + if (platform_ip_ban_exempt($ip)) { + hub_json(['ok' => false, 'error' => 'endereços internos não podem ser banidos'], 400); + } + // `minutes: null` é permanente; ausente é um dia. + $minutes = array_key_exists('minutes', $req) && $req['minutes'] === null + ? null : max(1, (int) ($req['minutes'] ?? 1440)); + $reason = trim((string) ($req['reason'] ?? '')) ?: 'banido a partir do hub'; + $ok = platform_ip_ban($pdo, $ip, $reason, $minutes, 'hub', null); + hub_json(['ok' => $ok, 'ip' => $ip, 'minutes' => $minutes], $ok ? 200 : 500); + + // ── Origem das visitas ─────────────────────────────────────────────────── + // Só agregados — origens, formulários, países, dispositivos. Nenhuma visita + // individual sai daqui, nem o hash do IP. + case 'tracking.summary': + require_once __DIR__ . '/../functions_tracking.php'; + $days = (int) (is_array($req) ? ($req['days'] ?? 30) : 30); + if (!in_array($days, [7, 30, 90, 365], true)) $days = 30; + platform_tracking_ensure_tables($pdo); + hub_json([ + 'ok' => true, + 'days' => $days, + 'sources' => array_slice(platform_tracking_report($pdo, $days), 0, 25), + 'forms' => platform_tracking_conversions_by_form($pdo, $days), + 'countries' => platform_tracking_breakdown($pdo, 'country', $days, 10), + 'devices' => platform_tracking_breakdown($pdo, 'device_type', $days, 6), + ]); + // ── Migrações ──────────────────────────────────────────────────────────── // Um pull sem as migrações aplicadas deixa a app a correr contra um esquema // antigo, portanto o hub tem de conseguir fazer as duas coisas. diff --git a/shared/platform-tools/api/router.php b/shared/platform-tools/api/router.php new file mode 100644 index 0000000..85c4b5b --- /dev/null +++ b/shared/platform-tools/api/router.php @@ -0,0 +1,36 @@ + (ou +// api/platform?endpoint=… com 'clean_urls'). A lista é fechada +// (platform_api_routes()), e cada endpoint continua a autenticar-se a si +// próprio: este ficheiro só carrega o arranque do site e despacha. +// +// Um site com implementação própria de um endpoint declara-a no +// platform_connect(): 'api_files' => ['backup_trigger' => ] +// (a silver tem guardas com outros nomes). O 'migrations_dir' do site chega ao +// agente, como chega às páginas. + +declare(strict_types=1); + +require_once __DIR__ . '/../hub_bootstrap.php'; // $repo_root, $pdo, o arranque do site +require_once __DIR__ . '/../functions_routes.php'; + +$endpoint = (string) ($_GET['endpoint'] ?? ''); +$file = platform_api_routes()[$endpoint] ?? null; +if ($file === null) { + hub_json(['ok' => false, 'error' => 'endpoint desconhecido'], 404); +} + +$cfg = function_exists('platform_config') ? platform_config() : []; +if (!empty($cfg['migrations_dir'])) { + $GLOBALS['MIGRATIONS_DIR'] = (string) $cfg['migrations_dir']; +} +$target = (string) ($cfg['api_files'][$endpoint] ?? (dirname(__DIR__) . '/' . $file)); +unset($cfg, $file); + +require $target; diff --git a/shared/platform-tools/audit.php b/shared/platform-tools/audit.php new file mode 100644 index 0000000..43d8e8c --- /dev/null +++ b/shared/platform-tools/audit.php @@ -0,0 +1,154 @@ + trim((string) ($_GET['actor'] ?? '')), + 'action' => trim((string) ($_GET['action'] ?? '')), + 'target_type' => trim((string) ($_GET['target_type'] ?? '')), + 'target_id' => trim((string) ($_GET['target_id'] ?? '')), + 'q' => trim((string) ($_GET['q'] ?? '')), + 'from' => preg_match('/^\d{4}-\d{2}-\d{2}$/', (string) ($_GET['from'] ?? '')) ? (string) $_GET['from'] : '', + 'to' => preg_match('/^\d{4}-\d{2}-\d{2}$/', (string) ($_GET['to'] ?? '')) ? (string) $_GET['to'] : '', +]; +$perPage = 50; +$page = max(1, (int) ($_GET['p'] ?? 1)); + +// Exportação: o filtro inteiro (até 5000 linhas), em CSV que o Excel abre em pt. +if (($_GET['export'] ?? '') === 'csv') { + $rows = platform_audit_query($pdo, $filters, 5000); + header('Content-Type: text/csv; charset=utf-8'); + header('Content-Disposition: attachment; filename="auditoria-' . date('Y-m-d') . '.csv"'); + $out = fopen('php://output', 'w'); + fwrite($out, "\xEF\xBB\xBF"); + fputcsv($out, ['Quando', 'Quem', 'Papel', 'Ação', 'Tipo', 'Id', 'Alvo', 'Resumo', 'Alterações', 'IP'], ';'); + foreach ($rows as $r) { + fputcsv($out, [$r['created_at'], $r['actor_name'], $r['actor_role'], $r['action'], $r['target_type'], + $r['target_id'], $r['target_label'], $r['summary'], $r['changes'], $r['ip']], ';'); + } + fclose($out); + exit; +} + +$rows = platform_audit_query($pdo, $filters, $perPage + 1, ($page - 1) * $perPage); +$hasNext = count($rows) > $perPage; +$rows = array_slice($rows, 0, $perPage); +$actions = platform_audit_distinct($pdo, 'action'); +$types = platform_audit_distinct($pdo, 'target_type'); + +$selfUrl = strtok((string) ($_SERVER['REQUEST_URI'] ?? ''), '?') ?: ''; +$link = function (array $q) use ($selfUrl, $filters): string { + $base = isset($_GET['tool']) ? ['tool' => (string) $_GET['tool']] : []; + return $selfUrl . '?' . http_build_query($base + array_filter($q + $filters, fn($v) => $v !== '' && $v !== null)); +}; + +/** Uma alteração em HTML: tabela campo / antes / depois, ou o texto tal como veio. */ +$renderChanges = function (?string $json): string { + if ($json === null || $json === '') return ''; + $data = json_decode($json, true); + if (!is_array($data)) return '
    ' . htmlspecialchars($json) . '
    '; + $fmt = fn($v) => $v === null ? '—' + : htmlspecialchars(is_scalar($v) ? (string) $v : json_encode($v, JSON_UNESCAPED_UNICODE)); + $isDiff = $data && array_reduce($data, fn($ok, $v) => $ok && is_array($v) && (array_key_exists('from', $v) || array_key_exists('to', $v)), true); + if (!$isDiff) return '
    ' . htmlspecialchars(json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE)) . '
    '; + $h = ''; + foreach ($data as $k => $v) { + $h .= ''; + } + return $h . '
    CampoAntesDepois
    ' . htmlspecialchars((string) $k) . '' . $fmt($v['from'] ?? null) . '' . $fmt($v['to'] ?? null) . '
    '; +}; + +$layout_header = $platform_layout_header ?? ($repo_root . '/includes/header.php'); +$layout_navbar = $platform_layout_navbar ?? ($repo_root . '/includes/navbar.php'); +$layout_footer = $platform_layout_footer ?? ($repo_root . '/includes/footer.php'); +$dashboard_url = $platform_dashboard_url ?? (function_exists('platform_admin_url') ? platform_admin_url('index.php') : 'index.php'); + +$pageTitle = 'Registo de auditoria'; +if (is_file($layout_header)) include $layout_header; +if (is_file($layout_navbar)) include $layout_navbar; +?> +
    +
    +
    +

    Registo de auditoria

    +

    Quem fez o quê, a quê e quando. Os segredos nunca entram no registo.

    +
    +
    + Exportar CSV + Voltar +
    +
    + +
    + +
    +
    +
    +
    + +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    + + Limpar +
    +
    +
    + +
    +
    + + + + + + + + + + + + + + + +
    QuandoQuemAçãoAlvoResumoIP
    Nada no registo com este filtro.
    sistema' ?> +
    		+ +
    +     		+ + +
    alterações
    + +
    +
    + 1 || $hasNext): ?> +
    + 1): ?>← Mais recentes + página + Mais antigas → +
    + +
    +
    + diff --git a/shared/platform-tools/backups.php b/shared/platform-tools/backups.php index fe3d083..1f75dfb 100644 --- a/shared/platform-tools/backups.php +++ b/shared/platform-tools/backups.php @@ -37,6 +37,7 @@ if ($_SERVER['REQUEST_METHOD'] === 'POST' && ($_POST['action'] ?? '') === 'delet || !str_starts_with($real, $dir . DIRECTORY_SEPARATOR)) { $_SESSION['backup_flash'] = ['type' => 'danger', 'message' => 'Ficheiro inválido.']; } elseif (@unlink($real)) { + if (function_exists('platform_audit')) platform_audit($pdo ?? null, 'backup.delete', ['target_type' => 'backup', 'target_label' => $fn]); $_SESSION['backup_flash'] = ['type' => 'success', 'message' => "Backup {$fn} apagado."]; } else { $_SESSION['backup_flash'] = ['type' => 'danger', 'message' => "Não foi possível apagar {$fn} (permissões?)."]; @@ -80,7 +81,7 @@ if ($_SERVER['REQUEST_METHOD'] === 'POST' && ($_POST['action'] ?? '') === 'resto } elseif ($info['type'] === 'db' && !isset($pdo)) { $_SESSION['backup_flash'] = [ 'type' => 'danger', - 'message' => 'Restauro da base de dados indisponível: $pdo não foi carregado pelo stub.', + 'message' => 'Restauro da base de dados indisponível: o arranque do site (config/db.php) não abriu a ligação à base de dados.', ]; } else { $r = ($info['type'] === 'db') @@ -295,7 +296,8 @@ if (is_file($layout_navbar)) include $layout_navbar;
    - Os backups com mais de dias são eliminados automaticamente. + Retenção automática, por tipo: . + O resto é apagado no fim de cada backup. Os ficheiros estão armazenados na pasta backups/ no servidor.
    diff --git a/shared/platform-tools/backups/backup_maker.php b/shared/platform-tools/backups/backup_maker.php index 575ac3c..b95dbfe 100644 --- a/shared/platform-tools/backups/backup_maker.php +++ b/shared/platform-tools/backups/backup_maker.php @@ -182,4 +182,4 @@ echo "Ficheiro : $outputPath\n"; echo "Tamanho : $size\n"; echo "Ficheiros: $added adicionados, $skipped ignorados" . ($errors ? ", $errors erros" : '') . "\n"; -cleanOldBackups($backupDir, 'backup_*.zip'); +backup_prune_report(); diff --git a/shared/platform-tools/backups/config.php b/shared/platform-tools/backups/config.php index 0ed5e71..b7cb6c6 100644 --- a/shared/platform-tools/backups/config.php +++ b/shared/platform-tools/backups/config.php @@ -13,9 +13,9 @@ $host_root = dirname(__DIR__, 3); // Three host patterns coexist: // - fotografia-style : config/env.php exposes env_load(), needs an explicit call // - dsa/moremio-style: config/env.php auto-loads .env via an IIFE; require is enough -// - surf-style : no config/ directory at all -- src/config.php plus -// vlucas/phpdotenv, which has already populated $_ENV and -// getenv() by the time a web request reaches here. +// - surf-style : no config/env.php -- config/db.php loads .env with +// vlucas/phpdotenv, and the workers run without it, so +// they read .env themselves (the fallback below). // Requiring config/env.php unconditionally fataled on the third layout. if (is_file($host_root . '/config/env.php')) { require_once $host_root . '/config/env.php'; @@ -51,7 +51,10 @@ if (!function_exists('env')) { } define('BACKUP_TOKEN', env('BACKUP_TOKEN', 'replace_me')); -define('BACKUP_KEEP_DAYS', (int) env('BACKUP_KEEP_DAYS', 7)); +// Retenção avô-pai-filho — ver backup_gfs_keep() em functions_backup.php. +define('BACKUP_KEEP_DAYS', (int) env('BACKUP_KEEP_DAYS', 7)); +define('BACKUP_KEEP_WEEKS', (int) env('BACKUP_KEEP_WEEKS', 4)); +define('BACKUP_KEEP_MONTHS', (int) env('BACKUP_KEEP_MONTHS', 1)); // Pasta (relativa à raiz do host) que o backup de ficheiros arquiva. Só os // uploads têm informação externa — todo o resto é reconstituível a partir do @@ -68,28 +71,12 @@ define('DB_USER', env('DB_USER', '')); define('DB_PASS', env('DB_PASS', '')); define('DB_CHARSET', 'utf8mb4'); -/** - * Apaga backups mais antigos que BACKUP_KEEP_DAYS na pasta indicada. - * $pattern — glob pattern para identificar os ficheiros (ex: 'backup_*.zip') - */ -function cleanOldBackups(string $dir, string $pattern): void +/** Poda avô-pai-filho no fim de um worker (ver backup_prune()), com o relatório no output. */ +function backup_prune_report(): void { - $cutoff = time() - (BACKUP_KEEP_DAYS * 86400); - $files = glob($dir . '/' . $pattern) ?: []; - $deleted = 0; - - foreach ($files as $file) { - if (filemtime($file) < $cutoff) { - if (@unlink($file)) { - $deleted++; - echo "Apagado (antigo): " . basename($file) . "\n"; - } - } - } - - if ($deleted === 0) { - echo "Rotação: nenhum backup antigo para apagar.\n"; - } else { - echo "Rotação: $deleted ficheiro(s) apagado(s).\n"; - } + $r = backup_prune(); + foreach ($r['deleted'] as $f) echo "Apagado (retenção): $f\n"; + foreach ($r['errors'] as $f) echo "ERRO a apagar: $f\n"; + echo 'Rotação: ' . count($r['deleted']) . ' apagado(s), ' . count($r['kept']) . ' mantido(s) — ' + . backup_retention_summary($r['policy']) . ".\n"; } diff --git a/shared/platform-tools/backups/db_backup.php b/shared/platform-tools/backups/db_backup.php index a856171..bb13507 100644 --- a/shared/platform-tools/backups/db_backup.php +++ b/shared/platform-tools/backups/db_backup.php @@ -182,6 +182,6 @@ echo "Backup da BD concluído!\n"; echo "Ficheiro : $zipPath\n"; echo "Tamanho : $size\n"; -cleanOldBackups($backupDir, 'db_backup_*.zip'); -// Varre também .sql órfãos de execuções antigas interrompidas a meio. -cleanOldBackups($backupDir, 'db_backup_*.sql'); +// Só se chega aqui com a cópia nova no disco: a poda nunca corre depois de uma +// cópia falhada, que é quando as antigas são as únicas que há. +backup_prune_report(); diff --git a/shared/platform-tools/bin/backup-prune.php b/shared/platform-tools/bin/backup-prune.php new file mode 100644 index 0000000..eb903df --- /dev/null +++ b/shared/platform-tools/bin/backup-prune.php @@ -0,0 +1,30 @@ +query('SELECT DATABASE()')->fetchColumn(); if ($expected !== '' && $actual !== $expected) { diff --git a/shared/platform-tools/bin/geo-relay-update.sh b/shared/platform-tools/bin/geo-relay-update.sh new file mode 100644 index 0000000..1dc9d73 --- /dev/null +++ b/shared/platform-tools/bin/geo-relay-update.sh @@ -0,0 +1,100 @@ +#!/usr/bin/env bash +# +# Refresh the iCloud Private Relay egress ranges that functions_geo.php reads. +# +# geo-relay-update.sh pt # one or more ISO country codes +# geo-relay-update.sh # falls back to $GEO_ALLOW_COUNTRIES +# +# Why this exists: Private Relay sends Safari traffic out through Apple's egress +# addresses, which are registered where Apple registered them and not where the +# person is. Against the ipdeny lists a subscriber in Aveiro looks foreign, gets +# refused, and never hears back. Apple publishes which country each egress range +# serves, so the gate can ask the right question about it. +# +# It writes relay-.v4 / relay-.v6 — same format as the ipdeny lists, read +# by the same code. **Only the countries you ask for**, and that is the point: +# the published list is 42k IPv4 ranges and 246k IPv6 (855 KB and 6.7 MB), while +# Portugal is 611 of them. The whole file would be a 6.7 MB commit every week and +# a 6.7 MB parse on every request, to answer a question about one country. +# +# Keeping it per-country is also what stops this becoming a Relay whitelist: a +# range serving France is simply never written, so a French relay user is +# refused by the normal path exactly like any other foreign address. +# +# Apple adds ranges as it adds capacity, so weekly is reasonable: +# +# 23 4 * * 1 /srv/sites//shared/platform-tools/bin/geo-relay-update.sh pt +# +# The files are committed, same as the ipdeny data and for the same reason: a +# deploy on a box that cannot reach Apple still has working data — as current as +# the last commit. + +set -euo pipefail + +DATA_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/data/geo" +URL="${ICLOUD_RELAY_URL:-https://mask-api.icloud.com/egress-ip-ranges.csv}" + +# Apple serves relay capacity for a country from at least a few dozen ranges. +# Fewer than this means the country code was wrong, the format changed, or the +# download was truncated — and overwriting a good file with it would quietly +# turn every relay visitor back into a foreigner. +MIN_ROWS=10 + +countries=("$@") +if [ ${#countries[@]} -eq 0 ]; then + read -r -a countries <<< "${GEO_ALLOW_COUNTRIES//[,;]/ }" +fi +if [ ${#countries[@]} -eq 0 ]; then + echo "uso: $(basename "$0") [cc...] (ou defina GEO_ALLOW_COUNTRIES)" >&2 + exit 2 +fi + +tmp="$(mktemp -d)" +trap 'rm -rf "$tmp"' EXIT + +echo "iCloud Private Relay: a descarregar $URL" +if ! curl -fsS --max-time 60 "$URL" -o "$tmp/raw.csv"; then + echo "FALHOU o download — os ficheiros anteriores mantêm-se." >&2 + exit 1 +fi + +failed=0 +for cc in "${countries[@]}"; do + cc="$(echo "$cc" | tr '[:upper:]' '[:lower:]')" + [ -n "$cc" ] || continue + up="$(echo "$cc" | tr '[:lower:]' '[:upper:]')" + + # O formato da Apple é: cidr,countryCode,region,city, — só as duas + # primeiras colunas interessam, e uma linha que não seja exactamente isso é + # descartada em vez de adivinhada: uma mudança de formato tem de aparecer + # como "poucas gamas" e parar o script, não como um ficheiro meio lido. + awk -F',' -v want="$up" ' + $1 ~ /\// && toupper($2) == want { + if ($1 ~ /:/) { print $1 > v6 } else { print $1 > v4 } + } + ' v4="$tmp/$cc.v4" v6="$tmp/$cc.v6" "$tmp/raw.csv" || true + touch "$tmp/$cc.v4" "$tmp/$cc.v6" + + rows4=$(wc -l < "$tmp/$cc.v4" | tr -d ' ') + rows6=$(wc -l < "$tmp/$cc.v6" | tr -d ' ') + total=$((rows4 + rows6)) + + if [ "$total" -lt "$MIN_ROWS" ]; then + echo "FALHOU $up: só $total gamas (mínimo $MIN_ROWS). Ficheiros anteriores mantidos." >&2 + failed=1 + continue + fi + + # Ordenados no disco para um git diff entre duas actualizações se conseguir + # ler. O módulo volta a ordená-los ao carregar, porque esta ordem é textual + # e a procura precisa da ordem dos bytes empacotados. + sort -u "$tmp/$cc.v4" -o "$tmp/$cc.v4" + sort -u "$tmp/$cc.v6" -o "$tmp/$cc.v6" + + mkdir -p "$DATA_DIR" + mv "$tmp/$cc.v4" "$DATA_DIR/relay-$cc.v4" + mv "$tmp/$cc.v6" "$DATA_DIR/relay-$cc.v6" + echo "OK $up: $rows4 gamas IPv4, $rows6 IPv6 → $DATA_DIR/relay-$cc.{v4,v6}" +done + +exit "$failed" diff --git a/shared/platform-tools/bin/hub-security-sync.php b/shared/platform-tools/bin/hub-security-sync.php new file mode 100644 index 0000000..d37073b --- /dev/null +++ b/shared/platform-tools/bin/hub-security-sync.php @@ -0,0 +1,29 @@ + true, 'skipped' => 'plataforma sem base de dados']), "\n"; + exit(0); +} + +$res = hub_security_sync($pdo, 50); +echo json_encode($res, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n"; +exit(!empty($res['ok']) ? 0 : 1); diff --git a/shared/platform-tools/data/countries-pt.php b/shared/platform-tools/data/countries-pt.php new file mode 100644 index 0000000..44ac03c --- /dev/null +++ b/shared/platform-tools/data/countries-pt.php @@ -0,0 +1,100 @@ + [ + 'PT' => 'Portugal', + 'ES' => 'Espanha', + 'FR' => 'França', + 'GB' => 'Reino Unido', + 'CH' => 'Suíça', + 'LU' => 'Luxemburgo', + 'DE' => 'Alemanha', + 'BR' => 'Brasil', + ], + 'Resto da Europa' => [ + 'AD' => 'Andorra', + 'AL' => 'Albânia', + 'AT' => 'Áustria', + 'BA' => 'Bósnia e Herzegovina', + 'BE' => 'Bélgica', + 'BG' => 'Bulgária', + 'BY' => 'Bielorrússia', + 'CY' => 'Chipre', + 'CZ' => 'Chéquia', + 'DK' => 'Dinamarca', + 'EE' => 'Estónia', + 'FI' => 'Finlândia', + 'GI' => 'Gibraltar', + 'GR' => 'Grécia', + 'HR' => 'Croácia', + 'HU' => 'Hungria', + 'IE' => 'Irlanda', + 'IS' => 'Islândia', + 'IT' => 'Itália', + 'LI' => 'Listenstaine', + 'LT' => 'Lituânia', + 'LV' => 'Letónia', + 'MC' => 'Mónaco', + 'MD' => 'Moldávia', + 'ME' => 'Montenegro', + 'MK' => 'Macedónia do Norte', + 'MT' => 'Malta', + 'NL' => 'Países Baixos', + 'NO' => 'Noruega', + 'PL' => 'Polónia', + 'RO' => 'Roménia', + 'RS' => 'Sérvia', + 'RU' => 'Rússia', + 'SE' => 'Suécia', + 'SI' => 'Eslovénia', + 'SK' => 'Eslováquia', + 'SM' => 'São Marinho', + 'UA' => 'Ucrânia', + 'VA' => 'Vaticano', + ], + 'Língua portuguesa' => [ + 'AO' => 'Angola', + 'CV' => 'Cabo Verde', + 'GQ' => 'Guiné Equatorial', + 'GW' => 'Guiné-Bissau', + 'MO' => 'Macau', + 'MZ' => 'Moçambique', + 'ST' => 'São Tomé e Príncipe', + 'TL' => 'Timor-Leste', + ], + 'Fora da Europa' => [ + 'AE' => 'Emirados Árabes Unidos', + 'AR' => 'Argentina', + 'AU' => 'Austrália', + 'CA' => 'Canadá', + 'CL' => 'Chile', + 'CN' => 'China', + 'CO' => 'Colômbia', + 'IL' => 'Israel', + 'IN' => 'Índia', + 'JP' => 'Japão', + 'MA' => 'Marrocos', + 'MX' => 'México', + 'NZ' => 'Nova Zelândia', + 'TR' => 'Turquia', + 'US' => 'Estados Unidos', + 'VE' => 'Venezuela', + 'ZA' => 'África do Sul', + ], +]; diff --git a/shared/platform-tools/data/geo/relay-pt.v4 b/shared/platform-tools/data/geo/relay-pt.v4 new file mode 100644 index 0000000..3ed2b3b --- /dev/null +++ b/shared/platform-tools/data/geo/relay-pt.v4 @@ -0,0 +1,76 @@ +104.28.136.119/32 +104.28.136.120/32 +104.28.138.54/32 +104.28.138.55/32 +104.28.139.148/32 +104.28.139.149/32 +104.28.143.15/32 +104.28.146.45/32 +104.28.146.46/32 +104.28.146.47/32 +104.28.146.48/32 +104.28.146.49/32 +104.28.34.141/32 +104.28.34.142/32 +104.28.34.143/32 +104.28.34.144/32 +104.28.42.78/32 +104.28.42.79/32 +104.28.53.18/32 +104.28.53.19/32 +104.28.86.43/32 +104.28.86.44/32 +104.28.87.85/32 +104.28.87.86/32 +104.28.87.87/32 +104.28.87.88/32 +104.28.88.103/32 +104.28.88.104/32 +104.28.88.105/32 +104.28.88.106/32 +104.28.96.131/32 +104.28.96.132/32 +140.248.40.172/31 +140.248.40.174/31 +140.248.40.176/31 +140.248.40.178/31 +146.75.168.156/31 +146.75.168.158/31 +146.75.168.160/31 +146.75.168.162/31 +146.75.182.52/31 +146.75.182.54/31 +146.75.182.56/31 +146.75.182.58/31 +146.75.185.156/31 +146.75.185.158/31 +146.75.185.160/31 +146.75.185.162/31 +146.75.210.52/31 +146.75.210.54/31 +146.75.210.56/31 +146.75.210.58/31 +172.225.158.178/31 +172.225.158.180/30 +172.225.158.216/31 +172.225.159.64/28 +172.225.161.144/28 +172.225.162.192/28 +172.225.163.62/31 +172.225.163.80/30 +172.225.163.84/31 +172.225.178.176/28 +172.225.178.192/28 +172.225.179.50/31 +172.225.179.52/30 +172.225.179.64/31 +172.225.192.208/28 +172.225.193.58/31 +172.225.193.60/30 +172.225.193.64/31 +172.225.212.0/28 +172.225.212.16/30 +172.225.212.20/31 +172.225.212.22/31 +172.225.212.240/28 +172.225.243.64/28 diff --git a/shared/platform-tools/data/geo/relay-pt.v6 b/shared/platform-tools/data/geo/relay-pt.v6 new file mode 100644 index 0000000..3c6c0b6 --- /dev/null +++ b/shared/platform-tools/data/geo/relay-pt.v6 @@ -0,0 +1,535 @@ +2606:54c0:4fe8::/45 +2606:54c0:4ff0::/45 +2606:54c0:4ff8::/45 +2606:54c0:5000::/45 +2606:54c0:5008::/45 +2606:54c0:5010::/45 +2606:54c3:0:1152::/64 +2606:54c3:0:132a::/64 +2606:54c3:0:16a0::/64 +2606:54c3:0:1992::/64 +2606:54c3:0:857::/64 +2606:54c3:0:ac1::/64 +2a02:26f7:cb00:4000::/64 +2a02:26f7:cb00:400::/56 +2a02:26f7:cb00:500::/58 +2a02:26f7:cb00:5280::/64 +2a02:26f7:cb00:5281::/64 +2a02:26f7:cb00:5282::/64 +2a02:26f7:cb00:5283::/64 +2a02:26f7:cb00:5284::/64 +2a02:26f7:cb00:5285::/64 +2a02:26f7:cb00:5286::/64 +2a02:26f7:cb00:5287::/64 +2a02:26f7:cb00:5288::/64 +2a02:26f7:cb00:5289::/64 +2a02:26f7:cb00:528a::/64 +2a02:26f7:cb00:528b::/64 +2a02:26f7:cb00:528c::/64 +2a02:26f7:cb00:528d::/64 +2a02:26f7:cb00:528e::/64 +2a02:26f7:cb00:528f::/64 +2a02:26f7:cb00:5290::/64 +2a02:26f7:cb00:5291::/64 +2a02:26f7:cb00:5292::/64 +2a02:26f7:cb00:5293::/64 +2a02:26f7:cb00:5294::/64 +2a02:26f7:cb00:5295::/64 +2a02:26f7:cb00:5296::/64 +2a02:26f7:cb00:5297::/64 +2a02:26f7:cb00:5298::/64 +2a02:26f7:cb00:5299::/64 +2a02:26f7:cb00:529a::/64 +2a02:26f7:cb00:529b::/64 +2a02:26f7:cb00:529c::/64 +2a02:26f7:cb00:529d::/64 +2a02:26f7:cb00:529e::/64 +2a02:26f7:cb00:529f::/64 +2a02:26f7:cb00:52a0::/64 +2a02:26f7:cb00:52a1::/64 +2a02:26f7:cb00:52a2::/64 +2a02:26f7:cb00:52a3::/64 +2a02:26f7:cb00:52a4::/64 +2a02:26f7:cb00:52a5::/64 +2a02:26f7:cb00:52a6::/64 +2a02:26f7:cb00:52a7::/64 +2a02:26f7:cb00:52a8::/64 +2a02:26f7:cb00:52a9::/64 +2a02:26f7:cb00:52aa::/64 +2a02:26f7:cb00:52ab::/64 +2a02:26f7:cb00:52ac::/64 +2a02:26f7:cb00:52ad::/64 +2a02:26f7:cb00:52ae::/64 +2a02:26f7:cb00:52af::/64 +2a02:26f7:cb00:52b0::/64 +2a02:26f7:cb00:52b1::/64 +2a02:26f7:cb00:52b2::/64 +2a02:26f7:cb00:52b3::/64 +2a02:26f7:cb00:52b4::/64 +2a02:26f7:cb00:52b5::/64 +2a02:26f7:cb00:52b6::/64 +2a02:26f7:cb00:52b7::/64 +2a02:26f7:cb00:52b8::/64 +2a02:26f7:cb00:52b9::/64 +2a02:26f7:cb00:52ba::/64 +2a02:26f7:cb00:52bb::/64 +2a02:26f7:cb00:52bc::/64 +2a02:26f7:cb00:52bd::/64 +2a02:26f7:cb00:52be::/64 +2a02:26f7:cb00:52bf::/64 +2a02:26f7:cb00:52c0::/64 +2a02:26f7:cb00:52c1::/64 +2a02:26f7:cb00:52c2::/64 +2a02:26f7:cb00:52c3::/64 +2a02:26f7:cb00:52c4::/64 +2a02:26f7:cb00:52c5::/64 +2a02:26f7:cb00:52c6::/64 +2a02:26f7:cb00:52c7::/64 +2a02:26f7:cb00:52c8::/64 +2a02:26f7:cb00:52c9::/64 +2a02:26f7:cb00:52ca::/64 +2a02:26f7:cb00:52cb::/64 +2a02:26f7:cb00:52cc::/64 +2a02:26f7:cb00:52cd::/64 +2a02:26f7:cb00:52ce::/64 +2a02:26f7:cb00:52cf::/64 +2a02:26f7:cb00:52d0::/64 +2a02:26f7:cb00:52d1::/64 +2a02:26f7:cb00:52d2::/64 +2a02:26f7:cb00:52d3::/64 +2a02:26f7:cb00:52d4::/64 +2a02:26f7:cb00:52d5::/64 +2a02:26f7:cb00:52d6::/64 +2a02:26f7:cb00:52d7::/64 +2a02:26f7:cb00:52d8::/64 +2a02:26f7:cb00:52d9::/64 +2a02:26f7:cb00::/54 +2a02:26f7:cb01:4000::/64 +2a02:26f7:cb02:4000::/64 +2a02:26f7:cb02:400::/56 +2a02:26f7:cb02:500::/58 +2a02:26f7:cb02:5280::/64 +2a02:26f7:cb02:5281::/64 +2a02:26f7:cb02:5282::/64 +2a02:26f7:cb02:5283::/64 +2a02:26f7:cb02:5284::/64 +2a02:26f7:cb02:5285::/64 +2a02:26f7:cb02:5286::/64 +2a02:26f7:cb02:5287::/64 +2a02:26f7:cb02:5288::/64 +2a02:26f7:cb02:5289::/64 +2a02:26f7:cb02:528a::/64 +2a02:26f7:cb02:528b::/64 +2a02:26f7:cb02:528c::/64 +2a02:26f7:cb02:528d::/64 +2a02:26f7:cb02:528e::/64 +2a02:26f7:cb02:528f::/64 +2a02:26f7:cb02:5290::/64 +2a02:26f7:cb02:5291::/64 +2a02:26f7:cb02:5292::/64 +2a02:26f7:cb02:5293::/64 +2a02:26f7:cb02:5294::/64 +2a02:26f7:cb02:5295::/64 +2a02:26f7:cb02:5296::/64 +2a02:26f7:cb02:5297::/64 +2a02:26f7:cb02:5298::/64 +2a02:26f7:cb02:5299::/64 +2a02:26f7:cb02:529a::/64 +2a02:26f7:cb02:529b::/64 +2a02:26f7:cb02:529c::/64 +2a02:26f7:cb02:529d::/64 +2a02:26f7:cb02:529e::/64 +2a02:26f7:cb02:529f::/64 +2a02:26f7:cb02:52a0::/64 +2a02:26f7:cb02:52a1::/64 +2a02:26f7:cb02:52a2::/64 +2a02:26f7:cb02:52a3::/64 +2a02:26f7:cb02:52a4::/64 +2a02:26f7:cb02:52a5::/64 +2a02:26f7:cb02:52a6::/64 +2a02:26f7:cb02:52a7::/64 +2a02:26f7:cb02:52a8::/64 +2a02:26f7:cb02:52a9::/64 +2a02:26f7:cb02:52aa::/64 +2a02:26f7:cb02:52ab::/64 +2a02:26f7:cb02:52ac::/64 +2a02:26f7:cb02:52ad::/64 +2a02:26f7:cb02:52ae::/64 +2a02:26f7:cb02:52af::/64 +2a02:26f7:cb02:52b0::/64 +2a02:26f7:cb02:52b1::/64 +2a02:26f7:cb02:52b2::/64 +2a02:26f7:cb02:52b3::/64 +2a02:26f7:cb02:52b4::/64 +2a02:26f7:cb02:52b5::/64 +2a02:26f7:cb02:52b6::/64 +2a02:26f7:cb02:52b7::/64 +2a02:26f7:cb02:52b8::/64 +2a02:26f7:cb02:52b9::/64 +2a02:26f7:cb02:52ba::/64 +2a02:26f7:cb02:52bb::/64 +2a02:26f7:cb02:52bc::/64 +2a02:26f7:cb02:52bd::/64 +2a02:26f7:cb02:52be::/64 +2a02:26f7:cb02:52bf::/64 +2a02:26f7:cb02:52c0::/64 +2a02:26f7:cb02:52c1::/64 +2a02:26f7:cb02:52c2::/64 +2a02:26f7:cb02:52c3::/64 +2a02:26f7:cb02:52c4::/64 +2a02:26f7:cb02:52c5::/64 +2a02:26f7:cb02:52c6::/64 +2a02:26f7:cb02:52c7::/64 +2a02:26f7:cb02:52c8::/64 +2a02:26f7:cb02:52c9::/64 +2a02:26f7:cb02:52ca::/64 +2a02:26f7:cb02:52cb::/64 +2a02:26f7:cb02:52cc::/64 +2a02:26f7:cb02:52cd::/64 +2a02:26f7:cb02:52ce::/64 +2a02:26f7:cb02:52cf::/64 +2a02:26f7:cb02:52d0::/64 +2a02:26f7:cb02:52d1::/64 +2a02:26f7:cb02:52d2::/64 +2a02:26f7:cb02:52d3::/64 +2a02:26f7:cb02:52d4::/64 +2a02:26f7:cb02:52d5::/64 +2a02:26f7:cb02:52d6::/64 +2a02:26f7:cb02:52d7::/64 +2a02:26f7:cb02:52d8::/64 +2a02:26f7:cb02:52d9::/64 +2a02:26f7:cb02::/54 +2a02:26f7:cb03:4000::/64 +2a02:26f7:cb04:4000::/64 +2a02:26f7:cb04:400::/56 +2a02:26f7:cb04:500::/58 +2a02:26f7:cb04:5280::/64 +2a02:26f7:cb04:5281::/64 +2a02:26f7:cb04:5282::/64 +2a02:26f7:cb04:5283::/64 +2a02:26f7:cb04:5284::/64 +2a02:26f7:cb04:5285::/64 +2a02:26f7:cb04:5286::/64 +2a02:26f7:cb04:5287::/64 +2a02:26f7:cb04:5288::/64 +2a02:26f7:cb04:5289::/64 +2a02:26f7:cb04:528a::/64 +2a02:26f7:cb04:528b::/64 +2a02:26f7:cb04:528c::/64 +2a02:26f7:cb04:528d::/64 +2a02:26f7:cb04:528e::/64 +2a02:26f7:cb04:528f::/64 +2a02:26f7:cb04:5290::/64 +2a02:26f7:cb04:5291::/64 +2a02:26f7:cb04:5292::/64 +2a02:26f7:cb04:5293::/64 +2a02:26f7:cb04:5294::/64 +2a02:26f7:cb04:5295::/64 +2a02:26f7:cb04:5296::/64 +2a02:26f7:cb04:5297::/64 +2a02:26f7:cb04:5298::/64 +2a02:26f7:cb04:5299::/64 +2a02:26f7:cb04:529a::/64 +2a02:26f7:cb04:529b::/64 +2a02:26f7:cb04:529c::/64 +2a02:26f7:cb04:529d::/64 +2a02:26f7:cb04:529e::/64 +2a02:26f7:cb04:529f::/64 +2a02:26f7:cb04:52a0::/64 +2a02:26f7:cb04:52a1::/64 +2a02:26f7:cb04:52a2::/64 +2a02:26f7:cb04:52a3::/64 +2a02:26f7:cb04:52a4::/64 +2a02:26f7:cb04:52a5::/64 +2a02:26f7:cb04:52a6::/64 +2a02:26f7:cb04:52a7::/64 +2a02:26f7:cb04:52a8::/64 +2a02:26f7:cb04:52a9::/64 +2a02:26f7:cb04:52aa::/64 +2a02:26f7:cb04:52ab::/64 +2a02:26f7:cb04:52ac::/64 +2a02:26f7:cb04:52ad::/64 +2a02:26f7:cb04:52ae::/64 +2a02:26f7:cb04:52af::/64 +2a02:26f7:cb04:52b0::/64 +2a02:26f7:cb04:52b1::/64 +2a02:26f7:cb04:52b2::/64 +2a02:26f7:cb04:52b3::/64 +2a02:26f7:cb04:52b4::/64 +2a02:26f7:cb04:52b5::/64 +2a02:26f7:cb04:52b6::/64 +2a02:26f7:cb04:52b7::/64 +2a02:26f7:cb04:52b8::/64 +2a02:26f7:cb04:52b9::/64 +2a02:26f7:cb04:52ba::/64 +2a02:26f7:cb04:52bb::/64 +2a02:26f7:cb04:52bc::/64 +2a02:26f7:cb04:52bd::/64 +2a02:26f7:cb04:52be::/64 +2a02:26f7:cb04:52bf::/64 +2a02:26f7:cb04:52c0::/64 +2a02:26f7:cb04:52c1::/64 +2a02:26f7:cb04:52c2::/64 +2a02:26f7:cb04:52c3::/64 +2a02:26f7:cb04:52c4::/64 +2a02:26f7:cb04:52c5::/64 +2a02:26f7:cb04:52c6::/64 +2a02:26f7:cb04:52c7::/64 +2a02:26f7:cb04:52c8::/64 +2a02:26f7:cb04:52c9::/64 +2a02:26f7:cb04:52ca::/64 +2a02:26f7:cb04:52cb::/64 +2a02:26f7:cb04:52cc::/64 +2a02:26f7:cb04:52cd::/64 +2a02:26f7:cb04:52ce::/64 +2a02:26f7:cb04:52cf::/64 +2a02:26f7:cb04:52d0::/64 +2a02:26f7:cb04:52d1::/64 +2a02:26f7:cb04:52d2::/64 +2a02:26f7:cb04:52d3::/64 +2a02:26f7:cb04:52d4::/64 +2a02:26f7:cb04:52d5::/64 +2a02:26f7:cb04:52d6::/64 +2a02:26f7:cb04:52d7::/64 +2a02:26f7:cb04:52d8::/64 +2a02:26f7:cb04:52d9::/64 +2a02:26f7:cb04::/54 +2a02:26f7:cb05:4000::/64 +2a02:26f7:cb0c:4000::/64 +2a02:26f7:cb0c:400::/56 +2a02:26f7:cb0c:500::/58 +2a02:26f7:cb0c:5280::/64 +2a02:26f7:cb0c:5281::/64 +2a02:26f7:cb0c:5282::/64 +2a02:26f7:cb0c:5283::/64 +2a02:26f7:cb0c:5284::/64 +2a02:26f7:cb0c:5285::/64 +2a02:26f7:cb0c:5286::/64 +2a02:26f7:cb0c:5287::/64 +2a02:26f7:cb0c:5288::/64 +2a02:26f7:cb0c:5289::/64 +2a02:26f7:cb0c:528a::/64 +2a02:26f7:cb0c:528b::/64 +2a02:26f7:cb0c:528c::/64 +2a02:26f7:cb0c:528d::/64 +2a02:26f7:cb0c:528e::/64 +2a02:26f7:cb0c:528f::/64 +2a02:26f7:cb0c:5290::/64 +2a02:26f7:cb0c:5291::/64 +2a02:26f7:cb0c:5292::/64 +2a02:26f7:cb0c:5293::/64 +2a02:26f7:cb0c:5294::/64 +2a02:26f7:cb0c:5295::/64 +2a02:26f7:cb0c:5296::/64 +2a02:26f7:cb0c:5297::/64 +2a02:26f7:cb0c:5298::/64 +2a02:26f7:cb0c:5299::/64 +2a02:26f7:cb0c:529a::/64 +2a02:26f7:cb0c:529b::/64 +2a02:26f7:cb0c:529c::/64 +2a02:26f7:cb0c:529d::/64 +2a02:26f7:cb0c:529e::/64 +2a02:26f7:cb0c:529f::/64 +2a02:26f7:cb0c:52a0::/64 +2a02:26f7:cb0c:52a1::/64 +2a02:26f7:cb0c:52a2::/64 +2a02:26f7:cb0c:52a3::/64 +2a02:26f7:cb0c:52a4::/64 +2a02:26f7:cb0c:52a5::/64 +2a02:26f7:cb0c:52a6::/64 +2a02:26f7:cb0c:52a7::/64 +2a02:26f7:cb0c:52a8::/64 +2a02:26f7:cb0c:52a9::/64 +2a02:26f7:cb0c:52aa::/64 +2a02:26f7:cb0c:52ab::/64 +2a02:26f7:cb0c:52ac::/64 +2a02:26f7:cb0c:52ad::/64 +2a02:26f7:cb0c:52ae::/64 +2a02:26f7:cb0c:52af::/64 +2a02:26f7:cb0c:52b0::/64 +2a02:26f7:cb0c:52b1::/64 +2a02:26f7:cb0c:52b2::/64 +2a02:26f7:cb0c:52b3::/64 +2a02:26f7:cb0c:52b4::/64 +2a02:26f7:cb0c:52b5::/64 +2a02:26f7:cb0c:52b6::/64 +2a02:26f7:cb0c:52b7::/64 +2a02:26f7:cb0c:52b8::/64 +2a02:26f7:cb0c:52b9::/64 +2a02:26f7:cb0c:52ba::/64 +2a02:26f7:cb0c:52bb::/64 +2a02:26f7:cb0c:52bc::/64 +2a02:26f7:cb0c:52bd::/64 +2a02:26f7:cb0c:52be::/64 +2a02:26f7:cb0c:52bf::/64 +2a02:26f7:cb0c:52c0::/64 +2a02:26f7:cb0c:52c1::/64 +2a02:26f7:cb0c:52c2::/64 +2a02:26f7:cb0c:52c3::/64 +2a02:26f7:cb0c:52c4::/64 +2a02:26f7:cb0c:52c5::/64 +2a02:26f7:cb0c:52c6::/64 +2a02:26f7:cb0c:52c7::/64 +2a02:26f7:cb0c:52c8::/64 +2a02:26f7:cb0c:52c9::/64 +2a02:26f7:cb0c:52ca::/64 +2a02:26f7:cb0c:52cb::/64 +2a02:26f7:cb0c:52cc::/64 +2a02:26f7:cb0c:52cd::/64 +2a02:26f7:cb0c:52ce::/64 +2a02:26f7:cb0c:52cf::/64 +2a02:26f7:cb0c:52d0::/64 +2a02:26f7:cb0c:52d1::/64 +2a02:26f7:cb0c:52d2::/64 +2a02:26f7:cb0c:52d3::/64 +2a02:26f7:cb0c:52d4::/64 +2a02:26f7:cb0c:52d5::/64 +2a02:26f7:cb0c:52d6::/64 +2a02:26f7:cb0c:52d7::/64 +2a02:26f7:cb0c:52d8::/64 +2a02:26f7:cb0c:52d9::/64 +2a02:26f7:cb0c::/54 +2a02:26f7:cb0d:4000::/64 +2a02:26f7:cb10:4000::/64 +2a02:26f7:cb10:400::/56 +2a02:26f7:cb10:500::/58 +2a02:26f7:cb10:5280::/64 +2a02:26f7:cb10:5281::/64 +2a02:26f7:cb10:5282::/64 +2a02:26f7:cb10:5283::/64 +2a02:26f7:cb10:5284::/64 +2a02:26f7:cb10:5285::/64 +2a02:26f7:cb10:5286::/64 +2a02:26f7:cb10:5287::/64 +2a02:26f7:cb10:5288::/64 +2a02:26f7:cb10:5289::/64 +2a02:26f7:cb10:528a::/64 +2a02:26f7:cb10:528b::/64 +2a02:26f7:cb10:528c::/64 +2a02:26f7:cb10:528d::/64 +2a02:26f7:cb10:528e::/64 +2a02:26f7:cb10:528f::/64 +2a02:26f7:cb10:5290::/64 +2a02:26f7:cb10:5291::/64 +2a02:26f7:cb10:5292::/64 +2a02:26f7:cb10:5293::/64 +2a02:26f7:cb10:5294::/64 +2a02:26f7:cb10:5295::/64 +2a02:26f7:cb10:5296::/64 +2a02:26f7:cb10:5297::/64 +2a02:26f7:cb10:5298::/64 +2a02:26f7:cb10:5299::/64 +2a02:26f7:cb10:529a::/64 +2a02:26f7:cb10:529b::/64 +2a02:26f7:cb10:529c::/64 +2a02:26f7:cb10:529d::/64 +2a02:26f7:cb10:529e::/64 +2a02:26f7:cb10:529f::/64 +2a02:26f7:cb10:52a0::/64 +2a02:26f7:cb10:52a1::/64 +2a02:26f7:cb10:52a2::/64 +2a02:26f7:cb10:52a3::/64 +2a02:26f7:cb10:52a4::/64 +2a02:26f7:cb10:52a5::/64 +2a02:26f7:cb10:52a6::/64 +2a02:26f7:cb10:52a7::/64 +2a02:26f7:cb10:52a8::/64 +2a02:26f7:cb10:52a9::/64 +2a02:26f7:cb10:52aa::/64 +2a02:26f7:cb10:52ab::/64 +2a02:26f7:cb10:52ac::/64 +2a02:26f7:cb10:52ad::/64 +2a02:26f7:cb10:52ae::/64 +2a02:26f7:cb10:52af::/64 +2a02:26f7:cb10:52b0::/64 +2a02:26f7:cb10:52b1::/64 +2a02:26f7:cb10:52b2::/64 +2a02:26f7:cb10:52b3::/64 +2a02:26f7:cb10:52b4::/64 +2a02:26f7:cb10:52b5::/64 +2a02:26f7:cb10:52b6::/64 +2a02:26f7:cb10:52b7::/64 +2a02:26f7:cb10:52b8::/64 +2a02:26f7:cb10:52b9::/64 +2a02:26f7:cb10:52ba::/64 +2a02:26f7:cb10:52bb::/64 +2a02:26f7:cb10:52bc::/64 +2a02:26f7:cb10:52bd::/64 +2a02:26f7:cb10:52be::/64 +2a02:26f7:cb10:52bf::/64 +2a02:26f7:cb10:52c0::/64 +2a02:26f7:cb10:52c1::/64 +2a02:26f7:cb10:52c2::/64 +2a02:26f7:cb10:52c3::/64 +2a02:26f7:cb10:52c4::/64 +2a02:26f7:cb10:52c5::/64 +2a02:26f7:cb10:52c6::/64 +2a02:26f7:cb10:52c7::/64 +2a02:26f7:cb10:52c8::/64 +2a02:26f7:cb10:52c9::/64 +2a02:26f7:cb10:52ca::/64 +2a02:26f7:cb10:52cb::/64 +2a02:26f7:cb10:52cc::/64 +2a02:26f7:cb10:52cd::/64 +2a02:26f7:cb10:52ce::/64 +2a02:26f7:cb10:52cf::/64 +2a02:26f7:cb10:52d0::/64 +2a02:26f7:cb10:52d1::/64 +2a02:26f7:cb10:52d2::/64 +2a02:26f7:cb10:52d3::/64 +2a02:26f7:cb10:52d4::/64 +2a02:26f7:cb10:52d5::/64 +2a02:26f7:cb10:52d6::/64 +2a02:26f7:cb10:52d7::/64 +2a02:26f7:cb10:52d8::/64 +2a02:26f7:cb10:52d9::/64 +2a02:26f7:cb10::/54 +2a02:26f7:cb11:4000::/64 +2a02:26f7:ed00:4000::/64 +2a02:26f7:ed00:cbc0::/64 +2a02:26f7:ed00:cbc1::/64 +2a02:26f7:ed01:4000::/64 +2a02:26f7:ed02:4000::/64 +2a02:26f7:ed02:cbc0::/64 +2a02:26f7:ed02:cbc1::/64 +2a02:26f7:ed03:4000::/64 +2a02:26f7:ed04:4000::/64 +2a02:26f7:ed04:cbc0::/64 +2a02:26f7:ed04:cbc1::/64 +2a02:26f7:ed05:4000::/64 +2a02:26f7:ed0c:4000::/64 +2a02:26f7:ed0c:cbc0::/64 +2a02:26f7:ed0c:cbc1::/64 +2a02:26f7:ed0d:4000::/64 +2a04:4e41:1303:5000::/52 +2a04:4e41:1303:6000::/52 +2a04:4e41:1303:7000::/52 +2a04:4e41:1324::/48 +2a04:4e41:1603:6000::/52 +2a04:4e41:1603:7000::/52 +2a04:4e41:1603:8000::/52 +2a04:4e41:161a::/48 +2a04:4e41:4100:8000::/52 +2a04:4e41:4100:9000::/52 +2a04:4e41:4100:a000::/52 +2a04:4e41:4112::/48 +2a04:4e41:7403:6000::/52 +2a04:4e41:7403:7000::/52 +2a04:4e41:7403:8000::/52 +2a04:4e41:741a::/48 +2a04:4e41:7800:8000::/52 +2a04:4e41:7800:9000::/52 +2a04:4e41:7800:a000::/52 +2a04:4e41:7812::/48 +2a09:bac2:4fe8::/45 +2a09:bac2:4ff0::/45 +2a09:bac2:4ff8::/45 +2a09:bac2:5000::/45 +2a09:bac2:5008::/45 +2a09:bac2:5010::/45 +2a09:bac3:4fe8::/45 +2a09:bac3:4ff0::/45 +2a09:bac3:4ff8::/45 +2a09:bac3:5000::/45 +2a09:bac3:5008::/45 +2a09:bac3:5010::/45 diff --git a/shared/platform-tools/feedback_widget.php b/shared/platform-tools/feedback_widget.php index 5e1f778..ae18636 100644 --- a/shared/platform-tools/feedback_widget.php +++ b/shared/platform-tools/feedback_widget.php @@ -76,7 +76,12 @@ require_once __DIR__ . '/functions_csrf.php'; // A página onde o sysadmin liga isto. Cada site tem a sua árvore de vistas, // daí poder ser sobreposta pelo layout antes do include. - $hubPage = (string) ($GLOBALS['platform_feedback_hub_url'] ?? '/views/sysadmin/hub_integration.php'); + // Num site com router (platform_connect(['router' => true])) é o endereço + // dele; o stub antigo só reencaminha. + $hubPage = (string) ($GLOBALS['platform_feedback_hub_url'] + ?? (function_exists('platform_router_enabled') && platform_router_enabled() + ? platform_route_url('hub_integration') + : '/views/sysadmin/hub_integration.php')); $inline = ($GLOBALS['platform_feedback_mode'] ?? 'bubble') === 'footer'; ?> diff --git a/shared/platform-tools/functions_antispam_forms.php b/shared/platform-tools/functions_antispam_forms.php index d81a64d..877b928 100644 --- a/shared/platform-tools/functions_antispam_forms.php +++ b/shared/platform-tools/functions_antispam_forms.php @@ -115,6 +115,13 @@ function platform_antispam_ident_ok(string $ident): bool * tabela de settings. Não é um segredo tão bom como os outros, mas é * constante — e uma defesa que tranca todos os formulários é pior do que * uma assinatura mais fraca. + * + * A mesma escada vive agora em platform_derived_key() (functions_settings.php), + * que é o que os módulos novos usam — o captcha, por exemplo. Esta cópia fica + * porque separa os domínios de outra maneira (ver o comentário lá dentro sobre + * a chave do ambiente) e porque trocá-la num site a correr invalida os + * formulários abertos nesse instante. Quem a converter faz uma janela que + * aceite as duas assinaturas antes de tirar a antiga. */ function platform_antispam_key(?PDO $pdo = null): string { @@ -195,8 +202,13 @@ function platform_antispam_trap_field(string $form = 'form', ?PDO $pdo = null): if (!$scriptPrinted) { $scriptPrinted = true; - $html .= ''; + // Corre já (o formulário que o imprime está acima) e outra vez quando a + // página acaba de carregar: o script sai uma vez só, junto ao PRIMEIRO + // formulário, e um segundo mais abaixo na mesma página ainda não existia + // quando ele correu — ficava sem a prova de JS (silver, 2026-09-23). + $html .= ''; } return $html; diff --git a/shared/platform-tools/functions_audit.php b/shared/platform-tools/functions_audit.php new file mode 100644 index 0000000..e85da04 --- /dev/null +++ b/shared/platform-tools/functions_audit.php @@ -0,0 +1,348 @@ + 'user', +// 'target_id' => 42, +// 'target_label' => 'Maria Silva', +// 'summary' => 'Enviada para a reciclagem', +// 'changes' => platform_audit_diff($antes, $depois), +// ]); +// +// Porque existe: a frota tinha TRÊS registos incompatíveis (hub, dance, quack, +// cada um com as suas colunas e a sua função) e cinco sites sem nenhum. O +// mesmo argumento do anti-spam e dos segredos — cópias não ficam iguais, +// ficam parecidas. +// +// ─── As tabelas que já existiam ───────────────────────────────────────────── +// +// Não se renomeia nada. O escritor LÊ as colunas da tabela do site +// (information_schema, uma vez por pedido) e escreve cada campo canónico na +// coluna que o site declarou para ele — `platform_connect(['audit' => ['map' => +// ['actor_id' => 'user_id', ...]]])`, como o `schema` da autenticação. Um campo +// sem coluna é simplesmente omitido; uma coluna NOT NULL sem valor por omissão +// recebe um vazio (a do quack, `summary`, rebentava o INSERT); os textos são +// cortados ao tamanho da coluna. As migrações de cada site acrescentam as +// colunas que faltam, e daí em diante nada se perde. +// +// Um site sem tabela recebe-a no primeiro uso, já na forma canónica +// (platform_audit_ensure_table()). +// +// ─── As regras ────────────────────────────────────────────────────────────── +// +// - **Nunca parte a ação.** Uma falha a escrever regista-se no error_log e o +// pedido segue: perde-se a linha, não a operação. +// - **Segredos nunca entram.** Qualquer chave de `changes` com cara de segredo +// (password, token, secret, key, hash, cookie, csrf) é substituída por +// «(oculto)», a qualquer profundidade. +// - **O autor vem da sessão**, em qualquer das formas da frota +// (current_user(), $_SESSION['user'], ou as chaves soltas do quack), e o IP é +// o verdadeiro (platform_client_ip()). Quem chama pode passar 'actor' quando +// sabe melhor — o hub a agir por ops, o webhook do deploy, o PIN do dance. + +require_once __DIR__ . '/functions_client_ip.php'; + +/** Os campos canónicos, e a definição de cada um numa tabela nova. */ +function platform_audit_columns(): array +{ + return [ + 'actor_id' => 'BIGINT UNSIGNED NULL', + 'actor_name' => 'VARCHAR(150) NULL', + 'actor_role' => 'VARCHAR(30) NULL', + 'action' => "VARCHAR(80) NOT NULL DEFAULT ''", + 'target_type' => "VARCHAR(60) NOT NULL DEFAULT ''", + 'target_id' => 'VARCHAR(64) NULL', + 'target_label' => 'VARCHAR(250) NULL', + 'summary' => 'VARCHAR(1000) NULL', + 'changes' => 'LONGTEXT NULL', + 'ip' => 'VARCHAR(45) NULL', + 'user_agent' => 'VARCHAR(255) NULL', + ]; +} + +/** Nome da tabela e mapa de colunas deste site (platform_connect 'audit'). */ +function platform_audit_config(): array +{ + $cfg = function_exists('platform_config') ? (array) (platform_config()['audit'] ?? []) : []; + return [ + 'table' => (string) ($cfg['table'] ?? 'audit_log'), + 'map' => (array) ($cfg['map'] ?? []), + // Dias que uma linha vive; 0 = para sempre. + 'keep_days' => (int) ($cfg['keep_days'] ?? 730), + ]; +} + +function platform_audit_ensure_table(PDO $pdo, string $table): void +{ + if (!preg_match('/^[A-Za-z0-9_]+$/', $table)) return; + $cols = ''; + foreach (platform_audit_columns() as $name => $def) $cols .= " `$name` $def,\n"; + $pdo->exec( + "CREATE TABLE IF NOT EXISTS `$table` ( + `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, + $cols `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY (`id`), + KEY `idx_audit_created` (`created_at`), + KEY `idx_audit_actor` (`actor_id`, `created_at`), + KEY `idx_audit_action` (`action`, `created_at`), + KEY `idx_audit_target` (`target_type`, `target_id`) + ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci" + ); +} + +/** + * As colunas reais da tabela: [nome => ['type' => …, 'max' => int|null, + * 'required' => bool]]. Uma consulta por pedido. Cria a tabela quando não há. + */ +function platform_audit_table_columns(PDO $pdo): array +{ + static $cache = []; + $table = platform_audit_config()['table']; + if (isset($cache[$table])) return $cache[$table]; + + $read = function () use ($pdo, $table): array { + $st = $pdo->prepare( + 'SELECT COLUMN_NAME, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH, IS_NULLABLE, COLUMN_DEFAULT, EXTRA + FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?' + ); + $st->execute([$table]); + $out = []; + foreach ($st->fetchAll(PDO::FETCH_ASSOC) as $c) { + $out[$c['COLUMN_NAME']] = [ + 'type' => strtolower((string) $c['DATA_TYPE']), + 'max' => $c['CHARACTER_MAXIMUM_LENGTH'] !== null ? (int) $c['CHARACTER_MAXIMUM_LENGTH'] : null, + 'required' => $c['IS_NULLABLE'] === 'NO' && $c['COLUMN_DEFAULT'] === null + && !str_contains((string) $c['EXTRA'], 'auto_increment'), + 'not_null' => $c['IS_NULLABLE'] === 'NO', + ]; + } + return $out; + }; + $cols = $read(); + if (!$cols) { + platform_audit_ensure_table($pdo, $table); + $cols = $read(); + } + return $cache[$table] = $cols; +} + +/** A coluna do site para um campo canónico (o mapa, ou o próprio nome). */ +function platform_audit_column(string $field): string +{ + return (string) (platform_audit_config()['map'][$field] ?? $field); +} + +/** + * Quem está a agir, a partir da sessão, em qualquer das formas da frota: + * current_user(), $_SESSION['user'], ou as chaves soltas user_id/username/role. + */ +function platform_audit_actor(): ?array +{ + $u = null; + if (function_exists('current_user')) { + try { $u = current_user(); } catch (Throwable) { $u = null; } + } + if (!is_array($u) && session_status() === PHP_SESSION_ACTIVE && is_array($_SESSION['user'] ?? null)) { + $u = $_SESSION['user']; + } + if (is_array($u) && !empty($u['id'])) { + return [ + 'id' => (int) $u['id'], + 'name' => (string) ($u['full_name'] ?? $u['name'] ?? $u['display_name'] ?? $u['username'] ?? $u['email'] ?? ''), + 'role' => (string) ($u['role'] ?? ''), + ]; + } + if (session_status() === PHP_SESSION_ACTIVE && !empty($_SESSION['user_id'])) { + return [ + 'id' => (int) $_SESSION['user_id'], + 'name' => (string) ($_SESSION['full_name'] ?? $_SESSION['username'] ?? ''), + 'role' => (string) ($_SESSION['role'] ?? ''), + ]; + } + return null; +} + +/** Tira os segredos de uma estrutura antes de ela ir para o registo. */ +function platform_audit_redact(mixed $v, string $key = ''): mixed +{ + if ($key !== '' && preg_match('/pass|token|secret|api_?key|ops_?key|hash|cookie|csrf|validator|pairing_code/i', $key)) { + // Oculta os valores mas mantém a forma: um {from, to} continua a ser um + // {from, to}, e a página continua a mostrá-lo como alteração. + if (is_array($v)) return array_map(fn($x) => ($x === null || $x === '') ? $x : '(oculto)', $v); + return ($v === null || $v === '') ? $v : '(oculto)'; + } + if (is_array($v)) { + $out = []; + foreach ($v as $k => $x) $out[$k] = platform_audit_redact($x, is_string($k) ? $k : $key); + return $out; + } + return $v; +} + +/** + * O que mudou entre duas versões de um registo: [campo => ['from' => …, 'to' => …]]. + * Compara como texto, para um '1' da base de dados e um 1 do formulário não + * contarem como mudança. $ignore: campos a não comparar (updated_at, …). + */ +function platform_audit_diff(array $before, array $after, array $ignore = ['updated_at', 'created_at']): array +{ + $out = []; + foreach (array_unique(array_merge(array_keys($before), array_keys($after))) as $k) { + if (in_array($k, $ignore, true)) continue; + $a = $before[$k] ?? null; + $b = $after[$k] ?? null; + if ((string) (is_scalar($a) || $a === null ? $a : json_encode($a)) === (string) (is_scalar($b) || $b === null ? $b : json_encode($b))) continue; + $out[$k] = ['from' => $a, 'to' => $b]; + } + return $out; +} + +/** Os campos de um registo novo, na forma do diff (a partir de nada). Vazios ficam de fora. */ +function platform_audit_created(array $fields): array +{ + $out = []; + foreach ($fields as $k => $v) { + if ($v === null || $v === '') continue; + $out[$k] = ['from' => null, 'to' => $v]; + } + return $out; +} + +/** + * Regista uma ação. Nunca lança. + * + * $d: target_type, target_id, target_label, summary, changes (array), e + * opcionalmente actor (['id','name','role'], ou false para «sistema»). + */ +function platform_audit(?PDO $pdo, string $action, array $d = []): void +{ + if (!$pdo instanceof PDO) { + $pdo = function_exists('platform_pdo') ? platform_pdo() : null; + if (!$pdo instanceof PDO) return; + } + try { + $actor = array_key_exists('actor', $d) ? ($d['actor'] ?: null) : platform_audit_actor(); + $changes = $d['changes'] ?? null; + if (is_array($changes)) { + $changes = $changes ? json_encode(platform_audit_redact($changes), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) : null; + } + $values = [ + 'actor_id' => $actor['id'] ?? null, + 'actor_name' => $actor['name'] ?? null, + 'actor_role' => $actor['role'] ?? null, + 'action' => $action, + 'target_type' => (string) ($d['target_type'] ?? ''), + 'target_id' => isset($d['target_id']) ? (string) $d['target_id'] : null, + 'target_label' => $d['target_label'] ?? null, + 'summary' => $d['summary'] ?? null, + 'changes' => $changes, + 'ip' => platform_client_ip(), + 'user_agent' => isset($_SERVER['HTTP_USER_AGENT']) ? (string) $_SERVER['HTTP_USER_AGENT'] : null, + ]; + + $cols = platform_audit_table_columns($pdo); + if (!$cols) return; + + $insert = []; + foreach ($values as $field => $v) { + $col = platform_audit_column($field); + if (!isset($cols[$col])) continue; // o site não tem coluna para isto + $c = $cols[$col]; + if ($v !== null && in_array($c['type'], ['int', 'bigint', 'smallint', 'mediumint', 'tinyint'], true)) { + $v = is_numeric($v) ? (int) $v : null; // um id que não é número não cabe numa coluna INT + } + if (is_string($v) && $c['max'] !== null && mb_strlen($v) > $c['max']) { + $v = mb_substr($v, 0, $c['max']); + } + if ($v === null && $c['not_null']) { + // NOT NULL: com valor por omissão, omite-se e vale o dela; sem ele, vazio. + if (!$c['required']) continue; + $v = ''; + } + $insert[$col] = $v; + } + // Colunas obrigatórias do site que nada preencheu (NOT NULL sem valor por omissão). + foreach ($cols as $col => $c) { + if ($c['required'] && !array_key_exists($col, $insert) && $col !== 'id') $insert[$col] = ''; + } + + $table = platform_audit_config()['table']; + $names = implode(', ', array_map(fn($c) => "`$c`", array_keys($insert))); + $marks = implode(', ', array_fill(0, count($insert), '?')); + $pdo->prepare("INSERT INTO `$table` ($names) VALUES ($marks)")->execute(array_values($insert)); + + platform_audit_maybe_prune($pdo); + } catch (Throwable $e) { + error_log('[audit] não registado (' . $action . '): ' . $e->getMessage()); + } +} + +/** Apaga as linhas mais velhas do que keep_days — no máximo uma vez por dia e por pedido. */ +function platform_audit_maybe_prune(PDO $pdo): void +{ + static $done = false; + if ($done) return; + $done = true; + $keep = platform_audit_config()['keep_days']; + if ($keep <= 0 || random_int(1, 200) !== 1) return; // barato: ~1 em 200 escritas + try { + $table = platform_audit_config()['table']; + $col = 'created_at'; + $pdo->prepare("DELETE FROM `$table` WHERE `$col` < DATE_SUB(NOW(), INTERVAL ? DAY) LIMIT 5000")->execute([$keep]); + } catch (Throwable $e) { + error_log('[audit] poda falhou: ' . $e->getMessage()); + } +} + +// ─── Leitura (a página audit.php) ─────────────────────────────────────────── + +/** + * Linhas do registo com os nomes canónicos, seja qual for a forma da tabela do + * site. Filtros: actor (texto), action (prefixo), target_type, target_id, + * from/to (Y-m-d), q (texto livre). + */ +function platform_audit_query(PDO $pdo, array $f = [], int $limit = 100, int $offset = 0): array +{ + $cols = platform_audit_table_columns($pdo); + $table = platform_audit_config()['table']; + $sel = ['`id`', '`created_at`']; + $has = []; + foreach (array_keys(platform_audit_columns()) as $field) { + $col = platform_audit_column($field); + if (isset($cols[$col])) { $sel[] = "`$col` AS `$field`"; $has[$field] = "`$col`"; } + else { $sel[] = "NULL AS `$field`"; } + } + $where = []; $params = []; + if (($f['actor'] ?? '') !== '' && isset($has['actor_name'])) { $where[] = "{$has['actor_name']} LIKE ?"; $params[] = '%' . $f['actor'] . '%'; } + if (($f['action'] ?? '') !== '') { $where[] = "{$has['action']} LIKE ?"; $params[] = $f['action'] . '%'; } + if (($f['target_type'] ?? '') !== '' && isset($has['target_type'])) { $where[] = "{$has['target_type']} = ?"; $params[] = $f['target_type']; } + if (($f['target_id'] ?? '') !== '' && isset($has['target_id'])) { $where[] = "{$has['target_id']} = ?"; $params[] = $f['target_id']; } + if (($f['from'] ?? '') !== '') { $where[] = '`created_at` >= ?'; $params[] = $f['from'] . ' 00:00:00'; } + if (($f['to'] ?? '') !== '') { $where[] = '`created_at` <= ?'; $params[] = $f['to'] . ' 23:59:59'; } + if (($f['q'] ?? '') !== '') { + $like = []; + foreach (['target_label', 'summary', 'changes'] as $field) if (isset($has[$field])) $like[] = "{$has[$field]} LIKE ?"; + if ($like) { $where[] = '(' . implode(' OR ', $like) . ')'; foreach ($like as $_) $params[] = '%' . $f['q'] . '%'; } + } + $sql = 'SELECT ' . implode(', ', $sel) . " FROM `$table`" + . ($where ? ' WHERE ' . implode(' AND ', $where) : '') + . ' ORDER BY `created_at` DESC, `id` DESC LIMIT ' . max(1, min(1000, $limit)) . ' OFFSET ' . max(0, $offset); + $st = $pdo->prepare($sql); + $st->execute($params); + return $st->fetchAll(PDO::FETCH_ASSOC); +} + +/** Os valores distintos de um campo, para os filtros (ações, tipos). */ +function platform_audit_distinct(PDO $pdo, string $field, int $limit = 200): array +{ + $cols = platform_audit_table_columns($pdo); + $col = platform_audit_column($field); + if (!isset($cols[$col])) return []; + $table = platform_audit_config()['table']; + return $pdo->query("SELECT DISTINCT `$col` FROM `$table` WHERE `$col` IS NOT NULL AND `$col` <> '' ORDER BY `$col` LIMIT " . (int) $limit) + ->fetchAll(PDO::FETCH_COLUMN); +} diff --git a/shared/platform-tools/functions_auth.php b/shared/platform-tools/functions_auth.php index 5d6acd9..3f6953b 100644 --- a/shared/platform-tools/functions_auth.php +++ b/shared/platform-tools/functions_auth.php @@ -21,6 +21,8 @@ require_once __DIR__ . '/functions_settings.php'; require_once __DIR__ . '/functions_client_ip.php'; +require_once __DIR__ . '/functions_security_events.php'; +require_once __DIR__ . '/functions_connector.php'; // ─── Schema map ───────────────────────────────────────────────────────────── // @@ -30,24 +32,11 @@ require_once __DIR__ . '/functions_client_ip.php'; // is a function call. Sites converging on the standard names can simply not // call auth_schema() at all. +// The defaults live in functions_connector.php, which the conformance check +// reads too — one list of standard names, not two that drift apart. function auth_schema(?array $map = null): array { - static $schema = [ - 'table' => 'users', - 'id' => 'id', - 'email' => 'email', - // The column the login form matches on. null => use `email`, which is - // what five of the six sites do. quack authenticates by `username` - // instead, and still needs `email` to stay the address password - // recovery mails to -- so the two cannot be the same key. - 'login' => null, - 'password' => 'password_hash', - 'name' => 'name', - 'role' => 'role', - 'active' => 'is_active', // null => no active flag on this site - 'deleted_at' => null, // set when the site soft-deletes instead - 'last_login' => 'last_login_at', - 'last_ip' => 'last_login_ip', - ]; + static $schema = null; + $schema ??= platform_auth_schema_defaults(); if ($map !== null) $schema = array_merge($schema, $map); return $schema; } @@ -243,6 +232,9 @@ function auth_throttle_check(PDO $pdo, string $identifier, int $max = 5, int $wi $count = (int) $row['c']; $blocked = $count >= $max; + if ($blocked) { + platform_security_event($pdo, 'login_throttled', hub_security_mask_identifier($identifier), $ip); + } return [ 'blocked' => $blocked, 'remaining' => max(0, $max - $count), @@ -261,6 +253,7 @@ function auth_throttle_hit(PDO $pdo, string $identifier): void { } catch (Throwable $e) { error_log('[auth] throttle record failed: ' . $e->getMessage()); } + platform_security_event($pdo, 'login_failed', hub_security_mask_identifier($identifier)); } function auth_throttle_clear(PDO $pdo, string $identifier): void { @@ -327,6 +320,11 @@ function auth_login(PDO $pdo, array $user): void { ]; $_SESSION['_auth_seen'] = time(); + if (function_exists('platform_audit')) { + platform_audit($pdo, 'auth.login', ['target_type' => 'user', 'target_id' => (int) $user[$s['id']], + 'target_label' => (string) ($user[$s['email']] ?? '')]); + } + $sets = []; $params = []; if ($s['last_login']) { $sets[] = "`{$s['last_login']}` = NOW()"; } if ($s['last_ip']) { $sets[] = "`{$s['last_ip']}` = ?"; $params[] = auth_client_ip(); } @@ -342,6 +340,10 @@ function auth_login(PDO $pdo, array $user): void { } function auth_logout(bool $destroy = true): void { + // Antes de limpar a sessão: depois já não se sabe quem saiu. + if (function_exists('platform_audit') && !empty($_SESSION['user']['id'])) { + platform_audit(null, 'auth.logout', ['target_type' => 'user', 'target_id' => (int) $_SESSION['user']['id']]); + } $_SESSION = []; if (ini_get('session.use_cookies')) { $p = session_get_cookie_params(); diff --git a/shared/platform-tools/functions_auto_update.php b/shared/platform-tools/functions_auto_update.php index 3c5f7c2..1ade259 100644 --- a/shared/platform-tools/functions_auto_update.php +++ b/shared/platform-tools/functions_auto_update.php @@ -528,6 +528,15 @@ function auto_update_run(PDO $pdo, string $repo_root, ?string $ref = null): arra /** Persist the outcome so the UI can show it without re-running anything. */ function auto_update_record(PDO $pdo, array $result, ?string $ref): void { + if (function_exists('platform_audit')) { + // Sem sessão (webhook do Gitea) o autor é a própria atualização automática. + platform_audit($pdo, 'platform.auto_update', [ + 'actor' => platform_audit_actor() ?? ['id' => null, 'name' => 'atualização automática', 'role' => 'webhook'], + 'target_type' => 'platform', + 'summary' => (string) ($result['summary'] ?? '') . (empty($result['ok']) ? ' — falhou' : ''), + 'changes' => ['status' => $result['status'] ?? null, 'ref' => $ref], + ]); + } try { platform_settings_set($pdo, 'auto_update_last_at', gmdate('Y-m-d H:i:s')); platform_settings_set($pdo, 'auto_update_last_ok', !empty($result['ok']) ? '1' : '0'); diff --git a/shared/platform-tools/functions_backup.php b/shared/platform-tools/functions_backup.php index a2d1041..4c1ac04 100644 --- a/shared/platform-tools/functions_backup.php +++ b/shared/platform-tools/functions_backup.php @@ -15,6 +15,11 @@ // backup_trigger(string $type): bool ($type in {files, db}) // backup_type_label(string): string // backup_type_badge(string): string +// backup_retention_policy(): array +// backup_retention_summary(?array $policy = null): string +// backup_created_at(string $filename, int $fallback): int +// backup_gfs_keep(array $items, array $policy, int $now): array +// backup_prune(bool $dryRun = false): array function backup_dir(): string { $dir = dirname(__DIR__, 2) . '/backups'; @@ -113,26 +118,21 @@ function backup_trigger(string $type): bool { // Where the self-call lands. Default assumes shared/ is inside the document // root. Under a public/ docroot it is not, so hosts point this at a thin // wrapper instead. Constant wins (fotografia defines it in - // config/functions_backup.php); .env covers hosts with no such file (surf). + // config/functions_backup.php); .env covers hosts with no such file. $prefix = defined('BACKUP_TRIGGER_URL_PREFIX') ? BACKUP_TRIGGER_URL_PREFIX : (function_exists('env') ? ((string) (env('BACKUP_TRIGGER_URL_PREFIX') ?: 'shared/platform-tools/backups/')) : 'shared/platform-tools/backups/'); - // Host base-URL helpers differ: fotografia and the config/-stack sites - // expose base_url(); surf exposes getBaseUrl(). Calling base_url() - // unconditionally fataled with "undefined function" on the latter, before - // any backup could be triggered. Fall back to APP_BASE_URL from .env so a - // host with neither helper still works. + // base_url() when the host has one; APP_BASE_URL from .env otherwise, so a + // host without the helper still works. $path = ltrim($prefix . $script, '/'); if (function_exists('base_url')) { $url = base_url($path); - } elseif (function_exists('getBaseUrl')) { - $url = rtrim(getBaseUrl(), '/') . '/' . $path; } else { $base = function_exists('env') ? (string) env('APP_BASE_URL', '') : (string) getenv('APP_BASE_URL'); if ($base === '') { - error_log('backup_trigger: no base URL available (no base_url(), no getBaseUrl(), no APP_BASE_URL).'); + error_log('backup_trigger: no base URL available (no base_url(), no APP_BASE_URL).'); return false; } $url = rtrim($base, '/') . '/' . $path; @@ -165,6 +165,152 @@ function backup_trigger(string $type): bool { return $ok; } +// ─── Retenção avô-pai-filho ───────────────────────────────────────────────── +// +// Antes: tudo o que tivesse mais de BACKUP_KEEP_DAYS dias era apagado, e tudo o +// que tivesse menos ficava — incluindo cinco cópias do mesmo dia (a da noite, a +// de antes de atualizar, as do hub, as de segurança de um restauro). Num site +// com galerias são gigabytes por cópia. +// +// Agora, por tipo (db e ficheiros contam em separado): +// • tudo das últimas 24 h — são os pontos de restauro de uma atualização; +// • a mais recente de cada um dos últimos BACKUP_KEEP_DAYS dias com cópia; +// • a mais recente de cada uma das últimas BACKUP_KEEP_WEEKS semanas; +// • a mais recente de cada um dos últimos BACKUP_KEEP_MONTHS meses; +// • e a mais recente de todas, sempre. +// +// Cada escalão começa onde o anterior acaba: as semanais são semanas mais +// antigas do que a diária mais antiga, e as mensais meses mais antigos do que a +// semanal mais antiga. Sem isto a «mensal» era a cópia mais recente do mês +// corrente — que já é a diária de hoje — e BACKUP_KEEP_MONTHS=1 não guardava +// nada. Com 7/4/1 cobre-se cerca de dois meses. +// +// «Dias com cópia», e não «dias de calendário»: se as cópias pararem durante um +// mês, a poda não pode ficar sem nada para guardar — é exactamente quando as +// antigas são as únicas que há. + +function backup_retention_policy(): array { + $read = static function (string $key, int $default): int { + if (defined($key)) return max(0, (int) constant($key)); + $v = function_exists('env') ? env($key, null) : (getenv($key) !== false ? getenv($key) : null); + return ($v === null || $v === '') ? $default : max(0, (int) $v); + }; + return [ + 'recent_hours' => 24, + 'days' => $read('BACKUP_KEEP_DAYS', 7), + 'weeks' => $read('BACKUP_KEEP_WEEKS', 4), + 'months' => $read('BACKUP_KEEP_MONTHS', 1), + ]; +} + +/** + * A data da cópia pelo nome do ficheiro, que não muda quando o ficheiro é + * copiado ou restaurado de outro disco — ao contrário do mtime. + */ +function backup_created_at(string $filename, int $fallback): int { + if (preg_match('/_(\d{2})_(\d{2})_(\d{4})_(\d{2})_(\d{2})(?:_(\d{2}))?(?:_[0-9a-f]{6})?\.zip$/', $filename, $m)) { + $ts = mktime((int) $m[4], (int) $m[5], (int) ($m[6] ?? 0), (int) $m[2], (int) $m[1], (int) $m[3]); + if ($ts !== false) return $ts; + } + return $fallback; +} + +/** + * Que cópias ficam. Função pura: recebe a lista (filename, type, created_at) e + * devolve [filename => motivo]. O que não vier na resposta é para apagar. + */ +function backup_gfs_keep(array $items, array $policy, int $now): array { + $tiers = [ + 'days' => ['Y-m-d', 'diária'], + 'weeks' => ['o-\WW', 'semanal'], + 'months' => ['Y-m', 'mensal'], + ]; + + $byType = []; + foreach ($items as $it) $byType[$it['type']][] = $it; + + $keep = []; + foreach ($byType as $list) { + usort($list, fn($a, $b) => $b['created_at'] <=> $a['created_at']); + $keep[$list[0]['filename']] = 'mais recente'; + + foreach ($list as $it) { + if ($now - (int) $it['created_at'] < $policy['recent_hours'] * 3600) { + $keep[$it['filename']] ??= 'últimas ' . $policy['recent_hours'] . ' h'; + } + } + + // $floor: a cópia mais antiga guardada pelo escalão anterior. O escalão + // seguinte só olha para o que é mais antigo, e salta o balde dela — esse + // período já está representado. + $floor = null; + foreach ($tiers as $tier => [$fmt, $label]) { + $skip = $floor === null ? null : date($fmt, $floor); + $buckets = []; + $oldest = null; + // Da mais recente para a mais antiga: a primeira que cai num balde é + // a mais recente desse dia/semana/mês. + foreach ($list as $it) { + $t = (int) $it['created_at']; + if ($floor !== null && $t >= $floor) continue; + if (count($buckets) >= $policy[$tier]) break; + $key = date($fmt, $t); + if ($key === $skip || isset($buckets[$key])) continue; + $buckets[$key] = true; + $keep[$it['filename']] ??= $label; + $oldest = $t; + } + if ($oldest !== null) $floor = $oldest; + } + } + return $keep; +} + +/** + * Aplica a retenção à pasta de cópias. Com $dryRun não apaga nada — diz o que + * apagaria. Devolve ['policy', 'kept' => [[filename, reason]], 'deleted', 'errors']. + */ +function backup_prune(bool $dryRun = false): array { + $dir = backup_dir(); + $policy = backup_retention_policy(); + $now = time(); + + $items = []; + foreach (backup_list() as $b) { + $b['created_at'] = backup_created_at($b['filename'], (int) $b['created_at']); + $items[] = $b; + } + $keep = backup_gfs_keep($items, $policy, $now); + + $out = ['policy' => $policy, 'kept' => [], 'deleted' => [], 'errors' => []]; + foreach ($items as $b) { + if (isset($keep[$b['filename']])) { + $out['kept'][] = ['filename' => $b['filename'], 'reason' => $keep[$b['filename']]]; + } elseif ($dryRun || @unlink($dir . '/' . $b['filename'])) { + $out['deleted'][] = $b['filename']; + } else { + $out['errors'][] = $b['filename']; + } + } + + // .sql de dumps interrompidos antes de irem para o ZIP: texto em claro que + // não aparece na lista. Um dia chega para não apanhar um dump a decorrer. + foreach (glob($dir . '/db_backup_*.sql') ?: [] as $f) { + if (filemtime($f) < $now - 86400) { + if ($dryRun || @unlink($f)) $out['deleted'][] = basename($f); + else $out['errors'][] = basename($f); + } + } + return $out; +} + +/** Linha legível da política, para a página e para o log dos workers. */ +function backup_retention_summary(?array $policy = null): string { + $p = $policy ?? backup_retention_policy(); + return sprintf('tudo das últimas %d h, e a mais recente de cada um dos últimos %d dias, %d semanas e %d meses', + $p['recent_hours'], $p['days'], $p['weeks'], $p['months']); +} + function backup_type_label(string $type): string { return match($type) { 'db' => 'Base de dados', diff --git a/shared/platform-tools/functions_captcha.php b/shared/platform-tools/functions_captcha.php new file mode 100644 index 0000000..1d9f3ed --- /dev/null +++ b/shared/platform-tools/functions_captcha.php @@ -0,0 +1,839 @@ +: +// echo platform_captcha_field('registo', $pdo); +// +// // no handler, depois do CSRF: +// if (($erro = platform_captcha_verify('registo', $pdo)) !== null) { +// $error = $erro; // já em português, pronto a mostrar +// } +// +// O primeiro argumento é o âmbito: entra na assinatura, para que um desafio +// colhido no formulário de contacto não sirva no de registo. Dois formulários na +// mesma página com âmbitos diferentes são independentes. +// +// API pública: +// platform_captcha_config(?array) — configuração do módulo +// platform_captcha_field(string, ?PDO) — o bloco HTML pronto a imprimir +// platform_captcha_issue(string, ?PDO) — pergunta + token, para marcação própria +// platform_captcha_verify(string, ?PDO) — null passa, ou a mensagem de erro +// platform_captcha_ok(string, ?PDO) — o mesmo em booleano +// +// E o recurso — a razão pela qual este módulo existe. Ver a secção no fim: +// platform_captcha_appeal_offer(PDO, form, reason) — guarda a submissão recusada +// platform_captcha_appeal_field(token, form, ?PDO) — o bloco do segundo ecrã +// platform_captcha_appeal_claim(PDO, form, &$error) — devolve a submissão libertada + +require_once __DIR__ . '/functions_settings.php'; +require_once __DIR__ . '/functions_client_ip.php'; + +/** + * Configuração. Com um array define; sem argumentos, lê. + */ +function platform_captcha_config(?array $set = null): array +{ + static $cfg = [ + // 'math' (contas), 'letter' (letra de uma palavra) ou 'mixed' (sorteia + // uma das duas por desafio). Misturar é de graça e obriga quem + // automatiza a resolver dois formatos em vez de um. + 'type' => 'mixed', + + // Validade do desafio. Curta de propósito: sem sessão activa é ela que + // limita quantas respostas cabem num token. 15 minutos chegam para + // preencher um formulário e não chegam para um ataque com paciência. + 'ttl' => 900, + + // Nomes dos campos. Configuráveis porque um site pode já ter um campo + // chamado 'captcha' vindo de outra coisa. + 'field_answer' => 'captcha_answer', + 'field_token' => 'captcha_token', + + // Classes do Bootstrap 5, que é o que toda a frota carrega. Um sítio sem + // Bootstrap passa strings vazias e estiliza por fora. + 'class_wrap' => 'mb-3', + 'class_label' => 'form-label', + 'class_input' => 'form-control', + 'class_help' => 'form-text', + 'help' => 'Uma pergunta simples, para travar envios automáticos.', + 'autocomplete' => 'off', + + // Uma tentativa por pergunta, quando há sessão. Ver o cabeçalho. + 'single_use' => true, + + // Um token forjado ou em falta é sinal de bot e conta para a escalada do + // functions_ip_ban.php. Uma resposta errada NÃO conta, e a diferença é + // deliberada: a escada bane aos 3 registos em 24 h, e quem se engana + // duas vezes a escrever "catorze" não é um bot — seria banir gente por + // errar uma pergunta que nós próprios lhe fizemos. + 'offence_forged' => true, + 'offence_wrong' => false, + + // ─── O recurso ────────────────────────────────────────────────────── + // Tabela própria, criada à cabeça como as do functions_ip_ban.php: a + // `blocked_submissions` tem forma diferente em cada site e é um registo, + // não uma fila de trabalho. + 'appeal_table' => 'captcha_appeals', + + // Duas horas para responder. É uma pessoa a olhar para o ecrã, não um + // formulário deixado aberto — e quanto mais curto, menos tempo a + // submissão recusada fica guardada. + 'appeal_ttl' => 7200, + + // Tentativas por recurso, e recursos por IP à hora. O primeiro impede + // que se esgotem as respostas possíveis numa só submissão retida; o + // segundo impede que a fila de recursos vire um depósito de spam. + 'appeal_tries' => 6, + 'appeal_max_ip' => 5, + + // Motivos que NÃO dão direito a recurso. A recusa silenciosa existe + // para o bot não ficar a saber o que o apanhou, e estes dois não têm + // leitura inocente: o honeypot é um campo que ninguém vê, e o carimbo só + // é produzido pelo nosso próprio formulário. Oferecer recurso a quem + // falha ali é ensiná-lo a contornar. Todos os outros — país, limite por + // IP, pontuação de conteúdo, formulário expirado — têm falsos positivos + // reais e é para eles que isto serve. + 'appeal_never' => ['honeypot', 'carimbo inválido'], + + // Palavras do desafio da letra. Sem acentos, de propósito: a resposta é + // uma letra e não vale a pena pôr ninguém a decidir se escreve "a" ou + // "á". + 'words' => [ + 'CADEIRA', 'JANELA', 'SAPATO', 'CAMINHO', 'MERCADO', 'PALAVRA', + 'LARANJA', 'MONTANHA', 'TELEFONE', 'BICICLETA', 'ESCADA', + 'FLORESTA', 'CAMISOLA', 'GUITARRA', 'PADEIRO', 'CADERNO', + ], + ]; + + if ($set !== null) { + $cfg = array_merge($cfg, $set); + } + return $cfg; +} + +/** + * A chave que assina os desafios. + * + * Domínio próprio: um carimbo do anti-spam não valida aqui, nem ao contrário. A + * derivação e os seus três degraus estão em functions_settings.php, que é onde + * vive a única implementação. + */ +function platform_captcha_key(?PDO $pdo = null): string +{ + return platform_derived_key('captcha', $pdo); +} + +/** + * A pergunta e a resposta, derivadas do nonce. + * + * Determinista: o mesmo nonce, com a mesma chave e o mesmo âmbito, dá sempre o + * mesmo par. É isso que dispensa guardar seja o que for — o servidor volta a + * calcular a resposta no pedido seguinte em vez de se lembrar dela. + * + * Note-se que a resposta nunca vai para o cliente, nem sequer como hash: um hash + * de "14" quebra-se com vinte tentativas numa consola. + * + * @return array{question:string, answer:string} + */ +function platform_captcha_challenge(string $form, string $nonce, ?PDO $pdo = null): array +{ + $cfg = platform_captcha_config(); + $b = array_values(unpack( + 'C*', + hash_hmac('sha256', 'q|' . $form . '|' . $nonce, platform_captcha_key($pdo), true) + )); + + $type = $cfg['type']; + if ($type === 'mixed') { + $type = ($b[0] % 2 === 0) ? 'math' : 'letter'; + } + + if ($type === 'letter') { + $words = array_values($cfg['words']); + $word = $words ? $words[$b[1] % count($words)] : 'CADEIRA'; + // Até à quinta letra, e nunca além do tamanho da palavra. + $max = min(5, mb_strlen($word, 'UTF-8')); + $pos = 1 + ($b[2] % $max); + $ord = [1 => 'primeira', 2 => 'segunda', 3 => 'terceira', 4 => 'quarta', 5 => 'quinta'][$pos]; + + return [ + 'question' => 'Escreva a ' . $ord . ' letra da palavra ' . $word . '.', + 'answer' => mb_substr($word, $pos - 1, 1, 'UTF-8'), + ]; + } + + // Contas. Os limites dos operandos mantêm o resultado entre 0 e 20, que é o + // intervalo que platform_captcha_number_words() sabe escrever por extenso. + switch ($b[1] % 3) { + case 0: + $x = 1 + ($b[2] % 9); + $y = 1 + ($b[3] % 9); + $op = 'mais'; + $r = $x + $y; + break; + case 1: + // O maior primeiro: um resultado negativo é uma pergunta injusta. + $x = 2 + ($b[2] % 8); + $y = 1 + ($b[3] % ($x - 1)); + $op = 'menos'; + $r = $x - $y; + break; + default: + $x = 2 + ($b[2] % 4); + $y = 2 + ($b[3] % 3); + $op = 'vezes'; + $r = $x * $y; + } + + // Um operando por extenso e o outro em algarismos, sorteados. Custa nada e + // parte o regex /(\d+)\s*\+\s*(\d+)/ com que se resolve um captcha destes em + // três linhas. + $words = platform_captcha_number_words(); + $left = ($b[4] % 2 === 0) ? (string) $x : $words[$x]; + $right = ($b[4] % 2 === 0) ? $words[$y] : (string) $y; + + // "duas vezes três", não "dois vezes três": quem conta ali são as vezes, e + // "vez" é feminino. Só acontece com o operando da esquerda de uma + // multiplicação, e só quando calha ser escrito por extenso. A resposta não + // muda com isto — platform_captcha_canonical_answer() já lê "duas" como 2. + if ($op === 'vezes' && $left === 'dois') { + $left = 'duas'; + } + + return [ + 'question' => 'Quanto é ' . $left . ' ' . $op . ' ' . $right . '?', + 'answer' => (string) $r, + ]; +} + +/** 0–20 por extenso, já na forma normalizada (minúsculas, sem acentos). */ +function platform_captcha_number_words(): array +{ + return [ + 0 => 'zero', 'um', 'dois', 'tres', 'quatro', 'cinco', 'seis', 'sete', + 'oito', 'nove', 'dez', 'onze', 'doze', 'treze', 'catorze', 'quinze', + 'dezasseis', 'dezassete', 'dezoito', 'dezanove', 'vinte', + ]; +} + +/** + * Normaliza uma resposta: minúsculas, sem acentos, sem nada que não seja letra + * ou algarismo. "Catorze", "catorze " e "CATORZE" são a mesma resposta. + */ +function platform_captcha_normalize(string $s): string +{ + $s = mb_strtolower(trim($s), 'UTF-8'); + $s = strtr($s, [ + 'á' => 'a', 'à' => 'a', 'â' => 'a', 'ã' => 'a', 'ä' => 'a', + 'é' => 'e', 'è' => 'e', 'ê' => 'e', 'í' => 'i', 'ì' => 'i', 'î' => 'i', + 'ó' => 'o', 'ò' => 'o', 'ô' => 'o', 'õ' => 'o', 'ö' => 'o', + 'ú' => 'u', 'ù' => 'u', 'û' => 'u', 'ü' => 'u', 'ç' => 'c', 'ñ' => 'n', + ]); + return (string) preg_replace('/[^a-z0-9]+/', '', $s); +} + +/** + * A resposta de quem preencheu, posta na mesma forma que a nossa: por extenso + * vira algarismos, e as variantes do Brasil são aceites porque quem as escreve + * respondeu certo. + */ +function platform_captcha_canonical_answer(string $raw): string +{ + $n = platform_captcha_normalize($raw); + + $alias = [ + 'uma' => 'um', 'duas' => 'dois', 'quatorze' => 'catorze', + 'dezesseis' => 'dezasseis', 'dezessete' => 'dezassete', 'dezenove' => 'dezanove', + ]; + $n = $alias[$n] ?? $n; + + $words = array_flip(platform_captcha_number_words()); + if (isset($words[$n])) { + return (string) $words[$n]; + } + // "07" e "7" são a mesma resposta. + if ($n !== '' && ctype_digit($n)) { + return (string) (int) $n; + } + return $n; +} + +/** + * Emite um desafio: a pergunta, o token e os nomes dos campos. + * + * Para quem quer a sua própria marcação — um formulário em grelha, um modal, um + * passo de um assistente. Quem só quer um campo normal usa + * platform_captcha_field(), que é isto com HTML à volta. + * + * @return array{question:string, token:string, field_answer:string, field_token:string, id:string} + */ +function platform_captcha_issue(string $form = 'form', ?PDO $pdo = null): array +{ + $cfg = platform_captcha_config(); + $ts = time(); + $nonce = bin2hex(random_bytes(9)); + $sig = platform_captcha_sign($form, $ts, $nonce, $pdo); + $ch = platform_captcha_challenge($form, $nonce, $pdo); + + return [ + 'question' => $ch['question'], + 'token' => $ts . '.' . $nonce . '.' . $sig, + 'field_answer' => $cfg['field_answer'], + 'field_token' => $cfg['field_token'], + // Único por instância: a mesma página pode ter dois captchas, e dois + //