@thru/passkey

View as Markdown

@thru/passkey is the WebAuthn package for browser passkey registration, signing, popup-based fallback flows, and supporting helpers.

Install

npm install @thru/passkey

Entry Points

Import	What it provides
`@thru/passkey/web`	Browser WebAuthn registration, signing, capability checks, and shared passkey helpers.
`@thru/passkey/popup`	Popup bridge helpers for iframe or restricted WebAuthn environments.
`@thru/passkey`	Root package entrypoint. Prefer `@thru/passkey/web` for browser code.
`@thru/passkey/mobile`	Mobile passkey helpers. Not covered by this browser reference.
`@thru/passkey/auth`	Higher-level auth flow helpers.
`@thru/passkey/server`	Server-side challenge and submit helpers. Not covered by this browser reference.

When To Use It

Choose @thru/passkey/web when you need WebAuthn registration, signing, popup fallback behavior, or browser capability checks.

Choose a different package when:

you need to build passkey-manager transaction instructions and wallet account context: use @thru/programs with @thru/programs/passkey-manager
you only need byte or address helpers without WebAuthn flows: use @thru/sdk/helpers

Browser Import

import {
  getPasskeyClientCapabilities,
  isWebAuthnSupported,
  registerPasskey,
  signWithDiscoverablePasskey,
  signWithPasskey,
  signWithStoredPasskey,
} from "@thru/passkey/web";

Main Flows

Export	Use for
`registerPasskey(alias, userId, rpId)`	Creating a new platform passkey for a user profile.
`signWithPasskey(credentialId, challenge, rpId)`	Signing with a known credential ID.
`signWithStoredPasskey(challenge, rpId, preferredPasskey, allPasskeys, context?)`	Signing with stored metadata, including embedded and iframe flows.
`signWithDiscoverablePasskey(challenge, rpId)`	Letting the browser prompt the user to choose from available passkeys.

registerPasskey and the signing helpers require browser WebAuthn support. When the browser is inside an iframe or permissions policy blocks inline prompts, the package can fall back to its popup flow.

Example

import {
  isWebAuthnSupported,
  registerPasskey,
  signWithPasskey,
} from "@thru/passkey/web";

if (!isWebAuthnSupported()) {
  throw new Error("WebAuthn is not available");
}

const registration = await registerPasskey(
  "Primary device",
  "user-123",
  "wallet.thru.org"
);

const result = await signWithPasskey(
  registration.credentialId,
  challengeBytes,
  "wallet.thru.org"
);

Capability Checks

Use these exports to decide whether inline WebAuthn is available and whether you should preopen or prefer the popup bridge:

isWebAuthnSupported, preloadPasskeyClientCapabilities, getPasskeyClientCapabilities, getCachedPasskeyClientCapabilities, shouldUsePasskeyPopup, isInIframe

The package exports the pieces used by the popup window and its parent window:

PASSKEY_POPUP_PATH, PASSKEY_POPUP_READY_EVENT, PASSKEY_POPUP_REQUEST_EVENT, PASSKEY_POPUP_RESPONSE_EVENT, PASSKEY_POPUP_CHANNEL, openPasskeyPopupWindow, closePopup, requestPasskeyPopup

Popup-side helpers:

toPopupSigningResult, buildSuccessResponse, decodeChallenge, getPopupDisplayInfo, getResponseError, signWithPreferredPasskey, buildStoredPasskeyResult

Shared Helpers

For compatibility with passkey-manager flows, the package also exports P-256 and byte utilities:

parseDerSignature, normalizeLowS, normalizeSignatureComponent, P256_N, P256_HALF_N, bytesToBigIntBE, bigIntToBytesBE, arrayBufferToBase64Url, base64UrlToArrayBuffer, bytesToBase64Url, base64UrlToBytes, bytesToHex, hexToBytes, bytesEqual, compareBytes, uniqueAccounts