mppx 0.8.17 → 0.8.18

package/src/attestation/Client.ts

@@ -1,34 +0,0 @@
-import * as SigningContext from './internal/SigningContext.js'
-import type * as Types from './Types.js'
-
-/**
- * Combines request signers using one shared context per call.
- *
- * The returned signer creates a fresh context unless its caller supplies one,
- * allowing every signature on one HTTP attempt to share a nonce and timestamp.
- */
-export function composeSigners(
-  ...signers: readonly [Types.Signer, ...Types.Signer[]]
-): Types.Signer<'composed'> {
-  return {
-    protocol: 'composed',
-    async sign(request, context = SigningContext.create()) {
-      for (const signer of signers) request = await signer.sign(request, context)
-      return request
-    },
-  }
-}
-
-/**
- * Wraps a fetch implementation so every outbound request is attested.
- *
- * Configure this wrapper as the underlying `fetch` passed to `mppx/client`
- * `Fetch.from()`. MPPX then uses it for both the initial request and its
- * automatic request containing an `Authorization: Payment` credential.
- */
-export function wrapFetch(
-  fetch: typeof globalThis.fetch,
-  signer: Types.Signer,
-): typeof globalThis.fetch {
-  return async (input, init) => fetch(await signer.sign(new Request(input, init)))
-}

package/src/attestation/Constants.ts

@@ -1,15 +0,0 @@
-/** RFC 9421 signature algorithms supported by request attestation. */
-export const Algorithms = {
-  /** EdDSA using the Ed25519 curve. */
-  ed25519: 'ed25519',
-  /** RSASSA-PSS using SHA-512 and a 64-byte salt. */
-  rsaPssSha512: 'rsa-pss-sha512',
-} as const
-
-/** HTTP headers defined by RFC 9421 for request-attestation signatures. */
-export const Headers = {
-  /** Carries the RFC 9421 signature bytes. */
-  signature: 'Signature',
-  /** Carries the RFC 9421 covered components and signature parameters. */
-  signatureInput: 'Signature-Input',
-} as const

package/src/attestation/Server.test.ts

@@ -1,60 +0,0 @@
-import * as Attestation from 'mppx/attestation'
-import * as Tap from 'mppx/attestation/tap'
-import * as WebBotAuth from 'mppx/attestation/web-bot-auth'
-import { expect, test } from 'vp/test'
-import { jwkThumbprint, keyPair } from '~test/Attestation.js'
-
-test('returns typed protocol outcomes and namespaces shared nonces', async () => {
-  const keys = await keyPair()
-  const keyId = await jwkThumbprint(keys.publicKey)
-  const signatureAgent = 'https://agent.example'
-  const signed = await Attestation.Client.composeSigners(
-    WebBotAuth.Client.signer({ key: keys.privateKey, keyId, signatureAgent }),
-    Tap.Client.signer({
-      intent: Tap.Constants.intents.payment,
-      key: keys.privateKey,
-      keyId,
-    }),
-  ).sign(new Request('https://merchant.example/resource'))
-  const consumed = new Set<string>()
-  const backing = Attestation.Store.memory()
-  const nonceStore: Attestation.Store.AtomicStore = {
-    ...backing,
-    tryClaim(key, expires) {
-      consumed.add(key)
-      return Attestation.Store.tryClaim(backing, key, expires)
-    },
-  }
-  const verifiers = {
-    tap: Tap.Server.verifier({
-      keyResolver: ({ keyId: candidate }) => (candidate === keyId ? keys.publicKey : undefined),
-      nonceStore,
-    }),
-    webBotAuth: WebBotAuth.Server.verifier({
-      keyResolver: ({ keyId: candidate, signatureAgent: candidateAgent }) =>
-        candidate === keyId && candidateAgent === signatureAgent ? keys.publicKey : undefined,
-      nonceStore,
-    }),
-  }
-
-  const verified = await Attestation.Server.verify(signed, verifiers)
-  expect(verified.tap).toMatchObject({
-    status: 'verified',
-    value: { intent: Tap.Constants.intents.payment, keyId },
-  })
-  expect(verified.webBotAuth).toMatchObject({
-    status: 'verified',
-    value: { keyId, signatureAgent },
-  })
-  expect([...consumed].some((value) => value.startsWith(`${Tap.Constants.protocol}:`))).toBe(true)
-  expect([...consumed].some((value) => value.startsWith(`${WebBotAuth.Constants.protocol}:`))).toBe(
-    true,
-  )
-
-  const replay = await Attestation.Server.verify(signed, verifiers)
-  for (const outcome of Object.values(replay))
-    expect(outcome).toEqual({
-      reason: 'The signature nonce has already been used.',
-      status: 'invalid',
-    })
-})

package/src/attestation/Server.ts

@@ -1,12 +0,0 @@
-import type * as Types from './Types.js'
-
-/** Verifies every configured request-attestation protocol. */
-export async function verify<const verifiers extends Types.VerifierMap>(
-  request: Request,
-  verifiers: verifiers,
-): Promise<Types.VerificationsFrom<verifiers>> {
-  const outcomes: Record<string, Types.Verification> = {}
-  for (const [name, verifier] of Object.entries(verifiers))
-    outcomes[name] = await verifier.verify(request)
-  return outcomes as Types.VerificationsFrom<verifiers>
-}

package/src/attestation/Types.test-d.ts

@@ -1,54 +0,0 @@
-import * as Attestation from 'mppx/attestation'
-import * as Tap from 'mppx/attestation/tap'
-import { expectTypeOf, test } from 'vp/test'
-
-test('types: request signers compose with an optional shared context', () => {
-  const first: Attestation.Signer<'first'> = {
-    protocol: 'first',
-    sign: (request) => request,
-  }
-  const second: Attestation.Signer<'second'> = {
-    protocol: 'second',
-    sign: (request) => request,
-  }
-  const signer = Attestation.Client.composeSigners(first, second)
-
-  expectTypeOf(signer).toMatchTypeOf<Attestation.Signer>()
-  expectTypeOf<Parameters<typeof signer.sign>[1]>().toEqualTypeOf<
-    Attestation.SigningContext | undefined
-  >()
-
-  // @ts-expect-error at least one signer is required
-  Attestation.Client.composeSigners()
-})
-
-test('types: server verification preserves each protocol value', () => {
-  const tapVerifier: Attestation.Verifier<Tap.VerifiedRequest> = {
-    verify: () => ({ status: 'absent' }),
-  }
-  const verifiers = { tap: tapVerifier } as const
-  const verification = Attestation.Server.verify(
-    new Request('https://merchant.example/resource'),
-    verifiers,
-  )
-
-  expectTypeOf<Awaited<typeof verification>['tap']>().toEqualTypeOf<
-    Attestation.Verification<Tap.VerifiedRequest>
-  >()
-})
-
-test('types: server verifiers require explicit replay storage and expose the algorithm', () => {
-  const nonceStore = Attestation.Store.memory()
-  expectTypeOf(nonceStore).toEqualTypeOf<Attestation.Store.AtomicStore>()
-
-  Tap.Server.verifier({
-    keyResolver({ algorithm }) {
-      expectTypeOf(algorithm).toEqualTypeOf<Attestation.SignatureAlgorithm>()
-      return undefined
-    },
-    nonceStore,
-  })
-
-  // @ts-expect-error replay storage must be chosen explicitly
-  Tap.Server.verifier({ keyResolver: () => undefined })
-})

package/src/attestation/Types.ts

@@ -1,77 +0,0 @@
-import type { MaybePromise } from '../internal/types.js'
-import type { Algorithms } from './Constants.js'
-
-/** RFC 9421 algorithms implemented by the request-attestation signer and verifier. */
-export type SignatureAlgorithm = (typeof Algorithms)[keyof typeof Algorithms]
-
-/** Resolves a trusted public key for a parsed request signature. */
-export type KeyResolver = (parameters: {
-  /** RFC 9421 algorithm declared by the signature. */
-  algorithm: SignatureAlgorithm
-  /** Key identifier declared by the signature. */
-  keyId: string
-  /** Request carrying the signature. */
-  request: Request
-}) => MaybePromise<CryptoKey | undefined>
-
-/**
- * The complete outcome of attempting one protocol verifier.
- *
- * `absent` means the protocol did not appear on the request. `invalid` means
- * it appeared but failed validation and must reject the request. `unverified`
- * means key material or another required verification dependency was unavailable.
- * `verified` carries protocol-specific data that is safe for callers to inspect.
- */
-export type Verification<value = unknown> =
-  | { status: 'absent' }
-  | { status: 'invalid'; reason: string }
-  | { status: 'unverified'; reason: string }
-  | { status: 'verified'; value: value }
-
-/**
- * Verifies one request-attestation protocol carried by an HTTP request.
- *
- * Verifiers are registered in a {@link VerifierMap}; each map key names the
- * result returned to the caller.
- */
-export type Verifier<value = unknown> = {
-  /** Validates the request and returns a complete protocol verification outcome. */
-  verify: (request: Request) => MaybePromise<Verification<value>>
-}
-
-/** Maps each recognized protocol name to its verifier. */
-export type VerifierMap = Readonly<Record<string, Verifier>>
-
-/** Preserves each configured protocol's complete verification outcome. */
-export type VerificationsFrom<verifiers extends VerifierMap> = {
-  readonly [protocol in keyof verifiers]: Awaited<ReturnType<verifiers[protocol]['verify']>>
-}
-
-/**
- * Values shared by every signer contributing to one HTTP request attempt.
- *
- * A caller may reuse this context across independent signature protocols so
- * they describe the same attempt. A later network retry must use a new context.
- */
-export type SigningContext = {
-  /** Unix timestamp, in seconds, at which the request attempt was created. */
-  readonly created: number
-  /** Base64url-encoded random value identifying this request attempt. */
-  readonly nonce: string
-}
-
-/**
- * Signs each outbound HTTP request, including MPP payment retries.
- *
- * The protocol type preserves which adapter produced the signer for diagnostics
- * and composition, without asserting that the signer alone authorizes payment.
- */
-export type Signer<protocol extends string = string> = {
-  /** Protocol identifier used for diagnostics. */
-  protocol: protocol
-  /** Returns a new request containing the protocol's signature material. */
-  sign: (request: Request, context?: SigningContext | undefined) => MaybePromise<Request>
-}
-
-/** Maps application-defined names to request-attestation signers. */
-export type SignerMap = Readonly<Record<string, Signer>>

package/src/attestation/index.ts

@@ -1,5 +0,0 @@
-export * as Client from './Client.js'
-export * as Server from './Server.js'
-export * as Store from '../Store.js'
-export * from './Constants.js'
-export * from './Types.js'

package/src/attestation/internal/HttpMessageSignature.test.ts

@@ -1,101 +0,0 @@
-import { describe, expect, test } from 'vp/test'
-import { keyPair } from '~test/Attestation.js'
-
-import * as Store from '../../Store.js'
-import { Algorithms, Headers } from '../Constants.js'
-import * as HttpMessageSignature from './HttpMessageSignature.js'
-
-const signatureAgent = 'agent2="https://signature-agent.test"'
-const maximumVectorLifetime = 3_153_600_000
-
-describe('Web Bot Auth draft test vectors', () => {
-  test('verifies the Ed25519 Signature-Agent vector', async () => {
-    const key = await crypto.subtle.importKey(
-      'jwk',
-      {
-        crv: 'Ed25519',
-        kty: 'OKP',
-        x: 'JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs',
-      },
-      'Ed25519',
-      true,
-      ['verify'],
-    )
-    const request = vectorRequest({
-      input:
-        'sig2=("@authority" "signature-agent";key="agent2");created=1735689600;keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";alg="ed25519";expires=4889289600;nonce="n9p433xm+NJ3ph3upfBIGmsuwHw387YV7Q/F+6BSpGCVjYCqQw6rznNA8PVVLySrAWsv0hQtFioQb6E1YsauiA==";tag="web-bot-auth"',
-      signature:
-        'sig2=:RdNFx5Bj6au3YgAMQL/RzmUlZE8QZLIaXGRpw985hWnwPfMxT228NMk6ehRS1PSl4e8PhbNZACSanGdhEwYCCg==:',
-    })
-
-    expect(await verifyVector(request, key)).toMatchObject({ status: 'verified' })
-  })
-
-  test('verifies the RSA-PSS SHA-512 Signature-Agent vector', async () => {
-    const spki = Buffer.from(
-      'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr4tmm3r20Wd/PbqvP1s2+QEtvpuRaV8Yq40gjUR8y2Rjxa6dpG2GXHbPfvMs8ct+Lh1GH45x28Rw3Ry53mm+oAXjyQ86OnDkZ5N8lYbggD4O3w6M6pAvLkhk95AndTrifbIFPNU8PPMO7OyrFAHqgDsznjPFmTOtCEcN2Z1FpWgchwuYLPL+Wokqltd11nqqzi+bJ9cvSKADYdUAAN5WUtzdpiy6LbTgSxP7ociU4Tn0g5I6aDZJ7A8Lzo0KSyZYoA485mqcO0GVAdVw9lq4aOT9v6d+nb4bnNkQVklLQ3fVAvJm+xdDOp9LCNCN48V2pnDOkFV6+U9nV5oyc6XI2wIDAQAB',
-      'base64',
-    )
-    const key = await crypto.subtle.importKey(
-      'spki',
-      new Uint8Array(spki),
-      { hash: 'SHA-512', name: 'RSA-PSS' },
-      true,
-      ['verify'],
-    )
-    const request = vectorRequest({
-      input:
-        'sig2=("@authority" "signature-agent";key="agent2");created=1735689600;keyid="oD0HwocPBSfpNy5W3bpJeyFGY_IQ_YpqxSjQ3Yd-CLA";alg="rsa-pss-sha512";expires=4889289600;nonce="wcfPQPh7SzkvrIVvhD00vNk9PkxJNY2NVbYl2PVBB4zmUoluSwE7W6bPtF60QA3k8g06FU7PPCD+J58YofY1zg==";tag="web-bot-auth"',
-      signature:
-        'sig2=:gHzpLNeHaHIO19NaJH9YMW5dcVSi2s0wOMBr6p18vcofS106sfC4KBIS0/szPlBBd1vIcyQ88B6CTEWIhRAiVrb9zfX0mx1aG12CSGWcYkSirHeyTxhbuJvXd27ed6skWoy4PjXItq38936ivUQjfdIwXh1aX6HxkAC3vRnEdSNfntkLWeEuIQ5BLIOBGE39fSwg27Qjq6OVWYas/9/aFUr3HA34MXWYdp+//cvlEKDp3kRoLOw9ro0AOr6srHrTeEtxon2afcws1aZVSlPdd2fZSEIGmw9HAHLDCEkFTERu1gH2k/zIEqgy7CAYXI9E5slog0cLg/Vc6+f8gih33g==:',
-    })
-
-    expect(await verifyVector(request, key)).toMatchObject({ status: 'verified' })
-  })
-})
-
-test('rejects non-ASCII signed HTTP header values', async () => {
-  const keys = await keyPair()
-  await expect(
-    HttpMessageSignature.sign(
-      new Request('https://example.com', { headers: { 'X-Example': 'café' } }),
-      {
-        components: ['x-example'],
-        key: keys.privateKey,
-        keyId: 'test-key',
-        label: 'test',
-        tag: 'test',
-      },
-    ),
-  ).rejects.toThrow('Signed HTTP header "x-example" is not ASCII.')
-})
-
-function vectorRequest(parameters: { input: string; signature: string }): Request {
-  return new Request('https://example.com/foo?param=Value&Pet=dog', {
-    headers: {
-      [Headers.signature]: parameters.signature,
-      [Headers.signatureInput]: parameters.input,
-      'Signature-Agent': signatureAgent,
-    },
-    method: 'POST',
-  })
-}
-
-function verifyVector(request: Request, key: CryptoKey) {
-  return HttpMessageSignature.verify(request, {
-    keyResolver({ algorithm }) {
-      expect(algorithm).toBe(
-        key.algorithm.name === 'Ed25519' ? Algorithms.ed25519 : Algorithms.rsaPssSha512,
-      )
-      return key
-    },
-    maxAge: maximumVectorLifetime,
-    nonceNamespace: 'web-bot-auth',
-    nonceStore: Store.memory(),
-    requiredComponents: [
-      HttpMessageSignature.Constants.components.authority,
-      HttpMessageSignature.Constants.components.signatureAgent,
-    ],
-    tag: 'web-bot-auth',
-  })
-}