@arcanahq/sdk-integrations 0.1.0

package/src/common.ts

@@ -0,0 +1,162 @@
+import type { ArcanaTypedDataRequest, ArcanaWalletAdapter } from '@arcanahq/sdk';
+
+export type HexAddress = `0x${string}`;
+export type HexSignature = `0x${string}`;
+
+export interface SignTypedDataCapable {
+  signTypedData(request: ArcanaTypedDataRequest & { account?: HexAddress }): Promise<HexSignature>;
+}
+
+export interface ViemWalletClientLike extends SignTypedDataCapable {
+  account?: { address?: string } | HexAddress | null;
+  getAddresses?: () => Promise<string[]>;
+  getChainId?: () => Promise<number>;
+}
+
+export interface Eip1193ProviderLike {
+  request(args: { method: string; params?: unknown[] }): Promise<unknown>;
+}
+
+export interface AdapterOptions {
+  address?: string;
+  chainId?: number;
+}
+
+export function assertHexAddress(address: string | undefined | null, label: string = 'address'): HexAddress {
+  if (!address || !/^0x[a-fA-F0-9]{40}$/.test(address)) {
+    throw new Error(`Arcana integration requires a valid EVM ${label}`);
+  }
+  return address.toLowerCase() as HexAddress;
+}
+
+export async function resolveAddress(
+  provided: string | undefined,
+  walletClient?: ViemWalletClientLike,
+  provider?: Eip1193ProviderLike
+): Promise<HexAddress> {
+  if (provided) {
+    return assertHexAddress(provided);
+  }
+
+  const account = walletClient?.account;
+  if (typeof account === 'string') {
+    return assertHexAddress(account);
+  }
+  if (account && typeof account === 'object' && account.address) {
+    return assertHexAddress(account.address);
+  }
+
+  if (walletClient?.getAddresses) {
+    const addresses = await walletClient.getAddresses();
+    return assertHexAddress(addresses[0], 'wallet address');
+  }
+
+  if (provider) {
+    const addresses = await provider.request({ method: 'eth_accounts' });
+    if (!Array.isArray(addresses)) {
+      throw new Error('Arcana integration expected eth_accounts to return an array');
+    }
+    return assertHexAddress(addresses[0] as string | undefined, 'wallet address');
+  }
+
+  throw new Error('Arcana integration could not resolve a wallet address');
+}
+
+export async function resolveChainId(
+  provided: number | undefined,
+  walletClient?: ViemWalletClientLike,
+  provider?: Eip1193ProviderLike
+): Promise<number | undefined> {
+  if (provided !== undefined) {
+    return provided;
+  }
+  if (walletClient?.getChainId) {
+    return walletClient.getChainId();
+  }
+  if (provider) {
+    const chainId = await provider.request({ method: 'eth_chainId' });
+    if (typeof chainId === 'string') {
+      const parsed = chainId.startsWith('0x') ? parseInt(chainId, 16) : parseInt(chainId, 10);
+      if (!Number.isInteger(parsed)) {
+        throw new Error('Arcana integration expected eth_chainId to be parseable as an integer');
+      }
+      return parsed;
+    }
+    if (typeof chainId === 'number') {
+      return chainId;
+    }
+    throw new Error('Arcana integration expected eth_chainId to return a string or number');
+  }
+  return undefined;
+}
+
+export function stringifyTypedData(request: ArcanaTypedDataRequest): string {
+  return JSON.stringify({
+    domain: request.domain,
+    types: request.types,
+    primaryType: request.primaryType,
+    message: request.message,
+  }, (_key, value) => typeof value === 'bigint' ? value.toString() : value);
+}
+
+export function createViemArcanaWalletAdapter(
+  walletClient: ViemWalletClientLike,
+  options: AdapterOptions = {}
+): ArcanaWalletAdapter {
+  if (!walletClient || typeof walletClient.signTypedData !== 'function') {
+    throw new Error('Arcana integration requires a Viem-compatible signer with signTypedData');
+  }
+
+  return {
+    async getAddress() {
+      return resolveAddress(options.address, walletClient);
+    },
+    async getChainId() {
+      const chainId = await resolveChainId(options.chainId, walletClient);
+      if (chainId === undefined) {
+        throw new Error('Arcana integration could not resolve chainId from the Viem signer');
+      }
+      return chainId;
+    },
+    async signTypedData(request) {
+      const address = await resolveAddress(options.address, walletClient);
+      return walletClient.signTypedData({
+        ...request,
+        account: address,
+      });
+    },
+  };
+}
+
+export function createEip1193ArcanaWalletAdapter(
+  provider: Eip1193ProviderLike,
+  options: AdapterOptions = {}
+): ArcanaWalletAdapter {
+  if (!provider || typeof provider.request !== 'function') {
+    throw new Error('Arcana integration requires an EIP-1193 provider with request()');
+  }
+
+  return {
+    async getAddress() {
+      return resolveAddress(options.address, undefined, provider);
+    },
+    async getChainId() {
+      const chainId = await resolveChainId(options.chainId, undefined, provider);
+      if (chainId === undefined) {
+        throw new Error('Arcana integration could not resolve chainId from the EIP-1193 provider');
+      }
+      return chainId;
+    },
+    async signTypedData(request) {
+      const address = await resolveAddress(options.address, undefined, provider);
+      const signature = await provider.request({
+        method: 'eth_signTypedData_v4',
+        params: [address, stringifyTypedData(request)],
+      });
+      if (typeof signature !== 'string' || !signature.startsWith('0x')) {
+        throw new Error('Arcana integration expected eth_signTypedData_v4 to return a hex signature');
+      }
+      return signature as HexSignature;
+    },
+  };
+}

package/src/dynamic-zerodev.ts

@@ -0,0 +1,15 @@
+import { createZeroDevArcanaWalletAdapter } from './zerodev.js';
+import type { ZeroDevArcanaAdapterOptions, ZeroDevArcanaWalletAdapter } from './zerodev.js';
+
+export { registerArcanaDeviceWithAdapter } from './authenticate.js';
+export type { ArcanaClientForDeviceRegistration, RegisterArcanaDeviceOptions } from './authenticate.js';
+export { createDynamicArcanaWalletAdapter } from './dynamic.js';
+export type { DynamicArcanaAdapterOptions, DynamicWalletLike } from './dynamic.js';
+export { createZeroDevArcanaWalletAdapter } from './zerodev.js';
+export type { ZeroDevAccountLike, ZeroDevArcanaAdapterOptions, ZeroDevArcanaWalletAdapter, ZeroDevClientLike } from './zerodev.js';
+
+export function createDynamicZeroDevArcanaWalletAdapter(
+  options: ZeroDevArcanaAdapterOptions
+): ZeroDevArcanaWalletAdapter {
+  return createZeroDevArcanaWalletAdapter(options);
+}

package/src/dynamic.ts

@@ -0,0 +1,135 @@
+import type { ArcanaWalletAdapter } from '@arcanahq/sdk';
+import {
+  AdapterOptions,
+  Eip1193ProviderLike,
+  ViemWalletClientLike,
+  createEip1193ArcanaWalletAdapter,
+  createViemArcanaWalletAdapter,
+} from './common.js';
+import {
+  ArcanaClientForDeviceRegistration,
+  RegisterArcanaDeviceOptions,
+  registerArcanaDeviceWithAdapter,
+} from './authenticate.js';
+
+export { registerArcanaDeviceWithAdapter } from './authenticate.js';
+export type { ArcanaClientForDeviceRegistration, RegisterArcanaDeviceOptions } from './authenticate.js';
+
+export interface DynamicWalletLike {
+  address?: string;
+  getAddress?: () => string | Promise<string>;
+  getEthereumProvider?: () => Eip1193ProviderLike | Promise<Eip1193ProviderLike>;
+  getWalletClient?: () => ViemWalletClientLike | Promise<ViemWalletClientLike>;
+  connector?: {
+    getSigner?: () => unknown | Promise<unknown>;
+  };
+}
+
+export interface DynamicArcanaAdapterOptions extends AdapterOptions {
+  wallet?: DynamicWalletLike;
+  walletClient?: ViemWalletClientLike;
+}
+
+export interface DynamicArcanaAuthClient extends ArcanaClientForDeviceRegistration {
+  ensureAuthenticated?(): Promise<boolean>;
+  isAuthenticated?(): boolean;
+  deviceAuth?: ArcanaClientForDeviceRegistration['deviceAuth'] & {
+    activateWallet?(address: string | null): Promise<void>;
+    getUserId?(): string | null;
+    getWalletAddress?(): string | null;
+  };
+}
+
+export interface DynamicArcanaAuthOptions extends DynamicArcanaAdapterOptions, RegisterArcanaDeviceOptions {
+  client: DynamicArcanaAuthClient;
+  deviceName?: string;
+  ensureChain?: boolean;
+}
+
+export interface DynamicArcanaAuthResult {
+  adapter: ArcanaWalletAdapter;
+  address: `0x${string}`;
+  userId: string;
+  status: 'restored' | 'registered';
+  restored: boolean;
+}
+
+export async function createDynamicArcanaWalletAdapter(
+  options: DynamicArcanaAdapterOptions
+): Promise<ArcanaWalletAdapter> {
+  if (options.walletClient) {
+    return createViemArcanaWalletAdapter(options.walletClient, options);
+  }
+
+  if (!options.wallet) {
+    throw new Error('Dynamic Arcana integration requires a Dynamic wallet or Viem walletClient');
+  }
+
+  const walletAddress = options.address
+    ?? options.wallet.address
+    ?? (typeof options.wallet.getAddress === 'function' ? await options.wallet.getAddress() : undefined);
+
+  if (typeof options.wallet.getWalletClient === 'function') {
+    const walletClient = await options.wallet.getWalletClient();
+    return createViemArcanaWalletAdapter(walletClient, {
+      ...options,
+      address: walletAddress,
+    });
+  }
+
+  if (typeof options.wallet.getEthereumProvider === 'function') {
+    const provider = await options.wallet.getEthereumProvider();
+    return createEip1193ArcanaWalletAdapter(provider, {
+      ...options,
+      address: walletAddress,
+    });
+  }
+
+  throw new Error('Dynamic wallet does not expose getWalletClient() or getEthereumProvider(); pass a Dynamic Viem walletClient instead');
+}
+
+export async function ensureArcanaSessionWithDynamic(
+  options: DynamicArcanaAuthOptions
+): Promise<DynamicArcanaAuthResult> {
+  const { client, chainId, ensureChain = true } = options;
+  const adapter = await createDynamicArcanaWalletAdapter(options);
+  const address = await adapter.getAddress();
+
+  await client.deviceAuth?.activateWallet?.(address);
+
+  if (client.isAuthenticated?.()) {
+    const sessionWallet = client.deviceAuth?.getWalletAddress?.()?.toLowerCase() || '';
+    if (!sessionWallet || sessionWallet === address.toLowerCase()) {
+      const authenticated = await client.ensureAuthenticated?.();
+      const userId = client.deviceAuth?.getUserId?.() || '';
+      if (authenticated && userId) {
+        return { adapter, address, userId, status: 'restored', restored: true };
+      }
+    }
+  }
+
+  if (ensureChain && chainId !== undefined) {
+    const adapterChainId = await adapter.getChainId?.();
+    if (adapterChainId !== undefined && adapterChainId !== chainId) {
+      throw new Error(`Dynamic wallet is connected to chain ${adapterChainId}; switch to chain ${chainId} and retry`);
+    }
+  }
+
+  const registration = await registerArcanaDeviceWithAdapter(client, adapter, {
+    chainId,
+    verifyingContract: options.verifyingContract,
+    deviceName: options.deviceName,
+  });
+  const userId = registration.user_id || client.deviceAuth?.getUserId?.() || '';
+  if (!userId) {
+    throw new Error('Arcana Dynamic authentication did not return a user id');
+  }
+
+  return { adapter, address, userId, status: 'registered', restored: false };
+}
+
+export async function authenticateArcanaWithDynamic(
+  options: DynamicArcanaAuthOptions
+): Promise<DynamicArcanaAuthResult> {
+  return ensureArcanaSessionWithDynamic(options);
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+export {
+  createEip1193ArcanaWalletAdapter,
+  createViemArcanaWalletAdapter,
+} from './common.js';
+export type {
+  AdapterOptions,
+  Eip1193ProviderLike,
+  HexAddress,
+  HexSignature,
+  SignTypedDataCapable,
+  ViemWalletClientLike,
+} from './common.js';
+
+export { registerArcanaDeviceWithAdapter } from './authenticate.js';
+export type {
+  ArcanaClientForDeviceRegistration,
+  RegisterArcanaDeviceOptions,
+} from './authenticate.js';
+
+export { createPrivyArcanaWalletAdapter } from './privy.js';
+export type { PrivyArcanaAdapterOptions, PrivyWalletLike } from './privy.js';
+
+export {
+  authenticateArcanaWithDynamic,
+  createDynamicArcanaWalletAdapter,
+  ensureArcanaSessionWithDynamic,
+} from './dynamic.js';
+export type {
+  DynamicArcanaAdapterOptions,
+  DynamicArcanaAuthClient,
+  DynamicArcanaAuthOptions,
+  DynamicArcanaAuthResult,
+  DynamicWalletLike,
+} from './dynamic.js';
+
+export {
+  DEFAULT_ARCANA_TEST_PRIVATE_KEY,
+  createTestArcanaWalletAdapter,
+} from './test.js';
+export type { TestArcanaAdapterOptions } from './test.js';
+
+export { createZeroDevArcanaWalletAdapter } from './zerodev.js';
+export type {
+  ZeroDevAccountLike,
+  ZeroDevArcanaAdapterOptions,
+  ZeroDevArcanaWalletAdapter,
+  ZeroDevClientLike,
+} from './zerodev.js';

package/src/privy-zerodev.ts

@@ -0,0 +1,15 @@
+import { createZeroDevArcanaWalletAdapter } from './zerodev.js';
+import type { ZeroDevArcanaAdapterOptions, ZeroDevArcanaWalletAdapter } from './zerodev.js';
+
+export { registerArcanaDeviceWithAdapter } from './authenticate.js';
+export type { ArcanaClientForDeviceRegistration, RegisterArcanaDeviceOptions } from './authenticate.js';
+export { createPrivyArcanaWalletAdapter } from './privy.js';
+export type { PrivyArcanaAdapterOptions, PrivyWalletLike } from './privy.js';
+export { createZeroDevArcanaWalletAdapter } from './zerodev.js';
+export type { ZeroDevAccountLike, ZeroDevArcanaAdapterOptions, ZeroDevArcanaWalletAdapter, ZeroDevClientLike } from './zerodev.js';
+
+export function createPrivyZeroDevArcanaWalletAdapter(
+  options: ZeroDevArcanaAdapterOptions
+): ZeroDevArcanaWalletAdapter {
+  return createZeroDevArcanaWalletAdapter(options);
+}

package/src/privy.ts

@@ -0,0 +1,48 @@
+import type { ArcanaWalletAdapter } from '@arcanahq/sdk';
+import {
+  AdapterOptions,
+  Eip1193ProviderLike,
+  ViemWalletClientLike,
+  createEip1193ArcanaWalletAdapter,
+  createViemArcanaWalletAdapter,
+} from './common.js';
+
+export { registerArcanaDeviceWithAdapter } from './authenticate.js';
+export type { ArcanaClientForDeviceRegistration, RegisterArcanaDeviceOptions } from './authenticate.js';
+
+export interface PrivyWalletLike {
+  address?: string;
+  getEthereumProvider?: () => Eip1193ProviderLike | Promise<Eip1193ProviderLike>;
+}
+
+export interface PrivyArcanaAdapterOptions extends AdapterOptions {
+  wallet?: PrivyWalletLike;
+  walletClient?: ViemWalletClientLike;
+  account?: ViemWalletClientLike;
+}
+
+export async function createPrivyArcanaWalletAdapter(
+  options: PrivyArcanaAdapterOptions
+): Promise<ArcanaWalletAdapter> {
+  if (options.walletClient) {
+    return createViemArcanaWalletAdapter(options.walletClient, options);
+  }
+
+  if (options.account) {
+    return createViemArcanaWalletAdapter(options.account, options);
+  }
+
+  if (!options.wallet) {
+    throw new Error('Privy Arcana integration requires a Privy wallet, Viem walletClient, or Viem account');
+  }
+
+  if (typeof options.wallet.getEthereumProvider !== 'function') {
+    throw new Error('Privy wallet does not expose getEthereumProvider(); pass toViemAccount(wallet) as account instead');
+  }
+
+  const provider = await options.wallet.getEthereumProvider();
+  return createEip1193ArcanaWalletAdapter(provider, {
+    ...options,
+    address: options.address ?? options.wallet.address,
+  });
+}

package/src/test.ts

@@ -0,0 +1,43 @@
+import { privateKeyToAccount } from 'viem/accounts';
+import type { ArcanaWalletAdapter } from '@arcanahq/sdk';
+import type { HexAddress } from './common.js';
+import { assertHexAddress } from './common.js';
+
+export const DEFAULT_ARCANA_TEST_PRIVATE_KEY =
+  '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80' as const;
+
+export interface TestArcanaAdapterOptions {
+  /**
+   * Deterministic private key used only for local/test auth. Defaults to the
+   * first Anvil account so local agents can authenticate without OTP flows.
+   */
+  privateKey?: `0x${string}`;
+  /** Chain id to report to Arcana device registration. */
+  chainId?: number;
+}
+
+export function createTestArcanaWalletAdapter(
+  options: TestArcanaAdapterOptions = {}
+): ArcanaWalletAdapter {
+  const privateKey = options.privateKey ?? DEFAULT_ARCANA_TEST_PRIVATE_KEY;
+  const account = privateKeyToAccount(privateKey);
+  const address = assertHexAddress(account.address, 'test wallet address');
+  const chainId = options.chainId ?? 31337;
+
+  return {
+    getAddress(): HexAddress {
+      return address;
+    },
+    getChainId(): number {
+      return chainId;
+    },
+    async signTypedData(request) {
+      return account.signTypedData({
+        domain: request.domain,
+        types: request.types,
+        primaryType: request.primaryType,
+        message: request.message,
+      } as Parameters<typeof account.signTypedData>[0]);
+    },
+  };
+}

package/src/zerodev.ts

@@ -0,0 +1,73 @@
+import type { ArcanaWalletAdapter } from '@arcanahq/sdk';
+import {
+  AdapterOptions,
+  ViemWalletClientLike,
+  assertHexAddress,
+  createViemArcanaWalletAdapter,
+} from './common.js';
+
+export { registerArcanaDeviceWithAdapter } from './authenticate.js';
+export type { ArcanaClientForDeviceRegistration, RegisterArcanaDeviceOptions } from './authenticate.js';
+
+export interface ZeroDevAccountLike {
+  address?: string;
+}
+
+export interface ZeroDevClientLike extends ViemWalletClientLike {
+  account?: ZeroDevAccountLike | `0x${string}` | null;
+}
+
+export interface ZeroDevArcanaAdapterOptions extends AdapterOptions {
+  /**
+   * EOA or embedded wallet signer that controls the Kernel account.
+   *
+   * Arcana device registration currently verifies ECDSA recovery against
+   * user_address, so the signer must be the controlling wallet, not the Kernel
+   * smart-account address.
+   */
+  ownerWalletClient?: ViemWalletClientLike;
+  /** Alias used by Dynamic's ZeroDev helper docs. */
+  signerWalletClient?: ViemWalletClientLike;
+  /** Optional smart account address for app bookkeeping. It is not used for Arcana auth. */
+  smartAccountAddress?: string;
+  /** @deprecated Pass ownerWalletClient/signerWalletClient. Kernel signatures are not valid for Arcana auth yet. */
+  kernelClient?: ZeroDevClientLike;
+  /** @deprecated Use smartAccountAddress. */
+  smartAccount?: ZeroDevAccountLike;
+}
+
+export interface ZeroDevArcanaWalletAdapter extends ArcanaWalletAdapter {
+  getSmartAccountAddress(): `0x${string}` | null;
+}
+
+export function createZeroDevArcanaWalletAdapter(
+  options: ZeroDevArcanaAdapterOptions
+): ZeroDevArcanaWalletAdapter {
+  const ownerWalletClient = options.ownerWalletClient ?? options.signerWalletClient;
+  if (!ownerWalletClient) {
+    throw new Error('ZeroDev Arcana integration requires ownerWalletClient/signerWalletClient for Arcana auth; Kernel smart-account signatures are not accepted by Arcana device registration yet');
+  }
+
+  if (options.kernelClient && !options.ownerWalletClient && !options.signerWalletClient) {
+    throw new Error('ZeroDev kernelClient was provided without an owner signer. Pass ownerWalletClient/signerWalletClient for Arcana auth');
+  }
+
+  const smartAccountAddress = options.smartAccountAddress
+    ?? (typeof options.kernelClient?.account === 'string' ? options.kernelClient.account : options.kernelClient?.account?.address)
+    ?? options.smartAccount?.address
+    ?? null;
+
+  const adapter = createViemArcanaWalletAdapter(ownerWalletClient, {
+    ...options,
+    address: options.address,
+  });
+
+  return {
+    ...adapter,
+    getSmartAccountAddress() {
+      return smartAccountAddress
+        ? assertHexAddress(smartAccountAddress, 'ZeroDev smart account address')
+        : null;
+    },
+  };
+}