Proveedor de identidad (OAuth 2.0 + OpenID Connect) del ecosistema de Inled Group y de desarrolladores externos. Zero-knowledge por diseño: el servidor nunca ve la contraseña ni el perfil en claro.
- Runtime: Cloudflare Workers (TypeScript)
- Router: Hono (entrada del Worker) + Astro 7 para las páginas
- Datos: Cloudflare D1 (usuarios, clientes OAuth y códigos temporales)
- Cripto: Web Crypto API +
jose(ES256) - Sin KV: la sesión SSO es una cookie JWT firmada y los códigos viven en D1
Requisitos: Node 22+ y una cuenta de Cloudflare solo para desplegar (en local no hace falta).
npm install
npm run gen:keys # crea .dev.vars con PEPPER_KEY, SERVER_ENC_KEY, SIGNING_JWK
npm run db:init # aplica schema.sql en la D1 local (.wrangler/state)
npm run db:seed # clientes OAuth de demostración (solo desarrollo)
npm run devAbre http://localhost:4321. El servidor de desarrollo ejecuta el Worker real (workerd) con D1 local, así que las rutas de Hono y las páginas de Astro comparten entorno, base de datos y sesión.
Si
npm run devdice que ya hay otro servidor:npx astro dev stop.
| Comando | Qué hace |
|---|---|
npm run dev |
Worker + Astro en local (puerto 4321) |
npm run check |
Typecheck de todo el proyecto (astro check) |
npm run build |
astro check + build del Worker |
npm run test:e2e |
Smoke test del flujo completo (requiere npm run dev en marcha) |
npm run db:init / db:init:remote |
Aplicar el esquema en D1 local / remota |
npm run gen:keys -- --force |
Rotar los secretos locales |
Con npm run dev funcionando, en otra terminal:
npm run test:e2eEl script (scripts/e2e-check.mjs) usa el mismo src/lib/crypto-client.js que el navegador y
comprueba, contra el servidor real:
- registro zero-knowledge y login derivando claves en cliente;
/api/auth/me, sesión y logout;- autorización OAuth con PKCE, pantalla de consentimiento y canje del código;
- que el código es de un solo uso y que un
code_verifierincorrecto falla; id_tokenverificado con el JWKS (ES256),nonceyat_hash;/oauth/userinfocon Bearer token y rechazo de tokens manipulados;- cliente de primera parte (sin consentimiento) y cliente confidencial (HTTP Basic);
redirect_urino registrada y PKCE obligatorio.
-
Registro: http://localhost:4321/register. Al terminar se muestra la Recovery Key; descárgala. Puedes activar la copia recuperable del perfil para que el servidor pueda devolver claims
email/nameen/userinfo. -
Sesión: http://localhost:4321/developers crea un cliente OAuth. Verás el
client_secretuna sola vez. -
OAuth: monta la URL de autorización y ábrela:
http://localhost:4321/oauth/authorize?response_type=code &client_id=ic_demo_spa &redirect_uri=http%3A%2F%2Flocalhost%3A4321%2Fdemo-callback &scope=openid%20profile%20email &state=abc &code_challenge=<S256 del verifier> &code_challenge_method=S256ic_demo_spa(terceros) muestra la pantalla de consentimiento;ic_inled_notes(primera parte, secretodev-secret-change-me) la omite. El callback de demo no existe como página, así que el navegador acabará en un 404 con?code=...en la URL: es lo esperado, el código ya está emitido.
Los clientes de seeds.sql solo existen en local.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /.well-known/openid-configuration |
Descubrimiento OIDC |
| GET | /jwks.json |
Clave pública ES256 |
| GET | /oauth/authorize |
Authorization Code + PKCE S256 |
| POST | /oauth/authorize/decision |
Consentimiento (formulario) |
| POST | /oauth/token |
Canje del código (authorization_code) |
| GET | /oauth/userinfo |
Claims del usuario (Bearer) |
| POST | /api/auth/salt |
Parámetros KDF del email (con señuelo determinista) |
| POST | /api/auth/register |
Alta zero-knowledge |
| POST | /api/auth/login |
Verificación de authKey + cookie de sesión |
| POST | /api/auth/logout |
Borra la cookie |
| GET | /api/auth/session |
sub de la sesión actual |
| GET | /api/auth/me |
Material cifrado del propio usuario |
| DELETE | /api/auth/account |
Eliminar la cuenta (exige la contraseña) |
| GET/POST | /api/clients |
Listar / registrar clientes OAuth |
| DELETE | /api/clients/:id |
Eliminar un cliente propio |
PKCE (S256) es obligatorio para todos los clientes, también confidenciales (RFC 9700).
public/iccount.js es el equivalente a "Sign in with Google": se carga desde Iccount y pinta el
botón, hace PKCE, canjea el código y expone el usuario. No se descarga: se referencia por URL.
<script src="https://iccount.inled.es/iccount.js"
data-client-id="ic_..."
data-redirect-uri="https://miapp.example/callback"></script>
<div data-iccount-login></div>
<script>
Iccount.on('signedin', ({ user }) => console.log(user.sub, user.email));
</script>La documentación para integradores (y para pasarle a una IA) está en
public/iccount-ai-brief.md, enlazada desde Developer options.
- La interfaz está en español e inglés según
Accept-Language(inglés por defecto). - Con sesión iniciada,
/,/loginy/registerredirigen a/account. - Tras registrarse,
/account?welcome=1muestra la bienvenida y la clave de recuperación (una sola vez, víasessionStorage), con botón de descarga.
masterBits = PBKDF2-SHA256(password, kdfSalt, 600.000 iteraciones)→ 256 bits.authKey = HKDF-SHA256(masterBits, salt="iccount-hkdf-v1", info="iccount/auth/v1")→ se envía.encryptionKey = HKDF-SHA256(..., info="iccount/enc/v1")→ nunca sale del navegador.- Se genera una
userKeyAES-256-GCM aleatoria:- cifra
encrypted_emailyencrypted_profile(nombre, avatar, email); - se envuelve con
encryptionKey→encrypted_user_key; - se envuelve con la Recovery Key →
recovery_wrapped_user_key.
- cifra
email_blind_index = HMAC-SHA256(email normalizado, subclave HKDF de PEPPER_KEY). Búsqueda O(1) sin guardar el email.auth_hash = HMAC-SHA256(authKey, otra subclave de PEPPER_KEY). Comparación en tiempo constante./api/auth/saltdevuelve parámetros falsos pero deterministas para emails inexistentes, para no convertirse en un oráculo de cuentas.- Si el usuario acepta
email_recoverable, se guarda ademásrecoverable_profilecifrado con AES-256-GCM ySERVER_ENC_KEY: es lo único que permite devolver claimsemail/name/pictureen OIDC y mostrar el perfil en la pantalla de consentimiento. - Los códigos de autorización se guardan como
SHA-256y se consumen conDELETE ... RETURNING, garantizando un único uso. Los caducados se purgan en cada emisión/canje.
Cookie iccount_session: JWT ES256 con aud="iccount:session", HttpOnly; Secure; SameSite=Lax,
12 h por defecto (SESSION_TTL). El aud separa sesión, petición de consentimiento, access token e
id_token, de modo que ningún token sirve en otro contexto.
npx wrangler d1 create iccount # copia el database_id a wrangler.jsonc
npm run db:init:remote
npx wrangler secret put PEPPER_KEY # 32 bytes base64url
npx wrangler secret put SERVER_ENC_KEY # 32 bytes base64url
npx wrangler secret put SIGNING_JWK # JWK privada ES256 (JSON, una línea)
npm run deploywrangler.jsonc ya declara el dominio propio iccount.inled.es (routes + workers_dev: false)
y las variables ISSUER, ACCESS_TOKEN_TTL y SESSION_TTL, así que npm run deploy publica
directamente en https://iccount.inled.es. Los secretos viven solo en Cloudflare; nunca en el repo.
- La sesión es stateless. Cerrar sesión borra la cookie, pero un JWT ya emitido sigue siendo
válido hasta caducar. Para revocación inmediata haría falta una tabla de sesiones (o
jtien D1). /userinfosinemail. Si el usuario no opta por la copia recuperable, el servidor no puede leer su email: elsubes el único identificador estable entre apps.- No hay verificación de email (no se envían correos), así que no se emite
email_verified. - Recovery Key: se genera, se descarga y se guarda envuelta, pero el flujo de recuperación (reset de contraseña usando solo la Recovery Key) aún no está implementado.
- Sin rate limiting. En Workers sin KV/DO un contador fiable necesita D1 o Durable Objects; pendiente de decidir antes de exponerlo a internet.
- Rotación de claves: cambiar
SIGNING_JWKinvalida sesiones y access tokens vivos; no hay JWKS con varias claves todavía. - CSP se aplica solo fuera de
localhost(el cliente de Vite inyecta scripts en desarrollo). - Solo modo claro: Apple HIG sin variante oscura, por decisión de producto.
- El botón embebible guarda el token en
sessionStorage; para sesiones largas, canjea el código en tu backend y guarda el token en una cookieHttpOnly. - Los secretos locales de
.dev.varsy.wrangler/están fuera de git.
schema.sql Esquema D1 (usuarios, clientes, códigos)
seeds.sql Clientes OAuth de demo
wrangler.jsonc Bindings: D1 + vars (sin KV)
src/app.ts Entrada del Worker: Hono + Astro (`pages()`)
src/server/
crypto.ts HMAC, HKDF, blind index, AES-GCM de servidor
jwt.ts Firma/verificación ES256, JWKS, at_hash
session.ts Cookie de sesión JWT
db.ts Consultas D1 tipadas
routes/ auth, oauth, clients, discovery
src/lib/crypto-client.js Criptografía del navegador (PBKDF2, HKDF, AES-GCM)
src/i18n.ts Textos es/en y selección por Accept-Language
src/pages/ Landing, registro, login, cuenta, consentimiento, developer options
src/scripts/ Lógica de cliente de cada página
public/iccount.js Botón embebible "Continuar con Iccount" (PKCE incluido)
public/iccount-ai-brief.md Guía de integración para IAs
scripts/gen-keys.mjs Generación de secretos locales
scripts/e2e-check.mjs Smoke test del flujo completo