accounts 0.3.0 → 0.4.1

package/src/core/Storage.ts

@@ -0,0 +1,213 @@
+import { createStore, del, get, set } from 'idb-keyval'
+import { Json } from 'ox'
+
+import type { MaybePromise } from '../internal/types.js'
+
+/** Pluggable storage adapter for persisting provider state. */
+export type Storage = {
+  getItem: <value>(name: string) => MaybePromise<value | null>
+  setItem: (name: string, value: unknown) => MaybePromise<void>
+  removeItem: (name: string) => MaybePromise<void>
+}
+
+/** Creates a storage adapter from a custom implementation, optionally scoping all keys under a prefix. */
+export function from(storage: Storage, options: from.Options = {}): Storage {
+  const key = options.key ?? 'tempo'
+  const prefix = `${key}.`
+  return {
+    getItem: (name) => storage.getItem(`${prefix}${name}`),
+    setItem: (name, value) => storage.setItem(`${prefix}${name}`, value),
+    removeItem: (name) => storage.removeItem(`${prefix}${name}`),
+  }
+}
+
+export declare namespace from {
+  type Options = {
+    /** Key prefix for all stored items. @default "tempo" */
+    key?: string | undefined
+  }
+}
+
+/**
+ * Combines multiple storage adapters into one. Reads return the first
+ * non-null result; writes propagate to all storages (failures are isolated
+ * via `Promise.allSettled`).
+ */
+export function combine(...storages: readonly Storage[]): Storage {
+  return {
+    async getItem<value>(name: string) {
+      const results = await Promise.allSettled(storages.map((x) => x.getItem<value>(name)))
+      const result = results.find((x) => x.status === 'fulfilled' && x.value !== null)
+      if (result?.status !== 'fulfilled') return null
+      return result.value as value
+    },
+    async removeItem(name) {
+      await Promise.allSettled(storages.map((x) => x.removeItem(name)))
+    },
+    async setItem(name, value) {
+      await Promise.allSettled(storages.map((x) => x.setItem(name, value)))
+    },
+  }
+}
+
+/** Creates a `document.cookie`-backed storage adapter. Uses `SameSite=None; Secure` with a 1-year expiry. Deep objects are flattened into individual cookies to stay within the 4KB-per-cookie browser limit. */
+export function cookie(options: cookie.Options = {}): Storage {
+  function getRaw(name: string): string | undefined {
+    return document.cookie.split('; ').find((x) => x.startsWith(`${name}=`))
+  }
+
+  function setRaw(name: string, value: string) {
+    document.cookie = `${name}=${value};path=/;samesite=None;secure;max-age=31536000`
+  }
+
+  function removeRaw(name: string) {
+    document.cookie = `${name}=;max-age=-1;path=/`
+  }
+
+  function flatten(prefix: string, value: unknown, result: [string, string][] = []) {
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) flatten(`${prefix}[${i}]`, value[i], result)
+      // Store length so we know how many indices to reconstruct.
+      result.push([`${prefix}.__length`, Json.stringify(value.length)])
+    } else if (value !== null && typeof value === 'object') {
+      for (const [k, v] of Object.entries(value as Record<string, unknown>))
+        flatten(`${prefix}.${k}`, v, result)
+    } else result.push([prefix, Json.stringify(value)])
+    return result
+  }
+
+  function unflatten(prefix: string): unknown {
+    // Check for a direct (leaf) cookie first.
+    const direct = getRaw(prefix)
+    if (direct) {
+      try {
+        return Json.parse(direct.substring(prefix.length + 1))
+      } catch {
+        return null
+      }
+    }
+    // Check if this is an array (has a __length cookie).
+    const lengthCookie = getRaw(`${prefix}.__length`)
+    if (lengthCookie) {
+      const length = Json.parse(lengthCookie.substring(`${prefix}.__length`.length + 1)) as number
+      const result: unknown[] = []
+      for (let i = 0; i < length; i++) result.push(unflatten(`${prefix}[${i}]`))
+      return result
+    }
+    // Collect all sub-keys (object children use `.`, array children use `[`).
+    const dotPrefix = `${prefix}.`
+    const bracketPrefix = `${prefix}[`
+    const children = document.cookie
+      .split('; ')
+      .filter((x) => x.startsWith(dotPrefix) || x.startsWith(bracketPrefix))
+    if (children.length === 0) return null
+    const result: Record<string, unknown> = {}
+    for (const entry of children) {
+      const key = entry.substring(dotPrefix.length, entry.indexOf('='))
+      const segment = key.split(/[.[]/)[0]!
+      if (segment === '__length') continue
+      if (!(segment in result)) result[segment] = unflatten(`${dotPrefix}${segment}`)
+    }
+    return result
+  }
+
+  return from(
+    {
+      getItem(name) {
+        return unflatten(name) as any
+      },
+      setItem(name, value) {
+        // Remove existing keys before writing.
+        this.removeItem(name)
+        for (const [k, v] of flatten(name, value)) setRaw(k, v)
+      },
+      removeItem(name) {
+        removeRaw(name)
+        for (const entry of document.cookie.split('; '))
+          if (entry.startsWith(`${name}.`) || entry.startsWith(`${name}[`))
+            removeRaw(entry.substring(0, entry.indexOf('=')))
+      },
+    },
+    options,
+  )
+}
+
+export declare namespace cookie {
+  type Options = from.Options
+}
+
+/** Creates an IndexedDB-backed storage adapter. Stores raw values (no JSON serialization). */
+export function idb(options: idb.Options = {}): Storage {
+  const store = typeof indexedDB !== 'undefined' ? createStore('tempo', 'store') : undefined
+  return from(
+    {
+      async getItem(name) {
+        const value = await get(name, store)
+        if (value === null) return null
+        return value
+      },
+      async setItem(name, value) {
+        await set(name, value, store)
+      },
+      async removeItem(name) {
+        await del(name, store)
+      },
+    },
+    options,
+  )
+}
+
+export declare namespace idb {
+  type Options = from.Options
+}
+
+/** Creates a `localStorage`-backed storage adapter. */
+export function localStorage(options: localStorage.Options = {}): Storage {
+  return from(
+    {
+      getItem(name) {
+        const value = globalThis.localStorage.getItem(name)
+        if (value === null) return null
+        try {
+          return Json.parse(value)
+        } catch {
+          return null
+        }
+      },
+      setItem(name, value) {
+        globalThis.localStorage.setItem(name, Json.stringify(value))
+      },
+      removeItem(name) {
+        globalThis.localStorage.removeItem(name)
+      },
+    },
+    options,
+  )
+}
+
+export declare namespace localStorage {
+  type Options = from.Options
+}
+
+/** Creates an in-memory storage adapter. Useful for SSR and tests. */
+export function memory(options: memory.Options = {}): Storage {
+  const store = new Map<string, unknown>()
+  return from(
+    {
+      getItem(name) {
+        return (store.get(name) as any) ?? null
+      },
+      setItem(name, value) {
+        store.set(name, value)
+      },
+      removeItem(name) {
+        store.delete(name)
+      },
+    },
+    options,
+  )
+}
+
+export declare namespace memory {
+  type Options = from.Options
+}

package/src/core/Store.test.ts

@@ -0,0 +1,287 @@
+import { describe, expect, test } from 'vp/test'
+
+import * as Storage from './Storage.js'
+import * as Store from './Store.js'
+
+describe('create', () => {
+  test('default', () => {
+    const store = Store.create({ chainId: 123 })
+    expect(store.getState()).toMatchInlineSnapshot(`
+      {
+        "accessKeys": [],
+        "accounts": [],
+        "activeAccount": 0,
+        "chainId": 123,
+        "requestQueue": [],
+      }
+    `)
+  })
+
+  test('behavior: setState updates state', () => {
+    const store = Store.create({ chainId: 123 })
+
+    store.setState({
+      accounts: [{ address: '0x0000000000000000000000000000000000000001' }],
+    })
+
+    expect(store.getState()).toMatchInlineSnapshot(`
+      {
+        "accessKeys": [],
+        "accounts": [
+          {
+            "address": "0x0000000000000000000000000000000000000001",
+          },
+        ],
+        "activeAccount": 0,
+        "chainId": 123,
+        "requestQueue": [],
+      }
+    `)
+  })
+
+  test('behavior: subscribe fires on state change', () => {
+    const store = Store.create({ chainId: 123 })
+    const events: number[] = []
+
+    store.subscribe((state) => events.push(state.chainId))
+    store.setState({ chainId: 456 })
+
+    expect(events).toMatchInlineSnapshot(`
+      [
+        456,
+      ]
+    `)
+  })
+
+  test('behavior: subscribeWithSelector for granular subscriptions', () => {
+    const store = Store.create({ chainId: 123 })
+    const chainIds: number[] = []
+
+    store.subscribe(
+      (state) => state.chainId,
+      (chainId) => chainIds.push(chainId),
+    )
+
+    store.setState({ chainId: 456 })
+    expect(chainIds).toMatchInlineSnapshot(`
+      [
+        456,
+      ]
+    `)
+
+    // Changing accounts does NOT trigger the chainId subscription
+    store.setState({
+      accounts: [{ address: '0x0000000000000000000000000000000000000001' }],
+    })
+    expect(chainIds).toMatchInlineSnapshot(`
+      [
+        456,
+      ]
+    `)
+  })
+})
+
+describe('persistence', () => {
+  test('default: persists accounts, activeAccount, and chainId to storage', async () => {
+    const storage = Storage.memory()
+    const store = Store.create({ chainId: 123, storage })
+    await Store.waitForHydration(store)
+
+    store.setState({
+      accounts: [{ address: '0x0000000000000000000000000000000000000001' }],
+      activeAccount: 1,
+      chainId: 456,
+    })
+
+    const raw = storage.getItem('store') as any
+    expect(raw.state).toMatchInlineSnapshot(`
+      {
+        "accessKeys": [],
+        "accounts": [
+          {
+            "address": "0x0000000000000000000000000000000000000001",
+          },
+        ],
+        "activeAccount": 1,
+        "chainId": 456,
+      }
+    `)
+  })
+
+  test('behavior: hydrates from storage', async () => {
+    const storage = Storage.memory()
+
+    const store1 = Store.create({ chainId: 123, storage })
+    await Store.waitForHydration(store1)
+
+    store1.setState({
+      accounts: [{ address: '0x0000000000000000000000000000000000000001' }],
+      activeAccount: 0,
+      chainId: 456,
+    })
+
+    const store2 = Store.create({ chainId: 123, storage })
+    await Store.waitForHydration(store2)
+
+    expect(store2.getState()).toMatchInlineSnapshot(`
+      {
+        "accessKeys": [],
+        "accounts": [
+          {
+            "address": "0x0000000000000000000000000000000000000001",
+          },
+        ],
+        "activeAccount": 0,
+        "chainId": 456,
+        "requestQueue": [],
+      }
+    `)
+  })
+
+  test('behavior: persists accessKeys to storage', async () => {
+    const storage = Storage.memory()
+    const store = Store.create({ chainId: 123, storage })
+    await Store.waitForHydration(store)
+
+    store.setState({
+      accounts: [{ address: '0x0000000000000000000000000000000000000001' }],
+      accessKeys: [
+        {
+          address: '0x0000000000000000000000000000000000000099',
+          access: '0x0000000000000000000000000000000000000001',
+          keyType: 'webCrypto',
+          keyPair: {} as any,
+        },
+      ],
+    })
+
+    const raw = storage.getItem('store') as any
+    expect(raw.state.accessKeys).toMatchInlineSnapshot(`
+      [
+        {
+          "access": "0x0000000000000000000000000000000000000001",
+          "address": "0x0000000000000000000000000000000000000099",
+          "keyPair": {},
+          "keyType": "webCrypto",
+        },
+      ]
+    `)
+  })
+
+  test('behavior: hydrates accessKeys from storage', async () => {
+    const storage = Storage.memory()
+
+    const store1 = Store.create({ chainId: 123, storage })
+    await Store.waitForHydration(store1)
+
+    store1.setState({
+      accounts: [{ address: '0x0000000000000000000000000000000000000001' }],
+      accessKeys: [
+        {
+          address: '0x0000000000000000000000000000000000000099',
+          access: '0x0000000000000000000000000000000000000001',
+          expiry: 9999999999,
+          limits: [{ token: '0x0000000000000000000000000000000000000abc', limit: 500n }],
+          keyType: 'webCrypto',
+          keyPair: {} as any,
+        },
+      ],
+    })
+
+    const store2 = Store.create({ chainId: 123, storage })
+    await Store.waitForHydration(store2)
+
+    expect(store2.getState().accessKeys).toMatchInlineSnapshot(`
+      [
+        {
+          "access": "0x0000000000000000000000000000000000000001",
+          "address": "0x0000000000000000000000000000000000000099",
+          "expiry": 9999999999,
+          "keyPair": {},
+          "keyType": "webCrypto",
+          "limits": [
+            {
+              "limit": 500n,
+              "token": "0x0000000000000000000000000000000000000abc",
+            },
+          ],
+        },
+      ]
+    `)
+  })
+
+  test('behavior: disconnect clears accessKeys', async () => {
+    const storage = Storage.memory()
+    const store = Store.create({ chainId: 123, storage })
+    await Store.waitForHydration(store)
+
+    store.setState({
+      accounts: [{ address: '0x0000000000000000000000000000000000000001' }],
+      accessKeys: [
+        {
+          address: '0x0000000000000000000000000000000000000099',
+          access: '0x0000000000000000000000000000000000000001',
+          keyType: 'webCrypto',
+          keyPair: {} as any,
+        },
+      ],
+    })
+
+    store.setState({ accessKeys: [], accounts: [], activeAccount: 0 })
+
+    expect(store.getState().accessKeys).toMatchInlineSnapshot(`[]`)
+    expect(store.getState().accounts).toMatchInlineSnapshot(`[]`)
+  })
+
+  test('behavior: custom storage key', async () => {
+    const storage = Storage.memory({ key: 'custom' })
+    const store = Store.create({ chainId: 123, storage })
+    await Store.waitForHydration(store)
+
+    store.setState({ chainId: 789 })
+
+    const raw = storage.getItem('store') as any
+    expect(raw.state.chainId).toMatchInlineSnapshot(`789`)
+  })
+})
+
+describe('waitForHydration', () => {
+  test('default: resolves after hydration', async () => {
+    const storage = Storage.memory()
+
+    storage.setItem('store', {
+      state: {
+        accounts: [{ address: '0x0000000000000000000000000000000000000001' }],
+        activeAccount: 0,
+        chainId: 789,
+      },
+      version: 0,
+    })
+
+    const store = Store.create({ chainId: 123, storage })
+    await Store.waitForHydration(store)
+
+    expect(store.getState()).toMatchInlineSnapshot(`
+      {
+        "accessKeys": [],
+        "accounts": [
+          {
+            "address": "0x0000000000000000000000000000000000000001",
+          },
+        ],
+        "activeAccount": 0,
+        "chainId": 789,
+        "requestQueue": [],
+      }
+    `)
+  })
+
+  test('behavior: resolves multiple times', async () => {
+    const store = Store.create({ chainId: 123 })
+
+    await Store.waitForHydration(store)
+    await Store.waitForHydration(store)
+
+    expect(store.getState().chainId).toMatchInlineSnapshot(`123`)
+  })
+})

package/src/core/Store.ts

@@ -0,0 +1,129 @@
+import type { RpcRequest, RpcResponse } from 'ox'
+import type { Mutate, StoreApi } from 'zustand'
+import { persist } from 'zustand/middleware'
+import { subscribeWithSelector } from 'zustand/middleware'
+import { createStore } from 'zustand/vanilla'
+
+import type { OneOf } from '../internal/types.js'
+import type { AccessKey, Store as Account } from './Account.js'
+import * as Storage from './Storage.js'
+
+export type { AccessKey, Account }
+
+/** Reactive state for the provider. */
+export type State = {
+  /** Stored access keys. */
+  accessKeys: readonly AccessKey[]
+  /** Connected accounts. */
+  accounts: readonly Account[]
+  /** Index of the active account. */
+  activeAccount: number
+  /** Active chain ID. */
+  chainId: number
+  /** Queued RPC requests pending resolution by the dialog. */
+  requestQueue: readonly QueuedRequest[]
+}
+
+/** Zustand vanilla store with `subscribeWithSelector` and `persist` middleware. */
+export type Store = Mutate<
+  StoreApi<State>,
+  [['zustand/subscribeWithSelector', never], ['zustand/persist', State]]
+>
+
+/** Options for {@link create}. */
+export type Options = {
+  /** Initial chain ID. */
+  chainId: number
+  /** Whether to persist credentials and access keys to storage. When `false`, only account addresses are persisted. @default true */
+  persistCredentials?: boolean | undefined
+  /** Storage adapter for persistence. */
+  storage?: Storage.Storage | undefined
+}
+
+/** A queued JSON-RPC request tracked in the store. */
+export type QueuedRequest<result = unknown> = OneOf<
+  | {
+      request: RpcRequest.RpcRequest
+      status: 'pending'
+    }
+  | {
+      request: RpcRequest.RpcRequest
+      result: result
+      status: 'success'
+    }
+  | {
+      request: RpcRequest.RpcRequest
+      error: RpcResponse.ErrorObject
+      status: 'error'
+    }
+>
+
+/**
+ * Creates a Zustand vanilla store with `subscribeWithSelector` and `persist` middleware.
+ */
+export function create(options: Options): Store {
+  const {
+    chainId,
+    persistCredentials = true,
+    storage = typeof window !== 'undefined'
+      ? Storage.idb({ key: 'tempo' })
+      : Storage.memory({ key: 'tempo' }),
+  } = options
+
+  return createStore(
+    subscribeWithSelector(
+      persist<State>(
+        () => ({
+          accessKeys: [],
+          accounts: [],
+          activeAccount: 0,
+          chainId,
+          requestQueue: [],
+        }),
+        {
+          merge(persisted, current) {
+            const state = persisted as State
+            return {
+              ...state,
+              ...current,
+              // Preserve in-memory credentials when persisted accounts only have addresses.
+              accounts:
+                state.accounts?.map((persisted) => {
+                  const account = current.accounts.find(
+                    (a) => a.address.toLowerCase() === persisted.address.toLowerCase(),
+                  )
+                  return account ?? persisted
+                }) ?? current.accounts,
+              accessKeys: state.accessKeys ?? current.accessKeys,
+              chainId: state.chainId ?? current.chainId,
+            }
+          },
+          name: 'store',
+          partialize: (state) =>
+            ({
+              accounts: state.accounts,
+              activeAccount: state.activeAccount,
+              ...(persistCredentials ? { accessKeys: state.accessKeys } : {}),
+              chainId: state.chainId,
+            }) as unknown as State,
+          storage,
+          version: 0,
+        },
+      ),
+    ),
+  )
+}
+
+/**
+ * Waits for the store to finish hydrating from storage.
+ *
+ * Returns immediately if the store has already hydrated. Otherwise, waits
+ * for the `onFinishHydration` callback with a 100ms safety timeout fallback.
+ */
+export async function waitForHydration(store: Store): Promise<void> {
+  if (store.persist.hasHydrated()) return
+  await new Promise<void>((resolve) => {
+    store.persist.onFinishHydration(() => resolve())
+    setTimeout(() => resolve(), 100)
+  })
+}

package/src/core/adapters/dangerous_secp256k1.ts

@@ -0,0 +1,53 @@
+import { Account, Secp256k1 } from 'viem/tempo'
+
+import * as Adapter from '../Adapter.js'
+import { local } from './local.js'
+
+/**
+ * Creates a secp256k1 adapter that generates random private keys and persists them to storage.
+ *
+ * ⚠️ **Dangerous**: Private keys are stored in plaintext via the provider's storage adapter
+ * (e.g. localStorage, cookies). Use only for development, testing, or when the threat model allows it.
+ *
+ * Wraps the {@link local} adapter with automatic key generation.
+ *
+ * @example
+ * ```ts
+ * import { dangerous_secp256k1, Provider } from 'accounts'
+ *
+ * const provider = Provider.create({
+ *   adapter: dangerous_secp256k1(),
+ * })
+ * ```
+ */
+export function dangerous_secp256k1(options: dangerous_secp256k1.Options = {}): Adapter.Adapter {
+  const { icon, name, rdns } = options
+
+  return Adapter.define({ icon, name, rdns }, (config) => {
+    const { store } = config
+
+    return local({
+      async createAccount() {
+        const privateKey = Secp256k1.randomPrivateKey()
+        const account = Account.fromSecp256k1(privateKey)
+        return {
+          accounts: [{ address: account.address, keyType: 'secp256k1' as const, privateKey }],
+        }
+      },
+      async loadAccounts() {
+        return { accounts: [...store.getState().accounts] }
+      },
+    })(config)
+  })
+}
+
+export declare namespace dangerous_secp256k1 {
+  type Options = {
+    /** Data URI of the provider icon. @default Black 1×1 SVG. */
+    icon?: `data:image/${string}` | undefined
+    /** Display name of the provider (e.g. `"My Wallet"`). @default "Injected Wallet" */
+    name?: string | undefined
+    /** Reverse DNS identifier. @default `com.{lowercase name}` */
+    rdns?: string | undefined
+  }
+}