PASETO Implicit Assertions (v3 / v4)

Implicit assertions are a feature added in PASETO v3 and v4 that let issuer and verifier bind extra context into a token's signature/tag without putting that context on the wire.

The mechanism:

When you sign or encrypt a v3/v4 token, the API accepts an additional optional bytes parameter — the implicit assertion. That value is fed into the pre-authentication encoding (PAE) alongside the header, payload, and footer. The result: the signature/tag depends on the implicit assertion, but the assertion itself is not transmitted in the token.

To verify, the verifier must independently provide the same implicit assertion bytes. If issuer and verifier disagree, verification fails — even though every byte on the wire is unchanged.

Why this is useful:

Implicit assertions let you bind a token to a context that you don't want exposed. Examples:

• Tenant ID in a multi-tenant system — both sides know which tenant they're operating in, but you don't need to leak the tenant name in the wire token.
• Channel binding — bind a token to the TLS exporter value of the connection it was issued on, so it can't be replayed over a different connection.
• Configuration version — bind a token to a specific server config version, so a config rollback automatically invalidates outstanding tokens.

Implicit assertion vs footer:

Both are authenticated, but only the footer is on the wire. Use the footer when the verifier needs to read the value to dispatch (e.g. to look up a key by kid). Use implicit assertions when both sides already know the value out-of-band and you want to bind to it without leaking.

v1 and v2 don't have this:

This feature is v3+ only. v1 and v2 use only header + body + footer in their PAE. If you need implicit assertions, that's another reason to migrate to v3 or v4.

Common pitfalls:

The assertion bytes are matched exactly — there's no parsing or normalization. If issuer and verifier compute the assertion differently (e.g. one includes a trailing newline, one doesn't), verification will fail with a confusing-looking signature error. Always use a single canonical encoding function on both sides.