¿Por qué está bloqueada la licencia de este cliente?
Un ingeniero de soporte recibe un ticket que dice que una licencia "no se activa", pero el cliente falla cerrado y solo informa "bloqueado". Aquí tienes una herramienta de diagnóstico de solo lectura, construida sobre la API de administración de Keyright, que reproduce todo el pipeline de verificación en modo explicativo e informa exactamente qué comprobación falló —caducidad, revocación, vinculación de máquina, un asiento o una prestación ausente— sin exponer jamás la clave.
Un ingeniero de soporte abre un ticket: “El cliente ACME dice que la aplicación no se activa — solo dice que la licencia está bloqueada.” Esa es toda la información que hay, porque un cliente de licencias correctamente construido está diseñado para no dar nada más. Falla cerrado, deniega el acceso e informa de un único estado opaco. El ingeniero ahora tiene que averiguar si la suscripción caducó, la clave fue revocada, todos los asientos están ocupados, el cliente se cambió a una máquina nueva, o simplemente está en un plan que nunca incluyó la función que intenta usar — y debe hacerlo sin el único artefacto que lo haría trivial y peligroso de compartir: la clave firmada.
Es un problema resoluble, y la solución no es hacer al cliente más hablador. Es una pequeña herramienta de diagnóstico de solo lectura que habla con el servicio emisor a través de la API de administración de Keyright y reproduce el pipeline de verificación en un modo que explica en lugar de aplicar.
El cliente responde una pregunta; soporte necesita otra
La verificación dentro del cliente es un pipeline con cortocircuito. Ejecuta una secuencia fija de comprobaciones —¿es auténtica la firma, está el “ahora” dentro de la ventana de validez, está la clave en la lista de revocación, es esta la máquina a la que está vinculada la licencia, hay un asiento libre, concede la licencia la función que se pide— y en el momento en que una comprobación falla, se detiene y deniega. Nunca evalúa las comprobaciones posteriores al fallo, porque no lo necesita: la respuesta ya es no.
// Inside the client: fail-closed, short-circuiting, deliberately opaque.
LicenseInfo info = client.Validate(); // offline, never throws
if (!info.IsValid)
return Gate.Deny("This copy is not licensed. Contact your administrator.");
info.IsValid es un único booleano. El usuario ve “sin licencia”. Ese es el comportamiento correcto para un binario sujeto a cumplimiento, y es exactamente la razón por la que soporte no puede trabajar a partir de él. La pregunta que soporte necesita responder no es “¿está bloqueado?” —ya saben que lo está— sino “qué comprobación falló, y por qué”. Responder eso significa ejecutar el mismo pipeline contra el registro autoritativo del servicio emisor, pero con el cortocircuito desactivado, de modo que cada comprobación informe su propio veredicto en lugar de que el primer fallo se trague el resto.
Un endpoint de diagnóstico de solo lectura
El servicio emisor ya tiene el registro autoritativo de cada licencia: su ventana de validez, si ha sido revocada, a qué máquina está vinculada y cuántos de sus asientos están actualmente arrendados. La API de administración expone una vista de diagnóstico de solo lectura de ese registro. Toma un identificador no secreto —un id de licencia, o una huella corta de la clave que el cliente puede leer en su pantalla “Acerca de”— y, opcionalmente, una huella de máquina informada por el cliente, para que la comprobación de vinculación de nodo también pueda evaluarse.
GET /v1/admin/licenses/lic_7f3a9c2e/diagnose?machine=fp_9b21c4 HTTP/1.1
Host: licensing.example.com
Authorization: Bearer {admin_read_token}
La respuesta es el pipeline, evaluado por completo. Cada comprobación lleva su propio veredicto —pass, fail o unknown— y un fail lleva un code legible por máquina más un detail humano. Crucialmente, nada hace cortocircuito: el fail en la comprobación de asiento no impide que la comprobación de prestación informe, salvo cuando una comprobación genuinamente no puede evaluarse del lado del servidor.
{
"licenseId": "lic_7f3a9c2e",
"keyFingerprint": "KR…c4e1",
"product": "acme-suite",
"edition": "pro",
"overall": "blocked",
"checks": [
{ "gate": "signature", "verdict": "pass" },
{ "gate": "dateWindow", "verdict": "pass", "expiresOn": "2027-03-01T00:00:00Z" },
{ "gate": "revocation", "verdict": "pass" },
{ "gate": "machine", "verdict": "pass", "detail": "Reported fingerprint matches the bound host." },
{ "gate": "seat", "verdict": "fail", "code": "seats_exhausted",
"detail": "5 of 5 seats are leased. Oldest lease expires in 00:11:42." },
{ "gate": "entitlement","verdict": "unknown",
"detail": "Not reached by the client; not evaluated without a requested feature." }
]
}
El token de lectura es la palabra importante. Este endpoint es solo GET y el alcance del token no concede nada más que lecturas — no puede revocar, revincular, extender ni liberar un asiento. Un ingeniero de soporte que puede diagnosticar no debería, por tener esa capacidad, poder también repartir capacidad gratis en silencio. La remediación es una acción separada y auditada tras un alcance distinto.
La herramienta de soporte
Con un endpoint de solo lectura, la propia herramienta es delgada: obtener el diagnóstico, representar la lista de comprobaciones y encabezar con la primera comprobación que falla — porque esa es en la que el cliente realmente se detuvo y la que el cliente está golpeando.
public sealed class LicenseDoctor(HttpClient admin)
{
public async Task<Diagnosis> LookUpAsync(string handle, string? machine, CancellationToken ct)
{
var url = $"/v1/admin/licenses/{Uri.EscapeDataString(handle)}/diagnose";
if (machine is not null) url += $"?machine={Uri.EscapeDataString(machine)}";
return (await admin.GetFromJsonAsync<Diagnosis>(url, ct))!;
}
public static void Print(Diagnosis d)
{
Console.WriteLine($"License {d.KeyFingerprint} ({d.Product}/{d.Edition}) → {d.Overall.ToUpper()}");
foreach (var c in d.Checks)
{
var mark = c.Verdict switch
{
"pass" => "[ok] ",
"fail" => "[FAIL]",
_ => "[?] ",
};
Console.WriteLine($" {mark} {c.Gate,-12} {c.Detail}");
}
var cause = d.Checks.FirstOrDefault(c => c.Verdict == "fail");
if (cause is not null)
Console.WriteLine($"\nRoot cause: {cause.Gate} — {cause.Code}\n{cause.Detail}");
}
}
public sealed record Diagnosis(string LicenseId, string KeyFingerprint, string Product,
string Edition, string Overall, IReadOnlyList<Check> Checks);
public sealed record Check(string Gate, string Verdict, string? Code = null, string? Detail = null);
Ejecutada contra el ticket de ACME, imprime toda la historia de un vistazo:
License KR…c4e1 (acme-suite/pro) → BLOCKED
[ok] signature
[ok] dateWindow expires 2027-03-01
[ok] revocation
[ok] machine Reported fingerprint matches the bound host.
[FAIL] seat 5 of 5 seats are leased. Oldest lease expires in 00:11:42.
[?] entitlement Not reached by the client; not evaluated without a requested feature.
Root cause: seat — seats_exhausted
5 of 5 seats are leased. Oldest lease expires in 00:11:42.
El ticket queda ahora respondido en una línea: ACME no está roto, ni caducado, ni en el plan equivocado — simplemente ha usado todos los asientos que compró, y un arriendo se libera en once minutos. El ingeniero les dice que esperen, cierren una sesión o compren más asientos, y nadie pasa una tarde persiguiendo una caducidad que nunca fue el problema.
Leer la comprobación de prestación
La única comprobación que marca unknown por defecto es la de prestación, y la razón merece decirse con claridad: las prestaciones se evalúan contra una función que la aplicación pidió. La vista de diagnóstico no sabe qué función buscaba el cliente, así que no puede decir si esa concesión concreta está presente hasta que se lo digas. Pasa la clave de la función y se resuelve:
GET /v1/admin/licenses/lic_7f3a9c2e/diagnose?feature=feature.export HTTP/1.1
{ "gate": "entitlement", "verdict": "fail", "code": "not_granted",
"detail": "This license grants max_projects=10 but not feature.export (Standard edition)." }
Esas claves —feature.export, max_projects, max_major_version— son los propios nombres de prestación del proveedor, transportados en la concesión firmada y mostrados literalmente. El diagnóstico los lee directamente del registro autoritativo, de modo que “el cliente jura que pagó por la exportación” se resuelve al instante en “su edición no la incluye” — una conversación de ventas, no un error.
Advertencias, y la línea que la herramienta no debe cruzar
Tres límites mantienen esto honesto. Primero, la herramienta es de solo lectura por contrato: diagnóstico y remediación son alcances distintos, así que la capacidad de explicar un bloqueo nunca es la capacidad de deshacerlo en silencio. Segundo, dos comprobaciones dependen de hechos que el servidor no posee — la huella de máquina y el reloj local viven en el host del cliente, así que el diagnóstico solo puede marcarlas pass/fail cuando el cliente las informa y, en caso contrario, devuelve unknown. Un registro de servidor sano junto a un cliente bloqueado es la forma que tiene la herramienta de señalar exactamente esas dos cosas: una máquina movida o un reloj desajustado. Tercero, el diagnóstico es una instantánea en el momento en que soporte lo ejecuta — un asiento que estaba agotado a las 14:02 puede estar libre a las 14:05 — así que los tiempos de arriendo que imprime son orientativos, no una garantía.
Y la línea que no debe cruzar: la clave nunca entra en el flujo. La herramienta identifica una licencia por id o huella, la respuesta devuelve solo una huella, y la transcripción de soporte que sobrevive al ticket no lleva nada con lo que un lector pudiera activar. Una herramienta de diagnóstico existe para convertir “solo dice bloqueado” en “asientos agotados, se libera en once minutos” — para hacer legible para un humano el cliente que falla cerrado — mientras revela exactamente tan poco como el propio cliente.
Prueba Nebula.NET
Endurece tu código .NET en minutos — empieza con la edición gratuita.