accounts 0.12.0 → 0.12.2

package/src/core/AccessKey.test.ts

@@ -1,7 +1,7 @@
-import { WebCryptoP256 } from 'ox'
+import { Hex, WebCryptoP256 } from 'ox'
 import { KeyAuthorization, SignatureEnvelope } from 'ox/tempo'
 import { encodeErrorResult } from 'viem'
-import { Abis, Account as TempoAccount } from 'viem/tempo'
+import { Abis, Account as TempoAccount, Actions } from 'viem/tempo'
 import { describe, expect, test } from 'vp/test'
 
 import { accounts, privateKeys } from '../../test/config.js'
@@ -16,7 +16,11 @@ const rootAddress = accounts[0]!.address
 
 function createKeyAuthorization(
   address: `0x${string}`,
-  options: { expiry?: number | undefined; limits?: { token: `0x${string}`; limit: bigint }[] } = {},
+  options: {
+    expiry?: number | undefined
+    limits?: { token: `0x${string}`; limit: bigint }[] | undefined
+    scopes?: KeyAuthorization.Scope[] | undefined
+  } = {},
 ) {
   return KeyAuthorization.from(
     {
@@ -24,6 +28,7 @@ function createKeyAuthorization(
       chainId: 1n,
       expiry: options.expiry,
       limits: options.limits,
+      scopes: options.scopes,
       type: 'p256',
     },
     { signature: SignatureEnvelope.from(`0x${'00'.repeat(65)}`) },
@@ -285,9 +290,9 @@ describe('generate', () => {
   })
 })
 
-describe('prepare', () => {
+describe('prepareAuthorization', () => {
   test('default: prepares generated p256 key authorization', async () => {
-    const result = await AccessKey.prepare({ chainId: 1, expiry: 123 })
+    const result = await AccessKey.prepareAuthorization({ chainId: 1, expiry: 123 })
 
     expect(result.keyAuthorization.address).toMatch(/^0x[0-9a-f]{40}$/i)
     expect(result.keyAuthorization.chainId).toMatchInlineSnapshot(`1n`)
@@ -297,7 +302,7 @@ describe('prepare', () => {
   })
 
   test('behavior: prepares external key authorization from address', async () => {
-    const result = await AccessKey.prepare({
+    const result = await AccessKey.prepareAuthorization({
       address: accounts[1]!.address,
       chainId: 123n,
       expiry: 456,
@@ -349,7 +354,7 @@ describe('prepare', () => {
     const keyPair = await WebCryptoP256.createKeyPair()
     const account = TempoAccount.fromWebCryptoP256(keyPair)
 
-    const result = await AccessKey.prepare({
+    const result = await AccessKey.prepareAuthorization({
       chainId: 123n,
       expiry: 456,
       keyType: 'p256',
@@ -370,7 +375,7 @@ describe('prepare', () => {
   })
 
   test('behavior: defaults external key type to secp256k1', async () => {
-    const result = await AccessKey.prepare({
+    const result = await AccessKey.prepareAuthorization({
       address: accounts[1]!.address,
       chainId: 1,
       expiry: 123,
@@ -380,6 +385,87 @@ describe('prepare', () => {
   })
 })
 
+describe('saveAuthorization', () => {
+  test('default: saves prepared authorization with provided signature', async () => {
+    const store = createStore()
+    const prepared = await AccessKey.prepareAuthorization({
+      address: accounts[1]!.address,
+      chainId: 1,
+      expiry: 123,
+    })
+    const signature = `0x${'11'.repeat(32)}${'22'.repeat(32)}1b` as const
+
+    const result = AccessKey.saveAuthorization({
+      address: rootAddress,
+      prepared,
+      signature,
+      store,
+    })
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "chainId": "0x1",
+        "expiry": "0x7b",
+        "keyId": "0x8C8d35429F74ec245F8Ef2f4Fd1e551cFF97d650",
+        "keyType": "secp256k1",
+        "limits": undefined,
+        "signature": {
+          "r": "0x1111111111111111111111111111111111111111111111111111111111111111",
+          "s": "0x2222222222222222222222222222222222222222222222222222222222222222",
+          "type": "secp256k1",
+          "yParity": "0x0",
+        },
+      }
+    `)
+    expect(store.getState().accessKeys.map(({ keyAuthorization: _, ...accessKey }) => accessKey))
+      .toMatchInlineSnapshot(`
+      [
+        {
+          "access": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
+          "address": "0x8C8d35429F74ec245F8Ef2f4Fd1e551cFF97d650",
+          "chainId": 1,
+          "expiry": 123,
+          "keyType": "secp256k1",
+          "limits": undefined,
+          "scopes": undefined,
+        },
+      ]
+    `)
+  })
+})
+
+describe('authorize', () => {
+  test('default: prepares, signs, and saves authorization', async () => {
+    const store = createStore()
+    const digests: Hex.Hex[] = []
+    const signature = `0x${'11'.repeat(32)}${'22'.repeat(32)}1b` as const
+    const account = {
+      ...accounts[0]!,
+      sign: async (parameters: { hash: Hex.Hex }) => {
+        digests.push(parameters.hash)
+        return signature
+      },
+    } as TempoAccount.Account
+
+    await AccessKey.authorize({
+      account,
+      chainId: 1,
+      parameters: {
+        address: accounts[1]!.address,
+        expiry: 123,
+      },
+      store,
+    })
+
+    expect(digests).toMatchInlineSnapshot(`
+      [
+        "0xea47721547363fc82a5dca62b4544e4718d861b3df10bfac65d30102594b5c26",
+      ]
+    `)
+    expect(store.getState().accessKeys.length).toMatchInlineSnapshot(`1`)
+  })
+})
+
 describe('hydrate', () => {
   test('default: hydrates webCrypto access key to signable account', async () => {
     const keyPair = await WebCryptoP256.createKeyPair()
@@ -660,6 +746,96 @@ describe('selectAccount', () => {
     expect(result?.source).toMatchInlineSnapshot(`"accessKey"`)
   })
 
+  test('behavior: scoped access key checks recipient allowlist', async () => {
+    const keyPair = await WebCryptoP256.createKeyPair()
+    const token = '0x0000000000000000000000000000000000000abc' as const
+    const recipient = '0x0000000000000000000000000000000000000def' as const
+    const store = setup([
+      {
+        access: rootAddress,
+        address: '0x0000000000000000000000000000000000000099',
+        chainId: 1,
+        keyPair,
+        keyType: 'webCrypto',
+        scopes: [
+          { address: token, selector: 'transfer(address,uint256)', recipients: [recipient] },
+        ],
+      },
+    ])
+    const call = Actions.token.transfer.call({
+      amount: 1n,
+      to: recipient,
+      token,
+    })
+
+    const result = AccessKey.selectAccount({
+      address: rootAddress,
+      chainId: 1,
+      store,
+      calls: [call],
+    })
+
+    expect(result?.source).toMatchInlineSnapshot(`"accessKey"`)
+  })
+
+  test('behavior: scoped access key skips non-allowlisted recipients', async () => {
+    const keyPair = await WebCryptoP256.createKeyPair()
+    const token = '0x0000000000000000000000000000000000000abc' as const
+    const store = setup([
+      {
+        access: rootAddress,
+        address: '0x0000000000000000000000000000000000000099',
+        chainId: 1,
+        keyPair,
+        keyType: 'webCrypto',
+        scopes: [
+          {
+            address: token,
+            selector: 'transfer(address,uint256)',
+            recipients: ['0x0000000000000000000000000000000000000def'],
+          },
+        ],
+      },
+    ])
+    const call = Actions.token.transfer.call({
+      amount: 1n,
+      to: '0x0000000000000000000000000000000000000fed',
+      token,
+    })
+
+    const result = AccessKey.selectAccount({
+      address: rootAddress,
+      chainId: 1,
+      store,
+      calls: [call],
+    })
+
+    expect(result).toMatchInlineSnapshot(`undefined`)
+  })
+
+  test('behavior: malformed scopes skip the access key', async () => {
+    const keyPair = await WebCryptoP256.createKeyPair()
+    const store = setup([
+      {
+        access: rootAddress,
+        address: '0x0000000000000000000000000000000000000099',
+        chainId: 1,
+        keyPair,
+        keyType: 'webCrypto',
+        scopes: [{}],
+      } as never,
+    ])
+
+    const result = AccessKey.selectAccount({
+      address: rootAddress,
+      chainId: 1,
+      store,
+      calls: [{ to: '0x0000000000000000000000000000000000000abc', data: '0xa9059cbb' }],
+    })
+
+    expect(result).toMatchInlineSnapshot(`undefined`)
+  })
+
   test('behavior: scoped access key without selector allows any call to that address', async () => {
     const keyPair = await WebCryptoP256.createKeyPair()
     const token = '0x0000000000000000000000000000000000000abc' as const
@@ -703,6 +879,81 @@ describe('selectAccount', () => {
   })
 })
 
+describe('getStatus', () => {
+  test('behavior: returns pending for locally stored key authorization', async () => {
+    const store = createStore()
+    const keyPair = await WebCryptoP256.createKeyPair()
+    const accessKey = TempoAccount.fromWebCryptoP256(keyPair)
+    const keyAuthorization = createKeyAuthorization(accessKey.address)
+
+    AccessKey.save({ address: rootAddress, keyAuthorization, keyPair, store })
+
+    const result = await AccessKey.getStatus({
+      address: rootAddress,
+      chainId: 1,
+      store,
+    })
+
+    expect(result).toMatchInlineSnapshot(`"pending"`)
+  })
+
+  test('behavior: returns published for local key without pending authorization', async () => {
+    const store = createStore()
+    const keyPair = await WebCryptoP256.createKeyPair()
+    const accessKey = TempoAccount.fromWebCryptoP256(keyPair, { access: rootAddress })
+    const keyAuthorization = createKeyAuthorization(accessKey.accessKeyAddress)
+
+    AccessKey.save({ address: rootAddress, keyAuthorization, keyPair, store })
+    AccessKey.removePending(accessKey, { store })
+
+    const result = await AccessKey.getStatus({
+      address: rootAddress,
+      chainId: 1,
+      store,
+    })
+
+    expect(result).toMatchInlineSnapshot(`"published"`)
+  })
+
+  test('behavior: returns expired for expired local key', async () => {
+    const store = createStore()
+    const keyPair = await WebCryptoP256.createKeyPair()
+    const accessKey = TempoAccount.fromWebCryptoP256(keyPair)
+    const keyAuthorization = createKeyAuthorization(accessKey.address, { expiry: 100 })
+
+    AccessKey.save({ address: rootAddress, keyAuthorization, keyPair, store })
+
+    const result = await AccessKey.getStatus({
+      address: rootAddress,
+      chainId: 1,
+      now: 101,
+      store,
+    })
+
+    expect(result).toMatchInlineSnapshot(`"expired"`)
+  })
+
+  test('behavior: returns missing when no local key matches the policy', async () => {
+    const store = createStore()
+    const keyPair = await WebCryptoP256.createKeyPair()
+    const accessKey = TempoAccount.fromWebCryptoP256(keyPair)
+    const keyAuthorization = createKeyAuthorization(accessKey.address, {
+      scopes: [{ address: '0x0000000000000000000000000000000000000abc' }],
+    })
+
+    AccessKey.save({ address: rootAddress, keyAuthorization, keyPair, store })
+
+    const result = await AccessKey.getStatus({
+      address: rootAddress,
+      calls: [{ to: '0x0000000000000000000000000000000000000def', data: '0xdeadbeef' }],
+      chainId: 1,
+      store,
+    })
+
+    expect(result).toMatchInlineSnapshot(`"missing"`)
+  })
+})
+
 describe('revoke', () => {
   test('default: removes access keys by root address', async () => {
     const store = createStore()

package/src/core/AccessKey.ts

@@ -1,6 +1,7 @@
 import { AbiFunction, Address, Hex, Provider, PublicKey, WebCryptoP256 } from 'ox'
-import { KeyAuthorization } from 'ox/tempo'
-import { Account as TempoAccount } from 'viem/tempo'
+import { KeyAuthorization, SignatureEnvelope } from 'ox/tempo'
+import type { Client, Transport } from 'viem'
+import { Account as TempoAccount, Actions } from 'viem/tempo'
 
 import type { OneOf } from '../internal/types.js'
 import * as ExecutionError from './ExecutionError.js'
@@ -16,6 +17,21 @@ const removalErrorNames = new Set([
   'SignatureTypeMismatch',
 ])
 
+/** Access-key publication states. */
+export const status = {
+  /** No matching usable access key was found. */
+  missing: 'missing',
+  /** A matching key exists locally and still needs its first transaction to publish the authorization. */
+  pending: 'pending',
+  /** A matching key exists on-chain and can be used. */
+  published: 'published',
+  /** A matching key exists but is past its expiry. */
+  expired: 'expired',
+} as const
+
+/** Publication state for an access key. */
+export type Status = (typeof status)[keyof typeof status]
+
 /** Access key entry stored alongside accounts. */
 export type AccessKey = {
   /** Access key address. */
@@ -91,7 +107,9 @@ export declare namespace generate {
 }
 
 /** Prepares an unsigned key authorization and local key material when needed. */
-export async function prepare(options: prepare.Options): Promise<prepare.ReturnType> {
+export async function prepareAuthorization(
+  options: prepareAuthorization.Options,
+): Promise<prepareAuthorization.ReturnType> {
   const { address, chainId, expiry, keyType, limits, publicKey, scopes } = options
 
   if (address || publicKey) {
@@ -118,8 +136,8 @@ export async function prepare(options: prepare.Options): Promise<prepare.ReturnT
   return { keyAuthorization, keyPair }
 }
 
-export declare namespace prepare {
-  /** Options for {@link prepare}. */
+export declare namespace prepareAuthorization {
+  /** Options for {@link prepareAuthorization}. */
   type Options = {
     /** External access key address. Alternative to `publicKey`. */
     address?: Address.Address | undefined
@@ -146,6 +164,91 @@ export declare namespace prepare {
   }
 }
 
+/** Saves a prepared access key authorization with an existing signature. */
+export function saveAuthorization(
+  options: saveAuthorization.Options,
+): saveAuthorization.ReturnType {
+  const { address, prepared, signature, store } = options
+  const keyAuthorization = KeyAuthorization.from(prepared.keyAuthorization, {
+    signature: SignatureEnvelope.from(signature),
+  })
+
+  save({
+    address,
+    keyAuthorization,
+    ...(prepared.keyPair ? { keyPair: prepared.keyPair } : {}),
+    store,
+  })
+
+  return KeyAuthorization.toRpc(keyAuthorization)
+}
+
+export declare namespace saveAuthorization {
+  /** Options for {@link saveAuthorization}. */
+  type Options = {
+    /** Root account address that owns this access key. */
+    address: Address.Address
+    /** Prepared unsigned key authorization returned by {@link prepareAuthorization}. */
+    prepared: prepareAuthorization.ReturnType
+    /** Signature over the key authorization digest. */
+    signature: Hex.Hex
+    /** Reactive state store. */
+    store: Store.Store
+  }
+
+  /** Signed key authorization in RPC form. */
+  type ReturnType = KeyAuthorization.Rpc
+}
+
+/** Prepares, signs, and saves an access key authorization. */
+export async function authorize(options: authorize.Options): Promise<authorize.ReturnType> {
+  const { account, chainId, parameters, store } = options
+  const prepared = await prepareAuthorization({
+    ...parameters,
+    chainId: parameters.chainId ?? chainId,
+  })
+  return await signAuthorization({ account, prepared, store })
+}
+
+export declare namespace authorize {
+  /** Options for {@link authorize}. */
+  type Options = {
+    /** Root account that owns this access key and signs its authorization. */
+    account: TempoAccount.Account
+    /** Default chain ID for the authorization when `parameters.chainId` is not set. */
+    chainId: bigint | number
+    /** Access key authorization parameters. */
+    parameters: Omit<prepareAuthorization.Options, 'chainId'> & {
+      /** Chain ID the key authorization is scoped to. */
+      chainId?: bigint | number | undefined
+    }
+    /** Reactive state store. */
+    store: Store.Store
+  }
+
+  /** Signed key authorization in RPC form. */
+  type ReturnType = KeyAuthorization.Rpc
+}
+
+async function signAuthorization(
+  options: signAuthorization.Options,
+): Promise<signAuthorization.ReturnType> {
+  const { account, prepared, store } = options
+  const digest = KeyAuthorization.getSignPayload(prepared.keyAuthorization)
+  const signature = await account.sign({ hash: digest })
+  return saveAuthorization({ address: account.address, prepared, signature, store })
+}
+
+declare namespace signAuthorization {
+  type Options = {
+    account: TempoAccount.Account
+    prepared: prepareAuthorization.ReturnType
+    store: Store.Store
+  }
+
+  type ReturnType = KeyAuthorization.Rpc
+}
+
 /** Hydrates an access key entry to a viem Account. Only works for locally-generated keys. */
 export function hydrate(accessKey: AccessKey): TempoAccount.Account {
   if ('keyPair' in accessKey && accessKey.keyPair)
@@ -249,6 +352,48 @@ export declare namespace selectAccount {
   }
 }
 
+/** Returns publication status for a stored or on-chain access key. */
+export async function getStatus(options: getStatus.Options): Promise<getStatus.ReturnType> {
+  const { accessKey, address, calls, chainId, client, store } = options
+  const now = options.now ?? Date.now() / 1000
+  const local = store
+    .getState()
+    .accessKeys.find((key) => matches(key, { accessKey, address, calls, chainId }))
+
+  if (local) {
+    if (isExpired(local.expiry, now)) return status.expired
+    if (local.keyAuthorization) return status.pending
+    if (client) return await getPublishedStatus(client, { accessKey: local.address, address, now })
+    return status.published
+  }
+
+  if (accessKey && client) return await getPublishedStatus(client, { accessKey, address, now })
+  return status.missing
+}
+
+export declare namespace getStatus {
+  /** Options for {@link getStatus}. */
+  type Options = {
+    /** Root account address that owns the access key. */
+    address: Address.Address
+    /** Specific access key address to query. When omitted, the first locally matching key is used. */
+    accessKey?: Address.Address | undefined
+    /** Calls to match against access key scopes. */
+    calls?: readonly { to?: Address.Address | undefined; data?: Hex.Hex | undefined }[] | undefined
+    /** Chain ID the access key must be authorized on. */
+    chainId: number
+    /** Client used to verify published state on-chain. */
+    client?: Client<Transport> | undefined
+    /** Current Unix timestamp in seconds. Defaults to `Date.now() / 1000`. */
+    now?: number | undefined
+    /** Reactive state store. */
+    store: Store.Store
+  }
+
+  /** Access-key publication status. */
+  type ReturnType = Status
+}
+
 /** Removes an access key from the store. */
 export function revoke(options: revoke.Options): void {
   const { address, store } = options
@@ -273,25 +418,113 @@ function scopesMatch(
     calls?: readonly { to?: Address.Address | undefined; data?: Hex.Hex | undefined }[] | undefined
   },
 ): boolean {
-  if (!key.scopes) return true
+  const scopes = key.scopes
+  if (typeof scopes === 'undefined') return true
+  if (!Array.isArray(scopes)) return false
   if (!options.calls) return false
   return options.calls.every((call) => {
     if (!call.to) return false
     const callTo = call.to.toLowerCase()
     const callSelector = call.data?.slice(0, 10).toLowerCase()
-    return key.scopes!.some((scope) => {
+    return scopes.some((scope) => {
+      if (!isScope(scope)) return false
       if (scope.address.toLowerCase() !== callTo) return false
-      if (!scope.selector) return true
-      const scopeSelector = (
-        scope.selector.startsWith('0x') && scope.selector.length === 10
-          ? scope.selector
-          : AbiFunction.getSelector(scope.selector)
-      ).toLowerCase()
-      return callSelector === scopeSelector
+      if (!scope.selector) return scope.recipients ? scope.recipients.length === 0 : true
+      const scopeSelector = getSelector(scope.selector)
+      if (!scopeSelector || callSelector !== scopeSelector) return false
+      return recipientsMatch(scope.recipients, call.data)
     })
   })
 }
 
+function matches(
+  key: AccessKey,
+  options: {
+    accessKey?: Address.Address | undefined
+    address: Address.Address
+    calls?: readonly { to?: Address.Address | undefined; data?: Hex.Hex | undefined }[] | undefined
+    chainId: number
+  },
+): boolean {
+  const { accessKey, address, calls, chainId } = options
+  if (key.access.toLowerCase() !== address.toLowerCase()) return false
+  if (key.chainId !== chainId) return false
+  if (accessKey && key.address.toLowerCase() !== accessKey.toLowerCase()) return false
+  return scopesMatch(key, { calls })
+}
+
+function isExpired(expiry: number | undefined, now: number): boolean {
+  return typeof expiry === 'number' && expiry < now
+}
+
+async function getPublishedStatus(
+  client: Client<Transport>,
+  options: { accessKey: Address.Address; address: Address.Address; now: number },
+): Promise<Status> {
+  const { accessKey, address, now } = options
+  try {
+    const metadata = await Actions.accessKey.getMetadata(client, {
+      account: address,
+      accessKey,
+    })
+    if (metadata.isRevoked) return status.missing
+    if (metadata.expiry > 0n && metadata.expiry < BigInt(Math.floor(now))) return status.expired
+    return status.published
+  } catch (error) {
+    if (!(error instanceof Error)) throw error
+    const parsed = ExecutionError.parse(error)
+    if (parsed.errorName === 'KeyNotFound' || parsed.errorName === 'KeyAlreadyRevoked')
+      return status.missing
+    throw error
+  }
+}
+
+function isScope(scope: unknown): scope is NonNullable<AccessKey['scopes']>[number] {
+  if (!scope || typeof scope !== 'object') return false
+  const value = scope as {
+    address?: unknown
+    recipients?: unknown
+    selector?: unknown
+  }
+  if (typeof value.address !== 'string' || !Address.validate(value.address)) return false
+  if (typeof value.selector !== 'undefined' && typeof value.selector !== 'string') return false
+  if (typeof value.recipients !== 'undefined') {
+    if (!Array.isArray(value.recipients)) return false
+    if (value.recipients.some((recipient) => typeof recipient !== 'string')) return false
+    if (value.recipients.some((recipient) => !Address.validate(recipient))) return false
+  }
+  return true
+}
+
+function getSelector(selector: string): string | undefined {
+  try {
+    return (
+      selector.startsWith('0x') && selector.length === 10
+        ? selector
+        : AbiFunction.getSelector(selector)
+    ).toLowerCase()
+  } catch {
+    return undefined
+  }
+}
+
+function recipientsMatch(
+  recipients: readonly Address.Address[] | undefined,
+  data: Hex.Hex | undefined,
+): boolean {
+  if (!recipients || recipients.length === 0) return true
+  const recipient = getCallRecipient(data)
+  if (!recipient) return false
+  return recipients.some((address) => address.toLowerCase() === recipient.toLowerCase())
+}
+
+function getCallRecipient(data: Hex.Hex | undefined): Address.Address | undefined {
+  if (!data || data.length < 74) return undefined
+  const recipient = `0x${data.slice(34, 74)}` as Address.Address
+  if (!Address.validate(recipient)) return undefined
+  return recipient
+}
+
 function shouldRemoveForError(error: unknown): boolean {
   if (!(error instanceof Error)) return false
   const parsed = ExecutionError.parse(error)

package/src/core/Adapter.ts

@@ -311,8 +311,6 @@ export declare namespace authorizeAccessKey {
           recipients?: readonly Address[] | undefined
         }[]
       | undefined
-    /** Pre-computed signature over the key authorization digest (skips a second signing ceremony). */
-    signature?: Hex | undefined
   }
 
   type ReturnType = {

package/src/core/Provider.test-d.ts

@@ -1,6 +1,7 @@
 import type { RpcSchema } from 'ox'
 import { describe, expectTypeOf, test } from 'vp/test'
 
+import * as Provider from './Provider.js'
 import type * as Schema from './Schema.js'
 
 type Result<method extends RpcSchema.MethodNameGeneric<Schema.Ox>> = RpcSchema.ExtractReturnType<
@@ -57,3 +58,17 @@ describe('request', () => {
     expectTypeOf<Result<'wallet_switchEthereumChain'>>().toEqualTypeOf<undefined>()
   })
 })
+
+describe('create options', () => {
+  test('mpp accepts session deposit options', () => {
+    expectTypeOf<NonNullable<Parameters<typeof Provider.create>[0]>>().toMatchTypeOf<{
+      mpp?:
+        | boolean
+        | {
+            deposit?: string | undefined
+            maxDeposit?: string | undefined
+          }
+        | undefined
+    }>()
+  })
+})