mppx 0.0.1 → 0.1.0

package/src/Credential.ts

@@ -0,0 +1,154 @@
+import { Base64 } from 'ox'
+import * as Challenge from './Challenge.js'
+import * as PaymentRequest from './PaymentRequest.js'
+
+/**
+ * A payment credential containing the challenge and payment proof.
+ */
+export type Credential<
+  payload = unknown,
+  challenge extends Challenge.Challenge = Challenge.Challenge,
+> = {
+  /** The challenge from the 402 response. */
+  challenge: challenge
+  /** Method-specific payment proof. */
+  payload: payload
+  /** Optional payer identifier as a DID (e.g., "did:pkh:eip155:1:0x..."). */
+  source?: string
+}
+
+/**
+ * Deserializes an Authorization header value to a credential.
+ *
+ * @param header - The Authorization header value.
+ * @returns The deserialized credential.
+ *
+ * @example
+ * ```ts
+ * import { Credential } from 'mppx'
+ *
+ * const credential = Credential.deserialize(header)
+ * ```
+ */
+export function deserialize<payload = unknown>(value: string): Credential<payload> {
+  const prefixMatch = value.match(/^Payment\s+(.+)$/i)
+  if (!prefixMatch?.[1]) throw new Error('Missing Payment scheme.')
+  try {
+    const json = Base64.toString(prefixMatch[1])
+    const parsed = JSON.parse(json) as {
+      challenge: Omit<Challenge.Challenge, 'request'> & { request: string }
+      payload: payload
+      source?: string
+    }
+    const challenge = Challenge.Schema.parse({
+      ...parsed.challenge,
+      request: PaymentRequest.deserialize(parsed.challenge.request),
+    })
+    return {
+      challenge,
+      payload: parsed.payload,
+      ...(parsed.source && { source: parsed.source }),
+    } as Credential<payload>
+  } catch {
+    throw new Error('Invalid base64url or JSON.')
+  }
+}
+
+/**
+ * Creates a credential from the given parameters.
+ *
+ * @param parameters - Credential parameters with a Challenge object.
+ * @returns A credential.
+ *
+ * @example
+ * ```ts
+ * import { Credential, Challenge } from 'mppx'
+ *
+ * const credential = Credential.from({
+ *   challenge,
+ *   payload: { signature: '0x...' },
+ * })
+ * ```
+ */
+export function from<const parameters extends from.Parameters>(
+  parameters: parameters,
+): Credential<parameters['payload'], parameters['challenge']> {
+  const { challenge, payload, source } = parameters
+  return {
+    challenge,
+    payload,
+    ...(source && { source }),
+  } as Credential<parameters['payload'], parameters['challenge']>
+}
+
+export declare namespace from {
+  type Parameters = {
+    /** The challenge from the 402 response. */
+    challenge: Challenge.Challenge
+    /** Method-specific payment proof. */
+    payload: unknown
+    /** Optional payer identifier as a DID (e.g., "did:pkh:eip155:1:0x..."). */
+    source?: string
+  }
+}
+
+/**
+ * Extracts the credential from a Request's Authorization header.
+ *
+ * @param request - The HTTP request.
+ * @returns The deserialized credential.
+ *
+ * @example
+ * ```ts
+ * import { Credential } from 'mppx'
+ *
+ * const credential = Credential.fromRequest(request)
+ * ```
+ */
+export function fromRequest<payload = unknown>(request: Request): Credential<payload> {
+  const header = request.headers.get('Authorization')
+  if (!header) throw new Error('Missing Authorization header.')
+  const payment = extractPaymentScheme(header)
+  if (!payment) throw new Error('Missing Payment scheme.')
+  return deserialize<payload>(payment)
+}
+
+/**
+ * Serializes a credential to the Authorization header format.
+ *
+ * @param credential - The credential to serialize.
+ * @returns A string suitable for the Authorization header value.
+ *
+ * @example
+ * ```ts
+ * import { Credential } from 'mppx'
+ *
+ * const header = Credential.serialize(credential)
+ * // => 'Payment eyJjaGFsbGVuZ2UiOnsi...'
+ * ```
+ */
+export function serialize(credential: Credential): string {
+  const wire = {
+    challenge: {
+      ...credential.challenge,
+      request: PaymentRequest.serialize(credential.challenge.request),
+    },
+    payload: credential.payload,
+    ...(credential.source && { source: credential.source }),
+  }
+  const json = JSON.stringify(wire)
+  const encoded = Base64.fromString(json, { pad: false, url: true })
+  return `Payment ${encoded}`
+}
+
+/**
+ * Extracts the `Payment` scheme from an Authorization header value
+ * that may contain multiple schemes (comma-separated per RFC 9110).
+ *
+ * @param header - The raw Authorization header value.
+ * @returns The `Payment ...` scheme string, or `null` if not found.
+ */
+export function extractPaymentScheme(header: string): string | null {
+  const schemes = header.split(',').map((s) => s.trim())
+  return schemes.find((s) => /^Payment\s+/i.test(s)) ?? null
+}

package/src/Errors.test.ts

@@ -0,0 +1,402 @@
+import { describe, expect, test } from 'vitest'
+import {
+  AmountExceedsDepositError,
+  BadRequestError,
+  ChannelClosedError,
+  ChannelNotFoundError,
+  DeltaTooSmallError,
+  InsufficientBalanceError,
+  InvalidChallengeError,
+  InvalidPayloadError,
+  InvalidSignatureError,
+  MalformedCredentialError,
+  PaymentExpiredError,
+  PaymentRequiredError,
+  SignerMismatchError,
+  VerificationFailedError,
+} from './Errors.js'
+
+function errorSnapshot(error: Error & { type: string; status: number }) {
+  return {
+    name: error.name,
+    message: error.message,
+    type: error.type,
+    status: error.status,
+  }
+}
+
+describe('MalformedCredentialError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new MalformedCredentialError())).toMatchInlineSnapshot(`
+      {
+        "message": "Credential is malformed.",
+        "name": "MalformedCredentialError",
+        "status": 402,
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/malformed-credential",
+      }
+    `)
+  })
+
+  test('with reason', () => {
+    expect(
+      errorSnapshot(new MalformedCredentialError({ reason: 'invalid base64url' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Credential is malformed: invalid base64url.",
+          "name": "MalformedCredentialError",
+          "status": 402,
+          "type": "https://tempoxyz.github.io/payment-auth-spec/problems/malformed-credential",
+        }
+      `)
+  })
+})
+
+describe('InvalidChallengeError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new InvalidChallengeError())).toMatchInlineSnapshot(`
+      {
+        "message": "Challenge is invalid.",
+        "name": "InvalidChallengeError",
+        "status": 402,
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-challenge",
+      }
+    `)
+  })
+
+  test('with id', () => {
+    expect(errorSnapshot(new InvalidChallengeError({ id: 'abc123' }))).toMatchInlineSnapshot(`
+      {
+        "message": "Challenge "abc123" is invalid.",
+        "name": "InvalidChallengeError",
+        "status": 402,
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-challenge",
+      }
+    `)
+  })
+
+  test('with reason', () => {
+    expect(errorSnapshot(new InvalidChallengeError({ reason: 'expired' }))).toMatchInlineSnapshot(`
+      {
+        "message": "Challenge is invalid: expired.",
+        "name": "InvalidChallengeError",
+        "status": 402,
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-challenge",
+      }
+    `)
+  })
+
+  test('with id and reason', () => {
+    expect(
+      errorSnapshot(new InvalidChallengeError({ id: 'abc123', reason: 'already used' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Challenge "abc123" is invalid: already used.",
+          "name": "InvalidChallengeError",
+          "status": 402,
+          "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-challenge",
+        }
+      `)
+  })
+})
+
+describe('VerificationFailedError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new VerificationFailedError())).toMatchInlineSnapshot(`
+      {
+        "message": "Payment verification failed.",
+        "name": "VerificationFailedError",
+        "status": 402,
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/verification-failed",
+      }
+    `)
+  })
+
+  test('with reason', () => {
+    expect(
+      errorSnapshot(new VerificationFailedError({ reason: 'invalid signature' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Payment verification failed: invalid signature.",
+          "name": "VerificationFailedError",
+          "status": 402,
+          "type": "https://tempoxyz.github.io/payment-auth-spec/problems/verification-failed",
+        }
+      `)
+  })
+})
+
+describe('PaymentExpiredError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new PaymentExpiredError())).toMatchInlineSnapshot(`
+      {
+        "message": "Payment has expired.",
+        "name": "PaymentExpiredError",
+        "status": 402,
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/payment-expired",
+      }
+    `)
+  })
+
+  test('with expires', () => {
+    expect(
+      errorSnapshot(new PaymentExpiredError({ expires: '2025-01-26T12:00:00Z' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Payment expired at 2025-01-26T12:00:00Z.",
+          "name": "PaymentExpiredError",
+          "status": 402,
+          "type": "https://tempoxyz.github.io/payment-auth-spec/problems/payment-expired",
+        }
+      `)
+  })
+})
+
+describe('PaymentRequiredError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new PaymentRequiredError())).toMatchInlineSnapshot(`
+      {
+        "message": "Payment is required.",
+        "name": "PaymentRequiredError",
+        "status": 402,
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/payment-required",
+      }
+    `)
+  })
+
+  test('with realm', () => {
+    expect(
+      errorSnapshot(new PaymentRequiredError({ realm: 'api.example.com' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Payment is required for "api.example.com".",
+          "name": "PaymentRequiredError",
+          "status": 402,
+          "type": "https://tempoxyz.github.io/payment-auth-spec/problems/payment-required",
+        }
+      `)
+  })
+
+  test('with realm and description', () => {
+    expect(
+      errorSnapshot(
+        new PaymentRequiredError({ realm: 'api.example.com', description: 'API access fee' }),
+      ),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Payment is required for "api.example.com" (API access fee).",
+          "name": "PaymentRequiredError",
+          "status": 402,
+          "type": "https://tempoxyz.github.io/payment-auth-spec/problems/payment-required",
+        }
+      `)
+  })
+})
+
+describe('InvalidPayloadError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new InvalidPayloadError())).toMatchInlineSnapshot(`
+      {
+        "message": "Credential payload is invalid.",
+        "name": "InvalidPayloadError",
+        "status": 402,
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-payload",
+      }
+    `)
+  })
+
+  test('with reason', () => {
+    expect(
+      errorSnapshot(new InvalidPayloadError({ reason: 'missing signature field' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Credential payload is invalid: missing signature field.",
+          "name": "InvalidPayloadError",
+          "status": 402,
+          "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-payload",
+        }
+      `)
+  })
+})
+
+describe('BadRequestError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new BadRequestError())).toMatchInlineSnapshot(`
+      {
+        "message": "Bad request.",
+        "name": "BadRequestError",
+        "status": 400,
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/bad-request",
+      }
+    `)
+  })
+
+  test('with reason', () => {
+    expect(
+      errorSnapshot(new BadRequestError({ reason: 'cannot combine hash type with feePayer' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Bad request: cannot combine hash type with feePayer.",
+          "name": "BadRequestError",
+          "status": 400,
+          "type": "https://tempoxyz.github.io/payment-auth-spec/problems/bad-request",
+        }
+      `)
+  })
+})
+
+describe('InsufficientBalanceError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new InsufficientBalanceError())).toMatchInlineSnapshot(`
+      {
+        "message": "Insufficient balance.",
+        "name": "InsufficientBalanceError",
+        "status": 402,
+        "type": "https://paymentauth.org/problems/stream/insufficient-balance",
+      }
+    `)
+  })
+
+  test('with reason', () => {
+    expect(
+      errorSnapshot(new InsufficientBalanceError({ reason: 'requested 500, available 100' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Insufficient balance: requested 500, available 100.",
+          "name": "InsufficientBalanceError",
+          "status": 402,
+          "type": "https://paymentauth.org/problems/stream/insufficient-balance",
+        }
+      `)
+  })
+})
+
+describe('InvalidSignatureError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new InvalidSignatureError())).toMatchInlineSnapshot(`
+      {
+        "message": "Invalid signature.",
+        "name": "InvalidSignatureError",
+        "status": 402,
+        "type": "https://paymentauth.org/problems/stream/invalid-signature",
+      }
+    `)
+  })
+
+  test('with reason', () => {
+    expect(
+      errorSnapshot(new InvalidSignatureError({ reason: 'ECDSA recovery failed' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Invalid signature: ECDSA recovery failed.",
+          "name": "InvalidSignatureError",
+          "status": 402,
+          "type": "https://paymentauth.org/problems/stream/invalid-signature",
+        }
+      `)
+  })
+})
+
+describe('SignerMismatchError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new SignerMismatchError())).toMatchInlineSnapshot(`
+      {
+        "message": "Signer is not authorized for this channel.",
+        "name": "SignerMismatchError",
+        "status": 402,
+        "type": "https://paymentauth.org/problems/stream/signer-mismatch",
+      }
+    `)
+  })
+})
+
+describe('AmountExceedsDepositError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new AmountExceedsDepositError())).toMatchInlineSnapshot(`
+      {
+        "message": "Voucher amount exceeds channel deposit.",
+        "name": "AmountExceedsDepositError",
+        "status": 402,
+        "type": "https://paymentauth.org/problems/stream/amount-exceeds-deposit",
+      }
+    `)
+  })
+})
+
+describe('DeltaTooSmallError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new DeltaTooSmallError())).toMatchInlineSnapshot(`
+      {
+        "message": "Amount increase below minimum voucher delta.",
+        "name": "DeltaTooSmallError",
+        "status": 402,
+        "type": "https://paymentauth.org/problems/stream/delta-too-small",
+      }
+    `)
+  })
+})
+
+describe('ChannelNotFoundError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new ChannelNotFoundError())).toMatchInlineSnapshot(`
+      {
+        "message": "No channel with this ID exists.",
+        "name": "ChannelNotFoundError",
+        "status": 410,
+        "type": "https://paymentauth.org/problems/stream/channel-not-found",
+      }
+    `)
+  })
+})
+
+describe('ChannelClosedError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new ChannelClosedError())).toMatchInlineSnapshot(`
+      {
+        "message": "Channel is closed.",
+        "name": "ChannelClosedError",
+        "status": 410,
+        "type": "https://paymentauth.org/problems/stream/channel-finalized",
+      }
+    `)
+  })
+
+  test('with reason', () => {
+    expect(
+      errorSnapshot(new ChannelClosedError({ reason: 'channel is finalized on-chain' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Channel closed: channel is finalized on-chain.",
+          "name": "ChannelClosedError",
+          "status": 410,
+          "type": "https://paymentauth.org/problems/stream/channel-finalized",
+        }
+      `)
+  })
+})
+
+describe('toProblemDetails', () => {
+  test('without challengeId', () => {
+    const error = new MalformedCredentialError({ reason: 'invalid JSON' })
+    expect(error.toProblemDetails()).toMatchInlineSnapshot(`
+      {
+        "detail": "Credential is malformed: invalid JSON.",
+        "status": 402,
+        "title": "MalformedCredentialError",
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/malformed-credential",
+      }
+    `)
+  })
+
+  test('with challengeId', () => {
+    const error = new InvalidChallengeError({ id: 'abc123', reason: 'expired' })
+    expect(error.toProblemDetails('abc123')).toMatchInlineSnapshot(`
+      {
+        "challengeId": "abc123",
+        "detail": "Challenge "abc123" is invalid: expired.",
+        "status": 402,
+        "title": "InvalidChallengeError",
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-challenge",
+      }
+    `)
+  })
+})