webauthnnamespacenamespace webauthnWebAuthn (Web Authentication Level 3) for a relying party, pure and with no outside package (commons 0014-webauthn): the options a browser's navigator.credentials.create() and .get() take, and the verification of what they answer, in the JSON shapes of the Level 3 toJSON() methods (every binary field as base64url). Registration checks the client data (webauthn.create, the challenge, the origin), the attestation object (CBOR: fmt none, or packed with no more than self-attestation's trust), the authenticator data (the SHA-256 of the RP ID, user presence and user verification, the attested credential) and the credential's COSE key (ES256 or EdDSA). Authentication checks the client data (webauthn.get), the authenticator data, the signature over the authenticator data and the SHA-256 of the client data by the stored key, and that the signature counter went up. Every refusal is a plain sentence, never an exception: what a browser sends is input from outside.
The kernel has no randomness and no store: the caller makes each challenge (16 or more random bytes, base64url), keeps it until the answer comes, and keeps the credential (credentialId, publicKey, alg, signCount) that registration gives back.
import { registrationOptions, verifyRegistration } from "./webauthn.ts";
const options = registrationOptions({
rpId: "example.com",
rpName: "Example",
user: { id: "dXNlci0x", name: "ada", displayName: "Ada" },
challenge: "q83vEjRWeJq83vEjRWeJqw",
});
// send `options` to the browser; then, with what it answers:
// const r = await verifyRegistration({ response, expectedChallenge: options.challenge, expectedOrigin: "https://example.com", rpId: "example.com" });webauthnnamespacenamespace webauthnwebauthn.PublicKeyCredentialRpEntitytypeno test imports ittype PublicKeyCredentialRpEntity = { readonly id?: string; readonly name: string };A relying party as the options name it.
webauthn.PublicKeyCredentialUserEntityJSONtypeno test imports ittype PublicKeyCredentialUserEntityJSON = { readonly id: string; readonly name: string; readonly displayName: string };A user account as the options name it (id base64url, at most 64 bytes).
webauthn.PublicKeyCredentialParameterstypeno test imports ittype PublicKeyCredentialParameters = { readonly type: "public-key"; readonly alg: number };An algorithm offered for a new credential.
webauthn.PublicKeyCredentialDescriptorJSONtypeno test imports ittype PublicKeyCredentialDescriptorJSON = {
readonly type: "public-key";
readonly id: string;
readonly transports?: readonly string[];
};A credential named by its id (base64url).
webauthn.AuthenticatorSelectionCriteriatypeno test imports ittype AuthenticatorSelectionCriteria = {
readonly authenticatorAttachment?: "platform" | "cross-platform";
readonly residentKey?: "discouraged" | "preferred" | "required";
readonly requireResidentKey?: boolean;
readonly userVerification?: "required" | "preferred" | "discouraged";
};What kind of authenticator is wanted.
webauthn.PublicKeyCredentialCreationOptionsJSONtypeno test imports ittype PublicKeyCredentialCreationOptionsJSON = {
readonly rp: PublicKeyCredentialRpEntity;
readonly user: PublicKeyCr… (642 characters)type PublicKeyCredentialCreationOptionsJSON = {
readonly rp: PublicKeyCredentialRpEntity;
readonly user: PublicKeyCredentialUserEntityJSON;
readonly challenge: string;
readonly pubKeyCredParams: readonly PublicKeyCredentialParameters[];
readonly timeout?: number;
readonly excludeCredentials?: readonly PublicKeyCredentialDescriptorJSON[];
readonly authenticatorSelection?: AuthenticatorSelectionCriteria;
readonly hints?: readonly string[];
readonly attestation?: "none" | "indirect" | "direct" | "enterprise";
readonly attestationFormats?: readonly string[];
readonly extensions?: Readonly<Record<string, unknown>>;
};The options of navigator.credentials.create({ publicKey }) as JSON (PublicKeyCredential.parseCreationOptionsFromJSON takes it).
webauthn.PublicKeyCredentialRequestOptionsJSONtypeno test imports ittype PublicKeyCredentialRequestOptionsJSON = {
readonly challenge: string;
readonly timeout?: number;
readonly rpId?: string;
readonly allowCredentials?: readonly PublicKeyCredentialDescriptorJSON[];
readonly userVerification?: "required" | "preferred" | "discouraged";
readonly hints?: readonly string[];
readonly extensions?: Readonly<Record<string, unknown>>;
};The options of navigator.credentials.get({ publicKey }) as JSON (PublicKeyCredential.parseRequestOptionsFromJSON takes it).
webauthn.AuthenticatorAttestationResponseJSONtypeno test imports ittype AuthenticatorAttestationResponseJSON = {
readonly clientDataJSON: string;
readonly attestationObject: string;
readonly authenticatorData?: string;
readonly transports?: readonly string[];
readonly publicKey?: string;
readonly publicKeyAlgorithm?: number;
};An authenticator's answer to create(), as AuthenticatorAttestationResponse.toJSON() gives it.
webauthn.RegistrationResponseJSONtypeno test imports ittype RegistrationResponseJSON = {
readonly id: string;
readonly rawId: string;
readonly response: AuthenticatorAttestationResponseJSON;
readonly authenticatorAttachment?: string | null;
readonly clientExtensionResults: Readonly<Record<string, unknown>>;
readonly type: "public-key";
};A new credential, as PublicKeyCredential.toJSON() gives it after create().
webauthn.AuthenticatorAssertionResponseJSONtypeno test imports ittype AuthenticatorAssertionResponseJSON = {
readonly clientDataJSON: string;
readonly authenticatorData: string;
readonly signature: string;
readonly userHandle?: string | null;
};An authenticator's answer to get(), as AuthenticatorAssertionResponse.toJSON() gives it.
webauthn.AuthenticationResponseJSONtypeno test imports ittype AuthenticationResponseJSON = {
readonly id: string;
readonly rawId: string;
readonly response: AuthenticatorAssertionResponseJSON;
readonly authenticatorAttachment?: string | null;
readonly clientExtensionResults: Readonly<Record<string, unknown>>;
readonly type: "public-key";
};An assertion, as PublicKeyCredential.toJSON() gives it after get().
webauthn.StoredCredentialtypeno test imports ittype StoredCredential = { readonly id: string; readonly publicKey: string; readonly alg: number; readonly signCount: number };A credential as the relying party keeps it: its id and COSE public key (base64url), its algorithm and its last signature counter.
webauthn.VerifiedRegistrationtypeno test imports ittype VerifiedRegistration = {
/** The credential's id, base64url. */
readonly credentialId: string;
/** The creden… (794 characters)type VerifiedRegistration = {
/** The credential's id, base64url. */
readonly credentialId: string;
/** The credential's public key as its CBOR `COSE_Key`, base64url. */
readonly publicKey: string;
/** Its COSE algorithm: -7 (ES256) or -8 (EdDSA). */
readonly alg: number;
readonly signCount: number;
readonly userVerified: boolean;
/** Whether the credential is backed up (synced, a passkey): the BS flag. */
readonly backedUp: boolean;
/** Whether it may be backed up: the BE flag. */
readonly backupEligible: boolean;
/** The authenticator's AAGUID, as a UUID (all zeros under attestation `none`). */
readonly aaguid: string;
/** The attestation format the authenticator used (`none` or `packed`). */
readonly fmt: string;
readonly transports?: string[];
};What a verified registration gives the relying party to keep.
webauthn.VerifiedAuthenticationtypeno test imports ittype VerifiedAuthentication = {
readonly signCount: number;
readonly userVerified: boolean;
readonly backedUp: boolean;
};What a verified authentication gives: the counter to keep, and the flags.
webauthn.DEFAULT_TIMEOUT_MSconstno test imports itconst DEFAULT_TIMEOUT_MS: 300000The default time a ceremony may take: five minutes, within what Level 3 recommends where user verification is required.
webauthn.registrationOptionsfunctionno test imports itfunction registrationOptions(o: { readonly rpId: string; readonly rpName: string; readonly user: { readonly id: string; readonly name: string; readonly displayName: string; }; readonly challenge: string; readonly excludeCredentials?: readonly string[] | undefined; readonly timeoutMs?: number | undefined; }): PublicKeyCredentialCreationOptionsJSONThe options for registering a credential: ES256 and EdDSA offered, a discoverable credential preferred, user verification required, no attestation asked for, and the credentials the user already has excluded. A challenge shorter than 16 bytes or a user id longer than 64 is a programming error and throws a RangeError.
webauthn.authenticationOptionsfunctionno test imports itfunction authenticationOptions(o: { readonly rpId: string; readonly challenge: string; readonly allowCredentials?: readonly string[] | undefined; readonly timeoutMs?: number | undefined; }): PublicKeyCredentialRequestOptionsJSONThe options for authenticating: user verification required, and the credentials allowed where the user is known (none for a passkey's discoverable sign-in).
webauthn.FLAGSconstno test imports itconst FLAGS: { readonly up: 1; readonly uv: 4; readonly be: 8; readonly bs: 16; readonly at: 64; readonly ed: 128; }The flags of authenticator data (WebAuthn §6.1).
webauthn.AuthenticatorDatatypeno test imports ittype AuthenticatorData = {
readonly rpIdHash: Uint8Array;
readonly flags: number;
readonly userPresent: boolean;
… (576 characters)type AuthenticatorData = {
readonly rpIdHash: Uint8Array;
readonly flags: number;
readonly userPresent: boolean;
readonly userVerified: boolean;
readonly backupEligible: boolean;
readonly backedUp: boolean;
readonly signCount: number;
/** The attested credential data, where the AT flag says it is there. */
readonly attested?: { readonly aaguid: Uint8Array; readonly credentialId: Uint8Array; readonly publicKey: Uint8Array };
/** The extension outputs, where the ED flag says they are there. */
readonly extensions?: ReadonlyMap<CborKey, CborValue>;
};Authenticator data as read (WebAuthn §6.1).
webauthn.parseAuthenticatorDatafunctionno test imports itfunction parseAuthenticatorData(bytes: Uint8Array<ArrayBufferLike>): Result<AuthenticatorData, string>Authenticator data read: the RP ID hash, the flags, the counter, the attested credential (its COSE key's bytes as given) and extensions; every byte accounted for.
webauthn.ClientDatatypeno test imports ittype ClientData = {
readonly type: string;
readonly challenge: string;
readonly origin: string;
readonly crossOrigin?: boolean;
readonly topOrigin?: string;
};Client data as read (WebAuthn §5.8.1).
webauthn.parseClientDatafunctionno test imports itfunction parseClientData(bytes: Uint8Array<ArrayBufferLike>): Result<ClientData, string>Client data JSON (its bytes, UTF-8) read.
webauthn.verifyRegistrationfunctionno test imports itfunction verifyRegistration(o: { readonly response: RegistrationResponseJSON; readonly expectedChallenge: string; readonly expectedOrigin: string | readonly string[]; readonly rpId: string; }): Promise<Result<VerifiedRegistration, string>>A registration verified (WebAuthn §7.1): the client data, the attestation object, the authenticator data and the credential's key; what to keep, or why it is refused.
webauthn.verifyAuthenticationfunctionno test imports itfunction verifyAuthentication(o: { readonly response: AuthenticationResponseJSON; readonly expectedChallenge: string; readonly expectedOrigin: string | readonly string[]; readonly rpId: string; readonly credential: StoredCredential; }): Promise<Result<VerifiedAuthentication, string>>An authentication verified (WebAuthn §7.2) against the credential kept at registration: the client data, the authenticator data, the signature and the counter; the counter and flags to keep, or why it is refused.
webauthn.parseRegistrationResponsefunctionno test imports itfunction parseRegistrationResponse(input: unknown): Result<RegistrationResponseJSON, string>JSON from a browser read as a RegistrationResponseJSON, or why it is not one: the boundary before verifyRegistration.
webauthn.parseAuthenticationResponsefunctionno test imports itfunction parseAuthenticationResponse(input: unknown): Result<AuthenticationResponseJSON, string>JSON from a browser read as an AuthenticationResponseJSON, or why it is not one: the boundary before verifyAuthentication.
PublicKeyCredentialRpEntitytypeno test imports ittype PublicKeyCredentialRpEntity = { readonly id?: string; readonly name: string };A relying party as the options name it.
PublicKeyCredentialUserEntityJSONtypeno test imports ittype PublicKeyCredentialUserEntityJSON = { readonly id: string; readonly name: string; readonly displayName: string };A user account as the options name it (id base64url, at most 64 bytes).
PublicKeyCredentialParameterstypeno test imports ittype PublicKeyCredentialParameters = { readonly type: "public-key"; readonly alg: number };An algorithm offered for a new credential.
PublicKeyCredentialDescriptorJSONtypeno test imports ittype PublicKeyCredentialDescriptorJSON = {
readonly type: "public-key";
readonly id: string;
readonly transports?: readonly string[];
};A credential named by its id (base64url).
AuthenticatorSelectionCriteriatypeno test imports ittype AuthenticatorSelectionCriteria = {
readonly authenticatorAttachment?: "platform" | "cross-platform";
readonly residentKey?: "discouraged" | "preferred" | "required";
readonly requireResidentKey?: boolean;
readonly userVerification?: "required" | "preferred" | "discouraged";
};What kind of authenticator is wanted.
PublicKeyCredentialCreationOptionsJSONtypeno test imports ittype PublicKeyCredentialCreationOptionsJSON = {
readonly rp: PublicKeyCredentialRpEntity;
readonly user: PublicKeyCr… (642 characters)type PublicKeyCredentialCreationOptionsJSON = {
readonly rp: PublicKeyCredentialRpEntity;
readonly user: PublicKeyCredentialUserEntityJSON;
readonly challenge: string;
readonly pubKeyCredParams: readonly PublicKeyCredentialParameters[];
readonly timeout?: number;
readonly excludeCredentials?: readonly PublicKeyCredentialDescriptorJSON[];
readonly authenticatorSelection?: AuthenticatorSelectionCriteria;
readonly hints?: readonly string[];
readonly attestation?: "none" | "indirect" | "direct" | "enterprise";
readonly attestationFormats?: readonly string[];
readonly extensions?: Readonly<Record<string, unknown>>;
};The options of navigator.credentials.create({ publicKey }) as JSON (PublicKeyCredential.parseCreationOptionsFromJSON takes it).
PublicKeyCredentialRequestOptionsJSONtypeno test imports ittype PublicKeyCredentialRequestOptionsJSON = {
readonly challenge: string;
readonly timeout?: number;
readonly rpId?: string;
readonly allowCredentials?: readonly PublicKeyCredentialDescriptorJSON[];
readonly userVerification?: "required" | "preferred" | "discouraged";
readonly hints?: readonly string[];
readonly extensions?: Readonly<Record<string, unknown>>;
};The options of navigator.credentials.get({ publicKey }) as JSON (PublicKeyCredential.parseRequestOptionsFromJSON takes it).
AuthenticatorAttestationResponseJSONtypeno test imports ittype AuthenticatorAttestationResponseJSON = {
readonly clientDataJSON: string;
readonly attestationObject: string;
readonly authenticatorData?: string;
readonly transports?: readonly string[];
readonly publicKey?: string;
readonly publicKeyAlgorithm?: number;
};An authenticator's answer to create(), as AuthenticatorAttestationResponse.toJSON() gives it.
type RegistrationResponseJSON = {
readonly id: string;
readonly rawId: string;
readonly response: AuthenticatorAttestationResponseJSON;
readonly authenticatorAttachment?: string | null;
readonly clientExtensionResults: Readonly<Record<string, unknown>>;
readonly type: "public-key";
};A new credential, as PublicKeyCredential.toJSON() gives it after create().
AuthenticatorAssertionResponseJSONtypeno test imports ittype AuthenticatorAssertionResponseJSON = {
readonly clientDataJSON: string;
readonly authenticatorData: string;
readonly signature: string;
readonly userHandle?: string | null;
};An authenticator's answer to get(), as AuthenticatorAssertionResponse.toJSON() gives it.
type AuthenticationResponseJSON = {
readonly id: string;
readonly rawId: string;
readonly response: AuthenticatorAssertionResponseJSON;
readonly authenticatorAttachment?: string | null;
readonly clientExtensionResults: Readonly<Record<string, unknown>>;
readonly type: "public-key";
};An assertion, as PublicKeyCredential.toJSON() gives it after get().
StoredCredentialtypeno test imports ittype StoredCredential = { readonly id: string; readonly publicKey: string; readonly alg: number; readonly signCount: number };A credential as the relying party keeps it: its id and COSE public key (base64url), its algorithm and its last signature counter.
VerifiedRegistrationtypeno test imports ittype VerifiedRegistration = {
/** The credential's id, base64url. */
readonly credentialId: string;
/** The creden… (794 characters)type VerifiedRegistration = {
/** The credential's id, base64url. */
readonly credentialId: string;
/** The credential's public key as its CBOR `COSE_Key`, base64url. */
readonly publicKey: string;
/** Its COSE algorithm: -7 (ES256) or -8 (EdDSA). */
readonly alg: number;
readonly signCount: number;
readonly userVerified: boolean;
/** Whether the credential is backed up (synced, a passkey): the BS flag. */
readonly backedUp: boolean;
/** Whether it may be backed up: the BE flag. */
readonly backupEligible: boolean;
/** The authenticator's AAGUID, as a UUID (all zeros under attestation `none`). */
readonly aaguid: string;
/** The attestation format the authenticator used (`none` or `packed`). */
readonly fmt: string;
readonly transports?: string[];
};What a verified registration gives the relying party to keep.
VerifiedAuthenticationtypeno test imports ittype VerifiedAuthentication = {
readonly signCount: number;
readonly userVerified: boolean;
readonly backedUp: boolean;
};What a verified authentication gives: the counter to keep, and the flags.
DEFAULT_TIMEOUT_MSconstno test imports itconst DEFAULT_TIMEOUT_MS: 300000The default time a ceremony may take: five minutes, within what Level 3 recommends where user verification is required.
registrationOptionsfunctionfunction registrationOptions(o: { readonly rpId: string; readonly rpName: string; readonly user: { readonly id: string; readonly name: string; readonly displayName: string; }; readonly challenge: string; readonly excludeCredentials?: readonly string[] | undefined; readonly timeoutMs?: number | undefined; }): PublicKeyCredentialCreationOptionsJSONThe options for registering a credential: ES256 and EdDSA offered, a discoverable credential preferred, user verification required, no attestation asked for, and the credentials the user already has excluded. A challenge shorter than 16 bytes or a user id longer than 64 is a programming error and throws a RangeError.
authenticationOptionsfunctionfunction authenticationOptions(o: { readonly rpId: string; readonly challenge: string; readonly allowCredentials?: readonly string[] | undefined; readonly timeoutMs?: number | undefined; }): PublicKeyCredentialRequestOptionsJSONThe options for authenticating: user verification required, and the credentials allowed where the user is known (none for a passkey's discoverable sign-in).
FLAGSconstconst FLAGS: { readonly up: 1; readonly uv: 4; readonly be: 8; readonly bs: 16; readonly at: 64; readonly ed: 128; }The flags of authenticator data (WebAuthn §6.1).
AuthenticatorDatatypeno test imports ittype AuthenticatorData = {
readonly rpIdHash: Uint8Array;
readonly flags: number;
readonly userPresent: boolean;
… (576 characters)type AuthenticatorData = {
readonly rpIdHash: Uint8Array;
readonly flags: number;
readonly userPresent: boolean;
readonly userVerified: boolean;
readonly backupEligible: boolean;
readonly backedUp: boolean;
readonly signCount: number;
/** The attested credential data, where the AT flag says it is there. */
readonly attested?: { readonly aaguid: Uint8Array; readonly credentialId: Uint8Array; readonly publicKey: Uint8Array };
/** The extension outputs, where the ED flag says they are there. */
readonly extensions?: ReadonlyMap<CborKey, CborValue>;
};Authenticator data as read (WebAuthn §6.1).
parseAuthenticatorDatafunctionfunction parseAuthenticatorData(bytes: Uint8Array<ArrayBufferLike>): Result<AuthenticatorData, string>Authenticator data read: the RP ID hash, the flags, the counter, the attested credential (its COSE key's bytes as given) and extensions; every byte accounted for.
ClientDatatypeno test imports ittype ClientData = {
readonly type: string;
readonly challenge: string;
readonly origin: string;
readonly crossOrigin?: boolean;
readonly topOrigin?: string;
};Client data as read (WebAuthn §5.8.1).
parseClientDatafunctionno test imports itfunction parseClientData(bytes: Uint8Array<ArrayBufferLike>): Result<ClientData, string>Client data JSON (its bytes, UTF-8) read.
verifyRegistrationfunctionfunction verifyRegistration(o: { readonly response: RegistrationResponseJSON; readonly expectedChallenge: string; readonly expectedOrigin: string | readonly string[]; readonly rpId: string; }): Promise<Result<VerifiedRegistration, string>>A registration verified (WebAuthn §7.1): the client data, the attestation object, the authenticator data and the credential's key; what to keep, or why it is refused.
verifyAuthenticationfunctionfunction verifyAuthentication(o: { readonly response: AuthenticationResponseJSON; readonly expectedChallenge: string; readonly expectedOrigin: string | readonly string[]; readonly rpId: string; readonly credential: StoredCredential; }): Promise<Result<VerifiedAuthentication, string>>An authentication verified (WebAuthn §7.2) against the credential kept at registration: the client data, the authenticator data, the signature and the counter; the counter and flags to keep, or why it is refused.
parseRegistrationResponsefunctionfunction parseRegistrationResponse(input: unknown): Result<RegistrationResponseJSON, string>JSON from a browser read as a RegistrationResponseJSON, or why it is not one: the boundary before verifyRegistration.
parseAuthenticationResponsefunctionfunction parseAuthenticationResponse(input: unknown): Result<AuthenticationResponseJSON, string>JSON from a browser read as an AuthenticationResponseJSON, or why it is not one: the boundary before verifyAuthentication.