fix(contracts): restrict idempotency keys to visible ASCII (R-7.1)

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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 12:19:48 +09:00
co-authored by Claude Opus 5.5
parent df9b15c039
commit 4f7a3be50d
2 changed files with 28 additions and 18 deletions
+10 -15
View File
@@ -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 {
@@ -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({