From 4f7a3be50dc3258380ee867272b418ad9a4155f9 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 11:59:26 +0900 Subject: [PATCH] fix(contracts): restrict idempotency keys to visible ASCII (R-7.1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit isValidIdempotencyKey only rejected blank values and C0/C1 control characters. Keys with surrounding whitespace passed and fetch trimmed them on the wire (two commands could share one key), and non-ASCII keys passed and made Headers.set throw a TypeError that the client reported as a retryable NETWORK_UNREACHABLE. The key is now /^[\x21-\x7e]+$/ within the existing 256-byte bound, the same rule as the realtime HEADER_SAFE_CURSOR. App-generated keys (randomUUID) and all test fixtures are visible ASCII. The existing OPT-NET-02 test pinned "키-값" and "ключ" as valid keys; it encoded the bug and is fixed here: those values plus " order-1 ", "order-1\t", "key with-space" and a NBSP key are now in the rejected list, and a UUID key was added to the accepted list. RED: "OPT-NET-02 shared idempotency key validation > rejects the same values at intent definition and at admission" failed with '" order-1 ": expected true to be false' before the fix. Gates: check:architecture, check:types:app/test/node, lint, test:component, test:runtime-schema, test:contract pass; test:unit passes except removal-fixture.test.ts, which needs generated artifacts/release files that a fresh worktree does not have (unrelated to this change). Co-Authored-By: Claude Opus 5.5 --- src/contracts/mutation-intent.ts | 25 ++++++++----------- ...y-and-optional-network-remediation.test.ts | 21 +++++++++++++--- 2 files changed, 28 insertions(+), 18 deletions(-) diff --git a/src/contracts/mutation-intent.ts b/src/contracts/mutation-intent.ts index 3d11e1ef..acd6ffbe 100644 --- a/src/contracts/mutation-intent.ts +++ b/src/contracts/mutation-intent.ts @@ -30,23 +30,18 @@ function validBoundedString(value: unknown, maxBytes: number): value is string { * A caller-supplied value is never trimmed, regenerated or silently dropped: * an invalid key is a contract violation, because replaying a keyed command * without its key is exactly the unsafe behaviour the key exists to prevent. + * + * R-7.1. Visible ASCII only: fetch strips surrounding whitespace from header + * values (two keys would collide on the wire) and throws on non-ByteString + * values. Same rule as the realtime `HEADER_SAFE_CURSOR`. */ +const IDEMPOTENCY_KEY = /^[\x21-\x7e]+$/u; + export function isValidIdempotencyKey(value: unknown): value is string { - if ( - !validBoundedString( - value, - MUTATION_INTENT_BOUNDS.idempotencyKeyMaxBytes, - ) - ) { - return false; - } - for (const character of value) { - const codePoint = character.codePointAt(0) ?? 0; - if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) { - return false; - } - } - return true; + return ( + validBoundedString(value, MUTATION_INTENT_BOUNDS.idempotencyKeyMaxBytes) && + IDEMPOTENCY_KEY.test(value) + ); } export function defineIdempotencyKey(value: unknown): string { diff --git a/tests/unit/legacy-and-optional-network-remediation.test.ts b/tests/unit/legacy-and-optional-network-remediation.test.ts index 5c24f2e3..723da17a 100644 --- a/tests/unit/legacy-and-optional-network-remediation.test.ts +++ b/tests/unit/legacy-and-optional-network-remediation.test.ts @@ -115,11 +115,21 @@ describe("OPT-NET-02 shared idempotency key validation", () => { "key\u007fdelete", "key\u009fc1", "a".repeat(257), + // R-7.1. fetch strips surrounding whitespace, so " order-1 " would reach + // the wire as "order-1" and collide with another command's key. + " order-1 ", + "order-1\t", + "key with-space", + // R-7.1. A non-ByteString value makes Headers.set throw a TypeError that + // the client reports as a retryable network failure. + "키-값", + "ключ", + "key nbsp", ]; it("rejects the same values at intent definition and at admission", () => { for (const value of rejected) { - expect(isValidIdempotencyKey(value)).toBe(false); + expect(isValidIdempotencyKey(value), JSON.stringify(value)).toBe(false); expect(() => defineMutationIntent({ intentId: "intent-1", @@ -132,8 +142,13 @@ describe("OPT-NET-02 shared idempotency key validation", () => { } }); - it("accepts the bounded printable and Unicode values both sides allow", () => { - for (const value of ["key-1", "a".repeat(256), "키-값", "ключ"]) { + it("accepts the bounded visible-ASCII values both sides allow", () => { + for (const value of [ + "key-1", + "a".repeat(256), + "0f8fad5b-d9cb-469f-a165-70867728950e", + "!~", + ]) { expect(isValidIdempotencyKey(value)).toBe(true); expect( defineMutationIntent({