# frozen_string_literal: true # lib_registro.rb — Fuente de verdad de cuotas Y del valor real de cada key # ============================================================================== # NEXXA-F1 (P200, evolucionado en P201/Fase2-3 — D045 §10/§11) — registro propio, # inspirado en apirot.rb (P121, dtic-GEMMA) pero con delta de dominio: campo # 'provider'/'cuenta_origen' (D045 §2.3/§11) y, desde P201/Fase2, el VALOR REAL # cifrado de cada key (D045 §10: NEXXA es la fuente de verdad, ya no candados, # para API keys de terceros). 'identificador' es una ETIQUETA legible (ej. # 'gemini-01'), no el secreto — el secreto vive solo en 'valor_cifrado', nunca # en texto plano en disco ni en ningún log (ME-293/296). # # Dos ejes distintos, no confundir (corrección P201/Fase3, D045 §11): # - cuenta_origen: PERMANENTE — qué cuenta ante el proveedor generó esta key. # Informativo, nunca filtro de acceso (pool compartido, D045 §8). # - ultimo_individuo / reservar / reportar / lib_usos.rb: EFÍMERO — qué individuo # del ecosistema APIDs la tiene asignada ahora (o la tuvo la última vez). Una # key se reclama y se libera — no tiene "dueño" en ese sentido. # ============================================================================== # NO hace: no llama a los providers externos, no valida las keys en sí — solo # lleva el registro declarado (alta vía mini-app o cli_registrar.rb) # ============================================================================== # Salud real de keys (P204/Fase3, D045 §8) — el CONSUMIDOR es el árbitro del # agotamiento, no NEXXA: solo él le pegó al proveedor real. reservar() aplica # una reserva corta de contención al dispensar (evita doble-asignación # concurrente, sin asumir agotamiento); reportar() recibe la señal real # ('sana' renueva, 'liberada' suelta, 'agotada' recién ahí bloquea con # disponible_desde). Ver registro.json: campos reservado_por/reservado_hasta. # ============================================================================== require 'json' require 'time' require_relative 'lib_cripto' require_relative 'lib_usos' module Nexxa module Registro STATE_FILE = File.expand_path('registro.json', __dir__).freeze # Reserva corta de contención (P204/Fase3, D045 §8) — no asume agotamiento, # solo evita que 2 consumidores reciban la misma key mientras uno la está # probando. Vence sola (evaluada en self.disponible, sin proceso de limpieza # aparte) si nadie reporta nada; self.reportar la renueva o la libera. RESERVA_TTL_SEGUNDOS = 600 def self.leer if File.exist?(STATE_FILE) JSON.parse(File.read(STATE_FILE)) else { 'keys' => [] } end rescue JSON::ParserError { 'keys' => [] } end def self.guardar(state) File.write(STATE_FILE, JSON.pretty_generate(state) + "\n") end # provider: "gemini"/"groq"/... ; identificador: ETIQUETA legible (ej. "gemini-01"), # nunca el secreto ; cuenta_origen: cuenta ante el proveedor que generó la key — # PERMANENTE, informativo, no filtro de acceso (D045 §8/§11) ; reset_segundos: # ciclo de cuota del proveedor, se persiste para que marcar_uso pueda recalcular # disponible_desde sin que el caller tenga que volver a pasarlo ; valor: el # secreto en texto plano — se cifra acá mismo, nunca se persiste sin cifrar # (nil = alta solo de metadata, compatibilidad con registros viejos aún no # migrados, D045 §9→§10). ultimo_uso: nil (default) = key nueva/sin agotar, # disponible YA — nunca se asume 'se usó ahora' (bug real encontrado en # P200/Fase4: registrar una key recién creada la dejaba "agotada" 24h por # error, ME-603). Pasar ultimo_uso explícito solo cuando se sabe que la key # SÍ se agotó en ese momento. def self.registrar(provider:, identificador:, cuenta_origen:, reset_segundos:, valor: nil, ultimo_uso: nil) state = leer ahora = Time.now disponible_desde = ultimo_uso ? (Time.parse(ultimo_uso) + reset_segundos).iso8601(3) : ahora.iso8601(3) ultimo_uso ||= ahora.iso8601(3) valor_cifrado = valor ? cifrar(valor) : nil existente = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador } if existente existente.merge!( 'ultimo_uso' => ultimo_uso, 'disponible_desde' => disponible_desde, 'cuenta_origen' => cuenta_origen, 'reset_segundos' => reset_segundos ) existente['valor_cifrado'] = valor_cifrado if valor_cifrado else state['keys'] << { 'provider' => provider, 'identificador' => identificador, 'cuenta_origen' => cuenta_origen, 'reset_segundos' => reset_segundos, 'ultimo_uso' => ultimo_uso, 'ultimo_individuo' => nil, 'disponible_desde' => disponible_desde, 'valor_cifrado' => valor_cifrado, 'activo' => true, 'reservado_por' => nil, 'reservado_hasta' => nil } end guardar(state) state end # Edita metadata de una key existente (P201/Fase3) — NUNCA el valor (eso no # se re-muestra, se reemplaza vía 'registrar' con un valor nuevo si hace # falta rotarlo). Cada parámetro es opcional: solo se actualiza lo pasado. def self.actualizar(provider:, identificador:, cuenta_origen: nil, reset_segundos: nil, activo: nil) state = leer entrada = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador } raise "Key no encontrada: #{provider}/#{identificador}" unless entrada entrada['cuenta_origen'] = cuenta_origen unless cuenta_origen.nil? entrada['reset_segundos'] = reset_segundos unless reset_segundos.nil? entrada['activo'] = activo unless activo.nil? guardar(state) entrada end IDENTIFICADOR_VALIDO = /\A[a-z0-9][a-z0-9._-]{0,63}\z/.freeze # Cambia el identificador de una key (P335/Fase 13). Único dentro del provider; rechazado mientras esté RESERVADA # (el consumidor que la tiene reportaría con el nombre viejo). El historial previo de usos queda con el nombre # anterior (log append-only) y se registra el evento 'renombrada'. Los pools los actualiza el llamador (Pools). def self.renombrar(provider:, de:, a:, usuario: nil, ahora: Time.now) a = a.to_s.strip raise "Identificador inválido: '#{a}' (minúsculas, números, punto, guion o guion bajo)" unless a.match?(IDENTIFICADOR_VALIDO) return leer['keys'].find { |k| k['provider'] == provider && k['identificador'] == de } if a == de state = leer entrada = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == de } raise "Key no encontrada: #{provider}/#{de}" unless entrada raise "Ya existe #{provider}/#{a}" if state['keys'].any? { |k| k['provider'] == provider && k['identificador'] == a } if entrada['reservado_hasta'] && Time.parse(entrada['reservado_hasta']) > ahora raise "#{provider}/#{de} está reservada por #{entrada['reservado_por']}: esperá a que la libere para renombrarla" end entrada['identificador'] = a guardar(state) Nexxa::Usos.registrar(provider: provider, identificador: a, individuo: usuario ? "web:#{usuario}" : 'web', en: ahora, evento: "renombrada (antes #{de})") entrada end # Elimina una key del registro — destructivo, sin deshacer (P201/Fase3). # No borra su historial en lib_usos.rb (log append-only, queda como evidencia). def self.eliminar(provider:, identificador:) state = leer existia = state['keys'].reject! { |k| k['provider'] == provider && k['identificador'] == identificador } guardar(state) if existia !existia.nil? end # Todas las keys, solo metadata — para la vista de consulta de la mini-app # (P201/Fase3). Nunca incluye valor_cifrado, bajo ningún caso (Regla 15). def self.todas leer['keys'].map { |k| k.reject { |campo, _| campo == 'valor_cifrado' } } end # Descifra y devuelve el valor real de una key — SOLO para el endpoint HTTP # autenticado (Fase 2/2.4). El router de apids chat (router.rb) nunca llama # a esto — sigue devolviendo solo metadata, texto plano sin el secreto. def self.revelar(provider:, identificador:) entrada = leer['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador } return nil unless entrada && entrada['valor_cifrado'] descifrar(entrada['valor_cifrado']) end # Reserva corta de contención al dispensar (P204/Fase3, D045 §8) — reemplaza # el bloqueo ciego de la vieja marcar_uso: NO asume agotamiento, solo evita # que 2 consumidores reciban la misma key mientras uno la está probando. # disponible_desde queda intacto — el agotamiento real solo lo aplica # self.reportar(estado: 'agotada'), con la señal del consumidor. Se llama # automático al dispensar (server.rb, GET /disponible). def self.reservar(provider:, identificador:, individuo:) state = leer entrada = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador } raise "Key no encontrada: #{provider}/#{identificador}" unless entrada ahora = Time.now entrada['ultimo_uso'] = ahora.iso8601(3) entrada['ultimo_individuo'] = individuo entrada['reservado_por'] = individuo entrada['reservado_hasta'] = (ahora + RESERVA_TTL_SEGUNDOS).iso8601(3) guardar(state) Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: individuo, en: ahora, evento: 'dispensada') entrada end # Reporte real del consumidor sobre una key que tiene reservada (P204/Fase3, # D045 §8) — el consumidor es el árbitro de salud, no NEXXA (solo él le pegó # al proveedor real). Exige reservado_por == individuo — nadie reporta el # estado de una key que no tiene reservada. # 'sana' → renueva la reserva (sigue activo, evita que le venza en uso) # 'liberada' → libera la reserva ya, sin tocar disponible_desde (buen # ciudadano que terminó antes de tiempo) # 'agotada' → recién acá se aplica el bloqueo real: disponible_desde = # ahora + (liberar_en_segundos si el proveedor dio una pista # real, si no el reset_segundos registrado como fallback) # # P334/Fase 4 (GEMMA, 2026-10-04): quien marcó una key 'agotada' puede DESHACER su propio reporte con # 'liberada' aunque ya no la tenga reservada (agotada_por == individuo y el bloqueo sigue vigente). Caso real # 2026-10-01 19:46: un 429 por minuto reportado como agotada bloqueó el pool compartido y el consumidor no podía # revertirlo (409). Solo el autor del reporte: nadie libera lo que bloqueó otro. def self.reportar(provider:, identificador:, individuo:, estado:, liberar_en_segundos: nil, motivo: nil) state = leer entrada = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador } raise "Key no encontrada: #{provider}/#{identificador}" unless entrada ahora = Time.now if estado == 'liberada' && entrada['reservado_por'] != individuo && revertible_por?(entrada, individuo, ahora) entrada['disponible_desde'] = ahora.iso8601(3) entrada['agotada_por'] = nil guardar(state) Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: individuo, en: ahora, evento: 'revertida') return entrada end raise "Key #{provider}/#{identificador} no está reservada por #{individuo}" unless entrada['reservado_por'] == individuo case estado when 'sana' entrada['reservado_hasta'] = (ahora + RESERVA_TTL_SEGUNDOS).iso8601(3) when 'liberada' entrada['reservado_por'] = nil entrada['reservado_hasta'] = nil when 'agotada' reset_segundos = entrada['reset_segundos'] raise "Key #{provider}/#{identificador} sin reset_segundos persistido — no se puede reportar agotada" unless reset_segundos entrada['disponible_desde'] = (ahora + (liberar_en_segundos || reset_segundos)).iso8601(3) entrada['agotada_por'] = individuo entrada['motivo_agotada'] = motivo.to_s[0, 200] unless motivo.to_s.empty? entrada['reservado_por'] = nil entrada['reservado_hasta'] = nil Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: individuo, en: ahora, evento: 'agotada') else raise "estado inválido: #{estado} (esperado: sana|liberada|agotada)" end guardar(state) entrada end # Liberación por un ADMIN desde nexxa-web (P335/Fase 7): la key queda disponible ya, sin reserva ni marca de # agotada, sea quien sea que la bloqueó. El rastro queda en usos ('liberada-admin', con el usuario de la web). def self.liberar_admin(provider:, identificador:, usuario:) state = leer entrada = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador } raise "Key no encontrada: #{provider}/#{identificador}" unless entrada ahora = Time.now entrada['disponible_desde'] = ahora.iso8601(3) if Time.parse(entrada['disponible_desde']) > ahora entrada['reservado_por'] = nil entrada['reservado_hasta'] = nil entrada['agotada_por'] = nil entrada['motivo_agotada'] = nil guardar(state) Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: "web:#{usuario}", en: ahora, evento: 'liberada-admin') entrada end # ¿individuo puede deshacer el 'agotada' de esta key? Solo si lo reportó él y el bloqueo sigue vigente. def self.revertible_por?(entrada, individuo, ahora = Time.now) entrada['agotada_por'] == individuo && Time.parse(entrada['disponible_desde']) > ahora end # Estado del pool de un provider, por key, SIN el valor (P334/Fase 4): para diagnosticar desde un consumidor sin # entrar a la mini-app. estado: inactiva | agotada | reservada | disponible. def self.estado_pool(provider, ahora = Time.now) estado_de(leer['keys'].select { |k| k['provider'] == provider }, ahora) end # Estado de las keys de un pool (P335/Fase 5): mezcla proveedores, por eso cada fila trae su provider. def self.estado_en(refs, ahora = Time.now) estado_de(de_refs(refs), ahora) end def self.estado_de(keys, ahora = Time.now) keys.map do |k| estado = if k['activo'] == false then 'inactiva' elsif Time.parse(k['disponible_desde']) > ahora then 'agotada' elsif k['reservado_hasta'] && Time.parse(k['reservado_hasta']) > ahora then 'reservada' else 'disponible' end { 'provider' => k['provider'], 'identificador' => k['identificador'], 'estado' => estado, 'libera_en' => (estado == 'agotada' ? k['disponible_desde'] : nil), 'reservado_por' => (estado == 'reservada' ? k['reservado_por'] : nil), 'agotada_por' => (estado == 'agotada' ? k['agotada_por'] : nil), 'motivo' => (estado == 'agotada' ? k['motivo_agotada'] : nil), 'ultimo_uso' => k['ultimo_uso'], 'ultimo_individuo' => k['ultimo_individuo'] } end end def self.cifrar(valor) Nexxa::Cripto.new(Nexxa::MasterKey.cargar!).encrypt(valor) end def self.descifrar(valor_cifrado) Nexxa::Cripto.new(Nexxa::MasterKey.cargar!).decrypt(valor_cifrado) end # Devuelve la key elegible MENOS USADA RECIENTEMENTE del provider (rotación # del pool, P204/Fase4, propuesta del Operador) — nil si ninguna es elegible. # Antes usaba el primer match del array: si la primera key nunca se agotaba, # las demás no se usaban jamás y quedaban en riesgo de que el proveedor las # diera de baja por inactividad. min_by sobre ultimo_uso rota el pool solo, # sin estado adicional (nil = nunca usada, va primero). Elegible = 'activo' # ausente/true (compat keys viejas), disponible_desde vencido, y # reservado_hasta ausente/nil/vencido (compat keys pre-P204/Fase3 — la # reserva vence sola acá, evaluada al consultar, sin limpieza aparte). def self.disponible(provider) elegir_libre(leer['keys'].select { |k| k['provider'] == provider }) end # Igual que disponible, pero dentro de un POOL (P335/Fase 4): refs "provider/identificador" que pueden mezclar # proveedores. La menos usada recientemente entre las libres, sin importar el proveedor. def self.disponible_en(refs) elegir_libre(de_refs(refs)) end def self.proxima_en(refs) de_refs(refs).select { |k| k['activo'] != false }.min_by { |k| Time.parse(k['disponible_desde']) } end def self.de_refs(refs) refs = Array(refs) leer['keys'].select { |k| refs.include?("#{k['provider']}/#{k['identificador']}") } end # Criterio ÚNICO de "libre ahora" (activa, no agotada, sin reserva vigente) y de cuál dar (la menos usada). def self.elegir_libre(keys) ahora = Time.now keys .select do |k| k['activo'] != false && Time.parse(k['disponible_desde']) <= ahora && (k['reservado_hasta'].nil? || Time.parse(k['reservado_hasta']) <= ahora) end .min_by { |k| k['ultimo_uso'] ? Time.parse(k['ultimo_uso']) : Time.at(0) } end # Próxima key de un provider a liberarse (para responder explícito, nunca # silencioso) — también excluye desactivadas, nunca las ofrece como "próxima". def self.proxima(provider) leer['keys'] .select { |k| k['provider'] == provider && k['activo'] != false } .min_by { |k| Time.parse(k['disponible_desde']) } end end end