# Hospedagem: JWT Bearer e headers de autenticação

## Recomendação para integradores (produção e cPanel)

**Use o header `X-Kombex-Authorization`** com o mesmo valor que seria enviado em `Authorization`:

```http
X-Kombex-Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
```

Alternativa equivalente: **`X-Access-Token`** com o JWT **sem** o prefixo `Bearer`.

Na prática, em **Apache + PHP como CGI ou FastCGI** (comum no cPanel), o header padrão **`Authorization`** frequentemente não chega ao PHP — mesmo com `.htaccess` correto. Por isso a documentação principal da API e a coleção Postman adotam **`X-Kombex-Authorization`** como padrão; `Authorization: Bearer ...` continua suportado quando o servidor repassa (vários ambientes locais).

O CORS em `public/index.php` já permite `Authorization`, `X-Kombex-Authorization` e `X-Access-Token`.

---

### Se a API retornar 401 com `"Token ausente ou inválido"`

1. Confirme que envia **`X-Kombex-Authorization: Bearer <access_token>`** (ou `X-Access-Token`).
2. Se insistir em `Authorization` apenas, ajuste o servidor conforme as seções abaixo (Apache/Nginx) ou peça ao suporte o repasse desse header ao PHP.

O projeto inclui `public/.htaccess` com regras de repasse e `CGIPassAuth On`; em parte dos planos isso **não** resolve — o header alternativo permanece a solução estável.

---

## cPanel: não sei se é Nginx ou Apache

Em **hospedagem compartilhada com cPanel** o mais comum é:

| Servidor web | Observação |
|--------------|------------|
| **Apache** | Muito frequente; costuma respeitar `.htaccess` na pasta do site. |
| **LiteSpeed (LSWS)** | Também muito comum no cPanel; em geral aceita as mesmas regras de `.htaccess` do Apache. |
| **Nginx na frente + Apache atrás** | O provedor cuida do proxy; você em geral só mexe em **Apache** via `.htaccess` na sua conta. |
| **Só Nginx (sem Apache)** | Mais raro em plano compartilhado “puro”; típico de VPS onde você administra tudo. |

**Ou seja:** na prática você quase sempre age como se fosse **Apache/LiteSpeed** até provar o contrário: manter o `public/.htaccess` do repositório e o **Document Root** do subdomínio apontando para a pasta `public` da API (veja *Subdomínios* ou *Domínios* no cPanel).

### Como descobrir no cPanel (sem ser técnico)

1. **PHP Info** — No cPanel: *Software* → *Select PHP Version* ou *MultiPHP INI Editor*; às vezes há link *phpinfo*. Procure por **`Server API`** e **`SERVER_SOFTWARE`**:
   - Se aparecer `Apache`, `LiteSpeed` ou `litespeed`, está no mundo Apache/LiteSpeed.
   - Se sua hospedagem só mostrar “CGI/FastCGI”, ainda assim o servidor web atrás costuma ser Apache ou LiteSpeed.
2. **Pergunte ao suporte** — Uma frase resolve: *“O servidor web do meu plano é Apache, LiteSpeed ou Nginx? Preciso repassar o header Authorization para PHP.”*
3. **Script de teste** — Use o arquivo da [seção 6](#6-teste-rápido-no-servidor) abaixo e complemente com:

```php
'SERVER_SOFTWARE' => $_SERVER['SERVER_SOFTWARE'] ?? null,
```

Abra no navegador; `SERVER_SOFTWARE` costuma começar com `Apache`, `LiteSpeed` ou mencionar `nginx`.

### O `.htaccess` mínimo que você descreveu está correto

`RewriteEngine`, `RewriteCond %{HTTP:Authorization}` e o `RewriteRule` com `[E=HTTP_AUTHORIZATION:...]` são o padrão certo. Em **muitos planos cPanel** o PHP roda como **CGI/FastCGI** e só isso **não basta** — o Apache precisa também de **`CGIPassAuth On`** (Apache 2.4.13+) para encaminhar o header ao PHP.

O **`public/.htaccess`** deste repositório inclui `CGIPassAuth On` e `SetEnvIf Authorization` como reforço. **Copie a versão atual do repositório para o servidor.** Se após colar der **erro 500**, seu plano pode bloquear essa diretiva — remova só o bloco `CGIPassAuth` e peça ao suporte habilitar o repasse do header `Authorization`.

### O que fazer primeiro no cPanel (ordem sugerida)

1. Confirmar que o subdomínio `api-desenv` (etc.) aponta para a pasta **`.../kombex-api/public`** (ou equivalente), e não só para a raiz do projeto sem `public`.
2. Garantir que o **`public/.htaccess`** no servidor está **igual ao do repositório** (com `CGIPassAuth` + `SetEnvIf`, se o servidor aceitar).
3. Rodar o teste da seção 6 com header `Authorization: Bearer teste`. Se continuar `null`, abra chamado com o provedor citando: *“Authorization header not passed to PHP (FastCGI/CGI)”* — muitos têm receita pronta ou habilitam no servidor.

Em plano compartilhado você **não** costuma editar `nginx.conf`; se for Nginx gerenciado pelo host, o suporte aplica o `fastcgi_param`.

---

## 1. Nginx + PHP-FPM (muito comum em VPS)

Dentro do bloco `location ~ \.php$` (ou no `fastcgi_pass` que atende ao `index.php`), garanta que o FastCGI receba o header do cliente:

```nginx
location ~ ^/index\.php(/|$) {
    fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
    fastcgi_split_path_info ^(.+\.php)(/.*)$;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    fastcgi_param DOCUMENT_ROOT $realpath_root;

    # Repassa Authorization para o PHP (obrigatório em muitos setups)
    fastcgi_param HTTP_AUTHORIZATION $http_authorization;

    internal;
}
```

Se você usa um único `location ~ \.php$` sem `internal`, o essencial é **esta linha** junto dos demais `fastcgi_param`:

```nginx
fastcgi_param HTTP_AUTHORIZATION $http_authorization;
```

**Versão alternativa** (alguns guias usam quando a variável vem vazia):

```nginx
set $auth_header $http_authorization;
fastcgi_param HTTP_AUTHORIZATION $auth_header;
```

Recarregue o Nginx: `sudo nginx -t && sudo systemctl reload nginx`.

---

## 2. Apache — Virtual Host (DocumentRoot = `public/`)

Garanta que a raiz do site seja a pasta **`public`** da API e que mod_rewrite esteja ativo.

```apache
<VirtualHost *:443>
    ServerName api-desenv.kombex.log.br
    DocumentRoot /caminho/para/kombex-api/public

    <Directory /caminho/para/kombex-api/public>
        AllowOverride All
        Require all granted
    </Directory>

    # Opcional: se FastCGI/CGI ainda não enxergar Authorization, force o env:
    SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

    ErrorLog ${APACHE_LOG_DIR}/api-desenv-error.log
    CustomLog ${APACHE_LOG_DIR}/api-desenv-access.log combined
</VirtualHost>
```

O arquivo `public/.htaccess` do repositório já contém:

```apache
RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
```

Sem **`AllowOverride All`**, o `.htaccess` é ignorado e o header pode não chegar ao PHP.

---

## 3. Apache — URL com `/public/` no path

Se o DocumentRoot for a **pasta pai** (ex.: `.../kombex-api`) e a URL for `https://dominio/public/api/v1/...`, o `.htaccess` que vale é o de **`public/.htaccess`** (desde que requisições caiam em `public/`). Confirme no painel da hospedagem qual pasta é a raiz do subdomínio; o ideal é apontar o subdomínio **direto para `public/`** e usar URLs sem `/public/` no meio.

---

## 4. OpenLiteSpeed

No painel: **Virtual Hosts → sua vhost → Context** da pasta PHP, ou em **Rewrite**, assegure que headers de autorização sejam repassados. Em muitos casos a regra equivalente ao Apache `RewriteRule [E=HTTP_AUTHORIZATION:...]` pode ser configurada nas regras de rewrite do LiteSpeed; consulte a documentação “Environment Variables” / Authorization do seu painel.

---

## 5. Cloudflare / proxy reverso

Verifique se não há regra que **remove** o header `Authorization`. Page Rules e transformações podem alterar headers; o padrão costuma manter `Authorization` intacto.

---

## 6. Teste rápido no servidor

Use o arquivo **`public/check-auth-header.php`** do repositório (remova após o diagnóstico em produção).

Chame no navegador ou Postman, por exemplo:  
`https://seu-dominio/check-auth-header.php` — **GET** com header `Authorization: Bearer teste`.  
Repita o teste enviando também **`X-Kombex-Authorization: Bearer teste`**: se `HTTP_X_KOMBEX_AUTHORIZATION` vier preenchido, use esse header na API real (veja tabela acima).

Se `HTTP_AUTHORIZATION` e `REDIRECT_HTTP_AUTHORIZATION` vierem `null` mas `X-Kombex-Authorization` funcionar, use o fallback até o provedor corrigir o repasse de `Authorization`.

---

## 7. Código da API

O `JwtAuthMiddleware` lê o token nesta ordem: `Authorization`, depois **`X-Kombex-Authorization`**, depois **`X-Access-Token`**, com fallbacks em `$_SERVER`, `getenv` e `apache_request_headers`. Em Nginx **sem** `fastcgi_param HTTP_AUTHORIZATION`, o header `Authorization` pode continuar vazio; **`X-Kombex-Authorization` não depende dessa diretiva** e costuma funcionar em cPanel.