@arcanahq/sdk-integrations 0.1.0

package/dist/test.d.ts

@@ -0,0 +1,12 @@
+import type { ArcanaWalletAdapter } from '@arcanahq/sdk';
+export declare const DEFAULT_ARCANA_TEST_PRIVATE_KEY: "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+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 declare function createTestArcanaWalletAdapter(options?: TestArcanaAdapterOptions): ArcanaWalletAdapter;

package/dist/test.js

@@ -0,0 +1,25 @@
+import { privateKeyToAccount } from 'viem/accounts';
+import { assertHexAddress } from './common.js';
+export const DEFAULT_ARCANA_TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+export function createTestArcanaWalletAdapter(options = {}) {
+    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() {
+            return address;
+        },
+        getChainId() {
+            return chainId;
+        },
+        async signTypedData(request) {
+            return account.signTypedData({
+                domain: request.domain,
+                types: request.types,
+                primaryType: request.primaryType,
+                message: request.message,
+            });
+        },
+    };
+}

package/dist/zerodev.d.ts

@@ -0,0 +1,32 @@
+import type { ArcanaWalletAdapter } from '@arcanahq/sdk';
+import { AdapterOptions, ViemWalletClientLike } 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 declare function createZeroDevArcanaWalletAdapter(options: ZeroDevArcanaAdapterOptions): ZeroDevArcanaWalletAdapter;

package/dist/zerodev.js

@@ -0,0 +1,27 @@
+import { assertHexAddress, createViemArcanaWalletAdapter, } from './common.js';
+export { registerArcanaDeviceWithAdapter } from './authenticate.js';
+export function createZeroDevArcanaWalletAdapter(options) {
+    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;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@arcanahq/sdk-integrations",
+  "version": "0.1.0",
+  "description": "Optional wallet and account-abstraction integrations for @arcanahq/sdk",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./privy": {
+      "import": "./dist/privy.js",
+      "types": "./dist/privy.d.ts",
+      "default": "./dist/privy.js"
+    },
+    "./dynamic": {
+      "import": "./dist/dynamic.js",
+      "types": "./dist/dynamic.d.ts",
+      "default": "./dist/dynamic.js"
+    },
+    "./zerodev": {
+      "import": "./dist/zerodev.js",
+      "types": "./dist/zerodev.d.ts",
+      "default": "./dist/zerodev.js"
+    },
+    "./authenticate": {
+      "import": "./dist/authenticate.js",
+      "types": "./dist/authenticate.d.ts",
+      "default": "./dist/authenticate.js"
+    },
+    "./test": {
+      "import": "./dist/test.js",
+      "types": "./dist/test.d.ts",
+      "default": "./dist/test.js"
+    },
+    "./privy-zerodev": {
+      "import": "./dist/privy-zerodev.js",
+      "types": "./dist/privy-zerodev.d.ts",
+      "default": "./dist/privy-zerodev.js"
+    },
+    "./dynamic-zerodev": {
+      "import": "./dist/dynamic-zerodev.js",
+      "types": "./dist/dynamic-zerodev.d.ts",
+      "default": "./dist/dynamic-zerodev.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@arcanahq/sdk": "^0.1.0",
+    "@dynamic-labs-sdk/client": "*",
+    "@dynamic-labs-sdk/evm": "*",
+    "@dynamic-labs-sdk/react-hooks": "*",
+    "@dynamic-labs-sdk/zerodev": "*",
+    "@dynamic-labs/sdk-react-core": "*",
+    "@dynamic-labs/viem-utils": "*",
+    "@privy-io/react-auth": "*",
+    "@zerodev/sdk": "*",
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@dynamic-labs-sdk/client": {
+      "optional": true
+    },
+    "@dynamic-labs-sdk/evm": {
+      "optional": true
+    },
+    "@dynamic-labs-sdk/react-hooks": {
+      "optional": true
+    },
+    "@dynamic-labs-sdk/zerodev": {
+      "optional": true
+    },
+    "@dynamic-labs/sdk-react-core": {
+      "optional": true
+    },
+    "@dynamic-labs/viem-utils": {
+      "optional": true
+    },
+    "@privy-io/react-auth": {
+      "optional": true
+    },
+    "@zerodev/sdk": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arcanahq/sdk": "file:../sdk",
+    "@types/node": "^20.19.41",
+    "typescript": "^5.3.0",
+    "viem": "^2.0.0",
+    "vitest": "^4.1.8"
+  }
+}

package/src/__tests__/adapters.test.ts

@@ -0,0 +1,286 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createEip1193ArcanaWalletAdapter,
+  createViemArcanaWalletAdapter,
+} from '../common.js';
+import {
+  authenticateArcanaWithDynamic,
+  createDynamicArcanaWalletAdapter,
+  ensureArcanaSessionWithDynamic,
+} from '../dynamic.js';
+import { createZeroDevArcanaWalletAdapter } from '../zerodev.js';
+import { registerArcanaDeviceWithAdapter } from '../authenticate.js';
+import { createTestArcanaWalletAdapter } from '../test.js';
+
+const address = '0xa0ee7a142d267c1f36714e4a8f75612f20a79720' as const;
+const verifyingContract = '0x1212121212121212121212121212121212121212' as const;
+
+const typedData = {
+  account: address,
+  domain: {
+    name: 'Arcana',
+    version: '1',
+    chainId: 31337,
+    verifyingContract,
+  },
+  types: {
+    DeviceRegistration: [
+      { name: 'userAddress', type: 'address' },
+      { name: 'devicePubkey', type: 'string' },
+      { name: 'timestamp', type: 'uint256' },
+      { name: 'nonce', type: 'string' },
+    ],
+  },
+  primaryType: 'DeviceRegistration',
+  message: {
+    userAddress: address,
+    devicePubkey: 'ab'.repeat(32),
+    timestamp: 1n,
+    nonce: 'nonce',
+  },
+};
+
+describe('Arcana integration adapters', () => {
+  it('wraps a Viem-compatible wallet client', async () => {
+    const signTypedData = vi.fn().mockResolvedValue('0x' + '11'.repeat(65));
+    const walletClient = {
+      account: { address },
+      getChainId: vi.fn().mockResolvedValue(31337),
+      signTypedData,
+    };
+
+    const adapter = createViemArcanaWalletAdapter(walletClient);
+
+    await expect(adapter.getAddress()).resolves.toBe(address);
+    await expect(adapter.getChainId?.()).resolves.toBe(31337);
+    await expect(adapter.signTypedData(typedData)).resolves.toBe('0x' + '11'.repeat(65));
+    expect(signTypedData).toHaveBeenCalledWith(expect.objectContaining({ account: address }));
+  });
+
+  it('wraps an EIP-1193 provider and signs typed data v4', async () => {
+    const request = vi.fn(async ({ method }: { method: string }) => {
+      if (method === 'eth_accounts') return [address];
+      if (method === 'eth_chainId') return '0x7a69';
+      if (method === 'eth_signTypedData_v4') return '0x' + '22'.repeat(65);
+      throw new Error(`unexpected method ${method}`);
+    });
+
+    const adapter = createEip1193ArcanaWalletAdapter({ request });
+
+    await expect(adapter.getAddress()).resolves.toBe(address);
+    await expect(adapter.getChainId?.()).resolves.toBe(31337);
+    await expect(adapter.signTypedData(typedData)).resolves.toBe('0x' + '22'.repeat(65));
+    expect(request).toHaveBeenCalledWith(expect.objectContaining({
+      method: 'eth_signTypedData_v4',
+      params: expect.arrayContaining([address]),
+    }));
+  });
+
+  it('uses Dynamic getWalletClient when present', async () => {
+    const walletClient = {
+      account: { address },
+      signTypedData: vi.fn().mockResolvedValue('0x' + '33'.repeat(65)),
+    };
+
+    const adapter = await createDynamicArcanaWalletAdapter({
+      wallet: {
+        address,
+        getWalletClient: vi.fn().mockResolvedValue(walletClient),
+      },
+    });
+
+    await expect(adapter.getAddress()).resolves.toBe(address);
+    await expect(adapter.signTypedData(typedData)).resolves.toBe('0x' + '33'.repeat(65));
+  });
+
+  it('restores Dynamic Arcana device auth without registering again', async () => {
+    const walletClient = {
+      account: { address },
+      getChainId: vi.fn().mockResolvedValue(31337),
+      signTypedData: vi.fn().mockResolvedValue('0x' + '33'.repeat(65)),
+    };
+    const registerDevice = vi.fn();
+    const activateWallet = vi.fn();
+
+    const result = await authenticateArcanaWithDynamic({
+      client: {
+        auth: {
+          getDomainInfo: vi.fn().mockResolvedValue({
+            name: 'Arcana',
+            version: '1',
+            chainId: 31337,
+            verifyingContract,
+          }),
+        },
+        isAuthenticated: vi.fn().mockReturnValue(true),
+        ensureAuthenticated: vi.fn().mockResolvedValue(true),
+        deviceAuth: {
+          activateWallet,
+          getWalletAddress: vi.fn().mockReturnValue(address),
+          getUserId: vi.fn().mockReturnValue(address),
+          registerDevice,
+        },
+      },
+      walletClient,
+      chainId: 31337,
+    });
+
+    expect(result).toMatchObject({ address, userId: address, status: 'restored', restored: true });
+    expect(activateWallet).toHaveBeenCalledWith(address);
+    expect(registerDevice).not.toHaveBeenCalled();
+  });
+
+  it('exposes a Dynamic session helper for one-button Arcana sign-in flows', async () => {
+    const walletClient = {
+      account: { address },
+      getChainId: vi.fn().mockResolvedValue(31337),
+      signTypedData: vi.fn().mockResolvedValue('0x' + '33'.repeat(65)),
+    };
+    const registerDevice = vi.fn().mockResolvedValue({
+      device_id: 'dev-1',
+      refresh_token: 'refresh',
+      refresh_expires_at: 1,
+      access_token: 'access',
+      access_token_id: 'access-id',
+      access_expires_at: 2,
+      user_id: address,
+    });
+
+    const result = await ensureArcanaSessionWithDynamic({
+      client: {
+        auth: {
+          getDomainInfo: vi.fn().mockResolvedValue({
+            name: 'Arcana',
+            version: '1',
+            chainId: 31337,
+            verifyingContract,
+          }),
+        },
+        isAuthenticated: vi.fn().mockReturnValue(false),
+        ensureAuthenticated: vi.fn().mockResolvedValue(false),
+        deviceAuth: {
+          activateWallet: vi.fn(),
+          getWalletAddress: vi.fn().mockReturnValue(null),
+          getUserId: vi.fn().mockReturnValue(address),
+          registerDevice,
+        },
+      },
+      walletClient,
+      chainId: 31337,
+      deviceName: 'dynamic one button',
+    });
+
+    expect(result).toMatchObject({
+      address,
+      userId: address,
+      status: 'registered',
+      restored: false,
+    });
+  });
+
+  it('registers Dynamic Arcana device auth when restore is unavailable', async () => {
+    const walletClient = {
+      account: { address },
+      getChainId: vi.fn().mockResolvedValue(31337),
+      signTypedData: vi.fn().mockResolvedValue('0x' + '33'.repeat(65)),
+    };
+    const registerDevice = vi.fn().mockResolvedValue({
+      device_id: 'dev-1',
+      refresh_token: 'refresh',
+      refresh_expires_at: 1,
+      access_token: 'access',
+      access_token_id: 'access-id',
+      access_expires_at: 2,
+      user_id: address,
+      user: { id: address },
+    });
+
+    const result = await authenticateArcanaWithDynamic({
+      client: {
+        auth: {
+          getDomainInfo: vi.fn().mockResolvedValue({
+            name: 'Arcana',
+            version: '1',
+            chainId: 31337,
+            verifyingContract,
+          }),
+        },
+        isAuthenticated: vi.fn().mockReturnValue(false),
+        ensureAuthenticated: vi.fn().mockResolvedValue(false),
+        deviceAuth: {
+          activateWallet: vi.fn(),
+          getWalletAddress: vi.fn().mockReturnValue(null),
+          getUserId: vi.fn().mockReturnValue(address),
+          registerDevice,
+        },
+      },
+      walletClient,
+      chainId: 31337,
+      deviceName: 'dynamic test',
+    });
+
+    expect(result).toMatchObject({ address, userId: address, status: 'registered', restored: false });
+    expect(registerDevice).toHaveBeenCalledWith(
+      expect.any(Object),
+      address,
+      31337,
+      verifyingContract,
+      'dynamic test'
+    );
+  });
+
+  it('creates a deterministic local test adapter', async () => {
+    const adapter = createTestArcanaWalletAdapter();
+
+    expect(await adapter.getAddress()).toBe('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266');
+    expect(await adapter.getChainId?.()).toBe(31337);
+    await expect(adapter.signTypedData(typedData)).resolves.toMatch(/^0x[0-9a-f]+$/);
+  });
+
+  it('requires a ZeroDev owner signer instead of accepting a Kernel-only client', () => {
+    expect(() => createZeroDevArcanaWalletAdapter({
+      kernelClient: {
+        account: { address: '0x2222222222222222222222222222222222222222' },
+        signTypedData: vi.fn().mockResolvedValue('0x' + '44'.repeat(65)),
+      },
+    })).toThrow('ownerWalletClient');
+  });
+
+  it('registers Arcana device auth with adapter domain values', async () => {
+    const adapter = createViemArcanaWalletAdapter({
+      account: { address },
+      getChainId: vi.fn().mockResolvedValue(31337),
+      signTypedData: vi.fn().mockResolvedValue('0x' + '55'.repeat(65)),
+    });
+
+    const registerDevice = vi.fn().mockResolvedValue({
+      device_id: 'dev-1',
+      refresh_token: 'refresh',
+      refresh_expires_at: 1,
+      access_token: 'access',
+      access_token_id: 'access-id',
+      access_expires_at: 2,
+      user_id: address,
+    });
+
+    await registerArcanaDeviceWithAdapter({
+      auth: {
+        getDomainInfo: vi.fn().mockResolvedValue({
+          name: 'Arcana',
+          version: '1',
+          chainId: 31337,
+          verifyingContract,
+        }),
+      },
+      deviceAuth: { registerDevice },
+    }, adapter, { deviceName: 'test device' });
+
+    expect(registerDevice).toHaveBeenCalledWith(
+      adapter,
+      address,
+      31337,
+      verifyingContract,
+      'test device'
+    );
+  });
+});

package/src/authenticate.ts

@@ -0,0 +1,56 @@
+import type { ArcanaWalletAdapter, DeviceRegistrationResponse, DomainInfo } from '@arcanahq/sdk';
+import { assertHexAddress } from './common.js';
+
+export interface ArcanaClientForDeviceRegistration {
+  auth: {
+    getDomainInfo(): Promise<DomainInfo>;
+  };
+  deviceAuth?: {
+    registerDevice(
+      wallet: ArcanaWalletAdapter,
+      address: `0x${string}`,
+      chainId: number,
+      verifyingContract: `0x${string}`,
+      deviceName?: string
+    ): Promise<DeviceRegistrationResponse>;
+  };
+}
+
+export interface RegisterArcanaDeviceOptions {
+  chainId?: number;
+  verifyingContract?: `0x${string}`;
+  deviceName?: string;
+}
+
+export async function registerArcanaDeviceWithAdapter(
+  client: ArcanaClientForDeviceRegistration,
+  adapter: ArcanaWalletAdapter,
+  options: RegisterArcanaDeviceOptions = {}
+): Promise<DeviceRegistrationResponse> {
+  if (!client.deviceAuth) {
+    throw new Error('Arcana device authentication is not enabled on this client');
+  }
+
+  const address = await adapter.getAddress();
+  const domainInfo = await client.auth.getDomainInfo();
+  const domainVerifyingContract = domainInfo.verifyingContract || domainInfo.verifying_contract;
+  const verifyingContract = assertHexAddress(
+    options.verifyingContract ?? domainVerifyingContract,
+    'Arcana auth verifying contract'
+  );
+
+  const adapterChainId = adapter.getChainId ? await adapter.getChainId() : undefined;
+  const chainId = options.chainId ?? adapterChainId ?? domainInfo.chainId;
+
+  if (chainId === undefined || !Number.isInteger(chainId)) {
+    throw new Error('Arcana device registration requires a chainId');
+  }
+
+  return client.deviceAuth.registerDevice(
+    adapter,
+    address,
+    chainId,
+    verifyingContract,
+    options.deviceName
+  );
+}