mppx 0.8.14 → 0.8.17

package/src/tempo/subscription/KeyAuthorization.test.ts

@@ -1,4 +1,5 @@
-import { KeyAuthorization } from 'ox/tempo'
+import { Rlp } from 'ox'
+import { KeyAuthorization, SignatureEnvelope } from 'ox/tempo'
 import { privateKeyToAccount } from 'viem/accounts'
 import { describe, expect, test } from 'vp/test'
 
@@ -69,6 +70,25 @@ async function createPayload(request = parseRequest()) {
   } as const
 }
 
+function serializeCompositeSignature(
+  type: 'keychain' | 'multisig',
+  inner: SignatureEnvelope.Primitive,
+) {
+  return SignatureEnvelope.serialize(
+    type === 'keychain'
+      ? {
+          inner,
+          type,
+          userAddress: rootAccount.address,
+        }
+      : {
+          account: rootAccount.address,
+          signatures: [inner],
+          type,
+        },
+  )
+}
+
 describe('tempo subscription key authorization', () => {
   test('signs and verifies a scoped key authorization', async () => {
     const request = parseRequest()
@@ -87,6 +107,55 @@ describe('tempo subscription key authorization', () => {
     )
   })
 
+  test.each(['keychain', 'multisig'] as const)(
+    'rejects %s authorization signatures',
+    async (type) => {
+      const request = parseRequest()
+
+      await expect(
+        signSubscriptionKeyAuthorization({
+          accessKey,
+          account: {
+            async sign({ hash }) {
+              const inner = SignatureEnvelope.from(await rootAccount.sign({ hash }))
+              if (inner.type === 'keychain' || inner.type === 'multisig') {
+                throw new Error('expected primitive signature')
+              }
+              return serializeCompositeSignature(type, inner)
+            },
+          },
+          chainId: 4217,
+          request,
+        }),
+      ).rejects.toThrow('keyAuthorization must use a primitive signature')
+    },
+  )
+
+  test.each(['keychain', 'multisig'] as const)(
+    'rejects serialized %s authorization signatures',
+    async (type) => {
+      const request = parseRequest()
+      const payload = await createPayload(request)
+      const authorization = KeyAuthorization.deserialize(payload.signature)
+      const [authorizationTuple] = KeyAuthorization.toTuple(authorization)
+
+      expect(() =>
+        verifySubscriptionKeyAuthorization({
+          accessKey,
+          chainId: 4217,
+          payload: {
+            ...payload,
+            signature: Rlp.fromHex([
+              authorizationTuple,
+              serializeCompositeSignature(type, authorization.signature!),
+            ]),
+          },
+          request,
+        }),
+      ).toThrow('keyAuthorization must use a primitive signature')
+    },
+  )
+
   test('builds wallet allowed calls from the subscription request', () => {
     const request = parseRequest()
 

package/src/tempo/subscription/KeyAuthorization.ts

@@ -168,8 +168,14 @@ export async function signSubscriptionKeyAuthorization(parameters: {
   const signature = await account.sign({
     hash: KeyAuthorization.getSignPayload(authorization),
   })
+  const signatureEnvelope = SignatureEnvelope.from(signature)
+  if (signatureEnvelope.type === 'keychain' || signatureEnvelope.type === 'multisig') {
+    throw new VerificationFailedError({
+      reason: 'keyAuthorization must use a primitive signature',
+    })
+  }
   return KeyAuthorization.from(authorization, {
-    signature: SignatureEnvelope.from(signature),
+    signature,
   })
 }
 
@@ -238,14 +244,19 @@ function createUnsignedAuthorization(parameters: {
 function deserializeAuthorization(signature: `0x${string}`) {
   try {
     return KeyAuthorization.deserialize(signature)
-  } catch {
+  } catch (error) {
+    if (error instanceof KeyAuthorization.InvalidSignatureTypeError) {
+      throw new VerificationFailedError({
+        reason: 'keyAuthorization must use a primitive signature',
+      })
+    }
     throw new VerificationFailedError({ reason: 'invalid keyAuthorization payload' })
   }
 }
 
 function getPrimitiveSignature(authorization: Authorization) {
   const signature = authorization.signature
-  if (!signature || signature.type === 'keychain') {
+  if (!signature) {
     throw new VerificationFailedError({
       reason: 'keyAuthorization must use a primitive signature',
     })

package/src/viem/Client.test.ts

@@ -2,7 +2,7 @@ import { createClient, custom, defineChain, type Hex } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
 import { signTransaction } from 'viem/actions'
 import { Account as TempoAccount, Transaction } from 'viem/tempo'
-import { tempoLocalnet } from 'viem/tempo/chains'
+import { tempo as tempoMainnetChain, tempoLocalnet, tempoModerato } from 'viem/tempo/chains'
 import { afterEach, describe, expect, test, vi } from 'vp/test'
 
 import * as Client from './Client.js'
@@ -48,6 +48,23 @@ describe('getResolver', () => {
     expect(client.chain?.name).toBe('test')
   })
 
+  test('behavior: resolves the correct named Tempo chain even when the default chain differs', async () => {
+    const getClient = Client.getResolver({
+      // Default chain is mainnet, but the resolved chain ID below is testnet.
+      chain: tempoMainnetChain as never,
+      rpcUrl: {
+        [tempoMainnetChain.id]: 'https://rpc.example.com',
+        [tempoModerato.id]: 'https://rpc2.example.com',
+      },
+    })
+
+    const client = await getClient({ chainId: tempoModerato.id })
+
+    expect(client.chain?.id).toBe(tempoModerato.id)
+    expect(client.chain?.name).toBe(tempoModerato.name)
+    expect(client.chain?.name).not.toBe(tempoMainnetChain.name)
+  })
+
   test('error: throws when no rpcUrl provided', () => {
     const getClient = Client.getResolver({})
 

package/src/viem/Client.ts

@@ -1,8 +1,14 @@
 import { type Chain, type Client, createClient, createTransport, custom, http } from 'viem'
 import { withFeePayer } from 'viem/tempo'
+import { tempo as tempoMainnetChain, tempoModerato } from 'viem/tempo/chains'
 
 import type { MaybePromise } from '../internal/types.js'
 
+const knownTempoChains: Record<number, Chain> = {
+  [tempoMainnetChain.id]: tempoMainnetChain,
+  [tempoModerato.id]: tempoModerato,
+}
+
 export function getResolver(
   parameters: getResolver.Parameters & {
     /** Default chain to use if not provided. */
@@ -73,7 +79,7 @@ export function getResolver(
     if (!url) throw new Error(`No \`rpcUrl\` configured for \`chainId\` (${resolvedChainId}).`)
     const transport = feePayerUrl ? withFeePayer(http(url), http(feePayerUrl)) : http(url)
     return createClient({
-      chain: { ...chain, id: resolvedChainId } as never,
+      chain: (knownTempoChains[resolvedChainId] ?? { ...chain, id: resolvedChainId }) as never,
       transport,
     })
   }

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

@@ -0,0 +1,24 @@
+import { Constants as HttpMessageSignature } from '../attestation/internal/HttpMessageSignature.js'
+
+/** Web Bot Auth values for the supported HTTPS-directory signature profile. */
+export const Constants = {
+  /** Stable identifier for Web Bot Auth signers and replay storage. */
+  protocol: 'web-bot-auth',
+  /** Web Bot Auth discovery type supported by this adapter. */
+  discoveryType: 'directory',
+  /** RFC 9421 signature label used when no label is configured. */
+  label: 'webbot',
+  /** Tag identifying a Web Bot Auth request signature. */
+  tag: 'web-bot-auth',
+  /** Structured HTTP header linking a bot signature to its HTTPS directory origin. */
+  signatureAgentHeader: 'Signature-Agent',
+  /** Default lifetime, in seconds, for a bot request signature. */
+  defaultSignatureLifetime: 60,
+  /** Default verifier limit, following the draft's recommended 24-hour maximum. */
+  defaultMaximumSignatureLifetime: 24 * 60 * 60,
+  /** HTTP components required by this directory profile. */
+  requiredComponents: [
+    HttpMessageSignature.components.authority,
+    HttpMessageSignature.components.signatureAgent,
+  ],
+} as const

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
+  }
+}