mppx 0.8.14 → 0.8.17

package/src/attestation/Client.test.ts

@@ -0,0 +1,83 @@
+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('shares one immutable context and composes signature dictionaries', async () => {
+  const tapKeys = await keyPair()
+  const webBotAuthKeys = await keyPair()
+  const webBotAuthKeyId = await jwkThumbprint(webBotAuthKeys.publicKey)
+  const tapSigner = Tap.Client.signer({
+    intent: Tap.Constants.intents.payment,
+    key: tapKeys.privateKey,
+    keyId: 'tap-agent',
+  })
+  const webBotAuthSigner = WebBotAuth.Client.signer({
+    key: webBotAuthKeys.privateKey,
+    keyId: webBotAuthKeyId,
+    signatureAgent: 'https://agent.example',
+  })
+
+  for (const signers of [
+    [webBotAuthSigner, tapSigner],
+    [tapSigner, webBotAuthSigner],
+  ] as const) {
+    const contexts: Attestation.SigningContext[] = []
+    const observingSigners = signers.map((signer) => ({
+      ...signer,
+      sign(request: Request, context?: Attestation.SigningContext) {
+        if (context) contexts.push(context)
+        return signer.sign(request, context)
+      },
+    })) as [Attestation.Signer, Attestation.Signer]
+    const signed = await Attestation.Client.composeSigners(...observingSigners).sign(
+      new Request('https://merchant.example/resource'),
+    )
+
+    expect(contexts).toHaveLength(2)
+    expect(contexts[0]).toBe(contexts[1])
+    expect(Object.isFrozen(contexts[0])).toBe(true)
+    const input = signed.headers.get(Attestation.Headers.signatureInput) ?? ''
+    const signature = signed.headers.get(Attestation.Headers.signature) ?? ''
+    expect(input).toContain(`${WebBotAuth.Constants.label}=`)
+    expect(input).toContain(`${Tap.Constants.label}=`)
+    expect(signature).toContain(`${WebBotAuth.Constants.label}=`)
+    expect(signature).toContain(`${Tap.Constants.label}=`)
+  }
+})
+
+test('rejects duplicate and mismatched signature labels', async () => {
+  const tapKeys = await keyPair()
+  const webBotAuthKeys = await keyPair()
+  const webBotAuthKeyId = await jwkThumbprint(webBotAuthKeys.publicKey)
+  const signer = Attestation.Client.composeSigners(
+    WebBotAuth.Client.signer({
+      key: webBotAuthKeys.privateKey,
+      keyId: webBotAuthKeyId,
+      label: 'agent',
+      signatureAgent: 'https://agent.example',
+    }),
+    Tap.Client.signer({
+      intent: Tap.Constants.intents.payment,
+      key: tapKeys.privateKey,
+      keyId: 'tap-agent',
+      label: 'agent',
+    }),
+  )
+
+  await expect(signer.sign(new Request('https://merchant.example/resource'))).rejects.toThrow(
+    'HTTP message signature label "agent" already exists.',
+  )
+  await expect(
+    Tap.Client.signer({
+      intent: Tap.Constants.intents.payment,
+      key: tapKeys.privateKey,
+      keyId: 'tap-agent',
+    }).sign(
+      new Request('https://merchant.example/resource', {
+        headers: { [Attestation.Headers.signatureInput]: 'orphan=("@authority")' },
+      }),
+    ),
+  ).rejects.toThrow('Signature-Input and Signature must contain the same labels.')
+})

package/src/attestation/Client.ts

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,15 @@
+/** 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

@@ -0,0 +1,60 @@
+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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,54 @@
+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

@@ -0,0 +1,77 @@
+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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,101 @@
+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',
+  })
+}