Spider Bucket · API

Armazenamento de objetos estilo Cloudflare R2, com os bytes criptografados (crypt/AEAD) na sua conta Google Drive. Buckets são pastas de topo; objetos têm chaves (caminho/arquivo.ext).

Autenticação

Toda chamada de API usa Authorization: Bearer <token>. O token pode ser:

• API key (dbk_...) — criada por você, com escopos e buckets limitados.
• ADMIN_TOKEN — controle total, inclusive gerenciar chaves (impresso ao subir o servidor; fica no .state.json ou no .env).

O painel local (mesma máquina, 127.0.0.1) é tratado como admin automaticamente — não precisa de token no navegador.

Escopos

Uma chave também pode ser restrita a buckets específicos (allowlist) ou a todos (*).

Criando uma API key

# precisa de admin (ADMIN_TOKEN ou painel local)
curl -X POST http://127.0.0.1:8787/api/keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"meu-app","scopes":["read","write"],"buckets":["fotos"],"expires_in":2592000}'

# resposta (o "secret" aparece SÓ aqui — guarde):
{"ok":true,"data":{"id":"k1a2b3...","secret":"dbk_k1a2b3..._xxxxx","scopes":["read","write"],...}}

Upload / Download

# criar bucket
curl -X PUT http://127.0.0.1:8787/r2/fotos -H "Authorization: Bearer $KEY"

# upload (corpo cru, streaming)
curl -X PUT http://127.0.0.1:8787/r2/fotos/2026/a.jpg \
  -H "Authorization: Bearer $KEY" --data-binary @a.jpg

# download
curl http://127.0.0.1:8787/r2/fotos/2026/a.jpg \
  -H "Authorization: Bearer $KEY" -o a.jpg

# listar (paginado) e stats
curl "http://127.0.0.1:8787/r2/fotos?recursive=1&limit=100" -H "Authorization: Bearer $KEY"
curl "http://127.0.0.1:8787/r2/fotos?stats=1" -H "Authorization: Bearer $KEY"

URLs pré-assinadas

Gere um link temporário para baixar/enviar UM objeto sem expor a chave:

# gerar (GET, válido 1h)
curl -X POST http://127.0.0.1:8787/api/presign \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"bucket":"fotos","key":"2026/a.jpg","method":"GET","expires_in":3600}'
# -> {"url":"/r2/fotos/2026/a.jpg?exp=...&sig=...","expires_at":...}

# baixar sem token, direto pela URL assinada
curl "http://127.0.0.1:8787/r2/fotos/2026/a.jpg?exp=...&sig=..." -o a.jpg

Todos os endpoints