Skip to content

fix(sip): raise header value cap to 4 KB for carrier tokens like X-Twilio-CallToken - #1750

Open
rkfshakti wants to merge 1 commit into
livekit:mainfrom
rkfshakti:fix/sip-header-long-values-tolerance
Open

fix(sip): raise header value cap to 4 KB for carrier tokens like X-Twilio-CallToken#1750
rkfshakti wants to merge 1 commit into
livekit:mainfrom
rkfshakti:fix/sip-header-long-values-tolerance

Conversation

@rkfshakti

Copy link
Copy Markdown

Summary

CreateSIPParticipant rejects valid Twilio X-Twilio-CallToken values over 1,024 bytes:

TwirpError: invalid header value for X-Twilio-CallToken:
header X-Twilio-CallToken: value too long (max 1024 characters)

HTTP status: 400
Twirp code: invalid_argument
at SipClient.createSipParticipant

Twilio's Immutable Call Forwarding flow requires this token to be forwarded unchanged on the outbound leg so the original caller ID can be presented. The token is opaque and may contain SHAKEN/STIR and DIV PASSporTs, so truncating it is not valid either.

Root cause

ValidateHeaderValueResult caps every header value at 1,024 characters. RFC 3261 does not bound individual header values — §7.1 bounds the whole message (8 KB datagram over UDP, larger over TCP). The 1 KB figure is this codebase's own policy and sits below the size real carrier tokens reach.

Fix

  • Introduce maxHeaderValueLength = 4096 and reject values above it. 4 KB keeps a single header from dominating an 8 KB datagram while tolerating real-world carrier tokens. Character-set validation is unchanged.
  • Update the valid/invalid test boundary cases (1024 & 4096 pass; 4097 fails) and add a changeset.

Fixes #789

…ilio-CallToken

Twilio's Immutable Call Forwarding flow requires X-Twilio-CallToken to be
forwarded unchanged on the outbound leg. The token is opaque and carries
SHAKEN/STIR + DIV PASSporTs, so it routinely exceeds the current 1024-byte
cap and CreateSIPParticipant rejects the request with
'invalid header value for X-Twilio-CallToken: value too long (max 1024
characters)' before the INVITE is ever sent.

RFC 3261 §7.1 bounds the message (8 KB datagram on UDP), not individual
header values. 4096 keeps a single header from dominating a datagram while
tolerating real carrier tokens; the character-set validation is unchanged.

Fixes livekit#789
@changeset-bot

changeset-bot Bot commented Aug 29, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 439a424

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages
Name Type
github.com/livekit/protocol Patch
@livekit/protocol Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant