Function verifyEnvelope

verifyEnvelope(
    key: VerifyKey,
    envelope: ReceivedEnvelope,
    options: VerifyOptions,
): void

Verify a received envelope: version, signature format, freshness (maxAgeSecs, plus skewSecs into the future), the expected slot, then the signature (constant-time). Returns normally when the envelope is valid.

Parameters

key: VerifyKey
{ mode: 'hmac', secret } or { mode: 'ed25519', publicKey }.
envelope: ReceivedEnvelope
The received envelope (parsed JSON or an Envelope).
options: VerifyOptions
{ maxAgeSecs, slot, skewSecs?, now? }.

Returns void

Remarks

TLS protects each hop, but a CDN or proxy that terminates TLS can still change a response. Signed envelopes let whoever receives a fragment (a server or edge that relays it, another service) check that it came from the origin unchanged. The Anza browser library does not verify envelopes.

The checks run in this order; the first failure throws CRYPTO with:

Check	Message
`v` is `2`	`unsupported envelope version`
`ts`, `slot`, `html`, `css` have the right types	`malformed envelope`
`sig` is present	`envelope is not signed`
`sig` is strict lowercase hex	`malformed signature`
`ts <= now + skewSecs`	`envelope timestamp is in the future`
`now - ts <= maxAgeSecs`	`envelope expired`
`slot` equals `options.slot`	`slot mismatch`
the signature verifies (constant-time)	`bad signature`

An HMAC secret shorter than 32 bytes, a malformed Ed25519 public key or an unknown mode is invalid verification key. The slot check stops a fragment signed for one slot from being replayed into another; maxAgeSecs limits replay in time. Engine.verifyEnvelope runs the same checks with the engine's own key.

Throws

AnzaError CRYPTO whose message names the failed check.

Example

import { AnzaError, verifyEnvelope } from '@anzaui/engine';

try {
  verifyEnvelope({ mode: 'ed25519', publicKey: publicHex }, JSON.parse(body), { maxAgeSecs: 60, slot: 'feed' });
} catch (err) {
  if (err instanceof AnzaError && err.code === 'CRYPTO') return reject(err.message); // e.g. "envelope expired"
  throw err;
}