"""Chaves de serviço nomeadas (ADR 0027 §10): emitir, listar e revogar sem reiniciar o serviço. Formato: `dvk__`. - 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 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())