Files
MateuusandClaude Opus 5.5 84f30bbc2d CenaForge: primeira versão pública
Gerador de vídeos narrativos (Godot + FFmpeg), painel Next.js, serviço de voz,
Clipador de lives e Publicador para YouTube, TikTok e Instagram.

Inclui a leitura das visualizações dos posts para o Dashboard e o botão
"Publicar no <rede>" nos cartões das publicações.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 16:35:09 -03:00

311 lines
12 KiB
Python

"""Chaves de serviço nomeadas (ADR 0027 §10): emitir, listar e revogar sem reiniciar o serviço.
Formato: `dvk_<keyId 12>_<segredo 32 bytes em base64url>`.
- O arquivo guarda só o SHA-256 do segredo, mais `keyId`, `name`, `scopes`, `createdAt` e `revokedAt`.
O segredo tem 256 bits, então não precisa de KDF lenta.
- A busca é por `keyId` (não é segredo); a comparação do hash é em tempo constante.
- O arquivo fica no volume de dados (`/data/keys/service_keys.json`), fora do Git. O serviço relê quando ele muda.
- A `VOICE_SERVICE_KEY` do `.env` continua aceita como a chave `env`: partida e recuperação, com todos os escopos.
CLI (dentro do container, que já tem `VOICE_DATA_DIR`):
python -m app.keys create --name backend-prod --scopes tts,transcribe,status
python -m app.keys list
python -m app.keys revoke <keyId>
A chave em claro só aparece na saída do `create`. Nunca vai para log nem para arquivo.
"""
from __future__ import annotations
import argparse
import base64
import contextlib
import hashlib
import hmac
import json
import logging
import os
import re
import secrets
import sys
import threading
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
try: # o container é Linux; no Windows (fora do container) o CLI roda sem trava entre processos
import fcntl
except ImportError: # pragma: no cover
fcntl = None # type: ignore[assignment]
SCOPES = ("tts", "transcribe", "convert", "status", "admin")
KEY_PREFIX = "dvk_"
KEY_ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789"
KEY_ID_LENGTH = 12
SECRET_BYTES = 32
KEY_RE = re.compile(r"^dvk_([a-z0-9]{12})_([A-Za-z0-9_-]{43})$")
KEY_ID_RE = re.compile(r"^[a-z0-9]{12}$")
NAME_RE = re.compile(r"^[A-Za-z0-9._-]{1,64}$")
SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
ENV_KEY_ID = "env"
FILE_VERSION = 1
log = logging.getLogger("cenaforge_voice.keys")
class KeyFileError(RuntimeError):
"""Arquivo de chaves ilegível ou fora do formato."""
@dataclass(frozen=True)
class Principal:
"""Quem chamou: só o que pode aparecer em log e no /v1/status (nunca a chave)."""
key_id: str
name: str
scopes: frozenset[str]
@dataclass(frozen=True)
class KeyRecord:
key_id: str
name: str
scopes: tuple[str, ...]
secret_sha256: str
created_at: str
revoked_at: str | None = None
def to_json(self) -> dict:
return {
"keyId": self.key_id, "name": self.name, "scopes": list(self.scopes),
"secretSha256": self.secret_sha256, "createdAt": self.created_at, "revokedAt": self.revoked_at,
}
def public(self) -> dict:
"""Sem o hash: o que o `list` mostra."""
data = self.to_json()
del data["secretSha256"]
return data
def keys_path(data_dir: Path) -> Path:
return data_dir / "keys" / "service_keys.json"
def _hash_secret(secret: str) -> str:
return hashlib.sha256(secret.encode("ascii")).hexdigest()
def _now() -> str:
return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
def parse_scopes(raw: str) -> tuple[str, ...]:
scopes = sorted({part.strip() for part in raw.split(",") if part.strip()})
if not scopes:
raise ValueError("informe ao menos um escopo")
unknown = [s for s in scopes if s not in SCOPES]
if unknown:
raise ValueError(f"escopo desconhecido: {', '.join(unknown)} (válidos: {', '.join(SCOPES)})")
return tuple(scopes)
def _parse_record(item: object) -> KeyRecord:
if not isinstance(item, dict):
raise KeyFileError("entrada não é objeto")
key_id, name, scopes, digest = item.get("keyId"), item.get("name"), item.get("scopes"), item.get("secretSha256")
created, revoked = item.get("createdAt"), item.get("revokedAt")
if not (isinstance(key_id, str) and KEY_ID_RE.fullmatch(key_id)):
raise KeyFileError("keyId inválido")
if not (isinstance(name, str) and NAME_RE.fullmatch(name)):
raise KeyFileError("name inválido")
if not (isinstance(scopes, list) and scopes and all(isinstance(s, str) and s in SCOPES for s in scopes)):
raise KeyFileError("scopes inválidos")
if not (isinstance(digest, str) and SHA256_RE.fullmatch(digest)):
raise KeyFileError("secretSha256 inválido")
if not isinstance(created, str) or not (revoked is None or isinstance(revoked, str)):
raise KeyFileError("datas inválidas")
return KeyRecord(key_id, name, tuple(sorted(set(scopes))), digest, created, revoked)
def read_records(path: Path) -> list[KeyRecord]:
"""Lê e valida o arquivo inteiro. Arquivo ausente = nenhuma chave nomeada."""
try:
raw = path.read_text(encoding="utf-8")
except FileNotFoundError:
return []
try:
data = json.loads(raw)
except ValueError:
raise KeyFileError("JSON ilegível") from None
if not isinstance(data, dict) or data.get("version") != FILE_VERSION or not isinstance(data.get("keys"), list):
raise KeyFileError("formato do arquivo desconhecido")
records = [_parse_record(item) for item in data["keys"]]
if len({r.key_id for r in records}) != len(records):
raise KeyFileError("keyId repetido")
return records
def _write_records(path: Path, records: list[KeyRecord]) -> None:
"""Grava atômico (arquivo temporário 0600 + rename) para o serviço nunca ler um arquivo pela metade."""
payload = json.dumps({"version": FILE_VERSION, "keys": [r.to_json() for r in records]}, indent=2) + "\n"
tmp = path.with_name(f".{path.name}.{secrets.token_hex(6)}.tmp")
fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
try:
with os.fdopen(fd, "w", encoding="utf-8") as handle:
handle.write(payload)
handle.flush()
os.fsync(handle.fileno())
os.replace(tmp, path)
except BaseException:
with contextlib.suppress(FileNotFoundError):
os.unlink(tmp)
raise
@contextlib.contextmanager
def _locked(path: Path):
"""Trava entre processos do CLI (leitura-alteração-gravação). O serviço só lê."""
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
if fcntl is None: # pragma: no cover
yield
return
fd = os.open(path.with_name(".lock"), os.O_RDWR | os.O_CREAT, 0o600)
try:
fcntl.flock(fd, fcntl.LOCK_EX)
yield
finally:
fcntl.flock(fd, fcntl.LOCK_UN)
os.close(fd)
def issue_key(path: Path, name: str, scopes: tuple[str, ...]) -> tuple[KeyRecord, str]:
"""Emite uma chave. Devolve o registro e a chave em claro, que o chamador mostra uma vez e descarta."""
if not NAME_RE.fullmatch(name):
raise ValueError("nome inválido: use 1 a 64 caracteres entre letras, números, '.', '_' e '-'")
scopes = parse_scopes(",".join(scopes))
with _locked(path):
records = read_records(path)
taken = {r.key_id for r in records}
key_id = "".join(secrets.choice(KEY_ID_ALPHABET) for _ in range(KEY_ID_LENGTH))
while key_id in taken: # pragma: no cover - 36^12 combinações
key_id = "".join(secrets.choice(KEY_ID_ALPHABET) for _ in range(KEY_ID_LENGTH))
secret = base64.urlsafe_b64encode(secrets.token_bytes(SECRET_BYTES)).decode("ascii").rstrip("=")
record = KeyRecord(key_id, name, scopes, _hash_secret(secret), _now())
_write_records(path, [*records, record])
return record, f"{KEY_PREFIX}{key_id}_{secret}"
def revoke_key(path: Path, key_id: str) -> KeyRecord:
"""Marca `revokedAt` (o registro fica para auditoria). Revogar de novo não muda a data."""
with _locked(path):
records = read_records(path)
for index, record in enumerate(records):
if record.key_id == key_id:
if record.revoked_at is None:
record = KeyRecord(
record.key_id, record.name, record.scopes, record.secret_sha256, record.created_at, _now()
)
records[index] = record
_write_records(path, records)
return record
raise LookupError(key_id)
class KeyRing:
"""Autenticação do serviço: chave `env` + chaves nomeadas do arquivo, relido quando muda.
Arquivo ilegível → nenhuma chave nomeada vale (falha fechada); a chave `env` continua valendo para recuperar.
"""
def __init__(self, path: Path, env_key: str):
self._path = path
self._env_key = env_key.encode("utf-8")
self._env = Principal(ENV_KEY_ID, ENV_KEY_ID, frozenset(SCOPES))
self._lock = threading.Lock()
self._signature: tuple | None = ("never-loaded",)
self._records: dict[str, KeyRecord] = {}
# Hash fixo para a comparação quando o keyId não existe: o tempo não diz se o keyId existe.
self._dummy = _hash_secret(secrets.token_urlsafe(SECRET_BYTES))
def _stat_signature(self) -> tuple | None:
try:
st = os.stat(self._path)
except FileNotFoundError:
return None
return (st.st_ino, st.st_mtime_ns, st.st_size)
def _refresh(self) -> None:
signature = self._stat_signature()
if signature == self._signature:
return
with self._lock:
if signature == self._signature:
return
try:
records = {r.key_id: r for r in read_records(self._path)}
except (KeyFileError, OSError) as exc:
records = {}
log.error("arquivo de chaves rejeitado (%s); só a chave env vale até ele ser corrigido", exc)
self._records = records
self._signature = signature
active = sum(1 for r in records.values() if r.revoked_at is None)
log.info("chaves de serviço carregadas: %d ativa(s), %d revogada(s)", active, len(records) - active)
def authenticate(self, provided: str) -> Principal | None:
self._refresh()
match = KEY_RE.fullmatch(provided)
principal: Principal | None = None
if match:
key_id, secret = match.groups()
record = self._records.get(key_id)
expected = record.secret_sha256 if record else self._dummy
if hmac.compare_digest(_hash_secret(secret), expected) and record and record.revoked_at is None:
principal = Principal(record.key_id, record.name, frozenset(record.scopes))
# A chave env é sempre comparada (tempo constante em relação ao conteúdo), casando ou não com o formato dvk_.
env_ok = hmac.compare_digest(provided.encode("utf-8"), self._env_key)
if principal is None and env_ok:
principal = self._env
return principal
def _data_dir() -> Path:
return Path(os.environ.get("VOICE_DATA_DIR", "/data"))
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(prog="python -m app.keys", description="Chaves de serviço do dropsz_voice.")
sub = parser.add_subparsers(dest="command", required=True)
create = sub.add_parser("create", aliases=["issue"], help="emite uma chave e mostra-a uma única vez")
create.add_argument("--name", required=True)
create.add_argument("--scopes", required=True, help=f"lista separada por vírgula: {','.join(SCOPES)}")
sub.add_parser("list", help="lista as chaves (sem segredo nem hash)")
revoke = sub.add_parser("revoke", help="revoga uma chave pelo keyId")
revoke.add_argument("key_id")
args = parser.parse_args(argv)
path = keys_path(_data_dir())
try:
if args.command in ("create", "issue"):
record, plaintext = issue_key(path, args.name, parse_scopes(args.scopes))
print(f"keyId: {record.key_id}\nname: {record.name}\nscopes: {','.join(record.scopes)}")
print("chave (aparece só agora; guarde no cofre do backend):")
print(plaintext)
elif args.command == "list":
print(json.dumps([r.public() for r in read_records(path)], indent=2, ensure_ascii=False))
else:
if not KEY_ID_RE.fullmatch(args.key_id):
print("keyId inválido", file=sys.stderr)
return 2
record = revoke_key(path, args.key_id)
print(f"revogada: {record.key_id} ({record.name}) em {record.revoked_at}")
except LookupError:
print("keyId não encontrado", file=sys.stderr)
return 1
except (ValueError, KeyFileError) as exc:
print(f"erro: {exc}", file=sys.stderr)
return 2
return 0
if __name__ == "__main__": # pragma: no cover
raise SystemExit(main())