Referencia

ascua-passkey

El cliente y el servidor de passkeys, con su firma.

ts
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.

ts
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

ts
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.

ts
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».