tapimo 0.5.3 → 0.7.0

package/src/apps/mpp/App.ts

@@ -0,0 +1,86 @@
+import { Hono } from 'hono'
+import type * as z from 'zod/mini'
+
+import type * as App from '../../App.js'
+import * as Auth from '../../internal/Auth.js'
+import * as OpenApi from '../../internal/OpenApi.js'
+import * as Metadata from '../metadata.js'
+import * as Mpp from './Mpp.js'
+
+/** Mounts MPP credential verification and broadcast routes. */
+export function mpp() {
+  const app = new Hono<App.Environment>()
+    .post(
+      '/v1/mpp/verify',
+      Auth.policy({ apiKey: { scopes: ['mpp:write'] }, mpp: false, public: false }),
+      OpenApi.validate('json', Mpp.schema.RelayInput, bodyValidation),
+      OpenApi.describeRoute({
+        operationId: 'verifyMppCredential',
+        responses: responses({
+          description: 'The MPP credential validation result.',
+          schema: Mpp.schema.VerifyResponse,
+        }),
+        summary: 'Verify MPP credential',
+        tags: ['MPP Relay'],
+      }),
+      (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, bodyValidation)
+        return Mpp.unavailable<Mpp.VerifyResponse>(c)
+      },
+    )
+    .post(
+      '/v1/mpp/broadcast',
+      Auth.policy({ apiKey: { scopes: ['mpp:write'] }, mpp: false, public: false }),
+      OpenApi.validate('json', Mpp.schema.RelayInput, bodyValidation),
+      OpenApi.describeRoute({
+        operationId: 'broadcastMppCredential',
+        responses: responses({
+          description: 'The MPP credential broadcast result.',
+          schema: Mpp.schema.BroadcastResponse,
+        }),
+        summary: 'Broadcast MPP credential',
+        tags: ['MPP Relay'],
+      }),
+      (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, bodyValidation)
+        return Mpp.unavailable<Mpp.BroadcastResponse>(c)
+      },
+    )
+  return Metadata.attach(app, openapi)
+}
+
+const bodyValidation = {
+  code: 'body_invalid',
+  message: 'Check the MPP credential and challenge, then try again.',
+} as const
+
+function responses<schema extends z.ZodMiniType>(options: { description: string; schema: schema }) {
+  return {
+    ...OpenApi.responses({
+      errors: { 403: 'The API key does not grant MPP relay access.' },
+      success: options,
+    }),
+    503: {
+      content: { 'application/json': { schema: OpenApi.resolver(Mpp.schema.Unavailable) } },
+      description: 'MPP relay settlement is temporarily unavailable.',
+      headers: {
+        'Retry-After': {
+          description: 'How many seconds to wait before retrying the relay.',
+          schema: { type: 'integer' as const },
+        },
+      },
+    },
+  }
+}
+
+const openapi = {
+  tags: [
+    {
+      name: 'MPP Relay',
+      description: 'Validate and broadcast MPP payment credentials through Tempo.',
+    },
+  ],
+  'x-tagGroups': [{ name: 'Payments', tags: ['MPP Relay'] }],
+} satisfies App.create.Metadata

package/src/apps/mpp/Mpp.test.ts

@@ -0,0 +1,193 @@
+import * as TestApp from '../../../test/App.js'
+import * as Mpp from './Mpp.js'
+
+const key = {
+  id: 'key_mpp',
+  orgId: 'org_test',
+  scopes: ['mpp:write'],
+  token: 'secret_mpp',
+} satisfies TestApp.kvStore.Key
+
+const input = {
+  challenge: {
+    description: 'Tempo API payment',
+    id: 'ch_01j3j1k2l3m4n5p6q7r8s9t0u',
+    intent: 'charge',
+    method: 'tempo',
+    opaque: 'eyJhbGciOiJIUzI1NiJ9',
+    realm: 'merchant.example',
+    request: { amount: '1', currency: 'USD' },
+  },
+  payload: { signature: `0x${'aa'.repeat(65)}`, type: 'transaction' },
+} satisfies Mpp.RelayInput
+
+const errorCodes = [
+  'unsupported',
+  'policy_denied',
+  'invalid_payment',
+  'insufficient_funds',
+  'expired',
+  'already_used',
+  'screen_rejected',
+  'simulation_failed',
+  'broadcast_failed',
+  'temporarily_unavailable',
+  'unknown',
+] as const
+
+const errorDescriptions = [
+  'Method, intent, network, or asset is unsupported.',
+  'Payment violates relay or account policy.',
+  'Payload, signature, parties, or payment requirements are invalid.',
+  'Sender lacks funds.',
+  'Challenge or payment authorization expired.',
+  'Credential or transaction already used.',
+  'Originator or recipient failed screening.',
+  'Transaction simulation failed before broadcast.',
+  'Transaction broadcast or confirmation failed.',
+  'Retry may succeed.',
+  'Unexpected relay failure.',
+] as const
+
+describe('MPP relay', () => {
+  test.each(['/v1/mpp/verify', '/v1/mpp/broadcast'])('%s requires the MPP scope', async (path) => {
+    const app = TestApp.create({ auth: { keys: [key] } })
+    const response = await app.fetch(
+      new Request(`http://tempo-api.test${path}`, {
+        body: JSON.stringify(input),
+        headers: { 'content-type': 'application/json', authorization: 'Bearer secret_mpp' },
+        method: 'POST',
+      }),
+    )
+
+    expect(response.status).toBe(503)
+    expect(response.headers.get('retry-after')).toBe('60')
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "temporarily_unavailable",
+          "message": "MPP relay is not enabled yet.",
+        },
+        "success": false,
+      }
+    `)
+  })
+
+  test('rejects unscoped API keys', async () => {
+    const app = TestApp.create({ auth: { keys: [key, TestApp.key] } })
+    const response = await app.fetch(
+      new Request('http://tempo-api.test/v1/mpp/verify', {
+        body: JSON.stringify(input),
+        headers: {
+          'content-type': 'application/json',
+          authorization: `Bearer ${TestApp.key.token}`,
+        },
+        method: 'POST',
+      }),
+    )
+
+    expect(response.status).toBe(403)
+    expect(await response.json()).toMatchObject({ error: { code: 'api_key_forbidden' } })
+  })
+
+  test('requires API-key authentication', async () => {
+    const app = TestApp.create()
+    const response = await app.fetch(
+      new Request('http://tempo-api.test/v1/mpp/verify', {
+        body: JSON.stringify(input),
+        headers: { 'content-type': 'application/json' },
+        method: 'POST',
+      }),
+    )
+
+    expect(response.status).toBe(401)
+    expect(await response.json()).toMatchObject({ error: { code: 'api_key_missing' } })
+  })
+
+  test.each(['/v1/mpp/verify', '/v1/mpp/broadcast'])(
+    '%s rejects malformed credential input before the disabled handler',
+    async (path) => {
+      const app = TestApp.create({ auth: { keys: [key] } })
+      const response = await app.fetch(
+        new Request(`http://tempo-api.test${path}`, {
+          body: JSON.stringify({}),
+          headers: { 'content-type': 'application/json', authorization: 'Bearer secret_mpp' },
+          method: 'POST',
+        }),
+      )
+
+      expect(response.status).toBe(400)
+      expect(await response.json()).toMatchObject({ error: { code: 'body_invalid' } })
+    },
+  )
+
+  test.each(['/v1/mpp/verify', '/v1/mpp/broadcast'])(
+    '%s requires a credential payload',
+    async (path) => {
+      const app = TestApp.create({ auth: { keys: [key] } })
+      const response = await app.fetch(
+        new Request(`http://tempo-api.test${path}`, {
+          body: JSON.stringify({ challenge: input.challenge }),
+          headers: { 'content-type': 'application/json', authorization: 'Bearer secret_mpp' },
+          method: 'POST',
+        }),
+      )
+
+      expect(response.status).toBe(400)
+      expect(await response.json()).toMatchObject({ error: { code: 'body_invalid' } })
+    },
+  )
+
+  test('publishes the MPP endpoints', async () => {
+    const app = TestApp.create()
+    const spec = (await (await app.request('/openapi.json')).json()) as {
+      paths: Record<string, { post?: { responses?: Record<string, unknown> } }>
+    }
+
+    for (const path of ['/v1/mpp/verify', '/v1/mpp/broadcast']) {
+      expect(spec.paths[path]?.post?.responses?.['200']).toBeDefined()
+      expect(spec.paths[path]?.post?.responses?.['503']).toBeDefined()
+    }
+
+    const response = JSON.stringify(spec.paths['/v1/mpp/verify']?.post?.responses?.['200'])
+    for (const description of errorDescriptions) expect(response).toContain(description)
+  })
+})
+
+describe('MPP relay schemas', () => {
+  test('parses public relay contracts', () => {
+    expect(Mpp.schema.RelayInput.parse(input)).toEqual(input)
+    expect(Mpp.schema.VerifyResponse.parse({ success: true })).toEqual({ success: true })
+    expect(
+      Mpp.schema.BroadcastResponse.parse({
+        receipt: {
+          method: 'tempo',
+          reference: `0x${'22'.repeat(32)}`,
+          timestamp: '2026-07-20T18:30:00.000Z',
+        },
+        success: true,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "receipt": {
+          "method": "tempo",
+          "reference": "0x2222222222222222222222222222222222222222222222222222222222222222",
+          "timestamp": "2026-07-20T18:30:00.000Z",
+        },
+        "success": true,
+      }
+    `)
+  })
+
+  test.each(errorCodes)('accepts the %s error code', (code) => {
+    expect(Mpp.schema.RelayError.parse({ code })).toEqual({ code })
+  })
+
+  test('publishes the relay error code type', () => {
+    expectTypeOf<Mpp.RelayErrorCode>().toEqualTypeOf<(typeof errorCodes)[number]>()
+  })
+
+  test('rejects an unknown error code', () => {
+    expect(Mpp.schema.RelayError.safeParse({ code: 'unexpected' }).success).toBe(false)
+  })
+})

package/src/apps/mpp/Mpp.ts

@@ -0,0 +1,353 @@
+import type { Context, TypedResponse } from 'hono'
+import * as z from 'zod/mini'
+
+import type * as App from '../../App.js'
+import * as Response from '../../internal/Response.js'
+import * as Schema from '../../internal/Schema.js'
+
+/** Stable MPP relay failure codes. */
+export const relayErrorCode = {
+  /** Credential or transaction already used. */
+  alreadyUsed: 'already_used',
+  /** Transaction broadcast or confirmation failed. */
+  broadcastFailed: 'broadcast_failed',
+  /** Challenge or payment authorization expired. */
+  expired: 'expired',
+  /** Payload, signature, parties, or payment requirements are invalid. */
+  invalidPayment: 'invalid_payment',
+  /** Sender lacks funds. */
+  insufficientFunds: 'insufficient_funds',
+  /** Payment violates relay or account policy. */
+  policyDenied: 'policy_denied',
+  /** Originator or recipient failed screening. */
+  screenRejected: 'screen_rejected',
+  /** Transaction simulation failed before broadcast. */
+  simulationFailed: 'simulation_failed',
+  /** Retry may succeed. */
+  temporarilyUnavailable: 'temporarily_unavailable',
+  /** Method, intent, network, or asset is unsupported. */
+  unsupported: 'unsupported',
+  /** Unexpected relay failure. */
+  unknown: 'unknown',
+} as const
+
+/** Stable MPP relay failure code. */
+export type RelayErrorCode = (typeof relayErrorCode)[keyof typeof relayErrorCode]
+
+/** MPP relay error response. */
+export type RelayError = {
+  /** Stable machine-readable reason the relay rejected the credential. */
+  code: RelayErrorCode
+  /** Human-readable explanation of the relay result. */
+  message?: string | undefined
+}
+
+/** MPP challenge accepted with a relay credential payload. */
+export type Challenge = {
+  /** Additional MPP challenge metadata, preserved verbatim for validation. */
+  [key: string]: unknown
+  /** Human-readable payment description. */
+  description?: string | undefined
+  /** When the payment challenge expires, as an ISO-8601 timestamp. */
+  expires?: string | undefined
+  /** Payment challenge identifier. */
+  id: string
+  /** MPP payment intent. */
+  intent: string
+  /** MPP payment method. */
+  method: string
+  /** Opaque data bound to the challenge by its issuer. */
+  opaque?: string | undefined
+  /** MPP realm that issued the challenge. */
+  realm: string
+  /** Payment request bound to the challenge. */
+  request: Record<string, unknown>
+}
+
+/** MPP challenge and credential payload accepted by the relay. */
+export type RelayInput = {
+  /** Payment challenge supplied with the credential. */
+  challenge: Challenge
+  /** Method-specific MPP credential payload. */
+  payload: unknown
+}
+
+/** Broadcast MPP payment receipt. */
+export type Receipt = {
+  /** Optional caller-provided payment reference. */
+  externalId?: string | undefined
+  /** Payment method that settled the credential. */
+  method: string
+  /** On-chain or payment-system settlement reference. */
+  reference: string
+  /** When the payment settled, as an ISO-8601 timestamp. */
+  timestamp: string
+}
+
+/** MPP credential validation response. */
+export type VerifyResponse = { success: true } | { error: RelayError; success: false }
+
+/** MPP credential broadcast response. */
+export type BroadcastResponse =
+  | { receipt: Receipt; success: true }
+  | { error: RelayError; success: false }
+
+/** Retryable response returned while relay settlement is disabled. */
+export type Unavailable = {
+  error: { code: 'temporarily_unavailable'; message: 'MPP relay is not enabled yet.' }
+  success: false
+}
+
+function errorCode<const code extends RelayErrorCode>(value: code, description: string) {
+  return z.literal(value).check(z.describe(description), z.meta({ examples: [value] }))
+}
+
+/** MPP relay schemas. */
+export namespace schema {
+  /** Stable MPP relay failure codes. */
+  export const ErrorCode = Schema.describe(
+    z.union([
+      errorCode(relayErrorCode.unsupported, 'Method, intent, network, or asset is unsupported.'),
+      errorCode(relayErrorCode.policyDenied, 'Payment violates relay or account policy.'),
+      errorCode(
+        relayErrorCode.invalidPayment,
+        'Payload, signature, parties, or payment requirements are invalid.',
+      ),
+      errorCode(relayErrorCode.insufficientFunds, 'Sender lacks funds.'),
+      errorCode(relayErrorCode.expired, 'Challenge or payment authorization expired.'),
+      errorCode(relayErrorCode.alreadyUsed, 'Credential or transaction already used.'),
+      errorCode(relayErrorCode.screenRejected, 'Originator or recipient failed screening.'),
+      errorCode(relayErrorCode.simulationFailed, 'Transaction simulation failed before broadcast.'),
+      errorCode(relayErrorCode.broadcastFailed, 'Transaction broadcast or confirmation failed.'),
+      errorCode(relayErrorCode.temporarilyUnavailable, 'Retry may succeed.'),
+      errorCode(relayErrorCode.unknown, 'Unexpected relay failure.'),
+    ]),
+    'A stable machine-readable reason the MPP relay rejected or could not process a payment.',
+  )
+
+  /** Error returned by the MPP relay. */
+  export const RelayError = Schema.describe(
+    z
+      .object({
+        code: ErrorCode,
+        message: z
+          .optional(z.string())
+          .check(
+            z.describe('A human-readable explanation of the relay result.'),
+            z.meta({ examples: ['MPP relay is not enabled yet.'] }),
+          ),
+      })
+      .check(
+        z.meta({
+          examples: [
+            {
+              code: relayErrorCode.temporarilyUnavailable,
+              message: 'MPP relay is not enabled yet.',
+            },
+          ],
+        }),
+      ),
+    'An error returned by the MPP relay.',
+  )
+
+  /** MPP challenge accepted with a relay credential payload. */
+  export const Challenge = Schema.describe(
+    z.looseObject({
+      description: z
+        .optional(z.string())
+        .check(
+          z.describe('A human-readable description of the payment.'),
+          z.meta({ examples: ['Tempo API payment'] }),
+        ),
+      expires: z
+        .optional(z.string())
+        .check(
+          z.describe('When the payment challenge expires, as an ISO-8601 timestamp.'),
+          z.meta({ examples: ['2026-07-21T21:30:00.000Z'] }),
+        ),
+      id: z
+        .string()
+        .check(
+          z.describe('The payment challenge identifier.'),
+          z.meta({ examples: ['ch_01j3j1k2l3m4n5p6q7r8s9t0u'] }),
+        ),
+      intent: z
+        .string()
+        .check(z.describe('The MPP payment intent.'), z.meta({ examples: ['charge'] })),
+      method: z
+        .string()
+        .check(z.describe('The MPP payment method.'), z.meta({ examples: ['tempo'] })),
+      opaque: z
+        .optional(z.string())
+        .check(
+          z.describe('Opaque data bound to the challenge by its issuer.'),
+          z.meta({ examples: ['eyJhbGciOiJIUzI1NiJ9'] }),
+        ),
+      realm: z
+        .string()
+        .check(
+          z.describe('The MPP realm that issued the challenge.'),
+          z.meta({ examples: ['merchant.example'] }),
+        ),
+      request: z
+        .record(z.string(), z.unknown())
+        .check(
+          z.describe('The payment request bound to the challenge.'),
+          z.meta({ examples: [{ amount: '1', currency: 'USD' }] }),
+        ),
+    }),
+    'An MPP payment challenge.',
+  )
+
+  /** Request accepted by MPP relay verification and broadcast routes. */
+  export const RelayInput = Schema.describe(
+    z.object({
+      challenge: Challenge,
+      payload: z
+        .custom<unknown>((value) => value !== undefined)
+        .check(
+          z.describe('The method-specific MPP credential payload.'),
+          z.meta({ examples: [{ signature: `0x${'aa'.repeat(65)}`, type: 'transaction' }] }),
+        ),
+    }),
+    'An MPP payment credential and its challenge.',
+  )
+
+  /** Receipt returned after the relay broadcasts a payment. */
+  export const Receipt = Schema.describe(
+    z.object({
+      externalId: z
+        .optional(z.string())
+        .check(
+          z.describe('An optional caller-provided payment reference.'),
+          z.meta({ examples: ['pi_01j3j1k2l3m4n5p6q7r8s9t0u'] }),
+        ),
+      method: z
+        .string()
+        .check(
+          z.describe('The payment method that settled the credential.'),
+          z.meta({ examples: ['tempo'] }),
+        ),
+      reference: z
+        .string()
+        .check(
+          z.describe('The on-chain or payment-system reference for the settlement.'),
+          z.meta({ examples: [`0x${'22'.repeat(32)}`] }),
+        ),
+      timestamp: z
+        .string()
+        .check(
+          z.describe('When the payment settled, as an ISO-8601 timestamp.'),
+          z.meta({ examples: ['2026-07-20T18:30:00.000Z'] }),
+        ),
+    }),
+    'A receipt for a broadcast MPP payment.',
+  )
+
+  /** Read-only MPP credential validation result. */
+  export const VerifyResponse = Schema.describe(
+    z.union([
+      z.object({
+        success: z
+          .literal(true)
+          .check(
+            z.describe('Whether the credential passed relay checks.'),
+            z.meta({ examples: [true] }),
+          ),
+      }),
+      z.object({
+        error: RelayError.check(
+          z.describe('The reason the credential did not pass relay checks.'),
+          z.meta({
+            examples: [
+              { code: relayErrorCode.invalidPayment, message: 'Credential signature is invalid.' },
+            ],
+          }),
+        ),
+        success: z
+          .literal(false)
+          .check(
+            z.describe('Whether the credential passed relay checks.'),
+            z.meta({ examples: [false] }),
+          ),
+      }),
+    ]),
+    'The result of read-only MPP credential validation.',
+  )
+
+  /** MPP credential broadcast result. */
+  export const BroadcastResponse = Schema.describe(
+    z.union([
+      z.object({
+        receipt: Receipt.check(
+          z.describe('The payment settlement receipt.'),
+          z.meta({
+            examples: [
+              {
+                method: 'tempo',
+                reference: `0x${'22'.repeat(32)}`,
+                timestamp: '2026-07-20T18:30:00.000Z',
+              },
+            ],
+          }),
+        ),
+        success: z
+          .literal(true)
+          .check(
+            z.describe('Whether the relay broadcast the credential.'),
+            z.meta({ examples: [true] }),
+          ),
+      }),
+      z.object({
+        error: RelayError.check(
+          z.describe('The reason the relay did not broadcast the credential.'),
+          z.meta({
+            examples: [
+              { code: relayErrorCode.broadcastFailed, message: 'Transaction broadcast failed.' },
+            ],
+          }),
+        ),
+        success: z
+          .literal(false)
+          .check(
+            z.describe('Whether the relay broadcast the credential.'),
+            z.meta({ examples: [false] }),
+          ),
+      }),
+    ]),
+    'The result of broadcasting an MPP credential.',
+  )
+
+  /** Temporary response returned while MPP relay settlement is disabled. */
+  export const Unavailable = Schema.describe(
+    z.object({
+      error: z.object({
+        code: z
+          .literal(relayErrorCode.temporarilyUnavailable)
+          .check(z.describe('The retryable relay failure code.')),
+        message: z
+          .literal('MPP relay is not enabled yet.')
+          .check(z.describe('The retryable relay failure message.')),
+      }),
+      success: z.literal(false).check(z.describe('Whether the relay processed the credential.')),
+    }),
+    'A retryable response returned while MPP relay settlement is disabled.',
+  )
+}
+
+/** Returns the relay-disabled response while retaining its published success contract. */
+export function unavailable<success>(
+  c: Context<App.Environment>,
+): TypedResponse<success, 200> | TypedResponse<Unavailable, 503> {
+  c.header('Retry-After', '60')
+  return c.json(
+    Response.validated(schema.Unavailable, {
+      error: {
+        code: relayErrorCode.temporarilyUnavailable,
+        message: 'MPP relay is not enabled yet.',
+      },
+      success: false,
+    }),
+    503,
+  )
+}

package/src/apps/mpp/index.ts

@@ -0,0 +1,2 @@
+export { mpp } from './App.js'
+export * as Mpp from './Mpp.js'

package/src/apps/mpp/internal/Adapter.ts

@@ -0,0 +1,11 @@
+import type * as Mpp from '../Mpp.js'
+
+/** Future MPPX lifecycle adapter. */
+export type Adapter = {
+  /** Broadcasts a validated MPP credential. */
+  broadcast(input: Mpp.RelayInput): Promise<Mpp.BroadcastResponse>
+  /** Validates an MPP credential without broadcasting it. */
+  verify(input: Mpp.RelayInput): Promise<Mpp.VerifyResponse>
+}
+
+// TODO(mppx#597): implement with validateCredential and broadcastCredential.

package/src/apps/mpp/internal/Error.ts

@@ -0,0 +1,9 @@
+import type * as Mpp from '../Mpp.js'
+
+/** Future MPPX failure mapper. */
+export type Mapper = {
+  /** Maps an MPPX failure to the stable public relay error contract. */
+  map(cause: unknown): Mpp.RelayError
+}
+
+// TODO(mppx#597): map validation, replay, simulation, and broadcast failures.

package/src/apps/mpp/internal/Idempotency.ts

@@ -0,0 +1,7 @@
+/** Future challenge-derived broadcast idempotency identity. */
+export type Identity = {
+  /** MPP challenge identifier. */
+  challengeId: string
+}
+
+// TODO(mppx#597): persist terminal broadcast results in Durable Object state.

package/src/apps/mpp/internal/Screening.ts

@@ -0,0 +1,10 @@
+/** Future address-screening result. */
+export type Result = { allowed: boolean }
+
+/** Future address-screening provider. */
+export type Provider = {
+  /** Screens one normalized account address on a Tempo chain. */
+  screen(options: { address: string; chainId: number }): Promise<Result>
+}
+
+// TODO(mppx#597): add concurrent cached Chainalysis screening behind this provider.