@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.31

package/dist/runtime/choice.js

@@ -1,14 +1,74 @@
-import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
-import { assertFreshProviderChoiceIssuedAt, ProviderChoiceTokenError, } from "../choice-token";
-import { ProviderError } from "../errors";
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, randomInt, timingSafeEqual, } from "node:crypto";
+import { assertFreshProviderChoiceIssuedAt, ProviderChoiceTokenError, } from "../choice-token.js";
+import { isProviderError, ProviderError } from "../errors.js";
+import { CHOICE_WORDLIST_SIZE, choiceWordAt, HIGH_CHOICE_WORD_COUNT, isChoiceWord, STANDARD_CHOICE_WORD_COUNT, } from "./choice-wordlist.js";
 export const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV = "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET";
+export const PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV = "APIFUSE__PROVIDER_RUNTIME__CHOICE_WORD_ISSUANCE";
 const PRIMARY_CHOICE_TOKEN_KID = "v1";
 const MANAGED_CHOICE_TOKEN_VERSION = 1;
+const SERVER_STORED_CHOICE_RECORD_VERSION = 1;
+const SERVER_STORED_CHOICE_ISSUE_ATTEMPTS = 5;
+const WORD_CHOICE_NOT_FOUND_MESSAGE = "Provider choice token was not found.";
 export function createProviderChoiceContext(options) {
     const kid = options.kid ?? PRIMARY_CHOICE_TOKEN_KID;
     const resolveMasterSecret = () => resolveChoiceMasterSecret(options);
     function issue(issueOptions) {
         const issuedAtMs = issueOptions.nowMs ?? Date.now();
+        const resolvedStorage = resolveIssueStorage(issueOptions.storage, issueOptions.payload);
+        if (resolvedStorage.mode === "server") {
+            const issuance = resolveChoiceWordIssuance(options.env);
+            const keys = hasRequestedChoiceBinding(issueOptions.bind)
+                ? deriveManagedChoiceKeys({
+                    masterSecret: resolveMasterSecret(),
+                    providerId: options.providerId,
+                    purpose: issueOptions.purpose,
+                    kid,
+                })
+                : undefined;
+            const binding = hasRequestedChoiceBinding(issueOptions.bind)
+                ? createChoiceBinding({
+                    keys: keys,
+                    options: issueOptions.bind,
+                    request: options.request,
+                    credential: options.credential,
+                    required: true,
+                })
+                : undefined;
+            const baseEnvelope = {
+                v: MANAGED_CHOICE_TOKEN_VERSION,
+                provider_id: options.providerId,
+                purpose: issueOptions.purpose,
+                issued_at_ms: issuedAtMs,
+                ttl_ms: issueOptions.ttlMs,
+                binding,
+            };
+            if (issuance === "legacy") {
+                const legacyKeys = keys ??
+                    deriveManagedChoiceKeys({
+                        masterSecret: resolveMasterSecret(),
+                        providerId: options.providerId,
+                        purpose: issueOptions.purpose,
+                        kid,
+                    });
+                return issueLegacyServerStoredChoice({
+                    baseEnvelope,
+                    issueOptions,
+                    storage: resolvedStorage.storage,
+                    contextState: options.state,
+                    kid,
+                    keys: legacyKeys,
+                    issuedAtMs,
+                });
+            }
+            return issueWordServerStoredChoice({
+                baseEnvelope: {
+                    ...baseEnvelope,
+                },
+                issueOptions,
+                storage: resolvedStorage.storage,
+                contextState: options.state,
+            });
+        }
         const keys = deriveManagedChoiceKeys({
             masterSecret: resolveMasterSecret(),
             providerId: options.providerId,
@@ -29,18 +89,6 @@ export function createProviderChoiceContext(options) {
                 required: true,
             }),
         };
-        const resolvedStorage = resolveIssueStorage(issueOptions.storage, issueOptions.payload);
-        if (resolvedStorage.mode === "server") {
-            return issueServerStoredChoice({
-                baseEnvelope,
-                issueOptions,
-                storage: resolvedStorage.storage,
-                contextState: options.state,
-                kid,
-                keys,
-                issuedAtMs,
-            });
-        }
         const envelope = {
             ...baseEnvelope,
             payload: issueOptions.payload,
@@ -53,77 +101,228 @@ export function createProviderChoiceContext(options) {
         });
     }
     function parse(parseOptions) {
-        const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature,] = parseManagedChoiceTokenParts(parseOptions.token);
-        if (actualPrefix !== parseOptions.prefix ||
-            tokenKid !== kid ||
-            !encodedIv ||
-            !encryptedPayload ||
-            !authTag ||
-            !signature) {
-            throw new ProviderChoiceTokenError("invalid_shape", "Provider choice token shape is invalid.");
-        }
-        const keys = deriveManagedChoiceKeys({
-            masterSecret: resolveMasterSecret(),
-            providerId: options.providerId,
-            purpose: parseOptions.purpose,
-            kid: tokenKid,
+        const consumeMode = parseOptions.consume ?? "never";
+        const wordStateKey = parseWordChoiceStateKey({
+            token: parseOptions.token,
+            prefix: parseOptions.prefix,
         });
-        const signedBody = [
-            parseOptions.prefix,
-            tokenKid,
-            encodedIv,
-            encryptedPayload,
-            authTag,
-        ].join(".");
-        assertManagedChoiceSignature({
-            signedBody,
-            signature,
-            signingKey: keys.signing,
-        });
-        const envelope = decryptManagedChoiceToken({
-            encodedIv,
-            encryptedPayload,
-            authTag,
-            encryptionKey: keys.encryption,
-        });
-        assertManagedChoiceEnvelope(envelope, {
-            providerId: options.providerId,
-            purpose: parseOptions.purpose,
-            ttlMs: parseOptions.ttlMs,
-            nowMs: parseOptions.nowMs,
-            futureToleranceMs: parseOptions.futureToleranceMs,
-        });
-        assertChoiceBindingMatches({
-            actual: envelope.binding,
-            expected: createChoiceBinding({
-                keys,
-                options: parseOptions.bind,
+        if (wordStateKey) {
+            const parsed = parseWordServerStoredChoice({
+                stateKey: wordStateKey,
+                parseOptions,
+                contextState: options.state,
+                providerId: options.providerId,
                 request: options.request,
                 credential: options.credential,
-                required: true,
-            }),
-        });
-        if (isServerChoiceHandlePayload(envelope.payload)) {
-            return parseServerStoredChoice({
-                handle: envelope.payload,
-                storage: parseOptions.storage,
-                contextState: options.state,
+                resolveBindingKeys: () => deriveManagedChoiceKeys({
+                    masterSecret: resolveMasterSecret(),
+                    providerId: options.providerId,
+                    purpose: parseOptions.purpose,
+                    kid,
+                }),
+                onConsume: (result) => emitChoiceTelemetry(options.onTelemetry, {
+                    providerId: options.providerId,
+                    purpose: parseOptions.purpose,
+                    operation: "consume",
+                    format: "word",
+                    outcome: "success",
+                    consumeMode,
+                    consumed: result.status === "consumed",
+                    replay: result.status === "already-consumed",
+                }),
+            });
+            return observeChoiceParse(parsed, {
+                onTelemetry: options.onTelemetry,
+                providerId: options.providerId,
+                purpose: parseOptions.purpose,
+                format: "word",
+                consumeMode,
+            });
+        }
+        // Legacy encrypted-envelope compatibility fallback. Removal is gated on
+        // the last legacy mint plus the maximum issued TTL; see ADR 0006.
+        // A structurally valid word token returns above, so lookup, expiry,
+        // consumption, and binding failures can never enter this branch.
+        try {
+            const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature] = parseManagedChoiceTokenParts(parseOptions.token);
+            if (actualPrefix !== parseOptions.prefix ||
+                tokenKid !== kid ||
+                !encodedIv ||
+                !encryptedPayload ||
+                !authTag ||
+                !signature) {
+                throw new ProviderChoiceTokenError("invalid_shape", "Provider choice token shape is invalid.");
+            }
+            const keys = deriveManagedChoiceKeys({
+                masterSecret: resolveMasterSecret(),
+                providerId: options.providerId,
+                purpose: parseOptions.purpose,
+                kid: tokenKid,
+            });
+            const signedBody = [parseOptions.prefix, tokenKid, encodedIv, encryptedPayload, authTag].join(".");
+            assertManagedChoiceSignature({
+                signedBody,
+                signature,
+                signingKey: keys.signing,
+            });
+            const envelope = decryptManagedChoiceToken({
+                encodedIv,
+                encryptedPayload,
+                authTag,
+                encryptionKey: keys.encryption,
+            });
+            assertManagedChoiceEnvelope(envelope, {
+                providerId: options.providerId,
+                purpose: parseOptions.purpose,
+                ttlMs: parseOptions.ttlMs,
+                nowMs: parseOptions.nowMs,
+                futureToleranceMs: parseOptions.futureToleranceMs,
+            });
+            assertChoiceBindingMatches({
+                actual: envelope.binding,
+                expected: createChoiceBinding({
+                    keys,
+                    options: parseOptions.bind,
+                    request: options.request,
+                    credential: options.credential,
+                    required: true,
+                }),
+            });
+            const payload = isServerChoiceHandlePayload(envelope.payload)
+                ? parseLegacyServerStoredChoice({
+                    handle: envelope.payload,
+                    storage: parseOptions.storage,
+                    contextState: options.state,
+                })
+                : envelope.payload;
+            const parsed = consumeMode === "explicit"
+                ? Promise.resolve(payload).then((resolvedPayload) => createLegacyExplicitParseResult({
+                    payload: resolvedPayload,
+                    replayKey: digestChoiceReplayKey(parseOptions.token),
+                    onConsume: () => emitChoiceTelemetry(options.onTelemetry, {
+                        providerId: options.providerId,
+                        purpose: parseOptions.purpose,
+                        operation: "consume",
+                        format: "legacy",
+                        outcome: "unsupported",
+                        consumeMode,
+                        consumed: false,
+                        replay: false,
+                    }),
+                }))
+                : payload;
+            return observeChoiceParse(parsed, {
+                onTelemetry: options.onTelemetry,
+                providerId: options.providerId,
+                purpose: parseOptions.purpose,
+                format: "legacy",
+                consumeMode,
+            });
+        }
+        catch (error) {
+            emitChoiceParseFailure(options.onTelemetry, error, {
+                providerId: options.providerId,
+                purpose: parseOptions.purpose,
+                format: "legacy",
+                consumeMode,
             });
+            throw error;
         }
-        return envelope.payload;
     }
     return { issue, parse };
 }
 export function createTestProviderChoiceContext(options) {
     return createProviderChoiceContext({
         ...options,
-        masterSecret: options.masterSecret ??
-            "apifuse-test-provider-runtime-choice-token-master-secret",
+        masterSecret: options.masterSecret ?? "apifuse-test-provider-runtime-choice-token-master-secret",
+    });
+}
+function observeChoiceParse(result, base) {
+    if (result instanceof Promise) {
+        return result.then((value) => {
+            emitChoiceParseSuccess(base, value);
+            return value;
+        }, (error) => {
+            emitChoiceParseFailure(base.onTelemetry, error, base);
+            throw error;
+        });
+    }
+    emitChoiceParseSuccess(base, result);
+    return result;
+}
+function emitChoiceParseSuccess(base, result) {
+    const replay = isConsumedChoiceReplay(result);
+    emitChoiceTelemetry(base.onTelemetry, {
+        providerId: base.providerId,
+        purpose: base.purpose,
+        operation: "parse",
+        format: base.format,
+        outcome: "success",
+        consumeMode: base.consumeMode,
+        consumed: replay || (base.format === "word" && base.consumeMode === "on-parse"),
+        replay,
+    });
+}
+function isConsumedChoiceReplay(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        "status" in value &&
+        value.status === "consumed" &&
+        "replayKey" in value &&
+        typeof value.replayKey === "string");
+}
+function emitChoiceParseFailure(onTelemetry, error, base) {
+    const outcome = error instanceof ProviderChoiceTokenError
+        ? base.format === "word" && error.message === WORD_CHOICE_NOT_FOUND_MESSAGE
+            ? "not-found"
+            : "invalid"
+        : "error";
+    emitChoiceTelemetry(onTelemetry, {
+        providerId: base.providerId,
+        purpose: base.purpose,
+        operation: "parse",
+        format: base.format,
+        outcome,
+        consumeMode: base.consumeMode,
+        consumed: false,
+        replay: false,
+    });
+}
+function emitChoiceTelemetry(onTelemetry, event) {
+    try {
+        onTelemetry?.(event);
+    }
+    catch {
+        // Observability must never change provider token semantics.
+    }
+}
+function createLegacyExplicitParseResult(options) {
+    return {
+        status: "active",
+        payload: options.payload,
+        replayKey: options.replayKey,
+        consume: async () => {
+            options.onConsume();
+            return { status: "unsupported" };
+        },
+    };
+}
+function resolveChoiceWordIssuance(env) {
+    const configured = env?.get(PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV);
+    const value = configured?.trim() ?? "";
+    if (value === "" || value === "legacy")
+        return "legacy";
+    if (value === "word")
+        return "word";
+    throw new ProviderError(`Unsupported provider choice word issuance mode "${value}". Expected "legacy" or "word".`, {
+        code: "CHOICE_WORD_ISSUANCE_INVALID",
+        category: "input_validation",
+        retryable: false,
+        details: { env: PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV },
     });
 }
 function resolveChoiceMasterSecret(options) {
-    const configured = options.masterSecret ??
-        options.env?.get(PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV);
+    const configured = options.masterSecret ?? options.env?.get(PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV);
     const trimmed = configured?.trim();
     if (trimmed)
         return trimmed;
@@ -165,19 +364,68 @@ function encryptManagedChoiceToken(options) {
     ]).toString("base64url");
     const authTag = cipher.getAuthTag().toString("base64url");
     const encodedIv = iv.toString("base64url");
-    const signedBody = [
-        options.prefix,
-        options.kid,
-        encodedIv,
-        encryptedPayload,
-        authTag,
-    ].join(".");
+    const signedBody = [options.prefix, options.kid, encodedIv, encryptedPayload, authTag].join(".");
     const signature = createHmac("sha256", options.keys.signing)
         .update(signedBody)
         .digest("base64url");
     return `${signedBody}.${signature}`;
 }
-async function issueServerStoredChoice(options) {
+async function issueWordServerStoredChoice(options) {
+    const serializedPayload = serializeChoicePayload(options.issueOptions.payload);
+    const payloadDigest = digestChoicePayload(serializedPayload);
+    const namespace = resolveChoiceStateNamespace({
+        storage: options.storage,
+        contextState: options.contextState,
+        ttlMs: options.issueOptions.ttlMs,
+    });
+    const wordCount = options.issueOptions.strength === "high" ? HIGH_CHOICE_WORD_COUNT : STANDARD_CHOICE_WORD_COUNT;
+    for (let attempt = 0; attempt < SERVER_STORED_CHOICE_ISSUE_ATTEMPTS; attempt += 1) {
+        const stateKey = generateChoiceWordSequence(wordCount);
+        const token = `${options.issueOptions.prefix}${stateKey}`;
+        const record = {
+            v: SERVER_STORED_CHOICE_RECORD_VERSION,
+            storage: "server",
+            status: "active",
+            provider_id: options.baseEnvelope.provider_id,
+            purpose: options.baseEnvelope.purpose,
+            issued_at_ms: options.baseEnvelope.issued_at_ms,
+            ttl_ms: options.baseEnvelope.ttl_ms,
+            binding: options.baseEnvelope.binding,
+            prefix: options.issueOptions.prefix,
+            payload: options.issueOptions.payload,
+            payload_digest: payloadDigest,
+            replay_key: digestChoiceReplayKey(token),
+        };
+        const valueBytes = Buffer.byteLength(JSON.stringify(record), "utf8");
+        if (valueBytes > options.storage.maxValueBytes) {
+            throw new ProviderError("Provider choice payload exceeds state storage policy.", {
+                code: "CHOICE_STATE_PAYLOAD_TOO_LARGE",
+                category: "input_validation",
+                retryable: false,
+                details: {
+                    maxValueBytes: options.storage.maxValueBytes,
+                    valueBytes,
+                },
+            });
+        }
+        const result = await namespace.compareAndSet(optionsStateKey(stateKey), 0, record, {
+            ttl: stateTtl(options.storage, options.issueOptions.ttlMs),
+        });
+        if (result.ok)
+            return token;
+    }
+    throw new ProviderError("Provider choice state storage is not available.", {
+        code: "CHOICE_STATE_UNAVAILABLE",
+        category: "internal_error",
+        retryable: false,
+    });
+}
+/**
+ * Beta.28-compatible server handle issuance. The state stores the payload and
+ * the client receives the existing six-part encrypted envelope whose payload
+ * is a server-state handle.
+ */
+async function issueLegacyServerStoredChoice(options) {
     const serializedPayload = serializeChoicePayload(options.issueOptions.payload);
     const payloadBytes = Buffer.byteLength(serializedPayload, "utf8");
     if (payloadBytes > options.storage.maxValueBytes) {
@@ -185,14 +433,10 @@ async function issueServerStoredChoice(options) {
             code: "CHOICE_STATE_PAYLOAD_TOO_LARGE",
             category: "input_validation",
             retryable: false,
-            details: {
-                maxValueBytes: options.storage.maxValueBytes,
-                payloadBytes,
-            },
+            details: { maxValueBytes: options.storage.maxValueBytes, payloadBytes },
         });
     }
     const stateId = `choice_${randomBytes(16).toString("base64url")}`;
-    const digest = digestChoicePayload(serializedPayload);
     const namespace = resolveChoiceStateNamespace({
         storage: options.storage,
         contextState: options.contextState,
@@ -206,7 +450,7 @@ async function issueServerStoredChoice(options) {
         payload: {
             storage: "server",
             state_id: stateId,
-            payload_digest: digest,
+            payload_digest: digestChoicePayload(serializedPayload),
             created_at_ms: options.issuedAtMs,
         },
     };
@@ -217,13 +461,149 @@ async function issueServerStoredChoice(options) {
         keys: options.keys,
     });
 }
-async function parseServerStoredChoice(options) {
+async function parseWordServerStoredChoice(options) {
+    const storage = resolveParseStorage(options.parseOptions.storage);
+    const namespace = resolveChoiceStateNamespace({
+        storage,
+        contextState: options.contextState,
+        ttlMs: options.parseOptions.ttlMs,
+    });
+    let stored;
+    try {
+        stored = await namespace.get(optionsStateKey(options.stateKey));
+    }
+    catch (error) {
+        if (isProviderError(error))
+            throw error;
+        throw wordChoiceNotFoundError();
+    }
+    if (!stored || !isServerStoredChoiceRecord(stored.value)) {
+        throw wordChoiceNotFoundError();
+    }
+    const record = stored.value;
+    const expectedReplayKey = digestChoiceReplayKey(`${options.parseOptions.prefix}${options.stateKey}`);
+    try {
+        if (record.provider_id !== options.providerId ||
+            record.purpose !== options.parseOptions.purpose ||
+            record.prefix !== options.parseOptions.prefix) {
+            throw wordChoiceNotFoundError();
+        }
+        assertFreshProviderChoiceIssuedAt(record.issued_at_ms, {
+            ttlMs: options.parseOptions.ttlMs != null
+                ? Math.min(options.parseOptions.ttlMs, record.ttl_ms)
+                : record.ttl_ms,
+            nowMs: options.parseOptions.nowMs,
+            futureToleranceMs: options.parseOptions.futureToleranceMs,
+        });
+        assertPayloadDigestMatches({
+            actual: digestChoicePayload(serializeChoicePayload(record.payload)),
+            expected: record.payload_digest,
+        });
+        assertPayloadDigestMatches({ actual: expectedReplayKey, expected: record.replay_key });
+        assertWordChoiceBindingMatches({
+            actual: record.binding,
+            requested: options.parseOptions.bind,
+            request: options.request,
+            credential: options.credential,
+            resolveKeys: options.resolveBindingKeys,
+        });
+    }
+    catch (error) {
+        if (error instanceof ProviderChoiceTokenError ||
+            (isProviderError(error) && error.code === "CHOICE_CONTEXT_REQUIRED")) {
+            throw wordChoiceNotFoundError();
+        }
+        throw error;
+    }
+    const consumeMode = options.parseOptions.consume ?? "never";
+    if (record.status === "consumed") {
+        if (consumeMode === "explicit") {
+            return { status: "consumed", replayKey: record.replay_key };
+        }
+        throw wordChoiceNotFoundError();
+    }
+    if (consumeMode === "never")
+        return record.payload;
+    if (consumeMode === "explicit") {
+        return {
+            status: "active",
+            payload: record.payload,
+            replayKey: record.replay_key,
+            consume: async () => {
+                const result = await consumeWordServerStoredChoice({
+                    stateKey: options.stateKey,
+                    stored,
+                    record,
+                    storage,
+                    contextState: options.contextState,
+                });
+                options.onConsume(result);
+                return result;
+            },
+        };
+    }
+    const consumed = await consumeWordServerStoredChoice({
+        stateKey: options.stateKey,
+        stored,
+        record,
+        storage,
+        contextState: options.contextState,
+    });
+    if (consumed.status !== "consumed")
+        throw wordChoiceNotFoundError();
+    return record.payload;
+}
+async function consumeWordServerStoredChoice(options) {
+    const namespace = resolveChoiceStateNamespace({
+        storage: options.storage,
+        contextState: options.contextState,
+        ttlMs: options.record.ttl_ms,
+    });
+    try {
+        const consumed = await namespace.compareAndSet(optionsStateKey(options.stateKey), options.stored.version, { ...options.record, status: "consumed" }, { ttl: remainingStateTtl(options.stored.expiresAt) });
+        if (consumed.ok)
+            return { status: "consumed" };
+        if (consumed.current &&
+            isServerStoredChoiceRecord(consumed.current.value) &&
+            consumed.current.value.status === "consumed" &&
+            consumed.current.value.replay_key === options.record.replay_key) {
+            return { status: "already-consumed" };
+        }
+        throw wordChoiceNotFoundError();
+    }
+    catch (error) {
+        if (isProviderError(error))
+            throw error;
+        if (error instanceof ProviderChoiceTokenError)
+            throw error;
+        throw wordChoiceNotFoundError();
+    }
+}
+async function parseLegacyServerStoredChoice(options) {
     const storage = resolveParseStorage(options.storage);
     const namespace = resolveChoiceStateNamespace({
         storage,
         contextState: options.contextState,
     });
-    const record = await namespace.get(optionsStateKey(options.handle.state_id));
+    // Reading a server-stored choice back deserializes a persisted value. A
+    // corrupt/undecodable value would otherwise surface as a raw JSON.parse
+    // SyntaxError (or another unexpected throwable) that escapes the choice error
+    // taxonomy, gets masked as internal_error 500, and is treated as retryable by
+    // the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
+    // Convert any non-branded throwable into a branded invalid_payload so it maps
+    // to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
+    // ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
+    // their category/retryable semantics are preserved.
+    let record;
+    try {
+        record = await namespace.get(optionsStateKey(options.handle.state_id));
+    }
+    catch (error) {
+        if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
+            throw error;
+        }
+        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload could not be decoded.");
+    }
     if (!record) {
         throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload is missing.");
     }
@@ -234,6 +614,71 @@ async function parseServerStoredChoice(options) {
     });
     return record.value;
 }
+function generateChoiceWordSequence(wordCount) {
+    return Array.from({ length: wordCount }, () => choiceWordAt(randomInt(CHOICE_WORDLIST_SIZE))).join("-");
+}
+function parseWordChoiceStateKey(options) {
+    if (!options.token.startsWith(options.prefix))
+        return null;
+    const body = options.token.slice(options.prefix.length);
+    // The official list contains one hyphenated entry (`yo-yo`), so structural
+    // recognition uses dictionary-aware segmentation instead of assuming every
+    // hyphen is a word boundary.
+    if (!/^[a-z]+(?:-[a-z]+){3,9}$/.test(body))
+        return null;
+    const segments = body.split("-");
+    if (!canSegmentChoiceWords(segments, 0, STANDARD_CHOICE_WORD_COUNT) &&
+        !canSegmentChoiceWords(segments, 0, HIGH_CHOICE_WORD_COUNT)) {
+        return null;
+    }
+    return body;
+}
+function canSegmentChoiceWords(segments, segmentIndex, wordsRemaining) {
+    if (wordsRemaining === 0)
+        return segmentIndex === segments.length;
+    const segmentsRemaining = segments.length - segmentIndex;
+    if (segmentsRemaining < wordsRemaining)
+        return false;
+    for (let end = segmentIndex + 1; end <= segments.length - (wordsRemaining - 1); end += 1) {
+        const candidate = segments.slice(segmentIndex, end).join("-");
+        if (candidate.length > 10)
+            break;
+        if (isChoiceWord(candidate) && canSegmentChoiceWords(segments, end, wordsRemaining - 1)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isServerStoredChoiceRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    return ("v" in value &&
+        value.v === SERVER_STORED_CHOICE_RECORD_VERSION &&
+        "storage" in value &&
+        value.storage === "server" &&
+        "status" in value &&
+        (value.status === "active" || value.status === "consumed") &&
+        "provider_id" in value &&
+        typeof value.provider_id === "string" &&
+        "purpose" in value &&
+        typeof value.purpose === "string" &&
+        "issued_at_ms" in value &&
+        typeof value.issued_at_ms === "number" &&
+        "ttl_ms" in value &&
+        typeof value.ttl_ms === "number" &&
+        (!("binding" in value) || value.binding === undefined || isChoiceBinding(value.binding)) &&
+        "prefix" in value &&
+        typeof value.prefix === "string" &&
+        "payload" in value &&
+        isChoicePayload(value.payload) &&
+        "payload_digest" in value &&
+        typeof value.payload_digest === "string" &&
+        "replay_key" in value &&
+        typeof value.replay_key === "string");
+}
+function wordChoiceNotFoundError() {
+    return new ProviderChoiceTokenError("invalid_payload", WORD_CHOICE_NOT_FOUND_MESSAGE);
+}
 function resolveIssueStorage(storage, payload) {
     if (!storage || storage.mode === "inline")
         return { mode: "inline" };
@@ -269,6 +714,10 @@ function resolveChoiceStateNamespace(options) {
 function stateTtl(storage, ttlMs) {
     return storage.ttl ?? `${ttlMs ?? 1}ms`;
 }
+function remainingStateTtl(expiresAt) {
+    const remainingMs = Date.parse(expiresAt) - Date.now();
+    return `${Number.isFinite(remainingMs) ? Math.max(1, Math.floor(remainingMs)) : 1}ms`;
+}
 function optionsStateKey(stateId) {
     return stateId;
 }
@@ -278,6 +727,9 @@ function serializeChoicePayload(payload) {
 function digestChoicePayload(serializedPayload) {
     return createHash("sha256").update(serializedPayload).digest("base64url");
 }
+function digestChoiceReplayKey(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
 function isServerChoiceHandlePayload(value) {
     return (value.storage === "server" &&
         typeof value.state_id === "string" &&
@@ -345,9 +797,7 @@ function isManagedChoiceEnvelope(value) {
         typeof value.issued_at_ms === "number" &&
         "ttl_ms" in value &&
         typeof value.ttl_ms === "number" &&
-        (!("binding" in value) ||
-            value.binding === undefined ||
-            isChoiceBinding(value.binding)));
+        (!("binding" in value) || value.binding === undefined || isChoiceBinding(value.binding)));
 }
 function isChoicePayload(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
@@ -355,29 +805,23 @@ function isChoicePayload(value) {
 function isChoiceBinding(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
-    return ((!("connection_hash" in value) ||
-        typeof value.connection_hash === "string") &&
+    return ((!("connection_hash" in value) || typeof value.connection_hash === "string") &&
         (!("credential_hash" in value) || typeof value.credential_hash === "string"));
 }
 function assertManagedChoiceEnvelope(envelope, options) {
-    if (envelope.provider_id !== options.providerId ||
-        envelope.purpose !== options.purpose) {
+    if (envelope.provider_id !== options.providerId || envelope.purpose !== options.purpose) {
         throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token payload is invalid.");
     }
     assertFreshProviderChoiceIssuedAt(envelope.issued_at_ms, {
         // Clamp to the issuer's embedded TTL so a caller-supplied value cannot
         // silently extend token validity past the deadline the issuer intended.
-        ttlMs: options.ttlMs != null
-            ? Math.min(options.ttlMs, envelope.ttl_ms)
-            : envelope.ttl_ms,
+        ttlMs: options.ttlMs != null ? Math.min(options.ttlMs, envelope.ttl_ms) : envelope.ttl_ms,
         nowMs: options.nowMs,
         futureToleranceMs: options.futureToleranceMs,
     });
 }
 function createChoiceBinding(options) {
-    const connectionHash = options.options?.connection
-        ? hashRequiredConnection(options)
-        : undefined;
+    const connectionHash = options.options?.connection ? hashRequiredConnection(options) : undefined;
     const credentialHash = options.options?.credentialKeys?.length
         ? hashCredentialKeys(options)
         : undefined;
@@ -388,6 +832,27 @@ function createChoiceBinding(options) {
         ...(credentialHash ? { credential_hash: credentialHash } : {}),
     };
 }
+function hasRequestedChoiceBinding(options) {
+    return options?.connection === true || Boolean(options?.credentialKeys?.length);
+}
+function assertWordChoiceBindingMatches(options) {
+    const hasStoredBinding = Boolean(options.actual?.connection_hash || options.actual?.credential_hash);
+    const hasRequestedBinding = hasRequestedChoiceBinding(options.requested);
+    if (!hasStoredBinding && !hasRequestedBinding)
+        return;
+    if (hasStoredBinding !== hasRequestedBinding)
+        throw wordChoiceNotFoundError();
+    assertChoiceBindingMatches({
+        actual: options.actual,
+        expected: createChoiceBinding({
+            keys: options.resolveKeys(),
+            options: options.requested,
+            request: options.request,
+            credential: options.credential,
+            required: true,
+        }),
+    });
+}
 function hashRequiredConnection(options) {
     const connectionId = options.request?.connectionId;
     if (!connectionId) {