🔐 OAuth e tokens

OAuth 2.0 é o protocolo que permite ao Postiz postar no seu LinkedIn sem nunca ver sua senha. Em vez disso, o usuário aprova um consent screen, e o provedor devolve um access token com escopo limitado (ex.: "publicar posts", mas não "ler mensagens privadas").

O fluxo mais usado para apps com backend é o Authorization Code Flow: o usuário é redirecionado para o provedor, autoriza, volta para uma redirect URI registrada com um code de uso único, e o backend troca esse code por um token.

Fluxo Authorization Code passo a passo

Conceitos-chave

O provedor devolve dois tokens com propósitos opostos. Confundir os dois é o erro nº1 de quem começa: vazar um access token é incômodo (expira em horas), vazar um refresh token é incidente de segurança grave (vale meses).

Conceitos-chave

Tokens em texto puro no banco é o mesmo que guardar senhas em texto puro: catastrófico se houver leak. O padrão da indústria é encrypt at rest com AES-256-GCM, usando uma chave mestra que vive em variável de ambiente — nunca no código.

AES-256-GCM dá dois benefícios: criptografia simétrica forte (256 bits) e autenticação (GCM detecta se o ciphertext foi adulterado). Sempre use IV aleatório por registro — reusar IV em GCM quebra o esquema inteiro.

// crypto.service.ts — encrypt/decrypt de tokens
import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';

const KEY = Buffer.from(process.env.TOKEN_ENCRYPTION_KEY!, 'hex'); // 32 bytes

export function encryptToken(plaintext: string): string {
  const iv = randomBytes(12);                              // 96 bits, único por registro
  const cipher = createCipheriv('aes-256-gcm', KEY, iv);
  const enc = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
  const tag = cipher.getAuthTag();
  // formato: iv.tag.ciphertext (todos em base64)
  return [iv, tag, enc].map(b => b.toString('base64')).join('.');
}

export function decryptToken(blob: string): string {
  const [iv, tag, enc] = blob.split('.').map(s => Buffer.from(s, 'base64'));
  const decipher = createDecipheriv('aes-256-gcm', KEY, iv);
  decipher.setAuthTag(tag);
  return Buffer.concat([decipher.update(enc), decipher.final()]).toString('utf8');
}

Conceitos-chave

Postar a 1h da manhã com token expirado é o pesadelo clássico. A solução é um interceptor que checa expires_at antes de cada chamada e renova proativamente, mais um retry com novo token caso a API retorne 401 mesmo assim.

O exemplo abaixo é o coração de qualquer integração OAuth séria: três blocos em ordem — preflight check, chamada, retry on 401.

// social-api.client.ts — request com refresh automático
async function apiCall(account: SocialAccount, url: string, body: any) {
  // 1) Preflight: renova se faltam menos de 5 min
  if (account.expiresAt.getTime() - Date.now() < 5 * 60_000) {
    await refreshAccessToken(account);
  }

  let token = decryptToken(account.accessToken);

  // 2) Chamada
  let res = await fetch(url, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  // 3) Retry com novo token se o provedor expirou antes do esperado
  if (res.status === 401) {
    await refreshAccessToken(account);
    token = decryptToken(account.accessToken);
    res = await fetch(url, {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });
  }

  if (!res.ok) throw new Error(`API error ${res.status}: ${await res.text()}`);
  return res.json();
}

async function refreshAccessToken(account: SocialAccount) {
  const refresh = decryptToken(account.refreshToken);
  const r = await fetch(account.provider.tokenUrl, {
    method: 'POST',
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refresh,
      client_id: process.env[`${account.provider.name}_CLIENT_ID`]!,
      client_secret: process.env[`${account.provider.name}_CLIENT_SECRET`]!,
    }),
  });
  const data = await r.json();
  account.accessToken = encryptToken(data.access_token);
  if (data.refresh_token) account.refreshToken = encryptToken(data.refresh_token); // rotativo
  account.expiresAt = new Date(Date.now() + data.expires_in * 1000);
  await account.save();
}

Conceitos-chave

Provedores grandes não liberam scopes sensíveis (como "publicar posts") sem que seu app passe por App Review. Em modo dev o app só funciona com contas dos próprios desenvolvedores; para qualquer usuário externo postar, a review é obrigatória.

O que acelera a aprovação

Conceitos-chave

Enquanto Meta e LinkedIn te fazem esperar semanas, o fediverso resolve o mesmo problema em minutos. Bluesky (AT Protocol) e Mastodon (ActivityPub) seguem outra filosofia: instâncias abertas, autenticação por App Password ou OAuth dinâmico, sem comitê de revisão.

Para um MVP que precisa rodar essa semana, ou para qualquer self-hosted que não quer depender da boa vontade de empresas privadas, esses dois são o caminho rápido.

# Bluesky — autenticação direta via App Password
# Settings > App Passwords > gera uma string tipo abcd-efgh-ijkl-mnop

curl -X POST https://bsky.social/xrpc/com.atproto.server.createSession \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "seu-handle.bsky.social",
    "password": "abcd-efgh-ijkl-mnop"
  }'
# Devolve { accessJwt, refreshJwt, did, handle } — pronto para postar.

# Mastodon — registra app via API e autoriza usuário
curl -X POST https://mastodon.social/api/v1/apps \
  -d 'client_name=MeuApp' \
  -d 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' \
  -d 'scopes=write:statuses'

Conceitos-chave