fix(sqs): gate v2 receipt handles at the public API boundary

CodeRabbit major on PR #724 round 2: the v2 codec is in the
binary AND reachable on the public API. A client can re-encode a
legitimately-issued v1 handle's (queue_gen, message_id,
receipt_token) under the v2 layout, and DeleteMessage /
ChangeMessageVisibility will accept it (downstream validation
only checks queue_gen + receipt_token). The behaviour is
technically correct (the v1 keyspace lookup still finds the
message) but it leaks the new wire format before PR 5b lands —
breaking the "no behavior change yet" guarantee.

Fix

decodeClientReceiptHandle wraps decodeReceiptHandle with the
dormancy gate: any v2 handle on the public API surfaces as
ReceiptHandleIsInvalid until PR 5b's queue-aware version replaces
the gate (v1 required on non-partitioned queues, v2 required on
partitioned ones).

Changed call sites

Three public-API decode points switch from decodeReceiptHandle
to decodeClientReceiptHandle:

  - parseQueueAndReceipt (sqs_messages.go) — DeleteMessage and
    ChangeMessageVisibility entry point.
  - DeleteMessageBatch entry decode (sqs_messages_batch.go).
  - ChangeMessageVisibilityBatch entry decode (sqs_messages_batch.go).

The low-level decodeReceiptHandle keeps working as a pure codec
so the existing v1 + v2 round-trip tests keep passing.

Tests

  - TestDecodeClientReceiptHandle_AcceptsV1: v1 handles flow
    through unchanged.
  - TestDecodeClientReceiptHandle_RejectsV2: a v2 handle on the
    public API surfaces as the dormancy-gate error. The
    low-level decoder still accepts it (the gate is at the API
    boundary, not in the codec).
  - TestDecodeClientReceiptHandle_PassesThroughDecodeErrors: a
    decode-step error (e.g. base64 garbage) is NOT masked by
    the dormancy-gate message — operators see the underlying
    error.

Audit per the lessons-learned discipline

The semantic change here is the rejection contract for v2
handles on the public API. grep -rn "decodeReceiptHandle"
across adapter/ showed 3 production call sites (parseQueueAndReceipt,
DeleteMessageBatch, ChangeMessageVisibilityBatch). All 3 updated.
The v2 codec round-trip tests intentionally keep using
decodeReceiptHandle directly so they exercise the codec, not
the public API.

Note on Gemini's "appendU32 is undefined" finding (round 2)

False positive. appendU32 is defined in adapter/sqs_keys.go:444
and has been since PR #703 merged. Gemini did not search across
files in the package; CI build is green and the round-1 v2
round-trip tests exercise the function. No code change needed.

Author: bootjp

adapter/sqs_messages.go

@@ -368,6 +368,48 @@ func decodeReceiptHandleV1(b []byte) (*decodedReceiptHandle, error) {
 	}, nil
 }
 
+// decodeClientReceiptHandle is the public-API entry point for
+// decoding a client-supplied receipt handle. It wraps
+// decodeReceiptHandle with the dormancy gate that keeps the v2
+// codec inert until Phase 3.D PR 5b wires the partitioned-FIFO
+// data plane.
+//
+// # Why the gate
+//
+// PR 5a adds the v2 codec to the binary but does NOT yet wire any
+// production path that produces v2 handles — SendMessage on a
+// partitioned queue is rejected by the §11 PR 2 dormancy gate
+// (PartitionCount > 1 → InvalidAttributeValue). Without this
+// helper, a client could craft a v2 handle (re-encoding a
+// legitimately-issued v1 handle's queue_gen / message_id /
+// receipt_token under the v2 layout) and DeleteMessage /
+// ChangeMessageVisibility would accept it, since the downstream
+// validation only checks queue_gen + receipt_token. The behaviour
+// is technically correct (the v1 keyspace lookup still finds the
+// message) but it leaks the new wire format before PR 5b lands —
+// breaking the "no behavior change yet" guarantee of this PR
+// (codex/coderabbit major on PR #724).
+//
+// PR 5b lifts this gate together with the rest of the data-plane
+// fanout: it replaces the != v1 check with a queue-aware version
+// (v1 required on non-partitioned queues, v2 required on
+// partitioned ones), so neither version leaks into the wrong
+// keyspace. Until then, any v2 handle on the public API surfaces
+// as ReceiptHandleIsInvalid.
+func decodeClientReceiptHandle(raw string) (*decodedReceiptHandle, error) {
+	handle, err := decodeReceiptHandle(raw)
+	if err != nil {
+		return nil, err
+	}
+	if handle.Version != sqsReceiptHandleVersion1 {
+		// v2 codec is added but dormant until PR 5b. Reject any
+		// non-v1 handle on the public API so the wire format
+		// does not leak.
+		return nil, errors.New("receipt handle version is not yet enabled on the public API")
+	}
+	return handle, nil
+}
+
 func decodeReceiptHandleV2(b []byte) (*decodedReceiptHandle, error) {
 	if len(b) != sqsReceiptHandleV2Size {
 		return nil, errors.New("receipt handle length or version mismatch")
@@ -1494,7 +1536,7 @@ func (s *SQSServer) parseQueueAndReceipt(queueUrl, receiptHandle string) (string
 	if err != nil {
 		return "", nil, err
 	}
-	handle, err := decodeReceiptHandle(receiptHandle)
+	handle, err := decodeClientReceiptHandle(receiptHandle)
 	if err != nil {
 		return "", nil, newSQSAPIError(http.StatusBadRequest, sqsErrReceiptHandleInvalid, "receipt handle is not parseable")
 	}

adapter/sqs_messages_batch.go

@@ -467,7 +467,7 @@ func (s *SQSServer) deleteMessageBatch(w http.ResponseWriter, r *http.Request) {
 		// retry-bound stale-is-success delete that single DeleteMessage
 		// uses. Per-entry isolation matches AWS, where a malformed
 		// handle in slot 3 must not poison slot 4.
-		handle, decodeErr := decodeReceiptHandle(entry.ReceiptHandle)
+		handle, decodeErr := decodeClientReceiptHandle(entry.ReceiptHandle)
 		if decodeErr != nil {
 			failed = append(failed, sqsBatchResultErrorEntry{
 				Id:          entry.Id,
@@ -567,7 +567,7 @@ func (s *SQSServer) applyChangeVisibilityBatchEntry(ctx context.Context, queueNa
 			SenderFault: true,
 		}
 	}
-	handle, decodeErr := decodeReceiptHandle(entry.ReceiptHandle)
+	handle, decodeErr := decodeClientReceiptHandle(entry.ReceiptHandle)
 	if decodeErr != nil {
 		return false, sqsBatchResultErrorEntry{
 			Id:          entry.Id,

adapter/sqs_receipt_handle_v2_test.go

@@ -264,3 +264,67 @@ func TestDecodeReceiptHandle_RejectsBase64Garbage(t *testing.T) {
 	require.Error(t, err,
 		"non-base64 input must fail at the base64 decode step")
 }
+
+// TestDecodeClientReceiptHandle_AcceptsV1 pins the public-API
+// wrapper's happy path — v1 handles flow through unchanged.
+func TestDecodeClientReceiptHandle_AcceptsV1(t *testing.T) {
+	t.Parallel()
+	token := make([]byte, sqsReceiptTokenBytes)
+	h, err := encodeReceiptHandle(7, "deadbeefdeadbeefdeadbeefdeadbeef", token)
+	require.NoError(t, err)
+	back, err := decodeClientReceiptHandle(h)
+	require.NoError(t, err)
+	require.Equal(t, sqsReceiptHandleVersion1, back.Version)
+	require.Equal(t, uint64(7), back.QueueGeneration)
+}
+
+// TestDecodeClientReceiptHandle_RejectsV2 pins the codex/coderabbit
+// major fix on PR #724 round 1: the v2 codec is added but
+// dormant. A client-supplied v2 handle MUST be rejected at the
+// public API boundary so the wire format does not leak before
+// PR 5b wires the partitioned-FIFO data plane.
+//
+// Without this gate, a malicious / curious client could re-encode
+// a legitimately-issued v1 handle's (queue_gen, message_id,
+// receipt_token) under the v2 layout, and DeleteMessage /
+// ChangeMessageVisibility would accept it (since downstream
+// validation only checks queue_gen + receipt_token). PR 5b
+// replaces this gate with a queue-aware version (v1 required on
+// non-partitioned queues, v2 required on partitioned ones), so
+// the gate-removal lands together with the partitioned data plane.
+func TestDecodeClientReceiptHandle_RejectsV2(t *testing.T) {
+	t.Parallel()
+	token := make([]byte, sqsReceiptTokenBytes)
+	h, err := encodeReceiptHandleV2(3, 7, "deadbeefdeadbeefdeadbeefdeadbeef", token)
+	require.NoError(t, err,
+		"v2 encoder must succeed even though the public API "+
+			"wrapper rejects the result — the codec is dormant, "+
+			"not absent")
+
+	// Low-level decoder still accepts v2 (it's pure codec).
+	back, err := decodeReceiptHandle(h)
+	require.NoError(t, err)
+	require.Equal(t, sqsReceiptHandleVersion2, back.Version,
+		"low-level decodeReceiptHandle must keep working — the "+
+			"gate is at the public API boundary, not in the codec")
+
+	// Public API wrapper rejects v2.
+	_, err = decodeClientReceiptHandle(h)
+	require.Error(t, err,
+		"v2 handle on the public API must fail until PR 5b lifts "+
+			"the dormancy gate")
+	require.Contains(t, err.Error(), "not yet enabled")
+}
+
+// TestDecodeClientReceiptHandle_PassesThroughDecodeErrors pins
+// that decode-error propagation is unchanged — a malformed blob
+// still surfaces the underlying base64 / length error rather than
+// being masked by the dormancy-gate message.
+func TestDecodeClientReceiptHandle_PassesThroughDecodeErrors(t *testing.T) {
+	t.Parallel()
+	_, err := decodeClientReceiptHandle("!!!" + strings.Repeat("?", 50))
+	require.Error(t, err)
+	require.NotContains(t, err.Error(), "not yet enabled",
+		"a decode-step error must NOT be reported as the "+
+			"dormancy-gate message")
+}