Emite tokens de capacidade de curta duração para objetos privados, autoriza requisições HTTP byte-range com o mesmo token, proíbe URLs públicas duráveis e registra a identidade do download no registro de auditoria.
Status do pacote: contexto de referência pronto para revisão humana. O contrato e os cenários de teste estão completos, mas não há garantia de que uma implementação adotante os tenha passado.
Decisão
Objetos privados nunca recebem um ACL público durável. Os baixadores recebem um token de capacidade de curta duração vinculado a sujeito, chave do objeto, HTTP GET, expiração e limites de byte-range. Requisições Range (RFC 9110) são tratadas como primeira classe: um token válido autoriza uma resposta parcial 206 dentro de max_range_bytes. Ranges maiores ou não vinculados são negados. Cada concessão bem-sucedida grava files.download.granted com identidade e range. Tokens expiram independentemente do tempo de vida do objeto. Sessões de upload do bloco relacionado de upload retomável não geram tokens de download até que o objeto esteja completo.
Escopo
- Autorização para ler blobs privados, incluindo retomada via Range.
- TTL do token, vinculação de chave, proibição de ACL e campos de auditoria.
- Emissão e verificação backend de tokens de capacidade ou URLs assinadas que atendam a este contrato.
Fora deste bloco
- Como os bytes foram enviados ou escaneados.
- Cache CDN de conteúdo privado (não deve converter um token em uma chave de cache pública).
- DRM de vídeo streaming.
Contrato
- Tokens carregam
expires_at; após esse instante, GET retornadownload_token_expirede zero bytes do objeto. - Um token válido autoriza
Rangeembytesatémax_range_bytes(8388608 neste perfil) e pode retornar 206. - Um Range maior que
max_range_bytesé negado mesmo que o token não tenha expirado. - Definir um ACL público permanente no objeto é rejeitado (
public_acl: forbidden). - Leituras bem-sucedidas emitem
files.download.grantedcomsubject_id,object_key, id do token e o range servido. - Tokens são vinculados a
object_keyetenant_id; trocar a chave na URL sem token correspondente falha.
Orientação de implementação
- Codifique método, chave, expiração e range máximo no token. Registre ids dos tokens, nunca segredos.
- Normalize Range; rejeite unidades não bytes acima de
max_range_bytes. O relógio do verificador não tem desvio neste perfil.
Tratamento de falhas e salvaguardas
- Falhas na gravação de auditoria negam o download. Sessões de upload incompletas não podem gerar tokens de download.
- Ranges insatisfatórios retornam 416. Reutilização dentro do TTL é permitida; TTL é o limite contra roubo.
Verificação e operações
- Testes: expiração, 206 dentro do limite, range grande, rejeição de ACL pública, campos de auditoria.
- Não cache 206 sem contexto de capacidade. TTL de 900 segundos é um valor de adoção.
Os exemplos executáveis neste pacote são fixtures e contratos de aceitação. Execute
python tools/validate.py a partir da raiz da coleção para verificar a estrutura e metadados do pacote; depois
implemente e execute os cenários no repositório alvo.
Suposições para adoção
- Nomes e valores numéricos em
example.yamlsão um perfil de adoção, não padrões universais. - A equipe adotante deve mapear atores, classes de dados, vocabulário de erros e propriedade para seu sistema.