tapimo 0.15.1 → 0.18.1

package/src/internal/CliAuth.ts

@@ -0,0 +1,319 @@
+import { Base64, Bytes, Hash, Hex } from 'ox'
+import * as z from 'zod/mini'
+
+import * as Id from './Id.js'
+import type * as Store from './Store.js'
+import * as Ttl from './Ttl.js'
+
+/** Lifetime of a pending CLI authorization before the CLI must restart sign-in. */
+export const authorizationTtl = Ttl.minutes(10)
+
+/** Seconds a CLI waits between token polls. */
+export const pollInterval = 5
+
+/** Default lifetime of a CLI session. */
+export const sessionTtl = Ttl.days(30)
+
+/** API scopes selected by default when approving a CLI sign-in. */
+export const defaultScopes = ['data:read', 'routes:read', 'routes:write', 'rpc-relay:read']
+
+// Consonants only: codes never spell words and never mix up 0/O or 1/I.
+const codeAlphabet = 'BCDFGHJKLMNPQRSTVWXZ'
+const codeLength = 8
+const tokenPrefix = 'tempo:cli:'
+
+/** Storage schemas for pending authorizations and minted sessions. */
+export namespace schema {
+  /** Client details the CLI reports so the approver can recognize the request. */
+  export const Client = z.object({
+    device: z.optional(z.string().check(z.minLength(1), z.maxLength(100))),
+    name: z.optional(z.string().check(z.minLength(1), z.maxLength(100))),
+  })
+
+  /** A PKCE S256 code challenge: base64url SHA-256, unpadded. */
+  export const CodeChallenge = z.string().check(z.regex(/^[A-Za-z0-9_-]{43}$/))
+
+  /** A PKCE code verifier (RFC 7636 section 4.1). */
+  export const CodeVerifier = z.string().check(z.regex(/^[A-Za-z0-9._~-]{43,128}$/))
+
+  /** A pending, approved, or denied CLI sign-in request. */
+  export const Authorization = z.object({
+    approvedAt: z.optional(z.string()),
+    client: Client,
+    code: z.string(),
+    codeChallenge: CodeChallenge,
+    createdAt: z.string(),
+    expiresAt: z.string(),
+    ip: z.optional(z.string()),
+    scopes: z.optional(z.array(z.string())),
+    status: z.enum(['approved', 'denied', 'pending']),
+    userId: z.optional(z.string()),
+  })
+
+  /** A minted CLI session, keyed by its token hash. */
+  export const Session = z.object({
+    client: Client,
+    createdAt: z.string(),
+    expiresAt: z.string(),
+    id: z.string(),
+    scopes: z.optional(z.array(z.string())),
+    userId: z.string(),
+  })
+}
+
+/** Client details reported by the CLI. */
+export type Client = z.output<typeof schema.Client>
+
+/** A stored CLI sign-in request. */
+export type Authorization = z.output<typeof schema.Authorization>
+
+/** A stored CLI session. */
+export type Session = z.output<typeof schema.Session>
+
+/** Generates a human-typeable authorization code (8 consonants, stored without a separator). */
+export function generateCode(): string {
+  let code = ''
+  while (code.length < codeLength)
+    for (const byte of Bytes.random(codeLength)) {
+      // Rejection sampling keeps every letter equally likely (240 = 12 * 20).
+      if (byte >= 240 || code.length === codeLength) continue
+      code += codeAlphabet[byte % codeAlphabet.length]
+    }
+  return code
+}
+
+/** Normalizes user- or URL-supplied code input (case, dashes, spaces), or `undefined` when malformed. */
+export function normalizeCode(value: string): string | undefined {
+  const code = value.toUpperCase().replace(/[\s-]/g, '')
+  if (code.length !== codeLength) return undefined
+  for (const character of code) if (!codeAlphabet.includes(character)) return undefined
+  return code
+}
+
+/** Formats a stored code for display (`BCDF-GHJK`). */
+export function formatCode(code: string): string {
+  return `${code.slice(0, 4)}-${code.slice(4)}`
+}
+
+/** Derives the PKCE S256 challenge for a code verifier. */
+export function challengeFrom(verifier: string): string {
+  return Base64.fromBytes(Hash.sha256(Bytes.fromString(verifier)), { pad: false, url: true })
+}
+
+/** Generates a CLI session token (`tempo:cli:` + 64 lowercase hex chars). */
+export function generateToken(): string {
+  return `${tokenPrefix}${Hex.random(32).slice(2)}`
+}
+
+/** Whether a credential is a CLI session token rather than an API key. */
+export function isToken(value: string): boolean {
+  return value.startsWith(tokenPrefix)
+}
+
+/** Masks CLI session tokens embedded in text so they never reach logs. */
+export function redact(text: string): string {
+  return text.replace(/tempo:cli:[a-f0-9]{64}/g, `${tokenPrefix}…`)
+}
+
+/** Stores a new pending authorization for a CLI that holds the matching code verifier. */
+export async function authorize(store: Store.State, options: authorize.Options) {
+  const { client, codeChallenge, ip } = options
+  const now = Date.now()
+  // A collision in a 20^8 space is vanishingly rare; skip occupied codes instead of overwriting them.
+  const code = await (async () => {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const candidate = generateCode()
+      if ((await store.get(authorizationKey(candidate))) === null) return candidate
+    }
+    throw new Error('Could not allocate a CLI authorization code')
+  })()
+  const authorization: Authorization = {
+    client,
+    code,
+    codeChallenge,
+    createdAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + authorizationTtl).toISOString(),
+    ...(ip ? { ip } : {}),
+    status: 'pending',
+  }
+  await store.put(authorizationKey(code), JSON.stringify(authorization), { ttl: authorizationTtl })
+  return authorization
+}
+
+export declare namespace authorize {
+  /** Options for {@link authorize}. */
+  type Options = {
+    /** Client details shown to the approver. */
+    client: Client
+    /** PKCE S256 challenge derived from the CLI's code verifier. */
+    codeChallenge: string
+    /** Caller IP address shown to the approver, when known. */
+    ip?: string | undefined
+  }
+}
+
+/** Reads an unexpired authorization by its normalized code. */
+export async function getAuthorization(store: Store.State, code: string) {
+  const value = await store.get(authorizationKey(code))
+  if (value === null) return undefined
+  const authorization = schema.Authorization.parse(JSON.parse(value))
+  // KV expiry is eventual; the stored deadline is authoritative.
+  if (Date.parse(authorization.expiresAt) <= Date.now()) return undefined
+  return authorization
+}
+
+/** Approves a pending authorization for a user; approving it again as the same user is a no-op. */
+export async function approve(store: Store.State, options: approve.Options) {
+  const { code, scopes = defaultScopes, userId } = options
+  const authorization = await getAuthorization(store, code)
+  if (!authorization) return { status: 'not_found' } as const
+  if (authorization.status === 'approved' && authorization.userId === userId)
+    return { authorization, status: 'approved' } as const
+  if (authorization.status !== 'pending') return { status: 'conflict' } as const
+  const approved: Authorization = {
+    ...authorization,
+    approvedAt: new Date().toISOString(),
+    scopes: [...scopes],
+    status: 'approved',
+    userId,
+  }
+  await write(store, approved)
+  return { authorization: approved, status: 'approved' } as const
+}
+
+export declare namespace approve {
+  /** Options for {@link approve}. */
+  type Options = {
+    /** Normalized authorization code. */
+    code: string
+    /** API scopes approved for this device. Defaults to {@link defaultScopes}. */
+    scopes?: readonly string[] | undefined
+    /** User the CLI session will act as. */
+    userId: string
+  }
+}
+
+/** Denies a pending authorization so the waiting CLI stops polling. */
+export async function deny(store: Store.State, code: string) {
+  const authorization = await getAuthorization(store, code)
+  if (!authorization) return { status: 'not_found' } as const
+  if (authorization.status === 'denied') return { status: 'denied' } as const
+  if (authorization.status !== 'pending') return { status: 'conflict' } as const
+  await write(store, { ...authorization, status: 'denied' })
+  return { status: 'denied' } as const
+}
+
+/**
+ * Exchanges an authorization for a CLI session once approved. Returns `undefined`
+ * when the code is unknown, expired, or the verifier does not match, so callers
+ * cannot probe for live codes.
+ */
+export async function redeem(store: Store.State, options: redeem.Options) {
+  const { code, codeVerifier, ttl = sessionTtl } = options
+  const authorization = await getAuthorization(store, code)
+  if (!authorization) return undefined
+  if (!timingSafeEqual(challengeFrom(codeVerifier), authorization.codeChallenge)) return undefined
+  if (authorization.status === 'pending') return { status: 'pending' } as const
+  // Settled authorizations are single use; KV lacks compare-and-delete, so a
+  // concurrent redeem by the same verifier holder may mint a second session.
+  const consumed = await store.delete(authorizationKey(code)).then(
+    () => true,
+    () => false,
+  )
+  // KV rejects a second write to a key within a second (a poll right after the decision); the next poll retries.
+  if (!consumed) return { status: 'pending' } as const
+  if (authorization.status === 'denied' || !authorization.userId)
+    return { status: 'denied' } as const
+  const { session, token } = await mint(store, {
+    client: authorization.client,
+    scopes: authorization.scopes ?? [],
+    ttl,
+    userId: authorization.userId,
+  })
+  return { session, status: 'approved', token } as const
+}
+
+export declare namespace redeem {
+  /** Options for {@link redeem}. */
+  type Options = {
+    /** Normalized authorization code. */
+    code: string
+    /** PKCE code verifier whose S256 challenge was stored at authorization. */
+    codeVerifier: string
+    /** Session lifetime in milliseconds. Defaults to {@link sessionTtl}. */
+    ttl?: number | undefined
+  }
+}
+
+/** Mints a CLI session for a user, returning the plaintext token once. */
+export async function mint(store: Store.State, options: mint.Options) {
+  const { client, scopes, ttl = sessionTtl, userId } = options
+  const now = Date.now()
+  const token = generateToken()
+  const session: Session = {
+    client,
+    createdAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + ttl).toISOString(),
+    id: Id.generate('cli'),
+    ...(scopes ? { scopes: [...scopes] } : {}),
+    userId,
+  }
+  await store.put(sessionKey(token), JSON.stringify(session), { ttl })
+  return { session, token }
+}
+
+export declare namespace mint {
+  /** Options for {@link mint}. */
+  type Options = {
+    /** Client details recorded on the session. */
+    client: Client
+    /** API scopes approved for this device; absent on legacy sessions. */
+    scopes?: readonly string[] | undefined
+    /** Session lifetime in milliseconds. Defaults to {@link sessionTtl}. */
+    ttl?: number | undefined
+    /** User the session acts as. */
+    userId: string
+  }
+}
+
+/** Resolves an unexpired CLI session by its plaintext token. */
+export async function resolve(store: Store.State, token: string) {
+  if (!isToken(token)) return undefined
+  const value = await store.get(sessionKey(token))
+  if (value === null) return undefined
+  const session = schema.Session.parse(JSON.parse(value))
+  if (Date.parse(session.expiresAt) <= Date.now()) return undefined
+  return session
+}
+
+/** Revokes a CLI session by its plaintext token. */
+export async function revoke(store: Store.State, token: string) {
+  if (!isToken(token)) return
+  await store.delete(sessionKey(token))
+}
+
+function authorizationKey(code: string) {
+  return `cli:authorization:${code}`
+}
+
+function sessionKey(token: string) {
+  // Tokens are stored by hash so a KV read never exposes a usable credential.
+  return `cli:session:${Hash.sha256(Hex.fromString(token)).slice(2)}`
+}
+
+// Rewrites an authorization with its remaining lifetime. Cloudflare KV rejects
+// TTLs under a minute, so storage may outlive `expiresAt`, which reads enforce.
+async function write(store: Store.State, authorization: Authorization) {
+  const ttl = Date.parse(authorization.expiresAt) - Date.now()
+  await store.put(authorizationKey(authorization.code), JSON.stringify(authorization), {
+    ttl: Math.max(ttl, Ttl.minutes(1)),
+  })
+}
+
+function timingSafeEqual(left: string, right: string): boolean {
+  if (left.length !== right.length) return false
+  let difference = 0
+  for (let index = 0; index < left.length; index++)
+    difference |= left.charCodeAt(index) ^ right.charCodeAt(index)
+  return difference === 0
+}

package/src/internal/EarnSharePrices.test.ts

@@ -3,6 +3,8 @@ import {
   ContractFunctionExecutionError,
   ContractFunctionRevertedError,
   ContractFunctionZeroDataError,
+  RpcRequestError,
+  getContractError,
   parseAbi,
 } from 'viem'
 
@@ -36,6 +38,29 @@ describe('timestamps', () => {
 })
 
 describe('isUnavailable', () => {
+  test.each([
+    { code: -32000, message: 'historical state is not available', unavailable: true },
+    { code: -32001, message: 'historical state is not available', unavailable: true },
+    { code: -32000, message: 'historical state unavailable', unavailable: true },
+    { code: -32000, message: 'state at block 123 has been pruned', unavailable: true },
+    { code: -32000, message: 'missing trie node', unavailable: true },
+    { code: -32001, message: 'no state available for block 123', unavailable: true },
+    { code: -32000, message: 'RPC request timed out', unavailable: false },
+    { code: -32001, message: 'header not found', unavailable: false },
+    { code: -32000, message: 'rate limit exceeded', unavailable: false },
+    { code: 429, message: 'historical state unavailable', unavailable: false },
+  ])('classifies RPC $code: $message', ({ code, message, unavailable }) => {
+    const error = getContractError(
+      new RpcRequestError({
+        body: { method: 'eth_call', params: [] },
+        error: { code, message },
+        url: 'https://rpc.example',
+      }),
+      { abi, args: [1n], functionName: 'previewRedeem' },
+    )
+    expect(EarnSharePrices.isUnavailable(error)).toBe(unavailable)
+  })
+
   test('accepts only contract execution failures that prove a quote is unavailable', () => {
     expect([
       EarnSharePrices.isUnavailable(

package/src/internal/EarnSharePrices.ts

@@ -3,6 +3,7 @@ import {
   ContractFunctionExecutionError,
   ContractFunctionRevertedError,
   ContractFunctionZeroDataError,
+  RpcRequestError,
 } from 'viem'
 
 import type * as Tidx from './Tidx.js'
@@ -109,14 +110,20 @@ export declare namespace timestamps {
   }
 }
 
-/** Returns whether a historical quote is unavailable from contract execution. */
+/** Returns whether contract execution or missing historical state makes a quote unavailable. */
 export function isUnavailable(error: unknown): boolean {
   if (!(error instanceof ContractFunctionExecutionError)) return false
   return Boolean(
     error.walk(
       (cause) =>
         cause instanceof ContractFunctionRevertedError ||
-        cause instanceof ContractFunctionZeroDataError,
+        cause instanceof ContractFunctionZeroDataError ||
+        // These RPC codes also cover transient failures; require explicit missing-state evidence.
+        (cause instanceof RpcRequestError &&
+          (cause.code === -32000 || cause.code === -32001) &&
+          /\b(?:historical state|state at block)\b.*\b(?:not available|unavailable|pruned)\b|\bmissing trie node\b|\bno state available for block\b/i.test(
+            cause.details ?? '',
+          )),
     ),
   )
 }

package/src/internal/EarnVaults.test.ts

@@ -6,6 +6,7 @@ import * as Runtime from '../../test/runtime.js'
 import * as TestViem from '../../test/Viem.js'
 import * as Zones from '../apps/Zones.js'
 import * as EarnVaults from './EarnVaults.js'
+import * as Store from './Store.js'
 import * as Viem from './Viem.js'
 
 const vaultAddress = '0xF4ae63687d6753A78e7f551d2EDA1D0d31A5ea3A'
@@ -227,6 +228,72 @@ describe('resolve', () => {
   )
 })
 
+describe('resolve with hints', () => {
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'reuses cached vault facts and replaces them when the engine no longer matches',
+    async () => {
+      const hints = Store.memory()
+      const resolve = () =>
+        EarnVaults.resolve({
+          getClient: Viem.createGetClient({ defaultChainId: tempoTestnet.id, rpc: TestViem.rpc }),
+          hints,
+          input: { chainId: tempoTestnet.id, vaultAddress },
+          zones: [],
+        })
+      const facts = (discovery: EarnVaults.Discovery) => ({
+        access: discovery.access,
+        assetToken: discovery.assetToken,
+        capabilities: discovery.capabilities,
+        engine: discovery.engine,
+        shareToken: discovery.shareToken,
+      })
+
+      // A full read stores one hint; a hinted miss must describe the same vault.
+      const full = await resolve()
+      const [key] = (await hints.list({ prefix: 'earn-vault:hint:' })).keys.map(({ name }) => name)
+      expect(key).toBeDefined()
+      if (!key) return
+      expect(facts(await resolve())).toStrictEqual(facts(full))
+
+      // Hints are read and written the way the resolver does, through memoize.
+      type StoredHint = { engine: string }
+      const cached = () =>
+        Store.memoize<StoredHint>(async () => ({ engine: '' }), { key, store: hints, ttl: 60_000 })
+      const replace = async (hint: StoredHint) => {
+        await hints.delete(key)
+        await Store.memoize(async () => hint, { key, store: hints, ttl: 60_000 })
+      }
+
+      // A hint naming another engine falls back to a full read and is replaced.
+      await replace({ ...(await cached()), engine: `0x${'11'.repeat(20)}` })
+      expect(facts(await resolve())).toStrictEqual(facts(full))
+      expect((await cached()).engine.toLowerCase()).toBe(full.engine.address)
+
+      // A corrupt hint reads as a miss.
+      await hints.put(key, 'not json')
+      expect(facts(await resolve())).toStrictEqual(facts(full))
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'writes no hint when the request asks not to store',
+    async () => {
+      const hints = Store.memory()
+      await EarnVaults.resolve({
+        getClient: Viem.createGetClient({ defaultChainId: tempoTestnet.id, rpc: TestViem.rpc }),
+        hints: Store.withRequest(hints, {
+          header: (name) => (name === 'cache-control' ? 'no-store' : undefined),
+        }),
+        input: { chainId: tempoTestnet.id, vaultAddress },
+        zones: [],
+      })
+      expect((await hints.list({ prefix: 'earn-vault:hint:' })).keys).toStrictEqual([])
+    },
+    60_000,
+  )
+})
+
 describe('resolveZoneRoutes', () => {
   test.runIf(Runtime.get().mode === 'testnet')(
     'verifies immutable router bindings and derives private tokens',