signature

Overview ¶

Claude thinking signature validation.

Spec reference: SIGNATURE-CHANNEL-SPEC.md

Encoding detection (Spec section 3)

Claude signatures use base64 encoding in one or two layers. The raw string's first character determines the encoding depth. This is mathematically equivalent to the spec's "decode first, check byte" approach:

• E prefix: single-layer, payload[0] == 0x12, first 6 bits = 000100, base64 index 4 = E.
• R prefix: double-layer, inner[0] == E (0x45), first 6 bits = 010001, base64 index 17 = R.

Valid signatures can be normalized to R-form (double-layer base64) before sending to the Antigravity backend.

Protobuf structure (Spec sections 4.1 and 4.2) in strict mode only ¶

After base64 decoding to raw bytes, the first byte must be 0x12:

Top-level protobuf
|- Field 2 (bytes): container                    -> extractClaudeBytesField(payload, 2)
|  |- Field 1 (bytes): channel block             -> extractClaudeBytesField(container, 1)
|  |  |- Field 1 (varint): channel_id [required] -> routing_class (11 | 12)
|  |  |- Field 2 (varint): infra [optional]      -> infrastructure_class (aws=1 | google=2)
|  |  |- Field 3 (varint): version=2             -> skipped
|  |  |- Field 5 (bytes): ECDSA sig              -> skipped, per Spec section 11
|  |  |- Field 6 (bytes): model_text [optional]  -> schema_features
|  |  `- Field 7 (varint): unknown [optional]    -> schema_features
|  |- Field 2 (bytes): nonce 12B                 -> skipped
|  |- Field 3 (bytes): session 12B               -> skipped
|  |- Field 4 (bytes): SHA-384 48B               -> skipped
|  `- Field 5 (bytes): metadata                  -> skipped, per Spec section 11
`- Field 3 (varint): =1                          -> skipped

Output dimensions (Spec section 8)

routing_class:        routing_class_11 | routing_class_12 | unknown
infrastructure_class: infra_default (absent) | infra_aws (1) | infra_google (2) | infra_unknown
schema_features:      compact_schema (len 70-72, no f6/f7) | extended_model_tagged_schema (f6 exists) | unknown
legacy_route_hint:    only for ch=11, legacy_default_group | legacy_aws_group | legacy_vertex_direct/proxy

Compatibility ¶

Verified against all confirmed spec samples (Anthropic Max 20x, Azure, Vertex, Bedrock) and legacy ch=11 signatures. Both single-layer (E) and double-layer (R) encodings are supported. Historical cache-mode modelGroup# prefixes are stripped.

CAIS envelope (newest Claude Code models) ¶

Newer Claude Code models wrap the channel block in a CAIS envelope whose decoded payload starts with 0x08 (top-level field 1 varint) instead of 0x12, so the base64 string starts with 'C' instead of 'E'/'R'. The envelope version varint in top-level field 1 is the ONLY structural difference from the layout above; everything below it is unchanged.

The channel block itself belongs to a newer schema generation that is shared by both envelopes: channel_id 16, no infra field 2, plus a block kind (field 8) and a context id (field 11). Observed traffic confirms this schema appears under the classic 0x12 envelope too (opus-4-6/4-7/4-8, sonnet-5) and under the CAIS envelope (opus-5, fable-5), so envelope form and channel schema generation vary independently and must not be inferred from each other:

Top-level protobuf
|- Field 1 (varint): envelope version [required marker, observed as 2]
|- Field 2 (bytes): container [required]
|  `- Field 1 (bytes): channel block [required]
|     |- Field 1  (varint): channel_id [required, observed as 16]
|     |- Field 3  (varint): version [optional, observed as 2]
|     |- Field 5  (bytes):  ECDSA signature [required, observed as 64B]
|     |- Field 6  (bytes):  model_text [required, "claude-" prefixed]
|     |- Field 7  (varint): unknown [optional, observed as 1]
|     |- Field 8  (bytes):  block kind [optional, observed as "thinking"]
|     `- Field 11 (bytes):  context id [optional, canonical UUID]
`- Field 3 (varint): trailer [optional, observed as 1]

CAIS validation is structural rather than an exact replay of the observed bytes. The payload is an opaque upstream-issued blob and rejecting it drops the whole thinking block, so only the fields that actually identify the format are required: the 0x08 marker, the nested container/channel block, the signature bytes, and the "claude-" model text. Observed-but-incidental values such as channel_id 16 or the "thinking" block kind are recorded for debugging and checked only for wire type, so an upstream field bump cannot silently erase conversation history.

Which provider emits which envelope ¶

Three providers serve Claude models, and the envelope depends on the model generation rather than on the provider:

• Claude Code OAuth subscription (Claude Code Max): opus-4-5, sonnet-4-6 and every later model up to opus-5 and fable-5. Emits the CAIS envelope for the newest models (opus-5, fable-5) and the single-layer E envelope for the opus-4-6/4-7/4-8 and sonnet-5 generation — but both carry the same channel_id 16 channel schema, so only the envelope differs.
• Claude Messages API: the full Claude model range, same envelopes as the Claude Code OAuth subscription.
• Antigravity: only opus-4-6-think and sonnet-4-6, and always the double-layer R form on Google infrastructure (infra_google). Antigravity never issues a CAIS envelope or a single-layer E signature, and its replay path requires R form, so CompatibleAntigravityClaudeThinkingSignature rejects CAIS signatures.

A single conversation therefore mixes envelopes whenever a user switches model generations or providers, and every form must stay replayable toward the provider that issued it.

Gemini thought signature validation notes.

The Antigravity Gemini request translator can preserve provider-compatible Gemini thought signatures and uses the skip sentinel only for synthetic or incompatible model parts.

Gemini 3 and later models can return thoughtSignature on model content parts. Function-call parts are the strict case: when a model functionCall is replayed with a following functionResponse, Gemini validates that the original functionCall part still carries its provider-issued thoughtSignature. Text or other non-functionCall parts may also carry a signature; those should be preserved when replaying native Gemini history, but they are not the primary validation gate.

Synthetic history and migration from other model families are different. If a functionCall part was not produced by Gemini API, there is no real signature to preserve. Gemini documents two bypass sentinels for that case:

• "skip_thought_signature_validator"
• "context_engineering_is_the_way_to_go"

This repo emits "skip_thought_signature_validator" only when the first functionCall in a synthetic model turn lacks a compatible provider signature. Later parallel calls and ordinary text/thought parts preserve their native unsigned shape.

This validator is intentionally more conservative than a decrypting verifier. Claude has a known E/R base64 envelope and a protobuf tree in this package. Gemini thought signatures are opaque provider state here, so local validation checks only the transport-level protobuf envelope and leaves the wrapped provider payload uninterpreted.

Validation tiers:

• Sentinel tier: accept the documented bypass sentinels only on the first model functionCall when it is synthetic, migrated, or otherwise not traceable to a prior Gemini model response in the same conversation.
• Opaque-shape tier: for real Gemini signatures, require a non-empty string, bounded length, successful standard base64 decoding, and a known protobuf envelope when the caller needs provider compatibility. The only known envelope is the Gemini 3.x field-2 -> field-1 payload, whose body holds either versioned opaque state or a provider UUID. Gemini 2.5 emitted a repeated field-1 form; those models are out of scope and their signatures are no longer a known envelope. Bare base64 UUID payloads are classified separately and should be replaced with the bypass sentinel rather than replayed.
• Replay tier: real validation means preserving the exact model part that came from Gemini, including its thoughtSignature, id/name/function args, part index, and ordering relative to sibling parallel function calls.
• Tool pairing tier: functionResponse parts must match the preceding functionCall id/name and must not be interleaved between parallel calls. The valid shape is all model functionCalls first, then their responses.
• Compatibility tier: GPT-compatible Gemini traffic stores the same state under tool_calls[].extra_content.google.thought_signature. If that path is translated back to native Gemini, the value must stay attached to the same assistant tool call.

Important non-goals:

• Do not treat a Gemini thoughtSignature as a Claude signature. Similar base64 prefixes are not provenance.
• Do not attach a signature to user functionResponse/tool-result parts.
• Do not log complete signatures during validation failures; log only field paths, lengths, and redacted prefixes.
• Do not preserve client-provided signatures across model/provider/session boundaries unless the request pipeline can prove they came from the same Gemini conversation state.