Guía
Passkeys
Entrar con la huella, la cara o el PIN del dispositivo, sin contraseña que filtrar. ascua-passkey hace la ceremonia del navegador y la verificación en el servidor, sin dependencias.
Qué son
Una passkey es un par de claves que crea el dispositivo para un sitio. La privada no sale de él —o del llavero sincronizado de iCloud, Google o el gestor de contraseñas—; el servidor guarda solo la pública. Para entrar, el dispositivo firma un reto con la privada después de que el usuario lo desbloquee, y el servidor comprueba la firma.
No hay nada que robar en la base de datos ni que escribir en un sitio falso:
la passkey está atada al dominio, y en evil.example no existe.
stil add ascua-passkeyascua-passkey tiene dos partes: la del navegador (1,8 kB gzip) y
ascua-passkey/server, que verifica con Web Crypto en Node 20+, Deno, Bun y
un worker. Las dos hablan el JSON estándar de WebAuthn, así que el cliente
sirve igual contra un servidor en otro lenguaje.
Las dos ceremonias
Registrar, con el usuario ya identificado —tras entrar con su contraseña, por ejemplo—:
- El servidor crea las opciones con
registrationOptions()y guarda el reto. - El navegador llama a
register(options): el usuario confirma y el dispositivo crea la passkey. - El servidor la verifica con
verifyRegistration()y guardaid,publicKeyycounter.
Entrar:
- El servidor crea las opciones con
authenticationOptions()y guarda el reto. - El navegador llama a
authenticate(options): el usuario elige su passkey. - El servidor busca la passkey por
id, la verifica converifyAuthentication(), actualiza el contador y abre la sesión.
El reto es de un solo uso. Se guarda donde no se pueda reutilizar —una cookie firmada que se borra al verificar, una fila con caducidad— y se descarta tras la primera verificación, salga bien o mal.
Con el kit de sitios
En un sitio con mode: "server", las acciones guardan el reto en una cookie
firmada y la isla las llama con fetch, igual que hace enhance().
// src/routes/login.ts
import { authenticationOptions, verifyAuthentication } from "ascua-passkey/server";
import { fail, redirect, type ActionContext } from "vite-plugin-ascua/site";
import { PasskeyLoginIsland } from "../islands/passkey-login.js";
const RP_ID = "example.com";
const ORIGIN = "https://www.example.com";
export const actions = {
async options({ cookies }: ActionContext) {
const { options, challenge } = authenticationOptions({ rpId: RP_ID });
await cookies.setSigned("passkey-challenge", challenge, { maxAge: 300 });
return options;
},
async login({ formData, cookies }: ActionContext) {
const challenge = await cookies.getSigned("passkey-challenge");
cookies.delete("passkey-challenge"); // un solo uso, salga bien o mal
if (!challenge) return fail(401, { error: "Reto caducado" });
const response = JSON.parse(String(formData.get("credential")));
const passkey = await findPasskey(response.id);
if (!passkey) return fail(401, { error: "Passkey desconocida" });
try {
const { counter } = await verifyAuthentication(response, {
challenge, origin: ORIGIN, rpId: RP_ID, credential: passkey,
});
await updateCounter(passkey.id, counter);
} catch {
return fail(401, { error: "No se pudo verificar" });
}
await cookies.setSigned("session", passkey.userId, { maxAge: 60 * 60 * 24 * 7 });
throw redirect("/dashboard");
},
};
export default function Login() {
return view`<main><PasskeyLoginIsland/></main>`;
}// src/islands/passkey-login.ts
import { defineIsland, signal } from "ascua";
import { authenticate, PasskeyError, supported } from "ascua-passkey";
/** Llama a una acción de la página y devuelve lo que respondió. */
async function action(name: string, fields: Record<string, string> = {}) {
const body = new FormData();
for (const [key, value] of Object.entries(fields)) body.set(key, value);
const res = await fetch(`?/${name}`, { method: "POST", headers: { "x-ascua-action": "1" }, body });
return res.json();
}
function PasskeyLogin() {
const error = signal("");
async function signIn() {
error.set("");
try {
const options = await action("options");
const credential = await authenticate(options.data);
const result = await action("login", { credential: JSON.stringify(credential) });
if (result.type === "redirect") location.assign(result.location);
else error.set(result.data?.error ?? "No se pudo entrar");
} catch (e) {
if (e instanceof PasskeyError && e.code === "cancelled") return;
error.set(e instanceof Error ? e.message : String(e));
}
}
return view`
<div>
<button type="button" disabled=${!supported()} onclick=${signIn}>Entrar con passkey</button>
<p class="error">${() => error()}</p>
</div>`;
}
export const PasskeyLoginIsland = defineIsland("passkey-login", {}, PasskeyLogin);La acción responde en JSON porque la petición lleva x-ascua-action: 1:
{ type: "success", data }, { type: "failure", status, data } o
{ type: "redirect", location }. La comprobación de origen del kit vale igual
para estas peticiones.
Registrar es lo mismo con registrationOptions() y verifyRegistration(),
en una página a la que solo se llega con sesión. user.id es un
identificador opaco y estable —no el email—, y exclude lleva las passkeys
que el usuario ya tiene, para que el navegador no cree otra en el mismo
dispositivo:
async registerOptions({ cookies, locals }: ActionContext) {
const user = locals.user;
const { options, challenge } = registrationOptions({
rp: { id: RP_ID, name: "Example" },
user: { id: user.id, name: user.email },
exclude: (await passkeysOf(user.id)).map((p) => p.id),
});
await cookies.setSigned("passkey-challenge", challenge, { maxAge: 300 });
return options;
},En el navegador
supported(): boolean
conditionalSupported(): Promise<boolean>
register(options, { signal? }): Promise<RegistrationResponseJSON>
authenticate(options, { signal?, conditional? }): Promise<AuthenticationResponseJSON>Las opciones entran tal como llegan del servidor, con o sin { publicKey }
alrededor. Donde el navegador tiene parseCreationOptionsFromJSON y
toJSON(), se usan; donde no —Safari antes de la 17.4, Firefox antes de la
119—, la conversión de base64url se hace a mano.
Con conditional: true, authenticate no abre el diálogo: espera a que el
usuario elija su passkey en el autocompletado de un campo con
autocomplete="username webauthn". Se lanza al cargar la página, con un
AbortController para cancelarla si el usuario usa la contraseña, y solo si
conditionalSupported().
Un fallo es un PasskeyError con code:
code |
Qué pasó |
|---|---|
cancelled |
Cerró el diálogo, o no se completó. No hace falta un mensaje. |
exists |
Esa passkey ya está registrada en este dispositivo. |
timeout |
Se acabó el tiempo de las opciones. |
security |
El dominio no es el de la passkey, o la página no es segura. |
unsupported |
El navegador no admite passkeys. |
unknown |
Cualquier otra cosa: el error original va en cause. |
El mensaje sale en el idioma de <html lang>, español o inglés.
Dos reglas que no pone el paquete
Son de la aplicación, no de la ceremonia, y saltárselas abre un agujero:
- Confirmar antes de registrar. Una passkey es una forma de entrar que dura más que la sesión. Si registrarla solo pide estar dentro, quien robe una sesión deja la suya y vuelve cuando quiera. Pide la contraseña actual (o una passkey que ya tenga) en el paso que genera las opciones de registro.
- Revocar al recuperar la cuenta. Cambiar la contraseña por sospecha no sirve de nada si la passkey que dejó otro sigue valiendo. Al cambiarla, y al desactivar a un usuario, borra sus passkeys.
Lo que no hace
No verifica la atestación del fabricante. Las opciones piden
attestation: "none" y se aceptan los formatos none y packed
autoatestado. Para entrar a un sitio basta: lo que importa es que quien
entra tiene la clave privada, no qué marca de llave la guarda. Si necesitas
restringir a llaves de un fabricante —un banco, un entorno regulado—, hace
falta otra librería.
No guarda nada. Dónde viven las passkeys y los retos es cosa de la aplicación: la referencia dice qué guardar de cada una.