---
title: "@thru/passkey"
description: Browser WebAuthn package for passkey registration and signing flows.
source_url:
  html: https://thru.org/docs/sdks/web-packages/passkey/
  md: https://thru.org/docs/sdks/web-packages/passkey.md
---

# @thru/passkey

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

## Install

```bash
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`](https://thru.org/docs/sdks/web-packages/programs.md) with `@thru/programs/passkey-manager`
- you only need byte or address helpers without WebAuthn flows: use `@thru/sdk/helpers`

## Browser Import

```ts
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

```ts
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`

## Popup Bridge

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`

## Related

- [`@thru/programs`](https://thru.org/docs/sdks/web-packages/programs.md)
- [Passkey Manager Program](https://thru.org/docs/core-programs/passkey-manager-program.md)
- [`@thru/wallet`](https://thru.org/docs/sdks/web-packages/wallet.md)