mppx 0.8.17 → 0.8.18

package/src/internal/AcceptPayment.ts

@@ -1,366 +0,0 @@
-import type * as Challenge from '../Challenge.js'
-import * as x402_ChallengeBrand from '../x402/internal/ChallengeBrand.js'
-import type { MaybePromise } from './types.js'
-
-type MethodLike = {
-  canHandleChallenge?: ((parameters: { challenge: Challenge.Challenge }) => boolean) | undefined
-  intent: string
-  name: string
-}
-
-/** Supported challenge paired with the configured client method that can sign it. */
-export type ChallengeCandidate<method extends MethodLike = MethodLike> = method extends MethodLike
-  ? {
-      challenge: Challenge.Challenge<Record<string, unknown>, method['intent'], method['name']>
-      index: number
-      method: method
-    }
-  : never
-
-/**
- * Hook for filtering and sorting supported challenges before credential creation.
- *
- * Return candidates in preference order. The SDK signs the first returned
- * candidate. Return an empty array to reject all offered challenges.
- */
-export type OrderChallenges<methods extends readonly MethodLike[]> = (
-  candidates: readonly ChallengeCandidate<methods[number]>[],
-) => MaybePromise<readonly ChallengeCandidate<methods[number]>[]>
-
-/** Typed `method/intent` key for a configured payment capability. */
-export type Key<methods extends readonly MethodLike[]> = methods[number] extends infer mi
-  ? mi extends { name: infer name extends string; intent: infer intent extends string }
-    ? `${name}/${intent}`
-    : never
-  : never
-
-/** Method keys grouped by method name for ergonomic config callbacks. */
-export type KeyTree<methods extends readonly MethodLike[]> = {
-  [name in methods[number]['name']]: {
-    [mi in Extract<
-      methods[number],
-      { name: name }
-    > as mi['intent']]: `${mi['name']}/${mi['intent']}`
-  }
-}
-
-/** Per-capability q-values keyed by typed `method/intent` strings. */
-export type Definition<methods extends readonly MethodLike[]> = Partial<
-  Record<Key<methods>, number>
->
-
-/**
- * Accept-Payment configuration.
- *
- * Callers may provide a plain definition map or a callback that receives a
- * typed key tree for authoring preferences without string literals.
- */
-export type Config<methods extends readonly MethodLike[]> =
-  | Definition<methods>
-  | ((keys: KeyTree<methods>) => Definition<methods>)
-
-/** Parsed Accept-Payment entry with its original declaration order. */
-export type Entry = {
-  intent: string | '*'
-  method: string | '*'
-  q: number
-  index: number
-}
-
-/** Resolved negotiation data derived from client methods and config. */
-export type Resolved<methods extends readonly MethodLike[]> = {
-  definition: Definition<methods>
-  entries: Entry[]
-  header: string
-  keys: KeyTree<methods>
-}
-
-type Match = Entry & { specificity: number }
-
-/** Builds the typed key tree used by callback-style preference config. */
-export function buildKeys<const methods extends readonly MethodLike[]>(
-  methods: methods,
-): KeyTree<methods> {
-  const keys: Record<string, Record<string, string>> = {}
-
-  for (const method of methods) {
-    const group = (keys[method.name] ??= {})
-    group[method.intent] = keyOf(method)
-  }
-
-  return keys as KeyTree<methods>
-}
-
-/** Resolves configured payment preferences into a header string and parsed entries. */
-export function resolve<const methods extends readonly MethodLike[]>(
-  methods: methods,
-  config?: Config<methods>,
-): Resolved<methods> {
-  const keys = buildKeys(methods)
-  const definition = resolveDefinition(methods, keys, config)
-  const entries = methods.map((method, index) => ({
-    intent: method.intent,
-    method: method.name,
-    q: definition[keyOf(method) as Key<methods>] ?? 1,
-    index,
-  }))
-
-  return {
-    definition,
-    entries,
-    header: serialize(entries),
-    keys,
-  }
-}
-
-/** Parses an `Accept-Payment` header into normalized preference entries. */
-export function parse(header: string): Entry[] {
-  const parts = header
-    .split(/\s*,\s*/)
-    .map((part) => part.trim())
-    .filter(Boolean)
-
-  if (parts.length === 0) throw new Error('Accept-Payment header is empty.')
-
-  return parts.map((part, index) => parseEntry(part, index))
-}
-
-/** Serializes preference entries to an `Accept-Payment` header value. */
-export function serialize(entries: readonly Omit<Entry, 'index'>[] | readonly Entry[]): string {
-  return entries
-    .map(({ method, intent, q }) => {
-      const value = `${method}/${intent}`
-      return q === 1 ? value : `${value};q=${formatQ(q)}`
-    })
-    .join(', ')
-}
-
-/**
- * Orders offered payment methods by the best matching client preference.
- *
- * More specific matches win before comparing q-values, so an explicit opt-out
- * like `tempo/charge;q=0` overrides a broader wildcard such as `tempo/*;q=1`.
- */
-export function rank<const offer extends { intent: string; method: string }>(
-  offers: readonly offer[],
-  preferences: readonly Entry[],
-): offer[] {
-  return offers
-    .map((offer, index) => {
-      const match = bestMatch(offer, preferences)
-      return match && match.q > 0 ? { match, offer, index } : undefined
-    })
-    .filter((candidate): candidate is NonNullable<typeof candidate> => Boolean(candidate))
-    .sort((left, right) => right.match.q - left.match.q || left.index - right.index)
-    .map(({ offer }) => offer)
-}
-
-/** Selects the best supported challenge from a set of server offers. */
-export function selectChallenge<const methods extends readonly MethodLike[]>(
-  challenges: readonly Challenge.Challenge[],
-  methods: methods,
-  preferences: readonly Entry[],
-):
-  | {
-      challenge: Challenge.Challenge
-      method: methods[number]
-    }
-  | undefined {
-  const candidate = selectChallengeCandidates(challenges, methods, preferences)[0]
-  if (!candidate) return undefined
-
-  return {
-    challenge: candidate.challenge,
-    method: candidate.method,
-  }
-}
-
-/** Returns supported challenge candidates ordered by client payment preferences. */
-export function selectChallengeCandidates<const methods extends readonly MethodLike[]>(
-  challenges: readonly Challenge.Challenge[],
-  methods: methods,
-  preferences: readonly Entry[],
-): ChallengeCandidate<methods[number]>[] {
-  const methodsByKey = new Map<string, methods[number][]>()
-  for (const method of methods) {
-    const key = keyOf(method)
-    const matchingMethods = methodsByKey.get(key)
-    if (matchingMethods) matchingMethods.push(method)
-    else methodsByKey.set(key, [method])
-  }
-
-  return challenges
-    .flatMap((challenge, index) => {
-      const matchingMethods = methodsByKey.get(keyOf(challenge))
-      if (!matchingMethods) return []
-
-      const match = bestMatch(challenge, preferences)
-      if (!match || match.q <= 0) return []
-
-      return matchingMethods
-        .filter((method) => method.canHandleChallenge?.({ challenge }) ?? true)
-        .map(
-          (method) =>
-            ({
-              challenge,
-              index,
-              match,
-              method,
-            }) as ChallengeCandidate<methods[number]> & { match: Match },
-        )
-    })
-    .sort(
-      (left, right) =>
-        protocolRank(left.challenge) - protocolRank(right.challenge) ||
-        right.match.q - left.match.q ||
-        left.index - right.index,
-    )
-    .map((candidate) => {
-      const { match: _match, ...rest } = candidate
-      return rest as unknown as ChallengeCandidate<methods[number]>
-    })
-}
-
-/** Returns the canonical `method/intent` key for a method or challenge-like value. */
-export function keyOf(value: { intent: string; method?: string; name?: string }): string {
-  const method = value.method ?? value.name
-  if (!method) throw new Error('Missing payment method name.')
-  return `${method}/${value.intent}`
-}
-
-function bestMatch(
-  offer: { intent: string; method: string },
-  preferences: readonly Entry[],
-): Match | undefined {
-  let best: Match | undefined
-
-  for (const preference of preferences) {
-    if (!matches(offer, preference)) continue
-
-    const candidate = { ...preference, specificity: specificity(preference) }
-    if (
-      !best ||
-      candidate.specificity > best.specificity ||
-      (candidate.specificity === best.specificity && candidate.q > best.q) ||
-      (candidate.specificity === best.specificity &&
-        candidate.q === best.q &&
-        candidate.index < best.index)
-    ) {
-      best = candidate
-    }
-  }
-
-  return best
-}
-
-function matches(
-  offer: { intent: string; method: string },
-  preference: Pick<Entry, 'intent' | 'method'>,
-): boolean {
-  return (
-    (preference.method === '*' || preference.method === offer.method) &&
-    (preference.intent === '*' || preference.intent === offer.intent)
-  )
-}
-
-function specificity(preference: Pick<Entry, 'intent' | 'method'>): number {
-  return Number(preference.method !== '*') + Number(preference.intent !== '*')
-}
-
-function protocolRank(challenge: Challenge.Challenge): number {
-  return x402_ChallengeBrand.is(challenge) ? 1 : 0
-}
-
-function parseEntry(part: string, index: number): Entry {
-  const match =
-    /^(?<method>[^/;\s]+|\*)\s*\/\s*(?<intent>[^/;\s]+|\*)(?<params>(?:\s*;\s*.+)?)$/u.exec(part)
-  const method = match?.groups?.method
-  const intent = match?.groups?.intent
-
-  if (!method || !intent) {
-    throw new Error(`Invalid Accept-Payment entry: ${part}`)
-  }
-
-  assertToken(method, 'method')
-  assertToken(intent, 'intent')
-
-  let q = 1
-  for (const param of splitParameters(match.groups?.params)) {
-    if (!param) continue
-
-    const parameterMatch = /^(?<name>[A-Za-z0-9_-]+)\s*=\s*(?<value>\S+)$/u.exec(param)
-    const name = parameterMatch?.groups?.name
-    const rawValue = parameterMatch?.groups?.value
-
-    if (!name || !rawValue) {
-      throw new Error(`Invalid Accept-Payment parameter: ${param}`)
-    }
-    if (name !== 'q') continue
-    q = parseHeaderQ(rawValue, `Accept-Payment entry "${part}"`)
-  }
-
-  return { intent, method, q, index }
-}
-
-function splitParameters(value?: string): string[] {
-  return value ? value.split(/\s*;\s*/).filter(Boolean) : []
-}
-
-function resolveDefinition<const methods extends readonly MethodLike[]>(
-  methods: methods,
-  keys: KeyTree<methods>,
-  config?: Config<methods>,
-): Definition<methods> {
-  if (!config) return {} as Definition<methods>
-
-  const raw = typeof config === 'function' ? config(keys) : config
-  const allowed = new Set(methods.map((method) => keyOf(method)))
-  const normalized: Record<string, number> = {}
-
-  for (const [key, value] of Object.entries(raw ?? {})) {
-    if (!allowed.has(key)) {
-      throw new Error(`Unknown payment preference "${key}". Available: ${[...allowed].join(', ')}`)
-    }
-    normalized[key] = parseQ(value, `payment preference "${key}"`)
-  }
-
-  return normalized as Definition<methods>
-}
-
-function parseQ(value: unknown, context: string): number {
-  if (typeof value !== 'number' || Number.isNaN(value) || !Number.isFinite(value)) {
-    throw new Error(`Invalid q-value for ${context}. Expected a finite number.`)
-  }
-  return assertQ(value, context)
-}
-
-function parseHeaderQ(value: string, context: string): number {
-  if (!/^0(?:\.\d{0,3})?$|^1(?:\.0{0,3})?$/.test(value)) {
-    throw new Error(`Invalid q-value for ${context}. Expected an HTTP qvalue.`)
-  }
-  return assertQ(Number(value), context)
-}
-
-function assertQ(value: number, context: string): number {
-  if (value < 0 || value > 1) {
-    throw new Error(`Invalid q-value for ${context}. Expected a value between 0 and 1.`)
-  }
-  const rounded = Math.round(value * 1000)
-  if (Math.abs(value * 1000 - rounded) > 1e-9) {
-    throw new Error(`Invalid q-value for ${context}. Expected at most 3 decimal places.`)
-  }
-  return rounded / 1000
-}
-
-function formatQ(value: number): string {
-  return value
-    .toFixed(3)
-    .replace(/\.0+$/, '')
-    .replace(/(\.\d*?)0+$/, '$1')
-}
-
-function assertToken(value: string, label: string): void {
-  if (value !== '*' && !/^[a-z0-9-]+$/.test(value)) {
-    throw new Error(`Invalid Accept-Payment ${label}: ${value}`)
-  }
-}

package/src/internal/HeaderCodec.ts

@@ -1,36 +0,0 @@
-import { Base64 } from 'ox'
-
-import type * as z from '../zod.js'
-
-/**
- * Creates a typed codec for JSON HTTP header values.
- *
- * x402 uses plain base64 JSON header bodies, while the Payment auth scheme uses
- * its own base64url/JCS serializers. Keep this helper internal so transports
- * can opt into the exact wire encoding their protocol expects.
- */
-export function createJson<const schema extends z.ZodMiniType>(schema: schema) {
-  type value = z.output<schema>
-
-  return {
-    encode(value: value): string {
-      return Base64.fromString(JSON.stringify(schema.parse(value)))
-    },
-    decode(value: string): value {
-      try {
-        return schema.parse(JSON.parse(Base64.toString(value))) as value
-      } catch {
-        throw new InvalidJsonHeaderError()
-      }
-    },
-  }
-}
-
-/** Error thrown when a JSON header value is not valid base64-encoded JSON. */
-export class InvalidJsonHeaderError extends Error {
-  override readonly name = 'InvalidJsonHeaderError'
-
-  constructor() {
-    super('Invalid base64 JSON header.')
-  }
-}

package/src/internal/changeset.test.ts

@@ -1,106 +0,0 @@
-import * as fs from 'node:fs'
-import * as path from 'node:path'
-
-import { describe, expect, test } from 'vp/test'
-
-const changesetDir = path.resolve(import.meta.dirname, '../../.changeset')
-const validPackages = new Set(['mppx'])
-const validBumpTypes = new Set(['major', 'minor', 'patch', 'none'])
-
-function getChangesetFiles() {
-  return fs
-    .readdirSync(changesetDir)
-    .filter((f) => f.endsWith('.md') && f !== 'README.md' && !f.startsWith('.'))
-}
-
-function parseFrontmatter(content: string) {
-  const match = content.match(/^\s*---\n([^]*?)\n\s*---/)
-  if (!match) return undefined
-  return match[1]
-}
-
-function parseReleases(frontmatter: string) {
-  return [...frontmatter.matchAll(/^['"]?([^'":\n]+?)['"]?\s*:\s*(.+)$/gm)].map(
-    ([, name, type]) => ({ name: name!.trim(), type: type!.trim().replace(/['"]/g, '') }),
-  )
-}
-
-describe('changesets', () => {
-  const files = getChangesetFiles()
-
-  test('all changeset files have valid frontmatter fences', () => {
-    for (const file of files) {
-      const content = fs.readFileSync(path.join(changesetDir, file), 'utf-8')
-      expect(content, `${file}: must start with "---"`).toMatch(/^---\n/)
-      const closingIdx = content.indexOf('---', 3)
-      expect(closingIdx, `${file}: missing closing "---" fence`).toBeGreaterThan(3)
-
-      // closing fence must not have trailing non-whitespace (parser chokes)
-      const afterClosing = content.slice(closingIdx + 3).split('\n')[0]!
-      expect(afterClosing.trim(), `${file}: trailing characters after closing "---"`).toBe('')
-    }
-  })
-
-  test('all changesets reference valid packages', () => {
-    for (const file of files) {
-      const content = fs.readFileSync(path.join(changesetDir, file), 'utf-8')
-      const frontmatter = parseFrontmatter(content)
-      if (!frontmatter) continue
-      for (const { name } of parseReleases(frontmatter)) {
-        expect(
-          validPackages.has(name),
-          `${file}: unknown package "${name}" (valid: ${[...validPackages].join(', ')})`,
-        ).toBe(true)
-      }
-    }
-  })
-
-  test('all changesets use valid bump types', () => {
-    for (const file of files) {
-      const content = fs.readFileSync(path.join(changesetDir, file), 'utf-8')
-      const frontmatter = parseFrontmatter(content)
-      if (!frontmatter) continue
-      for (const { name, type } of parseReleases(frontmatter)) {
-        expect(
-          validBumpTypes.has(type),
-          `${file}: invalid bump type "${type}" for "${name}" (valid: major, minor, patch, none)`,
-        ).toBe(true)
-      }
-    }
-  })
-
-  test('no changeset uses major bump (pre-v1 policy)', () => {
-    for (const file of files) {
-      const content = fs.readFileSync(path.join(changesetDir, file), 'utf-8')
-      const frontmatter = parseFrontmatter(content)
-      if (!frontmatter) continue
-      for (const { name, type } of parseReleases(frontmatter)) {
-        expect(type, `${file}: "${name}" uses major bump — pre-v1 policy forbids this`).not.toBe(
-          'major',
-        )
-      }
-    }
-  })
-
-  test('all changesets have a non-empty description', () => {
-    for (const file of files) {
-      const content = fs.readFileSync(path.join(changesetDir, file), 'utf-8')
-      const match = content.match(/^\s*---[^]*?---\s*(.*)$/s)
-      expect(match?.[1]?.trim(), `${file}: changeset has an empty description`).toBeTruthy()
-    }
-  })
-
-  test('no duplicate package entries in frontmatter', () => {
-    for (const file of files) {
-      const content = fs.readFileSync(path.join(changesetDir, file), 'utf-8')
-      const frontmatter = parseFrontmatter(content)
-      if (!frontmatter) continue
-      const releases = parseReleases(frontmatter)
-      const seen = new Set<string>()
-      for (const { name } of releases) {
-        expect(seen.has(name), `${file}: duplicate entry for "${name}"`).toBe(false)
-        seen.add(name)
-      }
-    }
-  })
-})

package/src/internal/constantTimeEqual.test.ts

@@ -1,47 +0,0 @@
-import { describe, expect, test } from 'vp/test'
-
-import { constantTimeEqual } from './constantTimeEqual.js'
-
-describe('constantTimeEqual', () => {
-  test('returns true for identical strings', () => {
-    expect(constantTimeEqual('abc', 'abc')).toBe(true)
-  })
-
-  test('returns true for empty strings', () => {
-    expect(constantTimeEqual('', '')).toBe(true)
-  })
-
-  test('returns false for different strings of same length', () => {
-    expect(constantTimeEqual('abc', 'abd')).toBe(false)
-  })
-
-  test('returns false for different lengths', () => {
-    expect(constantTimeEqual('abc', 'abcd')).toBe(false)
-    expect(constantTimeEqual('abcd', 'abc')).toBe(false)
-  })
-
-  test('returns false for empty vs non-empty', () => {
-    expect(constantTimeEqual('', 'a')).toBe(false)
-    expect(constantTimeEqual('a', '')).toBe(false)
-  })
-
-  test('returns false when only first character differs', () => {
-    expect(constantTimeEqual('xbc', 'abc')).toBe(false)
-  })
-
-  test('returns false when only last character differs', () => {
-    expect(constantTimeEqual('abx', 'abc')).toBe(false)
-  })
-
-  test('handles base64url strings (typical HMAC output)', () => {
-    const a = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
-    const b = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
-    expect(constantTimeEqual(a, b)).toBe(true)
-  })
-
-  test('detects single-bit difference in base64url strings', () => {
-    const a = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
-    const b = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXl'
-    expect(constantTimeEqual(a, b)).toBe(false)
-  })
-})

package/src/internal/constantTimeEqual.ts

@@ -1,10 +0,0 @@
-import { Hash, Hex } from 'ox'
-
-/** Constant-time string comparison to prevent timing attacks. */
-export function constantTimeEqual(a: string, b: string): boolean {
-  const hashA = Hash.sha256(Hex.fromString(a))
-  const hashB = Hash.sha256(Hex.fromString(b))
-  let result = 0
-  for (let i = 0; i < hashA.length; i++) result |= hashA.charCodeAt(i) ^ hashB.charCodeAt(i)
-  return result === 0
-}

package/src/internal/env.test.ts

@@ -1,42 +0,0 @@
-import * as Env from './env.js'
-
-afterEach(() => {
-  vi.unstubAllEnvs()
-})
-
-describe('Env.get', () => {
-  test('returns undefined when no env vars are set', () => {
-    expect(Env.get('realm')).toBeUndefined()
-  })
-
-  test('returns undefined when MPP_SECRET_KEY is not set', () => {
-    expect(Env.get('secretKey')).toBeUndefined()
-  })
-
-  test('returns MPP_SECRET_KEY when set', () => {
-    vi.stubEnv('MPP_SECRET_KEY', 'sk_live_abc123')
-    expect(Env.get('secretKey')).toBe('sk_live_abc123')
-  })
-
-  test('MPP_REALM takes precedence over platform vars', () => {
-    vi.stubEnv('MPP_REALM', 'custom-realm')
-    vi.stubEnv('FLY_APP_NAME', 'fly-app')
-    expect(Env.get('realm')).toBe('custom-realm')
-  })
-
-  test('returns FLY_APP_NAME when set', () => {
-    vi.stubEnv('FLY_APP_NAME', 'my-fly-app')
-    expect(Env.get('realm')).toBe('my-fly-app')
-  })
-
-  test('FLY_APP_NAME takes precedence over VERCEL_URL', () => {
-    vi.stubEnv('FLY_APP_NAME', 'fly-app')
-    vi.stubEnv('VERCEL_URL', 'my-app.vercel.app')
-    expect(Env.get('realm')).toBe('fly-app')
-  })
-
-  test('falls through to later vars when earlier ones are unset', () => {
-    vi.stubEnv('VERCEL_URL', 'my-app.vercel.app')
-    expect(Env.get('realm')).toBe('my-app.vercel.app')
-  })
-})

package/src/internal/env.ts

@@ -1,49 +0,0 @@
-/** Map of configuration keys to environment variable names, checked in order. */
-const variables = {
-  realm: [
-    'MPP_REALM',
-    'FLY_APP_NAME',
-    'HEROKU_APP_NAME',
-    'RAILWAY_PUBLIC_DOMAIN',
-    'RENDER_EXTERNAL_HOSTNAME',
-    'VERCEL_URL',
-    'WEBSITE_HOSTNAME',
-  ],
-  secretKey: ['MPP_SECRET_KEY'],
-} as const satisfies Record<string, readonly string[]>
-
-/** Fallback values when no environment variable is set. */
-const defaults = {} as const satisfies Partial<Record<keyof typeof variables, string>>
-
-/**
- * Resolves a configuration value from environment variables.
- *
- * Checks platform-specific env vars in order, falling back to a default if one exists.
- *
- * @example
- * ```ts
- * Env.get('realm')     // e.g. "my-app.vercel.app"
- * Env.get('secretKey') // e.g. value of MPP_SECRET_KEY
- * ```
- */
-export function get(key: keyof typeof variables): string | undefined {
-  for (const name of variables[key]) {
-    const value = read(name)
-    if (value) return value
-  }
-  return (defaults as Record<string, string | undefined>)[key]
-}
-
-/** Reads a single environment variable, probing available runtime APIs. */
-function read(name: string): string | undefined {
-  try {
-    if (typeof process !== 'undefined' && process?.env) return process.env[name] || undefined
-  } catch {}
-
-  try {
-    const deno = (globalThis as any).Deno
-    if (deno?.env?.get) return deno.env.get(name) || undefined
-  } catch {}
-
-  return undefined
-}

package/src/internal/types.test-d.ts

@@ -1,21 +0,0 @@
-import { expectTypeOf, test } from 'vp/test'
-
-import type { ConfiguredDefaults } from './types.js'
-
-test('ConfiguredDefaults retains only known defined values', () => {
-  type Parameters = {
-    configured: string
-    maybeDefined?: number | undefined
-    explicitlyUndefined: boolean | undefined
-    unrelated: bigint
-  }
-  type Defaults = {
-    configured?: string | undefined
-    maybeDefined?: number | undefined
-    explicitlyUndefined?: boolean | undefined
-  }
-
-  expectTypeOf<ConfiguredDefaults<Parameters, Defaults>>().toEqualTypeOf<{
-    configured: string
-  }>()
-})