# Vibers

> 🇧🇷 Plataforma que transforma uma ideia descrita em linguagem natural em um SaaS completo (PHP + MySQL), usando múltiplos agentes de IA — **a IA solicita ações, a plataforma valida e executa**.
>
> 🇺🇸 A platform that turns an idea written in plain language into a complete SaaS (PHP + MySQL) using multiple AI agents — **the AI requests actions, the platform validates and executes them**.

**Status:** v0.2 — Fundação ✅ · IA (Gemini/GPT/Claude) ✅ · Build com 4 painéis + preview isolado ✅ · Planos, créditos e Stripe ✅
Arquitetura / Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) · **Configurar IAs, Stripe, worker / Configure AI, Stripe, worker: [docs/CONFIGURACAO.md](docs/CONFIGURACAO.md)**

---

## Stack

PHP 8.2+ (sem framework / no framework) · MySQL 8 / MariaDB 10.4+ · PDO · Bootstrap 5.3 · JavaScript vanilla · Nginx ou/or Apache · Linux VPS.
Nenhuma dependência Composer na Fase 1 / No Composer dependencies in Phase 1.

## O que a Fase 1 entrega / What Phase 1 delivers

| PT | EN |
|---|---|
| Cadastro, login (e-mail ou usuário), logout | Sign-up, sign-in (e-mail or username), sign-out |
| Sessão endurecida + registro de sessões por dispositivo, com revogação | Hardened sessions + per-device session records with revocation |
| CSRF em todo POST, rate limit de login/cadastro, CSP estrita, headers de segurança | CSRF on every POST, login/sign-up rate limit, strict CSP, security headers |
| Dashboard, CRUD de projetos (UUID público, soft delete, cota por usuário) | Dashboard, project CRUD (public UUID, soft delete, per-user quota) |
| Configurações: perfil, idioma, troca de senha, sessões ativas | Settings: profile, language, password change, active sessions |
| Área admin por papel (`user` / `admin` / `superadmin`) | Role-based admin area |
| Audit log + logs separados (`application`, `security`, `ai`, `deployment`) com redação de segredos | Audit log + separate log channels with secret redaction |
| Migrations SQL com checksum | Checksummed SQL migrations |
| Interface bilíngue PT-BR / EN | Bilingual UI PT-BR / EN |
| `PathGuard` (anti path-traversal) pronto para a Fase 2 | `PathGuard` (anti path-traversal) ready for Phase 2 |
| 35 testes de segurança/integração | 35 security/integration tests |

---

## Instalação / Installation

### 1. Requisitos / Requirements
- PHP ≥ 8.2 com / with `pdo_mysql`, `mbstring`, `openssl`, `sodium`, `curl`
- MySQL ≥ 8.0 ou/or MariaDB ≥ 10.4 (produção: MariaDB ≥ 10.6 recomendado / recommended)

### 2. Configuração / Configuration
```bash
cp .env.example .env
```
Edite `.env` (banco, `APP_URL`, `APP_ENV=production`, `SESSION_SECURE_COOKIE=true`).
Edit `.env` (database, `APP_URL`, `APP_ENV=production`, `SESSION_SECURE_COOKIE=true`).

### 3. Banco / Database
Crie um usuário MySQL **da aplicação** (não use root em produção) / Create an **application** MySQL user (never root in production):
```sql
CREATE DATABASE saasfactory_main CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'saasfactory'@'localhost' IDENTIFIED BY '<strong-password>';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, REFERENCES ON saasfactory_main.* TO 'saasfactory'@'localhost';
```
> A Fase 2 usará um segundo usuário, `DB_PROVISIONER_*`, só no worker CLI, para criar bancos `sf_project_*`.
> Phase 2 adds a second, CLI-only `DB_PROVISIONER_*` account to create `sf_project_*` databases.

```bash
php bin/migrate.php            # aplica migrations / run migrations
php bin/migrate.php status     # lista / list
php bin/migrate.php --create-db  # (dev) cria o banco antes / create DB first
```

### 4. Primeiro admin / First admin
Cadastre-se pela interface e promova via CLI (nunca por HTTP) / Sign up in the UI, then promote via CLI (never over HTTP):
```bash
php bin/set-role.php voce@exemplo.com superadmin
```

### 5. Permissões / Permissions (Linux)
```bash
chown -R www-data:www-data storage
find storage -type d -exec chmod 750 {} \;
chmod 640 .env
```

### 6. Webserver
O document root é **somente** `public/` / The document root is **only** `public/`.

**Nginx**
```nginx
server {
    listen 443 ssl http2;
    server_name app.example.com;
    root /var/www/saas-factory/public;
    index index.php;

    location / { try_files $uri /index.php$is_args$args; }

    location = /index.php {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/index.php;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
    # Nenhum outro .php executa / No other .php is executed
    location ~ \.php$ { return 404; }
    location ~ /\. { deny all; }

    client_max_body_size 10m;
    # ssl_certificate … (Certbot)
}
server { listen 80; server_name app.example.com; return 301 https://$host$request_uri; }
```

**Apache**: aponte o `DocumentRoot` para `public/` com `AllowOverride All` (o `public/.htaccess` já faz o rewrite e bloqueia outros `.php`).
**Apache**: point `DocumentRoot` to `public/` with `AllowOverride All` (`public/.htaccess` handles rewrites and blocks other `.php`).

### 7. Worker / cron
Chega na Fase 2 (`php bin/worker.php` via systemd). Nada a configurar agora.
Arrives in Phase 2 (`php bin/worker.php` via systemd). Nothing to set up yet.

### Desenvolvimento local / Local development
```bash
php -S localhost:8080 -t public public/index.php
```

---

## Testes / Tests
```bash
php tests/run.php            # tudo / all
php tests/run.php isolation  # filtro / filter
```
Os testes recriam um banco descartável `<DB_DATABASE>_test` a cada execução.
Tests recreate a disposable `<DB_DATABASE>_test` database on every run.

Cobertura / Coverage: path traversal (25 variantes), CSRF, SQL injection no login, rate limit, fixação de sessão, revogação de sessão, **isolamento A×B de projetos** (ver/editar/atualizar/excluir/buscar → 404), soft delete, cota, XSS armazenado, papel admin, audit log sem segredos, open redirect.

---

## Segurança / Security checklist (Fase 1)

- [x] PDO + prepared statements, `EMULATE_PREPARES=false`, SQL só em `app/Repositories`
- [x] `password_hash` / `password_verify` / rehash automático, verificação em tempo constante para usuário inexistente
- [x] CSRF (token por sessão, `hash_equals`, rotação no login/logout)
- [x] `session_regenerate_id` no login/logout, rotação a cada 15 min, timeout ocioso, `HttpOnly`, `SameSite=Lax`, `Secure` em HTTPS, `use_strict_mode`
- [x] Rate limit (login por conta+IP e por IP; cadastro por IP) — IP real só via `TRUSTED_PROXIES`
- [x] CSP sem `unsafe-inline`, `X-Frame-Options: DENY`, `nosniff`, `Referrer-Policy`, `Permissions-Policy`, HSTS em HTTPS
- [x] Escape de HTML em toda saída (`e()`), redirects apenas locais
- [x] IDs internos nunca expostos (UUID v4 nas URLs); acesso a projeto alheio = 404
- [x] Erros amigáveis; stack trace apenas com `APP_ENV=local` + `APP_DEBUG=true`
- [x] Logs sem senha/token/API key (redação automática)
- [x] Segredos apenas em `.env`, fora do `public/`

## Estrutura / Layout
```
app/        Core, Controllers, Services, Repositories, Models, Middleware, Policies, Validators, Security, Support, Database
bin/        migrate.php, set-role.php
config/     app, database, security, ai
database/   migrations/
docs/       ARCHITECTURE.md
lang/       pt-BR.php, en.php
public/     index.php, assets/  ← único diretório público / only public dir
storage/    logs, cache, temp, sessions, projects, backups
tests/      run.php
views/      layouts, partials, auth, dashboard, projects, settings, admin, errors
```

## v0.2 — Fábrica / Factory

| PT | EN |
|---|---|
| Criar projeto → build automático em fila (worker CLI) | Create project → automatic queued build (CLI worker) |
| Estratégia (Gemini), Design (GPT), Código (Claude) — configurável por `.env` | Strategy, Design, Code agents — provider per agent in `.env` |
| Modo demonstração sem chaves (gera um SaaS real localmente) | Demo mode without keys (builds a real SaaS locally) |
| Workspace + banco MySQL + usuário MySQL próprios por projeto | Own workspace, MySQL database and MySQL user per project |
| Ações da IA validadas (schema, caminho, extensão, scanner, SQL guard, `php -l`) | AI actions validated (schema, path, extension, scanner, SQL guard, `php -l`) |
| QA automático: abre cada página do preview e corrige a que falhar | Automatic QA: opens every preview page and fixes failures |
| Preview isolado (`open_basedir`, sem shell, host separado) com login automático | Isolated preview (`open_basedir`, no shell, separate host) with auto-login |
| Planos (Gratuito/Starter/Pro/Business), pacotes de créditos, Stripe Checkout + webhooks idempotentes | Plans, credit packs, Stripe Checkout + idempotent webhooks |
| Registro de custo por chamada de IA (`ai_usage`) | Per-call AI cost tracking |

```bash
php bin/worker.php                    # fila / queue (produção: systemd)
php bin/credits.php email@x.com 1000  # ajuste de créditos / credit adjustment
php bin/generate-key.php              # APP_KEY
```

## Próximo passo / Next step
Editor conversacional (Fase 7: "adicione controle de estoque" → nova versão só com o necessário), restauração de versões, publicação em produção (Fase 8), catálogo/instalador de módulos (Fase 5) e pool PHP-FPM por projeto em produção.