Files
clean-architecture-frontend…/src/contracts/mutation-intent.ts
T
DongHyeonkaandClaude Opus 5.5 4f7a3be50d 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>
2026-09-24 12:19:48 +09:00

88 lines
2.7 KiB
TypeScript

export const MUTATION_INTENT_BOUNDS = Object.freeze({
intentIdMaxBytes: 256,
operationIdMaxBytes: 256,
canonicalInputIdentityMaxBytes: 16_384,
idempotencyKeyMaxBytes: 256,
} as const);
export type MutationIntent = Readonly<{
intentId: string;
operationId: string;
canonicalInputIdentity: string;
idempotencyKey?: string;
createdAtMonotonicMs: number;
}>;
const UTF8 = new TextEncoder();
function validBoundedString(value: unknown, maxBytes: number): value is string {
return (
typeof value === "string" &&
value.trim().length > 0 &&
UTF8.encode(value).byteLength <= maxBytes
);
}
/**
* N-06. The single idempotency-key authority shared by the V2 compatibility
* client and the V3 executor.
*
* 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 {
return (
validBoundedString(value, MUTATION_INTENT_BOUNDS.idempotencyKeyMaxBytes) &&
IDEMPOTENCY_KEY.test(value)
);
}
export function defineIdempotencyKey(value: unknown): string {
if (!isValidIdempotencyKey(value)) {
throw new TypeError("Idempotency key is invalid.");
}
return value;
}
export function defineMutationIntent(intent: MutationIntent): MutationIntent {
if (
!validBoundedString(
intent.intentId,
MUTATION_INTENT_BOUNDS.intentIdMaxBytes,
) ||
!validBoundedString(
intent.operationId,
MUTATION_INTENT_BOUNDS.operationIdMaxBytes,
) ||
!validBoundedString(
intent.canonicalInputIdentity,
MUTATION_INTENT_BOUNDS.canonicalInputIdentityMaxBytes,
) ||
// OPT-NET-02. Intent definition and executor admission share one key
// authority; a second, looser rule here is how a control character reaches
// an `Idempotency-Key` header.
(intent.idempotencyKey !== undefined &&
!isValidIdempotencyKey(intent.idempotencyKey)) ||
!Number.isFinite(intent.createdAtMonotonicMs) ||
intent.createdAtMonotonicMs < 0
) {
throw new TypeError("Mutation intent is invalid.");
}
return Object.freeze({
intentId: intent.intentId,
operationId: intent.operationId,
canonicalInputIdentity: intent.canonicalInputIdentity,
...(intent.idempotencyKey === undefined
? {}
: { idempotencyKey: intent.idempotencyKey }),
createdAtMonotonicMs: intent.createdAtMonotonicMs,
});
}