@thru/programs 0.2.22

package/src/passkey-manager/index.ts

@@ -0,0 +1,99 @@
+// Constants
+export {
+  PASSKEY_MANAGER_PROGRAM_ADDRESS,
+  INSTRUCTION_CREATE,
+  INSTRUCTION_VALIDATE,
+  INSTRUCTION_TRANSFER,
+  INSTRUCTION_INVOKE,
+  INSTRUCTION_ADD_AUTHORITY,
+  INSTRUCTION_REMOVE_AUTHORITY,
+  INSTRUCTION_REGISTER_CREDENTIAL,
+  AUTHORITY_TAG_PASSKEY,
+  AUTHORITY_TAG_PUBKEY,
+} from './constants';
+
+// Types
+export type {
+  Authority,
+  CreateInstructionParams,
+  TransferInstructionParams,
+  ValidateInstructionParams,
+  RegisterCredentialInstructionParams,
+  AccountContext,
+  WalletSigner,
+  TransactionExecutionSummary,
+  PasskeyMetadata,
+  PasskeyRegistrationResult,
+  PasskeySigningResult,
+  PasskeyDiscoverableSigningResult,
+} from './types';
+
+// Instructions
+export { encodeCreateInstruction } from './instructions/create';
+export { encodeValidateInstruction } from './instructions/validate';
+export { encodeTransferInstruction } from './instructions/transfer';
+export { encodeInvokeInstruction } from './instructions/invoke';
+export { encodeAddAuthorityInstruction } from './instructions/add-authority';
+export { encodeRemoveAuthorityInstruction } from './instructions/remove-authority';
+export { encodeRegisterCredentialInstruction } from './instructions/register-credential';
+export { concatenateInstructions } from './instructions/shared';
+
+// Challenge
+export { createValidateChallenge } from './challenge';
+
+// Seeds & derivation
+export { createWalletSeed, deriveWalletAddress, createCredentialLookupSeed, deriveCredentialLookupAddress } from './seeds';
+
+// Account context building
+export { buildAccountContext, buildPasskeyReadWriteAccounts, FEE_PAYER_ADDRESS } from './context';
+export { decodeAddress, encodeAddress } from '@thru/sdk/helpers';
+
+// Account parsing
+export {
+  parseWalletNonce,
+  fetchWalletNonce,
+  parseCredentialLookupWallet,
+  parseWalletAuthorities,
+  formatAuthorityPubkey,
+} from './accounts';
+export type { ParsedAuthority, WalletAuthorities } from './accounts';
+
+// Authority matching
+export {
+  findPasskeyAuthorityIndexForIdentity,
+  findPasskeyAuthorityIndexInWalletData,
+  isPasskeyAuthorityCheckable,
+  preparePasskeyAuthorityTargets,
+  resolvePasskeyAuthorityIndex,
+} from './authority';
+export type {
+  CheckablePasskeyAuthorityIdentity,
+  PasskeyAuthorityIdentity,
+  PasskeyAuthorityTarget,
+  PreparePasskeyAuthorityTargetsOptions,
+} from './authority';
+
+// Crypto (platform-agnostic P-256 / DER utilities)
+export {
+  parseDerSignature,
+  normalizeLowS,
+  normalizeSignatureComponent,
+  P256_N,
+  P256_HALF_N,
+  bytesToBigIntBE,
+  bigIntToBytesBE,
+} from './crypto';
+
+// Encoding (platform-agnostic byte/base64/hex utilities)
+export {
+  arrayBufferToBase64Url,
+  base64UrlToArrayBuffer,
+  bytesToBase64,
+  bytesToBase64Url,
+  base64UrlToBytes,
+  bytesToHex,
+  hexToBytes,
+  bytesEqual,
+  compareBytes,
+  uniqueAccounts,
+} from './encoding';

package/src/passkey-manager/instructions/add-authority.ts

@@ -0,0 +1,21 @@
+import type { Authority } from '../types';
+import {
+  AddAuthorityArgsBuilder,
+  PasskeyInstructionBuilder,
+} from '../abi/thru/program/passkey_manager/types';
+import { buildAuthority } from './create';
+
+export function encodeAddAuthorityInstruction(params: { authority: Authority }): Uint8Array {
+  const authorityBytes = buildAuthority(params.authority);
+
+  const argsPayload = new AddAuthorityArgsBuilder()
+    .set_authority(authorityBytes)
+    .build();
+
+  return new PasskeyInstructionBuilder()
+    .payload()
+    .select('add_authority')
+    .writePayload(argsPayload)
+    .finish()
+    .build();
+}

package/src/passkey-manager/instructions/create.ts

@@ -0,0 +1,54 @@
+import type { Authority, CreateInstructionParams } from '../types';
+import {
+  AuthorityBuilder,
+  CreateArgsBuilder,
+  PasskeyInstructionBuilder,
+} from '../abi/thru/program/passkey_manager/types';
+
+function buildAuthority(authority: Authority): Uint8Array {
+  const data = new Array<number>(64).fill(0);
+
+  if (authority.tag === 1) {
+    if (authority.pubkeyX.length !== 32) throw new Error('pubkeyX must be 32 bytes');
+    if (authority.pubkeyY.length !== 32) throw new Error('pubkeyY must be 32 bytes');
+    for (let i = 0; i < 32; i++) data[i] = authority.pubkeyX[i];
+    for (let i = 0; i < 32; i++) data[32 + i] = authority.pubkeyY[i];
+  } else if (authority.tag === 2) {
+    if (authority.pubkey.length !== 32) throw new Error('pubkey must be 32 bytes');
+    for (let i = 0; i < 32; i++) data[i] = authority.pubkey[i];
+  } else {
+    throw new Error('Invalid authority tag');
+  }
+
+  return new AuthorityBuilder()
+    .set_tag(authority.tag)
+    .set_data(data)
+    .build();
+}
+
+export { buildAuthority };
+
+export function encodeCreateInstruction(params: CreateInstructionParams): Uint8Array {
+  const { walletAccountIdx, authority, seed, stateProof } = params;
+
+  if (seed.length !== 32) throw new Error('seed must be 32 bytes');
+  if (walletAccountIdx < 0 || walletAccountIdx > 0xffff) {
+    throw new Error('walletAccountIdx must be 0-65535');
+  }
+
+  const authorityBytes = buildAuthority(authority);
+
+  const argsPayload = new CreateArgsBuilder()
+    .set_wallet_account_idx(walletAccountIdx)
+    .set_authority(authorityBytes)
+    .set_seed(seed)
+    .set_state_proof(stateProof)
+    .build();
+
+  return new PasskeyInstructionBuilder()
+    .payload()
+    .select('create')
+    .writePayload(argsPayload)
+    .finish()
+    .build();
+}

package/src/passkey-manager/instructions/invoke.ts

@@ -0,0 +1,25 @@
+import {
+  InvokeArgsBuilder,
+  PasskeyInstructionBuilder,
+} from '../abi/thru/program/passkey_manager/types';
+
+export function encodeInvokeInstruction(
+  programPubkey: Uint8Array,
+  instruction: Uint8Array
+): Uint8Array {
+  if (programPubkey.length !== 32) {
+    throw new Error('Program pubkey must be 32 bytes');
+  }
+
+  const argsPayload = new InvokeArgsBuilder()
+    .set_program_pubkey(programPubkey)
+    .instr().write(instruction).finish()
+    .build();
+
+  return new PasskeyInstructionBuilder()
+    .payload()
+    .select('invoke')
+    .writePayload(argsPayload)
+    .finish()
+    .build();
+}

package/src/passkey-manager/instructions/register-credential.ts

@@ -0,0 +1,33 @@
+import type { RegisterCredentialInstructionParams } from '../types';
+import {
+  RegisterCredentialArgsBuilder,
+  PasskeyInstructionBuilder,
+} from '../abi/thru/program/passkey_manager/types';
+
+export function encodeRegisterCredentialInstruction(
+  params: RegisterCredentialInstructionParams
+): Uint8Array {
+  const { walletAccountIdx, lookupAccountIdx, seed, stateProof } = params;
+
+  if (seed.length !== 32) throw new Error('seed must be 32 bytes');
+  if (walletAccountIdx < 0 || walletAccountIdx > 0xffff) {
+    throw new Error('walletAccountIdx must be 0-65535');
+  }
+  if (lookupAccountIdx < 0 || lookupAccountIdx > 0xffff) {
+    throw new Error('lookupAccountIdx must be 0-65535');
+  }
+
+  const argsPayload = new RegisterCredentialArgsBuilder()
+    .set_wallet_account_idx(walletAccountIdx)
+    .set_lookup_account_idx(lookupAccountIdx)
+    .set_seed(seed)
+    .set_state_proof(stateProof)
+    .build();
+
+  return new PasskeyInstructionBuilder()
+    .payload()
+    .select('register_credential')
+    .writePayload(argsPayload)
+    .finish()
+    .build();
+}

package/src/passkey-manager/instructions/remove-authority.ts

@@ -0,0 +1,20 @@
+import {
+  RemoveAuthorityArgsBuilder,
+  PasskeyInstructionBuilder,
+} from '../abi/thru/program/passkey_manager/types';
+
+export function encodeRemoveAuthorityInstruction(params: { authIdx: number }): Uint8Array {
+  const { authIdx } = params;
+  if (authIdx < 0 || authIdx > 0xff) throw new Error('authIdx must be 0-255');
+
+  const argsPayload = new RemoveAuthorityArgsBuilder()
+    .set_auth_idx(authIdx)
+    .build();
+
+  return new PasskeyInstructionBuilder()
+    .payload()
+    .select('remove_authority')
+    .writePayload(argsPayload)
+    .finish()
+    .build();
+}

package/src/passkey-manager/instructions/shared.ts

@@ -0,0 +1,12 @@
+export function concatenateInstructions(instructions: Uint8Array[]): Uint8Array {
+  const totalLength = instructions.reduce((sum, instr) => sum + instr.length, 0);
+  const result = new Uint8Array(totalLength);
+
+  let offset = 0;
+  for (const instr of instructions) {
+    result.set(instr, offset);
+    offset += instr.length;
+  }
+
+  return result;
+}

package/src/passkey-manager/instructions/transfer.ts

@@ -0,0 +1,30 @@
+import type { TransferInstructionParams } from '../types';
+import {
+  TransferArgsBuilder,
+  PasskeyInstructionBuilder,
+} from '../abi/thru/program/passkey_manager/types';
+
+export function encodeTransferInstruction(params: TransferInstructionParams): Uint8Array {
+  const { walletAccountIdx, toAccountIdx, amount } = params;
+
+  if (walletAccountIdx < 0 || walletAccountIdx > 0xffff) {
+    throw new Error('walletAccountIdx must be 0-65535');
+  }
+  if (toAccountIdx < 0 || toAccountIdx > 0xffff) {
+    throw new Error('toAccountIdx must be 0-65535');
+  }
+  if (amount < 0n) throw new Error('amount must be non-negative');
+
+  const argsPayload = new TransferArgsBuilder()
+    .set_wallet_account_idx(walletAccountIdx)
+    .set_to_account_idx(toAccountIdx)
+    .set_amount(amount as unknown as number)
+    .build();
+
+  return new PasskeyInstructionBuilder()
+    .payload()
+    .select('transfer')
+    .writePayload(argsPayload)
+    .finish()
+    .build();
+}

package/src/passkey-manager/instructions/validate.ts

@@ -0,0 +1,33 @@
+import type { ValidateInstructionParams } from '../types';
+import {
+  ValidateArgsBuilder,
+  PasskeyInstructionBuilder,
+} from '../abi/thru/program/passkey_manager/types';
+
+export function encodeValidateInstruction(params: ValidateInstructionParams): Uint8Array {
+  const { walletAccountIdx, authIdx, signatureR, signatureS, authenticatorData, clientDataJSON } =
+    params;
+
+  if (walletAccountIdx < 0 || walletAccountIdx > 0xffff) {
+    throw new Error('walletAccountIdx must be 0-65535');
+  }
+  if (authIdx < 0 || authIdx > 0xff) throw new Error('authIdx must be 0-255');
+  if (signatureR.length !== 32) throw new Error('signatureR must be 32 bytes');
+  if (signatureS.length !== 32) throw new Error('signatureS must be 32 bytes');
+
+  const argsPayload = new ValidateArgsBuilder()
+    .set_wallet_account_idx(walletAccountIdx)
+    .set_auth_idx(authIdx)
+    .set_signature_r(signatureR)
+    .set_signature_s(signatureS)
+    .authenticator_data().write(authenticatorData).finish()
+    .client_data().write(clientDataJSON).finish()
+    .build();
+
+  return new PasskeyInstructionBuilder()
+    .payload()
+    .select('validate')
+    .writePayload(argsPayload)
+    .finish()
+    .build();
+}

package/src/passkey-manager/seeds.ts

@@ -0,0 +1,73 @@
+import { decodeAddress } from '@thru/sdk/helpers';
+
+/**
+ * Create a 32-byte seed from wallet name and passkey coordinates.
+ * SHA-256(walletName || pubkey_x || pubkey_y)
+ */
+export async function createWalletSeed(
+  walletName: string,
+  pubkeyX: Uint8Array,
+  pubkeyY: Uint8Array,
+): Promise<Uint8Array> {
+  if (pubkeyX.length !== 32) throw new Error("pubkeyX must be 32 bytes");
+  if (pubkeyY.length !== 32) throw new Error("pubkeyY must be 32 bytes");
+
+  const nameBytes = new TextEncoder().encode(walletName);
+  const data = new Uint8Array(nameBytes.length + 32 + 32);
+  data.set(nameBytes, 0);
+  data.set(pubkeyX, nameBytes.length);
+  data.set(pubkeyY, nameBytes.length + 32);
+
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return new Uint8Array(hashBuffer);
+}
+
+/**
+ * Derive wallet account address from seed using proper PDA derivation.
+ * SHA256(program_address || is_ephemeral || seed)
+ */
+export async function deriveWalletAddress(
+  seed: Uint8Array,
+  programAddress: string,
+): Promise<Uint8Array> {
+  if (seed.length !== 32) {
+    throw new Error("seed must be 32 bytes");
+  }
+
+  const programBytes = decodeAddress(programAddress);
+  const isEphemeral = new Uint8Array([0]);
+
+  const preimage = new Uint8Array(32 + 1 + 32);
+  preimage.set(programBytes, 0);
+  preimage.set(isEphemeral, 32);
+  preimage.set(seed, 33);
+
+  const hashBuffer = await crypto.subtle.digest("SHA-256", preimage);
+  return new Uint8Array(hashBuffer);
+}
+
+/**
+ * Create a 32-byte seed for a credential lookup PDA.
+ * SHA-256(credentialId)
+ */
+export async function createCredentialLookupSeed(
+  credentialId: Uint8Array,
+): Promise<Uint8Array> {
+  const data = new Uint8Array(credentialId.length);
+  data.set(credentialId);
+
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return new Uint8Array(hashBuffer);
+}
+
+/**
+ * Derive credential lookup PDA address from a credential ID.
+ * Convenience wrapper: deriveWalletAddress(SHA-256(credentialId), programAddress)
+ */
+export async function deriveCredentialLookupAddress(
+  credentialId: Uint8Array,
+  programAddress: string,
+): Promise<Uint8Array> {
+  const seed = await createCredentialLookupSeed(credentialId);
+  return deriveWalletAddress(seed, programAddress);
+}

package/src/passkey-manager/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Result of passkey registration (credential creation).
+ */
+export interface PasskeyRegistrationResult {
+  credentialId: string; // base64url-encoded
+  publicKeyX: string; // hex-encoded (32 bytes)
+  publicKeyY: string; // hex-encoded (32 bytes)
+  rpId: string;
+  authenticatorAttachment?: 'platform' | 'cross-platform' | null;
+}
+
+/**
+ * Result of passkey signing (assertion).
+ */
+export interface PasskeySigningResult {
+  signature: Uint8Array; // Raw P-256 signature (r || s, 64 bytes)
+  authenticatorData: Uint8Array;
+  clientDataJSON: Uint8Array;
+  signatureR: Uint8Array; // 32 bytes
+  signatureS: Uint8Array; // 32 bytes
+  /** WebAuthn authenticator attachment, if surfaced by the browser:
+   *  - 'platform': built-in / passkey on this device
+   *  - 'cross-platform': e.g. signed in via QR using another device
+   *  Used by the wallet to decide whether to offer "add this device". */
+  authenticatorAttachment?: 'platform' | 'cross-platform' | null;
+}
+
+/**
+ * Signing result with discoverable credential info.
+ */
+export interface PasskeyDiscoverableSigningResult extends PasskeySigningResult {
+  credentialId: string; // base64url-encoded
+  rpId: string;
+}
+
+/**
+ * Passkey metadata stored locally (the actual private key lives in the device's secure enclave).
+ */
+export interface PasskeyMetadata {
+  credentialId: string;
+  publicKeyX: string;
+  publicKeyY: string;
+  rpId: string;
+  /** On-chain passkey authority index for this wallet account.
+   *  Omitted for the primary authority, which defaults to index 0. */
+  authIdx?: number;
+  label?: string;
+  deviceName?: string;
+  devicePlatform?: string;
+  browserName?: string;
+  authenticatorAttachment?: 'platform' | 'cross-platform' | null;
+  createdAt: string;
+  lastUsedAt: string;
+}
+
+export type Authority =
+  | {
+      tag: 1; // passkey
+      pubkeyX: Uint8Array; // 32 bytes
+      pubkeyY: Uint8Array; // 32 bytes
+    }
+  | {
+      tag: 2; // pubkey
+      pubkey: Uint8Array; // 32 bytes
+    };
+
+export interface CreateInstructionParams {
+  walletAccountIdx: number;
+  authority: Authority;
+  seed: Uint8Array;
+  stateProof: Uint8Array;
+}
+
+export interface TransferInstructionParams {
+  walletAccountIdx: number;
+  toAccountIdx: number;
+  amount: bigint;
+}
+
+export interface ValidateInstructionParams {
+  walletAccountIdx: number;
+  authIdx: number;
+  signatureR: Uint8Array;
+  signatureS: Uint8Array;
+  authenticatorData: Uint8Array;
+  clientDataJSON: Uint8Array;
+}
+
+export interface AccountContext {
+  readWriteAddresses: string[];
+  readOnlyAddresses: string[];
+  accountAddresses: string[];
+  walletAccountIdx: number;
+  getAccountIndex: (pubkey: Uint8Array) => number;
+}
+
+export interface RegisterCredentialInstructionParams {
+  walletAccountIdx: number;
+  lookupAccountIdx: number;
+  seed: Uint8Array; // SHA-256(credentialId), 32 bytes
+  stateProof: Uint8Array;
+}
+
+export type WalletSigner = {
+  signTransaction: (payloadBase64: string) => Promise<string>;
+};
+
+export type TransactionExecutionSummary = {
+  executionResult?: bigint | number | null;
+  userErrorCode?: bigint | number | null;
+  vmError?: number | string | bigint | null;
+};