@thru/passkey

View as Markdown

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

Install

npm install @thru/passkey

Entry Points

Import	What it provides
`@thru/passkey`	Root browser registration/signing exports plus shared passkey types and helpers.
`@thru/passkey/web`	Browser WebAuthn exports.
`@thru/passkey/popup`	Popup bridge helpers for iframe or restricted WebAuthn environments.
`@thru/passkey/mobile`	Mobile passkey helpers.
`@thru/passkey/auth`	Higher-level auth flow helpers.
`@thru/passkey/auth/add-device`	Add-device auth helpers.
`@thru/passkey/server`	Server-side challenge and submit helpers.

When To Use It

Choose @thru/passkey when you need WebAuthn registration, signing, popup fallback behavior, or passkey auth helpers.

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";

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";

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