IF Commons GitHub

webauthn

Written to: 1 requirement: 0 proved, 0 partly, 0 failing, 1 with no test recorded. 0001-crypto FR-008

WebAuthn (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" });

Source: commons/crypto/src/webauthn.ts

10 of 52 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

webauthnnamespace
namespace webauthn
webauthn.PublicKeyCredentialRpEntitytypeno test imports it
type PublicKeyCredentialRpEntity = { readonly id?: string; readonly name: string };

A relying party as the options name it.

webauthn.PublicKeyCredentialUserEntityJSONtypeno test imports it
type 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 it
type PublicKeyCredentialParameters = { readonly type: "public-key"; readonly alg: number };

An algorithm offered for a new credential.

webauthn.PublicKeyCredentialDescriptorJSONtypeno test imports it
type PublicKeyCredentialDescriptorJSON = {
  readonly type: "public-key";
  readonly id: string;
  readonly transports?: readonly string[];
};

A credential named by its id (base64url).

webauthn.AuthenticatorSelectionCriteriatypeno test imports it
type 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 it
type 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 it
type 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 it
type 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 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().

webauthn.AuthenticatorAssertionResponseJSONtypeno test imports it
type 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 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().

webauthn.StoredCredentialtypeno test imports it
type 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 it
type 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 it
type 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 it
const DEFAULT_TIMEOUT_MS: 300000

The default time a ceremony may take: five minutes, within what Level 3 recommends where user verification is required.

webauthn.registrationOptionsfunctionno test imports it
function 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; }): PublicKeyCredentialCreationOptionsJSON

The 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 it
function authenticationOptions(o: { readonly rpId: string; readonly challenge: string; readonly allowCredentials?: readonly string[] | undefined; readonly timeoutMs?: number | undefined; }): PublicKeyCredentialRequestOptionsJSON

The 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 it
const 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 it
type 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 it
function 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 it
type 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 it
function parseClientData(bytes: Uint8Array<ArrayBufferLike>): Result<ClientData, string>

Client data JSON (its bytes, UTF-8) read.

webauthn.verifyRegistrationfunctionno test imports it
function 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 it
function 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 it
function 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 it
function 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 it
type PublicKeyCredentialRpEntity = { readonly id?: string; readonly name: string };

A relying party as the options name it.

PublicKeyCredentialUserEntityJSONtypeno test imports it
type 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 it
type PublicKeyCredentialParameters = { readonly type: "public-key"; readonly alg: number };

An algorithm offered for a new credential.

PublicKeyCredentialDescriptorJSONtypeno test imports it
type PublicKeyCredentialDescriptorJSON = {
  readonly type: "public-key";
  readonly id: string;
  readonly transports?: readonly string[];
};

A credential named by its id (base64url).

AuthenticatorSelectionCriteriatypeno test imports it
type 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 it
type 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 it
type 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 it
type 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.

RegistrationResponseJSONtype
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().

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

AuthenticatorAssertionResponseJSONtypeno test imports it
type 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.

AuthenticationResponseJSONtype
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().

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

StoredCredentialtypeno test imports it
type 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 it
type 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 it
type 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 it
const DEFAULT_TIMEOUT_MS: 300000

The default time a ceremony may take: five minutes, within what Level 3 recommends where user verification is required.

registrationOptionsfunction
function 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; }): PublicKeyCredentialCreationOptionsJSON

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

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

authenticationOptionsfunction
function authenticationOptions(o: { readonly rpId: string; readonly challenge: string; readonly allowCredentials?: readonly string[] | undefined; readonly timeoutMs?: number | undefined; }): PublicKeyCredentialRequestOptionsJSON

The options for authenticating: user verification required, and the credentials allowed where the user is known (none for a passkey's discoverable sign-in).

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

FLAGSconst
const 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).

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

AuthenticatorDatatypeno test imports it
type 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).

parseAuthenticatorDatafunction
function 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.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

ClientDatatypeno test imports it
type 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 it
function parseClientData(bytes: Uint8Array<ArrayBufferLike>): Result<ClientData, string>

Client data JSON (its bytes, UTF-8) read.

verifyRegistrationfunction
function 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.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

verifyAuthenticationfunction
function 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.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

parseRegistrationResponsefunction
function parseRegistrationResponse(input: unknown): Result<RegistrationResponseJSON, string>

JSON from a browser read as a RegistrationResponseJSON, or why it is not one: the boundary before verifyRegistration.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

parseAuthenticationResponsefunction
function parseAuthenticationResponse(input: unknown): Result<AuthenticationResponseJSON, string>

JSON from a browser read as an AuthenticationResponseJSON, or why it is not one: the boundary before verifyAuthentication.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.