@thru/passkey 0.2.21 → 0.2.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thru/passkey",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -31,6 +31,11 @@
       "import": "./dist/auth.js",
       "require": "./dist/auth.cjs"
     },
+    "./auth/add-device": {
+      "types": "./dist/auth/add-device.d.ts",
+      "import": "./dist/auth/add-device.js",
+      "require": "./dist/auth/add-device.cjs"
+    },
     "./server": {
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js",
@@ -38,8 +43,8 @@
     }
   },
   "dependencies": {
-    "@thru/passkey-manager": "0.2.21",
-    "@thru/thru-sdk": "0.2.21"
+    "@thru/sdk": "0.2.23",
+    "@thru/programs": "0.2.23"
   },
   "peerDependencies": {
     "expo-secure-store": "*",
@@ -62,9 +67,9 @@
     }
   },
   "devDependencies": {
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   },
   "scripts": {
     "build": "tsup",

package/src/auth/add-device.ts

@@ -0,0 +1,236 @@
+/* Add-passkey-to-account transaction builder, lifted from
+   `web/wallet-auth-manager/app/page.tsx` (`runValidateThen`,
+   `handleSubmitAddPasskey`) so the wallet's `/embedded` post-connect
+   step can reuse the exact same flow.
+
+   Builds the on-chain transaction:
+     VALIDATE(existingAuthority -> ADD_AUTHORITY(newPasskey))
+     or VALIDATE(existingAuthority -> multicall[ADD_AUTHORITY, REGISTER_CREDENTIAL])
+   asks the caller's existing passkey to sign the challenge, then asks
+   the caller's wallet signer to sign the assembled transaction, sends
+   it, and returns the result. */
+
+import {
+  type Authority,
+  buildAccountContext,
+  createValidateChallenge,
+  createCredentialLookupSeed,
+  decodeAddress,
+  deriveWalletAddress,
+  encodeAddAuthorityInstruction,
+  encodeRegisterCredentialInstruction,
+  encodeValidateInstruction,
+  parseWalletAuthorities,
+  type ParsedAuthority,
+  type WalletSigner,
+} from "@thru/programs/passkey-manager";
+import {
+  MULTICALL_PROGRAM_PUBKEY,
+  buildMulticallInstruction,
+} from "@thru/programs/multicall";
+
+/** Minimal shape required from a passkey signer. Both web's
+    `signWithDiscoverablePasskey`/`signWithPasskey` and mobile's
+    counterparts conform. */
+export interface PasskeyChallengeSigner {
+  signChallenge: (challenge: Uint8Array) => Promise<{
+    signatureR: Uint8Array;
+    signatureS: Uint8Array;
+    authenticatorData: Uint8Array;
+    clientDataJSON: Uint8Array;
+  }>;
+}
+
+/** Minimal shape required from a Thru chain client. Loosely-typed
+    because @thru/sdk's DTS emit is currently broken in this
+    repo. The caller passes the real Thru and we narrow operationally. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyThruClient = any;
+
+export interface AddDeviceParams {
+  /** Loosely-typed Thru chain client (`@thru/sdk/client`). */
+  thru: AnyThruClient;
+  /** Wallet (the on-chain WalletAccount) to attach the passkey to. */
+  walletAddress: string;
+  /** Index of the existing authority that approves this change. Must
+      currently be a passkey authority. */
+  authIdx: number;
+  /** New passkey to attach. tag = 1 (passkey). */
+  newAuthority: Authority;
+  /** Optional credential-lookup registration so the new passkey is
+      discoverable on subsequent sign-ins. */
+  credentialId?: Uint8Array;
+  walletName?: string;
+  /** Existing-passkey challenge signer (web or mobile). */
+  passkey: PasskeyChallengeSigner;
+  /** Wallet transaction signer that returns base64(signed bytes). */
+  walletSigner: WalletSigner;
+  /** Passkey program address (base58). */
+  programAddress: string;
+  /** Sign-and-send executor (lifted from passkey-transaction.ts in the
+      wallet-auth-manager - wallet apps own this because it depends on
+      the `Thru` client's transaction builder). */
+  executor: TxExecutor;
+  /** Optional status callback so UIs can show progress. */
+  onStatus?: (message: string) => void;
+}
+
+export interface TxExecutorParams {
+  thru: AnyThruClient;
+  walletSigner: WalletSigner;
+  instructionData: Uint8Array;
+  readWriteAddresses: string[];
+  readOnlyAddresses: string[];
+  label: string;
+}
+
+export interface TxExecutorResult {
+  signature: string;
+  /** Loosely-typed because @thru/sdk types aren't available. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  execution: any;
+}
+
+export type TxExecutor = (
+  params: TxExecutorParams,
+) => Promise<TxExecutorResult>;
+
+export interface AddDeviceResult extends TxExecutorResult {
+  /** The new passkey's authority index after the transaction lands. */
+  newAuthorityIdx: number;
+}
+
+/**
+ * Run VALIDATE + ADD_AUTHORITY [+ REGISTER_CREDENTIAL] to attach a new
+ * passkey to an on-chain WalletAccount.
+ */
+export async function addDeviceToAccount(
+  params: AddDeviceParams,
+): Promise<AddDeviceResult> {
+  const status = params.onStatus ?? (() => {});
+
+  const walletAccount = await params.thru.accounts.get(params.walletAddress);
+  const walletData: Uint8Array | undefined = walletAccount?.data?.data;
+  if (!walletData) {
+    throw new Error("Wallet account data missing");
+  }
+
+  const parsed = parseWalletAuthorities(walletData);
+  const authorizing: ParsedAuthority | undefined =
+    parsed.authorities[params.authIdx];
+  if (!authorizing) {
+    throw new Error("Authorization index out of bounds");
+  }
+  if (authorizing.kind !== "passkey") {
+    throw new Error(
+      "addDeviceToAccount currently requires a passkey authority for VALIDATE",
+    );
+  }
+
+  /* The new authority will land at the next free slot. */
+  const newAuthorityIdx = parsed.authorities.length;
+
+  let readWriteAccounts: Uint8Array[] = [];
+  let lookupSeed: Uint8Array | undefined;
+  let lookupAddressBytes: Uint8Array | undefined;
+  let lookupProof: Uint8Array | undefined;
+
+  if (params.credentialId) {
+    lookupSeed = await createCredentialLookupSeed(params.credentialId);
+    lookupAddressBytes = await deriveWalletAddress(
+      lookupSeed,
+      params.programAddress,
+    );
+
+    status("Fetching state proof for credential lookup...");
+    const proofResult = await params.thru.proofs.generate({
+      proofType: 1 /* StateProofType.CREATING */,
+      address: lookupAddressBytes,
+    });
+    lookupProof = proofResult.proof;
+    readWriteAccounts = [lookupAddressBytes];
+  }
+
+  const ctx = buildAccountContext({
+    walletAddress: params.walletAddress,
+    readWriteAccounts,
+    readOnlyAccounts: params.credentialId ? [MULTICALL_PROGRAM_PUBKEY] : [],
+    programAddress: params.programAddress,
+  });
+
+  const passkeyProgramPubkey = decodeAddress(params.programAddress);
+  const addAuthorityInstruction = encodeAddAuthorityInstruction({
+    walletAccountIdx: ctx.walletAccountIdx,
+    authority: params.newAuthority,
+  });
+
+  let targetProgramIdx = ctx.getAccountIndex(passkeyProgramPubkey);
+  let targetInstructionData = addAuthorityInstruction;
+
+  if (params.credentialId) {
+    if (!lookupSeed || !lookupAddressBytes || !lookupProof) {
+      throw new Error("Credential lookup proof data missing");
+    }
+
+    const registerCredentialInstruction = encodeRegisterCredentialInstruction({
+      walletAccountIdx: ctx.walletAccountIdx,
+      lookupAccountIdx: ctx.getAccountIndex(lookupAddressBytes),
+      seed: lookupSeed,
+      stateProof: lookupProof,
+    });
+
+    targetProgramIdx = ctx.getAccountIndex(MULTICALL_PROGRAM_PUBKEY);
+    targetInstructionData = buildMulticallInstruction([
+      {
+        programIdx: ctx.getAccountIndex(passkeyProgramPubkey),
+        instructionData: addAuthorityInstruction,
+      },
+      {
+        programIdx: ctx.getAccountIndex(passkeyProgramPubkey),
+        instructionData: registerCredentialInstruction,
+      },
+    ]);
+  }
+
+  /* Build the VALIDATE challenge over the target CPI and ask the caller's passkey to sign. */
+  const challenge = await createValidateChallenge(
+    parsed.nonce,
+    ctx.accountAddresses,
+    ctx.walletAccountIdx,
+    params.authIdx,
+    {
+      programIdx: targetProgramIdx,
+      instructionData: targetInstructionData,
+    },
+  );
+
+  status("Waiting for passkey approval...");
+  const signature = await params.passkey.signChallenge(challenge);
+
+  const validateInstruction = encodeValidateInstruction({
+    walletAccountIdx: ctx.walletAccountIdx,
+    authIdx: params.authIdx,
+    targetInstruction: {
+      programIdx: targetProgramIdx,
+      instructionData: targetInstructionData,
+    },
+    signatureR: signature.signatureR,
+    signatureS: signature.signatureS,
+    authenticatorData: signature.authenticatorData,
+    clientDataJSON: signature.clientDataJSON,
+  });
+
+  status("Sending transaction...");
+  const result = await params.executor({
+    thru: params.thru,
+    walletSigner: params.walletSigner,
+    instructionData: validateInstruction,
+    readWriteAddresses: ctx.readWriteAddresses,
+    readOnlyAddresses: ctx.readOnlyAddresses,
+    label: params.credentialId
+      ? "VALIDATE -> MULTICALL(ADD_AUTHORITY, REGISTER_CREDENTIAL)"
+      : "VALIDATE -> ADD_AUTHORITY",
+  });
+
+  return { ...result, newAuthorityIdx };
+}

package/src/auth/execute-tx.ts

@@ -1,4 +1,4 @@
-import { base64UrlToBytes, bytesToBase64, bytesToHex } from '@thru/passkey-manager';
+import { base64UrlToBytes, bytesToBase64, bytesToHex } from '@thru/programs/passkey-manager';
 import { signWithPasskey } from '../mobile/passkey';
 import { touchPasskeyLastUsedAt } from '../mobile/storage';
 

package/src/auth/index.ts

@@ -11,6 +11,17 @@ export type {
 
 export { executePasskeyTransaction } from './execute-tx';
 
+export { addDeviceToAccount } from './add-device';
+export type {
+  AddDeviceParams,
+  AddDeviceResult,
+  AnyThruClient,
+  PasskeyChallengeSigner,
+  TxExecutor,
+  TxExecutorParams,
+  TxExecutorResult,
+} from './add-device';
+
 export {
   createPasskeyAuthStore,
   getPasskeyAuthStore,

package/src/auth/use-passkey-auth.ts

@@ -1,4 +1,4 @@
-import { bytesToHex } from '@thru/passkey-manager';
+import { bytesToHex } from '@thru/programs/passkey-manager';
 import { create } from 'zustand';
 import { classifyPasskeyError } from '../mobile/errors';
 import {
@@ -152,8 +152,9 @@ export function createPasskeyAuthStore<TExtra = Record<string, never>>(
 
       try {
         const tempId = `user-${Date.now()}`;
+        const passkeyLabel = resolvedAlias.trim() || 'Thru Wallet';
         const { credentialId, publicKeyX, publicKeyY, rpId } =
-          await registerPasskey(resolvedAlias, tempId, {
+          await registerPasskey(passkeyLabel, tempId, {
             rpId: config.rpId,
             rpName: config.rpName,
           });
@@ -167,6 +168,7 @@ export function createPasskeyAuthStore<TExtra = Record<string, never>>(
           publicKeyX: pubkeyXHex,
           publicKeyY: pubkeyYHex,
           rpId,
+          label: passkeyLabel,
           createdAt: now,
           lastUsedAt: now,
         });

package/src/capabilities.ts

@@ -1,6 +1,7 @@
 import type { PasskeyClientCapabilities } from './types';
 
-const DEBUG = typeof process !== 'undefined' && process.env?.NEXT_PUBLIC_PASSKEY_DEBUG === '1';
+const globalProcess = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;
+const DEBUG = globalProcess?.env?.NEXT_PUBLIC_PASSKEY_DEBUG === '1';
 
 let cachedClientCapabilities: PasskeyClientCapabilities | null | undefined;
 let clientCapabilitiesPromise: Promise<PasskeyClientCapabilities | null> | null = null;

package/src/index.ts

@@ -12,6 +12,8 @@ export type {
   PasskeyClientCapabilities,
   PasskeyPopupContext,
   PasskeyPopupAccount,
+  PasskeyStoredSigningOptions,
+  PasskeyRegistrationOptions,
 } from './web';
 
 /**
@@ -19,6 +21,7 @@ export type {
  */
 export {
   registerPasskey,
+  createDistinctPasskeyLabel,
   signWithPasskey,
   signWithStoredPasskey,
   signWithDiscoverablePasskey,
@@ -45,6 +48,7 @@ export {
   bytesEqual,
   compareBytes,
   uniqueAccounts,
+  type DistinctPasskeyLabelOptions,
   type PasskeyPromptAction,
 } from './web';
 

package/src/label.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { createDistinctPasskeyLabel } from './label';
+
+describe('createDistinctPasskeyLabel', () => {
+  it('keeps a provided passkey label exactly without appending random hex', () => {
+    expect(
+      createDistinctPasskeyLabel('Jerry iPhone', {
+        suffixFactory: () => 'a1b2c3',
+      })
+    ).toBe('Jerry iPhone');
+  });
+
+  it('uses the default fallback exactly when the label is blank', () => {
+    expect(
+      createDistinctPasskeyLabel('   ', {
+        existingLabels: ['Thru Wallet passkey'],
+        suffixFactory: () => 'a1b2c3',
+      })
+    ).toBe('Thru Wallet passkey');
+  });
+});

package/src/label.ts

@@ -0,0 +1,14 @@
+const DEFAULT_LABEL = 'Thru Wallet passkey';
+
+export interface DistinctPasskeyLabelOptions {
+  existingLabels?: Iterable<string | null | undefined>;
+  maxAttempts?: number;
+  suffixFactory?: () => string;
+}
+
+export function createDistinctPasskeyLabel(
+  baseLabel: string,
+  _options: DistinctPasskeyLabelOptions = {}
+): string {
+  return baseLabel.trim() || DEFAULT_LABEL;
+}

package/src/mobile/index.ts

@@ -9,7 +9,7 @@ export type {
 
 export { classifyPasskeyError, type PasskeyErrorKind } from './errors';
 
-export { bytesToBase64 } from '@thru/passkey-manager';
+export { bytesToBase64 } from '@thru/programs/passkey-manager';
 
 export {
   storePasskeyMetadata,

package/src/mobile/passkey.ts

@@ -5,7 +5,7 @@ import {
   normalizeLowS,
   parseDerSignature,
   type PasskeySigningResult,
-} from '@thru/passkey-manager';
+} from '@thru/programs/passkey-manager';
 import type {
   DiscoverablePasskeyResult,
   PasskeyMobileConfig,

package/src/mobile/storage.ts

@@ -1,5 +1,5 @@
 import * as SecureStore from 'expo-secure-store';
-import type { PasskeyMetadata } from '@thru/passkey-manager';
+import type { PasskeyMetadata } from '@thru/programs/passkey-manager';
 
 const SECURE_STORE_OPTS = {
   keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,

package/src/mobile/types.ts

@@ -1,6 +1,6 @@
-import type { PasskeySigningResult, PasskeyMetadata } from '@thru/passkey-manager';
+import type { PasskeySigningResult, PasskeyMetadata } from '@thru/programs/passkey-manager';
 
-export type { PasskeySigningResult, PasskeyMetadata } from '@thru/passkey-manager';
+export type { PasskeySigningResult, PasskeyMetadata } from '@thru/programs/passkey-manager';
 
 export interface PasskeyMobileConfig {
   rpId?: string;

package/src/popup-service.ts

@@ -7,7 +7,7 @@ import type {
 import {
   PASSKEY_POPUP_RESPONSE_EVENT,
 } from './popup';
-import { bytesToBase64Url, base64UrlToBytes } from '@thru/passkey-manager';
+import { bytesToBase64Url, base64UrlToBytes } from '@thru/programs/passkey-manager';
 export function toPopupSigningResult(result: PasskeySigningResult): PasskeyPopupSigningResult {
   return {
     signatureBase64Url: bytesToBase64Url(result.signature),
@@ -15,6 +15,7 @@ export function toPopupSigningResult(result: PasskeySigningResult): PasskeyPopup
     clientDataJSONBase64Url: bytesToBase64Url(result.clientDataJSON),
     signatureRBase64Url: bytesToBase64Url(result.signatureR),
     signatureSBase64Url: bytesToBase64Url(result.signatureS),
+    authenticatorAttachment: result.authenticatorAttachment ?? null,
   };
 }
 

package/src/register.ts

@@ -1,5 +1,9 @@
-import type { PasskeyRegistrationResult, PasskeyPopupRegistrationResult } from './types';
-import { arrayBufferToBase64Url, bytesToHex } from '@thru/passkey-manager';
+import type {
+  PasskeyRegistrationOptions,
+  PasskeyRegistrationResult,
+  PasskeyPopupRegistrationResult,
+} from './types';
+import { arrayBufferToBase64Url, bytesToHex } from '@thru/programs/passkey-manager';
 import {
   isWebAuthnSupported,
   getPasskeyPromptMode,
@@ -15,7 +19,8 @@ import { requestPasskeyPopup, openPasskeyPopupWindow, closePopup } from './popup
 export async function registerPasskey(
   alias: string,
   userId: string,
-  rpId: string
+  rpId: string,
+  options: PasskeyRegistrationOptions = {}
 ): Promise<PasskeyRegistrationResult> {
   if (!isWebAuthnSupported()) {
     throw new Error('WebAuthn is not supported in this browser');
@@ -24,17 +29,20 @@ export async function registerPasskey(
   return runWithPromptMode(
     'create',
     () => registerPasskeyInline(alias, userId, rpId),
-    (preopenedPopup) => registerPasskeyViaPopup(alias, userId, rpId, preopenedPopup)
+    (preopenedPopup) => registerPasskeyViaPopup(alias, userId, rpId, preopenedPopup),
+    options
   );
 }
 
 async function runWithPromptMode<T>(
   action: PasskeyPromptAction,
   inlineFn: () => Promise<T>,
-  popupFn: (preopenedPopup?: Window | null) => Promise<T>
+  popupFn: (preopenedPopup?: Window | null) => Promise<T>,
+  options: PasskeyRegistrationOptions = {}
 ): Promise<T> {
-  const preopenedPopup = maybePreopenPopup(action, openPasskeyPopupWindow);
-  const promptMode = await getPasskeyPromptMode(action);
+  const allowPopupFallback = options.allowPopupFallback ?? true;
+  const preopenedPopup = allowPopupFallback ? maybePreopenPopup(action, openPasskeyPopupWindow) : null;
+  const promptMode = allowPopupFallback ? await getPasskeyPromptMode(action) : 'inline';
   if (promptMode === 'popup') {
     return popupFn(preopenedPopup);
   }
@@ -44,7 +52,7 @@ async function runWithPromptMode<T>(
   try {
     return await inlineFn();
   } catch (error) {
-    if (shouldFallbackToPopup(error)) {
+    if (allowPopupFallback && shouldFallbackToPopup(error)) {
       return popupFn();
     }
     throw error;
@@ -97,12 +105,19 @@ async function registerPasskeyInline(
 
   const response = credential.response as AuthenticatorAttestationResponse;
   const { x, y } = extractP256PublicKey(response);
+  const authenticatorAttachment =
+    (
+      credential as PublicKeyCredential & {
+        authenticatorAttachment?: AuthenticatorAttachment | null;
+      }
+    ).authenticatorAttachment ?? null;
 
   return {
     credentialId: arrayBufferToBase64Url(credential.rawId),
     publicKeyX: bytesToHex(x),
     publicKeyY: bytesToHex(y),
     rpId,
+    authenticatorAttachment,
   };
 }
 

package/src/server/challenge.ts

@@ -1,22 +1,33 @@
 import {
   bytesToBase64Url,
   createValidateChallenge,
+  decodeAddress,
   fetchWalletNonce,
-} from '@thru/passkey-manager';
-import type { AccountContext } from '@thru/passkey-manager';
+} from '@thru/programs/passkey-manager';
+import type { AccountContext } from '@thru/programs/passkey-manager';
 import type { PasskeyChallengeResult, ThruClient } from './types';
 
 export async function createPasskeyChallenge(opts: {
   client: ThruClient;
   walletAddress: string;
   accountCtx: AccountContext;
-  invokeIx: Uint8Array;
+  targetProgramAddress: string;
+  instructionData: Uint8Array;
+  authIdx?: number;
 }): Promise<PasskeyChallengeResult> {
   const nonce = await fetchWalletNonce(opts.client, opts.walletAddress);
+  const targetProgramIdx = opts.accountCtx.getAccountIndex(
+    decodeAddress(opts.targetProgramAddress)
+  );
   const challenge = await createValidateChallenge(
     nonce,
     opts.accountCtx.accountAddresses,
-    opts.invokeIx
+    opts.accountCtx.walletAccountIdx,
+    opts.authIdx ?? 0,
+    {
+      programIdx: targetProgramIdx,
+      instructionData: opts.instructionData,
+    }
   );
 
   return {

package/src/server/create-wallet.test.ts

@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { ThruClient } from './types';
 
-vi.mock('@thru/helpers', () => ({
+vi.mock('@thru/sdk/helpers', () => ({
   encodeAddress: (bytes: Uint8Array) => {
     const first = bytes[0];
     if (first === 11) return 'wallet-address';
@@ -10,7 +10,7 @@ vi.mock('@thru/helpers', () => ({
   },
 }));
 
-vi.mock('@thru/passkey-manager', () => ({
+vi.mock('@thru/programs/passkey-manager', () => ({
   PASSKEY_MANAGER_PROGRAM_ADDRESS: 'passkey-program',
   base64UrlToBytes: () => new Uint8Array([7]),
   buildAccountContext: (params: { readWriteAccounts: Uint8Array[] }) => ({