mppx 0.8.15 → 0.8.17

package/src/web-bot-auth/Types.ts

@@ -0,0 +1,9 @@
+/** Verified Web Bot Auth HTTPS-directory profile request signature. */
+export type VerifiedRequest = {
+  /** Public-key thumbprint advertised by the bot. */
+  keyId: string
+  /** HTTPS directory origin carried in the signed `Signature-Agent` header. */
+  signatureAgent: string
+  /** Signature nonce supplied by the bot. */
+  nonce: string
+}

package/src/web-bot-auth/WebBotAuth.test.ts

@@ -0,0 +1,182 @@
+import * as Attestation from 'mppx/attestation'
+import * as WebBotAuth from 'mppx/attestation/web-bot-auth'
+import { expect, test } from 'vp/test'
+import { jwkThumbprint, keyPair, rsaKeyPair } from '~test/Attestation.js'
+
+import * as HttpMessageSignature from '../attestation/internal/HttpMessageSignature.js'
+
+test('emits and verifies a signed Signature-Agent member', async () => {
+  const keys = await keyPair()
+  const keyId = await jwkThumbprint(keys.publicKey)
+  const signatureAgent = 'https://agent.example'
+  const signed = await WebBotAuth.Client.signer({
+    expiresIn: WebBotAuth.Constants.defaultSignatureLifetime + 1,
+    key: keys.privateKey,
+    keyId,
+    signatureAgent: `${signatureAgent}/`,
+  }).sign(new Request('https://merchant.example/resource'))
+
+  expect(signed.headers.get(WebBotAuth.Constants.signatureAgentHeader)).toBe(
+    `${WebBotAuth.Constants.label}="${signatureAgent}"`,
+  )
+  expect(signed.headers.get(Attestation.Headers.signatureInput)).toContain(
+    `"signature-agent";key="${WebBotAuth.Constants.label}"`,
+  )
+  expect(
+    await WebBotAuth.Server.verifier({
+      keyResolver: () => keys.publicKey,
+      maxAge: WebBotAuth.Constants.defaultSignatureLifetime,
+      nonceStore: Attestation.Store.memory(),
+    }).verify(signed),
+  ).toMatchObject({ status: 'invalid' })
+  expect(
+    await WebBotAuth.Server.verifier({
+      keyResolver: () => keys.publicKey,
+      nonceStore: Attestation.Store.memory(),
+    }).verify(signed),
+  ).toMatchObject({
+    status: 'verified',
+    value: { keyId, signatureAgent },
+  })
+})
+
+test('signs and verifies RSA-PSS SHA-512', async () => {
+  const keys = await rsaKeyPair()
+  const keyId = await jwkThumbprint(keys.publicKey)
+  const algorithms: Attestation.SignatureAlgorithm[] = []
+  const signed = await WebBotAuth.Client.signer({
+    key: keys.privateKey,
+    keyId,
+    signatureAgent: 'https://agent.example',
+  }).sign(new Request('https://merchant.example/resource'))
+  const result = await WebBotAuth.Server.verifier({
+    keyResolver({ algorithm, keyId: candidate }) {
+      algorithms.push(algorithm)
+      return candidate === keyId ? keys.publicKey : undefined
+    },
+    nonceStore: Attestation.Store.memory(),
+  }).verify(signed)
+
+  expect(signed.headers.get(Attestation.Headers.signatureInput)).toContain(
+    `alg="${Attestation.Algorithms.rsaPssSha512}"`,
+  )
+  expect(algorithms).toEqual([Attestation.Algorithms.rsaPssSha512])
+  expect(result).toMatchObject({ status: 'verified' })
+})
+
+test('preserves directory lookup failures as unverified outcomes', async () => {
+  const keys = await keyPair()
+  const keyId = await jwkThumbprint(keys.publicKey)
+  const signed = await WebBotAuth.Client.signer({
+    key: keys.privateKey,
+    keyId,
+    signatureAgent: 'https://agent.example',
+  }).sign(new Request('https://merchant.example/resource'))
+
+  expect(
+    await WebBotAuth.Server.verifier({
+      keyResolver: () => undefined,
+      nonceStore: Attestation.Store.memory(),
+    }).verify(signed),
+  ).toEqual({
+    reason: 'No public key is available for the signature key ID.',
+    status: 'unverified',
+  })
+  expect(
+    await WebBotAuth.Server.verifier({
+      keyResolver() {
+        throw new Error('directory unavailable')
+      },
+      nonceStore: Attestation.Store.memory(),
+    }).verify(signed),
+  ).toEqual({
+    reason: 'The public key could not be resolved.',
+    status: 'unverified',
+  })
+})
+
+test('rejects mismatched keys, non-directory discovery, and header tampering', async () => {
+  const advertisedKeys = await keyPair()
+  const signingKeys = await keyPair()
+  const advertisedKeyId = await jwkThumbprint(advertisedKeys.publicKey)
+  const signatureAgent = 'https://agent.example'
+  const signed = await WebBotAuth.Client.signer({
+    key: signingKeys.privateKey,
+    keyId: advertisedKeyId,
+    signatureAgent,
+  }).sign(new Request('https://merchant.example/resource'))
+  const verifier = WebBotAuth.Server.verifier({
+    keyResolver: () => signingKeys.publicKey,
+    nonceStore: Attestation.Store.memory(),
+  })
+
+  expect(await verifier.verify(signed)).toMatchObject({ status: 'invalid' })
+
+  const alteredHeaders = new Headers(signed.headers)
+  alteredHeaders.set(
+    WebBotAuth.Constants.signatureAgentHeader,
+    `${WebBotAuth.Constants.label}="https://attacker.example"`,
+  )
+  expect(
+    await WebBotAuth.Server.verifier({
+      keyResolver: () => signingKeys.publicKey,
+      nonceStore: Attestation.Store.memory(),
+    }).verify(new Request(signed, { headers: alteredHeaders })),
+  ).toMatchObject({ status: 'invalid' })
+
+  const discoveryHeaders = new Headers({
+    [WebBotAuth.Constants.signatureAgentHeader]:
+      'webbot="https://agent.example/keys";type=jwks_uri',
+  })
+  const unsupportedDiscovery = await HttpMessageSignature.sign(
+    new Request('https://merchant.example/resource', { headers: discoveryHeaders }),
+    {
+      components: [
+        HttpMessageSignature.Constants.components.authority,
+        {
+          id: HttpMessageSignature.Constants.components.signatureAgent,
+          parameters: new Map([['key', WebBotAuth.Constants.label]]),
+        },
+      ],
+      key: advertisedKeys.privateKey,
+      keyId: advertisedKeyId,
+      label: WebBotAuth.Constants.label,
+      tag: WebBotAuth.Constants.tag,
+    },
+  )
+  expect(
+    await WebBotAuth.Server.verifier({
+      keyResolver: () => advertisedKeys.publicKey,
+      nonceStore: Attestation.Store.memory(),
+    }).verify(unsupportedDiscovery),
+  ).toMatchObject({
+    reason: 'The Signature-Agent discovery type is not supported by this directory profile.',
+    status: 'invalid',
+  })
+})
+
+test('validates signer and verifier configuration', async () => {
+  const keys = await keyPair()
+  const keyId = await jwkThumbprint(keys.publicKey)
+  const config = { key: keys.privateKey, keyId, signatureAgent: 'https://agent.example' }
+
+  expect(() => WebBotAuth.Client.signer({ ...config, keyId: 'not-a-thumbprint' })).toThrow(
+    'Web Bot Auth keyId must be an RFC 7638 SHA-256 JWK thumbprint.',
+  )
+  expect(() => WebBotAuth.Client.signer({ ...config, signatureAgent: 'https://' })).toThrow(
+    'Signature-Agent must identify a valid HTTPS origin.',
+  )
+  expect(() =>
+    WebBotAuth.Client.signer({ ...config, signatureAgent: 'https://agent.example/keys' }),
+  ).toThrow('Signature-Agent must identify a valid HTTPS origin.')
+  expect(() => WebBotAuth.Client.signer({ ...config, expiresIn: 0 })).toThrow(
+    'Web Bot Auth expiresIn must be a positive integer.',
+  )
+  expect(() =>
+    WebBotAuth.Server.verifier({
+      keyResolver: () => keys.publicKey,
+      maxAge: 0,
+      nonceStore: Attestation.Store.memory(),
+    }),
+  ).toThrow('Web Bot Auth maxAge must be a positive integer.')
+})

package/src/web-bot-auth/client/index.ts

@@ -0,0 +1,84 @@
+import { parseDictionary, serializeDictionary } from 'structured-headers'
+import type { Dictionary } from 'structured-headers'
+
+import * as HttpMessageSignature from '../../attestation/internal/HttpMessageSignature.js'
+import type * as AttestationTypes from '../../attestation/Types.js'
+import { Constants } from '../Constants.js'
+import * as JwkThumbprint from '../internal/JwkThumbprint.js'
+import * as SignatureAgent from '../internal/SignatureAgent.js'
+
+/**
+ * Creates a Web Bot Auth HTTPS-directory profile request signer.
+ *
+ * The signed `Signature-Agent` header links the request to the HTTPS origin
+ * of an HTTP Message Signatures Directory. This adapter does not support
+ * direct key configuration or other Web Bot Auth discovery types. It
+ * establishes bot identity only; it does not assert consumer identity or
+ * authority to make a payment.
+ */
+export function signer(config: signer.Config): AttestationTypes.Signer<typeof Constants.protocol> {
+  const label = config.label ?? Constants.label
+  const signatureAgentKey = config.signatureAgentKey ?? label
+  const expiresIn = config.expiresIn ?? Constants.defaultSignatureLifetime
+  const signatureAgent = SignatureAgent.directoryOrigin(config.signatureAgent)
+  if (!JwkThumbprint.is(config.keyId))
+    throw new TypeError('Web Bot Auth keyId must be an RFC 7638 SHA-256 JWK thumbprint.')
+  if (!signatureAgent) throw new TypeError('Signature-Agent must identify a valid HTTPS origin.')
+  if (!Number.isInteger(expiresIn) || expiresIn <= 0)
+    throw new RangeError('Web Bot Auth expiresIn must be a positive integer.')
+  return {
+    protocol: Constants.protocol,
+    sign(request, context) {
+      const headers = new Headers(request.headers)
+      const signatureAgents = parseSignatureAgents(headers)
+      if (signatureAgents.has(signatureAgentKey))
+        throw new Error(`Signature-Agent member "${signatureAgentKey}" already exists.`)
+      signatureAgents.set(signatureAgentKey, [signatureAgent, new Map()])
+      headers.set(Constants.signatureAgentHeader, serializeDictionary(signatureAgents))
+      return HttpMessageSignature.sign(new Request(request, { headers }), {
+        components: [
+          HttpMessageSignature.Constants.components.authority,
+          {
+            id: HttpMessageSignature.Constants.components.signatureAgent,
+            parameters: new Map([['key', signatureAgentKey]]),
+          },
+        ],
+        context,
+        expiresIn,
+        key: config.key,
+        keyId: config.keyId,
+        label,
+        tag: Constants.tag,
+      })
+    },
+  }
+}
+
+export declare namespace signer {
+  type Config = {
+    /** Ed25519 or RSA-PSS SHA-512 private key registered for the bot. */
+    key: CryptoKey
+    /** RFC 7638 JWK thumbprint for the registered public key. */
+    keyId: string
+    /** Required HTTPS directory origin, sent with the default `directory` discovery type. */
+    signatureAgent: string
+    /** Dictionary member name used for `Signature-Agent`. @default signature label */
+    signatureAgentKey?: string | undefined
+    /** Signature lifetime in seconds. @default 60 */
+    expiresIn?: number | undefined
+    /** RFC 9421 dictionary label. @default 'webbot' */
+    label?: string | undefined
+  }
+}
+
+function parseSignatureAgents(headers: Headers): Dictionary {
+  const value = headers.get(Constants.signatureAgentHeader)
+  if (!value) return new Map()
+  try {
+    return parseDictionary(value)
+  } catch {
+    throw new Error(
+      `HTTP header "${Constants.signatureAgentHeader}" is not a structured dictionary.`,
+    )
+  }
+}

package/src/web-bot-auth/index.ts

@@ -0,0 +1,6 @@
+/** Client helpers for the Web Bot Auth HTTPS-directory profile. */
+export * as Client from './client/index.js'
+/** Server helpers for the Web Bot Auth HTTPS-directory profile. */
+export * as Server from './server/index.js'
+export * from './Constants.js'
+export * from './Types.js'

package/src/web-bot-auth/internal/JwkThumbprint.ts

@@ -0,0 +1,21 @@
+import { Base64 } from 'ox'
+
+const pattern = /^[A-Za-z0-9_-]{43}$/
+
+/** Returns whether a value has the RFC 7638 SHA-256 thumbprint encoding. */
+export function is(value: string): boolean {
+  return pattern.test(value)
+}
+
+/** Derives an RFC 7638 thumbprint from an extractable Ed25519 or RSA public key. */
+export async function fromKey(key: CryptoKey): Promise<string> {
+  const jwk = await crypto.subtle.exportKey('jwk', key)
+  let canonical: string
+  if (jwk.kty === 'OKP' && jwk.crv === 'Ed25519' && jwk.x)
+    canonical = JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x })
+  else if (jwk.kty === 'RSA' && jwk.e && jwk.n)
+    canonical = JSON.stringify({ e: jwk.e, kty: jwk.kty, n: jwk.n })
+  else throw new TypeError('Web Bot Auth requires an Ed25519 or RSA public key.')
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical))
+  return Base64.fromBytes(new Uint8Array(digest), { pad: false, url: true })
+}

package/src/web-bot-auth/internal/SignatureAgent.ts

@@ -0,0 +1,18 @@
+/** Returns the canonical origin for a Web Bot Auth directory identifier. */
+export function directoryOrigin(value: string): string | undefined {
+  try {
+    const url = new URL(value)
+    if (
+      url.protocol !== 'https:' ||
+      url.username ||
+      url.password ||
+      url.pathname !== '/' ||
+      url.search ||
+      url.hash
+    )
+      return undefined
+    return url.origin
+  } catch {
+    return undefined
+  }
+}

package/src/web-bot-auth/server/index.ts

@@ -0,0 +1,113 @@
+import { isInnerList, parseDictionary, Token } from 'structured-headers'
+
+import * as HttpMessageSignature from '../../attestation/internal/HttpMessageSignature.js'
+import type * as Attestation from '../../attestation/Types.js'
+import type * as Store from '../../Store.js'
+import { Constants } from '../Constants.js'
+import * as JwkThumbprint from '../internal/JwkThumbprint.js'
+import * as SignatureAgent from '../internal/SignatureAgent.js'
+import type * as Types from '../Types.js'
+
+/**
+ * Creates a verifier for the Web Bot Auth HTTPS-directory profile.
+ *
+ * It requires an `@authority` and signed `Signature-Agent` directory member;
+ * direct key configuration and other Web Bot Auth discovery types are outside
+ * this adapter's scope. Verification confirms the cryptographic identity of an
+ * automated HTTP client. It must not be used on its own as user or payment
+ * authorization.
+ */
+export function verifier(config: verifier.Config): Attestation.Verifier<Types.VerifiedRequest> {
+  const maxAge = config.maxAge ?? Constants.defaultMaximumSignatureLifetime
+  if (!Number.isInteger(maxAge) || maxAge <= 0)
+    throw new RangeError('Web Bot Auth maxAge must be a positive integer.')
+  return {
+    async verify(request) {
+      let signatureAgent: string | undefined
+      const result = await HttpMessageSignature.verify(request, {
+        async keyResolver(parameters) {
+          return config.keyResolver({
+            ...parameters,
+            signatureAgent: signatureAgent!,
+          })
+        },
+        async validateKey(key, input) {
+          try {
+            return (await JwkThumbprint.fromKey(key)) === input.keyId
+              ? undefined
+              : 'The Web Bot Auth key does not match its RFC 7638 keyid.'
+          } catch {
+            return 'The Web Bot Auth key must be an extractable Ed25519 or RSA public key.'
+          }
+        },
+        maxAge,
+        nonceNamespace: Constants.protocol,
+        nonceStore: config.nonceStore,
+        requiredComponents: Constants.requiredComponents,
+        tag: Constants.tag,
+        validate(signature, request) {
+          if (!JwkThumbprint.is(signature.keyId))
+            return 'The Web Bot Auth keyid must be an RFC 7638 SHA-256 JWK thumbprint.'
+          const component = signature.components.find(
+            (entry) => entry.id === HttpMessageSignature.Constants.components.signatureAgent,
+          )
+          const key = component?.parameters?.get('key')
+          if (typeof key !== 'string')
+            return 'The signed Signature-Agent component must identify a dictionary member.'
+          const value = request.headers.get(Constants.signatureAgentHeader)
+          if (!value) return 'The Signature-Agent header is required.'
+          let agents
+          try {
+            agents = parseDictionary(value)
+          } catch {
+            return 'The Signature-Agent header must be a structured dictionary.'
+          }
+          const agent = agents.get(key)
+          if (!agent || isInnerList(agent) || typeof agent[0] !== 'string')
+            return 'The signed Signature-Agent member must be an HTTPS URL.'
+          const type = agent[1].get('type')
+          if (
+            type !== undefined &&
+            (!(type instanceof Token) || type.toString() !== Constants.discoveryType)
+          )
+            return 'The Signature-Agent discovery type is not supported by this directory profile.'
+          const origin = SignatureAgent.directoryOrigin(agent[0])
+          if (!origin) return 'The Signature-Agent header must identify a valid HTTPS origin.'
+          signatureAgent = origin
+          return undefined
+        },
+      })
+      if (result.status !== 'verified') return result
+      return {
+        status: 'verified',
+        value: {
+          keyId: result.input.keyId,
+          nonce: result.input.nonce,
+          signatureAgent: signatureAgent!,
+        },
+      }
+    },
+  }
+}
+
+export declare namespace verifier {
+  type Config = {
+    /**
+     * Resolves a public key for the advertised directory.
+     *
+     * Apply the origin's trust policy before any network lookup; do not fetch an
+     * arbitrary caller-provided `signatureAgent` URL. Returned public keys
+     * must be extractable so their RFC 7638 thumbprints can be verified.
+     */
+    keyResolver: (parameters: {
+      algorithm: Attestation.SignatureAlgorithm
+      keyId: string
+      request: Request
+      signatureAgent: string
+    }) => Promise<CryptoKey | undefined> | CryptoKey | undefined
+    /** Maximum accepted signature lifetime in seconds. @default 86400 */
+    maxAge?: number | undefined
+    /** Atomically consumes each nonce in shared storage for multi-instance deployments. */
+    nonceStore: Store.AtomicStore
+  }
+}