Documentación de la API

easysecret.dev es una API REST para guardar y compartir secretos cifrados de extremo a extremo. El servidor almacena únicamente datos ya cifrados — nunca la clave de descifrado. Cada secreto se destruye en el momento de su primera lectura.

https://easysecret.dev

Autenticación

Los endpoints de secretos aceptan peticiones sin autenticar (plan Free: 10 req/día · 300/mes por IP) o con una API key en la cabecera Authorization (planes con cuota mensual).

Authorization: Bearer es_live_aBcDeFgHiJkLmNoPqRsTuVwX

Formato de la key

Las keys tienen el prefijo es_live_ seguido de 32 caracteres en base64url. El servidor las almacena en claro en la base de datos local SQLite.

Planes y límites

El plan determina la cuota mensual de peticiones y el TTL máximo permitido para los secretos. Las peticiones sin API key se cuentan por IP con una ventana diaria.

Rate Limiting

El endpoint de signup tiene un límite propio por IP para frenar altas masivas. El resto de endpoints usan los límites del plan descrito arriba.

Al superar el límite el servidor devuelve 429 con el mensaje de error correspondiente.

Errores

Todos los errores devuelven JSON con el campo error y el código HTTP correspondiente.

{ "error": "descripción del error" }

Crea una cuenta nueva y devuelve la API key. No requiere autenticación. La key se muestra una única vez en la respuesta — guárdala antes de cerrar.

Cuerpo de la petición

Ejemplo

curl -X POST https://easysecret.dev/api/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"tu@ejemplo.com"}'

{
  "email":   "tu@ejemplo.com",
  "api_key": "es_live_aBcDeFgHiJkLmNoPqRsTuVwX",  // ⚠ solo aquí
  "plan":    "basic",
  "message": "Guarda tu api_key, no se mostrará de nuevo."
}

Respuestas de error

Almacena un secreto ya cifrado en Redis con un TTL. El servidor guarda el texto cifrado y el IV — nunca la clave de descifrado, que el cliente pasa solo en el fragmento de URL (#).

Autenticación

Opcional. Sin Authorization el límite del plan Free es 10 peticiones/día · 300/mes por IP. Con API key se usa la cuota del plan.

Cuerpo de la petición

Ejemplo — cifrar en el navegador y guardar

// 1. Generar clave e IV aleatorios
const iv  = crypto.getRandomValues(new Uint8Array(12));
const key = await crypto.subtle.generateKey(
  { name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]
);

// 2. Cifrar
const encoded = new TextEncoder().encode("mi secreto");
const cipher  = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, encoded);

// 3. Exportar clave (para el fragmento #) y IV (para la API)
const rawKey     = await crypto.subtle.exportKey("raw", key);
const ivBase64   = btoa(String.fromCharCode(...iv));
const cipherB64  = btoa(String.fromCharCode(...new Uint8Array(cipher)));
const keyBase64  = btoa(String.fromCharCode(...new Uint8Array(rawKey)))
                     .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

// 4. Guardar en la API
const res  = await fetch("/api/secret", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ ivBase64, cipherBase64: cipherB64 })
});
const { id } = await res.json();

// 5. Construir enlace — la clave NUNCA va al servidor
const link = `https://easysecret.dev/ver/${id}#${keyBase64}`;

curl -X POST https://easysecret.dev/api/secret \
  -H "Authorization: Bearer es_live_aBcDeFgHiJkLmNoPqRsTuVwX" \
  -H "Content-Type: application/json" \
  -d '{"ivBase64":"aXZfdGVzdA==","cipherBase64":"Y2lwaGVy","ttl":3600}'

{
  "id":                 "550e8400-e29b-41d4-a716-446655440000",
  "expires_in_seconds": 3600
}

Respuestas de error

Lee y destruye atómicamente el secreto. Tras esta llamada el secreto desaparece de Redis para siempre — no se puede volver a leer. El descifrado ocurre en el cliente usando la clave que va en el fragmento # de la URL.

Parámetros de ruta

Ejemplo — leer y descifrar en el navegador

curl https://easysecret.dev/api/secret/550e8400-e29b-41d4-a716-446655440000

{
  "ivBase64":     "aXZfdGVzdA==",
  "cipherBase64": "Y2lwaGVy..."
}

// La clave viene del fragmento # de la URL (nunca del servidor)
const keyB64UrlSafe = window.location.hash.substring(1);
let keyB64 = keyB64UrlSafe.replace(/-/g, '+').replace(/_/g, '/');
while (keyB64.length % 4) keyB64 += '=';

const base64ToBuf = b64 => Uint8Array.from(atob(b64), c => c.charCodeAt(0)).buffer;

const key = await crypto.subtle.importKey(
  "raw", base64ToBuf(keyB64), { name: "AES-GCM" }, false, ["decrypt"]
);

const res  = await fetch(`/api/secret/${secretId}`);
const data = await res.json();

const decrypted = await crypto.subtle.decrypt(
  { name: "AES-GCM", iv: base64ToBuf(data.ivBase64) },
  key,
  base64ToBuf(data.cipherBase64)
);
const plainText = new TextDecoder().decode(decrypted);

Respuestas de error

Zero-Knowledge

El diseño de easysecret garantiza que el servidor nunca puede acceder al contenido de un secreto, incluso con acceso completo a la base de datos y a Redis.

Esto significa que incluso si el servidor fuera comprometido, el atacante solo obtendrá texto cifrado sin la clave — ilegible sin el fragmento de URL.

TTL y caducidad

Cada secreto tiene un tiempo de vida (TTL) configurable. Transcurrido ese tiempo Redis expira la entrada automáticamente y el secreto desaparece sin necesidad de limpiezas manuales.

Si pasas un ttl mayor al máximo del plan, el servidor lo trunca silenciosamente al máximo permitido. El campo expires_in_seconds de la respuesta indica el TTL que se aplicó realmente.

Destrucción atómica

La lectura del secreto usa la operación atómica GETDEL de Redis, que lee y borra en una sola instrucción. Esto garantiza que no hay ventana de tiempo entre la lectura y la eliminación — incluso bajo carga alta.

Una vez que GET /api/secret/:id devuelve 200, el secreto ya no existe en Redis. Reintentar la petición devolverá 404.