@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/vps-security-hardening/SKILL.md

@@ -0,0 +1,406 @@
+---
+name: vps-security-hardening
+description: Canonical 7-step VPS security hardening protocol — SSH key auth, ufw firewall, fail2ban, password rotation, recovery doc. Apply to EVERY new VPS before exposing services to the internet.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [vps-hardening, vps-setup, ssh-hardening, ufw, fail2ban, ssh-brute-force]
+  tool_reminders:
+    [
+      Disabling password auth requires HIGH approval — verify key auth works FIRST,
+      Enabling ufw requires whitelist port 22 BEFORE enabling — order matters,
+      sshd config changes require `sshd -t` validation BEFORE reload,
+      Use `systemctl reload ssh` (not restart) to preserve current session,
+      Recovery doc with private key MUST be encrypted before leaving disk,
+      Old credentials in committed scripts are dead after rotation but should be purged anyway,
+    ]
+---
+
+# VPS Security Hardening Skill
+
+**Mission:** Every VPS that touches the public internet on behalf of a Merlin
+project goes through this 7-step protocol BEFORE production traffic. No
+exceptions. This skill exists because the cost of forgetting once is total
+compromise; the cost of running through the checklist is 30 minutes.
+
+The protocol was forged on 2026-04-27 during a real VPS security audit, where a
+production server was found with `PermitRootLogin yes` + `PasswordAuthentication
+yes` + no firewall + no fail2ban while receiving 626 SSH brute-force attempts
+per day. None succeeded, but the exposure was unacceptable. This skill
+codifies the fix so future-us never has to rediscover it.
+
+---
+
+## When to invoke this skill
+
+**Always run on:**
+
+- A freshly provisioned VPS, before any service is exposed
+- An inherited VPS where security posture is unknown
+- After the user mentions "I just got a new VPS / droplet / server"
+- When auditing an existing server (run as a comparison checklist)
+
+**Pre-flight signals you need this skill NOW:**
+
+- `ufw status` returns "inactive"
+- `crontab -l` shows no entries (no fail2ban triggers, no automation)
+- `grep PasswordAuthentication /etc/ssh/sshd_config*/*.conf` shows `yes`
+- `cat /root/.ssh/authorized_keys` is empty
+- `which fail2ban-client` returns nothing
+- `journalctl _SYSTEMD_UNIT=ssh.service --since '1 day ago' | grep -c 'Failed password'` returns >50
+
+---
+
+## The 7-Step Canonical Protocol
+
+Execute IN ORDER. Each step must succeed before the next. Each step is
+independently verifiable and reversible if you stop early.
+
+### Step 1 — Install local SSH public key on VPS (no destructive change)
+
+Use the existing dev machine SSH key (or generate one with `ssh-keygen -t ed25519`).
+Append public key to `/root/.ssh/authorized_keys` via password auth (still enabled
+at this stage).
+
+**Idempotency:** Always grep the fingerprint first; only append if absent.
+**Verification:** Connect with key-only auth (`allow_agent=False, look_for_keys=False`)
+in a separate session before proceeding.
+
+### Step 2 — Verify key auth works END-TO-END
+
+Open a NEW SSH connection using ONLY the key (refuse password fallback). If it
+fails, stop and debug. Common causes:
+
+- `~/.ssh/authorized_keys` permissions wrong (must be 600, owned by root)
+- `~/.ssh/` directory permissions wrong (must be 700)
+- SELinux contexts (rare on Ubuntu, common on RHEL)
+
+**DO NOT proceed to step 3 until this is green.**
+
+### Step 3 — Install + configure `fail2ban`
+
+```bash
+DEBIAN_FRONTEND=noninteractive apt-get update -qq
+DEBIAN_FRONTEND=noninteractive apt-get install -y -qq fail2ban
+```
+
+Write `/etc/fail2ban/jail.local`:
+
+```ini
+[DEFAULT]
+bantime = 1h
+findtime = 10m
+maxretry = 5
+ignoreip = 127.0.0.1/8 ::1 <DEV_HOME_IP>
+backend = systemd
+
+[sshd]
+enabled = true
+port = ssh
+filter = sshd
+maxretry = 5
+findtime = 10m
+bantime = 1h
+# Ubuntu 24.04 uses ssh.service, NOT sshd.service — see Gotcha #1
+journalmatch = _SYSTEMD_UNIT=ssh.service + _COMM=sshd
+```
+
+Then `systemctl enable fail2ban && systemctl restart fail2ban`.
+
+**Verification:** `fail2ban-client status sshd` shows the journal match line
+ending in `_SYSTEMD_UNIT=ssh.service`.
+
+### Step 4 — Enable `ufw` with strict whitelist
+
+**ORDER IS LIFE-OR-DEATH:** add allow rules BEFORE enabling. If you enable
+first, you lose access immediately.
+
+```bash
+ufw default deny incoming
+ufw default allow outgoing
+ufw allow 22/tcp comment 'SSH'
+ufw allow 80/tcp comment 'HTTP'
+ufw allow 443/tcp comment 'HTTPS'
+# Add only the ports your services actually need:
+# ufw allow 5432/tcp comment 'PostgreSQL'
+# ufw allow 8000/tcp comment 'App'
+# ufw allow 9000/tcp comment 'Portainer'
+ufw --force enable
+ufw status verbose
+```
+
+**Verification:** Open a NEW SSH session through the firewall. The existing
+session is unaffected (ufw only governs new connections).
+
+### Step 5 — Disable password auth + restrict root to key-only
+
+Write `/etc/ssh/sshd_config.d/99-<project>-hardening.conf`:
+
+```
+PasswordAuthentication no
+PubkeyAuthentication yes
+PermitRootLogin prohibit-password
+PermitEmptyPasswords no
+ChallengeResponseAuthentication no
+KbdInteractiveAuthentication no
+HostKeyAlgorithms ssh-ed25519,rsa-sha2-512,rsa-sha2-256
+MaxAuthTries 3
+MaxSessions 5
+LoginGraceTime 30s
+ClientAliveInterval 300
+ClientAliveCountMax 2
+```
+
+**Critical sub-step:** Cloud images often ship `/etc/ssh/sshd_config.d/50-cloud-init.conf`
+with `PasswordAuthentication yes`. Higher number drop-in (`99-*`) overrides
+lexically, BUT some sshd versions read in alphabetical order and stop at first
+match. **Neutralize the cloud-init line:**
+
+```bash
+sed -i 's/^PasswordAuthentication yes/#PasswordAuthentication yes  # neutralized by hardening/' \
+  /etc/ssh/sshd_config.d/50-cloud-init.conf
+```
+
+**Validate config syntax BEFORE reload (NEVER skip this):**
+
+```bash
+sshd -t || { echo "CONFIG ERROR — DO NOT RELOAD"; exit 1; }
+```
+
+**Reload (NOT restart) — keeps current session alive:**
+
+```bash
+systemctl reload ssh
+```
+
+**Verify config is live:**
+
+```bash
+sshd -T | grep -iE '^(passwordauth|permitroot|kbdinter)'
+# Expected:
+#   passwordauthentication no
+#   permitrootlogin without-password   (this is the canonical form of prohibit-password)
+#   kbdinteractiveauthentication no
+```
+
+**TWO-PART VERIFICATION:**
+
+1. NEW session via key — must succeed
+2. Connection attempt with password — must FAIL with `paramiko.AuthenticationException`
+
+If part 2 succeeds (password still works), the hardening did not take effect —
+roll back via the existing session and debug.
+
+### Step 6 — Rotate root password (defense in depth)
+
+Even with password auth disabled, rotate the password because:
+
+- Console access via cloud provider panel still uses it
+- Old password may exist in committed scripts / shell history / leaked logs
+- Defense-in-depth — if password auth gets re-enabled by accident, the old
+  one is dead
+
+```python
+import secrets, string
+alphabet = string.ascii_letters + string.digits + '!@#%^*-_=+'
+new_password = ''.join(secrets.choice(alphabet) for _ in range(32))
+# Apply via: echo "root:NEW_PW" | chpasswd
+```
+
+**Save the new password in:**
+
+1. Project password manager (1Password, Bitwarden, KeePass) — primary
+2. Encrypted recovery USB (see Step 7) — secondary
+
+### Step 7 — Generate offline recovery kit
+
+Create a self-contained markdown file with:
+
+- New root password (post-rotation)
+- SSH private key (full text, copy-pasteable)
+- SSH public key
+- Recovery scenarios (lost laptop, lost USB, panel inaccessible)
+- Date stamp + project name + VPS IP
+
+**Storage requirements:**
+
+- BitLocker-encrypted USB (Windows native) OR VeraCrypt container OR hardware-encrypted USB
+- Physical safe / vault for the encrypted USB
+- **A SECOND copy in a geographically different location** (more important than encryption — protects against fire, theft, USB hardware failure)
+
+**Acceptable shortcut:** plaintext file on USB inside a real safe (NOT a R$200
+fire safe) is defensible for small-business threat models, but encryption
+costs 5 minutes and survives safe compromise.
+
+**Unacceptable:** Google Drive, Dropbox, email, WhatsApp, repo (even private),
+unencrypted USB outside a safe, password manager note (those are designed for
+short secrets, not multi-line keys).
+
+---
+
+## Critical Gotchas (the hard-won knowledge)
+
+### Gotcha #1 — Ubuntu 24.04 systemd unit is `ssh.service`, NOT `sshd.service`
+
+Default fail2ban filter expects `_SYSTEMD_UNIT=sshd.service`. On Ubuntu 24.04
+the unit is `ssh.service` (the binary is `sshd`, but systemd registers `ssh`).
+Without explicit `journalmatch` override, fail2ban will sit at "Total failed:
+0" forever while attacks continue.
+
+**Detection:** `systemctl status sshd` returns "Unit sshd.service could not be found"
+but `systemctl status ssh` works.
+
+**Fix:** explicit `journalmatch = _SYSTEMD_UNIT=ssh.service + _COMM=sshd` in
+jail.local (see Step 3 template).
+
+### Gotcha #2 — `cloud-init` ships `PasswordAuthentication yes` in a drop-in
+
+Cloud provider images (Hostinger, DigitalOcean, AWS, Azure, GCP) install
+`/etc/ssh/sshd_config.d/50-cloud-init.conf` with password auth ENABLED. Even
+if your hardening drop-in says `no`, sshd may read 50- before 99- depending
+on version. Always neutralize the cloud-init directive directly.
+
+### Gotcha #3 — `systemctl restart ssh` kills your session; `reload` doesn't
+
+`restart` terminates all current SSH sessions including yours. If the new
+config has a syntax error you didn't catch, you're locked out. **Always use
+`reload`** — current sessions live until they disconnect, new connections use
+new config. Combined with `sshd -t` validation before reload, this gives you
+a safe atomic upgrade.
+
+### Gotcha #4 — `ufw enable` BEFORE `ufw allow 22` = locked out instantly
+
+Default policy is `deny incoming`. If you enable before adding the SSH allow
+rule, your current session continues (existing connections unaffected) but
+you cannot reconnect. Always `ufw allow 22/tcp` first, then `ufw enable`.
+
+### Gotcha #5 — `paramiko.connect()` fingerprint cache (`known_hosts`)
+
+After enabling key auth, paramiko on Windows may cache the host key in
+`~/.ssh/known_hosts`. If the VPS host key changes (rebuild, OS reinstall),
+paramiko refuses to connect with `MissingHostKeyPolicy=RejectPolicy`. Use
+`AutoAddPolicy()` for dev tooling, but be aware it disables MITM detection.
+
+### Gotcha #6 — `Postgres on 0.0.0.0:5432` is required if Cloud Functions need it
+
+If the project uses Firebase Functions / AWS Lambda / Vercel that connect to
+the VPS Postgres directly, you cannot bind Postgres to 127.0.0.1. The
+mitigation is strong Postgres auth + IP allowlist in `pg_hba.conf` for the
+provider's egress IP range. Don't try to "fix" this exposure without
+understanding the dependency.
+
+### Gotcha #7 — Hardcoded passwords in committed scripts survive git history
+
+Even after rotating the root password, the OLD password remains in
+`git log -p` forever (unless you `git-filter-repo`, which is overkill for
+already-rotated credentials). The damage is done — anyone who cloned the repo
+when the password was live has it. Rotation invalidates that exposure but does
+not "undo" the leak. **Conclusion: never put passwords in scripts in the first
+place. Use env vars, password managers, or SSH keys.**
+
+---
+
+## Tooling — Reusable Scripts
+
+A reference project (`/path/to/project/scripts/`) has battle-tested
+implementations of all 7 steps using paramiko. When applying this skill to a
+new VPS, copy and adapt:
+
+| Script                    | Purpose                                                                |
+| ------------------------- | ---------------------------------------------------------------------- |
+| `_vps_ssh.py`             | Helper: `connect()` returns paramiko SSHClient via key auth            |
+| `vps_install_ssh_key.py`  | Step 1-2 (one-shot bootstrap; reads VPS_PASSWORD from env)             |
+| `vps_install_fail2ban.py` | Step 3 (idempotent install + config + verify)                          |
+| `vps_enable_ufw.py`       | Step 4 (whitelist-first ordering)                                      |
+| `vps_harden_sshd.py`      | Step 5 (backup + drop-in + sshd -t + reload + verify)                  |
+| `vps_full_audit.py`       | Health check: containers, DB, certs, backups, ports                    |
+| `vps_security_check.py`   | Compromise indicator scan: successful logins, UID 0 users, hidden cron |
+
+When provisioning a new VPS for any Merlin project: clone these into the new
+project's `scripts/` dir, edit `_vps_ssh.py` with the new IP/host, and run the
+sequence.
+
+---
+
+## Recovery Doc Template
+
+For Step 7, generate a markdown file with this skeleton:
+
+```markdown
+# 🔐 <PROJECT> VPS — KIT DE RECUPERAÇÃO DE EMERGÊNCIA
+
+**Gerado:** YYYY-MM-DD
+**Servidor:** <IP> (<provider>)
+**Domínio:** <domain>
+
+## 1. Senha root (apenas console emergencial — SSH password disabled)
+
+<rotated_password>
+
+## 2. Chave privada SSH (Ed25519)
+
+**Fingerprint:** SHA256:...
+-----BEGIN OPENSSH PRIVATE KEY-----
+<content>
+-----END OPENSSH PRIVATE KEY-----
+
+## 3. Chave pública (instalada em /root/.ssh/authorized_keys)
+
+ssh-ed25519 AAAA... user@host
+
+## 4. Cenários de recuperação
+
+A. Perdi o PC mas tenho USB → copiar conteúdo das seções 2-3 para ~/.ssh/
+B. Perdi PC + USB → console do provedor + senha da seção 1 + nova chave
+C. Provedor inacessível → suporte do provedor para reset out-of-band
+D. Adicionar 2ª chave de backup → SSH normal + echo >> authorized_keys
+
+## 5. Configuração aplicada (referência)
+
+- PasswordAuthentication: no
+- PermitRootLogin: prohibit-password
+- ufw: active (allow <ports>)
+- fail2ban: active (5 fails / 10min = 1h ban)
+- Backup do sshd config em: /etc/ssh/sshd_config.bak.YYYYMMDD
+
+## 6. Compromisso de manutenção
+
+- Atualizar este doc ao rotacionar credenciais
+- Rotação anual recomendada
+- Manter cópia em ≥2 locais físicos diferentes
+```
+
+---
+
+## Threat Model — what this skill defends against
+
+| Threat                                  | Defense                             | Residual risk                                 |
+| --------------------------------------- | ----------------------------------- | --------------------------------------------- |
+| SSH brute-force (automated bots)        | fail2ban + key-only auth            | Effectively zero                              |
+| Stolen password from leaked script      | Password auth disabled + rotated    | Zero (password is non-functional for SSH)     |
+| Targeted attack with stolen private key | Hardware-encrypted USB + safe       | Low — requires physical access to safe        |
+| Cloud provider panel compromise         | None at this layer                  | High — accept or use 2FA on provider account  |
+| Postgres direct attack on 5432          | Provider firewall + Postgres auth   | Medium — depends on app passwords             |
+| Insider with prior root password        | Rotation invalidates                | Zero post-rotation                            |
+| Lost laptop with private key            | USB recovery doc + provider console | Low — accept brief downtime to rebuild access |
+| Catastrophic cofre/USB loss             | Geographic redundancy (2nd USB)     | Accept if not implemented                     |
+
+---
+
+## Maintenance cadence
+
+- **Quarterly:** verify `ufw status`, `fail2ban-client status sshd`, recent successful SSH logins (`journalctl _SYSTEMD_UNIT=ssh.service --since '90 days ago' | grep Accepted`)
+- **Annually:** rotate SSH key + root password + regenerate recovery doc
+- **On staff change:** rotate immediately + remove old key from authorized_keys + update recovery doc
+- **On VPS rebuild:** re-run Steps 1-7 from scratch on the new instance
+
+---
+
+## References
+
+- [VPS hardening session research](.merlin-core/thoughts/shared/research/) — 2026-04-27 audit + live hardening
+- [SSH best practices — Mozilla](https://infosec.mozilla.org/guidelines/openssh)
+- [fail2ban systemd backend docs](https://fail2ban.readthedocs.io/)
+- [Ubuntu 24.04 ssh.service vs sshd.service](https://wiki.ubuntu.com/SSH) — gotcha #1 reference

package/.merlin-core/skills/general/web-quality/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: web-quality
+description: Web quality optimization covering Core Web Vitals (LCP, CLS, INP), accessibility (WCAG 2.2), SEO best practices, and performance budgets. Framework-aware for React, Next.js, Vue, and Svelte.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  inspired-by: AO/web-quality-skills
+  auto_activate:
+    [lighthouse, core-web-vitals, accessibility, wcag, a11y, page-speed]
+  file_triggers: ["*.html", "*.tsx", "*.jsx", "*.vue", "*.svelte"]
+  tool_reminders:
+    [
+      Always check accessibility before visual polish — WCAG 2.2 Level AA minimum,
+      Performance budgets: LCP < 2.5s,
+      CLS < 0.1,
+      INP < 200ms,
+      Use Lighthouse CI for automated performance regression detection,
+    ]
+---
+
+# Web Quality Skills
+
+Comprehensive web quality optimization covering performance, accessibility, and SEO.
+
+## Core Web Vitals
+
+| Metric                          | Good    | Needs Improvement | Poor    |
+| ------------------------------- | ------- | ----------------- | ------- |
+| LCP (Largest Contentful Paint)  | ≤ 2.5s  | ≤ 4.0s            | > 4.0s  |
+| CLS (Cumulative Layout Shift)   | ≤ 0.1   | ≤ 0.25            | > 0.25  |
+| INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms           | > 500ms |
+
+### LCP Optimization
+
+- Preload critical resources: `<link rel="preload" as="image" href="hero.webp">`
+- Use responsive images with `srcset` and `sizes`
+- Inline critical CSS, defer non-critical
+- Use `fetchpriority="high"` on LCP element
+- **React**: Use `next/image` or lazy loading for below-fold images
+- **Next.js**: Use `priority` prop on hero images, ISR for dynamic content
+
+### CLS Prevention
+
+- Always set `width` and `height` on images and videos
+- Use `aspect-ratio` CSS property for responsive containers
+- Reserve space for dynamic content (ads, embeds, lazy-loaded content)
+- Use `font-display: swap` with proper fallback metrics
+- Avoid inserting content above existing content
+
+### INP Optimization
+
+- Break long tasks with `requestIdleCallback` or `scheduler.yield()`
+- Use `content-visibility: auto` for off-screen content
+- Debounce expensive event handlers (resize, scroll, input)
+- Use `will-change` sparingly for known animations
+- **React**: Use `useDeferredValue` and `useTransition` for non-urgent updates
+
+## Accessibility (WCAG 2.2 Level AA)
+
+### Semantic HTML Checklist
+
+- [ ] Use `<nav>`, `<main>`, `<header>`, `<footer>`, `<aside>` landmarks
+- [ ] Headings follow proper hierarchy (h1 → h2 → h3, no skipping)
+- [ ] Links have descriptive text (no "click here")
+- [ ] Forms have associated `<label>` elements
+- [ ] Tables have `<th>` with `scope` attribute
+- [ ] Lists use `<ul>`, `<ol>`, `<dl>` appropriately
+
+### ARIA Guidelines
+
+- Use ARIA only when native HTML semantics are insufficient
+- `aria-label` for icon-only buttons
+- `aria-live` regions for dynamic content updates
+- `role="alert"` for error messages
+- `aria-expanded` for collapsible sections
+- Never use `role="presentation"` on focusable elements
+
+### Keyboard Navigation
+
+- [ ] All interactive elements are focusable
+- [ ] Focus order follows visual order
+- [ ] Focus indicator is visible (min 2px outline, 3:1 contrast)
+- [ ] Escape closes modals and returns focus to trigger
+- [ ] Skip navigation link present
+- [ ] No keyboard traps
+
+### Color Contrast
+
+- Normal text: minimum 4.5:1 ratio
+- Large text (18pt or 14pt bold): minimum 3:1 ratio
+- UI components and graphical objects: minimum 3:1 ratio
+- Tool: `npx @contrast-checker/cli check "#333" "#fff"`
+
+## SEO Checklist
+
+### Technical SEO
+
+- [ ] Unique `<title>` per page (50-60 characters)
+- [ ] Meta description per page (150-160 characters)
+- [ ] Canonical URL: `<link rel="canonical" href="...">`
+- [ ] Open Graph tags: `og:title`, `og:description`, `og:image`
+- [ ] Structured data (JSON-LD) for content type
+- [ ] `robots.txt` configured correctly
+- [ ] XML sitemap generated and submitted
+- [ ] Proper 301 redirects for moved content
+
+### Content SEO
+
+- [ ] One `<h1>` per page matching topic
+- [ ] Descriptive alt text on all images
+- [ ] Internal linking between related content
+- [ ] Clean, readable URLs (no query params for content pages)
+
+## Lighthouse CI
+
+```bash
+# Install
+npm install -g @lhci/cli
+
+# Run against local server
+lhci autorun --collect.url=http://localhost:3000
+
+# CI configuration (.lighthouserc.json)
+{
+  "ci": {
+    "collect": {
+      "numberOfRuns": 3,
+      "url": ["http://localhost:3000/", "http://localhost:3000/about"]
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["error", {"minScore": 0.9}],
+        "categories:accessibility": ["error", {"minScore": 0.95}],
+        "categories:seo": ["error", {"minScore": 0.9}],
+        "categories:best-practices": ["error", {"minScore": 0.9}]
+      }
+    }
+  }
+}
+```
+
+## Framework-Specific Patterns
+
+### React
+
+- Use `React.memo()` for expensive renders, but measure first
+- `useMemo`/`useCallback` for referential stability, not premature optimization
+- Code-split routes with `React.lazy()` + `Suspense`
+- Use `react-helmet-async` for SEO meta tags
+
+### Next.js
+
+- Use `next/image` for automatic optimization
+- ISR (`revalidate`) for semi-static pages
+- `generateMetadata()` for dynamic SEO
+- `loading.tsx` for route-level loading states
+
+### Vue
+
+- Use `defineAsyncComponent` for code splitting
+- `v-once` for static content that never updates
+- `useHead()` from `@unhead/vue` for SEO
+
+### Svelte
+
+- Leverage compiler optimizations (no virtual DOM overhead)
+- Use `{#await}` blocks for async data
+- `svelte:head` for SEO meta tags
+
+## Performance Budgets
+
+| Resource Type          | Budget   |
+| ---------------------- | -------- |
+| Total JS (compressed)  | < 200 KB |
+| Total CSS (compressed) | < 50 KB  |
+| Hero image             | < 100 KB |
+| Web fonts              | < 100 KB |
+| Third-party scripts    | < 50 KB  |
+| Total page weight      | < 500 KB |