@thru/passkey 0.2.13 → 0.2.14

package/README.md

@@ -1,6 +1,6 @@
 # @thru/passkey
 
-Browser-only WebAuthn package for passkey registration, signing, and popup-based flows. Built on top of `@thru/passkey-manager` for platform-agnostic crypto and encoding utilities.
+Cross-platform passkey helpers for Thru applications.
 
 ## Installation
 
@@ -8,82 +8,74 @@ Browser-only WebAuthn package for passkey registration, signing, and popup-based
 npm install @thru/passkey
 ```
 
-This package requires a browser environment with WebAuthn support (`navigator.credentials`).
+## Entry Points
 
-## Basic Usage
+- `@thru/passkey/web` - browser/WebAuthn registration and signing
+- `@thru/passkey/popup` - popup bridge/protocol helpers for embedded browser flows
+- `@thru/passkey/mobile` - React Native/mobile passkey and secure-storage helpers
+- `@thru/passkey/auth` - higher-level app auth/store helpers
+- `@thru/passkey/server` - backend wallet/challenge/submit helpers
 
-### Register a Passkey
+## Deprecated Root Import
 
-Create a new P-256 credential bound to the user's platform authenticator:
+The root import path is deprecated:
 
 ```typescript
 import { registerPasskey } from '@thru/passkey';
+```
+
+Use explicit entry points instead:
+
+```typescript
+import { registerPasskey } from '@thru/passkey/web';
+```
+
+The root path remains as a temporary compatibility shim and will be removed after downstream consumers migrate.
+
+## Browser Usage
+
+This package requires a browser environment with WebAuthn support (`navigator.credentials`).
+
+### Register a Passkey
+
+```typescript
+import { registerPasskey } from '@thru/passkey/web';
 
 const result = await registerPasskey('alice', 'user-id-123', 'example.com');
-// result.credentialId  - base64url credential ID
-// result.publicKeyX    - hex-encoded P-256 X coordinate
-// result.publicKeyY    - hex-encoded P-256 Y coordinate
-// result.rpId          - relying party ID
 ```
 
 ### Sign with a Known Credential
 
-Sign a challenge using a specific credential ID:
-
 ```typescript
-import { signWithPasskey } from '@thru/passkey';
+import { signWithPasskey } from '@thru/passkey/web';
 
-const challenge = new Uint8Array(32); // your challenge bytes
+const challenge = new Uint8Array(32);
 const result = await signWithPasskey(credentialId, challenge, 'example.com');
-// result.signature         - 64-byte concatenated r||s (low-S normalized)
-// result.signatureR        - 32-byte r component
-// result.signatureS        - 32-byte s component
-// result.authenticatorData - raw authenticator data
-// result.clientDataJSON    - raw client data JSON
 ```
 
 ### Sign with a Stored Passkey
 
-For embedded or iframe contexts where you have stored passkey metadata. Automatically falls back to a popup window when inline WebAuthn is restricted:
-
 ```typescript
-import { signWithStoredPasskey } from '@thru/passkey';
-import type { PasskeyMetadata } from '@thru/passkey';
+import { signWithStoredPasskey } from '@thru/passkey/web';
+import type { PasskeyMetadata, PasskeyPopupContext } from '@thru/passkey/web';
+
+const preferredPasskey: PasskeyMetadata | null = null;
+const allPasskeys: PasskeyMetadata[] = [];
+const context: PasskeyPopupContext = {
+  appName: 'My App',
+  origin: 'https://app.example.com',
+};
 
 const result = await signWithStoredPasskey(
   challenge,
   'example.com',
-  preferredPasskey,  // PasskeyMetadata | null
-  allPasskeys,       // PasskeyMetadata[]
-  { appName: 'My App', origin: 'https://app.example.com' }
+  preferredPasskey,
+  allPasskeys,
+  context
 );
-// result includes .passkey metadata for the credential that signed
 ```
 
-### Sign with a Discoverable Passkey
-
-Let the browser prompt the user to choose from their available passkeys:
-
-```typescript
-import { signWithDiscoverablePasskey } from '@thru/passkey';
-
-const result = await signWithDiscoverablePasskey(challenge, 'example.com');
-// result.credentialId - the credential the user selected
-// result.rpId         - relying party ID
-```
-
-## Key Capabilities
-
-- **P-256 (ES256) credential creation** via `navigator.credentials.create` with platform authenticator selection, resident key, and user verification required
-- **Three signing modes**: known credential, stored passkey with fallback, and discoverable (browser-prompted)
-- **Automatic popup fallback** for iframe/embedded contexts where the Permissions Policy blocks inline WebAuthn
-- **Low-S signature normalization** applied to all signing results for protocol compatibility
-- **Capability detection** to query WebAuthn support, client capabilities, and determine the optimal prompt mode before signing
-- **Re-exports** encoding and crypto utilities from `@thru/passkey-manager` for backward compatibility
-
-## Capability Detection
-
-Check browser support and determine the best prompt mode ahead of time:
+### Capability Detection
 
 ```typescript
 import {
@@ -91,27 +83,12 @@ import {
   preloadPasskeyClientCapabilities,
   getPasskeyClientCapabilities,
   shouldUsePasskeyPopup,
-  isInIframe,
-} from '@thru/passkey';
-
-// Quick synchronous check
-if (!isWebAuthnSupported()) {
-  // WebAuthn not available
-}
-
-// Preload capabilities early (e.g., on app init)
-preloadPasskeyClientCapabilities();
-
-// Later, read cached or await capabilities
-const capabilities = await getPasskeyClientCapabilities();
-
-// Check if a popup is needed for a given action
-const needsPopup = await shouldUsePasskeyPopup('get');
+} from '@thru/passkey/web';
 ```
 
 ## Popup Bridge
 
-For applications that host the passkey popup window (e.g., the wallet app), the package provides both the parent-side and popup-side APIs:
+Use the popup helpers when your browser app needs a separate approval window for embedded or iframe-based passkey flows.
 
 ### Parent Side
 
@@ -122,44 +99,50 @@ import {
   closePopup,
   PASSKEY_POPUP_PATH,
   PASSKEY_POPUP_CHANNEL,
-} from '@thru/passkey';
+} from '@thru/passkey/popup';
 ```
 
 ### Popup Window Side
 
 ```typescript
 import {
-  toPopupSigningResult,
   buildSuccessResponse,
   decodeChallenge,
-  getPopupDisplayInfo,
   getResponseError,
-  signWithPreferredPasskey,
-  buildStoredPasskeyResult,
-} from '@thru/passkey';
+  toPopupSigningResult,
+} from '@thru/passkey/popup';
 ```
 
 Communication between parent and popup uses `postMessage` with `BroadcastChannel` as a fallback. The popup path defaults to `/passkey/popup`.
 
-## Re-exported Utilities
+## Browser Convenience Exports
 
-The following are re-exported from `@thru/passkey-manager` for convenience:
+`@thru/passkey/web` re-exports the browser-side encoding and crypto helpers used by the wallet today, including:
 
-**Crypto**: `parseDerSignature`, `normalizeLowS`, `normalizeSignatureComponent`, `P256_N`, `P256_HALF_N`, `bytesToBigIntBE`, `bigIntToBytesBE`
-
-**Encoding**: `arrayBufferToBase64Url`, `base64UrlToArrayBuffer`, `bytesToBase64Url`, `base64UrlToBytes`, `bytesToHex`, `hexToBytes`, `bytesEqual`, `compareBytes`, `uniqueAccounts`
+- `bytesToHex`
+- `hexToBytes`
+- `bytesToBase64`
+- `bytesToBase64Url`
+- `base64UrlToBytes`
+- `arrayBufferToBase64Url`
+- `base64UrlToArrayBuffer`
 
 ## Types
 
-Key types exported from this package:
-
-| Type | Description |
-|------|-------------|
-| `PasskeyRegistrationResult` | Credential ID and P-256 public key coordinates |
-| `PasskeySigningResult` | Signature bytes, authenticator data, and client data |
-| `PasskeyDiscoverableSigningResult` | Signing result with credential ID and rpId |
-| `PasskeyStoredSigningResult` | Signing result with attached passkey metadata |
-| `PasskeyMetadata` | Stored passkey info (credential ID, public key, rpId, timestamps) |
-| `PasskeyClientCapabilities` | WebAuthn client capability flags |
-| `PasskeyPopupContext` | App context passed to popup for display |
-| `PasskeyPopupAccount` | Account info passed through popup bridge |
+Key web types exported from `@thru/passkey/web`:
+
+- `PasskeyRegistrationResult`
+- `PasskeySigningResult`
+- `PasskeyDiscoverableSigningResult`
+- `PasskeyStoredSigningResult`
+- `PasskeyMetadata`
+- `PasskeyClientCapabilities`
+- `PasskeyPopupContext`
+
+Key popup types exported from `@thru/passkey/popup`:
+
+- `PasskeyPopupRequest`
+- `PasskeyPopupResponse`
+- `PasskeyPopupSigningResult`
+- `PasskeyPopupStoredSigningResult`
+- `PasskeyPopupAccount`