Referencia
ascua-passkey
El cliente y el servidor de passkeys, con su firma.
import { authenticate, conditionalSupported, PasskeyError, register, supported } from "ascua-passkey";
import {
authenticationOptions, registrationOptions, VerificationError,
verifyAuthentication, verifyRegistration,
} from "ascua-passkey/server";Sin dependencias. El cliente pesa 1,8 kB gzip; el servidor usa Web Crypto y corre en Node 20+, Deno, Bun y un worker. La guía está en Passkeys.
Navegador
function supported(): boolean;
function conditionalSupported(): Promise<boolean>;
function register(
options: CreationOptionsJSON | { publicKey: CreationOptionsJSON },
init?: { signal?: AbortSignal },
): Promise<RegistrationResponseJSON>;
function authenticate(
options: RequestOptionsJSON | { publicKey: RequestOptionsJSON },
init?: { signal?: AbortSignal; conditional?: boolean },
): Promise<AuthenticationResponseJSON>;
class PasskeyError extends Error {
code: "cancelled" | "unsupported" | "exists" | "security" | "timeout" | "unknown";
}Los tipos CreationOptionsJSON, RequestOptionsJSON,
RegistrationResponseJSON y AuthenticationResponseJSON son los JSON de
WebAuthn nivel 3, con los bytes en base64url sin relleno.
Servidor
function registrationOptions(input: {
rp: { id: string; name: string };
user: { id: string | Uint8Array; name: string; displayName?: string };
exclude?: (string | { id: string; transports?: Transport[] })[];
timeout?: number; // 5 minutos
}): { options: CreationOptionsJSON; challenge: string };
function authenticationOptions(input: {
rpId: string;
allow?: (string | { id: string; transports?: Transport[] })[];
timeout?: number;
}): { options: RequestOptionsJSON; challenge: string };Las opciones piden una passkey descubrible (residentKey: "required"),
userVerification: "preferred", attestation: "none" y los algoritmos
EdDSA, ES256 y RS256. challenge son 32 bytes al azar: hay que guardarlo
para verificar.
interface Expected {
challenge: string;
origin: string | string[];
rpId: string;
requireUserVerification?: boolean;
}
function verifyRegistration(response: RegistrationResponseJSON, expected: Expected): Promise<{
id: string;
publicKey: string; // COSE, en base64url
algorithm: number; // -7, -257 o -8
counter: number;
transports: Transport[];
backedUp: boolean;
deviceType: "singleDevice" | "multiDevice";
userVerified: boolean;
}>;
function verifyAuthentication(
response: AuthenticationResponseJSON,
expected: Expected & { credential: { id: string; publicKey: string; counter?: number } },
): Promise<{ counter: number; backedUp: boolean; userVerified: boolean; userHandle?: string }>;De una passkey nueva se guardan id, publicKey y counter —transports
sirve para allow—, y tras cada entrada, el counter nuevo.
Se comprueban el tipo de ceremonia, el reto, el origen, que no venga de un
iframe de otro origen, el hash del rpId, la presencia del usuario, su
verificación si se pide, la firma y el contador: si no avanza y alguno de los
dos no es 0, es un clon. Las passkeys sincronizadas mandan siempre 0.
VerificationError
Un rechazo lleva code: format, type, credential, challenge,
origin, rp, flags, algorithm, signature o counter. El mensaje es
para el log; al usuario, un «no se pudo verificar».