mppx 0.6.19 → 0.6.20

package/src/tempo/client/Subscription.test.ts

@@ -0,0 +1,131 @@
+import { Challenge, Credential } from 'mppx'
+import { KeyAuthorization } from 'ox/tempo'
+import { privateKeyToAccount } from 'viem/accounts'
+import { describe, expect, test } from 'vp/test'
+
+import * as Methods from '../Methods.js'
+import { signSubscriptionKeyAuthorization } from '../subscription/KeyAuthorization.js'
+import type { SubscriptionAccessKey } from '../subscription/Types.js'
+import { subscription } from './Subscription.js'
+
+const chainId = 4217
+const currency = '0x20c0000000000000000000000000000000000001'
+const recipient = '0x1234567890abcdef1234567890abcdef12345678'
+const selectedAccount = privateKeyToAccount(
+  '0x0000000000000000000000000000000000000000000000000000000000000001',
+)
+const accessAccount = privateKeyToAccount(
+  '0x0000000000000000000000000000000000000000000000000000000000000002',
+)
+const otherRootAccount = privateKeyToAccount(
+  '0x0000000000000000000000000000000000000000000000000000000000000003',
+)
+const accessKey = {
+  accessKeyAddress: accessAccount.address,
+  keyType: 'secp256k1',
+} as const satisfies SubscriptionAccessKey
+
+type SubscriptionRequest = ReturnType<typeof Methods.subscription.schema.request.parse>
+
+function secondsFromNow(milliseconds: number) {
+  return new Date(Math.ceil((Date.now() + milliseconds) / 1_000) * 1_000).toISOString()
+}
+
+function createChallenge(
+  overrides: Partial<Parameters<typeof Methods.subscription.schema.request.parse>[0]> = {},
+): Challenge.Challenge<SubscriptionRequest, 'subscription', 'tempo'> {
+  const request = Methods.subscription.schema.request.parse({
+    accessKey,
+    amount: '1',
+    chainId,
+    currency,
+    decimals: 6,
+    periodCount: '1',
+    periodUnit: 'day',
+    recipient,
+    subscriptionExpires: secondsFromNow(86_400_000),
+    ...overrides,
+  })
+  return Challenge.from({
+    id: 'test-challenge-id',
+    intent: 'subscription',
+    method: 'tempo',
+    realm: 'api.example.com',
+    request,
+  }) as Challenge.Challenge<SubscriptionRequest, 'subscription', 'tempo'>
+}
+
+describe('tempo.subscription client', () => {
+  test('uses Tempo testnet as the default subscription chain', async () => {
+    const challenge = createChallenge({ chainId: undefined })
+    const method = subscription({
+      account: selectedAccount,
+    })
+
+    const credential = Credential.deserialize(
+      await method.createCredential({ challenge, context: {} }),
+    )
+    const payload = Methods.subscription.schema.credential.payload.parse(credential.payload)
+    const authorization = KeyAuthorization.deserialize(payload.signature as `0x${string}`)
+
+    expect(authorization.chainId).toBe(42431n)
+  })
+
+  test('can reject subscription expiry from custom request validation', async () => {
+    const challenge = createChallenge({
+      subscriptionExpires: secondsFromNow(2 * 86_400_000),
+    })
+    const method = subscription({
+      account: selectedAccount,
+      validateRequest: (request) => {
+        const maxExpiry = Date.now() + 86_400_000
+        if (new Date(request.subscriptionExpires).getTime() > maxExpiry) {
+          throw new Error('subscription expiry too late')
+        }
+      },
+    })
+
+    await expect(method.createCredential({ challenge, context: {} })).rejects.toThrow(
+      'subscription expiry too late',
+    )
+  })
+
+  test('runs custom request validation before authorizing the access key', async () => {
+    const challenge = createChallenge()
+    const method = subscription({
+      account: selectedAccount,
+      validateRequest: () => {
+        throw new Error('unexpected subscription request')
+      },
+    })
+
+    await expect(method.createCredential({ challenge, context: {} })).rejects.toThrow(
+      'unexpected subscription request',
+    )
+  })
+
+  test('rejects key authorizations signed by a different account', async () => {
+    const challenge = createChallenge()
+    const keyAuthorization = await signSubscriptionKeyAuthorization({
+      accessKey,
+      account: otherRootAccount,
+      chainId,
+      request: challenge.request,
+    })
+    if (!keyAuthorization) throw new Error('expected key authorization')
+
+    const method = subscription({
+      account: selectedAccount.address,
+      getClient: async () =>
+        ({
+          request: async () => ({
+            keyAuthorization: KeyAuthorization.toRpc(keyAuthorization),
+          }),
+        }) as never,
+    })
+
+    await expect(method.createCredential({ challenge, context: {} })).rejects.toThrow(
+      'keyAuthorization signer does not match the selected account',
+    )
+  })
+})

package/src/tempo/client/Subscription.ts

@@ -0,0 +1,155 @@
+import { KeyAuthorization } from 'ox/tempo'
+import { isAddressEqual, type Address } from 'viem'
+import { tempo as tempo_chain } from 'viem/chains'
+
+import * as Credential from '../../Credential.js'
+import type { MaybePromise } from '../../internal/types.js'
+import * as Method from '../../Method.js'
+import * as Account from '../../viem/Account.js'
+import * as Client from '../../viem/Client.js'
+import * as z from '../../zod.js'
+import * as defaults from '../internal/defaults.js'
+import * as Methods from '../Methods.js'
+import {
+  getSubscriptionRpcAllowedCalls,
+  signSubscriptionKeyAuthorization,
+  toSubscriptionExpiryDate,
+  toSubscriptionExpirySeconds,
+  toSubscriptionPeriodSeconds,
+  verifySubscriptionKeyAuthorization,
+} from '../subscription/KeyAuthorization.js'
+import type { SubscriptionAccessKey } from '../subscription/Types.js'
+
+type SubscriptionRequest = ReturnType<typeof Methods.subscription.schema.request.parse>
+
+/** Context accepted by the Tempo subscription client method. */
+export const subscriptionContextSchema = z.object({
+  accessKey: z.optional(z.custom<SubscriptionAccessKey>()),
+  account: z.optional(z.custom<Account.getResolver.Parameters['account']>()),
+})
+
+/** Runtime context for creating a Tempo subscription credential. */
+export type SubscriptionContext = z.infer<typeof subscriptionContextSchema>
+
+/** Creates a Tempo subscription client method. */
+export function subscription(parameters: subscription.Parameters = {}) {
+  const getClient = Client.getResolver({
+    chain: tempo_chain,
+    getClient: parameters.getClient,
+    rpcUrl: defaults.rpcUrl,
+  })
+  const getAccount = Account.getResolver({ account: parameters.account })
+
+  return Method.toClient(Methods.subscription, {
+    context: subscriptionContextSchema,
+
+    async createCredential({ challenge, context }) {
+      const chainId = challenge.request.methodDetails?.chainId ?? defaults.chainId.testnet
+      const client = await getClient({ chainId })
+      const account = getAccount(client, context)
+      const accessKey =
+        context?.accessKey ?? parameters.accessKey ?? challenge.request.methodDetails?.accessKey
+      if (!accessKey) {
+        throw new Error(
+          'No `accessKey` provided. The subscription challenge must include `accessKey`, or the client must pass one to parameters/context.',
+        )
+      }
+
+      assertSubscriptionRequestRepresentable(challenge.request)
+      await parameters.validateRequest?.(challenge.request)
+
+      const keyAuthorization = await authorizeAccessKey(client, {
+        accessKey,
+        account,
+        chainId,
+        request: challenge.request,
+      } as never)
+
+      const verified = verifySubscriptionKeyAuthorization({
+        accessKey,
+        chainId,
+        payload: {
+          signature: KeyAuthorization.serialize(keyAuthorization as never),
+          type: 'keyAuthorization',
+        },
+        request: challenge.request,
+      })
+      if (!isAddressEqual(verified.source.address, account.address)) {
+        throw new Error('keyAuthorization signer does not match the selected account')
+      }
+
+      return Credential.serialize({
+        challenge,
+        payload: {
+          signature: KeyAuthorization.serialize(keyAuthorization as never),
+          type: 'keyAuthorization',
+        },
+        source: `did:pkh:eip155:${chainId}:${account.address.toLowerCase()}`,
+      })
+    },
+  })
+}
+
+async function authorizeAccessKey(
+  client: Awaited<ReturnType<ReturnType<typeof Client.getResolver>>>,
+  parameters: {
+    accessKey: SubscriptionAccessKey
+    account: Account.Account
+    chainId: number
+    request: Pick<
+      SubscriptionRequest,
+      'amount' | 'currency' | 'periodCount' | 'periodUnit' | 'recipient' | 'subscriptionExpires'
+    >
+  },
+) {
+  const { accessKey, account, chainId, request } = parameters
+
+  const local = await signSubscriptionKeyAuthorization({
+    accessKey,
+    account,
+    chainId,
+    request,
+  })
+  if (local) return local
+
+  const result = (await client.request({
+    method: 'wallet_authorizeAccessKey',
+    params: [
+      {
+        address: accessKey.accessKeyAddress,
+        allowedCalls: getSubscriptionRpcAllowedCalls(request),
+        expiry: toSubscriptionExpirySeconds(toSubscriptionExpiryDate(request.subscriptionExpires)),
+        keyType: accessKey.keyType,
+        limits: [
+          {
+            token: request.currency as Address,
+            limit: BigInt(request.amount),
+            period: toSubscriptionPeriodSeconds(request),
+          },
+        ],
+      },
+    ],
+  } as never)) as {
+    keyAuthorization: Parameters<typeof KeyAuthorization.fromRpc>[0]
+  }
+
+  return KeyAuthorization.fromRpc(result.keyAuthorization)
+}
+
+function assertSubscriptionRequestRepresentable(request: SubscriptionRequest) {
+  toSubscriptionPeriodSeconds(request)
+  toSubscriptionExpirySeconds(toSubscriptionExpiryDate(request.subscriptionExpires))
+}
+
+export declare namespace subscription {
+  /** Parameters for creating a Tempo subscription credential. */
+  type Parameters = Account.getResolver.Parameters &
+    Client.getResolver.Parameters & {
+      accessKey?: SubscriptionAccessKey | undefined
+      validateRequest?:
+        | ((
+            request: ReturnType<typeof Methods.subscription.schema.request.parse>,
+          ) => MaybePromise<void>)
+        | undefined
+    }
+}

package/src/tempo/client/index.ts

@@ -1,5 +1,6 @@
 export { charge } from './Charge.js'
 export { tempo } from './Methods.js'
 export { session } from './Session.js'
+export { subscription } from './Subscription.js'
 export type { PaymentResponse, SessionManager } from './SessionManager.js'
 export { sessionManager } from './SessionManager.js'

package/src/tempo/index.ts

@@ -1,3 +1,4 @@
 export * as Proof from './Proof.js'
 export * as Methods from './Methods.js'
 export * as Session from './session/index.js'
+export * as Subscription from './subscription/index.js'

package/src/tempo/server/Methods.ts

@@ -1,6 +1,7 @@
 import * as Ws_ from '../session/Ws.js'
 import { charge as charge_ } from './Charge.js'
 import { session as session_, settle as settle_ } from './Session.js'
+import { renew as renewSubscription_, subscription as subscription_ } from './Subscription.js'
 
 /**
  * Creates both Tempo `charge` and `session` methods from shared parameters.
@@ -28,6 +29,10 @@ export namespace tempo {
   export const charge = charge_
   /** Creates a Tempo `session` method for session-based TIP-20 token payments. */
   export const session = session_
+  /** Creates a Tempo `subscription` method for recurring TIP-20 token payments. */
+  export const subscription = subscription_
+  /** Renews an overdue Tempo subscription outside of the HTTP request path. */
+  export const renewSubscription = renewSubscription_
   /** One-shot settle: reads highest voucher from storage and submits on-chain. */
   export const settle = settle_
   /** Experimental websocket helpers for Tempo sessions. */