Skip to main content
Home

Built and signed on GitHub Actions

Works with
This package works with Cloudflare Workers, Node.js, Deno, Bun
This package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
This package works with Bun
JSR Score88%
License
MIT
Downloads105/wk
Published4 weeks ago (13.3.2)

SimpleWebAuthn for Servers

Classes

c

An implementation of MetadataService that can download and parse BLOBs, and support on-demand requesting and caching of individual metadata statements.

  • downloadBlob(cachedMDS: CachedMDS)

    Download and process the latest BLOB from MDS

  • getStatement(aaguid: string | Uint8Array_): Promise<MetadataStatement | undefined>
    No documentation available
  • initialize(opts?: { mdsServers?: string[]; statements?: MetadataStatement[]; verificationMode?: VerificationMode; }): Promise<void>
    No documentation available
  • mdsCache: { [url: string]: CachedMDS; }
    No documentation available
  • pauseUntilReady(): Promise<void>

    A helper method to pause execution until the service is ready

  • setState(newState: SERVICE_STATE): void

    Report service status on change

  • state: SERVICE_STATE
    No documentation available
  • statementCache: { [aaguid: string]: CachedBLOBEntry; }
    No documentation available
  • verificationMode: VerificationMode
    No documentation available
  • verifyBlob(
    blob: string,
    cachedMDS: CachedMDS
    ): Promise<void>

    Verify and process the MDS metadata blob

Functions

f
generateAuthenticationOptions(options: { rpID: string; allowCredentials?: { id: Base64URLString; transports?: AuthenticatorTransportFuture[]; }[]; challenge?: string | Uint8Array_; timeout?: number; userVerification?: "required" | "preferred" | "discouraged"; extensions?: AuthenticationExtensionsClientInputs; }): Promise<PublicKeyCredentialRequestOptionsJSON>

Prepare a value to pass into navigator.credentials.get(...) for authenticator authentication

f
generateRegistrationOptions(options: { rpName: string; rpID: string; userName: string; userID?: Uint8Array_; challenge?: string | Uint8Array_; userDisplayName?: string; timeout?: number; attestationType?: "direct" | "enterprise" | "none"; excludeCredentials?: { id: Base64URLString; transports?: AuthenticatorTransportFuture[]; }[]; authenticatorSelection?: AuthenticatorSelectionCriteria; extensions?: AuthenticationExtensionsClientInputs; supportedAlgorithmIDs?: COSEAlgorithmIdentifier[]; preferredAuthenticatorType?: "securityKey" | "localDevice" | "remoteDevice"; }): Promise<PublicKeyCredentialCreationOptionsJSON>

Prepare a value to pass into navigator.credentials.create(...) for authenticator registration

f
verifyAuthenticationResponse(options: { response: AuthenticationResponseJSON; expectedChallenge: string | ((challenge: string) => boolean | Promise<boolean>); expectedOrigin: string | string[]; expectedRPID: string | string[]; credential: WebAuthnCredential; expectedType?: string | string[]; requireUserVerification?: boolean; advancedFIDOConfig?: { userVerification?: UserVerificationRequirement; }; }): Promise<VerifiedAuthenticationResponse>

Verify that the user has legitimately completed the authentication process

f
verifyRegistrationResponse(options: { response: RegistrationResponseJSON; expectedChallenge: string | ((challenge: string) => boolean | Promise<boolean>); expectedOrigin: string | string[]; expectedRPID?: string | string[]; expectedType?: string | string[]; requireUserPresence?: boolean; requireUserVerification?: boolean; supportedAlgorithmIDs?: COSEAlgorithmIdentifier[]; attestationSafetyNetEnforceCTSCheck?: boolean; }): Promise<VerifiedRegistrationResponse>

Verify that the user has legitimately completed the registration process

Interfaces

I

The value returned from navigator.credentials.get()

  • response: AuthenticatorAssertionResponse
    No documentation available
I
No documentation available
I
No documentation available
  • appid: boolean
    No documentation available
  • credProps: CredentialPropertiesOutput
    No documentation available
  • No documentation available
I

A slightly-modified AuthenticationCredential to simplify working with ArrayBuffers that are Base64URL-encoded in the browser so that they can be sent as JSON to the server.

  • authenticatorAttachment: AuthenticatorAttachment
    No documentation available
  • clientExtensionResults: AuthenticationExtensionsClientOutputs
    No documentation available
  • id: Base64URLString
    No documentation available
  • rawId: Base64URLString
    No documentation available
  • response: AuthenticatorAssertionResponseJSON
    No documentation available
  • type: PublicKeyCredentialType
    No documentation available
I

Available only in secure contexts.

I

A slightly-modified AuthenticatorAssertionResponse to simplify working with ArrayBuffers that are Base64URL-encoded in the browser so that they can be sent as JSON to the server.

I

Available only in secure contexts.

I

AuthenticatorAttestationResponse in TypeScript's DOM lib is outdated (up through v3.9.7). Maintain an augmented version here so we can implement additional properties as the WebAuthn spec evolves.

  • getTransports(): AuthenticatorTransportFuture[]
    No documentation available
I

A slightly-modified AuthenticatorAttestationResponse to simplify working with ArrayBuffers that are Base64URL-encoded in the browser so that they can be sent as JSON to the server.

I
No documentation available
I

Basic cryptography features available in the current context. It allows access to a cryptographically strong random number generator and to cryptographic primitives.

  • getRandomValues<T extends ArrayBufferView | null>(array: T): T
  • randomUUID(): `${string}-${string}-${string}-${string}-${string}`

    Available only in secure contexts.

  • subtle: SubtleCrypto

    Available only in secure contexts.

I
v
No documentation available
  • getStatement(aaguid: string | Uint8Array): Promise<MetadataStatement | undefined>

    Get a metadata statement for a given AAGUID.

  • initialize(opts?: { mdsServers?: string[]; statements?: MetadataStatement[]; verificationMode?: VerificationMode; }): Promise<void>

    Prepare the service to handle remote MDS servers and/or cache local metadata statements.

I

Available only in secure contexts.

I
No documentation available
  • attestation: AttestationConveyancePreference
    No documentation available
  • authenticatorSelection: AuthenticatorSelectionCriteria
    No documentation available
  • challenge: BufferSource
    No documentation available
  • excludeCredentials: PublicKeyCredentialDescriptor[]
    No documentation available
  • extensions: AuthenticationExtensionsClientInputs
    No documentation available
  • pubKeyCredParams: PublicKeyCredentialParameters[]
    No documentation available
  • rp: PublicKeyCredentialRpEntity
    No documentation available
  • timeout: number
    No documentation available
  • user: PublicKeyCredentialUserEntity
    No documentation available
I

A variant of PublicKeyCredentialCreationOptions suitable for JSON transmission to the browser to (eventually) get passed into navigator.credentials.create(...) in the browser.

  • attestation: AttestationConveyancePreference
    No documentation available
  • attestationFormats: AttestationFormat[]
    No documentation available
  • authenticatorSelection: AuthenticatorSelectionCriteria
    No documentation available
  • challenge: Base64URLString
    No documentation available
  • excludeCredentials: PublicKeyCredentialDescriptorJSON[]
    No documentation available
  • extensions: AuthenticationExtensionsClientInputs
    No documentation available
  • hints: PublicKeyCredentialHint[]
    No documentation available
  • pubKeyCredParams: PublicKeyCredentialParameters[]
    No documentation available
  • rp: PublicKeyCredentialRpEntity
    No documentation available
  • timeout: number
    No documentation available
  • user: PublicKeyCredentialUserEntityJSON
    No documentation available
I
No documentation available
  • id: BufferSource
    No documentation available
  • transports: AuthenticatorTransport[]
    No documentation available
  • type: PublicKeyCredentialType
    No documentation available
I

A super class of TypeScript's PublicKeyCredentialDescriptor that knows about the latest transports. Should eventually be replaced by TypeScript's when TypeScript gets updated to know about it (sometime after 4.6.3)

  • transports: AuthenticatorTransportFuture[]
    No documentation available
  • id: Base64URLString
    No documentation available
  • transports: AuthenticatorTransportFuture[]
    No documentation available
  • type: PublicKeyCredentialType
    No documentation available
I

A super class of TypeScript's PublicKeyCredential that knows about upcoming WebAuthn features

I
No documentation available
  • alg: COSEAlgorithmIdentifier
    No documentation available
  • type: PublicKeyCredentialType
    No documentation available
I
No documentation available
  • allowCredentials: PublicKeyCredentialDescriptor[]
    No documentation available
  • challenge: BufferSource
    No documentation available
  • extensions: AuthenticationExtensionsClientInputs
    No documentation available
  • rpId: string
    No documentation available
  • timeout: number
    No documentation available
  • userVerification: UserVerificationRequirement
    No documentation available
I

A variant of PublicKeyCredentialRequestOptions suitable for JSON transmission to the browser to (eventually) get passed into navigator.credentials.get(...) in the browser.

  • allowCredentials: PublicKeyCredentialDescriptorJSON[]
    No documentation available
  • challenge: Base64URLString
    No documentation available
  • extensions: AuthenticationExtensionsClientInputs
    No documentation available
  • hints: PublicKeyCredentialHint[]
    No documentation available
  • rpId: string
    No documentation available
  • timeout: number
    No documentation available
  • userVerification: UserVerificationRequirement
    No documentation available
I
No documentation available
  • id: string
    No documentation available
I
No documentation available
  • displayName: string
    No documentation available
  • id: BufferSource
    No documentation available
  • displayName: string
    No documentation available
  • id: string
    No documentation available
  • name: string
    No documentation available
I

The value returned from navigator.credentials.create()

  • response: AuthenticatorAttestationResponseFuture
    No documentation available
I

A slightly-modified RegistrationCredential to simplify working with ArrayBuffers that are Base64URL-encoded in the browser so that they can be sent as JSON to the server.

  • authenticatorAttachment: AuthenticatorAttachment
    No documentation available
  • clientExtensionResults: AuthenticationExtensionsClientOutputs
    No documentation available
  • id: Base64URLString
    No documentation available
  • rawId: Base64URLString
    No documentation available
  • response: AuthenticatorAttestationResponseJSON
    No documentation available
  • type: PublicKeyCredentialType
    No documentation available
I
v
No documentation available
  • getRootCertificates(opts: { identifier: RootCertIdentifier; }): string[]

    Get any registered root certificates for the specified attestation format

  • setRootCertificates(opts: { identifier: RootCertIdentifier; certificates: (Uint8Array_ | string)[]; }): void

    Set potential root certificates for attestation formats that use them. Root certs will be tried one-by-one when validating a certificate path.

Type Aliases

T
AlgKey =
"ecc_x962_raw"
| "ecc_x962_der"
| "rsa_2048_raw"
| "rsa_2048_der"
| "cose"
T
AlternativeDescriptions = { [langCode: string]: string; }

langCode -> "en-US", "ja-JP", etc...

T
AttachmentHint =
"internal"
| "external"
| "wired"
| "wireless"
| "nfc"
| "bluetooth"
| "network"
| "ready"
| "wifi_direct"
T
Attestation =
"basic_full"
| "basic_surrogate"
| "ecdaa"
| "attca"
| "anonca"
| "none"
T
AttestationConveyancePreference = "direct" | "enterprise" | "indirect" | "none"
No documentation available
T
AttestationFormat =
"fido-u2f"
| "packed"
| "android-safetynet"
| "android-key"
| "tpm"
| "apple"
| "none"

Values for an attestation object's fmt

T
AttestationFormatVerifierOpts = { aaguid: Uint8Array_; attStmt: AttestationStatement; authData: Uint8Array_; clientDataHash: Uint8Array_; credentialID: Uint8Array_; credentialPublicKey: Uint8Array_; rootCertificates: string[]; rpIdHash: Uint8Array_; verifyTimestampMS?: boolean; attestationSafetyNetEnforceCTSCheck?: boolean; }

Values passed to all attestation format verifiers, from which they are free to use as they please

T
AuthenticatorAttachment = "cross-platform" | "platform"
No documentation available
T
AuthenticatorGetInfo = { versions: ("FIDO_2_0" | "U2F_V2")[]; extensions?: string[]; aaguid: string; options?: { plat?: boolean; rk?: boolean; clientPin?: boolean; up?: boolean; uv?: boolean; }; maxMsgSize?: number; pinProtocols?: number[]; algorithms?: { type: "public-key"; alg: number; }[]; }
  • aaguid: string
    No documentation available
  • algorithms: { type: "public-key"; alg: number; }[]
    No documentation available
  • extensions: string[]
    No documentation available
  • maxMsgSize: number
    No documentation available
  • options: { plat?: boolean; rk?: boolean; clientPin?: boolean; up?: boolean; uv?: boolean; }
    No documentation available
  • pinProtocols: number[]
    No documentation available
  • versions: ("FIDO_2_0" | "U2F_V2")[]
    No documentation available
T
AuthenticatorStatus =
"NOT_FIDO_CERTIFIED"
| "FIDO_CERTIFIED"
| "USER_VERIFICATION_BYPASS"
| "ATTESTATION_KEY_COMPROMISE"
| "USER_KEY_REMOTE_COMPROMISE"
| "USER_KEY_PHYSICAL_COMPROMISE"
| "UPDATE_AVAILABLE"
| "REVOKED"
| "SELF_ASSERTION_SUBMITTED"
| "FIDO_CERTIFIED_L1"
| "FIDO_CERTIFIED_L1plus"
| "FIDO_CERTIFIED_L2"
| "FIDO_CERTIFIED_L2plus"
| "FIDO_CERTIFIED_L3"
| "FIDO_CERTIFIED_L3plus"
No documentation available
T
AuthenticatorTransport = "ble" | "hybrid" | "internal" | "nfc" | "usb"
No documentation available
T
AuthenticatorTransportFuture =
"ble"
| "cable"
| "hybrid"
| "internal"
| "nfc"
| "smart-card"
| "usb"

A super class of TypeScript's AuthenticatorTransport that includes support for the latest transports. Should eventually be replaced by TypeScript's when TypeScript gets updated to know about it (sometime after 4.6.3)

T

An attempt to communicate that this isn't just any string, but a Base64URL-encoded string

T
BiometricAccuracyDescriptor = { selfAttestedFRR?: number; selfAttestedFAR?: number; maxTemplates?: number; maxRetries?: number; blockSlowdown?: number; }
No documentation available
T
BiometricStatusReport = { certLevel: number; modality: UserVerify; effectiveDate?: string; certificationDescriptor?: string; certificateNumber?: string; certificationPolicyVersion?: string; certificationRequirementsVersion?: string; }
No documentation available
T
CodeAccuracyDescriptor = { base: number; minLength: number; maxRetries?: number; blockSlowdown?: number; }

Types defined in the FIDO Metadata Statement spec

T
No documentation available
T
CredentialDeviceType = "singleDevice" | "multiDevice"

The two types of credentials as defined by bit 3 ("Backup Eligibility") in authenticator data:

T
DisplayPNGCharacteristicsDescriptor = { width: number; height: number; bitDepth: number; colorType: number; compression: number; filter: number; interlace: number; plte?: rgbPaletteEntry[]; }
No documentation available
  • bitDepth: number
    No documentation available
  • colorType: number
    No documentation available
  • compression: number
    No documentation available
  • filter: number
    No documentation available
  • height: number
    No documentation available
  • interlace: number
    No documentation available
  • plte: rgbPaletteEntry[]
    No documentation available
  • width: number
    No documentation available
T
EcdaaTrustAnchor = { X: string; Y: string; c: string; sx: string; sy: string; G1Curve: string; }
No documentation available
  • G1Curve: string
    No documentation available
  • X: string
    No documentation available
  • Y: string
    No documentation available
  • c: string
    No documentation available
  • sx: string
    No documentation available
  • sy: string
    No documentation available
T
ExtensionDescriptor = { id: string; tag?: number; data?: string; fail_if_unknown: boolean; }
No documentation available
  • data: string
    No documentation available
  • No documentation available
  • id: string
    No documentation available
  • tag: number
    No documentation available
T
GenerateAuthenticationOptionsOpts = Parameters<generateAuthenticationOptions>[0]
No documentation available
T
GenerateRegistrationOptionsOpts = Parameters<generateRegistrationOptions>[0]
No documentation available
T
KeyProtection =
"software"
| "hardware"
| "tee"
| "secure_element"
| "remote_handle"
T
MDSJWTHeader = { alg: string; typ: string; x5c: Base64URLString[]; }
No documentation available
  • alg: string
    No documentation available
  • typ: string
    No documentation available
  • x5c: Base64URLString[]
    No documentation available
T
MDSJWTPayload = { legalHeader: string; no: number; nextUpdate: string; entries: MetadataBLOBPayloadEntry[]; }
No documentation available
  • entries: MetadataBLOBPayloadEntry[]
    No documentation available
  • legalHeader: string
    No documentation available
  • nextUpdate: string
    No documentation available
  • no: number
    No documentation available
T
MetadataBLOBPayloadEntry = { aaid?: string; aaguid?: string; attestationCertificateKeyIdentifiers?: string[]; metadataStatement?: MetadataStatement; biometricStatusReports?: BiometricStatusReport[]; statusReports: StatusReport[]; timeOfLastStatusChange: string; rogueListURL?: string; rogueListHash?: string; }
No documentation available
T
MetadataStatement = { legalHeader?: string; aaid?: string; aaguid?: string; attestationCertificateKeyIdentifiers?: string[]; description: string; alternativeDescriptions?: AlternativeDescriptions; authenticatorVersion: number; protocolFamily: string; schema: number; upv: Version[]; authenticationAlgorithms: AlgSign[]; publicKeyAlgAndEncodings: AlgKey[]; attestationTypes: Attestation[]; userVerificationDetails: VerificationMethodANDCombinations[]; keyProtection: KeyProtection[]; isKeyRestricted?: boolean; isFreshUserVerificationRequired?: boolean; matcherProtection: MatcherProtection[]; cryptoStrength?: number; attachmentHint?: AttachmentHint[]; tcDisplay: TransactionConfirmationDisplay[]; tcDisplayContentType?: string; tcDisplayPNGCharacteristics?: DisplayPNGCharacteristicsDescriptor[]; attestationRootCertificates: string[]; ecdaaTrustAnchors?: EcdaaTrustAnchor[]; icon?: string; supportedExtensions?: ExtensionDescriptor[]; authenticatorGetInfo?: AuthenticatorGetInfo; }
No documentation available
T
PatternAccuracyDescriptor = { minComplexity: number; maxRetries?: number; blockSlowdown?: number; }
No documentation available
T
PublicKeyCredentialHint = "hybrid" | "security-key" | "client-device"

Categories of authenticators that Relying Parties can pass along to browsers during registration. Browsers that understand these values can optimize their modal experience to start the user off in a particular registration flow:

T
PublicKeyCredentialJSON = RegistrationResponseJSON | AuthenticationResponseJSON
No documentation available
T
No documentation available
T
ResidentKeyRequirement = "discouraged" | "preferred" | "required"
No documentation available
T
rgbPaletteEntry = { r: number; g: number; b: number; }
No documentation available
  • b: number
    No documentation available
  • g: number
    No documentation available
  • r: number
    No documentation available
T
RootCertIdentifier = AttestationFormat | "mds"
No documentation available
T
StatusReport = { status: AuthenticatorStatus; effectiveDate?: string; authenticatorVersion?: number; certificate?: string; url?: string; certificationDescriptor?: string; certificateNumber?: string; certificationPolicyVersion?: string; certificationRequirementsVersion?: string; }
No documentation available
T
T
Uint8Array_ = ReturnType<Uint8Array["slice"]>

Equivalent to Uint8Array before TypeScript 5.7, and Uint8Array<ArrayBuffer> in TypeScript 5.7 and beyond.

T
UserVerificationRequirement = "discouraged" | "preferred" | "required"
No documentation available
T
UserVerify =
"presence_internal"
| "fingerprint_internal"
| "passcode_internal"
| "voiceprint_internal"
| "faceprint_internal"
| "location_internal"
| "eyeprint_internal"
| "pattern_internal"
| "handprint_internal"
| "passcode_external"
| "pattern_external"
| "none"
| "all"
T
VerificationMethodANDCombinations = VerificationMethodDescriptor[]
No documentation available
T
VerificationMethodDescriptor = { userVerificationMethod: UserVerify; caDesc?: CodeAccuracyDescriptor; baDesc?: BiometricAccuracyDescriptor; paDesc?: PatternAccuracyDescriptor; }
No documentation available
  • baDesc: BiometricAccuracyDescriptor
    No documentation available
  • caDesc: CodeAccuracyDescriptor
    No documentation available
  • paDesc: PatternAccuracyDescriptor
    No documentation available
  • No documentation available
T
VerificationMode = "permissive" | "strict"

Allow MetadataService to accommodate unregistered AAGUIDs ("permissive"), or only allow registered AAGUIDs ("strict"). Currently primarily impacts how getStatement() operates

T
VerifiedAuthenticationResponse = { verified: boolean; authenticationInfo: { credentialID: Base64URLString; newCounter: number; userVerified: boolean; credentialDeviceType: CredentialDeviceType; credentialBackedUp: boolean; origin: string; rpID: string; authenticatorExtensionResults?: AuthenticationExtensionsAuthenticatorOutputs; }; }

Result of authentication verification

  • authenticationInfo: { credentialID: Base64URLString; newCounter: number; userVerified: boolean; credentialDeviceType: CredentialDeviceType; credentialBackedUp: boolean; origin: string; rpID: string; authenticatorExtensionResults?: AuthenticationExtensionsAuthenticatorOutputs; }
    No documentation available
  • verified: boolean
    No documentation available
T
VerifiedRegistrationResponse =
{ verified: false; registrationInfo?: never; }
| { verified: true; registrationInfo: { fmt: AttestationFormat; aaguid: string; credential: WebAuthnCredential; credentialType: "public-key"; attestationObject: Uint8Array_; userVerified: boolean; credentialDeviceType: CredentialDeviceType; credentialBackedUp: boolean; origin: string; rpID?: string; authenticatorExtensionResults?: AuthenticationExtensionsAuthenticatorOutputs; }; }

Result of registration verification

T
VerifyAuthenticationResponseOpts = Parameters<verifyAuthenticationResponse>[0]

Configurable options when calling verifyAuthenticationResponse()

T
VerifyRegistrationResponseOpts = Parameters<verifyRegistrationResponse>[0]

Configurable options when calling verifyRegistrationResponse()

  • major: number
    No documentation available
  • minor: number
    No documentation available
T
WebAuthnCredential = { id: Base64URLString; publicKey: Uint8Array_; counter: number; transports?: AuthenticatorTransportFuture[]; }

Public key credential information needed to verify authentication responses

  • counter: number
    No documentation available
  • id: Base64URLString
    No documentation available
  • publicKey: Uint8Array_
    No documentation available
  • transports: AuthenticatorTransportFuture[]
    No documentation available

Variables

Report package

Please provide a reason for reporting this package. We will review your report and take appropriate action.

Please review the JSR usage policy before submitting a report.

Add Package

deno add jsr:@simplewebauthn/server

Import symbol

import * as mod from "@simplewebauthn/server";
or

Import directly with a jsr specifier

import * as mod from "jsr:@simplewebauthn/server";