@thru/programs 0.2.22

package/src/passkey-manager/accounts.ts

@@ -0,0 +1,142 @@
+import { encodeAddress } from '@thru/sdk/helpers';
+import {
+  CredentialLookup,
+  WalletAccount,
+} from './abi/thru/program/passkey_manager/types';
+
+/**
+ * Parse wallet account data to extract nonce.
+ */
+export function parseWalletNonce(data: Uint8Array): bigint {
+  const account = WalletAccount.from_array(data);
+  if (!account) return 0n;
+  return account.get_nonce();
+}
+
+/**
+ * Fetch wallet nonce from the chain.
+ * Takes an SDK-like object with accounts.get() method.
+ */
+export async function fetchWalletNonce(
+  sdk: { accounts: { get: (address: string) => Promise<{ data?: { data?: Uint8Array } }> } },
+  walletAddress: string
+): Promise<bigint> {
+  const account = await sdk.accounts.get(walletAddress);
+  const data = account.data?.data;
+  if (!data) return 0n;
+  const parsed = WalletAccount.from_array(data);
+  if (!parsed) return 0n;
+  return parsed.get_nonce();
+}
+
+/* ------------------------------------------------------------------ */
+/* Authority list parsing                                              */
+/* ------------------------------------------------------------------ */
+
+export type ParsedAuthority =
+  | {
+      idx: number;
+      kind: 'passkey';
+      x: Uint8Array;
+      y: Uint8Array;
+    }
+  | {
+      idx: number;
+      kind: 'pubkey';
+      pubkey: Uint8Array;
+    }
+  | {
+      idx: number;
+      kind: 'unknown';
+      tag: number;
+      data: Uint8Array;
+    };
+
+export interface WalletAuthorities {
+  nonce: bigint;
+  authorities: ParsedAuthority[];
+}
+
+const AUTHORITY_HEADER_BYTES = 9; /* num_auth (u8) + nonce (u64 LE) */
+const AUTHORITY_ENTRY_BYTES = 65; /* tag (u8) + data (64) */
+
+function readU64LE(data: Uint8Array, offset: number): bigint {
+  if (offset + 8 > data.length) {
+    throw new Error('Out of bounds');
+  }
+  let value = 0n;
+  for (let i = 0; i < 8; i++) {
+    value |= BigInt(data[offset + i]) << (8n * BigInt(i));
+  }
+  return value;
+}
+
+/**
+ * Parse the on-chain WalletAccount data buffer into its nonce and full
+ * authority list. The on-chain layout is:
+ *
+ *   num_auth: u8
+ *   nonce:    u64 LE
+ *   authorities[num_auth + 1]: { tag: u8, data: [u8; 64] }
+ *
+ * (`num_auth + 1` because num_auth stores the count minus one.)
+ */
+export function parseWalletAuthorities(data: Uint8Array): WalletAuthorities {
+  if (data.length < AUTHORITY_HEADER_BYTES) {
+    throw new Error('Wallet data too small');
+  }
+
+  const numAuth = data[0];
+  const nonce = readU64LE(data, 1);
+
+  const count = numAuth + 1;
+  const required =
+    AUTHORITY_HEADER_BYTES + count * AUTHORITY_ENTRY_BYTES;
+  if (data.length < required) {
+    throw new Error('Wallet data truncated');
+  }
+
+  const authorities: ParsedAuthority[] = [];
+  for (let idx = 0; idx < count; idx++) {
+    const offset = AUTHORITY_HEADER_BYTES + idx * AUTHORITY_ENTRY_BYTES;
+    const tag = data[offset];
+    const payload = data.slice(offset + 1, offset + AUTHORITY_ENTRY_BYTES);
+
+    if (tag === 1) {
+      authorities.push({
+        idx,
+        kind: 'passkey',
+        x: payload.slice(0, 32),
+        y: payload.slice(32, 64),
+      });
+      continue;
+    }
+
+    if (tag === 2) {
+      authorities.push({ idx, kind: 'pubkey', pubkey: payload.slice(0, 32) });
+      continue;
+    }
+
+    authorities.push({ idx, kind: 'unknown', tag, data: payload });
+  }
+
+  return { nonce, authorities };
+}
+
+/**
+ * Encode a 32-byte pubkey to its base58 wallet address representation.
+ */
+export function formatAuthorityPubkey(pubkey: Uint8Array): string {
+  return encodeAddress(pubkey);
+}
+
+/**
+ * Parse a CredentialLookup account and return the wallet account pubkey
+ * stored inside it.
+ */
+export function parseCredentialLookupWallet(data: Uint8Array): Uint8Array | null {
+  const lookup = CredentialLookup.from_array(data);
+  if (!lookup) return null;
+  const wallet = lookup.get_wallet() as unknown as { buffer?: Uint8Array };
+  return wallet.buffer ? wallet.buffer.slice() : null;
+}

package/src/passkey-manager/authority.ts

@@ -0,0 +1,148 @@
+import { parseWalletAuthorities, type ParsedAuthority } from './accounts';
+import { bytesToHex } from './encoding';
+
+const DEFAULT_AUTHORITY_TARGET_CONCURRENCY = 8;
+
+export interface PasskeyAuthorityIdentity {
+  publicKeyX?: string | null;
+  publicKeyY?: string | null;
+}
+
+export interface CheckablePasskeyAuthorityIdentity {
+  publicKeyX: string;
+  publicKeyY: string;
+}
+
+interface AccountLike {
+  data?: {
+    data?: Uint8Array;
+  };
+}
+
+interface ThruAccountClient {
+  accounts: {
+    get(address: string): Promise<AccountLike>;
+  };
+}
+
+export interface PasskeyAuthorityTarget<T> {
+  account: T;
+  walletAddress: string;
+  authIdx: number;
+  authorities: ParsedAuthority[];
+}
+
+export interface PreparePasskeyAuthorityTargetsOptions<T> {
+  accounts: T[];
+  passkey?: PasskeyAuthorityIdentity | null;
+  thru: ThruAccountClient;
+  getWalletAddress: (account: T) => string;
+  concurrency?: number;
+}
+
+function getAccountData(account: AccountLike | null | undefined): Uint8Array | null {
+  return account?.data?.data ?? null;
+}
+
+export function isPasskeyAuthorityCheckable(
+  passkey: PasskeyAuthorityIdentity | null | undefined
+): passkey is CheckablePasskeyAuthorityIdentity {
+  return Boolean(passkey?.publicKeyX && passkey.publicKeyY);
+}
+
+export function findPasskeyAuthorityIndexForIdentity(
+  authorities: ParsedAuthority[],
+  passkey: PasskeyAuthorityIdentity | null | undefined
+): number | null {
+  if (!isPasskeyAuthorityCheckable(passkey)) return null;
+
+  const expectedX = passkey.publicKeyX.toLowerCase();
+  const expectedY = passkey.publicKeyY.toLowerCase();
+  const authority = authorities.find(
+    (item) =>
+      item.kind === 'passkey' &&
+      bytesToHex(item.x).toLowerCase() === expectedX &&
+      bytesToHex(item.y).toLowerCase() === expectedY
+  );
+  return authority?.idx ?? null;
+}
+
+export function findPasskeyAuthorityIndexInWalletData(
+  walletData: Uint8Array,
+  passkey: PasskeyAuthorityIdentity | null | undefined
+): { authIdx: number; authorities: ParsedAuthority[] } | null {
+  const parsed = parseWalletAuthorities(walletData);
+  const authIdx = findPasskeyAuthorityIndexForIdentity(parsed.authorities, passkey);
+  return authIdx === null ? null : { authIdx, authorities: parsed.authorities };
+}
+
+export async function resolvePasskeyAuthorityIndex(params: {
+  thru: ThruAccountClient;
+  walletAddress: string;
+  passkey?: PasskeyAuthorityIdentity | null;
+}): Promise<number | null> {
+  const walletAccount = await params.thru.accounts.get(params.walletAddress);
+  const walletData = getAccountData(walletAccount);
+  if (!walletData) return null;
+
+  return findPasskeyAuthorityIndexInWalletData(walletData, params.passkey)?.authIdx ?? null;
+}
+
+async function mapWithConcurrency<T, R>(
+  items: T[],
+  concurrency: number,
+  mapper: (item: T) => Promise<R>
+): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let nextIndex = 0;
+  const workerCount = Math.max(1, Math.min(Math.floor(concurrency), items.length));
+
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (nextIndex < items.length) {
+        const currentIndex = nextIndex;
+        nextIndex += 1;
+        results[currentIndex] = await mapper(items[currentIndex]);
+      }
+    })
+  );
+
+  return results;
+}
+
+export async function preparePasskeyAuthorityTargets<T>({
+  accounts,
+  passkey,
+  thru,
+  getWalletAddress,
+  concurrency = DEFAULT_AUTHORITY_TARGET_CONCURRENCY,
+}: PreparePasskeyAuthorityTargetsOptions<T>): Promise<PasskeyAuthorityTarget<T>[]> {
+  if (!isPasskeyAuthorityCheckable(passkey) || accounts.length === 0) {
+    return [];
+  }
+
+  const targets = await mapWithConcurrency(accounts, concurrency, async (account) => {
+    const walletAddress = getWalletAddress(account);
+    try {
+      const walletAccount = await thru.accounts.get(walletAddress);
+      const walletData = getAccountData(walletAccount);
+      if (!walletData) return null;
+
+      const target = findPasskeyAuthorityIndexInWalletData(walletData, passkey);
+      if (!target) return null;
+
+      return {
+        account,
+        walletAddress,
+        authIdx: target.authIdx,
+        authorities: target.authorities,
+      };
+    } catch {
+      return null;
+    }
+  });
+
+  return targets.filter(
+    (target): target is PasskeyAuthorityTarget<T> => target !== null
+  );
+}

package/src/passkey-manager/challenge.ts

@@ -0,0 +1,39 @@
+/**
+ * Create challenge for VALIDATE instruction.
+ * SHA256(nonce || account_0 || account_1 || ... || trailing_instruction_bytes)
+ */
+export async function createValidateChallenge(
+  nonce: bigint,
+  accountAddresses: string[],
+  trailingInstructionData: Uint8Array
+): Promise<Uint8Array> {
+  const encoder = new TextEncoder();
+  const accountBytes = accountAddresses.map((address) => {
+    return encoder.encode(address);
+  });
+
+  const totalSize =
+    accountBytes.reduce((sum, bytes) => sum + bytes.length, 8) +
+    trailingInstructionData.length;
+  const challengeData = new Uint8Array(totalSize);
+
+  let offset = 0;
+
+  // Write nonce as little-endian u64
+  let v = nonce;
+  for (let i = 0; i < 8; i++) {
+    challengeData[offset + i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  offset += 8;
+
+  for (const bytes of accountBytes) {
+    challengeData.set(bytes, offset);
+    offset += bytes.length;
+  }
+
+  challengeData.set(trailingInstructionData, offset);
+
+  const hashBuffer = await crypto.subtle.digest('SHA-256', challengeData);
+  return new Uint8Array(hashBuffer);
+}

package/src/passkey-manager/constants.ts

@@ -0,0 +1,15 @@
+export const PASSKEY_MANAGER_PROGRAM_ADDRESS =
+  'taUDdQyFxvM5i0HFRkEK3W45kWLyblAHSnMg4zplgUnz6Z';
+
+// Instruction discriminants
+export const INSTRUCTION_CREATE = 0x00;
+export const INSTRUCTION_VALIDATE = 0x01;
+export const INSTRUCTION_TRANSFER = 0x02;
+export const INSTRUCTION_INVOKE = 0x03;
+export const INSTRUCTION_ADD_AUTHORITY = 0x04;
+export const INSTRUCTION_REMOVE_AUTHORITY = 0x05;
+export const INSTRUCTION_REGISTER_CREDENTIAL = 0x06;
+
+// Authority tags
+export const AUTHORITY_TAG_PASSKEY = 1;
+export const AUTHORITY_TAG_PUBKEY = 2;

package/src/passkey-manager/context.ts

@@ -0,0 +1,112 @@
+import { encodeAddress, decodeAddress } from '@thru/sdk/helpers';
+import { bytesEqual, compareBytes, uniqueAccounts } from './encoding';
+import { PASSKEY_MANAGER_PROGRAM_ADDRESS } from './constants';
+import type { AccountContext } from './types';
+
+/**
+ * Default fee payer address (manager profile).
+ */
+export const FEE_PAYER_ADDRESS =
+  'taVcZv3wB2m-euBpMHm2rF9fQRY_fO_g7WdOjs70CxDh_S';
+
+/**
+ * Build account context for passkey manager transactions.
+ * Handles account deduplication, sorting, and index lookup.
+ */
+export function buildAccountContext(params: {
+  walletAddress: string;
+  readWriteAccounts: Uint8Array[];
+  readOnlyAccounts: Uint8Array[];
+  feePayerAddress?: string;
+  programAddress?: string;
+}): AccountContext {
+  const feePayerBytes = decodeAddress(params.feePayerAddress ?? FEE_PAYER_ADDRESS);
+  const programBytes = decodeAddress(params.programAddress ?? PASSKEY_MANAGER_PROGRAM_ADDRESS);
+  const walletBytes = decodeAddress(params.walletAddress);
+
+  const readWriteBytes = uniqueAccounts([walletBytes, ...params.readWriteAccounts])
+    .filter(
+      (addr) => !bytesEqual(addr, feePayerBytes) && !bytesEqual(addr, programBytes)
+    )
+    .sort(compareBytes);
+
+  const readOnlyBytes = uniqueAccounts(params.readOnlyAccounts)
+    .filter(
+      (addr) =>
+        !bytesEqual(addr, feePayerBytes) &&
+        !bytesEqual(addr, programBytes) &&
+        !readWriteBytes.some((candidate) => bytesEqual(candidate, addr))
+    )
+    .sort(compareBytes);
+
+  const readWriteAddresses = readWriteBytes.map(encodeAddress);
+  const readOnlyAddresses = readOnlyBytes.map(encodeAddress);
+
+  const accountAddresses = [
+    encodeAddress(feePayerBytes),
+    encodeAddress(programBytes),
+    ...readWriteAddresses,
+    ...readOnlyAddresses,
+  ];
+
+  const findIndex = (target: Uint8Array): number => {
+    if (bytesEqual(target, feePayerBytes)) return 0;
+    if (bytesEqual(target, programBytes)) return 1;
+
+    const rwIndex = readWriteBytes.findIndex((candidate) => bytesEqual(candidate, target));
+    if (rwIndex >= 0) return rwIndex + 2;
+
+    const roIndex = readOnlyBytes.findIndex((candidate) => bytesEqual(candidate, target));
+    if (roIndex >= 0) return roIndex + 2 + readWriteBytes.length;
+
+    return -1;
+  };
+
+  const walletAccountIdx = findIndex(walletBytes);
+  if (walletAccountIdx < 2) {
+    throw new Error('Wallet account must be a non-fee-payer account');
+  }
+
+  return {
+    readWriteAddresses,
+    readOnlyAddresses,
+    accountAddresses,
+    walletAccountIdx,
+    getAccountIndex: (pubkey: Uint8Array) => {
+      const idx = findIndex(pubkey);
+      if (idx < 0) {
+        throw new Error('Account not found in transaction accounts');
+      }
+      return idx;
+    },
+  };
+}
+
+/**
+ * Build read-write accounts list for passkey manager transactions (simpler wallet-only version).
+ */
+export function buildPasskeyReadWriteAccounts(
+  userAccounts: Uint8Array[],
+  feePayerPublicKey: Uint8Array,
+  programAddress: Uint8Array
+): {
+  readWriteAddresses: string[];
+  findAccountIndex: (target: Uint8Array) => number;
+} {
+  const sortedUserAccounts = uniqueAccounts(userAccounts).sort(compareBytes);
+  const filteredUserAccounts = sortedUserAccounts.filter(
+    (addr) => !bytesEqual(addr, feePayerPublicKey) && !bytesEqual(addr, programAddress)
+  );
+  const readWriteAddresses = filteredUserAccounts.map((addr) => encodeAddress(addr));
+
+  const findAccountIndex = (target: Uint8Array): number => {
+    if (bytesEqual(target, feePayerPublicKey)) return 0;
+    if (bytesEqual(target, programAddress)) return 1;
+    for (let i = 0; i < filteredUserAccounts.length; i++) {
+      if (bytesEqual(filteredUserAccounts[i], target)) return i + 2;
+    }
+    return -1;
+  };
+
+  return { readWriteAddresses, findAccountIndex };
+}

package/src/passkey-manager/crypto.ts

@@ -0,0 +1,80 @@
+/**
+ * P-256 curve order and half-order for low-S normalization.
+ */
+export const P256_N =
+  0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n;
+export const P256_HALF_N = P256_N >> 1n;
+
+/**
+ * Parse DER-encoded ECDSA signature to get r and s components.
+ */
+export function parseDerSignature(der: Uint8Array): { r: Uint8Array; s: Uint8Array } {
+  if (der[0] !== 0x30) throw new Error('Invalid DER signature');
+
+  let offset = 2;
+
+  if (der[offset] !== 0x02) throw new Error('Invalid DER signature');
+  offset++;
+
+  const rLen = der[offset++];
+  let r: Uint8Array = der.slice(offset, offset + rLen);
+  offset += rLen;
+
+  if (der[offset] !== 0x02) throw new Error('Invalid DER signature');
+  offset++;
+
+  const sLen = der[offset++];
+  let s: Uint8Array = der.slice(offset, offset + sLen);
+
+  r = normalizeSignatureComponent(r);
+  s = normalizeSignatureComponent(s);
+
+  return { r, s };
+}
+
+/**
+ * Ensure S is in the lower half of the curve order (BIP-62 / SEC1 compliance).
+ */
+export function normalizeLowS(s: Uint8Array): Uint8Array {
+  const sValue = bytesToBigIntBE(s);
+  if (sValue > P256_HALF_N) {
+    return bigIntToBytesBE(P256_N - sValue, 32);
+  }
+  return s;
+}
+
+/**
+ * Normalize signature component to exactly 32 bytes.
+ */
+export function normalizeSignatureComponent(component: Uint8Array): Uint8Array {
+  if (component.length === 32) return component;
+
+  if (component.length > 32) {
+    if (component[0] === 0x00 && component.length === 33) {
+      return component.slice(1);
+    }
+    throw new Error('Invalid signature component length');
+  }
+
+  const normalized = new Uint8Array(32);
+  normalized.set(component, 32 - component.length);
+  return normalized;
+}
+
+export function bytesToBigIntBE(bytes: Uint8Array): bigint {
+  let value = 0n;
+  for (const byte of bytes) {
+    value = (value << 8n) | BigInt(byte);
+  }
+  return value;
+}
+
+export function bigIntToBytesBE(value: bigint, length: number): Uint8Array {
+  const out = new Uint8Array(length);
+  let v = value;
+  for (let i = length - 1; i >= 0; i--) {
+    out[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return out;
+}

package/src/passkey-manager/encoding.ts

@@ -0,0 +1,85 @@
+import { hexToBytes as sharedHexToBytes } from '@thru/sdk/helpers';
+
+export function arrayBufferToBase64Url(buffer: ArrayBuffer | SharedArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let base64 = '';
+  for (let i = 0; i < bytes.length; i++) {
+    base64 += String.fromCharCode(bytes[i]);
+  }
+  return btoa(base64).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function base64UrlToArrayBuffer(base64Url: string): ArrayBuffer {
+  const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+export function bytesToBase64Url(bytes: Uint8Array): string {
+  const slice = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  return arrayBufferToBase64Url(slice);
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  type BufferLike = {
+    from(value: Uint8Array): { toString(encoding: 'base64'): string };
+  };
+  const globalBuffer =
+    typeof globalThis !== 'undefined' ? (globalThis as { Buffer?: BufferLike }).Buffer : undefined;
+  if (globalBuffer) {
+    return globalBuffer.from(bytes).toString('base64');
+  }
+
+  if (typeof btoa === 'function') {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+
+  throw new Error('Base64 encoding is not supported in this environment');
+}
+
+export function base64UrlToBytes(base64Url: string): Uint8Array {
+  return new Uint8Array(base64UrlToArrayBuffer(base64Url));
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  return sharedHexToBytes(hex);
+}
+
+export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+export function compareBytes(a: Uint8Array, b: Uint8Array): number {
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return a.length - b.length;
+}
+
+export function uniqueAccounts(accounts: Uint8Array[]): Uint8Array[] {
+  const unique: Uint8Array[] = [];
+  for (const account of accounts) {
+    if (!unique.some((candidate) => bytesEqual(candidate, account))) {
+      unique.push(account);
+    }
+  }
+  return unique;
+}