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>
88 lines
2.7 KiB
TypeScript
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,
|
|
});
|
|
}
|