@openzeppelin/guardian-evm-client 0.14.5

package/src/index.test.ts

@@ -0,0 +1,245 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  GuardianEvmClient,
+  GuardianEvmHttpError,
+  buildEvmSessionTypedData,
+  evmAccountId,
+  normalizeEvmAddress,
+  signProposalHash,
+  type Eip1193Provider,
+} from './index.js';
+
+const address = '0xE7f1725E7734CE288F8367e1Bb143E90bb3F0512';
+const normalizedAddress = '0xe7f1725e7734ce288f8367e1bb143e90bb3f0512';
+const validator = '0x1111111111111111111111111111111111111111';
+const accountId = `evm:31337:${normalizedAddress}`;
+const hash = `0x${'12'.repeat(32)}` as const;
+const signature = `0x${'11'.repeat(65)}` as const;
+const secondSigner = '0x2222222222222222222222222222222222222222';
+
+describe('guardian-evm-client', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('normalizes EVM addresses and account ids', () => {
+    expect(normalizeEvmAddress(address)).toBe(normalizedAddress);
+    expect(evmAccountId(31337, address)).toBe(accountId);
+  });
+
+  it('builds Guardian EVM session typed data', () => {
+    const typedData = buildEvmSessionTypedData({
+      address,
+      nonce: `0x${'ab'.repeat(32)}`,
+      issuedAt: 1,
+      expiresAt: 2,
+    });
+
+    expect(typedData.domain).toEqual({ name: 'Guardian EVM Session', version: '1' });
+    expect(typedData.primaryType).toBe('GuardianEvmSession');
+    expect(typedData.message.wallet).toBe(normalizedAddress);
+  });
+
+  it('logs in with an EIP-712 challenge and cookie fetch mode', async () => {
+    const provider = providerReturning(signature);
+    const fetchMock = mockFetch([
+      {
+        address: normalizedAddress,
+        nonce: `0x${'aa'.repeat(32)}`,
+        issued_at: 10,
+        expires_at: 20,
+      },
+      {
+        address: normalizedAddress,
+        expires_at: 1234,
+      },
+    ]);
+    const client = new GuardianEvmClient({
+      guardianUrl: 'http://guardian.test',
+      provider,
+      signerAddress: address,
+    });
+
+    const session = await client.login();
+
+    expect(session.address).toBe(normalizedAddress);
+    expect(provider.request).toHaveBeenCalledWith(
+      expect.objectContaining({ method: 'eth_signTypedData_v4' })
+    );
+    expect(fetchMock.mock.calls[0]?.[0]).toContain('/evm/auth/challenge');
+    expect(fetchMock.mock.calls[1]?.[0]).toContain('/evm/auth/verify');
+    expect(fetchMock.mock.calls[0]?.[1]).toMatchObject({ credentials: 'include' });
+  });
+
+  it('registers an EVM account through /evm/accounts', async () => {
+    const fetchMock = mockFetch([
+      {
+        account_id: accountId,
+        chain_id: 31337,
+        account_address: normalizedAddress,
+        multisig_validator_address: validator,
+        signers: [normalizedAddress, secondSigner],
+        threshold: 2,
+      },
+    ]);
+    const client = new GuardianEvmClient({ guardianUrl: 'http://guardian.test' });
+
+    const response = await client.configure({
+      chainId: 31337,
+      smartAccountAddress: address,
+      multisigValidatorAddress: validator,
+    });
+
+    expect(response.accountId).toBe(accountId);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe('http://guardian.test/evm/accounts');
+    const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body));
+    expect(body).toEqual({
+      chain_id: 31337,
+      account_address: normalizedAddress,
+      multisig_validator_address: validator,
+    });
+  });
+
+  it('creates proposals through /evm/proposals', async () => {
+    const fetchMock = mockFetch([proposal({ signatureCount: 1 })]);
+    const client = new GuardianEvmClient({ guardianUrl: 'http://guardian.test' });
+
+    const response = await client.createProposal({
+      chainId: 31337,
+      smartAccountAddress: address,
+      userOpHash: hash,
+      payload: '{"kind":"userOp"}',
+      nonce: '0x01',
+      signature,
+      ttlSeconds: 300,
+    });
+
+    expect(response.proposalId).toBe(hash);
+    expect(response.signatures).toHaveLength(1);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe('http://guardian.test/evm/proposals');
+    const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body));
+    expect(body).toEqual({
+      account_id: accountId,
+      user_op_hash: hash,
+      payload: '{"kind":"userOp"}',
+      nonce: '0x01',
+      ttl_seconds: 300,
+      signature,
+    });
+  });
+
+  it('fetches and converts proposals from /evm/proposals', async () => {
+    mockFetch([{ proposals: [proposal({ signatureCount: 1 })] }]);
+    const client = new GuardianEvmClient({ guardianUrl: 'http://guardian.test' });
+
+    const proposals = await client.listProposals(accountId);
+
+    expect(proposals[0]?.proposalId).toBe(hash);
+    expect(proposals[0]?.signatures[0]?.signedAt).toBe(42);
+  });
+
+  it('approves proposals with raw ECDSA signatures', async () => {
+    const fetchMock = mockFetch([proposal({ signatureCount: 2 })]);
+    const client = new GuardianEvmClient({ guardianUrl: 'http://guardian.test' });
+
+    const updated = await client.approveProposal(accountId, hash, { signature });
+
+    expect(updated.signatures).toHaveLength(2);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      `http://guardian.test/evm/proposals/${hash}/approve`
+    );
+    const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body));
+    expect(body).toEqual({ account_id: accountId, signature });
+  });
+
+  it('fetches executable proposal data and cancels proposals', async () => {
+    const fetchMock = mockFetch([
+      {
+        hash,
+        payload: '{}',
+        signatures: [signature],
+        signers: [normalizedAddress],
+      },
+      { success: true },
+    ]);
+    const client = new GuardianEvmClient({ guardianUrl: 'http://guardian.test' });
+
+    const executable = await client.getExecutableProposal(accountId, hash);
+    await client.cancelProposal(accountId, hash);
+
+    expect(executable.hash).toBe(hash);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      `http://guardian.test/evm/proposals/${hash}/executable?account_id=${encodeURIComponent(accountId)}`
+    );
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      `http://guardian.test/evm/proposals/${hash}/cancel`
+    );
+  });
+
+  it('parses stable error codes', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ code: 'unsupported_for_network' }), { status: 400 }))
+    );
+    const client = new GuardianEvmClient({ guardianUrl: 'http://guardian.test' });
+
+    await expect(client.challenge(address)).rejects.toMatchObject<Partial<GuardianEvmHttpError>>({
+      code: 'unsupported_for_network',
+    });
+  });
+
+  it('can request hash signatures from injected wallets', async () => {
+    const provider = providerReturning(signature);
+
+    const result = await signProposalHash(provider, address, hash);
+
+    expect(result).toBe(signature);
+    expect(provider.request).toHaveBeenCalledWith({
+      method: 'eth_sign',
+      params: [normalizedAddress, hash],
+    });
+  });
+});
+
+function providerReturning(result: string): Eip1193Provider {
+  return {
+    request: vi.fn(async () => result),
+  };
+}
+
+function mockFetch(jsonResponses: unknown[]) {
+  const fetchMock = vi.fn(async () => {
+    const response = jsonResponses.shift();
+    return new Response(JSON.stringify(response), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  });
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+}
+
+function proposal({ signatureCount }: { signatureCount: number }) {
+  const signatures = Array.from({ length: signatureCount }, (_, index) => ({
+    signer: index === 0 ? normalizedAddress : secondSigner,
+    signature,
+    signed_at: 42 + index,
+  }));
+  return {
+    proposal_id: hash,
+    account_id: accountId,
+    chain_id: 31337,
+    smart_account_address: normalizedAddress,
+    validator_address: validator,
+    user_op_hash: hash,
+    payload: '{}',
+    nonce: '1',
+    nonce_key: '0',
+    proposer: normalizedAddress,
+    signer_snapshot: [normalizedAddress, secondSigner],
+    threshold: 2,
+    signatures,
+    created_at: 1,
+    expires_at: 2,
+  };
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { GuardianEvmClient, type EvmSession } from './client.js';
+export {
+  requestWalletAddress,
+  signProposalHash,
+  signTypedData,
+  type Eip1193Provider,
+} from './auth.js';
+export { normalizeBytes32, normalizeEvmAddress, normalizeSignature, normalizeUint256String } from './encoding.js';
+export { GuardianEvmHttpError } from './errors.js';
+export {
+  buildEvmSessionTypedData,
+  type EvmSessionChallenge,
+  type GuardianTypedData,
+  type TypedDataField,
+} from './typed-data.js';
+export {
+  evmAccountId,
+  type AccountRegistration,
+  type ApproveRequest,
+  type ConfigureRequest,
+  type EvmProposalSignature,
+  type ExecutableProposal,
+  type Proposal,
+  type ProposeRequest,
+} from './proposals.js';

package/src/proposals.ts

@@ -0,0 +1,271 @@
+import {
+  normalizeBytes32,
+  normalizeEvmAddress,
+  normalizeSignature,
+  normalizeUint256String,
+} from './encoding.js';
+
+export interface ConfigureRequest {
+  chainId: number;
+  smartAccountAddress: `0x${string}` | string;
+  multisigValidatorAddress: `0x${string}` | string;
+}
+
+export interface AccountRegistration {
+  accountId: string;
+  chainId: number;
+  accountAddress: `0x${string}`;
+  multisigValidatorAddress: `0x${string}`;
+  signers: `0x${string}`[];
+  threshold: number;
+}
+
+export interface EvmProposalSignature {
+  signer: `0x${string}`;
+  signature: `0x${string}`;
+  signedAt: number;
+}
+
+export interface ProposeRequest {
+  accountId?: string;
+  chainId: number;
+  smartAccountAddress: `0x${string}` | string;
+  userOpHash: `0x${string}` | string;
+  payload: string;
+  nonce: string;
+  signature: `0x${string}` | string;
+  ttlSeconds: number;
+}
+
+export interface Proposal {
+  proposalId: string;
+  accountId: string;
+  chainId: number;
+  smartAccountAddress: `0x${string}`;
+  validatorAddress: `0x${string}`;
+  userOpHash: `0x${string}`;
+  payload: string;
+  nonce: string;
+  nonceKey: string;
+  proposer: `0x${string}`;
+  signerSnapshot: `0x${string}`[];
+  threshold: number;
+  signatures: EvmProposalSignature[];
+  createdAt: number;
+  expiresAt: number;
+}
+
+export interface ApproveRequest {
+  signature: `0x${string}` | string;
+}
+
+export interface ExecutableProposal {
+  hash: `0x${string}`;
+  payload: string;
+  signatures: `0x${string}`[];
+  signers: `0x${string}`[];
+}
+
+export interface ServerRegisterAccountRequest {
+  chain_id: number;
+  account_address: string;
+  multisig_validator_address: string;
+}
+
+export interface ServerRegisterAccountResponse {
+  account_id: string;
+  chain_id: number;
+  account_address: string;
+  multisig_validator_address: string;
+  signers: string[];
+  threshold: number;
+}
+
+export interface ServerCreateProposalRequest {
+  account_id: string;
+  user_op_hash: string;
+  payload: string;
+  nonce: string;
+  ttl_seconds: number;
+  signature: string;
+}
+
+export interface ServerProposal {
+  proposal_id: string;
+  account_id: string;
+  chain_id: number;
+  smart_account_address: string;
+  validator_address: string;
+  user_op_hash: string;
+  payload: string;
+  nonce: string;
+  nonce_key: string;
+  proposer: string;
+  signer_snapshot: string[];
+  threshold: number;
+  signatures: ServerProposalSignature[];
+  created_at: number;
+  expires_at: number;
+}
+
+export interface ServerProposalSignature {
+  signer: string;
+  signature: string;
+  signed_at: number;
+}
+
+export interface ServerListProposalsResponse {
+  proposals: ServerProposal[];
+}
+
+export interface ServerApproveProposalRequest {
+  account_id: string;
+  signature: string;
+}
+
+export interface ServerCancelProposalRequest {
+  account_id: string;
+}
+
+export interface ServerExecutableProposal {
+  hash: string;
+  payload: string;
+  signatures: string[];
+  signers: string[];
+}
+
+export function evmAccountId(chainId: number, smartAccountAddress: string): string {
+  assertSafeChainId(chainId);
+  return `evm:${chainId}:${normalizeEvmAddress(smartAccountAddress)}`;
+}
+
+export function toServerRegisterAccountRequest(
+  request: ConfigureRequest
+): ServerRegisterAccountRequest {
+  assertSafeChainId(request.chainId);
+  return {
+    chain_id: request.chainId,
+    account_address: normalizeEvmAddress(request.smartAccountAddress),
+    multisig_validator_address: normalizeEvmAddress(request.multisigValidatorAddress),
+  };
+}
+
+export function fromServerAccountRegistration(
+  server: ServerRegisterAccountResponse
+): AccountRegistration {
+  return {
+    accountId: stringField(server.account_id, 'account_id'),
+    chainId: numberField(server.chain_id, 'chain_id'),
+    accountAddress: normalizeEvmAddress(server.account_address),
+    multisigValidatorAddress: normalizeEvmAddress(server.multisig_validator_address),
+    signers: arrayField(server.signers, 'signers').map(normalizeEvmAddress),
+    threshold: numberField(server.threshold, 'threshold'),
+  };
+}
+
+export function toServerCreateProposalRequest(
+  request: ProposeRequest
+): ServerCreateProposalRequest {
+  assertSafeChainId(request.chainId);
+  assertPositiveSeconds(request.ttlSeconds, 'ttlSeconds');
+  const accountId =
+    request.accountId ?? evmAccountId(request.chainId, request.smartAccountAddress);
+  return {
+    account_id: accountId,
+    user_op_hash: normalizeBytes32(request.userOpHash, 'userOpHash'),
+    payload: request.payload,
+    nonce: normalizeUint256String(request.nonce),
+    ttl_seconds: request.ttlSeconds,
+    signature: normalizeSignature(request.signature),
+  };
+}
+
+export function toServerApproveRequest(
+  accountId: string,
+  request: ApproveRequest
+): ServerApproveProposalRequest {
+  return {
+    account_id: accountId,
+    signature: normalizeSignature(request.signature),
+  };
+}
+
+export function toServerCancelRequest(accountId: string): ServerCancelProposalRequest {
+  return { account_id: accountId };
+}
+
+export function fromServerProposal(server: ServerProposal): Proposal {
+  return {
+    proposalId: normalizeBytes32(server.proposal_id, 'proposal_id'),
+    accountId: stringField(server.account_id, 'account_id'),
+    chainId: numberField(server.chain_id, 'chain_id'),
+    smartAccountAddress: normalizeEvmAddress(server.smart_account_address),
+    validatorAddress: normalizeEvmAddress(server.validator_address),
+    userOpHash: normalizeBytes32(server.user_op_hash, 'user_op_hash'),
+    payload: stringField(server.payload, 'payload'),
+    nonce: stringField(server.nonce, 'nonce'),
+    nonceKey: stringField(server.nonce_key, 'nonce_key'),
+    proposer: normalizeEvmAddress(server.proposer),
+    signerSnapshot: arrayField(server.signer_snapshot, 'signer_snapshot').map(
+      normalizeEvmAddress
+    ),
+    threshold: numberField(server.threshold, 'threshold'),
+    signatures: arrayField(server.signatures, 'signatures').map(fromServerSignature),
+    createdAt: numberField(server.created_at, 'created_at'),
+    expiresAt: numberField(server.expires_at, 'expires_at'),
+  };
+}
+
+export function fromServerExecutable(server: ServerExecutableProposal): ExecutableProposal {
+  return {
+    hash: normalizeBytes32(server.hash, 'hash'),
+    payload: stringField(server.payload, 'payload'),
+    signatures: arrayField(server.signatures, 'signatures').map(normalizeSignature),
+    signers: arrayField(server.signers, 'signers').map(normalizeEvmAddress),
+  };
+}
+
+export function accountProposalParams(accountId: string): URLSearchParams {
+  return new URLSearchParams({ account_id: accountId });
+}
+
+function fromServerSignature(server: ServerProposalSignature): EvmProposalSignature {
+  return {
+    signer: normalizeEvmAddress(server.signer),
+    signature: normalizeSignature(server.signature),
+    signedAt: numberField(server.signed_at, 'signed_at'),
+  };
+}
+
+function assertSafeChainId(chainId: number): void {
+  if (!Number.isSafeInteger(chainId) || chainId <= 0) {
+    throw new Error('chainId must be a positive safe integer');
+  }
+}
+
+function assertPositiveSeconds(value: number, field: string): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${field} must be a positive safe integer`);
+  }
+}
+
+function stringField(value: unknown, field: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`${field} must be a string`);
+  }
+  return value;
+}
+
+function numberField(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+    throw new Error(`${field} must be a safe integer`);
+  }
+  return value;
+}
+
+function arrayField<T>(value: T[] | undefined, field: string): T[] {
+  if (!Array.isArray(value)) {
+    throw new Error(`${field} must be an array`);
+  }
+  return value;
+}

package/src/typed-data.ts

@@ -0,0 +1,112 @@
+import type { Hex } from 'viem';
+import { normalizeBytes32, normalizeEvmAddress } from './encoding.js';
+
+export type TypedDataField = { name: string; type: string };
+
+export type GuardianTypedData = {
+  domain: {
+    name: string;
+    version: string;
+  };
+  types: {
+    EIP712Domain: TypedDataField[];
+    GuardianEvmSession: TypedDataField[];
+  };
+  primaryType: 'GuardianEvmSession';
+  message: {
+    wallet: `0x${string}`;
+    nonce: Hex;
+    issued_at: number;
+    expires_at: number;
+  };
+};
+
+export interface EvmSessionChallenge {
+  address: `0x${string}`;
+  nonce: Hex;
+  issuedAt: number;
+  expiresAt: number;
+  typedData: GuardianTypedData;
+}
+
+export function buildEvmSessionTypedData(input: {
+  address: string;
+  nonce: string;
+  issuedAt: number;
+  expiresAt: number;
+}): GuardianTypedData {
+  return {
+    domain: {
+      name: 'Guardian EVM Session',
+      version: '1',
+    },
+    types: {
+      EIP712Domain: [
+        { name: 'name', type: 'string' },
+        { name: 'version', type: 'string' },
+      ],
+      GuardianEvmSession: [
+        { name: 'wallet', type: 'address' },
+        { name: 'nonce', type: 'bytes32' },
+        { name: 'issued_at', type: 'uint64' },
+        { name: 'expires_at', type: 'uint64' },
+      ],
+    },
+    primaryType: 'GuardianEvmSession',
+    message: {
+      wallet: normalizeEvmAddress(input.address),
+      nonce: normalizeBytes32(input.nonce, 'nonce'),
+      issued_at: input.issuedAt,
+      expires_at: input.expiresAt,
+    },
+  };
+}
+
+export function fromServerChallenge(server: ServerChallengeResponse): EvmSessionChallenge {
+  const issuedAt = numberField(server.issued_at, 'issued_at');
+  const expiresAt = numberField(server.expires_at, 'expires_at');
+  const typedData = parseTypedData(server.typed_data, server.address, server.nonce, issuedAt, expiresAt);
+  return {
+    address: normalizeEvmAddress(server.address),
+    nonce: normalizeBytes32(server.nonce, 'nonce'),
+    issuedAt,
+    expiresAt,
+    typedData,
+  };
+}
+
+interface ServerChallengeResponse {
+  address: string;
+  nonce: string;
+  issued_at: number;
+  expires_at: number;
+  typed_data?: unknown;
+}
+
+function parseTypedData(
+  value: unknown,
+  address: string,
+  nonce: string,
+  issuedAt: number,
+  expiresAt: number
+): GuardianTypedData {
+  if (!isRecord(value)) {
+    return buildEvmSessionTypedData({ address, nonce, issuedAt, expiresAt });
+  }
+  const primaryType = value.primaryType;
+  if (primaryType !== 'GuardianEvmSession') {
+    return buildEvmSessionTypedData({ address, nonce, issuedAt, expiresAt });
+  }
+  return buildEvmSessionTypedData({ address, nonce, issuedAt, expiresAt });
+}
+
+function numberField(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+    throw new Error(`${field} must be a safe integer`);
+  }
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}