use-web-authn

Encode bytes as unpadded base64url.


Package	`@vizejs/composable/use-web-authn`
Own the source	`vize lib pull composable:use-web-authn`
Runtime exports	`useWebAuthn`, `encodeBase64Url`, `decodeBase64Url`, `parseCreationOptionsFromJSON`, `parseRequestOptionsFromJSON`, `serializeRegistrationCredential`, `serializeAuthenticationCredential`
Gzip budget	4096 B

Usage

import { useWebAuthn, encodeBase64Url, decodeBase64Url, parseCreationOptionsFromJSON, parseRequestOptionsFromJSON, serializeRegistrationCredential, serializeAuthenticationCredential } from "@vizejs/composable/use-web-authn";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useWebAuthn`	capability	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`AbortController`, `atob`, `window`	`tryOnScopeDispose`
`encodeBase64Url`	system	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	`btoa`	—
`decodeBase64Url`	system	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	`atob`	—
`parseCreationOptionsFromJSON`	system	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	`atob`	—
`parseRequestOptionsFromJSON`	system	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	`atob`	—
`serializeRegistrationCredential`	system	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	`btoa`	—
`serializeAuthenticationCredential`	system	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	`btoa`	—

API

`encodeBase64Url`

Encode bytes as unpadded base64url.

function encodeBase64Url(bytes: ArrayBuffer | ArrayBufferView): string

`decodeBase64Url`

Decode base64url (padded or unpadded) into bytes.

function decodeBase64Url(text: string): Uint8Array<ArrayBuffer>

`parseCreationOptionsFromJSON`

Convert server creation-options JSON into binary options for create.

function parseCreationOptionsFromJSON( json: PublicKeyCredentialCreationOptionsJSON, ): WebAuthnCreationInit

`parseRequestOptionsFromJSON`

Convert server request-options JSON into binary options for get.

function parseRequestOptionsFromJSON( json: PublicKeyCredentialRequestOptionsJSON, ): WebAuthnRequestInit

`serializeRegistrationCredential`

Serialize a registration credential into JSON-safe base64url fields.

function serializeRegistrationCredential( credential: RegistrationCredentialLike, ): RegistrationResponseJSON

`serializeAuthenticationCredential`

Serialize an authentication credential into JSON-safe base64url fields.

function serializeAuthenticationCredential( credential: AuthenticationCredentialLike, ): AuthenticationResponseJSON

`useWebAuthn`

Register and authenticate passkeys with the Web Authentication API. create and get accept binary options or server JSON, run one ceremony at a time (starting one aborts the previous), and resolve to a discriminated WebAuthnResult. Use the exported pure helpers to serialize results for the server. A pending ceremony is aborted when the owning reactive scope stops; outside a scope call abort(). Server rendering: nothing is requested, supported and pending are false.

function useWebAuthn(options: UseWebAuthnOptions = {}): WebAuthnControls

const webAuthn = useWebAuthn();
const result = await webAuthn.get(await fetchJSON("/login/options"));
if (result.status === "success") await post(serializeAuthenticationCredential(result.credential));

Types

`PublicKeyCredentialDescriptorJSON`

Credential descriptor in server JSON form.

Member	Type	Description
`type`	`"public-key"`	Credential type.
`id`	`string`	Base64url-encoded credential id.
`transports`?	`readonly WebAuthnTransport[]`	Transports the credential is reachable through.

`WebAuthnCredentialDescriptor`

Credential descriptor in binary form.

Member	Type	Description
`type`	`"public-key"`	Credential type.
`id`	`Uint8Array<ArrayBuffer>`	Raw credential id.
`transports`?	`WebAuthnTransport[]`	Transports the credential is reachable through.

`WebAuthnAuthenticatorSelection`

Authenticator selection criteria of a registration ceremony.

Member	Type	Description
`authenticatorAttachment`?	`WebAuthnAuthenticatorAttachment`	Required attachment modality.
`residentKey`?	`WebAuthnResidentKey`	Discoverable-credential requirement.
`requireResidentKey`?	`boolean`	Legacy discoverable-credential flag.
`userVerification`?	`WebAuthnUserVerification`	User verification requirement.

`WebAuthnRelyingParty`

Relying party entity.

Member	Type	Description
`id`?	`string`	Relying party id (a registrable domain).
`name`	`string`	Human-readable name.

`WebAuthnCredentialParameter`

Public-key algorithm parameter.

Member	Type	Description
`type`	`"public-key"`	Credential type.
`alg`	`number`	COSE algorithm identifier (for example -7 for ES256).

`PublicKeyCredentialCreationOptionsJSON`

PublicKeyCredentialCreationOptions as serialized by a server (binary fields base64url).

Member	Type	Description
`rp`	`Readonly<WebAuthnRelyingParty>`	Relying party.
`user`	`{ readonly id: string; readonly name: string; readonly displayName: string }`	User account with a base64url-encoded `id`.
`challenge`	`string`	Base64url-encoded challenge.
`pubKeyCredParams`	`readonly Readonly<WebAuthnCredentialParameter>[]`	Acceptable algorithms in preference order.
`timeout`?	`number`	Ceremony timeout in milliseconds.
`excludeCredentials`?	`readonly PublicKeyCredentialDescriptorJSON[]`	Credentials that must not be re-registered.
`authenticatorSelection`?	`Readonly<WebAuthnAuthenticatorSelection>`	Authenticator selection criteria.
`attestation`?	`WebAuthnAttestation`	Attestation preference.
`hints`?	`readonly WebAuthnHint[]`	Authenticator hints.
`extensions`?	`Readonly<Record<string, unknown>>`	Client extension inputs; PRF values are decoded from base64url.

`PublicKeyCredentialRequestOptionsJSON`

PublicKeyCredentialRequestOptions as serialized by a server (binary fields base64url).

Member	Type	Description
`challenge`	`string`	Base64url-encoded challenge.
`timeout`?	`number`	Ceremony timeout in milliseconds.
`rpId`?	`string`	Relying party id.
`allowCredentials`?	`readonly PublicKeyCredentialDescriptorJSON[]`	Allowed credentials; empty or omitted for discoverable credentials.
`userVerification`?	`WebAuthnUserVerification`	User verification requirement.
`hints`?	`readonly WebAuthnHint[]`	Authenticator hints.
`extensions`?	`Readonly<Record<string, unknown>>`	Client extension inputs; PRF values are decoded from base64url.

`WebAuthnCreationInit`

Binary creation options passed to navigator.credentials.create.

Member	Type	Description
`rp`	`WebAuthnRelyingParty`	Relying party.
`user`	`{ id: Uint8Array<ArrayBuffer>; name: string; displayName: string }`	User account.
`challenge`	`Uint8Array<ArrayBuffer>`	Challenge bytes.
`pubKeyCredParams`	`WebAuthnCredentialParameter[]`	Acceptable algorithms in preference order.
`timeout`?	`number`	Ceremony timeout in milliseconds.
`excludeCredentials`?	`WebAuthnCredentialDescriptor[]`	Credentials that must not be re-registered.
`authenticatorSelection`?	`WebAuthnAuthenticatorSelection`	Authenticator selection criteria.
`attestation`?	`WebAuthnAttestation`	Attestation preference.
`hints`?	`WebAuthnHint[]`	Authenticator hints.
`extensions`?	`Record<string, unknown>`	Client extension inputs.

`WebAuthnRequestInit`

Binary request options passed to navigator.credentials.get.

Member	Type	Description
`challenge`	`Uint8Array<ArrayBuffer>`	Challenge bytes.
`timeout`?	`number`	Ceremony timeout in milliseconds.
`rpId`?	`string`	Relying party id.
`allowCredentials`?	`WebAuthnCredentialDescriptor[]`	Allowed credentials.
`userVerification`?	`WebAuthnUserVerification`	User verification requirement.
`hints`?	`WebAuthnHint[]`	Authenticator hints.
`extensions`?	`Record<string, unknown>`	Client extension inputs.

`PublicKeyCredentialLike`

Fields shared by every returned PublicKeyCredential.

Member	Type	Description
`id`	`string`	Base64url credential id.
`rawId`	`ArrayBuffer`	Raw credential id.
`type`	`string`	Credential type (`"public-key"`).
`authenticatorAttachment`?	`string \| null`	Attachment of the authenticator that produced the credential.
`getClientExtensionResults`	`() => object`	Client extension outputs.

`RegistrationCredentialLike`

Credential returned by a registration ceremony.

Member	Type	Description
`id`	`string`	Base64url credential id.
`rawId`	`ArrayBuffer`	Raw credential id.
`type`	`string`	Credential type (`"public-key"`).
`authenticatorAttachment`?	`string \| null`	Attachment of the authenticator that produced the credential.
`getClientExtensionResults`	`() => object`	Client extension outputs.
`response`	`{ /** Client data. / readonly clientDataJSON: ArrayBuffer; /* CBOR attestation object. / readonly attestationObject: ArrayBuffer; /* Transports reported by the authenticator. / getTransports?(): readonly string[]; /* DER SubjectPublicKeyInfo of the new credential. / getPublicKey?(): ArrayBuffer \| null; /* COSE algorithm of the new credential. / getPublicKeyAlgorithm?(): number; /* Authenticator data. */ getAuthenticatorData?(): ArrayBuffer; }`	Attestation response.

`AuthenticationCredentialLike`

Credential returned by an authentication ceremony.

Member	Type	Description
`id`	`string`	Base64url credential id.
`rawId`	`ArrayBuffer`	Raw credential id.
`type`	`string`	Credential type (`"public-key"`).
`authenticatorAttachment`?	`string \| null`	Attachment of the authenticator that produced the credential.
`getClientExtensionResults`	`() => object`	Client extension outputs.
`response`	`{ /** Client data. / readonly clientDataJSON: ArrayBuffer; /* Authenticator data. / readonly authenticatorData: ArrayBuffer; /* Assertion signature. / readonly signature: ArrayBuffer; /* User handle of a discoverable credential. */ readonly userHandle: ArrayBuffer \| null; }`	Assertion response.

`RegistrationResponseJSON`

JSON-safe registration result, ready to POST to a server.

Member	Type	Description
`id`	`string`	Base64url credential id.
`rawId`	`string`	Base64url raw credential id.
`type`	`"public-key"`	Credential type.
`authenticatorAttachment`?	`WebAuthnAuthenticatorAttachment`	Authenticator attachment, when known.
`clientExtensionResults`	`object`	Client extension outputs.
`response`	`{ /** Base64url client data. / readonly clientDataJSON: string; /* Base64url attestation object. / readonly attestationObject: string; /* Known transports. / readonly transports?: readonly WebAuthnTransport[]; /* Base64url public key, when exposed. / readonly publicKey?: string; /* COSE algorithm, when exposed. / readonly publicKeyAlgorithm?: number; /* Base64url authenticator data, when exposed. */ readonly authenticatorData?: string; }`	Attestation response with base64url fields.

`AuthenticationResponseJSON`

JSON-safe authentication result, ready to POST to a server.

Member	Type	Description
`id`	`string`	Base64url credential id.
`rawId`	`string`	Base64url raw credential id.
`type`	`"public-key"`	Credential type.
`authenticatorAttachment`?	`WebAuthnAuthenticatorAttachment`	Authenticator attachment, when known.
`clientExtensionResults`	`object`	Client extension outputs.
`response`	`{ /** Base64url client data. / readonly clientDataJSON: string; /* Base64url authenticator data. / readonly authenticatorData: string; /* Base64url signature. / readonly signature: string; /* Base64url user handle, when present. */ readonly userHandle?: string; }`	Assertion response with base64url fields.

`WebAuthnCredentialsHost`

Minimal navigator.credentials consumed by useWebAuthn.

Member	Type	Description
`create`	`(options: { publicKey: WebAuthnCreationInit; signal?: AbortSignal; mediation?: WebAuthnMediation; }) => Promise<unknown>`	Run a registration ceremony.
`get`	`(options: { publicKey: WebAuthnRequestInit; signal?: AbortSignal; mediation?: WebAuthnMediation; }) => Promise<unknown>`	Run an authentication ceremony.

`PublicKeyCredentialStatics`

Static capability checks of PublicKeyCredential.

Member	Type	Description
`isUserVerifyingPlatformAuthenticatorAvailable`?	`() => Promise<boolean>`	Whether a user-verifying platform authenticator (Touch ID, Windows Hello) exists.
`isConditionalMediationAvailable`?	`() => Promise<boolean>`	Whether conditional mediation (passkey autofill) is available.

`UseWebAuthnOptions`

Options for useWebAuthn.

Member	Type	Description
`credentials`?	`MaybeRefOrGetter<WebAuthnCredentialsHost \| null \| undefined>`	Credentials container for alternate runtimes and tests.
`publicKeyCredential`?	`MaybeRef<PublicKeyCredentialStatics \| null \| undefined>`	`PublicKeyCredential` interface used for capability checks. A ref (not a getter) because the browser value is a constructor function.

`WebAuthnCeremonyOptions`

Per-ceremony options of WebAuthnControls.create and WebAuthnControls.get.

Member	Type	Description
`mediation`?	`WebAuthnMediation`	Mediation requirement; `"conditional"` for passkey autofill.
`signal`?	`AbortSignal`	Additional signal aborting the ceremony.

`WebAuthnControls`

Reactive state and actions returned by useWebAuthn.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether WebAuthn is available.
`pending`	`Readonly<Ref<boolean>>`	Whether a ceremony is in progress.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent ceremony failure (not aborts), cleared when a ceremony starts.
`create`	`( options: WebAuthnCreationInit \| PublicKeyCredentialCreationOptionsJSON, ceremony?: WebAuthnCeremonyOptions, ) => Promise<WebAuthnResult<RegistrationCredentialLike>>`	Register a credential. Aborts any pending ceremony first.
`get`	`( options: WebAuthnRequestInit \| PublicKeyCredentialRequestOptionsJSON, ceremony?: WebAuthnCeremonyOptions, ) => Promise<WebAuthnResult<AuthenticationCredentialLike>>`	Authenticate with a credential. Aborts any pending ceremony first.
`abort`	`(reason?: unknown) => void`	Abort the pending ceremony, if any.
`isUserVerifyingPlatformAuthenticatorAvailable`	`() => Promise<boolean>`	Whether a user-verifying platform authenticator exists.
`isConditionalMediationAvailable`	`() => Promise<boolean>`	Whether conditional mediation (passkey autofill) is available.